@ghostlygawd/codeweb 0.9.0

package/scripts/lib/brief-core.mjs

@@ -0,0 +1,92 @@
+// brief-core — the day-one briefing: everything an agent burns its first 20-50k tokens
+// discovering, pre-computed from the graph into one ~2KB page. Where things live, what the
+// repo hangs off, where the tests are, what's already known to be wrong. Injected at session
+// start (hooks/session-brief.mjs), callable any time (codeweb_brief / scripts/brief.mjs).
+
+import { fileCycles, orphans, fanInOf } from './graph-ops.mjs';
+
+const CONFIRMED = new Set(['high', 'medium']);
+
+/** Assemble the briefing object from a normalized graph + index. Pure; budgeting built in. */
+export function buildBrief(graph, index) {
+  const nodes = graph.nodes || [];
+  const product = nodes.filter((n) => n.role === 'product' && n.kind !== 'module');
+  const files = new Set(nodes.map((n) => n.file));
+  const roles = {};
+  for (const n of nodes) roles[n.role || 'product'] = (roles[n.role || 'product'] || 0) + 1;
+
+  const loadBearing = product
+    .slice().sort((a, b) => fanInOf(index, b.id, true) - fanInOf(index, a.id, true) || (a.id < b.id ? -1 : 1)).slice(0, 10)
+    .filter((n) => fanInOf(index, n.id, true) > 0)
+    .map((n) => ({ id: n.id, label: n.label, fanIn: fanInOf(index, n.id, true), at: `${n.file}:${n.line}` }));
+
+  // entry points: exported product symbols nobody in-repo calls but which call a lot — the
+  // places execution starts (CLIs, handlers, public surface). Heuristic, labeled as such.
+  const outDegree = (id) => index.callOut?.get(id)?.size || 0;
+  const entryPoints = product
+    .filter((n) => n.exports && fanInOf(index, n.id, true) === 0 && outDegree(n.id) >= 2)
+    .sort((a, b) => outDegree(b.id) - outDegree(a.id) || (a.id < b.id ? -1 : 1))
+    .slice(0, 5)
+    .map((n) => ({ label: n.label, at: `${n.file}:${n.line}`, callsOut: outDegree(n.id) }));
+
+  const testNodes = nodes.filter((n) => n.role === 'test');
+  const testDirs = {};
+  for (const n of testNodes) {
+    const d = n.file.includes('/') ? n.file.slice(0, n.file.lastIndexOf('/')) : '.';
+    testDirs[d] = (testDirs[d] || 0) + 1;
+  }
+  const topTestDirs = Object.entries(testDirs).sort((a, b) => b[1] - a[1]).slice(0, 3).map(([d]) => d);
+
+  const domains = (graph.domains || [])
+    .filter((d) => (d.role || 'product') === 'product')
+    .sort((a, b) => (b.nodes || 0) - (a.nodes || 0)).slice(0, 6)
+    .map((d) => ({ name: d.name, nodes: d.nodes, summary: d.summary || '' }));
+
+  const dup = (graph.overlaps || []).filter((o) => o.kind !== 'interface-pattern' && (o.confidence == null || CONFIRMED.has(o.confidence))).length;
+  const cyc = fileCycles(graph).length;
+  const orph = orphans(graph, index).length;
+
+  return {
+    target: graph.meta?.target || null,
+    root: graph.meta?.root || null,
+    generatedAt: graph.meta?.generatedAt || null,
+    languages: graph.meta?.languages || [],
+    size: { symbols: nodes.length, edges: (graph.edges || []).length, files: files.size, domains: (graph.domains || []).length },
+    roles,
+    domains,
+    loadBearing,
+    entryPoints,
+    tests: { symbols: testNodes.length, dirs: topTestDirs },
+    findings: { duplications: dup, cycles: cyc, orphanCandidates: orph },
+  };
+}
+
+/** One-page text rendering (the session-start injection format). */
+export function renderBrief(b) {
+  const L = [];
+  L.push(`codeweb brief — ${b.target || b.root || 'mapped repo'}: ${b.size.symbols} symbols / ${b.size.files} files / ${b.size.domains} domains (${(b.languages || []).join(', ') || 'unknown languages'})`);
+  if (b.domains.length) {
+    L.push('areas:');
+    for (const d of b.domains) L.push(`  - ${d.name} (${d.nodes}): ${d.summary}`);
+  }
+  if (b.loadBearing.length) {
+    L.push(`load-bearing (most depended-on — check impact before touching): ${b.loadBearing.slice(0, 6).map((s) => `${s.label}×${s.fanIn}`).join(', ')}`);
+  }
+  if (b.entryPoints.length) {
+    L.push(`entry points (heuristic): ${b.entryPoints.map((e) => `${e.label} @ ${e.at}`).join('; ')}`);
+  }
+  L.push(`tests: ${b.tests.symbols} test symbol(s)${b.tests.dirs.length ? ` under ${b.tests.dirs.join(', ')}` : ''}`);
+  const f = b.findings;
+  L.push(`known issues: ${f.duplications} duplication finding(s), ${f.cycles} file cycle(s), ${f.orphanCandidates} orphan candidate(s)`);
+  if (b.activity) {
+    const c = b.activity.counters;
+    const bits = [];
+    if (c.cardsDelivered) bits.push(`${c.cardsDelivered} pre-edit card(s)`);
+    if (c.cardCallersFollowed) bits.push(`${c.cardCallersFollowed} card-named caller(s) followed`);
+    if (c.regressionsFlagged) bits.push(`${c.regressionsFlagged} regression(s) flagged`);
+    if (c.queriesServed) bits.push(`${c.queriesServed} queries served`);
+    if (bits.length) L.push(`codeweb this month: ${bits.join(' · ')} (full receipt: scripts/stats.mjs)`);
+  }
+  L.push('ask codeweb before guessing: codeweb_find "<concept>" → codeweb_explain <id> → codeweb_context <id>.');
+  return L.join('\n');
+}

