pr-shepherd 0.8.1 → 0.10.0

package/bin/cli/formatters.mjs

@@ -1,49 +1,79 @@
 export { formatIterateResult } from "./iterate-formatter.mjs";
+export { projectIterateLean } from "./iterate-lean.mjs";
+import { safeFence } from "./fence.mjs";
+import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderFirstLookStatusTag, } from "./list-formatters.mjs";
+import { joinSections } from "../util/markdown.mjs";
 export function formatFetchResult(result) {
-    const total = result.actionableThreads.length +
+    const activeTotal = result.actionableThreads.length +
         result.actionableComments.length +
         result.changesRequestedReviews.length +
         result.reviewSummaries.length;
+    const firstLookTotal = result.firstLookThreads.length + result.firstLookComments.length;
+    const total = activeTotal + firstLookTotal;
+    const headingParts = [];
+    if (activeTotal > 0)
+        headingParts.push(`${activeTotal} actionable`);
+    if (firstLookTotal > 0)
+        headingParts.push(`${firstLookTotal} first-look`);
+    const headingSuffix = headingParts.length > 0 ? headingParts.join(", ") : "0 actionable";
     const sections = [];
-    sections.push(`# PR #${result.prNumber} — Resolve fetch (${total === 0 ? "0 actionable" : `${total} actionable`})`);
+    sections.push(`# PR #${result.prNumber} — Resolve fetch (${headingSuffix})`);
     if (result.actionableThreads.length > 0) {
         sections.push(`## Actionable Review Threads (${result.actionableThreads.length})` +
             (result.commitSuggestionsEnabled ? " [commit-suggestions: enabled]" : ""));
         sections.push(result.actionableThreads
-            .map((t) => {
-            const suggestionMarker = t.suggestion ? " [suggestion]" : "";
-            return `- \`threadId=${t.id}\` \`${t.path ?? ""}:${t.line ?? "?"}\` (@${t.author})${suggestionMarker}: ${t.body.split("\n")[0]?.slice(0, 100) ?? ""}`;
-        })
-            .join("\n"));
+            .map((t) => renderThreadBullet(t, { renderSuggestion: true }))
+            .join("\n\n"));
     }
     if (result.actionableComments.length > 0) {
         sections.push(`## Actionable PR Comments (${result.actionableComments.length})`);
-        sections.push(result.actionableComments
-            .map((c) => `- \`commentId=${c.id}\` (@${c.author}): ${c.body.split("\n")[0]?.slice(0, 100) ?? ""}`)
-            .join("\n"));
+        sections.push(result.actionableComments.map((c) => renderCommentBullet(c)).join("\n"));
     }
     if (result.changesRequestedReviews.length > 0) {
         sections.push(`## Pending CHANGES_REQUESTED reviews (${result.changesRequestedReviews.length})`);
-        sections.push(result.changesRequestedReviews.map((r) => `- \`reviewId=${r.id}\` (@${r.author})`).join("\n"));
+        sections.push(result.changesRequestedReviews.map((r) => renderReviewBullet(r)).join("\n"));
     }
     if (result.reviewSummaries.length > 0) {
         sections.push(`## Review summaries (${result.reviewSummaries.length})`);
-        sections.push(result.reviewSummaries
-            .map((r) => `- \`reviewId=${r.id}\` (@${r.author}): ${r.body.split("\n")[0].slice(0, 100)}`)
-            .join("\n"));
+        sections.push(result.reviewSummaries.map((r) => renderReviewBullet(r, { includeBody: true })).join("\n"));
+    }
+    if (firstLookTotal > 0) {
+        sections.push(`## First-look items (${firstLookTotal}) — already closed on GitHub; acknowledge only`);
+        const bullets = [];
+        for (const t of result.firstLookThreads) {
+            bullets.push(renderThreadBullet(t, { statusTag: renderFirstLookStatusTag(t) }));
+        }
+        for (const c of result.firstLookComments) {
+            bullets.push(renderCommentBullet(c, { statusTag: "[status: minimized]" }));
+        }
+        sections.push(bullets.join("\n"));
     }
     sections.push("## Summary");
