@ghostlygawd/codeweb 0.9.0

package/agents/codeweb-domain-mapper.md

@@ -0,0 +1,63 @@
+---
+name: codeweb-domain-mapper
+description: Read-only domain-tagging and overlap-detection pass for the codeweb plugin. Given the merged node/edge graph, clusters nodes into semantic domains, assigns a domain to every node, and detects cross-domain overlap (duplicated logic, parallel implementations, tangled responsibilities) with ranked consolidation recommendations. Returns JSON.
+tools: Read, Grep, Glob
+model: opus
+---
+
+# codeweb-domain-mapper
+
+You turn a raw symbol web into a **domain map** and an **overlap graph**. You run once, after
+all dissectors have produced the merged `{nodes, edges}`. Your output is data — return one JSON
+object and nothing else.
+
+## Inputs
+
+- The merged graph: `nodes[]` (with empty `domain`) and `edges[]`.
+- Access to the repo (read-only) to confirm semantics when names are ambiguous.
+- The **overlap heuristics** reference — apply its kinds and severity rubric.
+
+## Step 1 — Assign domains
+
+A **domain** is a coherent area of responsibility (e.g. `auth`, `billing`, `persistence`,
+`http-routing`, `rendering`, `notifications`). Derive domains from: directory structure,
+naming, what each symbol does, and edge clustering (densely-connected groups tend to be one
+domain). Assign every node exactly one `domain`. Aim for 4–15 domains for a typical repo —
+not one-per-file, not one-for-everything. Produce a `domains[]` summary with a node count and
+one-line description each.
+
+## Step 2 — Detect overlaps
+
+Find places where **separate parts of the system do overlapping work**. For each, classify the
+`kind`:
+
+- `duplicate-logic` — the same algorithm/check re-implemented in 2+ places.
+- `parallel-impl` — competing implementations of one capability (e.g. two HTTP clients).
+- `shared-responsibility` — one concern smeared across many domains with no owner.
+- `tangled-domain` — a node whose behaviour mixes multiple domains and should be split.
+
+Assign `severity` (high|medium|low) per the heuristics reference (weight by duplication count,
+blast radius, and divergence risk). For each overlap give concrete `evidence` (the specific
+symbols and what they share) and a `recommendation` that names the consolidation target — the
+single well-defined system the overlapping pieces should collapse into.
+
+## Step 3 — Rank
+
+Order `overlaps[]` by severity then by how many nodes/domains they touch. The top items are the
+codebase's best simplification opportunities.
+
+## Output
+
+Return exactly one JSON object — no prose, no fences:
+
+```json
+{
+  "nodes": [ { "id": "...", "domain": "auth" } ],
+  "domains": [ { "name": "auth", "nodes": 12, "summary": "..." } ],
+  "overlaps": [ { "id": "ov1", "title": "...", "kind": "duplicate-logic", "severity": "high",
+    "domains": ["auth","billing"], "nodes": ["..."], "evidence": "...", "recommendation": "..." } ]
+}
+```
+
+In `nodes` you only need `id` + `domain` (the orchestrator merges these back onto the full
+nodes). Include every node id.

package/commands/codeweb.md

