@ybotok/loam 0.2.0-alpha.6 → 0.2.0-alpha.9

package/ROADMAP.md

@@ -18,19 +18,19 @@ 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 **464 TypeScript modules in 143 source packages**, with an acyclic package graph
+The tree contains **500 TypeScript modules in 155 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 **173 test files**. Those four counts are deliberately stated OUTSIDE the
+CLI exposes **30 commands** from [src/cli.ts](https://github.com/ybotok/loam/blob/main/src/cli.ts),
+and the suite stands at **190 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-04 at `0.2.0-alpha.6`, and dated because neither number has a cheap derivation:_
+_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,772/3,772 tests**, with two `skipIf(asRoot)` cases the root gate container cannot run; the
-coverage gate passing with **92.78% statements, 84.65% branches, 97.08% functions, and 94.63%
+**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.
 
@@ -128,10 +128,57 @@ Closed since the 2026-08-18 assessment, each with the commit or commit range tha
 `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, which open the list — 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.
+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
 
@@ -193,7 +240,9 @@ merged map before writing either. Second, the consumer census read `architecture
 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. Third, the wiring guard this entry landed
+`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
@@ -675,6 +724,54 @@ item gets promoted — it went from here to `## Now` and from there to
   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