pr-shepherd 0.54.0 → 0.55.0

package/bin/cli/iterate-formatter.mjs

@@ -6,6 +6,8 @@ import { formatMergeRequirementLines } from "../merge-status/requirements-format
 import { appendMergeQueueHeader, formatDeferredWorkLine, formatMergeAction, } from "./iterate-merge-formatter.mjs";
 import { formatApiUsage, formatQuotaWarning } from "./api-usage-formatter.mjs";
 import { formatActivityLine } from "./iterate-activity-formatter.mjs";
+import { branchStateSegment } from "./iterate-branch-segment.mjs";
+import { insertRuleAutoResolveSection } from "../commands/rule-auto-resolve-format.mjs";
 /**
  * Format an IterateResult as human-readable Markdown.
  *
@@ -23,21 +25,17 @@ import { formatActivityLine } from "./iterate-activity-formatter.mjs";
 export function formatIterateResult(result, opts) {
     const verbose = opts?.verbose ?? false;
     const readyDelaySuffix = opts?.readyDelaySuffix;
+    const finish = (text) => insertRuleAutoResolveSection(text, result.ruleAutoResolve);
     const heading = `# PR #${result.pr} [${result.action.toUpperCase()}]`;
     const reviewDecisionSeg = result.mergeStatus === "BLOCKED" && result.reviewDecision
         ? ` · **reviewDecision** \`${result.reviewDecision}\``
         : "";
     const baseBranchSeg = verbose && result.baseBranch ? ` · **baseBranch** \`${result.baseBranch}\`` : "";
     const baseLine = `**status** \`${result.status}\` · **merge** \`${result.mergeStateStatus}\`${reviewDecisionSeg} · **state** \`${result.state}\` · **repo** \`${result.repo}\`${baseBranchSeg}`;
+    const branchSeg = branchStateSegment(result);
     let summaryLine;
     if (verbose) {
-        let verboseBranch = "";
-        if (result.mergeStatus === "BEHIND" && result.baseBranch) {
-            verboseBranch = ` · **branch** behind PR base \`${result.baseBranch}\``;
-        }
-        else if (result.mergeStatus === "CONFLICTS" && result.baseBranch) {
-            verboseBranch = ` · **branch** conflicts with PR base \`${result.baseBranch}\``;
-        }
+        const verboseBranch = branchSeg ? ` · ${branchSeg}` : "";
         summaryLine = `**summary** ${result.summary.passing} passing, ${result.summary.skipped} skipped, ${result.summary.filtered} filtered, ${result.summary.inProgress} inProgress, ${result.summary.superseded} superseded · **remainingSeconds** ${result.remainingSeconds} · **blockingBotReviewInProgress** ${result.blockingBotReviewInProgress} · **isDraft** ${result.isDraft} · **shouldCancel** ${result.shouldCancel}${verboseBranch}`;
     }
     else {
@@ -58,12 +56,8 @@ export function formatIterateResult(result, opts) {
             segs.push(`**blockingBotReviewInProgress**`);
         if (result.isDraft)
             segs.push(`**isDraft**`);
-        if (result.mergeStatus === "BEHIND" && result.baseBranch) {
-            segs.push(`**branch** behind PR base \`${result.baseBranch}\``);
-        }
-        else if (result.mergeStatus === "CONFLICTS" && result.baseBranch) {
-            segs.push(`**branch** conflicts with PR base \`${result.baseBranch}\``);
-        }
+        if (branchSeg)
+            segs.push(branchSeg);
         summaryLine = segs.join(" · ");
     }
     // Surface an explicit `--ready-delay` override (set only when the user passed the flag)
@@ -105,6 +99,7 @@ export function formatIterateResult(result, opts) {
         const names = result.supersededNames.map((n) => "`" + n + "`").join(", ");
         headerLines.push(`**superseded** ${names}`);
     }
+    appendUnreportedLines(headerLines, result);
     appendMergeQueueHeader(headerLines, result);
     const activityLine = formatActivityLine(result);
     if (activityLine)
@@ -115,22 +110,29 @@ export function formatIterateResult(result, opts) {
     const verboseChecks = verbose ? formatRelevantChecks(result.checks) : null;
     const telemetrySections = [quotaWarning, apiUsage, verboseChecks];
     switch (result.action) {
+        case "ready":
+            return joinSections([
+                header,
+                ...telemetrySections,
+                adaptIterateLog(result.log),
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
+            ]);
         case "wait": {
             const waitLines = [header, ...telemetrySections, adaptIterateLog(result.log)];
             if (result.deferredWork)
                 waitLines.push(formatDeferredWorkLine(result.deferredWork));
             waitLines.push(`## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`);
-            return joinSections(waitLines);
+            return finish(joinSections(waitLines));
         }
         case "mark_ready":
-            return joinSections([
+            return finish(joinSections([
                 header,
                 ...telemetrySections,
                 adaptIterateLog(result.log),
                 `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
-            ]);
+            ]));
         case "merge":
-            return formatMergeAction(joinSections([header, ...telemetrySections]), result);
+            return finish(formatMergeAction(joinSections([header, ...telemetrySections]), result));
         case "cancel": {
             const cancelHeaderLines = [`${heading} — ${result.reason}`, "", baseLine, summaryLine];
             if (result.mergeRequirements) {
@@ -147,26 +149,36 @@ export function formatIterateResult(result, opts) {
                 const supersededStr = result.supersededNames.map((n) => "`" + n + "`").join(", ");
                 cancelHeaderLines.push(`**superseded** ${supersededStr}`);
             }
+            appendUnreportedLines(cancelHeaderLines, result);
             appendMergeQueueHeader(cancelHeaderLines, result);
             if (activityLine)
                 cancelHeaderLines.push(activityLine);
-            return joinSections([
+            return finish(joinSections([
                 cancelHeaderLines.join("\n"),
                 ...(apiUsage ? [apiUsage] : []),
                 ...(verboseChecks ? [verboseChecks] : []),
                 adaptIterateLog(result.log),
                 `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
-            ]);
+            ]));
         }
         case "escalate":
-            return joinSections([
+            return finish(joinSections([
                 header,
                 ...(apiUsage ? [apiUsage] : []),
                 ...(verboseChecks ? [verboseChecks] : []),
                 result.escalate.humanMessage,
                 `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
-            ]);
+            ]));
         case "fix_code":
-            return formatFixCodeResult(joinSections([header, ...telemetrySections]), result, { verbose });
+            return finish(formatFixCodeResult(joinSections([header, ...telemetrySections]), result, { verbose }));
+    }
+}
+function appendUnreportedLines(lines, result) {
+    if (result.unreportedRequiredChecks && result.unreportedRequiredChecks.length > 0) {
+        const names = result.unreportedRequiredChecks.map((name) => "`" + name + "`").join(", ");
+        lines.push(`**unreported required** ${names}`);
+    }
+    if (result.trunkBehindBy !== undefined && result.trunkBehindBy > 0) {
+        lines.push(`**trunk behind** \`${result.trunkBehindBy}\``);
     }
 }

package/bin/cli/iterate-instructions.mjs

@@ -6,6 +6,12 @@ import { AUTO_MARK_READY_DISABLED_HOLD } from "../commands/stack-work.mjs";
 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.`;
+            return [
+                result.quotaWarning ? buildQuotaAwareContinuation(result.quotaWarning, sentence) : sentence,
+            ];
+        }
         case "wait":
             if (result.stackDraftHold)
                 return [buildStackDraftHoldInstruction(result, result.stackDraftHold)];

package/bin/cli/iterate-lean.mjs

@@ -1,4 +1,5 @@
 import { adaptIterateLog, buildSimpleIterateInstructions } from "./iterate-instructions.mjs";
+import { projectRuleAutoResolve } from "../commands/rule-auto-resolve-format.mjs";
 /**
  * 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
@@ -41,6 +42,7 @@ export function projectIterateLean(result, opts) {
             remainingSeconds: result.remainingSeconds,
         }),
         ...(result.baseBranch && { baseBranch: result.baseBranch }),
+        ...(result.stackTrunkConflict && { stackTrunkConflict: result.stackTrunkConflict }),
         ...(result.branchProtection !== null && { branchProtection: result.branchProtection }),
         ...(result.mergeRequirements && { mergeRequirements: result.mergeRequirements }),
         ...(result.mergeQueue && { mergeQueue: result.mergeQueue }),
@@ -65,9 +67,23 @@ export function projectIterateLean(result, opts) {
         ...((result.supersededNames?.length ?? 0) > 0 && {
             supersededNames: result.supersededNames,
         }),
+        ...((result.unreportedRequiredChecks?.length ?? 0) > 0 && {
+            unreportedRequiredChecks: result.unreportedRequiredChecks,
+        }),
+        ...(result.trunkBehindBy !== undefined &&
+            result.trunkBehindBy > 0 && { trunkBehindBy: result.trunkBehindBy }),
         ...(result.quotaWarning && { quotaWarning: result.quotaWarning }),
+        ...(result.ruleAutoResolve && {
+            ruleAutoResolve: projectRuleAutoResolve(result.ruleAutoResolve),
+        }),
     };
     switch (result.action) {
+        case "ready":
+            return {
+                ...base,
+                log: adaptIterateLog(result.log),
+                instructions: simpleInstructions(result),
+            };
         case "wait":
             return {
                 ...base,

package/bin/cli/poll-summary-emitter.mjs

@@ -1,7 +1,10 @@
 import { EXIT } from "../exit-codes.mjs";
 import { formatPollSummaryResult } from "./poll-summary-formatter.mjs";
+import { projectStackOverview } from "./stack-overview.mjs";
 export function emitPollSummaryResult(result, opts) {
-    process.stdout.write(opts.format === "json" ? `${JSON.stringify(result)}\n` : `${formatPollSummaryResult(result)}\n`);
+    process.stdout.write(opts.format === "json"
+        ? `${JSON.stringify(result.selection.kind === "stack" ? projectStackOverview(result) : result)}\n`
+        : `${formatPollSummaryResult(result)}\n`);
     process.exitCode = pollSummaryExitCode(result);
 }
 function pollSummaryExitCode(result) {

package/bin/cli/poll-summary-formatter.mjs

@@ -1,9 +1,10 @@
 import { formatApiUsage, formatQuotaWarning } from "./api-usage-formatter.mjs";
 import { withPollSummaryInstructions } from "../commands/poll-summary-instructions.mjs";
+import { formatStackOverview, projectStackOverview } from "./stack-overview.mjs";
 export function formatPollSummaryResult(result) {
-    const selection = result.selection.kind === "stack"
-        ? `stack #${result.selection.stackNumber} anchored at PR #${result.selection.anchor} (${result.selection.stackSize} PRs)`
-        : `PRs ${result.selection.requested.map((pr) => `#${pr}`).join(", ")}`;
+    if (result.selection.kind === "stack")
+        return formatStackOverview(projectStackOverview(result));
+    const selection = `PRs ${result.selection.requested.map((pr) => `#${pr}`).join(", ")}`;
     const lines = [
         `# Poll summary [${result.reason.toUpperCase()}]`,
         "",
@@ -52,6 +53,12 @@ function formatItem(item) {
         ...(checks
             ? [`  - checks: ${formatCounts(checks, checks.incomplete ? ", incomplete" : "")}`]
             : []),
+        ...(checks?.unreportedRequired?.length
+            ? [
+                `  - unreported required: ${checks.unreportedRequired.map((name) => `\`${name}\``).join(", ")}`,
+            ]
+            : []),
+        ...(checks?.actionsWorkflowInProgress ? ["  - actions workflow in progress"] : []),
         ...(review
             ? [`  - review: ${formatCounts(review, review.incomplete ? ", incomplete" : "")}`]
             : []),

package/bin/cli/stack-overview.d.mts

@@ -0,0 +1,48 @@
+import type { PollSummaryItem, PollSummaryResult, PollSummaryStackAncestry, StackNextAction } from "../types.mts";
+import type { ApiUsage, GraphqlQuotaWarning } from "../types/api-usage.mts";
+/** Agent-facing stack row. Planning keeps the richer PollSummaryItem. */
+interface StackLayerView {
+    pr: number;
+    title: string;
+    url: string;
+    state: PollSummaryItem["state"];
+    shepherded: boolean;
+    mergeable: boolean;
+    blocker?: string;
+    author?: string;
+    owned?: true;
+    isDraft?: true;
+    isInMergeQueue?: true;
+    position?: number;
+    stackSize?: number;
+    baseRefName: string;
+    failing?: number;
+    inProgress?: number;
+    actionable?: number;
+    checksIncomplete?: true;
+    reviewIncomplete?: true;
+    queueRemoval?: {
+        reason: string | null;
+        actor?: string;
+    };
+}
+export interface StackOverview {
+    mode: "summary";
+    repo: string;
+    selection: Extract<PollSummaryResult["selection"], {
+        kind: "stack";
+    }>;
+    reason: PollSummaryResult["reason"];
+    stackMergeable?: boolean;
+    nextAction?: StackNextAction;
+    prs: StackLayerView[];
+    stackAncestry?: PollSummaryStackAncestry[];
+    instructions?: string[];
+    apiUsage?: ApiUsage;
+    quotaWarning?: GraphqlQuotaWarning;
+}
+/** Lean stack payload shared by Markdown, JSON, and MCP. */
+export declare function projectStackOverview(result: PollSummaryResult): StackOverview;
+/** Markdown for a stack overview. */
+export declare function formatStackOverview(overview: StackOverview): string;
+export {};

