# Workflow Enforcement Implementation Plan

## Problem Statement

The current `/workflow:spawn` command documents phases and steps but lacks **strict enforcement**:
- Steps are described in markdown but rely on Claude following them voluntarily
- No blocking mechanisms prevent skipping phases
- Review and security checks can be bypassed in auto modes
- State persistence is incomplete - phases can be skipped on resume

## Solution Architecture

### Three Pillars of Enforcement

```
┌─────────────────────────────────────────────────────────────────┐
│                    ENFORCEMENT SYSTEM                           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────┐  │
│  │   BLOCKING   │    │   SCRIPT     │    │     STATE        │  │
│  │ CHECKPOINTS  │    │    GATES     │    │   PERSISTENCE    │  │
│  │              │    │              │    │                  │  │
│  │ - HALT until │    │ - Validation │    │ - File-based     │  │
│  │   verified   │    │   scripts    │    │   checkpoints    │  │
│  │ - Exit code  │    │ - Exit 0     │    │ - Cannot skip    │  │
│  │   required   │    │   required   │    │   on resume      │  │
│  └──────────────┘    └──────────────┘    └──────────────────┘  │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

## Implementation Components

### 1. Phase Gate Validator (`phase_gate.py`)

**Purpose**: Single script that controls ALL phase transitions

**Commands**:
```bash
# Check if ready to ENTER a phase
phase_gate.py can-enter $PHASE

# Mark completion of a phase's requirements
phase_gate.py complete $PHASE

# Save a named checkpoint within a phase
phase_gate.py checkpoint $NAME --phase $PHASE

# Verify all checkpoints for a phase are complete
phase_gate.py verify-checkpoints $PHASE

# Get current blocking conditions
phase_gate.py blockers
```

**Exit Codes**:
- `0` = PASS - proceed allowed
- `1` = BLOCKED - conditions not met (with reason)
- `2` = ERROR - system error

### 2. Checkpoint State File

**Location**: `.workflow/versions/$VERSION/gate_state.yml`

```yaml
version: v001
phase: IMPLEMENTING
created_at: "2025-12-18T10:00:00Z"
updated_at: "2025-12-18T10:30:00Z"

phases:
  INITIALIZING:
    status: completed
    entered_at: "2025-12-18T10:00:00Z"
    completed_at: "2025-12-18T10:01:00Z"
    checkpoints:
      manifest_exists: { status: passed, at: "..." }
      version_created: { status: passed, at: "..." }

  DESIGNING:
    status: completed
    entered_at: "2025-12-18T10:01:00Z"
    completed_at: "2025-12-18T10:10:00Z"
    checkpoints:
      design_document_created: { status: passed, at: "..." }
      design_validated: { status: passed, at: "..." }
      tasks_generated: { status: passed, at: "..." }
      task_count_verified: { status: passed, at: "...", data: { count: 15 } }

  AWAITING_DESIGN_APPROVAL:
    status: completed
    entered_at: "2025-12-18T10:10:00Z"
    completed_at: "2025-12-18T10:11:00Z"
    checkpoints:
      approval_granted: { status: passed, at: "...", data: { approver: "auto" } }

  IMPLEMENTING:
    status: in_progress
    entered_at: "2025-12-18T10:11:00Z"
    completed_at: null
    checkpoints:
      layer_1_complete: { status: passed, at: "..." }
      layer_2_complete: { status: pending }
      layer_3_complete: { status: pending }
      build_passes: { status: pending }

  REVIEWING:
    status: not_started
    checkpoints:
      review_script_run: { status: pending }
      all_files_exist: { status: pending }
      build_verified: { status: pending }

  SECURITY_REVIEW:
    status: not_started
    checkpoints:
      security_scan_run: { status: pending }
      api_contract_validated: { status: pending }
      no_critical_issues: { status: pending }

  AWAITING_IMPL_APPROVAL:
    status: not_started
    checkpoints:
      approval_granted: { status: pending }

  COMPLETING:
    status: not_started
    checkpoints:
      tasks_marked_complete: { status: pending }
      manifest_updated: { status: pending }
      version_completed: { status: pending }
```

### 3. Blocking Conditions Configuration

**Location**: `skills/guardrail-orchestrator/config/blocking_conditions.yml`

```yaml
# Defines what MUST be true before entering each phase
# and what MUST be completed before leaving each phase

