feat: node role classification + dead code detection

.claude/skills/dogfood/SKILL.md

@@ -158,6 +158,33 @@ Test that incremental rebuilds, full rebuilds, and cross-feature state remain co
 
 ---
 
+## Phase 4b — Performance Benchmarks
+
+Run all four benchmark scripts from the codegraph source repo (not the temp install dir) and record results. These detect performance regressions between releases.
+
+| Benchmark | Script | What it measures | When it matters |
+|-----------|--------|-----------------|-----------------|
+| Build | `node scripts/benchmark.js` | Build speed (native vs WASM), query latency | Always |
+| Incremental | `node scripts/incremental-benchmark.js` | Incremental build tiers, import resolution throughput | Always |
+| Query | `node scripts/query-benchmark.js` | Query depth scaling, diff-impact latency | Always |
+| Embedding | `node scripts/embedding-benchmark.js` | Search recall (Hit@1/3/5/10) across models | Always |
+
+1. Run all four from the codegraph source repo directory.
+2. Record the JSON output from each.
+3. Compare with the previous release's numbers in `generated/BUILD-BENCHMARKS.md` (build benchmark) and previous dogfood reports.
+4. Flag any regressions:
+   - Build time per file >10% slower → investigate
+   - Query latency >2x slower → investigate
+   - Embedding recall (Hit@5) drops by >2% → investigate
+   - Incremental no-op >10ms → investigate
+5. Include a **Performance Benchmarks** section in the report with tables for each benchmark.
+
+**Note:** The native engine may not be available in the dev repo (no prebuilt binary in `node_modules`). Record WASM results at minimum. If native is available, record both.
+
+**IMPORTANT:** If your bug-fix PR touches code covered by a benchmark (`builder.js`, `parser.js`, `queries.js`, `resolve.js`, `db.js`, `embedder.js`, `journal.js`), you **must** run the relevant benchmarks **before and after** your changes and include the comparison in the PR description.
+
+---
+
 ## Phase 5 — Changes Since Last Release
 
 1. Read `CHANGELOG.md` to identify what changed in v$ARGUMENTS vs the previous version.
@@ -254,14 +281,15 @@ For each bug you can fix in this session:
 2. Implement the fix.
 3. Run `npm test` to verify no regressions.
 4. Run `npm run lint` to verify code style.
-5. Commit with a message referencing the issue:
+5. **Run benchmarks before and after** if your fix touches code covered by a benchmark (see Phase 4b table). Include the comparison in the PR body.
+6. Commit with a message referencing the issue:
    ```
    fix(<scope>): <description>
 
    Closes #<issue-number>
    ```
    The `Closes #N` footer tells GitHub to auto-close the issue when the PR merges.
-6. Push and open a PR:
+7. Push and open a PR. If benchmarks were run, include them in the body:
    ```bash
    gh pr create --base main \
      --title "fix(<scope>): <description>" \
@@ -272,12 +300,15 @@ For each bug you can fix in this session:
    ## Found during
    Dogfooding v$ARGUMENTS — see #<issue-number>
 
+   ## Benchmark results
+   <before/after table if applicable — see Phase 4b>
+
    ## Test plan
    - [ ] <how to verify the fix>
    PR_EOF
    )"
    ```
-7. Return to the main working branch before continuing to the next bug.
+8. Return to the main working branch before continuing to the next bug.
 
 If a bug is too complex to fix in this session, leave the issue open and note it in the report.
 

README.md

