pr-shepherd 0.5.2 → 0.7.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -2,6 +2,19 @@
 
 Autonomous PR CI monitor and review-comment resolver for Claude Code.
 
+## Why pr-shepherd
+
+Concrete improvements to an agentic PR-review workflow:
+
+- **Faster monitor loops** — one batched GraphQL query per tick (see [docs/graphql.md](docs/graphql.md)) instead of N REST round-trips
+- **Lower context usage per iteration** — classification lives in TypeScript; the agent receives one decision per tick and never sees raw GraphQL payloads or resolved threads
+- **Deterministic output** — `--format=json` and `--format=text` surface equivalent information, so both scripts and agents see the same state
+- **Prompt-cache friendly** — the 4-minute default tick is tuned to Claude's 5-minute prompt-cache TTL (tunable via `watch.interval`)
+- **Reduced GitHub rate-limit exposure** — read results share a 5-minute file cache with atomic writes (see [docs/cache.md](docs/cache.md))
+- **No MCP surface** — skills call the CLI via `npx`; no long-lived MCP server, no extra auth boundary, smaller reasoning surface
+- **Skills over subagents** — skill prompts inject into the main conversation rather than spawning a subagent that reloads CLAUDE.md every turn
+- **Safe to interrupt** — all state lives in the PR on GitHub; the cron loop self-terminates when the PR is merged, closed, or settles after ready-delay
+
 ## Design principles
 
 - **Reduced agent context** — logic lives in the CLI, not the prompt
@@ -10,14 +23,32 @@ Autonomous PR CI monitor and review-comment resolver for Claude Code.
 - **No MCP** — smaller reasoning surface, much faster than the GitHub MCP
 - **No vendor lock-in** — runs against `gh` + `git`; no hosted service required
 - **Skills over subagents** — subagents reload all CLAUDE.md context on every turn; skills inject into the main conversation instead, keeping cost low
+- **JSON/text parity** — `--format=json` and `--format=text` carry equivalent information; every field in one has a representation in the other
 
 ## Features
 
-- **CI handling** — cancels runs on actionable failures, reruns on transient/infra failures, skips non-PR trigger events
-- **Comments** — resolves inline threads (including bot and AI reviewer comments), auto-resolves outdated threads before the agent sees them, aggressively hides bot comments, paginates and filters server-side
-- **Readiness** — converts draft → ready-for-review when CI passes, waits for pending Copilot reviews, settles for a configurable window (default 10 min) before exiting
-- **Rebases on conflict** — automatically rebases on the PR base branch when merge conflicts appear
-- **Intended as a PR merge blocker** — pair with a GitHub Actions required check that verifies all threads are resolved
+pr-shepherd is split into a CLI (deterministic, pure GitHub I/O) and three Claude Code skills that wrap the CLI with model-driven flow and mutation.
+
+### What the CLI does
+
+Deterministic commands that fetch, classify, and mutate PR state without invoking the model:
+
+- **`check`** — one-shot PR snapshot (merge state, CI results, unresolved comments) via a single batched GraphQL query
+- **`resolve`** — fetch/triage mode auto-resolves outdated threads and returns actionable items; mutate mode batch-resolves threads, minimizes comments, and dismisses reviews by ID, polling `--require-sha` so reviewers see the push before threads close
+- **`iterate`** — classifies current PR state and emits exactly one of eight actions: `cooldown`, `wait`, `rerun_ci`, `mark_ready`, `rebase`, `fix_code`, `cancel`, `escalate` (see [docs/actions.md](docs/actions.md))
+- **`status`** — multi-PR summary table, one lightweight GraphQL query per PR in parallel
+
+Cross-cutting machinery: file cache with atomic writes ([docs/cache.md](docs/cache.md)), merge-status derivation ([docs/merge-status.md](docs/merge-status.md)), CI failure classification into `actionable` / `infrastructure` / `timeout` / `flaky` ([docs/checks.md](docs/checks.md)), outdated-thread detection ([docs/comments.md](docs/comments.md)), deprecation-warning-aware RC loader.
+
+### What the skills do
+
+Claude Code skills that wrap the CLI with model-driven triage, code edits, and flow control:
+
+- **`/pr-shepherd:check`** — calls `check --format=json` and prints a human summary; never declares "ready to merge" unless every gate passes (merge status CLEAN, status READY, Copilot review not in progress)
+- **`/pr-shepherd:monitor`** — creates a `/loop` cron job (4-minute default, 8-hour expiry, 50-turn cap), deduplicates via a `# pr-shepherd-loop:pr=<N>` tag in `CronList`, dispatches on the `[ACTION]` H1 tag each tick, runs rebase scripts and fix instructions in the main conversation
+- **`/pr-shepherd:resolve`** — runs `resolve --fetch`, triages every returned item into Fixed / Actionable / Not-relevant / Outdated / Acknowledge (no silent drops — this is a project invariant), applies edits, cancels stale CI runs, pushes, then calls `resolve` in mutate mode with `--require-sha`
+
+See [docs/skills.md](docs/skills.md) for full skill reference.
 
 ## Install
 
