docs(rag): rewrite the KB docs to the real gateway verb surface

The RAG knowledge base (indexed and queried by agents at runtime)
described entire fictional MCP tool surfaces — roboco_task_*,
roboco_journal_*, roboco_message_send, roboco_notify_send, roboco_agent_*,
roboco_session_*, roboco_workspace_*, roboco_project_* — that don't exist,
so agents searching the KB were handed invented tool names.

Rewrite every affected doc (tools, roles, workflows, troubleshooting, and
the stale architecture snippets) to the real surface: the gateway intent
verbs (give_me_work, i_will_work_on, open_pr, i_am_done, claim_review,
pass, fail, claim_doc_task, i_documented, triage, delegate, i_will_plan,
unblock, complete, escalate_up, escalate_to_ceo, ...) and content tools
(commit, note(scope=...), say, dm, evidence, notify*, open_session,
channels). Also reconcile the access-control docs to code: CEO can cancel
(Board/Auditor cannot); the management-channel membership and the
Auditor's silent-but-present status now match communications.py.
This commit is contained in:
Renn F
2026-06-05 17:20:36 +02:00
parent 416356899d
commit ecea593a51
27 changed files with 999 additions and 1009 deletions
+12 -11
View File
@@ -34,20 +34,20 @@ pending → claimed → in_progress → verifying → awaiting_qa
### QA Flow
```
awaiting_qa → claimed → in_progress → pass/fail
pass: awaiting_documentation
fail: needs_revision
awaiting_qa → claimed (claim_review) → pass/fail
pass: awaiting_documentation
fail: needs_revision
```
### Documenter Flow
```
awaiting_documentation → claimed → in_progress → awaiting_pm_review
awaiting_documentation → claimed (claim_doc_task) → awaiting_pm_review
```
### PM Activation
```
backlog → pending (via roboco_task_activate)
backlog → pending (a PM activates the task during `triage`)
```
## Role-Restricted Transitions
@@ -63,7 +63,7 @@ backlog → pending (via roboco_task_activate)
| `awaiting_pm_review → awaiting_ceo_approval` | cell_pm, main_pm (parent tasks only) |
| `awaiting_ceo_approval → completed` | ceo only |
| `awaiting_ceo_approval → needs_revision` | ceo only |
| `any → cancelled` | cell_pm, main_pm |
| `any → cancelled` | cell_pm, main_pm, ceo |
## CEO Approval Notes
@@ -73,7 +73,8 @@ backlog → pending (via roboco_task_activate)
## Checking State
```python
task = roboco_task_get(task_id)
# task.status contains current state
```
You don't poll task state directly — every flow verb returns a
standardized envelope whose `status` and `next` fields tell you the
task's current state and what to call next. Trust the envelope rather
than guessing. To pull the full task context (criteria, prior notes,
handoff), call `evidence(task_id)`.