Adjusted documentation

docs/architecture/README.md

@@ -0,0 +1,52 @@
+# Architecture Documentation
+
+This directory contains detailed architecture documentation for the RoboCo system.
+
+## Documents
+
+| Document | Description |
+|----------|-------------|
+| [Task Lifecycle](./task_lifecycle.md) | Task states, transitions, and workflow enforcement |
+| [Data Model](./data_model.md) | Core entities: Task, Agent, Project, Session, Message, WorkSession |
+| [API Overview](./api_overview.md) | High-level API structure and endpoint categories |
+| [Workspaces](./workspaces.md) | Multi-agent workspace architecture for parallel development |
+
+## Quick Reference
+
+### System Overview
+
+RoboCo is an AI Agentic Company - a virtual organization of 18 AI agents + 1 human CEO. The system implements:
+
+- **Organizational Hierarchy**: CEO, Board (3 agents), Main PM, and 3 Cell teams (Backend, Frontend, UX/UI)
+- **Task Management**: Full lifecycle from backlog to completion with QA and documentation phases
+- **Git Integration**: Per-agent workspaces, branch management, PR workflows
+- **Knowledge Base**: RAG-powered semantic search across code, docs, decisions, and learnings
+- **Communication**: Channel-based messaging with sessions and scoped contexts
+
+### Core Technology Stack
+
+| Layer | Technology |
+|-------|------------|
+| API Framework | FastAPI |
+| Database | PostgreSQL |
+| Cache/Queue | Redis |
+| Vector DB | Qdrant (via pgvector) |
+| Container Runtime | Docker + Docker Compose |
+| Cloud LLM | Claude API |
+| Local LLM | Ollama / vLLM |
+| Embeddings | text-embedding-3-small / local |
+
+### Key Design Principles
+
+1. **Everything is a task** - All work is tracked and documented
+2. **No work without a task** - Create task record first
+3. **No task without acceptance criteria** - How do we know it's done?
+4. **No closure without documentation** - Future agents need context
+5. **State is sacred** - If interrupted, state must be recoverable
+6. **Communication is constant** - Stream reasoning, log everything
+7. **The Auditor sees all** - Quality monitored silently
+
+## Related Documentation
+
+- [CLAUDE.md](../../CLAUDE.md) - Project instructions and coding standards
+- [HOMELAB_TEAM_V0.md](../../HOMELAB_TEAM_V0.md) - Complete system design blueprint

docs/architecture/api_overview.md

