# Codegraph Feature Backlog

**Last updated:** 2026-05-01
**Source:** Features derived from [COMPETITIVE_ANALYSIS.md](../../generated/competitive/COMPETITIVE_ANALYSIS.md) and internal roadmap discussions.

---

## How to Read This Backlog

Each item has a short title, description, category, expected benefit, and four assessment columns left blank for prioritization review:

| Column | Meaning |
|--------|---------|
| **Zero-dep** | Can this feature be implemented without adding new runtime dependencies to the project? A checkmark means it builds entirely on what we already ship (tree-sitter, SQLite, existing AST). Blank means it needs evaluation. Features that require new deps raise the install footprint and maintenance burden — they need stronger justification. |
| **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. |

---

## Backlog

### Tier 0 — Promote before Phase 4-5 (highest immediate impact)

Both items are now **DONE**. These directly improved agent experience and graph accuracy without requiring Rust porting or TypeScript migration.

**Rationale:** Item #83 enriches the *passively-injected* context that agents actually see via hooks — the single highest-leverage surface for reducing blind edits. Item #71 closed the biggest accuracy gap in the graph for TypeScript and Java, where missing type-aware resolution caused hallucinated "no callers" results.

| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on |
|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------|
| 83 | ~~Hook-optimized `codegraph brief` command~~ | ~~New `codegraph brief <file>` command designed for Claude Code hook context injection. Returns a compact, token-efficient summary per file: each symbol with its role and caller count (e.g. `buildGraph [core, 12 callers]`), blast radius count on importers (`Imported by: src/cli.js (+8 transitive)`), and overall file risk tier. Current `deps --json` output used by `enrich-context.sh` is shallow — just file-level imports/importedBy and symbol names with no role or blast radius info. The `brief` command would include: **(a)** symbol roles in the output — knowing a file defines `core` vs `leaf` symbols changes editing caution; **(b)** per-symbol transitive caller counts — makes blast radius visible without a separate `fn-impact` call; **(c)** file-level risk tier (high/medium/low based on max fan-in and role composition). Output optimized for `additionalContext` injection — single compact block, not verbose JSON. Also add `--brief` flag to `deps` as an alias.~~ | Embeddability | ~~The `enrich-context.sh` hook is the only codegraph context agents actually see (they ignore CLAUDE.md instructions to run commands manually). Making that passively-injected context richer — with roles, caller counts, and risk tiers — directly reduces blind edits to high-impact code. Currently the hook shows `Defines: function buildGraph` but not that it's a core symbol with 12 transitive callers~~ | ✓ | ✓ | 4 | No | — | **DONE** — `codegraph brief <file>` command with symbol roles, caller counts, and risk tiers. CLI command, MCP tool, and presentation layer. ([#480](https://github.com/optave/ops-codegraph-tool/pull/480)) |
| 71 | ~~Basic type inference for typed languages~~ | ~~Extract type annotations from TypeScript and Java AST nodes (variable declarations, function parameters, return types, generics) to resolve method calls through typed references. Currently `const x: Router = express.Router(); x.get(...)` produces no edge because `x.get` can't be resolved without knowing `x` is a `Router`. Tree-sitter already parses type annotations — we just don't use them for resolution. Start with declared types (no flow inference), which covers the majority of TS/Java code.~~ | Resolution | ~~Dramatically improves call graph completeness for TypeScript and Java — the two languages where developers annotate types explicitly and expect tooling to use them. Directly prevents hallucinated "no callers" results for methods called through typed variables~~ | ✓ | ✓ | 5 | No | — | **DONE** — Type inference for all typed languages (TS, Java, Go, Rust, C#, PHP, Python). WASM + native engines. ([#501](https://github.com/optave/ops-codegraph-tool/pull/501)) |

### Tier 1 — Zero-dep + Foundation-aligned (build these first)

Non-breaking, ordered by problem-fit:

| 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 <from> <to>` 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 <base> <target>` 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 <file-or-function>` 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 <file-or-function>` 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 <targets...>` 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 <name>` / `codegraph snapshot restore <name>` 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 <name>` 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 <name>` 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 <file>` 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 <from> <to>` 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 | 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 | — | **DONE** — Class instantiation via `new` is now tracked as consumption in dead code detection. Also: type-only imports, barrel re-exports, and same-file constants now correctly tracked. ([#861](https://github.com/optave/ops-codegraph-tool/pull/861), [#862](https://github.com/optave/ops-codegraph-tool/pull/862), [#860](https://github.com/optave/ops-codegraph-tool/pull/860), [#859](https://github.com/optave/ops-codegraph-tool/pull/859)) |
| 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 | — |
| 85 | Hot-path expensive-initialization detection | Cross-reference `ast_nodes` call expressions (e.g. `db.prepare(...)`, `new RegExp(...)`, `JSON.parse(...)`, `fs.readFileSync(...)`) with graph fan-in to flag functions that compile/allocate expensive objects on every invocation. A function containing `db.prepare()` with fan-in > N is almost certainly a performance bug — the statement should be prepared once and cached. Query: find `call` AST nodes matching a configurable pattern list inside functions whose `fan_in` exceeds a threshold; surface as a `check` predicate (`--no-hot-path-alloc`) and in `triage` risk scoring. The pattern list should be user-configurable via `.codegraphrc.json` `check.hotPathPatterns` so it works beyond SQLite (Redis clients, HTTP agents, compiled regexes). | Performance | Catches a class of performance regression that no complexity metric surfaces — a function can have low cyclomatic complexity and still be a hot allocation source. Directly prevents the "missed blast radius" problem: changing a helper that was accidentally called N×/request has outsized perf impact invisible to call-graph analysis alone | ✓ | ✓ | 4 | 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 | 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 | — | **DONE** — Cyclomatic complexity now derived from CFG structure (`E - N + 2`) as part of the unified AST analysis framework. CFG visitor rewrite in PR #392. |
| 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 | 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 | 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 Leiden 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 | #545 |
| 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 1e.1 — Community leverage (build on vendored Leiden algorithm)

Community detection now uses a vendored Leiden optimiser (PRs #545, #552, #556) with full control over resolution, quality functions, and true probabilistic refinement (Algorithm 3). The `graphology` dependency has been removed. Items in this tier are now **unblocked**.

| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on |
|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------|
| 100 | Weighted community labels | Auto-generate a human-readable label for each community from its member files and symbols. Heuristics: most common directory prefix, dominant symbol kinds, shared naming patterns (e.g., "parsing pipeline", "CLI presentation", "graph algorithms"). Store labels in `communities` output and `graph-enrichment.js`. Expose as `--labels` flag on `communities` command. | Intelligence | Raw community IDs (0, 1, 2…) are meaningless to agents and humans. Labels like "database layer" or "test utilities" make community output immediately actionable — agents can reference architectural groups by name instead of number | ✓ | ✓ | 3 | No | #545 |
| 101 | Hierarchical community decomposition | Run Leiden at multiple resolution levels (e.g., γ=0.5, 1.0, 2.0) and expose nested community structure — macro-clusters containing sub-clusters. The vendored optimiser already computes multi-level coarsening internally; surface it as `communities --hierarchical` with a tree output showing which fine-grained communities nest inside coarse ones. Store hierarchy in a `community_hierarchy` table or JSON metadata. | Architecture | Single-resolution communities force a choice between broad architectural groups and tight cohesion clusters. Hierarchical decomposition gives both — agents can zoom from "this is the graph subsystem" to "specifically the Leiden algorithm cluster within it" without re-running at different resolutions | ✓ | ✓ | 3 | No | #545 |
| 102 | Community-aware impact scoring | Factor community boundaries into `fn-impact` and `diff-impact` risk scoring. Changes that cross community boundaries are architecturally riskier than changes within a single community — they indicate coupling between modules that should be independent. Add `crossCommunityCount` to impact output and weight it in triage risk scoring. A function with blast radius 5 all within one community is lower risk than blast radius 5 spanning 4 communities. | Analysis | Directly improves blast radius accuracy — the core problem codegraph exists to solve. Community-crossing impact is a strong signal for architectural coupling that raw call-chain fan-out doesn't capture | ✓ | ✓ | 4 | No | #545 |


### 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 | Depends on |
|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------|
| 56 | Find similar functions | New `codegraph similar <name>` 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 | 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 <name>` 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 <glob>` and `--diff <ref>` 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 |
| 84 | Call-count annotations on `sequence` diagram arrows | `sequence` currently deduplicates caller→callee pairs with `SELECT DISTINCT`, silently hiding multi-site calls. Instead, count how many times each caller→callee pair appears in the edges table and annotate the Mermaid arrow with the count when > 1 (e.g., `CallerFile ->> CalleeFile: fnName (×3)`). Requires grouping by `(source_id, target_id)` and emitting the count alongside the edge. | Visualization | Sequence diagrams reveal call intensity — a file calling another 8 times is architecturally different from one that calls it once; agents and reviewers can immediately spot hot paths and coupling strength | ✓ | ✓ | 3 | No | — |
| 103 | Recursively foldable graph viewer | Add directory-level collapsing to the interactive HTML viewer (`codegraph plot`). Any directory group collapses into a single node showing only its external edges (imports in/out); click to expand into constituent symbols. Recursive: collapsed groups contain collapsed sub-groups. Inspired by Weft's "recursively foldable" design — a 100-node system still looks like 5 blocks at the top level. Implementation: extend `graph-enrichment.ts` to compute directory-level aggregate edges, extend `viewer.ts` to support expand/collapse toggling on `subgraph` cluster nodes (vis-network supports compound nodes via `clustering`). Add `--collapsed` flag to start fully collapsed, `--expand-depth N` to control initial expansion level. | Visualization | Large codebase graphs are currently unusable — hundreds of nodes render as spaghetti. Directory-level collapsing makes `codegraph plot` viable for real projects by letting users zoom from architecture overview to file-level detail interactively. Directly improves the "orientation" problem — agents and humans see module boundaries at a glance | ✓ | ✓ | 4 | No | — |
| 86 | Mermaid `classDiagram` export | New `codegraph export -f class-diagram` (and `exportClassDiagram` programmatic API) that emits a Mermaid `classDiagram` for classes, interfaces, structs, traits, and enums in the graph. **What we already have:** class/interface/struct/trait/enum nodes in the `nodes` table, method nodes with `parent_id` linking them to their class (migration v11), property/parameter/constant child nodes via `symbol_children`, `extends` and `implements` edges stored by `builder.js`. **What's needed:** **(a)** New rendering function in `export.js` that queries classes → groups their child methods and properties → emits Mermaid `classDiagram` syntax with `<<abstract>>`/`<<interface>>` stereotypes, inheritance (`<\|--`) and implementation (`..\|>`) arrows; **(b)** visibility markers (`+`/`-`/`#`) — infer from JS `#private` fields (already detected as `private_property_identifier` in `extractClassProperties`) and language-specific access modifiers; **(c)** optional `--scope <file-or-class>` to restrict diagram to a class and its hierarchy (uses `getClassHierarchy` BFS); **(d)** dependency arrows (`..>`) derived from cross-class call edges. **Nice-to-have (not blocking):** type annotations on methods/fields (requires extractor changes to persist TS/Java type info). Add corresponding `class_diagram` MCP tool. | Visualization | Agents and PR reviewers get UML-style class hierarchy diagrams generated directly from the graph — useful for understanding inheritance structures, spotting god classes, and reviewing OOP designs without manual diagramming. Particularly valuable for Java, C#, TypeScript, and Rust codebases with deep type hierarchies | ✓ | ✓ | 3 | No | — |

### Tier 1h — Core accuracy improvements (resolve known analysis gaps)

These address fundamental limitations in the parsing and resolution pipeline that reduce graph accuracy for real-world codebases. All are zero-dep (tree-sitter AST + existing resolution infrastructure), non-breaking (purely additive — more edges, better resolution), and high problem-fit (directly prevent hallucinated or missing dependencies).

| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on |
|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------|
| 72 | Interprocedural dataflow analysis | Extend the existing intraprocedural dataflow (ID 14) to propagate `flows_to`/`returns`/`mutates` edges across function boundaries. When function A calls B with argument X, and B's dataflow shows X flows to its return value, connect A's call site to the downstream consumers of B's return. Requires stitching per-function dataflow summaries at call edges — no new parsing, just graph traversal over existing `dataflow` + `edges` tables. Start with single-level propagation (caller↔callee), not transitive closure. | Analysis | Current dataflow stops at function boundaries, missing the most important flows — data passing through helper functions, middleware chains, and factory patterns. Single-function scope means `dataflow` can't answer "where does this user input end up?" across call boundaries. Cross-function propagation is the difference between toy dataflow and useful taint-like analysis | ✓ | ✓ | 5 | No | 14 |
| 73 | ~~Improved dynamic call resolution~~ | ~~Upgrade the current "best-effort" dynamic dispatch resolution for Python, Ruby, and JavaScript. Three concrete improvements: **(a)** receiver-type tracking — when `x = SomeClass()` is followed by `x.method()`, resolve `method` to `SomeClass.method` using the assignment chain (leverages existing `ast_nodes` + `dataflow` tables); **(b)** common pattern recognition — resolve `EventEmitter.on('event', handler)` callback registration, `Promise.then/catch` chains, `Array.map/filter/reduce` with named function arguments, and decorator/annotation patterns; **(c)** confidence-tiered edges — mark dynamically-resolved edges with a confidence score (high for direct assignment, medium for pattern match, low for heuristic) so consumers can filter by reliability.~~ | Resolution | ~~In Python/Ruby/JS, 30-60% of real calls go through dynamic dispatch — method calls on variables, callbacks, event handlers, higher-order functions. The current best-effort resolution misses most of these, leaving massive gaps in the call graph for the languages where codegraph is most commonly used. Even partial improvement here has outsized impact on graph completeness~~ | ✓ | ✓ | 5 | No | — | **PROMOTED** — Moved to ROADMAP Phase 4.2 (Receiver Type Tracking for Method Dispatch) |
| 81 | Track dynamic `import()` and re-exports as graph edges | Extract `import()` expressions as `dynamic-imports` edges in both WASM extraction paths (query-based and walk-based). Destructured names (`const { a } = await import(...)`) feed into `importedNames` for call resolution. **Partially done:** WASM JS/TS extraction works (PR #389). Remaining: **(a)** native Rust engine support — `crates/codegraph-core/src/extractors/javascript.rs` doesn't extract `import()` calls; **(b)** non-static paths (`import(\`./plugins/${name}.js\`)`, `import(variable)`) are skipped with a debug warning; **(c)** re-export consumer counting in `exports --unused` only checks `calls` edges, not `imports`/`dynamic-imports` — symbols consumed only via import edges show as zero-consumer false positives. | Resolution | Fixes false "zero consumers" reports for symbols consumed via dynamic imports. 95 `dynamic-imports` edges found in codegraph's own codebase — these were previously invisible to impact analysis, exports audit, and dead-export hooks | ✓ | ✓ | 5 | No | — |
| 82 | Extract names from `import().then()` callback patterns | `extractDynamicImportNames` only extracts destructured names from `const { a } = await import(...)` (walks up to `variable_declarator`). The `.then()` pattern — `import('./foo.js').then(({ a, b }) => ...)` — produces an edge with empty names because the destructured parameters live in the `.then()` callback, not a `variable_declarator`. Detect when an `import()` call's parent is a `member_expression` with `.then`, find the arrow/function callback in `.then()`'s arguments, and extract parameter names from its destructuring pattern. | Resolution | `.then()`-style dynamic imports are common in older codebases and lazy-loading patterns (React.lazy, Webpack code splitting). Without name extraction, these produce file-level edges only — no symbol-level `calls` edges, so the imported symbols still appear as zero-consumer false positives | ✓ | ✓ | 4 | No | 81 |

### Tier 1i — Search, navigation, and monitoring improvements

These close gaps in search expressiveness, cross-repo navigation, implementation tracking, and proactive monitoring. All are zero-dep and foundation-aligned.

| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on |
|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------|
| 74 | ~~Interface and trait implementation tracking~~ | ~~Extract `implements`/`extends`/trait-impl relationships from tree-sitter AST and store as `implements` edges in the graph. New `codegraph implementations <interface>` command returns all concrete types that implement a given interface, abstract class, or trait. Inverse: `codegraph interfaces <class>` returns what a type implements. Cross-reference with existing `contains` edges for full type hierarchy. Covers TypeScript interfaces, Java interfaces/abstract classes, Go interfaces (structural matching via method set comparison), Rust traits, C# interfaces, PHP interfaces.~~ | Navigation | ~~Agents can answer "who implements this interface?" and "what contract does this type satisfy?" in one call — currently impossible without reading every file. Directly prevents missed blast radius when an interface signature changes, since all implementors are affected but invisible to the current call-graph-only impact analysis~~ | ✓ | ✓ | 5 | No | — | **PROMOTED** — Moved to ROADMAP Phase 4.3 (Interface and Trait Implementation Tracking) |
| 75 | Diff and commit content search | Search within git diffs and commit messages using the existing graph's file/symbol awareness. `codegraph search-history "pattern" --since 30d` searches `git log -p` output, returning matches with commit SHA, author, date, file, and enclosing function (resolved via line-number intersection with `nodes` table). Supports `--author`, `--file`, `--kind` filters to scope by symbol type. Unlike `co-change` (which tracks statistical co-occurrence), this searches actual diff content — "find every commit that modified the `authenticate` function" or "find when `TODO: hack` was introduced." | Search | Agents can trace when and why a function changed without leaving the graph — answers "who introduced this bug?" and "what changed in this module last month?" in one query. Eliminates manual `git log -p` + grep workflows that burn tokens on raw diff output | ✓ | ✓ | 4 | No | — |
| 76 | Regression watchers (query-based commit monitors) | Define persistent watch rules that evaluate graph queries against each new commit during `build --watch` or incremental rebuild. Rules are declared in `.codegraphrc.json` under `monitors[]` — each rule has a name, a query type (`check` predicate, `search` pattern, `ast` pattern, or custom SQL), and an action (`warn`, `fail`, or `webhook`). Examples: "alert when a new call to `deprecatedAPI()` appears in a diff", "fail when a new `eval()` AST node is added", "warn when fan-in of any function exceeds 20 after this commit." Results surfaced in CLI output during watch mode and as a `monitors` section in `diff-impact`. | CI | Proactive detection of regressions as they happen — agents and CI pipelines get immediate feedback when a commit introduces banned patterns, exceeds thresholds, or violates architectural rules. Shifts detection left from periodic audits to per-commit triggers | ✓ | ✓ | 4 | No | — |
| 77 | Metric trend tracking (code insights) | `codegraph trends` computes key graph metrics (total symbols, avg complexity, dead code count, cycle count, community drift score, boundary violations) at historical git revisions and outputs a time-series table or JSON. Uses `git stash && git checkout <rev> && build && collect && restore` loop over sampled commits (configurable `--samples N` defaulting to 10 evenly-spaced commits). Stores results in a `metric_snapshots` table for incremental updates. `--since` and `--until` for date range. `--metric` to select specific metrics. Enables tracking migration progress ("how many files still use old API?"), tech debt trends, and codebase growth over time without external dashboards. | Intelligence | Agents and teams can answer "is our codebase getting healthier or worse?" with data instead of intuition — tracks complexity trends, dead code accumulation, architectural drift, and migration progress over time. Historical backfill from git history means instant visibility into months of trends | ✓ | ✓ | 3 | No | — |
| 78 | Cross-repo symbol resolution | In multi-repo mode, resolve import edges that cross repository boundaries. When repo A imports `@org/shared-lib`, and repo B is `@org/shared-lib` in the registry, create cross-repo edges linking A's import to B's actual exported symbol. Requires matching npm/pip/go package names to registered repos. Store cross-repo edges with a `repo` qualifier in the `edges` table. Enables cross-repo `fn-impact` (changing a shared library function shows impact across all consuming repos), cross-repo `path` queries, and cross-repo `diff-impact`. | Navigation | Multi-repo mode currently treats each repo as isolated — agents can search across repos but can't trace dependencies between them. Cross-repo edges enable "if I change this shared utility, which downstream repos break?" — the highest-value question in monorepo and multi-repo architectures | ✓ | ✓ | 5 | No | — |
| 79 | Advanced query language with boolean operators and output shaping | Extend `codegraph search` and `codegraph where` with a structured query syntax supporting: **(a)** boolean operators — `kind:function AND file:src/` , `name:parse OR name:extract`, `NOT kind:class`; **(b)** compound filters — `kind:method AND complexity.cognitive>15 AND role:core`; **(c)** output shaping — `--select symbols` (just names), `--select files` (distinct files), `--select owners` (CODEOWNERS for matches), `--select stats` (aggregate counts by kind/file/role); **(d)** result aggregation — `--group-by file`, `--group-by kind`, `--group-by community` with counts. Parse the query into a SQL WHERE clause against the `nodes`/`function_complexity`/`edges` tables. Expose as `query_language` MCP tool parameter. | Search | Current search is either keyword/semantic (fuzzy) or exact-name (`where`). Agents needing "all core functions with cognitive complexity > 15 in src/api/" must chain multiple commands and filter manually — wasting tokens on intermediate results. A structured query language answers compound questions in one call | ✓ | ✓ | 4 | No | — |
| 97 | Unified multi-repo graph | New `codegraph build --repos <path1> <path2> ...` (or `.codegraphrc.json` `repos[]` list) that builds a single unified graph spanning multiple repositories. Each repo is parsed independently, then a merge step stitches them into one SQLite DB with repo-qualified file paths (`repo:path`). Three connection modes: **(a)** npm/pip/go package imports — repo A imports `@org/lib` which is repo B, resolved via `package.json`/`setup.py`/`go.mod` name matching; **(b)** API boundary inference — repo A calls `fetch('/api/users')` and repo B defines an Express/Flask/Gin route for `/api/users`, linked as a `cross-repo-api` edge with lower confidence; **(c)** shared schema/proto — repos sharing `.proto`, OpenAPI, or GraphQL schema files get edges through the shared contract types. All existing query commands (`fn-impact`, `diff-impact`, `path`, `audit`, `triage`, `exports`) work transparently on the unified graph — changing a shared library function shows impact across all consuming repos in one query. Requires a `repos` registry mapping package names to local paths (extend existing `~/.codegraph/registry.json`). Store a `repo` column on `nodes` and `edges` tables to partition ownership. | Navigation | Current multi-repo mode (`--multi-repo`) keeps each repo's graph isolated — you can search across repos but can't trace how a change in one repo impacts another. Real-world systems span multiple repos connected by package imports, API integrations, or shared schemas. A unified graph answers "if I change this endpoint handler, which frontend components break?" or "if I update this shared utility, which downstream services are affected?" — the highest-value cross-cutting questions that currently require manual tracing across repo boundaries | ✓ | ✓ | 5 | Yes | 78 |
| 80 | ~~Find implementations in impact analysis~~ | ~~When a function signature or interface definition changes, automatically include all implementations/subtypes in `fn-impact` and `diff-impact` blast radius. Currently impact only follows `calls` edges — changing an interface method signature breaks every implementor, but this is invisible. Requires ID 74's `implements` edges. Add `--include-implementations` flag (on by default) to impact commands.~~ | Analysis | ~~Catches the most dangerous class of missed blast radius — interface/trait changes that silently break all implementors. A single method signature change on a widely-implemented interface can break dozens of files, none of which appear in the current call-graph-only impact analysis~~ | ✓ | ✓ | 5 | No | 74 | **PROMOTED** — Folded into ROADMAP Phase 4.3 (`--include-implementations` flag on impact commands) |

### Tier 1j — Audit-identified gaps (from Architecture Audit v3.1.4)

Items identified by the architectural audit (v3.1.4) that don't fit existing tiers. Most are zero-dep and foundation-aligned (see individual rows for exceptions).

| ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on |
|----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------|
| 87 | ~~Confidence annotations on query output~~ | ~~Every query output should include resolution statistics: `{ resolved: N, unresolved_method_calls: M, confidence: 0.XX }`. When `fn-impact` shows a blast radius of 5 functions, it should note how many method-dispatch calls may be missing. CLI displays as a footer line; MCP tools include in JSON. Makes the tool honest about its known blind spots instead of presenting precise-looking numbers without qualification.~~ | Embeddability | ~~Agents and users can assess how much to trust a result — a blast radius of 5 with 82% confidence is actionable, while 5 with 40% confidence means "run more analysis". Directly prevents the "missed blast radius" problem by making the gap visible~~ | ✓ | ✓ | 5 | No | — | **PROMOTED** — Moved to ROADMAP Phase 7.10 |
| 88 | SCIP/LSP integration for top languages | Use compiler-grade symbol indices from TypeScript (tsc/tsserver), Python (Pyright), Go (gopls), and Rust (rust-analyzer) for import resolution and call graph construction. These tools export SCIP or LSP-compatible symbol tables that give 100% precision on resolved symbols — at near-zero implementation cost compared to building custom type inference. Current heuristic resolution becomes the fallback for languages without SCIP support. | Resolution | The single highest-value accuracy improvement available. Compiler-backed resolution eliminates the entire class of method-dispatch, overload, and type-narrowing resolution failures for the 4 most popular typed languages. Transforms codegraph from "~75% accurate heuristic" to "~99% accurate for TS/Py/Go/Rust, ~75% for the rest" | ✓ | ✓ | 5 | No | — |
| 89 | ~~Call resolution precision/recall benchmark suite~~ | ~~Hand-annotated fixture projects per language with `expected-edges.json` manifests declaring the correct call edges. Benchmark runner compares codegraph's resolved edges against expected, reports precision (correct / total resolved) and recall (correct / total expected). CI gate fails if metrics drop below baseline. Without this, there's no way to know if a change improves or degrades call graph quality. CodeScene publishes precision metrics; Sourcegraph SCIP indexers have per-language benchmarks; codegraph has none.~~ | Testing | ~~The only way to measure whether resolution changes actually improve accuracy — without it, "improvements" might silently break other resolution paths. Also provides regression protection as new languages and resolution modes are added~~ | ✓ | ✓ | 5 | No | — | **PROMOTED** — Moved to ROADMAP Phase 4.4 |
| 90 | ~~`package.json` `exports` field resolution~~ | ~~Modern Node.js standard since v12. Import resolution currently uses brute-force filesystem probing (tries 10+ extensions via `fs.existsSync()`). It doesn't read `package.json` `exports` field, meaning conditional exports, subpath patterns, and package self-references are invisible. Support subpath patterns, conditional exports (`"import"`, `"require"`, `"default"`), and fall back to filesystem probing only when `exports` is absent.~~ | Resolution | ~~Fixes resolution failures for any project using modern Node.js package conventions — which is most projects published since 2020. Currently produces low-confidence heuristic matches for imports that should resolve deterministically~~ | ✓ | ✓ | 4 | No | — | **PROMOTED** — Moved to ROADMAP Phase 4.5 |
| 91 | ~~Monorepo workspace resolution~~ | ~~`pnpm-workspace.yaml`, npm workspaces (`package.json` `workspaces`), and `lerna.json` are not recognized. Internal package imports (`@myorg/utils`) fall through to global resolution with low confidence. Detect workspace root, enumerate workspace packages, resolve internal imports to actual source files with high confidence (0.95).~~ | Resolution | ~~Fixes resolution for the most common monorepo patterns — affects every monorepo user. Internal package imports currently produce wrong or missing edges~~ | ✓ | ✓ | 4 | No | — | **PROMOTED** — Moved to ROADMAP Phase 4.6 (resolution layer only; full monorepo graph in Phase 12.2) |
| 92 | Auto-generate MCP tool schemas from types | The `tool-registry.js` (801 LOC) contains hand-maintained JSON schemas for 40+ tools. With TypeScript (Phase 5), these can be derived from types via `zod` or `typebox`. Schema drift between the implementation and MCP schema is inevitable with hand-maintenance. | Embeddability | Eliminates an entire class of MCP bugs (schema says one thing, implementation does another). Reduces maintenance burden for adding new MCP tools | ✗ | ✓ | 3 | No | Phase 5 (TypeScript) |
| 93 | ~~Shell completion for CLI~~ | ~~Commander supports shell completion but it's not implemented. `codegraph completion bash\|zsh\|fish` outputs the appropriate script. Basic UX gap for a CLI tool with 40+ commands.~~ | Developer Experience | ~~Tab completion makes the CLI discoverable — users find commands without reading docs. Reduces friction for new users and agents exploring available commands~~ | ✓ | ✓ | 2 | No | — | **PROMOTED** — Moved to ROADMAP Phase 7.11 |
| 94 | VS Code extension | Replace the planned Web UI (removed from roadmap Phase 12) with a VS Code extension providing: webview-based graph visualization (reusing the existing `viewer.js` HTML), go-to-definition via graph edges, inline impact annotations on hover, integration with the MCP server for queries, and a sidebar panel for triage/audit results. VS Code is the right UI target for developer tools in 2026. | Visualization | Developers get graph intelligence directly in their editor — no context switching to a browser or terminal. Impact annotations on hover surface blast radius without running commands | ✗ | ✓ | 3 | No | — |
| 104 | Architecture-as-code validation gate | Elevate `codegraph check` + `manifesto` + `boundaries` into a unified "architecture-as-code" validation system. Define architectural invariants in `.codegraphrc.json` under a new `architecture{}` block: layer rules (existing `boundaries`), dependency direction rules ("domain must not import infrastructure"), module cohesion thresholds ("community drift score < 0.3"), fan-in caps per layer ("adapters must have fan-in < 5"), and cross-cutting constraints ("no file may import from more than 3 top-level directories"). `codegraph check --architecture` validates all rules in one pass, exit code 1 on any violation. Framing inspired by Weft's design principle "if it compiles, the architecture is sound" — the goal is that passing `codegraph check` in CI means the architecture is structurally valid, not just that individual metrics are below thresholds. Builds entirely on existing `boundaries`, `manifesto`, `communities`, and `check` infrastructure — the work is unification and config surface, not new analysis. | Architecture | Current architecture validation is scattered across three features (`boundaries`, `manifesto`, `check`) with separate configs and no unified mental model. A single `architecture{}` config block with a single `check --architecture` command makes it practical for teams to adopt architectural CI gates — the barrier today is config complexity, not capability. Directly prevents architectural decay by making violations as visible as test failures | ✓ | ✓ | 4 | No | — |
| 95 | SARIF output for cycle detection | Add SARIF output format so cycle detection integrates with GitHub Code Scanning, showing issues inline in PRs. Currently planned for Phase 11 but could be delivered as early as Phase 7 since it's a pure output format addition. | CI | GitHub Code Scanning integration surfaces cycle violations directly in PR review — no separate CI step or comment bot needed | ✓ | ✓ | 3 | No | — |
| 96 | Fix README runtime dependency count | README claims "Only 3 runtime dependencies" but there are 5 — it omits `graphology` and `graphology-communities-louvain` which are in `package.json` `dependencies` (not optional). Correct to 5. | Documentation | Accuracy — users and contributors should be able to trust the README | ✓ | ✓ | 1 | No | #545 | **SUPERSEDED** — PR #545 removes `graphology` and `graphology-communities-louvain`, making the README's "3 runtime dependencies" claim correct again. No further action needed once #545 merges. |

### Tier 2 — Foundation-aligned, needs dependencies

Ordered by problem-fit:

| 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 | 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. |

---

## Scoring Guide

When filling in the assessment columns during a prioritization session:

**Zero-dep checklist:**
- Does it use only tree-sitter AST data we already extract? → likely zero-dep
- Does it need a new npm package at runtime? → not zero-dep
- Does it need git CLI access? → acceptable (git is already assumed)
- Does it need a new WASM module or native addon? → not zero-dep

**Foundation alignment red flags:**
- Adds a cloud API call to the core pipeline → violates P1 and P4
- Requires Docker, external DB, or non-npm toolchain → violates zero-infrastructure goal
- Generates code, edits files, or makes decisions → violates P8 (we're not an agent)
- Primarily optimizes for CI/CD or linting use cases → deprioritized by P8 (we optimize for planning, developing, and refactoring)
- Breaks programmatic API contract → check against P5 (embeddable-first)

**Problem-fit rubric:**
- **5** — Directly reduces token waste, prevents hallucinated dependencies, or catches blast-radius breakage
- **4** — Improves agent accuracy or reduces round-trips for common tasks
- **3** — Useful for developers and agents but doesn't address the core "lost AI" problem
- **2** — Nice-to-have; improves the tool but tangential to the stated problem
- **1** — Cool feature, but doesn't help AI agents navigate codebases better

