@sdd-method/author-cli 0.4.0 → 0.6.0

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: "3.20.0"
+schema_version: "4.0.0"
 schema_owner: "sdd-method"
 schema_status: "generated"
 enums:
@@ -389,7 +389,7 @@ enums:
     description: M-ADR 0159 entity persistence kind. Bound at 3.13.0 from the column descriptions; measured against both reference estates before binding (M-ADR 0205 §4.4).
   required_stability:
     values:
-    - value: locked
+    - value: stable
     - value: provisional
     - value: unknown
     description: "M-ADR 0204: the stability a consumer requires of a target; external | legacy live in target_locus, not here. Bound at 3.13.0 from the column descriptions; measured against both reference estates before binding (M-ADR 0205 §4.4)."
@@ -613,6 +613,35 @@ enums:
     - value: generated-from
       description: Its content was produced from the other repository's templates.
     description: How one repository depends on another's code (M-ADR 0217 §4.1).
+  requirement_stage:
+    values:
+    - value: living
+      description: "In the living spec: shipped behaviour."
+    - value: agreed
+      description: Added by an open change whose agreement record is agreed; not yet shipped.
+    description: Where a catalogued requirement stands (M-ADR 0221 §4.4).
+  requirement_change_kind:
+    values:
+    - value: baseline
+      description: Recorded existing behaviour through the baseline gate.
+    - value: change
+      description: A delta agreed, built and judged through the change gate.
+    description: What kind of archived change a lineage row names (M-ADR 0222 §4.3).
+  requirement_operation:
+    values:
+    - value: ADDED
+    - value: MODIFIED
+    - value: RENAMED
+    description: How a change's delta treated a requirement that is current now (a removed requirement has no row).
+  requirement_status_value:
+    values:
+    - value: agreed
+      description: In an agreed, open change.
+    - value: declared-shipped
+      description: Its change archived on a passing judge, with this repository's task group complete.
+    - value: observed
+      description: Independent evidence from this repository's code matches (a baseline's characterization tests or a reverse snapshot).
+    description: A requirement's status in one implementing repository (M-ADR 0221 §4.5).
 catalogues:
   domains:
     primary_key: id
@@ -1276,7 +1305,7 @@ catalogues:
     - name: contract_provenance
       type: string
       nullable: true
-      description: "How this capability's declared contract SET was produced, from `traceability.contracts.provenance`. hand-authored | reverse-extracted | generated — the vocabulary the method already ships for `authoring-mode`, reused deliberately so provenance has one vocabulary and not two. Empty means undeclared, and undeclared reads as `hand-authored` by convention. Added at 3.5.0. ⚠ STRICTLY ORTHOGONAL to the contract-set maturity ladder (`traceability.contracts.status`: planned | provisional | partial | complete | locked | none): provenance never constrains status and status never constrains provenance, and `reverse-extracted` + `complete` is the legitimate pair that motivated the field. Evidence: 2 reverse-estate manifests had written `reverse-extracted` INTO contracts.status, where it is invalid, because a complete reverse-derived contract surface had no way to say both true things at once and the author picked the provenance one. A rule here that constrained maturity would re-create exactly that defect. ⚠ Note the asymmetry this column exposes and does not fix: the maturity ladder it is orthogonal to has NO catalogue column at all — `traceability.contracts.status` is validator-enforced but uncatalogued, so it is queryable by no consumer. That is the authored-but-uncatalogued class (a block with no column has no automated reader, so nothing can notice when it is absent or wrong); this column is given one precisely so the provenance half does not join it. Giving the ladder a column is a candidate follow-on, not done here."
+      description: "How this capability's declared contract SET was produced, from `traceability.contracts.provenance`. hand-authored | reverse-extracted | generated — the vocabulary the method already ships for `authoring-mode`, reused deliberately so provenance has one vocabulary and not two. Empty means undeclared, and undeclared reads as `hand-authored` by convention. Added at 3.5.0. ⚠ STRICTLY ORTHOGONAL to the contract-set maturity ladder (`traceability.contracts.status`: planned | provisional | partial | complete | stable | none): provenance never constrains status and status never constrains provenance, and `reverse-extracted` + `complete` is the legitimate pair that motivated the field. Evidence: 2 reverse-estate manifests had written `reverse-extracted` INTO contracts.status, where it is invalid, because a complete reverse-derived contract surface had no way to say both true things at once and the author picked the provenance one. A rule here that constrained maturity would re-create exactly that defect. ⚠ Note the asymmetry this column exposes and does not fix: the maturity ladder it is orthogonal to has NO catalogue column at all — `traceability.contracts.status` is validator-enforced but uncatalogued, so it is queryable by no consumer. That is the authored-but-uncatalogued class (a block with no column has no automated reader, so nothing can notice when it is absent or wrong); this column is given one precisely so the provenance half does not join it. Giving the ladder a column is a candidate follow-on, not done here."
     - name: source
       type: string
       nullable: false
