Your document is a map. The repository is the ground.

An out-of-date README confuses a person, who notices and asks. An out-of-date CLAUDE.md hands the agent a false premise that it executes with confidence: it runs a script that no longer exists, edits a file that moved, follows an abandoned convention.

The cost is not confusion, it is incorrect work with no error signal.

Linters check your code. Nothing checks the document you wrote about your code.

Unlike code, these files have no compiler, no tests, no linter. They are the one part of the repo where lying has no mechanical consequence.

SpecimenAGENTS.md, with revision overprint

1# Contributing

2

3 The entry point is ~~src/util/date.ts~~. src/helpers/date.ts

4

5 See ~~src/cli.ts~~ for the flag table. no single candidate, not rewritten

6

7Run pnpm test before pushing.

Struck in overprint: a claim the ground contradicts. Written beneath it: the correction, only when exactly one candidate clears 0.8 confidence.

Four checks. Each answers a question the document already claimed to know.

path/missing Every path a context file claims exists, verified against the repo index. The check that pays for the project: the paths are what an agent acts on. fixable
script/missing npm/pnpm/yarn/bun run, deno task and make, against the nearest package.json, Makefile or deno.json. No manifest anywhere means silence. fixable
link/broken A Markdown link to an anchor no heading in the target document produces. Suggests a near heading. never fixable
frontmatter/invalid A frontmatter block that is not valid YAML. What a field holds is the author's business; only the block failing to parse is reported. never fixable
skill/frontmatter A SKILL.md names itself something other than its directory — the folder was renamed and the frontmatter did not follow. Not a format validator: a name in snake_case or a four-word description are real problems and none of them are drift, so this does not report them. fixable

Turning one off

--skip link/broken turns that check off everywhere
--only path keeps only that family, and a prefix matches, so --only path and --only path/missing both work
checks: in the config file makes either permanent, or demotes a check to a warning instead of silencing it
a directive in the document silences one line rather than a whole check, and the syntax is with the first run
ignore: in the config drops a whole document — a skill somebody else wrote, a vendored file you do not maintain — which is the one thing sources cannot do

A selection that leaves no check enabled is refused.

What it never does

judge whether the content is good. It checks whether a claim is true, and those are different questions with different answers
lint your Markdown. Style, formatting and spelling belong to a tool you already have
rewrite prose. --fix touches the mechanically verifiable fragment of a line and nothing around it
put a model on the main path. That is out of scope by design, not unimplemented

One false positive costs more than ten false negatives.

A linter that shouts too much gets uninstalled on first use. So driftwatch stays silent when it is unsure, and every discard rule in the extractor carries a comment naming the false positive it prevents. This is the measurement, over context files their authors wrote without knowing driftwatch exists.

1901 context files96 repositories pinned to a commitnine languages

nothing found findings, none false carries a false positive One mark is one repository. Point at one, or tab in and use the arrow keys.

A lit mark is a repository carrying at least one false positive — 15 of the 96, which is the figure below read the other way. An outlined mark produced findings and none of them false: 216 context files carry 337 findings between them, and 32 are true drift the maintainers had not noticed. 289 findings in the nine noisiest repositories are unread, and cannot move the figure: each of those repositories already carries a false positive, so it is already counted.

Repositories with zero false positives: 81/ 96; 84.4%, and the project's own bar is 90%. Said here rather than quietly: the bar is not met, and it moved further away when the corpus stopped being built out of small repositories
Same, over the validation group alone: 29/ 32; 90.6%. Added after the heuristics were frozen, and never used to derive one. Unchanged by the thirty repositories added in round thirty-one, which are all calibration
Findings ruled, of 337: 4932 true, 17 false; The rest sit in repositories already settled by a false positive, which is all condition 6 needs since ADR-0015 withdrew the three that counted them
Edits --fix would apply across all 96: 6; and every one is correct, checked by hand at the level of the edit and not only of the finding

What it refuses to report

a path inside a URL, a glob, or a placeholder: <name>, {{path}}, $VAR, [id], EventNameHere
a bare word with no slash, or a single-segment directory like feat/
a path whose shape exists somewhere in the repo, because the document is probably writing relative to a directory its prose already named
anything git ignores, or that lands in a generated output directory
a path the line already hedges: "such as", "if exists", "(optional)", "is generated by", or a line opening with "Create ..."
a path inside another assistant's configuration root, in a repo that does not use that assistant
a host with the scheme left off, linkedin.com/in/, or a Windows drive letter, D:/Projects/… — both name somewhere that is not this repository
a path the writer abbreviated, core/.../sql/, or a variable with its sigil missing, SKILL_DIR/wiki/
anything under .git/, which no repository versions

How it was measured

Thirty-three rounds of hand adjudication, including the four where a condition broke and the two where the corpus caught a regression that reading the diff would not have. A repository is settled by its first false positive, so not every finding is read — and a test refuses to count one clean on evidence nobody looked at.

Ten false-positive classes have been named, each with a fixture and a test naming the repository and line it came from. Not every class becomes a rule: of the five largest, three produced none — one because its vocabulary is the vocabulary of real directory names, one because its marker says nothing about absence, one because its signal is not on disk. Every rule that did ship was measured over both corpora before being kept, and not one has ever removed a true positive.

The corpus does not run in CI, because the verdict requires a person. CI can detect that a snapshot changed; it cannot rule on whether the change is an improvement, and that ruling is the measurement.

The whole argument, with the rounds where they broke →

Most first runs find nothing. That is an answer, not a failure.

