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

package/dist/commands/vouch/vet/verify.js

@@ -0,0 +1,123 @@
+/**
+ * Does this spec still describe the code it points at?
+ *
+ * One spec, read against the sources it declares. It answers only about what it
+ * could check, and says which sources it skipped — a vouch over a spec whose
+ * sources could not be read would be the claim this command exists to prevent.
+ */
+import { listField, parseFrontmatter } from "../../../core/document/frontmatter.js";
+import { missingSources, patternSources, unsafeSources } from "../../../core/provenance/sources.js";
+import { emptySourcesMessage, sourcesDigest } from "../../../core/provenance/stamp.js";
+import { NotUtf8Error, readUtf8 } from "../../../core/staging/writes.js";
+/**
+ * "There is no living spec here", in one sentence.
+ *
+ * Three callers reach this state independently — the stamp (`../run.ts`), the
+ * reading list (`../sample/plan.ts`) and the reading pack (`../pack/pack.ts`)
+ * — and two of them carried a comment promising to keep the wording identical
+ * to the third, which is a promise nothing could enforce. It lives in the leaf
+ * all three already import, because the failure this repo has actually shipped
+ * is four copies of an enumeration `catch` that looked identical for years
+ * while a fix landed in one of them: a `--sample` run refusing a missing spec
+ * with older advice than a bare run gives is the same defect, one flag wide.
+ */
+export function noLivingSpecMessage(specPath, service) {
+    return `No living spec at ${specPath}. Run \`loam adopt\` for '${service}' first.`;
+}
+/**
+ * The per-file half of the refusal discipline: everything vouch cannot verify
+ * about ONE spec file, checked the same way for spec.md and arch.spec.md.
+ */
+export async function verifySpec(req, path, file) {
+    // Through readUtf8, so the round trip below is exact: the stamp is computed
+    // from `raw` and the race check compares `Buffer.from(raw)` against the bytes
+    // on disk, which only agree if the file decoded without substitutions. A
+    // non-UTF-8 spec is refused by name rather than stamped as verified with
+    // every undecodable byte replaced. Refused HERE rather than left to the CLI's
+    // top-level handler, which would report a diagnosable state as `internal`.
+    // What it replaces is a diagnosis that was worse than none: a UTF-16 spec
+    // decoded to a document with no frontmatter loam could find, so vouch refused
+    // it as `sources-absent` — "names no sources" — over a file whose `sources:`
+    // line is right there.
+    let raw;
+    try {
+        raw = await readUtf8(path);
+    }
+    catch (err) {
+        if (!(err instanceof NotUtf8Error))
+            throw err;
+        return {
+            ok: false,
+            code: "repository-unavailable",
+            message: `${req.service}: ${file} cannot be vouched for — ${err.message}`,
+        };
+    }
+    const fm = parseFrontmatter(raw);
+    // Before any sources reasoning: a header that does not parse hides whatever
+    // fields the author wrote, so "names no sources" would be a false diagnosis —
+    // and if the file ever reached the stamp, withFrontmatterFields' rule for
+    // unreadable headers is replace-don't-merge, which would silently discard the
+    // author's owner/service/sources lines. Refuse before the write path can see
+    // the file. The code stays `sources-absent` — for vouch's purposes the
+    // sources ARE unreadable-hence-absent, and the message carries the real
+    // diagnosis — rather than minting a new ErrorCode for one refusal.
+    if (fm.malformed) {
+        return {
+            ok: false,
+            code: "sources-absent",
+            message: `${req.service}: ${file} has a frontmatter block that cannot be read as YAML — ` +
+                `its fields (\`sources\` included) are unreadable, and stamping would rewrite the header wholesale, ` +
+                `losing what the author wrote. Fix the YAML between the \`---\` fences ` +
+                `(\`loam validate\` reports it as \`frontmatter.malformed\`), then re-run.`,
+        };
+    }
+    const sources = listField(fm, "sources");
+    if (sources.length === 0) {
+        return {
+            ok: false,
+            code: "sources-absent",
+            message: `${req.service}: ${file} names no sources — there is nothing to vouch it against. Add \`sources:\` naming the code it was written from.`,
+        };
+    }
+    // spec.md's refusals predate the second axis and keep their exact wording;
+    // where they did not name the file, only the newer axis adds it.
+    const label = file === "spec.md" ? req.service : `${req.service}: ${file}`;
+    // Before the existence check: a pattern is not a path that "does not exist",
+    // it is an entry loam no longer reads at all, and the refusal has to say so.
+    const patterns = patternSources(sources);
+    if (patterns.length > 0) {
+        return {
+            ok: false,
+            code: "sources-path-missing",
+            message: `${label}: ${patterns.length} source(s) are glob patterns — ${patterns.join(", ")}. Patterns are no longer supported: name files or directories (a directory already covers everything beneath it). A stamp over a pattern would vouch for a file set nobody can be sure of.`,
+        };
+    }
+    const unsafe = unsafeSources(req.repoDir, sources);
+    if (unsafe.length > 0) {
+        return {
+            ok: false,
+            code: "sources-path-missing",
+            message: `${label}: ${unsafe.length} source(s) escape the service repo — ${unsafe.join(", ")}. Sources must be relative paths contained by this repository, including through symlinks; vouch will not hash files outside it.`,
+        };
+    }
+    const missing = missingSources(req.repoDir, sources);
+    if (missing.length > 0) {
+        return {
+            ok: false,
+            code: "sources-path-missing",
+            message: `${label}: ${missing.length} source(s) do not exist — ${missing.join(", ")}. Vouching now would stamp a claim about code that is not there.`,
+        };
+    }
+    const { digest, index, skipped } = await sourcesDigest(req.repoDir, sources);
+    if (index.length === 0) {
+        // A directory that exists but holds no files — or only ones the walk leaves
+        // out: dot-entries, `node_modules`, anything the repository itself ignores.
+        // The paths "resolve", but a digest over nothing never changes, so the stamp
+        // would read as current forever. The sentence comes from provenance/stamp.ts so
+        // that `loam validate` can grade the same state in the same words instead of
+        // going green on a document this command refuses.
+        return { ok: false, code: "sources-absent", message: emptySourcesMessage(label, sources) };
+    }
+    return { ok: true, path, file, raw, sources, digest, index, skipped };
+}
+//# sourceMappingURL=verify.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../../../src/commands/vouch/vet/verify.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAEpF,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,qCAAqC,CAAC;AACpG,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAyB,MAAM,mCAAmC,CAAC;AAE9G,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAuCzE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,mBAAmB,CAAC,QAAgB,EAAE,OAAe;IACnE,OAAO,qBAAqB,QAAQ,6BAA6B,OAAO,UAAU,CAAC;AACrF,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,GAAgB,EAChB,IAAY,EACZ,IAAY;IAEZ,4EAA4E;IAC5E,8EAA8E;IAC9E,yEAAyE;IACzE,yEAAyE;IACzE,8EAA8E;IAC9E,2EAA2E;IAC3E,0EAA0E;IAC1E,8EAA8E;IAC9E,6EAA6E;IAC7E,uBAAuB;IACvB,IAAI,GAAW,CAAC;IAChB,IAAI,CAAC;QACH,GAAG,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,CAAC,GAAG,YAAY,YAAY,CAAC;YAAE,MAAM,GAAG,CAAC;QAC9C,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,wBAAwB;YAC9B,OAAO,EAAE,GAAG,GAAG,CAAC,OAAO,KAAK,IAAI,4BAA4B,GAAG,CAAC,OAAO,EAAE;SAC1E,CAAC;IACJ,CAAC;IACD,MAAM,EAAE,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAC;IACjC,4EAA4E;IAC5E,8EAA8E;IAC9E,0EAA0E;IAC1E,8EAA8E;IAC9E,6EAA6E;IAC7E,uEAAuE;IACvE,wEAAwE;IACxE,mEAAmE;IACnE,IAAI,EAAE,CAAC,SAAS,EAAE,CAAC;QACjB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,gBAAgB;YACtB,OAAO,EACL,GAAG,GAAG,CAAC,OAAO,KAAK,IAAI,yDAAyD;gBAChF,qGAAqG;gBACrG,wEAAwE;gBACxE,2EAA2E;SAC9E,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,SAAS,CAAC,EAAE,EAAE,SAAS,CAAC,CAAC;IACzC,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,gBAAgB;YACtB,OAAO,EAAE,GAAG,GAAG,CAAC,OAAO,KAAK,IAAI,iHAAiH;SAClJ,CAAC;IACJ,CAAC;IAED,2EAA2E;IAC3E,iEAAiE;IACjE,MAAM,KAAK,GAAG,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;IAE3E,6EAA6E;IAC7E,6EAA6E;IAC7E,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC;IACzC,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,sBAAsB;YAC5B,OAAO,EAAE,GAAG,KAAK,KAAK,QAAQ,CAAC,MAAM,kCAAkC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,4LAA4L;SACvR,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,aAAa,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACnD,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,sBAAsB;YAC5B,OAAO,EAAE,GAAG,KAAK,KAAK,MAAM,CAAC,MAAM,wCAAwC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,kIAAkI;SAC/N,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,cAAc,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACrD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,IAAI,EAAE,sBAAsB;YAC5B,OAAO,EAAE,GAAG,KAAK,KAAK,OAAO,CAAC,MAAM,6BAA6B,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,kEAAkE;SACtJ,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,aAAa,CAAC,GAAG,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7E,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvB,4EAA4E;QAC5E,4EAA4E;QAC5E,6EAA6E;QAC7E,gFAAgF;QAChF,6EAA6E;QAC7E,kDAAkD;QAClD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,mBAAmB,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC;IAC7F,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AACxE,CAAC","sourcesContent":["/**\n * Does this spec still describe the code it points at?\n *\n * One spec, read against the sources it declares. It answers only about what it\n * could check, and says which sources it skipped — a vouch over a spec whose\n * sources could not be read would be the claim this command exists to prevent.\n */\nimport { listField, parseFrontmatter } from \"../../../core/document/frontmatter.js\";\nimport type { PathableService } from \"../../../core/kernel/ids/service.js\";\nimport { missingSources, patternSources, unsafeSources } from \"../../../core/provenance/sources.js\";\nimport { emptySourcesMessage, sourcesDigest, type SourceIndexEntry } from \"../../../core/provenance/stamp.js\";\nimport type { SkippedSource } from \"../../../core/provenance/walk.js\";\nimport { NotUtf8Error, readUtf8 } from \"../../../core/staging/writes.js\";\n\nexport interface VerifiedSpec {\n  ok: true;\n  path: string;\n  file: string;\n  /** The file exactly as read — what the stamp is applied to. */\n  raw: string;\n  sources: string[];\n  digest: string;\n  /** Per-file shas, in digest order — what `sources_files` is stamped from. */\n  index: SourceIndexEntry[];\n  skipped: SkippedSource[];\n}\n\n/**\n * The two facts the vetting reads — not the whole VouchRequest, because the\n * reading pack (`../pack/pack.ts`) asks the same questions with no date or\n * identity to offer: a pack stamps nothing.\n */\nexport interface SpecVetting {\n  service: PathableService;\n  repoDir: string;\n}\n\n/**\n * The refusal half, spelled here rather than imported from `../contract.ts`:\n * this module is a LEAF two sibling consumers share — `run.ts` (the stamp) and\n * `pack/pack.ts` (the worklist) — which is why it lives in its own package,\n * and an import from the vouch package above it would close the exact\n * package-graph cycle the move exists to avoid. The codes are a subset of\n * VouchOutcome's refusal codes, so run.ts returns one of these unchanged.\n */\nexport interface SpecRefusal {\n  ok: false;\n  code: \"sources-absent\" | \"sources-path-missing\" | \"repository-unavailable\";\n  message: string;\n}\n\n/**\n * \"There is no living spec here\", in one sentence.\n *\n * Three callers reach this state independently — the stamp (`../run.ts`), the\n * reading list (`../sample/plan.ts`) and the reading pack (`../pack/pack.ts`)\n * — and two of them carried a comment promising to keep the wording identical\n * to the third, which is a promise nothing could enforce. It lives in the leaf\n * all three already import, because the failure this repo has actually shipped\n * is four copies of an enumeration `catch` that looked identical for years\n * while a fix landed in one of them: a `--sample` run refusing a missing spec\n * with older advice than a bare run gives is the same defect, one flag wide.\n */\nexport function noLivingSpecMessage(specPath: string, service: string): string {\n  return `No living spec at ${specPath}. Run \\`loam adopt\\` for '${service}' first.`;\n}\n\n/**\n * The per-file half of the refusal discipline: everything vouch cannot verify\n * about ONE spec file, checked the same way for spec.md and arch.spec.md.\n */\nexport async function verifySpec(\n  req: SpecVetting,\n  path: string,\n  file: string,\n): Promise<VerifiedSpec | SpecRefusal> {\n  // Through readUtf8, so the round trip below is exact: the stamp is computed\n  // from `raw` and the race check compares `Buffer.from(raw)` against the bytes\n  // on disk, which only agree if the file decoded without substitutions. A\n  // non-UTF-8 spec is refused by name rather than stamped as verified with\n  // every undecodable byte replaced. Refused HERE rather than left to the CLI's\n  // top-level handler, which would report a diagnosable state as `internal`.\n  // What it replaces is a diagnosis that was worse than none: a UTF-16 spec\n  // decoded to a document with no frontmatter loam could find, so vouch refused\n  // it as `sources-absent` — \"names no sources\" — over a file whose `sources:`\n  // line is right there.\n  let raw: string;\n  try {\n    raw = await readUtf8(path);\n  } catch (err) {\n    if (!(err instanceof NotUtf8Error)) throw err;\n    return {\n      ok: false,\n      code: \"repository-unavailable\",\n      message: `${req.service}: ${file} cannot be vouched for — ${err.message}`,\n    };\n  }\n  const fm = parseFrontmatter(raw);\n  // Before any sources reasoning: a header that does not parse hides whatever\n  // fields the author wrote, so \"names no sources\" would be a false diagnosis —\n  // and if the file ever reached the stamp, withFrontmatterFields' rule for\n  // unreadable headers is replace-don't-merge, which would silently discard the\n  // author's owner/service/sources lines. Refuse before the write path can see\n  // the file. The code stays `sources-absent` — for vouch's purposes the\n  // sources ARE unreadable-hence-absent, and the message carries the real\n  // diagnosis — rather than minting a new ErrorCode for one refusal.\n  if (fm.malformed) {\n    return {\n      ok: false,\n      code: \"sources-absent\",\n      message:\n        `${req.service}: ${file} has a frontmatter block that cannot be read as YAML — ` +\n        `its fields (\\`sources\\` included) are unreadable, and stamping would rewrite the header wholesale, ` +\n        `losing what the author wrote. Fix the YAML between the \\`---\\` fences ` +\n        `(\\`loam validate\\` reports it as \\`frontmatter.malformed\\`), then re-run.`,\n    };\n  }\n  const sources = listField(fm, \"sources\");\n  if (sources.length === 0) {\n    return {\n      ok: false,\n      code: \"sources-absent\",\n      message: `${req.service}: ${file} names no sources — there is nothing to vouch it against. Add \\`sources:\\` naming the code it was written from.`,\n    };\n  }\n\n  // spec.md's refusals predate the second axis and keep their exact wording;\n  // where they did not name the file, only the newer axis adds it.\n  const label = file === \"spec.md\" ? req.service : `${req.service}: ${file}`;\n\n  // Before the existence check: a pattern is not a path that \"does not exist\",\n  // it is an entry loam no longer reads at all, and the refusal has to say so.\n  const patterns = patternSources(sources);\n  if (patterns.length > 0) {\n    return {\n      ok: false,\n      code: \"sources-path-missing\",\n      message: `${label}: ${patterns.length} source(s) are glob patterns — ${patterns.join(\", \")}. Patterns are no longer supported: name files or directories (a directory already covers everything beneath it). A stamp over a pattern would vouch for a file set nobody can be sure of.`,\n    };\n  }\n\n  const unsafe = unsafeSources(req.repoDir, sources);\n  if (unsafe.length > 0) {\n    return {\n      ok: false,\n      code: \"sources-path-missing\",\n      message: `${label}: ${unsafe.length} source(s) escape the service repo — ${unsafe.join(\", \")}. Sources must be relative paths contained by this repository, including through symlinks; vouch will not hash files outside it.`,\n    };\n  }\n\n  const missing = missingSources(req.repoDir, sources);\n  if (missing.length > 0) {\n    return {\n      ok: false,\n      code: \"sources-path-missing\",\n      message: `${label}: ${missing.length} source(s) do not exist — ${missing.join(\", \")}. Vouching now would stamp a claim about code that is not there.`,\n    };\n  }\n\n  const { digest, index, skipped } = await sourcesDigest(req.repoDir, sources);\n  if (index.length === 0) {\n    // A directory that exists but holds no files — or only ones the walk leaves\n    // out: dot-entries, `node_modules`, anything the repository itself ignores.\n    // The paths \"resolve\", but a digest over nothing never changes, so the stamp\n    // would read as current forever. The sentence comes from provenance/stamp.ts so\n    // that `loam validate` can grade the same state in the same words instead of\n    // going green on a document this command refuses.\n    return { ok: false, code: \"sources-absent\", message: emptySourcesMessage(label, sources) };\n  }\n  return { ok: true, path, file, raw, sources, digest, index, skipped };\n}\n"]}

