pr-shepherd 0.54.1 → 0.55.0

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,122 @@
+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 buildUnreportedRequiredInstruction(input) {
+    const listed = input.names.map((name) => `\`${name}\``).join(", ");
+    const observed = input.trunkBehindBy !== undefined && input.trunkBehindBy > 0
+        ? `The stack trunk compare is behind by ${input.trunkBehindBy}.`
+        : input.behind
+            ? "This PR's derived merge status is BEHIND."
+            : "The stack trunk compare is not behind and this PR's derived merge status is not BEHIND.";
+    const update = input.stackRebase
+        ? `${input.stackRebase} Then push the rewritten stack with \`gh stack push\`.`
+        : `Rebase or otherwise update the PR branch from \`${input.baseBranch}\` according to repository conventions, then push.`;
+    return [
+        `Required status checks have no check run and no status context on this head, and no Actions workflow is running: ${listed}.`,
+        observed,
+        `If the stack trunk is behind or this PR is behind its base, update the branch so a pull_request synchronize event runs: ${update}`,
+        `Otherwise retrigger workflows once for this head with \`gh pr close ${input.pr} -R ${input.repo}\` then \`gh pr reopen ${input.pr} -R ${input.repo}\`.`,
+        "Do not close the PR again if those checks are still missing on the next poll.",
+    ].join(" ");
+}
+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 behind = (input.report.trunkBehindBy ?? 0) > 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 instruction = buildUnreportedRequiredInstruction({
+        names,
+        repo: input.report.repo,
+        pr: input.report.pr,
+        baseBranch: input.report.baseBranch,
+        behind,
+        ...(input.report.trunkBehindBy !== undefined && { trunkBehindBy: input.report.trunkBehindBy }),
+        ...(rebase && { stackRebase: rebase }),
+    });
+    if (decision === "reopen") {
+        await writeCiRetrigger(input.stateKey, { headSha: input.headSha, contexts: names });
+    }
+    return { repairInstructions: [instruction] };
+}
+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;

package/bin/commands/rule-auto-resolve-format.mjs

