@sdd-method/verify-cli 2.1.0 → 2.3.0

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

@@ -7,7 +7,7 @@
 # Emitted by sdd-cli's YAML emitter with no line folding; the three header scalars are quoted for the
 # textual readers downstream. The one deliberate difference from the authored form is schema_status:
 # the authored form says canonical; a projection never does.
-schema_version: "4.0.0"
+schema_version: "4.1.0"
 schema_owner: "sdd-method"
 schema_status: "generated"
 enums:
@@ -361,6 +361,7 @@ enums:
     - value: graphql
     - value: rpc
     - value: authz
+    - value: cli
     description: Contract kind. Bound at 3.13.0 from the column descriptions; measured against both reference estates before binding (M-ADR 0205 §4.4).
   contract_status:
     values:
@@ -1552,7 +1553,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 agreement gate certified .zed schemas as contracts while no kind could represent them.
+      description: rest | graphql | rpc | event | authz | cli. 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; cli covers a command-line interface's command manifest (its commands, options and exit codes), added at 4.1.0 because a command-line tool often serves no REST, RPC, event or authorization contract, so its behaviour baselines had nothing to name as their surface.
     - name: version
       type: string
       nullable: true

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

@@ -281,47 +281,47 @@ export function renderContractCoverage(res, tier) {
 }
 // ─── the nine Phase-0 gate checks ────────────────────────────────────────
 export function renderEventCatalogueCheck(gaps) {
-    return gaps.map((g) => `[finding] coverage: domain ${g.domain} event-catalog.yaml declares ${g.declared} events but events.csv contains ${g.emitted} rows for that domain (per ADR 0156 Phase 0)`);
+    return gaps.map((g) => `[finding] coverage: domain ${g.domain} event-catalog.yaml declares ${g.declared} events but events.csv contains ${g.emitted} rows for that domain (per M-ADR 0156 Phase 0)`);
 }
 export function renderRepoEdgesCheck(res) {
     const lines = [];
     if (res.repoCapabilityGap) {
         const g = res.repoCapabilityGap;
-        lines.push(`[finding] coverage: repo_capability.csv is empty but ${g.capabilityService} capability_service rows + ${g.servicesWithRepo} services with primary_repo_id present — reverse-method derivation likely missing (per ADR 0157 §4.3, Phase 0)`);
+        lines.push(`[finding] coverage: repo_capability.csv is empty but ${g.capabilityService} capability_service rows + ${g.servicesWithRepo} services with primary_repo_id present — reverse-method derivation likely missing (per M-ADR 0157 §4.3, Phase 0)`);
     }
     if (res.repoContractForwardGap) {
         const g = res.repoContractForwardGap;
-        lines.push(`[finding] coverage: repo_contract.csv is empty but ${g.contracts} contracts and ${g.repoConfigsWithContracts} repo-configs with contracts: blocks present — forward-method derivation likely missing (per ADR 0157 §4.2, Phase 0)`);
+        lines.push(`[finding] coverage: repo_contract.csv is empty but ${g.contracts} contracts and ${g.repoConfigsWithContracts} repo-configs with contracts: blocks present — forward-method derivation likely missing (per M-ADR 0157 §4.2, Phase 0)`);
     }
     if (res.repoContractPathXGap) {
         const g = res.repoContractPathXGap;
-        lines.push(`[finding] coverage: repo_contract.csv is empty but ${g.serviceContracts} service_contract rows + ${g.servicesWithRepo} services with primary_repo_id present — reverse-method Path X (service_contract ⋈ services.primary_repo_id) derivation likely missing (per ADR 0157 §4.2, Phase 0)`);
+        lines.push(`[finding] coverage: repo_contract.csv is empty but ${g.serviceContracts} service_contract rows + ${g.servicesWithRepo} services with primary_repo_id present — reverse-method Path X (service_contract ⋈ services.primary_repo_id) derivation likely missing (per M-ADR 0157 §4.2, Phase 0)`);
     }
     if (res.repoContractReverseGap) {
         const g = res.repoContractReverseGap;
-        lines.push(`[finding] coverage: repo_contract.csv is empty with ${g.contracts} contracts present and no repo-config.contracts: blocks or service_contract rows — reverse-method derivation via contracts.source_repo_id likely missing (per ADR 0157 §4.2, Phase 0)`);
+        lines.push(`[finding] coverage: repo_contract.csv is empty with ${g.contracts} contracts present and no repo-config.contracts: blocks or service_contract rows — reverse-method derivation via contracts.source_repo_id likely missing (per M-ADR 0157 §4.2, Phase 0)`);
     }
     return lines;
 }
 export function renderGlossaryXrefCheck(finding) {
     return finding
         ? [
-            `[finding] coverage: docs/platform/reference/glossary-alignment-manifest.yaml exists but glossary_xref.csv emits 0 rows — multi-source derivation likely missing (per ADR 0158 §4.5, Phase 0)`,
+            `[finding] coverage: docs/platform/reference/glossary-alignment-manifest.yaml exists but glossary_xref.csv emits 0 rows — multi-source derivation likely missing (per M-ADR 0158 §4.5, Phase 0)`,
         ]
         : [];
 }
 export function renderDataModelEntitiesCheck(res) {
     const lines = [];
     if (res.entitiesGap) {
-        lines.push(`[finding] coverage: ${res.entitiesGap.domainModels} domain-model files catalogued but entities.csv emits 0 rows — reverse-method entity extraction missing (per ADR 0159 Phase 0)`);
+        lines.push(`[finding] coverage: ${res.entitiesGap.domainModels} domain-model files catalogued but entities.csv emits 0 rows — reverse-method entity extraction missing (per M-ADR 0159 Phase 0)`);
     }
     if (res.serviceEntityGap) {
         const g = res.serviceEntityGap;
-        lines.push(`[finding] coverage: ${g.entities} entities + ${g.services} services catalogued but service_entity.csv emits 0 rows — Data Store Mapping ingestion missing (per ADR 0159 Phase 0)`);
+        lines.push(`[finding] coverage: ${g.entities} entities + ${g.services} services catalogued but service_entity.csv emits 0 rows — Data Store Mapping ingestion missing (per M-ADR 0159 Phase 0)`);
     }
     if (res.containerEntityGap) {
         const g = res.containerEntityGap;
-        lines.push(`[finding] coverage: ${g.containersWithService} containers map to services + ${g.serviceEntity} service_entity edges present but c4_container_entity.csv emits 0 rows — Phase 3 derivation missing (per ADR 0159 Phase 0)`);
+        lines.push(`[finding] coverage: ${g.containersWithService} containers map to services + ${g.serviceEntity} service_entity edges present but c4_container_entity.csv emits 0 rows — Phase 3 derivation missing (per M-ADR 0159 Phase 0)`);
     }
     return lines;
 }
@@ -329,24 +329,24 @@ export function renderCapabilityEventCheck(res) {
     const lines = [];
     if (res.derivableGap) {
         const g = res.derivableGap;
-        lines.push(`[finding] coverage: service_event (${g.serviceEvent}) + capability_service (${g.capabilityService}) populated but capability_event emits 0 rows — reverse-derivable edge missing (per ADR 0160 Phase 0)`);
+        lines.push(`[finding] coverage: service_event (${g.serviceEvent}) + capability_service (${g.capabilityService}) populated but capability_event emits 0 rows — reverse-derivable edge missing (per M-ADR 0160 Phase 0)`);
     }
     if (res.authoredGap) {
-        lines.push(`[finding] coverage: capability_event has ${res.authoredGap.derived} derived rows but 0 authored rows — no traceability.events[] or traceability.contracts.{published,consumed}_events declarations are landing in the catalogue. Governance queries filtering to source=authored will return empty (per ADR 0160 Phase 0)`);
+        lines.push(`[finding] coverage: capability_event has ${res.authoredGap.derived} derived rows but 0 authored rows — no traceability.events[] or traceability.contracts.{published,consumed}_events declarations are landing in the catalogue. Governance queries filtering to source=authored will return empty (per M-ADR 0160 Phase 0)`);
     }
     return lines;
 }
 export function renderFeatureEventCheck(res) {
     return res.gap
         ? [
-            `[finding] coverage: service_event (${res.gap.serviceEvent}) + feature_service (${res.gap.featureService}) populated but feature_event emits 0 rows — reverse-derivable edge missing (per ADR 0161 Phase 0)`,
+            `[finding] coverage: service_event (${res.gap.serviceEvent}) + feature_service (${res.gap.featureService}) populated but feature_event emits 0 rows — reverse-derivable edge missing (per M-ADR 0161 Phase 0)`,
         ]
         : [];
 }
 export function renderPlatformDependenciesCheck(finding) {
     return finding
         ? [
-            `[finding] coverage: app-platform-dependencies.yaml declares a platform_dependencies block but product_platform_dependencies.csv emits 0 rows — forward-method ingestion missing (per ADR 0162 Phase 0). Resolves once the builder reads the forward source.`,
+            `[finding] coverage: app-platform-dependencies.yaml declares a platform_dependencies block but product_platform_dependencies.csv emits 0 rows — forward-method ingestion missing (per M-ADR 0162 Phase 0). Resolves once the builder reads the forward source.`,
         ]
         : [];
 }