@@ -1523,7 +1552,7 @@ catalogues:
     - name: kind
       type: string
       nullable: false
-      description: rest | graphql | rpc | event | authz. rpc covers Proto/gRPC; event covers Avro schemas; authz covers authorization/policy schemas (SpiceDB .zed and equivalents), added because an adopter contract lock-in gate certified .zed schemas as contracts while no kind could represent them.
+      description: rest | graphql | rpc | event | authz. rpc covers Proto/gRPC; event covers Avro schemas; authz covers authorization/policy schemas (SpiceDB .zed and equivalents), added because an adopter contract agreement gate certified .zed schemas as contracts while no kind could represent them.
     - name: version
       type: string
       nullable: true
@@ -1888,7 +1917,7 @@ catalogues:
     - name: version
       type: string
       nullable: true
-      description: Optional explicit version; null until the domain model is formally versioned (typically at first contract lock-in).
+      description: Optional explicit version; null until the domain model is formally versioned (typically when a contract is first pinned).
     - name: evidence_class
       type: string
       nullable: true
@@ -2142,7 +2171,7 @@ catalogues:
     - name: required_stability
       type: string
       nullable: true
-      description: "provisional | locked | unknown. The consuming SDD's expectation of contract stability, carried verbatim from app-platform-dependencies.yaml. Not a bound enum: an out-of-vocabulary value is carried, not rejected, and is reported by validate-app-dependencies.sh."
+      description: "provisional | stable | unknown. The consuming SDD's expectation of contract stability, carried verbatim from app-platform-dependencies.yaml. Not a bound enum: an out-of-vocabulary value is carried, not rejected, and is reported by validate-app-dependencies.sh."
     description: "Edge: product depends on / consumes service. Forward sources from app-platform-dependencies.yaml. service_id is external because the consuming product (an application-product SDD) references a service owned by the platform SDD."
     foreign_keys:
     - column: product_id
@@ -2930,7 +2959,7 @@ catalogues:
     - name: required_stability
       type: string
       nullable: true
-      description: "provisional | locked | unknown. Optional; the consuming SDD's expectation of contract stability — and only that: where the target lives and what lifecycle its implementation is in are separate concerns that do not belong in this field. Not a bound enum: an out-of-vocabulary value is carried, not rejected, and is reported by validate-app-dependencies.sh."
+      description: "provisional | stable | unknown. Optional; the consuming SDD's expectation of contract stability — and only that: where the target lives and what lifecycle its implementation is in are separate concerns that do not belong in this field. Not a bound enum: an out-of-vocabulary value is carried, not rejected, and is reported by validate-app-dependencies.sh."
     - name: contract_path
       type: string
       nullable: true
@@ -4115,3 +4144,127 @@ catalogues:
       external: true
     column_enums:
       kind: enums.repo_dependency_kind