-    sections.push(total === 0 ? "0 actionable — all threads resolved/minimized" : `${total} actionable item(s)`);
+    sections.push(total === 0
+        ? "0 actionable, 0 first-look — all items seen"
+        : [
+            activeTotal > 0 ? `${activeTotal} actionable` : null,
+            firstLookTotal > 0 ? `${firstLookTotal} first-look` : null,
+        ]
+            .filter(Boolean)
+            .join(", "));
     sections.push("## Instructions");
     sections.push(result.instructions.map((inst, i) => `${i + 1}. ${inst}`).join("\n"));
-    return `${sections.join("\n\n")}\n`;
+    return joinSections(sections);
 }
 export function formatCommitSuggestionResult(result) {
     const lines = [];
+    const range = result.startLine === result.endLine
+        ? `line ${result.startLine}`
+        : `lines ${result.startLine}–${result.endLine}`;
+    function pushPatch(patch) {
+        const fence = safeFence(patch);
+        lines.push("");
+        lines.push(`${fence}diff`);
+        lines.push(patch.trimEnd());
+        lines.push(fence);
+    }
     if (result.dryRun) {
-        const range = result.startLine === result.endLine
-            ? `line ${result.startLine}`
-            : `lines ${result.startLine}-${result.endLine}`;
         if (result.valid) {
             lines.push(`Dry-run: would apply suggestion from @${result.author}:`);
             lines.push(`  ${result.path} (${range})`);
@@ -54,45 +84,32 @@ export function formatCommitSuggestionResult(result) {
             lines.push(`- author: @${result.author}`);
             lines.push(`- reason: ${result.reason ?? "unknown"}`);
         }
-        if (result.patch) {
-            lines.push("");
-            lines.push("```diff");
-            lines.push(result.patch.trimEnd());
-            lines.push("```");
-        }
+        if (result.patch)
+            pushPatch(result.patch);
     }
     else if (result.applied) {
         lines.push(`Applied suggestion from @${result.author}:`);
-        const range = result.startLine === result.endLine
-            ? `line ${result.startLine}`
-            : `lines ${result.startLine}-${result.endLine}`;
         lines.push(`  ${result.path} (${range})`);
         if (result.commitSha)
             lines.push(`Commit: ${result.commitSha}`);
-        if (result.patch) {
-            lines.push("");
-            lines.push("```diff");
-            lines.push(result.patch.trimEnd());
-            lines.push("```");
-        }
+        if (result.patch)
+            pushPatch(result.patch);
     }
     else {
         lines.push(`Failed to apply suggestion ${result.threadId}:`);
-        lines.push(`- path: ${result.path} (lines ${result.startLine}–${result.endLine})`);
+        lines.push(`- path: ${result.path} (${range})`);
         lines.push(`- author: @${result.author}`);
         lines.push(`- reason: ${result.reason ?? "unknown"}`);
-        if (result.patch) {
-            lines.push("");
-            lines.push("```diff");
-            lines.push(result.patch.trimEnd());
-            lines.push("```");
-        }
+        if (result.patch)
+            pushPatch(result.patch);
     }
     if (result.postActionInstruction) {
         lines.push("");
-        lines.push(result.postActionInstruction);
+        lines.push("## Instructions");
+        lines.push("");
+        lines.push(`1. ${result.postActionInstruction}`);
     }
-    return `${lines.join("\n")}\n`;
+    return lines.join("\n");
 }
 export function formatMutateResult(result) {
     const lines = [];
@@ -104,5 +121,5 @@ export function formatMutateResult(result) {
         lines.push(`Dismissed reviews (${result.dismissedReviews.length}): ${result.dismissedReviews.join(", ")}`);
     if (result.errors.length)
         lines.push(`Errors:\n  ${result.errors.join("\n  ")}`);
-    return `${lines.join("\n")}\n`;
+    return lines.join("\n");
 }

package/bin/cli/handlers.mjs

@@ -6,7 +6,7 @@ import { getRepoInfo } from "../github/client.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { parseCommonArgs, getFlag, hasFlag, parseStatusPrNumbers, parseIntStrict, } from "./args.mjs";
 import { parseDurationToMinutes, iterateActionToExitCode, deriveSimpleReady, } from "./exit-codes.mjs";
-import { formatCommitSuggestionResult, formatIterateResult } from "./formatters.mjs";
+import { formatCommitSuggestionResult, formatIterateResult, projectIterateLean, } from "./formatters.mjs";
 export async function handleCommitSuggestion(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const threadId = getFlag(extra, "--thread-id");
@@ -34,7 +34,7 @@ export async function handleCommitSuggestion(args) {
     });
     process.stdout.write(globalOpts.format === "json"
         ? `${JSON.stringify(result, null, 2)}\n`
-        : formatCommitSuggestionResult(result));
+        : `${formatCommitSuggestionResult(result)}\n`);
     if (result.dryRun) {
         process.exitCode = result.valid ? 0 : 1;
     }
@@ -67,10 +67,11 @@ export async function handleIterate(args) {
         noAutoCancelActionable,
     });
     if (globalOpts.format === "json") {
-        process.stdout.write(`${JSON.stringify(result)}\n`);
+        const output = globalOpts.verbose ? result : projectIterateLean(result);
+        process.stdout.write(`${JSON.stringify(output)}\n`);
     }
     else {
-        process.stdout.write(`${formatIterateResult(result)}\n`);
+        process.stdout.write(`${formatIterateResult(result, { verbose: globalOpts.verbose })}\n`);
     }
     process.exitCode = iterateActionToExitCode(result.action);
 }

