phase-enforcement

What this skill does

# Phase Completion Enforcement

**Version:** 1.0.0
**Purpose:** Mechanical enforcement of phase completion requirements for /dev:feature
**Status:** Production Ready

## Overview

This skill provides **mechanical enforcement** (not just prompt-based instructions) for the 8-phase feature development workflow. It prevents:

1. **Claiming completion without proof** - Artifacts must exist
2. **Skipping documentation** - Required files per phase
3. **Ignoring validation criteria** - Phase 1 criteria must map to Phase 7 results
4. **Bypassing retry logic** - Outer loop enforced with state tracking
5. **Shipping without tests** - Phase 6 requires test files
6. **Faking completion when blocked** - Graceful degradation with honest status
7. **Hiding actual results** - Show-your-work requirement
8. **Missing automated checks** - Checkpoint verification at boundaries

## Enforcement Components

### 1. Phase Completion Validator

**Script:** `scripts/phase-completion-validator.js`

**How it works:**
- Runs as PreToolUse hook on TaskUpdate
- Detects phase from task subject (e.g., "Phase 3: Planning")
- Checks required artifacts exist for that phase
- Blocks completion if artifacts missing or empty

**Required Artifacts per Phase:**

| Phase | Required Artifacts | Custom Checks |
|-------|-------------------|---------------|
| 1 | requirements.md, validation-criteria.md, iteration-config.json | Config has required fields |
| 3 | architecture.md | Plan reviews exist |
| 4 | implementation-log.md | Git changes detected |
| 5 | reviews/code-review/consolidated.md | Has PASS/FAIL verdict |
| 6 | tests/test-plan.md | Test files created |
| 7 | validation/result.md | Has PASS/FAIL status + evidence |
| 8 | report.md | Phase 7 PASSED |

**Usage in orchestrator:**

```markdown
Before marking any phase complete:

1. Run checkpoint verification:
   ```bash
   ${PLUGIN_PATH}/scripts/checkpoint-verifier.sh phase{N} ${SESSION_PATH}
   ```

2. If check passes, mark task complete:
   ```
   TaskUpdate(taskId: X, status: "completed")
   ```

3. If check fails, DO NOT mark complete. Fix missing artifacts first.
```

---

### 2. Outer Loop Enforcer

**Script:** `scripts/outer-loop-enforcer.js`

**How it works:**
- Tracks iteration state in session-meta.json
- Blocks Phase 8 unless Phase 7 PASSED
- Detects regression (score getting worse)
- Handles escalation when max iterations reached

**Commands:**

```bash
# Start new iteration (call before Phase 3)
node outer-loop-enforcer.js start-iteration ${SESSION_PATH}

# Record Phase 7 result
node outer-loop-enforcer.js record-result ${SESSION_PATH} PASS "All checks passed" 95

# Check if Phase 8 can proceed
node outer-loop-enforcer.js check-can-complete ${SESSION_PATH}

# Get current status
node outer-loop-enforcer.js get-status ${SESSION_PATH}
```

**Session state tracking:**

```json
{
  "outerLoop": {
    "currentIteration": 2,
    "maxIterations": 3,
    "mode": "limited",
    "phase7Results": [
      {"iteration": 1, "status": "FAIL", "reason": "Button color mismatch", "score": 78},
      {"iteration": 2, "status": "PASS", "reason": "All checks passed", "score": 94}
    ]
  }
}
```

**Usage in orchestrator:**

```markdown
OUTER LOOP: Before starting Phase 3

1. Start iteration:
   ```bash
   node ${PLUGIN_PATH}/scripts/outer-loop-enforcer.js start-iteration ${SESSION_PATH}
   ```

2. Check exit code:
   - 0: Proceed with iteration
   - 2: Max iterations reached, escalate to user

OUTER LOOP: After Phase 7 completes

1. Record result:
   ```bash
   node ${PLUGIN_PATH}/scripts/outer-loop-enforcer.js record-result ${SESSION_PATH} <PASS|FAIL> "reason" [score]
   ```

2. If PASS: Proceed to Phase 8
3. If FAIL: Loop back to Phase 3 (start-iteration will be called again)

OUTER LOOP: Before Phase 8

1. Verify Phase 7 passed:
   ```bash
   node ${PLUGIN_PATH}/scripts/outer-loop-enforcer.js check-can-complete ${SESSION_PATH}
   ```

2. If exit code 1: BLOCKED - cannot proceed to Phase 8
```

---

### 3. Validation Criteria Enforcer