@@ -358,7 +358,7 @@ export function renderFeatureSpecPromotionCheck(res) {
         `[finding] coverage: ${f.intermediate} of ${f.total} features are reverse-intermediate ` +
             `(capability-spec/feature-grounding) not yet promoted to feature-spec — ` +
             `unresolvable as realises:/FK targets (${f.pctResolvable}% resolvable, ${f.note}; ` +
-            `per ADR 0177 §4.2)`,
+            `per M-ADR 0177 §4.2)`,
     ];
 }
 export function renderFeatureSurfaceDuplicationCheck(res) {
@@ -370,7 +370,7 @@ export function renderFeatureSurfaceDuplicationCheck(res) {
         `[finding] coverage: ${f.pairs} near-duplicate feature surface(s) across ` +
             `${f.capabilities} ${capWord} — a capability-spec (rollup) and feature-grounding ` +
             `(detailed) slug naming the same surface; reconcile to one slug per surface, ` +
-            `detailed slug canonical (per ADR 0177 §4.3)`,
+            `detailed slug canonical (per M-ADR 0177 §4.3)`,
     ];
 }
 // ─── Scores coverage (M-ADR 0205 §4.5, B2 — the fourteenth check) ─────────

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

@@ -1,7 +1,7 @@
 /**
  * Deterministic CSV writer for catalogues.
  *
- * Emits headers + sorted rows per ADR 0134 builder contract:
+ * Emits headers + sorted rows per M-ADR 0134 builder contract:
  *   - column order matches the canonical schema exactly,
  *   - rows sorted by primary-key value,
  *   - cells with embedded comma/quote/newline are RFC-4180 quoted,

package/dist/lib/catalogue/findings.js

@@ -1,5 +1,5 @@
 /**
- * Findings collector for the canonical builder per ADR 0134 / builder-spec
+ * Findings collector for the canonical builder per M-ADR 0134 / builder-spec
  * §"Emit findings as it parses".
  *
  * Findings are human-readable AND machine-parseable. Format per finding:

package/dist/lib/catalogue/fk-validator.js

@@ -1,5 +1,5 @@
 /**
- * FK validator per ADR 0134 builder-spec §"Run internal FK validation
+ * FK validator per M-ADR 0134 builder-spec §"Run internal FK validation
  * before exiting" + §"External FK handling".
  *
  * For each catalogue's foreign keys:
@@ -9,7 +9,7 @@
  *   - External FKs (external=true, or external for the build's profile via
  *     `externalForProfiles` — schema 2.23.0): every non-empty value is logged
  *     as a `[finding] external` line and skipped from validation. The
- *     aggregator resolves these post-merge per ADR 0134 §4.5. A required
+ *     aggregator resolves these post-merge per M-ADR 0134 §4.5. A required
  *     (non-nullable) external FK still fails when EMPTY — the value must be
  *     named even if it resolves cross-SDD.
  *

package/dist/lib/catalogue/manifest-loader.js

@@ -223,8 +223,8 @@ const ManifestSchema = z.object({
     // shape here. Whether the value resolves against the active vocabulary
     // (method ∪ RA-bundle ∪ adopter) is checked in the build step, which has
     // the bundle cache. Absent reads as "unclassified" (with a finding). Named
-    // application_archetype to stay distinct from the ADR 0173 domain archetype
-    // and the ADR 0169 openui archetype.
+    // application_archetype to stay distinct from the M-ADR 0173 domain archetype
+    // and the M-ADR 0169 openui archetype.
     application_archetype: z
         .string()
         .regex(/^[a-z][a-z0-9-]*$/, {
@@ -298,7 +298,7 @@ export async function loadSddManifest(sddPath, options) {
         const code = err.code;
         if (code === "ENOENT") {
             throw new Error(`SDD manifest not found at ${sourcePath}\n\n` +
-                `Every SDD repo MUST declare an .sdd/sdd-manifest.yaml per ADR 0134 §4.6.\n` +
+                `Every SDD repo MUST declare an .sdd/sdd-manifest.yaml per M-ADR 0134 §4.6.\n` +
                 `Schema: docs/method/methods/sdd-manifest-schema.yaml in sdd-method.\n` +
                 `Bootstrap: \`sdd-cli init\` (when migrated to support manifest authoring).`);
         }

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

@@ -23,8 +23,8 @@
  *     release; migration tooling (`sdd-cli migrate <schema> --to <v>`,
  *     planned) covers downgrade paths.
  *
- * See ADR 0132 (catalogue-integrity gate's schema-drift digest hook) +
- * ADR 0134 §4.6 (canonical builder + aggregator).
+ * See M-ADR 0132 (catalogue-integrity gate's schema-drift digest hook) +
+ * M-ADR 0134 §4.6 (canonical builder + aggregator).
  */
 export const SCHEMA_COMPAT = {
     catalogue_schema: "^4.0.0",

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

@@ -1,7 +1,7 @@
 /**
  * Loader for the canonical catalogue-schema.yaml vendored from sdd-method.
  *
- * Per ADR 0134 §4.6 the canonical builder reads the schema rather than
+ * Per M-ADR 0134 §4.6 the canonical builder reads the schema rather than
  * hardcoding column shapes or FK rules. This loader is the only place in
  * the CLI that knows the schema file's location.
  */

package/dist/lib/metamodel/tql-subset-parser.js

@@ -0,0 +1,280 @@
+// The documented TypeQL subset — PARSER (M-ADR 0210 §4.2).
+//
+// This module reads the authored form of a fact-based model and nothing else: it knows
+// the subset's grammar and refuses, with a located error, anything outside it. It knows
+// nothing about catalogues, YAML or projections — that is `schema-projection.ts`. The split
+// is deliberate: a store extending the subset extends the parser; the method's projection
+// is one consumer of the parsed model among possible others.
+//
+// Fail-closed (M-ADR 0200 §4.3): a construct the parser does not recognise is a ParseError,
+// never a skip. The five blindnesses measured in the prototype this replaces — `@values`,
+// an `@card` form outside the subset, a role with two players, a value-type/family
+// contradiction, a content change that must be visible — are each refused here or made
+// visible to the projection, and the round-trip gate proves that with mutation controls
+// before every verdict.
+//
+// Grammar (one declaration per line; `#` outside a string literal starts a comment):
+//   define
+//   attribute <label>, value <string|integer|double|boolean|date|datetime>;
+//   entity <label>[, owns <attr> [@key] [@card(1..1)|@card(0..1)|@card(0..)]][, plays <rel>:<role> [...]] ...;
+//   relation <label>[, relates <role> [@card(1..1)|@card(0..1)|@card(0..)]][, owns ...][, plays ...] ...;
+// Meta rows (the second file):
+//   insert $m isa <meta-type>, has <key> <"string"|int|true|false>[, has ...];
+export class ParseError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ParseError";
+    }
+}
+export const VALUE_TYPES = new Set(["string", "integer", "double", "boolean", "date", "datetime"]);
+export const META_TYPES = new Set([
+    "schema-meta",
+    "catalogue-meta",
+    "column-meta",
+    "fk-meta",
+    "column-enum-meta",
+    "enum-meta",
+    "enum-value-meta",
+    "enum-value-property",
+    "coverage-meta",
+    "relationship-meta",
+    "vocabulary-meta",
+    "rule-meta",
+]);
+/** Meta keys whose values are lists (repeated `has` on one row). */
+const LIST_KEYS = new Set(["m-external-for-profile", "m-reads"]);
+function unlit(s, where) {
+    let out = "";
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (c === "\\" && i + 1 < s.length) {
+            const n = s[i + 1];
+            const map = { n: "\n", t: "\t", '"': '"', "\\": "\\" };
+            const r = map[n];
+            if (r === undefined)
+                throw new ParseError(`${where}: bad escape \\${n}`);
+            out += r;
+            i++;
+        }
+        else {
+            out += c;
+        }
+    }
+    return out;
+}
+/** A `#` outside a string literal starts a comment. */
+export function stripComment(line) {
+    let out = "";
+    let q = false;
+    for (let i = 0; i < line.length; i++) {
+        const c = line[i];
+        if (c === '"' && (i === 0 || line[i - 1] !== "\\"))
+            q = !q;
+        if (c === "#" && !q)
+            break;
+        out += c;
+    }
+    return out.trim();
+}
+const CARD_RE = /^@card\((\d+)\.\.(\d*)\)$/;
+function parseAnnotations(tokens, where) {
+    let key = false;
+    let required = false;
+    let multi = false;
+    let optional = false;
+    for (const t of tokens) {
+        if (t === "@key") {
+            key = true;
+        }
+        else if (t.startsWith("@card(")) {
+            const m = CARD_RE.exec(t);
+            if (!m)
+                throw new ParseError(`${where}: unparseable cardinality ${JSON.stringify(t)}`);
+            const lo = m[1];
+            const hi = m[2];
+            if (lo === "1" && hi === "1")
+                required = true;
+            else if (lo === "0" && hi === "")
+                multi = true;
+            else if (lo === "0" && hi === "1")
+                optional = true;
+            else
+                throw new ParseError(`${where}: cardinality ${t} cannot be projected onto the catalogue schema (only @card(1..1), @card(0..1) or @card(0..) are in the subset)`);
+        }
+        else if (t.startsWith("@values")) {
+            throw new ParseError(`${where}: @values(...) is not admitted in this projection — vocabularies bind through column_enums meta rows or a recorded absence (M-ADR 0210 §4.5)`);
+        }
+        else {
+            throw new ParseError(`${where}: unknown token ${JSON.stringify(t)}`);
+        }
+    }
+    return { key, required, multi, optional };
+}
+function splitClauses(body, where) {
+    // refuse before the naive split can be fooled by a comma inside the parenthesis
+    if (body.includes("@values")) {
+        throw new ParseError(`${where}: @values(...) is not admitted in this projection (M-ADR 0210 §4.5)`);
+    }
+    return body.split(",").map((c) => c.trim());
+}
+const ATTR_RE = /^attribute ([a-z][a-z0-9-]*), value ([a-z]+)$/;
+const TYPE_RE = /^(entity|relation) ([a-z][a-z0-9-]*)(?:, (.*))?$/;
+/** Parse the type-system file. `fileLabel` names the file in error locations. */
+export function parseTypes(text, fileLabel = "catalogue-schema.tql", options = {}) {
+    const singlePlayer = options.singlePlayer ?? true;
+    const attrs = new Map();
+    const entities = new Map();
+    const relations = new Map();
+    const seen = new Set();
+    const lines = text.split(/\r?\n/);
+    for (let ln = 1; ln <= lines.length; ln++) {
+        let line = stripComment(lines[ln - 1]);
+        if (line === "" || line === "define")
+            continue;
+        const where = `${fileLabel}:${ln}`;
+        if (!line.endsWith(";"))
+            throw new ParseError(`${where}: declaration must end with ';' — one declaration per line`);
+        line = line.slice(0, -1);
+        const am = ATTR_RE.exec(line);
+        if (am) {
+            const lab = am[1];
+            const vt = am[2];
+            if (!VALUE_TYPES.has(vt))
+                throw new ParseError(`${where}: unknown value type ${JSON.stringify(vt)}`);
+            if (seen.has(lab))
+                throw new ParseError(`${where}: duplicate declaration of ${JSON.stringify(lab)}`);
+            seen.add(lab);
+            attrs.set(lab, vt);
+            continue;
+        }
+        const tm = TYPE_RE.exec(line);
+        if (!tm)
+            throw new ParseError(`${where}: not in the subset: ${JSON.stringify(line.slice(0, 100))}`);
+        const kind = tm[1];
+        const lab = tm[2];
+        const body = tm[3];
+        if (seen.has(lab))
+            throw new ParseError(`${where}: duplicate declaration of ${JSON.stringify(lab)}`);
+        seen.add(lab);
+        const decl = { owns: new Map(), plays: new Map(), relates: new Map() };
+        for (const clause of body !== undefined ? splitClauses(body, where) : []) {
+            const w = clause.split(/\s+/).filter((x) => x !== "");
+            if (w.length === 0)
+                throw new ParseError(`${where}: empty clause`);
+            const head = w[0];
+            if (head === "owns") {
+                if (w.length < 2)
+                    throw new ParseError(`${where}: owns without attribute`);
+                if (decl.owns.has(w[1]))
+                    throw new ParseError(`${where}: ${lab} owns ${w[1]} twice`);
+                decl.owns.set(w[1], parseAnnotations(w.slice(2), where));
+            }
+            else if (head === "plays") {
+                if (w.length < 2 || !w[1].includes(":"))
+                    throw new ParseError(`${where}: plays needs <relation>:<role>`);
+                if (decl.plays.has(w[1]))
+                    throw new ParseError(`${where}: ${lab} plays ${w[1]} twice`);
+                decl.plays.set(w[1], parseAnnotations(w.slice(2), where));
+            }
+            else if (head === "relates") {
+                if (kind !== "relation")
+                    throw new ParseError(`${where}: only a relation relates`);
+                if (w.length < 2)
+                    throw new ParseError(`${where}: relates without role`);
+                if (decl.relates.has(w[1]))
+                    throw new ParseError(`${where}: ${lab} relates ${w[1]} twice`);
+                decl.relates.set(w[1], parseAnnotations(w.slice(2), where));
+            }
+            else {
+                throw new ParseError(`${where}: unknown clause ${JSON.stringify(head)}`);
+            }
+        }
+        (kind === "entity" ? entities : relations).set(lab, decl);
+    }
+    // every owned attribute must be declared; every role must exist; a role has at most ONE player
+    const playersAll = new Map();
+    for (const [lab, d] of [...entities, ...relations]) {
+        for (const a of d.owns.keys()) {
+            if (!attrs.has(a))
+                throw new ParseError(`${lab} owns undeclared attribute ${JSON.stringify(a)}`);
+        }
+        for (const rr of d.plays.keys()) {
+            const idx = rr.indexOf(":");
+            const rel = rr.slice(0, idx);
+            const role = rr.slice(idx + 1);
+            const r = relations.get(rel);
+            if (!r)
+                throw new ParseError(`${lab} plays role of undeclared relation ${JSON.stringify(rel)}`);
+            if (!r.relates.has(role))
+                throw new ParseError(`${lab} plays undeclared role ${JSON.stringify(rr)}`);
+            const list = playersAll.get(rr) ?? [];
+            list.push(lab);
+            playersAll.set(rr, list);
+        }
+    }
+    const players = new Map();
+    for (const [rr, ps] of playersAll) {
+        if (ps.length > 1 && !singlePlayer)
+            continue;
+        if (ps.length > 1) {
+            throw new ParseError(`role ${rr} has ${ps.length} players (${ps.join(", ")}); the projection can carry exactly one and refuses to pick`);
+        }
+        players.set(rr, ps[0]);
+    }
+    return { attrs, entities, relations, players, playersAll };
+}
+const ROW_RE = /^insert \$m isa ([a-z][a-z0-9-]*), (.*);$/;
+const TOK_RE = /has ([a-z][a-z0-9-]*) ("(?:[^"\\]|\\.)*"|-?\d+|true|false)/y;
+export function parseMeta(text, fileLabel = "catalogue-schema-meta.tql", options = {}) {
+    const metaTypes = options.metaTypes ?? META_TYPES;
+    const rows = new Map();
+    const lines = text.split(/\r?\n/);
+    for (let ln = 1; ln <= lines.length; ln++) {
+        const line = stripComment(lines[ln - 1]);
+        if (line === "")
+            continue;
+        const where = `${fileLabel}:${ln}`;
+        const m = ROW_RE.exec(line);
+        if (!m)
+            throw new ParseError(`${where}: not in the subset: ${JSON.stringify(line.slice(0, 100))}`);
+        const typ = m[1];
+        const body = m[2];
+        if (!metaTypes.has(typ))
+            throw new ParseError(`${where}: unknown meta type ${JSON.stringify(typ)}`);
+        const acc = new Map();
+        let i = 0;
+        for (;;) {
+            TOK_RE.lastIndex = i;
+            const t = TOK_RE.exec(body);
+            if (!t)
+                throw new ParseError(`${where}: meta row body not in the subset at offset ${i}: ${JSON.stringify(body.slice(i, i + 60))}`);
+            const k = t[1];
+            const v = t[2];
+            let val;
+            if (v.startsWith('"'))
+                val = unlit(v.slice(1, -1), where);
+            else if (v === "true" || v === "false")
+                val = v === "true";
+            else
+                val = Number.parseInt(v, 10);
+            const list = acc.get(k) ?? [];
+            list.push(val);
+            acc.set(k, list);
+            i = TOK_RE.lastIndex;
+            if (i === body.length)
+                break;
+            if (body.startsWith(", ", i))
+                i += 2;
+            else
+                throw new ParseError(`${where}: expected ', has ...' at offset ${i}: ${JSON.stringify(body.slice(i, i + 40))}`);
+        }
+        const row = {};
+        for (const [k, vs] of acc)
+            row[k] = LIST_KEYS.has(k) ? vs : vs[0];
+        const list = rows.get(typ) ?? [];
+        list.push(row);
+        rows.set(typ, list);
+    }
+    return rows;
+}
+//# sourceMappingURL=tql-subset-parser.js.map

