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)