docs: add unified multi-repo graph to backlog (#97) (#514)

* docs: add unified multi-repo graph to backlog (#97)

Add backlog item for building a single graph spanning multiple
repositories, connected via package imports, API boundary inference,
and shared schema/proto files. Depends on #78 (cross-repo symbol
resolution). Placed in Tier 1i.

* fix: mark unified multi-repo graph as breaking (#514)

DB schema change (new repo column on nodes/edges) and output format
change (repo:path-qualified paths) both qualify as breaking per the
backlog's own column definition.

Author: carlos-alm

docs/roadmap/BACKLOG.md

@@ -172,6 +172,7 @@ These close gaps in search expressiveness, cross-repo navigation, implementation
 | 77 | Metric trend tracking (code insights) | `codegraph trends` computes key graph metrics (total symbols, avg complexity, dead code count, cycle count, community drift score, boundary violations) at historical git revisions and outputs a time-series table or JSON. Uses `git stash && git checkout <rev> && build && collect && restore` loop over sampled commits (configurable `--samples N` defaulting to 10 evenly-spaced commits). Stores results in a `metric_snapshots` table for incremental updates. `--since` and `--until` for date range. `--metric` to select specific metrics. Enables tracking migration progress ("how many files still use old API?"), tech debt trends, and codebase growth over time without external dashboards. | Intelligence | Agents and teams can answer "is our codebase getting healthier or worse?" with data instead of intuition — tracks complexity trends, dead code accumulation, architectural drift, and migration progress over time. Historical backfill from git history means instant visibility into months of trends | ✓ | ✓ | 3 | No | — |
 | 78 | Cross-repo symbol resolution | In multi-repo mode, resolve import edges that cross repository boundaries. When repo A imports `@org/shared-lib`, and repo B is `@org/shared-lib` in the registry, create cross-repo edges linking A's import to B's actual exported symbol. Requires matching npm/pip/go package names to registered repos. Store cross-repo edges with a `repo` qualifier in the `edges` table. Enables cross-repo `fn-impact` (changing a shared library function shows impact across all consuming repos), cross-repo `path` queries, and cross-repo `diff-impact`. | Navigation | Multi-repo mode currently treats each repo as isolated — agents can search across repos but can't trace dependencies between them. Cross-repo edges enable "if I change this shared utility, which downstream repos break?" — the highest-value question in monorepo and multi-repo architectures | ✓ | ✓ | 5 | No | — |
 | 79 | Advanced query language with boolean operators and output shaping | Extend `codegraph search` and `codegraph where` with a structured query syntax supporting: **(a)** boolean operators — `kind:function AND file:src/` , `name:parse OR name:extract`, `NOT kind:class`; **(b)** compound filters — `kind:method AND complexity.cognitive>15 AND role:core`; **(c)** output shaping — `--select symbols` (just names), `--select files` (distinct files), `--select owners` (CODEOWNERS for matches), `--select stats` (aggregate counts by kind/file/role); **(d)** result aggregation — `--group-by file`, `--group-by kind`, `--group-by community` with counts. Parse the query into a SQL WHERE clause against the `nodes`/`function_complexity`/`edges` tables. Expose as `query_language` MCP tool parameter. | Search | Current search is either keyword/semantic (fuzzy) or exact-name (`where`). Agents needing "all core functions with cognitive complexity > 15 in src/api/" must chain multiple commands and filter manually — wasting tokens on intermediate results. A structured query language answers compound questions in one call | ✓ | ✓ | 4 | No | — |
+| 97 | Unified multi-repo graph | New `codegraph build --repos <path1> <path2> ...` (or `.codegraphrc.json` `repos[]` list) that builds a single unified graph spanning multiple repositories. Each repo is parsed independently, then a merge step stitches them into one SQLite DB with repo-qualified file paths (`repo:path`). Three connection modes: **(a)** npm/pip/go package imports — repo A imports `@org/lib` which is repo B, resolved via `package.json`/`setup.py`/`go.mod` name matching; **(b)** API boundary inference — repo A calls `fetch('/api/users')` and repo B defines an Express/Flask/Gin route for `/api/users`, linked as a `cross-repo-api` edge with lower confidence; **(c)** shared schema/proto — repos sharing `.proto`, OpenAPI, or GraphQL schema files get edges through the shared contract types. All existing query commands (`fn-impact`, `diff-impact`, `path`, `audit`, `triage`, `exports`) work transparently on the unified graph — changing a shared library function shows impact across all consuming repos in one query. Requires a `repos` registry mapping package names to local paths (extend existing `~/.codegraph/registry.json`). Store a `repo` column on `nodes` and `edges` tables to partition ownership. | Navigation | Current multi-repo mode (`--multi-repo`) keeps each repo's graph isolated — you can search across repos but can't trace how a change in one repo impacts another. Real-world systems span multiple repos connected by package imports, API integrations, or shared schemas. A unified graph answers "if I change this endpoint handler, which frontend components break?" or "if I update this shared utility, which downstream services are affected?" — the highest-value cross-cutting questions that currently require manual tracing across repo boundaries | ✓ | ✓ | 5 | Yes | 78 |
 | 80 | ~~Find implementations in impact analysis~~ | ~~When a function signature or interface definition changes, automatically include all implementations/subtypes in `fn-impact` and `diff-impact` blast radius. Currently impact only follows `calls` edges — changing an interface method signature breaks every implementor, but this is invisible. Requires ID 74's `implements` edges. Add `--include-implementations` flag (on by default) to impact commands.~~ | Analysis | ~~Catches the most dangerous class of missed blast radius — interface/trait changes that silently break all implementors. A single method signature change on a widely-implemented interface can break dozens of files, none of which appear in the current call-graph-only impact analysis~~ | ✓ | ✓ | 5 | No | 74 | **PROMOTED** — Folded into ROADMAP Phase 4.3 (`--include-implementations` flag on impact commands) |
 
 ### Tier 1j — Audit-identified gaps (from Architecture Audit v3.1.4)