Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

docs: correct what 0.52.0 changed, and give documentation drift a page (#2480)

Raghav Chamadiya8f693247d5a0
diff --git a/README.md b/README.md
index 6d524d8ae..55ed6bfca 100644
--- a/README.md
+++ b/README.md
@@ -161,8 +161,9 @@ toward the modules you and your agent ask about most, with no switch needed.
| **Graph** | File + symbol dependencies across 26 AST-parsed languages, confidence-stamped call resolution, communities, centrality, cycles, and execution flows |
| **Git** | Hotspots, ownership, co-change, bus factor, and bug-fix history: behavioral signals static analysis cannot see |
| **Docs** | A wiki for every module and file, rebuilt incrementally with freshness and confidence scoring plus hybrid search |
+| **Documentation drift** | Your own markdown checked against the tree: the claims each document makes, resolved against the graph, and the ones the code refutes |
| **Decisions** | Architectural rationale mined from five index-time sources plus human and agent capture, each claim traced to evidence |
-| **Code health** | 49 deterministic detectors across defect risk, maintainability, and performance, followed by concrete refactoring plans |
+| **Code health** | 51 deterministic detectors across defect risk, maintainability, and performance, followed by concrete refactoring plans |
The structural wiki needs no model. Model-written prose is an optional upgrade, one
page or directory at a time. Six of the seven decision sources are deterministic too;
@@ -193,7 +194,7 @@ rewrites noisy commands automatically, shown to you for approval first.
<div align="center">
<img src=".github/assets/savings.png" alt="repowise Costs dashboard: tokens and dollars saved across distill and the MCP tools" width="100%" />
-<p align="center"><sub>The <strong>Costs</strong> dashboard tallies both savings surfaces, priced at your own agent's model. Example from a week of heavy local use.</sub></p>
+<p align="center"><sub>The <strong>Costs</strong> dashboard tallies both savings surfaces. Every event is priced from the model that produced it, never repriced at whatever you are running today, and the total is a deliberate floor: where the evidence is ambiguous it declines to claim a saving. Example from a week of heavy local use.</sub></p>
</div>
Full guide: **[docs/agent/DISTILL.md →](docs/agent/DISTILL.md)**
@@ -309,7 +310,7 @@ every file, locates where the risk concentrates, and then names the specific fix
<img src=".github/assets/health-loop.svg" alt="repowise code-health loop: deterministic markers fan into three signals, the graph and git history locate where risk concentrates, and refactoring intelligence emits concrete plans your agent executes" width="100%" />
</div>
-Every file is scored 1-10 by **49 deterministic detectors** (McCabe complexity, brain
+Every file is scored 1-10 by **51 deterministic detectors** (McCabe complexity, brain
methods, LCOM4 cohesion, god classes, native Rabin-Karp clone detection, untested
hotspots, change entropy, prior-defect history and more), split into three lenses:
**defect risk**, **maintainability**, and **performance**: static N+1 and I/O-in-loop
@@ -846,7 +847,7 @@ August 2026. Unmarked rows are capability presence, not measurements.</sub>
| | repowise | CodeScene |
|---|---|---|
| Self-hostable, open source | ✅ AGPL-3.0 | ⚠️ on-prem Docker, proprietary |
-| Code health score (1-10) | ✅ 49 detectors, 26 scoring | ✅ 25-30 |
+| Code health score (1-10) | ✅ 51 detectors, 26 scoring | ✅ 25-30 |
| Brain Method / LCOM4 / god class | ✅ | ✅ |
| **Defects found at a 20% review budget** *([measured](docs/BENCHMARKS.md#5-code-health-predicts-defects), 2,770 files)* | ✅ **0.173** | 0.074 |
| **Effort-aware ranking, Popt** *(measured, p=0.003)* | ✅ **0.607** | 0.462 |
@@ -1004,10 +1005,12 @@ repowise risk main..HEAD # score a branch or PR range for defect risk
repowise risk -t <file> # what history says about touching a file
repowise impacted-tests # only the tests a diff actually exercises
repowise dead-code # unreachable-code report
+repowise doc-drift # documentation the code no longer supports
repowise decision list # architectural decisions
repowise export --format structurizr # the architecture as Structurizr DSL, no LLM
repowise distill pytest # compact, errors-first, reversible command output
repowise saved # tokens and dollars saved by distillation
+repowise savings # the full agent savings ledger, priced per event
repowise workspace add # multi-repo workspace management
repowise doctor # check setup, API keys, index drift
repowise uninstall # remove what repowise wrote, and say what it left
diff --git a/docs/BENCHMARKS.md b/docs/BENCHMARKS.md
index aeb86ae6f..332df1fd4 100644
--- a/docs/BENCHMARKS.md
+++ b/docs/BENCHMARKS.md
@@ -555,7 +555,7 @@ one that reaches significance and the one to cite.
Marker weights are **calibrated against a real defect corpus, not hand-tuned**:
every file scored at a commit preceding the bug window so nothing leaks backward,
and an L2-logistic fit with file size as an explicit control, so a marker only
-earns weight for defect lift *beyond* being big. Only **26** of the 49 detectors
+earns weight for defect lift *beyond* being big. Only **26** of the 51 detectors
are permitted to move the defect number, because that is the number carrying these
accuracy claims.
diff --git a/docs/CHANGELOG.md b/docs/CHANGELOG.md
index f30df82f1..c21ccb986 100644
--- a/docs/CHANGELOG.md
+++ b/docs/CHANGELOG.md
@@ -45,6 +45,7 @@ Code health can see test quality for the first time — a test that checks nothi
- **`timing_ms` is reported for every tool** (#2271), rather than for the ones someone had remembered to thread it through.
- **History-based health gates are ranked against the repository** (#2437, #2438). Six months is a fixed window, so a repository landing many commits a day accumulates more fix commits per file inside it than a quiet one; with an entry gate of one fix, `prior_defect` fired on 43.5% of the files here, and a signal that flags nearly half a tree is not locating anything. Co-change breadth is measured before truncation rather than by counting a list capped at 25 partners, where above the cap every file looks identical.
- **An agent is defined once** (#2394). The same agent was spelled four ways across four hand-maintained namespaces, and the savings domain had added a fifth and a sixth that agreed with the target registry only by hand.
+- Plugin: the `decision` command says that acceptance now requires a stated reason, documents `--kind agreement` and `--evidence-commit`, and stops claiming a fixed capture-source count.
### Fixed
diff --git a/docs/README.md b/docs/README.md
index 34f5ce165..d6070ff53 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -51,7 +51,7 @@ your agent in under five minutes, with no API key.
| Doc | What it covers |
|-----|----------------|
| [layers/INTELLIGENCE_LAYERS.md](layers/INTELLIGENCE_LAYERS.md) | Overview of the five layers: graph, git, docs, decisions, code health |
-| [layers/CODE_HEALTH.md](layers/CODE_HEALTH.md) | Defect risk, maintainability, and performance from 49 deterministic detectors |
+| [layers/CODE_HEALTH.md](layers/CODE_HEALTH.md) | Defect risk, maintainability, and performance from 51 deterministic detectors |
| [layers/REFACTORING.md](layers/REFACTORING.md) | Concrete, graph-aware refactoring plans (Extract Class, Move Method, Break Cycle) |
| [layers/CHANGE_RISK.md](layers/CHANGE_RISK.md) | Score any commit or `base..HEAD` range 0-10 for defect risk |
| [layers/BUG_HISTORY.md](layers/BUG_HISTORY.md) | Which files and symbols actually get bug-fixed, and how recently |
@@ -59,6 +59,7 @@ your agent in under five minutes, with no API key.
| [layers/GRAPH.md](layers/GRAPH.md) | The dependency graph: what is in it, how every edge is resolved, and how much to trust each one |
| [layers/DECISIONS.md](layers/DECISIONS.md) | Architectural decisions mined from your repo and from your own agent sessions |
| [layers/DEAD_CODE.md](layers/DEAD_CODE.md) | Unreachable files, unused exports, and zombie packages by confidence tier |
+| [layers/DOC_DRIFT.md](layers/DOC_DRIFT.md) | Documentation claims checked against the tree: what is checked, what is not, and how to read a finding |
| [layers/SECURITY.md](layers/SECURITY.md) | The local pattern scan: what the sixteen patterns catch, what they do not, and how far to trust the result |
| [layers/LANGUAGE_SUPPORT.md](layers/LANGUAGE_SUPPORT.md) | What works per language: 26 parsed to a full AST, 40 on the five-rung ladder |
| [layers/WIKI.md](layers/WIKI.md) | The generated wiki: page types, what `update` re-renders, styles, output language |
@@ -111,6 +112,7 @@ How repowise is built, for contributors and the curious.
| [architecture/chat.md](architecture/chat.md) | Codebase chat: agent loop, streaming, artifact panel |
| [architecture/structurizr-export.md](architecture/structurizr-export.md) | Export the architecture as Structurizr DSL and render it anywhere |
| [architecture/editor-files.md](architecture/editor-files.md) | How `CLAUDE.md` and `AGENTS.md` get generated |
+| [architecture/savings-accounting.md](architecture/savings-accounting.md) | The agent savings ledger: one canonical event per interaction, priced from its own evidence |
| [architecture/deep-dives.md](architecture/deep-dives.md) | Systems not covered elsewhere |
| [architecture/pluggable-storage.md](architecture/pluggable-storage.md) | The capability seams: storage, graph, vector, CLI, MCP |
| [design/theme-tokens.md](design/theme-tokens.md) | Resolved design tokens and the WCAG contrast matrix |
diff --git a/docs/agent/HOOKS.md b/docs/agent/HOOKS.md
index 289df2b74..56c7da3ee 100644
--- a/docs/agent/HOOKS.md
+++ b/docs/agent/HOOKS.md
@@ -27,7 +27,7 @@ crashes or blocks your agent.
| **Codex context + staleness** | Codex | `repowise init --codex` | SessionStart / edit / shell | Reminds Codex to use the MCP tools and flags stale context after edits |
Every agent hook records what it said and whether the agent acted on it — see
-[`repowise hook stats`](#is-any-of-this-actually-helping--repowise-hook-stats).
+[`repowise hook stats`](#hook-efficacy-repowise-hook-stats).
---
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.md
index 4c8fc9c72..615addab7 100644
--- a/docs/architecture/code-health.md
+++ b/docs/architecture/code-health.md
@@ -296,9 +296,9 @@ returning a list of `BiomarkerResult`s.
### The full roster
-`biomarkers/registry.py` registers **49 detectors**; counting the three
+`biomarkers/registry.py` registers **51 detectors**; counting the three
governance findings written by the additive pass (`governance.py`) there
-are **52 marker ids**. They divide by what each is permitted to affect:
+are **54 marker ids**. They divide by what each is permitted to affect:
| Group | Count | Scores into |
|---|---:|---|
@@ -306,6 +306,7 @@ are **52 marker ids**. They divide by what each is permitted to affect:
| Performance | 20 | `performance` only |
| SQL | 3 | `maintainability` only |
| Governance | 3 | nothing — the finding surfaces, the score is untouched |
+| Advisory | 2 | nothing — measured by construction, kept out of impact-ranked lists unless requested |
The authority is `scoring._BIOMARKER_DIMENSIONS`. Any biomarker **not** listed
there defaults into `defect`, which is why every `sql_*` and every performance
diff --git a/docs/business/COMMERCIAL.md b/docs/business/COMMERCIAL.md
index f616ab51a..215471bc7 100644
--- a/docs/business/COMMERCIAL.md
+++ b/docs/business/COMMERCIAL.md
@@ -48,7 +48,7 @@ All of the following ship in `pip install repowise` today, free for internal use
commits, contributor profiles, module health), Documentation (a wiki page per
module and file, freshness scoring, hybrid search), Decision (architectural
decision records linked to graph nodes, staleness tracking), and Code Health
- (49 deterministic detectors, 1–10 score per file, coverage ingestion, trend
+ (51 deterministic detectors, 1–10 score per file, coverage ingestion, trend
alerts). Full detail on each, and what every layer costs to build:
**[INTELLIGENCE_LAYERS.md](../layers/INTELLIGENCE_LAYERS.md)**.
- **Zero LLM calls in every analysis layer.** Graph, git, code health, change
diff --git a/docs/layers/CODE_HEALTH.md b/docs/layers/CODE_HEALTH.md
index 3e7b71ac6..2fb66988f 100644
--- a/docs/layers/CODE_HEALTH.md
+++ b/docs/layers/CODE_HEALTH.md
@@ -74,7 +74,7 @@ per-line blame index built for every file.
## The markers, and what each is allowed to do
-Repowise ships **49 registered detectors (52 marker ids)**, but only **26 are
+Repowise ships **51 registered detectors (54 marker ids)**, but only **26 are
permitted to move the headline number**. That restriction is deliberate: the
defect score carries published accuracy claims, so only markers that earned
their weight against a bug corpus may affect it.
@@ -85,6 +85,7 @@ their weight against a bug corpus may affect it.
| **Performance** | **20** | Own pillar, own cap; never touches the defect score |
| **Maintainability-only (SQL)** | **3** | Maintainability only |
| **Governance** | **3** | Surfaces as a finding; never deducts |
+| **Advisory** | **2** | Measured and reported; never deducts, and stays out of impact-ranked lists unless asked for |
Nothing is inert, but "doesn't move the number" means three different things:
@@ -645,5 +646,7 @@ unchanged files stay put; no nightly full re-index.
the full marker roster, and the complete weight tables.
- [`docs/BENCHMARKS.md`](../BENCHMARKS.md): every published number with its
sample size and test.
+- [DOC_DRIFT.md](DOC_DRIFT.md): the other thing this layer checks, your own
+ documentation against the tree.
- [REFACTORING.md](REFACTORING.md) · [TEST_INTELLIGENCE.md](TEST_INTELLIGENCE.md) ·
[BUG_HISTORY.md](BUG_HISTORY.md)
diff --git a/docs/layers/DOC_DRIFT.md b/docs/layers/DOC_DRIFT.md
new file mode 100644
index 000000000..a763cb862
--- /dev/null
+++ b/docs/layers/DOC_DRIFT.md
@@ -0,0 +1,88 @@
+# Documentation drift
+
+Documentation makes checkable claims about code. A path, a link, a heading
+reference, a command. Repowise already holds the graph those claims are about,
+so it checks them and reports the ones the tree refutes.
+
+This is part of the code-health layer, not a separate analysis you run. It
+happens on every `init` and every `update`, needs no model, and costs nothing.
+
+## What it checks
+
+Four classes of reference, all of them things the repository itself can settle:
+
+| Kind | The claim | How it is refuted |
+|---|---|---|
+| `path` | a document names a file or directory | nothing at that path |
+| `link` | a document links to another document | the target is not there |
+| `anchor` | a link points at a heading | the heading was renamed or removed |
+| `command` | a document tells you to run something | the manifest no longer declares it |
+
+The anchor case is the one people are most surprised by, because it is the one
+that rots silently: renaming a heading breaks every link into it, and nothing
+in an ordinary toolchain notices.
+
+## What it deliberately does not check
+
+Most sentences in a repository are not checkable, and this analysis does not
+guess at them. It says nothing about whether prose is accurate, current,
+well-written or complete. It has no opinion on a paragraph describing how a
+system works.
+
+**A clean run is not a claim that your documentation is true.** It is a claim
+that the references it could resolve, resolved. That distinction is the whole
+design: a checker that guessed would be wrong often enough that nobody would
+trust the findings that matter.
+
+## Reading a finding
+
+Every finding carries the line as the document wrote it, the heading trail
+locating the passage, and what the resolver checked. You should be able to
+decide whether it is real without opening the file.
+
+Findings carry a confidence, and the default floor is 0.4. Raise it when you
+want only the near-certain ones:
+
+```bash
+repowise doc-drift # everything above the floor
+repowise doc-drift --kind anchor # just the renamed-heading links
+repowise doc-drift --min-confidence 0.9 # the ones worth fixing blind
+```
+
+Confidence is about resolution, not importance. A high-confidence finding is
+one the analysis is sure it resolved correctly. Whether that broken link
+matters is your call.
+
+## The reverse view
+
+The question "which documents talk about this file?" is worth asking before
+you change the file, and it is the same evidence read the other way:
+
+```
+get_context(targets=["src/auth.py"], include=["doc_drift"])
+```
+
+That returns the documents naming it, where in each, and whether those
+documents already carry drift of their own. Useful when you are about to move
+or rename something and want to know what will go stale.
+
+## Where it shows up
+
+- `repowise doc-drift` for the report, with `--format json` for a script
+- `get_health(include=["doc_drift"])` for an agent
+- The Code Health tab in the dashboard
+- Refreshed on every `update`, not only on a clean index
+
+## Known limitation
+
+A path that exists on disk but sits outside the index reports as though it were
+missing. The reason string says the path no longer exists when it means the
+path is not indexed. Excluded directories such as test fixtures are the common
+case. Check whether the path is in your index scope before acting on a `path`
+finding that looks wrong.
+
+## See also
+
+- [CODE_HEALTH.md](CODE_HEALTH.md) — the layer this belongs to
+- [`repowise doc-drift`](../reference/CLI_REFERENCE.md#repowise-doc-drift-path) — every flag
+- [MCP_TOOLS.md](../agent/MCP_TOOLS.md) — the agent-facing surface
diff --git a/docs/layers/INTELLIGENCE_LAYERS.md b/docs/layers/INTELLIGENCE_LAYERS.md
index 77238c43d..bcf403fb2 100644
--- a/docs/layers/INTELLIGENCE_LAYERS.md
+++ b/docs/layers/INTELLIGENCE_LAYERS.md
@@ -194,7 +194,7 @@ your own repo six months later. This keeps it in the codebase.
## Code Health Intelligence
repowise scores **every file 1–10** on three co-equal signals (defect risk,
-maintainability, and performance risk) from a roster of **49 deterministic
+maintainability, and performance risk) from a roster of **51 deterministic
detectors**, of which only **26 are permitted to move the defect number**. Pure
static analysis over tree-sitter and git data, budgeted (and CI-tested) to
finish in **under 30 seconds on a 3,000-file repo**.
@@ -220,6 +220,11 @@ repowise health --refactoring-targets # ranked by impact / effort
repowise health --trend # snapshots + declining-health alerts
```
+The same layer also checks **documentation drift**: the claims your markdown
+makes about the tree (a path, a link, a heading, a command), resolved against
+the graph, with the refuted ones reported. No model, and it runs on every
+update. [`DOC_DRIFT.md`](DOC_DRIFT.md).
+
Full guide, the calibration story and the head-to-head against CodeScene:
[`CODE_HEALTH.md`](CODE_HEALTH.md).
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index c2af3a033..3ef4eb40f 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -959,7 +959,7 @@ repowise impacted-tests main..HEAD --format list | xargs pytest
### `repowise health [PATH]`
-Compute per-file code-health scores from 49 deterministic detectors (McCabe complexity, nesting, brain methods, LCOM4 cohesion, god classes, native clone detection, untested hotspots, coverage gradient, function/ownership/churn/change-entropy organizational risk, test-quality smells, and more). Zero LLM calls by default, pure Python over tree-sitter + git data. See [`docs/layers/CODE_HEALTH.md`](../layers/CODE_HEALTH.md) for the user guide and [`docs/architecture/code-health.md`](../architecture/code-health.md) for the internals.
+Compute per-file code-health scores from 51 deterministic detectors (McCabe complexity, nesting, brain methods, LCOM4 cohesion, god classes, native clone detection, untested hotspots, coverage gradient, function/ownership/churn/change-entropy organizational risk, test-quality smells, and more). Zero LLM calls by default, pure Python over tree-sitter + git data. See [`docs/layers/CODE_HEALTH.md`](../layers/CODE_HEALTH.md) for the user guide and [`docs/architecture/code-health.md`](../architecture/code-health.md) for the internals.
**Options:**
diff --git a/docs/reference/UPGRADING.md b/docs/reference/UPGRADING.md
index 3d428d554..80ee0a4ef 100644
--- a/docs/reference/UPGRADING.md
+++ b/docs/reference/UPGRADING.md
@@ -33,6 +33,20 @@ It is a recommendation, not a requirement. Nothing is wiped until you choose to
## Behaviour changes worth knowing about
+### 0.52.0: decision capture is stricter, and health re-scores once
+
+Three changes you may notice after upgrading to 0.52.0.
+
+**Transcript mining is off by default.** Decisions are no longer mined from coding-agent transcripts unless you ask for it. The lane was binding records to files the repository does not have, so it now stays quiet until you turn it on:
+
+```bash
+repowise decision source set session --on
+```
+
+**A decision needs a stated reason to be accepted.** `repowise decision confirm` refuses a record whose body only restates its own title. Existing records are untouched, but ids that used to pass may now be rejected; add a reason with `repowise decision add --rationale`, or re-record it.
+
+**Your first `update` re-scores the whole repository.** The health analyzer version moved from 11 to 21 over this cycle, because new test-quality markers, a per-language assertion vocabulary, a `.tsx` grammar fix and re-ranked history gates all change how a stored health number is computed. Rather than wait out the decay timer, the first update after upgrading re-scores every file, so it takes longer than usual. On a 171-file repository that was 10.2 seconds against a 5.8 second baseline, with the next update back to normal. Nothing needs re-indexing: the store format and parser schema are unchanged.
+
### `health-rules.json` globs now match like `.gitignore`
Per-path rules in `.repowise/health-rules.json` used to be matched with
diff --git a/packages/core/src/repowise/core/generation/editor_files/tool_table.py b/packages/core/src/repowise/core/generation/editor_files/tool_table.py
index 91a16bbad..0df1ead07 100644
--- a/packages/core/src/repowise/core/generation/editor_files/tool_table.py
+++ b/packages/core/src/repowise/core/generation/editor_files/tool_table.py
@@ -99,8 +99,9 @@ TOOL_TABLE_ROWS: dict[str, tuple[str, str]] = {
),
"get_health": (
"get_health(targets?, include?)",
- "Defect / maintainability / performance scores and findings. Self-check the "
- "files you touched before finishing.",
+ "Defect / maintainability / performance scores and findings, plus "
+ "documentation the code no longer supports. Self-check the files you "
+ "touched before finishing.",
),
"get_dead_code": (
"get_dead_code(tier?, min_confidence?, safe_only?)",
diff --git a/packages/core/src/repowise/core/upgrade/_data/CHANGELOG.md b/packages/core/src/repowise/core/upgrade/_data/CHANGELOG.md
index f30df82f1..c21ccb986 100644
--- a/packages/core/src/repowise/core/upgrade/_data/CHANGELOG.md
+++ b/packages/core/src/repowise/core/upgrade/_data/CHANGELOG.md
@@ -45,6 +45,7 @@ Code health can see test quality for the first time — a test that checks nothi
- **`timing_ms` is reported for every tool** (#2271), rather than for the ones someone had remembered to thread it through.
- **History-based health gates are ranked against the repository** (#2437, #2438). Six months is a fixed window, so a repository landing many commits a day accumulates more fix commits per file inside it than a quiet one; with an entry gate of one fix, `prior_defect` fired on 43.5% of the files here, and a signal that flags nearly half a tree is not locating anything. Co-change breadth is measured before truncation rather than by counting a list capped at 25 partners, where above the cap every file looks identical.
- **An agent is defined once** (#2394). The same agent was spelled four ways across four hand-maintained namespaces, and the savings domain had added a fifth and a sixth that agreed with the target registry only by hand.
+- Plugin: the `decision` command says that acceptance now requires a stated reason, documents `--kind agreement` and `--evidence-commit`, and stops claiming a fixed capture-source count.
### Fixed