pr-guardian

Files (5)

• SKILL.md
• openai.yaml · agents/
• guardian-event-contract.md · references/
• pr-feedback-audit.md · references/
• validate_guardian_event.py · scripts/

SKILL.md (first lines)

# PR Guardian

Use this workflow by default after opening a pull request, and when an existing PR needs follow-up after CI, CodeRabbit, Codex, bot, or human review feedback. The goal is to leave the PR merge-ready or report a specific blocker, not to provide a partial status update.

## Workflow

0. Delegate passive monitoring to a compatible guardian runner.
   - Read `references/guardian-event-contract.md`. Require `kaizen-loop guardian capabilities --json` to advertise schema version 1 and durable completion notification support before monitoring. When the repository is registered with a compatible kaizen-loop, start `kaizen-loop guardian run <pr-number> --project <project-slug> --json` once through an execution path that can deliver its terminal event without asking Codex to inspect repeated process snapshots.
   - Do not repeatedly call a tool to poll the guardian process, GitHub, CI, review bots, or the stabilization window. Sleeps, `gh run watch`, GitHub API polling, head-change detection, review-completion checks, and stabilization are passive runner work and must not consume Codex reasoning cycles.
   - If the execution transport yields before completion, use its non-LLM completion notification or detach the durable job and record its job/event location. End the invocation as `monitoring delegated`; resume only from a terminal event. Do not wake Codex merely to observe that nothing changed.
   - Require one terminal event that passes `scripts/validate_guardian_event.py` for the expected repo, PR, job, sequence, and head, as well as a successful runner exit, before accepting `merge_ready`. Confirm the remote head once when consuming that event. Treat missing, stale, mismatched, malformed, or unsupported event output as `blocked: incompatible guardian runner`, never as success.
   - If no compatible durable runner or completion notification exists, inspect and fix immediately actionable state, but do not reproduce the wait loop with agent tool calls. Report `blocked: passive guardian runner unavailable` with the missing capability and installation or upgrade action.
   - `gh pr checks --watch` is only a CI watcher and never satisfies review/thread monitoring by itself.
   - Treat `success` as a convergence checkpoint, not a permanent terminal state while the PR remains open. The durable runner must re-observe successful jobs and reactivate a same-head PR when late review threads, checks, or merge-gate activity make it non-ready.
   - Run durable jobs in a disposable worktree pinned to the observed head. Before pushing, re-read the remote head SHA; if it changed, stop and reconcile the new head instead of overwriting it.

1. Resolve the GitHub CLI before doing any PR work.
   - Resolve a usable GitHub CLI as `GH_BIN`: try `command -v gh`, the active Nix user profiles (`$HOME/.nix-profile/bin/gh` and `$HOME/.local/state/nix/profiles/profile/bin/gh`), `/run/current-system/sw/bin/gh`, then platform fallbacks such as `/opt/homebrew/bin/gh` and `/usr/local/bin/gh`. Use the resolved absolute path for every command in this workflow; desktop and sandboxed agent shells may intentionally sanitize the user's interactive `PATH`.
2. Resolve the target PRs.
   - Use explicit repo or PR URLs when provided.
   - Otherwise identify the current branch PR, branch, remote, and expected base branch.
   - If the user asks for "each repo" or "all repos", scan the relevant workspace repositories, list open PRs, and process one repo at a time.
   - If the user says a PR is still blocked, still remains, or points at a repository PR list, enumerate the open PRs in the relevant repositories and process every PR that is `BLOCKED`, has unresolved review threads, or has actionable bot/human feedback. Do not stop after fixing only the current checkout's branch.
   - Derive the target host and repository from the resolved PR URL or remote. Run `"$GH_BIN" auth status --active --hostname <host>` and a read-only `"$GH_BIN" api --hostname <host> repos/<owner>/<repo> --jq .full_name`. An authentication failure on an unrelated host or inactive account is not a blocker. A missing executable, failed target-host authentication, or insufficient target-repository access is a concrete blocker; report the exact failed command and stderr.
3. Load local repo context before edits.
   - Read local instructions such as `AGENTS.md`, package scripts, branch status, and PR metadata.
   - Preserve unrelated local changes.
4. Build a complete PR state and feedback inventory.
   - Read `mergeStateStatus`, `mergeable`, `reviewDecision`, `statusCheckRollup`, `reviews`, `latestReviews`, review requests, PR comments, and `gh pr checks`.
   - Always fetch thread-aware review data before claiming success. Flat PR comments are not enough because CodeRabbit, Codex, and human actionable feedback is often in inline review threads.
   - Do not treat an earlier PR Guardian summary comment as current evidence. A bot review can arrive after that comment, so every resume must re-fetch PR state, comments, reviews, latest reviews, and review threads from GitHub.
   - Read `references/pr-feedback-audit.md` and run its executable GraphQL cursor loops and REST `--paginate` commands on every target PR before deciding that no feedback remains. Paginate every connection until `hasNextPage=false` by feeding each `endCursor` into the next request, including nested review comments, and exhaust REST reviews, review comments, issue comments, check runs, and annotations. Summaries and first pages are not complete evidence.
5. Classify every feedback item.
   - `fix`: code, docs, tests, CI, or config change is needed.
   - `respond`: a reviewer asked for clarification and no code change is appropriate.
   - `ignore`: duplicate, outdated, already resolved, or demonstrably wrong.
   - `blocked`: credentials, product decision, external service, or maintainer action is required.
