@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.13

package/dist/core/explain/refusals.js

@@ -0,0 +1,49 @@
+export const REFUSAL_MEANINGS = {
+    "no-config": "No loam.json at or above the working directory — the repo is not wired to a fleet; run `loam init --docs <dir>` once per repository rather than letting a command guess where the fleet lives.",
+    "config-invalid": "loam.json exists but cannot be loaded — repair the file (or delete it and re-run `loam init`); the code is distinct from `no-config` because running init over a corrupt config would silently rewrite it.",
+    "unknown-target": "The name resolves to nothing this command can address — no such service, feature, workflow or subject; the message offers the closest known names.",
+    "invalid-option": "The invocation itself is wrong — flags that contradict each other, a value that cannot be right, or a mistyped flag or command; nothing was read or written, and with `--json` anywhere in the arguments even commander's own usage errors arrive as this envelope.",
+    "already-exists": "Refusing to create over something that already exists — a feature directory, a workspace file, a name already claimed in the subsystem namespace — because overwriting would destroy work nobody asked to lose.",
+    "sources-absent": "`loam vouch` refuses to stamp a document that names no `sources` — with nothing tying the document to code, the staleness signal a vouch exists to power could never fire.",
+    "sources-path-missing": "`loam vouch` refuses to stamp: a listed source does not exist in the service repo, or is a glob pattern (not supported) — the digest would cover a different file set than the author meant.",
+    "not-coherent": "`loam archive` refuses: the feature has coherence issues, carried in `issues[]` with a per-issue `overridable` — fix the gating ones, or `--approve` the judgment calls; a refusal `--approve` cannot move says so in the message.",
+    "living-outside-requirements": "`loam archive` refuses: the LIVING spec holds a requirement outside its `## Requirements` section, and the merge rewrites only that section, so the requirement would land in the file twice — the fix is in the living document, and `--approve` does not override it.",
+    "archive-exists": "`loam archive` refuses: `features/archive/` already holds a directory for this feature — a destination collision, not a merge problem; move the old archive entry aside first.",
+    "merge-failed": "The merge — or a journaled writer's one-file commit — could not be computed or was rolled back; the living docs are unchanged, and re-running can work.",
+    "rollback-incomplete": "A failed write could not be fully undone: some files were not put back, and the message lists them — the one refusal that needs a human before anything else runs against the repo.",
+    "feature-active": "`loam unarchive` refuses: a `features/` directory for this feature already exists outside the archive, so restoring would write over work in flight — remove or rename it, then re-run.",
+    "snapshot-missing": "`loam unarchive` refuses: the archive carries no snapshot of what it overwrote (it predates snapshots, or was written by a different loam) — restore the living docs from version control instead.",
+    "snapshot-stale": "`loam unarchive` refuses: a file the archive wrote changed after it — a living document, another feature's document whose links into this one it rewrote, or one of the feature's own documents it relinked under `features/archive/` — so restoring is no longer an undo; re-run with `--force` to restore anyway, deliberately discarding those later changes.",
+    "snapshot-corrupt": "`loam unarchive` refuses: a snapshot pre-image no longer matches the digest the archive recorded for it, so restoring would write text nobody wrote — `--force` does not override this one; restore from version control.",
+    "commit-interrupted": "A journaled writer (archive, unarchive, rebase, vouch, new, gherkin, a recording verify) was killed mid-commit and this run cannot repair the leftovers on its own — the docs may be half-written; run the command the message names, or `loam doctor` for the file-by-file account.",
+    "restore-failed": "`loam unarchive` failed and everything was rolled back — nothing was restored, the living docs are unchanged, and re-running can work.",
+    "answers-unreadable": "A recording `loam verify` could not read a user-named file — the answers JSON, or a cucumber/contract report — as what it claims to be; fail-closed: nothing was recorded, so fix the file and re-run.",
+    "answers-mismatch": "The answer set does not answer the current checklist — an id not on it, a claim with no answer, or an entry for a claim a passed report already owns; re-derive the checklist and answer exactly what it asks.",
+    "answers-unevidenced": "A `confirmed` answer carries no evidence — evidence is `file:line`, and a claim you cannot show is `unconfirmed` with a note saying why, which is a successful record, not a failure.",
+    "service-mismatch": "A command that must run inside one service's own repository was told `--service` for a service this repository's loam.json does not declare: a recording `loam verify`, whose attestation must be bound to the code it is about; `loam gherkin`, whose .feature files land in that service's checkout; or `loam vouch`, whose `sources` resolve there. Run it from that service's own repo.",
+    "unknown-service": "Federated verify recording: the selected service is not one this feature's checklist (or the docs repo) knows, so there is nothing its attestation could bind to — fix the id.",
+    "repository-unavailable": "The repository this operation must be bound to (or read from) cannot be answered for — most commonly a writing `loam verify`, a `loam gherkin` or a `loam vouch` run where loam.json declares no `service` at all (the docs repo, usually), or a docs repo that cannot be enumerated — so the command refuses rather than guessing which service it is about.",
+    "record-federated": "`loam verify --record` without `--service` over a federated (schema 2) record — per-service files under `verification/`, or a one-file record carrying attestations — the all-at-once form would put one unattested answer set over other repositories' attestations, so it is refused naming the attestors; record per service instead.",
+    "record-unreadable": "A file of the verification record (`verification.yaml`, or one service's `verification/<svc>.yaml`) exists but cannot be read — broken YAML, git conflict markers, a summary contradicting its claims, or a per-service file holding anything but its own service's attestation. It is never overwritten and never reported as absent. The message names the file and the safe repair: a service's own file holds only that service's word, so it may be repaired, or deleted and recorded again from that service's repo; the one-file `verification.yaml` may hold other services' attestations, so it is repaired or restored from version control (after a merge, the copy on the branch you merged into), never deleted.",
+    "record-raced": "`loam verify --record` found the record changed between its locked read and the swap — an editor or a lock-ignoring writer landed first; nothing was written, and re-running merges over the record as it now stands.",
+    "gherkin-conflict": "`loam gherkin <FEAT>` would overwrite a `.feature` file owned by another feature still in flight — the whole emission refuses and names the owner; archive or coordinate with that feature first.",
+    "vouch-raced": "`loam vouch` found the spec changed between reading and stamping — another vouch or an edit landed first; nothing was written, so re-read and re-run.",
+    "vouch-unattended": "`loam vouch` with nobody on the other end of stdin and no `--yes` — the stamp is a person's claim to have read the document, and nobody was asked.",
+    "vouch-unattributable": "`loam vouch` could not learn who is vouching — git names no `user.email` here — and a stamp with nobody behind it records only that the word was written; set your git identity and re-run.",
+    "vouch-declined": "`loam vouch` asked and the person said no — nothing was stamped; a successful refusal, not a failure.",
+    "docs-missing": "`docsDir` in loam.json points at nothing — the docs repo was never cloned, or the path is wrong; a read command refuses rather than reporting an empty fleet, and `loam doctor` names the wiring to fix.",
+    "services-missing": "`docsDir` is a directory but holds no `services/` — it is some other directory, most often the service repo itself after a typo; fix the pointer rather than scaffolding a second source of truth beside the real one.",
+    "docs-busy": "Another loam writer holds the docs repo's advisory lock — nothing was read or written, and re-running once it finishes works; a lock nothing will ever release shows up in `loam doctor` as a blocker.",
+    "subsystem-not-empty": "`loam subsystem` rm refuses a subsystem that still holds members — services or child subsystems, named in the message — because a destructive command never picks targets the caller did not name; move them out first, then re-run.",
+    "move-uncommitted": "A subsystem move/rename refuses because git reports uncommitted or untracked paths under a directory being moved, or in a document outside it whose links the move would rewrite — the move would sweep them into a change nobody reviewed; commit, `git stash -u`, or remove them, then re-run.",
+    "move-failed": "A subsystem move/rename failed and was rolled back cleanly — every rename undone, the generated views file restored, the docs unchanged; re-running can work.",
+    "no-members": "`loam open` found no service checkout bound to this docs repo under any scanned root — the workspace would hold only the docs repo; clone a bound checkout beside it, or point `--root` at where the checkouts live.",
+    "binding-duplicate": "Two discovered repositories' committed loam.json files declare the same `service` for this docs repo — loam will not guess which checkout speaks for the service; narrow the scan with `--root`, or fix the stray binding.",
+    "owners-unreadable": "`loam list --owners` could not use the named CODEOWNERS file — the path cannot be read, or a line does not parse as `pattern owner…` (the message names the line); fail-closed, because a half-read ownership file must never file a service under the wrong team.",
+    "seed-file-invalid": "`loam seed`'s fleet file is missing, unreadable, not YAML, the wrong shape, carries an illegal id — or no longer names every existing `services/<id>/` (that refusal lists the exact ids as `missingServices`); the message names the file and line, and editing the file and re-running succeeds.",
+    "seed-duplicate-service": "fleet.yaml declares one name twice — as two services, or as both a service and an external/subsystem; service ids, subsystem names and externals share one flat namespace, both declaration lines are named, and renaming one fixes it.",
+    "seed-unknown-subsystem": "A service's `subsystem:` in fleet.yaml names nothing `subsystems:` declares — the message carries a did-you-mean over the names the file really declares; add the subsystem or fix the spelling, then re-run.",
+    "seed-landscape-edited": "architecture/landscape.likec4 carries hand edits (the line-1 stamp's digest no longer matches) or was authored some other way, which includes anything written ABOVE the scaffold's stub — `loam seed` never overwrites human work and wrote nothing. Seed runs once, before any operation is drawn: fleet.yaml cannot carry `metadata { op }`, publishes or consumes, so once the map holds them it grows without seed — `loam adopt --service <id>` for a new service, a feature's C4 delta for everything else. Folding the edits into fleet.yaml and deleting the file works only when every edit is a service, subsystem or plain call fleet.yaml can say.",
+    internal: "An unexpected throw — the one refusal with no stable meaning; it exists so a `--json` consumer still receives an envelope instead of a stack trace, and a repeatable `internal` is a loam defect worth reporting.",
+};
+//# sourceMappingURL=refusals.js.map