@@ -55,7 +55,7 @@ cd your-project
 codegraph build
 ```
 
-That's it. No config files, no Docker, no JVM, no API keys, no accounts. The graph is ready to query. Add `codegraph mcp` to your AI agent's config and it has full access to your dependency graph through 17 MCP tools.
+That's it. No config files, no Docker, no JVM, no API keys, no accounts. The graph is ready to query. Add `codegraph mcp` to your AI agent's config and it has full access to your dependency graph through 18 MCP tools.
 
 ### Why it matters
 
@@ -79,6 +79,7 @@ That's it. No config files, no Docker, no JVM, no API keys, no accounts. The gra
 | MCP / AI agent support | **Yes** | — | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | — |
 | Git diff impact | **Yes** | — | — | — | — | **Yes** | — | **Yes** |
 | Watch mode | **Yes** | — | **Yes** | — | — | — | — | — |
+| Dead code / role classification | **Yes** | — | **Yes** | — | — | — | — | **Yes** |
 | Cycle detection | **Yes** | — | **Yes** | — | — | — | — | **Yes** |
 | Incremental rebuilds | **O(changed)** | — | O(n) Merkle | — | — | — | — | — |
 | Zero config | **Yes** | — | **Yes** | — | — | — | — | — |
@@ -94,7 +95,8 @@ That's it. No config files, no Docker, no JVM, no API keys, no accounts. The gra
 | **⚡** | **Always-fresh graph** | Three-tier change detection: journal (O(changed)) → mtime+size (O(n) stats) → hash (O(changed) reads). Sub-second rebuilds even on large codebases |
 | **🔓** | **Zero-cost core, LLM-enhanced when you want** | Full graph analysis with no API keys, no accounts, no cost. Optionally bring your own LLM provider — your code only goes where you choose |
 | **🔬** | **Function-level, not just files** | Traces `handleAuth()` → `validateToken()` → `decryptJWT()` and shows 14 callers across 9 files break if `decryptJWT` changes |
-| **🤖** | **Built for AI agents** | 17-tool [MCP server](https://modelcontextprotocol.io/) — AI assistants query your graph directly. Single-repo by default |
+| **🏷️** | **Role classification** | Every symbol auto-tagged as `entry`/`core`/`utility`/`adapter`/`dead`/`leaf` — agents instantly know what they're looking at |
+| **🤖** | **Built for AI agents** | 18-tool [MCP server](https://modelcontextprotocol.io/) — AI assistants query your graph directly. Single-repo by default |
 | **🌐** | **Multi-language, one CLI** | JS/TS + Python + Go + Rust + Java + C# + PHP + Ruby + HCL in a single graph |
 | **💥** | **Git diff impact** | `codegraph diff-impact` shows changed functions, their callers, and full blast radius — ships with a GitHub Actions workflow |
 | **🧠** | **Semantic search** | Local embeddings by default, LLM-powered when opted in — multi-query with RRF ranking via `"auth; token; JWT"` |
@@ -141,7 +143,7 @@ After modifying code:
 Or connect directly via MCP:
 
 ```bash
-codegraph mcp          # 17-tool MCP server — AI queries the graph directly
+codegraph mcp          # 18-tool MCP server — AI queries the graph directly
 ```
 
 Full agent setup: [AI Agent Guide](docs/guides/ai-agent-guide.md) · [CLAUDE.md template](docs/guides/ai-agent-guide.md#claudemd-template)
@@ -161,11 +163,12 @@ Full agent setup: [AI Agent Guide](docs/guides/ai-agent-guide.md) · [CLAU
 | 📊 | **Diff impact** | Parse `git diff`, find overlapping functions, trace their callers |
 | 🗺️ | **Module map** | Bird's-eye view of your most-connected files |
 | 🏗️ | **Structure & hotspots** | Directory cohesion scores, fan-in/fan-out hotspot detection, module boundaries |
+| 🏷️ | **Node role classification** | Every symbol auto-tagged as `entry`/`core`/`utility`/`adapter`/`dead`/`leaf` based on connectivity patterns — agents instantly know architectural role |
 | 🔄 | **Cycle detection** | Find circular dependencies at file or function level |
 | 📤 | **Export** | DOT (Graphviz), Mermaid, and JSON graph export |
 | 🧠 | **Semantic search** | Embeddings-powered natural language search with multi-query RRF ranking |
 | 👀 | **Watch mode** | Incrementally update the graph as files change |
-| 🤖 | **MCP server** | 17-tool MCP server for AI assistants; single-repo by default, opt-in multi-repo |
+| 🤖 | **MCP server** | 18-tool MCP server for AI assistants; single-repo by default, opt-in multi-repo |
 | ⚡ | **Always fresh** | Three-tier incremental detection — sub-second rebuilds even on large codebases |
 
 ## 📦 Commands
@@ -189,6 +192,9 @@ codegraph map -n 50 --no-tests # Top 50, excluding test files
 codegraph where <name>         # Where is a symbol defined and used?
 codegraph where --file src/db.js  # List symbols, imports, exports for a file
 codegraph stats                # Graph health: nodes, edges, languages, quality score
+codegraph roles                # Node role classification (entry, core, utility, adapter, dead, leaf)
+codegraph roles --role dead -T # Find dead code (unreferenced, non-exported symbols)
+codegraph roles --role core --file src/  # Core symbols in src/
 ```
 
 ### Deep Context (AI-Optimized)
@@ -402,7 +408,7 @@ Optional: `@huggingface/transformers` (semantic search), `@modelcontextprotocol/
 
 ### MCP Server
 
-Codegraph includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server with 17 tools, so AI assistants can query your dependency graph directly:
+Codegraph includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server with 18 tools, so AI assistants can query your dependency graph directly:
 
 ```bash
 codegraph mcp                  # Single-repo mode (default) — only local project
