@sdd-method/author-cli 0.6.0 → 0.8.0

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

@@ -1,6 +1,6 @@
 // Repo-edge builders — repo_capability, repo_contract, feature_repo.
 //
-// Per ADR 0157 (Forward-Declared / Reverse-Derived Parity for Edge Catalogues):
+// Per M-ADR 0157 (Forward-Declared / Reverse-Derived Parity for Edge Catalogues):
 // both edges ingest from forward-method declared sources AND reverse-method
 // derived sources, merged by primary-key deduplication. The two paths are
 // equal-status per the parity principle; neither displaces the other.
@@ -32,20 +32,20 @@
 //     services.primary_repo_id`. A service exposing a contract is implemented
 //     by a repo (its primary_repo_id) — the repo "owns" the contract by
 //     transitive inference. Works universally because primary_repo_id and
-//     service_contract are core-schema populated. Added per ADR 0157 §4.2
+//     service_contract are core-schema populated. Added per M-ADR 0157 §4.2
 //     amendment after an early-adopter 0/30 source_repo_id outcome.
 //   repo_contract Path Y — `contracts.source_repo_id` denormalisation
-//     (from OpenAPI `x-source-repo` hints per ADR 0110, or whatever
+//     (from OpenAPI `x-source-repo` hints per M-ADR 0110, or whatever
 //     populates the column). Augments Path X when adopters carry the hint.
 //   repo_capability Path X (universal) — `capability_service ⋈
 //     services.primary_repo_id`. Works in both forward and reverse method
 //     shapes because primary_repo_id is core-schema and capability_service
 //     is heavily authored.
-//   repo_capability Path Y (augments via ADR 0143 feature-grounding) —
+//   repo_capability Path Y (augments via M-ADR 0143 feature-grounding) —
 //     `capability_feature ⋈ feature_repo`. Adopters who have adopted the
 //     feature-grounding extractor get many additional rows.
 //
-// feature_repo: ADR 0143's feature-grounding extractor populates this in
+// feature_repo: M-ADR 0143's feature-grounding extractor populates this in
 // build.ts (10a). The forward declared `contributes_to.artifact_type:
 // feature-set` path is documented in the metamodel but unused by any
 // observed adopter — left empty here pending first-adopter authoring.
@@ -68,7 +68,7 @@ import { normaliseAdditionalContextEntry, REPO_CONFIG_CONTRACT_KINDS, } from "./
  * identity-DEPENDENT, and so is this. A first review of D8 flagged the opposite
  * and was wrong.
  *
- * Caller supplies `existingIds` so this only ever ADDS: the ADR 0143
+ * Caller supplies `existingIds` so this only ever ADDS: the M-ADR 0143
  * feature-grounding extractor and the capability-spec walker own their rows and
  * are authoritative where they overlap.
  */
