fe6c8e387f
* docs: sync prompts/RAG/CLAUDE + bump to 0.11.0 for the run-hardening wave
Documentation + version sweep for everything shipped since 889f3689 (the 0.11.0
wave: MegaTask + #249-#253 run-hardening). Closes the doc drift behind the live
incidents — agents had no branch-behind-master guidance, so a Main PM invented
a bogus "rebase subtask".
Agent guidance (the headline gap):
- main_pm / cell_pm / developer prompts: a task branch is made current at CLAIM;
there is NO rebase/pull/merge verb at the agent layer. Never create a "rebase
subtask" or improvise git surgery; escalate a behind-base branch
(developer: i_am_blocked; PM: escalate_up). "A rebase subtask is always a mistake."
- board prompt: Board has no unblock verb; a blocked task assigned to it is a
mis-assignment -> escalate_to_ceo immediately, never sit on it (respawn loop).
- developer prompt: the shared clone is git-reset on a fresh claim; push/open_pr
target the task branch by name regardless of the current checkout.
- RAG (git-errors, blocked-tools, pr-creation): branch-behind-base, "src refspec
does not match any", and non-fast-forward recovery -> escalate, don't improvise.
CLAUDE.md: 9 shipped behaviors synced (session-limit parking, one-active-work-
session + migration 047, push/PR-by-name + origin ref recovery, fresh-claim
workspace reset, Board never owns a coordination root, verb-runner per-action
INVALID_STATE re-check, note fire-and-forget RAG indexing,
ROBOCO_GATEWAY_HEALTH_ENABLED flag, learnings not broadcast to human roles).
Version 0.10.0 -> 0.11.0: pyproject, roboco/__init__, config.app_version +
agent-image-tag example, panel/package.json, uv.lock, README/deploy examples;
CHANGELOG [Unreleased] cut to [0.11.0] - 2026-06-24.
* docs(site): document session-limit parking + the branch-behind-base operator flow
User-facing docs site updates for the 0.11.0 wave (the run-hardening behaviors
that are operator-visible):
- models/resilience.md: the Claude session-limit (5-hour usage window) parks
and auto-revives like an overload, not just per-request 429s / 5xx overloads.
- troubleshooting/common-issues.md: same session-limit note on the parked-
provider entries; plus a new "task stuck on a branch behind its base" entry —
agents have no rebase verb so they escalate it; the operator rebases from the
panel Git tab (auto-rebase-at-spawn is the roadmap cure).
---------
Co-authored-by: Renn F <rennf93@users.noreply.github.com>
2.9 KiB
Blocked Tools
Native Git Commands Blocked
Symptom: Bash(git commit), Bash(git push), Bash(git checkout), etc. denied by the bash-guard hook.
Cause: Shell git for network / auth / branch-mutating ops bypasses the PAT injection done by the MCP layer; raw git fetch etc. would fail with could not read Username for 'https://github.com' anyway.
Solution: Use the role-scoped MCP verb that matches what you're trying to do. There is no roboco_git_commit / _push / _create_pr / _merge_pr / _checkout MCP tool — the surface is smaller than that:
| Blocked shell command | Use instead |
|---|---|
git status / git diff / git log / git branch |
roboco_git_status / roboco_git_diff / roboco_git_log / roboco_git_branch_list (roboco-git-readonly) |
git commit + git push (devs / docs) |
commit(message, files) (roboco-do) — auto-prefixes [task-id], pushes |
git checkout of a task branch |
None — branch is auto-checked-out by i_will_work_on(task_id) (devs) or i_will_plan(task_id, plan) (PMs) |
| Open a PR | None — PR is opened by the choreographer when the dev calls open_pr(task_id) |
| Merge a PR | complete(task_id, notes) (PMs only) — Cell PM merges leaf PR; Main PM merges parent and escalates to CEO |
git fetch / git pull / git rebase |
None at the agent layer — there is no pull/rebase verb. If your branch is behind its base, ESCALATE (escalate_up / i_am_blocked) — that, not unclaim, is the fix. Use unclaim + re-claim only to rebuild a branch fresh from the current base, and only on instruction |
Write/Edit Outside Workspace
Symptom: Write() or Edit() denied for a file path
Cause: Write operations restricted to your workspace
Solution:
- Developers: Only write in
/data/workspaces/{project}/{team}/{agent-id}/ - Documenters: Only write in
/app/docs/ - QA: No write access (review only)
QA Cannot Commit
Symptom: commit() returns not_authorized for a QA agent
Cause: QA role is read-only — cannot modify code or open PRs.
Solution: QA pass(task_id, notes) or fail(task_id, issues) only. Developers fix issues and re-submit.
NO_PLAN Error on Start
Symptom: Lifecycle transition rejected with NO_PLAN
Cause: Parent tasks require a plan before they can leave pending.
Solution: PMs call i_will_plan(task_id, plan); the verb both records the plan and transitions the task into in_progress.
Parent Branch Required
Symptom: Can't claim subtask, error "Parent task must be claimed first"
Cause: Parent task hasn't been claimed/started yet, so it has no branch for the subtask's branch to fork from.
Solution:
- Parent task must transition to
in_progressfirst (PMs:i_will_plan(parent_id, plan); devs:i_will_work_on(parent_id)). - Then the subtask's branch will auto-fork from the parent's on claim.
Branches are auto-created hierarchically. No manual creation needed.