package/dist/core/explain/refusals.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"refusals.js","sourceRoot":"","sources":["../../../src/core/explain/refusals.ts"],"names":[],"mappings":"AAiBA,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC9B,WAAW,EACT,gMAAgM;IAClM,gBAAgB,EACd,4MAA4M;IAC9M,gBAAgB,EACd,oJAAoJ;IACtJ,gBAAgB,EACd,qQAAqQ;IACvQ,gBAAgB,EACd,iNAAiN;IACnN,gBAAgB,EACd,4KAA4K;IAC9K,sBAAsB,EACpB,8LAA8L;IAChM,cAAc,EACZ,oOAAoO;IACtO,6BAA6B,EAC3B,yQAAyQ;IAC3Q,gBAAgB,EACd,gLAAgL;IAClL,cAAc,EACZ,yJAAyJ;IAC3J,qBAAqB,EACnB,qLAAqL;IACvL,gBAAgB,EACd,yLAAyL;IAC3L,kBAAkB,EAChB,oMAAoM;IACtM,gBAAgB,EACd,kWAAkW;IACpW,kBAAkB,EAChB,2NAA2N;IAC7N,oBAAoB,EAClB,sRAAsR;IACxR,gBAAgB,EACd,wIAAwI;IAC1I,oBAAoB,EAClB,wMAAwM;IAC1M,kBAAkB,EAChB,gNAAgN;IAClN,qBAAqB,EACnB,uLAAuL;IACzL,kBAAkB,EAChB,6XAA6X;IAC/X,iBAAiB,EACf,gLAAgL;IAClL,wBAAwB,EACtB,+VAA+V;IACjW,kBAAkB,EAChB,0UAA0U;IAC5U,mBAAmB,EACjB,+rBAA+rB;IACjsB,cAAc,EACZ,uNAAuN;IACzN,kBAAkB,EAChB,mMAAmM;IACrM,aAAa,EACX,uJAAuJ;IACzJ,kBAAkB,EAChB,oJAAoJ;IACtJ,sBAAsB,EACpB,6LAA6L;IAC/L,gBAAgB,EACd,uGAAuG;IACzG,cAAc,EACZ,0MAA0M;IAC5M,kBAAkB,EAChB,wNAAwN;IAC1N,WAAW,EACT,wMAAwM;IAC1M,qBAAqB,EACnB,sOAAsO;IACxO,kBAAkB,EAChB,kSAAkS;IACpS,aAAa,EACX,+JAA+J;IACjK,YAAY,EACV,sNAAsN;IACxN,mBAAmB,EACjB,4NAA4N;IAC9N,mBAAmB,EACjB,oQAAoQ;IACtQ,mBAAmB,EACjB,oSAAoS;IACtS,wBAAwB,EACtB,yOAAyO;IAC3O,wBAAwB,EACtB,+MAA+M;IACjN,uBAAuB,EACrB,ioBAAioB;IACnoB,QAAQ,EACN,mNAAmN;CACzK,CAAC","sourcesContent":["/**\n * One sentence per envelope refusal code, for `loam explain`.\n *\n * This is the one deliberate restatement in the explain lookup, and the\n * compiler is its drift test: unlike the finding codes — whose prose ships in\n * the /loam-check fix tables and is PARSED at runtime (fix-tables.ts) — the\n * `ErrorCode` union's meanings live only in doc comments, which are erased,\n * so there is no runtime constant to read. `satisfies Record<ErrorCode,\n * string>` makes the pairing exhaustive both ways: a new union member cannot\n * ship without a row here (missing key fails typecheck), and a row for a\n * retired code fails the same way. What tsc cannot pin is accuracy — a\n * reworded doc comment can drift from its sentence — which is why each row\n * stays ONE sentence in the union's own voice (what happened, what it means,\n * whether re-running can work) rather than growing a paragraph of its own.\n */\nimport type { ErrorCode } from \"../envelope/json.js\";\n\nexport const REFUSAL_MEANINGS = {\n  \"no-config\":\n    \"No loam.json at or above the working directory — the repo is not wired to a fleet; run `loam init --docs <dir>` once per repository rather than letting a command guess where the fleet lives.\",\n  \"config-invalid\":\n    \"loam.json exists but cannot be loaded — repair the file (or delete it and re-run `loam init`); the code is distinct from `no-config` because running init over a corrupt config would silently rewrite it.\",\n  \"unknown-target\":\n    \"The name resolves to nothing this command can address — no such service, feature, workflow or subject; the message offers the closest known names.\",\n  \"invalid-option\":\n    \"The invocation itself is wrong — flags that contradict each other, a value that cannot be right, or a mistyped flag or command; nothing was read or written, and with `--json` anywhere in the arguments even commander's own usage errors arrive as this envelope.\",\n  \"already-exists\":\n    \"Refusing to create over something that already exists — a feature directory, a workspace file, a name already claimed in the subsystem namespace — because overwriting would destroy work nobody asked to lose.\",\n  \"sources-absent\":\n    \"`loam vouch` refuses to stamp a document that names no `sources` — with nothing tying the document to code, the staleness signal a vouch exists to power could never fire.\",\n  \"sources-path-missing\":\n    \"`loam vouch` refuses to stamp: a listed source does not exist in the service repo, or is a glob pattern (not supported) — the digest would cover a different file set than the author meant.\",\n  \"not-coherent\":\n    \"`loam archive` refuses: the feature has coherence issues, carried in `issues[]` with a per-issue `overridable` — fix the gating ones, or `--approve` the judgment calls; a refusal `--approve` cannot move says so in the message.\",\n  \"living-outside-requirements\":\n    \"`loam archive` refuses: the LIVING spec holds a requirement outside its `## Requirements` section, and the merge rewrites only that section, so the requirement would land in the file twice — the fix is in the living document, and `--approve` does not override it.\",\n  \"archive-exists\":\n    \"`loam archive` refuses: `features/archive/` already holds a directory for this feature — a destination collision, not a merge problem; move the old archive entry aside first.\",\n  \"merge-failed\":\n    \"The merge — or a journaled writer's one-file commit — could not be computed or was rolled back; the living docs are unchanged, and re-running can work.\",\n  \"rollback-incomplete\":\n    \"A failed write could not be fully undone: some files were not put back, and the message lists them — the one refusal that needs a human before anything else runs against the repo.\",\n  \"feature-active\":\n    \"`loam unarchive` refuses: a `features/` directory for this feature already exists outside the archive, so restoring would write over work in flight — remove or rename it, then re-run.\",\n  \"snapshot-missing\":\n    \"`loam unarchive` refuses: the archive carries no snapshot of what it overwrote (it predates snapshots, or was written by a different loam) — restore the living docs from version control instead.\",\n  \"snapshot-stale\":\n    \"`loam unarchive` refuses: a file the archive wrote changed after it — a living document, another feature's document whose links into this one it rewrote, or one of the feature's own documents it relinked under `features/archive/` — so restoring is no longer an undo; re-run with `--force` to restore anyway, deliberately discarding those later changes.\",\n  \"snapshot-corrupt\":\n    \"`loam unarchive` refuses: a snapshot pre-image no longer matches the digest the archive recorded for it, so restoring would write text nobody wrote — `--force` does not override this one; restore from version control.\",\n  \"commit-interrupted\":\n    \"A journaled writer (archive, unarchive, rebase, vouch, new, gherkin, a recording verify) was killed mid-commit and this run cannot repair the leftovers on its own — the docs may be half-written; run the command the message names, or `loam doctor` for the file-by-file account.\",\n  \"restore-failed\":\n    \"`loam unarchive` failed and everything was rolled back — nothing was restored, the living docs are unchanged, and re-running can work.\",\n  \"answers-unreadable\":\n    \"A recording `loam verify` could not read a user-named file — the answers JSON, or a cucumber/contract report — as what it claims to be; fail-closed: nothing was recorded, so fix the file and re-run.\",\n  \"answers-mismatch\":\n    \"The answer set does not answer the current checklist — an id not on it, a claim with no answer, or an entry for a claim a passed report already owns; re-derive the checklist and answer exactly what it asks.\",\n  \"answers-unevidenced\":\n    \"A `confirmed` answer carries no evidence — evidence is `file:line`, and a claim you cannot show is `unconfirmed` with a note saying why, which is a successful record, not a failure.\",\n  \"service-mismatch\":\n    \"A command that must run inside one service's own repository was told `--service` for a service this repository's loam.json does not declare: a recording `loam verify`, whose attestation must be bound to the code it is about; `loam gherkin`, whose .feature files land in that service's checkout; or `loam vouch`, whose `sources` resolve there. Run it from that service's own repo.\",\n  \"unknown-service\":\n    \"Federated verify recording: the selected service is not one this feature's checklist (or the docs repo) knows, so there is nothing its attestation could bind to — fix the id.\",\n  \"repository-unavailable\":\n    \"The repository this operation must be bound to (or read from) cannot be answered for — most commonly a writing `loam verify`, a `loam gherkin` or a `loam vouch` run where loam.json declares no `service` at all (the docs repo, usually), or a docs repo that cannot be enumerated — so the command refuses rather than guessing which service it is about.\",\n  \"record-federated\":\n    \"`loam verify --record` without `--service` over a federated (schema 2) record — per-service files under `verification/`, or a one-file record carrying attestations — the all-at-once form would put one unattested answer set over other repositories' attestations, so it is refused naming the attestors; record per service instead.\",\n  \"record-unreadable\":\n    \"A file of the verification record (`verification.yaml`, or one service's `verification/<svc>.yaml`) exists but cannot be read — broken YAML, git conflict markers, a summary contradicting its claims, or a per-service file holding anything but its own service's attestation. It is never overwritten and never reported as absent. The message names the file and the safe repair: a service's own file holds only that service's word, so it may be repaired, or deleted and recorded again from that service's repo; the one-file `verification.yaml` may hold other services' attestations, so it is repaired or restored from version control (after a merge, the copy on the branch you merged into), never deleted.\",\n  \"record-raced\":\n    \"`loam verify --record` found the record changed between its locked read and the swap — an editor or a lock-ignoring writer landed first; nothing was written, and re-running merges over the record as it now stands.\",\n  \"gherkin-conflict\":\n    \"`loam gherkin <FEAT>` would overwrite a `.feature` file owned by another feature still in flight — the whole emission refuses and names the owner; archive or coordinate with that feature first.\",\n  \"vouch-raced\":\n    \"`loam vouch` found the spec changed between reading and stamping — another vouch or an edit landed first; nothing was written, so re-read and re-run.\",\n  \"vouch-unattended\":\n    \"`loam vouch` with nobody on the other end of stdin and no `--yes` — the stamp is a person's claim to have read the document, and nobody was asked.\",\n  \"vouch-unattributable\":\n    \"`loam vouch` could not learn who is vouching — git names no `user.email` here — and a stamp with nobody behind it records only that the word was written; set your git identity and re-run.\",\n  \"vouch-declined\":\n    \"`loam vouch` asked and the person said no — nothing was stamped; a successful refusal, not a failure.\",\n  \"docs-missing\":\n    \"`docsDir` in loam.json points at nothing — the docs repo was never cloned, or the path is wrong; a read command refuses rather than reporting an empty fleet, and `loam doctor` names the wiring to fix.\",\n  \"services-missing\":\n    \"`docsDir` is a directory but holds no `services/` — it is some other directory, most often the service repo itself after a typo; fix the pointer rather than scaffolding a second source of truth beside the real one.\",\n  \"docs-busy\":\n    \"Another loam writer holds the docs repo's advisory lock — nothing was read or written, and re-running once it finishes works; a lock nothing will ever release shows up in `loam doctor` as a blocker.\",\n  \"subsystem-not-empty\":\n    \"`loam subsystem` rm refuses a subsystem that still holds members — services or child subsystems, named in the message — because a destructive command never picks targets the caller did not name; move them out first, then re-run.\",\n  \"move-uncommitted\":\n    \"A subsystem move/rename refuses because git reports uncommitted or untracked paths under a directory being moved, or in a document outside it whose links the move would rewrite — the move would sweep them into a change nobody reviewed; commit, `git stash -u`, or remove them, then re-run.\",\n  \"move-failed\":\n    \"A subsystem move/rename failed and was rolled back cleanly — every rename undone, the generated views file restored, the docs unchanged; re-running can work.\",\n  \"no-members\":\n    \"`loam open` found no service checkout bound to this docs repo under any scanned root — the workspace would hold only the docs repo; clone a bound checkout beside it, or point `--root` at where the checkouts live.\",\n  \"binding-duplicate\":\n    \"Two discovered repositories' committed loam.json files declare the same `service` for this docs repo — loam will not guess which checkout speaks for the service; narrow the scan with `--root`, or fix the stray binding.\",\n  \"owners-unreadable\":\n    \"`loam list --owners` could not use the named CODEOWNERS file — the path cannot be read, or a line does not parse as `pattern owner…` (the message names the line); fail-closed, because a half-read ownership file must never file a service under the wrong team.\",\n  \"seed-file-invalid\":\n    \"`loam seed`'s fleet file is missing, unreadable, not YAML, the wrong shape, carries an illegal id — or no longer names every existing `services/<id>/` (that refusal lists the exact ids as `missingServices`); the message names the file and line, and editing the file and re-running succeeds.\",\n  \"seed-duplicate-service\":\n    \"fleet.yaml declares one name twice — as two services, or as both a service and an external/subsystem; service ids, subsystem names and externals share one flat namespace, both declaration lines are named, and renaming one fixes it.\",\n  \"seed-unknown-subsystem\":\n    \"A service's `subsystem:` in fleet.yaml names nothing `subsystems:` declares — the message carries a did-you-mean over the names the file really declares; add the subsystem or fix the spelling, then re-run.\",\n  \"seed-landscape-edited\":\n    \"architecture/landscape.likec4 carries hand edits (the line-1 stamp's digest no longer matches) or was authored some other way, which includes anything written ABOVE the scaffold's stub — `loam seed` never overwrites human work and wrote nothing. Seed runs once, before any operation is drawn: fleet.yaml cannot carry `metadata { op }`, publishes or consumes, so once the map holds them it grows without seed — `loam adopt --service <id>` for a new service, a feature's C4 delta for everything else. Folding the edits into fleet.yaml and deleting the file works only when every edit is a service, subsystem or plain call fleet.yaml can say.\",\n  internal:\n    \"An unexpected throw — the one refusal with no stable meaning; it exists so a `--json` consumer still receives an envelope instead of a stack trace, and a repeatable `internal` is a loam defect worth reporting.\",\n} as const satisfies Record<ErrorCode, string>;\n"]}

