@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.13

package/ROADMAP.md

@@ -0,0 +1,1035 @@
+# Roadmap
+
+_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
+an item between sections is a product decision, not a wording change.
+
+The compatibility boundary remains the one in
+[AGENTS.md](https://github.com/ybotok/loam/blob/main/AGENTS.md): command names and flags, exit
+codes, the JSON envelope, and stable finding codes are public contracts. An improvement that changes
+one of them needs an explicit compatibility decision and a user-visible CHANGELOG entry.
+
+## Current assessment
+
+loam is a credible beta with a differentiated core: architecture, requirements, contracts, generated
+acceptance tests, and implementation evidence remain ordinary files in repositories rather than
+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 **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 **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-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
+`listen EPERM` — a runner restriction, not a CLI behavior failure — and a sandbox that denies tmpdir
+writes is the class under which `validate --all`'s batched parse degrades to per-document speed
+without changing a finding.
+
+The strongest foundations to preserve are:
+
+- **Durable, inspectable source of truth.** The product still has no server, database, or runtime
+  network dependency. Its document contract is described in [SCHEMA.md](SCHEMA.md), and only three
+  packages are runtime dependencies in [package.json](package.json).
+- **Explicit machine contracts.** The versioned JSON envelope and stable error codes live in
+  [src/core/envelope/json.ts](https://github.com/ybotok/loam/blob/main/src/core/envelope/json.ts);
+  issue severity, archive gating, and override semantics remain separate in
+  [src/core/vocabulary/issue.ts](https://github.com/ybotok/loam/blob/main/src/core/vocabulary/issue.ts).
+  [test/codes-drift.test.ts](https://github.com/ybotok/loam/blob/main/test/codes-drift.test.ts) and
+  [test/agent-commands-runnable.test.ts](https://github.com/ybotok/loam/blob/main/test/agent-commands-runnable.test.ts)
+  protect what agents branch on and what loam tells them to run, and
+  [test/docs-facts.test.ts](https://github.com/ybotok/loam/blob/main/test/docs-facts.test.ts) plus
+  [test/package-docs.test.ts](https://github.com/ybotok/loam/blob/main/test/package-docs.test.ts)
+  hold the shipped prose to the same standard: counted facts derive or carry a date, named codes are
+  codes loam emits, links resolve from the tarball, and every documented gap has its owner in this
+  file.
+- **One transactional write path.** Archive and unarchive keep their snapshot-backed path across
+  [src/commands/archive/run.ts](https://github.com/ybotok/loam/blob/main/src/commands/archive/run.ts)
+  and [src/core/staging/](https://github.com/ybotok/loam/tree/main/src/core/staging); every other
+  multi-file writer — `new`, `gherkin`, `rebase`, `vouch`, `subsystem move` and `sync` — commits
+  through the smaller journaled transaction in
+  [src/core/staging/txn/](https://github.com/ybotok/loam/tree/main/src/core/staging/txn), whose
+  staged bytes are durable beside their targets so recovery rolls forward, and the verification
+  record commits under the same docs lock with a byte-level compare-and-swap. `validate` and
+  `doctor` report an interrupted commit until recovery succeeds. This is the model for any future
+  writer, not a subsystem to replace.
+- **Path, identity and provenance discipline.** Lexical and real-path containment are centralized in
+  [src/core/kernel/path-safety.ts](https://github.com/ybotok/loam/blob/main/src/core/kernel/path-safety.ts);
+  validated ids and directories carry branded types constructible only in
+  [src/core/kernel/ids/](https://github.com/ybotok/loam/tree/main/src/core/kernel/ids) and consumed
+  through [src/core/repo/paths.ts](https://github.com/ybotok/loam/blob/main/src/core/repo/paths.ts),
+  with the casts contained by the architecture gate. Verification distinguishes an agent attestation
+  from digest-matched test evidence through
+  [src/core/verify/](https://github.com/ybotok/loam/tree/main/src/core/verify) and the verification
+  record defined in [SCHEMA.md](SCHEMA.md).
+- **Executable architecture.** `npm run arch:check`
+  ([scripts/arch-check.mjs](https://github.com/ybotok/loam/blob/main/scripts/arch-check.mjs)) proves
+  every invariant [docs/DESIGN.md](https://github.com/ybotok/loam/blob/main/docs/DESIGN.md) and
+  [docs/CODE-STYLE.md](https://github.com/ybotok/loam/blob/main/docs/CODE-STYLE.md) state — import
+  cycles, the package graph, the core→commands ban, the barrel ban, the console/process boundary,
+  child-process bounds, brand-cast containment — each with a negative self-test in
+  [test/arch-gate.test.ts](https://github.com/ybotok/loam/blob/main/test/arch-gate.test.ts); the
+  400-line / four-parameter / five-file limits hold with an empty baseline in
+  [test/code-limits.test.ts](https://github.com/ybotok/loam/blob/main/test/code-limits.test.ts);
+  coverage thresholds are explicit in
+  [vitest.config.ts](https://github.com/ybotok/loam/blob/main/vitest.config.ts); and
+  [scripts/gate-stress.mjs](https://github.com/ybotok/loam/blob/main/scripts/gate-stress.mjs) makes
+  gate stability a classified measurement rather than an impression.
+
+## 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, 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 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
+acceptance criterion — never because this section is empty. An empty `## Now` is a true statement
+about the backlog, and filling it from the candidate list to avoid the appearance of one would be
+exactly the invented need the non-goals forbid.
+
+## Recently landed
+
+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 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,
+  create-only, refused by `usecase.flow-exists` when the living tree already holds that file. All
+  four exit criteria: a `#req-` tag in it resolves against the feature's own capability delta as
+  well as the living tree (the both-corpora rule `Realizes:` follows); `capability.uncovered` counts
+  a resolved feature-local flow as cover, and its message now names the slot instead of telling an
+  author to `--approve` first and tag the flow afterwards; the merge and its undo go through the
+  transaction every other axis already uses; and a flow is graded against the map its own merge
+  would leave behind, so a hop may name a service the feature's `delta.likec4` adds while a hop
+  naming an element the merge does NOT land is `usecase.flow-invalid` — refused at plan time, with
+  `--approve` deliberately unable to move it. The design decision worth recording is the one the
+  item flagged as open: the overlay is the ARCHIVE'S OWN MERGE PREVIEW, computed with
+  `planLandscapeMerge` rather than approximated, so a flow can never be graded against a map the
+  merge does not write. `delta.likec4` still refuses a `dynamic view` and the reason is mechanical
+  rather than policy — it re-declares the landscape's identifiers and carries its own
+  `specification` block, so it cannot be staged beside the map in one LikeC4 project — but its
+  message now names the slot that exists.
+- **One predicate answers "is this a use case".** `isUseCase` moved out of
+  `core/usecases/fleet.ts`'s private scope, widened to either reserved prefix, and is now the only
+  spelling: `validate`'s `gradedViews`, the fleet-flow read behind `capability.requirement-unrealized`,
+  and every reader behind `loam diff`, `delta`, `status`, the packs and `list capabilities` take it.
+  The byte gate that lets a fleet with no use cases skip the LikeC4 load was widened with it, and
+  that half mattered more than the predicate: a fleet whose only flow was `#req-`-tagged declared
+  `tag req-…` and no `cap-` anywhere, so the scan answered "no use cases" and nothing loaded the
+  project at all. Six tests pin it, each proven to fail against the narrowed predicate.
+
+  Two of the exit criterion's named readers do NOT show a `#req-`-only view, and the wording was
+  wrong rather than the code: `loam explore --capability` seeds through `flowsClaiming`, which
+  matches the whole `cap-<slug>` tag, and `list capabilities`' `keptBy` needs exactly one RESOLVED
+  `#cap-` scope before a `#req-` tag means anything. A view with no capability tag claims no
+  capability — correctly, and in both places. What the widening buys them is that such a view is
+  now SEEN: it opts the fleet in, so the flows are read and `useCases.unreadable` answers honestly
+  instead of the scan reporting a fleet with no use cases.
+- **A step-definition catalogue.** Decided in writing first, as the item required, and the decision
+  is AUTHORED rather than emitted: `services/<svc>/steps.yaml`, a `steps:` list of step texts,
+  recording which phrases a team has agreed its suite defines. Four things decided it — loam does not
+  read code and must not present a derived thing as truth, so what can honestly be written down is a
+  decision and not an observation; `loam steps` needs no service repo to stand in and a catalogue
+  beside the code would make it need one; the rule the glossary and capability trees settled puts an
+  entry without prose in YAML; and nothing generated may land inside `<gherkinDir>/loam/`, which
+  `loam gherkin` owns and overwrites wholesale. `loam steps` now reports written phrases against
+  catalogued ones both ways round, so a phrase nobody has defined is distinguishable from one nobody
+  has written, and an ABSENT catalogue is distinguishable from an UNREADABLE one — reporting either
+  as "nothing catalogued" would print a whole suite as work owed. **The axis carries no stable code
+  and `loam validate` never reads it**: a phrase written before its glue is the normal order of work,
+  the near-duplicate groups stay a report, and no phrase-similarity finding ships. Entries are step
+  TEXTS rather than keys, because the key is loam's own normalisation and asking an author to type
+  it would make an internal spelling a hand-written contract.
+
+- The authored business axis, end to end: the `capabilities/<cap>/spec.md` tree, `Realizes:` with
+  its living pin, the `#req-` flow join, the feature-local delta, the archive gate in both
+  directions and `loam new --capability` — `1c5541a`…`0850538`. Every remainder the item listed is
+  closed: the flag is registered, `show` and `delta` project a capability delta, and a half-created
+  `features/<FEAT>/capabilities/<id>/` is graded. Full item text: `git show ab4c856:ROADMAP.md`.
+- The living `Realizes:` pin and `capability.realizes-stale`, with `loam rebase --living` — the
+  product's first standing suspect link over the LIVING corpus, and the answer to the one failure
+  class that decayed silently after a successful archive. Every other capability check is an
+  existence constraint and goes quiet when a target merely changes.
+- The spine-first first hour: `examples/fleet.yaml`, day zero starting at `loam seed`, and a
+  README entry point that reaches a cross-service conviction with no requirement Markdown at all.
+- `contracts.openapi` in `loam.json`: the build's own contract read as a check
+  (`openapi.generated-stale`, `contracts.source-missing`, `contracts.source-invalid`). Closes the
+  most load-bearing untested premise in SCHEMA — that the committed contract is the one the
+  service serves — without becoming a writer or an extractor.
+- `spec.unknown-directive`: the near-miss grammar guard. An unrecognised body-line key is prose,
+  so the join it resembles does not exist and every check over it stays green for want of anything
+  to fail.
+- `checklist` and `docsCommit` on each attestation, plus `verify.checklist-forked` — a federated
+  record can now say WHICH service's answers went stale rather than flagging all or none.
+- Atomic, locked, compare-and-swap verification records — `60f4df6`.
+- Full-gate concurrency stability: the classified stress runner and host probe — `d9b396a`.
+- Crash-consistent multi-file writers: the journaled roll-forward transaction — `88e9026`.
+- Executable architecture invariants: `npm run arch:check` and the brand migration —
+  `0106b49`…`9c0f01e`.
+- Baseline semantics for OpenAPI path items and components — `0824b02`…`246a800`.
+- OpenSpec corpus rebaselined at v1.9 beside the historical v1.7 — `9a0c6d7`, `724ab15`.
+- `validate --all` fit for the fleet gate: one LikeC4 workspace, 18.8x — `f66ff56`…`56b031d`.
+- The AsyncAPI feature lifecycle, mirrored axis-for-axis — `c5e205c`…`8837e9b`.
+- Subsystems: a navigable tree under `services/` that no identity depends on — `600a696`…`8aee101`.
+- The capability vocabulary, the requirement join and the `list capabilities` rollup —
+  `2bd9400`…`e26ff9f`.
+- Documentation, package-content and link protection — `6ea2a68`…`08330ea`; paper trails `5cd3942`.
+- The domain glossary, and the link check that makes it exact — `bc1b936`…`44a5386`.
+- Architectural obligations: the ADR, the `#obl-` tag and the living `Covers:` index — `0b5fc24`.
+
+Honest leftovers. One remains, and it lives outside this repository: the CI `stability` job has
+still to be observed green, which needs a push and then a `workflow_dispatch`.
+
+The two merge holes recorded here are closed, and they were not the same defect. On the OpenAPI axis
+the capability existed and was merely unreachable: the merge tested `paths` for absence and answered
+no-op before it had parsed the living document, while the component closure is the last thing it
+runs. It now consults the surface enumeration instead, and a genuinely new component is promoted
+BEFORE the ref fixpoint is seeded rather than after, so its own `$ref`s ride the same sweep.
+
+On the event axis the capability did not exist. AsyncAPI had no surface enumeration outside the
+three slots, no root baseline record, and no pin that could reach a `components.schemas` value — the
+event pin is written INTO a slot value, which works because every slot value is a mapping and a JSON
+Schema is not. So closing it was new machinery rather than the same control-flow fix: a
+`core/asyncapi/baseline/` package, a root `x-loam-baselines` record that `loam rebase` writes and
+`stripAsyncapiMarkers` removes on every branch, surface grading folded into the SAME per-service
+unpinned counter rather than a second warning, and one new archive-plan code,
+`asyncapi.component-modified`. The asymmetry is worth recording: two sentences in one bullet
+described one control-flow bug and one absent subsystem, and only tracing the code told them apart.
+
+## Later — promote only from evidence
+
+Health composition, built-in rendering, UI generation and landscape decomposition remain candidate
+investments, not promises. Promote one only when fleet evidence names the operator, repeated task,
+failure mode, frequency, current workaround, and measurable acceptance criterion. The authored
+business axis stays listed below because its trigger and its reasoning are the record of how a Later
+item gets promoted — it went from here to `## Now` and from there to
+[Recently landed](#recently-landed), and the trail is the point.
+
+- **Health composition:** proceed only if both service-level `health.yaml` and fleet relationships
+  are repeatedly being joined by hand and that work causes missed or contradictory checks. The
+  result must compose declared signals; it must not infer operational truth from code or monitoring
+  systems.
+- **Rendering:** LikeC4 remains the renderer. A loam rendering command needs evidence that
+  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. 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.
+- **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
+  appearing in `services/*/spec.md` history, or capability-level requirements accumulating as prose
+  that no requirement realizes. The maintainer supplied it as a statement about how his fleet works
+  rather than as git history — business does not think in services, and an analyst does not write
+  them — and the shape of the hole was verified rather than argued: **every requirement loam knew
+  belonged to exactly one service directory**, so an analyst’s whole surface was a declared name in
+  `capabilities.yaml` plus an `intent.md` that is archived with its feature. No living
+  business-level document existed at any altitude. The full gated text, including the four sub-items
+  and the cascade it follows, is in this file’s history (`git show 53c762a:ROADMAP.md`).
+
+Exit criteria for promoting a Later item:
+
+- 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.
+- The feature returns to this roadmap under a numbered priority before production implementation
+  begins.
+
+## Self-hosting: loam on loam
+
+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 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
+already produced by hand. As with every other section here, the position implies no schedule.
+
+### Model loam's own architecture in loam
+
+loam's architecture is already specified in prose and already executable:
+[docs/DESIGN.md](https://github.com/ybotok/loam/blob/main/docs/DESIGN.md) states it as numbered
+rules, and `npm run arch:check`
+([scripts/arch-check.mjs](https://github.com/ybotok/loam/blob/main/scripts/arch-check.mjs)) over
+[scripts/package-graph.mjs](https://github.com/ybotok/loam/blob/main/scripts/package-graph.mjs) is
+their proof. That is exactly the shape of an `arch.spec.md` whose requirements carry `Covers:` lines
+onto a LikeC4 model of loam's own package graph — the one axis where loam's subject matter and
+loam's own tree are the same object.
+
+The recorded trigger is two defects that reviewers caught **by hand** during the session that
+produced the current `[Unreleased]` [CHANGELOG.md](CHANGELOG.md), both of which a
+`c4.uncovered`-style check convicts mechanically: a package of one file — a `core/review/`, against
+DESIGN's own "a package of one is a directory pretending to be a subject" — and a package-layout
+table that had stopped describing the tree.
+
+Both are closed, and the second was worse than the hand check found. Checked 2026-08-27 the table
+was missing four rows; measured 2026-08-29 against the derived graph it was missing **nine**
+(`brief`, `explain`, `glossary`, `links`, `obligations`, `owners`, `provenance`, `scaffold`,
+`usecases`) and carried a false `Depends on` cell in **eleven more** — `core/c4/` claimed to depend
+on nothing while importing `repo` and `kernel`. That is the difference the item was written to buy:
+a hand check finds what a reader happens to look at, and a derived one finds the column nobody
+re-read. DESIGN carries 26 numbered rules under `## Rules`, plus two more in the package-layout
+section.
+
+What does not fit is larger, and pretending otherwise would be the failure this document is written
+against. loam is one CLI, not a fleet: there is no service topology, no OpenAPI, no AsyncAPI and no
+authorization vocabulary, so the `operationId` spine, the message spine and `Requires:` have nothing
+to join. Roughly half of `validate`'s checks would be permanently silent, and a check that is silent
+because nothing asked it must never be read as a check that passed. The evidence axis is worse:
+loam's own tests are vitest, not cucumber, so every scenario claim would be `attested` and never
+`verified` — the distinction loam exists to make would be the one property self-hosting does not
+exercise. Building a vitest-to-cucumber-JSON bridge to improve that number is precisely the invented
+need the non-goals below forbid — "an agent-confirmed scenario does not become verified merely to
+make a gate green" — and if such a bridge ever lands it must be because someone's fleet needed it.
+
+One layout constraint is settled rather than open. `loam.json` is in
+[.gitignore](https://github.com/ybotok/loam/blob/main/.gitignore) at the root and no root config is
+committed: one there governs every directory beneath it, this whole clone included. The self-docs
+therefore live under a subdirectory carrying its own config — `meta/loam.json` over `meta/docs/` —
+which works because config discovery walks upward from the cwd, and it is the shape
+[`examples/docs/`](https://github.com/ybotok/loam/tree/main/examples/docs) now carries too.
+
+**Self-hosting is not external evidence.** A repository maintained solely for loam is one operator
+by construction, so nothing here substitutes for proof from fleets that are not loam's own. That is
+not an obstacle to route around; it is the reason this item is written separately. This buys daily
+pressure on loam's own seams — a different kind of evidence.
+
+The recommended first step is the architecture axis only:
+
+- `meta/docs/` holding one landscape whose elements are loam's own source packages and whose edges
+  are the real import edges
+  [scripts/package-graph.mjs](https://github.com/ybotok/loam/blob/main/scripts/package-graph.mjs)
+  already computes.
+- One service, `loam`, whose `arch.spec.md` carries DESIGN's numbered rules as requirements with
+  `Covers:` lines onto that model.
+- `loam validate --all` running in CI beside `npm run arch:check`, in
+  [.github/workflows/ci.yml](https://github.com/ybotok/loam/blob/main/.github/workflows/ci.yml).
+
+**Landed.** `meta/docs/` holds a landscape whose 70 containers are the top-level subjects of `src/`
+and whose 403 relationships are the real value imports, and `services/loam/arch.spec.md` carries
+fourteen of DESIGN's numbered rules as requirements with `Covers:` lines onto real model objects.
+`npm run meta:check` runs in CI beside `npm run arch:check`. Each exit criterion, discharged:
+
+- **It convicted drift `arch:check` cannot see, and the drift is fixed here.** Nine missing
+  package-layout rows and eleven false `Depends on` cells; a DAG-levels table that placed `verify/`
+  below `gherkin/`, which it imports; a "7-level DAG" that is ten levels per package and eleven per
+  file; DESIGN's register-call sentence reading 27/28 against a tree of 28/29 — **whose pin in
+  `test/docs-facts.test.ts` had never once matched**, because it required a literal space where the
+  page wraps. That loop now runs over the flattened text and asserts the sentence is present before
+  grading it. And two mutual dependencies between top-level subjects that `arch:graph` cannot see at
+  all, because it keys on the full relative directory so `core/c4/project` and `core/c4` are
+  different nodes: `core/c4` ↔ `core/repo` and `core/repo` ↔ `core/provenance`. Both are hub moves
+  under the `git mv`-in-its-own-commit obligation, so they are **qualified rather than broken** —
+  DESIGN now names which granularity is checked and by what, and `scripts/self-model.mjs` holds them
+  in an `ACCEPTED_CYCLES` baseline that may only shrink. Breaking them is the follow-up.
+- **Nothing exists only to make a check fire, and here are the families that stay silent.**
+  `meta/docs` declares no `openapi.yaml`, `asyncapi.yaml`, `permissions.yaml`, `capabilities.yaml`,
+  `health.yaml`, no `sources:`, no `dynamic view` and no feature in flight — so `api.*`, `event.*`,
+  `spine.*`, `permissions.*`, `capability.*`, `health.*`, `usecase.*`, `obligation.*`, `link.*`,
+  `glossary.*`, `delta.*`, `openapi.*`, `asyncapi.*`, `archedge.*` and every `verify`/`vouch` claim
+  family are silent because nothing asked them. A green run here is two `ok` findings and two
+  `warn`s. It is not a fleet's worth of coverage and must not be read as one; the same list opens
+  `services/loam/arch.spec.md`, so a reader of the tree hits it before the requirements.
+- **The CI cost is measured**: `npm run meta:check` is 149/149/159 ms over three runs on the Linux
+  gate host — about a fifth of the 671/707 ms `npm run arch:check` it sits beside — plus 1.11 s of
+  test time for `test/self-model.test.ts`, which runs in parallel inside the suite.
+- **No root `loam.json` is committed.** `.gitignore`'s pattern was unanchored and so ignored a file
+  of that name at ANY depth, `meta/loam.json` included; it is now `/loam.json`, a developer's own
+  local pointer at the root is still ignored, and a committed one in a subdirectory is not.
+- **Every scenario claim stays `attested`** — vacuously, and that is worth saying rather than
+  ticking. The model produces **zero** claims: claims come from features, and there is no feature.
+  Nothing was built to convert one, and nothing could have been.
+
+What the axis found about the PRODUCT, which is what it was built to buy:
+
+- **A docs repo cannot describe a source tree above its own `loam.json`.** `repoDir` is the cwd only
+  when the config's own `service` field matches, and `meta/loam.json` sits below the tree it
+  describes, so the only spelling that reaches `src/` is `../src/` — which `sources.path-outside`
+  correctly refuses. There is no spelling that works. Provenance is dark, `loam vouch` has nothing
+  to stamp, and maturity is capped below `sourced`. That is why the pinned warning count is two.
+- **`c4.uncovered` has no living scope.** It grades only what a FEATURE DELTA introduces, so with no
+  feature open, 70 containers and 403 edges raise nothing. `covers.unknown` proves the `Covers:`
+  lines resolve and says nothing about what is left over. `obligation.uncovered` is the shape that
+  would answer this over a living map; this tree declares no obligations yet.
+- **The fleet scorecard counts service-LEVEL elements**, so a 70-box model reports
+  `c4: {elements: 1, covered: 0}` — correct by its own definition and badly misleading here.
+- **`services/core/` + `services/commands/` is unspellable, not merely unwise**: the one flat
+  namespace for subsystem names and service ids collides on eleven leaf names. Nesting inside one
+  bound system is what keeps `landscape.service-undocumented` correctly quiet, but it means the
+  service census answers "1" and every `landscape.*` shape advisory walks a set of one.
+- **`agents.stale` will fire on loam's own docs repo at the next version bump**, because
+  `meta/docs/AGENTS.md` carries a generated-by stamp. That is the axis working — daily pressure on a
+  seam — and it is now a release-checklist item: re-stamp the file and update the pin.
+  `examples/docs` has no `AGENTS.md`, so nothing had ever surfaced this.
+- **And `agents.stale` is graded on the STAMP, not the content**, which the same file then
+  demonstrated: `meta/docs/AGENTS.md` was already behind `src/` — by the AsyncAPI and OpenAPI merge
+  sections, before this change added two more — and every command reported the repo healthy, because
+  the version in the stamp still matched. A docs repo whose `AGENTS.md` was generated by THIS version
+  and has since been left behind by a same-version change is silently wrong, and there is no check
+  that can see it. The file is regenerated here; what would close it properly is a content digest
+  beside the stamp, which is a real design question (an AGENTS.md a fleet has edited by hand is a
+  supported state, and a digest would convict it) and is not attempted.
+- **`loam init` writes agent tooling into the cwd**, so a self-model directory inside a repository
+  that already has `.claude/` gets a duplicate set. `--no-commands --no-skills` is the escape hatch
+  and it works, but "the docs tree" and "this repository's agent tooling" are one command today.
+
+### The forward flow on loam's own repository — TRIED, then ADOPTED
+
+Whether loam's own changes go through `loam new`, `loam delta`, `loam archive` and `loam verify` per
+feature was the one question this section left open, because it is a far larger process commitment
+than one modeled axis: it changes how every change to this repository is WRITTEN rather than how one
+property of it is checked. It was first run as an experiment, on a throwaway copy of `meta/`, against
+the use-case work in this same change — and then taken as a decision.
+
+**What was adopted, and it is deliberately not "everything through the flow".** The maintenance
+obligations are unconditional and are now in the gate: `npm run meta:check` after any change that
+moves an import between two top-level subjects, and `npm run meta:agents` after any edit to the
+sections that generate a docs repo's `AGENTS.md`. The forward flow itself is for a change somebody
+should be able to read back as a DECISION — a new subject, a seam moved, a rule added to DESIGN —
+and a one-line edge stays a direct edit. `AGENTS.md`'s "The self-model" section states the rule and
+the `self-model` skill carries the commands, the frictions and the silent-check list.
+
+**Mechanically it works, end to end and with no special-casing.** `loam new FEAT-1 --touches loam`
+scaffolded the feature; the C4 delta re-declared the four containers its new edges join and tagged
+the edges `#FEAT-1`; the architectural requirement went into `specs/loam/arch.spec.md` as an
+`## ADDED Requirements` delta; `loam validate --feature` passed; `loam archive` merged four
+relationships into the landscape and the requirement into the living `arch.spec.md`. The archived
+result was compared against the same two edits made BY HAND, and the edge sets are identical.
+`npm run meta:check` reports the written model describes the tree either way.
+
+**Four things the trial found, and each is the axis earning its keep rather than an obstacle:**
+
+- **`loam delta` printed `Covers:` twice.** A directive line is a body line — `core/document/parse.ts`
+  keeps it in `text` so a requirement round-trips and its digest stays stable — and the briefing
+  printed the body verbatim AND the parsed field underneath. So `Operations:` and `Covers:` showed
+  twice while the five directives with no such re-print showed once. Fixed and pinned in this
+  change. Nothing had caught it because the human view is asserted almost nowhere and the
+  duplication is invisible on a requirement carrying neither line.
+- **The scaffold's delta template assumes a fleet of top-level systems.** It offers
+  `x = softwareSystem 'x'` and an edge between two of them; the self-model is 70 nested `container`s
+  inside one bound system, so every line of the template has to be deleted and the nesting
+  re-declared by hand. Not wrong — the template is written for loam's distributed-system entry
+  path — but the first feature in a nested single-boundary model costs a read of
+  `landscape.likec4` to find out.
+- **`loam new` scaffolds the BUSINESS axis and the self-model has only the architectural one.**
+  `specs/loam/spec.md` arrives and has to be deleted, and `specs/loam/arch.spec.md` written by hand;
+  there is no `--arch` to say which axis a feature is about.
+- **The arch-edge coverage line reads `loam → loam` once per edge**, because every edge is between
+  two containers inside one bound system. Correct by its own definition, and useless here — the same
+  shape as the fleet scorecard reporting `c4: {elements: 1}` over a 70-box model, already recorded
+  above.
+
+**What it still cannot buy is the evidence axis, and that is unchanged.** loam's tests are vitest,
+not cucumber, so `loam verify` would record every scenario claim as `attested` and never `verified`
+— the distinction loam exists to make is the one property self-hosting does not exercise. Building a
+vitest-to-cucumber-JSON bridge to improve that number remains the invented need the non-goals forbid.
+
+The cost was always process rather than capability, and the trial confirmed it: nothing prevents the
+flow, and the frictions are four rough edges in a scaffold written for a fleet of top-level systems.
+The decision taken is to pay that cost for changes worth reading back as decisions, and to make the
+two maintenance obligations unconditional — which is the half that had already been failing silently,
+twice, before anybody chose anything.
+
+**One thing this does NOT change.** A repository maintained solely for loam is one operator by
+construction, so nothing adopted here counts as external evidence for a `## Later` item. That was the
+reason this section sits apart from the promotion rules, and adopting a process inside it does not
+move that line.
+
+## Non-goals
+
+- No hosted control plane, server, database, background synchronizer, or network-owned source of
+  truth.
+- No code extractor or generated architecture presented as truth. Agents may read and propose; loam
+  owns deterministic questions, formats, and checks.
+- No full OpenSpec clone, bidirectional OpenSpec writer, or claim of compatibility beyond the exact
+  pinned corpus and explicitly supported Markdown grammar.
+- No replacement for LikeC4's renderer, the forge's ownership/review controls, or a service's
+  contract and test tooling.
+- No weakening of attested-versus-tested evidence: an agent-confirmed scenario does not become
+  verified merely to make a gate green.
+- No runtime dependency added to avoid implementing a small invariant with Node and the existing
+  stack.
+- No workspace split, barrel exports, command-oriented vertical slices, or architectural rewrite for
+  aesthetics. The single binary and acyclic source-package tree remain deliberate.
+- No silent break to commands, flags, exit codes, JSON envelope fields, stable codes, or the
+  plain-file formats users already commit.
+- No schedule inferred from section order. Priority says what must become true first; evidence
+  decides when it is true.