@sdd-method/sdd-cli 5.2.0 → 5.3.0

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

@@ -34,13 +34,17 @@
 //                 change was withdrawn or replaced (M-ADR 0222 §4.6).
 //   5. surfaces: every archived baseline's evidence lists, under **Surfaces:**, each contract the
 //                 repositories it was observed in serve, as covered at transport or excluded with a
-//                 reason, and the list is checked against the catalogue (catalogues/repo_contract.csv),
-//                 never against itself (M-ADR 0222 §4.3, §4.4). A list the catalogue gives nothing to
+//                 reason, and the list is checked against the catalogue (catalogues/repo_contract.csv, less
+//                 a contract service_contract records the repository's services consuming and none exposing:
+//                 repo_contract has no direction), never against itself (M-ADR 0222 §4.3, §4.4). A list the catalogue gives nothing to
 //                 check against (no Observed in line, or a repository with no catalogue contracts) fails:
 //                 a cross-check of zero contracts is unresolved, not a pass.
 //                 A baseline whose every requirement has since left the living specs (removed, or its
 //                 spec retired) is history: its list is not checked, so a retired surface can drop its
-//                 contract (M-ADR 0222 §4.4).
+//                 contract (M-ADR 0222 §4.4). A baseline archived where the SDD ships record schema 1.4.0
+//                 or later records its gate's PASS (**Baseline gate:**), so `change archive` refuses one
+//                 that has not passed (M-ADR 0222 §4.3). An open baseline is asked these questions, and
+//                 what it may change and which features key it, as warnings while it can still be fixed.
 //   7. features: every living spec is keyed by a catalogue feature (M-ADR 0221 §4.7). A spec keyed by no
 //                 feature is dropped from the catalogue by the requirements builder, which reports it only as a
 //                 build finding; this check makes it a failure, so a shipped requirement cannot vanish from the
@@ -69,11 +73,11 @@ import { tmpdir } from "node:os";
 import { basename, join } from "node:path";
 import { promisify } from "node:util";
 import { parseDocument } from "yaml";