package/dist/core/explain/terms/documents.js

@@ -0,0 +1,227 @@
+export const DOCUMENT_TERMS = {
+    heading: "the documents — what loam reads and grades",
+    terms: [
+        {
+            term: "delta",
+            aliases: ["deltas"],
+            paragraph: "A delta is a feature's change, stated against the living docs rather than in them. " +
+                "The living spec.md is the complete current state; a feature's copy is a diff against it, reviewed as a diff, with " +
+                "requirements grouped under `## ADDED`, `## MODIFIED` or `## REMOVED Requirements`; delta.likec4 carries the " +
+                "architecture change with every changed element tagged `#<FEAT>` (untagged elements are context, not changes); " +
+                "and the contract deltas are complete documents whose baseline pins mark what is merely quoted. " +
+                "`loam archive` folds the delta into the living state. The `delta.*` findings grade that algebra — whether the " +
+                "diff still applies to the living document it claims to change.",
+            pins: [
+                // Both used to pin the long layout opening, which stopped shipping when
+                // AGENTS.md was condensed; ORIENTATION's "What is where" teaches the same
+                // two facts in its own words. Re-paired on the clauses the two texts
+                // already share rather than by rewording either side, so `loam explain
+                // delta` prints exactly what it printed before.
+                { source: "AGENTS_MD", phrase: "the complete current state" },
+                { source: "AGENTS_MD", phrase: "reviewed as a diff" },
+            ],
+        },
+        {
+            term: "baseline",
+            aliases: ["based-on", "baselines"],
+            paragraph: "A baseline is the pin tying a delta to the living version it was written against. It rides as `Based-On:` under a " +
+                "MODIFIED/REMOVED requirement and `x-loam-based-on` on a contract surface — written by `loam rebase <FEAT>`, never by " +
+                "hand. It exists because a MODIFIED requirement carries its FULL new text, not a diff, so the merge REPLACES the " +
+                "living text wholesale; the pin is what lets archive tell an edit from a quote and refuse a stale one " +
+                "(`delta.baseline-stale`, `openapi.baseline-stale`) instead of silently reverting work that landed in between. " +
+                `**Restamping is not resolving.** A pin claims "I read this version". ` +
+                "Re-read the living text and fold in what you still mean before you re-pin.",
+            pins: [
+                // Without the sentence-initial "A": the paragraph embeds the clause
+                // mid-sentence, and a pin is a verbatim substring of BOTH sides.
+                { source: "SPINE_PAGE", phrase: "MODIFIED requirement carries its FULL new text, not a diff" },
+                { source: "SPINE_PAGE", phrase: `**Restamping is not resolving.** A pin claims "I read this version".` },
+            ],
+        },
+        {
+            term: "spine",
+            aliases: [],
+            paragraph: "The spine is a family of exact joins, not one magic id. Its ids are the feature tag (`#FEAT-101`), the service " +
+                "binding (`metadata { service }`), the synchronous operationId, the asynchronous message name, `Covers:` " +
+                "architecture coverage, `Requires:` permissions and `Capability:` realization. Three artifacts describe one synchronous call — " +
+                "a C4 edge, a requirement's `Operations:` line, the provider's openapi.yaml — joined by the operationId, and that " +
+                "join is what `loam validate` checks. Spell it identically in all three places. The `spine.*` findings are exactly " +
+                "these joins failing to resolve, and a mismatch is a broken contract between services, not a style problem.",
+            pins: [
+                { source: "SPINE_PAGE", phrase: "The spine is a family of exact joins, not one magic id" },
+                { source: "SPINE_PAGE", phrase: "Spell it identically in all three places." },
+            ],
+        },
+        {
+            term: "axis",
+            aliases: ["axes"],
+            paragraph: "An axis is one language a service is described in, and loam's checks are joins BETWEEN axes rather than opinions within one. " +
+                "The three: architecture — a C4 edge names the operation it calls; behaviour — a requirement declares the " +
+                "operations it governs; contract — the provider's `openapi.yaml` defines it (asyncapi.yaml is the same axis for " +
+                "events, and arch.spec.md is the behaviour axis for architectural obligations). A finding code's prefix names the " +
+                "axes that disagree — `spec-api.op-undefined` is the behaviour axis joined against the contract axis — and the fix " +
+                "is whichever side is wrong about the world.",
+            pins: [
+                { source: "SPINE_PAGE", phrase: "architecture — a C4 edge names the operation it calls" },
+                { source: "SPINE_PAGE", phrase: "behaviour — a requirement declares the operations it governs" },
+                { source: "SPINE_PAGE", phrase: "contract — the provider's `openapi.yaml` defines it" },
+            ],
+        },
+        {
+            // The `coherence` row of `loam status <FEAT>` and the `coherence:` line of
+            // `loam validate --feature` both print the word bare, and the row's last
+            // count — "N stop it" — is the one a newcomer reads as a severity.
+            // Gating and severity are two questions; this entry exists to say so in
+            // the place the row sends a reader.
+            term: "coherence",
+            aliases: ["coherent", "gates", "gating"],
+            paragraph: "Coherence is whether a feature's documents agree with each other and with the fleet in flight. " +
+                "The C4 delta, the requirement deltas and the contracts are joined exactly, as the spine spells them. " +
+                "`loam validate --feature <FEAT>` grades it — a change's three axes against each other — and prints " +
+                "`coherence: ✓ C4 · requirements · OpenAPI agree` when every join holds. " +
+                "`loam status <FEAT>` prints a `coherence` row counting what it graded on the feature — the union of what " +
+                "`loam validate --feature` and `loam archive` refuse — as errors, warnings, and how many stop it: the " +
+                "findings `loam validate --feature` or `loam archive` refuses on right now. " +
+                "Gating is not severity: archive is gated on coherence, so a finding carrying `gates: true` " +
+                "will stop `loam archive` even when it is a warning (`delta.requirement-not-merged` warns but gates). " +
+                "`--approve` overrides only the gating findings that are judgement calls, never a mechanical loss. " +
+                "Note what it does not read: coherence is something loam computed from the documents, and whether the code " +
+                "exists is the done-check's question (`loam explain claim`).",
+            pins: [
+                { source: "CHECK", phrase: "a change's three axes against each other" },
+                { source: "CHECK", phrase: "will stop `loam archive` even when it is a warning" },
+                { source: "AGENTS_MD", phrase: "archive is gated on coherence" },
+                { source: "DONE_CHECK", phrase: "coherence is something loam computed from the documents" },
+            ],
+        },
+        {
+            term: "vouch",
+            aliases: ["vouched", "vouching"],
+            paragraph: "A vouch is the human promotion of a living document from draft to verified. " +
+                "Promoting draft to verified is their call, not yours: a person runs `loam vouch --service <id>` in the service's own repo, " +
+                "and the stamp records the date, who vouched (from git), and digests of both the source files and the document body — " +
+                "which is what lets a later `loam validate` report `sources.stale` and `content.stale` when the code or the words move. " +
+                "**`loam vouch` is not yours to run**, and it is built so that it cannot be. It refuses unattended runs (`vouch-unattended`), " +
+                "records a no as `vouch-declined`, and refuses to stamp when git can name nobody (`vouch-unattributable`); " +
+                "when your work leaves a document ready, hand back and say a vouch is owed.",
+            pins: [
+                // Both phrases left AGENTS.md with the frontmatter teaching and are now
+                // in `loam instructions loam-authoring`. Repaired by following the text,
+                // not by rewording the paragraph to something still in the file: the
+                // pairing exists so this paragraph and the teaching cannot drift, and
+                // re-pinning to a different sentence would have quietly ended it.
+                { source: "AUTHORING", phrase: "Promoting draft to verified is their call, not yours" },
+                { source: "AUTHORING", phrase: "**`loam vouch` is not yours to run**, and it is built so that it cannot be." },
+            ],
+        },
+        {
+            // The ladder is defined in core/vocabulary/maturity.ts, a doc comment no
+            // reader of the binary sees, and `loam list` and the `--all` scorecard
+            // print its five words as bare counts ("0 empty · 0 partial · …"). The
+            // pins are the two places a shipped page USES a rung, which is as close
+            // as the shipped text comes to defining one — the definitions below are
+            // that module's, restated.
+            term: "maturity",
+            aliases: ["rung", "rungs", "empty", "partial", "documented", "sourced"],
+            paragraph: "Maturity is how far a service's documentation has got: empty, partial, documented, sourced or vouched. " +
+                "Those are the five rungs of one ladder, in order. " +
+                "`loam list` prints each service's rung and a `maturity:` rollup, and `loam validate --all` prints the same five " +
+                "counts on its fleet scorecard's `services` line. " +
+                "`empty`: `services/<id>/` exists and nothing is in it. `partial`: some documents, but not the required set — " +
+                "model.likec4 and spec.md, plus openapi.yaml unless the fleet map proves nothing calls the service. " +
+                "`documented`: the required set is present. `sourced`: the living spec declares `sources`, so something ties it to code. " +
+                "`vouched`: a person stamped it with `loam vouch` — `status: verified` with a sources digest behind it — and " +
+                "the maturity rung stays `vouched` when the person read only a sample, which the text views mark `vouched (sampled)`. " +
+                "Each rung stands on every rung below it, and the ladder reads presence and provenance only, never completeness: " +
+                "a service with one endpoint documented out of thirty climbs it as fast as a thorough one. It matters before a " +
+                "feature: a service at `empty` or `partial` has no baseline to write a delta against, so the work starts with " +
+                "`loam adopt --service <id>`.",
+            pins: [
+                { source: "FEATURE", phrase: "a service at `empty` or `partial` has no baseline to" },
+                { source: "AUTHORING", phrase: "the maturity rung stays `vouched`" },
+            ],
+        },
+    ],
+};
+export const DRAWING_TERMS = {
+    heading: "the picture — drawing the map and writing for a person",
+    terms: [
+        {
+            // The kind names are aliases because they are what an agent meets on an
+            // edge (`-[delivers]->`) and asks about; `readsWrites` is lowercased, as
+            // every alias is, because the lookup lowercases the subject first.
+            term: "kind",
+            aliases: [
+                "kinds",
+                "relationship-kind",
+                "arrow",
+                "direction",
+                "publishes",
+                "delivers",
+                "reads",
+                "writes",
+                "readswrites",
+                "calls",
+                "connects",
+            ],
+            paragraph: "A relationship kind says what an edge carries, and so which way its arrow points. " +
+                "`publishes` runs from a producer to a topic and `delivers` from the topic to a consumer, beside the " +
+                "`metadata { publishes }` and `metadata { consumes }` the event spine joins on; `calls` is a synchronous request, " +
+                "beside `metadata { op }`; `reads`, `writes` and `readsWrites` are a service's use of a store, and a store edge is ALWAYS written " +
+                "service `->` store, with the arrowhead put where the data lands by the kind's style; `connects` is a " +
+                "connection whose direction nobody has established, drawn gray and dashed with no arrowhead. " +
+                "**Never guess a direction.** Give an edge a direction only from evidence: the code, a configuration name " +
+                "that says which side a service is on, or its own asyncapi.yaml. Configuration that only lists an address is " +
+                "`connects`, and adopting the service from its code resolves it. The kinds are declared once in " +
+                "architecture/landscape.likec4's `specification` block, and again in a feature delta that draws one, and the " +
+                "living map must declare a kind before a feature using it archives. No check reads a kind: it is the picture, and " +
+                "the metadata is the join. `loam instructions loam-drawing` has the styles.",
+            pins: [
+                { source: "DRAWING", phrase: "**Never guess a direction.** Give an edge a direction only from evidence:" },
+                { source: "DRAWING", phrase: "a store edge is ALWAYS written" },
+            ],
+        },
+        {
+            term: "legend",
+            aliases: ["legend-view"],
+            paragraph: "A legend is a view in architecture/landscape.likec4 that draws ONE real " +
+                "edge of each kind the map uses, so a reader learns the colours from the fleet itself. It names real services, " +
+                "a real topic and a real store, each edge by both of its endpoints, and it gains a line when the map gains a " +
+                "kind. A view can name only elements the model declares, so `loam init` cannot scaffold one: the legend is " +
+                "written once the map has real edges of each kind.",
+            pins: [{ source: "DRAWING", phrase: "edge of each kind the map uses" }],
+        },
+        {
+            term: "overview",
+            aliases: ["overviews", "overview-view", "altitude"],
+            paragraph: "An overview is a view a person reads to answer one question about the fleet. " +
+                "**One question per view, at one altitude.** A fleet overview draws subsystem boxes, not services, at most " +
+                "about 20 nodes and 25 drawn lines, and the generated subsystem and service views are its drill-down. Above " +
+                "service altitude LikeC4 merges every relationship between two boxes into one line, and a line merged from " +
+                "different kinds is drawn in the default gray, so filter by one kind: " +
+                "`where kind is publishes` keeps the line amber, while a `kind is not` or an `or` filter still merges. " +
+                "Never author a `view … of` a subsystem or service element, which would take the drill-down from loam's " +
+                "generated views. `loam instructions loam-drawing` lists the spellings that render nothing.",
+            pins: [
+                { source: "DRAWING", phrase: "**One question per view, at one altitude.**" },
+                { source: "DRAWING", phrase: "`where kind is publishes` keeps the line amber" },
+            ],
+        },
+        {
+            term: "purpose",
+            aliases: ["narrative"],
+            paragraph: "A `## Purpose` section is the plain-language narrative of a spec delta: what the service does in the change, " +
+                "for someone who has never opened its code. " +
+                "Each spec delta opens with a plain-language `## Purpose`. Where the delta creates the living document — a " +
+                "new service's spec.md, a first arch.spec.md, a new capability — `loam archive` copies the section in as that " +
+                "document's narrative, beside the delta's title and frontmatter owner. Where the living document already exists, the " +
+                "section stays with the archived delta, and the archive plan says so; edit the living narrative directly when " +
+                "it should change. Nothing grades a purpose; `loam instructions loam-authoring`, \"Writing for a person\", has the shape.",
+            pins: [
+                { source: "AUTHORING", phrase: "Each spec delta opens with a plain-language `## Purpose`" },
+                { source: "AUTHORING", phrase: "section stays with the archived delta" },
+            ],
+        },
+    ],
+};
+//# sourceMappingURL=documents.js.map

