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

package/scripts/build-brain-census.cjs

@@ -0,0 +1,957 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Phase 246-02 (LOOP-02) - Brain graph census builder, two-lane.
+ * ==========================================================================
+ * Mirrors scripts/build-corpus-stats.cjs (Canon Part 7 reuse): the REPO_ROOT
+ * path-constant idiom, the GENERATED_NOTE stamp, the deterministic serializer
+ * (JSON.stringify with (null, 2) plus a trailing newline), and the
+ * require.main === module guard exporting pure functions for tests.
+ *
+ * Two deliberate departures from that precedent, documented here per the plan:
+ *   1. NO --check release gate. The census needs live network plus (for Lane
+ *      B) an operator-supplied admin key. A release gate must never depend on
+ *      live network, so this generator carries no --check mode at all.
+ *   2. The source of truth is live probes plus the committed state JSON, not
+ *      a committed source file. loadSource()-equivalent input for Lane A/B is
+ *      the live Brain server; only --render-only re-derives from the already
+ *      committed data/brain-census.generated.json.
+ *
+ * Canon Part 8 (The Graph Boundary): every CENSUS_QUERIES string is static
+ * and content-free (no interpolation of any user input, ever). Framework
+ * names come from repo frontmatter (generic methodology handles, Part 8
+ * permitted). tests/test-246-census-guard.cjs proves every string classifies
+ * allow under lib/core/part8-egress-guard.cjs classify().
+ *
+ * Usage:
+ *   node scripts/build-brain-census.cjs --lane-a
+ *       Run the per-framework read-tier census against the live deployment,
+ *       merge under lane_a, render both artifacts.
+ *   node scripts/build-brain-census.cjs --lane-b
+ *       Run the C1-C9 aggregate Cypher set (admin key required via
+ *       MINDRIAN_BRAIN_KEY / resolveBrainKey()), merge under lane_b, render.
+ *   node scripts/build-brain-census.cjs --lane-b-input <path>
+ *       Ingest an externally produced JSON (local-twin fallback) mapping
+ *       query id to result rows, merge under lane_b with a drift caveat.
+ *   node scripts/build-brain-census.cjs --render-only
+ *       Re-render both artifacts from the existing
+ *       data/brain-census.generated.json, zero network (idempotence check).
+ *
+ * No em-dashes anywhere (repo-wide fence). CJS only, no TypeScript, no new
+ * npm packages (Node built-ins plus resolve-brain-key.cjs only).
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+
+const DATA_DIR = path.join(REPO_ROOT, 'data');
+const DOCS_DIR = path.join(REPO_ROOT, 'docs');
+const COMMANDS_DIR = path.join(REPO_ROOT, 'commands');
+const MD_PATH = path.join(DOCS_DIR, 'BRAIN-GRAPH-CENSUS.generated.md');
+const JSON_PATH = path.join(DATA_DIR, 'brain-census.generated.json');
+
+const GENERATED_NOTE =
+  'GENERATED by scripts/build-brain-census.cjs - do not hand-edit';
+
+// Phase 339, 2026-09-03: origin resolved through getBrainUrl(), so there is
+// nothing left to mirror. getBrainUrl() (lib/core/brain-client.cjs) is the
+// single source of truth for the Brain origin, including the
+// MINDRIAN_BRAIN_URL override, which is honored inside that resolver.
+const { getBrainUrl } = require('../lib/core/brain-client.cjs');
+const BRAIN_URL = getBrainUrl();
+
+// Per-call budget note (research: server's ~5000ms default timeout). This
+// generator makes sequential calls only, never parallel fan-out, to be kind
+// to that budget.
+const BRAIN_REQUEST_TIMEOUT_MS = Number(process.env.MINDRIAN_BRAIN_TIMEOUT_MS) || 20000;
+
+// The 2026-08-10 canon-prose count, recorded (not resolved) against the
+// dated frontmatter scan below. See "Canon count discrepancy" in the
+// research: canon prose says "the 25 methodology commands".
+const CANON_PROSE_COMMAND_COUNT = 25;
+
+// The three frameworks the 2026-08-10 probe recorded as absent Framework
+// nodes, probed again live in Lane A via normalize_framework_name.
+const ABSENCE_PROBE_NAMES = ['TRIZ', 'SCAMPER', 'Five Whys'];
+
+// ---------------------------------------------------------------------------
+// CENSUS_QUERIES - the C1-C9 aggregate set plus the C2a-C2d single-type
+// fallbacks, copied VERBATIM (Cypher text unchanged) from "The census query
+// set" section of 246-RESEARCH.md. Every string is static and content-free;
+// no interpolation of any user input, ever (Part 8, threat T-246-02).
+//
+// C4 is recorded as THREE separate entries sharing id 'C4' (each carrying a
+// `sub` key: feeds_into / leads_to / alias_of), matching the research's three
+// separate MATCH clauses verbatim rather than fusing them into a query the
+// research never wrote. Lane B merges the three sub-results into a single
+// lane_b.results.C4 = { feeds_into, leads_to, alias_of } object.
+// ---------------------------------------------------------------------------
+const CENSUS_QUERIES = [
+  {
+    id: 'C1',
+    label: 'C1 total Framework nodes',
+    cypher: 'MATCH (f:Framework) RETURN count(f) AS frameworks',
+  },
+  {
+    id: 'C2',
+    label: 'C2 structure coverage per edge type (grouped alternation)',
+    cypher: `MATCH (f:Framework)-[r:HAS_PHASE|HAS_STAGE|HAS_PROCESS_STEP|HAS_STEP]->()
+RETURN type(r) AS t, count(r) AS edges, count(DISTINCT f) AS frameworks_with_t`,
+  },
+  {
+    id: 'C2a',
+    label: 'C2a HAS_PHASE coverage (single-type fallback)',
+    cypher: `MATCH (f:Framework)-[r:HAS_PHASE]->()
+RETURN type(r) AS t, count(r) AS edges, count(DISTINCT f) AS frameworks_with_t`,
+  },
+  {
+    id: 'C2b',
+    label: 'C2b HAS_STAGE coverage (single-type fallback)',
+    cypher: `MATCH (f:Framework)-[r:HAS_STAGE]->()
+RETURN type(r) AS t, count(r) AS edges, count(DISTINCT f) AS frameworks_with_t`,
+  },
+  {
+    id: 'C2c',
+    label: 'C2c HAS_PROCESS_STEP coverage (single-type fallback)',
+    cypher: `MATCH (f:Framework)-[r:HAS_PROCESS_STEP]->()
+RETURN type(r) AS t, count(r) AS edges, count(DISTINCT f) AS frameworks_with_t`,
+  },
+  {
+    id: 'C2d',
+    label: 'C2d HAS_STEP coverage (single-type fallback)',
+    cypher: `MATCH (f:Framework)-[r:HAS_STEP]->()
+RETURN type(r) AS t, count(r) AS edges, count(DISTINCT f) AS frameworks_with_t`,
+  },
+  {
+    id: 'C3',
+    label: 'C3 distinct frameworks with ANY structure',
+    cypher: `MATCH (f:Framework)-[:HAS_PHASE|HAS_STAGE|HAS_PROCESS_STEP|HAS_STEP]->()
+RETURN count(DISTINCT f) AS structured_frameworks`,
+  },
+  {
+    id: 'C4',
+    sub: 'feeds_into',
+    label: 'C4 FEEDS_INTO edge count',
+    cypher: 'MATCH ()-[r:FEEDS_INTO]->() RETURN count(r) AS feeds_into',
+  },
+  {
+    id: 'C4',
+    sub: 'leads_to',
+    label: 'C4 LEADS_TO edge count',
+    cypher: 'MATCH ()-[r:LEADS_TO]->() RETURN count(r) AS leads_to',
+  },
+  {
+    id: 'C4',
+    sub: 'alias_of',
+    label: 'C4 ALIAS_OF edge count',
+    cypher: 'MATCH ()-[r:ALIAS_OF]->() RETURN count(r) AS alias_of',
+  },
+  {
+    id: 'C5',
+    label: 'C5 label census (UNWIND, honest multi-label form)',
+    cypher:
+      'MATCH (n) UNWIND labels(n) AS label RETURN label, count(*) AS c ORDER BY c DESC LIMIT 50',
+  },
+  {
+    id: 'C6',
+    label: 'C6 relationship-type census',
+    cypher: 'MATCH ()-[r]->() RETURN type(r) AS t, count(*) AS c ORDER BY c DESC LIMIT 50',
+  },
+  {
+    id: 'C7',
+    label: 'C7 duplicate-name scan (JTBD-alias class, generalized)',
+    cypher: `MATCH (f:Framework) WITH trim(toLower(f.name)) AS k, collect(f.name) AS names, count(*) AS c
+WHERE c > 1 RETURN k, names, c ORDER BY c DESC LIMIT 50`,
+  },
+  {
+    id: 'C8',
+    label: 'C8 named-absence probes (TRIZ/SCAMPER/Five Whys, expect zero rows)',
+    cypher: `MATCH (f:Framework)
+WHERE toLower(f.name) CONTAINS 'triz' OR toLower(f.name) CONTAINS 'scamper'
+   OR toLower(f.name) CONTAINS 'five whys'
+RETURN f.name LIMIT 20`,
+  },
+  {
+    id: 'C9',
+    label: 'C9 JTBD alias enumeration (expect the 4 aliases on the record)',
+    cypher: `MATCH (f:Framework)
+WHERE toLower(f.name) CONTAINS 'jobs to be done' OR toLower(f.name) CONTAINS 'jtbd'
+RETURN f.name LIMIT 20`,
+  },
+];
+
+// ---------------------------------------------------------------------------
+// scanMethodologyCommands() - read every commands/*.md, extract the
+// frontmatter block between the first two lines that are exactly three
+// hyphens, and from files carrying "kind: methodology" extract the
+// single-line inline frameworks: [...] array. commandCount is DERIVED from
+// disk at run time (Part 11 ethos), never a frozen literal.
+// ---------------------------------------------------------------------------
+function scanMethodologyCommands() {
+  let files = [];
+  try {
+    files = fs.readdirSync(COMMANDS_DIR).filter((f) => f.endsWith('.md')).sort();
+  } catch (_e) {
+    files = [];
+  }
+
+  const usageMap = new Map();
+  let commandCount = 0;
+
+  for (const file of files) {
+    const abs = path.join(COMMANDS_DIR, file);
+    let content;
+    try {
+      content = fs.readFileSync(abs, 'utf8');
+    } catch (_e) {
+      continue;
+    }
+    const lines = content.split('\n');
+    let firstDash = -1;
+    let secondDash = -1;
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].trim() === '---') {
+        if (firstDash === -1) {
+          firstDash = i;
+        } else {
+          secondDash = i;
+          break;
+        }
+      }
+    }
+    if (firstDash === -1 || secondDash === -1) continue;
+
+    const fm = lines.slice(firstDash + 1, secondDash).join('\n');
+    if (!/^kind:\s*methodology\s*$/m.test(fm)) continue;
+    commandCount++;
+
+    const m = fm.match(/^frameworks:\s*\[(.*)\]\s*$/m);
+    if (!m) continue;
+    const inner = m[1];
+    const nameRe = /"([^"]*)"/g;
+    let mm;
+    while ((mm = nameRe.exec(inner)) !== null) {
+      const name = mm[1];
+      if (!name) continue;
+      usageMap.set(name, (usageMap.get(name) || 0) + 1);
+    }
+  }
+
+  const frameworks = Array.from(usageMap.entries())
+    .map(([name, uses]) => ({ name, uses }))
+    .sort((a, b) => (b.uses - a.uses) || a.name.localeCompare(b.name));
+
+  return {
+    commandCount,
+    scannedAt: new Date().toISOString().slice(0, 10),
+    frameworks,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// brainCall(toolName, args, key) - direct fetch POST to BRAIN_URL/mcp, the
+// exact wire shape lib/core/brain-client.cjs uses (headers, jsonrpc 2.0
+// tools/call body, SSE "data: " line parse). Two deliberate differences from
+// brain-client (research Pitfall 2): on a non-OK response, return
+// { ok:false, httpStatus, bodyText } with the body read VERBATIM, never null;
+// and no session cache. No initialize handshake is required up front (the
+// transport is stateless at the HTTP level); if the server ever rejects with
+// a session-required error, this mirrors _ensureSession's single initialize
+// call once and retries.
+// ---------------------------------------------------------------------------
+function _looksSessionRequired(bodyText) {
+  return typeof bodyText === 'string' && /session/i.test(bodyText) && /required|missing|invalid/i.test(bodyText);
+}
+
+async function _initializeOnce(key) {
+  const res = await fetch(BRAIN_URL + '/mcp', {
+    method: 'POST',
+    signal: AbortSignal.timeout(BRAIN_REQUEST_TIMEOUT_MS),
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json, text/event-stream',
+      Authorization: 'Bearer ' + key,
+    },
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'initialize',
+      params: {
+        protocolVersion: '2024-11-05',
+        capabilities: {},
+        clientInfo: { name: 'mindrian-census', version: '1.0.0' },
+      },
+    }),
+  });
+  try {
+    await res.text();
+  } catch (_e) {
+    /* drain best-effort */
+  }
+  return res.ok;
+}
+
+// Phase 259 (TRUST-02): classify a caught error into the D-05 failure-kind
+// taxonomy at the site where the error object still exists. Measured live
+// this session on Node v22.23.1: an AbortSignal.timeout abort yields
+// e.name === 'TimeoutError' (e.code === 23, message "The operation was
+// aborted due to timeout"); a connection failure yields a plain TypeError
+// with message "fetch failed" and no distinguishing name. Once brainCall
+// returns, both collapse into the same 'fetch failed: ...' bodyText prefix,
+// so e.message alone cannot tell them apart downstream -- classify HERE.
+function _classifyThrown(e) {
+  return (e && e.name === 'TimeoutError') ? 'timeout' : 'hard_error';
+}
+
+async function brainCall(toolName, args, key) {
+  const doCall = async () =>
+    fetch(BRAIN_URL + '/mcp', {
+      method: 'POST',
+      signal: AbortSignal.timeout(BRAIN_REQUEST_TIMEOUT_MS),
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'application/json, text/event-stream',
+        Authorization: 'Bearer ' + key,
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: 2,
+        method: 'tools/call',
+        params: { name: toolName, arguments: args },
+      }),
+    });
+
+  let res;
+  try {
+    res = await doCall();
+  } catch (e) {
+    return { ok: false, httpStatus: 0, bodyText: 'fetch failed: ' + (e && e.message ? e.message : String(e)), errorKind: _classifyThrown(e) };
+  }
+
+  if (!res.ok) {
+    let bodyText = '';
+    try {
+      bodyText = await res.text();
+    } catch (_e) {
+      bodyText = '';
+    }
+    if (_looksSessionRequired(bodyText)) {
+      const initOk = await _initializeOnce(key).catch(() => false);
+      if (initOk) {
+        let retryRes;
+        try {
+          retryRes = await doCall();
+        } catch (e) {
+          return { ok: false, httpStatus: 0, bodyText: 'retry fetch failed: ' + (e && e.message ? e.message : String(e)), errorKind: _classifyThrown(e) };
+        }
+        if (!retryRes.ok) {
+          let retryBody = '';
+          try {
+            retryBody = await retryRes.text();
+          } catch (_e) {
+            retryBody = '';
+          }
+          return { ok: false, httpStatus: retryRes.status, bodyText: retryBody, errorKind: 'hard_error' };
+        }
+        res = retryRes;
+      } else {
+        return { ok: false, httpStatus: res.status, bodyText, errorKind: 'hard_error' };
+      }
+    } else {
+      return { ok: false, httpStatus: res.status, bodyText, errorKind: 'hard_error' };
+    }
+  }
+
+  let text;
+  try {
+    text = await res.text();
+  } catch (e) {
+    return { ok: false, httpStatus: res.status, bodyText: 'body read failed: ' + (e && e.message ? e.message : String(e)), errorKind: 'malformed' };
+  }
+  const dataLine = text.split('\n').find((l) => l.startsWith('data: '));
+  if (!dataLine) {
+    return { ok: false, httpStatus: res.status, bodyText: 'no SSE data line in response: ' + text.slice(0, 500), errorKind: 'malformed' };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(dataLine.slice(6));
+  } catch (e) {
+    return { ok: false, httpStatus: res.status, bodyText: 'unparsable SSE payload: ' + text.slice(0, 500), errorKind: 'malformed' };
+  }
+  if (parsed.error) {
+    // OQ-3 (carried risk, A1): classified hard_error under D-05's "anything
+    // that did not cleanly succeed VOIDs regardless of bucket" rule. Risk:
+    // if orchestration_readiness ever errors on an unknown framework name
+    // rather than returning a readiness object, every genuinely-absent
+    // framework would VOID instead of MISS. Not discharged at research
+    // time; discharged by the live floor-run checkpoint in Plan 259-04.
+    return { ok: false, httpStatus: res.status, bodyText: JSON.stringify(parsed.error), errorKind: 'hard_error' };
+  }
+  if (parsed.result && Array.isArray(parsed.result.content)) {
+    const textContent = parsed.result.content.find((c) => c && c.type === 'text');
+    if (textContent) {
+      try {
+        return { ok: true, result: JSON.parse(textContent.text) };
+      } catch (_e) {
+        return { ok: true, result: { text: textContent.text } };
+      }
+    }
+  }
+  return { ok: true, result: parsed.result || null };
+}
+
+// ---------------------------------------------------------------------------
+// computeGapTable(laneA) - frameworks with readiness 0-2 or absent, sorted by
+// uses descending then name. This ordered list IS "top gaps by expected-use"
+// and IS the Phase 249 enrichment queue seed.
+// ---------------------------------------------------------------------------
+function computeGapTable(laneA) {
+  if (!laneA || !Array.isArray(laneA.frameworks)) return [];
+  const gaps = [];
+  for (const row of laneA.frameworks) {
+    const readiness = row.readiness && row.readiness.ok ? row.readiness : null;
+    const score =
+      readiness && readiness.result && readiness.result.readiness && typeof readiness.result.readiness.readiness_score === 'number'
+        ? readiness.result.readiness.readiness_score
+        : null;
+    const isGap = score === null || score <= 2;
+    if (!isGap) continue;
+    gaps.push({
+      framework: row.name,
+      uses: row.uses,
+      readiness_score: score,
+      status:
+        readiness && readiness.result && readiness.result.readiness
+          ? readiness.result.readiness.orchestration_status
+          : null,
+      reason:
+        score === null
+          ? 'readiness probe absent or failed - treated as a gap'
+          : 'readiness ' + score + '/4',
+    });
+  }
+  gaps.sort((a, b) => (b.uses - a.uses) || a.framework.localeCompare(b.framework));
+  return gaps;
+}
+
+// ---------------------------------------------------------------------------
+// renderMarkdown(census) - deterministic markdown, emitted in the fixed
+// order: H1 stamp, Census Meta, Canon count discrepancy, Lane B aggregates
+// (or the explicit PENDING line), Lane A per-framework table, Top gaps
+// table, 2026-08-10 findings. Hyphens only, never em-dashes.
+// ---------------------------------------------------------------------------
+function _fmtVal(v) {
+  if (v === null || v === undefined) return 'n/a';
+  return String(v);
+}
+
+function renderMarkdown(census) {
+  const c = census || {};
+  const meta = c.meta || {};
+  const canon = c.canon_discrepancy || {};
+  const laneA = c.lane_a || null;
+  const laneB = c.lane_b || null;
+  const gapTable = Array.isArray(c.gap_table) ? c.gap_table : [];
+
+  const lines = [];
+  lines.push('# Brain Graph Census (Generated)');
+  lines.push('');
+  lines.push('<!-- ' + GENERATED_NOTE + ' -->');
+  lines.push('> ' + GENERATED_NOTE + '. This file is rendered by scripts/build-brain-census.cjs. Edit the source lane data, not this file.');
+  lines.push('');
+
+  // ---- Census Meta ----
+  lines.push('## Census Meta');
+  lines.push('');
+  lines.push('| Field | Value |');
+  lines.push('| ----- | ----- |');
+  lines.push('| Census date | ' + _fmtVal(meta.census_date) + ' |');
+  lines.push('| Brain URL | ' + _fmtVal(meta.brain_url) + ' |');
+  if (meta.brain_stats) {
+    lines.push('| brain_stats backend | ' + _fmtVal(meta.brain_stats.backend) + ' |');
+    lines.push('| brain_stats totalRecordCount | ' + _fmtVal(meta.brain_stats.totalRecordCount) + ' |');
+    lines.push('| brain_stats relationshipCount | ' + _fmtVal(meta.brain_stats.relationshipCount) + ' |');
+    lines.push('| brain_stats vectorIndexes | ' + _fmtVal(Array.isArray(meta.brain_stats.vectorIndexes) ? meta.brain_stats.vectorIndexes.length : null) + ' |');
+  } else {
+    lines.push('| brain_stats | not captured this run |');
+  }
+  lines.push('| Lane A key tier | ' + _fmtVal(meta.key_tier_lane_a) + ' |');
+  lines.push('| Lane A source | ' + _fmtVal(meta.lane_a_source) + ' |');
+  lines.push('| Lane B key tier | ' + _fmtVal(meta.key_tier_lane_b) + ' |');
+  lines.push('| Lane B source | ' + _fmtVal(meta.lane_b_source) + ' |');
+  lines.push('');
+
+  // ---- Canon count discrepancy ----
+  lines.push('## Canon count discrepancy (recorded, not resolved)');
+  lines.push('');
+  lines.push(
+    'Canon prose says "the 25 methodology commands". The dated frontmatter scan of ' +
+      'commands/*.md (scanned ' + _fmtVal(canon.scanned_at) + ') counts ' +
+      _fmtVal(canon.scanned_count) + ' files with kind: methodology. This census\'s ' +
+      'enumeration source is the frontmatter scan, dated above. ENRICH-04\'s floor must ' +
+      'be measured against a confirmed set (research open question 2); this discrepancy ' +
+      'is surfaced to the navigator here, never silently resolved.'
+  );
+  lines.push('');
+
+  // ---- Lane B aggregates ----
+  lines.push('## Lane B aggregates');
+  lines.push('');
+  if (!laneB) {
+    lines.push(
+      'PENDING - Lane B aggregate Cypher not yet run (admin key not supplied as of ' +
+        _fmtVal(meta.census_date) + '); Lane A below is complete and citable.'
+    );
+  } else {
+    if (laneB.drift_caveat) {
+      lines.push(
+        '**Drift caveat:** these Lane B numbers came from the local twin (bolt://127.0.0.1:7690), ' +
+          'not the live Render deployment, and may drift from it.'
+      );
+      lines.push('');
+    }
+    const r = laneB.results || {};
+    lines.push('**C1 Framework totals:** ' + _fmtVal(r.C1 && r.C1.frameworks) + ' Framework nodes.');
+    lines.push('');
+    if (r.C2) {
+      lines.push('**C2/C3 HAS_* structure coverage (grouped alternation):**');
+      lines.push('');
+      lines.push('| Edge type | Edges | Frameworks with edge |');
+      lines.push('| --------- | ----- | --------------------- |');
+      const c2rows = Array.isArray(r.C2) ? r.C2 : [r.C2];
+      for (const row of c2rows) {
+        lines.push('| ' + _fmtVal(row.t) + ' | ' + _fmtVal(row.edges) + ' | ' + _fmtVal(row.frameworks_with_t) + ' |');
+      }
+    } else if (r.C2a || r.C2b || r.C2c || r.C2d) {
+      lines.push('**C2/C3 HAS_* structure coverage (single-type fallback used, grouped alternation errored):**');
+      lines.push('');
+      lines.push('| Edge type | Edges | Frameworks with edge |');
+      lines.push('| --------- | ----- | --------------------- |');
+      for (const key of ['C2a', 'C2b', 'C2c', 'C2d']) {
+        const row = r[key];
+        if (!row) continue;
+        const rr = Array.isArray(row) ? row[0] : row;
+        if (!rr) continue;
+        lines.push('| ' + _fmtVal(rr.t) + ' | ' + _fmtVal(rr.edges) + ' | ' + _fmtVal(rr.frameworks_with_t) + ' |');
+      }
+    }
+    lines.push('');
+    lines.push('C3 distinct frameworks with any structure: ' + _fmtVal(r.C3 && r.C3.structured_frameworks) + '.');
+    lines.push('');
+    lines.push(
+      '**C4 flow edge counts:** FEEDS_INTO=' + _fmtVal(r.C4 && r.C4.feeds_into) +
+        ', LEADS_TO=' + _fmtVal(r.C4 && r.C4.leads_to) +
+        ', ALIAS_OF=' + _fmtVal(r.C4 && r.C4.alias_of) + '.'
+    );
+    lines.push('');
+    lines.push(
+      '**C5 label census** (nodes carry up to 6 labels, so label counts sum to MORE than the ' +
+        'node count - the honest UNWIND form):'
+    );
+    lines.push('');
+    lines.push('| Label | Count |');
+    lines.push('| ----- | ----- |');
+    for (const row of Array.isArray(r.C5) ? r.C5 : []) {
+      lines.push('| ' + _fmtVal(row.label) + ' | ' + _fmtVal(row.c) + ' |');
+    }
+    lines.push('');
+    lines.push('**C6 relationship-type census:**');
+    lines.push('');
+    lines.push('| Relationship type | Count |');
+    lines.push('| ------------------ | ----- |');
+    for (const row of Array.isArray(r.C6) ? r.C6 : []) {
+      lines.push('| ' + _fmtVal(row.t) + ' | ' + _fmtVal(row.c) + ' |');
+    }
+    lines.push('');
+    lines.push('**C7 duplicate-name scan:**');
+    lines.push('');
+    if (!Array.isArray(r.C7) || r.C7.length === 0) {
+      lines.push('No duplicate Framework names found.');
+    } else {
+      lines.push('| Normalized key | Names | Count |');
+      lines.push('| -------------- | ----- | ----- |');
+      for (const row of r.C7) {
+        lines.push('| ' + _fmtVal(row.k) + ' | ' + _fmtVal(Array.isArray(row.names) ? row.names.join(', ') : row.names) + ' | ' + _fmtVal(row.c) + ' |');
+      }
+    }
+    lines.push('');
+    lines.push('**C8 named-absence probes (TRIZ/SCAMPER/Five Whys):**');
+    lines.push('');
+    if (!Array.isArray(r.C8) || r.C8.length === 0) {
+      lines.push('Zero rows returned - TRIZ, SCAMPER, and Five Whys are absent as Framework nodes.');
+    } else {
+      lines.push('Rows returned (NOT absent): ' + r.C8.map((row) => row['f.name'] || row.name).join(', '));
+    }
+    lines.push('');
+    lines.push('**C9 JTBD alias enumeration:**');
+    lines.push('');
+    if (!Array.isArray(r.C9) || r.C9.length === 0) {
+      lines.push('Zero rows returned.');
+    } else {
+      lines.push('| Name |');
+      lines.push('| ---- |');
+      for (const row of r.C9) {
+        lines.push('| ' + _fmtVal(row['f.name'] || row.name) + ' |');
+      }
+    }
+  }
+  lines.push('');
+
+  // ---- Lane A per-framework census ----
+  lines.push('## Lane A per-framework census');
+  lines.push('');
+  if (!laneA || !Array.isArray(laneA.frameworks) || laneA.frameworks.length === 0) {
+    lines.push('Lane A has not run yet.');
+  } else {
+    lines.push('| Framework | Uses | Normalize result | Readiness | Structure rows | Provenance |');
+    lines.push('| --------- | ---- | ----------------- | --------- | --------------- | ---------- |');
+    for (const row of laneA.frameworks) {
+      const norm =
+        row.normalize && row.normalize.ok
+          ? (Array.isArray(row.normalize.result && row.normalize.result.canonical_matches)
+              ? row.normalize.result.canonical_matches.length + ' canonical match(es)'
+              : 'ok')
+          : 'FAILED: ' + _fmtVal(row.normalize && row.normalize.httpStatus) + ' ' + _fmtVal(row.normalize && row.normalize.bodyText);
+      const readiness =
+        row.readiness && row.readiness.ok
+          ? (row.readiness.result && row.readiness.result.readiness
+              ? row.readiness.result.readiness.readiness_score + '/4 (' + row.readiness.result.readiness.orchestration_status + ')'
+              : 'no match')
+          : 'FAILED: ' + _fmtVal(row.readiness && row.readiness.httpStatus) + ' ' + _fmtVal(row.readiness && row.readiness.bodyText);
+      const structure =
+        row.structure && row.structure.ok
+          ? (Array.isArray(row.structure.result && row.structure.result.components)
+              ? String(row.structure.result.components.length)
+              : '0')
+          : 'FAILED: ' + _fmtVal(row.structure && row.structure.httpStatus) + ' ' + _fmtVal(row.structure && row.structure.bodyText);
+      const provenance = Array.isArray(row.provenance)
+        ? row.provenance.map((p) => p.tool + '@' + p.date).join('; ')
+        : '';
+      lines.push(
+        '| ' + _fmtVal(row.name) + ' | ' + _fmtVal(row.uses) + ' | ' + norm + ' | ' + readiness + ' | ' + structure + ' | ' + provenance + ' |'
+      );
+    }
+  }
+  lines.push('');
+
+  // ---- Top gaps ----
+  lines.push('## Top gaps by expected-use (Phase 249 queue seed)');
+  lines.push('');
+  if (gapTable.length === 0) {
+    lines.push('No gaps computed yet (Lane A has not run).');
+  } else {
+    lines.push('| Framework | Uses | Readiness | Reason |');
+    lines.push('| --------- | ---- | --------- | ------ |');
+    for (const row of gapTable) {
+      lines.push('| ' + _fmtVal(row.framework) + ' | ' + _fmtVal(row.uses) + ' | ' + _fmtVal(row.readiness_score) + '/4 | ' + _fmtVal(row.reason) + ' |');
+    }
+  }
+  lines.push('');
+
+  // ---- 2026-08-10 findings ----
+  lines.push('## 2026-08-10 findings: confirmed or corrected');
+  lines.push('');
+  if (!laneA || !Array.isArray(laneA.frameworks)) {
+    lines.push('Lane A has not run yet; the 2026-08-10 findings cannot be confirmed or corrected.');
+  } else {
+    const jtbd = laneA.frameworks.find((f) => /jobs to be done|jtbd/i.test(f.name));
+    if (jtbd) {
+      const score =
+        jtbd.readiness && jtbd.readiness.ok && jtbd.readiness.result && jtbd.readiness.result.readiness
+          ? jtbd.readiness.result.readiness.readiness_score
+          : null;
+      const aliasCount =
+        jtbd.normalize && jtbd.normalize.ok && Array.isArray(jtbd.normalize.result && jtbd.normalize.result.canonical_matches)
+          ? jtbd.normalize.result.canonical_matches.length
+          : null;
+      const structRows =
+        jtbd.structure && jtbd.structure.ok && Array.isArray(jtbd.structure.result && jtbd.structure.result.components)
+          ? jtbd.structure.result.components.length
+          : null;
+      const verdict = score === 0 && aliasCount === 4 && structRows === 0 ? 'CONFIRMED' : 'CORRECTED';
+      lines.push(
+        '- JTBD: recorded expectation readiness 0/4 with 4 aliases, empty discover_structure. ' +
+          'Live run: readiness ' + _fmtVal(score) + '/4, ' + _fmtVal(aliasCount) + ' canonical match(es), ' +
+          _fmtVal(structRows) + ' structure row(s). Verdict: ' + verdict + '.'
+      );
+    } else {
+      lines.push('- JTBD: not present in the Lane A framework list this run (unexpected - flag for review).');
+    }
+    if (Array.isArray(laneA.absence_probes) && laneA.absence_probes.length > 0) {
+      for (const p of laneA.absence_probes) {
+        const matches =
+          p.normalize && p.normalize.ok && Array.isArray(p.normalize.result && p.normalize.result.canonical_matches)
+            ? p.normalize.result.canonical_matches.length
+            : null;
+        const verdict = matches === 0 ? 'CONFIRMED absent' : matches === null ? 'probe failed' : 'CORRECTED - now present';
+        lines.push('- ' + p.name + ': recorded expectation absent as a Framework node. Live run: ' + _fmtVal(matches) + ' canonical match(es). Verdict: ' + verdict + '.');
+      }
+    } else {
+      lines.push('- TRIZ/SCAMPER/Five Whys absence probes not captured this run.');
+    }
+  }
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// serializeArtifactJson(census) - the machine-readable twin. JSON.stringify
+// with (null, 2) plus a trailing newline (the corpus-stats serializer
+// discipline), so two calls on the same input are byte-identical.
+// ---------------------------------------------------------------------------
+function serializeArtifactJson(census) {
+  return JSON.stringify(census, null, 2) + '\n';
+}
+
+// ---------------------------------------------------------------------------
+// Lane A live run.
+// ---------------------------------------------------------------------------
+async function _runLaneA(key) {
+  const nowIso = () => new Date().toISOString();
+
+  const statsRes = await brainCall('brain_stats', {}, key);
+  const brainStats = statsRes.ok ? statsRes.result : null;
+  if (!statsRes.ok) {
+    process.stderr.write('[census] brain_stats failed: ' + statsRes.httpStatus + ' ' + statsRes.bodyText + '\n');
+  }
+
+  const scanned = scanMethodologyCommands();
+  const frameworks = [];
+  let successCount = 0;
+
+  for (const fw of scanned.frameworks) {
+    const normalize = await brainCall('normalize_framework_name', { raw: fw.name }, key);
+    const readiness = await brainCall('orchestration_readiness', { framework_name: fw.name }, key);
+    const structure = await brainCall('discover_structure', { framework_name: fw.name }, key);
+
+    if (normalize.ok || readiness.ok || structure.ok) successCount++;
+
+    frameworks.push({
+      name: fw.name,
+      uses: fw.uses,
+      normalize,
+      readiness,
+      structure,
+      provenance: [
+        { tool: 'normalize_framework_name', date: nowIso() },
+        { tool: 'orchestration_readiness', date: nowIso() },
+        { tool: 'discover_structure', date: nowIso() },
+      ],
+    });
+  }
+
+  if (scanned.frameworks.length > 0 && successCount === 0) {
+    const first3 = frameworks.slice(0, 3).map((f) => ({
+      name: f.name,
+      normalize: f.normalize.ok ? 'ok' : f.normalize.httpStatus + ' ' + f.normalize.bodyText,
+    }));
+    throw new Error(
+      'Lane A: EVERY probe failed. First three: ' + JSON.stringify(first3) +
+        '. Refusing to commit an empty census.'
+    );
+  }
+
+  const absenceProbes = [];
+  for (const name of ABSENCE_PROBE_NAMES) {
+    const normalize = await brainCall('normalize_framework_name', { raw: name }, key);
+    absenceProbes.push({ name, normalize });
+  }
+
+  return {
+    frameworks,
+    absence_probes: absenceProbes,
+    commandCount: scanned.commandCount,
+    scannedAt: scanned.scannedAt,
+    brainStats,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Lane B live run against brain_query.
+// ---------------------------------------------------------------------------
+async function _runLaneB(key) {
+  const results = {};
+  let usedFallback = false;
+
+  const c1 = CENSUS_QUERIES.find((q) => q.id === 'C1');
+  const r1 = await brainCall('brain_query', { cypher: c1.cypher }, key);
+  if (!r1.ok) {
+    process.stderr.write('[census] Lane B brain_query failed on C1: ' + r1.httpStatus + ' ' + r1.bodyText + '\n');
+    process.stderr.write('[census] hint: HTTP 403 means the supplied key is not in Render\'s BRAIN_HTTP_ADMIN_KEYS (admin-tier gate).\n');
+    throw new Error('Lane B: C1 probe failed with httpStatus=' + r1.httpStatus + ' body=' + r1.bodyText);
+  }
+  results.C1 = Array.isArray(r1.result) ? r1.result[0] : r1.result;
+
+  const c2 = CENSUS_QUERIES.find((q) => q.id === 'C2');
+  const r2 = await brainCall('brain_query', { cypher: c2.cypher }, key);
+  if (r2.ok) {
+    results.C2 = r2.result;
+  } else {
+    usedFallback = true;
+    for (const subId of ['C2a', 'C2b', 'C2c', 'C2d']) {
+      const q = CENSUS_QUERIES.find((qq) => qq.id === subId);
+      const r = await brainCall('brain_query', { cypher: q.cypher }, key);
+      results[subId] = r.ok ? r.result : { error: r.bodyText };
+    }
+  }
+
+  const c3 = CENSUS_QUERIES.find((q) => q.id === 'C3');
+  const r3 = await brainCall('brain_query', { cypher: c3.cypher }, key);
+  results.C3 = r3.ok ? (Array.isArray(r3.result) ? r3.result[0] : r3.result) : { error: r3.bodyText };
+
+  const c4entries = CENSUS_QUERIES.filter((q) => q.id === 'C4');
+  const c4merged = {};
+  for (const q of c4entries) {
+    const r = await brainCall('brain_query', { cypher: q.cypher }, key);
+    const row = r.ok ? (Array.isArray(r.result) ? r.result[0] : r.result) : null;
+    c4merged[q.sub] = row ? row[q.sub] : null;
+  }
+  results.C4 = c4merged;
+
+  for (const id of ['C5', 'C6', 'C7', 'C8', 'C9']) {
+    const q = CENSUS_QUERIES.find((qq) => qq.id === id);
+    const r = await brainCall('brain_query', { cypher: q.cypher }, key);
+    results[id] = r.ok ? r.result : { error: r.bodyText };
+  }
+
+  return { results, usedFallback };
+}
+
+// ---------------------------------------------------------------------------
+// main() - four-mode CLI.
+// ---------------------------------------------------------------------------
+async function main() {
+  const argv = process.argv.slice(2);
+
+  fs.mkdirSync(DATA_DIR, { recursive: true });
+  fs.mkdirSync(DOCS_DIR, { recursive: true });
+
+  function loadExisting() {
+    if (!fs.existsSync(JSON_PATH)) return { meta: {}, canon_discrepancy: {}, gap_table: [] };
+    return JSON.parse(fs.readFileSync(JSON_PATH, 'utf8'));
+  }
+
+  function writeOut(census) {
+    fs.writeFileSync(MD_PATH, renderMarkdown(census));
+    fs.writeFileSync(JSON_PATH, serializeArtifactJson(census));
+  }
+
+  if (argv.includes('--render-only')) {
+    const census = loadExisting();
+    writeOut(census);
+    console.log('Re-rendered docs/BRAIN-GRAPH-CENSUS.generated.md + data/brain-census.generated.json (zero network)');
+    return;
+  }
+
+  if (argv.includes('--lane-a')) {
+    const { resolveBrainKey } = require('../lib/core/resolve-brain-key.cjs');
+    const r = resolveBrainKey();
+    if (!r.available) {
+      console.error('Brain key unavailable: ' + r.reason);
+      process.exit(1);
+    }
+    const scanned = scanMethodologyCommands();
+    const laneAResult = await _runLaneA(r.key);
+    const census = loadExisting();
+    census.generated_note = GENERATED_NOTE;
+    census.meta = Object.assign({}, census.meta, {
+      census_date: laneAResult.scannedAt,
+      brain_url: BRAIN_URL,
+      brain_stats: laneAResult.brainStats,
+      key_tier_lane_a: 'read',
+      lane_a_source: 'render-live ungated read tools',
+    });
+    census.canon_discrepancy = {
+      canon_prose_count: CANON_PROSE_COMMAND_COUNT,
+      scanned_count: laneAResult.commandCount,
+      scanned_at: laneAResult.scannedAt,
+      enumeration_source: 'frontmatter scan of commands/*.md (kind: methodology)',
+    };
+    census.lane_a = {
+      frameworks: laneAResult.frameworks,
+      absence_probes: laneAResult.absence_probes,
+    };
+    census.gap_table = computeGapTable(census.lane_a);
+    writeOut(census);
+    console.log('Lane A complete: ' + laneAResult.frameworks.length + ' frameworks probed, ' + census.gap_table.length + ' gaps.');
+    return;
+  }
+
+  if (argv.includes('--lane-b')) {
+    const { resolveBrainKey } = require('../lib/core/resolve-brain-key.cjs');
+    const r = resolveBrainKey();
+    if (!r.available) {
+      console.error('Brain key unavailable: ' + r.reason);
+      process.exit(1);
+    }
+    const laneB = await _runLaneB(r.key);
+    const census = loadExisting();
+    census.lane_b = {
+      results: laneB.results,
+      lane_b_source: 'render-live',
+      key_tier_lane_b: 'admin',
+      drift_caveat: false,
+      used_c2_fallback: laneB.usedFallback,
+    };
+    census.meta = Object.assign({}, census.meta, {
+      key_tier_lane_b: 'admin',
+      lane_b_source: 'render-live',
+    });
+    writeOut(census);
+    console.log('Lane B complete: results for ' + Object.keys(laneB.results).join(', '));
+    return;
+  }
+
+  const laneBInputIdx = argv.indexOf('--lane-b-input');
+  if (laneBInputIdx !== -1) {
+    const inputPath = argv[laneBInputIdx + 1];
+    if (!inputPath) {
+      console.error('--lane-b-input requires a file path argument');
+      process.exit(1);
+    }
+    const absInput = path.isAbsolute(inputPath) ? inputPath : path.join(REPO_ROOT, inputPath);
+    const ingested = JSON.parse(fs.readFileSync(absInput, 'utf8'));
+    const census = loadExisting();
+    census.lane_b = {
+      results: ingested,
+      lane_b_source: 'local-twin bolt://127.0.0.1:7690',
+      key_tier_lane_b: 'admin',
+      drift_caveat: true,
+      used_c2_fallback: !!(ingested.C2a || ingested.C2b || ingested.C2c || ingested.C2d) && !ingested.C2,
+    };
+    census.meta = Object.assign({}, census.meta, {
+      key_tier_lane_b: 'admin',
+      lane_b_source: 'local-twin bolt://127.0.0.1:7690',
+    });
+    writeOut(census);
+    console.log('Lane B ingested from local-twin file: ' + inputPath);
+    return;
+  }
+
+  console.error(
+    'Usage: node scripts/build-brain-census.cjs --lane-a | --lane-b | --lane-b-input <path> | --render-only'
+  );
+  process.exit(1);
+}
+
+module.exports = {
+  CENSUS_QUERIES,
+  scanMethodologyCommands,
+  computeGapTable,
+  renderMarkdown,
+  serializeArtifactJson,
+  brainCall,
+  BRAIN_URL,
+  GENERATED_NOTE,
+};
+
+if (require.main === module) {
+  main().catch((e) => {
+    console.error('FAIL: ' + (e && e.stack ? e.stack : e));
+    process.exit(1);
+  });
+}