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

package/scripts/build-render-coverage.cjs

@@ -0,0 +1,637 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Phase 178-01 - the SEPARATE render-coverage registry generator + drift tripwire.
+ *
+ * Implements: C-1 (registry-driven, DERIVED by an exhaustive AST/grep walk, NOT a
+ * hand list), D-178-02 (Part 7 reuse of the build-connector-registry.cjs walk +
+ * --check pattern; this is a SIBLING, it does NOT edit that file or its ledger),
+ * D-178-04 (additive only: mints a NEW local artifact; touches NO existing ledger,
+ * NO reach/posture/edge/node, NO Part 3 frozen contract), D-178-07 (residual
+ * honesty: the registry records the render PLANE only -- it does not claim to cover
+ * the terminal agent-honored tool-call, R-1).
+ *
+ * THE TWO PLANES (per docs/CANON-PART-11-RENDER-TWIN-PROPOSAL.md "Design consequence
+ * (separate render registry - CORRECTED)"). Plane 1 is INVOCATION (does Larry reach
+ * the right thing -- CIRS R2/R9, born-wired in data/connector-coverage-ledger.json,
+ * keyed on MARKDOWN surfaces commands/skills/agents). Plane 2 is RENDER (does the
+ * reached gate FIRE its card -- this phase). The render entry points are `.cjs` call
+ * sites in lib/ and scripts/ (the 14 pickShape callers + the 2 renderDial callers),
+ * and most have NO owning markdown surface, so co-residency on the connector ledger
+ * is undefined for them. The corrected design is a DEDICATED render-coverage registry
+ * (data/render-coverage-registry.json) keyed on those `.cjs` entry points.
+ *
+ * The connector ledger (data/connector-coverage-ledger.json) and its wired/excluded/
+ * gap counts are NEVER touched by this generator (separate keyspace). R-3
+ * (registry-completeness drift) is dissolved NOT by co-residency but by the
+ * EXHAUSTIVENESS FLOOR test (tests/test-render-registry-exhaustive.cjs): a render
+ * entry point present in code but ABSENT from the registry FAILS the build, because
+ * the walk re-derives the entry set from the live tree on every --check.
+ *
+ * Canon Part 8 (The Graph Boundary): the generator stays LOCAL-only. It reads source
+ * files and writes the local registry. It makes ZERO Brain reads/writes and ZERO
+ * network calls; the registry carries only generic machinery metadata (entry-point
+ * paths + the call-site kind + a two-state disposition), NEVER user data. The
+ * generator opens no remote wire and loads no Brain module -- the Part-8 grep gate
+ * over this file finds zero network or Brain symbols.
+ *
+ * Usage:
+ *   node scripts/build-render-coverage.cjs
+ *       walk the render entry points -> write data/render-coverage-registry.json ;
+ *       exit 1 on a render-only-excluded entry with no reason
+ *   node scripts/build-render-coverage.cjs --check
+ *       re-derive the walk in memory ; exit 1 if the on-disk JSON is STALE (a new
+ *       render entry point appeared in code but is not in the registry, OR the
+ *       registry drifted) ; print a one-line recovery command in stderr
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// Phase 209-03 (B3): the .md keyspace's wired predicate reuses the B1 stamp
+// script's OWN getHitlShape/grantTool/STAMP_MARKER (Canon Part 7) - one
+// shared definition site, never a second literal (T-209-10, the same
+// invariant B2 enforces in check-shape-declaration.cjs).
+const stampFiring = require('./stamp-firing-block.cjs');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+const DATA_DIR = path.join(REPO_ROOT, 'data');
+const REGISTRY_PATH = path.join(DATA_DIR, 'render-coverage-registry.json');
+
+// The two scopes the render walk enumerates. *.test.cjs files are excluded (they
+// are not runtime render entry points). The dispatcher self-call IS counted (it is
+// a real call site reached at runtime).
+const WALK_SCOPES = ['lib', 'scripts'];
+
+// The dispatcher whose F_SUBSHAPES array + F.7-dial branch the walk parses to
+// confirm the render-shape wiring exists (the AST/grep walk over the dispatcher
+// branches; GA-1). Pinned to the SINGLE source so the registry can never drift from
+// the live dispatch vocabulary.
+const DISPATCHER_REL = path.join('lib', 'hmi', 'selector-dispatcher.cjs');
+
+const GENERATED_NOTE =
+  'GENERATED by scripts/build-render-coverage.cjs - do not edit by hand. The SEPARATE render-coverage registry, now THREE keyspaces: (1) every .cjs render ENTRY POINT (pickShape / renderDial call site) classified card-emission or render-only-excluded (Canon Part 11 render twin; Phase 178); (2) every commands/*.md hitl_shape-declaring SURFACE classified { declared_shape, wired } (the "declared implies rendered" closure one plane up; Phase 209-03 B3); (3) every skills/*/SKILL.md hitl_shape-declaring SURFACE classified { declared_shape, wired } (the intern-w1-mode-gate-skip fix: a skill-declared Decision Gate is now PRIMARY-detectable, closing the gap where skills/*/SKILL.md was never walked). The connector ledger (data/connector-coverage-ledger.json) is a DIFFERENT keyspace and is NEVER touched by this generator.';
+
+// ---------------------------------------------------------------------------
+// The render-only-EXCLUDED table (mirrors build-orchestration-projection.cjs's
+// EXCLUDED_COMMANDS frozen reason-map idiom; the T-172-06 "EXCLUDED REQUIRES a
+// reason" tampering mitigation). A render entry point listed HERE is classified
+// 'render-only-excluded' and the value IS its required reason, so an excluded entry
+// can never be silently both-excluded-and-reasonless. The key is the entry-point
+// identity string "<entry>|<kind>".
+//
+// CURRENTLY EMPTY by design: every one of the 16 live render entry points routes
+// through the SEED-020 card-emission door (verified seams below), so none is
+// render-only-excluded today. The table is the structural slot that lets a FUTURE
+// render-only call site (a renderer that never reaches a gate) declare itself
+// excluded-with-reason rather than silently passing -- the same two-state ledger
+// CIRS uses for invocation. An entry added here with an empty/blank reason surfaces
+// a build error (excludeErrors), failing BOTH the default write and --check closed.
+// ---------------------------------------------------------------------------
+const RENDER_ONLY_EXCLUDED = Object.freeze({
+  // '<entry>|<kind>': 'the documented reason this render call site never reaches a Decision Gate',
+});
+
+// ---------------------------------------------------------------------------
+// listSourceFiles(scopeDirAbs) -- recursively enumerate every .cjs file under a
+// scope dir, EXCLUDING *.test.cjs, deterministically sorted. Mirrors the
+// build-connector-registry.cjs listSourceFiles idiom (readdir + filter + sort +
+// try/catch-yields-[] when the dir is absent), extended to recurse into
+// subdirectories because the render entry points live at arbitrary depth (lib/agents,
+// lib/core/breakthrough, lib/hmi, lib/render, lib/workflow, scripts).
+// ---------------------------------------------------------------------------
+function listCjsFiles(scopeDirAbs) {
+  const out = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(scopeDirAbs, { withFileTypes: true });
+  } catch (_e) {
+    return out;
+  }
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  for (const e of entries) {
+    const abs = path.join(scopeDirAbs, e.name);
+    if (e.isDirectory()) {
+      out.push(...listCjsFiles(abs));
+    } else if (e.isFile() && e.name.endsWith('.cjs') && !e.name.endsWith('.test.cjs')) {
+      out.push(abs);
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// parseDispatcherShapes(dispatcherSrc) -- the AST/grep walk over the dispatcher.
+// Extracts the F_SUBSHAPES array (selector-dispatcher.cjs:341) and confirms the
+// F.7-dial dispatch branch (:755) exists. Returns { subShapes: [...], hasDialBranch }.
+// This is the structural proof that the render-shape vocabulary the registry records
+// is the SAME vocabulary the dispatcher routes; a new F.* branch added to the
+// dispatcher changes this parse and so changes the derived registry (R-3 floor).
+// Pure string parse, zero I/O beyond the single read in the caller.
+// ---------------------------------------------------------------------------
+function parseDispatcherShapes(dispatcherSrc) {
+  const subShapes = [];
+  // F_SUBSHAPES = ['F.0', 'F.1', ..., 'F.7-dial'];
+  const m = /F_SUBSHAPES\s*=\s*\[([^\]]*)\]/.exec(dispatcherSrc);
+  if (m) {
+    const inner = m[1];
+    const re = /['"]([^'"]+)['"]/g;
+    let mm;
+    while ((mm = re.exec(inner)) !== null) {
+      subShapes.push(mm[1]);
+    }
+  }
+  // The F.7-dial branch: `requestedShape === 'F.7-dial'`.
+  const hasDialBranch = /requestedShape\s*===\s*['"]F\.7-dial['"]/.test(dispatcherSrc);
+  return { subShapes, hasDialBranch };
+}
+
+// The walk's OWN file. The registry generator is uniquely the file that MUST carry
+// the literal `pickShape(` / `renderDial(` tokens (the call-site regexes + the prose
+// that documents them); it is NOT a render entry point. A generator never enumerates
+// itself -- exactly as build-connector-registry.cjs is absent from its own connector
+// ledger. This self-reference exclusion is the ONLY entry-point exclusion; it is
+// documented, not a hand-maintained allow/deny list, and a NEW real call site in any
+// OTHER file is still caught by the walk (the R-3 exhaustiveness floor stays intact).
+const SELF_BASENAME = 'build-render-coverage.cjs';
+
+// hasCallSite(src, token) -- TRUE when `src` contains a real `<token>(` call site on
+// a NON-COMMENT, NON-REGEX-LITERAL line. A line that is a `//` or `*` comment is
+// ignored (so a doc-mention never mints a phantom entry), and the `\b` word boundary
+// + a deny of an immediately-preceding `\` (the regex-literal `\bpickShape` form)
+// keeps a pattern literal from counting. A real invocation -- `pickShape(`,
+// `dispatcher.pickShape(`, `presenter.renderDial(` -- matches. This is what makes the
+// FLOOR test (Task 2) valid: a synthesized NEW real call site trips the walk; a mere
+// textual mention does not.
+function hasCallSite(src, token) {
+  const callRe = new RegExp('(^|[^\\\\A-Za-z0-9_.])' + token + '\\s*\\(');
+  const dotCallRe = new RegExp('\\.' + token + '\\s*\\(');
+  for (const rawLine of src.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.startsWith('//') || line.startsWith('*') || line.startsWith('/*')) continue;
+    // Strip a trailing line comment so an inline `// pickShape(` note never counts.
+    const code = rawLine.replace(/\/\/.*$/, '');
+    if (dotCallRe.test(code) || callRe.test(code)) return true;
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------------------
+// walkRenderEntryPoints() -- the EXHAUSTIVE render-entry-point walk (C-1, R-3).
+// Greps every .cjs file under lib/ and scripts/ (excluding *.test.cjs AND the
+// generator's own file) for a real `pickShape(` call site and a real `renderDial(`
+// call site (hasCallSite ignores comment/regex-literal mentions). Each MATCHED file
+// yields one entry-point record PER call-site KIND it contains (a file calling BOTH
+// pickShape and renderDial -- e.g. scripts/intent-classifier.cjs -- yields TWO
+// records, one per kind, because they are two distinct render entry points). Returns
+// the records sorted deterministically by (entry, kind). Pure: reads source files
+// only; ZERO Brain, ZERO network (Part 8).
+// ---------------------------------------------------------------------------
+function walkRenderEntryPoints() {
+  const records = [];
+
+  for (const scope of WALK_SCOPES) {
+    const scopeAbs = path.join(REPO_ROOT, scope);
+    for (const fileAbs of listCjsFiles(scopeAbs)) {
+      if (path.basename(fileAbs) === SELF_BASENAME) continue;
+      let src;
+      try {
+        src = fs.readFileSync(fileAbs, 'utf8');
+      } catch (_e) {
+        continue;
+      }
+      const rel = path.relative(REPO_ROOT, fileAbs).split(path.sep).join('/');
+      if (hasCallSite(src, 'pickShape')) {
+        records.push({ entry: rel, kind: 'pickShape' });
+      }
+      if (hasCallSite(src, 'renderDial')) {
+        records.push({ entry: rel, kind: 'renderDial' });
+      }
+    }
+  }
+
+  records.sort((a, b) => {
+    if (a.entry !== b.entry) return a.entry.localeCompare(b.entry);
+    return a.kind.localeCompare(b.kind);
+  });
+  return records;
+}
+
+// ---------------------------------------------------------------------------
+// classifyRenderCoverage(rec) -- the two-state disposition derivation per entry.
+// Returns { render_coverage, reason?, note?, error? }.
+//
+//   render-only-excluded : the entry-point identity "<entry>|<kind>" is in the
+//                          RENDER_ONLY_EXCLUDED table (a render call site that never
+//                          reaches a Decision Gate); the table value IS the required
+//                          reason. A table entry with a blank reason yields an
+//                          `error` so the build fails closed (D-178-07 / T-172-06).
+//   card-emission        : the entry routes through the SEED-020 card-emission door.
+//                          For a pickShape call site that is pickShape's isFShape
+//                          host-append (selector-dispatcher.cjs:931-933, which appends
+//                          the AskUserQuestion marker to ANY F* shape, including the
+//                          dispatcher self-call). For a renderDial call site it is the
+//                          150.5 engine-arm thread (the dial output's
+//                          askuserquestion_marker is concatenated into the turn block;
+//                          the F.7-dial shape -- starting with 'F' -- is host-appended).
+// ---------------------------------------------------------------------------
+function classifyRenderCoverage(rec) {
+  const id = rec.entry + '|' + rec.kind;
+  if (Object.prototype.hasOwnProperty.call(RENDER_ONLY_EXCLUDED, id)) {
+    const reason = RENDER_ONLY_EXCLUDED[id];
+    const out = { render_coverage: 'render-only-excluded' };
+    if (typeof reason === 'string' && reason.trim().length > 0) {
+      out.reason = reason.trim();
+    } else {
+      out.error =
+        'render entry ' + id +
+        ' is render-only-excluded but carries no reason (D-178-07 / T-172-06: no surface excluded by accident)';
+    }
+    return out;
+  }
+
+  // card-emission. Record WHY it is covered (the door it routes through). The
+  // F.7-dial / dial-selector entry is host-appended because the renderDialShape
+  // return carries shape 'F.7-dial' which starts with 'F', so pickShape's isFShape
+  // branch appends the marker -- the registry records the reason, it does not demand
+  // an in-renderDialShape marker assignment.
+  const out = { render_coverage: 'card-emission' };
+  if (rec.kind === 'renderDial') {
+    out.note =
+      'host-appended: the dial render carries shape F.7-dial (starts with F), so pickShape isFShape appends the AskUserQuestion marker; the renderDial output is threaded into the turn block via the 150.5 engine-arm seam';
+  } else if (rec.entry === DISPATCHER_REL.split(path.sep).join('/')) {
+    out.note =
+      'dispatcher self-call: pickShape is defined and invoked here; the isFShape host-append (selector-dispatcher.cjs appendAskUserQuestionTrailer) mints the marker on every successful Shape F.* return';
+  } else {
+    out.note =
+      'routes through pickShape isFShape host-append (the SEED-020 single construction door): a Shape F.* return gets the AskUserQuestion marker appended by the dispatcher';
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// The md-keyspace render-only-EXCLUDED table (mirrors RENDER_ONLY_EXCLUDED above,
+// the declared-implies-rendered escape hatch one plane up - Phase 209-03 B3).
+// EMPTY by design at ship (the B1 stamp wired every live declaring command);
+// the escape hatch exists structurally for a future exempt surface. An entry
+// here requires a non-empty reason or the build fails closed, exactly like
+// the .cjs table.
+// ---------------------------------------------------------------------------
+const MD_RENDER_ONLY_EXCLUDED = Object.freeze({
+  // 'commands/<name>.md': 'the documented reason this declaring command is exempt',
+});
+
+// ---------------------------------------------------------------------------
+// stripFrontmatter(content) -- return the body text after the closing `---`,
+// or the whole string when no frontmatter block is found.
+// ---------------------------------------------------------------------------
+function stripFrontmatter(content) {
+  const m = /^---\r?\n[\s\S]*?\r?\n---/.exec(content);
+  return m ? content.slice(m[0].length) : content;
+}
+
+// ---------------------------------------------------------------------------
+// buildMdKeyspace(opts) -- Phase 209-03 (B3). The PARALLEL .md keyspace walk
+// over commands/*.md (opts.rootDir defaults to REPO_ROOT, so a fixture dir can
+// be walked without touching the live tree). For every hitl_shape-declaring
+// command (excluding 'none'), returns { surface, declared_shape, wired },
+// where wired = (body carries stampFiring.STAMP_MARKER OR mentions
+// 'AskUserQuestion') AND (the allowed-tools grant predicate is satisfied -
+// reused via stampFiring.grantTool: it returns the content UNCHANGED exactly
+// when the grant is either absent-and-unrestricted or already present, and
+// CHANGED only when a restrictive list is missing the grant, i.e. NOT wired).
+// A command listed in MD_RENDER_ONLY_EXCLUDED with a non-empty reason is
+// exempt from the wired half (mirrors the .cjs render-only-excluded model).
+// Keep the .cjs walk and its entries byte-identical; this function is
+// additive, never repurposing listCjsFiles.
+// ---------------------------------------------------------------------------
+function buildMdKeyspace(opts) {
+  opts = opts || {};
+  const rootDir = opts.rootDir || REPO_ROOT;
+  const dir = path.join(rootDir, 'commands');
+
+  let files = [];
+  try {
+    files = fs.readdirSync(dir).filter((f) => f.endsWith('.md')).sort();
+  } catch (_e) {
+    files = [];
+  }
+
+  const entries = [];
+  for (const f of files) {
+    const abs = path.join(dir, f);
+    let content;
+    try {
+      content = fs.readFileSync(abs, 'utf8');
+    } catch (_e) {
+      continue;
+    }
+    const shape = stampFiring.parseShape(content);
+    if (!shape || shape === 'none') continue;
+
+    const surface = 'commands/' + f;
+    const body = stripFrontmatter(content);
+    const bodyWired = body.indexOf(stampFiring.STAMP_MARKER) !== -1 || body.indexOf('AskUserQuestion') !== -1;
+    const toolWired = stampFiring.grantTool(content) === content;
+    const wired = bodyWired && toolWired;
+
+    const entry = { surface, declared_shape: shape, wired };
+    if (Object.prototype.hasOwnProperty.call(MD_RENDER_ONLY_EXCLUDED, surface)) {
+      const reason = MD_RENDER_ONLY_EXCLUDED[surface];
+      if (typeof reason === 'string' && reason.trim().length > 0) {
+        entry.excluded = true;
+        entry.reason = reason.trim();
+      }
+    }
+    entries.push(entry);
+  }
+
+  return entries;
+}
+
+// ---------------------------------------------------------------------------
+// The skill-keyspace render-only-EXCLUDED table (mirrors MD_RENDER_ONLY_EXCLUDED
+// one plane up - the THIRD keyspace, the intern-w1-mode-gate-skip fix). EMPTY by
+// design at ship; the escape hatch exists structurally for a future skill that is
+// BOTH a genuine hitl_shape-declaring surface AND legitimately render-only (rare:
+// a skill with a real hitl_shape has a fork by definition -- see
+// check-shape-declaration.cjs's hasShape-and-excluded contradiction predicate,
+// the doctrine-level guard against a skill claiming BOTH a fork and the no-fork
+// connector.excluded:true exemption at once). An entry here requires a
+// non-empty reason or the build fails closed, exactly like the .cjs and
+// commands/*.md tables.
+// ---------------------------------------------------------------------------
+const SKILL_RENDER_ONLY_EXCLUDED = Object.freeze({
+  // Merge-time population (2026-07-11/12, phases/217 + intern-w1-mode-gate-skip):
+  // extending PRIMARY detection to skills/*/SKILL.md surfaced 5 previously-invisible
+  // unwired declarations. 3 of the 5 (client-discovery-interview, mullins-scaffold,
+  // mva-pipeline) declare a real hitl_shape/hitl_why with no exemption claimed and no
+  // self-contradicting language -- they were genuinely missing the firing-block and
+  // have been stamped (see their SKILL.md files), not added here. The other 2 are
+  // legitimate render-only exceptions, each already admitting in its OWN hitl_why
+  // that it never fires a fork of its own:
+  //   - intelligence-orchestrator already declares `connector.excluded:true` with a
+  //     documented reason ("the ONE spine that READS the connector registry and
+  //     dispatches reaches; the orchestrator itself is the dispatcher, never a
+  //     dispatched reach") -- its hitl_shape:"F.0" describes the gate every
+  //     DISPATCHED reach passes through downstream, not a fork of its own.
+  //   - mos-deck-engine's own hitl_why states verbatim: "Deprecated redirect to
+  //     /mos:deck; inherits /mos:deck's F.1 Next Move gate ... never introduces a
+  //     separate fork of its own." A deprecated pure-redirect inheriting the
+  //     referenced command's gate is exactly the Part 11 exclusion doctrine's
+  //     intended case ("exempt via connector.excluded:true + reason, never via a
+  //     fork it does not have") -- its frontmatter had not yet been updated to
+  //     declare that exclusion explicitly; this table entry mirrors its own
+  //     admitted reasoning until that frontmatter update lands.
+  // buildSkillKeyspace() does not yet propagate connector.excluded/reason onto skill
+  // registry entries the way buildMdKeyspace() does for commands (a real gap this
+  // table's own original header comment anticipated) -- tracked as a follow-up, not
+  // fixed in this pass (see .planning/todos/pending/).
+  'skills/intelligence-orchestrator/SKILL.md': 'Ambient always-on infra. The ONE spine that READS the connector registry and dispatches reaches; the orchestrator itself is the dispatcher, never a dispatched reach, so it is excluded by construction (mirrors its own connector.excluded reason verbatim).',
+  'skills/mos-deck-engine/SKILL.md': 'Deprecated redirect to /mos:deck; inherits /mos:deck\'s F.1 Next Move gate at the close of the Feynman pipeline stages, never introduces a separate fork of its own (mirrors its own hitl_why verbatim).',
+});
+
+// ---------------------------------------------------------------------------
+// buildSkillKeyspace(opts) -- the intern-w1-mode-gate-skip fix (RCA gap 1). The
+// THIRD, ADDITIVE keyspace walk over skills/*/SKILL.md (opts.rootDir defaults to
+// REPO_ROOT, so a fixture dir can be walked without touching the live tree).
+// Mirrors buildMdKeyspace() exactly (same wired predicate: body carries
+// stampFiring.STAMP_MARKER OR mentions 'AskUserQuestion', AND the allowed-tools
+// grant predicate is satisfied), extended to the skills/<name>/SKILL.md shape
+// rather than a flat commands/<name>.md file.
+//
+// Before this fix, a skill-declared hitl_shape (e.g.
+// skills/conversation-mode/SKILL.md's self-declared "F.1") could NEVER register
+// in data/render-coverage-registry.json, because buildMdKeyspace() enumerates
+// only commands/*.md -- PRIMARY detection was structurally blind to every
+// skill-declared Decision Gate, regardless of runtime behavior. A skill listed
+// in SKILL_RENDER_ONLY_EXCLUDED with a non-empty reason is exempt from the
+// wired half (mirrors the .cjs / commands render-only-excluded model). Keep the
+// .cjs and commands/*.md walks byte-identical; this function is purely
+// additive, never repurposing buildMdKeyspace.
+// ---------------------------------------------------------------------------
+function buildSkillKeyspace(opts) {
+  opts = opts || {};
+  const rootDir = opts.rootDir || REPO_ROOT;
+  const dir = path.join(rootDir, 'skills');
+
+  let dirNames = [];
+  try {
+    dirNames = fs
+      .readdirSync(dir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name)
+      .sort();
+  } catch (_e) {
+    dirNames = [];
+  }
+
+  const entries = [];
+  for (const d of dirNames) {
+    const abs = path.join(dir, d, 'SKILL.md');
+    let content;
+    try {
+      content = fs.readFileSync(abs, 'utf8');
+    } catch (_e) {
+      continue;
+    }
+    const shape = stampFiring.parseShape(content);
+    if (!shape || shape === 'none') continue;
+
+    const surface = 'skills/' + d + '/SKILL.md';
+    const body = stripFrontmatter(content);
+    const bodyWired = body.indexOf(stampFiring.STAMP_MARKER) !== -1 || body.indexOf('AskUserQuestion') !== -1;
+    const toolWired = stampFiring.grantTool(content) === content;
+    const wired = bodyWired && toolWired;
+
+    const entry = { surface, declared_shape: shape, wired };
+    if (Object.prototype.hasOwnProperty.call(SKILL_RENDER_ONLY_EXCLUDED, surface)) {
+      const reason = SKILL_RENDER_ONLY_EXCLUDED[surface];
+      if (typeof reason === 'string' && reason.trim().length > 0) {
+        entry.excluded = true;
+        entry.reason = reason.trim();
+      }
+    }
+    entries.push(entry);
+  }
+
+  return entries;
+}
+
+// ---------------------------------------------------------------------------
+// buildRegistry() -- assemble the derived registry. Walks the render entry points,
+// classifies each, derives the dispatcher shape vocabulary (the structural anchor),
+// and computes the render_counts block. Returns the registry object PLUS a
+// non-serialized `_excludeErrors` field (callers strip it before writing and fail on
+// it). Pure: zero Brain, zero network.
+// ---------------------------------------------------------------------------
+function buildRegistry() {
+  let dispatcherSrc = '';
+  try {
+    dispatcherSrc = fs.readFileSync(path.join(REPO_ROOT, DISPATCHER_REL), 'utf8');
+  } catch (_e) {
+    dispatcherSrc = '';
+  }
+  const dispatch = parseDispatcherShapes(dispatcherSrc);
+
+  const walked = walkRenderEntryPoints();
+  const entries = [];
+  const excludeErrors = [];
+  let cardEmission = 0;
+  let renderOnlyExcluded = 0;
+
+  const dialShape = dispatch.subShapes.includes('F.7-dial') ? 'F.7-dial' : null;
+
+  for (const rec of walked) {
+    const cls = classifyRenderCoverage(rec);
+    const entry = {
+      entry: rec.entry,
+      kind: rec.kind,
+      render_coverage: cls.render_coverage,
+    };
+    // The renderDial entries carry the F.7-dial shape handle so a consumer (178-02)
+    // and the build test can key on shape without re-parsing the dispatcher.
+    if (rec.kind === 'renderDial' && dialShape) {
+      entry.shape = dialShape;
+    }
+    if (cls.reason) entry.reason = cls.reason;
+    if (cls.note) entry.note = cls.note;
+    if (cls.error) excludeErrors.push(cls.error);
+
+    if (cls.render_coverage === 'card-emission') cardEmission += 1;
+    else renderOnlyExcluded += 1;
+
+    entries.push(entry);
+  }
+
+  // Phase 209-03 (B3): the SECOND, ADDITIVE keyspace - commands/*.md with
+  // hitl_shape frontmatter. Appended AFTER the .cjs entries so the .cjs
+  // entries stay byte-identical in position and content (Test 6/T-209-14).
+  const mdEntries = buildMdKeyspace();
+  let mdWired = 0;
+  let mdUnwired = 0;
+  for (const e of mdEntries) {
+    if (e.excluded || e.wired) mdWired += 1;
+    else mdUnwired += 1;
+    entries.push(e);
+  }
+
+  // The intern-w1-mode-gate-skip fix: the THIRD, ADDITIVE keyspace -
+  // skills/*/SKILL.md with hitl_shape frontmatter. Appended AFTER the
+  // commands/*.md entries so both prior keyspaces stay byte-identical in
+  // position and content.
+  const skillEntries = buildSkillKeyspace();
+  let skillWired = 0;
+  let skillUnwired = 0;
+  for (const e of skillEntries) {
+    if (e.excluded || e.wired) skillWired += 1;
+    else skillUnwired += 1;
+    entries.push(e);
+  }
+
+  return {
+    generated_note: GENERATED_NOTE,
+    dispatcher: {
+      source: DISPATCHER_REL.split(path.sep).join('/'),
+      f_subshapes: dispatch.subShapes,
+      has_dial_branch: dispatch.hasDialBranch,
+    },
+    render_counts: {
+      card_emission: cardEmission,
+      render_only_excluded: renderOnlyExcluded,
+      md_declared_wired: mdWired,
+      md_declared_unwired: mdUnwired,
+      skill_declared_wired: skillWired,
+      skill_declared_unwired: skillUnwired,
+    },
+    entries,
+    _excludeErrors: excludeErrors,
+  };
+}
+
+// Serialize exactly the way the on-disk file is written so the --check byte-compare
+// is deterministic. Strips the non-serialized `_excludeErrors`. Mirrors
+// build-connector-registry.cjs serializeRegistry (JSON.stringify(...,2) + trailing
+// newline). The entries are ALREADY sorted by the walk; the key order here is the
+// stable serialization order.
+function serializeRegistry(reg) {
+  const clean = {
+    generated_note: reg.generated_note,
+    dispatcher: reg.dispatcher,
+    render_counts: reg.render_counts,
+    entries: reg.entries,
+  };
+  return JSON.stringify(clean, null, 2) + '\n';
+}
+
+// ---------------------------------------------------------------------------
+// main()
+// ---------------------------------------------------------------------------
+function main() {
+  const argv = process.argv.slice(2);
+  const reg = buildRegistry();
+  const errs = [];
+  for (const e of reg._excludeErrors) 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/render-coverage-registry.json is STALE (a render entry point appeared in code ' +
+          'but is absent from the registry, OR the registry drifted). ' +
+          'Run: node scripts/build-render-coverage.cjs'
+      );
+    }
+    if (errs.length) {
+      console.error(errs.join('\n'));
+      console.error('Recovery: regenerate the render registry: node scripts/build-render-coverage.cjs');
+      process.exit(1);
+    }
+    console.log('render-coverage-registry: OK');
+    return;
+  }
+
+  // Default: write the registry, refusing on any render-only-excluded-without-reason.
+  if (errs.length) {
+    console.error(errs.join('\n'));
+    console.error('Recovery: add a reason to the RENDER_ONLY_EXCLUDED entry, then re-run: node scripts/build-render-coverage.cjs');
+    process.exit(1);
+  }
+  fs.mkdirSync(DATA_DIR, { recursive: true });
+  fs.writeFileSync(REGISTRY_PATH, serializeRegistry(reg));
+  console.log(
+    'Wrote data/render-coverage-registry.json (' +
+      reg.entries.length + ' entries: ' +
+      reg.render_counts.card_emission + ' card-emission, ' +
+      reg.render_counts.render_only_excluded + ' render-only-excluded, ' +
+      reg.render_counts.md_declared_wired + ' md-declared-wired, ' +
+      reg.render_counts.md_declared_unwired + ' md-declared-unwired, ' +
+      reg.render_counts.skill_declared_wired + ' skill-declared-wired, ' +
+      reg.render_counts.skill_declared_unwired + ' skill-declared-unwired)'
+  );
+}
+
+if (require.main === module) {
+  main();
+} else {
+  module.exports = {
+    listCjsFiles,
+    hasCallSite,
+    parseDispatcherShapes,
+    walkRenderEntryPoints,
+    classifyRenderCoverage,
+    buildRegistry,
+    serializeRegistry,
+    RENDER_ONLY_EXCLUDED,
+    WALK_SCOPES,
+    // Phase 209-03 (B3): the .md keyspace walk.
+    buildMdKeyspace,
+    stripFrontmatter,
+    MD_RENDER_ONLY_EXCLUDED,
+    // intern-w1-mode-gate-skip fix: the skills/*/SKILL.md keyspace walk.
+    buildSkillKeyspace,
+    SKILL_RENDER_ONLY_EXCLUDED,
+  };
+}