pr-shepherd 0.8.0 → 0.9.0

package/bin/cli/iterate-lean.mjs

@@ -0,0 +1,98 @@
+/**
+ * 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.noiseCommentIds.length > 0 && {
+                        noiseCommentIds: result.fix.noiseCommentIds,
+                    }),
+                    ...(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-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") {
@@ -31,7 +31,7 @@ export function makeIterateResult(action = "wait") {
                 actionableComments: [],
                 noiseCommentIds: [],
                 reviewSummaryIds: [],
-                surfacedSummaries: [],
+                surfacedApprovals: [],
                 checks: [],
                 changesRequestedReviews: [],
                 resolveCommand: {
@@ -41,12 +41,19 @@ export function makeIterateResult(action = "wait") {
                     hasMutations: false,
                 },
                 instructions: ["End this iteration."],
+                firstLookThreads: [],
+                firstLookComments: [],
             },
             cancelled: [],
         };
     }
     if (action === "cancel")
-        return { ...base, action: "cancel", log: "CANCEL: PR #42 — stopping monitor" };
+        return {
+            ...base,
+            action: "cancel",
+            reason: "ready-delay-elapsed",
+            log: "CANCEL: PR #42 — stopping monitor",
+        };
     if (action === "escalate") {
         return {
             ...base,

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" ||

package/bin/commands/check.mjs

@@ -21,15 +21,17 @@ import { autoResolveOutdated } from "../comments/resolve.mjs";
 import { deriveMergeStatus } from "../merge-status/derive.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { computeStatus } from "./check-status.mjs";
+import { loadSeenSet, markSeen } from "../state/seen-comments.mjs";
 export async function runCheck(opts) {
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
     if (prNumber === null) {
         throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
     }
+    const config = loadConfig();
     // Only paginate APPROVED reviews when the caller will actually minimize them.
     // Otherwise the first-page cap of 50 (already in the batch) is plenty — no extra round-trip.
-    const paginateApprovedReviews = loadConfig().iterate.minimizeReviewSummaries.approvals;
+    const paginateApprovedReviews = config.iterate.minimizeApprovals;
     const result = await fetchPrBatch(prNumber, repo, { paginateApprovedReviews });
     let batchData = result.data;
     // GraphQL sometimes returns UNKNOWN for mergeable/mergeStateStatus while the
@@ -52,8 +54,11 @@ export async function runCheck(opts) {
     const inProgress = classifiedChecks.filter((c) => c.category === "in_progress");
     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, repo) : failing;
+    // Triage failures (fetch job info + log tails) — skipped when caller short-circuits early.
+    const triaged = failing.length > 0 && !opts.skipTriage
+        ? await triageFailingChecks(failing, repo, config.checks.logTailLines)
+        : failing;
+    const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
     // Resolve threads and comments.
     const unresolvedThreads = batchData.reviewThreads.filter((t) => !t.isResolved && !t.isMinimized);
     const visibleComments = batchData.comments.filter((c) => !c.isMinimized);
@@ -67,6 +72,36 @@ export async function runCheck(opts) {
         autoResolveErrors = errors;
     }
     const activeThreads = unresolvedThreads.filter((t) => !t.isOutdated);
+    // First-look: collect previously-hidden items not yet seen by the agent.
+    const outdatedCandidates = batchData.reviewThreads.filter((t) => t.isOutdated);
+    const resolvedCandidates = batchData.reviewThreads.filter((t) => t.isResolved && !t.isOutdated);
+    const minimizedThreadCandidates = batchData.reviewThreads.filter((t) => t.isMinimized && !t.isResolved && !t.isOutdated);
+    const minimizedCommentCandidates = batchData.comments.filter((c) => c.isMinimized);
+    const seenSet = await loadSeenSet(stateKey);
+    const autoResolvedIds = new Set(autoResolved.map((t) => t.id));
+    const firstLookThreads = [
+        ...outdatedCandidates
+            .filter((t) => !seenSet.has(t.id))
+            .map((t) => ({
+            ...t,
+            firstLookStatus: "outdated",
+            autoResolved: autoResolvedIds.has(t.id),
+        })),
+        ...resolvedCandidates
+            .filter((t) => !seenSet.has(t.id))
+            .map((t) => ({ ...t, firstLookStatus: "resolved" })),
+        ...minimizedThreadCandidates
+            .filter((t) => !seenSet.has(t.id))
+            .map((t) => ({ ...t, firstLookStatus: "minimized" })),
+    ];
+    const firstLookComments = minimizedCommentCandidates
+        .filter((c) => !seenSet.has(c.id))
+        .map((c) => ({ ...c, firstLookStatus: "minimized" }));
+    // Mark first-look items as seen (best-effort — markSeen never throws).
+    await Promise.allSettled([
+        ...firstLookThreads.map((t) => markSeen(stateKey, t.id)),
+        ...firstLookComments.map((c) => markSeen(stateKey, c.id)),
+    ]);
     // Actionable: all active threads and all visible comments (no classification — LLM handles triage).
     const actionableThreads = activeThreads;
     const actionableComments = visibleComments;
@@ -99,9 +134,11 @@ export async function runCheck(opts) {
             actionable: actionableThreads,
             autoResolved,
             autoResolveErrors,
+            firstLook: firstLookThreads,
         },
         comments: {
             actionable: actionableComments,
+            firstLook: firstLookComments,
         },
         changesRequestedReviews: batchData.changesRequestedReviews,
         reviewSummaries: batchData.reviewSummaries,

package/bin/commands/iterate/classify.mjs

@@ -1,31 +1,11 @@
-// Logins treated as bot authors regardless of the GitHub Bot/User user type.
-// Mirrors plugin/skills/resolve/SKILL.md §3 — kept in sync with the resolve triage guidance.
-const KNOWN_BOT_LOGINS = new Set([
-    "copilot-pull-request-reviewer",
-    "gemini-code-assist",
-    "coderabbitai",
-]);
-function isBotAuthor(login) {
-    const bare = login.replace(/\[bot\]$/, "");
-    if (bare !== login)
-        return true;
-    return KNOWN_BOT_LOGINS.has(bare);
-}
-export function classifyReviewSummaries(summaries, approvals, cfg) {
-    const minimizeIds = [];
-    const surfacedSummaries = [];
-    for (const r of summaries) {
-        const enabled = isBotAuthor(r.author) ? cfg.bots : cfg.humans;
-        if (enabled)
-            minimizeIds.push(r.id);
-        else
-            surfacedSummaries.push(r);
-    }
-    if (cfg.approvals) {
+export function classifyReviewSummaries(summaries, approvals, minimizeApprovals) {
+    const minimizeIds = summaries.map((r) => r.id);
+    if (minimizeApprovals) {
         for (const r of approvals)
             minimizeIds.push(r.id);
+        return { minimizeIds, surfacedApprovals: [] };
     }
-    return { minimizeIds, surfacedSummaries };
+    return { minimizeIds, surfacedApprovals: approvals };
 }
 // Patterns that indicate a comment is bot-generated noise rather than actionable feedback.
 // Conservative: only match explicit known patterns to avoid accidentally suppressing real reviews.

package/bin/commands/iterate/escalate.mjs

@@ -1,5 +1,5 @@
 import { loadConfig } from "../../config/load.mjs";
-export function checkEscalateTriggers(actionableThreads, actionableComments, changesRequestedReviews, actionableChecks, threadAttempts, hasConflicts) {
+export function checkEscalateTriggers(actionableThreads, actionableComments, changesRequestedReviews, failingChecks, threadAttempts, hasConflicts) {
     const triggers = [];
     const maxAttempts = loadConfig().iterate.fixAttemptsPerThread;
     // Trigger 1: fix thrash — same thread dispatched too many times without resolving.
@@ -12,7 +12,7 @@ export function checkEscalateTriggers(actionableThreads, actionableComments, cha
     if (changesRequestedReviews.length > 0 &&
         actionableThreads.length === 0 &&
         actionableComments.length === 0 &&
-        actionableChecks.length === 0 &&
+        failingChecks.length === 0 &&
         !hasConflicts) {
         triggers.push("pr-level-changes-requested");
     }

package/bin/commands/iterate/fix-code.mjs

@@ -6,8 +6,8 @@ import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { tryCancelRun } from "./helpers.mjs";
 export async function handleFixCode(ctx) {
-    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, surfacedSummaries, } = ctx;
-    const actionableChecks = report.checks.failing.filter((f) => f.failureKind === "actionable");
+    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, surfacedApprovals, } = ctx;
+    const failingChecks = report.checks.failing;
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
     const isNewSha = stored?.headSha !== headSha;
     // Accumulate across shas — only increment when a push is detected (sha changed)
@@ -17,7 +17,7 @@ export async function handleFixCode(ctx) {
             currentAttempts[t.id] = (currentAttempts[t.id] ?? 0) + 1;
         }
     }
-    const escalateTriggers = checkEscalateTriggers(report.threads.actionable, report.comments.actionable, report.changesRequestedReviews, actionableChecks, currentAttempts, report.mergeStatus.status === "CONFLICTS");
+    const escalateTriggers = checkEscalateTriggers(report.threads.actionable, report.comments.actionable, report.changesRequestedReviews, failingChecks, currentAttempts, report.mergeStatus.status === "CONFLICTS");
     if (escalateTriggers.triggers.length > 0) {
         const escalateBase = {
             triggers: escalateTriggers.triggers,
@@ -41,7 +41,7 @@ export async function handleFixCode(ctx) {
     let cancelled = [];
     if (!opts.noAutoCancelActionable) {
         const uniqueRunIds = [
-            ...new Set(actionableChecks.map((c) => c.runId).filter((id) => id !== null)),
+            ...new Set(failingChecks.map((c) => c.runId).filter((id) => id !== null)),
         ];
         const results = await Promise.all(uniqueRunIds.map((id) => tryCancelRun(id, repoOwner, repoName)));
         cancelled = results.filter((id) => id !== null);
@@ -49,7 +49,7 @@ export async function handleFixCode(ctx) {
     const baseLookup = validateBaseBranch(report.baseBranch);
     const threads = report.threads.actionable.map(toAgentThread);
     const { actionable: actionableComments, noiseIds: noiseCommentIds } = classifyComments(report.comments.actionable.map(toAgentComment));
-    const checks = toAgentChecks(actionableChecks);
+    const checks = toAgentChecks(failingChecks);
     const { changesRequestedReviews } = report;
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
     const allCommentIds = [
@@ -75,7 +75,9 @@ export async function handleFixCode(ctx) {
             },
         };
     }
-    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length);
+    const firstLookThreads = report.threads.firstLook;
+    const firstLookComments = report.comments.firstLook;
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments);
     return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, {
         ...base,
         baseBranch: baseLookup.branch,
@@ -86,11 +88,13 @@ export async function handleFixCode(ctx) {
             actionableComments,
             noiseCommentIds,
             reviewSummaryIds,
-            surfacedSummaries,
+            surfacedApprovals,
             checks,
             changesRequestedReviews,
             resolveCommand,
             instructions,
+            firstLookThreads,
+            firstLookComments,
         },
         cancelled,
     }, report, reviewSummaryIds);

package/bin/commands/iterate/helpers.mjs

@@ -13,7 +13,8 @@ export function buildSummary(report) {
 /**
  * Build the full list of CI checks relevant to PR readiness: triggered by a PR
  * event (or StatusContext with null event), completed, and not skipped/neutral.
- * Includes both passing and failing. Failing entries carry failureKind + errorExcerpt.
+ * Includes both passing and failing. Failing entries carry workflowName, jobName,
+ * failedStep, and summary.
  */
 export function buildRelevantChecks(report) {
     const excluded = new Set([null, "SKIPPED", "NEUTRAL"]);
@@ -41,10 +42,10 @@ export function buildRelevantChecks(report) {
                 conclusion,
                 runId: c.runId,
                 detailsUrl: c.detailsUrl || null,
-                failureKind: c.failureKind,
-                workflowName: c.workflowName,
-                failedStep: c.failedStep,
-                summary: c.summary,
+                ...(c.workflowName !== undefined && { workflowName: c.workflowName }),
+                ...(c.jobName !== undefined && { jobName: c.jobName }),
+                ...(c.failedStep !== undefined && { failedStep: c.failedStep }),
+                ...(c.summary !== undefined && { summary: c.summary }),
             },
         ];
     });