phases:
  INITIALIZING:
    entry_requirements: []  # No requirements to start
    exit_requirements:
      - check: file_exists
        path: project_manifest.json
        error: "Run /guardrail:init first"
      - check: script_passes
        script: version_manager.py create
        error: "Failed to create version"
    checkpoints:
      - name: manifest_exists
        validator: file_exists
        args: { path: project_manifest.json }
      - name: version_created
        validator: directory_exists
        args: { path: ".workflow/versions/$VERSION" }

  DESIGNING:
    entry_requirements:
      - check: phase_completed
        phase: INITIALIZING
        error: "Must complete INITIALIZING first"
    exit_requirements:
      - check: file_exists
        path: ".workflow/versions/$VERSION/design/design_document.yml"
        error: "Design document not created"
      - check: script_passes
        script: validate_design.py
        error: "Design validation failed"
      - check: min_file_count
        pattern: ".workflow/versions/$VERSION/tasks/*.yml"
        minimum: 1
        error: "No task files generated"
    checkpoints:
      - name: design_document_created
        validator: file_exists
        args: { path: ".workflow/versions/$VERSION/design/design_document.yml" }
      - name: design_validated
        validator: script_passes
        args: { script: validate_design.py }
      - name: tasks_generated
        validator: min_file_count
        args: { pattern: ".workflow/versions/$VERSION/tasks/*.yml", minimum: 1 }

  AWAITING_DESIGN_APPROVAL:
    entry_requirements:
      - check: phase_completed
        phase: DESIGNING
        error: "Must complete DESIGNING first"
    exit_requirements:
      - check: approval_granted
        gate: design
        error: "Design approval required"
    checkpoints:
      - name: approval_granted
        validator: approval_status
        args: { gate: design, required: approved }

  IMPLEMENTING:
    entry_requirements:
      - check: phase_completed
        phase: AWAITING_DESIGN_APPROVAL
        error: "Must get design approval first"
      - check: approval_granted
        gate: design
        error: "Design not approved"
    exit_requirements:
      - check: script_passes
        script: "npm run build"
        error: "Build must pass"
      - check: all_tasks_have_files
        error: "Not all tasks have implementation files"
    checkpoints:
      - name: layer_1_complete
        validator: layer_implemented
        args: { layer: 1 }
      - name: layer_2_complete
        validator: layer_implemented
        args: { layer: 2 }
      - name: layer_3_complete
        validator: layer_implemented
        args: { layer: 3 }
      - name: build_passes
        validator: script_passes
        args: { script: "npm run build" }

  REVIEWING:
    entry_requirements:
      - check: phase_completed
        phase: IMPLEMENTING
        error: "Must complete IMPLEMENTING first"
      - check: script_passes
        script: "npm run build"
        error: "Build must pass before review"
    exit_requirements:
      - check: script_passes
        script: verify_implementation.py
        error: "Implementation verification failed"
    checkpoints:
      - name: review_script_run
        validator: script_passes
        args: { script: verify_implementation.py }
      - name: all_files_exist
        validator: all_task_files_exist
        args: {}
      - name: build_verified
        validator: script_passes
        args: { script: "npm run build" }

  SECURITY_REVIEW:
    entry_requirements:
      - check: phase_completed
        phase: REVIEWING
        error: "Must complete REVIEWING first"
    exit_requirements:
      - check: script_passes
        script: "security_scan.py --severity HIGH"
        error: "Security scan has CRITICAL issues"
      - check: script_passes
        script: validate_api_contract.py
        error: "API contract validation failed"
    checkpoints:
      - name: security_scan_run
        validator: script_passes
        args: { script: "security_scan.py --project-dir . --severity HIGH" }
      - name: api_contract_validated
        validator: script_passes
        args: { script: validate_api_contract.py }
      - name: no_critical_issues
        validator: security_no_critical
        args: {}

  AWAITING_IMPL_APPROVAL:
    entry_requirements:
      - check: phase_completed
        phase: SECURITY_REVIEW
        error: "Must complete SECURITY_REVIEW first"
    exit_requirements:
      - check: approval_granted
        gate: implementation
        error: "Implementation approval required"
    checkpoints:
      - name: approval_granted
        validator: approval_status
        args: { gate: implementation, required: approved }

  COMPLETING:
    entry_requirements:
      - check: phase_completed
        phase: AWAITING_IMPL_APPROVAL
        error: "Must get implementation approval first"
    exit_requirements:
      - check: script_passes
        script: version_manager.py complete
        error: "Failed to complete version"
    checkpoints:
      - name: tasks_marked_complete
        validator: all_tasks_status
        args: { status: completed }
      - name: manifest_updated
        validator: manifest_entities_implemented
        args: {}
      - name: version_completed
        validator: script_passes
        args: { script: "version_manager.py complete" }
