Lap Tran
bc7daf8590
- **Restore 82 completed tasks** from tasks/complete/ back to tasks/ top level (all <7 days old per the cleanup policy; premature bulk archive was fixed). - **Dashboard: fix scroll-reset on auto-refresh** — renderBoard rebuilds the board via innerHTML every 2s, destroying each column-body's scrollTop. Now snapshots column-body scrollTop + board.scrollLeft + view.scrollTop before rebuild and restores after (matched by PHASE_GROUPS index). - **Dashboard UI additions** (pre-existing unstaged work): approval section cards, transition buttons, inline artifact editor (textarea for writing missing SPEC/VERDICT/etc from the detail modal). - **Bind ornith as Implement model** — config.md: Model explicit to omlx/Ornith-1.0-35B-4bit-mlx, context window 32768. Interactive autopilot already used ornith via opencode default; now explicit. - **Fix cleanup stub** — automaton-cleanup.sh had a stale --project arg pointing at a pytest temp dir (test isolation leak). Rewired to point at ~/.automaton. - **Fix plist-isolation test** — test asserted host plist doesn't exist, but a real install creates it. Now snapshots mtime before run, asserts unchanged after (only a write during the test counts as bleed). - **New Playwright smoke test** (tests/test_dashboard_ui.py) — 2 tests: board renders tasks, column scroll survives auto-refresh tick. Verified the test fails without the scroll fix (scrollTop resets to 0). Skipped via importorskip when playwright is absent (main CI stays green). - **Clarify SI loop scope in README** — new-project onboarding section documents the framework-scoped self-improvement loop and options (leave/pause/create project loop). - **CHANGELOG** documents all changes including the known model-divergence gap (mde tasks marked complete but per-role model binding was never implemented).
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) |