@@ -91,6 +92,8 @@ export function buildCooldownResult(prNumber, readyDelaySeconds) {
         status: "UNKNOWN",
         state: "UNKNOWN",
         mergeStateStatus: "UNKNOWN",
+        mergeStatus: "UNKNOWN",
+        reviewDecision: null,
         copilotReviewInProgress: false,
         isDraft: false,
         shouldCancel: false,

package/bin/commands/iterate/index.mjs

@@ -9,7 +9,6 @@ import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { buildWaitLog } from "./render.mjs";
 import { handleFixCode } from "./fix-code.mjs";
-import { buildRerunCiResult } from "./steps.mjs";
 export async function runIterate(opts) {
     const config = loadConfig();
     const cooldownSeconds = opts.cooldownSeconds ?? config.iterate.cooldownSeconds;
@@ -36,6 +35,8 @@ export async function runIterate(opts) {
             repo: report.repo,
             status: report.status,
             mergeStateStatus: report.mergeStatus.mergeStateStatus,
+            mergeStatus: report.mergeStatus.status,
+            reviewDecision: report.mergeStatus.reviewDecision,
             copilotReviewInProgress: report.mergeStatus.copilotReviewInProgress,
             isDraft: report.mergeStatus.isDraft,
             shouldCancel: true,
@@ -45,6 +46,7 @@ export async function runIterate(opts) {
             baseBranch: report.baseBranch,
             checks: buildRelevantChecks(report),
             action: "cancel",
+            reason: report.mergeStatus.state === "MERGED" ? "merged" : "closed",
             log: `CANCEL: PR #${report.pr} is ${state} — stopping monitor`,
         };
     }
@@ -60,6 +62,8 @@ export async function runIterate(opts) {
         status: report.status,
         state: report.mergeStatus.state,
         mergeStateStatus: report.mergeStatus.mergeStateStatus,
+        mergeStatus: report.mergeStatus.status,
+        reviewDecision: report.mergeStatus.reviewDecision,
         copilotReviewInProgress: report.mergeStatus.copilotReviewInProgress,
         isDraft: report.mergeStatus.isDraft,
         shouldCancel: readyState.shouldCancel,
@@ -69,23 +73,31 @@ export async function runIterate(opts) {
         checks: buildRelevantChecks(report),
     };
     if (readyState.shouldCancel) {
+        let cancelNote;
+        if (base.mergeStatus !== "BLOCKED")
+            cancelNote = "has been ready for review";
+        else if (base.reviewDecision === "REVIEW_REQUIRED")
+            cancelNote = "is awaiting human review";
+        else if (base.reviewDecision === "APPROVED")
+            cancelNote = "is awaiting additional approvals";
+        else
+            cancelNote = "is awaiting human review or branch protection resolution";
         return {
             ...base,
             action: "cancel",
-            log: `CANCEL: PR #${base.pr} has been ready for review — ready-delay elapsed, stopping monitor`,
+            reason: "ready-delay-elapsed",
+            log: `CANCEL: PR #${base.pr} ${cancelNote} — ready-delay elapsed, stopping monitor`,
         };
     }
     const headSha = (await getCurrentHeadSha()) ?? "unknown";
     const stallKey = { owner: repoOwner, repo: repoName, pr: prNumber };
-    const { minimizeIds: reviewSummaryIds, surfacedSummaries } = classifyReviewSummaries(report.reviewSummaries, report.approvedReviews, config.iterate.minimizeReviewSummaries);
-    const actionableChecks = report.checks.failing.filter((f) => f.failureKind === "actionable");
+    const { minimizeIds: reviewSummaryIds, surfacedApprovals } = classifyReviewSummaries(report.reviewSummaries, report.approvedReviews, config.iterate.minimizeApprovals);
     const hasActionableWork = report.threads.actionable.length > 0 ||
         report.comments.actionable.length > 0 ||
         report.changesRequestedReviews.length > 0 ||
-        actionableChecks.length > 0 ||
+        report.checks.failing.length > 0 ||
         report.mergeStatus.status === "CONFLICTS" ||
-        reviewSummaryIds.length > 0 ||
-        surfacedSummaries.length > 0;
+        reviewSummaryIds.length > 0;
     if (hasActionableWork) {
         return handleFixCode({
             base,
@@ -98,13 +110,9 @@ export async function runIterate(opts) {
             repoOwner,
             repoName,
             reviewSummaryIds,
-            surfacedSummaries,
+            surfacedApprovals,
         });
     }
-    const transientChecks = report.checks.failing.filter((f) => (f.failureKind === "timeout" || f.failureKind === "cancelled") && f.runId !== null);
-    if (transientChecks.length > 0) {
-        return buildRerunCiResult(transientChecks, base, prNumber, stallKey, stallTimeoutSeconds, headSha, report, reviewSummaryIds);
-    }
     const canMarkReady = report.status === "READY" &&
         report.mergeStatus.isDraft &&
         !report.mergeStatus.copilotReviewInProgress &&

package/bin/commands/iterate/render.mjs

@@ -28,22 +28,19 @@ export function renderResolveCommand(rc) {
     }
     return parts.join(" ");
 }
-export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount) {
+export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = []) {
     const instructions = [];
     if (threads.length > 0 || actionableComments.length > 0) {
         instructions.push(`Apply code fixes: read and edit each file referenced under \`## Review threads\` and \`## Actionable comments\` above.`);
     }
-    // Mirror the truthiness checks in `formatIterateResult` (cli/iterate-formatter.mts) so each
-    // AgentCheck maps to the same bullet shape here as there: runId → runId
-    // bullet, else detailsUrl → external bullet, else `(no runId)` bullet.
     const checksWithRunId = checks.filter((c) => c.runId);
     const externalChecks = checks.filter((c) => !c.runId && c.detailsUrl);
     const bareChecks = checks.filter((c) => !c.runId && !c.detailsUrl);
     if (checksWithRunId.length > 0) {
-        instructions.push(`For each bullet in \`## Failing checks\` whose backticked locator is a numeric runId (GitHub Actions): run \`gh run view <runId> --log-failed\`, identify the failure, and apply the fix.`);
+        instructions.push(`For each failing check under \`## Failing checks\` with a run ID: examine the log tail shown in the fenced block when available (or run \`gh run view <runId> --log-failed\` if the block is absent) to decide what to do. If the logs show a transient runner or infrastructure failure (e.g. network timeout, runner setup crash, OOM kill), run \`gh run rerun <runId> --failed\` and stop this iteration — CI will re-run automatically. If the logs show a real test or build failure, apply a code fix.`);
     }
     if (externalChecks.length > 0) {
-        instructions.push(`For each bullet in \`## Failing checks\` starting with \`external\` (external status check): open the linked URL in a browser to inspect the failure — \`gh run view\` cannot fetch logs for external checks.`);
+        instructions.push(`For each bullet in \`## Failing checks\` starting with \`external\` (external status check): open the linked URL in a browser to inspect the failure — log tails are not available for external checks.`);
     }
     if (bareChecks.length > 0) {
         instructions.push(`For each bullet in \`## Failing checks\` starting with \`(no runId)\`: there is no run or details URL to inspect. Escalate these to a human — they require manual investigation outside the pr-shepherd flow.`);
@@ -84,6 +81,13 @@ export function buildFixInstructions(threads, actionableComments, checks, review
     if (needsPush && cancelledCount > 0) {
         instructions.push(`Do not re-run \`gh run cancel\` on the IDs listed under \`## Cancelled runs\` — the CLI cancelled those runs before your push, and your push has already triggered new runs with different IDs.`);
     }
+    const firstLookTotal = firstLookThreads.length + firstLookComments.length;
+    if (firstLookTotal > 0) {
+        instructions.push(`Items in \`## First-look items\` are for acknowledgement only — do not pass their IDs to \`--resolve-thread-ids\`, \`--minimize-comment-ids\`, or \`--dismiss-review-ids\`. Acknowledge each one with a one-line classification (e.g. "outdated — addressed by commit abc1234", "resolved — already fixed", "minimized — noise").`);
+    }
+    if (resolveCommand.hasMutations) {
+        instructions.push(`For any large decisions or rejections you made this iteration, add or update a \`## Shepherd Journal\` section in the PR description (\`gh pr edit ${prNumber} --body …\`) summarizing each decision. For threads and comments, use the markdown link shown in its heading above; for reviews, reference the review ID.`);
+    }
     if (needsPush) {
         instructions.push(`Stop this iteration — CI needs time to run on the new push before the next tick.`);
     }
@@ -96,15 +100,20 @@ export function buildFixInstructions(threads, actionableComments, checks, review
     return instructions;
 }
 export function buildWaitLog(base) {
-    const { summary, mergeStateStatus, remainingSeconds } = base;
+    const { summary, remainingSeconds } = base;
     const parts = [`WAIT: ${summary.passing} passing, ${summary.inProgress} in-progress`];
-    switch (mergeStateStatus) {
+    switch (base.mergeStatus) {
+        case "BLOCKED":
+            if (base.reviewDecision === "REVIEW_REQUIRED")
+                parts.push("awaiting human review");
+            else if (base.reviewDecision === "APPROVED")
+                parts.push("awaiting additional approvals");
+            else
+                parts.push("awaiting human review or branch protection");
+            break;
         case "BEHIND":
             parts.push("branch is behind base");
             break;
-        case "BLOCKED":
-            parts.push("blocked by pending reviews or required status checks");
-            break;
         case "DRAFT":
             parts.push("PR is a draft");
             break;

package/bin/commands/iterate/stall.mjs

@@ -3,7 +3,7 @@ import { toAgentThread, toAgentComment } from "../../reporters/agent.mjs";
 import { buildEscalateSuggestion, buildEscalateHumanMessage } from "./escalate.mjs";
 export function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds) {
     const checks = [
-        ...report.checks.failing.map((f) => `failing:${f.name}:${f.failureKind ?? ""}`),
+        ...report.checks.failing.map((f) => `failing:${f.name}:${f.conclusion}`),
         ...report.checks.inProgress.map((p) => `inProgress:${p.name}`),
     ].sort();
     const threads = report.threads.actionable.map((t) => t.id).sort();

package/bin/commands/resolve-instructions.mjs

@@ -4,13 +4,15 @@
  * `buildFixInstructions` in `commands/iterate/render.mts`).
  */
 export function buildFetchInstructions(prNumber, result) {
-    const { actionableThreads, actionableComments, changesRequestedReviews, reviewSummaries, commitSuggestionsEnabled, } = result;
+    const { actionableThreads, firstLookThreads, actionableComments, firstLookComments, changesRequestedReviews, reviewSummaries, commitSuggestionsEnabled, } = result;
+    const firstLookTotal = firstLookThreads.length + firstLookComments.length;
     const total = actionableThreads.length +
         actionableComments.length +
         changesRequestedReviews.length +
-        reviewSummaries.length;
+        reviewSummaries.length +
+        firstLookTotal;
     if (total === 0) {
-        return ["No actionable items — end this invocation."];
+        return ["No actionable items and no first-look items — end this invocation."];
     }
     const hasCodeItems = actionableThreads.length > 0 ||
         actionableComments.length > 0 ||
@@ -18,6 +20,9 @@ export function buildFetchInstructions(prNumber, result) {
     const hasSuggestions = commitSuggestionsEnabled && actionableThreads.some((t) => t.suggestion != null);
     const instructions = [];
     instructions.push(`Classify every item listed above into exactly one of: Fixed / Actionable / Not relevant / Outdated / Acknowledge. Do not silently skip any item. Bot-authored review summaries (authors whose name contains \`[bot]\` or matches \`copilot-pull-request-reviewer\`, \`gemini-code-assist\`) default to Acknowledge with reason "bot summary — no actionable content" unless the body calls out an unaddressed issue.`);
+    if (firstLookTotal > 0) {
+        instructions.push(`Items in \`## First-look items\` are for acknowledgement only — do not pass their IDs to \`--resolve-thread-ids\`, \`--minimize-comment-ids\`, or \`--dismiss-review-ids\`. Acknowledge each one with a one-line classification (e.g. "outdated — addressed by commit abc1234", "resolved — already fixed", "minimized — noise").`);
+    }
     if (hasSuggestions) {
         instructions.push(`For each Actionable thread marked \`[suggestion]\` in \`## Actionable Review Threads\` above: run \`npx pr-shepherd commit-suggestion ${prNumber} --thread-id <id> --message "<one-sentence headline>" --format=json\`, one thread at a time. On \`applied: true\` mark it Fixed — the CLI already resolved the thread, so exclude the ID from \`--resolve-thread-ids\`. On \`applied: false\` read \`reason\` and \`patch\`, then fall through to the manual fix step — do not retry the same command. Optionally pass \`--dry-run\` (omitting \`--message\`) if you want to inspect the unified diff before it mutates the working tree — the CLI validates with \`git apply --check\`, returns the patch and \`valid: true/false\`, and exits \`1\` on drift without committing or resolving the thread.`);
     }
@@ -34,6 +39,7 @@ export function buildFetchInstructions(prNumber, result) {
             ? ` Review-summary IDs (\`PRR_…\` from \`## Review summaries\`) go into \`--minimize-comment-ids\`.`
             : "";
     instructions.push(`Run \`npx pr-shepherd resolve ${prNumber} [--resolve-thread-ids <ids>] [--minimize-comment-ids <ids>] [--dismiss-review-ids <ids> --message "<reason>"]\` with only the non-empty flag subsets. Skip the command entirely if all three ID lists are empty.${requireShaHint}${dismissNote}`);
+    instructions.push(`For any large decisions or rejections you made this iteration, add or update a \`## Shepherd Journal\` section in the PR description (\`gh pr edit ${prNumber} --body …\`) summarizing each decision. For threads and comments, use the markdown link shown in each item's bullet above; for reviews, reference the review ID.`);
     instructions.push(`Report: echo the CLI's mutation output, then one line per Acknowledged item: \`Acknowledged <id> (@<author>): <reason>\`. If any fetched item was neither resolved nor acknowledged, stop and escalate: "<N> item(s) fetched but not acted on or acknowledged — need human direction before closing".`);
     return instructions;
 }