diff --git a/docs/roadmap/BACKLOG.md b/docs/roadmap/BACKLOG.md index fd50e5de..78ac415c 100644 --- a/docs/roadmap/BACKLOG.md +++ b/docs/roadmap/BACKLOG.md @@ -15,6 +15,7 @@ Each item has a short title, description, category, expected benefit, and four a | **Foundation-aligned** | Does this feature align with the [FOUNDATION.md](../../FOUNDATION.md) core principles? Specifically: does it keep the graph always-current (P1), maintain zero-cost core with optional LLM enhancement (P4), respect embeddable-first design (P5), and optimize for planning, developing, and refactoring — not linting or CI/CD (P8)? A checkmark means full alignment. An X means it conflicts with at least one principle and needs a deliberate exception. | | **Problem-fit (1-5)** | How directly does this feature address the core problem from our README: *AI coding assistants waste tokens re-orienting themselves in large codebases, hallucinate dependencies, and miss blast radius.* A 5 means it directly reduces token waste, prevents hallucinated deps, or catches breakage. A 1 means it's tangential — nice to have but doesn't solve the stated problem. | | **Breaking** | Is this a breaking change? `Yes` means existing CLI output, API signatures, DB schema, or MCP tool contracts change in incompatible ways. `No` means it's purely additive. Breaking changes require a major version bump. | +| **Depends on** | List of backlog IDs that must be completed before this item can be implemented. `—` means no dependencies. When an item is completed, scan this column to find what it unlocks — those items are now unblocked and should be prioritized. | --- @@ -24,116 +25,135 @@ Each item has a short title, description, category, expected benefit, and four a 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 | **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. 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 | **DONE** — `src/cochange.js` module with scan, compute, analyze, and query functions. DB migration v5 adds `co_changes` + `co_change_meta` tables. CLI command `codegraph co-change [file]` with `--analyze`, `--since`, `--min-support`, `--min-jaccard`, `--full` options. Integrates into `diff-impact` output via `historicallyCoupled` section. New `co_changes` MCP tool. Uses Jaccard similarity on commit history. | -| 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 | **DONE** — `codegraph path ` command with `--reverse`, `--max-depth`, `--kinds` options. BFS pathfinding on the edges table. `symbol_path` MCP tool. | -| 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 | **DONE** — `codegraph flow` command with entry point detection and BFS flow tracing. MCP tools `flow` and `entry_points` added. Merged in PR #118. | -| 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 | **DONE** — `codegraph branch-compare ` builds separate graphs for each ref using git worktrees, diffs at the symbol level (added/removed/changed), and traces transitive caller impact via BFS. Supports `--json`, `--format mermaid`, `--depth`, `--no-tests`, `--engine`. `branchCompareData` and `branchCompareMermaid` exported from programmatic API. `branch_compare` MCP tool. | -| 20 | ~~Streaming / chunked results~~ | ~~Support streaming output for large query results so MCP clients and programmatic consumers can process incrementally.~~ | Embeddability | ~~Large codebases don't blow up agent context windows; consumers process results as they arrive instead of waiting for the full payload~~ | ✓ | ✓ | 4 | No | **DONE** — Universal pagination (`limit`/`offset` + `_pagination` metadata) on all 21 MCP tools with per-tool defaults in `MCP_DEFAULTS` and hard cap of 1000. NDJSON streaming (`--ndjson`/`--limit`/`--offset`) on ~14 CLI commands via shared `printNdjson` helper. Generator APIs (`iterListFunctions`, `iterRoles`, `iterWhere`, `iterComplexity`) using `better-sqlite3` `.iterate()` for memory-efficient streaming. PR #207. | -| 27 | ~~Composite audit command~~ | ~~Single `codegraph audit ` that combines `explain`, `fn-impact`, and code health metrics into one structured report per function. Core version uses graph data; enhanced version includes Phase 4.4 `risk_score`/`complexity_notes`/`side_effects` when available. Inspired by [Titan Paradigm](../docs/use-cases/titan-paradigm.md) Gauntlet phase.~~ | Orchestration | ~~Each sub-agent in a multi-agent swarm gets everything it needs to assess a function in one call instead of 3-4 — directly reduces token waste and round-trips~~ | ✓ | ✓ | 4 | No | **DONE** — `codegraph audit ` combines explain + fn-impact + complexity metrics into one structured report. `auditData` exported from programmatic API. PR #219. | -| 28 | ~~Batch querying~~ | ~~Accept a list of targets (file or JSON) and return all query results in one JSON payload. Applies to `audit`, `fn-impact`, `context`, and other per-symbol commands. Inspired by [Titan Paradigm](../docs/use-cases/titan-paradigm.md) swarm pattern.~~ | Orchestration | ~~A swarm of 20+ agents auditing different files can be fed from a single orchestrator call instead of N sequential invocations — reduces overhead and enables parallel dispatch~~ | ✓ | ✓ | 4 | No | **DONE** — `codegraph batch ` accepts a list of targets and returns all query results in one JSON payload. Applies to `audit`, `fn-impact`, `context`, and other per-symbol commands. `batch_query` MCP tool. PR #223. | -| 29 | ~~Triage priority queue~~ | ~~Single `codegraph triage` command that merges `map` connectivity, `hotspots` fan-in/fan-out, node roles, and optionally git churn + `risk_score` into one ranked audit queue. Inspired by [Titan Paradigm](../docs/use-cases/titan-paradigm.md) RECON phase.~~ | Orchestration | ~~Orchestrating agent gets a single prioritized list of what to audit first — replaces manual synthesis of 3+ commands, saves RECON phase from burning tokens on orientation~~ | ✓ | ✓ | 4 | No | **DONE** — `codegraph triage` merges connectivity, hotspots, node roles, and complexity into a ranked audit queue. `triageData` exported from programmatic API. PR #224. | -| 32 | ~~MCP orchestration tools~~ | ~~Expose `audit`, `triage`, and `check` as MCP tools alongside existing tools. Enables multi-agent orchestrators (Claude Code agent teams, custom MCP clients) to run the full Titan Paradigm loop through the MCP protocol without CLI overhead. Inspired by [Titan Paradigm](../docs/use-cases/titan-paradigm.md).~~ | Embeddability | ~~Agents query the graph through MCP with zero CLI overhead — fewer tokens, faster round-trips, native integration with AI agent frameworks~~ | ✓ | ✓ | 4 | No | **DONE** — `check` exposed as MCP tool. `audit`, `triage`, and `batch_query` also available as MCP tools. PR #230. | -| 5 | ~~TF-IDF lightweight search~~ | ~~SQLite FTS5 + TF-IDF as a middle tier (~50MB) between "no search" and full transformer embeddings (~500MB). Provides decent keyword search with near-zero overhead. Inspired by codexray.~~ | Search | ~~Users get useful search without the 500MB embedding model download; faster startup for small projects~~ | ✓ | ✓ | 3 | No | **DONE** — Subsumed by ID 15 (Hybrid BM25 + semantic search). FTS5 full-text index (`fts_index` table) populated during `codegraph embed`. `--mode keyword` provides BM25-only search with zero embedding overhead. PR #198. | -| 13 | ~~Architecture boundary rules~~ | ~~User-defined rules for allowed/forbidden dependencies between modules (e.g., "controllers must not import from other controllers"). Violations flagged in `diff-impact` and CI. Inspired by codegraph-rust, stratify.~~ | Architecture | ~~Prevents architectural decay in CI; agents are warned before introducing forbidden cross-module dependencies~~ | ✓ | ✓ | 3 | No | **DONE** — `src/boundaries.js` with `checkBoundaries` and `validateBoundaryConfig`. Architecture boundary rules added to manifesto engine via `.codegraphrc.json` `manifesto.boundaries` config. Includes onion architecture preset (`manifesto.boundaryPreset: "onion"`). PR #228 + #229. | -| 15 | ~~Hybrid BM25 + semantic search~~ | ~~Combine BM25 keyword matching with embedding-based semantic search using Reciprocal Rank Fusion. Better recall than either approach alone. Inspired by GitNexus, claude-context-local.~~ | Search | ~~Search results improve dramatically — keyword matches catch exact names, embeddings catch conceptual matches, RRF merges both~~ | ✓ | ✓ | 3 | No | **DONE** — FTS5 full-text index alongside embeddings for BM25 keyword search. `ftsSearchData()` for keyword-only, `hybridSearchData()` for RRF fusion. `search` command defaults to `--mode hybrid`, with `semantic` and `keyword` alternatives. MCP `semantic_search` tool gains `mode` parameter. Graceful fallback on older DBs. Zero new deps — FTS5 ships with better-sqlite3. PR #198. | -| 18 | ~~CODEOWNERS integration~~ | ~~Map graph nodes to CODEOWNERS entries. Show who owns each function, surface ownership boundaries in `diff-impact`. Inspired by CKB.~~ | Developer Experience | ~~`diff-impact` tells agents which teams to notify; ownership-aware impact analysis reduces missed reviews~~ | ✓ | ✓ | 3 | No | **DONE** — `src/owners.js` module with CODEOWNERS parser, matcher, and data functions. `codegraph owners [target]` CLI command with `--owner`, `--boundary`, `-f`, `-k`, `-T`, `-j` options. `code_owners` MCP tool. Integrated into `diff-impact` (affected owners + suggested reviewers). No new deps — glob patterns via ~30-line `patternToRegex`. PR #195. | -| 22 | ~~Manifesto-driven pass/fail~~ | ~~User-defined rule engine with custom thresholds (e.g. "cognitive > 15 = fail", "cyclomatic > 10 = fail", "imports > 10 = decompose"). Outputs pass/fail per function/file. Generalizes ID 13 (boundary rules) into a generic rule system.~~ | Analysis | ~~Enables autonomous multi-agent audit workflows (GAUNTLET pattern); CI integration for code health gates with configurable thresholds~~ | ✓ | ✓ | 3 | No | **DONE** — `codegraph manifesto` with 9 configurable rules (cognitive, cyclomatic, nesting, MI, Halstead volume/effort/bugs, fan-in, fan-out). Warn/fail thresholds via `.codegraphrc.json`. Exit code 1 on any fail-level breach — CI gate ready. PR #138. | -| 31 | ~~Graph snapshots~~ | ~~`codegraph snapshot save ` / `codegraph snapshot restore ` for lightweight SQLite DB backup and restore. Enables orchestrators to checkpoint before refactoring passes and instantly rollback without rebuilding. After Phase 4, also preserves embeddings and semantic metadata. Inspired by [Titan Paradigm](../docs/use-cases/titan-paradigm.md) STATE MACHINE phase.~~ | Orchestration | ~~Multi-agent workflows get instant rollback without re-running expensive builds or LLM calls — orchestrator checkpoints before each pass and restores on failure~~ | ✓ | ✓ | 3 | No | **DONE** — `codegraph snapshot` subcommand group with `save`, `restore`, `list`, `delete`. Uses SQLite `VACUUM INTO` for atomic, WAL-free snapshots in `.codegraph/snapshots/`. All 6 functions exported via programmatic API. PR #192. | -| 30 | ~~Change validation predicates~~ | ~~`codegraph check --staged` with configurable predicates: `--no-new-cycles`, `--max-blast-radius N`, `--no-signature-changes`, `--no-boundary-violations`. Returns exit code 0/1 for CI gates and state machines. Inspired by [Titan Paradigm](../docs/use-cases/titan-paradigm.md) STATE MACHINE phase.~~ | CI | ~~Automated rollback triggers without parsing JSON — orchestrators and CI pipelines get first-class pass/fail signals for blast radius, cycles, and contract changes~~ | ✓ | ✓ | 3 | No | **DONE** — `codegraph check` with `--no-new-cycles`, `--max-complexity N`, `--max-blast-radius N`, `--no-boundary-violations`, and `--staged`/ref support. Exit code 0/1 for CI gates. `check` MCP tool. PR #225 + #230. | -| 6 | ~~Formal code health metrics~~ | ~~Cyclomatic complexity, Maintainability Index, and Halstead metrics per function — we already parse the AST, the data is there. Inspired by code-health-meter (published in ACM TOSEM 2025).~~ | Analysis | ~~Agents can prioritize refactoring targets; `hotspots` becomes richer with quantitative health scores per function~~ | ✓ | ✓ | 2 | No | **DONE** — `codegraph complexity` provides cognitive, cyclomatic, nesting depth, Halstead (volume, difficulty, effort, bugs), and Maintainability Index per function. `--health` for full Halstead view, `--sort mi` to rank by MI, `--above-threshold` for flagged functions. `function_complexity` DB table. `complexity` MCP tool. PR #130 + #139. | -| 11 | ~~Community detection~~ | ~~Leiden/Louvain algorithm to discover natural module boundaries vs actual file organization. Reveals which symbols are tightly coupled and whether the directory structure matches. Inspired by axon, GitNexus, CodeGraphMCPServer.~~ | Intelligence | ~~Surfaces architectural drift — when directory structure no longer matches actual dependency clusters; guides refactoring~~ | ✓ | ✓ | 2 | No | **DONE** — `codegraph communities` with Louvain algorithm. File-level and `--functions` function-level detection. `--drift` for drift analysis (split/merge candidates). `--resolution` tunable. `communities` MCP tool. PR #133/#134. | -| 21 | ~~Cognitive + cyclomatic complexity~~ | ~~Cognitive Complexity (SonarSource) as the primary readability metric — penalizes nesting, so it subsumes nesting depth analysis. Cyclomatic complexity (McCabe) as secondary testability metric. Both computed from existing tree-sitter AST in a single traversal. Cognitive > 15 or cyclomatic > 10 = flag for refactoring. Extends ID 6 with the two most actionable metrics.~~ | Analysis | ~~Agents can flag hard-to-understand and hard-to-test functions in one pass; cognitive complexity captures both decision complexity and nesting depth in a single score~~ | ✓ | ✓ | 2 | No | **DONE** — Subsumed by ID 6. `codegraph complexity` provides both cognitive and cyclomatic metrics (plus nesting depth, Halstead, MI) in a single command. PR #130. | -| 33 | ~~Intraprocedural CFG~~ | ~~Build basic-block control flow graphs from tree-sitter AST for individual functions. Enables complexity-aware impact analysis and opens the path to dataflow (def-use chains). Inspired by Joern, cpg.~~ | Analysis | ~~Agents can visualize control flow through complex functions; enables more precise complexity metrics and future dataflow analysis~~ | ✓ | ✓ | 3 | No | **DONE** — `codegraph cfg ` with text/DOT/Mermaid output. Opt-in via `build --cfg`. DB migration v12 adds `cfg_blocks` + `cfg_edges` tables. Handles if/else, for/while/do-while, switch, try/catch/finally, break/continue (with labels), return/throw. Extended to all 11 languages with per-language `CFG_RULES`. `cfg` MCP tool. PR #274, #279, #283. | -| 34 | ~~AST node storage~~ | ~~Persist selected AST nodes (calls, new, string, regex, throw, await) in a queryable table during build. Enables pattern search without re-parsing. Inspired by Joern's CPG stored AST.~~ | Analysis | ~~Agents can search for patterns like "all throw statements" or "all string literals matching /api/" without re-parsing — instant structured queries on the AST~~ | ✓ | ✓ | 3 | No | **DONE** — `codegraph ast [pattern]` with `-k` (call, new, string, regex, throw, await), `-f`, `-T` filters. DB migration v13 adds `ast_nodes` table. SQL GLOB with auto-wrapping for substring search. Parent node resolution via narrowest enclosing definition. `ast_query` MCP tool. PR #279. | -| 35 | ~~Expanded node/edge types~~ | ~~Add parameter, property, constant node kinds with parent_id for sub-declaration queries. Add contains, parameter_of, receiver structural edge kinds. Inspired by Joern, cpg.~~ | Analysis | ~~Agents can answer "which functions take a Request param?" or "which classes have a userId field?" without reading source — structural queries on the graph~~ | ✓ | ✓ | 4 | Yes | **DONE** — `parameter`, `property`, `constant` node kinds extracted across all 9 WASM extractors. DB migration v11 adds `parent_id` column. `contains` (file→definition, parent→child), `parameter_of` (inverse), `receiver` (method dispatch) edge kinds. `codegraph children ` command. `symbol_children` MCP tool. PR #270, #279. | -| 36 | ~~Exports analysis~~ | ~~Show all exported symbols of a file with per-symbol consumers (who calls each export), re-export detection, and counts.~~ | Analysis | ~~Agents understand a file's public API surface and its consumers in one call — useful for assessing impact of API changes~~ | ✓ | ✓ | 4 | No | **DONE** — `codegraph exports ` with re-export detection and consumer counts. `exportsData` programmatic API. `file_exports` MCP tool. PR #269. | -| 37 | ~~Stable JSON schema~~ | ~~normalizeSymbol utility ensuring consistent 7-field output (name, kind, file, line, endLine, role, fileHash) across all query and search commands.~~ | Embeddability | ~~Programmatic consumers and MCP clients get predictable JSON shapes without field-name surprises across different commands~~ | ✓ | ✓ | 3 | No | **DONE** — `normalizeSymbol(row, db, hashCache)` used by all query and search functions. `docs/json-schema.md` documents the stable schema. Exported from programmatic API. PR #267. | -| 38 | ~~GraphML / GraphSON / Neo4j CSV export~~ | ~~Add GraphML (XML standard), GraphSON (TinkerPop v3), and Neo4j CSV (bulk import) export formats for graph database interoperability.~~ | Export | ~~Users can load codegraph data into Neo4j, JanusGraph, or any GraphML-compatible tool for advanced visualization and querying~~ | ✓ | ✓ | 2 | No | **DONE** — `codegraph export -f graphml|graphson|neo4j` with file-level and function-level modes. Neo4j outputs separate nodes/relationships CSV files. PR #268. | -| 39 | ~~CLI consolidation~~ | ~~Streamline CLI by removing redundant commands: batch-query → batch, hotspots → triage --level, manifesto → check, explain → audit --quick. Reduce MCP tool surface from 32 to 30.~~ | Developer Experience | ~~Fewer commands to learn; each command is more capable; MCP tool surface is smaller and more consistent~~ | ✓ | ✓ | 3 | Yes | **DONE** — Removed `batch-query`, `hotspots`, `manifesto`, `explain`, and `query --path`. MCP tools `fn_deps`, `symbol_path`, `list_entry_points` merged into `query` and `execution_flow`. Standalone `path ` added. PR #263, #280. | +| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on | +|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------| +| 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. 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 | — | **DONE** — `src/cochange.js` module with scan, compute, analyze, and query functions. DB migration v5 adds `co_changes` + `co_change_meta` tables. CLI command `codegraph co-change [file]` with `--analyze`, `--since`, `--min-support`, `--min-jaccard`, `--full` options. Integrates into `diff-impact` output via `historicallyCoupled` section. New `co_changes` MCP tool. Uses Jaccard similarity on commit history. | +| 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 | — | **DONE** — `codegraph path ` command with `--reverse`, `--max-depth`, `--kinds` options. BFS pathfinding on the edges table. `symbol_path` MCP tool. | +| 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 | — | **DONE** — `codegraph flow` command with entry point detection and BFS flow tracing. MCP tools `flow` and `entry_points` added. Merged in PR #118. | +| 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 | — | **DONE** — `codegraph branch-compare ` builds separate graphs for each ref using git worktrees, diffs at the symbol level (added/removed/changed), and traces transitive caller impact via BFS. Supports `--json`, `--format mermaid`, `--depth`, `--no-tests`, `--engine`. `branchCompareData` and `branchCompareMermaid` exported from programmatic API. `branch_compare` MCP tool. | +| 20 | ~~Streaming / chunked results~~ | ~~Support streaming output for large query results so MCP clients and programmatic consumers can process incrementally.~~ | Embeddability | ~~Large codebases don't blow up agent context windows; consumers process results as they arrive instead of waiting for the full payload~~ | ✓ | ✓ | 4 | No | — | **DONE** — Universal pagination (`limit`/`offset` + `_pagination` metadata) on all 21 MCP tools with per-tool defaults in `MCP_DEFAULTS` and hard cap of 1000. NDJSON streaming (`--ndjson`/`--limit`/`--offset`) on ~14 CLI commands via shared `printNdjson` helper. Generator APIs (`iterListFunctions`, `iterRoles`, `iterWhere`, `iterComplexity`) using `better-sqlite3` `.iterate()` for memory-efficient streaming. PR #207. | +| 27 | ~~Composite audit command~~ | ~~Single `codegraph audit ` that combines `explain`, `fn-impact`, and code health metrics into one structured report per function. Core version uses graph data; enhanced version includes Phase 4.4 `risk_score`/`complexity_notes`/`side_effects` when available. Inspired by [Titan Paradigm](../docs/use-cases/titan-paradigm.md) Gauntlet phase.~~ | Orchestration | ~~Each sub-agent in a multi-agent swarm gets everything it needs to assess a function in one call instead of 3-4 — directly reduces token waste and round-trips~~ | ✓ | ✓ | 4 | No | — | **DONE** — `codegraph audit ` combines explain + fn-impact + complexity metrics into one structured report. `auditData` exported from programmatic API. PR #219. | +| 28 | ~~Batch querying~~ | ~~Accept a list of targets (file or JSON) and return all query results in one JSON payload. Applies to `audit`, `fn-impact`, `context`, and other per-symbol commands. Inspired by [Titan Paradigm](../docs/use-cases/titan-paradigm.md) swarm pattern.~~ | Orchestration | ~~A swarm of 20+ agents auditing different files can be fed from a single orchestrator call instead of N sequential invocations — reduces overhead and enables parallel dispatch~~ | ✓ | ✓ | 4 | No | — | **DONE** — `codegraph batch ` accepts a list of targets and returns all query results in one JSON payload. Applies to `audit`, `fn-impact`, `context`, and other per-symbol commands. `batch_query` MCP tool. PR #223. | +| 29 | ~~Triage priority queue~~ | ~~Single `codegraph triage` command that merges `map` connectivity, `hotspots` fan-in/fan-out, node roles, and optionally git churn + `risk_score` into one ranked audit queue. Inspired by [Titan Paradigm](../docs/use-cases/titan-paradigm.md) RECON phase.~~ | Orchestration | ~~Orchestrating agent gets a single prioritized list of what to audit first — replaces manual synthesis of 3+ commands, saves RECON phase from burning tokens on orientation~~ | ✓ | ✓ | 4 | No | — | **DONE** — `codegraph triage` merges connectivity, hotspots, node roles, and complexity into a ranked audit queue. `triageData` exported from programmatic API. PR #224. | +| 32 | ~~MCP orchestration tools~~ | ~~Expose `audit`, `triage`, and `check` as MCP tools alongside existing tools. Enables multi-agent orchestrators (Claude Code agent teams, custom MCP clients) to run the full Titan Paradigm loop through the MCP protocol without CLI overhead. Inspired by [Titan Paradigm](../docs/use-cases/titan-paradigm.md).~~ | Embeddability | ~~Agents query the graph through MCP with zero CLI overhead — fewer tokens, faster round-trips, native integration with AI agent frameworks~~ | ✓ | ✓ | 4 | No | — | **DONE** — `check` exposed as MCP tool. `audit`, `triage`, and `batch_query` also available as MCP tools. PR #230. | +| 5 | ~~TF-IDF lightweight search~~ | ~~SQLite FTS5 + TF-IDF as a middle tier (~50MB) between "no search" and full transformer embeddings (~500MB). Provides decent keyword search with near-zero overhead. Inspired by codexray.~~ | Search | ~~Users get useful search without the 500MB embedding model download; faster startup for small projects~~ | ✓ | ✓ | 3 | No | — | **DONE** — Subsumed by ID 15 (Hybrid BM25 + semantic search). FTS5 full-text index (`fts_index` table) populated during `codegraph embed`. `--mode keyword` provides BM25-only search with zero embedding overhead. PR #198. | +| 13 | ~~Architecture boundary rules~~ | ~~User-defined rules for allowed/forbidden dependencies between modules (e.g., "controllers must not import from other controllers"). Violations flagged in `diff-impact` and CI. Inspired by codegraph-rust, stratify.~~ | Architecture | ~~Prevents architectural decay in CI; agents are warned before introducing forbidden cross-module dependencies~~ | ✓ | ✓ | 3 | No | — | **DONE** — `src/boundaries.js` with `checkBoundaries` and `validateBoundaryConfig`. Architecture boundary rules added to manifesto engine via `.codegraphrc.json` `manifesto.boundaries` config. Includes onion architecture preset (`manifesto.boundaryPreset: "onion"`). PR #228 + #229. | +| 15 | ~~Hybrid BM25 + semantic search~~ | ~~Combine BM25 keyword matching with embedding-based semantic search using Reciprocal Rank Fusion. Better recall than either approach alone. Inspired by GitNexus, claude-context-local.~~ | Search | ~~Search results improve dramatically — keyword matches catch exact names, embeddings catch conceptual matches, RRF merges both~~ | ✓ | ✓ | 3 | No | — | **DONE** — FTS5 full-text index alongside embeddings for BM25 keyword search. `ftsSearchData()` for keyword-only, `hybridSearchData()` for RRF fusion. `search` command defaults to `--mode hybrid`, with `semantic` and `keyword` alternatives. MCP `semantic_search` tool gains `mode` parameter. Graceful fallback on older DBs. Zero new deps — FTS5 ships with better-sqlite3. PR #198. | +| 18 | ~~CODEOWNERS integration~~ | ~~Map graph nodes to CODEOWNERS entries. Show who owns each function, surface ownership boundaries in `diff-impact`. Inspired by CKB.~~ | Developer Experience | ~~`diff-impact` tells agents which teams to notify; ownership-aware impact analysis reduces missed reviews~~ | ✓ | ✓ | 3 | No | — | **DONE** — `src/owners.js` module with CODEOWNERS parser, matcher, and data functions. `codegraph owners [target]` CLI command with `--owner`, `--boundary`, `-f`, `-k`, `-T`, `-j` options. `code_owners` MCP tool. Integrated into `diff-impact` (affected owners + suggested reviewers). No new deps — glob patterns via ~30-line `patternToRegex`. PR #195. | +| 22 | ~~Manifesto-driven pass/fail~~ | ~~User-defined rule engine with custom thresholds (e.g. "cognitive > 15 = fail", "cyclomatic > 10 = fail", "imports > 10 = decompose"). Outputs pass/fail per function/file. Generalizes ID 13 (boundary rules) into a generic rule system.~~ | Analysis | ~~Enables autonomous multi-agent audit workflows (GAUNTLET pattern); CI integration for code health gates with configurable thresholds~~ | ✓ | ✓ | 3 | No | — | **DONE** — `codegraph manifesto` with 9 configurable rules (cognitive, cyclomatic, nesting, MI, Halstead volume/effort/bugs, fan-in, fan-out). Warn/fail thresholds via `.codegraphrc.json`. Exit code 1 on any fail-level breach — CI gate ready. PR #138. | +| 31 | ~~Graph snapshots~~ | ~~`codegraph snapshot save ` / `codegraph snapshot restore ` for lightweight SQLite DB backup and restore. Enables orchestrators to checkpoint before refactoring passes and instantly rollback without rebuilding. After Phase 4, also preserves embeddings and semantic metadata. Inspired by [Titan Paradigm](../docs/use-cases/titan-paradigm.md) STATE MACHINE phase.~~ | Orchestration | ~~Multi-agent workflows get instant rollback without re-running expensive builds or LLM calls — orchestrator checkpoints before each pass and restores on failure~~ | ✓ | ✓ | 3 | No | — | **DONE** — `codegraph snapshot` subcommand group with `save`, `restore`, `list`, `delete`. Uses SQLite `VACUUM INTO` for atomic, WAL-free snapshots in `.codegraph/snapshots/`. All 6 functions exported via programmatic API. PR #192. | +| 30 | ~~Change validation predicates~~ | ~~`codegraph check --staged` with configurable predicates: `--no-new-cycles`, `--max-blast-radius N`, `--no-signature-changes`, `--no-boundary-violations`. Returns exit code 0/1 for CI gates and state machines. Inspired by [Titan Paradigm](../docs/use-cases/titan-paradigm.md) STATE MACHINE phase.~~ | CI | ~~Automated rollback triggers without parsing JSON — orchestrators and CI pipelines get first-class pass/fail signals for blast radius, cycles, and contract changes~~ | ✓ | ✓ | 3 | No | — | **DONE** — `codegraph check` with `--no-new-cycles`, `--max-complexity N`, `--max-blast-radius N`, `--no-boundary-violations`, and `--staged`/ref support. Exit code 0/1 for CI gates. `check` MCP tool. PR #225 + #230. | +| 6 | ~~Formal code health metrics~~ | ~~Cyclomatic complexity, Maintainability Index, and Halstead metrics per function — we already parse the AST, the data is there. Inspired by code-health-meter (published in ACM TOSEM 2025).~~ | Analysis | ~~Agents can prioritize refactoring targets; `hotspots` becomes richer with quantitative health scores per function~~ | ✓ | ✓ | 2 | No | — | **DONE** — `codegraph complexity` provides cognitive, cyclomatic, nesting depth, Halstead (volume, difficulty, effort, bugs), and Maintainability Index per function. `--health` for full Halstead view, `--sort mi` to rank by MI, `--above-threshold` for flagged functions. `function_complexity` DB table. `complexity` MCP tool. PR #130 + #139. | +| 11 | ~~Community detection~~ | ~~Leiden/Louvain algorithm to discover natural module boundaries vs actual file organization. Reveals which symbols are tightly coupled and whether the directory structure matches. Inspired by axon, GitNexus, CodeGraphMCPServer.~~ | Intelligence | ~~Surfaces architectural drift — when directory structure no longer matches actual dependency clusters; guides refactoring~~ | ✓ | ✓ | 2 | No | — | **DONE** — `codegraph communities` with Louvain algorithm. File-level and `--functions` function-level detection. `--drift` for drift analysis (split/merge candidates). `--resolution` tunable. `communities` MCP tool. PR #133/#134. | +| 21 | ~~Cognitive + cyclomatic complexity~~ | ~~Cognitive Complexity (SonarSource) as the primary readability metric — penalizes nesting, so it subsumes nesting depth analysis. Cyclomatic complexity (McCabe) as secondary testability metric. Both computed from existing tree-sitter AST in a single traversal. Cognitive > 15 or cyclomatic > 10 = flag for refactoring. Extends ID 6 with the two most actionable metrics.~~ | Analysis | ~~Agents can flag hard-to-understand and hard-to-test functions in one pass; cognitive complexity captures both decision complexity and nesting depth in a single score~~ | ✓ | ✓ | 2 | No | — | **DONE** — Subsumed by ID 6. `codegraph complexity` provides both cognitive and cyclomatic metrics (plus nesting depth, Halstead, MI) in a single command. PR #130. | +| 33 | ~~Intraprocedural CFG~~ | ~~Build basic-block control flow graphs from tree-sitter AST for individual functions. Enables complexity-aware impact analysis and opens the path to dataflow (def-use chains). Inspired by Joern, cpg.~~ | Analysis | ~~Agents can visualize control flow through complex functions; enables more precise complexity metrics and future dataflow analysis~~ | ✓ | ✓ | 3 | No | — | **DONE** — `codegraph cfg ` with text/DOT/Mermaid output. Opt-in via `build --cfg`. DB migration v12 adds `cfg_blocks` + `cfg_edges` tables. Handles if/else, for/while/do-while, switch, try/catch/finally, break/continue (with labels), return/throw. Extended to all 11 languages with per-language `CFG_RULES`. `cfg` MCP tool. PR #274, #279, #283. | +| 34 | ~~AST node storage~~ | ~~Persist selected AST nodes (calls, new, string, regex, throw, await) in a queryable table during build. Enables pattern search without re-parsing. Inspired by Joern's CPG stored AST.~~ | Analysis | ~~Agents can search for patterns like "all throw statements" or "all string literals matching /api/" without re-parsing — instant structured queries on the AST~~ | ✓ | ✓ | 3 | No | — | **DONE** — `codegraph ast [pattern]` with `-k` (call, new, string, regex, throw, await), `-f`, `-T` filters. DB migration v13 adds `ast_nodes` table. SQL GLOB with auto-wrapping for substring search. Parent node resolution via narrowest enclosing definition. `ast_query` MCP tool. PR #279. | +| 35 | ~~Expanded node/edge types~~ | ~~Add parameter, property, constant node kinds with parent_id for sub-declaration queries. Add contains, parameter_of, receiver structural edge kinds. Inspired by Joern, cpg.~~ | Analysis | ~~Agents can answer "which functions take a Request param?" or "which classes have a userId field?" without reading source — structural queries on the graph~~ | ✓ | ✓ | 4 | Yes | — | **DONE** — `parameter`, `property`, `constant` node kinds extracted across all 9 WASM extractors. DB migration v11 adds `parent_id` column. `contains` (file→definition, parent→child), `parameter_of` (inverse), `receiver` (method dispatch) edge kinds. `codegraph children ` command. `symbol_children` MCP tool. PR #270, #279. | +| 36 | ~~Exports analysis~~ | ~~Show all exported symbols of a file with per-symbol consumers (who calls each export), re-export detection, and counts.~~ | Analysis | ~~Agents understand a file's public API surface and its consumers in one call — useful for assessing impact of API changes~~ | ✓ | ✓ | 4 | No | — | **DONE** — `codegraph exports ` with re-export detection and consumer counts. `exportsData` programmatic API. `file_exports` MCP tool. PR #269. | +| 37 | ~~Stable JSON schema~~ | ~~normalizeSymbol utility ensuring consistent 7-field output (name, kind, file, line, endLine, role, fileHash) across all query and search commands.~~ | Embeddability | ~~Programmatic consumers and MCP clients get predictable JSON shapes without field-name surprises across different commands~~ | ✓ | ✓ | 3 | No | — | **DONE** — `normalizeSymbol(row, db, hashCache)` used by all query and search functions. `docs/json-schema.md` documents the stable schema. Exported from programmatic API. PR #267. | +| 38 | ~~GraphML / GraphSON / Neo4j CSV export~~ | ~~Add GraphML (XML standard), GraphSON (TinkerPop v3), and Neo4j CSV (bulk import) export formats for graph database interoperability.~~ | Export | ~~Users can load codegraph data into Neo4j, JanusGraph, or any GraphML-compatible tool for advanced visualization and querying~~ | ✓ | ✓ | 2 | No | — | **DONE** — `codegraph export -f graphml|graphson|neo4j` with file-level and function-level modes. Neo4j outputs separate nodes/relationships CSV files. PR #268. | +| 39 | ~~CLI consolidation~~ | ~~Streamline CLI by removing redundant commands: batch-query → batch, hotspots → triage --level, manifesto → check, explain → audit --quick. Reduce MCP tool surface from 32 to 30.~~ | Developer Experience | ~~Fewer commands to learn; each command is more capable; MCP tool surface is smaller and more consistent~~ | ✓ | ✓ | 3 | Yes | — | **DONE** — Removed `batch-query`, `hotspots`, `manifesto`, `explain`, and `query --path`. MCP tools `fn_deps`, `symbol_path`, `list_entry_points` merged into `query` and `execution_flow`. Standalone `path ` added. PR #263, #280. | ### Tier 1b — AST leverage (build on existing `ast_nodes` table) These features leverage the `ast_nodes` table that already exists and is populated during every build. All are zero-dep, non-breaking, and purely additive. -| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | -|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------| -| 40 | Complexity from AST nodes | `complexity.js` currently re-walks the tree-sitter AST to count nesting, branches, operators. Supplement it by querying `ast_nodes` instead — count `throw`/`await` per function via `parent_node_id`, get call counts, derive async complexity scores. Won't replace the full complexity walk but adds cheap signal. | Analysis | Richer complexity metrics without additional parsing cost; `await` density and `throw` frequency are meaningful risk indicators that the current walker doesn't surface | ✓ | ✓ | 3 | No | -| 41 | AST-based lint predicates in `check` | Add configurable `check` predicates like "no `new` of banned classes", "all `await` must be inside try/catch", or "no `throw` of raw strings". Implemented as SQL queries against `ast_nodes` + `cfg_blocks`, not a full linter. | CI | Pattern-based lint rules for CI gates without adding a linter dependency; agents get first-class pass/fail signals for anti-patterns | ✓ | ✓ | 3 | No | -| 42 | AST density in triage risk scoring | Factor AST node density into `triage.js` risk scoring — a function with 15 `await` calls and 3 `throw` statements is objectively riskier than pure synchronous logic. Add `asyncDensity` and `throwCount` as scoring dimensions alongside fan-in, complexity, and churn. | Intelligence | Triage produces more accurate risk rankings; agents prioritize genuinely risky functions over merely complex ones | ✓ | ✓ | 4 | No | -| 43 | Dead code detection via `new` cross-reference | Cross-reference `ast_nodes` `new ClassName()` calls against `nodes` table to find classes that are defined but never instantiated. Extend to string literals matching route patterns or config keys for unused-route / unused-config detection. | Analysis | Catches dead classes that the current role-based dead code detection misses (a class can have zero call edges but still be instantiated via `new`) | ✓ | ✓ | 4 | No | -| 44 | Migration/refactoring pattern queries | Higher-level queries built on `ast_nodes`: "find all `new Promise()` that could be async/await", "find all `throw` of raw strings instead of Error objects", "find all regex patterns" for regex-to-library migration. Expose as `ast` subcommands or `check` predicates. | Refactoring | Agents can identify modernization opportunities and anti-patterns in one query instead of grep + manual classification | ✓ | ✓ | 3 | No | +| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on | +|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------| +| 40 | Complexity from AST nodes | `complexity.js` currently re-walks the tree-sitter AST to count nesting, branches, operators. Supplement it by querying `ast_nodes` instead — count `throw`/`await` per function via `parent_node_id`, get call counts, derive async complexity scores. Won't replace the full complexity walk but adds cheap signal. | Analysis | Richer complexity metrics without additional parsing cost; `await` density and `throw` frequency are meaningful risk indicators that the current walker doesn't surface | ✓ | ✓ | 3 | No | — | +| 41 | AST-based lint predicates in `check` | Add configurable `check` predicates like "no `new` of banned classes", "all `await` must be inside try/catch", or "no `throw` of raw strings". Implemented as SQL queries against `ast_nodes` + `cfg_blocks`, not a full linter. | CI | Pattern-based lint rules for CI gates without adding a linter dependency; agents get first-class pass/fail signals for anti-patterns | ✓ | ✓ | 3 | No | — | +| 42 | AST density in triage risk scoring | Factor AST node density into `triage.js` risk scoring — a function with 15 `await` calls and 3 `throw` statements is objectively riskier than pure synchronous logic. Add `asyncDensity` and `throwCount` as scoring dimensions alongside fan-in, complexity, and churn. | Intelligence | Triage produces more accurate risk rankings; agents prioritize genuinely risky functions over merely complex ones | ✓ | ✓ | 4 | No | — | +| 43 | Dead code detection via `new` cross-reference | Cross-reference `ast_nodes` `new ClassName()` calls against `nodes` table to find classes that are defined but never instantiated. Extend to string literals matching route patterns or config keys for unused-route / unused-config detection. | Analysis | Catches dead classes that the current role-based dead code detection misses (a class can have zero call edges but still be instantiated via `new`) | ✓ | ✓ | 4 | No | — | +| 44 | Migration/refactoring pattern queries | Higher-level queries built on `ast_nodes`: "find all `new Promise()` that could be async/await", "find all `throw` of raw strings instead of Error objects", "find all regex patterns" for regex-to-library migration. Expose as `ast` subcommands or `check` predicates. | Refactoring | Agents can identify modernization opportunities and anti-patterns in one query instead of grep + manual classification | ✓ | ✓ | 3 | No | — | ### Tier 1c — CFG leverage (build on existing `cfg_blocks`/`cfg_edges` tables) CFG is built for every function on every build (~100ms) but only consumed by the `cfg` display command. These features leverage the stored control flow graph data. -| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | -|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------| -| 45 | Cyclomatic complexity from CFG | `complexity.js` re-walks the tree-sitter AST to compute cyclomatic complexity. The CFG already has the data — cyclomatic complexity is literally `edges - nodes + 2` on the stored graph. Replace or supplement the AST walk with a SQL query against `cfg_blocks`/`cfg_edges`. | Analysis | Eliminates redundant AST walking for the most common complexity metric; single source of truth for control flow | ✓ | ✓ | 3 | No | -| 46 | Unreachable block detection in `check` | Query `cfg_blocks` for blocks with zero incoming edges (excluding entry blocks) to detect dead branches and unreachable code paths. Add as a `check` predicate: `--no-unreachable-blocks`. | CI | Catches dead code that static call-graph analysis misses — unreachable branches inside functions, not just unused functions | ✓ | ✓ | 3 | No | -| 47 | CFG summary in `audit` | Include CFG structural summary in `audit` reports: block count, branch count, max path depth, try/catch coverage ratio. Agents get control flow complexity at a glance without running `cfg` separately. | Orchestration | Audit reports become more complete — agents understand control flow complexity alongside dependency and metric data in one call | ✓ | ✓ | 3 | No | -| 48 | CFG metrics in triage risk scoring | Add CFG-derived dimensions to `triage.js`: branch density (edges/blocks), max nesting path length, exception handler ratio. Functions with complex control flow but low cyclomatic complexity (many small branches) get flagged. | Intelligence | Triage catches control-flow-heavy functions that cyclomatic complexity alone underweights | ✓ | ✓ | 3 | No | +| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on | +|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------| +| 45 | Cyclomatic complexity from CFG | `complexity.js` re-walks the tree-sitter AST to compute cyclomatic complexity. The CFG already has the data — cyclomatic complexity is literally `edges - nodes + 2` on the stored graph. Replace or supplement the AST walk with a SQL query against `cfg_blocks`/`cfg_edges`. | Analysis | Eliminates redundant AST walking for the most common complexity metric; single source of truth for control flow | ✓ | ✓ | 3 | No | — | +| 46 | Unreachable block detection in `check` | Query `cfg_blocks` for blocks with zero incoming edges (excluding entry blocks) to detect dead branches and unreachable code paths. Add as a `check` predicate: `--no-unreachable-blocks`. | CI | Catches dead code that static call-graph analysis misses — unreachable branches inside functions, not just unused functions | ✓ | ✓ | 3 | No | — | +| 47 | CFG summary in `audit` | Include CFG structural summary in `audit` reports: block count, branch count, max path depth, try/catch coverage ratio. Agents get control flow complexity at a glance without running `cfg` separately. | Orchestration | Audit reports become more complete — agents understand control flow complexity alongside dependency and metric data in one call | ✓ | ✓ | 3 | No | — | +| 48 | CFG metrics in triage risk scoring | Add CFG-derived dimensions to `triage.js`: branch density (edges/blocks), max nesting path length, exception handler ratio. Functions with complex control flow but low cyclomatic complexity (many small branches) get flagged. | Intelligence | Triage catches control-flow-heavy functions that cyclomatic complexity alone underweights | ✓ | ✓ | 3 | No | — | ### Tier 1d — Dataflow leverage (build on existing `dataflow` table) Dataflow edges (`flows_to`, `returns`, `mutates`) are built on every build (~230ms) but only consumed by the `dataflow` command. These features integrate dataflow into core analysis. -| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | -|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------| -| 49 | Data-dependent impact analysis | `fnImpactData()` only follows `kind='calls'` edges. Add an option (`--include-dataflow`) to also traverse `flows_to`, `returns`, `mutates` edges for data-dependent blast radius. A function's return type changing affects everyone who captures that return value — currently invisible to impact analysis. | Analysis | Impact analysis catches data-flow breakage, not just call-chain breakage — directly prevents the "missed blast radius" problem codegraph exists to solve | ✓ | ✓ | 5 | No | -| 50 | Dataflow fan-out in triage | Functions with high dataflow fan-out (data spreads to many places) are riskier than their call-graph fan-out suggests. Add `dataflowFanOut` as a triage scoring dimension. | Intelligence | Triage surfaces data-spreading functions that call-graph analysis underweights — a function called once but whose return value flows to 15 consumers is high-risk | ✓ | ✓ | 4 | No | -| 51 | Dataflow predicates in `check` | Add `check` predicates for dangerous data flows: "no unvalidated data flows to SQL/eval/exec", "return values from error-prone functions must be checked". Query `dataflow` table joined with `ast_nodes` for pattern matching. | CI | Lightweight taint-like analysis using existing data — catches data flow anti-patterns in CI without a dedicated security scanner | ✓ | ✓ | 3 | No | -| 52 | Dataflow enrichment in `diff-impact` | When a function's signature or return type changes, use `dataflow` edges to identify who captures its return value (`returns` edges) and who passes data to it (`flows_to` edges). Show these as "data-dependent impact" alongside the existing call-dependent impact. | Analysis | `diff-impact` catches breakage from return type changes, parameter changes, and mutation patterns — not just call-chain reachability | ✓ | ✓ | 5 | No | +| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on | +|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------| +| 49 | Data-dependent impact analysis | `fnImpactData()` only follows `kind='calls'` edges. Add an option (`--include-dataflow`) to also traverse `flows_to`, `returns`, `mutates` edges for data-dependent blast radius. A function's return type changing affects everyone who captures that return value — currently invisible to impact analysis. | Analysis | Impact analysis catches data-flow breakage, not just call-chain breakage — directly prevents the "missed blast radius" problem codegraph exists to solve | ✓ | ✓ | 5 | No | — | +| 50 | Dataflow fan-out in triage | Functions with high dataflow fan-out (data spreads to many places) are riskier than their call-graph fan-out suggests. Add `dataflowFanOut` as a triage scoring dimension. | Intelligence | Triage surfaces data-spreading functions that call-graph analysis underweights — a function called once but whose return value flows to 15 consumers is high-risk | ✓ | ✓ | 4 | No | — | +| 51 | Dataflow predicates in `check` | Add `check` predicates for dangerous data flows: "no unvalidated data flows to SQL/eval/exec", "return values from error-prone functions must be checked". Query `dataflow` table joined with `ast_nodes` for pattern matching. | CI | Lightweight taint-like analysis using existing data — catches data flow anti-patterns in CI without a dedicated security scanner | ✓ | ✓ | 3 | No | — | +| 52 | Dataflow enrichment in `diff-impact` | When a function's signature or return type changes, use `dataflow` edges to identify who captures its return value (`returns` edges) and who passes data to it (`flows_to` edges). Show these as "data-dependent impact" alongside the existing call-dependent impact. | Analysis | `diff-impact` catches breakage from return type changes, parameter changes, and mutation patterns — not just call-chain reachability | ✓ | ✓ | 5 | No | — | ### Tier 1e — Co-change leverage (build on existing `co_changes` table) Co-change data captures historical coupling from git history. Currently only used by `co-change` command and a small enrichment in `diff-impact`. -| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | -|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------| -| 53 | Co-change coupling in triage | Files with high co-change Jaccard scores are maintenance risks — changing one always requires changing the other. Add `coChangeCoupling` as a triage scoring dimension using the max Jaccard score for each file. | Intelligence | Triage surfaces tightly coupled file pairs that static dependency analysis may miss — hidden coupling from shared business logic or implicit contracts | ✓ | ✓ | 4 | No | -| 54 | Co-change communities vs dependency communities | Compare Louvain communities from the dependency graph with clusters from co-change data. Files that co-change frequently but live in different dependency communities indicate hidden coupling or architectural drift. | Architecture | Surfaces coupling that the static graph can't see — two modules may have no import relationship but always change together due to shared assumptions | ✓ | ✓ | 3 | No | -| 55 | Missing co-change partner warning in `check` | When `--staged` changes touch file A but not its historical partner file B (high Jaccard), emit a warning: "file A historically co-changes with file B — did you forget to update it?" | CI | Catches incomplete changes in CI — the most common source of subtle bugs is changing one file in a coupled pair but forgetting the other | ✓ | ✓ | 4 | No | +| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on | +|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------| +| 53 | Co-change coupling in triage | Files with high co-change Jaccard scores are maintenance risks — changing one always requires changing the other. Add `coChangeCoupling` as a triage scoring dimension using the max Jaccard score for each file. | Intelligence | Triage surfaces tightly coupled file pairs that static dependency analysis may miss — hidden coupling from shared business logic or implicit contracts | ✓ | ✓ | 4 | No | — | +| 54 | Co-change communities vs dependency communities | Compare Louvain communities from the dependency graph with clusters from co-change data. Files that co-change frequently but live in different dependency communities indicate hidden coupling or architectural drift. | Architecture | Surfaces coupling that the static graph can't see — two modules may have no import relationship but always change together due to shared assumptions | ✓ | ✓ | 3 | No | — | +| 55 | Missing co-change partner warning in `check` | When `--staged` changes touch file A but not its historical partner file B (high Jaccard), emit a warning: "file A historically co-changes with file B — did you forget to update it?" | CI | Catches incomplete changes in CI — the most common source of subtle bugs is changing one file in a coupled pair but forgetting the other | ✓ | ✓ | 4 | No | — | ### Tier 1f — Embeddings leverage (build on existing `embeddings` table) Symbol embeddings and FTS index are populated via `codegraph embed`. Currently only consumed by the `search` command. The vectors and `cosineSim()` function already exist. -| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | -|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------| -| 56 | Find similar functions | New `codegraph similar ` command that loads a function's embedding and scans all others for cosine similarity above a threshold (e.g., 0.85). Surfaces near-duplicates and copy-paste code without syntactic matching. | Analysis | Agents find duplicate logic and refactoring candidates in one query — reduces codebase entropy and catches copy-paste drift | ✓ | ✓ | 3 | No | -| 57 | Similarity clusters in triage | Group functions with high embedding similarity (>0.9) as "duplicate clusters" in triage output. Multiple near-identical functions are a maintenance risk — changing one requires finding and updating all copies. | Intelligence | Triage flags copy-paste debt that no other metric catches — high similarity clusters are refactoring targets | ✓ | ✓ | 3 | No | -| 58 | Similarity warning in `audit` | When auditing a function, check if any other function has >0.85 cosine similarity and include it in the audit report: "this function is 92% similar to X — consider extracting shared logic." | Orchestration | Audit reports surface code duplication without dedicated tools — agents get actionable refactoring suggestions alongside structural analysis | ✓ | ✓ | 2 | No | +| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on | +|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------| +| 56 | Find similar functions | New `codegraph similar ` command that loads a function's embedding and scans all others for cosine similarity above a threshold (e.g., 0.85). Surfaces near-duplicates and copy-paste code without syntactic matching. | Analysis | Agents find duplicate logic and refactoring candidates in one query — reduces codebase entropy and catches copy-paste drift | ✓ | ✓ | 3 | No | — | +| 57 | Similarity clusters in triage | Group functions with high embedding similarity (>0.9) as "duplicate clusters" in triage output. Multiple near-identical functions are a maintenance risk — changing one requires finding and updating all copies. | Intelligence | Triage flags copy-paste debt that no other metric catches — high similarity clusters are refactoring targets | ✓ | ✓ | 3 | No | 56 | +| 58 | Similarity warning in `audit` | When auditing a function, check if any other function has >0.85 cosine similarity and include it in the audit report: "this function is 92% similar to X — consider extracting shared logic." | Orchestration | Audit reports surface code duplication without dedicated tools — agents get actionable refactoring suggestions alongside structural analysis | ✓ | ✓ | 2 | No | 56 | Breaking (penalized to end of tier): -| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | -|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------| -| 14 | ~~Dataflow analysis~~ | ~~Define/use chains and flows_to/returns/mutates edge types. Tracks how data moves through functions, not just call relationships. Major analysis depth increase. Inspired by codegraph-rust.~~ | Analysis | ~~Enables taint-like analysis, more precise impact analysis, and answers "where does this value end up?"~~ | ✓ | ✓ | 5 | Yes | **DONE** — `codegraph dataflow ` with `--impact` mode for transitive data-dependent blast radius. Three edge types: `flows_to` (parameter flows into callee), `returns` (return value captured by caller), `mutates` (parameter-derived value mutated in-place). Opt-in via `build --dataflow` (JS/TS MVP). Schema migration v10 adds `dataflow` table. `dataflow` MCP tool. Handles spread args, optional chaining, reassignment. PR #254. | +| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on | +|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------| +| 14 | ~~Dataflow analysis~~ | ~~Define/use chains and flows_to/returns/mutates edge types. Tracks how data moves through functions, not just call relationships. Major analysis depth increase. Inspired by codegraph-rust.~~ | Analysis | ~~Enables taint-like analysis, more precise impact analysis, and answers "where does this value end up?"~~ | ✓ | ✓ | 5 | Yes | — | **DONE** — `codegraph dataflow ` with `--impact` mode for transitive data-dependent blast radius. Three edge types: `flows_to` (parameter flows into callee), `returns` (return value captured by caller), `mutates` (parameter-derived value mutated in-place). Opt-in via `build --dataflow` (JS/TS MVP). Schema migration v10 adds `dataflow` table. `dataflow` MCP tool. Handles spread args, optional chaining, reassignment. PR #254. | + +### Tier 1g — Visualization leverage (enrich Mermaid/DOT output across all visual tools) + +Six commands already produce Mermaid/DOT output: `export`, `diff-impact -f mermaid`, `branch-compare --format mermaid`, `sequence`, `cfg`, and `plot`. These features enrich the shared visualization pipeline and underlying data model so all visual tools produce richer, PR-ready architectural diagrams. + +| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on | +|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------| +| 59 | Scoped graph rendering (file/diff filter) | Add `--files ` and `--diff ` options to `export` to restrict the Mermaid/DOT graph to a subset of files and their immediate neighbors. `--diff` extracts the file list from `git diff --name-only`. Apply the same scoping to `plot` (interactive HTML viewer) so it can render focused subgraphs. Currently both dump the entire graph — scoping makes them useful for PR review and focused architecture diagrams. | Visualization | Agents and reviewers get a focused dependency diagram for just the files that changed — no noise from the rest of the codebase | ✓ | ✓ | 4 | No | — | +| 60 | Symbol-level edge labels | Persist which specific symbol names flow on each file-to-file edge during `buildGraph` (import resolution already knows the names — store them in a new `edge_symbols` join table or `imported_names` column). Initially consumed by `export`/`plot` Mermaid/DOT edges (show `"re-exports COMPLEXITY_RULES, findFunctionNode"` instead of just `"imports"`). | Analysis | Foundational data model change — all downstream visual and dependency tools can show *what* flows between files, not just *that* something flows | ✓ | ✓ | 5 | No | — | +| 61 | Node export annotations | Add an option to embed a file's top exported symbols into Mermaid/DOT node labels (e.g., `shared.js · makeRules / makeCfgRules / buildExtToLangMap`). Data already exists via `file-exports` / `list-functions` — just needs wiring into the shared Mermaid formatter. | Visualization | Nodes communicate their API surface inline — reviewers immediately see what each file provides without drilling down | ✓ | ✓ | 3 | No | — | +| 62 | Semantic subgraph labels | Allow directory subgraphs in Mermaid/DOT output to carry contextual annotations: diff-aware labels (`**(unchanged)**` / `**(modified)**` / `**(new)**`), user-supplied labels via `.codegraphrc.json` `export.subgraphLabels` map. | Visualization | Diagrams communicate change context directly in the layout — reviewers see which module groups were affected without cross-referencing the diff | ✓ | ✓ | 3 | No | 59 | +| 63 | Scoped diagram in `audit --diagram` | Reuse 59's scoped export pipeline to embed a mini focused Mermaid flowchart in `audit` output showing the target's immediate dependency neighborhood. | Orchestration | Agents get structural context + visual diagram in one call — reduces round-trips between `audit` and `export` | ✓ | ✓ | 4 | No | 59 | +| 64 | Scoped diagram in `context --diagram` | Reuse 59's scoped export pipeline to embed a mini focused Mermaid flowchart in `context` output showing the target's file neighborhood. | Orchestration | Context queries gain optional visual output without a separate `export` call | ✓ | ✓ | 3 | No | 59 | +| 65 | Symbol-level labels in `diff-impact -f mermaid` | Use 60's `edge_symbols` data to label blast-radius edges with the specific exports affected. | Visualization | `diff-impact` diagrams show which symbols are at risk, not just which files | ✓ | ✓ | 5 | No | 60 | +| 66 | Symbol-level labels in `branch-compare --format mermaid` | Use 60's `edge_symbols` data to label structural diff edges with which symbols were added/removed on each file-to-file edge. | Visualization | Branch comparison diagrams show the specific API surface changes between branches | ✓ | ✓ | 4 | No | 60 | +| 67 | Symbol-level imports in `deps` output | Use 60's `edge_symbols` data so `file-deps` lists the specific symbols imported from each file, not just the file name. | Analysis | `deps` becomes a full import manifest — agents know exactly which names flow on each edge | ✓ | ✓ | 4 | No | 60 | +| 68 | Symbol-level messages in `sequence` | Use 60's `edge_symbols` data to label sequence diagram messages with the specific exports being called between participants. | Visualization | Sequence diagrams show which symbols drive each file-to-file interaction | ✓ | ✓ | 3 | No | 60 | +| 69 | Node annotations in `diff-impact` / `branch-compare` / `communities` | Use 61's annotation formatter to show top exports on file nodes in `diff-impact -f mermaid`, `branch-compare --format mermaid`, and `communities` output. | Visualization | All visual tools show file API surfaces inline, not just in `export` | ✓ | ✓ | 3 | No | 61 | +| 70 | Drift/risk subgraph labels in `communities` and `triage` | Use 62's semantic label system to annotate `communities` subgraphs with drift status (`**(drifted)**` / `**(cohesive)**`) and add a new `--format mermaid` to `triage` with risk-severity group labels. | Intelligence | Community and triage diagrams communicate structural health directly in the layout | ✓ | ✓ | 3 | No | 62 | ### Tier 2 — Foundation-aligned, needs dependencies Ordered by problem-fit: -| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | -|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------| -| 3 | Token counting on responses | Add tiktoken-based token counts to CLI and MCP responses so agents know how much context budget each query consumed. Inspired by glimpse, arbor. | Developer Experience | Agents and users can budget context windows; enables smarter multi-query strategies without blowing context limits | ✗ | ✓ | 3 | No | -| 8 | Optional LLM provider integration | Bring-your-own provider (OpenAI, Anthropic, Ollama, etc.) for richer embeddings and AI-powered search. Enhancement layer only — core graph never depends on it. Inspired by code-graph-rag, autodev-codebase. | Search | Semantic search quality jumps significantly with provider embeddings; users who already pay for an LLM get better results at no extra cost | ✗ | ✓ | 3 | No | +| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on | +|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------| +| 3 | Token counting on responses | Add tiktoken-based token counts to CLI and MCP responses so agents know how much context budget each query consumed. Inspired by glimpse, arbor. | Developer Experience | Agents and users can budget context windows; enables smarter multi-query strategies without blowing context limits | ✗ | ✓ | 3 | No | — | +| 8 | Optional LLM provider integration | Bring-your-own provider (OpenAI, Anthropic, Ollama, etc.) for richer embeddings and AI-powered search. Enhancement layer only — core graph never depends on it. Inspired by code-graph-rag, autodev-codebase. | Search | Semantic search quality jumps significantly with provider embeddings; users who already pay for an LLM get better results at no extra cost | ✗ | ✓ | 3 | No | — | ### Tier 3 — Not foundation-aligned (needs deliberate exception) Ordered by problem-fit: -| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | -|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------| -| 19 | Auto-generated context files | Generate structural summaries (AGENTS.md, CLAUDE.md sections) from the graph — module descriptions, key entry points, architecture overview. Inspired by GitNexus. | Intelligence | New contributors and AI agents get an always-current project overview without manual documentation effort | ✓ | ✗ | 3 | No | -| 17 | Multi-file coordinated rename | Rename a symbol across all call sites, validated against the graph structure. Inspired by GitNexus. | Refactoring | Safe renames without relying on LSP or IDE — works in CI, agent loops, and headless environments | ✓ | ✗ | 3 | No | -| 7 | OWASP/CWE pattern detection | Security pattern scanning on the existing AST — hardcoded secrets, SQL injection patterns, eval usage, XSS sinks. Lightweight static rules, not full taint analysis. Inspired by narsil-mcp, CKB. | Security | Catches low-hanging security issues during `diff-impact`; agents can flag risky patterns before they're committed | ✓ | ✗ | 1 | No | -| 10 | ~~Interactive HTML visualization~~ | ~~`codegraph viz` opens an interactive force-directed graph in the browser (vis.js or Cytoscape.js). Zoom, pan, filter by module, click to inspect. Inspired by autodev-codebase, CodeVisualizer.~~ | Visualization | ~~Developers and teams can visually explore architecture; useful for onboarding, code reviews, and spotting structural problems~~ | ✗ | ✗ | 1 | No | **DONE** — `codegraph plot` generates an interactive HTML viewer powered by vis-network. Hierarchical, force, and radial layouts with physics toggle. Node coloring by kind or role, search/filter, legend panel. Drill-down, clustering, complexity overlays, and detail panel. Configurable via `.plotDotCfg` JSON file. Also added GraphML, GraphSON, and Neo4j CSV export formats. PR #268. | +| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on | +|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------| +| 19 | Auto-generated context files | Generate structural summaries (AGENTS.md, CLAUDE.md sections) from the graph — module descriptions, key entry points, architecture overview. Inspired by GitNexus. | Intelligence | New contributors and AI agents get an always-current project overview without manual documentation effort | ✓ | ✗ | 3 | No | — | +| 17 | Multi-file coordinated rename | Rename a symbol across all call sites, validated against the graph structure. Inspired by GitNexus. | Refactoring | Safe renames without relying on LSP or IDE — works in CI, agent loops, and headless environments | ✓ | ✗ | 3 | No | — | +| 7 | OWASP/CWE pattern detection | Security pattern scanning on the existing AST — hardcoded secrets, SQL injection patterns, eval usage, XSS sinks. Lightweight static rules, not full taint analysis. Inspired by narsil-mcp, CKB. | Security | Catches low-hanging security issues during `diff-impact`; agents can flag risky patterns before they're committed | ✓ | ✗ | 1 | No | — | +| 10 | ~~Interactive HTML visualization~~ | ~~`codegraph viz` opens an interactive force-directed graph in the browser (vis.js or Cytoscape.js). Zoom, pan, filter by module, click to inspect. Inspired by autodev-codebase, CodeVisualizer.~~ | Visualization | ~~Developers and teams can visually explore architecture; useful for onboarding, code reviews, and spotting structural problems~~ | ✗ | ✗ | 1 | No | — | **DONE** — `codegraph plot` generates an interactive HTML viewer powered by vis-network. Hierarchical, force, and radial layouts with physics toggle. Node coloring by kind or role, search/filter, legend panel. Drill-down, clustering, complexity overlays, and detail panel. Configurable via `.plotDotCfg` JSON file. Also added GraphML, GraphSON, and Neo4j CSV export formats. PR #268. | ---