@ybotok/loam 0.2.0-alpha.7 → 0.2.0-alpha.9

package/dist/commands/archive/plan/refusal.js

@@ -3,10 +3,11 @@
  *
  * Every arm here keeps one property: a refusal means nothing was written. The
  * `--json` shapes carry the issues that caused it so an agent can act on the
- * list rather than on the sentence, and `ArchiveFailure` exists so a merge that
- * could not be computed reports as a merge failure rather than as `internal` —
- * a read-only directory or an unreadable pre-image is not a bug in loam, and
- * saying so sends the reader looking for one.
+ * list rather than on the sentence, and a refusal thrown from below is a
+ * `CodedFailure` (core/envelope/json.ts) so a merge that could not be computed
+ * reports as a merge failure rather than as `internal` — a read-only directory
+ * or an unreadable pre-image is not a bug in loam, and saying so sends the
+ * reader looking for one.
  */
 import { existsSync } from "node:fs";
 import { emitJsonError, repoPath } from "../../../core/envelope/json.js";
@@ -15,20 +16,9 @@ import {} from "../../../core/staging/interrupted.js";
 import {} from "../../../core/staging/writes.js";
 import { findingJson } from "../../../core/vocabulary/report.js";
 /**
- * A refusal or failure with its stable `--json` code attached. Thrown from the
- * plan phase (nothing written yet) and from the commit's rollback path (whose
- * message says whether the rollback held). Anything ELSE that escapes runArchive
- * is a bug, and the action handler reports it as `internal`.
- */
-export class ArchiveFailure extends Error {
-    code;
-    constructor(code, msg) {
-        super(msg);
-        this.code = code;
-    }
-}
-/**
- * An Issue as the `--json` envelope spells it — the Finding shape, minus details.
+ * An Issue as the `--json` envelope spells it — the whole Finding shape, `details`
+ * included (`[]` when the issue carries none; the overwrite warnings list their
+ * current consumers there), plus `overridable`.
  * `gates` and `overridable` are always present and already resolved: a consumer
  * must not have to re-implement the severity default to know what blocks
  * archive, nor keep a code list to know what `--approve` can move.

package/dist/commands/archive/plan/refusal.js.map

@@ -1 +1 @@
-{"version":3,"file":"refusal.js","sourceRoot":"","sources":["../../../../src/commands/archive/plan/refusal.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * How `loam archive` refuses, and what a refusal prints.\n *\n * Every arm here keeps one property: a refusal means nothing was written. The\n * `--json` shapes carry the issues that caused it so an agent can act on the\n * list rather than on the sentence, and `ArchiveFailure` exists so a merge that\n * could not be computed reports as a merge failure rather than as `internal` —\n * a read-only directory or an unreadable pre-image is not a bug in loam, and\n * saying so sends the reader looking for one.\n */\nimport { existsSync } from \"node:fs\";\nimport { emitJsonError, repoPath, type ErrorCode } from \"../../../core/envelope/json.js\";\nimport {\n  approveOverrides,\n  issueFinding,\n  type Issue,\n} from \"../../../core/vocabulary/issue.js\";\nimport { type CommitRecovery } from \"../../../core/staging/interrupted.js\";\nimport { type PlannedWrite } from \"../../../core/staging/writes.js\";\nimport { findingJson, type Finding } from \"../../../core/vocabulary/report.js\";\n\nexport interface ArchiveOptions {\n  approve?: boolean;\n  dryRun?: boolean;\n  json?: boolean;\n}\n\n\n/**\n * A refusal or failure with its stable `--json` code attached. Thrown from the\n * plan phase (nothing written yet) and from the commit's rollback path (whose\n * message says whether the rollback held). Anything ELSE that escapes runArchive\n * is a bug, and the action handler reports it as `internal`.\n */\nexport class ArchiveFailure extends Error {\n  constructor(\n    readonly code: ErrorCode,\n    msg: string,\n  ) {\n    super(msg);\n  }\n}\n\n/**\n * An Issue as the `--json` envelope spells it — the Finding shape, minus details.\n * `gates` and `overridable` are always present and already resolved: a consumer\n * must not have to re-implement the severity default to know what blocks\n * archive, nor keep a code list to know what `--approve` can move.\n */\nexport function issueJson(i: Issue, scope?: string): Record<string, unknown> {\n  return {\n    ...findingJson(\n      issueFinding(i),\n      scope === undefined ? undefined : { path: scope, role: \"scope\" },\n    ),\n    overridable: approveOverrides(i),\n  };\n}\n\n/** The failure envelope plus the issues that caused it, so a caller need not re-run validate. */\nexport function refuseJson(code: ErrorCode, msg: string, issues: Issue[], scope?: string): void {\n  emitJsonError(code, msg, { issues: issues.map((issue) => issueJson(issue, scope)) });\n}\n\n/**\n * The same envelope for a refusal computed from `Finding`s rather than\n * `Issue`s — the plan-time checks whose codes are not coherence's (they belong\n * to the LIVING documents, not to the feature) and so are not `IssueCode`s.\n *\n * `gates: true` is asserted rather than derived: every finding listed in a\n * refusal is a reason archive stopped, which is what the field means. Nothing\n * advisory reaches here.\n */\nexport function refuseFindings(\n  code: ErrorCode,\n  msg: string,\n  findings: Finding[],\n  scope?: string,\n): void {\n  emitJsonError(code, msg, {\n    issues: findings.map((finding) => ({\n      ...findingJson(\n        finding,\n        scope === undefined ? undefined : { path: scope, role: \"scope\" },\n      ),\n      gates: true,\n    })),\n  });\n}\n\n/**\n * Take the docs repo's advisory lock for the WHOLE plan+commit window, then\n * archive.\n *\n * The window is the point. Two archives that overlap do not fight over a\n * rename: they each read the living landscape, each splice their additions into\n * the bytes they read, and the second write replaces the first — both exit 0,\n * and `validate` stays green over a landscape that is missing one feature's\n * architecture, because a document with fewer elements is not an invalid one.\n * That is the only silent-loss path in loam that a later command cannot even\n * detect, so it is closed at the coarsest possible granularity: one writer per\n * docs repo, refusing rather than queueing, because a CLI that blocks for an\n * unknown time is worse for an agent than one that says `docs-busy`.\n */\n\n/**\n * What the recovery did, before this command's own output — a docs repo that\n * changed under the caller is the first thing they have to be told, not a\n * footnote. Shared by archive and unarchive through the same CommitRecovery.\n */\nexport function sayRecovery(r: CommitRecovery): void {\n  const what = `an interrupted \\`loam ${r.command} ${r.feature}\\``;\n  if (r.outcome === \"completed\") {\n    console.log(`⚠ ${what} had in fact finished — cleared its commit record.\\n`);\n    return;\n  }\n  if (r.outcome === \"consistent\") {\n    console.log(`⚠ ${what} was rolled back before it wrote anything — cleared its commit record.\\n`);\n    return;\n  }\n  // An interrupted archive is UNDONE and an interrupted unarchive is FINISHED —\n  // the merged text a restore was replacing is written down nowhere, so there is\n  // nothing to go back to. Say which happened; the paths are the same either way.\n  const what_ = r.command === \"archive\" ? \"put them back from\" : \"finished them from\";\n  console.log(`⚠ ${what} left ${r.repaired.length} file(s) half-written; ${what_} its snapshot:`);\n  for (const p of r.repaired) console.log(`  ↩ ${p}`);\n  console.log(\"\");\n}\n\n/** The full plan, as files: what a dry run shows instead of doing. */\nexport function printPlan(docsDir: string, writes: PlannedWrite[], dirName: string): void {\n  console.log(`\\n  plan — ${writes.length} file(s):`);\n  for (const w of writes) {\n    const verb = existsSync(w.path) ? \"update\" : \"create\";\n    console.log(`    ${verb}  ${repoPath(docsDir, w.path)}`);\n  }\n  console.log(`    move    features/${dirName} → features/archive/${dirName}`);\n  console.log(\"\\n  dry run — nothing was written.\");\n}\n"]}
+{"version":3,"file":"refusal.js","sourceRoot":"","sources":["../../../../src/commands/archive/plan/refusal.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * How `loam archive` refuses, and what a refusal prints.\n *\n * Every arm here keeps one property: a refusal means nothing was written. The\n * `--json` shapes carry the issues that caused it so an agent can act on the\n * list rather than on the sentence, and a refusal thrown from below is a\n * `CodedFailure` (core/envelope/json.ts) so a merge that could not be computed\n * reports as a merge failure rather than as `internal` — a read-only directory\n * or an unreadable pre-image is not a bug in loam, and saying so sends the\n * reader looking for one.\n */\nimport { existsSync } from \"node:fs\";\nimport { emitJsonError, repoPath, type ErrorCode } from \"../../../core/envelope/json.js\";\nimport {\n  approveOverrides,\n  issueFinding,\n  type Issue,\n} from \"../../../core/vocabulary/issue.js\";\nimport { type CommitRecovery } from \"../../../core/staging/interrupted.js\";\nimport { type PlannedWrite } from \"../../../core/staging/writes.js\";\nimport { findingJson, type Finding } from \"../../../core/vocabulary/report.js\";\n\nexport interface ArchiveOptions {\n  approve?: boolean;\n  dryRun?: boolean;\n  json?: boolean;\n}\n\n/**\n * An Issue as the `--json` envelope spells it — the whole Finding shape, `details`\n * included (`[]` when the issue carries none; the overwrite warnings list their\n * current consumers there), plus `overridable`.\n * `gates` and `overridable` are always present and already resolved: a consumer\n * must not have to re-implement the severity default to know what blocks\n * archive, nor keep a code list to know what `--approve` can move.\n */\nexport function issueJson(i: Issue, scope?: string): Record<string, unknown> {\n  return {\n    ...findingJson(\n      issueFinding(i),\n      scope === undefined ? undefined : { path: scope, role: \"scope\" },\n    ),\n    overridable: approveOverrides(i),\n  };\n}\n\n/** The failure envelope plus the issues that caused it, so a caller need not re-run validate. */\nexport function refuseJson(code: ErrorCode, msg: string, issues: Issue[], scope?: string): void {\n  emitJsonError(code, msg, { issues: issues.map((issue) => issueJson(issue, scope)) });\n}\n\n/**\n * The same envelope for a refusal computed from `Finding`s rather than\n * `Issue`s — the plan-time checks whose codes are not coherence's (they belong\n * to the LIVING documents, not to the feature) and so are not `IssueCode`s.\n *\n * `gates: true` is asserted rather than derived: every finding listed in a\n * refusal is a reason archive stopped, which is what the field means. Nothing\n * advisory reaches here.\n */\nexport function refuseFindings(\n  code: ErrorCode,\n  msg: string,\n  findings: Finding[],\n  scope?: string,\n): void {\n  emitJsonError(code, msg, {\n    issues: findings.map((finding) => ({\n      ...findingJson(\n        finding,\n        scope === undefined ? undefined : { path: scope, role: \"scope\" },\n      ),\n      gates: true,\n    })),\n  });\n}\n\n/**\n * Take the docs repo's advisory lock for the WHOLE plan+commit window, then\n * archive.\n *\n * The window is the point. Two archives that overlap do not fight over a\n * rename: they each read the living landscape, each splice their additions into\n * the bytes they read, and the second write replaces the first — both exit 0,\n * and `validate` stays green over a landscape that is missing one feature's\n * architecture, because a document with fewer elements is not an invalid one.\n * That is the only silent-loss path in loam that a later command cannot even\n * detect, so it is closed at the coarsest possible granularity: one writer per\n * docs repo, refusing rather than queueing, because a CLI that blocks for an\n * unknown time is worse for an agent than one that says `docs-busy`.\n */\n\n/**\n * What the recovery did, before this command's own output — a docs repo that\n * changed under the caller is the first thing they have to be told, not a\n * footnote. Shared by archive and unarchive through the same CommitRecovery.\n */\nexport function sayRecovery(r: CommitRecovery): void {\n  const what = `an interrupted \\`loam ${r.command} ${r.feature}\\``;\n  if (r.outcome === \"completed\") {\n    console.log(`⚠ ${what} had in fact finished — cleared its commit record.\\n`);\n    return;\n  }\n  if (r.outcome === \"consistent\") {\n    console.log(`⚠ ${what} was rolled back before it wrote anything — cleared its commit record.\\n`);\n    return;\n  }\n  // An interrupted archive is UNDONE and an interrupted unarchive is FINISHED —\n  // the merged text a restore was replacing is written down nowhere, so there is\n  // nothing to go back to. Say which happened; the paths are the same either way.\n  const what_ = r.command === \"archive\" ? \"put them back from\" : \"finished them from\";\n  console.log(`⚠ ${what} left ${r.repaired.length} file(s) half-written; ${what_} its snapshot:`);\n  for (const p of r.repaired) console.log(`  ↩ ${p}`);\n  console.log(\"\");\n}\n\n/** The full plan, as files: what a dry run shows instead of doing. */\nexport function printPlan(docsDir: string, writes: PlannedWrite[], dirName: string): void {\n  console.log(`\\n  plan — ${writes.length} file(s):`);\n  for (const w of writes) {\n    const verb = existsSync(w.path) ? \"update\" : \"create\";\n    console.log(`    ${verb}  ${repoPath(docsDir, w.path)}`);\n  }\n  console.log(`    move    features/${dirName} → features/archive/${dirName}`);\n  console.log(\"\\n  dry run — nothing was written.\");\n}\n"]}