@@ -0,0 +1,151 @@
+export function uniqueReasons(reasons) {
+    const unique = [];
+    for (const reason of reasons) {
+        const cleaned = reason.trim();
+        if (cleaned && !unique.includes(cleaned))
+            unique.push(cleaned);
+    }
+    return unique;
+}
+export function reasonClause(reasons) {
+    const unique = uniqueReasons(reasons);
+    if (unique.length === 0)
+        return undefined;
+    const label = unique.length === 1 ? "rule" : "rules";
+    return `(${label}: ${unique.join("; ")})`;
+}
+function joinedReason(reasons) {
+    const unique = uniqueReasons(reasons);
+    return unique.length > 0 ? unique.join("; ") : undefined;
+}
+function plural(count, singular, pluralForm = `${singular}s`) {
+    return `${count} ${count === 1 ? singular : pluralForm}`;
+}
+export function ruleAutoResolveBody(counts) {
+    const parts = [];
+    if (counts.threads > 0)
+        parts.push(`auto-resolved ${plural(counts.threads, "thread")}`);
+    const minimized = [];
+    if (counts.comments > 0)
+        minimized.push(plural(counts.comments, "comment"));
+    if (counts.reviewSummaries > 0) {
+        minimized.push(plural(counts.reviewSummaries, "review summary", "review summaries"));
+    }
+    if (minimized.length > 0)
+        parts.push(`minimized ${minimized.join(" and ")}`);
+    return parts.length > 0 ? parts.join(", ") : undefined;
+}
+function withReasonClause(body, reasons) {
+    const clause = reasonClause(reasons);
+    return clause ? `${body} ${clause}` : body;
+}
+export function formatRuleAutoResolveJournalItem(input) {
+    const login = input.viewerLogin?.trim();
+    const actor = login ? `as @${login}` : "(token login unavailable)";
+    const clause = reasonClause(input.reasons);
+    const links = input.urls.map((url) => url.trim()).filter(Boolean);
+    const reasonSuffix = clause ? ` ${clause}` : "";
+    const linkSuffix = links.length > 0 ? `: ${links.join(", ")}` : "";
+    return `- ${input.body} ${actor}${reasonSuffix}${linkSuffix}`;
+}
+export function decorateAutoResolveError(error, reasons) {
+    const clause = reasonClause(reasons);
+    return clause ? `${error} ${clause}` : error;
+}
+export function reasonsForError(error, ids, ruleReasons) {
+    const id = ids.find((candidate) => error.startsWith(`${candidate}:`));
+    if (id)
+        return [...(ruleReasons.get(id) ?? [])];
+    if (!error.startsWith("rate limit:"))
+        return [];
+    return uniqueReasons(ids.flatMap((candidate) => [...(ruleReasons.get(candidate) ?? [])]));
+}
+function splitJoined(reason) {
+    if (!reason)
+        return [];
+    return reason.split("; ").filter(Boolean);
+}
+export function ruleAutoResolveFromReport(report) {
+    const threads = report.threads.autoResolved;
+    const minimized = report.comments.autoMinimized ?? [];
+    const errors = report.threads.autoResolveErrors;
+    if (threads.length === 0 && minimized.length === 0 && errors.length === 0)
+        return undefined;
+    const comments = minimized.filter((item) => item.kind === "pr-comment").length;
+    const reviewSummaries = minimized.filter((item) => item.kind === "review-summary").length;
+    const success = threads.length + minimized.length > 0;
+    const reasons = success
+        ? uniqueReasons([
+            ...threads.flatMap((thread) => splitJoined(thread.ruleReason)),
+            ...minimized.flatMap((item) => splitJoined(item.ruleReason)),
+        ])
+        : uniqueReasons(report.threads.autoResolveErrorReasons ?? []);
+    const body = ruleAutoResolveBody({ threads: threads.length, comments, reviewSummaries }) ??
+        `auto-resolve failed for ${plural(errors.length, "mutation")}`;
+    return {
+        summary: withReasonClause(body, reasons),
+        ...(threads.length > 0 && { threads }),
+        ...(minimized.length > 0 && { minimized }),
+        ...(errors.length > 0 && { errors }),
+    };
+}
+function formatRuleAutoResolveSection(event) {
+    if (!event)
+        return null;
+    const lines = ["## Classification auto-resolve", "", event.summary];
+    const links = [
+        ...(event.threads ?? []).map((thread) => thread.url.trim() || `\`${thread.id}\``),
+        ...(event.minimized ?? []).map((item) => item.url?.trim() || `\`${item.id}\``),
+    ];
+    if (links.length > 0)
+        lines.push("", ...links.map((link) => `- ${link}`));
+    if ((event.errors?.length ?? 0) > 0) {
+        lines.push("", ...(event.errors ?? []).map((error) => `- ${error}`));
+    }
+    return lines.join("\n");
+}
+export function projectRuleAutoResolve(event) {
+    return {
+        summary: event.summary,
+        ...((event.threads?.length ?? 0) > 0 && { threads: event.threads }),
+        ...((event.minimized?.length ?? 0) > 0 && { minimized: event.minimized }),
+        ...((event.errors?.length ?? 0) > 0 && { errors: event.errors }),
+    };
+}
+export function insertRuleAutoResolveSection(text, event) {
+    const section = formatRuleAutoResolveSection(event);
+    if (!section)
+        return text;
+    const index = text.lastIndexOf("## Instructions");
+    if (index === -1)
+        return `${text}\n\n${section}`;
+    return `${text.slice(0, index)}${section}\n\n${text.slice(index)}`;
+}
+export function stripReplayedRuleAutoResolve(report) {
+    const hasEvent = report.threads.autoResolved.length > 0 ||
+        report.threads.autoResolveErrors.length > 0 ||
+        (report.threads.autoResolveErrorReasons?.length ?? 0) > 0 ||
+        (report.comments.autoMinimized?.length ?? 0) > 0;
+    if (!hasEvent)
+        return report;
+    const { autoMinimized: _autoMinimized, ...comments } = report.comments;
+    const { autoResolveErrorReasons: _autoResolveErrorReasons, ...threads } = report.threads;
+    return {
+        ...report,
+        threads: { ...threads, autoResolved: [], autoResolveErrors: [] },
+        comments,
+    };
+}
+export function minimizedItem(kind, id, url, reasons) {
+    const ruleReason = joinedReason(reasons);
+    return {
+        id,
+        kind,
+        ...(url?.trim() ? { url: url.trim() } : {}),
+        ...(ruleReason ? { ruleReason } : {}),
+    };
+}
+export function resolvedThread(thread, reasons) {
+    const ruleReason = joinedReason(reasons);
+    return { ...thread, isResolved: true, ...(ruleReason ? { ruleReason } : {}) };
+}