mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
468 lines
16 KiB
Markdown
468 lines
16 KiB
Markdown
# Task Lifecycle Standards
|
|
|
|
Comprehensive standards for task management in the RoboCo system. These standards are derived from the actual implementation in the codebase.
|
|
|
|
**Source Files:**
|
|
- Task Status Enum: `roboco/models/base.py` (lines 19-34)
|
|
- Lifecycle Enforcement: `roboco/enforcement/task_lifecycle.py`
|
|
- Task Service: `roboco/services/task.py`
|
|
|
|
---
|
|
|
|
## Table of Contents
|
|
|
|
1. [Task States](#task-states)
|
|
2. [Valid Transitions](#valid-transitions)
|
|
3. [Role-Restricted Transitions](#role-restricted-transitions)
|
|
4. [Task Service Methods](#task-service-methods)
|
|
5. [Workflow by Role](#workflow-by-role)
|
|
6. [Quality Gates](#quality-gates)
|
|
7. [State Categories](#state-categories)
|
|
|
|
---
|
|
|
|
## Task States
|
|
|
|
### WF-001: TaskStatus Enum
|
|
|
|
**Source:** `roboco/models/base.py`
|
|
|
|
```python
|
|
class TaskStatus(str, Enum):
|
|
"""Task lifecycle states."""
|
|
|
|
BACKLOG = "backlog" # PM setup phase
|
|
PENDING = "pending" # Ready for work
|
|
CLAIMED = "claimed" # Agent has ownership
|
|
IN_PROGRESS = "in_progress" # Active work
|
|
BLOCKED = "blocked" # Waiting on dependency
|
|
PAUSED = "paused" # Temporarily stopped
|
|
VERIFYING = "verifying" # Self-verification
|
|
NEEDS_REVISION = "needs_revision"# QA rejected
|
|
AWAITING_QA = "awaiting_qa" # Ready for QA
|
|
AWAITING_DOCUMENTATION = "awaiting_documentation" # QA passed
|
|
AWAITING_PM_REVIEW = "awaiting_pm_review" # Docs done
|
|
COMPLETED = "completed" # TERMINAL
|
|
CANCELLED = "cancelled" # TERMINAL
|
|
```
|
|
|
|
### WF-002: State Diagram
|
|
|
|
```
|
|
PM CREATES
|
|
│
|
|
▼
|
|
┌──────────┐
|
|
│ BACKLOG │───► cancelled
|
|
└────┬─────┘
|
|
│ activate()
|
|
▼
|
|
┌──────────┐
|
|
┌──────│ PENDING │◄─────────────────────────────────┐
|
|
│ └────┬─────┘───► cancelled │
|
|
│ │ │
|
|
│ claim() │
|
|
│ │ │
|
|
▼ ▼ │
|
|
┌──────────┐ │
|
|
│ CLAIMED │───► pending, cancelled │
|
|
└────┬─────┘ │
|
|
│ start() │
|
|
▼ │
|
|
┌─────────────┐ │
|
|
┌──────────│ IN_PROGRESS │───► completed, cancelled │
|
|
│ └──────┬──────┘ │
|
|
│ │ │
|
|
block() pause() │
|
|
│ │ │
|
|
▼ ▼ │
|
|
┌──────────┐ ┌─────────┐ │
|
|
│ BLOCKED │ │ PAUSED │ │
|
|
└────┬─────┘ └────┬────┘ │
|
|
│ │ │
|
|
unblock() resume() │
|
|
│ │ │
|
|
└────────►───────►└──────►──────┐ │
|
|
│ │
|
|
submit_for_verification() │
|
|
│ │
|
|
▼ │
|
|
┌───────────┐ │
|
|
│ VERIFYING │───► cancelled │
|
|
└─────┬─────┘ │
|
|
│ │
|
|
┌───────────────────────┼───────────────────────┐ │
|
|
│ │ │ │
|
|
submit_for_qa() needs_revision direct to docs│
|
|
│ │ │ │
|
|
▼ ▼ ▼ │
|
|
┌─────────────┐ ┌─────────────────┐ ┌─────────────────────┐
|
|
│ AWAITING_QA │◄───────│ NEEDS_REVISION │──│ AWAITING_DOCUMENTATION│
|
|
└──────┬──────┘ └─────────────────┘ └──────────┬──────────┘
|
|
│ ▲ │
|
|
┌─────────┼─────────┐ │ │
|
|
│ │ │ │ docs_complete()
|
|
pass_qa() fail_qa() block │ │
|
|
│ │ │ │ ▼
|
|
│ └─────────┴───────────────┘ ┌────────────────────┐
|
|
│ │ AWAITING_PM_REVIEW │
|
|
└────────────────────────────────────────────────└─────────┬──────────┘
|
|
│
|
|
complete()
|
|
│
|
|
▼
|
|
┌───────────┐
|
|
│ COMPLETED │
|
|
└───────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## Valid Transitions
|
|
|
|
### WF-010: Transition Matrix
|
|
|
|
**Source:** `roboco/enforcement/task_lifecycle.py` (lines 17-56)
|
|
|
|
| From Status | Valid Next States |
|
|
|-------------|-------------------|
|
|
| `backlog` | pending, cancelled |
|
|
| `pending` | claimed, cancelled |
|
|
| `claimed` | in_progress, pending, cancelled |
|
|
| `in_progress` | blocked, paused, verifying, completed, cancelled |
|
|
| `blocked` | in_progress, cancelled |
|
|
| `paused` | in_progress, cancelled |
|
|
| `verifying` | awaiting_qa, needs_revision, awaiting_documentation, cancelled |
|
|
| `needs_revision` | claimed, in_progress, cancelled |
|
|
| `awaiting_qa` | claimed, awaiting_documentation, needs_revision, blocked, cancelled |
|
|
| `awaiting_documentation` | claimed, awaiting_pm_review, cancelled |
|
|
| `awaiting_pm_review` | claimed, completed, cancelled |
|
|
| `completed` | *(TERMINAL - no transitions)* |
|
|
| `cancelled` | *(TERMINAL - no transitions)* |
|
|
|
|
### WF-011: Invalid Transitions
|
|
|
|
Any transition NOT in the matrix above will raise `InvalidTransitionError`.
|
|
|
|
```python
|
|
from roboco.enforcement.task_lifecycle import validate_task_transition
|
|
|
|
# This will raise InvalidTransitionError
|
|
validate_task_transition(
|
|
TaskStatus.PENDING,
|
|
TaskStatus.COMPLETED, # Cannot skip the workflow!
|
|
agent_role="developer"
|
|
)
|
|
```
|
|
|
|
---
|
|
|
|
## Role-Restricted Transitions
|
|
|
|
### WF-020: Permission Matrix
|
|
|
|
**Source:** `roboco/enforcement/task_lifecycle.py` (lines 66-93)
|
|
|
|
Certain transitions require specific roles:
|
|
|
|
| Transition | Allowed Roles |
|
|
|------------|---------------|
|
|
| `backlog → pending` | cell_pm, main_pm, product_owner, head_marketing |
|
|
| `awaiting_qa → claimed` | qa |
|
|
| `awaiting_qa → awaiting_documentation` | qa |
|
|
| `awaiting_qa → needs_revision` | qa |
|
|
| `awaiting_documentation → claimed` | documenter |
|
|
| `awaiting_documentation → awaiting_pm_review` | documenter |
|
|
| `awaiting_pm_review → claimed` | cell_pm, main_pm, product_owner, head_marketing |
|
|
| `awaiting_pm_review → completed` | cell_pm, main_pm, product_owner, head_marketing |
|
|
| `in_progress → completed` | cell_pm, main_pm, product_owner, head_marketing |
|
|
| `* → cancelled` | cell_pm, main_pm, product_owner, head_marketing |
|
|
|
|
### WF-021: Role Validation
|
|
|
|
```python
|
|
from roboco.enforcement.task_lifecycle import can_agent_transition
|
|
|
|
# Check if role can make transition
|
|
if can_agent_transition(
|
|
current_status=TaskStatus.AWAITING_QA,
|
|
new_status=TaskStatus.AWAITING_DOCUMENTATION,
|
|
agent_role="developer" # False - only QA can do this
|
|
):
|
|
# proceed
|
|
```
|
|
|
|
---
|
|
|
|
## Task Service Methods
|
|
|
|
### WF-030: Status Change Methods
|
|
|
|
**Source:** `roboco/services/task.py`
|
|
|
|
| Method | Status Change | Calling Roles |
|
|
|--------|---------------|---------------|
|
|
| `activate()` | BACKLOG → PENDING | PM roles |
|
|
| `claim()` | → CLAIMED | developer, qa, documenter (based on current status) |
|
|
| `start()` | CLAIMED/PAUSED/NEEDS_REVISION → IN_PROGRESS | Owner |
|
|
| `block()` | IN_PROGRESS → BLOCKED | Owner |
|
|
| `soft_block()` | IN_PROGRESS → BLOCKED | Owner (external factor) |
|
|
| `unblock()` | BLOCKED → IN_PROGRESS | Owner or PM |
|
|
| `pause()` | IN_PROGRESS → PAUSED | Owner |
|
|
| `resume()` | PAUSED → IN_PROGRESS | Owner |
|
|
| `submit_for_verification()` | IN_PROGRESS → VERIFYING | Developer |
|
|
| `submit_for_qa()` | VERIFYING → AWAITING_QA | Developer |
|
|
| `pass_qa()` | AWAITING_QA → AWAITING_DOCUMENTATION | QA |
|
|
| `fail_qa()` | AWAITING_QA → NEEDS_REVISION | QA |
|
|
| `docs_complete()` | AWAITING_DOCUMENTATION → AWAITING_PM_REVIEW | Documenter |
|
|
| `submit_for_pm_review()` | IN_PROGRESS → AWAITING_PM_REVIEW | Any (non-dev tasks) |
|
|
| `complete()` | AWAITING_PM_REVIEW → COMPLETED | PM roles |
|
|
| `cancel()` | ANY → CANCELLED | PM roles |
|
|
|
|
### WF-031: Core Validation Method
|
|
|
|
All status changes go through `_validate_and_set_status()`:
|
|
|
|
```python
|
|
def _validate_and_set_status(
|
|
self,
|
|
task: TaskTable,
|
|
new_status: TaskStatus,
|
|
agent_role: str | None = None,
|
|
) -> None:
|
|
"""
|
|
Validate and set task status with lifecycle enforcement.
|
|
|
|
This is the single point of truth for status changes.
|
|
"""
|
|
```
|
|
|
|
---
|
|
|
|
## Workflow by Role
|
|
|
|
### WF-040: Developer Workflow
|
|
|
|
```
|
|
PENDING
|
|
│ claim()
|
|
▼
|
|
CLAIMED
|
|
│ start()
|
|
▼
|
|
IN_PROGRESS ←──────────────┐
|
|
│ │
|
|
│ submit_for_ │ (from NEEDS_REVISION)
|
|
│ verification() │
|
|
▼ │
|
|
VERIFYING │
|
|
│ │
|
|
│ submit_for_qa() │
|
|
▼ │
|
|
AWAITING_QA ──fail_qa()──► NEEDS_REVISION
|
|
│ │
|
|
│ pass_qa() (by QA) │ claim() + start()
|
|
▼ │
|
|
[QA/Docs workflow] └───────────────────┘
|
|
```
|
|
|
|
**Developer can:**
|
|
- Claim `pending` and `needs_revision` tasks
|
|
- Start, pause, resume work
|
|
- Submit for verification and QA
|
|
- Block (with dependency)
|
|
|
|
**Developer cannot:**
|
|
- Pass/fail QA (that's QA's job)
|
|
- Complete tasks (that's PM's job)
|
|
- Cancel tasks
|
|
|
|
### WF-041: QA Workflow
|
|
|
|
```
|
|
AWAITING_QA
|
|
│ claim()
|
|
▼
|
|
CLAIMED (QA owns)
|
|
│ start()
|
|
▼
|
|
IN_PROGRESS
|
|
│
|
|
├── pass_qa() ────► AWAITING_DOCUMENTATION
|
|
│
|
|
└── fail_qa() ────► NEEDS_REVISION (reassigned to developer)
|
|
```
|
|
|
|
**QA can:**
|
|
- Claim `awaiting_qa` tasks only
|
|
- Pass or fail QA
|
|
- Block tasks
|
|
|
|
**QA cannot:**
|
|
- Claim pending tasks (developers do that)
|
|
- Complete documentation
|
|
- Complete tasks
|
|
|
|
### WF-042: Documenter Workflow
|
|
|
|
```
|
|
AWAITING_DOCUMENTATION
|
|
│ claim()
|
|
▼
|
|
CLAIMED (Documenter owns)
|
|
│ start()
|
|
▼
|
|
IN_PROGRESS
|
|
│ docs_complete()
|
|
▼
|
|
AWAITING_PM_REVIEW
|
|
```
|
|
|
|
**Documenter can:**
|
|
- Claim `awaiting_documentation` tasks
|
|
- Complete documentation
|
|
|
|
**Documenter cannot:**
|
|
- Claim pending tasks
|
|
- Pass/fail QA
|
|
- Complete tasks
|
|
|
|
### WF-043: PM Workflow
|
|
|
|
```
|
|
BACKLOG
|
|
│ activate()
|
|
▼
|
|
PENDING
|
|
│ (developers claim)
|
|
...
|
|
▼
|
|
AWAITING_PM_REVIEW
|
|
│ complete()
|
|
▼
|
|
COMPLETED
|
|
```
|
|
|
|
**PM can:**
|
|
- Create tasks in backlog
|
|
- Activate backlog → pending
|
|
- Complete awaiting_pm_review tasks
|
|
- Cancel any task
|
|
- Unblock blocked tasks
|
|
|
|
---
|
|
|
|
## Quality Gates
|
|
|
|
### WF-050: Before Claiming
|
|
|
|
```markdown
|
|
- [ ] Task is in valid claim status for your role
|
|
- [ ] No existing in_progress task (one at a time)
|
|
- [ ] Dependencies are completed
|
|
```
|
|
|
|
### WF-051: Before Starting
|
|
|
|
```markdown
|
|
- [ ] Task is claimed by you
|
|
- [ ] Plan is documented
|
|
- [ ] Cell channel notified
|
|
```
|
|
|
|
### WF-052: Before Submit to QA
|
|
|
|
```markdown
|
|
- [ ] Tests passing: `uv run pytest`
|
|
- [ ] Linting clean: `uv run ruff check .`
|
|
- [ ] Type check: `uv run mypy roboco/`
|
|
- [ ] Self-review completed
|
|
- [ ] Journal reflection written
|
|
```
|
|
|
|
### WF-053: Before Completion
|
|
|
|
```markdown
|
|
- [ ] QA approved
|
|
- [ ] Documentation complete
|
|
- [ ] PM review approved
|
|
```
|
|
|
|
---
|
|
|
|
## State Categories
|
|
|
|
### WF-060: Helper Functions
|
|
|
|
**Source:** `roboco/enforcement/task_lifecycle.py`
|
|
|
|
| Function | Returns True For |
|
|
|----------|-----------------|
|
|
| `is_terminal_state()` | completed, cancelled |
|
|
| `is_waiting_state()` | blocked, paused, awaiting_qa, awaiting_documentation, awaiting_pm_review |
|
|
| `is_active_state()` | claimed, in_progress, verifying, needs_revision |
|
|
|
|
### WF-061: Terminal States
|
|
|
|
Once a task reaches `COMPLETED` or `CANCELLED`, no further transitions are possible.
|
|
|
|
```python
|
|
get_valid_transitions(TaskStatus.COMPLETED) # Returns []
|
|
get_valid_transitions(TaskStatus.CANCELLED) # Returns []
|
|
```
|
|
|
|
### WF-062: Waiting States
|
|
|
|
Tasks in waiting states are "on hold" pending some external action:
|
|
|
|
- `BLOCKED` - Waiting for blocker task
|
|
- `PAUSED` - Waiting for agent to resume
|
|
- `AWAITING_QA` - Waiting for QA review
|
|
- `AWAITING_DOCUMENTATION` - Waiting for docs
|
|
- `AWAITING_PM_REVIEW` - Waiting for PM approval
|
|
|
|
### WF-063: Active States
|
|
|
|
Tasks where an agent is actively working:
|
|
|
|
- `CLAIMED` - Agent owns, about to start
|
|
- `IN_PROGRESS` - Active development
|
|
- `VERIFYING` - Self-verification
|
|
- `NEEDS_REVISION` - Fixing QA issues
|
|
|
|
---
|
|
|
|
## Quick Reference
|
|
|
|
### Valid Claim Statuses by Role
|
|
|
|
| Role | Can Claim From |
|
|
|------|----------------|
|
|
| Developer | `pending`, `needs_revision` |
|
|
| QA | `awaiting_qa` |
|
|
| Documenter | `awaiting_documentation` |
|
|
| PM | `pending`, `backlog` |
|
|
|
|
### Common Status Flows
|
|
|
|
**Happy Path:**
|
|
```
|
|
backlog → pending → claimed → in_progress → verifying → awaiting_qa
|
|
→ awaiting_documentation → awaiting_pm_review → completed
|
|
```
|
|
|
|
**QA Rejection:**
|
|
```
|
|
awaiting_qa → needs_revision → claimed → in_progress → verifying → awaiting_qa
|
|
```
|
|
|
|
**Direct PM Review (non-dev task):**
|
|
```
|
|
pending → claimed → in_progress → awaiting_pm_review → completed
|
|
```
|
|
|
|
**Cancellation:**
|
|
```
|
|
any_state → cancelled
|
|
```
|