pr-shepherd 0.55.1 → 0.56.0

package/bin/cli/help.d.mts

@@ -212,7 +212,7 @@ Flags:
 
 PR may be a number or GitHub pull request URL. When omitted, the current branch PR is inferred.
 Exit code: 0 on success; nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
-    readonly iterate: "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  READY       Clean PR is inside the ready-delay. Wait out remainingSeconds, then poll again.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n  MERGE       Run the emitted merge/queue command, then continue monitoring.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT or READY\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+    readonly iterate: "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  READY       Clean PR is inside the ready-delay. Schedule the rerun for when remainingSeconds elapses. Do not invent unrelated work. Already-owned later work may continue.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n  MERGE       Run the emitted merge/queue command, then continue monitoring.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT or READY\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
     readonly poll: "pr-shepherd poll\n\nRun iterate repeatedly for one PR, or read compact summaries for an explicit PR set or native\nGitHub stack. Aggregate mode returns when any row needs work, every row is terminal, or timeout.\nPoll exits as soon as iterate returns READY, MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default:\npoll.debounceSeconds; built-in 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal or --merge, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR ...] [poll-flags] [iterate-flags]\n  pr-shepherd poll --stack PR [poll-flags] [iterate-flags]\n\nPoll flags:\n  --stack PR                    Select all entries in PR's native GitHub stack, bottom to top.\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stackIntervalFactor (built-in 2) unless this flag is set.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until READY/FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes a stderr line naming what it is waiting on by default; poll.quietStatus can change that default, --quiet-status/--no-quiet-status override it, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until READY, FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT or READY (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
     readonly clean: `pr-shepherd clean
 

package/bin/cli/iterate-checks-formatter.mjs

@@ -1,3 +1,4 @@
+import { renderRelatedJobLines } from "./related-jobs-format.mjs";
 import { renderCheckAnnotation } from "./fix-formatter-extra.mjs";
 export function formatRelevantChecks(checks) {
     if (checks.length === 0)
@@ -14,6 +15,7 @@ function formatRelevantCheck(check) {
     const lines = [`- \`${workflow}${job}\` [conclusion: ${check.conclusion}]`];
     appendCheckFields(lines, check);
     appendLogExcerpt(lines, check.logExcerpt);
+    lines.push(...renderRelatedJobLines(check.relatedJobs));
     appendAnnotations(lines, check.annotations, check.logExcerpt);
     return lines;
 }

package/bin/cli/iterate-instructions.mjs

