@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

package/ROADMAP.md

@@ -1,6 +1,6 @@
 # Roadmap
 
-_Assessed 2026-08-28._
+_Assessed 2026-09-03._
 
 This is loam's canonical improvement sequence. It records priorities and exit criteria, not delivery
 dates. An item is complete only when its exit criteria are supported by repeatable evidence; moving
@@ -18,26 +18,30 @@ acceptance tests, and implementation evidence remain ordinary files in repositor
 state inside a service. The CLI is small enough to audit, and every writer — not only archive — now
 commits through a locked, journaled transaction that a crash cannot leave half-applied.
 
-The tree contains **419 TypeScript modules in 128 source packages**, with an acyclic package graph
+The tree contains **531 TypeScript modules in 166 source packages**, with an acyclic package graph
 checked by
 [scripts/package-graph.mjs](https://github.com/ybotok/loam/blob/main/scripts/package-graph.mjs). The
-CLI exposes **29 commands** from [src/cli.ts](https://github.com/ybotok/loam/blob/main/src/cli.ts),
-and the suite stands at **156 test files**. Those four counts are deliberately stated OUTSIDE the
+CLI exposes **30 commands** from [src/cli.ts](https://github.com/ybotok/loam/blob/main/src/cli.ts),
+and the suite stands at **205 test files**. Those four counts are deliberately stated OUTSIDE the
 dated snapshot below: each derives from the tree in one readdir, so
 [test/docs-facts.test.ts](https://github.com/ybotok/loam/blob/main/test/docs-facts.test.ts) grades
 them live and this paragraph cannot quietly trail the code the way its predecessor did.
 
-_Measured 2026-08-31 on `ab4c856` plus the changes on top of it, and dated because neither number
-has a cheap derivation:_ lint, typecheck, `npm run arch:check` and `npm run meta:check` green;
-`npm test` passing **3,358/3,358 tests**, with two `skipIf(asRoot)` cases the root gate container
-cannot run; and the coverage gate passing with **92.20% statements, 83.97% branches, 96.75%
-functions, and 94.13% lines** against its thresholds of 91 / 82 / 95 / 93.
-
-One qualification remains, and it is observation rather than code: nothing has been pushed since the
-CI `stability` job and the tarball-reading package smoke landed, so repeatable CI executions — the
-stability job seen green, and the installed-package smoke run from a pushed commit — are still
-release evidence to collect, even though the gate-stress proof passed locally on its landing tree
-and the smoke passes locally against the real tarball. The runner class recorded on 2026-08-18 is
+_Measured 2026-09-07 at `0.2.0-alpha.7`, and dated because neither number has a cheap derivation:_
+lint, typecheck, `npm run arch:check` and `npm run meta:check` green; `npm test` passing
+**3,802/3,802 tests**, with two `skipIf(asRoot)` cases the root gate container cannot run; the
+coverage gate passing with **92.88% statements, 84.83% branches, 97.14% functions, and 94.70%
+lines** against its thresholds of 91 / 82 / 95 / 93; and `npm run release:check` plus
+`npm run test:package` green against the real tarball.
+
+Most of that qualification is now closed by observation rather than by code. Measured 2026-09-03 on
+pushed commits: `ci` at `1de7c97` green — `test` on Node 22.22.3 and 24, and the installed-package
+`package` job on ubuntu (both Node lines) and windows — and the `release` workflow on tag
+`v0.2.0-alpha.4` green end to end, `release-gate` (lint, typecheck, coverage, the packed candidate,
+the smoke of that exact candidate, `release:check`) followed by `publish`, which put the tarball on
+npm under the `alpha` dist-tag. What is left is one job: `stability` is SKIPPED on a push — it runs
+on the weekly schedule and on dispatch — so it is still release evidence to collect, even though the
+gate-stress proof passes locally. The runner class recorded on 2026-08-18 is
 still the reading to apply to a red of that shape: a restricted filesystem sandbox that denies `tsx`
 its local IPC socket fails only the
 [test/cli-entry.test.ts](https://github.com/ybotok/loam/blob/main/test/cli-entry.test.ts) cases with
@@ -98,14 +102,19 @@ The strongest foundations to preserve are:
 ## Now
 
 Nothing is queued behind code. Every integrity, enforcement and lifecycle item that preceded this
-has landed (see [Recently landed](#recently-landed)) — the authored business axis and, with the three
-entries at the top of that section, the use-case axis too. The axis is now writable through the
-change lifecycle, and the gate and the report agree about what it contains.
+has landed (see [Recently landed](#recently-landed)) — the authored business axis, the use-case
+axis, and as of 2026-09-02 the deployment axis, which is the first item this file ever wrote
+directly into this section rather than promoting from [Later](#later--promote-only-from-evidence).
+
+### Release evidence — one job left
 
 What is left is the one thing this file cannot close by writing code, and it stays where it is
-rather than being promoted here for the shape of it: the CI `stability` job and the installed-package
-smoke have still to be OBSERVED green from a pushed commit. That is release evidence to collect, not
-an improvement to make.
+rather than being promoted for the shape of it. The installed-package half closed on 2026-09-03:
+the `package` job ran green on a pushed commit across three runner/Node combinations, and the whole
+publication path ran green on tag `v0.2.0-alpha.4`. The CI `stability` job has still to be OBSERVED
+green — it is skipped on a push and runs on the weekly schedule — so it is still release evidence to
+collect, not an improvement to make. `workflow_dispatch` is the way to collect it deliberately
+rather than waiting for Monday.
 
 An item returns to this section from [Later](#later--promote-only-from-evidence) when fleet evidence
 names its operator, repeated task, failure mode, frequency, current workaround and measurable
@@ -118,9 +127,452 @@ exactly the invented need the non-goals forbid.
 Closed since the 2026-08-18 assessment, each with the commit or commit range that landed it on
 `main`. [CHANGELOG.md](CHANGELOG.md) is the user-facing record; the full item texts — required
 changes, exit criteria, and what each review surfaced — are in this file's history (`git show
-5cd3942:ROADMAP.md`). The three use-case entries below carry no range yet: they are green in the
-working tree and not committed, and the range goes in with the commit rather than being guessed at
-here.
+5cd3942:ROADMAP.md`). The four 2026-09-03 problem-report entries that follow — the extending model
+and the report ordinal, the pair opening the 2026-09-04 group — landed together in `f751909`, one
+change built as four disjoint workstreams and gated as one; the three before them — the edgeless
+brief, the intra-service use case, and the styling paragraph under the generated views — landed
+together in `0eaa101` the same way.
+
+#### The work packet — the verify checklist read forwards
+
+**Landed 2026-09-21.** loam could already say what a feature PROMISES (`loam verify`'s checklist)
+and what to BUILD (`loam delta`), and nothing joined the two into the question an agent actually
+opens a session with: which promise is still open, at which step, and what fact closes it. The
+artifact a team reaches for to answer it is a `tasks.md` — the one document this project refuses,
+because a task list authored beside a spec is a second mutable state that drifts the moment the
+spec moves. That refusal (SCHEMA's "Deliberate limits of the workflow surface") is unchanged; what
+this item settles is that the question was never the problem, only the file.
+
+**What landed.** A read-only `loam tasks <FEAT> [--service <id>] [--next] [--json]`, and a
+`loam_tasks` MCP tool beside it, projecting one work unit per verify-checklist claim under the
+claim's own id — so the thing to do and the answer that closes it are one identity — plus a unit
+of kind requirement.described for an ADDED or MODIFIED requirement with no scenario at all. Each
+unit reports the step it waits on in `at` (`describe`, `generate`, `implement`, `attested`), and a
+unit is retired by exactly one fact: a claim recorded `confirmed` in a `verification.yaml` that is
+not stale against the current checklist. An agent-attested scenario deliberately stays on the list
+at `attested`. `frontier` is the first ten open units, providers before consumers on the exact token
+join and never on prose, and the order is advice rather than a lock; `--next` is the single leaf
+packet — scenario verbatim, digest, the check that closes it, the follow-up command — that an
+orchestrator hands one coding agent. Nothing is written to disk on any path, and no stable code was
+minted: every fact in the payload is a projection of state other commands already grade. CHANGELOG
+has every flag and payload key; SCHEMA's "The same checklist read forwards" has the unit model and
+the done rule.
+
+**Deliberately NOT built, each with its reason.** None of these is a gap nobody noticed.
+
+- **`--results` refinement against a live red/green run** — it needs the report readers re-exposed
+  read-only, which is a seam rather than a flag.
+- **A status rung for tasks in `loam status`'s `next[]`** — that is a new stable `next.*` code, and
+  minting one is a separate decision on a frozen surface.
+- **Removal-direction units** — a retirement's consumers are answered in prose by the consumer
+  scans today, and a unit would be a second account of the same walk.
+- **Obligation-coverage units** — `covers()` never checks that a scenario exists, so a unit derived
+  from an obligation would assert work nothing grades.
+- **A `size.phrasesOwed` figure from `loam steps`** — the step inventory is a report about a
+  service's whole suite, not about one feature's units, and joining them would put a fleet-wide
+  number inside a per-feature packet.
+- **A Jira (or any tracker) export protocol** — that is an agent workflow over `--json` and stays
+  one: an HTTP call from loam is the network dependency the product does not have.
+
+**Exit criteria**, each answerable by one run rather than by a reading: a unit leaves the list only
+when a confirmed claim in a non-stale record retires it, and an attested scenario is still on the
+list at `attested`; the frontier's provider-before-consumer order comes from the exact operation
+token join and from nowhere else; and a run writes no byte and mints no code, so the projection
+cannot be behind the documents it projected.
+
+#### One model, many documents — a service model may extend the fleet map
+
+**Landed 2026-09-04** in `f751909`, from three problem reports that turned out to be one cause,
+with a fourth landing beside it in the same change. #010 measured the cause: a service model must
+parse alone, so it re-declares its own `specification` and every partner it names — 78 double
+declarations in a 56-service fleet with four services adopted, projected to ~448 at full adoption —
+and the copies had already diverged, `#platform` missing from every copy of the broker and the
+identity provider but the map's, with no finding code for "two documents describe one element
+differently" because no check read two documents together. #009 measured the symptom: 57 flat
+entries in the renderer's project picker, 52 of them a single box, forced by the per-service
+project file `0.2.0-alpha.5` had to write **because** the models could not share a project. #011 is
+the structural proposal, every claim of it executed against copies of `examples/docs`: `extend`
+resolves across documents of one project, a model rewritten that way makes its containers visible
+in the fleet project with one copy of the broker in the whole model, and deleting a model's
+`specification` under the old loader is eleven `c4.invalid` errors — so the change had to be
+loam's, not a convention a repository could adopt. (#012, reports having no ordinal and loam never
+reading `loam-reports/`, landed in the same commit and has its own entry below.)
+
+**What landed.** The shape of a model is now read from the file's own grammar — a top-level
+`specification { }` block containing an `element` declaration means STANDALONE, its absence means
+EXTENDING — and each shape gets the grade the other cannot need: `c4.declaration-diverged` for a
+standalone model whose copies of the map's elements disagree with it, `c4.element-unowned` for an
+extending model that declares an element outside its own. Around them, the renderer wiring
+`loam subsystem sync` now owns end to end (`service.likec4-config-stray`, `service.model-excluded`,
+`service.model-unexcluded`, the narrowed `service.likec4-config-missing`, and the root project's
+`exclude` rewritten to cover exactly the models that stand alone), and `c4.fleet-project-invalid`,
+which loads the fleet project the way the renderer builds it and reports what only that load can
+see. `examples/docs` is migrated whole, and its ten deliberate warnings are unchanged. CHANGELOG
+has every code, key and message; SCHEMA's new "Two shapes of a service model" has the rules and the
+migration recipe.
+
+**Rejected, each with the reason.** Migrating repositories automatically — the recipe is documented
+and an agent performs it, because a real model's comments are the team's and not loam's to reflow.
+Making the shape a key in `loam.json` or `likec4.config.json` — the file's grammar already decides
+how it can be read, and a key would be a second answer able to disagree with the first. Widening
+loam's fleet map to the renderer's root project — the map is graded as `architecture/` alone so
+that one broken service model cannot blank the fleet's own picture, which is why a cross-service
+flow in `architecture/usecases/` still names service elements and never a container. Retiring the
+standalone shape — it is what lets a service's docs be validated from the service's own repository,
+and a fleet that wants that keeps it, now with a check on the divergence it costs.
+
+**The deliberate remainder**, stated so nobody reads it as an oversight. A cross-service call still
+exists TWICE: container-level in the model, service-level in the map (#011's item 6). The spine,
+the platform census and every other fleet check read the map alone, and `landscape.service-isolated`
+remains the nudge that carries an attested call up into it. Thinning the map to elements plus
+cross-service edges is the [Later](#later--promote-only-from-evidence) "Landscape scaling" row, and
+it is what would remove the duplication. Beside it sits #011's item 5, also deliberate: a
+cross-service flow cannot name a container, because loam grades the fleet map as its own document
+set. Revisit that one when a fleet asks for a cross-service flow whose hops are containers — the
+renderer already resolves such a hop, so the ask will be concrete when it arrives.
+
+**Verified 2026-09-04**, and three things the verification changed. The report's own "next thing to
+check" was the one that did not compose: `loam archive` spliced a delta's nested additions into the
+fleet map, and the extending model could then never declare them — the service went `c4.invalid`
+(duplicate) the moment it wrote the container the adopt brief prescribed. The merge now ROUTES each
+addition to the document that owns the interior, and proves the merged model parses beside the
+merged map before writing either. Second, the consumer census read `architecture/` alone, so under
+this shape a private store's consuming edges — which live in the models now — counted for nothing:
+`landscape.datastore-private` went silent or named the wrong service, and a nested store two
+services reach was graded nowhere. It reads every extending model's attested calls now, and
+`landscape.datastore-shared` fires for a nested store. (That census still stands; the code named
+here does not — `landscape.datastore-private` was retired on 2026-09-07, because where a store is
+drawn is the team's choice. See the CHANGELOG entry.) Third, the wiring guard this entry landed
+failed open on every root `exclude` spelling except `services/<tree>/**`, `loam subsystem sync`
+never removed the stray per-service project file it told repositories to delete (and that file
+CLAIMS the model, rather than holding nothing as the design note said), and
+`c4.fleet-project-invalid` enumerated three roots rather than the renderer's — a `.likec4` in a
+subsystem directory was in none of them. All three are closed; CHANGELOG's `[Unreleased]` has the
+codes and keys.
+
+**The `import` question is answered.** Reports #010 and #011 left open whether LikeC4's
+cross-project `import` could have delivered this without merging the projects. Measured at the
+1.59.2 pin: an import resolves REFERENCES across projects, and that is all — it carries no
+`specification`, so a kind or tag the other project declares is not usable in this one, and it does
+not support `extend`. A model importing the map could name the map's elements and still not add a
+container to one. So the choice was never between two mechanisms; one project holding both
+documents is what the shape requires.
+
+**Known and carried, 2026-09-04.** The second verification round reproduced these and they were
+NOT fixed. Each is written down with the repro that finds it again, so nobody spends a second
+afternoon rediscovering one. They are carried, not closed.
+
+- **Only the basename `likec4.config.json` is surveyed.** LikeC4 1.59.2 also accepts `.likec4rc` and
+  six other spellings; drop `{"name":"svc-a"}` into `services/svc-a/.likec4rc` on a synced extending
+  fleet and `validate --all`, `doctor` and `subsystem sync` all stay green while the renderer loads
+  three projects and refuses without `--project`. Carried on scope: the survey, the stray grade and
+  `sync`'s delete list are one table, and widening it is the same change as the two rows below —
+  worth doing once, together, with the pin's whole name list measured rather than guessed.
+- **A `likec4.config.json` in a SUBSYSTEM directory claims every model beneath it.** Write one at
+  `services/platform/likec4.config.json` over three extending models and all three go
+  `Could not resolve reference to Element named 'svc_svc_d'` in the renderer, while loam names
+  nothing (`sync` → "nothing to write"). Carried on scope, with the row above: the checks look one
+  directory deep, at a service, and seeing this needs a walk of the whole docs tree.
+- **`sync` keeps a config beside a model that is GONE, and that leftover project is not harmless.**
+  `rm services/svc-c/model.likec4` with its config left behind: loam is green everywhere, and
+  `likec4 validate` — and `likec4 build` — at the docs root then need `--project`. The keep is
+  deliberate ("that one really is the team's"), but its premise, that an empty nested project is
+  invisible to the renderer, is false at the pin. Carried on a design decision pending: deleting a
+  file loam never wrote needs a rule about whose file it is, not a bug fix.
+- **`validate --feature` does not preview a merge refusal.** A delta drawing a cross-interior edge,
+  or naming a kind the map does not declare, validates clean and then refuses at `archive`
+  (`merge-failed`, nothing written). Carried on scope: the preview needs the archive's own merge
+  planner run from the validate path, which is a new seam rather than a message.
+- **In the STANDALONE shape a broken UNTAGGED sibling is invisible to loam.** Make one service
+  standalone, `subsystem sync`, then write an unresolvable `services/<id>/usecases/plain.likec4`:
+  loam prints `c4.valid` and 0 errors while `likec4 validate --project <id> .` is Invalid. The
+  extending shape catches the same file through `c4.fleet-project-invalid`. Carried on scope: the
+  per-service load reads the model, and reading the standalone project the renderer builds is a
+  second loader.
+- **A root `exclude` that no longer covers `features/**` is silent.** Delete that one entry from
+  `examples/docs`' config: loam reports 0 errors and `sync` says "nothing to write", while the
+  renderer's fleet project is at 346 errors. The scaffold always writes the entry, so this is a
+  hand edit, which is why it is carried rather than fixed — on the evidence bar: no repository has
+  hit it, and a grade on an entry loam did not write is a policy claim.
+- **A root config the renderer REJECTS is reported only by `sync`'s note.** `"exclude": "services/**"`
+  as a string, or an array-valued `include`, is "loaded 0 projects out of 1" — nothing renders — and
+  `validate --all` is green; an unparseable file is the same. Carried on scope: loam reads the file
+  for one key, and schema-validating somebody else's config is a dependency on the renderer's own
+  schema at the pin.
+- **`LivingSlice.landscape.modelled` is `false` where `adopt` says `null`.** Over an
+  `architecture/` project that did not parse, `loam context <svc> --json` says `modelled: false` and
+  `loam adopt --service <svc> --json` says `modelled: null` about the same tree. Carried on scope:
+  the field is typed non-nullable in the pack, so agreeing with `adopt` is a contract change.
+- **`loam show` never mentions graded intra-service flows.** With a healthy `#req-…`-tagged flow
+  beside an extending model — `validate --service` prints "· 1 tagged flow(s) graded" — neither
+  `loam show <svc>` nor its `--json` names it anywhere. Carried on scope: `show`'s payload is a
+  frozen shape and the flow needs a section of its own.
+- **`loam status` never names the isolated state.** `landscape.service-isolated` is a warning
+  `validate --all` prints and `status`'s next-action ladder has no rung for. Carried on a design
+  decision pending: the ladder is derived from artifact presence and provenance, and a finding-derived
+  rung is a different rule for what `next[0]` means.
+- **The first ever container-level flow a FEATURE brings.** A cross-service flow cannot name a
+  container, because loam grades the fleet map as its own document set; the renderer already resolves
+  such a hop. Carried deliberately — the [Later](#later--promote-only-from-evidence) "Landscape
+  scaling" row owns it, and it is promoted when a fleet asks, not before.
+
+#### Problem reports carry an ordinal, and loam reads the directory it prescribes
+
+**Landed 2026-09-04**, from one problem report (#012). The `loam-report` protocol prescribed a
+directory, a filename shape and a document structure and then stopped: files were named
+`YYYY-MM-DD-<slug>.md` with a numeric suffix only on collision — a collision breaker, not an
+identifier — so in a directory of eleven reports written in two days, none had one, four shared
+their first eleven characters, and the discriminating part of every name sat far to the right of
+what a terminal, a file picker or a chat message shows. There was no field anywhere in the document
+for the one piece of state a report has (three of the eleven were already closed and one superseded,
+all of it living in whoever remembered), and `validate --all`, `doctor`, `status` and `list`
+mentioned `loam-reports` zero times between them. Landed: an unconditional ordinal at the front of
+the name, which is the computation the protocol already described for its suffix applied where it is
+visible; a `Status:` line in the template with a four-value vocabulary a report closes by editing;
+and `loam doctor` reading the directory — total, per-status counts and the next ordinal — as an
+additive `reports` key and one human row. Rejected: a `loam report list` verb (a new command for a
+count `doctor` was already the place for, on a frozen CLI surface); an index file (the workaround
+this replaces — a second place to keep in step, and the reason the state left the files in the first
+place); grading the corpus (an open report is not a defect in the repository holding it, so `doctor`
+reports it as state and `healthy` never moves); parsing past the first word of the status line (the
+rest is prose an author writes for a reader). Cost: one `readdir` and one small read per report on
+every `loam doctor`, and nothing is transmitted — which is the constraint the protocol is built
+around and the reason the whole fix needed no new state.
+
+#### The adopt brief on an edgeless landscape element
+
+**Landed 2026-09-03**, from one problem report. `loam adopt` decided whether the fleet map still
+owed a service from element EXISTENCE: a bound element with no edge — what
+`loam seed --from fleet.yaml` leaves for every service absent from `calls:` — read as
+`landscape.instruction: null`, no target, `inbound: []`, `outbound: []` in one payload, so an agent
+following the protocol to the letter wrote a validating baseline and never drew one edge, and
+`loam validate --all` stayed green over it. Landed: a fourth landscape state carried by two
+additive keys (`landscape.touched`, and `landscape.attested` — the calls the service's own
+model.likec4 declares across its boundary, derived once in `core/c4/resolve/attested.ts` for the
+brief and the fleet check alike, so the two can never name different edges); a non-null instruction
+in two arms (carry each attested call up as one edge on the existing element, naming the other
+party as the map spells it; or, with nothing attested, draw NOTHING rather than invent — an edgeless
+element that is true is a fact); the landscape target back as an edge-only `edit` whose shape
+refuses a second element; the `EDGELESS` flag in the text view; the evidence-gated
+`landscape.service-isolated` warning under `--all`; and a seventeenth unchecked statement about
+visibility (placeholder tags, curated views, `include *` over a boundary). Rejected: folding the
+state into `landscape.modelled` (an agent told `false` draws a second box); an unconditional "no
+edge touches it" warning (no correct fix for a worker that calls nothing, and every seeded fleet
+red-ish until adoption); grading the SET DIFFERENCE between the attested calls and the drawn edges
+(loam cannot tell a call the map forgot from one the fleet does not draw at its own altitude, so
+the difference reported as an omission is an invented edge with a code beside it — the check stays
+touched/untouched, and the brief says so out loud); a check on placeholder tags or on what a view
+shows (rule 26 — loam never
+computes what a view shows). Cost: one LikeC4 load of `model.likec4`, only in the edgeless state, a
+memo hit under `--all`.
+
+**Corrected 2026-09-04** by the verification of this entry: the brief read
+`architecture/landscape.likec4` alone where the fleet check reads the whole `architecture/` project,
+so a fleet keeping a second `model { }` block in a sibling got a brief demanding edges it had
+already drawn while `validate --all` reported `landscape.matched`. Both now read the project.
+
+#### A home for an intra-service use case
+
+**Landed 2026-09-03.** Measured: `architecture/usecases/` cannot resolve a container (one such file
+is `landscape.invalid` plus a `spine.landscape-invalid` per service), and a view beside the model
+rendered while nothing graded it. Landed: the service's own LikeC4 project as the slot — every
+`.likec4` beside model.likec4 and any tagged view inside it — graded by `validate --service`/`--all`
+with the five existing `usecase.*` codes, `#req-` scoped by the service's own Requirement-IDs,
+`#cap-` refused by placement, a broken sibling one `usecase.flow-invalid` while the model keeps
+grading; plus the tier-2 skip and the fourth `step-unlinked` guard in the shared graders. Rejected:
+a fixed `usecases/` directory alone (the reporter's `views.likec4` would render ungraded),
+`views.likec4` alone (a second file would be invisible), a new code for the broken sibling (nothing
+branches differently), gating the read on `likec4.config.json` (create-only, deletable). Cost: one
+recursive readdir per service; a workspace only where a view in model.likec4 opts in or a sibling
+mentions a reserved prefix anywhere in its bytes — an untagged sibling is never graded, and once
+the workspace is loaded a project that does not read is one `usecase.flow-invalid` whether or not a
+view opted in.
+
+#### The service model, renderable from the fleet root
+
+**Landed 2026-09-03**, from one problem report. The root `likec4.config.json` that
+`loam init --create` writes excludes `services/**` on purpose — every `model.likec4` declares its
+own `specification` block, and a renderer merging the tree calls each one a duplicate — and the
+cost of that exclusion had gone unstated for a release: the model `loam adopt` spends the most
+effort on was a box with nothing inside it in the renderer opened at the docs root, and the only
+documented path to its containers was one renderer invocation per service directory. The report's
+hand-written workaround, one project file per service, is what this entry makes loam's.
+
+**Measured** at the pinned likec4 before a line was written. A `services/<svc>/likec4.config.json`
+is registered as a project of its own even though the root excludes the directory: the workspace
+loads `fleet` plus one project per service with zero errors, the root project sees exactly the
+files it saw before, and each service project carries an auto `index` view of the containers beside
+the authored view. A nested project named `fleet` is silently registered as `fleet-1`. With more
+than one project, `likec4 validate` at the root refuses with `Specify exact project` until given
+`--project`. A nested project holding no `.likec4` file is silently absent from the project list. A
+service model that does not parse breaks only its own project; siblings and `fleet` still compute.
+And the project picker shows `title ?? id`, so the title is what a human reads.
+
+**What landed.** `loam subsystem sync` writes the file — create-only, two keys, bytes a function of
+the id alone — beside every service model that has none, once the root project file exists, and
+reports them under an additive `projects` key. `loam validate --all` grades presence with one
+warning per service, `service.likec4-config-missing`, whose fix is `sync`. No new command: the
+[Later](#later--promote-only-from-evidence) Rendering row's evidence bar was met for the SCOPING
+half of its trigger and answered by wiring — one file that tells the renderer where a project is —
+not by a drawing verb; drawing stays LikeC4's, and the row says so now.
+
+**Rejected.** A new command, because the report's problem was a missing file, not a missing verb,
+and a verb would have put loam between a team and its renderer for good. The agent writing the file
+from the adopt brief, because a file written by hand per service is the state the report found —
+one of four adopted services had one — and loam already writes the root file and knows every
+service directory. A generated-and-compared file with a `-stale` grade, because the bytes cannot go
+stale and a compare would fight the `title` and styles LikeC4 lets a team add. Grading in `doctor`
+alone, because the gap is per service and `doctor` reports on the repository, not on its services;
+the docs repo's CI runs `validate --all`.
+
+**Costs**, each where a user meets it. A repo with adopted services reports one warning per service
+on its first `validate --all` after upgrading, until one `sync`; that `sync` leaves N untracked
+files it does not `git add`; from the first service project on, `likec4 validate` at the docs root
+needs `--project <name>` (`build` and `export` take every project without one — measured); the
+renderer's project list grows by one per adopted service, and a fleet-map box is not a link into
+that project (LikeC4 projects are separate models); and the project name is not injective (an id spelled billing.core beside one spelled
+billing-core, `service-fleet` beside `fleet`), disclosed in SCHEMA rather than escaped away,
+because the picker shows the id.
+
+**Superseded for extending models, one day later.** The last of those costs — one picker entry per
+adopted service — is what report #009 measured at 57 entries, and the entry that opens this list is
+what removed its cause rather than its symptom: a model that extends the fleet map shares the root
+project with it, so it is owed no project file and adds no entry, and `loam subsystem sync` writes
+the file only for a model that stands alone. Everything measured here still holds for that shape,
+and is why it is still supported; it is no longer what a new model is written as.
+
+#### The generated subsystem views — a label, a boundary, and one reader of the map
+
+**Landed 2026-09-03.** Three problem reports from a fleet running loam, one axis. The generated
+`architecture/subsystems.likec4` exists only to be rendered and was the least readable object in a
+docs repo: no `title`, so the renderer showed the hex-escaped view id, and leaf includes only, so a
+fleet drawn as grouped C4 rendered flat. Each view now carries the marker's title (the directory
+name when it has none) and description, and draws a boundary the LANDSCAPE decides: the model's own
+containing element when one holds exactly the members, a `group` mirroring the directory subtree
+when the map nests nothing, and one `// model: no boundary — …` comment when the two disagree.
+That comment is the whole answer to the drift the third report asked about — disclosure in a
+generated artifact, never a finding, because grading placement against the map is the policy the
+tree is defined not to carry. The graded alternative is written down under
+[Later](#later--promote-only-from-evidence) with the evidence bar it has to clear.
+
+The hunt found what neither report did: `validate --all` graded that file against the whole
+`architecture/` project while every writer rendered it from `landscape.likec4` alone, so a
+use-case document binding one element could produce a `subsystem.views-stale` that
+`loam subsystem sync` reported as `current` — reproduced on `examples/docs`, and fixed by pointing
+both sides at the same read.
+
+**And the repository's palette (2026-09-03).** A generated view can carry no inline `style` rule —
+the file is regenerated wholesale — and the one mechanism LikeC4 gives a view for borrowing a
+repository's styling is a reference to a global style by id, which is a parse error that blanks the
+whole `architecture/` project when nothing declares it. So the convention is one reserved name:
+declare `global { styleGroup subsystems { … } }` anywhere in the `architecture/` project and every
+generated view references it; declare nothing and the file is what it was. Rejected: reading the id
+off a key in `likec4.config.json` (create-only, never re-read, and not a LikeC4 document whose
+contents a parse can check), and "reference the single declared group" (a second group declared for
+a hand-drawn view would silently switch the generated views' styling off and restale the file on a
+change that touched no subsystem). The presence read is a census of the keys of
+`$data.globals.styles`, a declaration read like `specification`; seven tripwire assertions in
+`test/likec4-view-shape.test.ts` pin the shape so a likec4 bump fails there before it reaches a
+generated file.
+
+#### The deployment axis — topology joined to requirements
+
+**Promoted 2026-09-02, and authored as a feature in loam's own docs repo** rather than as an item
+text here: `meta/docs/features/archive/FEAT-1-the-deployment-axis/`, whose `intent.md` carries the
+four measurements and whose `specs/loam/arch.spec.md` carries the five rules the change establishes,
+each with scenarios. This entry is the decision and the gate; that feature is the specification, and
+the two must not be allowed to become two accounts of the same change.
+
+**Landed 2026-09-02, complete.** Every step is in, and step 4 was corrected rather than built
+(below) — the item specified two finding codes that the implementation showed it should not mint.
+FEAT-1 archived once every edge it claimed existed —
+and it archived having been CORRECTED against the tree twice, which is the argument for the route
+rather than a footnote to it: the delta predicted a `core/kernel/` dependency that turned out to be
+type-only (a brand costs an annotation, not an import) and missed `core/coherence/` entirely.
+`npm run meta:check` was red for the whole of the build and went green with the archive, which is
+the axis working rather than a gap in it.
+
+The whole change is reviewable as five commits on `feat/deployment-axis`, and the one thing to read
+first is what the implementation taught the plan: two of the codes this item specified were not
+minted, and the reasons are in step 4.
+
+**What is wrong today.** A LikeC4 `deployment { }` block is legal in a docs repo and completely
+unread. The parser resolves every `instanceOf` in it — a container renamed out from under a
+deployment node fails the gate as `landscape.invalid` — and after that nothing: no requirement can
+name a node, no report counts one, and the context pack an agent implements from does not mention
+topology at all. Two of the four measurements taken on a copy of `examples/docs` are the reason this
+is an item rather than a wish. A `#obl-` tag on a `deploymentNode` is invisible to
+`validate/fleet/obligations.ts`, which walks the logical model only — the same undeclared tag raises
+`obligation.unknown` on a container and nothing on a datacenter, which is fail-open and a defect on
+its own terms. And `parsedModel().deployment` already returns nodes with their tags, instances
+carrying the id of the logical element each one instances, and relationships carrying metadata, so
+the read costs no second parse, no new file format and no change to the frozen CLI surface.
+
+**Required changes**, in the order the dependency graph forces:
+
+1. Walk the deployment model in every `#obl-` grade. Fail-open becomes fail-closed; no new code.
+2. A fourth `Covers:` entry form, `node:<id>`, with the same prefix accepted on either side of the
+   edge form. No new code.
+3. The parse adapter in `src/core/c4/parsed/`, and the deployment records added to
+   `test/likec4-model-parity.test.ts` — a two-stage substitution nothing measures is an assumption.
+   `src/core/c4/` holds exactly five files, so this is a sub-package and not a sixth module.
+4. **No new finding code, and this is a correction the implementation earned.** The item planned
+   two. The first, for a tagged node or edge no living arch requirement covers, turned out to be
+   `obligation.uncovered` asked of a second model: once step 1 walks the topology, the existing code
+   answers it, and a caller acts identically either way — write a `Covers:` line. A second code for
+   one question is exactly what the add-a-code checklist refuses. The second, for a container no
+   deployment instances, is declined outright: it asserts that everything modelled ought to be
+   deployed somewhere, which is a COMPLETENESS claim, and completeness is the one thing
+   `src/core/brief/unchecked.ts` says loam never checks. It is the same category error as the
+   at-least-two-datacenters rule below, one axis over.
+5. `features/<FEAT>/deployment/<name>.likec4`, create-only and copied whole — `core/usecases/delta/`
+   one axis over. It works because `extend` was measured to resolve across documents of one project,
+   so no text splice is needed; `delta-blocks.ts` goes on refusing a `deployment { }` block inside
+   `delta.likec4` and its message names the new slot. The collision is on the FILE, never on what is
+   inside it: two features may both extend one living region from documents of their own and both
+   archive, which is the shape the fleet-wide change actually takes.
+
+   **Graded against the merge preview**, which shipped one commit behind the slot and is the
+   second code, `deployment.doc-invalid` (error, never overridable). This axis needs the post-merge
+   corpus more literally than the use-case one: a feature that stands a NEW service up in a cluster
+   declares it in `delta.likec4` and instances it in the topology, so the element the document names
+   exists only after the merge. The staging that makes that readable moved OUT of
+   `core/usecases/delta/overlay.ts` into `core/c4/project/staged.ts` rather than being copied — the
+   two axes would have disagreed first about the merge preview, which is the one thing both
+   refusals rest on. The extraction dropped `core/usecases/` → `core/kernel/`, which is a one-line
+   edge and was edited into the model directly.
+6. The surfaces: the topology in the context pack (`context --json`'s `living.deployment`), the code
+   table `test/codes-drift.test.ts` requires, and one more statement in
+   `src/core/brief/unchecked.ts`. `loam explain` needed nothing — it parses the /loam-check fix
+   tables at runtime, so the rows added there ARE the entries. The scorecard row the item listed was
+   dropped: the fleet scorecard aggregates at the bound `service`, and a topology row there would
+   count deployment nodes against a denominator no service owns.
+
+**Exit criteria.** Every step above green under the full gate; `covers.unknown` demonstrated firing
+on a covered node that a topology change renamed, which is the acceptance criterion the trigger
+names; the parity suite extended and shown to fail against an un-extended adapter; and
+`test/self-model.test.ts` re-pinned once FEAT-1 archives.
+
+**Out of scope, and each refusal is load-bearing.** No reading of Terraform, Helm or cluster state —
+that is the extractor the non-goals forbid. No check that a service is deployed in at least two
+datacenters: it would need `criticality` promoted from prose to a read field, and it would turn
+`architecture/obligations.yaml` into the policy engine that file says in its own words it is not. A
+multi-datacenter rule is an authored requirement whose `Covers:` line names the nodes; loam grades
+the join and never the architecture. And no `environment` concept above LikeC4, because
+`deploymentNode` is that mechanism and the fleet names its own kinds.
+
+**The evidence, and its one gap stated plainly.** Operator: a team standing up a standby cluster in
+a second datacenter. Repeated task: keeping RTO/RPO requirements attached to a topology that keeps
+changing. Failure mode: a requirement about replication staying green after the node it described
+was renamed or removed. Frequency: every topology change, which is the cadence a migration runs at.
+Current workaround: a `Covers:` line that resolves to nothing, or no written requirement at all.
+Acceptance criterion: a topology change that orphans a covered requirement is convicted without a
+human noticing it first. **That is one operator, not two.** The maintainer judged the trigger
+sufficient on the same basis recorded for landscape scaling and the authored business axis, and the
+[Later](#later--promote-only-from-evidence) exit criteria are amended below to say so rather than
+leaving the two paragraphs to contradict each other. Steps 1 and 2 do not rest on that judgement at
+all: the first is a fail-open defect and the second is a grammar entry, and neither is a new axis.
+
 
 - **A feature can bring a use case.** `features/<FEAT>/usecases/<name>.likec4` — a views-only
   document `loam archive` copies into `architecture/usecases/` and `loam unarchive` takes back,
@@ -243,13 +695,99 @@ item gets promoted — it went from here to `## Now` and from there to
   invocation, scoping, or artifact reproducibility is the recurring problem, and it must stay
   outside validation so view computation cannot slow or change the gate. This item is about
   **drawing**, and LikeC4 keeps that job. Reading a `dynamic view`'s declared steps is not rendering
-  and is not this item — see docs/DESIGN.md rule 26.
+  and is not this item — see docs/DESIGN.md rule 26. The scoping half of that bar was met and
+  answered on 2026-09-03 by the per-service project file `loam subsystem sync` writes (see
+  [Recently landed](#recently-landed)) — wiring rather than a verb; drawing stays LikeC4's.
 - **UI generation:** begin with a disposable projection over the stable JSON contract only after CLI
   consumers demonstrate a repeated navigation problem. It must not introduce a second mutable state,
   hidden workflow state, or a required service.
-- **Landscape scaling:** retain one landscape while conflicts are exceptional. If same-service
-  conflicts become routine — the current trigger in [SCHEMA.md](SCHEMA.md) is weekly rather than
-  monthly — evaluate service-owned model files plus a thin global cross-service map. Migration must
+- **A graded subsystem/model correspondence:** a fleet that draws its landscape as grouped C4 states
+  its grouping twice — once as directories under `services/`, once as the nesting of the elements —
+  and `loam subsystem move` changes the first while the second stays put. Since 2026-09-02 the
+  generated views file DISCLOSES that (the `// model: no boundary — …` line; see
+  [SCHEMA.md](SCHEMA.md)), and nothing grades it, because grading placement against the map is the
+  policy the tree is defined not to carry. The shape a graded version would take is known and
+  measured: an author's opt-in `metadata { subsystem '<name>' }` on the grouping element, read
+  through the existing metadata reader, the NAME rather than the path (names are unique in one flat
+  namespace and survive a move, which a path binding would not), with the check structurally silent
+  for every fleet that never writes one. Promote only on evidence from a second fleet, after living
+  with the disclosure — the first report classified itself `inconclusive`, and one fleet is not
+  enough to qualify an invariant that says placement is never part of any identity.
+- **A feature brings an intra-service flow.** `features/<FEAT>/specs/<svc>/usecases/<name>.likec4`,
+  copied create-only by `loam archive` into `services/<…>/<svc>/usecases/` and taken back by
+  `loam unarchive`, graded before the copy against the service's own LikeC4 project with the
+  feature's `specs/<svc>/` requirement deltas in `#req-` scope — `usecase.flow-exists` and
+  `usecase.flow-invalid` reused, never `--approve`-overridable. Deliberately NOT built with the
+  living slot (2026-09-03): the version-3 snapshot manifest already carries an artifact path with a
+  directory in it, so nothing about the undo changes when it lands, and no model delta exists to
+  preview — what it waits for is one fleet asking for a container-level flow to ship in the same
+  change as the `arch.spec.md` requirement it answers. Until then a service-local flow is written
+  directly into the service directory in the same pull request, where git produces the conflict;
+  building the feature route ahead of that evidence is the invented need the non-goals forbid.
+- **A subsystem-scoped use-case slot.** A flow whose hops all sit inside one subsystem's subtree
+  looks like it wants a home between the two that exist — `architecture/usecases/` is the fleet's
+  slot, `services/<…>/<svc>/usecases/` is one service's. Deliberately NOT built (2026-09-07), and
+  the reason is that the capability is already there: a subsystem-scoped flow IS a fleet use case
+  whose hops happen to share a subtree, `architecture/usecases/<name>.likec4` already grades it, and
+  its view already folds into the same title-path folders as the generated subsystem view above it.
+  A second slot would duplicate the grader, the tag vocabulary and the archive route for no
+  capability that does not exist today. Promote only on evidence that a fleet's subsystem flows are
+  being lost among its fleet flows in the renderer's view list — which is a naming problem before it
+  is a slot problem, and one the title convention answers first.
+- **A flow-untagged check** (it would be spelled usecase.flow-untagged): a `.likec4` beside a
+  service's model that mentions a `req-` prefix while no view in that project carries the tag — an
+  author who reached for the intra-service use-case axis and missed, whose flow renders and is
+  graded by nothing. It grades a view that EXISTS rather than an absence, so docs/DESIGN.md rule 26
+  permits it, unlike the service.usecases-missing nobody may ever build. Not built (2026-09-07) for
+  a mechanical reason worth stating: `core/brief/checks.ts` sits at 399 of 400 lines inside a
+  five-file-capped package, so a new non-ok code forces a split-module commit before any behaviour
+  can land, and that split should be chosen for a seam rather than for a code. Promote when a second
+  fleet reports a flow that rendered and was graded by nothing.
+- **What the closed `flows-dynamic-views` branch had and main still lacks.** The branch drew
+  cross-service journeys as fleet-level dynamic views before main grew its own use-case axis; it was
+  closed as superseded on 2026-10-10, its one piece main lacked outright — suites, the participant
+  union a test stand needs — was ported onto that axis (`#suite-<name>`, `loam list suites`), and its
+  reference implementation stays reachable at the tag `archive/flows-dynamic-views` — commit
+  `d90b6f9`, the closed branch's head, which is the name to use where the tag was never fetched
+  (`git show d90b6f9:<path>`). Five things remain, and each waits for the same evidence — pilot
+  teams actually writing tagged use cases — because each would freeze a code, a grammar or a
+  generated file, and the two checks among them are advisory heuristics:
+  - **Per-view outcome counting against scenarios** — a view's `alt`/`opt`/`try` arms summed (not
+    multiplied) and compared with the scenarios covering it (it would be spelled
+    usecase.outcomes-uncovered, warn). `core/c4/parsed/dynamic-views.ts` flattens the block tree
+    it would need, and the count says how many outcomes lack a scenario, never which. Waits for
+    flows with branches being written and a team asking which outcomes go untested.
+  - **A feature-scope warning for a `#FEAT` cross-service edge no journey traverses** (it would be
+    spelled usecase.edge-unrepresented, adopt-gated on the fleet having a tagged use case). Main sees
+    only the removal direction (`diff.op-removed-consumed`). Waits for a fleet whose journeys are
+    kept at all — on one with none it is noise.
+  - **`Covers: view:<id>`** — a join from an arch-axis requirement to a journey that needs no
+    capability axis. It runs the opposite way to `#req-` (two answers to "what covers this flow"),
+    and a bare view id can now be stolen by a service-local view of the same name. Waits for
+    evidence that legacy teams will not write `capabilities/` — the one case where main has no way
+    to join a cross-service flow to a runner-verified arch-level outcome.
+  - **Generated per-suite views** (a `flow-groups.likec4`, a sync verb, a staleness code) —
+    rendering only. Waits for a team asking to SEE a suite rather than list it.
+  - **Changing an existing journey through a feature** (replace by view id, with a conflict
+    warning). Main declined it on purpose — the feature route is create-only and an existing flow is
+    edited in the pull request — and it waits for concurrent journey edits conflicting more often
+    than review absorbs.
+- **Landscape scaling:** retain one landscape while conflicts are exceptional, and half of what
+  this row once asked for arrived on 2026-09-04. Per-service internals now live in
+  `services/<svc>/model.likec4` by default: `loam archive` routes a delta's fqn-spelled interior
+  into the owning service's extending model, and a team adopting a service adds nothing to
+  `architecture/landscape.likec4` but one element and its cross-service edges. The map holds a
+  service's interior only where a team puts it on purpose — a store nested under its owner so a
+  second service can name it (SCHEMA's "Private stores") — or where a delta spells its parent by
+  title rather than by the map's id (the archive's documented remainder). What is
+  left is the CROSS-SERVICE EDGE, which still exists twice — container-level in the model,
+  service-level in the map — and that duplication is **deliberate**, not a leftover: the spine, the
+  platform census, `landscape.service-isolated` and every other fleet check read the map alone,
+  which is what lets a fleet answer "who calls this service" from one diffable document without
+  parsing sixty. Thinning the map to elements plus cross-service edges means teaching those checks
+  to read the edges out of the models that attest them, and paying the blast radius that comes with
+  it. If same-service conflicts become routine — the current trigger in [SCHEMA.md](SCHEMA.md) is
+  weekly rather than monthly — evaluate that. Migration must
   preserve archive/undo, deterministic resolution, and readable plain files.
 - **Authored business axis — PROMOTED 2026-08-27, and landed in full; see
   [Recently landed](#recently-landed).** The gate asked for evidence of authorship: analyst edits
@@ -264,8 +802,11 @@ item gets promoted — it went from here to `## Now` and from there to
 
 Exit criteria for promoting a Later item:
 
-- Evidence comes from at least two independent operators or fleets, except landscape scaling and the
-  authored business axis, whose recorded triggers are sufficient.
+- Evidence comes from at least two independent operators or fleets, except landscape scaling, the
+  authored business axis and — added 2026-09-02 — the deployment axis in [Now](#now), whose recorded
+  triggers are sufficient. Three exceptions is where this criterion starts describing the rule
+  rather than the exception: the next single-operator promotion has to say why the criterion should
+  survive, or retire it.
 - An ADR compares the existing workflow, external tooling, and the smallest loam-owned change.
 - A prototype is measured against a predeclared acceptance criterion and preserves every non-goal
   below.
@@ -276,7 +817,7 @@ Exit criteria for promoting a Later item:
 
 Placed in a section of its own, and the placement is the argument. This is not a `## Now` item, and
 nothing here may be mistaken for one. It is not a "Later" candidate either: promotion
-from that section requires evidence from at least two independent operators or fleets (bar the two
+from that section requires evidence from at least two independent operators or fleets (bar the three
 whose recorded triggers were judged sufficient when they were written), and loam's own repository is
 one operator by construction, so a Later entry could only ever be a permanent exception to the rule
 it sits under. Nor is its value speculative — the trigger below is a defect this repository has