@@ -0,0 +1,57 @@
+---
+name: codeweb
+description: Dissect a codebase into atomic nodes, wire the system web, tag domains, and surface overlap/consolidation opportunities as an interactive HTML map. Works on the current project or an external repo (path or git URL).
+---
+
+# /codeweb
+
+Invoke the **codebase-anatomy** skill to build a "biological web" of a codebase and an
+overlap graph for restructuring.
+
+## Usage
+
+```
+/codeweb [target] [flags]
+```
+
+- `target` — a local path (default: current directory `.`) **or** a git URL / `owner/repo`
+  to clone read-only and review before adopting.
+- `--depth module|symbol|auto` — granularity (default `auto`: module-level overview, then
+  symbol-level on the densest/most-overlapping subsystems).
+- `--engine hybrid|read|tools` — how edges are extracted (default `hybrid`: static-analysis
+  tools when available, agent reading otherwise).
+- `--focus <glob>` — restrict atomic dissection to a path glob (e.g. `src/payments/**`).
+- `--mode internal|external` — `internal` = restructure my own code; `external` = explore a
+  third-party repo and produce an adoption review. Auto-detected from `target` if omitted.
+- `--open` — open the generated `report.html` after rendering.
+
+## What it does
+
+1. Scopes and acquires the target (clones external repos read-only; never executes their code).
+2. Dissects the code to atomic nodes (functions, classes, methods, exported symbols).
+3. Wires the relationship web (calls, imports, inheritance) using the hybrid engine.
+4. Tags every node with a semantic domain and clusters the domains.
+5. Builds the overlap graph — duplicated logic, parallel implementations, tangled domains —
+   and ranks consolidation opportunities.
+6. Runs the consolidation advisor — tiers each duplicate-logic finding into **ready** (a
+   body-confirmed merge the regression gate would accept), **blocked** (a merge that would
+   introduce a new dependency cycle), or **review** (drifted/structural) — and writes `optimize.md`.
+7. Renders a self-contained interactive HTML map plus `graph.json`, `overlap.md`, and `optimize.md`.
+8. In external mode, adds an adoption review (risk, dependency, architecture verdict).
+
+## Instructions for Claude
+
+Activate the `codebase-anatomy` skill and follow its workflow. Parse the arguments above from
+`$ARGUMENTS`. If `target` is a git URL or `owner/repo`, treat it as **external mode** unless
+overridden. For JavaScript/TypeScript/Python targets, prefer the skill's **fast path** — a single
+deterministic command:
+
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/run.mjs" "<target>" --target "<label>" --out-dir "<target>/.codeweb"
+```
+
+which runs extract → cluster → overlap → optimize → render in one shot; fall back to the agent-based
+dissection only for languages it can't parse or `--engine read`. Write all outputs under
+`<target>/.codeweb/` (or a temp dir for cloned external repos) and finish by reporting the artifact
+paths and the top consolidation opportunities — lead with the **ready** tier from `optimize.md`
+(merges the regression gate would accept), then call out anything **blocked** by a projected cycle.

package/hooks/hooks.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json.schemastore.org/claude-code-settings.json",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/session-brief.mjs\"",
+            "timeout": 10
+          }
+        ],
+        "description": "codeweb: when the session starts in a .codeweb-mapped repo, inject the ~2KB day-one briefing (areas, load-bearing symbols, entry points, tests, known issues) so the agent starts oriented instead of exploring (fail-open; inert until /codeweb has mapped the repo)",
+        "id": "codeweb:session-brief"
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/pre-edit-impact.mjs\"",
+            "timeout": 10
+          }
+        ],
+        "description": "codeweb: before an edit in a .codeweb-mapped target, surface one line of blast-radius awareness (symbols + dependents in the file) so contract changes get impact-checked first (advisory; fail-open; inert until /codeweb has mapped the target)",
+        "id": "codeweb:pre-edit-impact"
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write|MultiEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/post-edit-diff.mjs\"",
+            "timeout": 30
+          }
+        ],
+        "description": "codeweb: after an edit to a .codeweb-mapped target, flag new dependency cycles or symbols that lost all callers (edges-only subset; fail-open, non-blocking, inert until /codeweb has mapped the target)",
+        "id": "codeweb:post-edit-diff"
+      }
+    ]
+  }
+}

package/hooks/post-edit-diff.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+// codeweb PostToolUse hook — structural regression check after an edit.
+//
+// Reads the PostToolUse payload on stdin. IF the edited file is a source file under a
+// `.codeweb/`-mapped target (i.e. /codeweb has been run, leaving `<target>/.codeweb/graph.json`),
+// re-extracts that target and compares to the baseline via structuralRegressions(): a NEW file
+// dependency cycle, or a symbol that lost ALL its callers, is surfaced to the agent.
+//
+// FAIL-OPEN by construction: any parse error, missing baseline, or extraction failure exits 0
+// silently, so the hook can never block or break an edit. It is INERT until a target is mapped
+// (no `.codeweb/graph.json` up-tree -> no-op), and only checks the edges-only regression subset
+// (cycles + lost-callers) — run `scripts/diff.mjs` or re-run /codeweb for the full delta.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { tmpdir } from 'node:os';
+import { structuralRegressions } from '../scripts/lib/graph-ops.mjs';
+import { bump, correlateEdit } from '../scripts/lib/stats.mjs';
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const EXTRACT = join(HERE, '..', 'scripts', 'extract-symbols.mjs');
+import { SRC_RE, findTarget } from '../scripts/lib/cli.mjs'; // Spec E: one truth (was a stale local copy missing five languages)
+
+
+// Returns { root, newCycles, lostCallers } when an edit introduces a structural regression, else null.
+export function check(raw) {
+  let input; try { input = JSON.parse(raw); } catch { return null; }
+  const fp = input?.tool_input?.file_path || input?.tool_input?.filePath;
+  if (!fp || !SRC_RE.test(fp)) return null;
+  const t = findTarget(fp);
+  if (!t) return null;
+  let baseline; try { baseline = JSON.parse(readFileSync(t.baseline, 'utf8')); } catch { return null; }
+  const tmpOut = join(tmpdir(), `codeweb-hook-${process.pid}.json`);
+  try {
+    // Incremental: the per-file scan cache lives beside the graph, so an edit re-scans only the
+    // changed file(s) instead of the whole target on every keystroke-batch.
+    const cache = join(dirname(t.baseline), 'scan-cache.json');
+    execFileSync(process.execPath, [EXTRACT, t.root, '--no-ctags', '--cache', cache, '--out', tmpOut], { stdio: 'ignore' });
+  } catch { return null; }
+  let after; try { after = JSON.parse(readFileSync(tmpOut, 'utf8')); } catch { return null; }
+  const reg = structuralRegressions(baseline, after);
+  if (!reg.newCycles.length && !reg.lostCallers.length) return null;
+  return { root: t.root, ...reg };
+}
+
+function format(out) {
+  const lines = [`[codeweb] ⚠ structural regression after edit (target: ${out.root}):`];
+  for (const c of out.newCycles) lines.push(`  new dependency cycle: ${c.join(' <-> ')}`);
+  for (const id of out.lostCallers) lines.push(`  ${id} lost all callers (now uncalled)`);
+  lines.push('  -> run `node scripts/diff.mjs` or re-run /codeweb for the full delta.');
+  return lines.join('\n');
+}
+
+// Execute as a hook only when run directly (not when imported by tests).
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
+  let raw = '';
+  try { raw = readFileSync(0, 'utf8'); } catch { /* no stdin */ }
+  let out = null;
+  try { out = check(raw); } catch { /* fail-open */ }
+  try {
+    const fp = JSON.parse(raw)?.tool_input?.file_path || JSON.parse(raw)?.tool_input?.filePath;
+    const t = fp && SRC_RE.test(fp) && findTarget(fp);
+    if (t) {
+      bump(t.baseline, 'postEditChecks');
+      if (out) bump(t.baseline, 'regressionsFlagged', out.newCycles.length + out.lostCallers.length);
+      // advice-followed correlation: did this edit touch a caller file the last card warned about?
+      const rel = resolve(fp).slice(t.root.length + 1).replace(/\\/g, '/');
+      correlateEdit(t.baseline, rel);
+    }
+  } catch { /* receipt only */ }
+  if (out) {
+    const msg = format(out);
+    process.stderr.write(msg + '\n');
+    try {
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: msg },
+      }) + '\n');
+    } catch { /* ignore */ }
+  }
+  process.exit(0); // ALWAYS non-blocking
+}

package/hooks/pre-edit-impact.mjs

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+// codeweb PreToolUse hook — one line of blast-radius awareness BEFORE an edit lands.
+//
+// The post-edit gate catches a regression after the fact; this is the missing other half: when the
+// agent is about to edit a file in a `.codeweb`-mapped target, surface how load-bearing that file
+// is (symbols + in-repo callers + the top symbol) so contract-changing edits get checked with
+// codeweb_impact/codeweb_context FIRST. One line, advisory, never blocks.
+//
+// FAIL-OPEN and cheap: any parse/read problem exits 0 silently; unmapped targets are a no-op; the
+// whole check is one JSON parse + an in-memory count (~50-100ms on a 3k-symbol graph).
+
+import { readFileSync, existsSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve, relative } from 'node:path';
+import { bump, recordPendingCard } from '../scripts/lib/stats.mjs';
+
+// set by preview() when a card is embedded — the caller FILES the card warned about
+// (docs/specs/card-correlation.md: a later edit touching one = advice followed)
+let lastCardMeta = null;
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const EXPLAIN = join(HERE, '..', 'scripts', 'explain.mjs');
+import { SRC_RE, findTarget } from '../scripts/lib/cli.mjs'; // Spec E: one truth (was a duplicated walk + a trailing language list)
+
+// Returns the one-line advisory for an edit payload, or null (not mapped / not source / no signal).
+export function preview(raw) {
+  let input; try { input = JSON.parse(raw); } catch { return null; }
+  const fp = input?.tool_input?.file_path || input?.tool_input?.filePath;
+  if (!fp || !SRC_RE.test(fp)) return null;
+  const t = findTarget(fp);
+  if (!t) return null;
+  let graph; try { graph = JSON.parse(readFileSync(t.baseline, 'utf8')); } catch { return null; }
+  const rel = relative(t.root, resolve(fp)).replace(/\\/g, '/');
+  const nodes = (graph.nodes || []).filter((n) => n.file === rel && n.kind !== 'module');
+  if (!nodes.length) return null;
+  const inCount = new Map();
+  for (const e of graph.edges || []) {
+    if (e.kind !== 'call' && e.kind !== 'import' && e.kind !== 'ref') continue;
+    inCount.set(e.to, (inCount.get(e.to) || 0) + 1);
+  }
+  let total = 0, top = null;
+  for (const n of nodes) {
+    const c = inCount.get(n.id) || 0;
+    total += c;
+    if (!top || c > top.c) top = { label: n.label, c };
+  }
+  if (total === 0) return null; // nothing depends on this file — stay quiet
+  let msg = `[codeweb] editing ${rel}: ${nodes.length} symbol(s), ${total} in-repo dependent edge(s)` +
+    (top && top.c > 0 ? ` (most depended-on: ${top.label} ×${top.c})` : '') + '.';
+  // AMBIENT context: don't just point at the tools — inject the ~1KB explain card for the file's
+  // most-depended-on symbol, so the blast radius arrives without the agent having to ask. This is
+  // the attack on the edit-quality null: awareness with zero discipline required. Fail-open.
+  if (top && top.c > 0) {
+    try {
+      const topNode = nodes.slice().sort((a, b) => (inCount.get(b.id) || 0) - (inCount.get(a.id) || 0))[0];
+      const r = execFileSync(process.execPath, [EXPLAIN, t.baseline, topNode.id, '--json'], { encoding: 'utf8', timeout: 8000, maxBuffer: 1 << 22 });
+      const card = JSON.parse(r).cards?.[0];
+      if (card) {
+        msg += `\n  ${card.summary}`;
+        if (card.topCallers?.length) msg += `\n  top callers: ${card.topCallers.slice(0, 4).join(', ')}`;
+        if (card.tests?.length) msg += `\n  tests: ${card.tests.slice(0, 2).join(', ')}`;
+        const callerFiles = [...new Set((card.topCallers || [])
+          .map((id) => id.slice(0, id.lastIndexOf(':')))
+          .filter((f) => f && f !== rel))]; // the SUBJECT file never counts as "following the advice"
+        if (callerFiles.length) lastCardMeta = { baseline: t.baseline, symbol: topNode.id, files: callerFiles };
+      }
+    } catch { /* card is a bonus, never a blocker */ }
+  }
+  msg += `\n  → codeweb_context for a bounded edit window; codeweb_impact for the full blast radius.`;
+  return msg;
+}
+
+// Execute as a hook only when run directly (not when imported by tests).
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
+  let raw = '';
+  try { raw = readFileSync(0, 'utf8'); } catch { /* no stdin */ }
+  let msg = null;
+  try { msg = preview(raw); } catch { /* fail-open */ }
+  if (msg) {
+    try {
+      const fp = JSON.parse(raw)?.tool_input?.file_path || JSON.parse(raw)?.tool_input?.filePath;
+      const t = fp && findTarget(fp);
+      if (t) bump(t.baseline, 'cardsDelivered');
+      if (lastCardMeta) recordPendingCard(lastCardMeta.baseline, lastCardMeta.symbol, lastCardMeta.files);
+    } catch { /* receipt only */ }
+    try {
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: 'allow', additionalContext: msg },
+      }) + '\n');
+    } catch { /* ignore */ }
+  }
+  process.exit(0); // ALWAYS non-blocking
+}

package/hooks/session-brief.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// codeweb SessionStart hook — the day-one briefing, injected before the first token is spent.
+//
+// A new session in a mapped repo starts oriented instead of exploring: one ~2KB page (areas,
+// load-bearing symbols, entry points, test layout, known issues) from the already-built graph.
+// FAIL-OPEN and cheap: unmapped cwd is a silent no-op; any error exits 0 with no output.
+
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve } from 'node:path';
+import { normalizeGraph, buildIndex } from '../scripts/lib/graph-ops.mjs';
+import { buildBrief, renderBrief } from '../scripts/lib/brief-core.mjs';
+import { bump, attachActivity } from '../scripts/lib/stats.mjs';
+
+function findGraph(startDir) {
+  let dir = resolve(startDir);
+  for (let i = 0; i < 40; i++) {
+    const cand = join(dir, '.codeweb', 'graph.json');
+    if (existsSync(cand)) return cand;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+// Returns the briefing text for a SessionStart payload, or null (unmapped / unreadable).
+export function preview(raw) {
+  let input; try { input = JSON.parse(raw); } catch { input = {}; }
+  const cwd = input?.cwd || process.cwd();
+  const graphPath = findGraph(cwd);
+  if (!graphPath) return null;
+  let graph; try { graph = normalizeGraph(JSON.parse(readFileSync(graphPath, 'utf8'))); } catch { return null; }
+  const brief = attachActivity(buildBrief(graph, buildIndex(graph)), graphPath);
+  const text = renderBrief(brief);
+  return `[codeweb] this repo is mapped (${graphPath}).\n${text}`;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url))) {
+  let raw = '';
+  try { raw = readFileSync(0, 'utf8'); } catch { /* no stdin */ }
+  let msg = null;
+  try { msg = preview(raw); } catch { /* fail-open */ }
+  if (msg) {
+    try { const input = JSON.parse(raw); bump(findGraph(input?.cwd || process.cwd()), 'briefInjected'); } catch { /* receipt only */ }
+    try {
+      process.stdout.write(JSON.stringify({
+        hookSpecificOutput: { hookEventName: 'SessionStart', additionalContext: msg },
+      }) + '\n');
+    } catch { /* ignore */ }
+  }
+  process.exit(0);
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@ghostlygawd/codeweb",
+  "version": "0.9.0",
+  "type": "module",
+  "description": "The living map of your codebase — deterministic call/import graph engine, 24 MCP tools for coding agents, and a self-contained interactive report.",
+  "keywords": [
+    "mcp",
+    "code-analysis",
+    "call-graph",
+    "dependency-graph",
+    "claude-code",
+    "agent-tools",
+    "dead-code",
+    "duplication"
+  ],
+  "homepage": "https://github.com/GhostlyGawd/codeweb#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GhostlyGawd/codeweb.git"
+  },
+  "license": "MIT",
+  "bin": {
+    "codeweb": "scripts/run.mjs",
+    "codeweb-mcp": "scripts/mcp-server.mjs"
+  },
+  "files": [
+    "scripts",
+    "hooks",
+    "skills",
+    "agents",
+    "commands",
+    ".claude-plugin",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test \"tests/**/*.test.mjs\"",
+    "build:site": "node site/build.mjs",
+    "version-sync": "node scripts/version-sync.mjs",
+    "check-consistency": "node scripts/check-consistency.mjs",
+    "release": "node scripts/release.mjs",
+    "optimize": "node scripts/optimize.mjs",
+    "trend": "node scripts/trend.mjs",
+    "context-pack": "node scripts/context-pack.mjs",
+    "simulate-edit": "node scripts/simulate-edit.mjs",
+    "hotspots": "node scripts/hotspots.mjs",
+    "campaign": "node scripts/campaign.mjs",
+    "bench": "node scripts/bench.mjs",
+    "bench:all": "node bench/all.mjs",
+    "stats": "node scripts/stats.mjs",
+    "reading-order": "node scripts/reading-order.mjs",
+    "annotate": "node scripts/annotate.mjs",
+    "bench:ts-engine": "node scripts/bench-ts-engine.mjs"
+  },
+  "optionalDependencies": {
+    "web-tree-sitter": "0.26.9"
+  }
+}

package/scripts/annotate.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+// codeweb annotate (F7) — record (or list) false-positive suppressions for finding fingerprints in
+// <dir>/annotations.json (default .codeweb). This is the ONLY mutation in the suppression workflow and
+// it writes to .codeweb metadata, NEVER to source. Idempotent by fingerprint. Built on
+// ./lib/annotations.mjs. A finding's fingerprint comes from the tools that emit it (deadcode/overlap).
+//
+// Usage:
+//   node annotate.mjs --suppress <fingerprint> [--note "why"] [--dir <.codeweb>] [--json]
+//   node annotate.mjs --list [--dir <.codeweb>] [--json]
+// Exit: 0 ok, 2 usage.
+
+import { resolve } from 'node:path';
+import { addSuppression, loadAnnotations } from './lib/annotations.mjs';
+
+const USAGE = 'usage: annotate.mjs (--suppress <fingerprint> [--note "..."] | --list) [--dir <.codeweb>] [--json]';
+import { die, emitJson, finish } from './lib/cli.mjs';
+
+const argv = process.argv.slice(2);
+let json = false, list = false, fp = null, note = '', dir = '.codeweb';
+for (let i = 0; i < argv.length; i++) {
+  const t = argv[i];
+  if (t === '--json') json = true;
+  else if (t === '--list') list = true;
+  else if (t === '--suppress') fp = argv[++i];
+  else if (t === '--note') note = argv[++i];
+  else if (t === '--dir') dir = argv[++i];
+}
+const annDir = resolve(dir);
+
+if (list) {
+  const ann = loadAnnotations(annDir);
+  if (json) emitJson(ann);
+  else {
+    console.log(`codeweb annotations (${annDir}): ${ann.suppressions.length} suppression(s)`);
+    for (const s of ann.suppressions) console.log(`  ${s.fingerprint}  ${s.verdict}${s.note ? `  — ${s.note}` : ''}`);
+    finish(0);
+  }
+} else {
+  if (!fp) die(USAGE, 2);
+  const ann = addSuppression(annDir, fp, { note, verdict: 'false-positive' });
+  if (json) emitJson({ dir: annDir, fingerprint: fp, suppressions: ann.suppressions.length });
+  else {
+    console.log(`codeweb annotate: suppressed ${fp} in ${annDir} (${ann.suppressions.length} total). Source untouched.`);
+    finish(0);
+  }
+}

package/scripts/bench-ts-engine.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+// Benchmark the optional tree-sitter complexity tier END-TO-END vs the regex F4 default, on a real
+// target. This is the "performance gate" from docs/backlog-ast-tree-sitter.md (risk #3): does the
+// parse cost stay acceptable before the tier is ever considered for default-on?
+//
+// Usage: node scripts/bench-ts-engine.mjs [target-dir]   (default: bench/corpus/axios)
+//   --no-ctags is forced so symbol discovery is identical on both sides; the ONLY variable is which
+//   engine computes complexity. Reports best-of-N wall time (subprocess) + per-symbol overhead.
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const argvAll = process.argv.slice(2);
+let outPath = null;
+const positional = [];
+for (let i = 0; i < argvAll.length; i++) {
+  if (argvAll[i] === '--out') outPath = argvAll[++i];
+  else positional.push(argvAll[i]);
+}
+const target = positional[0] || 'bench/corpus/axios';
+if (!existsSync(target)) { console.error(`[bench] target not found: ${target}`); process.exit(1); }
+const EXTRACT = resolve('scripts/extract-symbols.mjs');
+const REPS = 3;
+
+function timeRun(extra) {
+  const t0 = performance.now();
+  const r = spawnSync(process.execPath, [EXTRACT, target, '--no-ctags', ...extra], { encoding: 'utf8', maxBuffer: 1 << 28 });
+  const ms = performance.now() - t0;
+  if (r.status !== 0) { console.error(r.stderr); throw new Error('[bench] extract failed'); }
+  const frag = JSON.parse(r.stdout);
+  return { ms, symbols: frag.nodes.length, withCx: frag.nodes.filter((n) => n.complexity != null).length, engine: frag.meta.complexityEngine || 'regex' };
+}
+const best = (extra) => { let b = null; for (let i = 0; i < REPS; i++) { const r = timeRun(extra); if (!b || r.ms < b.ms) b = r; } return b; };
+
+console.log(`[bench] target: ${target}   (best of ${REPS} runs each, --no-ctags)`);
+// The tier is DEFAULT-ON since v9, so the regex arm must opt out explicitly — a no-flag arm
+// would silently benchmark tree-sitter against itself (the bug this line fixes).
+const regex = best(['--engine', 'regex']);
+const ts = best(['--engine', 'tree-sitter']);
+if (ts.engine === 'regex') { console.error('[bench] tree-sitter engine unavailable (optional dep not installed) — aborting'); process.exit(1); }
+
+const overhead = ts.ms - regex.ms;
+const perSym = ts.withCx > 0 ? overhead / ts.withCx : 0;
+console.log(`[bench] symbols: ${regex.symbols} (${regex.withCx} with complexity)`);
+console.log(`[bench] regex F4:    ${regex.ms.toFixed(0).padStart(6)} ms`);
+console.log(`[bench] tree-sitter: ${ts.ms.toFixed(0).padStart(6)} ms   (${ts.engine})`);
+console.log(`[bench] overhead:    ${('+' + overhead.toFixed(0)).padStart(6)} ms   = ${(ts.ms / regex.ms).toFixed(2)}x   = +${perSym.toFixed(3)} ms/symbol`);
+if (outPath) {
+  const payload = {
+    bench: 'ts-engine (cold extraction, regex vs tree-sitter tier)', target, reps: REPS,
+    symbols: regex.symbols, withComplexity: regex.withCx,
+    regexMs: Math.round(regex.ms), treeSitterMs: Math.round(ts.ms),
+    overheadMs: Math.round(overhead), factor: +(ts.ms / regex.ms).toFixed(2),
+    perSymbolMs: +perSym.toFixed(3), engine: ts.engine,
+  };
+  writeFileSync(outPath, JSON.stringify(payload, null, 2) + '\n');
+  console.log(`[bench] wrote ${outPath}`);
+}