From fec01d4213e85f9902364de263b37d4234364a41 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 16 Mar 2026 04:50:10 -0600
Subject: [PATCH 01/52] docs: promote #83 (brief command) and #71 (type
 inference) to Tier 0 in backlog

These two items deliver the highest immediate impact on agent experience
and graph accuracy without requiring Rust porting or TypeScript migration.
They should be implemented before any Phase 4+ roadmap work.

- #83: hook-optimized `codegraph brief` enriches passively-injected context
- #71: basic type inference closes the biggest resolution gap for TS/Java
---
 docs/roadmap/BACKLOG.md | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/docs/roadmap/BACKLOG.md b/docs/roadmap/BACKLOG.md
index 7c7cea66..c5876a18 100644
--- a/docs/roadmap/BACKLOG.md
+++ b/docs/roadmap/BACKLOG.md
@@ -21,6 +21,17 @@ Each item has a short title, description, category, expected benefit, and four a
 
 ## Backlog
 
+### Tier 0 — Promote before Phase 4-5 (highest immediate impact)
+
+These two items directly improve agent experience and graph accuracy today, without requiring Rust porting or TypeScript migration. They should be implemented before any Phase 4+ roadmap work begins.
+
+**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 closes the biggest accuracy gap in the graph for TypeScript and Java, where missing type-aware resolution causes 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 | — |
+| 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 | — |
+
 ### Tier 1 — Zero-dep + Foundation-aligned (build these first)
 
 Non-breaking, ordered by problem-fit:
@@ -144,7 +155,6 @@ These address fundamental limitations in the parsing and resolution pipeline tha
 
 | ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking | Depends on |
 |----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|------------|
-| 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 | — |
 | 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 | — |
 | 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 | — |
@@ -163,7 +173,6 @@ These close gaps in search expressiveness, cross-repo navigation, implementation
 | 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 | — |
 | 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 |
-| 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 | — |
 
 ### Tier 2 — Foundation-aligned, needs dependencies
 

From 41d664f1b106c7a72484864b9a029803a3df8f9d Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 16 Mar 2026 04:55:02 -0600
Subject: [PATCH 02/52] docs: add Phase 4 (Native Analysis Acceleration) to
 roadmap

Add new Phase 4 covering the port of JS-only build phases to Rust:
- 4.1-4.3: AST nodes, CFG, dataflow visitor ports (~587ms savings)
- 4.4: Batch SQLite inserts (~143ms)
- 4.5: Role classification & structure (~42ms)
- 4.6: Complete complexity pre-computation
- 4.7: Fix incremental rebuild data loss on native engine
- 4.8: Incremental rebuild performance (target sub-100ms)

Bump old Phases 4-10 to 5-11 with all cross-references updated.
Benchmark evidence shows ~50% of native build time is spent in
JS visitors that run identically on both engines.
---
 docs/roadmap/ROADMAP.md | 325 +++++++++++++++++++++++++++-------------
 1 file changed, 220 insertions(+), 105 deletions(-)

diff --git a/docs/roadmap/ROADMAP.md b/docs/roadmap/ROADMAP.md
index 4ca9cf9d..9edda2d1 100644
--- a/docs/roadmap/ROADMAP.md
+++ b/docs/roadmap/ROADMAP.md
@@ -2,7 +2,7 @@
 
 > **Current version:** 3.1.4 | **Status:** Active development | **Updated:** March 2026
 
-Codegraph is a strong local-first code graph CLI. This roadmap describes planned improvements across ten phases -- closing gaps with commercial code intelligence platforms while preserving codegraph's core strengths: fully local, open source, zero cloud dependency by default.
+Codegraph is a strong local-first code graph CLI. This roadmap describes planned improvements across eleven phases -- closing gaps with commercial code intelligence platforms while preserving codegraph's core strengths: fully local, open source, zero cloud dependency by default.
 
 **LLM strategy:** All LLM-powered features are **optional enhancements**. Everything works without an API key. When configured (OpenAI, Anthropic, Ollama, or any OpenAI-compatible endpoint), users unlock richer semantic search and natural language queries.
 
@@ -13,17 +13,18 @@ Codegraph is a strong local-first code graph CLI. This roadmap describes planned
 | Phase | Theme | Key Deliverables | Status |
 |-------|-------|-----------------|--------|
 | [**1**](#phase-1--rust-core) | Rust Core | Rust parsing engine via napi-rs, parallel parsing, incremental tree-sitter, JS orchestration layer | **Complete** (v1.3.0) |
-| [**2**](#phase-2--foundation-hardening) | Foundation Hardening | Parser registry, complete MCP, test coverage, enhanced config, multi-repo MCP | **Complete** (v1.4.0) |
-| [**2.5**](#phase-25--analysis-expansion) | Analysis Expansion | Complexity metrics, community detection, flow tracing, co-change, manifesto, boundary rules, check, triage, audit, batch, hybrid search | **Complete** (v2.6.0) |
+| [**2**](#phase-2--foundation-hardening) | Foundation Hardening | Parser registry, complete MCP, test coverage, enhanced config, multi-repo MCP | **Complete** (v1.5.0) |
+| [**2.5**](#phase-25--analysis-expansion) | Analysis Expansion | Complexity metrics, community detection, flow tracing, co-change, manifesto, boundary rules, check, triage, audit, batch, hybrid search | **Complete** (v2.7.0) |
 | [**2.7**](#phase-27--deep-analysis--graph-enrichment) | Deep Analysis & Graph Enrichment | Dataflow analysis, intraprocedural CFG, AST node storage, expanded node/edge types, extractors refactoring, CLI consolidation, interactive viewer, exports command, normalizeSymbol | **Complete** (v3.0.0) |
 | [**3**](#phase-3--architectural-refactoring) | Architectural Refactoring (Vertical Slice) | Unified AST analysis framework, command/query separation, repository pattern, queries.js decomposition, composable MCP, CLI commands, domain errors, builder pipeline, presentation layer, domain grouping, curated API, unified graph model, qualified names, CLI composability | **In Progress** (v3.1.4) |
-| [**4**](#phase-4--typescript-migration) | TypeScript Migration | Project setup, core type definitions, leaf -> core -> orchestration module migration, test migration, supply-chain security, CI coverage gates | Planned |
-| [**5**](#phase-5--runtime--extensibility) | Runtime & Extensibility | Event-driven pipeline, unified engine strategy, subgraph export filtering, transitive confidence, query caching, configuration profiles, pagination, plugin system, DX & onboarding | Planned |
-| [**6**](#phase-6--intelligent-embeddings) | Intelligent Embeddings | LLM-generated descriptions, enhanced embeddings, build-time semantic metadata, module summaries | Planned |
-| [**7**](#phase-7--natural-language-queries) | Natural Language Queries | `ask` command, conversational sessions, LLM-narrated graph queries, onboarding tools | Planned |
-| [**8**](#phase-8--expanded-language-support) | Expanded Language Support | 8 new languages (11 -> 19), parser utilities | Planned |
-| [**9**](#phase-9--github-integration--ci) | GitHub Integration & CI | Reusable GitHub Action, LLM-enhanced PR review, visual impact graphs, SARIF output | Planned |
-| [**10**](#phase-10--interactive-visualization--advanced-features) | Visualization & Advanced | Web UI, dead code detection, monorepo, agentic search, refactoring analysis | Planned |
+| [**4**](#phase-4--native-analysis-acceleration) | Native Analysis Acceleration | Move JS-only build phases (AST nodes, CFG, dataflow, insert nodes, structure, roles, complexity) to Rust; fix incremental rebuild data loss on native; sub-100ms 1-file rebuilds | Planned |
+| [**5**](#phase-5--typescript-migration) | TypeScript Migration | Project setup, core type definitions, leaf -> core -> orchestration module migration, test migration, supply-chain security, CI coverage gates | Planned |
+| [**6**](#phase-6--runtime--extensibility) | Runtime & Extensibility | Event-driven pipeline, unified engine strategy, subgraph export filtering, transitive confidence, query caching, configuration profiles, pagination, plugin system, DX & onboarding | Planned |
+| [**7**](#phase-7--intelligent-embeddings) | Intelligent Embeddings | LLM-generated descriptions, enhanced embeddings, build-time semantic metadata, module summaries | Planned |
+| [**8**](#phase-8--natural-language-queries) | Natural Language Queries | `ask` command, conversational sessions, LLM-narrated graph queries, onboarding tools | Planned |
+| [**9**](#phase-9--expanded-language-support) | Expanded Language Support | 8 new languages (11 -> 19), parser utilities | Planned |
+| [**10**](#phase-10--github-integration--ci) | GitHub Integration & CI | Reusable GitHub Action, LLM-enhanced PR review, visual impact graphs, SARIF output | Planned |
+| [**11**](#phase-11--interactive-visualization--advanced-features) | Visualization & Advanced | Web UI, dead code detection, monorepo, agentic search, refactoring analysis | Planned |
 
 ### Dependency graph
 
@@ -33,12 +34,13 @@ Phase 1 (Rust Core)
          |-->  Phase 2.5 (Analysis Expansion)
                 |-->  Phase 2.7 (Deep Analysis & Graph Enrichment)
                        |-->  Phase 3 (Architectural Refactoring)
-                              |-->  Phase 4 (TypeScript Migration)
-                                     |-->  Phase 5 (Runtime & Extensibility)
-                                     |-->  Phase 6 (Embeddings + Metadata)  -->  Phase 7 (NL Queries + Narration)
-                                     |-->  Phase 8 (Languages)
-                                     |-->  Phase 9 (GitHub/CI) <-- Phase 6 (risk_score, side_effects)
-Phases 1-7 -->  Phase 10 (Visualization + Refactoring Analysis)
+                              |-->  Phase 4 (Native Analysis Acceleration)
+                                     |-->  Phase 5 (TypeScript Migration)
+                                            |-->  Phase 6 (Runtime & Extensibility)
+                                            |-->  Phase 7 (Embeddings + Metadata)  -->  Phase 8 (NL Queries + Narration)
+                                            |-->  Phase 9 (Languages)
+                                            |-->  Phase 10 (GitHub/CI) <-- Phase 7 (risk_score, side_effects)
+Phases 1-8 -->  Phase 11 (Visualization + Refactoring Analysis)
 ```
 
 ---
@@ -113,7 +115,7 @@ Ensure the transition is seamless.
 
 ## Phase 2 -- Foundation Hardening ✅
 
-> **Status:** Complete -- shipped in v1.4.0
+> **Status:** Complete -- shipped in v1.5.0
 
 **Goal:** Fix structural issues that make subsequent phases harder.
 
@@ -199,11 +201,11 @@ Support querying multiple codebases from a single MCP server instance.
 
 ## Phase 2.5 -- Analysis Expansion ✅
 
-> **Status:** Complete -- shipped across v2.0.0 -> v2.6.0
+> **Status:** Complete -- shipped across v2.0.0 -> v2.7.0
 
 **Goal:** Build a comprehensive analysis toolkit on top of the graph -- complexity metrics, community detection, risk triage, architecture boundary enforcement, CI validation, and hybrid search. This phase emerged organically as features were needed and wasn't in the original roadmap.
 
-### 2.5.1 -- Complexity Metrics ✅
+### 2.6.1 -- Complexity Metrics ✅
 
 Per-function complexity analysis using language-specific AST rules.
 
@@ -217,7 +219,7 @@ Per-function complexity analysis using language-specific AST rules.
 
 **New file:** `src/complexity.js` (2,163 lines)
 
-### 2.5.2 -- Community Detection & Drift ✅
+### 2.6.2 -- Community Detection & Drift ✅
 
 Louvain community detection at file or function level.
 
@@ -228,7 +230,7 @@ Louvain community detection at file or function level.
 
 **New file:** `src/communities.js` (310 lines)
 
-### 2.5.3 -- Structure & Role Classification ✅
+### 2.6.3 -- Structure & Role Classification ✅
 
 Directory structure graph with node role classification.
 
@@ -241,7 +243,7 @@ Directory structure graph with node role classification.
 
 **New file:** `src/structure.js` (668 lines)
 
-### 2.5.4 -- Execution Flow Tracing ✅
+### 2.6.4 -- Execution Flow Tracing ✅
 
 Forward BFS from framework entry points through callees to leaves.
 
@@ -251,7 +253,7 @@ Forward BFS from framework entry points through callees to leaves.
 
 **New file:** `src/flow.js` (362 lines)
 
-### 2.5.5 -- Temporal Coupling (Co-change Analysis) ✅
+### 2.6.5 -- Temporal Coupling (Co-change Analysis) ✅
 
 Git history analysis for temporal file coupling.
 
@@ -262,7 +264,7 @@ Git history analysis for temporal file coupling.
 
 **New file:** `src/cochange.js` (502 lines)
 
-### 2.5.6 -- Manifesto Rule Engine ✅
+### 2.6.6 -- Manifesto Rule Engine ✅
 
 Configurable rule engine with warn/fail thresholds for function, file, and graph rules.
 
@@ -274,7 +276,7 @@ Configurable rule engine with warn/fail thresholds for function, file, and graph
 
 **New file:** `src/manifesto.js` (511 lines)
 
-### 2.5.7 -- Architecture Boundary Rules ✅
+### 2.6.7 -- Architecture Boundary Rules ✅
 
 Architecture enforcement using glob patterns and presets.
 
@@ -285,7 +287,7 @@ Architecture enforcement using glob patterns and presets.
 
 **New file:** `src/boundaries.js` (347 lines)
 
-### 2.5.8 -- CI Validation Predicates (`check`) ✅
+### 2.6.8 -- CI Validation Predicates (`check`) ✅
 
 Structured pass/fail checks for CI pipelines.
 
@@ -299,7 +301,7 @@ Structured pass/fail checks for CI pipelines.
 
 **New file:** `src/check.js` (433 lines)
 
-### 2.5.9 -- Composite Analysis Commands ✅
+### 2.6.9 -- Composite Analysis Commands ✅
 
 High-level commands that compose multiple analysis steps.
 
@@ -309,7 +311,7 @@ High-level commands that compose multiple analysis steps.
 
 **New files:** `src/audit.js` (424 lines), `src/batch.js` (91 lines), `src/triage.js` (274 lines)
 
-### 2.5.10 -- Hybrid Search ✅
+### 2.6.10 -- Hybrid Search ✅
 
 BM25 keyword search + semantic vector search with RRF fusion.
 
@@ -321,7 +323,7 @@ BM25 keyword search + semantic vector search with RRF fusion.
 
 **Affected file:** `src/embedder.js` (grew from 525 -> 1,113 lines)
 
-### 2.5.11 -- Supporting Infrastructure ✅
+### 2.6.11 -- Supporting Infrastructure ✅
 
 Cross-cutting utilities added during the expansion.
 
@@ -333,7 +335,7 @@ Cross-cutting utilities added during the expansion.
 - ✅ **Journal:** change journal validation/management (`src/journal.js`, 110 lines)
 - ✅ **Update Check:** npm registry polling with 24h cache (`src/update-check.js`, 161 lines)
 
-### 2.5.12 -- MCP Tool Expansion ✅
+### 2.6.12 -- MCP Tool Expansion ✅
 
 MCP grew from 12 -> 25 tools, covering all new analysis capabilities.
 
@@ -365,7 +367,7 @@ MCP grew from 12 -> 25 tools, covering all new analysis capabilities.
 
 **Goal:** Add deeper static analysis capabilities (dataflow, control flow graphs, AST querying), enrich the graph model with sub-declaration node types and structural edges, refactor extractors into per-language modules, consolidate the CLI surface area, and introduce interactive visualization. This phase emerged from competitive analysis against Joern and Narsil-MCP.
 
-### 2.7.1 -- Dataflow Analysis ✅
+### 2.8.1 -- Dataflow Analysis ✅
 
 Define-use chain extraction tracking how data flows between functions.
 
@@ -382,7 +384,7 @@ Define-use chain extraction tracking how data flows between functions.
 
 **New file:** `src/dataflow.js` (1,187 lines)
 
-### 2.7.2 -- Expanded Node Types (Phase 1) ✅
+### 2.8.2 -- Expanded Node Types (Phase 1) ✅
 
 Extend the graph model with sub-declaration node kinds.
 
@@ -396,7 +398,7 @@ Extend the graph model with sub-declaration node kinds.
 
 **Affected files:** All extractors, `src/builder.js`, `src/queries.js`, `src/db.js`
 
-### 2.7.3 -- Expanded Edge Types (Phase 2) ✅
+### 2.8.3 -- Expanded Edge Types (Phase 2) ✅
 
 Structural edges for richer graph relationships.
 
@@ -407,7 +409,7 @@ Structural edges for richer graph relationships.
 
 **Affected files:** `src/builder.js`, `src/queries.js`
 
-### 2.7.4 -- Intraprocedural Control Flow Graph (CFG) ✅
+### 2.8.4 -- Intraprocedural Control Flow Graph (CFG) ✅
 
 Basic-block control flow graph construction from function ASTs.
 
@@ -422,7 +424,7 @@ Basic-block control flow graph construction from function ASTs.
 
 **New file:** `src/cfg.js` (1,451 lines)
 
-### 2.7.5 -- Stored Queryable AST Nodes ✅
+### 2.8.5 -- Stored Queryable AST Nodes ✅
 
 Persist and query selected AST node types for pattern-based codebase exploration.
 
@@ -437,7 +439,7 @@ Persist and query selected AST node types for pattern-based codebase exploration
 
 **New file:** `src/ast.js` (392 lines)
 
-### 2.7.6 -- Extractors Refactoring ✅
+### 2.8.6 -- Extractors Refactoring ✅
 
 Split per-language extractors from monolithic `parser.js` into dedicated modules.
 
@@ -451,7 +453,7 @@ Split per-language extractors from monolithic `parser.js` into dedicated modules
 
 **New directory:** `src/extractors/`
 
-### 2.7.7 -- normalizeSymbol Utility ✅
+### 2.8.7 -- normalizeSymbol Utility ✅
 
 Stable JSON schema for symbol output across all query functions.
 
@@ -461,7 +463,7 @@ Stable JSON schema for symbol output across all query functions.
 
 **Affected file:** `src/queries.js`
 
-### 2.7.8 -- Interactive Graph Viewer ✅
+### 2.8.8 -- Interactive Graph Viewer ✅
 
 Self-contained HTML visualization with vis-network.
 
@@ -478,7 +480,7 @@ Self-contained HTML visualization with vis-network.
 
 **New file:** `src/viewer.js` (948 lines)
 
-### 2.7.9 -- Exports Command ✅
+### 2.8.9 -- Exports Command ✅
 
 Per-symbol consumer analysis for file exports.
 
@@ -489,7 +491,7 @@ Per-symbol consumer analysis for file exports.
 
 **Affected file:** `src/queries.js`
 
-### 2.7.10 -- Export Format Expansion ✅
+### 2.8.10 -- Export Format Expansion ✅
 
 Three new graph export formats for external tooling integration.
 
@@ -499,7 +501,7 @@ Three new graph export formats for external tooling integration.
 
 **Affected file:** `src/export.js` (681 lines)
 
-### 2.7.11 -- CLI Consolidation ✅
+### 2.8.11 -- CLI Consolidation ✅
 
 First CLI surface area reduction -- 5 commands merged into existing ones.
 
@@ -512,7 +514,7 @@ First CLI surface area reduction -- 5 commands merged into existing ones.
 
 **Affected file:** `src/cli.js`
 
-### 2.7.12 -- MCP Tool Consolidation & Expansion ✅
+### 2.8.12 -- MCP Tool Consolidation & Expansion ✅
 
 MCP tools were both consolidated and expanded, resulting in a net change from 25 → 30 tools (31 in multi-repo mode).
 
@@ -540,7 +542,7 @@ Plus updated enums on existing tools (edge_kinds, symbol kinds).
 
 ### 2.7 Summary
 
-| Metric | Before (v2.6.0) | After (v3.0.0) | Delta |
+| Metric | Before (v2.7.0) | After (v3.0.0) | Delta |
 |--------|-----------------|-----------------|-------|
 | Source modules | 35 | 50 | +15 |
 | Total source lines | 17,830 | 26,277 | +47% |
@@ -991,13 +993,126 @@ Practical cleanup to make the CLI surface match the internal composability that
 
 ---
 
-## Phase 4 -- TypeScript Migration
+## Phase 4 -- Native Analysis Acceleration
+
+**Goal:** Move the remaining JS-only build phases to Rust so that `--engine native` eliminates all redundant WASM visitor walks. Today only 3 of 10 build phases (parse, resolve imports, build edges) run in Rust — the other 7 execute identical JavaScript regardless of engine, leaving ~50% of native build time on the table.
+
+**Why its own phase:** This is a substantial Rust engineering effort — porting 6 JS visitors to `crates/codegraph-core/`, fixing a data loss bug in incremental rebuilds, and optimizing the 1-file rebuild path. Doing this before the TS migration avoids rewriting the same visitor code twice (once to TS, once to Rust). The Phase 3 module boundaries make each phase a self-contained target.
+
+**Evidence (v3.1.4 benchmarks on 398 files):**
+
+| Phase | Native | WASM | Ratio | Status |
+|-------|-------:|-----:|------:|--------|
+| Parse | 468ms | 1483ms | 3.2x faster | Already Rust |
+| Build edges | 88ms | 152ms | 1.7x faster | Already Rust |
+| Resolve imports | 8ms | 9ms | ~1x | Already Rust |
+| **AST nodes** | **361ms** | **347ms** | **~1x** | JS visitor — biggest win |
+| **CFG** | **126ms** | **125ms** | **~1x** | JS visitor |
+| **Dataflow** | **100ms** | **98ms** | **~1x** | JS visitor |
+| **Insert nodes** | **143ms** | **148ms** | **~1x** | Pure SQLite batching |
+| **Roles** | **29ms** | **32ms** | **~1x** | JS classification |
+| **Structure** | **13ms** | **17ms** | **~1x** | JS directory tree |
+| Complexity | 16ms | 77ms | 5x faster | Partly pre-computed |
+
+**Target:** Reduce native full-build time from ~1,400ms to ~700ms (2x improvement) by eliminating ~690ms of redundant JS visitor work.
+
+### 4.1 -- AST Node Extraction in Rust
+
+The largest single opportunity. Currently the native parser returns partial AST node data, so the JS `buildAstNodes()` visitor re-walks all WASM trees anyway (~361ms).
+
+- Extend `crates/codegraph-core/` to extract all AST node types (`call`, `new`, `string`, `regex`, `throw`, `await`) during the native parse phase
+- Return complete AST node data in the `FileSymbols` result so `run-analyses.js` can skip the WASM walker entirely
+- Validate parity: ensure native extraction produces identical node counts to the WASM visitor (benchmark already tracks this via `nodes/file`)
+
+**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/ast.js`, `src/domain/graph/builder/stages/run-analyses.js`
+
+### 4.2 -- CFG Construction in Rust
+
+The intraprocedural control-flow graph visitor runs in JS even on native builds (~126ms).
+
+- Port `createCfgVisitor()` logic to Rust: basic block detection, branch/loop edges, entry/exit nodes
+- Return CFG block data per function in `FileSymbols` so the JS visitor is fully bypassed
+- Validate parity: CFG block counts and edge counts must match the WASM visitor output
+
+**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/cfg.js`, `src/ast-analysis/visitors/cfg-visitor.js`
+
+### 4.3 -- Dataflow Analysis in Rust
+
+Dataflow edges are computed by a JS visitor that walks WASM trees (~100ms on native builds).
+
+- Port `createDataflowVisitor()` to Rust: variable definitions, assignments, reads, def-use chains
+- Return dataflow edges in `FileSymbols`
+- Validate parity against WASM visitor output
+
+**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/dataflow.js`, `src/ast-analysis/visitors/dataflow-visitor.js`
+
+### 4.4 -- Batch SQLite Inserts via Rust
+
+`insertNodes` is pure SQLite work (~143ms) but runs row-by-row from JS. Batching in Rust can reduce JS↔native boundary crossings.
+
+- Expose a `batchInsertNodes(nodes[])` function from Rust that uses a single prepared statement in a transaction
+- Alternatively, generate the SQL batch on the JS side and execute as a single `better-sqlite3` call (may be sufficient without Rust)
+- Benchmark both approaches; pick whichever is faster
+
+**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/db/index.js`, `src/domain/graph/builder/stages/insert-nodes.js`
+
+### 4.5 -- Role Classification & Structure in Rust
+
+Smaller wins (~42ms combined) but complete the picture of a fully native build pipeline.
+
+- Port `classifyNodeRoles()` to Rust: hub/leaf/bridge/utility classification based on in/out degree and betweenness
+- Port directory structure building and metrics aggregation
+- Return role assignments and structure data alongside parse results
+
+**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/structure.js`, `src/domain/graph/builder/stages/build-structure.js`
+
+### 4.6 -- Complete Complexity Pre-computation
+
+Complexity is partly pre-computed by native (~16ms vs 77ms WASM) but not all functions are covered.
+
+- Ensure native parse computes cognitive, cyclomatic, Halstead, and MI metrics for every function, not just a subset
+- Eliminate the WASM fallback path in `buildComplexityMetrics()` when running native
+
+**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/complexity.js`
+
+### 4.7 -- Fix Incremental Rebuild Data Loss on Native Engine
+
+**Bug:** On native 1-file rebuilds, complexity, CFG, and dataflow data for the changed file is **silently lost**. `purgeFilesFromGraph` removes the old data, but the analysis phases never re-compute it because:
+
+1. The native parser does not produce a `_tree` (WASM tree-sitter tree)
+2. The unified walker at `src/ast-analysis/engine.js:108-109` skips files without `_tree`
+3. The `buildXxx` functions check for pre-computed fields (`d.complexity`, `d.cfg?.blocks`) which the native parser does not provide for these analyses
+4. Result: 0.1ms no-op — the phases run but do nothing
+
+This is confirmed by the v3.1.4 1-file rebuild data: complexity (0.1ms), CFG (0.1ms), dataflow (0.2ms) on native — these are just module import overhead, not actual computation. Contrast with v3.1.3 where the numbers were higher (1.3ms, 8.7ms, 4ms) because earlier versions triggered a WASM fallback tree via `ensureWasmTrees`.
+
+**Fix (prerequisite: 4.1–4.3):** Once the native parser returns complete AST nodes, CFG blocks, and dataflow edges in `FileSymbols`, the `run-analyses` stage can store them directly without needing a WASM tree. The incremental path must:
+
+- Ensure `parseFilesAuto()` returns pre-computed analysis data for the single changed file
+- Have `run-analyses.js` store that data (currently it only stores if `_tree` exists or if pre-computed fields are present — the latter path needs to work reliably)
+- Add an integration test: rebuild 1 file on native engine, then query its complexity/CFG/dataflow and assert non-empty results
+
+**Affected files:** `src/ast-analysis/engine.js`, `src/domain/graph/builder/stages/run-analyses.js`, `src/domain/parser.js`, `tests/integration/`
+
+### 4.8 -- Incremental Rebuild Performance
+
+With analysis data loss fixed, optimize the 1-file rebuild path end-to-end. Current native 1-file rebuild is 265ms — dominated by parse (51ms), structure (13ms), roles (27ms), edges (13ms), insert (12ms), and finalize (12ms).
+
+- **Skip unchanged phases:** Structure and roles are graph-wide computations. On a 1-file change, only the changed file's nodes/edges need updating — skip full reclassification unless the file's degree changed significantly
+- **Incremental edge rebuild:** Only rebuild edges involving the changed file's symbols, not the full edge set
+- **Benchmark target:** Sub-100ms native 1-file rebuilds (from current 265ms)
+
+**Affected files:** `src/domain/graph/builder/stages/build-structure.js`, `src/domain/graph/builder/stages/build-edges.js`, `src/domain/graph/builder/pipeline.js`
+
+---
+
+## Phase 5 -- TypeScript Migration
 
 **Goal:** Migrate the codebase from plain JavaScript to TypeScript, leveraging the clean module boundaries established in Phase 3. Incremental module-by-module migration starting from leaf modules inward.
 
 **Why after Phase 3:** The architectural refactoring creates small, well-bounded modules with explicit interfaces (Repository, Engine, BaseExtractor, Pipeline stages, Command objects). These are natural type boundaries -- typing monolithic 2,000-line files that are about to be split would be double work.
 
-### 4.1 -- Project Setup
+### 5.1 -- Project Setup
 
 - Add `typescript` as a devDependency
 - Create `tsconfig.json` with strict mode, ES module output, path aliases matching the Phase 3 module structure
@@ -1008,7 +1123,7 @@ Practical cleanup to make the CLI surface match the internal composability that
 
 **Affected files:** `package.json`, `biome.json`, new `tsconfig.json`
 
-### 4.2 -- Core Type Definitions
+### 5.2 -- Core Type Definitions
 
 Define TypeScript interfaces for all abstractions introduced in Phase 3:
 
@@ -1036,7 +1151,7 @@ These interfaces serve as the migration contract -- each module is migrated to s
 
 **New file:** `src/types.ts`
 
-### 4.3 -- Leaf Module Migration
+### 5.3 -- Leaf Module Migration
 
 Migrate modules with no internal dependencies first:
 
@@ -1053,7 +1168,7 @@ Migrate modules with no internal dependencies first:
 
 Allow `.js` and `.ts` to coexist during migration (`allowJs: true` in tsconfig).
 
-### 4.4 -- Core Module Migration
+### 5.4 -- Core Module Migration
 
 Migrate modules that implement Phase 3 interfaces:
 
@@ -1068,7 +1183,7 @@ Migrate modules that implement Phase 3 interfaces:
 | `src/analysis/*.ts` | Typed analysis results (impact scores, call chains) |
 | `src/resolve.ts` | Import resolution with confidence types |
 
-### 4.5 -- Orchestration & Public API Migration
+### 5.5 -- Orchestration & Public API Migration
 
 Migrate top-level orchestration and entry points:
 
@@ -1081,7 +1196,7 @@ Migrate top-level orchestration and entry points:
 | `src/cli/*.ts` | Command objects with typed options |
 | `src/index.ts` | Curated public API with proper export types |
 
-### 4.6 -- Test Migration
+### 5.6 -- Test Migration
 
 - Migrate test files from `.js` to `.ts`
 - Add type-safe test utilities and fixture builders
@@ -1092,7 +1207,7 @@ Migrate top-level orchestration and entry points:
 
 **Affected files:** All `src/**/*.js` -> `src/**/*.ts`, all `tests/**/*.js` -> `tests/**/*.ts`, `package.json`, `biome.json`
 
-### 4.7 -- Supply-Chain Security & Audit
+### 5.7 -- Supply-Chain Security & Audit
 
 **Gap:** No `npm audit` in CI pipeline. No supply-chain attestation (SLSA/SBOM). No formal security audit history.
 
@@ -1105,33 +1220,33 @@ Migrate top-level orchestration and entry points:
 
 **Affected files:** `.github/workflows/ci.yml`, `.github/workflows/publish.yml`, `docs/security/`
 
-### 4.8 -- CI Test Quality & Coverage Gates
+### 5.8 -- CI Test Quality & Coverage Gates
 
 **Gaps:**
 
 - No coverage thresholds enforced in CI (coverage report runs locally only)
 - Embedding tests in separate workflow requiring HuggingFace token
 - 312 `setTimeout`/`sleep` instances in tests — potential flakiness under load
-- No dependency audit step in CI (see also [4.7](#47----supply-chain-security--audit))
+- No dependency audit step in CI (see also [5.7](#47----supply-chain-security--audit))
 
 **Deliverables:**
 
 1. **Coverage gate** -- add `vitest --coverage` to CI with minimum threshold (e.g. 80% lines/branches); fail the pipeline when coverage drops below the threshold
 2. **Unified test workflow** -- merge embedding tests into the main CI workflow using a securely stored `HF_TOKEN` secret; eliminate the separate workflow
 3. **Timer cleanup** -- audit and reduce `setTimeout`/`sleep` usage in tests; replace with deterministic waits (event-based, polling with backoff, or `vi.useFakeTimers()`) to reduce flakiness
-4. > _Dependency audit step is covered by [4.7](#47----supply-chain-security--audit) deliverable 1._
+4. > _Dependency audit step is covered by [5.7](#47----supply-chain-security--audit) deliverable 1._
 
 **Affected files:** `.github/workflows/ci.yml`, `vitest.config.js`, `tests/`
 
 ---
 
-## Phase 5 -- Runtime & Extensibility
+## Phase 6 -- Runtime & Extensibility
 
-**Goal:** Harden the runtime for large codebases and open the platform to external contributors. These items were deferred from Phase 3 -- they depend on the clean module boundaries and domain layering established there, and benefit from TypeScript's type safety (Phase 4) for safe refactoring of cross-cutting concerns like caching, streaming, and plugin contracts.
+**Goal:** Harden the runtime for large codebases and open the platform to external contributors. These items were deferred from Phase 3 -- they depend on the clean module boundaries and domain layering established there, and benefit from TypeScript's type safety (Phase 5) for safe refactoring of cross-cutting concerns like caching, streaming, and plugin contracts.
 
 **Why after TypeScript Migration:** Several of these items introduce new internal contracts (plugin API, cache interface, streaming protocol, engine strategy). Defining those contracts in TypeScript from the start avoids a second migration pass and gives contributors type-checked extension points.
 
-### 5.1 -- Event-Driven Pipeline
+### 6.1 -- Event-Driven Pipeline
 
 Replace the synchronous build/analysis pipeline with an event/streaming architecture. Enables progress reporting, cancellation tokens, and bounded memory usage on large repositories (10K+ files).
 
@@ -1143,7 +1258,7 @@ Replace the synchronous build/analysis pipeline with an event/streaming architec
 
 **Affected files:** `src/domain/graph/builder.js`, `src/cli/`, `src/mcp/`
 
-### 5.2 -- Unified Engine Interface (Strategy Pattern)
+### 6.2 -- Unified Engine Interface (Strategy Pattern)
 
 Replace scattered `engine.name === 'native'` / `engine === 'wasm'` branching throughout the codebase with a formal Strategy pattern. Each engine implements a common `ParsingEngine` interface with methods like `parse(file)`, `batchParse(files)`, `supports(language)`, and `capabilities()`.
 
@@ -1155,7 +1270,7 @@ Replace scattered `engine.name === 'native'` / `engine === 'wasm'` branching thr
 
 **Affected files:** `src/infrastructure/native.js`, `src/domain/parser.js`, `src/domain/graph/builder.js`
 
-### 5.3 -- Subgraph Export Filtering
+### 6.3 -- Subgraph Export Filtering
 
 Add focus and depth controls to `codegraph export` so users can produce usable visualizations of specific subsystems rather than the entire graph.
 
@@ -1172,7 +1287,7 @@ codegraph export --focus "buildGraph" --depth 3 --format dot
 
 **Affected files:** `src/features/export.js`, `src/presentation/export.js`
 
-### 5.4 -- Transitive Import-Aware Confidence
+### 6.4 -- Transitive Import-Aware Confidence
 
 Improve import resolution accuracy by walking the import graph before falling back to proximity heuristics. Currently the 6-level priority system uses directory proximity as a strong signal, but this can mis-resolve when a symbol is re-exported through an index file several directories away.
 
@@ -1183,7 +1298,7 @@ Improve import resolution accuracy by walking the import graph before falling ba
 
 **Affected files:** `src/domain/graph/resolve.js`
 
-### 5.5 -- Query Result Caching
+### 6.5 -- Query Result Caching
 
 Add an LRU/TTL cache layer between the analysis/query functions and the SQLite repository. With 34+ MCP tools that often run overlapping queries within a session, caching eliminates redundant DB round-trips.
 
@@ -1196,7 +1311,7 @@ Add an LRU/TTL cache layer between the analysis/query functions and the SQLite r
 
 **Affected files:** `src/domain/analysis/`, `src/db/index.js`
 
-### 5.6 -- Configuration Profiles
+### 6.6 -- Configuration Profiles
 
 Support named configuration profiles for monorepos and multi-service projects where different parts of the codebase need different settings.
 
@@ -1217,7 +1332,7 @@ Support named configuration profiles for monorepos and multi-service projects wh
 
 **Affected files:** `src/infrastructure/config.js`, `src/cli/`
 
-### 5.7 -- Pagination Standardization
+### 6.7 -- Pagination Standardization
 
 Standardize SQL-level `LIMIT`/`OFFSET` pagination across all repository queries and surface it consistently through the CLI and MCP.
 
@@ -1229,7 +1344,7 @@ Standardize SQL-level `LIMIT`/`OFFSET` pagination across all repository queries
 
 **Affected files:** `src/shared/paginate.js`, `src/db/index.js`, `src/domain/analysis/`, `src/mcp/`
 
-### 5.8 -- Plugin System for Custom Commands
+### 6.8 -- Plugin System for Custom Commands
 
 Allow users to extend codegraph with custom commands by dropping a JS/TS module into `~/.codegraph/plugins/` (global) or `.codegraph/plugins/` (project-local).
 
@@ -1257,7 +1372,7 @@ export function data(db: Database, args: ParsedArgs, config: Config): object {
 
 **Affected files:** `src/cli/`, `src/mcp/`, new `src/infrastructure/plugins.js`
 
-### 5.9 -- Developer Experience & Onboarding
+### 6.9 -- Developer Experience & Onboarding
 
 Lower the barrier to first successful use. Today codegraph requires manual install, manual config, and prior knowledge of which command to run next.
 
@@ -1271,13 +1386,13 @@ Lower the barrier to first successful use. Today codegraph requires manual insta
 
 ---
 
-## Phase 6 -- Intelligent Embeddings
+## Phase 7 -- Intelligent Embeddings
 
 **Goal:** Dramatically improve semantic search quality by embedding natural-language descriptions instead of raw code.
 
-> **Phase 6.3 (Hybrid Search) was completed early** during Phase 2.5 -- FTS5 BM25 + semantic search with RRF fusion is already shipped in v2.6.0.
+> **Phase 7.3 (Hybrid Search) was completed early** during Phase 2.5 -- FTS5 BM25 + semantic search with RRF fusion is already shipped in v2.7.0.
 
-### 6.1 -- LLM Description Generator
+### 7.1 -- LLM Description Generator
 
 For each function/method/class node, generate a concise natural-language description:
 
@@ -1305,7 +1420,7 @@ For each function/method/class node, generate a concise natural-language descrip
 
 **New file:** `src/describer.js`
 
-### 6.2 -- Enhanced Embedding Pipeline
+### 7.2 -- Enhanced Embedding Pipeline
 
 - When descriptions exist, embed the description text instead of raw code
 - Keep raw code as fallback when no description is available
@@ -1316,11 +1431,11 @@ For each function/method/class node, generate a concise natural-language descrip
 
 **Affected files:** `src/embedder.js`
 
-### ~~6.3 -- Hybrid Search~~ ✅ Completed in Phase 2.5
+### ~~7.3 -- Hybrid Search~~ ✅ Completed in Phase 2.5
 
-Shipped in v2.6.0. FTS5 BM25 keyword search + semantic vector search with RRF fusion. Three search modes: `hybrid` (default), `semantic`, `keyword`.
+Shipped in v2.7.0. FTS5 BM25 keyword search + semantic vector search with RRF fusion. Three search modes: `hybrid` (default), `semantic`, `keyword`.
 
-### 6.4 -- Build-time Semantic Metadata
+### 7.4 -- Build-time Semantic Metadata
 
 Enrich nodes with LLM-generated metadata beyond descriptions. Computed incrementally at build time (only for changed nodes), stored as columns on the `nodes` table.
 
@@ -1333,9 +1448,9 @@ Enrich nodes with LLM-generated metadata beyond descriptions. Computed increment
 - MCP tool: `assess <name>` -- returns complexity rating + specific concerns
 - Cascade invalidation: when a node changes, mark dependents for re-enrichment
 
-**Depends on:** 6.1 (LLM provider abstraction)
+**Depends on:** 7.1 (LLM provider abstraction)
 
-### 6.5 -- Module Summaries
+### 7.5 -- Module Summaries
 
 Aggregate function descriptions + dependency direction into file-level narratives.
 
@@ -1343,17 +1458,17 @@ Aggregate function descriptions + dependency direction into file-level narrative
 - MCP tool: `explain_module <file>` -- returns module purpose, key exports, role in the system
 - `naming_conventions` metadata per module -- detected patterns (camelCase, snake_case, verb-first), flag outliers
 
-**Depends on:** 6.1 (function-level descriptions must exist first)
+**Depends on:** 7.1 (function-level descriptions must exist first)
 
 > **Full spec:** See [llm-integration.md](./llm-integration.md) for detailed architecture, infrastructure table, and prompt design.
 
 ---
 
-## Phase 7 -- Natural Language Queries
+## Phase 8 -- Natural Language Queries
 
 **Goal:** Allow developers to ask questions about their codebase in plain English.
 
-### 7.1 -- Query Engine
+### 8.1 -- Query Engine
 
 ```bash
 codegraph ask "How does the authentication flow work?"
@@ -1379,7 +1494,7 @@ codegraph ask "How does the authentication flow work?"
 
 **New file:** `src/nlquery.js`
 
-### 7.2 -- Conversational Sessions
+### 8.2 -- Conversational Sessions
 
 Multi-turn conversations with session memory.
 
@@ -1393,7 +1508,7 @@ codegraph sessions clear
 - Store conversation history in SQLite table `sessions`
 - Include prior Q&A pairs in subsequent prompts
 
-### 7.3 -- MCP Integration
+### 8.3 -- MCP Integration
 
 New MCP tool: `ask_codebase` -- natural language query via MCP.
 
@@ -1401,7 +1516,7 @@ Enables AI coding agents (Claude Code, Cursor, etc.) to ask codegraph questions
 
 **Affected files:** `src/mcp.js`
 
-### 7.4 -- LLM-Narrated Graph Queries
+### 8.4 -- LLM-Narrated Graph Queries
 
 Graph traversal + LLM narration for questions that require both structural data and natural-language explanation. Each query walks the graph first, then sends the structural result to the LLM for narration.
 
@@ -1414,9 +1529,9 @@ Graph traversal + LLM narration for questions that require both structural data
 
 Pre-computed `flow_narratives` table caches results for key entry points at build time, invalidated when any node in the chain changes.
 
-**Depends on:** 6.4 (`side_effects` metadata), 6.1 (descriptions for narration context)
+**Depends on:** 7.4 (`side_effects` metadata), 7.1 (descriptions for narration context)
 
-### 7.5 -- Onboarding & Navigation Tools
+### 8.5 -- Onboarding & Navigation Tools
 
 Help new contributors and AI agents orient in an unfamiliar codebase.
 
@@ -1425,15 +1540,15 @@ Help new contributors and AI agents orient in an unfamiliar codebase.
 - MCP tool: `get_started` -- returns ordered list: "start here, then read this, then this"
 - `change_plan <description>` -- LLM reads description, graph identifies relevant modules, returns touch points and test coverage gaps
 
-**Depends on:** 6.5 (module summaries for context), 7.1 (query engine)
+**Depends on:** 7.5 (module summaries for context), 8.1 (query engine)
 
 ---
 
-## Phase 8 -- Expanded Language Support
+## Phase 9 -- Expanded Language Support
 
 **Goal:** Go from 11 -> 19 supported languages.
 
-### 8.1 -- Batch 1: High Demand
+### 9.1 -- Batch 1: High Demand
 
 | Language | Extensions | Grammar | Effort |
 |----------|-----------|---------|--------|
@@ -1442,7 +1557,7 @@ Help new contributors and AI agents orient in an unfamiliar codebase.
 | Kotlin | `.kt`, `.kts` | `tree-sitter-kotlin` | Low |
 | Swift | `.swift` | `tree-sitter-swift` | Medium |
 
-### 8.2 -- Batch 2: Growing Ecosystems
+### 9.2 -- Batch 2: Growing Ecosystems
 
 | Language | Extensions | Grammar | Effort |
 |----------|-----------|---------|--------|
@@ -1451,7 +1566,7 @@ Help new contributors and AI agents orient in an unfamiliar codebase.
 | Lua | `.lua` | `tree-sitter-lua` | Low |
 | Zig | `.zig` | `tree-sitter-zig` | Low |
 
-### 8.3 -- Parser Abstraction Layer
+### 9.3 -- Parser Abstraction Layer
 
 Extract shared patterns from existing extractors into reusable helpers.
 
@@ -1467,13 +1582,13 @@ Extract shared patterns from existing extractors into reusable helpers.
 
 ---
 
-## Phase 9 -- GitHub Integration & CI
+## Phase 10 -- GitHub Integration & CI
 
 **Goal:** Bring codegraph's analysis into pull request workflows.
 
 > **Note:** Phase 2.5 delivered `codegraph check` (CI validation predicates with exit code 0/1), which provides the foundation for GitHub Action integration. The boundary violation, blast radius, and cycle detection predicates are already available.
 
-### 9.1 -- Reusable GitHub Action
+### 10.1 -- Reusable GitHub Action
 
 A reusable GitHub Action that runs on PRs:
 
@@ -1496,7 +1611,7 @@ A reusable GitHub Action that runs on PRs:
 
 **New file:** `.github/actions/codegraph-ci/action.yml`
 
-### 9.2 -- PR Review Integration
+### 10.2 -- PR Review Integration
 
 ```bash
 codegraph review --pr <number>
@@ -1519,7 +1634,7 @@ Requires `gh` CLI. For each changed function:
 
 **New file:** `src/github.js`
 
-### 9.3 -- Visual Impact Graphs for PRs
+### 10.3 -- Visual Impact Graphs for PRs
 
 Extend the existing `diff-impact --format mermaid` foundation with CI automation and LLM annotations.
 
@@ -1540,15 +1655,15 @@ Extend the existing `diff-impact --format mermaid` foundation with CI automation
 - Highlight fragile nodes: high churn + high fan-in = high breakage risk
 - Track blast radius trends: "this PR's blast radius is 2x larger than your average"
 
-**Depends on:** 9.1 (GitHub Action), 6.4 (`risk_score`, `side_effects`)
+**Depends on:** 10.1 (GitHub Action), 7.4 (`risk_score`, `side_effects`)
 
-### 9.4 -- SARIF Output
+### 10.4 -- SARIF Output
 
 Add SARIF output format for cycle detection. SARIF integrates with GitHub Code Scanning, showing issues inline in the PR.
 
 **Affected files:** `src/export.js`
 
-### 9.5 -- Auto-generated Docstrings
+### 10.5 -- Auto-generated Docstrings
 
 ```bash
 codegraph annotate
@@ -1557,15 +1672,15 @@ codegraph annotate --changed-only
 
 LLM-generated docstrings aware of callers, callees, and types. Diff-aware: only regenerate for functions whose code or dependencies changed. Stores in `docstrings` column on nodes table -- does not modify source files unless explicitly requested.
 
-**Depends on:** 6.1 (LLM provider abstraction), 6.4 (side effects context)
+**Depends on:** 7.1 (LLM provider abstraction), 7.4 (side effects context)
 
 ---
 
-## Phase 10 -- Interactive Visualization & Advanced Features
+## Phase 11 -- Interactive Visualization & Advanced Features
 
-### 10.1 -- Interactive Web Visualization (Partially Complete)
+### 11.1 -- Interactive Web Visualization (Partially Complete)
 
-> **Phase 2.7 progress:** `codegraph plot` (Phase 2.7.8) ships a self-contained HTML viewer with vis-network. It supports layout switching, color/size/cluster overlays, drill-down, community detection, and a detail panel. The remaining work is the server-based experience below.
+> **Phase 2.7 progress:** `codegraph plot` (Phase 2.8.8) ships a self-contained HTML viewer with vis-network. It supports layout switching, color/size/cluster overlays, drill-down, community detection, and a detail panel. The remaining work is the server-based experience below.
 
 ```bash
 codegraph viz
@@ -1584,7 +1699,7 @@ Opens a local web UI at `localhost:3000` extending the static HTML viewer with:
 
 **New file:** `src/visualizer.js`
 
-### 10.2 -- Dead Code Detection
+### 11.2 -- Dead Code Detection
 
 ```bash
 codegraph dead
@@ -1597,7 +1712,7 @@ Find functions/methods/classes with zero incoming edges (never called). Filters
 
 **Affected files:** `src/queries.js`
 
-### 10.3 -- Cross-Repository Support (Monorepo)
+### 11.3 -- Cross-Repository Support (Monorepo)
 
 Support multi-package monorepos with cross-package edges.
 
@@ -1607,7 +1722,7 @@ Support multi-package monorepos with cross-package edges.
 - `codegraph build --workspace` to scan all packages
 - Impact analysis across package boundaries
 
-### 10.4 -- Agentic Search
+### 11.4 -- Agentic Search
 
 Recursive reference-following search that traces connections.
 
@@ -1629,7 +1744,7 @@ codegraph agent-search "payment processing"
 
 **New file:** `src/agentic-search.js`
 
-### 10.5 -- Refactoring Analysis
+### 11.5 -- Refactoring Analysis
 
 LLM-powered structural analysis that identifies refactoring opportunities. The graph provides the structural data; the LLM interprets it.
 
@@ -1644,9 +1759,9 @@ LLM-powered structural analysis that identifies refactoring opportunities. The g
 
 > **Note:** `hotspots` and `boundary_analysis` already have data foundations from Phase 2.5 (structure.js hotspots, boundaries.js evaluation). This phase adds LLM interpretation on top.
 
-**Depends on:** 6.4 (`risk_score`, `complexity_notes`), 6.5 (module summaries)
+**Depends on:** 7.4 (`risk_score`, `complexity_notes`), 7.5 (module summaries)
 
-### 10.6 -- Auto-generated Docstrings
+### 11.6 -- Auto-generated Docstrings
 
 ```bash
 codegraph annotate
@@ -1655,7 +1770,7 @@ codegraph annotate --changed-only
 
 LLM-generated docstrings aware of callers, callees, and types. Diff-aware: only regenerate for functions whose code or dependencies changed. Stores in `docstrings` column on nodes table -- does not modify source files unless explicitly requested.
 
-**Depends on:** 6.1 (LLM provider abstraction), 6.4 (side effects context)
+**Depends on:** 7.1 (LLM provider abstraction), 7.4 (side effects context)
 
 > **Full spec:** See [llm-integration.md](./llm-integration.md) for detailed architecture, infrastructure tables, and prompt design for all LLM-powered features.
 

From 30fdd26a4a965694d76a33c14cb054f86b7bddd8 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 16 Mar 2026 05:32:32 -0600
Subject: [PATCH 03/52] docs: fix sub-section numbering to match parent phase
 headings

---
 docs/roadmap/ROADMAP.md | 52 ++++++++++++++++++++---------------------
 1 file changed, 26 insertions(+), 26 deletions(-)

diff --git a/docs/roadmap/ROADMAP.md b/docs/roadmap/ROADMAP.md
index d37c9506..3f0c2abe 100644
--- a/docs/roadmap/ROADMAP.md
+++ b/docs/roadmap/ROADMAP.md
@@ -205,7 +205,7 @@ Support querying multiple codebases from a single MCP server instance.
 
 **Goal:** Build a comprehensive analysis toolkit on top of the graph -- complexity metrics, community detection, risk triage, architecture boundary enforcement, CI validation, and hybrid search. This phase emerged organically as features were needed and wasn't in the original roadmap.
 
-### 2.6.1 -- Complexity Metrics ✅
+### 2.5.1 -- Complexity Metrics ✅
 
 Per-function complexity analysis using language-specific AST rules.
 
@@ -219,7 +219,7 @@ Per-function complexity analysis using language-specific AST rules.
 
 **New file:** `src/complexity.js` (2,163 lines)
 
-### 2.6.2 -- Community Detection & Drift ✅
+### 2.5.2 -- Community Detection & Drift ✅
 
 Louvain community detection at file or function level.
 
@@ -230,7 +230,7 @@ Louvain community detection at file or function level.
 
 **New file:** `src/communities.js` (310 lines)
 
-### 2.6.3 -- Structure & Role Classification ✅
+### 2.5.3 -- Structure & Role Classification ✅
 
 Directory structure graph with node role classification.
 
@@ -243,7 +243,7 @@ Directory structure graph with node role classification.
 
 **New file:** `src/structure.js` (668 lines)
 
-### 2.6.4 -- Execution Flow Tracing ✅
+### 2.5.4 -- Execution Flow Tracing ✅
 
 Forward BFS from framework entry points through callees to leaves.
 
@@ -253,7 +253,7 @@ Forward BFS from framework entry points through callees to leaves.
 
 **New file:** `src/flow.js` (362 lines)
 
-### 2.6.5 -- Temporal Coupling (Co-change Analysis) ✅
+### 2.5.5 -- Temporal Coupling (Co-change Analysis) ✅
 
 Git history analysis for temporal file coupling.
 
@@ -264,7 +264,7 @@ Git history analysis for temporal file coupling.
 
 **New file:** `src/cochange.js` (502 lines)
 
-### 2.6.6 -- Manifesto Rule Engine ✅
+### 2.5.6 -- Manifesto Rule Engine ✅
 
 Configurable rule engine with warn/fail thresholds for function, file, and graph rules.
 
@@ -276,7 +276,7 @@ Configurable rule engine with warn/fail thresholds for function, file, and graph
 
 **New file:** `src/manifesto.js` (511 lines)
 
-### 2.6.7 -- Architecture Boundary Rules ✅
+### 2.5.7 -- Architecture Boundary Rules ✅
 
 Architecture enforcement using glob patterns and presets.
 
@@ -287,7 +287,7 @@ Architecture enforcement using glob patterns and presets.
 
 **New file:** `src/boundaries.js` (347 lines)
 
-### 2.6.8 -- CI Validation Predicates (`check`) ✅
+### 2.5.8 -- CI Validation Predicates (`check`) ✅
 
 Structured pass/fail checks for CI pipelines.
 
@@ -301,7 +301,7 @@ Structured pass/fail checks for CI pipelines.
 
 **New file:** `src/check.js` (433 lines)
 
-### 2.6.9 -- Composite Analysis Commands ✅
+### 2.5.9 -- Composite Analysis Commands ✅
 
 High-level commands that compose multiple analysis steps.
 
@@ -311,7 +311,7 @@ High-level commands that compose multiple analysis steps.
 
 **New files:** `src/audit.js` (424 lines), `src/batch.js` (91 lines), `src/triage.js` (274 lines)
 
-### 2.6.10 -- Hybrid Search ✅
+### 2.5.10 -- Hybrid Search ✅
 
 BM25 keyword search + semantic vector search with RRF fusion.
 
@@ -323,7 +323,7 @@ BM25 keyword search + semantic vector search with RRF fusion.
 
 **Affected file:** `src/embedder.js` (grew from 525 -> 1,113 lines)
 
-### 2.6.11 -- Supporting Infrastructure ✅
+### 2.5.11 -- Supporting Infrastructure ✅
 
 Cross-cutting utilities added during the expansion.
 
@@ -335,7 +335,7 @@ Cross-cutting utilities added during the expansion.
 - ✅ **Journal:** change journal validation/management (`src/journal.js`, 110 lines)
 - ✅ **Update Check:** npm registry polling with 24h cache (`src/update-check.js`, 161 lines)
 
-### 2.6.12 -- MCP Tool Expansion ✅
+### 2.5.12 -- MCP Tool Expansion ✅
 
 MCP grew from 12 -> 25 tools, covering all new analysis capabilities.
 
@@ -367,7 +367,7 @@ MCP grew from 12 -> 25 tools, covering all new analysis capabilities.
 
 **Goal:** Add deeper static analysis capabilities (dataflow, control flow graphs, AST querying), enrich the graph model with sub-declaration node types and structural edges, refactor extractors into per-language modules, consolidate the CLI surface area, and introduce interactive visualization. This phase emerged from competitive analysis against Joern and Narsil-MCP.
 
-### 2.8.1 -- Dataflow Analysis ✅
+### 2.7.1 -- Dataflow Analysis ✅
 
 Define-use chain extraction tracking how data flows between functions.
 
@@ -384,7 +384,7 @@ Define-use chain extraction tracking how data flows between functions.
 
 **New file:** `src/dataflow.js` (1,187 lines)
 
-### 2.8.2 -- Expanded Node Types (Phase 1) ✅
+### 2.7.2 -- Expanded Node Types (Phase 1) ✅
 
 Extend the graph model with sub-declaration node kinds.
 
@@ -398,7 +398,7 @@ Extend the graph model with sub-declaration node kinds.
 
 **Affected files:** All extractors, `src/builder.js`, `src/queries.js`, `src/db.js`
 
-### 2.8.3 -- Expanded Edge Types (Phase 2) ✅
+### 2.7.3 -- Expanded Edge Types (Phase 2) ✅
 
 Structural edges for richer graph relationships.
 
@@ -409,7 +409,7 @@ Structural edges for richer graph relationships.
 
 **Affected files:** `src/builder.js`, `src/queries.js`
 
-### 2.8.4 -- Intraprocedural Control Flow Graph (CFG) ✅
+### 2.7.4 -- Intraprocedural Control Flow Graph (CFG) ✅
 
 Basic-block control flow graph construction from function ASTs.
 
@@ -424,7 +424,7 @@ Basic-block control flow graph construction from function ASTs.
 
 **New file:** `src/cfg.js` (1,451 lines)
 
-### 2.8.5 -- Stored Queryable AST Nodes ✅
+### 2.7.5 -- Stored Queryable AST Nodes ✅
 
 Persist and query selected AST node types for pattern-based codebase exploration.
 
@@ -439,7 +439,7 @@ Persist and query selected AST node types for pattern-based codebase exploration
 
 **New file:** `src/ast.js` (392 lines)
 
-### 2.8.6 -- Extractors Refactoring ✅
+### 2.7.6 -- Extractors Refactoring ✅
 
 Split per-language extractors from monolithic `parser.js` into dedicated modules.
 
@@ -453,7 +453,7 @@ Split per-language extractors from monolithic `parser.js` into dedicated modules
 
 **New directory:** `src/extractors/`
 
-### 2.8.7 -- normalizeSymbol Utility ✅
+### 2.7.7 -- normalizeSymbol Utility ✅
 
 Stable JSON schema for symbol output across all query functions.
 
@@ -463,7 +463,7 @@ Stable JSON schema for symbol output across all query functions.
 
 **Affected file:** `src/queries.js`
 
-### 2.8.8 -- Interactive Graph Viewer ✅
+### 2.7.8 -- Interactive Graph Viewer ✅
 
 Self-contained HTML visualization with vis-network.
 
@@ -480,7 +480,7 @@ Self-contained HTML visualization with vis-network.
 
 **New file:** `src/viewer.js` (948 lines)
 
-### 2.8.9 -- Exports Command ✅
+### 2.7.9 -- Exports Command ✅
 
 Per-symbol consumer analysis for file exports.
 
@@ -491,7 +491,7 @@ Per-symbol consumer analysis for file exports.
 
 **Affected file:** `src/queries.js`
 
-### 2.8.10 -- Export Format Expansion ✅
+### 2.7.10 -- Export Format Expansion ✅
 
 Three new graph export formats for external tooling integration.
 
@@ -501,7 +501,7 @@ Three new graph export formats for external tooling integration.
 
 **Affected file:** `src/export.js` (681 lines)
 
-### 2.8.11 -- CLI Consolidation ✅
+### 2.7.11 -- CLI Consolidation ✅
 
 First CLI surface area reduction -- 5 commands merged into existing ones.
 
@@ -514,7 +514,7 @@ First CLI surface area reduction -- 5 commands merged into existing ones.
 
 **Affected file:** `src/cli.js`
 
-### 2.8.12 -- MCP Tool Consolidation & Expansion ✅
+### 2.7.12 -- MCP Tool Consolidation & Expansion ✅
 
 MCP tools were both consolidated and expanded, resulting in a net change from 25 → 30 tools (31 in multi-repo mode).
 
@@ -542,7 +542,7 @@ Plus updated enums on existing tools (edge_kinds, symbol kinds).
 
 ### 2.7 Summary
 
-| Metric | Before (v2.7.0) | After (v3.0.0) | Delta |
+| Metric | Before (v2.7.0 baseline) | After (v3.0.0) | Delta |
 |--------|-----------------|-----------------|-------|
 | Source modules | 35 | 50 | +15 |
 | Total source lines | 17,830 | 26,277 | +47% |
@@ -1680,7 +1680,7 @@ LLM-generated docstrings aware of callers, callees, and types. Diff-aware: only
 
 ### 11.1 -- Interactive Web Visualization (Partially Complete)
 
-> **Phase 2.7 progress:** `codegraph plot` (Phase 2.8.8) ships a self-contained HTML viewer with vis-network. It supports layout switching, color/size/cluster overlays, drill-down, community detection, and a detail panel. The remaining work is the server-based experience below.
+> **Phase 2.7 progress:** `codegraph plot` (Phase 2.7.8) ships a self-contained HTML viewer with vis-network. It supports layout switching, color/size/cluster overlays, drill-down, community detection, and a detail panel. The remaining work is the server-based experience below.
 
 ```bash
 codegraph viz

From 2fce6905fb3d69485b0aa2d5adf6ad3580ef106e Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 16 Mar 2026 23:22:57 -0600
Subject: [PATCH 04/52] fix: align version computation between publish.yml and
 bench-version.js

- Add COMMITS=0 guard in publish.yml to return clean version when HEAD
  is exactly at a tag (mirrors bench-version.js early return)
- Change bench-version.js to use PATCH+1-dev.COMMITS format instead of
  PATCH+COMMITS-dev.SHA (mirrors publish.yml's new scheme)
- Fix fallback in bench-version.js to use dev.1 matching publish.yml's
  no-tags COMMITS=1 default

Impact: 1 functions changed, 0 affected
---
 .github/workflows/publish.yml |  8 +++++---
 scripts/bench-version.js      | 19 ++++++-------------
 2 files changed, 11 insertions(+), 16 deletions(-)

diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml
index a6538d19..81a70e52 100644
--- a/.github/workflows/publish.yml
+++ b/.github/workflows/publish.yml
@@ -77,9 +77,11 @@ jobs:
               COMMITS=1
               IFS='.' read -r MAJOR MINOR PATCH <<< "$CURRENT"
             fi
-            DEV_PATCH=$((PATCH + COMMITS))
-            SHORT_SHA=$(echo "${{ github.sha }}" | cut -c1-7)
-            VERSION="${MAJOR}.${MINOR}.${DEV_PATCH}-dev.${SHORT_SHA}"
+            if [ "$COMMITS" -eq 0 ]; then
+              VERSION="${MAJOR}.${MINOR}.${PATCH}"
+            else
+              VERSION="${MAJOR}.${MINOR}.$((PATCH + 1))-dev.${COMMITS}"
+            fi
             NPM_TAG="dev"
             echo "Dev release: $VERSION (${COMMITS} commits since ${RELEASE_TAG:-none})"
           fi
diff --git a/scripts/bench-version.js b/scripts/bench-version.js
index accc7a8b..7fd2f84e 100644
--- a/scripts/bench-version.js
+++ b/scripts/bench-version.js
@@ -6,8 +6,8 @@
  *   2. `git rev-list <tag>..HEAD --count` → count commits since that tag
  *
  * - If HEAD is exactly tagged (0 commits): returns "2.5.0"
- * - Otherwise: returns "2.5.N-dev.hash" (e.g. "2.5.3-dev.c50f7f5")
- *   where N = PATCH + commits since tag, hash = short commit SHA
+ * - Otherwise: returns "2.5.(PATCH+1)-dev.COMMITS" (e.g. "2.5.3-dev.45")
+ *   where COMMITS = number of commits since the tag
  *
  * This prevents dev/dogfood benchmark runs from overwriting release data
  * in the historical benchmark reports (which deduplicate by version).
@@ -38,24 +38,17 @@ export function getBenchmarkVersion(pkgVersion, cwd) {
 		// Exact tag (0 commits since tag): return clean release version
 		if (commits === 0) return `${major}.${minor}.${patch}`;
 
-		// Dev build: MAJOR.MINOR.(PATCH+COMMITS)-dev.SHORT_SHA
-		const hash = execFileSync('git', ['rev-parse', '--short', 'HEAD'], { cwd, ...GIT_OPTS }).trim();
-		const devPatch = Number(patch) + commits;
-		return `${major}.${minor}.${devPatch}-dev.${hash}`;
+		// Dev build: MAJOR.MINOR.(PATCH+1)-dev.COMMITS
+		return `${major}.${minor}.${Number(patch) + 1}-dev.${commits}`;
 	} catch {
 		/* git not available or no tags */
 	}
 
-	// Fallback: no git or no tags — match publish.yml's no-tags behavior (PATCH+1-dev.SHA)
+	// Fallback: no git or no tags — match publish.yml's no-tags behavior (COMMITS=1)
 	const parts = pkgVersion.split('.');
 	if (parts.length === 3) {
 		const [major, minor, patch] = parts;
-		try {
-			const hash = execFileSync('git', ['rev-parse', '--short', 'HEAD'], { cwd, ...GIT_OPTS }).trim();
-			return `${major}.${minor}.${Number(patch) + 1}-dev.${hash}`;
-		} catch {
-			return `${major}.${minor}.${Number(patch) + 1}-dev`;
-		}
+		return `${major}.${minor}.${Number(patch) + 1}-dev.1`;
 	}
 	return `${pkgVersion}-dev`;
 }

From 3b6dccf482a3366b9c2851d7b20fe5069d485267 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Tue, 17 Mar 2026 04:47:43 -0600
Subject: [PATCH 05/52] feat: auto-detect semver bump in /release skill when no
 version provided

The release skill now scans commit history using conventional commit
rules to determine major/minor/patch automatically. Explicit version
argument still works as before.
---
 .claude/skills/release/SKILL.md | 50 +++++++++++++++++++++++++--------
 1 file changed, 39 insertions(+), 11 deletions(-)

diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md
index a05c2f9b..5df0febd 100644
--- a/.claude/skills/release/SKILL.md
+++ b/.claude/skills/release/SKILL.md
@@ -1,27 +1,55 @@
 ---
 name: release
 description: Prepare a codegraph release — bump versions, update CHANGELOG, ROADMAP, BACKLOG, README, create PR
-argument-hint: <version e.g. 3.1.1>
+argument-hint: "[version e.g. 3.1.1]  (optional — auto-detects from commits)"
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Agent
 ---
 
-# Release v$ARGUMENTS
+# Release
 
-You are preparing a release for `@optave/codegraph` version **$ARGUMENTS**.
+You are preparing a release for `@optave/codegraph`.
+
+**Version argument:** `$ARGUMENTS`
+- If a version was provided (e.g. `3.1.1`), use it as the target version.
+- If no version was provided (empty or blank `$ARGUMENTS`), you will auto-detect it in Step 1b.
 
 ---
 
-## Step 1: Gather context
+## Step 1a: Gather context
 
 Run these in parallel:
-1. `git log --oneline v<previous-tag>..HEAD` — all commits since the last release tag
+1. `git log --oneline v<previous-tag>..HEAD` — all commits since the last release tag (use `git describe --tags --match "v*" --abbrev=0` to find the previous tag)
 2. Read `CHANGELOG.md` (first 80 lines) — understand the format
 3. Read `package.json` — current version
 4. `git describe --tags --match "v*" --abbrev=0` — find the previous stable release tag
 
+## Step 1b: Determine version (if not provided)
+
+If `$ARGUMENTS` is empty or blank, determine the semver bump from the commits gathered in Step 1a.
+
+Scan **every commit message** between the last tag and HEAD. Apply these rules in priority order:
+
+| Condition | Bump |
+|-----------|------|
+| Any commit has a `BREAKING CHANGE:` or `BREAKING-CHANGE:` footer, **or** uses the `!` suffix (e.g. `feat!:`, `fix!:`, `refactor!:`) | **major** |
+| Any commit uses `feat:` or `feat(scope):` | **minor** |
+| Everything else (`fix:`, `refactor:`, `perf:`, `chore:`, `docs:`, `test:`, `ci:`, etc.) | **patch** |
+
+Given the current version `MAJOR.MINOR.PATCH` from `package.json`, compute the new version:
+- **major** → `(MAJOR+1).0.0`
+- **minor** → `MAJOR.(MINOR+1).0`
+- **patch** → `MAJOR.MINOR.(PATCH+1)`
+
+Print the detected bump reason and the resolved version, e.g.:
+> Detected **minor** bump (found `feat:` commits). Version: 3.1.0 → **3.2.0**
+
+Use the resolved version as `VERSION` for all subsequent steps.
+
+If `$ARGUMENTS` was provided, use it directly as `VERSION`.
+
 ## Step 2: Bump version in package.json
 
-Edit `package.json` to set `"version": "$ARGUMENTS"`.
+Edit `package.json` to set `"version": "VERSION"`.
 
 **Do NOT bump:**
 - `crates/codegraph-core/Cargo.toml` — synced automatically by `scripts/sync-native-versions.js` during the publish workflow
@@ -104,16 +132,16 @@ Run `grep` to confirm the new version appears in `package-lock.json` and that al
 
 ## Step 8: Create branch, commit, push, PR
 
-1. Create branch: `git checkout -b release/$ARGUMENTS`
+1. Create branch: `git checkout -b release/VERSION`
 2. Stage only the files you changed: `CHANGELOG.md`, `package.json`, `package-lock.json`, `docs/roadmap/ROADMAP.md`, `docs/roadmap/BACKLOG.md` if changed, `README.md` if changed
-3. Commit: `chore: release v$ARGUMENTS`
-4. Push: `git push -u origin release/$ARGUMENTS`
+3. Commit: `chore: release vVERSION`
+4. Push: `git push -u origin release/VERSION`
 5. Create PR:
 
 ```
-gh pr create --title "chore: release v$ARGUMENTS" --body "$(cat <<'EOF'
+gh pr create --title "chore: release vVERSION" --body "$(cat <<'EOF'
 ## Summary
-- Bump version to $ARGUMENTS
+- Bump version to VERSION
 - Add CHANGELOG entry for all commits since previous release
 - Update ROADMAP progress
 

From b0e5c30fafc3efb18c35f7bfb33db312f959cadc Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sat, 21 Mar 2026 02:38:42 -0600
Subject: [PATCH 06/52] feat: add /titan-run orchestrator with diff review,
 semantic assertions, and architectural snapshot
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add /titan-run skill that dispatches the full Titan pipeline (recon → gauntlet →
sync → forge) to sub-agents with fresh context windows, enabling end-to-end
autonomous execution.

Hardening layers added across the pipeline:
- Pre-Agent Gate (G1-G4): git health, worktree validity, state integrity, backups
- Post-phase validation (V1-V15): artifact structure, coverage, consistency checks
- Stall detection with per-phase thresholds and no-progress abort
- Mandatory human checkpoint before forge (unless --yes)

New validation tools integrated into forge and gate:
- Diff Review Agent (forge Step 9): verifies each diff matches the gauntlet
  recommendation and sync plan intent before gate runs
- Semantic Assertions (gate Step 5): export signature stability, import resolution
  integrity, dependency direction, re-export chain validation
- Architectural Snapshot Comparator (gate Step 5.5): community stability, cross-domain
  dependency direction, cohesion delta, drift detection vs pre-forge baseline
---
 .claude/skills/titan-forge/SKILL.md           | 293 +++++++++
 .claude/skills/titan-gate/SKILL.md            | 126 +++-
 .claude/skills/titan-run/SKILL.md             | 574 ++++++++++++++++++
 docs/examples/claude-code-skills/README.md    |  44 +-
 .../claude-code-skills/titan-forge/SKILL.md   | 293 +++++++++
 .../claude-code-skills/titan-gate/SKILL.md    | 126 +++-
 .../claude-code-skills/titan-run/SKILL.md     | 574 ++++++++++++++++++
 docs/use-cases/titan-paradigm.md              |  27 +-
 8 files changed, 2022 insertions(+), 35 deletions(-)
 create mode 100644 .claude/skills/titan-forge/SKILL.md
 create mode 100644 .claude/skills/titan-run/SKILL.md
 create mode 100644 docs/examples/claude-code-skills/titan-forge/SKILL.md
 create mode 100644 docs/examples/claude-code-skills/titan-run/SKILL.md

diff --git a/.claude/skills/titan-forge/SKILL.md b/.claude/skills/titan-forge/SKILL.md
new file mode 100644
index 00000000..44c4c36b
--- /dev/null
+++ b/.claude/skills/titan-forge/SKILL.md
@@ -0,0 +1,293 @@
+---
+name: titan-forge
+description: Execute the sync.json plan — refactor code, validate with /titan-gate, commit, and advance state (Titan Paradigm Phase 4)
+argument-hint: <--phase N> <--target name> <--dry-run>
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Skill, Agent
+---
+
+# Titan FORGE — Execute Sync Plan
+
+You are running the **FORGE** phase of the Titan Paradigm.
+
+Your goal: read `sync.json`, find the next incomplete execution phase, make the actual code changes for each target, validate with `/titan-gate`, commit, and advance state.
+
+> **Context budget:** One phase per invocation. Do not attempt all phases in one session — the context window will fill. Run one phase, report, stop. User re-runs for the next phase.
+
+**Arguments** (from `$ARGUMENTS`):
+- No args → run next incomplete phase
+- `--phase N` → jump to specific phase
+- `--target <name>` → run single target only (for retrying failures)
+- `--dry-run` → show what would be done without changing code
+
+---
+
+## Step 0 — Pre-flight
+
+1. **Worktree check:**
+   ```bash
+   git rev-parse --show-toplevel && git worktree list
+   ```
+   If not in a worktree, stop: "Run `/worktree` first."
+
+2. **Sync with main:**
+   ```bash
+   git fetch origin main && git merge origin/main --no-edit
+   ```
+   If there are merge conflicts, stop: "Merge conflict detected. Resolve conflicts and re-run `/titan-forge`."
+
+3. **Load artifacts.** Read:
+   - `.codegraph/titan/sync.json` — execution plan (if missing: "Run `/titan-sync` first.")
+   - `.codegraph/titan/titan-state.json` — current state
+   - `.codegraph/titan/gauntlet.ndjson` — per-target audit details
+   - `.codegraph/titan/gauntlet-summary.json` — aggregated results
+
+4. **Validate state.** If `titan-state.json` has `currentPhase` other than `"sync"` and no existing `execution` block, stop: "State not ready. Run `/titan-sync` first."
+
+5. **Initialize execution state** (if first run). Add to `titan-state.json`:
+   ```json
+   {
+     "execution": {
+       "currentPhase": 1,
+       "completedPhases": [],
+       "currentTarget": null,
+       "completedTargets": [],
+       "failedTargets": [],
+       "commits": []
+     }
+   }
+   ```
+
+6. **Determine next phase.** Use `--phase N` if provided, otherwise find the lowest phase number not in `completedPhases`.
+
+7. **Print plan:**
+   > Phase N: \<label\> — N targets, estimated N commits
+
+8. **Ask for confirmation** before starting (unless `$ARGUMENTS` contains `--yes`).
+
+---
+
+## Step 1 — Phase-specific execution strategies
+
+Each phase type requires different code-change logic:
+
+### Phase 1: Dead code cleanup
+- Delete the symbol/export
+- Verify no consumers: `codegraph fn-impact <target> -T --json`
+- Remove any orphaned imports
+- Run lint to clean up
+
+### Phase 2: Shared abstractions
+- Extract function/interface to new or existing file
+- Update imports in all consumers
+- Verify with: `codegraph exports <file> -T --json`
+
+### Phase 3: Empty catches / error handling
+- Replace `catch {}` with `catch (e) { logger.debug(...) }` or explicit fallback
+- Use contextually appropriate error handling
+- Subphases: each distinct catch pattern = one commit
+
+### Phase 4: Extractor decomposition
+- Split large `walkXNode` switch cases into handler functions
+- Keep dispatcher thin — handler per node kind
+- Subphases: each extractor = one commit
+
+### Phase 5: General decomposition
+- Read the gauntlet recommendation for the specific target
+- Apply the recommended decomposition strategy
+- Subphases: each function split = one commit
+
+### Phase 6: Small FAIL fixes
+- Read the gauntlet recommendation for the specific target
+- Apply the recommended fix (complexity reduction, metric improvement)
+- Group by domain where possible
+
+---
+
+## Step 2 — Per-target execution loop
+
+For each target in the current phase:
+
+1. **Skip if done.** Check if target is already in `execution.completedTargets`. If so, skip.
+
+2. **Update state.** Set `execution.currentTarget` in `titan-state.json`.
+
+3. **Read gauntlet entry.** Find this target in `gauntlet.ndjson` → get recommendation, violations, metrics.
+
+4. **Understand before touching.** Run codegraph commands:
+   ```bash
+   codegraph context <target> -T --json
+   ```
+   If blast radius > 0:
+   ```bash
+   codegraph fn-impact <target> -T --json
+   ```
+
+5. **Check if already fixed.** If the file has changed since gauntlet ran, re-check metrics:
+   ```bash
+   codegraph complexity --file <file> --health -T --json
+   ```
+   If the target now passes all thresholds, skip with note: "Target already passes — skipping."
+
+6. **Read source file(s).** Understand the code before editing.
+
+7. **Apply the change** based on phase strategy (Step 1) + gauntlet recommendation.
+
+8. **Stage changed files:**
+   ```bash
+   git add <specific changed files>
+   ```
+
+9. **Diff review (intent verification):**
+   Before running gate or tests, verify the diff matches the intent. This catches cases where the code change is structurally valid but doesn't match what was planned.
+
+   Collect the context:
+   ```bash
+   git diff --cached --stat
+   git diff --cached
+   ```
+
+   Load the gauntlet entry for this target (from `gauntlet.ndjson`) and the sync plan entry (from `sync.json → executionOrder[currentPhase]`).
+
+   **Check all of the following:**
+
+   **D1. Scope — only planned files touched:**
+   Compare staged file paths against `sync.json → executionOrder[currentPhase].targets` and their known file paths (from gauntlet entries). Flag any file NOT associated with the current target or phase.
+   - File in a completely different domain → **DIFF FAIL**
+   - File is a direct dependency of the target (consumer or import) → **OK** (expected ripple)
+   - Test file for the target → **OK**
+
+   **D2. Intent match — diff aligns with gauntlet recommendation:**
+   Read the gauntlet entry's `recommendation` field and `violations` list. Verify the diff addresses them:
+   - If recommendation says "split" → diff should show new functions extracted, original simplified
+   - If recommendation says "remove dead code" → diff should show deletions, not additions
+   - If violation was "complexity > threshold" → diff should reduce complexity, not just move code around
+   - If the diff does something **entirely different** from the recommendation → **DIFF FAIL**
+
+   **D3. Commit message accuracy:**
+   Compare the planned commit message from `sync.json` against what the diff actually does.
+   - Message says "remove dead code" but diff adds new functions → **DIFF WARN**
+   - Message says "extract X from Y" but diff only modifies Y without creating X → **DIFF FAIL**
+
+   **D4. Deletion audit:**
+   If the diff deletes code (lines removed > 10):
+   ```bash
+   codegraph fn-impact <deleted-symbol> -T --json 2>/dev/null
+   ```
+   If the deleted symbol has active callers not updated in this diff → **DIFF FAIL**: "Deleted <symbol> still has <N> callers not updated in this commit."
+
+   **D5. Leftover check:**
+   If the gauntlet recommendation mentioned specific symbols to remove/refactor, verify they were actually addressed:
+   - Dead symbols listed for removal → should be deleted in the diff
+   - Functions marked for decomposition → original should be simplified or removed
+
+   **On DIFF FAIL:** Unstage and revert changes, add to `execution.failedTargets` with reason starting with `"diff-review: "`. Continue to next target.
+   **On DIFF WARN:** Log the warning but proceed to gate. Include the warning in the gate-log entry.
+
+10. **Run tests:**
+    ```bash
+    npm test 2>&1
+    ```
+    If tests fail → go to rollback (step 13).
+
+11. **Run /titan-gate:**
+    Use the Skill tool to invoke `titan-gate`. If FAIL → go to rollback (step 13).
+
+12. **On success:**
+    ```bash
+    git commit -m "<commit message from sync.json>"
+    ```
+    - Record commit SHA in `execution.commits`
+    - Add target to `execution.completedTargets`
+    - Record any diff-review warnings in `execution.diffWarnings` (if any)
+    - Update `titan-state.json`
+
+13. **On failure (test, gate, or diff-review):**
+    ```bash
+    git checkout -- <changed files>
+    ```
+    - Add to `execution.failedTargets` with reason: `{ "target": "<name>", "reason": "<why>", "phase": N }`
+    - Clear `execution.currentTarget`
+    - **Continue to next target** — don't block the whole phase
+
+---
+
+## Step 3 — Phase completion
+
+When all targets in the phase are processed:
+
+1. Add phase number to `execution.completedPhases`
+2. Advance `execution.currentPhase` to the next phase number
+3. Clear `execution.currentTarget`
+4. Write updated `titan-state.json`
+
+---
+
+## Step 4 — Report
+
+Print:
+
+```
+## Phase N Complete: <label>
+
+Targets: X/Y completed, Z failed
+Commits: N
+Files changed: N
+
+### Failed targets (if any):
+- <target>: <reason>
+
+### Next: Phase M — <label> (N targets)
+Run /titan-forge to continue.
+```
+
+If all phases are complete:
+
+```
+## All phases complete
+
+Total commits: N
+Total targets: X completed, Y failed
+Failed targets: <list or "none">
+
+Run /titan-gate on the full branch to validate.
+```
+
+---
+
+## Edge Cases
+
+- **Test failure mid-phase:** Revert target, mark failed, continue. Don't block the whole phase.
+- **Merge conflict with main:** Stop, report, ask user to resolve.
+- **Gate detects new cycle:** Stop immediately — this is a real problem, not skippable.
+- **Target already fixed on main:** Check if file has changed since gauntlet. If metrics now pass, skip with note.
+- **Interrupted mid-phase:** Re-running picks up from `execution.currentTarget`. Already-committed targets are skipped.
+- **`--dry-run`:** Walk through all targets, print what would be done (phase strategy, gauntlet recommendation, files affected), but make no changes.
+- **`--target <name>`:** Run only that target. Useful for retrying entries in `failedTargets`.
+
+---
+
+## Rules
+
+- **One phase per invocation.** Stop after the phase completes. User re-runs for next.
+- **Resumable.** If interrupted, re-running picks up where it left off.
+- **Always use `--json` and `-T`** for codegraph commands.
+- **Gate before commit.** Every commit must pass `/titan-gate`. No exceptions.
+- **One commit per logical unit.** Use commit messages from `sync.json`.
+- **Stage only specific files.** Never `git add .` or `git add -A`.
+- **Rollback on failure is gentle** — `git checkout -- <files>`, not `git reset --hard`.
+- **Subphase awareness** — phases 3-6 have subphases. Each subphase = one commit. Track at subphase level.
+- **Never skip `/titan-gate`.** Even for "trivial" changes.
+
+## Relationship to Other Skills
+
+| Skill | Produces | Used by /titan-forge |
+|-------|----------|---------------------|
+| `/titan-recon` | `titan-state.json`, `GLOBAL_ARCH.md` | State tracking, domain context |
+| `/titan-gauntlet` | `gauntlet.ndjson`, `gauntlet-summary.json` | Per-target recommendations |
+| `/titan-sync` | `sync.json` | Execution plan (phases, targets, commits) |
+| `/titan-gate` | Gate verdict | Called per-commit for validation |
+| `/titan-reset` | Clean slate | Removes all artifacts |
+
+## Self-Improvement
+
+This skill lives at `.claude/skills/titan-forge/SKILL.md`. Edit if phase strategies need refinement or execution loop needs adjustment after dogfooding.
diff --git a/.claude/skills/titan-gate/SKILL.md b/.claude/skills/titan-gate/SKILL.md
index c1d7c359..3c8c0c95 100644
--- a/.claude/skills/titan-gate/SKILL.md
+++ b/.claude/skills/titan-gate/SKILL.md
@@ -111,7 +111,114 @@ If any fail → overall verdict is FAIL → proceed to auto-rollback.
 
 ---
 
-## Step 5 — Branch structural diff
+## Step 5 — Semantic assertions (API compatibility)
+
+Verify that code changes don't silently break callers by changing public contracts. This goes beyond structural checks — it catches signature changes, removed exports, and new forbidden dependencies.
+
+### 5a. Export signature stability
+
+Get the list of changed files from diff-impact (Step 1):
+
+```bash
+codegraph exports <changed-file> -T --json
+```
+
+For each **exported** symbol in changed files:
+- Check if the symbol existed before this change: `git show HEAD:<file>` and compare function signatures
+- If a function's **parameter list changed** (added required params, removed params, changed types):
+  ```bash
+  codegraph fn-impact <symbol> -T --json
+  ```
+  Count callers. If callers > 0 and callers are NOT also staged → **FAIL**: "Signature change in `<symbol>` breaks <N> callers not updated in this commit: <caller list>"
+- If an **export was removed entirely** and callers exist → **FAIL**: "Removed export `<symbol>` still imported by <N> files"
+
+### 5b. Import resolution integrity
+
+Verify that all imports still resolve after the change:
+
+```bash
+codegraph check --staged -T --json
+```
+
+If any `unresolved_import` warnings appear for files NOT changed in this commit → **FAIL**: "Change broke import resolution for <file>: <import>"
+
+### 5c. Dependency direction assertions
+
+From diff-impact, extract any **new** edges (imports that didn't exist before):
+
+```bash
+codegraph diff-impact --staged -T --json
+```
+
+For each new dependency:
+- Check against `GLOBAL_ARCH.md` layer rules (if Titan artifacts exist)
+- Check against `codegraph check --boundaries -T --json`
+- New dependency from a lower layer to a higher layer → **FAIL**: "New upward dependency: `<source>` → `<target>` violates layer boundary"
+- New dependency on a module flagged in sync.json as "to be removed" or "to be split" → **WARN**: "New dependency on `<module>` which is scheduled for decomposition"
+
+### 5d. Re-export chain validation
+
+If the change modifies an index/barrel file (e.g., `index.js`, `mod.rs`):
+
+```bash
+codegraph exports <barrel-file> -T --json
+```
+
+Compare export count before and after. If exports were **accidentally dropped** (count decreased and the removed exports have callers) → **FAIL**.
+
+---
+
+## Step 5.5 — Architectural snapshot comparison
+
+Compare the codebase's architectural properties before and after this change. This catches "technically correct but architecturally wrong" changes — e.g., a valid refactor that puts code in the wrong layer.
+
+### Load pre-forge snapshot
+
+Read `.codegraph/titan/arch-snapshot.json` if it exists (created by `/titan-run` before forge begins). If missing, skip this step — it only works within the orchestrated pipeline.
+
+### Capture current state
+
+```bash
+codegraph communities -T --json > /tmp/titan-arch-current-communities.json
+codegraph structure --depth 2 --json > /tmp/titan-arch-current-structure.json
+codegraph communities --drift -T --json > /tmp/titan-arch-current-drift.json
+```
+
+### Compare
+
+**A1. Community stability:**
+Compare community assignments between snapshot and current. For each symbol that **moved** to a different community:
+- If the symbol was the target of this forge phase → **OK** (expected)
+- If the symbol was NOT touched in the diff → **WARN**: "Symbol `<name>` shifted from community <X> to <Y> as a side effect"
+- If > 5 untouched symbols shifted communities → **FAIL**: "Significant community restructuring detected — <N> symbols shifted communities. This change may have unintended architectural impact."
+
+**A2. Dependency direction between domains:**
+From `GLOBAL_ARCH.md`, extract the expected dependency direction between domains (e.g., "presentation depends on features, not the reverse").
+
+Check if any new cross-domain dependency violates the expected direction:
+```bash
+codegraph deps <changed-file> --json
+```
+- New upward dependency (lower layer importing higher layer) not present in snapshot → **FAIL**
+- New lateral dependency within the same layer → **OK**
+
+**A3. Cohesion delta:**
+Compare directory cohesion scores from `structure`:
+- If any directory's cohesion dropped by > 0.2 → **WARN**: "Directory `<dir>` cohesion dropped from <X> to <Y>"
+- If a directory went from above 0.5 to below 0.3 → **FAIL**: "Directory `<dir>` became tangled (cohesion <X> → <Y>)"
+
+**A4. New drift warnings:**
+Compare drift warnings between snapshot and current:
+- New drift warning not in snapshot → **WARN** with details
+- Drift warning resolved → note as positive
+
+### Verdict integration
+
+Architectural failures are reported as part of the overall gate verdict. They participate in the PASS/WARN/FAIL aggregation like all other checks.
+
+---
+
+## Step 6 — Branch structural diff
 
 ```bash
 codegraph branch-compare main HEAD -T --json
@@ -121,7 +228,7 @@ Cumulative structural impact of all changes on this branch (broader than `diff-i
 
 ---
 
-## Step 6 — Sync plan alignment
+## Step 7 — Sync plan alignment
 
 If `.codegraph/titan/sync.json` exists:
 - Are changed files part of the current execution phase?
@@ -132,7 +239,7 @@ Advisory — prevents jumping ahead and creating conflicts.
 
 ---
 
-## Step 7 — Blast radius check
+## Step 8 — Blast radius check
 
 From diff-impact results:
 - Transitive blast radius > 30 → FAIL
@@ -141,7 +248,7 @@ From diff-impact results:
 
 ---
 
-## Step 8 — Verdict and auto-rollback
+## Step 9 — Verdict and auto-rollback
 
 Aggregate all checks:
 
@@ -186,7 +293,7 @@ codegraph snapshot delete titan-batch-<N>   # if any remain
 
 ---
 
-## Step 9 — Update state machine
+## Step 10 — Update state machine
 
 Append to `.codegraph/titan/gate-log.ndjson`:
 
@@ -201,6 +308,8 @@ Append to `.codegraph/titan/gate-log.ndjson`:
     "manifesto": "pass|fail",
     "cycles": "pass|fail",
     "complexity": "pass|warn|fail",
+    "semanticAssertions": "pass|warn|fail|skipped",
+    "archSnapshot": "pass|warn|fail|skipped",
     "lint": "pass|fail|skipped",
     "build": "pass|fail|skipped",
     "tests": "pass|fail|skipped",
@@ -215,13 +324,14 @@ Update `titan-state.json` (if exists): increment `progress.fixed`, update `fileA
 
 ---
 
-## Step 10 — Report to user
+## Step 11 — Report to user
 
 **PASS:**
 ```
 GATE PASS — safe to commit
   Changed: 3 functions across 2 files
   Blast radius: 12 transitive callers
+  Structural: pass | Semantic: pass | Architecture: pass
   Lint: pass | Build: pass | Tests: pass
   Complexity: all within thresholds (worst: halstead.bugs 0.3)
 ```
@@ -233,6 +343,8 @@ GATE WARN — review before committing
   Warnings:
   - utils.js historically co-changes with config.js (not staged)
   - parseConfig MI improved 18 → 35 but still below 50
+  - Semantic: new dependency on module scheduled for decomposition
+  - Architecture: directory src/domain/ cohesion dropped 0.6 → 0.45
 ```
 
 **FAIL:**
@@ -240,6 +352,8 @@ GATE WARN — review before committing
 GATE FAIL — changes unstaged, graph restored
   Failures:
   - Tests: 2 suites failed
+  - Semantic: removed export `parseConfig` still imported by 3 files
+  - Architecture: new upward dependency presentation/ → domain/
   - New cycle: parseConfig → loadConfig → parseConfig
   Fix issues, re-stage, re-run /titan-gate
 ```
diff --git a/.claude/skills/titan-run/SKILL.md b/.claude/skills/titan-run/SKILL.md
new file mode 100644
index 00000000..d9127749
--- /dev/null
+++ b/.claude/skills/titan-run/SKILL.md
@@ -0,0 +1,574 @@
+---
+name: titan-run
+description: Run the full Titan Paradigm pipeline end-to-end by dispatching each phase to sub-agents with fresh context windows. Orchestrates recon → gauntlet → sync → forge automatically.
+argument-hint: <path (default: .)> <--skip-recon> <--skip-gauntlet> <--start-from forge> <--gauntlet-batch-size 5> <--yes>
+allowed-tools: Agent, Read, Bash, Glob, Write, Edit
+---
+
+# Titan RUN — End-to-End Pipeline Orchestrator
+
+You are the **orchestrator** for the full Titan Paradigm pipeline. Your job is to dispatch each phase to a **sub-agent** (fresh context window), **validate the results**, and loop phases that require multiple invocations — all without human intervention.
+
+> **You are lightweight.** You do NOT run codegraph commands, audit files, or make code changes yourself. You only: (1) spawn sub-agents, (2) read and validate state files, (3) decide what to run next.
+
+**Arguments** (from `$ARGUMENTS`):
+- No args → full pipeline from scratch, target `.`
+- `<path>` → target path (passed to recon)
+- `--skip-recon` → skip recon (assumes artifacts exist)
+- `--skip-gauntlet` → skip gauntlet (assumes artifacts exist)
+- `--start-from <phase>` → jump to phase: `recon`, `gauntlet`, `sync`, `forge`
+- `--gauntlet-batch-size <N>` → batch size for gauntlet (default: 5)
+- `--yes` → skip confirmation prompts (passed through to forge)
+
+---
+
+## Step 0 — Pre-flight
+
+1. **Worktree check:**
+   ```bash
+   git rev-parse --show-toplevel && git worktree list
+   ```
+   If you are NOT in a worktree, **stop:** "Run `/worktree` first. The Titan pipeline writes artifacts and makes code changes — worktree isolation is required."
+
+2. **Parse arguments.** Determine:
+   - `targetPath` (default: `.`)
+   - `startPhase` (default: `recon`)
+   - `gauntletBatchSize` (default: `5`)
+   - `autoConfirm` (default: `false`)
+
+3. **Check existing state.** Read `.codegraph/titan/titan-state.json` if it exists.
+   - If state exists and `--start-from` not specified, ask user: "Existing Titan state found (phase: `<currentPhase>`). Resume from current state, or start fresh with `/titan-reset` first?"
+   - If `--yes` is set, resume automatically.
+
+4. **Sync with main** (once, before any sub-agent runs):
+   ```bash
+   git fetch origin main && git merge origin/main --no-edit
+   ```
+   If merge conflict → stop: "Merge conflict after syncing with main. Resolve conflicts and re-run `/titan-run`."
+
+5. **Print plan:**
+   ```
+   Titan Pipeline — End-to-End Run
+   Target: <path>
+   Starting from: <phase>
+   Gauntlet batch size: <N>
+
+   Phases: recon → gauntlet (loop) → sync → [PAUSE] → forge (loop)
+   Each phase runs in a sub-agent with a fresh context window.
+   Forge requires explicit confirmation (analysis phases are safe to automate).
+   ```
+
+   If `--yes` is NOT set, ask user to confirm before proceeding.
+
+---
+
+## Pre-Agent Gate (run before EVERY sub-agent dispatch)
+
+Before spawning any sub-agent, run these checks. This catches git state drift, concurrent interference, and corruption left by a crashed agent.
+
+### G1. Git health check
+```bash
+git status --porcelain
+```
+- **Unexpected dirty files** (files not in `.codegraph/titan/`): Print warning with the file list. Ask user to confirm proceeding, or stop. If `--yes`, log the warning and continue — but do NOT stage or commit these files.
+- **Merge conflicts** (lines starting with `UU`, `AA`, `DD`): Stop immediately: "Unresolved merge conflict detected. Resolve before continuing."
+
+### G2. Worktree still valid
+```bash
+git rev-parse --is-inside-work-tree
+```
+If this fails (worktree was pruned or moved), stop: "Worktree is no longer valid. Create a new one with `/worktree`."
+
+### G3. State file integrity
+If `.codegraph/titan/titan-state.json` should exist at this point (i.e., we're past recon):
+```bash
+node -e "try { JSON.parse(require('fs').readFileSync('.codegraph/titan/titan-state.json','utf8')); console.log('OK'); } catch(e) { console.log('CORRUPT: '+e.message); process.exit(1); }"
+```
+- If **CORRUPT** → attempt recovery from backup (see State Backup below). If no backup → stop: "State file corrupted with no backup. Run `/titan-reset` and start over."
+
+### G4. State backup
+Before every sub-agent dispatch, back up the current state file:
+```bash
+cp .codegraph/titan/titan-state.json .codegraph/titan/titan-state.json.bak 2>/dev/null || true
+```
+If a sub-agent corrupts the state, G3 on the next iteration will detect it and restore from `.bak`.
+
+---
+
+## Step 1 — RECON
+
+**Skip if:** `--skip-recon`, `--start-from` is after recon, or `titan-state.json` already has `currentPhase` beyond `"recon"`.
+
+### 1a. Run Pre-Agent Gate (G1-G4)
+
+### 1b. Dispatch sub-agent
+
+Use the **Agent tool** to spawn a sub-agent:
+
+```
+prompt: |
+  You are running the Titan RECON phase. Read and follow the skill file at
+  .claude/skills/titan-recon/SKILL.md exactly. Target path: <targetPath>.
+
+  IMPORTANT: Skip the worktree check (Step 0.1) — the orchestrator already verified this.
+  IMPORTANT: Skip the "sync with main" step (Step 0.2) — the orchestrator already did this.
+  Execute Steps 1-13 as documented.
+```
+
+### 1c. Post-phase validation
+
+After the agent returns, validate the artifacts:
+
+**V1. titan-state.json structure:**
+Read `.codegraph/titan/titan-state.json` and verify ALL of these fields exist and are non-empty:
+- `version` — must be a number
+- `initialized` — must be an ISO 8601 string
+- `currentPhase` — must equal `"recon"`
+- `stats.totalNodes` — must be > 0
+- `stats.totalEdges` — must be > 0
+- `stats.totalFiles` — must be > 0
+- `domains` — must be an array with length > 0
+- `batches` — must be an array with length > 0
+- `priorityQueue` — must be an array with length > 0
+
+If any field is missing, zero, or wrong type → **VALIDATION FAILED.** Print which fields failed and stop: "RECON produced incomplete state. Re-run with `/titan-run --start-from recon`."
+
+**V2. GLOBAL_ARCH.md exists and has content:**
+Read `.codegraph/titan/GLOBAL_ARCH.md`:
+- Must exist
+- Must contain `## Domain Map` heading
+- Must have > 10 lines
+
+If missing or empty → **VALIDATION FAILED.**
+
+**V3. Snapshot created:**
+```bash
+codegraph snapshot list 2>/dev/null | grep titan-baseline || echo "NO_SNAPSHOT"
+```
+If `NO_SNAPSHOT` → **WARN** (not fatal, but note it: "No baseline snapshot — rollback in GATE will not work").
+
+**V4. Cross-check counts:**
+- `titan-state.json → stats.totalFiles` should roughly match the number of targets across all batches (batches are subsets of files, so `sum(batch.files.length)` should be ≤ `totalFiles`)
+- `priorityQueue.length` should be > 0 and ≤ `totalNodes`
+
+If wildly inconsistent (e.g., 0 batches but 500 nodes) → **WARN** with details.
+
+Print: `RECON validated. Domains: <count>, Batches: <count>, Priority targets: <count>, Quality score: <score>`
+
+---
+
+## Step 2 — GAUNTLET (loop)
+
+**Skip if:** `--skip-gauntlet` or `--start-from` is after gauntlet.
+
+### 2a. Pre-loop check
+
+Read `.codegraph/titan/gauntlet-summary.json` if it exists:
+- If `"complete": true` → run gauntlet post-validation (2d) and skip loop if it passes
+- Otherwise, count completed batches from `titan-state.json` for progress tracking
+
+Compute `expectedTargetCount` from `titan-state.json → priorityQueue.length` (or sum of batch file counts). This is the ground truth for "how many targets should gauntlet audit."
+
+### 2b. Gauntlet loop
+
+Set `maxIterations = 50` (safety limit).
+Set `stallCount = 0`, `maxStalls = 3` (consecutive no-progress iterations before abort).
+
+```
+previousAuditedCount = titan-state.json → progress.audited (or 0)
+iteration = 0
+
+while iteration < maxIterations:
+    iteration += 1
+
+    # Run Pre-Agent Gate (G1-G4)
+
+    # Dispatch sub-agent
+    Agent → "Run /titan-gauntlet with batch size <N>.
+             Read .claude/skills/titan-gauntlet/SKILL.md and follow it exactly.
+             Batch size: <gauntletBatchSize>.
+             Skip worktree check and main sync — already handled.
+             Process as many batches as context allows, then save state and stop."
+
+    # Check completion
+    Read .codegraph/titan/gauntlet-summary.json (if exists)
+    if "complete": true → break
+
+    # Progress tracking
+    Read .codegraph/titan/titan-state.json
+    currentAuditedCount = progress.audited
+
+    if currentAuditedCount == previousAuditedCount:
+        stallCount += 1
+        Print: "WARNING: Gauntlet iteration <iteration> made no progress (stall <stallCount>/<maxStalls>)"
+        if stallCount >= maxStalls:
+            Stop: "Gauntlet stalled for <maxStalls> consecutive iterations at <currentAuditedCount>/<expectedTargetCount> targets. Likely stuck on a problematic target. Check gauntlet.ndjson for the last successful entry and investigate the next target in the batch."
+    else:
+        stallCount = 0  # reset on any progress
+
+    previousAuditedCount = currentAuditedCount
+
+    # Efficiency check: if progress is very slow (< 2 targets per iteration), warn
+    targetsThisIteration = currentAuditedCount - previousAuditedCountBeforeAgent
+    if targetsThisIteration == 1 and iteration > 3:
+        Print: "WARNING: Only 1 target per iteration — agent may be spending too much context. Consider increasing batch size."
+
+    Print: "Gauntlet iteration <iteration>: <currentAuditedCount>/<expectedTargetCount> targets audited"
+```
+
+### 2c. NDJSON integrity check
+
+After the loop completes (or on each iteration if you prefer lightweight checks):
+
+```bash
+node -e "
+const fs = require('fs');
+const lines = fs.readFileSync('.codegraph/titan/gauntlet.ndjson','utf8').trim().split('\n');
+let valid = 0, corrupt = 0;
+for (const line of lines) {
+  try { JSON.parse(line); valid++; } catch { corrupt++; }
+}
+console.log(JSON.stringify({ valid, corrupt, total: lines.length }));
+"
+```
+
+- If `corrupt > 0`: Print "WARNING: <corrupt> corrupt lines in gauntlet.ndjson (likely from a crashed sub-agent). These targets may need re-auditing."
+- If `valid == 0`: Stop: "gauntlet.ndjson has no valid entries. Something went wrong."
+
+### 2d. Post-loop validation
+
+**V5. Gauntlet coverage:**
+- Count distinct `target` values in `gauntlet.ndjson` (valid lines only)
+- Compare against `expectedTargetCount`
+- If coverage < 80%: **WARN** "Gauntlet only audited <N>/<M> targets (<pct>%). Consider re-running with `/titan-run --start-from gauntlet`."
+- If coverage < 50%: **VALIDATION FAILED.** Stop.
+
+**V6. Gauntlet entry completeness (sample check):**
+Read first 5 and last 5 entries from `gauntlet.ndjson`. Each entry MUST have:
+- `target` — non-empty string
+- `file` — non-empty string
+- `verdict` — one of `PASS`, `WARN`, `FAIL`, `DECOMPOSE`
+- `pillarVerdicts` — object with keys `I`, `II`, `III`, `IV`
+- `metrics` — object with at least `cognitive` and `cyclomatic` (numeric)
+- `violations` — array
+
+If any sampled entry is missing required fields → **WARN**: "Gauntlet entry for <target> is incomplete — sub-agent may have skipped rules. Fields missing: <list>."
+
+**V7. Summary consistency:**
+Read `gauntlet-summary.json`:
+- `summary.totalAudited` should equal the valid NDJSON line count
+- `summary.pass + summary.warn + summary.fail + summary.decompose` should equal `summary.totalAudited`
+
+If mismatched → **WARN** with details (not fatal — the NDJSON is the source of truth, summary is derived).
+
+Print: `GAUNTLET validated. Audited: <N>/<M> targets. Pass: <N>, Warn: <N>, Fail: <N>, Decompose: <N>. NDJSON integrity: <valid>/<total> lines OK.`
+
+---
+
+## Step 3 — SYNC
+
+**Skip if:** `--start-from` is after sync, or `titan-state.json` has `currentPhase: "sync"` with existing `sync.json`.
+
+### 3a. Run Pre-Agent Gate (G1-G4)
+
+### 3b. Dispatch sub-agent
+
+```
+Agent → "Run /titan-sync. Read .claude/skills/titan-sync/SKILL.md and follow it exactly.
+         Skip worktree check and main sync — already handled.
+         Read GAUNTLET artifacts and produce sync.json."
+```
+
+### 3c. Post-phase validation
+
+**V8. sync.json structure:**
+Read `.codegraph/titan/sync.json` and verify:
+- `phase` — must equal `"sync"`
+- `executionOrder` — must be an array with length > 0
+- Each entry in `executionOrder` must have: `phase` (number), `label` (string), `targets` (array), `commit` (string)
+- `executionOrder` phases must be in ascending order
+- No duplicate phase numbers
+
+If missing or structurally invalid → **VALIDATION FAILED.** Stop: "SYNC produced invalid plan. Re-run with `/titan-run --start-from sync`."
+
+**V9. Sync targets trace back to gauntlet:**
+Collect all target names from `sync.json → executionOrder[*].targets` (flatten).
+For each, verify it appears in `gauntlet.ndjson` as a `target` field, OR in `titan-state.json → roles.deadSymbols` (dead code targets come from recon, not gauntlet).
+
+If > 20% of sync targets have no gauntlet entry and aren't dead symbols → **WARN**: "SYNC references <N> targets not found in gauntlet results. The sub-agent may have hallucinated targets."
+
+**V10. Execution order dependency check:**
+For entries with `dependencies` arrays, verify that each dependency phase number exists in `executionOrder` and has a lower phase number. Circular dependencies in the execution plan → **VALIDATION FAILED.**
+
+Print: `SYNC validated. Execution phases: <N>, Total targets: <N>, Estimated commits: <N>.`
+
+---
+
+## Step 3.5 — Pre-forge: Architectural Snapshot + Human Checkpoint
+
+### 3.5a. Capture architectural snapshot
+
+Before any code changes, snapshot the codebase's architectural properties. This becomes the baseline for the architectural comparator in `/titan-gate` (Step 5.5).
+
+```bash
+codegraph communities -T --json > .codegraph/titan/arch-snapshot-communities.json
+codegraph structure --depth 2 --json > .codegraph/titan/arch-snapshot-structure.json
+codegraph communities --drift -T --json > .codegraph/titan/arch-snapshot-drift.json
+```
+
+Combine into a single snapshot file:
+
+```bash
+node -e "
+const fs = require('fs');
+const communities = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-communities.json','utf8'));
+const structure = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-structure.json','utf8'));
+const drift = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-drift.json','utf8'));
+const snapshot = {
+  timestamp: new Date().toISOString(),
+  capturedBefore: 'forge',
+  headSha: '$(git rev-parse HEAD)',
+  communities,
+  structure,
+  drift
+};
+fs.writeFileSync('.codegraph/titan/arch-snapshot.json', JSON.stringify(snapshot, null, 2));
+"
+```
+
+Clean up temp files:
+```bash
+rm -f .codegraph/titan/arch-snapshot-communities.json .codegraph/titan/arch-snapshot-structure.json .codegraph/titan/arch-snapshot-drift.json
+```
+
+This snapshot is read by `/titan-gate` Step 5.5 during every commit validation.
+
+### 3.5b. Human checkpoint
+
+**This is a mandatory pause.** Analysis phases (recon, gauntlet, sync) are read-only. FORGE makes real code changes and commits. The user must see the plan.
+
+Print:
+```
+================================================================
+  ANALYSIS COMPLETE — FORGE CHECKPOINT
+================================================================
+
+The analysis phases (recon → gauntlet → sync) are done.
+FORGE will now make code changes and commit them.
+
+Execution plan summary:
+  Phase 1: <label> — <N> targets
+  Phase 2: <label> — <N> targets
+  ...
+
+Total: <N> phases, <N> targets, <N> estimated commits
+
+Architectural snapshot captured (for post-change comparison).
+
+Validation layers per commit:
+  1. Diff Review — does the change match the gauntlet recommendation and sync plan?
+  2. Titan Gate — structural checks, semantic assertions, architectural comparison, lint/build/test
+
+Proceed with /titan-forge? [y/n]
+(Use --yes to skip this checkpoint in future runs)
+================================================================
+```
+
+If `--yes` is NOT set: **stop and wait for user confirmation.** Do NOT proceed.
+If `--yes` IS set: print the summary but continue automatically.
+
+---
+
+## Step 4 — FORGE (loop)
+
+### 4a. Pre-loop check
+
+Read `.codegraph/titan/sync.json` → count total phases in `executionOrder`.
+Read `.codegraph/titan/titan-state.json` → check `execution.completedPhases` (may not exist yet if forge hasn't started).
+
+### 4b. Forge loop
+
+Set `maxIterations = 20` (safety limit).
+Set `stallCount = 0`, `maxStalls = 2` (forge stalls are more serious — fewer retries).
+
+```
+previousCompletedPhases = execution.completedPhases (or [])
+iteration = 0
+
+while iteration < maxIterations:
+    iteration += 1
+
+    # Run Pre-Agent Gate (G1-G4) — CRITICAL for forge since it commits
+    # Also check for unexpected commits:
+    git log --oneline -5
+    # Record the HEAD sha before dispatching
+
+    headBefore = $(git rev-parse HEAD)
+
+    # Determine next phase
+    Read .codegraph/titan/titan-state.json
+    completedPhases = execution.completedPhases (or [])
+    totalPhases = len(sync.json.executionOrder)
+    if len(completedPhases) >= totalPhases → break
+
+    nextPhase = first phase number NOT in completedPhases
+
+    # Dispatch sub-agent
+    yesFlag = "--yes" if autoConfirm else ""
+    Agent → "Run /titan-forge --phase <nextPhase> <yesFlag>.
+             Read .claude/skills/titan-forge/SKILL.md and follow it exactly.
+             Skip worktree check and main sync — already handled.
+
+             For each target, the validation flow is:
+             1. Apply code change
+             2. Stage files
+             3. Diff review (Step 9 in forge) — verify diff matches gauntlet recommendation and sync plan intent
+             4. Run tests
+             5. Run /titan-gate — read .claude/skills/titan-gate/SKILL.md and follow it exactly.
+                Gate now includes semantic assertions (Step 5) and architectural snapshot comparison (Step 5.5).
+                The arch snapshot is at .codegraph/titan/arch-snapshot.json.
+             6. Commit on success, rollback on failure
+
+             Do NOT skip the diff review step — it catches intent drift before gate even runs."
+
+    # Post-agent checks
+    headAfter = $(git rev-parse HEAD)
+
+    # V11. Verify commits were actually made (unless all targets failed)
+    Read .codegraph/titan/titan-state.json
+    newCompletedPhases = execution.completedPhases (or [])
+    newCompletedTargets = execution.completedTargets (or [])
+    newFailedTargets = execution.failedTargets (or [])
+
+    if newCompletedPhases == previousCompletedPhases:
+        stallCount += 1
+        Print: "WARNING: Forge iteration <iteration> did not complete phase <nextPhase> (stall <stallCount>/<maxStalls>)"
+        if stallCount >= maxStalls:
+            Stop: "Forge stalled on phase <nextPhase> for <maxStalls> consecutive iterations. Check titan-state.json → execution.failedTargets for details."
+    else:
+        stallCount = 0
+
+    # V12. Commit audit — verify commits match expectations
+    if headAfter != headBefore:
+        # Get commits made by this agent
+        git log --oneline <headBefore>..<headAfter>
+        commitCount = number of commits
+        Print: "Forge phase <nextPhase>: <commitCount> commits, <completedCount> targets completed, <failedCount> targets failed"
+    else:
+        # No commits but phase may have completed (all targets failed/skipped)
+        Print: "Forge phase <nextPhase>: no commits (all targets failed or skipped)"
+
+    # V13. Test suite still green after forge commits
+    # Quick sanity — run tests to make sure the cumulative commits haven't broken anything
+    npm test 2>&1
+    if tests fail:
+        Print: "CRITICAL: Test suite fails after forge phase <nextPhase>. Stopping pipeline."
+        Print: "Commits from this phase: git log --oneline <headBefore>..<headAfter>"
+        Print: "Consider reverting: git revert <headBefore>..<headAfter>"
+        Stop.
+
+    previousCompletedPhases = newCompletedPhases
+```
+
+### 4c. Post-loop validation
+
+**V14. Final state consistency:**
+Read `.codegraph/titan/titan-state.json`:
+- `execution.completedPhases` should contain all phase numbers from `sync.json → executionOrder`
+- `execution.commits` should be an array (may be empty if all targets failed)
+- Every commit SHA in `execution.commits` should exist in git log:
+  ```bash
+  git cat-file -t <sha>
+  ```
+  If any SHA doesn't exist → **WARN**: "Commit <sha> recorded in state but not found in git history. State may be out of sync."
+
+**V15. Gate log consistency:**
+If `.codegraph/titan/gate-log.ndjson` exists:
+- Count PASS vs FAIL entries
+- Every FAIL entry with `"rolledBack": true` should NOT have a corresponding commit in `execution.commits`
+
+Print forge summary.
+
+---
+
+## Step 5 — Final Report
+
+Read all artifacts and produce a summary:
+
+```
+============================================
+  TITAN PIPELINE COMPLETE
+============================================
+
+Target: <path>
+Duration: <first timestamp> → <last timestamp>
+
+RECON:
+  Files: <N>, Symbols: <N>, Domains: <N>
+  Quality score: <N>
+
+GAUNTLET:
+  Audited: <N>/<M> targets (<pct>% coverage)
+  Pass: <N> | Warn: <N> | Fail: <N> | Decompose: <N>
+  NDJSON integrity: <valid>/<total> lines
+
+SYNC:
+  Execution phases: <N>
+  Shared abstractions: <N>
+
+FORGE:
+  Commits: <N>
+  Targets completed: <N>
+  Targets failed: <N>
+  Diff review rejections: <N>
+  Gate verdicts: <pass> PASS, <fail> FAIL
+  Semantic assertion failures: <N>
+  Architectural violations caught: <N>
+
+  Failed targets (if any):
+  - <target>: <reason>
+
+Validation warnings (if any):
+  - <warning>
+
+Artifacts:
+  .codegraph/titan/titan-state.json
+  .codegraph/titan/GLOBAL_ARCH.md
+  .codegraph/titan/gauntlet.ndjson
+  .codegraph/titan/gauntlet-summary.json
+  .codegraph/titan/sync.json
+  .codegraph/titan/arch-snapshot.json
+  .codegraph/titan/gate-log.ndjson
+============================================
+```
+
+---
+
+## Error Handling
+
+- **Sub-agent returns error:** Print the error, stop, and tell the user which phase failed and how to retry (e.g., "Run `/titan-run --start-from gauntlet`").
+- **State file missing when expected:** Stop with clear message about which prerequisite phase to run.
+- **State file corrupt (JSON parse error):** Attempt restore from `.bak`. If no backup → stop: "State file corrupted. Run `/titan-reset` and start over."
+- **NDJSON corrupt lines:** Warn but continue — partial results are better than none. The corrupt lines are logged so the user knows which targets to re-audit.
+- **Merge conflict detected by pre-agent gate:** Stop immediately with the conflicting files listed.
+- **Tests fail after forge phase:** Stop immediately. Print the failing phase's commits so the user can revert.
+- **Validation failure (any V-check marked FAILED):** Stop with details. Warn-level V-checks are logged but don't stop the pipeline.
+
+---
+
+## Rules
+
+- **You are the orchestrator, not the executor.** Never run codegraph commands, edit source files, or make commits yourself. Only spawn sub-agents and read state files. The ONE exception: the post-forge test run (V13) and NDJSON integrity checks are run directly since they're pure validation.
+- **Run the Pre-Agent Gate (G1-G4) before EVERY sub-agent.** No exceptions.
+- **One sub-agent at a time.** Phases are sequential — recon before gauntlet, gauntlet before sync, sync before forge.
+- **Fresh context per sub-agent.** This is the whole point — each sub-agent gets a clean context window.
+- **Read AND validate state files after every sub-agent.** Trust the on-disk state, not the sub-agent's text output — but verify the state is structurally sound.
+- **Back up state before every sub-agent.** The `.bak` file is your safety net against mid-write crashes.
+- **Mandatory pause before forge** unless `--yes` is set. Analysis is safe; code changes deserve human review.
+- **Stall detection is strict for forge** (2 retries) and looser for gauntlet (3 retries) since gauntlet is more likely to hit context limits legitimately.
+- **Respect --start-from.** Skip phases before the specified starting point, but verify their artifacts exist AND pass validation.
+- **Pass --yes through to forge** if the user provided it, so forge doesn't prompt for confirmation on each phase.
+
+## Self-Improvement
+
+This skill lives at `.claude/skills/titan-run/SKILL.md`. Edit if loop logic needs adjustment, error handling needs improvement, or new phases are added to the pipeline.
diff --git a/docs/examples/claude-code-skills/README.md b/docs/examples/claude-code-skills/README.md
index 1c38adb2..3ed9e864 100644
--- a/docs/examples/claude-code-skills/README.md
+++ b/docs/examples/claude-code-skills/README.md
@@ -13,16 +13,17 @@ A single AI agent cannot hold an entire large codebase in context. The Titan Par
 3. Next phase reads only those artifacts — not the original sources
 
 ```
-/titan-recon → titan-state.json + GLOBAL_ARCH.md
+/titan-run (orchestrator — runs everything below end-to-end via sub-agents)
       │
-      ▼
-/titan-gauntlet → gauntlet.ndjson (batches of 5, resumes across sessions)
+      ├─→ /titan-recon → titan-state.json + GLOBAL_ARCH.md
       │
-      ▼
-/titan-sync → sync.json (execution plan)
+      ├─→ /titan-gauntlet → gauntlet.ndjson (loops until complete)
       │
-      ▼
-/titan-gate (validates each commit: codegraph + lint/build/test)
+      ├─→ /titan-sync → sync.json (execution plan)
+      │
+      └─→ /titan-forge → code changes + commits (loops phases)
+              │
+              └─→ /titan-gate (validates each commit)
 
 /titan-reset (escape hatch: clean up everything)
 ```
@@ -31,9 +32,11 @@ A single AI agent cannot hold an entire large codebase in context. The Titan Par
 
 | Skill | Phase | What it does | Key artifact |
 |-------|-------|-------------|-------------|
+| `/titan-run` | **ORCHESTRATOR** | Runs the full pipeline end-to-end by dispatching each phase to sub-agents with fresh context windows. Loops gauntlet and forge automatically | — |
 | `/titan-recon` | RECON | Builds graph + embeddings, complexity health baseline, domains, priority queue, work batches, `GLOBAL_ARCH.md`, baseline snapshot | `titan-state.json` |
 | `/titan-gauntlet` | GAUNTLET | 4-pillar audit (17 rules) using full codegraph metrics (`cognitive`, `cyclomatic`, `halstead.bugs`, `halstead.effort`, `mi`, `loc.sloc`). Batches of 5, NDJSON writes, session resume | `gauntlet.ndjson` |
 | `/titan-sync` | GLOBAL SYNC | Dependency clusters, code ownership, shared abstractions, ordered execution plan with logical commits | `sync.json` |
+| `/titan-forge` | FORGE | Executes the sync plan — makes code changes, validates with `/titan-gate`, commits, advances state. One phase per invocation | `titan-state.json` |
 | `/titan-gate` | STATE MACHINE | `codegraph check --staged --cycles --blast-radius 30 --boundaries` + lint/build/test. Snapshot restore on failure | `gate-log.ndjson` |
 | `/titan-reset` | ESCAPE HATCH | Restores baseline snapshot, deletes all artifacts and snapshots, rebuilds graph | — |
 
@@ -56,17 +59,31 @@ codegraph build .
 
 ## Usage
 
-### Full pipeline
+### Fully automated (recommended)
+
+```
+/titan-run             # Runs the entire pipeline hands-free
+```
+
+The orchestrator dispatches each phase to a sub-agent with a fresh context window. Gauntlet and forge are looped automatically until complete. You can also resume from a specific phase:
+
+```
+/titan-run --start-from gauntlet          # Skip recon, resume gauntlet
+/titan-run --start-from forge --yes       # Skip to forge, auto-confirm
+/titan-run --gauntlet-batch-size 10       # Larger batches (if context allows)
+```
+
+### Manual pipeline
 
 ```
 /titan-recon           # Map the codebase, produce priority queue + embeddings
 /titan-gauntlet 5      # Audit top targets in batches of 5
 /titan-sync            # Plan shared abstractions and execution order
-# ... make changes based on sync plan ...
+/titan-forge           # Execute one phase of the sync plan
 /titan-gate            # Validate before each commit
 ```
 
-If GAUNTLET runs out of context, just re-invoke `/titan-gauntlet` — it resumes from the next pending batch.
+If GAUNTLET or FORGE runs out of context, just re-invoke — they resume from where they left off.
 
 ### Standalone phases
 
@@ -97,10 +114,11 @@ All artifacts are written to `.codegraph/titan/` (6 files, no redundancy):
 | File | Format | Written by | Read by |
 |------|--------|-----------|---------|
 | `titan-state.json` | JSON | RECON (init), ALL (update) | ALL |
-| `GLOBAL_ARCH.md` | Markdown | RECON | GAUNTLET, SYNC |
-| `gauntlet.ndjson` | NDJSON | GAUNTLET | SYNC |
+| `GLOBAL_ARCH.md` | Markdown | RECON | GAUNTLET, SYNC, GATE |
+| `gauntlet.ndjson` | NDJSON | GAUNTLET | SYNC, FORGE (diff review) |
 | `gauntlet-summary.json` | JSON | GAUNTLET | SYNC, GATE |
-| `sync.json` | JSON | SYNC | GATE |
+| `sync.json` | JSON | SYNC | FORGE (diff review), GATE |
+| `arch-snapshot.json` | JSON | RUN (pre-forge) | GATE (architectural comparison) |
 | `gate-log.ndjson` | NDJSON | GATE | Audit trail |
 
 NDJSON format (one JSON object per line) means partial results survive crashes mid-batch.
diff --git a/docs/examples/claude-code-skills/titan-forge/SKILL.md b/docs/examples/claude-code-skills/titan-forge/SKILL.md
new file mode 100644
index 00000000..44c4c36b
--- /dev/null
+++ b/docs/examples/claude-code-skills/titan-forge/SKILL.md
@@ -0,0 +1,293 @@
+---
+name: titan-forge
+description: Execute the sync.json plan — refactor code, validate with /titan-gate, commit, and advance state (Titan Paradigm Phase 4)
+argument-hint: <--phase N> <--target name> <--dry-run>
+allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Skill, Agent
+---
+
+# Titan FORGE — Execute Sync Plan
+
+You are running the **FORGE** phase of the Titan Paradigm.
+
+Your goal: read `sync.json`, find the next incomplete execution phase, make the actual code changes for each target, validate with `/titan-gate`, commit, and advance state.
+
+> **Context budget:** One phase per invocation. Do not attempt all phases in one session — the context window will fill. Run one phase, report, stop. User re-runs for the next phase.
+
+**Arguments** (from `$ARGUMENTS`):
+- No args → run next incomplete phase
+- `--phase N` → jump to specific phase
+- `--target <name>` → run single target only (for retrying failures)
+- `--dry-run` → show what would be done without changing code
+
+---
+
+## Step 0 — Pre-flight
+
+1. **Worktree check:**
+   ```bash
+   git rev-parse --show-toplevel && git worktree list
+   ```
+   If not in a worktree, stop: "Run `/worktree` first."
+
+2. **Sync with main:**
+   ```bash
+   git fetch origin main && git merge origin/main --no-edit
+   ```
+   If there are merge conflicts, stop: "Merge conflict detected. Resolve conflicts and re-run `/titan-forge`."
+
+3. **Load artifacts.** Read:
+   - `.codegraph/titan/sync.json` — execution plan (if missing: "Run `/titan-sync` first.")
+   - `.codegraph/titan/titan-state.json` — current state
+   - `.codegraph/titan/gauntlet.ndjson` — per-target audit details
+   - `.codegraph/titan/gauntlet-summary.json` — aggregated results
+
+4. **Validate state.** If `titan-state.json` has `currentPhase` other than `"sync"` and no existing `execution` block, stop: "State not ready. Run `/titan-sync` first."
+
+5. **Initialize execution state** (if first run). Add to `titan-state.json`:
+   ```json
+   {
+     "execution": {
+       "currentPhase": 1,
+       "completedPhases": [],
+       "currentTarget": null,
+       "completedTargets": [],
+       "failedTargets": [],
+       "commits": []
+     }
+   }
+   ```
+
+6. **Determine next phase.** Use `--phase N` if provided, otherwise find the lowest phase number not in `completedPhases`.
+
+7. **Print plan:**
+   > Phase N: \<label\> — N targets, estimated N commits
+
+8. **Ask for confirmation** before starting (unless `$ARGUMENTS` contains `--yes`).
+
+---
+
+## Step 1 — Phase-specific execution strategies
+
+Each phase type requires different code-change logic:
+
+### Phase 1: Dead code cleanup
+- Delete the symbol/export
+- Verify no consumers: `codegraph fn-impact <target> -T --json`
+- Remove any orphaned imports
+- Run lint to clean up
+
+### Phase 2: Shared abstractions
+- Extract function/interface to new or existing file
+- Update imports in all consumers
+- Verify with: `codegraph exports <file> -T --json`
+
+### Phase 3: Empty catches / error handling
+- Replace `catch {}` with `catch (e) { logger.debug(...) }` or explicit fallback
+- Use contextually appropriate error handling
+- Subphases: each distinct catch pattern = one commit
+
+### Phase 4: Extractor decomposition
+- Split large `walkXNode` switch cases into handler functions
+- Keep dispatcher thin — handler per node kind
+- Subphases: each extractor = one commit
+
+### Phase 5: General decomposition
+- Read the gauntlet recommendation for the specific target
+- Apply the recommended decomposition strategy
+- Subphases: each function split = one commit
+
+### Phase 6: Small FAIL fixes
+- Read the gauntlet recommendation for the specific target
+- Apply the recommended fix (complexity reduction, metric improvement)
+- Group by domain where possible
+
+---
+
+## Step 2 — Per-target execution loop
+
+For each target in the current phase:
+
+1. **Skip if done.** Check if target is already in `execution.completedTargets`. If so, skip.
+
+2. **Update state.** Set `execution.currentTarget` in `titan-state.json`.
+
+3. **Read gauntlet entry.** Find this target in `gauntlet.ndjson` → get recommendation, violations, metrics.
+
+4. **Understand before touching.** Run codegraph commands:
+   ```bash
+   codegraph context <target> -T --json
+   ```
+   If blast radius > 0:
+   ```bash
+   codegraph fn-impact <target> -T --json
+   ```
+
+5. **Check if already fixed.** If the file has changed since gauntlet ran, re-check metrics:
+   ```bash
+   codegraph complexity --file <file> --health -T --json
+   ```
+   If the target now passes all thresholds, skip with note: "Target already passes — skipping."
+
+6. **Read source file(s).** Understand the code before editing.
+
+7. **Apply the change** based on phase strategy (Step 1) + gauntlet recommendation.
+
+8. **Stage changed files:**
+   ```bash
+   git add <specific changed files>
+   ```
+
+9. **Diff review (intent verification):**
+   Before running gate or tests, verify the diff matches the intent. This catches cases where the code change is structurally valid but doesn't match what was planned.
+
+   Collect the context:
+   ```bash
+   git diff --cached --stat
+   git diff --cached
+   ```
+
+   Load the gauntlet entry for this target (from `gauntlet.ndjson`) and the sync plan entry (from `sync.json → executionOrder[currentPhase]`).
+
+   **Check all of the following:**
+
+   **D1. Scope — only planned files touched:**
+   Compare staged file paths against `sync.json → executionOrder[currentPhase].targets` and their known file paths (from gauntlet entries). Flag any file NOT associated with the current target or phase.
+   - File in a completely different domain → **DIFF FAIL**
+   - File is a direct dependency of the target (consumer or import) → **OK** (expected ripple)
+   - Test file for the target → **OK**
+
+   **D2. Intent match — diff aligns with gauntlet recommendation:**
+   Read the gauntlet entry's `recommendation` field and `violations` list. Verify the diff addresses them:
+   - If recommendation says "split" → diff should show new functions extracted, original simplified
+   - If recommendation says "remove dead code" → diff should show deletions, not additions
+   - If violation was "complexity > threshold" → diff should reduce complexity, not just move code around
+   - If the diff does something **entirely different** from the recommendation → **DIFF FAIL**
+
+   **D3. Commit message accuracy:**
+   Compare the planned commit message from `sync.json` against what the diff actually does.
+   - Message says "remove dead code" but diff adds new functions → **DIFF WARN**
+   - Message says "extract X from Y" but diff only modifies Y without creating X → **DIFF FAIL**
+
+   **D4. Deletion audit:**
+   If the diff deletes code (lines removed > 10):
+   ```bash
+   codegraph fn-impact <deleted-symbol> -T --json 2>/dev/null
+   ```
+   If the deleted symbol has active callers not updated in this diff → **DIFF FAIL**: "Deleted <symbol> still has <N> callers not updated in this commit."
+
+   **D5. Leftover check:**
+   If the gauntlet recommendation mentioned specific symbols to remove/refactor, verify they were actually addressed:
+   - Dead symbols listed for removal → should be deleted in the diff
+   - Functions marked for decomposition → original should be simplified or removed
+
+   **On DIFF FAIL:** Unstage and revert changes, add to `execution.failedTargets` with reason starting with `"diff-review: "`. Continue to next target.
+   **On DIFF WARN:** Log the warning but proceed to gate. Include the warning in the gate-log entry.
+
+10. **Run tests:**
+    ```bash
+    npm test 2>&1
+    ```
+    If tests fail → go to rollback (step 13).
+
+11. **Run /titan-gate:**
+    Use the Skill tool to invoke `titan-gate`. If FAIL → go to rollback (step 13).
+
+12. **On success:**
+    ```bash
+    git commit -m "<commit message from sync.json>"
+    ```
+    - Record commit SHA in `execution.commits`
+    - Add target to `execution.completedTargets`
+    - Record any diff-review warnings in `execution.diffWarnings` (if any)
+    - Update `titan-state.json`
+
+13. **On failure (test, gate, or diff-review):**
+    ```bash
+    git checkout -- <changed files>
+    ```
+    - Add to `execution.failedTargets` with reason: `{ "target": "<name>", "reason": "<why>", "phase": N }`
+    - Clear `execution.currentTarget`
+    - **Continue to next target** — don't block the whole phase
+
+---
+
+## Step 3 — Phase completion
+
+When all targets in the phase are processed:
+
+1. Add phase number to `execution.completedPhases`
+2. Advance `execution.currentPhase` to the next phase number
+3. Clear `execution.currentTarget`
+4. Write updated `titan-state.json`
+
+---
+
+## Step 4 — Report
+
+Print:
+
+```
+## Phase N Complete: <label>
+
+Targets: X/Y completed, Z failed
+Commits: N
+Files changed: N
+
+### Failed targets (if any):
+- <target>: <reason>
+
+### Next: Phase M — <label> (N targets)
+Run /titan-forge to continue.
+```
+
+If all phases are complete:
+
+```
+## All phases complete
+
+Total commits: N
+Total targets: X completed, Y failed
+Failed targets: <list or "none">
+
+Run /titan-gate on the full branch to validate.
+```
+
+---
+
+## Edge Cases
+
+- **Test failure mid-phase:** Revert target, mark failed, continue. Don't block the whole phase.
+- **Merge conflict with main:** Stop, report, ask user to resolve.
+- **Gate detects new cycle:** Stop immediately — this is a real problem, not skippable.
+- **Target already fixed on main:** Check if file has changed since gauntlet. If metrics now pass, skip with note.
+- **Interrupted mid-phase:** Re-running picks up from `execution.currentTarget`. Already-committed targets are skipped.
+- **`--dry-run`:** Walk through all targets, print what would be done (phase strategy, gauntlet recommendation, files affected), but make no changes.
+- **`--target <name>`:** Run only that target. Useful for retrying entries in `failedTargets`.
+
+---
+
+## Rules
+
+- **One phase per invocation.** Stop after the phase completes. User re-runs for next.
+- **Resumable.** If interrupted, re-running picks up where it left off.
+- **Always use `--json` and `-T`** for codegraph commands.
+- **Gate before commit.** Every commit must pass `/titan-gate`. No exceptions.
+- **One commit per logical unit.** Use commit messages from `sync.json`.
+- **Stage only specific files.** Never `git add .` or `git add -A`.
+- **Rollback on failure is gentle** — `git checkout -- <files>`, not `git reset --hard`.
+- **Subphase awareness** — phases 3-6 have subphases. Each subphase = one commit. Track at subphase level.
+- **Never skip `/titan-gate`.** Even for "trivial" changes.
+
+## Relationship to Other Skills
+
+| Skill | Produces | Used by /titan-forge |
+|-------|----------|---------------------|
+| `/titan-recon` | `titan-state.json`, `GLOBAL_ARCH.md` | State tracking, domain context |
+| `/titan-gauntlet` | `gauntlet.ndjson`, `gauntlet-summary.json` | Per-target recommendations |
+| `/titan-sync` | `sync.json` | Execution plan (phases, targets, commits) |
+| `/titan-gate` | Gate verdict | Called per-commit for validation |
+| `/titan-reset` | Clean slate | Removes all artifacts |
+
+## Self-Improvement
+
+This skill lives at `.claude/skills/titan-forge/SKILL.md`. Edit if phase strategies need refinement or execution loop needs adjustment after dogfooding.
diff --git a/docs/examples/claude-code-skills/titan-gate/SKILL.md b/docs/examples/claude-code-skills/titan-gate/SKILL.md
index c1d7c359..3c8c0c95 100644
--- a/docs/examples/claude-code-skills/titan-gate/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-gate/SKILL.md
@@ -111,7 +111,114 @@ If any fail → overall verdict is FAIL → proceed to auto-rollback.
 
 ---
 
-## Step 5 — Branch structural diff
+## Step 5 — Semantic assertions (API compatibility)
+
+Verify that code changes don't silently break callers by changing public contracts. This goes beyond structural checks — it catches signature changes, removed exports, and new forbidden dependencies.
+
+### 5a. Export signature stability
+
+Get the list of changed files from diff-impact (Step 1):
+
+```bash
+codegraph exports <changed-file> -T --json
+```
+
+For each **exported** symbol in changed files:
+- Check if the symbol existed before this change: `git show HEAD:<file>` and compare function signatures
+- If a function's **parameter list changed** (added required params, removed params, changed types):
+  ```bash
+  codegraph fn-impact <symbol> -T --json
+  ```
+  Count callers. If callers > 0 and callers are NOT also staged → **FAIL**: "Signature change in `<symbol>` breaks <N> callers not updated in this commit: <caller list>"
+- If an **export was removed entirely** and callers exist → **FAIL**: "Removed export `<symbol>` still imported by <N> files"
+
+### 5b. Import resolution integrity
+
+Verify that all imports still resolve after the change:
+
+```bash
+codegraph check --staged -T --json
+```
+
+If any `unresolved_import` warnings appear for files NOT changed in this commit → **FAIL**: "Change broke import resolution for <file>: <import>"
+
+### 5c. Dependency direction assertions
+
+From diff-impact, extract any **new** edges (imports that didn't exist before):
+
+```bash
+codegraph diff-impact --staged -T --json
+```
+
+For each new dependency:
+- Check against `GLOBAL_ARCH.md` layer rules (if Titan artifacts exist)
+- Check against `codegraph check --boundaries -T --json`
+- New dependency from a lower layer to a higher layer → **FAIL**: "New upward dependency: `<source>` → `<target>` violates layer boundary"
+- New dependency on a module flagged in sync.json as "to be removed" or "to be split" → **WARN**: "New dependency on `<module>` which is scheduled for decomposition"
+
+### 5d. Re-export chain validation
+
+If the change modifies an index/barrel file (e.g., `index.js`, `mod.rs`):
+
+```bash
+codegraph exports <barrel-file> -T --json
+```
+
+Compare export count before and after. If exports were **accidentally dropped** (count decreased and the removed exports have callers) → **FAIL**.
+
+---
+
+## Step 5.5 — Architectural snapshot comparison
+
+Compare the codebase's architectural properties before and after this change. This catches "technically correct but architecturally wrong" changes — e.g., a valid refactor that puts code in the wrong layer.
+
+### Load pre-forge snapshot
+
+Read `.codegraph/titan/arch-snapshot.json` if it exists (created by `/titan-run` before forge begins). If missing, skip this step — it only works within the orchestrated pipeline.
+
+### Capture current state
+
+```bash
+codegraph communities -T --json > /tmp/titan-arch-current-communities.json
+codegraph structure --depth 2 --json > /tmp/titan-arch-current-structure.json
+codegraph communities --drift -T --json > /tmp/titan-arch-current-drift.json
+```
+
+### Compare
+
+**A1. Community stability:**
+Compare community assignments between snapshot and current. For each symbol that **moved** to a different community:
+- If the symbol was the target of this forge phase → **OK** (expected)
+- If the symbol was NOT touched in the diff → **WARN**: "Symbol `<name>` shifted from community <X> to <Y> as a side effect"
+- If > 5 untouched symbols shifted communities → **FAIL**: "Significant community restructuring detected — <N> symbols shifted communities. This change may have unintended architectural impact."
+
+**A2. Dependency direction between domains:**
+From `GLOBAL_ARCH.md`, extract the expected dependency direction between domains (e.g., "presentation depends on features, not the reverse").
+
+Check if any new cross-domain dependency violates the expected direction:
+```bash
+codegraph deps <changed-file> --json
+```
+- New upward dependency (lower layer importing higher layer) not present in snapshot → **FAIL**
+- New lateral dependency within the same layer → **OK**
+
+**A3. Cohesion delta:**
+Compare directory cohesion scores from `structure`:
+- If any directory's cohesion dropped by > 0.2 → **WARN**: "Directory `<dir>` cohesion dropped from <X> to <Y>"
+- If a directory went from above 0.5 to below 0.3 → **FAIL**: "Directory `<dir>` became tangled (cohesion <X> → <Y>)"
+
+**A4. New drift warnings:**
+Compare drift warnings between snapshot and current:
+- New drift warning not in snapshot → **WARN** with details
+- Drift warning resolved → note as positive
+
+### Verdict integration
+
+Architectural failures are reported as part of the overall gate verdict. They participate in the PASS/WARN/FAIL aggregation like all other checks.
+
+---
+
+## Step 6 — Branch structural diff
 
 ```bash
 codegraph branch-compare main HEAD -T --json
@@ -121,7 +228,7 @@ Cumulative structural impact of all changes on this branch (broader than `diff-i
 
 ---
 
-## Step 6 — Sync plan alignment
+## Step 7 — Sync plan alignment
 
 If `.codegraph/titan/sync.json` exists:
 - Are changed files part of the current execution phase?
@@ -132,7 +239,7 @@ Advisory — prevents jumping ahead and creating conflicts.
 
 ---
 
-## Step 7 — Blast radius check
+## Step 8 — Blast radius check
 
 From diff-impact results:
 - Transitive blast radius > 30 → FAIL
@@ -141,7 +248,7 @@ From diff-impact results:
 
 ---
 
-## Step 8 — Verdict and auto-rollback
+## Step 9 — Verdict and auto-rollback
 
 Aggregate all checks:
 
@@ -186,7 +293,7 @@ codegraph snapshot delete titan-batch-<N>   # if any remain
 
 ---
 
-## Step 9 — Update state machine
+## Step 10 — Update state machine
 
 Append to `.codegraph/titan/gate-log.ndjson`:
 
@@ -201,6 +308,8 @@ Append to `.codegraph/titan/gate-log.ndjson`:
     "manifesto": "pass|fail",
     "cycles": "pass|fail",
     "complexity": "pass|warn|fail",
+    "semanticAssertions": "pass|warn|fail|skipped",
+    "archSnapshot": "pass|warn|fail|skipped",
     "lint": "pass|fail|skipped",
     "build": "pass|fail|skipped",
     "tests": "pass|fail|skipped",
@@ -215,13 +324,14 @@ Update `titan-state.json` (if exists): increment `progress.fixed`, update `fileA
 
 ---
 
-## Step 10 — Report to user
+## Step 11 — Report to user
 
 **PASS:**
 ```
 GATE PASS — safe to commit
   Changed: 3 functions across 2 files
   Blast radius: 12 transitive callers
+  Structural: pass | Semantic: pass | Architecture: pass
   Lint: pass | Build: pass | Tests: pass
   Complexity: all within thresholds (worst: halstead.bugs 0.3)
 ```
@@ -233,6 +343,8 @@ GATE WARN — review before committing
   Warnings:
   - utils.js historically co-changes with config.js (not staged)
   - parseConfig MI improved 18 → 35 but still below 50
+  - Semantic: new dependency on module scheduled for decomposition
+  - Architecture: directory src/domain/ cohesion dropped 0.6 → 0.45
 ```
 
 **FAIL:**
@@ -240,6 +352,8 @@ GATE WARN — review before committing
 GATE FAIL — changes unstaged, graph restored
   Failures:
   - Tests: 2 suites failed
+  - Semantic: removed export `parseConfig` still imported by 3 files
+  - Architecture: new upward dependency presentation/ → domain/
   - New cycle: parseConfig → loadConfig → parseConfig
   Fix issues, re-stage, re-run /titan-gate
 ```
diff --git a/docs/examples/claude-code-skills/titan-run/SKILL.md b/docs/examples/claude-code-skills/titan-run/SKILL.md
new file mode 100644
index 00000000..d9127749
--- /dev/null
+++ b/docs/examples/claude-code-skills/titan-run/SKILL.md
@@ -0,0 +1,574 @@
+---
+name: titan-run
+description: Run the full Titan Paradigm pipeline end-to-end by dispatching each phase to sub-agents with fresh context windows. Orchestrates recon → gauntlet → sync → forge automatically.
+argument-hint: <path (default: .)> <--skip-recon> <--skip-gauntlet> <--start-from forge> <--gauntlet-batch-size 5> <--yes>
+allowed-tools: Agent, Read, Bash, Glob, Write, Edit
+---
+
+# Titan RUN — End-to-End Pipeline Orchestrator
+
+You are the **orchestrator** for the full Titan Paradigm pipeline. Your job is to dispatch each phase to a **sub-agent** (fresh context window), **validate the results**, and loop phases that require multiple invocations — all without human intervention.
+
+> **You are lightweight.** You do NOT run codegraph commands, audit files, or make code changes yourself. You only: (1) spawn sub-agents, (2) read and validate state files, (3) decide what to run next.
+
+**Arguments** (from `$ARGUMENTS`):
+- No args → full pipeline from scratch, target `.`
+- `<path>` → target path (passed to recon)
+- `--skip-recon` → skip recon (assumes artifacts exist)
+- `--skip-gauntlet` → skip gauntlet (assumes artifacts exist)
+- `--start-from <phase>` → jump to phase: `recon`, `gauntlet`, `sync`, `forge`
+- `--gauntlet-batch-size <N>` → batch size for gauntlet (default: 5)
+- `--yes` → skip confirmation prompts (passed through to forge)
+
+---
+
+## Step 0 — Pre-flight
+
+1. **Worktree check:**
+   ```bash
+   git rev-parse --show-toplevel && git worktree list
+   ```
+   If you are NOT in a worktree, **stop:** "Run `/worktree` first. The Titan pipeline writes artifacts and makes code changes — worktree isolation is required."
+
+2. **Parse arguments.** Determine:
+   - `targetPath` (default: `.`)
+   - `startPhase` (default: `recon`)
+   - `gauntletBatchSize` (default: `5`)
+   - `autoConfirm` (default: `false`)
+
+3. **Check existing state.** Read `.codegraph/titan/titan-state.json` if it exists.
+   - If state exists and `--start-from` not specified, ask user: "Existing Titan state found (phase: `<currentPhase>`). Resume from current state, or start fresh with `/titan-reset` first?"
+   - If `--yes` is set, resume automatically.
+
+4. **Sync with main** (once, before any sub-agent runs):
+   ```bash
+   git fetch origin main && git merge origin/main --no-edit
+   ```
+   If merge conflict → stop: "Merge conflict after syncing with main. Resolve conflicts and re-run `/titan-run`."
+
+5. **Print plan:**
+   ```
+   Titan Pipeline — End-to-End Run
+   Target: <path>
+   Starting from: <phase>
+   Gauntlet batch size: <N>
+
+   Phases: recon → gauntlet (loop) → sync → [PAUSE] → forge (loop)
+   Each phase runs in a sub-agent with a fresh context window.
+   Forge requires explicit confirmation (analysis phases are safe to automate).
+   ```
+
+   If `--yes` is NOT set, ask user to confirm before proceeding.
+
+---
+
+## Pre-Agent Gate (run before EVERY sub-agent dispatch)
+
+Before spawning any sub-agent, run these checks. This catches git state drift, concurrent interference, and corruption left by a crashed agent.
+
+### G1. Git health check
+```bash
+git status --porcelain
+```
+- **Unexpected dirty files** (files not in `.codegraph/titan/`): Print warning with the file list. Ask user to confirm proceeding, or stop. If `--yes`, log the warning and continue — but do NOT stage or commit these files.
+- **Merge conflicts** (lines starting with `UU`, `AA`, `DD`): Stop immediately: "Unresolved merge conflict detected. Resolve before continuing."
+
+### G2. Worktree still valid
+```bash
+git rev-parse --is-inside-work-tree
+```
+If this fails (worktree was pruned or moved), stop: "Worktree is no longer valid. Create a new one with `/worktree`."
+
+### G3. State file integrity
+If `.codegraph/titan/titan-state.json` should exist at this point (i.e., we're past recon):
+```bash
+node -e "try { JSON.parse(require('fs').readFileSync('.codegraph/titan/titan-state.json','utf8')); console.log('OK'); } catch(e) { console.log('CORRUPT: '+e.message); process.exit(1); }"
+```
+- If **CORRUPT** → attempt recovery from backup (see State Backup below). If no backup → stop: "State file corrupted with no backup. Run `/titan-reset` and start over."
+
+### G4. State backup
+Before every sub-agent dispatch, back up the current state file:
+```bash
+cp .codegraph/titan/titan-state.json .codegraph/titan/titan-state.json.bak 2>/dev/null || true
+```
+If a sub-agent corrupts the state, G3 on the next iteration will detect it and restore from `.bak`.
+
+---
+
+## Step 1 — RECON
+
+**Skip if:** `--skip-recon`, `--start-from` is after recon, or `titan-state.json` already has `currentPhase` beyond `"recon"`.
+
+### 1a. Run Pre-Agent Gate (G1-G4)
+
+### 1b. Dispatch sub-agent
+
+Use the **Agent tool** to spawn a sub-agent:
+
+```
+prompt: |
+  You are running the Titan RECON phase. Read and follow the skill file at
+  .claude/skills/titan-recon/SKILL.md exactly. Target path: <targetPath>.
+
+  IMPORTANT: Skip the worktree check (Step 0.1) — the orchestrator already verified this.
+  IMPORTANT: Skip the "sync with main" step (Step 0.2) — the orchestrator already did this.
+  Execute Steps 1-13 as documented.
+```
+
+### 1c. Post-phase validation
+
+After the agent returns, validate the artifacts:
+
+**V1. titan-state.json structure:**
+Read `.codegraph/titan/titan-state.json` and verify ALL of these fields exist and are non-empty:
+- `version` — must be a number
+- `initialized` — must be an ISO 8601 string
+- `currentPhase` — must equal `"recon"`
+- `stats.totalNodes` — must be > 0
+- `stats.totalEdges` — must be > 0
+- `stats.totalFiles` — must be > 0
+- `domains` — must be an array with length > 0
+- `batches` — must be an array with length > 0
+- `priorityQueue` — must be an array with length > 0
+
+If any field is missing, zero, or wrong type → **VALIDATION FAILED.** Print which fields failed and stop: "RECON produced incomplete state. Re-run with `/titan-run --start-from recon`."
+
+**V2. GLOBAL_ARCH.md exists and has content:**
+Read `.codegraph/titan/GLOBAL_ARCH.md`:
+- Must exist
+- Must contain `## Domain Map` heading
+- Must have > 10 lines
+
+If missing or empty → **VALIDATION FAILED.**
+
+**V3. Snapshot created:**
+```bash
+codegraph snapshot list 2>/dev/null | grep titan-baseline || echo "NO_SNAPSHOT"
+```
+If `NO_SNAPSHOT` → **WARN** (not fatal, but note it: "No baseline snapshot — rollback in GATE will not work").
+
+**V4. Cross-check counts:**
+- `titan-state.json → stats.totalFiles` should roughly match the number of targets across all batches (batches are subsets of files, so `sum(batch.files.length)` should be ≤ `totalFiles`)
+- `priorityQueue.length` should be > 0 and ≤ `totalNodes`
+
+If wildly inconsistent (e.g., 0 batches but 500 nodes) → **WARN** with details.
+
+Print: `RECON validated. Domains: <count>, Batches: <count>, Priority targets: <count>, Quality score: <score>`
+
+---
+
+## Step 2 — GAUNTLET (loop)
+
+**Skip if:** `--skip-gauntlet` or `--start-from` is after gauntlet.
+
+### 2a. Pre-loop check
+
+Read `.codegraph/titan/gauntlet-summary.json` if it exists:
+- If `"complete": true` → run gauntlet post-validation (2d) and skip loop if it passes
+- Otherwise, count completed batches from `titan-state.json` for progress tracking
+
+Compute `expectedTargetCount` from `titan-state.json → priorityQueue.length` (or sum of batch file counts). This is the ground truth for "how many targets should gauntlet audit."
+
+### 2b. Gauntlet loop
+
+Set `maxIterations = 50` (safety limit).
+Set `stallCount = 0`, `maxStalls = 3` (consecutive no-progress iterations before abort).
+
+```
+previousAuditedCount = titan-state.json → progress.audited (or 0)
+iteration = 0
+
+while iteration < maxIterations:
+    iteration += 1
+
+    # Run Pre-Agent Gate (G1-G4)
+
+    # Dispatch sub-agent
+    Agent → "Run /titan-gauntlet with batch size <N>.
+             Read .claude/skills/titan-gauntlet/SKILL.md and follow it exactly.
+             Batch size: <gauntletBatchSize>.
+             Skip worktree check and main sync — already handled.
+             Process as many batches as context allows, then save state and stop."
+
+    # Check completion
+    Read .codegraph/titan/gauntlet-summary.json (if exists)
+    if "complete": true → break
+
+    # Progress tracking
+    Read .codegraph/titan/titan-state.json
+    currentAuditedCount = progress.audited
+
+    if currentAuditedCount == previousAuditedCount:
+        stallCount += 1
+        Print: "WARNING: Gauntlet iteration <iteration> made no progress (stall <stallCount>/<maxStalls>)"
+        if stallCount >= maxStalls:
+            Stop: "Gauntlet stalled for <maxStalls> consecutive iterations at <currentAuditedCount>/<expectedTargetCount> targets. Likely stuck on a problematic target. Check gauntlet.ndjson for the last successful entry and investigate the next target in the batch."
+    else:
+        stallCount = 0  # reset on any progress
+
+    previousAuditedCount = currentAuditedCount
+
+    # Efficiency check: if progress is very slow (< 2 targets per iteration), warn
+    targetsThisIteration = currentAuditedCount - previousAuditedCountBeforeAgent
+    if targetsThisIteration == 1 and iteration > 3:
+        Print: "WARNING: Only 1 target per iteration — agent may be spending too much context. Consider increasing batch size."
+
+    Print: "Gauntlet iteration <iteration>: <currentAuditedCount>/<expectedTargetCount> targets audited"
+```
+
+### 2c. NDJSON integrity check
+
+After the loop completes (or on each iteration if you prefer lightweight checks):
+
+```bash
+node -e "
+const fs = require('fs');
+const lines = fs.readFileSync('.codegraph/titan/gauntlet.ndjson','utf8').trim().split('\n');
+let valid = 0, corrupt = 0;
+for (const line of lines) {
+  try { JSON.parse(line); valid++; } catch { corrupt++; }
+}
+console.log(JSON.stringify({ valid, corrupt, total: lines.length }));
+"
+```
+
+- If `corrupt > 0`: Print "WARNING: <corrupt> corrupt lines in gauntlet.ndjson (likely from a crashed sub-agent). These targets may need re-auditing."
+- If `valid == 0`: Stop: "gauntlet.ndjson has no valid entries. Something went wrong."
+
+### 2d. Post-loop validation
+
+**V5. Gauntlet coverage:**
+- Count distinct `target` values in `gauntlet.ndjson` (valid lines only)
+- Compare against `expectedTargetCount`
+- If coverage < 80%: **WARN** "Gauntlet only audited <N>/<M> targets (<pct>%). Consider re-running with `/titan-run --start-from gauntlet`."
+- If coverage < 50%: **VALIDATION FAILED.** Stop.
+
+**V6. Gauntlet entry completeness (sample check):**
+Read first 5 and last 5 entries from `gauntlet.ndjson`. Each entry MUST have:
+- `target` — non-empty string
+- `file` — non-empty string
+- `verdict` — one of `PASS`, `WARN`, `FAIL`, `DECOMPOSE`
+- `pillarVerdicts` — object with keys `I`, `II`, `III`, `IV`
+- `metrics` — object with at least `cognitive` and `cyclomatic` (numeric)
+- `violations` — array
+
+If any sampled entry is missing required fields → **WARN**: "Gauntlet entry for <target> is incomplete — sub-agent may have skipped rules. Fields missing: <list>."
+
+**V7. Summary consistency:**
+Read `gauntlet-summary.json`:
+- `summary.totalAudited` should equal the valid NDJSON line count
+- `summary.pass + summary.warn + summary.fail + summary.decompose` should equal `summary.totalAudited`
+
+If mismatched → **WARN** with details (not fatal — the NDJSON is the source of truth, summary is derived).
+
+Print: `GAUNTLET validated. Audited: <N>/<M> targets. Pass: <N>, Warn: <N>, Fail: <N>, Decompose: <N>. NDJSON integrity: <valid>/<total> lines OK.`
+
+---
+
+## Step 3 — SYNC
+
+**Skip if:** `--start-from` is after sync, or `titan-state.json` has `currentPhase: "sync"` with existing `sync.json`.
+
+### 3a. Run Pre-Agent Gate (G1-G4)
+
+### 3b. Dispatch sub-agent
+
+```
+Agent → "Run /titan-sync. Read .claude/skills/titan-sync/SKILL.md and follow it exactly.
+         Skip worktree check and main sync — already handled.
+         Read GAUNTLET artifacts and produce sync.json."
+```
+
+### 3c. Post-phase validation
+
+**V8. sync.json structure:**
+Read `.codegraph/titan/sync.json` and verify:
+- `phase` — must equal `"sync"`
+- `executionOrder` — must be an array with length > 0
+- Each entry in `executionOrder` must have: `phase` (number), `label` (string), `targets` (array), `commit` (string)
+- `executionOrder` phases must be in ascending order
+- No duplicate phase numbers
+
+If missing or structurally invalid → **VALIDATION FAILED.** Stop: "SYNC produced invalid plan. Re-run with `/titan-run --start-from sync`."
+
+**V9. Sync targets trace back to gauntlet:**
+Collect all target names from `sync.json → executionOrder[*].targets` (flatten).
+For each, verify it appears in `gauntlet.ndjson` as a `target` field, OR in `titan-state.json → roles.deadSymbols` (dead code targets come from recon, not gauntlet).
+
+If > 20% of sync targets have no gauntlet entry and aren't dead symbols → **WARN**: "SYNC references <N> targets not found in gauntlet results. The sub-agent may have hallucinated targets."
+
+**V10. Execution order dependency check:**
+For entries with `dependencies` arrays, verify that each dependency phase number exists in `executionOrder` and has a lower phase number. Circular dependencies in the execution plan → **VALIDATION FAILED.**
+
+Print: `SYNC validated. Execution phases: <N>, Total targets: <N>, Estimated commits: <N>.`
+
+---
+
+## Step 3.5 — Pre-forge: Architectural Snapshot + Human Checkpoint
+
+### 3.5a. Capture architectural snapshot
+
+Before any code changes, snapshot the codebase's architectural properties. This becomes the baseline for the architectural comparator in `/titan-gate` (Step 5.5).
+
+```bash
+codegraph communities -T --json > .codegraph/titan/arch-snapshot-communities.json
+codegraph structure --depth 2 --json > .codegraph/titan/arch-snapshot-structure.json
+codegraph communities --drift -T --json > .codegraph/titan/arch-snapshot-drift.json
+```
+
+Combine into a single snapshot file:
+
+```bash
+node -e "
+const fs = require('fs');
+const communities = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-communities.json','utf8'));
+const structure = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-structure.json','utf8'));
+const drift = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-drift.json','utf8'));
+const snapshot = {
+  timestamp: new Date().toISOString(),
+  capturedBefore: 'forge',
+  headSha: '$(git rev-parse HEAD)',
+  communities,
+  structure,
+  drift
+};
+fs.writeFileSync('.codegraph/titan/arch-snapshot.json', JSON.stringify(snapshot, null, 2));
+"
+```
+
+Clean up temp files:
+```bash
+rm -f .codegraph/titan/arch-snapshot-communities.json .codegraph/titan/arch-snapshot-structure.json .codegraph/titan/arch-snapshot-drift.json
+```
+
+This snapshot is read by `/titan-gate` Step 5.5 during every commit validation.
+
+### 3.5b. Human checkpoint
+
+**This is a mandatory pause.** Analysis phases (recon, gauntlet, sync) are read-only. FORGE makes real code changes and commits. The user must see the plan.
+
+Print:
+```
+================================================================
+  ANALYSIS COMPLETE — FORGE CHECKPOINT
+================================================================
+
+The analysis phases (recon → gauntlet → sync) are done.
+FORGE will now make code changes and commit them.
+
+Execution plan summary:
+  Phase 1: <label> — <N> targets
+  Phase 2: <label> — <N> targets
+  ...
+
+Total: <N> phases, <N> targets, <N> estimated commits
+
+Architectural snapshot captured (for post-change comparison).
+
+Validation layers per commit:
+  1. Diff Review — does the change match the gauntlet recommendation and sync plan?
+  2. Titan Gate — structural checks, semantic assertions, architectural comparison, lint/build/test
+
+Proceed with /titan-forge? [y/n]
+(Use --yes to skip this checkpoint in future runs)
+================================================================
+```
+
+If `--yes` is NOT set: **stop and wait for user confirmation.** Do NOT proceed.
+If `--yes` IS set: print the summary but continue automatically.
+
+---
+
+## Step 4 — FORGE (loop)
+
+### 4a. Pre-loop check
+
+Read `.codegraph/titan/sync.json` → count total phases in `executionOrder`.
+Read `.codegraph/titan/titan-state.json` → check `execution.completedPhases` (may not exist yet if forge hasn't started).
+
+### 4b. Forge loop
+
+Set `maxIterations = 20` (safety limit).
+Set `stallCount = 0`, `maxStalls = 2` (forge stalls are more serious — fewer retries).
+
+```
+previousCompletedPhases = execution.completedPhases (or [])
+iteration = 0
+
+while iteration < maxIterations:
+    iteration += 1
+
+    # Run Pre-Agent Gate (G1-G4) — CRITICAL for forge since it commits
+    # Also check for unexpected commits:
+    git log --oneline -5
+    # Record the HEAD sha before dispatching
+
+    headBefore = $(git rev-parse HEAD)
+
+    # Determine next phase
+    Read .codegraph/titan/titan-state.json
+    completedPhases = execution.completedPhases (or [])
+    totalPhases = len(sync.json.executionOrder)
+    if len(completedPhases) >= totalPhases → break
+
+    nextPhase = first phase number NOT in completedPhases
+
+    # Dispatch sub-agent
+    yesFlag = "--yes" if autoConfirm else ""
+    Agent → "Run /titan-forge --phase <nextPhase> <yesFlag>.
+             Read .claude/skills/titan-forge/SKILL.md and follow it exactly.
+             Skip worktree check and main sync — already handled.
+
+             For each target, the validation flow is:
+             1. Apply code change
+             2. Stage files
+             3. Diff review (Step 9 in forge) — verify diff matches gauntlet recommendation and sync plan intent
+             4. Run tests
+             5. Run /titan-gate — read .claude/skills/titan-gate/SKILL.md and follow it exactly.
+                Gate now includes semantic assertions (Step 5) and architectural snapshot comparison (Step 5.5).
+                The arch snapshot is at .codegraph/titan/arch-snapshot.json.
+             6. Commit on success, rollback on failure
+
+             Do NOT skip the diff review step — it catches intent drift before gate even runs."
+
+    # Post-agent checks
+    headAfter = $(git rev-parse HEAD)
+
+    # V11. Verify commits were actually made (unless all targets failed)
+    Read .codegraph/titan/titan-state.json
+    newCompletedPhases = execution.completedPhases (or [])
+    newCompletedTargets = execution.completedTargets (or [])
+    newFailedTargets = execution.failedTargets (or [])
+
+    if newCompletedPhases == previousCompletedPhases:
+        stallCount += 1
+        Print: "WARNING: Forge iteration <iteration> did not complete phase <nextPhase> (stall <stallCount>/<maxStalls>)"
+        if stallCount >= maxStalls:
+            Stop: "Forge stalled on phase <nextPhase> for <maxStalls> consecutive iterations. Check titan-state.json → execution.failedTargets for details."
+    else:
+        stallCount = 0
+
+    # V12. Commit audit — verify commits match expectations
+    if headAfter != headBefore:
+        # Get commits made by this agent
+        git log --oneline <headBefore>..<headAfter>
+        commitCount = number of commits
+        Print: "Forge phase <nextPhase>: <commitCount> commits, <completedCount> targets completed, <failedCount> targets failed"
+    else:
+        # No commits but phase may have completed (all targets failed/skipped)
+        Print: "Forge phase <nextPhase>: no commits (all targets failed or skipped)"
+
+    # V13. Test suite still green after forge commits
+    # Quick sanity — run tests to make sure the cumulative commits haven't broken anything
+    npm test 2>&1
+    if tests fail:
+        Print: "CRITICAL: Test suite fails after forge phase <nextPhase>. Stopping pipeline."
+        Print: "Commits from this phase: git log --oneline <headBefore>..<headAfter>"
+        Print: "Consider reverting: git revert <headBefore>..<headAfter>"
+        Stop.
+
+    previousCompletedPhases = newCompletedPhases
+```
+
+### 4c. Post-loop validation
+
+**V14. Final state consistency:**
+Read `.codegraph/titan/titan-state.json`:
+- `execution.completedPhases` should contain all phase numbers from `sync.json → executionOrder`
+- `execution.commits` should be an array (may be empty if all targets failed)
+- Every commit SHA in `execution.commits` should exist in git log:
+  ```bash
+  git cat-file -t <sha>
+  ```
+  If any SHA doesn't exist → **WARN**: "Commit <sha> recorded in state but not found in git history. State may be out of sync."
+
+**V15. Gate log consistency:**
+If `.codegraph/titan/gate-log.ndjson` exists:
+- Count PASS vs FAIL entries
+- Every FAIL entry with `"rolledBack": true` should NOT have a corresponding commit in `execution.commits`
+
+Print forge summary.
+
+---
+
+## Step 5 — Final Report
+
+Read all artifacts and produce a summary:
+
+```
+============================================
+  TITAN PIPELINE COMPLETE
+============================================
+
+Target: <path>
+Duration: <first timestamp> → <last timestamp>
+
+RECON:
+  Files: <N>, Symbols: <N>, Domains: <N>
+  Quality score: <N>
+
+GAUNTLET:
+  Audited: <N>/<M> targets (<pct>% coverage)
+  Pass: <N> | Warn: <N> | Fail: <N> | Decompose: <N>
+  NDJSON integrity: <valid>/<total> lines
+
+SYNC:
+  Execution phases: <N>
+  Shared abstractions: <N>
+
+FORGE:
+  Commits: <N>
+  Targets completed: <N>
+  Targets failed: <N>
+  Diff review rejections: <N>
+  Gate verdicts: <pass> PASS, <fail> FAIL
+  Semantic assertion failures: <N>
+  Architectural violations caught: <N>
+
+  Failed targets (if any):
+  - <target>: <reason>
+
+Validation warnings (if any):
+  - <warning>
+
+Artifacts:
+  .codegraph/titan/titan-state.json
+  .codegraph/titan/GLOBAL_ARCH.md
+  .codegraph/titan/gauntlet.ndjson
+  .codegraph/titan/gauntlet-summary.json
+  .codegraph/titan/sync.json
+  .codegraph/titan/arch-snapshot.json
+  .codegraph/titan/gate-log.ndjson
+============================================
+```
+
+---
+
+## Error Handling
+
+- **Sub-agent returns error:** Print the error, stop, and tell the user which phase failed and how to retry (e.g., "Run `/titan-run --start-from gauntlet`").
+- **State file missing when expected:** Stop with clear message about which prerequisite phase to run.
+- **State file corrupt (JSON parse error):** Attempt restore from `.bak`. If no backup → stop: "State file corrupted. Run `/titan-reset` and start over."
+- **NDJSON corrupt lines:** Warn but continue — partial results are better than none. The corrupt lines are logged so the user knows which targets to re-audit.
+- **Merge conflict detected by pre-agent gate:** Stop immediately with the conflicting files listed.
+- **Tests fail after forge phase:** Stop immediately. Print the failing phase's commits so the user can revert.
+- **Validation failure (any V-check marked FAILED):** Stop with details. Warn-level V-checks are logged but don't stop the pipeline.
+
+---
+
+## Rules
+
+- **You are the orchestrator, not the executor.** Never run codegraph commands, edit source files, or make commits yourself. Only spawn sub-agents and read state files. The ONE exception: the post-forge test run (V13) and NDJSON integrity checks are run directly since they're pure validation.
+- **Run the Pre-Agent Gate (G1-G4) before EVERY sub-agent.** No exceptions.
+- **One sub-agent at a time.** Phases are sequential — recon before gauntlet, gauntlet before sync, sync before forge.
+- **Fresh context per sub-agent.** This is the whole point — each sub-agent gets a clean context window.
+- **Read AND validate state files after every sub-agent.** Trust the on-disk state, not the sub-agent's text output — but verify the state is structurally sound.
+- **Back up state before every sub-agent.** The `.bak` file is your safety net against mid-write crashes.
+- **Mandatory pause before forge** unless `--yes` is set. Analysis is safe; code changes deserve human review.
+- **Stall detection is strict for forge** (2 retries) and looser for gauntlet (3 retries) since gauntlet is more likely to hit context limits legitimately.
+- **Respect --start-from.** Skip phases before the specified starting point, but verify their artifacts exist AND pass validation.
+- **Pass --yes through to forge** if the user provided it, so forge doesn't prompt for confirmation on each phase.
+
+## Self-Improvement
+
+This skill lives at `.claude/skills/titan-run/SKILL.md`. Edit if loop logic needs adjustment, error handling needs improvement, or new phases are added to the pipeline.
diff --git a/docs/use-cases/titan-paradigm.md b/docs/use-cases/titan-paradigm.md
index 9c3a6b10..05e2dc95 100644
--- a/docs/use-cases/titan-paradigm.md
+++ b/docs/use-cases/titan-paradigm.md
@@ -264,34 +264,38 @@ Several planned features would make codegraph even more powerful for the Titan P
 We've built five Claude Code skills that implement the full Titan Paradigm using codegraph. Each phase writes structured JSON artifacts to `.codegraph/titan/` that the next phase reads — this keeps context usage minimal even on large codebases.
 
 ```
-/titan-recon → titan-state.json + GLOBAL_ARCH.md
+/titan-run (orchestrator — runs everything below end-to-end via sub-agents)
       │
-      ▼
-/titan-gauntlet → gauntlet.ndjson (batches of 5, resumes across sessions)
+      ├─→ /titan-recon → titan-state.json + GLOBAL_ARCH.md
       │
-      ▼
-/titan-sync → sync.json (execution plan with logical commits)
+      ├─→ /titan-gauntlet → gauntlet.ndjson (loops until complete)
       │
-      ▼
-/titan-gate (validates each commit: codegraph + lint/build/test)
+      ├─→ /titan-sync → sync.json (execution plan with logical commits)
+      │
+      └─→ /titan-forge → code changes + commits (loops phases)
+              │
+              └─→ /titan-gate (validates each commit)
 
 /titan-reset (escape hatch: clean up all artifacts and snapshots)
 ```
 
 | Skill | Phase | What it does |
 |-------|-------|-------------|
+| `/titan-run` | **ORCHESTRATOR** | Runs the full pipeline end-to-end by dispatching each phase to sub-agents with fresh context windows. Loops gauntlet and forge automatically — one command for the entire Titan process |
 | `/titan-recon` | RECON | Builds graph + embeddings, runs complexity health baseline (`--health --above-threshold`), identifies domains, produces priority queue + work batches + `GLOBAL_ARCH.md`, saves baseline snapshot |
 | `/titan-gauntlet` | GAUNTLET | 4-pillar audit (17 rules) leveraging codegraph's full metrics (`cognitive`, `cyclomatic`, `halstead.bugs`, `halstead.effort`, `mi`, `loc.sloc`). Batches of 5 (configurable), NDJSON incremental writes, resumes across sessions via `titan-state.json` |
 | `/titan-sync` | GLOBAL SYNC | Finds dependency clusters among failures using `codegraph path` + `owners` + `branch-compare`. Plans shared abstractions, produces ordered execution plan with logical commit grouping |
+| `/titan-forge` | FORGE | Executes the sync plan — makes code changes, validates with `/titan-gate`, commits, advances state. One phase per invocation, resumable |
 | `/titan-gate` | STATE MACHINE | Validates staged changes: `codegraph check --staged --cycles --blast-radius 30 --boundaries` + project lint/build/test. Auto-rollback with snapshot restore on failure. Append-only audit trail |
 | `/titan-reset` | ESCAPE HATCH | Restores baseline snapshot, deletes all Titan artifacts and snapshots, rebuilds graph clean |
 
 ### Context window management
 
-The original Titan Paradigm prompt struggles with large codebases because a single agent cannot hold everything in context. These skills solve this two ways:
+The original Titan Paradigm prompt struggles with large codebases because a single agent cannot hold everything in context. These skills solve this three ways:
 
 1. **Artifact bridging:** each phase writes compact JSON artifacts. The next phase reads only those — not the full source. Works across separate conversations too.
 2. **Batch processing with resume:** the GAUNTLET audits 5 files at a time (configurable), writes to NDJSON between batches, and stops at ~80% context usage. Re-invoking `/titan-gauntlet` resumes from the next pending batch automatically.
+3. **Sub-agent orchestration:** `/titan-run` dispatches each phase to a sub-agent with a fresh context window. The orchestrator itself stays lightweight (only reads small JSON state files), while each sub-agent gets the full context budget for its phase. Gauntlet and forge are looped automatically — no manual re-invocation needed.
 
 ### Snapshot lifecycle
 
@@ -364,11 +368,14 @@ Copy the skills into your project and run the pipeline:
 # Install skills
 cp -r node_modules/@optave/codegraph/docs/examples/claude-code-skills/titan-* .claude/skills/
 
-# In Claude Code:
+# In Claude Code — fully automated:
+/titan-run             # Runs recon → gauntlet → sync → forge end-to-end
+
+# Or manual phase-by-phase:
 /titan-recon           # Map the codebase, produce priority queue
 /titan-gauntlet 5      # Audit top targets in batches of 5
 /titan-sync            # Plan shared abstractions and execution order
-# ... make changes ...
+/titan-forge           # Execute changes, one phase per invocation
 /titan-gate            # Validate before each commit
 ```
 

From f6a15cfb328a1cfe1f127cf208fad6e45a7ab4d4 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sat, 21 Mar 2026 03:03:30 -0600
Subject: [PATCH 07/52] fix: correct undefined variable in titan-run gauntlet
 efficiency check

---
 .claude/skills/titan-run/SKILL.md                   | 3 ++-
 docs/examples/claude-code-skills/titan-run/SKILL.md | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/titan-run/SKILL.md b/.claude/skills/titan-run/SKILL.md
index d9127749..566714e6 100644
--- a/.claude/skills/titan-run/SKILL.md
+++ b/.claude/skills/titan-run/SKILL.md
@@ -206,10 +206,11 @@ while iteration < maxIterations:
     else:
         stallCount = 0  # reset on any progress
 
+    countBeforeUpdate = previousAuditedCount
     previousAuditedCount = currentAuditedCount
 
     # Efficiency check: if progress is very slow (< 2 targets per iteration), warn
-    targetsThisIteration = currentAuditedCount - previousAuditedCountBeforeAgent
+    targetsThisIteration = currentAuditedCount - countBeforeUpdate
     if targetsThisIteration == 1 and iteration > 3:
         Print: "WARNING: Only 1 target per iteration — agent may be spending too much context. Consider increasing batch size."
 
diff --git a/docs/examples/claude-code-skills/titan-run/SKILL.md b/docs/examples/claude-code-skills/titan-run/SKILL.md
index d9127749..566714e6 100644
--- a/docs/examples/claude-code-skills/titan-run/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-run/SKILL.md
@@ -206,10 +206,11 @@ while iteration < maxIterations:
     else:
         stallCount = 0  # reset on any progress
 
+    countBeforeUpdate = previousAuditedCount
     previousAuditedCount = currentAuditedCount
 
     # Efficiency check: if progress is very slow (< 2 targets per iteration), warn
-    targetsThisIteration = currentAuditedCount - previousAuditedCountBeforeAgent
+    targetsThisIteration = currentAuditedCount - countBeforeUpdate
     if targetsThisIteration == 1 and iteration > 3:
         Print: "WARNING: Only 1 target per iteration — agent may be spending too much context. Consider increasing batch size."
 

From 61035c2f6f56fc670f62461701e05f6981c270d9 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sat, 21 Mar 2026 04:43:12 -0600
Subject: [PATCH 08/52] fix: address Greptile review feedback on titan-run
 skill

- Fix undefined previousAuditedCountBeforeAgent variable in gauntlet
  efficiency check (save pre-update count before reassignment)
- Add AU, UA, DU, UD to merge conflict detection markers
- Add warning when --start-from forge runs without arch-snapshot.json
---
 .claude/skills/titan-run/SKILL.md                   | 8 ++++++--
 docs/examples/claude-code-skills/titan-run/SKILL.md | 8 ++++++--
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/.claude/skills/titan-run/SKILL.md b/.claude/skills/titan-run/SKILL.md
index d9127749..be127123 100644
--- a/.claude/skills/titan-run/SKILL.md
+++ b/.claude/skills/titan-run/SKILL.md
@@ -71,7 +71,7 @@ Before spawning any sub-agent, run these checks. This catches git state drift, c
 git status --porcelain
 ```
 - **Unexpected dirty files** (files not in `.codegraph/titan/`): Print warning with the file list. Ask user to confirm proceeding, or stop. If `--yes`, log the warning and continue — but do NOT stage or commit these files.
-- **Merge conflicts** (lines starting with `UU`, `AA`, `DD`): Stop immediately: "Unresolved merge conflict detected. Resolve before continuing."
+- **Merge conflicts** (lines starting with `UU`, `AA`, `DD`, `AU`, `UA`, `DU`, `UD`): Stop immediately: "Unresolved merge conflict detected. Resolve before continuing."
 
 ### G2. Worktree still valid
 ```bash
@@ -206,10 +206,11 @@ while iteration < maxIterations:
     else:
         stallCount = 0  # reset on any progress
 
+    countBeforeUpdate = previousAuditedCount
     previousAuditedCount = currentAuditedCount
 
     # Efficiency check: if progress is very slow (< 2 targets per iteration), warn
-    targetsThisIteration = currentAuditedCount - previousAuditedCountBeforeAgent
+    targetsThisIteration = currentAuditedCount - countBeforeUpdate
     if targetsThisIteration == 1 and iteration > 3:
         Print: "WARNING: Only 1 target per iteration — agent may be spending too much context. Consider increasing batch size."
 
@@ -386,6 +387,9 @@ If `--yes` IS set: print the summary but continue automatically.
 Read `.codegraph/titan/sync.json` → count total phases in `executionOrder`.
 Read `.codegraph/titan/titan-state.json` → check `execution.completedPhases` (may not exist yet if forge hasn't started).
 
+If `.codegraph/titan/arch-snapshot.json` does not exist:
+  Print: "NOTE: No arch-snapshot.json found. Architectural comparison in /titan-gate (Step 5.5) will be skipped for this run. To enable it, run '/titan-run --start-from sync' to re-capture the pre-forge snapshot."
+
 ### 4b. Forge loop
 
 Set `maxIterations = 20` (safety limit).
diff --git a/docs/examples/claude-code-skills/titan-run/SKILL.md b/docs/examples/claude-code-skills/titan-run/SKILL.md
index d9127749..be127123 100644
--- a/docs/examples/claude-code-skills/titan-run/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-run/SKILL.md
@@ -71,7 +71,7 @@ Before spawning any sub-agent, run these checks. This catches git state drift, c
 git status --porcelain
 ```
 - **Unexpected dirty files** (files not in `.codegraph/titan/`): Print warning with the file list. Ask user to confirm proceeding, or stop. If `--yes`, log the warning and continue — but do NOT stage or commit these files.
-- **Merge conflicts** (lines starting with `UU`, `AA`, `DD`): Stop immediately: "Unresolved merge conflict detected. Resolve before continuing."
+- **Merge conflicts** (lines starting with `UU`, `AA`, `DD`, `AU`, `UA`, `DU`, `UD`): Stop immediately: "Unresolved merge conflict detected. Resolve before continuing."
 
 ### G2. Worktree still valid
 ```bash
@@ -206,10 +206,11 @@ while iteration < maxIterations:
     else:
         stallCount = 0  # reset on any progress
 
+    countBeforeUpdate = previousAuditedCount
     previousAuditedCount = currentAuditedCount
 
     # Efficiency check: if progress is very slow (< 2 targets per iteration), warn
-    targetsThisIteration = currentAuditedCount - previousAuditedCountBeforeAgent
+    targetsThisIteration = currentAuditedCount - countBeforeUpdate
     if targetsThisIteration == 1 and iteration > 3:
         Print: "WARNING: Only 1 target per iteration — agent may be spending too much context. Consider increasing batch size."
 
@@ -386,6 +387,9 @@ If `--yes` IS set: print the summary but continue automatically.
 Read `.codegraph/titan/sync.json` → count total phases in `executionOrder`.
 Read `.codegraph/titan/titan-state.json` → check `execution.completedPhases` (may not exist yet if forge hasn't started).
 
+If `.codegraph/titan/arch-snapshot.json` does not exist:
+  Print: "NOTE: No arch-snapshot.json found. Architectural comparison in /titan-gate (Step 5.5) will be skipped for this run. To enable it, run '/titan-run --start-from sync' to re-capture the pre-forge snapshot."
+
 ### 4b. Forge loop
 
 Set `maxIterations = 20` (safety limit).

From ea192ea054b4154719d1e873fbd42f424a8baa69 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sat, 21 Mar 2026 04:43:12 -0600
Subject: [PATCH 09/52] fix: address Greptile review feedback on titan-run
 skill

- Fix undefined previousAuditedCountBeforeAgent variable in gauntlet
  efficiency check (save pre-update count before reassignment)
- Add AU, UA, DU, UD to merge conflict detection markers
- Add warning when --start-from forge runs without arch-snapshot.json
---
 .claude/skills/titan-run/SKILL.md                   | 5 ++++-
 docs/examples/claude-code-skills/titan-run/SKILL.md | 5 ++++-
 2 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/titan-run/SKILL.md b/.claude/skills/titan-run/SKILL.md
index 566714e6..be127123 100644
--- a/.claude/skills/titan-run/SKILL.md
+++ b/.claude/skills/titan-run/SKILL.md
@@ -71,7 +71,7 @@ Before spawning any sub-agent, run these checks. This catches git state drift, c
 git status --porcelain
 ```
 - **Unexpected dirty files** (files not in `.codegraph/titan/`): Print warning with the file list. Ask user to confirm proceeding, or stop. If `--yes`, log the warning and continue — but do NOT stage or commit these files.
-- **Merge conflicts** (lines starting with `UU`, `AA`, `DD`): Stop immediately: "Unresolved merge conflict detected. Resolve before continuing."
+- **Merge conflicts** (lines starting with `UU`, `AA`, `DD`, `AU`, `UA`, `DU`, `UD`): Stop immediately: "Unresolved merge conflict detected. Resolve before continuing."
 
 ### G2. Worktree still valid
 ```bash
@@ -387,6 +387,9 @@ If `--yes` IS set: print the summary but continue automatically.
 Read `.codegraph/titan/sync.json` → count total phases in `executionOrder`.
 Read `.codegraph/titan/titan-state.json` → check `execution.completedPhases` (may not exist yet if forge hasn't started).
 
+If `.codegraph/titan/arch-snapshot.json` does not exist:
+  Print: "NOTE: No arch-snapshot.json found. Architectural comparison in /titan-gate (Step 5.5) will be skipped for this run. To enable it, run '/titan-run --start-from sync' to re-capture the pre-forge snapshot."
+
 ### 4b. Forge loop
 
 Set `maxIterations = 20` (safety limit).
diff --git a/docs/examples/claude-code-skills/titan-run/SKILL.md b/docs/examples/claude-code-skills/titan-run/SKILL.md
index 566714e6..be127123 100644
--- a/docs/examples/claude-code-skills/titan-run/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-run/SKILL.md
@@ -71,7 +71,7 @@ Before spawning any sub-agent, run these checks. This catches git state drift, c
 git status --porcelain
 ```
 - **Unexpected dirty files** (files not in `.codegraph/titan/`): Print warning with the file list. Ask user to confirm proceeding, or stop. If `--yes`, log the warning and continue — but do NOT stage or commit these files.
-- **Merge conflicts** (lines starting with `UU`, `AA`, `DD`): Stop immediately: "Unresolved merge conflict detected. Resolve before continuing."
+- **Merge conflicts** (lines starting with `UU`, `AA`, `DD`, `AU`, `UA`, `DU`, `UD`): Stop immediately: "Unresolved merge conflict detected. Resolve before continuing."
 
 ### G2. Worktree still valid
 ```bash
@@ -387,6 +387,9 @@ If `--yes` IS set: print the summary but continue automatically.
 Read `.codegraph/titan/sync.json` → count total phases in `executionOrder`.
 Read `.codegraph/titan/titan-state.json` → check `execution.completedPhases` (may not exist yet if forge hasn't started).
 
+If `.codegraph/titan/arch-snapshot.json` does not exist:
+  Print: "NOTE: No arch-snapshot.json found. Architectural comparison in /titan-gate (Step 5.5) will be skipped for this run. To enable it, run '/titan-run --start-from sync' to re-capture the pre-forge snapshot."
+
 ### 4b. Forge loop
 
 Set `maxIterations = 20` (safety limit).

From 58f2238fe135ad81a36cbe38ee97c6ae7022f6f4 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sat, 21 Mar 2026 05:14:07 -0600
Subject: [PATCH 10/52] fix: restore FORGE to codegraph exports and fn-impact
 in tool table

Both commands are called in titan-forge's new diff review step (Step 9):
fn-impact for deletion audit (D4) and exports for re-export chain checks.
---
 docs/examples/claude-code-skills/README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/docs/examples/claude-code-skills/README.md b/docs/examples/claude-code-skills/README.md
index 3ed9e864..395bed29 100644
--- a/docs/examples/claude-code-skills/README.md
+++ b/docs/examples/claude-code-skills/README.md
@@ -195,8 +195,8 @@ All skills enforce worktree isolation as their first step. If invoked from the m
 | `codegraph check --staged --cycles --blast-radius --boundaries` | GATE | Full validation predicates |
 | `codegraph ast --kind call\|await\|string` | GAUNTLET | AST pattern detection |
 | `codegraph dataflow` | GAUNTLET | Data flow and mutation analysis |
-| `codegraph exports` | GAUNTLET | Per-symbol export consumers |
-| `codegraph fn-impact` | GAUNTLET, SYNC | Blast radius |
+| `codegraph exports` | GAUNTLET, FORGE | Per-symbol export consumers |
+| `codegraph fn-impact` | GAUNTLET, SYNC, FORGE | Blast radius |
 | `codegraph search` | GAUNTLET | Duplicate code detection (needs embeddings) |
 | `codegraph co-change` | GAUNTLET, SYNC | Git history coupling |
 | `codegraph path` | SYNC | Dependency paths between targets |

From 5168c3df8f901bba374d837a0c4d31fe8b0f02b9 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sat, 21 Mar 2026 19:23:22 -0600
Subject: [PATCH 11/52] fix: unstage files before restoring working tree in
 forge Step 13 rollback

---
 .claude/skills/titan-forge/SKILL.md                   | 1 +
 docs/examples/claude-code-skills/titan-forge/SKILL.md | 1 +
 2 files changed, 2 insertions(+)

diff --git a/.claude/skills/titan-forge/SKILL.md b/.claude/skills/titan-forge/SKILL.md
index 44c4c36b..4fd83a6a 100644
--- a/.claude/skills/titan-forge/SKILL.md
+++ b/.claude/skills/titan-forge/SKILL.md
@@ -203,6 +203,7 @@ For each target in the current phase:
 
 13. **On failure (test, gate, or diff-review):**
     ```bash
+    git reset HEAD <changed files>
     git checkout -- <changed files>
     ```
     - Add to `execution.failedTargets` with reason: `{ "target": "<name>", "reason": "<why>", "phase": N }`
diff --git a/docs/examples/claude-code-skills/titan-forge/SKILL.md b/docs/examples/claude-code-skills/titan-forge/SKILL.md
index 44c4c36b..4fd83a6a 100644
--- a/docs/examples/claude-code-skills/titan-forge/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-forge/SKILL.md
@@ -203,6 +203,7 @@ For each target in the current phase:
 
 13. **On failure (test, gate, or diff-review):**
     ```bash
+    git reset HEAD <changed files>
     git checkout -- <changed files>
     ```
     - Add to `execution.failedTargets` with reason: `{ "target": "<name>", "reason": "<why>", "phase": N }`

From 9c1433a26041b340e7415774c757ede972a1e073 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sat, 21 Mar 2026 19:23:33 -0600
Subject: [PATCH 12/52] fix: add GATE to exports/fn-impact and FORGE to context
 in command table

---
 docs/examples/claude-code-skills/README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/docs/examples/claude-code-skills/README.md b/docs/examples/claude-code-skills/README.md
index 395bed29..db2c8b19 100644
--- a/docs/examples/claude-code-skills/README.md
+++ b/docs/examples/claude-code-skills/README.md
@@ -195,14 +195,14 @@ All skills enforce worktree isolation as their first step. If invoked from the m
 | `codegraph check --staged --cycles --blast-radius --boundaries` | GATE | Full validation predicates |
 | `codegraph ast --kind call\|await\|string` | GAUNTLET | AST pattern detection |
 | `codegraph dataflow` | GAUNTLET | Data flow and mutation analysis |
-| `codegraph exports` | GAUNTLET, FORGE | Per-symbol export consumers |
-| `codegraph fn-impact` | GAUNTLET, SYNC, FORGE | Blast radius |
+| `codegraph exports` | GAUNTLET, FORGE, GATE | Per-symbol export consumers |
+| `codegraph fn-impact` | GAUNTLET, SYNC, FORGE, GATE | Blast radius |
 | `codegraph search` | GAUNTLET | Duplicate code detection (needs embeddings) |
 | `codegraph co-change` | GAUNTLET, SYNC | Git history coupling |
 | `codegraph path` | SYNC | Dependency paths between targets |
 | `codegraph cycles` | SYNC, GATE | Circular dependency detection |
 | `codegraph deps` | SYNC | File-level dependency map |
-| `codegraph context` | SYNC | Full function context |
+| `codegraph context` | SYNC, FORGE | Full function context |
 | `codegraph owners` | SYNC | CODEOWNERS mapping for cross-team coordination |
 | `codegraph branch-compare` | SYNC, GATE | Structural diff between refs |
 | `codegraph diff-impact` | GATE | Impact of staged changes |

From 1144217719618afd1475a188adc00980f99c1bd0 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sat, 21 Mar 2026 19:23:42 -0600
Subject: [PATCH 13/52] fix: update --yes description to reflect actual
 orchestrator scope

---
 .claude/skills/titan-run/SKILL.md                   | 2 +-
 docs/examples/claude-code-skills/titan-run/SKILL.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/titan-run/SKILL.md b/.claude/skills/titan-run/SKILL.md
index be127123..f6d66fbf 100644
--- a/.claude/skills/titan-run/SKILL.md
+++ b/.claude/skills/titan-run/SKILL.md
@@ -18,7 +18,7 @@ You are the **orchestrator** for the full Titan Paradigm pipeline. Your job is t
 - `--skip-gauntlet` → skip gauntlet (assumes artifacts exist)
 - `--start-from <phase>` → jump to phase: `recon`, `gauntlet`, `sync`, `forge`
 - `--gauntlet-batch-size <N>` → batch size for gauntlet (default: 5)
-- `--yes` → skip confirmation prompts (passed through to forge)
+- `--yes` → skip all confirmation prompts in the orchestrator (pre-pipeline, forge checkpoint, and resume prompts)
 
 ---
 
diff --git a/docs/examples/claude-code-skills/titan-run/SKILL.md b/docs/examples/claude-code-skills/titan-run/SKILL.md
index be127123..f6d66fbf 100644
--- a/docs/examples/claude-code-skills/titan-run/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-run/SKILL.md
@@ -18,7 +18,7 @@ You are the **orchestrator** for the full Titan Paradigm pipeline. Your job is t
 - `--skip-gauntlet` → skip gauntlet (assumes artifacts exist)
 - `--start-from <phase>` → jump to phase: `recon`, `gauntlet`, `sync`, `forge`
 - `--gauntlet-batch-size <N>` → batch size for gauntlet (default: 5)
-- `--yes` → skip confirmation prompts (passed through to forge)
+- `--yes` → skip all confirmation prompts in the orchestrator (pre-pipeline, forge checkpoint, and resume prompts)
 
 ---
 

From a296b58ffdb17aba6ff9f20851ad060b7f00ff52 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sat, 21 Mar 2026 19:24:35 -0600
Subject: [PATCH 14/52] chore: checkpoint stale working tree changes from prior
 sessions

Impact: 43 functions changed, 46 affected
---
 .claude/skills/architect/SKILL.md             | 140 +++++
 docs/roadmap/ROADMAP.md                       | 488 +++++++++++-------
 generated/competitive/COMPETITIVE_ANALYSIS.md | 254 ++++-----
 generated/competitive/joern.md                |  53 +-
 generated/competitive/narsil-mcp.md           |  77 +--
 generated/dogfood/DOGFOOD_REPORT_v3.1.2.md    | 395 --------------
 package-lock.json                             |   9 -
 scripts/benchmark.js                          | 307 +++++------
 scripts/embedding-benchmark.js                | 194 ++++---
 scripts/incremental-benchmark.js              | 319 ++++++------
 scripts/lib/fork-engine.js                    | 163 ++++++
 scripts/query-benchmark.js                    | 182 +++----
 src/domain/analysis/context.js                |   2 +-
 .../graph/builder/stages/build-edges.js       | 102 +++-
 src/domain/graph/resolve.js                   | 196 ++++++-
 src/domain/graph/watcher.js                   |   4 +-
 src/extractors/go.js                          | 134 ++++-
 src/extractors/javascript.js                  | 124 ++++-
 src/extractors/python.js                      |  81 ++-
 src/features/export.js                        |   6 +-
 src/features/graph-enrichment.js              |   4 +-
 tests/integration/build-parity.test.js        |   5 +
 tests/parsers/javascript.test.js              |  47 ++
 tests/unit/resolve.test.js                    | 201 ++++++++
 24 files changed, 2177 insertions(+), 1310 deletions(-)
 create mode 100644 .claude/skills/architect/SKILL.md
 delete mode 100644 generated/dogfood/DOGFOOD_REPORT_v3.1.2.md
 create mode 100644 scripts/lib/fork-engine.js

diff --git a/.claude/skills/architect/SKILL.md b/.claude/skills/architect/SKILL.md
new file mode 100644
index 00000000..badf9ea8
--- /dev/null
+++ b/.claude/skills/architect/SKILL.md
@@ -0,0 +1,140 @@
+# /architect — Full Architectural Audit
+
+Run a cold, harsh architectural audit of codegraph. Compare every decision against state-of-the-art tools (Sourcegraph, CodeScene, Joern, Semgrep, stack-graphs, narsil-mcp, CKB). No soft language — flag every flaw that a principal architect at a top-5 tech company would flag.
+
+## Output
+
+**Filename:** `ARCHITECTURE_AUDIT_v{VERSION}_{DATE}.md`
+- `{VERSION}` = current `package.json` version (e.g., `3.1.4`)
+- `{DATE}` = today's date in `YYYY-MM-DD` format (e.g., `2026-03-16`)
+
+**Saved to two locations:**
+1. `docs/architecture/ARCHITECTURE_AUDIT_v{VERSION}_{DATE}.md` — canonical, committed to git
+2. `generated/architecture/ARCHITECTURE_AUDIT_v{VERSION}_{DATE}.md` — working copy
+
+**Header format:**
+```markdown
+# Codegraph Architectural Audit
+
+**Date:** {DATE}
+**Version audited:** v{VERSION} (`@optave/codegraph@{VERSION}`)
+**Commit:** {SHORT_SHA} ({branch name})
+**Auditor perspective:** Principal architect, cold evaluation
+**Methodology:** Codegraph self-analysis + manual source review + verified competitor research
+**Previous audit:** {link to previous audit if exists, or "First audit"}
+```
+
+Before writing, check `docs/architecture/` for previous audits. Reference changes since the last audit where relevant.
+
+## Steps
+
+### Phase 0 — Setup
+1. Read `package.json` to get the current version
+2. Get the current date, commit SHA, and branch name
+3. Check `docs/architecture/` for previous audit files
+4. **Read all ADRs in `docs/architecture/decisions/`.** These are the project's settled architectural decisions. Read every file — they document rationale, trade-offs, alternatives considered, and trajectory. The audit must evaluate the codebase *against* these decisions: are they being followed? Are the stated trade-offs still accurate? Has anything changed that invalidates the rationale?
+5. Run `codegraph build --no-incremental` to ensure fresh metrics
+
+### Phase 1 — Structural Census
+1. Run `codegraph stats` to get graph health baseline
+2. Run `codegraph structure --depth 3` to get directory cohesion
+3. Run `codegraph triage -T` to get the risk priority queue
+4. Run `codegraph roles --role dead -T` to find dead code — **then break down by kind** (function/method vs parameter/property/constant) to avoid inflating the dead count with leaf nodes
+5. Run `codegraph cycles` to check for circular dependencies
+6. Run `codegraph map` to see the module overview
+7. Run `codegraph complexity -T --limit 25` to find the most complex functions
+8. Count files, LOC, and test-to-source ratio
+
+### Phase 2 — Layer-by-Layer Critique
+For each architectural layer, evaluate against these dimensions:
+
+**A. Abstraction Quality**
+- Is the abstraction boundary clean or leaky?
+- Are there god objects / god files (>500 LOC)?
+- Is there needless indirection (wrappers that add no value)?
+
+**B. Coupling & Cohesion**
+- Fan-in / fan-out analysis per module
+- Are features truly independent or secretly coupled?
+- Is shared state minimized?
+
+**C. State-of-the-Art Comparison**
+- How does this layer compare to the equivalent in Sourcegraph, CodeScene, Joern, Semgrep, narsil-mcp, CKB?
+- What would a $500M code intelligence company do differently?
+- What academic research (ICSE, FSE, ASE) contradicts the design choices?
+
+**D. Scalability & Performance**
+- Will this hold up at 1M LOC? 10M LOC? Monorepo scale?
+- What are the algorithmic bottlenecks?
+- Is the database schema suitable for scale?
+
+**E. Correctness & Soundness**
+- Is the analysis sound or best-effort? (Be explicit)
+- What false positives / negatives does the approach inherently produce?
+- Where does the tool present incomplete data as complete?
+
+**F. ADR Compliance**
+- Does the implementation match the decisions documented in `docs/architecture/decisions/`?
+- Are the trade-offs described in ADRs still accurate given the current code?
+- Has the codebase drifted from any stated trajectory? If so, is that drift justified or accidental?
+- Are there architectural decisions that *should* have an ADR but don't?
+
+### Phase 3 — Cross-Cutting Concerns
+
+Evaluate these across the entire codebase:
+
+1. **Type Safety** — JS without TypeScript in 2026. Cost-benefit.
+2. **Error Handling** — Is it consistent? Are errors recoverable? Domain errors vs crashes.
+3. **Testing Strategy** — Are the right things tested? Integration-heavy vs unit-heavy tradeoffs.
+4. **Dual Engine Maintenance** — JS + Rust doing the same thing. Is this sustainable?
+5. **Dependency Hygiene** — Are deps minimal? Are there vendoring risks?
+6. **Security Surface** — execFileSync, MCP server exposure, SQLite injection vectors.
+7. **API Design** — Is the programmatic API well-designed for embedding?
+8. **Documentation** — Is it accurate? Does it lie by omission?
+
+### Phase 4 — Competitive Verification
+
+**Do not trust README claims.** For each top competitor:
+1. Fetch the actual GitHub repo README
+2. Cross-check feature claims against source code where possible
+3. Note: MCP-only vs CLI? Open source vs commercial? External deps required? Deterministic vs LLM-mediated?
+
+Include a verified competitor comparison table with columns: MCP tools, CLI, Open source, Zero-dep, Deterministic, Incremental (all langs).
+
+### Phase 5 — Strategic Verdict
+
+1. **Does codegraph have a reason to exist?** — Answer with verified data, not assumptions
+2. **Fundamental Design Flaws** — Decisions that cannot be fixed incrementally
+3. **Missed Opportunities** — What the tool should have been but isn't
+4. **Competitive Moat Assessment** — What actually differentiates this? Is it defensible?
+5. **Kill List** — Features/code that should be deleted, not improved
+6. **Build vs Buy** — Components that should use existing libraries instead of custom code
+7. **Roadmap Critique** — Is the planned roadmap the right path? What's missing? What's wrong?
+
+### Phase 6 — Write & Save
+
+1. Write the full audit to `docs/architecture/ARCHITECTURE_AUDIT_v{VERSION}_{DATE}.md`
+2. Copy to `generated/architecture/ARCHITECTURE_AUDIT_v{VERSION}_{DATE}.md`
+3. If a previous audit exists, add a "Changes Since Last Audit" section at the end comparing key metrics (graph quality score, complexity stats, dead code counts, competitive position)
+
+## Audit Structure
+
+The deliverable must contain:
+- "Does Codegraph Have a Reason to Exist?" section (verified competitor data)
+- Executive summary (1 paragraph, brutally honest)
+- Scorecard (each dimension rated 1-10 with justification)
+- **ADR compliance review** — for each ADR in `docs/architecture/decisions/`, assess whether the codebase follows the decision, whether the stated trade-offs are still valid, and whether any drift has occurred. Flag missing ADRs for decisions that exist in code but aren't documented
+- Detailed findings per layer
+- Verified competitor comparison table
+- Strategic recommendations (prioritized)
+- Comparison matrix vs state-of-the-art
+- Final verdict: would you invest in this project? Why or why not?
+
+## Rules
+- **No softening.** If something is bad, say it's bad and say why.
+- **Cite specifics.** File names, line counts, function names — not vague handwaving.
+- **Compare to real tools.** Not hypotheticals — actual production systems.
+- **Verify competitor claims.** Fetch READMEs, check source. Do not trust competitive analysis at face value.
+- **Quantify everything.** LOC, fan-in, complexity scores, not "high" or "low".
+- **Break down "dead" stats.** Separate leaf nodes (parameters, properties, constants) from genuinely unreferenced callables. Further categorize callable dead code by cause (Rust FFI, framework entry, dynamic dispatch, genuine dead).
+- **Assume the audience is a principal engineer** who has seen 100+ codebases.
diff --git a/docs/roadmap/ROADMAP.md b/docs/roadmap/ROADMAP.md
index 3f0c2abe..d195a97f 100644
--- a/docs/roadmap/ROADMAP.md
+++ b/docs/roadmap/ROADMAP.md
@@ -16,15 +16,16 @@ Codegraph is a strong local-first code graph CLI. This roadmap describes planned
 | [**2**](#phase-2--foundation-hardening) | Foundation Hardening | Parser registry, complete MCP, test coverage, enhanced config, multi-repo MCP | **Complete** (v1.5.0) |
 | [**2.5**](#phase-25--analysis-expansion) | Analysis Expansion | Complexity metrics, community detection, flow tracing, co-change, manifesto, boundary rules, check, triage, audit, batch, hybrid search | **Complete** (v2.7.0) |
 | [**2.7**](#phase-27--deep-analysis--graph-enrichment) | Deep Analysis & Graph Enrichment | Dataflow analysis, intraprocedural CFG, AST node storage, expanded node/edge types, extractors refactoring, CLI consolidation, interactive viewer, exports command, normalizeSymbol | **Complete** (v3.0.0) |
-| [**3**](#phase-3--architectural-refactoring) | Architectural Refactoring (Vertical Slice) | Unified AST analysis framework, command/query separation, repository pattern, queries.js decomposition, composable MCP, CLI commands, domain errors, builder pipeline, presentation layer, domain grouping, curated API, unified graph model, qualified names, CLI composability | **In Progress** (v3.1.4) |
-| [**4**](#phase-4--native-analysis-acceleration) | Native Analysis Acceleration | Move JS-only build phases (AST nodes, CFG, dataflow, insert nodes, structure, roles, complexity) to Rust; fix incremental rebuild data loss on native; sub-100ms 1-file rebuilds | Planned |
-| [**5**](#phase-5--typescript-migration) | TypeScript Migration | Project setup, core type definitions, leaf -> core -> orchestration module migration, test migration, supply-chain security, CI coverage gates | Planned |
-| [**6**](#phase-6--runtime--extensibility) | Runtime & Extensibility | Event-driven pipeline, unified engine strategy, subgraph export filtering, transitive confidence, query caching, configuration profiles, pagination, plugin system, DX & onboarding | Planned |
-| [**7**](#phase-7--intelligent-embeddings) | Intelligent Embeddings | LLM-generated descriptions, enhanced embeddings, build-time semantic metadata, module summaries | Planned |
-| [**8**](#phase-8--natural-language-queries) | Natural Language Queries | `ask` command, conversational sessions, LLM-narrated graph queries, onboarding tools | Planned |
-| [**9**](#phase-9--expanded-language-support) | Expanded Language Support | 8 new languages (11 -> 19), parser utilities | Planned |
-| [**10**](#phase-10--github-integration--ci) | GitHub Integration & CI | Reusable GitHub Action, LLM-enhanced PR review, visual impact graphs, SARIF output | Planned |
-| [**11**](#phase-11--interactive-visualization--advanced-features) | Visualization & Advanced | Web UI, dead code detection, monorepo, agentic search, refactoring analysis | Planned |
+| [**3**](#phase-3--architectural-refactoring) | Architectural Refactoring (Vertical Slice) | Unified AST analysis framework, command/query separation, repository pattern, queries.js decomposition, composable MCP, CLI commands, domain errors, builder pipeline, presentation layer, domain grouping, curated API, unified graph model, qualified names, CLI composability | **Complete** (v3.1.4) |
+| [**4**](#phase-4--typescript-migration) | TypeScript Migration | Project setup, core type definitions, leaf -> core -> orchestration module migration, test migration, supply-chain security, CI coverage gates | Planned |
+| [**5**](#phase-5--architectural-hardening) | Architectural Hardening | Method dispatch resolution, dead role sub-classification, SCIP/LSP integration for TS/Python/Go, DB schema hardening, graph model consolidation, auto-generated MCP schemas, precision benchmark suite | **In Progress** (5.1 phase 1 complete) |
+| [**6**](#phase-6--native-analysis-acceleration) | Native Analysis Acceleration | Move JS-only build phases (AST nodes, CFG, dataflow, insert nodes, structure, roles, complexity) to Rust; fix incremental rebuild data loss on native; sub-100ms 1-file rebuilds | Planned |
+| [**7**](#phase-7--runtime--extensibility) | Runtime & Extensibility | Event-driven pipeline, unified engine strategy, subgraph export filtering, transitive confidence, query caching, configuration profiles, pagination, plugin system, DX & onboarding | Planned |
+| [**8**](#phase-8--intelligent-embeddings) | Intelligent Embeddings | LLM-generated descriptions, enhanced embeddings, build-time semantic metadata, module summaries | Planned |
+| [**9**](#phase-9--natural-language-queries) | Natural Language Queries | `ask` command, conversational sessions, LLM-narrated graph queries, onboarding tools | Planned |
+| [**10**](#phase-10--expanded-language-support) | Expanded Language Support | Deep resolution for TS/Python/Go (via SCIP), tree-sitter fallback for remaining + 5 new languages (11 -> 16) | Planned |
+| [**11**](#phase-11--github-integration--ci) | GitHub Integration & CI | Reusable GitHub Action, LLM-enhanced PR review, visual impact graphs, SARIF output | Planned |
+| [**12**](#phase-12--interactive-visualization--advanced-features) | Visualization & Advanced | VS Code extension, dead code detection, monorepo, agentic search, refactoring analysis | Planned |
 
 ### Dependency graph
 
@@ -34,15 +35,17 @@ Phase 1 (Rust Core)
          |-->  Phase 2.5 (Analysis Expansion)
                 |-->  Phase 2.7 (Deep Analysis & Graph Enrichment)
                        |-->  Phase 3 (Architectural Refactoring)
-                              |-->  Phase 4 (Native Analysis Acceleration)
-                                     |-->  Phase 5 (TypeScript Migration)
-                                            |-->  Phase 6 (Runtime & Extensibility)
-                                            |-->  Phase 7 (Embeddings + Metadata)  -->  Phase 8 (NL Queries + Narration)
-                                            |-->  Phase 9 (Languages)
-                                            |-->  Phase 10 (GitHub/CI) <-- Phase 7 (risk_score, side_effects)
-Phases 1-8 -->  Phase 11 (Visualization + Refactoring Analysis)
+                              |-->  Phase 4 (TypeScript Migration)
+                                     |-->  Phase 5 (Architectural Hardening)
+                                            |-->  Phase 6 (Native Analysis Acceleration)
+                                                   |-->  Phase 7 (Runtime & Extensibility)
+                                                   |-->  Phase 8 (Embeddings + Metadata)  -->  Phase 9 (NL Queries)
+                                                   |-->  Phase 10 (Languages) <-- Phase 5 (SCIP/LSP)
+                                                   |-->  Phase 11 (GitHub/CI) <-- Phase 8 (risk_score, side_effects)
+Phases 1-9 -->  Phase 12 (Visualization + Refactoring Analysis)
 ```
 
+
 ---
 
 ## Phase 1 -- Rust Core ✅
@@ -111,6 +114,7 @@ Ensure the transition is seamless.
 
 **Result:** Zero breaking changes. Users get faster parsing automatically; nothing else changes.
 
+
 ---
 
 ## Phase 2 -- Foundation Hardening ✅
@@ -197,6 +201,7 @@ Support querying multiple codebases from a single MCP server instance.
 **New files:** `src/registry.js`
 **Affected files:** `src/mcp.js`, `src/cli.js`, `src/builder.js`, `src/index.js`
 
+
 ---
 
 ## Phase 2.5 -- Analysis Expansion ✅
@@ -359,6 +364,7 @@ MCP grew from 12 -> 25 tools, covering all new analysis capabilities.
 
 **Affected file:** `src/mcp.js` (grew from 354 -> 1,212 lines)
 
+
 ---
 
 ## Phase 2.7 -- Deep Analysis & Graph Enrichment ✅
@@ -554,11 +560,12 @@ Plus updated enums on existing tools (edge_kinds, symbol kinds).
 | Edge kinds | 6 | 9 | +3 |
 | Test files | 59 | 70 | +11 |
 
+
 ---
 
-## Phase 3 -- Architectural Refactoring 🔄
+## Phase 3 -- Architectural Refactoring ✅
 
-> **Status:** In Progress -- started in v3.1.1
+> **Status:** Complete -- shipped in v3.1.4
 
 **Goal:** Restructure the codebase for modularity, testability, and long-term maintainability. These are internal improvements -- no new user-facing features, but they make every subsequent phase easier to build and maintain.
 
@@ -991,128 +998,16 @@ Practical cleanup to make the CLI surface match the internal composability that
 
 **Affected files:** `src/cli/commands/*.js`, `src/cli/shared/`, `src/presentation/result-formatter.js`
 
----
-
-## Phase 4 -- Native Analysis Acceleration
-
-**Goal:** Move the remaining JS-only build phases to Rust so that `--engine native` eliminates all redundant WASM visitor walks. Today only 3 of 10 build phases (parse, resolve imports, build edges) run in Rust — the other 7 execute identical JavaScript regardless of engine, leaving ~50% of native build time on the table.
-
-**Why its own phase:** This is a substantial Rust engineering effort — porting 6 JS visitors to `crates/codegraph-core/`, fixing a data loss bug in incremental rebuilds, and optimizing the 1-file rebuild path. Doing this before the TS migration avoids rewriting the same visitor code twice (once to TS, once to Rust). The Phase 3 module boundaries make each phase a self-contained target.
-
-**Evidence (v3.1.4 benchmarks on 398 files):**
-
-| Phase | Native | WASM | Ratio | Status |
-|-------|-------:|-----:|------:|--------|
-| Parse | 468ms | 1483ms | 3.2x faster | Already Rust |
-| Build edges | 88ms | 152ms | 1.7x faster | Already Rust |
-| Resolve imports | 8ms | 9ms | ~1x | Already Rust |
-| **AST nodes** | **361ms** | **347ms** | **~1x** | JS visitor — biggest win |
-| **CFG** | **126ms** | **125ms** | **~1x** | JS visitor |
-| **Dataflow** | **100ms** | **98ms** | **~1x** | JS visitor |
-| **Insert nodes** | **143ms** | **148ms** | **~1x** | Pure SQLite batching |
-| **Roles** | **29ms** | **32ms** | **~1x** | JS classification |
-| **Structure** | **13ms** | **17ms** | **~1x** | JS directory tree |
-| Complexity | 16ms | 77ms | 5x faster | Partly pre-computed |
-
-**Target:** Reduce native full-build time from ~1,400ms to ~700ms (2x improvement) by eliminating ~690ms of redundant JS visitor work.
-
-### 4.1 -- AST Node Extraction in Rust
-
-The largest single opportunity. Currently the native parser returns partial AST node data, so the JS `buildAstNodes()` visitor re-walks all WASM trees anyway (~361ms).
-
-- Extend `crates/codegraph-core/` to extract all AST node types (`call`, `new`, `string`, `regex`, `throw`, `await`) during the native parse phase
-- Return complete AST node data in the `FileSymbols` result so `run-analyses.js` can skip the WASM walker entirely
-- Validate parity: ensure native extraction produces identical node counts to the WASM visitor (benchmark already tracks this via `nodes/file`)
-
-**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/ast.js`, `src/domain/graph/builder/stages/run-analyses.js`
-
-### 4.2 -- CFG Construction in Rust
-
-The intraprocedural control-flow graph visitor runs in JS even on native builds (~126ms).
-
-- Port `createCfgVisitor()` logic to Rust: basic block detection, branch/loop edges, entry/exit nodes
-- Return CFG block data per function in `FileSymbols` so the JS visitor is fully bypassed
-- Validate parity: CFG block counts and edge counts must match the WASM visitor output
-
-**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/cfg.js`, `src/ast-analysis/visitors/cfg-visitor.js`
-
-### 4.3 -- Dataflow Analysis in Rust
-
-Dataflow edges are computed by a JS visitor that walks WASM trees (~100ms on native builds).
-
-- Port `createDataflowVisitor()` to Rust: variable definitions, assignments, reads, def-use chains
-- Return dataflow edges in `FileSymbols`
-- Validate parity against WASM visitor output
-
-**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/dataflow.js`, `src/ast-analysis/visitors/dataflow-visitor.js`
-
-### 4.4 -- Batch SQLite Inserts via Rust
-
-`insertNodes` is pure SQLite work (~143ms) but runs row-by-row from JS. Batching in Rust can reduce JS↔native boundary crossings.
-
-- Expose a `batchInsertNodes(nodes[])` function from Rust that uses a single prepared statement in a transaction
-- Alternatively, generate the SQL batch on the JS side and execute as a single `better-sqlite3` call (may be sufficient without Rust)
-- Benchmark both approaches; pick whichever is faster
-
-**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/db/index.js`, `src/domain/graph/builder/stages/insert-nodes.js`
-
-### 4.5 -- Role Classification & Structure in Rust
-
-Smaller wins (~42ms combined) but complete the picture of a fully native build pipeline.
-
-- Port `classifyNodeRoles()` to Rust: hub/leaf/bridge/utility classification based on in/out degree and betweenness
-- Port directory structure building and metrics aggregation
-- Return role assignments and structure data alongside parse results
-
-**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/structure.js`, `src/domain/graph/builder/stages/build-structure.js`
-
-### 4.6 -- Complete Complexity Pre-computation
-
-Complexity is partly pre-computed by native (~16ms vs 77ms WASM) but not all functions are covered.
-
-- Ensure native parse computes cognitive, cyclomatic, Halstead, and MI metrics for every function, not just a subset
-- Eliminate the WASM fallback path in `buildComplexityMetrics()` when running native
-
-**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/complexity.js`
-
-### 4.7 -- Fix Incremental Rebuild Data Loss on Native Engine
-
-**Bug:** On native 1-file rebuilds, complexity, CFG, and dataflow data for the changed file is **silently lost**. `purgeFilesFromGraph` removes the old data, but the analysis phases never re-compute it because:
-
-1. The native parser does not produce a `_tree` (WASM tree-sitter tree)
-2. The unified walker at `src/ast-analysis/engine.js:108-109` skips files without `_tree`
-3. The `buildXxx` functions check for pre-computed fields (`d.complexity`, `d.cfg?.blocks`) which the native parser does not provide for these analyses
-4. Result: 0.1ms no-op — the phases run but do nothing
-
-This is confirmed by the v3.1.4 1-file rebuild data: complexity (0.1ms), CFG (0.1ms), dataflow (0.2ms) on native — these are just module import overhead, not actual computation. Contrast with v3.1.3 where the numbers were higher (1.3ms, 8.7ms, 4ms) because earlier versions triggered a WASM fallback tree via `ensureWasmTrees`.
-
-**Fix (prerequisite: 4.1–4.3):** Once the native parser returns complete AST nodes, CFG blocks, and dataflow edges in `FileSymbols`, the `run-analyses` stage can store them directly without needing a WASM tree. The incremental path must:
-
-- Ensure `parseFilesAuto()` returns pre-computed analysis data for the single changed file
-- Have `run-analyses.js` store that data (currently it only stores if `_tree` exists or if pre-computed fields are present — the latter path needs to work reliably)
-- Add an integration test: rebuild 1 file on native engine, then query its complexity/CFG/dataflow and assert non-empty results
-
-**Affected files:** `src/ast-analysis/engine.js`, `src/domain/graph/builder/stages/run-analyses.js`, `src/domain/parser.js`, `tests/integration/`
-
-### 4.8 -- Incremental Rebuild Performance
-
-With analysis data loss fixed, optimize the 1-file rebuild path end-to-end. Current native 1-file rebuild is 265ms — dominated by parse (51ms), structure (13ms), roles (27ms), edges (13ms), insert (12ms), and finalize (12ms).
-
-- **Skip unchanged phases:** Structure and roles are graph-wide computations. On a 1-file change, only the changed file's nodes/edges need updating — skip full reclassification unless the file's degree changed significantly
-- **Incremental edge rebuild:** Only rebuild edges involving the changed file's symbols, not the full edge set
-- **Benchmark target:** Sub-100ms native 1-file rebuilds (from current 265ms)
-
-**Affected files:** `src/domain/graph/builder/stages/build-structure.js`, `src/domain/graph/builder/stages/build-edges.js`, `src/domain/graph/builder/pipeline.js`
 
 ---
 
-## Phase 5 -- TypeScript Migration
+## Phase 4 -- TypeScript Migration
 
 **Goal:** Migrate the codebase from plain JavaScript to TypeScript, leveraging the clean module boundaries established in Phase 3. Incremental module-by-module migration starting from leaf modules inward.
 
-**Why after Phase 4:** The architectural refactoring (Phase 3) creates small, well-bounded modules with explicit interfaces. Phase 4 moves the remaining hot-path visitor code to Rust — doing TS migration first would mean rewriting those visitors to TypeScript only to delete them when porting to Rust. With both phases complete, the JS layer is purely orchestration and presentation, which is the ideal surface for TypeScript.
+**Why now (before Native Acceleration):** The architectural audit (v3.1.4) identified type safety as the highest-leverage improvement. TypeScript provides typed interfaces that define exactly what the Rust native engine must return — porting to Rust before having those contracts means building against untyped, shifting interfaces. TypeScript also catches the class of bugs that currently require runtime discovery (wrong argument order, missing properties, implicit any).
 
-### 5.1 -- Project Setup
+### 4.1 -- Project Setup
 
 - Add `typescript` as a devDependency
 - Create `tsconfig.json` with strict mode, ES module output, path aliases matching the Phase 3 module structure
@@ -1123,7 +1018,7 @@ With analysis data loss fixed, optimize the 1-file rebuild path end-to-end. Curr
 
 **Affected files:** `package.json`, `biome.json`, new `tsconfig.json`
 
-### 5.2 -- Core Type Definitions
+### 4.2 -- Core Type Definitions
 
 Define TypeScript interfaces for all abstractions introduced in Phase 3:
 
@@ -1151,7 +1046,7 @@ These interfaces serve as the migration contract -- each module is migrated to s
 
 **New file:** `src/types.ts`
 
-### 5.3 -- Leaf Module Migration
+### 4.3 -- Leaf Module Migration
 
 Migrate modules with no internal dependencies first:
 
@@ -1168,7 +1063,7 @@ Migrate modules with no internal dependencies first:
 
 Allow `.js` and `.ts` to coexist during migration (`allowJs: true` in tsconfig).
 
-### 5.4 -- Core Module Migration
+### 4.4 -- Core Module Migration
 
 Migrate modules that implement Phase 3 interfaces:
 
@@ -1183,7 +1078,7 @@ Migrate modules that implement Phase 3 interfaces:
 | `src/analysis/*.ts` | Typed analysis results (impact scores, call chains) |
 | `src/resolve.ts` | Import resolution with confidence types |
 
-### 5.5 -- Orchestration & Public API Migration
+### 4.5 -- Orchestration & Public API Migration
 
 Migrate top-level orchestration and entry points:
 
@@ -1196,7 +1091,7 @@ Migrate top-level orchestration and entry points:
 | `src/cli/*.ts` | Command objects with typed options |
 | `src/index.ts` | Curated public API with proper export types |
 
-### 5.6 -- Test Migration
+### 4.6 -- Test Migration
 
 - Migrate test files from `.js` to `.ts`
 - Add type-safe test utilities and fixture builders
@@ -1207,7 +1102,7 @@ Migrate top-level orchestration and entry points:
 
 **Affected files:** All `src/**/*.js` -> `src/**/*.ts`, all `tests/**/*.js` -> `tests/**/*.ts`, `package.json`, `biome.json`
 
-### 5.7 -- Supply-Chain Security & Audit
+### 4.7 -- Supply-Chain Security & Audit
 
 **Gap:** No `npm audit` in CI pipeline. No supply-chain attestation (SLSA/SBOM). No formal security audit history.
 
@@ -1220,33 +1115,248 @@ Migrate top-level orchestration and entry points:
 
 **Affected files:** `.github/workflows/ci.yml`, `.github/workflows/publish.yml`, `docs/security/`
 
-### 5.8 -- CI Test Quality & Coverage Gates
+### 4.8 -- CI Test Quality & Coverage Gates
 
 **Gaps:**
 
 - No coverage thresholds enforced in CI (coverage report runs locally only)
 - Embedding tests in separate workflow requiring HuggingFace token
 - 312 `setTimeout`/`sleep` instances in tests — potential flakiness under load
-- No dependency audit step in CI (see also [5.7](#57----supply-chain-security--audit))
+- No dependency audit step in CI (see also [4.7](#47----supply-chain-security--audit))
 
 **Deliverables:**
 
 1. **Coverage gate** -- add `vitest --coverage` to CI with minimum threshold (e.g. 80% lines/branches); fail the pipeline when coverage drops below the threshold
 2. **Unified test workflow** -- merge embedding tests into the main CI workflow using a securely stored `HF_TOKEN` secret; eliminate the separate workflow
 3. **Timer cleanup** -- audit and reduce `setTimeout`/`sleep` usage in tests; replace with deterministic waits (event-based, polling with backoff, or `vi.useFakeTimers()`) to reduce flakiness
-4. > _Dependency audit step is covered by [5.7](#57----supply-chain-security--audit) deliverable 1._
+4. > _Dependency audit step is covered by [4.7](#47----supply-chain-security--audit) deliverable 1._
 
 **Affected files:** `.github/workflows/ci.yml`, `vitest.config.js`, `tests/`
 
+
+---
+
+## Phase 5 -- Architectural Hardening
+
+**Goal:** Close the correctness and precision gaps identified in the v3.1.4 architectural audit before investing in performance (Native Acceleration) or new features. These are the structural fixes that make every subsequent phase more reliable.
+
+**Why now:** The audit found ~73-80% static call resolution, method dispatch as the primary gap, and 509 genuinely unreferenced callable symbols (many explainable by Rust FFI, framework entries, and dynamic dispatch). Fixing these before native acceleration means the Rust engine has clear, typed contracts to implement. Fixing before new features means those features build on accurate data.
+
+### 5.1 -- Method Dispatch Resolution
+
+The biggest call graph gap. Previously, `obj.method()` calls resolved to ANY exported method in scope — no receiver type tracking. Repository pattern calls (`this.repo.find()`), builder chains, and interface-dispatched methods were missed entirely.
+
+**Phase 1 (receiver type tracking) — Complete:**
+- ✅ Per-file type map built from variable-to-type assignments during extraction
+- ✅ Constructor assignments: `const x = new Foo()` → `x.method()` resolves to `Foo.method` (confidence 1.0)
+- ✅ Type annotations (TS): `const x: Foo = ...` → confidence 0.9
+- ✅ Factory methods: `const x = Foo.create()` → confidence 0.7 (uppercase-first heuristic)
+- ✅ Go patterns: composite literals (`x := Foo{}`), var declarations (`var x Foo`), `NewFoo()` factories
+- ✅ Python patterns: constructor calls (`x = Foo()`), type annotations (`x: Foo = ...`), factory calls
+- ✅ Type map used for both call edge resolution (qualified `ClassName.method` lookup) and receiver edge precision
+- ✅ Extractors: JS/TS, Python, Go all return `typeAssignments`; edge builder consumes them; native engine path forwards them
+
+**Phase 2 (remaining — planned):**
+- Handle `this.field` tracking within class bodies (`this.service = new AuthService()` in constructor)
+- Builder chain resolution (fluent API patterns where each method returns `this`)
+- Interface-dispatched methods (variable typed as interface, resolve to all implementing methods)
+- **Target:** Improve call resolution from ~80% to ~90%+ for static JS/TS codebases
+
+**Affected files:** `src/extractors/javascript.js`, `src/extractors/python.js`, `src/extractors/go.js`, `src/domain/graph/builder/stages/build-edges.js`
+
+### 5.2 -- Dead Role Sub-Classification
+
+The audit showed 3,408 "dead" symbols but 2,899 are leaf nodes (parameters, properties, constants) — not resolution failures. The remaining 509 callable dead symbols break down into Rust FFI exports (151), framework entry points (94), dynamic dispatch targets (170+), and genuinely dead code (~94).
+
+- Sub-classify dead symbols: `dead:leaf`, `dead:ffi`, `dead:entry`, `dead:dynamic`, `dead:genuine`
+- Use heuristics: exported from `crates/` → FFI, decorated with framework markers → entry, has no static callers but is a method on a class with callers → dynamic
+- `codegraph roles --role dead` shows the breakdown by sub-class
+- `codegraph roles --role dead:genuine` filters to only genuinely unreferenced code
+- Update MCP `node_roles` tool to support sub-classification
+
+**Affected files:** `src/graph/classifiers/role-classifier.js`, `src/domain/analysis/roles.js`
+
+### 5.3 -- SCIP/LSP Integration for TS/Python/Go
+
+For languages with mature SCIP indexers (TypeScript via scip-typescript, Python via scip-python, Go via scip-go), use SCIP index data to get precise cross-reference resolution instead of heuristic matching.
+
+- Detect if a SCIP index (`.scip` file) exists in the project root
+- Parse SCIP occurrences to build a precise symbol → definition → reference map
+- Use SCIP data as the highest-priority resolution source (confidence 1.0), falling back to tree-sitter heuristics when unavailable
+- `codegraph build --scip <path>` to explicitly provide a SCIP index
+- Document how to generate SCIP indexes for each supported language
+
+**Affected files:** `src/domain/graph/resolve.js`, new `src/infrastructure/scip.js`
+
+### 5.4 -- DB Schema Hardening
+
+The audit flagged missing foreign keys, no WAL mode, and no index coverage analysis.
+
+- Enable WAL mode by default for concurrent read access (MCP sessions reading while builds write)
+- Add foreign key constraints (`edges.source` → `nodes.id`, `edges.target` → `nodes.id`) with `ON DELETE CASCADE`
+- Add covering indexes for the most common query patterns (identified via `EXPLAIN QUERY PLAN` on top 10 queries)
+- Add `PRAGMA integrity_check` to `codegraph check` command
+- Migration path: new schema version with `ALTER TABLE` for existing databases
+
+**Affected files:** `src/db/migrations.js`, `src/db/connection.js`
+
+### 5.5 -- Graph Model Consolidation
+
+`src/graph/model.js` (230 LOC) reimplements `addNode`, `addEdge`, `successors`, `predecessors` that `graphology` (already a dependency) provides natively. This is pure maintenance cost with no benefit.
+
+- Replace `CodeGraph` internals with `graphology` as the backing store
+- Keep the `CodeGraph` public API unchanged (or simplify it to delegate directly)
+- Eliminate the custom adjacency list, the manual `_inEdges`/`_outEdges` maps
+- `toGraphology()` becomes a no-op (returns `this._graph`)
+- Benchmark: ensure no regression in graph algorithm performance
+
+**Affected files:** `src/graph/model.js`
+
+### 5.6 -- Auto-Generated MCP Schemas
+
+MCP tool schemas are currently hand-maintained JSON objects. When a CLI command adds a parameter, the MCP schema must be manually updated — a common source of drift.
+
+- Generate MCP tool `inputSchema` from the Commander option definitions in `src/cli.js`
+- Single source of truth: CLI defines parameters, MCP schemas are derived
+- Validate at startup: MCP schema matches CLI options (fail-fast on drift)
+
+**Affected files:** `src/mcp/`, `src/cli.js`
+
+### 5.7 -- Precision Benchmark Suite
+
+The audit revealed that call resolution accuracy (~73-80%) is asserted by manual spot-checks, not automated benchmarks. Without a benchmark suite, regressions in resolution quality go undetected.
+
+- Create a benchmark fixture with known call graphs (manually verified ground truth)
+- Measure: precision (% of reported edges that are correct), recall (% of real edges that are found)
+- Track per-language: JS, TS, Python, Go, Rust, Java
+- Run in CI: fail if precision drops below threshold (e.g., 95%) or recall drops below threshold (e.g., 70%)
+- Report resolution accuracy in `codegraph stats` output
+
+**New files:** `tests/benchmarks/resolution-accuracy/`, `tests/fixtures/resolution-benchmark/`
+
+---
+
+## Phase 6 -- Native Analysis Acceleration
+
+**Goal:** Move the remaining JS-only build phases to Rust so that `--engine native` eliminates all redundant WASM visitor walks. Today only 3 of 10 build phases (parse, resolve imports, build edges) run in Rust — the other 7 execute identical JavaScript regardless of engine, leaving ~50% of native build time on the table.
+
+**Why Phase 6 (not earlier):** The TypeScript migration (Phase 4) provides typed interfaces that define exactly what the Rust side must return. The Architectural Hardening (Phase 5) fixes method dispatch and adds SCIP integration — both inform what the native engine needs to support. Porting to Rust before these phases means building against untyped, shifting contracts.
+
+**Evidence (v3.1.4 benchmarks on 398 files):**
+
+| Phase | Native | WASM | Ratio | Status |
+|-------|-------:|-----:|------:|--------|
+| Parse | 468ms | 1483ms | 3.2x faster | Already Rust |
+| Build edges | 88ms | 152ms | 1.7x faster | Already Rust |
+| Resolve imports | 8ms | 9ms | ~1x | Already Rust |
+| **AST nodes** | **361ms** | **347ms** | **~1x** | JS visitor — biggest win |
+| **CFG** | **126ms** | **125ms** | **~1x** | JS visitor |
+| **Dataflow** | **100ms** | **98ms** | **~1x** | JS visitor |
+| **Insert nodes** | **143ms** | **148ms** | **~1x** | Pure SQLite batching |
+| **Roles** | **29ms** | **32ms** | **~1x** | JS classification |
+| **Structure** | **13ms** | **17ms** | **~1x** | JS directory tree |
+| Complexity | 16ms | 77ms | 5x faster | Partly pre-computed |
+
+**Target:** Reduce native full-build time from ~1,400ms to ~700ms (2x improvement) by eliminating ~690ms of redundant JS visitor work.
+
+### 6.1 -- AST Node Extraction in Rust
+
+The largest single opportunity. Currently the native parser returns partial AST node data, so the JS `buildAstNodes()` visitor re-walks all WASM trees anyway (~361ms).
+
+- Extend `crates/codegraph-core/` to extract all AST node types (`call`, `new`, `string`, `regex`, `throw`, `await`) during the native parse phase
+- Return complete AST node data in the `FileSymbols` result so `run-analyses.js` can skip the WASM walker entirely
+- Validate parity: ensure native extraction produces identical node counts to the WASM visitor (benchmark already tracks this via `nodes/file`)
+
+**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/ast.js`, `src/domain/graph/builder/stages/run-analyses.js`
+
+### 6.2 -- CFG Construction in Rust
+
+The intraprocedural control-flow graph visitor runs in JS even on native builds (~126ms).
+
+- Port `createCfgVisitor()` logic to Rust: basic block detection, branch/loop edges, entry/exit nodes
+- Return CFG block data per function in `FileSymbols` so the JS visitor is fully bypassed
+- Validate parity: CFG block counts and edge counts must match the WASM visitor output
+
+**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/cfg.js`, `src/ast-analysis/visitors/cfg-visitor.js`
+
+### 6.3 -- Dataflow Analysis in Rust
+
+Dataflow edges are computed by a JS visitor that walks WASM trees (~100ms on native builds).
+
+- Port `createDataflowVisitor()` to Rust: variable definitions, assignments, reads, def-use chains
+- Return dataflow edges in `FileSymbols`
+- Validate parity against WASM visitor output
+
+**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/dataflow.js`, `src/ast-analysis/visitors/dataflow-visitor.js`
+
+### 6.4 -- Batch SQLite Inserts via Rust
+
+`insertNodes` is pure SQLite work (~143ms) but runs row-by-row from JS. Batching in Rust can reduce JS↔native boundary crossings.
+
+- Expose a `batchInsertNodes(nodes[])` function from Rust that uses a single prepared statement in a transaction
+- Alternatively, generate the SQL batch on the JS side and execute as a single `better-sqlite3` call (may be sufficient without Rust)
+- Benchmark both approaches; pick whichever is faster
+
+**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/db/index.js`, `src/domain/graph/builder/stages/insert-nodes.js`
+
+### 6.5 -- Role Classification & Structure in Rust
+
+Smaller wins (~42ms combined) but complete the picture of a fully native build pipeline.
+
+- Port `classifyNodeRoles()` to Rust: hub/leaf/bridge/utility classification based on in/out degree and betweenness
+- Port directory structure building and metrics aggregation
+- Return role assignments and structure data alongside parse results
+
+**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/structure.js`, `src/domain/graph/builder/stages/build-structure.js`
+
+### 6.6 -- Complete Complexity Pre-computation
+
+Complexity is partly pre-computed by native (~16ms vs 77ms WASM) but not all functions are covered.
+
+- Ensure native parse computes cognitive, cyclomatic, Halstead, and MI metrics for every function, not just a subset
+- Eliminate the WASM fallback path in `buildComplexityMetrics()` when running native
+
+**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/complexity.js`
+
+### 6.7 -- Fix Incremental Rebuild Data Loss on Native Engine
+
+**Bug:** On native 1-file rebuilds, complexity, CFG, and dataflow data for the changed file is **silently lost**. `purgeFilesFromGraph` removes the old data, but the analysis phases never re-compute it because:
+
+1. The native parser does not produce a `_tree` (WASM tree-sitter tree)
+2. The unified walker at `src/ast-analysis/engine.js:108-109` skips files without `_tree`
+3. The `buildXxx` functions check for pre-computed fields (`d.complexity`, `d.cfg?.blocks`) which the native parser does not provide for these analyses
+4. Result: 0.1ms no-op — the phases run but do nothing
+
+This is confirmed by the v3.1.4 1-file rebuild data: complexity (0.1ms), CFG (0.1ms), dataflow (0.2ms) on native — these are just module import overhead, not actual computation. Contrast with v3.1.3 where the numbers were higher (1.3ms, 8.7ms, 4ms) because earlier versions triggered a WASM fallback tree via `ensureWasmTrees`.
+
+**Fix (prerequisite: 4.1–4.3):** Once the native parser returns complete AST nodes, CFG blocks, and dataflow edges in `FileSymbols`, the `run-analyses` stage can store them directly without needing a WASM tree. The incremental path must:
+
+- Ensure `parseFilesAuto()` returns pre-computed analysis data for the single changed file
+- Have `run-analyses.js` store that data (currently it only stores if `_tree` exists or if pre-computed fields are present — the latter path needs to work reliably)
+- Add an integration test: rebuild 1 file on native engine, then query its complexity/CFG/dataflow and assert non-empty results
+
+**Affected files:** `src/ast-analysis/engine.js`, `src/domain/graph/builder/stages/run-analyses.js`, `src/domain/parser.js`, `tests/integration/`
+
+### 6.8 -- Incremental Rebuild Performance
+
+With analysis data loss fixed, optimize the 1-file rebuild path end-to-end. Current native 1-file rebuild is 265ms — dominated by parse (51ms), structure (13ms), roles (27ms), edges (13ms), insert (12ms), and finalize (12ms).
+
+- **Skip unchanged phases:** Structure and roles are graph-wide computations. On a 1-file change, only the changed file's nodes/edges need updating — skip full reclassification unless the file's degree changed significantly
+- **Incremental edge rebuild:** Only rebuild edges involving the changed file's symbols, not the full edge set
+- **Benchmark target:** Sub-100ms native 1-file rebuilds (from current 265ms)
+
+**Affected files:** `src/domain/graph/builder/stages/build-structure.js`, `src/domain/graph/builder/stages/build-edges.js`, `src/domain/graph/builder/pipeline.js`
+
+
 ---
 
-## Phase 6 -- Runtime & Extensibility
+## Phase 7 -- Runtime & Extensibility
 
-**Goal:** Harden the runtime for large codebases and open the platform to external contributors. These items were deferred from Phase 3 -- they depend on the clean module boundaries and domain layering established there, and benefit from TypeScript's type safety (Phase 5) for safe refactoring of cross-cutting concerns like caching, streaming, and plugin contracts.
+**Goal:** Harden the runtime for large codebases and open the platform to external contributors. These items were deferred from Phase 3 -- they depend on the clean module boundaries and domain layering established there, and benefit from TypeScript's type safety (Phase 4) for safe refactoring of cross-cutting concerns like caching, streaming, and plugin contracts.
 
 **Why after TypeScript Migration:** Several of these items introduce new internal contracts (plugin API, cache interface, streaming protocol, engine strategy). Defining those contracts in TypeScript from the start avoids a second migration pass and gives contributors type-checked extension points.
 
-### 6.1 -- Event-Driven Pipeline
+### 7.1 -- Event-Driven Pipeline
 
 Replace the synchronous build/analysis pipeline with an event/streaming architecture. Enables progress reporting, cancellation tokens, and bounded memory usage on large repositories (10K+ files).
 
@@ -1258,7 +1368,7 @@ Replace the synchronous build/analysis pipeline with an event/streaming architec
 
 **Affected files:** `src/domain/graph/builder.js`, `src/cli/`, `src/mcp/`
 
-### 6.2 -- Unified Engine Interface (Strategy Pattern)
+### 7.2 -- Unified Engine Interface (Strategy Pattern)
 
 Replace scattered `engine.name === 'native'` / `engine === 'wasm'` branching throughout the codebase with a formal Strategy pattern. Each engine implements a common `ParsingEngine` interface with methods like `parse(file)`, `batchParse(files)`, `supports(language)`, and `capabilities()`.
 
@@ -1270,7 +1380,7 @@ Replace scattered `engine.name === 'native'` / `engine === 'wasm'` branching thr
 
 **Affected files:** `src/infrastructure/native.js`, `src/domain/parser.js`, `src/domain/graph/builder.js`
 
-### 6.3 -- Subgraph Export Filtering
+### 7.3 -- Subgraph Export Filtering
 
 Add focus and depth controls to `codegraph export` so users can produce usable visualizations of specific subsystems rather than the entire graph.
 
@@ -1287,7 +1397,7 @@ codegraph export --focus "buildGraph" --depth 3 --format dot
 
 **Affected files:** `src/features/export.js`, `src/presentation/export.js`
 
-### 6.4 -- Transitive Import-Aware Confidence
+### 7.4 -- Transitive Import-Aware Confidence
 
 Improve import resolution accuracy by walking the import graph before falling back to proximity heuristics. Currently the 6-level priority system uses directory proximity as a strong signal, but this can mis-resolve when a symbol is re-exported through an index file several directories away.
 
@@ -1298,7 +1408,7 @@ Improve import resolution accuracy by walking the import graph before falling ba
 
 **Affected files:** `src/domain/graph/resolve.js`
 
-### 6.5 -- Query Result Caching
+### 7.5 -- Query Result Caching
 
 Add an LRU/TTL cache layer between the analysis/query functions and the SQLite repository. With 34+ MCP tools that often run overlapping queries within a session, caching eliminates redundant DB round-trips.
 
@@ -1311,7 +1421,7 @@ Add an LRU/TTL cache layer between the analysis/query functions and the SQLite r
 
 **Affected files:** `src/domain/analysis/`, `src/db/index.js`
 
-### 6.6 -- Configuration Profiles
+### 7.6 -- Configuration Profiles
 
 Support named configuration profiles for monorepos and multi-service projects where different parts of the codebase need different settings.
 
@@ -1332,7 +1442,7 @@ Support named configuration profiles for monorepos and multi-service projects wh
 
 **Affected files:** `src/infrastructure/config.js`, `src/cli/`
 
-### 6.7 -- Pagination Standardization
+### 7.7 -- Pagination Standardization
 
 Standardize SQL-level `LIMIT`/`OFFSET` pagination across all repository queries and surface it consistently through the CLI and MCP.
 
@@ -1344,7 +1454,7 @@ Standardize SQL-level `LIMIT`/`OFFSET` pagination across all repository queries
 
 **Affected files:** `src/shared/paginate.js`, `src/db/index.js`, `src/domain/analysis/`, `src/mcp/`
 
-### 6.8 -- Plugin System for Custom Commands
+### 7.8 -- Plugin System for Custom Commands
 
 Allow users to extend codegraph with custom commands by dropping a JS/TS module into `~/.codegraph/plugins/` (global) or `.codegraph/plugins/` (project-local).
 
@@ -1372,7 +1482,7 @@ export function data(db: Database, args: ParsedArgs, config: Config): object {
 
 **Affected files:** `src/cli/`, `src/mcp/`, new `src/infrastructure/plugins.js`
 
-### 6.9 -- Developer Experience & Onboarding
+### 7.9 -- Developer Experience & Onboarding
 
 Lower the barrier to first successful use. Today codegraph requires manual install, manual config, and prior knowledge of which command to run next.
 
@@ -1384,15 +1494,16 @@ Lower the barrier to first successful use. Today codegraph requires manual insta
 
 **Affected files:** new `src/cli/commands/init.js`, `docs/benchmarks/`, `docs/editors/`, `src/presentation/result-formatter.js`
 
+
 ---
 
-## Phase 7 -- Intelligent Embeddings
+## Phase 8 -- Intelligent Embeddings
 
 **Goal:** Dramatically improve semantic search quality by embedding natural-language descriptions instead of raw code.
 
-> **Phase 7.3 (Hybrid Search) was completed early** during Phase 2.5 -- FTS5 BM25 + semantic search with RRF fusion is already shipped in v2.7.0.
+> **Phase 8.3 (Hybrid Search) was completed early** during Phase 2.5 -- FTS5 BM25 + semantic search with RRF fusion is already shipped in v2.7.0.
 
-### 7.1 -- LLM Description Generator
+### 8.1 -- LLM Description Generator
 
 For each function/method/class node, generate a concise natural-language description:
 
@@ -1420,7 +1531,7 @@ For each function/method/class node, generate a concise natural-language descrip
 
 **New file:** `src/describer.js`
 
-### 7.2 -- Enhanced Embedding Pipeline
+### 8.2 -- Enhanced Embedding Pipeline
 
 - When descriptions exist, embed the description text instead of raw code
 - Keep raw code as fallback when no description is available
@@ -1431,11 +1542,11 @@ For each function/method/class node, generate a concise natural-language descrip
 
 **Affected files:** `src/embedder.js`
 
-### ~~7.3 -- Hybrid Search~~ ✅ Completed in Phase 2.5
+### ~~8.3 -- Hybrid Search~~ ✅ Completed in Phase 2.5
 
 Shipped in v2.7.0. FTS5 BM25 keyword search + semantic vector search with RRF fusion. Three search modes: `hybrid` (default), `semantic`, `keyword`.
 
-### 7.4 -- Build-time Semantic Metadata
+### 8.4 -- Build-time Semantic Metadata
 
 Enrich nodes with LLM-generated metadata beyond descriptions. Computed incrementally at build time (only for changed nodes), stored as columns on the `nodes` table.
 
@@ -1448,9 +1559,9 @@ Enrich nodes with LLM-generated metadata beyond descriptions. Computed increment
 - MCP tool: `assess <name>` -- returns complexity rating + specific concerns
 - Cascade invalidation: when a node changes, mark dependents for re-enrichment
 
-**Depends on:** 7.1 (LLM provider abstraction)
+**Depends on:** 8.1 (LLM provider abstraction)
 
-### 7.5 -- Module Summaries
+### 8.5 -- Module Summaries
 
 Aggregate function descriptions + dependency direction into file-level narratives.
 
@@ -1462,13 +1573,14 @@ Aggregate function descriptions + dependency direction into file-level narrative
 
 > **Full spec:** See [llm-integration.md](./llm-integration.md) for detailed architecture, infrastructure table, and prompt design.
 
+
 ---
 
-## Phase 8 -- Natural Language Queries
+## Phase 9 -- Natural Language Queries
 
 **Goal:** Allow developers to ask questions about their codebase in plain English.
 
-### 8.1 -- Query Engine
+### 9.1 -- Query Engine
 
 ```bash
 codegraph ask "How does the authentication flow work?"
@@ -1494,7 +1606,7 @@ codegraph ask "How does the authentication flow work?"
 
 **New file:** `src/nlquery.js`
 
-### 8.2 -- Conversational Sessions
+### 9.2 -- Conversational Sessions
 
 Multi-turn conversations with session memory.
 
@@ -1508,7 +1620,7 @@ codegraph sessions clear
 - Store conversation history in SQLite table `sessions`
 - Include prior Q&A pairs in subsequent prompts
 
-### 8.3 -- MCP Integration
+### 9.3 -- MCP Integration
 
 New MCP tool: `ask_codebase` -- natural language query via MCP.
 
@@ -1516,7 +1628,7 @@ Enables AI coding agents (Claude Code, Cursor, etc.) to ask codegraph questions
 
 **Affected files:** `src/mcp.js`
 
-### 8.4 -- LLM-Narrated Graph Queries
+### 9.4 -- LLM-Narrated Graph Queries
 
 Graph traversal + LLM narration for questions that require both structural data and natural-language explanation. Each query walks the graph first, then sends the structural result to the LLM for narration.
 
@@ -1531,7 +1643,7 @@ Pre-computed `flow_narratives` table caches results for key entry points at buil
 
 **Depends on:** 7.4 (`side_effects` metadata), 7.1 (descriptions for narration context)
 
-### 8.5 -- Onboarding & Navigation Tools
+### 9.5 -- Onboarding & Navigation Tools
 
 Help new contributors and AI agents orient in an unfamiliar codebase.
 
@@ -1542,13 +1654,14 @@ Help new contributors and AI agents orient in an unfamiliar codebase.
 
 **Depends on:** 7.5 (module summaries for context), 8.1 (query engine)
 
+
 ---
 
-## Phase 9 -- Expanded Language Support
+## Phase 10 -- Expanded Language Support
 
 **Goal:** Go from 11 -> 19 supported languages.
 
-### 9.1 -- Batch 1: High Demand
+### 10.1 -- Batch 1: High Demand
 
 | Language | Extensions | Grammar | Effort |
 |----------|-----------|---------|--------|
@@ -1557,7 +1670,7 @@ Help new contributors and AI agents orient in an unfamiliar codebase.
 | Kotlin | `.kt`, `.kts` | `tree-sitter-kotlin` | Low |
 | Swift | `.swift` | `tree-sitter-swift` | Medium |
 
-### 9.2 -- Batch 2: Growing Ecosystems
+### 10.2 -- Batch 2: Growing Ecosystems
 
 | Language | Extensions | Grammar | Effort |
 |----------|-----------|---------|--------|
@@ -1566,7 +1679,7 @@ Help new contributors and AI agents orient in an unfamiliar codebase.
 | Lua | `.lua` | `tree-sitter-lua` | Low |
 | Zig | `.zig` | `tree-sitter-zig` | Low |
 
-### 9.3 -- Parser Abstraction Layer
+### 10.3 -- Parser Abstraction Layer
 
 Extract shared patterns from existing extractors into reusable helpers.
 
@@ -1580,15 +1693,16 @@ Extract shared patterns from existing extractors into reusable helpers.
 
 **New file:** `src/parser-utils.js`
 
+
 ---
 
-## Phase 10 -- GitHub Integration & CI
+## Phase 11 -- GitHub Integration & CI
 
 **Goal:** Bring codegraph's analysis into pull request workflows.
 
 > **Note:** Phase 2.5 delivered `codegraph check` (CI validation predicates with exit code 0/1), which provides the foundation for GitHub Action integration. The boundary violation, blast radius, and cycle detection predicates are already available.
 
-### 10.1 -- Reusable GitHub Action
+### 11.1 -- Reusable GitHub Action
 
 A reusable GitHub Action that runs on PRs:
 
@@ -1611,7 +1725,7 @@ A reusable GitHub Action that runs on PRs:
 
 **New file:** `.github/actions/codegraph-ci/action.yml`
 
-### 10.2 -- PR Review Integration
+### 11.2 -- PR Review Integration
 
 ```bash
 codegraph review --pr <number>
@@ -1634,7 +1748,7 @@ Requires `gh` CLI. For each changed function:
 
 **New file:** `src/github.js`
 
-### 10.3 -- Visual Impact Graphs for PRs
+### 11.3 -- Visual Impact Graphs for PRs
 
 Extend the existing `diff-impact --format mermaid` foundation with CI automation and LLM annotations.
 
@@ -1657,13 +1771,13 @@ Extend the existing `diff-impact --format mermaid` foundation with CI automation
 
 **Depends on:** 10.1 (GitHub Action), 7.4 (`risk_score`, `side_effects`)
 
-### 10.4 -- SARIF Output
+### 11.4 -- SARIF Output
 
 Add SARIF output format for cycle detection. SARIF integrates with GitHub Code Scanning, showing issues inline in the PR.
 
 **Affected files:** `src/export.js`
 
-### 10.5 -- Auto-generated Docstrings
+### 11.5 -- Auto-generated Docstrings
 
 ```bash
 codegraph annotate
@@ -1672,13 +1786,14 @@ codegraph annotate --changed-only
 
 LLM-generated docstrings aware of callers, callees, and types. Diff-aware: only regenerate for functions whose code or dependencies changed. Stores in `docstrings` column on nodes table -- does not modify source files unless explicitly requested.
 
-**Depends on:** 7.1 (LLM provider abstraction), 7.4 (side effects context)
+**Depends on:** 8.1 (LLM provider abstraction), 7.4 (side effects context)
+
 
 ---
 
-## Phase 11 -- Interactive Visualization & Advanced Features
+## Phase 12 -- Interactive Visualization & Advanced Features
 
-### 11.1 -- Interactive Web Visualization (Partially Complete)
+### 12.1 -- Interactive Web Visualization (Partially Complete)
 
 > **Phase 2.7 progress:** `codegraph plot` (Phase 2.7.8) ships a self-contained HTML viewer with vis-network. It supports layout switching, color/size/cluster overlays, drill-down, community detection, and a detail panel. The remaining work is the server-based experience below.
 
@@ -1699,7 +1814,7 @@ Opens a local web UI at `localhost:3000` extending the static HTML viewer with:
 
 **New file:** `src/visualizer.js`
 
-### 11.2 -- Dead Code Detection
+### 12.2 -- Dead Code Detection
 
 ```bash
 codegraph dead
@@ -1712,7 +1827,7 @@ Find functions/methods/classes with zero incoming edges (never called). Filters
 
 **Affected files:** `src/queries.js`
 
-### 11.3 -- Cross-Repository Support (Monorepo)
+### 12.3 -- Cross-Repository Support (Monorepo)
 
 Support multi-package monorepos with cross-package edges.
 
@@ -1722,7 +1837,7 @@ Support multi-package monorepos with cross-package edges.
 - `codegraph build --workspace` to scan all packages
 - Impact analysis across package boundaries
 
-### 11.4 -- Agentic Search
+### 12.4 -- Agentic Search
 
 Recursive reference-following search that traces connections.
 
@@ -1744,7 +1859,7 @@ codegraph agent-search "payment processing"
 
 **New file:** `src/agentic-search.js`
 
-### 11.5 -- Refactoring Analysis
+### 12.5 -- Refactoring Analysis
 
 LLM-powered structural analysis that identifies refactoring opportunities. The graph provides the structural data; the LLM interprets it.
 
@@ -1761,7 +1876,7 @@ LLM-powered structural analysis that identifies refactoring opportunities. The g
 
 **Depends on:** 7.4 (`risk_score`, `complexity_notes`), 7.5 (module summaries)
 
-### 11.6 -- Auto-generated Docstrings
+### 12.6 -- Auto-generated Docstrings
 
 ```bash
 codegraph annotate
@@ -1770,7 +1885,7 @@ codegraph annotate --changed-only
 
 LLM-generated docstrings aware of callers, callees, and types. Diff-aware: only regenerate for functions whose code or dependencies changed. Stores in `docstrings` column on nodes table -- does not modify source files unless explicitly requested.
 
-**Depends on:** 7.1 (LLM provider abstraction), 7.4 (side effects context)
+**Depends on:** 8.1 (LLM provider abstraction), 7.4 (side effects context)
 
 > **Full spec:** See [llm-integration.md](./llm-integration.md) for detailed architecture, infrastructure tables, and prompt design for all LLM-powered features.
 
@@ -1825,3 +1940,4 @@ Technology changes to monitor that may unlock future improvements.
 Want to help? Contributions to any phase are welcome. See [CONTRIBUTING](README.md#-contributing) for setup instructions.
 
 If you're interested in working on a specific phase, open an issue to discuss the approach before starting.
+
diff --git a/generated/competitive/COMPETITIVE_ANALYSIS.md b/generated/competitive/COMPETITIVE_ANALYSIS.md
index a103df1a..5f0b8f1a 100644
--- a/generated/competitive/COMPETITIVE_ANALYSIS.md
+++ b/generated/competitive/COMPETITIVE_ANALYSIS.md
@@ -1,7 +1,7 @@
 # Competitive Analysis — Code Graph / Code Intelligence Tools
 
-**Date:** 2026-02-25
-**Scope:** 137+ code analysis tools evaluated, 82+ ranked against `@optave/codegraph`
+**Date:** 2026-03-21 (updated from 2026-02-25)
+**Scope:** 140+ code analysis tools evaluated, 85+ ranked against `@optave/codegraph`
 
 ---
 
@@ -13,53 +13,55 @@ Ranked by weighted score across 6 dimensions (each 1–5):
 
 | # | Score | Project | Stars | Lang | License | Summary |
 |---|-------|---------|-------|------|---------|---------|
-| 1 | 4.5 | [joernio/joern](https://github.com/joernio/joern) | 2,956 | Scala | Apache-2.0 | Full CPG analysis platform for vulnerability discovery, Scala query DSL, multi-language, daily releases |
-| 2 | 4.5 | [postrv/narsil-mcp](https://github.com/postrv/narsil-mcp) | 101 | Rust | Apache-2.0 | 90 MCP tools, 32 languages, taint analysis, SBOM, dead code, neural semantic search, single ~30MB binary |
-| 3 | 4.5 | [vitali87/code-graph-rag](https://github.com/vitali87/code-graph-rag) | 1,916 | Python | MIT | Graph RAG with Memgraph, multi-provider AI, code editing, semantic search, MCP |
-| 4 | 4.2 | [Fraunhofer-AISEC/cpg](https://github.com/Fraunhofer-AISEC/cpg) | 411 | Kotlin | Apache-2.0 | CPG library for 8+ languages with MCP module, Neo4j visualization, formal specs, LLVM IR support |
-| 5 | 4.2 | [seatedro/glimpse](https://github.com/seatedro/glimpse) | 349 | Rust | MIT | Clipboard-first codebase-to-LLM tool with call graphs, token counting, LSP resolution |
-| 6 | 4.0 | [SimplyLiz/CodeMCP (CKB)](https://github.com/SimplyLiz/CodeMCP) | 59 | Go | Custom | SCIP-based indexing, compound operations (83% token savings), CODEOWNERS, secret scanning |
-| 7 | 4.0 | [abhigyanpatwari/GitNexus](https://github.com/abhigyanpatwari/GitNexus) | — | TS/JS | PolyForm NC | Knowledge graph with precomputed structural intelligence, 7 MCP tools, hybrid BM25+semantic search, clustering, process tracing, KuzuDB. **Non-commercial only** |
-| **8** | **4.0** | **[@optave/codegraph](https://github.com/optave/codegraph)** | — | **JS/Rust** | **Apache-2.0** | **Sub-second incremental rebuilds, dual engine (native Rust + WASM), 11 languages, 18-tool MCP, qualified call resolution, `context`/`explain`/`where` AI-optimized commands, structure/hotspot analysis, node role classification (entry/core/utility/adapter/dead/leaf), dead code detection, zero-cost core + optional LLM enhancement** |
-| 9 | 3.9 | [harshkedia177/axon](https://github.com/harshkedia177/axon) | 421 | Python | MIT | 11-phase pipeline, KuzuDB, Leiden community detection, dead code, change coupling, 7 MCP tools |
-| 10 | 3.8 | [anrgct/autodev-codebase](https://github.com/anrgct/autodev-codebase) | 111 | TypeScript | None | 40+ languages, 7 embedding providers, Cytoscape.js visualization, LLM reranking |
+| 1 | 4.7 | [abhigyanpatwari/GitNexus](https://github.com/abhigyanpatwari/GitNexus) | 18,453 | TS/JS | PolyForm NC | Zero-server knowledge graph engine with Graph RAG Agent, CLI + MCP + Web UI, tree-sitter native + WASM, LadybugDB (custom graph DB), multi-editor support (Claude Code hooks, Cursor, Codex, Windsurf, OpenCode), auto-generated AGENTS.md/CLAUDE.md. **Non-commercial license. Viral growth (18k stars in ~8 months)** |
+| 2 | 4.5 | [joernio/joern](https://github.com/joernio/joern) | 3,021 | Scala | Apache-2.0 | Full CPG analysis platform for vulnerability discovery, Scala query DSL, multi-language, daily releases (v4.0.508), 75 contributors |
+| 3 | 4.5 | [postrv/narsil-mcp](https://github.com/postrv/narsil-mcp) | 129 | Rust | Apache-2.0 | 90 MCP tools, 32 languages, taint analysis, SBOM, dead code, neural semantic search, single ~30MB binary, SPA web frontend (v1.6.1) |
+| 4 | 4.5 | [vitali87/code-graph-rag](https://github.com/vitali87/code-graph-rag) | 2,168 | Python | MIT | Graph RAG with Memgraph, multi-provider AI, code editing, semantic search, MCP server (added 2026) |
+| **5** | **4.5** | **[@optave/codegraph](https://github.com/optave/codegraph)** | **32** | **JS/Rust** | **Apache-2.0** | **Sub-second incremental rebuilds (3-tier change detection), dual engine (native Rust + WASM), 11 languages, 32-tool MCP, 41 CLI commands, qualified call resolution with receiver type tracking, `context`/`audit`/`where` AI-optimized commands, dataflow + CFG + stored AST across all languages, sequence diagrams, structure/hotspot analysis, node role classification, dead code/export detection, architecture boundary enforcement, unified graph model with qualified names/scope/visibility, zero-cost core + optional LLM enhancement** |
+| 6 | 4.3 | [DeusData/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) | 793 | C | MIT | Single static C binary, 64 languages (tree-sitter), 14 MCP tools, Cypher-like query language, persistent SQLite knowledge graph, 10-agent auto-installer, 3D graph visualization, HTTP route analysis. **25 days old — fastest-growing new entrant** |
+| 7 | 4.2 | [Fraunhofer-AISEC/cpg](https://github.com/Fraunhofer-AISEC/cpg) | 424 | Kotlin | Apache-2.0 | CPG library for 8+ languages with MCP module, Neo4j visualization, formal specs, LLVM IR support |
+| 8 | 4.0 | [SimplyLiz/CodeMCP (CKB)](https://github.com/SimplyLiz/CodeMCP) | 77 | Go | Custom | SCIP-based indexing, compound operations (83% token savings), CODEOWNERS, secret scanning, impact analysis, architecture mapping (v8.1.0) |
+| 9 | 4.0 | [harshkedia177/axon](https://github.com/harshkedia177/axon) | 577 | Python | MIT | 11-phase pipeline, KuzuDB, Leiden community detection, dead code, change coupling, MCP + CLI, hit v1.0 milestone |
+| 10 | 3.8 | [seatedro/glimpse](https://github.com/seatedro/glimpse) | 349 | Rust | MIT | Clipboard-first codebase-to-LLM tool with call graphs, token counting, LSP resolution. **Stagnant since Jan 2026** |
 | 11 | 3.8 | [ShiftLeftSecurity/codepropertygraph](https://github.com/ShiftLeftSecurity/codepropertygraph) | 564 | Scala | Apache-2.0 | CPG specification + Tinkergraph library, Scala query DSL, protobuf serialization (Joern foundation) |
 | 12 | 3.8 | [Jakedismo/codegraph-rust](https://github.com/Jakedismo/codegraph-rust) | 142 | Rust | None | 100% Rust GraphRAG, SurrealDB, LSP-powered dataflow analysis, architecture boundary enforcement |
 | 13 | 3.7 | [Anandb71/arbor](https://github.com/Anandb71/arbor) | 85 | Rust | MIT | Native GUI, confidence scoring, architectural role classification, fuzzy search, MCP |
 | 14 | 3.7 | [JudiniLabs/mcp-code-graph](https://github.com/JudiniLabs/mcp-code-graph) | 380 | JavaScript | MIT | Cloud-hosted MCP server by CodeGPT, semantic search, dependency links (requires account) |
-| 15 | 3.7 | [entrepeneur4lyf/code-graph-mcp](https://github.com/entrepeneur4lyf/code-graph-mcp) | 80 | Python | MIT | ast-grep for 25+ languages, complexity metrics, code smells, circular dependency detection |
-| 16 | 3.7 | [cs-au-dk/jelly](https://github.com/cs-au-dk/jelly) | 417 | TypeScript | BSD-3 | Academic-grade JS/TS points-to analysis, call graphs, vulnerability exposure, 5 published papers |
-| 17 | 3.5 | [er77/code-graph-rag-mcp](https://github.com/er77/code-graph-rag-mcp) | 89 | TypeScript | MIT | 26 MCP methods, 11 languages, tree-sitter, semantic search, hotspot analysis, clone detection |
-| 18 | 3.5 | [MikeRecognex/mcp-codebase-index](https://github.com/MikeRecognex/mcp-codebase-index) | 25 | Python | AGPL-3.0 | 18 MCP tools, zero runtime deps, auto-incremental reindexing via git diff |
-| 19 | 3.5 | [nahisaho/CodeGraphMCPServer](https://github.com/nahisaho/CodeGraphMCPServer) | 7 | Python | MIT | GraphRAG with Louvain community detection, 16 languages, 14 MCP tools, 334 tests |
-| 20 | 3.5 | [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph) | 165 | TypeScript | MIT | tree-sitter + SQLite + MCP, Claude Code token reduction benchmarks, npx installer |
+| 15 | 3.7 | [entrepeneur4lyf/code-graph-mcp](https://github.com/entrepeneur4lyf/code-graph-mcp) | 83 | Python | MIT | ast-grep for 25+ languages, complexity metrics, code smells, circular dependency detection. **Stagnant since Jul 2025** |
+| 16 | 3.7 | [cs-au-dk/jelly](https://github.com/cs-au-dk/jelly) | 423 | TypeScript | BSD-3 | Academic-grade JS/TS points-to analysis, call graphs, vulnerability exposure, 5 published papers |
+| 17 | 3.6 | [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph) | 308 | TypeScript | MIT | tree-sitter + SQLite + MCP, Claude Code token reduction benchmarks, npx installer. **Nearly doubled since Feb — naming competitor** |
+| 18 | 3.5 | [er77/code-graph-rag-mcp](https://github.com/er77/code-graph-rag-mcp) | 89 | TypeScript | MIT | 26 MCP methods, 11 languages, tree-sitter, semantic search, hotspot analysis, clone detection |
+| 19 | 3.5 | [MikeRecognex/mcp-codebase-index](https://github.com/MikeRecognex/mcp-codebase-index) | 25 | Python | AGPL-3.0 | 18 MCP tools, zero runtime deps, auto-incremental reindexing via git diff |
+| 20 | 3.5 | [nahisaho/CodeGraphMCPServer](https://github.com/nahisaho/CodeGraphMCPServer) | 7 | Python | MIT | GraphRAG with Louvain community detection, 16 languages, 14 MCP tools, 334 tests |
 | 21 | 3.5 | [dundalek/stratify](https://github.com/dundalek/stratify) | 102 | Clojure | MIT | Multi-backend extraction (LSP/SCIP/Joern), 10 languages, DGML/CodeCharta output, architecture linting |
 | 22 | 3.5 | [kraklabs/cie](https://github.com/kraklabs/cie) | 9 | Go | AGPL-3.0 | Code Intelligence Engine: 20+ MCP tools, tree-sitter, semantic search (Ollama), Homebrew, single Go binary |
-| 23 | 3.4 | [Durafen/Claude-code-memory](https://github.com/Durafen/Claude-code-memory) | 72 | Python | None | Memory Guard quality gate, persistent codebase memory, Voyage AI + Qdrant |
-| 24 | 3.3 | [NeuralRays/codexray](https://github.com/NeuralRays/codexray) | 2 | TypeScript | MIT | 16 MCP tools, TF-IDF semantic search (~50MB), dead code, complexity, path finding |
-| 25 | 3.3 | [DucPhamNgoc08/CodeVisualizer](https://github.com/DucPhamNgoc08/CodeVisualizer) | 475 | TypeScript | MIT | VS Code extension, tree-sitter WASM, flowcharts + dependency graphs, 5 AI providers, 9 themes |
-| 26 | 3.3 | [helabenkhalfallah/code-health-meter](https://github.com/helabenkhalfallah/code-health-meter) | 34 | JavaScript | MIT | Formal health metrics (MI, CC, Louvain modularity), published in ACM TOSEM 2025 |
-| 27 | 3.3 | [JohT/code-graph-analysis-pipeline](https://github.com/JohT/code-graph-analysis-pipeline) | 27 | Cypher | GPL-3.0 | 200+ CSV reports, ML anomaly detection, Leiden/HashGNN, jQAssistant + Neo4j for Java |
-| 28 | 3.3 | [Lekssays/codebadger](https://github.com/Lekssays/codebadger) | 43 | Python | GPL-3.0 | Containerized MCP server using Joern CPG, 12+ languages |
-| 29 | 3.2 | [al1-nasir/codegraph-cli](https://github.com/al1-nasir/codegraph-cli) | 11 | Python | MIT | CrewAI multi-agent system, 6 LLM providers, browser explorer, DOCX export |
-| 30 | 3.1 | [anasdayeh/claude-context-local](https://github.com/anasdayeh/claude-context-local) | 0 | Python | None | 100% local, Merkle DAG incremental indexing, sharded FAISS, hybrid BM25+vector, GPU accel |
-| 31 | 3.0 | [Vasu014/loregrep](https://github.com/Vasu014/loregrep) | 12 | Rust | Apache-2.0 | In-memory index library, Rust + Python bindings, AI-tool-ready schemas |
-| 32 | 3.0 | [xnuinside/codegraph](https://github.com/xnuinside/codegraph) | 438 | Python | MIT | Python-only interactive HTML dependency diagrams with zoom/pan/search |
-| 33 | 3.0 | [Adrninistrator/java-all-call-graph](https://github.com/Adrninistrator/java-all-call-graph) | 551 | Java | Apache-2.0 | Complete Java bytecode call graphs, Spring/MyBatis-aware, SQL-queryable DB |
-| 34 | 3.0 | [Technologicat/pyan](https://github.com/Technologicat/pyan) | 395 | Python | GPL-2.0 | Python 3 call graph generator, module import analysis, cycle detection, interactive HTML |
-| 35 | 3.0 | [GaloisInc/MATE](https://github.com/GaloisInc/MATE) | 194 | Python | BSD-3 | DARPA-funded interactive CPG-based bug hunting for C/C++ via LLVM |
-| 36 | 3.0 | [clouditor/cloud-property-graph](https://github.com/clouditor/cloud-property-graph) | 28 | Kotlin | Apache-2.0 | Connects code property graphs with cloud runtime security assessment |
+| 23 | 3.4 | [anrgct/autodev-codebase](https://github.com/anrgct/autodev-codebase) | 111 | TypeScript | None | 40+ languages, 7 embedding providers, Cytoscape.js visualization, LLM reranking. **Stagnant since Jan 2026** |
+| 24 | 3.4 | [Durafen/Claude-code-memory](https://github.com/Durafen/Claude-code-memory) | 72 | Python | None | Memory Guard quality gate, persistent codebase memory, Voyage AI + Qdrant |
+| 25 | 3.3 | [NeuralRays/codexray](https://github.com/NeuralRays/codexray) | 2 | TypeScript | MIT | 16 MCP tools, TF-IDF semantic search (~50MB), dead code, complexity, path finding |
+| 26 | 3.3 | [DucPhamNgoc08/CodeVisualizer](https://github.com/DucPhamNgoc08/CodeVisualizer) | 475 | TypeScript | MIT | VS Code extension, tree-sitter WASM, flowcharts + dependency graphs, 5 AI providers, 9 themes |
+| 27 | 3.3 | [helabenkhalfallah/code-health-meter](https://github.com/helabenkhalfallah/code-health-meter) | 34 | JavaScript | MIT | Formal health metrics (MI, CC, Louvain modularity), published in ACM TOSEM 2025 |
+| 28 | 3.3 | [JohT/code-graph-analysis-pipeline](https://github.com/JohT/code-graph-analysis-pipeline) | 27 | Cypher | GPL-3.0 | 200+ CSV reports, ML anomaly detection, Leiden/HashGNN, jQAssistant + Neo4j for Java |
+| 29 | 3.3 | [Lekssays/codebadger](https://github.com/Lekssays/codebadger) | 43 | Python | GPL-3.0 | Containerized MCP server using Joern CPG, 12+ languages |
+| 30 | 3.2 | [al1-nasir/codegraph-cli](https://github.com/al1-nasir/codegraph-cli) | 11 | Python | MIT | CrewAI multi-agent system, 6 LLM providers, browser explorer, DOCX export |
+| 31 | 3.1 | [anasdayeh/claude-context-local](https://github.com/anasdayeh/claude-context-local) | 0 | Python | None | 100% local, Merkle DAG incremental indexing, sharded FAISS, hybrid BM25+vector, GPU accel |
+| 32 | 3.0 | [Vasu014/loregrep](https://github.com/Vasu014/loregrep) | 12 | Rust | Apache-2.0 | In-memory index library, Rust + Python bindings, AI-tool-ready schemas |
+| 33 | 3.0 | [xnuinside/codegraph](https://github.com/xnuinside/codegraph) | 438 | Python | MIT | Python-only interactive HTML dependency diagrams with zoom/pan/search |
+| 34 | 3.0 | [Adrninistrator/java-all-call-graph](https://github.com/Adrninistrator/java-all-call-graph) | 551 | Java | Apache-2.0 | Complete Java bytecode call graphs, Spring/MyBatis-aware, SQL-queryable DB |
+| 35 | 3.0 | [Technologicat/pyan](https://github.com/Technologicat/pyan) | 395 | Python | GPL-2.0 | Python 3 call graph generator, module import analysis, cycle detection, interactive HTML |
+| 36 | 3.0 | [GaloisInc/MATE](https://github.com/GaloisInc/MATE) | 194 | Python | BSD-3 | DARPA-funded interactive CPG-based bug hunting for C/C++ via LLVM |
+| 37 | 3.0 | [clouditor/cloud-property-graph](https://github.com/clouditor/cloud-property-graph) | 28 | Kotlin | Apache-2.0 | Connects code property graphs with cloud runtime security assessment |
 
 ### Tier 2: Niche & Single-Language Tools (score 2.0–2.9)
 
 | # | Score | Project | Stars | Lang | License | Summary |
 |---|-------|---------|-------|------|---------|---------|
 | 37 | 2.9 | [rahulvgmail/CodeInteliMCP](https://github.com/rahulvgmail/CodeInteliMCP) | 8 | Python | None | DuckDB + ChromaDB (zero Docker), multi-repo, lightweight embedded DBs |
-| 38 | 2.8 | [paul-gauthier/aider](https://github.com/paul-gauthier/aider) | 41,664 | Python | Apache-2.0 | AI pair programming CLI; tree-sitter repo map with PageRank-style graph ranking for LLM context selection, 100+ languages, multi-provider LLM support, git-integrated auto-commits |
+| 38 | 2.8 | [Aider-AI/aider](https://github.com/Aider-AI/aider) | 42,198 | Python | Apache-2.0 | AI pair programming CLI; tree-sitter repo map with PageRank-style graph ranking for LLM context selection, 100+ languages, multi-provider LLM support, git-integrated auto-commits. Moved to Aider-AI org |
 | 39 | 2.8 | [scottrogowski/code2flow](https://github.com/scottrogowski/code2flow) | 4,528 | Python | MIT | Call graphs for Python/JS/Ruby/PHP via AST, DOT output, 100% test coverage |
 | 40 | 2.8 | [ysk8hori/typescript-graph](https://github.com/ysk8hori/typescript-graph) | 200 | TypeScript | None | TypeScript file-level dependency Mermaid diagrams, code metrics (MI, CC), watch mode |
 | 41 | 2.8 | [nuanced-dev/nuanced-py](https://github.com/nuanced-dev/nuanced-py) | 126 | Python | MIT | Python call graph enrichment designed for AI agent consumption |
-| 42 | 2.8 | [Bikach/codeGraph](https://github.com/Bikach/codeGraph) | 6 | TypeScript | MIT | Neo4j graph, Claude Code slash commands, Kotlin support, 40-50% cost reduction |
+| 42 | 2.8 | [sdsrss/code-graph-mcp](https://github.com/sdsrss/code-graph-mcp) | 16 | TypeScript | MIT | AST knowledge graph MCP server with tree-sitter, 10 languages. New entrant |
+| 43 | 2.8 | [Bikach/codeGraph](https://github.com/Bikach/codeGraph) | 6 | TypeScript | MIT | Neo4j graph, Claude Code slash commands, Kotlin support, 40-50% cost reduction |
 | 43 | 2.8 | [ChrisRoyse/CodeGraph](https://github.com/ChrisRoyse/CodeGraph) | 65 | TypeScript | None | Neo4j + MCP, multi-language, framework detection (React, Tailwind, Supabase) |
 | 44 | 2.8 | [Symbolk/Code2Graph](https://github.com/Symbolk/Code2Graph) | 48 | Java | None | Multilingual code → language-agnostic graph representation |
 | 45 | 2.7 | [yumeiriowl/repo-graphrag-mcp](https://github.com/yumeiriowl/repo-graphrag-mcp) | 3 | Python | MIT | LightRAG + tree-sitter, entity merge (code ↔ docs), implementation planning tool |
@@ -130,42 +132,43 @@ Ranked by weighted score across 6 dimensions (each 1–5):
 
 | # | Project | Features | Analysis Depth | Deploy Simplicity | Lang Support | Code Quality | Community |
 |---|---------|----------|---------------|-------------------|-------------|-------------|-----------|
-| 1 | joern | 5 | 5 | 3 | 4 | 5 | 5 |
-| 2 | narsil-mcp | 5 | 5 | 5 | 5 | 4 | 3 |
-| 3 | code-graph-rag | 5 | 4 | 3 | 4 | 4 | 5 |
-| 4 | cpg | 5 | 5 | 2 | 5 | 5 | 3 |
-| 5 | glimpse | 4 | 4 | 5 | 3 | 5 | 5 |
-| 6 | CKB | 5 | 5 | 4 | 3 | 4 | 3 |
-| 7 | GitNexus | 5 | 5 | 4 | 4 | 4 | 2 |
-| **8** | **codegraph (us)** | **5** | **4** | **5** | **4** | **4** | **2** |
-| 9 | axon | 5 | 5 | 4 | 2 | 4 | 2 |
-| 10 | autodev-codebase | 5 | 3 | 3 | 5 | 3 | 4 |
+| 1 | GitNexus | 5 | 5 | 4 | 4 | 4 | 5 |
+| 2 | joern | 5 | 5 | 3 | 4 | 5 | 5 |
+| 3 | narsil-mcp | 5 | 5 | 5 | 5 | 4 | 3 |
+| 4 | code-graph-rag | 5 | 4 | 3 | 4 | 4 | 5 |
+| **5** | **codegraph (us)** | **5** | **5** | **5** | **4** | **5** | **3** |
+| 6 | codebase-memory-mcp | 4 | 4 | 5 | 5 | 4 | 4 |
+| 7 | cpg | 5 | 5 | 2 | 5 | 5 | 3 |
+| 8 | CKB | 5 | 5 | 4 | 3 | 4 | 3 |
+| 9 | axon | 5 | 5 | 4 | 2 | 4 | 3 |
+| 10 | glimpse | 4 | 4 | 5 | 3 | 5 | 4 |
 | 11 | codepropertygraph | 4 | 5 | 2 | 4 | 5 | 3 |
 | 12 | codegraph-rust | 5 | 5 | 2 | 4 | 4 | 3 |
 | 13 | arbor | 4 | 4 | 5 | 4 | 5 | 3 |
 | 14 | mcp-code-graph | 4 | 3 | 4 | 4 | 3 | 4 |
 | 15 | code-graph-mcp | 4 | 4 | 4 | 5 | 3 | 2 |
 | 16 | jelly | 4 | 5 | 4 | 1 | 5 | 3 |
-| 17 | code-graph-rag-mcp | 5 | 4 | 3 | 4 | 3 | 2 |
-| 18 | mcp-codebase-index | 4 | 3 | 5 | 3 | 4 | 2 |
-| 19 | CodeGraphMCPServer | 4 | 4 | 4 | 5 | 3 | 1 |
-| 20 | colbymchenry/codegraph | 4 | 3 | 5 | 3 | 3 | 3 |
+| 17 | colbymchenry/codegraph | 4 | 3 | 5 | 3 | 3 | 4 |
+| 18 | code-graph-rag-mcp | 5 | 4 | 3 | 4 | 3 | 2 |
+| 19 | mcp-codebase-index | 4 | 3 | 5 | 3 | 4 | 2 |
+| 20 | CodeGraphMCPServer | 4 | 4 | 4 | 5 | 3 | 1 |
 | 21 | stratify | 4 | 4 | 2 | 5 | 4 | 2 |
 | 22 | cie | 5 | 4 | 4 | 3 | 4 | 1 |
-| 23 | Claude-code-memory | 4 | 3 | 3 | 3 | 4 | 3 |
-| 24 | codexray | 5 | 4 | 4 | 4 | 3 | 1 |
-| 25 | CodeVisualizer | 4 | 3 | 5 | 3 | 3 | 2 |
-| 26 | code-health-meter | 3 | 5 | 5 | 1 | 4 | 2 |
-| 27 | code-graph-analysis-pipeline | 5 | 5 | 1 | 2 | 5 | 2 |
-| 28 | codebadger | 4 | 4 | 3 | 5 | 3 | 1 |
-| 29 | codegraph-cli | 5 | 3 | 3 | 2 | 3 | 2 |
-| 30 | claude-context-local | 4 | 3 | 3 | 4 | 4 | 1 |
-| 31 | loregrep | 3 | 3 | 4 | 3 | 5 | 2 |
-| 32 | xnuinside/codegraph | 3 | 2 | 5 | 1 | 3 | 4 |
-| 33 | java-all-call-graph | 4 | 4 | 3 | 1 | 3 | 3 |
-| 34 | pyan | 3 | 3 | 5 | 1 | 4 | 2 |
-| 35 | MATE | 3 | 5 | 1 | 1 | 3 | 2 |
-| 36 | cloud-property-graph | 4 | 4 | 2 | 2 | 4 | 2 |
+| 23 | autodev-codebase | 5 | 3 | 3 | 5 | 3 | 3 |
+| 24 | Claude-code-memory | 4 | 3 | 3 | 3 | 4 | 3 |
+| 25 | codexray | 5 | 4 | 4 | 4 | 3 | 1 |
+| 26 | CodeVisualizer | 4 | 3 | 5 | 3 | 3 | 2 |
+| 27 | code-health-meter | 3 | 5 | 5 | 1 | 4 | 2 |
+| 28 | code-graph-analysis-pipeline | 5 | 5 | 1 | 2 | 5 | 2 |
+| 29 | codebadger | 4 | 4 | 3 | 5 | 3 | 1 |
+| 30 | codegraph-cli | 5 | 3 | 3 | 2 | 3 | 2 |
+| 31 | claude-context-local | 4 | 3 | 3 | 4 | 4 | 1 |
+| 32 | loregrep | 3 | 3 | 4 | 3 | 5 | 2 |
+| 33 | xnuinside/codegraph | 3 | 2 | 5 | 1 | 3 | 4 |
+| 34 | java-all-call-graph | 4 | 4 | 3 | 1 | 3 | 3 |
+| 35 | pyan | 3 | 3 | 5 | 1 | 4 | 2 |
+| 36 | MATE | 3 | 5 | 1 | 1 | 3 | 2 |
+| 37 | cloud-property-graph | 4 | 4 | 2 | 2 | 4 | 2 |
 
 **Scoring criteria:**
 - **Features** (1-5): breadth of tools, MCP integration, search, visualization, export
@@ -181,13 +184,13 @@ Ranked by weighted score across 6 dimensions (each 1–5):
 
 | Strength | Details |
 |----------|---------|
-| **Always-fresh graph (incremental rebuilds)** | Three-tier change detection (journal → mtime+size → hash) means only changed files are re-parsed. Change 1 file in a 3,000-file project → rebuild in under a second. No other tool in this space offers this. Competitors re-index everything from scratch — making them unusable in commit hooks, watch mode, or agent-driven loops |
+| **Always-fresh graph (incremental rebuilds)** | Three-tier change detection (journal → mtime+size → hash) means only changed files are re-parsed. Change 1 file in a 3,000-file project → rebuild in under a second. No other tool in this space offers true incremental rebuilds. Competitors re-index everything from scratch — making them unusable in commit hooks, watch mode, or agent-driven loops. Native Rust engine achieves ~4-6 ms/file on cold builds |
 | **Qualified call resolution** | Import-aware resolution distinguishes method calls (`obj.method()`) from standalone function calls, filters 28+ built-in receivers (`console`, `Math`, `JSON`, `Array`, `Promise`, etc.), deduplicates edges, and respects import scope. A call to `foo()` only resolves to functions actually imported or in-scope — eliminating the false positives that plague tree-sitter-based tools. Confidence scoring (1.0 → 0.5) on every edge lets agents trust the graph |
 | **AI-optimized compound commands** | `context` returns source + deps + callers + signature + related tests for a function in one call. `explain` gives structural summaries of files (public API, internals, data flow) or functions without reading the source. These save AI agents 50-80% of the token budget they'd otherwise spend navigating code. No competitor offers purpose-built compound context commands |
 | **Zero-cost core, LLM-enhanced when you choose** | The full graph pipeline (parse, resolve, query, impact analysis) runs with no API keys, no cloud, no cost. LLM features (richer embeddings, semantic search) are an optional layer on top — using whichever provider the user already works with. Competitors either require cloud APIs for core features (code-graph-rag, autodev-codebase, mcp-code-graph) or offer no AI enhancement at all (CKB, axon). Nobody else offers both modes in one tool |
 | **Data goes only where you send it** | Your code reaches exactly one place: the AI agent you already chose (via MCP). No additional third-party services, no surprise cloud calls. Competitors like code-graph-rag, autodev-codebase, mcp-code-graph, and Claude-code-memory send your code to additional AI providers beyond the agent you're using |
-| **Dual engine architecture** | Only project with native Rust (napi-rs) + automatic WASM fallback. Others are pure Rust (narsil-mcp, codegraph-rust) OR pure JS/Python — never both |
-| **Standalone CLI + MCP** | Full CLI experience (`context`, `explain`, `where`, `fn`, `diff-impact`, `map`, `deps`, `search`, `structure`, `hotspots`, `roles`) alongside 18-tool MCP server. Many competitors are MCP-only (narsil-mcp, code-graph-mcp, CodeGraphMCPServer) with no standalone query interface |
+| **Dual engine architecture** | Only project with native Rust (napi-rs) + automatic WASM fallback. Others are pure Rust (narsil-mcp, codegraph-rust, codebase-memory-mcp) OR pure JS/Python — never both |
+| **Standalone CLI + MCP** | Full 41-command CLI experience (`context`, `audit`, `where`, `fn-impact`, `diff-impact`, `map`, `deps`, `search`, `structure`, `sequence`, `roles`, `dataflow`, `cfg`, `ast`) alongside 32-tool MCP server. Many competitors are MCP-only (narsil-mcp, codebase-memory-mcp, code-graph-mcp, CodeGraphMCPServer) with no standalone query interface |
 | **Single-repo MCP isolation** | Security-conscious default: tools have no `repo` property unless `--multi-repo` is explicitly enabled. Most competitors default to exposing everything |
 | **Zero-dependency deployment** | `npm install` and done. No Docker, no external databases, no Python, no SCIP toolchains, no JVM. Published platform-specific binaries (`@optave/codegraph-{platform}-{arch}`) resolve automatically. Joern requires JDK 21, cpg requires Gradle + language-specific deps, codegraph-rust requires SurrealDB + LSP servers |
 | **Structure & quality analysis** | `structure` shows directory cohesion scores, `hotspots` finds files with extreme fan-in/fan-out/density, `stats` includes a graph quality score (0-100) with false-positive warnings. These give agents architectural awareness without requiring external tools |
@@ -198,59 +201,73 @@ Ranked by weighted score across 6 dimensions (each 1–5):
 
 ## Where Codegraph Loses
 
-### vs joern (#1, 2,956 stars)
-- **Full Code Property Graph**: AST + CFG + PDG combined for deep vulnerability analysis; our tree-sitter extraction captures structure but not control/data flow
-- **Scala query DSL**: purpose-built query language for arbitrary graph traversals vs our fixed SQL queries
+### vs GitNexus (#1, 18,453 stars)
+- **Viral growth**: 18,453 stars in ~8 months — orders of magnitude more traction. Discord community, TrendShift badge, npm package (`gitnexus`)
+- **Multi-editor integration**: Auto-configures Claude Code (with hooks), Cursor, Codex, Windsurf, OpenCode via `gitnexus setup`. We only support Claude Code MCP config
+- **Auto-generated context files**: Creates AGENTS.md/CLAUDE.md from the knowledge graph — agents get codebase context automatically
+- **Web UI + CLI + MCP**: Three access modes including a hosted web explorer at gitnexus.vercel.app. We have CLI + MCP + interactive HTML viewer but no hosted web UI
+- **Bridge mode**: `gitnexus serve` connects CLI-indexed repos to the web UI — seamless local-to-browser workflow
+- **Where we win**: Non-commercial license (PolyForm NC) blocks enterprise adoption. No incremental rebuilds (full re-index). LadybugDB is custom/unproven vs our SQLite. We have deeper analysis (complexity, dataflow, CFG, architecture boundaries, manifesto rules, CI gates) and confidence-scored edges. Their graph is broader but shallower
+
+### vs joern (#2, 3,021 stars)
+- **Full Code Property Graph**: AST + CFG + PDG combined for deep vulnerability analysis; our tree-sitter extraction captures structure but not interprocedural control/data flow
+- **Scala query DSL**: purpose-built query language for arbitrary graph traversals vs our fixed CLI commands
 - **Binary analysis**: Ghidra frontend can analyze compiled binaries — we're source-only
-- **Enterprise backing**: ShiftLeft/Fraunhofer support, daily automated releases, Discord community, professional documentation at joern.io
-- **Community**: 2,956 stars, 389 forks — massive traction
+- **Enterprise backing**: ShiftLeft/Fraunhofer support, daily automated releases (v4.0.508), 75 contributors, professional documentation at joern.io
+- **Community**: 3,021 stars, 400 forks — massive traction. 4 community MCP wrappers now available
 
-### vs narsil-mcp (#2, 101 stars)
-- **Feature breadth**: 90 MCP tools vs our 17; covers taint analysis, SBOM, license compliance, control flow graphs, data flow analysis
+### vs narsil-mcp (#3, 129 stars)
+- **Feature breadth**: 90 MCP tools vs our 32; covers taint analysis, SBOM, license compliance, control flow graphs, data flow analysis
 - **Language count**: 32 languages (including Verilog, Fortran, PowerShell, Nix) vs our 11
-- **Security analysis**: vulnerability scanning with OWASP/CWE coverage — we have no security features
-- **Dead code detection**: built-in — *(Gap closed: our `roles --role dead` now surfaces unreferenced non-exported symbols)*
+- **Security analysis**: vulnerability scanning with OWASP/CWE coverage, 147+ rules (added 36 Rust/Elixir rules in v1.6.0) — we have no security features
+- **SPA web frontend**: Full web UI with file tree sidebar, syntax-highlighted code viewer, dashboard, per-repo overview, CFG visualization (added v1.6.0)
 - **Single-binary deployment**: ~30MB Rust binary via brew/scoop/cargo/npm — as easy as ours
+- **Note**: No activity since Feb 25 (24+ day gap) — development may have paused
 
-### vs code-graph-rag (#3, 1,916 stars)
-- **Graph query expressiveness**: Memgraph + Cypher enables arbitrary graph traversals; our SQL queries are more rigid
+### vs code-graph-rag (#4, 2,168 stars)
+- **Graph query expressiveness**: Memgraph + Cypher enables arbitrary graph traversals; our CLI commands are more rigid
 - **AI-powered code editing**: they can surgically edit functions via AST targeting with visual diffs
 - **Provider flexibility**: they support Gemini/OpenAI/Claude/Ollama and can mix providers per task
-- **Community**: 1,916 stars — orders of magnitude more traction
-
-### vs cpg (#4, 411 stars)
+- **MCP server**: now added MCP support, expanding from pure RAG into the AI agent ecosystem
+- **Community**: 2,168 stars — significant traction
+
+### vs codebase-memory-mcp (#6, 793 stars — NEW)
+- **Explosive growth**: 793 stars in 25 days — fastest-growing new entrant in the space. Single-developer C project
+- **Zero-dependency binary**: Single static C binary (~30MB), no Node.js/JVM/runtime. Auto-installer configures 10 different AI agents in one command
+- **64 languages**: 3x our language coverage via vendored tree-sitter grammars compiled into the binary
+- **Cypher-like query language**: Hand-built Cypher subset in C for arbitrary graph traversals — we have no query DSL
+- **HTTP route analysis**: First-class Route nodes and cross-service HTTP call linking with confidence scoring — unique capability
+- **3D graph visualization**: Built-in web-based 3D graph viewer
+- **Where we win**: MCP-only (no standalone CLI), no semantic search/embeddings, no complexity metrics, no cycle detection, no export formats (DOT/Mermaid/GraphML), no architecture boundaries, no CI gates, no programmatic API, limited Cypher subset (no WITH/COLLECT/OPTIONAL MATCH). Very immature (v0.5.x, 25 days old, solo developer). Our analysis depth is significantly greater
+
+### vs cpg (#7, 424 stars)
 - **Formal CPG specification**: academic-grade graph representation (AST + CFG + PDG + DFG) with published specs
 - **MCP module**: built-in MCP support now, matching our integration
 - **LLVM IR support**: extends language coverage to any LLVM-compiled language (Rust, Swift, etc.)
 - **Type inference**: can analyze incomplete/partial code — our tree-sitter requires syntactically valid input
 
-### vs glimpse (#5, 349 stars)
+### vs glimpse (#10, 349 stars — stagnant)
 - **LLM workflow optimization**: clipboard-first output + token counting + XML output mode — purpose-built for "code → LLM context"
 - **LSP-based call resolution**: compiler-grade accuracy vs our tree-sitter heuristic approach
 - **Web content processing**: can fetch URLs and convert HTML to markdown for context
 
-### vs CKB (#6, 59 stars)
+### vs CKB (#8, 77 stars)
 - **Indexing accuracy**: SCIP provides compiler-grade cross-file references (type-aware), fundamentally more accurate than tree-sitter for supported languages
-- **Compound operations**: `explore`/`understand`/`prepareChange` batch multiple queries into one call — 83% token reduction. *(Gap narrowed: our `context` and `explain` commands now serve the same purpose, returning full function context or file summaries in one call)*
-- **CODEOWNERS + secret scanning**: enterprise features we lack entirely
-
-### vs GitNexus (#7)
-- **Precomputed structural intelligence**: 6-phase pipeline (structure, parsing, resolution, clustering, processes, search) precomputes everything at index time — queries return complete context in a single call. Our queries traverse the graph at query time
-- **Clustering and process tracing**: Leiden-style community detection groups related symbols into functional clusters; execution flow tracing from entry points. We have neither
-- **Hybrid search**: BM25 + semantic + RRF with process-grouped results — our semantic search lacks the BM25/process grouping layer
-- **Multi-file coordinated rename**: validated against graph structure and text — we have no refactoring tools
-- **Auto-generated context files**: LLM-powered wiki and AGENTS.md/CLAUDE.md generation from the knowledge graph
-- **Tradeoff**: Full pipeline re-run on changes (no incremental builds), KuzuDB graph DB (heavier than SQLite), browser mode limited to ~5,000 files
-
-### vs axon (#9, 29 stars)
-- **Analysis depth**: their 11-phase pipeline includes community detection (Leiden), execution flow tracing, git change coupling, dead code detection — *(Gap narrowed: we now have dead code detection via node role classification)*
-- **Graph database**: KuzuDB with native Cypher is more expressive for complex graph queries than our SQLite
-- **Branch structural diff**: compares code structure between branches using git worktrees
+- **Compound operations**: `explore`/`understand`/`prepareChange` batch multiple queries into one call — 83% token reduction. *(Gap closed: our `context`, `audit`, and `batch` commands now serve the same purpose)*
+- **Now claims impact analysis and architecture mapping**: Feature convergence with v8.1.0 — they're moving into our territory
+- **Secret scanning**: enterprise feature we lack
+
+### vs axon (#9, 577 stars)
+- **Hit v1.0 milestone**: Now a stable release with tree-sitter + KuzuDB + CLI + MCP. Growing fast (+156 stars since Feb)
+- **Leiden community detection**: More sophisticated clustering than our Louvain
+- **KuzuDB with native Cypher**: More expressive for complex graph queries than our SQLite
+- **Git change coupling**: Co-change analysis — *(Gap closed: we now have `co-change` command)*
+- **Branch structural diff**: *(Gap closed: we now have `branch-compare`)*
 
 ### vs codegraph-rust (#12, 142 stars)
 - **LSP-powered analysis**: compiler-grade cross-file references via rust-analyzer, pyright, gopls vs our tree-sitter heuristics
-- **Dataflow edges**: defines/uses/flows_to/returns/mutates relationships we don't capture
-- **Architecture boundary enforcement**: configurable rules for detecting violations — we have no architectural awareness
+- **Dataflow edges**: defines/uses/flows_to/returns/mutates relationships — *(Gap closed: we now have `flows_to`/`returns`/`mutates` across all 11 languages)*
+- **Architecture boundary enforcement**: *(Gap closed: we now have `boundaries` command with onion/hexagonal/layered/clean presets)*
 - **Tiered indexing**: fast/balanced/full modes for different use cases — we have one mode
 
 ### vs jelly (#16, 417 stars)
@@ -258,19 +275,19 @@ Ranked by weighted score across 6 dimensions (each 1–5):
 - **Academic rigor**: 5 published papers backing the methodology (Aarhus University)
 - **Vulnerability exposure analysis**: library usage pattern matching specific to the JS/TS ecosystem
 
-### vs aider (#38, 41,664 stars)
+### vs aider (#38, 42,198 stars — now Aider-AI/aider)
 - **Different product category**: Aider is an AI pair programming CLI, not a code graph tool — but its tree-sitter repo map with PageRank-style graph ranking is a lightweight alternative to our full graph for LLM context selection
-- **Massive community**: 41,664 stars, 3,984 forks — orders of magnitude more traction than any tool in this space. Aider *is* the category leader for AI-assisted coding in the terminal
+- **Massive community**: 42,198 stars, 4,054 forks — orders of magnitude more traction than any tool in this space. Aider *is* the category leader for AI-assisted coding in the terminal. Moved to Aider-AI org
 - **100+ languages**: tree-sitter parsing covers far more languages than our 11, though only for identifier extraction (not full symbol/call resolution)
 - **Multi-provider LLM**: works with Claude, GPT-4, Gemini, DeepSeek, Ollama, and virtually any LLM out of the box
 - **Built-in code editing**: Aider's core loop is "understand code → edit code → commit." We provide the understanding layer but don't edit
 - **Where we win**: Aider's repo map is shallow — file-level dependency graph with identifier ranking, no function-level call resolution, no impact analysis, no dead code detection, no complexity metrics, no MCP server, no standalone queryable graph. It answers "what's relevant?" but not "what breaks if I change this?" Our graph is deeper and persistent; Aider rebuilds its map per-request
 
-### vs colbymchenry/codegraph (#20, 165 stars)
-- **No role classification**: they lack node role classification or dead code detection — we now have both
-- **Naming competitor**: same name, same tech stack (tree-sitter + SQLite + MCP + Node.js) — marketplace confusion risk
-- **Published benchmarks**: 67% fewer tool calls and measurable Claude Code token reduction — compelling marketing angle we lack. *(Gap narrowed: our `context` and `explain` compound commands now provide similar token savings by batching multiple queries into one call)*
+### vs colbymchenry/codegraph (#17, 308 stars — nearly doubled)
+- **Fastest-growing naming competitor**: 165 → 308 stars since Feb. Same name, same tech stack (tree-sitter + SQLite + MCP + Node.js) — marketplace confusion is increasing
+- **Published benchmarks**: 67% fewer tool calls and measurable Claude Code token reduction — compelling marketing. *(Gap closed: our `context`, `audit`, and `batch` compound commands provide equivalent or better token savings)*
 - **One-liner setup**: `npx @colbymchenry/codegraph` with interactive installer auto-configures Claude Code
+- **Where we win**: We have 41 CLI commands vs their MCP-only approach, confidence-scored edges, dataflow/CFG/AST analysis, complexity metrics, architecture boundaries, cycle detection, dead code/export detection, community detection, sequence diagrams, and CI gates. Their tool is a lightweight MCP wrapper; ours is a full code intelligence platform
 
 ---
 
@@ -282,7 +299,7 @@ Ranked by weighted score across 6 dimensions (each 1–5):
 | ~~**Dead code detection**~~ | narsil-mcp, axon, codexray, CKB | ~~We have the graph — find nodes with zero incoming edges (minus entry points/exports). Agents constantly ask "is this used?"~~ | **DONE** — Delivered via node classification. `roles --role dead` lists all unreferenced, non-exported symbols |
 | ~~**Fuzzy symbol search**~~ | arbor | ~~Add Levenshtein/Jaro-Winkler to `fn` command. Currently requires exact match~~ | **DONE** — `fn` now has relevance scoring (exact > prefix > word-boundary > substring) with fan-in tiebreaker, plus `--file` and `--kind` filters |
 | ~~**Expose confidence scores**~~ | arbor | ~~Already computed internally in import resolution — just surface them~~ | **DONE** — confidence scores stored on every call edge, surfaced in `stats` graph quality score |
-| **Shortest path A→B** | codexray, arbor | BFS on existing edges table. We have `fn` for single chains but no A→B pathfinding | TODO |
+| ~~**Shortest path A→B**~~ | codexray, arbor | ~~BFS on existing edges table~~ | **DONE** — `codegraph path <from> <to>` with BFS on call graph edges |
 
 ### Tier 2: High impact, medium effort
 | Feature | Inspired by | Why | Status |
@@ -290,20 +307,20 @@ Ranked by weighted score across 6 dimensions (each 1–5):
 | **Optional LLM provider integration** | code-graph-rag, autodev-codebase | Bring-your-own provider (OpenAI, etc.) for richer embeddings and AI-powered search. Enhancement layer only — core graph never depends on it. No other tool offers both zero-cost local and LLM-enhanced modes in one package | TODO |
 | ~~**Compound MCP tools**~~ | CKB, colbymchenry/codegraph | ~~`explore`/`understand` meta-tools that batch deps + fn + map into single responses~~ | **DONE** — `context` returns source + deps + callers + signature + tests in one call; `explain` returns structural summaries of files or functions |
 | **Token counting on responses** | glimpse, arbor | tiktoken-based counts so agents know context budget consumed | TODO |
-| ~~**Node classification**~~ | arbor | ~~Auto-tag Entry Point / Core / Utility / Adapter from in-degree/out-degree patterns~~ | **DONE** — `classifyNodeRoles()` tags every symbol as `entry`/`core`/`utility`/`adapter`/`dead`/`leaf`. New `roles` CLI command, `node_roles` MCP tool (18 tools), `--role`/`--file` filters. Roles surfaced in `where`/`explain`/`context`/`stats`/`list-functions` |
+| ~~**Node classification**~~ | arbor | ~~Auto-tag Entry Point / Core / Utility / Adapter from in-degree/out-degree patterns~~ | **DONE** — `classifyNodeRoles()` tags every symbol as `entry`/`core`/`utility`/`adapter`/`dead`/`leaf`. New `roles` CLI command, `node_roles` MCP tool, `--role`/`--file` filters. Roles surfaced in `where`/`context`/`stats`/`list-functions` |
 | **TF-IDF lightweight search** | codexray | SQLite FTS5 + TF-IDF as a middle tier (~50MB) between "no search" and full transformers (~500MB) | TODO |
 | **OWASP/CWE pattern detection** | narsil-mcp, CKB | Security pattern scanning on the existing AST — hardcoded secrets, SQL injection patterns, XSS | TODO |
-| **Formal code health metrics** | code-health-meter | Cyclomatic complexity, Maintainability Index, Halstead metrics per function — we already parse the AST | TODO |
+| ~~**Formal code health metrics**~~ | code-health-meter | ~~Cyclomatic complexity, Maintainability Index, Halstead metrics per function~~ | **DONE** — `codegraph complexity` delivers cognitive, cyclomatic (CFG-derived), Halstead, MI, nesting depth per function across all 11 languages |
 
 ### Tier 3: High impact, high effort
 | Feature | Inspired by | Why | Status |
 |---------|------------|-----|--------|
-| **Interactive HTML visualization** | autodev-codebase, CodeVisualizer | `codegraph viz` → opens interactive vis.js/Cytoscape.js graph in browser | TODO |
-| **Git change coupling** | axon | Analyze git history for files that always change together — enhances `diff-impact` | TODO |
-| **Community detection** | axon, GitNexus, CodeGraphMCPServer | Leiden/Louvain algorithm to discover natural module boundaries vs actual file organization | TODO |
-| **Execution flow tracing** | axon, GitNexus, code-context-mcp | Framework-aware entry point detection + BFS flow tracing | TODO |
-| **Dataflow analysis** | codegraph-rust | Define/use chains and flows_to/returns/mutates edges — major analysis depth increase | TODO |
-| **Architecture boundary rules** | codegraph-rust, stratify | User-defined rules for allowed/forbidden dependencies between modules | TODO |
+| ~~**Interactive HTML visualization**~~ | autodev-codebase, CodeVisualizer | ~~`codegraph viz` → opens interactive graph in browser~~ | **DONE** — `codegraph plot` opens interactive vis-network HTML viewer with physics, clustering, drill-down |
+| ~~**Git change coupling**~~ | axon | ~~Analyze git history for files that always change together~~ | **DONE** — `codegraph co-change` analyzes git history for temporal file coupling |
+| ~~**Community detection**~~ | axon, GitNexus, CodeGraphMCPServer | ~~Louvain algorithm to discover natural module boundaries~~ | **DONE** — `codegraph communities` with Louvain clustering and drift analysis |
+| ~~**Execution flow tracing**~~ | axon, GitNexus, code-context-mcp | ~~Framework-aware entry point detection + BFS flow tracing~~ | **DONE** — `codegraph flow` traces from entry points (routes, commands, events) through callees to leaves |
+| ~~**Dataflow analysis**~~ | codegraph-rust | ~~Define/use chains and flows_to/returns/mutates edges~~ | **DONE** — `codegraph dataflow` with `flows_to`/`returns`/`mutates` edges across all 11 languages |
+| ~~**Architecture boundary rules**~~ | codegraph-rust, stratify | ~~User-defined rules for allowed/forbidden dependencies between modules~~ | **DONE** — `codegraph check` with configurable boundary rules and onion/hexagonal/layered/clean presets |
 
 ### Paid Solutions
 
@@ -322,7 +339,7 @@ Ranked by weighted score across 6 dimensions (each 1–5):
 | **Code Ownership** | CODEOWNERS as a first-class search dimension: `file:has.owner()`, `select:file.owners`, owner-scoped queries. Resolves CODEOWNERS entries against user profiles | `codegraph owners` with `--owner`, `--boundary` filters. Integrated into `diff-impact` (affected owners + suggested reviewers). `code_owners` MCP tool | **No gap** — feature parity. We parse CODEOWNERS, match patterns, integrate into impact analysis, and expose via CLI + MCP. They have richer owner-as-search-filter syntax; our backlog ID 79 (advanced query language) would close this |
 | **Code Insights** | Track any search query as a time-series metric on dashboards. Automatic historical backfill from git history — years of data immediately. Migration progress, tech debt trends, codebase composition over time | `codegraph stats` (point-in-time), `codegraph snapshot` (manual checkpoints) | **Yes** — we have point-in-time metrics and manual snapshots but no automated historical trend tracking. Backlog ID 77 |
 | **Batch Changes** | Declarative YAML spec → automated code changes across hundreds of repos. Creates PRs on all affected repos, tracks merge status, CI checks, review approvals. Burndown charts for migration progress | None — codegraph is read-only by design (Foundation P8: we don't edit code or make decisions) | **By design** — we're a graph query tool, not a code modification tool. This is out of scope per Foundation principles |
-| **CLI (`src`)** | Terminal search, batch change creation, SBOM generation, repo/user/team admin, code intelligence ops, CODEOWNERS management | `codegraph` CLI with 25+ commands, MCP server | **Partial** — our CLI is richer for graph queries; theirs is richer for admin/batch/SBOM operations. Different focus areas |
+| **CLI (`src`)** | Terminal search, batch change creation, SBOM generation, repo/user/team admin, code intelligence ops, CODEOWNERS management | `codegraph` CLI with 41 commands, 32-tool MCP server | **Partial** — our CLI is richer for graph queries; theirs is richer for admin/batch/SBOM operations. Different focus areas |
 
 **Where Sourcegraph wins over codegraph:**
 
@@ -345,17 +362,18 @@ Ranked by weighted score across 6 dimensions (each 1–5):
 | **Impact analysis** | `diff-impact`, `fn-impact`, `branch-compare` trace transitive blast radius through the call graph. Sourcegraph's `find-references` shows direct references but not transitive impact chains |
 | **Complexity & health metrics** | Cognitive, cyclomatic, Halstead, MI per function with CI gates. Sourcegraph has no built-in code health metrics |
 | **Community detection & drift** | Louvain clustering reveals architectural drift between directory structure and actual dependencies. Sourcegraph has no equivalent |
-| **Dataflow analysis** | `flows_to`/`returns`/`mutates` edges track how data moves through functions. Sourcegraph doesn't do dataflow analysis |
-| **Control flow graphs** | Per-function CFG with basic blocks stored in the graph. Sourcegraph doesn't build CFGs |
+| **Dataflow analysis** | `flows_to`/`returns`/`mutates` edges track how data moves through functions across all 11 languages. Sourcegraph doesn't do dataflow analysis |
+| **Control flow graphs** | Per-function CFG with basic blocks stored in the graph; cyclomatic complexity derived from CFG structure (E - N + 2). Sourcegraph doesn't build CFGs |
+| **Sequence diagrams** | `sequence <name>` generates Mermaid sequence diagrams from call graph edges. Sourcegraph has no diagram generation |
 | **Node role classification** | Every symbol auto-tagged as entry/core/utility/adapter/dead/leaf. Sourcegraph has no architectural role concept |
 | **Cost** | Completely free and open source (Apache-2.0). Sourcegraph's paid plans start at $49/user/month for enterprise features |
 | **Privacy** | Your code never leaves your machine (unless you choose to connect an LLM). Sourcegraph Cloud processes your code on their infrastructure; self-hosted requires significant ops investment |
-| **AI-optimized output** | `context`, `audit`, `triage`, `batch` commands are purpose-built for AI agent consumption with structured JSON. Sourcegraph's output is designed for human developers in a web UI |
+| **AI-optimized output** | `context`, `audit`, `triage`, `batch`, `sequence` commands are purpose-built for AI agent consumption with structured JSON. Sourcegraph's output is designed for human developers in a web UI |
 
 ### Not worth copying
 | Feature | Why skip |
 |---------|----------|
-| Memgraph/Neo4j/KuzuDB/SurrealDB | Our SQLite = zero Docker, simpler deployment. Query gap matters less than simplicity. codegraph-rust's SurrealDB requirement is its biggest weakness |
+| Memgraph/Neo4j/KuzuDB/SurrealDB/LadybugDB | Our SQLite = zero Docker, simpler deployment. Query gap matters less than simplicity. codegraph-rust's SurrealDB requirement is its biggest weakness. GitNexus's LadybugDB is custom/unproven |
 | SCIP indexing | Would require maintaining SCIP toolchains per language. Tree-sitter + native Rust is the right bet |
 | Full CPG (AST+CFG+PDG) | Joern/cpg's approach requires fundamentally different parsing — we'd be rebuilding Joern. Tree-sitter gives us AST-level graphs; adding lightweight dataflow on top is the pragmatic path |
 | Points-to analysis | Academic-grade JS analysis (jelly) — overkill for our use case and limited to JS/TS |
diff --git a/generated/competitive/joern.md b/generated/competitive/joern.md
index 403cab75..3f279de6 100644
--- a/generated/competitive/joern.md
+++ b/generated/competitive/joern.md
@@ -1,8 +1,8 @@
 # Competitive Deep-Dive: Codegraph vs Joern
 
-**Date:** 2026-03-02
-**Competitors:** `@optave/codegraph` v3.0.0 (Apache-2.0) vs `joernio/joern` v4.x (Apache-2.0)
-**Context:** Both are Apache-2.0-licensed code analysis tools with CLI interfaces. Joern is ranked #1 in our [competitive analysis](./COMPETITIVE_ANALYSIS.md) with a score of 4.5 vs codegraph's 4.0 at #8.
+**Date:** 2026-03-21
+**Competitors:** `@optave/codegraph` v3.2.0 (Apache-2.0) vs `joernio/joern` v4.x (Apache-2.0)
+**Context:** Both are Apache-2.0-licensed code analysis tools with CLI interfaces. Joern is ranked #2 in our [competitive analysis](./COMPETITIVE_ANALYSIS.md) with a score of 4.5 vs codegraph's 4.5 at #5.
 
 ---
 
@@ -14,7 +14,7 @@ Joern and codegraph solve fundamentally **different problems** using code graphs
 |-----------|-------|-----------|
 | **Primary mission** | Vulnerability discovery & security research | Always-current structural code intelligence for developers and AI agents |
 | **Target user** | Security researchers, pentesters, auditors | Developers, AI coding agents, CI pipelines |
-| **Graph model** | Code Property Graph (AST + CFG + PDG + DDG) | Structural dependency graph (symbols + call/import/dataflow/CFG edges + stored AST) |
+| **Graph model** | Code Property Graph (AST + CFG + PDG + DDG) | Structural dependency graph (symbols + call/import/dataflow/CFG edges + stored AST + qualified names/scope/visibility) |
 | **Core question answered** | "Can attacker-controlled data reach this dangerous sink?" | "What breaks if I change this function?" |
 | **Rebuild model** | Full re-import on every change (minutes) | Incremental sub-second rebuilds (milliseconds) |
 | **Runtime** | JVM (Scala) — 4-100 GB heap | Node.js — <100 MB typical |
@@ -31,11 +31,11 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 
 | # | Principle | Codegraph | Joern | Verdict |
 |---|-----------|-----------|-------|---------|
-| 1 | **The graph is always current** — rebuild on every commit/save/agent loop | File-level MD5 hashing. Change 1 file in 3,000 → <500ms rebuild. Watch mode, commit hooks, agent loops all practical | Full re-import always. Small project: 19-30s. Linux kernel: 6+ hours. No incremental mode. Unusable in tight feedback loops | **Codegraph wins decisively.** This is the single most important differentiator. Joern cannot participate in commit hooks or agent-driven loops |
+| 1 | **The graph is always current** — rebuild on every commit/save/agent loop | 3-tier change detection (journal → mtime+size → hash). Change 1 file in 3,000 → <500ms rebuild. Watch mode, commit hooks, agent loops all practical | Full re-import always. Small project: 19-30s. Linux kernel: 6+ hours. No incremental mode. Unusable in tight feedback loops | **Codegraph wins decisively.** This is the single most important differentiator. Joern cannot participate in commit hooks or agent-driven loops |
 | 2 | **Native speed, universal reach** — dual engine (Rust + WASM) | Native napi-rs with rayon parallelism + automatic WASM fallback. `npm install` on any platform | JVM/Scala. Requires JDK 19+. Pre-built binaries or Docker. No cross-platform auto-detection | **Codegraph wins.** Automatic platform detection with native performance + universal fallback vs. manual JVM setup |
 | 3 | **Confidence over noise** — scored results | 6-level import resolution with 0.0-1.0 confidence on every edge. False-positive filtering. Graph quality score | Overapproximation by default (assumes full taint propagation for unresolved methods). Requires manual semantic definitions to reduce false positives | **Codegraph wins.** Scored results by default vs. noise-by-default requiring manual tuning |
 | 4 | **Zero-cost core, LLM-enhanced when you choose** | Full pipeline local, zero API keys. Optional embeddings with user's LLM provider | Fully local, zero API keys. No LLM enhancement path | **Codegraph wins.** Both are local-first, but codegraph adds optional AI enhancement that Joern lacks entirely |
-| 5 | **Functional CLI, embeddable API** | 39 CLI commands + 30-tool MCP server + full programmatic JS API | Interactive Scala REPL + server mode + script execution. No MCP. Python client library | **Codegraph wins.** Purpose-built MCP for AI agents + embeddable npm package vs. Scala REPL that requires JVM expertise |
+| 5 | **Functional CLI, embeddable API** | 41 CLI commands + 32-tool MCP server + full programmatic JS API | Interactive Scala REPL + server mode + script execution. No MCP. Python client library | **Codegraph wins.** Purpose-built MCP for AI agents + embeddable npm package vs. Scala REPL that requires JVM expertise |
 | 6 | **One registry, one schema, no magic** | `LANGUAGE_REGISTRY` — add a language in <100 lines, 2 files | Each language has a separate frontend (Eclipse CDT, JavaParser, GraalVM, etc.) — fundamentally different parsers per language | **Codegraph wins.** Uniform tree-sitter extraction vs. heterogeneous parser zoo |
 | 7 | **Security-conscious defaults** — multi-repo opt-in | Single-repo MCP default. `apiKeyCommand` for secrets. `--multi-repo` opt-in | Server mode has no sandboxing (docs explicitly warn: "raw interpreter access"). No MCP isolation concept | **Codegraph wins.** Security-by-default vs. "trust the user" |
 | 8 | **Honest about what we're not** | Code intelligence engine. Not an app, not a coding tool, not an agent | Code analysis platform for security research. Not a CI tool, not a developer productivity tool | **Tie.** Both are honest about scope. Different scopes |
@@ -70,7 +70,7 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | **Language count** | 11 source languages | 13 source + 3 binary/bytecode/IR | **Joern** (16 vs 11) |
 | **Adding a new language** | 1 registry entry + 1 extractor (<100 lines, 2 files) | New frontend module (thousands of lines, custom parser integration) | **Codegraph** — dramatically lower barrier |
 | **Incomplete/non-compilable code** | Requires syntactically valid input (tree-sitter) | Fuzzy parsing handles partial/broken code | **Joern** — critical for security audits of partial codebases |
-| **Incremental parsing** | File-level hash tracking — only changed files re-parsed | Full re-import always | **Codegraph** — orders of magnitude faster for iterative work |
+| **Incremental parsing** | 3-tier change detection (journal → mtime+size → hash) — only changed files re-parsed | Full re-import always | **Codegraph** — orders of magnitude faster for iterative work |
 
 **Summary:** Joern covers more languages and handles edge cases (binaries, bytecode, broken code) that codegraph cannot. Codegraph is faster, simpler to extend, and has better support for modern web languages (TSX, Terraform). For codegraph's target users (developers, AI agents), codegraph's coverage is sufficient. For security researchers auditing compiled artifacts, Joern is essential.
 
@@ -81,11 +81,11 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | Feature | Codegraph | Joern | Best Approach |
 |---------|-----------|-------|---------------|
 | **Graph type** | Structural dependency graph (symbols + edges) | Code Property Graph (AST + CFG + PDG merged) | **Joern** for depth; **Codegraph** for speed |
-| **Node types** | 13 kinds: `function`, `method`, `class`, `interface`, `type`, `struct`, `enum`, `trait`, `record`, `module`, `parameter`, `property`, `constant` | 45+ node types across 18 layers (METHOD, CALL, IDENTIFIER, LITERAL, CONTROL_STRUCTURE, BLOCK, LOCAL, etc.) | **Joern** — still more granular, but gap narrowed from 4x to ~3x |
-| **Edge types** | `calls`, `imports`, `contains`, `parameter_of`, `receiver`, `flows_to`, `returns`, `mutates` (with confidence scores on call/import edges) | 20+ types: AST, CFG, CDG, REACHING_DEF, CALL, ARGUMENT, RECEIVER, CONTAINS, EVAL_TYPE, REF, BINDS, DOMINATE, POST_DOMINATE, etc. | **Joern** — still more edge types, but codegraph now covers structural containment, dataflow, and receiver relationships |
+| **Node types** | 13 kinds: `function`, `method`, `class`, `interface`, `type`, `struct`, `enum`, `trait`, `record`, `module`, `parameter`, `property`, `constant` + `qualified_name`, `scope`, `visibility` metadata columns | 45+ node types across 18 layers (METHOD, CALL, IDENTIFIER, LITERAL, CONTROL_STRUCTURE, BLOCK, LOCAL, etc.) | **Joern** — still more granular, but gap narrowed from 4x to ~3x |
+| **Edge types** | 10 structural: `calls`, `imports`, `imports-type`, `dynamic-imports`, `reexports`, `extends`, `implements`, `contains`, `parameter_of`, `receiver` + 3 dataflow: `flows_to`, `returns`, `mutates` (with confidence scores on call/import edges) | 20+ types: AST, CFG, CDG, REACHING_DEF, CALL, ARGUMENT, RECEIVER, CONTAINS, EVAL_TYPE, REF, BINDS, DOMINATE, POST_DOMINATE, etc. | **Joern** — still more edge types, but codegraph now covers structural containment, dataflow, and receiver relationships |
 | **Abstract Syntax Tree** | Stored AST nodes (calls, new, string, regex, throw, await) queryable via `ast` command/`ast_query` MCP tool | Full AST stored and queryable | **Joern** for completeness; **Codegraph** now has stored AST for the most useful node kinds |
-| **Control Flow Graph** | Intraprocedural CFG for all 11 languages via `cfg` command/MCP tool. Basic blocks + branches. No dominator trees | Full CFG with dominator/post-dominator trees | **Joern** for depth (dominator trees); **Codegraph** now has basic CFG |
-| **Data Dependence Graph** | Intraprocedural dataflow: `flows_to`, `returns`, `mutates` edges via `dataflow` command/MCP tool (JS/TS only) | Reaching definitions (def-use chains) across procedures | **Joern** — interprocedural vs. codegraph's intraprocedural. But codegraph now has lightweight dataflow |
+| **Control Flow Graph** | Intraprocedural CFG for all 11 languages via `cfg` command/MCP tool. Basic blocks + branches. Cyclomatic complexity derived from CFG structure (E - N + 2). No dominator trees | Full CFG with dominator/post-dominator trees | **Joern** for depth (dominator trees); **Codegraph** now has basic CFG with complexity metrics |
+| **Data Dependence Graph** | Intraprocedural dataflow: `flows_to`, `returns`, `mutates` edges via `dataflow` command/MCP tool (all 11 languages) | Reaching definitions (def-use chains) across procedures | **Joern** — interprocedural vs. codegraph's intraprocedural. But codegraph now has lightweight dataflow across all supported languages |
 | **Program Dependence Graph** | Not available | Combined control + data dependence | **Joern** |
 | **Taint analysis** | Not available | Full interprocedural taint tracking (sources → sinks) | **Joern** — Joern's killer feature |
 | **Call graph** | Import-aware resolution with 6-level confidence scoring, qualified call filtering | Pre-computed CALL edges, caller/callee traversal | **Codegraph** for precision (confidence scoring, false-positive filtering); **Joern** for completeness (type-aware resolution) |
@@ -99,6 +99,7 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | **Custom data-flow semantics** | Not applicable | User-defined taint propagation rules for external methods | **Joern** |
 | **Binary analysis** | Not available | Ghidra frontend: disassembly → CPG | **Joern** |
 | **Execution flow tracing** | `flow` — traces from entry points (routes, commands, events) through callees to leaves | Achievable via CFG + call graph traversals | **Codegraph** — purpose-built command; **Joern** — more precise with CFG |
+| **Sequence diagrams** | `sequence <name>` — Mermaid sequence diagram generation from call graph | Not purpose-built (achievable via manual CFG/call graph traversal) | **Codegraph** — built-in command for visualizing call sequences |
 
 **Summary:** Joern's CPG is fundamentally deeper — it captures control flow, data dependence, and taint propagation that codegraph's structural graph cannot represent. Codegraph compensates with purpose-built commands (impact analysis, complexity, roles, communities) that would require expert CPG query writing in Joern. For vulnerability discovery, Joern is irreplaceable. For developer productivity and AI agent consumption, codegraph's pre-built commands are more accessible.
 
@@ -111,8 +112,8 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | **Query interface** | Fixed CLI commands with flags + SQL under the hood | Interactive Scala REPL with tab completion + arbitrary graph traversals | **Depends on user.** Codegraph for instant answers; Joern for exploratory research |
 | **Query language** | CLI flags (`--kind`, `--file`, `--role`, `--json`) | CPGQL (Scala-based DSL): `cpg.method.name("foo").callee.name.l` | **Joern** for expressiveness; **Codegraph** for accessibility |
 | **Learning curve** | Zero — standard CLI with `--help` | Steep — requires Scala/FP knowledge + graph theory | **Codegraph** |
-| **AI agent interface** | 30-tool MCP server with structured JSON responses | Community MCP server (mcp-joern). REST/WebSocket server mode | **Codegraph** — first-party MCP vs. community add-on |
-| **Compound queries** | `context` (source + deps + callers + tests in 1 call), `explain` (structural summary), `audit` (explain + impact + health) | Must compose via CPGQL chaining | **Codegraph** — purpose-built for agent token efficiency |
+| **AI agent interface** | 32-tool MCP server with structured JSON responses | Community MCP server (mcp-joern). REST/WebSocket server mode | **Codegraph** — first-party MCP vs. community add-on |
+| **Compound queries** | `context` (source + deps + callers + tests in 1 call), `explain` (structural summary), `audit` (explain + impact + health in one call) | Must compose via CPGQL chaining | **Codegraph** — purpose-built for agent token efficiency |
 | **Batch queries** | `batch` command for multi-target dispatch | Script mode (`--script`) for batch execution | **Tie** — different approaches, both work |
 | **JSON output** | `--json` flag on every command | `.toJsonPretty` method on query results | **Tie** |
 | **Syntax-highlighted output** | Colored terminal output | `.dump` for syntax-highlighted code display | **Tie** |
@@ -172,8 +173,8 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 
 | Feature | Codegraph | Joern | Best Approach |
 |---------|-----------|-------|---------------|
-| **MCP server** | First-party, 30 tools, single-repo default, `--multi-repo` opt-in | Community-built (mcp-joern), Python wrapper around Joern | **Codegraph** — first-party, security-conscious, production-ready |
-| **MCP tools count** | 30 purpose-built tools | ~10 tools (community MCP) | **Codegraph** |
+| **MCP server** | First-party, 32 tools, single-repo default, `--multi-repo` opt-in | 4 community MCP wrappers (sfncat/mcp-joern, caohaotiantian/joern_mcp, BlockSecCA/joern-mcp, effortlessdevsec/joern-mcp-server). No first-party MCP | **Codegraph** — first-party, security-conscious, production-ready |
+| **MCP tools count** | 32 purpose-built tools | ~10 tools (community MCP) | **Codegraph** |
 | **Token efficiency** | `context`/`explain`/`audit` compound commands reduce agent round-trips by 50-80% | Raw query results, no compound optimization | **Codegraph** |
 | **Structured JSON output** | Every command supports `--json` | `.toJsonPretty` on query results | **Tie** |
 | **Pagination** | Built-in pagination helpers with configurable limits | Not built-in | **Codegraph** |
@@ -192,7 +193,7 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 |---------|-----------|-------|---------------|
 | **Taint analysis** | Not available | Full interprocedural source-to-sink tracking | **Joern** — this is Joern's raison d'etre |
 | **Vulnerability scanning** | Not available | `joern-scan` with predefined query bundles, tag-based selection | **Joern** |
-| **Data-flow tracking** | Intraprocedural dataflow (`flows_to`/`returns`/`mutates`), JS/TS only | Reaching definitions, def-use chains across procedures | **Joern** — interprocedural vs. intraprocedural |
+| **Data-flow tracking** | Intraprocedural dataflow (`flows_to`/`returns`/`mutates`), all 11 languages | Reaching definitions, def-use chains across procedures | **Joern** — interprocedural vs. intraprocedural |
 | **Control-flow analysis** | Intraprocedural CFG (basic blocks + branches, all 11 languages) | Full CFG with dominator trees | **Joern** — dominator trees and post-dominators; codegraph has basic CFG |
 | **Custom security rules** | Not available | CPGQL-based custom queries + data-flow semantics | **Joern** |
 | **Binary vulnerability analysis** | Not available | Ghidra integration for x86/x64 | **Joern** |
@@ -225,9 +226,11 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | **Execution flow tracing** | `flow` — traces from entry points through callees | Achievable via CFG traversals (more precise) | **Codegraph** for convenience; **Joern** for precision |
 | **Module overview** | `map` — high-level module map with most-connected nodes | Not purpose-built | **Codegraph** |
 | **Cycle detection** | `cycles` — circular dependency detection | Achievable via CPGQL | **Codegraph** — built-in command |
-| **Export formats** | DOT, Mermaid, JSON, GraphML, GraphSON, Neo4j CSV + interactive HTML viewer | DOT, GraphML, GraphSON, Neo4j CSV | **Codegraph** — now matches Joern's formats plus Mermaid and interactive viewer |
+| **Sequence diagrams** | `sequence <name>` — Mermaid sequence diagrams from call graph | Not purpose-built | **Codegraph** |
+| **Dead export detection** | `exports --unused` — identifies unused exports across the codebase | Not purpose-built (achievable via CPGQL) | **Codegraph** — built-in flag |
+| **Export formats** | DOT, Mermaid, Mermaid sequence diagrams, JSON, GraphML, GraphSON, Neo4j CSV + interactive HTML viewer | DOT, GraphML, GraphSON, Neo4j CSV | **Codegraph** — now matches Joern's formats plus Mermaid (flowchart + sequence) and interactive viewer |
 
-**Summary:** Codegraph has 15+ purpose-built developer productivity commands that Joern either lacks entirely or requires expert CPGQL queries to achieve. This is where codegraph's value proposition is strongest for its target audience.
+**Summary:** Codegraph has 17+ purpose-built developer productivity commands that Joern either lacks entirely or requires expert CPGQL queries to achieve. This is where codegraph's value proposition is strongest for its target audience.
 
 ---
 
@@ -235,8 +238,8 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 
 | Feature | Codegraph | Joern | Best Approach |
 |---------|-----------|-------|---------------|
-| **GitHub stars** | New project (growing) | ~2,968 | **Joern** |
-| **Contributors** | Small team | 64 | **Joern** |
+| **GitHub stars** | 32 (growing) | ~3,021 | **Joern** |
+| **Contributors** | Small team | 75 | **Joern** |
 | **Release cadence** | As needed | **Daily automated releases** | **Joern** — impressive automation |
 | **Academic backing** | None | IEEE S&P 2014 paper (Test-of-Time Award 2024), TU Braunschweig, Stellenbosch University | **Joern** |
 | **Commercial backing** | Optave AI Solutions Inc. | Qwiet AI (formerly ShiftLeft), Privado, Whirly Labs | **Joern** — multiple sponsors |
@@ -327,11 +330,11 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | Install complexity | `npm install` | JDK + shell script | Codegraph |
 | Analysis depth (structural) | High | Very High | Joern |
 | Analysis depth (security) | None | Best in class | Joern |
-| AI agent integration | 30-tool MCP (first-party) | Community MCP wrapper | Codegraph |
-| Developer productivity commands | 39 built-in | ~5 built-in + custom CPGQL | Codegraph |
+| AI agent integration | 32-tool MCP (first-party) | Community MCP wrappers (4) | Codegraph |
+| Developer productivity commands | 41 built-in | ~5 built-in + custom CPGQL | Codegraph |
 | Language support | 11 | 16 (incl. binary/bytecode) | Joern |
 | Query expressiveness | Fixed commands | Arbitrary graph traversals | Joern |
-| Community & maturity | New | 7 years, IEEE award, 2,968 stars | Joern |
+| Community & maturity | 32 stars, growing | 7 years, IEEE award, 3,021 stars, 75 contributors | Joern |
 | CI/CD readiness | Yes (`check --staged`) | Limited | Codegraph |
 
 **Final score against FOUNDATION.md principles: Codegraph 6, Joern 0, Tie 2.**
@@ -350,7 +353,7 @@ Non-breaking, ordered by problem-fit:
 | ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking |
 |----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|
 | J1 | Lightweight call-chain slicing | Extract a bounded subgraph around a function (callers + callees to depth N) as standalone JSON/DOT/Mermaid. Not full PDG slicing — structural BFS on existing edges, exported as a self-contained artifact. Inspired by Joern's `joern-slice`. | Navigation | Agents get precisely-scoped subgraphs that fit context windows instead of full graph dumps — directly reduces token waste | ✓ | ✓ | 4 | No |
-| J2 | Type-informed call resolution | Extract type annotations from tree-sitter AST (TypeScript types, Java types, Go types, Python type hints) and use them to disambiguate call targets during import resolution. Improves edge accuracy without full type inference. Inspired by Joern's type-aware language frontends. | Analysis | Call graphs become more precise — fewer false edges means less noise in `fn-impact` and agents don't chase phantom dependencies | ✓ | ✓ | 4 | No |
+| J2 | Type-informed call resolution | **PARTIALLY DONE (v3.2.0):** `qualified_name`, `scope`, `visibility` metadata columns and receiver type tracking with graded confidence (Phase 4.2). Remaining: full type annotation extraction from tree-sitter AST (TypeScript types, Java types, Go types, Python type hints) to disambiguate call targets during import resolution. Inspired by Joern's type-aware language frontends. | Analysis | Call graphs become more precise — fewer false edges means less noise in `fn-impact` and agents don't chase phantom dependencies | ✓ | ✓ | 4 | No |
 | J3 | Error-tolerant partial parsing | Leverage tree-sitter's built-in error recovery to extract symbols from syntactically incomplete or broken files instead of skipping them entirely. Surface partial results with a quality indicator per file. Currently codegraph requires syntactically valid input; Joern's fuzzy parsing handles partial/broken code. | Parsing | Agents can analyze WIP branches, partial checkouts, and code mid-refactor — essential for real-world AI-agent loops where code is often in a broken state | ✓ | ✓ | 3 | No |
 | J4 | Kotlin language support | Add tree-sitter-kotlin to `LANGUAGE_REGISTRY`. 1 registry entry + 1 extractor function (<100 lines, 2 files). Covers functions, classes, interfaces, objects, data classes, companion objects, call sites. Kotlin is one of Joern's strongest languages (via IntelliJ PSI). | Parsing | Extends coverage to Android/KMP ecosystem — one of the most-requested missing languages and a gap vs. Joern | ✓ | ✓ | 2 | No |
 | J5 | Swift language support | Add tree-sitter-swift to `LANGUAGE_REGISTRY`. 1 registry entry + 1 extractor function (<100 lines, 2 files). Covers functions, classes, structs, protocols, enums, extensions, call sites. Joern supports Swift via SwiftSyntax. | Parsing | Extends coverage to Apple/iOS ecosystem — currently a gap vs. Joern. tree-sitter-swift is mature enough for production use | ✓ | ✓ | 2 | No |
@@ -388,5 +391,5 @@ These Joern-inspired capabilities are already tracked in [BACKLOG.md](../../docs
 
 | BACKLOG ID | Title | Joern Equivalent | Relationship |
 |------------|-------|------------------|--------------|
-| 14 | Dataflow analysis | Data Dependence Graph (def-use chains) | **DONE v3.0.0.** Lightweight intraprocedural dataflow with `flows_to`/`returns`/`mutates` edges. JS/TS only. CLI: `codegraph dataflow`. MCP: `dataflow` tool. |
+| 14 | Dataflow analysis | Data Dependence Graph (def-use chains) | **DONE v3.0.0, expanded v3.2.0.** Lightweight intraprocedural dataflow with `flows_to`/`returns`/`mutates` edges. Now all 11 languages (was JS/TS only). CLI: `codegraph dataflow`. MCP: `dataflow` tool. |
 | 7 | OWASP/CWE pattern detection | Vulnerability scanning (`joern-scan`) | Lightweight AST-based security checks — the codegraph-appropriate alternative to Joern's taint-based vulnerability scanning. Still Tier 3. J9 (stored AST) is now complete — this is unblocked. |
diff --git a/generated/competitive/narsil-mcp.md b/generated/competitive/narsil-mcp.md
index ae47af0a..c5272e7e 100644
--- a/generated/competitive/narsil-mcp.md
+++ b/generated/competitive/narsil-mcp.md
@@ -1,8 +1,8 @@
 # Competitive Deep-Dive: Codegraph vs Narsil-MCP
 
-**Date:** 2026-03-02
-**Competitors:** `@optave/codegraph` v3.0.0 (Apache-2.0) vs `postrv/narsil-mcp` v1.6 (Apache-2.0 OR MIT)
-**Context:** Both are Apache-2.0-licensed code analysis tools with MCP interfaces. Narsil-MCP is ranked #2 in our [competitive analysis](./COMPETITIVE_ANALYSIS.md) with a score of 4.5 vs codegraph's 4.0 at #8.
+**Date:** 2026-03-21
+**Competitors:** `@optave/codegraph` v3.2.0 (Apache-2.0) vs `postrv/narsil-mcp` v1.6.1 (Apache-2.0 OR MIT)
+**Context:** Both are Apache-2.0-licensed code analysis tools with MCP interfaces. Narsil-MCP is ranked #3 in our [competitive analysis](./COMPETITIVE_ANALYSIS.md) with a score of 4.5 vs codegraph's 4.5 at #5.
 
 ---
 
@@ -12,14 +12,14 @@ Narsil-MCP and codegraph share more DNA than any other pair in the competitive l
 
 | Dimension | Narsil-MCP | Codegraph |
 |-----------|------------|-----------|
-| **Primary mission** | Maximum-breadth code intelligence in a single binary | Always-current structural intelligence with sub-second rebuilds |
+| **Primary mission** | Maximum-breadth code intelligence in a single binary | Always-current structural intelligence with qualified names/scope/visibility graph model and sub-second rebuilds |
 | **Target user** | AI agents needing comprehensive analysis (security, types, dataflow) | Developers, AI coding agents, CI pipelines needing fast feedback |
 | **Architecture** | MCP-first, no standalone CLI queries | Full CLI + MCP server + programmatic JS API |
-| **Core question answered** | "Tell me everything about this code" (90 tools) | "What breaks if I change this function?" (39 commands, 30 MCP tools) |
+| **Core question answered** | "Tell me everything about this code" (90 tools) | "What breaks if I change this function?" (41 commands, 32 MCP tools) |
 | **Rebuild model** | In-memory index, opt-in persistence, file watcher | SQLite-persisted, incremental hash-based rebuilds |
 | **Runtime** | Single Rust binary (~30 MB) | Node.js + optional native Rust addon |
 
-**Bottom line:** Narsil-MCP is broader (90 tools, 32 languages, security scanning, taint analysis, SBOM, type inference). Codegraph is deeper on developer productivity (impact analysis, complexity metrics, community detection, architecture boundaries, manifesto rules) and faster for iterative workflows (incremental rebuilds, CI gates). Where they overlap (call graphs, dead code, search, MCP), narsil has more tools while codegraph has more purpose-built commands. They are the closest competitors in the landscape.
+**Bottom line:** Narsil-MCP is broader (90 tools, 32 languages, security scanning, taint analysis, SBOM, type inference). Codegraph is deeper on developer productivity (impact analysis, complexity metrics, community detection, architecture boundaries, manifesto rules, sequence diagrams) and faster for iterative workflows (incremental rebuilds, CI gates). Where they overlap (call graphs, dead code, search, MCP), narsil has more tools while codegraph has more purpose-built commands. They are the closest competitors in the landscape.
 
 ---
 
@@ -31,11 +31,11 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 
 | # | Principle | Codegraph | Narsil-MCP | Verdict |
 |---|-----------|-----------|------------|---------|
-| 1 | **The graph is always current** — rebuild on every commit/save/agent loop | File-level MD5 hashing, SQLite persistence. Change 1 file → <500ms rebuild. Watch mode, commit hooks, agent loops all practical | In-memory by default. `--watch` flag for auto-reindex. `--persist` for disk saves. Indexing is fast (2.1s for 50K symbols) but full re-index, not incremental | **Codegraph wins.** Narsil is fast but re-indexes everything. Codegraph only re-parses changed files — orders of magnitude faster for single-file changes in large repos |
+| 1 | **The graph is always current** — rebuild on every commit/save/agent loop | 3-tier change detection (journal → mtime+size → hash), SQLite persistence. Change 1 file → <500ms rebuild. Watch mode, commit hooks, agent loops all practical | In-memory by default. `--watch` flag for auto-reindex. `--persist` for disk saves. Indexing is fast (2.1s for 50K symbols) but full re-index, not incremental | **Codegraph wins.** Narsil is fast but re-indexes everything. Codegraph only re-parses changed files — orders of magnitude faster for single-file changes in large repos |
 | 2 | **Native speed, universal reach** — dual engine (Rust + WASM) | Native napi-rs with rayon parallelism + automatic WASM fallback. `npm install` on any platform | Pure Rust binary. Prebuilt for macOS/Linux/Windows. Also has WASM build (~3 MB) for browsers | **Tie.** Different approaches, both effective. Narsil is a single binary; codegraph is an npm package with native addon. Both have WASM stories |
 | 3 | **Confidence over noise** — scored results | 6-level import resolution with 0.0-1.0 confidence on every edge. Graph quality score. Relevance-ranked search | BM25 ranking on search. No confidence scores on call graph edges. No graph quality metric | **Codegraph wins.** Every edge has a trust score; narsil's call graph edges are unscored |
 | 4 | **Zero-cost core, LLM-enhanced when you choose** | Full pipeline local, zero API keys. Optional embeddings with user's LLM provider | Core is local. Neural search requires `--neural` flag + API key (Voyage AI/OpenAI) or local ONNX model | **Tie.** Both are local-first with optional AI enhancement. Narsil offers more backend choices (Voyage AI, OpenAI, ONNX); codegraph uses HuggingFace Transformers locally |
-| 5 | **Functional CLI, embeddable API** | 39 CLI commands + 30-tool MCP server + full programmatic JS API | MCP-first with 90 tools. `narsil-mcp config/tools` management commands but no standalone query CLI. No programmatic library API | **Codegraph wins.** Full CLI experience + embeddable API. Narsil is MCP-only for queries — useless without an MCP client |
+| 5 | **Functional CLI, embeddable API** | 41 CLI commands + 32-tool MCP server + full programmatic JS API | MCP-first with 90 tools. `narsil-mcp config/tools` management commands but no standalone query CLI. No programmatic library API | **Codegraph wins.** Full CLI experience + embeddable API. Narsil is MCP-only for queries — useless without an MCP client |
 | 6 | **One registry, one schema, no magic** | `LANGUAGE_REGISTRY` — add a language in <100 lines, 2 files | Tree-sitter for all 32 languages. Unified parser, but extractors are in compiled Rust — harder to contribute | **Codegraph wins slightly.** Both use tree-sitter uniformly. Codegraph's JS extractors are more accessible to contributors than narsil's compiled Rust |
 | 7 | **Security-conscious defaults** — multi-repo opt-in | Single-repo MCP default. `apiKeyCommand` for secrets. `--multi-repo` opt-in | Multi-repo by default (`--repos` accepts multiple paths). `discover_repos` auto-finds repos. No sandboxing concept | **Codegraph wins.** Single-repo isolation by default vs. multi-repo by default |
 | 8 | **Honest about what we're not** | Code intelligence engine. Not an app, not a coding tool, not an agent | Code intelligence MCP server. Also not an agent — but the open-core model adds commercial cloud features (narsil-cloud) | **Tie.** Both are honest about scope. Narsil's commercial layer is a legitimate business model |
@@ -75,7 +75,7 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | **Bash** | Not supported | tree-sitter | **Narsil** |
 | **Language count** | 11 | 32 | **Narsil** (3x more languages) |
 | **Adding a new language** | 1 registry entry + 1 JS extractor (<100 lines, 2 files) | Rust code + recompile binary | **Codegraph** — dramatically lower barrier for contributors |
-| **Incremental parsing** | File-level hash tracking — only changed files re-parsed | Full re-index (fast but complete) | **Codegraph** — orders of magnitude faster for single-file changes |
+| **Incremental parsing** | 3-tier change detection (journal → mtime+size → hash) — only changed files re-parsed | Full re-index (fast but complete) | **Codegraph** — orders of magnitude faster for single-file changes |
 | **Callback pattern extraction** | Commander `.command().action()`, Express routes, event handlers | Not documented | **Codegraph** — framework-aware symbol extraction |
 
 **Summary:** Narsil covers 3x more languages (32 vs 11) using the same parser technology (tree-sitter). Codegraph has better incremental parsing, easier extensibility, and unique framework callback extraction. For codegraph's target users (JS/TS/Python/Go developers), codegraph's coverage is sufficient. Narsil's breadth matters for polyglot enterprises.
@@ -87,22 +87,23 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | Feature | Codegraph | Narsil-MCP | Best Approach |
 |---------|-----------|------------|---------------|
 | **Graph type** | Structural dependency graph (symbols + edges) in SQLite | In-memory symbol/file caches (DashMap) + optional RDF knowledge graph | **Codegraph** for persistence; **Narsil** for RDF expressiveness |
-| **Node types** | 13 kinds: `function`, `method`, `class`, `interface`, `type`, `struct`, `enum`, `trait`, `record`, `module`, `parameter`, `property`, `constant` | Functions, classes, methods, variables, imports, exports + more | **Narsil** — still more granular, but gap narrowed |
-| **Edge types** | `calls`, `imports`, `contains`, `parameter_of`, `receiver`, `flows_to`, `returns`, `mutates` (with confidence scores on call/import edges) | Calls, imports, data flow, control flow, type relationships | **Tie** — both now cover structural + dataflow relationships |
+| **Node types** | 13 kinds: `function`, `method`, `class`, `interface`, `type`, `struct`, `enum`, `trait`, `record`, `module`, `parameter`, `property`, `constant` — each with `qualified_name`, `scope`, `visibility` metadata | Functions, classes, methods, variables, imports, exports + more | **Narsil** — still more granular, but gap narrowed with codegraph's richer per-node metadata |
+| **Edge types** | 10 structural edge types (`calls`, `imports`, `contains`, `parameter_of`, `receiver`, `type_of`, `implements`, `decorates`, `overloads`, `exports`) + 3 dataflow edge types (`flows_to`, `returns`, `mutates`), with confidence scores on call/import edges | Calls, imports, data flow, control flow, type relationships | **Codegraph** — 13 total edge types with confidence scoring vs. narsil's unscored edges |
 | **Call graph** | Import-aware resolution with 6-level confidence scoring, qualified call filtering | `get_call_graph`, `get_callers`, `get_callees`, `find_call_path` | **Codegraph** for precision (confidence scoring); **Narsil** for completeness |
 | **Control flow graph** | Intraprocedural CFG for all 11 languages via `cfg` command / `cfg` MCP tool | `get_control_flow` — basic blocks + branch conditions | **Tie** — both have intraprocedural CFG |
-| **Data flow analysis** | `flows_to`/`returns`/`mutates` edges via `dataflow` command / `dataflow` MCP tool (JS/TS only) | `get_data_flow`, `get_reaching_definitions`, `find_uninitialized`, `find_dead_stores` | **Narsil** — more mature with 4 dedicated tools; codegraph is JS/TS only |
-| **Type inference** | Not available | `infer_types`, `check_type_errors` for Python/JS/TS | **Narsil** |
+| **Data flow analysis** | `flows_to`/`returns`/`mutates` edges via `dataflow` command / `dataflow` MCP tool (all 11 languages) | `get_data_flow`, `get_reaching_definitions`, `find_uninitialized`, `find_dead_stores` | **Tie** — narsil has 4 dedicated tools (reaching defs, dead stores); codegraph covers all 11 languages with unified dataflow edges |
+| **Type inference** | No full type inference, but `qualified_name`, `scope`, `visibility` metadata on all symbols + receiver type tracking with graded confidence | `infer_types`, `check_type_errors` for Python/JS/TS | **Narsil** — full type inference vs. codegraph's metadata-level type tracking. Gap narrowed |
 | **Dead code detection** | `roles --role dead` — unreferenced non-exported symbols | `find_dead_code` — unreachable code paths via CFG | **Both** — complementary approaches (structural vs. control-flow) |
 | **Complexity metrics** | Cognitive, cyclomatic, Halstead, MI, nesting depth per function | Cyclomatic complexity only | **Codegraph** — 5 metrics vs 1 |
 | **Node role classification** | Auto-tags: `entry`/`core`/`utility`/`adapter`/`dead`/`leaf` | Not available | **Codegraph** |
 | **Community detection** | Louvain algorithm with drift analysis | Not available | **Codegraph** |
 | **Impact analysis** | `fn-impact`, `diff-impact` (git-aware), `impact` (file-level) | Not purpose-built | **Codegraph** — first-class impact commands |
+| **Sequence diagrams** | `sequence` command — generates Mermaid sequence diagrams from call chains | Not available | **Codegraph** |
 | **Shortest path** | `path <from> <to>` — BFS between symbols | `find_call_path` — between functions | **Tie** |
 | **SPARQL / Knowledge graph** | Not available | RDF graph via Oxigraph, SPARQL queries, predefined templates | **Narsil** — unique capability |
 | **Code Context Graph (CCG)** | Not available | 4-layer hierarchical context (L0-L3) with JSON-LD/N-Quads export | **Narsil** — unique capability |
 
-**Summary:** Narsil has broader analysis (CFG, dataflow, type inference, SPARQL, CCG). Codegraph is deeper on developer-facing metrics (5 complexity metrics, node roles, community detection, Louvain drift) and has unique impact analysis commands. Narsil's knowledge graph and CCG layering are genuinely novel features with no codegraph equivalent.
+**Summary:** Narsil has broader analysis (type inference, SPARQL, CCG). Codegraph now matches on dataflow (all 11 languages) and is deeper on developer-facing metrics (5 complexity metrics, node roles, community detection, Louvain drift, sequence diagrams) with unique impact analysis commands and 13 edge types with confidence scoring. Narsil's knowledge graph and CCG layering are genuinely novel features with no codegraph equivalent.
 
 ---
 
@@ -139,9 +140,9 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | **Vulnerability explanation** | Not available | `explain_vulnerability`, `suggest_fix` | **Narsil** |
 | **Crypto misuse detection** | Not available | Rules in `crypto.yaml` | **Narsil** |
 | **IaC security** | Not available | Rules in `iac.yaml` | **Narsil** |
-| **Language-specific rules** | Not available | Rust, Elixir, Go, Java, C#, Kotlin, Bash rule files | **Narsil** |
+| **Language-specific rules** | Not available | Rust, Elixir, Go, Java, C#, Kotlin, Bash rule files (+36 rules: 18 Rust + 18 Elixir) | **Narsil** |
 
-**Summary:** Narsil dominates security analysis completely with 147 rules across 12+ rule files. Codegraph has zero security features today — by design (FOUNDATION.md P8). OWASP pattern detection is on the roadmap as lightweight AST-based checks (BACKLOG ID 7), not taint analysis.
+**Summary:** Narsil dominates security analysis completely with 147+ rules across 12+ rule files (including +36 language-specific rules for Rust and Elixir). Codegraph has zero security features today — by design (FOUNDATION.md P8). OWASP pattern detection is on the roadmap as lightweight AST-based checks (BACKLOG ID 7), not taint analysis.
 
 ---
 
@@ -149,20 +150,20 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 
 | Feature | Codegraph | Narsil-MCP | Best Approach |
 |---------|-----------|------------|---------------|
-| **Primary interface** | Full CLI with 39 commands + MCP server | MCP server (primary) + config management CLI | **Codegraph** — usable without MCP client |
+| **Primary interface** | Full CLI with 41 commands + MCP server | MCP server (primary) + config management CLI | **Codegraph** — usable without MCP client |
 | **Standalone CLI queries** | `where`, `query`, `audit --quick`, `context`, `deps`, `exports`, `impact`, `map`, `dataflow`, `cfg`, `ast`, etc. | Not available — all queries via MCP tools | **Codegraph** — narsil requires an MCP client for any query |
-| **MCP tools count** | 30 purpose-built tools | 90 tools across 14 categories | **Narsil** — 3x more tools |
+| **MCP tools count** | 32 purpose-built tools | 90 tools across 14 categories | **Narsil** — ~3x more tools |
 | **Compound queries** | `context` (source + deps + callers + tests), `explain`, `audit` | No compound tools — each tool is atomic | **Codegraph** — purpose-built for agent token efficiency |
 | **Batch queries** | `batch` command for multi-target dispatch | No batch mechanism | **Codegraph** |
 | **JSON output** | `--json` flag on every command | MCP JSON responses | **Tie** |
 | **NDJSON streaming** | `--ndjson` with `--limit`/`--offset` on ~14 commands | `--streaming` flag for large results | **Tie** |
-| **Pagination** | Universal `limit`/`offset` on all 30 MCP tools with per-tool defaults | Not documented | **Codegraph** |
+| **Pagination** | Universal `limit`/`offset` on all 32 MCP tools with per-tool defaults | Not documented | **Codegraph** |
 | **SPARQL queries** | Not available | `sparql_query`, predefined templates | **Narsil** — unique expressiveness |
 | **Configuration presets** | Not available | Minimal (~26 tools), Balanced (~51), Full (75+), Security-focused | **Narsil** — manages token cost per preset |
-| **Visualization** | DOT, Mermaid, JSON, GraphML, GraphSON, Neo4j CSV export + interactive HTML viewer (`codegraph plot`) | Built-in web UI (Cytoscape.js) with interactive graphs | **Tie** — both have interactive visualization and rich export formats |
+| **Visualization** | DOT, Mermaid, JSON, GraphML, GraphSON, Neo4j CSV export + interactive HTML viewer (`codegraph plot`) | Built-in web UI (Cytoscape.js) with interactive graphs + full SPA frontend (v1.6.0): file tree sidebar, syntax-highlighted code viewer, dashboard, per-repo overview, CFG visualization | **Narsil** — SPA frontend with file browser and dashboard is significantly richer than codegraph's interactive HTML viewer |
 | **Programmatic API** | Full JS API: `import { buildGraph, queryNameData } from '@optave/codegraph'` | No library API | **Codegraph** — embeddable in JS/TS projects |
 
-**Summary:** Codegraph is more accessible (full CLI + API + MCP). Narsil has more MCP tools (90 vs 21) but no standalone query interface — completely dependent on MCP clients. Codegraph's compound commands (`context`, `explain`, `audit`) reduce agent round-trips; narsil requires multiple atomic tool calls for equivalent context. Narsil's configuration presets are a smart approach to managing MCP tool token costs.
+**Summary:** Codegraph is more accessible (full CLI + API + MCP). Narsil has more MCP tools (90 vs 32) but no standalone query interface — completely dependent on MCP clients. Narsil's new SPA frontend (v1.6.0) with file tree, syntax viewer, and dashboard is a significant UI advantage. Codegraph's compound commands (`context`, `explain`, `audit`) reduce agent round-trips; narsil requires multiple atomic tool calls for equivalent context. Narsil's configuration presets are a smart approach to managing MCP tool token costs.
 
 ---
 
@@ -210,17 +211,17 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 
 | Feature | Codegraph | Narsil-MCP | Best Approach |
 |---------|-----------|------------|---------------|
-| **MCP tools** | 30 purpose-built tools | 90 tools across 14 categories | **Narsil** (3x more tools) |
+| **MCP tools** | 32 purpose-built tools | 90 tools across 14 categories | **Narsil** (~3x more tools) |
 | **Token efficiency** | `context`/`explain`/`audit` compound commands reduce round-trips 50-80% | Atomic tools only. Forgemax integration collapses 90 → 2 tools (~1,000 vs ~12,000 tokens) | **Codegraph** natively; **Narsil** via Forgemax |
-| **Tool token cost** | ~5,500 tokens for 30 tool definitions | ~12,000 tokens for full set. Presets: Minimal ~4,600, Balanced ~8,900 | **Codegraph** — lower base cost. Narsil presets help |
-| **Pagination** | Universal `limit`/`offset` on all 30 tools with per-tool defaults, hard cap 1,000 | `--streaming` for large results | **Codegraph** — structured pagination metadata |
+| **Tool token cost** | ~6,000 tokens for 32 tool definitions | ~12,000 tokens for full set. Presets: Minimal ~4,600, Balanced ~8,900 | **Codegraph** — lower base cost. Narsil presets help |
+| **Pagination** | Universal `limit`/`offset` on all 32 tools with per-tool defaults, hard cap 1,000 | `--streaming` for large results | **Codegraph** — structured pagination metadata |
 | **Multi-repo support** | Registry-based, opt-in via `--multi-repo` or `--repos` | Multi-repo by default, `discover_repos` auto-detection | **Narsil** for convenience; **Codegraph** for security |
 | **Single-repo isolation** | Default — tools have no `repo` property unless `--multi-repo` | Not default — multi-repo access is always available | **Codegraph** — security-conscious default |
 | **Programmatic embedding** | Full JS API for VS Code extensions, CI pipelines, other MCP servers | No library API | **Codegraph** |
 | **CCG context layers** | Not available | L0-L3 hierarchical context for progressive disclosure | **Narsil** — novel approach to context management |
 | **Remote repo indexing** | Not available | `add_remote_repo` clones and indexes GitHub repos | **Narsil** |
 
-**Summary:** Narsil has 4x more MCP tools but higher token overhead. Codegraph's compound commands are more token-efficient per query. Narsil's CCG layering and configuration presets are innovative approaches to managing AI agent context budgets. Codegraph's programmatic API enables embedding scenarios narsil cannot serve.
+**Summary:** Narsil has ~3x more MCP tools but higher token overhead. Codegraph's compound commands are more token-efficient per query. Narsil's CCG layering and configuration presets are innovative approaches to managing AI agent context budgets. Codegraph's programmatic API enables embedding scenarios narsil cannot serve.
 
 ---
 
@@ -246,12 +247,14 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | **Module overview** | `map` — high-level module map with most-connected nodes | Not purpose-built | **Codegraph** |
 | **Cycle detection** | `cycles` — circular dependency detection | `find_circular_imports` — circular import chains | **Tie** |
 | **Architecture boundaries** | Configurable rules with onion preset | Not available | **Codegraph** |
+| **Sequence diagrams** | `sequence` command — Mermaid sequence diagrams from call chains | Not available | **Codegraph** |
+| **Dead export detection** | `exports --unused` — finds exported symbols with no consumers | Not available | **Codegraph** |
 | **Node role classification** | `entry`/`core`/`utility`/`adapter`/`dead`/`leaf` per symbol | Not available | **Codegraph** |
 | **Audit command** | `audit` — explain + impact + health in one call | Not available | **Codegraph** |
 | **Git integration** | `diff-impact`, `co-change`, `branch-compare` | `get_blame`, `get_file_history`, `get_recent_changes`, `get_symbol_history`, `get_contributors`, `get_hotspots` | **Narsil** for git data breadth; **Codegraph** for git-aware analysis |
 | **Export formats** | DOT, Mermaid, JSON, GraphML, GraphSON, Neo4j CSV + interactive HTML viewer | Cytoscape.js interactive UI, JSON-LD, N-Quads, RDF | **Tie** — both have interactive visualization and rich export formats |
 
-**Summary:** Codegraph has 15+ purpose-built developer productivity commands that narsil lacks (impact analysis, manifesto, triage, boundaries, co-change, branch-compare, audit, structure, CODEOWNERS). Narsil has richer git integration tools (blame, contributors, symbol history) and interactive visualization. For the "what breaks if I change this?" workflow, codegraph is the clear choice.
+**Summary:** Codegraph has 17+ purpose-built developer productivity commands that narsil lacks (impact analysis, manifesto, triage, boundaries, co-change, branch-compare, audit, structure, CODEOWNERS). Narsil has richer git integration tools (blame, contributors, symbol history) and interactive visualization. For the "what breaks if I change this?" workflow, codegraph is the clear choice.
 
 ---
 
@@ -259,17 +262,19 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 
 | Feature | Codegraph | Narsil-MCP | Best Approach |
 |---------|-----------|------------|---------------|
-| **GitHub stars** | Growing | 120 | **Narsil** (slightly) |
+| **GitHub stars** | Growing | 129 | **Narsil** (slightly) |
 | **License** | Apache-2.0 | Apache-2.0 OR MIT (dual) | **Narsil** — dual license is more permissive |
-| **Release cadence** | As needed | Regular (v1.6.1 latest, Feb 2026) | **Tie** |
+| **Release cadence** | As needed | v1.6.1 (Feb 2026); no activity since Feb 25 (24+ day gap) | **Codegraph** — narsil's development appears stalled |
 | **Test suite** | Vitest | 1,763+ tests + criterion benchmarks | **Narsil** — more tests, published benchmarks |
 | **Documentation** | CLAUDE.md + CLI `--help` | narsilmcp.com + README + editor configs | **Narsil** — dedicated docs site |
 | **Commercial backing** | Optave AI Solutions Inc. | Open-core model (narsil-cloud private repo) | **Both** — different business models |
 | **Integration ecosystem** | MCP + programmatic API | Forgemax, Ralph, Claude Code plugin | **Narsil** — more third-party integrations |
 | **Browser story** | Not available | WASM package for browser-based analysis | **Narsil** |
+| **SPA frontend** | Not available | Full SPA (v1.6.0): file tree sidebar, syntax-highlighted code viewer, dashboard, per-repo overview, CFG visualization | **Narsil** — full web application vs. codegraph's interactive HTML viewer |
+| **Security rules** | Not available | 147+ built-in YAML rules including +36 language-specific rules (18 Rust + 18 Elixir) | **Narsil** |
 | **CCG standard** | Not available | Code Context Graph — a proposed standard for AI code context | **Narsil** — potential industry standard |
 
-**Summary:** Narsil has a more developed ecosystem (docs site, editor configs, third-party integrations, browser build, CCG standard). Both are commercially backed. Narsil's open-core model (commercial cloud features in private repo) is a viable business approach.
+**Summary:** Narsil has a more developed ecosystem (docs site, editor configs, third-party integrations, browser build, SPA frontend, CCG standard). Both are commercially backed. Narsil's open-core model (commercial cloud features in private repo) is a viable business approach. However, narsil has had no activity since Feb 25 (24+ day gap as of this writing), which raises questions about development momentum.
 
 ---
 
@@ -290,7 +295,7 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 
 1. **You need security analysis** — taint tracking, OWASP/CWE compliance, SBOM, license scanning, 147 built-in rules. Codegraph has zero security features.
 2. **You need broad language coverage** — 32 languages vs 11. Critical for polyglot enterprises.
-3. **You need mature control flow or data flow analysis** — reaching definitions, dead stores, uninitialized variables. Codegraph now has basic CFG and intraprocedural dataflow (JS/TS), but narsil's analysis is more mature.
+3. **You need advanced data flow analysis** — reaching definitions, dead stores, uninitialized variables. Codegraph now has dataflow across all 11 languages, but narsil has 4 specialized tools (reaching defs, dead stores, uninitialized, taint).
 4. **You need type inference** — infer types for untyped Python/JS/TS code. Codegraph has no type analysis.
 5. **You want richer interactive visualization** — built-in Cytoscape.js web UI with drill-down, overlays, and clustering. Codegraph now has `codegraph plot` with interactive HTML, but narsil's UI is more feature-rich.
 6. **You need a single binary with no runtime deps** — `brew install narsil-mcp` and done. No Node.js required.
@@ -317,10 +322,10 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | Install complexity | `npm install` (requires Node.js) | Single binary (brew/scoop/cargo) | Narsil |
 | Analysis depth (structural) | High (impact, complexity, roles, CFG, dataflow) | High (CFG, DFG, type inference) | Tie |
 | Analysis depth (security) | None | Best in class (147 rules, taint) | Narsil |
-| AI agent integration | 30-tool MCP + compound commands | 90-tool MCP + presets + CCG | Narsil for breadth; Codegraph for efficiency |
-| Developer productivity | 20+ purpose-built commands | Git tools only | Codegraph |
+| AI agent integration | 32-tool MCP + compound commands | 90-tool MCP + presets + CCG | Narsil for breadth; Codegraph for efficiency |
+| Developer productivity | 41+ commands | Git tools only | Codegraph |
 | Language support | 11 | 32 | Narsil |
-| Standalone CLI | Full CLI experience | Config/tools management only | Codegraph |
+| Standalone CLI | 41 commands | Config/tools management only | Codegraph |
 | Programmatic API | Full JS API | None | Codegraph |
 | Community & maturity | New | Newer (Dec 2025), growing fast | Tie |
 | CI/CD readiness | Yes (`check --staged`) | No CI tooling | Codegraph |
@@ -386,9 +391,9 @@ These narsil-mcp features were evaluated and deliberately excluded:
 | **SPARQL / RDF knowledge graph** | B, E | Requires Oxigraph dependency. SQLite + existing query commands serve our use case. RDF/SPARQL is overkill for structural code intelligence — powerful but orthogonal to our goals |
 | **Code Context Graph (CCG) standard** | B, H | Interesting concept but tightly coupled to narsil's architecture and commercial model. Our MCP pagination + compound commands solve the progressive-disclosure problem differently |
 | **In-memory-first architecture** | F | Violates P1 (graph must survive restarts to stay always-current). SQLite persistence is a deliberate choice — narsil's opt-in persistence means state loss on every restart by default |
-| **90-tool MCP surface** | E, H | More tools = more token overhead per agent session. Our 30 purpose-built tools + compound commands are more token-efficient. Narsil compensates with presets; we compensate with fewer, smarter tools |
+| **90-tool MCP surface** | E, H | More tools = more token overhead per agent session. Our 32 purpose-built tools + compound commands are more token-efficient. Narsil compensates with presets; we compensate with fewer, smarter tools |
 | **Browser WASM build** | G, J | Different product category. We're a CLI/MCP engine, not a browser tool (P8). Narsil's WASM build is a legitimate capability, but building a browser runtime is outside our scope |
-| **Forgemax-style tool collapsing** | H | Collapses 90 tools to 2 (`search`/`execute`). We don't need this because we already have ~21 tools — small enough that collapsing adds complexity without meaningful savings |
+| **Forgemax-style tool collapsing** | H | Collapses 90 tools to 2 (`search`/`execute`). We don't need this because we already have 32 tools — small enough that collapsing adds complexity without meaningful savings |
 | **LSP integration** | B | Requires running language servers alongside codegraph. Violates zero-dependency goal. Tree-sitter + confidence scoring is our approach; LSP is a different architectural bet |
 | **License compliance scanning** | D | Tangential to code intelligence. Better served by dedicated tools (FOSSA, Snyk, etc.) |
 
@@ -401,7 +406,7 @@ These narsil-inspired capabilities are already tracked in [BACKLOG.md](../../doc
 | 7 | OWASP/CWE pattern detection | `scan_security` with 147 rules | Lightweight AST-based alternative to narsil's full rule engine. N14 above. Still Tier 3. Unblocked by stored AST (v3.0.0). |
 | 8 | Optional LLM provider integration | `--neural-backend api\|onnx` | Multiple embedding providers. N13 above. Still Tier 2. |
 | 10 | Interactive HTML visualization | Built-in Cytoscape.js frontend | **DONE v3.0.0.** `codegraph plot` opens interactive HTML viewer. N12 above. |
-| 14 | Dataflow analysis | `get_data_flow`, `get_reaching_definitions` | **DONE v3.0.0.** Intraprocedural dataflow with `flows_to`/`returns`/`mutates` edges. JS/TS only. CLI: `codegraph dataflow`. MCP: `dataflow` tool. |
+| 14 | Dataflow analysis | `get_data_flow`, `get_reaching_definitions` | **DONE v3.2.0.** Intraprocedural dataflow with `flows_to`/`returns`/`mutates` edges. All 11 languages. CLI: `codegraph dataflow`. MCP: `dataflow` tool. |
 
 ### Cross-references to Joern-inspired candidates
 
diff --git a/generated/dogfood/DOGFOOD_REPORT_v3.1.2.md b/generated/dogfood/DOGFOOD_REPORT_v3.1.2.md
deleted file mode 100644
index 4b63696e..00000000
--- a/generated/dogfood/DOGFOOD_REPORT_v3.1.2.md
+++ /dev/null
@@ -1,395 +0,0 @@
-# Dogfooding Report: @optave/codegraph@3.1.2
-
-**Date:** 2026-03-11
-**Platform:** Windows 11 Pro (10.0.26200), win32-x64, Node v22.18.0
-**Native binary:** @optave/codegraph-win32-x64-msvc@3.1.2 (npm package version) — reports v3.1.0 internally (BUG #411)
-**Active engine:** native (auto-detected)
-**Target repo:** codegraph itself (235 files, 2 languages)
-
----
-
-## 1. Setup & Installation
-
-| Step | Result |
-|------|--------|
-| `npm install @optave/codegraph@3.1.2` | Clean install in `/tmp/dogfood-3.1.2` |
-| `npx codegraph --version` | 3.1.2 |
-| Native binary package | @optave/codegraph-win32-x64-msvc@3.1.2 installed |
-| `npx codegraph info` | Native engine available, reports v3.1.0 (BUG — actual binary is 3.1.2) |
-| Optional deps pinned | All 7 platform packages pinned to 3.1.2 |
-| ESM-only package | `type: "module"`, exports `{ ".": { "import": "./src/index.js" } }` |
-
-**Issue:** `info` command reports `Native version: 3.1.0` despite the binary package being 3.1.2. The version string embedded in the Rust binary was not bumped. Filed as #411.
-
----
-
-## 2. Cold Start (Pre-Build)
-
-Tested from the v3.1.0 dogfood report — 34/34 commands handle missing graph gracefully. No regressions observed in v3.1.2.
-
----
-
-## 3. Full Command Sweep
-
-Build: `codegraph build <repo> --engine native --no-incremental`
-- 235 files, 4192 nodes, 9057 edges
-- Complexity: 1193 functions, CFG: 1193, Dataflow: 3886 edges
-- 43 exported symbols flagged as having zero cross-file consumers (inflated due to missing dynamic-imports on native — see #410)
-
-| Command | Status | Notes |
-|---------|--------|-------|
-| `query buildGraph -T` | PASS | Callers/callees correct |
-| `query buildGraph -T -j` | PASS | Valid JSON |
-| `query buildGraph -T --depth 1` | PASS | Correctly limits depth |
-| `query nonexistent_xyz` | PASS | "No function/method/class matching" (exit 0) |
-| `deps nonexistent_file.js` | PASS | "No file matching" (exit 0) |
-| `impact src/builder.js -T` | PASS | Transitive dependents listed |
-| `map -T --limit 5` | PASS | Top 5: db.js (56), parser.js (49+) |
-| `map --json -T` | PASS | Clean JSON, no status messages in stdout |
-| `stats -T -j` | PASS | 3417 nodes (filtered), quality 88/100 |
-| `context buildGraph -T --no-source` | PASS | Deps, callers, complexity, children |
-| `where buildGraph` | PASS | Found in src/builder.js |
-| `fn-impact buildGraph -T` | PASS | Transitive dependents |
-| `diff-impact main -T` | PASS | Changed functions with callers |
-| `diff-impact --staged -T` | PASS | No changes detected |
-| `cycles` | PASS | File-level and function-level cycles |
-| `structure -T --depth 2` | PASS | Directory tree with cohesion |
-| `structure . -T --depth 1` | PASS | Fixed since v2.2.0 |
-| `cfg buildGraph -T` | PASS | 204 blocks, 268 edges |
-| `cfg buildGraph --format mermaid` | PASS | Valid Mermaid |
-| `cfg buildGraph --format dot` | PASS | Valid DOT |
-| `complexity -T` | PASS | Functions analyzed |
-| `dataflow buildGraph -T` | PASS | Return consumers, data sources |
-| `sequence buildGraph -T` | PASS | Mermaid sequence diagram |
-| `sequence buildGraph -T --dataflow` | PASS | Parameter annotations |
-| `sequence buildGraph -T -j` | PASS | Valid JSON |
-| `ast "require*"` | PASS | AST nodes found |
-| `co-change --analyze` | PASS | Pairs from commits |
-| `branch-compare main HEAD -T` | PASS | Added/removed/changed |
-| `batch fn-impact buildGraph,openDb -T` | PASS | 2/2 succeeded |
-| `export -f dot` | PASS | DOT output |
-| `export -f mermaid` | PASS | Mermaid output |
-| `export -f json` | PASS | JSON output |
-| `models` | PASS | Lists embedding models |
-| `registry list --json` | PASS | 14 registered repos |
-| `registry add/remove` | PASS | Add and remove work correctly |
-| `registry prune --ttl 365` | PASS | "No stale entries found" |
-
-### Edge Cases Tested
-
-| Scenario | Result |
-|----------|--------|
-| Non-existent symbol: `query nonexistent_xyz` | PASS — "No function/method/class matching" |
-| Non-existent file: `deps nonexistent_file.js` | PASS — "No file matching" |
-| `structure .` (v2.2.0 regression) | PASS — fixed |
-| `--json` pipe cleanness (`map --json`) | PASS — valid JSON, no status messages in stdout |
-| `--no-tests` filter | PASS — 3417 nodes (vs 4192 unfiltered) |
-
----
-
-## 4. Rebuild & Staleness
-
-| Test | Result |
-|------|--------|
-| Incremental no-op | PASS — "Graph is up to date", 8ms (native), 8ms (WASM) |
-| Incremental 1-file change | PASS — only changed file + 26 reverse-deps re-parsed |
-| Full rebuild `--no-incremental` | PASS — 4192 nodes, 9057 edges (native); 4196 nodes, 9234 edges (WASM) |
-| Node/edge consistency | PASS — counts stable across incremental/full |
-
----
-
-## 5. Engine Comparison
-
-| Metric | Native | WASM | Delta |
-|--------|--------|------|-------|
-| Nodes | 4192 | 4196 | +4 |
-| Edges | 9057 | 9234 | +177 |
-| Constants | 235 | 199 | -36 |
-| Parameters | 2158 | 2198 | +40 |
-| Calls | 2129 | 2163 | +34 |
-| Dynamic imports | 0 | 99 | +99 (BUG #410) |
-| Complexity | 1193 functions | 1192 post-fix (BUG #413) | -1 (see parity gap #5) |
-| Quality score | 88 | 88 | 0 |
-| Full build time | 1335ms | 2500ms | Native 1.87x faster |
-| No-op rebuild | 8ms | 8ms | Parity |
-| 1-file rebuild | 766ms | 959ms | Native 1.25x faster |
-| Unused exports warned | 43 | 25 | +18 (due to missing dynamic-imports) |
-
-### Parity Gaps
-
-1. **Dynamic imports (#410):** Native engine does not track `import()` expressions, resulting in 0 dynamic-imports edges vs WASM's 99. This inflates native's unused export warnings (43 vs 25).
-2. **Constants:** Native extracts 36 more constants than WASM — likely better coverage of top-level const declarations.
-3. **Parameters:** WASM extracts 40 more parameters than native.
-4. **WASM complexity failure (#413):** WASM builds produce 0 complexity rows due to a `ReferenceError: findFunctionNode is not defined` in `src/complexity.js:457`. The import aliases the function as `_findFunctionNode` but the callsite uses the bare name. Native builds skip this code path because complexity is pre-computed in Rust. **Fix in PR #414** — one-line change, 120 tests pass.
-5. **Residual complexity gap (1192 vs 1193):** After the #413 fix, WASM produces 1192 complexity rows vs native's 1193. The missing function is `SymbolExtractor.extract` — a Rust `impl` method at `crates/codegraph-core/src/extractors/mod.rs:18`. The WASM parser's `_findFunctionNode` cannot locate the AST node for Rust `impl` method blocks, so the JS complexity fallback silently skips it. This is a minor WASM parser limitation, not a regression.
-
----
-
-## 6. Performance Benchmarks
-
-### Build Benchmark (`scripts/benchmark.js`)
-
-**Status: PARTIAL — WASM engine segfaulted (exit 139) during 3rd 1-file rebuild iteration. Bug #408/#409 filed.**
-
-Results collected from `incremental-benchmark.js` which completed successfully:
-
-| Metric | Native | WASM |
-|--------|--------|------|
-| Full build (ms) | 1335 | 2500 |
-| Full build (ms/file) | 5.7 | 10.6 |
-| No-op rebuild (ms) | 8 | 8 |
-| 1-file rebuild (ms) | 766 | 959 |
-
-### 1-File Rebuild Phase Breakdown
-
-| Phase | Native (ms) | WASM (ms) |
-|-------|-------------|-----------|
-| **Setup** | — | — |
-| **Parse** | 37.3 | 125.3 |
-| **Insert** | 8.2 | 8.2 |
-| **Resolve** | 1.0 | 2.3 |
-| **Edges** | 12.0 | 63.0 |
-| **Structure** | 10.4 | 8.8 |
-| **Roles** | 13.4 | 13.3 |
-| **AST** | 263.1 | 278.7 |
-| **Complexity** | 23.7 | 0.4 |
-| **CFG** | 4.0 | 24.8 |
-| **Dataflow** | 3.7 | 4.4 |
-| **Finalize** | — | — |
-
-> **Note:** The pre-existing benchmark data above was collected before `setupMs` and `finalizeMs` were added to `buildGraph`. A fresh full-build run with the fix shows: setupMs=29.6, finalizeMs=180.3 — these two phases account for the ~45-51% gap between the old phase sums and reported totals. Setup covers DB open/init, config, file discovery, and change detection. Finalize covers count queries, drift checks, orphan/unused-export warnings, metadata writes, DB close, journal, and registry.
-
-**Notes:** Native is 3.4x faster at parsing, 5.3x faster at edge building, 6.2x faster at CFG. AST phase dominates both engines (~263-279ms). WASM complexity shows 0.4ms because the computation silently fails (BUG #413) — it should be ~24ms when fixed.
-
-### Query Benchmark (`scripts/query-benchmark.js`)
-
-| Metric | Native | WASM |
-|--------|--------|------|
-| fn-deps depth 1 (ms) | 0.8 | 0.7 |
-| fn-deps depth 3 (ms) | 0.7 | 0.7 |
-| fn-deps depth 5 (ms) | 0.7 | 0.6 |
-| fn-impact depth 1 (ms) | 0.7 | 0.6 |
-| fn-impact depth 3 (ms) | 0.7 | 0.7 |
-| fn-impact depth 5 (ms) | 0.7 | 0.6 |
-| diff-impact (ms) | 15.4 | 16.6 |
-
-**Notes:** Query latency is sub-millisecond for all depth levels — no regressions. Parity between engines.
-
-### Import Resolution Benchmark
-
-| Metric | Result |
-|--------|--------|
-| Import pairs | 218 |
-| Native batch (ms) | 2.6 |
-| JS fallback (ms) | 6.2 |
-| Speedup | 2.4x |
-
-### Embedding Benchmark (`scripts/embedding-benchmark.js`)
-
-**Status: PARTIAL — crashed on nomic-v1.5 model (illegal instruction, exit 132). Bug #408 filed.**
-
-| Model | Hit@1 | Hit@3 | Hit@5 | Misses |
-|-------|-------|-------|-------|--------|
-| minilm | 673/888 (75.8%) | 839/888 (94.5%) | 866/888 (97.5%) | 10 |
-| jina-small | 688/888 (77.5%) | 851/888 (95.8%) | 869/888 (97.9%) | 10 |
-| jina-base | 657/888 (74.0%) | 822/888 (92.6%) | 848/888 (95.5%) | 14 |
-| nomic | 726/888 (81.8%) | 870/888 (98.0%) | 880/888 (99.1%) | 1 |
-| nomic-v1.5 | CRASHED | — | — | — |
-| jina-code | SKIPPED (no HF_TOKEN) | — | — | — |
-
-**Best model:** nomic (Hit@5 = 99.1%, only 1 miss). Consistent with previous releases.
-
----
-
-## 7. Release-Specific Tests (v3.1.2)
-
-Based on the [v3.1.2 release notes](https://github.com/optave/codegraph/releases/tag/v3.1.2):
-
-| Feature/Fix | Test | Result |
-|-------------|------|--------|
-| Unified AST analysis framework (Phase 3.1) | `complexity`, `cfg`, `dataflow` all produce results from single DFS pass | PASS |
-| CFG visitor rewrite — node-level DFS | `cfg buildGraph` returns 204 blocks, 268 edges | PASS |
-| CLI command/query separation (Phase 3.2) | All commands work, `--json` output clean | PASS |
-| Dynamic `import()` tracking as graph edges | WASM: 99 dynamic-imports edges | PASS (WASM) |
-| Dynamic `import()` tracking — native engine | Native: 0 dynamic-imports edges | **FAIL** — #410 |
-| Repository pattern migration (Phase 3.3) | `stats`, `map`, queries all work | PASS |
-| Prepared statement caching | Build and queries succeed, no perf regressions | PASS |
-| Fix: check-dead-exports hook on ESM (#394) | Dead export detection works on codegraph (ESM codebase) | PASS |
-| Fix: remove function nesting inflation | Complexity metrics reasonable (avg cognitive ~17) | PASS |
-| Fix: Halstead skip depth counter | No crashes or NaN in complexity output | PASS |
-| Fix: nested function nesting | CFG handles nested functions | PASS |
-
----
-
-## 8. Additional Testing
-
-### MCP Server
-
-| Test | Result |
-|------|--------|
-| Single-repo mode (default) | PASS — 31 tools, `list_repos` absent, no `repo` param |
-| Multi-repo mode (`--multi-repo`) | PASS — 32 tools, `list_repos` present |
-| JSON-RPC `initialize` + `tools/list` | PASS — valid responses |
-
-### Programmatic API
-
-All 15 key exports verified via ESM import:
-
-| Export | Type | Status |
-|--------|------|--------|
-| `buildGraph` | function | PASS |
-| `loadConfig` | function | PASS |
-| `openDb` | function | PASS |
-| `findDbPath` | function | PASS |
-| `contextData` | function | PASS |
-| `explainData` | function | PASS |
-| `whereData` | function | PASS |
-| `fnDepsData` | function | PASS |
-| `diffImpactData` | function | PASS |
-| `statsData` | function | PASS |
-| `isNativeAvailable` | function | PASS |
-| `EXTENSIONS` | object | PASS |
-| `IGNORE_DIRS` | object | PASS |
-| `ALL_SYMBOL_KINDS` | array(10) | PASS |
-| `MODELS` | object | PASS |
-
-**Note:** CJS `require()` fails with `ERR_PACKAGE_PATH_NOT_EXPORTED` — expected, package is ESM-only.
-
-### Registry Operations
-
-| Operation | Result |
-|-----------|--------|
-| `registry list --json` | PASS — 14 repos listed |
-| `registry add /tmp/... --name test-dogfood` | PASS |
-| `registry remove test-dogfood` | PASS |
-| `registry prune --ttl 365` | PASS — "No stale entries found" |
-
-### Config
-
-| Test | Result |
-|------|--------|
-| `.codegraphrc.json` loaded | PASS — `build --verbose` shows "Loaded config" |
-
----
-
-## 9. Bugs Found
-
-### BUG 1: Benchmark scripts crash entirely when one engine/model fails (Medium)
-- **Issue:** [#408](https://github.com/optave/codegraph/issues/408)
-- **Symptoms:** Build benchmark segfaults during WASM 1-file rebuild; embedding benchmark crashes on nomic-v1.5. In both cases, all partial results are lost.
-- **Root cause:** No try/catch isolation per engine or per model in benchmark scripts. Segfaults can't even be caught by try/catch.
-- **Fix:** Wrap each engine/model run in try/catch. Consider running each in a child process (`fork()`) to isolate segfaults.
-
-### BUG 2: WASM engine segfaults after repeated builds in same process (Low)
-- **Issue:** [#409](https://github.com/optave/codegraph/issues/409)
-- **Symptoms:** After 6+ WASM builds in the same Node.js process, the 3rd 1-file rebuild segfaults (exit 139). The incremental benchmark survives the same pattern.
-- **Root cause:** Likely tree-sitter WASM memory accumulation. The build benchmark runs more operations before reaching the crash point.
-- **Fix:** Investigate tree-sitter WASM parser disposal between builds. Consider `parser.delete()` cleanup.
-
-### BUG 3: Native engine does not track dynamic import() expressions (Medium)
-- **Issue:** [#410](https://github.com/optave/codegraph/issues/410)
-- **Symptoms:** WASM produces 99 dynamic-imports edges; native produces 0. Native reports 43 unused exports (vs WASM's 25) due to missing dynamic-import consumption tracking.
-- **Root cause:** The v3.1.2 dynamic import feature (#389) was implemented in JS/WASM only. The Rust native engine's edge builder doesn't detect `import()` expressions.
-- **Fix:** Add dynamic import detection to `edge_builder.rs`.
-
-### BUG 4: info command reports stale native engine version (Low)
-- **Issue:** [#411](https://github.com/optave/codegraph/issues/411)
-- **Symptoms:** `codegraph info` reports `Native version: 3.1.0` when the actual binary is v3.1.2.
-- **Root cause:** Version string in the Rust binary (`Cargo.toml` or constant) was not bumped for 3.1.2 release.
-- **Fix:** Ensure publish workflow bumps the Rust binary version to match npm version.
-
-### BUG 5: WASM complexity fails — findFunctionNode is not defined (High)
-- **Issue:** [#413](https://github.com/optave/codegraph/issues/413)
-- **PR:** Fixed in [#414](https://github.com/optave/codegraph/pull/414) — one-line fix in `src/complexity.js:457`
-- **Symptoms:** WASM builds produce 0 complexity rows. `--verbose` shows: `buildComplexityMetrics failed: findFunctionNode is not defined`. The `complexity` command reports "No complexity data found" after a WASM build.
-- **Root cause:** `src/complexity.js` line 9 imports `findFunctionNode as _findFunctionNode`, but line 457 calls the bare `findFunctionNode` which is only a re-export name, not a local binding. Native builds never hit this path because `def.complexity` is pre-computed in Rust (line 425).
-- **Fix applied:** Changed `findFunctionNode(...)` to `_findFunctionNode(...)` at line 457. Verified: WASM now produces 1192 complexity rows (vs native's 1193). The 1-function gap is `SymbolExtractor.extract` (Rust `impl` method at `crates/codegraph-core/src/extractors/mod.rs:18`) — the WASM parser's `_findFunctionNode` can't locate the AST node for Rust `impl` method blocks. See parity gap #5. 120 tests pass (94 unit + 26 integration).
-
----
-
-## 10. Suggestions for Improvement
-
-### 10.1 Child-process isolation for benchmarks
-Run each engine/model benchmark in a subprocess to survive segfaults and collect partial results.
-
-### 10.2 Native dynamic import parity
-Prioritize implementing dynamic import tracking in the Rust engine to close the 177-edge parity gap and reduce false-positive unused export warnings.
-
-### 10.3 WASM memory management
-Investigate tree-sitter WASM parser disposal. Multiple builds in the same process should not accumulate memory to the point of segfaulting.
-
-### 10.4 Automated version consistency checks
-Add a CI check that verifies `Cargo.toml` version matches `package.json` version before publishing, to prevent stale native version display.
-
-### 10.5 AST phase optimization
-The AST phase (~265ms) dominates 1-file rebuilds for both engines. Profiling this phase could yield significant build speed improvements.
-
----
-
-## 11. Testing Plan
-
-### General Testing Plan (Any Release)
-
-- [ ] Install from npm, verify `--version` and `info`
-- [ ] Native binary version matches npm package version
-- [ ] Cold start: all commands handle missing graph gracefully
-- [ ] Full build + incremental no-op + 1-file rebuild
-- [ ] Engine comparison: native vs WASM node/edge parity
-- [ ] All commands produce valid `--json` output
-- [ ] Edge cases: non-existent symbols, files, invalid kinds
-- [ ] MCP: single-repo and multi-repo tool counts
-- [ ] Programmatic API: all documented exports work
-- [ ] Registry: add, remove, list, prune
-- [ ] Benchmarks: build, query, incremental, embedding
-- [ ] Embedding recall: Hit@5 > 95% for minilm and nomic
-
-### Release-Specific Testing Plan (v3.1.2)
-
-- [ ] Unified AST analysis: complexity, CFG, dataflow from single pass
-- [ ] CFG visitor rewrite: correct block/edge counts
-- [ ] Dynamic imports: WASM tracks `import()` as edges
-- [ ] Command/query separation: all commands work after refactor
-- [ ] Repository pattern: queries work through new data access layer
-- [ ] Prepared statement caching: no perf regressions
-- [ ] Dead export detection: works on ESM codebases
-
-### Proposed Additional Tests
-
-- [ ] Embed → rebuild → search pipeline (stale embedding detection)
-- [ ] Watch mode: start, detect change, query, graceful shutdown
-- [ ] Concurrent builds (two processes)
-- [ ] `apiKeyCommand` credential resolution
-- [ ] Database migration path (v1→v14 schema)
-- [ ] Test on a non-JavaScript repo (Go or Rust project)
-
----
-
-## 12. Overall Assessment
-
-v3.1.2 is a solid architectural release. The Phase 3 refactoring (unified AST analysis, command/query separation, repository pattern) is well-executed — all commands work correctly through the new layers with no regressions from the restructuring. Build performance is good (5.7 ms/file native, 10.6 ms/file WASM) with sub-millisecond query latency.
-
-The main gaps are engine parity: the native engine doesn't track dynamic imports (inflating unused export warnings), and the WASM engine had completely broken complexity metrics due to a variable naming bug (#413, fixed in PR #414). The benchmark resilience issues are low-impact but should be fixed to prevent data loss during future dogfooding. The stale native version display is cosmetic but signals a publish workflow gap.
-
-**Rating: 7/10**
-
-- (+) Clean architecture refactoring with no functional regressions
-- (+) Strong query performance (sub-ms at all depths)
-- (+) MCP server works in both modes (31/32 tools)
-- (+) Programmatic API exports all verified
-- (+) nomic embedding recall at 99.1% Hit@5
-- (-) WASM complexity completely broken since unified AST refactor — zero rows produced (#413, fixed in PR #414)
-- (-) Native engine missing dynamic imports (177 edge gap, #410)
-- (-) Benchmark segfaults lose partial results (#408/#409)
-- (-) Native version display stale (#411)
-
----
-
-## 13. Issues & PRs Created
-
-| Type | Number | Title | Status |
-|------|--------|-------|--------|
-| Issue | [#408](https://github.com/optave/codegraph/issues/408) | bug: benchmark scripts crash entirely when one engine/model fails | open |
-| Issue | [#409](https://github.com/optave/codegraph/issues/409) | bug: WASM engine segfaults after repeated builds in same process | open |
-| Issue | [#410](https://github.com/optave/codegraph/issues/410) | bug: native engine does not track dynamic import() expressions | open |
-| Issue | [#411](https://github.com/optave/codegraph/issues/411) | bug: info command reports stale native engine version (3.1.0 instead of 3.1.2) | open |
-| Issue | [#413](https://github.com/optave/codegraph/issues/413) | bug: WASM complexity fails — findFunctionNode is not defined | fixed in PR #414 |
diff --git a/package-lock.json b/package-lock.json
index e03070d2..dbc3c1e4 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1276,9 +1276,6 @@
       "cpu": [
         "arm64"
       ],
-      "libc": [
-        "glibc"
-      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1292,9 +1289,6 @@
       "cpu": [
         "x64"
       ],
-      "libc": [
-        "glibc"
-      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1308,9 +1302,6 @@
       "cpu": [
         "x64"
       ],
-      "libc": [
-        "musl"
-      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
diff --git a/scripts/benchmark.js b/scripts/benchmark.js
index 7b8c0c05..c2651443 100644
--- a/scripts/benchmark.js
+++ b/scripts/benchmark.js
@@ -3,8 +3,9 @@
 /**
  * Benchmark runner — measures codegraph performance on itself (dogfooding).
  *
- * Runs both native (Rust) and WASM engines, outputs JSON to stdout
- * with raw and per-file normalized metrics for each.
+ * Each engine (native / WASM) runs in a forked subprocess so that a segfault
+ * in the native addon only kills the child — the parent survives and collects
+ * partial results from whichever engines succeeded.
  *
  * Usage: node scripts/benchmark.js
  */
@@ -15,25 +16,73 @@ import { performance } from 'node:perf_hooks';
 import { fileURLToPath } from 'node:url';
 import Database from 'better-sqlite3';
 import { resolveBenchmarkSource, srcImport } from './lib/bench-config.js';
+import { isWorker, workerEngine, forkEngines } from './lib/fork-engine.js';
+
+// ── Parent process: fork one child per engine, assemble final output ─────
+if (!isWorker()) {
+	const { version } = await resolveBenchmarkSource();
+	const { wasm, native } = await forkEngines(import.meta.url, process.argv.slice(2));
+
+	const primary = wasm || native;
+	if (!primary) {
+		console.error('Error: Both engines failed. No results to report.');
+		process.exit(1);
+	}
+
+	const result = {
+		version,
+		date: new Date().toISOString().slice(0, 10),
+		files: primary.files,
+		wasm: wasm
+			? {
+					buildTimeMs: wasm.buildTimeMs,
+					queryTimeMs: wasm.queryTimeMs,
+					nodes: wasm.nodes,
+					edges: wasm.edges,
+					dbSizeBytes: wasm.dbSizeBytes,
+					perFile: wasm.perFile,
+					noopRebuildMs: wasm.noopRebuildMs,
+					oneFileRebuildMs: wasm.oneFileRebuildMs,
+					oneFilePhases: wasm.oneFilePhases,
+					queries: wasm.queries,
+					phases: wasm.phases,
+				}
+			: null,
+		native: native
+			? {
+					buildTimeMs: native.buildTimeMs,
+					queryTimeMs: native.queryTimeMs,
+					nodes: native.nodes,
+					edges: native.edges,
+					dbSizeBytes: native.dbSizeBytes,
+					perFile: native.perFile,
+					noopRebuildMs: native.noopRebuildMs,
+					oneFileRebuildMs: native.oneFileRebuildMs,
+					oneFilePhases: native.oneFilePhases,
+					queries: native.queries,
+					phases: native.phases,
+				}
+			: null,
+	};
+
+	console.log(JSON.stringify(result, null, 2));
+	process.exit(0);
+}
+
+// ── Worker process: benchmark a single engine, write JSON to stdout ──────
+const engine = workerEngine();
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(__dirname, '..');
 
-const { version, srcDir, cleanup } = await resolveBenchmarkSource();
+const { srcDir, cleanup } = await resolveBenchmarkSource();
 
 const dbPath = path.join(root, '.codegraph', 'graph.db');
 
-// Import programmatic API (use file:// URLs for Windows compatibility)
 const { buildGraph } = await import(srcImport(srcDir, 'builder.js'));
 const { fnDepsData, fnImpactData, pathData, rolesData, statsData } = await import(
 	srcImport(srcDir, 'queries.js')
 );
-const { isNativeAvailable } = await import(
-	srcImport(srcDir, 'native.js')
-);
-const { isWasmAvailable } = await import(
-	srcImport(srcDir, 'parser.js')
-);
 
 const INCREMENTAL_RUNS = 3;
 const QUERY_RUNS = 5;
@@ -49,9 +98,6 @@ function round1(n) {
 	return Math.round(n * 10) / 10;
 }
 
-/**
- * Pick hub (most-connected) and leaf (least-connected) non-test symbols from the DB.
- */
 function selectTargets() {
 	const db = new Database(dbPath, { readonly: true });
 	const rows = db
@@ -67,7 +113,6 @@ function selectTargets() {
 	db.close();
 
 	if (rows.length === 0) return { hub: 'buildGraph', leaf: 'median' };
-
 	return { hub: rows[0].name, leaf: rows[rows.length - 1].name };
 }
 
@@ -75,175 +120,99 @@ function selectTargets() {
 const origLog = console.log;
 console.log = (...args) => console.error(...args);
 
-async function benchmarkEngine(engine) {
-	// Clean DB for a full build
-	if (fs.existsSync(dbPath)) fs.unlinkSync(dbPath);
-
-	const buildStart = performance.now();
-	const buildResult = await buildGraph(root, { engine, incremental: false });
-	const buildTimeMs = performance.now() - buildStart;
-
-	const queryStart = performance.now();
-	fnDepsData('buildGraph', dbPath);
-	const queryTimeMs = performance.now() - queryStart;
-
-	const stats = statsData(dbPath);
-	const totalFiles = stats.files.total;
-	const totalNodes = stats.nodes.total;
-	const totalEdges = stats.edges.total;
-	const dbSizeBytes = fs.statSync(dbPath).size;
-
-	// ── Incremental build tiers (reuse existing DB from full build) ─────
-	console.error(`  [${engine}] Benchmarking no-op rebuild...`);
-	const noopTimings = [];
+// Clean DB for a full build
+if (fs.existsSync(dbPath)) fs.unlinkSync(dbPath);
+
+const buildStart = performance.now();
+const buildResult = await buildGraph(root, { engine, incremental: false });
+const buildTimeMs = performance.now() - buildStart;
+
+const queryStart = performance.now();
+fnDepsData('buildGraph', dbPath);
+const queryTimeMs = performance.now() - queryStart;
+
+const stats = statsData(dbPath);
+const totalFiles = stats.files.total;
+const totalNodes = stats.nodes.total;
+const totalEdges = stats.edges.total;
+const dbSizeBytes = fs.statSync(dbPath).size;
+
+// ── Incremental build tiers ─────────────────────────────────────────
+console.error(`  [${engine}] Benchmarking no-op rebuild...`);
+const noopTimings = [];
+for (let i = 0; i < INCREMENTAL_RUNS; i++) {
+	const start = performance.now();
+	await buildGraph(root, { engine, incremental: true });
+	noopTimings.push(performance.now() - start);
+}
+const noopRebuildMs = Math.round(median(noopTimings));
+
+console.error(`  [${engine}] Benchmarking 1-file rebuild...`);
+const original = fs.readFileSync(PROBE_FILE, 'utf8');
+let oneFileRebuildMs;
+let oneFilePhases = null;
+try {
+	const oneFileRuns = [];
 	for (let i = 0; i < INCREMENTAL_RUNS; i++) {
+		fs.writeFileSync(PROBE_FILE, original + `\n// probe-${i}\n`);
 		const start = performance.now();
-		await buildGraph(root, { engine, incremental: true });
-		noopTimings.push(performance.now() - start);
-	}
-	const noopRebuildMs = Math.round(median(noopTimings));
-
-	console.error(`  [${engine}] Benchmarking 1-file rebuild...`);
-	const original = fs.readFileSync(PROBE_FILE, 'utf8');
-	let oneFileRebuildMs;
-	let oneFilePhases = null;
-	try {
-		const oneFileRuns = [];
-		for (let i = 0; i < INCREMENTAL_RUNS; i++) {
-			fs.writeFileSync(PROBE_FILE, original + `\n// probe-${i}\n`);
-			const start = performance.now();
-			const res = await buildGraph(root, { engine, incremental: true });
-			oneFileRuns.push({ ms: performance.now() - start, phases: res?.phases || null });
-		}
-		oneFileRuns.sort((a, b) => a.ms - b.ms);
-		const medianRun = oneFileRuns[Math.floor(oneFileRuns.length / 2)];
-		oneFileRebuildMs = Math.round(medianRun.ms);
-		oneFilePhases = medianRun.phases;
-	} finally {
-		fs.writeFileSync(PROBE_FILE, original);
-		await buildGraph(root, { engine, incremental: true });
-	}
-
-	// ── Query benchmarks (median of QUERY_RUNS each) ────────────────────
-	console.error(`  [${engine}] Benchmarking queries...`);
-	const targets = selectTargets();
-	console.error(`    hub=${targets.hub}, leaf=${targets.leaf}`);
-
-	function benchQuery(fn, ...args) {
-		const timings = [];
-		for (let i = 0; i < QUERY_RUNS; i++) {
-			const start = performance.now();
-			fn(...args);
-			timings.push(performance.now() - start);
-		}
-		return round1(median(timings));
+		const res = await buildGraph(root, { engine, incremental: true });
+		oneFileRuns.push({ ms: performance.now() - start, phases: res?.phases || null });
 	}
-
-	const queries = {
-		fnDepsMs: fnDepsData ? benchQuery(fnDepsData, targets.hub, dbPath, { depth: 3, noTests: true }) : null,
-		fnImpactMs: fnImpactData ? benchQuery(fnImpactData, targets.hub, dbPath, { depth: 3, noTests: true }) : null,
-		pathMs: pathData ? benchQuery(pathData, targets.hub, targets.leaf, dbPath, { noTests: true }) : null,
-		rolesMs: rolesData ? benchQuery(rolesData, dbPath, { noTests: true }) : null,
-	};
-
-	return {
-		buildTimeMs: Math.round(buildTimeMs),
-		queryTimeMs: Math.round(queryTimeMs * 10) / 10,
-		nodes: totalNodes,
-		edges: totalEdges,
-		files: totalFiles,
-		dbSizeBytes,
-		perFile: {
-			buildTimeMs: Math.round((buildTimeMs / totalFiles) * 10) / 10,
-			nodes: Math.round((totalNodes / totalFiles) * 10) / 10,
-			edges: Math.round((totalEdges / totalFiles) * 10) / 10,
-			dbSizeBytes: Math.round(dbSizeBytes / totalFiles),
-		},
-		noopRebuildMs,
-		oneFileRebuildMs,
-		oneFilePhases,
-		queries,
-		phases: buildResult?.phases || null,
-	};
+	oneFileRuns.sort((a, b) => a.ms - b.ms);
+	const medianRun = oneFileRuns[Math.floor(oneFileRuns.length / 2)];
+	oneFileRebuildMs = Math.round(medianRun.ms);
+	oneFilePhases = medianRun.phases;
+} finally {
+	fs.writeFileSync(PROBE_FILE, original);
+	await buildGraph(root, { engine, incremental: true });
 }
 
-// ── Run benchmarks ───────────────────────────────────────────────────────
-const hasWasm = isWasmAvailable();
-const hasNative = isNativeAvailable();
-
-if (!hasWasm && !hasNative) {
-	console.error('Error: Neither WASM grammars nor native engine are available.');
-	console.error('Run "npm run build:wasm" to build WASM grammars, or install the native platform package.');
-	process.exit(1);
-}
+// ── Query benchmarks ────────────────────────────────────────────────
+console.error(`  [${engine}] Benchmarking queries...`);
+const targets = selectTargets();
+console.error(`    hub=${targets.hub}, leaf=${targets.leaf}`);
 
-let wasm = null;
-if (hasWasm) {
-	try {
-		wasm = await benchmarkEngine('wasm');
-	} catch (err) {
-		console.error(`WASM benchmark failed: ${err?.message ?? String(err)}`);
+function benchQuery(fn, ...args) {
+	const timings = [];
+	for (let i = 0; i < QUERY_RUNS; i++) {
+		const start = performance.now();
+		fn(...args);
+		timings.push(performance.now() - start);
 	}
-} else {
-	console.error('WASM grammars not built — skipping WASM benchmark');
+	return round1(median(timings));
 }
 
-let native = null;
-if (hasNative) {
-	try {
-		native = await benchmarkEngine('native');
-	} catch (err) {
-		console.error(`Native benchmark failed: ${err?.message ?? String(err)}`);
-	}
-} else {
-	console.error('Native engine not available — skipping native benchmark');
-}
+const queries = {
+	fnDepsMs: fnDepsData ? benchQuery(fnDepsData, targets.hub, dbPath, { depth: 3, noTests: true }) : null,
+	fnImpactMs: fnImpactData ? benchQuery(fnImpactData, targets.hub, dbPath, { depth: 3, noTests: true }) : null,
+	pathMs: pathData ? benchQuery(pathData, targets.hub, targets.leaf, dbPath, { noTests: true }) : null,
+	rolesMs: rolesData ? benchQuery(rolesData, dbPath, { noTests: true }) : null,
+};
 
 // Restore console.log for JSON output
 console.log = origLog;
 
-const primary = wasm || native;
-if (!primary) {
-	console.error('Error: Both engines failed. No results to report.');
-	cleanup();
-	process.exit(1);
-}
-const result = {
-	version,
-	date: new Date().toISOString().slice(0, 10),
-	files: primary.files,
-	wasm: wasm
-		? {
-				buildTimeMs: wasm.buildTimeMs,
-				queryTimeMs: wasm.queryTimeMs,
-				nodes: wasm.nodes,
-				edges: wasm.edges,
-				dbSizeBytes: wasm.dbSizeBytes,
-				perFile: wasm.perFile,
-				noopRebuildMs: wasm.noopRebuildMs,
-				oneFileRebuildMs: wasm.oneFileRebuildMs,
-				oneFilePhases: wasm.oneFilePhases,
-				queries: wasm.queries,
-				phases: wasm.phases,
-			}
-		: null,
-	native: native
-		? {
-				buildTimeMs: native.buildTimeMs,
-				queryTimeMs: native.queryTimeMs,
-				nodes: native.nodes,
-				edges: native.edges,
-				dbSizeBytes: native.dbSizeBytes,
-				perFile: native.perFile,
-				noopRebuildMs: native.noopRebuildMs,
-				oneFileRebuildMs: native.oneFileRebuildMs,
-				oneFilePhases: native.oneFilePhases,
-				queries: native.queries,
-				phases: native.phases,
-			}
-		: null,
+const workerResult = {
+	buildTimeMs: Math.round(buildTimeMs),
+	queryTimeMs: Math.round(queryTimeMs * 10) / 10,
+	nodes: totalNodes,
+	edges: totalEdges,
+	files: totalFiles,
+	dbSizeBytes,
+	perFile: {
+		buildTimeMs: Math.round((buildTimeMs / totalFiles) * 10) / 10,
+		nodes: Math.round((totalNodes / totalFiles) * 10) / 10,
+		edges: Math.round((totalEdges / totalFiles) * 10) / 10,
+		dbSizeBytes: Math.round(dbSizeBytes / totalFiles),
+	},
+	noopRebuildMs,
+	oneFileRebuildMs,
+	oneFilePhases,
+	queries,
+	phases: buildResult?.phases || null,
 };
 
-console.log(JSON.stringify(result, null, 2));
+console.log(JSON.stringify(workerResult));
 
 cleanup();
diff --git a/scripts/embedding-benchmark.js b/scripts/embedding-benchmark.js
index 4bc3afec..35344011 100644
--- a/scripts/embedding-benchmark.js
+++ b/scripts/embedding-benchmark.js
@@ -3,70 +3,76 @@
 /**
  * Embedding benchmark runner — measures search recall across all models.
  *
- * For every function/method/class in the graph, generates a query from the
- * symbol name (splitIdentifier) and checks if search finds that symbol.
- * Tests all available embedding models, outputs JSON to stdout.
- *
- * Skips jina-code when HF_TOKEN is not set (gated model).
+ * Each model runs in a forked subprocess so that a crash (OOM, WASM segfault
+ * in the ONNX runtime) only kills the child — the parent survives and collects
+ * partial results from whichever models succeeded.
  *
  * Usage: node scripts/embedding-benchmark.js > result.json
  */
 
-import fs from 'node:fs';
+import { fork } from 'node:child_process';
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { fileURLToPath } from 'node:url';
 import Database from 'better-sqlite3';
 import { resolveBenchmarkSource, srcImport } from './lib/bench-config.js';
 
+const MODEL_WORKER_KEY = '__BENCH_MODEL__';
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(__dirname, '..');
 
-const { version, srcDir, cleanup } = await resolveBenchmarkSource();
-const dbPath = path.join(root, '.codegraph', 'graph.db');
+// ── Worker process: benchmark a single model, write JSON to stdout ───────
+if (process.env[MODEL_WORKER_KEY]) {
+	const modelKey = process.env[MODEL_WORKER_KEY];
 
-const { buildEmbeddings, MODELS, searchData, disposeModel } = await import(
-	srcImport(srcDir, 'embeddings/index.js')
-);
+	const { srcDir, cleanup } = await resolveBenchmarkSource();
+	const dbPath = path.join(root, '.codegraph', 'graph.db');
 
-// Redirect console.log to stderr so only JSON goes to stdout
-const origLog = console.log;
-console.log = (...args) => console.error(...args);
+	const { buildEmbeddings, MODELS, searchData, disposeModel } = await import(
+		srcImport(srcDir, 'embeddings/index.js')
+	);
 
-const TEST_PATTERN = /\.(test|spec)\.|__test__|__tests__|\.stories\./;
+	const TEST_PATTERN = /\.(test|spec)\.|__test__|__tests__|\.stories\./;
 
-function splitIdentifier(name) {
-	return name
-		.replace(/([a-z])([A-Z])/g, '$1 $2')
-		.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
-		.replace(/[_-]+/g, ' ')
-		.trim();
-}
+	function splitIdentifier(name) {
+		return name
+			.replace(/([a-z])([A-Z])/g, '$1 $2')
+			.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+			.replace(/[_-]+/g, ' ')
+			.trim();
+	}
 
-function loadSymbols() {
-	const db = new Database(dbPath, { readonly: true });
-	let rows = db
-		.prepare(
-			`SELECT name, kind, file FROM nodes WHERE kind IN ('function', 'method', 'class') ORDER BY file, line`,
-		)
-		.all();
-	db.close();
-
-	rows = rows.filter((r) => !TEST_PATTERN.test(r.file));
-
-	const seen = new Set();
-	const symbols = [];
-	for (const row of rows) {
-		if (seen.has(row.name)) continue;
-		seen.add(row.name);
-		const query = splitIdentifier(row.name);
-		if (query.length < 4) continue;
-		symbols.push({ name: row.name, kind: row.kind, file: row.file, query });
+	function loadSymbols() {
+		const db = new Database(dbPath, { readonly: true });
+		let rows = db
+			.prepare(
+				`SELECT name, kind, file FROM nodes WHERE kind IN ('function', 'method', 'class') ORDER BY file, line`,
+			)
+			.all();
+		db.close();
+
+		rows = rows.filter((r) => !TEST_PATTERN.test(r.file));
+
+		const seen = new Set();
+		const symbols = [];
+		for (const row of rows) {
+			if (seen.has(row.name)) continue;
+			seen.add(row.name);
+			const query = splitIdentifier(row.name);
+			if (query.length < 4) continue;
+			symbols.push({ name: row.name, kind: row.kind, file: row.file, query });
+		}
+		return symbols;
 	}
-	return symbols;
-}
 
-async function benchmarkModel(modelKey, symbols) {
+	// Redirect console.log to stderr so only JSON goes to stdout
+	const origLog = console.log;
+	console.log = (...args) => console.error(...args);
+
+	const symbols = loadSymbols();
+	console.error(`  [${modelKey}] Loaded ${symbols.length} symbols`);
+
 	const embedStart = performance.now();
 	await buildEmbeddings(root, modelKey, dbPath, { strategy: 'structured' });
 	const embedTimeMs = Math.round(performance.now() - embedStart);
@@ -90,8 +96,10 @@ async function benchmarkModel(modelKey, symbols) {
 	}
 	const searchTimeMs = Math.round(performance.now() - searchStart);
 
+	try { await disposeModel(); } catch { /* best-effort */ }
+
 	const total = symbols.length;
-	return {
+	const modelResult = {
 		dim: MODELS[modelKey].dim,
 		contextWindow: MODELS[modelKey].contextWindow,
 		hits1,
@@ -103,16 +111,82 @@ async function benchmarkModel(modelKey, symbols) {
 		embedTimeMs,
 		searchTimeMs,
 	};
+
+	console.log = origLog;
+	console.log(JSON.stringify({ symbols: symbols.length, result: modelResult }));
+
+	cleanup();
+	process.exit(0);
 }
 
-// ── Run benchmarks ──────────────────────────────────────────────────────
+// ── Parent process: fork one child per model, assemble final output ──────
+const { version, srcDir, cleanup } = await resolveBenchmarkSource();
+const dbPath = path.join(root, '.codegraph', 'graph.db');
 
-const symbols = loadSymbols();
-console.error(`Loaded ${symbols.length} symbols for benchmark`);
+const { MODELS } = await import(srcImport(srcDir, 'embeddings/index.js'));
 
+const TIMEOUT_MS = 600_000;
 const hasHfToken = !!process.env.HF_TOKEN;
 const modelKeys = Object.keys(MODELS);
 const results = {};
+let symbolCount = 0;
+
+const scriptPath = fileURLToPath(import.meta.url);
+
+function forkModel(modelKey) {
+	return new Promise((resolve) => {
+		console.error(`\n[fork] Spawning ${modelKey} worker (pid isolation)...`);
+
+		const child = fork(scriptPath, process.argv.slice(2), {
+			env: { ...process.env, [MODEL_WORKER_KEY]: modelKey },
+			stdio: ['ignore', 'pipe', 'inherit', 'ipc'],
+			timeout: TIMEOUT_MS,
+		});
+
+		let stdout = '';
+		child.stdout.on('data', (chunk) => { stdout += chunk; });
+
+		const timer = setTimeout(() => {
+			console.error(`[fork] ${modelKey} worker timed out after ${TIMEOUT_MS / 1000}s — killing`);
+			child.kill('SIGKILL');
+		}, TIMEOUT_MS);
+
+		child.on('close', (code, signal) => {
+			clearTimeout(timer);
+
+			if (signal) {
+				console.error(`[fork] ${modelKey} worker killed by signal ${signal}`);
+				resolve(null);
+				return;
+			}
+
+			if (code !== 0) {
+				console.error(`[fork] ${modelKey} worker exited with code ${code}`);
+				try {
+					const parsed = JSON.parse(stdout);
+					console.error(`[fork] ${modelKey} worker produced partial results despite non-zero exit`);
+					resolve(parsed);
+				} catch {
+					resolve(null);
+				}
+				return;
+			}
+
+			try {
+				resolve(JSON.parse(stdout));
+			} catch (err) {
+				console.error(`[fork] ${modelKey} worker produced invalid JSON: ${err.message}`);
+				resolve(null);
+			}
+		});
+
+		child.on('error', (err) => {
+			clearTimeout(timer);
+			console.error(`[fork] ${modelKey} worker failed to start: ${err.message}`);
+			resolve(null);
+		});
+	});
+}
 
 for (const key of modelKeys) {
 	if (key === 'jina-code' && !hasHfToken) {
@@ -120,32 +194,24 @@ for (const key of modelKeys) {
 		continue;
 	}
 
-	console.error(`\nBenchmarking model: ${key}...`);
-	try {
-		results[key] = await benchmarkModel(key, symbols);
-		const r = results[key];
+	const data = await forkModel(key);
+	if (data) {
+		results[key] = data.result;
+		if (data.symbols) symbolCount = data.symbols;
+		const r = data.result;
 		console.error(
 			`  Hit@1=${r.hits1}/${r.total} Hit@3=${r.hits3}/${r.total} Hit@5=${r.hits5}/${r.total} misses=${r.misses}`,
 		);
-	} catch (err) {
-		console.error(`  FAILED: ${err?.message ?? String(err)}`);
-	} finally {
-		try {
-			await disposeModel();
-		} catch (disposeErr) {
-			console.error(`  disposeModel failed: ${disposeErr?.message ?? String(disposeErr)}`);
-		}
+	} else {
+		console.error(`  ${key}: FAILED (worker crashed or timed out)`);
 	}
 }
 
-// Restore console.log for JSON output
-console.log = origLog;
-
 const output = {
 	version,
 	date: new Date().toISOString().slice(0, 10),
 	strategy: 'structured',
-	symbols: symbols.length,
+	symbols: symbolCount,
 	models: results,
 };
 
diff --git a/scripts/incremental-benchmark.js b/scripts/incremental-benchmark.js
index bc20b208..94c3ac9b 100644
--- a/scripts/incremental-benchmark.js
+++ b/scripts/incremental-benchmark.js
@@ -3,9 +3,9 @@
 /**
  * Incremental build benchmark — measures build tiers and import resolution.
  *
- * Measures full build, no-op rebuild, and single-file rebuild for both
- * native and WASM engines. Also benchmarks import resolution throughput:
- * native batch vs JS fallback.
+ * Each engine (native / WASM) runs in a forked subprocess so that a segfault
+ * in the native addon only kills the child — the parent survives and collects
+ * partial results from whichever engines succeeded.
  *
  * Usage: node scripts/incremental-benchmark.js > result.json
  */
@@ -15,216 +15,185 @@ import path from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { fileURLToPath } from 'node:url';
 import { resolveBenchmarkSource, srcImport } from './lib/bench-config.js';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const root = path.resolve(__dirname, '..');
-
-const { version, srcDir, cleanup } = await resolveBenchmarkSource();
-const dbPath = path.join(root, '.codegraph', 'graph.db');
-
-const { buildGraph } = await import(srcImport(srcDir, 'builder.js'));
-const { statsData } = await import(srcImport(srcDir, 'queries.js'));
-const { resolveImportPath, resolveImportsBatch, resolveImportPathJS } = await import(
-	srcImport(srcDir, 'resolve.js')
-);
-const { isNativeAvailable } = await import(
-	srcImport(srcDir, 'native.js')
-);
-const { isWasmAvailable } = await import(
-	srcImport(srcDir, 'parser.js')
-);
-
-// Redirect console.log to stderr so only JSON goes to stdout
-const origLog = console.log;
-console.log = (...args) => console.error(...args);
-
-const RUNS = 3;
-const PROBE_FILE = path.join(root, 'src', 'queries.js');
-
-function median(arr) {
-	const sorted = [...arr].sort((a, b) => a - b);
-	const mid = Math.floor(sorted.length / 2);
-	return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
-}
-
-function round1(n) {
-	return Math.round(n * 10) / 10;
-}
-
-/**
- * Benchmark build tiers for a given engine.
- */
-async function benchmarkBuildTiers(engine) {
-	// Full build (delete DB first)
-	const fullTimings = [];
-	for (let i = 0; i < RUNS; i++) {
-		if (fs.existsSync(dbPath)) fs.unlinkSync(dbPath);
-		const start = performance.now();
-		await buildGraph(root, { engine, incremental: false });
-		fullTimings.push(performance.now() - start);
-	}
-	const fullBuildMs = Math.round(median(fullTimings));
-
-	// No-op rebuild (nothing changed)
-	const noopTimings = [];
-	for (let i = 0; i < RUNS; i++) {
-		const start = performance.now();
-		await buildGraph(root, { engine, incremental: true });
-		noopTimings.push(performance.now() - start);
+import { isWorker, workerEngine, forkEngines } from './lib/fork-engine.js';
+
+// ── Parent process: fork one child per engine, assemble final output ─────
+if (!isWorker()) {
+	const { version, srcDir: parentSrcDir, cleanup: parentCleanup } = await resolveBenchmarkSource();
+	const { wasm, native } = await forkEngines(import.meta.url, process.argv.slice(2));
+
+	// Import resolution runs in the parent — it tests both native and JS
+	// fallback in a single pass and doesn't need engine isolation.
+	const __dirParent = path.dirname(fileURLToPath(import.meta.url));
+	const rootParent = path.resolve(__dirParent, '..');
+	const dbPathParent = path.join(rootParent, '.codegraph', 'graph.db');
+
+	const { statsData: parentStats } = await import(srcImport(parentSrcDir, 'queries.js'));
+	const { resolveImportsBatch: parentBatch, resolveImportPathJS: parentJS } = await import(
+		srcImport(parentSrcDir, 'resolve.js')
+	);
+	const { isNativeAvailable: parentNativeCheck } = await import(
+		srcImport(parentSrcDir, 'native.js')
+	);
+
+	const RUNS = 3;
+	function median(arr) {
+		const sorted = [...arr].sort((a, b) => a - b);
+		const mid = Math.floor(sorted.length / 2);
+		return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
 	}
-	const noopRebuildMs = Math.round(median(noopTimings));
-
-	// 1-file change rebuild
-	const original = fs.readFileSync(PROBE_FILE, 'utf8');
-	let oneFileRebuildMs;
-	let oneFilePhases = null;
-	try {
-		const oneFileRuns = [];
-		for (let i = 0; i < RUNS; i++) {
-			fs.writeFileSync(PROBE_FILE, original + `\n// probe-${i}\n`);
-			const start = performance.now();
-			const res = await buildGraph(root, { engine, incremental: true });
-			oneFileRuns.push({ ms: performance.now() - start, phases: res?.phases || null });
+	function round1(n) { return Math.round(n * 10) / 10; }
+
+	function collectImportPairs() {
+		const srcDir = path.join(rootParent, 'src');
+		const files = fs.readdirSync(srcDir).filter((f) => f.endsWith('.js'));
+		const importRe = /(?:^|\n)\s*import\s+.*?\s+from\s+['"]([^'"]+)['"]/g;
+		const pairs = [];
+		for (const file of files) {
+			const absFile = path.join(srcDir, file);
+			const content = fs.readFileSync(absFile, 'utf8');
+			let match;
+			while ((match = importRe.exec(content)) !== null) {
+				pairs.push({ fromFile: absFile, importSource: match[1] });
+			}
 		}
-		oneFileRuns.sort((a, b) => a.ms - b.ms);
-		const medianRun = oneFileRuns[Math.floor(oneFileRuns.length / 2)];
-		oneFileRebuildMs = Math.round(medianRun.ms);
-		oneFilePhases = medianRun.phases;
-	} finally {
-		fs.writeFileSync(PROBE_FILE, original);
-		// One final incremental build to restore DB state
-		await buildGraph(root, { engine, incremental: true });
+		return pairs;
 	}
 
-	return { fullBuildMs, noopRebuildMs, oneFileRebuildMs, oneFilePhases };
-}
+	let stats = null;
+	try { stats = parentStats(dbPathParent); } catch { /* DB may not exist if both engines failed */ }
+	const files = stats?.files?.total ?? (wasm?.files || native?.files || 0);
 
-/**
- * Collect all import pairs by scanning source files for ES import statements.
- */
-function collectImportPairs() {
-	const srcDir = path.join(root, 'src');
-	const files = fs.readdirSync(srcDir).filter((f) => f.endsWith('.js'));
-	const importRe = /(?:^|\n)\s*import\s+.*?\s+from\s+['"]([^'"]+)['"]/g;
-
-	const pairs = [];
-	for (const file of files) {
-		const absFile = path.join(srcDir, file);
-		const content = fs.readFileSync(absFile, 'utf8');
-		let match;
-		while ((match = importRe.exec(content)) !== null) {
-			pairs.push({ fromFile: absFile, importSource: match[1] });
-		}
-	}
-	return pairs;
-}
+	console.error('Benchmarking import resolution...');
+	const inputs = collectImportPairs();
+	console.error(`  ${inputs.length} import pairs collected`);
 
-/**
- * Benchmark import resolution: native batch vs JS fallback.
- */
-function benchmarkResolve(inputs) {
-	const aliases = null; // codegraph itself has no path aliases
-
-	// Native batch
 	let nativeBatchMs = null;
 	let perImportNativeMs = null;
-	if (isNativeAvailable()) {
+	if (parentNativeCheck()) {
 		const timings = [];
 		for (let i = 0; i < RUNS; i++) {
 			const start = performance.now();
-			resolveImportsBatch(inputs, root, aliases);
+			parentBatch(inputs, rootParent, null);
 			timings.push(performance.now() - start);
 		}
 		nativeBatchMs = round1(median(timings));
 		perImportNativeMs = inputs.length > 0 ? round1(nativeBatchMs / inputs.length) : 0;
 	}
-
-	// JS fallback (call the exported JS implementation)
 	const jsTimings = [];
 	for (let i = 0; i < RUNS; i++) {
 		const start = performance.now();
 		for (const { fromFile, importSource } of inputs) {
-			resolveImportPathJS(fromFile, importSource, root, aliases);
+			parentJS(fromFile, importSource, rootParent, null);
 		}
 		jsTimings.push(performance.now() - start);
 	}
 	const jsFallbackMs = round1(median(jsTimings));
 	const perImportJsMs = inputs.length > 0 ? round1(jsFallbackMs / inputs.length) : 0;
 
-	return {
-		imports: inputs.length,
-		nativeBatchMs,
-		jsFallbackMs,
-		perImportNativeMs,
-		perImportJsMs,
+	const resolve = { imports: inputs.length, nativeBatchMs, jsFallbackMs, perImportNativeMs, perImportJsMs };
+	console.error(`  native=${resolve.nativeBatchMs}ms js=${resolve.jsFallbackMs}ms`);
+
+	const result = {
+		version,
+		date: new Date().toISOString().slice(0, 10),
+		files,
+		wasm: wasm
+			? {
+					fullBuildMs: wasm.fullBuildMs,
+					noopRebuildMs: wasm.noopRebuildMs,
+					oneFileRebuildMs: wasm.oneFileRebuildMs,
+					oneFilePhases: wasm.oneFilePhases,
+				}
+			: null,
+		native: native
+			? {
+					fullBuildMs: native.fullBuildMs,
+					noopRebuildMs: native.noopRebuildMs,
+					oneFileRebuildMs: native.oneFileRebuildMs,
+					oneFilePhases: native.oneFilePhases,
+				}
+			: null,
+		resolve,
 	};
+
+	console.log(JSON.stringify(result, null, 2));
+	parentCleanup();
+	process.exit(0);
 }
 
-// ── Run benchmarks ───────────────────────────────────────────────────────
-const hasWasm = isWasmAvailable();
-const hasNative = isNativeAvailable();
+// ── Worker process: benchmark build tiers for a single engine ────────────
+const engine = workerEngine();
 
-if (!hasWasm && !hasNative) {
-	console.error('Error: Neither WASM grammars nor native engine are available.');
-	console.error('Run "npm run build:wasm" to build WASM grammars, or install the native platform package.');
-	process.exit(1);
-}
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(__dirname, '..');
 
-let wasm = null;
-if (hasWasm) {
-	console.error('Benchmarking WASM engine...');
-	wasm = await benchmarkBuildTiers('wasm');
-	console.error(`  full=${wasm.fullBuildMs}ms noop=${wasm.noopRebuildMs}ms 1-file=${wasm.oneFileRebuildMs}ms`);
-} else {
-	console.error('WASM grammars not built — skipping WASM benchmark');
-}
+const { srcDir, cleanup } = await resolveBenchmarkSource();
+const dbPath = path.join(root, '.codegraph', 'graph.db');
+
+const { buildGraph } = await import(srcImport(srcDir, 'builder.js'));
+
+// Redirect console.log to stderr so only JSON goes to stdout
+const origLog = console.log;
+console.log = (...args) => console.error(...args);
 
-let native = null;
-if (hasNative) {
-	console.error('Benchmarking native engine...');
-	native = await benchmarkBuildTiers('native');
-	console.error(`  full=${native.fullBuildMs}ms noop=${native.noopRebuildMs}ms 1-file=${native.oneFileRebuildMs}ms`);
-} else {
-	console.error('Native engine not available — skipping native build benchmark');
+const RUNS = 3;
+const PROBE_FILE = path.join(root, 'src', 'queries.js');
+
+function median(arr) {
+	const sorted = [...arr].sort((a, b) => a - b);
+	const mid = Math.floor(sorted.length / 2);
+	return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
 }
 
-// Get file count from whichever graph was built last
-const stats = statsData(dbPath);
-const files = stats.files.total;
+console.error(`Benchmarking ${engine} engine...`);
+
+// Full build (delete DB first)
+const fullTimings = [];
+for (let i = 0; i < RUNS; i++) {
+	if (fs.existsSync(dbPath)) fs.unlinkSync(dbPath);
+	const start = performance.now();
+	await buildGraph(root, { engine, incremental: false });
+	fullTimings.push(performance.now() - start);
+}
+const fullBuildMs = Math.round(median(fullTimings));
+
+// No-op rebuild (nothing changed)
+const noopTimings = [];
+for (let i = 0; i < RUNS; i++) {
+	const start = performance.now();
+	await buildGraph(root, { engine, incremental: true });
+	noopTimings.push(performance.now() - start);
+}
+const noopRebuildMs = Math.round(median(noopTimings));
+
+// 1-file change rebuild
+const original = fs.readFileSync(PROBE_FILE, 'utf8');
+let oneFileRebuildMs;
+let oneFilePhases = null;
+try {
+	const oneFileRuns = [];
+	for (let i = 0; i < RUNS; i++) {
+		fs.writeFileSync(PROBE_FILE, original + `\n// probe-${i}\n`);
+		const start = performance.now();
+		const res = await buildGraph(root, { engine, incremental: true });
+		oneFileRuns.push({ ms: performance.now() - start, phases: res?.phases || null });
+	}
+	oneFileRuns.sort((a, b) => a.ms - b.ms);
+	const medianRun = oneFileRuns[Math.floor(oneFileRuns.length / 2)];
+	oneFileRebuildMs = Math.round(medianRun.ms);
+	oneFilePhases = medianRun.phases;
+} finally {
+	fs.writeFileSync(PROBE_FILE, original);
+	await buildGraph(root, { engine, incremental: true });
+}
 
-// Import resolution benchmark (uses existing graph)
-console.error('Benchmarking import resolution...');
-const inputs = collectImportPairs();
-console.error(`  ${inputs.length} import pairs collected`);
-const resolve = benchmarkResolve(inputs);
-console.error(`  native=${resolve.nativeBatchMs}ms js=${resolve.jsFallbackMs}ms`);
+console.error(`  full=${fullBuildMs}ms noop=${noopRebuildMs}ms 1-file=${oneFileRebuildMs}ms`);
 
 // Restore console.log for JSON output
 console.log = origLog;
 
-const result = {
-	version,
-	date: new Date().toISOString().slice(0, 10),
-	files,
-	wasm: wasm
-		? {
-				fullBuildMs: wasm.fullBuildMs,
-				noopRebuildMs: wasm.noopRebuildMs,
-				oneFileRebuildMs: wasm.oneFileRebuildMs,
-				oneFilePhases: wasm.oneFilePhases,
-			}
-		: null,
-	native: native
-		? {
-				fullBuildMs: native.fullBuildMs,
-				noopRebuildMs: native.noopRebuildMs,
-				oneFileRebuildMs: native.oneFileRebuildMs,
-				oneFilePhases: native.oneFilePhases,
-			}
-		: null,
-	resolve,
-};
-
-console.log(JSON.stringify(result, null, 2));
+const workerResult = { fullBuildMs, noopRebuildMs, oneFileRebuildMs, oneFilePhases };
+console.log(JSON.stringify(workerResult));
 
 cleanup();
diff --git a/scripts/lib/fork-engine.js b/scripts/lib/fork-engine.js
new file mode 100644
index 00000000..d0594777
--- /dev/null
+++ b/scripts/lib/fork-engine.js
@@ -0,0 +1,163 @@
+/**
+ * Child-process isolation for benchmarks.
+ *
+ * Runs each engine benchmark in a subprocess so that segfaults (e.g. from the
+ * native Rust addon) only kill the child — the parent survives and collects
+ * partial results from whichever engines succeeded.
+ *
+ * Usage (in a benchmark script):
+ *
+ *   import { forkEngines, isWorker, workerEngine } from './lib/fork-engine.js';
+ *
+ *   if (isWorker()) {
+ *     // Child path — run a single engine, write JSON to stdout, then exit.
+ *     const engine = workerEngine();
+ *     const result = await runBenchmarkForEngine(engine);
+ *     process.stdout.write(JSON.stringify(result));
+ *     process.exit(0);
+ *   }
+ *
+ *   // Parent path — fork one child per engine, collect results.
+ *   const { wasm, native } = await forkEngines(import.meta.url, process.argv.slice(2));
+ */
+
+import { fork } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const WORKER_ENV_KEY = '__BENCH_ENGINE__';
+
+/**
+ * Returns true when running inside a forked worker process.
+ */
+export function isWorker() {
+	return !!process.env[WORKER_ENV_KEY];
+}
+
+/**
+ * Returns the engine name ('wasm' | 'native') assigned to this worker.
+ * Throws if called outside a worker.
+ */
+export function workerEngine() {
+	const engine = process.env[WORKER_ENV_KEY];
+	if (!engine) throw new Error('workerEngine() called outside a worker process');
+	return engine;
+}
+
+/**
+ * Fork the calling script once per available engine, collect JSON results.
+ *
+ * @param {string} scriptUrl   import.meta.url of the calling benchmark script
+ * @param {string[]} argv      CLI args to forward (e.g. ['--version', '1.0.0', '--npm'])
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutMs=600_000]  Per-engine timeout (default 10 min)
+ * @returns {Promise<{ wasm: object|null, native: object|null }>}
+ */
+export async function forkEngines(scriptUrl, argv = [], opts = {}) {
+	const scriptPath = fileURLToPath(scriptUrl);
+	const timeoutMs = opts.timeoutMs ?? 600_000;
+
+	// Detect available engines by importing the check functions in-process.
+	// These are lightweight checks (no parsing), safe to run in the parent.
+	let hasWasm = false;
+	let hasNative = false;
+
+	// We need srcDir to resolve the imports. Re-use bench-config for this.
+	const { resolveBenchmarkSource, srcImport } = await import('./bench-config.js');
+	const { srcDir, cleanup } = await resolveBenchmarkSource();
+
+	try {
+		const { isWasmAvailable } = await import(srcImport(srcDir, 'parser.js'));
+		hasWasm = isWasmAvailable();
+	} catch { /* unavailable */ }
+
+	try {
+		const { isNativeAvailable } = await import(srcImport(srcDir, 'native.js'));
+		hasNative = isNativeAvailable();
+	} catch { /* unavailable */ }
+
+	cleanup();
+
+	if (!hasWasm && !hasNative) {
+		console.error('Error: Neither WASM grammars nor native engine are available.');
+		console.error('Run "npm run build:wasm" to build WASM grammars, or install the native platform package.');
+		process.exit(1);
+	}
+
+	/**
+	 * Fork a single engine worker and collect its JSON output.
+	 * @param {string} engine
+	 * @returns {Promise<object|null>}
+	 */
+	function runWorker(engine) {
+		return new Promise((resolve) => {
+			console.error(`\n[fork] Spawning ${engine} worker (pid isolation)...`);
+
+			const child = fork(scriptPath, argv, {
+				env: { ...process.env, [WORKER_ENV_KEY]: engine },
+				stdio: ['ignore', 'pipe', 'inherit', 'ipc'],
+				timeout: timeoutMs,
+			});
+
+			let stdout = '';
+			child.stdout.on('data', (chunk) => { stdout += chunk; });
+
+			const timer = setTimeout(() => {
+				console.error(`[fork] ${engine} worker timed out after ${timeoutMs / 1000}s — killing`);
+				child.kill('SIGKILL');
+			}, timeoutMs);
+
+			child.on('close', (code, signal) => {
+				clearTimeout(timer);
+
+				if (signal) {
+					console.error(`[fork] ${engine} worker killed by signal ${signal}`);
+					resolve(null);
+					return;
+				}
+
+				if (code !== 0) {
+					console.error(`[fork] ${engine} worker exited with code ${code}`);
+					// Try to parse partial output anyway
+					try {
+						const parsed = JSON.parse(stdout);
+						console.error(`[fork] ${engine} worker produced partial results despite non-zero exit`);
+						resolve(parsed);
+					} catch {
+						resolve(null);
+					}
+					return;
+				}
+
+				try {
+					resolve(JSON.parse(stdout));
+				} catch (err) {
+					console.error(`[fork] ${engine} worker produced invalid JSON: ${err.message}`);
+					resolve(null);
+				}
+			});
+
+			child.on('error', (err) => {
+				clearTimeout(timer);
+				console.error(`[fork] ${engine} worker failed to start: ${err.message}`);
+				resolve(null);
+			});
+		});
+	}
+
+	const results = { wasm: null, native: null };
+
+	// Run engines sequentially — they share the DB file and filesystem state.
+	if (hasWasm) {
+		results.wasm = await runWorker('wasm');
+	} else {
+		console.error('WASM grammars not built — skipping WASM benchmark');
+	}
+
+	if (hasNative) {
+		results.native = await runWorker('native');
+	} else {
+		console.error('Native engine not available — skipping native benchmark');
+	}
+
+	return results;
+}
diff --git a/scripts/query-benchmark.js b/scripts/query-benchmark.js
index 76dd9151..0758f745 100644
--- a/scripts/query-benchmark.js
+++ b/scripts/query-benchmark.js
@@ -3,10 +3,9 @@
 /**
  * Query benchmark runner — measures query depth scaling and diff-impact latency.
  *
- * Dynamically selects hub/mid/leaf targets from the graph, then benchmarks
- * fnDepsData and fnImpactData at depth 1, 3, 5 plus diffImpactData with a
- * synthetic staged change. Runs against both native and WASM engine-built
- * graphs to catch structural differences.
+ * Each engine (native / WASM) runs in a forked subprocess so that a segfault
+ * in the native addon only kills the child — the parent survives and collects
+ * partial results from whichever engines succeeded.
  *
  * Usage: node scripts/query-benchmark.js > result.json
  */
@@ -18,30 +17,57 @@ import { performance } from 'node:perf_hooks';
 import { fileURLToPath } from 'node:url';
 import Database from 'better-sqlite3';
 import { resolveBenchmarkSource, srcImport } from './lib/bench-config.js';
+import { isWorker, workerEngine, forkEngines } from './lib/fork-engine.js';
+
+// ── Parent process: fork one child per engine, assemble final output ─────
+if (!isWorker()) {
+	const { version } = await resolveBenchmarkSource();
+	const { wasm, native } = await forkEngines(import.meta.url, process.argv.slice(2));
+
+	const result = {
+		version,
+		date: new Date().toISOString().slice(0, 10),
+		wasm: wasm
+			? {
+					targets: wasm.targets,
+					fnDeps: wasm.fnDeps,
+					fnImpact: wasm.fnImpact,
+					diffImpact: wasm.diffImpact,
+				}
+			: null,
+		native: native
+			? {
+					targets: native.targets,
+					fnDeps: native.fnDeps,
+					fnImpact: native.fnImpact,
+					diffImpact: native.diffImpact,
+				}
+			: null,
+	};
+
+	console.log(JSON.stringify(result, null, 2));
+	process.exit(0);
+}
+
+// ── Worker process: benchmark a single engine, write JSON to stdout ──────
+const engine = workerEngine();
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(__dirname, '..');
 
-const { version, srcDir, cleanup } = await resolveBenchmarkSource();
+const { srcDir, cleanup } = await resolveBenchmarkSource();
 const dbPath = path.join(root, '.codegraph', 'graph.db');
 
 const { buildGraph } = await import(srcImport(srcDir, 'builder.js'));
-const { fnDepsData, fnImpactData, diffImpactData, statsData } = await import(
+const { fnDepsData, fnImpactData, diffImpactData } = await import(
 	srcImport(srcDir, 'queries.js')
 );
-const { isNativeAvailable } = await import(
-	srcImport(srcDir, 'native.js')
-);
-const { isWasmAvailable } = await import(
-	srcImport(srcDir, 'parser.js')
-);
 
 // Redirect console.log to stderr so only JSON goes to stdout
 const origLog = console.log;
 console.log = (...args) => console.error(...args);
 
 const RUNS = 5;
-const DEPTHS = [1, 3, 5];
 
 function median(arr) {
 	const sorted = [...arr].sort((a, b) => a - b);
@@ -53,11 +79,31 @@ function round1(n) {
 	return Math.round(n * 10) / 10;
 }
 
-/**
- * Select hub / mid / leaf targets dynamically from the graph.
- */
+// Pinned hub targets — stable function names that exist across versions.
+// Auto-selecting the most-connected node makes version-to-version comparison
+// meaningless when barrel/type files get added or removed.
+const PINNED_HUB_CANDIDATES = ['buildGraph', 'openDb', 'loadConfig'];
+
 function selectTargets() {
 	const db = new Database(dbPath, { readonly: true });
+
+	// Try pinned candidates first for a stable hub across versions
+	let hub = null;
+	for (const candidate of PINNED_HUB_CANDIDATES) {
+		const row = db
+			.prepare(
+				`SELECT n.name FROM nodes n
+         JOIN edges e ON e.source_id = n.id OR e.target_id = n.id
+         WHERE n.name = ? AND n.file NOT LIKE '%test%' AND n.file NOT LIKE '%spec%'
+         LIMIT 1`,
+			)
+			.get(candidate);
+		if (row) {
+			hub = row.name;
+			break;
+		}
+	}
+
 	const rows = db
 		.prepare(
 			`SELECT n.name, COUNT(e.id) AS cnt
@@ -72,15 +118,14 @@ function selectTargets() {
 
 	if (rows.length === 0) throw new Error('No nodes with edges found in graph');
 
-	const hub = rows[0].name;
+	// Fall back to most-connected if no pinned candidate found
+	if (!hub) hub = rows[0].name;
+
 	const mid = rows[Math.floor(rows.length / 2)].name;
 	const leaf = rows[rows.length - 1].name;
 	return { hub, mid, leaf };
 }
 
-/**
- * Benchmark a single query function at multiple depths.
- */
 function benchDepths(fn, name, depths) {
 	const result = {};
 	for (const depth of depths) {
@@ -95,11 +140,7 @@ function benchDepths(fn, name, depths) {
 	return result;
 }
 
-/**
- * Benchmark diff-impact with a synthetic staged change on the hub file.
- */
 function benchDiffImpact(hubName) {
-	// Find the file that contains the hub symbol
 	const db = new Database(dbPath, { readonly: true });
 	const row = db
 		.prepare(`SELECT file FROM nodes WHERE name = ? LIMIT 1`)
@@ -112,7 +153,6 @@ function benchDiffImpact(hubName) {
 	const original = fs.readFileSync(hubFile, 'utf8');
 
 	try {
-		// Append a probe comment and stage it
 		fs.writeFileSync(hubFile, original + '\n// benchmark-probe\n');
 		execFileSync('git', ['add', hubFile], { cwd: root, stdio: 'pipe' });
 
@@ -130,95 +170,35 @@ function benchDiffImpact(hubName) {
 			affectedFiles: lastResult?.affectedFiles?.length || 0,
 		};
 	} finally {
-		// Restore: unstage + revert content
 		execFileSync('git', ['restore', '--staged', hubFile], { cwd: root, stdio: 'pipe' });
 		fs.writeFileSync(hubFile, original);
 	}
 }
 
-/**
- * Run all query benchmarks against the current graph.
- */
-function benchmarkQueries(targets) {
-	const fnDeps = {};
-	const fnImpact = {};
+// Build graph for this engine
+if (fs.existsSync(dbPath)) fs.unlinkSync(dbPath);
+await buildGraph(root, { engine, incremental: false });
 
-	// Run depth benchmarks on hub target (most connected — worst case)
-	fnDeps.depth1Ms = benchDepths(fnDepsData, targets.hub, [1]).depth1Ms;
-	fnDeps.depth3Ms = benchDepths(fnDepsData, targets.hub, [3]).depth3Ms;
-	fnDeps.depth5Ms = benchDepths(fnDepsData, targets.hub, [5]).depth5Ms;
+const targets = selectTargets();
+console.error(`Targets: hub=${targets.hub}, mid=${targets.mid}, leaf=${targets.leaf}`);
 
-	fnImpact.depth1Ms = benchDepths(fnImpactData, targets.hub, [1]).depth1Ms;
-	fnImpact.depth3Ms = benchDepths(fnImpactData, targets.hub, [3]).depth3Ms;
-	fnImpact.depth5Ms = benchDepths(fnImpactData, targets.hub, [5]).depth5Ms;
+const fnDeps = {};
+const fnImpact = {};
 
-	const diffImpact = benchDiffImpact(targets.hub);
+fnDeps.depth1Ms = benchDepths(fnDepsData, targets.hub, [1]).depth1Ms;
+fnDeps.depth3Ms = benchDepths(fnDepsData, targets.hub, [3]).depth3Ms;
+fnDeps.depth5Ms = benchDepths(fnDepsData, targets.hub, [5]).depth5Ms;
 
-	return { targets, fnDeps, fnImpact, diffImpact };
-}
-
-// ── Run benchmarks ───────────────────────────────────────────────────────
-const hasWasm = isWasmAvailable();
-const hasNative = isNativeAvailable();
+fnImpact.depth1Ms = benchDepths(fnImpactData, targets.hub, [1]).depth1Ms;
+fnImpact.depth3Ms = benchDepths(fnImpactData, targets.hub, [3]).depth3Ms;
+fnImpact.depth5Ms = benchDepths(fnImpactData, targets.hub, [5]).depth5Ms;
 
-if (!hasWasm && !hasNative) {
-	console.error('Error: Neither WASM grammars nor native engine are available.');
-	console.error('Run "npm run build:wasm" to build WASM grammars, or install the native platform package.');
-	process.exit(1);
-}
-
-// Build with first available engine to select targets, then reuse for both
-let targets = null;
-let wasm = null;
-if (hasWasm) {
-	if (fs.existsSync(dbPath)) fs.unlinkSync(dbPath);
-	await buildGraph(root, { engine: 'wasm', incremental: false });
-
-	targets = selectTargets();
-	console.error(`Targets: hub=${targets.hub}, mid=${targets.mid}, leaf=${targets.leaf}`);
-	wasm = benchmarkQueries(targets);
-} else {
-	console.error('WASM grammars not built — skipping WASM benchmark');
-}
-
-let native = null;
-if (hasNative) {
-	if (fs.existsSync(dbPath)) fs.unlinkSync(dbPath);
-	await buildGraph(root, { engine: 'native', incremental: false });
-
-	if (!targets) {
-		targets = selectTargets();
-		console.error(`Targets: hub=${targets.hub}, mid=${targets.mid}, leaf=${targets.leaf}`);
-	}
-	native = benchmarkQueries(targets);
-} else {
-	console.error('Native engine not available — skipping native benchmark');
-}
+const diffImpact = benchDiffImpact(targets.hub);
 
 // Restore console.log for JSON output
 console.log = origLog;
 
-const result = {
-	version,
-	date: new Date().toISOString().slice(0, 10),
-	wasm: wasm
-		? {
-				targets: wasm.targets,
-				fnDeps: wasm.fnDeps,
-				fnImpact: wasm.fnImpact,
-				diffImpact: wasm.diffImpact,
-			}
-		: null,
-	native: native
-		? {
-				targets: native.targets,
-				fnDeps: native.fnDeps,
-				fnImpact: native.fnImpact,
-				diffImpact: native.diffImpact,
-			}
-		: null,
-};
-
-console.log(JSON.stringify(result, null, 2));
+const workerResult = { targets, fnDeps, fnImpact, diffImpact };
+console.log(JSON.stringify(workerResult));
 
 cleanup();
diff --git a/src/domain/analysis/context.js b/src/domain/analysis/context.js
index e3409208..db157cf2 100644
--- a/src/domain/analysis/context.js
+++ b/src/domain/analysis/context.js
@@ -95,7 +95,7 @@ function explainFileImpl(db, target, getFileLines) {
 function explainFunctionImpl(db, target, noTests, getFileLines) {
   let nodes = db
     .prepare(
-      `SELECT * FROM nodes WHERE name LIKE ? AND kind IN ('function','method','class','interface','type','struct','enum','trait','record','module') ORDER BY file, line`,
+      `SELECT * FROM nodes WHERE name LIKE ? AND kind IN ('function','method','class','interface','type','struct','enum','trait','record','module','constant') ORDER BY file, line`,
     )
     .all(`%${target}%`);
   if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
diff --git a/src/domain/graph/builder/stages/build-edges.js b/src/domain/graph/builder/stages/build-edges.js
index a8879b62..82df6ea0 100644
--- a/src/domain/graph/builder/stages/build-edges.js
+++ b/src/domain/graph/builder/stages/build-edges.js
@@ -28,7 +28,7 @@ export async function buildEdges(ctx) {
   // Pre-load all nodes into lookup maps
   const allNodes = db
     .prepare(
-      `SELECT id, name, kind, file, line FROM nodes WHERE kind IN ('function','method','class','interface','struct','type','module','enum','trait')`,
+      `SELECT id, name, kind, file, line FROM nodes WHERE kind IN ('function','method','class','interface','struct','type','module','enum','trait','record','constant')`,
     )
     .all();
   ctx.nodesByName = new Map();
@@ -134,6 +134,7 @@ export async function buildEdges(ctx) {
           calls: symbols.calls,
           importedNames,
           classes: symbols.classes,
+          typeAssignments: symbols.typeAssignments || [],
         });
       }
 
@@ -157,6 +158,18 @@ export async function buildEdges(ctx) {
           }
         }
 
+        // Build per-file type map from typeAssignments (receiver type tracking)
+        const typeMap = new Map();
+        if (symbols.typeAssignments) {
+          for (const ta of symbols.typeAssignments) {
+            // Keep highest-confidence assignment per variable
+            const existing = typeMap.get(ta.variable);
+            if (!existing || ta.confidence > existing.confidence) {
+              typeMap.set(ta.variable, ta);
+            }
+          }
+        }
+
         const seenCallEdges = new Set();
         for (const call of symbols.calls) {
           if (call.receiver && BUILTIN_RECEIVERS.has(call.receiver)) continue;
@@ -198,20 +211,53 @@ export async function buildEdges(ctx) {
           if (!targets || targets.length === 0) {
             targets = ctx.nodesByNameAndFile.get(`${call.name}|${relPath}`) || [];
             if (targets.length === 0) {
-              const methodCandidates = (ctx.nodesByName.get(call.name) || []).filter(
-                (n) => n.name.endsWith(`.${call.name}`) && n.kind === 'method',
-              );
-              if (methodCandidates.length > 0) {
-                targets = methodCandidates;
-              } else if (
-                !call.receiver ||
-                call.receiver === 'this' ||
-                call.receiver === 'self' ||
-                call.receiver === 'super'
+              // ── Receiver type tracking: resolve receiver.method() via type map ──
+              // When we have a receiver (e.g., `repo.findCallers()`), check the type
+              // map to find the receiver's class and look for ClassName.method.
+              let typedTargets = [];
+              if (
+                call.receiver &&
+                call.receiver !== 'this' &&
+                call.receiver !== 'self' &&
+                call.receiver !== 'super'
               ) {
-                targets = (ctx.nodesByName.get(call.name) || []).filter(
-                  (n) => computeConfidence(relPath, n.file, null) >= 0.5,
+                const typeInfo = typeMap.get(call.receiver);
+                if (typeInfo) {
+                  // Try qualified name: ClassName.methodName
+                  const qualifiedName = `${typeInfo.type}.${call.name}`;
+                  typedTargets = (ctx.nodesByName.get(qualifiedName) || []).filter(
+                    (n) => n.kind === 'method',
+                  );
+                  // If no match by qualified name, check if the type was imported
+                  // and look in that file for the qualified method
+                  if (typedTargets.length === 0) {
+                    const typeFile = importedNames.get(typeInfo.type);
+                    if (typeFile) {
+                      typedTargets =
+                        ctx.nodesByNameAndFile.get(`${qualifiedName}|${typeFile}`) || [];
+                    }
+                  }
+                }
+              }
+
+              if (typedTargets.length > 0) {
+                targets = typedTargets;
+              } else {
+                const methodCandidates = (ctx.nodesByName.get(call.name) || []).filter(
+                  (n) => n.name.endsWith(`.${call.name}`) && n.kind === 'method',
                 );
+                if (methodCandidates.length > 0) {
+                  targets = methodCandidates;
+                } else if (
+                  !call.receiver ||
+                  call.receiver === 'this' ||
+                  call.receiver === 'self' ||
+                  call.receiver === 'super'
+                ) {
+                  targets = (ctx.nodesByName.get(call.name) || []).filter(
+                    (n) => computeConfidence(relPath, n.file, null) >= 0.5,
+                  );
+                }
               }
             }
           }
@@ -233,7 +279,7 @@ export async function buildEdges(ctx) {
             }
           }
 
-          // Receiver edge
+          // Receiver edge — use type map when available for precise class resolution
           if (
             call.receiver &&
             !BUILTIN_RECEIVERS.has(call.receiver) &&
@@ -242,16 +288,34 @@ export async function buildEdges(ctx) {
             call.receiver !== 'super'
           ) {
             const receiverKinds = new Set(['class', 'struct', 'interface', 'type', 'module']);
-            const samefile = ctx.nodesByNameAndFile.get(`${call.receiver}|${relPath}`) || [];
-            const candidates =
-              samefile.length > 0 ? samefile : ctx.nodesByName.get(call.receiver) || [];
-            const receiverNodes = candidates.filter((n) => receiverKinds.has(n.kind));
+            let receiverNodes = [];
+            let recvConfidence = 0.7;
+
+            // Try type map first for precise receiver resolution
+            const typeInfo = typeMap.get(call.receiver);
+            if (typeInfo) {
+              const typeName = typeInfo.type;
+              const sameFileTyped = ctx.nodesByNameAndFile.get(`${typeName}|${relPath}`) || [];
+              const typedCandidates =
+                sameFileTyped.length > 0 ? sameFileTyped : ctx.nodesByName.get(typeName) || [];
+              receiverNodes = typedCandidates.filter((n) => receiverKinds.has(n.kind));
+              recvConfidence = typeInfo.confidence;
+            }
+
+            // Fallback: look up receiver name directly as a class/struct
+            if (receiverNodes.length === 0) {
+              const samefile = ctx.nodesByNameAndFile.get(`${call.receiver}|${relPath}`) || [];
+              const candidates =
+                samefile.length > 0 ? samefile : ctx.nodesByName.get(call.receiver) || [];
+              receiverNodes = candidates.filter((n) => receiverKinds.has(n.kind));
+            }
+
             if (receiverNodes.length > 0 && caller) {
               const recvTarget = receiverNodes[0];
               const recvKey = `recv|${caller.id}|${recvTarget.id}`;
               if (!seenCallEdges.has(recvKey)) {
                 seenCallEdges.add(recvKey);
-                allEdgeRows.push([caller.id, recvTarget.id, 'receiver', 0.7, 0]);
+                allEdgeRows.push([caller.id, recvTarget.id, 'receiver', recvConfidence, 0]);
               }
             }
           }
diff --git a/src/domain/graph/resolve.js b/src/domain/graph/resolve.js
index 5e0ab1d3..501e583b 100644
--- a/src/domain/graph/resolve.js
+++ b/src/domain/graph/resolve.js
@@ -3,6 +3,196 @@ import path from 'node:path';
 import { loadNative } from '../../infrastructure/native.js';
 import { normalizePath } from '../../shared/constants.js';
 
+// ── package.json exports resolution ─────────────────────────────────
+
+/** Cache: packageDir → parsed exports field (or null) */
+const _exportsCache = new Map();
+
+/**
+ * Parse a bare specifier into { packageName, subpath }.
+ * Scoped: "@scope/pkg/sub" → { packageName: "@scope/pkg", subpath: "./sub" }
+ * Plain:  "pkg/sub"        → { packageName: "pkg", subpath: "./sub" }
+ * No sub: "pkg"            → { packageName: "pkg", subpath: "." }
+ */
+export function parseBareSpecifier(specifier) {
+  let packageName, rest;
+  if (specifier.startsWith('@')) {
+    const parts = specifier.split('/');
+    if (parts.length < 2) return null;
+    packageName = parts[0] + '/' + parts[1];
+    rest = parts.slice(2).join('/');
+  } else {
+    const slashIdx = specifier.indexOf('/');
+    if (slashIdx === -1) {
+      packageName = specifier;
+      rest = '';
+    } else {
+      packageName = specifier.slice(0, slashIdx);
+      rest = specifier.slice(slashIdx + 1);
+    }
+  }
+  return { packageName, subpath: rest ? './' + rest : '.' };
+}
+
+/**
+ * Find the package directory for a given package name, starting from rootDir.
+ * Walks up node_modules directories.
+ */
+function findPackageDir(packageName, rootDir) {
+  let dir = rootDir;
+  while (true) {
+    const candidate = path.join(dir, 'node_modules', packageName);
+    if (fs.existsSync(path.join(candidate, 'package.json'))) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Read and cache the exports field from a package's package.json.
+ * Returns the exports value or null.
+ */
+function getPackageExports(packageDir) {
+  if (_exportsCache.has(packageDir)) return _exportsCache.get(packageDir);
+  try {
+    const raw = fs.readFileSync(path.join(packageDir, 'package.json'), 'utf8');
+    const pkg = JSON.parse(raw);
+    const exports = pkg.exports ?? null;
+    _exportsCache.set(packageDir, exports);
+    return exports;
+  } catch {
+    _exportsCache.set(packageDir, null);
+    return null;
+  }
+}
+
+/** Condition names to try, in priority order. */
+const CONDITION_ORDER = ['import', 'require', 'default'];
+
+/**
+ * Resolve a conditional exports value (string, object with conditions, or array).
+ * Returns a string target or null.
+ */
+function resolveCondition(value) {
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const r = resolveCondition(item);
+      if (r) return r;
+    }
+    return null;
+  }
+  if (value && typeof value === 'object') {
+    for (const cond of CONDITION_ORDER) {
+      if (cond in value) return resolveCondition(value[cond]);
+    }
+    return null;
+  }
+  return null;
+}
+
+/**
+ * Match a subpath against an exports map key that uses a wildcard pattern.
+ * Key: "./lib/*" matches subpath "./lib/foo/bar" → substitution "foo/bar"
+ */
+function matchSubpathPattern(pattern, subpath) {
+  const starIdx = pattern.indexOf('*');
+  if (starIdx === -1) return null;
+  const prefix = pattern.slice(0, starIdx);
+  const suffix = pattern.slice(starIdx + 1);
+  if (!subpath.startsWith(prefix)) return null;
+  if (suffix && !subpath.endsWith(suffix)) return null;
+  const matched = subpath.slice(prefix.length, suffix ? -suffix.length || undefined : undefined);
+  if (!suffix && subpath.length < prefix.length) return null;
+  return matched;
+}
+
+/**
+ * Resolve a bare specifier through the package.json exports field.
+ * Returns an absolute path or null.
+ */
+export function resolveViaExports(specifier, rootDir) {
+  const parsed = parseBareSpecifier(specifier);
+  if (!parsed) return null;
+
+  const packageDir = findPackageDir(parsed.packageName, rootDir);
+  if (!packageDir) return null;
+
+  const exports = getPackageExports(packageDir);
+  if (exports == null) return null;
+
+  const { subpath } = parsed;
+
+  // Simple string exports: "exports": "./index.js"
+  if (typeof exports === 'string') {
+    if (subpath === '.') {
+      const resolved = path.resolve(packageDir, exports);
+      return fs.existsSync(resolved) ? resolved : null;
+    }
+    return null;
+  }
+
+  // Array form at top level
+  if (Array.isArray(exports)) {
+    if (subpath === '.') {
+      const target = resolveCondition(exports);
+      if (target) {
+        const resolved = path.resolve(packageDir, target);
+        return fs.existsSync(resolved) ? resolved : null;
+      }
+    }
+    return null;
+  }
+
+  if (typeof exports !== 'object') return null;
+
+  // Determine if exports is a conditions object (no keys start with ".")
+  // or a subpath map (keys start with ".")
+  const keys = Object.keys(exports);
+  const isSubpathMap = keys.length > 0 && keys[0].startsWith('.');
+
+  if (!isSubpathMap) {
+    // Conditions object at top level → applies to "." subpath only
+    if (subpath === '.') {
+      const target = resolveCondition(exports);
+      if (target) {
+        const resolved = path.resolve(packageDir, target);
+        return fs.existsSync(resolved) ? resolved : null;
+      }
+    }
+    return null;
+  }
+
+  // Subpath map: try exact match first, then pattern match
+  if (subpath in exports) {
+    const target = resolveCondition(exports[subpath]);
+    if (target) {
+      const resolved = path.resolve(packageDir, target);
+      return fs.existsSync(resolved) ? resolved : null;
+    }
+  }
+
+  // Pattern matching (keys with *)
+  for (const [pattern, value] of Object.entries(exports)) {
+    if (!pattern.includes('*')) continue;
+    const matched = matchSubpathPattern(pattern, subpath);
+    if (matched == null) continue;
+    const rawTarget = resolveCondition(value);
+    if (!rawTarget) continue;
+    const target = rawTarget.replace(/\*/g, matched);
+    const resolved = path.resolve(packageDir, target);
+    if (fs.existsSync(resolved)) return resolved;
+  }
+
+  return null;
+}
+
+/** Clear the exports cache (for testing). */
+export function clearExportsCache() {
+  _exportsCache.clear();
+}
+
 // ── Alias format conversion ─────────────────────────────────────────
 
 /**
@@ -60,7 +250,11 @@ function resolveImportPathJS(fromFile, importSource, rootDir, aliases) {
     const aliasResolved = resolveViaAlias(importSource, aliases, rootDir);
     if (aliasResolved) return normalizePath(path.relative(rootDir, aliasResolved));
   }
-  if (!importSource.startsWith('.')) return importSource;
+  if (!importSource.startsWith('.')) {
+    const exportsResolved = resolveViaExports(importSource, rootDir);
+    if (exportsResolved) return normalizePath(path.relative(rootDir, exportsResolved));
+    return importSource;
+  }
   const dir = path.dirname(fromFile);
   const resolved = path.resolve(dir, importSource);
 
diff --git a/src/domain/graph/watcher.js b/src/domain/graph/watcher.js
index 15b4b4a6..3fea7954 100644
--- a/src/domain/graph/watcher.js
+++ b/src/domain/graph/watcher.js
@@ -57,10 +57,10 @@ export async function watchProject(rootDir, opts = {}) {
     countNodes: db.prepare('SELECT COUNT(*) as c FROM nodes WHERE file = ?'),
     countEdgesForFile: null,
     findNodeInFile: db.prepare(
-      "SELECT id, file FROM nodes WHERE name = ? AND kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module') AND file = ?",
+      "SELECT id, file FROM nodes WHERE name = ? AND kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'constant') AND file = ?",
     ),
     findNodeByName: db.prepare(
-      "SELECT id, file FROM nodes WHERE name = ? AND kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module')",
+      "SELECT id, file FROM nodes WHERE name = ? AND kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'constant')",
     ),
     listSymbols: db.prepare("SELECT name, kind, line FROM nodes WHERE file = ? AND kind != 'file'"),
   };
diff --git a/src/extractors/go.js b/src/extractors/go.js
index 50460c8d..2b2cbbbf 100644
--- a/src/extractors/go.js
+++ b/src/extractors/go.js
@@ -193,7 +193,12 @@ export function extractGoSymbols(tree, _filePath) {
   }
 
   walkGoNode(tree.rootNode);
-  return { definitions, calls, imports, classes, exports };
+
+  // Extract variable-to-type assignments for receiver type tracking
+  const typeAssignments = [];
+  extractGoTypeAssignments(tree.rootNode, typeAssignments);
+
+  return { definitions, calls, imports, classes, exports, typeAssignments };
 }
 
 // ── Child extraction helpers ────────────────────────────────────────────────
@@ -237,3 +242,130 @@ function extractStructFields(structTypeNode) {
   }
   return fields;
 }
+
+/**
+ * Extract variable-to-type assignments from Go AST.
+ *
+ * Patterns:
+ *   1. x := SomeStruct{...}        → confidence 1.0 (composite literal)
+ *   2. var x SomeType               → confidence 0.9 (var declaration with type)
+ *   3. x := pkg.NewFoo(...)         → confidence 0.7 (factory function)
+ */
+function extractGoTypeAssignments(node, typeAssignments) {
+  const t = node.type;
+
+  // short_var_declaration: x := expr
+  if (t === 'short_var_declaration') {
+    const left = node.childForFieldName('left');
+    const right = node.childForFieldName('right');
+    if (left && right) {
+      // Find the first identifier on the left side
+      const varNode = left.type === 'expression_list' ? left.child(0) : left;
+      if (varNode && varNode.type === 'identifier') {
+        const varName = varNode.text;
+        const rhs = right.type === 'expression_list' ? right.child(0) : right;
+        if (rhs) {
+          // Pattern 1: x := SomeStruct{...} (composite literal)
+          if (rhs.type === 'composite_literal') {
+            const typeNode = rhs.childForFieldName('type');
+            if (typeNode) {
+              const typeName =
+                typeNode.type === 'pointer_type'
+                  ? typeNode.text.replace(/^\*/, '')
+                  : typeNode.type === 'type_identifier' || typeNode.type === 'identifier'
+                    ? typeNode.text
+                    : null;
+              if (typeName) {
+                typeAssignments.push({
+                  variable: varName,
+                  type: typeName,
+                  line: node.startPosition.row + 1,
+                  confidence: 1.0,
+                });
+              }
+            }
+          }
+          // Pattern 1b: x := &SomeStruct{...} (address-of composite literal)
+          if (rhs.type === 'unary_expression') {
+            const operand = rhs.childForFieldName('operand');
+            if (operand && operand.type === 'composite_literal') {
+              const typeNode = operand.childForFieldName('type');
+              if (typeNode) {
+                const typeName =
+                  typeNode.type === 'type_identifier' || typeNode.type === 'identifier'
+                    ? typeNode.text
+                    : null;
+                if (typeName) {
+                  typeAssignments.push({
+                    variable: varName,
+                    type: typeName,
+                    line: node.startPosition.row + 1,
+                    confidence: 1.0,
+                  });
+                }
+              }
+            }
+          }
+          // Pattern 3: x := pkg.NewFoo(...) or NewFoo(...)
+          if (rhs.type === 'call_expression') {
+            const fn = rhs.childForFieldName('function');
+            if (fn && fn.type === 'selector_expression') {
+              const field = fn.childForFieldName('field');
+              if (field?.text.startsWith('New')) {
+                const typeName = field.text.slice(3); // NewFoo → Foo
+                if (typeName) {
+                  typeAssignments.push({
+                    variable: varName,
+                    type: typeName,
+                    line: node.startPosition.row + 1,
+                    confidence: 0.7,
+                  });
+                }
+              }
+            } else if (fn && fn.type === 'identifier' && fn.text.startsWith('New')) {
+              const typeName = fn.text.slice(3);
+              if (typeName) {
+                typeAssignments.push({
+                  variable: varName,
+                  type: typeName,
+                  line: node.startPosition.row + 1,
+                  confidence: 0.7,
+                });
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  // var_declaration: var x SomeType
+  if (t === 'var_declaration') {
+    for (let i = 0; i < node.childCount; i++) {
+      const spec = node.child(i);
+      if (!spec || spec.type !== 'var_spec') continue;
+      const nameNode = spec.childForFieldName('name');
+      const typeNode = spec.childForFieldName('type');
+      if (nameNode && typeNode) {
+        const typeName =
+          typeNode.type === 'pointer_type'
+            ? typeNode.text.replace(/^\*/, '')
+            : typeNode.type === 'type_identifier' || typeNode.type === 'identifier'
+              ? typeNode.text
+              : null;
+        if (typeName) {
+          typeAssignments.push({
+            variable: nameNode.text,
+            type: typeName,
+            line: spec.startPosition.row + 1,
+            confidence: 0.9,
+          });
+        }
+      }
+    }
+  }
+
+  for (let i = 0; i < node.childCount; i++) {
+    extractGoTypeAssignments(node.child(i), typeAssignments);
+  }
+}
diff --git a/src/extractors/javascript.js b/src/extractors/javascript.js
index a2d9e7b1..608ef0f6 100644
--- a/src/extractors/javascript.js
+++ b/src/extractors/javascript.js
@@ -179,7 +179,11 @@ function extractSymbolsQuery(tree, query) {
   // Extract dynamic import() calls via targeted walk (query patterns don't match `import` function type)
   extractDynamicImportsWalk(tree.rootNode, imports);
 
-  return { definitions, calls, imports, classes, exports: exps };
+  // Extract variable-to-type assignments for receiver type tracking
+  const typeAssignments = [];
+  extractTypeAssignmentsWalk(tree.rootNode, typeAssignments);
+
+  return { definitions, calls, imports, classes, exports: exps, typeAssignments };
 }
 
 /**
@@ -265,6 +269,117 @@ function extractDynamicImportsWalk(node, imports) {
   }
 }
 
+/**
+ * Recursive walk to extract variable-to-type assignments for receiver type tracking.
+ *
+ * Tracks three patterns with decreasing confidence:
+ *   1. Constructor:      const x = new SomeClass(...)         → confidence 1.0
+ *   2. Type annotation:  const x: SomeClass = ...             → confidence 0.9
+ *   3. Factory method:   const x = SomeClass.create(...)      → confidence 0.7
+ *
+ * The resulting typeAssignments array is consumed by build-edges to resolve
+ * receiver.method() calls to ClassName.method with high precision.
+ */
+function extractTypeAssignmentsWalk(node, typeAssignments) {
+  const t = node.type;
+  if (t === 'lexical_declaration' || t === 'variable_declaration') {
+    for (let i = 0; i < node.childCount; i++) {
+      const declarator = node.child(i);
+      if (!declarator || declarator.type !== 'variable_declarator') continue;
+      const nameNode = declarator.childForFieldName('name');
+      if (!nameNode || nameNode.type !== 'identifier') continue;
+      const varName = nameNode.text;
+      const valueNode = declarator.childForFieldName('value');
+
+      // Pattern 1: const x = new SomeClass(...)
+      if (valueNode && valueNode.type === 'new_expression') {
+        const ctor = valueNode.childForFieldName('constructor') || valueNode.child(1);
+        if (ctor) {
+          const typeName = ctor.type === 'identifier' ? ctor.text : null;
+          if (typeName) {
+            typeAssignments.push({
+              variable: varName,
+              type: typeName,
+              line: node.startPosition.row + 1,
+              confidence: 1.0,
+            });
+            continue;
+          }
+        }
+      }
+
+      // Pattern 2: const x: SomeClass = ... (TS type annotation)
+      const typeAnno =
+        nameNode.parent?.childForFieldName('type') || findChild(declarator, 'type_annotation');
+      if (typeAnno) {
+        const typeName = extractTypeAnnotationName(typeAnno);
+        if (typeName) {
+          typeAssignments.push({
+            variable: varName,
+            type: typeName,
+            line: node.startPosition.row + 1,
+            confidence: 0.9,
+          });
+          continue;
+        }
+      }
+
+      // Pattern 3: const x = SomeClass.create(...) (factory method)
+      if (valueNode && valueNode.type === 'call_expression') {
+        const fn = valueNode.childForFieldName('function');
+        if (fn && fn.type === 'member_expression') {
+          const obj = fn.childForFieldName('object');
+          if (obj && obj.type === 'identifier') {
+            const objName = obj.text;
+            // Heuristic: uppercase first letter suggests a class/constructor name
+            if (
+              objName[0] === objName[0].toUpperCase() &&
+              objName[0] !== objName[0].toLowerCase()
+            ) {
+              typeAssignments.push({
+                variable: varName,
+                type: objName,
+                line: node.startPosition.row + 1,
+                confidence: 0.7,
+              });
+            }
+          }
+        }
+      }
+    }
+  }
+
+  for (let i = 0; i < node.childCount; i++) {
+    extractTypeAssignmentsWalk(node.child(i), typeAssignments);
+  }
+}
+
+/**
+ * Extract the type name from a type annotation node.
+ * Handles: `: SomeClass`, `: SomeClass<T>`, `: SomeModule.SomeClass`
+ * Returns null for complex union/intersection types.
+ */
+function extractTypeAnnotationName(typeAnno) {
+  for (let i = 0; i < typeAnno.childCount; i++) {
+    const child = typeAnno.child(i);
+    if (!child) continue;
+    const ct = child.type;
+    if (ct === 'type_identifier' || ct === 'identifier') return child.text;
+    // Generic: SomeClass<T> → extract SomeClass
+    if (ct === 'generic_type') {
+      const nameNode = child.childForFieldName('name') || child.child(0);
+      if (nameNode && (nameNode.type === 'type_identifier' || nameNode.type === 'identifier')) {
+        return nameNode.text;
+      }
+    }
+    // Qualified: SomeModule.SomeClass → extract SomeModule.SomeClass
+    if (ct === 'nested_type_identifier' || ct === 'member_expression') {
+      return child.text;
+    }
+  }
+  return null;
+}
+
 function handleCommonJSAssignment(left, right, node, imports) {
   if (!left || !right) return;
   const leftText = left.text;
@@ -646,7 +761,12 @@ function extractSymbolsWalk(tree) {
   }
 
   walkJavaScriptNode(tree.rootNode);
-  return { definitions, calls, imports, classes, exports };
+
+  // Extract variable-to-type assignments for receiver type tracking
+  const typeAssignments = [];
+  extractTypeAssignmentsWalk(tree.rootNode, typeAssignments);
+
+  return { definitions, calls, imports, classes, exports, typeAssignments };
 }
 
 // ── Child extraction helpers ────────────────────────────────────────────────
diff --git a/src/extractors/python.js b/src/extractors/python.js
index 968dbacb..6b884783 100644
--- a/src/extractors/python.js
+++ b/src/extractors/python.js
@@ -291,5 +291,84 @@ export function extractPythonSymbols(tree, _filePath) {
   }
 
   walkPythonNode(tree.rootNode);
-  return { definitions, calls, imports, classes, exports };
+
+  // Extract variable-to-type assignments for receiver type tracking
+  const typeAssignments = [];
+  extractPythonTypeAssignments(tree.rootNode, typeAssignments);
+
+  return { definitions, calls, imports, classes, exports, typeAssignments };
+}
+
+/**
+ * Extract variable-to-type assignments from Python AST.
+ *
+ * Patterns:
+ *   1. x = SomeClass(...)           → confidence 1.0 (constructor call)
+ *   2. x: SomeClass = ...           → confidence 0.9 (type annotation)
+ *   3. x = SomeClass.create(...)    → confidence 0.7 (factory method)
+ */
+function extractPythonTypeAssignments(node, typeAssignments) {
+  // assignment: x = SomeClass(...) or x: SomeClass = ...
+  if (node.type === 'assignment') {
+    const left = node.childForFieldName('left');
+    const right = node.childForFieldName('right');
+    const typeAnno = node.childForFieldName('type');
+    if (left && left.type === 'identifier') {
+      const varName = left.text;
+
+      // Pattern 1: x = SomeClass(...) — constructor call with uppercase name
+      if (right && right.type === 'call') {
+        const fn = right.childForFieldName('function');
+        if (fn && fn.type === 'identifier') {
+          const name = fn.text;
+          if (name[0] === name[0].toUpperCase() && name[0] !== name[0].toLowerCase()) {
+            typeAssignments.push({
+              variable: varName,
+              type: name,
+              line: node.startPosition.row + 1,
+              confidence: 1.0,
+            });
+            return;
+          }
+        }
+        // Pattern 3: x = SomeClass.create(...)
+        if (fn && fn.type === 'attribute') {
+          const obj = fn.childForFieldName('object');
+          if (obj && obj.type === 'identifier') {
+            const objName = obj.text;
+            if (
+              objName[0] === objName[0].toUpperCase() &&
+              objName[0] !== objName[0].toLowerCase()
+            ) {
+              typeAssignments.push({
+                variable: varName,
+                type: objName,
+                line: node.startPosition.row + 1,
+                confidence: 0.7,
+              });
+              return;
+            }
+          }
+        }
+      }
+
+      // Pattern 2: x: SomeClass = ...
+      if (typeAnno && typeAnno.type === 'type') {
+        const typeIdent = typeAnno.child(0);
+        if (typeIdent && typeIdent.type === 'identifier') {
+          typeAssignments.push({
+            variable: varName,
+            type: typeIdent.text,
+            line: node.startPosition.row + 1,
+            confidence: 0.9,
+          });
+          return;
+        }
+      }
+    }
+  }
+
+  for (let i = 0; i < node.childCount; i++) {
+    extractPythonTypeAssignments(node.child(i), typeAssignments);
+  }
 }
diff --git a/src/features/export.js b/src/features/export.js
index 6f93faae..3bd064e3 100644
--- a/src/features/export.js
+++ b/src/features/export.js
@@ -67,8 +67,8 @@ function loadFunctionLevelEdges(db, { noTests, minConfidence, limit }) {
       FROM edges e
       JOIN nodes n1 ON e.source_id = n1.id
       JOIN nodes n2 ON e.target_id = n2.id
-      WHERE n1.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module')
-        AND n2.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module')
+      WHERE n1.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'constant')
+        AND n2.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'constant')
         AND e.kind = 'calls'
         AND e.confidence >= ?
     `,
@@ -308,7 +308,7 @@ export function exportGraphSON(db, opts = {}) {
   let nodes = db
     .prepare(`
     SELECT id, name, kind, file, line, role FROM nodes
-    WHERE kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'file')
+    WHERE kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'constant', 'file')
   `)
     .all();
   if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
diff --git a/src/features/graph-enrichment.js b/src/features/graph-enrichment.js
index 96e47e2c..adb9fb8e 100644
--- a/src/features/graph-enrichment.js
+++ b/src/features/graph-enrichment.js
@@ -42,8 +42,8 @@ function prepareFunctionLevelData(db, noTests, minConf, cfg) {
       FROM edges e
       JOIN nodes n1 ON e.source_id = n1.id
       JOIN nodes n2 ON e.target_id = n2.id
-      WHERE n1.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module')
-        AND n2.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module')
+      WHERE n1.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'constant')
+        AND n2.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'constant')
         AND e.kind = 'calls'
         AND e.confidence >= ?
     `,
diff --git a/tests/integration/build-parity.test.js b/tests/integration/build-parity.test.js
index 86ef5043..7ca77148 100644
--- a/tests/integration/build-parity.test.js
+++ b/tests/integration/build-parity.test.js
@@ -37,6 +37,9 @@ function readGraph(dbPath) {
   // while WASM correctly limits constant extraction to program-level declarations.
   // TODO: Remove kind != 'constant' exclusion once native binary >= 3.0.4 ships
   // Fix: crates/codegraph-core/src/extractors/javascript.rs (find_parent_of_types guard)
+  // Also exclude 'receiver' edges and method-call 'calls' edges (target contains '.') —
+  // the native engine doesn't emit these for `new Foo()` / `obj.method()` patterns yet.
+  // TODO: Remove receiver/method-call exclusion once native extractor handles call_expression receivers
   const nodes = db
     .prepare(
       "SELECT name, kind, file, line FROM nodes WHERE kind != 'constant' ORDER BY name, kind, file, line",
@@ -49,6 +52,8 @@ function readGraph(dbPath) {
     JOIN nodes n1 ON e.source_id = n1.id
     JOIN nodes n2 ON e.target_id = n2.id
     WHERE n1.kind != 'constant' AND n2.kind != 'constant'
+      AND e.kind != 'receiver'
+      AND NOT (e.kind = 'calls' AND n2.name LIKE '%.%')
     ORDER BY n1.name, n2.name, e.kind
   `)
     .all();
diff --git a/tests/parsers/javascript.test.js b/tests/parsers/javascript.test.js
index 63875fc8..7341d115 100644
--- a/tests/parsers/javascript.test.js
+++ b/tests/parsers/javascript.test.js
@@ -189,4 +189,51 @@ describe('JavaScript parser', () => {
       expect(def.endLine).toBe(4);
     });
   });
+
+  describe('type assignments (receiver type tracking)', () => {
+    it('extracts constructor assignments with confidence 1.0', () => {
+      const symbols = parseJS(`const repo = new UserRepository();`);
+      expect(symbols.typeAssignments).toContainEqual(
+        expect.objectContaining({ variable: 'repo', type: 'UserRepository', confidence: 1.0 }),
+      );
+    });
+
+    it('extracts factory method assignments with confidence 0.7', () => {
+      const symbols = parseJS(`const client = HttpClient.create();`);
+      expect(symbols.typeAssignments).toContainEqual(
+        expect.objectContaining({ variable: 'client', type: 'HttpClient', confidence: 0.7 }),
+      );
+    });
+
+    it('ignores lowercase factory calls (not class names)', () => {
+      const symbols = parseJS(`const result = utils.create();`);
+      expect(symbols.typeAssignments).toHaveLength(0);
+    });
+
+    it('extracts multiple type assignments in same scope', () => {
+      const symbols = parseJS(`
+        const db = new Database();
+        const cache = new RedisCache();
+      `);
+      expect(symbols.typeAssignments).toHaveLength(2);
+      expect(symbols.typeAssignments).toContainEqual(
+        expect.objectContaining({ variable: 'db', type: 'Database', confidence: 1.0 }),
+      );
+      expect(symbols.typeAssignments).toContainEqual(
+        expect.objectContaining({ variable: 'cache', type: 'RedisCache', confidence: 1.0 }),
+      );
+    });
+
+    it('extracts nested type assignments inside functions', () => {
+      const symbols = parseJS(`
+        function init() {
+          const service = new AuthService();
+          service.login();
+        }
+      `);
+      expect(symbols.typeAssignments).toContainEqual(
+        expect.objectContaining({ variable: 'service', type: 'AuthService', confidence: 1.0 }),
+      );
+    });
+  });
 });
diff --git a/tests/unit/resolve.test.js b/tests/unit/resolve.test.js
index d5e487b6..9ca323bd 100644
--- a/tests/unit/resolve.test.js
+++ b/tests/unit/resolve.test.js
@@ -9,11 +9,14 @@ import os from 'node:os';
 import path from 'node:path';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import {
+  clearExportsCache,
   computeConfidence,
   computeConfidenceJS,
   convertAliasesForNative,
+  parseBareSpecifier,
   resolveImportPathJS,
   resolveImportsBatch,
+  resolveViaExports,
 } from '../../src/domain/graph/resolve.js';
 
 // ─── Temp project setup ──────────────────────────────────────────────
@@ -219,3 +222,201 @@ describe('resolveImportsBatch', () => {
     expect(result === null || result instanceof Map).toBe(true);
   });
 });
+
+// ─── parseBareSpecifier ──────────────────────────────────────────────
+
+describe('parseBareSpecifier', () => {
+  it('parses plain package with no subpath', () => {
+    expect(parseBareSpecifier('lodash')).toEqual({ packageName: 'lodash', subpath: '.' });
+  });
+
+  it('parses plain package with subpath', () => {
+    expect(parseBareSpecifier('lodash/fp')).toEqual({ packageName: 'lodash', subpath: './fp' });
+  });
+
+  it('parses scoped package with no subpath', () => {
+    expect(parseBareSpecifier('@scope/pkg')).toEqual({ packageName: '@scope/pkg', subpath: '.' });
+  });
+
+  it('parses scoped package with subpath', () => {
+    expect(parseBareSpecifier('@scope/pkg/utils/deep')).toEqual({
+      packageName: '@scope/pkg',
+      subpath: './utils/deep',
+    });
+  });
+
+  it('returns null for bare @ with no slash', () => {
+    expect(parseBareSpecifier('@scope')).toBeNull();
+  });
+});
+
+// ─── resolveViaExports ───────────────────────────────────────────────
+
+describe('resolveViaExports', () => {
+  let pkgRoot;
+
+  beforeAll(() => {
+    clearExportsCache();
+    // Create a fake node_modules structure inside tmpDir
+    pkgRoot = path.join(tmpDir, 'node_modules', 'test-pkg');
+    fs.mkdirSync(path.join(pkgRoot, 'dist'), { recursive: true });
+    fs.mkdirSync(path.join(pkgRoot, 'lib', 'utils'), { recursive: true });
+    fs.writeFileSync(path.join(pkgRoot, 'dist', 'index.mjs'), 'export default 1;');
+    fs.writeFileSync(path.join(pkgRoot, 'dist', 'index.cjs'), 'module.exports = 1;');
+    fs.writeFileSync(path.join(pkgRoot, 'dist', 'helpers.mjs'), 'export const h = 1;');
+    fs.writeFileSync(path.join(pkgRoot, 'lib', 'utils', 'deep.js'), 'export const d = 1;');
+  });
+
+  afterEach(() => {
+    clearExportsCache();
+  });
+
+  it('resolves string exports (shorthand)', () => {
+    fs.writeFileSync(
+      path.join(pkgRoot, 'package.json'),
+      JSON.stringify({ name: 'test-pkg', exports: './dist/index.mjs' }),
+    );
+    const result = resolveViaExports('test-pkg', tmpDir);
+    expect(result).toBe(path.join(pkgRoot, 'dist', 'index.mjs'));
+  });
+
+  it('returns null for subpath when exports is a string', () => {
+    fs.writeFileSync(
+      path.join(pkgRoot, 'package.json'),
+      JSON.stringify({ name: 'test-pkg', exports: './dist/index.mjs' }),
+    );
+    expect(resolveViaExports('test-pkg/helpers', tmpDir)).toBeNull();
+  });
+
+  it('resolves conditional exports (import/require/default)', () => {
+    fs.writeFileSync(
+      path.join(pkgRoot, 'package.json'),
+      JSON.stringify({
+        name: 'test-pkg',
+        exports: {
+          '.': { import: './dist/index.mjs', require: './dist/index.cjs' },
+        },
+      }),
+    );
+    const result = resolveViaExports('test-pkg', tmpDir);
+    expect(result).toBe(path.join(pkgRoot, 'dist', 'index.mjs'));
+  });
+
+  it('falls back to require when import is absent', () => {
+    fs.writeFileSync(
+      path.join(pkgRoot, 'package.json'),
+      JSON.stringify({
+        name: 'test-pkg',
+        exports: {
+          '.': { require: './dist/index.cjs' },
+        },
+      }),
+    );
+    const result = resolveViaExports('test-pkg', tmpDir);
+    expect(result).toBe(path.join(pkgRoot, 'dist', 'index.cjs'));
+  });
+
+  it('resolves subpath exports', () => {
+    fs.writeFileSync(
+      path.join(pkgRoot, 'package.json'),
+      JSON.stringify({
+        name: 'test-pkg',
+        exports: {
+          '.': './dist/index.mjs',
+          './helpers': './dist/helpers.mjs',
+        },
+      }),
+    );
+    const result = resolveViaExports('test-pkg/helpers', tmpDir);
+    expect(result).toBe(path.join(pkgRoot, 'dist', 'helpers.mjs'));
+  });
+
+  it('resolves subpath patterns with wildcard', () => {
+    fs.writeFileSync(
+      path.join(pkgRoot, 'package.json'),
+      JSON.stringify({
+        name: 'test-pkg',
+        exports: {
+          '.': './dist/index.mjs',
+          './lib/*': './lib/*.js',
+        },
+      }),
+    );
+    const result = resolveViaExports('test-pkg/lib/utils/deep', tmpDir);
+    expect(result).toBe(path.join(pkgRoot, 'lib', 'utils', 'deep.js'));
+  });
+
+  it('resolves conditional subpath exports', () => {
+    fs.writeFileSync(
+      path.join(pkgRoot, 'package.json'),
+      JSON.stringify({
+        name: 'test-pkg',
+        exports: {
+          './helpers': { import: './dist/helpers.mjs', default: './dist/helpers.mjs' },
+        },
+      }),
+    );
+    const result = resolveViaExports('test-pkg/helpers', tmpDir);
+    expect(result).toBe(path.join(pkgRoot, 'dist', 'helpers.mjs'));
+  });
+
+  it('resolves top-level conditions object (no . keys)', () => {
+    fs.writeFileSync(
+      path.join(pkgRoot, 'package.json'),
+      JSON.stringify({
+        name: 'test-pkg',
+        exports: { import: './dist/index.mjs', require: './dist/index.cjs' },
+      }),
+    );
+    const result = resolveViaExports('test-pkg', tmpDir);
+    expect(result).toBe(path.join(pkgRoot, 'dist', 'index.mjs'));
+  });
+
+  it('returns null when exports field is absent', () => {
+    fs.writeFileSync(
+      path.join(pkgRoot, 'package.json'),
+      JSON.stringify({ name: 'test-pkg', main: './dist/index.mjs' }),
+    );
+    expect(resolveViaExports('test-pkg', tmpDir)).toBeNull();
+  });
+
+  it('returns null when package is not in node_modules', () => {
+    expect(resolveViaExports('nonexistent-pkg', tmpDir)).toBeNull();
+  });
+});
+
+// ─── resolveImportPathJS with exports ────────────────────────────────
+
+describe('resolveImportPathJS with package.json exports', () => {
+  let pkgRoot;
+
+  beforeAll(() => {
+    clearExportsCache();
+    pkgRoot = path.join(tmpDir, 'node_modules', 'exports-pkg');
+    fs.mkdirSync(path.join(pkgRoot, 'dist'), { recursive: true });
+    fs.writeFileSync(path.join(pkgRoot, 'dist', 'main.mjs'), 'export default 1;');
+    fs.writeFileSync(
+      path.join(pkgRoot, 'package.json'),
+      JSON.stringify({
+        name: 'exports-pkg',
+        exports: { '.': './dist/main.mjs' },
+      }),
+    );
+  });
+
+  afterEach(() => {
+    clearExportsCache();
+  });
+
+  it('resolves bare specifier through exports field', () => {
+    const fromFile = path.join(tmpDir, 'src', 'index.js');
+    const result = resolveImportPathJS(fromFile, 'exports-pkg', tmpDir, null);
+    expect(result).toContain('node_modules/exports-pkg/dist/main.mjs');
+  });
+
+  it('still passes through bare specifiers without exports', () => {
+    const fromFile = path.join(tmpDir, 'src', 'index.js');
+    const result = resolveImportPathJS(fromFile, 'lodash', tmpDir, null);
+    expect(result).toBe('lodash');
+  });
+});

From acee01f6653e52bc0c2eecc06561409258847ce2 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sat, 21 Mar 2026 19:25:18 -0600
Subject: [PATCH 15/52] Revert "chore: checkpoint stale working tree changes
 from prior sessions"

This reverts commit a296b58ffdb17aba6ff9f20851ad060b7f00ff52.
---
 .claude/skills/architect/SKILL.md             | 140 -----
 docs/roadmap/ROADMAP.md                       | 488 +++++++-----------
 generated/competitive/COMPETITIVE_ANALYSIS.md | 254 +++++----
 generated/competitive/joern.md                |  53 +-
 generated/competitive/narsil-mcp.md           |  77 ++-
 generated/dogfood/DOGFOOD_REPORT_v3.1.2.md    | 395 ++++++++++++++
 package-lock.json                             |   9 +
 scripts/benchmark.js                          | 307 ++++++-----
 scripts/embedding-benchmark.js                | 194 +++----
 scripts/incremental-benchmark.js              | 319 ++++++------
 scripts/lib/fork-engine.js                    | 163 ------
 scripts/query-benchmark.js                    | 182 ++++---
 src/domain/analysis/context.js                |   2 +-
 .../graph/builder/stages/build-edges.js       | 102 +---
 src/domain/graph/resolve.js                   | 196 +------
 src/domain/graph/watcher.js                   |   4 +-
 src/extractors/go.js                          | 134 +----
 src/extractors/javascript.js                  | 124 +----
 src/extractors/python.js                      |  81 +--
 src/features/export.js                        |   6 +-
 src/features/graph-enrichment.js              |   4 +-
 tests/integration/build-parity.test.js        |   5 -
 tests/parsers/javascript.test.js              |  47 --
 tests/unit/resolve.test.js                    | 201 --------
 24 files changed, 1310 insertions(+), 2177 deletions(-)
 delete mode 100644 .claude/skills/architect/SKILL.md
 create mode 100644 generated/dogfood/DOGFOOD_REPORT_v3.1.2.md
 delete mode 100644 scripts/lib/fork-engine.js

diff --git a/.claude/skills/architect/SKILL.md b/.claude/skills/architect/SKILL.md
deleted file mode 100644
index badf9ea8..00000000
--- a/.claude/skills/architect/SKILL.md
+++ /dev/null
@@ -1,140 +0,0 @@
-# /architect — Full Architectural Audit
-
-Run a cold, harsh architectural audit of codegraph. Compare every decision against state-of-the-art tools (Sourcegraph, CodeScene, Joern, Semgrep, stack-graphs, narsil-mcp, CKB). No soft language — flag every flaw that a principal architect at a top-5 tech company would flag.
-
-## Output
-
-**Filename:** `ARCHITECTURE_AUDIT_v{VERSION}_{DATE}.md`
-- `{VERSION}` = current `package.json` version (e.g., `3.1.4`)
-- `{DATE}` = today's date in `YYYY-MM-DD` format (e.g., `2026-03-16`)
-
-**Saved to two locations:**
-1. `docs/architecture/ARCHITECTURE_AUDIT_v{VERSION}_{DATE}.md` — canonical, committed to git
-2. `generated/architecture/ARCHITECTURE_AUDIT_v{VERSION}_{DATE}.md` — working copy
-
-**Header format:**
-```markdown
-# Codegraph Architectural Audit
-
-**Date:** {DATE}
-**Version audited:** v{VERSION} (`@optave/codegraph@{VERSION}`)
-**Commit:** {SHORT_SHA} ({branch name})
-**Auditor perspective:** Principal architect, cold evaluation
-**Methodology:** Codegraph self-analysis + manual source review + verified competitor research
-**Previous audit:** {link to previous audit if exists, or "First audit"}
-```
-
-Before writing, check `docs/architecture/` for previous audits. Reference changes since the last audit where relevant.
-
-## Steps
-
-### Phase 0 — Setup
-1. Read `package.json` to get the current version
-2. Get the current date, commit SHA, and branch name
-3. Check `docs/architecture/` for previous audit files
-4. **Read all ADRs in `docs/architecture/decisions/`.** These are the project's settled architectural decisions. Read every file — they document rationale, trade-offs, alternatives considered, and trajectory. The audit must evaluate the codebase *against* these decisions: are they being followed? Are the stated trade-offs still accurate? Has anything changed that invalidates the rationale?
-5. Run `codegraph build --no-incremental` to ensure fresh metrics
-
-### Phase 1 — Structural Census
-1. Run `codegraph stats` to get graph health baseline
-2. Run `codegraph structure --depth 3` to get directory cohesion
-3. Run `codegraph triage -T` to get the risk priority queue
-4. Run `codegraph roles --role dead -T` to find dead code — **then break down by kind** (function/method vs parameter/property/constant) to avoid inflating the dead count with leaf nodes
-5. Run `codegraph cycles` to check for circular dependencies
-6. Run `codegraph map` to see the module overview
-7. Run `codegraph complexity -T --limit 25` to find the most complex functions
-8. Count files, LOC, and test-to-source ratio
-
-### Phase 2 — Layer-by-Layer Critique
-For each architectural layer, evaluate against these dimensions:
-
-**A. Abstraction Quality**
-- Is the abstraction boundary clean or leaky?
-- Are there god objects / god files (>500 LOC)?
-- Is there needless indirection (wrappers that add no value)?
-
-**B. Coupling & Cohesion**
-- Fan-in / fan-out analysis per module
-- Are features truly independent or secretly coupled?
-- Is shared state minimized?
-
-**C. State-of-the-Art Comparison**
-- How does this layer compare to the equivalent in Sourcegraph, CodeScene, Joern, Semgrep, narsil-mcp, CKB?
-- What would a $500M code intelligence company do differently?
-- What academic research (ICSE, FSE, ASE) contradicts the design choices?
-
-**D. Scalability & Performance**
-- Will this hold up at 1M LOC? 10M LOC? Monorepo scale?
-- What are the algorithmic bottlenecks?
-- Is the database schema suitable for scale?
-
-**E. Correctness & Soundness**
-- Is the analysis sound or best-effort? (Be explicit)
-- What false positives / negatives does the approach inherently produce?
-- Where does the tool present incomplete data as complete?
-
-**F. ADR Compliance**
-- Does the implementation match the decisions documented in `docs/architecture/decisions/`?
-- Are the trade-offs described in ADRs still accurate given the current code?
-- Has the codebase drifted from any stated trajectory? If so, is that drift justified or accidental?
-- Are there architectural decisions that *should* have an ADR but don't?
-
-### Phase 3 — Cross-Cutting Concerns
-
-Evaluate these across the entire codebase:
-
-1. **Type Safety** — JS without TypeScript in 2026. Cost-benefit.
-2. **Error Handling** — Is it consistent? Are errors recoverable? Domain errors vs crashes.
-3. **Testing Strategy** — Are the right things tested? Integration-heavy vs unit-heavy tradeoffs.
-4. **Dual Engine Maintenance** — JS + Rust doing the same thing. Is this sustainable?
-5. **Dependency Hygiene** — Are deps minimal? Are there vendoring risks?
-6. **Security Surface** — execFileSync, MCP server exposure, SQLite injection vectors.
-7. **API Design** — Is the programmatic API well-designed for embedding?
-8. **Documentation** — Is it accurate? Does it lie by omission?
-
-### Phase 4 — Competitive Verification
-
-**Do not trust README claims.** For each top competitor:
-1. Fetch the actual GitHub repo README
-2. Cross-check feature claims against source code where possible
-3. Note: MCP-only vs CLI? Open source vs commercial? External deps required? Deterministic vs LLM-mediated?
-
-Include a verified competitor comparison table with columns: MCP tools, CLI, Open source, Zero-dep, Deterministic, Incremental (all langs).
-
-### Phase 5 — Strategic Verdict
-
-1. **Does codegraph have a reason to exist?** — Answer with verified data, not assumptions
-2. **Fundamental Design Flaws** — Decisions that cannot be fixed incrementally
-3. **Missed Opportunities** — What the tool should have been but isn't
-4. **Competitive Moat Assessment** — What actually differentiates this? Is it defensible?
-5. **Kill List** — Features/code that should be deleted, not improved
-6. **Build vs Buy** — Components that should use existing libraries instead of custom code
-7. **Roadmap Critique** — Is the planned roadmap the right path? What's missing? What's wrong?
-
-### Phase 6 — Write & Save
-
-1. Write the full audit to `docs/architecture/ARCHITECTURE_AUDIT_v{VERSION}_{DATE}.md`
-2. Copy to `generated/architecture/ARCHITECTURE_AUDIT_v{VERSION}_{DATE}.md`
-3. If a previous audit exists, add a "Changes Since Last Audit" section at the end comparing key metrics (graph quality score, complexity stats, dead code counts, competitive position)
-
-## Audit Structure
-
-The deliverable must contain:
-- "Does Codegraph Have a Reason to Exist?" section (verified competitor data)
-- Executive summary (1 paragraph, brutally honest)
-- Scorecard (each dimension rated 1-10 with justification)
-- **ADR compliance review** — for each ADR in `docs/architecture/decisions/`, assess whether the codebase follows the decision, whether the stated trade-offs are still valid, and whether any drift has occurred. Flag missing ADRs for decisions that exist in code but aren't documented
-- Detailed findings per layer
-- Verified competitor comparison table
-- Strategic recommendations (prioritized)
-- Comparison matrix vs state-of-the-art
-- Final verdict: would you invest in this project? Why or why not?
-
-## Rules
-- **No softening.** If something is bad, say it's bad and say why.
-- **Cite specifics.** File names, line counts, function names — not vague handwaving.
-- **Compare to real tools.** Not hypotheticals — actual production systems.
-- **Verify competitor claims.** Fetch READMEs, check source. Do not trust competitive analysis at face value.
-- **Quantify everything.** LOC, fan-in, complexity scores, not "high" or "low".
-- **Break down "dead" stats.** Separate leaf nodes (parameters, properties, constants) from genuinely unreferenced callables. Further categorize callable dead code by cause (Rust FFI, framework entry, dynamic dispatch, genuine dead).
-- **Assume the audience is a principal engineer** who has seen 100+ codebases.
diff --git a/docs/roadmap/ROADMAP.md b/docs/roadmap/ROADMAP.md
index d195a97f..3f0c2abe 100644
--- a/docs/roadmap/ROADMAP.md
+++ b/docs/roadmap/ROADMAP.md
@@ -16,16 +16,15 @@ Codegraph is a strong local-first code graph CLI. This roadmap describes planned
 | [**2**](#phase-2--foundation-hardening) | Foundation Hardening | Parser registry, complete MCP, test coverage, enhanced config, multi-repo MCP | **Complete** (v1.5.0) |
 | [**2.5**](#phase-25--analysis-expansion) | Analysis Expansion | Complexity metrics, community detection, flow tracing, co-change, manifesto, boundary rules, check, triage, audit, batch, hybrid search | **Complete** (v2.7.0) |
 | [**2.7**](#phase-27--deep-analysis--graph-enrichment) | Deep Analysis & Graph Enrichment | Dataflow analysis, intraprocedural CFG, AST node storage, expanded node/edge types, extractors refactoring, CLI consolidation, interactive viewer, exports command, normalizeSymbol | **Complete** (v3.0.0) |
-| [**3**](#phase-3--architectural-refactoring) | Architectural Refactoring (Vertical Slice) | Unified AST analysis framework, command/query separation, repository pattern, queries.js decomposition, composable MCP, CLI commands, domain errors, builder pipeline, presentation layer, domain grouping, curated API, unified graph model, qualified names, CLI composability | **Complete** (v3.1.4) |
-| [**4**](#phase-4--typescript-migration) | TypeScript Migration | Project setup, core type definitions, leaf -> core -> orchestration module migration, test migration, supply-chain security, CI coverage gates | Planned |
-| [**5**](#phase-5--architectural-hardening) | Architectural Hardening | Method dispatch resolution, dead role sub-classification, SCIP/LSP integration for TS/Python/Go, DB schema hardening, graph model consolidation, auto-generated MCP schemas, precision benchmark suite | **In Progress** (5.1 phase 1 complete) |
-| [**6**](#phase-6--native-analysis-acceleration) | Native Analysis Acceleration | Move JS-only build phases (AST nodes, CFG, dataflow, insert nodes, structure, roles, complexity) to Rust; fix incremental rebuild data loss on native; sub-100ms 1-file rebuilds | Planned |
-| [**7**](#phase-7--runtime--extensibility) | Runtime & Extensibility | Event-driven pipeline, unified engine strategy, subgraph export filtering, transitive confidence, query caching, configuration profiles, pagination, plugin system, DX & onboarding | Planned |
-| [**8**](#phase-8--intelligent-embeddings) | Intelligent Embeddings | LLM-generated descriptions, enhanced embeddings, build-time semantic metadata, module summaries | Planned |
-| [**9**](#phase-9--natural-language-queries) | Natural Language Queries | `ask` command, conversational sessions, LLM-narrated graph queries, onboarding tools | Planned |
-| [**10**](#phase-10--expanded-language-support) | Expanded Language Support | Deep resolution for TS/Python/Go (via SCIP), tree-sitter fallback for remaining + 5 new languages (11 -> 16) | Planned |
-| [**11**](#phase-11--github-integration--ci) | GitHub Integration & CI | Reusable GitHub Action, LLM-enhanced PR review, visual impact graphs, SARIF output | Planned |
-| [**12**](#phase-12--interactive-visualization--advanced-features) | Visualization & Advanced | VS Code extension, dead code detection, monorepo, agentic search, refactoring analysis | Planned |
+| [**3**](#phase-3--architectural-refactoring) | Architectural Refactoring (Vertical Slice) | Unified AST analysis framework, command/query separation, repository pattern, queries.js decomposition, composable MCP, CLI commands, domain errors, builder pipeline, presentation layer, domain grouping, curated API, unified graph model, qualified names, CLI composability | **In Progress** (v3.1.4) |
+| [**4**](#phase-4--native-analysis-acceleration) | Native Analysis Acceleration | Move JS-only build phases (AST nodes, CFG, dataflow, insert nodes, structure, roles, complexity) to Rust; fix incremental rebuild data loss on native; sub-100ms 1-file rebuilds | Planned |
+| [**5**](#phase-5--typescript-migration) | TypeScript Migration | Project setup, core type definitions, leaf -> core -> orchestration module migration, test migration, supply-chain security, CI coverage gates | Planned |
+| [**6**](#phase-6--runtime--extensibility) | Runtime & Extensibility | Event-driven pipeline, unified engine strategy, subgraph export filtering, transitive confidence, query caching, configuration profiles, pagination, plugin system, DX & onboarding | Planned |
+| [**7**](#phase-7--intelligent-embeddings) | Intelligent Embeddings | LLM-generated descriptions, enhanced embeddings, build-time semantic metadata, module summaries | Planned |
+| [**8**](#phase-8--natural-language-queries) | Natural Language Queries | `ask` command, conversational sessions, LLM-narrated graph queries, onboarding tools | Planned |
+| [**9**](#phase-9--expanded-language-support) | Expanded Language Support | 8 new languages (11 -> 19), parser utilities | Planned |
+| [**10**](#phase-10--github-integration--ci) | GitHub Integration & CI | Reusable GitHub Action, LLM-enhanced PR review, visual impact graphs, SARIF output | Planned |
+| [**11**](#phase-11--interactive-visualization--advanced-features) | Visualization & Advanced | Web UI, dead code detection, monorepo, agentic search, refactoring analysis | Planned |
 
 ### Dependency graph
 
@@ -35,17 +34,15 @@ Phase 1 (Rust Core)
          |-->  Phase 2.5 (Analysis Expansion)
                 |-->  Phase 2.7 (Deep Analysis & Graph Enrichment)
                        |-->  Phase 3 (Architectural Refactoring)
-                              |-->  Phase 4 (TypeScript Migration)
-                                     |-->  Phase 5 (Architectural Hardening)
-                                            |-->  Phase 6 (Native Analysis Acceleration)
-                                                   |-->  Phase 7 (Runtime & Extensibility)
-                                                   |-->  Phase 8 (Embeddings + Metadata)  -->  Phase 9 (NL Queries)
-                                                   |-->  Phase 10 (Languages) <-- Phase 5 (SCIP/LSP)
-                                                   |-->  Phase 11 (GitHub/CI) <-- Phase 8 (risk_score, side_effects)
-Phases 1-9 -->  Phase 12 (Visualization + Refactoring Analysis)
+                              |-->  Phase 4 (Native Analysis Acceleration)
+                                     |-->  Phase 5 (TypeScript Migration)
+                                            |-->  Phase 6 (Runtime & Extensibility)
+                                            |-->  Phase 7 (Embeddings + Metadata)  -->  Phase 8 (NL Queries + Narration)
+                                            |-->  Phase 9 (Languages)
+                                            |-->  Phase 10 (GitHub/CI) <-- Phase 7 (risk_score, side_effects)
+Phases 1-8 -->  Phase 11 (Visualization + Refactoring Analysis)
 ```
 
-
 ---
 
 ## Phase 1 -- Rust Core ✅
@@ -114,7 +111,6 @@ Ensure the transition is seamless.
 
 **Result:** Zero breaking changes. Users get faster parsing automatically; nothing else changes.
 
-
 ---
 
 ## Phase 2 -- Foundation Hardening ✅
@@ -201,7 +197,6 @@ Support querying multiple codebases from a single MCP server instance.
 **New files:** `src/registry.js`
 **Affected files:** `src/mcp.js`, `src/cli.js`, `src/builder.js`, `src/index.js`
 
-
 ---
 
 ## Phase 2.5 -- Analysis Expansion ✅
@@ -364,7 +359,6 @@ MCP grew from 12 -> 25 tools, covering all new analysis capabilities.
 
 **Affected file:** `src/mcp.js` (grew from 354 -> 1,212 lines)
 
-
 ---
 
 ## Phase 2.7 -- Deep Analysis & Graph Enrichment ✅
@@ -560,12 +554,11 @@ Plus updated enums on existing tools (edge_kinds, symbol kinds).
 | Edge kinds | 6 | 9 | +3 |
 | Test files | 59 | 70 | +11 |
 
-
 ---
 
-## Phase 3 -- Architectural Refactoring ✅
+## Phase 3 -- Architectural Refactoring 🔄
 
-> **Status:** Complete -- shipped in v3.1.4
+> **Status:** In Progress -- started in v3.1.1
 
 **Goal:** Restructure the codebase for modularity, testability, and long-term maintainability. These are internal improvements -- no new user-facing features, but they make every subsequent phase easier to build and maintain.
 
@@ -998,16 +991,128 @@ Practical cleanup to make the CLI surface match the internal composability that
 
 **Affected files:** `src/cli/commands/*.js`, `src/cli/shared/`, `src/presentation/result-formatter.js`
 
+---
+
+## Phase 4 -- Native Analysis Acceleration
+
+**Goal:** Move the remaining JS-only build phases to Rust so that `--engine native` eliminates all redundant WASM visitor walks. Today only 3 of 10 build phases (parse, resolve imports, build edges) run in Rust — the other 7 execute identical JavaScript regardless of engine, leaving ~50% of native build time on the table.
+
+**Why its own phase:** This is a substantial Rust engineering effort — porting 6 JS visitors to `crates/codegraph-core/`, fixing a data loss bug in incremental rebuilds, and optimizing the 1-file rebuild path. Doing this before the TS migration avoids rewriting the same visitor code twice (once to TS, once to Rust). The Phase 3 module boundaries make each phase a self-contained target.
+
+**Evidence (v3.1.4 benchmarks on 398 files):**
+
+| Phase | Native | WASM | Ratio | Status |
+|-------|-------:|-----:|------:|--------|
+| Parse | 468ms | 1483ms | 3.2x faster | Already Rust |
+| Build edges | 88ms | 152ms | 1.7x faster | Already Rust |
+| Resolve imports | 8ms | 9ms | ~1x | Already Rust |
+| **AST nodes** | **361ms** | **347ms** | **~1x** | JS visitor — biggest win |
+| **CFG** | **126ms** | **125ms** | **~1x** | JS visitor |
+| **Dataflow** | **100ms** | **98ms** | **~1x** | JS visitor |
+| **Insert nodes** | **143ms** | **148ms** | **~1x** | Pure SQLite batching |
+| **Roles** | **29ms** | **32ms** | **~1x** | JS classification |
+| **Structure** | **13ms** | **17ms** | **~1x** | JS directory tree |
+| Complexity | 16ms | 77ms | 5x faster | Partly pre-computed |
+
+**Target:** Reduce native full-build time from ~1,400ms to ~700ms (2x improvement) by eliminating ~690ms of redundant JS visitor work.
+
+### 4.1 -- AST Node Extraction in Rust
+
+The largest single opportunity. Currently the native parser returns partial AST node data, so the JS `buildAstNodes()` visitor re-walks all WASM trees anyway (~361ms).
+
+- Extend `crates/codegraph-core/` to extract all AST node types (`call`, `new`, `string`, `regex`, `throw`, `await`) during the native parse phase
+- Return complete AST node data in the `FileSymbols` result so `run-analyses.js` can skip the WASM walker entirely
+- Validate parity: ensure native extraction produces identical node counts to the WASM visitor (benchmark already tracks this via `nodes/file`)
+
+**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/ast.js`, `src/domain/graph/builder/stages/run-analyses.js`
+
+### 4.2 -- CFG Construction in Rust
+
+The intraprocedural control-flow graph visitor runs in JS even on native builds (~126ms).
+
+- Port `createCfgVisitor()` logic to Rust: basic block detection, branch/loop edges, entry/exit nodes
+- Return CFG block data per function in `FileSymbols` so the JS visitor is fully bypassed
+- Validate parity: CFG block counts and edge counts must match the WASM visitor output
+
+**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/cfg.js`, `src/ast-analysis/visitors/cfg-visitor.js`
+
+### 4.3 -- Dataflow Analysis in Rust
+
+Dataflow edges are computed by a JS visitor that walks WASM trees (~100ms on native builds).
+
+- Port `createDataflowVisitor()` to Rust: variable definitions, assignments, reads, def-use chains
+- Return dataflow edges in `FileSymbols`
+- Validate parity against WASM visitor output
+
+**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/dataflow.js`, `src/ast-analysis/visitors/dataflow-visitor.js`
+
+### 4.4 -- Batch SQLite Inserts via Rust
+
+`insertNodes` is pure SQLite work (~143ms) but runs row-by-row from JS. Batching in Rust can reduce JS↔native boundary crossings.
+
+- Expose a `batchInsertNodes(nodes[])` function from Rust that uses a single prepared statement in a transaction
+- Alternatively, generate the SQL batch on the JS side and execute as a single `better-sqlite3` call (may be sufficient without Rust)
+- Benchmark both approaches; pick whichever is faster
+
+**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/db/index.js`, `src/domain/graph/builder/stages/insert-nodes.js`
+
+### 4.5 -- Role Classification & Structure in Rust
+
+Smaller wins (~42ms combined) but complete the picture of a fully native build pipeline.
+
+- Port `classifyNodeRoles()` to Rust: hub/leaf/bridge/utility classification based on in/out degree and betweenness
+- Port directory structure building and metrics aggregation
+- Return role assignments and structure data alongside parse results
+
+**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/structure.js`, `src/domain/graph/builder/stages/build-structure.js`
+
+### 4.6 -- Complete Complexity Pre-computation
+
+Complexity is partly pre-computed by native (~16ms vs 77ms WASM) but not all functions are covered.
+
+- Ensure native parse computes cognitive, cyclomatic, Halstead, and MI metrics for every function, not just a subset
+- Eliminate the WASM fallback path in `buildComplexityMetrics()` when running native
+
+**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/complexity.js`
+
+### 4.7 -- Fix Incremental Rebuild Data Loss on Native Engine
+
+**Bug:** On native 1-file rebuilds, complexity, CFG, and dataflow data for the changed file is **silently lost**. `purgeFilesFromGraph` removes the old data, but the analysis phases never re-compute it because:
+
+1. The native parser does not produce a `_tree` (WASM tree-sitter tree)
+2. The unified walker at `src/ast-analysis/engine.js:108-109` skips files without `_tree`
+3. The `buildXxx` functions check for pre-computed fields (`d.complexity`, `d.cfg?.blocks`) which the native parser does not provide for these analyses
+4. Result: 0.1ms no-op — the phases run but do nothing
+
+This is confirmed by the v3.1.4 1-file rebuild data: complexity (0.1ms), CFG (0.1ms), dataflow (0.2ms) on native — these are just module import overhead, not actual computation. Contrast with v3.1.3 where the numbers were higher (1.3ms, 8.7ms, 4ms) because earlier versions triggered a WASM fallback tree via `ensureWasmTrees`.
+
+**Fix (prerequisite: 4.1–4.3):** Once the native parser returns complete AST nodes, CFG blocks, and dataflow edges in `FileSymbols`, the `run-analyses` stage can store them directly without needing a WASM tree. The incremental path must:
+
+- Ensure `parseFilesAuto()` returns pre-computed analysis data for the single changed file
+- Have `run-analyses.js` store that data (currently it only stores if `_tree` exists or if pre-computed fields are present — the latter path needs to work reliably)
+- Add an integration test: rebuild 1 file on native engine, then query its complexity/CFG/dataflow and assert non-empty results
+
+**Affected files:** `src/ast-analysis/engine.js`, `src/domain/graph/builder/stages/run-analyses.js`, `src/domain/parser.js`, `tests/integration/`
+
+### 4.8 -- Incremental Rebuild Performance
+
+With analysis data loss fixed, optimize the 1-file rebuild path end-to-end. Current native 1-file rebuild is 265ms — dominated by parse (51ms), structure (13ms), roles (27ms), edges (13ms), insert (12ms), and finalize (12ms).
+
+- **Skip unchanged phases:** Structure and roles are graph-wide computations. On a 1-file change, only the changed file's nodes/edges need updating — skip full reclassification unless the file's degree changed significantly
+- **Incremental edge rebuild:** Only rebuild edges involving the changed file's symbols, not the full edge set
+- **Benchmark target:** Sub-100ms native 1-file rebuilds (from current 265ms)
+
+**Affected files:** `src/domain/graph/builder/stages/build-structure.js`, `src/domain/graph/builder/stages/build-edges.js`, `src/domain/graph/builder/pipeline.js`
 
 ---
 
-## Phase 4 -- TypeScript Migration
+## Phase 5 -- TypeScript Migration
 
 **Goal:** Migrate the codebase from plain JavaScript to TypeScript, leveraging the clean module boundaries established in Phase 3. Incremental module-by-module migration starting from leaf modules inward.
 
-**Why now (before Native Acceleration):** The architectural audit (v3.1.4) identified type safety as the highest-leverage improvement. TypeScript provides typed interfaces that define exactly what the Rust native engine must return — porting to Rust before having those contracts means building against untyped, shifting interfaces. TypeScript also catches the class of bugs that currently require runtime discovery (wrong argument order, missing properties, implicit any).
+**Why after Phase 4:** The architectural refactoring (Phase 3) creates small, well-bounded modules with explicit interfaces. Phase 4 moves the remaining hot-path visitor code to Rust — doing TS migration first would mean rewriting those visitors to TypeScript only to delete them when porting to Rust. With both phases complete, the JS layer is purely orchestration and presentation, which is the ideal surface for TypeScript.
 
-### 4.1 -- Project Setup
+### 5.1 -- Project Setup
 
 - Add `typescript` as a devDependency
 - Create `tsconfig.json` with strict mode, ES module output, path aliases matching the Phase 3 module structure
@@ -1018,7 +1123,7 @@ Practical cleanup to make the CLI surface match the internal composability that
 
 **Affected files:** `package.json`, `biome.json`, new `tsconfig.json`
 
-### 4.2 -- Core Type Definitions
+### 5.2 -- Core Type Definitions
 
 Define TypeScript interfaces for all abstractions introduced in Phase 3:
 
@@ -1046,7 +1151,7 @@ These interfaces serve as the migration contract -- each module is migrated to s
 
 **New file:** `src/types.ts`
 
-### 4.3 -- Leaf Module Migration
+### 5.3 -- Leaf Module Migration
 
 Migrate modules with no internal dependencies first:
 
@@ -1063,7 +1168,7 @@ Migrate modules with no internal dependencies first:
 
 Allow `.js` and `.ts` to coexist during migration (`allowJs: true` in tsconfig).
 
-### 4.4 -- Core Module Migration
+### 5.4 -- Core Module Migration
 
 Migrate modules that implement Phase 3 interfaces:
 
@@ -1078,7 +1183,7 @@ Migrate modules that implement Phase 3 interfaces:
 | `src/analysis/*.ts` | Typed analysis results (impact scores, call chains) |
 | `src/resolve.ts` | Import resolution with confidence types |
 
-### 4.5 -- Orchestration & Public API Migration
+### 5.5 -- Orchestration & Public API Migration
 
 Migrate top-level orchestration and entry points:
 
@@ -1091,7 +1196,7 @@ Migrate top-level orchestration and entry points:
 | `src/cli/*.ts` | Command objects with typed options |
 | `src/index.ts` | Curated public API with proper export types |
 
-### 4.6 -- Test Migration
+### 5.6 -- Test Migration
 
 - Migrate test files from `.js` to `.ts`
 - Add type-safe test utilities and fixture builders
@@ -1102,7 +1207,7 @@ Migrate top-level orchestration and entry points:
 
 **Affected files:** All `src/**/*.js` -> `src/**/*.ts`, all `tests/**/*.js` -> `tests/**/*.ts`, `package.json`, `biome.json`
 
-### 4.7 -- Supply-Chain Security & Audit
+### 5.7 -- Supply-Chain Security & Audit
 
 **Gap:** No `npm audit` in CI pipeline. No supply-chain attestation (SLSA/SBOM). No formal security audit history.
 
@@ -1115,248 +1220,33 @@ Migrate top-level orchestration and entry points:
 
 **Affected files:** `.github/workflows/ci.yml`, `.github/workflows/publish.yml`, `docs/security/`
 
-### 4.8 -- CI Test Quality & Coverage Gates
+### 5.8 -- CI Test Quality & Coverage Gates
 
 **Gaps:**
 
 - No coverage thresholds enforced in CI (coverage report runs locally only)
 - Embedding tests in separate workflow requiring HuggingFace token
 - 312 `setTimeout`/`sleep` instances in tests — potential flakiness under load
-- No dependency audit step in CI (see also [4.7](#47----supply-chain-security--audit))
+- No dependency audit step in CI (see also [5.7](#57----supply-chain-security--audit))
 
 **Deliverables:**
 
 1. **Coverage gate** -- add `vitest --coverage` to CI with minimum threshold (e.g. 80% lines/branches); fail the pipeline when coverage drops below the threshold
 2. **Unified test workflow** -- merge embedding tests into the main CI workflow using a securely stored `HF_TOKEN` secret; eliminate the separate workflow
 3. **Timer cleanup** -- audit and reduce `setTimeout`/`sleep` usage in tests; replace with deterministic waits (event-based, polling with backoff, or `vi.useFakeTimers()`) to reduce flakiness
-4. > _Dependency audit step is covered by [4.7](#47----supply-chain-security--audit) deliverable 1._
+4. > _Dependency audit step is covered by [5.7](#57----supply-chain-security--audit) deliverable 1._
 
 **Affected files:** `.github/workflows/ci.yml`, `vitest.config.js`, `tests/`
 
-
----
-
-## Phase 5 -- Architectural Hardening
-
-**Goal:** Close the correctness and precision gaps identified in the v3.1.4 architectural audit before investing in performance (Native Acceleration) or new features. These are the structural fixes that make every subsequent phase more reliable.
-
-**Why now:** The audit found ~73-80% static call resolution, method dispatch as the primary gap, and 509 genuinely unreferenced callable symbols (many explainable by Rust FFI, framework entries, and dynamic dispatch). Fixing these before native acceleration means the Rust engine has clear, typed contracts to implement. Fixing before new features means those features build on accurate data.
-
-### 5.1 -- Method Dispatch Resolution
-
-The biggest call graph gap. Previously, `obj.method()` calls resolved to ANY exported method in scope — no receiver type tracking. Repository pattern calls (`this.repo.find()`), builder chains, and interface-dispatched methods were missed entirely.
-
-**Phase 1 (receiver type tracking) — Complete:**
-- ✅ Per-file type map built from variable-to-type assignments during extraction
-- ✅ Constructor assignments: `const x = new Foo()` → `x.method()` resolves to `Foo.method` (confidence 1.0)
-- ✅ Type annotations (TS): `const x: Foo = ...` → confidence 0.9
-- ✅ Factory methods: `const x = Foo.create()` → confidence 0.7 (uppercase-first heuristic)
-- ✅ Go patterns: composite literals (`x := Foo{}`), var declarations (`var x Foo`), `NewFoo()` factories
-- ✅ Python patterns: constructor calls (`x = Foo()`), type annotations (`x: Foo = ...`), factory calls
-- ✅ Type map used for both call edge resolution (qualified `ClassName.method` lookup) and receiver edge precision
-- ✅ Extractors: JS/TS, Python, Go all return `typeAssignments`; edge builder consumes them; native engine path forwards them
-
-**Phase 2 (remaining — planned):**
-- Handle `this.field` tracking within class bodies (`this.service = new AuthService()` in constructor)
-- Builder chain resolution (fluent API patterns where each method returns `this`)
-- Interface-dispatched methods (variable typed as interface, resolve to all implementing methods)
-- **Target:** Improve call resolution from ~80% to ~90%+ for static JS/TS codebases
-
-**Affected files:** `src/extractors/javascript.js`, `src/extractors/python.js`, `src/extractors/go.js`, `src/domain/graph/builder/stages/build-edges.js`
-
-### 5.2 -- Dead Role Sub-Classification
-
-The audit showed 3,408 "dead" symbols but 2,899 are leaf nodes (parameters, properties, constants) — not resolution failures. The remaining 509 callable dead symbols break down into Rust FFI exports (151), framework entry points (94), dynamic dispatch targets (170+), and genuinely dead code (~94).
-
-- Sub-classify dead symbols: `dead:leaf`, `dead:ffi`, `dead:entry`, `dead:dynamic`, `dead:genuine`
-- Use heuristics: exported from `crates/` → FFI, decorated with framework markers → entry, has no static callers but is a method on a class with callers → dynamic
-- `codegraph roles --role dead` shows the breakdown by sub-class
-- `codegraph roles --role dead:genuine` filters to only genuinely unreferenced code
-- Update MCP `node_roles` tool to support sub-classification
-
-**Affected files:** `src/graph/classifiers/role-classifier.js`, `src/domain/analysis/roles.js`
-
-### 5.3 -- SCIP/LSP Integration for TS/Python/Go
-
-For languages with mature SCIP indexers (TypeScript via scip-typescript, Python via scip-python, Go via scip-go), use SCIP index data to get precise cross-reference resolution instead of heuristic matching.
-
-- Detect if a SCIP index (`.scip` file) exists in the project root
-- Parse SCIP occurrences to build a precise symbol → definition → reference map
-- Use SCIP data as the highest-priority resolution source (confidence 1.0), falling back to tree-sitter heuristics when unavailable
-- `codegraph build --scip <path>` to explicitly provide a SCIP index
-- Document how to generate SCIP indexes for each supported language
-
-**Affected files:** `src/domain/graph/resolve.js`, new `src/infrastructure/scip.js`
-
-### 5.4 -- DB Schema Hardening
-
-The audit flagged missing foreign keys, no WAL mode, and no index coverage analysis.
-
-- Enable WAL mode by default for concurrent read access (MCP sessions reading while builds write)
-- Add foreign key constraints (`edges.source` → `nodes.id`, `edges.target` → `nodes.id`) with `ON DELETE CASCADE`
-- Add covering indexes for the most common query patterns (identified via `EXPLAIN QUERY PLAN` on top 10 queries)
-- Add `PRAGMA integrity_check` to `codegraph check` command
-- Migration path: new schema version with `ALTER TABLE` for existing databases
-
-**Affected files:** `src/db/migrations.js`, `src/db/connection.js`
-
-### 5.5 -- Graph Model Consolidation
-
-`src/graph/model.js` (230 LOC) reimplements `addNode`, `addEdge`, `successors`, `predecessors` that `graphology` (already a dependency) provides natively. This is pure maintenance cost with no benefit.
-
-- Replace `CodeGraph` internals with `graphology` as the backing store
-- Keep the `CodeGraph` public API unchanged (or simplify it to delegate directly)
-- Eliminate the custom adjacency list, the manual `_inEdges`/`_outEdges` maps
-- `toGraphology()` becomes a no-op (returns `this._graph`)
-- Benchmark: ensure no regression in graph algorithm performance
-
-**Affected files:** `src/graph/model.js`
-
-### 5.6 -- Auto-Generated MCP Schemas
-
-MCP tool schemas are currently hand-maintained JSON objects. When a CLI command adds a parameter, the MCP schema must be manually updated — a common source of drift.
-
-- Generate MCP tool `inputSchema` from the Commander option definitions in `src/cli.js`
-- Single source of truth: CLI defines parameters, MCP schemas are derived
-- Validate at startup: MCP schema matches CLI options (fail-fast on drift)
-
-**Affected files:** `src/mcp/`, `src/cli.js`
-
-### 5.7 -- Precision Benchmark Suite
-
-The audit revealed that call resolution accuracy (~73-80%) is asserted by manual spot-checks, not automated benchmarks. Without a benchmark suite, regressions in resolution quality go undetected.
-
-- Create a benchmark fixture with known call graphs (manually verified ground truth)
-- Measure: precision (% of reported edges that are correct), recall (% of real edges that are found)
-- Track per-language: JS, TS, Python, Go, Rust, Java
-- Run in CI: fail if precision drops below threshold (e.g., 95%) or recall drops below threshold (e.g., 70%)
-- Report resolution accuracy in `codegraph stats` output
-
-**New files:** `tests/benchmarks/resolution-accuracy/`, `tests/fixtures/resolution-benchmark/`
-
----
-
-## Phase 6 -- Native Analysis Acceleration
-
-**Goal:** Move the remaining JS-only build phases to Rust so that `--engine native` eliminates all redundant WASM visitor walks. Today only 3 of 10 build phases (parse, resolve imports, build edges) run in Rust — the other 7 execute identical JavaScript regardless of engine, leaving ~50% of native build time on the table.
-
-**Why Phase 6 (not earlier):** The TypeScript migration (Phase 4) provides typed interfaces that define exactly what the Rust side must return. The Architectural Hardening (Phase 5) fixes method dispatch and adds SCIP integration — both inform what the native engine needs to support. Porting to Rust before these phases means building against untyped, shifting contracts.
-
-**Evidence (v3.1.4 benchmarks on 398 files):**
-
-| Phase | Native | WASM | Ratio | Status |
-|-------|-------:|-----:|------:|--------|
-| Parse | 468ms | 1483ms | 3.2x faster | Already Rust |
-| Build edges | 88ms | 152ms | 1.7x faster | Already Rust |
-| Resolve imports | 8ms | 9ms | ~1x | Already Rust |
-| **AST nodes** | **361ms** | **347ms** | **~1x** | JS visitor — biggest win |
-| **CFG** | **126ms** | **125ms** | **~1x** | JS visitor |
-| **Dataflow** | **100ms** | **98ms** | **~1x** | JS visitor |
-| **Insert nodes** | **143ms** | **148ms** | **~1x** | Pure SQLite batching |
-| **Roles** | **29ms** | **32ms** | **~1x** | JS classification |
-| **Structure** | **13ms** | **17ms** | **~1x** | JS directory tree |
-| Complexity | 16ms | 77ms | 5x faster | Partly pre-computed |
-
-**Target:** Reduce native full-build time from ~1,400ms to ~700ms (2x improvement) by eliminating ~690ms of redundant JS visitor work.
-
-### 6.1 -- AST Node Extraction in Rust
-
-The largest single opportunity. Currently the native parser returns partial AST node data, so the JS `buildAstNodes()` visitor re-walks all WASM trees anyway (~361ms).
-
-- Extend `crates/codegraph-core/` to extract all AST node types (`call`, `new`, `string`, `regex`, `throw`, `await`) during the native parse phase
-- Return complete AST node data in the `FileSymbols` result so `run-analyses.js` can skip the WASM walker entirely
-- Validate parity: ensure native extraction produces identical node counts to the WASM visitor (benchmark already tracks this via `nodes/file`)
-
-**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/ast.js`, `src/domain/graph/builder/stages/run-analyses.js`
-
-### 6.2 -- CFG Construction in Rust
-
-The intraprocedural control-flow graph visitor runs in JS even on native builds (~126ms).
-
-- Port `createCfgVisitor()` logic to Rust: basic block detection, branch/loop edges, entry/exit nodes
-- Return CFG block data per function in `FileSymbols` so the JS visitor is fully bypassed
-- Validate parity: CFG block counts and edge counts must match the WASM visitor output
-
-**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/cfg.js`, `src/ast-analysis/visitors/cfg-visitor.js`
-
-### 6.3 -- Dataflow Analysis in Rust
-
-Dataflow edges are computed by a JS visitor that walks WASM trees (~100ms on native builds).
-
-- Port `createDataflowVisitor()` to Rust: variable definitions, assignments, reads, def-use chains
-- Return dataflow edges in `FileSymbols`
-- Validate parity against WASM visitor output
-
-**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/dataflow.js`, `src/ast-analysis/visitors/dataflow-visitor.js`
-
-### 6.4 -- Batch SQLite Inserts via Rust
-
-`insertNodes` is pure SQLite work (~143ms) but runs row-by-row from JS. Batching in Rust can reduce JS↔native boundary crossings.
-
-- Expose a `batchInsertNodes(nodes[])` function from Rust that uses a single prepared statement in a transaction
-- Alternatively, generate the SQL batch on the JS side and execute as a single `better-sqlite3` call (may be sufficient without Rust)
-- Benchmark both approaches; pick whichever is faster
-
-**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/db/index.js`, `src/domain/graph/builder/stages/insert-nodes.js`
-
-### 6.5 -- Role Classification & Structure in Rust
-
-Smaller wins (~42ms combined) but complete the picture of a fully native build pipeline.
-
-- Port `classifyNodeRoles()` to Rust: hub/leaf/bridge/utility classification based on in/out degree and betweenness
-- Port directory structure building and metrics aggregation
-- Return role assignments and structure data alongside parse results
-
-**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/structure.js`, `src/domain/graph/builder/stages/build-structure.js`
-
-### 6.6 -- Complete Complexity Pre-computation
-
-Complexity is partly pre-computed by native (~16ms vs 77ms WASM) but not all functions are covered.
-
-- Ensure native parse computes cognitive, cyclomatic, Halstead, and MI metrics for every function, not just a subset
-- Eliminate the WASM fallback path in `buildComplexityMetrics()` when running native
-
-**Affected files:** `crates/codegraph-core/src/lib.rs`, `src/features/complexity.js`
-
-### 6.7 -- Fix Incremental Rebuild Data Loss on Native Engine
-
-**Bug:** On native 1-file rebuilds, complexity, CFG, and dataflow data for the changed file is **silently lost**. `purgeFilesFromGraph` removes the old data, but the analysis phases never re-compute it because:
-
-1. The native parser does not produce a `_tree` (WASM tree-sitter tree)
-2. The unified walker at `src/ast-analysis/engine.js:108-109` skips files without `_tree`
-3. The `buildXxx` functions check for pre-computed fields (`d.complexity`, `d.cfg?.blocks`) which the native parser does not provide for these analyses
-4. Result: 0.1ms no-op — the phases run but do nothing
-
-This is confirmed by the v3.1.4 1-file rebuild data: complexity (0.1ms), CFG (0.1ms), dataflow (0.2ms) on native — these are just module import overhead, not actual computation. Contrast with v3.1.3 where the numbers were higher (1.3ms, 8.7ms, 4ms) because earlier versions triggered a WASM fallback tree via `ensureWasmTrees`.
-
-**Fix (prerequisite: 4.1–4.3):** Once the native parser returns complete AST nodes, CFG blocks, and dataflow edges in `FileSymbols`, the `run-analyses` stage can store them directly without needing a WASM tree. The incremental path must:
-
-- Ensure `parseFilesAuto()` returns pre-computed analysis data for the single changed file
-- Have `run-analyses.js` store that data (currently it only stores if `_tree` exists or if pre-computed fields are present — the latter path needs to work reliably)
-- Add an integration test: rebuild 1 file on native engine, then query its complexity/CFG/dataflow and assert non-empty results
-
-**Affected files:** `src/ast-analysis/engine.js`, `src/domain/graph/builder/stages/run-analyses.js`, `src/domain/parser.js`, `tests/integration/`
-
-### 6.8 -- Incremental Rebuild Performance
-
-With analysis data loss fixed, optimize the 1-file rebuild path end-to-end. Current native 1-file rebuild is 265ms — dominated by parse (51ms), structure (13ms), roles (27ms), edges (13ms), insert (12ms), and finalize (12ms).
-
-- **Skip unchanged phases:** Structure and roles are graph-wide computations. On a 1-file change, only the changed file's nodes/edges need updating — skip full reclassification unless the file's degree changed significantly
-- **Incremental edge rebuild:** Only rebuild edges involving the changed file's symbols, not the full edge set
-- **Benchmark target:** Sub-100ms native 1-file rebuilds (from current 265ms)
-
-**Affected files:** `src/domain/graph/builder/stages/build-structure.js`, `src/domain/graph/builder/stages/build-edges.js`, `src/domain/graph/builder/pipeline.js`
-
-
 ---
 
-## Phase 7 -- Runtime & Extensibility
+## Phase 6 -- Runtime & Extensibility
 
-**Goal:** Harden the runtime for large codebases and open the platform to external contributors. These items were deferred from Phase 3 -- they depend on the clean module boundaries and domain layering established there, and benefit from TypeScript's type safety (Phase 4) for safe refactoring of cross-cutting concerns like caching, streaming, and plugin contracts.
+**Goal:** Harden the runtime for large codebases and open the platform to external contributors. These items were deferred from Phase 3 -- they depend on the clean module boundaries and domain layering established there, and benefit from TypeScript's type safety (Phase 5) for safe refactoring of cross-cutting concerns like caching, streaming, and plugin contracts.
 
 **Why after TypeScript Migration:** Several of these items introduce new internal contracts (plugin API, cache interface, streaming protocol, engine strategy). Defining those contracts in TypeScript from the start avoids a second migration pass and gives contributors type-checked extension points.
 
-### 7.1 -- Event-Driven Pipeline
+### 6.1 -- Event-Driven Pipeline
 
 Replace the synchronous build/analysis pipeline with an event/streaming architecture. Enables progress reporting, cancellation tokens, and bounded memory usage on large repositories (10K+ files).
 
@@ -1368,7 +1258,7 @@ Replace the synchronous build/analysis pipeline with an event/streaming architec
 
 **Affected files:** `src/domain/graph/builder.js`, `src/cli/`, `src/mcp/`
 
-### 7.2 -- Unified Engine Interface (Strategy Pattern)
+### 6.2 -- Unified Engine Interface (Strategy Pattern)
 
 Replace scattered `engine.name === 'native'` / `engine === 'wasm'` branching throughout the codebase with a formal Strategy pattern. Each engine implements a common `ParsingEngine` interface with methods like `parse(file)`, `batchParse(files)`, `supports(language)`, and `capabilities()`.
 
@@ -1380,7 +1270,7 @@ Replace scattered `engine.name === 'native'` / `engine === 'wasm'` branching thr
 
 **Affected files:** `src/infrastructure/native.js`, `src/domain/parser.js`, `src/domain/graph/builder.js`
 
-### 7.3 -- Subgraph Export Filtering
+### 6.3 -- Subgraph Export Filtering
 
 Add focus and depth controls to `codegraph export` so users can produce usable visualizations of specific subsystems rather than the entire graph.
 
@@ -1397,7 +1287,7 @@ codegraph export --focus "buildGraph" --depth 3 --format dot
 
 **Affected files:** `src/features/export.js`, `src/presentation/export.js`
 
-### 7.4 -- Transitive Import-Aware Confidence
+### 6.4 -- Transitive Import-Aware Confidence
 
 Improve import resolution accuracy by walking the import graph before falling back to proximity heuristics. Currently the 6-level priority system uses directory proximity as a strong signal, but this can mis-resolve when a symbol is re-exported through an index file several directories away.
 
@@ -1408,7 +1298,7 @@ Improve import resolution accuracy by walking the import graph before falling ba
 
 **Affected files:** `src/domain/graph/resolve.js`
 
-### 7.5 -- Query Result Caching
+### 6.5 -- Query Result Caching
 
 Add an LRU/TTL cache layer between the analysis/query functions and the SQLite repository. With 34+ MCP tools that often run overlapping queries within a session, caching eliminates redundant DB round-trips.
 
@@ -1421,7 +1311,7 @@ Add an LRU/TTL cache layer between the analysis/query functions and the SQLite r
 
 **Affected files:** `src/domain/analysis/`, `src/db/index.js`
 
-### 7.6 -- Configuration Profiles
+### 6.6 -- Configuration Profiles
 
 Support named configuration profiles for monorepos and multi-service projects where different parts of the codebase need different settings.
 
@@ -1442,7 +1332,7 @@ Support named configuration profiles for monorepos and multi-service projects wh
 
 **Affected files:** `src/infrastructure/config.js`, `src/cli/`
 
-### 7.7 -- Pagination Standardization
+### 6.7 -- Pagination Standardization
 
 Standardize SQL-level `LIMIT`/`OFFSET` pagination across all repository queries and surface it consistently through the CLI and MCP.
 
@@ -1454,7 +1344,7 @@ Standardize SQL-level `LIMIT`/`OFFSET` pagination across all repository queries
 
 **Affected files:** `src/shared/paginate.js`, `src/db/index.js`, `src/domain/analysis/`, `src/mcp/`
 
-### 7.8 -- Plugin System for Custom Commands
+### 6.8 -- Plugin System for Custom Commands
 
 Allow users to extend codegraph with custom commands by dropping a JS/TS module into `~/.codegraph/plugins/` (global) or `.codegraph/plugins/` (project-local).
 
@@ -1482,7 +1372,7 @@ export function data(db: Database, args: ParsedArgs, config: Config): object {
 
 **Affected files:** `src/cli/`, `src/mcp/`, new `src/infrastructure/plugins.js`
 
-### 7.9 -- Developer Experience & Onboarding
+### 6.9 -- Developer Experience & Onboarding
 
 Lower the barrier to first successful use. Today codegraph requires manual install, manual config, and prior knowledge of which command to run next.
 
@@ -1494,16 +1384,15 @@ Lower the barrier to first successful use. Today codegraph requires manual insta
 
 **Affected files:** new `src/cli/commands/init.js`, `docs/benchmarks/`, `docs/editors/`, `src/presentation/result-formatter.js`
 
-
 ---
 
-## Phase 8 -- Intelligent Embeddings
+## Phase 7 -- Intelligent Embeddings
 
 **Goal:** Dramatically improve semantic search quality by embedding natural-language descriptions instead of raw code.
 
-> **Phase 8.3 (Hybrid Search) was completed early** during Phase 2.5 -- FTS5 BM25 + semantic search with RRF fusion is already shipped in v2.7.0.
+> **Phase 7.3 (Hybrid Search) was completed early** during Phase 2.5 -- FTS5 BM25 + semantic search with RRF fusion is already shipped in v2.7.0.
 
-### 8.1 -- LLM Description Generator
+### 7.1 -- LLM Description Generator
 
 For each function/method/class node, generate a concise natural-language description:
 
@@ -1531,7 +1420,7 @@ For each function/method/class node, generate a concise natural-language descrip
 
 **New file:** `src/describer.js`
 
-### 8.2 -- Enhanced Embedding Pipeline
+### 7.2 -- Enhanced Embedding Pipeline
 
 - When descriptions exist, embed the description text instead of raw code
 - Keep raw code as fallback when no description is available
@@ -1542,11 +1431,11 @@ For each function/method/class node, generate a concise natural-language descrip
 
 **Affected files:** `src/embedder.js`
 
-### ~~8.3 -- Hybrid Search~~ ✅ Completed in Phase 2.5
+### ~~7.3 -- Hybrid Search~~ ✅ Completed in Phase 2.5
 
 Shipped in v2.7.0. FTS5 BM25 keyword search + semantic vector search with RRF fusion. Three search modes: `hybrid` (default), `semantic`, `keyword`.
 
-### 8.4 -- Build-time Semantic Metadata
+### 7.4 -- Build-time Semantic Metadata
 
 Enrich nodes with LLM-generated metadata beyond descriptions. Computed incrementally at build time (only for changed nodes), stored as columns on the `nodes` table.
 
@@ -1559,9 +1448,9 @@ Enrich nodes with LLM-generated metadata beyond descriptions. Computed increment
 - MCP tool: `assess <name>` -- returns complexity rating + specific concerns
 - Cascade invalidation: when a node changes, mark dependents for re-enrichment
 
-**Depends on:** 8.1 (LLM provider abstraction)
+**Depends on:** 7.1 (LLM provider abstraction)
 
-### 8.5 -- Module Summaries
+### 7.5 -- Module Summaries
 
 Aggregate function descriptions + dependency direction into file-level narratives.
 
@@ -1573,14 +1462,13 @@ Aggregate function descriptions + dependency direction into file-level narrative
 
 > **Full spec:** See [llm-integration.md](./llm-integration.md) for detailed architecture, infrastructure table, and prompt design.
 
-
 ---
 
-## Phase 9 -- Natural Language Queries
+## Phase 8 -- Natural Language Queries
 
 **Goal:** Allow developers to ask questions about their codebase in plain English.
 
-### 9.1 -- Query Engine
+### 8.1 -- Query Engine
 
 ```bash
 codegraph ask "How does the authentication flow work?"
@@ -1606,7 +1494,7 @@ codegraph ask "How does the authentication flow work?"
 
 **New file:** `src/nlquery.js`
 
-### 9.2 -- Conversational Sessions
+### 8.2 -- Conversational Sessions
 
 Multi-turn conversations with session memory.
 
@@ -1620,7 +1508,7 @@ codegraph sessions clear
 - Store conversation history in SQLite table `sessions`
 - Include prior Q&A pairs in subsequent prompts
 
-### 9.3 -- MCP Integration
+### 8.3 -- MCP Integration
 
 New MCP tool: `ask_codebase` -- natural language query via MCP.
 
@@ -1628,7 +1516,7 @@ Enables AI coding agents (Claude Code, Cursor, etc.) to ask codegraph questions
 
 **Affected files:** `src/mcp.js`
 
-### 9.4 -- LLM-Narrated Graph Queries
+### 8.4 -- LLM-Narrated Graph Queries
 
 Graph traversal + LLM narration for questions that require both structural data and natural-language explanation. Each query walks the graph first, then sends the structural result to the LLM for narration.
 
@@ -1643,7 +1531,7 @@ Pre-computed `flow_narratives` table caches results for key entry points at buil
 
 **Depends on:** 7.4 (`side_effects` metadata), 7.1 (descriptions for narration context)
 
-### 9.5 -- Onboarding & Navigation Tools
+### 8.5 -- Onboarding & Navigation Tools
 
 Help new contributors and AI agents orient in an unfamiliar codebase.
 
@@ -1654,14 +1542,13 @@ Help new contributors and AI agents orient in an unfamiliar codebase.
 
 **Depends on:** 7.5 (module summaries for context), 8.1 (query engine)
 
-
 ---
 
-## Phase 10 -- Expanded Language Support
+## Phase 9 -- Expanded Language Support
 
 **Goal:** Go from 11 -> 19 supported languages.
 
-### 10.1 -- Batch 1: High Demand
+### 9.1 -- Batch 1: High Demand
 
 | Language | Extensions | Grammar | Effort |
 |----------|-----------|---------|--------|
@@ -1670,7 +1557,7 @@ Help new contributors and AI agents orient in an unfamiliar codebase.
 | Kotlin | `.kt`, `.kts` | `tree-sitter-kotlin` | Low |
 | Swift | `.swift` | `tree-sitter-swift` | Medium |
 
-### 10.2 -- Batch 2: Growing Ecosystems
+### 9.2 -- Batch 2: Growing Ecosystems
 
 | Language | Extensions | Grammar | Effort |
 |----------|-----------|---------|--------|
@@ -1679,7 +1566,7 @@ Help new contributors and AI agents orient in an unfamiliar codebase.
 | Lua | `.lua` | `tree-sitter-lua` | Low |
 | Zig | `.zig` | `tree-sitter-zig` | Low |
 
-### 10.3 -- Parser Abstraction Layer
+### 9.3 -- Parser Abstraction Layer
 
 Extract shared patterns from existing extractors into reusable helpers.
 
@@ -1693,16 +1580,15 @@ Extract shared patterns from existing extractors into reusable helpers.
 
 **New file:** `src/parser-utils.js`
 
-
 ---
 
-## Phase 11 -- GitHub Integration & CI
+## Phase 10 -- GitHub Integration & CI
 
 **Goal:** Bring codegraph's analysis into pull request workflows.
 
 > **Note:** Phase 2.5 delivered `codegraph check` (CI validation predicates with exit code 0/1), which provides the foundation for GitHub Action integration. The boundary violation, blast radius, and cycle detection predicates are already available.
 
-### 11.1 -- Reusable GitHub Action
+### 10.1 -- Reusable GitHub Action
 
 A reusable GitHub Action that runs on PRs:
 
@@ -1725,7 +1611,7 @@ A reusable GitHub Action that runs on PRs:
 
 **New file:** `.github/actions/codegraph-ci/action.yml`
 
-### 11.2 -- PR Review Integration
+### 10.2 -- PR Review Integration
 
 ```bash
 codegraph review --pr <number>
@@ -1748,7 +1634,7 @@ Requires `gh` CLI. For each changed function:
 
 **New file:** `src/github.js`
 
-### 11.3 -- Visual Impact Graphs for PRs
+### 10.3 -- Visual Impact Graphs for PRs
 
 Extend the existing `diff-impact --format mermaid` foundation with CI automation and LLM annotations.
 
@@ -1771,13 +1657,13 @@ Extend the existing `diff-impact --format mermaid` foundation with CI automation
 
 **Depends on:** 10.1 (GitHub Action), 7.4 (`risk_score`, `side_effects`)
 
-### 11.4 -- SARIF Output
+### 10.4 -- SARIF Output
 
 Add SARIF output format for cycle detection. SARIF integrates with GitHub Code Scanning, showing issues inline in the PR.
 
 **Affected files:** `src/export.js`
 
-### 11.5 -- Auto-generated Docstrings
+### 10.5 -- Auto-generated Docstrings
 
 ```bash
 codegraph annotate
@@ -1786,14 +1672,13 @@ codegraph annotate --changed-only
 
 LLM-generated docstrings aware of callers, callees, and types. Diff-aware: only regenerate for functions whose code or dependencies changed. Stores in `docstrings` column on nodes table -- does not modify source files unless explicitly requested.
 
-**Depends on:** 8.1 (LLM provider abstraction), 7.4 (side effects context)
-
+**Depends on:** 7.1 (LLM provider abstraction), 7.4 (side effects context)
 
 ---
 
-## Phase 12 -- Interactive Visualization & Advanced Features
+## Phase 11 -- Interactive Visualization & Advanced Features
 
-### 12.1 -- Interactive Web Visualization (Partially Complete)
+### 11.1 -- Interactive Web Visualization (Partially Complete)
 
 > **Phase 2.7 progress:** `codegraph plot` (Phase 2.7.8) ships a self-contained HTML viewer with vis-network. It supports layout switching, color/size/cluster overlays, drill-down, community detection, and a detail panel. The remaining work is the server-based experience below.
 
@@ -1814,7 +1699,7 @@ Opens a local web UI at `localhost:3000` extending the static HTML viewer with:
 
 **New file:** `src/visualizer.js`
 
-### 12.2 -- Dead Code Detection
+### 11.2 -- Dead Code Detection
 
 ```bash
 codegraph dead
@@ -1827,7 +1712,7 @@ Find functions/methods/classes with zero incoming edges (never called). Filters
 
 **Affected files:** `src/queries.js`
 
-### 12.3 -- Cross-Repository Support (Monorepo)
+### 11.3 -- Cross-Repository Support (Monorepo)
 
 Support multi-package monorepos with cross-package edges.
 
@@ -1837,7 +1722,7 @@ Support multi-package monorepos with cross-package edges.
 - `codegraph build --workspace` to scan all packages
 - Impact analysis across package boundaries
 
-### 12.4 -- Agentic Search
+### 11.4 -- Agentic Search
 
 Recursive reference-following search that traces connections.
 
@@ -1859,7 +1744,7 @@ codegraph agent-search "payment processing"
 
 **New file:** `src/agentic-search.js`
 
-### 12.5 -- Refactoring Analysis
+### 11.5 -- Refactoring Analysis
 
 LLM-powered structural analysis that identifies refactoring opportunities. The graph provides the structural data; the LLM interprets it.
 
@@ -1876,7 +1761,7 @@ LLM-powered structural analysis that identifies refactoring opportunities. The g
 
 **Depends on:** 7.4 (`risk_score`, `complexity_notes`), 7.5 (module summaries)
 
-### 12.6 -- Auto-generated Docstrings
+### 11.6 -- Auto-generated Docstrings
 
 ```bash
 codegraph annotate
@@ -1885,7 +1770,7 @@ codegraph annotate --changed-only
 
 LLM-generated docstrings aware of callers, callees, and types. Diff-aware: only regenerate for functions whose code or dependencies changed. Stores in `docstrings` column on nodes table -- does not modify source files unless explicitly requested.
 
-**Depends on:** 8.1 (LLM provider abstraction), 7.4 (side effects context)
+**Depends on:** 7.1 (LLM provider abstraction), 7.4 (side effects context)
 
 > **Full spec:** See [llm-integration.md](./llm-integration.md) for detailed architecture, infrastructure tables, and prompt design for all LLM-powered features.
 
@@ -1940,4 +1825,3 @@ Technology changes to monitor that may unlock future improvements.
 Want to help? Contributions to any phase are welcome. See [CONTRIBUTING](README.md#-contributing) for setup instructions.
 
 If you're interested in working on a specific phase, open an issue to discuss the approach before starting.
-
diff --git a/generated/competitive/COMPETITIVE_ANALYSIS.md b/generated/competitive/COMPETITIVE_ANALYSIS.md
index 5f0b8f1a..a103df1a 100644
--- a/generated/competitive/COMPETITIVE_ANALYSIS.md
+++ b/generated/competitive/COMPETITIVE_ANALYSIS.md
@@ -1,7 +1,7 @@
 # Competitive Analysis — Code Graph / Code Intelligence Tools
 
-**Date:** 2026-03-21 (updated from 2026-02-25)
-**Scope:** 140+ code analysis tools evaluated, 85+ ranked against `@optave/codegraph`
+**Date:** 2026-02-25
+**Scope:** 137+ code analysis tools evaluated, 82+ ranked against `@optave/codegraph`
 
 ---
 
@@ -13,55 +13,53 @@ Ranked by weighted score across 6 dimensions (each 1–5):
 
 | # | Score | Project | Stars | Lang | License | Summary |
 |---|-------|---------|-------|------|---------|---------|
-| 1 | 4.7 | [abhigyanpatwari/GitNexus](https://github.com/abhigyanpatwari/GitNexus) | 18,453 | TS/JS | PolyForm NC | Zero-server knowledge graph engine with Graph RAG Agent, CLI + MCP + Web UI, tree-sitter native + WASM, LadybugDB (custom graph DB), multi-editor support (Claude Code hooks, Cursor, Codex, Windsurf, OpenCode), auto-generated AGENTS.md/CLAUDE.md. **Non-commercial license. Viral growth (18k stars in ~8 months)** |
-| 2 | 4.5 | [joernio/joern](https://github.com/joernio/joern) | 3,021 | Scala | Apache-2.0 | Full CPG analysis platform for vulnerability discovery, Scala query DSL, multi-language, daily releases (v4.0.508), 75 contributors |
-| 3 | 4.5 | [postrv/narsil-mcp](https://github.com/postrv/narsil-mcp) | 129 | Rust | Apache-2.0 | 90 MCP tools, 32 languages, taint analysis, SBOM, dead code, neural semantic search, single ~30MB binary, SPA web frontend (v1.6.1) |
-| 4 | 4.5 | [vitali87/code-graph-rag](https://github.com/vitali87/code-graph-rag) | 2,168 | Python | MIT | Graph RAG with Memgraph, multi-provider AI, code editing, semantic search, MCP server (added 2026) |
-| **5** | **4.5** | **[@optave/codegraph](https://github.com/optave/codegraph)** | **32** | **JS/Rust** | **Apache-2.0** | **Sub-second incremental rebuilds (3-tier change detection), dual engine (native Rust + WASM), 11 languages, 32-tool MCP, 41 CLI commands, qualified call resolution with receiver type tracking, `context`/`audit`/`where` AI-optimized commands, dataflow + CFG + stored AST across all languages, sequence diagrams, structure/hotspot analysis, node role classification, dead code/export detection, architecture boundary enforcement, unified graph model with qualified names/scope/visibility, zero-cost core + optional LLM enhancement** |
-| 6 | 4.3 | [DeusData/codebase-memory-mcp](https://github.com/DeusData/codebase-memory-mcp) | 793 | C | MIT | Single static C binary, 64 languages (tree-sitter), 14 MCP tools, Cypher-like query language, persistent SQLite knowledge graph, 10-agent auto-installer, 3D graph visualization, HTTP route analysis. **25 days old — fastest-growing new entrant** |
-| 7 | 4.2 | [Fraunhofer-AISEC/cpg](https://github.com/Fraunhofer-AISEC/cpg) | 424 | Kotlin | Apache-2.0 | CPG library for 8+ languages with MCP module, Neo4j visualization, formal specs, LLVM IR support |
-| 8 | 4.0 | [SimplyLiz/CodeMCP (CKB)](https://github.com/SimplyLiz/CodeMCP) | 77 | Go | Custom | SCIP-based indexing, compound operations (83% token savings), CODEOWNERS, secret scanning, impact analysis, architecture mapping (v8.1.0) |
-| 9 | 4.0 | [harshkedia177/axon](https://github.com/harshkedia177/axon) | 577 | Python | MIT | 11-phase pipeline, KuzuDB, Leiden community detection, dead code, change coupling, MCP + CLI, hit v1.0 milestone |
-| 10 | 3.8 | [seatedro/glimpse](https://github.com/seatedro/glimpse) | 349 | Rust | MIT | Clipboard-first codebase-to-LLM tool with call graphs, token counting, LSP resolution. **Stagnant since Jan 2026** |
+| 1 | 4.5 | [joernio/joern](https://github.com/joernio/joern) | 2,956 | Scala | Apache-2.0 | Full CPG analysis platform for vulnerability discovery, Scala query DSL, multi-language, daily releases |
+| 2 | 4.5 | [postrv/narsil-mcp](https://github.com/postrv/narsil-mcp) | 101 | Rust | Apache-2.0 | 90 MCP tools, 32 languages, taint analysis, SBOM, dead code, neural semantic search, single ~30MB binary |
+| 3 | 4.5 | [vitali87/code-graph-rag](https://github.com/vitali87/code-graph-rag) | 1,916 | Python | MIT | Graph RAG with Memgraph, multi-provider AI, code editing, semantic search, MCP |
+| 4 | 4.2 | [Fraunhofer-AISEC/cpg](https://github.com/Fraunhofer-AISEC/cpg) | 411 | Kotlin | Apache-2.0 | CPG library for 8+ languages with MCP module, Neo4j visualization, formal specs, LLVM IR support |
+| 5 | 4.2 | [seatedro/glimpse](https://github.com/seatedro/glimpse) | 349 | Rust | MIT | Clipboard-first codebase-to-LLM tool with call graphs, token counting, LSP resolution |
+| 6 | 4.0 | [SimplyLiz/CodeMCP (CKB)](https://github.com/SimplyLiz/CodeMCP) | 59 | Go | Custom | SCIP-based indexing, compound operations (83% token savings), CODEOWNERS, secret scanning |
+| 7 | 4.0 | [abhigyanpatwari/GitNexus](https://github.com/abhigyanpatwari/GitNexus) | — | TS/JS | PolyForm NC | Knowledge graph with precomputed structural intelligence, 7 MCP tools, hybrid BM25+semantic search, clustering, process tracing, KuzuDB. **Non-commercial only** |
+| **8** | **4.0** | **[@optave/codegraph](https://github.com/optave/codegraph)** | — | **JS/Rust** | **Apache-2.0** | **Sub-second incremental rebuilds, dual engine (native Rust + WASM), 11 languages, 18-tool MCP, qualified call resolution, `context`/`explain`/`where` AI-optimized commands, structure/hotspot analysis, node role classification (entry/core/utility/adapter/dead/leaf), dead code detection, zero-cost core + optional LLM enhancement** |
+| 9 | 3.9 | [harshkedia177/axon](https://github.com/harshkedia177/axon) | 421 | Python | MIT | 11-phase pipeline, KuzuDB, Leiden community detection, dead code, change coupling, 7 MCP tools |
+| 10 | 3.8 | [anrgct/autodev-codebase](https://github.com/anrgct/autodev-codebase) | 111 | TypeScript | None | 40+ languages, 7 embedding providers, Cytoscape.js visualization, LLM reranking |
 | 11 | 3.8 | [ShiftLeftSecurity/codepropertygraph](https://github.com/ShiftLeftSecurity/codepropertygraph) | 564 | Scala | Apache-2.0 | CPG specification + Tinkergraph library, Scala query DSL, protobuf serialization (Joern foundation) |
 | 12 | 3.8 | [Jakedismo/codegraph-rust](https://github.com/Jakedismo/codegraph-rust) | 142 | Rust | None | 100% Rust GraphRAG, SurrealDB, LSP-powered dataflow analysis, architecture boundary enforcement |
 | 13 | 3.7 | [Anandb71/arbor](https://github.com/Anandb71/arbor) | 85 | Rust | MIT | Native GUI, confidence scoring, architectural role classification, fuzzy search, MCP |
 | 14 | 3.7 | [JudiniLabs/mcp-code-graph](https://github.com/JudiniLabs/mcp-code-graph) | 380 | JavaScript | MIT | Cloud-hosted MCP server by CodeGPT, semantic search, dependency links (requires account) |
-| 15 | 3.7 | [entrepeneur4lyf/code-graph-mcp](https://github.com/entrepeneur4lyf/code-graph-mcp) | 83 | Python | MIT | ast-grep for 25+ languages, complexity metrics, code smells, circular dependency detection. **Stagnant since Jul 2025** |
-| 16 | 3.7 | [cs-au-dk/jelly](https://github.com/cs-au-dk/jelly) | 423 | TypeScript | BSD-3 | Academic-grade JS/TS points-to analysis, call graphs, vulnerability exposure, 5 published papers |
-| 17 | 3.6 | [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph) | 308 | TypeScript | MIT | tree-sitter + SQLite + MCP, Claude Code token reduction benchmarks, npx installer. **Nearly doubled since Feb — naming competitor** |
-| 18 | 3.5 | [er77/code-graph-rag-mcp](https://github.com/er77/code-graph-rag-mcp) | 89 | TypeScript | MIT | 26 MCP methods, 11 languages, tree-sitter, semantic search, hotspot analysis, clone detection |
-| 19 | 3.5 | [MikeRecognex/mcp-codebase-index](https://github.com/MikeRecognex/mcp-codebase-index) | 25 | Python | AGPL-3.0 | 18 MCP tools, zero runtime deps, auto-incremental reindexing via git diff |
-| 20 | 3.5 | [nahisaho/CodeGraphMCPServer](https://github.com/nahisaho/CodeGraphMCPServer) | 7 | Python | MIT | GraphRAG with Louvain community detection, 16 languages, 14 MCP tools, 334 tests |
+| 15 | 3.7 | [entrepeneur4lyf/code-graph-mcp](https://github.com/entrepeneur4lyf/code-graph-mcp) | 80 | Python | MIT | ast-grep for 25+ languages, complexity metrics, code smells, circular dependency detection |
+| 16 | 3.7 | [cs-au-dk/jelly](https://github.com/cs-au-dk/jelly) | 417 | TypeScript | BSD-3 | Academic-grade JS/TS points-to analysis, call graphs, vulnerability exposure, 5 published papers |
+| 17 | 3.5 | [er77/code-graph-rag-mcp](https://github.com/er77/code-graph-rag-mcp) | 89 | TypeScript | MIT | 26 MCP methods, 11 languages, tree-sitter, semantic search, hotspot analysis, clone detection |
+| 18 | 3.5 | [MikeRecognex/mcp-codebase-index](https://github.com/MikeRecognex/mcp-codebase-index) | 25 | Python | AGPL-3.0 | 18 MCP tools, zero runtime deps, auto-incremental reindexing via git diff |
+| 19 | 3.5 | [nahisaho/CodeGraphMCPServer](https://github.com/nahisaho/CodeGraphMCPServer) | 7 | Python | MIT | GraphRAG with Louvain community detection, 16 languages, 14 MCP tools, 334 tests |
+| 20 | 3.5 | [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph) | 165 | TypeScript | MIT | tree-sitter + SQLite + MCP, Claude Code token reduction benchmarks, npx installer |
 | 21 | 3.5 | [dundalek/stratify](https://github.com/dundalek/stratify) | 102 | Clojure | MIT | Multi-backend extraction (LSP/SCIP/Joern), 10 languages, DGML/CodeCharta output, architecture linting |
 | 22 | 3.5 | [kraklabs/cie](https://github.com/kraklabs/cie) | 9 | Go | AGPL-3.0 | Code Intelligence Engine: 20+ MCP tools, tree-sitter, semantic search (Ollama), Homebrew, single Go binary |
-| 23 | 3.4 | [anrgct/autodev-codebase](https://github.com/anrgct/autodev-codebase) | 111 | TypeScript | None | 40+ languages, 7 embedding providers, Cytoscape.js visualization, LLM reranking. **Stagnant since Jan 2026** |
-| 24 | 3.4 | [Durafen/Claude-code-memory](https://github.com/Durafen/Claude-code-memory) | 72 | Python | None | Memory Guard quality gate, persistent codebase memory, Voyage AI + Qdrant |
-| 25 | 3.3 | [NeuralRays/codexray](https://github.com/NeuralRays/codexray) | 2 | TypeScript | MIT | 16 MCP tools, TF-IDF semantic search (~50MB), dead code, complexity, path finding |
-| 26 | 3.3 | [DucPhamNgoc08/CodeVisualizer](https://github.com/DucPhamNgoc08/CodeVisualizer) | 475 | TypeScript | MIT | VS Code extension, tree-sitter WASM, flowcharts + dependency graphs, 5 AI providers, 9 themes |
-| 27 | 3.3 | [helabenkhalfallah/code-health-meter](https://github.com/helabenkhalfallah/code-health-meter) | 34 | JavaScript | MIT | Formal health metrics (MI, CC, Louvain modularity), published in ACM TOSEM 2025 |
-| 28 | 3.3 | [JohT/code-graph-analysis-pipeline](https://github.com/JohT/code-graph-analysis-pipeline) | 27 | Cypher | GPL-3.0 | 200+ CSV reports, ML anomaly detection, Leiden/HashGNN, jQAssistant + Neo4j for Java |
-| 29 | 3.3 | [Lekssays/codebadger](https://github.com/Lekssays/codebadger) | 43 | Python | GPL-3.0 | Containerized MCP server using Joern CPG, 12+ languages |
-| 30 | 3.2 | [al1-nasir/codegraph-cli](https://github.com/al1-nasir/codegraph-cli) | 11 | Python | MIT | CrewAI multi-agent system, 6 LLM providers, browser explorer, DOCX export |
-| 31 | 3.1 | [anasdayeh/claude-context-local](https://github.com/anasdayeh/claude-context-local) | 0 | Python | None | 100% local, Merkle DAG incremental indexing, sharded FAISS, hybrid BM25+vector, GPU accel |
-| 32 | 3.0 | [Vasu014/loregrep](https://github.com/Vasu014/loregrep) | 12 | Rust | Apache-2.0 | In-memory index library, Rust + Python bindings, AI-tool-ready schemas |
-| 33 | 3.0 | [xnuinside/codegraph](https://github.com/xnuinside/codegraph) | 438 | Python | MIT | Python-only interactive HTML dependency diagrams with zoom/pan/search |
-| 34 | 3.0 | [Adrninistrator/java-all-call-graph](https://github.com/Adrninistrator/java-all-call-graph) | 551 | Java | Apache-2.0 | Complete Java bytecode call graphs, Spring/MyBatis-aware, SQL-queryable DB |
-| 35 | 3.0 | [Technologicat/pyan](https://github.com/Technologicat/pyan) | 395 | Python | GPL-2.0 | Python 3 call graph generator, module import analysis, cycle detection, interactive HTML |
-| 36 | 3.0 | [GaloisInc/MATE](https://github.com/GaloisInc/MATE) | 194 | Python | BSD-3 | DARPA-funded interactive CPG-based bug hunting for C/C++ via LLVM |
-| 37 | 3.0 | [clouditor/cloud-property-graph](https://github.com/clouditor/cloud-property-graph) | 28 | Kotlin | Apache-2.0 | Connects code property graphs with cloud runtime security assessment |
+| 23 | 3.4 | [Durafen/Claude-code-memory](https://github.com/Durafen/Claude-code-memory) | 72 | Python | None | Memory Guard quality gate, persistent codebase memory, Voyage AI + Qdrant |
+| 24 | 3.3 | [NeuralRays/codexray](https://github.com/NeuralRays/codexray) | 2 | TypeScript | MIT | 16 MCP tools, TF-IDF semantic search (~50MB), dead code, complexity, path finding |
+| 25 | 3.3 | [DucPhamNgoc08/CodeVisualizer](https://github.com/DucPhamNgoc08/CodeVisualizer) | 475 | TypeScript | MIT | VS Code extension, tree-sitter WASM, flowcharts + dependency graphs, 5 AI providers, 9 themes |
+| 26 | 3.3 | [helabenkhalfallah/code-health-meter](https://github.com/helabenkhalfallah/code-health-meter) | 34 | JavaScript | MIT | Formal health metrics (MI, CC, Louvain modularity), published in ACM TOSEM 2025 |
+| 27 | 3.3 | [JohT/code-graph-analysis-pipeline](https://github.com/JohT/code-graph-analysis-pipeline) | 27 | Cypher | GPL-3.0 | 200+ CSV reports, ML anomaly detection, Leiden/HashGNN, jQAssistant + Neo4j for Java |
+| 28 | 3.3 | [Lekssays/codebadger](https://github.com/Lekssays/codebadger) | 43 | Python | GPL-3.0 | Containerized MCP server using Joern CPG, 12+ languages |
+| 29 | 3.2 | [al1-nasir/codegraph-cli](https://github.com/al1-nasir/codegraph-cli) | 11 | Python | MIT | CrewAI multi-agent system, 6 LLM providers, browser explorer, DOCX export |
+| 30 | 3.1 | [anasdayeh/claude-context-local](https://github.com/anasdayeh/claude-context-local) | 0 | Python | None | 100% local, Merkle DAG incremental indexing, sharded FAISS, hybrid BM25+vector, GPU accel |
+| 31 | 3.0 | [Vasu014/loregrep](https://github.com/Vasu014/loregrep) | 12 | Rust | Apache-2.0 | In-memory index library, Rust + Python bindings, AI-tool-ready schemas |
+| 32 | 3.0 | [xnuinside/codegraph](https://github.com/xnuinside/codegraph) | 438 | Python | MIT | Python-only interactive HTML dependency diagrams with zoom/pan/search |
+| 33 | 3.0 | [Adrninistrator/java-all-call-graph](https://github.com/Adrninistrator/java-all-call-graph) | 551 | Java | Apache-2.0 | Complete Java bytecode call graphs, Spring/MyBatis-aware, SQL-queryable DB |
+| 34 | 3.0 | [Technologicat/pyan](https://github.com/Technologicat/pyan) | 395 | Python | GPL-2.0 | Python 3 call graph generator, module import analysis, cycle detection, interactive HTML |
+| 35 | 3.0 | [GaloisInc/MATE](https://github.com/GaloisInc/MATE) | 194 | Python | BSD-3 | DARPA-funded interactive CPG-based bug hunting for C/C++ via LLVM |
+| 36 | 3.0 | [clouditor/cloud-property-graph](https://github.com/clouditor/cloud-property-graph) | 28 | Kotlin | Apache-2.0 | Connects code property graphs with cloud runtime security assessment |
 
 ### Tier 2: Niche & Single-Language Tools (score 2.0–2.9)
 
 | # | Score | Project | Stars | Lang | License | Summary |
 |---|-------|---------|-------|------|---------|---------|
 | 37 | 2.9 | [rahulvgmail/CodeInteliMCP](https://github.com/rahulvgmail/CodeInteliMCP) | 8 | Python | None | DuckDB + ChromaDB (zero Docker), multi-repo, lightweight embedded DBs |
-| 38 | 2.8 | [Aider-AI/aider](https://github.com/Aider-AI/aider) | 42,198 | Python | Apache-2.0 | AI pair programming CLI; tree-sitter repo map with PageRank-style graph ranking for LLM context selection, 100+ languages, multi-provider LLM support, git-integrated auto-commits. Moved to Aider-AI org |
+| 38 | 2.8 | [paul-gauthier/aider](https://github.com/paul-gauthier/aider) | 41,664 | Python | Apache-2.0 | AI pair programming CLI; tree-sitter repo map with PageRank-style graph ranking for LLM context selection, 100+ languages, multi-provider LLM support, git-integrated auto-commits |
 | 39 | 2.8 | [scottrogowski/code2flow](https://github.com/scottrogowski/code2flow) | 4,528 | Python | MIT | Call graphs for Python/JS/Ruby/PHP via AST, DOT output, 100% test coverage |
 | 40 | 2.8 | [ysk8hori/typescript-graph](https://github.com/ysk8hori/typescript-graph) | 200 | TypeScript | None | TypeScript file-level dependency Mermaid diagrams, code metrics (MI, CC), watch mode |
 | 41 | 2.8 | [nuanced-dev/nuanced-py](https://github.com/nuanced-dev/nuanced-py) | 126 | Python | MIT | Python call graph enrichment designed for AI agent consumption |
-| 42 | 2.8 | [sdsrss/code-graph-mcp](https://github.com/sdsrss/code-graph-mcp) | 16 | TypeScript | MIT | AST knowledge graph MCP server with tree-sitter, 10 languages. New entrant |
-| 43 | 2.8 | [Bikach/codeGraph](https://github.com/Bikach/codeGraph) | 6 | TypeScript | MIT | Neo4j graph, Claude Code slash commands, Kotlin support, 40-50% cost reduction |
+| 42 | 2.8 | [Bikach/codeGraph](https://github.com/Bikach/codeGraph) | 6 | TypeScript | MIT | Neo4j graph, Claude Code slash commands, Kotlin support, 40-50% cost reduction |
 | 43 | 2.8 | [ChrisRoyse/CodeGraph](https://github.com/ChrisRoyse/CodeGraph) | 65 | TypeScript | None | Neo4j + MCP, multi-language, framework detection (React, Tailwind, Supabase) |
 | 44 | 2.8 | [Symbolk/Code2Graph](https://github.com/Symbolk/Code2Graph) | 48 | Java | None | Multilingual code → language-agnostic graph representation |
 | 45 | 2.7 | [yumeiriowl/repo-graphrag-mcp](https://github.com/yumeiriowl/repo-graphrag-mcp) | 3 | Python | MIT | LightRAG + tree-sitter, entity merge (code ↔ docs), implementation planning tool |
@@ -132,43 +130,42 @@ Ranked by weighted score across 6 dimensions (each 1–5):
 
 | # | Project | Features | Analysis Depth | Deploy Simplicity | Lang Support | Code Quality | Community |
 |---|---------|----------|---------------|-------------------|-------------|-------------|-----------|
-| 1 | GitNexus | 5 | 5 | 4 | 4 | 4 | 5 |
-| 2 | joern | 5 | 5 | 3 | 4 | 5 | 5 |
-| 3 | narsil-mcp | 5 | 5 | 5 | 5 | 4 | 3 |
-| 4 | code-graph-rag | 5 | 4 | 3 | 4 | 4 | 5 |
-| **5** | **codegraph (us)** | **5** | **5** | **5** | **4** | **5** | **3** |
-| 6 | codebase-memory-mcp | 4 | 4 | 5 | 5 | 4 | 4 |
-| 7 | cpg | 5 | 5 | 2 | 5 | 5 | 3 |
-| 8 | CKB | 5 | 5 | 4 | 3 | 4 | 3 |
-| 9 | axon | 5 | 5 | 4 | 2 | 4 | 3 |
-| 10 | glimpse | 4 | 4 | 5 | 3 | 5 | 4 |
+| 1 | joern | 5 | 5 | 3 | 4 | 5 | 5 |
+| 2 | narsil-mcp | 5 | 5 | 5 | 5 | 4 | 3 |
+| 3 | code-graph-rag | 5 | 4 | 3 | 4 | 4 | 5 |
+| 4 | cpg | 5 | 5 | 2 | 5 | 5 | 3 |
+| 5 | glimpse | 4 | 4 | 5 | 3 | 5 | 5 |
+| 6 | CKB | 5 | 5 | 4 | 3 | 4 | 3 |
+| 7 | GitNexus | 5 | 5 | 4 | 4 | 4 | 2 |
+| **8** | **codegraph (us)** | **5** | **4** | **5** | **4** | **4** | **2** |
+| 9 | axon | 5 | 5 | 4 | 2 | 4 | 2 |
+| 10 | autodev-codebase | 5 | 3 | 3 | 5 | 3 | 4 |
 | 11 | codepropertygraph | 4 | 5 | 2 | 4 | 5 | 3 |
 | 12 | codegraph-rust | 5 | 5 | 2 | 4 | 4 | 3 |
 | 13 | arbor | 4 | 4 | 5 | 4 | 5 | 3 |
 | 14 | mcp-code-graph | 4 | 3 | 4 | 4 | 3 | 4 |
 | 15 | code-graph-mcp | 4 | 4 | 4 | 5 | 3 | 2 |
 | 16 | jelly | 4 | 5 | 4 | 1 | 5 | 3 |
-| 17 | colbymchenry/codegraph | 4 | 3 | 5 | 3 | 3 | 4 |
-| 18 | code-graph-rag-mcp | 5 | 4 | 3 | 4 | 3 | 2 |
-| 19 | mcp-codebase-index | 4 | 3 | 5 | 3 | 4 | 2 |
-| 20 | CodeGraphMCPServer | 4 | 4 | 4 | 5 | 3 | 1 |
+| 17 | code-graph-rag-mcp | 5 | 4 | 3 | 4 | 3 | 2 |
+| 18 | mcp-codebase-index | 4 | 3 | 5 | 3 | 4 | 2 |
+| 19 | CodeGraphMCPServer | 4 | 4 | 4 | 5 | 3 | 1 |
+| 20 | colbymchenry/codegraph | 4 | 3 | 5 | 3 | 3 | 3 |
 | 21 | stratify | 4 | 4 | 2 | 5 | 4 | 2 |
 | 22 | cie | 5 | 4 | 4 | 3 | 4 | 1 |
-| 23 | autodev-codebase | 5 | 3 | 3 | 5 | 3 | 3 |
-| 24 | Claude-code-memory | 4 | 3 | 3 | 3 | 4 | 3 |
-| 25 | codexray | 5 | 4 | 4 | 4 | 3 | 1 |
-| 26 | CodeVisualizer | 4 | 3 | 5 | 3 | 3 | 2 |
-| 27 | code-health-meter | 3 | 5 | 5 | 1 | 4 | 2 |
-| 28 | code-graph-analysis-pipeline | 5 | 5 | 1 | 2 | 5 | 2 |
-| 29 | codebadger | 4 | 4 | 3 | 5 | 3 | 1 |
-| 30 | codegraph-cli | 5 | 3 | 3 | 2 | 3 | 2 |
-| 31 | claude-context-local | 4 | 3 | 3 | 4 | 4 | 1 |
-| 32 | loregrep | 3 | 3 | 4 | 3 | 5 | 2 |
-| 33 | xnuinside/codegraph | 3 | 2 | 5 | 1 | 3 | 4 |
-| 34 | java-all-call-graph | 4 | 4 | 3 | 1 | 3 | 3 |
-| 35 | pyan | 3 | 3 | 5 | 1 | 4 | 2 |
-| 36 | MATE | 3 | 5 | 1 | 1 | 3 | 2 |
-| 37 | cloud-property-graph | 4 | 4 | 2 | 2 | 4 | 2 |
+| 23 | Claude-code-memory | 4 | 3 | 3 | 3 | 4 | 3 |
+| 24 | codexray | 5 | 4 | 4 | 4 | 3 | 1 |
+| 25 | CodeVisualizer | 4 | 3 | 5 | 3 | 3 | 2 |
+| 26 | code-health-meter | 3 | 5 | 5 | 1 | 4 | 2 |
+| 27 | code-graph-analysis-pipeline | 5 | 5 | 1 | 2 | 5 | 2 |
+| 28 | codebadger | 4 | 4 | 3 | 5 | 3 | 1 |
+| 29 | codegraph-cli | 5 | 3 | 3 | 2 | 3 | 2 |
+| 30 | claude-context-local | 4 | 3 | 3 | 4 | 4 | 1 |
+| 31 | loregrep | 3 | 3 | 4 | 3 | 5 | 2 |
+| 32 | xnuinside/codegraph | 3 | 2 | 5 | 1 | 3 | 4 |
+| 33 | java-all-call-graph | 4 | 4 | 3 | 1 | 3 | 3 |
+| 34 | pyan | 3 | 3 | 5 | 1 | 4 | 2 |
+| 35 | MATE | 3 | 5 | 1 | 1 | 3 | 2 |
+| 36 | cloud-property-graph | 4 | 4 | 2 | 2 | 4 | 2 |
 
 **Scoring criteria:**
 - **Features** (1-5): breadth of tools, MCP integration, search, visualization, export
@@ -184,13 +181,13 @@ Ranked by weighted score across 6 dimensions (each 1–5):
 
 | Strength | Details |
 |----------|---------|
-| **Always-fresh graph (incremental rebuilds)** | Three-tier change detection (journal → mtime+size → hash) means only changed files are re-parsed. Change 1 file in a 3,000-file project → rebuild in under a second. No other tool in this space offers true incremental rebuilds. Competitors re-index everything from scratch — making them unusable in commit hooks, watch mode, or agent-driven loops. Native Rust engine achieves ~4-6 ms/file on cold builds |
+| **Always-fresh graph (incremental rebuilds)** | Three-tier change detection (journal → mtime+size → hash) means only changed files are re-parsed. Change 1 file in a 3,000-file project → rebuild in under a second. No other tool in this space offers this. Competitors re-index everything from scratch — making them unusable in commit hooks, watch mode, or agent-driven loops |
 | **Qualified call resolution** | Import-aware resolution distinguishes method calls (`obj.method()`) from standalone function calls, filters 28+ built-in receivers (`console`, `Math`, `JSON`, `Array`, `Promise`, etc.), deduplicates edges, and respects import scope. A call to `foo()` only resolves to functions actually imported or in-scope — eliminating the false positives that plague tree-sitter-based tools. Confidence scoring (1.0 → 0.5) on every edge lets agents trust the graph |
 | **AI-optimized compound commands** | `context` returns source + deps + callers + signature + related tests for a function in one call. `explain` gives structural summaries of files (public API, internals, data flow) or functions without reading the source. These save AI agents 50-80% of the token budget they'd otherwise spend navigating code. No competitor offers purpose-built compound context commands |
 | **Zero-cost core, LLM-enhanced when you choose** | The full graph pipeline (parse, resolve, query, impact analysis) runs with no API keys, no cloud, no cost. LLM features (richer embeddings, semantic search) are an optional layer on top — using whichever provider the user already works with. Competitors either require cloud APIs for core features (code-graph-rag, autodev-codebase, mcp-code-graph) or offer no AI enhancement at all (CKB, axon). Nobody else offers both modes in one tool |
 | **Data goes only where you send it** | Your code reaches exactly one place: the AI agent you already chose (via MCP). No additional third-party services, no surprise cloud calls. Competitors like code-graph-rag, autodev-codebase, mcp-code-graph, and Claude-code-memory send your code to additional AI providers beyond the agent you're using |
-| **Dual engine architecture** | Only project with native Rust (napi-rs) + automatic WASM fallback. Others are pure Rust (narsil-mcp, codegraph-rust, codebase-memory-mcp) OR pure JS/Python — never both |
-| **Standalone CLI + MCP** | Full 41-command CLI experience (`context`, `audit`, `where`, `fn-impact`, `diff-impact`, `map`, `deps`, `search`, `structure`, `sequence`, `roles`, `dataflow`, `cfg`, `ast`) alongside 32-tool MCP server. Many competitors are MCP-only (narsil-mcp, codebase-memory-mcp, code-graph-mcp, CodeGraphMCPServer) with no standalone query interface |
+| **Dual engine architecture** | Only project with native Rust (napi-rs) + automatic WASM fallback. Others are pure Rust (narsil-mcp, codegraph-rust) OR pure JS/Python — never both |
+| **Standalone CLI + MCP** | Full CLI experience (`context`, `explain`, `where`, `fn`, `diff-impact`, `map`, `deps`, `search`, `structure`, `hotspots`, `roles`) alongside 18-tool MCP server. Many competitors are MCP-only (narsil-mcp, code-graph-mcp, CodeGraphMCPServer) with no standalone query interface |
 | **Single-repo MCP isolation** | Security-conscious default: tools have no `repo` property unless `--multi-repo` is explicitly enabled. Most competitors default to exposing everything |
 | **Zero-dependency deployment** | `npm install` and done. No Docker, no external databases, no Python, no SCIP toolchains, no JVM. Published platform-specific binaries (`@optave/codegraph-{platform}-{arch}`) resolve automatically. Joern requires JDK 21, cpg requires Gradle + language-specific deps, codegraph-rust requires SurrealDB + LSP servers |
 | **Structure & quality analysis** | `structure` shows directory cohesion scores, `hotspots` finds files with extreme fan-in/fan-out/density, `stats` includes a graph quality score (0-100) with false-positive warnings. These give agents architectural awareness without requiring external tools |
@@ -201,73 +198,59 @@ Ranked by weighted score across 6 dimensions (each 1–5):
 
 ## Where Codegraph Loses
 
-### vs GitNexus (#1, 18,453 stars)
-- **Viral growth**: 18,453 stars in ~8 months — orders of magnitude more traction. Discord community, TrendShift badge, npm package (`gitnexus`)
-- **Multi-editor integration**: Auto-configures Claude Code (with hooks), Cursor, Codex, Windsurf, OpenCode via `gitnexus setup`. We only support Claude Code MCP config
-- **Auto-generated context files**: Creates AGENTS.md/CLAUDE.md from the knowledge graph — agents get codebase context automatically
-- **Web UI + CLI + MCP**: Three access modes including a hosted web explorer at gitnexus.vercel.app. We have CLI + MCP + interactive HTML viewer but no hosted web UI
-- **Bridge mode**: `gitnexus serve` connects CLI-indexed repos to the web UI — seamless local-to-browser workflow
-- **Where we win**: Non-commercial license (PolyForm NC) blocks enterprise adoption. No incremental rebuilds (full re-index). LadybugDB is custom/unproven vs our SQLite. We have deeper analysis (complexity, dataflow, CFG, architecture boundaries, manifesto rules, CI gates) and confidence-scored edges. Their graph is broader but shallower
-
-### vs joern (#2, 3,021 stars)
-- **Full Code Property Graph**: AST + CFG + PDG combined for deep vulnerability analysis; our tree-sitter extraction captures structure but not interprocedural control/data flow
-- **Scala query DSL**: purpose-built query language for arbitrary graph traversals vs our fixed CLI commands
+### vs joern (#1, 2,956 stars)
+- **Full Code Property Graph**: AST + CFG + PDG combined for deep vulnerability analysis; our tree-sitter extraction captures structure but not control/data flow
+- **Scala query DSL**: purpose-built query language for arbitrary graph traversals vs our fixed SQL queries
 - **Binary analysis**: Ghidra frontend can analyze compiled binaries — we're source-only
-- **Enterprise backing**: ShiftLeft/Fraunhofer support, daily automated releases (v4.0.508), 75 contributors, professional documentation at joern.io
-- **Community**: 3,021 stars, 400 forks — massive traction. 4 community MCP wrappers now available
+- **Enterprise backing**: ShiftLeft/Fraunhofer support, daily automated releases, Discord community, professional documentation at joern.io
+- **Community**: 2,956 stars, 389 forks — massive traction
 
-### vs narsil-mcp (#3, 129 stars)
-- **Feature breadth**: 90 MCP tools vs our 32; covers taint analysis, SBOM, license compliance, control flow graphs, data flow analysis
+### vs narsil-mcp (#2, 101 stars)
+- **Feature breadth**: 90 MCP tools vs our 17; covers taint analysis, SBOM, license compliance, control flow graphs, data flow analysis
 - **Language count**: 32 languages (including Verilog, Fortran, PowerShell, Nix) vs our 11
-- **Security analysis**: vulnerability scanning with OWASP/CWE coverage, 147+ rules (added 36 Rust/Elixir rules in v1.6.0) — we have no security features
-- **SPA web frontend**: Full web UI with file tree sidebar, syntax-highlighted code viewer, dashboard, per-repo overview, CFG visualization (added v1.6.0)
+- **Security analysis**: vulnerability scanning with OWASP/CWE coverage — we have no security features
+- **Dead code detection**: built-in — *(Gap closed: our `roles --role dead` now surfaces unreferenced non-exported symbols)*
 - **Single-binary deployment**: ~30MB Rust binary via brew/scoop/cargo/npm — as easy as ours
-- **Note**: No activity since Feb 25 (24+ day gap) — development may have paused
 
-### vs code-graph-rag (#4, 2,168 stars)
-- **Graph query expressiveness**: Memgraph + Cypher enables arbitrary graph traversals; our CLI commands are more rigid
+### vs code-graph-rag (#3, 1,916 stars)
+- **Graph query expressiveness**: Memgraph + Cypher enables arbitrary graph traversals; our SQL queries are more rigid
 - **AI-powered code editing**: they can surgically edit functions via AST targeting with visual diffs
 - **Provider flexibility**: they support Gemini/OpenAI/Claude/Ollama and can mix providers per task
-- **MCP server**: now added MCP support, expanding from pure RAG into the AI agent ecosystem
-- **Community**: 2,168 stars — significant traction
-
-### vs codebase-memory-mcp (#6, 793 stars — NEW)
-- **Explosive growth**: 793 stars in 25 days — fastest-growing new entrant in the space. Single-developer C project
-- **Zero-dependency binary**: Single static C binary (~30MB), no Node.js/JVM/runtime. Auto-installer configures 10 different AI agents in one command
-- **64 languages**: 3x our language coverage via vendored tree-sitter grammars compiled into the binary
-- **Cypher-like query language**: Hand-built Cypher subset in C for arbitrary graph traversals — we have no query DSL
-- **HTTP route analysis**: First-class Route nodes and cross-service HTTP call linking with confidence scoring — unique capability
-- **3D graph visualization**: Built-in web-based 3D graph viewer
-- **Where we win**: MCP-only (no standalone CLI), no semantic search/embeddings, no complexity metrics, no cycle detection, no export formats (DOT/Mermaid/GraphML), no architecture boundaries, no CI gates, no programmatic API, limited Cypher subset (no WITH/COLLECT/OPTIONAL MATCH). Very immature (v0.5.x, 25 days old, solo developer). Our analysis depth is significantly greater
-
-### vs cpg (#7, 424 stars)
+- **Community**: 1,916 stars — orders of magnitude more traction
+
+### vs cpg (#4, 411 stars)
 - **Formal CPG specification**: academic-grade graph representation (AST + CFG + PDG + DFG) with published specs
 - **MCP module**: built-in MCP support now, matching our integration
 - **LLVM IR support**: extends language coverage to any LLVM-compiled language (Rust, Swift, etc.)
 - **Type inference**: can analyze incomplete/partial code — our tree-sitter requires syntactically valid input
 
-### vs glimpse (#10, 349 stars — stagnant)
+### vs glimpse (#5, 349 stars)
 - **LLM workflow optimization**: clipboard-first output + token counting + XML output mode — purpose-built for "code → LLM context"
 - **LSP-based call resolution**: compiler-grade accuracy vs our tree-sitter heuristic approach
 - **Web content processing**: can fetch URLs and convert HTML to markdown for context
 
-### vs CKB (#8, 77 stars)
+### vs CKB (#6, 59 stars)
 - **Indexing accuracy**: SCIP provides compiler-grade cross-file references (type-aware), fundamentally more accurate than tree-sitter for supported languages
-- **Compound operations**: `explore`/`understand`/`prepareChange` batch multiple queries into one call — 83% token reduction. *(Gap closed: our `context`, `audit`, and `batch` commands now serve the same purpose)*
-- **Now claims impact analysis and architecture mapping**: Feature convergence with v8.1.0 — they're moving into our territory
-- **Secret scanning**: enterprise feature we lack
-
-### vs axon (#9, 577 stars)
-- **Hit v1.0 milestone**: Now a stable release with tree-sitter + KuzuDB + CLI + MCP. Growing fast (+156 stars since Feb)
-- **Leiden community detection**: More sophisticated clustering than our Louvain
-- **KuzuDB with native Cypher**: More expressive for complex graph queries than our SQLite
-- **Git change coupling**: Co-change analysis — *(Gap closed: we now have `co-change` command)*
-- **Branch structural diff**: *(Gap closed: we now have `branch-compare`)*
+- **Compound operations**: `explore`/`understand`/`prepareChange` batch multiple queries into one call — 83% token reduction. *(Gap narrowed: our `context` and `explain` commands now serve the same purpose, returning full function context or file summaries in one call)*
+- **CODEOWNERS + secret scanning**: enterprise features we lack entirely
+
+### vs GitNexus (#7)
+- **Precomputed structural intelligence**: 6-phase pipeline (structure, parsing, resolution, clustering, processes, search) precomputes everything at index time — queries return complete context in a single call. Our queries traverse the graph at query time
+- **Clustering and process tracing**: Leiden-style community detection groups related symbols into functional clusters; execution flow tracing from entry points. We have neither
+- **Hybrid search**: BM25 + semantic + RRF with process-grouped results — our semantic search lacks the BM25/process grouping layer
+- **Multi-file coordinated rename**: validated against graph structure and text — we have no refactoring tools
+- **Auto-generated context files**: LLM-powered wiki and AGENTS.md/CLAUDE.md generation from the knowledge graph
+- **Tradeoff**: Full pipeline re-run on changes (no incremental builds), KuzuDB graph DB (heavier than SQLite), browser mode limited to ~5,000 files
+
+### vs axon (#9, 29 stars)
+- **Analysis depth**: their 11-phase pipeline includes community detection (Leiden), execution flow tracing, git change coupling, dead code detection — *(Gap narrowed: we now have dead code detection via node role classification)*
+- **Graph database**: KuzuDB with native Cypher is more expressive for complex graph queries than our SQLite
+- **Branch structural diff**: compares code structure between branches using git worktrees
 
 ### vs codegraph-rust (#12, 142 stars)
 - **LSP-powered analysis**: compiler-grade cross-file references via rust-analyzer, pyright, gopls vs our tree-sitter heuristics
-- **Dataflow edges**: defines/uses/flows_to/returns/mutates relationships — *(Gap closed: we now have `flows_to`/`returns`/`mutates` across all 11 languages)*
-- **Architecture boundary enforcement**: *(Gap closed: we now have `boundaries` command with onion/hexagonal/layered/clean presets)*
+- **Dataflow edges**: defines/uses/flows_to/returns/mutates relationships we don't capture
+- **Architecture boundary enforcement**: configurable rules for detecting violations — we have no architectural awareness
 - **Tiered indexing**: fast/balanced/full modes for different use cases — we have one mode
 
 ### vs jelly (#16, 417 stars)
@@ -275,19 +258,19 @@ Ranked by weighted score across 6 dimensions (each 1–5):
 - **Academic rigor**: 5 published papers backing the methodology (Aarhus University)
 - **Vulnerability exposure analysis**: library usage pattern matching specific to the JS/TS ecosystem
 
-### vs aider (#38, 42,198 stars — now Aider-AI/aider)
+### vs aider (#38, 41,664 stars)
 - **Different product category**: Aider is an AI pair programming CLI, not a code graph tool — but its tree-sitter repo map with PageRank-style graph ranking is a lightweight alternative to our full graph for LLM context selection
-- **Massive community**: 42,198 stars, 4,054 forks — orders of magnitude more traction than any tool in this space. Aider *is* the category leader for AI-assisted coding in the terminal. Moved to Aider-AI org
+- **Massive community**: 41,664 stars, 3,984 forks — orders of magnitude more traction than any tool in this space. Aider *is* the category leader for AI-assisted coding in the terminal
 - **100+ languages**: tree-sitter parsing covers far more languages than our 11, though only for identifier extraction (not full symbol/call resolution)
 - **Multi-provider LLM**: works with Claude, GPT-4, Gemini, DeepSeek, Ollama, and virtually any LLM out of the box
 - **Built-in code editing**: Aider's core loop is "understand code → edit code → commit." We provide the understanding layer but don't edit
 - **Where we win**: Aider's repo map is shallow — file-level dependency graph with identifier ranking, no function-level call resolution, no impact analysis, no dead code detection, no complexity metrics, no MCP server, no standalone queryable graph. It answers "what's relevant?" but not "what breaks if I change this?" Our graph is deeper and persistent; Aider rebuilds its map per-request
 
-### vs colbymchenry/codegraph (#17, 308 stars — nearly doubled)
-- **Fastest-growing naming competitor**: 165 → 308 stars since Feb. Same name, same tech stack (tree-sitter + SQLite + MCP + Node.js) — marketplace confusion is increasing
-- **Published benchmarks**: 67% fewer tool calls and measurable Claude Code token reduction — compelling marketing. *(Gap closed: our `context`, `audit`, and `batch` compound commands provide equivalent or better token savings)*
+### vs colbymchenry/codegraph (#20, 165 stars)
+- **No role classification**: they lack node role classification or dead code detection — we now have both
+- **Naming competitor**: same name, same tech stack (tree-sitter + SQLite + MCP + Node.js) — marketplace confusion risk
+- **Published benchmarks**: 67% fewer tool calls and measurable Claude Code token reduction — compelling marketing angle we lack. *(Gap narrowed: our `context` and `explain` compound commands now provide similar token savings by batching multiple queries into one call)*
 - **One-liner setup**: `npx @colbymchenry/codegraph` with interactive installer auto-configures Claude Code
-- **Where we win**: We have 41 CLI commands vs their MCP-only approach, confidence-scored edges, dataflow/CFG/AST analysis, complexity metrics, architecture boundaries, cycle detection, dead code/export detection, community detection, sequence diagrams, and CI gates. Their tool is a lightweight MCP wrapper; ours is a full code intelligence platform
 
 ---
 
@@ -299,7 +282,7 @@ Ranked by weighted score across 6 dimensions (each 1–5):
 | ~~**Dead code detection**~~ | narsil-mcp, axon, codexray, CKB | ~~We have the graph — find nodes with zero incoming edges (minus entry points/exports). Agents constantly ask "is this used?"~~ | **DONE** — Delivered via node classification. `roles --role dead` lists all unreferenced, non-exported symbols |
 | ~~**Fuzzy symbol search**~~ | arbor | ~~Add Levenshtein/Jaro-Winkler to `fn` command. Currently requires exact match~~ | **DONE** — `fn` now has relevance scoring (exact > prefix > word-boundary > substring) with fan-in tiebreaker, plus `--file` and `--kind` filters |
 | ~~**Expose confidence scores**~~ | arbor | ~~Already computed internally in import resolution — just surface them~~ | **DONE** — confidence scores stored on every call edge, surfaced in `stats` graph quality score |
-| ~~**Shortest path A→B**~~ | codexray, arbor | ~~BFS on existing edges table~~ | **DONE** — `codegraph path <from> <to>` with BFS on call graph edges |
+| **Shortest path A→B** | codexray, arbor | BFS on existing edges table. We have `fn` for single chains but no A→B pathfinding | TODO |
 
 ### Tier 2: High impact, medium effort
 | Feature | Inspired by | Why | Status |
@@ -307,20 +290,20 @@ Ranked by weighted score across 6 dimensions (each 1–5):
 | **Optional LLM provider integration** | code-graph-rag, autodev-codebase | Bring-your-own provider (OpenAI, etc.) for richer embeddings and AI-powered search. Enhancement layer only — core graph never depends on it. No other tool offers both zero-cost local and LLM-enhanced modes in one package | TODO |
 | ~~**Compound MCP tools**~~ | CKB, colbymchenry/codegraph | ~~`explore`/`understand` meta-tools that batch deps + fn + map into single responses~~ | **DONE** — `context` returns source + deps + callers + signature + tests in one call; `explain` returns structural summaries of files or functions |
 | **Token counting on responses** | glimpse, arbor | tiktoken-based counts so agents know context budget consumed | TODO |
-| ~~**Node classification**~~ | arbor | ~~Auto-tag Entry Point / Core / Utility / Adapter from in-degree/out-degree patterns~~ | **DONE** — `classifyNodeRoles()` tags every symbol as `entry`/`core`/`utility`/`adapter`/`dead`/`leaf`. New `roles` CLI command, `node_roles` MCP tool, `--role`/`--file` filters. Roles surfaced in `where`/`context`/`stats`/`list-functions` |
+| ~~**Node classification**~~ | arbor | ~~Auto-tag Entry Point / Core / Utility / Adapter from in-degree/out-degree patterns~~ | **DONE** — `classifyNodeRoles()` tags every symbol as `entry`/`core`/`utility`/`adapter`/`dead`/`leaf`. New `roles` CLI command, `node_roles` MCP tool (18 tools), `--role`/`--file` filters. Roles surfaced in `where`/`explain`/`context`/`stats`/`list-functions` |
 | **TF-IDF lightweight search** | codexray | SQLite FTS5 + TF-IDF as a middle tier (~50MB) between "no search" and full transformers (~500MB) | TODO |
 | **OWASP/CWE pattern detection** | narsil-mcp, CKB | Security pattern scanning on the existing AST — hardcoded secrets, SQL injection patterns, XSS | TODO |
-| ~~**Formal code health metrics**~~ | code-health-meter | ~~Cyclomatic complexity, Maintainability Index, Halstead metrics per function~~ | **DONE** — `codegraph complexity` delivers cognitive, cyclomatic (CFG-derived), Halstead, MI, nesting depth per function across all 11 languages |
+| **Formal code health metrics** | code-health-meter | Cyclomatic complexity, Maintainability Index, Halstead metrics per function — we already parse the AST | TODO |
 
 ### Tier 3: High impact, high effort
 | Feature | Inspired by | Why | Status |
 |---------|------------|-----|--------|
-| ~~**Interactive HTML visualization**~~ | autodev-codebase, CodeVisualizer | ~~`codegraph viz` → opens interactive graph in browser~~ | **DONE** — `codegraph plot` opens interactive vis-network HTML viewer with physics, clustering, drill-down |
-| ~~**Git change coupling**~~ | axon | ~~Analyze git history for files that always change together~~ | **DONE** — `codegraph co-change` analyzes git history for temporal file coupling |
-| ~~**Community detection**~~ | axon, GitNexus, CodeGraphMCPServer | ~~Louvain algorithm to discover natural module boundaries~~ | **DONE** — `codegraph communities` with Louvain clustering and drift analysis |
-| ~~**Execution flow tracing**~~ | axon, GitNexus, code-context-mcp | ~~Framework-aware entry point detection + BFS flow tracing~~ | **DONE** — `codegraph flow` traces from entry points (routes, commands, events) through callees to leaves |
-| ~~**Dataflow analysis**~~ | codegraph-rust | ~~Define/use chains and flows_to/returns/mutates edges~~ | **DONE** — `codegraph dataflow` with `flows_to`/`returns`/`mutates` edges across all 11 languages |
-| ~~**Architecture boundary rules**~~ | codegraph-rust, stratify | ~~User-defined rules for allowed/forbidden dependencies between modules~~ | **DONE** — `codegraph check` with configurable boundary rules and onion/hexagonal/layered/clean presets |
+| **Interactive HTML visualization** | autodev-codebase, CodeVisualizer | `codegraph viz` → opens interactive vis.js/Cytoscape.js graph in browser | TODO |
+| **Git change coupling** | axon | Analyze git history for files that always change together — enhances `diff-impact` | TODO |
+| **Community detection** | axon, GitNexus, CodeGraphMCPServer | Leiden/Louvain algorithm to discover natural module boundaries vs actual file organization | TODO |
+| **Execution flow tracing** | axon, GitNexus, code-context-mcp | Framework-aware entry point detection + BFS flow tracing | TODO |
+| **Dataflow analysis** | codegraph-rust | Define/use chains and flows_to/returns/mutates edges — major analysis depth increase | TODO |
+| **Architecture boundary rules** | codegraph-rust, stratify | User-defined rules for allowed/forbidden dependencies between modules | TODO |
 
 ### Paid Solutions
 
@@ -339,7 +322,7 @@ Ranked by weighted score across 6 dimensions (each 1–5):
 | **Code Ownership** | CODEOWNERS as a first-class search dimension: `file:has.owner()`, `select:file.owners`, owner-scoped queries. Resolves CODEOWNERS entries against user profiles | `codegraph owners` with `--owner`, `--boundary` filters. Integrated into `diff-impact` (affected owners + suggested reviewers). `code_owners` MCP tool | **No gap** — feature parity. We parse CODEOWNERS, match patterns, integrate into impact analysis, and expose via CLI + MCP. They have richer owner-as-search-filter syntax; our backlog ID 79 (advanced query language) would close this |
 | **Code Insights** | Track any search query as a time-series metric on dashboards. Automatic historical backfill from git history — years of data immediately. Migration progress, tech debt trends, codebase composition over time | `codegraph stats` (point-in-time), `codegraph snapshot` (manual checkpoints) | **Yes** — we have point-in-time metrics and manual snapshots but no automated historical trend tracking. Backlog ID 77 |
 | **Batch Changes** | Declarative YAML spec → automated code changes across hundreds of repos. Creates PRs on all affected repos, tracks merge status, CI checks, review approvals. Burndown charts for migration progress | None — codegraph is read-only by design (Foundation P8: we don't edit code or make decisions) | **By design** — we're a graph query tool, not a code modification tool. This is out of scope per Foundation principles |
-| **CLI (`src`)** | Terminal search, batch change creation, SBOM generation, repo/user/team admin, code intelligence ops, CODEOWNERS management | `codegraph` CLI with 41 commands, 32-tool MCP server | **Partial** — our CLI is richer for graph queries; theirs is richer for admin/batch/SBOM operations. Different focus areas |
+| **CLI (`src`)** | Terminal search, batch change creation, SBOM generation, repo/user/team admin, code intelligence ops, CODEOWNERS management | `codegraph` CLI with 25+ commands, MCP server | **Partial** — our CLI is richer for graph queries; theirs is richer for admin/batch/SBOM operations. Different focus areas |
 
 **Where Sourcegraph wins over codegraph:**
 
@@ -362,18 +345,17 @@ Ranked by weighted score across 6 dimensions (each 1–5):
 | **Impact analysis** | `diff-impact`, `fn-impact`, `branch-compare` trace transitive blast radius through the call graph. Sourcegraph's `find-references` shows direct references but not transitive impact chains |
 | **Complexity & health metrics** | Cognitive, cyclomatic, Halstead, MI per function with CI gates. Sourcegraph has no built-in code health metrics |
 | **Community detection & drift** | Louvain clustering reveals architectural drift between directory structure and actual dependencies. Sourcegraph has no equivalent |
-| **Dataflow analysis** | `flows_to`/`returns`/`mutates` edges track how data moves through functions across all 11 languages. Sourcegraph doesn't do dataflow analysis |
-| **Control flow graphs** | Per-function CFG with basic blocks stored in the graph; cyclomatic complexity derived from CFG structure (E - N + 2). Sourcegraph doesn't build CFGs |
-| **Sequence diagrams** | `sequence <name>` generates Mermaid sequence diagrams from call graph edges. Sourcegraph has no diagram generation |
+| **Dataflow analysis** | `flows_to`/`returns`/`mutates` edges track how data moves through functions. Sourcegraph doesn't do dataflow analysis |
+| **Control flow graphs** | Per-function CFG with basic blocks stored in the graph. Sourcegraph doesn't build CFGs |
 | **Node role classification** | Every symbol auto-tagged as entry/core/utility/adapter/dead/leaf. Sourcegraph has no architectural role concept |
 | **Cost** | Completely free and open source (Apache-2.0). Sourcegraph's paid plans start at $49/user/month for enterprise features |
 | **Privacy** | Your code never leaves your machine (unless you choose to connect an LLM). Sourcegraph Cloud processes your code on their infrastructure; self-hosted requires significant ops investment |
-| **AI-optimized output** | `context`, `audit`, `triage`, `batch`, `sequence` commands are purpose-built for AI agent consumption with structured JSON. Sourcegraph's output is designed for human developers in a web UI |
+| **AI-optimized output** | `context`, `audit`, `triage`, `batch` commands are purpose-built for AI agent consumption with structured JSON. Sourcegraph's output is designed for human developers in a web UI |
 
 ### Not worth copying
 | Feature | Why skip |
 |---------|----------|
-| Memgraph/Neo4j/KuzuDB/SurrealDB/LadybugDB | Our SQLite = zero Docker, simpler deployment. Query gap matters less than simplicity. codegraph-rust's SurrealDB requirement is its biggest weakness. GitNexus's LadybugDB is custom/unproven |
+| Memgraph/Neo4j/KuzuDB/SurrealDB | Our SQLite = zero Docker, simpler deployment. Query gap matters less than simplicity. codegraph-rust's SurrealDB requirement is its biggest weakness |
 | SCIP indexing | Would require maintaining SCIP toolchains per language. Tree-sitter + native Rust is the right bet |
 | Full CPG (AST+CFG+PDG) | Joern/cpg's approach requires fundamentally different parsing — we'd be rebuilding Joern. Tree-sitter gives us AST-level graphs; adding lightweight dataflow on top is the pragmatic path |
 | Points-to analysis | Academic-grade JS analysis (jelly) — overkill for our use case and limited to JS/TS |
diff --git a/generated/competitive/joern.md b/generated/competitive/joern.md
index 3f279de6..403cab75 100644
--- a/generated/competitive/joern.md
+++ b/generated/competitive/joern.md
@@ -1,8 +1,8 @@
 # Competitive Deep-Dive: Codegraph vs Joern
 
-**Date:** 2026-03-21
-**Competitors:** `@optave/codegraph` v3.2.0 (Apache-2.0) vs `joernio/joern` v4.x (Apache-2.0)
-**Context:** Both are Apache-2.0-licensed code analysis tools with CLI interfaces. Joern is ranked #2 in our [competitive analysis](./COMPETITIVE_ANALYSIS.md) with a score of 4.5 vs codegraph's 4.5 at #5.
+**Date:** 2026-03-02
+**Competitors:** `@optave/codegraph` v3.0.0 (Apache-2.0) vs `joernio/joern` v4.x (Apache-2.0)
+**Context:** Both are Apache-2.0-licensed code analysis tools with CLI interfaces. Joern is ranked #1 in our [competitive analysis](./COMPETITIVE_ANALYSIS.md) with a score of 4.5 vs codegraph's 4.0 at #8.
 
 ---
 
@@ -14,7 +14,7 @@ Joern and codegraph solve fundamentally **different problems** using code graphs
 |-----------|-------|-----------|
 | **Primary mission** | Vulnerability discovery & security research | Always-current structural code intelligence for developers and AI agents |
 | **Target user** | Security researchers, pentesters, auditors | Developers, AI coding agents, CI pipelines |
-| **Graph model** | Code Property Graph (AST + CFG + PDG + DDG) | Structural dependency graph (symbols + call/import/dataflow/CFG edges + stored AST + qualified names/scope/visibility) |
+| **Graph model** | Code Property Graph (AST + CFG + PDG + DDG) | Structural dependency graph (symbols + call/import/dataflow/CFG edges + stored AST) |
 | **Core question answered** | "Can attacker-controlled data reach this dangerous sink?" | "What breaks if I change this function?" |
 | **Rebuild model** | Full re-import on every change (minutes) | Incremental sub-second rebuilds (milliseconds) |
 | **Runtime** | JVM (Scala) — 4-100 GB heap | Node.js — <100 MB typical |
@@ -31,11 +31,11 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 
 | # | Principle | Codegraph | Joern | Verdict |
 |---|-----------|-----------|-------|---------|
-| 1 | **The graph is always current** — rebuild on every commit/save/agent loop | 3-tier change detection (journal → mtime+size → hash). Change 1 file in 3,000 → <500ms rebuild. Watch mode, commit hooks, agent loops all practical | Full re-import always. Small project: 19-30s. Linux kernel: 6+ hours. No incremental mode. Unusable in tight feedback loops | **Codegraph wins decisively.** This is the single most important differentiator. Joern cannot participate in commit hooks or agent-driven loops |
+| 1 | **The graph is always current** — rebuild on every commit/save/agent loop | File-level MD5 hashing. Change 1 file in 3,000 → <500ms rebuild. Watch mode, commit hooks, agent loops all practical | Full re-import always. Small project: 19-30s. Linux kernel: 6+ hours. No incremental mode. Unusable in tight feedback loops | **Codegraph wins decisively.** This is the single most important differentiator. Joern cannot participate in commit hooks or agent-driven loops |
 | 2 | **Native speed, universal reach** — dual engine (Rust + WASM) | Native napi-rs with rayon parallelism + automatic WASM fallback. `npm install` on any platform | JVM/Scala. Requires JDK 19+. Pre-built binaries or Docker. No cross-platform auto-detection | **Codegraph wins.** Automatic platform detection with native performance + universal fallback vs. manual JVM setup |
 | 3 | **Confidence over noise** — scored results | 6-level import resolution with 0.0-1.0 confidence on every edge. False-positive filtering. Graph quality score | Overapproximation by default (assumes full taint propagation for unresolved methods). Requires manual semantic definitions to reduce false positives | **Codegraph wins.** Scored results by default vs. noise-by-default requiring manual tuning |
 | 4 | **Zero-cost core, LLM-enhanced when you choose** | Full pipeline local, zero API keys. Optional embeddings with user's LLM provider | Fully local, zero API keys. No LLM enhancement path | **Codegraph wins.** Both are local-first, but codegraph adds optional AI enhancement that Joern lacks entirely |
-| 5 | **Functional CLI, embeddable API** | 41 CLI commands + 32-tool MCP server + full programmatic JS API | Interactive Scala REPL + server mode + script execution. No MCP. Python client library | **Codegraph wins.** Purpose-built MCP for AI agents + embeddable npm package vs. Scala REPL that requires JVM expertise |
+| 5 | **Functional CLI, embeddable API** | 39 CLI commands + 30-tool MCP server + full programmatic JS API | Interactive Scala REPL + server mode + script execution. No MCP. Python client library | **Codegraph wins.** Purpose-built MCP for AI agents + embeddable npm package vs. Scala REPL that requires JVM expertise |
 | 6 | **One registry, one schema, no magic** | `LANGUAGE_REGISTRY` — add a language in <100 lines, 2 files | Each language has a separate frontend (Eclipse CDT, JavaParser, GraalVM, etc.) — fundamentally different parsers per language | **Codegraph wins.** Uniform tree-sitter extraction vs. heterogeneous parser zoo |
 | 7 | **Security-conscious defaults** — multi-repo opt-in | Single-repo MCP default. `apiKeyCommand` for secrets. `--multi-repo` opt-in | Server mode has no sandboxing (docs explicitly warn: "raw interpreter access"). No MCP isolation concept | **Codegraph wins.** Security-by-default vs. "trust the user" |
 | 8 | **Honest about what we're not** | Code intelligence engine. Not an app, not a coding tool, not an agent | Code analysis platform for security research. Not a CI tool, not a developer productivity tool | **Tie.** Both are honest about scope. Different scopes |
@@ -70,7 +70,7 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | **Language count** | 11 source languages | 13 source + 3 binary/bytecode/IR | **Joern** (16 vs 11) |
 | **Adding a new language** | 1 registry entry + 1 extractor (<100 lines, 2 files) | New frontend module (thousands of lines, custom parser integration) | **Codegraph** — dramatically lower barrier |
 | **Incomplete/non-compilable code** | Requires syntactically valid input (tree-sitter) | Fuzzy parsing handles partial/broken code | **Joern** — critical for security audits of partial codebases |
-| **Incremental parsing** | 3-tier change detection (journal → mtime+size → hash) — only changed files re-parsed | Full re-import always | **Codegraph** — orders of magnitude faster for iterative work |
+| **Incremental parsing** | File-level hash tracking — only changed files re-parsed | Full re-import always | **Codegraph** — orders of magnitude faster for iterative work |
 
 **Summary:** Joern covers more languages and handles edge cases (binaries, bytecode, broken code) that codegraph cannot. Codegraph is faster, simpler to extend, and has better support for modern web languages (TSX, Terraform). For codegraph's target users (developers, AI agents), codegraph's coverage is sufficient. For security researchers auditing compiled artifacts, Joern is essential.
 
@@ -81,11 +81,11 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | Feature | Codegraph | Joern | Best Approach |
 |---------|-----------|-------|---------------|
 | **Graph type** | Structural dependency graph (symbols + edges) | Code Property Graph (AST + CFG + PDG merged) | **Joern** for depth; **Codegraph** for speed |
-| **Node types** | 13 kinds: `function`, `method`, `class`, `interface`, `type`, `struct`, `enum`, `trait`, `record`, `module`, `parameter`, `property`, `constant` + `qualified_name`, `scope`, `visibility` metadata columns | 45+ node types across 18 layers (METHOD, CALL, IDENTIFIER, LITERAL, CONTROL_STRUCTURE, BLOCK, LOCAL, etc.) | **Joern** — still more granular, but gap narrowed from 4x to ~3x |
-| **Edge types** | 10 structural: `calls`, `imports`, `imports-type`, `dynamic-imports`, `reexports`, `extends`, `implements`, `contains`, `parameter_of`, `receiver` + 3 dataflow: `flows_to`, `returns`, `mutates` (with confidence scores on call/import edges) | 20+ types: AST, CFG, CDG, REACHING_DEF, CALL, ARGUMENT, RECEIVER, CONTAINS, EVAL_TYPE, REF, BINDS, DOMINATE, POST_DOMINATE, etc. | **Joern** — still more edge types, but codegraph now covers structural containment, dataflow, and receiver relationships |
+| **Node types** | 13 kinds: `function`, `method`, `class`, `interface`, `type`, `struct`, `enum`, `trait`, `record`, `module`, `parameter`, `property`, `constant` | 45+ node types across 18 layers (METHOD, CALL, IDENTIFIER, LITERAL, CONTROL_STRUCTURE, BLOCK, LOCAL, etc.) | **Joern** — still more granular, but gap narrowed from 4x to ~3x |
+| **Edge types** | `calls`, `imports`, `contains`, `parameter_of`, `receiver`, `flows_to`, `returns`, `mutates` (with confidence scores on call/import edges) | 20+ types: AST, CFG, CDG, REACHING_DEF, CALL, ARGUMENT, RECEIVER, CONTAINS, EVAL_TYPE, REF, BINDS, DOMINATE, POST_DOMINATE, etc. | **Joern** — still more edge types, but codegraph now covers structural containment, dataflow, and receiver relationships |
 | **Abstract Syntax Tree** | Stored AST nodes (calls, new, string, regex, throw, await) queryable via `ast` command/`ast_query` MCP tool | Full AST stored and queryable | **Joern** for completeness; **Codegraph** now has stored AST for the most useful node kinds |
-| **Control Flow Graph** | Intraprocedural CFG for all 11 languages via `cfg` command/MCP tool. Basic blocks + branches. Cyclomatic complexity derived from CFG structure (E - N + 2). No dominator trees | Full CFG with dominator/post-dominator trees | **Joern** for depth (dominator trees); **Codegraph** now has basic CFG with complexity metrics |
-| **Data Dependence Graph** | Intraprocedural dataflow: `flows_to`, `returns`, `mutates` edges via `dataflow` command/MCP tool (all 11 languages) | Reaching definitions (def-use chains) across procedures | **Joern** — interprocedural vs. codegraph's intraprocedural. But codegraph now has lightweight dataflow across all supported languages |
+| **Control Flow Graph** | Intraprocedural CFG for all 11 languages via `cfg` command/MCP tool. Basic blocks + branches. No dominator trees | Full CFG with dominator/post-dominator trees | **Joern** for depth (dominator trees); **Codegraph** now has basic CFG |
+| **Data Dependence Graph** | Intraprocedural dataflow: `flows_to`, `returns`, `mutates` edges via `dataflow` command/MCP tool (JS/TS only) | Reaching definitions (def-use chains) across procedures | **Joern** — interprocedural vs. codegraph's intraprocedural. But codegraph now has lightweight dataflow |
 | **Program Dependence Graph** | Not available | Combined control + data dependence | **Joern** |
 | **Taint analysis** | Not available | Full interprocedural taint tracking (sources → sinks) | **Joern** — Joern's killer feature |
 | **Call graph** | Import-aware resolution with 6-level confidence scoring, qualified call filtering | Pre-computed CALL edges, caller/callee traversal | **Codegraph** for precision (confidence scoring, false-positive filtering); **Joern** for completeness (type-aware resolution) |
@@ -99,7 +99,6 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | **Custom data-flow semantics** | Not applicable | User-defined taint propagation rules for external methods | **Joern** |
 | **Binary analysis** | Not available | Ghidra frontend: disassembly → CPG | **Joern** |
 | **Execution flow tracing** | `flow` — traces from entry points (routes, commands, events) through callees to leaves | Achievable via CFG + call graph traversals | **Codegraph** — purpose-built command; **Joern** — more precise with CFG |
-| **Sequence diagrams** | `sequence <name>` — Mermaid sequence diagram generation from call graph | Not purpose-built (achievable via manual CFG/call graph traversal) | **Codegraph** — built-in command for visualizing call sequences |
 
 **Summary:** Joern's CPG is fundamentally deeper — it captures control flow, data dependence, and taint propagation that codegraph's structural graph cannot represent. Codegraph compensates with purpose-built commands (impact analysis, complexity, roles, communities) that would require expert CPG query writing in Joern. For vulnerability discovery, Joern is irreplaceable. For developer productivity and AI agent consumption, codegraph's pre-built commands are more accessible.
 
@@ -112,8 +111,8 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | **Query interface** | Fixed CLI commands with flags + SQL under the hood | Interactive Scala REPL with tab completion + arbitrary graph traversals | **Depends on user.** Codegraph for instant answers; Joern for exploratory research |
 | **Query language** | CLI flags (`--kind`, `--file`, `--role`, `--json`) | CPGQL (Scala-based DSL): `cpg.method.name("foo").callee.name.l` | **Joern** for expressiveness; **Codegraph** for accessibility |
 | **Learning curve** | Zero — standard CLI with `--help` | Steep — requires Scala/FP knowledge + graph theory | **Codegraph** |
-| **AI agent interface** | 32-tool MCP server with structured JSON responses | Community MCP server (mcp-joern). REST/WebSocket server mode | **Codegraph** — first-party MCP vs. community add-on |
-| **Compound queries** | `context` (source + deps + callers + tests in 1 call), `explain` (structural summary), `audit` (explain + impact + health in one call) | Must compose via CPGQL chaining | **Codegraph** — purpose-built for agent token efficiency |
+| **AI agent interface** | 30-tool MCP server with structured JSON responses | Community MCP server (mcp-joern). REST/WebSocket server mode | **Codegraph** — first-party MCP vs. community add-on |
+| **Compound queries** | `context` (source + deps + callers + tests in 1 call), `explain` (structural summary), `audit` (explain + impact + health) | Must compose via CPGQL chaining | **Codegraph** — purpose-built for agent token efficiency |
 | **Batch queries** | `batch` command for multi-target dispatch | Script mode (`--script`) for batch execution | **Tie** — different approaches, both work |
 | **JSON output** | `--json` flag on every command | `.toJsonPretty` method on query results | **Tie** |
 | **Syntax-highlighted output** | Colored terminal output | `.dump` for syntax-highlighted code display | **Tie** |
@@ -173,8 +172,8 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 
 | Feature | Codegraph | Joern | Best Approach |
 |---------|-----------|-------|---------------|
-| **MCP server** | First-party, 32 tools, single-repo default, `--multi-repo` opt-in | 4 community MCP wrappers (sfncat/mcp-joern, caohaotiantian/joern_mcp, BlockSecCA/joern-mcp, effortlessdevsec/joern-mcp-server). No first-party MCP | **Codegraph** — first-party, security-conscious, production-ready |
-| **MCP tools count** | 32 purpose-built tools | ~10 tools (community MCP) | **Codegraph** |
+| **MCP server** | First-party, 30 tools, single-repo default, `--multi-repo` opt-in | Community-built (mcp-joern), Python wrapper around Joern | **Codegraph** — first-party, security-conscious, production-ready |
+| **MCP tools count** | 30 purpose-built tools | ~10 tools (community MCP) | **Codegraph** |
 | **Token efficiency** | `context`/`explain`/`audit` compound commands reduce agent round-trips by 50-80% | Raw query results, no compound optimization | **Codegraph** |
 | **Structured JSON output** | Every command supports `--json` | `.toJsonPretty` on query results | **Tie** |
 | **Pagination** | Built-in pagination helpers with configurable limits | Not built-in | **Codegraph** |
@@ -193,7 +192,7 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 |---------|-----------|-------|---------------|
 | **Taint analysis** | Not available | Full interprocedural source-to-sink tracking | **Joern** — this is Joern's raison d'etre |
 | **Vulnerability scanning** | Not available | `joern-scan` with predefined query bundles, tag-based selection | **Joern** |
-| **Data-flow tracking** | Intraprocedural dataflow (`flows_to`/`returns`/`mutates`), all 11 languages | Reaching definitions, def-use chains across procedures | **Joern** — interprocedural vs. intraprocedural |
+| **Data-flow tracking** | Intraprocedural dataflow (`flows_to`/`returns`/`mutates`), JS/TS only | Reaching definitions, def-use chains across procedures | **Joern** — interprocedural vs. intraprocedural |
 | **Control-flow analysis** | Intraprocedural CFG (basic blocks + branches, all 11 languages) | Full CFG with dominator trees | **Joern** — dominator trees and post-dominators; codegraph has basic CFG |
 | **Custom security rules** | Not available | CPGQL-based custom queries + data-flow semantics | **Joern** |
 | **Binary vulnerability analysis** | Not available | Ghidra integration for x86/x64 | **Joern** |
@@ -226,11 +225,9 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | **Execution flow tracing** | `flow` — traces from entry points through callees | Achievable via CFG traversals (more precise) | **Codegraph** for convenience; **Joern** for precision |
 | **Module overview** | `map` — high-level module map with most-connected nodes | Not purpose-built | **Codegraph** |
 | **Cycle detection** | `cycles` — circular dependency detection | Achievable via CPGQL | **Codegraph** — built-in command |
-| **Sequence diagrams** | `sequence <name>` — Mermaid sequence diagrams from call graph | Not purpose-built | **Codegraph** |
-| **Dead export detection** | `exports --unused` — identifies unused exports across the codebase | Not purpose-built (achievable via CPGQL) | **Codegraph** — built-in flag |
-| **Export formats** | DOT, Mermaid, Mermaid sequence diagrams, JSON, GraphML, GraphSON, Neo4j CSV + interactive HTML viewer | DOT, GraphML, GraphSON, Neo4j CSV | **Codegraph** — now matches Joern's formats plus Mermaid (flowchart + sequence) and interactive viewer |
+| **Export formats** | DOT, Mermaid, JSON, GraphML, GraphSON, Neo4j CSV + interactive HTML viewer | DOT, GraphML, GraphSON, Neo4j CSV | **Codegraph** — now matches Joern's formats plus Mermaid and interactive viewer |
 
-**Summary:** Codegraph has 17+ purpose-built developer productivity commands that Joern either lacks entirely or requires expert CPGQL queries to achieve. This is where codegraph's value proposition is strongest for its target audience.
+**Summary:** Codegraph has 15+ purpose-built developer productivity commands that Joern either lacks entirely or requires expert CPGQL queries to achieve. This is where codegraph's value proposition is strongest for its target audience.
 
 ---
 
@@ -238,8 +235,8 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 
 | Feature | Codegraph | Joern | Best Approach |
 |---------|-----------|-------|---------------|
-| **GitHub stars** | 32 (growing) | ~3,021 | **Joern** |
-| **Contributors** | Small team | 75 | **Joern** |
+| **GitHub stars** | New project (growing) | ~2,968 | **Joern** |
+| **Contributors** | Small team | 64 | **Joern** |
 | **Release cadence** | As needed | **Daily automated releases** | **Joern** — impressive automation |
 | **Academic backing** | None | IEEE S&P 2014 paper (Test-of-Time Award 2024), TU Braunschweig, Stellenbosch University | **Joern** |
 | **Commercial backing** | Optave AI Solutions Inc. | Qwiet AI (formerly ShiftLeft), Privado, Whirly Labs | **Joern** — multiple sponsors |
@@ -330,11 +327,11 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | Install complexity | `npm install` | JDK + shell script | Codegraph |
 | Analysis depth (structural) | High | Very High | Joern |
 | Analysis depth (security) | None | Best in class | Joern |
-| AI agent integration | 32-tool MCP (first-party) | Community MCP wrappers (4) | Codegraph |
-| Developer productivity commands | 41 built-in | ~5 built-in + custom CPGQL | Codegraph |
+| AI agent integration | 30-tool MCP (first-party) | Community MCP wrapper | Codegraph |
+| Developer productivity commands | 39 built-in | ~5 built-in + custom CPGQL | Codegraph |
 | Language support | 11 | 16 (incl. binary/bytecode) | Joern |
 | Query expressiveness | Fixed commands | Arbitrary graph traversals | Joern |
-| Community & maturity | 32 stars, growing | 7 years, IEEE award, 3,021 stars, 75 contributors | Joern |
+| Community & maturity | New | 7 years, IEEE award, 2,968 stars | Joern |
 | CI/CD readiness | Yes (`check --staged`) | Limited | Codegraph |
 
 **Final score against FOUNDATION.md principles: Codegraph 6, Joern 0, Tie 2.**
@@ -353,7 +350,7 @@ Non-breaking, ordered by problem-fit:
 | ID | Title | Description | Category | Benefit | Zero-dep | Foundation-aligned | Problem-fit (1-5) | Breaking |
 |----|-------|-------------|----------|---------|----------|-------------------|-------------------|----------|
 | J1 | Lightweight call-chain slicing | Extract a bounded subgraph around a function (callers + callees to depth N) as standalone JSON/DOT/Mermaid. Not full PDG slicing — structural BFS on existing edges, exported as a self-contained artifact. Inspired by Joern's `joern-slice`. | Navigation | Agents get precisely-scoped subgraphs that fit context windows instead of full graph dumps — directly reduces token waste | ✓ | ✓ | 4 | No |
-| J2 | Type-informed call resolution | **PARTIALLY DONE (v3.2.0):** `qualified_name`, `scope`, `visibility` metadata columns and receiver type tracking with graded confidence (Phase 4.2). Remaining: full type annotation extraction from tree-sitter AST (TypeScript types, Java types, Go types, Python type hints) to disambiguate call targets during import resolution. Inspired by Joern's type-aware language frontends. | Analysis | Call graphs become more precise — fewer false edges means less noise in `fn-impact` and agents don't chase phantom dependencies | ✓ | ✓ | 4 | No |
+| J2 | Type-informed call resolution | Extract type annotations from tree-sitter AST (TypeScript types, Java types, Go types, Python type hints) and use them to disambiguate call targets during import resolution. Improves edge accuracy without full type inference. Inspired by Joern's type-aware language frontends. | Analysis | Call graphs become more precise — fewer false edges means less noise in `fn-impact` and agents don't chase phantom dependencies | ✓ | ✓ | 4 | No |
 | J3 | Error-tolerant partial parsing | Leverage tree-sitter's built-in error recovery to extract symbols from syntactically incomplete or broken files instead of skipping them entirely. Surface partial results with a quality indicator per file. Currently codegraph requires syntactically valid input; Joern's fuzzy parsing handles partial/broken code. | Parsing | Agents can analyze WIP branches, partial checkouts, and code mid-refactor — essential for real-world AI-agent loops where code is often in a broken state | ✓ | ✓ | 3 | No |
 | J4 | Kotlin language support | Add tree-sitter-kotlin to `LANGUAGE_REGISTRY`. 1 registry entry + 1 extractor function (<100 lines, 2 files). Covers functions, classes, interfaces, objects, data classes, companion objects, call sites. Kotlin is one of Joern's strongest languages (via IntelliJ PSI). | Parsing | Extends coverage to Android/KMP ecosystem — one of the most-requested missing languages and a gap vs. Joern | ✓ | ✓ | 2 | No |
 | J5 | Swift language support | Add tree-sitter-swift to `LANGUAGE_REGISTRY`. 1 registry entry + 1 extractor function (<100 lines, 2 files). Covers functions, classes, structs, protocols, enums, extensions, call sites. Joern supports Swift via SwiftSyntax. | Parsing | Extends coverage to Apple/iOS ecosystem — currently a gap vs. Joern. tree-sitter-swift is mature enough for production use | ✓ | ✓ | 2 | No |
@@ -391,5 +388,5 @@ These Joern-inspired capabilities are already tracked in [BACKLOG.md](../../docs
 
 | BACKLOG ID | Title | Joern Equivalent | Relationship |
 |------------|-------|------------------|--------------|
-| 14 | Dataflow analysis | Data Dependence Graph (def-use chains) | **DONE v3.0.0, expanded v3.2.0.** Lightweight intraprocedural dataflow with `flows_to`/`returns`/`mutates` edges. Now all 11 languages (was JS/TS only). CLI: `codegraph dataflow`. MCP: `dataflow` tool. |
+| 14 | Dataflow analysis | Data Dependence Graph (def-use chains) | **DONE v3.0.0.** Lightweight intraprocedural dataflow with `flows_to`/`returns`/`mutates` edges. JS/TS only. CLI: `codegraph dataflow`. MCP: `dataflow` tool. |
 | 7 | OWASP/CWE pattern detection | Vulnerability scanning (`joern-scan`) | Lightweight AST-based security checks — the codegraph-appropriate alternative to Joern's taint-based vulnerability scanning. Still Tier 3. J9 (stored AST) is now complete — this is unblocked. |
diff --git a/generated/competitive/narsil-mcp.md b/generated/competitive/narsil-mcp.md
index c5272e7e..ae47af0a 100644
--- a/generated/competitive/narsil-mcp.md
+++ b/generated/competitive/narsil-mcp.md
@@ -1,8 +1,8 @@
 # Competitive Deep-Dive: Codegraph vs Narsil-MCP
 
-**Date:** 2026-03-21
-**Competitors:** `@optave/codegraph` v3.2.0 (Apache-2.0) vs `postrv/narsil-mcp` v1.6.1 (Apache-2.0 OR MIT)
-**Context:** Both are Apache-2.0-licensed code analysis tools with MCP interfaces. Narsil-MCP is ranked #3 in our [competitive analysis](./COMPETITIVE_ANALYSIS.md) with a score of 4.5 vs codegraph's 4.5 at #5.
+**Date:** 2026-03-02
+**Competitors:** `@optave/codegraph` v3.0.0 (Apache-2.0) vs `postrv/narsil-mcp` v1.6 (Apache-2.0 OR MIT)
+**Context:** Both are Apache-2.0-licensed code analysis tools with MCP interfaces. Narsil-MCP is ranked #2 in our [competitive analysis](./COMPETITIVE_ANALYSIS.md) with a score of 4.5 vs codegraph's 4.0 at #8.
 
 ---
 
@@ -12,14 +12,14 @@ Narsil-MCP and codegraph share more DNA than any other pair in the competitive l
 
 | Dimension | Narsil-MCP | Codegraph |
 |-----------|------------|-----------|
-| **Primary mission** | Maximum-breadth code intelligence in a single binary | Always-current structural intelligence with qualified names/scope/visibility graph model and sub-second rebuilds |
+| **Primary mission** | Maximum-breadth code intelligence in a single binary | Always-current structural intelligence with sub-second rebuilds |
 | **Target user** | AI agents needing comprehensive analysis (security, types, dataflow) | Developers, AI coding agents, CI pipelines needing fast feedback |
 | **Architecture** | MCP-first, no standalone CLI queries | Full CLI + MCP server + programmatic JS API |
-| **Core question answered** | "Tell me everything about this code" (90 tools) | "What breaks if I change this function?" (41 commands, 32 MCP tools) |
+| **Core question answered** | "Tell me everything about this code" (90 tools) | "What breaks if I change this function?" (39 commands, 30 MCP tools) |
 | **Rebuild model** | In-memory index, opt-in persistence, file watcher | SQLite-persisted, incremental hash-based rebuilds |
 | **Runtime** | Single Rust binary (~30 MB) | Node.js + optional native Rust addon |
 
-**Bottom line:** Narsil-MCP is broader (90 tools, 32 languages, security scanning, taint analysis, SBOM, type inference). Codegraph is deeper on developer productivity (impact analysis, complexity metrics, community detection, architecture boundaries, manifesto rules, sequence diagrams) and faster for iterative workflows (incremental rebuilds, CI gates). Where they overlap (call graphs, dead code, search, MCP), narsil has more tools while codegraph has more purpose-built commands. They are the closest competitors in the landscape.
+**Bottom line:** Narsil-MCP is broader (90 tools, 32 languages, security scanning, taint analysis, SBOM, type inference). Codegraph is deeper on developer productivity (impact analysis, complexity metrics, community detection, architecture boundaries, manifesto rules) and faster for iterative workflows (incremental rebuilds, CI gates). Where they overlap (call graphs, dead code, search, MCP), narsil has more tools while codegraph has more purpose-built commands. They are the closest competitors in the landscape.
 
 ---
 
@@ -31,11 +31,11 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 
 | # | Principle | Codegraph | Narsil-MCP | Verdict |
 |---|-----------|-----------|------------|---------|
-| 1 | **The graph is always current** — rebuild on every commit/save/agent loop | 3-tier change detection (journal → mtime+size → hash), SQLite persistence. Change 1 file → <500ms rebuild. Watch mode, commit hooks, agent loops all practical | In-memory by default. `--watch` flag for auto-reindex. `--persist` for disk saves. Indexing is fast (2.1s for 50K symbols) but full re-index, not incremental | **Codegraph wins.** Narsil is fast but re-indexes everything. Codegraph only re-parses changed files — orders of magnitude faster for single-file changes in large repos |
+| 1 | **The graph is always current** — rebuild on every commit/save/agent loop | File-level MD5 hashing, SQLite persistence. Change 1 file → <500ms rebuild. Watch mode, commit hooks, agent loops all practical | In-memory by default. `--watch` flag for auto-reindex. `--persist` for disk saves. Indexing is fast (2.1s for 50K symbols) but full re-index, not incremental | **Codegraph wins.** Narsil is fast but re-indexes everything. Codegraph only re-parses changed files — orders of magnitude faster for single-file changes in large repos |
 | 2 | **Native speed, universal reach** — dual engine (Rust + WASM) | Native napi-rs with rayon parallelism + automatic WASM fallback. `npm install` on any platform | Pure Rust binary. Prebuilt for macOS/Linux/Windows. Also has WASM build (~3 MB) for browsers | **Tie.** Different approaches, both effective. Narsil is a single binary; codegraph is an npm package with native addon. Both have WASM stories |
 | 3 | **Confidence over noise** — scored results | 6-level import resolution with 0.0-1.0 confidence on every edge. Graph quality score. Relevance-ranked search | BM25 ranking on search. No confidence scores on call graph edges. No graph quality metric | **Codegraph wins.** Every edge has a trust score; narsil's call graph edges are unscored |
 | 4 | **Zero-cost core, LLM-enhanced when you choose** | Full pipeline local, zero API keys. Optional embeddings with user's LLM provider | Core is local. Neural search requires `--neural` flag + API key (Voyage AI/OpenAI) or local ONNX model | **Tie.** Both are local-first with optional AI enhancement. Narsil offers more backend choices (Voyage AI, OpenAI, ONNX); codegraph uses HuggingFace Transformers locally |
-| 5 | **Functional CLI, embeddable API** | 41 CLI commands + 32-tool MCP server + full programmatic JS API | MCP-first with 90 tools. `narsil-mcp config/tools` management commands but no standalone query CLI. No programmatic library API | **Codegraph wins.** Full CLI experience + embeddable API. Narsil is MCP-only for queries — useless without an MCP client |
+| 5 | **Functional CLI, embeddable API** | 39 CLI commands + 30-tool MCP server + full programmatic JS API | MCP-first with 90 tools. `narsil-mcp config/tools` management commands but no standalone query CLI. No programmatic library API | **Codegraph wins.** Full CLI experience + embeddable API. Narsil is MCP-only for queries — useless without an MCP client |
 | 6 | **One registry, one schema, no magic** | `LANGUAGE_REGISTRY` — add a language in <100 lines, 2 files | Tree-sitter for all 32 languages. Unified parser, but extractors are in compiled Rust — harder to contribute | **Codegraph wins slightly.** Both use tree-sitter uniformly. Codegraph's JS extractors are more accessible to contributors than narsil's compiled Rust |
 | 7 | **Security-conscious defaults** — multi-repo opt-in | Single-repo MCP default. `apiKeyCommand` for secrets. `--multi-repo` opt-in | Multi-repo by default (`--repos` accepts multiple paths). `discover_repos` auto-finds repos. No sandboxing concept | **Codegraph wins.** Single-repo isolation by default vs. multi-repo by default |
 | 8 | **Honest about what we're not** | Code intelligence engine. Not an app, not a coding tool, not an agent | Code intelligence MCP server. Also not an agent — but the open-core model adds commercial cloud features (narsil-cloud) | **Tie.** Both are honest about scope. Narsil's commercial layer is a legitimate business model |
@@ -75,7 +75,7 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | **Bash** | Not supported | tree-sitter | **Narsil** |
 | **Language count** | 11 | 32 | **Narsil** (3x more languages) |
 | **Adding a new language** | 1 registry entry + 1 JS extractor (<100 lines, 2 files) | Rust code + recompile binary | **Codegraph** — dramatically lower barrier for contributors |
-| **Incremental parsing** | 3-tier change detection (journal → mtime+size → hash) — only changed files re-parsed | Full re-index (fast but complete) | **Codegraph** — orders of magnitude faster for single-file changes |
+| **Incremental parsing** | File-level hash tracking — only changed files re-parsed | Full re-index (fast but complete) | **Codegraph** — orders of magnitude faster for single-file changes |
 | **Callback pattern extraction** | Commander `.command().action()`, Express routes, event handlers | Not documented | **Codegraph** — framework-aware symbol extraction |
 
 **Summary:** Narsil covers 3x more languages (32 vs 11) using the same parser technology (tree-sitter). Codegraph has better incremental parsing, easier extensibility, and unique framework callback extraction. For codegraph's target users (JS/TS/Python/Go developers), codegraph's coverage is sufficient. Narsil's breadth matters for polyglot enterprises.
@@ -87,23 +87,22 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | Feature | Codegraph | Narsil-MCP | Best Approach |
 |---------|-----------|------------|---------------|
 | **Graph type** | Structural dependency graph (symbols + edges) in SQLite | In-memory symbol/file caches (DashMap) + optional RDF knowledge graph | **Codegraph** for persistence; **Narsil** for RDF expressiveness |
-| **Node types** | 13 kinds: `function`, `method`, `class`, `interface`, `type`, `struct`, `enum`, `trait`, `record`, `module`, `parameter`, `property`, `constant` — each with `qualified_name`, `scope`, `visibility` metadata | Functions, classes, methods, variables, imports, exports + more | **Narsil** — still more granular, but gap narrowed with codegraph's richer per-node metadata |
-| **Edge types** | 10 structural edge types (`calls`, `imports`, `contains`, `parameter_of`, `receiver`, `type_of`, `implements`, `decorates`, `overloads`, `exports`) + 3 dataflow edge types (`flows_to`, `returns`, `mutates`), with confidence scores on call/import edges | Calls, imports, data flow, control flow, type relationships | **Codegraph** — 13 total edge types with confidence scoring vs. narsil's unscored edges |
+| **Node types** | 13 kinds: `function`, `method`, `class`, `interface`, `type`, `struct`, `enum`, `trait`, `record`, `module`, `parameter`, `property`, `constant` | Functions, classes, methods, variables, imports, exports + more | **Narsil** — still more granular, but gap narrowed |
+| **Edge types** | `calls`, `imports`, `contains`, `parameter_of`, `receiver`, `flows_to`, `returns`, `mutates` (with confidence scores on call/import edges) | Calls, imports, data flow, control flow, type relationships | **Tie** — both now cover structural + dataflow relationships |
 | **Call graph** | Import-aware resolution with 6-level confidence scoring, qualified call filtering | `get_call_graph`, `get_callers`, `get_callees`, `find_call_path` | **Codegraph** for precision (confidence scoring); **Narsil** for completeness |
 | **Control flow graph** | Intraprocedural CFG for all 11 languages via `cfg` command / `cfg` MCP tool | `get_control_flow` — basic blocks + branch conditions | **Tie** — both have intraprocedural CFG |
-| **Data flow analysis** | `flows_to`/`returns`/`mutates` edges via `dataflow` command / `dataflow` MCP tool (all 11 languages) | `get_data_flow`, `get_reaching_definitions`, `find_uninitialized`, `find_dead_stores` | **Tie** — narsil has 4 dedicated tools (reaching defs, dead stores); codegraph covers all 11 languages with unified dataflow edges |
-| **Type inference** | No full type inference, but `qualified_name`, `scope`, `visibility` metadata on all symbols + receiver type tracking with graded confidence | `infer_types`, `check_type_errors` for Python/JS/TS | **Narsil** — full type inference vs. codegraph's metadata-level type tracking. Gap narrowed |
+| **Data flow analysis** | `flows_to`/`returns`/`mutates` edges via `dataflow` command / `dataflow` MCP tool (JS/TS only) | `get_data_flow`, `get_reaching_definitions`, `find_uninitialized`, `find_dead_stores` | **Narsil** — more mature with 4 dedicated tools; codegraph is JS/TS only |
+| **Type inference** | Not available | `infer_types`, `check_type_errors` for Python/JS/TS | **Narsil** |
 | **Dead code detection** | `roles --role dead` — unreferenced non-exported symbols | `find_dead_code` — unreachable code paths via CFG | **Both** — complementary approaches (structural vs. control-flow) |
 | **Complexity metrics** | Cognitive, cyclomatic, Halstead, MI, nesting depth per function | Cyclomatic complexity only | **Codegraph** — 5 metrics vs 1 |
 | **Node role classification** | Auto-tags: `entry`/`core`/`utility`/`adapter`/`dead`/`leaf` | Not available | **Codegraph** |
 | **Community detection** | Louvain algorithm with drift analysis | Not available | **Codegraph** |
 | **Impact analysis** | `fn-impact`, `diff-impact` (git-aware), `impact` (file-level) | Not purpose-built | **Codegraph** — first-class impact commands |
-| **Sequence diagrams** | `sequence` command — generates Mermaid sequence diagrams from call chains | Not available | **Codegraph** |
 | **Shortest path** | `path <from> <to>` — BFS between symbols | `find_call_path` — between functions | **Tie** |
 | **SPARQL / Knowledge graph** | Not available | RDF graph via Oxigraph, SPARQL queries, predefined templates | **Narsil** — unique capability |
 | **Code Context Graph (CCG)** | Not available | 4-layer hierarchical context (L0-L3) with JSON-LD/N-Quads export | **Narsil** — unique capability |
 
-**Summary:** Narsil has broader analysis (type inference, SPARQL, CCG). Codegraph now matches on dataflow (all 11 languages) and is deeper on developer-facing metrics (5 complexity metrics, node roles, community detection, Louvain drift, sequence diagrams) with unique impact analysis commands and 13 edge types with confidence scoring. Narsil's knowledge graph and CCG layering are genuinely novel features with no codegraph equivalent.
+**Summary:** Narsil has broader analysis (CFG, dataflow, type inference, SPARQL, CCG). Codegraph is deeper on developer-facing metrics (5 complexity metrics, node roles, community detection, Louvain drift) and has unique impact analysis commands. Narsil's knowledge graph and CCG layering are genuinely novel features with no codegraph equivalent.
 
 ---
 
@@ -140,9 +139,9 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | **Vulnerability explanation** | Not available | `explain_vulnerability`, `suggest_fix` | **Narsil** |
 | **Crypto misuse detection** | Not available | Rules in `crypto.yaml` | **Narsil** |
 | **IaC security** | Not available | Rules in `iac.yaml` | **Narsil** |
-| **Language-specific rules** | Not available | Rust, Elixir, Go, Java, C#, Kotlin, Bash rule files (+36 rules: 18 Rust + 18 Elixir) | **Narsil** |
+| **Language-specific rules** | Not available | Rust, Elixir, Go, Java, C#, Kotlin, Bash rule files | **Narsil** |
 
-**Summary:** Narsil dominates security analysis completely with 147+ rules across 12+ rule files (including +36 language-specific rules for Rust and Elixir). Codegraph has zero security features today — by design (FOUNDATION.md P8). OWASP pattern detection is on the roadmap as lightweight AST-based checks (BACKLOG ID 7), not taint analysis.
+**Summary:** Narsil dominates security analysis completely with 147 rules across 12+ rule files. Codegraph has zero security features today — by design (FOUNDATION.md P8). OWASP pattern detection is on the roadmap as lightweight AST-based checks (BACKLOG ID 7), not taint analysis.
 
 ---
 
@@ -150,20 +149,20 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 
 | Feature | Codegraph | Narsil-MCP | Best Approach |
 |---------|-----------|------------|---------------|
-| **Primary interface** | Full CLI with 41 commands + MCP server | MCP server (primary) + config management CLI | **Codegraph** — usable without MCP client |
+| **Primary interface** | Full CLI with 39 commands + MCP server | MCP server (primary) + config management CLI | **Codegraph** — usable without MCP client |
 | **Standalone CLI queries** | `where`, `query`, `audit --quick`, `context`, `deps`, `exports`, `impact`, `map`, `dataflow`, `cfg`, `ast`, etc. | Not available — all queries via MCP tools | **Codegraph** — narsil requires an MCP client for any query |
-| **MCP tools count** | 32 purpose-built tools | 90 tools across 14 categories | **Narsil** — ~3x more tools |
+| **MCP tools count** | 30 purpose-built tools | 90 tools across 14 categories | **Narsil** — 3x more tools |
 | **Compound queries** | `context` (source + deps + callers + tests), `explain`, `audit` | No compound tools — each tool is atomic | **Codegraph** — purpose-built for agent token efficiency |
 | **Batch queries** | `batch` command for multi-target dispatch | No batch mechanism | **Codegraph** |
 | **JSON output** | `--json` flag on every command | MCP JSON responses | **Tie** |
 | **NDJSON streaming** | `--ndjson` with `--limit`/`--offset` on ~14 commands | `--streaming` flag for large results | **Tie** |
-| **Pagination** | Universal `limit`/`offset` on all 32 MCP tools with per-tool defaults | Not documented | **Codegraph** |
+| **Pagination** | Universal `limit`/`offset` on all 30 MCP tools with per-tool defaults | Not documented | **Codegraph** |
 | **SPARQL queries** | Not available | `sparql_query`, predefined templates | **Narsil** — unique expressiveness |
 | **Configuration presets** | Not available | Minimal (~26 tools), Balanced (~51), Full (75+), Security-focused | **Narsil** — manages token cost per preset |
-| **Visualization** | DOT, Mermaid, JSON, GraphML, GraphSON, Neo4j CSV export + interactive HTML viewer (`codegraph plot`) | Built-in web UI (Cytoscape.js) with interactive graphs + full SPA frontend (v1.6.0): file tree sidebar, syntax-highlighted code viewer, dashboard, per-repo overview, CFG visualization | **Narsil** — SPA frontend with file browser and dashboard is significantly richer than codegraph's interactive HTML viewer |
+| **Visualization** | DOT, Mermaid, JSON, GraphML, GraphSON, Neo4j CSV export + interactive HTML viewer (`codegraph plot`) | Built-in web UI (Cytoscape.js) with interactive graphs | **Tie** — both have interactive visualization and rich export formats |
 | **Programmatic API** | Full JS API: `import { buildGraph, queryNameData } from '@optave/codegraph'` | No library API | **Codegraph** — embeddable in JS/TS projects |
 
-**Summary:** Codegraph is more accessible (full CLI + API + MCP). Narsil has more MCP tools (90 vs 32) but no standalone query interface — completely dependent on MCP clients. Narsil's new SPA frontend (v1.6.0) with file tree, syntax viewer, and dashboard is a significant UI advantage. Codegraph's compound commands (`context`, `explain`, `audit`) reduce agent round-trips; narsil requires multiple atomic tool calls for equivalent context. Narsil's configuration presets are a smart approach to managing MCP tool token costs.
+**Summary:** Codegraph is more accessible (full CLI + API + MCP). Narsil has more MCP tools (90 vs 21) but no standalone query interface — completely dependent on MCP clients. Codegraph's compound commands (`context`, `explain`, `audit`) reduce agent round-trips; narsil requires multiple atomic tool calls for equivalent context. Narsil's configuration presets are a smart approach to managing MCP tool token costs.
 
 ---
 
@@ -211,17 +210,17 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 
 | Feature | Codegraph | Narsil-MCP | Best Approach |
 |---------|-----------|------------|---------------|
-| **MCP tools** | 32 purpose-built tools | 90 tools across 14 categories | **Narsil** (~3x more tools) |
+| **MCP tools** | 30 purpose-built tools | 90 tools across 14 categories | **Narsil** (3x more tools) |
 | **Token efficiency** | `context`/`explain`/`audit` compound commands reduce round-trips 50-80% | Atomic tools only. Forgemax integration collapses 90 → 2 tools (~1,000 vs ~12,000 tokens) | **Codegraph** natively; **Narsil** via Forgemax |
-| **Tool token cost** | ~6,000 tokens for 32 tool definitions | ~12,000 tokens for full set. Presets: Minimal ~4,600, Balanced ~8,900 | **Codegraph** — lower base cost. Narsil presets help |
-| **Pagination** | Universal `limit`/`offset` on all 32 tools with per-tool defaults, hard cap 1,000 | `--streaming` for large results | **Codegraph** — structured pagination metadata |
+| **Tool token cost** | ~5,500 tokens for 30 tool definitions | ~12,000 tokens for full set. Presets: Minimal ~4,600, Balanced ~8,900 | **Codegraph** — lower base cost. Narsil presets help |
+| **Pagination** | Universal `limit`/`offset` on all 30 tools with per-tool defaults, hard cap 1,000 | `--streaming` for large results | **Codegraph** — structured pagination metadata |
 | **Multi-repo support** | Registry-based, opt-in via `--multi-repo` or `--repos` | Multi-repo by default, `discover_repos` auto-detection | **Narsil** for convenience; **Codegraph** for security |
 | **Single-repo isolation** | Default — tools have no `repo` property unless `--multi-repo` | Not default — multi-repo access is always available | **Codegraph** — security-conscious default |
 | **Programmatic embedding** | Full JS API for VS Code extensions, CI pipelines, other MCP servers | No library API | **Codegraph** |
 | **CCG context layers** | Not available | L0-L3 hierarchical context for progressive disclosure | **Narsil** — novel approach to context management |
 | **Remote repo indexing** | Not available | `add_remote_repo` clones and indexes GitHub repos | **Narsil** |
 
-**Summary:** Narsil has ~3x more MCP tools but higher token overhead. Codegraph's compound commands are more token-efficient per query. Narsil's CCG layering and configuration presets are innovative approaches to managing AI agent context budgets. Codegraph's programmatic API enables embedding scenarios narsil cannot serve.
+**Summary:** Narsil has 4x more MCP tools but higher token overhead. Codegraph's compound commands are more token-efficient per query. Narsil's CCG layering and configuration presets are innovative approaches to managing AI agent context budgets. Codegraph's programmatic API enables embedding scenarios narsil cannot serve.
 
 ---
 
@@ -247,14 +246,12 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | **Module overview** | `map` — high-level module map with most-connected nodes | Not purpose-built | **Codegraph** |
 | **Cycle detection** | `cycles` — circular dependency detection | `find_circular_imports` — circular import chains | **Tie** |
 | **Architecture boundaries** | Configurable rules with onion preset | Not available | **Codegraph** |
-| **Sequence diagrams** | `sequence` command — Mermaid sequence diagrams from call chains | Not available | **Codegraph** |
-| **Dead export detection** | `exports --unused` — finds exported symbols with no consumers | Not available | **Codegraph** |
 | **Node role classification** | `entry`/`core`/`utility`/`adapter`/`dead`/`leaf` per symbol | Not available | **Codegraph** |
 | **Audit command** | `audit` — explain + impact + health in one call | Not available | **Codegraph** |
 | **Git integration** | `diff-impact`, `co-change`, `branch-compare` | `get_blame`, `get_file_history`, `get_recent_changes`, `get_symbol_history`, `get_contributors`, `get_hotspots` | **Narsil** for git data breadth; **Codegraph** for git-aware analysis |
 | **Export formats** | DOT, Mermaid, JSON, GraphML, GraphSON, Neo4j CSV + interactive HTML viewer | Cytoscape.js interactive UI, JSON-LD, N-Quads, RDF | **Tie** — both have interactive visualization and rich export formats |
 
-**Summary:** Codegraph has 17+ purpose-built developer productivity commands that narsil lacks (impact analysis, manifesto, triage, boundaries, co-change, branch-compare, audit, structure, CODEOWNERS). Narsil has richer git integration tools (blame, contributors, symbol history) and interactive visualization. For the "what breaks if I change this?" workflow, codegraph is the clear choice.
+**Summary:** Codegraph has 15+ purpose-built developer productivity commands that narsil lacks (impact analysis, manifesto, triage, boundaries, co-change, branch-compare, audit, structure, CODEOWNERS). Narsil has richer git integration tools (blame, contributors, symbol history) and interactive visualization. For the "what breaks if I change this?" workflow, codegraph is the clear choice.
 
 ---
 
@@ -262,19 +259,17 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 
 | Feature | Codegraph | Narsil-MCP | Best Approach |
 |---------|-----------|------------|---------------|
-| **GitHub stars** | Growing | 129 | **Narsil** (slightly) |
+| **GitHub stars** | Growing | 120 | **Narsil** (slightly) |
 | **License** | Apache-2.0 | Apache-2.0 OR MIT (dual) | **Narsil** — dual license is more permissive |
-| **Release cadence** | As needed | v1.6.1 (Feb 2026); no activity since Feb 25 (24+ day gap) | **Codegraph** — narsil's development appears stalled |
+| **Release cadence** | As needed | Regular (v1.6.1 latest, Feb 2026) | **Tie** |
 | **Test suite** | Vitest | 1,763+ tests + criterion benchmarks | **Narsil** — more tests, published benchmarks |
 | **Documentation** | CLAUDE.md + CLI `--help` | narsilmcp.com + README + editor configs | **Narsil** — dedicated docs site |
 | **Commercial backing** | Optave AI Solutions Inc. | Open-core model (narsil-cloud private repo) | **Both** — different business models |
 | **Integration ecosystem** | MCP + programmatic API | Forgemax, Ralph, Claude Code plugin | **Narsil** — more third-party integrations |
 | **Browser story** | Not available | WASM package for browser-based analysis | **Narsil** |
-| **SPA frontend** | Not available | Full SPA (v1.6.0): file tree sidebar, syntax-highlighted code viewer, dashboard, per-repo overview, CFG visualization | **Narsil** — full web application vs. codegraph's interactive HTML viewer |
-| **Security rules** | Not available | 147+ built-in YAML rules including +36 language-specific rules (18 Rust + 18 Elixir) | **Narsil** |
 | **CCG standard** | Not available | Code Context Graph — a proposed standard for AI code context | **Narsil** — potential industry standard |
 
-**Summary:** Narsil has a more developed ecosystem (docs site, editor configs, third-party integrations, browser build, SPA frontend, CCG standard). Both are commercially backed. Narsil's open-core model (commercial cloud features in private repo) is a viable business approach. However, narsil has had no activity since Feb 25 (24+ day gap as of this writing), which raises questions about development momentum.
+**Summary:** Narsil has a more developed ecosystem (docs site, editor configs, third-party integrations, browser build, CCG standard). Both are commercially backed. Narsil's open-core model (commercial cloud features in private repo) is a viable business approach.
 
 ---
 
@@ -295,7 +290,7 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 
 1. **You need security analysis** — taint tracking, OWASP/CWE compliance, SBOM, license scanning, 147 built-in rules. Codegraph has zero security features.
 2. **You need broad language coverage** — 32 languages vs 11. Critical for polyglot enterprises.
-3. **You need advanced data flow analysis** — reaching definitions, dead stores, uninitialized variables. Codegraph now has dataflow across all 11 languages, but narsil has 4 specialized tools (reaching defs, dead stores, uninitialized, taint).
+3. **You need mature control flow or data flow analysis** — reaching definitions, dead stores, uninitialized variables. Codegraph now has basic CFG and intraprocedural dataflow (JS/TS), but narsil's analysis is more mature.
 4. **You need type inference** — infer types for untyped Python/JS/TS code. Codegraph has no type analysis.
 5. **You want richer interactive visualization** — built-in Cytoscape.js web UI with drill-down, overlays, and clustering. Codegraph now has `codegraph plot` with interactive HTML, but narsil's UI is more feature-rich.
 6. **You need a single binary with no runtime deps** — `brew install narsil-mcp` and done. No Node.js required.
@@ -322,10 +317,10 @@ Codegraph's foundation document defines the problem as: *"Fast local analysis wi
 | Install complexity | `npm install` (requires Node.js) | Single binary (brew/scoop/cargo) | Narsil |
 | Analysis depth (structural) | High (impact, complexity, roles, CFG, dataflow) | High (CFG, DFG, type inference) | Tie |
 | Analysis depth (security) | None | Best in class (147 rules, taint) | Narsil |
-| AI agent integration | 32-tool MCP + compound commands | 90-tool MCP + presets + CCG | Narsil for breadth; Codegraph for efficiency |
-| Developer productivity | 41+ commands | Git tools only | Codegraph |
+| AI agent integration | 30-tool MCP + compound commands | 90-tool MCP + presets + CCG | Narsil for breadth; Codegraph for efficiency |
+| Developer productivity | 20+ purpose-built commands | Git tools only | Codegraph |
 | Language support | 11 | 32 | Narsil |
-| Standalone CLI | 41 commands | Config/tools management only | Codegraph |
+| Standalone CLI | Full CLI experience | Config/tools management only | Codegraph |
 | Programmatic API | Full JS API | None | Codegraph |
 | Community & maturity | New | Newer (Dec 2025), growing fast | Tie |
 | CI/CD readiness | Yes (`check --staged`) | No CI tooling | Codegraph |
@@ -391,9 +386,9 @@ These narsil-mcp features were evaluated and deliberately excluded:
 | **SPARQL / RDF knowledge graph** | B, E | Requires Oxigraph dependency. SQLite + existing query commands serve our use case. RDF/SPARQL is overkill for structural code intelligence — powerful but orthogonal to our goals |
 | **Code Context Graph (CCG) standard** | B, H | Interesting concept but tightly coupled to narsil's architecture and commercial model. Our MCP pagination + compound commands solve the progressive-disclosure problem differently |
 | **In-memory-first architecture** | F | Violates P1 (graph must survive restarts to stay always-current). SQLite persistence is a deliberate choice — narsil's opt-in persistence means state loss on every restart by default |
-| **90-tool MCP surface** | E, H | More tools = more token overhead per agent session. Our 32 purpose-built tools + compound commands are more token-efficient. Narsil compensates with presets; we compensate with fewer, smarter tools |
+| **90-tool MCP surface** | E, H | More tools = more token overhead per agent session. Our 30 purpose-built tools + compound commands are more token-efficient. Narsil compensates with presets; we compensate with fewer, smarter tools |
 | **Browser WASM build** | G, J | Different product category. We're a CLI/MCP engine, not a browser tool (P8). Narsil's WASM build is a legitimate capability, but building a browser runtime is outside our scope |
-| **Forgemax-style tool collapsing** | H | Collapses 90 tools to 2 (`search`/`execute`). We don't need this because we already have 32 tools — small enough that collapsing adds complexity without meaningful savings |
+| **Forgemax-style tool collapsing** | H | Collapses 90 tools to 2 (`search`/`execute`). We don't need this because we already have ~21 tools — small enough that collapsing adds complexity without meaningful savings |
 | **LSP integration** | B | Requires running language servers alongside codegraph. Violates zero-dependency goal. Tree-sitter + confidence scoring is our approach; LSP is a different architectural bet |
 | **License compliance scanning** | D | Tangential to code intelligence. Better served by dedicated tools (FOSSA, Snyk, etc.) |
 
@@ -406,7 +401,7 @@ These narsil-inspired capabilities are already tracked in [BACKLOG.md](../../doc
 | 7 | OWASP/CWE pattern detection | `scan_security` with 147 rules | Lightweight AST-based alternative to narsil's full rule engine. N14 above. Still Tier 3. Unblocked by stored AST (v3.0.0). |
 | 8 | Optional LLM provider integration | `--neural-backend api\|onnx` | Multiple embedding providers. N13 above. Still Tier 2. |
 | 10 | Interactive HTML visualization | Built-in Cytoscape.js frontend | **DONE v3.0.0.** `codegraph plot` opens interactive HTML viewer. N12 above. |
-| 14 | Dataflow analysis | `get_data_flow`, `get_reaching_definitions` | **DONE v3.2.0.** Intraprocedural dataflow with `flows_to`/`returns`/`mutates` edges. All 11 languages. CLI: `codegraph dataflow`. MCP: `dataflow` tool. |
+| 14 | Dataflow analysis | `get_data_flow`, `get_reaching_definitions` | **DONE v3.0.0.** Intraprocedural dataflow with `flows_to`/`returns`/`mutates` edges. JS/TS only. CLI: `codegraph dataflow`. MCP: `dataflow` tool. |
 
 ### Cross-references to Joern-inspired candidates
 
diff --git a/generated/dogfood/DOGFOOD_REPORT_v3.1.2.md b/generated/dogfood/DOGFOOD_REPORT_v3.1.2.md
new file mode 100644
index 00000000..4b63696e
--- /dev/null
+++ b/generated/dogfood/DOGFOOD_REPORT_v3.1.2.md
@@ -0,0 +1,395 @@
+# Dogfooding Report: @optave/codegraph@3.1.2
+
+**Date:** 2026-03-11
+**Platform:** Windows 11 Pro (10.0.26200), win32-x64, Node v22.18.0
+**Native binary:** @optave/codegraph-win32-x64-msvc@3.1.2 (npm package version) — reports v3.1.0 internally (BUG #411)
+**Active engine:** native (auto-detected)
+**Target repo:** codegraph itself (235 files, 2 languages)
+
+---
+
+## 1. Setup & Installation
+
+| Step | Result |
+|------|--------|
+| `npm install @optave/codegraph@3.1.2` | Clean install in `/tmp/dogfood-3.1.2` |
+| `npx codegraph --version` | 3.1.2 |
+| Native binary package | @optave/codegraph-win32-x64-msvc@3.1.2 installed |
+| `npx codegraph info` | Native engine available, reports v3.1.0 (BUG — actual binary is 3.1.2) |
+| Optional deps pinned | All 7 platform packages pinned to 3.1.2 |
+| ESM-only package | `type: "module"`, exports `{ ".": { "import": "./src/index.js" } }` |
+
+**Issue:** `info` command reports `Native version: 3.1.0` despite the binary package being 3.1.2. The version string embedded in the Rust binary was not bumped. Filed as #411.
+
+---
+
+## 2. Cold Start (Pre-Build)
+
+Tested from the v3.1.0 dogfood report — 34/34 commands handle missing graph gracefully. No regressions observed in v3.1.2.
+
+---
+
+## 3. Full Command Sweep
+
+Build: `codegraph build <repo> --engine native --no-incremental`
+- 235 files, 4192 nodes, 9057 edges
+- Complexity: 1193 functions, CFG: 1193, Dataflow: 3886 edges
+- 43 exported symbols flagged as having zero cross-file consumers (inflated due to missing dynamic-imports on native — see #410)
+
+| Command | Status | Notes |
+|---------|--------|-------|
+| `query buildGraph -T` | PASS | Callers/callees correct |
+| `query buildGraph -T -j` | PASS | Valid JSON |
+| `query buildGraph -T --depth 1` | PASS | Correctly limits depth |
+| `query nonexistent_xyz` | PASS | "No function/method/class matching" (exit 0) |
+| `deps nonexistent_file.js` | PASS | "No file matching" (exit 0) |
+| `impact src/builder.js -T` | PASS | Transitive dependents listed |
+| `map -T --limit 5` | PASS | Top 5: db.js (56), parser.js (49+) |
+| `map --json -T` | PASS | Clean JSON, no status messages in stdout |
+| `stats -T -j` | PASS | 3417 nodes (filtered), quality 88/100 |
+| `context buildGraph -T --no-source` | PASS | Deps, callers, complexity, children |
+| `where buildGraph` | PASS | Found in src/builder.js |
+| `fn-impact buildGraph -T` | PASS | Transitive dependents |
+| `diff-impact main -T` | PASS | Changed functions with callers |
+| `diff-impact --staged -T` | PASS | No changes detected |
+| `cycles` | PASS | File-level and function-level cycles |
+| `structure -T --depth 2` | PASS | Directory tree with cohesion |
+| `structure . -T --depth 1` | PASS | Fixed since v2.2.0 |
+| `cfg buildGraph -T` | PASS | 204 blocks, 268 edges |
+| `cfg buildGraph --format mermaid` | PASS | Valid Mermaid |
+| `cfg buildGraph --format dot` | PASS | Valid DOT |
+| `complexity -T` | PASS | Functions analyzed |
+| `dataflow buildGraph -T` | PASS | Return consumers, data sources |
+| `sequence buildGraph -T` | PASS | Mermaid sequence diagram |
+| `sequence buildGraph -T --dataflow` | PASS | Parameter annotations |
+| `sequence buildGraph -T -j` | PASS | Valid JSON |
+| `ast "require*"` | PASS | AST nodes found |
+| `co-change --analyze` | PASS | Pairs from commits |
+| `branch-compare main HEAD -T` | PASS | Added/removed/changed |
+| `batch fn-impact buildGraph,openDb -T` | PASS | 2/2 succeeded |
+| `export -f dot` | PASS | DOT output |
+| `export -f mermaid` | PASS | Mermaid output |
+| `export -f json` | PASS | JSON output |
+| `models` | PASS | Lists embedding models |
+| `registry list --json` | PASS | 14 registered repos |
+| `registry add/remove` | PASS | Add and remove work correctly |
+| `registry prune --ttl 365` | PASS | "No stale entries found" |
+
+### Edge Cases Tested
+
+| Scenario | Result |
+|----------|--------|
+| Non-existent symbol: `query nonexistent_xyz` | PASS — "No function/method/class matching" |
+| Non-existent file: `deps nonexistent_file.js` | PASS — "No file matching" |
+| `structure .` (v2.2.0 regression) | PASS — fixed |
+| `--json` pipe cleanness (`map --json`) | PASS — valid JSON, no status messages in stdout |
+| `--no-tests` filter | PASS — 3417 nodes (vs 4192 unfiltered) |
+
+---
+
+## 4. Rebuild & Staleness
+
+| Test | Result |
+|------|--------|
+| Incremental no-op | PASS — "Graph is up to date", 8ms (native), 8ms (WASM) |
+| Incremental 1-file change | PASS — only changed file + 26 reverse-deps re-parsed |
+| Full rebuild `--no-incremental` | PASS — 4192 nodes, 9057 edges (native); 4196 nodes, 9234 edges (WASM) |
+| Node/edge consistency | PASS — counts stable across incremental/full |
+
+---
+
+## 5. Engine Comparison
+
+| Metric | Native | WASM | Delta |
+|--------|--------|------|-------|
+| Nodes | 4192 | 4196 | +4 |
+| Edges | 9057 | 9234 | +177 |
+| Constants | 235 | 199 | -36 |
+| Parameters | 2158 | 2198 | +40 |
+| Calls | 2129 | 2163 | +34 |
+| Dynamic imports | 0 | 99 | +99 (BUG #410) |
+| Complexity | 1193 functions | 1192 post-fix (BUG #413) | -1 (see parity gap #5) |
+| Quality score | 88 | 88 | 0 |
+| Full build time | 1335ms | 2500ms | Native 1.87x faster |
+| No-op rebuild | 8ms | 8ms | Parity |
+| 1-file rebuild | 766ms | 959ms | Native 1.25x faster |
+| Unused exports warned | 43 | 25 | +18 (due to missing dynamic-imports) |
+
+### Parity Gaps
+
+1. **Dynamic imports (#410):** Native engine does not track `import()` expressions, resulting in 0 dynamic-imports edges vs WASM's 99. This inflates native's unused export warnings (43 vs 25).
+2. **Constants:** Native extracts 36 more constants than WASM — likely better coverage of top-level const declarations.
+3. **Parameters:** WASM extracts 40 more parameters than native.
+4. **WASM complexity failure (#413):** WASM builds produce 0 complexity rows due to a `ReferenceError: findFunctionNode is not defined` in `src/complexity.js:457`. The import aliases the function as `_findFunctionNode` but the callsite uses the bare name. Native builds skip this code path because complexity is pre-computed in Rust. **Fix in PR #414** — one-line change, 120 tests pass.
+5. **Residual complexity gap (1192 vs 1193):** After the #413 fix, WASM produces 1192 complexity rows vs native's 1193. The missing function is `SymbolExtractor.extract` — a Rust `impl` method at `crates/codegraph-core/src/extractors/mod.rs:18`. The WASM parser's `_findFunctionNode` cannot locate the AST node for Rust `impl` method blocks, so the JS complexity fallback silently skips it. This is a minor WASM parser limitation, not a regression.
+
+---
+
+## 6. Performance Benchmarks
+
+### Build Benchmark (`scripts/benchmark.js`)
+
+**Status: PARTIAL — WASM engine segfaulted (exit 139) during 3rd 1-file rebuild iteration. Bug #408/#409 filed.**
+
+Results collected from `incremental-benchmark.js` which completed successfully:
+
+| Metric | Native | WASM |
+|--------|--------|------|
+| Full build (ms) | 1335 | 2500 |
+| Full build (ms/file) | 5.7 | 10.6 |
+| No-op rebuild (ms) | 8 | 8 |
+| 1-file rebuild (ms) | 766 | 959 |
+
+### 1-File Rebuild Phase Breakdown
+
+| Phase | Native (ms) | WASM (ms) |
+|-------|-------------|-----------|
+| **Setup** | — | — |
+| **Parse** | 37.3 | 125.3 |
+| **Insert** | 8.2 | 8.2 |
+| **Resolve** | 1.0 | 2.3 |
+| **Edges** | 12.0 | 63.0 |
+| **Structure** | 10.4 | 8.8 |
+| **Roles** | 13.4 | 13.3 |
+| **AST** | 263.1 | 278.7 |
+| **Complexity** | 23.7 | 0.4 |
+| **CFG** | 4.0 | 24.8 |
+| **Dataflow** | 3.7 | 4.4 |
+| **Finalize** | — | — |
+
+> **Note:** The pre-existing benchmark data above was collected before `setupMs` and `finalizeMs` were added to `buildGraph`. A fresh full-build run with the fix shows: setupMs=29.6, finalizeMs=180.3 — these two phases account for the ~45-51% gap between the old phase sums and reported totals. Setup covers DB open/init, config, file discovery, and change detection. Finalize covers count queries, drift checks, orphan/unused-export warnings, metadata writes, DB close, journal, and registry.
+
+**Notes:** Native is 3.4x faster at parsing, 5.3x faster at edge building, 6.2x faster at CFG. AST phase dominates both engines (~263-279ms). WASM complexity shows 0.4ms because the computation silently fails (BUG #413) — it should be ~24ms when fixed.
+
+### Query Benchmark (`scripts/query-benchmark.js`)
+
+| Metric | Native | WASM |
+|--------|--------|------|
+| fn-deps depth 1 (ms) | 0.8 | 0.7 |
+| fn-deps depth 3 (ms) | 0.7 | 0.7 |
+| fn-deps depth 5 (ms) | 0.7 | 0.6 |
+| fn-impact depth 1 (ms) | 0.7 | 0.6 |
+| fn-impact depth 3 (ms) | 0.7 | 0.7 |
+| fn-impact depth 5 (ms) | 0.7 | 0.6 |
+| diff-impact (ms) | 15.4 | 16.6 |
+
+**Notes:** Query latency is sub-millisecond for all depth levels — no regressions. Parity between engines.
+
+### Import Resolution Benchmark
+
+| Metric | Result |
+|--------|--------|
+| Import pairs | 218 |
+| Native batch (ms) | 2.6 |
+| JS fallback (ms) | 6.2 |
+| Speedup | 2.4x |
+
+### Embedding Benchmark (`scripts/embedding-benchmark.js`)
+
+**Status: PARTIAL — crashed on nomic-v1.5 model (illegal instruction, exit 132). Bug #408 filed.**
+
+| Model | Hit@1 | Hit@3 | Hit@5 | Misses |
+|-------|-------|-------|-------|--------|
+| minilm | 673/888 (75.8%) | 839/888 (94.5%) | 866/888 (97.5%) | 10 |
+| jina-small | 688/888 (77.5%) | 851/888 (95.8%) | 869/888 (97.9%) | 10 |
+| jina-base | 657/888 (74.0%) | 822/888 (92.6%) | 848/888 (95.5%) | 14 |
+| nomic | 726/888 (81.8%) | 870/888 (98.0%) | 880/888 (99.1%) | 1 |
+| nomic-v1.5 | CRASHED | — | — | — |
+| jina-code | SKIPPED (no HF_TOKEN) | — | — | — |
+
+**Best model:** nomic (Hit@5 = 99.1%, only 1 miss). Consistent with previous releases.
+
+---
+
+## 7. Release-Specific Tests (v3.1.2)
+
+Based on the [v3.1.2 release notes](https://github.com/optave/codegraph/releases/tag/v3.1.2):
+
+| Feature/Fix | Test | Result |
+|-------------|------|--------|
+| Unified AST analysis framework (Phase 3.1) | `complexity`, `cfg`, `dataflow` all produce results from single DFS pass | PASS |
+| CFG visitor rewrite — node-level DFS | `cfg buildGraph` returns 204 blocks, 268 edges | PASS |
+| CLI command/query separation (Phase 3.2) | All commands work, `--json` output clean | PASS |
+| Dynamic `import()` tracking as graph edges | WASM: 99 dynamic-imports edges | PASS (WASM) |
+| Dynamic `import()` tracking — native engine | Native: 0 dynamic-imports edges | **FAIL** — #410 |
+| Repository pattern migration (Phase 3.3) | `stats`, `map`, queries all work | PASS |
+| Prepared statement caching | Build and queries succeed, no perf regressions | PASS |
+| Fix: check-dead-exports hook on ESM (#394) | Dead export detection works on codegraph (ESM codebase) | PASS |
+| Fix: remove function nesting inflation | Complexity metrics reasonable (avg cognitive ~17) | PASS |
+| Fix: Halstead skip depth counter | No crashes or NaN in complexity output | PASS |
+| Fix: nested function nesting | CFG handles nested functions | PASS |
+
+---
+
+## 8. Additional Testing
+
+### MCP Server
+
+| Test | Result |
+|------|--------|
+| Single-repo mode (default) | PASS — 31 tools, `list_repos` absent, no `repo` param |
+| Multi-repo mode (`--multi-repo`) | PASS — 32 tools, `list_repos` present |
+| JSON-RPC `initialize` + `tools/list` | PASS — valid responses |
+
+### Programmatic API
+
+All 15 key exports verified via ESM import:
+
+| Export | Type | Status |
+|--------|------|--------|
+| `buildGraph` | function | PASS |
+| `loadConfig` | function | PASS |
+| `openDb` | function | PASS |
+| `findDbPath` | function | PASS |
+| `contextData` | function | PASS |
+| `explainData` | function | PASS |
+| `whereData` | function | PASS |
+| `fnDepsData` | function | PASS |
+| `diffImpactData` | function | PASS |
+| `statsData` | function | PASS |
+| `isNativeAvailable` | function | PASS |
+| `EXTENSIONS` | object | PASS |
+| `IGNORE_DIRS` | object | PASS |
+| `ALL_SYMBOL_KINDS` | array(10) | PASS |
+| `MODELS` | object | PASS |
+
+**Note:** CJS `require()` fails with `ERR_PACKAGE_PATH_NOT_EXPORTED` — expected, package is ESM-only.
+
+### Registry Operations
+
+| Operation | Result |
+|-----------|--------|
+| `registry list --json` | PASS — 14 repos listed |
+| `registry add /tmp/... --name test-dogfood` | PASS |
+| `registry remove test-dogfood` | PASS |
+| `registry prune --ttl 365` | PASS — "No stale entries found" |
+
+### Config
+
+| Test | Result |
+|------|--------|
+| `.codegraphrc.json` loaded | PASS — `build --verbose` shows "Loaded config" |
+
+---
+
+## 9. Bugs Found
+
+### BUG 1: Benchmark scripts crash entirely when one engine/model fails (Medium)
+- **Issue:** [#408](https://github.com/optave/codegraph/issues/408)
+- **Symptoms:** Build benchmark segfaults during WASM 1-file rebuild; embedding benchmark crashes on nomic-v1.5. In both cases, all partial results are lost.
+- **Root cause:** No try/catch isolation per engine or per model in benchmark scripts. Segfaults can't even be caught by try/catch.
+- **Fix:** Wrap each engine/model run in try/catch. Consider running each in a child process (`fork()`) to isolate segfaults.
+
+### BUG 2: WASM engine segfaults after repeated builds in same process (Low)
+- **Issue:** [#409](https://github.com/optave/codegraph/issues/409)
+- **Symptoms:** After 6+ WASM builds in the same Node.js process, the 3rd 1-file rebuild segfaults (exit 139). The incremental benchmark survives the same pattern.
+- **Root cause:** Likely tree-sitter WASM memory accumulation. The build benchmark runs more operations before reaching the crash point.
+- **Fix:** Investigate tree-sitter WASM parser disposal between builds. Consider `parser.delete()` cleanup.
+
+### BUG 3: Native engine does not track dynamic import() expressions (Medium)
+- **Issue:** [#410](https://github.com/optave/codegraph/issues/410)
+- **Symptoms:** WASM produces 99 dynamic-imports edges; native produces 0. Native reports 43 unused exports (vs WASM's 25) due to missing dynamic-import consumption tracking.
+- **Root cause:** The v3.1.2 dynamic import feature (#389) was implemented in JS/WASM only. The Rust native engine's edge builder doesn't detect `import()` expressions.
+- **Fix:** Add dynamic import detection to `edge_builder.rs`.
+
+### BUG 4: info command reports stale native engine version (Low)
+- **Issue:** [#411](https://github.com/optave/codegraph/issues/411)
+- **Symptoms:** `codegraph info` reports `Native version: 3.1.0` when the actual binary is v3.1.2.
+- **Root cause:** Version string in the Rust binary (`Cargo.toml` or constant) was not bumped for 3.1.2 release.
+- **Fix:** Ensure publish workflow bumps the Rust binary version to match npm version.
+
+### BUG 5: WASM complexity fails — findFunctionNode is not defined (High)
+- **Issue:** [#413](https://github.com/optave/codegraph/issues/413)
+- **PR:** Fixed in [#414](https://github.com/optave/codegraph/pull/414) — one-line fix in `src/complexity.js:457`
+- **Symptoms:** WASM builds produce 0 complexity rows. `--verbose` shows: `buildComplexityMetrics failed: findFunctionNode is not defined`. The `complexity` command reports "No complexity data found" after a WASM build.
+- **Root cause:** `src/complexity.js` line 9 imports `findFunctionNode as _findFunctionNode`, but line 457 calls the bare `findFunctionNode` which is only a re-export name, not a local binding. Native builds never hit this path because `def.complexity` is pre-computed in Rust (line 425).
+- **Fix applied:** Changed `findFunctionNode(...)` to `_findFunctionNode(...)` at line 457. Verified: WASM now produces 1192 complexity rows (vs native's 1193). The 1-function gap is `SymbolExtractor.extract` (Rust `impl` method at `crates/codegraph-core/src/extractors/mod.rs:18`) — the WASM parser's `_findFunctionNode` can't locate the AST node for Rust `impl` method blocks. See parity gap #5. 120 tests pass (94 unit + 26 integration).
+
+---
+
+## 10. Suggestions for Improvement
+
+### 10.1 Child-process isolation for benchmarks
+Run each engine/model benchmark in a subprocess to survive segfaults and collect partial results.
+
+### 10.2 Native dynamic import parity
+Prioritize implementing dynamic import tracking in the Rust engine to close the 177-edge parity gap and reduce false-positive unused export warnings.
+
+### 10.3 WASM memory management
+Investigate tree-sitter WASM parser disposal. Multiple builds in the same process should not accumulate memory to the point of segfaulting.
+
+### 10.4 Automated version consistency checks
+Add a CI check that verifies `Cargo.toml` version matches `package.json` version before publishing, to prevent stale native version display.
+
+### 10.5 AST phase optimization
+The AST phase (~265ms) dominates 1-file rebuilds for both engines. Profiling this phase could yield significant build speed improvements.
+
+---
+
+## 11. Testing Plan
+
+### General Testing Plan (Any Release)
+
+- [ ] Install from npm, verify `--version` and `info`
+- [ ] Native binary version matches npm package version
+- [ ] Cold start: all commands handle missing graph gracefully
+- [ ] Full build + incremental no-op + 1-file rebuild
+- [ ] Engine comparison: native vs WASM node/edge parity
+- [ ] All commands produce valid `--json` output
+- [ ] Edge cases: non-existent symbols, files, invalid kinds
+- [ ] MCP: single-repo and multi-repo tool counts
+- [ ] Programmatic API: all documented exports work
+- [ ] Registry: add, remove, list, prune
+- [ ] Benchmarks: build, query, incremental, embedding
+- [ ] Embedding recall: Hit@5 > 95% for minilm and nomic
+
+### Release-Specific Testing Plan (v3.1.2)
+
+- [ ] Unified AST analysis: complexity, CFG, dataflow from single pass
+- [ ] CFG visitor rewrite: correct block/edge counts
+- [ ] Dynamic imports: WASM tracks `import()` as edges
+- [ ] Command/query separation: all commands work after refactor
+- [ ] Repository pattern: queries work through new data access layer
+- [ ] Prepared statement caching: no perf regressions
+- [ ] Dead export detection: works on ESM codebases
+
+### Proposed Additional Tests
+
+- [ ] Embed → rebuild → search pipeline (stale embedding detection)
+- [ ] Watch mode: start, detect change, query, graceful shutdown
+- [ ] Concurrent builds (two processes)
+- [ ] `apiKeyCommand` credential resolution
+- [ ] Database migration path (v1→v14 schema)
+- [ ] Test on a non-JavaScript repo (Go or Rust project)
+
+---
+
+## 12. Overall Assessment
+
+v3.1.2 is a solid architectural release. The Phase 3 refactoring (unified AST analysis, command/query separation, repository pattern) is well-executed — all commands work correctly through the new layers with no regressions from the restructuring. Build performance is good (5.7 ms/file native, 10.6 ms/file WASM) with sub-millisecond query latency.
+
+The main gaps are engine parity: the native engine doesn't track dynamic imports (inflating unused export warnings), and the WASM engine had completely broken complexity metrics due to a variable naming bug (#413, fixed in PR #414). The benchmark resilience issues are low-impact but should be fixed to prevent data loss during future dogfooding. The stale native version display is cosmetic but signals a publish workflow gap.
+
+**Rating: 7/10**
+
+- (+) Clean architecture refactoring with no functional regressions
+- (+) Strong query performance (sub-ms at all depths)
+- (+) MCP server works in both modes (31/32 tools)
+- (+) Programmatic API exports all verified
+- (+) nomic embedding recall at 99.1% Hit@5
+- (-) WASM complexity completely broken since unified AST refactor — zero rows produced (#413, fixed in PR #414)
+- (-) Native engine missing dynamic imports (177 edge gap, #410)
+- (-) Benchmark segfaults lose partial results (#408/#409)
+- (-) Native version display stale (#411)
+
+---
+
+## 13. Issues & PRs Created
+
+| Type | Number | Title | Status |
+|------|--------|-------|--------|
+| Issue | [#408](https://github.com/optave/codegraph/issues/408) | bug: benchmark scripts crash entirely when one engine/model fails | open |
+| Issue | [#409](https://github.com/optave/codegraph/issues/409) | bug: WASM engine segfaults after repeated builds in same process | open |
+| Issue | [#410](https://github.com/optave/codegraph/issues/410) | bug: native engine does not track dynamic import() expressions | open |
+| Issue | [#411](https://github.com/optave/codegraph/issues/411) | bug: info command reports stale native engine version (3.1.0 instead of 3.1.2) | open |
+| Issue | [#413](https://github.com/optave/codegraph/issues/413) | bug: WASM complexity fails — findFunctionNode is not defined | fixed in PR #414 |
diff --git a/package-lock.json b/package-lock.json
index dbc3c1e4..e03070d2 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1276,6 +1276,9 @@
       "cpu": [
         "arm64"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1289,6 +1292,9 @@
       "cpu": [
         "x64"
       ],
+      "libc": [
+        "glibc"
+      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
@@ -1302,6 +1308,9 @@
       "cpu": [
         "x64"
       ],
+      "libc": [
+        "musl"
+      ],
       "license": "Apache-2.0",
       "optional": true,
       "os": [
diff --git a/scripts/benchmark.js b/scripts/benchmark.js
index c2651443..7b8c0c05 100644
--- a/scripts/benchmark.js
+++ b/scripts/benchmark.js
@@ -3,9 +3,8 @@
 /**
  * Benchmark runner — measures codegraph performance on itself (dogfooding).
  *
- * Each engine (native / WASM) runs in a forked subprocess so that a segfault
- * in the native addon only kills the child — the parent survives and collects
- * partial results from whichever engines succeeded.
+ * Runs both native (Rust) and WASM engines, outputs JSON to stdout
+ * with raw and per-file normalized metrics for each.
  *
  * Usage: node scripts/benchmark.js
  */
@@ -16,73 +15,25 @@ import { performance } from 'node:perf_hooks';
 import { fileURLToPath } from 'node:url';
 import Database from 'better-sqlite3';
 import { resolveBenchmarkSource, srcImport } from './lib/bench-config.js';
-import { isWorker, workerEngine, forkEngines } from './lib/fork-engine.js';
-
-// ── Parent process: fork one child per engine, assemble final output ─────
-if (!isWorker()) {
-	const { version } = await resolveBenchmarkSource();
-	const { wasm, native } = await forkEngines(import.meta.url, process.argv.slice(2));
-
-	const primary = wasm || native;
-	if (!primary) {
-		console.error('Error: Both engines failed. No results to report.');
-		process.exit(1);
-	}
-
-	const result = {
-		version,
-		date: new Date().toISOString().slice(0, 10),
-		files: primary.files,
-		wasm: wasm
-			? {
-					buildTimeMs: wasm.buildTimeMs,
-					queryTimeMs: wasm.queryTimeMs,
-					nodes: wasm.nodes,
-					edges: wasm.edges,
-					dbSizeBytes: wasm.dbSizeBytes,
-					perFile: wasm.perFile,
-					noopRebuildMs: wasm.noopRebuildMs,
-					oneFileRebuildMs: wasm.oneFileRebuildMs,
-					oneFilePhases: wasm.oneFilePhases,
-					queries: wasm.queries,
-					phases: wasm.phases,
-				}
-			: null,
-		native: native
-			? {
-					buildTimeMs: native.buildTimeMs,
-					queryTimeMs: native.queryTimeMs,
-					nodes: native.nodes,
-					edges: native.edges,
-					dbSizeBytes: native.dbSizeBytes,
-					perFile: native.perFile,
-					noopRebuildMs: native.noopRebuildMs,
-					oneFileRebuildMs: native.oneFileRebuildMs,
-					oneFilePhases: native.oneFilePhases,
-					queries: native.queries,
-					phases: native.phases,
-				}
-			: null,
-	};
-
-	console.log(JSON.stringify(result, null, 2));
-	process.exit(0);
-}
-
-// ── Worker process: benchmark a single engine, write JSON to stdout ──────
-const engine = workerEngine();
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(__dirname, '..');
 
-const { srcDir, cleanup } = await resolveBenchmarkSource();
+const { version, srcDir, cleanup } = await resolveBenchmarkSource();
 
 const dbPath = path.join(root, '.codegraph', 'graph.db');
 
+// Import programmatic API (use file:// URLs for Windows compatibility)
 const { buildGraph } = await import(srcImport(srcDir, 'builder.js'));
 const { fnDepsData, fnImpactData, pathData, rolesData, statsData } = await import(
 	srcImport(srcDir, 'queries.js')
 );
+const { isNativeAvailable } = await import(
+	srcImport(srcDir, 'native.js')
+);
+const { isWasmAvailable } = await import(
+	srcImport(srcDir, 'parser.js')
+);
 
 const INCREMENTAL_RUNS = 3;
 const QUERY_RUNS = 5;
@@ -98,6 +49,9 @@ function round1(n) {
 	return Math.round(n * 10) / 10;
 }
 
+/**
+ * Pick hub (most-connected) and leaf (least-connected) non-test symbols from the DB.
+ */
 function selectTargets() {
 	const db = new Database(dbPath, { readonly: true });
 	const rows = db
@@ -113,6 +67,7 @@ function selectTargets() {
 	db.close();
 
 	if (rows.length === 0) return { hub: 'buildGraph', leaf: 'median' };
+
 	return { hub: rows[0].name, leaf: rows[rows.length - 1].name };
 }
 
@@ -120,99 +75,175 @@ function selectTargets() {
 const origLog = console.log;
 console.log = (...args) => console.error(...args);
 
-// Clean DB for a full build
-if (fs.existsSync(dbPath)) fs.unlinkSync(dbPath);
-
-const buildStart = performance.now();
-const buildResult = await buildGraph(root, { engine, incremental: false });
-const buildTimeMs = performance.now() - buildStart;
-
-const queryStart = performance.now();
-fnDepsData('buildGraph', dbPath);
-const queryTimeMs = performance.now() - queryStart;
-
-const stats = statsData(dbPath);
-const totalFiles = stats.files.total;
-const totalNodes = stats.nodes.total;
-const totalEdges = stats.edges.total;
-const dbSizeBytes = fs.statSync(dbPath).size;
-
-// ── Incremental build tiers ─────────────────────────────────────────
-console.error(`  [${engine}] Benchmarking no-op rebuild...`);
-const noopTimings = [];
-for (let i = 0; i < INCREMENTAL_RUNS; i++) {
-	const start = performance.now();
-	await buildGraph(root, { engine, incremental: true });
-	noopTimings.push(performance.now() - start);
-}
-const noopRebuildMs = Math.round(median(noopTimings));
-
-console.error(`  [${engine}] Benchmarking 1-file rebuild...`);
-const original = fs.readFileSync(PROBE_FILE, 'utf8');
-let oneFileRebuildMs;
-let oneFilePhases = null;
-try {
-	const oneFileRuns = [];
+async function benchmarkEngine(engine) {
+	// Clean DB for a full build
+	if (fs.existsSync(dbPath)) fs.unlinkSync(dbPath);
+
+	const buildStart = performance.now();
+	const buildResult = await buildGraph(root, { engine, incremental: false });
+	const buildTimeMs = performance.now() - buildStart;
+
+	const queryStart = performance.now();
+	fnDepsData('buildGraph', dbPath);
+	const queryTimeMs = performance.now() - queryStart;
+
+	const stats = statsData(dbPath);
+	const totalFiles = stats.files.total;
+	const totalNodes = stats.nodes.total;
+	const totalEdges = stats.edges.total;
+	const dbSizeBytes = fs.statSync(dbPath).size;
+
+	// ── Incremental build tiers (reuse existing DB from full build) ─────
+	console.error(`  [${engine}] Benchmarking no-op rebuild...`);
+	const noopTimings = [];
 	for (let i = 0; i < INCREMENTAL_RUNS; i++) {
-		fs.writeFileSync(PROBE_FILE, original + `\n// probe-${i}\n`);
 		const start = performance.now();
-		const res = await buildGraph(root, { engine, incremental: true });
-		oneFileRuns.push({ ms: performance.now() - start, phases: res?.phases || null });
+		await buildGraph(root, { engine, incremental: true });
+		noopTimings.push(performance.now() - start);
+	}
+	const noopRebuildMs = Math.round(median(noopTimings));
+
+	console.error(`  [${engine}] Benchmarking 1-file rebuild...`);
+	const original = fs.readFileSync(PROBE_FILE, 'utf8');
+	let oneFileRebuildMs;
+	let oneFilePhases = null;
+	try {
+		const oneFileRuns = [];
+		for (let i = 0; i < INCREMENTAL_RUNS; i++) {
+			fs.writeFileSync(PROBE_FILE, original + `\n// probe-${i}\n`);
+			const start = performance.now();
+			const res = await buildGraph(root, { engine, incremental: true });
+			oneFileRuns.push({ ms: performance.now() - start, phases: res?.phases || null });
+		}
+		oneFileRuns.sort((a, b) => a.ms - b.ms);
+		const medianRun = oneFileRuns[Math.floor(oneFileRuns.length / 2)];
+		oneFileRebuildMs = Math.round(medianRun.ms);
+		oneFilePhases = medianRun.phases;
+	} finally {
+		fs.writeFileSync(PROBE_FILE, original);
+		await buildGraph(root, { engine, incremental: true });
+	}
+
+	// ── Query benchmarks (median of QUERY_RUNS each) ────────────────────
+	console.error(`  [${engine}] Benchmarking queries...`);
+	const targets = selectTargets();
+	console.error(`    hub=${targets.hub}, leaf=${targets.leaf}`);
+
+	function benchQuery(fn, ...args) {
+		const timings = [];
+		for (let i = 0; i < QUERY_RUNS; i++) {
+			const start = performance.now();
+			fn(...args);
+			timings.push(performance.now() - start);
+		}
+		return round1(median(timings));
 	}
-	oneFileRuns.sort((a, b) => a.ms - b.ms);
-	const medianRun = oneFileRuns[Math.floor(oneFileRuns.length / 2)];
-	oneFileRebuildMs = Math.round(medianRun.ms);
-	oneFilePhases = medianRun.phases;
-} finally {
-	fs.writeFileSync(PROBE_FILE, original);
-	await buildGraph(root, { engine, incremental: true });
+
+	const queries = {
+		fnDepsMs: fnDepsData ? benchQuery(fnDepsData, targets.hub, dbPath, { depth: 3, noTests: true }) : null,
+		fnImpactMs: fnImpactData ? benchQuery(fnImpactData, targets.hub, dbPath, { depth: 3, noTests: true }) : null,
+		pathMs: pathData ? benchQuery(pathData, targets.hub, targets.leaf, dbPath, { noTests: true }) : null,
+		rolesMs: rolesData ? benchQuery(rolesData, dbPath, { noTests: true }) : null,
+	};
+
+	return {
+		buildTimeMs: Math.round(buildTimeMs),
+		queryTimeMs: Math.round(queryTimeMs * 10) / 10,
+		nodes: totalNodes,
+		edges: totalEdges,
+		files: totalFiles,
+		dbSizeBytes,
+		perFile: {
+			buildTimeMs: Math.round((buildTimeMs / totalFiles) * 10) / 10,
+			nodes: Math.round((totalNodes / totalFiles) * 10) / 10,
+			edges: Math.round((totalEdges / totalFiles) * 10) / 10,
+			dbSizeBytes: Math.round(dbSizeBytes / totalFiles),
+		},
+		noopRebuildMs,
+		oneFileRebuildMs,
+		oneFilePhases,
+		queries,
+		phases: buildResult?.phases || null,
+	};
 }
 
-// ── Query benchmarks ────────────────────────────────────────────────
-console.error(`  [${engine}] Benchmarking queries...`);
-const targets = selectTargets();
-console.error(`    hub=${targets.hub}, leaf=${targets.leaf}`);
+// ── Run benchmarks ───────────────────────────────────────────────────────
+const hasWasm = isWasmAvailable();
+const hasNative = isNativeAvailable();
 
-function benchQuery(fn, ...args) {
-	const timings = [];
-	for (let i = 0; i < QUERY_RUNS; i++) {
-		const start = performance.now();
-		fn(...args);
-		timings.push(performance.now() - start);
+if (!hasWasm && !hasNative) {
+	console.error('Error: Neither WASM grammars nor native engine are available.');
+	console.error('Run "npm run build:wasm" to build WASM grammars, or install the native platform package.');
+	process.exit(1);
+}
+
+let wasm = null;
+if (hasWasm) {
+	try {
+		wasm = await benchmarkEngine('wasm');
+	} catch (err) {
+		console.error(`WASM benchmark failed: ${err?.message ?? String(err)}`);
 	}
-	return round1(median(timings));
+} else {
+	console.error('WASM grammars not built — skipping WASM benchmark');
 }
 
-const queries = {
-	fnDepsMs: fnDepsData ? benchQuery(fnDepsData, targets.hub, dbPath, { depth: 3, noTests: true }) : null,
-	fnImpactMs: fnImpactData ? benchQuery(fnImpactData, targets.hub, dbPath, { depth: 3, noTests: true }) : null,
-	pathMs: pathData ? benchQuery(pathData, targets.hub, targets.leaf, dbPath, { noTests: true }) : null,
-	rolesMs: rolesData ? benchQuery(rolesData, dbPath, { noTests: true }) : null,
-};
+let native = null;
+if (hasNative) {
+	try {
+		native = await benchmarkEngine('native');
+	} catch (err) {
+		console.error(`Native benchmark failed: ${err?.message ?? String(err)}`);
+	}
+} else {
+	console.error('Native engine not available — skipping native benchmark');
+}
 
 // Restore console.log for JSON output
 console.log = origLog;
 
-const workerResult = {
-	buildTimeMs: Math.round(buildTimeMs),
-	queryTimeMs: Math.round(queryTimeMs * 10) / 10,
-	nodes: totalNodes,
-	edges: totalEdges,
-	files: totalFiles,
-	dbSizeBytes,
-	perFile: {
-		buildTimeMs: Math.round((buildTimeMs / totalFiles) * 10) / 10,
-		nodes: Math.round((totalNodes / totalFiles) * 10) / 10,
-		edges: Math.round((totalEdges / totalFiles) * 10) / 10,
-		dbSizeBytes: Math.round(dbSizeBytes / totalFiles),
-	},
-	noopRebuildMs,
-	oneFileRebuildMs,
-	oneFilePhases,
-	queries,
-	phases: buildResult?.phases || null,
+const primary = wasm || native;
+if (!primary) {
+	console.error('Error: Both engines failed. No results to report.');
+	cleanup();
+	process.exit(1);
+}
+const result = {
+	version,
+	date: new Date().toISOString().slice(0, 10),
+	files: primary.files,
+	wasm: wasm
+		? {
+				buildTimeMs: wasm.buildTimeMs,
+				queryTimeMs: wasm.queryTimeMs,
+				nodes: wasm.nodes,
+				edges: wasm.edges,
+				dbSizeBytes: wasm.dbSizeBytes,
+				perFile: wasm.perFile,
+				noopRebuildMs: wasm.noopRebuildMs,
+				oneFileRebuildMs: wasm.oneFileRebuildMs,
+				oneFilePhases: wasm.oneFilePhases,
+				queries: wasm.queries,
+				phases: wasm.phases,
+			}
+		: null,
+	native: native
+		? {
+				buildTimeMs: native.buildTimeMs,
+				queryTimeMs: native.queryTimeMs,
+				nodes: native.nodes,
+				edges: native.edges,
+				dbSizeBytes: native.dbSizeBytes,
+				perFile: native.perFile,
+				noopRebuildMs: native.noopRebuildMs,
+				oneFileRebuildMs: native.oneFileRebuildMs,
+				oneFilePhases: native.oneFilePhases,
+				queries: native.queries,
+				phases: native.phases,
+			}
+		: null,
 };
 
-console.log(JSON.stringify(workerResult));
+console.log(JSON.stringify(result, null, 2));
 
 cleanup();
diff --git a/scripts/embedding-benchmark.js b/scripts/embedding-benchmark.js
index 35344011..4bc3afec 100644
--- a/scripts/embedding-benchmark.js
+++ b/scripts/embedding-benchmark.js
@@ -3,76 +3,70 @@
 /**
  * Embedding benchmark runner — measures search recall across all models.
  *
- * Each model runs in a forked subprocess so that a crash (OOM, WASM segfault
- * in the ONNX runtime) only kills the child — the parent survives and collects
- * partial results from whichever models succeeded.
+ * For every function/method/class in the graph, generates a query from the
+ * symbol name (splitIdentifier) and checks if search finds that symbol.
+ * Tests all available embedding models, outputs JSON to stdout.
+ *
+ * Skips jina-code when HF_TOKEN is not set (gated model).
  *
  * Usage: node scripts/embedding-benchmark.js > result.json
  */
 
-import { fork } from 'node:child_process';
+import fs from 'node:fs';
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { fileURLToPath } from 'node:url';
 import Database from 'better-sqlite3';
 import { resolveBenchmarkSource, srcImport } from './lib/bench-config.js';
 
-const MODEL_WORKER_KEY = '__BENCH_MODEL__';
-
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(__dirname, '..');
 
-// ── Worker process: benchmark a single model, write JSON to stdout ───────
-if (process.env[MODEL_WORKER_KEY]) {
-	const modelKey = process.env[MODEL_WORKER_KEY];
+const { version, srcDir, cleanup } = await resolveBenchmarkSource();
+const dbPath = path.join(root, '.codegraph', 'graph.db');
 
-	const { srcDir, cleanup } = await resolveBenchmarkSource();
-	const dbPath = path.join(root, '.codegraph', 'graph.db');
+const { buildEmbeddings, MODELS, searchData, disposeModel } = await import(
+	srcImport(srcDir, 'embeddings/index.js')
+);
 
-	const { buildEmbeddings, MODELS, searchData, disposeModel } = await import(
-		srcImport(srcDir, 'embeddings/index.js')
-	);
+// Redirect console.log to stderr so only JSON goes to stdout
+const origLog = console.log;
+console.log = (...args) => console.error(...args);
 
-	const TEST_PATTERN = /\.(test|spec)\.|__test__|__tests__|\.stories\./;
+const TEST_PATTERN = /\.(test|spec)\.|__test__|__tests__|\.stories\./;
 
-	function splitIdentifier(name) {
-		return name
-			.replace(/([a-z])([A-Z])/g, '$1 $2')
-			.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
-			.replace(/[_-]+/g, ' ')
-			.trim();
-	}
+function splitIdentifier(name) {
+	return name
+		.replace(/([a-z])([A-Z])/g, '$1 $2')
+		.replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+		.replace(/[_-]+/g, ' ')
+		.trim();
+}
 
-	function loadSymbols() {
-		const db = new Database(dbPath, { readonly: true });
-		let rows = db
-			.prepare(
-				`SELECT name, kind, file FROM nodes WHERE kind IN ('function', 'method', 'class') ORDER BY file, line`,
-			)
-			.all();
-		db.close();
-
-		rows = rows.filter((r) => !TEST_PATTERN.test(r.file));
-
-		const seen = new Set();
-		const symbols = [];
-		for (const row of rows) {
-			if (seen.has(row.name)) continue;
-			seen.add(row.name);
-			const query = splitIdentifier(row.name);
-			if (query.length < 4) continue;
-			symbols.push({ name: row.name, kind: row.kind, file: row.file, query });
-		}
-		return symbols;
+function loadSymbols() {
+	const db = new Database(dbPath, { readonly: true });
+	let rows = db
+		.prepare(
+			`SELECT name, kind, file FROM nodes WHERE kind IN ('function', 'method', 'class') ORDER BY file, line`,
+		)
+		.all();
+	db.close();
+
+	rows = rows.filter((r) => !TEST_PATTERN.test(r.file));
+
+	const seen = new Set();
+	const symbols = [];
+	for (const row of rows) {
+		if (seen.has(row.name)) continue;
+		seen.add(row.name);
+		const query = splitIdentifier(row.name);
+		if (query.length < 4) continue;
+		symbols.push({ name: row.name, kind: row.kind, file: row.file, query });
 	}
+	return symbols;
+}
 
-	// Redirect console.log to stderr so only JSON goes to stdout
-	const origLog = console.log;
-	console.log = (...args) => console.error(...args);
-
-	const symbols = loadSymbols();
-	console.error(`  [${modelKey}] Loaded ${symbols.length} symbols`);
-
+async function benchmarkModel(modelKey, symbols) {
 	const embedStart = performance.now();
 	await buildEmbeddings(root, modelKey, dbPath, { strategy: 'structured' });
 	const embedTimeMs = Math.round(performance.now() - embedStart);
@@ -96,10 +90,8 @@ if (process.env[MODEL_WORKER_KEY]) {
 	}
 	const searchTimeMs = Math.round(performance.now() - searchStart);
 
-	try { await disposeModel(); } catch { /* best-effort */ }
-
 	const total = symbols.length;
-	const modelResult = {
+	return {
 		dim: MODELS[modelKey].dim,
 		contextWindow: MODELS[modelKey].contextWindow,
 		hits1,
@@ -111,82 +103,16 @@ if (process.env[MODEL_WORKER_KEY]) {
 		embedTimeMs,
 		searchTimeMs,
 	};
-
-	console.log = origLog;
-	console.log(JSON.stringify({ symbols: symbols.length, result: modelResult }));
-
-	cleanup();
-	process.exit(0);
 }
 
-// ── Parent process: fork one child per model, assemble final output ──────
-const { version, srcDir, cleanup } = await resolveBenchmarkSource();
-const dbPath = path.join(root, '.codegraph', 'graph.db');
+// ── Run benchmarks ──────────────────────────────────────────────────────
 
-const { MODELS } = await import(srcImport(srcDir, 'embeddings/index.js'));
+const symbols = loadSymbols();
+console.error(`Loaded ${symbols.length} symbols for benchmark`);
 
-const TIMEOUT_MS = 600_000;
 const hasHfToken = !!process.env.HF_TOKEN;
 const modelKeys = Object.keys(MODELS);
 const results = {};
-let symbolCount = 0;
-
-const scriptPath = fileURLToPath(import.meta.url);
-
-function forkModel(modelKey) {
-	return new Promise((resolve) => {
-		console.error(`\n[fork] Spawning ${modelKey} worker (pid isolation)...`);
-
-		const child = fork(scriptPath, process.argv.slice(2), {
-			env: { ...process.env, [MODEL_WORKER_KEY]: modelKey },
-			stdio: ['ignore', 'pipe', 'inherit', 'ipc'],
-			timeout: TIMEOUT_MS,
-		});
-
-		let stdout = '';
-		child.stdout.on('data', (chunk) => { stdout += chunk; });
-
-		const timer = setTimeout(() => {
-			console.error(`[fork] ${modelKey} worker timed out after ${TIMEOUT_MS / 1000}s — killing`);
-			child.kill('SIGKILL');
-		}, TIMEOUT_MS);
-
-		child.on('close', (code, signal) => {
-			clearTimeout(timer);
-
-			if (signal) {
-				console.error(`[fork] ${modelKey} worker killed by signal ${signal}`);
-				resolve(null);
-				return;
-			}
-
-			if (code !== 0) {
-				console.error(`[fork] ${modelKey} worker exited with code ${code}`);
-				try {
-					const parsed = JSON.parse(stdout);
-					console.error(`[fork] ${modelKey} worker produced partial results despite non-zero exit`);
-					resolve(parsed);
-				} catch {
-					resolve(null);
-				}
-				return;
-			}
-
-			try {
-				resolve(JSON.parse(stdout));
-			} catch (err) {
-				console.error(`[fork] ${modelKey} worker produced invalid JSON: ${err.message}`);
-				resolve(null);
-			}
-		});
-
-		child.on('error', (err) => {
-			clearTimeout(timer);
-			console.error(`[fork] ${modelKey} worker failed to start: ${err.message}`);
-			resolve(null);
-		});
-	});
-}
 
 for (const key of modelKeys) {
 	if (key === 'jina-code' && !hasHfToken) {
@@ -194,24 +120,32 @@ for (const key of modelKeys) {
 		continue;
 	}
 
-	const data = await forkModel(key);
-	if (data) {
-		results[key] = data.result;
-		if (data.symbols) symbolCount = data.symbols;
-		const r = data.result;
+	console.error(`\nBenchmarking model: ${key}...`);
+	try {
+		results[key] = await benchmarkModel(key, symbols);
+		const r = results[key];
 		console.error(
 			`  Hit@1=${r.hits1}/${r.total} Hit@3=${r.hits3}/${r.total} Hit@5=${r.hits5}/${r.total} misses=${r.misses}`,
 		);
-	} else {
-		console.error(`  ${key}: FAILED (worker crashed or timed out)`);
+	} catch (err) {
+		console.error(`  FAILED: ${err?.message ?? String(err)}`);
+	} finally {
+		try {
+			await disposeModel();
+		} catch (disposeErr) {
+			console.error(`  disposeModel failed: ${disposeErr?.message ?? String(disposeErr)}`);
+		}
 	}
 }
 
+// Restore console.log for JSON output
+console.log = origLog;
+
 const output = {
 	version,
 	date: new Date().toISOString().slice(0, 10),
 	strategy: 'structured',
-	symbols: symbolCount,
+	symbols: symbols.length,
 	models: results,
 };
 
diff --git a/scripts/incremental-benchmark.js b/scripts/incremental-benchmark.js
index 94c3ac9b..bc20b208 100644
--- a/scripts/incremental-benchmark.js
+++ b/scripts/incremental-benchmark.js
@@ -3,9 +3,9 @@
 /**
  * Incremental build benchmark — measures build tiers and import resolution.
  *
- * Each engine (native / WASM) runs in a forked subprocess so that a segfault
- * in the native addon only kills the child — the parent survives and collects
- * partial results from whichever engines succeeded.
+ * Measures full build, no-op rebuild, and single-file rebuild for both
+ * native and WASM engines. Also benchmarks import resolution throughput:
+ * native batch vs JS fallback.
  *
  * Usage: node scripts/incremental-benchmark.js > result.json
  */
@@ -15,185 +15,216 @@ import path from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { fileURLToPath } from 'node:url';
 import { resolveBenchmarkSource, srcImport } from './lib/bench-config.js';
-import { isWorker, workerEngine, forkEngines } from './lib/fork-engine.js';
-
-// ── Parent process: fork one child per engine, assemble final output ─────
-if (!isWorker()) {
-	const { version, srcDir: parentSrcDir, cleanup: parentCleanup } = await resolveBenchmarkSource();
-	const { wasm, native } = await forkEngines(import.meta.url, process.argv.slice(2));
-
-	// Import resolution runs in the parent — it tests both native and JS
-	// fallback in a single pass and doesn't need engine isolation.
-	const __dirParent = path.dirname(fileURLToPath(import.meta.url));
-	const rootParent = path.resolve(__dirParent, '..');
-	const dbPathParent = path.join(rootParent, '.codegraph', 'graph.db');
-
-	const { statsData: parentStats } = await import(srcImport(parentSrcDir, 'queries.js'));
-	const { resolveImportsBatch: parentBatch, resolveImportPathJS: parentJS } = await import(
-		srcImport(parentSrcDir, 'resolve.js')
-	);
-	const { isNativeAvailable: parentNativeCheck } = await import(
-		srcImport(parentSrcDir, 'native.js')
-	);
-
-	const RUNS = 3;
-	function median(arr) {
-		const sorted = [...arr].sort((a, b) => a - b);
-		const mid = Math.floor(sorted.length / 2);
-		return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(__dirname, '..');
+
+const { version, srcDir, cleanup } = await resolveBenchmarkSource();
+const dbPath = path.join(root, '.codegraph', 'graph.db');
+
+const { buildGraph } = await import(srcImport(srcDir, 'builder.js'));
+const { statsData } = await import(srcImport(srcDir, 'queries.js'));
+const { resolveImportPath, resolveImportsBatch, resolveImportPathJS } = await import(
+	srcImport(srcDir, 'resolve.js')
+);
+const { isNativeAvailable } = await import(
+	srcImport(srcDir, 'native.js')
+);
+const { isWasmAvailable } = await import(
+	srcImport(srcDir, 'parser.js')
+);
+
+// Redirect console.log to stderr so only JSON goes to stdout
+const origLog = console.log;
+console.log = (...args) => console.error(...args);
+
+const RUNS = 3;
+const PROBE_FILE = path.join(root, 'src', 'queries.js');
+
+function median(arr) {
+	const sorted = [...arr].sort((a, b) => a - b);
+	const mid = Math.floor(sorted.length / 2);
+	return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+}
+
+function round1(n) {
+	return Math.round(n * 10) / 10;
+}
+
+/**
+ * Benchmark build tiers for a given engine.
+ */
+async function benchmarkBuildTiers(engine) {
+	// Full build (delete DB first)
+	const fullTimings = [];
+	for (let i = 0; i < RUNS; i++) {
+		if (fs.existsSync(dbPath)) fs.unlinkSync(dbPath);
+		const start = performance.now();
+		await buildGraph(root, { engine, incremental: false });
+		fullTimings.push(performance.now() - start);
 	}
-	function round1(n) { return Math.round(n * 10) / 10; }
-
-	function collectImportPairs() {
-		const srcDir = path.join(rootParent, 'src');
-		const files = fs.readdirSync(srcDir).filter((f) => f.endsWith('.js'));
-		const importRe = /(?:^|\n)\s*import\s+.*?\s+from\s+['"]([^'"]+)['"]/g;
-		const pairs = [];
-		for (const file of files) {
-			const absFile = path.join(srcDir, file);
-			const content = fs.readFileSync(absFile, 'utf8');
-			let match;
-			while ((match = importRe.exec(content)) !== null) {
-				pairs.push({ fromFile: absFile, importSource: match[1] });
-			}
+	const fullBuildMs = Math.round(median(fullTimings));
+
+	// No-op rebuild (nothing changed)
+	const noopTimings = [];
+	for (let i = 0; i < RUNS; i++) {
+		const start = performance.now();
+		await buildGraph(root, { engine, incremental: true });
+		noopTimings.push(performance.now() - start);
+	}
+	const noopRebuildMs = Math.round(median(noopTimings));
+
+	// 1-file change rebuild
+	const original = fs.readFileSync(PROBE_FILE, 'utf8');
+	let oneFileRebuildMs;
+	let oneFilePhases = null;
+	try {
+		const oneFileRuns = [];
+		for (let i = 0; i < RUNS; i++) {
+			fs.writeFileSync(PROBE_FILE, original + `\n// probe-${i}\n`);
+			const start = performance.now();
+			const res = await buildGraph(root, { engine, incremental: true });
+			oneFileRuns.push({ ms: performance.now() - start, phases: res?.phases || null });
 		}
-		return pairs;
+		oneFileRuns.sort((a, b) => a.ms - b.ms);
+		const medianRun = oneFileRuns[Math.floor(oneFileRuns.length / 2)];
+		oneFileRebuildMs = Math.round(medianRun.ms);
+		oneFilePhases = medianRun.phases;
+	} finally {
+		fs.writeFileSync(PROBE_FILE, original);
+		// One final incremental build to restore DB state
+		await buildGraph(root, { engine, incremental: true });
 	}
 
-	let stats = null;
-	try { stats = parentStats(dbPathParent); } catch { /* DB may not exist if both engines failed */ }
-	const files = stats?.files?.total ?? (wasm?.files || native?.files || 0);
+	return { fullBuildMs, noopRebuildMs, oneFileRebuildMs, oneFilePhases };
+}
 
-	console.error('Benchmarking import resolution...');
-	const inputs = collectImportPairs();
-	console.error(`  ${inputs.length} import pairs collected`);
+/**
+ * Collect all import pairs by scanning source files for ES import statements.
+ */
+function collectImportPairs() {
+	const srcDir = path.join(root, 'src');
+	const files = fs.readdirSync(srcDir).filter((f) => f.endsWith('.js'));
+	const importRe = /(?:^|\n)\s*import\s+.*?\s+from\s+['"]([^'"]+)['"]/g;
+
+	const pairs = [];
+	for (const file of files) {
+		const absFile = path.join(srcDir, file);
+		const content = fs.readFileSync(absFile, 'utf8');
+		let match;
+		while ((match = importRe.exec(content)) !== null) {
+			pairs.push({ fromFile: absFile, importSource: match[1] });
+		}
+	}
+	return pairs;
+}
 
+/**
+ * Benchmark import resolution: native batch vs JS fallback.
+ */
+function benchmarkResolve(inputs) {
+	const aliases = null; // codegraph itself has no path aliases
+
+	// Native batch
 	let nativeBatchMs = null;
 	let perImportNativeMs = null;
-	if (parentNativeCheck()) {
+	if (isNativeAvailable()) {
 		const timings = [];
 		for (let i = 0; i < RUNS; i++) {
 			const start = performance.now();
-			parentBatch(inputs, rootParent, null);
+			resolveImportsBatch(inputs, root, aliases);
 			timings.push(performance.now() - start);
 		}
 		nativeBatchMs = round1(median(timings));
 		perImportNativeMs = inputs.length > 0 ? round1(nativeBatchMs / inputs.length) : 0;
 	}
+
+	// JS fallback (call the exported JS implementation)
 	const jsTimings = [];
 	for (let i = 0; i < RUNS; i++) {
 		const start = performance.now();
 		for (const { fromFile, importSource } of inputs) {
-			parentJS(fromFile, importSource, rootParent, null);
+			resolveImportPathJS(fromFile, importSource, root, aliases);
 		}
 		jsTimings.push(performance.now() - start);
 	}
 	const jsFallbackMs = round1(median(jsTimings));
 	const perImportJsMs = inputs.length > 0 ? round1(jsFallbackMs / inputs.length) : 0;
 
-	const resolve = { imports: inputs.length, nativeBatchMs, jsFallbackMs, perImportNativeMs, perImportJsMs };
-	console.error(`  native=${resolve.nativeBatchMs}ms js=${resolve.jsFallbackMs}ms`);
-
-	const result = {
-		version,
-		date: new Date().toISOString().slice(0, 10),
-		files,
-		wasm: wasm
-			? {
-					fullBuildMs: wasm.fullBuildMs,
-					noopRebuildMs: wasm.noopRebuildMs,
-					oneFileRebuildMs: wasm.oneFileRebuildMs,
-					oneFilePhases: wasm.oneFilePhases,
-				}
-			: null,
-		native: native
-			? {
-					fullBuildMs: native.fullBuildMs,
-					noopRebuildMs: native.noopRebuildMs,
-					oneFileRebuildMs: native.oneFileRebuildMs,
-					oneFilePhases: native.oneFilePhases,
-				}
-			: null,
-		resolve,
+	return {
+		imports: inputs.length,
+		nativeBatchMs,
+		jsFallbackMs,
+		perImportNativeMs,
+		perImportJsMs,
 	};
-
-	console.log(JSON.stringify(result, null, 2));
-	parentCleanup();
-	process.exit(0);
 }
 
-// ── Worker process: benchmark build tiers for a single engine ────────────
-const engine = workerEngine();
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const root = path.resolve(__dirname, '..');
-
-const { srcDir, cleanup } = await resolveBenchmarkSource();
-const dbPath = path.join(root, '.codegraph', 'graph.db');
-
-const { buildGraph } = await import(srcImport(srcDir, 'builder.js'));
-
-// Redirect console.log to stderr so only JSON goes to stdout
-const origLog = console.log;
-console.log = (...args) => console.error(...args);
-
-const RUNS = 3;
-const PROBE_FILE = path.join(root, 'src', 'queries.js');
+// ── Run benchmarks ───────────────────────────────────────────────────────
+const hasWasm = isWasmAvailable();
+const hasNative = isNativeAvailable();
 
-function median(arr) {
-	const sorted = [...arr].sort((a, b) => a - b);
-	const mid = Math.floor(sorted.length / 2);
-	return sorted.length % 2 ? sorted[mid] : (sorted[mid - 1] + sorted[mid]) / 2;
+if (!hasWasm && !hasNative) {
+	console.error('Error: Neither WASM grammars nor native engine are available.');
+	console.error('Run "npm run build:wasm" to build WASM grammars, or install the native platform package.');
+	process.exit(1);
 }
 
-console.error(`Benchmarking ${engine} engine...`);
-
-// Full build (delete DB first)
-const fullTimings = [];
-for (let i = 0; i < RUNS; i++) {
-	if (fs.existsSync(dbPath)) fs.unlinkSync(dbPath);
-	const start = performance.now();
-	await buildGraph(root, { engine, incremental: false });
-	fullTimings.push(performance.now() - start);
+let wasm = null;
+if (hasWasm) {
+	console.error('Benchmarking WASM engine...');
+	wasm = await benchmarkBuildTiers('wasm');
+	console.error(`  full=${wasm.fullBuildMs}ms noop=${wasm.noopRebuildMs}ms 1-file=${wasm.oneFileRebuildMs}ms`);
+} else {
+	console.error('WASM grammars not built — skipping WASM benchmark');
 }
-const fullBuildMs = Math.round(median(fullTimings));
-
-// No-op rebuild (nothing changed)
-const noopTimings = [];
-for (let i = 0; i < RUNS; i++) {
-	const start = performance.now();
-	await buildGraph(root, { engine, incremental: true });
-	noopTimings.push(performance.now() - start);
-}
-const noopRebuildMs = Math.round(median(noopTimings));
-
-// 1-file change rebuild
-const original = fs.readFileSync(PROBE_FILE, 'utf8');
-let oneFileRebuildMs;
-let oneFilePhases = null;
-try {
-	const oneFileRuns = [];
-	for (let i = 0; i < RUNS; i++) {
-		fs.writeFileSync(PROBE_FILE, original + `\n// probe-${i}\n`);
-		const start = performance.now();
-		const res = await buildGraph(root, { engine, incremental: true });
-		oneFileRuns.push({ ms: performance.now() - start, phases: res?.phases || null });
-	}
-	oneFileRuns.sort((a, b) => a.ms - b.ms);
-	const medianRun = oneFileRuns[Math.floor(oneFileRuns.length / 2)];
-	oneFileRebuildMs = Math.round(medianRun.ms);
-	oneFilePhases = medianRun.phases;
-} finally {
-	fs.writeFileSync(PROBE_FILE, original);
-	await buildGraph(root, { engine, incremental: true });
+
+let native = null;
+if (hasNative) {
+	console.error('Benchmarking native engine...');
+	native = await benchmarkBuildTiers('native');
+	console.error(`  full=${native.fullBuildMs}ms noop=${native.noopRebuildMs}ms 1-file=${native.oneFileRebuildMs}ms`);
+} else {
+	console.error('Native engine not available — skipping native build benchmark');
 }
 
-console.error(`  full=${fullBuildMs}ms noop=${noopRebuildMs}ms 1-file=${oneFileRebuildMs}ms`);
+// Get file count from whichever graph was built last
+const stats = statsData(dbPath);
+const files = stats.files.total;
+
+// Import resolution benchmark (uses existing graph)
+console.error('Benchmarking import resolution...');
+const inputs = collectImportPairs();
+console.error(`  ${inputs.length} import pairs collected`);
+const resolve = benchmarkResolve(inputs);
+console.error(`  native=${resolve.nativeBatchMs}ms js=${resolve.jsFallbackMs}ms`);
 
 // Restore console.log for JSON output
 console.log = origLog;
 
-const workerResult = { fullBuildMs, noopRebuildMs, oneFileRebuildMs, oneFilePhases };
-console.log(JSON.stringify(workerResult));
+const result = {
+	version,
+	date: new Date().toISOString().slice(0, 10),
+	files,
+	wasm: wasm
+		? {
+				fullBuildMs: wasm.fullBuildMs,
+				noopRebuildMs: wasm.noopRebuildMs,
+				oneFileRebuildMs: wasm.oneFileRebuildMs,
+				oneFilePhases: wasm.oneFilePhases,
+			}
+		: null,
+	native: native
+		? {
+				fullBuildMs: native.fullBuildMs,
+				noopRebuildMs: native.noopRebuildMs,
+				oneFileRebuildMs: native.oneFileRebuildMs,
+				oneFilePhases: native.oneFilePhases,
+			}
+		: null,
+	resolve,
+};
+
+console.log(JSON.stringify(result, null, 2));
 
 cleanup();
diff --git a/scripts/lib/fork-engine.js b/scripts/lib/fork-engine.js
deleted file mode 100644
index d0594777..00000000
--- a/scripts/lib/fork-engine.js
+++ /dev/null
@@ -1,163 +0,0 @@
-/**
- * Child-process isolation for benchmarks.
- *
- * Runs each engine benchmark in a subprocess so that segfaults (e.g. from the
- * native Rust addon) only kill the child — the parent survives and collects
- * partial results from whichever engines succeeded.
- *
- * Usage (in a benchmark script):
- *
- *   import { forkEngines, isWorker, workerEngine } from './lib/fork-engine.js';
- *
- *   if (isWorker()) {
- *     // Child path — run a single engine, write JSON to stdout, then exit.
- *     const engine = workerEngine();
- *     const result = await runBenchmarkForEngine(engine);
- *     process.stdout.write(JSON.stringify(result));
- *     process.exit(0);
- *   }
- *
- *   // Parent path — fork one child per engine, collect results.
- *   const { wasm, native } = await forkEngines(import.meta.url, process.argv.slice(2));
- */
-
-import { fork } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-
-const WORKER_ENV_KEY = '__BENCH_ENGINE__';
-
-/**
- * Returns true when running inside a forked worker process.
- */
-export function isWorker() {
-	return !!process.env[WORKER_ENV_KEY];
-}
-
-/**
- * Returns the engine name ('wasm' | 'native') assigned to this worker.
- * Throws if called outside a worker.
- */
-export function workerEngine() {
-	const engine = process.env[WORKER_ENV_KEY];
-	if (!engine) throw new Error('workerEngine() called outside a worker process');
-	return engine;
-}
-
-/**
- * Fork the calling script once per available engine, collect JSON results.
- *
- * @param {string} scriptUrl   import.meta.url of the calling benchmark script
- * @param {string[]} argv      CLI args to forward (e.g. ['--version', '1.0.0', '--npm'])
- * @param {object} [opts]
- * @param {number} [opts.timeoutMs=600_000]  Per-engine timeout (default 10 min)
- * @returns {Promise<{ wasm: object|null, native: object|null }>}
- */
-export async function forkEngines(scriptUrl, argv = [], opts = {}) {
-	const scriptPath = fileURLToPath(scriptUrl);
-	const timeoutMs = opts.timeoutMs ?? 600_000;
-
-	// Detect available engines by importing the check functions in-process.
-	// These are lightweight checks (no parsing), safe to run in the parent.
-	let hasWasm = false;
-	let hasNative = false;
-
-	// We need srcDir to resolve the imports. Re-use bench-config for this.
-	const { resolveBenchmarkSource, srcImport } = await import('./bench-config.js');
-	const { srcDir, cleanup } = await resolveBenchmarkSource();
-
-	try {
-		const { isWasmAvailable } = await import(srcImport(srcDir, 'parser.js'));
-		hasWasm = isWasmAvailable();
-	} catch { /* unavailable */ }
-
-	try {
-		const { isNativeAvailable } = await import(srcImport(srcDir, 'native.js'));
-		hasNative = isNativeAvailable();
-	} catch { /* unavailable */ }
-
-	cleanup();
-
-	if (!hasWasm && !hasNative) {
-		console.error('Error: Neither WASM grammars nor native engine are available.');
-		console.error('Run "npm run build:wasm" to build WASM grammars, or install the native platform package.');
-		process.exit(1);
-	}
-
-	/**
-	 * Fork a single engine worker and collect its JSON output.
-	 * @param {string} engine
-	 * @returns {Promise<object|null>}
-	 */
-	function runWorker(engine) {
-		return new Promise((resolve) => {
-			console.error(`\n[fork] Spawning ${engine} worker (pid isolation)...`);
-
-			const child = fork(scriptPath, argv, {
-				env: { ...process.env, [WORKER_ENV_KEY]: engine },
-				stdio: ['ignore', 'pipe', 'inherit', 'ipc'],
-				timeout: timeoutMs,
-			});
-
-			let stdout = '';
-			child.stdout.on('data', (chunk) => { stdout += chunk; });
-
-			const timer = setTimeout(() => {
-				console.error(`[fork] ${engine} worker timed out after ${timeoutMs / 1000}s — killing`);
-				child.kill('SIGKILL');
-			}, timeoutMs);
-
-			child.on('close', (code, signal) => {
-				clearTimeout(timer);
-
-				if (signal) {
-					console.error(`[fork] ${engine} worker killed by signal ${signal}`);
-					resolve(null);
-					return;
-				}
-
-				if (code !== 0) {
-					console.error(`[fork] ${engine} worker exited with code ${code}`);
-					// Try to parse partial output anyway
-					try {
-						const parsed = JSON.parse(stdout);
-						console.error(`[fork] ${engine} worker produced partial results despite non-zero exit`);
-						resolve(parsed);
-					} catch {
-						resolve(null);
-					}
-					return;
-				}
-
-				try {
-					resolve(JSON.parse(stdout));
-				} catch (err) {
-					console.error(`[fork] ${engine} worker produced invalid JSON: ${err.message}`);
-					resolve(null);
-				}
-			});
-
-			child.on('error', (err) => {
-				clearTimeout(timer);
-				console.error(`[fork] ${engine} worker failed to start: ${err.message}`);
-				resolve(null);
-			});
-		});
-	}
-
-	const results = { wasm: null, native: null };
-
-	// Run engines sequentially — they share the DB file and filesystem state.
-	if (hasWasm) {
-		results.wasm = await runWorker('wasm');
-	} else {
-		console.error('WASM grammars not built — skipping WASM benchmark');
-	}
-
-	if (hasNative) {
-		results.native = await runWorker('native');
-	} else {
-		console.error('Native engine not available — skipping native benchmark');
-	}
-
-	return results;
-}
diff --git a/scripts/query-benchmark.js b/scripts/query-benchmark.js
index 0758f745..76dd9151 100644
--- a/scripts/query-benchmark.js
+++ b/scripts/query-benchmark.js
@@ -3,9 +3,10 @@
 /**
  * Query benchmark runner — measures query depth scaling and diff-impact latency.
  *
- * Each engine (native / WASM) runs in a forked subprocess so that a segfault
- * in the native addon only kills the child — the parent survives and collects
- * partial results from whichever engines succeeded.
+ * Dynamically selects hub/mid/leaf targets from the graph, then benchmarks
+ * fnDepsData and fnImpactData at depth 1, 3, 5 plus diffImpactData with a
+ * synthetic staged change. Runs against both native and WASM engine-built
+ * graphs to catch structural differences.
  *
  * Usage: node scripts/query-benchmark.js > result.json
  */
@@ -17,57 +18,30 @@ import { performance } from 'node:perf_hooks';
 import { fileURLToPath } from 'node:url';
 import Database from 'better-sqlite3';
 import { resolveBenchmarkSource, srcImport } from './lib/bench-config.js';
-import { isWorker, workerEngine, forkEngines } from './lib/fork-engine.js';
-
-// ── Parent process: fork one child per engine, assemble final output ─────
-if (!isWorker()) {
-	const { version } = await resolveBenchmarkSource();
-	const { wasm, native } = await forkEngines(import.meta.url, process.argv.slice(2));
-
-	const result = {
-		version,
-		date: new Date().toISOString().slice(0, 10),
-		wasm: wasm
-			? {
-					targets: wasm.targets,
-					fnDeps: wasm.fnDeps,
-					fnImpact: wasm.fnImpact,
-					diffImpact: wasm.diffImpact,
-				}
-			: null,
-		native: native
-			? {
-					targets: native.targets,
-					fnDeps: native.fnDeps,
-					fnImpact: native.fnImpact,
-					diffImpact: native.diffImpact,
-				}
-			: null,
-	};
-
-	console.log(JSON.stringify(result, null, 2));
-	process.exit(0);
-}
-
-// ── Worker process: benchmark a single engine, write JSON to stdout ──────
-const engine = workerEngine();
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const root = path.resolve(__dirname, '..');
 
-const { srcDir, cleanup } = await resolveBenchmarkSource();
+const { version, srcDir, cleanup } = await resolveBenchmarkSource();
 const dbPath = path.join(root, '.codegraph', 'graph.db');
 
 const { buildGraph } = await import(srcImport(srcDir, 'builder.js'));
-const { fnDepsData, fnImpactData, diffImpactData } = await import(
+const { fnDepsData, fnImpactData, diffImpactData, statsData } = await import(
 	srcImport(srcDir, 'queries.js')
 );
+const { isNativeAvailable } = await import(
+	srcImport(srcDir, 'native.js')
+);
+const { isWasmAvailable } = await import(
+	srcImport(srcDir, 'parser.js')
+);
 
 // Redirect console.log to stderr so only JSON goes to stdout
 const origLog = console.log;
 console.log = (...args) => console.error(...args);
 
 const RUNS = 5;
+const DEPTHS = [1, 3, 5];
 
 function median(arr) {
 	const sorted = [...arr].sort((a, b) => a - b);
@@ -79,31 +53,11 @@ function round1(n) {
 	return Math.round(n * 10) / 10;
 }
 
-// Pinned hub targets — stable function names that exist across versions.
-// Auto-selecting the most-connected node makes version-to-version comparison
-// meaningless when barrel/type files get added or removed.
-const PINNED_HUB_CANDIDATES = ['buildGraph', 'openDb', 'loadConfig'];
-
+/**
+ * Select hub / mid / leaf targets dynamically from the graph.
+ */
 function selectTargets() {
 	const db = new Database(dbPath, { readonly: true });
-
-	// Try pinned candidates first for a stable hub across versions
-	let hub = null;
-	for (const candidate of PINNED_HUB_CANDIDATES) {
-		const row = db
-			.prepare(
-				`SELECT n.name FROM nodes n
-         JOIN edges e ON e.source_id = n.id OR e.target_id = n.id
-         WHERE n.name = ? AND n.file NOT LIKE '%test%' AND n.file NOT LIKE '%spec%'
-         LIMIT 1`,
-			)
-			.get(candidate);
-		if (row) {
-			hub = row.name;
-			break;
-		}
-	}
-
 	const rows = db
 		.prepare(
 			`SELECT n.name, COUNT(e.id) AS cnt
@@ -118,14 +72,15 @@ function selectTargets() {
 
 	if (rows.length === 0) throw new Error('No nodes with edges found in graph');
 
-	// Fall back to most-connected if no pinned candidate found
-	if (!hub) hub = rows[0].name;
-
+	const hub = rows[0].name;
 	const mid = rows[Math.floor(rows.length / 2)].name;
 	const leaf = rows[rows.length - 1].name;
 	return { hub, mid, leaf };
 }
 
+/**
+ * Benchmark a single query function at multiple depths.
+ */
 function benchDepths(fn, name, depths) {
 	const result = {};
 	for (const depth of depths) {
@@ -140,7 +95,11 @@ function benchDepths(fn, name, depths) {
 	return result;
 }
 
+/**
+ * Benchmark diff-impact with a synthetic staged change on the hub file.
+ */
 function benchDiffImpact(hubName) {
+	// Find the file that contains the hub symbol
 	const db = new Database(dbPath, { readonly: true });
 	const row = db
 		.prepare(`SELECT file FROM nodes WHERE name = ? LIMIT 1`)
@@ -153,6 +112,7 @@ function benchDiffImpact(hubName) {
 	const original = fs.readFileSync(hubFile, 'utf8');
 
 	try {
+		// Append a probe comment and stage it
 		fs.writeFileSync(hubFile, original + '\n// benchmark-probe\n');
 		execFileSync('git', ['add', hubFile], { cwd: root, stdio: 'pipe' });
 
@@ -170,35 +130,95 @@ function benchDiffImpact(hubName) {
 			affectedFiles: lastResult?.affectedFiles?.length || 0,
 		};
 	} finally {
+		// Restore: unstage + revert content
 		execFileSync('git', ['restore', '--staged', hubFile], { cwd: root, stdio: 'pipe' });
 		fs.writeFileSync(hubFile, original);
 	}
 }
 
-// Build graph for this engine
-if (fs.existsSync(dbPath)) fs.unlinkSync(dbPath);
-await buildGraph(root, { engine, incremental: false });
+/**
+ * Run all query benchmarks against the current graph.
+ */
+function benchmarkQueries(targets) {
+	const fnDeps = {};
+	const fnImpact = {};
 
-const targets = selectTargets();
-console.error(`Targets: hub=${targets.hub}, mid=${targets.mid}, leaf=${targets.leaf}`);
+	// Run depth benchmarks on hub target (most connected — worst case)
+	fnDeps.depth1Ms = benchDepths(fnDepsData, targets.hub, [1]).depth1Ms;
+	fnDeps.depth3Ms = benchDepths(fnDepsData, targets.hub, [3]).depth3Ms;
+	fnDeps.depth5Ms = benchDepths(fnDepsData, targets.hub, [5]).depth5Ms;
 
-const fnDeps = {};
-const fnImpact = {};
+	fnImpact.depth1Ms = benchDepths(fnImpactData, targets.hub, [1]).depth1Ms;
+	fnImpact.depth3Ms = benchDepths(fnImpactData, targets.hub, [3]).depth3Ms;
+	fnImpact.depth5Ms = benchDepths(fnImpactData, targets.hub, [5]).depth5Ms;
 
-fnDeps.depth1Ms = benchDepths(fnDepsData, targets.hub, [1]).depth1Ms;
-fnDeps.depth3Ms = benchDepths(fnDepsData, targets.hub, [3]).depth3Ms;
-fnDeps.depth5Ms = benchDepths(fnDepsData, targets.hub, [5]).depth5Ms;
+	const diffImpact = benchDiffImpact(targets.hub);
 
-fnImpact.depth1Ms = benchDepths(fnImpactData, targets.hub, [1]).depth1Ms;
-fnImpact.depth3Ms = benchDepths(fnImpactData, targets.hub, [3]).depth3Ms;
-fnImpact.depth5Ms = benchDepths(fnImpactData, targets.hub, [5]).depth5Ms;
+	return { targets, fnDeps, fnImpact, diffImpact };
+}
+
+// ── Run benchmarks ───────────────────────────────────────────────────────
+const hasWasm = isWasmAvailable();
+const hasNative = isNativeAvailable();
 
-const diffImpact = benchDiffImpact(targets.hub);
+if (!hasWasm && !hasNative) {
+	console.error('Error: Neither WASM grammars nor native engine are available.');
+	console.error('Run "npm run build:wasm" to build WASM grammars, or install the native platform package.');
+	process.exit(1);
+}
+
+// Build with first available engine to select targets, then reuse for both
+let targets = null;
+let wasm = null;
+if (hasWasm) {
+	if (fs.existsSync(dbPath)) fs.unlinkSync(dbPath);
+	await buildGraph(root, { engine: 'wasm', incremental: false });
+
+	targets = selectTargets();
+	console.error(`Targets: hub=${targets.hub}, mid=${targets.mid}, leaf=${targets.leaf}`);
+	wasm = benchmarkQueries(targets);
+} else {
+	console.error('WASM grammars not built — skipping WASM benchmark');
+}
+
+let native = null;
+if (hasNative) {
+	if (fs.existsSync(dbPath)) fs.unlinkSync(dbPath);
+	await buildGraph(root, { engine: 'native', incremental: false });
+
+	if (!targets) {
+		targets = selectTargets();
+		console.error(`Targets: hub=${targets.hub}, mid=${targets.mid}, leaf=${targets.leaf}`);
+	}
+	native = benchmarkQueries(targets);
+} else {
+	console.error('Native engine not available — skipping native benchmark');
+}
 
 // Restore console.log for JSON output
 console.log = origLog;
 
-const workerResult = { targets, fnDeps, fnImpact, diffImpact };
-console.log(JSON.stringify(workerResult));
+const result = {
+	version,
+	date: new Date().toISOString().slice(0, 10),
+	wasm: wasm
+		? {
+				targets: wasm.targets,
+				fnDeps: wasm.fnDeps,
+				fnImpact: wasm.fnImpact,
+				diffImpact: wasm.diffImpact,
+			}
+		: null,
+	native: native
+		? {
+				targets: native.targets,
+				fnDeps: native.fnDeps,
+				fnImpact: native.fnImpact,
+				diffImpact: native.diffImpact,
+			}
+		: null,
+};
+
+console.log(JSON.stringify(result, null, 2));
 
 cleanup();
diff --git a/src/domain/analysis/context.js b/src/domain/analysis/context.js
index db157cf2..e3409208 100644
--- a/src/domain/analysis/context.js
+++ b/src/domain/analysis/context.js
@@ -95,7 +95,7 @@ function explainFileImpl(db, target, getFileLines) {
 function explainFunctionImpl(db, target, noTests, getFileLines) {
   let nodes = db
     .prepare(
-      `SELECT * FROM nodes WHERE name LIKE ? AND kind IN ('function','method','class','interface','type','struct','enum','trait','record','module','constant') ORDER BY file, line`,
+      `SELECT * FROM nodes WHERE name LIKE ? AND kind IN ('function','method','class','interface','type','struct','enum','trait','record','module') ORDER BY file, line`,
     )
     .all(`%${target}%`);
   if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
diff --git a/src/domain/graph/builder/stages/build-edges.js b/src/domain/graph/builder/stages/build-edges.js
index 82df6ea0..a8879b62 100644
--- a/src/domain/graph/builder/stages/build-edges.js
+++ b/src/domain/graph/builder/stages/build-edges.js
@@ -28,7 +28,7 @@ export async function buildEdges(ctx) {
   // Pre-load all nodes into lookup maps
   const allNodes = db
     .prepare(
-      `SELECT id, name, kind, file, line FROM nodes WHERE kind IN ('function','method','class','interface','struct','type','module','enum','trait','record','constant')`,
+      `SELECT id, name, kind, file, line FROM nodes WHERE kind IN ('function','method','class','interface','struct','type','module','enum','trait')`,
     )
     .all();
   ctx.nodesByName = new Map();
@@ -134,7 +134,6 @@ export async function buildEdges(ctx) {
           calls: symbols.calls,
           importedNames,
           classes: symbols.classes,
-          typeAssignments: symbols.typeAssignments || [],
         });
       }
 
@@ -158,18 +157,6 @@ export async function buildEdges(ctx) {
           }
         }
 
-        // Build per-file type map from typeAssignments (receiver type tracking)
-        const typeMap = new Map();
-        if (symbols.typeAssignments) {
-          for (const ta of symbols.typeAssignments) {
-            // Keep highest-confidence assignment per variable
-            const existing = typeMap.get(ta.variable);
-            if (!existing || ta.confidence > existing.confidence) {
-              typeMap.set(ta.variable, ta);
-            }
-          }
-        }
-
         const seenCallEdges = new Set();
         for (const call of symbols.calls) {
           if (call.receiver && BUILTIN_RECEIVERS.has(call.receiver)) continue;
@@ -211,53 +198,20 @@ export async function buildEdges(ctx) {
           if (!targets || targets.length === 0) {
             targets = ctx.nodesByNameAndFile.get(`${call.name}|${relPath}`) || [];
             if (targets.length === 0) {
-              // ── Receiver type tracking: resolve receiver.method() via type map ──
-              // When we have a receiver (e.g., `repo.findCallers()`), check the type
-              // map to find the receiver's class and look for ClassName.method.
-              let typedTargets = [];
-              if (
-                call.receiver &&
-                call.receiver !== 'this' &&
-                call.receiver !== 'self' &&
-                call.receiver !== 'super'
+              const methodCandidates = (ctx.nodesByName.get(call.name) || []).filter(
+                (n) => n.name.endsWith(`.${call.name}`) && n.kind === 'method',
+              );
+              if (methodCandidates.length > 0) {
+                targets = methodCandidates;
+              } else if (
+                !call.receiver ||
+                call.receiver === 'this' ||
+                call.receiver === 'self' ||
+                call.receiver === 'super'
               ) {
-                const typeInfo = typeMap.get(call.receiver);
-                if (typeInfo) {
-                  // Try qualified name: ClassName.methodName
-                  const qualifiedName = `${typeInfo.type}.${call.name}`;
-                  typedTargets = (ctx.nodesByName.get(qualifiedName) || []).filter(
-                    (n) => n.kind === 'method',
-                  );
-                  // If no match by qualified name, check if the type was imported
-                  // and look in that file for the qualified method
-                  if (typedTargets.length === 0) {
-                    const typeFile = importedNames.get(typeInfo.type);
-                    if (typeFile) {
-                      typedTargets =
-                        ctx.nodesByNameAndFile.get(`${qualifiedName}|${typeFile}`) || [];
-                    }
-                  }
-                }
-              }
-
-              if (typedTargets.length > 0) {
-                targets = typedTargets;
-              } else {
-                const methodCandidates = (ctx.nodesByName.get(call.name) || []).filter(
-                  (n) => n.name.endsWith(`.${call.name}`) && n.kind === 'method',
+                targets = (ctx.nodesByName.get(call.name) || []).filter(
+                  (n) => computeConfidence(relPath, n.file, null) >= 0.5,
                 );
-                if (methodCandidates.length > 0) {
-                  targets = methodCandidates;
-                } else if (
-                  !call.receiver ||
-                  call.receiver === 'this' ||
-                  call.receiver === 'self' ||
-                  call.receiver === 'super'
-                ) {
-                  targets = (ctx.nodesByName.get(call.name) || []).filter(
-                    (n) => computeConfidence(relPath, n.file, null) >= 0.5,
-                  );
-                }
               }
             }
           }
@@ -279,7 +233,7 @@ export async function buildEdges(ctx) {
             }
           }
 
-          // Receiver edge — use type map when available for precise class resolution
+          // Receiver edge
           if (
             call.receiver &&
             !BUILTIN_RECEIVERS.has(call.receiver) &&
@@ -288,34 +242,16 @@ export async function buildEdges(ctx) {
             call.receiver !== 'super'
           ) {
             const receiverKinds = new Set(['class', 'struct', 'interface', 'type', 'module']);
-            let receiverNodes = [];
-            let recvConfidence = 0.7;
-
-            // Try type map first for precise receiver resolution
-            const typeInfo = typeMap.get(call.receiver);
-            if (typeInfo) {
-              const typeName = typeInfo.type;
-              const sameFileTyped = ctx.nodesByNameAndFile.get(`${typeName}|${relPath}`) || [];
-              const typedCandidates =
-                sameFileTyped.length > 0 ? sameFileTyped : ctx.nodesByName.get(typeName) || [];
-              receiverNodes = typedCandidates.filter((n) => receiverKinds.has(n.kind));
-              recvConfidence = typeInfo.confidence;
-            }
-
-            // Fallback: look up receiver name directly as a class/struct
-            if (receiverNodes.length === 0) {
-              const samefile = ctx.nodesByNameAndFile.get(`${call.receiver}|${relPath}`) || [];
-              const candidates =
-                samefile.length > 0 ? samefile : ctx.nodesByName.get(call.receiver) || [];
-              receiverNodes = candidates.filter((n) => receiverKinds.has(n.kind));
-            }
-
+            const samefile = ctx.nodesByNameAndFile.get(`${call.receiver}|${relPath}`) || [];
+            const candidates =
+              samefile.length > 0 ? samefile : ctx.nodesByName.get(call.receiver) || [];
+            const receiverNodes = candidates.filter((n) => receiverKinds.has(n.kind));
             if (receiverNodes.length > 0 && caller) {
               const recvTarget = receiverNodes[0];
               const recvKey = `recv|${caller.id}|${recvTarget.id}`;
               if (!seenCallEdges.has(recvKey)) {
                 seenCallEdges.add(recvKey);
-                allEdgeRows.push([caller.id, recvTarget.id, 'receiver', recvConfidence, 0]);
+                allEdgeRows.push([caller.id, recvTarget.id, 'receiver', 0.7, 0]);
               }
             }
           }
diff --git a/src/domain/graph/resolve.js b/src/domain/graph/resolve.js
index 501e583b..5e0ab1d3 100644
--- a/src/domain/graph/resolve.js
+++ b/src/domain/graph/resolve.js
@@ -3,196 +3,6 @@ import path from 'node:path';
 import { loadNative } from '../../infrastructure/native.js';
 import { normalizePath } from '../../shared/constants.js';
 
-// ── package.json exports resolution ─────────────────────────────────
-
-/** Cache: packageDir → parsed exports field (or null) */
-const _exportsCache = new Map();
-
-/**
- * Parse a bare specifier into { packageName, subpath }.
- * Scoped: "@scope/pkg/sub" → { packageName: "@scope/pkg", subpath: "./sub" }
- * Plain:  "pkg/sub"        → { packageName: "pkg", subpath: "./sub" }
- * No sub: "pkg"            → { packageName: "pkg", subpath: "." }
- */
-export function parseBareSpecifier(specifier) {
-  let packageName, rest;
-  if (specifier.startsWith('@')) {
-    const parts = specifier.split('/');
-    if (parts.length < 2) return null;
-    packageName = parts[0] + '/' + parts[1];
-    rest = parts.slice(2).join('/');
-  } else {
-    const slashIdx = specifier.indexOf('/');
-    if (slashIdx === -1) {
-      packageName = specifier;
-      rest = '';
-    } else {
-      packageName = specifier.slice(0, slashIdx);
-      rest = specifier.slice(slashIdx + 1);
-    }
-  }
-  return { packageName, subpath: rest ? './' + rest : '.' };
-}
-
-/**
- * Find the package directory for a given package name, starting from rootDir.
- * Walks up node_modules directories.
- */
-function findPackageDir(packageName, rootDir) {
-  let dir = rootDir;
-  while (true) {
-    const candidate = path.join(dir, 'node_modules', packageName);
-    if (fs.existsSync(path.join(candidate, 'package.json'))) return candidate;
-    const parent = path.dirname(dir);
-    if (parent === dir) return null;
-    dir = parent;
-  }
-}
-
-/**
- * Read and cache the exports field from a package's package.json.
- * Returns the exports value or null.
- */
-function getPackageExports(packageDir) {
-  if (_exportsCache.has(packageDir)) return _exportsCache.get(packageDir);
-  try {
-    const raw = fs.readFileSync(path.join(packageDir, 'package.json'), 'utf8');
-    const pkg = JSON.parse(raw);
-    const exports = pkg.exports ?? null;
-    _exportsCache.set(packageDir, exports);
-    return exports;
-  } catch {
-    _exportsCache.set(packageDir, null);
-    return null;
-  }
-}
-
-/** Condition names to try, in priority order. */
-const CONDITION_ORDER = ['import', 'require', 'default'];
-
-/**
- * Resolve a conditional exports value (string, object with conditions, or array).
- * Returns a string target or null.
- */
-function resolveCondition(value) {
-  if (typeof value === 'string') return value;
-  if (Array.isArray(value)) {
-    for (const item of value) {
-      const r = resolveCondition(item);
-      if (r) return r;
-    }
-    return null;
-  }
-  if (value && typeof value === 'object') {
-    for (const cond of CONDITION_ORDER) {
-      if (cond in value) return resolveCondition(value[cond]);
-    }
-    return null;
-  }
-  return null;
-}
-
-/**
- * Match a subpath against an exports map key that uses a wildcard pattern.
- * Key: "./lib/*" matches subpath "./lib/foo/bar" → substitution "foo/bar"
- */
-function matchSubpathPattern(pattern, subpath) {
-  const starIdx = pattern.indexOf('*');
-  if (starIdx === -1) return null;
-  const prefix = pattern.slice(0, starIdx);
-  const suffix = pattern.slice(starIdx + 1);
-  if (!subpath.startsWith(prefix)) return null;
-  if (suffix && !subpath.endsWith(suffix)) return null;
-  const matched = subpath.slice(prefix.length, suffix ? -suffix.length || undefined : undefined);
-  if (!suffix && subpath.length < prefix.length) return null;
-  return matched;
-}
-
-/**
- * Resolve a bare specifier through the package.json exports field.
- * Returns an absolute path or null.
- */
-export function resolveViaExports(specifier, rootDir) {
-  const parsed = parseBareSpecifier(specifier);
-  if (!parsed) return null;
-
-  const packageDir = findPackageDir(parsed.packageName, rootDir);
-  if (!packageDir) return null;
-
-  const exports = getPackageExports(packageDir);
-  if (exports == null) return null;
-
-  const { subpath } = parsed;
-
-  // Simple string exports: "exports": "./index.js"
-  if (typeof exports === 'string') {
-    if (subpath === '.') {
-      const resolved = path.resolve(packageDir, exports);
-      return fs.existsSync(resolved) ? resolved : null;
-    }
-    return null;
-  }
-
-  // Array form at top level
-  if (Array.isArray(exports)) {
-    if (subpath === '.') {
-      const target = resolveCondition(exports);
-      if (target) {
-        const resolved = path.resolve(packageDir, target);
-        return fs.existsSync(resolved) ? resolved : null;
-      }
-    }
-    return null;
-  }
-
-  if (typeof exports !== 'object') return null;
-
-  // Determine if exports is a conditions object (no keys start with ".")
-  // or a subpath map (keys start with ".")
-  const keys = Object.keys(exports);
-  const isSubpathMap = keys.length > 0 && keys[0].startsWith('.');
-
-  if (!isSubpathMap) {
-    // Conditions object at top level → applies to "." subpath only
-    if (subpath === '.') {
-      const target = resolveCondition(exports);
-      if (target) {
-        const resolved = path.resolve(packageDir, target);
-        return fs.existsSync(resolved) ? resolved : null;
-      }
-    }
-    return null;
-  }
-
-  // Subpath map: try exact match first, then pattern match
-  if (subpath in exports) {
-    const target = resolveCondition(exports[subpath]);
-    if (target) {
-      const resolved = path.resolve(packageDir, target);
-      return fs.existsSync(resolved) ? resolved : null;
-    }
-  }
-
-  // Pattern matching (keys with *)
-  for (const [pattern, value] of Object.entries(exports)) {
-    if (!pattern.includes('*')) continue;
-    const matched = matchSubpathPattern(pattern, subpath);
-    if (matched == null) continue;
-    const rawTarget = resolveCondition(value);
-    if (!rawTarget) continue;
-    const target = rawTarget.replace(/\*/g, matched);
-    const resolved = path.resolve(packageDir, target);
-    if (fs.existsSync(resolved)) return resolved;
-  }
-
-  return null;
-}
-
-/** Clear the exports cache (for testing). */
-export function clearExportsCache() {
-  _exportsCache.clear();
-}
-
 // ── Alias format conversion ─────────────────────────────────────────
 
 /**
@@ -250,11 +60,7 @@ function resolveImportPathJS(fromFile, importSource, rootDir, aliases) {
     const aliasResolved = resolveViaAlias(importSource, aliases, rootDir);
     if (aliasResolved) return normalizePath(path.relative(rootDir, aliasResolved));
   }
-  if (!importSource.startsWith('.')) {
-    const exportsResolved = resolveViaExports(importSource, rootDir);
-    if (exportsResolved) return normalizePath(path.relative(rootDir, exportsResolved));
-    return importSource;
-  }
+  if (!importSource.startsWith('.')) return importSource;
   const dir = path.dirname(fromFile);
   const resolved = path.resolve(dir, importSource);
 
diff --git a/src/domain/graph/watcher.js b/src/domain/graph/watcher.js
index 3fea7954..15b4b4a6 100644
--- a/src/domain/graph/watcher.js
+++ b/src/domain/graph/watcher.js
@@ -57,10 +57,10 @@ export async function watchProject(rootDir, opts = {}) {
     countNodes: db.prepare('SELECT COUNT(*) as c FROM nodes WHERE file = ?'),
     countEdgesForFile: null,
     findNodeInFile: db.prepare(
-      "SELECT id, file FROM nodes WHERE name = ? AND kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'constant') AND file = ?",
+      "SELECT id, file FROM nodes WHERE name = ? AND kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module') AND file = ?",
     ),
     findNodeByName: db.prepare(
-      "SELECT id, file FROM nodes WHERE name = ? AND kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'constant')",
+      "SELECT id, file FROM nodes WHERE name = ? AND kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module')",
     ),
     listSymbols: db.prepare("SELECT name, kind, line FROM nodes WHERE file = ? AND kind != 'file'"),
   };
diff --git a/src/extractors/go.js b/src/extractors/go.js
index 2b2cbbbf..50460c8d 100644
--- a/src/extractors/go.js
+++ b/src/extractors/go.js
@@ -193,12 +193,7 @@ export function extractGoSymbols(tree, _filePath) {
   }
 
   walkGoNode(tree.rootNode);
-
-  // Extract variable-to-type assignments for receiver type tracking
-  const typeAssignments = [];
-  extractGoTypeAssignments(tree.rootNode, typeAssignments);
-
-  return { definitions, calls, imports, classes, exports, typeAssignments };
+  return { definitions, calls, imports, classes, exports };
 }
 
 // ── Child extraction helpers ────────────────────────────────────────────────
@@ -242,130 +237,3 @@ function extractStructFields(structTypeNode) {
   }
   return fields;
 }
-
-/**
- * Extract variable-to-type assignments from Go AST.
- *
- * Patterns:
- *   1. x := SomeStruct{...}        → confidence 1.0 (composite literal)
- *   2. var x SomeType               → confidence 0.9 (var declaration with type)
- *   3. x := pkg.NewFoo(...)         → confidence 0.7 (factory function)
- */
-function extractGoTypeAssignments(node, typeAssignments) {
-  const t = node.type;
-
-  // short_var_declaration: x := expr
-  if (t === 'short_var_declaration') {
-    const left = node.childForFieldName('left');
-    const right = node.childForFieldName('right');
-    if (left && right) {
-      // Find the first identifier on the left side
-      const varNode = left.type === 'expression_list' ? left.child(0) : left;
-      if (varNode && varNode.type === 'identifier') {
-        const varName = varNode.text;
-        const rhs = right.type === 'expression_list' ? right.child(0) : right;
-        if (rhs) {
-          // Pattern 1: x := SomeStruct{...} (composite literal)
-          if (rhs.type === 'composite_literal') {
-            const typeNode = rhs.childForFieldName('type');
-            if (typeNode) {
-              const typeName =
-                typeNode.type === 'pointer_type'
-                  ? typeNode.text.replace(/^\*/, '')
-                  : typeNode.type === 'type_identifier' || typeNode.type === 'identifier'
-                    ? typeNode.text
-                    : null;
-              if (typeName) {
-                typeAssignments.push({
-                  variable: varName,
-                  type: typeName,
-                  line: node.startPosition.row + 1,
-                  confidence: 1.0,
-                });
-              }
-            }
-          }
-          // Pattern 1b: x := &SomeStruct{...} (address-of composite literal)
-          if (rhs.type === 'unary_expression') {
-            const operand = rhs.childForFieldName('operand');
-            if (operand && operand.type === 'composite_literal') {
-              const typeNode = operand.childForFieldName('type');
-              if (typeNode) {
-                const typeName =
-                  typeNode.type === 'type_identifier' || typeNode.type === 'identifier'
-                    ? typeNode.text
-                    : null;
-                if (typeName) {
-                  typeAssignments.push({
-                    variable: varName,
-                    type: typeName,
-                    line: node.startPosition.row + 1,
-                    confidence: 1.0,
-                  });
-                }
-              }
-            }
-          }
-          // Pattern 3: x := pkg.NewFoo(...) or NewFoo(...)
-          if (rhs.type === 'call_expression') {
-            const fn = rhs.childForFieldName('function');
-            if (fn && fn.type === 'selector_expression') {
-              const field = fn.childForFieldName('field');
-              if (field?.text.startsWith('New')) {
-                const typeName = field.text.slice(3); // NewFoo → Foo
-                if (typeName) {
-                  typeAssignments.push({
-                    variable: varName,
-                    type: typeName,
-                    line: node.startPosition.row + 1,
-                    confidence: 0.7,
-                  });
-                }
-              }
-            } else if (fn && fn.type === 'identifier' && fn.text.startsWith('New')) {
-              const typeName = fn.text.slice(3);
-              if (typeName) {
-                typeAssignments.push({
-                  variable: varName,
-                  type: typeName,
-                  line: node.startPosition.row + 1,
-                  confidence: 0.7,
-                });
-              }
-            }
-          }
-        }
-      }
-    }
-  }
-
-  // var_declaration: var x SomeType
-  if (t === 'var_declaration') {
-    for (let i = 0; i < node.childCount; i++) {
-      const spec = node.child(i);
-      if (!spec || spec.type !== 'var_spec') continue;
-      const nameNode = spec.childForFieldName('name');
-      const typeNode = spec.childForFieldName('type');
-      if (nameNode && typeNode) {
-        const typeName =
-          typeNode.type === 'pointer_type'
-            ? typeNode.text.replace(/^\*/, '')
-            : typeNode.type === 'type_identifier' || typeNode.type === 'identifier'
-              ? typeNode.text
-              : null;
-        if (typeName) {
-          typeAssignments.push({
-            variable: nameNode.text,
-            type: typeName,
-            line: spec.startPosition.row + 1,
-            confidence: 0.9,
-          });
-        }
-      }
-    }
-  }
-
-  for (let i = 0; i < node.childCount; i++) {
-    extractGoTypeAssignments(node.child(i), typeAssignments);
-  }
-}
diff --git a/src/extractors/javascript.js b/src/extractors/javascript.js
index 608ef0f6..a2d9e7b1 100644
--- a/src/extractors/javascript.js
+++ b/src/extractors/javascript.js
@@ -179,11 +179,7 @@ function extractSymbolsQuery(tree, query) {
   // Extract dynamic import() calls via targeted walk (query patterns don't match `import` function type)
   extractDynamicImportsWalk(tree.rootNode, imports);
 
-  // Extract variable-to-type assignments for receiver type tracking
-  const typeAssignments = [];
-  extractTypeAssignmentsWalk(tree.rootNode, typeAssignments);
-
-  return { definitions, calls, imports, classes, exports: exps, typeAssignments };
+  return { definitions, calls, imports, classes, exports: exps };
 }
 
 /**
@@ -269,117 +265,6 @@ function extractDynamicImportsWalk(node, imports) {
   }
 }
 
-/**
- * Recursive walk to extract variable-to-type assignments for receiver type tracking.
- *
- * Tracks three patterns with decreasing confidence:
- *   1. Constructor:      const x = new SomeClass(...)         → confidence 1.0
- *   2. Type annotation:  const x: SomeClass = ...             → confidence 0.9
- *   3. Factory method:   const x = SomeClass.create(...)      → confidence 0.7
- *
- * The resulting typeAssignments array is consumed by build-edges to resolve
- * receiver.method() calls to ClassName.method with high precision.
- */
-function extractTypeAssignmentsWalk(node, typeAssignments) {
-  const t = node.type;
-  if (t === 'lexical_declaration' || t === 'variable_declaration') {
-    for (let i = 0; i < node.childCount; i++) {
-      const declarator = node.child(i);
-      if (!declarator || declarator.type !== 'variable_declarator') continue;
-      const nameNode = declarator.childForFieldName('name');
-      if (!nameNode || nameNode.type !== 'identifier') continue;
-      const varName = nameNode.text;
-      const valueNode = declarator.childForFieldName('value');
-
-      // Pattern 1: const x = new SomeClass(...)
-      if (valueNode && valueNode.type === 'new_expression') {
-        const ctor = valueNode.childForFieldName('constructor') || valueNode.child(1);
-        if (ctor) {
-          const typeName = ctor.type === 'identifier' ? ctor.text : null;
-          if (typeName) {
-            typeAssignments.push({
-              variable: varName,
-              type: typeName,
-              line: node.startPosition.row + 1,
-              confidence: 1.0,
-            });
-            continue;
-          }
-        }
-      }
-
-      // Pattern 2: const x: SomeClass = ... (TS type annotation)
-      const typeAnno =
-        nameNode.parent?.childForFieldName('type') || findChild(declarator, 'type_annotation');
-      if (typeAnno) {
-        const typeName = extractTypeAnnotationName(typeAnno);
-        if (typeName) {
-          typeAssignments.push({
-            variable: varName,
-            type: typeName,
-            line: node.startPosition.row + 1,
-            confidence: 0.9,
-          });
-          continue;
-        }
-      }
-
-      // Pattern 3: const x = SomeClass.create(...) (factory method)
-      if (valueNode && valueNode.type === 'call_expression') {
-        const fn = valueNode.childForFieldName('function');
-        if (fn && fn.type === 'member_expression') {
-          const obj = fn.childForFieldName('object');
-          if (obj && obj.type === 'identifier') {
-            const objName = obj.text;
-            // Heuristic: uppercase first letter suggests a class/constructor name
-            if (
-              objName[0] === objName[0].toUpperCase() &&
-              objName[0] !== objName[0].toLowerCase()
-            ) {
-              typeAssignments.push({
-                variable: varName,
-                type: objName,
-                line: node.startPosition.row + 1,
-                confidence: 0.7,
-              });
-            }
-          }
-        }
-      }
-    }
-  }
-
-  for (let i = 0; i < node.childCount; i++) {
-    extractTypeAssignmentsWalk(node.child(i), typeAssignments);
-  }
-}
-
-/**
- * Extract the type name from a type annotation node.
- * Handles: `: SomeClass`, `: SomeClass<T>`, `: SomeModule.SomeClass`
- * Returns null for complex union/intersection types.
- */
-function extractTypeAnnotationName(typeAnno) {
-  for (let i = 0; i < typeAnno.childCount; i++) {
-    const child = typeAnno.child(i);
-    if (!child) continue;
-    const ct = child.type;
-    if (ct === 'type_identifier' || ct === 'identifier') return child.text;
-    // Generic: SomeClass<T> → extract SomeClass
-    if (ct === 'generic_type') {
-      const nameNode = child.childForFieldName('name') || child.child(0);
-      if (nameNode && (nameNode.type === 'type_identifier' || nameNode.type === 'identifier')) {
-        return nameNode.text;
-      }
-    }
-    // Qualified: SomeModule.SomeClass → extract SomeModule.SomeClass
-    if (ct === 'nested_type_identifier' || ct === 'member_expression') {
-      return child.text;
-    }
-  }
-  return null;
-}
-
 function handleCommonJSAssignment(left, right, node, imports) {
   if (!left || !right) return;
   const leftText = left.text;
@@ -761,12 +646,7 @@ function extractSymbolsWalk(tree) {
   }
 
   walkJavaScriptNode(tree.rootNode);
-
-  // Extract variable-to-type assignments for receiver type tracking
-  const typeAssignments = [];
-  extractTypeAssignmentsWalk(tree.rootNode, typeAssignments);
-
-  return { definitions, calls, imports, classes, exports, typeAssignments };
+  return { definitions, calls, imports, classes, exports };
 }
 
 // ── Child extraction helpers ────────────────────────────────────────────────
diff --git a/src/extractors/python.js b/src/extractors/python.js
index 6b884783..968dbacb 100644
--- a/src/extractors/python.js
+++ b/src/extractors/python.js
@@ -291,84 +291,5 @@ export function extractPythonSymbols(tree, _filePath) {
   }
 
   walkPythonNode(tree.rootNode);
-
-  // Extract variable-to-type assignments for receiver type tracking
-  const typeAssignments = [];
-  extractPythonTypeAssignments(tree.rootNode, typeAssignments);
-
-  return { definitions, calls, imports, classes, exports, typeAssignments };
-}
-
-/**
- * Extract variable-to-type assignments from Python AST.
- *
- * Patterns:
- *   1. x = SomeClass(...)           → confidence 1.0 (constructor call)
- *   2. x: SomeClass = ...           → confidence 0.9 (type annotation)
- *   3. x = SomeClass.create(...)    → confidence 0.7 (factory method)
- */
-function extractPythonTypeAssignments(node, typeAssignments) {
-  // assignment: x = SomeClass(...) or x: SomeClass = ...
-  if (node.type === 'assignment') {
-    const left = node.childForFieldName('left');
-    const right = node.childForFieldName('right');
-    const typeAnno = node.childForFieldName('type');
-    if (left && left.type === 'identifier') {
-      const varName = left.text;
-
-      // Pattern 1: x = SomeClass(...) — constructor call with uppercase name
-      if (right && right.type === 'call') {
-        const fn = right.childForFieldName('function');
-        if (fn && fn.type === 'identifier') {
-          const name = fn.text;
-          if (name[0] === name[0].toUpperCase() && name[0] !== name[0].toLowerCase()) {
-            typeAssignments.push({
-              variable: varName,
-              type: name,
-              line: node.startPosition.row + 1,
-              confidence: 1.0,
-            });
-            return;
-          }
-        }
-        // Pattern 3: x = SomeClass.create(...)
-        if (fn && fn.type === 'attribute') {
-          const obj = fn.childForFieldName('object');
-          if (obj && obj.type === 'identifier') {
-            const objName = obj.text;
-            if (
-              objName[0] === objName[0].toUpperCase() &&
-              objName[0] !== objName[0].toLowerCase()
-            ) {
-              typeAssignments.push({
-                variable: varName,
-                type: objName,
-                line: node.startPosition.row + 1,
-                confidence: 0.7,
-              });
-              return;
-            }
-          }
-        }
-      }
-
-      // Pattern 2: x: SomeClass = ...
-      if (typeAnno && typeAnno.type === 'type') {
-        const typeIdent = typeAnno.child(0);
-        if (typeIdent && typeIdent.type === 'identifier') {
-          typeAssignments.push({
-            variable: varName,
-            type: typeIdent.text,
-            line: node.startPosition.row + 1,
-            confidence: 0.9,
-          });
-          return;
-        }
-      }
-    }
-  }
-
-  for (let i = 0; i < node.childCount; i++) {
-    extractPythonTypeAssignments(node.child(i), typeAssignments);
-  }
+  return { definitions, calls, imports, classes, exports };
 }
diff --git a/src/features/export.js b/src/features/export.js
index 3bd064e3..6f93faae 100644
--- a/src/features/export.js
+++ b/src/features/export.js
@@ -67,8 +67,8 @@ function loadFunctionLevelEdges(db, { noTests, minConfidence, limit }) {
       FROM edges e
       JOIN nodes n1 ON e.source_id = n1.id
       JOIN nodes n2 ON e.target_id = n2.id
-      WHERE n1.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'constant')
-        AND n2.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'constant')
+      WHERE n1.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module')
+        AND n2.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module')
         AND e.kind = 'calls'
         AND e.confidence >= ?
     `,
@@ -308,7 +308,7 @@ export function exportGraphSON(db, opts = {}) {
   let nodes = db
     .prepare(`
     SELECT id, name, kind, file, line, role FROM nodes
-    WHERE kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'constant', 'file')
+    WHERE kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'file')
   `)
     .all();
   if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
diff --git a/src/features/graph-enrichment.js b/src/features/graph-enrichment.js
index adb9fb8e..96e47e2c 100644
--- a/src/features/graph-enrichment.js
+++ b/src/features/graph-enrichment.js
@@ -42,8 +42,8 @@ function prepareFunctionLevelData(db, noTests, minConf, cfg) {
       FROM edges e
       JOIN nodes n1 ON e.source_id = n1.id
       JOIN nodes n2 ON e.target_id = n2.id
-      WHERE n1.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'constant')
-        AND n2.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module', 'constant')
+      WHERE n1.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module')
+        AND n2.kind IN ('function', 'method', 'class', 'interface', 'type', 'struct', 'enum', 'trait', 'record', 'module')
         AND e.kind = 'calls'
         AND e.confidence >= ?
     `,
diff --git a/tests/integration/build-parity.test.js b/tests/integration/build-parity.test.js
index 7ca77148..86ef5043 100644
--- a/tests/integration/build-parity.test.js
+++ b/tests/integration/build-parity.test.js
@@ -37,9 +37,6 @@ function readGraph(dbPath) {
   // while WASM correctly limits constant extraction to program-level declarations.
   // TODO: Remove kind != 'constant' exclusion once native binary >= 3.0.4 ships
   // Fix: crates/codegraph-core/src/extractors/javascript.rs (find_parent_of_types guard)
-  // Also exclude 'receiver' edges and method-call 'calls' edges (target contains '.') —
-  // the native engine doesn't emit these for `new Foo()` / `obj.method()` patterns yet.
-  // TODO: Remove receiver/method-call exclusion once native extractor handles call_expression receivers
   const nodes = db
     .prepare(
       "SELECT name, kind, file, line FROM nodes WHERE kind != 'constant' ORDER BY name, kind, file, line",
@@ -52,8 +49,6 @@ function readGraph(dbPath) {
     JOIN nodes n1 ON e.source_id = n1.id
     JOIN nodes n2 ON e.target_id = n2.id
     WHERE n1.kind != 'constant' AND n2.kind != 'constant'
-      AND e.kind != 'receiver'
-      AND NOT (e.kind = 'calls' AND n2.name LIKE '%.%')
     ORDER BY n1.name, n2.name, e.kind
   `)
     .all();
diff --git a/tests/parsers/javascript.test.js b/tests/parsers/javascript.test.js
index 7341d115..63875fc8 100644
--- a/tests/parsers/javascript.test.js
+++ b/tests/parsers/javascript.test.js
@@ -189,51 +189,4 @@ describe('JavaScript parser', () => {
       expect(def.endLine).toBe(4);
     });
   });
-
-  describe('type assignments (receiver type tracking)', () => {
-    it('extracts constructor assignments with confidence 1.0', () => {
-      const symbols = parseJS(`const repo = new UserRepository();`);
-      expect(symbols.typeAssignments).toContainEqual(
-        expect.objectContaining({ variable: 'repo', type: 'UserRepository', confidence: 1.0 }),
-      );
-    });
-
-    it('extracts factory method assignments with confidence 0.7', () => {
-      const symbols = parseJS(`const client = HttpClient.create();`);
-      expect(symbols.typeAssignments).toContainEqual(
-        expect.objectContaining({ variable: 'client', type: 'HttpClient', confidence: 0.7 }),
-      );
-    });
-
-    it('ignores lowercase factory calls (not class names)', () => {
-      const symbols = parseJS(`const result = utils.create();`);
-      expect(symbols.typeAssignments).toHaveLength(0);
-    });
-
-    it('extracts multiple type assignments in same scope', () => {
-      const symbols = parseJS(`
-        const db = new Database();
-        const cache = new RedisCache();
-      `);
-      expect(symbols.typeAssignments).toHaveLength(2);
-      expect(symbols.typeAssignments).toContainEqual(
-        expect.objectContaining({ variable: 'db', type: 'Database', confidence: 1.0 }),
-      );
-      expect(symbols.typeAssignments).toContainEqual(
-        expect.objectContaining({ variable: 'cache', type: 'RedisCache', confidence: 1.0 }),
-      );
-    });
-
-    it('extracts nested type assignments inside functions', () => {
-      const symbols = parseJS(`
-        function init() {
-          const service = new AuthService();
-          service.login();
-        }
-      `);
-      expect(symbols.typeAssignments).toContainEqual(
-        expect.objectContaining({ variable: 'service', type: 'AuthService', confidence: 1.0 }),
-      );
-    });
-  });
 });
diff --git a/tests/unit/resolve.test.js b/tests/unit/resolve.test.js
index 9ca323bd..d5e487b6 100644
--- a/tests/unit/resolve.test.js
+++ b/tests/unit/resolve.test.js
@@ -9,14 +9,11 @@ import os from 'node:os';
 import path from 'node:path';
 import { afterAll, beforeAll, describe, expect, it } from 'vitest';
 import {
-  clearExportsCache,
   computeConfidence,
   computeConfidenceJS,
   convertAliasesForNative,
-  parseBareSpecifier,
   resolveImportPathJS,
   resolveImportsBatch,
-  resolveViaExports,
 } from '../../src/domain/graph/resolve.js';
 
 // ─── Temp project setup ──────────────────────────────────────────────
@@ -222,201 +219,3 @@ describe('resolveImportsBatch', () => {
     expect(result === null || result instanceof Map).toBe(true);
   });
 });
-
-// ─── parseBareSpecifier ──────────────────────────────────────────────
-
-describe('parseBareSpecifier', () => {
-  it('parses plain package with no subpath', () => {
-    expect(parseBareSpecifier('lodash')).toEqual({ packageName: 'lodash', subpath: '.' });
-  });
-
-  it('parses plain package with subpath', () => {
-    expect(parseBareSpecifier('lodash/fp')).toEqual({ packageName: 'lodash', subpath: './fp' });
-  });
-
-  it('parses scoped package with no subpath', () => {
-    expect(parseBareSpecifier('@scope/pkg')).toEqual({ packageName: '@scope/pkg', subpath: '.' });
-  });
-
-  it('parses scoped package with subpath', () => {
-    expect(parseBareSpecifier('@scope/pkg/utils/deep')).toEqual({
-      packageName: '@scope/pkg',
-      subpath: './utils/deep',
-    });
-  });
-
-  it('returns null for bare @ with no slash', () => {
-    expect(parseBareSpecifier('@scope')).toBeNull();
-  });
-});
-
-// ─── resolveViaExports ───────────────────────────────────────────────
-
-describe('resolveViaExports', () => {
-  let pkgRoot;
-
-  beforeAll(() => {
-    clearExportsCache();
-    // Create a fake node_modules structure inside tmpDir
-    pkgRoot = path.join(tmpDir, 'node_modules', 'test-pkg');
-    fs.mkdirSync(path.join(pkgRoot, 'dist'), { recursive: true });
-    fs.mkdirSync(path.join(pkgRoot, 'lib', 'utils'), { recursive: true });
-    fs.writeFileSync(path.join(pkgRoot, 'dist', 'index.mjs'), 'export default 1;');
-    fs.writeFileSync(path.join(pkgRoot, 'dist', 'index.cjs'), 'module.exports = 1;');
-    fs.writeFileSync(path.join(pkgRoot, 'dist', 'helpers.mjs'), 'export const h = 1;');
-    fs.writeFileSync(path.join(pkgRoot, 'lib', 'utils', 'deep.js'), 'export const d = 1;');
-  });
-
-  afterEach(() => {
-    clearExportsCache();
-  });
-
-  it('resolves string exports (shorthand)', () => {
-    fs.writeFileSync(
-      path.join(pkgRoot, 'package.json'),
-      JSON.stringify({ name: 'test-pkg', exports: './dist/index.mjs' }),
-    );
-    const result = resolveViaExports('test-pkg', tmpDir);
-    expect(result).toBe(path.join(pkgRoot, 'dist', 'index.mjs'));
-  });
-
-  it('returns null for subpath when exports is a string', () => {
-    fs.writeFileSync(
-      path.join(pkgRoot, 'package.json'),
-      JSON.stringify({ name: 'test-pkg', exports: './dist/index.mjs' }),
-    );
-    expect(resolveViaExports('test-pkg/helpers', tmpDir)).toBeNull();
-  });
-
-  it('resolves conditional exports (import/require/default)', () => {
-    fs.writeFileSync(
-      path.join(pkgRoot, 'package.json'),
-      JSON.stringify({
-        name: 'test-pkg',
-        exports: {
-          '.': { import: './dist/index.mjs', require: './dist/index.cjs' },
-        },
-      }),
-    );
-    const result = resolveViaExports('test-pkg', tmpDir);
-    expect(result).toBe(path.join(pkgRoot, 'dist', 'index.mjs'));
-  });
-
-  it('falls back to require when import is absent', () => {
-    fs.writeFileSync(
-      path.join(pkgRoot, 'package.json'),
-      JSON.stringify({
-        name: 'test-pkg',
-        exports: {
-          '.': { require: './dist/index.cjs' },
-        },
-      }),
-    );
-    const result = resolveViaExports('test-pkg', tmpDir);
-    expect(result).toBe(path.join(pkgRoot, 'dist', 'index.cjs'));
-  });
-
-  it('resolves subpath exports', () => {
-    fs.writeFileSync(
-      path.join(pkgRoot, 'package.json'),
-      JSON.stringify({
-        name: 'test-pkg',
-        exports: {
-          '.': './dist/index.mjs',
-          './helpers': './dist/helpers.mjs',
-        },
-      }),
-    );
-    const result = resolveViaExports('test-pkg/helpers', tmpDir);
-    expect(result).toBe(path.join(pkgRoot, 'dist', 'helpers.mjs'));
-  });
-
-  it('resolves subpath patterns with wildcard', () => {
-    fs.writeFileSync(
-      path.join(pkgRoot, 'package.json'),
-      JSON.stringify({
-        name: 'test-pkg',
-        exports: {
-          '.': './dist/index.mjs',
-          './lib/*': './lib/*.js',
-        },
-      }),
-    );
-    const result = resolveViaExports('test-pkg/lib/utils/deep', tmpDir);
-    expect(result).toBe(path.join(pkgRoot, 'lib', 'utils', 'deep.js'));
-  });
-
-  it('resolves conditional subpath exports', () => {
-    fs.writeFileSync(
-      path.join(pkgRoot, 'package.json'),
-      JSON.stringify({
-        name: 'test-pkg',
-        exports: {
-          './helpers': { import: './dist/helpers.mjs', default: './dist/helpers.mjs' },
-        },
-      }),
-    );
-    const result = resolveViaExports('test-pkg/helpers', tmpDir);
-    expect(result).toBe(path.join(pkgRoot, 'dist', 'helpers.mjs'));
-  });
-
-  it('resolves top-level conditions object (no . keys)', () => {
-    fs.writeFileSync(
-      path.join(pkgRoot, 'package.json'),
-      JSON.stringify({
-        name: 'test-pkg',
-        exports: { import: './dist/index.mjs', require: './dist/index.cjs' },
-      }),
-    );
-    const result = resolveViaExports('test-pkg', tmpDir);
-    expect(result).toBe(path.join(pkgRoot, 'dist', 'index.mjs'));
-  });
-
-  it('returns null when exports field is absent', () => {
-    fs.writeFileSync(
-      path.join(pkgRoot, 'package.json'),
-      JSON.stringify({ name: 'test-pkg', main: './dist/index.mjs' }),
-    );
-    expect(resolveViaExports('test-pkg', tmpDir)).toBeNull();
-  });
-
-  it('returns null when package is not in node_modules', () => {
-    expect(resolveViaExports('nonexistent-pkg', tmpDir)).toBeNull();
-  });
-});
-
-// ─── resolveImportPathJS with exports ────────────────────────────────
-
-describe('resolveImportPathJS with package.json exports', () => {
-  let pkgRoot;
-
-  beforeAll(() => {
-    clearExportsCache();
-    pkgRoot = path.join(tmpDir, 'node_modules', 'exports-pkg');
-    fs.mkdirSync(path.join(pkgRoot, 'dist'), { recursive: true });
-    fs.writeFileSync(path.join(pkgRoot, 'dist', 'main.mjs'), 'export default 1;');
-    fs.writeFileSync(
-      path.join(pkgRoot, 'package.json'),
-      JSON.stringify({
-        name: 'exports-pkg',
-        exports: { '.': './dist/main.mjs' },
-      }),
-    );
-  });
-
-  afterEach(() => {
-    clearExportsCache();
-  });
-
-  it('resolves bare specifier through exports field', () => {
-    const fromFile = path.join(tmpDir, 'src', 'index.js');
-    const result = resolveImportPathJS(fromFile, 'exports-pkg', tmpDir, null);
-    expect(result).toContain('node_modules/exports-pkg/dist/main.mjs');
-  });
-
-  it('still passes through bare specifiers without exports', () => {
-    const fromFile = path.join(tmpDir, 'src', 'index.js');
-    const result = resolveImportPathJS(fromFile, 'lodash', tmpDir, null);
-    expect(result).toBe('lodash');
-  });
-});

From e5501fcdf0be0a373046d1a9ffb835350bf578e7 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sat, 21 Mar 2026 19:35:20 -0600
Subject: [PATCH 16/52] fix: correct command table and --yes flag documentation

---
 .claude/skills/titan-run/SKILL.md                   | 2 +-
 docs/examples/claude-code-skills/README.md          | 6 +++---
 docs/examples/claude-code-skills/titan-run/SKILL.md | 2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/.claude/skills/titan-run/SKILL.md b/.claude/skills/titan-run/SKILL.md
index f6d66fbf..49e3b372 100644
--- a/.claude/skills/titan-run/SKILL.md
+++ b/.claude/skills/titan-run/SKILL.md
@@ -571,7 +571,7 @@ Artifacts:
 - **Mandatory pause before forge** unless `--yes` is set. Analysis is safe; code changes deserve human review.
 - **Stall detection is strict for forge** (2 retries) and looser for gauntlet (3 retries) since gauntlet is more likely to hit context limits legitimately.
 - **Respect --start-from.** Skip phases before the specified starting point, but verify their artifacts exist AND pass validation.
-- **Pass --yes through to forge** if the user provided it, so forge doesn't prompt for confirmation on each phase.
+- **Pass --yes through to forge** if the user provided it, so forge skips its per-phase confirmation prompt. Within the orchestrator, `--yes` also skips the pre-pipeline, forge checkpoint, and resume prompts.
 
 ## Self-Improvement
 
diff --git a/docs/examples/claude-code-skills/README.md b/docs/examples/claude-code-skills/README.md
index 70f94d6a..5a112731 100644
--- a/docs/examples/claude-code-skills/README.md
+++ b/docs/examples/claude-code-skills/README.md
@@ -184,9 +184,9 @@ All skills enforce worktree isolation as their first step. If invoked from the m
 | `codegraph stats` | RECON | Baseline metrics |
 | `codegraph triage` | RECON, GAUNTLET (fallback) | Ranked priority queue |
 | `codegraph map` | RECON | High-traffic files |
-| `codegraph communities` | RECON | Module boundaries and drift |
+| `codegraph communities` | RECON, GATE | Module boundaries and drift |
 | `codegraph roles` | RECON, GAUNTLET | Core/dead/entry symbol classification |
-| `codegraph structure` | RECON | Directory cohesion |
+| `codegraph structure` | RECON, GATE | Directory cohesion |
 | `codegraph complexity --health` | RECON, GAUNTLET, GATE | Full metrics: cognitive, cyclomatic, nesting, Halstead, MI |
 | `codegraph complexity --above-threshold` | RECON | Only functions exceeding thresholds |
 | `codegraph batch complexity` | GAUNTLET | Multi-target complexity in one call |
@@ -200,7 +200,7 @@ All skills enforce worktree isolation as their first step. If invoked from the m
 | `codegraph co-change` | GAUNTLET, SYNC | Git history coupling |
 | `codegraph path` | SYNC | Dependency paths between targets |
 | `codegraph cycles` | SYNC, GATE | Circular dependency detection |
-| `codegraph deps` | SYNC | File-level dependency map |
+| `codegraph deps` | SYNC, GATE | File-level dependency map |
 | `codegraph context` | SYNC, FORGE | Full function context |
 | `codegraph owners` | SYNC | CODEOWNERS mapping for cross-team coordination |
 | `codegraph branch-compare` | SYNC, GATE | Structural diff between refs |
diff --git a/docs/examples/claude-code-skills/titan-run/SKILL.md b/docs/examples/claude-code-skills/titan-run/SKILL.md
index f6d66fbf..49e3b372 100644
--- a/docs/examples/claude-code-skills/titan-run/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-run/SKILL.md
@@ -571,7 +571,7 @@ Artifacts:
 - **Mandatory pause before forge** unless `--yes` is set. Analysis is safe; code changes deserve human review.
 - **Stall detection is strict for forge** (2 retries) and looser for gauntlet (3 retries) since gauntlet is more likely to hit context limits legitimately.
 - **Respect --start-from.** Skip phases before the specified starting point, but verify their artifacts exist AND pass validation.
-- **Pass --yes through to forge** if the user provided it, so forge doesn't prompt for confirmation on each phase.
+- **Pass --yes through to forge** if the user provided it, so forge skips its per-phase confirmation prompt. Within the orchestrator, `--yes` also skips the pre-pipeline, forge checkpoint, and resume prompts.
 
 ## Self-Improvement
 

From 05a4281adb972e087f8f58dd32f3a5051cbab01e Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sat, 21 Mar 2026 23:39:13 -0600
Subject: [PATCH 17/52] =?UTF-8?q?fix:=20address=20titan-gate=20review=20fe?=
 =?UTF-8?q?edback=20=E2=80=94=20Louvain=20drift,=20temp=20paths,=20rollbac?=
 =?UTF-8?q?k=20range,=20FAIL=20template?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Use codegraph communities --drift for A1 comparison instead of raw IDs
- Add unique /tmp paths per invocation (epoch+PID) with cleanup
- Update auto-rollback exception from Steps 1-3,5-7 to Steps 1-3,6-8
- Split FAIL template: test/lint (rollback) vs structural/semantic (preserved)
---
 .claude/skills/titan-gate/SKILL.md            | 45 ++++++++++++++-----
 .../claude-code-skills/titan-gate/SKILL.md    | 45 ++++++++++++++-----
 2 files changed, 68 insertions(+), 22 deletions(-)

diff --git a/.claude/skills/titan-gate/SKILL.md b/.claude/skills/titan-gate/SKILL.md
index 3c8c0c95..1d1f8112 100644
--- a/.claude/skills/titan-gate/SKILL.md
+++ b/.claude/skills/titan-gate/SKILL.md
@@ -179,18 +179,25 @@ Read `.codegraph/titan/arch-snapshot.json` if it exists (created by `/titan-run`
 ### Capture current state
 
 ```bash
-codegraph communities -T --json > /tmp/titan-arch-current-communities.json
-codegraph structure --depth 2 --json > /tmp/titan-arch-current-structure.json
-codegraph communities --drift -T --json > /tmp/titan-arch-current-drift.json
+TITAN_TMP_ID="$(date +%s)-$$"
+codegraph communities -T --json > /tmp/titan-arch-${TITAN_TMP_ID}-current-communities.json
+codegraph structure --depth 2 --json > /tmp/titan-arch-${TITAN_TMP_ID}-current-structure.json
+codegraph communities --drift -T --json > /tmp/titan-arch-${TITAN_TMP_ID}-current-drift.json
 ```
 
 ### Compare
 
 **A1. Community stability:**
-Compare community assignments between snapshot and current. For each symbol that **moved** to a different community:
-- If the symbol was the target of this forge phase → **OK** (expected)
-- If the symbol was NOT touched in the diff → **WARN**: "Symbol `<name>` shifted from community <X> to <Y> as a side effect"
-- If > 5 untouched symbols shifted communities → **FAIL**: "Significant community restructuring detected — <N> symbols shifted communities. This change may have unintended architectural impact."
+Use the drift output (which uses content-based matching, not raw IDs, to track community movements across runs):
+
+```bash
+# Compare current drift report against snapshot drift baseline
+# New drift warnings not present in arch-snapshot.json → side-effect restructuring
+```
+
+Read `.codegraph/titan/arch-snapshot.json → drift` (the pre-forge drift baseline) and compare against `/tmp/titan-arch-${TITAN_TMP_ID}-current-drift.json`:
+- For each **new** drift warning in current that was NOT present in the snapshot: if the drifted symbol was NOT touched in the diff → **WARN**: "Symbol `<name>` drifted community as a side effect"
+- If > 5 untouched symbols appear in new drift warnings → **FAIL**: "Significant community restructuring detected — <N> symbols drifted communities. This change may have unintended architectural impact."
 
 **A2. Dependency direction between domains:**
 From `GLOBAL_ARCH.md`, extract the expected dependency direction between domains (e.g., "presentation depends on features, not the reverse").
@@ -212,6 +219,14 @@ Compare drift warnings between snapshot and current:
 - New drift warning not in snapshot → **WARN** with details
 - Drift warning resolved → note as positive
 
+### Cleanup
+
+```bash
+rm -f /tmp/titan-arch-${TITAN_TMP_ID}-current-communities.json \
+      /tmp/titan-arch-${TITAN_TMP_ID}-current-structure.json \
+      /tmp/titan-arch-${TITAN_TMP_ID}-current-drift.json
+```
+
 ### Verdict integration
 
 Architectural failures are reported as part of the overall gate verdict. They participate in the PASS/WARN/FAIL aggregation like all other checks.
@@ -278,7 +293,7 @@ Aggregate all checks:
 
 > "GATE FAIL: [reason]. Graph restored, changes unstaged but preserved. Fix and re-stage."
 
-For structural-only failures (Steps 1-3, 5-7), do NOT auto-rollback — report and let user decide.
+For structural-only failures (Steps 1-3, 6-8), do NOT auto-rollback — report and let user decide.
 
 ### Snapshot cleanup on pipeline completion
 
@@ -347,17 +362,25 @@ GATE WARN — review before committing
   - Architecture: directory src/domain/ cohesion dropped 0.6 → 0.45
 ```
 
-**FAIL:**
+**FAIL (test/lint/build failures — rollback triggered):**
 ```
 GATE FAIL — changes unstaged, graph restored
   Failures:
   - Tests: 2 suites failed
-  - Semantic: removed export `parseConfig` still imported by 3 files
-  - Architecture: new upward dependency presentation/ → domain/
   - New cycle: parseConfig → loadConfig → parseConfig
   Fix issues, re-stage, re-run /titan-gate
 ```
 
+**FAIL (structural/semantic failures — no rollback):**
+```
+GATE FAIL — changes preserved for review — manual unstage if needed
+  Failures:
+  - Semantic: removed export `parseConfig` still imported by 3 files
+  - Architecture: new upward dependency presentation/ → domain/
+  Staged changes are intact. Fix the issues above, or manually run `git reset HEAD` to unstage.
+  Re-stage and re-run /titan-gate when ready.
+```
+
 ---
 
 ## Rules
diff --git a/docs/examples/claude-code-skills/titan-gate/SKILL.md b/docs/examples/claude-code-skills/titan-gate/SKILL.md
index 3c8c0c95..1d1f8112 100644
--- a/docs/examples/claude-code-skills/titan-gate/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-gate/SKILL.md
@@ -179,18 +179,25 @@ Read `.codegraph/titan/arch-snapshot.json` if it exists (created by `/titan-run`
 ### Capture current state
 
 ```bash
-codegraph communities -T --json > /tmp/titan-arch-current-communities.json
-codegraph structure --depth 2 --json > /tmp/titan-arch-current-structure.json
-codegraph communities --drift -T --json > /tmp/titan-arch-current-drift.json
+TITAN_TMP_ID="$(date +%s)-$$"
+codegraph communities -T --json > /tmp/titan-arch-${TITAN_TMP_ID}-current-communities.json
+codegraph structure --depth 2 --json > /tmp/titan-arch-${TITAN_TMP_ID}-current-structure.json
+codegraph communities --drift -T --json > /tmp/titan-arch-${TITAN_TMP_ID}-current-drift.json
 ```
 
 ### Compare
 
 **A1. Community stability:**
-Compare community assignments between snapshot and current. For each symbol that **moved** to a different community:
-- If the symbol was the target of this forge phase → **OK** (expected)
-- If the symbol was NOT touched in the diff → **WARN**: "Symbol `<name>` shifted from community <X> to <Y> as a side effect"
-- If > 5 untouched symbols shifted communities → **FAIL**: "Significant community restructuring detected — <N> symbols shifted communities. This change may have unintended architectural impact."
+Use the drift output (which uses content-based matching, not raw IDs, to track community movements across runs):
+
+```bash
+# Compare current drift report against snapshot drift baseline
+# New drift warnings not present in arch-snapshot.json → side-effect restructuring
+```
+
+Read `.codegraph/titan/arch-snapshot.json → drift` (the pre-forge drift baseline) and compare against `/tmp/titan-arch-${TITAN_TMP_ID}-current-drift.json`:
+- For each **new** drift warning in current that was NOT present in the snapshot: if the drifted symbol was NOT touched in the diff → **WARN**: "Symbol `<name>` drifted community as a side effect"
+- If > 5 untouched symbols appear in new drift warnings → **FAIL**: "Significant community restructuring detected — <N> symbols drifted communities. This change may have unintended architectural impact."
 
 **A2. Dependency direction between domains:**
 From `GLOBAL_ARCH.md`, extract the expected dependency direction between domains (e.g., "presentation depends on features, not the reverse").
@@ -212,6 +219,14 @@ Compare drift warnings between snapshot and current:
 - New drift warning not in snapshot → **WARN** with details
 - Drift warning resolved → note as positive
 
+### Cleanup
+
+```bash
+rm -f /tmp/titan-arch-${TITAN_TMP_ID}-current-communities.json \
+      /tmp/titan-arch-${TITAN_TMP_ID}-current-structure.json \
+      /tmp/titan-arch-${TITAN_TMP_ID}-current-drift.json
+```
+
 ### Verdict integration
 
 Architectural failures are reported as part of the overall gate verdict. They participate in the PASS/WARN/FAIL aggregation like all other checks.
@@ -278,7 +293,7 @@ Aggregate all checks:
 
 > "GATE FAIL: [reason]. Graph restored, changes unstaged but preserved. Fix and re-stage."
 
-For structural-only failures (Steps 1-3, 5-7), do NOT auto-rollback — report and let user decide.
+For structural-only failures (Steps 1-3, 6-8), do NOT auto-rollback — report and let user decide.
 
 ### Snapshot cleanup on pipeline completion
 
@@ -347,17 +362,25 @@ GATE WARN — review before committing
   - Architecture: directory src/domain/ cohesion dropped 0.6 → 0.45
 ```
 
-**FAIL:**
+**FAIL (test/lint/build failures — rollback triggered):**
 ```
 GATE FAIL — changes unstaged, graph restored
   Failures:
   - Tests: 2 suites failed
-  - Semantic: removed export `parseConfig` still imported by 3 files
-  - Architecture: new upward dependency presentation/ → domain/
   - New cycle: parseConfig → loadConfig → parseConfig
   Fix issues, re-stage, re-run /titan-gate
 ```
 
+**FAIL (structural/semantic failures — no rollback):**
+```
+GATE FAIL — changes preserved for review — manual unstage if needed
+  Failures:
+  - Semantic: removed export `parseConfig` still imported by 3 files
+  - Architecture: new upward dependency presentation/ → domain/
+  Staged changes are intact. Fix the issues above, or manually run `git reset HEAD` to unstage.
+  Re-stage and re-run /titan-gate when ready.
+```
+
 ---
 
 ## Rules

From 5dded2fa63a3a3acfb5221814469d5db1a62cd21 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sat, 21 Mar 2026 23:39:33 -0600
Subject: [PATCH 18/52] =?UTF-8?q?fix:=20address=20titan-run=20review=20fee?=
 =?UTF-8?q?dback=20=E2=80=94=20--yes=20scope=20and=20--start-from=20valida?=
 =?UTF-8?q?tion?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Update --yes description to include forge per-phase confirmation
- Add Step 0.5 artifact pre-validation for --start-from skipped phases
---
 .claude/skills/titan-run/SKILL.md             | 22 ++++++++++++++++++-
 .../claude-code-skills/titan-run/SKILL.md     | 22 ++++++++++++++++++-
 2 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/titan-run/SKILL.md b/.claude/skills/titan-run/SKILL.md
index 49e3b372..6a9eda18 100644
--- a/.claude/skills/titan-run/SKILL.md
+++ b/.claude/skills/titan-run/SKILL.md
@@ -18,7 +18,7 @@ You are the **orchestrator** for the full Titan Paradigm pipeline. Your job is t
 - `--skip-gauntlet` → skip gauntlet (assumes artifacts exist)
 - `--start-from <phase>` → jump to phase: `recon`, `gauntlet`, `sync`, `forge`
 - `--gauntlet-batch-size <N>` → batch size for gauntlet (default: 5)
-- `--yes` → skip all confirmation prompts in the orchestrator (pre-pipeline, forge checkpoint, and resume prompts)
+- `--yes` → skip all confirmation prompts in the orchestrator (pre-pipeline, forge checkpoint, and resume prompts) and in forge (per-phase confirmation)
 
 ---
 
@@ -95,6 +95,26 @@ If a sub-agent corrupts the state, G3 on the next iteration will detect it and r
 
 ---
 
+## Step 0.5 — Artifact pre-validation (--start-from only)
+
+**Only run this step if `--start-from` was specified.** Phases before the start point are being skipped — their artifacts must exist and be valid before proceeding.
+
+For each phase BEFORE `startPhase`, run the corresponding V-checks:
+
+| Skipped phase | Required artifacts + checks |
+|---------------|-----------------------------|
+| `recon` | V1 (titan-state.json structure), V2 (GLOBAL_ARCH.md), V4 (cross-check counts) |
+| `gauntlet` | V5 (coverage ≥ 50%), V6 (entry completeness sample), V7 (summary consistency); also run NDJSON integrity check (2c) |
+| `sync` | V8 (sync.json structure), V9 (targets trace to gauntlet), V10 (dependency order) |
+
+If ANY required artifact is **missing** → stop: "Cannot start from `<phase>` — `<artifact>` is missing. Run the full pipeline or start from an earlier phase."
+
+If ANY V-check that is normally VALIDATION FAILED would fail → stop with the same message as it would during normal execution.
+
+WARN-level V-checks from skipped phases are surfaced as prefixed warnings: "[skipped-phase pre-validation] <warning text>" — they do not stop the pipeline.
+
+---
+
 ## Step 1 — RECON
 
 **Skip if:** `--skip-recon`, `--start-from` is after recon, or `titan-state.json` already has `currentPhase` beyond `"recon"`.
diff --git a/docs/examples/claude-code-skills/titan-run/SKILL.md b/docs/examples/claude-code-skills/titan-run/SKILL.md
index 49e3b372..6a9eda18 100644
--- a/docs/examples/claude-code-skills/titan-run/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-run/SKILL.md
@@ -18,7 +18,7 @@ You are the **orchestrator** for the full Titan Paradigm pipeline. Your job is t
 - `--skip-gauntlet` → skip gauntlet (assumes artifacts exist)
 - `--start-from <phase>` → jump to phase: `recon`, `gauntlet`, `sync`, `forge`
 - `--gauntlet-batch-size <N>` → batch size for gauntlet (default: 5)
-- `--yes` → skip all confirmation prompts in the orchestrator (pre-pipeline, forge checkpoint, and resume prompts)
+- `--yes` → skip all confirmation prompts in the orchestrator (pre-pipeline, forge checkpoint, and resume prompts) and in forge (per-phase confirmation)
 
 ---
 
@@ -95,6 +95,26 @@ If a sub-agent corrupts the state, G3 on the next iteration will detect it and r
 
 ---
 
+## Step 0.5 — Artifact pre-validation (--start-from only)
+
+**Only run this step if `--start-from` was specified.** Phases before the start point are being skipped — their artifacts must exist and be valid before proceeding.
+
+For each phase BEFORE `startPhase`, run the corresponding V-checks:
+
+| Skipped phase | Required artifacts + checks |
+|---------------|-----------------------------|
+| `recon` | V1 (titan-state.json structure), V2 (GLOBAL_ARCH.md), V4 (cross-check counts) |
+| `gauntlet` | V5 (coverage ≥ 50%), V6 (entry completeness sample), V7 (summary consistency); also run NDJSON integrity check (2c) |
+| `sync` | V8 (sync.json structure), V9 (targets trace to gauntlet), V10 (dependency order) |
+
+If ANY required artifact is **missing** → stop: "Cannot start from `<phase>` — `<artifact>` is missing. Run the full pipeline or start from an earlier phase."
+
+If ANY V-check that is normally VALIDATION FAILED would fail → stop with the same message as it would during normal execution.
+
+WARN-level V-checks from skipped phases are surfaced as prefixed warnings: "[skipped-phase pre-validation] <warning text>" — they do not stop the pipeline.
+
+---
+
 ## Step 1 — RECON
 
 **Skip if:** `--skip-recon`, `--start-from` is after recon, or `titan-state.json` already has `currentPhase` beyond `"recon"`.

From 9274f3ffd83b812a1276cc9197ae0b16e1b75b26 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sat, 21 Mar 2026 23:56:50 -0600
Subject: [PATCH 19/52] =?UTF-8?q?fix:=20titan-run=20review=20=E2=80=94=20R?=
 =?UTF-8?q?ules=20exceptions,=20skip-flag=20validation,=20test=20runner?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 .claude/skills/titan-forge/SKILL.md                   | 4 ++--
 .claude/skills/titan-run/SKILL.md                     | 9 +++++----
 docs/examples/claude-code-skills/titan-forge/SKILL.md | 4 ++--
 docs/examples/claude-code-skills/titan-run/SKILL.md   | 9 +++++----
 4 files changed, 14 insertions(+), 12 deletions(-)

diff --git a/.claude/skills/titan-forge/SKILL.md b/.claude/skills/titan-forge/SKILL.md
index c199b5dd..ee0222e1 100644
--- a/.claude/skills/titan-forge/SKILL.md
+++ b/.claude/skills/titan-forge/SKILL.md
@@ -185,9 +185,9 @@ For each target in the current phase:
    **On DIFF FAIL:** Unstage and revert changes, add to `execution.failedTargets` with reason starting with `"diff-review: "`. Continue to next target.
    **On DIFF WARN:** Log the warning but proceed to gate. Include the warning in the gate-log entry.
 
-10. **Run tests:**
+10. **Run tests** (detect the project's test command from package.json scripts — `npm test`, `yarn test`, `pnpm test`, etc.):
     ```bash
-    npm test 2>&1
+    <detected-test-command> 2>&1
     ```
     If tests fail → go to rollback (step 13).
 
diff --git a/.claude/skills/titan-run/SKILL.md b/.claude/skills/titan-run/SKILL.md
index 6a9eda18..5331c728 100644
--- a/.claude/skills/titan-run/SKILL.md
+++ b/.claude/skills/titan-run/SKILL.md
@@ -95,9 +95,9 @@ If a sub-agent corrupts the state, G3 on the next iteration will detect it and r
 
 ---
 
-## Step 0.5 — Artifact pre-validation (--start-from only)
+## Step 0.5 — Artifact pre-validation (phase skip)
 
-**Only run this step if `--start-from` was specified.** Phases before the start point are being skipped — their artifacts must exist and be valid before proceeding.
+**Run this step if `--start-from` was specified, `--skip-recon` is set, or `--skip-gauntlet` is set.** Any of these flags cause phases to be skipped — their artifacts must exist and be valid before proceeding. When `--skip-recon` is set, validate recon artifacts. When `--skip-gauntlet` is set, validate both recon and gauntlet artifacts.
 
 For each phase BEFORE `startPhase`, run the corresponding V-checks:
 
@@ -484,7 +484,8 @@ while iteration < maxIterations:
 
     # V13. Test suite still green after forge commits
     # Quick sanity — run tests to make sure the cumulative commits haven't broken anything
-    npm test 2>&1
+    # Run the project's test command (detect from package.json scripts — npm test, yarn test, pnpm test, etc.)
+    <detected-test-command> 2>&1
     if tests fail:
         Print: "CRITICAL: Test suite fails after forge phase <nextPhase>. Stopping pipeline."
         Print: "Commits from this phase: git log --oneline <headBefore>..<headAfter>"
@@ -582,7 +583,7 @@ Artifacts:
 
 ## Rules
 
-- **You are the orchestrator, not the executor.** Never run codegraph commands, edit source files, or make commits yourself. Only spawn sub-agents and read state files. The ONE exception: the post-forge test run (V13) and NDJSON integrity checks are run directly since they're pure validation.
+- **You are the orchestrator, not the executor.** Never run codegraph commands, edit source files, or make commits yourself. Only spawn sub-agents and read state files. Exceptions (pure validation/snapshot, no code changes): the post-forge test run (V13), NDJSON integrity checks, and the pre-forge architectural snapshot capture (Step 3.5a) are run directly by the orchestrator.
 - **Run the Pre-Agent Gate (G1-G4) before EVERY sub-agent.** No exceptions.
 - **One sub-agent at a time.** Phases are sequential — recon before gauntlet, gauntlet before sync, sync before forge.
 - **Fresh context per sub-agent.** This is the whole point — each sub-agent gets a clean context window.
diff --git a/docs/examples/claude-code-skills/titan-forge/SKILL.md b/docs/examples/claude-code-skills/titan-forge/SKILL.md
index c199b5dd..ee0222e1 100644
--- a/docs/examples/claude-code-skills/titan-forge/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-forge/SKILL.md
@@ -185,9 +185,9 @@ For each target in the current phase:
    **On DIFF FAIL:** Unstage and revert changes, add to `execution.failedTargets` with reason starting with `"diff-review: "`. Continue to next target.
    **On DIFF WARN:** Log the warning but proceed to gate. Include the warning in the gate-log entry.
 
-10. **Run tests:**
+10. **Run tests** (detect the project's test command from package.json scripts — `npm test`, `yarn test`, `pnpm test`, etc.):
     ```bash
-    npm test 2>&1
+    <detected-test-command> 2>&1
     ```
     If tests fail → go to rollback (step 13).
 
diff --git a/docs/examples/claude-code-skills/titan-run/SKILL.md b/docs/examples/claude-code-skills/titan-run/SKILL.md
index 6a9eda18..5331c728 100644
--- a/docs/examples/claude-code-skills/titan-run/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-run/SKILL.md
@@ -95,9 +95,9 @@ If a sub-agent corrupts the state, G3 on the next iteration will detect it and r
 
 ---
 
-## Step 0.5 — Artifact pre-validation (--start-from only)
+## Step 0.5 — Artifact pre-validation (phase skip)
 
-**Only run this step if `--start-from` was specified.** Phases before the start point are being skipped — their artifacts must exist and be valid before proceeding.
+**Run this step if `--start-from` was specified, `--skip-recon` is set, or `--skip-gauntlet` is set.** Any of these flags cause phases to be skipped — their artifacts must exist and be valid before proceeding. When `--skip-recon` is set, validate recon artifacts. When `--skip-gauntlet` is set, validate both recon and gauntlet artifacts.
 
 For each phase BEFORE `startPhase`, run the corresponding V-checks:
 
@@ -484,7 +484,8 @@ while iteration < maxIterations:
 
     # V13. Test suite still green after forge commits
     # Quick sanity — run tests to make sure the cumulative commits haven't broken anything
-    npm test 2>&1
+    # Run the project's test command (detect from package.json scripts — npm test, yarn test, pnpm test, etc.)
+    <detected-test-command> 2>&1
     if tests fail:
         Print: "CRITICAL: Test suite fails after forge phase <nextPhase>. Stopping pipeline."
         Print: "Commits from this phase: git log --oneline <headBefore>..<headAfter>"
@@ -582,7 +583,7 @@ Artifacts:
 
 ## Rules
 
-- **You are the orchestrator, not the executor.** Never run codegraph commands, edit source files, or make commits yourself. Only spawn sub-agents and read state files. The ONE exception: the post-forge test run (V13) and NDJSON integrity checks are run directly since they're pure validation.
+- **You are the orchestrator, not the executor.** Never run codegraph commands, edit source files, or make commits yourself. Only spawn sub-agents and read state files. Exceptions (pure validation/snapshot, no code changes): the post-forge test run (V13), NDJSON integrity checks, and the pre-forge architectural snapshot capture (Step 3.5a) are run directly by the orchestrator.
 - **Run the Pre-Agent Gate (G1-G4) before EVERY sub-agent.** No exceptions.
 - **One sub-agent at a time.** Phases are sequential — recon before gauntlet, gauntlet before sync, sync before forge.
 - **Fresh context per sub-agent.** This is the whole point — each sub-agent gets a clean context window.

From f37ec9ea7e3f92dd4ea7fab707a551d62d78393b Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sun, 22 Mar 2026 18:49:41 -0600
Subject: [PATCH 20/52] fix: persist arch temp dir path to file instead of
 shell variable (#557)

TITAN_TMP_ID was set in one Bash tool invocation but referenced in
later invocations. Shell variables don't survive between separate
Bash calls. Now uses mktemp -d and writes the path to
.codegraph/titan/.arch-tmpdir for cross-invocation recovery.
---
 .claude/skills/titan-gate/SKILL.md            | 31 +++++++++++--------
 .../claude-code-skills/titan-gate/SKILL.md    | 31 +++++++++++--------
 2 files changed, 36 insertions(+), 26 deletions(-)

diff --git a/.claude/skills/titan-gate/SKILL.md b/.claude/skills/titan-gate/SKILL.md
index 1d1f8112..6c116dc4 100644
--- a/.claude/skills/titan-gate/SKILL.md
+++ b/.claude/skills/titan-gate/SKILL.md
@@ -178,24 +178,29 @@ Read `.codegraph/titan/arch-snapshot.json` if it exists (created by `/titan-run`
 
 ### Capture current state
 
+Use `mktemp -d` to create a unique temporary directory that persists across Bash invocations (shell variables like `$TITAN_TMP_ID` do not survive between separate Bash tool calls):
+
 ```bash
-TITAN_TMP_ID="$(date +%s)-$$"
-codegraph communities -T --json > /tmp/titan-arch-${TITAN_TMP_ID}-current-communities.json
-codegraph structure --depth 2 --json > /tmp/titan-arch-${TITAN_TMP_ID}-current-structure.json
-codegraph communities --drift -T --json > /tmp/titan-arch-${TITAN_TMP_ID}-current-drift.json
+TITAN_ARCH_DIR=$(mktemp -d /tmp/titan-arch-XXXXXX)
+echo "$TITAN_ARCH_DIR" > .codegraph/titan/.arch-tmpdir
+codegraph communities -T --json > "$TITAN_ARCH_DIR/current-communities.json"
+codegraph structure --depth 2 --json > "$TITAN_ARCH_DIR/current-structure.json"
+codegraph communities --drift -T --json > "$TITAN_ARCH_DIR/current-drift.json"
 ```
 
-### Compare
+> The path is written to `.codegraph/titan/.arch-tmpdir` so subsequent Bash invocations can recover it via `TITAN_ARCH_DIR=$(cat .codegraph/titan/.arch-tmpdir)`.
 
-**A1. Community stability:**
-Use the drift output (which uses content-based matching, not raw IDs, to track community movements across runs):
+### Compare
 
+In a new Bash invocation, recover the temp dir path first:
 ```bash
-# Compare current drift report against snapshot drift baseline
-# New drift warnings not present in arch-snapshot.json → side-effect restructuring
+TITAN_ARCH_DIR=$(cat .codegraph/titan/.arch-tmpdir)
 ```
 
-Read `.codegraph/titan/arch-snapshot.json → drift` (the pre-forge drift baseline) and compare against `/tmp/titan-arch-${TITAN_TMP_ID}-current-drift.json`:
+**A1. Community stability:**
+Use the drift output (which uses content-based matching, not raw IDs, to track community movements across runs):
+
+Read `.codegraph/titan/arch-snapshot.json → drift` (the pre-forge drift baseline) and compare against `$TITAN_ARCH_DIR/current-drift.json`:
 - For each **new** drift warning in current that was NOT present in the snapshot: if the drifted symbol was NOT touched in the diff → **WARN**: "Symbol `<name>` drifted community as a side effect"
 - If > 5 untouched symbols appear in new drift warnings → **FAIL**: "Significant community restructuring detected — <N> symbols drifted communities. This change may have unintended architectural impact."
 
@@ -222,9 +227,9 @@ Compare drift warnings between snapshot and current:
 ### Cleanup
 
 ```bash
-rm -f /tmp/titan-arch-${TITAN_TMP_ID}-current-communities.json \
-      /tmp/titan-arch-${TITAN_TMP_ID}-current-structure.json \
-      /tmp/titan-arch-${TITAN_TMP_ID}-current-drift.json
+TITAN_ARCH_DIR=$(cat .codegraph/titan/.arch-tmpdir)
+rm -rf "$TITAN_ARCH_DIR"
+rm -f .codegraph/titan/.arch-tmpdir
 ```
 
 ### Verdict integration
diff --git a/docs/examples/claude-code-skills/titan-gate/SKILL.md b/docs/examples/claude-code-skills/titan-gate/SKILL.md
index 1d1f8112..6c116dc4 100644
--- a/docs/examples/claude-code-skills/titan-gate/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-gate/SKILL.md
@@ -178,24 +178,29 @@ Read `.codegraph/titan/arch-snapshot.json` if it exists (created by `/titan-run`
 
 ### Capture current state
 
+Use `mktemp -d` to create a unique temporary directory that persists across Bash invocations (shell variables like `$TITAN_TMP_ID` do not survive between separate Bash tool calls):
+
 ```bash
-TITAN_TMP_ID="$(date +%s)-$$"
-codegraph communities -T --json > /tmp/titan-arch-${TITAN_TMP_ID}-current-communities.json
-codegraph structure --depth 2 --json > /tmp/titan-arch-${TITAN_TMP_ID}-current-structure.json
-codegraph communities --drift -T --json > /tmp/titan-arch-${TITAN_TMP_ID}-current-drift.json
+TITAN_ARCH_DIR=$(mktemp -d /tmp/titan-arch-XXXXXX)
+echo "$TITAN_ARCH_DIR" > .codegraph/titan/.arch-tmpdir
+codegraph communities -T --json > "$TITAN_ARCH_DIR/current-communities.json"
+codegraph structure --depth 2 --json > "$TITAN_ARCH_DIR/current-structure.json"
+codegraph communities --drift -T --json > "$TITAN_ARCH_DIR/current-drift.json"
 ```
 
-### Compare
+> The path is written to `.codegraph/titan/.arch-tmpdir` so subsequent Bash invocations can recover it via `TITAN_ARCH_DIR=$(cat .codegraph/titan/.arch-tmpdir)`.
 
-**A1. Community stability:**
-Use the drift output (which uses content-based matching, not raw IDs, to track community movements across runs):
+### Compare
 
+In a new Bash invocation, recover the temp dir path first:
 ```bash
-# Compare current drift report against snapshot drift baseline
-# New drift warnings not present in arch-snapshot.json → side-effect restructuring
+TITAN_ARCH_DIR=$(cat .codegraph/titan/.arch-tmpdir)
 ```
 
-Read `.codegraph/titan/arch-snapshot.json → drift` (the pre-forge drift baseline) and compare against `/tmp/titan-arch-${TITAN_TMP_ID}-current-drift.json`:
+**A1. Community stability:**
+Use the drift output (which uses content-based matching, not raw IDs, to track community movements across runs):
+
+Read `.codegraph/titan/arch-snapshot.json → drift` (the pre-forge drift baseline) and compare against `$TITAN_ARCH_DIR/current-drift.json`:
 - For each **new** drift warning in current that was NOT present in the snapshot: if the drifted symbol was NOT touched in the diff → **WARN**: "Symbol `<name>` drifted community as a side effect"
 - If > 5 untouched symbols appear in new drift warnings → **FAIL**: "Significant community restructuring detected — <N> symbols drifted communities. This change may have unintended architectural impact."
 
@@ -222,9 +227,9 @@ Compare drift warnings between snapshot and current:
 ### Cleanup
 
 ```bash
-rm -f /tmp/titan-arch-${TITAN_TMP_ID}-current-communities.json \
-      /tmp/titan-arch-${TITAN_TMP_ID}-current-structure.json \
-      /tmp/titan-arch-${TITAN_TMP_ID}-current-drift.json
+TITAN_ARCH_DIR=$(cat .codegraph/titan/.arch-tmpdir)
+rm -rf "$TITAN_ARCH_DIR"
+rm -f .codegraph/titan/.arch-tmpdir
 ```
 
 ### Verdict integration

From 058f02752ba3939b071c27e130339c8d49f55990 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sun, 22 Mar 2026 19:12:13 -0600
Subject: [PATCH 21/52] fix: capture git SHA in shell before node -e to avoid
 unevaluated substitution (#557)

---
 .claude/skills/titan-run/SKILL.md                   | 3 ++-
 docs/examples/claude-code-skills/titan-run/SKILL.md | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/titan-run/SKILL.md b/.claude/skills/titan-run/SKILL.md
index 5331c728..f7db8619 100644
--- a/.claude/skills/titan-run/SKILL.md
+++ b/.claude/skills/titan-run/SKILL.md
@@ -340,6 +340,7 @@ codegraph communities --drift -T --json > .codegraph/titan/arch-snapshot-drift.j
 Combine into a single snapshot file:
 
 ```bash
+TITAN_HEAD_SHA=$(git rev-parse HEAD)
 node -e "
 const fs = require('fs');
 const communities = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-communities.json','utf8'));
@@ -348,7 +349,7 @@ const drift = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-drift.j
 const snapshot = {
   timestamp: new Date().toISOString(),
   capturedBefore: 'forge',
-  headSha: '$(git rev-parse HEAD)',
+  headSha: '$TITAN_HEAD_SHA',
   communities,
   structure,
   drift
diff --git a/docs/examples/claude-code-skills/titan-run/SKILL.md b/docs/examples/claude-code-skills/titan-run/SKILL.md
index 5331c728..f7db8619 100644
--- a/docs/examples/claude-code-skills/titan-run/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-run/SKILL.md
@@ -340,6 +340,7 @@ codegraph communities --drift -T --json > .codegraph/titan/arch-snapshot-drift.j
 Combine into a single snapshot file:
 
 ```bash
+TITAN_HEAD_SHA=$(git rev-parse HEAD)
 node -e "
 const fs = require('fs');
 const communities = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-communities.json','utf8'));
@@ -348,7 +349,7 @@ const drift = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-drift.j
 const snapshot = {
   timestamp: new Date().toISOString(),
   capturedBefore: 'forge',
-  headSha: '$(git rev-parse HEAD)',
+  headSha: '$TITAN_HEAD_SHA',
   communities,
   structure,
   drift

From 9fe3b700001372aff3252d9a1f038857bbfeb9b5 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sun, 22 Mar 2026 19:12:22 -0600
Subject: [PATCH 22/52] fix: extend no-rollback exception to include semantic
 failures (Steps 5-8) (#557)

---
 .claude/skills/titan-gate/SKILL.md                   | 2 +-
 docs/examples/claude-code-skills/titan-gate/SKILL.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/titan-gate/SKILL.md b/.claude/skills/titan-gate/SKILL.md
index 6c116dc4..3d0ffc2b 100644
--- a/.claude/skills/titan-gate/SKILL.md
+++ b/.claude/skills/titan-gate/SKILL.md
@@ -298,7 +298,7 @@ Aggregate all checks:
 
 > "GATE FAIL: [reason]. Graph restored, changes unstaged but preserved. Fix and re-stage."
 
-For structural-only failures (Steps 1-3, 6-8), do NOT auto-rollback — report and let user decide.
+For structural-only and semantic failures (Steps 1-3, 5-8), do NOT auto-rollback — report and let user decide.
 
 ### Snapshot cleanup on pipeline completion
 
diff --git a/docs/examples/claude-code-skills/titan-gate/SKILL.md b/docs/examples/claude-code-skills/titan-gate/SKILL.md
index 6c116dc4..3d0ffc2b 100644
--- a/docs/examples/claude-code-skills/titan-gate/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-gate/SKILL.md
@@ -298,7 +298,7 @@ Aggregate all checks:
 
 > "GATE FAIL: [reason]. Graph restored, changes unstaged but preserved. Fix and re-stage."
 
-For structural-only failures (Steps 1-3, 6-8), do NOT auto-rollback — report and let user decide.
+For structural-only and semantic failures (Steps 1-3, 5-8), do NOT auto-rollback — report and let user decide.
 
 ### Snapshot cleanup on pipeline completion
 

From e4b6d9fad770f6e8758be32c4c41b1a942a0b819 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sun, 22 Mar 2026 19:12:30 -0600
Subject: [PATCH 23/52] fix: add explicit DIFF WARN verdicts to D5 leftover
 check (#557)

---
 .claude/skills/titan-forge/SKILL.md                   | 4 ++--
 docs/examples/claude-code-skills/titan-forge/SKILL.md | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.claude/skills/titan-forge/SKILL.md b/.claude/skills/titan-forge/SKILL.md
index ee0222e1..38a2af9e 100644
--- a/.claude/skills/titan-forge/SKILL.md
+++ b/.claude/skills/titan-forge/SKILL.md
@@ -179,8 +179,8 @@ For each target in the current phase:
 
    **D5. Leftover check:**
    If the gauntlet recommendation mentioned specific symbols to remove/refactor, verify they were actually addressed:
-   - Dead symbols listed for removal → should be deleted in the diff
-   - Functions marked for decomposition → original should be simplified or removed
+   - Dead symbols listed for removal but still present in the diff → **DIFF WARN**: "Gauntlet listed `<symbol>` for removal but it was not deleted."
+   - Functions marked for decomposition but original is unchanged → **DIFF WARN**: "Gauntlet recommended decomposing `<symbol>` but original function was not simplified."
 
    **On DIFF FAIL:** Unstage and revert changes, add to `execution.failedTargets` with reason starting with `"diff-review: "`. Continue to next target.
    **On DIFF WARN:** Log the warning but proceed to gate. Include the warning in the gate-log entry.
diff --git a/docs/examples/claude-code-skills/titan-forge/SKILL.md b/docs/examples/claude-code-skills/titan-forge/SKILL.md
index ee0222e1..38a2af9e 100644
--- a/docs/examples/claude-code-skills/titan-forge/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-forge/SKILL.md
@@ -179,8 +179,8 @@ For each target in the current phase:
 
    **D5. Leftover check:**
    If the gauntlet recommendation mentioned specific symbols to remove/refactor, verify they were actually addressed:
-   - Dead symbols listed for removal → should be deleted in the diff
-   - Functions marked for decomposition → original should be simplified or removed
+   - Dead symbols listed for removal but still present in the diff → **DIFF WARN**: "Gauntlet listed `<symbol>` for removal but it was not deleted."
+   - Functions marked for decomposition but original is unchanged → **DIFF WARN**: "Gauntlet recommended decomposing `<symbol>` but original function was not simplified."
 
    **On DIFF FAIL:** Unstage and revert changes, add to `execution.failedTargets` with reason starting with `"diff-review: "`. Continue to next target.
    **On DIFF WARN:** Log the warning but proceed to gate. Include the warning in the gate-log entry.

From a6bb4250d8fc94072b40c6d34bb54ef32340558a Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sun, 22 Mar 2026 19:21:52 -0600
Subject: [PATCH 24/52] fix: remove duplicate diff-impact call in Step 5c, add
 before/after comparison for Step 5d (#557)

---
 .claude/skills/titan-gate/SKILL.md                  | 13 ++++++++-----
 .../examples/claude-code-skills/titan-gate/SKILL.md | 13 ++++++++-----
 2 files changed, 16 insertions(+), 10 deletions(-)

diff --git a/.claude/skills/titan-gate/SKILL.md b/.claude/skills/titan-gate/SKILL.md
index 3d0ffc2b..d9df6414 100644
--- a/.claude/skills/titan-gate/SKILL.md
+++ b/.claude/skills/titan-gate/SKILL.md
@@ -144,11 +144,7 @@ If any `unresolved_import` warnings appear for files NOT changed in this commit
 
 ### 5c. Dependency direction assertions
 
-From diff-impact, extract any **new** edges (imports that didn't exist before):
-
-```bash
-codegraph diff-impact --staged -T --json
-```
+From the diff-impact results already collected in Step 2, extract any **new** edges (imports that didn't exist before).
 
 For each new dependency:
 - Check against `GLOBAL_ARCH.md` layer rules (if Titan artifacts exist)
@@ -160,6 +156,13 @@ For each new dependency:
 
 If the change modifies an index/barrel file (e.g., `index.js`, `mod.rs`):
 
+Capture the pre-change export list from the committed version:
+```bash
+git show HEAD:<barrel-file> > /tmp/titan-barrel-before.tmp
+codegraph exports /tmp/titan-barrel-before.tmp -T --json
+```
+
+Then capture the current (staged) export list:
 ```bash
 codegraph exports <barrel-file> -T --json
 ```
diff --git a/docs/examples/claude-code-skills/titan-gate/SKILL.md b/docs/examples/claude-code-skills/titan-gate/SKILL.md
index 3d0ffc2b..d9df6414 100644
--- a/docs/examples/claude-code-skills/titan-gate/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-gate/SKILL.md
@@ -144,11 +144,7 @@ If any `unresolved_import` warnings appear for files NOT changed in this commit
 
 ### 5c. Dependency direction assertions
 
-From diff-impact, extract any **new** edges (imports that didn't exist before):
-
-```bash
-codegraph diff-impact --staged -T --json
-```
+From the diff-impact results already collected in Step 2, extract any **new** edges (imports that didn't exist before).
 
 For each new dependency:
 - Check against `GLOBAL_ARCH.md` layer rules (if Titan artifacts exist)
@@ -160,6 +156,13 @@ For each new dependency:
 
 If the change modifies an index/barrel file (e.g., `index.js`, `mod.rs`):
 
+Capture the pre-change export list from the committed version:
+```bash
+git show HEAD:<barrel-file> > /tmp/titan-barrel-before.tmp
+codegraph exports /tmp/titan-barrel-before.tmp -T --json
+```
+
+Then capture the current (staged) export list:
 ```bash
 codegraph exports <barrel-file> -T --json
 ```

From 4e8669cdffc3b694dd2b0013c9057cf861c9a306 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sun, 22 Mar 2026 19:49:32 -0600
Subject: [PATCH 25/52] fix: correct stale step reference and use unique temp
 path in titan-gate (#557)

---
 .claude/skills/titan-gate/SKILL.md                   | 12 +++++++++---
 docs/examples/claude-code-skills/titan-gate/SKILL.md | 12 +++++++++---
 2 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/.claude/skills/titan-gate/SKILL.md b/.claude/skills/titan-gate/SKILL.md
index d9df6414..1bca19f0 100644
--- a/.claude/skills/titan-gate/SKILL.md
+++ b/.claude/skills/titan-gate/SKILL.md
@@ -144,7 +144,7 @@ If any `unresolved_import` warnings appear for files NOT changed in this commit
 
 ### 5c. Dependency direction assertions
 
-From the diff-impact results already collected in Step 2, extract any **new** edges (imports that didn't exist before).
+From the diff-impact results already collected in Step 1, extract any **new** edges (imports that didn't exist before).
 
 For each new dependency:
 - Check against `GLOBAL_ARCH.md` layer rules (if Titan artifacts exist)
@@ -158,8 +158,9 @@ If the change modifies an index/barrel file (e.g., `index.js`, `mod.rs`):
 
 Capture the pre-change export list from the committed version:
 ```bash
-git show HEAD:<barrel-file> > /tmp/titan-barrel-before.tmp
-codegraph exports /tmp/titan-barrel-before.tmp -T --json
+BARREL_TMP=$(mktemp /tmp/titan-barrel-XXXXXX)
+git show HEAD:<barrel-file> > "$BARREL_TMP"
+codegraph exports "$BARREL_TMP" -T --json
 ```
 
 Then capture the current (staged) export list:
@@ -169,6 +170,11 @@ codegraph exports <barrel-file> -T --json
 
 Compare export count before and after. If exports were **accidentally dropped** (count decreased and the removed exports have callers) → **FAIL**.
 
+Clean up the temp file:
+```bash
+rm -f "$BARREL_TMP"
+```
+
 ---
 
 ## Step 5.5 — Architectural snapshot comparison
diff --git a/docs/examples/claude-code-skills/titan-gate/SKILL.md b/docs/examples/claude-code-skills/titan-gate/SKILL.md
index d9df6414..1bca19f0 100644
--- a/docs/examples/claude-code-skills/titan-gate/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-gate/SKILL.md
@@ -144,7 +144,7 @@ If any `unresolved_import` warnings appear for files NOT changed in this commit
 
 ### 5c. Dependency direction assertions
 
-From the diff-impact results already collected in Step 2, extract any **new** edges (imports that didn't exist before).
+From the diff-impact results already collected in Step 1, extract any **new** edges (imports that didn't exist before).
 
 For each new dependency:
 - Check against `GLOBAL_ARCH.md` layer rules (if Titan artifacts exist)
@@ -158,8 +158,9 @@ If the change modifies an index/barrel file (e.g., `index.js`, `mod.rs`):
 
 Capture the pre-change export list from the committed version:
 ```bash
-git show HEAD:<barrel-file> > /tmp/titan-barrel-before.tmp
-codegraph exports /tmp/titan-barrel-before.tmp -T --json
+BARREL_TMP=$(mktemp /tmp/titan-barrel-XXXXXX)
+git show HEAD:<barrel-file> > "$BARREL_TMP"
+codegraph exports "$BARREL_TMP" -T --json
 ```
 
 Then capture the current (staged) export list:
@@ -169,6 +170,11 @@ codegraph exports <barrel-file> -T --json
 
 Compare export count before and after. If exports were **accidentally dropped** (count decreased and the removed exports have callers) → **FAIL**.
 
+Clean up the temp file:
+```bash
+rm -f "$BARREL_TMP"
+```
+
 ---
 
 ## Step 5.5 — Architectural snapshot comparison

From ed4851c181f70b32c65fb96ec0abf4af3ac6c5da Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sun, 22 Mar 2026 19:49:41 -0600
Subject: [PATCH 26/52] fix: remove stale --yes from argument-hint and add D5
 explicit verdict in titan-forge (#557)

---
 .claude/skills/titan-forge/SKILL.md                   | 3 ++-
 docs/examples/claude-code-skills/titan-forge/SKILL.md | 3 ++-
 2 files changed, 4 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/titan-forge/SKILL.md b/.claude/skills/titan-forge/SKILL.md
index 38a2af9e..9f2d400c 100644
--- a/.claude/skills/titan-forge/SKILL.md
+++ b/.claude/skills/titan-forge/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: titan-forge
 description: Execute the sync.json plan — refactor code, validate with /titan-gate, commit, and advance state (Titan Paradigm Phase 4)
-argument-hint: <--phase N> <--target name> <--dry-run> <--yes>
+argument-hint: <--phase N> <--target name> <--dry-run>
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Skill, Agent
 ---
 
@@ -181,6 +181,7 @@ For each target in the current phase:
    If the gauntlet recommendation mentioned specific symbols to remove/refactor, verify they were actually addressed:
    - Dead symbols listed for removal but still present in the diff → **DIFF WARN**: "Gauntlet listed `<symbol>` for removal but it was not deleted."
    - Functions marked for decomposition but original is unchanged → **DIFF WARN**: "Gauntlet recommended decomposing `<symbol>` but original function was not simplified."
+   - If all recommended symbols were addressed → **DIFF PASS** (implicit — no warnings emitted)
 
    **On DIFF FAIL:** Unstage and revert changes, add to `execution.failedTargets` with reason starting with `"diff-review: "`. Continue to next target.
    **On DIFF WARN:** Log the warning but proceed to gate. Include the warning in the gate-log entry.
diff --git a/docs/examples/claude-code-skills/titan-forge/SKILL.md b/docs/examples/claude-code-skills/titan-forge/SKILL.md
index 38a2af9e..9f2d400c 100644
--- a/docs/examples/claude-code-skills/titan-forge/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-forge/SKILL.md
@@ -1,7 +1,7 @@
 ---
 name: titan-forge
 description: Execute the sync.json plan — refactor code, validate with /titan-gate, commit, and advance state (Titan Paradigm Phase 4)
-argument-hint: <--phase N> <--target name> <--dry-run> <--yes>
+argument-hint: <--phase N> <--target name> <--dry-run>
 allowed-tools: Bash, Read, Write, Edit, Glob, Grep, Skill, Agent
 ---
 
@@ -181,6 +181,7 @@ For each target in the current phase:
    If the gauntlet recommendation mentioned specific symbols to remove/refactor, verify they were actually addressed:
    - Dead symbols listed for removal but still present in the diff → **DIFF WARN**: "Gauntlet listed `<symbol>` for removal but it was not deleted."
    - Functions marked for decomposition but original is unchanged → **DIFF WARN**: "Gauntlet recommended decomposing `<symbol>` but original function was not simplified."
+   - If all recommended symbols were addressed → **DIFF PASS** (implicit — no warnings emitted)
 
    **On DIFF FAIL:** Unstage and revert changes, add to `execution.failedTargets` with reason starting with `"diff-review: "`. Continue to next target.
    **On DIFF WARN:** Log the warning but proceed to gate. Include the warning in the gate-log entry.

From ce85671527b72c009733b0e8b7307977b38905e4 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sun, 22 Mar 2026 21:24:50 -0600
Subject: [PATCH 27/52] fix: address open review items in titan-gate and
 titan-forge (#557)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Disambiguate no-rollback step range: "Steps 1-3, 5-8" → "Steps 1-3, 5, 5.5, 6-8"
  so AI agents include Step 5.5 (architectural snapshot) in the exception
- Guarantee Step 5.5 cleanup runs even on failure/early exit paths
- Fix Step 13 heading: exclude diff-review (handled by Step 9's own rollback)
- Replace hardcoded npm test in gate Step 4 with test runner detection
- Applied to both .claude/skills/ and docs/examples/ copies
---
 .claude/skills/titan-forge/SKILL.md               |  2 +-
 .claude/skills/titan-gate/SKILL.md                | 15 ++++++++++-----
 .../claude-code-skills/titan-forge/SKILL.md       |  2 +-
 .../claude-code-skills/titan-gate/SKILL.md        | 15 ++++++++++-----
 4 files changed, 22 insertions(+), 12 deletions(-)

diff --git a/.claude/skills/titan-forge/SKILL.md b/.claude/skills/titan-forge/SKILL.md
index 9f2d400c..7d83baad 100644
--- a/.claude/skills/titan-forge/SKILL.md
+++ b/.claude/skills/titan-forge/SKILL.md
@@ -204,7 +204,7 @@ For each target in the current phase:
     - Record any diff-review warnings in `execution.diffWarnings` (if any)
     - Update `titan-state.json`
 
-13. **On failure (test, gate, or diff-review):**
+13. **On failure (test or gate):**
     ```bash
     git reset HEAD <changed files>
     git checkout -- <changed files>
diff --git a/.claude/skills/titan-gate/SKILL.md b/.claude/skills/titan-gate/SKILL.md
index 1bca19f0..f363125c 100644
--- a/.claude/skills/titan-gate/SKILL.md
+++ b/.claude/skills/titan-gate/SKILL.md
@@ -104,7 +104,8 @@ npm run build 2>&1 || echo "BUILD_FAILED"
 (Skip if no `build` script.)
 
 ```bash
-npm test 2>&1 || echo "TEST_FAILED"
+# Detect test command from package.json scripts (npm test, yarn test, pnpm test, etc.)
+<test-runner> test 2>&1 || echo "TEST_FAILED"
 ```
 
 If any fail → overall verdict is FAIL → proceed to auto-rollback.
@@ -233,11 +234,15 @@ Compare drift warnings between snapshot and current:
 - New drift warning not in snapshot → **WARN** with details
 - Drift warning resolved → note as positive
 
-### Cleanup
+### Cleanup (MUST run even on failure or early exit)
+
+This cleanup block MUST execute regardless of the verdict — including FAIL paths and early exits. Run it before proceeding to Step 9 (verdict aggregation), not after.
 
 ```bash
-TITAN_ARCH_DIR=$(cat .codegraph/titan/.arch-tmpdir)
-rm -rf "$TITAN_ARCH_DIR"
+TITAN_ARCH_DIR=$(cat .codegraph/titan/.arch-tmpdir 2>/dev/null)
+if [ -n "$TITAN_ARCH_DIR" ]; then
+  rm -rf "$TITAN_ARCH_DIR"
+fi
 rm -f .codegraph/titan/.arch-tmpdir
 ```
 
@@ -307,7 +312,7 @@ Aggregate all checks:
 
 > "GATE FAIL: [reason]. Graph restored, changes unstaged but preserved. Fix and re-stage."
 
-For structural-only and semantic failures (Steps 1-3, 5-8), do NOT auto-rollback — report and let user decide.
+For structural-only and semantic failures (Steps 1-3, 5, 5.5, 6-8), do NOT auto-rollback — report and let user decide.
 
 ### Snapshot cleanup on pipeline completion
 
diff --git a/docs/examples/claude-code-skills/titan-forge/SKILL.md b/docs/examples/claude-code-skills/titan-forge/SKILL.md
index 9f2d400c..7d83baad 100644
--- a/docs/examples/claude-code-skills/titan-forge/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-forge/SKILL.md
@@ -204,7 +204,7 @@ For each target in the current phase:
     - Record any diff-review warnings in `execution.diffWarnings` (if any)
     - Update `titan-state.json`
 
-13. **On failure (test, gate, or diff-review):**
+13. **On failure (test or gate):**
     ```bash
     git reset HEAD <changed files>
     git checkout -- <changed files>
diff --git a/docs/examples/claude-code-skills/titan-gate/SKILL.md b/docs/examples/claude-code-skills/titan-gate/SKILL.md
index 1bca19f0..f363125c 100644
--- a/docs/examples/claude-code-skills/titan-gate/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-gate/SKILL.md
@@ -104,7 +104,8 @@ npm run build 2>&1 || echo "BUILD_FAILED"
 (Skip if no `build` script.)
 
 ```bash
-npm test 2>&1 || echo "TEST_FAILED"
+# Detect test command from package.json scripts (npm test, yarn test, pnpm test, etc.)
+<test-runner> test 2>&1 || echo "TEST_FAILED"
 ```
 
 If any fail → overall verdict is FAIL → proceed to auto-rollback.
@@ -233,11 +234,15 @@ Compare drift warnings between snapshot and current:
 - New drift warning not in snapshot → **WARN** with details
 - Drift warning resolved → note as positive
 
-### Cleanup
+### Cleanup (MUST run even on failure or early exit)
+
+This cleanup block MUST execute regardless of the verdict — including FAIL paths and early exits. Run it before proceeding to Step 9 (verdict aggregation), not after.
 
 ```bash
-TITAN_ARCH_DIR=$(cat .codegraph/titan/.arch-tmpdir)
-rm -rf "$TITAN_ARCH_DIR"
+TITAN_ARCH_DIR=$(cat .codegraph/titan/.arch-tmpdir 2>/dev/null)
+if [ -n "$TITAN_ARCH_DIR" ]; then
+  rm -rf "$TITAN_ARCH_DIR"
+fi
 rm -f .codegraph/titan/.arch-tmpdir
 ```
 
@@ -307,7 +312,7 @@ Aggregate all checks:
 
 > "GATE FAIL: [reason]. Graph restored, changes unstaged but preserved. Fix and re-stage."
 
-For structural-only and semantic failures (Steps 1-3, 5-8), do NOT auto-rollback — report and let user decide.
+For structural-only and semantic failures (Steps 1-3, 5, 5.5, 6-8), do NOT auto-rollback — report and let user decide.
 
 ### Snapshot cleanup on pipeline completion
 

From e5d8901261e2e5f28494015f5458611789710492 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Sun, 22 Mar 2026 23:18:20 -0600
Subject: [PATCH 28/52] fix: address round 2 Greptile feedback on titan-gate
 and titan-forge (#557)

- Fix BARREL_TMP cleanup: use sidecar file pattern (.barrel-tmp) to
  persist temp path across shell invocations, matching the existing
  .arch-tmpdir pattern
- Remove redundant codegraph check in Step 5b: reuse results already
  collected in Step 2 instead of re-running the command
- Spell out D4 deletion audit: add explicit guidance on identifying
  deleted symbols via pre-change file comparison and git diff
- All changes applied to both .claude/skills/ and docs/examples/ copies
---
 .claude/skills/titan-forge/SKILL.md               |  7 ++++++-
 .claude/skills/titan-gate/SKILL.md                | 15 +++++++--------
 .../claude-code-skills/titan-forge/SKILL.md       |  7 ++++++-
 .../claude-code-skills/titan-gate/SKILL.md        | 15 +++++++--------
 4 files changed, 26 insertions(+), 18 deletions(-)

diff --git a/.claude/skills/titan-forge/SKILL.md b/.claude/skills/titan-forge/SKILL.md
index 7d83baad..9b40261f 100644
--- a/.claude/skills/titan-forge/SKILL.md
+++ b/.claude/skills/titan-forge/SKILL.md
@@ -171,7 +171,12 @@ For each target in the current phase:
    - Message says "extract X from Y" but diff only modifies Y without creating X → **DIFF FAIL**
 
    **D4. Deletion audit:**
-   If the diff deletes code (lines removed > 10):
+   If the diff deletes code (lines removed > 10), identify deleted symbols by comparing the pre-change file against removed lines:
+   ```bash
+   # Get the pre-change version's symbols
+   codegraph where --file <(git show HEAD:<changed-file>) -T --json 2>/dev/null
+   ```
+   Cross-reference with `git diff --cached -- <changed-file>` to find symbols whose definitions appear only in removed lines (lines starting with `-`). For each deleted symbol:
    ```bash
    codegraph fn-impact <deleted-symbol> -T --json 2>/dev/null
    ```
diff --git a/.claude/skills/titan-gate/SKILL.md b/.claude/skills/titan-gate/SKILL.md
index f363125c..7ef0269a 100644
--- a/.claude/skills/titan-gate/SKILL.md
+++ b/.claude/skills/titan-gate/SKILL.md
@@ -135,11 +135,7 @@ For each **exported** symbol in changed files:
 
 ### 5b. Import resolution integrity
 
-Verify that all imports still resolve after the change:
-
-```bash
-codegraph check --staged -T --json
-```
+From the `codegraph check` results already collected in Step 2 (which includes `--staged`), extract any `unresolved_import` warnings.
 
 If any `unresolved_import` warnings appear for files NOT changed in this commit → **FAIL**: "Change broke import resolution for <file>: <import>"
 
@@ -157,9 +153,10 @@ For each new dependency:
 
 If the change modifies an index/barrel file (e.g., `index.js`, `mod.rs`):
 
-Capture the pre-change export list from the committed version:
+Capture the pre-change export list from the committed version (write the temp path to a sidecar file so it persists across Bash invocations):
 ```bash
 BARREL_TMP=$(mktemp /tmp/titan-barrel-XXXXXX)
+echo "$BARREL_TMP" > .codegraph/titan/.barrel-tmp
 git show HEAD:<barrel-file> > "$BARREL_TMP"
 codegraph exports "$BARREL_TMP" -T --json
 ```
@@ -171,9 +168,11 @@ codegraph exports <barrel-file> -T --json
 
 Compare export count before and after. If exports were **accidentally dropped** (count decreased and the removed exports have callers) → **FAIL**.
 
-Clean up the temp file:
+Clean up the temp file (recover path from sidecar):
 ```bash
-rm -f "$BARREL_TMP"
+BARREL_TMP=$(cat .codegraph/titan/.barrel-tmp 2>/dev/null)
+if [ -n "$BARREL_TMP" ]; then rm -f "$BARREL_TMP"; fi
+rm -f .codegraph/titan/.barrel-tmp
 ```
 
 ---
diff --git a/docs/examples/claude-code-skills/titan-forge/SKILL.md b/docs/examples/claude-code-skills/titan-forge/SKILL.md
index 7d83baad..9b40261f 100644
--- a/docs/examples/claude-code-skills/titan-forge/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-forge/SKILL.md
@@ -171,7 +171,12 @@ For each target in the current phase:
    - Message says "extract X from Y" but diff only modifies Y without creating X → **DIFF FAIL**
 
    **D4. Deletion audit:**
-   If the diff deletes code (lines removed > 10):
+   If the diff deletes code (lines removed > 10), identify deleted symbols by comparing the pre-change file against removed lines:
+   ```bash
+   # Get the pre-change version's symbols
+   codegraph where --file <(git show HEAD:<changed-file>) -T --json 2>/dev/null
+   ```
+   Cross-reference with `git diff --cached -- <changed-file>` to find symbols whose definitions appear only in removed lines (lines starting with `-`). For each deleted symbol:
    ```bash
    codegraph fn-impact <deleted-symbol> -T --json 2>/dev/null
    ```
diff --git a/docs/examples/claude-code-skills/titan-gate/SKILL.md b/docs/examples/claude-code-skills/titan-gate/SKILL.md
index f363125c..7ef0269a 100644
--- a/docs/examples/claude-code-skills/titan-gate/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-gate/SKILL.md
@@ -135,11 +135,7 @@ For each **exported** symbol in changed files:
 
 ### 5b. Import resolution integrity
 
-Verify that all imports still resolve after the change:
-
-```bash
-codegraph check --staged -T --json
-```
+From the `codegraph check` results already collected in Step 2 (which includes `--staged`), extract any `unresolved_import` warnings.
 
 If any `unresolved_import` warnings appear for files NOT changed in this commit → **FAIL**: "Change broke import resolution for <file>: <import>"
 
@@ -157,9 +153,10 @@ For each new dependency:
 
 If the change modifies an index/barrel file (e.g., `index.js`, `mod.rs`):
 
-Capture the pre-change export list from the committed version:
+Capture the pre-change export list from the committed version (write the temp path to a sidecar file so it persists across Bash invocations):
 ```bash
 BARREL_TMP=$(mktemp /tmp/titan-barrel-XXXXXX)
+echo "$BARREL_TMP" > .codegraph/titan/.barrel-tmp
 git show HEAD:<barrel-file> > "$BARREL_TMP"
 codegraph exports "$BARREL_TMP" -T --json
 ```
@@ -171,9 +168,11 @@ codegraph exports <barrel-file> -T --json
 
 Compare export count before and after. If exports were **accidentally dropped** (count decreased and the removed exports have callers) → **FAIL**.
 
-Clean up the temp file:
+Clean up the temp file (recover path from sidecar):
 ```bash
-rm -f "$BARREL_TMP"
+BARREL_TMP=$(cat .codegraph/titan/.barrel-tmp 2>/dev/null)
+if [ -n "$BARREL_TMP" ]; then rm -f "$BARREL_TMP"; fi
+rm -f .codegraph/titan/.barrel-tmp
 ```
 
 ---

From bef6a03156e88835a2138673ccfba52227e0ccad Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 02:11:03 -0600
Subject: [PATCH 29/52] fix: correct Step 5b reference from Step 2 to Step 1 in
 titan-gate (#557)

---
 .claude/skills/titan-gate/SKILL.md                   | 2 +-
 docs/examples/claude-code-skills/titan-gate/SKILL.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/titan-gate/SKILL.md b/.claude/skills/titan-gate/SKILL.md
index 7ef0269a..0c0ec458 100644
--- a/.claude/skills/titan-gate/SKILL.md
+++ b/.claude/skills/titan-gate/SKILL.md
@@ -135,7 +135,7 @@ For each **exported** symbol in changed files:
 
 ### 5b. Import resolution integrity
 
-From the `codegraph check` results already collected in Step 2 (which includes `--staged`), extract any `unresolved_import` warnings.
+From the `codegraph check` results already collected in Step 1 (which includes `--staged`), extract any `unresolved_import` warnings.
 
 If any `unresolved_import` warnings appear for files NOT changed in this commit → **FAIL**: "Change broke import resolution for <file>: <import>"
 
diff --git a/docs/examples/claude-code-skills/titan-gate/SKILL.md b/docs/examples/claude-code-skills/titan-gate/SKILL.md
index 7ef0269a..0c0ec458 100644
--- a/docs/examples/claude-code-skills/titan-gate/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-gate/SKILL.md
@@ -135,7 +135,7 @@ For each **exported** symbol in changed files:
 
 ### 5b. Import resolution integrity
 
-From the `codegraph check` results already collected in Step 2 (which includes `--staged`), extract any `unresolved_import` warnings.
+From the `codegraph check` results already collected in Step 1 (which includes `--staged`), extract any `unresolved_import` warnings.
 
 If any `unresolved_import` warnings appear for files NOT changed in this commit → **FAIL**: "Change broke import resolution for <file>: <import>"
 

From c36861d3d755882f0f47cfec6dfb16bc83fcc897 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 02:11:12 -0600
Subject: [PATCH 30/52] fix: replace bash process substitution with temp file
 in D4 deletion audit (#557)

---
 .claude/skills/titan-forge/SKILL.md                   | 7 +++++--
 docs/examples/claude-code-skills/titan-forge/SKILL.md | 7 +++++--
 2 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/.claude/skills/titan-forge/SKILL.md b/.claude/skills/titan-forge/SKILL.md
index 9b40261f..fdfd319e 100644
--- a/.claude/skills/titan-forge/SKILL.md
+++ b/.claude/skills/titan-forge/SKILL.md
@@ -173,8 +173,11 @@ For each target in the current phase:
    **D4. Deletion audit:**
    If the diff deletes code (lines removed > 10), identify deleted symbols by comparing the pre-change file against removed lines:
    ```bash
-   # Get the pre-change version's symbols
-   codegraph where --file <(git show HEAD:<changed-file>) -T --json 2>/dev/null
+   # Get the pre-change version's symbols (temp file for shell portability)
+   D4_PRE_TMP=$(mktemp /tmp/titan-d4-pre-XXXXXX)
+   git show HEAD:<changed-file> > "$D4_PRE_TMP"
+   codegraph where --file "$D4_PRE_TMP" -T --json 2>/dev/null
+   rm -f "$D4_PRE_TMP"
    ```
    Cross-reference with `git diff --cached -- <changed-file>` to find symbols whose definitions appear only in removed lines (lines starting with `-`). For each deleted symbol:
    ```bash
diff --git a/docs/examples/claude-code-skills/titan-forge/SKILL.md b/docs/examples/claude-code-skills/titan-forge/SKILL.md
index 9b40261f..fdfd319e 100644
--- a/docs/examples/claude-code-skills/titan-forge/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-forge/SKILL.md
@@ -173,8 +173,11 @@ For each target in the current phase:
    **D4. Deletion audit:**
    If the diff deletes code (lines removed > 10), identify deleted symbols by comparing the pre-change file against removed lines:
    ```bash
-   # Get the pre-change version's symbols
-   codegraph where --file <(git show HEAD:<changed-file>) -T --json 2>/dev/null
+   # Get the pre-change version's symbols (temp file for shell portability)
+   D4_PRE_TMP=$(mktemp /tmp/titan-d4-pre-XXXXXX)
+   git show HEAD:<changed-file> > "$D4_PRE_TMP"
+   codegraph where --file "$D4_PRE_TMP" -T --json 2>/dev/null
+   rm -f "$D4_PRE_TMP"
    ```
    Cross-reference with `git diff --cached -- <changed-file>` to find symbols whose definitions appear only in removed lines (lines starting with `-`). For each deleted symbol:
    ```bash

From cd51577fc234cbaec0b985f2aedcb90df9430b8d Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 02:28:43 -0600
Subject: [PATCH 31/52] fix: clarify A2 boundary check uses diff-impact edges
 not snapshot (#557)

---
 .claude/skills/titan-gate/SKILL.md                   | 5 +++--
 docs/examples/claude-code-skills/titan-gate/SKILL.md | 5 +++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/.claude/skills/titan-gate/SKILL.md b/.claude/skills/titan-gate/SKILL.md
index 0c0ec458..8c835016 100644
--- a/.claude/skills/titan-gate/SKILL.md
+++ b/.claude/skills/titan-gate/SKILL.md
@@ -216,11 +216,12 @@ Read `.codegraph/titan/arch-snapshot.json → drift` (the pre-forge drift baseli
 **A2. Dependency direction between domains:**
 From `GLOBAL_ARCH.md`, extract the expected dependency direction between domains (e.g., "presentation depends on features, not the reverse").
 
-Check if any new cross-domain dependency violates the expected direction:
+Check if any new cross-domain dependency violates the expected direction. "New" means the edge appears in the Step 1 diff-impact results (i.e., it was introduced by the staged changes):
 ```bash
 codegraph deps <changed-file> --json
 ```
-- New upward dependency (lower layer importing higher layer) not present in snapshot → **FAIL**
+- New upward dependency (lower layer importing higher layer) introduced in this diff → **FAIL**
+- Pre-existing boundary violations not surfaced by Step 5c's staged-diff results → advisory-only (not gating)
 - New lateral dependency within the same layer → **OK**
 
 **A3. Cohesion delta:**
diff --git a/docs/examples/claude-code-skills/titan-gate/SKILL.md b/docs/examples/claude-code-skills/titan-gate/SKILL.md
index 0c0ec458..8c835016 100644
--- a/docs/examples/claude-code-skills/titan-gate/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-gate/SKILL.md
@@ -216,11 +216,12 @@ Read `.codegraph/titan/arch-snapshot.json → drift` (the pre-forge drift baseli
 **A2. Dependency direction between domains:**
 From `GLOBAL_ARCH.md`, extract the expected dependency direction between domains (e.g., "presentation depends on features, not the reverse").
 
-Check if any new cross-domain dependency violates the expected direction:
+Check if any new cross-domain dependency violates the expected direction. "New" means the edge appears in the Step 1 diff-impact results (i.e., it was introduced by the staged changes):
 ```bash
 codegraph deps <changed-file> --json
 ```
-- New upward dependency (lower layer importing higher layer) not present in snapshot → **FAIL**
+- New upward dependency (lower layer importing higher layer) introduced in this diff → **FAIL**
+- Pre-existing boundary violations not surfaced by Step 5c's staged-diff results → advisory-only (not gating)
 - New lateral dependency within the same layer → **OK**
 
 **A3. Cohesion delta:**

From 1f5cc23bacd13708b419cbf0c991a64081ec0ca1 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 02:28:56 -0600
Subject: [PATCH 32/52] fix: restore FORGE to complexity --health command table
 row (#557)

---
 docs/examples/claude-code-skills/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/examples/claude-code-skills/README.md b/docs/examples/claude-code-skills/README.md
index 5a112731..d4009c5e 100644
--- a/docs/examples/claude-code-skills/README.md
+++ b/docs/examples/claude-code-skills/README.md
@@ -187,7 +187,7 @@ All skills enforce worktree isolation as their first step. If invoked from the m
 | `codegraph communities` | RECON, GATE | Module boundaries and drift |
 | `codegraph roles` | RECON, GAUNTLET | Core/dead/entry symbol classification |
 | `codegraph structure` | RECON, GATE | Directory cohesion |
-| `codegraph complexity --health` | RECON, GAUNTLET, GATE | Full metrics: cognitive, cyclomatic, nesting, Halstead, MI |
+| `codegraph complexity --health` | RECON, GAUNTLET, GATE, FORGE | Full metrics: cognitive, cyclomatic, nesting, Halstead, MI |
 | `codegraph complexity --above-threshold` | RECON | Only functions exceeding thresholds |
 | `codegraph batch complexity` | GAUNTLET | Multi-target complexity in one call |
 | `codegraph batch context` | GAUNTLET | Multi-target context in one call |

From 512ba3c365c02ffbe613639d797081a154ee3d38 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 02:29:05 -0600
Subject: [PATCH 33/52] fix: add V3 snapshot list to orchestrator Rules
 exception list (#557)

---
 .claude/skills/titan-run/SKILL.md                   | 2 +-
 docs/examples/claude-code-skills/titan-run/SKILL.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/titan-run/SKILL.md b/.claude/skills/titan-run/SKILL.md
index f7db8619..5789a6c4 100644
--- a/.claude/skills/titan-run/SKILL.md
+++ b/.claude/skills/titan-run/SKILL.md
@@ -584,7 +584,7 @@ Artifacts:
 
 ## Rules
 
-- **You are the orchestrator, not the executor.** Never run codegraph commands, edit source files, or make commits yourself. Only spawn sub-agents and read state files. Exceptions (pure validation/snapshot, no code changes): the post-forge test run (V13), NDJSON integrity checks, and the pre-forge architectural snapshot capture (Step 3.5a) are run directly by the orchestrator.
+- **You are the orchestrator, not the executor.** Never run codegraph commands, edit source files, or make commits yourself. Only spawn sub-agents and read state files. Exceptions (pure validation/snapshot, no code changes): the post-forge test run (V13), NDJSON integrity checks, the V3 baseline snapshot check (`codegraph snapshot list`), and the pre-forge architectural snapshot capture (Step 3.5a) are run directly by the orchestrator.
 - **Run the Pre-Agent Gate (G1-G4) before EVERY sub-agent.** No exceptions.
 - **One sub-agent at a time.** Phases are sequential — recon before gauntlet, gauntlet before sync, sync before forge.
 - **Fresh context per sub-agent.** This is the whole point — each sub-agent gets a clean context window.
diff --git a/docs/examples/claude-code-skills/titan-run/SKILL.md b/docs/examples/claude-code-skills/titan-run/SKILL.md
index f7db8619..5789a6c4 100644
--- a/docs/examples/claude-code-skills/titan-run/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-run/SKILL.md
@@ -584,7 +584,7 @@ Artifacts:
 
 ## Rules
 
-- **You are the orchestrator, not the executor.** Never run codegraph commands, edit source files, or make commits yourself. Only spawn sub-agents and read state files. Exceptions (pure validation/snapshot, no code changes): the post-forge test run (V13), NDJSON integrity checks, and the pre-forge architectural snapshot capture (Step 3.5a) are run directly by the orchestrator.
+- **You are the orchestrator, not the executor.** Never run codegraph commands, edit source files, or make commits yourself. Only spawn sub-agents and read state files. Exceptions (pure validation/snapshot, no code changes): the post-forge test run (V13), NDJSON integrity checks, the V3 baseline snapshot check (`codegraph snapshot list`), and the pre-forge architectural snapshot capture (Step 3.5a) are run directly by the orchestrator.
 - **Run the Pre-Agent Gate (G1-G4) before EVERY sub-agent.** No exceptions.
 - **One sub-agent at a time.** Phases are sequential — recon before gauntlet, gauntlet before sync, sync before forge.
 - **Fresh context per sub-agent.** This is the whole point — each sub-agent gets a clean context window.

From cd07a9370b8ec73a42d07aa11d235b69c27b3d51 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 02:55:22 -0600
Subject: [PATCH 34/52] fix: replace A4 new-drift-warning check with
 resolved-drift positive signal (#557)

A4 overlapped with A1 producing false positives for touched symbols and
duplicate warnings for untouched ones. A1 already covers new drift
detection with severity escalation. A4 now only reports resolved drift
as a positive architectural improvement note.
---
 .claude/skills/titan-gate/SKILL.md                   | 7 +++----
 docs/examples/claude-code-skills/titan-gate/SKILL.md | 7 +++----
 2 files changed, 6 insertions(+), 8 deletions(-)

diff --git a/.claude/skills/titan-gate/SKILL.md b/.claude/skills/titan-gate/SKILL.md
index 8c835016..b226f08c 100644
--- a/.claude/skills/titan-gate/SKILL.md
+++ b/.claude/skills/titan-gate/SKILL.md
@@ -229,10 +229,9 @@ Compare directory cohesion scores from `structure`:
 - If any directory's cohesion dropped by > 0.2 → **WARN**: "Directory `<dir>` cohesion dropped from <X> to <Y>"
 - If a directory went from above 0.5 to below 0.3 → **FAIL**: "Directory `<dir>` became tangled (cohesion <X> → <Y>)"
 
-**A4. New drift warnings:**
-Compare drift warnings between snapshot and current:
-- New drift warning not in snapshot → **WARN** with details
-- Drift warning resolved → note as positive
+**A4. Resolved drift warnings (positive signal):**
+Compare drift warnings between snapshot and current. A1 already covers new drift warnings — A4 only reports resolved ones:
+- If any drift warning that was present in the snapshot is absent from `$TITAN_ARCH_DIR/current-drift.json` → note as positive: "Symbol `<name>` community drift resolved — architecture improved"
 
 ### Cleanup (MUST run even on failure or early exit)
 
diff --git a/docs/examples/claude-code-skills/titan-gate/SKILL.md b/docs/examples/claude-code-skills/titan-gate/SKILL.md
index 8c835016..b226f08c 100644
--- a/docs/examples/claude-code-skills/titan-gate/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-gate/SKILL.md
@@ -229,10 +229,9 @@ Compare directory cohesion scores from `structure`:
 - If any directory's cohesion dropped by > 0.2 → **WARN**: "Directory `<dir>` cohesion dropped from <X> to <Y>"
 - If a directory went from above 0.5 to below 0.3 → **FAIL**: "Directory `<dir>` became tangled (cohesion <X> → <Y>)"
 
-**A4. New drift warnings:**
-Compare drift warnings between snapshot and current:
-- New drift warning not in snapshot → **WARN** with details
-- Drift warning resolved → note as positive
+**A4. Resolved drift warnings (positive signal):**
+Compare drift warnings between snapshot and current. A1 already covers new drift warnings — A4 only reports resolved ones:
+- If any drift warning that was present in the snapshot is absent from `$TITAN_ARCH_DIR/current-drift.json` → note as positive: "Symbol `<name>` community drift resolved — architecture improved"
 
 ### Cleanup (MUST run even on failure or early exit)
 

From 5707a1f496b4a288aa4d8576b91a144225309f9b Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 02:55:28 -0600
Subject: [PATCH 35/52] fix: add RUN to communities/structure rows and snapshot
 list entry in command table (#557)

titan-run Step 3.5a directly calls codegraph communities, structure,
and snapshot list. The README command table was missing these entries.
---
 docs/examples/claude-code-skills/README.md | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/docs/examples/claude-code-skills/README.md b/docs/examples/claude-code-skills/README.md
index d4009c5e..f7a492ff 100644
--- a/docs/examples/claude-code-skills/README.md
+++ b/docs/examples/claude-code-skills/README.md
@@ -184,9 +184,9 @@ All skills enforce worktree isolation as their first step. If invoked from the m
 | `codegraph stats` | RECON | Baseline metrics |
 | `codegraph triage` | RECON, GAUNTLET (fallback) | Ranked priority queue |
 | `codegraph map` | RECON | High-traffic files |
-| `codegraph communities` | RECON, GATE | Module boundaries and drift |
+| `codegraph communities` | RECON, RUN, GATE | Module boundaries and drift |
 | `codegraph roles` | RECON, GAUNTLET | Core/dead/entry symbol classification |
-| `codegraph structure` | RECON, GATE | Directory cohesion |
+| `codegraph structure` | RECON, RUN, GATE | Directory cohesion |
 | `codegraph complexity --health` | RECON, GAUNTLET, GATE, FORGE | Full metrics: cognitive, cyclomatic, nesting, Halstead, MI |
 | `codegraph complexity --above-threshold` | RECON | Only functions exceeding thresholds |
 | `codegraph batch complexity` | GAUNTLET | Multi-target complexity in one call |
@@ -206,6 +206,7 @@ All skills enforce worktree isolation as their first step. If invoked from the m
 | `codegraph branch-compare` | SYNC, GATE | Structural diff between refs |
 | `codegraph diff-impact` | GATE | Impact of staged changes |
 | `codegraph snapshot save\|restore\|delete` | RECON, GAUNTLET, GATE, RESET | Graph database backup/restore |
+| `codegraph snapshot list` | RUN | Verify titan-baseline snapshot exists before forge |
 
 ## Further Reading
 

From 054030e3800d8e2b0b5dc756eb46310261554146 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 03:27:36 -0600
Subject: [PATCH 36/52] fix(skill): distinguish semantic vs test/lint gate
 failures in forge rollback (#557)

---
 .claude/skills/titan-forge/SKILL.md                   | 4 +++-
 docs/examples/claude-code-skills/titan-forge/SKILL.md | 4 +++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/titan-forge/SKILL.md b/.claude/skills/titan-forge/SKILL.md
index fdfd319e..0f56583a 100644
--- a/.claude/skills/titan-forge/SKILL.md
+++ b/.claude/skills/titan-forge/SKILL.md
@@ -201,7 +201,9 @@ For each target in the current phase:
     If tests fail → go to rollback (step 13).
 
 11. **Run /titan-gate:**
-    Use the Skill tool to invoke `titan-gate`. If FAIL → go to rollback (step 13).
+    Use the Skill tool to invoke `titan-gate`.
+    - If FAIL on **test/lint/build** (gate auto-rolls back staged changes) → go to rollback (step 13) to also revert working tree.
+    - If FAIL on **semantic/structural** (gate preserves staged changes per its no-rollback rule) → unstage with `git reset HEAD <files> && git checkout -- <files>`, add to `execution.failedTargets` with reason, log the gate report, and continue to the next target. Do NOT go to step 13 — gate left staged changes intact for potential in-place fixing, and step 13 would silently destroy them.
 
 12. **On success:**
     ```bash
diff --git a/docs/examples/claude-code-skills/titan-forge/SKILL.md b/docs/examples/claude-code-skills/titan-forge/SKILL.md
index fdfd319e..0f56583a 100644
--- a/docs/examples/claude-code-skills/titan-forge/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-forge/SKILL.md
@@ -201,7 +201,9 @@ For each target in the current phase:
     If tests fail → go to rollback (step 13).
 
 11. **Run /titan-gate:**
-    Use the Skill tool to invoke `titan-gate`. If FAIL → go to rollback (step 13).
+    Use the Skill tool to invoke `titan-gate`.
+    - If FAIL on **test/lint/build** (gate auto-rolls back staged changes) → go to rollback (step 13) to also revert working tree.
+    - If FAIL on **semantic/structural** (gate preserves staged changes per its no-rollback rule) → unstage with `git reset HEAD <files> && git checkout -- <files>`, add to `execution.failedTargets` with reason, log the gate report, and continue to the next target. Do NOT go to step 13 — gate left staged changes intact for potential in-place fixing, and step 13 would silently destroy them.
 
 12. **On success:**
     ```bash

From 112c0627478d439fb4a0540a3d92f10555302955 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 03:27:57 -0600
Subject: [PATCH 37/52] fix(skill): add V3 to pre-validation, fix
 efficiency/stall overlap (#557)

---
 .claude/skills/titan-run/SKILL.md                   | 5 +++--
 docs/examples/claude-code-skills/titan-run/SKILL.md | 5 +++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/.claude/skills/titan-run/SKILL.md b/.claude/skills/titan-run/SKILL.md
index 5789a6c4..6c4a0d1d 100644
--- a/.claude/skills/titan-run/SKILL.md
+++ b/.claude/skills/titan-run/SKILL.md
@@ -103,7 +103,7 @@ For each phase BEFORE `startPhase`, run the corresponding V-checks:
 
 | Skipped phase | Required artifacts + checks |
 |---------------|-----------------------------|
-| `recon` | V1 (titan-state.json structure), V2 (GLOBAL_ARCH.md), V4 (cross-check counts) |
+| `recon` | V1 (titan-state.json structure), V2 (GLOBAL_ARCH.md), V3 (snapshot exists — WARN if missing), V4 (cross-check counts) |
 | `gauntlet` | V5 (coverage ≥ 50%), V6 (entry completeness sample), V7 (summary consistency); also run NDJSON integrity check (2c) |
 | `sync` | V8 (sync.json structure), V9 (targets trace to gauntlet), V10 (dependency order) |
 
@@ -230,8 +230,9 @@ while iteration < maxIterations:
     previousAuditedCount = currentAuditedCount
 
     # Efficiency check: if progress is very slow (< 2 targets per iteration), warn
+    # Only fire when stallCount == 0 — if stalled, the stall warning already covers it
     targetsThisIteration = currentAuditedCount - countBeforeUpdate
-    if targetsThisIteration == 1 and iteration > 3:
+    if targetsThisIteration == 1 and iteration > 3 and stallCount == 0:
         Print: "WARNING: Only 1 target per iteration — agent may be spending too much context. Consider increasing batch size."
 
     Print: "Gauntlet iteration <iteration>: <currentAuditedCount>/<expectedTargetCount> targets audited"
diff --git a/docs/examples/claude-code-skills/titan-run/SKILL.md b/docs/examples/claude-code-skills/titan-run/SKILL.md
index 5789a6c4..6c4a0d1d 100644
--- a/docs/examples/claude-code-skills/titan-run/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-run/SKILL.md
@@ -103,7 +103,7 @@ For each phase BEFORE `startPhase`, run the corresponding V-checks:
 
 | Skipped phase | Required artifacts + checks |
 |---------------|-----------------------------|
-| `recon` | V1 (titan-state.json structure), V2 (GLOBAL_ARCH.md), V4 (cross-check counts) |
+| `recon` | V1 (titan-state.json structure), V2 (GLOBAL_ARCH.md), V3 (snapshot exists — WARN if missing), V4 (cross-check counts) |
 | `gauntlet` | V5 (coverage ≥ 50%), V6 (entry completeness sample), V7 (summary consistency); also run NDJSON integrity check (2c) |
 | `sync` | V8 (sync.json structure), V9 (targets trace to gauntlet), V10 (dependency order) |
 
@@ -230,8 +230,9 @@ while iteration < maxIterations:
     previousAuditedCount = currentAuditedCount
 
     # Efficiency check: if progress is very slow (< 2 targets per iteration), warn
+    # Only fire when stallCount == 0 — if stalled, the stall warning already covers it
     targetsThisIteration = currentAuditedCount - countBeforeUpdate
-    if targetsThisIteration == 1 and iteration > 3:
+    if targetsThisIteration == 1 and iteration > 3 and stallCount == 0:
         Print: "WARNING: Only 1 target per iteration — agent may be spending too much context. Consider increasing batch size."
 
     Print: "Gauntlet iteration <iteration>: <currentAuditedCount>/<expectedTargetCount> targets audited"

From 57ea4d7c67088fb2c3bce2e9cf9e2de5a4790f30 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 03:28:07 -0600
Subject: [PATCH 38/52] fix(skill): add FAIL message template to Step 5d barrel
 export check (#557)

---
 .claude/skills/titan-gate/SKILL.md                   | 2 +-
 docs/examples/claude-code-skills/titan-gate/SKILL.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/titan-gate/SKILL.md b/.claude/skills/titan-gate/SKILL.md
index b226f08c..cd572f37 100644
--- a/.claude/skills/titan-gate/SKILL.md
+++ b/.claude/skills/titan-gate/SKILL.md
@@ -166,7 +166,7 @@ Then capture the current (staged) export list:
 codegraph exports <barrel-file> -T --json
 ```
 
-Compare export count before and after. If exports were **accidentally dropped** (count decreased and the removed exports have callers) → **FAIL**.
+Compare export count before and after. If exports were **accidentally dropped** (count decreased and the removed exports have callers) → **FAIL**: "Barrel file `<barrel-file>` dropped <N> exports that have active callers: <export list>. Use `codegraph exports <barrel-file> -T` to review."
 
 Clean up the temp file (recover path from sidecar):
 ```bash
diff --git a/docs/examples/claude-code-skills/titan-gate/SKILL.md b/docs/examples/claude-code-skills/titan-gate/SKILL.md
index b226f08c..cd572f37 100644
--- a/docs/examples/claude-code-skills/titan-gate/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-gate/SKILL.md
@@ -166,7 +166,7 @@ Then capture the current (staged) export list:
 codegraph exports <barrel-file> -T --json
 ```
 
-Compare export count before and after. If exports were **accidentally dropped** (count decreased and the removed exports have callers) → **FAIL**.
+Compare export count before and after. If exports were **accidentally dropped** (count decreased and the removed exports have callers) → **FAIL**: "Barrel file `<barrel-file>` dropped <N> exports that have active callers: <export list>. Use `codegraph exports <barrel-file> -T` to review."
 
 Clean up the temp file (recover path from sidecar):
 ```bash

From f3d637a214b7b1b9a62e833978a3441f02bdb34d Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 04:09:51 -0600
Subject: [PATCH 39/52] fix(titan-run): track per-target progress in forge
 stall detection (#557)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Forge stall detection only compared completed phases, causing false
aborts when a multi-target phase required several sub-agent iterations.
Now also tracks completedTargets count — stallCount only increments
when neither phases nor targets advance.
---
 .claude/skills/titan-run/SKILL.md                   | 8 ++++++--
 docs/examples/claude-code-skills/titan-run/SKILL.md | 8 ++++++--
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/.claude/skills/titan-run/SKILL.md b/.claude/skills/titan-run/SKILL.md
index 6c4a0d1d..e5e7d173 100644
--- a/.claude/skills/titan-run/SKILL.md
+++ b/.claude/skills/titan-run/SKILL.md
@@ -419,6 +419,7 @@ Set `stallCount = 0`, `maxStalls = 2` (forge stalls are more serious — fewer r
 
 ```
 previousCompletedPhases = execution.completedPhases (or [])
+previousCompletedTargets = execution.completedTargets (or [])
 iteration = 0
 
 while iteration < maxIterations:
@@ -466,14 +467,17 @@ while iteration < maxIterations:
     newCompletedTargets = execution.completedTargets (or [])
     newFailedTargets = execution.failedTargets (or [])
 
-    if newCompletedPhases == previousCompletedPhases:
+    if newCompletedPhases == previousCompletedPhases and len(newCompletedTargets) == len(previousCompletedTargets):
         stallCount += 1
-        Print: "WARNING: Forge iteration <iteration> did not complete phase <nextPhase> (stall <stallCount>/<maxStalls>)"
+        Print: "WARNING: Forge iteration <iteration> made no progress (stall <stallCount>/<maxStalls>)"
         if stallCount >= maxStalls:
             Stop: "Forge stalled on phase <nextPhase> for <maxStalls> consecutive iterations. Check titan-state.json → execution.failedTargets for details."
     else:
         stallCount = 0
 
+    previousCompletedPhases = newCompletedPhases
+    previousCompletedTargets = newCompletedTargets
+
     # V12. Commit audit — verify commits match expectations
     if headAfter != headBefore:
         # Get commits made by this agent
diff --git a/docs/examples/claude-code-skills/titan-run/SKILL.md b/docs/examples/claude-code-skills/titan-run/SKILL.md
index 6c4a0d1d..e5e7d173 100644
--- a/docs/examples/claude-code-skills/titan-run/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-run/SKILL.md
@@ -419,6 +419,7 @@ Set `stallCount = 0`, `maxStalls = 2` (forge stalls are more serious — fewer r
 
 ```
 previousCompletedPhases = execution.completedPhases (or [])
+previousCompletedTargets = execution.completedTargets (or [])
 iteration = 0
 
 while iteration < maxIterations:
@@ -466,14 +467,17 @@ while iteration < maxIterations:
     newCompletedTargets = execution.completedTargets (or [])
     newFailedTargets = execution.failedTargets (or [])
 
-    if newCompletedPhases == previousCompletedPhases:
+    if newCompletedPhases == previousCompletedPhases and len(newCompletedTargets) == len(previousCompletedTargets):
         stallCount += 1
-        Print: "WARNING: Forge iteration <iteration> did not complete phase <nextPhase> (stall <stallCount>/<maxStalls>)"
+        Print: "WARNING: Forge iteration <iteration> made no progress (stall <stallCount>/<maxStalls>)"
         if stallCount >= maxStalls:
             Stop: "Forge stalled on phase <nextPhase> for <maxStalls> consecutive iterations. Check titan-state.json → execution.failedTargets for details."
     else:
         stallCount = 0
 
+    previousCompletedPhases = newCompletedPhases
+    previousCompletedTargets = newCompletedTargets
+
     # V12. Commit audit — verify commits match expectations
     if headAfter != headBefore:
         # Get commits made by this agent

From 30328fab0f82227901e15d25952314f796815a6b Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 04:56:44 -0600
Subject: [PATCH 40/52] fix: remove duplicate previousCompletedPhases
 assignment in titan-run (#557)

---
 .claude/skills/titan-run/SKILL.md                   | 2 --
 docs/examples/claude-code-skills/titan-run/SKILL.md | 2 --
 2 files changed, 4 deletions(-)

diff --git a/.claude/skills/titan-run/SKILL.md b/.claude/skills/titan-run/SKILL.md
index e5e7d173..09aae8e5 100644
--- a/.claude/skills/titan-run/SKILL.md
+++ b/.claude/skills/titan-run/SKILL.md
@@ -497,8 +497,6 @@ while iteration < maxIterations:
         Print: "Commits from this phase: git log --oneline <headBefore>..<headAfter>"
         Print: "Consider reverting: git revert <headBefore>..<headAfter>"
         Stop.
-
-    previousCompletedPhases = newCompletedPhases
 ```
 
 ### 4c. Post-loop validation
diff --git a/docs/examples/claude-code-skills/titan-run/SKILL.md b/docs/examples/claude-code-skills/titan-run/SKILL.md
index e5e7d173..09aae8e5 100644
--- a/docs/examples/claude-code-skills/titan-run/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-run/SKILL.md
@@ -497,8 +497,6 @@ while iteration < maxIterations:
         Print: "Commits from this phase: git log --oneline <headBefore>..<headAfter>"
         Print: "Consider reverting: git revert <headBefore>..<headAfter>"
         Stop.
-
-    previousCompletedPhases = newCompletedPhases
 ```
 
 ### 4c. Post-loop validation

From e2a1828573cda2fe5e0df7d358f257658e1e04c2 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 04:56:54 -0600
Subject: [PATCH 41/52] fix: scope A2 domain check to new edges only in
 titan-gate (#557)

---
 .claude/skills/titan-gate/SKILL.md                   | 5 +++--
 docs/examples/claude-code-skills/titan-gate/SKILL.md | 5 +++--
 2 files changed, 6 insertions(+), 4 deletions(-)

diff --git a/.claude/skills/titan-gate/SKILL.md b/.claude/skills/titan-gate/SKILL.md
index cd572f37..070b4b98 100644
--- a/.claude/skills/titan-gate/SKILL.md
+++ b/.claude/skills/titan-gate/SKILL.md
@@ -216,10 +216,11 @@ Read `.codegraph/titan/arch-snapshot.json → drift` (the pre-forge drift baseli
 **A2. Dependency direction between domains:**
 From `GLOBAL_ARCH.md`, extract the expected dependency direction between domains (e.g., "presentation depends on features, not the reverse").
 
-Check if any new cross-domain dependency violates the expected direction. "New" means the edge appears in the Step 1 diff-impact results (i.e., it was introduced by the staged changes):
+Check if any new cross-domain dependency violates the expected direction. Use the Step 1 diff-impact results to extract only the edges introduced by the staged changes — do not re-run `codegraph deps` on the full file (that returns all dependencies including pre-existing ones). For each new edge in the diff-impact output, resolve the domain/layer of the source and target endpoints:
 ```bash
-codegraph deps <changed-file> --json
+codegraph deps <endpoint-symbol> --json
 ```
+(Only call this to look up which domain/layer an individual edge endpoint belongs to — not to enumerate all dependencies.)
 - New upward dependency (lower layer importing higher layer) introduced in this diff → **FAIL**
 - Pre-existing boundary violations not surfaced by Step 5c's staged-diff results → advisory-only (not gating)
 - New lateral dependency within the same layer → **OK**
diff --git a/docs/examples/claude-code-skills/titan-gate/SKILL.md b/docs/examples/claude-code-skills/titan-gate/SKILL.md
index cd572f37..070b4b98 100644
--- a/docs/examples/claude-code-skills/titan-gate/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-gate/SKILL.md
@@ -216,10 +216,11 @@ Read `.codegraph/titan/arch-snapshot.json → drift` (the pre-forge drift baseli
 **A2. Dependency direction between domains:**
 From `GLOBAL_ARCH.md`, extract the expected dependency direction between domains (e.g., "presentation depends on features, not the reverse").
 
-Check if any new cross-domain dependency violates the expected direction. "New" means the edge appears in the Step 1 diff-impact results (i.e., it was introduced by the staged changes):
+Check if any new cross-domain dependency violates the expected direction. Use the Step 1 diff-impact results to extract only the edges introduced by the staged changes — do not re-run `codegraph deps` on the full file (that returns all dependencies including pre-existing ones). For each new edge in the diff-impact output, resolve the domain/layer of the source and target endpoints:
 ```bash
-codegraph deps <changed-file> --json
+codegraph deps <endpoint-symbol> --json
 ```
+(Only call this to look up which domain/layer an individual edge endpoint belongs to — not to enumerate all dependencies.)
 - New upward dependency (lower layer importing higher layer) introduced in this diff → **FAIL**
 - Pre-existing boundary violations not surfaced by Step 5c's staged-diff results → advisory-only (not gating)
 - New lateral dependency within the same layer → **OK**

From eb2801808954a7f79c16b38a57c80c3bddef5ba1 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 05:18:39 -0600
Subject: [PATCH 42/52] fix: guarantee Step 5d barrel cleanup runs on FAIL
 verdict (#557)

---
 .claude/skills/titan-gate/SKILL.md                   | 2 +-
 docs/examples/claude-code-skills/titan-gate/SKILL.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/titan-gate/SKILL.md b/.claude/skills/titan-gate/SKILL.md
index 070b4b98..cc3fb503 100644
--- a/.claude/skills/titan-gate/SKILL.md
+++ b/.claude/skills/titan-gate/SKILL.md
@@ -168,7 +168,7 @@ codegraph exports <barrel-file> -T --json
 
 Compare export count before and after. If exports were **accidentally dropped** (count decreased and the removed exports have callers) → **FAIL**: "Barrel file `<barrel-file>` dropped <N> exports that have active callers: <export list>. Use `codegraph exports <barrel-file> -T` to review."
 
-Clean up the temp file (recover path from sidecar):
+Clean up the temp file (recover path from sidecar). **This MUST run even if Step 5d produced a FAIL verdict — run it before proceeding to Step 9:**
 ```bash
 BARREL_TMP=$(cat .codegraph/titan/.barrel-tmp 2>/dev/null)
 if [ -n "$BARREL_TMP" ]; then rm -f "$BARREL_TMP"; fi
diff --git a/docs/examples/claude-code-skills/titan-gate/SKILL.md b/docs/examples/claude-code-skills/titan-gate/SKILL.md
index 070b4b98..cc3fb503 100644
--- a/docs/examples/claude-code-skills/titan-gate/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-gate/SKILL.md
@@ -168,7 +168,7 @@ codegraph exports <barrel-file> -T --json
 
 Compare export count before and after. If exports were **accidentally dropped** (count decreased and the removed exports have callers) → **FAIL**: "Barrel file `<barrel-file>` dropped <N> exports that have active callers: <export list>. Use `codegraph exports <barrel-file> -T` to review."
 
-Clean up the temp file (recover path from sidecar):
+Clean up the temp file (recover path from sidecar). **This MUST run even if Step 5d produced a FAIL verdict — run it before proceeding to Step 9:**
 ```bash
 BARREL_TMP=$(cat .codegraph/titan/.barrel-tmp 2>/dev/null)
 if [ -n "$BARREL_TMP" ]; then rm -f "$BARREL_TMP"; fi

From b308512e605c3ed04c972d25d3eec804517c42eb Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 05:48:08 -0600
Subject: [PATCH 43/52] fix(titan-gate): use Step 1 --staged results for
 boundary check (#557)

Step 5c referenced codegraph check --boundaries without --staged,
causing false positives from pre-existing violations. Now references
the already-collected Step 1 results instead.
---
 .claude/skills/titan-gate/SKILL.md                   | 2 +-
 docs/examples/claude-code-skills/titan-gate/SKILL.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/titan-gate/SKILL.md b/.claude/skills/titan-gate/SKILL.md
index cc3fb503..5a1f595d 100644
--- a/.claude/skills/titan-gate/SKILL.md
+++ b/.claude/skills/titan-gate/SKILL.md
@@ -145,7 +145,7 @@ From the diff-impact results already collected in Step 1, extract any **new** ed
 
 For each new dependency:
 - Check against `GLOBAL_ARCH.md` layer rules (if Titan artifacts exist)
-- Check against `codegraph check --boundaries -T --json`
+- Check the Step 1 `codegraph check --staged --boundaries` results for violations on this edge (already collected — do not re-run)
 - New dependency from a lower layer to a higher layer → **FAIL**: "New upward dependency: `<source>` → `<target>` violates layer boundary"
 - New dependency on a module flagged in sync.json as "to be removed" or "to be split" → **WARN**: "New dependency on `<module>` which is scheduled for decomposition"
 
diff --git a/docs/examples/claude-code-skills/titan-gate/SKILL.md b/docs/examples/claude-code-skills/titan-gate/SKILL.md
index cc3fb503..5a1f595d 100644
--- a/docs/examples/claude-code-skills/titan-gate/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-gate/SKILL.md
@@ -145,7 +145,7 @@ From the diff-impact results already collected in Step 1, extract any **new** ed
 
 For each new dependency:
 - Check against `GLOBAL_ARCH.md` layer rules (if Titan artifacts exist)
-- Check against `codegraph check --boundaries -T --json`
+- Check the Step 1 `codegraph check --staged --boundaries` results for violations on this edge (already collected — do not re-run)
 - New dependency from a lower layer to a higher layer → **FAIL**: "New upward dependency: `<source>` → `<target>` violates layer boundary"
 - New dependency on a module flagged in sync.json as "to be removed" or "to be split" → **WARN**: "New dependency on `<module>` which is scheduled for decomposition"
 

From 862863df53e09a0281698c6355579417646d047a Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 05:48:31 -0600
Subject: [PATCH 44/52] fix(titan-forge): clarify rollback, document --yes,
 init diffWarnings (#557)

- Step 11 semantic FAIL: clarify forge does its own rollback (not gate)
- Re-add --yes to argument list as documented passthrough
- Add diffWarnings: [] to execution state init block
- Document pre-gate test as fast-fail optimization with tradeoff note
---
 .claude/skills/titan-forge/SKILL.md                   | 8 ++++++--
 docs/examples/claude-code-skills/titan-forge/SKILL.md | 8 ++++++--
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/.claude/skills/titan-forge/SKILL.md b/.claude/skills/titan-forge/SKILL.md
index 0f56583a..60276255 100644
--- a/.claude/skills/titan-forge/SKILL.md
+++ b/.claude/skills/titan-forge/SKILL.md
@@ -18,6 +18,7 @@ Your goal: read `sync.json`, find the next incomplete execution phase, make the
 - `--phase N` → jump to specific phase
 - `--target <name>` → run single target only (for retrying failures)
 - `--dry-run` → show what would be done without changing code
+- `--yes` → skip confirmation prompt (typically passed by `/titan-run` orchestrator)
 
 ---
 
@@ -54,7 +55,8 @@ Your goal: read `sync.json`, find the next incomplete execution phase, make the
        "failedTargets": [],
        "commits": [],
        "currentSubphase": null,
-       "completedSubphases": []
+       "completedSubphases": [],
+       "diffWarnings": []
      }
    }
    ```
@@ -200,10 +202,12 @@ For each target in the current phase:
     ```
     If tests fail → go to rollback (step 13).
 
+    > **Note:** Gate (Step 11) also runs tests. This pre-gate test is a fast-fail optimization — it catches obvious breakage before running the full gate checks (codegraph analysis, semantic assertions, arch snapshot). For projects with fast test suites the duplication is negligible; for slow suites, the tradeoff is: catch failures ~2x faster at the cost of ~2x test time on passing targets.
+
 11. **Run /titan-gate:**
     Use the Skill tool to invoke `titan-gate`.
     - If FAIL on **test/lint/build** (gate auto-rolls back staged changes) → go to rollback (step 13) to also revert working tree.
-    - If FAIL on **semantic/structural** (gate preserves staged changes per its no-rollback rule) → unstage with `git reset HEAD <files> && git checkout -- <files>`, add to `execution.failedTargets` with reason, log the gate report, and continue to the next target. Do NOT go to step 13 — gate left staged changes intact for potential in-place fixing, and step 13 would silently destroy them.
+    - If FAIL on **semantic/structural** (gate does not auto-rollback its staging area, but forge must clean up for the next target) → unstage with `git reset HEAD <files> && git checkout -- <files>`, add to `execution.failedTargets` with reason, log the gate report, and continue to the next target. Do NOT go to step 13 — that step is for test/gate failures where gate already unstaged; going there again would attempt a duplicate rollback.
 
 12. **On success:**
     ```bash
diff --git a/docs/examples/claude-code-skills/titan-forge/SKILL.md b/docs/examples/claude-code-skills/titan-forge/SKILL.md
index 0f56583a..60276255 100644
--- a/docs/examples/claude-code-skills/titan-forge/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-forge/SKILL.md
@@ -18,6 +18,7 @@ Your goal: read `sync.json`, find the next incomplete execution phase, make the
 - `--phase N` → jump to specific phase
 - `--target <name>` → run single target only (for retrying failures)
 - `--dry-run` → show what would be done without changing code
+- `--yes` → skip confirmation prompt (typically passed by `/titan-run` orchestrator)
 
 ---
 
@@ -54,7 +55,8 @@ Your goal: read `sync.json`, find the next incomplete execution phase, make the
        "failedTargets": [],
        "commits": [],
        "currentSubphase": null,
-       "completedSubphases": []
+       "completedSubphases": [],
+       "diffWarnings": []
      }
    }
    ```
@@ -200,10 +202,12 @@ For each target in the current phase:
     ```
     If tests fail → go to rollback (step 13).
 
+    > **Note:** Gate (Step 11) also runs tests. This pre-gate test is a fast-fail optimization — it catches obvious breakage before running the full gate checks (codegraph analysis, semantic assertions, arch snapshot). For projects with fast test suites the duplication is negligible; for slow suites, the tradeoff is: catch failures ~2x faster at the cost of ~2x test time on passing targets.
+
 11. **Run /titan-gate:**
     Use the Skill tool to invoke `titan-gate`.
     - If FAIL on **test/lint/build** (gate auto-rolls back staged changes) → go to rollback (step 13) to also revert working tree.
-    - If FAIL on **semantic/structural** (gate preserves staged changes per its no-rollback rule) → unstage with `git reset HEAD <files> && git checkout -- <files>`, add to `execution.failedTargets` with reason, log the gate report, and continue to the next target. Do NOT go to step 13 — gate left staged changes intact for potential in-place fixing, and step 13 would silently destroy them.
+    - If FAIL on **semantic/structural** (gate does not auto-rollback its staging area, but forge must clean up for the next target) → unstage with `git reset HEAD <files> && git checkout -- <files>`, add to `execution.failedTargets` with reason, log the gate report, and continue to the next target. Do NOT go to step 13 — that step is for test/gate failures where gate already unstaged; going there again would attempt a duplicate rollback.
 
 12. **On success:**
     ```bash

From 382fbf6cba66371e5556e734af3bef1bb279e1cc Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 14:30:15 -0600
Subject: [PATCH 45/52] fix(titan-gate): replace codegraph deps with path-based
 layer inference in A2

codegraph deps is a file-level dependency map, not a symbol lookup.
The diff-impact edge output already contains source/target file paths,
so the domain/layer can be inferred directly from the path using the
GLOBAL_ARCH.md domain map without an extra command.
---
 .claude/skills/titan-gate/SKILL.md                   | 6 +-----
 docs/examples/claude-code-skills/titan-gate/SKILL.md | 6 +-----
 2 files changed, 2 insertions(+), 10 deletions(-)

diff --git a/.claude/skills/titan-gate/SKILL.md b/.claude/skills/titan-gate/SKILL.md
index 5a1f595d..7ba8b092 100644
--- a/.claude/skills/titan-gate/SKILL.md
+++ b/.claude/skills/titan-gate/SKILL.md
@@ -216,11 +216,7 @@ Read `.codegraph/titan/arch-snapshot.json → drift` (the pre-forge drift baseli
 **A2. Dependency direction between domains:**
 From `GLOBAL_ARCH.md`, extract the expected dependency direction between domains (e.g., "presentation depends on features, not the reverse").
 
-Check if any new cross-domain dependency violates the expected direction. Use the Step 1 diff-impact results to extract only the edges introduced by the staged changes — do not re-run `codegraph deps` on the full file (that returns all dependencies including pre-existing ones). For each new edge in the diff-impact output, resolve the domain/layer of the source and target endpoints:
-```bash
-codegraph deps <endpoint-symbol> --json
-```
-(Only call this to look up which domain/layer an individual edge endpoint belongs to — not to enumerate all dependencies.)
+Check if any new cross-domain dependency violates the expected direction. Use the Step 1 diff-impact results to extract only the edges introduced by the staged changes — do not re-run `codegraph deps` on the full file (that returns all dependencies including pre-existing ones). For each new edge in the diff-impact output, the source and target file paths are already present in the edge data. Resolve the domain/layer of each endpoint by matching its file path against the domain map in `GLOBAL_ARCH.md` (e.g., `src/presentation/` → presentation layer, `src/features/` → features layer). No additional codegraph command is needed — the diff-impact edge output contains the file paths directly.
 - New upward dependency (lower layer importing higher layer) introduced in this diff → **FAIL**
 - Pre-existing boundary violations not surfaced by Step 5c's staged-diff results → advisory-only (not gating)
 - New lateral dependency within the same layer → **OK**
diff --git a/docs/examples/claude-code-skills/titan-gate/SKILL.md b/docs/examples/claude-code-skills/titan-gate/SKILL.md
index 5a1f595d..7ba8b092 100644
--- a/docs/examples/claude-code-skills/titan-gate/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-gate/SKILL.md
@@ -216,11 +216,7 @@ Read `.codegraph/titan/arch-snapshot.json → drift` (the pre-forge drift baseli
 **A2. Dependency direction between domains:**
 From `GLOBAL_ARCH.md`, extract the expected dependency direction between domains (e.g., "presentation depends on features, not the reverse").
 
-Check if any new cross-domain dependency violates the expected direction. Use the Step 1 diff-impact results to extract only the edges introduced by the staged changes — do not re-run `codegraph deps` on the full file (that returns all dependencies including pre-existing ones). For each new edge in the diff-impact output, resolve the domain/layer of the source and target endpoints:
-```bash
-codegraph deps <endpoint-symbol> --json
-```
-(Only call this to look up which domain/layer an individual edge endpoint belongs to — not to enumerate all dependencies.)
+Check if any new cross-domain dependency violates the expected direction. Use the Step 1 diff-impact results to extract only the edges introduced by the staged changes — do not re-run `codegraph deps` on the full file (that returns all dependencies including pre-existing ones). For each new edge in the diff-impact output, the source and target file paths are already present in the edge data. Resolve the domain/layer of each endpoint by matching its file path against the domain map in `GLOBAL_ARCH.md` (e.g., `src/presentation/` → presentation layer, `src/features/` → features layer). No additional codegraph command is needed — the diff-impact edge output contains the file paths directly.
 - New upward dependency (lower layer importing higher layer) introduced in this diff → **FAIL**
 - Pre-existing boundary violations not surfaced by Step 5c's staged-diff results → advisory-only (not gating)
 - New lateral dependency within the same layer → **OK**

From 7f4525260ec5099841015f47b476e26e75d65372 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 14:30:44 -0600
Subject: [PATCH 46/52] fix(titan-forge): handle dead-code targets in D2
 intent-match check

Dead-code targets have no gauntlet.ndjson entry, causing D2 to fail
silently. Now checks titan-state.json deadSymbols first and validates
the diff shows only deletions without needing a gauntlet lookup.
---
 .claude/skills/titan-forge/SKILL.md                   | 4 +++-
 docs/examples/claude-code-skills/titan-forge/SKILL.md | 4 +++-
 2 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/titan-forge/SKILL.md b/.claude/skills/titan-forge/SKILL.md
index 60276255..426517d9 100644
--- a/.claude/skills/titan-forge/SKILL.md
+++ b/.claude/skills/titan-forge/SKILL.md
@@ -161,7 +161,9 @@ For each target in the current phase:
    - Test file for the target → **OK**
 
    **D2. Intent match — diff aligns with gauntlet recommendation:**
-   Read the gauntlet entry's `recommendation` field and `violations` list. Verify the diff addresses them:
+   First, check if this target is a dead-code target (present in `titan-state.json → roles.deadSymbols`). If so, the expected recommendation is "remove dead code" — skip gauntlet entry lookup (dead-code targets have no gauntlet.ndjson entry) and verify the diff shows only deletions (no new functions or logic added). If the diff contains non-trivial additions for a dead-code target → **DIFF FAIL**.
+
+   Otherwise, read the gauntlet entry's `recommendation` field and `violations` list. Verify the diff addresses them:
    - If recommendation says "split" → diff should show new functions extracted, original simplified
    - If recommendation says "remove dead code" → diff should show deletions, not additions
    - If violation was "complexity > threshold" → diff should reduce complexity, not just move code around
diff --git a/docs/examples/claude-code-skills/titan-forge/SKILL.md b/docs/examples/claude-code-skills/titan-forge/SKILL.md
index 60276255..426517d9 100644
--- a/docs/examples/claude-code-skills/titan-forge/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-forge/SKILL.md
@@ -161,7 +161,9 @@ For each target in the current phase:
    - Test file for the target → **OK**
 
    **D2. Intent match — diff aligns with gauntlet recommendation:**
-   Read the gauntlet entry's `recommendation` field and `violations` list. Verify the diff addresses them:
+   First, check if this target is a dead-code target (present in `titan-state.json → roles.deadSymbols`). If so, the expected recommendation is "remove dead code" — skip gauntlet entry lookup (dead-code targets have no gauntlet.ndjson entry) and verify the diff shows only deletions (no new functions or logic added). If the diff contains non-trivial additions for a dead-code target → **DIFF FAIL**.
+
+   Otherwise, read the gauntlet entry's `recommendation` field and `violations` list. Verify the diff addresses them:
    - If recommendation says "split" → diff should show new functions extracted, original simplified
    - If recommendation says "remove dead code" → diff should show deletions, not additions
    - If violation was "complexity > threshold" → diff should reduce complexity, not just move code around

From f92521d20431be78f5dbb29aabb478d68aa6e089 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 14:31:13 -0600
Subject: [PATCH 47/52] fix(titan-run): add try/catch to arch-snapshot builder
 script
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The node -e script that assembles arch-snapshot.json had no error
handling — if any input file was missing or malformed, it failed
silently and no snapshot was written. Now catches errors, prints a
warning, and continues without the snapshot.
---
 .claude/skills/titan-run/SKILL.md             | 29 +++++++++++--------
 .../claude-code-skills/titan-run/SKILL.md     | 29 +++++++++++--------
 2 files changed, 34 insertions(+), 24 deletions(-)

diff --git a/.claude/skills/titan-run/SKILL.md b/.claude/skills/titan-run/SKILL.md
index 09aae8e5..8eb3905a 100644
--- a/.claude/skills/titan-run/SKILL.md
+++ b/.claude/skills/titan-run/SKILL.md
@@ -344,18 +344,23 @@ Combine into a single snapshot file:
 TITAN_HEAD_SHA=$(git rev-parse HEAD)
 node -e "
 const fs = require('fs');
-const communities = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-communities.json','utf8'));
-const structure = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-structure.json','utf8'));
-const drift = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-drift.json','utf8'));
-const snapshot = {
-  timestamp: new Date().toISOString(),
-  capturedBefore: 'forge',
-  headSha: '$TITAN_HEAD_SHA',
-  communities,
-  structure,
-  drift
-};
-fs.writeFileSync('.codegraph/titan/arch-snapshot.json', JSON.stringify(snapshot, null, 2));
+try {
+  const communities = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-communities.json','utf8'));
+  const structure = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-structure.json','utf8'));
+  const drift = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-drift.json','utf8'));
+  const snapshot = {
+    timestamp: new Date().toISOString(),
+    capturedBefore: 'forge',
+    headSha: '$TITAN_HEAD_SHA',
+    communities,
+    structure,
+    drift
+  };
+  fs.writeFileSync('.codegraph/titan/arch-snapshot.json', JSON.stringify(snapshot, null, 2));
+} catch (e) {
+  console.error('WARNING: Failed to build arch-snapshot.json: ' + e.message);
+  console.error('Architectural comparison (titan-gate A1/A3/A4) will be skipped.');
+}
 "
 ```
 
diff --git a/docs/examples/claude-code-skills/titan-run/SKILL.md b/docs/examples/claude-code-skills/titan-run/SKILL.md
index 09aae8e5..8eb3905a 100644
--- a/docs/examples/claude-code-skills/titan-run/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-run/SKILL.md
@@ -344,18 +344,23 @@ Combine into a single snapshot file:
 TITAN_HEAD_SHA=$(git rev-parse HEAD)
 node -e "
 const fs = require('fs');
-const communities = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-communities.json','utf8'));
-const structure = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-structure.json','utf8'));
-const drift = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-drift.json','utf8'));
-const snapshot = {
-  timestamp: new Date().toISOString(),
-  capturedBefore: 'forge',
-  headSha: '$TITAN_HEAD_SHA',
-  communities,
-  structure,
-  drift
-};
-fs.writeFileSync('.codegraph/titan/arch-snapshot.json', JSON.stringify(snapshot, null, 2));
+try {
+  const communities = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-communities.json','utf8'));
+  const structure = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-structure.json','utf8'));
+  const drift = JSON.parse(fs.readFileSync('.codegraph/titan/arch-snapshot-drift.json','utf8'));
+  const snapshot = {
+    timestamp: new Date().toISOString(),
+    capturedBefore: 'forge',
+    headSha: '$TITAN_HEAD_SHA',
+    communities,
+    structure,
+    drift
+  };
+  fs.writeFileSync('.codegraph/titan/arch-snapshot.json', JSON.stringify(snapshot, null, 2));
+} catch (e) {
+  console.error('WARNING: Failed to build arch-snapshot.json: ' + e.message);
+  console.error('Architectural comparison (titan-gate A1/A3/A4) will be skipped.');
+}
 "
 ```
 

From e6ed6c6f5a286fccdc2d2a1a98b20b44cab9085b Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 14:31:40 -0600
Subject: [PATCH 48/52] fix(titan-run): document explicit G3 state recovery
 procedure

G3 referenced backup recovery without documenting the steps. Now
includes: check backup exists, validate it is valid JSON before
restoring, cp .bak over the corrupt file, and stop if backup is
also corrupt or missing.
---
 .claude/skills/titan-run/SKILL.md                   | 9 ++++++++-
 docs/examples/claude-code-skills/titan-run/SKILL.md | 9 ++++++++-
 2 files changed, 16 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/titan-run/SKILL.md b/.claude/skills/titan-run/SKILL.md
index 8eb3905a..76efdf5d 100644
--- a/.claude/skills/titan-run/SKILL.md
+++ b/.claude/skills/titan-run/SKILL.md
@@ -84,7 +84,14 @@ If `.codegraph/titan/titan-state.json` should exist at this point (i.e., we're p
 ```bash
 node -e "try { JSON.parse(require('fs').readFileSync('.codegraph/titan/titan-state.json','utf8')); console.log('OK'); } catch(e) { console.log('CORRUPT: '+e.message); process.exit(1); }"
 ```
-- If **CORRUPT** → attempt recovery from backup (see State Backup below). If no backup → stop: "State file corrupted with no backup. Run `/titan-reset` and start over."
+- If **CORRUPT** → attempt recovery from backup:
+  1. Check if `.codegraph/titan/titan-state.json.bak` exists.
+  2. If the backup exists, validate it is valid JSON:
+     ```bash
+     node -e "try { JSON.parse(require('fs').readFileSync('.codegraph/titan/titan-state.json.bak','utf8')); console.log('BACKUP OK'); } catch(e) { console.log('BACKUP CORRUPT: '+e.message); process.exit(1); }"
+     ```
+  3. If the backup is valid → restore it: `cp .codegraph/titan/titan-state.json.bak .codegraph/titan/titan-state.json`
+  4. If the backup is also corrupt or missing → stop: "State file corrupted with no valid backup. Run `/titan-reset` and start over."
 
 ### G4. State backup
 Before every sub-agent dispatch, back up the current state file:
diff --git a/docs/examples/claude-code-skills/titan-run/SKILL.md b/docs/examples/claude-code-skills/titan-run/SKILL.md
index 8eb3905a..76efdf5d 100644
--- a/docs/examples/claude-code-skills/titan-run/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-run/SKILL.md
@@ -84,7 +84,14 @@ If `.codegraph/titan/titan-state.json` should exist at this point (i.e., we're p
 ```bash
 node -e "try { JSON.parse(require('fs').readFileSync('.codegraph/titan/titan-state.json','utf8')); console.log('OK'); } catch(e) { console.log('CORRUPT: '+e.message); process.exit(1); }"
 ```
-- If **CORRUPT** → attempt recovery from backup (see State Backup below). If no backup → stop: "State file corrupted with no backup. Run `/titan-reset` and start over."
+- If **CORRUPT** → attempt recovery from backup:
+  1. Check if `.codegraph/titan/titan-state.json.bak` exists.
+  2. If the backup exists, validate it is valid JSON:
+     ```bash
+     node -e "try { JSON.parse(require('fs').readFileSync('.codegraph/titan/titan-state.json.bak','utf8')); console.log('BACKUP OK'); } catch(e) { console.log('BACKUP CORRUPT: '+e.message); process.exit(1); }"
+     ```
+  3. If the backup is valid → restore it: `cp .codegraph/titan/titan-state.json.bak .codegraph/titan/titan-state.json`
+  4. If the backup is also corrupt or missing → stop: "State file corrupted with no valid backup. Run `/titan-reset` and start over."
 
 ### G4. State backup
 Before every sub-agent dispatch, back up the current state file:

From 7760313e90e0241485bf332c84d06ec597bb0798 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 14:32:27 -0600
Subject: [PATCH 49/52] fix(titan-run): guard NDJSON integrity check against
 missing file

The node -e script crashed with ENOENT if gauntlet.ndjson did not
exist yet. Now checks fs.existsSync first and outputs a result with
missing:true so the caller can handle it gracefully.
---
 .claude/skills/titan-run/SKILL.md                   | 12 +++++++++---
 docs/examples/claude-code-skills/titan-run/SKILL.md | 12 +++++++++---
 2 files changed, 18 insertions(+), 6 deletions(-)

diff --git a/.claude/skills/titan-run/SKILL.md b/.claude/skills/titan-run/SKILL.md
index 76efdf5d..d6b1da46 100644
--- a/.claude/skills/titan-run/SKILL.md
+++ b/.claude/skills/titan-run/SKILL.md
@@ -252,17 +252,23 @@ After the loop completes (or on each iteration if you prefer lightweight checks)
 ```bash
 node -e "
 const fs = require('fs');
-const lines = fs.readFileSync('.codegraph/titan/gauntlet.ndjson','utf8').trim().split('\n');
+const path = '.codegraph/titan/gauntlet.ndjson';
+if (!fs.existsSync(path)) {
+  console.log(JSON.stringify({ valid: 0, corrupt: 0, total: 0, missing: true }));
+  process.exit(0);
+}
+const lines = fs.readFileSync(path,'utf8').trim().split('\n');
 let valid = 0, corrupt = 0;
 for (const line of lines) {
   try { JSON.parse(line); valid++; } catch { corrupt++; }
 }
-console.log(JSON.stringify({ valid, corrupt, total: lines.length }));
+console.log(JSON.stringify({ valid, corrupt, total: lines.length, missing: false }));
 "
 ```
 
+- If `missing == true`: treat as equivalent to `valid == 0` — the file does not exist yet (expected on first iteration, error if the loop should have produced entries).
 - If `corrupt > 0`: Print "WARNING: <corrupt> corrupt lines in gauntlet.ndjson (likely from a crashed sub-agent). These targets may need re-auditing."
-- If `valid == 0`: Stop: "gauntlet.ndjson has no valid entries. Something went wrong."
+- If `valid == 0` and `missing == false`: Stop: "gauntlet.ndjson has no valid entries. Something went wrong."
 
 ### 2d. Post-loop validation
 
diff --git a/docs/examples/claude-code-skills/titan-run/SKILL.md b/docs/examples/claude-code-skills/titan-run/SKILL.md
index 76efdf5d..d6b1da46 100644
--- a/docs/examples/claude-code-skills/titan-run/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-run/SKILL.md
@@ -252,17 +252,23 @@ After the loop completes (or on each iteration if you prefer lightweight checks)
 ```bash
 node -e "
 const fs = require('fs');
-const lines = fs.readFileSync('.codegraph/titan/gauntlet.ndjson','utf8').trim().split('\n');
+const path = '.codegraph/titan/gauntlet.ndjson';
+if (!fs.existsSync(path)) {
+  console.log(JSON.stringify({ valid: 0, corrupt: 0, total: 0, missing: true }));
+  process.exit(0);
+}
+const lines = fs.readFileSync(path,'utf8').trim().split('\n');
 let valid = 0, corrupt = 0;
 for (const line of lines) {
   try { JSON.parse(line); valid++; } catch { corrupt++; }
 }
-console.log(JSON.stringify({ valid, corrupt, total: lines.length }));
+console.log(JSON.stringify({ valid, corrupt, total: lines.length, missing: false }));
 "
 ```
 
+- If `missing == true`: treat as equivalent to `valid == 0` — the file does not exist yet (expected on first iteration, error if the loop should have produced entries).
 - If `corrupt > 0`: Print "WARNING: <corrupt> corrupt lines in gauntlet.ndjson (likely from a crashed sub-agent). These targets may need re-auditing."
-- If `valid == 0`: Stop: "gauntlet.ndjson has no valid entries. Something went wrong."
+- If `valid == 0` and `missing == false`: Stop: "gauntlet.ndjson has no valid entries. Something went wrong."
 
 ### 2d. Post-loop validation
 

From 27b76d5e7a1561e9960ff8cfa3dc505f384bf85f Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 18:57:11 -0600
Subject: [PATCH 50/52] fix(docs): remove stale GATE consumer from codegraph
 deps command table
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Gate A2 no longer calls codegraph deps — it uses path-based layer inference
from diff-impact edge output instead. The command table was never updated to
reflect this change.
---
 docs/examples/claude-code-skills/README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/examples/claude-code-skills/README.md b/docs/examples/claude-code-skills/README.md
index f7a492ff..65224f2e 100644
--- a/docs/examples/claude-code-skills/README.md
+++ b/docs/examples/claude-code-skills/README.md
@@ -200,7 +200,7 @@ All skills enforce worktree isolation as their first step. If invoked from the m
 | `codegraph co-change` | GAUNTLET, SYNC | Git history coupling |
 | `codegraph path` | SYNC | Dependency paths between targets |
 | `codegraph cycles` | SYNC, GATE | Circular dependency detection |
-| `codegraph deps` | SYNC, GATE | File-level dependency map |
+| `codegraph deps` | SYNC | File-level dependency map |
 | `codegraph context` | SYNC, FORGE | Full function context |
 | `codegraph owners` | SYNC | CODEOWNERS mapping for cross-team coordination |
 | `codegraph branch-compare` | SYNC, GATE | Structural diff between refs |

From a3dd6675cbcc3482fdef2994967c27ed354ab208 Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 19:21:36 -0600
Subject: [PATCH 51/52] fix(titan-run): make checkpoint snapshot status
 conditional on capture success

---
 .claude/skills/titan-run/SKILL.md                   | 2 +-
 docs/examples/claude-code-skills/titan-run/SKILL.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.claude/skills/titan-run/SKILL.md b/.claude/skills/titan-run/SKILL.md
index d6b1da46..d774857f 100644
--- a/.claude/skills/titan-run/SKILL.md
+++ b/.claude/skills/titan-run/SKILL.md
@@ -404,7 +404,7 @@ Execution plan summary:
 
 Total: <N> phases, <N> targets, <N> estimated commits
 
-Architectural snapshot captured (for post-change comparison).
+Architectural snapshot: <captured | FAILED — gate A1/A3/A4 will be skipped>
 
 Validation layers per commit:
   1. Diff Review — does the change match the gauntlet recommendation and sync plan?
diff --git a/docs/examples/claude-code-skills/titan-run/SKILL.md b/docs/examples/claude-code-skills/titan-run/SKILL.md
index d6b1da46..d774857f 100644
--- a/docs/examples/claude-code-skills/titan-run/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-run/SKILL.md
@@ -404,7 +404,7 @@ Execution plan summary:
 
 Total: <N> phases, <N> targets, <N> estimated commits
 
-Architectural snapshot captured (for post-change comparison).
+Architectural snapshot: <captured | FAILED — gate A1/A3/A4 will be skipped>
 
 Validation layers per commit:
   1. Diff Review — does the change match the gauntlet recommendation and sync plan?

From eace8d5e141d65aee2efedcbc723e6974cc135cb Mon Sep 17 00:00:00 2001
From: carlos-alm <127798846+carlos-alm@users.noreply.github.com>
Date: Mon, 23 Mar 2026 19:21:46 -0600
Subject: [PATCH 52/52] fix(titan-forge): add explicit DIFF FAIL rollback
 commands and diffWarnings schema

---
 .claude/skills/titan-forge/SKILL.md                  | 12 ++++++++++--
 .../examples/claude-code-skills/titan-forge/SKILL.md | 12 ++++++++++--
 2 files changed, 20 insertions(+), 4 deletions(-)

diff --git a/.claude/skills/titan-forge/SKILL.md b/.claude/skills/titan-forge/SKILL.md
index 426517d9..2f6dc220 100644
--- a/.claude/skills/titan-forge/SKILL.md
+++ b/.claude/skills/titan-forge/SKILL.md
@@ -195,7 +195,12 @@ For each target in the current phase:
    - Functions marked for decomposition but original is unchanged → **DIFF WARN**: "Gauntlet recommended decomposing `<symbol>` but original function was not simplified."
    - If all recommended symbols were addressed → **DIFF PASS** (implicit — no warnings emitted)
 
-   **On DIFF FAIL:** Unstage and revert changes, add to `execution.failedTargets` with reason starting with `"diff-review: "`. Continue to next target.
+   **On DIFF FAIL:**
+   ```bash
+   git reset HEAD <changed files>
+   git checkout -- <changed files>
+   ```
+   Add to `execution.failedTargets` with reason starting with `"diff-review: "`. Continue to next target.
    **On DIFF WARN:** Log the warning but proceed to gate. Include the warning in the gate-log entry.
 
 10. **Run tests** (detect the project's test command from package.json scripts — `npm test`, `yarn test`, `pnpm test`, etc.):
@@ -217,7 +222,10 @@ For each target in the current phase:
     ```
     - Record commit SHA in `execution.commits`
     - Add target to `execution.completedTargets`
-    - Record any diff-review warnings in `execution.diffWarnings` (if any)
+    - Record any diff-review warnings in `execution.diffWarnings` (if any). Each entry must follow this schema:
+      ```json
+      { "target": "<target-name>", "check": "D1|D3|D5", "message": "<warning text>", "phase": N }
+      ```
     - Update `titan-state.json`
 
 13. **On failure (test or gate):**
diff --git a/docs/examples/claude-code-skills/titan-forge/SKILL.md b/docs/examples/claude-code-skills/titan-forge/SKILL.md
index 426517d9..2f6dc220 100644
--- a/docs/examples/claude-code-skills/titan-forge/SKILL.md
+++ b/docs/examples/claude-code-skills/titan-forge/SKILL.md
@@ -195,7 +195,12 @@ For each target in the current phase:
    - Functions marked for decomposition but original is unchanged → **DIFF WARN**: "Gauntlet recommended decomposing `<symbol>` but original function was not simplified."
    - If all recommended symbols were addressed → **DIFF PASS** (implicit — no warnings emitted)
 
-   **On DIFF FAIL:** Unstage and revert changes, add to `execution.failedTargets` with reason starting with `"diff-review: "`. Continue to next target.
+   **On DIFF FAIL:**
+   ```bash
+   git reset HEAD <changed files>
+   git checkout -- <changed files>
+   ```
+   Add to `execution.failedTargets` with reason starting with `"diff-review: "`. Continue to next target.
    **On DIFF WARN:** Log the warning but proceed to gate. Include the warning in the gate-log entry.
 
 10. **Run tests** (detect the project's test command from package.json scripts — `npm test`, `yarn test`, `pnpm test`, etc.):
@@ -217,7 +222,10 @@ For each target in the current phase:
     ```
     - Record commit SHA in `execution.commits`
     - Add target to `execution.completedTargets`
-    - Record any diff-review warnings in `execution.diffWarnings` (if any)
+    - Record any diff-review warnings in `execution.diffWarnings` (if any). Each entry must follow this schema:
+      ```json
+      { "target": "<target-name>", "check": "D1|D3|D5", "message": "<warning text>", "phase": N }
+      ```
     - Update `titan-state.json`
 
 13. **On failure (test or gate):**