feat(mcp): overhaul tools — get_symbol exposed, get_answer reworked, page leads tuned

[RaghavChamadiya]

Summary

Overhaul of the Repowise MCP surface plus the wiki-page generator that feeds it, so the two compound instead of fighting each other.

MCP server (8 tools, was 7)

• get_symbol exposed — agents can now fetch bounded source bytes by canonical path::Name ID without computing line offsets
• get_context trimmed to a triage card — removed include=[\"source\"], added a single hotspot bit, decision-record titles, and symbol_id pointers. Ownership, last_change, decisions are now include=-gated
• get_risk(changed_files=...) no longer bloats to 76k tokens — drops global hotspots in PR mode, caps co-change/transitive lists, emits a directive block (will_break, missing_cochanges, missing_tests) for one-glance PR review
• search_codebase — new kind filter (implementation/test/config/doc), search_method per result (embedding vs bm25 fallback), Grep hint when query is a bareword identifier
• Staleness signal in _meta — index_age_days always present; stale_warning fires only when repository.head_commit ≠ live .git/HEAD. Silence is the signal; the field stays trustworthy
• Every tool's docstring rewritten to lead with what only that tool answers

get_answer pipeline (new modules _answer_pipeline.py, _answer_context.py)

• Hybrid retrieval — FTS + vector store in parallel, merged via Reciprocal Rank Fusion, scaled into BM25 range so existing gates calibrate
• PageRank bias — damped, normalised within the candidate set; tie-breaker not override
• 1-hop graph expansion — rescues near-misses where retrieval landed in the right module but on the wrong file (consumer vs orchestrator)
• Decision-record fusion for "why" questions — get_why ADRs are injected into the LLM context block so get_answer and get_why finally cohere
• Structured prelude — top symbols, recent significant commits, decision titles prepended before file excerpts
• Calibrated confidence + separate retrieval_quality — synthesis quality and retrieval quality reported on different axes
• best_guesses on low-confidence path — agent gets ranked candidates with one-line justifications instead of an empty answer
• Schema-versioned cache — bumped to v3; older payloads auto-invalidate

Wiki page generation

The MCP retrieval upgrades only matter if the corpus has signal-dense leads. The first 200–500 chars of a page dominate the embedding signal and were previously boilerplate metadata.

• file_page / module_page / repo_overview system prompts now mandate a role-leading first sentence with architectural vocabulary (orchestrator, entry point, parser, adapter, …)
• file_page.j2 collapses 8 bullet metadata into a compact line plus a prose **Architectural signals:** line that translates raw metrics (PageRank 0.0234) into vocabulary ("entry point", "central in the dependency graph", "bridge between modules"). Raw numerics moved to a "do NOT recite verbatim" footer
• module_page.j2 and repo_overview.j2 get the same treatment

CLAUDE.md generator

The stale 9-tool table referenced three tools that don't exist (update_decision_records, get_dependency_path, get_architecture_diagram). Replaced with the actual 8-tool surface, with each row leading with the tool's unique value and a "verify when…" line tied to the new stale_warning / retrieval_quality / search_method signals.

Test plan

• Smoke import: python -c \"from repowise.server.mcp_server import get_symbol, get_answer\" succeeds
• repowise update --force regenerates pages under the new prompts
• Restart MCP, ask get_answer(\"how does a repository get indexed end-to-end?\") — should now surface orchestrator.py via vector retrieval + graph expansion, not tool_symbol.py
• get_context([\"packages/cli/src/repowise/cli/commands/init_cmd.py\"]) returns hotspot: true, symbol_id per symbol, no ownership/last_change unless requested
• get_risk(targets=[\"X\"], changed_files=[\"X\", \"Y\"]) returns the new directive block and stays under ~8k tokens
• search_codebase(\"PageGenerator\") returns the grep_hint for bareword identifier queries
• On a clean repo, _meta.stale_warning is absent; after committing without re-indexing, it appears with the live HEAD short SHA