package/bin/cli/iterate-formatter.mjs

@@ -1,4 +1,5 @@
 import { formatFixCodeResult } from "./fix-formatter.mjs";
+import { joinSections } from "../util/markdown.mjs";
 /**
  * Format an IterateResult as human-readable Markdown.
  *
@@ -14,64 +15,69 @@ import { formatFixCodeResult } from "./fix-formatter.mjs";
  *      unconditional: every action, every variant, always emits at least one step.
  *      The SKILL simply follows those steps; it does not need its own dispatch table.
  */
-export function formatIterateResult(result) {
+export function formatIterateResult(result, opts) {
+    const verbose = opts?.verbose ?? false;
     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 reviewDecisionSeg = result.mergeStatus === "BLOCKED" && result.reviewDecision
+        ? ` · **reviewDecision** \`${result.reviewDecision}\``
+        : "";
+    const baseLine = `**status** \`${result.status}\` · **merge** \`${result.mergeStateStatus}\`${reviewDecisionSeg} · **state** \`${result.state}\` · **repo** \`${result.repo}\``;
+    let summaryLine;
+    if (verbose) {
+        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}`;
+    }
+    else {
+        const counts = [`${result.summary.passing} passing`];
+        if (result.summary.skipped > 0)
+            counts.push(`${result.summary.skipped} skipped`);
+        if (result.summary.filtered > 0)
+            counts.push(`${result.summary.filtered} filtered`);
+        if (result.summary.inProgress > 0)
+            counts.push(`${result.summary.inProgress} inProgress`);
+        const segs = [`**summary** ${counts.join(", ")}`];
+        if (result.status === "READY" && result.remainingSeconds > 0) {
+            segs.push(`**remainingSeconds** ${result.remainingSeconds}`);
+        }
+        if (result.copilotReviewInProgress)
+            segs.push(`**copilotReviewInProgress**`);
+        if (result.isDraft)
+            segs.push(`**isDraft**`);
+        summaryLine = segs.join(" · ");
+    }
     const header = [heading, "", baseLine, summaryLine].join("\n");
     switch (result.action) {
         case "cooldown":
-            return [
-                header,
-                "",
+            // In default mode: suppress base/summary lines — cooldown carries UNKNOWN/empty
+            // placeholders that add no value. Emit only heading + log + Instructions.
+            return joinSections([
+                verbose ? header : heading,
                 result.log,
-                "",
-                "## Instructions",
-                "",
-                "1. End this iteration — the next cron fire will recheck once CI starts reporting.",
-            ].join("\n");
-        case "wait": {
-            const parts = [
+                "## Instructions\n\n1. End this iteration — the next cron fire will recheck once CI starts reporting.",
+            ]);
+        case "wait":
+            return joinSections([
                 header,
                 result.log,
-                "## Instructions",
-                "1. End this iteration — the next cron fire will recheck.",
-            ];
-            return parts.join("\n\n").replace(/\n\n\n+/g, "\n\n");
-        }
-        case "rerun_ci": {
-            const rerunInstructions = result.reran.map((r, i) => `${i + 1}. Run: \`gh run rerun ${r.runId} --failed\``);
-            rerunInstructions.push(`${rerunInstructions.length + 1}. End this iteration — wait for CI to report results after the re-run.`);
-            const parts = [header, result.log, "## Instructions", rerunInstructions.join("\n")];
-            return parts.join("\n\n").replace(/\n\n\n+/g, "\n\n");
-        }
-        case "mark_ready": {
-            const parts = [
+                "## Instructions\n\n1. End this iteration — the next cron fire will recheck.",
+            ]);
+        case "mark_ready":
+            return joinSections([
                 header,
                 result.log,
-                "## Instructions",
-                "1. The CLI already marked the PR ready for review — end this iteration.",
-            ];
-            return parts.join("\n\n").replace(/\n\n\n+/g, "\n\n");
-        }
-        case "cancel": {
-            const parts = [
+                "## Instructions\n\n1. The CLI already marked the PR ready for review — end this iteration.",
+            ]);
+        case "cancel":
+            return joinSections([
                 [`${heading} — ${result.reason}`, "", baseLine, summaryLine].join("\n"),
                 result.log,
-                "## Instructions",
-                "1. Invoke `/loop cancel` via the Skill tool.\n2. Stop.",
-            ];
-            return parts.join("\n\n").replace(/\n\n\n+/g, "\n\n");
-        }
-        case "escalate": {
-            const parts = [
+                "## Instructions\n\n1. Invoke `/loop cancel` via the Skill tool.\n2. Stop.",
+            ]);
+        case "escalate":
+            return joinSections([
                 header,
                 result.escalate.humanMessage,
-                "## Instructions",
-                "1. Invoke `/loop cancel` via the Skill tool.\n2. Stop — the PR needs human direction before monitoring can resume.",
-            ];
-            return parts.join("\n\n").replace(/\n\n\n+/g, "\n\n");
-        }
+                "## Instructions\n\n1. Invoke `/loop cancel` via the Skill tool.\n2. Stop — the PR needs human direction before monitoring can resume.",
+            ]);
         case "fix_code":
             return formatFixCodeResult(header, result);
     }

