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

package/SCHEMA.md

@@ -89,24 +89,25 @@ docs/
     delta.likec4                     C4 delta (architecture)             [authored]
     specs/<svc>/spec.md              requirement delta (ADDED/MODIFIED/REMOVED + scenarios)  [authored]
     specs/<svc>/arch.spec.md         architectural requirement delta, same algebra  [authored]
-    specs/<svc>/openapi.yaml         the endpoints this feature adds     [authored]
-    specs/<svc>/asyncapi.yaml        the event-contract delta, slot-pinned  [authored]
+    specs/<svc>/openapi.yaml         only the endpoints it adds/changes/removes  [authored]
+    specs/<svc>/asyncapi.yaml        only the event slots it adds/changes/removes  [authored]
     capabilities/<cap>/spec.md       capability delta, same requirement grammar  [authored]
     glossary/<term>.md               a word this feature brings with it; create-only  [authored]
     usecases/<name>.likec4           a FLOW this feature brings; views-only, create-only  [authored]
     adrs/NNNN-*.md                   feature-level decisions             [authored]
-    verification.yaml                the done-check: claims + verdicts + evidence, one attestation per service  [loam verify --service <id> --record]
+    verification/<svc>.yaml          the done-check, one file per attesting service: claims + verdicts + evidence  [loam verify --service <id> --record]
+    verification.yaml                the same answered all at once, and every record from before the directory — read forever  [loam verify --record]
   features/archive/<FEAT>/           a shipped change — the same files, plus:
-    .loam-before/                    the bytes the merge overwrote        [written by loam]
+    .loam-before/                    the bytes the merge overwrote, and the checklist it shipped with  [written by loam]
   .loam-lock                         transient: one writer at a time      [archive/unarchive only]
   .loam-commit                       transient: the commit intent journal [archive/unarchive only]
 ```
 
 There is no `flows/` tree, and there will not be one. A cross-service **interaction flow** is a
 `dynamic view` under `architecture/` — the one place that already holds every cross-service edge —
-tagged with the capability it realizes. A flow that spans services does not belong under one
-service's directory, and the view's steps join to the landscape's own relationships, which is what
-makes the flow checkable rather than merely drawn.
+tagged with the capability it realizes, or with the suites it runs in (below). A flow that spans
+services does not belong under one service's directory, and the view's steps join to the
+landscape's own relationships, which is what makes the flow checkable rather than merely drawn.
 
 A flow that stays INSIDE one service — the hop sequence behind an arch.spec.md requirement whose
 `Covers:` names containers — cannot live under `architecture/`: loam parses that directory as its
@@ -147,6 +148,41 @@ would leave behind — so a flow may draw a hop into a service the feature's own
 and a hop into an element the merge does NOT land is refused at plan time rather than archived into
 a map the next reader's `loam validate --all` fails on.
 
+**A fleet flow can also say which SUITE it runs with: `#suite-<name>`.** A suite is a set of
+journeys a test run exercises together — a smoke suite, a payments suite — and a journey joins one
+by carrying the tag on its `dynamic view`, declared like every LikeC4 tag in the landscape's one
+`specification` block (`tag suite-smoke`), so a mistyped suite is a parse error rather than a second,
+empty suite. It is a SEPARATE prefix, not `#cap-`: a capability says what a flow is FOR, a suite says
+what it is RUN WITH, and membership is **many-to-many** — one view may carry several `#suite-` tags,
+and a suite holds as many views as carry its tag, which is why it is a tag and not a directory.
+
+**Tagging is the opt-in, and it grades.** A view carrying only `#suite-` tags — no `#cap-`, no
+`#req-` — IS a use case: every reader takes it (the predicate and the byte gate below now read three
+prefixes), and `loam validate --all` grades its hops like any other's (`usecase.step-unbacked`,
+`usecase.step-contested`, `usecase.step-unlinked`). A journey a test stand is provisioned from must
+be held to the model it is drawn over. The suite tag claims no capability and no requirement, so it
+earns nothing from the capability axis. An UNTAGGED view stays ungraded, exactly as before.
+
+`loam list suites [<name>] [--json]` is the answer the tag exists for: **which services must be up
+for suite X.** For each suite it lists the views carrying the tag, the enumerated services their
+steps resolve to — through the same element→service resolver the step grades use, so a step into
+one of order-service's containers counts order-service — and every participant that resolves to NO
+service, by element id, with whether it (or anything it is drawn inside) carries `#external`: the
+customer who drives the flow, a topic, a partner's API. The walk up stops at the first element
+bound to or titled for a service, as `loam gate`'s partner reading does, so a service drawn inside
+an `#external` grouping is still ours. Those are named and never dropped, because an environment
+list that is silently short comes up, and the journey then fails against something nobody was
+told to start. The payload is `suites[]` (`name`, `views[]` of `{id, file}`, `services[]`, `unresolved[]`
+of `{element, external}`), `ungrouped[]` — the use cases carrying no `#suite-` tag, which every
+per-suite line would otherwise leave out — and `useCases` (`state`: `absent` when the fleet
+declares no use case, `ok`, or `unreadable` with `error`, beside the `unreadable` boolean
+`list capabilities` spells). Over an unreadable `architecture/` the section degrades rather than
+refusing, and `suites` and `ungrouped` are ABSENT rather than `[]`. A `<name>` narrows `suites[]`
+only; an unknown one refuses `unknown-target` with the close names. The listing reads the FLEET
+map's use cases; a `#suite-` tag on a flow inside one service's own project is graded there like any
+other use-case tag, and is not listed — that flow runs inside one service, whose environment is the
+service itself.
+
 ### Two shapes of a service model
 
 `services/<…>/<svc>/model.likec4` comes in two shapes, and **the file's own grammar decides which**
@@ -708,7 +744,10 @@ so running loam from a subdirectory works; `loam init` writes the file where it
   this repo, digests that document and compares it with the committed
   `services/<id>/openapi.yaml`: `openapi.generated-stale` (warn) when they differ,
   `contracts.source-missing` (error) when nothing is there, `contracts.source-invalid` (error) when
-  the path escapes the repository or the file does not parse.
+  the path escapes the repository or the file does not parse. The stale warning's `details` name
+  the operationIds that differ (served but not in the committed copy, committed but no longer
+  served), and its message says when the two sets agree, so a reworded description no longer reads
+  the same as twenty vanished endpoints.
 
   **loam reads it and never writes it.** The copy into the docs repo stays a human `cp` reviewed in
   a pull request — that is what keeps the committed contract a document somebody agreed to rather
@@ -922,7 +961,12 @@ two checked files:
   `--all` alike, from the docs repo included. A `verified` spec whose current body hash mismatches
   gets `content.stale` (**warning**, the `sources.stale` grading: the doc changed since it was
   vouched, and only a person can say whether verified still holds). A verified doc with no
-  `content_digest` predates the stamp and stays quiet — the fix is re-vouching.
+  `content_digest` predates the stamp and stays quiet — the fix is re-vouching. Every fleet readout
+  carries the same fact, because it is computable from the docs repo: `loam list` shows
+  `vouched (stale)` and owes the row `re-vouch` in `missing` (so `--needs-work` lists it), `loam
+  status` counts it under `services.contentStale` and emits `next.revouch` instead of
+  `next.fleet-clean`, and `validate --all`'s scorecard counts it under `provenance.contentStale`.
+  The rung stays `vouched` — a person did stamp the document — exactly as for `vouch_scope` below.
 - `vouch_scope` — written by `loam vouch --sample <n>`, never by hand, and present only when the
   person who vouched read a recorded SAMPLE of the document rather than all of it. One flat string,
   `sampled <k>/<n> seed=<16 hex>`: k sections read of n, and the seed that chose them. `status`
@@ -1197,9 +1241,64 @@ under any flag — `x-loam-remove` and `x-loam-based-on` are stripped at path le
 level alike, on every merge branch. A path item consisting of nothing but a marker publishes no
 phantom path. The same feature must carry a `REMOVED` requirement whose `Operations:` line names
 that id. Coherence gates an absent path+method, an id mismatch, an unjustified marker, a removed
-requirement with no marker, and a new tagged C4 edge consuming the operation being removed.
+requirement with no marker, a new tagged C4 edge consuming the operation being removed, and a
+removal anything would still consume after the merge (`openapi.remove-op-consumed`, error,
+`--approve` overrides — **Who still consumes it** below says what counts). A `REMOVED`
+requirement owes a marker only while there is a living operation for it to retire: not for an id
+the service's living contract does not define (a consumer's `REMOVED` requirement naming another
+service's operation), and not for one this delta already replaces at its address (the overwrite
+below — no marker could be written there, since the replacement holds the slot). A living
+contract that does not parse proves neither exemption, so the marker stays owed.
 `serviceOperationIds` evaluates the feature as living upserts minus removals, so other same-feature
