Close the doc gaps the audit found in the agent knowledge base and the human
walkthrough:
- config-reference: add the Grok provider env table (host ~/.grok subscription
mount, grok-build, idle-kill, cost cap) and the Self-Healing CI loop toggles.
- agent-model: provider-aware Model Configuration (ANTHROPIC default / GROK) +
add the pr_reviewer / prompter / secretary roles to the Roles table.
- tool-permissions: 'three' -> five MCP servers (roboco-optimal, roboco-docs) +
PR Reviewer / Prompter / Secretary tool sections.
- new roles/pr-reviewer.md (the 22nd agent had no role doc); permissions +
agent-uuids + task-tools 'PR Reviewer flow' all gain the role.
- api-endpoints: drop the removed USAGE_UPDATE event (only USAGE_SNAPSHOT exists).
- how-to: self-healing CI loop + Company Scorecard (ch.5), inbound external-PR
review + CEO Supersede/Dismiss queue (ch.4).
Every claim verified against current code by the audit (grok model grok-build,
auth ~/.grok, no metered API; opencode fully removed).
The cell-pm role doc showed delegate with a nonexistent nested body={...}
and omitted covers_parent_criteria, so an agent following it would make a
malformed call and burn turns rediscovering the real shape. Both PM docs now
match the actual flow_server.delegate signature (flat keywords, with
covers_parent_criteria; the subtask inherits the parent's project — resolved
from the product cell→project map for coordination roots, never passed).
Also document reassign (cell PM could call it but it was undocumented) and
cross-link the two roles: cell-pm explains submit_up hands finished work to
Main PM; main-pm explains the receiving side — the integration-branch chain,
that its complete on the root opens the master PR, and that only Main PM and
the CEO act on master.
Markdown and editors soft-wrap on their own, so the manual ~75-char line
breaks across the docs added nothing but noise. Join wrapped prose, list
items, and paragraphs into single lines across 67 docs — README, CLAUDE.md,
deployment, usage, the RAG knowledge base, and the agent role prompts.
Whitespace-only: code fences, tables, and blockquote alerts are byte-identical
and the change is token-verified (no content altered). Applied with a
deterministic reflow tool (committed separately).
Also lands two doc edits that were awaiting commit: the measured under-load
resource numbers in usage.md and the pr_reviewer additions to the
org-structure RAG doc.
The agents' runtime KB had drifted three releases behind the gateway. Add the
two missing role docs (prompter, secretary — both live-session SDK chat roles,
human-only) and fold the AC/decomposition guardrails and per-dev code queues
into the high-traffic PM docs:
- task-model: acceptance_criteria_ids + parent_ac_refs fields and how the
child->parent AC link works.
- task-planning: covers_parent_criteria on delegate, the parent_ac_coverage /
unclaimed_parent_acs briefing fields, the decomposition-floor and roll-up
gates (safe-by-construction), and per-dev sequenced code queues.
- task-tools: same coverage note + correct stale verbs — QA is
pass_review/fail_review (not pass/fail), cell_pm gains reassign, and main_pm
no longer claims submit_up/reassign it does not have.
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.
- Add roboco_project_* tools (list, get, create, update) with CEO bypass
- Add roboco_workspace_* tools (ensure, status, list) for workspace management
- Add project_slug and requires_git fields to TaskCreateInput schema
- Validate project exists and cell matches when creating git-enabled tasks
- Register project MCP server in orchestrator with proper permissions
Workspace permissions by role:
- Developer: Write to own workspace only
- QA: Read-only access to all cell workspaces
- Documenter: Write to all cell workspaces (add docs to dev branches)
- Cell PM: Write to own workspace, project_update for own cell
- Main PM: Full project access (create, update all, workspace_list all)
- CEO: Full bypass on all permission checks
Also includes:
- Git templates for commits, branches, PRs (separation of concerns)
- Updated blueprints with project/workspace tools documentation
- Updated RAG docs with project tools reference
Renn F