+  requirements:
+    primary_key: id
+    columns:
+    - name: id
+      type: string
+      nullable: false
+      description: <feature_id>::<requirement name>. The name is unique within its spec and stable across changes (M-ADR 0221 §4.7).
+    - name: feature_id
+      type: string
+      nullable: false
+      description: "The catalogue feature whose living spec holds the requirement: the spec's directory name under openspec/specs/."
+    - name: name
+      type: string
+      nullable: false
+      description: The requirement's name as the spec heads it; automated tests carry it.
+    - name: stage
+      type: string
+      nullable: false
+      description: "Bound to requirement_stage: living (in the living spec) or agreed (added by an open change whose agreement record is agreed)."
+    - name: spec_path
+      type: string
+      nullable: false
+      description: "The file that holds the requirement: the living spec, or the open change's delta."
+    - name: scenario_count
+      type: integer
+      nullable: false
+      description: Scenarios under the requirement in that file.
+    - name: source_sdd_id
+      type: string
+      nullable: true
+      description: Originating SDD (stamped at aggregation; empty in a per-SDD build).
+    - name: platform_sdd_id
+      type: string
+      nullable: true
+      description: The platform SDD the row belongs to (stamped at aggregation).
+    description: "A requirement in the SDD's behaviour store (M-ADR 0221): one row per requirement of a living spec, keyed by the catalogue feature the spec describes, and per requirement an open agreed change adds. Projected from openspec/ at the SDD's commit; never authored here."
+    foreign_keys:
+    - column: feature_id
+      references: features.id
+      nullable: false
+    column_enums:
+      stage: enums.requirement_stage
+  requirement_lineage:
+    primary_key: id
+    columns:
+    - name: id
+      type: string
+      nullable: false
+      description: <requirement_id>__<change_id>.
+    - name: requirement_id
+      type: string
+      nullable: false
+    - name: change_id
+      type: string
+      nullable: false
+      description: The archived change's directory name (its archive date prefix included).
+    - name: change_kind
+      type: string
+      nullable: false
+      description: "Bound to requirement_change_kind: baseline or change."
+    - name: operation
+      type: string
+      nullable: false
+      description: "Bound to requirement_operation: how the change's delta treated the requirement."
+    - name: archived_on
+      type: string
+      nullable: false
+      description: The archive date (YYYY-MM-DD) from the change's directory name.
+    - name: source_sdd_id
+      type: string
+      nullable: true
+      description: Originating SDD (stamped at aggregation; empty in a per-SDD build).
+    - name: platform_sdd_id
+      type: string
+      nullable: true
+      description: The platform SDD the row belongs to (stamped at aggregation).
+    description: "Annotation: an archived change that made a current requirement what it is (M-ADR 0221 §4.6), in archive order. A baseline change (one carrying baseline-evidence.md) records existing behaviour; any other change carries a verdict."
+    foreign_keys:
+    - column: requirement_id
+      references: requirements.id
+      nullable: false
+    column_enums:
+      change_kind: enums.requirement_change_kind
+      operation: enums.requirement_operation
+  requirement_status:
+    primary_key: id
+    columns:
+    - name: id
+      type: string
+      nullable: false
+      description: <requirement_id>__<repo_id>.
+    - name: requirement_id
+      type: string
+      nullable: false
+    - name: repo_id
+      type: string
+      nullable: false
+      description: "The implementing repository: a work order's repository, or a repository a baseline was observed in."
+    - name: status
+      type: string
+      nullable: false
+      description: Bound to requirement_status_value.
+    - name: basis
+      type: string
+      nullable: false
+      description: "The change that produced the status: the open change's or the archived change's directory name."
+    - name: source_sdd_id
+      type: string
+      nullable: true
+      description: Originating SDD (stamped at aggregation; empty in a per-SDD build).
+    - name: platform_sdd_id
+      type: string
+      nullable: true
+      description: The platform SDD the row belongs to (stamped at aggregation).
+    description: "Edge: a requirement's status in a repository that implements it (M-ADR 0221 §4.5; M-ADR 0223 §4.7). Derived, never authored: agreed from an open agreed change's work orders, declared-shipped from an archived change's PASS verdict and its work orders, observed from a baseline's evidence. The latest event in archive order wins."
+    foreign_keys:
+    - column: requirement_id
+      references: requirements.id
+      nullable: false
+    - column: repo_id
+      references: repositories.id
+      nullable: false
+    column_enums:
+      status: enums.requirement_status_value

