@ghostlygawd/codeweb 0.9.0

package/scripts/bench.mjs

@@ -0,0 +1,133 @@
+#!/usr/bin/env node
+// codeweb bench — run the grep-vs-codeweb comparison on YOUR repo, graded by YOUR compiler.
+//
+// The published oracle A/B (bench/results/oracle-ab.json) is a paper artifact; this is the same
+// engine (scripts/lib/bench-core.mjs, shared verbatim) packaged as a product command, so anyone
+// can generate their own evidence — and a recall dip on a real repo is a bug report with a
+// built-in reproducer.
+//
+//   Q1  "who depends on X?"        cost per task + (TS repos) recall/precision vs the compiler
+//   Q2  "what transitively breaks?" one budgeted impact call vs the recursive grep loop
+//
+// usage: bench.mjs <graph.json> [--scope <rel>] [--n 30] [--seed 42] [--json] [--out <file>]
+//   --scope   repo-relative dir to sample from (default: the whole mapped root)
+//   --n       symbols to sample (default 30; deterministic given --seed)
+//   --json    emit the full result object instead of the text summary
+//   --out     also write the result object to a file
+// Optional at runtime: ripgrep (grep arm; absent -> reported unavailable) and the `typescript`
+// package resolvable from cwd or TS_MODULE (compiler grading; absent -> cost-only).
+
+import { writeFileSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { die, emitJson, emitText, loadGraph } from './lib/cli.mjs';
+import { buildIndex } from './lib/graph-ops.mjs';
+import { loadTypescript, rgAvailable, sampleSymbols, makeTsOracle, codewebArm, grepArm, score, impactCost, mean, aggArm, aggImpact } from './lib/bench-core.mjs';
+
+const argv = process.argv.slice(2);
+const USAGE = 'usage: bench.mjs <graph.json> [--scope <rel>] [--n 30] [--seed 42] [--json] [--out <file>]';
+let n = 30, seed = 42, scopeArg = '', outPath = null, asJson = false; const pos = [];
+for (let i = 0; i < argv.length; i++) {
+  if (argv[i] === '--n') n = Math.max(1, parseInt(argv[++i], 10) || 30);
+  else if (argv[i] === '--seed') seed = parseInt(argv[++i], 10) || 42;
+  else if (argv[i] === '--scope') scopeArg = String(argv[++i] || '').replace(/^\/+|\/+$/g, '');
+  else if (argv[i] === '--out') outPath = argv[++i];
+  else if (argv[i] === '--json') asJson = true;
+  else if (!argv[i].startsWith('-')) pos.push(argv[i]);
+}
+const { graph } = loadGraph(pos[0], { usage: USAGE });
+const index = buildIndex(graph);
+const root = graph.meta?.root;
+if (!root || !existsSync(root)) die('graph.meta.root missing or absent on disk — bench needs the mapped source (rebuild the graph where the source lives)', 2);
+const srcRoot = scopeArg ? join(root, scopeArg) : root;
+if (!existsSync(srcRoot)) die(`--scope not found under the mapped root: ${srcRoot}`, 2);
+const scope = scopeArg;
+
+const { sample } = sampleSymbols(graph, index, { scope, n, seed });
+if (!sample.length) die(`no benchable symbols in scope "${scope || '(whole repo)'}" — need exported product functions/classes with fan-in >= 3 (is the graph fresh? is the scope right?)`, 2);
+
+// oracle: optional, TS-only (the compiler grades its own language)
+const ts = loadTypescript();
+let oracle = null, oracleReason = 'typescript not resolvable from cwd (npm i typescript, or set TS_MODULE)';
+if (ts) {
+  const o = makeTsOracle(ts, { srcRoot, graphRoot: root });
+  if (o.tsFileCount > 0) { oracle = o; oracleReason = null; }
+  else oracleReason = 'no TypeScript files in scope — cost-only (grading needs a compiler oracle)';
+}
+
+const hasRg = rgAvailable();
+const rows = [];
+let oracleExcluded = 0;
+for (const node of sample) {
+  const truth = oracle ? oracle.oracleFiles(node) : undefined; // undefined = ungraded run, null = oracle couldn't resolve
+  if (oracle && !truth) { oracleExcluded++; continue; }
+  const cw = codewebArm(graph, index, node);
+  cw.files.delete(node.file);
+  const gr = hasRg ? grepArm(node, { srcRoot, graphRoot: root }) : null;
+  const row = {
+    symbol: node.id, label: node.label,
+    codeweb: { files: cw.files.size, bytes: cw.bytes, pages: cw.pages },
+    grep: gr ? { files: gr.files.size, bytes: gr.bytes } : null,
+    impact: impactCost(graph, index, node, { srcRoot }),
+  };
+  if (oracle) {
+    const truthNoDecl = new Set([...truth].filter((f) => f !== node.file));
+    row.truthFiles = truthNoDecl.size;
+    Object.assign(row.codeweb, score(cw.files, truthNoDecl));
+    if (gr) Object.assign(row.grep, score(gr.files, truthNoDecl));
+  }
+  rows.push(row);
+}
+if (!rows.length) die(`oracle excluded all ${sample.length} sampled symbol(s) — nothing gradable (try a different --scope or --seed)`, 2);
+
+const kb = (b) => `${Math.round(b / 1024 * 10) / 10}KB`;
+const result = {
+  design: 'grep-vs-codeweb on this repo, same engine as bench/results/oracle-ab.json: control=rg dump, treatment=codeweb --dependents (budgeted pages of 20); blast radius = one codeweb_impact call vs the graph-assisted recursive grep loop; grading (when available) = TS LanguageService references, file-level.',
+  corpus: { root, scope: scope || '(whole repo)', sampled: sample.length, benched: rows.length, oracleExcluded, seed },
+  oracle: oracle ? { available: true, gradedBy: 'typescript LanguageService' } : { available: false, reason: oracleReason },
+  grepAvailable: hasRg,
+  codeweb: oracle && hasRg ? aggArm(rows, 'codeweb') : {
+    meanBytes: Math.round(mean(rows.map((r) => r.codeweb.bytes))),
+    totalBytes: rows.reduce((s, r) => s + r.codeweb.bytes, 0),
+    ...(oracle ? { meanRecall: +mean(rows.map((r) => r.codeweb.recall)).toFixed(3), meanPrecision: +mean(rows.map((r) => r.codeweb.precision)).toFixed(3) } : {}),
+  },
+  grep: hasRg ? (oracle ? aggArm(rows, 'grep') : {
+    meanBytes: Math.round(mean(rows.map((r) => r.grep.bytes))),
+    totalBytes: rows.reduce((s, r) => s + r.grep.bytes, 0),
+  }) : { unavailable: 'ripgrep (rg) not on PATH' },
+  impact: hasRg ? aggImpact(rows) : {
+    meanImpactSize: Math.round(mean(rows.map((r) => r.impact.impactSize))),
+    codewebMeanBytes: Math.round(mean(rows.map((r) => r.impact.codewebBytes))),
+    grepUnavailable: 'ripgrep (rg) not on PATH',
+  },
+  tokensNote: 'tokens ~ bytes/4; cost = what the channel injects into the agent context',
+  rows,
+};
+if (outPath) writeFileSync(resolve(outPath), JSON.stringify(result, null, 2));
+if (asJson) { emitJson(result); }
+else {
+  const L = [];
+  L.push(`codeweb bench — ${root}  (scope: ${scope || 'whole repo'}, ${rows.length} symbols, seed ${seed})`);
+  L.push('');
+  L.push('  Q1 "who depends on X?" — context cost per task');
+  L.push(`    codeweb  ${kb(result.codeweb.meanBytes)}/task  (budgeted pages, as MCP serves it)`);
+  if (hasRg) {
+    const ratio = result.codeweb.meanBytes ? (result.grep.meanBytes / result.codeweb.meanBytes).toFixed(1) : '—';
+    L.push(`    grep     ${kb(result.grep.meanBytes)}/task  (the rg dump an agent must read)   ${ratio}x more context`);
+  } else L.push('    grep     unavailable (install ripgrep to compare)');
+  if (oracle) {
+    L.push(`    graded by the TypeScript compiler (${rows.length}/${sample.length} oracle-resolvable):`);
+    L.push(`      codeweb  recall ${result.codeweb.meanRecall}  precision ${result.codeweb.meanPrecision}`);
+    if (hasRg) {
+      L.push(`      grep     recall ${result.grep.meanRecall}  precision ${result.grep.meanPrecision}`);
+      const wins = rows.filter((r) => r.codeweb.recall >= r.grep.recall).length;
+      L.push(`      per-task recall: codeweb >= grep on ${wins}/${rows.length}`);
+    }
+  } else L.push(`    ungraded — ${oracleReason}`);
+  L.push('');
+  L.push('  Q2 "what transitively breaks?" — blast radius');
+  L.push(`    codeweb  ${kb(result.impact.codewebMeanBytes)}/call  (one budgeted impact call, mean closure ${result.impact.meanImpactSize} symbols)`);
+  if (hasRg) L.push(`    grep     ${kb(result.impact.grepMeanBytes)}/loop  (${result.impact.grepMeanRounds} rounds, graph-assisted lower bound)   ${result.impact.costRatio}x more context`);
+  else L.push('    grep     unavailable (install ripgrep to compare)');
+  if (outPath) { L.push(''); L.push(`  full rows: ${resolve(outPath)}`); }
+  emitText(L.join('\n'));
+}

package/scripts/brief.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+// codeweb brief — the day-one page: what this repo is, where things live, what everything
+// hangs off, where the tests are, what's already known to be wrong. The first call of a
+// session (or injected automatically by hooks/session-brief.mjs), replacing the exploratory
+// token burn with ~2KB of pre-computed orientation.
+//
+//   node scripts/brief.mjs <graph.json> [--json]
+
+import { die, emitJson, emitText, loadGraph, checkStaleness } from './lib/cli.mjs';
+import { buildIndex } from './lib/graph-ops.mjs';
+import { buildBrief, renderBrief } from './lib/brief-core.mjs';
+import { attachActivity } from './lib/stats.mjs';
+
+const USAGE = 'usage: brief.mjs <graph.json> [--json]';
+const argv = process.argv.slice(2);
+let json = false; const pos = [];
+for (const t of argv) { if (t === '--json') json = true; else if (!t.startsWith('-')) pos.push(t); else die(USAGE, 2); }
+
+const { graph, abs } = loadGraph(pos[0], { usage: USAGE });
+const brief = attachActivity(buildBrief(graph, buildIndex(graph)), abs);
+const stale = checkStaleness(graph);
+if (stale) brief.stale = stale;
+
+if (json) { emitJson(brief); } else {
+  let text = renderBrief(brief);
+  if (stale) text += `\nnote: graph is stale for ${stale.count}+ file(s) — run codeweb_refresh for current numbers.`;
+  emitText(text);
+}

package/scripts/build-report.mjs

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+// codeweb report renderer: graph.json -> self-contained interactive report.html
+//
+// Usage:
+//   node build-report.mjs [path/to/graph.json] [--out report.html] [--open]
+//
+// Reads a codeweb graph (see skills/codebase-anatomy/references/graph-schema.md), normalizes it
+// (defaults, dangling-edge removal, computed stats), injects it into report-template.html, and
+// writes a single self-contained HTML file. No network/CDN required.
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execSync } from 'node:child_process';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+function parseArgs(argv) {
+  const a = { _: [], open: false, out: null, md: true };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === '--open') a.open = true;
+    else if (t === '--no-md') a.md = false;
+    else if (t === '--out') a.out = argv[++i];
+    else a._.push(t);
+  }
+  return a;
+}
+
+const args = parseArgs(process.argv.slice(2));
+const graphPath = resolve(args._[0] || join('.codeweb', 'graph.json'));
+
+if (!existsSync(graphPath)) {
+  console.error(`[codeweb] graph not found: ${graphPath}`);
+  process.exit(1);
+}
+
+let graph;
+try {
+  graph = JSON.parse(readFileSync(graphPath, 'utf8'));
+} catch (e) {
+  console.error(`[codeweb] invalid JSON in ${graphPath}: ${e.message}`);
+  process.exit(1);
+}
+
+// --- normalize ---
+graph.meta = graph.meta || {};
+graph.nodes = Array.isArray(graph.nodes) ? graph.nodes : [];
+graph.edges = Array.isArray(graph.edges) ? graph.edges : [];
+graph.domains = Array.isArray(graph.domains) ? graph.domains : [];
+graph.overlaps = Array.isArray(graph.overlaps) ? graph.overlaps : [];
+
+for (const n of graph.nodes) if (!n.domain) n.domain = 'unassigned';
+
+const ids = new Set(graph.nodes.map((n) => n.id));
+const beforeEdges = graph.edges.length;
+graph.edges = graph.edges.filter((e) => ids.has(e.from) && ids.has(e.to));
+const droppedEdges = beforeEdges - graph.edges.length;
+
+if (graph.domains.length === 0) {
+  const counts = {};
+  for (const n of graph.nodes) counts[n.domain] = (counts[n.domain] || 0) + 1;
+  graph.domains = Object.entries(counts).map(([name, nodes]) => ({ name, nodes, summary: '' }));
+}
+
+graph.meta.generatedAt = new Date().toISOString();
+graph.meta.stats = {
+  files: new Set(graph.nodes.map((n) => n.file).filter(Boolean)).size,
+  nodes: graph.nodes.length,
+  edges: graph.edges.length,
+  domains: graph.domains.length,
+  overlaps: graph.overlaps.length,
+};
+
+// Persist the normalized graph back to disk so graph.json matches what the report renders:
+// generatedAt, the computed meta.stats, default-filled domains, and the dangling-edge drop
+// become part of the machine-readable artifact (they previously lived only in report.html/md).
+// Minified, matching the upstream writers (cluster3.mjs / overlap.mjs).
+writeFileSync(graphPath, JSON.stringify(graph));
+
+// --- render ---
+const templatePath = join(here, 'report-template.html');
+if (!existsSync(templatePath)) {
+  console.error(`[codeweb] template missing: ${templatePath}`);
+  process.exit(1);
+}
+const template = readFileSync(templatePath, 'utf8');
+
+// The report is self-contained and shareable (teammate, blog post, GitHub Pages), so it must not
+// embed the absolute LOCAL source path. meta.root is only a disk pointer the query tools use to
+// read bodies — graph.json on disk (written above) keeps it; the template renders meta.target,
+// never meta.root. Strip it from the embedded copy without mutating the on-disk graph.
+const embed = { ...graph, meta: { ...graph.meta } };
+delete embed.meta.root;
+
+// Escape "<" so the JSON can live inside a <script type="application/json"> tag without ever
+// forming "</script>". Inside JSON, "<" only appears within string values, where < is a
+// valid escape that decodes back to "<".
+const json = JSON.stringify(embed).replace(/</g, '\\u003c');
+
+// Function replacement avoids String.replace's $-pattern interpretation in the payload.
+const html = template.replace('__GRAPH_DATA__', () => json);
+
+const outPath = args.out ? resolve(args.out) : join(dirname(graphPath), 'report.html');
+writeFileSync(outPath, html);
+
+const s = graph.meta.stats;
+console.log(`[codeweb] wrote ${outPath}`);
+console.log(
+  `[codeweb] ${s.nodes} nodes, ${s.edges} edges, ${s.domains} domains, ${s.overlaps} overlaps` +
+    (droppedEdges ? ` (dropped ${droppedEdges} dangling edges)` : '')
+);
+console.log(`[codeweb] updated ${graphPath} (meta.generatedAt + meta.stats persisted)`);
+
+if (args.md) {
+  const mdPath = join(dirname(outPath), 'report.md');
+  writeFileSync(mdPath, buildMermaid(graph));
+  console.log(`[codeweb] wrote ${mdPath}`);
+}
+
+if (args.open) {
+  const cmd =
+    process.platform === 'win32'
+      ? `start "" "${outPath}"`
+      : process.platform === 'darwin'
+        ? `open "${outPath}"`
+        : `xdg-open "${outPath}"`;
+  try {
+    execSync(cmd, { stdio: 'ignore', shell: true });
+  } catch {
+    /* opening is best-effort */
+  }
+}
+
+// --- Mermaid / markdown fallback (renders on GitHub, no JS) ---
+function mmId(s) { return 'd_' + String(s).replace(/[^A-Za-z0-9_]/g, '_'); }
+function buildMermaid(g) {
+  const byId = new Map((g.nodes || []).map((n) => [n.id, n]));
+  const m = g.meta || {}, st = m.stats || {};
+  const out = [
+    '# codeweb — system map (static)',
+    '',
+    '> Auto-generated by codeweb. Open `report.html` for the interactive version.',
+    '',
+    `**Target:** ${m.target || '?'}${m.mode ? ' · ' + m.mode : ''}  ·  ` +
+      `${st.nodes || 0} nodes · ${st.edges || 0} edges · ${st.domains || 0} domains · ${st.overlaps || 0} overlaps` +
+      `${m.engine ? '  ·  engine: ' + m.engine : ''}`,
+    '',
+    '## Domain graph',
+    '',
+    '```mermaid',
+    'flowchart LR',
+  ];
+  const cnt = {};
+  (g.nodes || []).forEach((n) => { cnt[n.domain] = (cnt[n.domain] || 0) + 1; });
+  const domains = (g.domains && g.domains.length ? g.domains.map((d) => d.name) : Object.keys(cnt));
+  domains.forEach((d) => out.push(`  ${mmId(d)}["${d} (${cnt[d] || 0})"]`));
+  const agg = new Map();
+  (g.edges || []).forEach((e) => {
+    const a = byId.get(e.from), b = byId.get(e.to);
+    if (!a || !b || a.domain === b.domain) return;
+    const k = a.domain < b.domain ? a.domain + '|' + b.domain : b.domain + '|' + a.domain;
+    agg.set(k, (agg.get(k) || 0) + (e.weight || 1));
+  });
+  for (const [k, w] of agg) { const p = k.split('|'); out.push(`  ${mmId(p[0])} ===|${w}| ${mmId(p[1])}`); }
+  out.push('```', '', '## Overlap / consolidation opportunities', '');
+  const ov = g.overlaps || [];
+  if (!ov.length) { out.push('_None recorded._', ''); }
+  else {
+    const rank = { high: 0, medium: 1, low: 2 };
+    ov.slice().sort((a, b) => (rank[a.severity] == null ? 3 : rank[a.severity]) - (rank[b.severity] == null ? 3 : rank[b.severity]))
+      .forEach((o, i) => {
+        out.push(`### ${i + 1}. ${o.title || '(untitled)'} — \`${o.severity || 'low'}\``);
+        out.push(`- **kind:** ${o.kind || '?'}  ·  **domains:** ${(o.domains || []).join(', ')}`);
+        if (o.evidence) out.push(`- **evidence:** ${o.evidence}`);
+        if (o.recommendation) out.push(`- **→ consolidate:** ${o.recommendation}`);
+        if ((o.nodes || []).length) out.push(`- **nodes:** ${o.nodes.map((n) => '`' + n + '`').join(', ')}`);
+        out.push('');
+      });
+  }
+  return out.join('\n');
+}

