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

package/dist/core/explain/lookup.js

@@ -0,0 +1,181 @@
+/**
+ * The explain lookup: one subject in — a finding code, an envelope refusal
+ * code, or a concept term — one discriminated explanation out. It also answers
+ * the two listings the command prints with no subject: `listTerms` for the
+ * concept vocabulary and `listCodes` for the code vocabulary, the latter built
+ * from the same `findingIn` the per-code answer uses so the inventory cannot
+ * describe a code differently from the page about it.
+ *
+ * Assembled ON DEMAND, never cached at module level: tests run in forked
+ * processes that chdir per invocation, and a long-running host (the MCP
+ * server) outlives many calls — a table built at import time is exactly the
+ * module-level mutable state AGENTS.md names as a hazard. The build is a walk
+ * over constants already in memory, so there is nothing worth caching anyway.
+ *
+ * Resolution order — finding tables first, then the family registry, then
+ * refusal codes, then terms — IS the tie-break: a subject in two families
+ * would silently take the earlier family's answer (a refusal named like a term
+ * alias would win over the term). No naming convention keeps them apart —
+ * `based-on` is a dashed term alias, exactly the shape a refusal code takes —
+ * so test/explain.test.ts asserts the key sets are pairwise disjoint, and the
+ * order never actually decides anything.
+ *
+ * The one place that order is load-bearing anyway is the fix tables against
+ * ./families.ts: the tables are PARSED from the bytes the binary ships and the
+ * registry is written by hand, so where both could answer, the parsed prose has
+ * to win and the hand-written row must never silently shadow it. It is written
+ * first here and asserted disjoint there, which makes the precedence a fact
+ * about the code as well as a fact about the data.
+ */
+import { COMMANDS } from "../agent/protocol.js";
+import { VALIDATE_CHECKS } from "../brief/checks.js";
+import { familyCodes, familyFinding } from "./families.js";
+import { parseFixRows } from "./fix-tables.js";
+import { REFUSAL_MEANINGS } from "./refusals.js";
+import { TERMS } from "./terms.js";
+/** Every fix-table row shipped in the workflow bodies, in protocol order. */
+function allRows() {
+    return COMMANDS.flatMap((command) => parseFixRows(command.body));
+}
+function briefFor(subject) {
+    return VALIDATE_CHECKS.find((check) => check.code === subject);
+}
+/** Terms match case-insensitively, by name or alias — codes stay exact, they are already lowercase by grammar. */
+function termFor(subject) {
+    const wanted = subject.toLowerCase();
+    return TERMS.find((entry) => entry.term === wanted || entry.aliases.includes(wanted));
+}
+/**
+ * The finding answer for one subject out of rows ALREADY parsed, or null when
+ * no table grades it.
+ *
+ * Split out of `explainSubject` so `listCodes` builds its rows through the
+ * very same function rather than a parallel one: the inventory's per-code
+ * payload is then the per-code answer by construction, not by two pieces of
+ * code agreeing. It also keeps the inventory's cost linear — `explainSubject`
+ * re-parses every workflow body on each call, and calling it 270 times to
+ * enumerate the vocabulary would re-walk the whole corpus 270 times.
+ */
+function findingIn(rows, subject) {
+    const brief = briefFor(subject);
+    // VALIDATE_CHECKS contributes `via` ONLY, never a fallback entry. An
+    // earlier draft synthesized a row from the brief when the tables had none,
+    // and that fallback was both unreachable (every brief check has a table
+    // row, pinned by test/explain.test.ts) and wrong if ever reached: its
+    // scope would have been the brief's invocation string, a spelling no
+    // parsed row uses. A brief check that LOSES its table row should fail
+    // loudly there — explain refusing is the tripwire — not render a
+    // one-of-a-kind page nobody else prints.
+    const entries = rows
+        .filter((row) => row.codes.includes(subject))
+        .map(({ scope, severityNote, meaning, fix }) => ({ scope, severityNote, meaning, fix }));
+    if (entries.length === 0)
+        return null;
+    return { kind: "finding", entries, ...(brief === undefined ? {} : { via: brief.via }) };
+}
+/**
+ * The finding answer from EITHER source, tables first.
+ *
+ * One function rather than two call sites choosing an order, because the order
+ * is the precedence rule: a code a fix table grades is answered from the bytes
+ * the binary ships, and ./families.ts only ever answers codes no table reaches.
+ * `via` is a fix-table-only fact — it comes from a `VALIDATE_CHECKS` entry, and
+ * no brief check names a `doctor.*`, `next.*`, `diff.*` or `gate.*` code — so a
+ * registry answer carries a single entry and nothing else, which is the same
+ * shape a one-table code already returns.
+ */
+function findingFor(rows, subject) {
+    const table = findingIn(rows, subject);
+    if (table !== null)
+        return table;
+    const family = familyFinding(subject);
+    return family === null ? null : { kind: "finding", entries: [family] };
+}
+export function explainSubject(subject) {
+    const finding = findingFor(allRows(), subject);
+    if (finding !== null)
+        return finding;
+    // Through Object.entries rather than an indexed read: the record's keys are
+    // `ErrorCode`, `subject` is an arbitrary string, and the Map lookup needs
+    // neither a key cast nor a hasOwn pre-check.
+    const refusal = new Map(Object.entries(REFUSAL_MEANINGS)).get(subject);
+    if (refusal !== undefined)
+        return { kind: "refusal", meaning: refusal };
+    const term = termFor(subject);
+    if (term !== undefined)
+        return { kind: "term", term: term.term, paragraph: term.paragraph };
+    return null;
+}
+/**
+ * Every subject `explainSubject` can answer — for the unknown-subject
+ * refusal's close-match suggestions. Sorted, so suggestion ties break the
+ * same way on every machine.
+ */
+export function knownSubjects() {
+    const known = new Set();
+    for (const row of allRows())
+        for (const rowCode of row.codes)
+            known.add(rowCode);
+    for (const familyCode of familyCodes())
+        known.add(familyCode);
+    for (const check of VALIDATE_CHECKS)
+        known.add(check.code);
+    for (const key of Object.keys(REFUSAL_MEANINGS))
+        known.add(key);
+    for (const entry of TERMS) {
+        known.add(entry.term);
+        for (const alias of entry.aliases)
+            known.add(alias);
+    }
+    return [...known].sort();
+}
+/**
+ * A paragraph's first sentence — the one-line summary form both listings
+ * print. One definition rather than two: the term listing and the code
+ * listing must cut prose the same way, or the same sentence reads as two
+ * different summaries depending on which command printed it.
+ */
+export function firstSentence(text) {
+    const cut = text.indexOf(". ");
+    return cut === -1 ? text : text.slice(0, cut + 1);
+}
+/** The no-argument listing: each term with its paragraph's first sentence as the one-line summary. */
+export function listTerms() {
+    return TERMS.map(({ term, paragraph }) => ({ term, summary: firstSentence(paragraph) }));
+}
+/**
+ * Every code `explainSubject` can answer — the machine-readable inventory of
+ * the vocabulary, which is otherwise discoverable only by parsing the 83 KB
+ * prose body of `loam instructions loam-check` or by reading TypeScript
+ * unions that are erased at runtime.
+ *
+ * Sorted within each kind rather than left in document order: the fix tables
+ * are ordered by scope for somebody working through one table, but an
+ * inventory is read by name and diffed between binaries, and document order
+ * would reshuffle on an unrelated table edit.
+ */
+export function listCodes() {
+    const rows = allRows();
+    // One sorted finding group over BOTH sources rather than a third listing
+    // heading. A caller building a code-to-fix cache asks "what does this binary
+    // explain", and a `doctor.*` row that arrived from ./families.ts rather than
+    // from a parsed table is the same answer to that question — the row it gets
+    // is `explain <code> --json`'s payload either way. Splitting them would put
+    // the provenance of the prose into the machine contract, where nothing
+    // branches on it.
+    const findings = [...new Set([...rows.flatMap((row) => row.codes), ...familyCodes()])]
+        .sort()
+        // Non-null: the code came out of `rows` or out of the registry, and
+        // `findingFor` reads exactly those two.
+        .map((code) => ({ code, ...findingFor(rows, code) }));
+    // Through a Map for the same reason `explainSubject` reads one: the record's
+    // keys are `ErrorCode` and this listing's are plain strings. Plain `.sort()`
+    // throughout, never `localeCompare` — the order is part of the machine
+    // contract and must not depend on the host's ICU locale.
+    const meanings = new Map(Object.entries(REFUSAL_MEANINGS));
+    const refusals = [...meanings.keys()]
+        .sort()
+        .map((code) => ({ code, kind: "refusal", meaning: meanings.get(code) }));
+    return [...findings, ...refusals];
+}
+//# sourceMappingURL=lookup.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"lookup.js","sourceRoot":"","sources":["../../../src/core/explain/lookup.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The explain lookup: one subject in — a finding code, an envelope refusal\n * code, or a concept term — one discriminated explanation out. It also answers\n * the two listings the command prints with no subject: `listTerms` for the\n * concept vocabulary and `listCodes` for the code vocabulary, the latter built\n * from the same `findingIn` the per-code answer uses so the inventory cannot\n * describe a code differently from the page about it.\n *\n * Assembled ON DEMAND, never cached at module level: tests run in forked\n * processes that chdir per invocation, and a long-running host (the MCP\n * server) outlives many calls — a table built at import time is exactly the\n * module-level mutable state AGENTS.md names as a hazard. The build is a walk\n * over constants already in memory, so there is nothing worth caching anyway.\n *\n * Resolution order — finding tables first, then the family registry, then\n * refusal codes, then terms — IS the tie-break: a subject in two families\n * would silently take the earlier family's answer (a refusal named like a term\n * alias would win over the term). No naming convention keeps them apart —\n * `based-on` is a dashed term alias, exactly the shape a refusal code takes —\n * so test/explain.test.ts asserts the key sets are pairwise disjoint, and the\n * order never actually decides anything.\n *\n * The one place that order is load-bearing anyway is the fix tables against\n * ./families.ts: the tables are PARSED from the bytes the binary ships and the\n * registry is written by hand, so where both could answer, the parsed prose has\n * to win and the hand-written row must never silently shadow it. It is written\n * first here and asserted disjoint there, which makes the precedence a fact\n * about the code as well as a fact about the data.\n */\nimport { COMMANDS } from \"../agent/protocol.js\";\nimport { VALIDATE_CHECKS, type BriefCheck } from \"../brief/checks.js\";\nimport { familyCodes, familyFinding } from \"./families.js\";\nimport { parseFixRows, type FixRow } from \"./fix-tables.js\";\nimport { REFUSAL_MEANINGS } from \"./refusals.js\";\nimport { TERMS, type TermEntry } from \"./terms.js\";\n\nexport interface FindingEntry {\n  /** Which table graded it — `--service <id>`, `--feature <FEAT-id>`, `--all`, `loam archive`, … */\n  readonly scope: string;\n  /** The table's verbatim parenthetical, or \"error\" — its default. */\n  readonly severityNote: string;\n  readonly meaning: string;\n  readonly fix: string;\n}\n\nexport type Explanation =\n  | { readonly kind: \"finding\"; readonly entries: readonly FindingEntry[]; readonly via?: string }\n  | { readonly kind: \"refusal\"; readonly meaning: string }\n  | { readonly kind: \"term\"; readonly term: string; readonly paragraph: string };\n\n/** Every fix-table row shipped in the workflow bodies, in protocol order. */\nfunction allRows(): FixRow[] {\n  return COMMANDS.flatMap((command) => parseFixRows(command.body));\n}\n\nfunction briefFor(subject: string): BriefCheck | undefined {\n  return VALIDATE_CHECKS.find((check) => check.code === subject);\n}\n\n/** Terms match case-insensitively, by name or alias — codes stay exact, they are already lowercase by grammar. */\nfunction termFor(subject: string): TermEntry | undefined {\n  const wanted = subject.toLowerCase();\n  return TERMS.find((entry) => entry.term === wanted || entry.aliases.includes(wanted));\n}\n\n/**\n * The finding answer for one subject out of rows ALREADY parsed, or null when\n * no table grades it.\n *\n * Split out of `explainSubject` so `listCodes` builds its rows through the\n * very same function rather than a parallel one: the inventory's per-code\n * payload is then the per-code answer by construction, not by two pieces of\n * code agreeing. It also keeps the inventory's cost linear — `explainSubject`\n * re-parses every workflow body on each call, and calling it 270 times to\n * enumerate the vocabulary would re-walk the whole corpus 270 times.\n */\nfunction findingIn(rows: readonly FixRow[], subject: string): Extract<Explanation, { kind: \"finding\" }> | null {\n  const brief = briefFor(subject);\n  // VALIDATE_CHECKS contributes `via` ONLY, never a fallback entry. An\n  // earlier draft synthesized a row from the brief when the tables had none,\n  // and that fallback was both unreachable (every brief check has a table\n  // row, pinned by test/explain.test.ts) and wrong if ever reached: its\n  // scope would have been the brief's invocation string, a spelling no\n  // parsed row uses. A brief check that LOSES its table row should fail\n  // loudly there — explain refusing is the tripwire — not render a\n  // one-of-a-kind page nobody else prints.\n  const entries: FindingEntry[] = rows\n    .filter((row) => row.codes.includes(subject))\n    .map(({ scope, severityNote, meaning, fix }) => ({ scope, severityNote, meaning, fix }));\n  if (entries.length === 0) return null;\n  return { kind: \"finding\", entries, ...(brief === undefined ? {} : { via: brief.via }) };\n}\n\n/**\n * The finding answer from EITHER source, tables first.\n *\n * One function rather than two call sites choosing an order, because the order\n * is the precedence rule: a code a fix table grades is answered from the bytes\n * the binary ships, and ./families.ts only ever answers codes no table reaches.\n * `via` is a fix-table-only fact — it comes from a `VALIDATE_CHECKS` entry, and\n * no brief check names a `doctor.*`, `next.*`, `diff.*` or `gate.*` code — so a\n * registry answer carries a single entry and nothing else, which is the same\n * shape a one-table code already returns.\n */\nfunction findingFor(rows: readonly FixRow[], subject: string): Extract<Explanation, { kind: \"finding\" }> | null {\n  const table = findingIn(rows, subject);\n  if (table !== null) return table;\n  const family = familyFinding(subject);\n  return family === null ? null : { kind: \"finding\", entries: [family] };\n}\n\nexport function explainSubject(subject: string): Explanation | null {\n  const finding = findingFor(allRows(), subject);\n  if (finding !== null) return finding;\n  // Through Object.entries rather than an indexed read: the record's keys are\n  // `ErrorCode`, `subject` is an arbitrary string, and the Map lookup needs\n  // neither a key cast nor a hasOwn pre-check.\n  const refusal = new Map<string, string>(Object.entries(REFUSAL_MEANINGS)).get(subject);\n  if (refusal !== undefined) return { kind: \"refusal\", meaning: refusal };\n  const term = termFor(subject);\n  if (term !== undefined) return { kind: \"term\", term: term.term, paragraph: term.paragraph };\n  return null;\n}\n\n/**\n * Every subject `explainSubject` can answer — for the unknown-subject\n * refusal's close-match suggestions. Sorted, so suggestion ties break the\n * same way on every machine.\n */\nexport function knownSubjects(): string[] {\n  const known = new Set<string>();\n  for (const row of allRows()) for (const rowCode of row.codes) known.add(rowCode);\n  for (const familyCode of familyCodes()) known.add(familyCode);\n  for (const check of VALIDATE_CHECKS) known.add(check.code);\n  for (const key of Object.keys(REFUSAL_MEANINGS)) known.add(key);\n  for (const entry of TERMS) {\n    known.add(entry.term);\n    for (const alias of entry.aliases) known.add(alias);\n  }\n  return [...known].sort();\n}\n\n/**\n * A paragraph's first sentence — the one-line summary form both listings\n * print. One definition rather than two: the term listing and the code\n * listing must cut prose the same way, or the same sentence reads as two\n * different summaries depending on which command printed it.\n */\nexport function firstSentence(text: string): string {\n  const cut = text.indexOf(\". \");\n  return cut === -1 ? text : text.slice(0, cut + 1);\n}\n\n/** The no-argument listing: each term with its paragraph's first sentence as the one-line summary. */\nexport function listTerms(): Array<{ term: string; summary: string }> {\n  return TERMS.map(({ term, paragraph }) => ({ term, summary: firstSentence(paragraph) }));\n}\n\n/**\n * One row of the code inventory: the per-code answer with its code attached.\n *\n * DERIVED from `Explanation` rather than restated, so `loam explain <code>\n * --json` and `loam explain --codes --json` cannot describe the same code with\n * two different key sets — a caching consumer reads one and looks up the other.\n * The `term` arm is excluded on purpose: a concept term is a different kind of\n * subject, and the bare `loam explain` listing keeps them.\n *\n * There is deliberately NO `severity` or `gates` key here, and adding one\n * would be a defect rather than an improvement. A fix table carries only the\n * verbatim parenthetical its author wrote (`warn, gates archive; one per\n * service`), which is prose about a scope, while the answer a caller would\n * actually branch on is computed per ISSUE at runtime by `gatesArchive()` and\n * `approveOverrides()` in core/vocabulary/issue.ts — from `severity`, an\n * optional per-issue `gates`, and a never-overridable code set. A severity\n * derived from the parenthetical here would be a second answer to a question\n * that already has one, free to disagree with the binary's own gate.\n */\nexport type CodeListing = { readonly code: string } & Exclude<Explanation, { kind: \"term\" }>;\n\n/**\n * Every code `explainSubject` can answer — the machine-readable inventory of\n * the vocabulary, which is otherwise discoverable only by parsing the 83 KB\n * prose body of `loam instructions loam-check` or by reading TypeScript\n * unions that are erased at runtime.\n *\n * Sorted within each kind rather than left in document order: the fix tables\n * are ordered by scope for somebody working through one table, but an\n * inventory is read by name and diffed between binaries, and document order\n * would reshuffle on an unrelated table edit.\n */\nexport function listCodes(): CodeListing[] {\n  const rows = allRows();\n  // One sorted finding group over BOTH sources rather than a third listing\n  // heading. A caller building a code-to-fix cache asks \"what does this binary\n  // explain\", and a `doctor.*` row that arrived from ./families.ts rather than\n  // from a parsed table is the same answer to that question — the row it gets\n  // is `explain <code> --json`'s payload either way. Splitting them would put\n  // the provenance of the prose into the machine contract, where nothing\n  // branches on it.\n  const findings: CodeListing[] = [...new Set([...rows.flatMap((row) => row.codes), ...familyCodes()])]\n    .sort()\n    // Non-null: the code came out of `rows` or out of the registry, and\n    // `findingFor` reads exactly those two.\n    .map((code) => ({ code, ...findingFor(rows, code)! }));\n  // Through a Map for the same reason `explainSubject` reads one: the record's\n  // keys are `ErrorCode` and this listing's are plain strings. Plain `.sort()`\n  // throughout, never `localeCompare` — the order is part of the machine\n  // contract and must not depend on the host's ICU locale.\n  const meanings = new Map<string, string>(Object.entries(REFUSAL_MEANINGS));\n  const refusals: CodeListing[] = [...meanings.keys()]\n    .sort()\n    .map((code) => ({ code, kind: \"refusal\" as const, meaning: meanings.get(code)! }));\n  return [...findings, ...refusals];\n}\n"]}

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: the living docs changed after the 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 — the all-at-once form would erase other repositories' attestations, so it is refused naming the attestors; record per service instead.",
+    "record-unreadable": "A verification.yaml exists but cannot be read as a record — it is never overwritten and never reported as absent; repair it by hand, or re-record from the service's repo.",
+    "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 — the rename would sweep them into a move 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 — `loam seed` never overwrites human work and wrote nothing; fold the edits into fleet.yaml and delete the file, or keep the hand-authored map and stop using seed.",
+    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,gMAAgM;IAClM,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,uNAAuN;IACzN,mBAAmB,EACjB,4KAA4K;IAC9K,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,kOAAkO;IACpO,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,mSAAmS;IACrS,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: the living docs changed after the 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 — the all-at-once form would erase other repositories' attestations, so it is refused naming the attestors; record per service instead.\",\n  \"record-unreadable\":\n    \"A verification.yaml exists but cannot be read as a record — it is never overwritten and never reported as absent; repair it by hand, or re-record from the service's repo.\",\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 — the rename would sweep them into a move 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 — `loam seed` never overwrites human work and wrote nothing; fold the edits into fleet.yaml and delete the file, or keep the hand-authored map and stop using seed.\",\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.js