package/bin/cli/iterate-lean.mjs

@@ -0,0 +1,95 @@
+/**
+ * Project an IterateResult to a lean JSON shape for the default (non-verbose) output.
+ * Omits fields that are the trivial default (false, 0, empty) or state-gated fields
+ * outside the state where they are meaningful.
+ */
+export function projectIterateLean(result) {
+    const base = {
+        action: result.action,
+        pr: result.pr,
+        repo: result.repo || undefined,
+        status: result.status,
+        state: result.state,
+        mergeStateStatus: result.mergeStateStatus,
+        ...(result.mergeStatus === "BLOCKED" &&
+            result.reviewDecision !== null && { reviewDecision: result.reviewDecision }),
+        ...(result.copilotReviewInProgress && { copilotReviewInProgress: true }),
+        ...(result.isDraft && { isDraft: true }),
+        summary: {
+            passing: result.summary.passing,
+            ...(result.summary.skipped > 0 && { skipped: result.summary.skipped }),
+            ...(result.summary.filtered > 0 && { filtered: result.summary.filtered }),
+            ...(result.summary.inProgress > 0 && { inProgress: result.summary.inProgress }),
+        },
+        // remainingSeconds: only when the ready-delay timer is actively counting down
+        ...(result.status === "READY" &&
+            result.remainingSeconds > 0 && {
+            remainingSeconds: result.remainingSeconds,
+        }),
+        ...(result.baseBranch && { baseBranch: result.baseBranch }),
+    };
+    switch (result.action) {
+        case "cooldown":
+            return { ...base, log: result.log };
+        case "wait":
+            return { ...base, log: result.log };
+        case "cancel":
+            return { ...base, reason: result.reason, log: result.log };
+        case "mark_ready":
+            // drop markedReady — always true, redundant with action discriminator
+            return { ...base, log: result.log };
+        case "fix_code":
+            return {
+                ...base,
+                ...(result.checks.length > 0 && { checks: result.checks }),
+                ...(result.cancelled.length > 0 && { cancelled: result.cancelled }),
+                fix: {
+                    mode: result.fix.mode,
+                    ...(result.fix.threads.length > 0 && { threads: result.fix.threads }),
+                    ...(result.fix.actionableComments.length > 0 && {
+                        actionableComments: result.fix.actionableComments,
+                    }),
+                    ...(result.fix.reviewSummaryIds.length > 0 && {
+                        reviewSummaryIds: result.fix.reviewSummaryIds,
+                    }),
+                    ...(result.fix.surfacedApprovals.length > 0 && {
+                        surfacedApprovals: result.fix.surfacedApprovals,
+                    }),
+                    ...(result.fix.firstLookThreads.length > 0 && {
+                        firstLookThreads: result.fix.firstLookThreads,
+                    }),
+                    ...(result.fix.firstLookComments.length > 0 && {
+                        firstLookComments: result.fix.firstLookComments,
+                    }),
+                    ...(result.fix.checks.length > 0 && { checks: result.fix.checks }),
+                    ...(result.fix.changesRequestedReviews.length > 0 && {
+                        changesRequestedReviews: result.fix.changesRequestedReviews,
+                    }),
+                    resolveCommand: result.fix.resolveCommand,
+                    ...(result.fix.instructions.length > 0 && { instructions: result.fix.instructions }),
+                },
+            };
+        case "escalate":
+            return {
+                ...base,
+                escalate: {
+                    ...(result.escalate.triggers.length > 0 && { triggers: result.escalate.triggers }),
+                    ...(result.escalate.unresolvedThreads.length > 0 && {
+                        unresolvedThreads: result.escalate.unresolvedThreads,
+                    }),
+                    ...(result.escalate.ambiguousComments.length > 0 && {
+                        ambiguousComments: result.escalate.ambiguousComments,
+                    }),
+                    ...(result.escalate.changesRequestedReviews.length > 0 && {
+                        changesRequestedReviews: result.escalate.changesRequestedReviews,
+                    }),
+                    ...(result.escalate.attemptHistory &&
+                        result.escalate.attemptHistory.length > 0 && {
+                        attemptHistory: result.escalate.attemptHistory,
+                    }),
+                    suggestion: result.escalate.suggestion,
+                    humanMessage: result.escalate.humanMessage,
+                },
+            };
+    }
+}

