Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
docs(mcp): guidance that matches the response envelope (#2126)
Raghav Chamadiya1e4cbba3070a
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.mdindex 698fe0b14..7d348257f 100644--- a/docs/agent/MCP_TOOLS.md+++ b/docs/agent/MCP_TOOLS.md@@ -147,11 +147,11 @@ Resolve refs with `repowise expand <ref>` from a shell, or| Field | When present ||-------|--------------|| `timing_ms` | Tool wall-time |-| `hint` | A short, conservative follow-up suggestion |+| `hint` | A short, conservative follow-up suggestion. On a `get_answer` reply that graded `low` while the index is behind live HEAD, it says to run `repowise update` and ask again before trusting the answer || `cached` | Only when `true` || `index_age_days` | Days since the last `repowise update` || `indexed_commit` | Short (12-char) SHA the index was built against |-| `live_head` | Only when it differs from `indexed_commit` |+| `live_head` | Short (12-char) SHA of the current checkout, whenever `.git/HEAD` is readable. Equal to `indexed_commit` when the index is current || `stale_warning` | Only on a real signal: HEAD mismatch **that actually changed files**, or age over ~90 days when git is unreachable. Two commits with identical trees (an empty commit, a no-op merge) report `index_behind` with no warning || `index_behind` | Whenever the live-vs-indexed comparison ran: `true` if HEAD has moved (alongside `stale_warning` when served content actually changed), `false` if the commits match. Absent means the comparison could not run (no git, or a repo-level tool that serves no file content) || `embedder_degraded` | Whenever an embedder is resolved, `true` or `false`. Absent means none was initialised |@@ -247,28 +247,51 @@ One-call RAG: retrieves over the wiki, gates synthesis on confidence, and return| Parameter | Type | Required | Description ||-----------|------|----------|-------------|| `question` | string | Yes | Natural language question about the codebase |+| `scope` | string | No | Repository-relative path prefix to restrict retrieval to |+| `include` | list[string] | No | `["evidence"]` returns the expanded projection: no confidence-keyed trimming, and a larger response budget || `repo` | string | No | *(workspace only)* Target repo alias |-**Returns:** A synthesized answer with file/symbol citations and a confidence label (`high`, `medium`, `low`). High-confidence answers can be cited directly. Low-confidence answers return ranked wiki candidates instead, with the page excerpt served on the highest-scoring few; the rest carry path, title and summary, and one follow-up call opens any of them.--When synthesis cannot run at all — no provider resolvable, or the call failed —-the response carries a top-level `degraded` naming the reason, and is built from-retrieval and mined rationale with no LLM involved. `confidence` is `low` there-for a different reason than usual, so read `degraded` first. It also raises-`_meta.state.degraded`.+**Returns:** A synthesized answer with file/symbol citations, a `confidence`+label (`high`, `medium`, `low`) rating the prose, and a `retrieval_quality`+label (`high`, `partial`, `weak`) rating the evidence under it. Every grade+returns an answer; what changes is how much evidence rides along with it.+A `high` answer can be cited directly and sheds `retrieval`, `best_guesses`,+`candidates` and `fallback_targets`, keeping one quote and, when the answer is+not already grounded, one symbol body. A `medium` answer keeps one body, two+quotes and the top two evidence rows. A `low` answer keeps two bodies and the+top three evidence rows, and `fallback_targets` appears only when nothing else+was served. Read the rows the reply names rather than calling `search_codebase`+again. `include=["evidence"]` skips this trimming entirely.++When synthesis cannot run at all, no provider resolvable or the call failed, the+response carries a top-level `degraded` naming the reason, is built from+retrieval and mined rationale with no LLM involved, and keeps the fullest+evidence shape whatever it graded. It also raises `_meta.state.degraded`.+`confidence` there is graded from the retrieval actually served, not from the+missing prose: on `no-llm-provider` it is `medium` unless `retrieval_quality` is+`weak`, in which case `low`. Any other reason, a configured provider whose call+failed, stays `low`, because a retry can still produce a real answer. `high` is+unreachable on this path, since the `answer` string is assembled boilerplate.++`_meta.complete` names the symbol bodies served whole from live source, with+bounds checked against the file; do not re-open those. `_meta.scope_hint` names+up to three knowledge-graph layers holding none of the served paths, so an agent+knows which areas the answer did not touch. When an answer grades `low` and the+index is behind live HEAD, `_meta.hint` says to run `repowise update` and ask+again before trusting it.Two path-bearing blocks, with different jobs:| Field | Job | Confidence-gated? ||-------|-----|-------------------|| `retrieval` | **Evidence.** Enriched hits (summary, snippet, key symbols) to re-read when the prose needs checking. Shrinks as confidence rises, because a trustworthy answer needs less of it. | Yes |-| `candidates` | **Navigation.** The ranked shortlist of files retrieval resolved, one `{path, lines?}` entry each, up to 20. | No |+| `candidates` | **Navigation.** The ranked shortlist of files retrieval resolved, one `{path, lines?}` entry each, up to 20. | Shape-gated: the default projection drops it at every confidence |-`candidates` is present whenever retrieval resolved anything, including on high-confidence answers where `retrieval` is deliberately empty. It is where to look next; it is not evidence that the answer is right.+`candidates` is built whenever retrieval resolved anything, including on high-confidence answers where `retrieval` is deliberately empty, but the default projection drops it; ask for it with `include=["evidence"]`. It is where to look next; it is not evidence that the answer is right.**Retrieval legs:** three, fused by Reciprocal Rank Fusion: full-text and vector search over wiki pages, plus the structural symbol index. The symbol leg is keyed on the content words of the question rather than on whether it happens to carry an identifier-shaped token, so "how does an incremental update persist symbols" reaches the same rows as `_persist_symbols`. It exists because a generated file page renders only the *public* symbol table: a private helper or a local name is not in the text the other two legs index.-**When to use:** First call on any code question. Collapses search, read, and reason into one round-trip. If confidence is low, follow up with `search_codebase` to discover candidate pages.+**When to use:** First call on any code question. Collapses search, read, and reason into one round-trip. On a low grade, start from the evidence rows the reply already carries; reach for `search_codebase` only when `retrieval_quality` is `weak`.**Example call:**diff --git a/packages/core/src/repowise/core/generation/templates/agents_md.j2 b/packages/core/src/repowise/core/generation/templates/agents_md.j2index 37911329c..ddcd95286 100644--- a/packages/core/src/repowise/core/generation/templates/agents_md.j2+++ b/packages/core/src/repowise/core/generation/templates/agents_md.j2@@ -4,7 +4,8 @@ Indexed by [Repowise](https://repowise.dev). Last indexed: {{ data.indexed_at }}### How to work in this repo-- **Trust the index.** `verified: true` means the bytes were checked against the live tree, so never re-read those lines. Re-read only on `bounds: "approximate"`, `_meta.stale_warning`, `search_method: "bm25"` or `confidence: "low"`; `index_behind: true` alone is informational. `_meta.complete` names units served whole; never re-read those.+- **Trust the index.** `verified: true` and `_meta.complete` mean the bytes were checked against the live tree, so never re-read them. Re-read only what `bounds: "approximate"` or `_meta.stale_warning` names. `confidence` rates the prose, not the evidence: on `low` read the `fallback_targets` or `best_guesses` the reply names, and run `repowise update` and ask again if `_meta.hint` says the index is behind HEAD. `index_behind: true` alone is informational.+- **A zero carries its basis.** An empty `callers`/`callees`/`used_by` comes with a `*_basis` saying how much of that language's calls the graph resolved, so read it before concluding nothing calls a symbol. `_meta.scope_hint` names the areas the answer did not touch.- **Pre-edit, not instead-of-edit.** These tools decide *which* files to read and edit. Reading a file before you edit it is correct and expected.- **Noisy commands** (tests, builds, `git log`/`diff`, searches, listings): prefer `repowise distill <cmd>`, the same command with its exit code preserved and errors-first output. A `[repowise#<ref>: N lines omitted]` marker is recoverable via `repowise expand <ref>` (add `-q <regex>` to filter); never re-run the command to see omitted output.- **Recording a decision** you had to reason out: `repowise decision add --title T --decision D` records it without prompting and prints the id (`--format json` to parse it back). It lands `proposed`, for a person to confirm.diff --git a/packages/core/src/repowise/core/generation/templates/claude_md.j2 b/packages/core/src/repowise/core/generation/templates/claude_md.j2index 166b349ac..55b7e4120 100644--- a/packages/core/src/repowise/core/generation/templates/claude_md.j2+++ b/packages/core/src/repowise/core/generation/templates/claude_md.j2@@ -4,7 +4,8 @@ Indexed by [Repowise](https://repowise.dev). Last indexed: {{ data.indexed_at }}### How to work in this repo-- **Trust the index.** `verified: true` means the bytes were checked against the live tree, so never re-read those lines. Re-read only on `bounds: "approximate"`, `_meta.stale_warning`, `search_method: "bm25"` or `confidence: "low"`; `index_behind: true` alone is informational. `_meta.complete` names units served whole; never re-read those.+- **Trust the index.** `verified: true` and `_meta.complete` mean the bytes were checked against the live tree, so never re-read them. Re-read only what `bounds: "approximate"` or `_meta.stale_warning` names. `confidence` rates the prose, not the evidence: on `low` read the `fallback_targets` or `best_guesses` the reply names, and run `repowise update` and ask again if `_meta.hint` says the index is behind HEAD. `index_behind: true` alone is informational.+- **A zero carries its basis.** An empty `callers`/`callees`/`used_by` comes with a `*_basis` saying how much of that language's calls the graph resolved, so read it before concluding nothing calls a symbol. `_meta.scope_hint` names the areas the answer did not touch.- **Pre-edit, not instead-of-edit.** These tools decide *which* files to read and edit. Claude Code requires a raw Read of any file you will Edit, and that Read is correct and expected.- **Noisy commands** (tests, builds, `git log`/`diff`, searches, listings): prefer `repowise distill <cmd>` — same command, exit code preserved, errors-first output. A `[repowise#<ref>: N lines omitted]` marker is recoverable via `repowise expand <ref>` (add `-q <regex>` to filter); never re-run the command to see omitted output.- **Recording a decision** you had to reason out: `repowise decision add --title T --decision D` records it without prompting and prints the id (`--format json` to parse it back). It lands `proposed`, for a person to confirm.diff --git a/packages/core/src/repowise/core/generation/templates/workspace_claude_md.j2 b/packages/core/src/repowise/core/generation/templates/workspace_claude_md.j2index b85f54bc9..18671e900 100644--- a/packages/core/src/repowise/core/generation/templates/workspace_claude_md.j2+++ b/packages/core/src/repowise/core/generation/templates/workspace_claude_md.j2@@ -56,7 +56,8 @@ Files that frequently change together across repos — consider reviewing both wThese tools work across all repos in this workspace. Pass `repo="alias"` to scope, `repo="all"` for cross-repo queries, or omit for the default repo.-- **Trust the index.** `verified: true` means the bytes were checked against the live tree, so never re-read those lines. Re-read only on `bounds: "approximate"`, `_meta.stale_warning`, `search_method: "bm25"` or `confidence: "low"`; `index_behind: true` alone is informational. `_meta.complete` names units served whole; never re-read those.+- **Trust the index.** `verified: true` and `_meta.complete` mean the bytes were checked against the live tree, so never re-read them. Re-read only what `bounds: "approximate"` or `_meta.stale_warning` names. `confidence` rates the prose, not the evidence: on `low` read the `fallback_targets` or `best_guesses` the reply names, and run `repowise update` and ask again if `_meta.hint` says the index is behind HEAD. `index_behind: true` alone is informational.+- **A zero carries its basis.** An empty `callers`/`callees`/`used_by` comes with a `*_basis` saying how much of that language's calls the graph resolved, so read it before concluding nothing calls a symbol. `_meta.scope_hint` names the areas the answer did not touch.- **Workspace-specific:** `get_overview(repo="all")` returns cross-repo topology (co-changes, package deps, API contracts); `get_risk(changed_files=[...])` picks up cross-repo consumers automatically; `get_blast_radius` / `get_conformance` / `get_architecture` cover cross-repo impact, dependency-rule violations, and coupling.{{ data.tool_table_md }}diff --git a/tests/unit/generation/test_kg_claude_md_onboarding.py b/tests/unit/generation/test_kg_claude_md_onboarding.pyindex 54aa6f93e..a94e1ac4e 100644--- a/tests/unit/generation/test_kg_claude_md_onboarding.py+++ b/tests/unit/generation/test_kg_claude_md_onboarding.py@@ -116,7 +116,12 @@ class TestClaudeMdKGSection:# a response shape the agent sees rarely, and it was cut for size; the# load-bearing clause is what has to stay reachable.assert "`verified: true`" in rendered- assert "never re-read those lines" in rendered+ assert "never re-read them" in rendered+ # `confidence` rates the prose; a low grade points at the evidence the+ # reply already named rather than at a second round-trip.+ assert "`fallback_targets` or `best_guesses`" in rendered+ # An empty call-graph list is never served without the basis beside it.+ assert "`*_basis`" in rendered# Pre-edit framing: the mandatory Read of edit targets is conceded.assert "raw Read of any file you will Edit" in rendered# The tool table renders from the single-source module.