@@ -0,0 +1,144 @@
+/**
+ * The concept terms `loam explain` answers — the vocabulary wall an agent hits
+ * in its first minute, before any docs repo exists to read.
+ *
+ * Each paragraph is authored HERE, but it is not free to drift: every entry
+ * carries pin phrases lifted VERBATIM from the section that teaches the
+ * concept, and test/explain.test.ts asserts each phrase appears both in the
+ * paragraph and in its named source constant. Rewording that prose therefore
+ * breaks the pairing loudly — the same discipline the compiler applies to
+ * refusals.ts, done with a test because prose has no type. A pin phrase is
+ * kept to one source LINE, because the sections wrap at ~80 columns and a
+ * phrase spanning a wrap would never match.
+ *
+ * A source is no longer always an agents-md section. When the reference pages
+ * were split out of the scaffolded AGENTS.md, the frontmatter teaching went
+ * with them, and `vouch`'s pin went with the text rather than being reworded
+ * to something still in the file — the pairing is with whatever loam SHIPS as
+ * the teaching, not with one delivery of it.
+ */
+import { ARTIFACTS } from "../agent/agents-md/artifacts.js";
+import { CYCLE } from "../agent/agents-md/cycle.js";
+import { REFUSALS } from "../agent/agents-md/refusals.js";
+import { SPINE } from "../agent/agents-md/spine.js";
+import { LOAM_AUTHORING } from "../agent/workflows/reference/authoring.js";
+import { LOAM_DONE_CHECK } from "../agent/workflows/reference/done-check.js";
+import { LOAM_SPINE } from "../agent/workflows/reference/spine.js";
+/**
+ * The section constants the pins point at, for the drift test and for anyone
+ * auditing a pairing.
+ *
+ * `REFUSALS` is still listed and still pinned against, and it is no longer a
+ * section of AGENTS.md — it is the refusal half of the `loam-codes` page. The
+ * constant is what a pin names, and the constant did not move; only its
+ * delivery did.
+ */
+export const PIN_SOURCE_TEXT = {
+    SPINE,
+    SPINE_PAGE: LOAM_SPINE.body,
+    REFUSALS,
+    CYCLE,
+    ARTIFACTS,
+    AUTHORING: LOAM_AUTHORING.body,
+    DONE_CHECK: LOAM_DONE_CHECK.body,
+};
+export const TERMS = [
+    {
+        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." },
+        ],
+    },
+    {
+        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.",
+        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" },
+        ],
+    },
+    {
+        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: "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: [
+            { source: "ARTIFACTS", phrase: "is a diff against it, reviewed as a diff" },
+            { source: "ARTIFACTS", phrase: "`loam archive` folds the delta into the living state." },
+        ],
+    },
+    {
+        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" },
+        ],
+    },
+    {
+        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".` },
+        ],
+    },
+];
+//# sourceMappingURL=terms.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"terms.js","sourceRoot":"","sources":["../../../src/core/explain/terms.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The concept terms `loam explain` answers — the vocabulary wall an agent hits\n * in its first minute, before any docs repo exists to read.\n *\n * Each paragraph is authored HERE, but it is not free to drift: every entry\n * carries pin phrases lifted VERBATIM from the section that teaches the\n * concept, and test/explain.test.ts asserts each phrase appears both in the\n * paragraph and in its named source constant. Rewording that prose therefore\n * breaks the pairing loudly — the same discipline the compiler applies to\n * refusals.ts, done with a test because prose has no type. A pin phrase is\n * kept to one source LINE, because the sections wrap at ~80 columns and a\n * phrase spanning a wrap would never match.\n *\n * A source is no longer always an agents-md section. When the reference pages\n * were split out of the scaffolded AGENTS.md, the frontmatter teaching went\n * with them, and `vouch`'s pin went with the text rather than being reworded\n * to something still in the file — the pairing is with whatever loam SHIPS as\n * the teaching, not with one delivery of it.\n */\nimport { ARTIFACTS } from \"../agent/agents-md/artifacts.js\";\nimport { CYCLE } from \"../agent/agents-md/cycle.js\";\nimport { REFUSALS } from \"../agent/agents-md/refusals.js\";\nimport { SPINE } from \"../agent/agents-md/spine.js\";\nimport { LOAM_AUTHORING } from \"../agent/workflows/reference/authoring.js\";\nimport { LOAM_DONE_CHECK } from \"../agent/workflows/reference/done-check.js\";\nimport { LOAM_SPINE } from \"../agent/workflows/reference/spine.js\";\n\nexport type PinSource =\n  | \"SPINE\"\n  | \"SPINE_PAGE\"\n  | \"REFUSALS\"\n  | \"CYCLE\"\n  | \"ARTIFACTS\"\n  | \"AUTHORING\"\n  | \"DONE_CHECK\";\n\n/**\n * The section constants the pins point at, for the drift test and for anyone\n * auditing a pairing.\n *\n * `REFUSALS` is still listed and still pinned against, and it is no longer a\n * section of AGENTS.md — it is the refusal half of the `loam-codes` page. The\n * constant is what a pin names, and the constant did not move; only its\n * delivery did.\n */\nexport const PIN_SOURCE_TEXT: Record<PinSource, string> = {\n  SPINE,\n  SPINE_PAGE: LOAM_SPINE.body,\n  REFUSALS,\n  CYCLE,\n  ARTIFACTS,\n  AUTHORING: LOAM_AUTHORING.body,\n  DONE_CHECK: LOAM_DONE_CHECK.body,\n};\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\nexport const TERMS: readonly TermEntry[] = [\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    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    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    ],\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: \"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      { source: \"ARTIFACTS\", phrase: \"is a diff against it, reviewed as a diff\" },\n      { source: \"ARTIFACTS\", phrase: \"`loam archive` folds the delta into the living state.\" },\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    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"]}

