pr-shepherd 0.54.1 → 0.55.1

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,15 @@ 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.baseBehindBy !== undefined &&
+            report.baseBehindBy > 0 && { baseBehindBy: report.baseBehindBy }),
         ...(report.fingerprintReused === true && { fingerprintReused: true }),
+        ...(ruleAutoResolve && { ruleAutoResolve }),
     };
 }

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

@@ -4,7 +4,7 @@ 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
- * rebase/merge mechanics itself (see "Keep skills and loop prompts minimal" in CLAUDE.md); this
+ * 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

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

@@ -8,7 +8,7 @@ export function buildCrStaleClause(reviews) {
 /**
  * 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
- * rebase/merge mechanics itself (see "Keep skills and loop prompts minimal" in CLAUDE.md); this
+ * 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

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${names}, and no CI is running. Rebase and push is the fix when the branch is behind. This head is current, and another reopen will not create a job the workflow does not emit. Path filters are the usual cause. Investigate that, then handle the missing checks manually.`;
+    }
     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.`;

package/bin/commands/iterate/index.mjs

@@ -18,6 +18,7 @@ import { markReadyIfAuthorized } from "./mark-ready.mjs";
 import { withIterateApiUsage } from "./run.mjs";
 import { fetchRawSummaryPr } from "../../github/poll-summary.mjs";
 import { summarizePollSummaryPr } from "../../github/poll-summary-projector.mjs";
+import { annotationProbeUnavailable } from "../../github/poll-summary-annotation-probe.mjs";
 import { fingerprintRawSummaryPr } from "../../github/poll-summary-fingerprint.mjs";
 import { currentQueueRemovalEvent } from "../../github/poll-summary-queue-removal.mjs";
 import { isCurrentSummaryReady } from "../../github/poll-summary-readiness.mjs";
@@ -25,6 +26,7 @@ import { clearReadyReceipt, isReadyReceiptCurrent, readReadyReceipt, writeReadyR
 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";
 export function runIterate(opts) {
     return withIterateApiUsage(opts, () => runIterateCore(opts));
 }
@@ -122,6 +124,16 @@ async function runIterateCore(opts) {
     // readiness evidence, so a rerun (e.g. with --merge) does not wait again.
     const readyState = await updateReadyDelay(report.pr, isCleanReadyState, readyDelaySeconds, repoOwner, repoName, { headSha, alreadyElapsed: receiptCurrent });
     const base = buildIterateBase(reportForWork, readyState);
+    const unreportedPlan = await planUnreportedRequired({
+        report,
+        base,
+        stateKey: stallKey,
+        headSha,
+        otherAutonomousWork: hasActionableWork || staleAncestry !== null,
+    });
+    if (unreportedPlan.escalate)
+        return unreportedPlan.escalate;
+    const unreportedRepair = unreportedPlan.repairInstructions ?? [];
     // Checks (including merge-queue synthetic-commit checks) and hard conflicts are signals
     // GitHub itself is already acting on — the queue will eject the PR for these regardless of
     // what Shepherd does, so they always surface immediately. Only review threads/comments/
@@ -148,9 +160,36 @@ async function runIterateCore(opts) {
             surfacedApprovals,
             botUsernames,
             releasedCheckNames: blockerGate?.releasedNames,
+            ...((unreportedRepair.length > 0 || staleAncestry !== null) && {
+                repairInstructions: [...unreportedRepair, ...(staleAncestry?.instructions ?? [])],
+            }),
+            ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
+        });
+    }
+    if (unreportedRepair.length > 0 && staleAncestry) {
+        return handleFixCode({
+            base,
+            report: reportForWork,
+            opts: { ...opts, prNumber, neverCancelRuns },
+            headSha,
+            stallKey,
+            prNumber,
+            stallTimeoutSeconds,
+            repoOwner,
+            repoName,
+            reviewSummaryIds,
+            firstLookSummaries,
+            editedSummaries,
+            surfacedApprovals,
+            botUsernames,
+            releasedCheckNames: blockerGate?.releasedNames,
+            repairInstructions: [...unreportedRepair, ...staleAncestry.instructions],
             ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
         });
     }
+    if (unreportedRepair.length > 0) {
+        return annotateBlockedWait(await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, buildUnreportedFixResult(base, report, unreportedRepair), reportForWork, reviewSummaryIds), blockerGate);
+    }
     const mergeStateResult = await handleActiveMergeState({
         enabled: opts.merge,
         active: activeMerge,
@@ -182,7 +221,7 @@ async function runIterateCore(opts) {
             surfacedApprovals,
             botUsernames,
             releasedCheckNames: blockerGate?.releasedNames,
-            repairInstructions: staleAncestry.instructions,
+            repairInstructions: [...unreportedRepair, ...staleAncestry.instructions],
             ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
         });
     }
@@ -220,6 +259,17 @@ async function runIterateCore(opts) {
             log: `CANCEL: PR #${base.pr} ${cancelNote} — ready-delay elapsed, stopping`,
         };
     }
+    if (isCleanReadyState &&
+        readyState.isReady &&
+        !readyState.shouldCancel &&
+        readyState.remainingSeconds > 0) {
+        await clearStallState(stallKey);
+        return {
+            ...base,
+            action: "ready",
+            log: `READY: PR #${base.pr} is ready — ${readyState.remainingSeconds}s of ready-delay remaining — ${buildWaitLog(base).slice("WAIT: ".length)}`,
+        };
+    }
     const hold = stackDraftHold(report, autoMarkReady);
     const wait = {
         ...base,
@@ -238,14 +288,19 @@ async function recordReadyReceipt(key, report) {
         return false;
     try {
         const raw = await fetchRawSummaryPr(report.pr, { owner: key.owner, name: key.repo });
-        const fingerprint = fingerprintRawSummaryPr(raw);
-        if (fingerprint === null ||
+        if (fingerprintRawSummaryPr(raw) === null ||
             raw.state !== "OPEN" ||
             raw.isDraft ||
             raw.headRefOid !== report.headSha ||
             raw.baseRefOid !== report.baseRefOid)
             return false;
+        // Summarize hydrates annotation totals onto the snapshot before the stored hash.
         const summary = await summarizePollSummaryPr(raw, { owner: key.owner, name: key.repo }, { stackPrNumber: report.pr });
+        if (annotationProbeUnavailable(raw))
+            return false;
+        const fingerprint = fingerprintRawSummaryPr(raw);
+        if (fingerprint === null)
+            return false;
         if (!isCurrentSummaryReady(raw, summary.checks ?? {}, summary.review ?? {}))
             return false;
         const removalEvent = currentQueueRemovalEvent(raw);
@@ -290,6 +345,17 @@ async function revalidateReadyReceipt(key, report, hasReadinessWork) {
     }
     try {
         const raw = await fetchRawSummaryPr(report.pr, { owner: key.owner, name: key.repo });
+        const summary = await summarizePollSummaryPr(raw, { owner: key.owner, name: key.repo }, { stackPrNumber: report.pr });
+        if (annotationProbeUnavailable(raw)) {
+            const sameHead = raw.headRefOid === report.headSha;
+            const sameBase = retainQueuedReceipt || raw.baseRefOid === report.baseRefOid;
+            const stillReady = isCurrentSummaryReady(raw, summary.checks ?? {}, summary.review ?? {});
+            if (!sameHead || !sameBase || !stillReady) {
+                await clearReadyReceipt(key);
+                return false;
+            }
+            return true;
+        }
         // Queue predecessors can advance the target branch without changing this
         // PR's source. Compare against the receipt's base only while both fresh
         // views still place the PR in the queue.

package/bin/commands/iterate/merge-state.mjs

@@ -1,6 +1,6 @@
 import { clearStallState } from "../../state/iterate-stall.mjs";
 import { buildEscalateHumanMessage, buildEscalateSuggestion } from "./escalate.mjs";
-import { buildMergeCommandPlan } from "./merge.mjs";
+import { buildMergeCommandPlan, unavailableMergeResult } from "./merge.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
 import { buildPrShepherdCommand } from "../../cli/runner.mjs";
 import { inlineCode } from "../../util/markdown.mjs";
@@ -49,17 +49,17 @@ export function buildReadyMergeOutcome(enabled, readyElapsed, base, report) {
         return buildStackedRouteResult(base, report, stack);
     const queue = Boolean(report.mergeStatus.mergeRequirements?.mergeQueue?.required ||
         report.mergeStatus.mergeRequirements?.mergeQueue?.enabled);
-    return {
-        ...base,
-        action: "merge",
-        merge: buildMergeCommandPlan({
-            pr: report.pr,
-            repo: report.repo,
-            nodeId: report.nodeId,
-            headSha: report.headSha ?? "unknown",
-            queue,
-        }),
-    };
+    const plan = buildMergeCommandPlan({
+        pr: report.pr,
+        repo: report.repo,
+        nodeId: report.nodeId,
+        headSha: report.headSha ?? "unknown",
+        queue,
+        ...(report.allowedMergeMethods && { allowedMergeMethods: report.allowedMergeMethods }),
+    });
+    if ("unavailable" in plan)
+        return unavailableMergeResult(base, report, plan.unavailable);
+    return { ...base, action: "merge", merge: plan };
 }
 /** Raw counts of non-CI actionable work held back for one queued-PR wait tick. Omitted (all zero) when empty. */
 function buildDeferredWork(input) {

package/bin/commands/iterate/merge.d.mts

@@ -1,13 +1,23 @@
-import type { MergeCommandPlan } from "../../types.mts";
+import { type MergeMethod } from "../../config/merge-method.mts";
+import type { IterateResult, IterateResultBase, MergeCommandPlan } from "../../types.mts";
 interface MergePlanInput {
     pr: number;
     repo: string;
     nodeId: string;
     headSha: string;
     queue: boolean;
+    /** Omitted when the batch did not select repository merge settings. */
+    allowedMergeMethods?: readonly MergeMethod[];
 }
-export declare function buildMergeCommandPlan(input: MergePlanInput): MergeCommandPlan;
+export interface MergeMethodUnavailable {
+    unavailable: string;
+}
+export declare function buildMergeCommandPlan(input: MergePlanInput): MergeCommandPlan | MergeMethodUnavailable;
 export declare function renderMergeCommand(command: {
     argv: string[];
 }): string;
+export declare function unavailableMergeResult(base: IterateResultBase, report: {
+    pr: number;
+    repo: string;
+}, unavailable: string): IterateResult;
 export {};

package/bin/commands/iterate/merge.mjs

@@ -1,6 +1,9 @@
 import { loadConfig } from "../../config/load.mjs";
 import { findMergeStrategies } from "../../config/merge-command-args.mjs";
+import { chooseMergeMethod, configuredMergeMethod, } from "../../config/merge-method.mjs";
+import { formatPrUrl } from "../../pr-reference.mjs";
 import { renderShellCommand } from "../../cli/runner.mjs";
+import { buildEscalateHumanMessage } from "./escalate.mjs";
 const ENQUEUE_MUTATION = "mutation EnqueuePullRequest($pullRequestId: ID!, $expectedHeadOid: GitObjectID!) { enqueuePullRequest(input: { pullRequestId: $pullRequestId, expectedHeadOid: $expectedHeadOid }) { mergeQueueEntry { id } } }";
 export function buildMergeCommandPlan(input) {
     const base = [
@@ -32,9 +35,17 @@ export function buildMergeCommandPlan(input) {
             },
         };
     }
-    const configuredArgs = loadConfig().merge?.commandArgs ?? [];
+    const mergeConfig = loadConfig().merge;
+    const configuredArgs = mergeConfig?.commandArgs ?? [];
+    const decision = chooseMergeMethod({
+        allowed: input.allowedMergeMethods,
+        configured: configuredMergeMethod(mergeConfig ?? {}),
+        fallback: "merge",
+    });
+    if ("unavailable" in decision)
+        return decision;
     const hasStrategy = findMergeStrategies(configuredArgs).length > 0;
-    const commandArgs = hasStrategy ? configuredArgs : [...configuredArgs, "--merge"];
+    const commandArgs = hasStrategy ? configuredArgs : [...configuredArgs, `--${decision.method}`];
     return {
         mode: "auto",
         command: { argv: [...base, "--auto", ...commandArgs] },
@@ -44,3 +55,22 @@ export function buildMergeCommandPlan(input) {
 export function renderMergeCommand(command) {
     return renderShellCommand(command.argv);
 }
+export function unavailableMergeResult(base, report, unavailable) {
+    const escalateBase = {
+        triggers: ["merge-method-unavailable"],
+        unresolvedThreads: [],
+        ambiguousComments: [],
+        changesRequestedReviews: [],
+        suggestion: unavailable,
+    };
+    return {
+        ...base,
+        action: "escalate",
+        escalate: {
+            ...escalateBase,
+            humanMessage: buildEscalateHumanMessage(escalateBase, formatPrUrl(report.repo, report.pr), {
+                merge: true,
+            }),
+        },
+    };
+}

package/bin/commands/iterate/unreported-required.d.mts

@@ -0,0 +1,18 @@
+import type { IterateResult, IterateResultBase, ShepherdReport } from "../../types.mts";
+interface UnreportedPlan {
+    escalate?: IterateResult;
+    repairInstructions?: string[];
+}
+export declare function planUnreportedRequired(input: {
+    report: ShepherdReport;
+    base: IterateResultBase;
+    stateKey: {
+        owner: string;
+        repo: string;
+        pr: number;
+    };
+    headSha: string;
+    otherAutonomousWork: boolean;
+}): Promise<UnreportedPlan>;
+export declare function buildUnreportedFixResult(base: IterateResultBase, report: ShepherdReport, instructions: string[]): IterateResult;
+export {};

package/bin/commands/iterate/unreported-required.mjs

@@ -0,0 +1,136 @@
+import { buildPrShepherdCommand } from "../../cli/runner.mjs";
+import { formatPrUrl } from "../../pr-reference.mjs";
+import { readCiRetrigger, sameCiRetrigger, writeCiRetrigger } from "../../state/ci-retrigger.mjs";
+import { buildFixCompletionInstruction } from "./check-instructions.mjs";
+import { buildEscalateHumanMessage, buildEscalateSuggestion } from "./escalate.mjs";
+import { buildNativeStackRebaseInstruction } from "./native-stack-rebase.mjs";
+/** Rebase when the trunk or the PR base is behind; otherwise close and reopen once. */
+function decideUnreportedRequired(input) {
+    if (input.behind)
+        return "rebase";
+    if (input.alreadyRetriggered)
+        return input.otherAutonomousWork ? "none" : "escalate";
+    return "reopen";
+}
+function listedChecks(names) {
+    return names.map((name) => `\`${name}\``).join(", ");
+}
+/** Facts, then rebase-and-push, then investigate or escalate if that push does not start CI. */
+function buildUnreportedRequiredInstructions(input) {
+    const names = listedChecks(input.names);
+    const gap = input.behindBy > 0 && input.trunk
+        ? `The stack trunk is behind by ${input.behindBy} commits.`
+        : input.behindBy > 0
+            ? `This branch is behind \`${input.baseBranch}\` by ${input.behindBy} commits.`
+            : input.behind
+                ? "This PR's derived merge status is BEHIND."
+                : `This branch is not behind \`${input.baseBranch}\`.`;
+    const facts = `${gap} No CI checks are running, and required checks have not passed: ${names}.`;
+    if (!input.behind) {
+        return [
+            facts,
+            `Retrigger workflows once for this head with \`gh pr close ${input.pr} -R ${input.repo}\` then \`gh pr reopen ${input.pr} -R ${input.repo}\`.`,
+            "If those checks are still missing on the next poll, investigate why the workflows did not start. Do not close the PR again. Shepherd escalates with `required-checks-unreported` when this remains the only blocker.",
+        ];
+    }
+    const rebase = input.stackRebase
+        ? `${input.stackRebase} Then push the rewritten stack with \`gh stack push\`.`
+        : `Rebase onto \`${input.baseBranch}\` and push.`;
+    return [
+        facts,
+        `${rebase} Rebase and push is how these checks start.`,
+        "If that push does not start the checks, investigate why the workflows did not run. Shepherd escalates with `required-checks-unreported` when the branch is current and this remains the only blocker.",
+    ];
+}
+export async function planUnreportedRequired(input) {
+    const names = input.report.unreportedRequiredChecks ?? [];
+    const actionsRunning = input.report.actionsWorkflowInProgress === true || input.report.checks.inProgress.length > 0;
+    const failing = input.report.checks.failing.length > 0;
+    const conflicts = input.report.mergeStatus.status === "CONFLICTS";
+    const inQueue = input.report.mergeQueue?.inQueue === true;
+    if (names.length === 0 || actionsRunning || failing || conflicts || inQueue)
+        return {};
+    const behindBy = input.report.trunkBehindBy ?? input.report.baseBehindBy ?? 0;
+    const behind = behindBy > 0 || input.report.mergeStatus.status === "BEHIND";
+    const decision = decideUnreportedRequired({
+        behind,
+        alreadyRetriggered: sameCiRetrigger(await readCiRetrigger(input.stateKey), input.headSha, names),
+        otherAutonomousWork: input.otherAutonomousWork,
+    });
+    if (decision === "none")
+        return {};
+    if (decision === "escalate")
+        return { escalate: escalateUnreported(input.base, input.report, names) };
+    const rebase = stackRebase(input.report);
+    const instructions = buildUnreportedRequiredInstructions({
+        names,
+        repo: input.report.repo,
+        pr: input.report.pr,
+        baseBranch: input.report.baseBranch,
+        behind,
+        behindBy,
+        trunk: (input.report.trunkBehindBy ?? 0) > 0,
+        ...(rebase && { stackRebase: rebase }),
+    });
+    if (decision === "reopen") {
+        await writeCiRetrigger(input.stateKey, { headSha: input.headSha, contexts: names });
+    }
+    return { repairInstructions: instructions };
+}
+export function buildUnreportedFixResult(base, report, instructions) {
+    const prUrl = formatPrUrl(report.repo, report.pr);
+    return {
+        ...base,
+        action: "fix_code",
+        fix: {
+            threads: [],
+            resolutionOnlyThreads: [],
+            actionableComments: [],
+            reviewSummaryIds: [],
+            firstLookSummaries: [],
+            editedSummaries: [],
+            surfacedApprovals: [],
+            checks: [],
+            changesRequestedReviews: [],
+            resolveCommand: {
+                argv: buildPrShepherdCommand(["apply", "review", prUrl]).argv,
+                requiresHeadSha: false,
+                requiresDismissMessage: false,
+                hasMutations: false,
+            },
+            instructions: [...instructions, buildFixCompletionInstruction([])],
+            inProgressRunIds: [],
+            protectedRuns: [],
+            firstLookThreads: [],
+            firstLookComments: [],
+        },
+        cancelled: [],
+    };
+}
+function stackRebase(report) {
+    const stack = report.mergeStatus.mergeRequirements?.stack;
+    if (!stack)
+        return undefined;
+    const start = report.stackBottomPr !== undefined
+        ? { bottomPr: report.stackBottomPr }
+        : { trunk: stack.baseRefName };
+    return buildNativeStackRebaseInstruction(report.repo, stack.number, start);
+}
+function escalateUnreported(base, report, names) {
+    const detail = names.map((name) => `\`${name}\``).join(", ");
+    const escalateBase = {
+        triggers: ["required-checks-unreported"],
+        unresolvedThreads: [],
+        ambiguousComments: [],
+        changesRequestedReviews: [],
+        suggestion: buildEscalateSuggestion(["required-checks-unreported"], detail),
+    };
+    return {
+        ...base,
+        action: "escalate",
+        escalate: {
+            ...escalateBase,
+            humanMessage: buildEscalateHumanMessage(escalateBase, report.pr),
+        },
+    };
+}

package/bin/commands/poll-summary.mjs

@@ -31,6 +31,7 @@ async function runPollSummaryCore(opts) {
         reason: allTerminal ? "all_terminal" : actionable ? "actionable" : "waiting",
         prs: fetched.prs,
         ...(fetched.stackAncestry?.length && { stackAncestry: fetched.stackAncestry }),
+        ...(fetched.allowedMergeMethods && { allowedMergeMethods: fetched.allowedMergeMethods }),
     }, opts.merge === true);
     return applyStackStallGuard(planned, repo, opts.stallTimeoutSeconds ?? loadConfig().iterate.stallTimeoutMinutes * 60);
 }

package/bin/commands/poll.mjs

@@ -6,6 +6,10 @@ import { quotaPollIntervalMs } from "./poll-quota.mjs";
 import { onePrCancelFromPulls, onePrRateLimitTargets } from "./poll-rate-limit-cancel.mjs";
 import { createUntilTerminalRateLimitRetry } from "./poll-rate-limit-wait.mjs";
 import { writeDebounceProgress, writeWaitProgress } from "./poll-progress.mjs";
+function noteRuleAutoResolve(result) {
+    if (result.ruleAutoResolve?.summary)
+        process.stderr.write(`${result.ruleAutoResolve.summary}\n`);
+}
 const DEFAULT_POLL_DEBOUNCE_SECONDS = 60;
 const MAX_TIMER_MS = 2 ** 31 - 1;
 const TIMER_DRIFT_TOLERANCE_MS = 500;
@@ -38,8 +42,7 @@ async function runPollCore(opts) {
         const remainingBefore = untilTerminal
             ? Number.POSITIVE_INFINITY
             : timeoutMs - (Date.now() - start);
-        // Cache only internal continuation ticks. Last bounded tick, FIX_CODE debounce,
-        // and any tick we return to the caller must fetch BatchPr.
+        // Cache only internal continuation ticks; returned ticks must fetch BatchPr.
         const allowCache = debounceUntil === null && remainingBefore + TIMER_DRIFT_TOLERANCE_MS >= intervalMs;
         const iterateTick = (fingerprintCache) => runIterate({
             ...iterateOpts,
@@ -89,6 +92,7 @@ async function runPollCore(opts) {
             if (lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) {
                 debounceUntil ??= Date.now() + debounceMs;
                 const remainingMs = Math.max(debounceUntil - Date.now(), 0);
+                noteRuleAutoResolve(lastResult);
                 writeDebounceProgress(tick, Date.now() - start, remainingMs);
                 await sleep(Math.min(intervalMs, remainingMs));
                 continue;
@@ -123,6 +127,7 @@ async function runPollCore(opts) {
                 verbose,
                 lastWaitSignature,
             });
+            noteRuleAutoResolve(lastResult);
             await sleep(sleepMs);
             continue;
         }
@@ -139,10 +144,12 @@ async function runPollCore(opts) {
                     break;
                 }
             }
+            noteRuleAutoResolve(lastResult);
             await sleep(sleepMs);
             continue;
         }
         if (lastResult.action === "fix_code" && debounceSeconds > 0 && !pastDebounce) {
+            noteRuleAutoResolve(lastResult);
             debounceUntil ??= Date.now() + debounceMs;
             const remainingMs = debounceUntil - Date.now();
             if (remainingMs > 0) {

package/bin/commands/ready-mergeability.d.mts

@@ -10,6 +10,6 @@ export declare function refreshUnknownMergeability(prNumber: number, repo: RepoI
     batchData: BatchPrData;
     didRefresh: boolean;
 }>;
-export declare function refreshReadyMergeability(prNumber: number, repo: RepoInfo, batchData: BatchPrData, verdict: CiVerdict, unresolvedThreads: number, unresolvedComments: number, changesRequestedCount: number): Promise<ReadyMergeabilityRefresh>;
+export declare function refreshReadyMergeability(prNumber: number, repo: RepoInfo, batchData: BatchPrData, verdict: CiVerdict, unresolvedThreads: number, unresolvedComments: number, changesRequestedCount: number, hasUnreportedRequired?: boolean): Promise<ReadyMergeabilityRefresh>;
 export declare function isBlockedByFilteredCheck(mergeStatus: MergeStatusResult, verdict: CiVerdict): boolean;
 export {};

package/bin/commands/ready-mergeability.mjs

@@ -8,10 +8,10 @@ export async function refreshUnknownMergeability(prNumber, repo, batchData) {
     }
     return { batchData: await readMergeability(prNumber, repo, batchData), didRefresh: true };
 }
-export async function refreshReadyMergeability(prNumber, repo, batchData, verdict, unresolvedThreads, unresolvedComments, changesRequestedCount) {
+export async function refreshReadyMergeability(prNumber, repo, batchData, verdict, unresolvedThreads, unresolvedComments, changesRequestedCount, hasUnreportedRequired = false) {
     const refreshedBatchData = await readMergeability(prNumber, repo, batchData);
     const mergeStatus = deriveMergeStatus(refreshedBatchData);
-    const status = computeStatus(verdict, unresolvedThreads, unresolvedComments, mergeStatus, changesRequestedCount);
+    const status = computeStatus(verdict, unresolvedThreads, unresolvedComments, mergeStatus, changesRequestedCount, hasUnreportedRequired);
     return { batchData: refreshedBatchData, mergeStatus, status };
 }
 export function isBlockedByFilteredCheck(mergeStatus, verdict) {

package/bin/commands/rule-auto-resolve-format.d.mts

@@ -0,0 +1,22 @@
+import type { AutoMinimizedItem, AutoResolvedThread, RuleAutoResolveReport, ShepherdReport } from "../types.mts";
+export declare function uniqueReasons(reasons: readonly string[]): string[];
+export declare function reasonClause(reasons: readonly string[]): string | undefined;
+export declare function ruleAutoResolveBody(counts: {
+    threads: number;
+    comments: number;
+    reviewSummaries: number;
+}): string | undefined;
+export declare function formatRuleAutoResolveJournalItem(input: {
+    body: string;
+    reasons: readonly string[];
+    viewerLogin?: string;
+    urls: readonly string[];
+}): string;
+export declare function decorateAutoResolveError(error: string, reasons: readonly string[]): string;
+export declare function reasonsForError(error: string, ids: readonly string[], ruleReasons: ReadonlyMap<string, readonly string[]>): string[];
+export declare function ruleAutoResolveFromReport(report: ShepherdReport): RuleAutoResolveReport | undefined;
+export declare function projectRuleAutoResolve(event: RuleAutoResolveReport): Record<string, unknown>;
+export declare function insertRuleAutoResolveSection(text: string, event: RuleAutoResolveReport | undefined): string;
+export declare function stripReplayedRuleAutoResolve(report: ShepherdReport): ShepherdReport;
+export declare function minimizedItem(kind: AutoMinimizedItem["kind"], id: string, url: string | undefined, reasons: readonly string[]): AutoMinimizedItem;
+export declare function resolvedThread(thread: AutoResolvedThread, reasons: readonly string[]): AutoResolvedThread;