pr-shepherd 0.7.1 → 0.8.0

package/bin/github/batch.mjs

@@ -1,18 +1,11 @@
-/**
- * Executes the primary batch GraphQL query and parses the raw GitHub response
- * into shepherd's typed `BatchPrData` shape.
- *
- * The batch query fetches CI checks + review threads + PR comments + merge
- * status in a single network round-trip, drastically reducing API call counts
- * compared to the previous per-agent approach.
- */
 import { graphql, graphqlWithRateLimit } from "./client.mjs";
 import { paginateForward, paginateBackward } from "./pagination.mjs";
 import { BATCH_PR_QUERY } from "./queries.mjs";
+import { parseRawPr } from "./batch-parsers.mjs";
 /**
  * Fetch all PR data needed for a `shepherd check` in one (or a few, if paginating) GraphQL requests.
  */
-export async function fetchPrBatch(pr, repo) {
+export async function fetchPrBatch(pr, repo, opts = {}) {
     // First page: no cursor variables.
     const result = await graphqlWithRateLimit(BATCH_PR_QUERY, {
         owner: repo.owner,
@@ -95,12 +88,34 @@ export async function fetchPrBatch(pr, repo) {
         }, raw.reviewSummaries.pageInfo.startCursor);
         rawReviewSummaryNodes = [...extra, ...rawReviewSummaryNodes];
     }
+    // Paginate APPROVED reviews backward if the first page is incomplete — gated behind
+    // `paginateApprovedReviews` because approvals minimization is opt-in. See FetchPrBatchOptions.
+    let rawApprovedReviewNodes = raw.approvedReviews.nodes;
+    if (opts.paginateApprovedReviews &&
+        raw.approvedReviews.pageInfo.hasPreviousPage &&
+        raw.approvedReviews.pageInfo.startCursor) {
+        const extra = await paginateBackward(async (cursor) => {
+            const res = await graphql(BATCH_PR_QUERY, {
+                owner: repo.owner,
+                repo: repo.name,
+                pr,
+                ...(cursor ? { approvedReviewsCursor: cursor } : {}),
+            });
+            const pr2 = res.data.repository.pullRequest;
+            if (!pr2)
+                throw new Error(`PR #${pr} not found`);
+            return pr2.approvedReviews;
+        }, raw.approvedReviews.pageInfo.startCursor);
+        rawApprovedReviewNodes = [...extra, ...rawApprovedReviewNodes];
+    }
     // Paginate check contexts forward if the first page is incomplete.
     let rawCheckNodes = raw.commits.nodes[0]?.commit.statusCheckRollup?.contexts.nodes ?? [];
     const checksPageInfo = raw.commits.nodes[0]?.commit.statusCheckRollup?.contexts.pageInfo;
+    const firstOid = raw.commits.nodes[0]?.commit.oid;
     if (checksPageInfo?.hasNextPage && checksPageInfo.endCursor) {
         // Pass endCursor so paginateForward fetches pages *after* the already-
         // fetched first page instead of re-fetching it from the start.
+        let pageCount = 0;
         const extra = await paginateForward(async (cursor) => {
             const res = await graphql(BATCH_PR_QUERY, {
                 owner: repo.owner,
@@ -109,129 +124,19 @@ export async function fetchPrBatch(pr, repo) {
                 ...(cursor ? { checksCursor: cursor } : {}),
             });
             const pr2 = res.data.repository.pullRequest;
-            const ctxs = pr2?.commits.nodes[0]?.commit.statusCheckRollup?.contexts;
+            if (!pr2?.commits.nodes[0]?.commit.statusCheckRollup) {
+                throw new Error(`Check-context pagination interrupted: statusCheckRollup disappeared on page ${pageCount + 2} (possible force-push race). Retry after the push stabilizes.`);
+            }
+            const currentOid = pr2.commits.nodes[0]?.commit.oid;
+            if (firstOid !== undefined && currentOid !== undefined && currentOid !== firstOid) {
+                throw new Error(`Check-context pagination interrupted: head commit changed from ${firstOid} to ${currentOid} between pages (force-push race). Retry.`);
+            }
+            pageCount++;
+            const ctxs = pr2.commits.nodes[0]?.commit.statusCheckRollup?.contexts;
             return ctxs ?? { pageInfo: { hasNextPage: false, endCursor: null }, nodes: [] };
         }, checksPageInfo.endCursor);
         rawCheckNodes = [...rawCheckNodes, ...extra];
     }
-    const data = parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes, rawReviewSummaryNodes, rawCheckNodes);
+    const data = parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes, rawReviewSummaryNodes, rawApprovedReviewNodes, rawCheckNodes);
     return { data, rateLimit: result.rateLimit };
 }
