@ybotok/loam 0.2.0-alpha.1 → 0.2.0-alpha.13

package/README.md

@@ -5,13 +5,16 @@
 ![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
 ![node: >=22.22.3](https://img.shields.io/badge/node-%3E%3D22.22.3-brightgreen.svg)
 [![CI](https://github.com/ybotok/loam/actions/workflows/ci.yml/badge.svg)](https://github.com/ybotok/loam/actions/workflows/ci.yml)
-[![npm](https://img.shields.io/npm/v/@ybotok/loam.svg)](https://www.npmjs.com/package/@ybotok/loam)
+[![npm](https://img.shields.io/npm/v/@ybotok/loam/alpha.svg?label=npm%20alpha)](https://www.npmjs.com/package/@ybotok/loam)
 
-> **Pre-release: `0.2.0-alpha.1`**, the first release of the 0.2 line and the newest published
-> version of [`@ybotok/loam`](https://www.npmjs.com/package/@ybotok/loam). It publishes under the
-> `alpha` npm dist-tag: `npm i @ybotok/loam@alpha`, or the exact version, always installs this
-> line. `latest` is moved onto a release by hand once it has published, so a plain
-> `npm i @ybotok/loam` may still resolve to `0.1.0-beta.3` until it is. See [Status](#status).
+> **Pre-release: `0.2.0-alpha.13`** is the version this checkout's `package.json` names, on the 0.2
+> line of [`@ybotok/loam`](https://www.npmjs.com/package/@ybotok/loam). Whether npm serves it is not
+> something this file can know — a version is cut before its publish runs, and a publish can fail
+> after — so **the npm dist-tags are the source of truth**: the badge above reads the `alpha` tag, and
+> `npm view @ybotok/loam dist-tags` prints every tag. Prereleases publish under `alpha`, so
+> `npm i @ybotok/loam@alpha` installs the newest one that did. `latest` is moved onto a release by
+> hand once it has published, so a plain `npm i @ybotok/loam` resolves to an earlier release until it
+> is moved. See [Status](#status).
 
 `loam` keeps an authored C4 model, requirements, API and event contracts, permissions, domain
 vocabulary and verification evidence in explicit agreement as a system changes. The same lifecycle
@@ -70,7 +73,8 @@ Topology changes where loam's checks pay off; it does not change the lifecycle:
   nesting depth, decides which `services/<id>/` owns an element.
 
 For example, the frozen `service` term can name an application while its internal modules remain
-ordinary C4 elements:
+ordinary C4 elements. This is `architecture/landscape.likec4`, the fleet map — the one document
+that declares the kinds:
 
 ```likec4
 specification {
@@ -91,6 +95,11 @@ model {
 }
 ```
 
+The modules can equally live in `services/commerce-app/model.likec4`, which is the ordinary place
+for them once the application has one — as an **extending model**, declaring no kinds of its own and
+saying `extend commerce { … }` on the element above. SCHEMA.md's "Two shapes of a service model" has
+that shape, the older one that parses alone, and the rule that picks between them.
+
 An internal edge normally carries no `metadata { op }`: that key specifically joins a call to the
 governed boundary's OpenAPI contract. An architecture requirement can instead say
 `Covers: commerce.orders -> commerce.billing`. Fleet-level maturity, dependency and scorecard views
@@ -102,13 +111,13 @@ and says what its architecture *means*, and a model that was guessed is worse th
 downstream has to re-derive it to know whether to believe it. So loam takes the half of the job that
 is mechanical: it **states the work** and it **checks the result**. An agent does the reading, and
 both halves are written down: the question in the brief or the checklist, the answer in `sources` or
-`verification.yaml`.
+the verification record.
 
 ### What green means here, and what it does not
 
 Most of this category will tell you what it checks. loam ships the other list too, in the binary:
 **[`src/core/brief/unchecked.ts`](https://github.com/ybotok/loam/blob/main/src/core/brief/unchecked.ts)
-is fifteen statements of what no check will ever tell you**, printed into the adoption brief beside
+is seventeen statements of what no check will ever tell you**, printed into the adoption brief beside
 the checks that do run. It says, in loam's own words, that nothing here knows whether the model is
 the architecture the code actually has, whether a requirement is *true*, whether an `operationId` is
 the one the code serves, or whether `sources` names the files anybody read. And it says the one that
@@ -213,22 +222,42 @@ a contract spelling it `authorizePayment` fails here and nowhere else a team nor
 **Expect a red run, and read it correctly.** Five seeded services with no C4 centre report
 `service.no-model` (error) five times, and `service.no-spec` (warn) five times. Those are not
 misconfiguration: they are a truthful reading of a fleet where adoption has not started, and they
-stay until you write those documents. The finding you came for is the spine one.
+stay until you write those documents. The finding you came for is the spine one. Under the `--base`
+PR gate [below](#guard-the-fleets-edges-on-every-pr), a PR that adds a service's `openapi.yaml`
+stays red until that service has a `model.likec4` — the gate grades the service the PR touched, and
+`service.no-model` is that ratchet working as designed — while a PR that only names operations on
+the map is graded on those edges alone.
 [`test/spine-first.test.ts`](https://github.com/ybotok/loam/blob/main/test/spine-first.test.ts)
 pins this whole sequence against the shipped `examples/fleet.yaml`, so the recipe cannot drift from
 the binary.
 
 From here, [WORKFLOW.md's day zero](WORKFLOW.md#day-zero-onboarding-a-fleet) is the rest: bind each
-service repo, adopt, grade, promote.
+service repo, adopt, grade, promote. Bind each one with the service profile:
+
+```bash
+# in each service checkout, beside the docs repo
+loam init --docs ../docs --service payment-service --agent-profile service
+loam doctor
+```
+
+Pass the profile explicitly. `--agent-profile` defaults to `full`, with `--service` or without it,
+and `full` writes all seven entry points into the checkout — `loam-feature` and `loam-ship` among
+them, the two workflows that author a feature and archive it into the living docs, which the `docs`
+profile gives to the docs repo. `service` writes the five that run beside the code: `loam-adopt`,
+`loam-implement`, `loam-check`, `loam-verify` and `loam-report`. Across a hundred service repos that
+is the difference between one place a cross-service change starts and a hundred places an agent
+can be told to start one. The people in those service repos need about a screen of this:
+[docs/SERVICE-TEAMS.md](https://github.com/ybotok/loam/blob/main/docs/SERVICE-TEAMS.md).
 
 ### Guard the fleet's edges on every PR
 
 Two commands, each installable on its own with no part of the workflow above adopted. **`loam diff`
 exits 1 when a pull request removes an operation or an event message the fleet still consumes**,
-and names the consumers. That question — *who still calls this?* — is the one a fleet answers wrong,
-and it is answerable only from a document that knows the whole fleet. **`loam validate --all --base
-<ref>` grades only the boundaries the branch touched**, which is what lets a strict gate go in on
-the first day of adoption and tighten as the system gets written down.
+and names the consumers — of a removal, a deprecation, or a change to what an operation or message
+returns. That question — *who is joined to this?* — is the one a fleet answers wrong, and it is
+answerable only from a document that knows the whole fleet. **`loam validate --all --base <ref>`
+grades only the boundaries the branch touched**, which is what lets a strict gate go in on the
+first day of adoption and tighten as the system gets written down.
 
 ```yaml
 # .github/workflows/fleet-edges.yml — in the docs repo
@@ -237,34 +266,198 @@ on: pull_request
 jobs:
   edges:
     runs-on: ubuntu-latest
+    env:
+      LOAM: "@ybotok/loam@0.2.0-alpha.13"   # an exact version: bump it in a PR of its own
+      BASE: origin/${{ github.base_ref }}
     steps:
       - uses: actions/checkout@v4
-        with: { fetch-depth: 0 }          # both read the base out of git history
+        with: { fetch-depth: 0 }          # every step reads the base out of git history
       - uses: actions/setup-node@v4
         with: { node-version: 22 }
-      # did you break a consumer?
-      - run: npx -y @ybotok/loam diff --base origin/${{ github.base_ref }}
+      # did you remove something an authored consumer still names? (fails) — and
+      # who is joined to each operation or message you changed? (warns, naming them)
+      - run: npx -y "$LOAM" diff --base "$BASE"
       # did you document what you touched?
-      - run: npx -y @ybotok/loam validate --all --base origin/${{ github.base_ref }} --strict
+      - run: npx -y "$LOAM" validate --all --base "$BASE" --strict
+      # does a changed operation break its readers? oasdiff answers that; loam does not
+      - run: |
+          for spec in $(git diff --name-only --diff-filter=M "$BASE"... -- 'services/*openapi.yaml'); do
+            git show "$BASE:./$spec" > "$RUNNER_TEMP/base.yaml"
+            docker run --rm -v "$RUNNER_TEMP:/base:ro" -v "$PWD:/head:ro" tufin/oasdiff \
+              breaking /base/base.yaml "/head/$spec" --fail-on ERR
+          done
 ```
 
-Two gates, two different questions, and neither is the other's cheaper form. `diff` reports every
-removal against the system's current consumers rather than against a rule list, which is why it
-repays installation before anything else exists. `validate --base` grades the boundaries this
-branch changed, at full strictness, and says out loud how much of the system that was — a run with
-nothing in scope prints that it graded nothing rather than the word valid. Unscoped, neither
-setting is usable on a partly-documented system: `loam validate --all` is green over boundaries
-nobody has written yet, because warnings do not gate, and `--strict` over all of them is red from
-the first minute of adoption until the last one is done.
+**Pin loam, and move the pin on purpose.** An unpinned `npx -y @ybotok/loam` runs whatever the
+`latest` tag points at on the day the job starts, so a release can change what gates your pull
+requests in the middle of a review. Bump `LOAM` in a pull request of its own: run
+`loam subsystem sync` with the new version, update the `<!-- generated by loam vX.Y.Z -->` stamp
+in the docs repo's `AGENTS.md`, and read the release's CHANGELOG entry, which opens with what a
+repository notices after upgrading. Pin the oasdiff image's tag the same way.
+
+Three steps, three different questions, and none is another's cheaper form. `diff` reports every
+removal against the fleet's authored consumers — landscape edges, other services' living
+requirements, use-case hops — rather than against a rule list, which is why it repays installation
+before anything else exists. It names who is joined to a changed operation or message, and it never
+says whether the change breaks them: loam does not read what a schema says, so a renamed required
+field and a new optional one are the same warning to it. That half is oasdiff's, and
+`asyncapi diff`'s for event contracts. A caller drawn on the map with no operation on its edge is
+listed as one nobody could check, never counted as no caller. `validate --base` grades the
+boundaries this branch changed, at full strictness, and says out loud how much of the system that
+was — a run with nothing in scope prints that it graded nothing rather than the word valid.
+Unscoped, neither setting is usable on a partly-documented system: `loam validate --all` is green
+over boundaries nobody has written yet, because warnings do not gate, and `--strict` over all of
+them is red from the first minute of adoption until the last one is done.
+
+An archive's PR stays red under `--base --strict` until its re-vouches land: the merge moves every
+vouched spec it touches under its vouch stamp, so `content.stale` follows, and `loam archive` names
+each such spec and its owner (`revouchOwed`) so those re-vouches can join the same PR.
 
 **A `--base`-scoped validate cannot see a victim boundary the change did not touch.** Remove an
 operation `payment-service` owns, and `checkout-web` — whose living requirement still names it —
 is not in scope, so nothing in that gate reports the broken join. That is `loam diff --base`'s
 question, it stays `loam diff --base`'s, and a green scoped validate is not a statement about the
-consumers of what changed. [WORKFLOW.md](WORKFLOW.md#what-actually-gates) has what each does and
+consumers of what changed. A join the branch itself *wrote* is the other case: a call edge it adds
+or edits in `architecture/` is graded against its provider's contract even with the provider out of
+scope, so the one-letter `authorisePayment` above fails on the PR that introduces it.
+[WORKFLOW.md](WORKFLOW.md#what-actually-gates) has what each does and
 does not grade — including the oasdiff invocation for the byte-level OpenAPI breaking-change
 catalogue, which loam deliberately does not reimplement.
 
+### Check each service repo on its own pull requests
+
+The docs repo's job cannot see provenance. `sources` resolve only inside a service's own
+repository, so `sources.stale` — the code under a vouched spec moved — surfaces only in that
+service repo's CI ([SCHEMA.md](SCHEMA.md), "Operating at fleet scale"). Its committed `loam.json`
+reaches the docs repo through a relative `docsDir` such as `"../docs"`, so the job rebuilds the
+side-by-side layout a laptop has. `actions/checkout` refuses `path: ../docs` — it writes only
+beneath `GITHUB_WORKSPACE` — so check out **both** repositories as subdirectories of the workspace,
+siblings, and run loam from the service's:
+
+```yaml
+# .github/workflows/loam.yml — in each service repo
+name: loam
+on: pull_request
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    env:
+      LOAM: "@ybotok/loam@0.2.0-alpha.13"   # the docs repo's pin: move them together
+      SERVICE: payment-service              # this repo's "service" in its loam.json
+    steps:
+      # Both repositories as siblings under the workspace, the way a laptop holds
+      # them, so the committed "docsDir": "../docs" resolves unchanged.
+      - uses: actions/checkout@v4
+        with: { path: payment-service }
+      - uses: actions/checkout@v4
+        with:
+          repository: acme/docs                       # your docs repo
+          path: docs                                  # the last segment of docsDir
+          token: ${{ secrets.LOAM_DOCS_READ_TOKEN }}  # contents: read on the docs repo
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - name: loam validate --service
+        working-directory: payment-service
+        run: |
+          rc=0
+          npx -y "$LOAM" validate --service "$SERVICE" --json > "$RUNNER_TEMP/loam.json" || rc=$?
+          # one annotation per error and warning; a refusal (docs-missing, …) is one error
+          jq -r '
+            def esc: gsub("%"; "%25") | gsub("\r"; "%0D") | gsub("\n"; "%0A");
+            if .ok then
+              .targets[].findings[] | select(.severity != "ok")
+              | "::\(if .severity == "error" then "error" else "warning" end) title=\(.code)::\(.message | esc) (docs: \(.locations[0].path))"
+            else "::error title=\(.error.code)::\(.error.message | esc)" end
+          ' "$RUNNER_TEMP/loam.json"
+          # the same findings as a table on the run's summary page
+          jq -r '
+            if .ok then
+              "### loam validate --service \(.targets[0].id) — \(.summary.errors) error(s), \(.summary.warnings) warning(s)",
+              "", "| severity | code | finding |", "|---|---|---|",
+              (.targets[].findings[] | select(.severity != "ok")
+                | "| \(.severity) | `\(.code)` | \(.message | gsub("\\|"; "\\|") | gsub("\n"; " ")) |")
+            else "### loam refused: `\(.error.code)`", "", .error.message end
+          ' "$RUNNER_TEMP/loam.json" >> "$GITHUB_STEP_SUMMARY"
+          exit "$rc"
+```
+
+Run from a `payment-service` checkout beside `examples/docs`, in a repository with no
+`src/main/java/` — the source that service's specs name — the step exits 1 and prints:
+
+```text
+::warning title=spine.op-link-missing::payment-service: landscape edge checkout-web → payment-service ("Calls the payment API") has no operation link (metadata { op }) (docs: services/payment-service)
+::error title=sources.path-missing::payment-service: spec.md: 1 source(s) do not exist — src/main/java/ (docs: services/payment-service)
+::error title=sources.path-missing::payment-service: arch.spec.md: 1 source(s) do not exist — src/main/java/ (docs: services/payment-service)
+```
+
+The annotations carry no `file=`, on purpose: every location loam reports is a path in the docs
+repo, which is not the repository this pull request diffs, so GitHub could not place one on a line
+here. They land on the check run and its summary instead. A docs repo that is private needs a token
+that can read it — a fine-grained token or a GitHub App token with `contents: read` on that one
+repository — because the workflow's own `GITHUB_TOKEN` reads only the repository it runs in. Add
+`--strict` once the service is vouched and its warnings are ones you mean to keep at zero; before
+that, the warnings are the adoption still to do.
+
+The same layout answers the deploy question. In the deploy pipeline, check the docs repo out with
+`fetch-depth: 0` — `--since` is read from its git history — and ask whether this service may ship:
+
+```bash
+npx -y "$LOAM" gate --service "$SERVICE" --since "$DOCS_SHA_OF_LAST_DEPLOY"
+```
+
+`gate` executes nothing and writes nothing, and without `--strict` its warnings stay advisory;
+[WORKFLOW.md](WORKFLOW.md#what-actually-gates) says what each finding of it means for a pipeline.
+
+**Cloud agents in a service repo** need the same sibling on disk before they start: a lone clone
+of the service answers every docs-reading command with `docs-missing`. GitHub's Copilot coding
+agent and Codex cloud each start from the one repository the task names and run a setup step you
+own, so clone the docs repo there, into the committed `docsDir`. Copilot reads the job
+`copilot-setup-steps` from `.github/workflows/copilot-setup-steps.yml` on the default branch, and
+an
+[Agents secret](https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/configure-secrets-and-variables)
+reaches those steps as an environment variable:
+
+```yaml
+# .github/workflows/copilot-setup-steps.yml — in each service repo
+name: Copilot setup steps
+on: workflow_dispatch
+jobs:
+  copilot-setup-steps:
+    runs-on: ubuntu-latest
+    permissions: { contents: read }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - run: npm install -g @ybotok/loam@0.2.0-alpha.13
+      # "../docs" is outside the workspace, so git clone rather than actions/checkout;
+      # the second command takes the token back out of the clone's config
+      - run: |
+          git clone --depth 1 "https://x-access-token:${LOAM_DOCS_READ_TOKEN}@github.com/acme/docs.git" ../docs
+          git -C ../docs remote set-url origin https://github.com/acme/docs.git
+      - run: loam doctor
+```
+
+Codex cloud has no workflow file: the same commands go in the environment's setup script, with
+the token as an environment **secret** — Codex hands secrets to the setup script only and removes
+them before the agent phase, which is all a clone needs. Pin Node.js to 22 or newer in the
+environment's package versions, and spell the target from the repository root, because where the
+script starts is not documented:
+
+```bash
+npm install -g @ybotok/loam@0.2.0-alpha.13
+DOCS="$(git rev-parse --show-toplevel)/../docs"
+git clone --depth 1 "https://x-access-token:${LOAM_DOCS_READ_TOKEN}@github.com/acme/docs.git" "$DOCS"
+git -C "$DOCS" remote set-url origin https://github.com/acme/docs.git
+loam doctor
+```
+
+The clone is the agent's reading, not a second place it can deliver. A cloud agent opens its pull
+request against the repository it was started in, so anything it writes into the docs checkout —
+a verification record, a spec edit — stays in its sandbox. `loam-implement`'s own outputs, the
+generated Gherkin and the code, land in the service repo as usual; what belongs in the docs repo
+goes there through that repo's own pull request.
+
 ### Try loam on one governed system in five minutes
 
 The full model may be one application or a fleet; the trial is one repository. In the codebase you
@@ -324,7 +517,7 @@ loam status                         # what to do next, derived from the files
 loam validate --all                 # the CI gate: 0 errors, 10 deliberate warnings
 loam archive FEAT-101 --dry-run     # the whole three-axis merge plan, writing nothing
 loam archive FEAT-112 --dry-run     # an operation being retired, writing nothing
-loam verify FEAT-088                # a shipped feature's done-check: attested
+loam verify FEAT-088                # an archived feature's done-check: attested
 loam verify FEAT-120                # its pair, same check: verified
 ```
 
@@ -343,30 +536,31 @@ cannot hold.
 |---|---|---|
 | `loam init` | `--docs <dir>` `--service <id>` `--create` `--force` `--tools <ids>` `--agent-profile <full\|service\|docs>` `--example <dir>` `--no-commands` `--no-skills` `--mcp` `--mcp-author` | Bind this repository to the single shared docs repo: a committed local `loam.json`, plus command and Agent Skill pointers for detected AI tools. Profiles narrow the six lifecycle workflows to a repo's role; the support-only `loam-report` stays in every profile. Re-running init refreshes only unchanged loam-owned pointers; edited files are preserved. `--mcp` writes the read-only host entry, while `--mcp-author` opts into the bounded authoring tools. `--create` scaffolds the docs repo; `--example` copies the packaged example and stops |
 | `loam seed` | `--from <file>` | Template the fleet map and one `services/<id>/` directory per service from a tiny human-authored `fleet.yaml`. Mechanical, never a guess: a human stated every fact. Refuses once the landscape has been hand-edited |
-| `loam list [services\|features\|capabilities\|glossary]` | `--archived` `--needs-work` `--review-order` `--subsystem <name>` `--owners <path>` | What is in the docs repo, and what is missing from it. `capabilities` rolls up who realizes each promise; `glossary` rolls up each term with the documents that cite it |
+| `loam list [services\|features\|capabilities\|glossary\|suites]` | `--archived` `--needs-work` `--review-order` `--subsystem <name>` `--owners <path>` | What is in the docs repo, and what is missing from it. `capabilities` rolls up who realizes each promise; `glossary` rolls up each term with the documents that cite it; `suites` groups the use cases by `#suite-` tag and names the services each suite needs up (`loam list suites <name>` shows one) |
 | `loam status [<FEAT>]` | `--service <id>` | Where the work stands and what to do next, as a projection over the two gates. Each `next[]` row has an `execution` object that says whether it is runnable, where, and what input or edit is still needed. Derived every run; writes nothing |
 | `loam doctor` | — | Read-only preflight for runtime, config, docs-repo access, fleet roots, counts, and the current service binding. Blockers exit 1; incomplete optional bindings stay warnings |
 | `loam dependencies [<FEAT>]` | — | The active-feature dependency graph and same-identity conflicts, derived from requirement deltas and OpenAPI operationIds |
-| `loam diff` | `--base <ref>` | Semantic diff of the living docs against a base git ref of the docs repo — the review lens for a docs-repo PR, with the current consumers of every removal named. Exit 1 on a removal the fleet still consumes |
+| `loam diff` | `--base <ref>` | Semantic diff of the living docs against a base git ref of the docs repo — the review lens for a docs-repo PR, with the authored consumers of every removal, deprecation and contract change named. Exit 1 on a removal the fleet still consumes |
 | `loam explore [<service>...]` | `--op <operationId>` `--capability <id>` `--as <FEAT>` | Read the fleet around a change nobody has written down yet: the ring one hop out, each service's maturity and living operations, the features already in flight over the same ground, and the `loam new` line the seeds imply |
 | `loam context <service>` | `--feature <FEAT>` | Assemble one service's docs slice — living requirements verbatim, both contracts, the fleet edges around it, permissions, capabilities, provenance, and every active feature's delta over it — as one deterministic briefing |
 | `loam steps` | `--service <id>` `--duplicates` `--json` | Inventory the step phrases of one service's scenarios: how many distinct steps its suite is written in, how few definitions cover most of them, and which phrases differ only by an article or a trailing clause. Reads the living specs, writes nothing — the work-list a team writes its step definitions from, diffed against the optional `services/<svc>/steps.yaml` catalogue when one exists |
-| `loam instructions [<workflow>] [args...]` | `--no-fix-tables` | Print one of the six workflow protocols, the separate `loam-report` support protocol, or one of the four reference pages `loam-codes`, `loam-spine`, `loam-authoring` and `loam-done-check`, version-matched to this binary. Workflow `$1`/`$2` placeholders are filled; support/reference pages take no arguments. Reads no config. `--no-fix-tables` collapses the per-code fix tables to a line each, keeping the paragraph that says which scope graded them: `loam-check`'s page goes 84,151 bytes to 3,541, while a support/reference page holds no such table and comes back byte-identical |
-| `loam explain [<subject>]` | `--codes` | Explain a finding code, a refusal code, or a concept term. Most finding prose is parsed at runtime from the shipped fix tables, so it cannot drift from the binary; the `doctor.*`, `next.*`, `diff.*` and `gate.*` families, which no fix table grades, are answered from a registry written beside them. Every text-mode refusal prints `<code>  ·  loam explain <code>` on stderr and every non-`ok` finding line carries its code in parentheses, so the lookup is reachable without re-running under `--json`. Omit the subject to list the terms; `--codes` lists the whole vocabulary — 293 finding codes and 46 refusal codes, each row the same answer `explain <code> --json` gives for that one |
+| `loam instructions [<workflow>] [args...]` | `--no-fix-tables` | Print one of the six workflow protocols, the separate `loam-report` support protocol, or one of the five reference pages `loam-codes`, `loam-spine`, `loam-authoring`, `loam-done-check` and `loam-drawing`, version-matched to this binary. Workflow `$1`/`$2` placeholders are filled; support/reference pages take no arguments. Reads no config. `--no-fix-tables` collapses the per-code fix tables to a line each, keeping the paragraph that says which scope graded them: `loam-check`'s page, almost all of it fix tables, comes back in a few kilobytes, while a support/reference page holds no such table and comes back byte-identical |
+| `loam explain [<subject>]` | `--codes` | Explain a finding code, a refusal code, or a concept term. Most finding prose is parsed at runtime from the shipped fix tables, so it cannot drift from the binary; the `doctor.*`, `next.*`, `diff.*` and `gate.*` families, which no fix table grades, are answered from a registry written beside them. Every text-mode refusal prints `<code>  ·  loam explain <code>` on stderr and every non-`ok` finding line carries its code in parentheses, so the lookup is reachable without re-running under `--json`. The concept terms cover every word loam prints to a person — the stages (`ready`, `done`), the claim kinds, the `loam tasks` steps, the maturity ladder. Omit the subject to list the terms; `--codes` lists the whole vocabulary — every finding code and every refusal code it can answer, each row the same answer `explain <code> --json` gives for that one |
 | `loam open` | `--root <dir>` `--out <file>` `--force` | Write a `.code-workspace` joining the docs repo and every service checkout whose committed `loam.json` binds to it. Never overwrites without `--force` |
-| `loam mcp` | `--author` | Serve fourteen read tools, version-matched instruction resources and a declared envelope output schema over MCP. `--author` adds `new`, `rebase`, `gherkin` and an archive dry-run; it never exposes `vouch`, verification recording or a committing archive — [the MCP server](WORKFLOW.md#the-mcp-server) |
-| `loam new <FEAT>` | `--title <text>` `--touches <id>` `--new-service <id>` `--capability <id>` | Scaffold a feature: intent, C4 delta, a requirement delta per service named by `--touches`/`--new-service`, and a capability delta per promise named by `--capability` (all repeatable) |
+| `loam mcp` | `--author` | Serve sixteen read tools, version-matched instruction resources and a declared envelope output schema over MCP. `--author` adds `new`, `rebase`, `gherkin` and an archive dry-run; it never exposes `vouch`, verification recording or a committing archive — [the MCP server](WORKFLOW.md#the-mcp-server) |
+| `loam new <FEAT>` | `--title <text>` `--touches <id>` `--new-service <id>` `--capability <id>` `--modifies <Req-ID>` | Scaffold a feature: intent, C4 delta, a requirement delta per service named by `--touches`/`--new-service`, and a capability delta per promise named by `--capability` (all repeatable). `--modifies` copies a touched service's living requirement into an uncommented `## MODIFIED Requirements` block with its `Based-On:` pin already set, so a small change is new → edit → archive; when every touched service is rewritten that way and nothing is introduced, no `delta.likec4` is written |
 | `loam show <service\|FEAT>` | `--type <kind>` | Everything loam knows about one service or feature. A feature's JSON includes a semantic `review` pack: intent, exact architecture objects, API/event slices, dependencies, artifacts, verification, blockers and next actions. `--type` forces an ambiguous reading |
 | `loam subsystem <verb> [names...]` | `--into <name>` `--under <name>` `--title <text>` `--description <text>` `--owner <name>` | Manage the grouping tree under `services/` — a navigable tree no identity depends on. `new`/`rm`, `move … --into`, `rename`, `list`, `history`, `sync` |
-| `loam adopt` | `--service <id>` `--subsystem <name>` `--targets` | Brief an agent to write this service's baseline into the docs repo as `draft`: the target paths, the grammar of each, what the landscape already says, and the checks that follow. Writes nothing. `--targets` narrows it to what varies by service — the walk, the 37 checks and the fifteen statements of what nothing checks are the same bytes everywhere, so a `full` field names the one run that carries them: 42,873 bytes to 17,805 |
+| `loam adopt` | `--service <id>` `--subsystem <name>` `--targets` | Brief an agent to write this service's baseline into the docs repo as `draft`: the target paths, the grammar of each, what the landscape already says — and, for an element no edge touches, the edges the service's own model.likec4 attests — and the checks that follow. Writes nothing. `--targets` narrows it to what varies by service — the walk, the 52 checks and the seventeen statements of what nothing checks are the same bytes everywhere, so a `full` field names the one run that carries them. Both sizes, for the example fleet's payment-service, are in the payload table of [docs/BENCHMARKS.md](https://github.com/ybotok/loam/blob/main/docs/BENCHMARKS.md#what-an-agent-is-handed--payload-sizes), which a test regenerates from the tree |
 | `loam delta <FEAT>` | `--service <id>` | Project a feature onto one service: the intent, its requirement deltas with every body and Given/When/Then line verbatim, the endpoints it adds or retires, and the edges around it. Doubles as a coding-agent task |
+| `loam tasks <FEAT>` | `--service <id>` `--next` | The same checklist `loam verify` grades, read forwards: one work unit per promise the feature makes, each carrying the step it waits on (`describe`, `generate`, `implement`, `attested`) and the fact that closes it — only a confirmed claim in a non-stale verification record retires one, and an attested scenario stays visible. Derived every run and writes nothing. `--service` is a pure lens that adds what this service is waiting on elsewhere, and in a service repository it defaults to that service when the feature touches it; the frontier orders providers before consumers as advice, never a lock. The per-unit work packet, and `--next` is the single leaf packet an orchestrator hands a coding agent |
 | `loam gherkin [<FEAT>]` | `--service <id>` `--dry-run` | Emit spec scenarios as digest-stamped Gherkin `.feature` files into the service repo's `<gherkinDir>/loam/` |
 | `loam rebase [<FEAT>]` | `--service <id>` `--dry-run` `--living` | Pin the feature to the living versions it was written against, on the requirement axis and the contract axis. `--living` takes no feature: it pins the living corpus's `Realizes:` entries to the capability requirements they name, which is what makes `capability.realizes-stale` able to fire later |
 | `loam validate [<id>]` | `--service <id>` `--feature <id>` `--all` `--base <ref>` `--strict` `--errors-only` | Validate one service or feature, or the whole fleet in one run. JSON findings carry `locations[]`: an exact primary location when the check knows one, otherwise the narrowest proved scope. `--base` is the adoption ratchet, not a substitute for `loam diff`; `--strict` exits 1 on warnings; `--errors-only` drops the `ok` confirmations from the text view, keeping every warning |
 | `loam verify <FEAT>` | `--record <file>` `--results <file>` `--contract-results <file>` `--diff-answers <files...>` `--service <id>` | The done-check: derive a checklist of the feature's own promises, and record the answers with their evidence. `--results`/`--contract-results` answer claims from a test report; `--diff-answers` cross-examines two blind answer sets |
 | `loam vouch` | `--service <id>` `--yes` `--pack` `--sample <n>` | The human promotion `draft` → `verified`: stamp a living spec against the code it was written from. `--pack` prints the re-vouch reading pack; `--sample <n>` records a partial read as one. Run in the service's own repo |
-| `loam gate` | `--service <id>` `--strict` | Can this service deploy? A pure query over recorded evidence for deploy pipelines outside loam's lifecycle. Executes nothing, writes nothing; errors exit 1, warnings stay advisory |
-| `loam archive <FEAT>` | `--approve` `--dry-run` | Merge a shipped feature into the living specs, API, events, business tree and landscape; gated on what only the computed merge can see. `--approve` overrides the judgement calls, never the mechanical losses |
+| `loam gate` | `--service <id>` `--since <ref>` `--strict` | Can this service deploy? A pure query over recorded evidence for deploy pipelines outside loam's lifecycle. Executes nothing, writes nothing; errors exit 1, warnings stay advisory. Without `--since` it grades in-flight features only; `--since` (the docs commit the last deploy recorded) adds every feature archived after it |
+| `loam archive <FEAT>` | `--approve` `--dry-run` | Merge a finished feature into the living specs, API, events, business tree and landscape; gated on what only the computed merge can see — the documents, never the code or the verification record. `--approve` overrides the judgement calls, never the mechanical losses |
 | `loam unarchive <FEAT>` | `--force` | Take that back: restore the living docs from the snapshot archive left behind, and re-open the feature |
 | `loam audit-openspec <root>` | `--write-mapping <path>` | Read-only inventory of an OpenSpec checkout/workspace/Store checkout. `--write-mapping` emits the decision skeleton you fill in |
 | `loam migrate-openspec <root>` | `--map <path>` `--mapping <path>` `--apply` `--target <directory>` | Validate a completed mapping against a re-read of the source, and materialize staged migration docs. Dry-run is the default |
@@ -391,7 +585,9 @@ repo it runs in, every `init` writes pointers for the six workflow bodies (`loam
 twenty-one targets**: as a command file you type — `/loam-check` for most, `/loam:check` where the
 tool namespaces by directory, `@loam-check` in Amazon Q's prompt library — and as an Agent Skill
 at `<tool-dir>/skills/loam-<x>/SKILL.md`, which the model loads by itself when the task matches. Two
-targets are skills only: Codex reads `.codex/skills/` and loads no custom command files, and
+targets are skills only: Codex loads no custom command files, and its target writes
+`.codex/skills/` — a root Codex still reads but no longer documents (its skills page names only
+`.agents/skills`; select `agents` too if you want the documented one) — and
 `agents` is not a tool at all but the vendor-neutral `.agents/skills/` root that Cursor, GitHub
 Copilot, Codex, Gemini CLI, Zed and Roo Code each document reading — one copy those six share
 instead of six copies of the same bytes. `--no-commands` and `--no-skills` each suppress one
@@ -429,29 +625,34 @@ run. That split exists because the two go stale in opposite directions and only
 fixable: embedded protocol text eventually describes a different loam with total confidence, while
 the command cannot. Pointing at the binary is also what makes the protocol
 affordable to load: `loam instructions loam-check --no-fix-tables` prints the same page with its
-per-code fix tables collapsed to a line each — 84,151 bytes down to 3,541 — and
-`loam explain <code> --json` answers, in 473 bytes, whichever two or three of those rows a run
-actually reported. A copy frozen into the generated file would have charged the full 84 KB every
-session, and gone stale doing it. `AGENTS.md` itself was the one generated file that argument did
+per-code fix tables collapsed to a line each — from a page that is almost all tables down to a few
+kilobytes — and `loam explain <code> --json` answers, one code at a time, whichever two or three of
+those rows a run actually reported. What each of those costs in bytes and tokens, page by page, is
+[docs/BENCHMARKS.md](https://github.com/ybotok/loam/blob/main/docs/BENCHMARKS.md)'s payload table,
+generated from the tree rather than typed. A copy frozen into the generated file would have charged
+the whole page every session, and gone stale doing it. `AGENTS.md` itself was the one generated file that argument did
 not reach — it was the process contract *and* the reference manual, and every session paid for all
 of it — so four **reference pages** now come out of the binary instead, printed by
 `loam instructions`: `loam-codes` (which codes each invocation can raise), `loam-spine` (every join
 between the artifacts, and the `Based-On:` pins), `loam-authoring` (`arch.spec.md`, the generated
-Gherkin suite, frontmatter) and `loam-done-check` (how `loam verify` derives its claims, and
-verified versus attested). What stayed is what a reader needs to form a question at all: the layout,
-the cycle, which element is which service, the validator's rules and the archive gate. The current
-orientation is **8,762 bytes**, below both the 32,768-byte Codex chain limit and the smaller 12,000
-workspace-rule ceiling. Detailed pages are fetched only when the task reaches them. `loam init`
+Gherkin suite, frontmatter, and writing a feature a reviewer can follow) and `loam-done-check` (how
+`loam verify` derives its claims, and verified versus attested). A fifth page, `loam-drawing`,
+never stood in `AGENTS.md`: it teaches how to draw the map so that a person can read it — one
+relationship kind per kind of traffic, an arrow only where evidence gives one, a legend, and
+overview views that each answer one question. What stayed is what a reader needs to form a question at all: the layout,
+the cycle, which element is which service, the validator's rules and the archive gate. The
+orientation stays below both the 32,768-byte Codex chain limit and the smaller 12,000-byte
+workspace-rule ceiling — `test/agents.test.ts` fails the build the day it does not. Detailed pages are fetched only when the task reaches them. `loam init`
 writes **no file** for a reference page: a page printed on demand describes the loam you are
 running, not the one that scaffolded the repository.
 
 The code inventory is that same split applied twice, and the largest page is what it left behind.
-`loam instructions loam-codes` lists which codes each invocation can raise — 331 of the 335 the
-scaffolded docs name between them, the one fact no other surface carries — and no longer says what
+`loam instructions loam-codes` lists which codes each invocation can raise — nearly every code the
+scaffolded docs name, and the one fact no other surface carries — and no longer says what
 any of them means, because `loam explain <code>` answers that from the binary actually running and a
 paragraph written once at `init` cannot. Dropping the duplicated gloss came first and took the file
 from 120,896 bytes to 109,399; moving the inventory off it took the remaining 79,679. The OpenSpec
-migration codes keep their notes inline on the page, because they are 49 of the 51 codes
+migration codes keep their notes inline on the page, because they are almost all of the codes
 `loam explain` does not answer yet, and a pointer to an explanation that does not exist is worse
 than the prose it replaced.
 
@@ -481,15 +682,21 @@ always preserved byte for byte, with the entry printed for manual merge.
 - [COMPARISON.md](COMPARISON.md) — where loam fits beside architecture-as-code tools, software and
   event catalogs, contract verification and diff engines, requirements traceability, and code-level
   architecture checks. Each is treated as a neighbouring specialist, not an opponent loam needs to
-  replace.
+  replace. One dated section sets out what the spec-driven change tools — OpenSpec, Spec Kit and
+  Kiro — each offer for a change that crosses repositories, what is still open upstream, and where
+  loam differs.
 - [MIGRATING-from-OpenSpec.md](MIGRATING-from-OpenSpec.md) — moving an OpenSpec repo onto loam: what
   maps, what is lost, what must be added.
 - [ROADMAP.md](ROADMAP.md) — the evidence-backed improvement plan, priorities, non-goals and exit
   criteria.
-- [CHANGELOG.md](CHANGELOG.md) — released beta.1–alpha.1 plus the changes on `main` under
+- [CHANGELOG.md](CHANGELOG.md) — released beta.1–alpha.13 plus the changes on `main` under
   `[Unreleased]`.
+- [docs/SERVICE-TEAMS.md](https://github.com/ybotok/loam/blob/main/docs/SERVICE-TEAMS.md) — one
+  screen for a team whose repository is one service in the fleet: the commands, the slash
+  commands, what to know before vouching, and the codes they will actually meet.
 - [docs/BENCHMARKS.md](https://github.com/ybotok/loam/blob/main/docs/BENCHMARKS.md) — what a
-  fleet-sized run costs, with the method, the machine and the committed runs behind every number.
+  fleet-sized run costs, with the method, the machine and the committed runs behind every number,
+  and what each payload loam hands an agent weighs in bytes and tokens.
 
 ## Development
 
@@ -502,9 +709,9 @@ npm run arch:check          # package-level dependency graph stays acyclic
 npm test                   # vitest
 npm run test:coverage      # full src/**/*.ts coverage with enforced thresholds
 npm run test:package       # clean, pack, install the tarball, run its loam binary
-# optional, against the exact upstream checkout named in MIGRATING-from-OpenSpec.md (the
-# flag matters: --baseline defaults to canary, and the sweep refuses a checkout
-# at any other HEAD):
+# optional, against the exact upstream checkout named in MIGRATING-from-OpenSpec.md
+# (--baseline defaults to release, the certified pin; every pinned baseline refuses a
+# checkout at any other HEAD, and only --baseline latest sweeps an unpinned one):
 npm run test:openspec-corpus -- --baseline release /path/to/OpenSpec
 ```
 
@@ -520,17 +727,19 @@ component baselines, the `architecture/permissions.yaml` authorization vocabular
 authored-capability axes with the `Realizes:` join, use cases graded as `dynamic view`s, the
 `glossary/<term>.md` domain vocabulary checked through the links that cite it, and the
 `architecture/obligations.yaml` architectural obligations checked through `#obl-` tags and
-`Covers:`. Known limits, each with its owner in [ROADMAP.md](ROADMAP.md): the complete gate still
-needs repeatable CI and installed-package evidence observed from an actual push. Speculative
-`render`, health composition and UI generation come later. Behind that status stand **156 test files** (counted 2026-09-01): the count is graded
+`Covers:`. Known limits, each with its owner in [ROADMAP.md](ROADMAP.md): the scheduled CI
+`stability` job has still to be observed green. Speculative `render`, health composition and UI
+generation come later. Behind that status stand **205 test files** (counted 2026-10-22): the count is graded
 against a live readdir by `test/docs-facts.test.ts`, so this sentence fails the suite the moment it
 trails the tree.
 
-The package is published as [`@ybotok/loam`](https://www.npmjs.com/package/@ybotok/loam), currently
-`0.2.0-alpha.1`: the unscoped `loam` name is taken by an unrelated GDAL wrapper, so the package ships
-under the maintainer's own npm user scope. Releases are tag-driven and maintainer-only
-([CONTRIBUTING.md](CONTRIBUTING.md)); the version this line names is pinned to `package.json` by a
-drift test, so it cannot silently trail a release.
+The package is published as [`@ybotok/loam`](https://www.npmjs.com/package/@ybotok/loam): the
+unscoped `loam` name is taken by an unrelated GDAL wrapper, so the package ships under the
+maintainer's own npm user scope. Releases are tag-driven and maintainer-only
+([CONTRIBUTING.md](CONTRIBUTING.md)). This checkout is `0.2.0-alpha.13` — a version pinned to
+`package.json` by a drift test, so it is always the version of the checkout you are reading, and for
+that reason it says nothing about whether that version reached npm.
+`npm view @ybotok/loam dist-tags` is the answer to what installs.
 
 ## Contributing