edercnj/x-detect-spec-drift

Global Output Policy

• Language: English ONLY.
• Tone: Technical, Direct, and Concise.
• Efficiency: Remove all conversational fillers and greetings to save tokens.

Skill: Spec Drift Check

Purpose

Compares story specifications (data contracts, endpoints, Gherkin scenarios) against implemented code to detect drift. Operates in two modes:

• Standalone mode (default): Full report with all check categories
• Inline mode: Compact output for TDD loop integration

Triggers

• /x-detect-spec-drift STORY-ID — standalone mode (full report)
• /x-detect-spec-drift STORY-ID --mode inline — inline mode (compact output)

Parameters

| Parameter | Type | Default | Values | Description | |-----------|------|---------|--------|-------------| | STORY-ID | String | required | story identifier | Story to check for drift | | --mode | String | standalone | standalone, inline | Output mode |

Mode Selection

| Mode | When to Use | Output | |------|-------------|--------| | standalone | Manual invocation before PR | Full itemized report | | inline | Automated call in x-implement-story Phase 2 | Single-line compact summary |

Workflow

Standalone Mode

1. PARSE    -> Read story file, extract data contracts + endpoints + Gherkin
2. SCAN     -> Search source code for matching fields, endpoints, tests
3. CHECK    -> Compare spec vs code, classify drift (PASS/WARN/FAIL)
4. REPORT   -> Generate itemized report with severity

Step 1 — Parse Story

Read the story markdown file and extract:

1. Data Contracts (Section 5): field name, type, mandatory (M/O)
2. Endpoints: HTTP method + path (e.g., POST /v1/payments)
3. Gherkin Scenarios (Section 7): IDs @GK-N and titles
4. Constitution reference: Check if CONSTITUTION.md exists in project root

Step 2 — Scan Source Code

For each extracted item, search the source tree:

• Fields: Search DTOs, Records, data classes for field name + type match
• Endpoints: Search controllers/handlers for route annotations matching method + path
• Gherkin Scenarios: Search test files for acceptance test references to @GK-N
• Constitution: If present, validate naming conventions against source

Step 3 — Classify Drift

| Check Type | Severity | Condition | |-----------|----------|-----------| | Field Missing (M) | FAIL | Mandatory field from data contract not found in any DTO/Record | | Field Missing (O) | WARN | Optional field absent from code | | Field Type Mismatch | WARN | Field found but type differs from spec | | Endpoint Missing | FAIL | Declared endpoint not found in any controller | | Scenario Uncovered | WARN | @GK-N without corresponding acceptance test | | Naming Violation | WARN | CONSTITUTION.md naming convention violated |

Step 4 — Report

Output follows itemized format with severity:

=== Spec Drift Check — STORY-XXXX-YYYY ===
Data Contracts:
  PASS  FieldName (Type, M) -> found in ClassName
  FAIL  FieldName (Type, M) -> NOT FOUND
  WARN  FieldName (Type, O) -> field absent (optional)
Endpoints:
  PASS  POST /path -> ControllerClass.methodName()
  FAIL  GET /path -> NOT FOUND in any controller
Gherkin Coverage:
  PASS  @GK-1 "title" -> AT-1 found (TestClass)
  WARN  @GK-3 "title" -> no AT found
Constitution Compliance:
  PASS  No violations detected
Summary: N FAIL, M WARN — DRIFT DETECTED / NO DRIFT

Exit Code

• 0: No FAIL results (only PASS and WARN)
• Non-zero: At least one FAIL detected

Inline Mode (x-implement-story TDD Loop Integration)

Provides compact, non-blocking drift checks after each RED-GREEN-REFACTOR cycle in x-implement-story Phase 2. Designed for automated integration — not manual invocation.

Scope Restrictions

Inline mode performs a subset of standalone checks:

| Check | Inline Mode | Standalone Mode | |-------|------------|-----------------| | Data Contract fields (M) | Yes | Yes | | Data Contract fields (O) | Yes | Yes | | Field Type Mismatch | Yes | Yes | | Endpoint Missing | Yes | Yes | | Gherkin Coverage | No — reserved for standalone | Yes | | Constitution Compliance | No — reserved for standalone | Yes |

Compact Output Format

For non-critical results (PASS and WARN only):

Drift Check (inline): N PASS, M WARN — details of first warning

For critical drift (at least one FAIL):

Drift Check (inline): CRITICAL — FieldName (Type, M) NOT FOUND in DTO
   Continue TDD loop despite critical drift? (y/n)

Non-Blocking Behavior

• WARN results are displayed but do not interrupt the TDD loop. The non-blocking nature ensures development flow continues.
• FAIL results (critical drift) pause the loop with a confirmation prompt
• If the developer confirms: loop continues with FAIL logged
• If the developer denies: loop pauses for correction

TDD Loop Integration Point

Called automatically by x-implement-story after each TDD cycle:

Phase 2 TDD Loop:
  2.1 RED   — write failing test
  2.2 GREEN — make test pass
  2.3 REFACTOR — improve design
  2.4 DRIFT CHECK (inline) — verify spec alignment
  2.5 COMMIT — atomic TDD commit

InlineDriftCheckConfig

| Field | Type | Default | Description | |-------|------|---------|-------------| | enabled | boolean | true | Activate inline drift check (auto-enabled when story has data contract) | | blockOnCritical | boolean | true | Pause TDD loop on critical FAIL |

InlineDriftResult

| Field | Type | Description | |-------|------|-------------| | passCount | int | Total PASS checks | | warnCount | int | Total WARN checks | | failCount | int | Total critical FAIL checks | | summary | String | Compact single-line message | | criticalDetails | List | Details of FAIL items (empty if none) |

Decision Logic

if story has no data contract:
    skip inline check entirely
    return

run data contract field checks (M and O)
run endpoint checks

if failCount > 0 and blockOnCritical:
    emit CRITICAL message
    prompt for confirmation
else:
    emit summary message
    continue TDD loop

Error Handling

| Scenario | Action | |----------|--------| | Story file not found | Abort with "Story file not found: {path}" | | No data contract in story | Standalone: report "No data contract defined" / Inline: skip silently | | Source root not accessible | Abort with "Source root not accessible: {path}" | | Malformed data contract | WARN with "Unable to parse data contract field: {line}" |

Integration Notes

| Skill | Relationship | Context | |-------|-------------|---------| | x-implement-story | Called by | Invoked during Phase 2 TDD loop for inline drift detection | | x-implement-task | Complements | Drift check validates that implementation matches story spec | | x-review-pr | Complements | Standalone drift check provides pre-PR validation of spec alignment |