-// ---------------------------------------------------------------------------
-// Parsers
-// ---------------------------------------------------------------------------
-function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes, rawReviewSummaryNodes, rawCheckNodes) {
-    const reviewRequests = (raw.reviewRequests?.nodes ?? []).flatMap((n) => {
-        const login = n.requestedReviewer?.login ?? n.requestedReviewer?.name;
-        return login ? [{ login }] : [];
-    });
-    const latestReviews = (raw.latestReviews?.nodes ?? []).map((n) => ({
-        login: n.author?.login ?? "unknown",
-        state: n.state,
-    }));
-    const reviewThreads = rawThreadPages.map((t) => {
-        const comment = t.comments.nodes[0];
-        return {
-            id: t.id,
-            isResolved: t.isResolved,
-            isOutdated: t.isOutdated,
-            isMinimized: comment?.isMinimized ?? false,
-            path: comment?.path ?? null,
-            line: comment?.line ?? null,
-            author: comment?.author?.login ?? "unknown",
-            body: comment?.body ?? "",
-            createdAtUnix: comment ? parseCreatedAt(comment.createdAt) : 0,
-        };
-    });
-    const comments = rawCommentNodes.map((c) => ({
-        id: c.id,
-        isMinimized: c.isMinimized,
-        author: c.author?.login ?? "unknown",
-        body: c.body,
-        createdAtUnix: parseCreatedAt(c.createdAt),
-    }));
-    const changesRequestedReviews = rawReviewNodes.map((r) => ({
-        id: r.id,
-        author: r.author?.login ?? "unknown",
-        body: r.body,
-    }));
-    const reviewSummaries = rawReviewSummaryNodes
-        .filter((r) => !r.isMinimized && r.body.trim() !== "")
-        .map((r) => ({
-        id: r.id,
-        author: r.author?.login ?? "unknown",
-        body: r.body,
-    }));
-    const checks = rawCheckNodes.flatMap((node) => {
-        if (node.__typename === "CheckRun") {
-            const event = node.checkSuite?.workflowRun?.event ?? null;
-            const runId = extractRunId(node.detailsUrl);
-            return [
-                {
-                    name: node.name,
-                    status: node.status,
-                    conclusion: node.conclusion,
-                    detailsUrl: node.detailsUrl ?? "",
-                    event,
-                    runId,
-                },
-            ];
-        }
-        if (node.__typename === "StatusContext") {
-            const { status, conclusion } = mapStatusContextState(node.state);
-            return [
-                {
-                    name: node.context,
-                    status,
-                    conclusion,
-                    detailsUrl: node.targetUrl ?? "",
-                    event: null,
-                    runId: null,
-                },
-            ];
-        }
-        return [];
-    });
-    return {
-        nodeId: raw.id,
-        number: raw.number,
-        state: raw.state,
-        isDraft: raw.isDraft,
-        mergeable: raw.mergeable,
-        mergeStateStatus: raw.mergeStateStatus,
-        reviewDecision: (raw.reviewDecision ?? null),
-        headRefOid: raw.headRefOid,
-        baseRefName: raw.baseRefName,
-        reviewRequests,
-        latestReviews,
-        reviewThreads,
-        comments,
-        changesRequestedReviews,
-        reviewSummaries,
-        checks,
-    };
-}
-function parseCreatedAt(iso) {
-    const ms = new Date(iso).getTime();
-    return Number.isFinite(ms) ? Math.floor(ms / 1000) : 0;
-}
-function extractRunId(url) {
-    if (!url)
-        return null;
-    const m = /\/runs\/(\d+)/.exec(url);
-    return m ? (m[1] ?? null) : null;
-}
-/** Maps a GitHub commit status `state` to CheckRun-compatible status + conclusion. */
-function mapStatusContextState(state) {
-    switch (state) {
-        case "SUCCESS":
-            return { status: "COMPLETED", conclusion: "SUCCESS" };
-        case "FAILURE":
-        case "ERROR":
-            return { status: "COMPLETED", conclusion: "FAILURE" };
-        case "PENDING":
-        case "EXPECTED":
-        default:
-            return { status: "IN_PROGRESS", conclusion: null };
-    }
-}

