pr-shepherd 0.7.0 → 0.8.0

package/bin/reporters/text.mjs

@@ -1,101 +1,154 @@
-/**
- * Human-readable text reporter for shepherd check output.
- */
+import { buildCheckInstructions } from "./check-instructions.mjs";
 export function formatText(report) {
-    const lines = [];
-    // Header
-    lines.push(`\nPR #${report.pr} — ${report.repo}`);
-    lines.push(`Status: ${report.status}`);
-    lines.push("");
+    const parts = [];
+    // Header — scan-friendly status lines for quick at-a-glance review
+    parts.push(`\nPR #${report.pr} — ${report.repo}`);
+    parts.push(`Status: ${report.status}`);
+    parts.push(`Base: ${report.baseBranch}`);
+    parts.push("");
     // Merge status
     const ms = report.mergeStatus;
-    lines.push(`Merge Status: ${ms.status}`);
-    lines.push(`  mergeStateStatus:       ${ms.mergeStateStatus}`);
-    lines.push(`  mergeable:              ${ms.mergeable}`);
-    lines.push(`  reviewDecision:         ${ms.reviewDecision ?? "(none)"}`);
-    lines.push(`  isDraft:                ${ms.isDraft}`);
-    lines.push(`  copilotReviewInProgress:${ms.copilotReviewInProgress}`);
-    lines.push("");
+    parts.push("## Merge Status");
+    parts.push("");
+    parts.push(`${ms.status}`);
+    parts.push(`  mergeStateStatus:        ${ms.mergeStateStatus}`);
+    parts.push(`  mergeable:               ${ms.mergeable}`);
+    parts.push(`  reviewDecision:          ${ms.reviewDecision ?? "(none)"}`);
+    parts.push(`  isDraft:                 ${ms.isDraft}`);
+    parts.push(`  copilotReviewInProgress: ${ms.copilotReviewInProgress}`);
+    parts.push("");
     // CI checks
     const { passing, failing, inProgress, skipped } = report.checks;
     const total = passing.length + failing.length + inProgress.length + skipped.length;
-    lines.push(`CI Checks: ${passing.length}/${total} passed`);
+    parts.push("## CI Checks");
+    parts.push("");
+    parts.push(`${passing.length}/${total} passed`);
+    parts.push("");
     if (failing.length > 0) {
-        lines.push(`\nFailed Checks (${failing.length}):`);
+        parts.push(`### Failed (${failing.length})`);
+        parts.push("");
         for (const c of failing) {
             const triaged = c;
-            const kind = triaged.failureKind ? ` [${triaged.failureKind}]` : "";
-            lines.push(`  - ${c.name}${kind}: ${c.conclusion ?? c.status}`);
-            if (triaged.logExcerpt) {
-                lines.push(indent(triaged.logExcerpt.split("\n").slice(-10).join("\n"), "    "));
+            const prefix = triaged.workflowName ? `${triaged.workflowName} › ` : "";
+            parts.push(`- ${prefix}${c.name}: ${c.conclusion ?? c.status}`);
+            if (triaged.failedStep) {
+                parts.push(`    failed step: ${triaged.failedStep}`);
+            }
+            if (triaged.summary) {
+                parts.push(`    summary: ${triaged.summary}`);
             }
         }
+        parts.push("");
     }
     if (inProgress.length > 0) {
-        lines.push(`\nIn Progress (${inProgress.length}):`);
+        parts.push(`### In Progress (${inProgress.length})`);
+        parts.push("");
         for (const c of inProgress) {
-            lines.push(`  - ${c.name}: ${c.status}`);
+            parts.push(`- ${c.name}: ${c.status}`);
         }
+        parts.push("");
     }
     if (skipped.length > 0) {
-        lines.push(`\nSkipped (${skipped.length}): ${skipped.map((c) => c.name).join(", ")}`);
+        parts.push(`### Skipped (${skipped.length}): ${skipped.map((c) => c.name).join(", ")}`);
+        parts.push("");
     }
     if (report.checks.filtered.length > 0) {
-        lines.push(`\nFiltered (non-PR-trigger) (${report.checks.filtered.length}): ${report.checks.filtered.map((c) => c.name).join(", ")}`);
+        parts.push(`### Filtered non-PR-trigger (${report.checks.filtered.length}): ${report.checks.filtered.map((c) => c.name).join(", ")}`);
+        parts.push("");
         if (report.checks.blockedByFilteredCheck) {
-            lines.push("  Note: PR is BLOCKED and all filtered checks are non-PR-trigger — one of these filtered checks may be a required status check blocking merge.");
+            parts.push("  Note: PR is BLOCKED and all filtered checks are non-PR-trigger — one of these filtered checks may be a required status check blocking merge.");
         }
         else if (report.mergeStatus.status === "BLOCKED") {
-            lines.push("  Note: one or more of these filtered checks may be a required status check blocking merge.");
+            parts.push("  Note: one or more of these filtered checks may be a required status check blocking merge.");
         }
+        parts.push("");
     }
-    lines.push("");
     // Review threads
     const { actionable: actionableThreads, autoResolved, autoResolveErrors } = report.threads;
-    if (autoResolved.length > 0) {
-        lines.push(`Auto-resolved outdated threads (${autoResolved.length}):`);
-        for (const t of autoResolved) {
-            lines.push(`  - threadId=${t.id} ${t.path ?? ""}:${t.line ?? "?"} (@${t.author})`);
+    const hasThreadSection = autoResolved.length > 0 || autoResolveErrors.length > 0 || actionableThreads.length > 0;
+    if (hasThreadSection) {
+        parts.push("## Review Threads");
+        parts.push("");
+        if (autoResolved.length > 0) {
+            parts.push(`Auto-resolved outdated (${autoResolved.length}):`);
+            for (const t of autoResolved) {
+                parts.push(`- threadId=${t.id} ${t.path ?? ""}:${t.line ?? "?"} (@${t.author})`);
+            }
+            parts.push("");
         }
-        lines.push("");
-    }
-    if (autoResolveErrors.length > 0) {
-        lines.push(`Auto-resolve errors (${autoResolveErrors.length}):`);
-        for (const e of autoResolveErrors) {
-            lines.push(`  - ${e}`);
+        if (autoResolveErrors.length > 0) {
+            parts.push(`Auto-resolve errors (${autoResolveErrors.length}):`);
+            for (const e of autoResolveErrors) {
+                parts.push(`- ${e}`);
+            }
+            parts.push("");
         }
-        lines.push("");
-    }
-    if (actionableThreads.length > 0) {
-        lines.push(`Actionable Review Threads (${actionableThreads.length}):`);
-        for (const t of actionableThreads) {
-            const label = t.path ? `${t.path}:${t.line ?? "?"}` : "(general)";
-            lines.push(`  - threadId=${t.id} ${label} (@${t.author})`);
-            lines.push(`    ${firstLine(t.body)}`);
+        if (actionableThreads.length > 0) {
+            parts.push(`### Actionable (${actionableThreads.length})`);
+            parts.push("");
+            for (const t of actionableThreads) {
+                const label = t.path ? `${t.path}:${t.line ?? "?"}` : "(general)";
+                parts.push(`- threadId=${t.id} ${label} (@${t.author})`);
+                parts.push(`  ${firstLine(t.body)}`);
+            }
+            parts.push("");
         }
-        lines.push("");
     }
     // PR comments
     const { actionable: actionableComments } = report.comments;
     if (actionableComments.length > 0) {
-        lines.push(`Actionable PR Comments (${actionableComments.length}):`);
+        parts.push("## PR Comments");
+        parts.push("");
+        parts.push(`### Actionable (${actionableComments.length})`);
+        parts.push("");
         for (const c of actionableComments) {
-            lines.push(`  - commentId=${c.id} (@${c.author}): ${firstLine(c.body)}`);
+            parts.push(`- commentId=${c.id} (@${c.author}): ${firstLine(c.body)}`);
         }
-        lines.push("");
+        parts.push("");
     }
     // CHANGES_REQUESTED reviews
     if (report.changesRequestedReviews.length > 0) {
-        lines.push(`Pending CHANGES_REQUESTED reviews (${report.changesRequestedReviews.length}):`);
+        parts.push("## CHANGES_REQUESTED Reviews");
+        parts.push("");
         for (const r of report.changesRequestedReviews) {
-            lines.push(`  - reviewId=${r.id} (@${r.author}): ${firstLine(r.body)}`);
+            parts.push(`- reviewId=${r.id} (@${r.author}): ${firstLine(r.body)}`);
         }
-        lines.push("");
+        parts.push("");
+    }
+    // Review summaries
+    if (report.reviewSummaries.length > 0) {
+        parts.push("## Review Summaries");
+        parts.push("");
+        for (const r of report.reviewSummaries) {
+            parts.push(`- reviewId=${r.id} (@${r.author}): ${firstLine(r.body)}`);
+        }
+        parts.push("");
+    }
+    // Approved reviews
+    if (report.approvedReviews.length > 0) {
+        parts.push("## Approved Reviews");
+        parts.push("");
+        for (const r of report.approvedReviews) {
+            parts.push(`- reviewId=${r.id} (@${r.author}): ${firstLine(r.body)}`);
+        }
+        parts.push("");
     }
     // Summary
     const totalActionable = actionableThreads.length + actionableComments.length + report.changesRequestedReviews.length;
-    lines.push(`Summary: ${totalActionable === 0 ? "0 actionable — all threads resolved/minimized" : `${totalActionable} actionable item(s) remaining`}`);
-    return lines.join("\n");
+    parts.push("## Summary");
+    parts.push("");
+    parts.push(totalActionable === 0
+        ? "0 actionable — all threads resolved/minimized"
+        : `${totalActionable} actionable item(s) remaining`);
+    parts.push("");
+    // Instructions
+    parts.push("## Instructions");
+    parts.push("");
+    const instructions = buildCheckInstructions(report);
+    instructions.forEach((step, i) => {
+        parts.push(`${i + 1}. ${step}`);
+    });
+    return parts.join("\n");
 }
 // ---------------------------------------------------------------------------
 // Helpers
@@ -103,9 +156,3 @@ export function formatText(report) {
 function firstLine(text) {
     return (text.split("\n")[0] ?? "").trim().slice(0, 120);
 }
-function indent(text, prefix) {
-    return text
-        .split("\n")
-        .map((l) => prefix + l)
-        .join("\n");
-}

package/bin/{cache → state}/fix-attempts.mjs

@@ -5,7 +5,7 @@
  * handler without being resolved. Counts are reset automatically when the HEAD
  * commit SHA changes (i.e. a new push landed).
  *
- * State lives in `$TMPDIR/pr-shepherd-cache/<owner>-<repo>/<pr>/fix-attempts.json`.
+ * State lives in `$TMPDIR/pr-shepherd-state/<owner>-<repo>/<pr>/fix-attempts.json`.
  */
 import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
 import { randomUUID } from "node:crypto";
@@ -59,9 +59,9 @@ function resolvePath(key) {
         ["repo", key.repo],
     ]) {
         if (!SAFE_SEGMENT.test(value)) {
-            throw new Error(`Invalid cache key segment "${field}": ${value}`);
+            throw new Error(`Invalid state key segment "${field}": ${value}`);
         }
     }
-    const base = process.env["PR_SHEPHERD_CACHE_DIR"] ?? join(tmpdir(), "pr-shepherd-cache");
+    const base = process.env["PR_SHEPHERD_STATE_DIR"] ?? join(tmpdir(), "pr-shepherd-state");
     return join(base, `${key.owner}-${key.repo}`, String(key.pr), "fix-attempts.json");
 }

package/bin/state/iterate-stall.mjs

@@ -0,0 +1,74 @@
+/**
+ * Persistent stall-detection state for the iterate loop.
+ *
+ * Tracks the fingerprint of the last iterate result and when that fingerprint
+ * was first seen. If the fingerprint does not change for stallTimeoutSeconds
+ * the iterate command escalates instead of repeating the same action.
+ *
+ * State lives in `$TMPDIR/pr-shepherd-state/<owner>-<repo>/<pr>/iterate-stall.json`.
+ */
+import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { join, dirname } from "node:path";
+import { tmpdir } from "node:os";
+import { SAFE_SEGMENT } from "../util/path-segment.mjs";
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/** Read the current stall state. Returns null on miss, corrupt data, or invalid shape. */
+export async function readStallState(key) {
+    try {
+        const raw = await readFile(resolvePath(key), "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed === null ||
+            typeof parsed !== "object" ||
+            typeof parsed["fingerprint"] !== "string" ||
+            !Number.isFinite(parsed["firstSeenAt"])) {
+            return null;
+        }
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+/** Write stall state (fire-and-forget — never throws). */
+export async function writeStallState(key, state) {
+    let tmp;
+    try {
+        const path = resolvePath(key);
+        tmp = `${path}.${randomUUID()}.tmp`;
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(tmp, JSON.stringify(state), "utf8");
+        await rename(tmp, path);
+        tmp = undefined;
+    }
+    catch {
+        // Best-effort.
+    }
+    finally {
+        if (tmp !== undefined) {
+            try {
+                await unlink(tmp);
+            }
+            catch {
+                // Best-effort cleanup.
+            }
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function resolvePath(key) {
+    for (const [field, value] of [
+        ["owner", key.owner],
+        ["repo", key.repo],
+    ]) {
+        if (!SAFE_SEGMENT.test(value)) {
+            throw new Error(`Invalid state key segment "${field}": ${value}`);
+        }
+    }
+    const base = process.env["PR_SHEPHERD_STATE_DIR"] ?? join(tmpdir(), "pr-shepherd-state");
+    return join(base, `${key.owner}-${key.repo}`, String(key.pr), "iterate-stall.json");
+}

package/bin/suggestions/parse.mjs

@@ -0,0 +1,119 @@
+/**
+ * Parse GitHub review-comment "suggestion" blocks.
+ *
+ * GitHub's "Commit suggestion" UI button treats the first ```suggestion fenced
+ * block in a review comment as a replacement for the commented line range.
+ * This module extracts that block from the comment body, plus applies a
+ * parsed suggestion to a file's contents.
+ *
+ * There is no GitHub API for applying suggestions — tools that reproduce the
+ * button (this one included) must parse + commit themselves.
+ */
+/**
+ * Return the first ```suggestion block from a review-comment body, or null if none.
+ *
+ * Handles three distinct cases:
+ *   - Empty block (` ```suggestion\n``` `) → `lines: []` (deletion).
+ *   - Blank-line-only body (` ```suggestion\n\n``` `) → `lines: [""]`.
+ *   - Non-empty body → split into lines.
+ *
+ * The opening fence may be 3+ backticks; the closing fence must be at least
+ * as many backticks, at the start of a line (after the captured prefix). This
+ * means content lines that contain ` ``` ` in the middle (not at line-start)
+ * are treated as content rather than a closing fence — fixing the silent
+ * truncation in the original regex approach (issue #68).
+ *
+ * When the block is embedded in a quoted reply (e.g. `> ```suggestion …`),
+ * the leading prefix captured from the opening fence is stripped from each
+ * body line — but only when that exact prefix is present, so legitimate `>`
+ * characters inside the suggested code survive.
+ */
+export function parseSuggestion(body) {
+    const lines = body.split("\n");
+    // Find the opening fence: optional prefix + N backticks (N≥3) + "suggestion" + anything.
+    let openIdx = -1;
+    let prefix = "";
+    let fenceLen = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const m = /^([ \t>]*?)(`{3,})suggestion[^\n]*$/.exec(lines[i]);
+        if (m) {
+            openIdx = i;
+            prefix = m[1];
+            fenceLen = m[2].length;
+            break;
+        }
+    }
+    if (openIdx === -1)
+        return null;
+    // Find the closing fence: same prefix + N+ backticks at the start of a line.
+    const escapedPrefix = prefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const closeRegex = new RegExp(`^${escapedPrefix}\`{${fenceLen},}[ \\t]*$`);
+    let closeIdx = -1;
+    for (let i = openIdx + 1; i < lines.length; i++) {
+        if (closeRegex.test(lines[i])) {
+            closeIdx = i;
+            break;
+        }
+    }
+    let bodyLines;
+    if (closeIdx !== -1) {
+        bodyLines = lines.slice(openIdx + 1, closeIdx);
+    }
+    else if (prefix === "" && lines.length > openIdx + 1) {
+        // Inline-close fallback: last line ends with N+ backticks (no trailing newline).
+        // Preserves the historical behaviour for bodies like "```suggestion\nfoo```".
+        // Only supported for non-quoted (prefix="") blocks.
+        const last = lines[lines.length - 1];
+        const m = new RegExp(`^(.*?)\`{${fenceLen},}$`).exec(last);
+        if (!m)
+            return null;
+        bodyLines = [...lines.slice(openIdx + 1, lines.length - 1), m[1]];
+    }
+    else {
+        return null;
+    }
+    if (bodyLines.length === 0)
+        return { lines: [] };
+    const cleaned = prefix === ""
+        ? bodyLines
+        : bodyLines.map((l) => (l.startsWith(prefix) ? l.slice(prefix.length) : l));
+    return { lines: cleaned };
+}
+/**
+ * True when a parsed suggestion's replacement is safe to commit: the joined
+ * replacement contains no nested ` ```suggestion ` marker and no unmatched
+ * ` ``` ` run (odd count). Both shapes previously masked silent truncation
+ * (issue #68). Conservative by design: reviewers whose suggestion content
+ * legitimately includes these markers must apply the change manually.
+ */
+export function isCommittableSuggestion(parsed) {
+    const replacement = parsed.lines.join("\n");
+    if (replacement.includes("```suggestion"))
+        return false;
+    const fenceRuns = (replacement.match(/`{3,}/g) ?? []).length;
+    return fenceRuns % 2 === 0;
+}
+/**
+ * Apply a suggestion to a file's full contents by replacing lines
+ * [startLine..endLine] (1-indexed, inclusive) with the given replacement lines.
+ *
+ * Pass `[]` to delete the range, `[""]` to replace with a single blank line,
+ * or `["a", "b", ...]` for arbitrary replacements. The file's trailing-newline
+ * state is preserved exactly.
+ */
+export function applySuggestionToFile(fileContent, startLine, endLine, replacementLines) {
+    if (startLine < 1 || endLine < startLine) {
+        throw new Error(`Invalid line range: start=${startLine}, end=${endLine}`);
+    }
+    const endsWithNewline = fileContent.endsWith("\n");
+    // Strip a single trailing \n so split/join round-trips exactly.
+    const body = endsWithNewline ? fileContent.slice(0, -1) : fileContent;
+    const lines = body.split("\n");
+    if (endLine > lines.length) {
+        throw new Error(`Line ${endLine} is out of range (file has ${lines.length} line(s))`);
+    }
+    const before = lines.slice(0, startLine - 1);
+    const after = lines.slice(endLine);
+    const result = [...before, ...replacementLines, ...after].join("\n");
+    return endsWithNewline ? `${result}\n` : result;
+}

package/bin/suggestions/patch.mjs

@@ -0,0 +1,52 @@
+/**
+ * Build a git-apply-compatible unified diff for a single suggestion hunk.
+ *
+ * The diff uses `--- a/<path>` / `+++ b/<path>` headers so `git apply` and
+ * `git apply --check` accept it without a `diff --git` preamble.
+ */
+export function buildUnifiedDiff({ path, originalContent, startLine, endLine, replacementLines, context = 3, }) {
+    const endsWithNewline = originalContent.endsWith("\n");
+    const body = endsWithNewline ? originalContent.slice(0, -1) : originalContent;
+    const fileLines = body === "" ? [] : body.split("\n");
+    const removedLines = fileLines.slice(startLine - 1, endLine);
+    const beforeStart = Math.max(0, startLine - 1 - context);
+    const beforeLines = fileLines.slice(beforeStart, startLine - 1);
+    const afterEnd = Math.min(fileLines.length, endLine + context);
+    const afterLines = fileLines.slice(endLine, afterEnd);
+    const hunkOrigStart = beforeStart + 1;
+    const hunkOrigCount = beforeLines.length + removedLines.length + afterLines.length;
+    const hunkNewCount = beforeLines.length + replacementLines.length + afterLines.length;
+    const noNewline = "\\n";
+    const isLastOrigLine = (lineIdx) => !endsWithNewline && lineIdx === fileLines.length - 1;
+    const out = [
+        `--- a/${path}\n`,
+        `+++ b/${path}\n`,
+        `@@ -${hunkOrigStart},${hunkOrigCount} +${hunkOrigStart},${hunkNewCount} @@\n`,
+    ];
+    for (let i = 0; i < beforeLines.length; i++) {
+        out.push(` ${beforeLines[i]}\n`);
+        if (isLastOrigLine(beforeStart + i))
+            out.push(noNewline);
+    }
+    for (let i = 0; i < removedLines.length; i++) {
+        out.push(`-${removedLines[i]}\n`);
+        if (isLastOrigLine(startLine - 1 + i))
+            out.push(noNewline);
+    }
+    // Replacement ends the file only when the removed range reaches the very last line —
+    // not just because context is 0 (there may still be unshown lines beyond the hunk).
+    const addedEndsFile = !endsWithNewline && endLine >= fileLines.length;
+    const hasCr = originalContent.includes("\r\n");
+    for (let i = 0; i < replacementLines.length; i++) {
+        const line = hasCr ? replacementLines[i] + "\r" : replacementLines[i];
+        out.push(`+${line}\n`);
+        if (addedEndsFile && i === replacementLines.length - 1)
+            out.push(noNewline);
+    }
+    for (let i = 0; i < afterLines.length; i++) {
+        out.push(` ${afterLines[i]}\n`);
+        if (isLastOrigLine(endLine + i))
+            out.push(noNewline);
+    }
+    return out.join("");
+}

package/bin/types/github.mjs

@@ -0,0 +1,2 @@
+// GitHub primitives, check runs, review threads, and batch PR data types.
+export {};

package/bin/types/iterate.mjs

@@ -0,0 +1,2 @@
+// Iterate command types.
+export {};

package/bin/types/report.mjs

@@ -0,0 +1,2 @@
+// Shepherd-specific report types, agent projections, and CLI options.
+export {};

package/bin/types.mjs

@@ -1,2 +1,4 @@
 /** Shared type definitions for the shepherd CLI. */
-export {};
+export * from "./types/github.mjs";
+export * from "./types/report.mjs";
+export * from "./types/iterate.mjs";

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "pr-shepherd",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
   "license": "MIT",
   "author": "Jonathan Ong",
   "type": "module",
   "bin": {
-    "pr-shepherd": "bin/index.mjs"
+    "pr-shepherd": "bin/pr-shepherd"
   },
   "files": [
     "bin/**",
@@ -32,7 +32,7 @@
   },
   "scripts": {
     "build": "node scripts/build.mjs",
-    "prepare": "npm run build",
+    "prepare": "node scripts/install-hooks.mjs && node scripts/install-plugin-symlink.mjs && npm run build",
     "prepublishOnly": "npm run typecheck && npm test && npm run build",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint src/ plugin/skills/",

package/plugin/skills/check/SKILL.md

@@ -10,59 +10,26 @@ allowed-tools: ["Bash"]
 
 ## Arguments: $ARGUMENTS
 
-## Resolve PR number(s)
+## Steps
 
-1. If `$ARGUMENTS` contains PR numbers or GitHub PR URLs, extract the number(s).
-2. Otherwise, infer: `gh pr list --head "$(git rev-parse --abbrev-ref HEAD)" --json number --jq '.[0].number'`
-3. If no PR found, report an error and stop.
+1. **Parse `$ARGUMENTS`:** extract PR numbers or GitHub PR URLs. If none, infer:
+   `gh pr list --head "$(git rev-parse --abbrev-ref HEAD)" --json number --jq '.[0].number'`
+   If no PR found, report an error and stop.
 
-For each resolved PR number, check if it is already merged:
+2. **Short-circuit if merged:**
 
-```bash
-gh pr view <N> --json state --jq '.state'
-```
+   ```bash
+   gh pr view <N> --json state --jq '.state'
+   ```
 
-If `MERGED`, output: `PR #N is already merged. Nothing to check.` and skip.
+   If `MERGED`, output: `PR #N is already merged. Nothing to check.` and skip.
 
-## Run the check
+3. **Run the check and follow instructions:**
 
-```bash
-npx pr-shepherd check <N> --format=json
-```
+   ```bash
+   npx pr-shepherd check <N>
+   ```
 
-## Reporting
+   Print the full output. Follow the `## Instructions` section exactly.
 
-Parse the JSON output and report all three:
-
-- **Merge status** (`report.mergeStatus.status`): CLEAN | BEHIND | CONFLICTS | BLOCKED | UNSTABLE | DRAFT | UNKNOWN — never omit; include `copilotReviewInProgress` when true
-- **CI check results** (`report.checks`): passing count, failing names + kinds, in-progress names
-- **Unresolved review comments** (`report.threads.actionable` + `report.comments.actionable`): count + details with file paths and line numbers
-
-## Rebase policy
-
-The CLI already determines whether a rebase is warranted. Read `report.mergeStatus.status` directly:
-
-- `CONFLICTS` — a rebase is required to resolve the merge conflict before the PR can land.
-- `BEHIND` — a rebase may be appropriate; a `flaky` failure while `BEHIND` is the canonical rebase signal. If all checks pass but the PR is `BEHIND`, a rebase is optional.
-- Any other status — no rebase needed.
-
-Do not re-derive these conditions from raw branch state. For automated monitoring that acts on these signals, use `/pr-shepherd:monitor` — it handles rebase decisions end-to-end.
-
-## CI budget policy
-
-Each entry in `report.checks` carries a `failureKind` field. Read it directly rather than re-classifying failures:
-
-- `actionable` — the failure is code-level and needs a fix.
-- `infrastructure` — transient infra problem; re-run with `gh run rerun <runId> --failed`.
-- `timeout` — job exceeded the time limit; re-run with `gh run rerun <runId> --failed`.
-- `flaky` — known-flaky test; do NOT cancel. Rebase first if `mergeStatus.status` is `BEHIND`.
-
-## Never declare ready to merge
-
-Unless ALL of:
-
-1. `report.mergeStatus.mergeStateStatus == 'CLEAN'`
-2. `report.status == 'READY'`
-3. `report.mergeStatus.copilotReviewInProgress == false`
-
-This is a one-shot check. For continuous monitoring, use `/pr-shepherd:monitor`.
+4. For multiple PRs, repeat steps 2–3 for each.