gitea
3d4c0926b4
CI / build (push) Has been cancelled
- Insert code_review phase between implement and bug_find - Approval gate: code_review:awaiting_approval → code_review:approved - Read-only phase — no edits, no fixes, no returning to implement - Reviewer≠implementer: .state.implementer tracking + --claim enforcement - Structured CODE_REVIEW.md: spec compliance, design conformance, quality scorecard, items found (severity/category/location/resolution), test coverage - Updated status.py (10 data structures), dashboard (4 files), prompts (3 files), agent routing, tests (6 new test classes, 19 new tests)
115 lines
7.9 KiB
Markdown
115 lines
7.9 KiB
Markdown
# Workflow State Machine
|
|
|
|
This file defines the linear progression of a task in automaton. The Orchestrator uses this to determine the next phase.
|
|
|
|
## Single Source of Truth: `.state` File
|
|
|
|
The `.state` file in each task folder is the canonical indicator of a task's current phase. It takes precedence over artifact-based heuristic.
|
|
|
|
- **Location**: `tasks/{task-name}/.state`
|
|
- **Content**: A single phase name (e.g., `research`, `research:awaiting_approval`, `implement`, `complete`)
|
|
- **Atomic writes**: Written to `.state.tmp` first, then renamed to `.state`
|
|
- **If `.state` is missing**: Fall back to artifact-based heuristic and write `.state` with the inferred phase
|
|
|
|
### `.state.approvals` Log
|
|
|
|
Each task has a `.state.approvals` file recording all user approvals:
|
|
|
|
- **Location**: `tasks/{task-name}/.state.approvals`
|
|
- **Format**: One line per approval: `{phase}:approved|{ISO-8601-timestamp}|{approver}`
|
|
- **Append-only**: Approvals are never deleted
|
|
- **Metadata**: Not a phase deliverable, excluded from artifact checks
|
|
|
|
### `.state.lock` (Multi-Agent Mode Only)
|
|
|
|
When `Mode: multi-agent` is set in `.agent.md`, a `.state.lock` file tracks which agent has claimed the task:
|
|
|
|
- **Location**: `tasks/{task-name}/.state.lock`
|
|
- **Format**: `agent: {id}`, `phase: {current}`, `claimed: {timestamp}`, `expires: {timestamp}`
|
|
- **Atomic writes**: Same `.tmp` pattern as `.state`
|
|
- **Default timeout**: 30 minutes (configurable in `.agent.md`)
|
|
- **Metadata**: Not a phase deliverable, excluded from artifact checks
|
|
|
|
## Task Lifecycle
|
|
|
|
| Current State | Signal | Next Phase | Action |
|
|
| :--- | :--- | :--- | :--- |
|
|
| **New Task** | `status.py --create-task {name} --project {project}` creates folder with `.state` = `new` | Research | Generate `SPEC.md` |
|
|
| **Research** | Has `.state` = `research` | research:awaiting_approval | Present SPEC.md draft for user sign-off |
|
|
| **research:awaiting_approval** | Has `.state` = `research:awaiting_approval` | research:approved | User says "APPROVED", call `status.py --approve` |
|
|
| **research:approved** | Has `.state` = `research:approved` | Decomposition (optional) or Design (optional) or Implement | Transition via `status.py --transition` |
|
|
| **Decomposition** | Has `.state` = `decomposition` | decomposition:awaiting_approval | Present DECOMPOSITION.md draft for user sign-off |
|
|
| **decomposition:awaiting_approval** | Has `.state` = `decomposition:awaiting_approval` | decomposition:approved | User says "APPROVED", call `status.py --approve` |
|
|
| **decomposition:approved** | Has `.state` = `decomposition:approved` | Sub-task Research | Orchestrator creates sub-task folders |
|
|
| **Design** | Has `.state` = `design` | design:awaiting_approval | Present DESIGN.md draft for user sign-off |
|
|
| **design:awaiting_approval** | Has `.state` = `design:awaiting_approval` | design:approved | User says "APPROVED", call `status.py --approve` |
|
|
| **design:approved** | Has `.state` = `design:approved` | Test Design (optional) or Implement | Transition via `status.py --transition` |
|
|
| **Test Design** | Has `.state` = `test_design` | test_design:awaiting_approval | Present TEST_PLAN.md draft for user sign-off |
|
|
| **test_design:awaiting_approval** | Has `.state` = `test_design:awaiting_approval` | test_design:approved | User says "APPROVED", call `status.py --approve` |
|
|
| **test_design:approved** | Has `.state` = `test_design:approved` | Implement | Transition via `status.py --transition` |
|
|
| **Implementation** | Has `.state` = `implement` | Code Review | Generate `CODE_REVIEW.md` |
|
|
| **Code Review** | Has `.state` = `code_review` | code_review:awaiting_approval | Present CODE_REVIEW.md draft for user sign-off |
|
|
| **code_review:awaiting_approval** | Has `.state` = `code_review:awaiting_approval` | code_review:approved | User says "APPROVED", call `status.py --approve` |
|
|
| **code_review:approved** | Has `.state` = `code_review:approved` | Bug Find | Transition via `status.py --transition` |
|
|
| **Bug Find** | Has `.state` = `bug_find` | Adversarial Bug Find | Generate `ADVERSARIAL_BUG_REPORT.md` |
|
|
| **Adversarial Bug Find** | Has `.state` = `adversarial_bug_find` | Doc Review | Generate `DOC_REVIEW.md` |
|
|
| **Doc Review** | Has `.state` = `doc_review` | Referee | Generate `VERDICT.md` |
|
|
| **Referee** | Has `.state` = `referee` | Complete / Human Intervention | Finalize or request user intervention |
|
|
|
|
### Phases Without Approval Gates
|
|
|
|
The following phases do **not** have `:awaiting_approval` sub-states because they do not require interactive user sign-off:
|
|
- `implement`, `bug_find`, `adversarial_bug_find`, `doc_review`, `referee`
|
|
- These transition directly to the next phase upon producing their artifact and calling `status.py --transition`
|
|
|
|
Phases with approval gates (require user sign-off):
|
|
- `research`, `decomposition`, `design`, `test_design`, `code_review`
|
|
|
|
## Task Creation (via `status.py`)
|
|
|
|
New tasks MUST be created via `status.py --create-task {name} --project {project}`. This creates the folder, `.state` = `new`, and an empty `.state.approvals` file.
|
|
|
|
Manual task folder creation (`mkdir tasks/my-task`) is flagged as a violation by `status.py --audit` and `status.py --validate-folder`.
|
|
|
|
Tasks without `.state` files are UNTRACKED. All commands (`--transition`, `--can-edit`, `--task`, `--approve`) refuse to operate on them. Run `status.py --upgrade --project {project}` to bootstrap `.state` files for pre-v2.0 tasks.
|
|
|
|
### Task creation from bugs
|
|
When the Orchestrator detects a `VERDICT.md` with `FAIL` or `NEEDS_REVIEW`, it uses `status.py --create-task --project {project}` to create fix/review/tiebreak tasks. The Orchestrator also copies relevant artifacts (SPEC.md, BUG_REPORT.md, etc.) and sets `.state` to the appropriate phase (e.g., `bug_find` for fix tasks).
|
|
|
|
## Enforcement via `status.py`
|
|
|
|
### Phase-Gated Transitions
|
|
All transitions go through `status.py --transition {phase} --project {project}`:
|
|
- Only legal transitions are allowed (defined in LEGAL_TRANSITIONS)
|
|
- `:awaiting_approval` phases can only transition to `:approved` via `status.py --approve --project {project}`
|
|
- Required artifacts must exist and be non-empty before transitioning
|
|
- Forbidden artifacts (from future phases) block transitions
|
|
|
|
### Folder Validation
|
|
`status.py --validate-folder --task {name} --project {project}` checks for:
|
|
- Out-of-order artifacts (artifacts from future phases)
|
|
- Missing `.state` file (manually created task)
|
|
- Phase-artifact inconsistency
|
|
|
|
### Audit
|
|
`status.py --audit --project {project}` checks all tasks for:
|
|
- Category 1: Out-of-order artifacts
|
|
- Category 2: State-artifact inconsistency
|
|
- Category 3: Unauthorized git modifications (if git repo)
|
|
- Category 4: Manually created task folders (no `.state`)
|
|
|
|
### Approval Gates
|
|
`status.py --approve --task {name} --project {project}` transitions from `:awaiting_approval` to `:approved`:
|
|
- Records approval in `.state.approvals` with timestamp and approver
|
|
- Refuses if not in an `:awaiting_approval` sub-state
|
|
- Refuses for phases that don't require approval
|
|
|
|
## Autopilot Rules
|
|
|
|
1. **Linear Progression**: Never skip a phase. Each transition must go through `status.py --transition --project {project}`.
|
|
2. **Approval Gates**: Research, Decomposition, Design, Test Design, and Code Review phases require explicit user approval before proceeding. The autopilot MUST pause at `:awaiting_approval` sub-states.
|
|
3. **Artifact Check**: A phase is only considered "complete" if its corresponding artifact exists, is non-empty, AND the `.state` file reflects the completed phase.
|
|
4. **Folder Validation**: Before each phase transition, run `status.py --validate-folder --project {project}`. Do not proceed past violations.
|
|
5. **Human Intervention**: If the Referee marks a task as `FAIL`, `NEEDS_REVIEW`, or identifies "Tie-Breaks", the Autopilot pauses and waits for user input.
|
|
6. **Task Creation**: Always use `status.py --create-task --project {project}` to create new tasks. Never create task folders manually.
|
|
7. **Forbidden Actions**: Respect the ALLOWED/FORBIDDEN sections in each phase prompt. Even in autopilot, the Orchestrator must not perform forbidden actions. |