@sdd-method/maintain-cli 0.17.2 → 0.18.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/catalogue/build.js

@@ -110,6 +110,7 @@ export async function runCatalogueBuild(inputs, write) {
     await reportCollapsedFamilies(outDir, join(sddPath, "catalogues"), rowsByCatalogue, findings);
     // 4. Write CSVs (headers + rows).
     const rowCounts = new Map();
+    const preserved = [];
     const ownCatalogues = resolve(join(sddPath, "catalogues"));
     for (const cat of schema.catalogues) {
         const rows = rowsByCatalogue.get(cat.name) ?? [];
@@ -134,6 +135,7 @@ export async function runCatalogueBuild(inputs, write) {
         // also silent, and that is why 26 SDDs lost their conformance evidence
         // while their registries went on citing it.
         if (result.preserved) {
+            preserved.push({ name: cat.name, rows: result.preservedRows ?? result.rowCount });
             findings.add("convention", `catalogues/${cat.name}.csv: this build produced NO rows for it, and the file on disk ` +
                 `holds ${result.preservedRows}. The existing file was LEFT UNTOUCHED rather than ` +
                 `replaced with a bare header. Either the catalogue has no producer in this CLI — in ` +
@@ -237,6 +239,7 @@ export async function runCatalogueBuild(inputs, write) {
         findingsCount: findings.count(),
         pkConflicts: dedupe.conflicts.length,
         unionedRows: dedupe.unionedRows,
+        preserved,
         outDir,
         findings: findings.all(),
     };

package/dist/lib/catalogue/builders/requirements.js

@@ -37,12 +37,12 @@ import { readdir, readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { createHash } from "node:crypto";
-import { observedIn, orderArchives, parseRequirements, renamePairs, resolveImplements } from "../../behaviour-store/archive.js";
+import { observedIn, observedInProblems, orderArchives, parseRequirements, renamePairs, resolveImplements } from "../../behaviour-store/archive.js";
 import { effectsOf, parseAppliedRecord } from "../../structure/effects.js";
 import { APPLIED_FILE, loadChangeStructure, loadModel } from "../../structure/model.js";
 import { viewOf } from "../../structure/view.js";
 import { requirementBlock } from "../../validate/agreement-evidence.js";
-export { observedIn, parseRequirements, resolveImplements };
+export { observedIn, observedInProblems, parseRequirements, resolveImplements };
 /** `sha256:` of a requirement block, its lines trimmed and blank lines dropped (M-ADR 0230 §4.7). */
 export function requirementDigest(spec, name) {
     const block = requirementBlock(spec, name);
@@ -276,6 +276,10 @@ export async function buildRequirements(inputs) {
             structureEffects.push(effectRow(scoped(dir), "structure", e.element, e.operation, e.base ?? "", e.target ?? ""));
         if (evidence !== null) {
             const repos = observedIn(evidence);
+            const malformed = observedInProblems(evidence);
+            if (malformed.length > 0) {
+                findings.add("convention", `${rel(sddPath, join(changeDir, "baseline-evidence.md"))}: "**Observed in:**" has ${malformed.length} entr${malformed.length === 1 ? "y" : "ies"} not shaped "<repository> @ <commit>", not read as repositories; detail goes in the body`);
+            }
             if (repos.length === 0 && delta.length > 0) {
                 findings.add("convention", `${rel(sddPath, join(changeDir, "baseline-evidence.md"))}: no "**Observed in:**" line, so its requirements carry no observed status`);
             }

package/dist/lib/sync/restore-cache.js

@@ -0,0 +1,66 @@
+// sync --restore-cache: rebuild a repository's bundle cache from the bundle its lock records, touching nothing else.
+//
+// The cache (.sdd/bundle-cache/, M-ADR 0176 §4.2) is gitignored, and only sync fills it, so a fresh clone has none and
+// every check that resolves against it (archetype-citations, scaffold --archetype) fails there. A full sync in the clone
+// restores it, but a sync may also move the tree, and a gate wants to know that the tree is what was pushed. A restore
+// therefore takes exactly the bundle the lock records (the same tarball, by the sha256 the lock holds) and writes only
+// the cache: no tracked file, no lock, no .gitignore. Any other bundle is refused, because extracting it would make the
+// cache disagree with the lock; moving to it is a sync.
+import { createHash } from "node:crypto";
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { loadBundle } from "../bundle.js";
+import { findBundle, LOCK_FILE, readLockFile } from "../lock-file.js";
+import { BUNDLE_CACHE_REL, cacheBundle } from "./bundle-cache.js";
+async function exists(p) {
+    return access(p).then(() => true, () => false);
+}
+/** Whether the repository's .gitignore already excludes the cache (a restore never writes it). */
+async function cacheIgnored(targetRepo) {
+    const text = await readFile(join(targetRepo, ".gitignore"), "utf8").catch(() => "");
+    return text.split("\n").some((l) => l.trim() === `${BUNDLE_CACHE_REL}/` || l.trim() === BUNDLE_CACHE_REL);
+}
+export async function restoreBundleCache(opts, stdout = (line) => process.stdout.write(line)) {
+    const fail = (msg) => {
+        stdout(`[FAIL] restore-cache: ${msg}\n`);
+        return { exitCode: 1 };
+    };
+    if (!(await exists(opts.bundle)))
+        return fail(`bundle not found: ${opts.bundle}`);
+    if (!(await exists(opts.targetRepo)))
+        return fail(`target repo not found: ${opts.targetRepo}`);
+    const lock = await readLockFile(opts.targetRepo);
+    if (lock === null)
+        return fail(`${LOCK_FILE} is absent; a restore rebuilds the cache a sync recorded, so sync first`);
+    const sha = createHash("sha256").update(await readFile(opts.bundle)).digest("hex");
+    const bundle = await loadBundle(opts.bundle);
+    try {
+        const { bundleName, bundleVersion } = bundle.manifest;
+        const entry = findBundle(lock, bundleName);
+        if (entry === null)
+            return fail(`${bundleName} ${bundleVersion} is not in ${LOCK_FILE}; a restore takes only a bundle the lock records`);
+        if (entry.bundleSha256 !== sha) {
+            return fail(`${bundleName} ${bundleVersion} (sha256 ${sha.slice(0, 12)}) is not the bundle ${LOCK_FILE} records ` +
+                `(${entry.bundleVersion}, sha256 ${entry.bundleSha256.slice(0, 12)}); a restore takes exactly the locked bundle, and moving to another is a sync`);
+        }
+        if (bundle.manifest.isForwardBase) {
+            stdout(`[INFO] restore-cache: ${bundleName} ${bundleVersion} is a forward base, which sync never caches; nothing to restore\n`);
+            return { exitCode: 0 };
+        }
+        if (!(await cacheIgnored(opts.targetRepo))) {
+            return fail(`.gitignore does not exclude ${BUNDLE_CACHE_REL}/; a restore writes no tracked file, so the line a sync adds is missing here: sync, or add it`);
+        }
+        const dest = `${BUNDLE_CACHE_REL}/${bundleName}@${bundleVersion}`;
+        if (opts.dryRun) {
+            stdout(`[INFO] restore-cache: would cache ${bundleName} ${bundleVersion} at ${dest} (${bundle.managedPaths.length} file(s)); the bundle is the one ${LOCK_FILE} records\n`);
+            return { exitCode: 0 };
+        }
+        await cacheBundle({ targetRepo: opts.targetRepo, bundleName, bundleVersion, managedPaths: bundle.managedPaths, payloadDir: bundle.payloadDir });
+        stdout(`[PASS] restore-cache: ${bundleName} ${bundleVersion} cached at ${dest} (${bundle.managedPaths.length} file(s)), the bundle ${LOCK_FILE} records; no tracked file written\n`);
+        return { exitCode: 0 };
+    }
+    finally {
+        await bundle.cleanup();
+    }
+}
+//# sourceMappingURL=restore-cache.js.map

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/verbs/sync.js

@@ -2,6 +2,7 @@ import { AGENT_HARNESSES, resolveAgentHarness, } from "../lib/agent-harness.js";
 import { loadSyncConfig } from "../lib/sync/config.js";
 import { materialiseBundle } from "../lib/sync/bundle-source.js";
 import { runSync } from "../lib/sync/index.js";
+import { restoreBundleCache } from "../lib/sync/restore-cache.js";
 import { CI_BINDINGS, CI_RUNNER_DEFAULT, isCiBinding, parseCiRunner } from "../lib/ci-binding/index.js";
 import { CLI_SOURCES, DEFAULT_VERIFY_CLI_PACKAGE, NPM_PACKAGE_NAME } from "../lib/hooks-seed/index.js";
 import { resolvePathOption } from "./path-option.js";
@@ -13,6 +14,7 @@ export function registerSync(program) {
         .option("--config <path>", "path to a multi-bundle sync config (iterates bundles in declared order; runs each through the single-bundle sync engine)")
         .option("--target-repo <dir>", "target SDD repo", resolvePathOption, process.cwd())
         .option("--dry-run", "report planned actions without writing")
+        .option("--restore-cache", "rebuild .sdd/bundle-cache from the bundle(s) the lock records, writing no tracked file, lock or .gitignore: for a fresh clone, whose cache is gitignored. Each bundle must be the exact tarball the lock records (by sha256); any other is refused, since moving to it is a sync")
         .option("--replace-bundle <name>", "migrate: drop the named bundle's lock block and release its paths to the incoming bundle (single --bundle mode only; prints the shared/arriving/orphaned split; requires --yes outside --dry-run)")
         .option("--yes", "confirm a --replace-bundle migration outside --dry-run")
         .option("--allow-overwrite", "accept overwrites of locally-modified method content")
@@ -63,6 +65,53 @@ export function registerSync(program) {
             process.stderr.write("[FAIL] --replace-bundle requires single-bundle mode (--bundle <tarball>) — a migration is one deliberate act, not a config iteration\n");
             process.exit(1);
         }
+        if (opts.restoreCache) {
+            const lockChoices = [
+                opts.replaceBundle ? "--replace-bundle" : "",
+                opts.yes ? "--yes" : "",
+                opts.allowOverwrite ? "--allow-overwrite" : "",
+                opts.delete === false ? "--no-delete" : "",
+                opts.ciBinding ? "--ci-binding" : "",
+                opts.ciRunner ? "--ci-runner" : "",
+                opts.cliSource ? "--cli-source" : "",
+                opts.cliPackage ? "--cli-package" : "",
+            ].filter(Boolean);
+            if (lockChoices.length > 0) {
+                process.stderr.write(`[FAIL] --restore-cache writes only the bundle cache; ${lockChoices.join(", ")} change(s) the tree or the lock, which is a sync\n`);
+                process.exit(1);
+            }
+            const one = async (bundle) => (await restoreBundleCache({ bundle, targetRepo: opts.targetRepo, dryRun: opts.dryRun === true })).exitCode;
+            if (opts.bundle) {
+                const code = await one(opts.bundle);
+                if (code !== 0)
+                    process.exit(code);
+                return;
+            }
+            if (!opts.config) {
+                process.stderr.write("[FAIL] one of --bundle or --config is required\n");
+                process.exit(1);
+            }
+            try {
+                const config = await loadSyncConfig(opts.config);
+                for (const entry of config.bundles) {
+                    const resolved = await materialiseBundle(entry);
+                    let code;
+                    try {
+                        code = await one(resolved.localPath);
+                    }
+                    finally {
+                        await resolved.cleanup();
+                    }
+                    if (code !== 0)
+                        process.exit(code);
+                }
+            }
+            catch (err) {
+                process.stderr.write(`[FAIL] ${err.message}\n`);
+                process.exit(1);
+            }
+            return;
+        }
         // Single-bundle path (legacy and explicit).
         if (opts.bundle) {
             const { exitCode } = await runSync({

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/maintain-cli",
-  "version": "0.17.2",
-  "sddCliVersion": "5.3.2",
+  "version": "0.18.0",
+  "sddCliVersion": "5.4.0",
   "description": "Bring an SDD repository current and rebuild its derived model — sync, briefing, catalogue build and aggregate, pack build, context pull — plus every read-only verify verb. Ships only the code those verbs reach; it cannot author specification content. Authoring is in @sdd-method/sdd-cli.",
   "license": "UNLICENSED",
   "type": "module",