package/bin/cli/list-formatters.mjs

@@ -0,0 +1,32 @@
+import { renderLineRange, renderSuggestionBlock } from "./suggestion-renderer.mjs";
+const BODY_PREVIEW_MAX = 100;
+export function renderBodyPreview(body) {
+    const normalizedBody = body.replace(/\r\n?/g, "\n");
+    const firstLine = normalizedBody.split("\n")[0]?.trim() ?? "";
+    return firstLine.slice(0, BODY_PREVIEW_MAX);
+}
+export function renderFirstLookStatusTag(t) {
+    return t.autoResolved ? "[status: outdated, auto-resolved]" : `[status: ${t.firstLookStatus}]`;
+}
+export function renderThreadBullet(t, opts = {}) {
+    const link = t.url ? ` [↗](${t.url})` : "";
+    const loc = t.path
+        ? `\`${t.path}:${renderLineRange(t.startLine ?? undefined, t.line ?? null)}\``
+        : "`(no location)`";
+    const suggestionMarker = t.suggestion ? " [suggestion]" : "";
+    const statusSuffix = opts.statusTag ? ` ${opts.statusTag}` : "";
+    const bulletLine = `- \`threadId=${t.id}\`${link} ${loc} (@${t.author})${suggestionMarker}${statusSuffix}: ${renderBodyPreview(t.body)}`;
+    if (t.suggestion && opts.renderSuggestion) {
+        return `${bulletLine}\n${renderSuggestionBlock(t.suggestion)}`;
+    }
+    return bulletLine;
+}
+export function renderCommentBullet(c, opts = {}) {
+    const link = c.url ? ` [↗](${c.url})` : "";
+    const statusSuffix = opts.statusTag ? ` ${opts.statusTag}` : "";
+    return `- \`commentId=${c.id}\`${link} (@${c.author})${statusSuffix}: ${renderBodyPreview(c.body)}`;
+}
+export function renderReviewBullet(r, opts = {}) {
+    const bodySuffix = opts.includeBody && r.body != null && r.body !== "" ? `: ${renderBodyPreview(r.body)}` : "";
+    return `- \`reviewId=${r.id}\` (@${r.author})${bodySuffix}`;
+}

