@sdd-method/author-cli 0.4.0 → 0.5.0

package/dist/author-program.js

@@ -22,6 +22,7 @@ import { registerConformance } from "./verbs/conformance.js";
 import { registerContext } from "./verbs/context.js";
 import { registerContracts } from "./verbs/contracts.js";
 import { registerGenerateBriefing } from "./verbs/generate-briefing.js";
+import { registerMigrate } from "./verbs/migrate.js";
 import { registerPlan } from "./verbs/plan.js";
 import { registerRender } from "./verbs/render.js";
 import { registerScaffold } from "./verbs/scaffold.js";
@@ -44,6 +45,7 @@ export const AUTHOR_ONLY_SURFACE = [
     "generate-briefing",
     "context pull",
     "catalogue check",
+    "migrate vocabulary",
 ];
 /** The full surface: verify's, plus the author's own. */
 export const AUTHOR_SURFACE = [...VERIFY_SURFACE, ...AUTHOR_ONLY_SURFACE];
@@ -83,6 +85,7 @@ export function buildAuthorProgram() {
     // The verify surface first, from verify's own registration: verify ⊂ author is structural.
     registerVerifySurface(program);
     registerScaffold(program);
+    registerMigrate(program);
     registerPlan(program);
     registerContracts(program);
     registerConformance(program);

package/dist/lib/catalogue/build.js

@@ -34,6 +34,7 @@ import { readCatalogueCsv } from "./csv-reader.js";
 import { buildDataItems, buildFeatureDemand, buildIntegrationSupply } from "./builders/data-items.js";
 import { buildEvidenceTargetRepos } from "./builders/evidence-target-repo.js";
 import { buildRepoDependencies } from "./builders/repo-dependency.js";
+import { buildRequirements } from "./builders/requirements.js";
 import { buildDomains, buildProducts, buildApplicationDataPlaneBindings, buildApplicationDataPlaneDeviations, buildApplicationConformanceCoverage, buildImplementations, buildRepositories, buildServices, buildCapabilities, buildCapabilityService, buildCapabilityAdr, buildCapabilityFeature, buildCapabilityContract, buildAdrs, buildAdrSupersedes, buildFeatures, buildFeatureGroups, buildFeatureGrounding, buildCapabilitySpec, buildContracts, buildDeclaredExternalContracts, buildRepoEdges, deriveFeatureRepoFromServices, buildRepoCapabilityExemption, buildServiceCapabilityExemption, buildEvents, buildServiceEvent, buildCapabilityEvent, buildFeatureEvent, buildServiceContract, buildServiceContractConsumes, buildFeatureContract, buildDomainModels, buildCapabilityDomainModel, buildFeatureDomainModel, buildFeatureSubscriptionChannels, buildProductPlatformDependencies, buildGlossaryItems, backfillGlossaryRelations, buildGlossaryXref, buildC4Systems, buildC4Containers, buildC4Components, buildC4ExternalSystems, buildExternalSystemExemption, buildContainerDependency, reportEntryIdReferentCollisions, buildSystemExternalDependency, buildPersonaC4System, buildPersonaContainer, buildPersonas, buildQualityScores, buildScaffolds, buildScreens, buildUserJourneys, buildPersonaJourney, buildPersonaFeature, buildJourneyFeature, buildProductEdges, buildIntegrations, entitySlug, buildEntitiesFromManifest, buildEntitiesFromMermaid, buildServiceEntityFromTables, enrichEntityPersistenceKind, buildC4ContainerEntity, buildC4SystemEntity, } from "./builders/index.js";
 import { buildIntegrationComponents } from "./builders/integration-components.js";
 import { loadReverseProductQuality } from "./reverse-product-quality.js";
@@ -1151,6 +1152,18 @@ async function collectRows(schema, manifest, findings, sddPath, snapshotStore) {
     // M-ADR 0217: build-time and generation-time dependencies between repositories,
     // declared (repo-config depends_on) and derived (per-component sharedLibraries).
     out.set("repo_dependency", await buildRepoDependencies({ sddPath, configs: reposResult.configs, knownRepoIds: knownRepoIdsFinal, findings }));
+    // M-ADR 0221 §4.5-4.7: the behaviour store projected into requirements, their lineage and their status.
+    {
+        const r = await buildRequirements({
+            sddPath,
+            findings,
+            knownFeatureIds: new Set((out.get("features") ?? []).map((row) => String(row["id"]))),
+            knownRepoIds: knownRepoIdsFinal,
+        });
+        out.set("requirements", r.requirements);
+        out.set("requirement_lineage", r.lineage);
+        out.set("requirement_status", r.status);
+    }
     // 15. C4 systems + containers + components (L1 + L2 + L3). The L3 walker
     // is the forward-method authoring path reading
     // `c4-l3-*.mermaid.md` files alongside the L2 layout. The earlier Path-B

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

@@ -13,6 +13,7 @@
 import { readFile, stat } from "node:fs/promises";
 import { join, relative, sep } from "node:path";
 import { readdir } from "node:fs/promises";
+import { rename } from "../../vocabulary/renames.js";
 const DOMAINS_DIR_REL = join("docs", "domains");
 /**
  * The vocabulary `catalogue-schema.yaml` documents for `capabilities.status`.
@@ -48,7 +49,9 @@ const DOCUMENTED_CAPABILITY_STATUS = new Set([
 const SPEC_AUTHORING_STAGES = new Set([
     "placeholder",
     "first-draft",
-    "detailed-pre-lock",
+    rename("authoring-status-detailed").new,
+    // The stage's former name (M-ADR 0222 §4.1) is the same stage on the same wrong axis.
+    rename("authoring-status-detailed").old,
     "reverse-derived",
 ]);
 /**

package/dist/lib/catalogue/builders/product-edges.js

@@ -15,6 +15,7 @@ import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { z } from "zod";
+import { canonicalValue } from "../../vocabulary/renames.js";
 const REL_PATH = "app-platform-dependencies.yaml";
 const DependencyEntrySchema = z.object({
     capability_id: z.string().optional(),
@@ -70,7 +71,8 @@ export async function buildProductEdges(inputs) {
             continue;
         const capabilityId = (dep.capability_id ?? "").trim();
         const serviceId = (dep.service_id ?? "").trim();
-        const requiredStability = (dep.required_stability ?? "").trim();
+        // Normalised silently here: product-platform-dependencies reads the same file and reports the former name.
+        const requiredStability = canonicalValue("stability-stable", (dep.required_stability ?? "").trim());
         const notes = (dep.notes ?? "").trim();
         if (capabilityId !== "") {
             const id = `${inputs.productId}__${capabilityId}`;

package/dist/lib/catalogue/builders/product-platform-dependencies.js

@@ -21,7 +21,7 @@
 //       service_id: <target-service-slug>            # platform-side service
 //       domain: <domain-hint>                        # optional (reverse shape)
 //       contract_type: rest | graphql | openapi | grpc | event | other
-//       required_stability: locked | provisional | unknown
+//       required_stability: stable | provisional | unknown
 //       contract_path: <relative-path-in-platform-sdd>  # optional (reverse)
 //       consumed_by:                                     # optional (reverse)
 //         - <service-name-within-this-product>
@@ -57,6 +57,7 @@
 import { readFile, readdir, stat } from "node:fs/promises";
 import { join, relative, sep } from "node:path";
 import { parse as parseYaml } from "yaml";
+import { canonicalValue, isFormerValue } from "../../vocabulary/renames.js";
 const FORWARD_REL_PATH = "app-platform-dependencies.yaml";
 /**
  * Contract types that denote an ASYNC shared-stream dependency (M-ADR 0192).
@@ -260,6 +261,20 @@ export async function buildProductPlatformDependencies(inputs) {
             });
         }
     }
+    // The stability class `locked` is `stable` from catalogue schema 4.0.0 (M-ADR 0222 §4.1). A source
+    // still carrying the former name is read as the new one for one major release, so no cell carries
+    // the former word, and reported once per SDD so the adopter can run the migration.
+    let former = 0;
+    for (let i = 0; i < rows.length; i++) {
+        const v = String(rows[i]["required_stability"] ?? "");
+        if (isFormerValue("stability-stable", v)) {
+            rows[i] = { ...rows[i], required_stability: canonicalValue("stability-stable", v) };
+            former++;
+        }
+    }
+    if (former > 0) {
+        inputs.findings.add("convention", `product_platform_dependencies: ${former} dependenc${former === 1 ? "y declares" : "ies declare"} the former required_stability 'locked', read as 'stable' (M-ADR 0222 §4.1); run 'sdd-cli migrate vocabulary'`);
+    }
     return rows;
 }
 /**

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

@@ -0,0 +1,240 @@
+// Behaviour store -> requirements, requirement_lineage, requirement_status (M-ADR 0221 §4.5-4.7, M-ADR 0223 §4.7).
+//
+// The store is an OpenSpec project inside the SDD (`openspec/`). Everything here is a projection: the living specs
+// and changes are the record, and the catalogue reads them at the SDD's own commit. A sibling-repository store is
+// read in that repository, not here.
+//
+//   requirements        one row per `### Requirement:` in a living spec (stage living), keyed by the spec's
+//                       directory name, which is the catalogue feature id; plus one per requirement an open,
+//                       agreed change ADDS (stage agreed).
+//   requirement_lineage each archived change, in archive order, whose delta ADDED, MODIFIED or RENAMED a
+//                       requirement that is current now. A change carrying baseline-evidence.md is a baseline.
+//   requirement_status  per (requirement, repository): observed from a baseline's `**Observed in:**` line;
+//                       declared-shipped from an archived change whose agreement record's verdict is PASS, through
+//                       its work orders' `implements` lists; agreed from an open change whose record is agreed.
+//                       The latest event wins, archived changes in archive order, then open changes.
+//
+// A feature or repository the catalogue does not hold is a finding and produces no row, so no foreign key dangles.
+import { readdir, readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+const STORE = "openspec";
+const AGREEMENTS = join("docs", "agreements");
+async function isDir(p) {
+    try {
+        return (await stat(p)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+async function dirs(p) {
+    try {
+        return (await readdir(p, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name).sort();
+    }
+    catch {
+        return [];
+    }
+}
+async function readText(p) {
+    try {
+        return await readFile(p, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Requirement names and scenario counts under each `## <OP> Requirements` section (or the whole file for a living spec). */
+export function parseRequirements(text) {
+    const out = [];
+    let op = null;
+    let current = null;
+    for (const line of text.split("\n")) {
+        const section = /^##\s+(ADDED|MODIFIED|REMOVED|RENAMED)\s+Requirements\b/.exec(line);
+        if (section) {
+            op = section[1];
+            current = null;
+            continue;
+        }
+        if (/^##\s/.test(line) && !/^###/.test(line)) {
+            current = null;
+            continue;
+        }
+        // RENAMED: "- TO: `### Requirement: New name`"
+        const renamedTo = /^\s*-\s*TO:\s*`?###\s+Requirement:\s*(.+?)`?\s*$/.exec(line);
+        if (op === "RENAMED" && renamedTo) {
+            current = { name: renamedTo[1].trim(), operation: op, scenarios: 0 };
+            out.push(current);
+            continue;
+        }
+        const req = /^###\s+Requirement:\s*(.+?)\s*$/.exec(line);
+        if (req) {
+            current = { name: req[1], operation: op, scenarios: 0 };
+            out.push(current);
+            continue;
+        }
+        if (current && /^####\s+Scenario:/.test(line))
+            current.scenarios++;
+    }
+    return out;
+}
+async function deltaOf(changeDir) {
+    const out = [];
+    for (const feature of await dirs(join(changeDir, "specs"))) {
+        const file = join(changeDir, "specs", feature, "spec.md");
+        const text = await readText(file);
+        if (text === null)
+            continue;
+        for (const r of parseRequirements(text)) {
+            if (r.operation)
+                out.push({ feature, name: r.name, operation: r.operation, file, scenarios: r.scenarios });
+        }
+    }
+    return out;
+}
+async function agreementRecord(sddPath, change) {
+    const text = await readText(join(sddPath, AGREEMENTS, `${change}.yaml`));
+    if (text === null)
+        return null;
+    try {
+        const doc = parseYaml(text);
+        return doc?.agreement_record ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** The repositories a baseline was observed in: its evidence file's `**Observed in:** repo[@sha], repo[@sha]` line. */
+export function observedIn(evidence) {
+    const m = /^\s*\*\*Observed in:\*\*\s*(.+)$/m.exec(evidence);
+    if (!m)
+        return [];
+    return m[1]
+        .split(",")
+        .map((s) => s.trim().split(/\s*@\s*/)[0].replace(/`/g, "").trim())
+        .filter((s) => s !== "");
+}
+const rel = (sddPath, p) => p.slice(sddPath.length + 1).split("\\").join("/");
+export async function buildRequirements(inputs) {
+    const { sddPath, findings } = inputs;
+    const empty = { requirements: [], lineage: [], status: [] };
+    const store = join(sddPath, STORE);
+    if (!(await isDir(store)))
+        return empty;
+    const requirements = new Map();
+    const unknownFeatures = new Set();
+    const known = (feature) => {
+        if (inputs.knownFeatureIds.has(feature))
+            return true;
+        unknownFeatures.add(feature);
+        return false;
+    };
+    // 1. Living specs.
+    for (const feature of await dirs(join(store, "specs"))) {
+        const file = join(store, "specs", feature, "spec.md");
+        const text = await readText(file);
+        if (text === null || !known(feature))
+            continue;
+        for (const r of parseRequirements(text)) {
+            const id = `${feature}::${r.name}`;
+            if (requirements.has(id)) {
+                findings.add("convention", `${rel(sddPath, file)}: requirement "${r.name}" is named twice; names must be unique within a spec (M-ADR 0221 §4.7)`);
+                continue;
+            }
+            requirements.set(id, { id, feature_id: feature, name: r.name, stage: "living", spec_path: rel(sddPath, file), scenario_count: r.scenarios, source_sdd_id: "", platform_sdd_id: "" });
+        }
+    }
+    const events = [];
+    const lineage = [];
+    const unknownRepos = new Set();
+    const pushEvent = (e) => {
+        if (!inputs.knownRepoIds.has(e.repo)) {
+            unknownRepos.add(e.repo);
+            return;
+        }
+        if (requirements.has(e.requirementId))
+            events.push(e);
+    };
+    // 2. Archived changes, in archive order.
+    for (const dir of await dirs(join(store, "changes", "archive"))) {
+        const changeDir = join(store, "changes", "archive", dir);
+        const change = dir.replace(/^\d{4}-\d{2}-\d{2}-/, "");
+        const archivedOn = /^(\d{4}-\d{2}-\d{2})-/.exec(dir)?.[1] ?? "";
+        const evidence = await readText(join(changeDir, "baseline-evidence.md"));
+        const kind = evidence !== null ? "baseline" : "change";
+        const delta = await deltaOf(changeDir);
+        for (const d of delta) {
+            if (d.operation === "REMOVED")
+                continue;
+            const requirementId = `${d.feature}::${d.name}`;
+            if (!requirements.has(requirementId))
+                continue;
+            lineage.push({ id: `${requirementId}__${dir}`, requirement_id: requirementId, change_id: dir, change_kind: kind, operation: d.operation, archived_on: archivedOn, source_sdd_id: "", platform_sdd_id: "" });
+        }
+        if (evidence !== null) {
+            const repos = observedIn(evidence);
+            if (repos.length === 0) {
+                findings.add("convention", `${rel(sddPath, join(changeDir, "baseline-evidence.md"))}: no "**Observed in:**" line, so its requirements carry no observed status`);
+            }
+            for (const repo of repos)
+                for (const d of delta)
+                    if (d.operation !== "REMOVED")
+                        pushEvent({ requirementId: `${d.feature}::${d.name}`, repo, status: "observed", basis: dir });
+            continue;
+        }
+        const record = await agreementRecord(sddPath, change);
+        if (record?.verdict?.result !== "PASS")
+            continue; // the behaviour-store validator reports an archived change without a PASS verdict
+        for (const wo of record.work_orders ?? []) {
+            if (!wo.repo)
+                continue;
+            for (const name of wo.implements ?? []) {
+                const match = delta.filter((d) => d.name === name && d.operation !== "REMOVED");
+                if (match.length === 0) {
+                    findings.add("convention", `${AGREEMENTS}/${change}.yaml: work order for ${wo.repo} implements "${name}", which the change's delta does not name`);
+                }
+                for (const d of match)
+                    pushEvent({ requirementId: `${d.feature}::${d.name}`, repo: wo.repo, status: "declared-shipped", basis: dir });
+            }
+        }
+    }
+    // 3. Open changes whose agreement record is agreed.
+    for (const dir of (await dirs(join(store, "changes"))).filter((d) => d !== "archive")) {
+        const record = await agreementRecord(sddPath, dir);
+        if (record?.status !== "agreed")
+            continue;
+        const delta = await deltaOf(join(store, "changes", dir));
+        for (const d of delta) {
+            const id = `${d.feature}::${d.name}`;
+            if (d.operation === "ADDED" && !requirements.has(id) && known(d.feature)) {
+                requirements.set(id, { id, feature_id: d.feature, name: d.name, stage: "agreed", spec_path: rel(sddPath, d.file), scenario_count: d.scenarios, source_sdd_id: "", platform_sdd_id: "" });
+            }
+        }
+        for (const wo of record.work_orders ?? []) {
+            if (!wo.repo)
+                continue;
+            for (const name of wo.implements ?? []) {
+                for (const d of delta.filter((x) => x.name === name && x.operation !== "REMOVED")) {
+                    pushEvent({ requirementId: `${d.feature}::${d.name}`, repo: wo.repo, status: "agreed", basis: dir });
+                }
+            }
+        }
+    }
+    for (const f of unknownFeatures)
+        findings.add("convention", `${STORE}/: a spec keyed "${f}" names no catalogue feature, so its requirements are not catalogued (M-ADR 0221 §4.7)`);
+    for (const r of unknownRepos)
+        findings.add("convention", `${STORE}/: a status names repository "${r}", which the catalogue does not hold; no status row`);
+    // Latest event per (requirement, repository) wins.
+    const status = new Map();
+    for (const e of events) {
+        const id = `${e.requirementId}__${e.repo}`;
+        status.set(id, { id, requirement_id: e.requirementId, repo_id: e.repo, status: e.status, basis: e.basis, source_sdd_id: "", platform_sdd_id: "" });
+    }
+    const byId = (a, b) => String(a["id"]).localeCompare(String(b["id"]));
+    return {
+        requirements: [...requirements.values()].sort(byId),
+        lineage,
+        status: [...status.values()].sort(byId),
+    };
+}
+//# sourceMappingURL=requirements.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: "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/vocabulary/migrate.js

@@ -0,0 +1,237 @@
+/**
+ * `migrate vocabulary` (M-ADR 0222 §4.1; docs/method/foundations/vocabulary-renames.yaml): rewrite an SDD's
+ * OWN files from the former tool-read values to the new ones. Authored content, so the verb is the author's
+ * and the full CLI's, never maintain's (M-ADR 0218), and it is deterministic: a second run changes nothing.
+ *
+ * Scope: tracked files only, minus every lock-managed path (method and pack payload, which sync and pack
+ * cycles own), `.sdd/` and `catalogues/` (rebuilt by catalogue build). A value is rewritten only in a known
+ * position, never as a free-text word:
+ *   - a spec `**Status:**` header (bold or the `> … Status:` prose form)            detailed-pre-lock -> detailed
+ *   - the spec-lifecycle ratchet baseline's `<status> :: <path>` keys                detailed-pre-lock -> detailed
+ *   - a YAML value of `required_stability`, `stability`, `template-stability`,
+ *     `traceability.contracts.status`, and the same keys in Markdown examples       locked -> stable
+ *   - an agreement tag anywhere (`release-vMAJOR.MINOR-locked`)                      -> release-vMAJOR.MINOR-agreed
+ *   - the key `lock_in_tag`                                                          -> agreement_tag
+ *   - gate-registry `next_gate: lock-in` and the key `remediation_before_lock_in`    -> agreement, remediation_before_agreement
+ * Reported, never rewritten: an adopter-named `x-<adopter>-stability` extension (the adopter's to rename, M-ADR 0222 §4.1),
+ * and `detailed-pre-lock` in a manifest's `capability.status` (a spec-authoring stage on the wrong axis, which
+ * the traceability check already reports; it is not translated, because the true lifecycle value is not a
+ * translation of the word).
+ */
+import { execFile } from "node:child_process";
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { promisify } from "node:util";
+import { isPair, isScalar, parseDocument, visit } from "yaml";
+import { rename } from "./renames.js";
+const execFileAsync = promisify(execFile);
+const MAX_BYTES = 4 * 1024 * 1024;
+const STABILITY_KEYS = new Set(["required_stability", "stability", "template-stability"]);
+// MAJOR.MINOR as the method writes it, and any dotted version an adopter wrote (release-v1.0.1-locked).
+const TAG_RE = /\brelease-v(?:\d+|X|MAJOR)(?:\.(?:\d+|X|MINOR|PATCH))+-locked\b/g;
+function lineOf(text, offset) {
+    let n = 1;
+    for (let i = 0; i < offset && i < text.length; i++)
+        if (text.charCodeAt(i) === 10)
+            n++;
+    return n;
+}
+async function trackedFiles(sddPath) {
+    const { stdout } = await execFileAsync("git", ["-C", sddPath, "ls-files", "-z"], { maxBuffer: 64 * 1024 * 1024 });
+    return stdout.split("\0").filter((p) => p !== "");
+}
+async function managedPaths(sddPath) {
+    const out = new Set();
+    let text;
+    try {
+        text = await readFile(join(sddPath, "method-baseline.lock"), "utf8");
+    }
+    catch {
+        return out;
+    }
+    for (const line of text.split("\n")) {
+        const m = /^\s+-\s+[0-9a-f]{64}\s+(.+)$/.exec(line);
+        if (m)
+            out.add(m[1].trim());
+    }
+    return out;
+}
+/** Edits for text forms that are values wherever they appear: the agreement tag and the lock_in_tag key. */
+function tokenEdits(text) {
+    const edits = [];
+    const tag = rename("agreement-tag");
+    for (const m of text.matchAll(TAG_RE)) {
+        const to = m[0].replace(/-locked$/, "-agreed");
+        edits.push({ start: m.index, end: m.index + m[0].length, text: to, rewrite: { from: m[0], to, rule: tag.id } });
+    }
+    const key = rename("agreement-tag-key");
+    for (const m of text.matchAll(new RegExp(`\\b${key.old}\\b`, "g"))) {
+        edits.push({ start: m.index, end: m.index + key.old.length, text: key.new, rewrite: { from: key.old, to: key.new, rule: key.id } });
+    }
+    return edits;
+}
+function markdownEdits(text) {
+    const edits = tokenEdits(text);
+    const status = rename("authoring-status-detailed");
+    const stab = rename("stability-stable");
+    const lines = text.split("\n");
+    let offset = 0;
+    for (const line of lines) {
+        const header = /^(\s*(?:[-*]\s+)?\*\*Status:\*\*\s*)(\S+)/.exec(line) ?? /^(>.*\bStatus:\s*)([^\s|]+)/.exec(line);
+        if (header && header[2] === status.old) {
+            const start = offset + header[1].length;
+            edits.push({ start, end: start + status.old.length, text: status.new, rewrite: { from: status.old, to: status.new, rule: status.id } });
+        }
+        // Stability values in Markdown examples (YAML blocks or prose quoting a key: value pair).
+        // Not after a hyphen or word character: `x-<adopter>-stability: locked` is the adopter's (M-ADR 0222 §4.1).
+        const stabRe = /(?<![\w-])(required_stability|stability|template-stability)(\s*:\s*["']?)locked\b/g;
+        for (const m of line.matchAll(stabRe)) {
+            const start = offset + m.index + m[1].length + m[2].length;
+            edits.push({ start, end: start + stab.old.length, text: stab.new, rewrite: { from: stab.old, to: stab.new, rule: stab.id } });
+        }
+        offset += line.length + 1;
+    }
+    return edits;
+}
+function baselineEdits(text) {
+    const status = rename("authoring-status-detailed");
+    const edits = [];
+    let offset = 0;
+    for (const line of text.split("\n")) {
+        if (line.startsWith(`${status.old} :: `)) {
+            edits.push({ start: offset, end: offset + status.old.length, text: status.new, rewrite: { from: status.old, to: status.new, rule: status.id } });
+        }
+        offset += line.length + 1;
+    }
+    return edits;
+}
+function pathKeys(path) {
+    const keys = [];
+    for (const n of path)
+        if (isPair(n) && isScalar(n.key))
+            keys.push(String(n.key.value));
+    return keys;
+}
+/** The scalar's own source text, so a quoted value keeps its quotes. */
+function scalarEdit(text, node, from, to, rule) {
+    const r = node.range;
+    if (!r)
+        return undefined;
+    const src = text.slice(r[0], r[1]);
+    const at = src.indexOf(from);
+    if (at < 0)
+        return undefined;
+    return { start: r[0] + at, end: r[0] + at + from.length, text: to, rewrite: { from, to, rule } };
+}
+function yamlEdits(text, file, reported) {
+    const edits = tokenEdits(text);
+    let doc;
+    try {
+        doc = parseDocument(text);
+    }
+    catch {
+        return edits;
+    }
+    if (doc.errors.length > 0)
+        return edits;
+    const stab = rename("stability-stable");
+    const gate = rename("gate-registry-next-gate");
+    const remed = rename("gate-registry-remediation-key");
+    const status = rename("authoring-status-detailed");
+    visit(doc, {
+        Pair(_, pair, path) {
+            if (!isScalar(pair.key))
+                return;
+            const key = String(pair.key.value);
+            const val = isScalar(pair.value) ? pair.value : undefined;
+            const v = val ? String(val.value) : undefined;
+            const ancestors = pathKeys(path);
+            if (/^x-.+-stability$/.test(key)) {
+                reported.push({ file, line: lineOf(text, pair.key.range?.[0] ?? 0), text: `${key}: ${v ?? "…"}`, reason: "an adopter-named extension: the adopter's to rename; the method's value is `stable`" });
+                return;
+            }
+            if (val && v === stab.old && (STABILITY_KEYS.has(key) || (key === "status" && ancestors.slice(-2).join(".") === "traceability.contracts"))) {
+                const e = scalarEdit(text, val, stab.old, stab.new, stab.id);
+                if (e)
+                    edits.push(e);
+            }
+            if (val && key === "next_gate" && v === gate.old) {
+                const e = scalarEdit(text, val, gate.old, gate.new, gate.id);
+                if (e)
+                    edits.push(e);
+            }
+            if (key === remed.old) {
+                const e = scalarEdit(text, pair.key, remed.old, remed.new, remed.id);
+                if (e)
+                    edits.push(e);
+            }
+            if (val && key === "status" && v === status.old && ancestors.slice(-1)[0] === "capability") {
+                reported.push({ file, line: lineOf(text, val.range?.[0] ?? 0), text: `capability.status: ${v}`, reason: "a spec-authoring stage on the lifecycle axis: re-author to the capability's true lifecycle phase; not translated" });
+            }
+            return undefined;
+        },
+    });
+    return edits;
+}
+function applyEdits(text, edits) {
+    const sorted = [...edits].sort((a, b) => b.start - a.start);
+    let out = text;
+    let lastStart = Number.POSITIVE_INFINITY;
+    for (const e of sorted) {
+        if (e.end > lastStart)
+            continue; // overlapping edits: keep the later one only
+        out = out.slice(0, e.start) + e.text + out.slice(e.end);
+        lastStart = e.start;
+    }
+    return out;
+}
+export async function migrateVocabulary(sddPath, opts = {}) {
+    const managed = await managedPaths(sddPath);
+    const files = (await trackedFiles(sddPath)).filter((f) => !managed.has(f) && !f.startsWith(".sdd/") && !f.startsWith("catalogues/") && !f.includes("node_modules/"));
+    const rewrites = [];
+    const reported = [];
+    let changed = 0;
+    for (const rel of files) {
+        const abs = join(sddPath, rel);
+        let st;
+        try {
+            st = await stat(abs);
+        }
+        catch {
+            continue;
+        }
+        if (!st.isFile() || st.size > MAX_BYTES)
+            continue;
+        const buf = await readFile(abs);
+        if (buf.includes(0))
+            continue;
+        const text = buf.toString("utf8");
+        let edits;
+        if (/\.ya?ml$/.test(rel))
+            edits = yamlEdits(text, rel, reported);
+        else if (rel.endsWith("spec-lifecycle-baseline.txt"))
+            edits = baselineEdits(text);
+        else if (/\.(md|hbs)$/.test(rel))
+            edits = markdownEdits(text);
+        else
+            edits = tokenEdits(text);
+        if (edits.length === 0)
+            continue;
+        const seen = new Set();
+        for (const e of edits.sort((a, b) => a.start - b.start)) {
+            const k = `${e.start}:${e.end}`;
+            if (seen.has(k))
+                continue;
+            seen.add(k);
+            rewrites.push({ file: rel, line: lineOf(text, e.start), ...e.rewrite });
+        }
+        const next = applyEdits(text, edits);
+        if (next !== text) {
+            changed++;
+            if (!opts.dryRun)
+                await writeFile(abs, next);
+        }
+    }
+    return { rewrites, reported, filesScanned: files.length, filesChanged: changed };
+}
+//# sourceMappingURL=migrate.js.map

package/dist/lib/vocabulary/renames.js

@@ -0,0 +1,40 @@
+/**
+ * The method's vocabulary renames (M-ADR 0222 §4.1), loaded from the vendored copy of
+ * sdd-method's docs/method/foundations/vocabulary-renames.yaml (one-way, sdd-method ->
+ * vendored; scripts/sync-vendored-script.sh, drift-tested in tests/parity).
+ *
+ * For one major release every reader accepts a former value and reads it as the new one;
+ * from `removed_in` the former value is an error. Readers ask this module rather than
+ * keeping their own copy, so a rename has one definition here as it has one in the bundles.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse } from "yaml";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+export const VENDORED_RENAMES_PATH = join(__dirname, "vocabulary-renames.yaml");
+let cached;
+export function vocabularyRenames() {
+    if (cached === undefined) {
+        const doc = parse(readFileSync(VENDORED_RENAMES_PATH, "utf8"));
+        cached = { introduced_in: String(doc.introduced_in), removed_in: String(doc.removed_in), renames: doc.renames };
+    }
+    return cached;
+}
+/** The rename with this id; throws on an id the file does not hold, so a reader cannot silently lose its alias. */
+export function rename(id) {
+    const r = vocabularyRenames().renames.find((x) => x.id === id);
+    if (r === undefined)
+        throw new Error(`vocabulary-renames.yaml has no rename "${id}"`);
+    return r;
+}
+/** The value as a reader should treat it: the new name for the former one, anything else unchanged. */
+export function canonicalValue(id, value) {
+    const r = rename(id);
+    return value === r.old ? r.new : value;
+}
+/** Whether a value is the former name under this rename (for the reader's finding). */
+export function isFormerValue(id, value) {
+    return value === rename(id).old;
+}
+//# sourceMappingURL=renames.js.map

package/dist/lib/vocabulary/vocabulary-renames.yaml

@@ -0,0 +1,76 @@
+# Vocabulary renames (M-ADR 0222 §4.1)
+#
+# The tool-read values the method renamed when "lock" left its vocabulary, as data:
+# every reader that accepts a former value, and the migrate verb, follows this file.
+# For one major release a reader accepts the former value, treats it as the new one
+# and reports it; from removed_in the former value is an error.
+#
+# Each reader that aliases a former value marks the place with a comment line
+#   vocabulary-alias: <old> -> <new>
+# and the correspondence registry holds the readers and this file to each other in
+# both directions (orchestration/correspondence-registry.yaml, vocabulary-renames).
+#
+# Consumed by:
+#   - validate-spec-lifecycle.sh, validate-traceability.sh, validate-app-dependencies.sh,
+#     dispatch-release.sh (the bundled readers)
+#   - sdd-cli's catalogue build and repo-config reader
+#   - `sdd-cli migrate vocabulary` (rewrites an SDD's own files)
+#
+# Distribution: ships in every method baseline via the seed-file lists.
+
+schema_version: "1.0.0"
+introduced_in: "2.0.0"   # the sdd-cli major that reads both names
+removed_in: "3.0.0"      # the sdd-cli major that rejects the former names
+
+renames:
+  - id: authoring-status-detailed
+    old: detailed-pre-lock
+    new: detailed
+    positions:
+      - "spec `**Status:**` header (M-ADR 0201's authoring ladder)"
+      - "work-order status"
+      - "capability manifest `capability.status` (a spec-authoring stage on the wrong axis; reported, never translated)"
+
+  - id: stability-stable
+    old: locked
+    new: stable
+    positions:
+      - "`required_stability` (app and integration platform dependencies)"
+      - "`traceability.contracts.status` (the contract-set maturity ladder)"
+      - "repository config `stability` (a stability class)"
+      - "runtime-artefact `stability` and `template-stability`"
+    note: "Only where `locked` is a stability CLASS. A pinned version is a different thing (M-ADR 0222 §4.1)."
+
+  - id: agreement-tag
+    old: release-vMAJOR.MINOR-locked
+    new: release-vMAJOR.MINOR-agreed
+    positions:
+      - "the agreement tag on a release branch (M-ADRs 0072-0074)"
+
+  - id: agreement-tag-key
+    old: lock_in_tag
+    new: agreement_tag
+    positions:
+      - "a platform BASELINE.md record key (M-ADR 0073)"
+
+  - id: gate-registry-next-gate
+    old: lock-in
+    new: agreement
+    positions:
+      - "gate registry `next_gate` value (domain-architecture rubric)"
+
+  - id: gate-registry-remediation-key
+    old: remediation_before_lock_in
+    new: remediation_before_agreement
+    positions:
+      - "gate registry key (domain-architecture rubric)"
+
+  - id: journey-status-accepted
+    old: accepted-pre-lock
+    new: accepted
+    positions:
+      - "user-journey status (templates only; no reader)"
+
+# An extension an adopter names itself (an `x-<adopter>-stability` contract extension,
+# say) is the adopter's to rename; its values follow the method's (M-ADR 0222 §4.1). The migrate verb
+# reports such extensions and never rewrites them.

package/dist/maintain-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.5.0",
-  "built_against_sdd_cli": "1.46.0"
+  "version": "0.6.0",
+  "built_against_sdd_cli": "2.0.0"
 }

package/dist/verbs/migrate.js

@@ -0,0 +1,32 @@
+import { resolve } from "node:path";
+import { migrateVocabulary } from "../lib/vocabulary/migrate.js";
+/**
+ * `migrate vocabulary` (M-ADR 0222 §4.1): rewrite the SDD's own files from the former tool-read values to the
+ * new ones, in known positions only, and report what it must not rewrite. Authored content, so the verb is the
+ * author's and the full CLI's (M-ADR 0218). Exit 0 when nothing is left to migrate, 1 when it rewrote values
+ * (or, with --dry-run, found values it would rewrite), so a wave can gate on "migrated".
+ */
+export function registerMigrate(program) {
+    const migrate = program.command("migrate").description("Migrate an SDD's own files to the method's current vocabulary");
+    migrate
+        .command("vocabulary")
+        .description("Rewrite the SDD's own files from the former tool-read values (detailed-pre-lock, stability locked, release-vX.X-locked, lock_in_tag, next_gate lock-in, remediation_before_lock_in) to the new ones, in known positions only; method- and pack-managed files, .sdd/ and catalogues/ are untouched (exit 1 when anything was or would be rewritten)")
+        .option("--sdd-path <path>", "Path to the SDD repo root (defaults to cwd)")
+        .option("--dry-run", "List what would be rewritten; write nothing")
+        .action(async (opts) => {
+        const root = resolve(opts.sddPath ?? process.cwd());
+        const r = await migrateVocabulary(root, { dryRun: opts.dryRun === true });
+        const w = (s) => process.stdout.write(s);
+        for (const x of r.rewrites)
+            w(`  ${opts.dryRun ? "would rewrite" : "rewrote"}  ${x.file}:${x.line}  ${x.from} -> ${x.to}  (${x.rule})\n`);
+        for (const x of r.reported)
+            w(`  reported  ${x.file}:${x.line}  ${x.text}  — ${x.reason}\n`);
+        const verb = opts.dryRun ? "would rewrite" : "rewrote";
+        w(r.rewrites.length === 0
+            ? `[PASS] migrate vocabulary: nothing to migrate in ${r.filesScanned} file(s) the SDD owns${r.reported.length ? `; ${r.reported.length} reported for the adopter` : ""}\n`
+            : `[INFO] migrate vocabulary: ${verb} ${r.rewrites.length} value(s) in ${r.filesChanged} file(s) of ${r.filesScanned}${r.reported.length ? `; ${r.reported.length} reported for the adopter` : ""}\n`);
+        if (r.rewrites.length > 0)
+            process.exit(1);
+    });
+}
+//# sourceMappingURL=migrate.js.map

package/dist/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "1.5.0",
-  "built_against_sdd_cli": "1.46.0"
+  "version": "2.0.0",
+  "built_against_sdd_cli": "2.0.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sdd-method/author-cli",
-  "version": "0.4.0",
-  "sddCliVersion": "1.46.0",
+  "version": "0.5.0",
+  "sddCliVersion": "2.0.0",
   "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",

package/scripts/validate-app-dependencies.sh

@@ -11,23 +11,23 @@
 #
 # Checks (for each entry in app-platform-dependencies.yaml), split by whether they
 # need a platform surface at all — LOCAL checks run wherever the app repo is:
-#   1.  (local)    required_stability is a valid value (provisional | locked | unknown)
+#   1.  (local)    required_stability is a valid value (provisional | stable | unknown)
 #   2a. (local)    service_id is declared and non-empty
 #   2b. (platform) service_id resolves against the platform source of truth:
 #                  catalogues/services.csv (exact id match) when the catalogue exists,
 #                  else docs/platform/service-architecture.md (word-anchored match)
-#   3a. (local)    a `locked` dependency declares a contract_path at all
+#   3a. (local)    a `stable` dependency declares a contract_path at all
 #   3b. (platform) that contract_path resolves to a file under the platform root
 #
 # Outputs a dependency status table.
-# Used as the Stage 6 agreement gate in the App Exploration Workflow.
+# Used as the Stage 9 agreement gate in the App Exploration Workflow.
 #
 # THE STABILITY VOCABULARY, AND WHY IT IS WHAT IT IS
 #   `required_stability` states the CONSUMING app's expectation of contract
 #   stability. Three values express that:
 #
 #     provisional  the contract may still change; the app tolerates it
-#     locked       the contract is fixed; a contract_path must exist (check 3)
+#     stable       the contract is fixed; a contract_path must exist (check 3)
 #     unknown      the expectation is not determined
 #
 #   `unknown` is accepted because the canonical schema's
@@ -158,7 +158,7 @@ APP_DEPS_FILE="$APP_ROOT/app-platform-dependencies.yaml"
 #   This gate read only the forward file, so an entire equal-status source went
 #   ungated. Measured in one reverse estate: 15 evidence files declaring 65
 #   further dependencies, 38 of them `locked` — precisely the population
-#   a Stage 6 agreement gate exists to check — none of which this gate could see.
+#   a Stage 9 agreement gate exists to check — none of which this gate could see.
 #
 #   A source that the catalogue reads and the gate does not is a coverage gap by
 #   construction, so the gate now reads both.
@@ -180,7 +180,7 @@ PLATFORM_SERVICES_CSV="$PLATFORM_ROOT/catalogues/services.csv"
 # offer (instances app-dependency-stability-vocabulary-forward and -reverse).
 VALID_STABILITY_VALUES=(
     "provisional"  # contract may still change; the app tolerates it
-    "locked"       # contract is fixed; check 3 requires a resolvable contract_path
+    "stable"       # contract is fixed; check 3 requires a resolvable contract_path
     "unknown"      # expectation not determined; no contract_path required
 )
 
@@ -353,6 +353,13 @@ validate_dependency() {
     service_id="$(yq e ".platform_dependencies[$index].service_id // \"\"" "$source_file")"
     contract_type="$(yq e ".platform_dependencies[$index].contract_type // \"\"" "$source_file")"
     required_stability="$(yq e ".platform_dependencies[$index].required_stability // \"\"" "$source_file")"
+    # vocabulary-alias: locked -> stable
+    # The fixed-contract stability class was `locked` (M-ADR 0222 §4.1; docs/method/foundations/vocabulary-renames.yaml).
+    # Read as `stable` for one major release and reported; from sdd-cli 3.0.0 it is invalid.
+    if [[ "$required_stability" == "locked" ]]; then
+        log_warn "$source_file: platform_dependencies[$index] uses the former required_stability 'locked', read as 'stable' (M-ADR 0222 §4.1). Run 'sdd-cli migrate vocabulary'; from sdd-cli 3.0.0 the former value is invalid."
+        required_stability="stable"
+    fi
     contract_path="$(yq e ".platform_dependencies[$index].contract_path // \"\"" "$source_file")"
 
     local dep_label="${service_id:-dep[$index]}"
@@ -403,7 +410,7 @@ validate_dependency() {
         done
 
         if [[ "$stability_deprecated" -eq 1 ]]; then
-            log_fail "$dep_label: required_stability '$required_stability' is not a stability value (M-ADR 0204 §4.4). Declare target_locus: '$required_stability' on the entry and give required_stability a real value (${VALID_STABILITY_VALUES[*]}) — a third-party contract can be locked."
+            log_fail "$dep_label: required_stability '$required_stability' is not a stability value (M-ADR 0204 §4.4). Declare target_locus: '$required_stability' on the entry and give required_stability a real value (${VALID_STABILITY_VALUES[*]}) — a third-party contract can be stable."
             ((dep_errors++))
         else
             log_fail "$dep_label: invalid required_stability '$required_stability' (allowed: ${VALID_STABILITY_VALUES[*]})"
@@ -490,26 +497,26 @@ validate_dependency() {
         ((WARNINGS++))
     fi
 
-    # Check 3: a locked dependency declares a contract_path (3a, local) and that path
-    # resolves to a file (3b, needs the platform). Same split, same reason: "locked
+    # Check 3: a stable dependency declares a contract_path (3a, local) and that path
+    # resolves to a file (3b, needs the platform). Same split, same reason: "stable
     # with no path at all" is an app-repo defect that needs nothing external to catch.
-    if [[ "$required_stability" == "locked" ]]; then
+    if [[ "$required_stability" == "stable" ]]; then
         if [[ -z "$contract_path" || "$contract_path" == "null" ]]; then
-            log_fail "$dep_label: required_stability is 'locked' but contract_path is empty"
+            log_fail "$dep_label: required_stability is 'stable' but contract_path is empty"
             ((dep_errors++))
         elif [[ "$PLATFORM_AVAILABLE" -eq 0 ]]; then
             ((UNRESOLVED_CONTRACT_PATHS++))
         else
             local full_contract_path="$PLATFORM_ROOT/$contract_path"
             if [[ ! -f "$full_contract_path" ]]; then
-                log_fail "$dep_label: locked contract_path '$contract_path' does not exist in platform repo"
+                log_fail "$dep_label: stable contract_path '$contract_path' does not exist in platform repo"
                 ((dep_errors++))
             fi
         fi
     elif [[ "$required_stability" == "provisional" || "$required_stability" == "unknown" ]]; then
         # Neither requires a contract_path. If one is declared it is still worth
         # reporting when it does not resolve — silently accepting a path that
-        # points at nothing is how a locked dependency later inherits a dead path.
+        # points at nothing is how a stable dependency later inherits a dead path.
         if [[ -n "$contract_path" && "$contract_path" != "null" && "$PLATFORM_AVAILABLE" -eq 1 ]]; then
             local full_contract_path="$PLATFORM_ROOT/$contract_path"
             if [[ ! -f "$full_contract_path" ]]; then
@@ -552,21 +559,22 @@ print_status_table() {
         local service_id required_stability contract_type contract_path dep_status
         service_id="$(yq e ".platform_dependencies[$i].service_id // \"(missing)\"" "$source_file")"
         required_stability="$(yq e ".platform_dependencies[$i].required_stability // \"(missing)\"" "$source_file")"
+        if [[ "$required_stability" == "locked" ]]; then required_stability="stable"; fi   # the former name, reported above
         contract_type="$(yq e ".platform_dependencies[$i].contract_type // \"(missing)\"" "$source_file")"
         contract_path="$(yq e ".platform_dependencies[$i].contract_path // \"\"" "$source_file")"
 
         # Determine display status
-        if [[ "$required_stability" == "locked" ]]; then
+        if [[ "$required_stability" == "stable" ]]; then
             if [[ -z "$contract_path" || "$contract_path" == "null" ]]; then
-                dep_status="${RED}LOCKED UNMET${NC}"
+                dep_status="${RED}STABLE UNMET${NC}"
             elif [[ "$PLATFORM_AVAILABLE" -eq 0 ]]; then
                 # A declared path that was never resolved is not "OK" and not "UNMET".
                 # Reporting either would be a claim the run cannot support.
-                dep_status="${YELLOW}LOCKED UNRESOLVED${NC}"
+                dep_status="${YELLOW}STABLE UNRESOLVED${NC}"
             elif [[ -f "$PLATFORM_ROOT/$contract_path" ]]; then
-                dep_status="${GREEN}LOCKED OK${NC}"
+                dep_status="${GREEN}STABLE OK${NC}"
             else
-                dep_status="${RED}LOCKED UNMET${NC}"
+                dep_status="${RED}STABLE UNMET${NC}"
             fi
         elif [[ "$required_stability" == "provisional" ]]; then
             dep_status="${YELLOW}PROVISIONAL${NC}"
@@ -637,7 +645,7 @@ main() {
     fi
 
     if [[ "$FAILURES" -gt 0 ]]; then
-        log_fail "$FAILURES dependency check(s) failed. Stage 6 agreement gate NOT met."
+        log_fail "$FAILURES dependency check(s) failed. Stage 9 agreement gate NOT met."
         exit 1
     fi
 
@@ -648,7 +656,7 @@ main() {
     # while never executing (M-ADR 0200 §4.3).
     if [[ "$PLATFORM_AVAILABLE" -eq 0 ]]; then
         log_warn "Ran check 1 (stability vocabulary) and the local halves of checks 2-3 over $TOTAL_DEPS dependency(ies): $FAILURES failure(s), $WARNINGS warning(s)."
-        log_warn "NOT RUN, for want of --platform-root: $UNRESOLVED_SERVICE_IDS service_id resolution(s) and $UNRESOLVED_CONTRACT_PATHS locked contract_path resolution(s)."
+        log_warn "NOT RUN, for want of --platform-root: $UNRESOLVED_SERVICE_IDS service_id resolution(s) and $UNRESOLVED_CONTRACT_PATHS stable contract_path resolution(s)."
         log_info "This is a partial run, not a met gate — pass --platform-root to complete it."
         exit 0
     fi
@@ -656,7 +664,7 @@ main() {
     if [[ "$WARNINGS" -gt 0 ]]; then
         log_warn "All required checks passed with $WARNINGS warning(s)."
     else
-        log_pass "All dependency checks passed. Stage 6 agreement gate met."
+        log_pass "All dependency checks passed. Stage 9 agreement gate met."
     fi
     exit 0
 }