@@ -7,7 +7,7 @@ import { buildPrShepherdCommand } from "./runner.mjs";
 export function buildSimpleIterateInstructions(result) {
     switch (result.action) {
         case "ready": {
-            const sentence = `PR #${result.pr} is ready. Ready-delay has ${result.remainingSeconds}s left. Run this same command again when the timer elapses. Do not start other work.`;
+            const sentence = `PR #${result.pr} is ready. Ready-delay has ${result.remainingSeconds}s left. Rerun this command when the timer elapses. Do not invent unrelated work.`;
             return [
                 result.quotaWarning ? buildQuotaAwareContinuation(result.quotaWarning, sentence) : sentence,
             ];

package/bin/cli/related-jobs-format.d.mts

@@ -0,0 +1,3 @@
+import type { RelatedFailedJob } from "../types/check-classification.mts";
+/** Shared text rendering of sibling failed jobs under a failing check bullet. */
+export declare function renderRelatedJobLines(jobs: RelatedFailedJob[] | undefined, indent?: string): string[];

package/bin/cli/related-jobs-format.mjs

@@ -0,0 +1,16 @@
+/** Shared text rendering of sibling failed jobs under a failing check bullet. */
+export function renderRelatedJobLines(jobs, indent = "  ") {
+    if (!jobs || jobs.length === 0)
+        return [];
+    const lines = [`${indent}Other failed jobs in this run:`];
+    for (const job of jobs) {
+        lines.push(`${indent}- \`${job.name}\` [conclusion: ${job.conclusion}]`);
+        if (job.failedStep)
+            lines.push(`${indent}  > failed step: ${job.failedStep}`);
+        if (job.logExcerpt) {
+            for (const line of job.logExcerpt.split("\n"))
+                lines.push(`${indent}  > ${line}`);
+        }
+    }
+    return lines;
+}

package/bin/commands/check-execution-context.d.mts

@@ -0,0 +1,12 @@
+import type { RepoInfo } from "../github/client.mts";
+import { readStackTopology } from "../github/stack-read.mts";
+import type { RawSummaryPr } from "../github/poll-summary-raw.mts";
+/** Fresh for each iterate tick; never persisted or exposed in CLI output. */
+export declare function createCheckExecutionContext(readyDelaySeconds?: number): {
+    readStackTopology(pr: number, repo: RepoInfo): ReturnType<typeof readStackTopology>;
+    wantsReceiptSummary(pr: number, repo: RepoInfo): Promise<boolean>;
+    setReceiptSummary(raw: RawSummaryPr | null): void;
+    getReceiptSummary(): RawSummaryPr | null;
+    invalidateReceiptSummary(): void;
+};
+export type CheckExecutionContext = ReturnType<typeof createCheckExecutionContext>;

package/bin/commands/check-execution-context.mjs

@@ -0,0 +1,38 @@
+import { readStackTopology } from "../github/stack-read.mjs";
+import { readReadyReceipt } from "../state/ready-receipts.mjs";
+import { readyDelayElapsed } from "./ready-delay.mjs";
+/** Fresh for each iterate tick; never persisted or exposed in CLI output. */
+export function createCheckExecutionContext(readyDelaySeconds) {
+    const topologies = new Map();
+    let receiptSummary = null;
+    let receiptSummaryInvalidated = false;
+    return {
+        readStackTopology(pr, repo) {
+            const key = `${repo.owner.toLowerCase()}/${repo.name.toLowerCase()}#${pr}`;
+            let pending = topologies.get(key);
+            if (!pending) {
+                pending = readStackTopology(pr, repo);
+                topologies.set(key, pending);
+            }
+            return pending;
+        },
+        async wantsReceiptSummary(pr, repo) {
+            if (readyDelaySeconds === undefined)
+                return false;
+            const key = { owner: repo.owner, repo: repo.name, pr };
+            if (await readReadyReceipt(key))
+                return true;
+            return readyDelayElapsed(pr, repo.owner, repo.name, readyDelaySeconds);
+        },
+        setReceiptSummary(raw) {
+            receiptSummary = raw;
+        },
+        getReceiptSummary() {
+            return receiptSummaryInvalidated ? null : receiptSummary;
+        },
+        invalidateReceiptSummary() {
+            receiptSummaryInvalidated = true;
+            receiptSummary = null;
+        },
+    };
+}

package/bin/commands/check-fingerprint.mjs

@@ -31,20 +31,26 @@ export async function tryReuseFingerprintReport(prNumber, repo, stateKey, config
     }
     if (!reportAllowsFingerprintSkip(cached.report))
         return null;
-    const live = await fetchPrFingerprint(prNumber, repo);
-    if (live.isInMergeQueue || cached.fingerprint.isInMergeQueue)
+    if (cached.fingerprint.isInMergeQueue)
+        return null;
+    if (!cached.fingerprint.checkSuitesComplete)
+        return null;
+    if (cached.fingerprint.commentCount > 100)
         return null;
-    if (!live.checkSuitesComplete || !cached.fingerprint.checkSuitesComplete)
+    if (cached.fingerprint.reviewCount > 100)
         return null;
-    if (live.commentCount > 100 || cached.fingerprint.commentCount > 100)
+    if (cached.fingerprint.threadCount > 20)
         return null;
-    if (live.reviewCount > 100 || cached.fingerprint.reviewCount > 100)
+    if (cached.fingerprint.hasMultiCommentThreads)
         return null;
-    if (live.threadCount > 20 || cached.fingerprint.threadCount > 20)
+    if (!cached.fingerprint.rulesComplete)
+        return null;
+    const live = await fetchPrFingerprint(prNumber, repo);
+    if (live.isInMergeQueue || !live.checkSuitesComplete)
         return null;
-    if (live.hasMultiCommentThreads || cached.fingerprint.hasMultiCommentThreads)
+    if (live.commentCount > 100 || live.reviewCount > 100 || live.threadCount > 20)
         return null;
-    if (!live.rulesComplete || !cached.fingerprint.rulesComplete)
+    if (live.hasMultiCommentThreads || !live.rulesComplete)
         return null;
     if (!fingerprintsEqual(cached.fingerprint, live))
         return null;

package/bin/commands/check-unreported.d.mts

@@ -1,6 +1,7 @@
 import { type WorkflowSuiteSnapshot } from "../checks/unreported-required.mts";
 import type { BatchPrData, CheckRun, ShepherdReport } from "../types.mts";
 import type { RepoInfo } from "../github/client.mts";
+import type { CheckExecutionContext } from "./check-execution-context.mts";
 export interface UnreportedRequiredFields {
     unreportedRequiredChecks?: string[];
     trunkBehindBy?: number;
@@ -20,9 +21,9 @@ export declare function collectUnreportedRequired(input: {
     name: string;
     pr: number;
     relevantEvents: readonly string[];
-}): Promise<UnreportedRequiredFields>;
+}, context?: CheckExecutionContext): Promise<UnreportedRequiredFields>;
 /**
  * A fingerprint hit can keep a stale trunk `behindBy`. Refresh the trunk compare
  * and the required-context diff without refetching the whole batch.
  */
-export declare function refreshCachedUnreported(report: ShepherdReport, repo: RepoInfo): Promise<ShepherdReport>;
+export declare function refreshCachedUnreported(report: ShepherdReport, repo: RepoInfo, context?: CheckExecutionContext): Promise<ShepherdReport>;

package/bin/commands/check-unreported.mjs

@@ -1,7 +1,7 @@
 import { actionsWorkflowInProgress, reportedCheckNames, unreportedRequiredContexts, } from "../checks/unreported-required.mjs";
 import { loadBaseBehindBy, loadMergeTargetStatus } from "../github/merge-target-rules.mjs";
 /** Load trunk rules for a stack and diff them against the head's check names. */
-export async function collectUnreportedRequired(input) {
+export async function collectUnreportedRequired(input, context) {
     const localContexts = input.batchData.branchRules?.requiredStatusCheckContexts ??
         input.batchData.branchProtection?.requiredStatusCheckContexts ??
         [];
@@ -13,7 +13,7 @@ export async function collectUnreportedRequired(input) {
         headRefName: input.batchData.headRefName,
         localContexts,
         stack: input.batchData.stack,
-    });
+    }, context);
     const unreported = unreportedRequiredContexts(target.contexts, reportedCheckNames(input.checks));
     const actionsRunning = actionsWorkflowInProgress(input.suites, new Set(input.relevantEvents));
     const baseBehindBy = unreported.length > 0 && !input.batchData.stack
@@ -34,7 +34,7 @@ export async function collectUnreportedRequired(input) {
  * A fingerprint hit can keep a stale trunk `behindBy`. Refresh the trunk compare
  * and the required-context diff without refetching the whole batch.
  */
-export async function refreshCachedUnreported(report, repo) {
+export async function refreshCachedUnreported(report, repo, context) {
     const stack = report.mergeStatus?.mergeRequirements?.stack;
     if (!report.headRefName)
         return report;
@@ -48,7 +48,7 @@ export async function refreshCachedUnreported(report, repo) {
         headRefName: report.headRefName,
         localContexts: report.mergeStatus.mergeRequirements?.requiredStatusChecks?.contexts ?? [],
         stack,
-    });
+    }, context);
     const unreported = unreportedRequiredContexts(target.contexts, reportedCheckNames(reportChecks(report)));
     const next = { ...report };
     if (unreported.length > 0)

package/bin/commands/check.d.mts

@@ -1,3 +1,4 @@
+import type { CheckExecutionContext } from "./check-execution-context.mts";
 import type { GlobalOptions, ShepherdReport } from "../types.mts";
 export declare function runCheck(opts: GlobalOptions & {
     autoResolve?: boolean;
@@ -6,4 +7,4 @@ export declare function runCheck(opts: GlobalOptions & {
     persistSeen?: boolean;
     fingerprintCache?: boolean;
     merge?: boolean;
-}): Promise<ShepherdReport>;
+}, context?: CheckExecutionContext): Promise<ShepherdReport>;

package/bin/commands/check.mjs

@@ -7,6 +7,7 @@ import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
 import { classifyChecks, getCiVerdict } from "../checks/classify.mjs";
 import { mergeStartupFailureChecks } from "../checks/startup-failures.mjs";
 import { fetchStartupFailureChecks, triageFailingChecks } from "../checks/triage.mjs";
+import { TriageBudget } from "../checks/triage-budget.mjs";
 import { deriveMergeStatus } from "../merge-status/derive.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { classifyVisibleComments } from "../comments/visible-comments.mjs";
@@ -26,7 +27,7 @@ import { discoverRuleFiles, loadRules } from "../classify/loader.mjs";
 import { buildClassifyIndex, partitionBatch } from "../classify/apply.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { getEffectiveCwd } from "../execution-context.mjs";
-export async function runCheck(opts) {
+export async function runCheck(opts, context) {
     const repo = opts.targetRepository ?? (await getRepoInfo());
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
     if (prNumber === null) {
@@ -38,10 +39,15 @@ export async function runCheck(opts) {
     if (reuseFingerprint) {
         const cached = await tryReuseFingerprintReport(prNumber, repo, stateKey, config);
         if (cached)
-            return refreshCachedUnreported(cached, repo);
+            return refreshCachedUnreported(cached, repo, context);
     }
     const paginateApprovedReviews = config.iterate.minimizeApprovals;
-    const result = await fetchPrBatch(prNumber, repo, { paginateApprovedReviews });
+    const includeReceiptSummary = (await context?.wantsReceiptSummary(prNumber, repo)) ?? false;
+    const result = await fetchPrBatch(prNumber, repo, {
+        paginateApprovedReviews,
+        ...(includeReceiptSummary && { includeReceiptSummary: true }),
+    });
+    context?.setReceiptSummary(result.receiptSummary ?? null);
     let batchData = result.data;
     const unknownRefresh = await refreshUnknownMergeability(prNumber, repo, batchData);
     batchData = unknownRefresh.batchData;
@@ -55,9 +61,10 @@ export async function runCheck(opts) {
         return terminal;
     }
     const startupFailuresNeedAttempt = batchData.checks.some((check) => check.source === "startup_failure" && check.runAttempt === undefined);
+    const triageBudget = new TriageBudget();
     const startupFailureChecks = result.checkSuitesComplete && !startupFailuresNeedAttempt
         ? []
-        : await fetchStartupFailureChecks(repo, batchData.headRefOid, prNumber, stateKey);
+        : await fetchStartupFailureChecks(repo, batchData.headRefOid, prNumber, stateKey, triageBudget);
     const allChecks = mergeStartupFailureChecks(batchData.checks, startupFailureChecks);
     const classifiedPrChecks = classifyChecks(allChecks);
     const latestRemoval = batchData.latestMergeQueueRemoval;
@@ -103,8 +110,10 @@ export async function runCheck(opts) {
     const filtered = classifiedChecks.filter((c) => c.category === "filtered");
     const ignored = classifiedChecks.filter((c) => c.category === "ignored");
     const triagedBase = failing.length > 0 && !opts.skipTriage
-        ? await triageFailingChecks(failing, repo, stateKey)
+        ? await triageFailingChecks(failing, repo, stateKey, triageBudget, classifiedChecks.filter((c) => c.category !== "failing"))
         : failing;
+    triageBudget.throwIfSecondary();
+    triageBudget.reportOmissionIfNeeded();
     const seenMap = await loadSeenMap(stateKey);
     const botUsernames = normalizeBotUsernames(config.botUsernames);
     const ruleSet = await loadRules(discoverRuleFiles(getEffectiveCwd()));
@@ -168,7 +177,7 @@ export async function runCheck(opts) {
         name: repo.name,
         pr: prNumber,
         relevantEvents: config.checks.ciTriggerEvents,
-    });
+    }, context);
     let status = computeStatus(verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, mergeStatus, changesRequestedReviewCount, unreported.hasUnreportedRequired);
     // Resolve any pending mergeability refresh (and the resulting MERGED/CLOSED short-circuit)
     // before deciding what to persist below — deferWhileQueued must see the same final,
@@ -251,6 +260,12 @@ export async function runCheck(opts) {
         ruleAutoResolveCommentIds: partition.ruleAutoResolveCommentIds.filter((id) => batchData.comments.find((comment) => comment.id === id)?.viewerCanMinimize === true),
         ruleAutoResolveReviewSummaryIds: partition.ruleAutoResolveReviewSummaryIds.filter((id) => batchData.reviewSummaries.find((review) => review.id === id)?.viewerCanMinimize === true),
     };
+    if (opts.autoMinimizeSuppressed === true &&
+        (authorizedPartition.ruleAutoResolveThreadIds.length > 0 ||
+            authorizedPartition.ruleAutoResolveCommentIds.length > 0 ||
+            authorizedPartition.ruleAutoResolveReviewSummaryIds.length > 0)) {
+        context?.invalidateReceiptSummary();
+    }
     const { threadIds: authorizedRuleAutoResolveThreadIds, commentIds: ruleAutoResolveCommentIds, reviewSummaryIds: ruleAutoResolveReviewSummaryIds, autoResolved, autoMinimized, autoResolveErrors, errorReasons, } = await applySuppressedRuleAutoResolve({
         enabled: opts.autoMinimizeSuppressed === true,
         partition: authorizedPartition,

package/bin/commands/commit-suggestion-instruction.mjs

@@ -1,4 +1,5 @@
 import { buildPrShepherdCommand } from "../cli/runner.mjs";
+import { playbookPointer } from "./playbook-pointer.mjs";
 /**
  * Build the `build-suggestion-patches` instruction step for agent consumers.
  * Currently emitted by iterate `fix_code` for suggestion review threads. The CLI keeps
@@ -19,5 +20,5 @@ export function buildCommitSuggestionInstruction(prReference, sectionName) {
         "<one-sentence headline>",
         "--format=json",
     ]).text;
-    return `For all threads marked \`[suggestion]\` under \`${sectionName}\`, run one \`${command}\` command, repeating the \`--thread-id <id> --message <one-sentence headline>\` group in displayed order, then apply the returned patches in order. See "Suggestion patches" in the pr-shepherd skill for refusals and drift.`;
+    return `For every \`[suggestion]\` thread under \`${sectionName}\`, run one \`${command}\`, repeating \`--thread-id\` and \`--message\` in displayed order. ${playbookPointer("Suggestion patches")}`;
 }

package/bin/commands/iterate/check-instructions.d.mts

@@ -2,15 +2,18 @@ import type { AgentCheck, ResolveCommand, Review } from "../../types.mts";
 /** Build the stale-CR clause appended to the `## Changes-requested reviews` instruction. */
 export declare function buildCrStaleClause(reviews: Review[]): string;
 /**
- * Build the optional behind-base push hint. Empty unless the branch is actually behind its base
- * and the user configured a non-blank `iterate.behindBaseHint` — the CLI never prescribes
+ * Build the optional branch-update hint. Empty unless the branch is behind or conflicts with its
+ * base and the user configured a non-blank `iterate.behindBaseHint` — the CLI never prescribes
  * rebase/merge mechanics itself (see "Keep skills and loop prompts minimal" in AGENTS.md); this
  * only echoes back the caller's own configured pointer. `hint` is trimmed and type-checked at the
  * point of use (rather than at config load) so a malformed rc file value (non-string, or
  * whitespace-only) degrades to "no hint" instead of rendering garbage into agent-facing text or
  * discarding the rest of the user's config.
  */
-export declare function buildBehindBaseHintInstruction(baseBranch: string, hint: string, isBehind: boolean): string[];
+export declare function buildBehindBaseHintInstruction(baseBranch: string, hint: string, branch: {
+    isBehind: boolean;
+    hasConflicts: boolean;
+}): string[];
 /**
  * Give one branch-refresh recovery path after Shepherd's single workflow rerun has failed.
  * The fetched PR base branch is raw context; the caller still owns repository-specific git
@@ -31,8 +34,9 @@ export declare function buildRepeatedWorkflowBranchRecoveryInstructions(baseBran
  * tells the agent that playbook exists.
  */
 export declare function buildResolveCommandInstruction(resolveCommand: ResolveCommand): string[];
-/** Build the CI-triage pointer; the skill limits follow-up actions to included evidence. */
+/** One pointer. Conclusion, rerun, and bare-check rules live in the CI playbook. */
 export declare function buildFailingCheckInstructions(checks: AgentCheck[]): string[];
 /** Update the PR branch after an external blocker merges or closes. Never rerun that job. */
 export declare function buildReleasedBlockerInstruction(prNumber: number): string;
-export declare function buildFixCompletionInstruction(checks: AgentCheck[], hasConflicts?: boolean, hasShaGatedReviewMutations?: boolean, pushesRewrittenStack?: boolean): string;
+/** Recurrence only. Commit, push, rerun, and SHA steps are earlier instructions. */
+export declare function buildFixCompletionInstruction(): string;

package/bin/commands/iterate/check-instructions.mjs

@@ -1,3 +1,5 @@
+import { playbookPointer } from "../playbook-pointer.mjs";
+const FIX_CODE_CONTINUATION = "`[FIX_CODE]` is non-terminal. Iterate immediately with the same options.";
 /** Build the stale-CR clause appended to the `## Changes-requested reviews` instruction. */
 export function buildCrStaleClause(reviews) {
     const human = reviews.some((r) => r.staleReview && !r.staleBotCr)
@@ -6,19 +8,20 @@ export function buildCrStaleClause(reviews) {
     return human;
 }
 /**
- * Build the optional behind-base push hint. Empty unless the branch is actually behind its base
- * and the user configured a non-blank `iterate.behindBaseHint` — the CLI never prescribes
+ * Build the optional branch-update hint. Empty unless the branch is behind or conflicts with its
+ * base and the user configured a non-blank `iterate.behindBaseHint` — the CLI never prescribes
  * rebase/merge mechanics itself (see "Keep skills and loop prompts minimal" in AGENTS.md); this
  * only echoes back the caller's own configured pointer. `hint` is trimmed and type-checked at the
  * point of use (rather than at config load) so a malformed rc file value (non-string, or
  * whitespace-only) degrades to "no hint" instead of rendering garbage into agent-facing text or
  * discarding the rest of the user's config.
  */
-export function buildBehindBaseHintInstruction(baseBranch, hint, isBehind) {
+export function buildBehindBaseHintInstruction(baseBranch, hint, branch) {
     const trimmedHint = typeof hint === "string" ? hint.trim() : "";
-    if (!isBehind || trimmedHint === "")
+    if ((!branch.isBehind && !branch.hasConflicts) || trimmedHint === "")
         return [];
-    return [`The branch is behind PR base branch \`${baseBranch}\`. ${trimmedHint} before pushing.`];
+    const state = branch.hasConflicts ? "conflicts with" : "is behind";
+    return [`The branch ${state} PR base branch \`${baseBranch}\`. ${trimmedHint} before pushing.`];
 }
 /**
  * Give one branch-refresh recovery path after Shepherd's single workflow rerun has failed.
@@ -53,48 +56,25 @@ export function buildResolveCommandInstruction(resolveCommand) {
         return [];
     const instructions = [];
     if (resolveCommand.requiresHeadSha) {
-        instructions.push("If you did not change code, replace `$HEAD_SHA` with `$(git rev-parse HEAD)`, which must equal the current remote PR head. If you changed code, commit and push to the PR head branch first, then replace `$HEAD_SHA` with the pushed commit SHA.");
+        instructions.push("If you did not change code, replace `$HEAD_SHA` with `$(git rev-parse HEAD)` (it must equal the remote PR head). If you did, use the pushed SHA.");
     }
     if (resolveCommand.requiresDismissMessage) {
         instructions.push("Replace `$DISMISS_MESSAGE` with one sentence describing what changed.");
     }
-    instructions.push('Run the `apply review:` command shown above. See "Review-mutation mechanics" in the pr-shepherd skill for dismiss-ID retention.');
+    instructions.push(`Run the \`apply review:\` command above. ${playbookPointer("Review-mutation mechanics")}`);
     return instructions;
 }
-/** Build the CI-triage pointer; the skill limits follow-up actions to included evidence. */
+/** One pointer. Conclusion, rerun, and bare-check rules live in the CI playbook. */
 export function buildFailingCheckInstructions(checks) {
     if (checks.length === 0)
         return [];
-    const hasBare = checks.some((c) => !c.runId && !c.detailsUrl);
-    const hasTriageable = checks.some((c) => c.runId || c.detailsUrl);
-    const hasRerunAuthorized = checks.some((c) => c.rerunCommand);
-    const instructions = [];
-    if (hasTriageable) {
-        instructions.push('Triage every failure under `## Failing checks`. See "CI failure triage" in the pr-shepherd skill for read-only inspection rules.');
-    }
-    if (hasRerunAuthorized) {
-        instructions.push('A `[rerun authorized]` check includes a `rerun:` command. See "CI failure triage" in the pr-shepherd skill for which conclusions warrant a rerun versus a code fix.');
-    }
-    if (hasBare) {
-        instructions.push("For each `(no runId)` failure, preserve the displayed metadata; Shepherd will escalate when no other autonomous work remains.");
-    }
-    return instructions;
+    return [`Triage \`## Failing checks\`. ${playbookPointer("CI failure triage")}`];
 }
 /** Update the PR branch after an external blocker merges or closes. Never rerun that job. */
 export function buildReleasedBlockerInstruction(prNumber) {
     return `Update this PR branch from its base with \`gh pr update-branch ${prNumber} --rebase\`. Do not rerun the job; a rerun retests the old merge ref.`;
 }
-export function buildFixCompletionInstruction(checks, hasConflicts = false, hasShaGatedReviewMutations = false, pushesRewrittenStack = false) {
-    const push = pushesRewrittenStack
-        ? "push the rewritten stack with `gh stack push`"
-        : "push to the PR head branch";
-    if (hasConflicts)
-        return `\`[FIX_CODE]\` is non-terminal: resolve the conflicts, commit, ${push}, then iterate immediately with the same options.`;
-    if (hasShaGatedReviewMutations) {
-        return `\`[FIX_CODE]\` is non-terminal: if you changed code, commit and ${push}, then run the review mutations using the pushed commit SHA and iterate immediately with the same options; if you did not change code, complete the authorized review mutations and iterate immediately with the same options.`;
-    }
-    if (checks.some((check) => check.rerunCommand)) {
-        return "`[FIX_CODE]` is non-terminal. Run any warranted reruns for `[rerun authorized]` checks (or apply code fixes for real failures), then iterate immediately with the same options to continue.";
-    }
-    return "`[FIX_CODE]` is non-terminal. After completing these steps, iterate immediately with the same options to continue.";
+/** Recurrence only. Commit, push, rerun, and SHA steps are earlier instructions. */
+export function buildFixCompletionInstruction() {
+    return FIX_CODE_CONTINUATION;
 }

package/bin/commands/iterate/escalate.mjs

@@ -1,3 +1,5 @@
+/* eslint-disable max-lines */
+import { renderRelatedJobLines } from "../../cli/related-jobs-format.mjs";
 import { loadConfig } from "../../config/load.mjs";
 import { renderResolveCommand } from "./render.mjs";
 function renderEscalateAuthor(item) {
@@ -52,6 +54,7 @@ function renderEscalateCheck(check) {
         lines.push(`  > ${check.summary}`);
     if (check.logExcerpt)
         lines.push(...renderBlockquoteLines(check.logExcerpt, "  "));
+    lines.push(...renderRelatedJobLines(check.relatedJobs));
     if (check.rerunCommand)
         lines.push(`  rerun: \`${check.rerunCommand}\``);
     for (const annotation of check.annotations ?? []) {

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

@@ -19,6 +19,10 @@ import { canRerunWorkflows } from "../../checks/conclusions.mjs";
 import { loadConfig } from "../../config/load.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
 const EMPTY_RELEASED = new Set();
+function hasLogEvidence(check) {
+    return (Boolean(check.logExcerpt?.trim()) ||
+        (check.relatedJobs ?? []).some((job) => Boolean(job.logExcerpt?.trim())));
+}
 function checkRequiresHumanFollowUp(check) {
     if (check.rerunCommand)
         return false;
@@ -30,13 +34,13 @@ function checkRequiresHumanFollowUp(check) {
     // identify a code or configuration fix for the agent. Only a later failure with
     // no actionable evidence needs a human handoff.
     if (check.runAttempt !== undefined && check.runAttempt > 1)
-        return !check.logExcerpt?.trim();
+        return !hasLogEvidence(check);
     // An external check's direct URL is actionable evidence: the agent can inspect the
     // provider and/or reproduce the reported failure locally. Only a truly bare check
     // has no autonomous investigation path.
     if (check.runId === null)
         return !check.detailsUrl?.trim();
-    return !check.logExcerpt?.trim();
+    return !hasLogEvidence(check);
 }
 function nextFixAttempts(stored, threads, countAttempt) {
     const threadAttempts = stored ? { ...stored.threadAttempts } : {};

package/bin/commands/iterate/helpers.mjs

@@ -80,6 +80,7 @@ export function buildRelevantChecks(report) {
                 ...(c.failedStep !== undefined && { failedStep: c.failedStep }),
                 ...(c.summary !== undefined && { summary: c.summary }),
                 ...(c.logExcerpt !== undefined && { logExcerpt: c.logExcerpt }),
+                ...(c.relatedJobs !== undefined && { relatedJobs: c.relatedJobs }),
                 ...(c.annotations !== undefined && { annotations: c.annotations }),
                 ...(c.scope !== undefined && { scope: c.scope }),
                 ...(c.commitOid !== undefined && { commitOid: c.commitOid }),

package/bin/commands/iterate/index.mjs

@@ -27,6 +27,7 @@ import { stackDraftHold } from "./parent-first.mjs";
 import { findStaleNativeStackAncestry } from "./stale-ancestry.mjs";
 import { annotateBlockedWait, resolveCheckBlockerGate } from "./check-blocker-gate.mjs";
 import { buildUnreportedFixResult, planUnreportedRequired } from "./unreported-required.mjs";
+import { createCheckExecutionContext } from "../check-execution-context.mjs";
 export function runIterate(opts) {
     return withIterateApiUsage(opts, () => runIterateCore(opts));
 }
@@ -40,6 +41,7 @@ async function runIterateCore(opts) {
         throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
     }
     const neverCancelRuns = opts.neverCancelRuns ?? config.actions.neverCancelRuns;
+    const checkContext = createCheckExecutionContext(readyDelaySeconds);
     const report = await runCheck({
         ...opts,
         prNumber,
@@ -48,7 +50,7 @@ async function runIterateCore(opts) {
         // compatibility key in the config loader.
         autoResolve: true,
         autoMinimizeSuppressed: config.actions.autoMinimizeSuppressed,
-    });
+    }, checkContext);
     const [repoOwner, repoName] = report.repo.split("/");
     if (!repoOwner || !repoName) {
         throw new ShepherdError(`Unexpected repo format: "${report.repo}" (expected "owner/name")`, EXIT.DATAERR);
@@ -84,6 +86,7 @@ async function runIterateCore(opts) {
     // the apply command remains a working fallback instead of silently dropping it.
     let reviewSummaryIds = minimizeIds;
     if (selfMinimizeIds.length > 0) {
+        checkContext.invalidateReceiptSummary();
         const { minimized } = await autoMinimizeComments(selfMinimizeIds);
         const minimizedIds = new Set(minimized);
         const unminimized = selfMinimizeIds.filter((id) => !minimizedIds.has(id));
@@ -110,13 +113,13 @@ async function runIterateCore(opts) {
     const staleAncestry = await findStaleNativeStackAncestry(report, {
         owner: repoOwner,
         name: repoName,
-    });
+    }, checkContext);
     const isCleanReadyState = report.status === "READY" &&
         !report.mergeStatus.isDraft &&
         !hasReadinessWork &&
         !activeMerge &&
         staleAncestry === null;
-    const receiptCurrent = await revalidateReadyReceipt(receiptKey, report, hasReadinessWork);
+    const receiptCurrent = await revalidateReadyReceipt(receiptKey, report, hasReadinessWork, checkContext);
     const headSha = report.headSha ?? "unknown";
     // The elapsed marker survives a hidden-comment acknowledgement tick and is
     // consumed only when this tick cancels or merges. A receipt that is still
@@ -233,7 +236,7 @@ async function runIterateCore(opts) {
     if (markReadyResult)
         return markReadyResult;
     if (readyState.shouldCancel && !report.mergeStatus.isDraft) {
-        const receiptWritten = receiptCurrent || (await recordReadyReceipt(receiptKey, report));
+        const receiptWritten = receiptCurrent || (await recordReadyReceipt(receiptKey, report, checkContext));
         // Aggregate --stack routing trusts only a layer's receipt, so an unwritten
         // one keeps the elapsed marker and retries next tick. A one-PR receipt
         // only lets a rerun skip the wait, so its failure never changes the action.
@@ -279,7 +282,7 @@ async function runIterateCore(opts) {
     };
     return annotateBlockedWait(await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, wait, reportForWork, reviewSummaryIds), blockerGate);
 }
-async function recordReadyReceipt(key, report) {
+async function recordReadyReceipt(key, report, context) {
     if (report.status !== "READY" ||
         report.mergeStatus.state !== "OPEN" ||
         report.mergeStatus.isDraft ||
@@ -287,7 +290,7 @@ async function recordReadyReceipt(key, report) {
         !report.baseRefOid)
         return false;
     try {
-        const raw = await fetchRawSummaryPr(report.pr, { owner: key.owner, name: key.repo });
+        const raw = await receiptSummaryForReport(key, report, context);
         if (fingerprintRawSummaryPr(raw) === null ||
             raw.state !== "OPEN" ||
             raw.isDraft ||
@@ -327,7 +330,7 @@ async function recordReadyReceipt(key, report) {
     }
 }
 /** Clear a stale READY receipt; return whether a current receipt remains. */
-async function revalidateReadyReceipt(key, report, hasReadinessWork) {
+async function revalidateReadyReceipt(key, report, hasReadinessWork, context) {
     const receipt = await readReadyReceipt(key);
     if (!receipt)
         return false;
@@ -344,7 +347,7 @@ async function revalidateReadyReceipt(key, report, hasReadinessWork) {
         return false;
     }
     try {
-        const raw = await fetchRawSummaryPr(report.pr, { owner: key.owner, name: key.repo });
+        const raw = await receiptSummaryForReport(key, report, context);
         const summary = await summarizePollSummaryPr(raw, { owner: key.owner, name: key.repo }, { stackPrNumber: report.pr });
         if (annotationProbeUnavailable(raw)) {
             const sameHead = raw.headRefOid === report.headSha;
@@ -385,3 +388,12 @@ async function revalidateReadyReceipt(key, report, hasReadinessWork) {
         return false;
     }
 }
+/** A mismatched or invalidated same-request hint falls back to the original fresh read. */
+async function receiptSummaryForReport(key, report, context) {
+    const candidate = context?.getReceiptSummary();
+    if (candidate?.number === report.pr &&
+        candidate.headRefOid === report.headSha &&
+        candidate.baseRefOid === report.baseRefOid)
+        return candidate;
+    return fetchRawSummaryPr(report.pr, { owner: key.owner, name: key.repo });
+}

package/bin/commands/iterate/native-stack-rebase.mjs

@@ -1,3 +1,4 @@
+import { playbookPointer } from "../playbook-pointer.mjs";
 /**
  * One gh-stack rebase step. A native stack layer must not be rebased or merged from its base
  * branch alone: that rewrites one branch and strands every layer above it.
@@ -15,8 +16,8 @@ export function buildNativeStackRebaseInstruction(repo, stackNumber, start) {
         : "bottomPr" in start
             ? [`check out the head branch of PR #${start.bottomPr}`, "gh stack rebase"]
             : [`check out the bottom open layer whose base is \`${start.trunk}\``, "gh stack rebase"];
-    const prepare = `if \`gh stack\` does not track stack #${stackNumber} locally, import it with \`gh stack checkout ${stackNumber}\`, then confirm every layer's local branch is at its PR's head commit — a stale local layer would overwrite that PR's newer commits on push`;
-    return `From a clean checkout of \`${repo}\`, ${prepare}. Then ${checkout} and run \`${command}\`; if it stops on a conflict, resolve it and run \`gh stack rebase --continue\`.`;
+    const prepare = `if \`gh stack\` does not track stack #${stackNumber} locally, import it with \`gh stack checkout ${stackNumber}\``;
+    return `From a clean checkout of \`${repo}\`, ${prepare}. Then ${checkout} and run \`${command}\`. ${playbookPointer("Branch update")}`;
 }
 /**
  * The stack-aware branch update for a native stack layer (a conflict, or a behind branch whose