-checks see the post-archive contract. Archive deletes only the matching method, reports removals in
+checks see the post-archive contract.
+
+**An overwrite can remove an operation too, and is graded as one.** The merge writes per method and
+path, so a delta defining ANOTHER operationId where a living operation lives replaces it there — and
+when the contract the merge would write then defines the living one nowhere, it has left the
+contract with no marker for any of the checks above to read. Coherence asks the removal's own
+consumer question of it, on the merged contract: `openapi.remove-op-consumed` (error, `--approve`
+overrides, exactly as for a marker) while anything would still consume it after the merge. With no
+marker there is no `REMOVED` requirement either, so the provider's own requirement naming the old id
+stays unless the feature `MODIFIES` it to name the new operation or `REMOVES` it — and a `REMOVED`
+one owes no marker here. A new tagged edge onto the replaced operation is `c4-api.op-removing`. The
+fix is the delta's choice: define the replaced operation at another address in the same delta if it
+is to stay; for a rename, redraw the living edge and restate the governing requirement. An
+overwrite of an operation nothing names stays the advisory `api.op-unconsumed` it always was.
+
+**Who still consumes it — one answer for the gate, `loam diff` and `loam archive`.** The consumers
+of an operation are read once, the same way for every reader (`core/consumers/`):
+
+- every edge of the `architecture/` **project** whose `metadata { op }` names it and whose target
+  resolves to the provider — any document the spine grades, never `landscape.likec4` alone (when
+  only a sibling document fails to parse, the map file's own edges still count);
+- another service's requirement — in `spec.md` **or** `arch.spec.md` — whose `Operations:` line
+  names it, **unless that service's own contract defines the same id** — then the line names that
+  service's own operation: `validate` resolves a spec.md `Operations:` line against its own
+  service's contract, and `loam dependencies` reads a line in either file naming an operation its
+  own service provides as no dependency on anybody (an unreadable or absent contract proves no
+  ownership, and the line counts);
+- the use-case hops the model attributes to it (a contested hop is a doubt, never a consumer);
+- the provider's OWN documents still naming it — its `spec.md` requirements, and edges it draws to
+  itself. Not its `arch.spec.md` lines: `validate` grades an `Operations:` line in spec.md only, so
+  one in arch.spec.md strands nothing (another service's does count — it is a dependency on this
+  contract, as `loam dependencies` reads it). The gate counts these, because the merge strands them as surely; `loam diff` and the archive's
+  `openapi.op-modified` warnings answer who ELSE is affected, and leave them out (a service owes no
+  operationId to itself).
+
+The gate reads all of it **after the feature's merge**: a requirement the same feature `MODIFIES`
+to drop the id, or `REMOVES`, no longer counts — another service's too, so retiring the consumer in
+the same feature is a fix the gate sees — and one of its own `ADDED`/`MODIFIED` requirements naming
+the id does. A delta the merge would refuse to apply fails closed: the living requirements count,
+plus every one the delta adds or modifies. Edges and hops are read as they stand: the landscape
+merge only ADDS edges and a feature's flows are create-only, so no feature document can take one
+away — drop or redraw a living edge by editing the living map in the same change. The refusal lists
+the consumers in its `details[]`, in the order `loam diff` lists the victims of the same removal.
+A consumer document nobody could read refuses too, and is named there: a spec file that does not
+decode (another service's, or the provider's own), or a service id two directories claim — the gate
+cannot prove such a document does not name what is leaving, so it says it could not check, never
+that the fleet still consumes it. An edge drawn with no `metadata { op }` and a contested use-case
+hop are doubts about a drawing: `loam diff` lists them, and they never refuse, since `loam seed`
+draws every edge without an op. Archive deletes only the matching method, reports removals in
 text and `openapiRemovals` JSON, never copies the marker into living OpenAPI, and deliberately does
 not garbage-collect components. A removal marker in a living `openapi.yaml` is
 `openapi.remove-marker-living` (error). The usual staged-write rollback and `unarchive` snapshot
@@ -1211,9 +1310,11 @@ A `paymentService -> kafka 'Publishes PaymentAuthorized'` edge used to read as f
 while naming no contract anybody could check. The event axis is the API axis's mirror, in **AsyncAPI
 3.0** — only 3.0, because its operations are named top-level objects carrying
 `action: send|receive`, the exact analog of an `operationId`, where 2.x spells the same thing as
-`publish`/`subscribe` under a channel and leaves whose perspective they take ambiguous. A 2.x
-document declares no `operations` and reads as a contract with no messages rather than as a
-mis-parsed one. Like OpenAPI it is read with a shallow structural walk over the `yaml` parse, never
+`publish`/`subscribe` under a channel and leaves whose perspective they take ambiguous. A document
+whose `asyncapi:` field says 1.x or 2.x is refused as one `asyncapi.invalid` naming the version, and
+nothing on the event axis is graded against it: reading it as a 3.0 contract with no messages used
+to turn every edge and requirement into a misleading `spine.message-undefined`. The AsyncAPI CLI's
+`asyncapi convert --target-version=3.0.0` upgrades it. Like OpenAPI it is read with a shallow structural walk over the `yaml` parse, never
 a real AsyncAPI parser: the slice loam joins on is small enough that the parser's model would be
 dead weight, and adding it would be a fourth runtime dependency.
 
@@ -1276,9 +1377,14 @@ the edges point at channels it is the channels that collect three consumers each
 broker leaves a row of untagged hubs behind it.
 
 **The feature lifecycle, mirrored from the OpenAPI axis.** A feature changes this contract through
-`features/<FEAT>/specs/<svc>/asyncapi.yaml` — a **complete AsyncAPI 3.0 document**, exactly as an
-openapi delta is a complete document: the author restates the living contract around the part they
-are changing, and the machinery tells restatement from edit. Identity is the **slot** — the pair
+`features/<FEAT>/specs/<svc>/asyncapi.yaml` — a self-contained AsyncAPI 3.0 document holding **only
+the slots the feature adds, changes or removes**, exactly as an openapi delta holds only its own
+operations: the merge walks only the slots the delta declares, so a slot it leaves out stays as the
+living contract has it, and an edited slot is written out whole. A slot restated without being
+changed is legal and the machinery tells it from an edit, but it buys nothing and costs a pin,
+which a parallel feature's removal turns into `asyncapi.baseline-invalid` and `asyncapi.slot-revived`
+— or, unpinned, into `asyncapi.slot-revived` alone, the contract axis's revival check (under *Living
+spec vs delta* below) on this axis's identity. Identity is the **slot** — the pair
 (section, key) over the three named sections `channels.<key>`, `operations.<key>` and
 `components.messages.<key>` — and the join token stays the message name. Three feature-only keys,
 spelled and shaped exactly as on the OpenAPI axis: `x-loam-based-on` inside a slot's value (written
@@ -1330,7 +1436,36 @@ decision that reverses that stance: the removal family exists, a message-slot re
 justified by a `REMOVED` requirement's `Publishes:`/`Consumes:` line (channel and operation slots
 need exactness only — requirements join on message names and never on channel or operation keys, so
 demanding a justifying requirement there would invent a join the corpus cannot express), and
-`asyncapi.remove-message-consumed` gates a removal the living fleet still consumes. The lag argument
+`asyncapi.remove-message-consumed` gates a removal the fleet would still consume after the merge —
+a `consumes` edge of the `architecture/` project, another service's `Consumes:` line in either spec
+file (no ownership rule here: a consumer declares the message in its own contract as `receive` by
+construction), a use-case hop backed by such an edge — or whose provider's own `Publishes:` line the
+merge would leave behind, or its own `publishes` edge (the spine grades that edge on its source,
+`spine.message-undefined`; drop or redraw it in the living map), which covers a message slot re-keyed to another name or a send operation
+turned around as surely as a marker: read after the merge, as on the HTTP axis, and a `REMOVED`
+requirement owes no marker for a message the merge already takes out. **A consumer counts only
+while nothing would still send the message after the merge** — no service, and no `#external`
+element whose edge publishes it: the join is fleet-global, and a consumer with another producer is
+not stranded — `spine.message-unproduced` grades a consumer by exactly that, an outside producer
+included (*The direction is not decoration* above), and `loam diff` reports such a removal as
+`diff.message-removed`, "still sent by …", naming an outside producer as `<title> (#external)`.
+The senders are read after the merge too: a service this feature carries an event delta for sends
+what the merged contract would (the delta itself, where it creates the contract), and vouches for
+nothing where the merge cannot be simulated, so a feature retiring the message from every sender
+is still refused; an unreadable contract never vouches. The outside producer is read off the
+living `architecture/` project with validate's own rule, and only while that project parses. The
+landscape merge only adds to the map, so no feature takes its edge or tag away — but the rule also
+asks that no `services/<id>/` directory stand for the element, and the merge creates one from each
+`specs/<id>/` the feature carries. So the rule is asked over the directories as the merge leaves
+them: a feature that onboards the outside system as a service (`specs/legacy-gateway/`, its element
+titled or bound `legacy-gateway`, or a topic nested inside it) takes the producer away, and a
+retirement in it is refused unless something else still sends the message — the new service's own
+contract, in its `specs/legacy-gateway/` delta, for one. A `publishes` edge
+from an `#external` element that only the feature's own C4 delta draws does not count either —
+draw it in the living map, or archive with `--approve`. Another sender does not excuse the
+provider's own `Publishes:` lines and `publishes` edges — those are graded against its own
+contract, whoever else sends the message — nor its own unreadable spec files; another service's
+unreadable spec file, or an id two directories claim, refuses only while nothing would send. The lag argument
 survives as an **operational warning**, not a veto: passing the gate proves the *documents* agree
 nobody consumes the message — it does not prove no consumer is still reading the topic with lag, so
 sequence the runtime retirement accordingly.