package/bin/cli/stack-overview.mjs

@@ -0,0 +1,138 @@
+import { stackLayerBlockReason } from "../commands/stack-layer-readiness.mjs";
+import { formatApiUsage, formatQuotaWarning } from "./api-usage-formatter.mjs";
+/** Lean stack payload shared by Markdown, JSON, and MCP. */
+export function projectStackOverview(result) {
+    const selection = result.selection;
+    if (selection.kind !== "stack") {
+        throw new Error("projectStackOverview requires a stack selection");
+    }
+    const stale = new Set(result.stackAncestry?.map((gap) => gap.childPr) ?? []);
+    return {
+        mode: "summary",
+        repo: result.repo,
+        selection,
+        reason: result.reason,
+        ...(result.stackMergeable !== undefined && { stackMergeable: result.stackMergeable }),
+        ...(result.nextAction && { nextAction: result.nextAction }),
+        prs: result.prs.map((item) => projectLayer(item, stale.has(item.pr))),
+        ...(result.stackAncestry?.length && { stackAncestry: result.stackAncestry }),
+        ...(result.instructions?.length && { instructions: result.instructions }),
+        ...(result.apiUsage && { apiUsage: result.apiUsage }),
+        ...(result.quotaWarning && { quotaWarning: result.quotaWarning }),
+    };
+}
+function projectLayer(item, stale) {
+    const blocker = layerBlocker(item, stale);
+    const removal = item.queueRemoval;
+    return {
+        pr: item.pr,
+        title: item.title,
+        url: item.url,
+        state: item.state,
+        shepherded: item.readyReceipt === true,
+        mergeable: blocker === undefined,
+        ...(blocker && { blocker }),
+        ...(item.authorLogin && { author: item.authorLogin }),
+        ...(item.owned && { owned: true }),
+        ...(item.isDraft && { isDraft: true }),
+        ...(item.isInMergeQueue && { isInMergeQueue: true }),
+        ...(item.stack && { position: item.stack.position, stackSize: item.stack.size }),
+        baseRefName: item.baseRefName,
+        ...(blocker === "failing-checks" &&
+            (item.checks?.failing ?? 0) > 0 && { failing: item.checks?.failing }),
+        ...(blocker === "checks-in-progress" &&
+            (item.checks?.inProgress ?? 0) > 0 && { inProgress: item.checks?.inProgress }),
+        ...(blocker === "review-work" &&
+            (item.review?.actionable ?? 0) > 0 && { actionable: item.review?.actionable }),
+        ...(item.checks?.incomplete && { checksIncomplete: true }),
+        ...(item.review?.incomplete && { reviewIncomplete: true }),
+        ...(removal && {
+            queueRemoval: {
+                reason: removal.reason,
+                ...(removal.actor && { actor: removal.actor }),
+            },
+        }),
+    };
+}
+/** Mergeability blocker. A missing receipt is "not shepherded", not a mergeability reason. */
+function layerBlocker(item, stale) {
+    if (item.action === "escalate") {
+        return item.reasons.find((reason) => reason !== "appears-ready") ?? "escalate";
+    }
+    if (stale)
+        return "stale-ancestry";
+    const reason = stackLayerBlockReason(item);
+    if (reason === undefined || reason === "no-ready-receipt")
+        return undefined;
+    return reason;
+}
+/** Skill stop tokens. Other stack actions stay untagged so the loop keeps running. */
+function stackTerminalTag(nextAction) {
+    if (nextAction === "cancel")
+        return " [CANCEL]";
+    if (nextAction === "escalate")
+        return " [ESCALATE]";
+    return "";
+}
+/** Markdown for a stack overview. */
+export function formatStackOverview(overview) {
+    const stack = overview.selection;
+    const lines = [
+        `# ${overview.repo} stack #${stack.stackNumber}${stackTerminalTag(overview.nextAction)} — ${overview.reason}`,
+        "",
+        `Stack: #${stack.stackNumber} · anchor PR #${stack.anchor} · ${stack.stackSize} layers · mode \`${overview.mode}\``,
+        ...(overview.stackMergeable !== undefined
+            ? [`stackMergeable: ${overview.stackMergeable}`]
+            : []),
+        ...(overview.nextAction ? [`nextAction: ${overview.nextAction}`] : []),
+        "",
+        "## Layers",
+        "",
+        ...overview.prs.flatMap(formatLayerLines),
+    ];
+    if (overview.stackAncestry?.length) {
+        lines.push("", "## Stack ancestry", "");
+        for (const gap of overview.stackAncestry) {
+            lines.push(`- PR #${gap.childPr} base \`${gap.childBaseRefName}\` at \`${gap.childBaseRefOid}\` differs from parent PR #${gap.parentPr} head \`${gap.parentHeadRefName}\` at \`${gap.parentHeadRefOid}\`.`);
+        }
+    }
+    if (overview.instructions?.length) {
+        lines.push("", "## Instructions", "", ...overview.instructions);
+    }
+    const quota = formatQuotaWarning(overview.quotaWarning);
+    const usage = formatApiUsage(overview.apiUsage);
+    if (quota)
+        lines.push("", quota);
+    if (usage)
+        lines.push("", usage);
+    return lines.join("\n");
+}
+function formatLayerLines(layer) {
+    const facts = [
+        layer.shepherded ? "shepherded" : "not shepherded",
+        layer.mergeable ? "mergeable" : `not mergeable (\`${layer.blocker ?? "unknown"}\`)`,
+        layer.author ? `owner \`@${layer.author}\`` : undefined,
+        layer.owned ? "owned" : undefined,
+    ].filter((fact) => fact !== undefined);
+    const details = [
+        layer.state,
+        layer.isDraft ? "draft" : undefined,
+        layer.isInMergeQueue ? "in merge queue" : undefined,
+        layer.position !== undefined && layer.stackSize !== undefined
+            ? `position ${layer.position}/${layer.stackSize}`
+            : undefined,
+        `base \`${layer.baseRefName}\``,
+        layer.failing ? `${layer.failing} failing` : undefined,
+        layer.inProgress ? `${layer.inProgress} in progress` : undefined,
+        layer.actionable ? `${layer.actionable} actionable` : undefined,
+        layer.checksIncomplete ? "checks incomplete" : undefined,
+        layer.reviewIncomplete ? "review incomplete" : undefined,
+        layer.queueRemoval
+            ? `removed from merge queue (${layer.queueRemoval.reason ?? "unknown reason"}${layer.queueRemoval.actor ? ` by @${layer.queueRemoval.actor}` : ""})`
+            : undefined,
+    ].filter((detail) => detail !== undefined);
+    return [
+        `- [PR #${layer.pr}: ${layer.title}](${layer.url}) — ${facts.join(" · ")}`,
+        `  - ${details.join(" · ")}`,
+    ];
+}