6. Handle CI events.
   - Let the durable runner watch pending CI. Use `gh run view` and failing logs only after the runner reports an actionable CI failure.
   - If CI fails, inspect failing jobs and logs, reproduce locally when practical, and make the smallest fix.
7. Implement all `fix` items.
   - Keep edits scoped to the PR and trace each change back to a feedback or CI cluster.
   - Add or update tests when the feedback identifies behavior risk.
   - Do not rewrite unrelated user changes or broaden the PR scope.
8. Handle every current review thread explicitly.
   - Required conversation resolution is per GitHub review thread, not per PR. The merge gate "all comments must be resolved" is satisfied only when every unresolved `reviewThreads` node has been replied to or intentionally handled and then resolved.
   - For `fix` items, reply in the same review thread or directly to the review comment with the fix made and validation run.
   - For `respond` and `ignore` items, reply in the same review thread or directly to the review comment with the clarification or reason the suggestion is not applicable.
   - Reply before resolving. Use the thread's first review comment `fullDatabaseId` for the REST reply endpoint, then resolve the thread with the GraphQL `reviewThreads.nodes[].id`.
   - Resolve each addressed GitHub review thread, including outdated unresolved threads, when permissions allow. If GitHub does not allow replying or resolving, report the thread URL as `blocked: unresolved required conversation`.
   - Do not rely on an aggregate PR comment as a substitute for per-thread disposition; repositories with required conversation resolution stay blocked until each current thread is resolved.
9. Push fixes and return control to the durable runner.
   - After a push, start or reactivate the runner once and end the reasoning pass. Do not have Codex supervise the runner's wait cycle.
   - The runner must re-fetch review threads after CodeRabbit, Codex, or other review automation updates. While a review bot is `pending` or `in_progress`, unresolved-thread counts are provisional and must not appear in a terminal `merge_ready` event.
   - After every expected review bot reaches a terminal state, the runner must re-fetch thread-aware review data before emitting another actionable event or `merge_ready`. New bot comments can appear after CI is already green.
   - Pin the current PR head SHA at the start of every monitoring cycle. After any push, discard all earlier review-completion and quiet-period evidence. Fetch paginated reviews from the REST `pulls/<pr>/reviews` endpoint; an expected bot review counts as complete only when its terminal review `commit_id` equals the pinned head SHA, or a bot-specific terminal API result explicitly names that SHA. `gh pr view --json reviews` is not commit-SHA evidence, and a review with a missing or older SHA is not completion evidence.
   - After all expected bots have terminal evidence for the pinned head, the runner must start a bounded stabilization window. It waits at least 60 seconds, then fetches the head SHA, checks, merge state, review decision, comments, reviews, and all review threads twice, at least 30 seconds apart. Both snapshots must have the same head SHA and no new review or thread activity. Any new push, check transition, comment, review, or thread resets the runner-side window.
   - A rate limit, timeout, or missing current-head terminal review is `pending external review`, never merge-ready. Do not shorten the stabilization window because GitHub temporarily reports `CLEAN` or zero unresolved threads.
   - Continue while `reviewDecision` is `CHANGES_REQUESTED`, required checks are pending or failing, expected bot reviews are pending, any review thread remains unresolved, any actionable top-level PR comment lacks a clear disposition, or `mergeStateStatus` is `BLOCKED`, `DIRTY`, `UNKNOWN`, or `BEHIND`.
10. Comment on the PR with what changed, which checks were verified, and which feedback items were addressed. If a suggestion is not applied, explain why and link to the per-thread reply. If no fixes were needed, claim merge-readiness only after the same final gate below passes; otherwise name the remaining blocker.

## Mergeability gate

When diagnosing an actionable event, inspect current state with commands such as:

```sh
"$GH_BIN" pr view <pr> --json isDraft,mergeStateStatus,mergeable,reviewDecision,statusCheckRollup,reviews,comments,latestReviews,reviewRequests
"$GH_BIN" pr checks <pr>
```

Also re-run the thread-aware GraphQL query and count unresolved review threads:

```sh
"$GH_BIN" api graphql \
  -f owner='<owner>' \
  -f name='<repo>' \
  -F number=<number> \
  -f query='
query($owner:String!, $name:String!, $number:Int!, $cursor:String) {
  repository(owner:$owner, name:$name) {
    pullRequest(number:$number) {
      reviewThreads(first:100, after:$cursor) {
        pageInfo { hasNextPage endCursor }
        nodes {
          id
          isResolved
          isOutdated
          path
          comments(first:20) {
            nodes {
              fullDatabaseId
              url
              author { login }
              body
              outdated
            }
          }
        }
      }
    }
  }
}'
```

If `pageInfo.hasNextPage` is true, paginate before counting unresolved threads. For each unresolved thread that has been handled, reply and resolve:

```sh
"$GH_BIN" api \
  --method POST \
  repos/<owner>/<repo>/pulls/<pr-number>/comments/<top-level-comment-full-database-id>/replies \
  -f body='Fixed in <commit>: <short disposition>. Verified with <command>.'

"$GH_BIN" api graphql \
  -f threadId='<review-thread-id>' \
  -f query='
mutation($threadId:ID!) {
  resolveReviewThread(input:{threadId:$threadId}) {
    thread { id isResolved }
  }

From s-hiraoku/codex-harnesses, MIT.

More from s-hiraoku/codex-harnesses