14 KiB
14 KiB
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:
# 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 allowed1= BLOCKED - conditions not met (with reason)2= ERROR - system error
2. Checkpoint State File
Location: .workflow/versions/$VERSION/gate_state.yml
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
# 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:
### 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]
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]
# 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