@@ -1444,19 +1579,35 @@ the source for tests.
   never the resolution itself — a pin says "I read this version", so `loam rebase` reports every
   requirement that moved and says plainly that restamping without re-reading merges your text over
   theirs. There is deliberately no three-way merge: requirement prose does not merge.
-- **The same baseline on the contract axis, where it matters more.** A feature's `openapi.yaml` is a
-  **complete document, not a patch** — authors restate the living contract around the slot they
-  change — and the merge upserts every operation the document spells. The collision therefore needs
-  no overlap between the two features at all: two deltas over one service, editing *different*
-  operations, destroy each other, because whichever archives second pushes its authoring-time copy
-  of the operation it never meant to touch back over what landed in between. On a service with
-  thirty operations a delta quotes twenty-nine of them, and each is a candidate. So every operation
-  in a feature contract carries **`x-loam-based-on`** — the same 16-hex digest, in the
+- **The same baseline on the contract axis.** A feature's `openapi.yaml` is a **self-contained
+  document holding only what the feature adds, changes or removes** — not a copy of the living
+  contract. The merge walks only the paths and methods the delta spells: an operation it leaves out
+  stays exactly as the living contract has it, a local `$ref` (`#/components/schemas/Order`)
+  resolves into the living document, and a brand-new operation, path-level key or component has no
+  living version to pin, so an add-only delta never trips `openapi.baseline-missing` and needs no
+  `loam rebase` at all. What the merge does upsert is every operation the document *does* spell,
+  so an operation quoted without being changed — copied for context, or a whole contract pasted in
+  — is a collision waiting for somebody else's edit: two deltas over one service, each quoting the
+  operation the other edits, destroy each other, because whichever archives second pushes its
+  authoring-time copy back over what landed in between. A quote also costs something even pinned:
+  it is one more pin, and a pinned quote whose living operation a parallel feature removes is
+  `openapi.baseline-invalid` — the living slot is gone, so the pin is founded on nothing — an
+  error that blocks the archive until the quote is deleted. Unpinned, the same quote has no living
+  operation behind it, so the baseline axis cannot tell it from an addition — and it used to
+  archive as one, at exit 0, putting the retired operation back. The **revival check** below is
+  what refuses it now. So a delta quotes nothing it does not change, and every operation in it that
+  the living contract already holds carries
+  **`x-loam-based-on`** — the same 16-hex digest, in the
   vendor-extension shape this axis already uses for `x-loam-remove`, written by `loam rebase` and
   stripped on merge exactly like `Based-On:`. The digest is taken over the operation's *canonical*
   form (object keys sorted), which is the same comparison `isDeepStrictEqual` makes when the merge
   decides an operation "differs" — so a pin goes stale exactly when the merge would say something