package/scripts/campaign.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+// codeweb campaign CLI (F5) — run the three advisors (optimize / deadcode / break-cycles) and compose
+// their outputs into ONE ordered, gated, ROI-ranked optimization worklist with cumulative projected
+// deltas. Read-only PLAN: it never writes source — each step is for the agent + gate to execute. Built
+// on ./lib/campaign.mjs. The advisors stay authoritative (one truth); campaign only orchestrates.
+//
+// Usage: node campaign.mjs <graph.json> [--json] [--budget N] [--git]   (or set CODEWEB_WS)
+// Exit: 0 ok (advisory), 2 usage/IO.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import { resolve, dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { normalizeGraph } from './lib/graph-ops.mjs';
+import { planCampaign } from './lib/campaign.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const USAGE = 'usage: campaign.mjs <graph.json> [--json] [--budget N] [--git]   (or set CODEWEB_WS)';
+import { die, emitJson, finish, loadGraph } from './lib/cli.mjs';
+
+const argv = process.argv.slice(2);
+let json = false, budget = Infinity, git = false; const pos = [];
+for (let i = 0; i < argv.length; i++) {
+  const t = argv[i];
+  if (t === '--json') json = true;
+  else if (t === '--budget') budget = Math.max(0, parseInt(argv[++i], 10) || 0);
+  else if (t === '--git') git = true;
+  else if (!t.startsWith('-')) pos.push(t);
+}
+const { graph, abs } = loadGraph(pos[0], { usage: USAGE });
+
+// run each advisor as its tested artifact (--json); a failed advisor degrades to empty (the campaign
+// still composes whatever the others found).
+const advise = (script, extra = []) => {
+  const r = spawnSync(process.execPath, [join(HERE, script), abs, ...extra, '--json'], { encoding: 'utf8', maxBuffer: 1 << 28 });
+  try { return JSON.parse(r.stdout); } catch { return null; }
+};
+const optimize = advise('optimize.mjs') || { opportunities: [] };
+const deadcode = advise('deadcode.mjs') || { safe: [] };
+const breakCycles = advise('break-cycles.mjs') || { cycles: [] };
+
+const plan = planCampaign(graph, { optimize, deadcode, breakCycles, budget });
+const t0 = plan.totals;
+const payload = {
+  target: graph.meta?.target || 'target',
+  summary: `${t0.steps} step(s): ${t0.cuts} cut, ${t0.deletes} delete, ${t0.merges} merge — projected -${t0.locReclaimed} LOC, ${t0.cyclesBroken} cycle(s) broken (gate-green in order)`,
+  ...plan,
+};
+
+if (json) { emitJson(payload); } else {
+
+const t = plan.totals;
+console.log(`codeweb campaign: ${payload.target} — ${t.steps} step(s): ${t.cuts} cut, ${t.deletes} delete, ${t.merges} merge`);
+console.log(`  projected: -${t.locReclaimed} LOC, ${t.cyclesBroken} cycle(s) broken (all steps stay gate-green in order)`);
+for (const s of plan.steps) {
+  const tag = s.type.toUpperCase().padEnd(6);
+  const what = s.type === 'cut' ? `${s.files.join(' <-> ')}` : s.type === 'delete' ? s.op.ids.join(', ') : `${s.op.ids.join(' + ')} -> ${s.op.into}`;
+  console.log(`  [${tag}] ${what}  (roi ${s.roi}; +${s.delta.locReclaimed} LOC, +${s.delta.cyclesBroken} cycle; cumulative -${s.cumulative.locReclaimed} LOC)`);
+}
+finish();
+}

