drift-review

Drift Review

Resolve open drift contracts: review the declared targets against what actually changed, fix staleness, record the ack, log a dogfood observation. Full system reference: docs/contribute/drift-contracts.md. The manifest is drift.toml at the repo root.

A contract is "open" when tracked files matching its triggers changed (in the git index) since the last recorded review — or the contract definition itself changed, or it never had an ack. The tool proves that a review happened; this skill's job is to make the review genuine. There is deliberately no bypass anywhere in the system — the legitimate escape is an honest "nothing to update" rationale, which is cheap and auditable.

Workflow

1. See what's open

make drift-plan            # all open contracts
make drift-plan CONTRACT=<id>   # one contract's full packet

Each packet gives you: the description, exactly which trigger files were added/removed/modified since the last ack, the review targets, the verify commands, the previous ack's rationale, and the exact ack command to run.

2. Review — this is the point, not a formality

Work from the trigger diff to the review targets:

• For each added/modified/removed trigger file, identify what a reader of the review targets could observe changing: new, renamed, or removed options, settings, defaults, commands, behaviors. Use git diff on the trigger files; the previous ack's rationale tells you what the last review already covered, so focus on what changed since.
• Grep the review targets for the changed names, settings, and symbols — then read the surrounding prose. A mention can be present but stale (wrong default, wrong behavior, incomplete), not just missing.
• Grep finds wrong mentions; it cannot find missing ones. A claim that quantifies — every, all, only, the sole exception, none, or any count — is a claim about a set, and it rots by omission: the symbol that falsified it appears nowhere in the sentence that is now false, so searching the target for what changed will never surface it. Read the targets for their quantified claims and re-derive each set from the code. (Same root as the no-hardcoded-counts rule — "the three helpers" and "the sole exception" go stale identically.)
• Verify each claim against the artifact it is about, never against another document. A claim about a test is checked by reading what the test executes — its calls, its parametrize lists — not its docstring; a claim about a module, by enumerating the module. A docstring, a sibling doc, or the previous ack is not evidence: prose drifts from the same edit that missed it, so two documents agreeing is agreement, not verification.
• Fix what's stale, following the repo's doc rules: docs describe current reality, no hardcoded counts, MkDocs conventions (blank line before lists). When the fix is to a quantified claim, prefer converting the construct over correcting the value — name the class ("the deck-reading helpers") rather than restating a count that will rot again.
• "Nothing to update" is a legitimate verdict — but only after you actually opened and read the review targets. If you didn't open them, you haven't reviewed.