Devflow tdd enforcer

DevFlow TDD Enforcer

Purpose

Enforce Test-First Development (TDD) order by preventing users from marking implementation tasks complete before their corresponding test tasks.

Trigger: PreToolUse hook when editing devflow/requirements/**/TASKS.md

Enforcement Rule

Source: Extracted from planner agent's TDD mandate + Constitution Article VI

❌ BLOCKED Pattern (Violation)

- [x] **T010** [US1] Implement user registration endpoint
- [ ] **T011** [US1] Test user registration with valid data

Problem: Implementation marked done BEFORE test

Regex Pattern: \[x\].*Implementation.*\n.*\[ \].*Test

✅ CORRECT Pattern (TDD Sequence)

- [ ] **T010** [US1] Test user registration with valid data (write FAILING test)
- [ ] **T011** [US1] Implement user registration endpoint (make test PASS)

Or after completion:

- [x] **T010** [US1] Test user registration with valid data
- [x] **T011** [US1] Implement user registration endpoint

Blocking Message

When violation detected, PreToolUse hook returns exit code 2 (blocks file save):

⚠️ BLOCKED - TDD Violation Detected

📋 REQUIRED ACTION:
1. Re-order TASKS.md to follow TDD sequence
2. Mark test tasks [x] BEFORE implementation tasks
3. Review Constitution Article VI - Test-First Development

Reason: CC-DevFlow enforces TDD (Tests First → Implementation)
Source: planner agent mandate + Constitution Article VI
File: {file_path}

Current Issue:
  Line {N}: Implementation task marked complete
  Line {N+1}: Test task NOT marked complete

💡 SKIP: Add `@skip-tdd-check` comment or set SKIP_TDD_ENFORCER=1

Constitutional Basis

Article VI: Test-First Development

TDD MANDATE:
  - Write test FIRST (must fail)
  - Implement code SECOND (make test pass)
  - No implementation without corresponding test
  - Test coverage ≥80%

planner agent enforces

• Generates TASKS.md with correct TDD order
• Phase 2: All tests listed first
• Phase 3+: Each user story has Test task before Implementation task
• Inserts "⚠️ TEST VERIFICATION CHECKPOINT" between Phase 2 and Phase 3

devflow-tdd-enforcer guardrail prevents

• Users from manually reversing that order
• Implementation tasks marked complete before test tasks
• Real-time detection during file editing

Additional Violation Patterns

Pattern 2: Phase 3+ User Story TDD Order

# ❌ BLOCKED
- [x] **T020** [US2] Implement login endpoint
- [ ] **T021** [US2] Test login with valid credentials

# ✅ CORRECT
- [x] **T020** [US2] Test login with valid credentials
- [x] **T021** **T021** [US2] Implement login endpoint

Regex Pattern: \[x\].*\[US\d+\].*Implement.*\n.*\[ \].*\[US\d+\].*Test

Pattern 3: Implementation without Test

# ❌ BLOCKED (if no corresponding test found)
- [ ] **T030** [US3] Implement password reset endpoint
# (No T029 or T031 test task found)

# ✅ CORRECT
- [ ] **T029** [US3] Test password reset with valid email
- [ ] **T030** [US3] Implement password reset endpoint

Skip Conditions

Users can bypass TDD enforcer in specific scenarios:

1. Session Skip (One-time per session)

• Mechanism: sessionSkillUsed: true in skill-rules.json
• Behavior: Guardrail only triggers once per Claude session
• Use case: User acknowledged TDD violation, wants to continue

2. File Marker (Permanent skip for specific file)

• Marker: Add @skip-tdd-check comment anywhere in TASKS.md
• Example:

  <!-- @skip-tdd-check: Hotfix deployment, will add tests in follow-up -->
  

• Use case: Emergency hotfix, tests to be added later

3. Environment Variable (Temporary global skip)

• Variable: SKIP_TDD_ENFORCER=1
• Scope: Current terminal session
• Use case: Batch operations, automated scripts

Relationship with Other Components

mark-task-complete.sh (Script)

• Purpose: Marks tasks complete in正常 workflow (via /flow-dev)
• Validation: Batch validation at phase completion
• Timing: After task execution

devflow-tdd-enforcer (Guardrail)

• Purpose: Real-time prevention of manual TDD violations
• Validation: Per-edit, blocks save if violation detected
• Timing: During file editing (PreToolUse hook)

Relationship: Complementary (双重保险)

• Script ensures正常流程 follows TDD
• Guardrail prevents手动编辑 from breaking TDD

Constitution Article VI

• Defines: TDD philosophy and mandates
• Enforcement: planner agent (generation time) + devflow-tdd-enforcer (edit time)

Configuration

In .claude/skills/skill-rules.json:

{
  "devflow-tdd-enforcer": {
    "type": "guardrail",
    "enforcement": "block",
    "priority": "critical",
    "description": "Enforces TDD order, extracted from planner agent rules",
    "fileTriggers": {
      "pathPatterns": ["devflow/requirements/**/TASKS.md"],
      "contentPatterns": [
        "\\[x\\].*Implementation.*\\n.*\\[ \\].*Test",
        "\\[x\\].*\\[US\\d+\\].*Implement.*\\n.*\\[ \\].*\\[US\\d+\\].*Test"
      ]
    },
    "blockMessage": "⚠️ BLOCKED - TDD Violation\n\nTasks must follow TDD order:\n1. [ ] Test (write failing test)\n2. [ ] Implementation (make test pass)\n\n📋 ACTION: Re-order TASKS.md\nSource: planner agent mandate + Constitution Article VI\n\n💡 SKIP: @skip-tdd-check or SKIP_TDD_ENFORCER=1",
    "skipConditions": {
      "sessionSkillUsed": true,
      "fileMarkers": ["@skip-tdd-check"],
      "envOverride": "SKIP_TDD_ENFORCER"
    }
  }
}

Design Principle

This guardrail does NOT contain:

• ❌ Complete TDD methodology (that's in planner agent)
• ❌ Task generation logic (that's in planner agent)
• ❌ Full Constitution Article VI (that's in project-constitution.md)

This guardrail ONLY contains:

• ✅ Prohibition rule extraction (from planner agent)
• ✅ Real-time violation detection (content pattern matching)
• ✅ Blocking mechanism (PreToolUse hook, exit code 2)
• ✅ Links to source documentation

Rationale: Avoid duplication ("不重不漏" principle). planner agent owns TDD generation logic, guardrail owns real-time enforcement.