@sdd-method/author-cli 0.16.2 → 0.17.1

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/structure/archive.js

@@ -65,9 +65,9 @@ async function defaultBehaviourFindings(sddPath, archiveDir) {
     const r = await checkBehaviourStore(sddPath);
     return r.stdout.split("\n").filter((l) => l.startsWith("[FAIL]") && l.includes(archiveDir));
 }
-function viewProblems(schema, view) {
+function viewProblems(schema, view, profile) {
     const out = [];
-    validateView(schema, view, () => null, out, new Set());
+    validateView(schema, view, () => null, out, new Set(), () => undefined, profile);
     return new Set(out);
 }
 /** Does the effect record hold at `commit`? Each added or modified element at its target, each removed one absent. */
@@ -98,6 +98,11 @@ async function verifyAt(root, relSdd, commit, effects) {
         await rm(scratch, { recursive: true, force: true });
     }
 }
+/** The SDD's profile from its manifest, "" when absent or unreadable. */
+async function sddProfile(sddPath) {
+    const text = await readFile(join(sddPath, ".sdd", "sdd-manifest.yaml"), "utf8").catch(() => "");
+    return /^profile:\s*["']?([A-Za-z0-9-]+)["']?\s*$/m.exec(text)?.[1] ?? "";
+}
 export async function archiveChange(o) {
     const say = (s) => o.write(`${s}\n`);
     const refuse = (s) => {
@@ -241,6 +246,7 @@ async function publish(o, root, relSdd, schema, s, changeRel, mode) {
         say(`[FAIL] change archive ${o.change}: ${x}`);
         return 1;
     };
+    const profile = await sddProfile(o.sddPath);
     const storeRel = join(relSdd, "openspec");
     const viewsRel = join(relSdd, "docs", "structure");
     const dirty = await git(root, "status", "--porcelain", "--", storeRel, viewsRel);
@@ -250,9 +256,9 @@ async function publish(o, root, relSdd, schema, s, changeRel, mode) {
     // §4.5 again, against the model as it now is.
     const problems = [];
     const current = viewOf((await loadModel(o.sddPath, problems)) ?? [], problems);
-    const before = viewProblems(schema, current);
+    const before = viewProblems(schema, current, profile);
     const deltaProblems = [];
-    validateDeltas(schema, current, s.deltas, new Map(), deltaProblems);
+    validateDeltas(schema, current, s.deltas, new Map(), deltaProblems, profile);
     if (deltaProblems.length > 0)
         return refuse(`its structural deltas no longer apply to the model as it stands:\n  ${deltaProblems.join("\n  ")}`);
     const effects = effectsOf(s, current);
@@ -280,7 +286,7 @@ async function publish(o, root, relSdd, schema, s, changeRel, mode) {
         // 2. Validate the candidate as a whole.
         const cp = [];
         const candidate = viewOf((await loadModel(scratchSdd, cp)) ?? [], cp);
-        const after = viewProblems(schema, candidate);
+        const after = viewProblems(schema, candidate, profile);
         const worse = [...cp, ...[...after].filter((p) => !before.has(p))];
         if (worse.length > 0)
             return refuse(`the model as it would stand fails where it did not:\n  ${worse.join("\n  ")}`);

package/dist/lib/structure/extract.js

@@ -75,6 +75,12 @@ export async function extractStructure(sddPath, build = runCatalogueBuild) {
         if (built.exitCode !== 0) {
             return { ...none, refused: `the sources do not build cleanly (sdd-cli catalogue build exits ${built.exitCode}: ${built.internalFkPass ? "" : "dangling references, "}${built.pkConflicts} key conflict(s)); a model extracted from them would carry the same faults. Fix the build first` };
         }
+        // A catalogue the build produced no rows for keeps the SDD's file (catalogue build never replaces rows with a bare
+        // header). Those rows came from no source, so a model "extracted from its sources" must not carry them.
+        const kept = built.preserved.filter((p) => schema.catalogues.some((c) => c.name === p.name && c.sourceOfTruth === STRUCTURE));
+        if (kept.length > 0) {
+            return { ...none, refused: `${kept.map((k) => `catalogues/${k.name}.csv holds ${k.rows} row(s)`).join("; ")} that no source gives any more (the build produced none and kept the file); a model extracted now would carry them as if derived. Restore the source, or delete those rows from catalogues/ (keep the header), then extract` };
+        }
         const rows = new Map();
         for (const c of schema.catalogues) {
             if (c.sourceOfTruth !== STRUCTURE)

package/dist/lib/structure/view.js

@@ -90,13 +90,15 @@ function find(view, catalogue, column, value) {
     return undefined;
 }
 /** The element's references: each non-external foreign key with a value. */
-export function referencesOf(schema, e) {
+export function referencesOf(schema, e, profile = "") {
     const cat = catalogueOf(schema, e.catalogue);
     if (!cat)
         return [];
     const out = [];
     for (const fk of cat.foreignKeys) {
-        if (fk.external)
+        // An external key names another SDD's element; so does one external for this SDD's profile (an application or
+        // integration model naming a data item the platform model owns), as the FK validator and the graph projection read it.
+        if (fk.external || (profile !== "" && (fk.externalForProfiles ?? []).includes(profile)))
             continue;
         const v = e.columns[fk.column];
         if (v === undefined || v === "")
@@ -121,7 +123,7 @@ function naturalKey(cat, e) {
  * catalogue of another class, against its built rows), no cycle through a self-reference, natural keys unique, and
  * domain invariants naming their entity's own attributes and relationships.
  */
-export function validateView(schema, view, built, problems, unresolved, addedBy = () => undefined) {
+export function validateView(schema, view, built, problems, unresolved, addedBy = () => undefined, profile = "") {
     // A reference to an open change's addition, from outside that change and its dependants (§4.11 proof 3).
     const outside = (catalogue, id) => {
         const by = addedBy(catalogue, id);
@@ -135,7 +137,7 @@ export function validateView(schema, view, built, problems, unresolved, addedBy
             problems.push(...shape);
             if (!cat || cat.sourceOfTruth !== STRUCTURE)
                 continue;
-            for (const r of referencesOf(schema, e)) {
+            for (const r of referencesOf(schema, e, profile)) {
                 if (r.structural) {
                     if (!find(view, r.catalogue, r.targetColumn, r.value))
                         problems.push(`${e.file}: ${elementKey(catalogue, e.id)}: ${r.column} ${JSON.stringify(r.value)} names no ${r.catalogue} element in this view (${elementKey(r.catalogue, r.value)})${r.targetColumn === "id" ? outside(r.catalogue, r.value) : ""}`);
@@ -218,7 +220,7 @@ export function validateView(schema, view, built, problems, unresolved, addedBy
  * A base revision that no longer matches the current element is reported as moved: the change is revalidated.
  * `addedElsewhere` holds the elements other open changes add, for a reference into one of them.
  */
-export function validateDeltas(schema, current, deltas, addedElsewhere, problems) {
+export function validateDeltas(schema, current, deltas, addedElsewhere, problems, profile = "") {
     const ownAdded = new Set();
     const dependsOn = new Set();
     for (const d of deltas) {
@@ -281,7 +283,7 @@ export function validateDeltas(schema, current, deltas, addedElsewhere, problems
         }
         // Reads: every element an added or modified element references.
         for (const e of [...d.added, ...d.modified]) {
-            for (const r of referencesOf(schema, e)) {
+            for (const r of referencesOf(schema, e, profile)) {
                 if (!r.structural)
                     continue;
                 const target = r.targetColumn === "id" ? r.value : find(current, r.catalogue, r.targetColumn, r.value)?.id;

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/lib/validate/structural-model.js

@@ -162,7 +162,7 @@ export async function checkStructuralModel(repo, options = {}) {
     // The current view.
     const unresolved = new Set();
     const currentProblems = [];
-    validateView(schema, view, builtIn(built, allNew, new Set()), currentProblems, unresolved, addedBy);
+    validateView(schema, view, builtIn(built, allNew, new Set()), currentProblems, unresolved, addedBy, profile);
     problems.push(...currentProblems);
     const elementCount = [...view.values()].reduce((n, m) => n + m.size, 0);
     lines.push(files === null ? `model: none (${STRUCTURE_DIR}/ absent)` : `model: ${files.length} partition file(s), ${elementCount} element(s) in ${view.size} catalogue(s)`);
@@ -211,7 +211,7 @@ export async function checkStructuralModel(repo, options = {}) {
         if (s.noOp && s.deltas.length > 0)
             problems.push(`${s.noOp.file}: a no-op claim beside ${s.deltas.length} partition delta(s); state one or the other`);
         const elsewhere = new Map([...addedByChange].filter(([, c]) => c !== s.change));
-        validateDeltas(schema, view, s.deltas, elsewhere, problems);
+        validateDeltas(schema, view, s.deltas, elsewhere, problems, profile);
         // A behaviour delta for a feature the model does not hold needs that feature added here.
         const adds = new Set(s.deltas.flatMap((d) => d.added.filter((e) => e.catalogue === "features").map((e) => e.id)));
         for (const feature of await subdirs(join(repo, dir, "specs"))) {
@@ -238,7 +238,7 @@ export async function checkStructuralModel(repo, options = {}) {
         if (oc.structure.deltas.length === 0)
             continue;
         const at = [];
-        validateView(schema, viewAt(view, name, open), builtIn(built, allNew, additions.contracts(closure(name, open))), at, new Set(), addedBy);
+        validateView(schema, viewAt(view, name, open), builtIn(built, allNew, additions.contracts(closure(name, open))), at, new Set(), addedBy, profile);
         for (const p of at) {
             if (known.has(p))
                 continue;
@@ -250,7 +250,7 @@ export async function checkStructuralModel(repo, options = {}) {
     const agreed = agreedOrder(open);
     if (agreed.length > 0) {
         const inIntended = [];
-        validateView(schema, intended(view, open), builtIn(built, allNew, additions.contracts(agreed)), inIntended, new Set(), addedBy);
+        validateView(schema, intended(view, open), builtIn(built, allNew, additions.contracts(agreed)), inIntended, new Set(), addedBy, profile);
         for (const p of inIntended) {
             if (known.has(p) || atAgreed.has(p))
                 continue;

package/dist/maintain-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.17.2",
-  "built_against_sdd_cli": "5.3.2"
+  "version": "0.18.1",
+  "built_against_sdd_cli": "5.4.1"
 }

package/dist/verify-version.json

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sdd-method/author-cli",
-  "version": "0.16.2",
-  "sddCliVersion": "5.3.2",
+  "version": "0.17.1",
+  "sddCliVersion": "5.4.1",
   "description": "Re-author one SDD's content — scaffold, plan, contracts, conformance, api-surface, snapshots, briefings, catalogue check — plus every read-only verify verb. Ships only the code those verbs reach; it cannot sync the baseline or rebuild the catalogues. Maintenance is in @sdd-method/maintain-cli, administration in @sdd-method/sdd-cli.",
   "license": "UNLICENSED",
   "type": "module",