phase-enforcement

# 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

───────────────────────────────────