@mindrian_os/cli 2.0.0-beta.3 → 2.0.0-beta.31

package/scripts/build-connector-registry.cjs

@@ -0,0 +1,1331 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Phase 143.3-01 - Connector registry generator + drift tripwire + names refresh.
+ *
+ * Implements: CONN-02 (the generator with the nested-map parser extension).
+ *
+ * The Connector Contract generalizes Phase 122: the `connector:` frontmatter
+ * block on each skill/command is the ONE place the reach-wiring lives, and
+ * `data/connector-registry.json` is GENERATED from it and CI-checked against it.
+ * A `--check` run regenerates it in memory and exits non-zero on a stale
+ * on-disk registry OR an unresolvable framework name (one not in the
+ * FEEDS_INTO-linked Brain framework slice snapshotted to
+ * `data/framework-names.json`).
+ *
+ * Canon Part 7 (Reuse Before Build): this MIRRORS
+ * scripts/build-command-registry.cjs wholesale -- the hand-rolled line-walk
+ * frontmatter parser, the static-allowlist load, the deterministic serializer,
+ * the three-branch main(). The ONE genuine net-new concern is the nested-map
+ * descent (parseConnectorFrontmatter), because the `connector:` block is one
+ * indent level deeper than Phase 122's flat `frameworks:` list. It adds NO new
+ * dependency (no gray-matter, no zod).
+ *
+ * Canon Part 8 (The Graph Boundary): the registry is plugin-local, validated
+ * AGAINST the SHIPPED Brain framework-name snapshot, NEVER written back. The
+ * ONLY Brain touch is a read-only brain.query in --refresh-names at BUILD time
+ * -- the query carries only generic `:Framework` node names (a methodology
+ * handle, never user data), and there is no write Cypher anywhere in this file.
+ * A connector's framework/web_scope are GENERIC handles only; the registry
+ * never carries user content. The generator and the orchestrator never need the
+ * Brain at runtime.
+ *
+ * Usage:
+ *   node scripts/build-connector-registry.cjs
+ *       scan the commands and skills frontmatter -> write
+ *       data/connector-registry.json ; exit 1 on an unresolvable framework
+ *   node scripts/build-connector-registry.cjs --check
+ *       regenerate in memory ; exit 1 if on-disk JSON is stale OR a framework
+ *       is unresolvable ; print a one-line recovery command in stderr
+ *   node scripts/build-connector-registry.cjs --refresh-names
+ *       read-only brain.query -> rewrite data/framework-names.json
+ *       (build-time only ; graceful no-op if the Brain is unreachable)
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+
+// CONN-03 frozen banks. REACH_IDS (the 6, Phase 148 D-09) + POSTURE_IDS (the 3) are required
+// from the SINGLE frozen source so the connector validations can NEVER drift
+// from the dial doctrine (lib/core/sensors/sensor-types.cjs). The --check
+// tripwire validates every connector's reach_id / posture against these banks.
+// This require is sync, zero-I/O, and makes ZERO Brain/network calls (Part 8).
+const { REACH_IDS, POSTURE_IDS } = require(
+  path.join(REPO_ROOT, 'lib', 'core', 'sensors', 'sensor-types.cjs')
+);
+
+// CONN-03 WFL-01 resolver-resolution guard. commandsForFramework() is the only
+// door from a framework name to a /mos: command (Phase 122). The --check
+// tripwire asserts every connector framework RESOLVES through it (length > 0),
+// catching a fake/typo framework that the build-time allowlist has() could
+// miss. The resolver reads only data/command-registry.json; it makes ZERO Brain
+// calls (command-resolver.cjs header, Part 8).
+const { commandsForFramework } = require(
+  path.join(REPO_ROOT, 'lib', 'workflow', 'command-resolver.cjs')
+);
+
+// Phase 235-02 (CIRS-02). The generic seam-liveness helper. coverageReport()
+// below routes its MCP-tool-file walk through checkClaimedModuleLiveness() so
+// the "this module claims to export connectors" seam is checked by the SAME
+// shared primitive Phases 237/238/239 use for their own seams, instead of a
+// CIRS-local reimplementation. Pure, zero Brain/network (Part 8).
+const seamLiveness = require(path.join(REPO_ROOT, 'lib', 'core', 'seam-liveness.cjs'));
+
+const COMMANDS_DIR = path.join(REPO_ROOT, 'commands');
+const SKILLS_DIR = path.join(REPO_ROOT, 'skills');
+const AGENTS_DIR = path.join(REPO_ROOT, 'agents');
+const DATA_DIR = path.join(REPO_ROOT, 'data');
+const REGISTRY_PATH = path.join(DATA_DIR, 'connector-registry.json');
+const FW_NAMES_PATH = path.join(DATA_DIR, 'framework-names.json');
+const LEDGER_PATH = path.join(DATA_DIR, 'connector-coverage-ledger.json');
+
+const LEDGER_GENERATED_NOTE =
+  'GENERATED by scripts/build-connector-registry.cjs (coverageReport) - do not edit by hand. The wired-XOR-excluded coverage ledger: every command/skill/agent surface classified as wired, excluded, or gap (Canon Part 11 R1).';
+
+// Phase 198-04 (SPEC-2, Task 1) -- the MCP-tool connector discovery source. A
+// FOURTH connector source (commands/skills/agents are the first three) so MCP
+// tools are first-class in the born-wired gate: every lib/mcp/tools/*.cjs
+// module -- plus lib/mcp/tool-router.cjs's MCP_TOOL_CONNECTORS and
+// lib/mcp/contract-version.cjs's connectors -- exports a `connectors` array
+// (the SOURCE of truth); this generator discovers each and GENERATES
+// data/mcp-tool-connectors.json from them (the MCP-tool projection, "do not
+// edit by hand" like data/connector-registry.json), AND folds the same
+// entries into data/connector-registry.json's `connectors` array so a single
+// `--check` proves BOTH files clean. Canon Part 8: zero Brain/network calls --
+// this is pure filesystem discovery, exactly like listSourceFiles() above.
+const MCP_TOOLS_DIR = path.join(REPO_ROOT, 'lib', 'mcp', 'tools');
+const MCP_TOOL_ROUTER_PATH = path.join(REPO_ROOT, 'lib', 'mcp', 'tool-router.cjs');
+const MCP_CONTRACT_VERSION_PATH = path.join(REPO_ROOT, 'lib', 'mcp', 'contract-version.cjs');
+const MCP_CONNECTORS_PATH = path.join(DATA_DIR, 'mcp-tool-connectors.json');
+const MCP_GENERATED_NOTE =
+  'GENERATED by scripts/build-connector-registry.cjs (MCP-tool discovery) - do not edit by hand. The MCP-tool projection: every lib/mcp/tools/*.cjs module (plus lib/mcp/tool-router.cjs and lib/mcp/contract-version.cjs) exports a `connectors` array (the SOURCE of truth); this file is the generated registry of those descriptors, also folded into data/connector-registry.json (source: "mcp_tool").';
+
+const GENERATED_NOTE =
+  'GENERATED by scripts/build-connector-registry.cjs - do not edit by hand';
+
+// The FEEDS_INTO traversal that snapshots the framework-name allowlist. This
+// is the ONLY Cypher this file ever runs, it is read-only, and it carries no
+// user-specific strings -- only the generic `:Framework` label. Reused from
+// build-command-registry.cjs verbatim so a --refresh-names here matches Phase
+// 122 exactly.
+const FW_NAMES_CYPHER =
+  'MATCH (f:Framework) WHERE (f)-[:FEEDS_INTO]-() RETURN f.name AS name';
+
+// The 11 connector sub-keys (the contract in docs/CONNECTOR-CONTRACT.md). The
+// generator pulls each from the parsed connector map; absent fields degrade.
+const CONNECTOR_KEYS = [
+  'connects_to_spine',
+  'sensor_triggers',
+  'reach_id',
+  'sub_mode',
+  'framework',
+  'posture',
+  'hierarchy_rank',
+  'filing',
+  'plan_gated',
+  'web_scope',
+  'surface',
+];
+
+// ---------------------------------------------------------------------------
+// coerce(v) -- the value coercions the flat parser already does (null, boolean,
+// integer, JSON array, quote-strip). Shared by the flat top-level walk and the
+// nested connector descent so the two stay byte-identical in behavior.
+// ---------------------------------------------------------------------------
+function coerce(v) {
+  if (v === '') return [];
+  if (v === 'null' || v === '~') return null;
+  if (v === 'true' || v === 'false') return v === 'true';
+  if (/^-?\d+$/.test(v)) return parseInt(v, 10);
+  if (v.startsWith('[')) {
+    try {
+      return JSON.parse(v);
+    } catch (_e) {
+      // Not strict JSON (e.g. `[SENS-02, SENS-07]` with unquoted tokens, the
+      // common shape for sensor_triggers). Split the inner CSV into a trimmed,
+      // quote-stripped array. An empty `[]` yields [].
+      const inner = v.replace(/^\[/, '').replace(/\]$/, '').trim();
+      if (inner === '') return [];
+      return inner
+        .split(',')
+        .map((s) => s.trim().replace(/^["']|["']$/g, ''))
+        .filter((s) => s.length > 0);
+    }
+  }
+  return v.replace(/^["']|["']$/g, '');
+}
+
+// ---------------------------------------------------------------------------
+// parseConnectorFrontmatter(md) -- the nested-map parser. Mirrors the flat
+// parseFrontmatter in build-command-registry.cjs (lines 100-137) AND extends it
+// to DESCEND one indent level into the `connector:` nested map: when a
+// top-level key is `connector` with an empty value, subsequent indented
+// `  key: value` lines are accumulated into out.connector as an object, with
+// the SAME value coercions (null, booleans, integers, JSON arrays, indented
+// dash-lists, quote-stripping). This nested descent is the ONE genuine net-new
+// parsing concern this phase introduces.
+// ---------------------------------------------------------------------------
+function parseConnectorFrontmatter(md) {
+  if (typeof md !== 'string') return {};
+  const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(md);
+  if (!m) return {};
+  const out = {};
+  let key = null; // current top-level dash-list key
+
+  // Nested-descent state: when we are inside the `connector:` map, every
+  // indented line is parsed into `connectorObj` until a non-indented line ends
+  // the block.
+  let inConnector = false;
+  let connectorObj = null;
+  let connectorKey = null; // current nested dash-list key
+
+  for (const rawLine of m[1].split(/\r?\n/)) {
+    const line = rawLine.replace(/\s+$/, '');
+    const indented = /^\s+\S/.test(line);
+
+    // While inside the connector map, an indented line is a nested sub-key (or a
+    // nested dash-list item). A non-indented, non-blank line ends the block.
+    if (inConnector) {
+      if (line.trim() === '' || indented) {
+        if (line.trim() === '') continue;
+        // Strip the comment-only lines (e.g. `  # MUST match ...`).
+        const noComment = line.replace(/\s+#.*$/, '');
+        const subKv = /^\s+([A-Za-z0-9_-]+):\s*(.*)$/.exec(noComment);
+        if (subKv) {
+          connectorKey = subKv[1];
+          const sv = subKv[2].trim();
+          connectorObj[connectorKey] = coerce(sv);
+          continue;
+        }
+        const subDash = /^\s+-\s+(.*)$/.exec(noComment);
+        if (subDash && connectorKey) {
+          if (!Array.isArray(connectorObj[connectorKey])) connectorObj[connectorKey] = [];
+          connectorObj[connectorKey].push(subDash[1].replace(/^["']|["']$/g, ''));
+          continue;
+        }
+        // An indented line that is neither (blank-after-trim handled above) is
+        // ignored.
+        continue;
+      }
+      // A non-indented line -> the connector block is done.
+      inConnector = false;
+      out.connector = connectorObj;
+      connectorObj = null;
+      connectorKey = null;
+      // fall through to parse this line as a normal top-level line
+    }
+
+    const kv = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(line);
+    if (kv) {
+      key = kv[1];
+      const v = kv[2].trim();
+      if (key === 'connector' && v === '') {
+        // Enter the nested descent. connectorObj accumulates the sub-keys.
+        inConnector = true;
+        connectorObj = {};
+        connectorKey = null;
+        continue;
+      }
+      out[key] = coerce(v);
+    } else if (key && /^\s*-\s+/.test(line)) {
+      if (!Array.isArray(out[key])) out[key] = [];
+      out[key].push(line.replace(/^\s*-\s+/, '').replace(/^["']|["']$/g, ''));
+    }
+    // Any other line (blank, comment `# ...`) is ignored.
+  }
+
+  // EOF inside the connector block -> flush it.
+  if (inConnector && connectorObj) out.connector = connectorObj;
+
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// Load the committed framework-name allowlist (the FEEDS_INTO-linked Brain
+// slice UNION curated_extras). Mirrors build-command-registry.cjs verbatim --
+// the connector generator REUSES the shipped data/framework-names.json; it adds
+// NO new Brain query.
+// ---------------------------------------------------------------------------
+function loadFrameworkNames() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(FW_NAMES_PATH, 'utf8'));
+    const names = Array.isArray(raw && raw.framework_names) ? raw.framework_names : [];
+    const extras = Array.isArray(raw && raw.curated_extras) ? raw.curated_extras : [];
+    return new Set([...names, ...extras]);
+  } catch (_e) {
+    return new Set();
+  }
+}
+
+function loadCuratedExtras() {
+  try {
+    const raw = JSON.parse(fs.readFileSync(FW_NAMES_PATH, 'utf8'));
+    const extras = Array.isArray(raw && raw.curated_extras) ? raw.curated_extras : [];
+    return extras.slice();
+  } catch (_e) {
+    return [];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Source-file discovery: walk commands/*.md AND skills/*/SKILL.md AND
+// agents/*.md, deterministically sorted (commands, then skills, then agents),
+// so the registry is byte-stable across machines. Returns [{ kind, file, base }]
+// where the kind drives the surface id in buildRegistry(). The agents leg
+// byte-mirrors the commands leg (the same readdirSync + .md filter + sort +
+// try/catch-yields-[] when the dir is absent); an agent .md is parsed by the
+// SAME parseConnectorFrontmatter and obeys the SAME one-connector-per-file
+// contract, exactly like a command.
+// ---------------------------------------------------------------------------
+function listSourceFiles() {
+  const out = [];
+
+  let cmdFiles = [];
+  try {
+    cmdFiles = fs.readdirSync(COMMANDS_DIR).filter((f) => f.endsWith('.md')).sort();
+  } catch (_e) {
+    cmdFiles = [];
+  }
+  for (const f of cmdFiles) {
+    out.push({ kind: 'command', file: path.join(COMMANDS_DIR, f), base: f.replace(/\.md$/, '') });
+  }
+
+  let skillDirs = [];
+  try {
+    skillDirs = fs
+      .readdirSync(SKILLS_DIR, { withFileTypes: true })
+      .filter((e) => e.isDirectory())
+      .map((e) => e.name)
+      .sort();
+  } catch (_e) {
+    skillDirs = [];
+  }
+  for (const d of skillDirs) {
+    const skillFile = path.join(SKILLS_DIR, d, 'SKILL.md');
+    if (fs.existsSync(skillFile)) {
+      out.push({ kind: 'skill', file: skillFile, base: d });
+    }
+  }
+
+  let agentFiles = [];
+  try {
+    agentFiles = fs.readdirSync(AGENTS_DIR).filter((f) => f.endsWith('.md')).sort();
+  } catch (_e) {
+    agentFiles = [];
+  }
+  for (const f of agentFiles) {
+    out.push({ kind: 'agent', file: path.join(AGENTS_DIR, f), base: f.replace(/\.md$/, '') });
+  }
+
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// listMcpToolConnectorDescriptors() -- Phase 198-04 (SPEC-2, Task 1) MCP-tool
+// discovery. Walks lib/mcp/tools/*.cjs (sorted, deterministic) PLUS the two
+// named non-tools/ exporters (tool-router.cjs's MCP_TOOL_CONNECTORS,
+// contract-version.cjs's connectors), requires each, and collects every raw
+// descriptor from its exported array. Returns the RAW descriptors (each
+// module's own {tool, surface, connector, hitl_shape, hitl_why, ...} shape) --
+// normalizeMcpToolEntry() below maps them into the registry entry shape. A
+// module that fails to load or export nothing is silently skipped (Wave-safe,
+// mirrors listSourceFiles()'s try/catch-yields-[] discipline). Zero Brain/
+// network calls -- pure filesystem + require.
+// ---------------------------------------------------------------------------
+function listMcpToolConnectorDescriptors() {
+  const out = [];
+
+  const namedModules = [
+    { file: MCP_TOOL_ROUTER_PATH, exportKey: 'MCP_TOOL_CONNECTORS' },
+    { file: MCP_CONTRACT_VERSION_PATH, exportKey: 'connectors' },
+  ];
+  for (const nm of namedModules) {
+    if (!fs.existsSync(nm.file)) continue;
+    let mod;
+    try {
+      mod = require(nm.file);
+    } catch (_e) {
+      continue;
+    }
+    const arr = mod && Array.isArray(mod[nm.exportKey]) ? mod[nm.exportKey] : [];
+    for (const c of arr) out.push(c);
+  }
+
+  let toolFiles = [];
+  try {
+    toolFiles = fs.readdirSync(MCP_TOOLS_DIR).filter((f) => f.endsWith('.cjs')).sort();
+  } catch (_e) {
+    toolFiles = [];
+  }
+  for (const f of toolFiles) {
+    let mod;
+    try {
+      mod = require(path.join(MCP_TOOLS_DIR, f));
+    } catch (_e) {
+      continue;
+    }
+    const arr = mod && Array.isArray(mod.connectors) ? mod.connectors : [];
+    for (const c of arr) out.push(c);
+  }
+
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// listMcpToolClaimedSources() -- Phase 235-02 (CIRS-02). The CENSUS half of the
+// MCP-tool blind-spot fix. listMcpToolConnectorDescriptors() above answers "what
+// loaded?", which is exactly why it could not see the bug: a file that throws at
+// require time, or that forgets its `connectors` export, simply contributes
+// nothing and disappears without a trace. This function answers the other
+// question, "what does the repo CLAIM should be there?", by enumerating files on
+// disk and never requiring anything. The gap between the two censuses IS the
+// dead seam.
+//
+// Returns [{ id, path, exportKey }] -- one entry per lib/mcp/tools/*.cjs file
+// (sorted, deterministic), plus lib/mcp/tool-router.cjs (MCP_TOOL_CONNECTORS)
+// and lib/mcp/contract-version.cjs (connectors) when they exist. Pure
+// filesystem, zero Brain/network (Part 8).
+// ---------------------------------------------------------------------------
+function listMcpToolClaimedSources() {
+  const out = [];
+
+  let toolFiles = [];
+  try {
+    toolFiles = fs.readdirSync(MCP_TOOLS_DIR).filter((f) => f.endsWith('.cjs')).sort();
+  } catch (_e) {
+    toolFiles = [];
+  }
+  for (const f of toolFiles) {
+    out.push({
+      id: 'lib/mcp/tools/' + f,
+      path: path.join(MCP_TOOLS_DIR, f),
+      exportKey: 'connectors',
+    });
+  }
+
+  if (fs.existsSync(MCP_TOOL_ROUTER_PATH)) {
+    out.push({
+      id: 'lib/mcp/tool-router.cjs',
+      path: MCP_TOOL_ROUTER_PATH,
+      exportKey: 'MCP_TOOL_CONNECTORS',
+    });
+  }
+  if (fs.existsSync(MCP_CONTRACT_VERSION_PATH)) {
+    out.push({
+      id: 'lib/mcp/contract-version.cjs',
+      path: MCP_CONTRACT_VERSION_PATH,
+      exportKey: 'connectors',
+    });
+  }
+
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// listMcpToolFileHealth(claimedSources) -- the PROBE half. For each claimed
+// source, require() it inside a try/catch and read the claimed export. Returns
+// [{ id, live, loadError, connectorCount }] where `live` means the module loaded
+// AND its claimed export is a NON-EMPTY array. Unlike
+// listMcpToolConnectorDescriptors()'s `catch { continue }`, nothing is swallowed
+// here: a load failure becomes a reported loadError, and an empty/missing export
+// becomes live:false with connectorCount 0.
+//
+// claimedSources is OPTIONAL and defaults to listMcpToolClaimedSources(), so a
+// test can pass a synthetic array pointing at temp files and probe the real
+// logic without touching the real lib/mcp/tools/ tree.
+// ---------------------------------------------------------------------------
+function listMcpToolFileHealth(claimedSources) {
+  const sources = Array.isArray(claimedSources) ? claimedSources : listMcpToolClaimedSources();
+  const out = [];
+  for (const src of sources) {
+    const id = src && typeof src.id === 'string' ? src.id : String(src && src.path);
+    const exportKey =
+      src && typeof src.exportKey === 'string' && src.exportKey ? src.exportKey : 'connectors';
+    let mod = null;
+    let loadError = null;
+    try {
+      mod = require(src.path);
+    } catch (e) {
+      loadError = e && e.message ? String(e.message) : String(e);
+    }
+    const arr = !loadError && mod && Array.isArray(mod[exportKey]) ? mod[exportKey] : null;
+    out.push({
+      id,
+      exportKey,
+      live: !loadError && Array.isArray(arr) && arr.length > 0,
+      loadError,
+      connectorCount: arr ? arr.length : 0,
+    });
+  }
+  return out;
+}
+
+// normalizeMcpToolEntry(raw) -- maps a raw MCP-tool connector descriptor into
+// the SAME entry shape buildRegistry() emits for commands/skills/agents (a
+// superset: it carries reach_id/posture/framework as null -- the MCP-tool
+// governance dial is hitl_shape/hitl_why, not reach/posture -- plus the two
+// additive keys). source:'mcp_tool' is the discriminator validateConnectors()
+// uses to skip the frozen-6/frozen-3 reach/posture checks for these entries
+// (they are validated separately, advisory, by scripts/check-shape-
+// declaration.cjs's MCP-tool enumeration).
+function normalizeMcpToolEntry(raw) {
+  const r = raw && typeof raw === 'object' ? raw : {};
+  const tool = typeof r.tool === 'string' && r.tool
+    ? r.tool
+    : (typeof r.surface === 'string' && r.surface ? r.surface : 'unknown');
+  return {
+    surface: 'mcp:' + tool,
+    source: 'mcp_tool',
+    connects_to_spine: true,
+    sensor_triggers: [],
+    reach_id: null,
+    sub_mode: null,
+    framework: null,
+    posture: null,
+    hierarchy_rank: null,
+    filing: null,
+    plan_gated: false,
+    web_scope: null,
+    decision_surface: null,
+    hitl_shape: typeof r.hitl_shape === 'string' ? r.hitl_shape : null,
+    hitl_why: typeof r.hitl_why === 'string' ? r.hitl_why : null,
+  };
+}
+
+// buildMcpToolRegistry() -- the MCP-tool projection (data/mcp-tool-
+// connectors.json). Discovers + normalizes + sorts by surface for byte-stable
+// --check comparisons, mirroring serializeRegistry's determinism discipline.
+function buildMcpToolRegistry() {
+  const raw = listMcpToolConnectorDescriptors();
+  const connectors = raw
+    .map(normalizeMcpToolEntry)
+    .sort((a, b) => a.surface.localeCompare(b.surface));
+  return { generated_note: MCP_GENERATED_NOTE, connectors };
+}
+
+// serializeMcpToolRegistry(reg) -- same JSON.stringify(...,2)+trailing-newline
+// discipline as serializeRegistry(), so the --check byte-compare is
+// deterministic.
+function serializeMcpToolRegistry(reg) {
+  const clean = {
+    generated_note: reg.generated_note,
+    connectors: reg.connectors,
+  };
+  return JSON.stringify(clean, null, 2) + '\n';
+}
+
+// ---------------------------------------------------------------------------
+// buildRegistry() -- walk commands + skills (sorted), parse the nested
+// connector map, filter to surfaces where connector.connects_to_spine === true,
+// build the connectors[] array, the sensor_index, the framework_index, and
+// collect _unresolved for any framework not in the allowlist. Returns the
+// registry object PLUS the non-serialized `_unresolved` field (callers strip it
+// before writing).
+// ---------------------------------------------------------------------------
+function buildRegistry() {
+  const fwNames = loadFrameworkNames();
+  const sources = listSourceFiles();
+  const connectors = [];
+  const sensorIndex = {};
+  const frameworkIndex = {};
+  const unresolved = [];
+
+  for (const src of sources) {
+    let fm;
+    try {
+      fm = parseConnectorFrontmatter(fs.readFileSync(src.file, 'utf8'));
+    } catch (_e) {
+      continue;
+    }
+    const conn = fm.connector;
+    if (!conn || typeof conn !== 'object' || Array.isArray(conn)) continue;
+    // R1 (Canon Part 11) EXCLUDE branch: a connector that declares
+    // `excluded: true` is a first-class EXCLUDED surface, NOT wired. It does NOT
+    // push a wired connector entry and is NOT subject to the wired validations.
+    // `reason` is REQUIRED (D-172-a "no surface dark by accident") -- a missing
+    // reason is a build error surfaced via _excludeErrors so the default run and
+    // --check both fail closed. The exclude path opens NO Brain wire (Part 8).
+    if (conn.excluded === true) continue;
+    // Filter: only surfaces that opt in are wired. Absent/false = legacy.
+    if (conn.connects_to_spine !== true) continue;
+
+    // Three-way surface-id branch: command -> "/mos:" + base, skill -> "skill:"
+    // + base, agent -> "agent:" + base. The agent prefix mirrors the command and
+    // skill prefixes; an agent that declares a connect-to-spine connector: block
+    // joins the registry the same way a command does.
+    const surfaceName =
+      src.kind === 'command'
+        ? '/mos:' + src.base
+        : src.kind === 'skill'
+          ? 'skill:' + src.base
+          : 'agent:' + src.base;
+
+    const sensorTriggers = Array.isArray(conn.sensor_triggers)
+      ? conn.sensor_triggers.slice()
+      : [];
+    const framework =
+      typeof conn.framework === 'string' && conn.framework ? conn.framework : null;
+
+    const entry = {
+      surface: surfaceName,
+      source: src.kind,
+      connects_to_spine: true,
+      sensor_triggers: sensorTriggers,
+      reach_id: typeof conn.reach_id === 'string' ? conn.reach_id : null,
+      sub_mode: typeof conn.sub_mode === 'string' ? conn.sub_mode : null,
+      framework,
+      posture: typeof conn.posture === 'string' ? conn.posture : null,
+      hierarchy_rank:
+        typeof conn.hierarchy_rank === 'number' ? conn.hierarchy_rank : null,
+      filing: typeof conn.filing === 'string' ? conn.filing : null,
+      plan_gated: conn.plan_gated === true,
+      web_scope:
+        typeof conn.web_scope === 'string' && conn.web_scope ? conn.web_scope : null,
+      decision_surface: typeof conn.surface === 'string' ? conn.surface : null,
+    };
+
+    // WFL-01 build-time guard (mirror build-command-registry.cjs line 222):
+    // a framework not in the allowlist is unresolvable.
+    if (framework && !fwNames.has(framework)) {
+      unresolved.push({ surface: surfaceName, framework });
+    }
+
+    // sensor_index: each sensor_id -> push this connector's surface.
+    for (const sid of sensorTriggers) {
+      if (!Array.isArray(sensorIndex[sid])) sensorIndex[sid] = [];
+      sensorIndex[sid].push(surfaceName);
+    }
+
+    // framework_index: framework -> [surface] (the Phase 122 inverse-index idiom).
+    if (framework) {
+      if (!Array.isArray(frameworkIndex[framework])) frameworkIndex[framework] = [];
+      frameworkIndex[framework].push(surfaceName);
+    }
+
+    connectors.push(entry);
+  }
+
+  // Phase 198-04 (SPEC-2, Task 1): fold the MCP-tool connector projection into
+  // the SAME generated connector-registry.json, source-tagged 'mcp_tool' so
+  // validateConnectors() below can distinguish the HITL-shape dial (MCP tools)
+  // from the reach/posture dial (commands/skills/agents). The mcpToolRegistry
+  // returned alongside is the dedicated MCP-tool projection
+  // (data/mcp-tool-connectors.json), generated from the SAME discovery pass so
+  // the two files can never drift from each other.
+  const mcpToolRegistry = buildMcpToolRegistry();
+  for (const c of mcpToolRegistry.connectors) connectors.push(c);
+
+  return {
+    ontology_ref: 'data/framework-names.json',
+    generated_note: GENERATED_NOTE,
+    connectors,
+    sensor_index: sensorIndex,
+    framework_index: frameworkIndex,
+    _unresolved: unresolved,
+    _mcpToolRegistry: mcpToolRegistry,
+  };
+}
+
+// Serialize the registry exactly the way the on-disk file is written, so the
+// --check byte-compare is deterministic. Strips the non-serialized
+// `_unresolved` field. (Copied from build-command-registry.cjs lines 256-265 in
+// spirit so the layout + trailing newline are stable.)
+function serializeRegistry(reg) {
+  const clean = {
+    ontology_ref: reg.ontology_ref,
+    generated_note: reg.generated_note,
+    connectors: reg.connectors,
+    sensor_index: reg.sensor_index,
+    framework_index: reg.framework_index,
+  };
+  return JSON.stringify(clean, null, 2) + '\n';
+}
+
+// ---------------------------------------------------------------------------
+// ---------------------------------------------------------------------------
+// The four governed surface CLASSES (Canon Part 11 R1 four-class amendment,
+// navigator-LOCKED 2026-06-23; externally grounded in the ArbiterOS
+// governance-ISA paradigm, research/172-GOVERNOR-RESEARCH.md). Every governed
+// surface carries EXACTLY ONE class. The four classes are the invocation
+// governance ISA; the gate is class-aware. A fifth label, `utility-excluded`,
+// is NOT one of the four governance classes -- it is the class slot for an
+// EXCLUDED utility surface (the first-class conformant terminal state, R1), kept
+// distinct so an excluded utility is never mis-counted as a governed class.
+// This MINTS no new edge/node/reach and opens no Brain wire -- it NAMES existing
+// surface types. The wired/excluded/gap COUNTS are UNCHANGED by the class field.
+//   mechanical   -- a non-framework command/operation (plumbing that triggers a
+//                   reach but is not itself a pws methodology).
+//   framework    -- a pws methodology (declares frameworks: or a resolvable
+//                   connector.framework).
+//   intelligence -- an engine/sensor/analysis surface (rs-* / find-* / score-* /
+//                   whitespace / diagnostics / radar / the intelligence
+//                   orchestrator / analysis agents).
+//   pipeline     -- a chain/workflow surface (act / discover / ingest / a
+//                   multi-step orchestrated flow).
+// ---------------------------------------------------------------------------
+const FOUR_CLASSES = Object.freeze(['mechanical', 'framework', 'intelligence', 'pipeline']);
+const CLASS_UTILITY_EXCLUDED = 'utility-excluded';
+
+// Phase 235-02 (CIRS-02). The MCP-tool-FILE class: an ADDITIVE fifth member of
+// the class enum, deliberately NOT one of the four governance classes. An MCP
+// tool file is a module-liveness surface (does it load and export usable
+// connectors?), not a pws methodology / plumbing / engine / pipeline surface, so
+// it sits alongside CLASS_UTILITY_EXCLUDED rather than inside FOUR_CLASSES.
+// tests/test-cirs-four-class-floor.cjs deliberately never asserts a class COUNT
+// (see its header) precisely so an additive member like this one cannot
+// false-fail the floor.
+const CLASS_MCP_TOOL = 'mcp_tool';
+const SURFACE_CLASS_ENUM = Object.freeze(
+  FOUR_CLASSES.concat([CLASS_UTILITY_EXCLUDED, CLASS_MCP_TOOL])
+);
+
+// The intelligence-surface name prefixes/markers (engine/sensor/analysis). A
+// surface whose base matches one of these is an intelligence class. Generic
+// machinery handles only (Part 8).
+const INTELLIGENCE_MARKERS = Object.freeze([
+  'rs-', 'find-', 'score-', 'whitespace', 'diagnostics', 'radar',
+  'breakthrough', 'reverse-salient', 'analyze-', 'detect-',
+  'intelligence-orchestrator', 'lens', 'sensor',
+]);
+
+// The pipeline-surface name markers (chain/workflow). A multi-step orchestrated
+// flow.
+const PIPELINE_MARKERS = Object.freeze([
+  'act', 'discover', 'ingest', 'pipeline', 'chain', 'workflow', 'run-chain', 'runchain',
+]);
+
+// ---------------------------------------------------------------------------
+// classifySurfaceClass(src, fm, state) -- derive the one governed class for a
+// surface (Canon Part 11 R1 four-class amendment). EXCLUDED surfaces take the
+// `utility-excluded` slot. Otherwise: a surface that declares a frameworks:
+// block or a resolvable connector.framework is `framework`; an intelligence
+// marker base is `intelligence`; a pipeline marker base is `pipeline`;
+// everything else is `mechanical`. Deterministic + pure (reads only the passed
+// frontmatter + base name). The order is framework -> pipeline -> intelligence
+// -> mechanical so an act-like pipeline that also declares a framework is named
+// by its strongest signal (framework methodology wins). Zero Brain/network.
+// ---------------------------------------------------------------------------
+function classifySurfaceClass(src, fm, state) {
+  if (state === 'excluded') return CLASS_UTILITY_EXCLUDED;
+  const base = (src && typeof src.base === 'string') ? src.base.toLowerCase() : '';
+  const conn = fm && fm.connector && typeof fm.connector === 'object' && !Array.isArray(fm.connector)
+    ? fm.connector
+    : null;
+  const hasFrameworksBlock = Array.isArray(fm && fm.frameworks) && fm.frameworks.length > 0;
+  const hasConnFramework =
+    conn && typeof conn.framework === 'string' && conn.framework.trim().length > 0;
+  if (hasFrameworksBlock || hasConnFramework) return 'framework';
+  if (PIPELINE_MARKERS.indexOf(base) !== -1) return 'pipeline';
+  if (INTELLIGENCE_MARKERS.some(function (m) { return base.indexOf(m) === 0 || base === m; })) {
+    return 'intelligence';
+  }
+  return 'mechanical';
+}
+
+// classifySurface(src) -- the pure per-surface classifier shared by
+// coverageReport(). Reads ONE source file's connector frontmatter and returns
+// the R1 (Canon Part 11) terminal state:
+//   - 'wired'    : connector.connects_to_spine === true
+//   - 'excluded' : connector.excluded === true (a reason is REQUIRED; a missing
+//                  reason is a build error reported via the `error` field)
+//   - 'gap'      : neither (the surface is dark)
+// `excluded` takes precedence over a stray connects_to_spine on the same block:
+// an EXCLUDED surface is never counted as a gap. Returns
+// { surface, source, state, reason?, error? }. Zero Brain, zero network.
+// ---------------------------------------------------------------------------
+function classifySurface(src) {
+  const surfaceName =
+    src.kind === 'command'
+      ? '/mos:' + src.base
+      : src.kind === 'skill'
+        ? 'skill:' + src.base
+        : 'agent:' + src.base;
+
+  let fm;
+  try {
+    fm = parseConnectorFrontmatter(fs.readFileSync(src.file, 'utf8'));
+  } catch (_e) {
+    fm = {};
+  }
+  const conn = fm.connector;
+  const hasConn = conn && typeof conn === 'object' && !Array.isArray(conn);
+
+  if (hasConn && conn.excluded === true) {
+    const reason =
+      typeof conn.reason === 'string' && conn.reason.trim() ? conn.reason.trim() : null;
+    const out = {
+      surface: surfaceName,
+      source: src.kind,
+      state: 'excluded',
+      reason,
+      class: classifySurfaceClass(src, fm, 'excluded'),
+    };
+    if (!reason) {
+      out.error =
+        'connector ' + surfaceName +
+        ' declares excluded:true but no reason (D-172-a: no surface dark by accident)';
+    }
+    return out;
+  }
+
+  if (hasConn && conn.connects_to_spine === true) {
+    return {
+      surface: surfaceName,
+      source: src.kind,
+      state: 'wired',
+      class: classifySurfaceClass(src, fm, 'wired'),
+    };
+  }
+
+  return {
+    surface: surfaceName,
+    source: src.kind,
+    state: 'gap',
+    class: classifySurfaceClass(src, fm, 'gap'),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// coverageReport() -- the wired-XOR-excluded coverage classifier (Canon Part 11
+// R1/R9). Walks EVERY surface listSourceFiles() walks and classifies each as
+// wired / excluded / gap, so the command+skill+agent slice of surfaces.length
+// === the total command+skill+agent file count. Phase 235-02 adds a SECOND
+// slice: one surface per claimed MCP tool file (source:'mcp_tool'), so
+// surfaces.length === listSourceFiles().length + listMcpToolClaimedSources()
+// .length. counts.wired + counts.excluded + counts.gap === surfaces.length
+// either way (the XOR invariant: every surface lands in exactly one bucket).
+// Returns
+// { surfaces: [{surface, source, state}], counts: {wired, excluded, gap},
+//   errors: [...] } where errors carries any excluded-without-reason build
+// error. Pure: reads only the source frontmatter, makes ZERO Brain/network
+// calls, opens NO Brain wire (Part 8). This is the R9 gate's source of truth.
+// ---------------------------------------------------------------------------
+function coverageReport() {
+  const surfaces = [];
+  const counts = { wired: 0, excluded: 0, gap: 0 };
+  const errors = [];
+  for (const src of listSourceFiles()) {
+    const c = classifySurface(src);
+    surfaces.push({ surface: c.surface, source: c.source, state: c.state, class: c.class });
+    counts[c.state] += 1;
+    if (c.error) errors.push(c.error);
+  }
+
+  // Phase 235-02 (CIRS-02): the MCP-tool-file walk. Before this, MCP tools sat
+  // entirely outside the wired-XOR-excluded invariant -- coverageReport() walked
+  // only listSourceFiles(), and the separate listMcpToolConnectorDescriptors()
+  // path silently swallowed both a require() failure and a missing/empty
+  // `connectors` export. A tool file could be born dark and the gate stayed
+  // green. Every claimed source is now a surface here, so main()'s existing
+  // generic `state === 'gap'` hard-fail catches a dead one with no change to
+  // main() itself. The dead/live decision is delegated to the SHARED
+  // seam-liveness helper, never reimplemented inline: this call is load-bearing
+  // and tests/test-235-seam-liveness-mcp-coverage.cjs proves it.
+  const mcpHealth = listMcpToolFileHealth();
+  const mcpLiveness = seamLiveness.checkClaimedModuleLiveness(
+    mcpHealth.map((h) => ({
+      id: h.id,
+      live: h.live,
+      reason: h.loadError || 'exports.' + h.exportKey + ' is missing or empty',
+    }))
+  );
+  const mcpDead = new Set(mcpLiveness.dead);
+  for (const h of mcpHealth) {
+    const state = mcpDead.has(h.id) ? 'gap' : 'wired';
+    surfaces.push({
+      surface: 'mcp_tool_file:' + h.id,
+      source: 'mcp_tool',
+      state,
+      class: CLASS_MCP_TOOL,
+    });
+    counts[state] += 1;
+  }
+
+  surfaces.sort((a, b) => a.surface.localeCompare(b.surface));
+  return { surfaces, counts, errors };
+}
+
+// ---------------------------------------------------------------------------
+// serializeLedger(report) -- emit data/connector-coverage-ledger.json from a
+// coverageReport() result. Top-level keys are EXACTLY generated_note, counts,
+// surfaces (surfaces sorted by surface name for determinism). Mirrors
+// serializeRegistry's JSON.stringify(...,2) + trailing-newline + byte-compare
+// discipline so the --check STALE byte-compare is deterministic. The non-
+// serialized `errors` field never lands on disk.
+// ---------------------------------------------------------------------------
+function serializeLedger(report) {
+  const surfaces = Array.isArray(report && report.surfaces)
+    ? report.surfaces
+        .slice()
+        .map((s) => ({ surface: s.surface, source: s.source, state: s.state, class: s.class }))
+        .sort((a, b) => a.surface.localeCompare(b.surface))
+    : [];
+  const counts =
+    report && report.counts
+      ? { wired: report.counts.wired, excluded: report.counts.excluded, gap: report.counts.gap }
+      : { wired: 0, excluded: 0, gap: 0 };
+  const clean = {
+    generated_note: LEDGER_GENERATED_NOTE,
+    counts,
+    surfaces,
+  };
+  return JSON.stringify(clean, null, 2) + '\n';
+}
+
+// ---------------------------------------------------------------------------
+// validateConnectors(reg) -- the four CONN-03 validations. Returns an array of
+// error strings (empty = clean). Pure: reads only the built registry + the two
+// frozen banks + the resolver (zero Brain, zero network). Exported so
+// tests/test-connector-tripwire.cjs can exercise each bad case directly without
+// spawning a subprocess.
+//
+// The four validations (mirroring the missingTeaching error in
+// build-command-registry.cjs lines 367-382):
+//   (1) every reach_id is one of the frozen 6 (REACH_IDS)
+//   (2) every framework resolves via commandsForFramework() (WFL-01) -- checked
+//       for connectors that declare a filing or a decision surface (the ones
+//       that actually fire a command on APPROVE)
+//   (3) every posture is one of the frozen 3 (POSTURE_IDS)
+//   (4) no duplicate (sensor, reach, sub_mode) tuple collision
+// ---------------------------------------------------------------------------
+function validateConnectors(reg) {
+  const errs = [];
+  const connectors = Array.isArray(reg && reg.connectors) ? reg.connectors : [];
+  const seenTuples = new Set();
+
+  for (const c of connectors) {
+    const surface = (c && c.surface) || (c && c.command) || '<unknown>';
+
+    // Phase 198-04 (SPEC-2, Task 1): an MCP-tool connector (source:'mcp_tool')
+    // is governed by the hitl_shape/hitl_why dial, not reach_id/posture -- it
+    // legitimately carries reach_id:null/posture:null (normalizeMcpToolEntry
+    // above). The frozen-6/frozen-3 checks below are scoped to the
+    // reach/posture dial (commands/skills/agents); an MCP tool's hitl_shape is
+    // validated separately, advisory, by scripts/check-shape-declaration.cjs's
+    // MCP-tool enumeration -- never here, and never a hard --check failure.
+    const isMcpTool = c && c.source === 'mcp_tool';
+
+    // (1) frozen-6 reach.
+    if (!isMcpTool && REACH_IDS.indexOf(c && c.reach_id) === -1) {
+      errs.push(
+        'connector ' + surface + ' reach_id ' + (c && c.reach_id) +
+          ' not in frozen 6'
+      );
+    }
+
+    // (3) frozen-3 posture.
+    if (!isMcpTool && POSTURE_IDS.indexOf(c && c.posture) === -1) {
+      errs.push(
+        'connector ' + surface + ' posture ' + (c && c.posture) +
+          ' not in frozen 3'
+      );
+    }
+
+    // (2) WFL-01 resolver-resolution: a connector that declares a filing or a
+    // decision surface AND DECLARES A FRAMEWORK fires a command on APPROVE via
+    // framework resolution, so that framework MUST resolve through
+    // commandsForFramework(). A connector with framework:null declares no
+    // framework -- per CONNECTOR-CONTRACT.md section 4 (additive-degrade) it
+    // routes through the orchestrator with no framework and degrades to "run it
+    // manually" rather than fabricating a command. The minimal Part-8-safe
+    // memory-cortex reach (Phase 150, framework:null + filing:memory_event_only)
+    // is exactly this degrade case; gating the resolver check on a declared
+    // framework keeps the additive-degrade rule honest.
+    const declaresFramework = typeof c.framework === 'string' && c.framework;
+    const firesCommand =
+      ((typeof c.filing === 'string' && c.filing && c.filing !== 'none') ||
+        (typeof c.decision_surface === 'string' && c.decision_surface)) &&
+      declaresFramework;
+    if (firesCommand) {
+      const resolved = commandsForFramework(c && c.framework);
+      if (!Array.isArray(resolved) || resolved.length === 0) {
+        errs.push(
+          'connector ' + surface + ' framework ' +
+            JSON.stringify(c && c.framework) +
+            ' does not resolve via commandsForFramework (WFL-01)'
+        );
+      }
+    }
+
+    // (4) no duplicate (sensor, reach, sub_mode) tuple. score-innovation and
+    // whitespace share SENS-06 + context_block but differ in sub_mode (hsi vs
+    // whitespace) -- a legal distinct tuple. A genuine collision (same sensor +
+    // reach + sub_mode on two surfaces) fails.
+    const sensors = Array.isArray(c && c.sensor_triggers) ? c.sensor_triggers : [];
+    const reach = c && c.reach_id;
+    const subMode = c && c.sub_mode;
+    for (const sid of sensors) {
+      const tuple = sid + '|' + reach + '|' + subMode;
+      if (seenTuples.has(tuple)) {
+        errs.push(
+          'duplicate connector tuple (sensor,reach,sub_mode): ' + tuple +
+            ' (surface ' + surface + ')'
+        );
+      } else {
+        seenTuples.add(tuple);
+      }
+    }
+  }
+
+  return errs;
+}
+
+// ---------------------------------------------------------------------------
+// methodologyCommandsMissingConnector() -- the WARN nudge source. A command
+// whose frontmatter carries a `frameworks:` block (the methodology heuristic,
+// mirroring build-command-registry.cjs's kind/frameworks signal) but NO
+// `connector:` block has not opted into the spine. This is a STDERR WARNING
+// (opt-in nudge), NEVER a hard fail -- mirroring the missingServesJtbd WARNING
+// at build-command-registry.cjs lines 406-417.
+// ---------------------------------------------------------------------------
+function methodologyCommandsMissingConnector() {
+  const out = [];
+  let cmdFiles = [];
+  try {
+    cmdFiles = fs.readdirSync(COMMANDS_DIR).filter((f) => f.endsWith('.md')).sort();
+  } catch (_e) {
+    cmdFiles = [];
+  }
+  for (const f of cmdFiles) {
+    let fm;
+    try {
+      fm = parseConnectorFrontmatter(fs.readFileSync(path.join(COMMANDS_DIR, f), 'utf8'));
+    } catch (_e) {
+      continue;
+    }
+    const hasFrameworks =
+      Array.isArray(fm.frameworks) && fm.frameworks.length > 0;
+    const hasConnector =
+      fm.connector && typeof fm.connector === 'object' && !Array.isArray(fm.connector);
+    if (hasFrameworks && !hasConnector) {
+      out.push('/mos:' + f.replace(/\.md$/, ''));
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// --refresh-names: read-only brain.query for the FEEDS_INTO-linked name
+// slice -> rewrite data/framework-names.json. BUILD-TIME ONLY. The ONLY code
+// path in this file that touches the Brain, and it is read-only. brain-client
+// is required HERE -- inside this branch only. There is no top-level require of
+// brain-client; the generator and --check never load it.
+// ---------------------------------------------------------------------------
+async function refreshNames() {
+  let brain;
+  try {
+    brain = require(path.join(REPO_ROOT, 'lib', 'core', 'brain-client.cjs'));
+  } catch (_e) {
+    console.error('Brain client unavailable -- keeping the committed snapshot');
+    process.exit(0);
+    return;
+  }
+  if (!brain.isAvailable || !brain.isAvailable()) {
+    console.log('Brain unavailable -- keeping the committed snapshot');
+    process.exit(0);
+    return;
+  }
+
+  let result;
+  try {
+    result = await brain.query(FW_NAMES_CYPHER);
+  } catch (_e) {
+    console.log('Brain query failed -- keeping the committed snapshot');
+    process.exit(0);
+    return;
+  }
+  if (!result || !Array.isArray(result.records)) {
+    console.log('Brain returned no usable records -- keeping the committed snapshot');
+    process.exit(0);
+    return;
+  }
+
+  const names = [];
+  for (const rec of result.records) {
+    const v = rec && (rec.name !== undefined ? rec.name : rec['f.name']);
+    if (typeof v === 'string' && v.trim()) names.push(v.trim());
+  }
+  const deduped = Array.from(new Set(names)).sort((a, b) => a.localeCompare(b));
+  if (deduped.length === 0) {
+    console.log('Brain returned an empty name list -- keeping the committed snapshot');
+    process.exit(0);
+    return;
+  }
+
+  const curatedExtras = loadCuratedExtras().slice().sort((a, b) => a.localeCompare(b));
+  const snapshot = {
+    snapshot_note:
+      'FEEDS_INTO-linked :Framework names from the Brain (read-only build-time query). Refresh with: node scripts/build-command-registry.cjs --refresh-names',
+    snapshot_date: new Date().toISOString().slice(0, 10),
+    framework_names: deduped,
+    curated_extras_note:
+      'Legitimate :Framework node names that exist in the Brain but are not yet FEEDS_INTO-linked. Hand-curated. NOT junk nodes. The allowlist the registry validates against is framework_names UNION curated_extras.',
+    curated_extras: curatedExtras,
+  };
+  fs.mkdirSync(DATA_DIR, { recursive: true });
+  fs.writeFileSync(FW_NAMES_PATH, JSON.stringify(snapshot, null, 2) + '\n');
+  console.log('Wrote data/framework-names.json (' + deduped.length + ' FEEDS_INTO-linked names)');
+}
+
+// ---------------------------------------------------------------------------
+// Phase 245-01 (D-22 as CORRECTED by 245-RESEARCH.md F-3): the SENSOR-SIDE
+// SENS_PRIORITY completeness gate.
+//
+// WHAT IT PROVES: every sensor registered in lib/core/insight-sensors.cjs's
+// SENSOR_REGISTRY has a rank in the SENS_PRIORITY doctrine table, and the table
+// carries no phantom entry for a sensor that does not exist. A sensor with no
+// priority entry would silently degrade a same-reach collision back to
+// SENSOR_REGISTRY file order, which is exactly the accident Requirement 4
+// exists to abolish. So this fails the build CLOSED.
+//
+// WHY THIS DOES NOT READ `sensor_index`, AND MUST NOT BE "FIXED" TO DO SO.
+// The obvious-looking move is to gate on the `sensor_index` this same script
+// already builds a few hundred lines above. That is wrong, and it was measured
+// wrong, not guessed wrong (245-RESEARCH.md F-3, key set enumerated live):
+// `sensor_index` is derived from COMMAND FRONTMATTER (`sensor_triggers` on
+// commands/*.md), not from SENSOR_REGISTRY. It is a record of which commands
+// CLAIM a sensor, not of which sensors EXIST. It currently has 13 keys, it
+// already omits SENS-10, SENS-11, SENS-12 and SENS-16 (three of which are
+// among the 12 sensors that can fire `context_block`, i.e. exactly the
+// colliders Requirement 4 is about), and it contains ids with no registered
+// implementation behind them. A completeness gate built on it would report
+// green while silently exempting the sensors in scope. The two sides are
+// allowed to differ; only the SENSOR side answers "does every sensor have a
+// rank". Leave this reading SENSOR_REGISTRY_IDS.
+//
+// This gate adds NO key to data/connector-registry.json and does not touch the
+// sensor_index build: the generated registry must stay byte-identical.
+//
+// Canon Part 8: both requires are pure LOCAL modules, zero Brain/network.
+// ---------------------------------------------------------------------------
+function sensorPriorityCompletenessErrors() {
+  const errs = [];
+  let SENSOR_REGISTRY;
+  let SENSOR_REGISTRY_IDS;
+  let SENS_PRIORITY;
+  try {
+    const sensors = require(path.join(REPO_ROOT, 'lib', 'core', 'insight-sensors.cjs'));
+    const priority = require(path.join(REPO_ROOT, 'lib', 'core', 'sensors', 'sensor-priority.cjs'));
+    SENSOR_REGISTRY = sensors.SENSOR_REGISTRY;
+    SENSOR_REGISTRY_IDS = sensors.SENSOR_REGISTRY_IDS;
+    SENS_PRIORITY = priority.SENS_PRIORITY;
+  } catch (e) {
+    errs.push(
+      'SENSOR PRIORITY GATE: could not load the sensor modules: ' +
+        (e && e.message ? e.message : String(e))
+    );
+    return errs;
+  }
+
+  if (!Array.isArray(SENSOR_REGISTRY) || !Array.isArray(SENSOR_REGISTRY_IDS) || !Array.isArray(SENS_PRIORITY)) {
+    errs.push('SENSOR PRIORITY GATE: SENSOR_REGISTRY, SENSOR_REGISTRY_IDS and SENS_PRIORITY must all be arrays');
+    return errs;
+  }
+
+  // (1) The two parallel arrays must stay index-parallel, so an id read by
+  // registry position in dispatchSensors is always the right sensor's id.
+  if (SENSOR_REGISTRY.length !== SENSOR_REGISTRY_IDS.length) {
+    errs.push(
+      'SENSOR PRIORITY GATE: SENSOR_REGISTRY (' + SENSOR_REGISTRY.length + ' sensors) and ' +
+        'SENSOR_REGISTRY_IDS (' + SENSOR_REGISTRY_IDS.length + ' ids) have diverged. ' +
+        'A new sensor must be appended to BOTH arrays, in the same position.'
+    );
+  }
+
+  // (2) Every registered sensor must have a doctrine rank.
+  const missingFromPriority = SENSOR_REGISTRY_IDS.filter((id) => SENS_PRIORITY.indexOf(id) === -1);
+  if (missingFromPriority.length) {
+    errs.push(
+      'SENSOR PRIORITY GATE: registered sensor(s) with NO SENS_PRIORITY entry: ' +
+        missingFromPriority.join(', ') +
+        '. Add each to the ordered table in lib/core/sensors/sensor-priority.cjs ' +
+        '(its header carries the three placement rules).'
+    );
+  }
+
+  // (3) The table must carry no phantom entry for a sensor that is not
+  // registered, so the doctrine cannot quietly outlive the code.
+  const missingFromRegistry = SENS_PRIORITY.filter((id) => SENSOR_REGISTRY_IDS.indexOf(id) === -1);
+  if (missingFromRegistry.length) {
+    errs.push(
+      'SENSOR PRIORITY GATE: SENS_PRIORITY entr(ies) with NO registered sensor: ' +
+        missingFromRegistry.join(', ') +
+        '. Remove each from lib/core/sensors/sensor-priority.cjs, or register the sensor ' +
+        'in SENSOR_REGISTRY + SENSOR_REGISTRY_IDS.'
+    );
+  }
+
+  return errs;
+}
+
+// ---------------------------------------------------------------------------
+// main()
+// ---------------------------------------------------------------------------
+function main() {
+  const argv = process.argv.slice(2);
+
+  if (argv.includes('--refresh-names')) {
+    refreshNames().catch((e) => {
+      console.error('refresh-names error: ' + (e && e.message ? e.message : String(e)));
+      process.exit(1);
+    });
+    return;
+  }
+
+  const reg = buildRegistry();
+  const report = coverageReport();
+  const errs = [];
+  if (reg._unresolved.length) {
+    const list = reg._unresolved
+      .map((u) => u.surface + ' -> "' + u.framework + '"')
+      .join(', ');
+    errs.push('Unresolvable frameworks (not in data/framework-names.json): ' + list);
+  }
+  // R1 build error: any surface that declares excluded:true with no reason
+  // fails CLOSED on BOTH the default write run and --check (D-172-a).
+  for (const e of report.errors) errs.push(e);
+
+  if (argv.includes('--check')) {
+    const next = serializeRegistry(reg);
+    const onDisk = fs.existsSync(REGISTRY_PATH) ? fs.readFileSync(REGISTRY_PATH, 'utf8') : '';
+    if (onDisk !== next) {
+      errs.push('data/connector-registry.json is STALE. Run: node scripts/build-connector-registry.cjs');
+    }
+
+    // The coverage ledger STALE byte-compare (same discipline as the registry).
+    // Regenerate the ledger in memory and fail if the on-disk ledger drifts.
+    const nextLedger = serializeLedger(report);
+    const onDiskLedger = fs.existsSync(LEDGER_PATH) ? fs.readFileSync(LEDGER_PATH, 'utf8') : '';
+    if (onDiskLedger !== nextLedger) {
+      errs.push('data/connector-coverage-ledger.json is STALE. Run: node scripts/build-connector-registry.cjs');
+    }
+
+    // Phase 198-04 (SPEC-2, Task 1): data/mcp-tool-connectors.json STALE
+    // byte-compare -- same discipline as the registry + ledger above.
+    const nextMcp = serializeMcpToolRegistry(reg._mcpToolRegistry);
+    const onDiskMcp = fs.existsSync(MCP_CONNECTORS_PATH) ? fs.readFileSync(MCP_CONNECTORS_PATH, 'utf8') : '';
+    if (onDiskMcp !== nextMcp) {
+      errs.push('data/mcp-tool-connectors.json is STALE. Run: node scripts/build-connector-registry.cjs');
+    }
+
+    // Phase 245-01 (D-22 corrected by F-3): the sensor-side SENS_PRIORITY
+    // completeness gate. Fails CLOSED when a registered sensor has no doctrine
+    // rank. Reads SENSOR_REGISTRY_IDS, NEVER sensor_index -- see the function
+    // header for why that distinction is load-bearing.
+    for (const e of sensorPriorityCompletenessErrors()) errs.push(e);
+
+    // The four CONN-03 connector validations (frozen-6 reach, frozen-3 posture,
+    // WFL-01 resolver-resolution framework, no (sensor,reach,sub_mode) tuple
+    // collision). Any failure is a hard exit 1.
+    for (const e of validateConnectors(reg)) errs.push(e);
+
+    // The R9 gap HARD-FAIL (Canon Part 11 R2/R9 / INV-10 step 3; the
+    // navigator-approved "full flip" 2026-06-23). A `gap` surface (neither WIRED
+    // via a connector: block NOR EXCLUDED via connector:{excluded:true,reason})
+    // now makes --check exit non-zero -- it no longer merely warns. The flip is
+    // safe because Plan 172-16 wired/excluded the baseline (counts.gap === 0), so
+    // a clean repo stays exit 0; only an accidental-dark surface trips it. Each
+    // gap names itself + the recovery line (wire it or exclude it with a reason).
+    const gaps = report.surfaces.filter((s) => s.state === 'gap');
+    for (const g of gaps) {
+      errs.push(
+        'GAP: surface "' + g.surface + '" (' + g.source + ') is neither WIRED ' +
+          '(a connector: block) nor EXCLUDED (connector:{excluded:true,reason}). ' +
+          'Wire it or exclude it with a reason. ' +
+          'Run: node scripts/build-connector-registry.cjs'
+      );
+    }
+
+    if (errs.length) {
+      console.error(errs.join('\n'));
+      console.error('Recovery: fix the connector frontmatter (or run --refresh-names), then regenerate: node scripts/build-connector-registry.cjs');
+      process.exit(1);
+    }
+
+    // The WARN nudge (stderr, NOT exit 1): a methodology command (frameworks:
+    // block) that has not opted into the spine (no connector: block). Opt-in,
+    // never a hard block. Mirrors missingServesJtbd in build-command-registry.
+    const missingConnector = methodologyCommandsMissingConnector();
+    if (missingConnector.length > 0) {
+      const preview = missingConnector.slice(0, 5).join(', ');
+      const ellipsis = missingConnector.length > 5 ? '...' : '';
+      process.stderr.write(
+        '[build-connector-registry] WARNING: ' +
+          missingConnector.length +
+          ' methodology command(s) ship a frameworks: block but no connector: block (opt-in nudge): ' +
+          preview +
+          ellipsis +
+          '\n'
+      );
+    }
+
+    // (The R9 gap check is now a HARD FAIL folded into `errs` above, before this
+    // success path; a gap surface exits non-zero. Canon Part 11 R2/R9.)
+
+    console.log('connector-registry: OK');
+    return;
+  }
+
+  // Default: write the registry, refusing on any unresolvable framework.
+  if (errs.length) {
+    console.error(errs.join('\n'));
+    console.error('Recovery: fix the connector frontmatter (or run --refresh-names), then re-run: node scripts/build-connector-registry.cjs');
+    process.exit(1);
+  }
+  fs.mkdirSync(DATA_DIR, { recursive: true });
+  fs.writeFileSync(REGISTRY_PATH, serializeRegistry(reg));
+  console.log('Wrote data/connector-registry.json (' + reg.connectors.length + ' connectors)');
+  // Emit the wired-XOR-excluded coverage ledger alongside the registry.
+  fs.writeFileSync(LEDGER_PATH, serializeLedger(report));
+  console.log(
+    'Wrote data/connector-coverage-ledger.json (' +
+      report.counts.wired + ' wired, ' +
+      report.counts.excluded + ' excluded, ' +
+      report.counts.gap + ' gap)'
+  );
+  // Phase 198-04 (SPEC-2, Task 1): emit the MCP-tool projection alongside the
+  // registry + ledger, generated from the SAME discovery pass folded into
+  // reg.connectors above.
+  fs.writeFileSync(MCP_CONNECTORS_PATH, serializeMcpToolRegistry(reg._mcpToolRegistry));
+  console.log(
+    'Wrote data/mcp-tool-connectors.json (' + reg._mcpToolRegistry.connectors.length + ' MCP tool connectors)'
+  );
+}
+
+if (require.main === module) {
+  main();
+} else {
+  module.exports = {
+    parseConnectorFrontmatter,
+    buildRegistry,
+    serializeRegistry,
+    validateConnectors,
+    methodologyCommandsMissingConnector,
+    classifySurface,
+    classifySurfaceClass,
+    coverageReport,
+    serializeLedger,
+    listSourceFiles,
+    FOUR_CLASSES,
+    SURFACE_CLASS_ENUM,
+    CLASS_UTILITY_EXCLUDED,
+    // Phase 235-02 (CIRS-02): the MCP-tool-file census/probe pair + the additive
+    // class constant, exported so tests/test-235-seam-liveness-mcp-coverage.cjs
+    // can drive them directly (including the synthetic claimed-source override)
+    // without spawning a subprocess.
+    CLASS_MCP_TOOL,
+    listMcpToolClaimedSources,
+    listMcpToolFileHealth,
+    // Phase 198-04 (SPEC-2, Task 1): the MCP-tool discovery/build/serialize
+    // trio, exported so scripts/check-shape-declaration.cjs can mirror the
+    // SAME discovery into its advisory hitl_shape enumeration without
+    // re-walking lib/mcp/tools/ a second way (Canon Part 7).
+    listMcpToolConnectorDescriptors,
+    normalizeMcpToolEntry,
+    buildMcpToolRegistry,
+    serializeMcpToolRegistry,
+  };
+}