package/dist/commands/archive/plan/specs.js

@@ -23,8 +23,8 @@ import { locateServicePaths } from "../../../core/repo/service-target.js";
 import { isRequirementsHeading, parseRequirements, sectionHeadings, splitRequirementsSection, } from "../../../core/document/parse.js";
 import { applyRequirementDelta } from "../../../core/document/apply.js";
 import { serializeRequirements } from "../../../core/document/spec.js";
-import {} from "../../../core/document/spec.js";
-import { ArchiveFailure } from "./refusal.js";
+import { movedUnderVouch, parseFrontmatter, stringField } from "../../../core/document/frontmatter.js";
+import { CodedFailure } from "../../../core/envelope/json.js";
 import {} from "./state.js";
 export async function planSpecs(config, gated, plan, say) {
     const { featureDir, deltaServices } = gated;
@@ -71,10 +71,23 @@ export async function planSpecs(config, gated, plan, say) {
             // Mechanical, like a model-less landscape, so merge-failed, not --approve.
             const reqHeadings = sectionHeadings(livingText).filter((h) => isRequirementsHeading(h.text));
             if (reqHeadings.length > 1) {
-                throw new ArchiveFailure("merge-failed", `living ${axis.file} for ${svc} has ${reqHeadings.length} '## Requirements' headings (lines ${reqHeadings.map((h) => h.line).join(", ")}) — the merge rewrites ONE requirements section and cannot choose; merge them into one, then re-run`);
+                throw new CodedFailure("merge-failed", `living ${axis.file} for ${svc} has ${reqHeadings.length} '## Requirements' headings (lines ${reqHeadings.map((h) => h.line).join(", ")}) — the merge rewrites ONE requirements section and cannot choose; merge them into one, then re-run`);
+            }
+            const livingReqs = parseRequirements(livingText);
+            const merged = applyRequirementDelta(livingReqs, deltaReqs);
+            const next = rewriteRequirementsRun(livingText, livingReqs, merged);
+            writes.push(planWrite(livingPath, next));
+            // A merge is an edit to the document's body like any other, so a vouched
+            // spec it moves goes `content.stale` — and honestly: the merged text is
+            // words no person has yet read against the code. Archive does not soften
+            // that. It names the document and its owner, so the re-vouch is known to
+            // be owed while the merge is still a PR rather than discovered later as a
+            // red `--strict` gate. Asked of the bytes about to be written, through the
+            // one definition validate grades with.
+            const fm = parseFrontmatter(next);
+            if (movedUnderVouch(fm, next)) {
+                plan.revouchOwed.push({ service: svc, path: livingPath, owner: stringField(fm, "owner") ?? null });
             }
-            const merged = applyRequirementDelta(parseRequirements(livingText), deltaReqs);
-            writes.push(planWrite(livingPath, rewriteRequirementsRun(livingText, merged)));
             const c = summarize(deltaReqs);
             say(`  ${axis.label}: ${svc} ← +${c.ADDED} ~${c.MODIFIED} -${c.REMOVED} (now ${merged.length} total)`);
         }
@@ -144,10 +157,11 @@ export async function planCapabilities(config, gated, plan, say) {
         // reason it cannot be guessed at.
         const reqHeadings = sectionHeadings(livingText).filter((h) => isRequirementsHeading(h.text));
         if (reqHeadings.length > 1) {
-            throw new ArchiveFailure("merge-failed", `living capabilities/${doc.id}/spec.md has ${reqHeadings.length} '## Requirements' headings (lines ${reqHeadings.map((h) => h.line).join(", ")}) — the merge rewrites ONE requirements section and cannot choose; merge them into one, then re-run`);
+            throw new CodedFailure("merge-failed", `living capabilities/${doc.id}/spec.md has ${reqHeadings.length} '## Requirements' headings (lines ${reqHeadings.map((h) => h.line).join(", ")}) — the merge rewrites ONE requirements section and cannot choose; merge them into one, then re-run`);
         }
-        const merged = applyRequirementDelta(parseRequirements(livingText), deltaReqs);
-        writes.push(planWrite(livingPath, rewriteRequirementsRun(livingText, merged)));
+        const livingReqs = parseRequirements(livingText);
+        const merged = applyRequirementDelta(livingReqs, deltaReqs);
+        writes.push(planWrite(livingPath, rewriteRequirementsRun(livingText, livingReqs, merged)));
         const c = summarize(deltaReqs);
         say(`  capability: ${doc.id} ← +${c.ADDED} ~${c.MODIFIED} -${c.REMOVED} (now ${merged.length} total)`);
     }
@@ -156,32 +170,127 @@ export async function planCapabilities(config, gated, plan, say) {
     }
 }
 /**
- * Rewrite ONLY the requirements run of a living spec. Byte-for-byte preserved:
- * everything before the first requirement inside `## Requirements` (the intro,
- * the heading line, prose under the heading) and everything from the section's
- * end onward (the next `## ` heading to EOF) — the old cut was a substring
- * `indexOf("\n## Requirements")`, a prefix match that also hit
- * `## Requirements Extra` and silently destroyed every section after the
- * requirements. Prose BETWEEN requirements is body text of whatever is open
- * above it (parseRequirements attributes it to the previous requirement's last
- * scenario, or its text) and survives inside the re-serialized run, framing
- * normalized. `merged` must contain every living requirement — runArchive's
+ * Rewrite ONLY what the delta touched inside a living spec's requirements run.
+ * Byte-for-byte preserved: everything before the first requirement inside
+ * `## Requirements` (the intro, the heading line, prose under the heading) and
+ * everything from the section's end onward (the next `## ` heading to EOF) —
+ * the old cut was a substring `indexOf("\n## Requirements")`, a prefix match
+ * that also hit `## Requirements Extra` and silently destroyed every section
+ * after the requirements. `living` must be every living requirement — the gate's
  * stray guard refuses any document whose requirements sit outside the section,
  * using the same heading definition, before this output is ever written.
+ *
+ * Inside the run the unit is one requirement, and an untouched one is written
+ * back as its raw slice (`spliceRun`). The whole run used to be re-serialized,
+ * and `serializeRequirements` writes a blank line under every
+ * `### Requirement:` heading — so a living spec written without one, the shape
+ * the adopt brief's own examples taught, had that line inserted under every
+ * requirement the feature never mentioned. The diff, the vouch pack and the
+ * re-vouch all widened from the delta to the whole section.
+ *
+ * Exported for test/archive.test.ts alone: the slice-to-requirement join
+ * (`verbatimSlices`) can only be handed a disagreeing pair directly, because
+ * the gate refuses every document that would produce one through the CLI.
  */
