# Implementation: State File Enforcement

## Changes Made

### 1. `.state` file format (implemented in `scripts/status.py`)
- `.state` file contains a single phase name (e.g., `research`, `research:awaiting_approval`, `implement`)
- Written atomically via `.state.tmp` → `.state` rename
- `.state.approvals` append-only log records all approvals with timestamp and approver
- `.state.lock` for multi-agent claiming (optional, only in multi-agent mode)
- Non-artifact metadata files (`.state`, `.state.approvals`, `.state.lock`, `.state.tmp`, `VRAM_CONFIG.md`, `PARENT_SPEC.md`, `REVIEW.md`) are excluded from artifact checks

### 2. State transitions with approval sub-states
- Approval-gated phases: research, decomposition, design, test_design now have `:awaiting_approval` → `:approved` sub-states
- Non-approval phases: implement, bug_find, adversarial_bug_find, doc_review, referee have no sub-states
- `status.py --transition` refuses transitions past `:awaiting_approval` without `--approve`
- `status.py --approve` transitions `:awaiting_approval` → `:approved` and records approval in `.state.approvals`

### 3. Backward compatibility
- If `.state` doesn't exist, `status.py` infers phase from artifacts and writes `.state`
- `upgrade.sh` bootstraps `.state` for all existing tasks
- Phase prompts work with or without `.state` (warns if missing)

### 4. Forbidden artifacts per phase (implemented in `status.py --validate-folder`)
- Each phase has a defined set of artifacts that must NOT exist (artifacts from future phases)
- `--validate-folder` checks and reports violations
- `--transition` refuses to proceed if forbidden artifacts exist

### 5. Task creation gate (implemented in `status.py --create-task`)
- `--create-task` creates task folder with `.state` = `new` and empty `.state.approvals`
- Validates kebab-case task names
- Refuses if task already exists
- `--audit` Category 4 flags manually created task folders

### 6. Orchestrator and workflow updates
- `prompts/workflow.md` rewritten: `.state` is canonical, approval sub-states documented, `status.py` commands referenced
- `prompts/orchestrate.md` reduced from 493 to 143 lines, references `workflow.md` and `subtask_management.md`
- All phase prompts include `.state` precondition check

## Files Modified
- `scripts/status.py` (new, 980 lines)
- `prompts/workflow.md` (rewritten)
- `prompts/orchestrate.md` (rewritten, 143 lines)
- `prompts/subtask_management.md` (new, extracted from orchestrate.md)
- `tests/test_status.py` (new, 25 tests)
- `scripts/upgrade.sh` (new)

## Test Results
- 183 tests passing (including 25 new status.py tests)
- Python compilation clean
- Shell script syntax clean