-  moved, never over a reordered key. The pin is always the digest of the **living** operation, and
+  moved, never over a reordered key. The pin is keyed by the slot, method and path, on both sides,
+  so an operation written with no `operationId` — living or in the delta — is pinned, graded and
+  quoted exactly as a named one: `loam rebase` always pinned against whatever stood at the slot,
+  and the gate once read named operations alone, so it refused the pin rebase had just written as
+  one over "no operation at that slot" and never asked an unnamed quote for a pin. The pin is
+  always the digest of the **living** operation, and
   that one rule yields both merge verdicts by itself: an operation the author only quoted is
   byte-equal to living, so its pin equals its own content and **the merge skips it entirely**
   (reported as `· quotes …` in the plan, so the plan never silently writes less than the delta
@@ -1466,7 +1617,8 @@ the source for tests.
   decision, reverting an operation nobody edited is a bug. `openapi.baseline-missing` is a warning
   that gates the archive, exactly like its requirement-axis sibling — every unpinned restatement is
   a candidate rollback — and it is reported **once per service** rather than per operation: the fix
-  is one command, and twenty-nine identical findings teach people to filter the code out. **Covered
+  is one command, and the twenty-nine identical findings a contract pasted whole from a
+  thirty-operation service would raise teach people to filter the code out. **Covered
   since the path-item/component baselines landed:** the same discipline now reaches the two surfaces
   the operation pin cannot — path-level keys (`parameters`, `servers`, `summary`, `x-*`) and every
   `components/<kind>/<name>` — through a single feature-only root record **`x-loam-baselines`** (`{
@@ -1481,6 +1633,93 @@ the source for tests.
   component copying is verdict-driven, with genuinely new components copied only when reachable from
   content actually written. Removal markers still carry no pin, since
   `openapi.remove-target-mismatch` already checks that exact slot.
+- **A retired operation does not come back by accident.** An operation the living contract does
+  not hold is either new or *retired*, and the living contract alone cannot say which: both are
+  simply absent. So the feature gate also reads what every **archived** feature took out — the
+  `x-loam-remove: true` markers left in `features/archive/<FEAT>/specs/<svc>/openapi.yaml` and
+  `asyncapi.yaml`, through the same relocation rule the gate applies to an in-flight delta (a
+  marker on an id the same delta redefines elsewhere moved it, and retired nothing). A delta entry
+  that is not itself a removal, that its service's living contract does not hold, and that an
+  archived feature retired is **`openapi.op-revived`** (by operationId — a
+  retired operation quoted at a new path is the same operation back) or **`asyncapi.slot-revived`**
+  (a `channels` or `operations` slot by its key; a message by its *name*, wherever it is declared).
+  A relocation retires nothing, but it VACATES an address — and so does a retirement, once a later
+  feature re-adds the id somewhere else — so the index records, per id, every address an archived
+  feature's executed marker vacated, which feature, and for a move where its delta put the id. The
+  finding is judged on the contract the archive would WRITE: the check runs the archive's own
+  merge of the delta over the living contract and compares where each operationId stands there with
+  where it stands now. An (operationId, address) the merged contract has and the living one lacks
+  is `openapi.op-revived` when the living contract holds the id nowhere and an archived feature
+  retired it (anywhere — by identity) or moved it away from that very address, or when the merged
+  contract answers the id at two or more addresses and an archived feature retired it at, or moved
+  it away from, that very address: archived, it would answer the id at both. An id that the living
+  contract still holds and the merged contract answers at exactly one address is never a revival —
+  a delta moving it back with its own removal marker where it lives now, or swapping another
+  operation in there (named or not: the merge writes per method and path), leaves it at one
+  address — while a marker standing where the id does not live deletes nothing, and excuses
+  nothing. One address is no exemption for an id the living contract holds nowhere: that is the
+  first case, so a quote of an address a move vacated is the finding even after a hand edit took
+  the id out of where the move put it. Reading the merged contract replaced a
+  case-by-case re-derivation of the merge that each review found a new hole in.
+  On the event axis the same rule runs on the message name, over the event merge: the addresses a
+  feature vacates are `components.messages` keys (a marker there) and the inline declarations a
+  channel removal took. A delta that restates the channel an inline declaration stands in (with
+  the message as a `$ref`) or retires that channel takes the name out, since a channel upsert
+  replaces the channel's interior; a marker nested on the inline message does not
+  (`asyncapi.remove-marker-inline`), so the finding names the channel as the remedy. A channel or
+  operation slot's identity is its key, so moving one is a retirement plus an addition, graded as
+  such. A message declared inline under a channel the delta brings back is that channel's
+  interior, and the channel's finding stands for it — unless the merged contract declares the
+  name somewhere else too (an archived feature re-declared it under `components` when it retired
+  the channel): then the inline declaration is a second place of its own, and gets its own
+  finding, since the channel's says nothing of the duplicate `--approve` would archive.
+  Both are warnings that **gate** the archive, `openapi.baseline-missing`'s doctrine: the document
+  is legal, and re-adding a retired operation can be exactly what a feature means — a retirement
+  rolled back — so `--approve` carries the call, and the archive output then names what came back
+  and whose retirement it reverses. The message offers both remedies: delete the quote if it only
+  restated the operation; archive with `--approve` if the feature brings it back on purpose (a pin
+  over nothing is `openapi.baseline-invalid`, so a deliberate re-add drops it first). At a vacated
+  address beside a living one it names the address to drop instead: delete the quote, or, to move
+  the id back on purpose, take it out of where it lives now in the same delta (a removal marker
+  there; for a message declared inline, restate or retire its channel; for a `components.messages`
+  key, also restate every channel or operation of the merged contract still `$ref`-ing it, with
+  the `$ref` pointed at the quoted key — the message names them, since a marker alone would leave
+  them pointing at nothing and their send would stop sending the message) — and where the delta
+  already spells that address, so no marker can stand there, archive with `--approve`. A slot
+  holds one entry, so where the living contract has ANOTHER operation (or message) at the address
+  the delta spells the id at, the merge replaces it there: the message names it ("now holds
+  'requestCancellation', and archiving this delta replaces it there"), and the move-back remedy
+  says to define it at another address (another key, for a message) in the same delta if it is
+  to stay — never an address
+  "the living contract no longer has", a remedy that once led to a clean gate and an archive that
+  deleted the other entry unnamed. `loam rebase`
+  never pins such an entry as new: it prints the same finding (`revived[]` in `--json`) and leaves
+  the decision to the author. It asks the question of the delta as it will WRITE it, pins
+  included: a quote pinned to its own content is skipped by the merge, and the same quote
+  repinned to whatever now lives at its address is an edit the merge writes — so a revival
+  rebase's own repin creates is in that list, `--dry-run` included, and the next validate agrees. A channel-slot removal retires the messages its living channel
+  declared inline, which the delta never spells, so those names are read from the archived
+  feature's undo snapshot (`.loam-before/`, the pre-image of the contract the merge ran against) —
+  only while that pre-image still hashes to what the manifest recorded. A marker is a request, not a
+  record of what happened: the OpenAPI merge deletes a living operation only when the one at the
+  marker's own method and path carries the marker's `operationId`, and the event merge deletes a
+  `channels` or `operations` slot only when the living contract has that key, and a
+  `components.messages` slot only when the message declared there carries the marker's name. A
+  marker that missed — archived past `remove-target-missing` or `remove-target-mismatch` under
+  `--approve` — deleted nothing, so each marker counts only if the same pre-image held its target
+  (a contract the archive created, or never wrote, lost nothing to it); a feature with no intact
+  snapshot cannot be checked, and its markers count as written. Two marker
+  shapes are never sources, because neither can match anything: a marker with no `operationId`
+  (`openapi.remove-marker-anonymous`) and one written at path level
+  (`openapi.remove-marker-path-level`) — a feature archived past either under `--approve` left the
+  operation living.
+  **The honest limit:** the check knows only what the files under `features/archive/` record. A
+  removal made by hand-editing a living contract leaves no marker anywhere, and an archived feature
+  deleted from disk takes its markers with it; both read as "never retired", and a quote of such an
+  operation grades as an addition exactly as it did before the check existed. A channel's inline
+  messages drop out the same way when its feature carries no intact pre-image (archived before the
+  snapshot existed, or the snapshot edited or removed since) — the channel slot itself is still
+  caught. No git history is read: the archive directory is the record.
 
 A requirement may carry a stable identity in its body: `Requirement-ID: <id>`, where the ID matches
 `[A-Za-z][A-Za-z0-9._-]{0,127}`. It is optional for backward compatibility. When present in a delta,
@@ -1533,7 +1772,10 @@ scenarios exercise. Comma-separated, same keep-last-line quirk (and the same rep
 
 An entry that resolves to nothing is `covers.unknown` (**warning**, with close ids offered where
 they exist): the typo guard, because a mistyped entry silently costs exactly the coverage it was
-written for.
+written for. It is suspended — every form at once — for a service whose `model.likec4` could not be
+read, whether the model itself does not parse (`c4.invalid`) or it extends a map that does not
+(`spine.landscape-invalid`): an entry naming a container of an unread model is not a typo, and the
+one repair brings the whole grade back on the next run.
 
 **Coverage obligations** — both warnings, deliberately: they never gate `archive`, and `--strict` is
 the CI escalation.
@@ -1649,12 +1891,15 @@ digest:
 - stamps: line 1 is `# generated by loam v<version> — …` (the AGENTS.md stamp pattern — the file is
   never to be hand-edited), and each scenario carries the tag `@loam-digest-<16hex>` on the line
   above its `Scenario:` keyword: the first 16 hex characters of `loam verify`'s scenario body hash —
-  sha256 of the body lines joined and edge-trimmed, salted with the file name on the arch axis, the
-  exact recipe `scenario.tested` claim ids fold in — so the stamp, the claim and the spec can never
-  disagree about what a scenario says, and identically-worded scenarios across `spec.md` and
-  `arch.spec.md` can never share a digest (a business-axis test run cannot answer for an arch
-  scenario). A tag rather than a comment because cucumber's JSON report carries tags per scenario
-  (`elements[].tags`): the stamp rides through the runner untouched, which is what
+  sha256 of the body lines joined and edge-trimmed, salted with the owning SERVICE and, on the arch
+  axis, with that axis's file name — the exact recipe `scenario.tested` claim ids fold in — so the
+  stamp, the claim and the spec can never disagree about what a scenario says. Both salts are there
+  for one reason: a digest that spanned two namespaces would let a green run answer a question
+  nobody ran a test for. Identically-worded scenarios across `spec.md` and `arch.spec.md` can never
+  share a digest (a business-axis test run cannot answer for an arch scenario), and neither can two
+  services wording a scenario the same way (one repository's green run cannot answer another
+  repository's claim). A tag rather than a comment because cucumber's JSON report carries tags per
+  scenario (`elements[].tags`): the stamp rides through the runner untouched, which is what
   `loam verify --results` matches on.
 
 **Staleness** (`loam validate --service <id>`, service-repo-scoped like the `sources.*` chain):
@@ -1727,6 +1972,12 @@ requirement also needs a current `Based-On:` pin before archive; `loam rebase <F
 Omitting or leaving the intent as scaffold text raises the gating `intent.empty` /
 `scaffold.placeholder` warning, so the old one-file shape is not archive-ready.
 
+Below that floor is no feature at all. A change that touches no requirement, no operation and
+no fleet edge — a refactor, a dependency bump, a fix that brings the code back to behaviour the
+living spec already documents — leaves the docs repo untouched: it is a code PR, then
+`loam validate --service <id>` in the service repo, where `sources.stale` names the moved paths, and
+the re-vouch they owe (`loam vouch --pack` is the reading list; the vouch is a person's).
+
 Each axis may be legitimately empty, and the checks grade absence differently from
 emptiness-by-accident:
 
@@ -1737,7 +1988,8 @@ emptiness-by-accident:
   declared-but-untagged is almost always a forgotten tag, while declaring nothing is a legible
   statement that the architecture is unchanged.
 - **openapi delta** — absent whenever the feature adds no operations; a requirement change that
-  stays inside the existing contract has no API axis to speak on.
+  stays inside the existing contract has no API axis to speak on. Present, it holds only the
+  operations the feature adds, changes or removes.
 - **requirement delta** — the axis that is nearly always present, because a feature that changes no
   requirement changes no promised behaviour. The exception is architecture-only work: a new service
   in the C4 delta with no `specs/<svc>/spec.md` gets `service.no-requirement-delta` as a warning,
@@ -1750,6 +2002,16 @@ a feature cannot fold into the living docs with its reason unwritten. Its siblin
 `scaffold.placeholder` refuses the rest of an unedited `loam new` scaffold the same way — the exact
 template strings, a requirement or description nobody authored, must not become living truth.
 
+The scaffolded `intent.md` also carries an optional `## Open questions` heading over a comment.
+It is where `loam-feature`'s analyze step — between authoring and `loam rebase` — writes what the
+documents leave open: a SHALL two engineers could build two ways, a value or window two services
+state differently and which side refuses, a `Realizes:` that does not deliver its capability, an
+edge with no stated timeout, retry, partial-failure or compensation answer, a neighbour left out of
+`--touches`. A person answers by editing the file. Nothing grades the section: `intent.empty` reads
+past it, so questions written there are never mistaken for the Why, and they never gate the archive —
+every check loam has is a join between exact tokens, and whether two services MEAN the same thing by
+one is the part no join reads.
+
 ### Where a capability lives (a declared name, and the document behind it)
 
 A business capability — "payment splitting" — is spread across the living specs of every service
@@ -1916,13 +2178,19 @@ refusing it, which is why the flattening is a whitelist and not a list of substi
   document declares no requirements yet, it declares none flattening to this slug (close ids
   offered, each already spelled as the tag to write), or two of its ids flatten to one slug.
 
-**Either reserved prefix opts a view in.** A view carrying `#req-` and no `#cap-` is an author who
+**Any reserved prefix opts a view in.** A view carrying `#req-` and no `#cap-` is an author who
 asked to be graded and forgot half the claim; it earns the `unscoped` message rather than silence.
-That opt-in is **one predicate**, and every reader takes it: `loam validate`, `loam diff`,
-`loam delta`, `loam status`, the context and explore packs and `loam list capabilities` all decide
-"is this a use case" the same way, so a flow one of them can see is a flow all of them can see. The
-byte scan that lets a fleet with no use cases skip the LikeC4 load looks for both prefixes for the
-same reason — a gate narrower than the predicate is silence, not a smaller answer.
+A view carrying only `#suite-<name>` is a use case too (see the layout section above). That opt-in
+is **one predicate**, and every reader takes it: `loam validate`, `loam diff`, `loam delta`,
+`loam status`, the context and explore packs, `loam list capabilities` and `loam list suites` all
+decide "is this a use case" the same way, so a flow one of them can see is a flow all of them can
+see. The byte scan that lets a fleet with no use cases skip the LikeC4 load looks for every prefix
+— `cap-`, `req-` and `suite-` — for the same reason: a gate narrower than the predicate is silence,
+not a smaller answer. It looks for each written as a tag REFERENCE: a `#`, then only what LikeC4
+skips between the `#` and a tag's name (whitespace, line breaks, comments), then the prefix — the
+only way a view carries a tag. A prefix in prose, a title or a `tag cap-…` declaration does not open
+it, so a hand-drawn `.likec4` beside a service's model that names `suite-` in its title, carries no
+tagged view and does not parse is not loaded and earns no `usecase.flow-invalid`.
 
 Being SEEN is not the same as claiming something, and the difference is worth stating because it
 looks like a gap and is not. A view with no resolved `#cap-` tag claims no capability, so it seeds
@@ -2107,7 +2375,10 @@ ready. Several useful product shapes remain outside that boundary on purpose:
   a third thing to keep truthful.
 - **Authored `tasks.md` as authoritative state** — loam derives its actionable checklist (`loam
   delta`, `loam verify`), so it cannot drift from the delta. Imported task lists are preserved as
-  non-authoritative migration evidence until a human chooses their disposition.
+  non-authoritative migration evidence until a human chooses their disposition. The refusal stands,
+  and the derived projection now exists as `loam tasks`, which answers the same question the file
+  would have — recomputed from the delta, the generated suite and the verification record on every
+  run, so there is nothing to tick and nothing to go stale.
 - **Per-tool workflow forks** — `AGENTS.md` is the tool-agnostic contract. Generated adapters wrap
   shared bodies and are never independent process definitions.
 
@@ -2198,6 +2469,19 @@ which carry them across loam upgrades. Correspondingly, `archive` refuses to rep
 version-3 claim graded at its service's current directory: the previous archive's writes are still
 in the docs and those files are the only way back.
 
+The manifest also carries one key that is not about bytes, added without a version bump because
+nothing that restores reads it: **`checklist`**, the digest of the checklist a fresh `loam verify`
+derived for the feature just before the merge — written when the feature carried a readable
+verification record then, absent otherwise and in every manifest an older loam wrote. It is the
+question the feature asked as it shipped. Once archived, a record is frozen history and the checklist
+cannot be re-derived (the merge moved the feature's operations into the living contract, so a
+derivation after it can only mismatch), so this is the one thing an archived record can still be
+held to: `loam gate --since` grades the record against it, and a record that answered an older
+checklist reads `stale`. `unarchive` takes the snapshot away with the rest of it, so a feature
+archived again gets a fresh capture. `list`, `status` and `verify` keep reading an archived record as
+frozen history; a manifest with no `checklist` leaves the gate reading it that way too, and saying
+so.
+
 Some checks run at plan time rather than in the gate, because only the computed merge can see them.
 A **living** requirement sitting outside `## Requirements` refuses the whole archive
 (`living.requirement-outside-requirements`, error): the merge rewrites only that section, so the
@@ -2205,7 +2489,9 @@ requirement would land in the file twice — and `--approve` does not override i
 duplication is mechanical, not a judgment call; re-home the requirement first. A delta that
 redefines a path+method the living OpenAPI already has (`openapi.op-modified`, warning) merges
 anyway, but the plan says so — the overwrite is wholesale, and the living definition it replaces
-deserved an eye. An unparseable `delta.likec4` fails the archive at plan time regardless of
+deserved an eye. One that defines a different operationId there, leaving a consumed operation
+defined nowhere, never reaches the plan without `--approve`: the gate refuses it first
+(`openapi.remove-op-consumed`, the overwrite shape). An unparseable `delta.likec4` fails the archive at plan time regardless of
 `--approve`: the alternative was archiving with the architecture axis silently dropped, which is the
 data loss this tool exists to prevent.
 
@@ -2213,7 +2499,8 @@ The landscape merge **splices authored source, it does not re-serialize**. Each
 relationship is copied into the living landscape byte-for-byte from `delta.likec4` — technology,
 style, icons, links, metadata, nested children, every tag — with exactly one edit: the feature's own
 tag is stripped (the additions are baseline now — the drop above is why unarchive restores bytes),
-and a construct the strip empties goes with it (`x = kind 'y' { #FEAT-1 }` lands as `x = kind 'y'`).
+together with the `,` or `;` that set it apart in a tag list (`#FEAT-1, #x` lands as `#x`), and a
+construct the strip empties goes with it (`x = kind 'y' { #FEAT-1 }` lands as `x = kind 'y'`).
 Placement is deterministic and **service-grouped**, and never moves an authored byte — it only
 chooses where the new blocks go. A top-level element whose service the model already draws (the
 `metadata { service }` binding first, the title as fallback) lands immediately after the last
@@ -2231,22 +2518,32 @@ services) yields the byte-identical landscape to B then A, so concurrent archive
 different lines and git merges them without help. The insertions carry no marker comment — which
 archive added what is the git history's to say. A **nested** element lands inside its parent's block
 — inside the living parent when the landscape already has it, riding verbatim inside the spliced
-parent when the parent is new — never as a flat dotted id, which LikeC4 rejects at top level. LikeC4
+parent when the parent is new — never as a flat dotted id, which LikeC4 rejects at top level. A
+landscape may be written in **several top-level `model { }` blocks**, which LikeC4 reads as one
+model, and the merge reads all of them: an ANCHORED addition — nested in a parent, joining its
+service's neighborhood, or joining its source's edges — lands in its anchor's block, and an
+unanchored one lands in the trailing region of the **first** block, the one every addition went to
+before a second block was readable. The walks never cross a block boundary, so the scheme stays
+order-independent, and a one-block map places exactly as before. LikeC4
 reference resolution is not order-dependent, so a relationship placed before an element it names
 still parses — and because splicing is text surgery, the computed landscape is **parsed in memory
 before anything is written**: a result LikeC4 rejects — a splice bug, or legal inputs the living
 document cannot absorb, like an element kind or tag its `specification` block never declares —
 refuses the archive at plan time (`merge-failed`, nothing written), the same discipline as the
-unparseable delta. A living declaration sharing its line with another statement (legal LikeC4 the
-splice map cannot see around — its statement scan runs to the end of the line) refuses the same way:
-give each top-level declaration its own line, then re-run.
+unparseable delta. A living declaration the splice map cannot locate refuses the same way rather
+than be spliced around blind — most often one sharing its line with another statement, which is
+legal LikeC4 the splice map cannot see around, since it reads one statement per line. The refusal
+names the line LikeC4 parsed the declaration on and what the splice map read there instead, and
+says "shares that line" only when the line shows it: give each top-level declaration its own line,
+then re-run.
 
 **Which document an addition lands in.** The C4 merge asks it per declaration, not per feature. An
 element whose PARENT resolves to a service whose `model.likec4` extends the map is spliced into that
 model — and so is the interior a delta writes inside a service element the same archive introduces,
 since those containers carry no feature tag and would otherwise ride onto the map inside their
 parent's bytes. The parent chain has to be spelled in the map's own ids for either to happen. The
-splice goes inside the `extend <fqn> { … }` block for the parent — appended when the model has none, as
+splice goes inside the `extend <fqn> { … }` block for the parent — in whichever `model { }` block
+holds it, and appended to the first one when the model has none, as
 the `model { }` block itself is appended to a model that has none (an empty file, a `views { }`-only
 file and a tags-only `specification { }` are all extending models, and all three are legal to
 archive into). A
@@ -2349,7 +2646,9 @@ design. The heading must be reachable, too — a leading UTF-8 BOM used to hide
 
 ## The verification record
 
-`features/<FEAT>/verification.yaml` is the done-check written down. `loam verify <FEAT>` derives a
+The done-check is written down inside the feature: one `features/<FEAT>/verification/<svc>.yaml` per
+attesting service, or — for the all-at-once form, and every record written before the directory —
+the one file `features/<FEAT>/verification.yaml`. `loam verify <FEAT>` derives a
 **checklist** from the feature's own artifacts — the same files `validate` reads, never the code:
 
 | kind | one claim per | reads |
@@ -2373,18 +2672,26 @@ nobody wrote must not carry over as if it still applied.
 anything that does not answer the *current* checklist, each under its own `--json` `error.code`:
 `answers-unreadable` (not JSON, or a verdict outside `confirmed` / `unconfirmed`),
 `answers-mismatch` (an id nobody asked about, a claim with no answer, or one answered twice),
-`answers-unevidenced` (a `confirmed` with no `file:line` behind it). An unchecked claim must never
-be able to masquerade as checked.
+`answers-unevidenced` (a `confirmed` with no `file:line` behind it, or one citing a file or a line
+that does not exist in the repository the record is written from — the all-at-once form included,
+which binds to no commit but no longer takes a citation on trust). The all-at-once form checks what
+is shaped like a citation and only that: an evidence entry that is one token ending in `:<digits>`
+and is not a URL must name a regular file inside the repository with that line, while prose ("manual
+QA by Alice"), a URL or a path with no line is recorded as it always was. The federated form keeps
+its stricter contract — every agent entry a `file:line` bound to the attested commit. An unchecked
+claim must never be able to masquerade as checked.
 
 **`--results <report.json>` answers the `scenario.tested` claims mechanically, from a cucumber JSON
-test report** — the format `cucumber-js --format json` emits, and cucumber-jvm, behave and SpecFlow
-speak too. The contract is exactly this and nothing more: a top-level array of features, each
+test report** — the format `cucumber-js --format json` emits, and cucumber-jvm, behave,
+SpecFlow/Reqnroll, pytest-bdd (`--cucumberjson`) and godog's cucumber formatter speak too. The contract is exactly this and nothing more: a top-level array of features, each
 `elements[]` (scenarios) with `name`, `tags[] {name}` and `steps[] {result {status}}` — plus the two
 places those dialects put a failure the steps never see: cucumber-jvm's per-element
 `before[]`/`after[]` hook results and behave's element-level `status`. Every other field is ignored,
 tagless elements (backgrounds, hand-written scenarios) are invisible, and a file that is not that
 array at all refuses under `answers-unreadable` rather than quietly answering every claim "not
-found".
+found". A file that is not JSON at all — a JUnit XML report is the usual one — refuses the same way,
+and the refusal names both shapes `--results` reads, because the second one exists for exactly that
+runner.
 
 Matching is by digest and nothing else: a claim is answered by the report scenarios carrying its
 `@loam-digest-<16hex>` tag — the tag `loam gherkin` stamped, the same 16 hex of the same body hash
@@ -2393,12 +2700,21 @@ name), so a business run can never answer an arch claim however identically the
 worded. Names never match anything: a reworded spec scenario matches nothing until the suite is
 regenerated and re-run — an agent must not be able to SAY a scenario is tested; only a green run
 may. The verdicts: every matching occurrence (a digest the report holds twice is a re-run, and all
-occurrences count) ran at least one step, every step `passed`, every before/after hook `passed`, and
-the element-level status (when the dialect carries one) is `passed` → `confirmed`, with evidence
+occurrences count) ran at least one step, every step `passed`, every before/after hook `passed`, the
+element-level status (when the dialect carries one) is `passed`, and **it ran exactly as many steps
+as the stamped scenario has** — the count `loam gherkin` emits for it, `And`/`But` included →
+`confirmed`, with evidence
 `<report-path>: <feature uri or name> › <scenario name>` per occurrence; a failed / undefined /
 pending / ambiguous step (`failed at step N`), a failing hook (`failed in a before/after hook`), a
 failed element status, a skipped-only run (`skipped`), or no match at all (`not found in report`) →
