Add IDE-style semantic navigation for agents (#155)

* Add workspace symbol lookup surfaces

* Add type hierarchy and implementation lookup

* Add bounded call hierarchy navigation

* Add safe semantic rename previews

* Add refactor evidence planning workflow

* Address semantic navigation review findings

* Address final semantic navigation review findings

* Bound semantic implementation diagnostics

* Cover composed symbol filters and overload identity

* Assert overload implementation ownership

* Fix deterministic workspace symbol ranking

* Cache sorted call hierarchy adjacency

* Use deterministic call hierarchy ordering

Author: lzehrung

README.md

@@ -31,16 +31,18 @@ Use Codegraph alongside text search and compilers: text search finds exact strin
 
 ## What you can do
 
-| Question                                | Start here                                                              | What comes back                                                                   |
-| --------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
-| "Where should I start in this repo?"    | `codegraph orient --root . --budget small --pretty`                     | Central modules, a bounded tree, and copyable follow-ups                          |
-| "How does this feature work?"           | `codegraph explore "<question>" --root . --pretty`                      | Ranked anchors, source packets, dependency paths, blast radius, and likely tests  |
-| "What could this change break?"         | `codegraph review --base HEAD --head WORKTREE --summary`                | Changed symbols, risk signals, candidate tests, duplicate leads, and review tasks |
-| "What depends on this file?"            | `codegraph rdeps src/file.ts --json`                                    | Reverse dependencies from the resolved project graph                              |
-| "Where is this symbol defined or used?" | `codegraph goto <file> <line> <column>` and `codegraph refs ...`        | Semantic definitions and references across supported languages                    |
-| "Is the architecture drifting?"         | `codegraph drift ./src --base origin/main --head HEAD --pretty`         | New cycles, hotspot changes, unresolved imports, API changes, and graph deltas    |
-| "Where is code duplicated?"             | `codegraph duplicates ./src --min-confidence medium`                    | Ranked exact and near-duplicate groups with locations and confidence              |
-| "Can another tool consume the graph?"   | `codegraph graph --root . ./src --compact-json --output codegraph.json` | JSON, Mermaid, DOT, or SQLite output                                              |
+| Question                                     | Start here                                                              | What comes back                                                                              |
+| -------------------------------------------- | ----------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| "Where should I start in this repo?"         | `codegraph orient --root . --budget small --pretty`                     | Central modules, a bounded tree, and copyable follow-ups                                     |
+| "How does this feature work?"                | `codegraph explore "<question>" --root . --pretty`                      | Ranked anchors, source packets, dependency paths, blast radius, and likely tests             |
+| "What could this change break?"              | `codegraph review --base HEAD --head WORKTREE --summary`                | Changed symbols, risk signals, candidate tests, duplicate leads, and review tasks            |
+| "What depends on this file?"                 | `codegraph rdeps src/file.ts --json`                                    | Reverse dependencies from the resolved project graph                                         |
+| "Where is this symbol defined or used?"      | `codegraph goto <file> <line> <column>` and `codegraph refs ...`        | Semantic definitions and references across supported languages                               |
+| "Which declaration matches this name?"       | `codegraph symbols "CodeReviewSession" --root . --pretty`               | Ranked symbols with portable handles, exact ranges, provenance, and omissions                |
+| "What evidence do I need before a refactor?" | `codegraph refactor-plan <symbol-handle> --pretty`                      | References, call and type relationships, candidate tests, omissions, and copyable follow-ups |
+| "Is the architecture drifting?"              | `codegraph drift ./src --base origin/main --head HEAD --pretty`         | New cycles, hotspot changes, unresolved imports, API changes, and graph deltas               |
+| "Where is code duplicated?"                  | `codegraph duplicates ./src --min-confidence medium`                    | Ranked exact and near-duplicate groups with locations and confidence                         |
+| "Can another tool consume the graph?"        | `codegraph graph --root . ./src --compact-json --output codegraph.json` | JSON, Mermaid, DOT, or SQLite output                                                         |
 
 Human-readable output uses `--pretty` or `--summary`. JSON, MCP tools, and library APIs preserve stable fields, ranges, handles, reasons, confidence, and omission counts for automation.
 

codegraph-skill/codegraph/SKILL.md

@@ -43,12 +43,31 @@ Use `--root` to define the boundary for config lookup, cache scope, path confine
 
 - answer a question with bounded evidence: `codegraph explore "how does auth reach db?" --root . --pretty`
 - find a ranked anchor: `codegraph search "auth user" --json`
+- resolve a known symbol identity: `codegraph symbols "CodeReviewSession" --root . --pretty`
 - explain a known target: `codegraph explain <file|symbol|sql-object|handle>`
 - retrieve bounded indexed context: `codegraph packet get <file|symbol|sql-object|handle> --pretty`
 - read current disk content: `codegraph file <path> --offset 1 --limit 200 --pretty`
 
 `explore` returns ranked anchors, bounded packets, dependency paths, blast radius, candidate tests, explicit limits, omission counts, and copyable follow-ups. Hybrid search is code-first by default; search, explain, explore, and review output preserve analysis labels so reduced or mixed runs remain visible.
 
+Use `symbols` instead of hybrid `search` when only declarations should compete. It supports `--kind <kind,...>`, `--exported`, `--include-imports`, project-relative `--file-glob`, and `--limit <0-500>`; imports default off, and only named/default aliases that resolve to concrete declarations are returned.
+
+Use the portable callable handle from `symbols` with `codegraph callers <handle>` or `codegraph callees <handle>`. Depth defaults to 1 and caps at 5, the symbol limit defaults to 100 and caps at 500, JSON is the default, and `--pretty` prints grouped exact callsites.
+
+Call hierarchy contains resolved semantic `calls` edges only. `--include-heuristic` is accepted but currently adds no guessed dynamic calls; use `refs` for all references and `deps` or `rdeps` for file relationships.
+
+Use the portable handle from `symbols` with `codegraph supertypes <handle>`, `codegraph subtypes <handle>`, or `codegraph implementations <handle>`. Hierarchy depth defaults to 1 and caps at 10; all result limits default to 100 and cap at 500, and `--pretty` is the concise human-readable form.
+
+Hierarchy results contain only proven indexed `extends` and `implements` relationships. Implementation targets are interfaces, traits, abstract types, and members with proven implementation or override relationships; exact declarations are returned, while overloads, dynamic or structural conformance, unrelated same-name methods, and unresolved external bases are not guessed.
+
+Use `codegraph rename-preview <handle> <new-name> --json` to plan a semantic rename without changing files. Add `--include-comments`, `--include-strings`, or `--include-filenames` only when needed, and use `--max-edits <1-10000>` to bound the plan.
+
+Treat `safe: false`, conflicts, unsafe sites, and omissions as blockers. Eligible exported class, interface, and type filename results are suggestions only; Codegraph has no apply command or tool.
+
+Use `codegraph refactor-plan <handle> --pretty` to compose references, direct callers and callees, hierarchy, implementations, section issues, candidate tests, omissions, and copyable follow-ups from one snapshot. It accepts portable search or workspace-symbol handles and exact internal review or impact symbol handles; add `--rename <new-name>` only when the packet should include the authoritative nested rename preview.
+
+The independent `--max-references`, `--max-callers`, and `--max-hierarchy` bounds accept 0 to 500, and `--include-source` opts reference context into output. Treat `sectionIssues`, omissions, and nested `rename.safe` as authoritative; the packet is read-only and has no apply action.
+
 ### Navigate
 
 - dependencies: `codegraph deps <file>`
@@ -111,7 +130,12 @@ Sensitive-file rules:
 
 ## MCP and Freshness
 
-If MCP tools are available, prefer them over repeated CLI invocations. Use `explore`, `orient`, `search`, `get_file`, `packet_get`, `goto`, `refs`, `deps`, `rdeps`, `path`, `impact`, `review`, and `query_sqlite`; fall back to the CLI when MCP is unavailable.
+If MCP tools are available, prefer them over repeated CLI invocations. Use `explore`, `orient`, `workspace_symbols`, `search`, `get_file`, `packet_get`, `goto`, `refs`, `rename_preview`, `refactor_plan`, `callers`, `callees`, `deps`, `rdeps`, `path`, `impact`, `review`, and `query_sqlite`; fall back to the CLI when MCP is unavailable.
+Use `refactor_plan` with flat `handle`, optional `renameTo`, independent optional `maxReferences`, `maxCallers`, and `maxHierarchy` bounds from 0 to 500, and optional `includeSource`. It reuses the configured server root and one session snapshot, returns portable targets and follow-ups even for exact internal review handles, exposes unsupported implementation sections in `sectionIssues`, preserves nested `rename.safe`, and never writes.
+Use `workspace_symbols` for deterministic symbol identities and exact ranges; use `search` when paths, prose, SQL, snippets, or graph evidence should participate.
+Use `supertypes`, `subtypes`, and `implementations` with portable symbol handles for repeated hierarchy queries; their schemas are flat and use the same 10-depth and 500-result caps as the CLI.
+Use `callers` and `callees` with portable callable handles for repeated call hierarchy queries. Their flat schemas accept `handle`, `depth`, `limit`, and `includeHeuristic`, reuse the MCP freshness gate, and cap depth at 5 and symbols at 500; current results remain semantic-only.
+Use `rename_preview` with `handle`, `newName`, optional boolean inclusion fields, and optional `maxEdits`. It remains available in read-only mode, reuses the MCP session, never changes files, and has no apply counterpart.
 
 Keep live and indexed evidence distinct:
 

docs/agent-workflows.md

@@ -93,6 +93,46 @@ Orientation returns summary bullets, ranked `focus` targets, a bounded tree, bud
 Use `orient --pretty` or MCP `orient` for compact model-readable triage and `orient --json` when follow-up tools need exact focus reasons, limits, or omission counts.
 Small orientation packets default to cheap health analysis; use larger budgets only when cycle, unresolved-import, or duplicate counts matter.
 
+## Workspace-symbol identities
+
+Use `symbols` when the question is "which declaration has this identity?" and follow with the returned portable handle. It is deterministic and filterable; use hybrid `search` instead when paths, prose, SQL, snippets, or graph evidence should participate.
+
+```bash
+codegraph symbols "CodeReviewSession" --root . --pretty
+codegraph symbols "src/session.ts::CodeReviewSession" --json
+codegraph explain "<handle-from-symbols>" --json
+```
+
+Imports are excluded unless `--include-imports` is explicit. Compose `--kind`, `--exported`, and project-relative `--file-glob` filters to narrow large workspaces; the limit defaults to 50 and caps at 500.
+
+## Read-only rename planning
+
+Resolve the declaration with `symbols`, then pass its portable handle to rename preview:
+
+```bash
+codegraph rename-preview "<type-handle-from-symbols>" RenamedService --include-filenames --json
+```
+
+Treat `safe: false`, conflicts, unsafe sites, and omitted edits as blockers rather than silently applying a partial plan. Comment and string edits are opt-in low-confidence candidates; eligible exported type filename results are suggestions only, Codegraph never changes files, and no apply command or tool exists.
+
+Repeated library calls should use `previewRenameWithSession` or `tool_previewRename` with one caller-owned `AgentSession`. MCP hosts should use `rename_preview`, which stays available in read-only mode and reuses the server session.
+
+## Search or review handoff to a refactor plan
+
+Keep the exact symbol handle returned by search or the changed-symbol handle returned by review or impact, then pass it directly to `refactor-plan`:
+
+```bash
+codegraph search "service dispatch" --mode symbol --json
+codegraph refactor-plan "<exact-handle-from-search>" --max-references 200 --pretty
+
+codegraph review --base HEAD --head WORKTREE --json
+codegraph refactor-plan "<exact-changed-symbol-handle-from-review>" --rename RenamedService --json
+```
+
+The packet reuses one snapshot and freshness decision for references, direct calls, hierarchy, implementations, candidate tests, and follow-ups. Review and impact may expose internal symbol handles, but the packet returns a portable target handle and uses it in copyable commands.
+
+Treat nested `rename.safe` as authoritative when `--rename` is present. Limits are independent, omissions remain explicit, source context is opt-in with `--include-source`, and refactor planning never writes or exposes an apply action.
+
 ## Search anchors
 
 Use `search` when an agent has a query but no file target or search handle and needs a compact starting point before calling `goto`, `refs`, `deps`, `rdeps`, `chunk`, or later explanation tooling:

docs/benchmarks/README.md

@@ -20,6 +20,12 @@ npm run bench:docs
 
 This command rebuilds stale `dist` output when needed, runs every scenario and both variants serially, requires complete anchor evidence, rewrites `results.example.json` and the generated table below, and prints the median table. The fixtures are local and the run makes no network requests.
 
+### Focused semantic regression fixture
+
+`tests/refactor-plan-performance.test.ts` uses the deterministic TypeScript fixture under `tests/fixtures/refactor-plan-performance`. It records runtime metadata, operation samples for exact workspace lookup, direct and depth-3 calls, hierarchy and implementations, rename preview at 10, 100, and 1000 references, repeated warm plans, and hierarchy-index peak RSS.
+
+The test asserts result structure, one-session and adjacency-cache behavior, plus deliberately generous environment-scoped time and memory ceilings. It is a regression guard, is not part of the checked comparison table below, and does not establish universal latency or scale claims.
+
 ## Workflows and metrics
 
 Each checked scenario in [`scenarios.json`](./scenarios.json) defines a local fixture, a task, ordered expected anchors, and the exact steps for both variants. The scenarios cover TypeScript request paths, Python imports, SQL migration and application coupling, and Markdown-to-TypeScript request paths.