diff --git a/packages/skills-catalog/catalog/bundled/software-development/github-pr-workflow/SKILL.md b/packages/skills-catalog/catalog/bundled/software-development/github-pr-workflow/SKILL.md index 6ce844f1b0a..46836ea7dc8 100644 --- a/packages/skills-catalog/catalog/bundled/software-development/github-pr-workflow/SKILL.md +++ b/packages/skills-catalog/catalog/bundled/software-development/github-pr-workflow/SKILL.md @@ -70,6 +70,24 @@ Skip the `Risk and rollback` section only for clearly trivial PRs (typos, docs). - For migrations, include a dry-run plan and reversal steps. - For performance changes, include a before/after measurement, not adjectives. +## Automated code-review bots + +Automated review bots (Greptile, Superagent, Socket, Snyk, and similar) leave +their verdicts on the PR itself rather than in the required-checks list. Treat +their signal as part of the merge gate, not commentary: + +- Before flipping a PR from draft to ready, resolve every open bot comment on + the current head. If the bot exposes a confidence score (Greptile: `x/5`), + the exit condition is the top score, not "green enough". +- If a bot posts new comments after you push, address them in the same run — + do not defer to a later heartbeat and do not wait to be asked. +- If a bot's verdict is genuinely wrong, resolve the thread with a one-sentence + rationale on the PR. Silent dismissal reads as "not addressed" to the human + reviewer. +- For long-lived split PRs (child PRs of a larger recovery/split), run this + loop on every child before handing the parent back — don't rely on the human + to fan out the ask. + ## Replying to review comments - Reply on every comment, even with just "fixed in " — silent fixes leave the reviewer guessing. @@ -80,6 +98,10 @@ Skip the `Risk and rollback` section only for clearly trivial PRs (typos, docs). ## Merge checklist - All required checks green. +- All automated code-review bots satisfied on the current head SHA (Greptile + at top confidence with zero unresolved threads, Superagent security scan + cleared, etc.). Bot signals sit outside the required-checks list and must + be checked separately. - All review comments resolved. - PR title/body still accurate (update if scope changed mid-review). - Linked issue moves to `in_review` or `done` per project convention. diff --git a/skills/paperclip/SKILL.md b/skills/paperclip/SKILL.md index 3c9b66555cd..ea488f73df7 100644 --- a/skills/paperclip/SKILL.md +++ b/skills/paperclip/SKILL.md @@ -396,6 +396,39 @@ PUT /api/issues/{issueId}/documents/plan If `plan` already exists, fetch the current document first and send its latest `baseRevisionId` when you update it. +## Authorization boundaries — check ownership before mutating another agent's issue + +The Paperclip API scopes write access to the authorization boundary of the +currently-checked-out issue. If you try to `PATCH /api/issues/{id}` or +`POST /api/issues/{id}/comments` on an issue you do not own, the API returns +`403 Issue is outside this actor's authorization boundary` and the mutation +is dropped. This is a per-run scope, not a per-agent scope: you can own an +issue conceptually and still hit 403 from a different task-bridge run. + +**Before you mutate another agent's issue, do one of:** + +1. Check the target issue's `assigneeAgentId` and `authorizationBoundary` fields: + ```sh + curl -sS "$PAPERCLIP_API_URL/api/issues/" \ + -H "Authorization: Bearer $PAPERCLIP_API_KEY" \ + | jq '{assignee: .assigneeAgentId, boundary: .authorizationBoundary}' + ``` + If the assignee is not you and the boundary does not include you, do not + attempt the write. Route the ask instead. +2. Route the ask via one of: + - A comment on your own issue naming the target owner and the desired change. + - A child issue assigned to the owner with the mutation encoded as its body. + - An `interactions` request on your issue when a human/board approval is + the correct escalation. + +**Do not** treat the 403 as a signal to retry with a different verb — the +boundary is real. Retrying wastes the heartbeat and leaves the mutation +un-owned. + +This applies especially to coordinator roles (CTO, plan owners, routine +owners) that regularly need to clear blockers on issues held by engineers, +QA, or CloudOps. + ## Key Endpoints (Hot Routes) | Action | Endpoint |