-`unconfirmed` with the reason as the note.
+`unconfirmed` with the reason as the note — and a run whose step count differs from the stamped
+scenario's is `unconfirmed` too (`ran N step(s) where the stamped scenario has M`). The digest is
+only a tag, and a tag is text: a one-step stub carrying the right digest used to confirm five-step
+scenarios, because nothing compared what ran with what was stamped. The count is what every dialect
+can be held to; the step TEXT is not compared, because an outline's steps reach the report with
+their placeholders filled in and dialects disagree about keyword spacing and localisation. The hook
+entries cucumber-js lists among `steps[]` (marked `hidden`, keyword `Before`/`After`) are read as
+hooks, never counted as steps — and a failing one still sinks the run.
 
 `--results` OWNS every `scenario.tested` claim **in the same run**: an answers-file entry for one is
 refused (`answers-mismatch` — the runner owns it), `--record` alongside must answer exactly the
@@ -2430,6 +2746,8 @@ own runner-neutral shape, chosen by its marker key:
 ```
 
 `digest` is the 16 lowercase hex of the `@loam-digest-…` tag `loam gherkin` stamped on the scenario.
+An entry carries no steps, so it is held to its `status` alone — the step-count check above is a
+property of the cucumber shape.
 `status` is `passed` or `failed` — nothing else. `test` is optional free text: the runner's own name
 for the run, used as the evidence string a reader follows. `loamScenarioReport: 1` is the format
 version this loam reads; any other value refuses rather than being partly understood.
@@ -2455,12 +2773,18 @@ carrying the marker is always graded as this shape, even when malformed: falling
 cucumber parser would tell an author their report is not a cucumber array, which is true, useless,
 and hides the real mistake.
 
-**Two services wording a scenario identically share one digest**, and a single report then cannot
-say whose suite ran it. Those claims are left `unconfirmed` with `verify.digest-contested` (warn)
-naming both services and the affected claim ids, rather than confirming both from one run. Record
-each service's claims from its own repository with `--service`, which narrows the checklist before
-matching. Scenario digests are salted by *axis* (business versus arch) but **not** by service, so a
-digest identifies scenario words; `--service` is what gives a report an owner.
+**Scenario digests are salted by both the owning service and the axis** (business versus arch), so
+two services wording a scenario identically do not share one: the hash folds in the service the
+claim is filed under. The service salt is what makes ordinary repeated wording CORRECT rather than
+merely refused — "the service returns 404 for an unknown id" is a sentence a fleet writes many
+times, and before the salt those scenarios shared a digest, so one repository's green run could
+appear to confirm claims from suites that never ran each other's tests, and the only defence was to
+decline to answer. `verify.digest-contested` (warn) survives as the guard on that invariant rather
+than as a diagnosis of ordinary authoring: if a digest is ever claimed by two services it is a
+truncated-hash collision, a single report still cannot say whose suite ran it, and those claims are
+left `unconfirmed` naming both services and the affected claim ids rather than confirmed from one
+run. Record each service's claims from its own repository with `--service`, which narrows the
+checklist before matching.
 
 ### Contract-test reports answer the `api.exposes` claims
 
@@ -2554,7 +2878,7 @@ service's as a pure lens — no repository binding, usable from the docs repo, r
 `unknown-service` when the checklist has no claims owned by that id — and both agents must have
 answered the same scope. Combining the flag with `--record`, `--results` or `--contract-results`
 refuses `invalid-option`, as does any arity other than exactly two files and an archived feature
-(frozen history has no current checklist to answer). A `verification.yaml` too damaged to read does
+(frozen history has no current checklist to answer). A verification record too damaged to read does
 **not** block the diff — the lens never reads the record, and the moment a cross-examination is most
 needed is before re-recording over a broken one.
 
@@ -2574,7 +2898,7 @@ block pins each file's path and the sha256 of the exact bytes read.
 confirmed/unconfirmed/unanswered. The payload also deliberately carries **no `verified`, `verdict`
 or `attested` key at all**: two answer sets agreeing — usually two contexts of the same model, so
 correlated — ranks where a reviewer reads first; it is not verification, it upgrades nothing, and it
-leaves `verification.yaml` byte-identical (no docs lock is taken, and the diff runs while a writer
+leaves the verification record byte-identical (no docs lock is taken, and the diff runs while a writer
 holds one).
 
 ### Attested is not verified
@@ -2609,28 +2933,79 @@ the decision:
 So "a green run is the only thing that confirms a scenario" is a claim about the **record**, not
 about the CLI's flags: the short path still works, and it is legible afterwards as the short path.
 
-### The record is federated: one file, one attestation per service
+### The record is federated: one attestation per service, one file each
 
 A cross-service feature's claims belong to several services, and each service's code lives in its
 own repository — so no single place can honestly answer all of them.
 `loam verify <FEAT> --service <id> --record answers.json`, run **in that service's own repo**,
 narrows the checklist to that service's claims and binds the answers to this repository's commit.
-The result is one `schema: 2` `verification.yaml` holding a list of **`attestations`**, one per
-service: the service id, the commit the answers were bound to, and that service's answered claims.
-
-The merge semantics are additive and non-destructive. Recording for service B keeps service A's
-attestation exactly as it stood — the new record is the old attestations minus B's previous one,
-plus B's new one. Answers the new record does *not* carry are reported in `discarded`, tagged
-`unattested` (a schema-1 answer, or one whose attestation is gone) or `off-checklist` (a claim the
-current checklist no longer asks). Nothing is dropped silently.
-
-The write behind that merge holds the same advisory lock archive does, and holds it from before the
-feature is resolved to after the record lands — two `--record` runs for different services serialize
-(the later one waits briefly, then merges over what the first left, so **both** attestations
-survive), and a record can no longer be written into a path an `archive` is renaming out from under
-it. The commit itself is staged beside the target and swapped in by one rename over the exact bytes
-the merge was computed from, so a kill mid-record leaves the previous record whole — never truncated
-YAML — and an edit that landed in between refuses instead of being buried:
+The result is that service's **attestation**, written to a file of its own:
+`features/<FEAT>/verification/<id>.yaml` — a `schema: 2` record holding exactly that service's
+attestation (the service id, the commit the answers were bound to, the checklist digest it answered,
+and its answered claims) and nothing of anybody else's. **The directory is the record**, the rule
+`glossary/` and `capabilities/` already follow: loam reads every file in it and adds them up, and
+the verdict and the counts are computed from the union at read time — exactly as they always were,
+since nothing ever trusted a stored `summary`. Each file's own `summary` counts the whole checklist,
+with the claims other services own honestly `unanswered` in it.
+
+**Why one file per service.** The record used to be ONE `verification.yaml` for every service, and
+every attestation rewrote its `summary`, its `recorded` date and its checklist-ordered `claims`. Two
+teams recording two different services on two docs-repo branches therefore always conflicted when
+the PRs merged — add/add from an empty start, content conflicts on the summary, the claims and the
+attestations once one had landed — and sorting the attestations did not help, because two
+insertions at one anchor are a conflict whatever the order. The advisory lock below serializes
+writers on one checkout only; a fleet records from many. With a file per service, two teams' records
+touch two different paths and merge cleanly. Recording a service again replaces that service's file
+and nothing else; another service's file is never rewritten, and its pins never touched.
+
+The record answers **one version of the checklist**: the one the feature asks now — `loam verify`
+(read and record alike), `tasks`, and `status`, `list` and `gate` for an in-flight feature all
+derive it, and the files that answered it are the ones that count. Only where no reader knows the
+current version (the frozen view of an archived feature) or no file answered it does the newest
+file decide (by `recorded`, a later service id breaking a same-day tie). Newest-by-date used to
+decide always, and `recorded` is a date: a service that recorded the current checklist lost a
+same-day tie to a service with a later id that had recorded an older one, so the current answers
+were dropped and every reader called the record stale. A file that answered a different version
+keeps its attestation in the list — `verify.checklist-forked` names it, on the recording run's
+output as well as the read view — but its answers do not count until that service records again.
+The one shared file used to settle this by rewriting: the last writer pruned everybody's answers to
+its own checklist. Per-service files are never rewritten by anyone else, so nothing can prune them,
+and counting an answer filed against another question set would let an id the feature no longer
+asks fill the slot of the question that replaced it.
+
+**`features/<FEAT>/verification/` is loam's.** Every non-dot `*.yaml` in it is read as one
+service's attestation file — the file name is the claim about whose word it holds — so a file there
+that is not one (a hand-made `k6.yaml`, say) makes the record `record-unreadable`, exactly like a
+damaged attestation. Keep anything else beside the feature, not inside that directory.
+
+**The one-file record is read forever.** A `verification.yaml` written before the directory existed
+— a federated record with several attestations in it, active or archived — reads exactly as it
+always did while no service has a file of its own. Once services do, it is read beside them: a
+service that records again supersedes its share of the one-file record (that attestation and its
+answers drop out of the union; the file itself is not rewritten), and the write that leaves nothing
+in it counting removes it. An all-at-once record (no `schema`, no attestations) never counts once a
+service has a file — its answers carry no commit attestation — so the first `--service` write
+removes it in the same commit and lists its answers in `discarded`. Answers a write takes off the
+disk that its new file does not carry are reported in `discarded`, tagged `unattested` (an
+all-at-once answer) or `off-checklist` (a claim the current checklist no longer asks). Nothing is
+dropped silently.
+
+**The all-at-once form keeps the one file, by decision.** `--record` without `--service` answers the
+whole checklist from one place on one word, with no commit and no service — so there is no second
+writer for it to collide with and no service to name a file after, and every record it ever wrote
+(the example fleet's included) stays byte-for-byte what it is. There is one reader either way:
+`loam verify`, `status`, `list`, `tasks`, `gate` and `validate` all read the record through the same
+union, whichever files it is made of.
+
+The write holds the same advisory lock archive does, and holds it from before the feature is
+resolved to after the record lands — two `--record` runs for different services serialize (the
+later one waits briefly, then writes its own file, so **both** attestations survive), and a record
+can no longer be written into a path an `archive` is renaming out from under it. The commit itself
+is staged beside the target and swapped in by one rename over the exact bytes the read found, so a
+kill mid-record leaves the previous record whole — never truncated YAML — and an edit that landed in
+between refuses instead of being buried. A write that also removes a superseded one-file record
+holds that removal to the same compare, and lands the service's own file first, so a kill between
+the two leaves a record that still reads whole:
 
 - `docs-busy` — another writer held the lock longer than the record was willing to wait (5 s).
   Nothing was read or written; re-run once it finishes. The contention runs both ways: `archive`,
@@ -2651,9 +3026,10 @@ Recording refuses rather than guesses, each under its own `--json` `error.code`:
 - `repository-unavailable` — `--service` from a repo that declares none, or one whose commit cannot
   be read. An attestation with nothing to bind to is not an attestation.
 - **`record-federated`** — the legacy all-at-once form (`--record` with **no** `--service`) over a
-  record that already carries attestations. That form writes the whole file from one place, so it
-  would erase every other repository's evidence; loam refuses outright and names the attestors, and
-  never silently migrates or merges. Re-run with `--service`.
+  record that already carries attestations, in per-service files or in a one-file record. That form
+  writes the whole record from one place, so it would put one unattested answer set over every
+  other repository's evidence; loam refuses outright and names the attestors, and never silently
+  migrates or merges. Re-run with `--service`.
 - `record-unreadable` — see below.
 
 Reading is unrestricted: `loam verify <FEAT> --service <id>` **without** `--record` is a pure lens
@@ -2662,12 +3038,26 @@ in `services`, which is how you find out which repositories still owe an attesta
 
 The record is YAML, like the other data artifacts, and holds the claim text next to each verdict so
 it reads without loam. Because it has to survive without loam, human edits are expected — and read
-back defensively. A file that exists but does not read as a record (broken YAML, or a shape missing
+back defensively. A record file that exists but does not read as a record (git conflict markers a
+merge left in it — named before the YAML parser sees them, since the parser either fails on a line
+that is not the problem or reads both sides as one plausible document; broken YAML; a shape missing
 what the readers use — `summary` with its counts, `recorded`, `checklist`, claims each with an `id`
-and a known `verdict`) is **`record-unreadable`**: reported with the YAML line, and **never
+and a known `verdict`; or a `verification/<svc>.yaml` holding anything but that one service's
+attestation and answers) is **`record-unreadable`**: reported with the file and the line, and **never
 overwritten**. It used to count as *no record at all*, which was the wrong direction on the one
 artifact loam cannot reconstruct — "no record" invites writing a fresh one over evidence somebody's
-edit merely broke. Only a genuinely absent file is "no verification record". Extra keys a human adds
+edit merely broke. Only a genuinely absent file is "no verification record".
+
+The refusal names the ONE file that failed and the repair that is safe for it, because the two kinds
+of file call for opposite advice. A service's own `verification/<svc>.yaml` holds that service's
+word and nobody else's — after a merge, both sides of a conflict in it are that service's own
+attestations — so repairing it by hand, or deleting it and recording that service again from its
+repository, loses no other team's evidence. The one-file `verification.yaml` may hold every other
+service's attestation, so its advice is to repair it or **restore it from version control** (after a
+merge, the copy on the branch you merged into) and then record again — **never to delete it**. The
+old one-size advice, "delete it and record again", erased other teams' attestations when followed on
+a shared record, and the miscount advice, "record the answers again", sent the reader straight back
+into this refusal: `--record` will not write over a file it could not read. Both now end in a record. Extra keys a human adds
 still pass through untouched. Every verdict names who answered it — `answered_by: runner` (a
 cucumber report's green run, mechanical), `answered_by: external-runner` (a contract-test report's
 operationId-matched green entry, mechanical too), or `answered_by: agent` (somebody's word about the
@@ -2737,7 +3127,7 @@ next `--record` makes it drift-checkable), warn `evidence.unresolved` (the cited
 unsafe, not a regular file, or the cited line is past its end), `evidence.moved` (the file's digest
 differs while the cited line still reads as pinned), `evidence.line-changed` (the cited line no
 longer says what was recorded), `evidence.token-missing` (the file contained the token at the
-attested commit and no longer does) and `evidence.record-unreadable` (a verification.yaml that
+attested commit and no longer does) and `evidence.record-unreadable` (a verification record file that
 exists but cannot be read — none of its evidence was checked, and a silent skip would read as clean,
 on the very file a hand edit to the pins most plausibly breaks). Archived records are deliberately
 not linted — frozen history, and post-ship code drift is normal evolution. From the docs repo the
@@ -2747,13 +3137,18 @@ verdict in either direction, `attested` never silently becomes `verified`, and t
 fail `validate`; `--strict` remains the CI lever it always was.
 
 It lives inside the feature, so `archive` carries it into `features/archive/<FEAT>/` with everything
-else. `loam verify` re-run later compares `checklist` against the current digest and reports the
+else — the `verification/` directory moves with the feature it sits in, and `unarchive` brings it
+back the same way; the frozen view reads it through the same union. `loam verify` re-run later compares `checklist` against the current digest and reports the
 record as **stale** if the feature moved under it — while the feature is active. Once archived there
 is no current checklist to be stale against (the merge itself moved the feature's operations into
 the living OpenAPI, so a re-derived checklist could only disagree): `loam verify` on an archived
 feature renders the record verbatim as **frozen history** (`frozen: true` under `--json`, no
 staleness judgment), and `--record` refuses (`invalid-option` — there is no current checklist for
-the answers to answer): the record is about the words that shipped, and it stays that way.
+the answers to answer): the record is about the words that shipped, and it stays that way. One
+reader holds it to something all the same: `loam gate --since <ref>` grades an archived record
+against the checklist digest `archive` captured as the feature merged (the snapshot manifest's
+`checklist`, above), because the deploy question is whether what shipped was what was checked — a
+record that had gone stale before the archive is `stale` there, never `verified` again.
 
 **Verification does not gate `archive`.** Coherence gates because loam computed it from the
 documents; a verdict is an agent's word about code loam never read, and a gate in front of shipping
@@ -2762,6 +3157,72 @@ comes later, and an `unconfirmed` claim with a note is worth more there than a `
 can back up. `loam verify` exits 0 either way; branch on `verified` in the `--json` payload, or on
 `verdict` when you need to tell `attested` from `unverified`.
 