package/dist/commands/vouch/vouch.js

@@ -0,0 +1,176 @@
+import { loadConfig } from "../../core/envelope/config.js";
+import { fail, NO_SERVICE_MESSAGE, reportNoConfig } 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";
+import { runPack } from "./pack/print.js";
+import { confirmVouch } from "./prompt/confirm.js";
+import { emitStampJson, printStamp } from "./report.js";
+import { vouch } from "./run.js";
+import { buildSamplePlan } from "./sample/plan.js";
+import { printReadingList } from "./sample/print.js";
+export function registerVouch(program) {
+    program
+        .command("vouch")
+        .description("Vouch for a service's living specs: stamp spec.md, and arch.spec.md when present, verified against the code they describe")
+        .option("--service <id>", "service to vouch for (defaults to the configured service)")
+        .option("--yes", "skip the confirmation — required when stdin is not a terminal, and still records `vouched_by`")
+        .option("--pack", "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")
+        .option("--sample <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")
+        .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);
+            return;
+        }
+        const config = loaded.config;
+        const service = opts.service ?? config.service;
+        if (service === undefined) {
+            return fail(json, "invalid-option", NO_SERVICE_MESSAGE);
+        }
+        // Vouching hashes the code the doc was written from, so it can only run
+        // where that code is. From anywhere else the paths are someone else's.
+        //
+        // TWO conditions, two codes, and the split is the whole point. Both used
+        // to answer `invalid-option`, whose `loam explain` row says the
+        // invocation itself is wrong — contradictory flags, a mistyped one, a
+        // value that cannot be right. Here the invocation is perfectly correct
+        // and the REPOSITORY is the wrong one, so that code sent a user whose
+        // flags were fine off to re-read their flags, and left CI and agents
+        // unable to tell "run this in the service repo" from "you typed the flag
+        // wrong". `loam verify --record --service` already draws exactly this
+        // line for exactly this reason (see commands/verify/verify.ts); vouch
+        // and gherkin now answer the same pair, so a caller branching on
+        // `error.code` gets one answer from all three. The messages are
+        // unchanged — only the code moved.
+        if (config.service === undefined) {
+            return fail(json, "repository-unavailable", `Cannot vouch for '${service}' from here: this is not a service repo. \`sources\` resolve against the service's own repo — run it there.`);
+        }
+        if (config.service !== service) {
+            return fail(json, "service-mismatch", `Cannot vouch for '${service}' from here: this repo is '${config.service}'. \`sources\` resolve against the service's own repo — run it there.`);
+        }
+        // The repo root, not the cwd — see the comment on `repoDir` below; the
+        // identity has to be asked of the same directory the sources resolve in,
+        // or a subdirectory with its own git config would answer for it.
+        const repoDir = config.root ?? process.cwd();
+        // The flag's own grammar, before anything is read or hashed: `--sample`
+        // decides what the run CLAIMS, so a value nobody can read must not reach
+        // a stamp. Whole numbers only, and at least one — `0` is a vouch that
+        // read nothing, and there is already a way to record that (do not
+        // vouch). Checked before `--pack` below so a typo is refused the same
+        // way in both modes.
+        let sampleSize;
+        if (opts.sample !== undefined) {
+            if (!/^\d+$/.test(opts.sample.trim()) || Number(opts.sample) < 1) {
+                return fail(json, "invalid-option", `--sample expects a positive whole number of sections; got '${opts.sample}'. ` +
+                    "Nothing was read and nothing was stamped.");
+            }
+            sampleSize = Number(opts.sample);
+        }
+        // The reading pack: read-only, so it runs BEFORE — and instead of —
+        // every write-path gate below (identity, TTY, `--yes`, lock, journal),
+        // which all defend the stamp; pack/pack.ts's banner carries the full
+        // reasoning. It runs AFTER the wrong-repo gate above on purpose: the
+        // source delta resolves `sources` here. `--yes` does not compose — it
+        // is the unattended stamp, and a pack that stamped would defeat the
+        // read it just prescribed.
+        if (opts.pack === true) {
+            if (opts.yes === true) {
+                return fail(json, "invalid-option", "--pack is the reading list and --yes is the unattended stamp; a pack that immediately " +
+                    `stamped would defeat the read it just prescribed. Run --pack, read it, then \`loam vouch --service ${service}\`.`);
+            }
+            // `--sample` composes with the pack instead of conflicting with it:
+            // the pack is the reading list, and a sampled vouch's reading list is
+            // the sample. Passing it here makes the pack print the sections the
+            // subsequent `loam vouch --sample <n>` will stamp for — the same
+            // derivation from the same seed, so the two cannot prescribe
+            // different documents.
+            return runPack({ docsDir: config.docsDir, service: config.service, repoDir, json, sample: sampleSize });
+        }
+        // Who. Before any reading, because a run that cannot name a person has
+        // nothing to offer at the end of it and should not spend a digest finding
+        // that out.
+        const vouchedBy = await gitIdentity(repoDir);
+        if (vouchedBy === null) {
+            return fail(json, "vouch-unattributable", `Cannot vouch for '${service}': git names no \`user.email\` in ${repoDir}, so the stamp would ` +
+                "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
+        // `--yes` gets past here.
+        const attended = opts.yes === true;
+        if (!attended) {
+            if (process.stdin.isTTY !== true) {
+                return fail(json, "vouch-unattended", `Cannot vouch for '${service}' with nothing on the other end of stdin: this command records that ` +
+                    "a PERSON read the code and says the document matches it, and nobody was asked. Run it from a " +
+                    "terminal, or pass --yes to state that you are standing behind it anyway — `vouched_by` records " +
+                    `${vouchedBy} either way.`);
+            }
+            // `--json` and a prompt do not compose: the envelope is one JSON
+            // document on stdout, and a question printed beside it is not parseable
+            // by the consumer that asked for it. A JSON caller is a program, so it
+            // gets the same answer a pipe does — say so with --yes.
+            if (json) {
+                return fail(json, "vouch-unattended", `Cannot vouch for '${service}' in --json mode without --yes: the confirmation is a question for a ` +
+                    "person, and it cannot be asked on a stream whose whole contract is one JSON document.");
+            }
+        }
+        // The reading list is built BEFORE the question and AFTER the attendance
+        // gates: a run that cannot ask anybody anything must not spend two
+        // source-tree digests finding that out, and a person must not be asked
+        // to confirm a sample nobody has shown them. Every refusal a vouch can
+        // raise about these documents fires in here, so it lands before the read
+        // rather than after it.
+        let sample;
+        if (sampleSize !== undefined) {
+            const built = await buildSamplePlan({ docsDir: config.docsDir, service: config.service, repoDir, n: sampleSize });
+            if (!built.ok)
+                return fail(json, built.code, built.message);
+            sample = built.plan;
+            if (!json)
+                printReadingList(sample, service);
+        }
+        const servicePath = await serviceTreePathOf(config.docsDir, service);
+        if (!attended && !(await confirmVouch({ service, vouchedBy, docsDir: config.docsDir, servicePath, sample }))) {
+            return fail(json, "vouch-declined", `Nothing was stamped for '${service}'.`);
+        }
+        const outcome = await vouch({
+            docsDir: config.docsDir,
+            // The guard above proved `service` IS `config.service`, and only the
+            // latter carries the parse (`loam.json`'s `service` field is validated
+            // at load). Same string, but only one spelling is pathable.
+            service: config.service,
+            vouchedBy,
+            // The repo root, not the cwd. `sources:` are spelled relative to the
+            // repository — that is what they mean in the frontmatter and what
+            // `loam validate` resolves them against — so vouching from a
+            // subdirectory used to report every real source as missing
+            // (`sources-path-missing`) and refuse the stamp. `config.root` is the
+            // directory loam.json was found in, which is the only definition of
+            // "this repo" that does not move with the caller.
+            repoDir,
+            today: today(new Date()),
+            // Absent for an ordinary vouch, which is what makes an ordinary vouch
+            // CLEAR a prior sample's scope rather than leave it standing.
+            ...(sample === undefined ? {} : { sample }),
+        });
+        if (!outcome.ok)
+            return fail(json, outcome.code, outcome.message);
+        const report = { service, docsDir: config.docsDir, outcome, ...(sample === undefined ? {} : { sample }) };
+        if (json)
+            return emitStampJson(report);
+        printStamp(report);
+    });
+}
+//# sourceMappingURL=vouch.js.map

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