package/dist/core/explain/terms/documents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"documents.js","sourceRoot":"","sources":["../../../../src/core/explain/terms/documents.ts"],"names":[],"mappings":"AAmBA,MAAM,CAAC,MAAM,cAAc,GAAc;IACvC,OAAO,EAAE,4CAA4C;IACrD,KAAK,EAAE;QACL;YACE,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,CAAC,QAAQ,CAAC;YACnB,SAAS,EACP,qFAAqF;gBACrF,oHAAoH;gBACpH,8GAA8G;gBAC9G,gHAAgH;gBAChH,iGAAiG;gBACjG,gHAAgH;gBAChH,gEAAgE;YAClE,IAAI,EAAE;gBACJ,wEAAwE;gBACxE,0EAA0E;gBAC1E,qEAAqE;gBACrE,uEAAuE;gBACvE,gDAAgD;gBAChD,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,4BAA4B,EAAE;gBAC7D,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,oBAAoB,EAAE;aACtD;SACF;QACD;YACE,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,CAAC,UAAU,EAAE,WAAW,CAAC;YAClC,SAAS,EACP,oHAAoH;gBACpH,uHAAuH;gBACvH,kHAAkH;gBAClH,uGAAuG;gBACvG,gHAAgH;gBAChH,uEAAuE;gBACvE,4EAA4E;YAC9E,IAAI,EAAE;gBACJ,oEAAoE;gBACpE,iEAAiE;gBACjE,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,4DAA4D,EAAE;gBAC9F,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,sEAAsE,EAAE;aACzG;SACF;QACD;YACE,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,EAAE;YACX,SAAS,EACP,iHAAiH;gBACjH,0GAA0G;gBAC1G,gIAAgI;gBAChI,mHAAmH;gBACnH,oHAAoH;gBACpH,4GAA4G;YAC9G,IAAI,EAAE;gBACJ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,wDAAwD,EAAE;gBAC1F,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,2CAA2C,EAAE;aAC9E;SACF;QACD;YACE,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE,CAAC,MAAM,CAAC;YACjB,SAAS,EACP,+HAA+H;gBAC/H,2GAA2G;gBAC3G,iHAAiH;gBACjH,mHAAmH;gBACnH,oHAAoH;gBACpH,6CAA6C;YAC/C,IAAI,EAAE;gBACJ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,uDAAuD,EAAE;gBACzF,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,8DAA8D,EAAE;gBAChG,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,qDAAqD,EAAE;aACxF;SACF;QACD;YACE,2EAA2E;YAC3E,yEAAyE;YACzE,mEAAmE;YACnE,wEAAwE;YACxE,oCAAoC;YACpC,IAAI,EAAE,WAAW;YACjB,OAAO,EAAE,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAC;YACxC,SAAS,EACP,iGAAiG;gBACjG,uGAAuG;gBACvG,qGAAqG;gBACrG,0EAA0E;gBAC1E,2GAA2G;gBAC3G,uGAAuG;gBACvG,6EAA6E;gBAC7E,6FAA6F;gBAC7F,uGAAuG;gBACvG,oGAAoG;gBACpG,4GAA4G;gBAC5G,6DAA6D;YAC/D,IAAI,EAAE;gBACJ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,0CAA0C,EAAE;gBACvE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,oDAAoD,EAAE;gBACjF,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,+BAA+B,EAAE;gBAChE,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,yDAAyD,EAAE;aAC5F;SACF;QACD;YACE,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,CAAC,SAAS,EAAE,UAAU,CAAC;YAChC,SAAS,EACP,8EAA8E;gBAC9E,6HAA6H;gBAC7H,uHAAuH;gBACvH,yHAAyH;gBACzH,+HAA+H;gBAC/H,4GAA4G;gBAC5G,4EAA4E;YAC9E,IAAI,EAAE;gBACJ,wEAAwE;gBACxE,yEAAyE;gBACzE,qEAAqE;gBACrE,sEAAsE;gBACtE,kEAAkE;gBAClE,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,sDAAsD,EAAE;gBACvF,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,6EAA6E,EAAE;aAC/G;SACF;QACD;YACE,yEAAyE;YACzE,uEAAuE;YACvE,uEAAuE;YACvE,wEAAwE;YACxE,wEAAwE;YACxE,2BAA2B;YAC3B,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,CAAC;YACvE,SAAS,EACP,yGAAyG;gBACzG,oDAAoD;gBACpD,kHAAkH;gBAClH,mDAAmD;gBACnD,+GAA+G;gBAC/G,qGAAqG;gBACrG,0HAA0H;gBAC1H,8GAA8G;gBAC9G,uHAAuH;gBACvH,kHAAkH;gBAClH,gHAAgH;gBAChH,+GAA+G;gBAC/G,8BAA8B;YAChC,IAAI,EAAE;gBACJ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,sDAAsD,EAAE;gBACrF,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,mCAAmC,EAAE;aACrE;SACF;KACF;CACF,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAc;IACtC,OAAO,EAAE,wDAAwD;IACjE,KAAK,EAAE;QACL;YACE,wEAAwE;YACxE,yEAAyE;YACzE,mEAAmE;YACnE,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE;gBACP,OAAO;gBACP,mBAAmB;gBACnB,OAAO;gBACP,WAAW;gBACX,WAAW;gBACX,UAAU;gBACV,OAAO;gBACP,QAAQ;gBACR,aAAa;gBACb,OAAO;gBACP,UAAU;aACX;YACD,SAAS,EACP,oFAAoF;gBACpF,sGAAsG;gBACtG,mHAAmH;gBACnH,mIAAmI;gBACnI,uGAAuG;gBACvG,8FAA8F;gBAC9F,2GAA2G;gBAC3G,8GAA8G;gBAC9G,iGAAiG;gBACjG,8GAA8G;gBAC9G,mHAAmH;gBACnH,4EAA4E;YAC9E,IAAI,EAAE;gBACJ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,2EAA2E,EAAE;gBAC1G,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,gCAAgC,EAAE;aAChE;SACF;QACD;YACE,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,CAAC,aAAa,CAAC;YACxB,SAAS,EACP,0EAA0E;gBAC1E,gHAAgH;gBAChH,8GAA8G;gBAC9G,4GAA4G;gBAC5G,mDAAmD;YACrD,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,gCAAgC,EAAE,CAAC;SACxE;QACD;YACE,IAAI,EAAE,UAAU;YAChB,OAAO,EAAE,CAAC,WAAW,EAAE,eAAe,EAAE,UAAU,CAAC;YACnD,SAAS,EACP,+EAA+E;gBAC/E,4GAA4G;gBAC5G,6GAA6G;gBAC7G,4GAA4G;gBAC5G,uEAAuE;gBACvE,wGAAwG;gBACxG,yGAAyG;gBACzG,4FAA4F;YAC9F,IAAI,EAAE;gBACJ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,6CAA6C,EAAE;gBAC5E,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,gDAAgD,EAAE;aAChF;SACF;QACD;YACE,IAAI,EAAE,SAAS;YACf,OAAO,EAAE,CAAC,WAAW,CAAC;YACtB,SAAS,EACP,+GAA+G;gBAC/G,6CAA6C;gBAC7C,4GAA4G;gBAC5G,+GAA+G;gBAC/G,sHAAsH;gBACtH,+GAA+G;gBAC/G,0HAA0H;YAC5H,IAAI,EAAE;gBACJ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,0DAA0D,EAAE;gBAC3F,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,uCAAuC,EAAE;aACzE;SACF;KACF;CACF,CAAC","sourcesContent":["/**\n * The document terms: the words for how loam reads a docs repo at rest — a\n * feature's change and the pin tying it to what it changes, the joins between\n * the three languages a service is described in, the agreement `loam archive`\n * is gated on, and the two dials of how far a service's documentation has got\n * (`loam vouch`, and the maturity ladder `loam list` and the fleet scorecard\n * print). The first five are the oldest entries in the registry and carry\n * their re-pairing history in the comments beside their pins.\n *\n * The second group below, `DRAWING_TERMS`, is the words for drawing the map\n * and writing a feature a person can follow. It is the vocabulary of the\n * `loam-drawing` page and of `loam-authoring`'s \"Writing for a person\". It\n * lives in this module rather than one of its own because ./ is at the\n * five-file cap, and because those words are about the same documents: a\n * relationship kind is part of landscape.likec4, and a `## Purpose` is part of\n * a spec delta.\n */\nimport type { TermGroup } from \"./entry.js\";\n\nexport const DOCUMENT_TERMS: TermGroup = {\n  heading: \"the documents — what loam reads and grades\",\n  terms: [\n    {\n      term: \"delta\",\n      aliases: [\"deltas\"],\n      paragraph:\n        \"A delta is a feature's change, stated against the living docs rather than in them. \" +\n        \"The living spec.md is the complete current state; a feature's copy is a diff against it, reviewed as a diff, with \" +\n        \"requirements grouped under `## ADDED`, `## MODIFIED` or `## REMOVED Requirements`; delta.likec4 carries the \" +\n        \"architecture change with every changed element tagged `#<FEAT>` (untagged elements are context, not changes); \" +\n        \"and the contract deltas are complete documents whose baseline pins mark what is merely quoted. \" +\n        \"`loam archive` folds the delta into the living state. The `delta.*` findings grade that algebra — whether the \" +\n        \"diff still applies to the living document it claims to change.\",\n      pins: [\n        // Both used to pin the long layout opening, which stopped shipping when\n        // AGENTS.md was condensed; ORIENTATION's \"What is where\" teaches the same\n        // two facts in its own words. Re-paired on the clauses the two texts\n        // already share rather than by rewording either side, so `loam explain\n        // delta` prints exactly what it printed before.\n        { source: \"AGENTS_MD\", phrase: \"the complete current state\" },\n        { source: \"AGENTS_MD\", phrase: \"reviewed as a diff\" },\n      ],\n    },\n    {\n      term: \"baseline\",\n      aliases: [\"based-on\", \"baselines\"],\n      paragraph:\n        \"A baseline is the pin tying a delta to the living version it was written against. It rides as `Based-On:` under a \" +\n        \"MODIFIED/REMOVED requirement and `x-loam-based-on` on a contract surface — written by `loam rebase <FEAT>`, never by \" +\n        \"hand. It exists because a MODIFIED requirement carries its FULL new text, not a diff, so the merge REPLACES the \" +\n        \"living text wholesale; the pin is what lets archive tell an edit from a quote and refuse a stale one \" +\n        \"(`delta.baseline-stale`, `openapi.baseline-stale`) instead of silently reverting work that landed in between. \" +\n        `**Restamping is not resolving.** A pin claims \"I read this version\". ` +\n        \"Re-read the living text and fold in what you still mean before you re-pin.\",\n      pins: [\n        // Without the sentence-initial \"A\": the paragraph embeds the clause\n        // mid-sentence, and a pin is a verbatim substring of BOTH sides.\n        { source: \"SPINE_PAGE\", phrase: \"MODIFIED requirement carries its FULL new text, not a diff\" },\n        { source: \"SPINE_PAGE\", phrase: `**Restamping is not resolving.** A pin claims \"I read this version\".` },\n      ],\n    },\n    {\n      term: \"spine\",\n      aliases: [],\n      paragraph:\n        \"The spine is a family of exact joins, not one magic id. Its ids are the feature tag (`#FEAT-101`), the service \" +\n        \"binding (`metadata { service }`), the synchronous operationId, the asynchronous message name, `Covers:` \" +\n        \"architecture coverage, `Requires:` permissions and `Capability:` realization. Three artifacts describe one synchronous call — \" +\n        \"a C4 edge, a requirement's `Operations:` line, the provider's openapi.yaml — joined by the operationId, and that \" +\n        \"join is what `loam validate` checks. Spell it identically in all three places. The `spine.*` findings are exactly \" +\n        \"these joins failing to resolve, and a mismatch is a broken contract between services, not a style problem.\",\n      pins: [\n        { source: \"SPINE_PAGE\", phrase: \"The spine is a family of exact joins, not one magic id\" },\n        { source: \"SPINE_PAGE\", phrase: \"Spell it identically in all three places.\" },\n      ],\n    },\n    {\n      term: \"axis\",\n      aliases: [\"axes\"],\n      paragraph:\n        \"An axis is one language a service is described in, and loam's checks are joins BETWEEN axes rather than opinions within one. \" +\n        \"The three: architecture — a C4 edge names the operation it calls; behaviour — a requirement declares the \" +\n        \"operations it governs; contract — the provider's `openapi.yaml` defines it (asyncapi.yaml is the same axis for \" +\n        \"events, and arch.spec.md is the behaviour axis for architectural obligations). A finding code's prefix names the \" +\n        \"axes that disagree — `spec-api.op-undefined` is the behaviour axis joined against the contract axis — and the fix \" +\n        \"is whichever side is wrong about the world.\",\n      pins: [\n        { source: \"SPINE_PAGE\", phrase: \"architecture — a C4 edge names the operation it calls\" },\n        { source: \"SPINE_PAGE\", phrase: \"behaviour — a requirement declares the operations it governs\" },\n        { source: \"SPINE_PAGE\", phrase: \"contract — the provider's `openapi.yaml` defines it\" },\n      ],\n    },\n    {\n      // The `coherence` row of `loam status <FEAT>` and the `coherence:` line of\n      // `loam validate --feature` both print the word bare, and the row's last\n      // count — \"N stop it\" — is the one a newcomer reads as a severity.\n      // Gating and severity are two questions; this entry exists to say so in\n      // the place the row sends a reader.\n      term: \"coherence\",\n      aliases: [\"coherent\", \"gates\", \"gating\"],\n      paragraph:\n        \"Coherence is whether a feature's documents agree with each other and with the fleet in flight. \" +\n        \"The C4 delta, the requirement deltas and the contracts are joined exactly, as the spine spells them. \" +\n        \"`loam validate --feature <FEAT>` grades it — a change's three axes against each other — and prints \" +\n        \"`coherence: ✓ C4 · requirements · OpenAPI agree` when every join holds. \" +\n        \"`loam status <FEAT>` prints a `coherence` row counting what it graded on the feature — the union of what \" +\n        \"`loam validate --feature` and `loam archive` refuse — as errors, warnings, and how many stop it: the \" +\n        \"findings `loam validate --feature` or `loam archive` refuses on right now. \" +\n        \"Gating is not severity: archive is gated on coherence, so a finding carrying `gates: true` \" +\n        \"will stop `loam archive` even when it is a warning (`delta.requirement-not-merged` warns but gates). \" +\n        \"`--approve` overrides only the gating findings that are judgement calls, never a mechanical loss. \" +\n        \"Note what it does not read: coherence is something loam computed from the documents, and whether the code \" +\n        \"exists is the done-check's question (`loam explain claim`).\",\n      pins: [\n        { source: \"CHECK\", phrase: \"a change's three axes against each other\" },\n        { source: \"CHECK\", phrase: \"will stop `loam archive` even when it is a warning\" },\n        { source: \"AGENTS_MD\", phrase: \"archive is gated on coherence\" },\n        { source: \"DONE_CHECK\", phrase: \"coherence is something loam computed from the documents\" },\n      ],\n    },\n    {\n      term: \"vouch\",\n      aliases: [\"vouched\", \"vouching\"],\n      paragraph:\n        \"A vouch is the human promotion of a living document from draft to verified. \" +\n        \"Promoting draft to verified is their call, not yours: a person runs `loam vouch --service <id>` in the service's own repo, \" +\n        \"and the stamp records the date, who vouched (from git), and digests of both the source files and the document body — \" +\n        \"which is what lets a later `loam validate` report `sources.stale` and `content.stale` when the code or the words move. \" +\n        \"**`loam vouch` is not yours to run**, and it is built so that it cannot be. It refuses unattended runs (`vouch-unattended`), \" +\n        \"records a no as `vouch-declined`, and refuses to stamp when git can name nobody (`vouch-unattributable`); \" +\n        \"when your work leaves a document ready, hand back and say a vouch is owed.\",\n      pins: [\n        // Both phrases left AGENTS.md with the frontmatter teaching and are now\n        // in `loam instructions loam-authoring`. Repaired by following the text,\n        // not by rewording the paragraph to something still in the file: the\n        // pairing exists so this paragraph and the teaching cannot drift, and\n        // re-pinning to a different sentence would have quietly ended it.\n        { source: \"AUTHORING\", phrase: \"Promoting draft to verified is their call, not yours\" },\n        { source: \"AUTHORING\", phrase: \"**`loam vouch` is not yours to run**, and it is built so that it cannot be.\" },\n      ],\n    },\n    {\n      // The ladder is defined in core/vocabulary/maturity.ts, a doc comment no\n      // reader of the binary sees, and `loam list` and the `--all` scorecard\n      // print its five words as bare counts (\"0 empty · 0 partial · …\"). The\n      // pins are the two places a shipped page USES a rung, which is as close\n      // as the shipped text comes to defining one — the definitions below are\n      // that module's, restated.\n      term: \"maturity\",\n      aliases: [\"rung\", \"rungs\", \"empty\", \"partial\", \"documented\", \"sourced\"],\n      paragraph:\n        \"Maturity is how far a service's documentation has got: empty, partial, documented, sourced or vouched. \" +\n        \"Those are the five rungs of one ladder, in order. \" +\n        \"`loam list` prints each service's rung and a `maturity:` rollup, and `loam validate --all` prints the same five \" +\n        \"counts on its fleet scorecard's `services` line. \" +\n        \"`empty`: `services/<id>/` exists and nothing is in it. `partial`: some documents, but not the required set — \" +\n        \"model.likec4 and spec.md, plus openapi.yaml unless the fleet map proves nothing calls the service. \" +\n        \"`documented`: the required set is present. `sourced`: the living spec declares `sources`, so something ties it to code. \" +\n        \"`vouched`: a person stamped it with `loam vouch` — `status: verified` with a sources digest behind it — and \" +\n        \"the maturity rung stays `vouched` when the person read only a sample, which the text views mark `vouched (sampled)`. \" +\n        \"Each rung stands on every rung below it, and the ladder reads presence and provenance only, never completeness: \" +\n        \"a service with one endpoint documented out of thirty climbs it as fast as a thorough one. It matters before a \" +\n        \"feature: a service at `empty` or `partial` has no baseline to write a delta against, so the work starts with \" +\n        \"`loam adopt --service <id>`.\",\n      pins: [\n        { source: \"FEATURE\", phrase: \"a service at `empty` or `partial` has no baseline to\" },\n        { source: \"AUTHORING\", phrase: \"the maturity rung stays `vouched`\" },\n      ],\n    },\n  ],\n};\n\nexport const DRAWING_TERMS: TermGroup = {\n  heading: \"the picture — drawing the map and writing for a person\",\n  terms: [\n    {\n      // The kind names are aliases because they are what an agent meets on an\n      // edge (`-[delivers]->`) and asks about; `readsWrites` is lowercased, as\n      // every alias is, because the lookup lowercases the subject first.\n      term: \"kind\",\n      aliases: [\n        \"kinds\",\n        \"relationship-kind\",\n        \"arrow\",\n        \"direction\",\n        \"publishes\",\n        \"delivers\",\n        \"reads\",\n        \"writes\",\n        \"readswrites\",\n        \"calls\",\n        \"connects\",\n      ],\n      paragraph:\n        \"A relationship kind says what an edge carries, and so which way its arrow points. \" +\n        \"`publishes` runs from a producer to a topic and `delivers` from the topic to a consumer, beside the \" +\n        \"`metadata { publishes }` and `metadata { consumes }` the event spine joins on; `calls` is a synchronous request, \" +\n        \"beside `metadata { op }`; `reads`, `writes` and `readsWrites` are a service's use of a store, and a store edge is ALWAYS written \" +\n        \"service `->` store, with the arrowhead put where the data lands by the kind's style; `connects` is a \" +\n        \"connection whose direction nobody has established, drawn gray and dashed with no arrowhead. \" +\n        \"**Never guess a direction.** Give an edge a direction only from evidence: the code, a configuration name \" +\n        \"that says which side a service is on, or its own asyncapi.yaml. Configuration that only lists an address is \" +\n        \"`connects`, and adopting the service from its code resolves it. The kinds are declared once in \" +\n        \"architecture/landscape.likec4's `specification` block, and again in a feature delta that draws one, and the \" +\n        \"living map must declare a kind before a feature using it archives. No check reads a kind: it is the picture, and \" +\n        \"the metadata is the join. `loam instructions loam-drawing` has the styles.\",\n      pins: [\n        { source: \"DRAWING\", phrase: \"**Never guess a direction.** Give an edge a direction only from evidence:\" },\n        { source: \"DRAWING\", phrase: \"a store edge is ALWAYS written\" },\n      ],\n    },\n    {\n      term: \"legend\",\n      aliases: [\"legend-view\"],\n      paragraph:\n        \"A legend is a view in architecture/landscape.likec4 that draws ONE real \" +\n        \"edge of each kind the map uses, so a reader learns the colours from the fleet itself. It names real services, \" +\n        \"a real topic and a real store, each edge by both of its endpoints, and it gains a line when the map gains a \" +\n        \"kind. A view can name only elements the model declares, so `loam init` cannot scaffold one: the legend is \" +\n        \"written once the map has real edges of each kind.\",\n      pins: [{ source: \"DRAWING\", phrase: \"edge of each kind the map uses\" }],\n    },\n    {\n      term: \"overview\",\n      aliases: [\"overviews\", \"overview-view\", \"altitude\"],\n      paragraph:\n        \"An overview is a view a person reads to answer one question about the fleet. \" +\n        \"**One question per view, at one altitude.** A fleet overview draws subsystem boxes, not services, at most \" +\n        \"about 20 nodes and 25 drawn lines, and the generated subsystem and service views are its drill-down. Above \" +\n        \"service altitude LikeC4 merges every relationship between two boxes into one line, and a line merged from \" +\n        \"different kinds is drawn in the default gray, so filter by one kind: \" +\n        \"`where kind is publishes` keeps the line amber, while a `kind is not` or an `or` filter still merges. \" +\n        \"Never author a `view … of` a subsystem or service element, which would take the drill-down from loam's \" +\n        \"generated views. `loam instructions loam-drawing` lists the spellings that render nothing.\",\n      pins: [\n        { source: \"DRAWING\", phrase: \"**One question per view, at one altitude.**\" },\n        { source: \"DRAWING\", phrase: \"`where kind is publishes` keeps the line amber\" },\n      ],\n    },\n    {\n      term: \"purpose\",\n      aliases: [\"narrative\"],\n      paragraph:\n        \"A `## Purpose` section is the plain-language narrative of a spec delta: what the service does in the change, \" +\n        \"for someone who has never opened its code. \" +\n        \"Each spec delta opens with a plain-language `## Purpose`. Where the delta creates the living document — a \" +\n        \"new service's spec.md, a first arch.spec.md, a new capability — `loam archive` copies the section in as that \" +\n        \"document's narrative, beside the delta's title and frontmatter owner. Where the living document already exists, the \" +\n        \"section stays with the archived delta, and the archive plan says so; edit the living narrative directly when \" +\n        \"it should change. Nothing grades a purpose; `loam instructions loam-authoring`, \\\"Writing for a person\\\", has the shape.\",\n      pins: [\n        { source: \"AUTHORING\", phrase: \"Each spec delta opens with a plain-language `## Purpose`\" },\n        { source: \"AUTHORING\", phrase: \"section stays with the archived delta\" },\n      ],\n    },\n  ],\n};\n"]}