@@ -99,7 +130,7 @@ to be installed in the repository first (`npm install pr-shepherd`), so that
    ```
 
 For `monitor` and `resolve` custom commands, do **not** copy the
-[`skills/`](skills/) files directly — those contain skill/plugin-specific
+[`plugin/skills/`](plugin/skills/) files directly — those contain skill/plugin-specific
 frontmatter that is not valid for `.claude/commands/` files. Instead, create
 `.claude/commands/pr-monitor.md` and/or `.claude/commands/pr-resolve.md`
 using the same command-file structure as the `pr-check` example above, with
@@ -154,7 +185,7 @@ See [docs/skills.md](docs/skills.md) for full argument reference.
 
 ## Workflow
 
-On each 4-minute tick: fetch PR state in one GraphQL batch → classify CI, comments, and merge status → take one action (fix code, rebase, rerun CI, mark ready, or wait). See [docs/flow.md](docs/flow.md) for the full decision tree.
+On each tick (4-minute default, tunable via `watch.interval`): fetch PR state in one GraphQL batch → classify CI, comments, and merge status → take one action (fix code, rebase, rerun CI, mark ready, or wait). See [docs/flow.md](docs/flow.md) for the full decision tree.
 
 ## CLI
 
@@ -167,11 +198,11 @@ pr-shepherd status PR1 [PR2 …]                        # multi-PR table
 
 Common flags (all subcommands):
 
-| Flag                  | Default | Description                                                                    |
-| --------------------- | ------- | ------------------------------------------------------------------------------ |
-| `--format text\|json` | `text`  | Output format                                                                  |
-| `--no-cache`          | false   | Bypass the 5-minute file cache                                                 |
-| `--cache-ttl N`       | `300`   | Cache TTL in seconds; `PR_SHEPHERD_CACHE_TTL_SECONDS` env var takes precedence |
+| Flag                  | Default | Description                                                                         |
+| --------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `--format text\|json` | `text`  | Output format                                                                       |
+| `--no-cache`          | false   | Bypass the 5-minute file cache                                                      |
+| `--cache-ttl N`       | `300`   | Cache TTL in seconds; takes precedence over `PR_SHEPHERD_CACHE_TTL_SECONDS` env var |
 
 ### pr-shepherd check [PR]
 
@@ -267,18 +298,20 @@ Flags:
 | `--no-auto-mark-ready`        | false   | Skip converting draft → ready-for-review          |
 | `--no-auto-cancel-actionable` | false   | Skip cancelling actionable failing runs           |
 
-**Text output** (one line per action):
+**Markdown output** (default). The monitor SKILL reads the `[ACTION]` tag from the H1 heading to decide what to do. Every action emits an H1, a bolded base-fields line, a bolded summary line, then an action-specific body. Example for `[WAIT]`:
 
+```markdown
+# PR #42 [WAIT]
+
+**status** `READY` · **merge** `CLEAN` · **state** `OPEN` · **repo** `owner/repo`
+**summary** 3 passing, 0 skipped, 0 filtered, 0 inProgress · **remainingSeconds** 540 · **copilotReviewInProgress** false · **isDraft** false · **shouldCancel** false
+
+WAIT: 3 passing, 0 in-progress — 540s until auto-cancel
 ```
-PR #42 [COOLDOWN] status=UNKNOWN merge=UNKNOWN (cooldown: CI still starting)
-PR #42 [WAIT] status=READY merge=CLEAN (540s until cancel)
-PR #42 [RERUN_CI] status=FAILING merge=UNSTABLE reran=12345,67890
-PR #42 [FIX_CODE] status=UNRESOLVED_COMMENTS merge=BLOCKED threads=2 comments=0 checks=1 cancelled=1
-PR #42 [REBASE] status=FAILING merge=BEHIND (branch is behind main)
-PR #42 [MARK_READY] status=READY merge=CLEAN markedReady=true
-PR #42 [CANCEL] status=READY merge=CLEAN (ready-delay elapsed)
-PR #42 [ESCALATE] status=UNRESOLVED_COMMENTS merge=BLOCKED triggers=fix-thrash — Same thread(s) attempted multiple times without resolution — fix manually then rerun /pr-shepherd:monitor
-```
+
+See [docs/actions.md](docs/actions.md) for the other seven actions — `cooldown`, `rerun_ci`, `mark_ready`, `cancel`, `rebase`, `fix_code`, `escalate`. `fix_code` is the richest: it emits sections for `## Review threads`, `## Actionable comments`, `## Failing checks`, `## Changes-requested reviews`, `## Noise (minimize only)`, `## Cancelled runs`, `## Rebase`, and `## Instructions`.
+
+Both `--format=text` (default Markdown) and `--format=json` carry equivalent information — every field exposed in JSON has a corresponding Markdown representation, and vice versa.
 
 **JSON output** (`--format=json`, compact single line):
 