package/dist/lib/pack/schema.js

@@ -26,7 +26,7 @@ export const PackSeedSchema = z.object({
     scope: z
         .string()
         .regex(/^[a-z0-9-]+$/, "scope must be lower-kebab-case slug"),
-    // Optional per ADR 0176 §4.6: absent = profile-agnostic pack.
+    // Optional per M-ADR 0176 §4.6: absent = profile-agnostic pack.
     forwardBase: z
         .object({
         bundle: z.enum(KNOWN_FORWARD_BASES),
@@ -66,7 +66,7 @@ export const PackSeedSchema = z.object({
         .array(z.string().min(1))
         .min(1, "managed_paths must have at least one entry"),
     forbiddenPaths: z.array(z.string()).optional(),
-    // ADR 0176 §4.3: scaffold-source path prefixes; each must cover at
+    // M-ADR 0176 §4.3: scaffold-source path prefixes; each must cover at
     // least one managed_paths entry (checked in the superRefine below).
     scaffoldSourcePaths: z.array(z.string().min(1)).optional(),
     requiresPack: z

package/dist/lib/pack/seed.js

@@ -2,7 +2,7 @@ import { readFile } from "node:fs/promises";
 import { dirname, isAbsolute, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
 /**
- * Adopter pack seed file. Per ADR 0151 + context-pack-seed-schema.yaml.
+ * Adopter pack seed file. Per M-ADR 0151 + context-pack-seed-schema.yaml.
  *
  * Loaded by `sdd-cli pack build` and `sdd-cli pack validate` from
  * `orchestration/distribution/{pack-name}-seed.yaml` in adopter repos.
@@ -120,7 +120,7 @@ async function loadSeedRecursive(absPath, visited) {
     const seed = {
         version: asString(own.version, "version", absPath),
         scope: asString(own.scope, "scope", absPath),
-        // forward_base optional per ADR 0176 §4.6 (profile-agnostic packs omit it)
+        // forward_base optional per M-ADR 0176 §4.6 (profile-agnostic packs omit it)
         ...(own.forward_base && {
             forwardBase: {
                 bundle: asString(own.forward_base.bundle, "forward_base.bundle", absPath),

package/dist/lib/pack/validate.js

@@ -36,7 +36,7 @@ export async function runPackValidate(opts, stdout = (s) => process.stdout.write
     stdout(pass(`Seed valid: ${seed.scope} v${seed.version}`));
     stdout(info(seed.forwardBase
         ? `Forward base: ${seed.forwardBase.bundle} >= ${seed.forwardBase.minimumVersion}`
-        : "Forward base: none (profile-agnostic pack, ADR 0176 §4.6)"));
+        : "Forward base: none (profile-agnostic pack, M-ADR 0176 §4.6)"));
     if (seed.scaffoldSourcePaths) {
         stdout(info(`Scaffold-source prefixes: ${seed.scaffoldSourcePaths.join(", ")}`));
     }

package/dist/lib/repo-kind.js

@@ -2,7 +2,7 @@ import { readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 /**
  * Forward-base bundles set `.sdd-repo-kind` and qualify as the base
- * layer that additive extensions can compose on top of (per ADR 0135).
+ * layer that additive extensions can compose on top of (per M-ADR 0135).
  * The legacy self-contained `reverse-baseline` is retained as a
  * forward base for compat with adopters who haven't migrated to the
  * `reverse-extension-baseline` additive shape yet.
@@ -59,7 +59,7 @@ export function repoKindFromProfile(profile) {
 /**
  * Returns the profile a bundle authoritatively claims, or null for
  * additive bundles that don't claim a profile of their own. Accepts
- * arbitrary strings (adopter pack names per ADR 0151) and returns null
+ * arbitrary strings (adopter pack names per M-ADR 0151) and returns null
  * for any name not in the closed sdd-method bundle set.
  */
 export function profileFromBundleName(name) {
@@ -73,7 +73,7 @@ export function bundleNameFromProfile(profile) {
 /**
  * Forward-base bundles set `.sdd-repo-kind` and qualify as the base
  * layer that additive extensions compose on top of. Additive bundles
- * (sdd-method's `reverse-extension-baseline` and ADR 0151 adopter
+ * (sdd-method's `reverse-extension-baseline` and M-ADR 0151 adopter
  * packs) return false. Accepts arbitrary strings; unknown names return
  * false.
  */

package/dist/lib/scaffold/archetype-behaviour.js

@@ -0,0 +1,171 @@
+// Archetype behaviour, seeded once and then cited (reference architecture sdm-d93u.4.1).
+//
+// A reference-architecture archetype ships its behaviour as canonical rows (behaviour.tql, rows of the
+// behaviour schema in the M-ADR 0210 subset). An estate does not sync them: it takes them ONCE, when it
+// scaffolds the domain, as an OpenSpec change that ADDS the archetype's requirements to its behaviour store,
+// to agree and build through its own process like any other change (M-ADR 0221-0223). From then on the
+// estate owns its requirements and CITES the archetype's: docs/domains/<domain>/archetype-citations.yaml
+// records, per requirement, the archetype requirement it answers to, the bundle version and a digest of that
+// requirement there, and how the estate's relates to it (derived, extended, narrowed, or departed with a
+// reason and the decision that took it). The validator `archetype-citations` reports a citation whose source
+// has changed since, so evolution is visible rather than silent; re-aligning is a re-pin.
+//
+// The generated OpenSpec spec the reference architecture keeps beside its rows is never read here: the rows
+// are the source, and two homes for one behaviour is what M-ADR 0221 rules out.
+import { createHash } from "node:crypto";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { stringify as stringifyYaml } from "yaml";
+import { parseMeta } from "../metamodel/tql-subset-parser.js";
+export const BEHAVIOUR_FILE = "behaviour.tql";
+export const CITATIONS_FILE = "archetype-citations.yaml";
+export const RELATIONS = ["derived", "extended", "narrowed", "departed"];
+const BEHAVIOUR_META = new Set(["requirement-meta", "scenario-meta", "scenario-step-meta", "cite-meta"]);
+const str = (r, k) => String(r[k] ?? "");
+const num = (r, k) => Number(r[k] ?? 0);
+/** The archetype's requirements, in position order, from its behaviour rows. */
+export function parseArchetypeBehaviour(text, label) {
+    const rows = parseMeta(text, label, { metaTypes: BEHAVIOUR_META });
+    const reqs = [...(rows.get("requirement-meta") ?? [])].sort((a, b) => num(a, "m-position") - num(b, "m-position"));
+    const scen = rows.get("scenario-meta") ?? [];
+    const steps = rows.get("scenario-step-meta") ?? [];
+    const cites = rows.get("cite-meta") ?? [];
+    return reqs.map((r) => {
+        const id = str(r, "m-requirement");
+        const scenarios = scen
+            .filter((x) => str(x, "m-requirement") === id)
+            .sort((a, b) => num(a, "m-position") - num(b, "m-position"))
+            .map((x) => {
+            const sid = str(x, "m-scenario");
+            return {
+                id: sid,
+                title: str(x, "m-title"),
+                steps: steps
+                    .filter((t) => str(t, "m-scenario") === sid)
+                    .sort((a, b) => num(a, "m-position") - num(b, "m-position"))
+                    .map((t) => ({ keyword: str(t, "m-keyword"), text: str(t, "m-text") })),
+                cites: cites.filter((c) => str(c, "m-scenario") === sid).map((c) => str(c, "m-cites")),
+            };
+        });
+        const req = {
+            id,
+            title: str(r, "m-title"),
+            statement: str(r, "m-statement"),
+            tier: str(r, "m-tier"),
+            ruleFile: str(r, "m-rule-file"),
+            ruleLabel: str(r, "m-rule-label"),
+            scenarios,
+        };
+        return { ...req, digest: requirementDigest(req) };
+    });
+}
+/** Digest of everything a citation answers to: wording, tier, source rule and scenarios, not position. */
+export function requirementDigest(r) {
+    const canon = JSON.stringify([r.id, r.title, r.statement, r.tier, r.ruleFile, r.ruleLabel,
+        r.scenarios.map((s) => [s.id, s.title, s.steps.map((t) => [t.keyword, t.text]), [...s.cites].sort()])]);
+    return createHash("sha256").update(canon).digest("hex").slice(0, 12);
+}
+/** The archetype's behaviour rows in a cached bundle: <bundle cache>/<seed prefix>/behaviour.tql, if it ships them. */
+export async function loadArchetypeBehaviour(bundleCacheDir, seeds) {
+    for (const seed of seeds) {
+        const file = join(bundleCacheDir, seed, BEHAVIOUR_FILE);
+        let text;
+        try {
+            text = await readFile(file, "utf8");
+        }
+        catch {
+            continue;
+        }
+        return parseArchetypeBehaviour(text, file);
+    }
+    return undefined;
+}
+/** `<bundle>@<version>` cache directory names carry the version the estate locked. */
+export function cachedVersion(bundleCacheDir) {
+    const name = bundleCacheDir.replace(/[\\/]+$/, "").split(/[\\/]/).pop() ?? "";
+    const at = name.lastIndexOf("@");
+    return at > 0 ? name.slice(at + 1) : undefined;
+}
+function renderChange(domain, archetypeId, bundle, version, reqs) {
+    const proposal = [
+        "## Why", "",
+        `The ${domain} domain was scaffolded from the reference architecture's ${archetypeId} archetype (${bundle} ${version}). ` +
+            "The archetype prescribes behaviour every conforming estate needs; this change adds it to the behaviour store once. " +
+            "From here the requirements are this estate's: the citations in " +
+            `docs/domains/${domain}/${CITATIONS_FILE} record which archetype requirement each one answers to.`, "",
+        "## What Changes", "",
+        `- Adds ${reqs.length} requirements to the ${domain} spec, one per archetype rule, each with its scenarios.`,
+        "- Before agreeing the change, narrow, extend or remove requirements to fit this estate: an optional requirement whose condition " +
+            "the estate does not declare is removed; one the estate meets differently is reworded. Record each such choice in the citations " +
+            "(narrowed, extended, or departed with its reason and the decision that took it).",
+        "",
+    ].join("\n");
+    const spec = ["## ADDED Requirements"];
+    for (const r of reqs) {
+        spec.push("", `### Requirement: ${r.title}`, "", r.statement, "", `Seeded from archetype requirement ${r.id} (${archetypeId}, ${r.tier}), rule "${r.ruleLabel}".`, "");
+        for (const s of r.scenarios) {
+            spec.push(`#### Scenario: ${s.title}`, "", ...s.steps.map((t) => `- **${t.keyword}** ${t.text}`), "");
+        }
+    }
+    const tasks = ["## 1. Fit", "", "- [ ] 1.1 Review each seeded requirement against this estate and record the relation in the citations", ""].join("\n");
+    return { proposal, spec: spec.join("\n").replace(/\n+$/, "") + "\n", tasks };
+}
+async function exists(p) {
+    try {
+        await access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function writeAt(path, content) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, content, "utf8");
+}
+/**
+ * Seed an estate's behaviour from an archetype, once: an OpenSpec change adding the archetype's requirements,
+ * and the domain's citations. Writes nothing when the estate has no behaviour store, when the archetype ships
+ * no rows, or when either the change or the citations already exist.
+ */
+export async function seedArchetypeBehaviour(input) {
+    const store = join(input.targetRepo, "openspec");
+    if (!(await exists(store)))
+        return { filesWritten: [], skipped: "no behaviour store (openspec/) in this repository" };
+    const reqs = await loadArchetypeBehaviour(input.bundleCacheDir, input.seeds);
+    if (!reqs || reqs.length === 0)
+        return { filesWritten: [], skipped: `archetype ${input.archetypeId} ships no behaviour rows` };
+    const version = cachedVersion(input.bundleCacheDir) ?? "unknown";
+    const change = `seed-${input.domain}-from-archetype`;
+    const changeDir = join(store, "changes", change);
+    const citations = join(input.targetRepo, "docs", "domains", input.domain, CITATIONS_FILE);
+    if (await exists(changeDir))
+        return { filesWritten: [], skipped: `openspec/changes/${change} already exists (seeded once)` };
+    if (await exists(citations))
+        return { filesWritten: [], skipped: `docs/domains/${input.domain}/${CITATIONS_FILE} already exists (seeded once)` };
+    const { proposal, spec, tasks } = renderChange(input.domain, input.archetypeId, input.bundleName, version, reqs);
+    const doc = {
+        archetype: input.archetypeId,
+        bundle: input.bundleName,
+        version,
+        citations: reqs.map((r) => ({ requirement: r.title, cites: r.id, digest: r.digest, relation: "derived" })),
+    };
+    const header = [
+        `# ${CITATIONS_FILE} — the ${input.domain} domain's requirements that answer to reference-architecture archetype requirements.`,
+        "# Seeded once from the archetype; the requirements are this estate's. Per citation: `requirement` is this estate's",
+        "# requirement title, `cites` the archetype requirement id, `digest` that requirement at `version`, and `relation` one of",
+        "# derived | extended | narrowed | departed (departed needs `reason` and `decision`). Checked by",
+        "# `sdd-cli validate --validator archetype-citations`: a changed source is reported until reviewed and re-pinned.",
+        "",
+    ].join("\n");
+    const files = [
+        [join(changeDir, "proposal.md"), proposal],
+        [join(changeDir, "tasks.md"), tasks],
+        [join(changeDir, "specs", input.domain, "spec.md"), spec],
+        [citations, header + stringifyYaml(doc, { lineWidth: 0 })],
+    ];
+    for (const [p, c] of files)
+        await writeAt(p, c);
+    return { filesWritten: files.map(([p]) => p.slice(input.targetRepo.length + 1)) };
+}
+//# sourceMappingURL=archetype-behaviour.js.map

package/dist/lib/scaffold/registry.js

@@ -0,0 +1,136 @@
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { BUNDLE_CACHE_REL, REGISTRY_FILE } from "../sync/bundle-cache.js";
+/**
+ * Scan the bundle cache for registries and return every archetype found.
+ * Bundles without any registry.yaml are skipped silently (vendor packs
+ * etc.). A registry may sit at the bundle's payload root or nested
+ * (multi-bundle producer repos keep one registry per bundle subtree,
+ * e.g. a vertical overlay's `verticals/fleet/registry.yaml`) — all are
+ * read; seed paths stay payload-root-relative regardless of where the
+ * declaring registry sits.
+ */
+export async function discoverArchetypes(targetRepo) {
+    const cacheRoot = join(targetRepo, BUNDLE_CACHE_REL);
+    let entries;
+    try {
+        entries = await readdir(cacheRoot, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const e of entries) {
+        if (!e.isDirectory())
+            continue;
+        const bundleCacheDir = join(cacheRoot, e.name);
+        const at = e.name.lastIndexOf("@");
+        const bundleName = at > 0 ? e.name.slice(0, at) : e.name;
+        for (const registryPath of await findRegistryFiles(bundleCacheDir)) {
+            let raw;
+            try {
+                raw = await readFile(registryPath, "utf8");
+            }
+            catch {
+                continue;
+            }
+            let parsed;
+            try {
+                parsed = parseYaml(raw);
+            }
+            catch {
+                continue; // malformed registry — skip rather than break scaffold
+            }
+            if (parsed === null || typeof parsed !== "object")
+                continue;
+            if (!Array.isArray(parsed.archetypes))
+                continue;
+            const tier = typeof parsed.tier === "string" ? parsed.tier : "unknown";
+            for (const a of parsed.archetypes) {
+                if (a === null || typeof a !== "object")
+                    continue;
+                const rec = a;
+                const id = typeof rec.id === "string" ? rec.id : undefined;
+                const seeds = Array.isArray(rec.seeds)
+                    ? rec.seeds.filter((s) => typeof s === "string")
+                    : [];
+                if (!id || seeds.length === 0)
+                    continue;
+                out.push({
+                    id,
+                    tier,
+                    seeds,
+                    bundleName,
+                    bundleCacheDir,
+                    ...(typeof rec.layer === "string" && { layer: rec.layer }),
+                    ...(typeof rec.domain_name === "string" && { domainName: rec.domain_name }),
+                    ...(typeof rec.status === "string" && { status: rec.status }),
+                    ...(typeof rec.notes === "string" && { notes: rec.notes }),
+                });
+            }
+        }
+    }
+    return out;
+}
+/** Depth cap for nested-registry discovery — bundle payloads are shallow. */
+const REGISTRY_SCAN_MAX_DEPTH = 4;
+/**
+ * Find every registry.yaml within a cached bundle (root + nested),
+ * depth-capped. Returns absolute paths in a stable (sorted) order.
+ */
+async function findRegistryFiles(dir, depth = 0) {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (e.isFile() && e.name === REGISTRY_FILE) {
+            found.push(join(dir, e.name));
+        }
+        else if (e.isDirectory() && depth < REGISTRY_SCAN_MAX_DEPTH) {
+            found.push(...(await findRegistryFiles(join(dir, e.name), depth + 1)));
+        }
+    }
+    return found;
+}
+/**
+ * Resolve an archetype reference against the cache. Accepts bare ids
+ * (`core/identity`) and bundle-qualified ids
+ * (`ref-arch-core-b2b-saas:core/identity`).
+ */
+export async function resolveArchetype(targetRepo, reference) {
+    const available = await discoverArchetypes(targetRepo);
+    let bundleFilter;
+    let id = reference;
+    const colon = reference.indexOf(":");
+    if (colon > 0) {
+        bundleFilter = reference.slice(0, colon);
+        id = reference.slice(colon + 1);
+    }
+    const matches = available.filter((a) => a.id === id && (bundleFilter === undefined || a.bundleName === bundleFilter));
+    if (matches.length === 1) {
+        return { ok: true, archetype: matches[0], available };
+    }
+    if (matches.length === 0) {
+        const known = available.map((a) => `${a.bundleName}:${a.id}`).join(", ");
+        return {
+            ok: false,
+            available,
+            error: available.length === 0
+                ? `No archetype registries found in ${BUNDLE_CACHE_REL}/ — sync an archetype-bearing bundle first (M-ADR 0176).`
+                : `Archetype '${reference}' not found in cached registries. Available: ${known}`,
+        };
+    }
+    const collisions = matches.map((a) => `${a.bundleName}:${a.id}`).join(", ");
+    return {
+        ok: false,
+        available,
+        error: `Archetype id '${id}' is declared by multiple bundles (${collisions}). Use the qualified form '<bundle>:<id>'.`,
+    };
+}
+//# sourceMappingURL=registry.js.map

package/dist/lib/sync/bundle-cache.js

@@ -0,0 +1,109 @@
+import { appendFile, copyFile, mkdir, readFile, readdir, rm } from "node:fs/promises";
+import { dirname, join } from "node:path";
+/**
+ * Consumer-side bundle cache (M-ADR 0176 §4.2).
+ *
+ * Every consumed non-forward-base bundle is extracted to
+ * `<targetRepo>/.sdd/bundle-cache/<bundleName>@<version>/` — the
+ * resolution substrate for `sdd-cli scaffold domain --archetype` and
+ * the staging source for materialise-mode paths. The cache directory
+ * is gitignored (ensured at sync time).
+ *
+ * Cache layout per bundle: the bundle's payload tree, verbatim (so
+ * registry.yaml and scaffold-source files sit at their shipped paths).
+ * Stale versions of the same bundle name are pruned on refresh.
+ */
+export const BUNDLE_CACHE_REL = ".sdd/bundle-cache";
+/**
+ * The registry file name (M-ADR 0176 §4.1) — always cache-only. A bundle may
+ * ship its registry at the payload root or nested (a multi-bundle producer
+ * repo keeps one registry per bundle subtree, e.g. a vertical overlay's
+ * `verticals/fleet/registry.yaml`, because the producer-layout rule forbids
+ * path mapping and the root name can only be claimed once).
+ */
+export const REGISTRY_FILE = "registry.yaml";
+/**
+ * The application-archetype vocabulary file name (M-ADR 0191 §4.2) — always
+ * cache-only, like the registry. Carries the seedless classification
+ * vocabulary a bundle contributes (resolution data, not adopter-editable
+ * content). May sit at the payload root (core layer) or nested (a vertical
+ * overlay's `verticals/<v>/application-archetypes.yaml`), same as the
+ * registry.
+ */
+export const VOCAB_FILE = "application-archetypes.yaml";
+/**
+ * Split a bundle's managed paths into the set to materialise into the
+ * repo tree vs the set that stays cache-only (M-ADR 0176 §4.3):
+ * scaffold-source-prefixed paths, registry files, and the archetype
+ * vocabulary file are cache-only.
+ */
+export function splitConsumptionModes(managedPaths, scaffoldSourcePaths) {
+    const prefixes = scaffoldSourcePaths ?? [];
+    const materialise = [];
+    const cacheOnly = [];
+    for (const p of managedPaths) {
+        const isScaffoldSource = prefixes.some((prefix) => p.startsWith(prefix));
+        const isRegistry = p === REGISTRY_FILE || p.endsWith(`/${REGISTRY_FILE}`);
+        const isVocab = p === VOCAB_FILE || p.endsWith(`/${VOCAB_FILE}`);
+        if (isScaffoldSource || isRegistry || isVocab) {
+            cacheOnly.push(p);
+        }
+        else {
+            materialise.push(p);
+        }
+    }
+    return { materialise, cacheOnly };
+}
+/**
+ * Extract a bundle's payload into the cache, replacing any previously
+ * cached version of the same bundle name (one cached version per
+ * bundle — the lock pins exactly one).
+ */
+export async function cacheBundle(input) {
+    const cacheRoot = join(input.targetRepo, BUNDLE_CACHE_REL);
+    await prunePreviousVersions(cacheRoot, input.bundleName);
+    const dest = join(cacheRoot, `${input.bundleName}@${input.bundleVersion}`);
+    for (const p of input.managedPaths) {
+        const src = join(input.payloadDir, p);
+        const dst = join(dest, p);
+        await mkdir(dirname(dst), { recursive: true });
+        await copyFile(src, dst);
+    }
+    return dest;
+}
+async function prunePreviousVersions(cacheRoot, bundleName) {
+    let entries;
+    try {
+        entries = await readdir(cacheRoot, { withFileTypes: true });
+    }
+    catch {
+        return; // no cache yet
+    }
+    for (const e of entries) {
+        if (e.isDirectory() && e.name.startsWith(`${bundleName}@`)) {
+            await rm(join(cacheRoot, e.name), { recursive: true, force: true });
+        }
+    }
+}
+/**
+ * Ensure the consumer's .gitignore excludes the bundle cache. Appends
+ * a marked line when absent; leaves adopter content untouched otherwise.
+ */
+export async function ensureCacheGitignored(targetRepo) {
+    const giPath = join(targetRepo, ".gitignore");
+    const line = `${BUNDLE_CACHE_REL}/`;
+    let existing = "";
+    try {
+        existing = await readFile(giPath, "utf8");
+    }
+    catch {
+        // no .gitignore yet — create one below
+    }
+    if (existing.split("\n").some((l) => l.trim() === line || l.trim() === BUNDLE_CACHE_REL)) {
+        return false;
+    }
+    const prefixNewline = existing.length > 0 && !existing.endsWith("\n") ? "\n" : "";
+    await appendFile(giPath, `${prefixNewline}# sdd-cli bundle cache (M-ADR 0176) — extracted bundle payloads, not source\n${line}\n`);
+    return true;
+}
+//# sourceMappingURL=bundle-cache.js.map

package/dist/lib/validate/archetype-citations.js

@@ -0,0 +1,134 @@
+// archetype-citations: an estate's citations of reference-architecture archetype behaviour still say what is true
+// (seed once, then cite; scaffold/archetype-behaviour.ts writes them).
+//
+// For each docs/domains/<domain>/archetype-citations.yaml, each citation is resolved against the archetype's
+// behaviour rows in the bundle the estate has cached (its locked version):
+//   unresolved  the citations name no cached bundle or archetype, the cited requirement is gone from the
+//               archetype, the relation is not one of the four, a departure has no reason or decision, or the
+//               estate requirement it names exists in neither the living specs nor an open change;
+//   stale       a derived, extended or narrowed citation whose archetype requirement no longer has the digest
+//               recorded: the archetype changed since the estate took or re-aligned it. Review it and re-pin
+//               (move `digest` and `version`), or record that the estate departs.
+// A departed citation is never stale: departing is a decision, recorded with its reason, not drift. With no
+// citations anywhere the check reports [N/A], an empty population, not a pass.
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { cachedVersion, CITATIONS_FILE, loadArchetypeBehaviour, RELATIONS } from "../scaffold/archetype-behaviour.js";
+import { discoverArchetypes } from "../scaffold/registry.js";
+const REQ_RE = /^###\s+Requirement:\s*(.+?)\s*$/gm;
+async function list(dir) {
+    try {
+        return (await readdir(dir, { withFileTypes: true })).filter((e) => e.isDirectory()).map((e) => e.name);
+    }
+    catch {
+        return [];
+    }
+}
+/** Every requirement title in the living specs and in open changes (a seeded change not yet archived counts). */
+async function estateRequirements(repo) {
+    const titles = new Set();
+    const specFiles = [];
+    for (const d of await list(join(repo, "openspec", "specs")))
+        specFiles.push(join(repo, "openspec", "specs", d, "spec.md"));
+    for (const c of await list(join(repo, "openspec", "changes"))) {
+        if (c === "archive")
+            continue;
+        for (const d of await list(join(repo, "openspec", "changes", c, "specs"))) {
+            specFiles.push(join(repo, "openspec", "changes", c, "specs", d, "spec.md"));
+        }
+    }
+    for (const f of specFiles) {
+        let text;
+        try {
+            text = await readFile(f, "utf8");
+        }
+        catch {
+            continue;
+        }
+        for (const m of text.matchAll(REQ_RE))
+            titles.add(m[1]);
+    }
+    return titles;
+}
+export async function checkArchetypeCitations(repo) {
+    const domains = await list(join(repo, "docs", "domains"));
+    const files = [];
+    for (const d of domains) {
+        const p = join(repo, "docs", "domains", d, CITATIONS_FILE);
+        try {
+            files.push([`docs/domains/${d}/${CITATIONS_FILE}`, await readFile(p, "utf8")]);
+        }
+        catch {
+            // no citations for this domain
+        }
+    }
+    if (files.length === 0)
+        return { exitCode: 0, stdout: "[N/A] no archetype citations (docs/domains/*/archetype-citations.yaml) in this repository\n" };
+    const archetypes = await discoverArchetypes(repo);
+    const titles = await estateRequirements(repo);
+    const lines = [];
+    let problems = 0;
+    let total = 0;
+    const bad = (tag, msg) => {
+        lines.push(`[${tag}] ${msg}`);
+        problems++;
+    };
+    for (const [rel, text] of files) {
+        let doc;
+        try {
+            doc = (parseYaml(text) ?? {});
+        }
+        catch (e) {
+            bad("unresolved", `${rel}: does not parse: ${e.message.split("\n")[0]}`);
+            continue;
+        }
+        const archetype = archetypes.find((a) => a.id === doc.archetype && a.bundleName === doc.bundle);
+        if (!archetype) {
+            bad("unresolved", `${rel}: archetype ${String(doc.archetype)} of bundle ${String(doc.bundle)} is not in the bundle cache (sync the bundle)`);
+            continue;
+        }
+        const reqs = await loadArchetypeBehaviour(archetype.bundleCacheDir, archetype.seeds);
+        const byId = new Map((reqs ?? []).map((r) => [r.id, r]));
+        const at = cachedVersion(archetype.bundleCacheDir) ?? "the cached bundle";
+        const cites = Array.isArray(doc.citations) ? doc.citations : [];
+        if (cites.length === 0)
+            bad("unresolved", `${rel}: lists no citations`);
+        for (const c of cites) {
+            total++;
+            const tag = `${rel}: '${String(c.requirement)}' -> ${String(c.cites)}`;
+            const relation = String(c.relation);
+            if (!RELATIONS.includes(relation)) {
+                bad("unresolved", `${tag}: relation must be one of ${RELATIONS.join(", ")} (got ${relation})`);
+                continue;
+            }
+            if (relation === "departed" && (!c.reason || !c.decision)) {
+                bad("unresolved", `${tag}: a departure needs its reason and the decision that took it`);
+                continue;
+            }
+            if (relation !== "departed" && !titles.has(String(c.requirement))) {
+                bad("unresolved", `${tag}: this estate has no requirement titled so (living specs or open changes)`);
+                continue;
+            }
+            const src = byId.get(String(c.cites));
+            if (!src) {
+                bad("unresolved", `${tag}: ${archetype.bundleName} ${at} has no archetype requirement ${String(c.cites)}`);
+                continue;
+            }
+            if (relation === "departed") {
+                lines.push(`[ok] ${tag} (departed: ${String(c.reason)})`);
+            }
+            else if (src.digest !== String(c.digest)) {
+                bad("stale", `${tag}: the archetype requirement changed (${String(c.digest)} at ${String(doc.version)} -> ${src.digest} at ${at}); review it and re-pin, or record a departure`);
+            }
+            else {
+                lines.push(`[ok] ${tag} (${relation})`);
+            }
+        }
+    }
+    const verdict = problems
+        ? `[FAIL] archetype citations: ${problems} of ${total} unresolved or stale`
+        : `[PASS] archetype citations: ${total} resolve, none stale`;
+    return { exitCode: problems ? 1 : 0, stdout: lines.join("\n") + "\n" + verdict + "\n" };
+}
+//# sourceMappingURL=archetype-citations.js.map

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

@@ -20,6 +20,11 @@
 //                 never against itself (M-ADR 0222 §4.3, §4.4). A list the catalogue gives nothing to
 //                 check against (no Observed in line, or a repository with no catalogue contracts) fails:
 //                 a cross-check of zero contracts is unresolved, not a pass.
+//   7. features: every living spec is keyed by a catalogue feature (M-ADR 0221 §4.7). A spec keyed by no
+//                 feature is dropped from the catalogue by the requirements builder, which reports it only as a
+//                 build finding; this check makes it a failure, so a shipped requirement cannot vanish from the
+//                 catalogue with every check green. Without catalogues/features.csv the check is unresolved, not
+//                 passed.
 //   6. scope:    a baseline ADDS requirements; it REMOVES, MODIFIES or RENAMES only a requirement whose
 //                 latest archived change was a baseline, which is how a corrective baseline withdraws
 //                 what a baseline admitted wrongly. A requirement a judged change shipped is changed only
@@ -354,6 +359,25 @@ export async function checkBehaviourStore(repo) {
     lines.push(scopeChecked === 0 ? "scope: vacuous (no baseline removes, modifies or renames a requirement)" : `scope: ${scopeChecked} requirement(s) a baseline removes, modifies or renames, checked against their lineage`);
     for (const [a, b] of ties)
         lines.push(`order: ${a} and ${b} were archived the same day and the history does not order them; ordered by name`);
+    // 7. living specs keyed by a catalogue feature
+    const livingSpecs = await dirs(join(repo, STORE_DIR, "specs"));
+    if (livingSpecs.length > 0) {
+        const featuresCsv = await readText(join(repo, "catalogues", "features.csv"));
+        if (featuresCsv === null) {
+            failures.push(`${STORE_DIR}/specs: living specs cannot be checked against catalogue features: catalogues/features.csv is missing; build the catalogue`);
+        }
+        else {
+            const featureIds = new Set(parseCatalogueCsv(featuresCsv).rows.map((r) => r["id"] ?? ""));
+            const unkeyed = livingSpecs.filter((f) => !featureIds.has(f));
+            for (const f of unkeyed) {
+                failures.push(`${STORE_DIR}/specs/${f}: no catalogue feature has the id "${f}", so its requirements are not catalogued; give the behaviour a feature first (M-ADR 0222 §4.4)`);
+            }
+            lines.push(`features: ${livingSpecs.length} living spec(s), ${livingSpecs.length - unkeyed.length} keyed by a catalogue feature`);
+        }
+    }
+    else {
+        lines.push("features: vacuous (no living spec)");
+    }
     const population = recordFiles.length + open.length + archived.length;
     const body = lines.map((l) => `  ${l}`).join("\n") + "\n";
     if (failures.length > 0) {
@@ -361,7 +385,7 @@ export async function checkBehaviourStore(repo) {
     }
     if (population === 0)
         return { exitCode: 0, stdout: body + `[N/A] the behaviour store has no changes and no agreement records yet\n` };
-    return { exitCode: 0, stdout: body + "[PASS] behaviour store: records, agreement, stale, verdict, surfaces and scope checks hold\n" };
+    return { exitCode: 0, stdout: body + "[PASS] behaviour store: records, agreement, stale, verdict, surfaces, scope and feature checks hold\n" };
 }
 /** Per repository, the contracts the catalogue says it serves (repo_contract ⋈ contracts.spec_path); null when either file is missing. */
 async function catalogueContracts(repo) {

package/dist/lib/validate/dispatch.js

@@ -1,3 +1,4 @@
+import { checkArchetypeCitations } from "./archetype-citations.js";
 import { checkBehaviourStore, checkBehaviourStoreOpenspec } from "./behaviour-store.js";
 import { checkBundleCoherence } from "./bundle-coherence.js";
 import { checkYamlParse } from "./yaml-parse.js";
@@ -14,6 +15,12 @@ const BEHAVIOUR_STORE_VALIDATORS = [
         source: { kind: "native", run: async (ctx) => checkBehaviourStoreOpenspec(ctx.targetRepo) },
         build: () => ({ status: "run", args: [] }),
     },
+    // Seed once, then cite: requirements an estate took from a reference-architecture archetype still answer to it.
+    {
+        name: "archetype-citations",
+        source: { kind: "native", run: async (ctx) => checkArchetypeCitations(ctx.targetRepo) },
+        build: () => ({ status: "run", args: [] }),
+    },
 ];
 // Validators that accept --app-root / --repo-root flags work fine from the
 // bundled location because they override their internal ROOT_DIR via the
@@ -92,7 +99,7 @@ const APP_VALIDATORS = [
     ...BEHAVIOUR_STORE_VALIDATORS,
     // Note: validate-runway-classification is intentionally NOT in the app set.
     // It requires platform-level files (docs/platform/feature-tree.md,
-    // architecture-runway-index.md) that app repos don't own. Per ADR 0089,
+    // architecture-runway-index.md) that app repos don't own. Per M-ADR 0089,
     // the reduced app suite is app-specific validators + shared foundations,
     // not platform validators.
 ];

package/dist/maintain-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.7.0",
-  "built_against_sdd_cli": "2.1.0"
+  "version": "0.9.0",
+  "built_against_sdd_cli": "2.3.0"
 }

package/dist/verbs/list.js

@@ -7,7 +7,7 @@ const VALID_PROFILES = [
 export function registerList(program) {
     program
         .command("list")
-        .description("Enumerate SDD repositories discoverable in the current workspace, including adopter pack provenance (ADR 0151)")
+        .description("Enumerate SDD repositories discoverable in the current workspace, including adopter pack provenance (M-ADR 0151)")
         .option("--profile <profile>", "filter by profile: platform | application | integration")
         .option("--workspace-root <path>", "workspace directory to walk (repeatable; defaults to cwd)", collectRoots, [])
         .option("--format <format>", "output format: text | json", "text")

package/dist/verify-program.js

@@ -109,11 +109,11 @@ export function registerVerifySurface(program) {
     registerList(program);
     const pack = program
         .command("pack")
-        .description("Validate adopter-shipped context-pack seeds (ADR 0151) — read-only");
+        .description("Validate adopter-shipped context-pack seeds (M-ADR 0151) — read-only");
     registerPackValidate(pack);
     const catalogue = program
         .command("catalogue")
-        .description("Validate and query per-SDD catalogues (ADR 0134) — read-only, never rebuilds");
+        .description("Validate and query per-SDD catalogues (M-ADR 0134) — read-only, never rebuilds");
     registerCatalogueValidate(catalogue);
     registerCatalogueImpact(catalogue);
     registerCatalogueBaselineCheck(catalogue);

package/dist/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "2.1.0",
-  "built_against_sdd_cli": "2.1.0"
+  "version": "2.3.0",
+  "built_against_sdd_cli": "2.3.0"
 }

package/package.json

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

package/scripts/validate-app-dependencies.sh

@@ -149,7 +149,7 @@ fi
 APP_DEPS_FILE="$APP_ROOT/app-platform-dependencies.yaml"
 
 # TWO AUTHORING SOURCES, NOT ONE.
-#   The catalogue builder does multi-source ingestion under the ADR 0157 parity
+#   The catalogue builder does multi-source ingestion under the M-ADR 0157 parity
 #   principle: `app-platform-dependencies.yaml` AND every
 #   `reverse-evidence/**/feature-grounding-evidence.yaml`'s platform_dependencies
 #   block, merged by primary key with forward winning. They are equal-status

package/scripts/validate-integration-docs.sh

@@ -160,7 +160,7 @@ check_manifest() {
             ;;
     esac
 
-    # Interaction patterns (ADR 0171) — optional fields, validated only when present.
+    # Interaction patterns (M-ADR 0171) — optional fields, validated only when present.
     # Existing manifests predate the field; absence is not a failure. Directionality
     # mismatch (pattern present but the matching capability flag is false) is a warning.
     local ingestion invocation