package/dist/lib/catalogue/rubric-coverage-map.yaml

@@ -869,3 +869,39 @@ coverage:
     kind: enum
     scoring: not-applicable
     reason: closed vocabulary, not an artefact
+  requirements:
+    kind: entity
+    scoring: not-applicable
+    reason: projected from the behaviour store, whose baseline and change gates hold its quality (M-ADR 0222)
+    relationships:
+      feature_id:
+        class: membership
+        impact_flow: toward-target
+  requirement_lineage:
+    kind: annotation
+    scoring: derived-edge
+    class: lineage
+    impact_flow: none
+    reason: derived from the archived changes scored by their own judge
+  requirement_status:
+    kind: edge
+    scoring: derived-edge
+    class: realisation
+    impact_flow: both
+    reason: derived from agreement records, verdicts and baseline evidence
+  requirement_stage:
+    kind: enum
+    scoring: not-applicable
+    reason: closed vocabulary, not an artefact
+  requirement_change_kind:
+    kind: enum
+    scoring: not-applicable
+    reason: closed vocabulary, not an artefact
+  requirement_operation:
+    kind: enum
+    scoring: not-applicable
+    reason: closed vocabulary, not an artefact
+  requirement_status_value:
+    kind: enum
+    scoring: not-applicable
+    reason: closed vocabulary, not an artefact

package/dist/lib/catalogue/schema-compat.js

@@ -27,7 +27,7 @@
  * ADR 0134 §4.6 (canonical builder + aggregator).
  */
 export const SCHEMA_COMPAT = {
-    catalogue_schema: "^3.0.0",
+    catalogue_schema: "^4.0.0",
     sdd_manifest: "^1.0.0",
     aggregation_manifest: "^1.0.0",
 };

package/dist/lib/sdd-index/repo-config.js

