mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
docs: reflow hard-wrapped prose to one line per paragraph
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.
This commit is contained in:
Renn F
@@ -2,16 +2,11 @@
|
||||
|
||||
## Native Git Commands Blocked
|
||||
|
||||
**Symptom:** `Bash(git commit)`, `Bash(git push)`, `Bash(git checkout)`, etc.
|
||||
denied by the bash-guard hook.
|
||||
**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.
|
||||
**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:
|
||||
**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 |
|
||||
|-----------------------|-------------|
|
||||
@@ -40,8 +35,7 @@ to do. There is **no** `roboco_git_commit / _push / _create_pr / _merge_pr
|
||||
|
||||
**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.
|
||||
**Solution:** QA `pass(task_id, notes)` or `fail(task_id, issues)` only. Developers fix issues and re-submit.
|
||||
|
||||
## NO_PLAN Error on Start
|
||||
|
||||
@@ -49,20 +43,17 @@ Developers fix issues and re-submit.
|
||||
|
||||
**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`.
|
||||
**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.
|
||||
**Cause:** Parent task hasn't been claimed/started yet, so it has no branch for the subtask's branch to fork from.
|
||||
|
||||
**Solution:**
|
||||
|
||||
1. Parent task must transition to `in_progress` first (PMs:
|
||||
`i_will_plan(parent_id, plan)`; devs: `i_will_work_on(parent_id)`).
|
||||
1. Parent task must transition to `in_progress` first (PMs: `i_will_plan(parent_id, plan)`; devs: `i_will_work_on(parent_id)`).
|
||||
2. Then the subtask's branch will auto-fork from the parent's on claim.
|
||||
|
||||
Branches are auto-created hierarchically. No manual creation needed.
|
||||
|
||||
@@ -57,8 +57,7 @@
|
||||
Cell members → Cell PM → Main PM → Product Owner → CEO
|
||||
```
|
||||
|
||||
Cannot skip levels or choose target. (Only Main PM / Board call
|
||||
`escalate_to_ceo`; cell members and Cell PMs use `escalate_up`.)
|
||||
Cannot skip levels or choose target. (Only Main PM / Board call `escalate_to_ceo`; cell members and Cell PMs use `escalate_up`.)
|
||||
|
||||
## Tests Failing Before Submit
|
||||
|
||||
@@ -127,10 +126,8 @@ roboco_docs_write({
|
||||
**Problem**: Sent a `dm` but no response
|
||||
|
||||
**Check**:
|
||||
1. Is the recipient in your **own cell**? Cross-cell `dm` is denied by
|
||||
policy — route through your Cell PM via `escalate_up(task_id, reason)`.
|
||||
2. Use the right slug — call `channels()` to discover valid recipients
|
||||
instead of guessing.
|
||||
1. Is the recipient in your **own cell**? Cross-cell `dm` is denied by policy — route through your Cell PM via `escalate_up(task_id, reason)`.
|
||||
2. Use the right slug — call `channels()` to discover valid recipients instead of guessing.
|
||||
3. Did you include `task_id`? It anchors the message to the work.
|
||||
|
||||
**Solutions**:
|
||||
@@ -144,5 +141,4 @@ roboco_docs_write({
|
||||
|
||||
**Cause**: Direct A2A is same-cell only — there is no cross-cell `dm`
|
||||
|
||||
**Solution**: Escalate up the chain. Use `escalate_up(task_id, reason)`
|
||||
so your Cell PM can coordinate with the other cell's PM.
|
||||
**Solution**: Escalate up the chain. Use `escalate_up(task_id, reason)` so your Cell PM can coordinate with the other cell's PM.
|
||||
|
||||
@@ -2,120 +2,90 @@
|
||||
|
||||
## Missing Git Token
|
||||
|
||||
**Error:** `Project requires a git token for HTTPS repositories`
|
||||
(also surfaces as `WorkspaceError` during clone)
|
||||
**Error:** `Project requires a git token for HTTPS repositories` (also surfaces as `WorkspaceError` during clone)
|
||||
|
||||
**Cause:** No encrypted GitHub PAT on
|
||||
`projects.git_token_encrypted` for this project.
|
||||
**Cause:** No encrypted GitHub PAT on `projects.git_token_encrypted` for this project.
|
||||
|
||||
**Fix:**
|
||||
|
||||
1. Open the project's settings tab in the panel
|
||||
2. Paste a GitHub Personal Access Token with `repo` scope
|
||||
3. Save — the panel encrypts and stores it; the API never returns
|
||||
the plaintext
|
||||
3. Save — the panel encrypts and stores it; the API never returns the plaintext
|
||||
|
||||
Notes:
|
||||
|
||||
- Each project has its own token (no global fallback)
|
||||
- Tokens are encrypted at rest with Fernet
|
||||
- The token is injected only at the MCP layer (commit / clone / PR ops);
|
||||
`.git/config` is scrubbed post-clone so a leaked PAT from there is
|
||||
not a recovery path
|
||||
- The token is injected only at the MCP layer (commit / clone / PR ops); `.git/config` is scrubbed post-clone so a leaked PAT from there is not a recovery path
|
||||
|
||||
## Workspace Not Found
|
||||
|
||||
**Error:** `Workspace does not exist`
|
||||
|
||||
**Cause:** Workspace not cloned yet (or `ROBOCO_WORKSPACE_AUTO_CLONE`
|
||||
is `false` and no manual clone has run).
|
||||
**Cause:** Workspace not cloned yet (or `ROBOCO_WORKSPACE_AUTO_CLONE` is `false` and no manual clone has run).
|
||||
|
||||
**Fix:**
|
||||
|
||||
- If `ROBOCO_WORKSPACE_AUTO_CLONE=true` (default), the first MCP verb
|
||||
that touches the workspace will trigger the clone. Just call your
|
||||
next verb (`i_will_work_on`, `commit`, etc.).
|
||||
- Otherwise check `ROBOCO_WORKSPACE_CLONE_TIMEOUT` and the
|
||||
orchestrator logs for a stuck clone.
|
||||
- If `ROBOCO_WORKSPACE_AUTO_CLONE=true` (default), the first MCP verb that touches the workspace will trigger the clone. Just call your next verb (`i_will_work_on`, `commit`, etc.).
|
||||
- Otherwise check `ROBOCO_WORKSPACE_CLONE_TIMEOUT` and the orchestrator logs for a stuck clone.
|
||||
|
||||
## BRANCH_MISMATCH
|
||||
|
||||
**Error envelope:**
|
||||
`Workspace is on '<other-branch>' but task requires '<task-branch>'`
|
||||
**Error envelope:** `Workspace is on '<other-branch>' but task requires '<task-branch>'`
|
||||
|
||||
**Cause:** You're trying to act on task A while your workspace is still
|
||||
on task B's branch.
|
||||
**Cause:** You're trying to act on task A while your workspace is still on task B's branch.
|
||||
|
||||
**Fix:** Don't checkout by hand — there is no `roboco_git_checkout`
|
||||
tool. Call the verb on the *intended* task instead:
|
||||
**Fix:** Don't checkout by hand — there is no `roboco_git_checkout` tool. Call the verb on the *intended* task instead:
|
||||
|
||||
- Devs: `i_will_work_on(task_id)` switches to that task's branch
|
||||
- PMs: `i_will_plan(task_id, plan)` switches to that parent task's
|
||||
branch
|
||||
- PMs: `i_will_plan(task_id, plan)` switches to that parent task's branch
|
||||
- QA: `claim_review(task_id)` switches to the dev's branch under review
|
||||
|
||||
If your workspace is dirty, the verb returns an envelope telling you to
|
||||
either `commit(...)` first or escalate via `i_am_blocked`.
|
||||
If your workspace is dirty, the verb returns an envelope telling you to either `commit(...)` first or escalate via `i_am_blocked`.
|
||||
|
||||
## NO_COMMITS on open_pr
|
||||
|
||||
**Cause:** No commits on the task yet — the choreographer has nothing
|
||||
to open a PR over.
|
||||
**Cause:** No commits on the task yet — the choreographer has nothing to open a PR over.
|
||||
|
||||
**Fix:** `commit(message=..., files=...)` at least once, then call
|
||||
`open_pr(task_id)` again.
|
||||
**Fix:** `commit(message=..., files=...)` at least once, then call `open_pr(task_id)` again.
|
||||
|
||||
## NO_PR on pass / fail
|
||||
|
||||
**Cause:** The PR was never created — usually because
|
||||
`open_pr(task_id)` did not run cleanly.
|
||||
**Cause:** The PR was never created — usually because `open_pr(task_id)` did not run cleanly.
|
||||
|
||||
**Fix:** Roll back to the dev: have them re-call `open_pr(task_id)`
|
||||
after fixing whatever blocked the PR opening (see PR Creation Failed,
|
||||
below). QA cannot create the PR.
|
||||
**Fix:** Roll back to the dev: have them re-call `open_pr(task_id)` after fixing whatever blocked the PR opening (see PR Creation Failed, below). QA cannot create the PR.
|
||||
|
||||
## PR Creation Failed (during open_pr)
|
||||
|
||||
**Causes:**
|
||||
|
||||
1. Nothing to push — no commits on the branch
|
||||
2. Branch is on the workspace but not pushed yet (rare; the choreographer
|
||||
pushes during `commit`, but a stale workspace can drift)
|
||||
2. Branch is on the workspace but not pushed yet (rare; the choreographer pushes during `commit`, but a stale workspace can drift)
|
||||
3. Project has no git token configured
|
||||
4. The GitHub repo doesn't allow PRs from your branch (rare; usually
|
||||
org-level branch protection)
|
||||
4. The GitHub repo doesn't allow PRs from your branch (rare; usually org-level branch protection)
|
||||
|
||||
**Fix:**
|
||||
|
||||
- Verify commits exist with `roboco_git_log(project_slug=...)`
|
||||
- Verify the project has a git token (Missing Git Token, above)
|
||||
- If the task is in a stuck state, `unclaim(task_id)` and re-`claim`
|
||||
to rebuild the branch
|
||||
- If the task is in a stuck state, `unclaim(task_id)` and re-`claim` to rebuild the branch
|
||||
|
||||
## FORCE_PUSH_FORBIDDEN
|
||||
|
||||
**Cause:** Force-push is CEO-only. Anyone else attempting it (typically
|
||||
because their branch diverged) is denied.
|
||||
**Cause:** Force-push is CEO-only. Anyone else attempting it (typically because their branch diverged) is denied.
|
||||
|
||||
**Fix:** `unclaim(task_id)` and re-`claim` it. The choreographer
|
||||
rebuilds the branch from the parent's HEAD; replay your commits with
|
||||
`commit(...)`.
|
||||
**Fix:** `unclaim(task_id)` and re-`claim` it. The choreographer rebuilds the branch from the parent's HEAD; replay your commits with `commit(...)`.
|
||||
|
||||
## Merge Conflicts on `complete`
|
||||
|
||||
**Cause:** The leaf PR conflicts with the parent branch (cell branch
|
||||
or master).
|
||||
**Cause:** The leaf PR conflicts with the parent branch (cell branch or master).
|
||||
|
||||
**Fix:** This currently surfaces as an error envelope from `complete`.
|
||||
The recovery path:
|
||||
**Fix:** This currently surfaces as an error envelope from `complete`. The recovery path:
|
||||
|
||||
1. PM `unblock(task_id, restore=False)` — frees the task back to the
|
||||
dev
|
||||
2. Dev re-claims, the choreographer rebuilds the branch off the latest
|
||||
parent, and they replay their commits
|
||||
1. PM `unblock(task_id, restore=False)` — frees the task back to the dev
|
||||
2. Dev re-claims, the choreographer rebuilds the branch off the latest parent, and they replay their commits
|
||||
3. Dev `open_pr` again
|
||||
4. QA re-runs `pass` (or `fail` if the rebase changed behaviour)
|
||||
5. PM `complete` again
|
||||
|
||||
We don't expose a "resolve conflicts in place" path at the agent layer
|
||||
— rebuilds via the lifecycle are the recovery.
|
||||
We don't expose a "resolve conflicts in place" path at the agent layer — rebuilds via the lifecycle are the recovery.
|
||||
|
||||
@@ -31,9 +31,7 @@
|
||||
2. Task in wrong status
|
||||
|
||||
**Solutions**:
|
||||
- Claim + start in one step: `i_will_work_on(task_id, plan="...")`
|
||||
(devs), `claim_review(task_id)` (QA), `claim_doc_task(task_id)` (doc),
|
||||
or `i_will_plan(task_id, plan, approach)` (PMs)
|
||||
- Claim + start in one step: `i_will_work_on(task_id, plan="...")` (devs), `claim_review(task_id)` (QA), `claim_doc_task(task_id)` (doc), or `i_will_plan(task_id, plan, approach)` (PMs)
|
||||
- Check current status
|
||||
|
||||
Note: Git branches are auto-created on claim, no waiting needed.
|
||||
@@ -67,14 +65,11 @@ Note: Git branches are auto-created on claim, no waiting needed.
|
||||
|
||||
**Cause**: Attempting to escalate a task that has a `parent_task_id`
|
||||
|
||||
**Solution**: Escalate the parent task instead. Find the parent task ID
|
||||
(it's on the subtask's `parent_task_id` field, surfaced in your
|
||||
`give_me_work()` / `triage()` envelope), then escalate the parent:
|
||||
**Solution**: Escalate the parent task instead. Find the parent task ID (it's on the subtask's `parent_task_id` field, surfaced in your `give_me_work()` / `triage()` envelope), then escalate the parent:
|
||||
```python
|
||||
escalate_to_ceo(task_id=parent_id, reason="...")
|
||||
```
|
||||
`escalate_to_ceo` is Main PM / Board only; Cell PMs and cell members
|
||||
use `escalate_up(task_id, reason)` instead.
|
||||
`escalate_to_ceo` is Main PM / Board only; Cell PMs and cell members use `escalate_up(task_id, reason)` instead.
|
||||
|
||||
## Git Task: Parent Branch Required
|
||||
|
||||
@@ -93,10 +88,8 @@ use `escalate_up(task_id, reason)` instead.
|
||||
**Cause**: Trying to complete a parent task while subtasks are still in progress
|
||||
|
||||
**Solution**: The error message includes which subtask IDs are blocking. Either:
|
||||
1. Complete the blocking subtasks first (drive them through QA → docs →
|
||||
`complete(task_id, notes)`)
|
||||
2. Cancel them if no longer needed (PM/CEO only — cancellation is not an
|
||||
agent verb; ask your PM)
|
||||
1. Complete the blocking subtasks first (drive them through QA → docs → `complete(task_id, notes)`)
|
||||
2. Cancel them if no longer needed (PM/CEO only — cancellation is not an agent verb; ask your PM)
|
||||
|
||||
## Invalid Task Status for Operation
|
||||
|
||||
|
||||
Reference in New Issue
Block a user