package/dist/core/explain/terms/done-check.js

@@ -0,0 +1,144 @@
+export const DONE_CHECK_TERMS = {
+    heading: "the done-check — what `loam verify` asks, and what an answer is worth",
+    terms: [
+        {
+            term: "claim",
+            aliases: ["claims", "checklist", "confirmed", "unconfirmed", "unanswered"],
+            paragraph: "A claim is one question on the done-check's checklist: a promise the feature's documents make about code. " +
+                "loam asks it so that evidence, not prose, can answer it. " +
+                "`loam verify <FEAT>` derives a checklist from the feature's own artifacts: one claim per new service " +
+                "(`service.exists`), per operation the contract delta adds (`api.exposes`), per message the event contract " +
+                "newly declares (`event.declares`), per tagged edge that names an operation (`c4.calls`), and per scenario of " +
+                "every changed requirement (`scenario.tested`) — `loam explain <kind>` says what each one asks and who may answer it. " +
+                "Each claim has a stable id, so two runs are diffable and an answer cannot drift onto a different question; " +
+                "`loam tasks` uses the same id for the unit that closes it. " +
+                "An answer is `confirmed` with `file:line` evidence or `unconfirmed` with a note saying why — a successful " +
+                "record either way — and a claim nobody answered is `unanswered`. Every recorded answer says who gave it " +
+                "(`answered_by: runner | external-runner | agent`), and that is what separates **verified** from **attested**.",
+            pins: [
+                { source: "DONE_CHECK", phrase: "`loam verify <FEAT>` derives a checklist from the feature's own artifacts" },
+                { source: "DONE_CHECK", phrase: "Each claim has a stable id, so" },
+                { source: "DONE_CHECK", phrase: "two runs are diffable and an answer cannot drift onto a different question" },
+                { source: "DONE_CHECK", phrase: "`answered_by: runner | external-runner | agent`" },
+            ],
+        },
+        {
+            term: "service.exists",
+            aliases: [],
+            paragraph: "A `service.exists` claim asks whether a service the feature introduces has actually been built. " +
+                "`loam verify` derives one per new service the feature's delta.likec4 adds to the fleet map. " +
+                "Answer it by finding it in the code, not by reasoning that it must be there. What to open: " +
+                "`service.exists` — the service is deployable: its build, its entry point. " +
+                "The answer is `file:line` evidence, recorded from that service's own repository with " +
+                "`loam verify <FEAT> --service <id> --record answers.json`. No test runner answers this kind, so an agent's " +
+                "word is the expected answer here, and it never makes the verdict **attested** — only scenario claims do.",
+            pins: [{ source: "VERIFY", phrase: "`service.exists` — the service is deployable: its build, its entry point." }],
+        },
+        {
+            term: "api.exposes",
+            aliases: [],
+            paragraph: "An `api.exposes` claim asks whether the service really serves an operation the feature's contract delta adds. " +
+                "`loam verify` derives one per operationId in the feature's openapi.yaml that the living contract does not " +
+                "already define; an operation the delta merely restates is never asked about. " +
+                "What to open: `api.exposes` — the route handler serving that operationId, not the spec that declares it. " +
+                "It also has a mechanical channel: an API contract-test run, passed back in loam's contract-results shape with " +
+                "`loam verify <FEAT> --contract-results contract.json`, answers it as `answered_by: external-runner`. " +
+                "In `loam tasks`, a `c4.calls` unit depends on the `api.exposes` unit that promises the operation it calls.",
+            pins: [
+                { source: "VERIFY", phrase: "`api.exposes` — the route handler serving that operationId, not the spec that" },
+                { source: "DONE_CHECK", phrase: "`loam verify <FEAT> --contract-results contract.json`" },
+            ],
+        },
+        {
+            term: "event.declares",
+            aliases: [],
+            paragraph: "An `event.declares` claim asks whether the service sends or receives a message the feature's event contract " +
+                "newly declares. " +
+                "For a feature, `loam verify` derives one per (direction, message) its asyncapi delta newly declares against the " +
+                "living contract's send/receive sets — quotes and removals are never questions. " +
+                "What to open: `event.declares` — the code that puts the message on the wire (sends) or handles it off the " +
+                "wire (receives), not the contract that names it. " +
+                "It is answered with `file:line` evidence through `loam verify <FEAT> --service <id> --record answers.json`.",
+            pins: [
+                { source: "VERIFY", phrase: "`event.declares` — the code that puts the message on the wire (sends) or" },
+                { source: "VERIFY", phrase: "per (direction, message) its asyncapi delta newly declares against the living" },
+            ],
+        },
+        {
+            term: "c4.calls",
+            aliases: [],
+            paragraph: "A `c4.calls` claim asks whether a call the feature draws on the architecture really exists in the caller's code. " +
+                "`loam verify` derives one per edge in delta.likec4 that is tagged with the feature and names an operation " +
+                "(`metadata { op '<operationId>' }`); an untagged edge is context, and an edge with no operation names nothing " +
+                "specific enough to look for. " +
+                "What to open: `c4.calls` — the call site in the CALLER. " +
+                "Its subject is the calling service, so it is answered from that service's repository, and in `loam tasks` it " +
+                "depends on the `api.exposes` unit for the operation it calls when the same feature adds that operation.",
+            pins: [{ source: "VERIFY", phrase: "`c4.calls` — the call site in the CALLER." }],
+        },
+        {
+            term: "scenario.tested",
+            aliases: [],
+            paragraph: "A `scenario.tested` claim asks whether one scenario of a changed requirement passes in a test run. " +
+                "The run is of the service's generated suite, in that service's own repository. " +
+                "`loam verify` derives one per scenario of every requirement the feature adds or modifies, arch.spec.md deltas " +
+                "included (those want an integration or ops test, not an acceptance test). " +
+                "The `scenario.tested` claims are the runner's to answer, not yours. Run the suite `loam gherkin <FEAT>` " +
+                "generated, with a JSON report, and pass it back with `loam verify <FEAT> --service <id> --results report.json`; " +
+                "the match is the scenario's `@loam-digest-…` tag. The digest is the only identity: a reworded spec scenario " +
+                "matches nothing until the suite is regenerated and re-run. " +
+                "With no runnable suite your word may answer them, and the feature is then **attested**, not verified — these " +
+                "are the only claims that verdict turns on.",
+            pins: [
+                { source: "VERIFY", phrase: "The `scenario.tested` claims are the runner's to answer, not yours." },
+                { source: "DONE_CHECK", phrase: "The digest is the only identity: a reworded spec scenario matches" },
+            ],
+        },
+        {
+            term: "attested",
+            aliases: ["attest", "attestation"],
+            paragraph: "Attested is the verdict one rung below verified on the done-check's ladder. " +
+                "Verified means somebody says the code was built and showed evidence — and for scenario claims that evidence is a " +
+                "test runner's report, answered mechanically. Without a runnable suite your word can still answer them " +
+                "(`loam verify <FEAT> --record` alone), but the record says who answered, and a feature whose " +
+                "scenario claims rest on an agent's word is **attested**, not verified. Nothing gates on the difference; " +
+                "pass `--results <report>` the moment a suite runs and the verdict moves on its own. " +
+                "In `loam tasks` it is also the fourth step a unit can wait at, and the one that is not work to write: " +
+                "the claim was closed on somebody's word rather than on a run, so the unit stays visible at `attested` until a " +
+                "test run re-records it.",
+            pins: [
+                { source: "REFUSALS", phrase: "somebody says the code was built and showed evidence" },
+                // Left the cycle with the done-check teaching; repaired by following the
+                // text, as `vouch`'s two were.
+                { source: "DONE_CHECK", phrase: "scenario claims rest on an agent's word is **attested**, not verified" },
+                { source: "IMPLEMENT", phrase: "the claim was closed on somebody's word rather than on a run" },
+            ],
+        },
+        {
+            // The other half of the most overloaded word in loam's output. The status
+            // row and the scorecard print the verdict (`verified · attested ·
+            // unverified`), while a document's frontmatter prints `status: verified`
+            // for a vouch — and the two have nothing to do with each other. A reader
+            // who looks the word up after either one gets both meanings here.
+            term: "verified",
+            aliases: ["unverified", "verdict", "verdicts"],
+            paragraph: "Verified is the done-check's top verdict: every claim recorded confirmed, the scenario claims by a test run. " +
+                "Every claim on the checklist has an answer with evidence, and no scenario claim rests on somebody's word. " +
+                "A record's `verdict` (`verified` | `attested` | `unverified`) is computed from its claims, never stored: " +
+                "`unverified` means some claim is still unconfirmed or unanswered, or the record answers a checklist the feature " +
+                "no longer asks; **attested** means complete, with a scenario claim resting on an agent's word. " +
+                "Between `verified` and `attested` the verdict turns on the scenario claims alone, so a `verified` record can still rest " +
+                "partly on an agent's word about kinds the verdict does not turn on — `service.exists` or `c4.calls`, which " +
+                "only the code can answer. " +
+                "Only `verified` makes a feature in flight `done`. **Nothing gates on it.** `loam archive` will ship an " +
+                "unverified feature. " +
+                "The same word on a living document means something else: `status: verified` in a spec.md's frontmatter is a " +
+                "person's vouch for the words, not a test result (`loam explain vouch`).",
+            pins: [
+                { source: "CODES_PAGE", phrase: "`verdict` (`verified` | `attested` | `unverified`)" },
+                { source: "CODES_PAGE", phrase: "partly on an agent's word about kinds the verdict does not turn on" },
+            ],
+        },
+    ],
+};
+//# sourceMappingURL=done-check.js.map