@@ -0,0 +1,452 @@
+# API Overview
+
+This document provides a high-level overview of the RoboCo API structure, organized by functional domain.
+
+## API Architecture
+
+The API is built with FastAPI and follows RESTful principles. All endpoints require agent authentication via headers:
+
+```
+X-Agent-ID: <uuid or slug>
+X-Agent-Role: <role>
+X-Agent-Team: <team>
+```
+
+## Route Modules
+
+| Module | Path Prefix | Description |
+|--------|-------------|-------------|
+| `health` | `/health` | Health checks and readiness probes |
+| `agents` | `/agents` | Agent lookup and information |
+| `tasks` | `/tasks` | Task CRUD and lifecycle management |
+| `projects` | `/projects` | Git project/repository management |
+| `work_session` | `/work-sessions` | Work session tracking |
+| `git` | `/git` | Git operations for agents |
+| `channels` | `/channels` | Communication channels |
+| `groups` | `/groups` | Channel groups |
+| `sessions` | `/sessions` | Message sessions |
+| `messages` | `/messages` | Message operations |
+| `notifications` | `/notifications` | Formal notifications |
+| `journals` | `/journals` | Agent journals |
+| `optimal` | `/optimal` | Knowledge base and RAG |
+| `kanban` | `/kanban` | Kanban board views |
+| `dashboard` | `/dashboard` | Dashboard data |
+| `orchestrator` | `/orchestrator` | Agent orchestration |
+| `stream` | `/stream` | WebSocket streaming |
+| `test` | `/test` | Test execution |
+| `a2a` | `/a2a` | Agent-to-Agent protocol |
+
+---
+
+## Task API (`/tasks`)
+
+Full CRUD operations and lifecycle management for tasks.
+
+### CRUD Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/tasks` | Create a new task |
+| `GET` | `/tasks` | List tasks with optional filters |
+| `GET` | `/tasks/my` | Get tasks assigned to current agent |
+| `GET` | `/tasks/pending` | Get pending tasks available to claim |
+| `GET` | `/tasks/blocked` | Get blocked tasks |
+| `GET` | `/tasks/awaiting-qa` | Get tasks awaiting QA review |
+| `GET` | `/tasks/awaiting-docs` | Get tasks awaiting documentation |
+| `GET` | `/tasks/awaiting-pm-review` | Get tasks awaiting PM review |
+| `GET` | `/tasks/awaiting-ceo-approval` | Get CEO approval queue |
+| `GET` | `/tasks/team/{team}` | Get tasks for a specific team |
+| `GET` | `/tasks/stats` | Get task counts by status |
+| `GET` | `/tasks/stats/by-team` | Get task counts by team |
+| `GET` | `/tasks/{task_id}` | Get a specific task with full context |
+| `PUT/PATCH` | `/tasks/{task_id}` | Update a task |
+| `DELETE` | `/tasks/{task_id}` | Delete a task |
+| `GET` | `/tasks/{task_id}/subtasks` | Get immediate subtasks |
+| `GET` | `/tasks/{task_id}/descendants` | Get all descendants (recursive) |
+
+### Lifecycle Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/tasks/{task_id}/claim` | Claim a pending task |
+| `POST` | `/tasks/{task_id}/start` | Start working on claimed task |
+| `POST` | `/tasks/{task_id}/block` | Block task on dependency |
+| `POST` | `/tasks/{task_id}/soft-block` | Block on external factor |
+| `POST` | `/tasks/{task_id}/unblock` | Unblock a task |
+| `POST` | `/tasks/{task_id}/pause` | Pause active task |
+| `POST` | `/tasks/{task_id}/resume` | Resume paused task |
+| `POST` | `/tasks/{task_id}/verify` | Submit for self-verification |
+| `POST` | `/tasks/{task_id}/submit-qa` | Submit to QA |
+| `POST` | `/tasks/{task_id}/pass-qa` | QA passes task |
+| `POST` | `/tasks/{task_id}/fail-qa` | QA fails task |
+| `POST` | `/tasks/{task_id}/docs-complete` | Mark docs complete (documenter) |
+| `POST` | `/tasks/{task_id}/submit-pm-review` | Submit for PM review |
+| `POST` | `/tasks/{task_id}/complete` | Complete task (PM) |
+| `POST` | `/tasks/{task_id}/cancel` | Cancel task (PM) |
+| `POST` | `/tasks/{task_id}/activate` | Activate from backlog (PM) |
+
+### CEO Approval Workflow
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/tasks/{task_id}/escalate-to-ceo` | Escalate to CEO (PM) |
+| `POST` | `/tasks/{task_id}/ceo-approve` | CEO approves |
+| `POST` | `/tasks/{task_id}/ceo-reject` | CEO rejects |
+
+### Escalation & Substitution
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/tasks/{task_id}/escalate` | Escalate to PM/management (all agents) |
+| `POST` | `/tasks/{task_id}/substitute` | Request substitution (assigned agent) |
+
+### Progress & Artifacts
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/tasks/{task_id}/progress` | Add progress update |
+| `POST` | `/tasks/{task_id}/checkpoint` | Add state checkpoint |
+| `POST` | `/tasks/{task_id}/commit` | Link a commit |
+| `GET` | `/tasks/{task_id}/sessions` | Get linked sessions |
+
+---
+
+## Agent API (`/agents`)
+
+Agent lookup and information endpoints.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/agents` | List agents (filter by slug, role, team) |
+| `GET` | `/agents/{agent_id}` | Get agent by ID or slug |
+
+---
+
+## Project API (`/projects`)
+
+CRUD operations for managing git projects/repositories.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/projects` | List projects (filter by cell, active) |
+| `POST` | `/projects` | Register a new project (PM) |
+| `GET` | `/projects/{project_id}` | Get project details |
+| `PUT/PATCH` | `/projects/{project_id}` | Update project |
+| `DELETE` | `/projects/{project_id}` | Delete project |
+| `POST` | `/projects/{project_id}/sync` | Update sync state |
+| `POST` | `/projects/{project_id}/workspace` | Set workspace path |
+
+---
+
+## Git API (`/git`)
+
+Git operations for agents working on code tasks.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/git/{project}/status` | Get git status |
+| `GET` | `/git/{project}/diff` | Get diff |
+| `GET` | `/git/{project}/log` | Get commit log |
+| `GET` | `/git/{project}/branches` | List branches |
+| `POST` | `/git/{project}/branch` | Create a branch |
+| `POST` | `/git/{project}/checkout` | Checkout a branch |
+| `POST` | `/git/{project}/commit` | Create a commit |
+| `POST` | `/git/{project}/push` | Push changes |
+| `POST` | `/git/{project}/pr` | Create a pull request |
+| `POST` | `/git/{project}/pr/merge` | Merge a pull request |
+
+---
+
+## Work Session API (`/work-sessions`)
+
+Work session tracking for git-enabled tasks.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/work-sessions` | List work sessions |
+| `POST` | `/work-sessions` | Create a work session |
+| `GET` | `/work-sessions/{id}` | Get work session details |
+| `PATCH` | `/work-sessions/{id}` | Update work session |
+| `GET` | `/work-sessions/task/{task_id}` | Get work session for task |
+| `GET` | `/work-sessions/agent/{agent_id}` | Get agent's active session |
+
+---
+
+## Messaging API
+
+### Channels (`/channels`)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/channels` | List channels |
+| `POST` | `/channels` | Create a channel |
+| `GET` | `/channels/{slug}` | Get channel by slug |
+| `PUT` | `/channels/{slug}` | Update channel |
+| `DELETE` | `/channels/{slug}` | Delete channel |
+
+### Groups (`/groups`)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/groups` | List groups |
+| `POST` | `/groups` | Create a group |
+| `GET` | `/groups/{id}` | Get group |
+| `PUT` | `/groups/{id}` | Update group |
+| `DELETE` | `/groups/{id}` | Delete group |
+
+### Sessions (`/sessions`)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/sessions` | List sessions |
+| `POST` | `/sessions` | Create a session |
+| `GET` | `/sessions/{id}` | Get session |
+| `POST` | `/sessions/{id}/close` | Close session |
+| `POST` | `/sessions/{id}/messages` | Add message to session |
+| `GET` | `/sessions/{id}/messages` | Get session messages |
+| `POST` | `/sessions/for-tasks` | Create session for tasks (PM) |
+| `POST` | `/sessions/{id}/link-task` | Link task to session |
+
+### Messages (`/messages`)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/messages` | List messages |
+| `POST` | `/messages` | Create a message |
+| `GET` | `/messages/{id}` | Get message |
+| `PUT` | `/messages/{id}` | Edit message |
+
+---
+
+## Notifications API (`/notifications`)
+
+Formal notification management.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/notifications` | List notifications |
+| `GET` | `/notifications/unread` | Get unread notifications |
+| `POST` | `/notifications` | Create notification (PM/Board) |
+| `GET` | `/notifications/{id}` | Get notification |
+| `POST` | `/notifications/{id}/ack` | Acknowledge notification |
+| `POST` | `/notifications/{id}/read` | Mark as read |
+
+---
+
+## Journal API (`/journals`)
+
+Agent personal journal management.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/journals` | Get current agent's journal |
+| `GET` | `/journals/{agent_id}` | Get agent's journal |
+| `POST` | `/journals/entries` | Create journal entry |
+| `GET` | `/journals/entries` | List entries |
+| `GET` | `/journals/entries/{id}` | Get entry |
+
+---
+
+## Optimal API (`/optimal`)
+
+Knowledge base, RAG queries, and semantic search.
+
+### Indexing
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/optimal/kb/index/code` | Index code files |
+| `POST` | `/optimal/kb/index/docs` | Index documentation |
+| `POST` | `/optimal/kb/refresh` | Refresh an index |
+| `POST` | `/optimal/kb/reindex` | Trigger full reindex |
+| `DELETE` | `/optimal/kb/{index_type}` | Clear an index |
+| `GET` | `/optimal/kb/{index_type}/documents` | List indexed documents |
+
+### Search & RAG
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/optimal/kb/search` | Semantic search |
+| `GET` | `/optimal/kb/similar` | Find similar documents |
+| `POST` | `/optimal/rag/query` | RAG query with answer |
+| `POST` | `/optimal/rag/context` | Get context without answer |
+
+### Knowledge Services
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/optimal/mentor/ask` | Ask the organizational knowledge base |
+| `POST` | `/optimal/errors/search` | Search for error solutions |
+| `POST` | `/optimal/errors/record` | Record error solution |
+| `POST` | `/optimal/decisions/check` | Check for precedent decisions |
+| `POST` | `/optimal/decisions/record` | Record a decision |
+| `POST` | `/optimal/standards/get` | Get coding/security standards |
+| `POST` | `/optimal/standards/validate` | Validate action against standards |
+| `POST` | `/optimal/review/code` | Code review |
+| `POST` | `/optimal/learnings/record` | Record a learning |
+| `POST` | `/optimal/learnings/search` | Search learnings |
+| `POST` | `/optimal/context/proactive` | Get proactive context for task |
+
+### Management
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/optimal/stats` | Get all index statistics |
+| `GET` | `/optimal/stats/{index_type}` | Get single index stats |
+| `GET` | `/optimal/health` | RAG system health check |
+| `POST` | `/optimal/tokens/estimate` | Estimate token count |
+| `POST` | `/optimal/prompts` | Create prompt template |
+| `GET` | `/optimal/prompts` | List prompt templates |
+
+---
+
+## Kanban API (`/kanban`)
+
+Kanban board views for task management.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/kanban/board` | Get kanban board data |
+| `GET` | `/kanban/board/{team}` | Get team kanban board |
+| `GET` | `/kanban/swimlanes` | Get swimlane view |
+
+---
+
+## Dashboard API (`/dashboard`)
+
+Dashboard data and metrics.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/dashboard/summary` | Get dashboard summary |
+| `GET` | `/dashboard/metrics` | Get system metrics |
+| `GET` | `/dashboard/activity` | Get recent activity |
+
+---
+
+## Orchestrator API (`/orchestrator`)
+
+Agent orchestration and management.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/orchestrator/spawn` | Spawn an agent |
+| `POST` | `/orchestrator/terminate` | Terminate an agent |
+| `GET` | `/orchestrator/status` | Get orchestrator status |
+
+---
+
+## Stream API (`/stream`)
+
+WebSocket streaming for real-time communication.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `WS` | `/stream/connect` | WebSocket connection |
+| `WS` | `/stream/channel/{slug}` | Channel stream |
+| `WS` | `/stream/agent/{id}` | Agent stream |
+
+---
+
+## Test API (`/test`)
+
+Test execution endpoints.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/test/run` | Run tests in workspace |
+| `GET` | `/test/results/{id}` | Get test results |
+
+---
+
+## A2A API (`/a2a`)
+
+Agent-to-Agent protocol support.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/a2a/.well-known/agent.json` | Agent discovery |
+| `POST` | `/a2a/tasks/send` | Send task to agent |
+| `GET` | `/a2a/tasks/{id}/status` | Get task status |
+
+---
+
+## Health API (`/health`)
+
+System health and readiness.
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `GET` | `/health` | Basic health check |
+| `GET` | `/health/ready` | Readiness probe |
+| `GET` | `/health/live` | Liveness probe |
+
+---
+
+## Permission Model
+
+The API enforces role-based permissions:
+
+### Task Actions
+
+| Action | Allowed Roles |
+|--------|---------------|
+| `CREATE` | PM, Board, CEO |
+| `VIEW_ALL` | Main PM, Board, CEO, Auditor |
+| `CLAIM` | Developers, QA, Documenters (own team) |
+| `UPDATE_OWN` | Assigned agent or creator |
+| `ASSIGN` | PM, Board, CEO |
+| `CHANGE_PRIORITY` | PM, Board, CEO |
+| `CLOSE` | PM, Board, CEO |
+
+### KB Actions
+
+| Action | Allowed Roles |
+|--------|---------------|
+| `INDEX_CODE` | PM, Board, CEO |
+| `INDEX_DOCS` | PM, Board, CEO |
+| `VIEW_STATS` | All authenticated agents |
+| `CLEAR_INDEX` | PM, Board, CEO |
+| `REFRESH_INDEX` | PM, Board, CEO |
+
+### Notification Permissions
+
+Only specific roles can send formal notifications:
+- `cell_pm`
+- `main_pm`
+- `product_owner`
+- `head_marketing`
+- `auditor`
+
+---
+
+## Error Responses
+
+All endpoints return standard error responses:
+
+```json
+{
+  "detail": "Error message describing what went wrong"
+}
+```
+
+Common HTTP status codes:
+
+| Code | Meaning |
+|------|---------|
+| `400` | Bad Request - Invalid input |
+| `401` | Unauthorized - Missing authentication |
+| `403` | Forbidden - Insufficient permissions |
+| `404` | Not Found - Resource doesn't exist |
+| `500` | Internal Server Error |
+| `504` | Gateway Timeout - Operation timed out |
+
+---
+
+## Rate Limiting
+
+Currently, no rate limiting is implemented. This is planned for future versions.
+
+## Versioning
+
+The API does not currently implement versioning. Breaking changes will be documented in release notes.

docs/architecture/data_model.md

@@ -0,0 +1,525 @@
+# Data Model
+
+This document describes the core entities in the RoboCo system, their relationships, and key fields.
+
+## Entity Relationship Overview
+
+```
+                              +--------+
+                              |  CEO   |
+                              +---+----+
+                                  |
+                                  v
++--------+     +----------+    +-------+    +---------+
+| Project| <-- |WorkSession| -- | Task  | -- | Agent   |
++---+----+     +----------+    +---+---+    +----+----+
+    |                              |             |
+    |                              |             |
+    v                              v             v
++----------+               +---------------+  +----------+
+| Workspace|               | SessionTask   |  | Journal  |
+| (on disk)|               | (many-to-many)|  +----+-----+
++----------+               +-------+-------+       |
+                                   |               v
+                                   v         +-------------+
+                              +----------+   |JournalEntry |
+                              | Session  |   +-------------+
+                              +----+-----+
+                                   |
+                                   v
+                              +----------+
+                              | Message  |
+                              +----------+
+
++----------+     +-------+     +---------+
+| Channel  | --> | Group | --> | Session |
++----------+     +-------+     +---------+
+
++---------------+
+| Notification  |
++---------------+
+
++---------------+
+| Handoff       | (Reserved for future use)
++---------------+
+
++------------------+
+| IndexedDocument  | (Knowledge base tracking)
++------------------+
+```
+
+## Core Entities
+
+### Agent
+
+Represents an AI agent in the organization. Each agent has a role, team affiliation, capabilities, and permissions.
+
+**Table**: `agents`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Primary key |
+| `name` | String(100) | Display name |
+| `slug` | String(50) | URL-safe identifier (e.g., `be-dev-1`) |
+| `role` | Enum | `developer`, `qa`, `documenter`, `cell_pm`, `main_pm`, `product_owner`, `head_marketing`, `auditor`, `ceo`, `system` |
+| `team` | Enum | `backend`, `frontend`, `ux_ui`, `main_pm`, `board`, `marketing` (nullable for board members) |
+| `status` | Enum | `active`, `idle`, `offline` |
+| `current_task_id` | UUID | Currently assigned task (FK) |
+| `model_config` | JSON | LLM configuration (provider, model name, temperature, etc.) |
+| `system_prompt` | Text | Base system prompt for this agent |
+| `capabilities` | Array[String] | List of capabilities (`code_execution`, `git_operations`, etc.) |
+| `permissions` | JSON | Channel access permissions |
+| `metrics` | JSON | Performance metrics (tasks completed, quality score, etc.) |
+| `journal_id` | UUID | Agent's personal journal ID |
+| `description` | Text | Human-readable description |
+| `created_at` | Timestamp | Creation time |
+| `updated_at` | Timestamp | Last update time |
+
+**Agent Roles**:
+- **Executive**: `ceo`
+- **Board**: `product_owner`, `head_marketing`, `auditor`
+- **Management**: `main_pm`, `cell_pm`
+- **Cell Members**: `developer`, `qa`, `documenter`
+- **System**: `system` (internal orchestrator)
+
+---
+
+### Task
+
+The atomic unit of work in RoboCo. Every piece of work follows the universal task lifecycle.
+
+**Table**: `tasks`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Primary key |
+| `title` | String(200) | Task title |
+| `description` | Text | Detailed description |
+| `acceptance_criteria` | Array[String] | How we know it's done |
+| `status` | Enum | Current lifecycle state (see [Task Lifecycle](./task_lifecycle.md)) |
+| `priority` | Integer | 0=P0 (highest) to 3=P3 (lowest) |
+| `task_type` | Enum | `code`, `documentation`, `research`, `planning`, `design`, `administrative` |
+| `requires_git` | Boolean | Whether git workflow applies |
+| `project_id` | UUID | Associated project (FK) |
+| `branch_name` | String(500) | Git branch for this task |
+| `work_session_id` | UUID | Active work session (FK) |
+| `pr_number` | Integer | GitHub/GitLab PR number |
+| `pr_url` | String(500) | Full URL to PR |
+| `docs_complete` | Boolean | Documenter has finished |
+| `pr_created` | Boolean | Developer has created PR |
+| `pm_approvals` | JSON | PM approval tracking |
+| `created_by` | UUID | Agent who created the task (FK) |
+| `assigned_to` | UUID | Currently assigned agent (FK) |
+| `team` | Enum | Which cell owns this task |
+| `parent_task_id` | UUID | Parent task for sub-tasks (FK) |
+| `dependency_ids` | Array[UUID] | Tasks this is blocked by |
+| `blocker_ids` | Array[UUID] | Tasks this is blocking |
+| `claimed_at` | Timestamp | When task was claimed |
+| `started_at` | Timestamp | When work started |
+| `completed_at` | Timestamp | When task completed |
+| `target_date` | Timestamp | Target completion date |
+| `plan` | JSON | Implementation plan (sub-tasks, risks, questions) |
+| `estimated_complexity` | Enum | `low`, `medium`, `high` |
+| `execution_log` | JSON | Execution events and errors |
+| `checkpoints` | JSON | State recovery checkpoints |
+| `progress_updates` | JSON | Progress update history |
+| `commits` | JSON | Linked commits |
+| `documents` | JSON | Linked documents |
+| `outputs` | JSON | Output artifacts |
+| `dev_notes` | Text | Developer journey notes |
+| `qa_notes` | Text | QA feedback |
+| `auditor_notes` | Text | Auditor observations |
+| `self_verified` | Boolean | Self-verification passed |
+| `qa_verified` | Boolean | QA verification result |
+| `quick_context` | Text | 2-3 sentences for quick context restoration |
+| `proactive_context` | JSON | RAG context injected when claimed |
+| `created_at` | Timestamp | Creation time |
+| `updated_at` | Timestamp | Last update time |
+
+**Indexes**:
+- `ix_tasks_team_status` - Team + Status queries
+- `ix_tasks_assigned_status` - Assignee + Status queries
+- `ix_tasks_project_status` - Project + Status queries
+
+---
+
+### Project
+
+A git repository that agents work on. Projects are registered by PMs and contain configuration for the development workflow.
+
+**Table**: `projects`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Primary key |
+| `name` | String(100) | Project name |
+| `slug` | String(50) | URL-safe identifier (e.g., `roboco`, `roboco-panel`) |
+| `git_url` | String(500) | Git repository URL |
+| `default_branch` | String(100) | Default branch (default: `main`) |
+| `protected_branches` | Array[String] | Branches that cannot be pushed directly |
+| `test_command` | String(500) | Command to run tests |
+| `lint_command` | String(500) | Command to run linter |
+| `format_command` | String(500) | Command to format code |
+| `typecheck_command` | String(500) | Command to run type checker |
+| `build_command` | String(500) | Command to build |
+| `assigned_cell` | Enum | Which cell owns this project |
+| `allowed_agents` | Array[UUID] | Specific agents allowed (null = all in cell) |
+| `workspace_path` | String(500) | Local workspace path |
+| `last_synced_at` | Timestamp | Last sync from remote |
+| `head_commit` | String(40) | Current HEAD commit SHA |
+| `created_by` | UUID | PM who registered the project (FK) |
+| `is_active` | Boolean | Whether project is active |
+| `created_at` | Timestamp | Creation time |
+| `updated_at` | Timestamp | Last update time |
+
+---
+
+### WorkSession
+
+Tracks an agent's working session on a task, including branch management, commits, and PR tracking.
+
+**Table**: `work_sessions`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Primary key |
+| `project_id` | UUID | Project being worked on (FK) |
+| `task_id` | UUID | Task being worked on (FK) |
+| `agent_id` | UUID | Agent doing the work (FK) |
+| `branch_name` | String(500) | Full branch name |
+| `base_branch` | String(500) | Branch this was forked from |
+| `target_branch` | String(500) | Branch to merge into |
+| `started_at` | Timestamp | Session start time |
+| `ended_at` | Timestamp | Session end time |
+| `status` | Enum | `active`, `completed`, `abandoned` |
+| `commits` | Array[String] | Commit SHAs made in this session |
+| `files_modified` | Array[String] | Files touched in this session |
+| `pr_number` | Integer | PR number |
+| `pr_url` | String(500) | Full URL to PR |
+| `pr_status` | String(50) | `open`, `merged`, `closed` |
+| `pr_created_at` | Timestamp | When PR was created |
+| `pr_merged_at` | Timestamp | When PR was merged |
+| `merged_by` | UUID | Agent who merged the PR (FK) |
+| `created_at` | Timestamp | Creation time |
+| `updated_at` | Timestamp | Last update time |
+
+---
+
+### Session
+
+Sessions group messages within boundaries (time, count, content length). They are automatically created and closed based on configuration.
+
+**Table**: `sessions`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Primary key (sesh_id) |
+| `group_id` | UUID | Parent group (FK) |
+| `max_time_window` | Interval | Maximum session duration (default: 30 min) |
+| `max_message_count` | Integer | Maximum messages per session (default: 100) |
+| `max_content_length` | Integer | Maximum total characters (default: 50000) |
+| `timeout_seconds` | Integer | Inactivity timeout (default: 300) |
+| `status` | Enum | `active`, `closed`, `timed_out` |
+| `scope` | Enum | `initiative`, `cell`, `task` |
+| `started_at` | Timestamp | Session start time |
+| `last_activity_at` | Timestamp | Last activity time |
+| `closed_at` | Timestamp | Session close time |
+| `message_count` | Integer | Number of messages |
+| `total_content_length` | Integer | Total character count |
+| `created_at` | Timestamp | Creation time |
+
+**Session Scopes**:
+- `initiative`: Cross-cell coordination (Main PM, #dev-all)
+- `cell`: Cell-specific work (Cell PM, #backend-cell)
+- `task`: Individual task execution (Developer level)
+
+---
+
+### SessionTask (Junction Table)
+
+Many-to-many relationship between Sessions and Tasks. PMs can create work sessions as discussion contexts for tasks.
+
+**Table**: `session_tasks`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Primary key |
+| `session_id` | UUID | Session (FK) |
+| `task_id` | UUID | Task (FK) |
+| `is_primary` | Boolean | Primary discussion session for this task |
+| `relationship_type` | String(50) | `discussion`, `planning`, `review`, `retrospective` |
+| `added_at` | Timestamp | When link was created |
+| `added_by` | UUID | PM who created the link (FK) |
+
+---
+
+### Message
+
+Extracted, stored message from agent streams. Messages are the atomic unit of communication.
+
+**Table**: `messages`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Primary key (msg_id) |
+| `agent_id` | UUID | Agent who sent the message (FK) |
+| `channel_id` | UUID | Channel the message is in (FK) |
+| `group_id` | UUID | Group the message belongs to (FK) |
+| `session_id` | UUID | Session ID (FK) |
+| `type` | Enum | `reasoning`, `dialogue`, `decision`, `action`, `blocker`, `technical` |
+| `content` | Text | Message content |
+| `content_length` | Integer | Character count |
+| `is_reply` | Boolean | Whether this is a reply |
+| `reply_to` | UUID | Parent message ID (FK) |
+| `mentions` | Array[UUID] | Agent IDs mentioned |
+| `task_id` | UUID | Related task ID (FK) |
+| `commit_ref` | String(40) | Related commit hash |
+| `timestamp` | Timestamp | Message timestamp |
+| `confidence` | Float | Extraction confidence |
+| `raw_excerpt` | Text | Original text before extraction |
+| `edited_at` | Timestamp | Last edit time |
+| `edit_history` | JSON | Previous versions |
+| `created_at` | Timestamp | Creation time |
+
+---
+
+### Channel
+
+Communication channels for agent messaging.
+
+**Table**: `channels`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Primary key |
+| `name` | String(100) | Channel name |
+| `slug` | String(50) | URL-safe identifier |
+| `type` | Enum | `cell`, `cross_cell`, `management`, `special` |
+| `description` | Text | Channel description |
+| `topic` | String(500) | Current topic |
+| `members` | Array[UUID] | Member agent IDs |
+| `writers` | Array[UUID] | Agents with write access |
+| `silent_observers` | Array[UUID] | Agents with silent read access (Auditor) |
+| `is_archived` | Boolean | Whether channel is archived |
+| `is_private` | Boolean | Private channel flag |
+| `allow_threads` | Boolean | Whether threads are allowed |
+| `allow_reactions` | Boolean | Whether reactions are allowed |
+| `message_retention_days` | Integer | Message retention (default: 90) |
+| `max_message_length` | Integer | Maximum message length (default: 10000) |
+| `message_count` | Integer | Total messages |
+| `group_count` | Integer | Total groups |
+| `last_activity` | Timestamp | Last activity time |
+| `created_at` | Timestamp | Creation time |
+| `updated_at` | Timestamp | Last update time |
+
+**Channel Types**:
+- `cell`: Internal team channels (#backend-cell, #frontend-cell, #uxui-cell)
+- `cross_cell`: Coordination channels (#dev-all, #qa-all, #pm-all, #doc-all)
+- `management`: Management channels (#main-pm-board, #board-private)
+- `special`: Special channels (#announcements, #all-hands)
+
+---
+
+### Group
+
+Groups within channels, used to organize conversations.
+
+**Table**: `groups`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Primary key |
+| `name` | String(100) | Group name |
+| `channel_id` | UUID | Parent channel (FK) |
+| `allowed_roles` | Array[String] | Roles allowed in this group |
+| `hierarchy_level` | Integer | Hierarchy level (default: 4) |
+| `members` | Array[UUID] | Member agent IDs |
+| `is_active` | Boolean | Whether group is active |
+| `active_session_id` | UUID | Current active session |
+| `default_session_config` | JSON | Session boundary configuration |
+| `total_sessions` | Integer | Total sessions |
+| `total_messages` | Integer | Total messages |
+| `last_activity` | Timestamp | Last activity time |
+| `created_at` | Timestamp | Creation time |
+| `updated_at` | Timestamp | Last update time |
+
+---
+
+### Notification
+
+Formal notifications requiring acknowledgment.
+
+**Table**: `notifications`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Primary key |
+| `type` | Enum | `task_assignment`, `priority_change`, `blocker_escalation`, `review_request`, `documentation_request`, `alert`, `broadcast`, `knowledge_share`, `mention` |
+| `priority` | Enum | `normal`, `high`, `urgent` |
+| `from_agent` | UUID | Sender agent (FK) |
+| `to_agents` | Array[UUID] | Recipient agent IDs |
+| `subject` | String(200) | Notification subject |
+| `body` | Text | Notification body |
+| `requires_ack` | Boolean | Requires acknowledgment |
+| `acked_by` | Array[UUID] | Agents who acknowledged |
+| `acked_at` | JSON | Acknowledgment timestamps |
+| `related_task_id` | UUID | Related task (FK) |
+| `related_message_ids` | Array[UUID] | Related message IDs |
+| `timestamp` | Timestamp | Notification timestamp |
+| `expires_at` | Timestamp | Expiration time |
+| `read_by` | Array[UUID] | Agents who read |
+| `delivered_at` | Timestamp | Delivery time |
+| `created_at` | Timestamp | Creation time |
+
+---
+
+### Journal
+
+Agent personal journal for reflections and growth tracking.
+
+**Table**: `journals`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Primary key |
+| `agent_id` | UUID | Agent owner (FK, unique) |
+| `total_entries` | Integer | Entry count |
+| `last_entry_at` | Timestamp | Last entry time |
+| `latest_summary` | Text | Latest summary |
+| `summary_updated_at` | Timestamp | Summary update time |
+| `entries_by_type` | JSON | Entry counts by type |
+| `created_at` | Timestamp | Creation time |
+| `updated_at` | Timestamp | Last update time |
+
+---
+
+### JournalEntry
+
+Individual journal entries.
+
+**Table**: `journal_entries`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Primary key |
+| `journal_id` | UUID | Parent journal (FK) |
+| `type` | Enum | `task_reflection`, `decision_log`, `learning`, `struggle`, `general` |
+| `title` | String(200) | Entry title |
+| `content` | Text | Entry content |
+| `task_id` | UUID | Related task (FK) |
+| `session_id` | UUID | Related session (FK) |
+| `timestamp` | Timestamp | Entry timestamp |
+| `tags` | Array[String] | Entry tags |
+| `sentiment` | String(50) | Entry sentiment |
+| `is_private` | Boolean | Private entry flag |
+| `created_at` | Timestamp | Creation time |
+| `updated_at` | Timestamp | Last update time |
+
+---
+
+### IndexedDocument
+
+Tracks documents indexed into the knowledge base.
+
+**Table**: `indexed_documents`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Primary key |
+| `index_type` | String(50) | `code`, `docs`, `conversations`, `journals`, `errors`, `standards`, etc. |
+| `source` | String(1000) | Source path/URL |
+| `source_hash` | String(64) | SHA256 for deduplication |
+| `title` | String(500) | Document title |
+| `preview` | Text | First 500 chars for UI |
+| `chunk_count` | Integer | Number of chunks |
+| `extra_data` | JSON | Additional metadata |
+| `indexed_at` | Timestamp | Indexing time |
+| `updated_at` | Timestamp | Last update time |
+
+---
+
+### Handoff (Reserved)
+
+Structured documentation handoffs. Currently unused - reserved for future implementation.
+
+**Table**: `handoffs`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | UUID | Primary key |
+| `task_id` | UUID | Related task (FK, unique) |
+| `summary` | Text | Handoff summary |
+| `new_functionality` | Array[String] | New features |
+| `modified_behavior` | Array[String] | Modified behaviors |
+| `breaking_changes` | Array[String] | Breaking changes |
+| `required_docs` | JSON | Required documentation items |
+| `optional_docs` | JSON | Optional documentation items |
+| `commits` | JSON | Key commits |
+| `new_files` | JSON | New file locations |
+| `modified_files` | JSON | Modified file locations |
+| `key_conversations` | JSON | Key conversations |
+| `code_samples` | JSON | Code samples |
+| `gotchas` | JSON | Gotchas and warnings |
+| `related_docs` | Array[String] | Related documentation |
+| `changelog_entry` | Text | Changelog entry |
+| `key_learnings` | Array[String] | Key learnings |
+| `key_decisions` | JSON | Key decisions |
+| `questions` | Array[String] | Open questions |
+| `dev_notes_location` | String(500) | Dev notes file path |
+| `status` | Enum | `pending`, `claimed`, `in_progress`, `accepted`, `completed` |
+| `assigned_to` | UUID | Assigned documenter (FK) |
+| `documenter_notes` | Text | Documenter feedback |
+| `created_at` | Timestamp | Creation time |
+| `updated_at` | Timestamp | Last update time |
+| `claimed_at` | Timestamp | Claim time |
+| `completed_at` | Timestamp | Completion time |
+
+## Enumerations
+
+### TaskStatus
+`backlog`, `pending`, `claimed`, `in_progress`, `blocked`, `paused`, `verifying`, `needs_revision`, `awaiting_qa`, `awaiting_documentation`, `awaiting_pm_review`, `awaiting_ceo_approval`, `completed`, `cancelled`
+
+### TaskType
+`code`, `documentation`, `research`, `planning`, `design`, `administrative`
+
+### Complexity
+`low`, `medium`, `high`
+
+### Team
+`backend`, `frontend`, `ux_ui`, `main_pm`, `board`, `marketing`
+
+### AgentRole
+`system`, `ceo`, `product_owner`, `head_marketing`, `auditor`, `main_pm`, `cell_pm`, `developer`, `qa`, `documenter`
+
+### AgentStatus
+`active`, `idle`, `offline`
+
+### SessionStatus
+`active`, `closed`, `timed_out`
+
+### SessionScope
+`initiative`, `cell`, `task`
+
+### MessageType
+`reasoning`, `dialogue`, `decision`, `action`, `blocker`, `technical`
+
+### NotificationType
+`task_assignment`, `priority_change`, `blocker_escalation`, `review_request`, `documentation_request`, `alert`, `broadcast`, `knowledge_share`, `mention`
+
+### NotificationPriority
+`normal`, `high`, `urgent`
+
+### ChannelType
+`cell`, `cross_cell`, `management`, `special`
+
+### JournalEntryType
+`task_reflection`, `decision_log`, `learning`, `struggle`, `general`
+
+### WorkSessionStatus
+`active`, `completed`, `abandoned`
+
+### HandoffStatus
+`pending`, `claimed`, `in_progress`, `accepted`, `completed`
+
+### ModelProvider
+`anthropic`, `openai`, `local`

docs/architecture/task_lifecycle.md

@@ -0,0 +1,302 @@
+# Task Lifecycle
+
+This document describes all task states, valid transitions, and workflow enforcement in the RoboCo system.
+
+## Task States
+
+Tasks follow a defined lifecycle from creation to completion. Each state represents a specific phase of work.
+
+### State Definitions
+
+| State | Description |
+|-------|-------------|
+| `backlog` | PM setup phase - task with dependencies or needs session setup |
+| `pending` | Ready for work - orchestrator can spawn agents |
+| `claimed` | Agent has taken ownership but not started |
+| `in_progress` | Active work being performed |
+| `blocked` | Waiting on another task or external dependency |
+| `paused` | Temporarily suspended by the assigned agent |
+| `verifying` | Self-verification by the developer |
+| `needs_revision` | QA or CEO has requested changes |
+| `awaiting_qa` | Ready for QA review |
+| `awaiting_documentation` | Docs + Developer PR creation in parallel |
+| `awaiting_pm_review` | After docs + PR ready, PM reviews |
+| `awaiting_ceo_approval` | PMs approved, CEO makes final decision |
+| `completed` | Task finished successfully (terminal) |
+| `cancelled` | Task cancelled (terminal) |
+| `quarantined` | Special state for problematic tasks |
+
+### State Categories
+
+```python
+# Terminal states - cannot transition out
+TERMINAL_STATES = ["completed", "cancelled"]
+
+# Waiting states - agent can work on other tasks
+WAITING_STATES = [
+    "blocked",
+    "paused",
+    "awaiting_qa",
+    "awaiting_documentation",
+    "awaiting_pm_review",
+    "awaiting_ceo_approval",
+]
+
+# Active states - agent is actively working
+ACTIVE_STATES = ["claimed", "in_progress", "verifying", "needs_revision"]
+```
+
+## State Transition Diagram
+
+```
+                                    +-----------+
+                                    | quarantined|
+                                    +-----+-----+
+                                          |
+                                          v
++--------+     +----------+     +---------+     +-------------+
+| backlog| --> | pending  | --> | claimed | --> | in_progress |
++---+----+     +----+-----+     +----+----+     +------+------+
+    |               |                |                 |
+    v               v                v                 |
++---------+    +---------+     +-----------+           |
+|cancelled|    |cancelled|     | pending   |           |
++---------+    +---------+     |(unclaim)  |           |
+                               +-----------+           |
+                                                       |
+                   +-----------------------------------+
+                   |                |              |   |
+                   v                v              v   v
+            +----------+     +----------+    +---------+
+            | blocked  |     | paused   |    |verifying|
+            +----+-----+     +----+-----+    +----+----+
+                 |                |               |
+                 v                v               |
+            in_progress     in_progress          |
+                                                 |
+                   +-----------------------------+
+                   |                |            |
+                   v                v            v
+            +-------------+  +---------------+  +---------------------+
+            | awaiting_qa |  |needs_revision |  |awaiting_documentation|
+            +------+------+  +-------+-------+  +----------+----------+
+                   |                 |                     |
+                   |                 v                     |
+                   |           claimed/in_progress         |
+                   |                                       |
+                   +-----------------+---------------------+
+                                     |
+                                     v
+                            +------------------+
+                            |awaiting_pm_review|
+                            +--------+---------+
+                                     |
+           +-------------------------+-------------------------+
+           |                         |                         |
+           v                         v                         v
+    +-----------+          +--------------------+        +-----------+
+    | completed |          |awaiting_ceo_approval|       | cancelled |
+    +-----------+          +---------+----------+        +-----------+
+                                     |
+           +-------------------------+-------------------------+
+           |                         |                         |
+           v                         v                         v
+    +-----------+            +---------------+           +-----------+
+    | completed |            | needs_revision|           | cancelled |
+    +-----------+            +---------------+           +-----------+
+```
+
+## Valid Transitions
+
+The following table shows all valid state transitions:
+
+| From State | To States |
+|------------|-----------|
+| `backlog` | `pending`, `cancelled` |
+| `pending` | `claimed`, `cancelled` |
+| `claimed` | `in_progress`, `pending`, `cancelled` |
+| `in_progress` | `blocked`, `paused`, `verifying`, `awaiting_pm_review`, `awaiting_documentation`, `needs_revision`, `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`, `awaiting_ceo_approval`, `completed`, `cancelled` |
+| `awaiting_ceo_approval` | `completed`, `needs_revision`, `cancelled` |
+| `completed` | (none - terminal) |
+| `cancelled` | (none - terminal) |
+| `quarantined` | `pending` |
+
+## Role-Based Restrictions
+
+Certain transitions require specific roles:
+
+### PM-Only Transitions
+- `backlog` -> `pending` (activate task)
+- `awaiting_pm_review` -> `completed`
+- `awaiting_pm_review` -> `awaiting_ceo_approval`
+- `in_progress` -> `completed` (PM completing their own task)
+- All cancellation transitions
+
+### QA-Only Transitions
+- `awaiting_qa` -> `claimed` (QA claims)
+- `awaiting_qa` -> `awaiting_documentation` (QA pass)
+- `awaiting_qa` -> `needs_revision` (QA fail)
+- `in_progress` -> `awaiting_documentation` (direct QA assignment pass)
+- `in_progress` -> `needs_revision` (direct QA assignment fail)
+
+### Documenter-Only Transitions
+- `awaiting_documentation` -> `claimed` (Documenter claims)
+- `awaiting_documentation` -> `awaiting_pm_review` (Docs complete)
+
+### CEO-Only Transitions
+- `awaiting_ceo_approval` -> `completed` (CEO approves)
+- `awaiting_ceo_approval` -> `needs_revision` (CEO requests changes)
+- `awaiting_ceo_approval` -> `cancelled` (CEO cancels)
+
+### PM Cancel Roles
+The following roles can cancel tasks:
+- `cell_pm`
+- `main_pm`
+- `product_owner`
+- `head_marketing`
+
+## Git Integration
+
+Tasks with `requires_git=True` have additional requirements:
+
+### Git Workflow Requirements
+
+1. **Starting Work** (`claimed` -> `in_progress`):
+   - Task must have `branch_name` set (PM created the branch)
+
+2. **Documentation to PM Review** (`awaiting_documentation` -> `awaiting_pm_review`):
+   - Requires BOTH `docs_complete=True` AND `pr_created=True`
+   - Documenter and Developer work in parallel during this phase
+
+3. **PM Review to CEO Approval** (`awaiting_pm_review` -> `awaiting_ceo_approval`):
+   - Task must have `pr_number` set (PR exists)
+
+4. **CEO Approval to Completed** (`awaiting_ceo_approval` -> `completed`):
+   - PR should be merged (CEO merges as final action)
+
+### Parallel Execution Phase
+
+During `awaiting_documentation`:
+- **Documenter**: Works on docs, calls `roboco_task_docs_complete()` when done
+- **Developer**: Creates PR, calls `roboco_git_create_pr()` when ready
+
+Both must complete before transitioning to `awaiting_pm_review`.
+
+```python
+def check_parallel_completion(docs_complete: bool, pr_created: bool, requires_git: bool = True) -> bool:
+    """Check if parallel execution is complete."""
+    if not requires_git:
+        return docs_complete
+    return docs_complete and pr_created
+```
+
+## Task Types
+
+Task types determine whether git workflow applies:
+
+| Type | Git Required | Description |
+|------|-------------|-------------|
+| `code` | Yes | Technical work - full git workflow |
+| `documentation` | Optional | May or may not need git |
+| `research` | No | Investigation/analysis tasks |
+| `planning` | No | Planning and design tasks |
+| `design` | No | UX/UI design tasks |
+| `administrative` | No | Administrative tasks |
+
+## Workflow Enforcement
+
+The `task_lifecycle.py` module enforces these rules:
+
+```python
+from roboco.enforcement.task_lifecycle import (
+    validate_task_transition,
+    validate_git_requirements,
+    can_agent_transition,
+    is_terminal_state,
+    is_waiting_state,
+    is_active_state,
+)
+
+# Validate a transition
+validate_task_transition(
+    current_status="in_progress",
+    target_status="verifying",
+    agent_role="developer"
+)
+
+# Check git requirements
+from roboco.enforcement.task_lifecycle import GitContext
+
+git_ctx = GitContext(
+    requires_git=True,
+    docs_complete=True,
+    pr_created=True,
+    pr_number=42,
+    branch_name="feature/backend/ABC123"
+)
+
+validate_git_requirements(
+    current_status="awaiting_documentation",
+    target_status="awaiting_pm_review",
+    git_ctx=git_ctx
+)
+```
+
+## Exceptions
+
+The lifecycle module raises specific exceptions:
+
+- `TaskLifecycleError`: Invalid state transition or role not permitted
+- `GitRequirementError`: Git requirements not met for a transition
+
+Example error handling:
+
+```python
+from roboco.exceptions import TaskLifecycleError
+from roboco.enforcement.task_lifecycle import GitRequirementError
+
+try:
+    validate_task_transition("pending", "in_progress", "developer")
+except TaskLifecycleError as e:
+    print(f"Invalid transition: {e.current_status} -> {e.target_status}")
+    print(f"Valid transitions: {e.valid_transitions}")
+
+try:
+    validate_git_requirements("claimed", "in_progress", git_ctx)
+except GitRequirementError as e:
+    print(f"Git requirement not met: {e.requirement}")
+    print(f"Message: {e.message}")
+```
+
+## Related API Endpoints
+
+Task lifecycle operations are exposed via the Task API:
+
+| Endpoint | Description |
+|----------|-------------|
+| `POST /tasks/{id}/claim` | Claim a pending task |
+| `POST /tasks/{id}/start` | Start working on claimed task |
+| `POST /tasks/{id}/block` | Block task on dependency |
+| `POST /tasks/{id}/soft-block` | Block on external factor |
+| `POST /tasks/{id}/unblock` | Unblock a task |
+| `POST /tasks/{id}/pause` | Pause active task |
+| `POST /tasks/{id}/resume` | Resume paused task |
+| `POST /tasks/{id}/verify` | Submit for self-verification |
+| `POST /tasks/{id}/submit-qa` | Submit to QA |
+| `POST /tasks/{id}/pass-qa` | QA passes task |
+| `POST /tasks/{id}/fail-qa` | QA fails task |
+| `POST /tasks/{id}/docs-complete` | Mark docs complete |
+| `POST /tasks/{id}/submit-pm-review` | Submit for PM review |
+| `POST /tasks/{id}/escalate-to-ceo` | Escalate to CEO |
+| `POST /tasks/{id}/ceo-approve` | CEO approves |
+| `POST /tasks/{id}/ceo-reject` | CEO rejects |
+| `POST /tasks/{id}/complete` | Complete task (PM) |
+| `POST /tasks/{id}/cancel` | Cancel task (PM) |
+| `POST /tasks/{id}/activate` | Activate from backlog (PM) |

docs/architecture/workspaces.md

@@ -0,0 +1,233 @@
+# Multi-Agent Workspace Architecture
+
+This document describes the workspace structure that enables multiple AI agents to work on the same project in parallel without conflicts.
+
+## Overview
+
+Each agent gets their own git clone (workspace) of a project. This allows:
+
+- **Parallel development**: Multiple agents working on different tasks simultaneously
+- **No file conflicts**: Each agent has their own working tree
+- **Independent branches**: Agents can be on different branches
+- **Scoped permissions**: Agents only have access to their own workspace
+
+## Directory Structure
+
+```
+{workspaces_root}/
+└── {project-slug}/
+    └── {team}/
+        └── {agent-slug}/
+            └── [git repository files]
+```
+
+### Example
+
+```
+/data/workspaces/
+├── roboco/                           # Project: roboco
+│   ├── backend/                      # Team: backend
+│   │   ├── be-dev-1/                 # Agent: be-dev-1
+│   │   │   ├── .git/
+│   │   │   ├── roboco/
+│   │   │   └── ...
+│   │   └── be-dev-2/                 # Agent: be-dev-2
+│   │       ├── .git/
+│   │       ├── roboco/
+│   │       └── ...
+│   ├── frontend/                     # Team: frontend
+│   │   ├── fe-dev-1/
+│   │   └── fe-dev-2/
+│   └── uxui/                         # Team: uxui
+│       └── ux-dev-1/
+│
+└── roboco-panel/                     # Project: roboco-panel
+    ├── frontend/
+    │   ├── fe-dev-1/
+    │   └── fe-dev-2/
+    └── ...
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ROBOCO_WORKSPACES_ROOT` | `/data/workspaces` | Root directory for all workspaces |
+| `ROBOCO_WORKSPACE_AUTO_CLONE` | `true` | Auto-clone repos on first access |
+| `ROBOCO_WORKSPACE_CLONE_TIMEOUT` | `300` | Clone timeout in seconds |
+
+### Example `.env`
+
+```bash
+ROBOCO_WORKSPACES_ROOT=/data/workspaces
+ROBOCO_WORKSPACE_AUTO_CLONE=true
+ROBOCO_WORKSPACE_CLONE_TIMEOUT=300
+```
+
+## How It Works
+
+### 1. Workspace Resolution
+
+When an agent makes a git/test API request:
+
+```
+Agent: be-dev-1 (team: backend)
+Project: roboco
+→ Workspace: /data/workspaces/roboco/backend/be-dev-1/
+```
+
+### 2. Auto-Clone
+
+If `ROBOCO_WORKSPACE_AUTO_CLONE=true` and workspace doesn't exist:
+
+1. Create parent directories
+2. Clone from project's `git_url`
+3. Checkout `default_branch`
+
+### 3. API Flow
+
+```
+┌─────────────┐     ┌─────────────────┐     ┌──────────────────┐
+│  Agent      │────▶│  API Endpoint   │────▶│  WorkspaceService│
+│  (be-dev-1) │     │  (git/test)     │     │                  │
+└─────────────┘     └─────────────────┘     └──────────────────┘
+                           │                         │
+                           ▼                         ▼
+                    ┌─────────────┐          ┌──────────────────┐
+                    │ X-Agent-ID  │          │ Resolve path:    │
+                    │ X-Agent-Role│          │ /workspaces/     │
+                    │ X-Agent-Team│          │   roboco/        │
+                    └─────────────┘          │   backend/       │
+                                             │   be-dev-1/      │
+                                             └──────────────────┘
+```
+
+## API Endpoints
+
+### WorkspaceService Methods
+
+```python
+from roboco.services.workspace import get_workspace_service
+
+service = get_workspace_service(db)
+
+# Get workspace path
+path = service.get_workspace_path("roboco", "backend", "be-dev-1")
+# → Path("/data/workspaces/roboco/backend/be-dev-1")
+
+# Resolve from agent UUID
+path = await service.resolve_workspace("roboco", agent_uuid)
+
+# Ensure workspace exists (clone if needed)
+path = await service.ensure_workspace(
+    project_slug="roboco",
+    agent_id=agent_uuid,
+    git_url="git@github.com:org/roboco.git",
+    default_branch="main"
+)
+
+# List all workspaces for a project
+workspaces = await service.list_workspaces("roboco")
+# [{"team": "backend", "agent": "be-dev-1", "path": "...", "exists": True}, ...]
+
+# Delete workspace (use with caution)
+deleted = await service.delete_workspace("roboco", agent_uuid)
+```
+
+## Git Workflow
+
+### Branch Naming
+
+Each agent works on task-specific branches:
+
+```
+{type}/{team}/{task-id-first-8-chars}
+
+Examples:
+- feature/backend/abc12345   (be-dev-1 on Task ABC12345)
+- fix/backend/def67890       (be-dev-2 on Task DEF67890)
+- feature/frontend/ghi11223  (fe-dev-1 on Task GHI11223)
+```
+
+### Parallel Work Example
+
+```
+be-dev-1 workspace:
+  └── branch: feature/backend/task-001
+      └── Working on user authentication
+
+be-dev-2 workspace:
+  └── branch: fix/backend/task-002
+      └── Fixing database connection issue
+
+(Both agents work simultaneously, no conflicts)
+```
+
+## Backwards Compatibility
+
+The system maintains backwards compatibility with the legacy `workspace_path` field on Projects:
+
+1. If `agent_id` is provided → Use multi-agent workspace resolution
+2. If `agent_id` is `None` → Fall back to `project.workspace_path`
+
+This allows gradual migration from single-workspace to multi-agent workspaces.
+
+## Best Practices
+
+### For PMs
+
+1. **Register projects** with `git_url` - workspaces are created automatically
+2. **Don't set `workspace_path`** on projects - let the system manage workspaces
+3. **Assign tasks to specific agents** - each gets their own workspace
+
+### For Developers (Agents)
+
+1. **Always work in your workspace** - don't access other agents' workspaces
+2. **Commit frequently** - your workspace is yours alone
+3. **Create PRs** - merge through the standard PR process
+
+### For Operations
+
+1. **Set `ROBOCO_WORKSPACES_ROOT`** to a location with sufficient disk space
+2. **Consider NFS/shared storage** for multi-node deployments
+3. **Monitor disk usage** - workspaces can grow large
+
+## Troubleshooting
+
+### Workspace Not Found
+
+```
+WorkspaceError: Agent not found: be-dev-1
+```
+
+**Solution**: Ensure the agent exists in the database with correct team.
+
+### Clone Failed
+
+```
+WorkspaceError: Failed to clone repository: Permission denied
+```
+
+**Solution**: Ensure the RoboCo service has SSH keys configured for git access.
+
+### Disk Space
+
+```
+WorkspaceError: No space left on device
+```
+
+**Solution**: Clean up old workspaces or expand storage:
+
+```python
+# Delete workspace for an agent
+await service.delete_workspace("roboco", agent_uuid)
+```
+
+## Security Considerations
+
+1. **Workspace Isolation**: Agents should only access their own workspaces
+2. **Git Credentials**: Store SSH keys securely, don't expose in workspaces
+3. **File Permissions**: Ensure appropriate Unix permissions on workspace directories
+4. **Network Access**: Workspaces need network access for git operations