@@ -589,6 +595,7 @@ const { results: fused } = await multiSearchData(
 | Incremental rebuilds | **O(changed)** | — | O(n) Merkle | — | — | — |
 | MCP / AI agent support | **Yes** | — | **Yes** | **Yes** | **Yes** | **Yes** |
 | Git diff impact | **Yes** | — | — | — | — | **Yes** |
+| Dead code / role classification | **Yes** | — | **Yes** | — | — | — |
 | Semantic search | **Yes** | — | **Yes** | **Yes** | — | **Yes** |
 | Watch mode | **Yes** | — | **Yes** | — | — | — |
 | Zero config, no Docker/JVM | **Yes** | — | **Yes** | — | — | — |
@@ -606,7 +613,7 @@ See **[ROADMAP.md](ROADMAP.md)** for the full development roadmap and **[STABILI
 5. **Natural Language Queries** — `codegraph ask` command, conversational sessions
 6. **Expanded Language Support** — 8 new languages (12 → 20)
 7. **GitHub Integration & CI** — reusable GitHub Action, PR review, SARIF output
-8. **Visualization & Advanced** — web UI, dead code detection, monorepo support, agentic search
+8. **Visualization & Advanced** — web UI, monorepo support, agentic search
 
 ## 🤝 Contributing
 

docs/BACKLOG.md

@@ -1,6 +1,6 @@
 # Codegraph Feature Backlog
 
-**Last updated:** 2026-02-23
+**Last updated:** 2026-02-25
 **Source:** Features derived from [COMPETITIVE_ANALYSIS.md](../generated/COMPETITIVE_ANALYSIS.md) and internal roadmap discussions.
 
 ---
@@ -26,9 +26,9 @@ Non-breaking, ordered by problem-fit:
 
 | ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking |
 |----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|
-| 4 | Node classification | Auto-tag symbols as Entry Point / Core / Utility / Adapter based on in-degree/out-degree patterns. High fan-in + low fan-out = Core. Zero fan-in + non-export = Dead. Inspired by arbor. | Intelligence | Agents immediately understand architectural role of any symbol without reading surrounding code — fewer orientation tokens | ✓ | ✓ | 5 | No |
+| 4 | ~~Node classification~~ | ~~Auto-tag symbols as Entry Point / Core / Utility / Adapter based on in-degree/out-degree patterns. High fan-in + low fan-out = Core. Zero fan-in + non-export = Dead. Inspired by arbor.~~ | Intelligence | ~~Agents immediately understand architectural role of any symbol without reading surrounding code — fewer orientation tokens~~ | ✓ | ✓ | 5 | No | **DONE** — `classifyNodeRoles()` in `structure.js` auto-tags every symbol as `entry`/`core`/`utility`/`adapter`/`dead`/`leaf` using median-based fan-in/fan-out thresholds. Roles stored in DB (`role` column, migration v5), surfaced in `where`/`explain`/`context`/`stats`/`list-functions`, new `roles` CLI command, new `node_roles` MCP tool (18 tools total). Includes `--role` and `--file` filters. |
 | 9 | Git change coupling | Analyze git history for files/functions that always change together. Surfaces hidden dependencies that the static graph can't see. Enhances `diff-impact` with historical co-change data. Inspired by axon. | Analysis | `diff-impact` catches more breakage by including historically coupled files; agents get a more complete blast radius picture | ✓ | ✓ | 5 | No |
-| 1 | Dead code detection | Find symbols with zero incoming edges (excluding entry points and exports). Agents constantly ask "is this used?" — the graph already has the data, we just need to surface it. Inspired by narsil-mcp, axon, codexray, CKB. | Analysis | Agents stop wasting tokens investigating dead code; developers get actionable cleanup lists without external tools | ✓ | ✓ | 4 | No |
+| 1 | ~~Dead code detection~~ | ~~Find symbols with zero incoming edges (excluding entry points and exports). Agents constantly ask "is this used?" — the graph already has the data, we just need to surface it. Inspired by narsil-mcp, axon, codexray, CKB.~~ | Analysis | ~~Agents stop wasting tokens investigating dead code; developers get actionable cleanup lists without external tools~~ | ✓ | ✓ | 4 | No | **DONE** — Delivered as part of node classification (ID 4). `codegraph roles --role dead -T` lists all symbols with zero fan-in that aren't exported. |
 | 2 | Shortest path A→B | BFS/Dijkstra on the existing edges table to find how symbol A reaches symbol B. We have `fn` for single-node chains but no A→B pathfinding. Inspired by codexray, arbor. | Navigation | Agents can answer "how does this function reach that one?" in one call instead of manually tracing chains | ✓ | ✓ | 4 | No |
 | 12 | Execution flow tracing | Framework-aware entry point detection (Express routes, CLI commands, event handlers) + BFS flow tracing from entry to leaf. Inspired by axon, GitNexus, code-context-mcp. | Navigation | Agents can answer "what happens when a user hits POST /login?" by tracing the full execution path in one query | ✓ | ✓ | 4 | No |
 | 16 | Branch structural diff | Compare code structure between two branches using git worktrees. Show added/removed/changed symbols and their impact. Inspired by axon. | Analysis | Teams can review structural impact of feature branches before merge; agents get branch-aware context | ✓ | ✓ | 4 | No |