package/scripts/lib/campaign.mjs

@@ -0,0 +1,73 @@
+// codeweb optimization campaign planner (F5) — compose the three existing advisors (optimize /
+// deadcode / break-cycles; each stays authoritative — one truth) into ONE ordered, cumulatively
+// pre-flighted worklist with projected cumulative deltas. This is the "auto-optimize at any scale"
+// deliverable: a big repo becomes a verified, conflict-free, prioritized refactor backlog the agent
+// executes step by step. Read-only PLAN — execution stays with the agent + the gate. Pure.
+//
+// Phase order (CMP-ORDER): cuts -> deletes -> merges. Cuts are advisory (a manual dependency
+// inversion, not a node op) and go first so a merge blocked by a cycle is unblocked first. Deletes of
+// dead code only remove edges, so they can never introduce a cycle. Merges are pre-flighted against
+// the graph WITH all prior steps applied (CMP-GREEN-CHAIN) — a merge that would introduce a file cycle
+// is dropped, so applying the whole plan in order never creates a cycle absent at the start.
+
+import { normalizeGraph, fileCycles, applyEdit, buildIndex, chooseCanonical } from './graph-ops.mjs';
+
+const byRoiThenId = (a, b) => b.roi - a.roi || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+
+export function planCampaign(graph, { optimize = { opportunities: [] }, deadcode = { safe: [] }, breakCycles = { cycles: [] }, budget = Infinity } = {}) {
+  const g0 = normalizeGraph(structuredClone(graph));
+  // "New coupling" is judged by CONTAINMENT, not by the cycle's sorted-file key: an after-cycle is new
+  // only if its files were NOT all already mutually cyclic. (A merge/delete that contracts an existing
+  // SCC changes its key but introduces no new coupling — the same subtlety apply-edit.test pins.)
+  const baseSets = fileCycles(g0).map((c) => new Set(c));
+  const introducesCoupling = (cycles) => cycles.some((c) => !baseSets.some((bc) => c.every((f) => bc.has(f))));
+
+  // Phase 1 — cuts (advisory; each verified cut breaks one cycle). Step ids stay COMPACT: SCCs are
+  // disjoint, so the first (sorted) file names the cycle uniquely — a 60-file SCC must not put a
+  // multi-KB file list into every step id.
+  const cutSteps = (breakCycles.cycles || []).filter((c) => c.verified).map((c) => {
+    const files = c.files || [];
+    return {
+      id: `cut:${files[0] || '?'}${files.length > 1 ? `(+${files.length - 1})` : ''}`, type: 'cut', op: null, roi: 10,
+      gate: { ok: true }, delta: { locReclaimed: 0, cyclesBroken: 1 }, detail: c.cut || null, files,
+    };
+  }).sort(byRoiThenId);
+
+  // Phase 2 — safe dead-code deletes (cycle-neutral: an orphan is in no SCC). ROI = the symbol's
+  // span: deadcode emits `loc` (locSaved kept as a legacy alias so older advisor output still ranks).
+  const delSteps = (deadcode.safe || []).map((o) => {
+    const saved = o.locSaved ?? o.loc ?? 0;
+    return {
+      id: `del:${o.id}`, type: 'delete', op: { kind: 'delete', ids: [o.id] }, roi: saved,
+      gate: { ok: true }, delta: { locReclaimed: saved, cyclesBroken: 0 },
+    };
+  }).sort(byRoiThenId);
+
+  // Phase 3 — ready merges, cumulatively pre-flighted from the graph-with-prior-steps-applied.
+  // Deletes are independent node removals, so applying them as ONE batched op is equivalent to the
+  // sequential chain — and O(1) whole-graph clones instead of O(deletes). (549 per-step clones of a
+  // 1.8MB graph made campaign the 8.9s outlier while every other tool answered in ~100ms.)
+  const delIds = delSteps.map((s) => s.op.ids[0]);
+  let cur = delIds.length ? applyEdit(g0, { kind: 'delete', ids: delIds }) : g0;
+  const idx0 = buildIndex(g0);
+  const cands = (optimize.opportunities || [])
+    .filter((o) => o.tier === 'ready' && o.kind === 'duplicate-logic' && Array.isArray(o.nodes) && o.nodes.length >= 2)
+    .map((o) => ({ o, canonical: o.canonical || chooseCanonical(idx0, o.nodes), loc: o.locSaved || 0 }))
+    .sort((a, b) => b.loc - a.loc || (a.o.id < b.o.id ? -1 : a.o.id > b.o.id ? 1 : 0));
+  const mergeSteps = [];
+  for (const m of cands) {
+    const sim = applyEdit(cur, { kind: 'merge', ids: m.o.nodes, into: m.canonical });
+    if (introducesCoupling(fileCycles(sim))) continue; // would introduce NEW coupling -> drop (gate would block)
+    mergeSteps.push({
+      id: `merge:${m.canonical}`, type: 'merge', op: { kind: 'merge', ids: m.o.nodes.slice().sort(), into: m.canonical },
+      roi: m.loc, gate: { ok: true }, delta: { locReclaimed: m.loc, cyclesBroken: 0 },
+    });
+    cur = sim;
+  }
+
+  const ordered = [...cutSteps, ...delSteps, ...mergeSteps];
+  const steps = Number.isFinite(budget) ? ordered.slice(0, Math.max(0, budget)) : ordered;
+  let loc = 0, cyc = 0;
+  for (const s of steps) { loc += s.delta.locReclaimed; cyc += s.delta.cyclesBroken; s.cumulative = { locReclaimed: loc, cyclesBroken: cyc }; }
+  return { steps, totals: { steps: steps.length, cuts: steps.filter((s) => s.type === 'cut').length, deletes: steps.filter((s) => s.type === 'delete').length, merges: steps.filter((s) => s.type === 'merge').length, locReclaimed: loc, cyclesBroken: cyc } };
+}

