jpmschweitzer/settled-reach
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(governance): D-263 — domains mirror the implant apps, and atlas is one ladder

Browse Source 
reach's domain names should not be a fresh taxonomy. Where the game already
presents something to the player, the CLI takes that name and that shape: what
you browse in-game is what you generate and inspect from the terminal.

That splits domains in two. atlas, ledger and wiki mirror implant apps and
follow their structure. check, validate, godot, visual, jobs and dev mirror
nothing — no app exists for a lint gate, and inventing a player-facing framing
for one would be worse than having none.

The first consequence corrects a contradiction rather than a preference. D-191
already says "Atlas is the star map extended downward, not a separate app —
implant/map at different zoom levels", four rungs from Reach map to regional.
The domain map had atlas, starmap and planet as peers, which would have
presented as three unrelated things what the game presents as one descent.
Generation now nests by rung; authoring and inspection verbs stay flat on
atlas, because they act on the whole thing rather than a rung.

The second is a rename with the same reasoning: db becomes ledger, after the UI
component that will aggregate economics — markets, wealth, transactions, the
economic counterpart to what the Atlas offers for topography. db named a
storage layer nobody looks at.

One caution recorded because the words collide. D-191's MVP criterion 7 says
"Atlas is read-only (no verbs execute from map)". That governs the app. The
atlas tooling writes — it commits proposals, mutates fields, syncs the wiki —
and a later reader must not take the app's constraint as licence to delete the
authoring verbs.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
jpmschweitzer
2026-09-02 14:15:03 +02:00
co-authored by Claude Opus 5
parent a384ec0c7c
commit 6daaa2235f
4 changed files with 37 additions and 4 deletions
Download Patch File Download Diff File Expand all files Collapse all files
governance/decisions/architecture.md
+8
View File
@@ -2619,6 +2619,14 @@ tooling/
- **Failures that name the fix are the highest-value requirement in this record.** The reader of an error message is usually an agent deciding what to run next. A message that says only "no" costs a whole exploratory turn; one that names the command costs none.
- **Machine-readable output is the default path, not the exception.** stderr is a pipe far more often than a terminal, so JSONL-when-not-a-TTY matches reality rather than accommodating an edge case.
**Player-facing domains mirror the implant apps; tooling domains mirror nothing** *(settled 2026-09-02)*. `reach`'s domain names are not a fresh taxonomy — where the game already presents something to the player, the CLI uses **that** name and **that** shape. What you browse in-game is what you generate and inspect from the terminal.
- **The two kinds.** `atlas`, `ledger` and `wiki` mirror implant apps and follow their structure. `check`, `validate`, `godot`, `visual`, `jobs`, `dev` mirror nothing — no app exists, none is expected, and inventing a player-facing framing for a lint gate would be worse than having none.
- **`atlas` is one ladder, not three domains.** D-191 states it: *"Atlas is the star map extended downward, not a separate app — `implant/map` at different zoom levels"*, four rungs Reach map → system → planetary → regional. An earlier domain map (T-1271) had `atlas`, `starmap` and `planet` as peers, which contradicted that record and would have presented as three unrelated things what the game presents as one descent. **Generation nests by rung** — `reach atlas map …`, `reach atlas planet …` — so `reach atlas --help` shows the ladder rather than thirty flat verbs. Authoring and inspection verbs stay flat on `atlas`, because they act on the whole thing rather than on a rung.
- **`ledger` aggregates economics**, and is the name because it is the UI component the player will use — markets, wealth, transactions — the economic counterpart to what the Atlas offers for topography. Not `db`, which named a storage layer nobody looks at, and not `economics`, which names a subject rather than the thing on screen.
- **Where the mirror does not apply, do not force it.** The distinction that matters is player-facing versus tooling. A domain in the first group inherits its name and its shape; one in the second is free to be organised however the work is organised.
- **One caution, since the words collide.** D-191's MVP criterion 7 says *"Atlas is read-only (no verbs execute from map)"*. That governs the **app**. The atlas *tooling* writes — it commits proposals, mutates fields, syncs the wiki — and a later reader must not take the app's constraint as licence to delete the authoring verbs.
**The bash scripts are rewritten in Python, not wrapped** *(settled 2026-08-31, after a survey found the tree is half shell)*. **17 of the 33 tooling executables are bash, ~900 lines** — the record and the domain map had both assumed a Python tree, so porting them is a rewrite rather than a move. They are rewritten anyway.
- **Why not wrap them.** Wrapping achieves one door while leaving half the surface outside the contract: no `@command`, no remedy on failure, no streaming, no testable service. `reach --help` would then list verbs that behave differently from the ones beside them, which is worse than two doors because the inconsistency is invisible until a failure.