Lap Tran
4a2301b077
CI / build (push) Has been cancelled
- Archive 79 completed framework-dev tasks from tasks/ -> tasks/complete/ - status.py: add --cleanup-done and --install-cleanup-schedule commands - Add scripts/automaton-cleanup.sh for periodic task archiving - Dashboard: rename 'Background' tab -> 'Agent', 'Cleanup' agent -> 'Completed Task Archiver', remove redundant group headers and pill badges, dim inactive agent placeholders - .rules.md: add Self-Documenting UI Names rule - New tests: test_cleanup_done.py, expanded test_app.py and test_task.py
109 lines
5.5 KiB
Markdown
109 lines
5.5 KiB
Markdown
# 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) |