doc-freshness-reverse-lint

Doc Freshness Reverse-Lint

Problem

Huiyan's project docs under docs/{research,decisions,findings,runbooks}/ contain normative guidance. When she later corrects that guidance in ~/.claude/lessons.md or a feedback_*.md entry, the original project docs stay stale. Future Claude sessions read them as authoritative and repeat the retracted advice.

Real example: the-causal-impact-repo/docs/research/pre_period_length_methodology.md:92,98 referenced "sorting by p-value" after the user had already decided that approach was wrong.

And a second shape the grep above cannot see (added v1.3.0). A rule is not always contradicted — sometimes it is retired, and the docs that carried it keep a scoped survivor: "X is retired — but it still applies if you are a Y." That reads as current guidance, and it is dead the moment no Y exists.

Real example (DoodleRun, 2026-08-04): "no deploys by agents" was retired across four live briefs, and every retirement kept "a cloud session still cannot" as a live branch — after cloud sessions had stopped existing. The next reader would have paused to work out which kind of session it was instead of just deploying. The retirement was correct; the surviving condition was the defect. The owner caught it by hand, one turn after the retirement shipped.

Mechanisms

1. Reverse-lint (primary, event-driven)

Runs when a negation rule is added to a memory file. Extracts the "don't X" phrase, greps project docs, lists matches. Does NOT edit.

1b. Dead-branch detection (v1.3.0, runs with the reverse-lint)

Same trigger, different question. Where mechanism 1 asks "does any doc still assert the thing you just forbade?", this asks "does any doc still carry the CONDITION of a rule you just retired?"

THREE explicit signals, ANDed — a scoped survivor is often perfectly legitimate, and only a human knows whether the branch can still fire:

1. a retirement trigger in the memory file (retired, superseded, no longer applies, is dead, …);
2. a quoted subject within 160 chars either side of it — retirement prose nearly always quotes the rule it retires ("...", '...', `...`, **...**), and the quote must be ≥ 2 tokens and not a path or filename;
3. a doc paragraph containing that subject with a surviving-conditional marker after it (still cannot, only applies, unless you, except when, if you are a, remains true for, …).