--- name: ad-drift description: Read-only drift audit — compare AGENTS.md, ARCHITECTURE.md, ADR statuses, feature specs in doc/specs/, and documentation discipline against what the code actually does. Outputs a drift list, never writes files. Use when the user wants to audit, review for drift, sanity-check, or report inconsistencies between the repo's docs and its code. summary: Read-only drift report comparing AGENTS.md / ARCHITECTURE.md / ADRs against the code. allowed-tools: Read, Glob, Grep, Bash --- # /ad-drift Read-only. Produces a drift list comparing the repo's operational docs against what the code actually does. Writes nothing — the user decides whether to fix the spec or the code. ## Step 1 — Decide what to audit If the user names an artifact (`AGENTS.md`, `ARCHITECTURE.md`, ADRs, specs), audit only that. Otherwise audit all categories below. ## Step 2 — Run checks ### `AGENTS.md` drift (if present) * Stack — does the listed stack match `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod` / equivalent? * Setup/build/test commands — do they match `package.json#scripts`, `Makefile`, or `pyproject.toml`? * Quality gates — do referenced hook configs exist (`.husky/`, `.pre-commit-config.yaml`, `.github/workflows/`)? * Repository layout — do referenced directories exist? * Pre-approved commands — anything in the list missing from the toolchain? ### `ARCHITECTURE.md` drift (if present) * Layers and boundaries — do the named directories exist? Sample 1–2 files per layer; are imports respecting the stated boundaries? * Patterns — sample one handler / one repository / one entry point. Do they follow the documented pattern? * No `## Active ADRs` section — ARCHITECTURE.md must not duplicate the `doc/adr/` directory index per ADR-0030 §2. ### ADR drift (if `doc/adr/` exists) * Numbering — gaps or duplicates in `doc/adr/NNNN-*.md`? * Status field — every ADR has one of `proposed | accepted | deprecated | superseded by ADR-NNNN`. * Superseded chains — every "superseded by ADR-NNNN" target exists. ### Spec drift (if `doc/specs/` exists) Structural integrity only — does **not** deep-audit spec text against shipped code (deferred per ADR-0011 Consequences). * Numbering — gaps or duplicates in `doc/specs/NNNN-*.md`? * Status field — every spec has one of `draft | accepted | shipped | superseded by SPEC-NNNN`. * Superseded chains — every "superseded by SPEC-NNNN" target exists. * Reciprocity — every task under `doc/tasks/NNNN-*.md` whose `Spec ref` field is non-empty points to a spec that exists. And every spec with `Status: accepted` or `shipped` has at least one entry in its `Related → Tasks` list (an accepted spec with no implementing task is a smell). * No checkbox UI — per ADR-0030 §1, Spec is decision-record (not tracking). Functional Requirements / Non-functional Requirements / Success Criteria sections must use plain bullets, not `- [ ]` checkboxes; implementation tracking lives in per-Spec tasks. * Status / task aggregate alignment — when every task that references a spec is `done`, the spec's `Status` should be `shipped`. A spec with all tasks done but `Status: accepted` is drift between work-unit completion and feature-level claim. ### Documentation discipline drift (`WORKFLOW.md` §2 / ADR-0008) Audit narrative documents — `README.md`, `AGENTS.md` / `CLAUDE.md`, `ARCHITECTURE.md`, `DESIGN.md`, and prose pages under `doc/` that are not lifecycle-managed artifacts under `doc/product/`, `doc/specs/`, `doc/adr/`, or `doc/tasks/`: * Emoji — any present? Rule 3 forbids emoji anywhere (docs, code, comments, commits, skill outputs). * Dates / version stamps / `DRAFT` markers / changelog blocks in narrative documents — Rule 2 forbids these. Lifecycle-managed artifacts under `doc/product/`, `doc/specs/`, `doc/adr/`, and `doc/tasks/` are exempt. * Business context first — does the first paragraph answer *why* the document exists, before *what* and *how*? Rule 4. * Scope duplication — does the document copy material that is canonically owned by another file (`AGENTS.md` repeating `ARCHITECTURE.md` patterns; `README.md` re-stating ADR rationale)? Rule 5 requires linking, not copying. * Speculation — phrases like "we might", "in the future", "could be added", or roadmaps without an ADR / task reference. Rule 1 forbids unfounded plans. Source code (sample, not exhaustive — flag findings, not every match): * Orphan `TODO` / `FIXME` — Rule 7. A reference to a GitHub Issue or a `doc/tasks/NNNN-*.md` task file makes it not orphan. * Commented-out code blocks — Rule 7. Removed code lives in git history. ### Single-responsibility drift (ADR-0030) Per WORKFLOW §2 rules #9–#12, definition-layer documents do not take on tracking or duplicate other layers' indices, and `WORKFLOW.md` stays universal: * **Definition-layer tracking UI** (Rule #9) — grep `^- \[ \]\|^- \[x\]` inside `AGENTS.md`, `WORKFLOW.md`, `ARCHITECTURE.md`, `GUIDELINES.md`, `CONTEXT.md`, `doc/product/*.md`. Findings: definition documents must not carry per-item checkbox UI. Exception: fenced code blocks showing template examples (e.g., PR-body shape) are illustrative, not pillar tracking. * **Directory-as-index duplication** (Rule #10) — flag sections that re-state another layer's index. Concrete patterns: `## Active ADRs` inside `ARCHITECTURE.md` or `AGENTS.md`; multi-bullet `## Architectural Principles` digests that paraphrase each ADR; PRD `## Related → ADRs` bullet lists that enumerate the kit's ADR ledger. * **Kit-state in `WORKFLOW.md`** (Rule #12) — grep `ADR-[0-9]\{4\}` in `WORKFLOW.md`. Universal philosophy must not cite kit-specific ADR numbers (downstream installs receive `WORKFLOW.md` without `doc/adr/`). Literature citations (named books / papers) and generic `doc/adr/` directory references are allowed. * **Cross-references that are decoration** (Rule #11) — sample inline ADR refs (`per ADR-NNNN`) in narrative documents and apply the load-bearing test: if you delete the reference and the surrounding statement still stands, the reference was decoration; flag it. Judgment-call; surface as findings, not as automated reject. ## Step 3 — Output One line per finding, formatted: ``` [file or section]: spec says X, code says Y. Suggested resolution: change spec / change code / discuss. ``` Group by artifact. If a category has no drift, print one line: `AGENTS.md — no drift.` etc. If an audited artifact does not exist, say so explicitly rather than reporting zero findings. The Documentation discipline drift category groups its own findings under `Documentation discipline — : ...`. If something the user says contradicts what the code shows, surface the conflict. Don't silently trust the user; don't silently trust the code. ## Output contract A drift list, no file written. Read-only operation. Empty result is reported explicitly ("no drift found across audited artifacts"), not silently. Missing artifacts are flagged, not skipped. ## Next - Address each finding with one of the three resolutions named in the format ("change spec / change code / discuss"). - For findings that require implementation: `/ad-task` to scaffold the fix. - For workflow drift (where am I, what's stuck): `/ad-next`. - For kit-version drift (state file behind current kit): `agentic update`.