package/dist/core/explain/terms/done-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"done-check.js","sourceRoot":"","sources":["../../../../src/core/explain/terms/done-check.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The done-check terms: what `loam verify` asks (a claim, and the five kinds\n * of one), and what the answer is worth (the verdicts).\n *\n * One entry per claim kind rather than one `claim` entry with the kinds as\n * aliases, because the kinds differ in exactly the fact a reader looks one up\n * for: WHO may answer it. A `scenario.tested` claim is a test runner's, an\n * `api.exposes` claim may be a contract suite's, and the other three are\n * answered from the code — a single paragraph listing all five would answer\n * `loam explain c4.calls` with four sentences about something else. Each kind\n * is pinned to its own line of the /loam-verify body, which is where the\n * binary already teaches \"what to open\" one kind at a time.\n *\n * `attested` moved here from the old flat registry with its paragraph and\n * pins intact, and gained a sentence and a pin of its own: `loam tasks` prints\n * the same word as the fourth step a unit waits at, and the two meanings are\n * one fact seen from two commands, so one entry answers both rather than two\n * entries competing for one name.\n */\nimport type { TermGroup } from \"./entry.js\";\n\nexport const DONE_CHECK_TERMS: TermGroup = {\n  heading: \"the done-check — what `loam verify` asks, and what an answer is worth\",\n  terms: [\n    {\n      term: \"claim\",\n      aliases: [\"claims\", \"checklist\", \"confirmed\", \"unconfirmed\", \"unanswered\"],\n      paragraph:\n        \"A claim is one question on the done-check's checklist: a promise the feature's documents make about code. \" +\n        \"loam asks it so that evidence, not prose, can answer it. \" +\n        \"`loam verify <FEAT>` derives a checklist from the feature's own artifacts: one claim per new service \" +\n        \"(`service.exists`), per operation the contract delta adds (`api.exposes`), per message the event contract \" +\n        \"newly declares (`event.declares`), per tagged edge that names an operation (`c4.calls`), and per scenario of \" +\n        \"every changed requirement (`scenario.tested`) — `loam explain <kind>` says what each one asks and who may answer it. \" +\n        \"Each claim has a stable id, so two runs are diffable and an answer cannot drift onto a different question; \" +\n        \"`loam tasks` uses the same id for the unit that closes it. \" +\n        \"An answer is `confirmed` with `file:line` evidence or `unconfirmed` with a note saying why — a successful \" +\n        \"record either way — and a claim nobody answered is `unanswered`. Every recorded answer says who gave it \" +\n        \"(`answered_by: runner | external-runner | agent`), and that is what separates **verified** from **attested**.\",\n      pins: [\n        { source: \"DONE_CHECK\", phrase: \"`loam verify <FEAT>` derives a checklist from the feature's own artifacts\" },\n        { source: \"DONE_CHECK\", phrase: \"Each claim has a stable id, so\" },\n        { source: \"DONE_CHECK\", phrase: \"two runs are diffable and an answer cannot drift onto a different question\" },\n        { source: \"DONE_CHECK\", phrase: \"`answered_by: runner | external-runner | agent`\" },\n      ],\n    },\n    {\n      term: \"service.exists\",\n      aliases: [],\n      paragraph:\n        \"A `service.exists` claim asks whether a service the feature introduces has actually been built. \" +\n        \"`loam verify` derives one per new service the feature's delta.likec4 adds to the fleet map. \" +\n        \"Answer it by finding it in the code, not by reasoning that it must be there. What to open: \" +\n        \"`service.exists` — the service is deployable: its build, its entry point. \" +\n        \"The answer is `file:line` evidence, recorded from that service's own repository with \" +\n        \"`loam verify <FEAT> --service <id> --record answers.json`. No test runner answers this kind, so an agent's \" +\n        \"word is the expected answer here, and it never makes the verdict **attested** — only scenario claims do.\",\n      pins: [{ source: \"VERIFY\", phrase: \"`service.exists` — the service is deployable: its build, its entry point.\" }],\n    },\n    {\n      term: \"api.exposes\",\n      aliases: [],\n      paragraph:\n        \"An `api.exposes` claim asks whether the service really serves an operation the feature's contract delta adds. \" +\n        \"`loam verify` derives one per operationId in the feature's openapi.yaml that the living contract does not \" +\n        \"already define; an operation the delta merely restates is never asked about. \" +\n        \"What to open: `api.exposes` — the route handler serving that operationId, not the spec that declares it. \" +\n        \"It also has a mechanical channel: an API contract-test run, passed back in loam's contract-results shape with \" +\n        \"`loam verify <FEAT> --contract-results contract.json`, answers it as `answered_by: external-runner`. \" +\n        \"In `loam tasks`, a `c4.calls` unit depends on the `api.exposes` unit that promises the operation it calls.\",\n      pins: [\n        { source: \"VERIFY\", phrase: \"`api.exposes` — the route handler serving that operationId, not the spec that\" },\n        { source: \"DONE_CHECK\", phrase: \"`loam verify <FEAT> --contract-results contract.json`\" },\n      ],\n    },\n    {\n      term: \"event.declares\",\n      aliases: [],\n      paragraph:\n        \"An `event.declares` claim asks whether the service sends or receives a message the feature's event contract \" +\n        \"newly declares. \" +\n        \"For a feature, `loam verify` derives one per (direction, message) its asyncapi delta newly declares against the \" +\n        \"living contract's send/receive sets — quotes and removals are never questions. \" +\n        \"What to open: `event.declares` — the code that puts the message on the wire (sends) or handles it off the \" +\n        \"wire (receives), not the contract that names it. \" +\n        \"It is answered with `file:line` evidence through `loam verify <FEAT> --service <id> --record answers.json`.\",\n      pins: [\n        { source: \"VERIFY\", phrase: \"`event.declares` — the code that puts the message on the wire (sends) or\" },\n        { source: \"VERIFY\", phrase: \"per (direction, message) its asyncapi delta newly declares against the living\" },\n      ],\n    },\n    {\n      term: \"c4.calls\",\n      aliases: [],\n      paragraph:\n        \"A `c4.calls` claim asks whether a call the feature draws on the architecture really exists in the caller's code. \" +\n        \"`loam verify` derives one per edge in delta.likec4 that is tagged with the feature and names an operation \" +\n        \"(`metadata { op '<operationId>' }`); an untagged edge is context, and an edge with no operation names nothing \" +\n        \"specific enough to look for. \" +\n        \"What to open: `c4.calls` — the call site in the CALLER. \" +\n        \"Its subject is the calling service, so it is answered from that service's repository, and in `loam tasks` it \" +\n        \"depends on the `api.exposes` unit for the operation it calls when the same feature adds that operation.\",\n      pins: [{ source: \"VERIFY\", phrase: \"`c4.calls` — the call site in the CALLER.\" }],\n    },\n    {\n      term: \"scenario.tested\",\n      aliases: [],\n      paragraph:\n        \"A `scenario.tested` claim asks whether one scenario of a changed requirement passes in a test run. \" +\n        \"The run is of the service's generated suite, in that service's own repository. \" +\n        \"`loam verify` derives one per scenario of every requirement the feature adds or modifies, arch.spec.md deltas \" +\n        \"included (those want an integration or ops test, not an acceptance test). \" +\n        \"The `scenario.tested` claims are the runner's to answer, not yours. Run the suite `loam gherkin <FEAT>` \" +\n        \"generated, with a JSON report, and pass it back with `loam verify <FEAT> --service <id> --results report.json`; \" +\n        \"the match is the scenario's `@loam-digest-…` tag. The digest is the only identity: a reworded spec scenario \" +\n        \"matches nothing until the suite is regenerated and re-run. \" +\n        \"With no runnable suite your word may answer them, and the feature is then **attested**, not verified — these \" +\n        \"are the only claims that verdict turns on.\",\n      pins: [\n        { source: \"VERIFY\", phrase: \"The `scenario.tested` claims are the runner's to answer, not yours.\" },\n        { source: \"DONE_CHECK\", phrase: \"The digest is the only identity: a reworded spec scenario matches\" },\n      ],\n    },\n    {\n      term: \"attested\",\n      aliases: [\"attest\", \"attestation\"],\n      paragraph:\n        \"Attested is the verdict one rung below verified on the done-check's ladder. \" +\n        \"Verified means somebody says the code was built and showed evidence — and for scenario claims that evidence is a \" +\n        \"test runner's report, answered mechanically. Without a runnable suite your word can still answer them \" +\n        \"(`loam verify <FEAT> --record` alone), but the record says who answered, and a feature whose \" +\n        \"scenario claims rest on an agent's word is **attested**, not verified. Nothing gates on the difference; \" +\n        \"pass `--results <report>` the moment a suite runs and the verdict moves on its own. \" +\n        \"In `loam tasks` it is also the fourth step a unit can wait at, and the one that is not work to write: \" +\n        \"the claim was closed on somebody's word rather than on a run, so the unit stays visible at `attested` until a \" +\n        \"test run re-records it.\",\n      pins: [\n        { source: \"REFUSALS\", phrase: \"somebody says the code was built and showed evidence\" },\n        // Left the cycle with the done-check teaching; repaired by following the\n        // text, as `vouch`'s two were.\n        { source: \"DONE_CHECK\", phrase: \"scenario claims rest on an agent's word is **attested**, not verified\" },\n        { source: \"IMPLEMENT\", phrase: \"the claim was closed on somebody's word rather than on a run\" },\n      ],\n    },\n    {\n      // The other half of the most overloaded word in loam's output. The status\n      // row and the scorecard print the verdict (`verified · attested ·\n      // unverified`), while a document's frontmatter prints `status: verified`\n      // for a vouch — and the two have nothing to do with each other. A reader\n      // who looks the word up after either one gets both meanings here.\n      term: \"verified\",\n      aliases: [\"unverified\", \"verdict\", \"verdicts\"],\n      paragraph:\n        \"Verified is the done-check's top verdict: every claim recorded confirmed, the scenario claims by a test run. \" +\n        \"Every claim on the checklist has an answer with evidence, and no scenario claim rests on somebody's word. \" +\n        \"A record's `verdict` (`verified` | `attested` | `unverified`) is computed from its claims, never stored: \" +\n        \"`unverified` means some claim is still unconfirmed or unanswered, or the record answers a checklist the feature \" +\n        \"no longer asks; **attested** means complete, with a scenario claim resting on an agent's word. \" +\n        \"Between `verified` and `attested` the verdict turns on the scenario claims alone, so a `verified` record can still rest \" +\n        \"partly on an agent's word about kinds the verdict does not turn on — `service.exists` or `c4.calls`, which \" +\n        \"only the code can answer. \" +\n        \"Only `verified` makes a feature in flight `done`. **Nothing gates on it.** `loam archive` will ship an \" +\n        \"unverified feature. \" +\n        \"The same word on a living document means something else: `status: verified` in a spec.md's frontmatter is a \" +\n        \"person's vouch for the words, not a test result (`loam explain vouch`).\",\n      pins: [\n        { source: \"CODES_PAGE\", phrase: \"`verdict` (`verified` | `attested` | `unverified`)\" },\n        { source: \"CODES_PAGE\", phrase: \"partly on an agent's word about kinds the verdict does not turn on\" },\n      ],\n    },\n  ],\n};\n"]}

