refactor(tooling): T-1293 — atlas map, and the generator that must not run
The star-map family was the last unported part of the tree, and it never had a ticket. Two of its scripts become `reach atlas map` verbs, nested under atlas like planet (D-243: the Reach map is the ladder's top rung): - `reach atlas map data [--check]` regenerates client/data/star_map_data.json. The regenerated file differs by one line: `_meta.note`, which named the old script's path. - `reach atlas map svg` renders the concentric SVG (+ PNG), byte-identical to the old script's output on the same data. make check-star-map and star-map-data stay as one-line delegates, because pre-pr-client and pre-pr-validate depend on check-star-map. generate-star-map.py, its seed, sculpt-star-map.py and tune-star-map-topology.py are archived, not ported. The generator rewrites docs/design/star-map.json unconditionally from an S-NNN-keyed seed, so re-running it would erase the GJ migration and every hand edit since; sculpt and tune only understand S-NNN edges. .claude/rules/diagrams.md was telling agents to "edit the generator and re-run it". It now distinguishes the live concentric render, the seven frozen S-keyed sector .d2 files (T-1294), and the two SVGs that never had a generator in the repo. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -25,14 +25,25 @@ Scratch renders go in `.cache/` — never in `docs/diagrams/`, never in `/tmp`.
|
||||
|
||||
## Some `.d2` files are generator output — do not hand-edit
|
||||
|
||||
`docs/diagrams/design/star-map-*.d2` (×7: `overview`, `core`,
|
||||
`north`/`south`/`east`/`west-reach`, `deep-frontier`) are written by
|
||||
`tooling/generate-star-map.py` alongside `docs/design/star-map.json`. The
|
||||
`concentric`/`realcoords`/`topology` SVGs come from a second script,
|
||||
`tooling/generate-star-map-svg.py`, and never pass through d2 at all.
|
||||
The star-map family is three different cases, and the difference matters
|
||||
(T-1293):
|
||||
|
||||
Edit the generator and re-run it; a hand-edit is lost on the next run. Same
|
||||
source-canonical rule as `.claude/rules/asset-pipeline.md`.
|
||||
- **`star-map-concentric.svg` (+ its `.png`) is a live render.** Regenerate it
|
||||
with `reach atlas map svg`; it reads the committed `docs/design/star-map.json`
|
||||
and `systems.db` and never passes through d2. Edit the renderer, not the SVG.
|
||||
- **`star-map-*.d2` (×7: `overview`, `core`, the four reaches, `deep-frontier`)
|
||||
are FROZEN output — do not regenerate them.** Their generator is archived in
|
||||
`tooling/archive/map-bootstrap/` because it rewrites
|
||||
`docs/design/star-map.json` from an `S-NNN`-keyed seed, which would destroy the
|
||||
GJ-keyed, hand-maintained map. The d2 files still carry `S-` ids from before
|
||||
the GJ migration. Replacing them means a new renderer that reads
|
||||
`star-map.json` — see T-1294.
|
||||
- **`star-map-realcoords.svg` and `star-map-topology.svg` have no generator in
|
||||
the repo** — committed once (2026-03-16) as static artefacts.
|
||||
|
||||
Same source-canonical principle as `.claude/rules/asset-pipeline.md`, with one
|
||||
trap: here the "source" the old generator would rebuild from is no longer the
|
||||
source.
|
||||
|
||||
## A diagram that names files goes stale silently
|
||||
|
||||
|
||||
Reference in New Issue
Block a user