@sdd-method/author-cli 0.3.0 → 0.5.0

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.4.0",
-  "built_against_sdd_cli": "1.45.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.4.0",
-  "built_against_sdd_cli": "1.45.0"
+  "version": "2.0.0",
+  "built_against_sdd_cli": "2.0.0"
 }

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@sdd-method/author-cli",
-  "version": "0.3.0",
-  "sddCliVersion": "1.45.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": "Apache-2.0",
+  "license": "UNLICENSED",
   "type": "module",
   "bin": {
     "sdd-author": "dist/author-bin.js"
@@ -23,8 +23,6 @@
   "files": [
     "dist",
     "scripts",
-    "README.md",
-    "LICENSE",
-    "NOTICE"
+    "README.md"
   ]
 }

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 lock-in 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
@@ -157,8 +157,8 @@ 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 lock-in population
-#   a Stage 6 lock-in gate exists to check — none of which this gate could see.
+#   further dependencies, 38 of them `locked` — precisely the population
+#   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 lock-in 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 lock-in gate met."
+        log_pass "All dependency checks passed. Stage 9 agreement gate met."
     fi
     exit 0
 }

package/scripts/validate-integration-docs.sh

@@ -341,7 +341,7 @@ check_grounding_doc() {
 
     local grounding="$REPO_ROOT/docs/design/integration/feature-grounding.md"
     if [[ ! -f "$grounding" ]]; then
-        log_warn "docs/design/integration/feature-grounding.md not found — create before lock-in"
+        log_warn "docs/design/integration/feature-grounding.md not found — create before agreement"
         return
     fi