-function rewriteRequirementsRun(text, merged) {
+export function rewriteRequirementsRun(text, living, merged) {
     const s = splitRequirementsSection(text);
     // No `## Requirements` at all: the stray guard has already refused any doc
     // whose requirements live elsewhere, so this one has none — open the section.
     if (s === null)
         return `${text.trimEnd()}\n\n## Requirements\n\n${serializeRequirements(merged)}`;
-    const body = serializeRequirements(merged);
-    // head/tail are raw slices; only the run's own framing is normalized. When
-    // the section held no requirements yet, the glue supplies the blank line the
-    // author never had reason to write.
-    const headGlue = s.run !== "" || s.head.endsWith("\n\n") ? "" : s.head.endsWith("\n") ? "\n" : "\n\n";
+    if (s.run !== "")
+        return s.head + spliceRun(s, living, merged) + s.tail;
+    // The section held no requirements yet: head and tail are raw slices, and the
+    // glue supplies the blank lines the author never had reason to write.
+    const headGlue = s.head.endsWith("\n\n") ? "" : s.head.endsWith("\n") ? "\n" : "\n\n";
     const tailGlue = s.tail === "" ? "" : "\n";
-    return s.head + headGlue + body + tailGlue + s.tail;
+    return s.head + headGlue + serializeRequirements(merged) + tailGlue + s.tail;
+}
+/** The line breaks (and blank lines) a slice ends with — what separates it from whatever follows. */
+const TRAILING_BREAKS = /(?:\r?\n[ \t]*)*$/;
+/**
+ * The merged run: every living requirement the delta left alone as its raw
+ * slice, every one it added or replaced serialized, in `merged`'s order.
+ *
+ * Keyed on object identity, which `applyRequirementDelta` keeps for exactly the
+ * requirements it did not touch — so there is no second reading here of what
+ * the delta changed, and no way for the splice and the algebra to disagree.
+ * Which slice belongs to which living requirement is `verbatimSlices`' join.
+ *
+ * Prose BETWEEN requirements rides in the slice of the requirement above it,
+ * which is where parseRequirements attributes it too: it survives verbatim
+ * beside an untouched requirement and goes with a replaced one, as it always
+ * did — a MODIFIED carries its full new text.
+ */
+function spliceRun(section, living, merged) {
+    const verbatim = verbatimSlices(section.requirements, living);
+    let out = "";
+    let previousVerbatim = true;
+    for (const requirement of merged) {
+        const raw = verbatim.get(requirement);
+        // Two untouched neighbours keep whatever the author put between them. Next
+        // to a serialized requirement the canonical blank line is ADDED after the
+        // untouched text, never by rewriting it.
+        if (out !== "" && (raw === undefined || !previousVerbatim))
+            out = withBlankLine(out);
+        out += raw ?? serializeRequirements([requirement]);
+        previousVerbatim = raw !== undefined;
+    }
+    if (out === "")
+        return "";
+    // The run ends as it ended: whatever separated the old last requirement from
+    // the next heading (or EOF) now follows the new last one — and at least a
+    // newline when a merged requirement lands where the file used to stop without one.
+    const ending = section.run.slice(section.run.search(TRAILING_BREAKS));
+    const body = out.slice(0, out.search(TRAILING_BREAKS));
+    return body + (ending === "" && merged.at(-1) !== living.at(-1) ? "\n" : ending);
+}
+/** A requirement's identity as the merge selects it: `Requirement-ID:` when authored, the exact heading otherwise. */
+const identity = (r) => (r.id === undefined ? `name:${r.name}` : `id:${r.id}`);
+/**
+ * Each living requirement's raw slice, joined on its IDENTITY — the slice read
+ * back through the same parser that produced `living`, so a slice can only
+ * land in place of the requirement it actually is.
+ *
+ * The join used to be by position, guarded by a count. The two walks agree in
+ * order today (one heading-and-fence definition, core/document/parse.ts, and
+ * the gate's stray guard refusing any requirement outside the section), but
+ * nothing declared that, and equal counts paired differently would have written
+ * one requirement's bytes where another belongs — under its vouch stamp, with
+ * nothing to say so.
+ *
+ * Fails closed to the empty map, which serializes every requirement — the old
+ * whole-run rewrite, still a correct merge and only a wider diff: when the
+ * counts differ, when a slice does not read as exactly one requirement, when
+ * two slices claim one identity, or when a living requirement finds no slice
+ * of its own.
+ */
+function verbatimSlices(slices, living) {
+    const none = new Map();
+    if (slices.length !== living.length)
+        return none;
+    const byIdentity = new Map();
+    for (const slice of slices) {
+        const [only, ...more] = parseRequirements(slice);
+        if (only === undefined || more.length > 0 || byIdentity.has(identity(only)))
+            return none;
+        byIdentity.set(identity(only), slice);
+    }
+    const verbatim = new Map();
+    for (const requirement of living) {
+        const slice = byIdentity.get(identity(requirement));
+        if (slice === undefined)
+            return none;
+        // Taken once: a second living requirement of the same identity finds nothing.
+        byIdentity.delete(identity(requirement));
+        verbatim.set(requirement, slice);
+    }
+    return verbatim;
+}
+/** `text` ending in a blank line: line breaks appended to make one, nothing rewritten. */
+function withBlankLine(text) {
+    const breaks = text.slice(text.search(TRAILING_BREAKS)).split("\n").length - 1;
+    return breaks >= 2 ? text : text + "\n".repeat(2 - breaks);
 }
 function summarize(reqs) {
     const c = { ADDED: 0, MODIFIED: 0, REMOVED: 0 };

package/dist/commands/archive/plan/specs.js.map

@@ -1 +1 @@
-{"version":3,"file":"specs.js","sourceRoot":"","sources":["../../../../src/commands/archive/plan/specs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The requirements merge: the feature's ADDED/MODIFIED/REMOVED requirements\n * applied into each living service spec. The contract merges live beside it in\n * `./contracts/` — one file per axis, split out when the OpenAPI half made\n * this one carry two merges.\n *\n * ONE code path for the pair of requirement-carrying files — the business\n * spec.md and the architecture arch.spec.md ride the same delta algebra, the\n * same prose-preserving rewrite and the same guards, parameterized by filename.\n * A fork here would be two places the merge could disagree.\n *\n * Nothing is written. Everything lands in the `Plan`, so a failure on any axis\n * leaves the living docs exactly as they were.\n */\nimport { existsSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport { rebaseLinks } from \"../../../core/links/parse.js\";\nimport { planWrite, readUtf8 } from \"../../../core/staging/writes.js\";\nimport { featureSpecPaths, SPEC_AXES } from \"../../../core/repo/paths.js\";\nimport { capabilityDocsDir, glossaryDir, livingCapabilityPaths } from \"../../../core/repo/authored/paths.js\";\nimport { featureGlossary, livingTermPath } from \"../../../core/glossary/delta.js\";\nimport { locateServicePaths } from \"../../../core/repo/service-target.js\";\nimport {\n  isRequirementsHeading,\n  parseRequirements,\n  sectionHeadings,\n  splitRequirementsSection,\n} from \"../../../core/document/parse.js\";\nimport { applyRequirementDelta } from \"../../../core/document/apply.js\";\nimport { serializeRequirements } from \"../../../core/document/spec.js\";\nimport { type Requirement } from \"../../../core/document/spec.js\";\nimport { ArchiveFailure } from \"./refusal.js\";\nimport { type Gated, type Plan } from \"./state.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport type { FleetContext } from \"../../../core/fleet-context.js\";\n\nexport async function planSpecs(\n  config: { docsDir: DocsDir; fleet?: FleetContext },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const { featureDir, deltaServices } = gated;\n  const { writes } = plan;\n  // Requirements merge — apply ADDED/MODIFIED/REMOVED into each living service\n  // spec. ONE code path for the pair of requirement-carrying files: the business\n  // spec.md and the architecture arch.spec.md ride the same delta algebra, the\n  // same prose-preserving rewrite and the same guards, parameterized by filename\n  // (SPEC_AXES) — a fork here would be two places the merge could disagree.\n  for (const svc of deltaServices) {\n    for (const axis of SPEC_AXES) {\n      const deltaPath = featureSpecPaths(featureDir, svc)[axis.key];\n      if (!existsSync(deltaPath)) continue;\n\n      // The shared context: this is a deltaServices × SPEC_AXES loop, and a\n      // context-less locate is a full fleet walk per iteration.\n      const livingPath = (await locateServicePaths(config.docsDir, svc, config.fleet))[axis.key];\n      // Resolved BEFORE the delta is parsed, because the parse now depends on\n      // it: a requirement's markdown links are relative to the file they were\n      // written in, and this merge moves the text two directories up the tree.\n      // `core/links/parse.ts`'s `rebaseLinks` states the defect; the ordering\n      // here is what lets the fix see both ends of the move, including a\n      // service filed under a subsystem, whose living directory is deeper still.\n      const deltaReqs = parseRequirements(\n        rebaseLinks(await readUtf8(deltaPath), { from: dirname(deltaPath), to: dirname(livingPath) }),\n      );\n      if (!existsSync(livingPath)) {\n        // New service (or first arch spec) — create the living file from the\n        // ADDED/MODIFIED requirements.\n        const created = applyRequirementDelta([], deltaReqs);\n        if (created.length === 0) {\n          say(`  ${axis.label}: ${svc} — nothing to merge (delta leaves no requirements), no living ${axis.file} created`);\n          continue;\n        }\n        const heading = axis.key === \"spec\" ? svc : `${svc} — architecture`;\n        const frontmatter = `---\\nservice: ${svc}\\nstatus: draft\\n---\\n\\n# ${heading}\\n\\n`;\n        writes.push(planWrite(livingPath, `${frontmatter}## Requirements\\n\\n${serializeRequirements(created)}`));\n        say(`  ${axis.label}: ${svc} — created living ${axis.file} (${created.length} requirement(s))`);\n        continue;\n      }\n      const livingText = await readUtf8(livingPath);\n      // TWO `## Requirements` headings would put the rewrite's one-section\n      // invariant to a choice it must not make: the run of the first would be\n      // rewritten while the second survived verbatim in the tail — and its\n      // requirements, collected by parseRequirements, would land in the run TOO.\n      // Mechanical, like a model-less landscape, so merge-failed, not --approve.\n      const reqHeadings = sectionHeadings(livingText).filter((h) => isRequirementsHeading(h.text));\n      if (reqHeadings.length > 1) {\n        throw new ArchiveFailure(\n          \"merge-failed\",\n          `living ${axis.file} for ${svc} has ${reqHeadings.length} '## Requirements' headings (lines ${reqHeadings.map((h) => h.line).join(\", \")}) — the merge rewrites ONE requirements section and cannot choose; merge them into one, then re-run`,\n        );\n      }\n      const merged = applyRequirementDelta(parseRequirements(livingText), deltaReqs);\n      writes.push(planWrite(livingPath, rewriteRequirementsRun(livingText, merged)));\n\n      const c = summarize(deltaReqs);\n      say(`  ${axis.label}: ${svc} ← +${c.ADDED} ~${c.MODIFIED} -${c.REMOVED} (now ${merged.length} total)`);\n    }\n  }\n}\n\n/**\n * The BUSINESS corpus's merge: a feature's `capabilities/<id>/spec.md` deltas\n * applied into the living `capabilities/<id>/spec.md`.\n *\n * Here rather than in a sixth file in this package because this module already\n * owns \"requirements merged into a living document\" — it owns\n * `rewriteRequirementsRun`, the two-headings refusal and the `applyRequirementDelta`\n * call, and the business corpus needs all three unchanged. What differs from\n * `planSpecs` above is only where the living document lives and what a CREATED\n * one says at the top.\n *\n * ARCHIVE CREATES THE LIVING DOCUMENT, by exact analogy with the new-service\n * branch above. The directory IS the list on this axis (`core/capabilities/tree.ts`),\n * so an archive that merged into a file it refused to create would make the\n * whole delta merge nothing — which is the `delta.no-delta-sections` failure\n * class, arriving through the merge instead of through the grammar.\n *\n * NO FRONTMATTER on a created capability document, and that is a decision\n * rather than an omission. Nothing reads a capability document's frontmatter:\n * `readCapabilityTree` classifies by the file's PRESENCE and\n * `readCapabilityVocabulary` takes `description`/`owner` from the YAML side. A\n * `status:` field invented here would be the \"second list nothing keeps\n * current\" this axis was designed against.\n *\n * AND IT SAYS SO OUT LOUD. Creating the first `capabilities/<id>/spec.md`\n * creates `capabilities/`, which is one of the two ways a fleet opts INTO the\n * capability axis — from the next command on, `loam validate --all` grades a\n * corpus that did not exist before. A merge that changes what the whole fleet\n * is graded on must not do it silently.\n */\nexport async function planCapabilities(\n  config: { docsDir: DocsDir; fleet?: FleetContext },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const { writes } = plan;\n  // Whether `capabilities/` exists is asked BEFORE the loop, because the loop\n  // is what would create it; `creating` records whether this run actually\n  // materialises a document, so the adoption line below is not printed by a\n  // run whose every capability delta merged into a document already there.\n  const adopting = !existsSync(capabilityDocsDir(config.docsDir));\n  let creating = false;\n  for (const doc of gated.capabilityDeltas) {\n    const livingPath = livingCapabilityPaths(config.docsDir, doc.id).spec;\n    // Same move, same rewrite: `features/<FEAT>/capabilities/<id>/` is two\n    // directories deeper than `capabilities/<id>/`, so a citation of a glossary\n    // term or an ADR would land pointing above the repository.\n    const deltaReqs = parseRequirements(\n      rebaseLinks(await readUtf8(doc.spec), { from: dirname(doc.spec), to: dirname(livingPath) }),\n    );\n    if (!existsSync(livingPath)) {\n      const created = applyRequirementDelta([], deltaReqs);\n      if (created.length === 0) {\n        say(`  capability: ${doc.id} — nothing to merge (delta leaves no requirements), no living spec.md created`);\n        continue;\n      }\n      // The heading is the id and nothing else. loam merges requirements and\n      // never prose, so it must not fabricate the narrative that is the whole\n      // point of the document — the line below tells the author it is theirs.\n      writes.push(planWrite(livingPath, `# ${doc.id}\\n\\n## Requirements\\n\\n${serializeRequirements(created)}`));\n      creating = true;\n      say(`  capability: ${doc.id} — created capabilities/${doc.id}/spec.md (${created.length} requirement(s))`);\n      say(`      write the narrative above '## Requirements' — loam merges requirements, not prose`);\n      continue;\n    }\n    const livingText = await readUtf8(livingPath);\n    // The same one-section invariant as the service axis above, and the same\n    // reason it cannot be guessed at.\n    const reqHeadings = sectionHeadings(livingText).filter((h) => isRequirementsHeading(h.text));\n    if (reqHeadings.length > 1) {\n      throw new ArchiveFailure(\n        \"merge-failed\",\n        `living capabilities/${doc.id}/spec.md has ${reqHeadings.length} '## Requirements' headings (lines ${reqHeadings.map((h) => h.line).join(\", \")}) — the merge rewrites ONE requirements section and cannot choose; merge them into one, then re-run`,\n      );\n    }\n    const merged = applyRequirementDelta(parseRequirements(livingText), deltaReqs);\n    writes.push(planWrite(livingPath, rewriteRequirementsRun(livingText, merged)));\n    const c = summarize(deltaReqs);\n    say(`  capability: ${doc.id} ← +${c.ADDED} ~${c.MODIFIED} -${c.REMOVED} (now ${merged.length} total)`);\n  }\n  if (adopting && creating) {\n    say(`  capabilities/ did not exist — this archive opts the fleet into the business axis, and \\`loam validate --all\\` grades it from now on`);\n  }\n}\n\n/**\n * Rewrite ONLY the requirements run of a living spec. Byte-for-byte preserved:\n * everything before the first requirement inside `## Requirements` (the intro,\n * the heading line, prose under the heading) and everything from the section's\n * end onward (the next `## ` heading to EOF) — the old cut was a substring\n * `indexOf(\"\\n## Requirements\")`, a prefix match that also hit\n * `## Requirements Extra` and silently destroyed every section after the\n * requirements. Prose BETWEEN requirements is body text of whatever is open\n * above it (parseRequirements attributes it to the previous requirement's last\n * scenario, or its text) and survives inside the re-serialized run, framing\n * normalized. `merged` must contain every living requirement — runArchive's\n * stray guard refuses any document whose requirements sit outside the section,\n * using the same heading definition, before this output is ever written.\n */\nfunction rewriteRequirementsRun(text: string, merged: Requirement[]): string {\n  const s = splitRequirementsSection(text);\n  // No `## Requirements` at all: the stray guard has already refused any doc\n  // whose requirements live elsewhere, so this one has none — open the section.\n  if (s === null) return `${text.trimEnd()}\\n\\n## Requirements\\n\\n${serializeRequirements(merged)}`;\n  const body = serializeRequirements(merged);\n  // head/tail are raw slices; only the run's own framing is normalized. When\n  // the section held no requirements yet, the glue supplies the blank line the\n  // author never had reason to write.\n  const headGlue = s.run !== \"\" || s.head.endsWith(\"\\n\\n\") ? \"\" : s.head.endsWith(\"\\n\") ? \"\\n\" : \"\\n\\n\";\n  const tailGlue = s.tail === \"\" ? \"\" : \"\\n\";\n  return s.head + headGlue + body + tailGlue + s.tail;\n}\n\nfunction summarize(reqs: Requirement[]): { ADDED: number; MODIFIED: number; REMOVED: number } {\n  const c = { ADDED: 0, MODIFIED: 0, REMOVED: 0 };\n  for (const r of reqs) {\n    if (r.kind === \"ADDED\") c.ADDED += 1;\n    else if (r.kind === \"MODIFIED\") c.MODIFIED += 1;\n    else if (r.kind === \"REMOVED\") c.REMOVED += 1;\n  }\n  return c;\n}\n\n/**\n * The vocabulary merge: each `features/<FEAT>/glossary/<term>.md` copied to\n * `glossary/<term>.md`.\n *\n * A WHOLE-FILE COPY, and there is nothing else it could be. A capability delta\n * is folded into a living document by the requirement algebra because the two\n * documents share identified parts; a term document has one part, and merging\n * two definitions of one word is not something a machine may attempt. So the\n * definition the author wrote in the feature IS the definition that lands,\n * verbatim — loam re-encodes it as UTF-8 through `readUtf8` and changes nothing\n * else, not even the trailing newline.\n *\n * CREATE-ONLY, which is why this loop has no other branch. A term the living\n * glossary already defines was refused at the gate (`glossary.term-exists`,\n * `core/glossary/delta.ts` has the reasoning), so by the time the plan runs\n * every path here is a file that does not exist. `planWrite` marks it\n * `exclusive`, so a race that created it between the gate and the commit fails\n * the write rather than overwriting somebody.\n *\n * AND IT SAYS SO OUT LOUD when it creates `glossary/`, exactly as\n * `planCapabilities` does for `capabilities/`: the directory's existence is the\n * axis's opt-in, so this merge changes what `loam validate --all` grades from\n * the next command on, and a merge that widens the fleet's own gate must not do\n * it silently.\n */\nexport async function planGlossary(\n  config: { docsDir: DocsDir },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const glossary = await featureGlossary(gated.featureDir);\n  if (!glossary.present || glossary.terms.length === 0) return;\n  // Asked BEFORE the loop, because the loop is what would create it.\n  const adopting = !existsSync(glossaryDir(config.docsDir));\n  for (const term of glossary.terms) {\n    plan.writes.push(planWrite(livingTermPath(config.docsDir, term.id), await readUtf8(term.path)));\n    say(`  glossary: ${term.id} — created glossary/${term.id}.md`);\n  }\n  if (adopting) {\n    say(`  glossary/ did not exist — this archive opts the fleet into the domain vocabulary, and \\`loam validate --all\\` grades it from now on`);\n  }\n}\n"]}
+{"version":3,"file":"specs.js","sourceRoot":"","sources":["../../../../src/commands/archive/plan/specs.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The requirements merge: the feature's ADDED/MODIFIED/REMOVED requirements\n * applied into each living service spec. The contract merges live beside it in\n * `./contracts/` — one file per axis, split out when the OpenAPI half made\n * this one carry two merges.\n *\n * ONE code path for the pair of requirement-carrying files — the business\n * spec.md and the architecture arch.spec.md ride the same delta algebra, the\n * same prose-preserving rewrite and the same guards, parameterized by filename.\n * A fork here would be two places the merge could disagree.\n *\n * Nothing is written. Everything lands in the `Plan`, so a failure on any axis\n * leaves the living docs exactly as they were.\n */\nimport { existsSync } from \"node:fs\";\nimport { dirname } from \"node:path\";\nimport { rebaseLinks } from \"../../../core/links/parse.js\";\nimport { planWrite, readUtf8 } from \"../../../core/staging/writes.js\";\nimport { featureSpecPaths, SPEC_AXES } from \"../../../core/repo/paths.js\";\nimport { capabilityDocsDir, glossaryDir, livingCapabilityPaths } from \"../../../core/repo/authored/paths.js\";\nimport { featureGlossary, livingTermPath } from \"../../../core/glossary/delta.js\";\nimport { locateServicePaths } from \"../../../core/repo/service-target.js\";\nimport {\n  isRequirementsHeading,\n  parseRequirements,\n  sectionHeadings,\n  splitRequirementsSection,\n} from \"../../../core/document/parse.js\";\nimport { applyRequirementDelta } from \"../../../core/document/apply.js\";\nimport { serializeRequirements, type Requirement } from \"../../../core/document/spec.js\";\nimport { movedUnderVouch, parseFrontmatter, stringField } from \"../../../core/document/frontmatter.js\";\nimport { CodedFailure } from \"../../../core/envelope/json.js\";\nimport { type Gated, type Plan } from \"./state.js\";\nimport type { DocsDir } from \"../../../core/kernel/ids/dirs.js\";\nimport type { FleetContext } from \"../../../core/fleet-context.js\";\n\nexport async function planSpecs(\n  config: { docsDir: DocsDir; fleet: FleetContext },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const { featureDir, deltaServices } = gated;\n  const { writes } = plan;\n  // Requirements merge — apply ADDED/MODIFIED/REMOVED into each living service\n  // spec. ONE code path for the pair of requirement-carrying files: the business\n  // spec.md and the architecture arch.spec.md ride the same delta algebra, the\n  // same prose-preserving rewrite and the same guards, parameterized by filename\n  // (SPEC_AXES) — a fork here would be two places the merge could disagree.\n  for (const svc of deltaServices) {\n    for (const axis of SPEC_AXES) {\n      const deltaPath = featureSpecPaths(featureDir, svc)[axis.key];\n      if (!existsSync(deltaPath)) continue;\n\n      // The shared context: this is a deltaServices × SPEC_AXES loop, and a\n      // context-less locate is a full fleet walk per iteration.\n      const livingPath = (await locateServicePaths(config.docsDir, svc, config.fleet))[axis.key];\n      // Resolved BEFORE the delta is parsed, because the parse now depends on\n      // it: a requirement's markdown links are relative to the file they were\n      // written in, and this merge moves the text two directories up the tree.\n      // `core/links/parse.ts`'s `rebaseLinks` states the defect; the ordering\n      // here is what lets the fix see both ends of the move, including a\n      // service filed under a subsystem, whose living directory is deeper still.\n      const deltaReqs = parseRequirements(\n        rebaseLinks(await readUtf8(deltaPath), { from: dirname(deltaPath), to: dirname(livingPath) }),\n      );\n      if (!existsSync(livingPath)) {\n        // New service (or first arch spec) — create the living file from the\n        // ADDED/MODIFIED requirements.\n        const created = applyRequirementDelta([], deltaReqs);\n        if (created.length === 0) {\n          say(`  ${axis.label}: ${svc} — nothing to merge (delta leaves no requirements), no living ${axis.file} created`);\n          continue;\n        }\n        const heading = axis.key === \"spec\" ? svc : `${svc} — architecture`;\n        const frontmatter = `---\\nservice: ${svc}\\nstatus: draft\\n---\\n\\n# ${heading}\\n\\n`;\n        writes.push(planWrite(livingPath, `${frontmatter}## Requirements\\n\\n${serializeRequirements(created)}`));\n        say(`  ${axis.label}: ${svc} — created living ${axis.file} (${created.length} requirement(s))`);\n        continue;\n      }\n      const livingText = await readUtf8(livingPath);\n      // TWO `## Requirements` headings would put the rewrite's one-section\n      // invariant to a choice it must not make: the run of the first would be\n      // rewritten while the second survived verbatim in the tail — and its\n      // requirements, collected by parseRequirements, would land in the run TOO.\n      // Mechanical, like a model-less landscape, so merge-failed, not --approve.\n      const reqHeadings = sectionHeadings(livingText).filter((h) => isRequirementsHeading(h.text));\n      if (reqHeadings.length > 1) {\n        throw new CodedFailure(\n          \"merge-failed\",\n          `living ${axis.file} for ${svc} has ${reqHeadings.length} '## Requirements' headings (lines ${reqHeadings.map((h) => h.line).join(\", \")}) — the merge rewrites ONE requirements section and cannot choose; merge them into one, then re-run`,\n        );\n      }\n      const livingReqs = parseRequirements(livingText);\n      const merged = applyRequirementDelta(livingReqs, deltaReqs);\n      const next = rewriteRequirementsRun(livingText, livingReqs, merged);\n      writes.push(planWrite(livingPath, next));\n      // A merge is an edit to the document's body like any other, so a vouched\n      // spec it moves goes `content.stale` — and honestly: the merged text is\n      // words no person has yet read against the code. Archive does not soften\n      // that. It names the document and its owner, so the re-vouch is known to\n      // be owed while the merge is still a PR rather than discovered later as a\n      // red `--strict` gate. Asked of the bytes about to be written, through the\n      // one definition validate grades with.\n      const fm = parseFrontmatter(next);\n      if (movedUnderVouch(fm, next)) {\n        plan.revouchOwed.push({ service: svc, path: livingPath, owner: stringField(fm, \"owner\") ?? null });\n      }\n\n      const c = summarize(deltaReqs);\n      say(`  ${axis.label}: ${svc} ← +${c.ADDED} ~${c.MODIFIED} -${c.REMOVED} (now ${merged.length} total)`);\n    }\n  }\n}\n\n/**\n * The BUSINESS corpus's merge: a feature's `capabilities/<id>/spec.md` deltas\n * applied into the living `capabilities/<id>/spec.md`.\n *\n * Here rather than in a sixth file in this package because this module already\n * owns \"requirements merged into a living document\" — it owns\n * `rewriteRequirementsRun`, the two-headings refusal and the `applyRequirementDelta`\n * call, and the business corpus needs all three unchanged. What differs from\n * `planSpecs` above is only where the living document lives and what a CREATED\n * one says at the top.\n *\n * ARCHIVE CREATES THE LIVING DOCUMENT, by exact analogy with the new-service\n * branch above. The directory IS the list on this axis (`core/capabilities/tree.ts`),\n * so an archive that merged into a file it refused to create would make the\n * whole delta merge nothing — which is the `delta.no-delta-sections` failure\n * class, arriving through the merge instead of through the grammar.\n *\n * NO FRONTMATTER on a created capability document, and that is a decision\n * rather than an omission. Nothing reads a capability document's frontmatter:\n * `readCapabilityTree` classifies by the file's PRESENCE and\n * `readCapabilityVocabulary` takes `description`/`owner` from the YAML side. A\n * `status:` field invented here would be the \"second list nothing keeps\n * current\" this axis was designed against.\n *\n * AND IT SAYS SO OUT LOUD. Creating the first `capabilities/<id>/spec.md`\n * creates `capabilities/`, which is one of the two ways a fleet opts INTO the\n * capability axis — from the next command on, `loam validate --all` grades a\n * corpus that did not exist before. A merge that changes what the whole fleet\n * is graded on must not do it silently.\n */\nexport async function planCapabilities(\n  config: { docsDir: DocsDir; fleet: FleetContext },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const { writes } = plan;\n  // Whether `capabilities/` exists is asked BEFORE the loop, because the loop\n  // is what would create it; `creating` records whether this run actually\n  // materialises a document, so the adoption line below is not printed by a\n  // run whose every capability delta merged into a document already there.\n  const adopting = !existsSync(capabilityDocsDir(config.docsDir));\n  let creating = false;\n  for (const doc of gated.capabilityDeltas) {\n    const livingPath = livingCapabilityPaths(config.docsDir, doc.id).spec;\n    // Same move, same rewrite: `features/<FEAT>/capabilities/<id>/` is two\n    // directories deeper than `capabilities/<id>/`, so a citation of a glossary\n    // term or an ADR would land pointing above the repository.\n    const deltaReqs = parseRequirements(\n      rebaseLinks(await readUtf8(doc.spec), { from: dirname(doc.spec), to: dirname(livingPath) }),\n    );\n    if (!existsSync(livingPath)) {\n      const created = applyRequirementDelta([], deltaReqs);\n      if (created.length === 0) {\n        say(`  capability: ${doc.id} — nothing to merge (delta leaves no requirements), no living spec.md created`);\n        continue;\n      }\n      // The heading is the id and nothing else. loam merges requirements and\n      // never prose, so it must not fabricate the narrative that is the whole\n      // point of the document — the line below tells the author it is theirs.\n      writes.push(planWrite(livingPath, `# ${doc.id}\\n\\n## Requirements\\n\\n${serializeRequirements(created)}`));\n      creating = true;\n      say(`  capability: ${doc.id} — created capabilities/${doc.id}/spec.md (${created.length} requirement(s))`);\n      say(`      write the narrative above '## Requirements' — loam merges requirements, not prose`);\n      continue;\n    }\n    const livingText = await readUtf8(livingPath);\n    // The same one-section invariant as the service axis above, and the same\n    // reason it cannot be guessed at.\n    const reqHeadings = sectionHeadings(livingText).filter((h) => isRequirementsHeading(h.text));\n    if (reqHeadings.length > 1) {\n      throw new CodedFailure(\n        \"merge-failed\",\n        `living capabilities/${doc.id}/spec.md has ${reqHeadings.length} '## Requirements' headings (lines ${reqHeadings.map((h) => h.line).join(\", \")}) — the merge rewrites ONE requirements section and cannot choose; merge them into one, then re-run`,\n      );\n    }\n    const livingReqs = parseRequirements(livingText);\n    const merged = applyRequirementDelta(livingReqs, deltaReqs);\n    writes.push(planWrite(livingPath, rewriteRequirementsRun(livingText, livingReqs, merged)));\n    const c = summarize(deltaReqs);\n    say(`  capability: ${doc.id} ← +${c.ADDED} ~${c.MODIFIED} -${c.REMOVED} (now ${merged.length} total)`);\n  }\n  if (adopting && creating) {\n    say(`  capabilities/ did not exist — this archive opts the fleet into the business axis, and \\`loam validate --all\\` grades it from now on`);\n  }\n}\n\n/**\n * Rewrite ONLY what the delta touched inside a living spec's requirements run.\n * Byte-for-byte preserved: everything before the first requirement inside\n * `## Requirements` (the intro, the heading line, prose under the heading) and\n * everything from the section's end onward (the next `## ` heading to EOF) —\n * the old cut was a substring `indexOf(\"\\n## Requirements\")`, a prefix match\n * that also hit `## Requirements Extra` and silently destroyed every section\n * after the requirements. `living` must be every living requirement — the gate's\n * stray guard refuses any document whose requirements sit outside the section,\n * using the same heading definition, before this output is ever written.\n *\n * Inside the run the unit is one requirement, and an untouched one is written\n * back as its raw slice (`spliceRun`). The whole run used to be re-serialized,\n * and `serializeRequirements` writes a blank line under every\n * `### Requirement:` heading — so a living spec written without one, the shape\n * the adopt brief's own examples taught, had that line inserted under every\n * requirement the feature never mentioned. The diff, the vouch pack and the\n * re-vouch all widened from the delta to the whole section.\n *\n * Exported for test/archive.test.ts alone: the slice-to-requirement join\n * (`verbatimSlices`) can only be handed a disagreeing pair directly, because\n * the gate refuses every document that would produce one through the CLI.\n */\nexport function rewriteRequirementsRun(text: string, living: Requirement[], merged: Requirement[]): string {\n  const s = splitRequirementsSection(text);\n  // No `## Requirements` at all: the stray guard has already refused any doc\n  // whose requirements live elsewhere, so this one has none — open the section.\n  if (s === null) return `${text.trimEnd()}\\n\\n## Requirements\\n\\n${serializeRequirements(merged)}`;\n  if (s.run !== \"\") return s.head + spliceRun(s, living, merged) + s.tail;\n  // The section held no requirements yet: head and tail are raw slices, and the\n  // glue supplies the blank lines the author never had reason to write.\n  const headGlue = s.head.endsWith(\"\\n\\n\") ? \"\" : s.head.endsWith(\"\\n\") ? \"\\n\" : \"\\n\\n\";\n  const tailGlue = s.tail === \"\" ? \"\" : \"\\n\";\n  return s.head + headGlue + serializeRequirements(merged) + tailGlue + s.tail;\n}\n\n/** The line breaks (and blank lines) a slice ends with — what separates it from whatever follows. */\nconst TRAILING_BREAKS = /(?:\\r?\\n[ \\t]*)*$/;\n\n/**\n * The merged run: every living requirement the delta left alone as its raw\n * slice, every one it added or replaced serialized, in `merged`'s order.\n *\n * Keyed on object identity, which `applyRequirementDelta` keeps for exactly the\n * requirements it did not touch — so there is no second reading here of what\n * the delta changed, and no way for the splice and the algebra to disagree.\n * Which slice belongs to which living requirement is `verbatimSlices`' join.\n *\n * Prose BETWEEN requirements rides in the slice of the requirement above it,\n * which is where parseRequirements attributes it too: it survives verbatim\n * beside an untouched requirement and goes with a replaced one, as it always\n * did — a MODIFIED carries its full new text.\n */\nfunction spliceRun(\n  section: { run: string; requirements: string[] },\n  living: Requirement[],\n  merged: Requirement[],\n): string {\n  const verbatim = verbatimSlices(section.requirements, living);\n  let out = \"\";\n  let previousVerbatim = true;\n  for (const requirement of merged) {\n    const raw = verbatim.get(requirement);\n    // Two untouched neighbours keep whatever the author put between them. Next\n    // to a serialized requirement the canonical blank line is ADDED after the\n    // untouched text, never by rewriting it.\n    if (out !== \"\" && (raw === undefined || !previousVerbatim)) out = withBlankLine(out);\n    out += raw ?? serializeRequirements([requirement]);\n    previousVerbatim = raw !== undefined;\n  }\n  if (out === \"\") return \"\";\n  // The run ends as it ended: whatever separated the old last requirement from\n  // the next heading (or EOF) now follows the new last one — and at least a\n  // newline when a merged requirement lands where the file used to stop without one.\n  const ending = section.run.slice(section.run.search(TRAILING_BREAKS));\n  const body = out.slice(0, out.search(TRAILING_BREAKS));\n  return body + (ending === \"\" && merged.at(-1) !== living.at(-1) ? \"\\n\" : ending);\n}\n\n/** A requirement's identity as the merge selects it: `Requirement-ID:` when authored, the exact heading otherwise. */\nconst identity = (r: Pick<Requirement, \"id\" | \"name\">): string => (r.id === undefined ? `name:${r.name}` : `id:${r.id}`);\n\n/**\n * Each living requirement's raw slice, joined on its IDENTITY — the slice read\n * back through the same parser that produced `living`, so a slice can only\n * land in place of the requirement it actually is.\n *\n * The join used to be by position, guarded by a count. The two walks agree in\n * order today (one heading-and-fence definition, core/document/parse.ts, and\n * the gate's stray guard refusing any requirement outside the section), but\n * nothing declared that, and equal counts paired differently would have written\n * one requirement's bytes where another belongs — under its vouch stamp, with\n * nothing to say so.\n *\n * Fails closed to the empty map, which serializes every requirement — the old\n * whole-run rewrite, still a correct merge and only a wider diff: when the\n * counts differ, when a slice does not read as exactly one requirement, when\n * two slices claim one identity, or when a living requirement finds no slice\n * of its own.\n */\nfunction verbatimSlices(slices: string[], living: Requirement[]): Map<Requirement, string> {\n  const none = new Map<Requirement, string>();\n  if (slices.length !== living.length) return none;\n  const byIdentity = new Map<string, string>();\n  for (const slice of slices) {\n    const [only, ...more] = parseRequirements(slice);\n    if (only === undefined || more.length > 0 || byIdentity.has(identity(only))) return none;\n    byIdentity.set(identity(only), slice);\n  }\n  const verbatim = new Map<Requirement, string>();\n  for (const requirement of living) {\n    const slice = byIdentity.get(identity(requirement));\n    if (slice === undefined) return none;\n    // Taken once: a second living requirement of the same identity finds nothing.\n    byIdentity.delete(identity(requirement));\n    verbatim.set(requirement, slice);\n  }\n  return verbatim;\n}\n\n/** `text` ending in a blank line: line breaks appended to make one, nothing rewritten. */\nfunction withBlankLine(text: string): string {\n  const breaks = text.slice(text.search(TRAILING_BREAKS)).split(\"\\n\").length - 1;\n  return breaks >= 2 ? text : text + \"\\n\".repeat(2 - breaks);\n}\n\nfunction summarize(reqs: Requirement[]): { ADDED: number; MODIFIED: number; REMOVED: number } {\n  const c = { ADDED: 0, MODIFIED: 0, REMOVED: 0 };\n  for (const r of reqs) {\n    if (r.kind === \"ADDED\") c.ADDED += 1;\n    else if (r.kind === \"MODIFIED\") c.MODIFIED += 1;\n    else if (r.kind === \"REMOVED\") c.REMOVED += 1;\n  }\n  return c;\n}\n\n/**\n * The vocabulary merge: each `features/<FEAT>/glossary/<term>.md` copied to\n * `glossary/<term>.md`.\n *\n * A WHOLE-FILE COPY, and there is nothing else it could be. A capability delta\n * is folded into a living document by the requirement algebra because the two\n * documents share identified parts; a term document has one part, and merging\n * two definitions of one word is not something a machine may attempt. So the\n * definition the author wrote in the feature IS the definition that lands,\n * verbatim — loam re-encodes it as UTF-8 through `readUtf8` and changes nothing\n * else, not even the trailing newline.\n *\n * CREATE-ONLY, which is why this loop has no other branch. A term the living\n * glossary already defines was refused at the gate (`glossary.term-exists`,\n * `core/glossary/delta.ts` has the reasoning), so by the time the plan runs\n * every path here is a file that does not exist. `planWrite` marks it\n * `exclusive`, so a race that created it between the gate and the commit fails\n * the write rather than overwriting somebody.\n *\n * AND IT SAYS SO OUT LOUD when it creates `glossary/`, exactly as\n * `planCapabilities` does for `capabilities/`: the directory's existence is the\n * axis's opt-in, so this merge changes what `loam validate --all` grades from\n * the next command on, and a merge that widens the fleet's own gate must not do\n * it silently.\n */\nexport async function planGlossary(\n  config: { docsDir: DocsDir },\n  gated: Gated,\n  plan: Plan,\n  say: (line?: string) => void,\n): Promise<void> {\n  const glossary = await featureGlossary(gated.featureDir);\n  if (!glossary.present || glossary.terms.length === 0) return;\n  // Asked BEFORE the loop, because the loop is what would create it.\n  const adopting = !existsSync(glossaryDir(config.docsDir));\n  for (const term of glossary.terms) {\n    plan.writes.push(planWrite(livingTermPath(config.docsDir, term.id), await readUtf8(term.path)));\n    say(`  glossary: ${term.id} — created glossary/${term.id}.md`);\n  }\n  if (adopting) {\n    say(`  glossary/ did not exist — this archive opts the fleet into the domain vocabulary, and \\`loam validate --all\\` grades it from now on`);\n  }\n}\n"]}

package/dist/commands/archive/plan/state.js

@@ -22,6 +22,7 @@ export function emptyPlan() {
         openapiRemovals: [],
         asyncapiRemovals: [],
         architectureServices: new Set(),
+        revouchOwed: [],
     };
 }
 //# sourceMappingURL=state.js.map

package/dist/commands/archive/plan/state.js.map

@@ -1 +1 @@
-{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../../src/commands/archive/plan/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAc,MAAM,mCAAmC,CAAC;AAC/D,OAAO,EAAqB,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAmB,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAwB,MAAM,qCAAqC,CAAC;AAC3E,OAAO,EAAkB,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAsB,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAuB,MAAM,sCAAsC,CAAC;AA6C3E,MAAM,UAAU,SAAS;IACvB,OAAO;QACL,MAAM,EAAE,EAAE;QACV,SAAS,EAAE,EAAE;QACb,SAAS,EAAE,EAAE;QACb,eAAe,EAAE,EAAE;QACnB,gBAAgB,EAAE,EAAE;QACpB,oBAAoB,EAAE,IAAI,GAAG,EAAmB;KACjD,CAAC;AACJ,CAAC","sourcesContent":["/**\n * What one phase of an archive hands the next.\n *\n * `Gated` is everything the refusals resolved on the way through — the\n * canonical id, the delta document parsed once, the issue lists. `Plan` is what\n * the merges accumulate. Neither is a bag of conveniences: a value is in here\n * exactly when two phases have to agree about it, and the alternative was\n * fifteen parameters threaded through three functions in the same order.\n */\nimport { type Issue } from \"../../../core/vocabulary/issue.js\";\nimport { type PlannedWrite } from \"../../../core/staging/writes.js\";\nimport { type FeatureDir } from \"../../../core/kernel/ids/dirs.js\";\nimport { type PathableService } from \"../../../core/kernel/ids/service.js\";\nimport { type LoadedDoc } from \"../../../core/c4/likec4.js\";\nimport { type CapabilityDoc } from \"../../../core/capabilities/tree.js\";\nimport { type CommitRecovery } from \"../../../core/staging/interrupted.js\";\n\nexport interface Gated {\n  /** The canonical feature id. The raw argument does not survive the gate. */\n  id: string;\n  dirName: string;\n  featureDir: FeatureDir;\n  /** Parsed ONCE for the whole run — loading it spins up a fresh Langium workspace. */\n  deltaDoc: LoadedDoc | undefined;\n  deltaServices: PathableService[];\n  /**\n   * The capability documents this feature's delta carries, walked ONCE in the\n   * gate. Three phases downstream ask about them — the conflict-marker scan,\n   * the strayed-requirement scan and the merge — and a second walk is a second\n   * chance to disagree about which capabilities the merge touches.\n   */\n  capabilityDeltas: CapabilityDoc[];\n  gating: Issue[];\n  advisory: Issue[];\n  archiveDir: string;\n  archiveDest: string;\n  /** The interrupted commit this run repaired, if any — `--json` reports it. */\n  recovered: CommitRecovery | null;\n  /** Every coherence issue the gate read, gating and advisory together. */\n  issues: Issue[];\n}\n\nexport interface Plan {\n  writes: PlannedWrite[];\n  /**\n   * Warnings born in the plan itself (openapi.op-modified,\n   * openapi.component-modified, the asyncapi.*-modified trio) — printed with\n   * the plan and carried into the `--json` envelope beside the coherence\n   * warnings.\n   */\n  planWarns: Issue[];\n  /** Gating issues born in the plan itself (openapi.ref-unresolved, asyncapi.ref-unresolved). */\n  planGates: Issue[];\n  openapiRemovals: Array<{ service: string; operations: string[] }>;\n  /** Living asyncapi slots the plan deletes on removal markers, by their labels. */\n  asyncapiRemovals: Array<{ service: string; slots: string[] }>;\n  /** Services this feature introduces on the architecture axis alone. */\n  architectureServices: Set<PathableService>;\n}\n\nexport function emptyPlan(): Plan {\n  return {\n    writes: [],\n    planWarns: [],\n    planGates: [],\n    openapiRemovals: [],\n    asyncapiRemovals: [],\n    architectureServices: new Set<PathableService>(),\n  };\n}\n"]}
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../../src/commands/archive/plan/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EAAc,MAAM,mCAAmC,CAAC;AAC/D,OAAO,EAAqB,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAmB,MAAM,kCAAkC,CAAC;AACnE,OAAO,EAAwB,MAAM,qCAAqC,CAAC;AAC3E,OAAO,EAAkB,MAAM,4BAA4B,CAAC;AAC5D,OAAO,EAAsB,MAAM,oCAAoC,CAAC;AACxE,OAAO,EAAuB,MAAM,sCAAsC,CAAC;AAqD3E,MAAM,UAAU,SAAS;IACvB,OAAO;QACL,MAAM,EAAE,EAAE;QACV,SAAS,EAAE,EAAE;QACb,SAAS,EAAE,EAAE;QACb,eAAe,EAAE,EAAE;QACnB,gBAAgB,EAAE,EAAE;QACpB,oBAAoB,EAAE,IAAI,GAAG,EAAmB;QAChD,WAAW,EAAE,EAAE;KAChB,CAAC;AACJ,CAAC","sourcesContent":["/**\n * What one phase of an archive hands the next.\n *\n * `Gated` is everything the refusals resolved on the way through — the\n * canonical id, the delta document parsed once, the issue lists. `Plan` is what\n * the merges accumulate. Neither is a bag of conveniences: a value is in here\n * exactly when two phases have to agree about it, and the alternative was\n * fifteen parameters threaded through three functions in the same order.\n */\nimport { type Issue } from \"../../../core/vocabulary/issue.js\";\nimport { type PlannedWrite } from \"../../../core/staging/writes.js\";\nimport { type FeatureDir } from \"../../../core/kernel/ids/dirs.js\";\nimport { type PathableService } from \"../../../core/kernel/ids/service.js\";\nimport { type LoadedDoc } from \"../../../core/c4/likec4.js\";\nimport { type CapabilityDoc } from \"../../../core/capabilities/tree.js\";\nimport { type CommitRecovery } from \"../../../core/staging/interrupted.js\";\n\nexport interface Gated {\n  /** The canonical feature id. The raw argument does not survive the gate. */\n  id: string;\n  dirName: string;\n  featureDir: FeatureDir;\n  /** Parsed ONCE for the whole run — loading it spins up a fresh Langium workspace. */\n  deltaDoc: LoadedDoc | undefined;\n  deltaServices: PathableService[];\n  /**\n   * The capability documents this feature's delta carries, walked ONCE in the\n   * gate. Three phases downstream ask about them — the conflict-marker scan,\n   * the strayed-requirement scan and the merge — and a second walk is a second\n   * chance to disagree about which capabilities the merge touches.\n   */\n  capabilityDeltas: CapabilityDoc[];\n  gating: Issue[];\n  advisory: Issue[];\n  archiveDir: string;\n  archiveDest: string;\n  /** The interrupted commit this run repaired, if any — `--json` reports it. */\n  recovered: CommitRecovery | null;\n  /** Every coherence issue the gate read, gating and advisory together. */\n  issues: Issue[];\n}\n\nexport interface Plan {\n  writes: PlannedWrite[];\n  /**\n   * Warnings born in the plan itself (openapi.op-modified,\n   * openapi.component-modified, the asyncapi.*-modified trio) — printed with\n   * the plan and carried into the `--json` envelope beside the coherence\n   * warnings.\n   */\n  planWarns: Issue[];\n  /** Gating issues born in the plan itself (openapi.ref-unresolved, asyncapi.ref-unresolved). */\n  planGates: Issue[];\n  openapiRemovals: Array<{ service: string; operations: string[] }>;\n  /** Living asyncapi slots the plan deletes on removal markers, by their labels. */\n  asyncapiRemovals: Array<{ service: string; slots: string[] }>;\n  /** Services this feature introduces on the architecture axis alone. */\n  architectureServices: Set<PathableService>;\n  /**\n   * Every vouched living spec this merge leaves out of step with its vouch\n   * stamp — `content.stale` follows on each until its owner re-vouches.\n   * `path` is absolute, like every planned write's, and made docs-relative\n   * where it is printed; `owner` is the frontmatter's, or null when the\n   * document names none. The `--json` payload carries it as `revouchOwed`.\n   */\n  revouchOwed: Array<{ service: string; path: string; owner: string | null }>;\n}\n\nexport function emptyPlan(): Plan {\n  return {\n    writes: [],\n    planWarns: [],\n    planGates: [],\n    openapiRemovals: [],\n    asyncapiRemovals: [],\n    architectureServices: new Set<PathableService>(),\n    revouchOwed: [],\n  };\n}\n"]}