package/scripts/check-consistency.mjs

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+/**
+ * Fail when codeweb's public comms disagree with the source of truth:
+ *  - a version string out of sync with package.json
+ *  - a documented MCP tool count != the actual TOOLS table in mcp-server.mjs
+ *  - a missing CHANGELOG entry for the current version
+ *
+ * This applies codeweb's own "fail on regression" philosophy to its marketing.
+ * Exit 1 on any problem, 0 when aligned. Read-only.
+ *
+ *   node scripts/check-consistency.mjs   (or: npm run check-consistency)
+ */
+import { dirname, join } from 'node:path';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { checkConsistency } from './release-utils.mjs';
+import { auditClaims } from './lib/claims-check.mjs';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const r = checkConsistency(ROOT);
+
+// Spec C: the claims audit — every evidence source cited by the ledger and the README must exist.
+// A receipt whose backing file is gone is a rotted claim, and rotted claims fail the build.
+try {
+  const product = JSON.parse(readFileSync(join(ROOT, 'site', 'data', 'product.json'), 'utf8'));
+  const readme = readFileSync(join(ROOT, 'README.md'), 'utf8');
+  const audit = auditClaims(ROOT, { product, readme });
+  if (!audit.ok) {
+    r.ok = false;
+    for (const m of audit.missing) r.problems.push(`claim source missing: ${m.where} cites "${m.source}"`);
+  }
+} catch (e) {
+  r.ok = false;
+  r.problems.push(`claims audit could not run: ${e.message}`);
+}
+
+if (r.ok) {
+  process.stdout.write(`check-consistency: OK — v${r.version}, ${r.count} tools, all surfaces aligned.\n`);
+  process.exit(0);
+}
+
+process.stderr.write(`check-consistency: ${r.problems.length} problem(s) for v${r.version} (${r.count} tools):\n`);
+for (const p of r.problems) process.stderr.write(`  x ${p}\n`);
+process.stderr.write('Fix with: node scripts/version-sync.mjs (then update CHANGELOG.md if needed)\n');
+process.exit(1);