@@ -322,7 +355,7 @@ Exit code: `0` if every PR is READY, `1` otherwise.
 
 ## Configuration
 
-Create a `.pr-shepherdrc.yml` in your project root (or any parent directory) to override defaults:
+Create a `.pr-shepherdrc.yml` in your project root (or any parent directory) to override defaults. The loader walks up from `cwd` to `$HOME` (if `$HOME` is on that path) or the filesystem root; the first match wins.
 
 ```yaml
 iterate:
@@ -336,12 +369,39 @@ actions:
   autoRebase: false # disable for repos that enforce merge commits
 ```
 
-See [docs/configuration.md](docs/configuration.md) for all options.
+All supported keys:
+
+| Key                                  | Default                                   | Purpose                                                                          |
+| ------------------------------------ | ----------------------------------------- | -------------------------------------------------------------------------------- |
+| `cache.ttlSeconds`                   | `300`                                     | File-cache TTL for read operations                                               |
+| `iterate.cooldownSeconds`            | `30`                                      | Wait after a push before reading CI                                              |
+| `iterate.fixAttemptsPerThread`       | `3`                                       | Max fix attempts per unresolved thread before `escalate`                         |
+| `watch.interval`                     | `"4m"`                                    | Monitor tick interval (tuned to Claude's 5-min prompt-cache TTL)                 |
+| `watch.readyDelayMinutes`            | `10`                                      | Settle window after READY before the monitor loop cancels                        |
+| `watch.expiresHours`                 | `8`                                       | Max lifetime of a monitor cron job                                               |
+| `watch.maxTurns`                     | `50`                                      | Max monitor ticks per session                                                    |
+| `resolve.concurrency`                | `4`                                       | Parallel fanout for per-thread GraphQL fetches                                   |
+| `resolve.shaPoll.intervalMs`         | `2000`                                    | Poll interval when waiting for `--require-sha` to land on GitHub                 |
+| `resolve.shaPoll.maxAttempts`        | `10`                                      | Max `--require-sha` polls before giving up                                       |
+| `resolve.fetchReviewSummaries`       | `true`                                    | Surface `COMMENTED` review summaries in `resolve --fetch` output                 |
+| `checks.ciTriggerEvents`             | `["pull_request", "pull_request_target"]` | Workflow `on:` events treated as PR CI (add `merge_group` for merge-queue repos) |
+| `checks.timeoutPatterns`             | see [`src/config.json`](src/config.json)  | Log patterns that classify a failure as `timeout`                                |
+| `checks.infraPatterns`               | see [`src/config.json`](src/config.json)  | Log patterns that classify a failure as `infrastructure`                         |
+| `checks.logMaxLines`                 | `50`                                      | Max log lines kept per failing check                                             |
+| `checks.logMaxChars`                 | `3000`                                    | Max log characters kept per failing check                                        |
+| `mergeStatus.blockingReviewerLogins` | `["copilot"]`                             | Reviewer logins whose pending review blocks `mark_ready`                         |
+| `actions.autoResolveOutdated`        | `true`                                    | Auto-resolve threads that point to code no longer in the PR diff                 |
+| `actions.autoRebase`                 | `true`                                    | Emit `rebase` for flaky failures when the branch is behind base                  |
+| `actions.autoMarkReady`              | `true`                                    | Emit `mark_ready` when a draft PR's CI goes clean                                |
+
+Environment variables: `GH_TOKEN` / `GITHUB_TOKEN` (auth; falls back to `gh auth token`), `PR_SHEPHERD_CACHE_DIR` (override cache base dir), `PR_SHEPHERD_CACHE_TTL_SECONDS` (override cache TTL; `--cache-ttl` takes precedence over this env var, which in turn takes precedence over the RC/config value).
+
+See [docs/configuration.md](docs/configuration.md) for full semantics and deprecated-key migration.
 
 ## Requirements
 
 - Node.js ≥ 22.0.0
-- `gh` CLI authenticated (`gh auth login`); `repo` scope is required for private repositories (public repositories may not need it)
+- A GitHub token: set `GH_TOKEN` or `GITHUB_TOKEN`, **or** install and authenticate the `gh` CLI (`gh auth login`) — pr-shepherd uses `gh auth token` as a fallback. The `repo` scope is required for private repositories.
 - `git`
 
 ## Docs

package/bin/checks/triage.mjs

@@ -8,10 +8,8 @@
  * Shepherd computes and returns triage results, including `failureKind`, for
  * downstream callers or slash-command logic to consume.
  */
-import { execFile as execFileCb } from "node:child_process";
-import { promisify } from "node:util";
+import { rest, restText } from "../github/http.mjs";
 import { loadConfig } from "../config/load.mjs";
-const execFile = promisify(execFileCb);
 const config = loadConfig();
 const TIMEOUT_PATTERNS = config.checks.timeoutPatterns.map((p) => new RegExp(p, "i"));
 const INFRA_PATTERNS = config.checks.infraPatterns.map((p) => new RegExp(p, "i"));
@@ -23,17 +21,17 @@ const INFRA_PATTERNS = config.checks.infraPatterns.map((p) => new RegExp(p, "i")
  *
  * Fetching logs is skipped for checks that have no `runId` (e.g. StatusContext nodes).
  */
-export function triageFailingChecks(failingChecks) {
-    return Promise.all(failingChecks.map((c) => triageCheck(c)));
+export function triageFailingChecks(failingChecks, repo) {
+    return Promise.all(failingChecks.map((c) => triageCheck(c, repo)));
 }
 // ---------------------------------------------------------------------------
 // Internal
 // ---------------------------------------------------------------------------
-async function triageCheck(check) {
+async function triageCheck(check, repo) {
     if (check.runId === null) {
         return { ...check, failureKind: "actionable" };
     }
-    const logExcerpt = await fetchFailedLogs(check.runId);
+    const logExcerpt = await fetchFailedLogs(check.runId, repo);
     const failureKind = classifyLogs(check, logExcerpt);
     return {
         ...check,
@@ -41,37 +39,54 @@ async function triageCheck(check) {
         logExcerpt: logExcerpt.slice(-config.checks.logMaxChars) || undefined,
     };
 }
-async function fetchFailedLogs(runId) {
+async function fetchFailedLogs(runId, repo) {
     try {
-        const { stdout } = await execFile("gh", ["run", "view", runId, "--log-failed"], {
-            maxBuffer: config.execution.triageLogBufferMb * 1024 * 1024,
-        });
-        // Strip ANSI escape codes.
-        // eslint-disable-next-line no-control-regex
+        const { owner, name } = repo;
+        const perPage = 100;
+        const allJobs = [];
+        for (let page = 1;; page++) {
+            const jobsData = await rest("GET", `/repos/${owner}/${name}/actions/runs/${runId}/jobs?filter=latest&per_page=${perPage}&page=${page}`);
+            allJobs.push(...jobsData.jobs);
+            if (jobsData.jobs.length < perPage)
+                break;
+        }
+        const failedJobs = allJobs.filter((j) => ["failure", "timed_out", "cancelled"].includes(j.conclusion ?? ""));
+        if (failedJobs.length === 0)
+            return "";
+        const logParts = await Promise.all(failedJobs.map(async (job) => {
+            try {
+                // Job-level endpoint (jobs/{id}/logs) redirects to plain text, unlike
+                // run-level (runs/{id}/logs) which returns a ZIP archive.
+                const logs = await restText(`/repos/${owner}/${name}/actions/jobs/${job.id}/logs`);
+                return logs.trim() ? `===== job: ${job.name} =====\n${logs}` : "";
+            }
+            catch {
+                return "";
+            }
+        }));
+        const combined = logParts.filter(Boolean).join("\n");
         const ansiEscapes = /\u001B\[[0-9;]*m/g;
-        return stdout.replace(ansiEscapes, "").split("\n").slice(-config.checks.logMaxLines).join("\n");
+        return combined
+            .replace(ansiEscapes, "")
+            .split("\n")
+            .slice(-config.checks.logMaxLines)
+            .join("\n");
     }
     catch {
         return "";
     }
 }
 function classifyLogs(check, logs) {
-    // Timed out — check conclusion first, then logs.
     if (check.conclusion === "TIMED_OUT")
         return "timeout";
     if (TIMEOUT_PATTERNS.some((re) => re.test(logs)))
         return "timeout";
-    // Infrastructure error — typically CANCELLED with infra markers in logs.
     if (check.conclusion === "CANCELLED" && INFRA_PATTERNS.some((re) => re.test(logs))) {
         return "infrastructure";
     }
-    // No logs at all — treat as infrastructure.
     if (!logs.trim())
         return "infrastructure";
-    // Heuristic: if the failure is in a file the PR likely didn't touch
-    // and the message contains "flaky" or timing language, call it flaky.
     if (/flaky|timing|race condition|retry/i.test(logs))
         return "flaky";
-    // Default: assume actionable.
     return "actionable";
 }

package/bin/cli.mjs

@@ -6,12 +6,12 @@
  *   pr-shepherd resolve [PR] [--fetch] [--resolve-thread-ids A,B] [--minimize-comment-ids X,Y]
  *                            [--dismiss-review-ids Q] [--message MSG] [--require-sha SHA]
  *                            [--last-push-time N]
- *   pr-shepherd iterate [PR] [--cooldown-seconds N] [--ready-delay Nm] [--last-push-time N]
+ *   pr-shepherd iterate [PR] [--format text|json] [--cooldown-seconds N] [--ready-delay Nm] [--last-push-time N]
  *   pr-shepherd status PR1 [PR2 …]
  */
 import { runCheck } from "./commands/check.mjs";
 import { runResolveFetch, runResolveMutate } from "./commands/resolve.mjs";
-import { runIterate } from "./commands/iterate.mjs";
+import { runIterate, renderResolveCommand } from "./commands/iterate.mjs";
 import { runStatus, formatStatusTable } from "./commands/status.mjs";
 import { getRepoInfo } from "./github/client.mjs";
 import { formatJson } from "./reporters/json.mjs";
@@ -163,9 +163,16 @@ function formatFetchResult(result) {
             lines.push(`  - reviewId=${r.id} (@${r.author})`);
         }
     }
+    if (result.reviewSummaries.length > 0) {
+        lines.push(`\nReview summaries (${result.reviewSummaries.length}):`);
+        for (const r of result.reviewSummaries) {
+            lines.push(`  - reviewId=${r.id} (@${r.author}): ${r.body.split("\n")[0].slice(0, 100)}`);
+        }
+    }
     const total = result.actionableThreads.length +
         result.actionableComments.length +
-        result.changesRequestedReviews.length;
+        result.changesRequestedReviews.length +
+        result.reviewSummaries.length;
     lines.push(`\nSummary: ${total === 0 ? "0 actionable — all threads resolved/minimized" : `${total} actionable item(s)`}`);
     return `${lines.join("\n")}\n`;
 }
@@ -181,24 +188,99 @@ function formatMutateResult(result) {
         lines.push(`Errors:\n  ${result.errors.join("\n  ")}`);
     return `${lines.join("\n")}\n`;
 }
+/**
+ * Format an IterateResult as human-readable Markdown.
+ *
+ * Load-bearing conventions the monitor SKILL relies on:
+ *   1. The H1 heading on line 1 contains `[<ACTION>]` — the SKILL greps this tag.
+ *   2. The `resolve` bullet under `## Rebase` wraps the command in backticks —
+ *      the SKILL extracts the backticked content for execution.
+ *   3. The shell script under `[REBASE]` is inside a ```bash fenced block.
+ *   4. `## Instructions` items are numbered `1.`, `2.`, … and executed in order.
+ */
 function formatIterateResult(result) {
-    const base = `PR #${result.pr} [${result.action.toUpperCase()}] status=${result.status} merge=${result.mergeStateStatus}`;
+    const heading = `# PR #${result.pr} [${result.action.toUpperCase()}]`;
+    const baseLine = `**status** \`${result.status}\` · **merge** \`${result.mergeStateStatus}\` · **state** \`${result.state}\` · **repo** \`${result.repo}\``;
+    const summaryLine = `**summary** ${result.summary.passing} passing, ${result.summary.skipped} skipped, ${result.summary.filtered} filtered, ${result.summary.inProgress} inProgress · **remainingSeconds** ${result.remainingSeconds} · **copilotReviewInProgress** ${result.copilotReviewInProgress} · **isDraft** ${result.isDraft} · **shouldCancel** ${result.shouldCancel}`;
+    const header = [heading, "", baseLine, summaryLine].join("\n");
     switch (result.action) {
         case "cooldown":
-            return `${base} (cooldown: CI still starting)`;
         case "wait":
-            return `${base} (${result.remainingSeconds}s until cancel)`;
         case "cancel":
-            return `${base} (ready-delay elapsed)`;
-        case "fix_code":
-            return `${base} threads=${result.fix.threads.length} comments=${result.fix.comments.length} checks=${result.fix.checks.length} cancelled=${result.cancelled.length}`;
         case "rerun_ci":
-            return `${base} reran=${result.reran.join(",")}`;
-        case "rebase":
-            return `${base} (branch is behind main)`;
         case "mark_ready":
-            return `${base} markedReady=${result.markedReady}`;
+            return [header, "", result.log].join("\n");
+        case "rebase":
+            return [
+                header,
+                "",
+                result.rebase.reason,
+                "",
+                "```bash",
+                result.rebase.shellScript,
+                "```",
+            ].join("\n");
         case "escalate":
-            return `${base} triggers=${result.escalate.triggers.join(",")} — ${result.escalate.suggestion}`;
+            return [header, "", result.escalate.humanMessage].join("\n");
+        case "fix_code":
+            return formatFixCodeResult(header, result);
     }
 }
+function formatFixCodeResult(header, result) {
+    const sections = [header];
+    if (result.fix.threads.length > 0) {
+        sections.push("## Review threads");
+        for (const t of result.fix.threads) {
+            const loc = t.path ? `\`${t.path}:${t.line ?? "?"}\`` : "(no location)";
+            sections.push(`### \`${t.id}\` — ${loc} (@${t.author})`);
+            sections.push(blockquote(t.body));
+        }
+    }
+    if (result.fix.actionableComments.length > 0) {
+        sections.push("## Actionable comments");
+        for (const c of result.fix.actionableComments) {
+            sections.push(`### \`${c.id}\` (@${c.author})`);
+            sections.push(blockquote(c.body));
+        }
+    }
+    if (result.fix.checks.length > 0) {
+        sections.push("## Failing checks");
+        const bullets = result.fix.checks.map((ch) => {
+            const kind = ch.failureKind ?? "actionable";
+            if (ch.runId)
+                return `- \`${ch.runId}\` — \`${ch.name}\` (${kind})`;
+            if (ch.detailsUrl)
+                return `- external \`${ch.detailsUrl}\` — \`${ch.name}\` (${kind})`;
+            return `- (no runId) — \`${ch.name}\` (${kind})`;
+        });
+        sections.push(bullets.join("\n"));
+    }
+    if (result.fix.changesRequestedReviews.length > 0) {
+        sections.push("## Changes-requested reviews");
+        sections.push(result.fix.changesRequestedReviews.map((r) => `- \`${r.id}\` (@${r.author})`).join("\n"));
+    }
+    if (result.fix.noiseCommentIds.length > 0) {
+        sections.push("## Noise (minimize only)");
+        sections.push(result.fix.noiseCommentIds.map((id) => `\`${id}\``).join(", "));
+    }
+    if (result.cancelled.length > 0) {
+        sections.push("## Cancelled runs");
+        sections.push(result.cancelled.map((id) => `\`${id}\``).join(", "));
+    }
+    sections.push("## Rebase");
+    sections.push([
+        `- base: \`${result.baseBranch}\``,
+        `- resolve: \`${renderResolveCommand(result.fix.resolveCommand)}\``,
+    ].join("\n"));
+    if (result.fix.instructions.length > 0) {
+        sections.push("## Instructions");
+        sections.push(result.fix.instructions.map((inst, i) => `${i + 1}. ${inst}`).join("\n"));
+    }
+    return sections.join("\n\n");
+}
+function blockquote(body) {
+    return body
+        .split("\n")
+        .map((line) => (line === "" ? ">" : `> ${line}`))
+        .join("\n");
+}

package/bin/commands/check.mjs

@@ -6,10 +6,11 @@
  *
  * Exit codes:
  *   0  READY — all checks passed, no unresolved threads, CLEAN merge status.
- *   1  FAILING — one or more CI checks failed.
+ *   1  FAILING — CI has red checks, or merge has conflicts.
+ *   1  PENDING — CI passing but merge blocked (BLOCKED, UNSTABLE, or BEHIND).
+ *   1  UNKNOWN — merge state unresolvable.
  *   2  IN_PROGRESS — CI checks still running.
  *   3  UNRESOLVED_COMMENTS — CI ok but actionable threads remain.
- *   1  (also) BLOCKED/CONFLICTS/UNKNOWN merge status.
  */
 import { fetchPrBatch } from "../github/batch.mjs";
 import { getRepoInfo, getCurrentPrNumber, getMergeableState } from "../github/client.mjs";
@@ -60,7 +61,7 @@ export async function runCheck(opts) {
     const skipped = classifiedChecks.filter((c) => c.category === "skipped");
     const filtered = classifiedChecks.filter((c) => c.category === "filtered");
     // Triage failures (fetch logs) — skipped when caller will short-circuit before needing failureKind.
-    const triaged = failing.length > 0 && !opts.skipTriage ? await triageFailingChecks(failing) : failing;
+    const triaged = failing.length > 0 && !opts.skipTriage ? await triageFailingChecks(failing, repo) : failing;
     // Resolve threads and comments.
     const unresolvedThreads = batchData.reviewThreads.filter((t) => !t.isResolved && !t.isMinimized);
     const visibleComments = batchData.comments.filter((c) => !c.isMinimized);
@@ -85,11 +86,13 @@ export async function runCheck(opts) {
         !verdict.anyInProgress &&
         verdict.filteredNames.length > 0;
     // Compute overall status.
-    const status = computeStatus(verdict, actionableThreads.length, actionableComments.length, mergeStatus.status, batchData.changesRequestedReviews.length);
+    const status = computeStatus(verdict, actionableThreads.length, actionableComments.length, mergeStatus, batchData.changesRequestedReviews.length);
     return {
         pr: prNumber,
+        nodeId: batchData.nodeId,
         repo: `${repo.owner}/${repo.name}`,
         status,
+        baseBranch: batchData.baseRefName,
         mergeStatus,
         checks: {
             passing,
@@ -117,24 +120,38 @@ export async function runCheck(opts) {
 // ---------------------------------------------------------------------------
 function computeStatus(verdict, unresolvedThreads, unresolvedComments, mergeStatus, changesRequestedReviews) {
     // Merge conflicts are always terminal regardless of CI state.
-    if (mergeStatus === "CONFLICTS")
+    if (mergeStatus.status === "CONFLICTS")
         return "FAILING";
     // Check CI state before merge-blocking states: BLOCKED/UNSTABLE/BEHIND are
     // often caused by CI not having passed yet, so they shouldn't mask IN_PROGRESS.
+    // These merge-blocking states become PENDING (not FAILING) once CI is resolved.
     if (verdict.anyFailing)
         return "FAILING";
     if (verdict.anyInProgress)
         return "IN_PROGRESS";
-    if (mergeStatus === "BLOCKED" || mergeStatus === "UNSTABLE" || mergeStatus === "BEHIND")
-        return "FAILING";
-    if (mergeStatus === "UNKNOWN")
+    // BLOCKED solely because a human reviewer hasn't approved yet — shepherd is done, hand off.
+    // copilotReviewInProgress means a bot still owes a review, which is not this case.
+    if (verdict.allPassed &&
+        unresolvedThreads === 0 &&
+        unresolvedComments === 0 &&
+        changesRequestedReviews === 0 &&
+        mergeStatus.status === "BLOCKED" &&
+        !mergeStatus.copilotReviewInProgress &&
+        mergeStatus.reviewDecision === "REVIEW_REQUIRED") {
+        return "READY";
+    }
+    if (mergeStatus.status === "BLOCKED" ||
+        mergeStatus.status === "UNSTABLE" ||
+        mergeStatus.status === "BEHIND")
+        return "PENDING";
+    if (mergeStatus.status === "UNKNOWN")
         return "UNKNOWN";
     if (changesRequestedReviews > 0)
         return "UNRESOLVED_COMMENTS";
     if (unresolvedThreads > 0 || unresolvedComments > 0)
         return "UNRESOLVED_COMMENTS";
     // DRAFT is treated the same as CLEAN for readiness — marking the PR ready resolves it.
-    if ((mergeStatus === "CLEAN" || mergeStatus === "DRAFT") && verdict.allPassed)
+    if ((mergeStatus.status === "CLEAN" || mergeStatus.status === "DRAFT") && verdict.allPassed)
         return "READY";
     return "UNKNOWN";
 }