@@ -0,0 +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"]}

package/dist/core/agent/agents-md/artifacts.js

@@ -0,0 +1,220 @@
+/**
+ * The document's opening arc: what the docs repo HOLDS — the layout, how its
+ * documents link to each other, the glossary, architectural obligations, and
+ * the `loam.json` wiring every repository commits.
+ *
+ * The three sections that used to close this file — the architecture spec
+ * axis, the generated Gherkin suite, and the frontmatter/vouch chain — are now
+ * the `loam-authoring` reference page (../workflows/reference/authoring.ts),
+ * printed by `loam instructions loam-authoring` rather than written into
+ * AGENTS.md. They are grammars consulted while writing ONE document, and the
+ * file they were in is auto-loaded on every session by hosts that truncate it
+ * silently; ./command-map.ts's header carries the measurement that decided it.
+ * What is left here is what an agent must know before it can form a question
+ * at all.
+ *
+ * One section 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.
+ */
+export const ARTIFACTS = `# Working in this docs repo
+
+This is a **loam** docs repo: the shared source of truth for a governed software
+system — its architecture, requirements, contracts and evidence. Everything here
+is plain files. \`loam\` reads and writes them; delete \`loam\` and the docs remain.
+
+**The bar this artifact set aims at is reproducibility**: a reader should be able
+to answer, from these files alone — what each governed boundary exposes, what it
+reaches, what shapes it exchanges, how it is run, and what pages whom —
+without opening the code. \`loam validate\` grades form and joins, never depth:
+green means the files agree with each other, and the bar is what "done" is
+measured against — a thin baseline that validates is thin, not done.
+
+## Layout
+
+\`\`\`
+architecture/landscape.likec4     the living C4 model of the whole system
+architecture/permissions.yaml     optional system-wide authorization vocabulary
+architecture/obligations.yaml     optional ARCHITECTURAL obligations (#obl-<name> on the map)
+architecture/adrs/NNNN-*.md       optional SYSTEM-level decisions (MADR) — only their links are graded
+glossary/<term>.md                optional domain vocabulary — one file per term, nesting allowed
+services/<svc>/
+  model.likec4                    this governed boundary's C4
+  spec.md                         its living requirements (current state)
+  arch.spec.md                    its living ARCHITECTURE requirements (outbox, retries, alerts)
+  openapi.yaml                    its API contract
+  asyncapi.yaml                   its AsyncAPI 3 event contract
+  adrs/  runbook.md  health.yaml  why it is like this, how to run it
+features/<FEAT>/                  a change in flight
+  intent.md                       why, in business terms
+  delta.likec4                    the architecture change, tagged #<FEAT>
+  specs/<svc>/spec.md             the requirement change for one governed boundary
+  specs/<svc>/arch.spec.md        the architectural requirement change, same delta grammar
+  specs/<svc>/openapi.yaml        the endpoints this feature adds
+  specs/<svc>/asyncapi.yaml       the event-contract delta (optional; a complete AsyncAPI 3 document)
+  verification.yaml               what was checked once the code was built
+features/archive/<FEAT>/          shipped changes — the evolution history
+\`\`\`
+
+## Linking between documents
+
+Documents here link to each other with **standard markdown links**, and the
+target is a relative path to the file:
+
+\`\`\`markdown
+[0001 — transactional outbox](../../architecture/adrs/0001-transactional-outbox.md)
+\`\`\`
+
+Two reasons, and the second is the one that decides it. A markdown link renders
+as a link in pull-request review, which is where these documents are actually
+read, while \`[[0001 transactional outbox]]\` renders there as the literal
+brackets somebody typed. And its target is a real relative path, so "does this
+link resolve" is a filesystem question with a yes-or-no answer — where resolving
+a wikilink means reimplementing Obsidian's shortest-unique-path search across the
+whole repo, which is guessing, and loam refuses and names rather than guessing.
+
+You lose nothing by it. Obsidian reads a repo written this way with no
+integration at all — graph view, backlinks and search all work on markdown links
+— and its per-vault \`Use [[Wikilinks]]\` setting turns OFF, after which its own
+autocomplete and rename-tracking produce markdown links too. The authoring
+comfort is a toggle in somebody's editor, not a decision this repo carries.
+
+**\`loam validate\` resolves these links** (\`link.unresolved\`, error): a relative
+target that names nothing is a broken join, reported once per document with
+every bad link and its line. A link here is a **join**, not decoration — a
+requirement that names a term wants that term's document linked, and an ADR that
+supersedes another wants to say which, the same kind of relationship
+\`Operations:\` and \`Covers:\` already state.
+
+Three things are deliberately NOT graded, so write them freely: a target outside
+this repository (\`../../some-service/README.md\` — that tree may not be checked
+out beside these documents), a link to a heading (\`#section\`), and any link
+inside a fenced code block or an inline code span, which is how a document shows
+the convention without being convicted for it.
+
+CASE **is** graded, and deliberately: \`[Order](Order.md)\` beside a file called
+\`order.md\` resolves on Windows and macOS and 404s on GitHub and every Linux
+runner, so the message names the stored spelling on all of them alike.
+
+## The glossary — the system's domain words
+
+\`glossary/<term>.md\`, one file per term, nesting allowed
+(\`glossary/payments/authorization.md\` is the term \`payments/authorization\`). There is
+no \`glossary.yaml\`: a definition is prose, and the DIRECTORY is the list. The
+directory's existence is the opt-in — a system without one hears nothing.
+
+**A term is checkable because a link is a join.** Cite it from the document that
+uses the word — a requirement, a capability document, a feature's intent — with an
+ordinary relative link:
+
+\`\`\`markdown
+An [Order](../../glossary/order.md) is what a customer has confirmed.
+\`\`\`
+
+A citation that does not resolve is \`link.unresolved\` like any other; a term nothing
+outside \`glossary/\` cites is \`glossary.unlinked\` (warn). Terms citing each other is
+normal and does NOT count as adoption — a glossary is a network of definitions, and
+two terms defining each other say nothing about whether the system uses either word.
+\`loam list glossary\` prints every term with the documents that cite it.
+
+**A feature may bring a new word with it**: write it at
+\`features/<FEAT>/glossary/<term>.md\` and \`loam archive\` copies it into \`glossary/\`,
+\`loam unarchive\` takes it back out. This route is CREATE-ONLY — a term the living
+glossary already defines is \`glossary.term-exists\`, which \`--approve\` does not
+override, because the merge is a whole-file copy and would replace an authored
+definition wholesale. To CHANGE a definition, edit \`glossary/<term>.md\` directly in
+the same pull request, where git produces an ordinary conflict.
+
+Cite the new word at its FUTURE living path (\`../../../../glossary/order.md\` from a
+\`specs/<svc>/\` delta) — that link resolves while the feature is in flight, and the
+merge re-expresses it from wherever the text lands, so it keeps resolving afterwards.
+
+Write the definition for a reader who knows the business and not this system: what the
+word means, and what it is NOT (an order is not a cart). Never which service owns it —
+that is the system map's question and it changes.
+
+
+## Architectural obligations — what the architect hands the team
+
+An architect has always had one checked channel here: an edge carrying
+\`metadata { op 'authorizePayment' }\` obliges the provider to define that operationId,
+or \`spine.op-undefined\` fails the gate. Obligations are the same handoff for the rules
+that VARY — an outbox on this publisher and not that one, a circuit breaker on two
+edges out of five — and they are three separate things on purpose:
+
+- an **ADR** in \`architecture/adrs/\` says WHAT was decided, as thin or as thick as the
+  decision needs;
+- a **\`#obl-<name>\` tag** on an element or an edge in \`architecture/landscape.likec4\`
+  says WHERE it applies, so one ADR governs three edges and not the fourth without the
+  document forking;
+- **\`architecture/obligations.yaml\`** declares the names, so a mistyped tag is an error
+  rather than a word nobody notices.
+
+\`\`\`yaml
+obligations:
+  outbox:
+    description: Publishers write the event and the state change in one transaction.
+    adr: architecture/adrs/0001-transactional-outbox.md   # relative to the docs repo root
+\`\`\`
+
+**Your side of it is \`Covers:\`**. A tagged object with no living requirement covering it
+is \`obligation.uncovered\` (warn), and the finding names the service, the object and the
+exact line to write — \`Covers: <element>\` or \`Covers: <source> -> <target>\` in that
+service's \`arch.spec.md\`, with a scenario that proves it. An id is its own tag suffix,
+so it may hold letters, digits, \`_\` and \`-\` only.
+
+## \`loam.json\` — the wiring, in every repo
+
+A governed system is **N + 1 repositories**: this docs repo, and one per governed
+implementation boundary. Paths and commands call that boundary a \`service\`; it
+may be a modular monolith, a network service, a CLI or a worker. Every repo
+commits its own \`loam.json\`, so an agent, human or CI runner can find the rest
+of the system. There is no global config; without a \`loam.json\`, commands refuse
+with \`no-config\` rather than guessing.
+
+\`\`\`json
+{ "docsDir": "../docs-repo", "service": "payment-service", "gherkinDir": "features" }
+\`\`\`
+
+- \`docsDir\` — where the docs repo is, **stored exactly as it was passed** and
+  resolved against the directory holding the \`loam.json\`. So \`../docs-repo\`
+  keeps working on every machine that checks the repos out side by side, which
+  is the point of committing the file. An absolute path is a warning
+  (\`doctor.docs-absolute\`): it resolves only on the machine that ran \`loam init\`.
+  The docs repo's own \`loam.json\` says \`"docsDir": "."\`.
+- \`service\` — the canonical id of the governed boundary THIS repo contains, i.e. the
+  \`services/<id>/\` directory it is allowed to speak for. \`loam vouch\`,
+  \`loam gherkin\` and \`loam verify --service\` when writing with \`--record\`,
+  \`--results\` or \`--contract-results\` bind to it; without it they refuse
+  (\`repository-unavailable\`) rather than write another boundary's documents
+  from a repo that is not that boundary's. A read-only verify checklist needs no
+  binding and works from the docs repo.
+- \`gherkinDir\` — optional, default \`features\`: the directory \`loam gherkin\`
+  writes its own \`loam/\` subtree into.
+- \`agentTools\` — optional: the agent tools \`loam init\` has written command and
+  skill files for here, accumulated across runs. Written by \`init\`, read by
+  \`loam doctor\`; nothing else depends on it, and a config without it loads.
+
+**Step 0 of everything below, once per repo:**
+
+\`\`\`sh
+loam init --docs ../docs-repo --service payment-service   # in EACH service repo
+loam doctor                                               # before you trust any of it
+\`\`\`
+
+\`loam init --docs <dir>\` **joins** an existing docs repo; creating a new one
+takes \`--create\`, so a mistyped path cannot quietly scaffold a second source of
+truth beside the real one. \`loam doctor\` is the read-only preflight: it reads
+loam.json defensively, resolves \`docsDir\`, probes access, checks \`services/\` and
+the system map, and reports the service binding — run it first when anything
+behaves as though the system were empty.
+
+**Living vs delta.** \`services/<svc>/spec.md\` is the complete current state.
+\`features/<FEAT>/specs/<svc>/spec.md\` is a diff against it, reviewed as a diff, with
+requirements grouped under \`## ADDED\`, \`## MODIFIED\` or \`## REMOVED Requirements\`.
+\`loam archive\` folds the delta into the living state.
+
+`;
+//# sourceMappingURL=artifacts.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../../../../src/core/agent/agents-md/artifacts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAqMxB,CAAC","sourcesContent":["/**\n * The document's opening arc: what the docs repo HOLDS — the layout, how its\n * documents link to each other, the glossary, architectural obligations, and\n * the `loam.json` wiring every repository commits.\n *\n * The three sections that used to close this file — the architecture spec\n * axis, the generated Gherkin suite, and the frontmatter/vouch chain — are now\n * the `loam-authoring` reference page (../workflows/reference/authoring.ts),\n * printed by `loam instructions loam-authoring` rather than written into\n * AGENTS.md. They are grammars consulted while writing ONE document, and the\n * file they were in is auto-loaded on every session by hosts that truncate it\n * silently; ./command-map.ts's header carries the measurement that decided it.\n * What is left here is what an agent must know before it can form a question\n * at all.\n *\n * One section of the AGENTS.md template. ../agents-md.ts assembles the\n * document by PLAIN CONCATENATION — no join separator — so every section\n * starts at the first character of its opening line and ends with the newline\n * that closes its last one. Keep that shape when editing, or two sections glue\n * onto one line in every docs repo loam scaffolds from now on.\n */\nexport const ARTIFACTS = `# Working in this docs repo\n\nThis is a **loam** docs repo: the shared source of truth for a governed software\nsystem — its architecture, requirements, contracts and evidence. Everything here\nis plain files. \\`loam\\` reads and writes them; delete \\`loam\\` and the docs remain.\n\n**The bar this artifact set aims at is reproducibility**: a reader should be able\nto answer, from these files alone — what each governed boundary exposes, what it\nreaches, what shapes it exchanges, how it is run, and what pages whom —\nwithout opening the code. \\`loam validate\\` grades form and joins, never depth:\ngreen means the files agree with each other, and the bar is what \"done\" is\nmeasured against — a thin baseline that validates is thin, not done.\n\n## Layout\n\n\\`\\`\\`\narchitecture/landscape.likec4     the living C4 model of the whole system\narchitecture/permissions.yaml     optional system-wide authorization vocabulary\narchitecture/obligations.yaml     optional ARCHITECTURAL obligations (#obl-<name> on the map)\narchitecture/adrs/NNNN-*.md       optional SYSTEM-level decisions (MADR) — only their links are graded\nglossary/<term>.md                optional domain vocabulary — one file per term, nesting allowed\nservices/<svc>/\n  model.likec4                    this governed boundary's C4\n  spec.md                         its living requirements (current state)\n  arch.spec.md                    its living ARCHITECTURE requirements (outbox, retries, alerts)\n  openapi.yaml                    its API contract\n  asyncapi.yaml                   its AsyncAPI 3 event contract\n  adrs/  runbook.md  health.yaml  why it is like this, how to run it\nfeatures/<FEAT>/                  a change in flight\n  intent.md                       why, in business terms\n  delta.likec4                    the architecture change, tagged #<FEAT>\n  specs/<svc>/spec.md             the requirement change for one governed boundary\n  specs/<svc>/arch.spec.md        the architectural requirement change, same delta grammar\n  specs/<svc>/openapi.yaml        the endpoints this feature adds\n  specs/<svc>/asyncapi.yaml       the event-contract delta (optional; a complete AsyncAPI 3 document)\n  verification.yaml               what was checked once the code was built\nfeatures/archive/<FEAT>/          shipped changes — the evolution history\n\\`\\`\\`\n\n## Linking between documents\n\nDocuments here link to each other with **standard markdown links**, and the\ntarget is a relative path to the file:\n\n\\`\\`\\`markdown\n[0001 — transactional outbox](../../architecture/adrs/0001-transactional-outbox.md)\n\\`\\`\\`\n\nTwo reasons, and the second is the one that decides it. A markdown link renders\nas a link in pull-request review, which is where these documents are actually\nread, while \\`[[0001 transactional outbox]]\\` renders there as the literal\nbrackets somebody typed. And its target is a real relative path, so \"does this\nlink resolve\" is a filesystem question with a yes-or-no answer — where resolving\na wikilink means reimplementing Obsidian's shortest-unique-path search across the\nwhole repo, which is guessing, and loam refuses and names rather than guessing.\n\nYou lose nothing by it. Obsidian reads a repo written this way with no\nintegration at all — graph view, backlinks and search all work on markdown links\n— and its per-vault \\`Use [[Wikilinks]]\\` setting turns OFF, after which its own\nautocomplete and rename-tracking produce markdown links too. The authoring\ncomfort is a toggle in somebody's editor, not a decision this repo carries.\n\n**\\`loam validate\\` resolves these links** (\\`link.unresolved\\`, error): a relative\ntarget that names nothing is a broken join, reported once per document with\nevery bad link and its line. A link here is a **join**, not decoration — a\nrequirement that names a term wants that term's document linked, and an ADR that\nsupersedes another wants to say which, the same kind of relationship\n\\`Operations:\\` and \\`Covers:\\` already state.\n\nThree things are deliberately NOT graded, so write them freely: a target outside\nthis repository (\\`../../some-service/README.md\\` — that tree may not be checked\nout beside these documents), a link to a heading (\\`#section\\`), and any link\ninside a fenced code block or an inline code span, which is how a document shows\nthe convention without being convicted for it.\n\nCASE **is** graded, and deliberately: \\`[Order](Order.md)\\` beside a file called\n\\`order.md\\` resolves on Windows and macOS and 404s on GitHub and every Linux\nrunner, so the message names the stored spelling on all of them alike.\n\n## The glossary — the system's domain words\n\n\\`glossary/<term>.md\\`, one file per term, nesting allowed\n(\\`glossary/payments/authorization.md\\` is the term \\`payments/authorization\\`). There is\nno \\`glossary.yaml\\`: a definition is prose, and the DIRECTORY is the list. The\ndirectory's existence is the opt-in — a system without one hears nothing.\n\n**A term is checkable because a link is a join.** Cite it from the document that\nuses the word — a requirement, a capability document, a feature's intent — with an\nordinary relative link:\n\n\\`\\`\\`markdown\nAn [Order](../../glossary/order.md) is what a customer has confirmed.\n\\`\\`\\`\n\nA citation that does not resolve is \\`link.unresolved\\` like any other; a term nothing\noutside \\`glossary/\\` cites is \\`glossary.unlinked\\` (warn). Terms citing each other is\nnormal and does NOT count as adoption — a glossary is a network of definitions, and\ntwo terms defining each other say nothing about whether the system uses either word.\n\\`loam list glossary\\` prints every term with the documents that cite it.\n\n**A feature may bring a new word with it**: write it at\n\\`features/<FEAT>/glossary/<term>.md\\` and \\`loam archive\\` copies it into \\`glossary/\\`,\n\\`loam unarchive\\` takes it back out. This route is CREATE-ONLY — a term the living\nglossary already defines is \\`glossary.term-exists\\`, which \\`--approve\\` does not\noverride, because the merge is a whole-file copy and would replace an authored\ndefinition wholesale. To CHANGE a definition, edit \\`glossary/<term>.md\\` directly in\nthe same pull request, where git produces an ordinary conflict.\n\nCite the new word at its FUTURE living path (\\`../../../../glossary/order.md\\` from a\n\\`specs/<svc>/\\` delta) — that link resolves while the feature is in flight, and the\nmerge re-expresses it from wherever the text lands, so it keeps resolving afterwards.\n\nWrite the definition for a reader who knows the business and not this system: what the\nword means, and what it is NOT (an order is not a cart). Never which service owns it —\nthat is the system map's question and it changes.\n\n\n## Architectural obligations — what the architect hands the team\n\nAn architect has always had one checked channel here: an edge carrying\n\\`metadata { op 'authorizePayment' }\\` obliges the provider to define that operationId,\nor \\`spine.op-undefined\\` fails the gate. Obligations are the same handoff for the rules\nthat VARY — an outbox on this publisher and not that one, a circuit breaker on two\nedges out of five — and they are three separate things on purpose:\n\n- an **ADR** in \\`architecture/adrs/\\` says WHAT was decided, as thin or as thick as the\n  decision needs;\n- a **\\`#obl-<name>\\` tag** on an element or an edge in \\`architecture/landscape.likec4\\`\n  says WHERE it applies, so one ADR governs three edges and not the fourth without the\n  document forking;\n- **\\`architecture/obligations.yaml\\`** declares the names, so a mistyped tag is an error\n  rather than a word nobody notices.\n\n\\`\\`\\`yaml\nobligations:\n  outbox:\n    description: Publishers write the event and the state change in one transaction.\n    adr: architecture/adrs/0001-transactional-outbox.md   # relative to the docs repo root\n\\`\\`\\`\n\n**Your side of it is \\`Covers:\\`**. A tagged object with no living requirement covering it\nis \\`obligation.uncovered\\` (warn), and the finding names the service, the object and the\nexact line to write — \\`Covers: <element>\\` or \\`Covers: <source> -> <target>\\` in that\nservice's \\`arch.spec.md\\`, with a scenario that proves it. An id is its own tag suffix,\nso it may hold letters, digits, \\`_\\` and \\`-\\` only.\n\n## \\`loam.json\\` — the wiring, in every repo\n\nA governed system is **N + 1 repositories**: this docs repo, and one per governed\nimplementation boundary. Paths and commands call that boundary a \\`service\\`; it\nmay be a modular monolith, a network service, a CLI or a worker. Every repo\ncommits its own \\`loam.json\\`, so an agent, human or CI runner can find the rest\nof the system. There is no global config; without a \\`loam.json\\`, commands refuse\nwith \\`no-config\\` rather than guessing.\n\n\\`\\`\\`json\n{ \"docsDir\": \"../docs-repo\", \"service\": \"payment-service\", \"gherkinDir\": \"features\" }\n\\`\\`\\`\n\n- \\`docsDir\\` — where the docs repo is, **stored exactly as it was passed** and\n  resolved against the directory holding the \\`loam.json\\`. So \\`../docs-repo\\`\n  keeps working on every machine that checks the repos out side by side, which\n  is the point of committing the file. An absolute path is a warning\n  (\\`doctor.docs-absolute\\`): it resolves only on the machine that ran \\`loam init\\`.\n  The docs repo's own \\`loam.json\\` says \\`\"docsDir\": \".\"\\`.\n- \\`service\\` — the canonical id of the governed boundary THIS repo contains, i.e. the\n  \\`services/<id>/\\` directory it is allowed to speak for. \\`loam vouch\\`,\n  \\`loam gherkin\\` and \\`loam verify --service\\` when writing with \\`--record\\`,\n  \\`--results\\` or \\`--contract-results\\` bind to it; without it they refuse\n  (\\`repository-unavailable\\`) rather than write another boundary's documents\n  from a repo that is not that boundary's. A read-only verify checklist needs no\n  binding and works from the docs repo.\n- \\`gherkinDir\\` — optional, default \\`features\\`: the directory \\`loam gherkin\\`\n  writes its own \\`loam/\\` subtree into.\n- \\`agentTools\\` — optional: the agent tools \\`loam init\\` has written command and\n  skill files for here, accumulated across runs. Written by \\`init\\`, read by\n  \\`loam doctor\\`; nothing else depends on it, and a config without it loads.\n\n**Step 0 of everything below, once per repo:**\n\n\\`\\`\\`sh\nloam init --docs ../docs-repo --service payment-service   # in EACH service repo\nloam doctor                                               # before you trust any of it\n\\`\\`\\`\n\n\\`loam init --docs <dir>\\` **joins** an existing docs repo; creating a new one\ntakes \\`--create\\`, so a mistyped path cannot quietly scaffold a second source of\ntruth beside the real one. \\`loam doctor\\` is the read-only preflight: it reads\nloam.json defensively, resolves \\`docsDir\\`, probes access, checks \\`services/\\` and\nthe system map, and reports the service binding — run it first when anything\nbehaves as though the system were empty.\n\n**Living vs delta.** \\`services/<svc>/spec.md\\` is the complete current state.\n\\`features/<FEAT>/specs/<svc>/spec.md\\` is a diff against it, reviewed as a diff, with\nrequirements grouped under \\`## ADDED\\`, \\`## MODIFIED\\` or \\`## REMOVED Requirements\\`.\n\\`loam archive\\` folds the delta into the living state.\n\n`;\n"]}