External/roboco
1
0
Fork 0
mirror of https://github.com/rennf93/roboco.git synced 2026-08-03 07:23:24 +02:00
Code Issues Packages Projects Releases Wiki Activity

RAG expansion + Optimal API

Browse Source
This commit is contained in:
Renn F
2025-12-27 21:53:38 +01:00
parent 3f48a93504
commit 1116e597d0
58 changed files with 11768 additions and 7840 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/standards/workflow/task_lifecycle.md
+467
View File
@@ -0,0 +1,467 @@
# 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
```