pr-shepherd 0.54.1 → 0.55.0

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
@@ -66,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 })),
+    ];
+}

package/bin/commands/check.mjs

@@ -2,6 +2,7 @@ import { fetchPrBatch } from "../github/batch.mjs";
 import { queueRemovalAppliesToHead } from "../github/queue-removal-freshness.mjs";
 import { storePrFingerprint } from "../state/pr-fingerprint.mjs";
 import { tryReuseFingerprintReport } from "./check-fingerprint.mjs";
+import { collectUnreportedRequired, refreshCachedUnreported } from "./check-unreported.mjs";
 import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
 import { classifyChecks, getCiVerdict } from "../checks/classify.mjs";
 import { mergeStartupFailureChecks } from "../checks/startup-failures.mjs";
@@ -17,7 +18,7 @@ import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs"
 import { threadTranscriptBody } from "../threads/transcript.mjs";
 import { classifyThreadVisibility } from "../comments/thread-visibility.mjs";
 import { classifyReviewsForDisplay, classifyChangesRequestedReviewsForDisplay, } from "../comments/review-visibility.mjs";
-import { autoMinimizeComments, autoResolveThreads } from "../comments/resolve.mjs";
+import { applySuppressedRuleAutoResolve } from "./rule-auto-resolve.mjs";
 import { markReviewInlineThreadMarkers } from "../comments/review-thread-markers.mjs";
 import { isConfiguredBotAuthor, isHumanAuthor, normalizeBotUsernames, } from "../comments/authors.mjs";
 import { buildThreadMutationRouting, threadHasAuthorizedMutation, } from "./iterate/thread-mutation-routing.mjs";
@@ -37,7 +38,7 @@ export async function runCheck(opts) {
     if (reuseFingerprint) {
         const cached = await tryReuseFingerprintReport(prNumber, repo, stateKey, config);
         if (cached)
-            return cached;
+            return refreshCachedUnreported(cached, repo);
     }
     const paginateApprovedReviews = config.iterate.minimizeApprovals;
     const result = await fetchPrBatch(prNumber, repo, { paginateApprovedReviews });
@@ -67,8 +68,10 @@ export async function runCheck(opts) {
     // it as stale/updated rather than as still current, so Shepherd doesn't escalate
     // `merge-queue-removed` permanently on data it can no longer check. A squash or rebase
     // queue commit has one parent and does not list the PR head; that removal stays current
-    // until the head's committer time is later than the removal. The raw removal fields still
-    // render in the merge-queue header regardless of this flag.
+    // until this head reached the PR after it. The push time is the earliest pull_request
+    // check on the head, with committer time as the fallback when no check time is
+    // available. The raw removal fields still render in the merge-queue header regardless
+    // of this flag.
     const headCommittedAtUnix = batchData.activity?.latestCommitCommittedAtUnix;
     const headUpdatedAfterRemoval = Boolean(latestRemoval &&
         !queueRemovalAppliesToHead({
@@ -76,6 +79,9 @@ export async function runCheck(opts) {
             headOid: batchData.headRefOid,
             ...(headCommittedAtUnix !== undefined &&
                 headCommittedAtUnix !== null && { headCommittedAtUnix }),
+            ...(batchData.headPushedAtUnix !== undefined && {
+                headPushedAtUnix: batchData.headPushedAtUnix,
+            }),
             removedAtUnix: latestRemoval.createdAtUnix,
         }));
     const queueRawChecks = batchData.isInMergeQueue
@@ -154,14 +160,23 @@ export async function runCheck(opts) {
             visibleChangesRequestedIds.has(review.id));
     }).length;
     const approvedReviews = approvedReviewVisibility.visible;
-    let status = computeStatus(verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, mergeStatus, changesRequestedReviewCount);
+    const unreported = await collectUnreportedRequired({
+        batchData,
+        checks: allChecks,
+        suites: result.headWorkflowSuites ?? [],
+        owner: repo.owner,
+        name: repo.name,
+        pr: prNumber,
+        relevantEvents: config.checks.ciTriggerEvents,
+    });
+    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,
     // possibly-refreshed mergeStatus that commands/iterate/index.mts acts on, not the pre-refresh
     // snapshot. A conflict newly discovered by this REST read is exactly the kind of check-driven
     // signal that keeps a queued PR out of the deferral path.
     if (status === "READY" && !didRefreshMergeability) {
-        const refreshed = await refreshReadyMergeability(prNumber, repo, batchData, verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, changesRequestedReviewCount);
+        const refreshed = await refreshReadyMergeability(prNumber, repo, batchData, verdict, threadVisibility.activeThreads.length + threadVisibility.resolutionOnlyThreads.length, visibleCommentClassification.actionable.length, changesRequestedReviewCount, unreported.hasUnreportedRequired);
         batchData = refreshed.batchData;
         mergeStatus = refreshed.mergeStatus;
         status = refreshed.status;
@@ -236,7 +251,13 @@ 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),
     };
