Add checkout compliance and run traceability to all agents

Add explicit POST /api/issues/{issueId}/checkout and PATCH status
update curl templates with X-Paperclip-Run-Id headers to all agent
heartbeats. Document Gemini workspace sandboxing in Hugh's TOOLS.md.
Also removed Regina's ghost instructionsFilePath from live DB.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

engineering/gandalf/HEARTBEAT.md

@@ -24,12 +24,34 @@ Orient yourself:
 
 For each assigned issue:
 
+#### Checkout the issue first
+
+**You MUST checkout before doing any work. If you skip this, your work is untraceable.**
+
+    curl -sf -X POST "$PAPERCLIP_API_URL/api/issues/{issueId}/checkout" \
+      -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+      -H "Content-Type: application/json" \
+      -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
+      -d '{"agentId": "28e654c9-8971-467b-ac32-5d2a287c30c7", "expectedStatuses": ["todo", "backlog", "blocked"]}'
+
+Replace `{issueId}` with the actual issue ID. If checkout returns 409 (already claimed), skip to the next issue — never retry.
+
+#### Do the work
+
 - Read the full thread and all context Nancy provided
 - Identify the target repo and what needs to be built or fixed
 - Implement the change, write tests, open a PR
-- Comment on the Paperclip issue with the PR link and a summary
 - Create a Paperclip issue assigned to Regression Regina (`8a627431-075d-4fc5-8f90-0bcac607e6ae`) with the PR link and what needs QA review. Always set `assigneeAgentId` explicitly.
-- Update the original issue status to `in_review`
+
+#### Update issue status
+
+**Every status change MUST include the X-Paperclip-Run-Id header.**
+
+    curl -sf -X PATCH "$PAPERCLIP_API_URL/api/issues/{issueId}" \
+      -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+      -H "Content-Type: application/json" \
+      -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
+      -d '{"status": "in_review", "comment": "PR link and summary of what was implemented."}'
 
 ### 3. Check open PRs for review feedback
 

engineering/hugh/TOOLS.md

@@ -6,3 +6,15 @@
 - `pnpm paperclipai issue ...` — Create, list, update, and comment on Paperclip issues
 - `pnpm paperclipai agent list` — List all agents and their status
 - `curl` — HTTP requests (e.g., loading the Paperclip skill)
+
+## Gemini Workspace Restrictions
+
+The `gemini_local` adapter sandboxes Gemini's built-in file tools (`grep_search`, `read_file`, etc.) to the workspace directory. Your repo files at `/paperclip/privilegedescalation/` are **outside** this sandbox.
+
+**Do NOT use Gemini's native file tools to access the repo.** They will fail with "Path not in workspace."
+
+Instead, use `bash` wrappers:
+
+- `cat`, `grep`, `find`, `ls` — for reading/searching files
+- `gh` — for GitHub operations
+- `curl` — for API calls

engineering/regina/HEARTBEAT.md

@@ -24,12 +24,34 @@ Orient yourself:
 
 For each assigned issue:
 
+#### Checkout the issue first
+
+**You MUST checkout before doing any work. If you skip this, your work is untraceable.**
+
+    curl -sf -X POST "$PAPERCLIP_API_URL/api/issues/{issueId}/checkout" \
+      -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+      -H "Content-Type: application/json" \
+      -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
+      -d '{"agentId": "8a627431-075d-4fc5-8f90-0bcac607e6ae", "expectedStatuses": ["todo", "backlog", "blocked"]}'
+
+Replace `{issueId}` with the actual issue ID. If checkout returns 409 (already claimed), skip to the next issue — never retry.
+
+#### Do the work
+
 - Read the full thread
 - Execute the requested testing or verification work
 - Document your findings clearly: what you tested, how, and what you found
-- Comment on the Paperclip issue with your results
 - If you found bugs, open GitHub issues on the affected repo with clear reproduction steps
-- Update issue status appropriately
+
+#### Update issue status
+
+**Every status change MUST include the X-Paperclip-Run-Id header.**
+
+    curl -sf -X PATCH "$PAPERCLIP_API_URL/api/issues/{issueId}" \
+      -H "Authorization: Bearer $PAPERCLIP_API_KEY" \
+      -H "Content-Type: application/json" \
+      -H "X-Paperclip-Run-Id: $PAPERCLIP_RUN_ID" \
+      -d '{"status": "done", "comment": "Describe what you tested, how, and what you found."}'
 
 ### 3. Review open PRs that need QA