package/scripts/ci-gate.mjs

@@ -0,0 +1,86 @@
+#!/usr/bin/env node
+// codeweb CI gate — fail a PR when an edit makes the structure worse.
+//
+//   node scripts/ci-gate.mjs --base <ref> [--repo <path>] [--target <subdir>] [--md <file>]
+//
+// Builds the BEFORE graph from a base ref (materialized in an ephemeral git worktree) and the AFTER
+// graph from the current working tree, then runs the diff regression gate. Exit 1 (listing the
+// regressions) when an edit introduces a new dependency cycle, a new duplication finding, or makes
+// an existing symbol lose all its callers; exit 0 otherwise; exit 2 on usage/IO error. Read-only
+// over the repo — the base worktree is removed afterwards. Reuses the canonical run.mjs pipeline and
+// the diff.mjs gate verbatim, so the gate's verdict matches `diff` exactly.
+//
+// --md writes the structural review as a PR-comment-ready markdown digest (lib/gate-md.mjs) —
+// best-effort: a digest failure never changes the gate's verdict.
+
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { gateComment } from './lib/gate-md.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+
+function parseArgs(argv) {
+  const a = { base: null, repo: '.', target: '.', md: null };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === '--base') a.base = argv[++i];
+    else if (t === '--repo') a.repo = argv[++i];
+    else if (t === '--target') a.target = argv[++i];
+    else if (t === '--md') a.md = argv[++i];
+  }
+  return a;
+}
+
+const opts = parseArgs(process.argv.slice(2));
+if (!opts.base) {
+  console.error('usage: ci-gate.mjs --base <ref> [--repo <path>] [--target <subdir>] [--md <file>]');
+  process.exit(2);
+}
+
+const repo = resolve(opts.repo);
+const node = process.execPath;
+const buildGraph = (srcDir, label, ws) => {
+  execFileSync(node, [join(HERE, 'run.mjs'), srcDir, '--target', label, '--out-dir', ws], { stdio: 'ignore' });
+  return join(ws, 'graph.json');
+};
+
+const base = mkdtempSync(join(tmpdir(), 'codeweb-gate-'));
+const afterWs = join(base, 'after'), beforeWs = join(base, 'before'), wt = join(base, 'wt');
+let code = 0;
+try {
+  // AFTER = the current working tree (what the PR proposes to merge)
+  const afterGraph = buildGraph(join(repo, opts.target), 'after', afterWs);
+  // BEFORE = the base ref, materialized read-only in an ephemeral worktree
+  const r = spawnSync('git', ['-C', repo, 'worktree', 'add', '--detach', '--force', wt, opts.base], { encoding: 'utf8' });
+  if (r.status !== 0) {
+    // throw (NOT process.exit) so the finally block still removes the worktree + temp dir — a bare
+    // process.exit() runs synchronously and skips finally, leaking the scratch dir on every failure.
+    throw new Error(`cannot create base worktree for "${opts.base}" (need full history — actions/checkout with fetch-depth: 0): ${r.stderr}`);
+  }
+  const beforeGraph = buildGraph(join(wt, opts.target), 'before', beforeWs);
+  // GATE — diff.mjs prints the delta + regressions and sets the exit code we propagate.
+  const d = spawnSync(node, [join(HERE, 'diff.mjs'), beforeGraph, afterGraph], { stdio: 'inherit' });
+  if (d.status == null) {
+    console.error(`[codeweb] gate inconclusive — diff was terminated${d.signal ? ` by ${d.signal}` : ''}`);
+    code = 1;
+  } else {
+    code = d.status;
+  }
+  // PR-comment digest — a second diff over the already-built graphs (ms), rendered budgeted
+  if (opts.md) {
+    try {
+      const dj = spawnSync(node, [join(HERE, 'diff.mjs'), beforeGraph, afterGraph, '--json'], { encoding: 'utf8', maxBuffer: 1 << 26 });
+      writeFileSync(opts.md, gateComment(JSON.parse(dj.stdout)));
+    } catch (e) { console.error(`[codeweb] gate comment not written: ${(e && e.message) || e}`); }
+  }
+} catch (e) {
+  console.error(`[codeweb] gate error: ${(e && e.message) || e}`);
+  code = 2;
+} finally {
+  try { spawnSync('git', ['-C', repo, 'worktree', 'remove', '--force', wt]); } catch { /* best-effort */ }
+  try { rmSync(base, { recursive: true, force: true }); } catch { /* best-effort */ }
+}
+process.exit(code);