package/dist/core/explore/describe.js

@@ -0,0 +1,105 @@
+/**
+ * One service as the explorer sees it: what it is, what it touches, and the
+ * `loam new` line that would start work on it.
+ *
+ * Split from the walk in `./explore.ts` because it answers per SERVICE while
+ * that answers per QUESTION — the walk decides which services are in the answer
+ * and why, this fills each one in. `DescribeRequest` is a record rather than a
+ * parameter list for the ordinary reason: nine facts about one service, and no
+ * call site should be able to transpose two of them.
+ */
+import { existsSync } from "node:fs";
+import { FleetContext } from "../fleet-context.js";
+import {} from "../c4/likec4.js";
+import { landscapeEvidence, maturityGaps, serviceMaturity } from "../vocabulary/maturity.js";
+import { compareIds } from "../repo/entries.js";
+import { servicePathsAt } from "../repo/paths.js";
+// Type-only, so it is erased and no runtime edge points back at the walk.
+import {} from "./explore.js";
+export async function describe(req) {
+    const { id, reason, entry, relationships, svcOf } = req;
+    // The edge partition, the modelled probe and the apiExpected rule are ONE
+    // derivation (core/vocabulary/maturity.ts `landscapeEvidence`), shared with
+    // the context pack's living slice — the same rule spelled twice is how the
+    // same service grades `partial` in one command and `documented` in another.
+    const { inbound, outbound, modelled, apiExpected } = landscapeEvidence({
+        id,
+        parses: req.parses,
+        relationships,
+        elementIds: req.elements.map((e) => e.id),
+        svcOf,
+    });
+    // A service that does not exist has no rung: `empty` would be a claim about a
+    // directory nobody has made, and it reads as "exists, nothing in it" — the
+    // one state a caller most needs to tell it apart from.
+    if (entry === undefined) {
+        return {
+            id,
+            reason,
+            known: false,
+            maturity: null,
+            missing: [],
+            modelled,
+            operations: [],
+            // Not `unreadable`: there is no contract here to fail to read. A service
+            // with no directory owes nothing, and reporting a parse failure over an
+            // absent file would send a reader looking for a document to fix.
+            openapi: { unreadable: false },
+            inbound,
+            outbound,
+        };
+    }
+    const archSpec = existsSync(servicePathsAt(entry.dir).archSpec);
+    const input = { entry, archSpec, apiExpected };
+    // `readOpenapi`, not `operationIds`: a contract that exists but does not
+    // parse comes back from the id list as an EMPTY set, indistinguishable from a
+    // service with no endpoints — and "this service offers nothing" is the worst
+    // possible lie to tell somebody deciding whether to call it.
+    const api = await req.context.readOpenapi(servicePathsAt(entry.dir).openapi);
+    const operations = api.ops.filter((o) => !o.remove).map((o) => o.id);
+    return {
+        id,
+        reason,
+        known: true,
+        maturity: serviceMaturity(input),
+        missing: maturityGaps(input),
+        modelled,
+        operations,
+        openapi: {
+            unreadable: api.unreadable,
+            ...(api.error === undefined ? {} : { error: api.error }),
+        },
+        inbound,
+        outbound,
+    };
+}
+/**
+ * The service whose living contract defines an operationId, or null.
+ *
+ * Reads every service's `openapi.yaml`, which is the cost of asking a question
+ * nothing indexes. It is YAML, not LikeC4 — the expensive parse in this
+ * codebase — and it happens only when somebody passes `--op`.
+ */
+export async function operationOwner(entries, op, context) {
+    for (const entry of entries) {
+        if (!entry.has.openapi)
+            continue;
+        const api = await context.readOpenapi(servicePathsAt(entry.dir).openapi);
+        if (api.ops.some((o) => o.id === op && !o.remove))
+            return entry.id;
+    }
+    return null;
+}
+/**
+ * The `loam new` line the seeds imply. A seed that names no existing service is
+ * `--new-service`, not `--touches`: those are different scaffolds, and getting
+ * it wrong is what leaves a feature with a requirement delta for a service that
+ * has no directory to archive into.
+ */
+export function newCommand(featureId, seeds, known) {
+    const flags = [...seeds]
+        .sort(compareIds)
+        .map((id) => (known.has(id) ? `--touches ${id}` : `--new-service ${id}`));
+    return `loam new ${featureId}${flags.length > 0 ? ` ${flags.join(" ")}` : ""}`;
+}
+//# sourceMappingURL=describe.js.map