package/dist/commands/archive/run.js

@@ -10,10 +10,11 @@
  */
 import { existsSync } from "node:fs";
 import { mkdir, rename } from "node:fs/promises";
-import { emitJson, repoPath, sayExplain } from "../../core/envelope/json.js";
+import { CodedFailure, emitJson, repoPath, sayExplain } from "../../core/envelope/json.js";
 import { message, quietPruneEmptyParents, quietRm, rollbackError, rollbackStaged, stageWrites, swapStaged, } from "../../core/staging/commit.js";
 import { clearCommitIntent, writeCommitIntent } from "../../core/staging/recovery/intent.js";
-import { SNAPSHOT_DIR, SnapshotClobberError, snapshotDir, writeSnapshot, } from "../../core/staging/snapshot.js";
+import { SNAPSHOT_DIR, snapshotDir } from "../../core/staging/snapshot/manifest.js";
+import { SnapshotClobberError, writeSnapshot } from "../../core/staging/snapshot/snapshot.js";
 import { enumeratedServices } from "../../core/repo/service-target.js";
 import { listFleetTree } from "../../core/repo/repo.js";
 import { serviceViewsPath, subsystemViewsPath } from "../../core/repo/paths.js";
@@ -21,15 +22,14 @@ import { serviceViewsState, viewsState } from "../../core/repo/tree/render/stale
 import { loadArchitecture } from "../../core/c4/project/architecture.js";
 import { FleetContext } from "../../core/fleet-context.js";
 import { gate } from "./plan/gate.js";