package/bin/github/client.mjs

@@ -45,6 +45,36 @@ export async function getPrHeadSha(pr, owner, name) {
     const data = await rest("GET", `/repos/${owner}/${name}/pulls/${pr}`);
     return data.head.sha;
 }
+/**
+ * Full head info for a PR — sha, branch name, and the head repository's full name.
+ * Needed by commit-suggestions to target the correct branch via `createCommitOnBranch`.
+ */
+export async function getPrHead(pr, owner, name) {
+    const data = await rest("GET", `/repos/${owner}/${name}/pulls/${pr}`);
+    if (!data.head.repo) {
+        throw new Error(`PR #${pr} head repository is unavailable (fork may have been deleted).`);
+    }
+    return {
+        sha: data.head.sha,
+        ref: data.head.ref,
+        repoWithOwner: data.head.repo.full_name,
+    };
+}
+/**
+ * Fetch a file's raw text content at a given ref. Uses the REST contents endpoint,
+ * which returns base64 for files under 1MB. Throws for binary / oversize files.
+ */
+export async function getFileContents(repoWithOwner, path, ref) {
+    const data = await rest("GET", `/repos/${repoWithOwner}/contents/${encodePathForApi(path)}?ref=${encodeURIComponent(ref)}`);
+    if (!data.content || data.encoding !== "base64") {
+        throw new Error(`File ${path} could not be read as text (encoding=${data.encoding ?? "n/a"}).`);
+    }
+    return Buffer.from(data.content, "base64").toString("utf8");
+}
+// Encode every path segment but preserve the slashes between them.
+function encodePathForApi(path) {
+    return path.split("/").map(encodeURIComponent).join("/");
+}
 /**
  * Fetches `mergeable` and `mergeStateStatus` via the REST API.
  *
@@ -60,22 +90,30 @@ export async function getMergeableState(pr, owner, repo) {
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
-async function getCurrentBranch() {
+export async function getCurrentBranch() {
     const { stdout } = await execFile("git", ["rev-parse", "--abbrev-ref", "HEAD"]);
     return stdout.trim();
 }
 function parseRemoteUrl(url) {
-    // Strip trailing .git and trailing slash
-    const stripped = url.replace(/\.git$/, "").replace(/\/$/, "");
-    // ssh: git@host:owner/repo
-    const sshMatch = /^git@[^:]+:([^/]+)\/(.+)$/.exec(stripped);
+    const trimmed = url.trim();
+    // ssh: git@host:owner/repo[.git]
+    const sshMatch = /^git@[^:]+:([^/]+)\/([^/]+?)(?:\.git)?$/.exec(trimmed);
     if (sshMatch) {
         return { owner: sshMatch[1], name: sshMatch[2] };
     }
-    // https or ssh://: https://host/owner/repo  or  ssh://git@host/owner/repo
-    const httpsMatch = /^(?:https?|ssh):\/\/[^/]+\/([^/]+)\/(.+)$/.exec(stripped);
-    if (httpsMatch) {
-        return { owner: httpsMatch[1], name: httpsMatch[2] };
+    // https or ssh://: parse via URL and require exactly /<owner>/<repo>[.git]
+    if (/^(?:https?|ssh):\/\//.test(trimmed)) {
+        try {
+            const parsed = new URL(trimmed);
+            const pathname = parsed.pathname.replace(/\.git\/?$/, "").replace(/\/$/, "");
+            const parts = pathname.split("/").filter(Boolean);
+            if (parts.length === 2) {
+                return { owner: parts[0], name: parts[1] };
+            }
+        }
+        catch {
+            // fall through to error
+        }
     }
     throw new Error(`Cannot parse GitHub remote URL: ${url}`);
 }

package/bin/github/gql/batch-pr.gql

@@ -7,6 +7,7 @@ query BatchPr(
   $commentsCursor: String
   $changesRequestedCursor: String
   $reviewSummariesCursor: String
+  $approvedReviewsCursor: String
 ) {
   repository(owner: $owner, name: $repo) {
     pullRequest(number: $pr) {
@@ -63,6 +64,7 @@ query BatchPr(
               body
               path
               line
+              startLine
               createdAt
             }
           }
@@ -114,9 +116,24 @@ query BatchPr(
           body
         }
       }
+      approvedReviews: reviews(states: APPROVED, last: 50, before: $approvedReviewsCursor) {
+        pageInfo {
+          hasPreviousPage
+          startCursor
+        }
+        nodes {
+          id
+          isMinimized
+          author {
+            login
+          }
+          body
+        }
+      }
       commits(last: 1) {
         nodes {
           commit {
+            oid
             statusCheckRollup {
               contexts(first: 100, after: $checksCursor) {
                 pageInfo {
@@ -130,6 +147,8 @@ query BatchPr(
                     status
                     conclusion
                     detailsUrl
+                    title
+                    summary
                     checkSuite {
                       workflowRun {
                         event
@@ -140,6 +159,7 @@ query BatchPr(
                     context
                     state
                     targetUrl
+                    description
                   }
                 }
               }

package/bin/github/http.mjs

@@ -1,12 +1,3 @@
-/**
- * Thin native-fetch HTTP client for the GitHub API.
- * Replaces the previous `gh` CLI shell-out on every code path.
- *
- * Token resolution order:
- *   1. GH_TOKEN env
- *   2. GITHUB_TOKEN env
- *   3. `gh auth token` (fallback for users who have run `gh auth login`)
- */
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 const execFile = promisify(execFileCb);
@@ -21,12 +12,9 @@ export function _resetTokenCache() {
 async function resolveToken() {
     if (_token)
         return _token;
-    if (process.env["GH_TOKEN"]) {
-        _token = process.env["GH_TOKEN"];
-        return _token;
-    }
-    if (process.env["GITHUB_TOKEN"]) {
-        _token = process.env["GITHUB_TOKEN"];
+    const envToken = process.env["GH_TOKEN"] ?? process.env["GITHUB_TOKEN"];
+    if (envToken) {
+        _token = envToken;
         return _token;
     }
     try {
@@ -51,24 +39,43 @@ async function makeHeaders() {
         "Content-Type": "application/json",
     };
 }
+function sanitizeBody(body) {
+    return body.replace(/Bearer\s+\S+/gi, "[REDACTED]").slice(0, 200);
+}
+async function requestWithTokenRetry(fn) {
+    const res = await fn();
+    if (res.status === 401 && _token !== undefined) {
+        try {
+            await res.arrayBuffer();
+        }
+        catch { }
+        _token = undefined;
+        return fn();
+    }
+    return res;
+}
 // ---------------------------------------------------------------------------
 // GraphQL
 // ---------------------------------------------------------------------------
 async function graphqlInner(query, vars) {
-    const res = await fetch(`${BASE_URL}/graphql`, {
+    const res = await requestWithTokenRetry(async () => fetch(`${BASE_URL}/graphql`, {
         method: "POST",
         headers: await makeHeaders(),
         body: JSON.stringify({ query, variables: vars }),
-    });
+    }));
     const rateLimit = parseRateLimit(res.headers);
     if (!res.ok) {
         const body = await res.text();
-        throw new Error(`GitHub GraphQL request failed: ${res.status} ${body.slice(0, 300)}`);
+        throw new Error(`GitHub GraphQL request failed: ${res.status} ${sanitizeBody(body)}`);
     }
     const parsed = (await res.json());
+    if (parsed.data == null) {
+        const messages = (parsed.errors ?? []).map((e) => e.message).join("; ");
+        throw new Error(`GitHub GraphQL error (no data): ${messages}`);
+    }
     if (parsed.errors?.length) {
         const messages = parsed.errors.map((e) => e.message).join("; ");
-        throw new Error(`GitHub GraphQL error: ${messages}`);
+        process.stderr.write(`pr-shepherd: GraphQL non-fatal errors: ${messages}\n`);
     }
     return { data: parsed.data, rateLimit };
 }
@@ -84,14 +91,14 @@ export async function graphqlWithRateLimit(query, vars = {}) {
 // REST
 // ---------------------------------------------------------------------------
 export async function rest(method, path, body) {
-    const res = await fetch(`${BASE_URL}${path}`, {
+    const res = await requestWithTokenRetry(async () => fetch(`${BASE_URL}${path}`, {
         method,
         headers: await makeHeaders(),
         body: body !== undefined ? JSON.stringify(body) : undefined,
-    });
+    }));
     if (!res.ok) {
         const text = await res.text();
-        throw new Error(`GitHub REST ${method} ${path} failed: ${res.status} ${text.slice(0, 300)}`);
+        throw new Error(`GitHub REST ${method} ${path} failed: ${res.status} ${sanitizeBody(text)}`);
     }
     const ct = res.headers.get("content-type") ?? "";
     if (ct.includes("application/json")) {
@@ -99,17 +106,12 @@ export async function rest(method, path, body) {
     }
     return undefined;
 }
-/**
- * GET request that returns plain text.
- * Handles the 302 redirect pattern used by the GitHub Actions job-logs endpoint —
- * the redirect target (a signed storage URL) is fetched without auth headers.
- */
 export async function restText(path) {
-    const res = await fetch(`${BASE_URL}${path}`, {
+    const res = await requestWithTokenRetry(async () => fetch(`${BASE_URL}${path}`, {
         method: "GET",
         headers: await makeHeaders(),
         redirect: "manual",
-    });
+    }));
     if (res.status === 301 || res.status === 302 || res.status === 307 || res.status === 308) {
         const location = res.headers.get("location");
         if (location) {
@@ -122,7 +124,7 @@ export async function restText(path) {
     }
     if (!res.ok) {
         const text = await res.text();
-        throw new Error(`GitHub REST GET ${path} failed: ${res.status} ${text.slice(0, 300)}`);
+        throw new Error(`GitHub REST GET ${path} failed: ${res.status} ${sanitizeBody(text)}`);
     }
     return res.text();
 }

package/bin/index.mjs

@@ -8,8 +8,21 @@
  *   pr-shepherd iterate [PR]
  *   pr-shepherd status PR1 [PR2 …]
  */
-import { main } from "./cli.mjs";
+import { main } from "./cli-parser.mjs";
+function formatCause(cause, seen = new Set(), depth = 0) {
+    if (depth > 5 || seen.has(cause))
+        return "[circular or deep cause chain]";
+    seen.add(cause);
+    if (cause instanceof Error) {
+        const stack = cause.stack ?? `${cause.message}`;
+        const nested = cause.cause != null ? `\n  caused by: ${formatCause(cause.cause, seen, depth + 1)}` : "";
+        return `${stack}${nested}`;
+    }
+    return String(cause);
+}
 main(process.argv).catch((err) => {
-    process.stderr.write(`pr-shepherd error: ${err instanceof Error ? err.message : String(err)}\n`);
+    const msg = err instanceof Error ? err.message : String(err);
+    const causeStr = err instanceof Error && err.cause != null ? formatCause(err.cause) : null;
+    process.stderr.write(`pr-shepherd error: ${msg}${causeStr !== null ? ` (cause: ${causeStr})` : ""}\n`);
     process.exit(1);
 });

package/bin/merge-status/derive.mjs

@@ -5,13 +5,13 @@
  * for non-OPEN (merged/closed) PRs — this function does not branch on it.
  *
  * Interpretation order for `status` — first match wins:
- *   1. mergeable == CONFLICTING       → CONFLICTS
- *   2. mergeStateStatus DIRTY         → CONFLICTS (GitHub merge conflicts)
- *   3. copilotReviewInProgress        → BLOCKED
- *   4. mergeStateStatus BEHIND        → BEHIND
- *   5. mergeStateStatus BLOCKED / HAS_HOOKS → BLOCKED
- *   6. mergeStateStatus UNSTABLE      → UNSTABLE
- *   7. isDraft                        → DRAFT
+ *   1. mergeable == CONFLICTING       → CONFLICTS (hard conflict even for drafts)
+ *   2. copilotReviewInProgress        → BLOCKED
+ *   3. mergeStateStatus DIRTY         → CONFLICTS (GitHub merge conflicts, even for drafts)
+ *   4. isDraft                        → DRAFT
+ *   5. mergeStateStatus BEHIND        → BEHIND
+ *   6. mergeStateStatus BLOCKED / HAS_HOOKS → BLOCKED
+ *   7. mergeStateStatus UNSTABLE      → UNSTABLE
  *   8. mergeStateStatus UNKNOWN       → UNKNOWN
  *   9. mergeStateStatus CLEAN         → CLEAN
  */
@@ -26,9 +26,12 @@ export function deriveMergeStatus(pr) {
         status = "BLOCKED";
     }
     else if (pr.mergeStateStatus === "DIRTY") {
-        // DIRTY means GitHub detected merge conflicts in the branch.
+        // DIRTY means GitHub detected merge conflicts — surface as CONFLICTS even for drafts.
         status = "CONFLICTS";
     }
+    else if (pr.isDraft || pr.mergeStateStatus === "DRAFT") {
+        status = "DRAFT";
+    }
     else if (pr.mergeStateStatus === "BEHIND") {
         status = "BEHIND";
     }
@@ -38,9 +41,6 @@ export function deriveMergeStatus(pr) {
     else if (pr.mergeStateStatus === "UNSTABLE") {
         status = "UNSTABLE";
     }
-    else if (pr.isDraft || pr.mergeStateStatus === "DRAFT") {
-        status = "DRAFT";
-    }
     else if (pr.mergeStateStatus === "UNKNOWN") {
         status = "UNKNOWN";
     }

package/bin/reporters/agent.mjs

@@ -2,9 +2,10 @@
  * Projections for the agent-facing iterate output.
  *
  * These strip fields that are always-false by the time items reach iterate
- * (isResolved, isOutdated, isMinimized, createdAtUnix) and metadata that the
- * monitor prompt never reads (detailsUrl, event, status, conclusion, category,
- * logExcerpt). The original domain types are preserved for check command output.
+ * (isResolved, isOutdated, isMinimized, createdAtUnix) and check metadata the
+ * monitor prompt never reads (event, status, conclusion, category).
+ * detailsUrl is preserved in AgentCheck as a fallback for external status checks.
+ * The original domain types are preserved for check command output.
  */
 export function toAgentThread(t) {
     return { id: t.id, path: t.path, line: t.line, author: t.author, body: t.body };
@@ -13,7 +14,15 @@ export function toAgentComment(c) {
     return { id: c.id, author: c.author, body: c.body };
 }
 export function toAgentCheck(c) {
-    return { name: c.name, runId: c.runId, detailsUrl: c.detailsUrl, failureKind: c.failureKind };
+    return {
+        name: c.name,
+        runId: c.runId,
+        detailsUrl: c.detailsUrl,
+        failureKind: c.failureKind,
+        ...(c.workflowName !== undefined && { workflowName: c.workflowName }),
+        ...(c.failedStep !== undefined && { failedStep: c.failedStep }),
+        ...(c.summary !== undefined && { summary: c.summary }),
+    };
 }
 /**
  * Project and deduplicate checks so the agent makes one `gh run view` call

package/bin/reporters/check-instructions.mjs

@@ -0,0 +1,65 @@
+/**
+ * Build the numbered instruction steps for the agent to follow after a `check` run.
+ * All rebase policy, CI budget policy, and ready-to-merge gating live here so the
+ * skill stays a thin dispatcher and these rules co-evolve with the CLI data model.
+ */
+export function buildCheckInstructions(report) {
+    const { mergeStatus, checks, threads, comments, changesRequestedReviews, status } = report;
+    const instructions = [];
+    // 1. Summary
+    const totalActionable = threads.actionable.length + comments.actionable.length + changesRequestedReviews.length;
+    const total = checks.passing.length +
+        checks.failing.length +
+        checks.inProgress.length +
+        checks.skipped.length;
+    const copilotNote = mergeStatus.copilotReviewInProgress ? " (Copilot review in progress)" : "";
+    instructions.push(`Report: merge status is ${mergeStatus.status}${copilotNote}, CI ${checks.passing.length}/${total} passed` +
+        (checks.failing.length > 0 ? ` (${checks.failing.length} failing)` : "") +
+        (checks.inProgress.length > 0 ? ` (${checks.inProgress.length} in progress)` : "") +
+        `, ${totalActionable} actionable review item(s).`);
+    // 2. Rebase policy (only emit when relevant)
+    if (mergeStatus.status === "CONFLICTS") {
+        instructions.push("Rebase required: the branch has merge conflicts that must be resolved before this PR can land.");
+    }
+    else if (mergeStatus.status === "BEHIND") {
+        instructions.push("The PR is behind the base branch. A rebase is optional if all CI checks pass.");
+    }
+    // 3. CI budget policy — one instruction per failing check
+    for (const c of checks.failing) {
+        if (c.failureKind === "actionable") {
+            const diagnosisHint = c.failedStep
+                ? `the failure was in step \`${c.failedStep}\` — fetch the run log with \`gh run view ${c.runId ?? "<runId>"} --log-failed\` to diagnose`
+                : c.runId
+                    ? `fetch the run log with \`gh run view ${c.runId} --log-failed\` to diagnose the failure`
+                    : `open the check details (${c.detailsUrl}) to diagnose the failure`;
+            instructions.push(`Fix code failure: \`${c.name}\` (actionable) — ${diagnosisHint} and apply a fix.`);
+        }
+        else if (c.failureKind === "cancelled" || c.failureKind === "timeout") {
+            const rerunCmd = c.runId
+                ? `gh run rerun ${c.runId} --failed`
+                : `gh run rerun <runId> --failed`;
+            instructions.push(`Re-run transient failure: \`${c.name}\` [${c.failureKind}] — run \`${rerunCmd}\`.`);
+        }
+    }
+    // 4. Ready-to-merge gate
+    const isClean = mergeStatus.mergeStateStatus === "CLEAN";
+    const isReady = isClean && status === "READY" && !mergeStatus.copilotReviewInProgress;
+    if (isReady) {
+        instructions.push("This PR is ready to merge: mergeStateStatus is CLEAN, status is READY, and no Copilot review is in progress.");
+    }
+    else {
+        const blockers = [];
+        if (!isClean)
+            blockers.push(`mergeStateStatus is ${mergeStatus.mergeStateStatus} (not CLEAN)`);
+        if (status !== "READY")
+            blockers.push(`status is ${status} (not READY)`);
+        if (mergeStatus.copilotReviewInProgress)
+            blockers.push("Copilot review is still in progress");
+        instructions.push(`Do not declare this PR ready to merge: ${blockers.join("; ")}.`);
+    }
+    // 5. Continuous monitoring pointer (suppressed only when truly ready to merge)
+    if (!isReady) {
+        instructions.push("This is a one-shot check. For continuous monitoring that acts on these signals automatically, use `/pr-shepherd:monitor`.");
+    }
+    return instructions;
+}

package/bin/reporters/json.mjs

@@ -1,9 +1,10 @@
 /**
- * Machine-readable JSON reporter.
+ * Machine-readable JSON reporter for shepherd check output.
  *
  * Slash commands parse this output to extract IDs, status, and actionable items
  * without string-scraping the human-readable text reporter.
  */
+import { buildCheckInstructions } from "./check-instructions.mjs";
 export function formatJson(report) {
-    return JSON.stringify(report, null, 2);
+    return JSON.stringify({ ...report, instructions: buildCheckInstructions(report) }, null, 2);
 }