-    const { threadIds: authorizedRuleAutoResolveThreadIds, commentIds: ruleAutoResolveCommentIds, reviewSummaryIds: ruleAutoResolveReviewSummaryIds, } = await remainingRuleAutoResolveIds(authorizedPartition, opts.autoMinimizeSuppressed);
+    const { threadIds: authorizedRuleAutoResolveThreadIds, commentIds: ruleAutoResolveCommentIds, reviewSummaryIds: ruleAutoResolveReviewSummaryIds, autoResolved, autoMinimized, autoResolveErrors, errorReasons, } = await applySuppressedRuleAutoResolve({
+        enabled: opts.autoMinimizeSuppressed === true,
+        partition: authorizedPartition,
+        batch: batchData,
+        prNumber,
+        repo,
+    });
     const visibleMutationThreadIds = new Set([...threadVisibility.activeThreads, ...threadVisibility.resolutionOnlyThreads].map((thread) => thread.id));
     const ruleAutoResolveThreadIds = [
         ...authorizedRuleAutoResolveThreadIds,
@@ -254,6 +275,7 @@ export async function runCheck(opts) {
         pr: prNumber,
         nodeId: batchData.nodeId,
         headSha: batchData.headRefOid,
+        headRefName: unreported.headRefName,
         repo: `${repo.owner}/${repo.name}`,
         ...(batchData.viewerAuthorization && { viewerAuthorization: batchData.viewerAuthorization }),
         status,
@@ -276,8 +298,9 @@ export async function runCheck(opts) {
         threads: {
             actionable: threadVisibility.activeThreads,
             resolutionOnly: threadVisibility.resolutionOnlyThreads,
-            autoResolved: [],
-            autoResolveErrors: [],
+            autoResolved,
+            autoResolveErrors,
+            ...(errorReasons.length > 0 && { autoResolveErrorReasons: errorReasons }),
             firstLook: threadVisibility.firstLookThreads,
             ...(ruleAutoResolveThreadIds.length > 0
                 ? { ruleAutoResolveIds: ruleAutoResolveThreadIds }
@@ -287,6 +310,7 @@ export async function runCheck(opts) {
             actionable: visibleCommentClassification.actionable,
             minimizeIds: [...visibleCommentClassification.minimizeIds, ...ruleAutoResolveCommentIds],
             firstLook: firstLookComments,
+            ...(autoMinimized.length > 0 && { autoMinimized }),
         },
         changesRequestedReviews,
         reviewSummaries: seenSummaries,
@@ -297,6 +321,9 @@ export async function runCheck(opts) {
             ? { ruleAutoResolveReviewSummaryIds }
             : undefined),
         branchProtection: batchData.branchProtection,
+        ...(batchData.allowedMergeMethods && {
+            allowedMergeMethods: batchData.allowedMergeMethods,
+        }),
         activity: batchData.activity,
         ...(hasQueueState && {
             mergeQueue: {
@@ -316,38 +343,17 @@ export async function runCheck(opts) {
                 ...(headUpdatedAfterRemoval && { headUpdatedAfterRemoval: true }),
             },
         }),
+        ...(unreported.unreportedRequiredChecks && {
+            unreportedRequiredChecks: unreported.unreportedRequiredChecks,
+        }),
+        ...(unreported.trunkBehindBy !== undefined && { trunkBehindBy: unreported.trunkBehindBy }),
+        ...(unreported.actionsWorkflowInProgress && {
+            actionsWorkflowInProgress: true,
+        }),
+        ...(unreported.stackBottomPr !== undefined && { stackBottomPr: unreported.stackBottomPr }),
     };
     if (result.fingerprint) {
         await storePrFingerprint(stateKey, result.fingerprint, report, config);
     }
     return report;
 }
-async function remainingRuleAutoResolveIds(partition, autoMinimizeSuppressed = false) {
-    const consumedIds = autoMinimizeSuppressed
-        ? await selfApplySuppressedRuleAutoResolve(partition)
-        : { minimized: new Set(), resolvedThreads: new Set() };
-    return {
-        threadIds: partition.ruleAutoResolveThreadIds.filter((id) => !consumedIds.resolvedThreads.has(id)),
-        commentIds: partition.ruleAutoResolveCommentIds.filter((id) => !consumedIds.minimized.has(id)),
-        reviewSummaryIds: partition.ruleAutoResolveReviewSummaryIds.filter((id) => !consumedIds.minimized.has(id)),
-    };
-}
-async function selfApplySuppressedRuleAutoResolve(partition) {
-    const minimizeIds = [
-        ...partition.ruleAutoResolveCommentIds.filter((id) => partition.suppressedCommentIds.has(id)),
-        ...partition.ruleAutoResolveReviewSummaryIds.filter((id) => partition.suppressedReviewSummaryIds.has(id)),
-    ];
-    const threadIds = partition.ruleAutoResolveThreadIds.filter((id) => partition.suppressedThreadIds.has(id));
-    const [minimized, resolved] = await Promise.all([
-        minimizeIds.length > 0
-            ? autoMinimizeComments(minimizeIds)
-            : Promise.resolve({ minimized: [], errors: [] }),
-        threadIds.length > 0
-            ? autoResolveThreads(threadIds)
-            : Promise.resolve({ resolved: [], errors: [] }),
-    ]);
-    return {
-        minimized: new Set(minimized.minimized),
-        resolvedThreads: new Set(resolved.resolved),
-    };
-}

package/bin/commands/iterate/base.mjs

@@ -1,5 +1,7 @@
+import { ruleAutoResolveFromReport } from "../rule-auto-resolve-format.mjs";
 import { buildActiveChecks, buildRelevantChecks, buildSummary, buildSuppressedCheckFields, } from "./helpers.mjs";
 export function buildIterateBase(report, readyState) {
+    const ruleAutoResolve = ruleAutoResolveFromReport(report);
     return {
         pr: report.pr,
         repo: report.repo,
@@ -21,6 +23,13 @@ export function buildIterateBase(report, readyState) {
         ...buildSuppressedCheckFields(report),
         activity: report.activity,
         mergeQueue: report.mergeQueue,
+        ...(report.unreportedRequiredChecks &&
+            report.unreportedRequiredChecks.length > 0 && {
+            unreportedRequiredChecks: report.unreportedRequiredChecks,
+        }),
+        ...(report.trunkBehindBy !== undefined &&
+            report.trunkBehindBy > 0 && { trunkBehindBy: report.trunkBehindBy }),
         ...(report.fingerprintReused === true && { fingerprintReused: true }),
+        ...(ruleAutoResolve && { ruleAutoResolve }),
     };
 }

package/bin/commands/iterate/escalate.mjs

@@ -240,6 +240,10 @@ export function buildEscalateSuggestion(triggers, detail) {
         const duration = detail ?? "60 minutes";
         return `No progress detected for ${duration} — state has not changed. This is a manual checkpoint: inspect the PR and apply a manual fix before resuming.`;
     }
+    if (triggers.includes("required-checks-unreported")) {
+        const names = detail ? ` (${detail})` : "";
+        return `Required checks are still unreported after one close/reopen of this head${names}. Another reopen will not create a job the workflow does not emit. Path filters are the usual cause.`;
+    }
     if (triggers.includes("stall-state-unavailable")) {
         const reason = detail ?? "unknown error";
         return `The stall timer could not be saved (${reason}). Fix PR_SHEPHERD_STATE_DIR or the directory permissions, then resume. Automated polling is paused because a stuck loop would not be detected.`;