feat: add highway synthesis proposals

README.md

@@ -65,7 +65,7 @@ claude mcp add -s user -t stdio codebase-intelligence -- npx -y codebase-intelli
 - **Symbol-level analysis** — callers/callees, symbol importance, impact blast radius
 - **BM25 search** — ranked keyword search across files, symbols, and type/shape facts
 - **Process tracing** — detect entry points and execution flows through the call graph
-- **Highways analysis** — find repeated routes that bypass canonical dataflow paths
+- **Highways analysis** — find repeated routes that bypass canonical dataflow paths and synthesize safe proposed highways
 - **Community detection** — Louvain clustering for natural file groupings
 - **Agent adoption** — `init` writes per-agent instruction files + installs a skill so AI agents query CI before grep/read
 - **MCP parity (secondary)** — same analysis and rules gate available as 19 MCP tools, 2 prompts, and 3 resources
@@ -111,7 +111,7 @@ codebase-intelligence <command> <path> [options]
 | `impact` | Symbol-level blast radius |
 | `rename` | Reference discovery for rename planning |
 | `processes` | Entry-point execution flow tracing |
-| `highways` | Repeated route convergence and canonical path opportunities |
+| `highways` | Repeated route convergence, canonical path opportunities, and synthesis proposals |
 | `clusters` | Community-detected file clusters |
 | `check` | Rules-engine gate for CI, including opt-in dead-code and dependency gates |
 | `init` | Set up AI agents to use CI — writes per-agent instruction files (skill opt-in via `--skill`) |

docs/architecture.md

@@ -47,7 +47,7 @@ src/
   duplication/index.ts <- Duplicate family detection + trace evidence
   config/index.ts      <- Config discovery + zod validation
   rules/index.ts       <- Rules engine + registry (check command + MCP check tool)
-  highways/index.ts    <- Repeated route convergence + bypass/cowpath evidence
+  highways/index.ts    <- Repeated route convergence + bypass/cowpath/synthesis evidence
   mcp/index.ts         <- 19 MCP tools for LLM integration
   mcp/hints.ts         <- Operation-keyed next-step hints for MCP tool responses
   impact/index.ts      <- Symbol-level impact analysis + rename planning
@@ -97,7 +97,7 @@ runOperation(operation, codebaseGraph, input, context)
 - **Duplication families**: Parser stores deterministic function-body token streams on symbols. `duplicates` / `find_duplicates` groups symbols into strict, renamed, and near-miss clone families, with optional trace evidence for AI agents before refactors.
 - **Dead-code gates**: `check` can opt into unused-file, unused-type, unused-member, and dependency hygiene rules. These rules use graph metrics plus local TypeScript AST facts and emit confidence/evidence in JSON and SARIF; dependency hygiene is scoped to the nearest package/workspace manifest.
 - **Suppression hygiene**: `check` reports active and stale `ci-ignore-*` / `@expected-unused` suppressions, emits stale suppression findings via `no-stale-suppressions`, and treats `@public` exported type declarations as intentional public API while `@internal` stays checkable.
-- **Highways H1**: `highways` / `analyze_highways` enumerates entry-to-sink call routes, groups repeated routes by sink, detects bypasses and cowpaths around an existing canonical node, and emits route chains, evidence, blast radius, recommendations, and a context pack for agents.
+- **Highways H1/H2**: `highways` / `analyze_highways` enumerates entry-to-sink call routes, groups repeated routes by operation/shape/sink, detects bypasses and cowpaths around an existing canonical node, and with `--propose` synthesizes a read-only proposed highway with name, file, signature, skeleton, reroute plan, cycle safety, evidence, blast radius, recommendations, and a context pack for agents.
 - **Shared graph-load pipeline**: CLI commands and MCP stdio startup both use `src/graph-loader/` for path checks, legacy cache migration, cache reuse, parse/build/analyze, optional persistence, and stderr progress events.
 - **graphology**: In-memory graph with O(1) neighbor lookup. PageRank and betweenness computed via graphology-metrics.
 - **Batch git churn**: Single `git log --all --name-only` call, parsed for all files. Avoids O(n) subprocess spawning.

docs/cli-reference.md

@@ -176,7 +176,7 @@ Find repeated routes that should converge on one canonical operation path.
 codebase-intelligence highways <path> [--operation <verb>] [--shape <name>] [--min-routes <n>] [--propose] [--trace <id>] [--json] [--force]
 ```
 
-**Output:** route opportunities with `bypass` / `cowpath` kind, operation, shape, sink, canonical node, route chains, bypass routes, duplicated callees when present, evidence, blast radius, recommendation, and context pack.
+**Output:** route opportunities with `bypass`, `cowpath`, or `synthesis` kind, operation, shape, sink, canonical/proposed node, route chains, bypass routes, duplicated callees when present, evidence, blast radius, recommendation, context pack, and optional synthesis proposal (`name`, `file`, `signature`, `skeleton`, `reroutePlan`, `cycleSafety`).
 
 ### clusters
 

docs/data-model.md

@@ -194,14 +194,30 @@ HighwaysResult {
 
 HighwayOpportunity {
   id: string                         // hwy-<kind>-<stable hash>
-  kind: "bypass" | "cowpath"
+  kind: "bypass" | "cowpath" | "synthesis"
   operation: string
   shape?: string
   sink: HighwayStep
-  canonicalNode: HighwayStep
+  canonicalNode: HighwayStep         // proposed=true for synthesis findings
   routes: HighwayRoute[]             // all routes reaching the sink
   bypassRoutes: HighwayRoute[]       // routes missing canonicalNode
   duplicatedCallees?: HighwayStep[]  // cowpath overlap with canonical node callees
+  proposal?: {
+    name: string
+    file: string
+    signature: string
+    skeleton: string
+    reroutePlan: Array<{
+      entryPoint: string
+      replaceSteps: string[]
+      call: string
+    }>
+    cycleSafety: {
+      safe: boolean
+      checkedEdges: string[]
+      reason: string
+    }
+  }
   evidence: string[]
   blastRadius: number
   recommendation: string
@@ -230,6 +246,7 @@ HighwayStep {
   id: string
   file: string
   symbol: string
+  proposed?: boolean
 }
 ```
 

