430 lines
14 KiB
Markdown
430 lines
14 KiB
Markdown
# 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
|
|
```
|