-import { observedIn, orderArchives, parseRequirements, parseSurfaces, renamedFrom, renamePairs, resolveImplements, surfaceMatches } from "../behaviour-store/archive.js";
+import { contractMoves, observedIn, 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";
-import { compareStoreSchema, SCHEMA_NAME, SHIPPED_SCHEMA_DIR, STORE_CONFIG, STORE_SCHEMA_DIR, storeSchemaName } from "../behaviour-store/schema.js";
+import { BASELINE_SCHEMA_NAME, compareStoreSchema, SCHEMA_NAME, SHIPPED_SCHEMA_DIR, shippedSchemaDir, STORE_CONFIG, STORE_SCHEMA_DIR, storeSchemaDir, storeSchemaName } from "../behaviour-store/schema.js";
 const execFileAsync = promisify(execFile);
 /** The OpenSpec release the method depends on (M-ADR 0223 ruling 2). The module installs exactly this. */
 export const OPENSPEC_VERSION = "1.14.3";
@@ -86,6 +90,8 @@ const COMMIT_RE = /^[0-9a-f]{7,40}$/;
 // OpenSpec counts a task done when its box holds only `x`, either case, any spacing.
 const TASK_DONE_RE = /^\s*-\s*\[\s*[xX]\s*\]/m;
 const TARGET_HEADING_RE = /^##\s+(MODIFIED|REMOVED|RENAMED)\s+Requirements\b/m;
+// A tasks.md group headed by one word, `## <n>. <word>`, is that repository's work order (taskGroups).
+const GROUP_REPO = (repo) => `tasks.md has a work order for ${repo} and the record's work_orders do not; its evidence cannot be checked (a group heading of one word, \`## <n>. ${repo}\`, names the group's repository)`;
 async function exists(p) {
     try {
         await access(p);
@@ -516,6 +522,14 @@ export async function checkBehaviourStore(repo, options = {}) {
                 }
             }
         }
+        // The archive check reads a task group's repository from its heading; once the record declares work orders, a
+        // heading it would read as a repository the record lacks fails here, while the change can still be amended.
+        if (versionAtLeast(record?.schemaVersion, "1.1.0") && record?.status === "agreed" && record.workOrders.length > 0 && tasks !== null) {
+            const recorded = new Set(record.workOrders.map((w) => w.repo));
+            for (const g of taskGroups(tasks))
+                if (!recorded.has(g.repo))
+                    failures.push(`${record.file}: ${GROUP_REPO(g.repo)}`);
+        }
         // A test plan's kinds (M-ADR 0223 §4.4 as amended): changed and repaired scenarios go red then green, carried ones stay green.
         if (versionAtLeast(record?.schemaVersion, "1.1.0") && record?.status === "agreed") {
             const plan = await readText(join(repo, dir, "test-plan.md"));
@@ -717,7 +731,7 @@ export async function checkBehaviourStore(repo, options = {}) {
         const recorded = new Set(record.workOrders.map((w) => w.repo));
         for (const g of groups)
             if (!recorded.has(g.repo))
-                failures.push(`${record.file}: tasks.md has a work order for ${g.repo} and the record's work_orders do not; its evidence cannot be checked`);
+                failures.push(`${record.file}: ${GROUP_REPO(g.repo)}`);
         // Requirement names are unique within a feature, not across a change: a work order names `<feature>::<name>`,
         // or a bare name only one feature in the change has (schema 5.0.0). An ambiguous bare name implements nothing.
         const built = [];
@@ -818,8 +832,107 @@ export async function checkBehaviourStore(repo, options = {}) {
     }
     const orderDecides = (name, key) => [...(peers.get(name) ?? [])].some((p) => p !== name && touches.get(p)?.has(key));
     let scopeUnresolved = 0;
-    const servedBy = baselines > 0 ? await catalogueContracts(repo) : null;
+    const openBaselines = [];
+    for (const change of open)
+        if (await exists(join(repo, STORE_DIR, "changes", change, "baseline-evidence.md")))
+            openBaselines.push(change);
+    const servedBy = baselines + openBaselines.length > 0 ? await catalogueContracts(repo) : null;
     let surfacesChecked = 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.
+    const movesAt = [];
+    for (const name of order) {
+        const found = [];
+        let names = [];
+        try {
+            names = (await readdir(join(repo, archiveRel, name, "structure"))).filter((f) => f.endsWith(".yaml")).sort();
+        }
+        catch {
+            names = [];
+        }
+        for (const f of names) {
+            try {
+                found.push(...contractMoves(parseDocument((await readText(join(repo, archiveRel, name, "structure", f))) ?? "").toJS()?.["moved"]).moves);
+            }
+            catch {
+                // the structural-model check reports an unreadable delta
+            }
+        }
+        movesAt.push(found);
+    }
+    // An open change's moves count too, after every archive: the catalogue it is built with already holds the new
+    // identity, so the lists that named the old one follow the move while it is open, not only once it archives.
+    const openMoves = [];
+    for (const change of open) {
+        let names = [];
+        try {
+            names = (await readdir(join(repo, STORE_DIR, "changes", change, "structure"))).filter((f) => f.endsWith(".yaml")).sort();
+        }
+        catch {
+            names = [];
+        }
+        for (const f of names) {
+            try {
+                openMoves.push(...contractMoves(parseDocument((await readText(join(repo, STORE_DIR, "changes", change, "structure", f))) ?? "").toJS()?.["moved"]).moves);
+            }
+            catch {
+                // the structural-model check reports an unreadable delta
+            }
+        }
+    }
+    /** The identities a contract had before the moves archived after position `after` (-1: every archived move). */
+    const formerIdentities = (id, after) => {
+        const back = new Map();
+        for (const m of [...movesAt.slice(after + 1).flat(), ...openMoves])
+            back.set(m.to, [...(back.get(m.to) ?? []), m]);
+        const out = [];
+        const seen = new Set([id]);
+        const queue = [id];
+        while (queue.length > 0) {
+            for (const m of back.get(queue.shift()) ?? []) {
+                if (seen.has(m.from))
+                    continue;
+                seen.add(m.from);
+                out.push({ id: m.from, path: m.fromPath ?? "" });
+                queue.push(m.from);
+            }
+        }
+        return out;
+    };
+    /** 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 parsed = parseSurfaces(evidence);
+        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)
+            out.push(`${dir}/baseline-evidence.md: Surfaces: ${p}`);
+        if (!parsed.present)
+            return out;
+        if (servedBy === null) {
+            out.push(`${dir}/baseline-evidence.md: Surfaces 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 cannot be cross-checked: no **Observed in:** line names a repository`);
+        for (const r of repos) {
+            const known = servedBy.get(r);
+            if ((known?.served ?? []).length === 0) {
+                const consumed = known?.consumed ? ` (it consumes ${known.consumed}, which a baseline does not list)` : "";
+                out.push(`${dir}/baseline-evidence.md: Surfaces cannot be cross-checked: the catalogue records no contract that ${r} serves${consumed}; declare the contracts it serves in its repo-config`);
+            }
+            for (const c of known?.served ?? []) {
+                surfacesChecked++;
+                const former = formerIdentities(c.id, after);
+                if (!parsed.entries.some((e) => surfaceMatches(e.contract, c.id, c.specPath) || former.some((f) => surfaceMatches(e.contract, f.id, f.path)))) {
+                    out.push(`${dir}/baseline-evidence.md: Surfaces does not list ${c.specPath || c.id} (${c.id}), which ${r} serves (catalogues/repo_contract.csv, less what service_contract records it only consuming); list it as covered at transport or excluded with a reason`);
+                }
+            }
+        }
+        return out;
+    };
     // A baseline whose every requirement has since left the living specs (removed, or its spec retired) records a
     // surface that no longer exists; its Surfaces list is history, not checked against today's catalogue, or a
     // retired surface could never drop its contract.
@@ -831,33 +944,23 @@ export async function checkBehaviourStore(repo, options = {}) {
         const evidence = await readText(join(repo, dir, "baseline-evidence.md"));
         const isBaseline = evidence !== null;
         if (isBaseline) {
-            const parsed = parseSurfaces(evidence);
-            if (!parsed.present)
-                failures.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)
-                failures.push(`${dir}/baseline-evidence.md: Surfaces: ${p}`);
-            if (parsed.present && historical.has(name)) {
-                // history: see historicalBaselines
+            if (historical.has(name)) {
+                // history: see historicalBaselines; its gate and Surfaces list are not checked
+                const parsed = parseSurfaces(evidence);
+                if (!parsed.present)
+                    failures.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)
+                    failures.push(`${dir}/baseline-evidence.md: Surfaces: ${p}`);
             }
-            else if (parsed.present) {
-                if (servedBy === null) {
-                    failures.push(`${dir}/baseline-evidence.md: Surfaces cannot be cross-checked: catalogues/repo_contract.csv or catalogues/contracts.csv is missing; build the catalogue`);
-                }
-                else {
-                    const repos = observedIn(evidence);
-                    if (repos.length === 0)
-                        failures.push(`${dir}/baseline-evidence.md: Surfaces cannot be cross-checked: no **Observed in:** line names a repository`);
-                    for (const r of repos) {
-                        if ((servedBy.get(r) ?? []).length === 0) {
-                            failures.push(`${dir}/baseline-evidence.md: Surfaces cannot be cross-checked: catalogues/repo_contract.csv records no contract for ${r}; declare the contracts it serves in its repo-config`);
-                        }
-                        for (const c of servedBy.get(r) ?? []) {
-                            surfacesChecked++;
-                            if (!parsed.entries.some((e) => surfaceMatches(e.contract, c.id, c.specPath))) {
-                                failures.push(`${dir}/baseline-evidence.md: Surfaces does not list ${c.specPath || c.id} (${c.id}), which ${r} serves (catalogues/repo_contract.csv); list it as covered at transport or excluded with a reason`);
-                            }
-                        }
-                    }
+            else {
+                failures.push(...(await surfaceProblems(dir, evidence, order.indexOf(name))));
+                // The gate's outcome is recorded where the SDD ships record schema 1.4.0 or later when the baseline archives;
+                // a baseline archived earlier carries none and is not held to it.
+                const archivedAt = await integratedAt(repo, dir);
+                if (versionAtLeast(await shippedRecordSchema(repo, archivedAt), "1.4.0")) {
+                    const gate = baselineGate(evidence);
+                    if (gate !== "PASS")
+                        failures.push(`${dir}/baseline-evidence.md: archived ${gate === null ? "with no **Baseline gate:** line" : `with **Baseline gate:** ${gate}`}; a baseline archives once its gate passes: every requirement cites its evidence, characterization tests exist where the code has none, and every covered surface is evidenced at its transport (M-ADR 0222 §4.3)`);
                 }
             }
         }
@@ -892,8 +995,34 @@ export async function checkBehaviourStore(repo, options = {}) {
                 lastTouch.delete(`${feature}::${from}`);
         }
     }
-    const unseen = servedBy === null ? "" : `; repositories with no catalogue contracts: ${[...new Set(await observedInAll(repo, archiveRel, order))].filter((r) => (servedBy.get(r) ?? []).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${unseen}${historical.size ? `; ${historical.size} historical baseline(s) not checked (every requirement they baselined has left the living specs)` : ""}`);
+    // An open baseline is asked the archive's questions while it can still be fixed: its Surfaces list, what it may
+    // change given the lineage so far, the features its deltas are keyed by, and its gate. Warnings, since it is in
+    // progress; `change archive` refuses what is still wrong when it archives.
+    const featureIds = await readText(join(repo, "catalogues", "features.csv")).then((t) => (t === null ? null : new Set(parseCatalogueCsv(t).rows.map((r) => r["id"] ?? ""))));
+    for (const change of openBaselines) {
+        const dir = `${STORE_DIR}/changes/${change}`;
+        const evidence = (await readText(join(repo, dir, "baseline-evidence.md"))) ?? "";
+        const found = [...(await surfaceProblems(dir, evidence))];
+        for (const feature of await dirs(join(repo, dir, "specs"))) {
+            if (featureIds !== null && !featureIds.has(feature))
+                found.push(`${dir}/specs/${feature}: no catalogue feature has the id "${feature}"; give the behaviour a feature first (M-ADR 0222 §4.4)`);
+            const text = (await readText(join(repo, dir, "specs", feature, "spec.md"))) ?? "";
+            for (const target of [...parseRequirements(text).filter((r) => r.operation === "MODIFIED" || r.operation === "REMOVED").map((r) => r.name), ...renamedFrom(text)]) {
+                scopeChecked++;
+                const last = lastTouch.get(`${feature}::${target}`);
+                if (last !== "baseline")
+                    found.push(`${dir}: a baseline changes "${target}" (${feature}), which ${last === "change" ? "a judged change last shipped" : "no earlier archived change admitted"}; a baseline may remove or modify only what a baseline admitted (M-ADR 0222 §4.4)`);
+            }
+        }
+        const gate = baselineGate(evidence);
+        if (gate !== "PASS")
+            found.push(`${dir}/baseline-evidence.md: ${gate === null ? "no **Baseline gate:** line yet" : `**Baseline gate:** ${gate}`}; it archives once the gate passes (M-ADR 0222 §4.3)`);
+        warnings.push(...found.map((w) => `open baseline: ${w}`));
+    }
+    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}${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");
@@ -944,6 +1073,29 @@ export async function checkBehaviourStore(repo, options = {}) {
             lines.push(drift === 0 ? `schema: ${SCHEMA_NAME}, identical to the shipped copy` : `schema: ${SCHEMA_NAME}, ${drift} file(s) differ from the shipped copy`);
         }
     }
+    // The baseline schema: checked as sdd-change is where the bundle ships it (a bundle from before it shipped has none),
+    // and an open baseline selects it rather than sdd-change, whose Gate 0, test plan and agreement a baseline lacks.
+    if (selected === SCHEMA_NAME) {
+        const b = await compareStoreSchema(repo, BASELINE_SCHEMA_NAME);
+        if (b.shipped) {
+            const fix = "sdd-cli sync refreshes it; put adopter guidance in the store's config.yaml rules, not in the schema";
+            for (const f of b.missing)
+                failures.push(`${storeSchemaDir(BASELINE_SCHEMA_NAME)}/${f}: missing from the store's copy of the schema; ${fix}`);
+            for (const f of b.differing)
+                failures.push(`${storeSchemaDir(BASELINE_SCHEMA_NAME)}/${f}: differs from the shipped ${shippedSchemaDir(BASELINE_SCHEMA_NAME)}/${f}; ${fix}`);
+            for (const f of b.extra)
+                failures.push(`${storeSchemaDir(BASELINE_SCHEMA_NAME)}/${f}: not in the shipped schema; ${fix}`);
+            const drift = b.missing.length + b.differing.length + b.extra.length;
+            lines.push(drift === 0 ? `schema: ${BASELINE_SCHEMA_NAME}, identical to the shipped copy` : `schema: ${BASELINE_SCHEMA_NAME}, ${drift} file(s) differ from the shipped copy`);
+            for (const change of openBaselines) {
+                const meta = await readText(join(repo, STORE_DIR, "changes", change, ".openspec.yaml"));
+                const chosen = meta === null ? null : parseDocument(meta).toJS()?.schema;
+                if (chosen !== BASELINE_SCHEMA_NAME) {
+                    warnings.push(`open baseline: ${STORE_DIR}/changes/${change}/.openspec.yaml selects ${chosen === null || chosen === undefined ? "no schema" : `"${String(chosen)}"`}; a baseline selects ${BASELINE_SCHEMA_NAME} (schema: ${BASELINE_SCHEMA_NAME}), whose artifacts are a baseline's rather than a change's Gate 0, test plan and agreement`);
+                }
+            }
+        }
+    }
     const population = recordFiles.length + open.length + archived.length;
     const body = lines.map((l) => `  ${l}`).join("\n") + "\n";
     if (failures.length > 0) {
@@ -1002,25 +1154,47 @@ async function historicalBaselines(repo, archiveRel, order) {
     });
     return out;
 }
-/** Per repository, the contracts the catalogue says it serves (repo_contract ⋈ contracts.spec_path); null when either file is missing. */
+/**
+ * Per repository, the contracts the catalogue says it serves, with how many it only consumes; null when repo_contract or
+ * contracts is missing. repo_contract binds a repository to a contract in either direction, so a row is dropped where
+ * service_contract records the repository's services consuming that contract and none exposing it. Rows
+ * service_contract says nothing about stay: a model that omits a service's exposes rows does not shrink what is checked.
+ */
 async function catalogueContracts(repo) {
     const rc = await readText(join(repo, "catalogues", "repo_contract.csv"));
     const cs = await readText(join(repo, "catalogues", "contracts.csv"));
     if (rc === null || cs === null)
         return null;
     const spec = new Map(parseCatalogueCsv(cs).rows.map((r) => [r["id"] ?? "", r["spec_path"] ?? ""]));
+    const repoOf = new Map(parseCatalogueCsv((await readText(join(repo, "catalogues", "services.csv"))) ?? "").rows.map((r) => [r["id"] ?? "", r["primary_repo_id"] ?? ""]));
+    const roles = new Map();
+    for (const r of parseCatalogueCsv((await readText(join(repo, "catalogues", "service_contract.csv"))) ?? "").rows) {
+        const key = `${repoOf.get(r["service_id"] ?? "") ?? ""}\u0000${r["contract_id"] ?? ""}`;
+        roles.set(key, (roles.get(key) ?? new Set()).add(r["role"] ?? ""));
+    }
     const out = new Map();
     for (const r of parseCatalogueCsv(rc).rows) {
         const repoId = r["repo_id"] ?? "";
         const id = r["contract_id"] ?? "";
         if (repoId === "" || id === "")
             continue;
-        const list = out.get(repoId) ?? [];
-        list.push({ id, specPath: spec.get(id) ?? "" });
-        out.set(repoId, list);
+        const entry = out.get(repoId) ?? { served: [], consumed: 0 };
+        const role = roles.get(`${repoId}\u0000${id}`);
+        if (role?.has("consumes") && !role.has("exposes"))
+            entry.consumed++;
+        else
+            entry.served.push({ id, specPath: spec.get(id) ?? "" });
+        out.set(repoId, entry);
     }
     return out;
 }
+/** A baseline's recorded gate outcome: the last `**Baseline gate:** <outcome>` line's first word, upper-cased; null when there is none. */
+function baselineGate(evidence) {
+    let out = null;
+    for (const m of evidence.matchAll(/^\s*\*\*Baseline gate:\*\*\s*(\S+)/gm))
+        out = m[1].replace(/[^A-Za-z]/g, "").toUpperCase();
+    return out;
+}
 async function observedInAll(repo, archiveRel, names) {
     const out = [];
     for (const n of names) {