package/scripts/cluster3.mjs

@@ -0,0 +1,112 @@
+// codeweb — clustering v3 (directory-anchored, dir-seeded label propagation + light de-hub)
+// Names domains after the repo's own module structure (directories) instead of utility symbols
+// (the old "lib · log" failure). Mechanism: (1) seed each node's label with its 2-level
+// directory, (2) run label-propagation that migrates a node across dirs only where call-cohesion
+// clearly pulls it (ties keep the current dir, so the directory prior wins), (3) name each
+// domain by its dominant member directory.
+//
+// De-hub (HUB_INDEG): exclude high-in-degree nodes from the clustering adjacency. This began as
+// a workaround for false super-hubs the extractor used to fabricate (unresolved `log()`/`get()`
+// wired to the first global def — e.g. discord/ecc-bot.mjs:log at in-degree 127). That bug is
+// fixed at extraction now, so de-hub no longer changes the domain COUNT (17 either way). But it
+// still does real work: the surviving GENUINE utility hubs (utils.log, utils.readFile,
+// state-store.get) otherwise bridge their callers' home directory into lib — measured at ~20
+// nodes (mostly hooks/* calling lib utils) pulled out of their home dir when de-hub is removed.
+// Keeping it makes domain assignment track directory structure, so it stays.
+
+import { readFileSync, writeFileSync } from 'node:fs';
+
+const WS = process.env.CODEWEB_WS || '.live';   // per-target workspace dir (orchestrator sets this)
+const FRAG = `${WS}/fragment.json`;
+const GRAPH = `${WS}/graph.json`;
+// exclude genuine utility hubs from clustering adjacency (keeps callers in their home dir; see header).
+// CODEWEB_HUB_INDEG overrides the threshold for A/B regression testing of the de-hub decision
+// (mirrors extract-symbols' CODEWEB_LEGACY_FALLBACK lever): set it absurdly high to disable de-hub
+// and watch callers bleed into their hubs' home dir. Default 12 — the shipped behavior is unchanged.
+const hubOverride = Number(process.env.CODEWEB_HUB_INDEG);
+const HUB_INDEG = Number.isFinite(hubOverride) ? hubOverride : 12; // honor any finite override (incl. 0); unset -> 12
+const PASSES = 12;
+
+const dir2 = (file) => {
+  const p = file.split('/');
+  if (p.length === 1) return '(root)';
+  return p.slice(0, Math.min(2, p.length - 1)).join('/');
+};
+const pretty = (label) => (label === '(root)' ? 'CLI scripts (root)' : label);
+
+const frag = JSON.parse(readFileSync(FRAG, 'utf8'));
+const nodes = frag.nodes, edges = frag.edges;
+const fragMeta = frag.meta || {};
+const id2i = new Map(nodes.map((n, i) => [n.id, i]));
+
+// in-degree -> identify hubs to exclude from the clustering adjacency (also reused for summaries)
+const indeg = nodes.map(() => 0);
+for (const e of edges) { const b = id2i.get(e.to); if (b != null) indeg[b]++; }
+const isHub = indeg.map((d) => d >= HUB_INDEG);
+
+// de-hubbed undirected adjacency (drop self-loops and any edge touching a hub)
+const adj = nodes.map(() => []);
+for (const e of edges) {
+  const a = id2i.get(e.from), b = id2i.get(e.to);
+  if (a == null || b == null || a === b) continue;
+  if (isHub[a] || isHub[b]) continue;
+  adj[a].push(b); adj[b].push(a);
+}
+
+// seed labels with directory, then propagate (ties keep current => directory prior wins)
+let label = nodes.map((n) => dir2(n.file));
+for (let pass = 0; pass < PASSES; pass++) {
+  let changed = 0;
+  for (let i = 0; i < nodes.length; i++) {
+    if (isHub[i] || !adj[i].length) continue;
+    const cnt = new Map();
+    for (const j of adj[i]) cnt.set(label[j], (cnt.get(label[j]) || 0) + 1);
+    let best = label[i], bc = cnt.get(label[i]) || 0;
+    for (const [l, c] of cnt) if (c > bc) { best = l; bc = c; }
+    if (best !== label[i]) { label[i] = best; changed++; }
+  }
+  if (!changed) break;
+}
+
+// assign domains; name each cluster by its dominant member directory (robust if a label migrated)
+const groups = new Map();
+nodes.forEach((n, i) => { if (!groups.has(label[i])) groups.set(label[i], []); groups.get(label[i]).push(i); });
+const nameOf = new Map();
+for (const [lbl, idxs] of groups) {
+  const dc = {}; idxs.forEach((i) => { const d = dir2(nodes[i].file); dc[d] = (dc[d] || 0) + 1; });
+  const domDir = Object.entries(dc).sort((a, b) => b[1] - a[1])[0][0];
+  nameOf.set(lbl, pretty(domDir));
+}
+nodes.forEach((n, i) => { n.domain = nameOf.get(label[i]); });
+
+// domain summaries — deterministic DESCRIPTIVE labels: size, file count, the key symbols (exported
+// preferred, then fan-in), and the role composition when a domain is mostly supporting code. This is
+// the "what does this area do" one-liner the report + reading-order surface.
+const byDomain = new Map();
+nodes.forEach((n, i) => { if (!byDomain.has(n.domain)) byDomain.set(n.domain, []); byDomain.get(n.domain).push(i); });
+const domains = [...byDomain.entries()].map(([name, idxs]) => {
+  const top = idxs.slice()
+    .sort((a, b) => (nodes[b].exports === true) - (nodes[a].exports === true) || indeg[b] - indeg[a])
+    .slice(0, 5).map((i) => nodes[i].label).filter((l) => l !== '<module>');
+  const files = new Set(idxs.map((i) => nodes[i].file)).size;
+  const roles = {};
+  idxs.forEach((i) => { const r = nodes[i].role || 'product'; roles[r] = (roles[r] || 0) + 1; });
+  const domRole = Object.entries(roles).sort((a, b) => b[1] - a[1])[0][0];
+  const roleNote = domRole !== 'product' ? ` (mostly ${domRole} code)` : '';
+  return { name, nodes: idxs.length, role: domRole, summary: `${idxs.length} symbols across ${files} file(s)${roleNote}; key: ${top.join(', ')}.` };
+}).sort((a, b) => b.nodes - a.nodes);
+
+const graph = {
+  meta: { ...fragMeta, mode: 'internal', depth: 'symbol', engine: `${fragMeta.engine || 'regex'} + de-hubbed dir-seeded call-cohesion clustering` },
+  nodes, edges, domains, overlaps: [],
+};
+writeFileSync(GRAPH, JSON.stringify(graph));
+
+// stats
+const isolated = adj.filter((a) => a.length === 0).length;
+const hubCount = isHub.filter(Boolean).length;
+console.log(`hubs stripped (indeg>=${HUB_INDEG}): ${hubCount}`);
+console.log(`domains: ${domains.length}  (was 32, hub-named)`);
+console.log(`isolated-after-dehub: ${isolated} (${Math.round(isolated / nodes.length * 100)}%)`);
+console.log('--- top 18 domains ---');
+for (const d of domains.slice(0, 18)) console.log(String(d.nodes).padStart(4), d.name);