@@ -8,6 +8,7 @@
  */
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
+import { canonicalValue } from "../vocabulary/renames.js";
 import { walkFiles } from "../sdd-reader.js";
 export const REPO_CONFIG_DIR = "orchestration/repo-config";
 const CONTRACT_KINDS = [
@@ -229,8 +230,12 @@ function parseContractEntry(entry, kind, sourceRel, warnings) {
     };
 }
 function parseStability(v) {
-    if (v === "provisional" || v === "locked")
-        return v;
+    if (v === undefined)
+        return undefined;
+    // The fixed-contract class was `locked` (M-ADR 0222 §4.1); read as `stable` for one major release.
+    const c = canonicalValue("stability-stable", v);
+    if (c === "provisional" || c === "stable")
+        return c;
     return undefined;
 }
 function stringField(record, key) {

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

@@ -14,6 +14,16 @@
 //                 With no such targets the check is vacuous, and says so.
 //   4. verdicts: every archived change except a baseline has a verdict.md and a record whose
 //                 verdict is PASS and names it (M-ADR 0223 §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
+//                 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.
+//   6. scope:    a baseline ADDS requirements; it REMOVES, MODIFIES or RENAMES only a requirement whose
+//                 latest archived change was a baseline, which is how a corrective baseline withdraws
+//                 what a baseline admitted wrongly. A requirement a judged change shipped is changed only
+//                 by a change (M-ADR 0222 §4.4). Read in archive order.
 //
 // A sibling-repository store (M-ADR 0221 §4.2) is checked in that repository, not here.
 //
@@ -25,6 +35,8 @@ import { access, readdir, readFile } from "node:fs/promises";
 import { basename, join } from "node:path";
 import { promisify } from "node:util";
 import { parseDocument } from "yaml";
+import { observedIn, orderArchives, parseRequirements, parseSurfaces, renamedFrom, surfaceMatches } from "../behaviour-store/archive.js";
+import { parseCatalogueCsv } from "../catalogue/csv-reader.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";
@@ -271,6 +283,77 @@ export async function checkBehaviourStore(repo) {
             failures.push(`${record.file}: verdict.record ${JSON.stringify(vr)} does not name an existing file`);
     }
     lines.push(`verdicts: ${archived.length} archived change(s), ${baselines} baseline(s), ${archived.length - baselines} needing a PASS verdict`);
+    // 5. surfaces, and 6. what each baseline may change, in archive order
+    const archiveRel = `${STORE_DIR}/changes/archive`;
+    const { order, ties } = await orderArchives(repo, archiveRel, archived);
+    const servedBy = baselines > 0 ? await catalogueContracts(repo) : null;
+    let surfacesChecked = 0;
+    const lastTouch = new Map();
+    let scopeChecked = 0;
+    for (const name of order) {
+        const dir = `${archiveRel}/${name}`;
+        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) {
+                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`);
+                            }
+                        }
+                    }
+                }
+            }
+        }
+        for (const feature of await dirs(join(repo, dir, "specs"))) {
+            const text = (await readText(join(repo, dir, "specs", feature, "spec.md"))) ?? "";
+            const targets = [
+                ...parseRequirements(text).filter((r) => r.operation === "MODIFIED" || r.operation === "REMOVED").map((r) => r.name),
+                ...renamedFrom(text),
+            ];
+            for (const t of targets) {
+                const key = `${feature}::${t}`;
+                if (isBaseline) {
+                    scopeChecked++;
+                    const last = lastTouch.get(key);
+                    if (last !== "baseline") {
+                        failures.push(`${dir}: a baseline changes "${t}" (${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, and anything else takes a change (M-ADR 0222 §4.4)`);
+                    }
+                }
+            }
+            for (const r of parseRequirements(text)) {
+                const key = `${feature}::${r.name}`;
+                if (r.operation === "REMOVED")
+                    lastTouch.delete(key);
+                else if (r.operation)
+                    lastTouch.set(key, isBaseline ? "baseline" : "change");
+            }
+            for (const from of renamedFrom(text))
+                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}`);
+    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`);
+    for (const [a, b] of ties)
+        lines.push(`order: ${a} and ${b} were archived the same day and the history does not order them; ordered by name`);
     const population = recordFiles.length + open.length + archived.length;
     const body = lines.map((l) => `  ${l}`).join("\n") + "\n";
     if (failures.length > 0) {
@@ -278,7 +361,35 @@ export async function checkBehaviourStore(repo) {
     }
     if (population === 0)
         return { exitCode: 0, stdout: body + `[N/A] the behaviour store has no changes and no agreement records yet\n` };
-    return { exitCode: 0, stdout: body + "[PASS] behaviour store: records, agreement, stale and verdict checks hold\n" };
+    return { exitCode: 0, stdout: body + "[PASS] behaviour store: records, agreement, stale, verdict, surfaces and scope checks hold\n" };
+}
+/** Per repository, the contracts the catalogue says it serves (repo_contract ⋈ contracts.spec_path); null when either file is missing. */
+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 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);
+    }
+    return out;
+}
+async function observedInAll(repo, archiveRel, names) {
+    const out = [];
+    for (const n of names) {
+        const ev = await readText(join(repo, archiveRel, n, "baseline-evidence.md"));
+        if (ev !== null)
+            out.push(...observedIn(ev));
+    }
+    return out;
 }
 async function runOpenspec(repo, args) {
     try {