package/bin/cli/suggestion-renderer.mjs

@@ -0,0 +1,31 @@
+import { safeFence } from "./fence.mjs";
+export function renderLineRange(startLine, endLine) {
+    if (endLine === null)
+        return "?";
+    if (startLine !== undefined && startLine !== endLine)
+        return `${startLine}-${endLine}`;
+    return String(endLine);
+}
+export function renderSuggestionBlock(s, indent = "  ") {
+    const rangeLabel = s.startLine !== s.endLine ? `lines ${s.startLine}–${s.endLine}` : `line ${s.startLine}`;
+    const content = s.lines.join("\n");
+    const fence = safeFence(content);
+    const label = s.lines.length === 0
+        ? `Replaces ${rangeLabel} with nothing:`
+        : s.lines.length === 1 && s.lines[0] === ""
+            ? `Replaces ${rangeLabel} with a blank line:`
+            : `Replaces ${rangeLabel}:`;
+    return [
+        `${indent}${label}`,
+        `${indent}${fence}`,
+        ...(content === ""
+            ? []
+            : [
+                content
+                    .split("\n")
+                    .map((l) => `${indent}${l}`)
+                    .join("\n"),
+            ]),
+        `${indent}${fence}`,
+    ].join("\n");
+}

package/bin/cli-parser.iterate-fixtures.mjs

