From c402c3bbd6d4ef2ef4eb523695145f4c1010e246 Mon Sep 17 00:00:00 2001 From: Chris Farhood Date: Sun, 15 Mar 2026 12:01:50 -0400 Subject: [PATCH] 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 --- ceo/HEARTBEAT.md | 26 ++++++++++++++++++++++++-- cmo/HEARTBEAT.md | 26 ++++++++++++++++++++++++-- cto/HEARTBEAT.md | 26 ++++++++++++++++++++++++-- engineering/gandalf/HEARTBEAT.md | 26 ++++++++++++++++++++++++-- engineering/hugh/TOOLS.md | 12 ++++++++++++ engineering/regina/HEARTBEAT.md | 26 ++++++++++++++++++++++++-- marketing/samuel/HEARTBEAT.md | 26 ++++++++++++++++++++++++-- 7 files changed, 156 insertions(+), 12 deletions(-) diff --git a/ceo/HEARTBEAT.md b/ceo/HEARTBEAT.md index 185abc2..a6db76f 100644 --- a/ceo/HEARTBEAT.md +++ b/ceo/HEARTBEAT.md @@ -16,10 +16,32 @@ Read the Paperclip skill to understand how to interact with this system: For each open issue or unread comment: +#### 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": "cc3abd0b-f1fb-44fd-af37-81ba3184f328", "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 - Respond, redirect, or make a decision -- Post a comment summarizing what you did -- 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": "Summarize what you did."}' ### 3. Review org health diff --git a/cmo/HEARTBEAT.md b/cmo/HEARTBEAT.md index d2f207e..f0efb1e 100644 --- a/cmo/HEARTBEAT.md +++ b/cmo/HEARTBEAT.md @@ -20,11 +20,33 @@ Read the Paperclip skill to understand how to interact with this system: For each open issue or unread comment: +#### 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": "606d2953-ca84-4ffc-b575-cb7e2e5897d3", "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 issue thread - Determine action required (respond, delegate, research, draft content, open PR) - Take that action immediately -- Post a comment on the issue summarizing what you did -- 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": "Summarize what you did."}' ### 3. Check the GitHub org for signals diff --git a/cto/HEARTBEAT.md b/cto/HEARTBEAT.md index eba2a50..ea64e1a 100644 --- a/cto/HEARTBEAT.md +++ b/cto/HEARTBEAT.md @@ -24,11 +24,33 @@ Orient yourself: For each open issue or unread comment: +#### 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": "41b49768-c5c0-4473-8d52-6637de753064", "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 issue thread - Determine action required (code review, triage, decision, delegate to Gandalf, or assign QA to Regina) - Take that action immediately -- Post a comment on the issue summarizing what you did -- 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": "Summarize what you did."}' ### 3. Merge QA-approved PRs diff --git a/engineering/gandalf/HEARTBEAT.md b/engineering/gandalf/HEARTBEAT.md index f41f3b9..b77d163 100644 --- a/engineering/gandalf/HEARTBEAT.md +++ b/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 diff --git a/engineering/hugh/TOOLS.md b/engineering/hugh/TOOLS.md index 868eb34..4b2e609 100644 --- a/engineering/hugh/TOOLS.md +++ b/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 diff --git a/engineering/regina/HEARTBEAT.md b/engineering/regina/HEARTBEAT.md index 776d364..222696c 100644 --- a/engineering/regina/HEARTBEAT.md +++ b/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 diff --git a/marketing/samuel/HEARTBEAT.md b/marketing/samuel/HEARTBEAT.md index 02f5c7e..495ebd1 100644 --- a/marketing/samuel/HEARTBEAT.md +++ b/marketing/samuel/HEARTBEAT.md @@ -25,12 +25,34 @@ Then 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": "a413e3b4-14c8-45bc-b732-439d6e296dde", "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 including any context the CMO provided - Determine which mode you're in: **content writing**, **social media**, or **community** - Execute the work (see mode-specific rules below) - Open a PR to `privilegedescalation/marketing` with your output -- Comment on the Paperclip issue with the PR link and a one-line summary -- Mark the issue in-progress, or done if fully resolved + +#### 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": "PR link and one-line summary."}' ### 3. If no assigned work — run your scheduled loop