+### The same checklist read forwards (`loam tasks`)
+
+`loam verify` answers *answered, and by whom*. `loam tasks <FEAT> [--service <id>] [--next]
+[--json]` answers the other half of the same question — *still open, at which step, and what fact
+closes it* — and it is the identical checklist read in the other direction. It is derived on every
+run from the feature's deltas, the generated suite and the verification record; it writes nothing,
+anywhere, ever, and it adds no artifact for a later run to disagree with.
+
+**One unit per promise, and a unit's id is the claim's id.** Every claim the checklist derives is
+one work unit, under the same identity on both commands, so the thing to do and the answer that
+closes it can never be two different objects. One kind of unit has no claim behind it: an ADDED or
+MODIFIED requirement with no scenario under it asks the checklist nothing — there is no scenario to
+test — so `loam tasks` mints a unit of its own for it, of the kind requirement.described. That is
+the promise nobody has written acceptance criteria for yet, and it is where the loop starts.
+
+**Where a unit stands** is its `at` field, and the four values are the steps of the loop this
+document already describes rather than a percentage: `describe` (the requirement carries no scenario
+at all, so there is nothing to generate a test from), `generate` (the scenario exists and this
+repository's generated suite does not carry its stamp yet), `implement` (everything else still
+open), `attested` (an agent's word confirmed the claim and no run has). It is spelled `at`
+deliberately, and not `stage` or `verdict`: both of those already mean something else on payloads an
+agent reads beside this one, and a third meaning for either word is how a consumer comes to branch
+on the wrong field.
+
+**Done is a fact, not a tick.** A closed unit simply stops appearing, and exactly one thing closes
+one: a claim recorded `confirmed` in a verification record that is **not stale** against the current
+checklist. A stale record closes nothing — the words moved under the answers, which is the state
+`loam verify` already reports. An agent-attested scenario never vanishes either: it stays visible at
+`attested`, because attested is not verified, and a work list that hid the difference would be
+exactly the gate that teaches everyone the cheapest way past it is to say yes.
+
+**The frontier** is the first ten open units in derived order, providers before consumers — ordered
+on the exact token join `c4.calls.token == api.exposes.operation`, never on a reading of prose.
+**The order is advice and never a lock**: nothing is assigned, nothing is reserved, and working out
+of order is legal and invisible to every other command.
+
+**`--next` is the leaf**: the same packet with `units` narrowed to the frontier head, which is what
+an orchestrator hands a coding agent. Everything else — the counts, the frontier, the review
+notes — is left whole on purpose, so a cheap model handed one unit cannot read it as the whole job.
+The text view prints that leaf in full: the scenario's body verbatim and never reflowed (the bytes
+the digest was taken over), the digest itself — the same `@loam-digest-<16hex>` join key
+`loam gherkin` stamps and `loam verify --results` matches on — the `done` block whose `check` is the
+fact that closes the unit, and the literal follow-up command to run next, spelled out rather than
+left as a shape to fill in.
+
+**`--service <id>` is a pure lens.** It narrows the units to one service's without binding a
+repository, and adds `waitingOn[]`: the open units in OTHER services that this service's units
+depend on. A team learns what it is blocked by from the same run that tells it what to do.
+
+**What the payload says about what it could not see.** `stamps` is `read` or `unknown`, and
+`unknown` means the bound service repo's generated suite could not be read — could-not-look, never
+nothing-wrong, because a question loam was unable to ask must not read as one that came back clean.
+Beside it the payload carries `checklist` (the digest of the question set these units derive from),
+`record` (`absent`, `recorded`, `stale` or `unreadable`), `intent`, `services[]`,
+`size{requirements,scenarios,operations,messages,calls}` — the size of the DELTA and never of the
+open work, so that "this feature is small" and "this feature is nearly done" cannot become one
+sentence — `contracts{expose[],call[]}`, `counts{open,done,attested}` and `review[]`, the four
+instructions for re-deriving this answer and reviewing it, because a projection that says what to do
+must also say how to check it was read correctly. A broken `delta.likec4` or contract axis names
+what it could not read in `unreadable` and exits 1 with `ok: true` — `loam delta`'s own rule rather
+than a new one: a feeder nothing could read empties the packet, an empty packet reads as "nothing to
+do", so the envelope stays true while the exit code stops a pipeline building on it.
+
+The command mints no finding or refusal code of its own, and `loam_tasks` serves the same projection
+read-only over MCP.
+
 ## Operating at fleet scale
 
 One docs repo, a hundred services, many teams. The repo scales the way any shared codebase does —
