Spec Drift

Pack Availability Guard

Before telling the user to run a skill from another project-local pack, check .agents/project.json.enabled_packs. If the target pack is not enabled, recommend $pack install <pack> instead of the target skill. Global skills are always valid. Skills from this same pack are valid because the current skill is already running from that pack.

Spec Drift — Spec-to-Code Conformance Audit

Invoke as $spec-drift.

Checks that specs and codebase tell the same story. Extracts verifiable claims from spec documents, checks each against the actual implementation, and flags divergence. Complementary to $reconcile-research (doc-to-doc) and $expert-review (broad code review).

Prerequisites

At least one spec file must exist in specs/ (or specs/{app}/, docs/specifications/). If no specs exist, tell the user to run $research-roadmap first.

Process

0. App Scope Resolution (Monorepo Support)

1. If $ARGUMENTS specifies an app name matching a subdirectory of specs/, use it.
2. If specs/ contains subdirectories, list them and ask the user which app to target. If only one, use it automatically.
3. If no subdirectories exist, check docs/specifications/ as alternative. Otherwise proceed with flat structure.

1. Determine Mode & Inventory Specs

Parse $ARGUMENTS for mode (audit default, or fix) and scope (specific file or all). Scan spec directories for .md files, skipping non-spec files (README, index, changelog, mvp-gap, scale-audit, *-interview.md).

2. Pre-Scan & Extract Claims

1. Build a codebase summary: tech stack, key directories, routes, data models.
2. For each spec, extract verifiable claims across: routes/endpoints, data models, feature behaviors, config/env vars, UI flows, commands, pricing/limits, integration points.
3. Each claim records: source spec, section heading, direct quote, claim type.

3. Verify Claims & Detect Undocumented Code

For each claim, search the codebase and classify:

• Verified — code matches spec (cite file:line)
• Diverged — code exists but differs (spec quote + code quote)
• Unimplemented — spec describes it, code doesn't have it
• Removed — evidence of intentional removal

Then scan for significant undocumented code: routes, models, feature flags, and public APIs with no spec coverage. Only flag user-facing or public items.

4. Report Findings

Group by severity:

• Error — Diverged claims (spec contradicts code)
• Warning — Unimplemented or removed claims
• Info — Undocumented code that should have spec coverage

5. Fix Mode (if specified)

1. Present Errors with side-by-side spec vs code quotes. Ask: code right or spec right?
   • Code right → archive the existing spec, then update the canonical spec to match the implementation. Spec right → add concrete implementation fixes to tasks/todo.md.
2. Present Warnings — either archive then update the spec, add concrete work to tasks/todo.md, or add non-blocking condition-gated validation to tasks/record-todo.md.
3. Write specs/drift-report.md (or specs/{app}/drift-report.md) as audit trail.
4. Check downstream impact on research/journey-map.md, research/metrics.md, tasks/roadmap.md. If major, recommend $reconcile-research.

Deliverables

• Audit mode: Summary displayed directly — errors, warnings, info, verified count, and totals
• Fix mode: Same report plus specs/drift-report.md with resolved/deferred/remaining sections

Constraints

• Read-only by default. Only modify files in fix mode.
• Never auto-resolve Errors — always require user input.
• Every finding must cite spec quote + code reference.
• If uncertain, classify as Info, not Error.
• Respect monorepo structure with app-scoped paths.
• Do not make code changes — only update specs, tasks/todo.md, and tasks/record-todo.md; archive existing specs before replacement per the Archive-First Replacement Policy.

Default Shipping Contract

Follow the shared shipping contract convention in CLAUDE.md.