```

### 4. Updated spawn.md Phase Execution

Each phase in spawn.md will be updated to use mandatory gate calls:

```markdown
### PHASE 5: REVIEWING

#### Step 5.0: Gate Check [MANDATORY - BLOCKING]
```bash
# MUST pass before proceeding - HALT if fails
python3 skills/guardrail-orchestrator/scripts/phase_gate.py can-enter REVIEWING
EXIT_CODE=$?
if [ $EXIT_CODE -ne 0 ]; then
  echo "❌ BLOCKED: Cannot enter REVIEWING phase"
  echo "Run /workflow:status to see blocking conditions"
  # HALT - DO NOT PROCEED
  exit 1
fi
```

#### Step 5.1: Run Build Validation [MANDATORY]
```bash
npm run build 2>&1
BUILD_EXIT=$?

# Save checkpoint
python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint build_verified \
  --phase REVIEWING \
  --status $([ $BUILD_EXIT -eq 0 ] && echo "passed" || echo "failed")
```

... (rest of phase)

#### Step 5.X: Complete Phase [MANDATORY]
```bash
# MUST pass before transitioning - HALT if fails
python3 skills/guardrail-orchestrator/scripts/phase_gate.py complete REVIEWING
EXIT_CODE=$?
if [ $EXIT_CODE -ne 0 ]; then
  echo "❌ BLOCKED: Cannot complete REVIEWING phase"
  echo "Missing checkpoints:"
  python3 skills/guardrail-orchestrator/scripts/phase_gate.py blockers
  # HALT - DO NOT PROCEED
  exit 1
fi
```
```

### 5. Auto-Mode Enforcement

Even in `--auto` and `--full-auto` modes, the following are **NEVER skipped**:

| Phase | Auto-Approved | Script Gates Still Run |
|-------|---------------|------------------------|
| DESIGNING | N/A | validate_design.py |
| AWAITING_DESIGN_APPROVAL | YES | None (approval only) |
| IMPLEMENTING | N/A | npm run build |
| REVIEWING | YES if passes | verify_implementation.py, npm run build |
| SECURITY_REVIEW | YES if passes | security_scan.py, validate_api_contract.py |
| AWAITING_IMPL_APPROVAL | YES if passes | None (approval only) |

## Implementation Order

### Phase 1: Core Infrastructure
1. Create `phase_gate.py` script
2. Create `blocking_conditions.yml` config
3. Create `gate_state.yml` schema

### Phase 2: Integration
4. Update `workflow_manager.py` to use phase_gate
5. Update `validate_workflow.py` to check gate_state
6. Create hook integration for real-time enforcement

### Phase 3: spawn.md Updates
7. Add gate checks to each phase in spawn.md
8. Add checkpoint saves after each major step
9. Add blocking conditions to phase transitions

### Phase 4: Testing
10. Test manual mode enforcement
11. Test --auto mode (gates still run)
12. Test --full-auto mode (gates still run)
13. Test resume after interruption

## File Summary

| File | Purpose |
|------|---------|
| `scripts/phase_gate.py` | Main enforcement script |
| `config/blocking_conditions.yml` | Phase requirements definition |
| `.workflow/versions/$V/gate_state.yml` | Checkpoint persistence |
| `commands/workflow/spawn.md` | Updated with gate calls |

## Success Criteria

1. **Cannot skip phases**: Attempting to transition without completing previous phase fails
2. **Cannot skip review**: REVIEWING phase always runs verification scripts
3. **Cannot skip security**: SECURITY_REVIEW always runs security scan
4. **Resume preserves state**: Interrupted workflow resumes at correct checkpoint
5. **Auto modes run gates**: --auto and --full-auto still execute all validation scripts

## Command Reference

```bash
# Check current blockers
python3 skills/guardrail-orchestrator/scripts/phase_gate.py blockers

# Check if can enter a phase
python3 skills/guardrail-orchestrator/scripts/phase_gate.py can-enter REVIEWING

# Save a checkpoint
python3 skills/guardrail-orchestrator/scripts/phase_gate.py checkpoint build_verified --phase REVIEWING --status passed

# Complete a phase
python3 skills/guardrail-orchestrator/scripts/phase_gate.py complete REVIEWING

# View gate state
cat .workflow/versions/$VERSION/gate_state.yml
```