package/scripts/lib/claims-check.mjs

@@ -0,0 +1,44 @@
+// Spec C: the claims audit — every evidence source the marketing surfaces cite must exist in the
+// tree. Pure so check-consistency can wire it and tests can pin it without touching the real repo.
+//
+// A "source" is valid when it resolves to (a) an existing path relative to the repo root, (b) an
+// existing file under bench/results/, or (c) a filename-prefix of something under bench/results/
+// or bench/experiments/ (labels like "efficiency-pilot" cover a family of files).
+
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+
+function prefixHit(root, dir, label) {
+  try { return readdirSync(join(root, dir)).some((f) => f.startsWith(label)); } catch { return false; }
+}
+
+/** Validate one source label against the tree. */
+export function sourceExists(root, source) {
+  if (!source || typeof source !== 'string') return false;
+  const s = source.replace(/^\.\//, '');
+  return existsSync(join(root, s))
+    || existsSync(join(root, 'bench', 'results', s))
+    || prefixHit(root, 'bench/results', s)
+    || prefixHit(root, 'bench/experiments', s);
+}
+
+/**
+ * Audit the evidence ledger (product.json claims + proof.headline) and the README's
+ * bench-results references. Returns { ok, missing: [{where, source}] }.
+ */
+export function auditClaims(root, { product, readme }) {
+  const missing = [];
+  for (const c of product?.claims || []) {
+    if (!sourceExists(root, c.source)) missing.push({ where: `product.json claim "${c.claim}"`, source: c.source });
+  }
+  for (const h of product?.proof?.headline || []) {
+    if (!sourceExists(root, h.src)) missing.push({ where: `product.json headline "${h.label}"`, source: h.src });
+  }
+  const seen = new Set();
+  for (const m of String(readme || '').matchAll(/bench\/(?:results|experiments)\/[\w][\w.-]*/g)) {
+    const p = m[0];
+    if (seen.has(p)) continue; seen.add(p);
+    if (!existsSync(join(root, p))) missing.push({ where: 'README.md', source: p });
+  }
+  return { ok: missing.length === 0, missing };
+}

package/scripts/lib/cli.mjs

@@ -0,0 +1,140 @@
+// codeweb shared CLI harness — the one place stdout/exit/graph-loading plumbing lives.
+// Motivated by codeweb's own overlap finding ("CLI scaffolding hand-rolled across N scripts") and by
+// a real output-corruption bug: `process.stdout.write(big); process.exit(0)` silently drops
+// everything past the OS pipe buffer (~64KB) because exit() discards queued async writes. Every
+// emitter below ends the process NATURALLY (process.exitCode + event-loop drain), which is the
+// documented Node way to guarantee a full flush. stderr messages are small (< pipe buffer), so
+// die() may still hard-exit.
+
+import { readFileSync, existsSync, statSync } from 'node:fs';
+import { resolve, dirname, join } from 'node:path';
+import { normalizeGraph } from './graph-ops.mjs';
+
+// A consumer like `| head -1` closes the pipe early; without a handler Node dies on EPIPE with a
+// stack trace. Treat it as a normal end-of-output.
+process.stdout.on('error', (e) => { if (e && e.code === 'EPIPE') process.exit(0); throw e; });
+
+/** stderr + immediate exit. Only for SMALL diagnostic messages (they fit the pipe buffer). */
+export function die(msg, code = 2) {
+  console.error(msg);
+  process.exit(code);
+}
+
+/** Set the exit code WITHOUT killing pending stdout writes. Callers must fall off the end. */
+export function finish(code = 0) {
+  process.exitCode = code;
+}
+
+/** Write a JSON payload (any size) to stdout, flush-safe. Ends the turn via finish(code). */
+export function emitJson(payload, code = 0) {
+  process.stdout.write(JSON.stringify(payload) + '\n');
+  finish(code);
+}
+
+/** Write pre-rendered text lines (any size) to stdout, flush-safe. */
+export function emitText(text, code = 0) {
+  process.stdout.write(text.endsWith('\n') || text === '' ? text : text + '\n');
+  finish(code);
+}
+
+/**
+ * Resolve the graph path from an explicit arg or the CODEWEB_WS workspace, load, parse, normalize.
+ * Dies with the shared, actionable message on absence/corruption. Returns { graph, abs }.
+ */
+export function loadGraph(pathArg, { usage = null } = {}) {
+  const graphPath = pathArg || (process.env.CODEWEB_WS ? `${process.env.CODEWEB_WS}/graph.json` : null);
+  if (!graphPath) die(usage || 'usage: <graph.json> required (or set CODEWEB_WS)', 2);
+  const abs = resolve(graphPath);
+  if (!existsSync(abs)) die(`graph not found: ${abs} — build it first (run /codeweb, or: node scripts/run.mjs <target> --out-dir <target>/.codeweb)`, 2);
+  let graph;
+  try { graph = normalizeGraph(JSON.parse(readFileSync(abs, 'utf8'))); }
+  catch (e) { die(`invalid JSON in ${abs}: ${e.message}`, 2); }
+  return { graph, abs };
+}
+
+/**
+ * Cached, best-effort source access for a graph's target (meta.root) — THE body reader
+ * (context-pack, find-similar, diff rename-matching all read node spans; the logic lives once).
+ * bodyOf(node) = the exact source lines [line, line+loc-1], or null when unreadable.
+ */
+// One truth for "what counts as a mappable source file" — the extractor's SRC list, mirrored
+// here for the hooks (Spec E consolidation; the hooks previously trailed the extractor's list).
+export const SRC_RE = /\.(js|mjs|cjs|jsx|ts|tsx|py|rs|go|java|cs|rb|php|kt|kts|swift)$/;
+
+// Walk up from a file to the nearest mapped workspace (.codeweb/graph.json). Previously
+// duplicated verbatim in both hooks — codeweb's own campaign flagged it (Spec E dogfood).
+export function findTarget(filePath) {
+  let dir = dirname(resolve(filePath));
+  for (let i = 0; i < 40; i++) {
+    const baseline = join(dir, '.codeweb', 'graph.json');
+    if (existsSync(baseline)) return { root: dir, baseline };
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export function sourceReader(root) {
+  const available = !!root && existsSync(root);
+  const cache = new Map();
+  const linesOf = (rel) => {
+    if (!available) return null;
+    if (!cache.has(rel)) { try { cache.set(rel, readFileSync(root + '/' + rel, 'utf8').split(/\r?\n/)); } catch { cache.set(rel, null); } }
+    return cache.get(rel);
+  };
+  const bodyOf = (n) => {
+    const lines = n && linesOf(n.file);
+    if (!lines) return null;
+    return lines.slice(n.line - 1, n.line - 1 + (n.loc || 1)).join('\n');
+  };
+  return { available, linesOf, bodyOf };
+}
+
+/**
+ * Staleness check against the extractor's per-file stamps (meta.sources: {rel: {s,m}}). Returns
+ * null when the graph matches disk (or has no stamps/root); else { count, files: [up to 8 rels] }.
+ * stat-only — a few ms even on thousands of files. New files can't be detected without a walk
+ * (documented); changed + deleted are.
+ */
+export function checkStaleness(graph) {
+  const root = graph?.meta?.root, sources = graph?.meta?.sources;
+  if (!root || !sources || !existsSync(root)) return null;
+  const stale = [];
+  for (const [relPath, st] of Object.entries(sources)) {
+    try {
+      const cur = statSync(root + '/' + relPath);
+      if (cur.size !== st.s || Math.round(cur.mtimeMs) !== st.m) stale.push(relPath);
+    } catch { stale.push(relPath + ' (deleted)'); }
+    if (stale.length >= 64) break; // enough to know it's stale; don't stat forever
+  }
+  // directory stamps catch NEW files (a created file touches its directory's mtime)
+  for (const [relDir, m] of Object.entries(graph?.meta?.dirs || {})) {
+    if (stale.length >= 64) break;
+    try {
+      const cur = statSync(relDir === '.' ? root : root + '/' + relDir);
+      if (Math.round(cur.mtimeMs) !== m) stale.push(relDir + '/ (dir changed — new/removed files)');
+    } catch { stale.push(relDir + '/ (dir deleted)'); }
+  }
+  return stale.length ? { count: stale.length, files: stale.slice(0, 8) } : null;
+}
+
+/** Signed-delta formatter for renderers ("+3", "-2", "+0" — a delta always shows its direction). */
+export const sign = (n) => (n >= 0 ? `+${n}` : `${n}`);
+
+/**
+ * Shared list-truncation for budgeted output: keep the first `limit` items and describe the rest,
+ * so a tool can return top-N + an explicit remainder instead of an unbounded dump (no silent caps).
+ * limit == null / Infinity -> untouched.
+ */
+export function capList(items, limit, offset = 0) {
+  const all = Array.isArray(items) ? items : [];
+  const off = Number.isFinite(offset) && offset > 0 ? Math.floor(offset) : 0;
+  if (limit == null || !Number.isFinite(limit)) {
+    return { items: off ? all.slice(off) : all, total: all.length, offset: off, truncated: false, remaining: 0 };
+  }
+  const lim = Math.max(0, Math.floor(limit));
+  const slice = all.slice(off, off + lim);
+  const remaining = Math.max(0, all.length - (off + slice.length));
+  return { items: slice, total: all.length, offset: off, truncated: remaining > 0, remaining };
+}

package/scripts/lib/complexity.mjs

@@ -0,0 +1,68 @@
+// codeweb complexity primitives (F4) — approximate cyclomatic complexity + max nesting depth of a
+// function body, computed from source text with NO parser (deterministic, zero-dependency, matches the
+// regex-engine ethos). Shared by the extractor (node fields) and any consumer. Pure.
+//
+// Cyclomatic = 1 + decision points. Decision points are control-flow keywords + short-circuit/branch
+// operators, counted on source with comments and string/template literals stripped (so a keyword
+// inside a string never counts — the property CX-IGNORES-STRINGS-COMMENTS). Identifiers are never
+// counted, so renaming can't change the number (CX-RENAME-INVARIANT). The exact per-language token set
+// is documented below; it is an APPROXIMATION (no AST), good enough as a ranking signal for hotspots.
+
+// Strip line/block comments and string/template literals to ` `, so tokens inside them don't count.
+// Order: comments first, then strings (a `"` inside a `// comment` is already gone).
+const strip = (src, lang) => {
+  let s = src;
+  if (lang === 'py') {
+    s = s.replace(/'''[\s\S]*?'''/g, ' ').replace(/"""[\s\S]*?"""/g, ' ').replace(/#[^\n]*/g, ' ');
+  } else {
+    s = s.replace(/\/\/[^\n]*/g, ' ').replace(/\/\*[\s\S]*?\*\//g, ' ');
+  }
+  // template literals (whole, incl. ${…}) then double/single quoted strings
+  s = s.replace(/`(?:\\.|[^`\\])*`/g, ' ').replace(/"(?:\\.|[^"\\])*"/g, ' ').replace(/'(?:\\.|[^'\\])*'/g, ' ');
+  return s;
+};
+const count = (s, re) => (s.match(re) || []).length;
+
+// Approximate cyclomatic complexity. lang: 'py' uses Python decision tokens; everything else (js/ts/
+// go/rust) uses the C-family set. Always >= 1.
+export function cyclomatic(src, lang = 'js') {
+  const s = strip(src || '', lang);
+  let decisions;
+  if (lang === 'py') {
+    // if / elif / for / while / except  +  boolean `and` / `or`  (else/try are not decisions)
+    decisions = count(s, /\b(?:if|elif|for|while|except)\b/g) + count(s, /\b(?:and|or)\b/g);
+  } else {
+    // if / for / while / case / catch  +  &&  ||  ??  +  ternary ? (not part of ?? or ?.)
+    const kw = count(s, /\b(?:if|for|while|case|catch)\b/g);
+    const and = count(s, /&&/g), or = count(s, /\|\|/g), nullish = count(s, /\?\?/g);
+    const ternary = count(s.replace(/\?\?/g, ' ').replace(/\?\./g, ' '), /\?/g);
+    decisions = kw + and + or + nullish + ternary;
+  }
+  return 1 + decisions;
+}
+
+// Max nesting depth. Brace languages: deepest `{}` nesting (strings/comments stripped). Python:
+// deepest indentation level below the first line. Always >= 0.
+export function nestingDepth(src, lang = 'js') {
+  if (lang === 'py') {
+    const lines = (src || '').split(/\r?\n/).filter((l) => l.trim() !== '');
+    if (!lines.length) return 0;
+    const indent = (l) => l.length - l.replace(/^\s+/, '').length;
+    const stack = [indent(lines[0])];
+    let max = 0;
+    for (const l of lines.slice(1)) {
+      const ind = indent(l);
+      while (stack.length > 1 && ind <= stack[stack.length - 1]) stack.pop();
+      if (ind > stack[stack.length - 1]) stack.push(ind);
+      max = Math.max(max, stack.length - 1);
+    }
+    return max;
+  }
+  const s = strip(src || '', lang);
+  let depth = 0, max = 0;
+  for (const ch of s) {
+    if (ch === '{') { depth++; if (depth > max) max = depth; }
+    else if (ch === '}') { if (depth > 0) depth--; }
+  }
+  return max;
+}

package/scripts/lib/dup-check.mjs

@@ -0,0 +1,51 @@
+// codeweb incremental duplication check (F3) — closes the hole where a post-edit / refreshed graph
+// (overlaps:[]) can't see a freshly-introduced clone. For each CHANGED symbol, body-confirm against
+// every other non-test function body and report it if it duplicates one at the same "high" bar
+// overlap.mjs uses (Jaccard >= 0.6). Reuses the ONE shingle/Jaccard truth (lib/shingles.mjs) and
+// rounds to 6 dp like find-similar.mjs — no second similarity formula. Pure; bodies come from a
+// `bodyOf` injector (tests) or are read from `root` by line range (the same read overlap.mjs uses).
+
+import { readFileSync } from 'node:fs';
+import { isTestFile } from './graph-ops.mjs';
+import { shingles, jaccard } from './shingles.mjs';
+
+const HIGH = 0.6, K = 3;
+const round6 = (x) => +x.toFixed(6);
+const isFn = (n) => n && (n.kind === 'function' || n.kind === 'method');
+
+export function incrementalOverlap(graph, changedIds, { root = null, bodyOf = null } = {}) {
+  const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+  const fileCache = new Map();
+  const readLines = (rel) => {
+    if (!fileCache.has(rel)) { try { fileCache.set(rel, readFileSync(root + '/' + rel, 'utf8').split(/\r?\n/)); } catch { fileCache.set(rel, null); } }
+    return fileCache.get(rel);
+  };
+  const getBody = (n) => {
+    if (bodyOf) return bodyOf(n);
+    if (!root) return null;
+    const lines = readLines(n.file);
+    return lines ? lines.slice(n.line - 1, n.line - 1 + (n.loc || 1)).join('\n') : null;
+  };
+  const shOf = new Map();
+  const shingleOf = (n) => { if (!shOf.has(n.id)) { const b = getBody(n); shOf.set(n.id, b ? shingles(b, K) : null); } return shOf.get(n.id); };
+
+  const pool = graph.nodes.filter((n) => isFn(n) && !isTestFile(n.file));
+  const out = [];
+  for (const id of changedIds.filter((x) => byId.has(x))) {
+    const n = byId.get(id);
+    if (!isFn(n) || isTestFile(n.file)) continue;
+    const cand = shingleOf(n);
+    if (!cand || !cand.size) continue;
+    let best = null;
+    for (const other of pool) {
+      if (other.id === id) continue;                          // never report a symbol as duplicating itself
+      const osh = shingleOf(other);
+      if (!osh || !osh.size) continue;
+      const sim = round6(jaccard(cand, osh));
+      if (sim < HIGH) continue;                                // precision over recall: only the confirmed bar
+      if (!best || sim > best.sim || (sim === best.sim && other.id < best.dupOf)) best = { dupOf: other.id, sim };
+    }
+    if (best) out.push({ id, dupOf: best.dupOf, sim: best.sim });
+  }
+  return out.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}

package/scripts/lib/find-core.mjs

@@ -0,0 +1,85 @@
+// find-core — concept search over the graph: "where is retry handled?" -> ranked symbols.
+// Deterministic token matching + structural weighting; no LLM, no embeddings, no index build.
+// Every other query tool needs a NAME; this one turns an idea into the right starting symbol
+// (then explain/context/impact take over). Same-input-same-output, like everything else here.
+
+// Grammatical noise only — never drop meaning-bearing words ("handled" must reach handleError).
+const STOP = new Set([
+  'a', 'an', 'the', 'is', 'are', 'was', 'were', 'be', 'been', 'being', 'do', 'does', 'did',
+  'how', 'what', 'where', 'when', 'which', 'who', 'why', 'in', 'on', 'at', 'of', 'for', 'to',
+  'from', 'with', 'and', 'or', 'not', 'it', 'its', 'this', 'that', 'these', 'those', 'there',
+  'we', 'you', 'i', 'my', 'our', 'your', 'can', 'could', 'should', 'would', 'will', 'happen', 'happens',
+]);
+
+/** Porter-lite: strip plural/participle/agent suffixes so query and identifier meet in the middle. */
+export const stemToken = (w) => {
+  if (w.length > 4 && w.endsWith('ies')) return w.slice(0, -3) + 'y';
+  if (w.length > 5 && w.endsWith('ing')) w = w.slice(0, -3);
+  else if (w.length > 4 && (w.endsWith('ed') || w.endsWith('es') || w.endsWith('er'))) w = w.slice(0, -2);
+  else if (w.length > 3 && w.endsWith('s') && !w.endsWith('ss')) w = w.slice(0, -1);
+  if (w.length > 4 && w.endsWith('e')) w = w.slice(0, -1);
+  return w;
+};
+
+/** Split an identifier/path segment on camelCase, snake_case, kebab-case, dots, digits. */
+export const splitIdent = (s) => String(s)
+  .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+  .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+  .toLowerCase()
+  .split(/[^a-z0-9]+/)
+  .filter(Boolean);
+
+/** Query -> stemmed, deduped, stopword-free tokens (order-independent). */
+export const tokenizeQuery = (q) => [...new Set(splitIdent(q).filter((t) => !STOP.has(t)).map(stemToken))];
+
+const stemmedSet = (tokens) => new Set(tokens.map(stemToken));
+
+/**
+ * Rank graph nodes for a free-text query. Returns ALL matches sorted (score desc, id asc) —
+ * budgeting is the caller's job (capList / MCP budget), so totals stay true.
+ * Row: { id, label, kind, file, line, domain, role, score, match } — `match` says WHY, compactly.
+ */
+export function findSymbols(graph, index, query) {
+  const qtoks = tokenizeQuery(query);
+  if (!qtoks.length) return { qtoks, results: [] };
+  const qJoined = qtoks.join('');
+  const wantsTests = qtoks.some((t) => t === 'test' || t === 'spec');
+  const results = [];
+  for (const n of graph.nodes) {
+    const labelToks = stemmedSet(splitIdent(n.label));
+    const labelJoined = splitIdent(n.label).map(stemToken).join('');
+    const idTail = n.id.slice(n.id.lastIndexOf(':') + 1);
+    const ownerToks = idTail === n.label ? labelToks : stemmedSet(splitIdent(idTail));
+    const segs = String(n.file || '').split('/');
+    const baseToks = stemmedSet(splitIdent(segs[segs.length - 1].replace(/\.[^.]+$/, '')));
+    const pathToks = stemmedSet(segs.slice(0, -1).flatMap(splitIdent));
+    const domainToks = stemmedSet(splitIdent(n.domain || ''));
+    let base = 0, matched = 0;
+    const why = [];
+    for (const qt of qtoks) {
+      let hit = 0;
+      if (labelToks.has(qt)) { hit = 3; why.push(`label:${qt}`); }
+      else if (qt.length >= 3 && [...labelToks].some((lt) => lt.startsWith(qt))) { hit = 1.5; why.push(`label~${qt}`); }
+      else if (ownerToks.has(qt)) { hit = 1.5; why.push(`owner:${qt}`); }
+      else if (baseToks.has(qt)) { hit = 2; why.push(`file:${qt}`); }
+      else if (pathToks.has(qt)) { hit = 1; why.push(`path:${qt}`); }
+      else if (domainToks.has(qt)) { hit = 0.75; why.push(`domain:${qt}`); }
+      if (hit) { base += hit; matched++; }
+    }
+    if (!matched) continue;
+    if (labelJoined === qJoined) { base += 4; why.unshift('label=query'); }
+    let score = base * (matched / qtoks.length);
+    if (n.exports) score *= 1.25;
+    if (n.kind === 'module') score *= 0.4;
+    if (!wantsTests) {
+      if (n.role === 'test' || n.role === 'fixture') score *= 0.6;
+      else if (n.role === 'generated' || n.role === 'bench' || n.role === 'example') score *= 0.5;
+      else score *= 1.2; // product
+    }
+    const inDegree = (index.callIn.get(n.id)?.size || 0) + (index.importIn.get(n.id)?.size || 0);
+    score *= 1 + Math.min(inDegree, 20) / 40;
+    results.push({ id: n.id, label: n.label, kind: n.kind, file: n.file, line: n.line, domain: n.domain || 'unassigned', role: n.role, score: +score.toFixed(2), match: why.join(' ') });
+  }
+  results.sort((a, b) => b.score - a.score || (a.id < b.id ? -1 : 1));
+  return { qtoks, results };
+}

package/scripts/lib/gate-md.mjs

@@ -0,0 +1,50 @@
+// gate-md — render diff.mjs's JSON payload as the PR comment the CI gate posts. The gate used to
+// be invisible unless it blocked ("today it only pass/fails"); this puts the structural review
+// where reviewers already look, budgeted like every other codeweb surface (hard caps + explicit
+// "+N more", never an unbounded dump).
+
+import { sign } from './cli.mjs';
+
+const MARKER = '<!-- codeweb-gate -->';
+
+const cap = (arr, n) => ({ head: arr.slice(0, n), more: Math.max(0, arr.length - n) });
+
+/**
+ * payload = the `diff.mjs --json` object. Returns the full comment body (marker included, so the
+ * workflow can find-and-update its own comment instead of stacking new ones).
+ */
+export function gateComment(p) {
+  const L = [];
+  L.push(MARKER);
+  L.push(`## codeweb gate — ${p.ok ? '✅ no structural regressions' : `❌ ${p.regressions.length} regression type(s)`}`);
+  L.push('');
+  const rn = p.nodes.renamed.length;
+  L.push(
+    `\`${p.before}\` → \`${p.after}\` · nodes +${p.nodes.added.length} −${p.nodes.removed.length}${rn ? ` ~${rn} renamed` : ''}` +
+    ` · edges +${p.edges.added} −${p.edges.removed} · cross-domain Δ${sign(p.crossDomainEdges.delta)}` +
+    ` · cycles +${p.cycles.added.length} −${p.cycles.removed.length} · overlaps +${p.overlaps.added.length} −${p.overlaps.removed.length}`
+  );
+  if (!p.ok) {
+    L.push('');
+    L.push('**Blocking:**');
+    for (const r of p.regressions) L.push(`- ❌ ${r}`);
+  }
+  // existing symbols that lost their last caller (brand-new and renamed-to nodes are not "lost")
+  const added = new Set(p.nodes.added), renamedTo = new Set(p.nodes.renamed.map((r) => r.to));
+  const lost = p.orphans.added.filter((id) => !added.has(id) && !renamedTo.has(id));
+  const section = (title, items, render, n) => {
+    if (!items.length) return;
+    const c = cap(items, n);
+    L.push('');
+    L.push(`**${title}**`);
+    for (const it of c.head) L.push(render(it));
+    if (c.more) L.push(`- …+${c.more} more`);
+  };
+  section('New dependency cycles', p.cycles.added, (c) => `- ${c.join(' → ')}`, 3);
+  section('New duplication findings', p.overlaps.added, (o) => `- ${o.kind}: ${o.title || '(untitled)'}`, 5);
+  section('Symbols that lost all callers', lost, (id) => `- \`${id}\``, 5);
+  section('Renames (not churn)', p.nodes.renamed, (r) => `- \`${r.from}\` → \`${r.to}\`${r.sim != null ? ` (body ${(r.sim * 100).toFixed(0)}%)` : ''}`, 5);
+  L.push('');
+  L.push('<sub>codeweb structural review (same verdict as the gate). Reproduce locally: `node scripts/ci-gate.mjs --base <base-sha> --target <dir>`.</sub>');
+  return L.join('\n') + '\n';
+}