Many fixes and cleanups

docs/rag/troubleshooting/git-errors.md

@@ -2,87 +2,120 @@
 
 ## Missing Git Token
 
-**Error**: "Project requires a git token for HTTPS repositories"
+**Error:** `Project requires a git token for HTTPS repositories`
+(also surfaces as `WorkspaceError` during clone)
 
-**Cause**: No GitHub PAT configured for this project
+**Cause:** No encrypted GitHub PAT on
+`projects.git_token_encrypted` for this project.
 
-**Solutions**:
-1. Open project settings in UI
-2. Add GitHub token (Personal Access Token)
-3. Token needs `repo` scope for clone/push/PR
+**Fix:**
 
-**Notes**:
-- Each project requires its own token (no global fallback)
-- Tokens are encrypted at rest
-- Token never exposed in API responses
+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
+
+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
 
 ## Workspace Not Found
 
-**Error**: "Workspace does not exist"
+**Error:** `Workspace does not exist`
 
-**Cause**: Workspace not cloned yet
+**Cause:** Workspace not cloned yet (or `ROBOCO_WORKSPACE_AUTO_CLONE`
+is `false` and no manual clone has run).
 
-**Solutions**:
-- If auto_clone enabled: workspace creates on first access
-- Manual: Wait for workspace service to clone
-- Check config: `ROBOCO_WORKSPACE_AUTO_CLONE=true`
+**Fix:**
 
-## Cannot Push
+- 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.
 
-**Error**: "Push failed"
+## BRANCH_MISMATCH
 
-**Causes**:
-1. No commits to push
-2. Remote branch doesn't exist
-3. Conflicts with remote
+**Error envelope:**
+`Workspace is on '<other-branch>' but task requires '<task-branch>'`
 
-**Solutions**:
-- Create commits first: `roboco_git_commit(...)`
-- Check branch exists: `roboco_git_branches()`
-- Pull and resolve conflicts
+**Cause:** You're trying to act on task A while your workspace is still
+on task B's branch.
 
-## Branch Already Exists
+**Fix:** Don't checkout by hand — there is no `roboco_git_checkout`
+tool. Call the verb on the *intended* task instead:
 
-**Error**: "Branch already exists"
+- 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
+- QA: `claim_review(task_id)` switches to the dev's branch under review
 
-**Cause**: Trying to create existing branch
+If your workspace is dirty, the verb returns an envelope telling you to
+either `commit(...)` first or escalate via `i_am_blocked`.
 
-**Solution**: Checkout existing branch:
-```python
-roboco_git_checkout(project_slug, branch_name)
-```
+## NO_COMMITS on open_pr
 
-## Merge Conflicts
+**Cause:** No commits on the task yet — the choreographer has nothing
+to open a PR over.
 
-**Error**: "Merge conflict"
+**Fix:** `commit(message=..., files=...)` at least once, then call
+`open_pr(task_id)` again.
 
-**Cause**: Conflicting changes between branches
+## NO_PR on pass / fail
 
-**Solutions**:
-1. Pull latest from target branch
-2. Resolve conflicts manually
-3. Commit resolution
-4. Push again
+**Cause:** The PR was never created — usually because
+`open_pr(task_id)` did not run cleanly.
 
-## PR Creation Failed
+**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.
 
-**Error**: "PR creation failed"
+## PR Creation Failed (during open_pr)
 
-**Causes**:
-1. No commits on branch
-2. Branch not pushed
-3. GitHub CLI not configured
+**Causes:**
 
-**Solutions**:
-- Push branch first: `roboco_git_push()`
-- Verify commits exist: `roboco_git_log()`
+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)
+3. Project has no git token configured
+4. The GitHub repo doesn't allow PRs from your branch (rare; usually
+   org-level branch protection)
 
-## Checkout Failed
+**Fix:**
 
-**Error**: "Cannot checkout - uncommitted changes"
+- 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
 
-**Cause**: Working directory has uncommitted changes
+## FORCE_PUSH_FORBIDDEN
 
-**Solutions**:
-- Commit changes: `roboco_git_commit(...)`
-- Or stash changes (if supported)
+**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(...)`.
+
+## Merge Conflicts on `complete`
+
+**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:
+
+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.