package/bin/commands/check-fingerprint.mjs

@@ -2,6 +2,7 @@ import { getMergeableState } from "../github/client.mjs";
 import { fetchPrFingerprint, fingerprintsEqual, } from "../github/fingerprint.mjs";
 import { fingerprintInputDigest, loadPrFingerprint } from "../state/pr-fingerprint.mjs";
 import { hasCheckDrivenActionableWork } from "./check-annotations.mjs";
+import { stripReplayedRuleAutoResolve } from "./rule-auto-resolve-format.mjs";
 function reportAllowsFingerprintSkip(report) {
     if (report.status === "READY")
         return false;
@@ -50,7 +51,7 @@ export async function tryReuseFingerprintReport(prNumber, repo, stateKey, config
     if (!(await cachedReportSurvivesMergeabilityRefresh(prNumber, repo, cached.report, cached.fingerprint))) {
         return null;
     }
-    return { ...cached.report, fingerprintReused: true };
+    return { ...stripReplayedRuleAutoResolve(cached.report), fingerprintReused: true };
 }
 async function cachedReportSurvivesMergeabilityRefresh(prNumber, repo, report, fingerprint) {
     const restDerived = fingerprint.mergeable !== report.mergeStatus.mergeable ||

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

@@ -1,3 +1,3 @@
 import type { MergeStatusResult, ShepherdStatus } from "../types.mts";
 import type { CiVerdict } from "../checks/classify.mts";
-export declare function computeStatus(verdict: CiVerdict, unresolvedThreads: number, unresolvedComments: number, mergeStatus: MergeStatusResult, changesRequestedReviews: number): ShepherdStatus;
+export declare function computeStatus(verdict: CiVerdict, unresolvedThreads: number, unresolvedComments: number, mergeStatus: MergeStatusResult, changesRequestedReviews: number, hasUnreportedRequired?: boolean): ShepherdStatus;

package/bin/commands/check-status.mjs

@@ -1,4 +1,4 @@
-export function computeStatus(verdict, unresolvedThreads, unresolvedComments, mergeStatus, changesRequestedReviews) {
+export function computeStatus(verdict, unresolvedThreads, unresolvedComments, mergeStatus, changesRequestedReviews, hasUnreportedRequired = false) {
     // Merge conflicts are always terminal regardless of CI state.
     if (mergeStatus.status === "CONFLICTS")
         return "FAILING";
@@ -25,7 +25,8 @@ export function computeStatus(verdict, unresolvedThreads, unresolvedComments, me
         unresolvedComments === 0 &&
         changesRequestedReviews === 0 &&
         (mergeStatus.status === "BLOCKED" || mergeStatus.status === "UNSTABLE") &&
-        !mergeStatus.blockingBotReviewInProgress) {
+        !mergeStatus.blockingBotReviewInProgress &&
+        !hasUnreportedRequired) {
         return "READY";
     }
     if (mergeStatus.status === "BLOCKED" ||
@@ -37,7 +38,11 @@ export function computeStatus(verdict, unresolvedThreads, unresolvedComments, me
     if (changesRequestedReviews > 0 || unresolvedThreads > 0 || unresolvedComments > 0)
         return "UNRESOLVED_COMMENTS";
     // DRAFT is treated the same as CLEAN for readiness — marking the PR ready resolves it.
-    if ((mergeStatus.status === "CLEAN" || mergeStatus.status === "DRAFT") && verdict.allPassed)
+    if ((mergeStatus.status === "CLEAN" || mergeStatus.status === "DRAFT") &&
+        verdict.allPassed &&
+        !hasUnreportedRequired)
         return "READY";
+    if (hasUnreportedRequired && (mergeStatus.status === "CLEAN" || mergeStatus.status === "DRAFT"))
+        return "PENDING";
     return "UNKNOWN";
 }

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

@@ -0,0 +1,26 @@
+import { type WorkflowSuiteSnapshot } from "../checks/unreported-required.mts";
+import type { BatchPrData, CheckRun, ShepherdReport } from "../types.mts";
+import type { RepoInfo } from "../github/client.mts";
+export interface UnreportedRequiredFields {
+    unreportedRequiredChecks?: string[];
+    trunkBehindBy?: number;
+    actionsWorkflowInProgress?: true;
+    stackBottomPr?: number;
+    headRefName: string;
+    hasUnreportedRequired: boolean;
+}
+/** Load trunk rules for a stack and diff them against the head's check names. */
+export declare function collectUnreportedRequired(input: {
+    batchData: BatchPrData;
+    checks: readonly CheckRun[];
+    suites: readonly WorkflowSuiteSnapshot[];
+    owner: string;
+    name: string;
+    pr: number;
+    relevantEvents: readonly string[];
+}): 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>;

package/bin/commands/check-unreported.mjs

@@ -0,0 +1,73 @@
+import { actionsWorkflowInProgress, reportedCheckNames, unreportedRequiredContexts, } from "../checks/unreported-required.mjs";
+import { 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) {
+    const localContexts = input.batchData.branchRules?.requiredStatusCheckContexts ??
+        input.batchData.branchProtection?.requiredStatusCheckContexts ??
+        [];
+    const target = await loadMergeTargetStatus({
+        owner: input.owner,
+        name: input.name,
+        pr: input.pr,
+        baseRefName: input.batchData.baseRefName,
+        headRefName: input.batchData.headRefName,
+        localContexts,
+        stack: input.batchData.stack,
+    });
+    const unreported = unreportedRequiredContexts(target.contexts, reportedCheckNames(input.checks));
+    const actionsRunning = actionsWorkflowInProgress(input.suites, new Set(input.relevantEvents));
+    return {
+        ...(unreported.length > 0 && { unreportedRequiredChecks: unreported }),
+        ...(target.trunkBehindBy !== undefined &&
+            target.trunkBehindBy > 0 && { trunkBehindBy: target.trunkBehindBy }),
+        ...(actionsRunning && { actionsWorkflowInProgress: true }),
+        ...(target.stackBottomPr !== undefined && { stackBottomPr: target.stackBottomPr }),
+        headRefName: input.batchData.headRefName,
+        hasUnreportedRequired: unreported.length > 0,
+    };
+}
+/**
+ * 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) {
+    const stack = report.mergeStatus?.mergeRequirements?.stack;
+    if (!stack || !report.headRefName)
+        return report;
+    const target = await loadMergeTargetStatus({
+        owner: repo.owner,
+        name: repo.name,
+        pr: report.pr,
+        baseRefName: report.baseBranch,
+        headRefName: report.headRefName,
+        localContexts: report.mergeStatus.mergeRequirements?.requiredStatusChecks?.contexts ?? [],
+        stack,
+    });
+    const unreported = unreportedRequiredContexts(target.contexts, reportedCheckNames(reportChecks(report)));
+    const next = { ...report };
+    if (unreported.length > 0)
+        next.unreportedRequiredChecks = unreported;
+    else
+        delete next.unreportedRequiredChecks;
+    if (target.trunkBehindBy !== undefined && target.trunkBehindBy > 0) {
+        next.trunkBehindBy = target.trunkBehindBy;
+    }
+    else
+        delete next.trunkBehindBy;
+    if (target.stackBottomPr !== undefined)
+        next.stackBottomPr = target.stackBottomPr;
+    if (unreported.length > 0 && next.status === "READY")
+        next.status = "PENDING";
+    return next;
+}
+function reportChecks(report) {
+    return [
+        ...report.checks.passing,
+        ...report.checks.failing,
+        ...report.checks.inProgress,
+        ...report.checks.skipped,
+        ...report.checks.filtered,
+        ...(report.checks.ignored ?? []),
+        ...(report.checks.supersededNames ?? []).map((name) => ({ name })),
+    ];
+}