**Script:** `scripts/validation-criteria-enforcer.js`

**How it works:**
- Parses validation-criteria.md from Phase 1
- Parses validation/result.md from Phase 7
- Matches criteria to results using fuzzy matching
- Blocks if >20% criteria unaddressed

**Usage in orchestrator:**

```markdown
PHASE 7: After creating result.md

1. Run criteria enforcer:
   ```bash
   node ${PLUGIN_PATH}/scripts/validation-criteria-enforcer.js ${SESSION_PATH}
   ```

2. Review generated report:
   ${SESSION_PATH}/validation/criteria-mapping.md

3. If unaddressed criteria found:
   - Update result.md to address them
   - Or document why they couldn't be tested
```

**Output format:**

```markdown
# Validation Criteria Mapping Report

## Summary
- Total Criteria: 5
- Matched: 4
- Unmatched: 1
- Coverage: 80%

## Criteria Mapping
| Line | Criterion | Result | Evidence |
|------|-----------|--------|----------|
| 12 | "Navigate to test URL" | PASS | screenshot-before.png |
| 13 | "Fill email field" | PASS | action-log.md line 5 |
| 14 | "Click login button" | PASS | action-log.md line 8 |
| 15 | "Redirect to dashboard" | PASS | screenshot-after.png |

## ⚠️ Unaddressed Criteria
- Line 16: "Show error for invalid password"
```

---

### 4. Checkpoint Verifier

**Script:** `scripts/checkpoint-verifier.sh`

**How it works:**
- Bash script for fast automated checks
- Runs at phase boundaries
- Verifies files exist and have content
- Checks git state for implementation phase

**Usage:**

```bash
# Before completing Phase 4
./checkpoint-verifier.sh phase4 ${SESSION_PATH}

# Before completing Phase 7
./checkpoint-verifier.sh phase7 ${SESSION_PATH}
```

**Example output:**

```
📋 Checkpoint Verification: phase4
─────────────────────────────────────
Session: ai-docs/sessions/dev-feature-login-20260204-143022

✅ Implementation Log: implementation-log.md (1234 bytes)
✅ Code Changes: 8 files with changes
✅ Implementation Log: Has structured progress

─────────────────────────────────────
✅ Checkpoint passed
```

---

## Integration with /dev:feature

### Phase Transition Protocol

**MANDATORY: Before marking ANY phase as completed:**

```markdown
<phase_completion_protocol>
  **Step 1: Run Checkpoint Verification**

  ```bash
  ${PLUGIN_PATH}/scripts/checkpoint-verifier.sh phase{N} ${SESSION_PATH}
  ```

  If exit code != 0: STOP. Fix missing artifacts first.

  **Step 2: Show Evidence Summary**

  Display 3-5 lines of actual results:
  ```
  ## Phase {N} Evidence
  - Artifact: ${SESSION_PATH}/{artifact}.md (exists, 1234 bytes)
  - Key result: {actual output from phase}
  - Evidence: {file paths to screenshots, logs, etc.}
  ```

  **Step 3: Map to Original Criteria** (for Phase 7)

  ```
  From validation-criteria.md:
  - [x] Criterion 1 → Verified (evidence file)
  - [x] Criterion 2 → Verified (screenshot)
  - [ ] Criterion 3 → Skipped (reason documented)
  ```

  **Step 4: Mark Task Complete**

  Only if Steps 1-3 pass:
  ```
  TaskUpdate(taskId: X, status: "completed")
  ```
</phase_completion_protocol>
```

### Show-Your-Work Requirement

**Anti-pattern (BLOCKED):**

```markdown
I'll run the tests now.
[Task tool call to run tests]
Tests passed! Moving to next phase.
```

**Required pattern:**

```markdown
Running tests:

$ bun test
✓ auth.test.ts (5 tests)
  ✓ should authenticate valid user (12ms)
  ✓ should reject invalid password (8ms)
  ✓ should expire session after timeout (15ms)
  ✓ should refresh token correctly (10ms)
  ✓ should logout user (5ms)

✗ payment.test.ts (3 tests)
  ✓ should process valid payment (20ms)
  ✓ should reject invalid card (12ms)
  ✗ should handle timeout (FAILED)
    Error: Expected timeout after 30s, got success

Results: 7 passed, 1 failed

The payment timeout test failure needs investigation before Phase 6 can complete.
```

---

## Graceful Degradation

### Three Completion Statuses

**COMPLETE**: All validation criteria passed
- All artifacts created
- All tests pass
- Full validation executed

**PARTIAL**