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:
2026-09-23 20:00:05 +02:00
co-authored by Claude Opus 5.5
parent 26cc8de7f3
commit 59b3fc4caa
18 changed files with 548 additions and 437 deletions
+18 -7
View File
@@ -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