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

package/WORKFLOW.md

@@ -19,7 +19,7 @@ that order.
   [Why there is no task list](#why-there-is-no-task-list)
 - [Picking the work back up](#picking-the-work-back-up)
 - [Day zero: onboarding a fleet](#day-zero-onboarding-a-fleet) · [Command notes](#command-notes) ·
-  [The MCP server](#the-mcp-server)
+  [The MCP server](#the-mcp-server) · [Build on the envelope](#build-on-the-envelope)
 
 ## The two flows
 
@@ -97,7 +97,10 @@ no fleet manifest, deliberately — the wiring is one file per repo, and it is r
    entry, in one journaled transaction, and guesses nothing: a human stated every fact in the file,
    which is what keeps seed on the same side of the no-extractor line as `loam new`. Re-running is
    safe — once the landscape has been hand-edited, seed refuses (`seed-landscape-edited`) rather
-   than overwrite it.
+   than overwrite it. That makes seed a day-zero step: list every service id you already know in
+   `fleet.yaml` up front, because the first `metadata { op }` below has no spelling in
+   `fleet.yaml`. From then on the map grows without seed — `loam adopt --service <id>` briefs the
+   element and edges a new service adds, and a feature's C4 delta carries every other change.
 
    Drawing it by hand instead is entirely legal, and the landscape is a **required** artifact
    either way, not an optional one: `loam validate --all` reports `landscape.missing` as an error
@@ -113,11 +116,13 @@ no fleet manifest, deliberately — the wiring is one file per repo, and it is r
    repo:
 
    ```bash
-   loam init --docs ../docs-repo --service payment-service   # no --create: it JOINS
-   loam doctor                                               # confirms the wiring
+   loam init --docs ../docs-repo --service payment-service --agent-profile service   # no --create: it JOINS
+   loam doctor                                                                        # confirms the wiring
    ```
 
-   `--service` is the binding: without it `loam vouch` and `loam gherkin` refuse outright, and
+   `--agent-profile service` writes the five workflows that run beside the code. Without it the
+   profile is `full`, which also writes `loam-feature` and `loam-ship` — the two workflows the docs
+   repo keeps — into the service checkout. `--service` is the binding: without it `loam vouch` and `loam gherkin` refuse outright, and
    `loam verify --service --record` / `--results` refuse to attest, because none of them will write
    a service's documents from a repo that has not said which service it is. Reading —
    `loam verify --service` on its own — needs no binding, because it writes nothing. Commit the
@@ -137,7 +142,8 @@ no fleet manifest, deliberately — the wiring is one file per repo, and it is r
    stamping the source and content digests that make later staleness detectable. `loam list --json`
    in the docs repo then grades the whole fleet on the presence ladder
    `empty → partial → documented → sourced → vouched`, and `loam list --needs-work` is the remaining
-   worklist.
+   worklist — including any vouched service whose spec moved after the vouch (`vouched (stale)`,
+   missing a re-vouch), which `loam status` names as `next.revouch`.
 
 Steps 3–6 repeat per service and are independent — no ordering, no lock, no shared state between two
 services' runs — so ten services can be onboarded by ten people in parallel. The one file they all
@@ -155,9 +161,9 @@ configurable graph, because a governed system needs one lifecycle and one meanin
 | `delta.likec4` | feature | no | New elements and edges, each tagged with the feature id. The design. A requirements-only change deletes it |
 | `specs/<svc>/spec.md` | service | yes | The behaviour delta — `ADDED` / `MODIFIED` / `REMOVED` requirements, each with Given/When/Then scenarios |
 | `specs/<svc>/arch.spec.md` | service | no | The architectural obligations a business spec never mentions: outbox, retries, idempotency, alerts. Same grammar, plus `Covers:` lines tying each to the C4 elements it accounts for |
-| `specs/<svc>/openapi.yaml` | service | conditional | The contract delta. Required where the fleet map shows somebody calls this service |
-| `specs/<svc>/asyncapi.yaml` | service | no | The event-contract delta: a complete AsyncAPI 3.0 document restating the living contract around the changed slots. `loam rebase` pins restated slots (`x-loam-based-on`), `x-loam-remove: true` retires one |
-| `verification.yaml` | feature | yes | The done-check record: every claim, its answer, its evidence, and who gave it |
+| `specs/<svc>/openapi.yaml` | service | conditional | The contract delta: only the operations the feature adds, changes or removes — an operation it leaves out stays as the living contract has it. Required where the fleet map shows somebody calls this service |
+| `specs/<svc>/asyncapi.yaml` | service | no | The event-contract delta: an AsyncAPI 3.0 document holding only the slots the feature adds, changes or removes. `loam rebase` pins each one the living contract already has (`x-loam-based-on`), `x-loam-remove: true` retires one |
+| `verification/<svc>.yaml` | feature | yes | The done-check record, one file per attesting service: every claim, its answer, its evidence, and who gave it. The all-at-once form writes the one file `verification.yaml` instead |
 
 Two fleet/living axes sit beside this feature graph. `services/<svc>/asyncapi.yaml` joins
 `publishes`/`consumes` edges to `Publishes:`/`Consumes:` requirements, and the event axis carries
@@ -175,7 +181,7 @@ present and fine. Marking everything required is how an axis that is optional ev
 reported as missing everywhere and then ignored.
 
 **Dependencies are enablers, not gates — with one real exception.** You can author these in any
-order. `verification.yaml` is the exception, and it is a genuine impossibility rather than a
+order. The verification record is the exception, and it is a genuine impossibility rather than a
 preference: its checklist is *derived* from the delta and the per-service specs, so with none of
 them written there is no question set to answer. That artifact alone comes back `blocked`, naming
 what it is waiting on.
@@ -265,16 +271,39 @@ runs already recorded (the join partners' documentation state, staleness, the ve
 of the features touching the service, an interrupted docs commit). Its verdict is advice to a
 pipeline loam does not own — advisory by default, `--strict` the per-invocation CI lever — and it
 deliberately changes nothing about what gates the archive: verify still never gates the merge, and
-archive still reads no verification record.
+archive still reads no verification record. Know what `--strict` buys before wiring it: its
+freshness check reads `content.stale` over the gated service **and every documented join partner**,
+so one partner whose spec moved under its vouch — every archive into a vouched spec does that —
+turns this service's `gate --strict` red until that partner's owner re-vouches from their own repo.
+That is the question asked honestly (a deploy joins documents nobody has re-read), but it is
+another team's queue: a pipeline that must not wait on it runs `gate` without `--strict` and
+branches on the `content.stale` findings in `checks[]` itself.
+
+Which features it grades is the one thing a pipeline has to say. Without `--since`, the gate reads
+**in-flight features only**: a feature leaves the check the moment it is archived, so a slice that
+deploys after its feature shipped is gated without it — and under `--strict`, archiving would be
+the cheapest way past an unverified-feature warning. `loam gate --since <ref>` closes that: pass
+the docs-repo commit your last deploy recorded, and every feature archived after it (its
+`features/archive/<FEAT>/` directory absent at the ref, or changed since — a feature unarchived,
+edited and archived again ships again) that touches the service is graded too, under the same
+`gate.feature-unverified`, its `features[]` row carrying `archived: true`. Its record is frozen, but
+held to the checklist `loam archive` captured as the feature merged (`checklistAtArchive` on the
+row): a record that had stopped answering the feature before it shipped reads `stale`, so archiving
+is no longer a way past the warning. A feature archived by a loam that captured no checklist is read
+as frozen history, and the row says so (`checklistAtArchive: null`). The ref is
+read from the docs repo's own git exactly as `loam diff --base` reads its base, with the same
+refusals when git cannot answer. loam stores nothing for it — the pipeline already knows which docs
+commit it deployed from.
 
 **`loam diff` does not add one either — it is the review lens.** On a docs-repo PR,
 `loam diff --base origin/main` says what the branch *changes* in fleet-meaningful terms: services,
 requirements (by identity and content digest, so a rebase pin is not a change), operations,
-messages, and the cross-service joins between them — with the current consumers of every removal
-named, which is what a reviewer actually needs to know. `validate --all` remains the fleet gate;
-diff exits 1 on a removal the fleet still consumes (`diff.op-removed-consumed`,
-`diff.message-removed-consumed`) — and also whenever a document on either side could not be read,
-because a suspended axis is reported, never graded as "nothing changed" — so a PR job gets those
+messages, and the cross-service joins between them — with the authored consumers of every removal,
+deprecation and contract modification named, which is what a reviewer actually needs to know.
+`validate --all` remains the fleet gate; diff exits 1 on a removal the fleet still consumes
+(`diff.op-removed-consumed`, `diff.message-removed-consumed`) — and also whenever a document on
+either side could not be read, because a suspended axis is reported, never graded as "nothing
+changed" — so a PR job gets those
 checks for free, but a green diff is not a valid fleet: run both. For the byte-level OpenAPI
 breaking-change catalogue, use oasdiff on the two states of one contract; [the `loam diff` command
 note](#command-notes) below has the exact invocation, and loam deliberately does not reimplement
@@ -312,16 +341,16 @@ repository, while the runtime page cannot go out of date the same way.
 
 `AGENTS.md` — the one file `init` lays down that every host auto-loads, and so the first thing an
 agent reads — now works the same way, which changes the reading order. It is orientation only (the
-layout, the cycle, what gates and what only advises, at 8,762 bytes rather than 109,399), and the
-four **reference pages** it used to carry inline come out of the binary at the moment the question
-arises: `loam instructions loam-codes`, `loam-spine`, `loam-authoring` and `loam-done-check`, each
-taking no arguments and printing whole, listed beside the six workflows by a bare
-`loam instructions`. `init` writes no file for any of them, so nothing new landed in the repo.
+layout, the cycle, what gates and what only advises, held under a 12,000-byte ceiling a test enforces
+where it used to be 109,399 bytes), and the four **reference pages** it used to carry inline come
+out of the binary at the moment the question arises: `loam instructions loam-codes`, `loam-spine`,
+`loam-authoring` and `loam-done-check`, each taking no arguments and printing whole, listed beside
+the six workflows by a bare `loam instructions`. `init` writes no file for any of them, so nothing new landed in the repo.
 
 | Workflow | When | What it drives |
 |---|---|---|
 | `loam-adopt` | Once per service, before any feature touches it | `loam adopt` briefs the baseline; an agent reads the code and writes it as `draft`; validate twice — the service, then the fleet — and hand to a human to vouch |
-| `loam-feature` | Starting a change | `loam explore` to decide what it touches, `loam new` to scaffold, author the delta and the specs, `loam rebase` to pin, `loam validate`, `loam dependencies` |
+| `loam-feature` | Starting a change — after asking whether it needs a feature at all (step 0) | `loam explore` to decide what it touches, `loam new` to scaffold, author the delta and the specs, write what they leave open under `## Open questions` in `intent.md` (ungraded), `loam rebase` to pin, `loam validate`, `loam dependencies` |
 | `loam-implement` | Building one service's slice, in that service's repo | `loam delta` is the task, `loam gherkin` emits the acceptance criteria, step definitions come before code |
 | `loam-check` | Any time; always before shipping | `loam validate`, and fixing what it reports by code |
 | `loam-verify` | When the code is built | `loam verify` derives the checklist; the test runner answers what it can; you answer the rest with evidence |
@@ -371,6 +400,22 @@ this command just makes sure you are weighing all of it.
 
 ### The honestly-small change
 
+**The smallest change needs 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 — changes nothing in the docs repo, so there is nothing to scaffold,
+pin or archive. It is a code PR in the service repo, and then, in that repo:
+
+```bash
+loam validate --service payment-service       # the only place sources.stale is visible
+loam vouch --pack --service payment-service   # read-only: what the moved sources owe a re-read
+```
+
+`sources.stale` names the paths that moved since the spec was last vouched, the pack is the reading
+list, and the vouch itself is a person's. That is lighter than a feature by construction rather than
+by exemption: there is no delta for a gate to grade, and the one signal that did move — the vouch —
+is still owed. The moment the change alters what a requirement promises, it is a feature, however
+small, and the lane below is the floor. `loam-feature`'s step 0 asks the same question first.
+
 Most changes are not cross-service features. A one-service, requirements-only change — a new
 refusal, a tightened invariant, behaviour behind an endpoint that already exists — walks the same
 graph with most of it not owed, and the tooling already says so. The whole loop:
@@ -405,15 +450,15 @@ Every command takes `--json`, and the contract is built so an agent never has to
 - **Findings carry stable codes** — `c4.valid`, `spine.op-undefined`, `coherence.ok`. Branch on the
   code. Prose gets reworded; codes do not.
 - **The protocol has a narrowed form, and one code is answerable as data** —
-  `loam instructions loam-check` is 84,151 bytes, almost all of it the per-code fix tables, and
-  `--no-fix-tables` prints the same page at 3,541 with each table's scope paragraph kept. Branch on
-  the code, then `loam explain <code> --json` for the two or three a run reported (473 bytes each),
-  or `loam explain --codes --json` once for the whole vocabulary — 293 finding codes and 46 refusal
-  codes, 339 of the 390 loam emits. The four families no fix table grades (`doctor.*`, `next.*`,
-  `diff.*`, `gate.*`) are among them, so a code read out of a `status`, `doctor`, `diff` or `gate`
-  payload is answerable as data like any other; the 51 that are not are the OpenSpec migration
-  surface (`openspec.*`, `mapping.*`), which an agent meets once before the repository is governed
-  at all, and two `ok`-severity confirmations.
+  `loam instructions loam-check` is almost all per-code fix tables, and `--no-fix-tables` prints the
+  same page in a few kilobytes with each table's scope paragraph kept. Branch on the code, then
+  `loam explain <code> --json` for the two or three a run reported, or `loam explain --codes --json`
+  once for the whole vocabulary — every finding and refusal code `loam explain` answers. The four
+  families no fix table grades (`doctor.*`, `next.*`, `diff.*`, `gate.*`) are among them, so a code
+  read out of a `status`, `doctor`, `diff` or `gate` payload is answerable as data like any other;
+  the codes that are not are the OpenSpec migration surface (`openspec.*`, `mapping.*`), which an
+  agent meets once before the repository is governed at all, and a couple of `ok`-severity
+  confirmations.
 - **`validate --json` already carries the fix for every code it raised** — `fixes` is a map keyed by
   code, so joining `findings[].code` to `fixes[code]` answers "what now" out of the payload you are
   holding: no `loam explain` round trip per code, and no fix table loaded into context to read one.
@@ -481,10 +526,13 @@ A task list authored beside a spec is a second mutable state. It drifts — the
 checklist does not, and now two documents describe the work and only one of them is checked. The
 question a task list answers is a good one; the file is the wrong place to answer it.
 
-loam derives the answer instead, at two altitudes:
+loam derives the answer instead, at three altitudes:
 
 - **What to do next**, from `loam status`: the artifact table plus an ordered `next[]`, recomputed
   every run, so it cannot disagree with the files.
+- **Which promise to pick up, and what closes it**, from `loam tasks <FEAT>`: one unit per promise
+  the feature makes, each carrying the step it is waiting on and the fact that retires it. `--next`
+  narrows it to the single leaf packet an orchestrator hands one coding agent.
 - **What to build**, from `loam delta <FEAT> --service <svc>`: the intent, every requirement body
   and every Given/When/Then line reproduced verbatim, the endpoints added or retired, and the edges
   around it. That output *is* the coding task, and it is regenerated from the spec each time rather
@@ -501,6 +549,15 @@ input — a human's statement of the problem, which nothing can derive. The desi
 operations against the contracts. A prose design document beside those would be a third description
 of the same change, and the only one nothing grades.
 
+The third altitude is new; the decision above is not. `loam tasks` is the `loam verify` checklist
+read forwards — the same claims under the same ids, one unit per promise, each with the fact that
+closes it — recomputed on every run from the delta, the generated suite and the verification record.
+It is still not a file: nothing to tick, nothing to commit, nothing that can disagree with the
+documents it was derived from, and so the reason there is no `tasks.md` is unchanged. A unit leaves
+the list only when a confirmed claim in a non-stale verification record retires it, and an
+agent-attested scenario stays on it at `attested` rather than being ticked off — the work list must
+not be able to say more than the record does.
+
 ## Picking the work back up
 
 The three states worth naming, because each has one command:
@@ -577,10 +634,21 @@ replaces it with a `full` field naming the one run that carries them, which is 5
 (`rev-parse`/`ls-tree`/`show`, read-only, no checkout), so it refuses (`repository-unavailable`)
 when the docs repo has no history to ask and (`unknown-target`) when `--base` resolves to no commit
 there. What it reports is the *joined*, fleet-meaningful delta — a removed operation is graded
-against the landscape edges and living requirements that still name it (`diff.op-removed-consumed`,
-exit 1), a removed message against its `Consumes:` lines and consumes-edges — and an artifact
+against the consumers the archive gate reads too ([SCHEMA.md](SCHEMA.md), "Who still consumes it"):
+the edges of the `architecture/` project, other services' `Operations:` lines in either spec file
+(not one naming its own service's operation of the same id) and the use-case hops attributed to it
+(`diff.op-removed-consumed`, exit 1); a removed message against its `Consumes:` lines,
+consumes-edges and hops — and an artifact
 unreadable on either side suspends that subject's axis and exits 1, because "nobody could look" must
-never read as "nothing changed". `validate --all` remains the fleet gate; diff is the review lens.
+never read as "nothing changed". The exception is an `openapi.yaml` or `asyncapi.yaml` that cannot be
+read but is byte-identical at the base (an AsyncAPI 2.x file nobody has converted yet): the branch did
+not touch it, so it is skipped rather than failing every PR. A spec file stays suspended even then,
+because another service's removal may be the one that could not be checked against it.
+A landscape edge into the provider drawn with no `metadata { op }`
+is the same doubt at warning strength: it is listed as a consumer nobody could check, never dropped.
+An operation or message whose own node or `$ref` closure moved is `diff.op-modified` /
+`diff.message-modified` — a warning that names the same consumers and does not say whether the
+change breaks them. `validate --all` remains the fleet gate; diff is the review lens.
 For the byte-level OpenAPI breaking-change catalogue, run oasdiff on the two states of one contract:
 `git -C <docs> show <ref>:./services/<id>/openapi.yaml > base.yaml && oasdiff breaking base.yaml <docs>/services/<id>/openapi.yaml`
 (the `./` resolves the path relative to the docs directory rather than the git root, so this holds
@@ -594,7 +662,11 @@ landscape the branch changed since a base git ref of the docs repo — which is
 both passing on the first day of adoption and tightening after it, and which for that reason
 grades nothing outside the branch: the consumer whose living requirement still names an operation
 this branch removed is not in scope, so that finding is `loam diff`'s and never this run's, and a
-scope holding no target says it graded nothing rather than reporting the word valid.
+scope holding no target says it graded nothing rather than reporting the word valid. The landscape
+is graded by what in it the branch changed: a call edge the branch added or edited is checked
+against its provider's contract even when the provider is out of scope, and the fleet-wide
+vocabulary warnings (a permission, capability, obligation or glossary term nothing cites) and the
+AGENTS.md stamp ride the run only when the file that carries them changed.
 
 **`loam gherkin`** — a feature's changed requirements, or (without a feature) the full living suite.
 Deterministic, digest-stamped, regeneration-owned; run in the service's own repo.
@@ -603,21 +675,45 @@ Deterministic, digest-stamped, regeneration-owned; run in the service's own repo
 on every operation in the contract delta that the living docs already hold; what this feature is
 *adding* has nothing to pin against, and the output says so per item. On the requirement axis that
 stops a second feature rewriting the same requirement from landing on top of the first in silence;
-on the contract axis it also marks the rest of the delta as **quotation** — an `openapi.yaml` is a
-complete document, so without the pin the merge upserts operations you only restated and reverts
-whatever landed on them. Restamping is the last step of resolving a collision, not the resolution —
-the output says which pins moved.
-
-**`loam verify`** — `--results <report.json>` answers the scenario claims from a cucumber JSON run,
+on the contract axis it also tells an edit from a **quotation** — the merge upserts every operation
+the delta spells, so without the pin an operation you only quoted reverts whatever landed on it.
+The cheaper fix is not to quote: a feature's `openapi.yaml` or `asyncapi.yaml` holds only what it
+adds, changes or removes, the merge leaves every operation it does not spell exactly as the living
+contract has it, and a local `$ref` resolves into the living document — so an add-only contract
+delta has nothing to pin and needs no rebase. Each quote costs a pin, and a pinned quote whose living
+operation a parallel feature removes becomes `openapi.baseline-invalid`, an error that blocks the
+archive until the quote is deleted, with `openapi.op-revived` beside it — while an unpinned one is
+`openapi.op-revived` alone (`asyncapi.slot-revived` on the event axis), which gates the archive too,
+because the merge would read the retired operation as an addition and put it back. Rebase pins neither as new: it prints
+the same finding (`revived[]` in `--json`), and whether the quote goes or the feature re-adds the
+operation on purpose is the author's call. It judges the delta as it will write it, pins included:
+a quote repinned over whatever now lives at an address an archived feature moved the operation away
+from becomes an edit the merge writes, and that revival is reported by the rebase (or `--dry-run`)
+that makes it, not first by the next validate. Restamping is the last step of resolving a collision,
+not the resolution — the output says which pins moved.
+
+**`loam verify`** — `--results <report.json>` answers the scenario claims from a test run,
 digest-matched, so only a green run confirms one, and the record writes down which file it read
-(path, sha256, mtime). It answers *only* those claims, so on a feature with open `service.exists` /
-`api.exposes` claims it is passed alongside `--record` or refused (`answers-mismatch`).
-`--record <answers.json>` takes the agent's answers, refusing anything unevidenced — under
-`--service`, refusing a `file:line` that does not resolve in that repo at the attested commit — and
-a scenario claim answered that way makes the record `attested` rather than `verified`. A
-cross-service feature is recorded **once per service repo** with `--service <id>`, each run adding
-its own commit-bound attestation to one shared record; the `--service`-less `--record` form writes
-the whole record from one place and is refused (`record-federated`) once anyone else has attested.
+(path, sha256, mtime). It reads two shapes: a cucumber JSON report (cucumber-js, cucumber-jvm,
+behave, SpecFlow/Reqnroll, pytest-bdd `--cucumberjson` and godog's cucumber formatter all write
+one), in which a matched scenario must also have run exactly the stamped scenario's number of
+steps — a hand-tagged stub is not that scenario's run — or loam's runner-neutral
+`{"loamScenarioReport": 1, "results": [{"digest": "…", "status": "passed"}]}`, which a JUnit,
+pytest, Vitest or house runner's report is adapted into. Anything else, JUnit XML included, is
+refused naming both (`answers-unreadable`). It answers *only* those claims, so on a feature with
+open `service.exists` / `api.exposes` claims it is passed alongside `--record` or refused
+(`answers-mismatch`). `--record <answers.json>` takes the agent's answers, refusing anything
+unevidenced — a `file:line` that does not resolve to a real line in this repository, and under
+`--service` one that does not resolve at the attested commit — and a scenario claim answered that
+way makes the record `attested` rather than `verified`. A
+cross-service feature is recorded **once per service repo** with `--service <id>`, each run writing
+its own commit-bound attestation to a file of its own, `features/<FEAT>/verification/<id>.yaml` —
+the directory is the record, so two teams' attestations on two docs-repo branches merge cleanly. The
+`--service`-less `--record` form writes the whole record from one place, into the one file
+`verification.yaml`, and is refused (`record-federated`) once anyone else has attested. A record
+file that will not read (`record-unreadable`, git conflict markers included) is named with its safe
+repair: a service's own file may be deleted and recorded again by that service; the one-file
+`verification.yaml` may hold other services' attestations and is restored, never deleted.
 
 **`loam unarchive`** — it refuses rather than guesses: `snapshot-stale` when a merged file moved
 since (`--force` says that was meant), and `snapshot-corrupt` when a pre-image no longer hashes to
@@ -649,8 +745,8 @@ archive is undone, an interrupted unarchive is *finished*, because the merged te
 is written down nowhere else — or refusing with `commit-interrupted` when a file has been edited
 since. `loam doctor` reports that state rather than calling the repo healthy.
 
-The gate itself comes in two kinds. Coherence, an unknown service and the OpenAPI plan are judgement
-calls, and `--approve` carries them; two refusals are mechanical loss and `--approve` deliberately
+The gate itself comes in two kinds. Coherence (a revived retired operation among it), an unknown
+service and the OpenAPI plan are judgement calls, and `--approve` carries them; two refusals are mechanical loss and `--approve` deliberately
 does not — a living document still holding git conflict markers (`merge-failed`) and a living
 requirement that has strayed outside `## Requirements` (`living-outside-requirements`). loam's docs
 files must be **UTF-8** for the same reason: undecodable bytes refuse the merge (`merge-failed`,
@@ -666,19 +762,37 @@ beside the methods, addresses no operation and retires nothing; archive refuses
 (`openapi.remove-marker-path-level`) rather than publishing a meaningless key into the fleet's
 living contract. Validation refuses stale, mismatched, or unjustified markers; archive deletes the
 method without persisting the marker or garbage-collecting components, and reports the removals in
-both text and JSON. See [SCHEMA.md](SCHEMA.md) for the lifecycle contract.
+both text and JSON. See [SCHEMA.md](SCHEMA.md) for the lifecycle contract. A delta that defines
+another operationId where a living operation lives replaces it there, and when the merged contract
+then defines it nowhere the gate grades it like a retirement: `openapi.remove-op-consumed` while an
+edge of the `architecture/` project, another service's requirement, a use-case hop, or the
+provider's own requirement as the merge would leave it still names the old id — so a rename redraws
+the edge and restates its requirement in the same change, or defines the old operation at another
+address if it is to stay. Every consumer is read after the feature's merge, so retiring one in the
+same feature (MODIFY or REMOVE the requirement that names it) is a fix the gate sees.
+
+A retirement also stays retired. The archive gate reads the removal markers every feature under
+`features/archive/` left behind, and refuses a delta that spells an HTTP operation, a channel, an
+event operation or a message one of them retired while the living contract no longer holds it —
+or spells one at an address one of them retired it from or moved it away from while it lives on
+elsewhere, which would put it back beside where it lives, judged on the contract the merge would
+write (`openapi.op-revived`, `asyncapi.slot-revived` — warnings that gate). Without it, a parallel
+feature that had merely quoted the operation archived second and put it back at exit 0.
+`--approve` re-adds it on purpose, and the archive output names what came back and whose
+retirement it reverses. A removal made by hand-editing a living contract, or an archive deleted
+from disk, leaves no marker, and the gate cannot see it.
 
 ## The MCP server
 
-For hosts that reach tools through MCP rather than a shell, `loam mcp` serves the fourteen read
-commands — `validate`, `status`, `list`, `show`, `delta`, `explore`, `dependencies`, `diff`,
-`doctor`, `context`, `gate`, `steps`, `explain`, `instructions` — as MCP tools (`loam_validate` …
-`loam_instructions`) over stdio, newline-delimited JSON-RPC 2.0, protocol revision 2025-06-18 (older
-revisions negotiated down; JSON-RPC batch arrays refused). Every tool is advertised
-`readOnlyHint: true` and `openWorldHint: false`, which is what a host needs to run one without
-stopping to ask its user: the first says the call cannot change the repository, the second that it
-cannot reach anything outside the directory the server was launched in — and both are true of the
-whole base table only because the writing commands are kept out of it. It also publishes
+For hosts that reach tools through MCP rather than a shell, `loam mcp` serves the sixteen read
+commands — `validate`, `status`, `list`, `show`, `delta`, `tasks`, `explore`, `dependencies`,
+`diff`, `doctor`, `context`, `adopt`, `gate`, `steps`, `explain`, `instructions` — as MCP tools
+(`loam_validate` … `loam_instructions`) over stdio, newline-delimited JSON-RPC 2.0, protocol
+revision 2025-06-18 (older revisions negotiated down; JSON-RPC batch arrays refused). Every tool is
+advertised `readOnlyHint: true` and `openWorldHint: false`, which is what a host needs to run one
+without stopping to ask its user: the first says the call cannot change the repository, the second
+that it cannot reach anything outside the directory the server was launched in — and both are true
+of the whole base table only because the writing commands are kept out of it. It also publishes
 `loam://orientation` and every `loam://instructions/<name>` page as Markdown resources, so the host
 can load version-matched guidance progressively; `loam://instructions/loam-check/compact` omits the
 large fix table and pairs with `loam explain <code>`. A typical host entry:
@@ -712,3 +826,99 @@ gets coherent `no-config` envelopes, not silence. Calls run strictly one at a ti
 `loam_validate` blocks the queue for its duration; MCP requests carry ids and hosts tolerate the
 latency. Even author mode excludes `vouch`, verification recording and a committing archive:
 human trust and irreversible lifecycle transitions stay under the CLI permission flow.
+
+## Build on the envelope
+
+loam makes no network call, so it syncs with no tracker, dashboard or catalog — and does not need
+to. Every command's `--json` is a stable contract, and the integrations are a few lines of shell
+over it, owned by whoever runs them. Four recipes, each run against `examples/docs`.
+
+**Feature work into a tracker.** `loam tasks <FEAT> --json` lists every open unit of a feature:
+`id`, `subject` (the owning service), `claim`, `done` (its `check` is the fact that closes it) and
+`dependsOn` (unit ids to finish first). The unit id is the idempotency key — prefixed with the
+feature id, so one tracker holds every feature's units and each title says which — and a re-run
+opens issues only for units it has not seen:
+
+```bash
+existing=$(gh issue list --state all --limit 1000 --json title --jq '.[].title')
+loam tasks FEAT-101 --json \
+  | jq -r '.feature as $f | .units[] | ["[\($f) \(.id)]", .subject, .claim, .done.check, (.dependsOn | map("[\($f) \(.)]") | join(" "))] | @tsv' \
+  | while IFS=$'\t' read -r key svc claim check after; do
+      grep -qF "$key" <<<"$existing" && continue
+      gh issue create --title "$key $claim" --body "Service: $svc. Done when: $check. After: ${after:-nothing}"
+    done
+```
+
+On the example's FEAT-101 that is nineteen issues the first time and none the second. A finished
+unit leaves `units[]` once the evidence its `check` names is recorded, so the issues to close are a
+set difference against the last export. **A unit's id is a hash of what it says**, which is what
+makes it a key and also its one hazard: rewording a scenario — its name or any Given/When/Then line
+— or renaming a requirement that carries no `Requirement-ID:` mints a new id. The next export opens
+a fresh issue, and the old one is orphaned: it drops out of `units[]` exactly as a finished unit
+does, so read the set difference before closing anything as done, and carry the orphan's history
+over by hand. Renaming a requirement that does carry a `Requirement-ID:` keeps every id. The same
+loop drives `jira` or any CLI that creates an issue from a title and a body.
+
+**The fleet view of every service repo's CI.** Staleness is visible only from each service repo,
+so each one's CI publishes the per-service summary (SCHEMA.md, "The per-service summary a CI
+pipeline publishes") wherever your fleet view reads. Rolling those up is a join against the list of
+services the docs repo knows, so a service that never reported reads as unknown and never as clean:
+
+```bash
+jq -s 'map({(.service): .}) | add // {}' summaries/*.json > reports.json
+loam list --json | jq -r --slurpfile r reports.json '
+  .services[] | .id as $id | $r[0][$id] as $s
+  | [$id,
+     if $s == null then "unknown: no report"
+     elif now - ($s.generatedAt | fromdateiso8601) > 86400 then "unknown: last report \($s.generatedAt)"
+     elif $s.valid | not then "invalid: \($s.errors) error(s)"
+     elif $s.sources.stale + $s.contentStale > 0 then "owes a re-vouch: \($s.sources.stale) source-stale, \($s.contentStale) content-stale"
+     else "clean" end]
+  | @tsv'
+```
+
+The day-old cutoff is a policy and yours to set; what is not a policy is that `generatedAt` comes
+from the CI's clock, never loam's, so an old one means that repo stopped reporting.
+
+**Which services must be up for suite X.** A fleet usually keeps that answer by hand — a compose
+file, a CI matrix, a paragraph in a runbook — and it drifts from the journeys it is for. Tag each
+cross-service use case with the suites it runs in (`#suite-smoke` on its `dynamic view`, declared in
+the landscape's `specification`; one journey may carry several) and `loam list suites <name>`
+derives it: the union of the suite's participants, resolved to service ids through the same join the
+step grades use. The participants no service stands for are listed beside them rather than dropped —
+the person who drives the flow, an `#external` topic or partner — because a stand that comes up
+short fails its journey against something nobody was told to start:
+
+```bash
+loam list suites smoke --json | jq -r '
+  if .useCases.unreadable then error("architecture/ did not parse: \(.useCases.error)") else . end
+  | .suites[0] | (.services[] | "up \(.)"), (.unresolved[] | "stand-in \(.element)\(if .external then " (#external)" else "" end)")'
+```
+
+On the example that is three services up — checkout-web, notification-service, order-service — and
+two stand-ins: `customer`, and `kafka.orderEvents`, `#external` through its kind. Tagging a journey
+also opts it in to grading, so a suite cannot list a hop the map does not declare
+(`usecase.step-unbacked`); `ungrouped[]` names the use cases in no suite, and an unknown suite name
+refuses `unknown-target` rather than answering an empty environment.
+
+**LikeC4's own MCP server beside loam's.** The fleet map is plain LikeC4, so LikeC4's MCP server
+runs on the same docs repo with no configuration — `npx likec4 mcp --stdio .` from the docs root
+exposed eighteen tools on the example, measured at the 1.59.2 pin loam carries: element, view and
+relationship reads, graph traversals, metadata and tag queries. Run the likec4 loam itself depends
+on (`npm ls likec4` names it), so the server parses the grammar loam validates. The two answer
+different questions: `loam mcp` the joins, gates and lifecycle state; `likec4 mcp` the model as a
+graph. One host entry carries both:
+
+```json
+{
+  "mcpServers": {
+    "loam": { "command": "loam", "args": ["mcp"] },
+    "likec4": { "command": "npx", "args": ["likec4", "mcp", "--stdio", "."] }
+  }
+}
+```
+
+Two differences to know. LikeC4's server reads the root project, which excludes `features/**`, so
+it sees the living map and never an in-flight delta — ask `loam show <FEAT> --json` for those. And
+seventeen of its tools advertise `readOnlyHint`; `apply-semantic-layout` does not, so a host will
+ask before running it.

package/dist/cli.js

@@ -11,6 +11,7 @@ import { registerShow } from "./commands/show/show.js";
 import { registerStatus } from "./commands/status/status.js";
 import { registerSubsystem } from "./commands/subsystem/subsystem.js";
 import { registerDelta } from "./commands/delta/delta.js";
+import { registerTasks } from "./commands/tasks/tasks.js";
 import { registerDiff } from "./commands/diff/diff.js";
 import { registerGherkin } from "./commands/gherkin/gherkin.js";
 import { registerRebase } from "./commands/rebase/rebase.js";
@@ -30,7 +31,7 @@ import { registerOpen } from "./commands/open.js";
 import { registerInstructions } from "./commands/instructions.js";
 import { registerExplain } from "./commands/explain/explain.js";
 import { registerMigrateOpenSpec } from "./commands/migrate-openspec/migrate-openspec.js";
-import { emitJsonError } from "./core/envelope/json.js";
+import { emitJsonError, sayExplain } from "./core/envelope/json.js";
 import { LOAM_VERSION } from "./core/envelope/version.js";
 /**
  * The whole CLI surface, as a program nobody has parsed yet.
@@ -69,6 +70,7 @@ export function buildProgram() {
     registerStatus(program);
     registerSubsystem(program);
     registerDelta(program);
+    registerTasks(program);
     registerDiff(program);
     registerGherkin(program);
     registerRebase(program);
@@ -93,10 +95,10 @@ export function buildProgram() {
  * The two lines under the command list: where to start, and what to run when
  * lost.
  *
- * {@link HELP_GROUPS} does nearly all of the orienting work — twenty-nine
+ * {@link HELP_GROUPS} does nearly all of the orienting work — thirty
  * commands under seven headings, in the order of the work — but it stops one
  * step short of the two facts a newcomer does not have. Nothing on the page
- * said that `init` must run before any of the other twenty-eight, and nothing
+ * said that `init` must run before any of the others, and nothing
  * named the command that answers "what now"; the last thing a first
  * `loam --help` printed was `help [command]`.
  *
@@ -123,7 +125,7 @@ export const HELP_EPILOG = [
  * protocols (`loam instructions`) rather than inventing a second taxonomy, so a
  * reader who has met one has met the other.
  *
- * Twenty-nine commands printed as one flat registration-ordered list tells a
+ * Thirty commands printed as one flat registration-ordered list tells a
  * new reader nothing about which four to run first. NOTHING IS HIDDEN — a
  * hidden command is a command an agent cannot discover, and every one of these
  * still parses, still appears, and still carries the same flags. This is
@@ -135,7 +137,7 @@ const HELP_GROUPS = {
     explore: "Read the fleet", context: "Read the fleet", dependencies: "Read the fleet",
     explain: "Read the fleet", instructions: "Read the fleet", steps: "Read the fleet",
     adopt: "Adopt what exists", vouch: "Adopt what exists",
-    new: "Change it", delta: "Change it", gherkin: "Change it", rebase: "Change it",
+    new: "Change it", delta: "Change it", tasks: "Change it", gherkin: "Change it", rebase: "Change it",
     subsystem: "Change it",
     validate: "Check it", diff: "Check it", verify: "Check it", gate: "Check it",
     archive: "Ship it", unarchive: "Ship it",
@@ -144,7 +146,7 @@ const HELP_GROUPS = {
 /**
  * Apply {@link HELP_GROUPS}, and FAIL CLOSED on a command it does not name.
  *
- * The throw is the point. A thirtieth command added without a heading would
+ * The throw is the point. A thirty-first command added without a heading would
  * otherwise land silently in an "unclassified" bucket at the bottom of the
  * page, which is the drift this whole file's neighbours are written to prevent;
  * `test/help-groups.test.ts` catches it at gate time, and this catches it the
@@ -162,6 +164,19 @@ function groupCommands(program) {
 }
 /** CommanderError codes whose output (already printed) is the point, not a failure to wrap. */
 const PASS_THROUGH = new Set(["commander.help", "commander.helpDisplayed", "commander.version"]);
+/**
+ * What a text-mode usage error prints under commander's own diagnostic: the
+ * fix and the stable code, the two lines every other refusal carries through
+ * `fail`. Without them `loam diff` with no `--base` printed commander's one
+ * sentence and nothing else — the only refusals in the CLI a person could not
+ * look up, while `--json` already reported them as `invalid-option`.
+ */
+function sayUsageFix(program) {
+    const name = process.argv.slice(2).find((token) => program.commands.some((c) => c.name() === token));
+    const help = name === undefined ? "`loam --help` lists the commands" : `\`loam ${name} --help\` lists the arguments and options it takes`;
+    console.error(`Fix the invocation: ${help}.`);
+    sayExplain("invalid-option");
+}
 function main() {
     const program = buildProgram();
     // Set once a command's action actually runs: every subcommand declares its own
@@ -194,8 +209,11 @@ function main() {
             // Anything else is a usage error (unknown option/command, missing or
             // invalid argument). Commander has already printed its diagnostic to
             // stderr, and that line stays: the invariant below is about stdout only.
-            if (!PASS_THROUGH.has(err.code) && jsonRequested()) {
-                emitJsonError("invalid-option", err.message.replace(/^error: /, ""));
+            if (!PASS_THROUGH.has(err.code)) {
+                if (jsonRequested())
+                    emitJsonError("invalid-option", err.message.replace(/^error: /, ""));
+                else
+                    sayUsageFix(program);
             }
             process.exitCode = err.exitCode;
             return;