@@ -2913,11 +3374,14 @@ repairing anything:
 
   And it reports the **agent surface**: which tool and profile the repo is wired for, how many command and skill
   files it holds, how many a newer loam would lay down (`doctor.agent-files-missing`), and how many
-  have fallen behind (`doctor.agent-files-stale`). The staleness check reads exactly one thing — the
-  `<!-- generated by loam vX.Y.Z -->` line every generated body opens with — and nothing else.
+  have fallen behind (`doctor.agent-files-stale`). A file has fallen behind when BOTH hold: its
+  bytes, the `<!-- generated by loam vX.Y.Z -->` line every generated body opens with set aside, are
+  not what this binary writes; and that stamp is missing or older than this binary. A stamp-only
+  difference is not staleness — the stamp moves in every file at every release, and a warning that
+  fires on every upgrade hides the release where a pointer's body really changed. A customized body
+  under a current stamp is not staleness either: the stamp is the record that somebody reviewed it.
   The digest manifest is what authorizes `init` to refresh an unchanged pointer; a different body is
-  treated as human-owned and never overwritten. A stamp is a separate claim and can be stale while
-  every edit around it is legitimate. Which deliveries a repo holds is asked of the files rather
+  treated as human-owned and never overwritten. Which deliveries a repo holds is asked of the files rather
   than of a record: `loam.json` stores tools and profile, not deliveries, and a repo initialized
   `--no-skills` is not reported as missing the selected skills.
 
