mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
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>
76 lines
4.0 KiB
Markdown
76 lines
4.0 KiB
Markdown
# Pull Request Creation
|
|
|
|
## When PRs Are Created
|
|
|
|
PRs are opened **before** QA review, not during `awaiting_documentation`. The choreographer creates the PR as a side-effect of the developer's `open_pr(task_id)` transition (`verifying → awaiting_qa`).
|
|
|
|
This is by design: QA reviews the real PR diff on GitHub, and the downstream PM/CEO approval chain operates on a PR that already exists.
|
|
|
|
You do **not** call any tool to create a PR. There is no `roboco_git_create_pr` MCP tool.
|
|
|
|
## How the dev triggers it
|
|
|
|
```python
|
|
# 1. Make commits as you work (auto-pushes, no separate push step)
|
|
commit(message="feat(api): add Redis rate limiter",
|
|
files=["roboco/api/routes/rate.py", "tests/integration/test_rate.py"])
|
|
|
|
# 2. Once acceptance criteria are implemented + tested, hand off to QA.
|
|
# The choreographer opens the PR here, sets pr_number/pr_url on the
|
|
# task, and transitions verifying → awaiting_qa.
|
|
open_pr(task_id="<task>")
|
|
```
|
|
|
|
The transition enforces (`enforcement/task_lifecycle.py`):
|
|
|
|
- `self_verified=True` — set when you call `i_am_done()` or `verify(task_id)` first
|
|
- `commits` non-empty — at least one commit on the task
|
|
- `progress_updates` non-empty — at least one note on what changed
|
|
- `pr_number` is set automatically by the choreographer; you don't pass it
|
|
|
|
If any precondition is missing, the verb returns an envelope explaining what's missing and how to remediate.
|
|
|
|
The push and the PR head always target **the task's own branch by name**, independent of whatever the shared clone happens to be checked out on. So a `No commits between` or wrong-branch worry at `open_pr` is the verb's job to resolve — never switch branches by hand to "fix" it.
|
|
|
|
## PR Title and Body
|
|
|
|
Generated from templates in `roboco/templates/git/pr_internal.py` and `roboco/templates/git/pr_root.py`. You don't write the body by hand — it's filled with task title, acceptance criteria, the dev's notes, and the standard traceability links.
|
|
|
|
Title format: `[TASK-{root-id:8}:{task-id:8}] {task-title}`.
|
|
|
|
## Parallel Documenter Phase
|
|
|
|
After QA passes, the task transitions to `awaiting_documentation` and runs documenter + dev in parallel:
|
|
|
|
| Agent | Action | Flag set |
|
|
|-------|--------|----------|
|
|
| Documenter | Writes docs files, then `i_documented(task_id, notes, files)` | `docs_complete=True` |
|
|
| Developer | (already done by the time we get here) | `pr_created=True` |
|
|
|
|
Task transitions to `awaiting_pm_review` when both are true.
|
|
|
|
## PM Merges via `complete`
|
|
|
|
An assembled parent reaches `awaiting_pm_review` only after the in-path gate: the Cell PM's `submit_up` opens the cell→root PR and enters `awaiting_pr_review`, where the cell PR reviewer `pr_pass`es it. The Cell PM then calls `complete(task_id, notes)`. The choreographer:
|
|
|
|
1. Verifies all subtasks are in a terminal state
|
|
2. Verifies the PR is reviewable
|
|
3. Merges the leaf PR into the parent branch (squash by default)
|
|
4. Transitions the task to `completed`
|
|
|
|
For the root parent, **Main PM**'s `submit_root` opens the root→master PR and enters the same gate; after the main reviewer `pr_pass`es it, the Main PM's `complete` escalates to the CEO (it does **not** merge). Only the CEO merges the root→master PR.
|
|
|
|
There is no `roboco_git_merge_pr` MCP tool.
|
|
|
|
## Prerequisites
|
|
|
|
- **Git token:** the project must have an encrypted GitHub PAT set on `projects.git_token_encrypted`. Without it, the workspace clone — and therefore everything downstream — fails with `WorkspaceError`.
|
|
- **Token scope:** `repo` (for branch push, PR create, PR merge).
|
|
- **Default branch:** `projects.default_branch` is the merge target for the master PR (typically `master`).
|
|
|
|
## Troubleshooting
|
|
|
|
- `NO_COMMITS` on `open_pr` → call `commit(...)` first; nothing to open a PR over.
|
|
- `NO_PR` on `pass`/`fail` → the choreographer didn't open a PR; check the workspace state with `roboco_git_status` and re-call `open_pr` once the workspace is clean.
|
|
- `FORCE_PUSH_FORBIDDEN` → only the CEO may force-push. If your branch diverged, `unclaim` and re-`claim` the task; the choreographer rebuilds the branch.
|