Add `doc-drift` skill: find docs that no longer match the code by running the code

[thisguymartin]

Problem

maintain-verification-skill keeps one document honest: the project's verification skill and feature map. Every other document rots the same way and nothing checks it: README install steps, CLAUDE.md / AGENTS.md rules, runbooks, API docs, config references, the docs/ tree.

Stale docs are worse for agents than for humans. A person skims and doubts; an agent reads "run make test" and runs it. In this repo, docs/USAGE.md and docs/LANES.md carry prices, env var names, and CLI flags that all drift as providers change.

Proposed skill

Skill	Use it when
doc-drift	You want every checkable claim in the project's docs (commands, flags, paths, env vars, defaults, prices, behaviors) tested against the real code or product, and the stale ones fixed or deleted in one proven PR.

Flow: inventory claims -> partition by doc -> parallel readers extract checkable claims -> one live session checks them -> fix or delete -> one PR.

1. Scope. Default: README, CLAUDE.md/AGENTS.md, docs/**, and doc comments on public entry points. The user can narrow to one file.
2. Extract claims. One read-only worker per document (swarm partition). Each returns a list of checkable claims with a check method: command (run it), path (exists?), env (read by code?), flag (parser accepts it?), default (matches source?), behavior (verification-skill scenario), external (URL or price; note the date). Prose opinions are skipped; only claims that can be wrong get listed.
3. Check. One live session runs the checks in a scratch worktree. Commands actually run. Flags are actually passed. External claims get a fetch and the date recorded. Each claim: PASS, DRIFT (with the observed truth), or UNCHECKABLE (say why).
4. Fix. For each DRIFT: correct the doc to the observed truth, or delete the claim when the feature is gone. Edit docs only; never product code. If the code looks wrong rather than the doc, file it as a finding, don't fix it here (same rule as maintain-verification-skill).
5. Ship. One PR, one commit per document, a table of claims checked / drifted / fixed in the PR body. technical-writing for tone. unslop before opening.

Outcome names mirror maintain-verification-skill: clean, changed, blocked.

Real-world use cases

1. This repo. docs/LANES.md says "Prices (verified 2026-09-25)". docs/USAGE.md lists PSTACK_FLEX_<PROVIDER>_CONFIG_DIR and exit codes 69 and 77. A doc-drift run re-fetches the price pages, checks that runner/flex-providers.ts reads exactly those env var names, and runs the CLI to confirm those exit codes. Anything off becomes a fix; the price date gets bumped only if the prices were actually re-checked.

2. Onboarding doc that lies. A team's README says npm run dev starts on port 3000 and cp .env.example .env is enough. A new hire (or intake's grounding pass) loses an hour because the port moved to 5173 and .env.example is missing two required keys. Doc-drift runs the command, reads the port from the log, diffs .env.example against the config loader's required keys, and fixes both lines.

3. Runbook after a refactor. An ops runbook references scripts/rotate-keys.sh and a --dry-run flag. The script was moved to a Go subcommand last quarter. Doc-drift marks the path claim DRIFT (missing), finds the replacement via how, and rewrites the step. The flag claim is checked against the actual Cobra command.

4. CLAUDE.md rules that reference dead tooling. "Always run bun run lint:strict" but the script was renamed. Every agent session has been running a failing command and moving on. Doc-drift catches it because it runs the command.

What already exists and how this differs

• maintain-verification-skill: same loop, one document. Doc-drift is the same discipline for the rest of the docs; it should share the source-wave / live-session structure rather than reinvent it.
• technical-writing: how to write. Doc-drift decides what's wrong.
• unslop: applied to the output.
• how: used to find where a moved thing went.

Guardrails

• Docs only. Product code is never edited; code bugs become findings.
• Claims are proven by running, not by reading. A claim checked only by source inspection is marked as such.
• External fetches record the date; nothing is marked "verified" without one.
• No implicit timeout on the live session. No fallback lanes.

Acceptance

• plugins/pstack/skills/doc-drift/SKILL.md, shared tree, with the claim-type table and PR body format.
• README row and docs/reference.md entry.
• Bun tests, strict typecheck, static invariants, plugin validation pass.
• Live test on the installed candidate in each affected harness: run doc-drift on this repo's docs/USAGE.md with one seeded stale claim, confirm it is found by running the command and fixed in a PR. Record installed version, surface, action, observed result in the PR.