Spec Check

Spec-Check - Drift Detection

Read-only verification that implementation aligns with specification. Detects coverage gaps, scope creep, and requirement drift.

When to run:

• At wave gates (integrated into /wave-gate sequence)
• Before /finalize
• On-demand during long implementations
• Manual: /spec-check

Not what this does: Check code quality, style, security (that's code-reviewer's job).

Integration with Wave-Gate

Spec-check runs as part of wave-gate sequence, between test verification and code review:

Wave N complete
    → verify test evidence
    → /spec-check (NEW)
    → spawn code reviewers
    → advance wave

CRITICAL findings from spec-check block wave advancement.

Process

1. Load Artifacts

# Find spec
SPEC=$(ls -t .claude/specs/*/spec.md | head -1)

# Find plan
PLAN=$(jq -r '.plan_file' .claude/state/active_task_graph.json)

# Get current wave tasks
WAVE=$(jq -r '.current_wave' .claude/state/active_task_graph.json)
jq -r ".tasks[] | select(.wave == $WAVE)" .claude/state/active_task_graph.json

2. Build Requirement Map

Extract from spec:

• FR-xxx (Functional Requirements)
• SC-xxx (Success Criteria)
• US-x acceptance scenarios

Build mapping:

FR-001 → {description, priority, related_scenarios}
FR-002 → {description, priority, related_scenarios}
SC-001 → {metric, threshold}
...

3. Build Implementation Map

From wave tasks and git diff:

# Files changed in current wave
BASE=$(git merge-base HEAD origin/main)
git diff --name-only $BASE..HEAD

Extract from code:

• Functions/classes created
• Tests written
• API endpoints added

4. Run Detection Passes

Pass 1: Coverage Gaps

Check every FR/SC has corresponding implementation:

Detection method:

• Parse task descriptions for requirement references (FR-xxx, SC-xxx)
• Check spec_anchors in task state
• Search code for requirement IDs in comments
• Match test names to acceptance scenarios

Pass 2: Scope Creep

Check for code that maps to no requirement:

Detection method:

• Compare created functions/endpoints to spec
• Check Out of Scope section for violations
• Flag code with no traceability to requirements

Pass 3: Terminology Drift

Check naming consistency:

Detection method:

• Extract key terms from spec (entities, actions)
• Search codebase for variants
• Flag mismatches

Pass 4: Acceptance Criteria Coverage

For each Given/When/Then in spec:

Detection method:

• Parse acceptance scenarios from spec
• Match to test descriptions/names
• Check test assertions align with "Then" clauses

Pass 5: Success Criteria Verifiability

For each SC-xxx:

Detection method:

• Check for performance tests
• Check for metric assertions
• Validate evidence in task state

Output Format

Console Output

## Spec-Check Report

**Spec:** .claude/specs/2025-01-29-user-auth/spec.md
**Wave:** 2
**Tasks Checked:** T3, T4, T5

### CRITICAL (2)

1. **Coverage Gap:** FR-003 (email validation) has no implementation
   - Requirement: "System MUST validate email format"
   - Expected in: T3 (auth service)
   - Found: No validation logic in auth service

2. **Scope Creep:** New /api/admin endpoint not in spec
   - File: src/routes/admin.ts
   - Not mapped to any FR-xxx
   - Not in Out of Scope (should be if intentional)

### HIGH (1)

1. **Acceptance Gap:** US1 error scenario has no test
   - Scenario: "Given invalid password, When submit, Then error shown"
   - Expected test: Login failure test
   - Found: Only happy path tested

### MEDIUM (2)

1. **Terminology Drift:** Spec "User" vs Code "Account"
2. **Missing Metric:** SC-002 (response time) not measured in tests

### Summary

| Severity | Count |
|----------|-------|
| CRITICAL | 2 |
| HIGH | 1 |
| MEDIUM | 2 |
| LOW | 0 |

**Verdict:** BLOCKED - 2 critical findings must be resolved

State File Update

Write findings to task state for wave-gate:

{
  "spec_check": {
    "wave": 2,
    "run_at": "2025-01-29T10:00:00Z",
    "critical_count": 2,
    "high_count": 1,
    "findings": [
      {
        "severity": "CRITICAL",
        "type": "coverage_gap",
        "requirement": "FR-003",
        "description": "email validation has no implementation",
        "task": "T3"
      }
    ],
    "verdict": "BLOCKED"
  }
}

Wave-Gate Integration

Blocking Logic

Wave advancement blocked if:

• spec_check.critical_count > 0

Wave advancement proceeds if:

• spec_check.critical_count == 0 (HIGH/MEDIUM are advisory)

Re-Check After Fixes

When critical issues fixed:

1. Re-run /spec-check
2. Updated findings replace previous
3. If critical_count == 0, wave can advance

Severity Definitions

Manual Invocation

/spec-check                    # Check current wave
/spec-check --full             # Check all waves
/spec-check --spec path/to/spec.md  # Use specific spec

Fixing Critical Findings

Coverage Gap

**Finding:** FR-003 has no implementation

**Fix options:**
1. Implement the requirement (spawn impl agent for affected task)
2. Defer requirement (move to Out of Scope with justification)
3. Update spec if requirement changed (requires re-approval)

Scope Creep

**Finding:** New endpoint not in spec

**Fix options:**
1. Add requirement to spec (FR-xxx) and re-run /specify
2. Remove code if truly out of scope
3. Document in Out of Scope as "added during implementation" with rationale

Constraints

• Read-only: NEVER modify code or spec
• Findings only: Report issues, don't fix them
• Spec is source of truth: Code must align to spec, not vice versa
• CRITICAL blocks waves: Non-negotiable
• Different from code review: Quality vs alignment are separate concerns