@mmerterden/multi-agent-pipeline 13.5.0 → 14.0.0

package/pipeline/scripts/skill-conformance.mjs

@@ -0,0 +1,960 @@
+#!/usr/bin/env node
+// skill-conformance.mjs  -  resolve WHAT the changed code was supposed to honour,
+// before any reviewer looks at it. Zero LLM calls.
+//
+// Phase 4 used to pick its review criteria from `detectedStack`, a string Phase 1
+// computed before a line of code existed, and the dev phase never recorded which
+// skills it actually applied. So "was this done correctly" could only ever be
+// answered as "it looks fine to me". This script produces the missing denominator:
+// a bounded, enumerable set of rule IDs plus the criteria sources they came from,
+// written to disk BEFORE the reviewers run so it cannot be renegotiated after.
+//
+// Usage:
+//   skill-conformance.mjs --diff <patch-file> [--changed-files a.swift,b.kt]
+//                         [--state <agent-state.json>]   # reads telemetry.skillCalls[]
+//                         [--repo <root>]                # default: cwd
+//                         [--out <criteria-manifest.json>]
+//                         [--skills-root <dir>]          # override discovery root
+//                         [--json]                       # manifest to stdout
+//
+// Contract (full spec: multi-agent-refs/features/skill-conformance.md):
+//   1. Registry discovery is DECLARED, never sniffed by name: a skill opts in with
+//      `standards-registry: <relative path>` in its SKILL.md frontmatter. The
+//      pipeline therefore names no stack-specific skill, and a new language's
+//      registry drops in with zero pipeline change.
+//   2. Every registry declares its own `scope` (languages / paths). Rules outside
+//      the changed files' languages are DROPPED and counted. Without this an
+//      Objective-C or UIKit diff would collect the whole Swift/SwiftUI rule set,
+//      which manufactures findings and buries the real ones.
+//   3. The resolver is PRIMARY; `telemetry.skillCalls[]` only corroborates. An
+//      unrecorded consultation and no consultation are byte-identical in state, so
+//      a coverage number computed from self-report reads green over an empty set.
+//   4. Absent, empty and zero are three different states in the output.
+//
+// Exit codes:
+//   0  manifest written (may still carry findings or declared coverage gaps)
+//   1  setup error: no diff, unreadable state, or an explicit --skills-root that
+//      does not exist. A typo there used to resolve to zero roots and produce a
+//      clean review over criteria that were never loaded.
+//   2  fail-closed: no skills root resolved at all, a declared registry could not
+//      be parsed, or a declared path escaped its skill directory. All named in the
+//      manifest (`resolutionFailure`, `unparseableRegistries`).
+
+import { existsSync, readFileSync, writeFileSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, resolve, relative, basename, extname, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+// ---------------------------------------------------------------------------
+// Skills-root resolution
+//
+// This script runs from four different trees: `<repo>/pipeline/scripts` in a
+// checkout, and `~/.claude/scripts`, `~/.copilot/scripts`, `~/.codex/scripts`
+// once installed. install/copilot.mjs copies `scripts/` byte-for-byte with no
+// path rewrite, and Codex puts skills under `multi-agent-refs/skills`, so a
+// hardcoded `~/.claude/skills` is inert on two of the three hosts. That exact
+// bug already shipped once here (see match-skills.mjs header): dynamic skill
+// loading exited 1 on every real install while passing a smoke that ran from
+// the repo. Installed layouts are tried first  -  that is where a run happens.
+// ---------------------------------------------------------------------------
+function skillsRootCandidates() {
+  const installRoot = resolve(here, ".."); // ~/.claude | ~/.copilot | ~/.codex
+  const repoRoot = resolve(here, "..", ".."); // <repo>
+  return [
+    join(installRoot, "skills"), // ~/.claude/skills, ~/.copilot/skills
+    join(installRoot, "multi-agent-refs", "skills"), // ~/.codex/multi-agent-refs/skills
+    join(repoRoot, "pipeline", "skills"), // checkout
+  ];
+}
+
+/**
+ * Resolve the roots to search, and report every candidate that was PROBED  -  not
+ * only the ones that existed.
+ *
+ * Returning just the survivors made `skillsRootsSearched` empty exactly when it
+ * mattered most: a run that found no roots produced `[]`, so "no registries" and
+ * "wrong root" were indistinguishable  -  the failure this field exists to
+ * attribute. The schema and the feature doc both promise attribution, so the
+ * candidates carry an `existed` flag instead.
+ *
+ * @returns {{roots: string[], probed: Array<{path: string, existed: boolean}>}}
+ */
+function resolveSkillsRoots(override) {
+  const candidates = override ? [override] : skillsRootCandidates();
+  const probed = candidates.map((p) => ({ path: p, existed: existsSync(p) }));
+  return { roots: probed.filter((p) => p.existed).map((p) => p.path), probed };
+}
+
+// ---------------------------------------------------------------------------
+// Zero-dependency YAML subset reader.
+//
+// The runtime ships no YAML parser by policy. Semantic parsing is not needed and
+// not attempted: the reviewers are handed the registry FILE PATH and read the
+// YAML natively. This extracts only the flat scalars the gate must reason about,
+// anchored so nested maps cannot contribute.
+//
+// Anchoring is load-bearing. A naive `grep -c '  - id:'` over the 99-rule iOS
+// registry returns 112: the extra 13 are `module_overlay_slots.slots[].id` and
+// friends at a deeper indent. Counting those as rules would inflate the
+// denominator with entries that are not rules, and every conformance percentage
+// computed from it would be quietly wrong.
+// ---------------------------------------------------------------------------
+function readRegistry(path) {
+  const text = readFileSync(path, "utf8");
+  const lines = text.split("\n");
+
+  const meta = { version: null, exceptionMarker: null, scope: null, notCovered: {} };
+  const rules = [];
+
+  let inRules = false;
+  let inTopScope = false;
+  let inScopeList = null; // "languages" | "paths" | "excludePaths" | "notCovered"
+  let cur = null;
+
+  const pushCur = () => {
+    if (cur) rules.push(cur);
+    cur = null;
+  };
+
+  for (const raw of lines) {
+    const line = raw.replace(/\s+$/, "");
+    if (!line || /^\s*#/.test(line)) continue;
+
+    // Top-level keys end any nested context.
+    const top = /^([a-z_]+):(.*)$/.exec(line);
+    if (top) {
+      const [, key, rest] = top;
+      if (key !== "rules") pushCur();
+      inRules = key === "rules";
+      inTopScope = key === "scope";
+      inScopeList = null;
+
+      if (key === "version") meta.version = rest.trim() || null;
+      if (key === "exception_marker") {
+        meta.exceptionMarker = rest.trim().replace(/^["']|["']$/g, "") || null;
+      }
+      if (key === "severity_levels") meta.severityLevels = parseInlineList(rest);
+      if (inTopScope) meta.scope = { languages: [], paths: [], excludePaths: [] };
+      continue;
+    }
+
+    if (inTopScope && meta.scope) {
+      const kv = /^ {2}([a-zA-Z_-]+):(.*)$/.exec(line);
+      if (kv) {
+        const [, key, rest] = kv;
+        inScopeList = null;
+        if (key === "languages") {
+          const inline = parseInlineList(rest);
+          if (inline.length) meta.scope.languages = inline;
+          else inScopeList = "languages";
+        } else if (key === "paths" || key === "excludePaths") {
+          const inline = parseInlineList(rest);
+          if (inline.length) meta.scope[key] = inline;
+          else inScopeList = key;
+        } else if (key === "notCovered") {
+          inScopeList = "notCovered";
+        }
+        continue;
+      }
+      if (inScopeList === "notCovered") {
+        const nc = /^ {4}([a-zA-Z0-9_-]+):\s*(.*)$/.exec(line);
+        if (nc) meta.notCovered[nc[1]] = nc[2].trim();
+        continue;
+      }
+      if (inScopeList) {
+        const item = /^ {4}- (.*)$/.exec(line);
+        if (item) meta.scope[inScopeList].push(unquote(item[1].trim()));
+        continue;
+      }
+      continue;
+    }
+
+    if (!inRules) continue;
+
+    // A rule starts at exactly two spaces. Deeper `- id:` lines belong to a
+    // nested structure and are deliberately ignored.
+    const idLine = /^ {2}- id:\s*(.+)$/.exec(line);
+    if (idLine) {
+      pushCur();
+      cur = { id: idLine[1].trim(), scope: null, statusDeclared: false };
+      continue;
+    }
+    if (!cur) continue;
+
+    const field = /^ {4}([a-zA-Z_]+):\s*(.*)$/.exec(line);
+    if (!field) continue;
+    const [, key, value] = field;
+    const v = value.trim();
+
+    if (key === "severity") cur.severity = v;
+    else if (key === "enforcement") cur.enforcement = v;
+    else if (key === "status") {
+      cur.status = v;
+      cur.statusDeclared = true;
+    } else if (key === "mechanism") cur.mechanism = v || "(block scalar)";
+    else if (key === "rationale") cur.rationale = v;
+    else if (key === "scope") cur.scope = parseInlineScope(v);
+    else if (key === "scope_reason") cur.scopeReason = v;
+    else if (key === "title") cur.title = v === ">" ? null : v;
+  }
+  pushCur();
+
+  return { meta, rules };
+}
+
+function unquote(s) {
+  return s.replace(/^["']|["']$/g, "");
+}
+
+function parseInlineList(rest) {
+  const m = /^\s*\[(.*)\]\s*$/.exec(rest);
+  if (!m) return [];
+  return m[1]
+    .split(",")
+    .map((s) => unquote(s.trim()))
+    .filter(Boolean);
+}
+
+// `scope: { frameworks: [swiftui], paths: ["**/*View.swift"] }`
+function parseInlineScope(v) {
+  if (!v.startsWith("{")) return null;
+  const out = {};
+  for (const key of ["languages", "frameworks", "paths", "excludePaths"]) {
+    const m = new RegExp(`${key}:\\s*\\[([^\\]]*)\\]`).exec(v);
+    if (m) {
+      out[key] = m[1]
+        .split(",")
+        .map((s) => unquote(s.trim()))
+        .filter(Boolean);
+    }
+  }
+  return Object.keys(out).length ? out : null;
+}
+
+// ---------------------------------------------------------------------------
+// Frontmatter reader: only the keys discovery needs.
+// ---------------------------------------------------------------------------
+function readFrontmatter(path) {
+  const text = readFileSync(path, "utf8");
+  if (!text.startsWith("---")) return {};
+  const end = text.indexOf("\n---", 3);
+  if (end < 0) return {};
+  const out = {};
+  for (const line of text.slice(3, end).split("\n")) {
+    const m = /^([a-zA-Z0-9_-]+):\s*(.*)$/.exec(line);
+    if (m) out[m[1]] = unquote(m[2].trim());
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Language classification from file extension.
+//
+// This replaces `detectedStack` for the dev modes, where Phase 1 never ran. It
+// is deliberately extension-based: it describes what the diff CONTAINS, which is
+// what the criteria have to match, rather than what the repo is nominally built
+// in. A Swift repo with one Objective-C bridging file must not get Swift rules
+// applied to that file.
+// ---------------------------------------------------------------------------
+const LANG_BY_EXT = {
+  ".swift": "swift",
+  ".m": "objective-c",
+  ".mm": "objective-c",
+  ".h": "objective-c-header",
+  ".kt": "kotlin",
+  ".kts": "kotlin",
+  ".java": "java",
+  ".py": "python",
+  ".js": "javascript",
+  ".mjs": "javascript",
+  ".cjs": "javascript",
+  ".ts": "typescript",
+  ".tsx": "typescript",
+  ".jsx": "javascript",
+  ".go": "go",
+  ".rb": "ruby",
+  ".rs": "rust",
+  ".c": "c",
+  ".cc": "cpp",
+  ".cpp": "cpp",
+  ".hpp": "cpp",
+  ".xml": "xml",
+  ".plist": "plist",
+  ".gradle": "gradle",
+  ".yml": "yaml",
+  ".yaml": "yaml",
+  ".json": "json",
+  ".sh": "shell",
+  ".bash": "shell",
+};
+
+function classifyLanguage(file) {
+  const base = basename(file);
+  if (base === "Info.plist" || base.endsWith(".plist")) return "plist";
+  if (base === "project.pbxproj") return "pbxproj";
+  if (base.endsWith(".entitlements")) return "plist";
+  if (base === "AndroidManifest.xml") return "xml";
+  if (base.endsWith(".gradle.kts")) return "gradle";
+  return LANG_BY_EXT[extname(base).toLowerCase()] ?? "other";
+}
+
+// ---------------------------------------------------------------------------
+// Minimal glob matcher for the `**/x`, `*.ext`, `dir/**` shapes registries use.
+// ---------------------------------------------------------------------------
+function globToRegExp(glob) {
+  let re = "";
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i];
+    if (c === "*") {
+      if (glob[i + 1] === "*") {
+        // `**/` matches zero or more path segments.
+        if (glob[i + 2] === "/") {
+          re += "(?:.*/)?";
+          i += 2;
+        } else {
+          re += ".*";
+          i += 1;
+        }
+      } else {
+        re += "[^/]*";
+      }
+    } else if (c === "?") re += "[^/]";
+    else re += c.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  }
+  return new RegExp(`^${re}$`);
+}
+
+function matchesAnyGlob(file, globs) {
+  if (!globs || globs.length === 0) return true;
+  return globs.some((g) => globToRegExp(g).test(file));
+}
+
+// ---------------------------------------------------------------------------
+// Diff parsing: changed files and added lines (for the exception audit).
+// ---------------------------------------------------------------------------
+/**
+ * Decode git's quoted-path form: backslash escapes plus \NNN octal bytes, which
+ * git emits per-byte for non-ASCII (a Turkish "ü" arrives as two octal escapes).
+ * Decoding octal per byte and then interpreting the result as UTF-8 is what makes
+ * a non-ASCII filename come back intact rather than mojibake.
+ */
+function unquoteGitPath(p) {
+  if (!p.includes("\\")) return p;
+  const bytes = [];
+  for (let i = 0; i < p.length; i++) {
+    if (p[i] !== "\\") {
+      bytes.push(...Buffer.from(p[i], "utf8"));
+      continue;
+    }
+    const next = p[i + 1];
+    if (next >= "0" && next <= "7") {
+      bytes.push(parseInt(p.slice(i + 1, i + 4), 8));
+      i += 3;
+    } else {
+      const simple = { n: 10, t: 9, r: 13, '"': 34, "\\": 92 };
+      bytes.push(simple[next] ?? next.charCodeAt(0));
+      i += 1;
+    }
+  }
+  return Buffer.from(bytes).toString("utf8");
+}
+
+function parseDiff(patch) {
+  const files = [];
+  const addedByFile = new Map();
+  let current = null;
+  let newLineNo = 0;
+
+  for (const line of patch.split("\n")) {
+    // git QUOTES a path containing spaces or non-ASCII: `+++ "b/Sources/Ekran
+    // Gorunumu.swift"`. Matching only the bare form dropped such a file from
+    // changedFiles entirely, so it appeared neither in selectedRules nor in
+    // coverage.uncoveredFiles  -  an unrecorded hole in the very denominator this
+    // gate exists to make complete. Turkish, and any non-ASCII, filename hits this.
+    const bPath = /^\+\+\+ (?:"b\/(.+)"|b\/(.+))$/.exec(line);
+    if (bPath) {
+      current = unquoteGitPath(bPath[1] ?? bPath[2]);
+      if (current !== "/dev/null" && !files.includes(current)) files.push(current);
+      addedByFile.set(current, addedByFile.get(current) ?? []);
+      continue;
+    }
+    const hunk = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/.exec(line);
+    if (hunk) {
+      newLineNo = parseInt(hunk[1], 10);
+      continue;
+    }
+    if (!current) continue;
+    if (line.startsWith("+") && !line.startsWith("+++")) {
+      addedByFile.get(current).push({ line: newLineNo, text: line.slice(1) });
+      newLineNo++;
+    } else if (line.startsWith("-") && !line.startsWith("---")) {
+      // deletion: new-side line number does not advance
+    } else if (line.startsWith(" ")) {
+      newLineNo++;
+    }
+  }
+  return { files, addedByFile };
+}
+
+// ---------------------------------------------------------------------------
+// Module guide walk. Same deterministic contract as /multi-agent:review Step 2b:
+// walk each changed file's directory chain to the repo root, collecting guides
+// the host CLI does not auto-load. Root-level files are excluded because the CLI
+// already loads those. Capped, with the drop logged rather than silent.
+// ---------------------------------------------------------------------------
+const GUIDE_CAP = 5;
+
+function collectModuleGuides(repoRoot, changedFiles) {
+  const found = new Set();
+  for (const f of changedFiles) {
+    let dir = dirname(resolve(repoRoot, f));
+    while (dir.startsWith(repoRoot) && dir !== repoRoot) {
+      for (const name of readdirSafe(dir)) {
+        if (name === "CLAUDE.md" || name === "AGENTS.md" || name.endsWith("-CLAUDE.md")) {
+          found.add(relative(repoRoot, join(dir, name)));
+        }
+      }
+      dir = dirname(dir);
+    }
+  }
+  const all = [...found].sort();
+  return { guides: all.slice(0, GUIDE_CAP), dropped: all.slice(GUIDE_CAP) };
+}
+
+function readdirSafe(dir) {
+  try {
+    return readdirSync(dir);
+  } catch {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Toolchain wiring check.
+//
+// A registry rule marked `enforcement: lint` names the tool that owns it. This
+// does NOT re-implement that tool: it checks whether the repo has it wired, and
+// reports absence as a finding. That is the honest answer and it is
+// stack-generic  -  swiftlint, ktlint, detekt, eslint and ruff all take rule ids.
+// Executing a registry's `mechanism` regex directly was considered and rejected:
+// across the 99-rule iOS registry only 43 rules carry `mechanism` at all, the
+// field is prose with an embedded pattern rather than a machine field, and each
+// carries its scope in English. Running them unscoped floods a review.
+// ---------------------------------------------------------------------------
+const TOOLCHAIN_CONFIGS = {
+  swiftlint: [".swiftlint.yml", ".swiftlint.yaml"],
+  ktlint: [".editorconfig", "ktlint.gradle"],
+  detekt: ["detekt.yml", "config/detekt/detekt.yml"],
+  eslint: [".eslintrc", ".eslintrc.json", ".eslintrc.cjs", "eslint.config.js", "eslint.config.mjs"],
+  ruff: ["ruff.toml", ".ruff.toml", "pyproject.toml"],
+  swiftformat: [".swiftformat"],
+};
+
+function detectToolchains(repoRoot, rules) {
+  const named = new Set();
+  for (const r of rules) {
+    const mech = (r.mechanism ?? "").toLowerCase();
+    for (const tool of Object.keys(TOOLCHAIN_CONFIGS)) {
+      if (mech.includes(tool)) named.add(tool);
+    }
+  }
+  return [...named].sort().map((tool) => ({
+    tool,
+    wired: TOOLCHAIN_CONFIGS[tool].some((c) => existsSync(join(repoRoot, c))),
+    configCandidates: TOOLCHAIN_CONFIGS[tool],
+  }));
+}
+
+// ---------------------------------------------------------------------------
+// Exception-marker audit  -  the one bespoke deterministic scan kept.
+//
+// Cheap, language-agnostic, and it answers "completely" directly: an exception
+// is the author's own claim that a rule does not apply here, so an expired or
+// unjustified one is a defect the reviewers would have to take on trust. The
+// marker template comes from the registry's `exception_marker`, never hardcoded,
+// so a registry using a different comment syntax still works.
+// ---------------------------------------------------------------------------
+function auditExceptions(addedByFile, knownIds, today, markerToken) {
+  const findings = [];
+  // The token comes from the registry's own `exception_marker` (e.g.
+  // "// standard:exception(<RULE-ID>) <reason> <expiry:YYYY-MM-DD>" yields
+  // "standard:exception"). Hardcoding it, as an earlier version did, meant a
+  // registry declaring a different marker got ZERO exception auditing with no gap
+  // recorded  -  a silent pass, and it contradicted the shipped contract. The
+  // comment prefix stays open (`//`, `#`, `--`) so the scan is language-agnostic.
+  const token = (markerToken ?? "standard:exception").replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const re = new RegExp(`(?://|#|--)\\s*${token}\\(([^)]*)\\)\\s*(.*)$`);
+
+  for (const [file, added] of addedByFile) {
+    for (const { line, text } of added) {
+      const m = re.exec(text);
+      if (!m) continue;
+      const id = m[1].trim();
+      const rest = (m[2] ?? "").trim();
+      const dateMatch = /(\d{4}-\d{2}-\d{2})/.exec(rest);
+      const reason = rest.replace(/(\d{4}-\d{2}-\d{2})/, "").trim();
+
+      if (!id) {
+        findings.push(f(file, line, "blocking", null, "Exception marker names no rule ID.",
+          "Name the rule the exception applies to: standard:exception(<RULE-ID>) <reason> <expiry>."));
+        continue;
+      }
+      if (knownIds.size > 0 && !knownIds.has(id)) {
+        findings.push(f(file, line, "blocking", id,
+          `Exception cites '${id}', which is not in any registry in scope for this diff.`,
+          "Use a real rule ID, or drop the marker. An exception against an unknown rule suppresses nothing and hides intent."));
+      }
+      if (!dateMatch) {
+        findings.push(f(file, line, "important", id,
+          `Exception for '${id}' has no expiry date.`,
+          "Add an expiry: standard:exception(<RULE-ID>) <reason> YYYY-MM-DD. An exception with no expiry is a permanent silent carve-out."));
+      } else if (dateMatch[1] < today) {
+        findings.push(f(file, line, "blocking", id,
+          `Exception for '${id}' expired on ${dateMatch[1]}.`,
+          "Fix the underlying violation, or renew the exception with a new expiry and a current reason."));
+      }
+      if (!reason) {
+        findings.push(f(file, line, "important", id,
+          `Exception for '${id}' gives no reason.`,
+          "State why the rule does not apply here. An unexplained exception cannot be reviewed, only trusted."));
+      }
+    }
+  }
+  return findings;
+}
+
+function f(file, line, severity, ruleId, issue, fix) {
+  return {
+    severity,
+    file,
+    line,
+    issue,
+    fix,
+    ...(ruleId ? { ruleId } : {}),
+    criteriaSource: "exception-marker-audit",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Registry discovery: declared, not sniffed.
+// ---------------------------------------------------------------------------
+// Depth differs per host, which is why this is a bounded walk rather than a
+// fixed path: an installed tree is flat (`~/.claude/skills/<skill>/SKILL.md`)
+// while a checkout nests by group (`pipeline/skills/shared/core/<skill>/`).
+// Hardcoding either depth finds nothing on the other host.
+const DISCOVERY_MAX_DEPTH = 4;
+
+function findSkillDirs(dir, depth, acc) {
+  if (depth > DISCOVERY_MAX_DEPTH) return acc;
+  if (existsSync(join(dir, "SKILL.md"))) {
+    acc.push(dir);
+    return acc; // a skill directory does not contain further skills
+  }
+  for (const entry of readdirSafe(dir)) {
+    if (entry.startsWith(".") || entry === "node_modules") continue;
+    const child = join(dir, entry);
+    let st;
+    try {
+      st = statSync(child);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) findSkillDirs(child, depth + 1, acc);
+  }
+  return acc;
+}
+
+function discoverRegistries(roots) {
+  const out = [];
+  const escaped = [];
+  const seen = new Set();
+  for (const root of roots) {
+    for (const skillDir of findSkillDirs(root, 0, [])) {
+      const skillFile = join(skillDir, "SKILL.md");
+      const fm = readFrontmatter(skillFile);
+      if (!fm["standards-registry"]) continue;
+      const name = fm.name ?? basename(skillDir);
+      if (seen.has(name)) continue;
+      // `standards-registry` is author-controlled frontmatter, and resolve()
+      // happily accepts `../../..` chains and absolute paths. Unconstrained, any
+      // installed skill could point this gate at an arbitrary readable file
+      // (`standards-registry: /Users/x/.aws/credentials`), whose matching lines
+      // would be extracted into the manifest and injected into every reviewer
+      // prompt via the shared ${CRITERIA} block. Contain it to the skill's own
+      // directory; a declaration that escapes is recorded, not followed.
+      const rulesPath = resolve(skillDir, fm["standards-registry"]);
+      const skillRoot = resolve(skillDir) + sep;
+      if (!rulesPath.startsWith(skillRoot)) {
+        escaped.push({
+          name,
+          path: rulesPath,
+          reason: `standards-registry escapes the skill directory (declared: ${fm["standards-registry"]})`,
+        });
+        continue;
+      }
+      seen.add(name);
+      out.push({ name, skillFile, rulesPath, declared: fm["standards-registry"] });
+    }
+  }
+  return { registries: out.sort((a, b) => a.name.localeCompare(b.name)), escaped };
+}
+
+// ---------------------------------------------------------------------------
+// main
+// ---------------------------------------------------------------------------
+function parseArgs(argv) {
+  const o = { changedFiles: null, json: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--json") o.json = true;
+    else if (a === "--diff") o.diff = argv[++i];
+    else if (a === "--changed-files") o.changedFiles = argv[++i].split(",").filter(Boolean);
+    else if (a === "--state") o.state = argv[++i];
+    else if (a === "--repo") o.repo = argv[++i];
+    else if (a === "--out") o.out = argv[++i];
+    else if (a === "--skills-root") o.skillsRoot = argv[++i];
+    else if (a === "--today") o.today = argv[++i]; // tests pin the clock
+    else {
+      console.error(`unknown argument: ${a}`);
+      process.exit(1);
+    }
+  }
+  return o;
+}
+
+const opts = parseArgs(process.argv.slice(2));
+const repoRoot = resolve(opts.repo ?? process.cwd());
+const today = opts.today ?? new Date().toISOString().slice(0, 10);
+
+let changedFiles = opts.changedFiles ?? [];
+let addedByFile = new Map();
+
+if (opts.diff) {
+  if (!existsSync(opts.diff)) {
+    console.error(`ERR: diff not found: ${opts.diff}`);
+    process.exit(1);
+  }
+  const parsed = parseDiff(readFileSync(opts.diff, "utf8"));
+  if (!opts.changedFiles) changedFiles = parsed.files;
+  addedByFile = parsed.addedByFile;
+} else if (changedFiles.length === 0) {
+  console.error("ERR: pass --diff <patch> or --changed-files a,b");
+  process.exit(1);
+}
+
+// --- self-report ledger (corroborating only) -------------------------------
+// Three distinct states. `absent` is NOT `empty`: a Phase 3 that consulted five
+// skills and forgot to record them is byte-identical in state to one that
+// consulted nothing, so treating a missing array as "nothing applied" would let
+// every completeness number report green over an empty set.
+let ledger = { status: "absent", entries: [] };
+if (opts.state) {
+  if (!existsSync(opts.state)) {
+    console.error(`ERR: state not found: ${opts.state}`);
+    process.exit(1);
+  }
+  try {
+    const state = JSON.parse(readFileSync(opts.state, "utf8"));
+    const calls = state?.telemetry?.skillCalls;
+    if (Array.isArray(calls)) {
+      ledger = { status: calls.length ? "declared" : "empty", entries: calls };
+    }
+  } catch (e) {
+    console.error(`ERR: state is not valid JSON: ${e.message}`);
+    process.exit(1);
+  }
+}
+
+// --- language census of the diff ------------------------------------------
+const languages = {};
+for (const file of changedFiles) {
+  const lang = classifyLanguage(file);
+  (languages[lang] ??= []).push(file);
+}
+
+// --- discover + load registries -------------------------------------------
+// An explicit --skills-root that does not exist is a SETUP error, not an empty
+// result: silently searching nothing produced a manifest with zero selected
+// rules, which made validate-reviewer.mjs skip the conformance check entirely
+// and a review report clean over criteria it never loaded. That is the single
+// worst outcome this gate exists to prevent, so it fails loudly instead.
+const { roots, probed: probedRoots } = resolveSkillsRoots(opts.skillsRoot);
+if (opts.skillsRoot && roots.length === 0) {
+  console.error(`ERR: --skills-root does not exist: ${opts.skillsRoot}`);
+  process.exit(1);
+}
+const noRootsResolved = roots.length === 0;
+const { registries: discovered, escaped: escapedDeclarations } = discoverRegistries(roots);
+
+const registries = [];
+const unparseable = [...escapedDeclarations];
+
+for (const d of discovered) {
+  if (!existsSync(d.rulesPath)) {
+    unparseable.push({ name: d.name, path: d.rulesPath, reason: "declared standards-registry file does not exist" });
+    continue;
+  }
+  let loaded;
+  try {
+    loaded = readRegistry(d.rulesPath);
+  } catch (e) {
+    unparseable.push({ name: d.name, path: d.rulesPath, reason: `unreadable: ${e.message}` });
+    continue;
+  }
+  if (loaded.rules.length === 0) {
+    unparseable.push({ name: d.name, path: d.rulesPath, reason: "no rules extracted  -  rules: block missing or unexpected indentation" });
+    continue;
+  }
+  registries.push({ ...d, ...loaded });
+}
+
+// --- scope resolution ------------------------------------------------------
+const selected = [];
+const perRegistry = [];
+
+for (const reg of registries) {
+  const scope = reg.meta.scope;
+  const regLanguages = scope?.languages ?? [];
+  const langHit = regLanguages.length === 0
+    ? Object.keys(languages)
+    : regLanguages.filter((l) => Object.prototype.hasOwnProperty.call(languages, l));
+
+  // Files this registry may speak about at all.
+  const inScopeFiles = changedFiles.filter((file) => {
+    const lang = classifyLanguage(file);
+    if (regLanguages.length && !regLanguages.includes(lang)) return false;
+    if (scope?.excludePaths?.length && matchesAnyGlob(file, scope.excludePaths)) return false;
+    if (scope?.paths?.length && !matchesAnyGlob(file, scope.paths)) return false;
+    return true;
+  });
+
+  const unscoped = !scope || (regLanguages.length === 0 && !scope.paths?.length);
+
+  let kept = 0;
+  const droppedReasons = {};
+  if (inScopeFiles.length > 0 && !unscoped) {
+    for (const rule of reg.rules) {
+      // A retired rule is retired by status, never deleted. `status` is absent
+      // from every shipped registry today, so missing means active  -  recorded
+      // as statusDeclared:false rather than assumed.
+      if (rule.status && rule.status !== "active") {
+        droppedReasons["retired-by-status"] = (droppedReasons["retired-by-status"] ?? 0) + 1;
+        continue;
+      }
+      // Per-rule scope narrows, never widens.
+      const files = rule.scope?.paths?.length
+        ? inScopeFiles.filter((f2) => matchesAnyGlob(f2, rule.scope.paths))
+        : inScopeFiles;
+      if (files.length === 0) {
+        const why = rule.scopeReason ? `out-of-scope: ${rule.scopeReason}` : "out-of-scope: no changed file matches the rule's paths";
+        droppedReasons[why] = (droppedReasons[why] ?? 0) + 1;
+        continue;
+      }
+      selected.push({
+        ruleId: rule.id,
+        registry: reg.name,
+        severity: rule.severity ?? "important",
+        enforcement: rule.enforcement ?? "judgement",
+        files,
+        statusDeclared: rule.statusDeclared,
+      });
+      kept++;
+    }
+  }
+
+  perRegistry.push({
+    name: reg.name,
+    rulesPath: reg.rulesPath,
+    version: reg.meta.version,
+    totalRules: reg.rules.length,
+    selectedRules: kept,
+    droppedRules: reg.rules.length - kept,
+    droppedReasons,
+    scopeDeclared: !unscoped,
+    scopeLanguages: regLanguages,
+    languagesMatched: langHit,
+    inScopeFileCount: inScopeFiles.length,
+    notCovered: reg.meta.notCovered,
+    loadedAs: unscoped ? "reference-only" : inScopeFiles.length ? "rule-checklist" : "not-applicable",
+    ...(unscoped
+      ? { referenceOnlyReason: "registry declares no scope; applying its rules to unknown languages would manufacture findings" }
+      : {}),
+    toolchains: detectToolchains(repoRoot, reg.rules),
+    exceptionMarker: reg.meta.exceptionMarker,
+  });
+}
+
+// --- coverage --------------------------------------------------------------
+const coveredFiles = new Set(selected.flatMap((s) => s.files));
+const uncovered = changedFiles.filter((f2) => !coveredFiles.has(f2));
+
+const gaps = [];
+for (const [lang, files] of Object.entries(languages)) {
+  const covered = files.filter((f2) => coveredFiles.has(f2));
+  if (covered.length === 0) {
+    const claims = perRegistry
+      .flatMap((r) => Object.entries(r.notCovered ?? {}).map(([k, v]) => ({ registry: r.name, key: k, note: v })))
+      .filter((c) => c.key === lang || lang.startsWith(c.key));
+    gaps.push({
+      language: lang,
+      fileCount: files.length,
+      files,
+      reason: claims.length
+        ? `no registry in scope covers ${lang}: ${claims.map((c) => `${c.registry} declares '${c.key}' not covered`).join("; ")}`
+        : `no registry in scope declares ${lang}`,
+      consequence: "these files are reviewed on general criteria only  -  no rule IDs apply to them",
+    });
+  }
+}
+
+// --- module guides ---------------------------------------------------------
+const { guides, dropped: guidesDropped } = collectModuleGuides(repoRoot, changedFiles);
+
+// --- exception audit -------------------------------------------------------
+// knownIds spans EVERY discovered registry, not just the in-scope ones. Narrowing
+// it to the selected set would report a valid rule as unknown whenever the
+// exception sits in a file that rule does not cover, which is a false accusation
+// in the one place the author is trying to be explicit. The narrower question  - 
+// "is this exception citing a rule that applies here?"  -  is answered separately
+// below, so a mis-scoped exception is still reported, just not as a typo.
+const knownIds = new Set(registries.flatMap((r) => r.rules.map((x) => x.id)));
+const inScopeIds = new Set(selected.map((s) => s.ruleId));
+const markerToken = registries
+  .map((r) => r.meta.exceptionMarker)
+  .filter(Boolean)
+  .map((m) => (m.match(/([A-Za-z0-9_:.-]+)\s*\(/) ?? [])[1])
+  .filter(Boolean)[0];
+const findings = auditExceptions(addedByFile, knownIds, today, markerToken);
+
+// A known rule cited where it does not apply: the exception suppresses nothing,
+// so it is dead weight that reads as deliberate coverage.
+if (inScopeIds.size > 0) {
+  for (const [file, added] of addedByFile) {
+    for (const { line, text } of added) {
+      const m = /(?:\/\/|#|--)\s*[A-Za-z0-9_:.-]+\(([^)]*)\)/.exec(text);
+      if (!m) continue;
+      const id = m[1].trim();
+      if (!id || !knownIds.has(id) || inScopeIds.has(id)) continue;
+      findings.push({
+        severity: "important",
+        file,
+        line,
+        issue: `Exception cites '${id}', a real rule that is not in scope for this file.`,
+        fix: "Drop the marker, or move it to a file the rule actually covers. An exception against an out-of-scope rule suppresses nothing while reading as a deliberate carve-out.",
+        ruleId: id,
+        criteriaSource: "exception-marker-audit",
+      });
+    }
+  }
+}
+
+// --- toolchain findings ----------------------------------------------------
+for (const reg of perRegistry) {
+  if (reg.loadedAs !== "rule-checklist") continue;
+  for (const t of reg.toolchains) {
+    if (t.wired) continue;
+    findings.push({
+      severity: "important",
+      file: ".",
+      line: 0,
+      issue: `${reg.name} delegates its mechanical rules to ${t.tool}, which is not wired in this repo (looked for ${t.configCandidates.join(", ")}).`,
+      fix: `Add a ${t.tool} config and run it in CI. Until then every '${t.tool}' rule in this registry is unverified, and a review that reports no violations is reporting that nothing was measured.`,
+      criteriaSource: `${reg.name}:toolchain`,
+    });
+  }
+}
+
+// --- ledger corroboration --------------------------------------------------
+// The resolver is primary. A declared entry the resolver did not independently
+// reach is FLAGGED, not trusted: it means the dev phase claims a criterion the
+// review cannot bind to any changed file.
+const resolvedNames = new Set(perRegistry.map((r) => r.name));
+const declaredNames = ledger.entries.map((e) => e?.skill).filter(Boolean);
+const declaredNotResolved = [...new Set(declaredNames)].filter((n) => !resolvedNames.has(n));
+const ledgerMissingTargets = ledger.entries.filter((e) => !Array.isArray(e?.targetFiles) || e.targetFiles.length === 0).length;
+
+// Two values, not three. An earlier version branched on
+// `declaredNotResolved.length === 0` and returned "mixed" from BOTH arms, so the
+// condition was dead and the flagged-vs-corroborated distinction it implied was
+// not expressible in the field. The distinction lives in
+// `ledger.declaredButNotResolved` instead, where a consumer can see exactly which
+// claim failed to bind rather than inferring it from a summary word.
+const ledgerSource = ledger.status === "declared" ? "mixed" : "derived";
+
+const manifest = {
+  schemaVersion: "1.0.0",
+  generatedFor: { repoRoot, changedFileCount: changedFiles.length },
+  ledger: {
+    source: ledgerSource,
+    selfReport: ledger.status,
+    entryCount: ledger.entries.length,
+    entriesMissingTargetFiles: ledgerMissingTargets,
+    declaredButNotResolved: declaredNotResolved,
+    note: "The resolver below is primary. This block is a self-report from Phase 3 and is corroborating evidence only: an unrecorded consultation and no consultation are indistinguishable in state, so coverage is never computed from it.",
+  },
+  languages: Object.fromEntries(Object.entries(languages).map(([k, v]) => [k, v.length])),
+  registries: perRegistry,
+  unparseableRegistries: unparseable,
+  selectedRules: selected,
+  selectedRuleCount: selected.length,
+  coverage: {
+    changedFiles: changedFiles.length,
+    filesWithRuleCriteria: coveredFiles.size,
+    filesWithoutRuleCriteria: uncovered.length,
+    uncoveredFiles: uncovered,
+    declaredGaps: gaps,
+  },
+  moduleGuides: { guides, dropped: guidesDropped, cap: GUIDE_CAP },
+  findings,
+  skillsRootsSearched: probedRoots,
+  resolutionFailure: noRootsResolved
+    ? "no skills root exists on this host  -  nothing was searched, so no criteria could be resolved"
+    : null,
+};
+
+const outPath = opts.out ?? join(repoRoot, ".pipeline", "criteria-manifest.json");
+try {
+  const dir = dirname(outPath);
+  if (!existsSync(dir)) {
+    const { mkdirSync } = await import("node:fs");
+    mkdirSync(dir, { recursive: true });
+  }
+  writeFileSync(outPath, JSON.stringify(manifest, null, 2) + "\n");
+} catch (e) {
+  console.error(`ERR: cannot write manifest to ${outPath}: ${e.message}`);
+  process.exit(1);
+}
+
+if (opts.json) {
+  process.stdout.write(JSON.stringify(manifest, null, 2) + "\n");
+} else {
+  console.log(`criteria-manifest: ${outPath}`);
+  console.log(`  languages:      ${Object.entries(manifest.languages).map(([k, v]) => `${k}:${v}`).join(" ") || "(none)"}`);
+  console.log(`  registries:     ${perRegistry.length} discovered, ${perRegistry.filter((r) => r.loadedAs === "rule-checklist").length} as rule-checklist`);
+  console.log(`  selected rules: ${selected.length}`);
+  console.log(`  coverage:       ${coveredFiles.size}/${changedFiles.length} changed files carry rule criteria`);
+  for (const g of gaps) console.log(`  GAP  ${g.language} (${g.fileCount} file(s)): ${g.reason}`);
+  console.log(`  ledger:         ${manifest.ledger.source} (self-report: ${ledger.status})`);
+  console.log(`  findings:       ${findings.length}`);
+}
+
+// Fail closed when NO skills root existed. Continuing would emit a manifest with
+// zero selected rules, which makes validate-reviewer.mjs skip the conformance
+// check and the review read as clean over criteria that were never loaded. An
+// empty registry set inside a root that DOES exist is a different, legitimate
+// case: it yields a declared coverage gap and exit 0.
+if (noRootsResolved) {
+  console.error("ERR: no skills root found  -  criteria could not be resolved. Probed:");
+  for (const c of probedRoots) console.error(`  ${c.existed ? "found" : "absent"}: ${c.path}`);
+  process.exit(2);
+}
+
+// Fail closed on a declared-but-unparseable registry: silently continuing would
+// drop that registry's whole rule set from the denominator, and the run would
+// report a clean review over criteria it never loaded.
+if (unparseable.length > 0) {
+  console.error("ERR: declared registries could not be parsed:");
+  for (const u of unparseable) console.error(`  ${u.name}: ${u.reason} (${u.path})`);
+  process.exit(2);
+}