package/dist/core/explore/describe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe.js","sourceRoot":"","sources":["../../../src/core/explore/describe.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * One service as the explorer sees it: what it is, what it touches, and the\n * `loam new` line that would start work on it.\n *\n * Split from the walk in `./explore.ts` because it answers per SERVICE while\n * that answers per QUESTION — the walk decides which services are in the answer\n * and why, this fills each one in. `DescribeRequest` is a record rather than a\n * parameter list for the ordinary reason: nine facts about one service, and no\n * call site should be able to transpose two of them.\n */\nimport { existsSync } from \"node:fs\";\nimport { FleetContext } from \"../fleet-context.js\";\nimport { type Elem, type Rel } from \"../c4/likec4.js\";\nimport { landscapeEvidence, maturityGaps, serviceMaturity } from \"../vocabulary/maturity.js\";\nimport { compareIds, type ServiceEntry } from \"../repo/entries.js\";\nimport { servicePathsAt } from \"../repo/paths.js\";\n// Type-only, so it is erased and no runtime edge points back at the walk.\nimport { type ExploreReason, type ExploreService } from \"./explore.js\";\n\ninterface DescribeRequest {\n  id: string;\n  reason: ExploreReason;\n  entry: ServiceEntry | undefined;\n  relationships: Rel[];\n  svcOf: (id: string) => string;\n  elements: Elem[];\n  /** Whether the landscape parsed — what makes its silence evidence rather than absence. */\n  parses: boolean;\n  context: FleetContext;\n}\n\nexport async function describe(req: DescribeRequest): Promise<ExploreService> {\n  const { id, reason, entry, relationships, svcOf } = req;\n\n  // The edge partition, the modelled probe and the apiExpected rule are ONE\n  // derivation (core/vocabulary/maturity.ts `landscapeEvidence`), shared with\n  // the context pack's living slice — the same rule spelled twice is how the\n  // same service grades `partial` in one command and `documented` in another.\n  const { inbound, outbound, modelled, apiExpected } = landscapeEvidence({\n    id,\n    parses: req.parses,\n    relationships,\n    elementIds: req.elements.map((e) => e.id),\n    svcOf,\n  });\n\n  // A service that does not exist has no rung: `empty` would be a claim about a\n  // directory nobody has made, and it reads as \"exists, nothing in it\" — the\n  // one state a caller most needs to tell it apart from.\n  if (entry === undefined) {\n    return {\n      id,\n      reason,\n      known: false,\n      maturity: null,\n      missing: [],\n      modelled,\n      operations: [],\n      // Not `unreadable`: there is no contract here to fail to read. A service\n      // with no directory owes nothing, and reporting a parse failure over an\n      // absent file would send a reader looking for a document to fix.\n      openapi: { unreadable: false },\n      inbound,\n      outbound,\n    };\n  }\n\n  const archSpec = existsSync(servicePathsAt(entry.dir).archSpec);\n  const input = { entry, archSpec, apiExpected };\n\n  // `readOpenapi`, not `operationIds`: a contract that exists but does not\n  // parse comes back from the id list as an EMPTY set, indistinguishable from a\n  // service with no endpoints — and \"this service offers nothing\" is the worst\n  // possible lie to tell somebody deciding whether to call it.\n  const api = await req.context.readOpenapi(servicePathsAt(entry.dir).openapi);\n  const operations = api.ops.filter((o) => !o.remove).map((o) => o.id);\n\n  return {\n    id,\n    reason,\n    known: true,\n    maturity: serviceMaturity(input),\n    missing: maturityGaps(input),\n    modelled,\n    operations,\n    openapi: {\n      unreadable: api.unreadable,\n      ...(api.error === undefined ? {} : { error: api.error }),\n    },\n    inbound,\n    outbound,\n  };\n}\n\n/**\n * The service whose living contract defines an operationId, or null.\n *\n * Reads every service's `openapi.yaml`, which is the cost of asking a question\n * nothing indexes. It is YAML, not LikeC4 — the expensive parse in this\n * codebase — and it happens only when somebody passes `--op`.\n */\nexport async function operationOwner(\n  entries: ServiceEntry[],\n  op: string,\n  context: FleetContext,\n): Promise<ServiceEntry[\"id\"] | null> {\n  for (const entry of entries) {\n    if (!entry.has.openapi) continue;\n    const api = await context.readOpenapi(servicePathsAt(entry.dir).openapi);\n    if (api.ops.some((o) => o.id === op && !o.remove)) return entry.id;\n  }\n  return null;\n}\n\n/**\n * The `loam new` line the seeds imply. A seed that names no existing service is\n * `--new-service`, not `--touches`: those are different scaffolds, and getting\n * it wrong is what leaves a feature with a requirement delta for a service that\n * has no directory to archive into.\n */\nexport function newCommand(featureId: string, seeds: string[], known: ReadonlySet<string>): string {\n  const flags = [...seeds]\n    .sort(compareIds)\n    .map((id) => (known.has(id) ? `--touches ${id}` : `--new-service ${id}`));\n  return `loam new ${featureId}${flags.length > 0 ? ` ${flags.join(\" \")}` : \"\"}`;\n}\n"]}