@sdd-method/verify-cli 5.4.3 → 5.5.1

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

@@ -173,7 +173,7 @@ export function observedInProblems(evidence) {
  * admits no behaviour may make (the caller decides; `none` is true and the list is empty).
  */
 /** What drives a service that serves no contract (sdm-xfln): the triggers `**Surfaces:** none served (...)` may name. */
-export const NONE_SERVED_TRIGGERS = ["scheduled", "queue-triggered", "stream-triggered"];
+export const NONE_SERVED_TRIGGERS = ["scheduled", "queue-triggered", "stream-triggered", "invoked"];
 export function parseSurfaces(evidence) {
     const lines = evidence.split("\n");
     // The LAST standalone line: an evidence file may carry an earlier prose section under the same label, and

package/dist/lib/catalogue/builders/feature-groups-prune.js

@@ -0,0 +1,19 @@
+export function pruneEmptyGroups(groups, features) {
+    const byId = new Map(groups.map((g) => [String(g["id"] ?? ""), g]));
+    const keep = new Set();
+    const climb = (id) => {
+        // Up the parent chain from a group a feature names; a cycle stops where it repeats.
+        let cur = id;
+        while (cur !== undefined && cur !== "" && byId.has(cur) && !keep.has(cur)) {
+            keep.add(cur);
+            cur = String(byId.get(cur)["parent_group_id"] ?? "");
+        }
+    };
+    for (const f of features)
+        climb(String(f["parent_group_id"] ?? ""));
+    return {
+        kept: groups.filter((g) => keep.has(String(g["id"] ?? ""))),
+        sections: groups.filter((g) => !keep.has(String(g["id"] ?? ""))),
+    };
+}
+//# sourceMappingURL=feature-groups-prune.js.map

package/dist/lib/catalogue/canonical-schema.yaml

@@ -7,7 +7,7 @@
 # Emitted by sdd-cli's YAML emitter with no line folding; the three header scalars are quoted for the
 # textual readers downstream. The one deliberate difference from the authored form is schema_status:
 # the authored form says canonical; a projection never does.
-schema_version: "7.2.0"
+schema_version: "7.3.0"
 schema_owner: "sdd-method"
 schema_status: "generated"
 enums:
@@ -2537,7 +2537,7 @@ catalogues:
       type: string
       nullable: false
       description: publishes | consumes.
-    description: "Edge: service publishes or consumes event."
+    description: "Edge: service publishes or consumes event. event_id is external (7.3.0), as service_contract.contract_id is: an event is an interface like a contract, so a service consuming another SDD's event names it here and the reference resolves at aggregation, where it is validated as internal."
     natural_key:
     - service_id
     - event_id
@@ -2549,6 +2549,7 @@ catalogues:
     - column: event_id
       references: events.id
       nullable: false
+      external: true
     column_enums:
       role: enums.event_participation
   service_entity:
@@ -3150,7 +3151,7 @@ catalogues:
       description: The platform this row belongs to — sdd_id of its platform-root. Stamped by the aggregator per M-ADR 0208 §4.4 (preserve-if-set, fill rule by pull path); left empty by per-SDD builders. Added in 3.7.0.
       source_of_truth: execution
     description: |
-      Edge: a C4 container depends on another INTERNAL container (the system-tier gap exactly one tier down: "no edge for internal" at L2). Derived by the aggregator at adjudication: an external-system candidate that resolves to an internal container was never external — each of its dependency edges whose member-resolved `from_container_id` is known is rewritten here, and a candidate with no remaining edges is dropped (it was a phantom duplicate of the container). A candidate with unconvertible edges is kept with the tier-contradiction finding, so no edge is ever destroyed to make a build quieter — the measured cost that stopped an adopter remediating 22 contradictions was eight real edges. ALSO emitted at member tier (2.33.1): the C4-correct authoring — Rel(container_a, container_b) between two Container(...) nodes — emits its edge directly; adjudication merges into a catalogue that already has content rather than being its only source, so the metamodel no longer rewards mis-declaration over correct authoring. Added in schema 2.33.0.
+      Edge: a C4 container depends on another INTERNAL container (the system-tier gap exactly one tier down: "no edge for internal" at L2). Derived by the aggregator at adjudication: an external-system candidate that resolves to an internal container was never external — each of its dependency edges whose member-resolved `from_container_id` is known is rewritten here, and a candidate with no remaining edges is dropped (it was a phantom duplicate of the container). A candidate with unconvertible edges is kept with the tier-contradiction finding, so no edge is ever destroyed to make a build quieter — the measured cost that stopped an adopter remediating 22 contradictions was eight real edges. ALSO emitted at member tier (2.33.1): the C4-correct authoring — Rel(container_a, container_b) between two Container(...) nodes — emits its edge directly; adjudication merges into a catalogue that already has content rather than being its only source, so the metamodel no longer rewards mis-declaration over correct authoring. Added in schema 2.33.0. to_container_id is external (7.3.0): a container may depend on a container another SDD owns (a platform container calling an application's private API once the application owns that container); the reference resolves at aggregation, where it is validated as internal, so the C4 L2 keeps the arrow.
     natural_key:
     - from_container_id
     - to_container_id
@@ -3161,6 +3162,7 @@ catalogues:
     - column: to_container_id
       references: c4_containers.id
       nullable: false
+      external: true
   system_system_dependency:
     primary_key: id
     source_of_truth: derived
@@ -3286,7 +3288,7 @@ catalogues:
       nullable: false
       description: spec | high | medium.
       source_of_truth: derived
-    description: "Edge: ADR informs capability. Forward: declared in capability spec Architecture Decisions. Reverse: same plus heuristic match supplements with confidence."
+    description: "Edge: ADR informs capability. Forward: declared in capability spec Architecture Decisions. Reverse: same plus heuristic match supplements with confidence. adr_id is external for application- and integration-product SDDs (7.3.0), as adrs.domain_id is: platform ADRs bind the applications built on the platform, so an application capability cites one the platform owns, and the owning platform's aggregate validates it."
     natural_key:
     - capability_id
     - adr_id
@@ -3297,6 +3299,9 @@ catalogues:
     - column: adr_id
       references: adrs.id
       nullable: false
+      external_for_profiles:
+      - application-product
+      - integration-product
     column_enums:
       confidence: enums.capability_adr_confidence
   adr_supersedes:

package/dist/lib/catalogue/coverage-predicates.js

@@ -392,7 +392,15 @@ function classifyContract(reachable, excluded, coveredAsEvent) {
  * refusal path (non-yaml extension, unreachable file, unparseable
  * content, non-mapping document → False, never a guess).
  */
-function hasNoOperations(sddRoot, specPath) {
+// The interface a contract describes, by its kind: an OpenAPI document's paths, a command manifest's commands
+// (`cli`), a UI surface manifest's custom elements and messages (`ui`, schema 7.2.0). Reading every YAML contract
+// as OpenAPI made a ui or cli manifest "not an interface" however much it described (reported by an adopter keying
+// a ui contract exactly as instructed).
+const NON_OPENAPI_INTERFACE = {
+    cli: ["commands"],
+    ui: ["elements", "messages"],
+};
+function hasNoOperations(sddRoot, specPath, kind = "") {
     if (!specPath || !(specPath.endsWith(".yaml") || specPath.endsWith(".yml"))) {
         return false;
     }
@@ -410,6 +418,9 @@ function hasNoOperations(sddRoot, specPath) {
         return false;
     }
     const d = doc;
+    const own = NON_OPENAPI_INTERFACE[kind];
+    if (own !== undefined)
+        return !own.some((k) => Array.isArray(d[k]) && d[k].length > 0);
     if (!("openapi" in d) && !("swagger" in d) && !("paths" in d))
         return true;
     const paths = d["paths"];
@@ -541,7 +552,7 @@ export async function runContractCoverage(session, options) {
             excluded = true;
             exclusionKey = "provider-surface";
         }
-        else if (hasNoOperations(options.sddRoot, sp)) {
+        else if (hasNoOperations(options.sddRoot, sp, kind)) {
             excluded = true;
             exclusionKey = "not-an-interface";
         }

package/dist/lib/catalogue/csv-writer.js

@@ -50,7 +50,7 @@ export async function writeCatalogue(opts) {
     // Refuse to replace rows with a bare header. Emitting one is correct when the
     // file is absent or already empty — that is the "consumers can rely on the
     // file existing" case — and is data loss when it is not.
-    if (opts.rows.length === 0) {
+    if (opts.rows.length === 0 && opts.emptiedDeliberately !== true) {
         const onDisk = await existingDataRows(filePath);
         if (onDisk > 0) {
             return { rowCount: onDisk, path: filePath, preserved: true, preservedRows: onDisk };

package/dist/lib/structure/empty-groups.js

@@ -0,0 +1,55 @@
+// Feature groups an admitted structural model holds with no feature beneath them (sdm-1al0). The catalogue build no
+// longer makes a group of such a heading, but a model extracted before that kept them, and a model changes only
+// through a judged change. So the structural-model check names them, and `structure prune-groups` writes the
+// structural delta that removes them into an open change. The change is judged and archived as any other.
+import { mkdir, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { stringify } from "yaml";
+import { pruneEmptyGroups } from "../catalogue/builders/feature-groups-prune.js";
+import { elementKey, FORMAT_VERSION } from "./model.js";
+import { revisionOf } from "./view.js";
+const rowsOf = (view, catalogue) => [...(view.get(catalogue)?.values() ?? [])].map((e) => ({ id: e.id, ...e.columns }));
+/** The model's feature groups no feature names as its parent group, directly or through a kept child group. */
+export function emptyGroups(view) {
+    const { sections } = pruneEmptyGroups(rowsOf(view, "feature_groups"), rowsOf(view, "features"));
+    const byId = view.get("feature_groups") ?? new Map();
+    return sections.map((s) => byId.get(String(s["id"]))).filter((e) => e !== undefined);
+}
+const REASON = "a heading with no feature beneath it is a section, not a feature group (sdm-1al0)";
+/**
+ * Write the structural delta removing every empty group into the open change `change`, one file per partition.
+ * Refuses when the change is absent (it is opened the usual way, so it carries its own proposal and agreement), or
+ * already has a structural delta for that partition. Returns the files written, relative to the SDD.
+ */
+export async function writePruneDelta(sddPath, change, view) {
+    const dir = join("openspec", "changes", change);
+    if (!(await stat(join(sddPath, dir)).then((s) => s.isDirectory(), () => false))) {
+        return { files: [], removed: 0, refused: `${dir} does not exist: open the change first (its proposal states why), then write its delta` };
+    }
+    const empty = emptyGroups(view);
+    const byPartition = new Map();
+    for (const e of empty)
+        (byPartition.get(e.partition) ?? byPartition.set(e.partition, []).get(e.partition)).push(e);
+    const files = [];
+    for (const [partition, groups] of [...byPartition].sort(([a], [b]) => a.localeCompare(b))) {
+        const rel = join(dir, "structure", `${partition}.yaml`);
+        if (await stat(join(sddPath, rel)).then(() => true, () => false)) {
+            return { files, removed: 0, refused: `${rel} already exists; a change carries one delta per partition, so add the removals to it by hand or use another change` };
+        }
+        const sorted = [...groups].sort((a, b) => a.id.localeCompare(b.id));
+        const base = {};
+        for (const g of sorted)
+            base[elementKey(g.catalogue, g.id)] = revisionOf(g);
+        const text = stringify({
+            schema_version: FORMAT_VERSION,
+            partition,
+            REMOVED: { feature_groups: sorted.map((g) => ({ id: g.id, reason: REASON })) },
+            base,
+        });
+        await mkdir(join(sddPath, dir, "structure"), { recursive: true });
+        await writeFile(join(sddPath, rel), text);
+        files.push(rel);
+    }
+    return { files, removed: empty.length };
+}
+//# sourceMappingURL=empty-groups.js.map

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

@@ -273,6 +273,25 @@ async function gitShow(repo, commit, path) {
         return null;
     }
 }
+/** Files under a directory on disk, relative to it, sorted. */
+async function filesUnder(root, rel = "") {
+    const out = [];
+    let entries;
+    try {
+        entries = await readdir(join(root, rel), { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        const p = rel ? `${rel}/${e.name}` : e.name;
+        if (e.isDirectory())
+            out.push(...(await filesUnder(root, p)));
+        else
+            out.push(p);
+    }
+    return out.sort();
+}
 /** Paths under a directory at a commit, relative to that directory. */
 async function gitFiles(repo, commit, dir) {
     try {
@@ -1133,6 +1152,46 @@ export async function checkBehaviourStore(repo, options = {}) {
         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` : ""}${generatedBaselines ? `; ${generatedBaselines} generator baseline(s) serving no contract, Surfaces: generated` : ""}${noneServedBaselines ? `; ${noneServedBaselines} baseline(s) of services serving no contract, Surfaces: none served` : ""}${historical.size ? `; ${historical.size} historical baseline(s) not checked (every requirement they baselined has left the living specs)` : ""}`);
+    // Archive integrity (sdm-9sk1): what MERGED is not edited. An archived change's spec deltas and structural deltas
+    // (specs/**, structure/** with applied.yaml) are what entered the living model and what the history catalogues are
+    // derived from (requirement_lineage, revisions, change_effects); editing one after it archived makes the history
+    // claim something entered that never did. A mistake there is fixed by a new change (a corrective baseline, for a
+    // baseline). Every other file of an archived change is bookkeeping (evidence notes, errata, tasks, a deferral) and may
+    // be corrected; git is the record of who changed what. Each archived change is compared with its tree at the commit
+    // that added it; without git history the check is unresolved, never a pass.
+    if (history) {
+        let checkedArchives = 0;
+        let payloadFiles = 0;
+        let bookkeepingEdits = 0;
+        const payload = (f) => f.startsWith("specs/") || f.startsWith("structure/");
+        for (const name of order) {
+            const dir = `${archiveRel}/${name}`;
+            const at = await integratedAt(repo, dir);
+            if (at === null)
+                continue; // not yet committed: nothing archived to compare with
+            checkedArchives++;
+            const then = new Set(await gitFiles(repo, at, dir));
+            const now = new Set(await filesUnder(join(repo, dir)));
+            for (const f of [...new Set([...then, ...now])].sort()) {
+                const before = then.has(f) ? await gitShow(repo, at, `${dir}/${f}`) : null;
+                const after = now.has(f) ? await readText(join(repo, dir, f)) : null;
+                if (payload(f))
+                    payloadFiles++;
+                if (before === after)
+                    continue;
+                if (!payload(f)) {
+                    bookkeepingEdits++;
+                    continue;
+                }
+                const what = before === null ? "added to" : after === null ? "removed from" : "edited in";
+                failures.push(`${dir}/${f}: ${what} an archived change after it archived (at ${at.slice(0, 12)}); its spec and structural deltas are what merged into the living model, so a mistake there is fixed by a new change (a corrective baseline, for a baseline), not by editing the archive`);
+            }
+        }
+        lines.push(`archive integrity: ${checkedArchives} archived change(s), ${payloadFiles} merged delta file(s) compared with the commit that archived them${bookkeepingEdits ? `; ${bookkeepingEdits} later correction(s) to bookkeeping files (evidence, tasks, notes), which may be corrected` : ""}`);
+    }
+    else if (archived.length > 0) {
+        lines.push("archive integrity: not checked (no git history: run from a clone)");
+    }
     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");
@@ -1351,6 +1410,7 @@ export async function checkBehaviourStoreOpenspec(repo) {
     }
     const lines = [];
     const failures = [];
+    const warnings = [];
     let measured = 0;
     for (const [label, args] of [
         ["specs and open changes (--all --strict)", ["validate", "--all", "--strict", "--json", "--no-interactive"]],
@@ -1367,8 +1427,27 @@ export async function checkBehaviourStoreOpenspec(repo) {
         for (const item of r.json?.items ?? []) {
             if (item.valid)
                 continue;
-            for (const i of item.issues ?? [])
+            for (const i of item.issues ?? []) {
+                // An archived change's task deliberately left undone, recorded as deferred with its reason and tracking id
+                // (sdm-7dmx), is a warning, not a failure. OpenSpec counts `- [~]` as incomplete, so the count it reports is
+                // compared with the deferred lines it can be accounted for by.
+                const inc = args[1] === "--archived" && i.path === "tasks.md" ? INCOMPLETE_RE.exec(i.message ?? "") : null;
+                if (inc) {
+                    const tasks = (await readText(join(repo, STORE_DIR, "changes", "archive", item.id, "tasks.md"))) ?? "";
+                    const d = deferredTasks(tasks);
+                    if (d.malformed.length === 0 && d.open === 0 && d.deferred.length === Number(inc[1])) {
+                        warnings.push(`${label}: ${item.id}: ${d.deferred.length} task(s) deferred: ${d.deferred.map((x) => `"${x.task}" (${x.reason}; ${x.id})`).join(", ")}; a deferred task is not done, and is no evidence of it`);
+                        continue;
+                    }
+                    const why = [
+                        d.open > 0 ? `${d.open} unticked` : "",
+                        d.malformed.length > 0 ? `${d.malformed.length} "- [~]" line(s) without "(deferred: <reason>; <tracking id>)": ${d.malformed.map((m) => JSON.stringify(m)).join(", ")}` : "",
+                    ].filter(Boolean).join("; ");
+                    failures.push(`${label}: ${item.id} (tasks.md): ${i.level} ${i.message}${why ? ` (${why}); a task deliberately left undone is written "- [~] <task> (deferred: <reason>; <tracking id>)"` : ""}`);
+                    continue;
+                }
                 failures.push(`${label}: ${item.id}${i.path ? ` (${i.path})` : ""}: ${i.level} ${i.message}`);
+            }
             if ((item.issues ?? []).length === 0)
                 failures.push(`${label}: ${item.id}: invalid`);
         }
@@ -1417,10 +1496,31 @@ export async function checkBehaviourStoreOpenspec(repo) {
     }
     lines.push(`dry archive: ${dryArchived} open, agreed change(s) archived in a copy`);
     const body = [`  OpenSpec ${version}`, ...lines.map((l) => `  ${l}`)].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}`).join("\n") + "\n" };
+        return { exitCode: 1, stdout: body + warn + failures.map((f) => `[FAIL] ${f}`).join("\n") + "\n" };
     if (measured === 0)
         return { exitCode: 0, stdout: body + "[N/A] OpenSpec found no specs and no changes to validate\n" };
-    return { exitCode: 0, stdout: body + "[PASS] OpenSpec strict validation holds\n" };
+    return { exitCode: 0, stdout: body + warn + `[PASS] OpenSpec strict validation holds${warnings.length ? ", with the deferred tasks above" : ""}\n` };
+}
+const INCOMPLETE_RE = /^(\d+) incomplete tasks?\b/;
+const DEFERRED_RE = /^\s*-\s+\[~\]\s+(.+?)\s+\(deferred:\s*([^;)]*?\S)\s*;\s*([^;)]*?\S)\s*\)\s*\.?\s*$/;
+/** A tasks.md's deferred tasks, its malformed `- [~]` lines, and how many tasks are simply unticked. */
+export function deferredTasks(tasks) {
+    const deferred = [];
+    const malformed = [];
+    let open = 0;
+    for (const line of tasks.split("\n")) {
+        if (/^\s*-\s+\[ \]/.test(line))
+            open++;
+        else if (/^\s*-\s+\[~\]/.test(line)) {
+            const m = DEFERRED_RE.exec(line);
+            if (m)
+                deferred.push({ task: m[1], reason: m[2], id: m[3] });
+            else
+                malformed.push(line.trim());
+        }
+    }
+    return { deferred, malformed, open };
 }
 //# sourceMappingURL=behaviour-store.js.map

package/dist/lib/validate/structural-model.js

@@ -37,6 +37,7 @@
 // Enforced (the release that accepts M-ADR 0230): every finding is a [FAIL] and the check
 // exits 1; with ENFORCED false it reports them as [WARN] and exits 0. Without openspec/structure/ and with no change
 // carrying a structure/ directory it reports [N/A], so an SDD without a model is unaffected.
+import { emptyGroups } from "../structure/empty-groups.js";
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { parseDocument } from "yaml";
@@ -274,7 +275,11 @@ export async function checkStructuralModel(repo, options = {}) {
     if (raw > 0)
         lines.push(`archived changes whose structure is not applied: ${raw}`);
     lines.push(`views: current; at each of ${[...open.values()].filter((o) => o.structure.deltas.length > 0).length} change(s) with deltas; intended from ${agreed.length} agreed change(s)`);
-    const body = lines.map((l) => `${l}\n`).join("") + removals.findings.map((w) => `[WARN] ${w}\n`).join("");
+    // Feature groups the model holds with no feature beneath them: sections a pre-1al0 extraction made groups of. They
+    // leave through a judged change; `structure prune-groups --change <name>` writes its delta (sdm-1al0).
+    const empty = emptyGroups(view);
+    const emptyWarn = empty.length === 0 ? [] : [`model: ${empty.length} feature group(s) hold no feature (${empty.slice(0, 5).map((e) => e.id).join(", ")}${empty.length > 5 ? ", ..." : ""}): headings that are sections, not groups; remove them through a change (sdd-cli structure prune-groups --change <name> writes its delta)`];
+    const body = lines.map((l) => `${l}\n`).join("") + [...removals.findings, ...emptyWarn].map((w) => `[WARN] ${w}\n`).join("");
     if (problems.length === 0)
         return { exitCode: 0, stdout: `structural-model:\n${body}[PASS] structural-model: ok\n` };
     const tag = enforced ? "FAIL" : "WARN";

package/dist/maintain-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.18.3",
-  "built_against_sdd_cli": "5.4.3"
+  "version": "0.19.1",
+  "built_against_sdd_cli": "5.5.1"
 }

package/dist/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "5.4.3",
-  "built_against_sdd_cli": "5.4.3"
+  "version": "5.5.1",
+  "built_against_sdd_cli": "5.5.1"
 }

package/package.json

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