docs/mcp-tools.md

@@ -174,7 +174,7 @@ Trace execution flows from entry points through the call graph.
 Detect repeated entry-to-sink routes that should converge on one canonical operation path.
 
 **Input:** `{ operation?: string, shape?: string, minRoutes?: number, propose?: boolean, trace?: string }`
-**Returns:** totalRoutes, totalSinks, totalOpportunities, opportunities[] (id, kind, operation, shape, sink, canonicalNode, routes[], bypassRoutes[], duplicatedCallees?, evidence[], blastRadius, recommendation, contextPack), optional trace
+**Returns:** totalRoutes, totalSinks, totalOpportunities, opportunities[] (id, kind, operation, shape, sink, canonicalNode, routes[], bypassRoutes[], duplicatedCallees?, proposal?, evidence[], blastRadius, recommendation, contextPack), optional trace. With `propose: true`, no-canonical route groups can return `kind: "synthesis"` with proposed name/file/signature/skeleton/reroutePlan/cycleSafety.
 
 **Use when:** Enforcing dataflow discipline, finding ad-hoc routes, or planning canonical shared paths.
 **Not for:** Raw execution flow listing (use get_processes).

llms-full.txt

@@ -51,7 +51,7 @@ src/
   operations/formatters.ts <- Result-object text formatters for CLI commands
   parser/duplication.ts <- Function-body clone token extraction
   duplication/index.ts <- Duplicate family detection + trace evidence
-  highways/index.ts    <- Repeated route convergence + bypass/cowpath evidence
+  highways/index.ts    <- Repeated route convergence + bypass/cowpath/synthesis evidence
   mcp/index.ts         <- 19 MCP tools for LLM integration
   mcp/hints.ts         <- Operation-keyed next-step hints for MCP tool responses
   impact/index.ts      <- Symbol-level impact analysis + rename planning
@@ -313,7 +313,7 @@ Reference finder for rename planning. Input: `{ oldName: string, newName: string
 Entry point execution flows. Input: `{ entryPoint?: string, limit?: number }`. Returns: processes with steps and depth.
 
 ## 17. analyze_highways
-Repeated route convergence. Input: `{ operation?: string, shape?: string, minRoutes?: number, propose?: boolean, trace?: string }`. Returns: bypass/cowpath opportunities with route chains, evidence, blast radius, proposed canonical node, and context pack.
+Repeated route convergence. Input: `{ operation?: string, shape?: string, minRoutes?: number, propose?: boolean, trace?: string }`. Returns: bypass/cowpath/synthesis opportunities with route chains, evidence, blast radius, proposed canonical node, optional synthesis proposal, and context pack.
 
 ## 18. get_clusters
 Community-detected file clusters. Input: `{ minFiles?: number }`. Returns: clusters with cohesion.
@@ -454,7 +454,7 @@ Entry point execution flows through the call graph.
 ```bash
 codebase-intelligence highways <path> [--operation <verb>] [--shape <name>] [--min-routes <n>] [--propose] [--trace <id>] [--json] [--force]
 ```
-Find repeated routes that should converge on one canonical operation path. Returns bypass/cowpath findings with route chains, canonical node, evidence, blast radius, recommendation, and context pack.
+Find repeated routes that should converge on one canonical operation path. Returns bypass/cowpath findings with route chains, canonical node, evidence, blast radius, recommendation, and context pack. With `--propose`, no-canonical route groups can return `synthesis` findings with proposed name, file, signature, skeleton, reroute plan, and cycle-safety check.
 
 ### clusters
 ```bash

llms.txt

@@ -35,7 +35,7 @@ codebase-intelligence symbol ./src parseCodebase
 codebase-intelligence impact ./src getUserById
 codebase-intelligence rename ./src oldName newName
 codebase-intelligence processes ./src --entry main
-codebase-intelligence highways ./src --operation create --min-routes 3 --json
+codebase-intelligence highways ./src --operation create --min-routes 3 --propose --json
 codebase-intelligence clusters ./src --min-files 3
 codebase-intelligence check ./src                      # rules gate for CI; JSON includes findings plus active/stale suppressions
 codebase-intelligence init .                         # make AI agents use CI

roadmap.md

@@ -397,9 +397,9 @@ entry ─► transform ─► validate ─► sink
 
 **Remaining:**
 
-- H2: add type-shape grouping once Type/Shape layer lands.
+- H2 shipped: add type-shape grouping once Type/Shape layer lands.
+- H2 shipped: synthesize new highway proposals: name, location, signature, skeleton, cycle-safe reroute plan.
 - H2: detect shape drift and near-duplicate intermediate steps.
-- H2: synthesize new highway proposals: name, location, signature, skeleton, cycle-safe reroute plan.
 - H3: add reuse hotspot metrics and cross-link opportunities into `forces` / `hotspots`.
 
 ### Scope Graph + Codebase Map