@@ -109,7 +109,7 @@ export function deriveFeatureRepoFromServices(inputs) {
 export function buildRepoEdges(inputs) {
     const repoCapability = collectRepoCapability(inputs);
     const repoContract = collectRepoContract(inputs);
-    // feature_repo is populated later in build.ts by the ADR 0143
+    // feature_repo is populated later in build.ts by the M-ADR 0143
     // feature-grounding extractor; this builder doesn't contribute.
     const featureRepo = [];
     return { repoCapability, repoContract, featureRepo };
@@ -222,9 +222,9 @@ function collectRepoCapability(inputs) {
             missingPrimaryRepoSvcs++;
     }
     if (missingPrimaryRepoSvcs > 0) {
-        inputs.findings.add("orphan", `repo_capability: ${missingPrimaryRepoSvcs} capability_service rows reference services with empty primary_repo_id — reverse-method Path X (capability_service ⋈ services.primary_repo_id) skipped those edges (per ADR 0157 §4.3)`);
+        inputs.findings.add("orphan", `repo_capability: ${missingPrimaryRepoSvcs} capability_service rows reference services with empty primary_repo_id — reverse-method Path X (capability_service ⋈ services.primary_repo_id) skipped those edges (per M-ADR 0157 §4.3)`);
     }
-    // Reverse path Y — capability_feature ⋈ feature_repo (transitive via ADR 0143).
+    // Reverse path Y — capability_feature ⋈ feature_repo (transitive via M-ADR 0143).
     const featuresToRepos = new Map();
     for (const fr of featureRepoRows) {
         const fid = String(fr["feature_id"] ?? "");
@@ -299,7 +299,7 @@ function collectRepoContract(inputs) {
     }
     // Reverse path X (universal) — service_contract ⋈ services.primary_repo_id.
     // A service exposing a contract is implemented by a repo; the repo "owns"
-    // the contract by transitive inference. Added per ADR 0157 §4.2 amendment
+    // the contract by transitive inference. Added per M-ADR 0157 §4.2 amendment
     // (an early adopter's source_repo_id was 0/30 populated, so
     // a derivation that depends only on it leaves them empty).
     const repoBySvcId = new Map();
@@ -323,10 +323,10 @@ function collectRepoContract(inputs) {
         emit(repoId, ctrId);
     }
     if (missingPrimaryRepoSvcs > 0) {
-        inputs.findings.add("orphan", `repo_contract: ${missingPrimaryRepoSvcs} service_contract rows reference services with empty primary_repo_id — reverse-method Path X (service_contract ⋈ services.primary_repo_id) skipped those edges (per ADR 0157 §4.2)`);
+        inputs.findings.add("orphan", `repo_contract: ${missingPrimaryRepoSvcs} service_contract rows reference services with empty primary_repo_id — reverse-method Path X (service_contract ⋈ services.primary_repo_id) skipped those edges (per M-ADR 0157 §4.2)`);
     }
     // Reverse path Y — contracts.source_repo_id denormalisation.
-    // Adopters who carry OpenAPI x-source-repo hints (per ADR 0110) or whose
+    // Adopters who carry OpenAPI x-source-repo hints (per M-ADR 0110) or whose
     // contracts builder otherwise populates source_repo_id get one row per
     // (source_repo_id, contract.id) for free.
     for (const c of contractRows) {

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

@@ -1,7 +1,7 @@
 // Repositories discoverer — emits `repositories.csv` rows from
 // `orchestration/repo-config/<domain>/<repo>.yaml` (recursive).
 //
-// Per ADR 0134 + Q7.1 resolution: `service_type` is constrained to the
+// Per M-ADR 0134 + Q7.1 resolution: `service_type` is constrained to the
 // canonical `enums.service_type` set (api_service, worker, gateway,
 // frontend, mobile, library, infrastructure, documentation). Unknown
 // values log a `[finding] convention` and are kept verbatim — the FK
@@ -33,16 +33,17 @@ const LOC_REPORT_REL = join("docs", "platform", "reference", "loc-report.csv");
 const REPOS_DIR_REL = "repos";
 const REVERSE_METADATA_BASENAME = "reverse-metadata.yaml";
 // The contract kinds a repo-config `contracts:` block keys, under `contracts/<kind>/`. The sdd-index reader
-// accepts the same four; `spicedb` (an `authz` contract) was once missing here, and zod strips an unknown key,
-// so a declared `.zed` schema vanished without a finding. GraphQL is not keyed in repo-config: that is its own
-// question, on this schema.
-export const REPO_CONFIG_CONTRACT_KINDS = ["openapi", "proto", "avro", "spicedb"];
+// accepts the same five; `spicedb` (an `authz` contract) was once missing here, and zod strips an unknown key,
+// so a declared `.zed` schema vanished without a finding. `cli` (schema 4.1.0) declares the command manifest a
+// command-line repository serves. GraphQL is not keyed in repo-config: that is its own question, on this schema.
+export const REPO_CONFIG_CONTRACT_KINDS = ["openapi", "proto", "avro", "spicedb", "cli"];
 const ContractsBlockSchema = z
     .object({
     openapi: z.array(z.string()).optional(),
     proto: z.array(z.string()).optional(),
     avro: z.array(z.string()).optional(),
     spicedb: z.array(z.string()).optional(),
+    cli: z.array(z.string()).optional(),
 })
     .optional();
 const EventEntrySchema = z.object({
@@ -172,13 +173,13 @@ export async function buildRepositories(inputs) {
             inputs.findings.add("convention", `${cfg.relPath}: missing required \`domain\` field`);
         }
         else if (!inputs.knownDomainIds.has(domain)) {
-            // Per ADR 0136: leave domain_id empty when the declared domain
+            // Per M-ADR 0136: leave domain_id empty when the declared domain
             // doesn't resolve locally (typical for app/integration SDDs whose
             // repo-config declares "applications"/"integrations").
             //
             // NOT `orphan`, and the argument is about TIER rather than a relabelling
             // of the same claim. A locally-unresolvable domain is two different
-            // things and THIS TIER CANNOT TELL THEM APART: ADR 0136 externality (the
+            // things and THIS TIER CANNOT TELL THEM APART: M-ADR 0136 externality (the
             // domain is owned by a sibling SDD — correct, expected, nothing to fix)
             // or a genuinely dangling domain name (a typo). The discriminator lives
             // at estate scope, not here. Measured across two estates: 137
@@ -190,7 +191,7 @@ export async function buildRepositories(inputs) {
             // §4.2 names. `inferred` records the builder's documented resolution
             // (empty the column, keep the repository) without claiming a defect this
             // build cannot see.
-            inputs.findings.add("inferred", `${cfg.relPath}: domain "${domain}" has no docs/domains/${domain}/ directory — domain_id left empty per ADR 0136. Whether that is external ownership or a dangling name is decidable only at estate scope`);
+            inputs.findings.add("inferred", `${cfg.relPath}: domain "${domain}" has no docs/domains/${domain}/ directory — domain_id left empty per M-ADR 0136. Whether that is external ownership or a dangling name is decidable only at estate scope`);
             resolvedDomain = "";
         }
         const loc = locByRepo.get(repoId);
@@ -251,19 +252,23 @@ async function loadRepoConfigs(sddPath, findings) {
             raw = parseYaml(text);
         }
         catch (err) {
-            findings.add("convention", `failed to parse YAML at ${relative(sddPath, path)}: ${err.message}`);
+            findings.add("convention", `failed to parse YAML at ${relative(sddPath, path)}: ${err.message} — repository dropped`, "error", relative(sddPath, path));
             continue;
         }
         if (!raw || typeof raw !== "object") {
-            findings.add("convention", `${relative(sddPath, path)}: not an object — skipped`);
+            findings.add("convention", `${relative(sddPath, path)}: not an object — repository dropped`, "error", relative(sddPath, path));
             continue;
         }
+        // A repo-config that cannot be read takes its repository, services and
+        // capability edges out of the catalogue with it. That is an error, not
+        // advice: as a warning it passed validation while the rows vanished, and
+        // only a downstream aggregate's FK check noticed.
         const parsed = RepoConfigSchema.safeParse(raw);
         if (!parsed.success) {
             const issues = parsed.error.issues
                 .map((i) => `${i.path.join(".") || "<root>"}: ${i.message}`)
                 .join("; ");
-            findings.add("convention", `${relative(sddPath, path)}: schema violation — ${issues}`);
+            findings.add("convention", `${relative(sddPath, path)}: schema violation — ${issues} — repository dropped`, "error", relative(sddPath, path));
             continue;
         }
         const repoFull = parsed.data.repo;

package/dist/lib/catalogue/builders/screen-tree.js

@@ -1,15 +1,15 @@
-// Screen composition-tree analysis for openui-lang blocks (per ADR 0168).
+// Screen composition-tree analysis for openui-lang blocks (per M-ADR 0168).
 //
 // The screens builder (screens.ts) lowers a ```openui-lang block into catalogue
-// rows by flat token-scanning. ADR 0168 adds a *fidelity floor*: the block must
+// rows by flat token-scanning. M-ADR 0168 adds a *fidelity floor*: the block must
 // be a faithful tree, not a flat / empty / mis-rooted "widget bag". That needs
 // the structural shape the flat scan throws away — so this module parses the
 // block into a tree and computes the metrics the depth findings reason about.
 //
 // Pure functions, no I/O. The metrics reason about TREE SHAPE only — never about
-// any component vocabulary (adopter-agnostic by construction, ADR 0168 §4.5).
+// any component vocabulary (adopter-agnostic by construction, M-ADR 0168 §4.5).
 //
-// Grammar recap (ADR 0166 / openui-lang-grammar-reference.md): one
+// Grammar recap (M-ADR 0166 / openui-lang-grammar-reference.md): one
 // `identifier = Expression` statement per line; the first statement is `root`;
 // composition is by identifier reference inside list literals. A component is a
 // Capitalised call head (`Name(`); local references are lowercase ids that are
@@ -73,7 +73,7 @@ function parseArgsActions(rhs) {
 }
 /**
  * Strip openui-lang inline comments: from the first *unquoted* `#` to
- * end-of-line, per line (ADR 0168 §4.4, defect g). A `Capitalised(` token inside
+ * end-of-line, per line (M-ADR 0168 §4.4, defect g). A `Capitalised(` token inside
  * a comment must not be lexed as a component. `#` inside a string literal is
  * preserved.
  */
@@ -113,7 +113,7 @@ function parseStatements(cleanBlock) {
         const rhs = m[2];
         // A component statement's RHS is a call (`Text("Q4")`) or a reference — never a
         // bare string literal. A line like `action="basket-updated"` (the block-level
-        // screen_action messaging contract, ADR 0166) matches the statement shape with
+        // screen_action messaging contract, M-ADR 0166) matches the statement shape with
         // id=`action`; skip it so it isn't lexed as a phantom component (and so a node
         // carrying an `action=` attr doesn't pick it up as a spurious child).
         if (/^["']/.test(rhs))

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

@@ -1,4 +1,4 @@
-// Screens builder — emits the UI screens catalogue family (per ADR 0166):
+// Screens builder — emits the UI screens catalogue family (per M-ADR 0166):
 //   screens, ui_components, screen_component, screen_feature,
 //   persona_screen, screen_action.
 //
@@ -7,7 +7,7 @@
 //   ---
 //   screen: <slug>            # optional; defaults to filename stem
 //   route: /path              # optional
-//   status: working           # optional (ADR 0165 maturity vocabulary)
+//   status: working           # optional (M-ADR 0165 maturity vocabulary)
 //   persona_access: [<persona-slug>, ...]   # -> persona_screen
 //   realises: [<feature-slug>, ...]         # -> screen_feature
 //   ---
@@ -25,7 +25,7 @@
 // toolkit projects an app's router + component tree into the same shape (the
 // upstream step that produces these artefacts).
 //
-// Per ADR 0135 the rows are identical regardless of authoring direction; only
+// Per M-ADR 0135 the rows are identical regardless of authoring direction; only
 // the `source` discriminator differs (screen-spec vs screen-extraction).
 //
 // Application-product profile. Like personas, the walker reads `screens/` at
@@ -36,9 +36,9 @@ import { basename, join } from "node:path";
 import { parse as parseYaml } from "yaml";
 import { analyzeComposition, maskStringLiterals, stripBlockComments } from "./screen-tree.js";
 import { isContainerArchetype } from "../archetype/resolver.js";
-/** Method default for the flat-composition threshold (ADR 0168 §4.2). */
+/** Method default for the flat-composition threshold (M-ADR 0168 §4.2). */
 const DEFAULT_FLAT_THRESHOLD = 6;
-/** The only maturity value that asserts a faithful, complete composition (ADR 0168 §4.3). */
+/** The only maturity value that asserts a faithful, complete composition (M-ADR 0168 §4.3). */
 const COMPLETENESS_STATUS = "working";
 const SCREENS_DIR_REL = "screens";
 /** Subdir of screens/ holding rendered wireframe artifacts — never screen specs. */
@@ -72,7 +72,7 @@ async function collectScreenSpecFiles(dir) {
     await walk("");
     return out.sort();
 }
-// Recognised standard maturity vocabulary (ADR 0165); other values pass through.
+// Recognised standard maturity vocabulary (M-ADR 0165); other values pass through.
 const STANDARD_MATURITY = new Set(["working", "provisional", "unknown", "absent"]);
 export async function buildScreens(inputs) {
     const screens = [];
@@ -105,7 +105,7 @@ export async function buildScreens(inputs) {
         }
         const name = extractH1(text) || (typeof fm.name === "string" ? fm.name : stem);
         const status = typeof fm.status === "string" && fm.status !== "" ? maturity(fm.status, inputs.findings, screenId) : "";
-        // Direction discriminator (ADR 0135): forward authoring is `screen-spec`,
+        // Direction discriminator (M-ADR 0135): forward authoring is `screen-spec`,
         // reverse extraction `screen-extraction`. Read from frontmatter, default
         // forward; only these two are recognised (others pass through, flagged).
         const source = screenSource(fm.source, inputs.findings, screenId);
@@ -130,7 +130,7 @@ export async function buildScreens(inputs) {
             evidence_class: evidenceClass(fm),
             source_sdd_id: "",
         });
-        // Evidence integrity (ADR 0168 §4.2, defect f): a reverse-extracted screen
+        // Evidence integrity (M-ADR 0168 §4.2, defect f): a reverse-extracted screen
         // must cite its route + component evidence with a `[^…]` footnote. Forward-
         // authored screens make no such claim, so the check is reverse-scoped.
         if (source === "screen-extraction" && !/\[\^[^\]]+\]/.test(text)) {
@@ -142,7 +142,7 @@ export async function buildScreens(inputs) {
         }
         else {
             // Strip inline `#` comments before any scan so a `Capitalised(` token in a
-            // comment can't emit a phantom component (ADR 0168 §4.4, defect g).
+            // comment can't emit a phantom component (M-ADR 0168 §4.4, defect g).
             const clean = stripBlockComments(block);
             // Component invocations: Capitalised call heads (e.g. Stack(, StatCard().
             // Local id references (lowercase, no parens) and list literals are skipped.
@@ -168,12 +168,12 @@ export async function buildScreens(inputs) {
                 const aKey = `${screenId}__${screenSlug(action)}`;
                 if (!screenAction.has(aKey)) {
                     // event_id left empty: external-capable, resolved against the event
-                    // catalogue when an explicit mapping exists (best-effort per ADR 0166).
+                    // catalogue when an explicit mapping exists (best-effort per M-ADR 0166).
                     screenAction.set(aKey, { id: aKey, screen_id: screenId, action, event_id: "", source_sdd_id: "" });
                 }
             }
-            // Composition-depth validation (ADR 0168): structural fidelity floor +
-            // status gate + the archetype-aware root check (ADR 0169). The vocabulary-
+            // Composition-depth validation (M-ADR 0168): structural fidelity floor +
+            // status gate + the archetype-aware root check (M-ADR 0169). The vocabulary-
             // free checks reason about tree shape + status only; root-is-leaf consults
             // the archetype map when the screen declares a `platform:`.
             const platform = typeof fm.platform === "string" ? fm.platform : undefined;
@@ -192,7 +192,7 @@ export async function buildScreens(inputs) {
             if (!fid) {
                 // App/integration screens can realise a platform-resident feature
                 // (MFE-over-platform: the platform owns the capability tree and its
-                // features — ADR 0177 single-slug). Emit a deferred cross-SDD edge
+                // features — M-ADR 0177 single-slug). Emit a deferred cross-SDD edge
                 // carrying the bare realises slug; the aggregator resolves it to the
                 // platform feature id, and the FK validator logs it `[finding] external`
                 // for this build (screen_feature.feature_id is external_for_profiles).
@@ -261,24 +261,24 @@ function emitDepthFindings(findings, screenId, status, m, ctx) {
         findings.add("coverage", `screen ${screenId}: composition is flat — root has ${m.rootChildCount} children at depth ${m.maxDepth} (screen-flat-composition)`);
     }
     // Status gate (keystone): `working` is the only maturity that asserts a
-    // faithful, complete composition (ADR 0168 §4.3). provisional/unknown/absent
+    // faithful, complete composition (M-ADR 0168 §4.3). provisional/unknown/absent
     // make no completeness claim and are not gated.
     if (status === COMPLETENESS_STATUS && (empty || flat)) {
         findings.add("convention", `screen ${screenId}: status "${COMPLETENESS_STATUS}" exceeds composition depth — block is ${empty ? "empty" : "flat"} (screen-status-exceeds-depth)`, "error");
     }
-    // Mis-rooted (ADR 0168 §4.2 screen-root-is-leaf, archetype-aware per ADR 0169):
+    // Mis-rooted (M-ADR 0168 §4.2 screen-root-is-leaf, archetype-aware per M-ADR 0169):
     // root is a leaf/control rather than a screen container. isContainer combines
     // the appears-with-children heuristic (containers) with the archetype map.
     // Only fires when the screen declares a known `platform:` — without a map the
     // heuristic alone can't distinguish an empty container root (Stack([])) from a
-    // genuine leaf root (Button([])), so the check no-ops (ADR 0168 §4.5).
+    // genuine leaf root (Button([])), so the check no-ops (M-ADR 0168 §4.5).
     if (m.rootComponent !== "" && m.rootChildCount === 0) {
         const byMap = isContainerArchetype(m.rootComponent, platform, overlay);
         if (byMap === false && !m.containers.has(m.rootComponent)) {
             findings.add("convention", `screen ${screenId}: root component "${m.rootComponent}" is a leaf, not a container (screen-root-is-leaf)`, "error");
         }
     }
-    // Styling-primitive leakage (ADR 0168 §4.2 screen-styling-primitive-as-structure):
+    // Styling-primitive leakage (M-ADR 0168 §4.2 screen-styling-primitive-as-structure):
     // an adopter-flagged decorative primitive composed as a structural component.
     // No-ops when the adopter declares no decorative set.
     if (decorativePrimitives !== undefined && decorativePrimitives.size > 0) {
@@ -317,7 +317,7 @@ function screenSlug(s) {
 function normalise(s) {
     return s.trim().toLowerCase().replace(/\s+/g, " ");
 }
-// Recognised direction discriminators (ADR 0135). Others pass through flagged.
+// Recognised direction discriminators (M-ADR 0135). Others pass through flagged.
 const SCREEN_SOURCES = new Set(["screen-spec", "screen-extraction"]);
 function screenSource(value, findings, screenId) {
     if (typeof value !== "string" || value.trim() === "")

package/dist/lib/catalogue/builders/service-contract-consumes.js

@@ -22,7 +22,7 @@
 //      the platform-root SDD validates internally first per the fk-validator
 //      optimistic-resolve rule.
 //
-// Pattern documented in sdd-method ADR 0147.
+// Pattern documented in sdd-method M-ADR 0147.
 import { readFile, readdir } from "node:fs/promises";
 import { join } from "node:path";
 const REPOS_DIR_REL = "repos";

package/dist/lib/catalogue/builders/service-entity-tables.js

@@ -1,8 +1,8 @@
 // Primary reverse-method walker for the service_entity edge catalogue per
-// ADR 0159 §4.5. Reads per-domain `## Data Store Mapping` markdown tables in
+// M-ADR 0159 §4.5. Reads per-domain `## Data Store Mapping` markdown tables in
 // `docs/domains/{domain}/architecture/data-model.mermaid.md` files.
 //
-// Prototype findings (per ADR 0159 — data-store-mapping table variations):
+// Prototype findings (per M-ADR 0159 — data-store-mapping table variations):
 // - Two heading variants: `## Data Store Mapping` and `## Data Store Inventory`
 //   (the latter is store-centric — different schema, no Entity column — and
 //   gets skipped with a convention finding).
@@ -14,7 +14,7 @@
 // - Cross-domain entity references in tables resolve against entities.csv
 //   from any domain (not just the table's own domain) — same-domain first.
 //
-// Service-name resolution rules (ADR 0159 §4.7):
+// Service-name resolution rules (M-ADR 0159 §4.7):
 // 1. Try alias-map exact match (case-insensitive on display name).
 // 2. Try entitySlug(display_name) ⋈ entitySlug(services.name).
 // 3. Try entitySlug(display_name) ⋈ last_segment(services.id).

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

@@ -10,7 +10,7 @@
 // 0197 §4.1 — a dangling reference to it resolves to an orphan finding
 // elsewhere, not a crash here).
 //
-// Per ADR 0134 + Q7.1 resolution, runtime kinds are
+// Per M-ADR 0134 + Q7.1 resolution, runtime kinds are
 // {api_service, worker, gateway, frontend, mobile} — read from the
 // canonical schema's enums.service_type block where
 // `emits_service_row: true`. The runtime-kind gate applies only to the
@@ -29,13 +29,13 @@
 // service-architecture-parser module.
 //
 // The `description` column has two authoring sources, honoured per the
-// forward/reverse parity principle (ADR 0157, extended to node columns by
-// ADR 0163):
+// forward/reverse parity principle (M-ADR 0157, extended to node columns by
+// M-ADR 0163):
 //   - forward: `orchestration/repo-config/<repo>.yaml` `description:` —
 //     the deliberate spec, authored by forward-method adopters.
 //   - reverse: the arch doc's `## Purpose` lead paragraph.
 // When both are present for the same service the forward repo-config
-// description wins (matching the ADR 0156 / 0162 merge convention) and a
+// description wins (matching the M-ADR 0156 / 0162 merge convention) and a
 // `divergence` finding records the conflict. In practice an adopter has
 // only one of the two, so this is usually a plain coalesce.
 //
@@ -111,7 +111,7 @@ export async function buildServices(inputs) {
     // repos/<group>/<repo>/docs/..., so a recursive walk is required.
     // Services whose architecture doc lives in a federated member SDD (rather
     // than this SDD's own repos/) resolve to no entry here — their metadata is
-    // an aggregation-time concern (ADR 0163 P2), not a local build gap.
+    // an aggregation-time concern (M-ADR 0163 P2), not a local build gap.
     const archIndex = await indexServiceArchitectures(inputs.sddPath);
     const repoDescriptions = inputs.repoDescriptions ?? new Map();
     const declaredByRepo = inputs.declaredServicesByRepo ?? new Map();

package/dist/lib/catalogue/builders/system-external-dependency.js

@@ -1,12 +1,12 @@
 // system_external_dependency edge builder — emits one row per
 // `Rel(...)` line on an L1/L2 diagram that connects the SDD's own system
-// (or one of its containers) to an external system (per ADR 0155).
+// (or one of its containers) to an external system (per M-ADR 0155).
 //
 // Resolution: the c4-external-systems builder supplies `externalIdByEntryId`
 // (diagram entry-id → ext-... row id). For each `Rel(a, b, "label")` where
 // exactly one endpoint is a known external entry-id, we emit an edge from
 // the SDD's c4_systems row to that external system. Container-level external
-// dependencies are intentionally collapsed to the system level — ADR 0155
+// dependencies are intentionally collapsed to the system level — M-ADR 0155
 // §4.2 keeps the edge system-scoped.
 import { readFile } from "node:fs/promises";
 import { collectC4DiagramFiles } from "./c4-external-systems.js";

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/contract-id.js

@@ -2,7 +2,7 @@
 // M-ADR 0203 §4.4, the cut's acid test.
 //
 // From 3.0.0 a contract id carries its KIND component: `{domain}-{stem}-{kind}`
-// (kind ∈ rest | graphql | rpc | event | authz). The kindless 2.x form made one
+// (kind ∈ rest | graphql | rpc | event | authz | cli). The kindless 2.x form made one
 // measured collision class unrepresentable: a service published as two contract
 // families (`calendar-service.yaml` + `calendar_service.proto`) minted one id,
 // costing a live estate one row and two edges permanently, and mislabelling

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/feature-grounding-aliases-loader.js

@@ -1,6 +1,6 @@
 /**
  * Loader for the optional `.sdd/feature-grounding-aliases.yaml` config
- * per ADR 0143 (schema 2.5.0).
+ * per M-ADR 0143 (schema 2.5.0).
  *
  * Adopters use this map to translate display names in
  * `feature-grounding.md` tables (class names, file basenames, route

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.
  *