package/dist/core/explain/terms/entry.js

@@ -0,0 +1,14 @@
+/**
+ * What one concept term IS, apart from any term's words: the entry shape the
+ * four subject modules beside this one fill in, and the names of the shipped
+ * pages a pin may point at.
+ *
+ * A module of its own, holding only types, because of where the assembler
+ * sits. `../terms.ts` imports every subject module of this package to build
+ * `TERMS`, so a subject module that reached back up into it for `TermEntry`
+ * would close a file-level cycle through a type — erased at runtime, but a
+ * cycle every graph in the gate still has to be told to ignore. Down here the
+ * graph stays a tree: the subjects import this, the assembler imports them.
+ */
+export {};
+//# sourceMappingURL=entry.js.map

package/dist/core/explain/terms/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../../../../src/core/explain/terms/entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG","sourcesContent":["/**\n * What one concept term IS, apart from any term's words: the entry shape the\n * four subject modules beside this one fill in, and the names of the shipped\n * pages a pin may point at.\n *\n * A module of its own, holding only types, because of where the assembler\n * sits. `../terms.ts` imports every subject module of this package to build\n * `TERMS`, so a subject module that reached back up into it for `TermEntry`\n * would close a file-level cycle through a type — erased at runtime, but a\n * cycle every graph in the gate still has to be told to ignore. Down here the\n * graph stays a tree: the subjects import this, the assembler imports them.\n */\n\n/**\n * The shipped texts a pin may name — each one a page `loam instructions`\n * prints, or the AGENTS.md loam writes. `../terms.ts` maps every name to its\n * bytes (`PIN_SOURCE_TEXT`), and the `Record` there makes a name added here\n * without a text a compile error rather than a pin that guards nothing.\n */\nexport type PinSource =\n  | \"AGENTS_MD\"\n  | \"SPINE_PAGE\"\n  | \"REFUSALS\"\n  | \"AUTHORING\"\n  | \"DRAWING\"\n  | \"DONE_CHECK\"\n  | \"CODES_PAGE\"\n  | \"CHECK\"\n  | \"FEATURE\"\n  | \"IMPLEMENT\"\n  | \"VERIFY\";\n\nexport interface TermPin {\n  readonly source: PinSource;\n  /** A verbatim single-line substring of both the paragraph and the source section. */\n  readonly phrase: string;\n}\n\nexport interface TermEntry {\n  readonly term: string;\n  readonly aliases: readonly string[];\n  /** The explanation. Its FIRST sentence doubles as the no-argument listing's summary. */\n  readonly paragraph: string;\n  readonly pins: readonly TermPin[];\n}\n\n/**\n * The terms of one subject, under the heading the bare `loam explain` listing\n * prints above them.\n *\n * The heading exists for a reader, not for the lookup: twenty-odd terms in one\n * flat column read as a glossary nobody scans, and the words a newcomer meets\n * arrive in clusters — the stages `loam status` prints, the claims and\n * verdicts of `loam verify`, the steps of `loam tasks` — so the listing is\n * grouped the way the output that printed them is. The `--json` listing stays\n * the flat `terms[]` it always was; a group is typography, never a key.\n */\nexport interface TermGroup {\n  readonly heading: string;\n  readonly terms: readonly TermEntry[];\n}\n"]}