@ybotok/loam 0.2.0-alpha.2 → 0.2.0-alpha.5

package/CHANGELOG.md

@@ -10,6 +10,130 @@ case for a change — the alternative that was rejected, the defect it came from
 generalises — lives where it is maintained: [SCHEMA.md](SCHEMA.md) for the rule,
 [ROADMAP.md](ROADMAP.md) for the priority and its exit criteria, and the commit that landed it._
 
+## [0.2.0-alpha.5] - 2026-09-03
+
+An adopted service's model renders from the docs root. Still a prerelease on the `alpha` line:
+`npm i @ybotok/loam@alpha` installs it. Nothing below is breaking. What a repo with adopted services
+NOTICES: one `service.likec4-config-missing` warning per service on its first `validate --all`
+until one `loam subsystem sync`, and from that sync on `--project` for `likec4 validate` at the
+docs root.
+
+### Added — an adopted service's model renders from the docs root
+
+The root `likec4.config.json` excludes `services/**`, and has to; what that cost was never stated:
+an adopted service's `model.likec4` — the artifact `loam adopt` spends the most effort on — was a
+box on the fleet map with nothing renderable inside it in the renderer opened at the docs root, and
+the only documented way to see its containers was one `npx likec4 start services/<id>` per service.
+One problem report; one file per service closes it.
+
+- `loam subsystem sync` now writes `services/<…>/<svc>/likec4.config.json` beside every service
+  `model.likec4` that has none, whenever the root `likec4.config.json` exists — **create-only**: a
+  file that exists is yours and is never compared, rewritten or removed. Measured at the pinned
+  likec4, a project file inside a service directory registers the model as a project of its own
+  regardless of the root's exclusion, so `npx likec4 start` at the docs root shows `fleet` plus one
+  project per service. Without the root file nothing is written and the text says `loam doctor`
+  prints it. `subsystem sync --json` carries an additive `projects` key, `{ root, created, current }`
+  — whether the root file exists, the repo-relative paths written this run (sorted by id), and how
+  many model-bearing services already had one. `action` still describes
+  `architecture/subsystems.likec4` alone.
+- `loam validate --all` gains one warning per service, `service.likec4-config-missing`, on the
+  `landscape` target with the service's tree path as its `scope`: `model.likec4` exists and the
+  project file does not. Never an error, never gating, never in `--service`, `status` or `doctor`;
+  the fix is `loam subsystem sync`, never a hand-written file. `doctor.likec4-config-missing`'s fix
+  text now hands over to `sync` once the root file is written.
+- The project name: the id with every `.` folded to `-` (LikeC4's name grammar refuses the byte),
+  prefixed `service-` when that would equal the root project's `fleet` or LikeC4's reserved
+  `default`; `title` is the id verbatim, and the title is what the renderer's picker shows. Not
+  injective — an id spelled billing.core beside one spelled billing-core, or `service-fleet` beside
+  `fleet` — and LikeC4 suffixes the later one `-1`; disclosed, never graded.
+
+What a repo NOTICES on upgrade: one warning per adopted service on the first `validate --all` until
+one `loam subsystem sync` — under `--strict`, CI is red until then; after that `sync`, N untracked
+files (`sync` does not `git add` them) and `move-uncommitted` on the next `loam subsystem move` of
+such a service until they are committed; from the first `sync` on, `likec4 validate` at the docs
+root needs `--project <name>` (measured: with more than one project it refuses bare, while
+`likec4 build` and `likec4 export` take every project and need no flag); and the renderer's project
+list grows by one per adopted service, beside `fleet`. No command, flag, exit code or envelope key
+changes; `projects` is additive.
+
+## [0.2.0-alpha.4] - 2026-09-03
+
+The view title becomes the subsystem's path. `0.2.0-alpha.3` was tagged and **never published** — it
+was withdrawn before its publish step for a reason unrelated to the code — so this is the release
+that carries both it and the entry below, and `npm i @ybotok/loam@alpha` moves from `0.2.0-alpha.2`
+straight to this one. A repo upgrading from either reports one `subsystem.views-stale` until one
+`loam subsystem sync`.
+
+### Changed — a generated subsystem view is titled by its path
+
+`0.2.0-alpha.3` gave each view the subsystem's own label. It now carries the whole path — every
+marked ancestor's label and its own, joined with ` / `, so `services/platform/order-flow` reads
+`Platform / Order flow`. Measured against the pinned likec4: the renderer reads that as a folder
+path, so the view list mirrors the directory tree a human already navigates — one folder per
+ancestor, the leaf's own label as the title — and two subsystems whose labels are equal are told
+apart by their parents instead of appearing twice under one name. The box a view draws keeps the
+subsystem's own label, unprefixed.
+
+Because loam is now the one composing with `/`, it owns what a `/` inside an authored label would
+do: measured, LikeC4 would show only the last segment and add a folder level the tree does not have,
+so a slash in a marker's `title` becomes `∕` (U+2215) and the whole authored label stays visible as
+one folder name. The alternative — a fixed `loam subsystems /` prefix — bought the same folder
+without the churn and put loam's own name in a reader's UI; the tree's own words won.
+
+Two costs, both real: the generated bytes move again, so a repo upgrading from `0.2.0-alpha.3`
+reports one `subsystem.views-stale` until one `loam subsystem sync`; and renaming a PARENT's title
+now rewrites the bytes of every view beneath it.
+
+## [0.2.0-alpha.3] - 2026-09-03
+
+The generated subsystem views, made readable — and the defect that hunt found underneath them.
+Still a prerelease on the `alpha` line: `npm i @ybotok/loam@alpha` installs it. Nothing below is
+breaking, and one entry is a change every repo NOTICES: the generated file's bytes move, so the
+first `loam validate --all` after upgrading asks for one `loam subsystem sync`.
+
+### Fixed — a `subsystem.views-stale` no command could clear
+
+`loam validate --all` grades `architecture/subsystems.likec4` against the whole `architecture/`
+project — the landscape merged with every `architecture/usecases/*.likec4` — while `loam subsystem
+sync` and the write verbs rendered it from `landscape.likec4` alone. One use-case document declaring
+an element bound to a filed service was therefore enough to make `sync` answer `current` while
+`validate --all` exited 1 with `subsystem.views-stale`, whose message names `sync` as the repair.
+Reproduced on `examples/docs`; the two now read the same documents. No code, flag or payload key
+changes.
+
+### Changed — the generated subsystem views carry a label and a boundary
+
+`architecture/subsystems.likec4` exists only to be rendered, and in the renderer its views were the
+least readable objects in a docs repo: no title, so LikeC4 showed the hex-escaped id
+(`subsystem_platform__order_2dflow`), and leaf includes only, so a fleet drawn as ordinary
+grouped C4 rendered flat. Every view now carries `title` (the marker's, or the directory name) and
+`description` when the marker authors one, and draws a boundary: the model's own containing element
+when one holds exactly the subsystem's members, a `group '<title>'` mirroring the directory subtree
+when the landscape nests nothing, and — when the members are nested but no element owns exactly them
+— no box plus one comment line, `// model: no boundary — …`, which is loam's whole answer to a tree
+and a map that disagree. Nothing grades that comment: placement still carries no policy.
+
+Marker text is normalized to one line and escaped before it is written (measured: a raw `'` in a
+title is two parse errors and blanks the fleet's whole map in the renderer; `Ops' } view evil {` is
+zero errors and injects a view). [SCHEMA.md](SCHEMA.md) states the rules.
+
+What a repo notices, and what it costs:
+
+- the first `loam validate --all` after upgrading reports exactly one `subsystem.views-stale` error
+  (exit 1) until one `loam subsystem sync` runs. `sync` does not `git add`, so the repair leaves one
+  unstaged one-file diff to commit;
+- the boundary depends on which OTHER services sit under an element, so an unrelated adoption or
+  archive can flip a view from boxed to flat and restale the file. `loam archive` now withholds its
+  "living spec + landscape are now complete + current" line, prints one warning naming
+  `loam subsystem sync`, and adds `subsystemViewsStale: true` to its `--json` payload when it left
+  the file behind;
+- `subsystem.views-stale` and `subsystem.view-id-collision` now carry `locations`: the generated
+  file (or `architecture/` when it does not exist yet) and the claimant document respectively. Both
+  used to fall back to the landscape, sending an editor to a file with nothing to fix in it.
+
+No command, flag, exit code, envelope key or stable code string changes; `subsystem.views-stale` is
+not in the `IssueCode` union and carries no `gates` key, so `loam archive` remains unaffected by it.
+
 ## [0.2.0-alpha.2] - 2026-09-02
 
 The deployment axis, and the two defects the axis surfaced on its way in. Still a prerelease on the

package/MIGRATING-from-OpenSpec.md

@@ -312,7 +312,10 @@ services, loam frontmatter, Operations/Covers links and feature identity still r
   specs intentionally remain `status: draft`.
 - `Operations:` links to provider OpenAPI `operationId`s, and `Covers:` links where architecture
   requirements are created.
-- `architecture/landscape.likec4`, service `model.likec4`, and explicit fleet relationships.
+- `architecture/landscape.likec4`, service `model.likec4`, and explicit fleet relationships — then
+  `loam subsystem sync`, which writes each model's `likec4.config.json` (the staged repo already
+  carries the root one) so the models render beside the map; `validate --all` warns
+  `service.likec4-config-missing` for any model still without one.
 - Service OpenAPI contracts and provider-before-consumer sequencing where inbound edges already name
   operations.
 - LikeC4 and OpenAPI deltas for the already mapped active feature ids (`FEAT-12`, `BUG-42`, and so

package/README.md

@@ -5,13 +5,14 @@
 ![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
 ![node: >=22.22.3](https://img.shields.io/badge/node-%3E%3D22.22.3-brightgreen.svg)
 [![CI](https://github.com/ybotok/loam/actions/workflows/ci.yml/badge.svg)](https://github.com/ybotok/loam/actions/workflows/ci.yml)
-[![npm](https://img.shields.io/npm/v/@ybotok/loam.svg)](https://www.npmjs.com/package/@ybotok/loam)
+[![npm](https://img.shields.io/npm/v/@ybotok/loam/alpha.svg?label=npm%20alpha)](https://www.npmjs.com/package/@ybotok/loam)
 
-> **Pre-release: `0.2.0-alpha.2`**, the second release of the 0.2 line and the newest published
+> **Pre-release: `0.2.0-alpha.5`**, the fourth published release of the 0.2 line and the newest published
 > version of [`@ybotok/loam`](https://www.npmjs.com/package/@ybotok/loam). It publishes under the
-> `alpha` npm dist-tag: `npm i @ybotok/loam@alpha`, or the exact version, always installs this
-> line. `latest` is moved onto a release by hand once it has published, so a plain
-> `npm i @ybotok/loam` may still resolve to `0.1.0-beta.3` until it is. See [Status](#status).
+> `alpha` npm dist-tag — which is what the badge above reads: `npm i @ybotok/loam@alpha`, or the
+> exact version, always installs this line. `latest` is moved onto a release by hand once it has
+> published, so a plain `npm i @ybotok/loam` resolves to an earlier release until it is moved. See
+> [Status](#status).
 
 `loam` keeps an authored C4 model, requirements, API and event contracts, permissions, domain
 vocabulary and verification evidence in explicit agreement as a system changes. The same lifecycle
@@ -486,7 +487,7 @@ always preserved byte for byte, with the entry printed for manual merge.
   maps, what is lost, what must be added.
 - [ROADMAP.md](ROADMAP.md) — the evidence-backed improvement plan, priorities, non-goals and exit
   criteria.
-- [CHANGELOG.md](CHANGELOG.md) — released beta.1–alpha.2 plus the changes on `main` under
+- [CHANGELOG.md](CHANGELOG.md) — released beta.1–alpha.5 plus the changes on `main` under
   `[Unreleased]`.
 - [docs/BENCHMARKS.md](https://github.com/ybotok/loam/blob/main/docs/BENCHMARKS.md) — what a
   fleet-sized run costs, with the method, the machine and the committed runs behind every number.
@@ -520,14 +521,14 @@ component baselines, the `architecture/permissions.yaml` authorization vocabular
 authored-capability axes with the `Realizes:` join, use cases graded as `dynamic view`s, the
 `glossary/<term>.md` domain vocabulary checked through the links that cite it, and the
 `architecture/obligations.yaml` architectural obligations checked through `#obl-` tags and
-`Covers:`. Known limits, each with its owner in [ROADMAP.md](ROADMAP.md): the complete gate still
-needs repeatable CI and installed-package evidence observed from an actual push. Speculative
-`render`, health composition and UI generation come later. Behind that status stand **157 test files** (counted 2026-09-02): the count is graded
+`Covers:`. Known limits, each with its owner in [ROADMAP.md](ROADMAP.md): the scheduled CI
+`stability` job has still to be observed green. Speculative `render`, health composition and UI
+generation come later. Behind that status stand **159 test files** (counted 2026-09-02): the count is graded
 against a live readdir by `test/docs-facts.test.ts`, so this sentence fails the suite the moment it
 trails the tree.
 
 The package is published as [`@ybotok/loam`](https://www.npmjs.com/package/@ybotok/loam), currently
-`0.2.0-alpha.2`: the unscoped `loam` name is taken by an unrelated GDAL wrapper, so the package ships
+`0.2.0-alpha.5`: the unscoped `loam` name is taken by an unrelated GDAL wrapper, so the package ships
 under the maintainer's own npm user scope. Releases are tag-driven and maintainer-only
 ([CONTRIBUTING.md](CONTRIBUTING.md)); the version this line names is pinned to `package.json` by a
 drift test, so it cannot silently trail a release.

package/ROADMAP.md

@@ -1,6 +1,6 @@
 # Roadmap
 
-_Assessed 2026-09-02._
+_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,27 +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 **424 TypeScript modules in 129 source packages**, with an acyclic package graph
+The tree contains **429 TypeScript modules in 130 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 **157 test files**. Those four counts are deliberately stated OUTSIDE the
+and the suite stands at **159 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-02 at `0.2.0-alpha.2`, and dated because neither number has a cheap derivation:_
+_Measured 2026-09-03 at `0.2.0-alpha.5`, 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,399/3,399 tests**, with two `skipIf(asRoot)` cases the root gate container cannot run; the
-coverage gate passing with **92.25% statements, 84.04% branches, 96.62% functions, and 94.18%
+**3,434/3,434 tests**, with two `skipIf(asRoot)` cases the root gate container cannot run; the
+coverage gate passing with **92.30% statements, 84.11% branches, 96.64% functions, and 94.24%
 lines** against its thresholds of 91 / 82 / 95 / 93; and `npm run release:check` plus
 `npm run test:package` green against the real tarball.
 
-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
+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
@@ -103,12 +106,15 @@ has landed (see [Recently landed](#recently-landed)) — the authored business a
 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, unchanged
+### 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 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.
+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
@@ -125,6 +131,72 @@ changes, exit criteria, and what each review surfaced — are in this file's his
 working tree and not committed, and the range goes in with the commit rather than being guessed at
 here.
 
+#### 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.
+
+#### 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.
+
 #### 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
@@ -345,10 +417,24 @@ 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.
+- **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.
 - **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

package/SCHEMA.md

@@ -72,6 +72,7 @@ docs/
   glossary/<term>.md                 the system's domain vocabulary, one file per term; nesting allowed [authored, opt-in]
   services/<svc>/                    at the root (unfiled), or inside subsystem directories at any depth
     model.likec4                        boundary C4 (containers/components) [adopt]
+    likec4.config.json                  one LikeC4 project per service model, create-only  [GENERATED: loam subsystem sync]
     spec.md                          living requirements (Requirement/Scenario)  [adopt]
     arch.spec.md                     living ARCHITECTURE requirements (outbox, retries, alerts; Covers:)  [authored]
     openapi.yaml                     API contract                        [adopt / authored]
@@ -164,14 +165,84 @@ check uses; a member nothing models is omitted, which `landscape.service-unmodel
 reports). The output is deterministic and line-oriented — subsystems sorted by path, members by id,
 one `include` per line, no timestamps, no absolute paths — so it is byte-reproducible on any machine
 and two concurrent moves into different groups merge in git without intervention.
+
+Each view carries the **label a human reads**: `title`, and `description` when the marker authors
+one. The title is the subsystem's **path** — every marked ancestor's label and its own, joined with
+` / `, so `services/platform/order-flow` reads `Platform / Order flow` — and each label is the
+marker's `title`, falling back to the directory name (an unlabelled view is shown by its id, which
+is hex-escaped for injectivity and reads as `subsystem_platform__order_2dflow`). LikeC4
+reads that path as folders: the view list mirrors the directory tree, showing one folder per
+ancestor and the leaf's own label as the title. A `/` **inside** a label becomes `∕` (U+2215), so an
+authored slash can neither hide half of what somebody wrote nor invent a folder level the tree does
+not have. Both strings are somebody's prose written into syntax, so both are normalized to one line
+and escaped. Titles are not unique — only ids are — and renaming a parent's title rewrites every
+view beneath it.
+
+The **boundary** each view draws is a fact about the landscape, never a setting:
+
+1. an element that holds *exactly* the subsystem's members and nothing else is included beside the
+   leaves, so the renderer nests them in the box the author drew, under the author's title;
+2. a landscape that nests nothing puts the services in a `group '<title>'` of loam's own, mirroring
+   the directory subtree, so a parent subsystem shows its children as boxes rather than one pile;
+3. members that ARE nested with no element owning exactly them get no box and one comment line —
+   `// model: no boundary — <id> also holds services outside this subsystem.` — because a synthetic
+   box would look identical whether or not the tree and the map agree. That comment is the whole of
+   what loam says about the two disagreeing: nothing grades it, nothing fails on it, and it lands in
+   the diff of the commit that caused it. **The tree and any `group` nesting in the landscape stay
+   independent**; `loam subsystem move` never rewrites the map, and no finding compares them.
+
+Because the boundary depends on which *other* services sit under an element, an unrelated adoption
+or archive can flip a view from boxed to flat — a new reason to see `subsystem.views-stale`, and why
+`loam archive` withholds its "complete + current" line and names `loam subsystem sync` when it left
+the file behind.
+
 `loam subsystem sync` is the one regenerator (it also *removes* the file when the tree has no
 subsystems), every `loam subsystem` write verb regenerates it inside the same transaction, and
-`validate --all` grades staleness by **byte comparison** — exactly one error,
+`validate --all` grades staleness by **content comparison** (line endings normalized; a CRLF
+checkout changes no fact) — exactly one error,
 `subsystem.views-stale`, on exactly that file; nothing in loam ever parses it: a views-only document
 does not parse standalone (its `include` lines reference elements the landscape defines), and it
 holds **static** views, whose contents loam never reads in any document. Only the LikeC4 renderer,
 which merges the whole `architecture/` project, resolves its includes.
 
+The tree's **second renderer file** is per service — `services/<…>/<svc>/likec4.config.json`,
+which `loam subsystem sync` also writes, beside every `model.likec4` that has none. The root
+project is scoped to `architecture/` and excludes `services/**`, and must be, since each model
+declares its own `specification` block; what that exclusion cost went unstated for a release: an
+adopted service was a box on the fleet map with nothing renderable inside it. Measured at the
+pinned likec4, a project file INSIDE a service directory is registered as a project of its own
+regardless of that exclusion, so one `npx likec4 start` at the docs root loads `fleet` plus one
+project per service, each carrying LikeC4's own `index` view of the containers beside the authored
+one, and a model that does not parse breaks only its own project. The file is **create-only** —
+never compared, never rewritten, never removed — under the root config's ownership rule, not the
+views file's: there is no `-stale` grade because nothing can make it stale. Its bytes are a
+function of the id alone (two keys, `name` and `title`), so placement never changes them and a
+`subsystem move` carries the file with no write of its own — it rides inside the rename the move's
+transaction already journals (in a git-backed repo, commit the files `sync` wrote first: `move`
+refuses over untracked paths, `move-uncommitted`); a compare would only fight the keys LikeC4 lets a
+team add (`title`, styles). `name` is the id with every
+`.` folded to `-` (LikeC4's name grammar refuses the byte; loam's id grammar admits it), prefixed
+`service-` when the result would equal the root project's `fleet` (a nested project of that name
+is silently registered as `fleet-1`) or LikeC4's reserved `default`; `title` is the id verbatim,
+and the title is what the renderer's project picker shows. The name is **not injective**, and
+that is disclosed rather than escaped away: an id spelled billing.core beside a service literally
+named billing-core, or `service-fleet` beside `fleet`, share a name and LikeC4 suffixes the later
+one `-1`; no loam
+finding grades it, because the picker still reads the id. Order is a gate — the root file first
+(`loam init --create` writes it, `loam doctor` prints it), then `sync`: without the root file
+nothing is written and the text output says so. No model, no file: a spec-only service is owed
+nothing and gets its file on the first `sync` after its model lands. No legal id, no file either: a
+directory whose name breaks the service-id grammar (`service.id-invalid`) would get a `name` the
+renderer silently drops, and a create-only file the renderer ignores would silence the grade for
+good, so `sync` skips it and the rename that clears `service.id-invalid` earns the file. A file left behind by a
+deleted model is the team's and harmless (measured: a nested project holding no `.likec4` file is
+absent from the project list). `validate --all` grades presence only — one warning per service,
+`service.likec4-config-missing`, on the fleet `landscape` target, never an error, never in
+`--service`, `status` or `doctor`; the fix is `loam subsystem sync`, never a hand-written file. A
+feature's `delta.likec4` is deliberately out of scope: the directory is transient and
+`loam archive` moves it where a project file would still be registered, so every shipped feature
+would keep a dead project in the list forever.
+
 A move is **one journaled transaction over N directory renames plus the regenerated views file**
 (`loam subsystem move <name>... --into <sub|.>`; `rename` is a one-rename move; whole subtrees move
 as one rename). It refuses only when git reports uncommitted changes under a directory being moved
@@ -2263,9 +2334,17 @@ through the forge, not through loam features:
   **parsed** model and never computes a view — it reads what a view **declares** (a `dynamic view`'s
   tags and ordered steps, already materialized by the parse loam pays for) and never what a view
   **shows**. It renders nothing, and view *computation* is what is superlinear in edges. (If you
-  want diagrams, add a `views` block and render it with LikeC4's own tooling — `npx likec4 start` in
-  the docs repo for the fleet map, `npx likec4 start services/<id>` for one service model — and
-  scope the views, because an `include *` over a fleet-sized landscape takes minutes. `loam init`
+  want diagrams, add a `views` block and render it with LikeC4's own tooling — `npx likec4 start`
+  at the docs root, which renders the fleet map AND every adopted service's model, each as the
+  project its own `services/<svc>/likec4.config.json` declares (written by `loam subsystem sync`;
+  the Layout section has the rule), and `npx likec4 start features/<FEAT>` for a delta, which is
+  transient and gets no project — and scope the views, because an `include *` over a fleet-sized
+  landscape takes minutes. Two costs arrive with the first service project. Measured at the
+  pinned likec4: with more than one project, `likec4 validate` at the docs root refuses without
+  `--project <name>`, so a CI step that ran it bare changes (`likec4 build` and `likec4 export` take
+  every project and need no flag). And the renderer's project list grows by one per adopted service
+  beside `fleet` — LikeC4 projects are separate models, so a box on the fleet map is not a link into
+  that service's project. `loam init`
   scaffolds the landscape with no `views` block for that reason: loam should not plant a diagram it
   never draws **— and never asks for one: a fleet that draws nothing owes no views block.** It also
   scaffolds a `likec4.config.json` that scopes the root LikeC4 project to `architecture/`: loam
@@ -2524,9 +2603,9 @@ component-surface pins), `verify`,
 transactional `archive` / `unarchive`, `vouch`, and the OpenSpec audit/migration on-ramp are
 implemented, each with a `--json` contract.
 
-Known and unclosed, so nobody has to discover them: the complete gate still needs repeatable CI and
-installed-package evidence observed from an actual push, even though behavior, coverage and the
-local stress runner pass. Both contract axes now merge a components-only delta: a feature
+Known and unclosed, so nobody has to discover them: the scheduled CI `stability` job has still to be
+observed green, even though behavior, coverage, the installed-package smoke and the local stress
+runner all pass. Both contract axes now merge a components-only delta: a feature
 asyncapi.yaml declaring no channel/operation/message slot (`components.schemas`-only, say) merges
 the component surfaces it declares, pinned by the root `x-loam-baselines` record, and they enter the
 ref sweep like anything else the merge wrote — so a `$ref` whose target the delta itself defines

package/dist/commands/archive/run.js

@@ -15,6 +15,10 @@ import { message, quietPruneEmptyParents, quietRm, rollbackError, rollbackStaged
 import { clearCommitIntent, writeCommitIntent } from "../../core/staging/recovery/intent.js";
 import { SNAPSHOT_DIR, SnapshotClobberError, snapshotDir, writeSnapshot, } from "../../core/staging/snapshot.js";
 import { enumeratedServices } from "../../core/repo/service-target.js";
+import { listFleetTree } from "../../core/repo/repo.js";
+import { subsystemViewsPath } from "../../core/repo/paths.js";
+import { viewsState } from "../../core/repo/tree/render/stale.js";
+import { loadArchitecture } from "../../core/c4/project/architecture.js";
 import { FleetContext } from "../../core/fleet-context.js";
 import { gate } from "./plan/gate.js";
 import {} from "./plan/refusal.js";
@@ -227,8 +231,19 @@ export async function archiveLocked(config, featureId, opts) {
             : "";
         throw new ArchiveFailure(failures.length > 0 ? "rollback-incomplete" : "merge-failed", wrapped.message + kept);
     }
+    // This merge just changed the map, and the generated views file is a
+    // function of the tree AND the map: a delta whose element lands inside a
+    // group that exactly covered a subsystem takes that subsystem's boundary
+    // line away, and a delta binding an element to a filed service adds an
+    // include. Archive does not rewrite the file — `loam subsystem sync` owns it
+    // outright, and folding a second generated artifact into this transaction
+    // would mean archive computing the post-merge tree AND the post-merge map,
+    // which is how the two writers disagree — but it must not report a repo as
+    // current when the next `validate --all` will call it stale. Graded through
+    // validate's own function, so the two cannot answer differently.
+    const staleViews = await subsystemViewsStale(config.docsDir);
     if (json) {
-        emitJson(payload(true));
+        emitJson({ ...payload(true), ...(staleViews ? { subsystemViewsStale: true } : {}) });
         return;
     }
     console.log(`\n  archived: features/${dirName} → features/archive/${dirName}`);
@@ -239,14 +254,43 @@ export async function archiveLocked(config, featureId, opts) {
     // caller told it to merge past. Printing it over either is how a red fleet
     // gets reported as a finished one.
     const incomplete = planWarns.filter((w) => w.code === "service.no-model");
-    if (incomplete.length === 0 && overridden.length === 0) {
+    if (incomplete.length === 0 && overridden.length === 0 && !staleViews) {
         console.log("  living spec + landscape are now complete + current.");
         return;
     }
+    if (staleViews) {
+        console.log("  ⚠ architecture/subsystems.likec4 no longer matches the tree and this map — run `loam subsystem sync`.");
+    }
     for (const w of incomplete)
         console.log(`  ⚠ ${w.message}`);
     if (overridden.length > 0) {
         console.log(`  ⚠ merged past ${overridden.length} gating issue(s) with --approve — the living docs carry them now; \`loam validate --all\` says what they cost.`);
     }
 }
+/**
+ * Would the next `validate --all` report `subsystem.views-stale`?
+ *
+ * Asked through validate's OWN function rather than a second compare, so the
+ * warning archive prints and the error validate raises can never disagree —
+ * including about the gate validate holds: a map that does not parse is
+ * `landscape.invalid`'s business, and grading a generated file against a map
+ * nobody can read would cascade a second complaint behind the first. An
+ * unreadable map therefore answers "no claim", exactly as validate does.
+ */
+async function subsystemViewsStale(docsDir) {
+    try {
+        const doc = await loadArchitecture(docsDir);
+        if (doc.errors.length > 0)
+            return false;
+        const state = await viewsState(subsystemViewsPath(docsDir), await listFleetTree(docsDir), doc.elements);
+        return !state.agrees;
+    }
+    catch {
+        // Tolerant for the reason the snapshot resolver above is: a docs repo with
+        // no `services/` at all still archives a landscape-only feature, and this
+        // question is an ADVISORY printed after a commit that already succeeded.
+        // Nothing here may turn a landed archive into a non-zero exit.
+        return false;
+    }
+}
 //# sourceMappingURL=run.js.map