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

package/dist/commands/vouch/vouch.js

@@ -1,5 +1,4 @@
-import { loadConfig } from "../../core/envelope/config.js";
-import { fail, NO_SERVICE_MESSAGE, reportNoConfig } from "../../core/envelope/json.js";
+import { configOrRefuse, fail, NO_SERVICE_MESSAGE } from "../../core/envelope/json.js";
 import { gitIdentity } from "../../core/provenance/git.js";
 import { today } from "../../core/provenance/stamp.js";
 import { serviceTreePathOf } from "../../core/repo/service-target.js";
@@ -20,12 +19,9 @@ export function registerVouch(program) {
         .option("--json", "emit the machine contract instead of the human view")
         .action(async (opts) => {
         const json = opts.json === true;
-        const loaded = await loadConfig();
-        if (loaded.kind !== "loaded") {
-            reportNoConfig(json, loaded);
+        const config = await configOrRefuse(json);
+        if (config === null)
             return;
-        }
-        const config = loaded.config;
         const service = opts.service ?? config.service;
         if (service === undefined) {
             return fail(json, "invalid-option", NO_SERVICE_MESSAGE);
@@ -98,16 +94,13 @@ export function registerVouch(program) {
                 "record a claim with nobody behind it — which is the one thing `status: verified` must not mean. " +
                 "Set it (`git config user.email you@example.com`) and re-run.");
         }
-        // Whether a person is actually here. `vouch` is the only command in loam
-        // whose output is a claim about a HUMAN act — every other check is
-        // internal consistency, which fluent prose satisfies — and it used to run
-        // unattended, unattributed, twice in a row, stamping `verified` both
-        // times. Meanwhile the generated skill files pre-approved `Bash(loam:*)`,
-        // so the same agent that wrote the draft was permitted to promote it.
-        // That inverts loam's own argument about test evidence: an agent must not
-        // be able to SAY a scenario is tested, and it must not be able to say a
-        // spec matches the code either. The allowlist no longer covers this
-        // command (core/agent/tools/dialects.ts), and nothing but a terminal or an explicit
+        // Whether a person is actually here — the gate the banner's "records a
+        // person" paragraph tells the history of. `vouch` is the only command in
+        // loam whose output is a claim about a HUMAN act — every other check is
+        // internal consistency, which fluent prose satisfies — and why an agent
+        // must not be able to make that claim for itself is recorded on the
+        // allowlist that no longer covers this command
+        // (core/agent/tools/dialects.ts). Nothing but a terminal or an explicit
         // `--yes` gets past here.
         const attended = opts.yes === true;
         if (!attended) {

package/dist/commands/vouch/vouch.js.map

@@ -1 +1 @@
-{"version":3,"file":"vouch.js","sourceRoot":"","sources":["../../../src/commands/vouch/vouch.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { loadConfig } from \"../../core/envelope/config.js\";\nimport { fail, NO_SERVICE_MESSAGE, reportNoConfig } from \"../../core/envelope/json.js\";\nimport { gitIdentity } from \"../../core/provenance/git.js\";\nimport { today } from \"../../core/provenance/stamp.js\";\nimport { serviceTreePathOf } from \"../../core/repo/service-target.js\";\nimport { runPack } from \"./pack/print.js\";\nimport { confirmVouch } from \"./prompt/confirm.js\";\nimport { emitStampJson, printStamp } from \"./report.js\";\nimport { vouch } from \"./run.js\";\nimport { buildSamplePlan, type SamplePlan } from \"./sample/plan.js\";\nimport { printReadingList } from \"./sample/print.js\";\n\n/**\n * `loam vouch` — the human act SCHEMA.md has always described as \"promote draft\n * -> verified\".\n *\n * Everything else loam checks is internal consistency, and an agent writing\n * fluent prose satisfies all of it. This is the one command that records a\n * person: they read the code, they say the document matches it, and loam stamps\n * a digest of what they read — and a digest of the document they read it\n * against, so neither side can move quietly. From then on `loam validate` can\n * tell the difference between a document nobody has checked, one that still\n * matches the code, one the code has moved out from under, and one whose own\n * prose changed after the stamp.\n *\n * \"Records a person\" was, for two releases, a thing this file said and did not\n * do. There was no `vouched_by`, no identity of any kind and no interactive\n * gate, so an agent could run it twice unattended and stamp `verified` both\n * times — while the skill files loam generates pre-approved `Bash(loam:*)`,\n * which meant the agent that wrote the draft was permitted to promote it. Three\n * things close that, and none of them is a signature: the stamp carries git's\n * `user.email` (`vouched_by`), the run refuses without a terminal or an explicit\n * `--yes`, and the generated allowlist names loam's read-only and authoring\n * verbs one by one instead of all of them (core/agent/tools/dialects.ts). What that buys is\n * attribution and a deliberate act, not proof — git config is a text file. A\n * reviewer can now ask a named person what they read, which is the question\n * `status: verified` was silently answering with nobody.\n *\n * The stamp is only worth what it claims, so vouch refuses everything it cannot\n * actually verify — a frontmatter block that will not parse (whose fields\n * nobody can read, and whose rewrite would lose the author's lines), a spec\n * with no sources, a glob pattern (no longer supported), a source that is\n * gone, a directory holding no files, or a repo that is not this service's —\n * and refuses without writing anything.\n *\n * \"The document\" is every spec-axis file the service has: spec.md always, and\n * arch.spec.md beside it when present — same frontmatter conventions, same\n * stamp, one vouch. The refusal discipline is per file but the vouch is\n * all-or-nothing per service: one unverifiable file refuses the whole run, so\n * a `verified` service never means \"half-stamped\".\n */\n\ninterface VouchOptions {\n  service?: string;\n  yes?: boolean;\n  pack?: boolean;\n  /** `--sample <n>` as typed — a string until it is proved to be a whole number. */\n  sample?: string;\n  json?: boolean;\n}\n\nexport function registerVouch(program: Command): void {\n  program\n    .command(\"vouch\")\n    .description(\n      \"Vouch for a service's living specs: stamp spec.md, and arch.spec.md when present, verified against the code they describe\",\n    )\n    .option(\"--service <id>\", \"service to vouch for (defaults to the configured service)\")\n    .option(\n      \"--yes\",\n      \"skip the confirmation — required when stdin is not a terminal, and still records `vouched_by`\",\n    )\n    .option(\n      \"--pack\",\n      \"print the re-vouch reading pack — the doc-body diff since the last vouch, the source files that moved, and the sections already covered — then exit without vouching; read-only, nothing is stamped\",\n    )\n    .option(\n      \"--sample <n>\",\n      \"vouch after reading a deterministic sample of <n> sections per spec file — the stamp records `vouch_scope: sampled`, `loam list` shows `vouched (sampled)`, and `loam validate` reports `sources.sampled-vouch` until a full vouch clears it\",\n    )\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: VouchOptions) => {\n      const json = opts.json === true;\n\n      const loaded = await loadConfig();\n      if (loaded.kind !== \"loaded\") {\n        reportNoConfig(json, loaded);\n        return;\n      }\n      const config = loaded.config;\n\n      const service = opts.service ?? config.service;\n      if (service === undefined) {\n        return fail(json, \"invalid-option\", NO_SERVICE_MESSAGE);\n      }\n      // Vouching hashes the code the doc was written from, so it can only run\n      // where that code is. From anywhere else the paths are someone else's.\n      //\n      // TWO conditions, two codes, and the split is the whole point. Both used\n      // to answer `invalid-option`, whose `loam explain` row says the\n      // invocation itself is wrong — contradictory flags, a mistyped one, a\n      // value that cannot be right. Here the invocation is perfectly correct\n      // and the REPOSITORY is the wrong one, so that code sent a user whose\n      // flags were fine off to re-read their flags, and left CI and agents\n      // unable to tell \"run this in the service repo\" from \"you typed the flag\n      // wrong\". `loam verify --record --service` already draws exactly this\n      // line for exactly this reason (see commands/verify/verify.ts); vouch\n      // and gherkin now answer the same pair, so a caller branching on\n      // `error.code` gets one answer from all three. The messages are\n      // unchanged — only the code moved.\n      if (config.service === undefined) {\n        return fail(\n          json,\n          \"repository-unavailable\",\n          `Cannot vouch for '${service}' from here: this is not a service repo. \\`sources\\` resolve against the service's own repo — run it there.`,\n        );\n      }\n      if (config.service !== service) {\n        return fail(\n          json,\n          \"service-mismatch\",\n          `Cannot vouch for '${service}' from here: this repo is '${config.service}'. \\`sources\\` resolve against the service's own repo — run it there.`,\n        );\n      }\n\n      // The repo root, not the cwd — see the comment on `repoDir` below; the\n      // identity has to be asked of the same directory the sources resolve in,\n      // or a subdirectory with its own git config would answer for it.\n      const repoDir = config.root ?? process.cwd();\n\n      // The flag's own grammar, before anything is read or hashed: `--sample`\n      // decides what the run CLAIMS, so a value nobody can read must not reach\n      // a stamp. Whole numbers only, and at least one — `0` is a vouch that\n      // read nothing, and there is already a way to record that (do not\n      // vouch). Checked before `--pack` below so a typo is refused the same\n      // way in both modes.\n      let sampleSize: number | undefined;\n      if (opts.sample !== undefined) {\n        if (!/^\\d+$/.test(opts.sample.trim()) || Number(opts.sample) < 1) {\n          return fail(\n            json,\n            \"invalid-option\",\n            `--sample expects a positive whole number of sections; got '${opts.sample}'. ` +\n              \"Nothing was read and nothing was stamped.\",\n          );\n        }\n        sampleSize = Number(opts.sample);\n      }\n\n      // The reading pack: read-only, so it runs BEFORE — and instead of —\n      // every write-path gate below (identity, TTY, `--yes`, lock, journal),\n      // which all defend the stamp; pack/pack.ts's banner carries the full\n      // reasoning. It runs AFTER the wrong-repo gate above on purpose: the\n      // source delta resolves `sources` here. `--yes` does not compose — it\n      // is the unattended stamp, and a pack that stamped would defeat the\n      // read it just prescribed.\n      if (opts.pack === true) {\n        if (opts.yes === true) {\n          return fail(\n            json,\n            \"invalid-option\",\n            \"--pack is the reading list and --yes is the unattended stamp; a pack that immediately \" +\n              `stamped would defeat the read it just prescribed. Run --pack, read it, then \\`loam vouch --service ${service}\\`.`,\n          );\n        }\n        // `--sample` composes with the pack instead of conflicting with it:\n        // the pack is the reading list, and a sampled vouch's reading list is\n        // the sample. Passing it here makes the pack print the sections the\n        // subsequent `loam vouch --sample <n>` will stamp for — the same\n        // derivation from the same seed, so the two cannot prescribe\n        // different documents.\n        return runPack({ docsDir: config.docsDir, service: config.service, repoDir, json, sample: sampleSize });\n      }\n\n      // Who. Before any reading, because a run that cannot name a person has\n      // nothing to offer at the end of it and should not spend a digest finding\n      // that out.\n      const vouchedBy = await gitIdentity(repoDir);\n      if (vouchedBy === null) {\n        return fail(\n          json,\n          \"vouch-unattributable\",\n          `Cannot vouch for '${service}': git names no \\`user.email\\` in ${repoDir}, so the stamp would ` +\n            \"record a claim with nobody behind it — which is the one thing `status: verified` must not mean. \" +\n            \"Set it (`git config user.email you@example.com`) and re-run.\",\n        );\n      }\n\n      // Whether a person is actually here. `vouch` is the only command in loam\n      // whose output is a claim about a HUMAN act — every other check is\n      // internal consistency, which fluent prose satisfies — and it used to run\n      // unattended, unattributed, twice in a row, stamping `verified` both\n      // times. Meanwhile the generated skill files pre-approved `Bash(loam:*)`,\n      // so the same agent that wrote the draft was permitted to promote it.\n      // That inverts loam's own argument about test evidence: an agent must not\n      // be able to SAY a scenario is tested, and it must not be able to say a\n      // spec matches the code either. The allowlist no longer covers this\n      // command (core/agent/tools/dialects.ts), and nothing but a terminal or an explicit\n      // `--yes` gets past here.\n      const attended = opts.yes === true;\n      if (!attended) {\n        if (process.stdin.isTTY !== true) {\n          return fail(\n            json,\n            \"vouch-unattended\",\n            `Cannot vouch for '${service}' with nothing on the other end of stdin: this command records that ` +\n              \"a PERSON read the code and says the document matches it, and nobody was asked. Run it from a \" +\n              \"terminal, or pass --yes to state that you are standing behind it anyway — `vouched_by` records \" +\n              `${vouchedBy} either way.`,\n          );\n        }\n        // `--json` and a prompt do not compose: the envelope is one JSON\n        // document on stdout, and a question printed beside it is not parseable\n        // by the consumer that asked for it. A JSON caller is a program, so it\n        // gets the same answer a pipe does — say so with --yes.\n        if (json) {\n          return fail(\n            json,\n            \"vouch-unattended\",\n            `Cannot vouch for '${service}' in --json mode without --yes: the confirmation is a question for a ` +\n              \"person, and it cannot be asked on a stream whose whole contract is one JSON document.\",\n          );\n        }\n      }\n\n      // The reading list is built BEFORE the question and AFTER the attendance\n      // gates: a run that cannot ask anybody anything must not spend two\n      // source-tree digests finding that out, and a person must not be asked\n      // to confirm a sample nobody has shown them. Every refusal a vouch can\n      // raise about these documents fires in here, so it lands before the read\n      // rather than after it.\n      let sample: SamplePlan | undefined;\n      if (sampleSize !== undefined) {\n        const built = await buildSamplePlan({ docsDir: config.docsDir, service: config.service, repoDir, n: sampleSize });\n        if (!built.ok) return fail(json, built.code, built.message);\n        sample = built.plan;\n        if (!json) printReadingList(sample, service);\n      }\n      const servicePath = await serviceTreePathOf(config.docsDir, service);\n      if (!attended && !(await confirmVouch({ service, vouchedBy, docsDir: config.docsDir, servicePath, sample }))) {\n        return fail(json, \"vouch-declined\", `Nothing was stamped for '${service}'.`);\n      }\n\n      const outcome = await vouch({\n        docsDir: config.docsDir,\n        // The guard above proved `service` IS `config.service`, and only the\n        // latter carries the parse (`loam.json`'s `service` field is validated\n        // at load). Same string, but only one spelling is pathable.\n        service: config.service,\n        vouchedBy,\n        // The repo root, not the cwd. `sources:` are spelled relative to the\n        // repository — that is what they mean in the frontmatter and what\n        // `loam validate` resolves them against — so vouching from a\n        // subdirectory used to report every real source as missing\n        // (`sources-path-missing`) and refuse the stamp. `config.root` is the\n        // directory loam.json was found in, which is the only definition of\n        // \"this repo\" that does not move with the caller.\n        repoDir,\n        today: today(new Date()),\n        // Absent for an ordinary vouch, which is what makes an ordinary vouch\n        // CLEAR a prior sample's scope rather than leave it standing.\n        ...(sample === undefined ? {} : { sample }),\n      });\n      if (!outcome.ok) return fail(json, outcome.code, outcome.message);\n\n      const report = { service, docsDir: config.docsDir, outcome, ...(sample === undefined ? {} : { sample }) };\n      if (json) return emitStampJson(report);\n      printStamp(report);\n    });\n}\n"]}
+{"version":3,"file":"vouch.js","sourceRoot":"","sources":["../../../src/commands/vouch/vouch.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Command } from \"commander\";\nimport { configOrRefuse, fail, NO_SERVICE_MESSAGE } from \"../../core/envelope/json.js\";\nimport { gitIdentity } from \"../../core/provenance/git.js\";\nimport { today } from \"../../core/provenance/stamp.js\";\nimport { serviceTreePathOf } from \"../../core/repo/service-target.js\";\nimport { runPack } from \"./pack/print.js\";\nimport { confirmVouch } from \"./prompt/confirm.js\";\nimport { emitStampJson, printStamp } from \"./report.js\";\nimport { vouch } from \"./run.js\";\nimport { buildSamplePlan, type SamplePlan } from \"./sample/plan.js\";\nimport { printReadingList } from \"./sample/print.js\";\n\n/**\n * `loam vouch` — the human act SCHEMA.md has always described as \"promote draft\n * -> verified\".\n *\n * Everything else loam checks is internal consistency, and an agent writing\n * fluent prose satisfies all of it. This is the one command that records a\n * person: they read the code, they say the document matches it, and loam stamps\n * a digest of what they read — and a digest of the document they read it\n * against, so neither side can move quietly. From then on `loam validate` can\n * tell the difference between a document nobody has checked, one that still\n * matches the code, one the code has moved out from under, and one whose own\n * prose changed after the stamp.\n *\n * \"Records a person\" was, for two releases, a thing this file said and did not\n * do. There was no `vouched_by`, no identity of any kind and no interactive\n * gate, so an agent could run it twice unattended and stamp `verified` both\n * times — while the skill files loam generates pre-approved `Bash(loam:*)`,\n * which meant the agent that wrote the draft was permitted to promote it. Three\n * things close that, and none of them is a signature: the stamp carries git's\n * `user.email` (`vouched_by`), the run refuses without a terminal or an explicit\n * `--yes`, and the generated allowlist names loam's read-only and authoring\n * verbs one by one instead of all of them (core/agent/tools/dialects.ts). What that buys is\n * attribution and a deliberate act, not proof — git config is a text file. A\n * reviewer can now ask a named person what they read, which is the question\n * `status: verified` was silently answering with nobody.\n *\n * The stamp is only worth what it claims, so vouch refuses everything it cannot\n * actually verify — a frontmatter block that will not parse (whose fields\n * nobody can read, and whose rewrite would lose the author's lines), a spec\n * with no sources, a glob pattern (no longer supported), a source that is\n * gone, a directory holding no files, or a repo that is not this service's —\n * and refuses without writing anything.\n *\n * \"The document\" is every spec-axis file the service has: spec.md always, and\n * arch.spec.md beside it when present — same frontmatter conventions, same\n * stamp, one vouch. The refusal discipline is per file but the vouch is\n * all-or-nothing per service: one unverifiable file refuses the whole run, so\n * a `verified` service never means \"half-stamped\".\n */\n\ninterface VouchOptions {\n  service?: string;\n  yes?: boolean;\n  pack?: boolean;\n  /** `--sample <n>` as typed — a string until it is proved to be a whole number. */\n  sample?: string;\n  json?: boolean;\n}\n\nexport function registerVouch(program: Command): void {\n  program\n    .command(\"vouch\")\n    .description(\n      \"Vouch for a service's living specs: stamp spec.md, and arch.spec.md when present, verified against the code they describe\",\n    )\n    .option(\"--service <id>\", \"service to vouch for (defaults to the configured service)\")\n    .option(\n      \"--yes\",\n      \"skip the confirmation — required when stdin is not a terminal, and still records `vouched_by`\",\n    )\n    .option(\n      \"--pack\",\n      \"print the re-vouch reading pack — the doc-body diff since the last vouch, the source files that moved, and the sections already covered — then exit without vouching; read-only, nothing is stamped\",\n    )\n    .option(\n      \"--sample <n>\",\n      \"vouch after reading a deterministic sample of <n> sections per spec file — the stamp records `vouch_scope: sampled`, `loam list` shows `vouched (sampled)`, and `loam validate` reports `sources.sampled-vouch` until a full vouch clears it\",\n    )\n    .option(\"--json\", \"emit the machine contract instead of the human view\")\n    .action(async (opts: VouchOptions) => {\n      const json = opts.json === true;\n\n      const config = await configOrRefuse(json);\n      if (config === null) return;\n\n      const service = opts.service ?? config.service;\n      if (service === undefined) {\n        return fail(json, \"invalid-option\", NO_SERVICE_MESSAGE);\n      }\n      // Vouching hashes the code the doc was written from, so it can only run\n      // where that code is. From anywhere else the paths are someone else's.\n      //\n      // TWO conditions, two codes, and the split is the whole point. Both used\n      // to answer `invalid-option`, whose `loam explain` row says the\n      // invocation itself is wrong — contradictory flags, a mistyped one, a\n      // value that cannot be right. Here the invocation is perfectly correct\n      // and the REPOSITORY is the wrong one, so that code sent a user whose\n      // flags were fine off to re-read their flags, and left CI and agents\n      // unable to tell \"run this in the service repo\" from \"you typed the flag\n      // wrong\". `loam verify --record --service` already draws exactly this\n      // line for exactly this reason (see commands/verify/verify.ts); vouch\n      // and gherkin now answer the same pair, so a caller branching on\n      // `error.code` gets one answer from all three. The messages are\n      // unchanged — only the code moved.\n      if (config.service === undefined) {\n        return fail(\n          json,\n          \"repository-unavailable\",\n          `Cannot vouch for '${service}' from here: this is not a service repo. \\`sources\\` resolve against the service's own repo — run it there.`,\n        );\n      }\n      if (config.service !== service) {\n        return fail(\n          json,\n          \"service-mismatch\",\n          `Cannot vouch for '${service}' from here: this repo is '${config.service}'. \\`sources\\` resolve against the service's own repo — run it there.`,\n        );\n      }\n\n      // The repo root, not the cwd — see the comment on `repoDir` below; the\n      // identity has to be asked of the same directory the sources resolve in,\n      // or a subdirectory with its own git config would answer for it.\n      const repoDir = config.root ?? process.cwd();\n\n      // The flag's own grammar, before anything is read or hashed: `--sample`\n      // decides what the run CLAIMS, so a value nobody can read must not reach\n      // a stamp. Whole numbers only, and at least one — `0` is a vouch that\n      // read nothing, and there is already a way to record that (do not\n      // vouch). Checked before `--pack` below so a typo is refused the same\n      // way in both modes.\n      let sampleSize: number | undefined;\n      if (opts.sample !== undefined) {\n        if (!/^\\d+$/.test(opts.sample.trim()) || Number(opts.sample) < 1) {\n          return fail(\n            json,\n            \"invalid-option\",\n            `--sample expects a positive whole number of sections; got '${opts.sample}'. ` +\n              \"Nothing was read and nothing was stamped.\",\n          );\n        }\n        sampleSize = Number(opts.sample);\n      }\n\n      // The reading pack: read-only, so it runs BEFORE — and instead of —\n      // every write-path gate below (identity, TTY, `--yes`, lock, journal),\n      // which all defend the stamp; pack/pack.ts's banner carries the full\n      // reasoning. It runs AFTER the wrong-repo gate above on purpose: the\n      // source delta resolves `sources` here. `--yes` does not compose — it\n      // is the unattended stamp, and a pack that stamped would defeat the\n      // read it just prescribed.\n      if (opts.pack === true) {\n        if (opts.yes === true) {\n          return fail(\n            json,\n            \"invalid-option\",\n            \"--pack is the reading list and --yes is the unattended stamp; a pack that immediately \" +\n              `stamped would defeat the read it just prescribed. Run --pack, read it, then \\`loam vouch --service ${service}\\`.`,\n          );\n        }\n        // `--sample` composes with the pack instead of conflicting with it:\n        // the pack is the reading list, and a sampled vouch's reading list is\n        // the sample. Passing it here makes the pack print the sections the\n        // subsequent `loam vouch --sample <n>` will stamp for — the same\n        // derivation from the same seed, so the two cannot prescribe\n        // different documents.\n        return runPack({ docsDir: config.docsDir, service: config.service, repoDir, json, sample: sampleSize });\n      }\n\n      // Who. Before any reading, because a run that cannot name a person has\n      // nothing to offer at the end of it and should not spend a digest finding\n      // that out.\n      const vouchedBy = await gitIdentity(repoDir);\n      if (vouchedBy === null) {\n        return fail(\n          json,\n          \"vouch-unattributable\",\n          `Cannot vouch for '${service}': git names no \\`user.email\\` in ${repoDir}, so the stamp would ` +\n            \"record a claim with nobody behind it — which is the one thing `status: verified` must not mean. \" +\n            \"Set it (`git config user.email you@example.com`) and re-run.\",\n        );\n      }\n\n      // Whether a person is actually here — the gate the banner's \"records a\n      // person\" paragraph tells the history of. `vouch` is the only command in\n      // loam whose output is a claim about a HUMAN act — every other check is\n      // internal consistency, which fluent prose satisfies — and why an agent\n      // must not be able to make that claim for itself is recorded on the\n      // allowlist that no longer covers this command\n      // (core/agent/tools/dialects.ts). Nothing but a terminal or an explicit\n      // `--yes` gets past here.\n      const attended = opts.yes === true;\n      if (!attended) {\n        if (process.stdin.isTTY !== true) {\n          return fail(\n            json,\n            \"vouch-unattended\",\n            `Cannot vouch for '${service}' with nothing on the other end of stdin: this command records that ` +\n              \"a PERSON read the code and says the document matches it, and nobody was asked. Run it from a \" +\n              \"terminal, or pass --yes to state that you are standing behind it anyway — `vouched_by` records \" +\n              `${vouchedBy} either way.`,\n          );\n        }\n        // `--json` and a prompt do not compose: the envelope is one JSON\n        // document on stdout, and a question printed beside it is not parseable\n        // by the consumer that asked for it. A JSON caller is a program, so it\n        // gets the same answer a pipe does — say so with --yes.\n        if (json) {\n          return fail(\n            json,\n            \"vouch-unattended\",\n            `Cannot vouch for '${service}' in --json mode without --yes: the confirmation is a question for a ` +\n              \"person, and it cannot be asked on a stream whose whole contract is one JSON document.\",\n          );\n        }\n      }\n\n      // The reading list is built BEFORE the question and AFTER the attendance\n      // gates: a run that cannot ask anybody anything must not spend two\n      // source-tree digests finding that out, and a person must not be asked\n      // to confirm a sample nobody has shown them. Every refusal a vouch can\n      // raise about these documents fires in here, so it lands before the read\n      // rather than after it.\n      let sample: SamplePlan | undefined;\n      if (sampleSize !== undefined) {\n        const built = await buildSamplePlan({ docsDir: config.docsDir, service: config.service, repoDir, n: sampleSize });\n        if (!built.ok) return fail(json, built.code, built.message);\n        sample = built.plan;\n        if (!json) printReadingList(sample, service);\n      }\n      const servicePath = await serviceTreePathOf(config.docsDir, service);\n      if (!attended && !(await confirmVouch({ service, vouchedBy, docsDir: config.docsDir, servicePath, sample }))) {\n        return fail(json, \"vouch-declined\", `Nothing was stamped for '${service}'.`);\n      }\n\n      const outcome = await vouch({\n        docsDir: config.docsDir,\n        // The guard above proved `service` IS `config.service`, and only the\n        // latter carries the parse (`loam.json`'s `service` field is validated\n        // at load). Same string, but only one spelling is pathable.\n        service: config.service,\n        vouchedBy,\n        // The repo root, not the cwd. `sources:` are spelled relative to the\n        // repository — that is what they mean in the frontmatter and what\n        // `loam validate` resolves them against — so vouching from a\n        // subdirectory used to report every real source as missing\n        // (`sources-path-missing`) and refuse the stamp. `config.root` is the\n        // directory loam.json was found in, which is the only definition of\n        // \"this repo\" that does not move with the caller.\n        repoDir,\n        today: today(new Date()),\n        // Absent for an ordinary vouch, which is what makes an ordinary vouch\n        // CLEAR a prior sample's scope rather than leave it standing.\n        ...(sample === undefined ? {} : { sample }),\n      });\n      if (!outcome.ok) return fail(json, outcome.code, outcome.message);\n\n      const report = { service, docsDir: config.docsDir, outcome, ...(sample === undefined ? {} : { sample }) };\n      if (json) return emitStampJson(report);\n      printStamp(report);\n    });\n}\n"]}

package/dist/core/agent/agents-md/command-map.js

@@ -1,14 +1,20 @@
 /**
- * Reading loam's output, in its two deliveries.
+ * Reading loam's output: which codes each invocation can raise.
  *
- * {@link READING_OUTPUT} and {@link REFERENCE_PAGES} are what AGENTS.md keeps:
- * the `--json` envelope, the rule to branch on codes rather than prose, and the
- * index of the pages this file no longer carries. {@link CODE_MAP} is the
- * code-by-code map of `status`, `validate`, `doctor`, `rebase`, `dependencies`,
- * `explore`, `seed` and `instructions` — the part `loam instructions loam-codes`
- * prints. ../workflows/reference/codes.ts composes it with `./map/`,
- * `./map/lenses/` and `./refusals.ts`, in exactly the order ../agents-md.ts used
- * to concatenate them, so the assembled page is the section byte for byte.
+ * {@link CODE_MAP} is the code-by-code map of `status`, `validate`, `doctor`,
+ * `rebase`, `dependencies`, `explore`, `seed` and `instructions` — the part
+ * `loam instructions loam-codes` prints. ../workflows/reference/codes.ts
+ * composes it with `./map/`, `./map/lenses/` and `./refusals.ts`, in exactly the
+ * order ../agents-md.ts used to concatenate them, so the assembled page is the
+ * section byte for byte.
+ *
+ * This module used to hold the other delivery too: `READING_OUTPUT` and
+ * `REFERENCE_PAGES`, the two AGENTS.md sections that stayed behind when the map
+ * left. Since 0.2.0-alpha.1 AGENTS.md is the single ORIENTATION literal in
+ * ../agents-md.ts, which carries its own condensed "Reading loam's output" and
+ * "Reference pages" sections, and nothing assembled the two old constants into
+ * anything loam shipped. They were deleted rather than left to be edited as if a
+ * reader would ever see them.
  *
  * WHY THE MAP LEFT THE FILE, given that this package's whole subject is a file.
  * AGENTS.md is auto-loaded from the working directory by every agents.md-aware
@@ -49,84 +55,13 @@
  * document does not survive being moved to another one; that is the class to
  * check for whenever anything else leaves this file.
  *
- * READING_OUTPUT and REFERENCE_PAGES are sections of the AGENTS.md template.
- * ../agents-md.ts assembles the document by PLAIN CONCATENATION — no join
- * separator — so every section starts at the first character of its opening line
- * and ends with the newline that closes its last one. Keep that shape when
- * editing, or two sections glue onto one line in every docs repo loam scaffolds
- * from now on. CODE_MAP owes the same shape for the same reason, one level up:
- * reference/codes.ts concatenates it with the modules listed above.
+ * CODE_MAP is one part of the `loam-codes` page, which
+ * ../workflows/reference/codes.ts assembles by PLAIN CONCATENATION — no join
+ * separator — so it starts at the first character of its opening line and ends
+ * with the newline that closes its last one. Keep that shape when editing, or
+ * two parts glue onto one line on the printed page.
  */
 import { STATUS_COMMAND } from "./map/status.js";
-/**
- * The section AGENTS.md keeps. Three facts an agent needs BEFORE it can form a
- * question — that every command speaks JSON, that the envelope survives a bad
- * invocation, and that codes are the contract and prose is not — plus the two
- * places the detail went.
- */
-export const READING_OUTPUT = `## Reading loam's output
-
-Every command takes \`--json\`, and the envelope holds even when the INVOCATION
-is wrong: with \`--json\` anywhere in the arguments, an unknown flag, unknown
-command or missing argument still yields \`{ ok: false, error: { code:
-"invalid-option" } }\` on stdout with exit 1 (commander's own diagnostic goes
-to stderr; \`--help\` and \`--version\` output pass through untouched). Without
-\`--json\` the same refusal is plain text on stderr with nothing on stdout.
-
-Branch on \`findings[].code\`, never on the prose — the wording changes, the codes do
-not.
-
-**What a code MEANS is one command away**, and the answer describes the loam you
-are running rather than the one that scaffolded this repo. \`loam explain <code>\`
-gives one code's meaning, its severity in each scope that grades it, and its fix;
-\`loam explain --codes\` lists the whole vocabulary and \`loam explain --codes --json\`
-is the machine-readable form. Reach for it rather than for a generated pointer:
-this page is printed by the binary that defines the codes.
-
-**Which codes an INVOCATION can raise** is the other half, and it is the one
-thing nothing else carries. It is a reference page rather than a section here:
-\`loam instructions loam-codes\`.
-
-`;
-/**
- * The index. A reference nobody can find is content deleted with extra steps,
- * so the exact command is spelled per page rather than described — and
- * test/agents.test.ts asserts that every name in REFERENCES appears here inside
- * its own `loam instructions` line, which is what makes a renamed page fail
- * loudly instead of leaving a pointer at nothing.
- */
-export const REFERENCE_PAGES = `## The reference pages
-
-This file is the orientation: the layout, the cycle, what gates and what only
-advises, and what the words mean. Four things it does NOT carry — the grammars
-you consult while writing ONE document, and the inventory of what each command
-can report — are **reference pages**, printed by the binary rather than written
-here. That is why: this file is auto-loaded on every session and never
-refreshed, while a page out of the binary describes the loam you are actually
-running, and is read at the one moment it is needed.
-
-- \`loam instructions loam-codes\` — which codes each invocation can raise:
-  \`validate --service\` / \`--feature\` / \`--all\`, \`status\`, \`doctor\`, \`gate\`,
-  \`context\`, \`diff\`, \`explore\`, \`dependencies\`, \`rebase\`, \`seed\`, \`subsystem\`,
-  \`mcp\`, the use-case views, the containment refusals, the error envelope, and
-  the OpenSpec migration surface.
-- \`loam instructions loam-spine\` — the ID spine: every join between the
-  artifacts (\`operationId\`, message name, \`Covers:\`, \`Requires:\`,
-  \`Capability:\`, \`Realizes:\`), the \`Based-On:\` baseline pins on both the
-  requirement and the contract axis, how to draw a shared broker, and how to
-  declare a message produced outside the fleet.
-- \`loam instructions loam-authoring\` — the grammars you author against:
-  the architecture spec axis (\`arch.spec.md\` and its \`Covers:\` line), the
-  generated Gherkin suite, and frontmatter with the vouch chain behind it.
-- \`loam instructions loam-done-check\` — the done-check: how \`loam verify\`
-  derives its claims, the three channels that may answer them, the federated
-  recording form, and what separates **verified** from **attested**.
-
-Each takes no arguments and prints whole. \`loam instructions\` with no argument
-lists them beside the six workflow protocols; \`loam explain <code>\` answers any
-single code without opening a page at all.
-
-`;
 /**
  * The reference page's own opening: what the map is, where the /loam-check fix
  * tables sit beside it, and the one family `loam explain` cannot answer.
@@ -163,6 +98,7 @@ The map:
 `;
 const MAP_REST = `- \`loam validate --service <id>\` grades one service's own axes: \`service.unknown\`,
   \`service.no-model\`, \`service.no-spec\`, \`service.no-openapi\`, \`c4.invalid\`,
+  \`c4.declaration-diverged\`, \`c4.element-unowned\`,
   \`c4.no-relationships\`, \`requirements.missing-scenarios\`,
   \`requirements.stepless-scenario\`, \`requirements.assertionless-scenario\`,
   \`requirements.examples-unbound\`, \`requirements.examples-unreferenced\`,
@@ -176,7 +112,7 @@ const MAP_REST = `- \`loam validate --service <id>\` grades one service's own ax
   \`service.no-asyncapi\`, \`asyncapi.invalid\`, \`asyncapi.duplicate-message\`,
   \`asyncapi.payload-undescribed\`, \`asyncapi.ref-unresolved\`,
   \`spine.message-undefined\`, \`spec-event.message-undefined\`,
-  \`spine.message-unproduced\`, \`spine.message-external\`,
+  \`spine.message-unproduced\`, \`spine.message-external\`, \`spine.message-unbound\`,
   \`asyncapi.message-contested\`, \`event.messages-unlinked\`, \`event.ungoverned\`,
   \`event.covered\`; and the architecture spec axis: \`covers.unknown\`,
   \`health.invalid\`, \`health.uncovered\`, \`health.dependency-unmodelled\`.
@@ -196,7 +132,9 @@ const MAP_REST = `- \`loam validate --service <id>\` grades one service's own ax
   codes service scope raises, graded here on the feature's own spec.md and
   arch.spec.md deltas, because every one of those breaches merges into the
   living document — \`spec.repeated-operations\`, \`spec.repeated-covers\`,
-  \`spec.merge-conflict\` and \`requirements.stepless-scenario\`. Then the
+  \`spec.merge-conflict\` and \`requirements.stepless-scenario\`. A feature
+  whose verification record will not read as one raises
+  \`evidence.record-unreadable\` (warn) here as well. Then the
   architecture spec axis (\`c4.uncovered\`, plus \`covers.unknown\` on the
   feature's arch.spec.md deltas), the delta-shape group:
   \`delta.unknown-section\`, \`delta.no-delta-sections\`,
@@ -204,9 +142,14 @@ const MAP_REST = `- \`loam validate --service <id>\` grades one service's own ax
   \`delta.added-duplicate\`, \`delta.added-near-duplicate\`, \`delta.modified-pending\`,
   \`delta.removed-pending\`, \`delta.added-conflict\`, \`delta.modified-conflict\`,
   \`delta.living-duplicate-requirement\`, and the API-removal group:
-  \`openapi.remove-marker-anonymous\`, \`openapi.remove-op-consumed\`.
+  \`openapi.remove-marker-anonymous\`, \`openapi.remove-op-consumed\`, and
+  \`openapi.op-revived\` (warn, gates archive: the delta spells an operation an
+  archived feature retired, or at an address one retired or moved it away
+  from while it lives on elsewhere, so the merge would put it back).
   The event axis is graded in feature scope too — the \`asyncapi.*\`
-  baseline/removal/conflict codes plus \`c4-event.*\` and \`spec-event.*\`.
+  baseline/removal/conflict codes, \`asyncapi.slot-revived\` (the same revival
+  on a channel, operation or message), plus \`c4-event.*\`, \`spec-event.*\` and
+  \`spine.message-unbound\` (a tagged edge's event key bound to a topic or other infrastructure).
   Where a finding names another feature in flight (\`delta.*-pending\`,
   \`delta.added-conflict\`, \`delta.modified-conflict\`, \`spec-api.op-pending\`,
   \`c4-api.op-pending\`) the ORDER is the answer, and \`loam dependencies --json\`
@@ -217,10 +160,24 @@ const MAP_REST = `- \`loam validate --service <id>\` grades one service's own ax
   \`landscape.merge-conflict\`, \`landscape.service-unmodelled\`,
   \`landscape.service-undocumented\`, \`landscape.binding-unknown\`,
   \`landscape.binding-duplicate\`, the fleet-shape advisories
-  \`landscape.platform-candidate\`, \`landscape.datastore-private\` and
+  \`landscape.platform-candidate\` and
   \`landscape.datastore-shared\`, \`service.id-invalid\` (fleet scope only, and
   graded before the map is opened, so it stands even when the landscape is
-  missing or unreadable), a per-service \`sources.unverifiable-from-here\`, and
+  missing or unreadable), the four renderer-wiring warnings a
+  \`loam subsystem sync\` repairs — \`service.likec4-config-missing\` (a model that
+  STANDS ALONE, declaring its own \`specification\`, with no
+  \`likec4.config.json\` beside it: it renders nowhere from the docs root),
+  \`service.likec4-config-stray\` (that file beside a model that EXTENDS the map,
+  where it registers a project that CLAIMS the model, out of the root project
+  where the map's kinds are),
+  \`service.model-excluded\` (the root \`likec4.config.json\` excludes an extending
+  model's directory, so the renderer never loads it) and
+  \`service.model-unexcluded\` (it does NOT exclude a standalone model's, so the
+  renderer merges that model into the map and calls every declaration a
+  duplicate) — plus \`c4.fleet-project-invalid\` (warn: every document reads clean
+  where loam grades it and the ONE project the renderer builds out of the map and
+  every extending model does not, because something is declared in two of them),
+  a per-service \`sources.unverifiable-from-here\`, and
   one check on the docs repo's own AGENTS.md, \`agents.stale\`. That last one is
   the reason to distrust THAT file rather than this page: it fires when its
   version stamp on line 1 (\`<!-- generated by loam vX.Y.Z -->\`) is missing or
@@ -255,15 +212,21 @@ const MAP_REST = `- \`loam validate --service <id>\` grades one service's own ax
   \`doctor.inventory-unreadable\`, \`doctor.landscape-missing\`,
   \`doctor.service-unbound\` (never raised inside the docs repo itself, where
   having no service binding is the correct state), \`doctor.service-unknown\`
-  (the same state \`loam status\` reports as \`next.adopt-bound\`),
+  (the same state \`loam status\` reports as \`next.adopt-bound\` — or, when an
+  active feature introduces the service, as that feature's \`next.feature\`, and
+  then the finding names the feature and \`currentService.introducedBy\` lists
+  it: there is nothing to adopt),
   \`doctor.likec4-config-missing\`, and the two about this repo's own generated
   command and skill files: \`doctor.agent-files-missing\` and
   \`doctor.agent-files-stale\`.
-  EXPECT the second one on the first \`loam doctor\` after an upgrade. It is not
-  evidence that anything was edited or broken: staleness reads the version
-  stamp only. Re-running \`loam init\` refreshes an unchanged pointer only when
-  its current bytes still match the digest recorded in \`loam.json\`; an
-  unrecorded or customized file stays in place for a human to review.
+  The second one fires only for a file whose body differs from the one this
+  loam writes AND whose stamp is missing or older — so after an upgrade, expect
+  it when the release changed the pointer text, never for a stamp-only
+  difference, and never for an edited body under a current stamp (that stamp is
+  the record that somebody reviewed it). Re-running \`loam init\` refreshes an
+  unchanged pointer only when its current bytes still match the digest
+  recorded in \`loam.json\`; an unrecorded or customized file stays in place
+  for a human to review.
 - \`loam rebase <FEAT>\` writes the baseline pins: \`Based-On:\` under every
   MODIFIED/REMOVED requirement in the feature's spec deltas, and
   \`x-loam-based-on\` on every operation in its openapi.yaml, from the living text
@@ -271,7 +234,14 @@ const MAP_REST = `- \`loam validate --service <id>\` grades one service's own ax
   after you resolve a collision — it is the one mechanism standing between two
   features in flight and silently reverting each other's landed work. It refuses
   rather than inventing a pin, and re-pinning is not resolving: see
-  "The requirement baseline".
+  "The requirement baseline". An operation or event slot the delta spells that
+  an ARCHIVED feature retired is not pinned as new: rebase prints the
+  \`openapi.op-revived\` / \`asyncapi.slot-revived\` finding (and \`revived[]\` in
+  \`--json\`) and leaves the call — delete the quote, or re-add on purpose — to
+  you. It judges the delta as it will write it, pins included, so a quote its
+  own repin turns into an edit — repinned over whatever lives now at an
+  address an archived feature moved the entry away from — is in that list too,
+  under \`--dry-run\` as well.
 - \`loam dependencies [<FEAT>]\` derives the ordering of the features in flight
   from the artifacts themselves — requirement identities and OpenAPI
   operationIds, never from validator prose. It is the answer to every
@@ -300,17 +270,22 @@ const MAP_REST = `- \`loam validate --service <id>\` grades one service's own ax
   "who calls whom" is the one thing no generator can read off a repository.
   The seeded landscape carries a line-1 stamp; while it stands unedited,
   editing fleet.yaml and re-running regenerates the map, and the first hand
-  edit makes the file yours — seed then refuses \`seed-landscape-edited\`
-  rather than overwrite. Then adopt each service: \`loam adopt --service <id>\`.
+  edit anywhere in the file, including above the stub, makes it yours — seed
+  then refuses \`seed-landscape-edited\`
+  rather than overwrite. So seed is a day-zero step: fleet.yaml has no spelling
+  for \`metadata { op }\`, and once an edge carries one the map grows through
+  adopt briefs and feature C4 deltas, not through seed. Then adopt each
+  service: \`loam adopt --service <id>\`.
 - \`loam instructions [<page>] [args...]\` prints one of the six workflow
   protocols — \`loam-adopt\`, \`loam-feature\`, \`loam-implement\`, \`loam-check\`,
   \`loam-verify\`, \`loam-ship\` — with \`$1\`, \`$2\` filled in from the arguments you
-  pass, or one of the four reference pages — \`loam-codes\`, \`loam-spine\`,
-  \`loam-authoring\`, \`loam-done-check\` — which take no arguments. With no
-  argument at all it lists both sets. The pages ship inside the binary, so they
-  describe the loam you are about to run rather than the one that scaffolded the
-  repository; the command and skill files \`loam init\` writes are pointers at it,
-  and so is AGENTS.md's own "The reference pages" section. It reads no
+  pass, the \`loam-report\` support protocol, or one of the five reference pages —
+  \`loam-codes\`, \`loam-spine\`, \`loam-authoring\`, \`loam-done-check\`,
+  \`loam-drawing\` — which take no arguments. With no argument at all it lists all three sets. The pages ship
+  inside the binary, so they describe the loam you are about to run rather than
+  the one that scaffolded the repository; the command and skill files
+  \`loam init\` writes are pointers at it, and so is AGENTS.md's own
+  "Reference pages — fetch when needed" section. It reads no
   \`loam.json\` and no docs repo, deliberately: \`loam-adopt\`'s own first step is
   to run \`loam init\` when there is no config, so it cannot be the step that
   requires one.

package/dist/core/agent/agents-md/command-map.js.map

@@ -1 +1 @@
-{"version":3,"file":"command-map.js","sourceRoot":"","sources":["../../../../src/core/agent/agents-md/command-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;CAuB7B,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+B9B,CAAC;AAEF;;;GAGG;AACH,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BjB,CAAC;AAEF,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyJhB,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,SAAS,GAAG,cAAc,GAAG,QAAQ,CAAC","sourcesContent":["/**\n * Reading loam's output, in its two deliveries.\n *\n * {@link READING_OUTPUT} and {@link REFERENCE_PAGES} are what AGENTS.md keeps:\n * the `--json` envelope, the rule to branch on codes rather than prose, and the\n * index of the pages this file no longer carries. {@link CODE_MAP} is the\n * code-by-code map of `status`, `validate`, `doctor`, `rebase`, `dependencies`,\n * `explore`, `seed` and `instructions` — the part `loam instructions loam-codes`\n * prints. ../workflows/reference/codes.ts composes it with `./map/`,\n * `./map/lenses/` and `./refusals.ts`, in exactly the order ../agents-md.ts used\n * to concatenate them, so the assembled page is the section byte for byte.\n *\n * WHY THE MAP LEFT THE FILE, given that this package's whole subject is a file.\n * AGENTS.md is auto-loaded from the working directory by every agents.md-aware\n * host, on every session, and `loam init` writes it once and never refreshes it.\n * It reached 109,399 bytes; Codex truncates the AGENTS.md chain at 32,768 bytes\n * and Windsurf caps a workspace rule file at 12,000 characters, both silently.\n * Roughly seventy percent of the document was being dropped with no error and no\n * way for the reader to tell which half it held — and this section alone was\n * 44,433 of those bytes, 41% of the file. It is also the half a reader consults\n * at a moment it can name (a run reported something) rather than the half it\n * needs to form a question at all, which is what decided which side of the split\n * it went. ../workflows/reference/reference.ts carries the rest of that argument.\n *\n * The move is a move and not a deletion: every byte is still shipped, still in\n * the same corpus test/codes-drift.test.ts reads (AGENTS_MD + PROTOCOLS), and\n * still one command away rather than one file away.\n *\n * WHAT THE MAP IS, AND WHAT IT DELIBERATELY IS NOT. The unique content is which\n * codes which INVOCATION can raise: nothing else in the corpus says that, and an\n * agent choosing what to run needs it. What it does not carry is a per-code\n * gloss of what each code MEANS. That half used to be written twice — once here,\n * once in the /loam-check fix tables — in two independently worded places, in a\n * file `loam init` writes once and never refreshes, so the two drifted with\n * nothing able to say which had rotted. `loam explain <code>` now answers\n * meaning, severity and fix for every code named below, out of the running\n * binary. test/agent-contract.test.ts holds that pointer honest: every code\n * backticked in the corpus must resolve through `explainSubject`, so a family\n * added here without an explanation fails by name. Keep the code list; add the\n * gloss only where it says something `explain` cannot — a condition on when the\n * invocation raises it at all, or a cross-reference between two codes.\n *\n * ONE PARAGRAPH THE MOVE MADE FALSE, and the reason to look for others like it.\n * The `agents.stale` entry read \"one check on this very file … the reason to\n * distrust what you are reading\", which was true while these bytes WERE the\n * scaffolded AGENTS.md. On a page printed by the binary it is exactly backwards\n * — this page cannot be stale, and the file it warns about is somewhere else —\n * so the entry names AGENTS.md instead. A section that talks about its own\n * document does not survive being moved to another one; that is the class to\n * check for whenever anything else leaves this file.\n *\n * READING_OUTPUT and REFERENCE_PAGES are sections of the AGENTS.md template.\n * ../agents-md.ts assembles the document by PLAIN CONCATENATION — no join\n * separator — so every section starts at the first character of its opening line\n * and ends with the newline that closes its last one. Keep that shape when\n * editing, or two sections glue onto one line in every docs repo loam scaffolds\n * from now on. CODE_MAP owes the same shape for the same reason, one level up:\n * reference/codes.ts concatenates it with the modules listed above.\n */\nimport { STATUS_COMMAND } from \"./map/status.js\";\n\n/**\n * The section AGENTS.md keeps. Three facts an agent needs BEFORE it can form a\n * question — that every command speaks JSON, that the envelope survives a bad\n * invocation, and that codes are the contract and prose is not — plus the two\n * places the detail went.\n */\nexport const READING_OUTPUT = `## Reading loam's output\n\nEvery command takes \\`--json\\`, and the envelope holds even when the INVOCATION\nis wrong: with \\`--json\\` anywhere in the arguments, an unknown flag, unknown\ncommand or missing argument still yields \\`{ ok: false, error: { code:\n\"invalid-option\" } }\\` on stdout with exit 1 (commander's own diagnostic goes\nto stderr; \\`--help\\` and \\`--version\\` output pass through untouched). Without\n\\`--json\\` the same refusal is plain text on stderr with nothing on stdout.\n\nBranch on \\`findings[].code\\`, never on the prose — the wording changes, the codes do\nnot.\n\n**What a code MEANS is one command away**, and the answer describes the loam you\nare running rather than the one that scaffolded this repo. \\`loam explain <code>\\`\ngives one code's meaning, its severity in each scope that grades it, and its fix;\n\\`loam explain --codes\\` lists the whole vocabulary and \\`loam explain --codes --json\\`\nis the machine-readable form. Reach for it rather than for a generated pointer:\nthis page is printed by the binary that defines the codes.\n\n**Which codes an INVOCATION can raise** is the other half, and it is the one\nthing nothing else carries. It is a reference page rather than a section here:\n\\`loam instructions loam-codes\\`.\n\n`;\n\n/**\n * The index. A reference nobody can find is content deleted with extra steps,\n * so the exact command is spelled per page rather than described — and\n * test/agents.test.ts asserts that every name in REFERENCES appears here inside\n * its own `loam instructions` line, which is what makes a renamed page fail\n * loudly instead of leaving a pointer at nothing.\n */\nexport const REFERENCE_PAGES = `## The reference pages\n\nThis file is the orientation: the layout, the cycle, what gates and what only\nadvises, and what the words mean. Four things it does NOT carry — the grammars\nyou consult while writing ONE document, and the inventory of what each command\ncan report — are **reference pages**, printed by the binary rather than written\nhere. That is why: this file is auto-loaded on every session and never\nrefreshed, while a page out of the binary describes the loam you are actually\nrunning, and is read at the one moment it is needed.\n\n- \\`loam instructions loam-codes\\` — which codes each invocation can raise:\n  \\`validate --service\\` / \\`--feature\\` / \\`--all\\`, \\`status\\`, \\`doctor\\`, \\`gate\\`,\n  \\`context\\`, \\`diff\\`, \\`explore\\`, \\`dependencies\\`, \\`rebase\\`, \\`seed\\`, \\`subsystem\\`,\n  \\`mcp\\`, the use-case views, the containment refusals, the error envelope, and\n  the OpenSpec migration surface.\n- \\`loam instructions loam-spine\\` — the ID spine: every join between the\n  artifacts (\\`operationId\\`, message name, \\`Covers:\\`, \\`Requires:\\`,\n  \\`Capability:\\`, \\`Realizes:\\`), the \\`Based-On:\\` baseline pins on both the\n  requirement and the contract axis, how to draw a shared broker, and how to\n  declare a message produced outside the fleet.\n- \\`loam instructions loam-authoring\\` — the grammars you author against:\n  the architecture spec axis (\\`arch.spec.md\\` and its \\`Covers:\\` line), the\n  generated Gherkin suite, and frontmatter with the vouch chain behind it.\n- \\`loam instructions loam-done-check\\` — the done-check: how \\`loam verify\\`\n  derives its claims, the three channels that may answer them, the federated\n  recording form, and what separates **verified** from **attested**.\n\nEach takes no arguments and prints whole. \\`loam instructions\\` with no argument\nlists them beside the six workflow protocols; \\`loam explain <code>\\` answers any\nsingle code without opening a page at all.\n\n`;\n\n/**\n * The reference page's own opening: what the map is, where the /loam-check fix\n * tables sit beside it, and the one family `loam explain` cannot answer.\n */\nconst MAP_INTRO = `**What this page is.** It says which codes an INVOCATION can raise. It does\nNOT say what they mean: that half is one command away and describes the loam you\nare running rather than the one that scaffolded this repo. \\`loam explain <code>\\`\ngives one code's meaning, its severity in each scope that grades it, and its fix;\n\\`loam explain --codes\\` lists the whole vocabulary and \\`loam explain --codes --json\\`\nis the machine-readable form. The one family \\`explain\\` does not answer\nis the OpenSpec migration surface (\\`openspec.*\\`, \\`mapping.*\\`) — those commands run\nbefore a repository has a governed loop to look a code up from — so those entries\nalone keep their notes here.\n\nThe code-by-code fix table is a different document again: it lives in the\n\\`/loam-check\\` command \\`loam init\\` lays\ndown. \\`init\\` writes that body twice for every tool it configures: once as a slash\ncommand in the tool's own command directory (you type it), and once as an Agent\nSkill at \\`<tool-dir>/skills/loam-check/SKILL.md\\` (the model loads it by itself when\nthe task matches the skill's description). Same body, two ways in.\n\nWhich tools get them is detected from the repo: \\`loam init\\` scans for the\ndot-directories of the tools it knows (\\`.claude\\`, \\`.cursor\\`, \\`.gemini\\`, …) and\nwrites for the ones it finds, falling back to Claude Code when it finds none.\n\\`loam init --tools <ids|all>\\` overrides the scan — an unknown id is refused\n(\\`invalid-option\\`) rather than skipped — and \\`--no-commands\\` / \\`--no-skills\\`\neach suppress one delivery. The tools written for are recorded in\n\\`loam.json\\` as \\`agentTools\\`, which is how \\`loam doctor\\` tells a file missing\nbecause the binary grew a new command from one missing because nobody ever\nselected that tool.\n\nThe map:\n\n`;\n\nconst MAP_REST = `- \\`loam validate --service <id>\\` grades one service's own axes: \\`service.unknown\\`,\n  \\`service.no-model\\`, \\`service.no-spec\\`, \\`service.no-openapi\\`, \\`c4.invalid\\`,\n  \\`c4.no-relationships\\`, \\`requirements.missing-scenarios\\`,\n  \\`requirements.stepless-scenario\\`, \\`requirements.assertionless-scenario\\`,\n  \\`requirements.examples-unbound\\`, \\`requirements.examples-unreferenced\\`,\n  \\`spec.merge-conflict\\`, \\`spec.duplicate-requirement\\`, \\`spec.no-requirements\\`,\n  \\`spec.repeated-operations\\`, \\`spec.repeated-covers\\`, \\`openapi.invalid\\`,\n  \\`openapi.duplicate-operationid\\`, \\`openapi.response-undescribed\\`,\n  \\`openapi.ref-unresolved\\`, \\`api.ungoverned\\`, \\`api.ops-unlinked\\`,\n  \\`api.requirement-deprecated\\`, \\`spec-api.op-undefined\\`,\n  \\`spine.landscape-invalid\\`, \\`spine.op-undefined\\`, \\`spine.op-link-missing\\`,\n  \\`spine.op-deprecated\\`; the async contract axis (AsyncAPI 3):\n  \\`service.no-asyncapi\\`, \\`asyncapi.invalid\\`, \\`asyncapi.duplicate-message\\`,\n  \\`asyncapi.payload-undescribed\\`, \\`asyncapi.ref-unresolved\\`,\n  \\`spine.message-undefined\\`, \\`spec-event.message-undefined\\`,\n  \\`spine.message-unproduced\\`, \\`spine.message-external\\`,\n  \\`asyncapi.message-contested\\`, \\`event.messages-unlinked\\`, \\`event.ungoverned\\`,\n  \\`event.covered\\`; and the architecture spec axis: \\`covers.unknown\\`,\n  \\`health.invalid\\`, \\`health.uncovered\\`, \\`health.dependency-unmodelled\\`.\n  Run inside the service's own repo, once a generated suite exists under\n  \\`<gherkinDir>/loam/\\`, it also grades that suite against the living specs:\n  \\`gherkin.missing\\`, \\`gherkin.stale\\`, \\`gherkin.orphaned\\`. A service that never\n  ran \\`loam gherkin\\` stays quiet — that whole trio is conditional on the suite\n  existing here — and a file tagged with a feature still in flight answers to\n  that feature, not to the living spec it has not merged into yet.\n- \\`loam validate --feature <id>\\` grades a change's three axes against each other and\n  against the fleet in flight: \\`delta.invalid\\`, \\`delta.nothing-tagged\\`,\n  \\`delta.service-unknown\\`, \\`delta.service-id-invalid\\`, \\`spec-api.op-undefined\\`,\n  \\`spec-api.op-pending\\`, \\`c4-api.op-undefined\\`, \\`c4-api.op-pending\\`,\n  \\`c4-api.op-deprecated\\`, \\`c4.op-ungoverned\\`, \\`c4.op-link-missing\\`,\n  \\`c4.service-binding-invalid\\`, \\`api.op-unconsumed\\`,\n  \\`service.no-requirement-delta\\`, \\`archedge.uncovered\\`, and — the same four\n  codes service scope raises, graded here on the feature's own spec.md and\n  arch.spec.md deltas, because every one of those breaches merges into the\n  living document — \\`spec.repeated-operations\\`, \\`spec.repeated-covers\\`,\n  \\`spec.merge-conflict\\` and \\`requirements.stepless-scenario\\`. Then the\n  architecture spec axis (\\`c4.uncovered\\`, plus \\`covers.unknown\\` on the\n  feature's arch.spec.md deltas), the delta-shape group:\n  \\`delta.unknown-section\\`, \\`delta.no-delta-sections\\`,\n  \\`delta.requirement-not-merged\\`, \\`delta.modified-unknown\\`, \\`delta.removed-unknown\\`,\n  \\`delta.added-duplicate\\`, \\`delta.added-near-duplicate\\`, \\`delta.modified-pending\\`,\n  \\`delta.removed-pending\\`, \\`delta.added-conflict\\`, \\`delta.modified-conflict\\`,\n  \\`delta.living-duplicate-requirement\\`, and the API-removal group:\n  \\`openapi.remove-marker-anonymous\\`, \\`openapi.remove-op-consumed\\`.\n  The event axis is graded in feature scope too — the \\`asyncapi.*\\`\n  baseline/removal/conflict codes plus \\`c4-event.*\\` and \\`spec-event.*\\`.\n  Where a finding names another feature in flight (\\`delta.*-pending\\`,\n  \\`delta.added-conflict\\`, \\`delta.modified-conflict\\`, \\`spec-api.op-pending\\`,\n  \\`c4-api.op-pending\\`) the ORDER is the answer, and \\`loam dependencies --json\\`\n  is what computes it: \\`order\\` is a dependency-first sequence, \\`conflicts\\`\n  the pairs no ordering fixes, \\`cycles\\` the ones that need a human.\n- \\`loam validate --all\\` runs both of those for everything and adds the fleet\n  cross-check: \\`landscape.missing\\`, \\`landscape.invalid\\`,\n  \\`landscape.merge-conflict\\`, \\`landscape.service-unmodelled\\`,\n  \\`landscape.service-undocumented\\`, \\`landscape.binding-unknown\\`,\n  \\`landscape.binding-duplicate\\`, the fleet-shape advisories\n  \\`landscape.platform-candidate\\`, \\`landscape.datastore-private\\` and\n  \\`landscape.datastore-shared\\`, \\`service.id-invalid\\` (fleet scope only, and\n  graded before the map is opened, so it stands even when the landscape is\n  missing or unreadable), a per-service \\`sources.unverifiable-from-here\\`, and\n  one check on the docs repo's own AGENTS.md, \\`agents.stale\\`. That last one is\n  the reason to distrust THAT file rather than this page: it fires when its\n  version stamp on line 1 (\\`<!-- generated by loam vX.Y.Z -->\\`) is missing or\n  older than the running binary, which is exactly when what it says may name a\n  loam that no longer exists. It is never refreshed automatically — your edits\n  outrank the template, so detection is all loam does, and a hand-curated file\n  silences it the same way, by keeping the stamp current. This page has no such\n  failure mode: it is printed by the binary it describes.\n  \\`loam validate --all\\`'s \\`--json\\` payload also carries the additive \\`scorecard\\` key — per-axis ceiling-vs-actual fleet\n  aggregates, the text report appending the same table; derived per run and never stored, so week-over-week is the pipeline's job: capture the key per run into a metrics store.\n  \\`scorecard.adoption\\` counts the services PARTICIPATING in each contract axis\n  (requirements, arch, openapi, asyncapi, permissions, capabilities; the\n  denominator is \\`scorecard.services\\`) — an axis at 0 of N reads \"not started\",\n  which is expected during staged adoption and distinct from partially adopted.\n  Text mode folds the warnings such an axis alone causes under one banner per\n  axis and says so; \\`--json\\` carries every finding unchanged, and the summary\n  counts, exit codes and \\`--strict\\` are identical either way.\n- \\`loam doctor\\` is read-only local/fleet preflight — the first thing to run in a\n  repo that behaves as though the fleet were empty. Every finding carries a\n  \\`fix\\` field naming the exact command or edit, so this is the one family you\n  rarely need \\`loam explain\\` for. Its blockers are \\`doctor.config-missing\\`,\n  \\`doctor.config-invalid\\`, \\`doctor.docs-missing\\`, \\`doctor.services-missing\\`, and\n  the three that say the fleet map cannot be read at all —\n  \\`doctor.landscape-merge-conflict\\`, \\`doctor.landscape-invalid\\` and\n  \\`doctor.landscape-unreadable\\`. It also grades what a WRITE that did not finish\n  left in the docs repo, reported as \\`writePath\\` beside the findings:\n  \\`doctor.docs-locked\\`, \\`doctor.commit-interrupted\\`, \\`doctor.commit-unreadable\\`\n  and \\`doctor.staging-temps\\`. When this repo is a service repo that same scan\n  covers \\`<gherkinDir>/loam/\\`, the root \\`loam gherkin\\` commits into.\n  Accessibility, portability and incomplete binding stay warnings:\n  \\`doctor.docs-unreadable\\`, \\`doctor.docs-readonly\\`, \\`doctor.docs-absolute\\`,\n  \\`doctor.inventory-unreadable\\`, \\`doctor.landscape-missing\\`,\n  \\`doctor.service-unbound\\` (never raised inside the docs repo itself, where\n  having no service binding is the correct state), \\`doctor.service-unknown\\`\n  (the same state \\`loam status\\` reports as \\`next.adopt-bound\\`),\n  \\`doctor.likec4-config-missing\\`, and the two about this repo's own generated\n  command and skill files: \\`doctor.agent-files-missing\\` and\n  \\`doctor.agent-files-stale\\`.\n  EXPECT the second one on the first \\`loam doctor\\` after an upgrade. It is not\n  evidence that anything was edited or broken: staleness reads the version\n  stamp only. Re-running \\`loam init\\` refreshes an unchanged pointer only when\n  its current bytes still match the digest recorded in \\`loam.json\\`; an\n  unrecorded or customized file stays in place for a human to review.\n- \\`loam rebase <FEAT>\\` writes the baseline pins: \\`Based-On:\\` under every\n  MODIFIED/REMOVED requirement in the feature's spec deltas, and\n  \\`x-loam-based-on\\` on every operation in its openapi.yaml, from the living text\n  as it stands right now. Run it when you finish authoring a delta and again\n  after you resolve a collision — it is the one mechanism standing between two\n  features in flight and silently reverting each other's landed work. It refuses\n  rather than inventing a pin, and re-pinning is not resolving: see\n  \"The requirement baseline\".\n- \\`loam dependencies [<FEAT>]\\` derives the ordering of the features in flight\n  from the artifacts themselves — requirement identities and OpenAPI\n  operationIds, never from validator prose. It is the answer to every\n  \"another feature in flight does this first\" finding, and to\n  \\`delta.added-conflict\\` / \\`delta.modified-conflict\\`, which no ordering fixes.\n- \\`loam explore [<service>...]\\` reads the fleet around a change nobody has\n  written down yet, and writes nothing. It exists because \\`loam new\\`'s\n  \\`--touches\\` list is the hardest call in the cycle and the only one nothing\n  downstream catches: a list short by one service produces a feature that\n  validates, archives and ships with a consumer nobody updated. What it derives\n  is mechanical — the one-hop ring, each service's rung, its living operations,\n  who already calls whom, and which active features cover the same services. It\n  does NOT decide which of those neighbours you actually change; that is a\n  judgement about intent, and loam does not make those. \\`--op <operationId>\\`\n  seeds from the operation's defining service; \\`--capability <id>\\` (repeatable)\n  seeds from a declared capability's realizing services, and an id that seeds\n  nothing lands in the additive \\`unresolvedCapabilities\\` — beside\n  \\`loam list capabilities\\`, the rollup those seeds are read from.\n- \\`loam seed --from fleet.yaml\\` is the onboarding entry point for an empty\n  fleet: a tiny human-authored YAML — a \\`services:\\` list of ids, optional\n  \\`subsystems:\\`, \\`externals:\\` and \\`calls:\\` lines like\n  \\`checkout -> payments\\` — templated mechanically into\n  architecture/landscape.likec4 (one bound element per service, plain edges, no\n  guessed operationIds) plus one services/<id>/ directory per service, in one\n  journaled transaction. Not an extractor: the human stated every fact, and\n  \"who calls whom\" is the one thing no generator can read off a repository.\n  The seeded landscape carries a line-1 stamp; while it stands unedited,\n  editing fleet.yaml and re-running regenerates the map, and the first hand\n  edit makes the file yours — seed then refuses \\`seed-landscape-edited\\`\n  rather than overwrite. Then adopt each service: \\`loam adopt --service <id>\\`.\n- \\`loam instructions [<page>] [args...]\\` prints one of the six workflow\n  protocols — \\`loam-adopt\\`, \\`loam-feature\\`, \\`loam-implement\\`, \\`loam-check\\`,\n  \\`loam-verify\\`, \\`loam-ship\\` — with \\`$1\\`, \\`$2\\` filled in from the arguments you\n  pass, or one of the four reference pages — \\`loam-codes\\`, \\`loam-spine\\`,\n  \\`loam-authoring\\`, \\`loam-done-check\\` — which take no arguments. With no\n  argument at all it lists both sets. The pages ship inside the binary, so they\n  describe the loam you are about to run rather than the one that scaffolded the\n  repository; the command and skill files \\`loam init\\` writes are pointers at it,\n  and so is AGENTS.md's own \"The reference pages\" section. It reads no\n  \\`loam.json\\` and no docs repo, deliberately: \\`loam-adopt\\`'s own first step is\n  to run \\`loam init\\` when there is no config, so it cannot be the step that\n  requires one.\n`;\n\n/**\n * The reference page's body, up to the modules that continue it. The bullets\n * are ordered so `status` — the orientation command, the one to run when you\n * have lost the session — is read first.\n */\nexport const CODE_MAP = MAP_INTRO + STATUS_COMMAND + MAP_REST;\n"]}
+{"version":3,"file":"command-map.js","sourceRoot":"","sources":["../../../../src/core/agent/agents-md/command-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8DG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAEjD;;;GAGG;AACH,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BjB,CAAC;AAEF,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiMhB,CAAC;AAEF;;;;GAIG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAG,SAAS,GAAG,cAAc,GAAG,QAAQ,CAAC","sourcesContent":["/**\n * Reading loam's output: which codes each invocation can raise.\n *\n * {@link CODE_MAP} is the code-by-code map of `status`, `validate`, `doctor`,\n * `rebase`, `dependencies`, `explore`, `seed` and `instructions` — the part\n * `loam instructions loam-codes` prints. ../workflows/reference/codes.ts\n * composes it with `./map/`, `./map/lenses/` and `./refusals.ts`, in exactly the\n * order ../agents-md.ts used to concatenate them, so the assembled page is the\n * section byte for byte.\n *\n * This module used to hold the other delivery too: `READING_OUTPUT` and\n * `REFERENCE_PAGES`, the two AGENTS.md sections that stayed behind when the map\n * left. Since 0.2.0-alpha.1 AGENTS.md is the single ORIENTATION literal in\n * ../agents-md.ts, which carries its own condensed \"Reading loam's output\" and\n * \"Reference pages\" sections, and nothing assembled the two old constants into\n * anything loam shipped. They were deleted rather than left to be edited as if a\n * reader would ever see them.\n *\n * WHY THE MAP LEFT THE FILE, given that this package's whole subject is a file.\n * AGENTS.md is auto-loaded from the working directory by every agents.md-aware\n * host, on every session, and `loam init` writes it once and never refreshes it.\n * It reached 109,399 bytes; Codex truncates the AGENTS.md chain at 32,768 bytes\n * and Windsurf caps a workspace rule file at 12,000 characters, both silently.\n * Roughly seventy percent of the document was being dropped with no error and no\n * way for the reader to tell which half it held — and this section alone was\n * 44,433 of those bytes, 41% of the file. It is also the half a reader consults\n * at a moment it can name (a run reported something) rather than the half it\n * needs to form a question at all, which is what decided which side of the split\n * it went. ../workflows/reference/reference.ts carries the rest of that argument.\n *\n * The move is a move and not a deletion: every byte is still shipped, still in\n * the same corpus test/codes-drift.test.ts reads (AGENTS_MD + PROTOCOLS), and\n * still one command away rather than one file away.\n *\n * WHAT THE MAP IS, AND WHAT IT DELIBERATELY IS NOT. The unique content is which\n * codes which INVOCATION can raise: nothing else in the corpus says that, and an\n * agent choosing what to run needs it. What it does not carry is a per-code\n * gloss of what each code MEANS. That half used to be written twice — once here,\n * once in the /loam-check fix tables — in two independently worded places, in a\n * file `loam init` writes once and never refreshes, so the two drifted with\n * nothing able to say which had rotted. `loam explain <code>` now answers\n * meaning, severity and fix for every code named below, out of the running\n * binary. test/agent-contract.test.ts holds that pointer honest: every code\n * backticked in the corpus must resolve through `explainSubject`, so a family\n * added here without an explanation fails by name. Keep the code list; add the\n * gloss only where it says something `explain` cannot — a condition on when the\n * invocation raises it at all, or a cross-reference between two codes.\n *\n * ONE PARAGRAPH THE MOVE MADE FALSE, and the reason to look for others like it.\n * The `agents.stale` entry read \"one check on this very file … the reason to\n * distrust what you are reading\", which was true while these bytes WERE the\n * scaffolded AGENTS.md. On a page printed by the binary it is exactly backwards\n * — this page cannot be stale, and the file it warns about is somewhere else —\n * so the entry names AGENTS.md instead. A section that talks about its own\n * document does not survive being moved to another one; that is the class to\n * check for whenever anything else leaves this file.\n *\n * CODE_MAP is one part of the `loam-codes` page, which\n * ../workflows/reference/codes.ts assembles by PLAIN CONCATENATION — no join\n * separator — so it starts at the first character of its opening line and ends\n * with the newline that closes its last one. Keep that shape when editing, or\n * two parts glue onto one line on the printed page.\n */\nimport { STATUS_COMMAND } from \"./map/status.js\";\n\n/**\n * The reference page's own opening: what the map is, where the /loam-check fix\n * tables sit beside it, and the one family `loam explain` cannot answer.\n */\nconst MAP_INTRO = `**What this page is.** It says which codes an INVOCATION can raise. It does\nNOT say what they mean: that half is one command away and describes the loam you\nare running rather than the one that scaffolded this repo. \\`loam explain <code>\\`\ngives one code's meaning, its severity in each scope that grades it, and its fix;\n\\`loam explain --codes\\` lists the whole vocabulary and \\`loam explain --codes --json\\`\nis the machine-readable form. The one family \\`explain\\` does not answer\nis the OpenSpec migration surface (\\`openspec.*\\`, \\`mapping.*\\`) — those commands run\nbefore a repository has a governed loop to look a code up from — so those entries\nalone keep their notes here.\n\nThe code-by-code fix table is a different document again: it lives in the\n\\`/loam-check\\` command \\`loam init\\` lays\ndown. \\`init\\` writes that body twice for every tool it configures: once as a slash\ncommand in the tool's own command directory (you type it), and once as an Agent\nSkill at \\`<tool-dir>/skills/loam-check/SKILL.md\\` (the model loads it by itself when\nthe task matches the skill's description). Same body, two ways in.\n\nWhich tools get them is detected from the repo: \\`loam init\\` scans for the\ndot-directories of the tools it knows (\\`.claude\\`, \\`.cursor\\`, \\`.gemini\\`, …) and\nwrites for the ones it finds, falling back to Claude Code when it finds none.\n\\`loam init --tools <ids|all>\\` overrides the scan — an unknown id is refused\n(\\`invalid-option\\`) rather than skipped — and \\`--no-commands\\` / \\`--no-skills\\`\neach suppress one delivery. The tools written for are recorded in\n\\`loam.json\\` as \\`agentTools\\`, which is how \\`loam doctor\\` tells a file missing\nbecause the binary grew a new command from one missing because nobody ever\nselected that tool.\n\nThe map:\n\n`;\n\nconst MAP_REST = `- \\`loam validate --service <id>\\` grades one service's own axes: \\`service.unknown\\`,\n  \\`service.no-model\\`, \\`service.no-spec\\`, \\`service.no-openapi\\`, \\`c4.invalid\\`,\n  \\`c4.declaration-diverged\\`, \\`c4.element-unowned\\`,\n  \\`c4.no-relationships\\`, \\`requirements.missing-scenarios\\`,\n  \\`requirements.stepless-scenario\\`, \\`requirements.assertionless-scenario\\`,\n  \\`requirements.examples-unbound\\`, \\`requirements.examples-unreferenced\\`,\n  \\`spec.merge-conflict\\`, \\`spec.duplicate-requirement\\`, \\`spec.no-requirements\\`,\n  \\`spec.repeated-operations\\`, \\`spec.repeated-covers\\`, \\`openapi.invalid\\`,\n  \\`openapi.duplicate-operationid\\`, \\`openapi.response-undescribed\\`,\n  \\`openapi.ref-unresolved\\`, \\`api.ungoverned\\`, \\`api.ops-unlinked\\`,\n  \\`api.requirement-deprecated\\`, \\`spec-api.op-undefined\\`,\n  \\`spine.landscape-invalid\\`, \\`spine.op-undefined\\`, \\`spine.op-link-missing\\`,\n  \\`spine.op-deprecated\\`; the async contract axis (AsyncAPI 3):\n  \\`service.no-asyncapi\\`, \\`asyncapi.invalid\\`, \\`asyncapi.duplicate-message\\`,\n  \\`asyncapi.payload-undescribed\\`, \\`asyncapi.ref-unresolved\\`,\n  \\`spine.message-undefined\\`, \\`spec-event.message-undefined\\`,\n  \\`spine.message-unproduced\\`, \\`spine.message-external\\`, \\`spine.message-unbound\\`,\n  \\`asyncapi.message-contested\\`, \\`event.messages-unlinked\\`, \\`event.ungoverned\\`,\n  \\`event.covered\\`; and the architecture spec axis: \\`covers.unknown\\`,\n  \\`health.invalid\\`, \\`health.uncovered\\`, \\`health.dependency-unmodelled\\`.\n  Run inside the service's own repo, once a generated suite exists under\n  \\`<gherkinDir>/loam/\\`, it also grades that suite against the living specs:\n  \\`gherkin.missing\\`, \\`gherkin.stale\\`, \\`gherkin.orphaned\\`. A service that never\n  ran \\`loam gherkin\\` stays quiet — that whole trio is conditional on the suite\n  existing here — and a file tagged with a feature still in flight answers to\n  that feature, not to the living spec it has not merged into yet.\n- \\`loam validate --feature <id>\\` grades a change's three axes against each other and\n  against the fleet in flight: \\`delta.invalid\\`, \\`delta.nothing-tagged\\`,\n  \\`delta.service-unknown\\`, \\`delta.service-id-invalid\\`, \\`spec-api.op-undefined\\`,\n  \\`spec-api.op-pending\\`, \\`c4-api.op-undefined\\`, \\`c4-api.op-pending\\`,\n  \\`c4-api.op-deprecated\\`, \\`c4.op-ungoverned\\`, \\`c4.op-link-missing\\`,\n  \\`c4.service-binding-invalid\\`, \\`api.op-unconsumed\\`,\n  \\`service.no-requirement-delta\\`, \\`archedge.uncovered\\`, and — the same four\n  codes service scope raises, graded here on the feature's own spec.md and\n  arch.spec.md deltas, because every one of those breaches merges into the\n  living document — \\`spec.repeated-operations\\`, \\`spec.repeated-covers\\`,\n  \\`spec.merge-conflict\\` and \\`requirements.stepless-scenario\\`. A feature\n  whose verification record will not read as one raises\n  \\`evidence.record-unreadable\\` (warn) here as well. Then the\n  architecture spec axis (\\`c4.uncovered\\`, plus \\`covers.unknown\\` on the\n  feature's arch.spec.md deltas), the delta-shape group:\n  \\`delta.unknown-section\\`, \\`delta.no-delta-sections\\`,\n  \\`delta.requirement-not-merged\\`, \\`delta.modified-unknown\\`, \\`delta.removed-unknown\\`,\n  \\`delta.added-duplicate\\`, \\`delta.added-near-duplicate\\`, \\`delta.modified-pending\\`,\n  \\`delta.removed-pending\\`, \\`delta.added-conflict\\`, \\`delta.modified-conflict\\`,\n  \\`delta.living-duplicate-requirement\\`, and the API-removal group:\n  \\`openapi.remove-marker-anonymous\\`, \\`openapi.remove-op-consumed\\`, and\n  \\`openapi.op-revived\\` (warn, gates archive: the delta spells an operation an\n  archived feature retired, or at an address one retired or moved it away\n  from while it lives on elsewhere, so the merge would put it back).\n  The event axis is graded in feature scope too — the \\`asyncapi.*\\`\n  baseline/removal/conflict codes, \\`asyncapi.slot-revived\\` (the same revival\n  on a channel, operation or message), plus \\`c4-event.*\\`, \\`spec-event.*\\` and\n  \\`spine.message-unbound\\` (a tagged edge's event key bound to a topic or other infrastructure).\n  Where a finding names another feature in flight (\\`delta.*-pending\\`,\n  \\`delta.added-conflict\\`, \\`delta.modified-conflict\\`, \\`spec-api.op-pending\\`,\n  \\`c4-api.op-pending\\`) the ORDER is the answer, and \\`loam dependencies --json\\`\n  is what computes it: \\`order\\` is a dependency-first sequence, \\`conflicts\\`\n  the pairs no ordering fixes, \\`cycles\\` the ones that need a human.\n- \\`loam validate --all\\` runs both of those for everything and adds the fleet\n  cross-check: \\`landscape.missing\\`, \\`landscape.invalid\\`,\n  \\`landscape.merge-conflict\\`, \\`landscape.service-unmodelled\\`,\n  \\`landscape.service-undocumented\\`, \\`landscape.binding-unknown\\`,\n  \\`landscape.binding-duplicate\\`, the fleet-shape advisories\n  \\`landscape.platform-candidate\\` and\n  \\`landscape.datastore-shared\\`, \\`service.id-invalid\\` (fleet scope only, and\n  graded before the map is opened, so it stands even when the landscape is\n  missing or unreadable), the four renderer-wiring warnings a\n  \\`loam subsystem sync\\` repairs — \\`service.likec4-config-missing\\` (a model that\n  STANDS ALONE, declaring its own \\`specification\\`, with no\n  \\`likec4.config.json\\` beside it: it renders nowhere from the docs root),\n  \\`service.likec4-config-stray\\` (that file beside a model that EXTENDS the map,\n  where it registers a project that CLAIMS the model, out of the root project\n  where the map's kinds are),\n  \\`service.model-excluded\\` (the root \\`likec4.config.json\\` excludes an extending\n  model's directory, so the renderer never loads it) and\n  \\`service.model-unexcluded\\` (it does NOT exclude a standalone model's, so the\n  renderer merges that model into the map and calls every declaration a\n  duplicate) — plus \\`c4.fleet-project-invalid\\` (warn: every document reads clean\n  where loam grades it and the ONE project the renderer builds out of the map and\n  every extending model does not, because something is declared in two of them),\n  a per-service \\`sources.unverifiable-from-here\\`, and\n  one check on the docs repo's own AGENTS.md, \\`agents.stale\\`. That last one is\n  the reason to distrust THAT file rather than this page: it fires when its\n  version stamp on line 1 (\\`<!-- generated by loam vX.Y.Z -->\\`) is missing or\n  older than the running binary, which is exactly when what it says may name a\n  loam that no longer exists. It is never refreshed automatically — your edits\n  outrank the template, so detection is all loam does, and a hand-curated file\n  silences it the same way, by keeping the stamp current. This page has no such\n  failure mode: it is printed by the binary it describes.\n  \\`loam validate --all\\`'s \\`--json\\` payload also carries the additive \\`scorecard\\` key — per-axis ceiling-vs-actual fleet\n  aggregates, the text report appending the same table; derived per run and never stored, so week-over-week is the pipeline's job: capture the key per run into a metrics store.\n  \\`scorecard.adoption\\` counts the services PARTICIPATING in each contract axis\n  (requirements, arch, openapi, asyncapi, permissions, capabilities; the\n  denominator is \\`scorecard.services\\`) — an axis at 0 of N reads \"not started\",\n  which is expected during staged adoption and distinct from partially adopted.\n  Text mode folds the warnings such an axis alone causes under one banner per\n  axis and says so; \\`--json\\` carries every finding unchanged, and the summary\n  counts, exit codes and \\`--strict\\` are identical either way.\n- \\`loam doctor\\` is read-only local/fleet preflight — the first thing to run in a\n  repo that behaves as though the fleet were empty. Every finding carries a\n  \\`fix\\` field naming the exact command or edit, so this is the one family you\n  rarely need \\`loam explain\\` for. Its blockers are \\`doctor.config-missing\\`,\n  \\`doctor.config-invalid\\`, \\`doctor.docs-missing\\`, \\`doctor.services-missing\\`, and\n  the three that say the fleet map cannot be read at all —\n  \\`doctor.landscape-merge-conflict\\`, \\`doctor.landscape-invalid\\` and\n  \\`doctor.landscape-unreadable\\`. It also grades what a WRITE that did not finish\n  left in the docs repo, reported as \\`writePath\\` beside the findings:\n  \\`doctor.docs-locked\\`, \\`doctor.commit-interrupted\\`, \\`doctor.commit-unreadable\\`\n  and \\`doctor.staging-temps\\`. When this repo is a service repo that same scan\n  covers \\`<gherkinDir>/loam/\\`, the root \\`loam gherkin\\` commits into.\n  Accessibility, portability and incomplete binding stay warnings:\n  \\`doctor.docs-unreadable\\`, \\`doctor.docs-readonly\\`, \\`doctor.docs-absolute\\`,\n  \\`doctor.inventory-unreadable\\`, \\`doctor.landscape-missing\\`,\n  \\`doctor.service-unbound\\` (never raised inside the docs repo itself, where\n  having no service binding is the correct state), \\`doctor.service-unknown\\`\n  (the same state \\`loam status\\` reports as \\`next.adopt-bound\\` — or, when an\n  active feature introduces the service, as that feature's \\`next.feature\\`, and\n  then the finding names the feature and \\`currentService.introducedBy\\` lists\n  it: there is nothing to adopt),\n  \\`doctor.likec4-config-missing\\`, and the two about this repo's own generated\n  command and skill files: \\`doctor.agent-files-missing\\` and\n  \\`doctor.agent-files-stale\\`.\n  The second one fires only for a file whose body differs from the one this\n  loam writes AND whose stamp is missing or older — so after an upgrade, expect\n  it when the release changed the pointer text, never for a stamp-only\n  difference, and never for an edited body under a current stamp (that stamp is\n  the record that somebody reviewed it). Re-running \\`loam init\\` refreshes an\n  unchanged pointer only when its current bytes still match the digest\n  recorded in \\`loam.json\\`; an unrecorded or customized file stays in place\n  for a human to review.\n- \\`loam rebase <FEAT>\\` writes the baseline pins: \\`Based-On:\\` under every\n  MODIFIED/REMOVED requirement in the feature's spec deltas, and\n  \\`x-loam-based-on\\` on every operation in its openapi.yaml, from the living text\n  as it stands right now. Run it when you finish authoring a delta and again\n  after you resolve a collision — it is the one mechanism standing between two\n  features in flight and silently reverting each other's landed work. It refuses\n  rather than inventing a pin, and re-pinning is not resolving: see\n  \"The requirement baseline\". An operation or event slot the delta spells that\n  an ARCHIVED feature retired is not pinned as new: rebase prints the\n  \\`openapi.op-revived\\` / \\`asyncapi.slot-revived\\` finding (and \\`revived[]\\` in\n  \\`--json\\`) and leaves the call — delete the quote, or re-add on purpose — to\n  you. It judges the delta as it will write it, pins included, so a quote its\n  own repin turns into an edit — repinned over whatever lives now at an\n  address an archived feature moved the entry away from — is in that list too,\n  under \\`--dry-run\\` as well.\n- \\`loam dependencies [<FEAT>]\\` derives the ordering of the features in flight\n  from the artifacts themselves — requirement identities and OpenAPI\n  operationIds, never from validator prose. It is the answer to every\n  \"another feature in flight does this first\" finding, and to\n  \\`delta.added-conflict\\` / \\`delta.modified-conflict\\`, which no ordering fixes.\n- \\`loam explore [<service>...]\\` reads the fleet around a change nobody has\n  written down yet, and writes nothing. It exists because \\`loam new\\`'s\n  \\`--touches\\` list is the hardest call in the cycle and the only one nothing\n  downstream catches: a list short by one service produces a feature that\n  validates, archives and ships with a consumer nobody updated. What it derives\n  is mechanical — the one-hop ring, each service's rung, its living operations,\n  who already calls whom, and which active features cover the same services. It\n  does NOT decide which of those neighbours you actually change; that is a\n  judgement about intent, and loam does not make those. \\`--op <operationId>\\`\n  seeds from the operation's defining service; \\`--capability <id>\\` (repeatable)\n  seeds from a declared capability's realizing services, and an id that seeds\n  nothing lands in the additive \\`unresolvedCapabilities\\` — beside\n  \\`loam list capabilities\\`, the rollup those seeds are read from.\n- \\`loam seed --from fleet.yaml\\` is the onboarding entry point for an empty\n  fleet: a tiny human-authored YAML — a \\`services:\\` list of ids, optional\n  \\`subsystems:\\`, \\`externals:\\` and \\`calls:\\` lines like\n  \\`checkout -> payments\\` — templated mechanically into\n  architecture/landscape.likec4 (one bound element per service, plain edges, no\n  guessed operationIds) plus one services/<id>/ directory per service, in one\n  journaled transaction. Not an extractor: the human stated every fact, and\n  \"who calls whom\" is the one thing no generator can read off a repository.\n  The seeded landscape carries a line-1 stamp; while it stands unedited,\n  editing fleet.yaml and re-running regenerates the map, and the first hand\n  edit anywhere in the file, including above the stub, makes it yours — seed\n  then refuses \\`seed-landscape-edited\\`\n  rather than overwrite. So seed is a day-zero step: fleet.yaml has no spelling\n  for \\`metadata { op }\\`, and once an edge carries one the map grows through\n  adopt briefs and feature C4 deltas, not through seed. Then adopt each\n  service: \\`loam adopt --service <id>\\`.\n- \\`loam instructions [<page>] [args...]\\` prints one of the six workflow\n  protocols — \\`loam-adopt\\`, \\`loam-feature\\`, \\`loam-implement\\`, \\`loam-check\\`,\n  \\`loam-verify\\`, \\`loam-ship\\` — with \\`$1\\`, \\`$2\\` filled in from the arguments you\n  pass, the \\`loam-report\\` support protocol, or one of the five reference pages —\n  \\`loam-codes\\`, \\`loam-spine\\`, \\`loam-authoring\\`, \\`loam-done-check\\`,\n  \\`loam-drawing\\` — which take no arguments. With no argument at all it lists all three sets. The pages ship\n  inside the binary, so they describe the loam you are about to run rather than\n  the one that scaffolded the repository; the command and skill files\n  \\`loam init\\` writes are pointers at it, and so is AGENTS.md's own\n  \"Reference pages — fetch when needed\" section. It reads no\n  \\`loam.json\\` and no docs repo, deliberately: \\`loam-adopt\\`'s own first step is\n  to run \\`loam init\\` when there is no config, so it cannot be the step that\n  requires one.\n`;\n\n/**\n * The reference page's body, up to the modules that continue it. The bullets\n * are ordered so `status` — the orientation command, the one to run when you\n * have lost the session — is read first.\n */\nexport const CODE_MAP = MAP_INTRO + STATUS_COMMAND + MAP_REST;\n"]}

package/dist/core/agent/agents-md/map/explain.js

@@ -6,23 +6,35 @@
  * subject it answers for is a code or term that already exists elsewhere,
  * which is the point of the command.
  *
- * Same assembly contract as every section: ../../agents-md.ts concatenates
- * with NO join separator, so this string starts at the first character of its
- * opening line and ends with the newline that closes its last one.
+ * Same assembly contract as every part of the `loam-codes` page:
+ * ../../workflows/reference/codes.ts concatenates with NO join separator, so this
+ * string starts at the first character of its opening line and ends with
+ * the newline that closes its last one.
  *
- * The six term names below are HAND-LISTED, unlike the interpolated copies in
+ * The term names below are HAND-LISTED, unlike the interpolated copies in
  * commands/explain and core/mcp/tools — importing core/explain/terms.ts from
  * here would close a package cycle, because terms.ts reads its pin sources
  * from this very package's siblings (agents-md → map → explain → agents-md).
  * test/explain.test.ts pins this string against TERMS instead: a term added
- * to the registry without a name here fails there, loudly.
+ * to the registry without a name here fails there, loudly. They are written
+ * as plain words, not backticked, on purpose: everywhere else on this page a
+ * backticked dotted name is a finding code, and the five claim kinds are
+ * spelled exactly like one without being one.
  */
 export const EXPLAIN_COMMAND = `- \`loam explain [<subject>]\` answers "what does this mean and what do I do
   about it" from the binary itself: a finding code (\`spine.op-undefined\`), a
-  refusal code (\`docs-busy\`), or a concept term — vouch, attested, spine,
-  delta, axis, baseline — and \`loam explain\` alone lists the terms. For
-  finding codes the meaning-and-fix text IS the /loam-check fix table, parsed
-  at runtime from the same body \`loam instructions loam-check\` prints, so the
+  refusal code (\`docs-busy\`), or a concept term — the words loam prints to a
+  person. \`loam explain\` alone lists the terms under five headings: the
+  stages \`loam status\` reports (stage, which also answers missing, blocked and
+  draft; ready; done), the done-check \`loam verify\` asks (claim; its five kinds
+  service.exists, api.exposes, event.declares, c4.calls and scenario.tested;
+  attested; verified), the work packet \`loam tasks\` lists (unit, frontier,
+  describe, generate, implement), and the documents (delta, baseline, spine,
+  axis, coherence, vouch, maturity, which also answers its rungs empty,
+  partial, documented and sourced), and the picture (kind, which also answers
+  each relationship kind from publishes to connects; legend; overview;
+  purpose). For finding codes the meaning-and-fix
+  text IS the /loam-check fix table, parsed at runtime from the same body \`loam instructions loam-check\` prints, so the
   two can never disagree; a code graded in more than one table (service scope
   and \`loam archive\` plan time, say) explains every context it appears in,
   and refusal meanings cover every \`error.code\` the envelope can carry. It

package/dist/core/agent/agents-md/map/explain.js.map

@@ -1 +1 @@
-{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../../../../src/core/agent/agents-md/map/explain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;CAa9B,CAAC","sourcesContent":["/**\n * The `loam explain` entry of the command map — its own section module for\n * `./lenses/gate.ts`'s exact reason: command-map.ts sits against the 300-line\n * limit, so the vocabulary command's documentation lives one package down and\n * is concatenated after the map. It introduces no codes of its own: every\n * subject it answers for is a code or term that already exists elsewhere,\n * which is the point of the command.\n *\n * Same assembly contract as every section: ../../agents-md.ts concatenates\n * with NO join separator, so this string starts at the first character of its\n * opening line and ends with the newline that closes its last one.\n *\n * The six term names below are HAND-LISTED, unlike the interpolated copies in\n * commands/explain and core/mcp/tools — importing core/explain/terms.ts from\n * here would close a package cycle, because terms.ts reads its pin sources\n * from this very package's siblings (agents-md → map → explain → agents-md).\n * test/explain.test.ts pins this string against TERMS instead: a term added\n * to the registry without a name here fails there, loudly.\n */\nexport const EXPLAIN_COMMAND = `- \\`loam explain [<subject>]\\` answers \"what does this mean and what do I do\n  about it\" from the binary itself: a finding code (\\`spine.op-undefined\\`), a\n  refusal code (\\`docs-busy\\`), or a concept term — vouch, attested, spine,\n  delta, axis, baseline — and \\`loam explain\\` alone lists the terms. For\n  finding codes the meaning-and-fix text IS the /loam-check fix table, parsed\n  at runtime from the same body \\`loam instructions loam-check\\` prints, so the\n  two can never disagree; a code graded in more than one table (service scope\n  and \\`loam archive\\` plan time, say) explains every context it appears in,\n  and refusal meanings cover every \\`error.code\\` the envelope can carry. It\n  reads no \\`loam.json\\` and no docs repo, exactly like \\`loam instructions\\`\n  and for the same reason: the vocabulary wall is hit before the wiring\n  exists. An unknown subject refuses \\`unknown-target\\` and offers the closest\n  known names.\n`;\n"]}
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../../../../src/core/agent/agents-md/map/explain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG;;;;;;;;;;;;;;;;;;;;;CAqB9B,CAAC","sourcesContent":["/**\n * The `loam explain` entry of the command map — its own section module for\n * `./lenses/gate.ts`'s exact reason: command-map.ts sits against the 300-line\n * limit, so the vocabulary command's documentation lives one package down and\n * is concatenated after the map. It introduces no codes of its own: every\n * subject it answers for is a code or term that already exists elsewhere,\n * which is the point of the command.\n *\n * Same assembly contract as every part of the `loam-codes` page:\n * ../../workflows/reference/codes.ts concatenates with NO join separator, so this\n * string starts at the first character of its opening line and ends with\n * the newline that closes its last one.\n *\n * The term names below are HAND-LISTED, unlike the interpolated copies in\n * commands/explain and core/mcp/tools — importing core/explain/terms.ts from\n * here would close a package cycle, because terms.ts reads its pin sources\n * from this very package's siblings (agents-md → map → explain → agents-md).\n * test/explain.test.ts pins this string against TERMS instead: a term added\n * to the registry without a name here fails there, loudly. They are written\n * as plain words, not backticked, on purpose: everywhere else on this page a\n * backticked dotted name is a finding code, and the five claim kinds are\n * spelled exactly like one without being one.\n */\nexport const EXPLAIN_COMMAND = `- \\`loam explain [<subject>]\\` answers \"what does this mean and what do I do\n  about it\" from the binary itself: a finding code (\\`spine.op-undefined\\`), a\n  refusal code (\\`docs-busy\\`), or a concept term — the words loam prints to a\n  person. \\`loam explain\\` alone lists the terms under five headings: the\n  stages \\`loam status\\` reports (stage, which also answers missing, blocked and\n  draft; ready; done), the done-check \\`loam verify\\` asks (claim; its five kinds\n  service.exists, api.exposes, event.declares, c4.calls and scenario.tested;\n  attested; verified), the work packet \\`loam tasks\\` lists (unit, frontier,\n  describe, generate, implement), and the documents (delta, baseline, spine,\n  axis, coherence, vouch, maturity, which also answers its rungs empty,\n  partial, documented and sourced), and the picture (kind, which also answers\n  each relationship kind from publishes to connects; legend; overview;\n  purpose). For finding codes the meaning-and-fix\n  text IS the /loam-check fix table, parsed at runtime from the same body \\`loam instructions loam-check\\` prints, so the\n  two can never disagree; a code graded in more than one table (service scope\n  and \\`loam archive\\` plan time, say) explains every context it appears in,\n  and refusal meanings cover every \\`error.code\\` the envelope can carry. It\n  reads no \\`loam.json\\` and no docs repo, exactly like \\`loam instructions\\`\n  and for the same reason: the vocabulary wall is hit before the wiring\n  exists. An unknown subject refuses \\`unknown-target\\` and offers the closest\n  known names.\n`;\n"]}