@@ -3020,6 +3484,7 @@ and publishes it wherever the fleet view reads:
   "errors": 0,
   "warnings": 2,
   "sources": { "current": 1, "stale": 0, "unvouched": 0, "absent": 0 },
+  "contentStale": 0,
   "generatedAt": "2026-08-03T12:00:00Z"
 }
 ```
@@ -3038,10 +3503,16 @@ loam validate --service "$SVC" --json | jq '{
     unvouched: [.targets[0].findings[] | select(.code == "sources.unvouched")] | length,
     absent:    [.targets[0].findings[] | select(.code == "sources.absent")]    | length
   },
+  contentStale: [.targets[0].findings[] | select(.code == "content.stale")] | length,
   generatedAt: (now | todate)
 }'
 ```
 
+`contentStale` counts the spec documents whose words moved after their vouch — the doc-side half of
+staleness, beside the code-side `sources.stale`. Unlike that half it is not owed to the service repo
+alone (the docs repo's own `validate --all` scorecard counts it too), but a summary that left it out
+would publish "0 stale" over a document nobody re-read.
+
 `generatedAt` is the CI's clock, never loam's — loam output carries no timestamps, by design, so the
 same repo state always yields the same bytes. That is also what makes the timestamp the liveness
 signal: the rule is that every service repo's CI publishes this summary on every run, so a summary
@@ -3111,7 +3582,7 @@ says what its architecture means, and two generated models of the same code disa
 every run — a done-check built on diffing them would flap until somebody turned it off. What is
 deterministic is the **question**: which files, in which grammar, bound to which existing elements;
 which operations, which edges, which scenarios. loam owns the questions and the checking; an agent
-owns the reading. `sources` and `verification.yaml` are where the answers are written down.
+owns the reading. `sources` and the verification record are where the answers are written down.
 
 ## Status