Sixty-seven of the ninety-six repositories in the corpus report nothing at all. A tool built to stay quiet when it is unsure is quiet most of the time, so a first run has three possible endings and only one of them reports drift.

```
✓ 14 files · no drift · 210ms
```
It read your documents and they were true

Fourteen context files, every claim in them checked against the repository. Exit code 0.

The file count is the proof that it looked at all. --json carries summary.claims beside it: how many individual assertions were verified. That is the only thing that tells nothing to find apart from nothing found. In CI, where nobody reads the output of a green run, it is the only number worth asserting on.
```
✓ 0 files · no drift · 12ms
```
It found nothing to read

Zero files does not mean your documents are clean. It means driftwatch found none to read, and it is the one result worth checking.

Discovery runs off git ls-files, so .gitignore is respected for free, and anything it hides is invisible to driftwatch too. A repository with no .git falls back to a glob walk.

agents-md

AGENTS.md, at any depth

claude-md

CLAUDE.md, CLAUDE.local.md

skill

<root>/skills/**/SKILL.md, where <root> is .claude, .agents, .cursor, .codex, .github or .opencode. There is no single one, and .claude/ is not the busiest: npx skills add writes to .agents/ by default.

subagent

.claude/agents/*.md

command

.claude/commands/**/*.md

cursor-rule

.cursorrules, .cursor/rules/**/*.mdc

copilot

.github/copilot-instructions.md

Anything else, name it yourself: driftwatch docs/ AGENTS.md audits only those paths, and a sources: key in the config makes it permanent.
```
AGENTS.md
  ✗ 3  src/util/date.ts  path does not exist  → src/helpers/date.ts?
  ✗ 5  src/cli.ts        path does not exist

1 file · 2 problems (2 errors) · 59ms
1 fixable with --fix
```
It found drift

A claim in your own repository that an agent would have believed, on the line that makes it. Exit code 1.

file:line is clickable in a modern terminal, so the fastest next move is to open the line and read what it claims. The arrow is a suggestion, and --fix --dry-run prints the exact rewrite before anything is written to disk.

If it is wrong about one

It will happen: six of the corpus's twenty-six findings are false. The recovery is a comment in the document itself, next to the claim it covers.

<!-- driftwatch-ignore-next-line -->
`src/planned/feature.ts` does not exist yet, it is the plan

<!-- driftwatch-ignore path/missing -->
<!-- driftwatch-ignore-file -->

With no id it silences every check on that line; with an id, only that one. Directives apply to findings rather than to claims, so an id you misspell silences nothing and the finding still shows up.

Then stop running it by hand

The first run tells you whether your documents are true today. Keeping them true is the part that has to happen on every change, which is what CI is for.

With --fix the exit code describes what is left, so a repository whose only error was autofixable exits 0. Code 2 is reserved for driftwatch itself failing (bad config, a path that does not exist, a crash) and never means drift.

Put it on the diff instead →

An autofix never guesses.

A wrong fix is not noise, it is a document that now points confidently at the wrong file, and the next agent will believe it.

So --fix applies a correction only when there is exactly one candidate above 0.8 confidence. It replaces the claim and nothing around it. And it refuses outright to rewrite a relative path in a document that is not at the repo root.

The whole list of what it will not touch, and why →

Terminal

$ driftwatch --fix --dry-run   # what it would change
$ driftwatch --fix             # change it

Try both in the field book above. It prints the real output.

Every stale claim becomes an annotation on the diff, on the line that makes it.

.github/workflows/ci.yml

- uses: actions/checkout@v7
- uses: abr4xas/driftwatch@v1.1.0

fail-on-drift: false makes it advisory. sarif: true writes a file for Code Scanning.

What the step accepts

paths Paths to audit, space separated. Empty means the whole repository.
only / skip Run only these checks, or everything except them. A prefix works: path.
format pretty | json | github | sarif. Annotations are the reason to run this in CI.
sarif Write a SARIF file and expose its path as an output.
fail-on-drift Whether drift fails the job, or only annotates it.
working-directory Where to run. Defaults to the workspace root.

Four formats, one set of findings

pretty: for a person at a terminal. The only one with a human as its consumer, and the only one that may change freely between versions.
--json: a stable contract. Breaking changes only on a major; version is what you branch on, and it is 1.
--github: one native annotation per finding and nothing else. A run with no findings emits nothing at all, not even a blank line.
--sarif: SARIF 2.1.0 for Code Scanning, carrying one rule per check that actually ran.

stdout is the report, stderr is everything else, and the exit code does not depend on the format.

One command with nothing after it, and a config file of two keys.

on the command line

driftwatch                       # the whole repo
driftwatch docs/ AGENTS.md       # only these paths
driftwatch --only path/missing   # only this check
driftwatch --skip link/broken    # everything but this one
driftwatch --strict              # warnings fail the build too
driftwatch --fix --dry-run       # what it would rewrite
driftwatch --json                # the machine-readable contract
driftwatch --init                # write a commented config

Exit 0 clean, 1 drift, 2 the tool could not run — a bad config, a path that does not exist. A crash never looks like a clean run.

driftwatch.config.yaml

# documents you did not write
ignore:
  - '.claude/skills/vendored/**'
  - 'third_party/**'

checks:
  'link/broken': 'warning'

A repository carries documents it did not write: an installed skill, a vendored AGENTS.md, a template's scaffold. They name paths in the project they came from, and reporting those is the check being asked the wrong question.

For a document you do maintain, silence one line with a directive instead. A directive for a document you own, ignore for one you do not — editing somebody else's skill to quiet your linter loses the edit the next time they ship it.