-import {} from "./plan/refusal.js";
+import { issueJson, printPlan, refuseJson } from "./plan/refusal.js";
 import { planCapabilities, planGlossary, planSpecs } from "./plan/specs.js";
 import { planOpenapiContracts } from "./plan/contracts/openapi.js";
 import { planAsyncapiContracts } from "./plan/contracts/asyncapi.js";
+import { contractConsumers } from "./plan/contracts/consumers.js";
 import { planDeployments, planFlows, planLandscape } from "./plan/landscape.js";
 import { emptyPlan } from "./plan/state.js";
-import { issueJson, refuseJson } from "./plan/refusal.js";
-import { ArchiveFailure } from "./plan/refusal.js";
-import { printPlan } from "./plan/refusal.js";
+import { checklistAtArchive } from "./shipped.js";
 export async function archiveLocked(config, featureId, opts) {
     const dryRun = opts.dryRun === true;
     const json = opts.json === true;
@@ -63,8 +63,12 @@ export async function archiveLocked(config, featureId, opts) {
     // a create-only whole-file copy, refused at the gate if the word already
     // lives (`core/glossary/delta.ts`).
     await planGlossary(read, gated, planned, say);
-    await planOpenapiContracts(read, gated, planned, say);
-    await planAsyncapiContracts(read, gated, planned, say);
+    // One consumer index for both contract planners, built only if one of them
+    // overwrites an operation or a message (./plan/contracts/consumers.ts) —
+    // and then over the living fleet as it stands before this merge.
+    const contracts = { ...read, consumers: contractConsumers(read) };
+    await planOpenapiContracts(contracts, gated, planned, say);
+    await planAsyncapiContracts(contracts, gated, planned, say);
     // `read`, not `config`: the C4 merge now asks which services own their own
     // interior, and that answer comes from the fleet enumeration this run has
     // already paid for.
@@ -77,6 +81,7 @@ export async function archiveLocked(config, featureId, opts) {
     await planFlows(config, gated, planned, say);
     await planDeployments(config, gated, planned, say);
     const { writes, planWarns, planGates, openapiRemovals, asyncapiRemovals } = planned;
+    const revouchOwed = planned.revouchOwed.map((r) => ({ ...r, path: repoPath(config.docsDir, r.path) }));
     // Gate on what only the plan could see: a merged operation pointing at a
     // component that exists nowhere, a removal marker addressing no operation.
     // Same doctrine as the coherence gate — a judgment call --approve overrides
@@ -102,6 +107,17 @@ export async function archiveLocked(config, featureId, opts) {
         for (const i of planGates)
             say(`      ✗ ${i.message}`);
     }
+    // Printed by the dry run and the real merge alike, before either commits to
+    // anything: the merge is what moves these documents, and the merge's PR is
+    // the place their re-vouches belong. Not a finding and not a refusal — the
+    // staleness that follows is honest, and `content.stale` is what grades it.
+    if (revouchOwed.length > 0) {
+        say(`\n  re-vouch owed — this merge moves ${revouchOwed.length} vouched spec(s) under the vouch stamp, so content.stale follows on each until its owner re-vouches:`);
+        for (const r of revouchOwed) {
+            say(`    ${r.path}  (owner: ${r.owner ?? "none recorded"}) — \`loam vouch --service ${r.service}\`, run in that service's repo`);
+        }
+        say(`    land the re-vouches in this PR: \`loam validate --all --base <ref> --strict\` stays red on it until they do.`);
+    }
     // The plan as data, verb decided now — after the commit everything would read
     // as an update. The `--json` payload is identical for a dry run and the real
     // thing except for `archived`; what WOULD happen is what DOES happen.
@@ -122,6 +138,7 @@ export async function archiveLocked(config, featureId, opts) {
         overridden: overridden.map((issue) => issueJson(issue, repoPath(config.docsDir, archiveDest))),
         openapiRemovals,
         asyncapiRemovals,
+        revouchOwed,
         // Present only when this run found an interrupted commit and dealt with it:
         // an agent that sees the docs change under it deserves to be told why, and
         // the absent field is the ordinary case.
@@ -134,6 +151,10 @@ export async function archiveLocked(config, featureId, opts) {
             printPlan(config.docsDir, writes, dirName);
         return;
     }
+    // The question the feature asks as it ships, captured before anything below
+    // moves the living docs it is derived from — see ./shipped.ts. It rides in
+    // the snapshot manifest; a dry run writes no snapshot, so it pays nothing.
+    const checklist = await checklistAtArchive(read, gated);
     // COMMIT — the whole plan computed cleanly. Stage every new version beside its
     // target, snapshot what is about to be overwritten, then swap them into place.
     // Staging touches the filesystem — a read-only `architecture/`, a full disk,
@@ -145,7 +166,7 @@ export async function archiveLocked(config, featureId, opts) {
         staged = await stageWrites(writes);
     }
     catch (err) {
-        throw new ArchiveFailure("merge-failed", `${message(err)} — nothing was written`);
+        throw new CodedFailure("merge-failed", `${message(err)} — nothing was written`);
     }
     let snapshot = false;
     let createdArchiveDir;
@@ -181,6 +202,7 @@ export async function archiveLocked(config, featureId, opts) {
             staged,
             serviceKeyOf,
             serviceDirOf,
+            ...(checklist === undefined ? {} : { checklist }),
         });
         snapshot = true;
         // The journal, fsynced, BEFORE the first rename: swapStaged is N renames and
@@ -202,7 +224,7 @@ export async function archiveLocked(config, featureId, opts) {
             // the answer is not "re-run": a previous archive of this feature is still
             // sitting in the living docs.
             await rollbackStaged(staged);
-            throw new ArchiveFailure("commit-interrupted", err.message);
+            throw new CodedFailure("commit-interrupted", err.message);
         }
         // Everything this run made, unmade: the swapped files, the snapshot inside the
         // feature that is staying put, and features/archive/ if we are the ones who
@@ -232,7 +254,7 @@ export async function archiveLocked(config, featureId, opts) {
         const kept = snapshot && failures.length > 0
             ? ` Pre-images of the overwritten files are kept in features/${dirName}/${SNAPSHOT_DIR}/files/.`
             : "";
-        throw new ArchiveFailure(failures.length > 0 ? "rollback-incomplete" : "merge-failed", wrapped.message + kept);
+        throw new CodedFailure(failures.length > 0 ? "rollback-incomplete" : "merge-failed", wrapped.message + kept);
     }
     // This merge just changed the map, and both generated views files are a
     // function of the tree AND the map: a delta whose element lands inside a