@sdd-method/verify-cli 5.3.2 → 5.4.0

package/dist/lib/behaviour-store/archive.js

@@ -136,15 +136,28 @@ export async function orderArchives(sddPath, archiveRel, names) {
 export function observedNone(evidence) {
     return /^\s*\*\*Observed in:\*\*\s*none\b/im.test(evidence);
 }
-/** The repositories a baseline was observed in: its evidence file's `**Observed in:** repo[@sha], repo[@sha]` line. */
-export function observedIn(evidence) {
+/** One `**Observed in:**` entry: `<repository> @ <commit>`, either side optionally in backticks. */
+const OBSERVED_ENTRY = /^`?([A-Za-z0-9][A-Za-z0-9._/-]*)`?\s*@\s*`?([0-9a-fA-F]{7,40})`?$/;
+function observedEntries(evidence) {
     const m = /^\s*\*\*Observed in:\*\*\s*(.+)$/m.exec(evidence);
     if (!m || observedNone(evidence))
         return [];
-    return m[1]
-        .split(",")
-        .map((s) => s.trim().split(/\s*@\s*/)[0].replace(/`/g, "").trim())
-        .filter((s) => s !== "");
+    return m[1].split(",").map((s) => s.trim()).filter((s) => s !== "");
+}
+/**
+ * The repositories a baseline was observed in: its evidence file's `**Observed in:** <repository> @ <commit>[, ...]`
+ * line. Only entries of that shape are read; anything else on the line is reported by `observedInProblems` and never
+ * taken for a repository.
+ */
+export function observedIn(evidence) {
+    return observedEntries(evidence).flatMap((e) => {
+        const m = OBSERVED_ENTRY.exec(e);
+        return m ? [m[1]] : [];
+    });
+}
+/** The `**Observed in:**` entries not shaped `<repository> @ <commit>` (detail belongs in the body, not on the line). */
+export function observedInProblems(evidence) {
+    return observedEntries(evidence).filter((e) => !OBSERVED_ENTRY.test(e));
 }
 /**
  * A baseline's `**Surfaces:**` list (M-ADR 0222 §4.3, §4.4; agreement-record-schema.yaml, Baselines): one entry per
@@ -165,20 +178,30 @@ export function parseSurfaces(evidence) {
     // the list is what the file ends up asserting.
     let at = -1;
     let none = false;
+    let generated = false;
     lines.forEach((l, i) => {
         if (/^\s*\*\*Surfaces:\*\*\s*$/.test(l)) {
             at = i;
             none = false;
+            generated = false;
         }
         else if (/^\s*\*\*Surfaces:\*\*\s*none\b/i.test(l)) {
             at = i;
             none = true;
+            generated = false;
+        }
+        else if (/^\s*\*\*Surfaces:\*\*\s*generated\b/i.test(l)) {
+            at = i;
+            none = false;
+            generated = true;
         }
     });
     if (at < 0)
-        return { present: false, none: false, entries: [], problems: [] };
+        return { present: false, none: false, generated: false, entries: [], problems: [] };
     if (none)
-        return { present: true, none: true, entries: [], problems: [] };
+        return { present: true, none: true, generated: false, entries: [], problems: [] };
+    if (generated)
+        return { present: true, none: false, generated: true, entries: [], problems: [] };
     const entries = [];
     const problems = [];
     for (const line of lines.slice(at + 1)) {
@@ -213,7 +236,37 @@ export function parseSurfaces(evidence) {
     }
     if (entries.length + problems.length === 0)
         problems.push('the **Surfaces:** line lists no contract; a baseline that admits no behaviour writes "**Surfaces:** none"');
-    return { present: true, none: false, entries, problems };
+    return { present: true, none: false, generated: false, entries, problems };
+}
+/**
+ * A generator's baseline (agreement-record-schema.yaml, Baselines: generated behaviour) serves no contract; its
+ * transport is the generated tree, and the run that generated it is evidence only if another reader can repeat it.
+ * The run is recorded on a line of its own:
+ *   **Generated by:** <repository> @ <commit>; run: `<command and options>`; tree: <hash>[, <hash>]
+ * where each tree hash is hex of 12 or more digits, optionally `sha256:`-prefixed and optionally labelled `<kit>=`.
+ * Returns what is wrong with the line, or that it is absent.
+ */
+export function generatedByProblems(evidence) {
+    const line = evidence.split("\n").filter((l) => /^\s*\*\*Generated by:\*\*/.test(l)).pop();
+    if (line === undefined)
+        return ["no **Generated by:** line"];
+    const body = line.replace(/^\s*\*\*Generated by:\*\*\s*/, "");
+    const parts = body.split(/;\s*(?=run:|tree:)/);
+    const out = [];
+    if (!/^`?[A-Za-z0-9][A-Za-z0-9._/-]*`?\s*@\s*`?[0-9a-fA-F]{7,40}`?\s*$/.test(parts[0] ?? ""))
+        out.push(`"${(parts[0] ?? "").trim()}" is not "<generator repository> @ <commit>"`);
+    const run = parts.find((p) => p.startsWith("run:"));
+    if (!run || !/^run:\s*`[^`]+`\s*$/.test(run.trim()))
+        out.push("no run: `<command and options>`");
+    const tree = parts.find((p) => p.startsWith("tree:"));
+    const hashes = tree ? tree.replace(/^tree:\s*/, "").split(",").map((h) => h.trim()).filter((h) => h !== "") : [];
+    if (hashes.length === 0)
+        out.push("no tree: <content hash of the generated tree>");
+    for (const h of hashes) {
+        if (!/^(?:[A-Za-z0-9._-]+=)?(?:sha256:)?[0-9a-fA-F]{12,}$/.test(h.replace(/`/g, "")))
+            out.push(`tree hash "${h}" is not hex of 12 or more digits`);
+    }
+    return out;
 }
 /**
  * A structural delta's `moved: {contracts: [{from, to, from_path?}]}` block. A contract's id is derived from its path,

package/dist/lib/validate/archetype-citations.js

@@ -77,22 +77,29 @@ export async function checkArchetypeCitations(repo) {
     const lines = [];
     let problems = 0;
     let total = 0;
+    // A citation file that cannot be read as a whole (it does not parse, names no cached archetype, or lists nothing)
+    // has no citations to count, so it is counted apart: "1 of 0" would read as a failure with no population.
+    let fileProblems = 0;
     const bad = (tag, msg) => {
         lines.push(`[${tag}] ${msg}`);
         problems++;
     };
+    const badFile = (msg) => {
+        lines.push(`[unresolved] ${msg}`);
+        fileProblems++;
+    };
     for (const [rel, text] of files) {
         let doc;
         try {
             doc = (parseYaml(text) ?? {});
         }
         catch (e) {
-            bad("unresolved", `${rel}: does not parse: ${e.message.split("\n")[0]}`);
+            badFile(`${rel}: does not parse: ${e.message.split("\n")[0]}`);
             continue;
         }
         const archetype = archetypes.find((a) => a.id === doc.archetype && a.bundleName === doc.bundle);
         if (!archetype) {
-            bad("unresolved", `${rel}: archetype ${String(doc.archetype)} of bundle ${String(doc.bundle)} is not in the bundle cache (sync the bundle)`);
+            badFile(`${rel}: archetype ${String(doc.archetype)} of bundle ${String(doc.bundle)} is not in the bundle cache (sync the bundle)`);
             continue;
         }
         const reqs = await loadArchetypeBehaviour(archetype.bundleCacheDir, archetype.seeds);
@@ -101,7 +108,7 @@ export async function checkArchetypeCitations(repo) {
         const cites = Array.isArray(doc.citations) ? doc.citations : [];
         const notAdopted = Array.isArray(doc.not_adopted) ? doc.not_adopted : [];
         if (cites.length === 0 && notAdopted.length === 0)
-            bad("unresolved", `${rel}: lists no citations`);
+            badFile(`${rel}: lists no citations`);
         const citedIds = new Set(cites.map((c) => String(c.cites)));
         for (const n of notAdopted) {
             total++;
@@ -161,9 +168,11 @@ export async function checkArchetypeCitations(repo) {
             `(${[...citedIds].filter((id) => byId.has(id)).length} cited, ${notAdopted.length} not adopted)` +
             (gaps.length ? `; not yet answered: ${gaps.join(", ")}` : ""));
     }
-    const verdict = problems
-        ? `[FAIL] archetype citations: ${problems} of ${total} unresolved or stale`
+    const filePart = fileProblems ? `${fileProblems} of ${files.length} citation file(s) unresolved` : "";
+    const citePart = problems ? `${problems} of ${total} citation(s) unresolved or stale` : "";
+    const verdict = problems || fileProblems
+        ? `[FAIL] archetype citations: ${[filePart, citePart].filter(Boolean).join("; ")}${problems ? "" : `; ${total} citation(s) checked resolve`}`
         : `[PASS] archetype citations: ${total} resolve, none stale`;
-    return { exitCode: problems ? 1 : 0, stdout: lines.join("\n") + "\n" + verdict + "\n" };
+    return { exitCode: problems || fileProblems ? 1 : 0, stdout: lines.join("\n") + "\n" + verdict + "\n" };
 }
 //# sourceMappingURL=archetype-citations.js.map

package/dist/lib/validate/behaviour-store.js

@@ -8,7 +8,8 @@
 //
 //   1. records:  every agreement record has the shape the checks below read.
 //   2. agreement: an open change with any completed task has an agreed record and a Gate 0 that
-//                 ends CLEAR (the pre-apply check, M-ADR 0223 §4.3). A record for an open change must
+//                 ends CLEAR (the pre-apply check, M-ADR 0223 §4.3); an open baseline (baseline-evidence.md)
+//                 has neither and is not asked for them. A record for an open change must
 //                 declare agreement-record schema 1.1.0 or later.
 //   3. stale:    for each open, agreed change, each requirement it MODIFIES, REMOVES or RENAMES is, block by
 //                 block, as it was at the agreed commit (the latest amendment's, else sdd.commit; M-ADR 0223
@@ -73,7 +74,7 @@ import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import { promisify } from "node:util";
 import { parseDocument } from "yaml";
-import { contractMoves, observedIn, orderArchives, parseRequirements, parseSurfaces, renamedFrom, renamePairs, resolveImplements, surfaceMatches } from "../behaviour-store/archive.js";
+import { contractMoves, generatedByProblems, observedIn, observedInProblems, orderArchives, parseRequirements, parseSurfaces, renamedFrom, renamePairs, resolveImplements, surfaceMatches } from "../behaviour-store/archive.js";
 import { parseCatalogueCsv } from "../catalogue/csv-reader.js";
 import { boundFile, conditionProblems, structuralFile, isCommit, normaliseBound, requirementBlock, sameCommit, scenarioKind, taskGroups, testPlanHeader, testPlanMapping, verdictLine, versionAtLeast } from "./agreement-evidence.js";
 import { ENFORCED as STRUCTURE_ENFORCED } from "./structural-model.js";
@@ -443,6 +444,7 @@ export async function checkBehaviourStore(repo, options = {}) {
     // 2 and 3. open changes
     const open = (await dirs(join(repo, STORE_DIR, "changes"))).filter((d) => d !== "archive");
     let started = 0;
+    let baselinesTicked = 0;
     let staleChecked = 0;
     let contentChecked = 0;
     let kindsChecked = 0;
@@ -450,7 +452,13 @@ export async function checkBehaviourStore(repo, options = {}) {
         const dir = `${STORE_DIR}/changes/${change}`;
         const tasks = await readText(join(repo, dir, "tasks.md"));
         const record = records.get(change);
-        if (tasks !== null && TASK_DONE_RE.test(tasks)) {
+        // A baseline (its baseline-evidence.md, the signal the archive side reads) has no agreement record and no Gate 0;
+        // its tasks are the characterization tests, ticked as each is written (sdd-baseline, M-ADR 0222 §4.3). Its gate is
+        // checked when it archives.
+        const baseline = await exists(join(repo, dir, "baseline-evidence.md"));
+        if (tasks !== null && TASK_DONE_RE.test(tasks) && baseline)
+            baselinesTicked++;
+        if (tasks !== null && TASK_DONE_RE.test(tasks) && !baseline) {
             started++;
             if (!record && recordFiles.some((f) => f.replace(/\.ya?ml$/, "") === change))
                 failures.push(`${dir}: has completed tasks but its agreement record (${AGREEMENTS_DIR}/${change}.yaml) is malformed; see its record failures`);
@@ -596,7 +604,7 @@ export async function checkBehaviourStore(repo, options = {}) {
             }
         }
     }
-    lines.push(`agreement: ${open.length} open change(s), ${started} with completed tasks`);
+    lines.push(`agreement: ${open.length} open change(s), ${started} with completed tasks${baselinesTicked > 0 ? `; ${baselinesTicked} open baseline(s) with ticked characterization tests, which need no agreement or Gate 0` : ""}`);
     lines.push(staleChecked === 0 ? "stale: vacuous (no open agreed change modifies, removes or renames a requirement)" : `stale: ${staleChecked} targeted requirement(s) checked against their agreed commits`);
     lines.push(`agreed content: ${contentChecked} open agreed change(s) compared with their pinned commits; ${kindsChecked} test-plan scenario kind(s) checked`);
     // 8. overlap: two open, agreed changes never name the same requirement of one living spec (M-ADR 0223 §4.10).
@@ -839,6 +847,7 @@ export async function checkBehaviourStore(repo, options = {}) {
     const servedBy = baselines + openBaselines.length > 0 ? await catalogueContracts(repo) : null;
     let surfacesChecked = 0;
     let structureOnly = 0;
+    let generatedBaselines = 0;
     // The contract moves each archived change records, in archive order. A contract's id derives from its path, so a
     // move changes it; an archived baseline's list names the contract as it was, and is resolved through the moves
     // archived after it rather than edited (M-ADR 0222 §4.4). A surface that vanished with no move still fails.
@@ -916,9 +925,16 @@ export async function checkBehaviourStore(repo, options = {}) {
     /** What is wrong with a baseline's Surfaces list against the catalogue (M-ADR 0222 §4.3, §4.4). */
     const surfaceProblems = async (dir, evidence, after = -1) => {
         const out = [];
+        const malformed = observedInProblems(evidence);
+        if (malformed.length > 0) {
+            const shown = malformed.slice(0, 3).map((e) => JSON.stringify(e.length > 60 ? `${e.slice(0, 57)}...` : e)).join(", ");
+            out.push(`${dir}/baseline-evidence.md: **Observed in:** has ${malformed.length} entr${malformed.length === 1 ? "y" : "ies"} not shaped "<repository> @ <commit>" (${shown}${malformed.length > 3 ? ", ..." : ""}); the line holds only those, comma-separated, and detail goes in the body (agreement-record-schema.yaml, Baselines)`);
+        }
         const parsed = parseSurfaces(evidence);
         const admits = await admitsBehaviour(dir);
         if (!admits) {
+            if (parsed.generated)
+                return [`${dir}/baseline-evidence.md: **Surfaces:** generated, but the baseline admits no behaviour (no requirement in its spec deltas): write "**Surfaces:** none"`];
             if (parsed.none) {
                 structureOnly++;
                 return out;
@@ -930,6 +946,30 @@ export async function checkBehaviourStore(repo, options = {}) {
         else if (parsed.none) {
             return [`${dir}/baseline-evidence.md: **Surfaces:** none, but the baseline admits behaviour (requirements in ${dir}/specs/); name every contract the observed repositories serve, covered at transport or excluded with a reason`];
         }
+        if (parsed.generated) {
+            // A generator serves nothing: its transport is the generated tree (agreement-record-schema.yaml, Baselines). The
+            // claim holds only where the catalogue confirms that no observed repository serves a contract, and where the run
+            // is recorded so another reader can repeat it; anything else fails, so the claim is never a way past the list.
+            for (const p of generatedByProblems(evidence)) {
+                out.push(`${dir}/baseline-evidence.md: **Surfaces:** generated needs the run recorded as "**Generated by:** <generator repository> @ <commit>; run: \`<command and options>\`; tree: <hash>": ${p}`);
+            }
+            if (servedBy === null) {
+                out.push(`${dir}/baseline-evidence.md: **Surfaces:** generated cannot be cross-checked: catalogues/repo_contract.csv or catalogues/contracts.csv is missing; build the catalogue`);
+                return out;
+            }
+            const repos = observedIn(evidence);
+            if (repos.length === 0)
+                out.push(`${dir}/baseline-evidence.md: **Surfaces:** generated cannot be cross-checked: no **Observed in:** line names a repository`);
+            for (const r of repos) {
+                const served = servedBy.get(r)?.served ?? [];
+                if (served.length > 0) {
+                    out.push(`${dir}/baseline-evidence.md: **Surfaces:** generated, but ${r} serves ${served.length} contract(s) (catalogues/repo_contract.csv: ${served.slice(0, 3).map((c) => c.id).join(", ")}${served.length > 3 ? ", ..." : ""}); a repository that serves contracts lists each, covered at transport or excluded with a reason`);
+                }
+            }
+            if (out.length === 0)
+                generatedBaselines++;
+            return out;
+        }
         if (!parsed.present)
             out.push(`${dir}/baseline-evidence.md: no **Surfaces:** list; name every contract the observed repositories serve, covered at transport or excluded with a reason`);
         for (const p of parsed.problems)
@@ -1048,7 +1088,7 @@ export async function checkBehaviourStore(repo, options = {}) {
     if (openBaselines.length > 0)
         lines.push(`open baselines: ${openBaselines.length}, asked the archive's questions as warnings`);
     const unseen = servedBy === null ? "" : `; repositories with no catalogue contracts: ${[...new Set(await observedInAll(repo, archiveRel, order))].filter((r) => (servedBy.get(r)?.served ?? []).length === 0).join(", ") || "none"}`;
-    lines.push(baselines === 0 ? "surfaces: vacuous (no baseline)" : `surfaces: ${baselines} baseline(s), ${surfacesChecked} served contract(s) checked against catalogues/repo_contract.csv less what service_contract records only consumed${unseen}${structureOnly ? `; ${structureOnly} structure-only baseline(s) admitting no behaviour, Surfaces: none` : ""}${historical.size ? `; ${historical.size} historical baseline(s) not checked (every requirement they baselined has left the living specs)` : ""}`);
+    lines.push(baselines === 0 ? "surfaces: vacuous (no baseline)" : `surfaces: ${baselines} baseline(s), ${surfacesChecked} served contract(s) checked against catalogues/repo_contract.csv less what service_contract records only consumed${unseen}${structureOnly ? `; ${structureOnly} structure-only baseline(s) admitting no behaviour, Surfaces: none` : ""}${generatedBaselines ? `; ${generatedBaselines} generator baseline(s) serving no contract, Surfaces: generated` : ""}${historical.size ? `; ${historical.size} historical baseline(s) not checked (every requirement they baselined has left the living specs)` : ""}`);
     lines.push(scopeChecked === 0 ? "scope: vacuous (no baseline removes, modifies or renames a requirement)" : `scope: ${scopeChecked} requirement(s) a baseline removes, modifies or renames, checked against their lineage`);
     if (!history && archived.length > 0)
         lines.push("order: no git history (not a git work tree, or git log failed), so same-day archives cannot be ordered");

package/dist/lib/validate/carve-citations.js

@@ -0,0 +1,228 @@
+// carve-citations: behaviour carved out of one SDD into another keeps one home at a time
+// (docs/method/methods/guides/carving-behaviour-into-a-new-sdd.md; M-ADR 0221, 0222).
+//
+// The new SDD's requirement names what it replaces, on a line of its own:
+//   Replaces <sdd-id>:<feature>::<requirement name>.
+//   Departs from <sdd-id>:<feature>::<requirement name>: <why>.
+// At cutover the old SDD removes the requirement, its Reason naming the replacement:
+//   replaced by <sdd-id>:<feature>::<requirement name>
+//
+// The other SDD is found beside this one: a sibling directory whose .sdd/sdd-manifest.yaml has that sdd_id. Checks:
+//   replaces:   each Replaces / Departs line parses, and names a requirement the other SDD has: living there (in
+//               flight), or removed by an archived change (carved).
+//   replaced:   each removal's `replaced by` names a requirement living in the other SDD.
+//   one home:   a requirement removed here as replaced by another SDD is not living here again; and no two living
+//               requirements here replace the same requirement.
+// A citation in a living spec or an archived change fails; one in an open change is a [WARN] (it is not agreed yet),
+// as is any citation whose other SDD has no checkout beside this one (unresolved, failed under --strict). Cutover
+// itself is an event of the estate's, not recorded in the store, so a requirement both SDDs hold before the old one is
+// removed is "in flight" and is reported in the inventory, not failed.
+import { readdir, readFile } from "node:fs/promises";
+import { basename, dirname, join } from "node:path";
+const STORE = "openspec";
+const REQ_HEAD = /^###\s+Requirement:\s*(.+?)\s*$/;
+const SECTION = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\s*$/i;
+const CITE_START = /^\s*(Replaces|Departs from)\s/;
+const REPLACES = /^\s*Replaces\s+([A-Za-z0-9._-]+):([A-Za-z0-9._-]+)::(.+?)\.\s*$/;
+const DEPARTS = /^\s*Departs from\s+([A-Za-z0-9._-]+):([A-Za-z0-9._-]+)::(.+?):\s+\S.*$/;
+const REPLACED_BY = /replaced by\s+`?([A-Za-z0-9._-]+):([A-Za-z0-9._-]+)::([^`\n]+?)`?\s*(?:[.;,)]\s*)?$/im;
+const key = (r) => `${r.sdd}:${r.feature}::${r.name}`;
+async function read(p) {
+    return readFile(p, "utf8").catch(() => null);
+}
+async function dirs(p) {
+    try {
+        return (await readdir(p, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name).sort();
+    }
+    catch {
+        return [];
+    }
+}
+/** Requirement blocks of a spec or delta file, each with the section it sits in. */
+function blocks(text, living) {
+    const out = [];
+    let op = living ? "living" : "";
+    let cur = null;
+    for (const line of text.split("\n")) {
+        const s = SECTION.exec(line);
+        if (s) {
+            if (cur)
+                out.push(cur);
+            cur = null;
+            op = s[1].toUpperCase();
+            continue;
+        }
+        const h = REQ_HEAD.exec(line);
+        if (h) {
+            if (cur)
+                out.push(cur);
+            cur = { name: h[1], op, text: "" };
+            continue;
+        }
+        if (/^##\s/.test(line) && cur) {
+            out.push(cur);
+            cur = null;
+            continue;
+        }
+        if (cur)
+            cur.text += `${line}\n`;
+    }
+    if (cur)
+        out.push(cur);
+    return out;
+}
+async function sddId(repo) {
+    const m = /^sdd_id:\s*["']?([^"'\n]+?)["']?\s*$/m.exec((await read(join(repo, ".sdd", "sdd-manifest.yaml"))) ?? "");
+    return m ? m[1] : "";
+}
+async function view(repo) {
+    const living = new Map();
+    for (const f of await dirs(join(repo, STORE, "specs"))) {
+        const t = await read(join(repo, STORE, "specs", f, "spec.md"));
+        if (t !== null)
+            living.set(f, new Set(blocks(t, true).map((b) => b.name)));
+    }
+    const removed = new Map();
+    for (const c of await dirs(join(repo, STORE, "changes", "archive"))) {
+        for (const f of await dirs(join(repo, STORE, "changes", "archive", c, "specs"))) {
+            const t = await read(join(repo, STORE, "changes", "archive", c, "specs", f, "spec.md"));
+            for (const b of t === null ? [] : blocks(t, false)) {
+                if (b.op === "REMOVED")
+                    (removed.get(f) ?? removed.set(f, new Set()).get(f)).add(b.name);
+            }
+        }
+    }
+    return { living, removed };
+}
+export async function checkCarveCitations(repo) {
+    const own = await sddId(repo);
+    const failures = [];
+    const warnings = [];
+    const cites = [];
+    const removals = [];
+    const collect = (rel, text, living, open, removalsOnly = false) => {
+        for (const b of blocks(text, living)) {
+            if (removalsOnly && b.op !== "REMOVED")
+                continue;
+            if (b.op === "REMOVED") {
+                const m = REPLACED_BY.exec(b.text);
+                if (m)
+                    removals.push({ where: `${rel}: '${b.name}'`, open, ref: { sdd: m[1], feature: m[2], name: m[3].trim() }, feature: basename(dirname(rel)), name: b.name });
+                continue;
+            }
+            for (const line of b.text.split("\n")) {
+                if (!CITE_START.test(line))
+                    continue;
+                const r = REPLACES.exec(line);
+                const d = r ? null : DEPARTS.exec(line);
+                const m = r ?? d;
+                cites.push({
+                    where: `${rel}: '${b.name}'`,
+                    open,
+                    line: line.trim(),
+                    ref: m ? { sdd: m[1], feature: m[2], name: m[3].trim() } : null,
+                    kind: /^\s*Departs/.test(line) ? "departs" : "replaces",
+                    owner: living ? `${basename(dirname(rel))}::${b.name}` : "",
+                });
+            }
+        }
+    };
+    for (const f of await dirs(join(repo, STORE, "specs"))) {
+        const rel = `${STORE}/specs/${f}/spec.md`;
+        const t = await read(join(repo, rel));
+        if (t !== null)
+            collect(rel, t, true, false);
+    }
+    for (const c of await dirs(join(repo, STORE, "changes"))) {
+        const archived = c === "archive";
+        for (const ch of archived ? await dirs(join(repo, STORE, "changes", "archive")) : [c]) {
+            const base = archived ? `${STORE}/changes/archive/${ch}` : `${STORE}/changes/${ch}`;
+            for (const f of await dirs(join(repo, base, "specs"))) {
+                const rel = `${base}/specs/${f}/spec.md`;
+                const t = await read(join(repo, rel));
+                // An archived delta's Replaces lines live on in the living spec it produced; only its removals are read here.
+                if (t !== null)
+                    collect(rel, t, false, !archived, archived);
+            }
+        }
+    }
+    if (cites.length === 0 && removals.length === 0) {
+        return { exitCode: 0, stdout: "[N/A] no carve citations (Replaces / Departs from lines, or removals replaced by another SDD) in this repository\n" };
+    }
+    // The other SDDs, found beside this one by their sdd_id.
+    const siblings = new Map();
+    const parent = dirname(repo);
+    for (const d of await dirs(parent)) {
+        const p = join(parent, d);
+        const id = await sddId(p);
+        if (id !== "" && !siblings.has(id))
+            siblings.set(id, p);
+    }
+    const self = await view(repo);
+    if (own !== "")
+        siblings.set(own, repo);
+    const views = new Map();
+    const other = async (id) => {
+        const p = siblings.get(id);
+        if (!p)
+            return null;
+        if (!views.has(id))
+            views.set(id, p === repo ? self : await view(p));
+        return views.get(id);
+    };
+    const report = (open, msg) => (open ? warnings : failures).push(msg);
+    let inFlight = 0;
+    let carved = 0;
+    let unresolved = 0;
+    const replacedBy = new Map();
+    for (const c of cites) {
+        if (c.ref === null) {
+            report(c.open, `${c.where}: "${c.line}" is not "Replaces <sdd-id>:<feature>::<requirement name>." or "Departs from <sdd-id>:<feature>::<requirement name>: <why>."`);
+            continue;
+        }
+        const v = await other(c.ref.sdd);
+        if (v === null) {
+            unresolved++;
+            warnings.push(`${c.where}: ${key(c.ref)} unresolved: no checkout beside this SDD has sdd_id "${c.ref.sdd}"; check it out beside this one (failed under --strict)`);
+            continue;
+        }
+        if (v.living.get(c.ref.feature)?.has(c.ref.name))
+            inFlight++;
+        else if (v.removed.get(c.ref.feature)?.has(c.ref.name))
+            carved++;
+        else {
+            report(c.open, `${c.where}: ${c.kind === "departs" ? "Departs from" : "Replaces"} ${key(c.ref)}, which ${c.ref.sdd} neither has nor removed (feature ${c.ref.feature}${v.living.has(c.ref.feature) ? "" : ", which it has no living spec for"})`);
+            continue;
+        }
+        if (c.owner !== "")
+            (replacedBy.get(key(c.ref)) ?? replacedBy.set(key(c.ref), []).get(key(c.ref))).push(c.owner);
+    }
+    for (const [k, owners] of replacedBy) {
+        if (owners.length > 1)
+            failures.push(`one home: ${k} is replaced by ${owners.length} living requirements here (${owners.join(", ")}); one requirement carries it`);
+    }
+    for (const r of removals) {
+        const v = await other(r.ref.sdd);
+        if (v === null) {
+            unresolved++;
+            warnings.push(`${r.where}: replaced by ${key(r.ref)} unresolved: no checkout beside this SDD has sdd_id "${r.ref.sdd}" (failed under --strict)`);
+        }
+        else if (!v.living.get(r.ref.feature)?.has(r.ref.name)) {
+            report(r.open, `${r.where}: removed as replaced by ${key(r.ref)}, which is not a living requirement of ${r.ref.sdd}`);
+        }
+        if (!r.open && self.living.get(r.feature)?.has(r.name)) {
+            failures.push(`one home: ${r.where}: removed here as replaced by ${key(r.ref)}, but '${r.name}' is living in ${STORE}/specs/${r.feature}/spec.md again`);
+        }
+    }
+    const lines = [
+        `  citations: ${cites.length} Replaces / Departs line(s): ${inFlight} in flight (still living where they came from), ${carved} carved (removed there), ${unresolved} unresolved`,
+        `  removals: ${removals.length} replaced by another SDD`,
+    ];
+    const body = lines.join("\n") + "\n";
+    const warn = warnings.map((w) => `[WARN] ${w}\n`).join("");
+    if (failures.length > 0) {
+        return { exitCode: 1, stdout: body + failures.map((f) => `[FAIL] ${f}\n`).join("") + warn + `[FAIL] carve citations: ${failures.length} problem(s)\n` };
+    }
+    return { exitCode: 0, stdout: body + warn + `[PASS] carve citations: one home each${warnings.length ? ", with the warnings above" : ""}\n` };
+}
+//# sourceMappingURL=carve-citations.js.map

package/dist/lib/validate/dispatch.js

@@ -1,6 +1,7 @@
 import { checkArchetypeCitations } from "./archetype-citations.js";
 import { checkBehaviourStore, checkBehaviourStoreOpenspec } from "./behaviour-store.js";
 import { checkBundleCoherence } from "./bundle-coherence.js";
+import { checkCarveCitations } from "./carve-citations.js";
 import { checkFeatureSpecPointers } from "./feature-spec-pointers.js";
 import { checkIntents } from "./intents.js";
 import { checkJourneyImpact } from "./journey-impact.js";
@@ -25,6 +26,12 @@ const BEHAVIOUR_STORE_VALIDATORS = [
         source: { kind: "native", run: async (ctx) => checkArchetypeCitations(ctx.targetRepo) },
         build: () => ({ status: "run", args: [] }),
     },
+    // Behaviour carved into another SDD keeps one home at a time (the carving guide); without citations it reports [N/A].
+    {
+        name: "carve-citations",
+        source: { kind: "native", run: async (ctx) => checkCarveCitations(ctx.targetRepo) },
+        build: () => ({ status: "run", args: [] }),
+    },
     // Intents (M-ADR 0227) can sit in an SDD of any profile; without any the check reports [N/A].
     {
         name: "intents",

package/dist/maintain-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.17.2",
-  "built_against_sdd_cli": "5.3.2"
+  "version": "0.18.0",
+  "built_against_sdd_cli": "5.4.0"
 }

package/dist/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "5.3.2",
-  "built_against_sdd_cli": "5.3.2"
+  "version": "5.4.0",
+  "built_against_sdd_cli": "5.4.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sdd-method/verify-cli",
-  "version": "5.3.2",
-  "sddCliVersion": "5.3.2",
+  "version": "5.4.0",
+  "sddCliVersion": "5.4.0",
   "description": "Verify an SDD repository without changing it — validate, list, and read-only catalogue and pack checks. Ships only the code those verbs reach; it cannot write to the repository it is pointed at. Authoring and maintenance are in @sdd-method/sdd-cli.",
   "license": "UNLICENSED",
   "type": "module",