# Documentation drift

repowise checks the paths, links, headings, commands and symbol names in your markdown against the real tree and reports any that no longer exist.

Your docs name files, link to headings, and tell readers to run commands.
repowise checks each of those references against the repository and
reports the ones the tree refutes. It runs on every `init` and `update`,
needs no model, and never edits your documents.

```bash
repowise doc-drift                          # everything the index found
repowise doc-drift --kind anchor            # just links to renamed headings
repowise doc-drift --min-confidence 0.9     # the ones safe to fix without looking
```

## What it checks

| Kind | The document says | It is a finding when |
|---|---|---|
| `path` | a file or directory exists | nothing is at that path |
| `link` | see another document | the target is gone |
| `anchor` | see a heading | the heading was renamed or removed |
| `command` | run `make x` or `npm run x` | the manifest no longer declares it |
| `symbol` | a function, class or method by name | it was defined when the line was written and is defined nowhere now |

A `symbol` finding needs proof from git: `git blame` finds the commit that
wrote the document line, and at that commit a source file defined exactly
that name. A backticked word the code never defined is not reported.

> **Note**
>
> A clean run does not mean your documentation is true. It means every
> reference repowise could resolve, resolved. It has no opinion on prose.

## Reading a finding

Each finding carries the line as written, the heading trail above it,
what was checked, and a confidence (stored from 0.4 up). When the tree says
where the reference went, it also suggests a replacement:

| Suggestion | When |
|---|---|
| Became a package | `src/cli.py` is gone and `src/cli/` exists |
| Renamed in git | git records the file moving, and the new path exists |
| Similar heading or target | one declared heading or `make` / `npm run` target is a close match |
| Renamed symbol | the defining file now defines one close name of the same kind |

A suggestion is evidence for you to check. It never raises a finding's
confidence.

## Keeping a reference on purpose

Mark it in the document, so the choice travels with the text:

```markdown
<!-- repowise-drift-ignore -->
Create `src/plugins/my_plugin.py` with the following contents.
```

The marker covers its own line and the next. Put
`<!-- repowise-drift-ignore-file -->` anywhere in a document to silence all
of it. Silenced references are still counted.

## In CI

`repowise doc-drift --check` reads the working tree with no index and
exits `1` on a finding at or above 0.7 confidence. Use a baseline or
`--since auto` on a repository that already has drift, and
`--fail-on-baseline-growth` to fail a change that adds entries to the
committed baseline instead of fixing the drift. Setup is on
[Gates in CI](https://docs.repowise.dev/ci), every flag on
[`repowise doc-drift`](https://docs.repowise.dev/cli/gates#repowise-doc-drift).

## Where else it shows up

- `get_health(include=["doc_drift"])` for an agent. See
  [`get_health`](https://docs.repowise.dev/mcp/get-health).
- `get_context(targets=["src/auth.py"], include=["doc_drift"])` answers the
  reverse question: which documents name this file, and whether they already
  drift. Ask before you move or rename something. See
  [`get_context`](https://docs.repowise.dev/mcp/get-context).
- The Code Health page in the [dashboard](https://docs.repowise.dev/dashboard).
- The VS Code extension's Problems panel, for Markdown files.