automaton/tasks/inflight-upgrade-path/SPEC.md

# SPEC: Inflight Upgrade Path

## Goal
Create a migration and upgrade path so that projects already using Automaton can adopt the new enforcement mechanisms (`.state` file, phase-scoped prompts, `status.py`) without breaking existing tasks or requiring manual intervention.

## Background
Existing projects have tasks in progress with artifact files but no `.state` files. They use the current prompts without FORBIDDEN sections. The upgrade needs to be backward-compatible — existing tasks must continue to work, and the transition should be automatic.

## Requirements

### 1. `.state` file bootstrap for existing tasks
When `status.py` encounters a task folder without a `.state` file:
1. Use the artifact heuristic (from `workflow.md`) to determine the current phase
2. Write `.state` with the inferred phase name
3. Output a note: "Bootstrapped .state for task '{task-name}': phase inferred as '{phase}' from existing artifacts"

This is already specified in the status-script spec. This task ensures:
- The artifact heuristic is correctly implemented in `status.py`
- Edge cases are handled (empty artifact files, partially completed phases)
- The bootstrap is logged so users can verify the inferred phase

### 2. Upgrade script
Create `scripts/upgrade.sh` (and reference it in `scripts/update.sh`) that:
1. Scans `{project}/.automaton/tasks/` for all task folders
2. For each task folder:
   - Check if `.state` exists
   - If not, call `status.py --task {task-name}` to bootstrap `.state`
   - Report the inferred phase for user verification
3. Scans sub-task folders (`subtasks/*/`) and does the same
4. Runs `status.py --audit` across all tasks to detect:
   - Out-of-order artifacts (Category 1)
   - State-artifact inconsistencies (Category 2)
   - Unauthorized modifications if git is available (Category 3)
5. Produces a summary:
   ```
   Upgrade Summary:
   - 5 tasks scanned
   - 3 tasks already had .state (no change)
   - 2 tasks bootstrapped with inferred .state:
     - add-user-auth: research (SPEC.md exists)
     - fix-login-bug: implement (IMPLEMENTATION.md exists)

   Audit Results:
   - 1 violation found:
     - fix-login-bug: IMPLEMENTATION.md exists but .state says research (corrected to implement)
   - 4 tasks clean
   ```

### 3. Update `install.sh` to create `.state` for new tasks
When the Orchestrator creates a new task folder, it must:
- Create the task folder
- Write `.state` with content `new\n`
- This is already covered by the state-file-enforcement spec; this task ensures the orchestrator prompt is updated to include this step

### 4. Update `migrate-project.sh`
The existing migration script needs to:
1. Handle `.state` files that may exist in old task folders (ignore them — they'll be bootstrapped by `status.py`)
2. Not delete `.state` files during migration
3. Add `.state` to the list of non-artifact files (alongside `VRAM_CONFIG.md` and `PARENT_SPEC.md`)

### 5. Backward-compatible phase prompts
The updated prompts (with FORBIDDEN sections and `.state` checks) must work even when `.state` doesn't exist:
- If `.state` doesn't exist, the precondition check should say: "No .state file found. Proceeding based on artifact heuristic. Recommend running 'python ~/.automaton/scripts/status.py --task {task}' to bootstrap .state."
- The prompt should not refuse to work if `.state` is missing — it should warn but continue
- This ensures a graceful transition period

### 6. Documentation updates
Update `README.md` to document:
- The `.state` file and its role
- The `status.py` command and its flags
- The upgrade path for existing projects
- That `status.py --list` replaces manual artifact checking

Update `CHANGELOG.md` under `[unreleased]`:
- Add `.state` file enforcement
- Add `status.py` script
- Phase-scoped prompts with ALLOWED/FORBIDDEN sections
- Backward-compatible with existing tasks (automatic `.state` bootstrap)

### 7. Version marker
Add a version marker to `~/.automaton/config.md`:
```
## Framework Version
- **Version**: 2.0
- **State enforcement**: enabled (`.state` file + `status.py`)
```

This allows `status.py` to detect the framework version and adjust behavior if needed. Existing projects without this marker are assumed to be on version 1.x and get the bootstrap treatment.

## Acceptance Criteria
- [ ] `status.py` bootstraps `.state` for tasks without it (artifact heuristic fallback)
- [ ] `scripts/upgrade.sh` scans all tasks and bootstraps missing `.state` files
- [ ] `scripts/upgrade.sh` runs `status.py --audit` and reports violations
- [ ] `scripts/upgrade.sh` produces a human-readable summary including audit results
- [ ] `scripts/install.sh` or orchestrator prompt updated to create `.state` for new tasks
- [ ] `scripts/migrate-project.sh` handles `.state` files correctly
- [ ] Phase prompts work with or without `.state` (graceful degradation)
- [ ] `README.md` updated with new features and upgrade instructions
- [ ] `CHANGELOG.md` updated under `[unreleased]`
- [ ] Version marker added to `config.md`
- [ ] Tests for `status.py` bootstrap logic in `tests/test_status.py`
- [ ] Tests for `status.py --validate-folder` and `--audit` in `tests/test_status.py`
- [ ] Tests for `upgrade.sh` in `tests/test_upgrade.py`

## Non-Goals
- This spec does not cover the `.state` file format itself (covered by state-file-enforcement)
- This spec does not cover `status.py` implementation (covered by status-script)
- This spec does not cover prompt restructuring (covered by phase-scoped-prompts)
- This spec does not cover autopilot integration (covered by autopilot-gate-integration)