@@ -5,6 +5,8 @@ export function makeIterateResult(action = "wait") {
         status: "IN_PROGRESS",
         state: "OPEN",
         mergeStateStatus: "BLOCKED",
+        mergeStatus: "BLOCKED",
+        reviewDecision: null,
         copilotReviewInProgress: false,
         isDraft: false,
         shouldCancel: false,
@@ -17,8 +19,6 @@ export function makeIterateResult(action = "wait") {
         return { ...base, action: "cooldown", log: "SKIP: CI still starting" };
     if (action === "wait")
         return { ...base, action: "wait", log: "WAIT: 0 passing, 1 in-progress" };
-    if (action === "rerun_ci")
-        return { ...base, action: "rerun_ci", log: "RERAN: run-99 (typecheck — transient)", reran: [] };
     if (action === "mark_ready")
         return { ...base, action: "mark_ready", markedReady: true, log: "MARKED READY: PR 42" };
     if (action === "fix_code") {
@@ -29,9 +29,8 @@ export function makeIterateResult(action = "wait") {
                 mode: "rebase-and-push",
                 threads: [],
                 actionableComments: [],
-                noiseCommentIds: [],
                 reviewSummaryIds: [],
-                surfacedSummaries: [],
+                surfacedApprovals: [],
                 checks: [],
                 changesRequestedReviews: [],
                 resolveCommand: {
@@ -41,6 +40,8 @@ export function makeIterateResult(action = "wait") {
                     hasMutations: false,
                 },
                 instructions: ["End this iteration."],
+                firstLookThreads: [],
+                firstLookComments: [],
             },
             cancelled: [],
         };
@@ -62,7 +63,7 @@ export function makeIterateResult(action = "wait") {
                 ambiguousComments: [],
                 changesRequestedReviews: [],
                 suggestion: "check manually",
-                humanMessage: "⚠️  /pr-shepherd:monitor paused — needs human direction",
+                humanMessage: "⚠️ /pr-shepherd:monitor paused — needs human direction",
             },
         };
     }

package/bin/cli-parser.mjs

@@ -18,12 +18,14 @@
 import { readFileSync } from "node:fs";
 import { runCheck } from "./commands/check.mjs";
 import { runResolveFetch, runResolveMutate } from "./commands/resolve.mjs";
+import { runLogFile } from "./commands/log-file.mjs";
 import { formatJson } from "./reporters/json.mjs";
 import { formatText } from "./reporters/text.mjs";
 import { parseCommonArgs, getFlag, hasFlag, parseList } from "./cli/args.mjs";
 import { statusToExitCode } from "./cli/exit-codes.mjs";
 import { formatFetchResult, formatMutateResult } from "./cli/formatters.mjs";
 import { handleCommitSuggestion, handleIterate, handleMonitor, handleStatus, } from "./cli/handlers.mjs";
+import { setupLog } from "./log/setup.mjs";
 // ---------------------------------------------------------------------------
 // Entry
 // ---------------------------------------------------------------------------
@@ -34,6 +36,13 @@ export async function main(argv) {
         process.stdout.write(`${readVersion()}\n`);
         return;
     }
+    // log-file must run before the stdout tee and log init to avoid recursion.
+    if (subcommand === "log-file") {
+        await handleLogFile(args.slice(1));
+        return;
+    }
+    // Initialize the per-worktree log and install a stdout tee.
+    await setupLog(argv);
     switch (subcommand) {
         case "check":
             await handleCheck(args.slice(1));
@@ -55,7 +64,7 @@ export async function main(argv) {
             break;
         default:
             process.stderr.write(`Unknown subcommand: ${subcommand ?? "(none)"}\n`);
-            process.stderr.write("Usage: pr-shepherd <check|resolve|commit-suggestion|iterate|monitor|status> [options]\n" +
+            process.stderr.write("Usage: pr-shepherd <check|resolve|commit-suggestion|iterate|monitor|status|log-file> [options]\n" +
                 "       pr-shepherd --version | -v\n");
             process.exitCode = 1;
             return;
@@ -76,6 +85,21 @@ async function handleCheck(args) {
     process.stdout.write(`${output}\n`);
     process.exitCode = statusToExitCode(report.status);
 }
+async function handleLogFile(args) {
+    const jsonOut = args.some((a) => a === "--format=json") ||
+        (() => {
+            const idx = args.indexOf("--format");
+            return idx !== -1 && args[idx + 1] === "json";
+        })();
+    try {
+        const result = await runLogFile();
+        process.stdout.write(jsonOut ? `${JSON.stringify(result, null, 2)}\n` : `${result.path}\n`);
+    }
+    catch (e) {
+        process.stderr.write(`pr-shepherd: log-file: ${String(e)}\n`);
+        process.exitCode = 1;
+    }
+}
 async function handleResolve(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const resolveThreadIds = parseList(getFlag(extra, "--resolve-thread-ids"));
@@ -91,7 +115,7 @@ async function handleResolve(args) {
         const result = await runResolveFetch({ ...globalOpts, prNumber });
         process.stdout.write(globalOpts.format === "json"
             ? `${JSON.stringify(result, null, 2)}\n`
-            : formatFetchResult(result));
+            : `${formatFetchResult(result)}\n`);
     }
     else {
         const result = await runResolveMutate({
@@ -105,6 +129,6 @@ async function handleResolve(args) {
         });
         process.stdout.write(globalOpts.format === "json"
             ? `${JSON.stringify(result, null, 2)}\n`
-            : formatMutateResult(result));
+            : `${formatMutateResult(result)}\n`);
     }
 }

package/bin/commands/check-status.mjs

@@ -9,15 +9,18 @@ export function computeStatus(verdict, unresolvedThreads, unresolvedComments, me
         return "FAILING";
     if (verdict.anyInProgress)
         return "IN_PROGRESS";
-    // 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.
+    // BLOCKED with no remaining shepherd work — hand off via ready-delay regardless of why GitHub
+    // is BLOCKED (review pending, insufficient approvals, branch-protection rule, etc.).
+    // Requires hasChecks so that a PR with zero relevant checks (CI never started, or all
+    // filtered/skipped) doesn't prematurely trigger READY before any check has reported.
+    // copilotReviewInProgress is still excluded — a bot review is shepherd's problem, not a hand-off.
     if (verdict.allPassed &&
+        verdict.hasChecks &&
         unresolvedThreads === 0 &&
         unresolvedComments === 0 &&
         changesRequestedReviews === 0 &&
         mergeStatus.status === "BLOCKED" &&
-        !mergeStatus.copilotReviewInProgress &&
-        mergeStatus.reviewDecision === "REVIEW_REQUIRED") {
+        !mergeStatus.copilotReviewInProgress) {
         return "READY";
     }
     if (mergeStatus.status === "BLOCKED" ||