pr-shepherd 0.54.1 → 0.55.1

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 } : {}) };
+}

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

@@ -0,0 +1,21 @@
+import type { BatchPartition } from "../classify/apply.mts";
+import type { AutoMinimizedItem, AutoResolvedThread, BatchPrData } from "../types.mts";
+export interface RuleAutoResolveApplied {
+    threadIds: string[];
+    commentIds: string[];
+    reviewSummaryIds: string[];
+    autoResolved: AutoResolvedThread[];
+    autoMinimized: AutoMinimizedItem[];
+    autoResolveErrors: string[];
+    errorReasons: string[];
+}
+export declare function applySuppressedRuleAutoResolve(input: {
+    enabled: boolean;
+    partition: BatchPartition;
+    batch: BatchPrData;
+    prNumber: number;
+    repo: {
+        owner: string;
+        name: string;
+    };
+}): Promise<RuleAutoResolveApplied>;

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

@@ -0,0 +1,113 @@
+import { autoMinimizeComments, autoResolveThreads } from "../comments/resolve.mjs";
+import { runJournal } from "./journal/index.mjs";
+import { decorateAutoResolveError, formatRuleAutoResolveJournalItem, minimizedItem, reasonClause, reasonsForError, resolvedThread, ruleAutoResolveBody, uniqueReasons, } from "./rule-auto-resolve-format.mjs";
+const EMPTY = {
+    threadIds: [],
+    commentIds: [],
+    reviewSummaryIds: [],
+    autoResolved: [],
+    autoMinimized: [],
+    autoResolveErrors: [],
+    errorReasons: [],
+};
+function idsIn(ids, confirmed) {
+    return ids.filter((id) => confirmed.has(id));
+}
+function decorateErrors(errors, ids, ruleReasons) {
+    return errors.map((error) => decorateAutoResolveError(error, reasonsForError(error, ids, ruleReasons)));
+}
+function successReasons(ids, ruleReasons) {
+    return uniqueReasons(ids.flatMap((id) => [...(ruleReasons.get(id) ?? [])]));
+}
+export async function applySuppressedRuleAutoResolve(input) {
+    if (!input.enabled) {
+        return {
+            ...EMPTY,
+            threadIds: input.partition.ruleAutoResolveThreadIds,
+            commentIds: input.partition.ruleAutoResolveCommentIds,
+            reviewSummaryIds: input.partition.ruleAutoResolveReviewSummaryIds,
+        };
+    }
+    const commentIds = input.partition.ruleAutoResolveCommentIds.filter((id) => input.partition.suppressedCommentIds.has(id));
+    const reviewSummaryIds = input.partition.ruleAutoResolveReviewSummaryIds.filter((id) => input.partition.suppressedReviewSummaryIds.has(id));
+    const threadIds = input.partition.ruleAutoResolveThreadIds.filter((id) => input.partition.suppressedThreadIds.has(id));
+    const minimizeIds = [...commentIds, ...reviewSummaryIds];
+    const [minimized, resolved] = await Promise.all([
+        minimizeIds.length > 0
+            ? autoMinimizeComments(minimizeIds)
+            : Promise.resolve({ minimized: [], errors: [] }),
+        threadIds.length > 0
+            ? autoResolveThreads(threadIds)
+            : Promise.resolve({ resolved: [], errors: [] }),
+    ]);
+    const minimizedSet = new Set(minimized.minimized);
+    const resolvedSet = new Set(resolved.resolved);
+    const resolvedIds = idsIn(threadIds, resolvedSet);
+    const minimizedCommentIds = idsIn(commentIds, minimizedSet);
+    const minimizedSummaryIds = idsIn(reviewSummaryIds, minimizedSet);
+    const threadsById = new Map(input.batch.reviewThreads.map((thread) => [thread.id, thread]));
+    const commentsById = new Map(input.batch.comments.map((comment) => [comment.id, comment]));
+    const summariesById = new Map(input.batch.reviewSummaries.map((review) => [review.id, review]));
+    const autoResolved = resolvedIds.flatMap((id) => {
+        const thread = threadsById.get(id);
+        return thread ? [resolvedThread(thread, input.partition.ruleReasons.get(id) ?? [])] : [];
+    });
+    const autoMinimized = [
+        ...minimizedCommentIds.map((id) => minimizedItem("pr-comment", id, commentsById.get(id)?.url, input.partition.ruleReasons.get(id) ?? [])),
+        ...minimizedSummaryIds.map((id) => minimizedItem("review-summary", id, summariesById.get(id)?.url, input.partition.ruleReasons.get(id) ?? [])),
+    ];
+    const autoResolveErrors = [
+        ...decorateErrors(minimized.errors, minimizeIds, input.partition.ruleReasons),
+        ...decorateErrors(resolved.errors, threadIds, input.partition.ruleReasons),
+    ];
+    const errorReasons = uniqueReasons([
+        ...minimized.errors.flatMap((error) => reasonsForError(error, minimizeIds, input.partition.ruleReasons)),
+        ...resolved.errors.flatMap((error) => reasonsForError(error, threadIds, input.partition.ruleReasons)),
+    ]);
+    const journalError = await journalSuccesses(input, autoResolved, autoMinimized);
+    if (journalError)
+        autoResolveErrors.push(journalError);
+    return {
+        threadIds: input.partition.ruleAutoResolveThreadIds.filter((id) => !resolvedSet.has(id)),
+        commentIds: input.partition.ruleAutoResolveCommentIds.filter((id) => !minimizedSet.has(id)),
+        reviewSummaryIds: input.partition.ruleAutoResolveReviewSummaryIds.filter((id) => !minimizedSet.has(id)),
+        autoResolved,
+        autoMinimized,
+        autoResolveErrors,
+        errorReasons,
+    };
+}
+async function journalSuccesses(input, autoResolved, autoMinimized) {
+    const body = ruleAutoResolveBody({
+        threads: autoResolved.length,
+        comments: autoMinimized.filter((item) => item.kind === "pr-comment").length,
+        reviewSummaries: autoMinimized.filter((item) => item.kind === "review-summary").length,
+    });
+    if (!body)
+        return undefined;
+    const ids = [...autoResolved.map((thread) => thread.id), ...autoMinimized.map((item) => item.id)];
+    const reasons = successReasons(ids, input.partition.ruleReasons);
+    const item = formatRuleAutoResolveJournalItem({
+        body,
+        reasons,
+        ...(input.batch.viewerLogin ? { viewerLogin: input.batch.viewerLogin } : {}),
+        urls: [
+            ...autoResolved.map((thread) => thread.url),
+            ...autoMinimized.map((item) => item.url ?? ""),
+        ],
+    });
+    try {
+        await runJournal({
+            prNumber: input.prNumber,
+            targetRepository: { owner: input.repo.owner, name: input.repo.name },
+            rawItem: item,
+            dryRun: false,
+        });
+        return undefined;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const clause = reasonClause(reasons);
+        return clause ? `journal: ${message} ${clause}` : `journal: ${message}`;
+    }
+}

package/bin/commands/shepherd-journal.d.mts

@@ -9,6 +9,6 @@ export declare const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review each body un
  * Build the Shepherd Journal instruction step. The reference-citation convention (link
  * threads/comments from their headings, cite reviews by ID) is invariant across every
  * invocation, so it lives in the pr-shepherd skill's "Shepherd Journal" playbook instead
- * of being re-emitted every tick (see CLAUDE.md "Keep skills and loop prompts minimal").
+ * of being re-emitted every tick (see AGENTS.md "Keep skills and loop prompts minimal").
  */
 export declare function buildShepherdJournalInstruction(prReference: string | number): string;

package/bin/commands/shepherd-journal.mjs

@@ -10,7 +10,7 @@ export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review each body under `##
  * Build the Shepherd Journal instruction step. The reference-citation convention (link
  * threads/comments from their headings, cite reviews by ID) is invariant across every
  * invocation, so it lives in the pr-shepherd skill's "Shepherd Journal" playbook instead
- * of being re-emitted every tick (see CLAUDE.md "Keep skills and loop prompts minimal").
+ * of being re-emitted every tick (see AGENTS.md "Keep skills and loop prompts minimal").
  */
 export function buildShepherdJournalInstruction(prReference) {
     // Single-quote the placeholder so a substituted decision stays literal in the shell.

package/bin/commands/stack-drain.d.mts

@@ -7,11 +7,6 @@ export interface StackPlan {
     idle?: PollSummaryItem[];
     instructions: string[];
 }
-/**
- * Merge the ready prefix by its highest PR number. `gh stack merge <n>` tries a
- * stack number first, but stack numbers come from the repository's issue and
- * pull request sequence, so a PR number never names a stack.
- */
 export declare function planPrefixDrain(result: PollSummaryResult, mergeRequested: boolean): StackPlan | undefined;
 /**
  * A merge-requested, fully ready stack whose bottom open layer still targets

package/bin/commands/stack-drain.mjs

@@ -1,11 +1,6 @@
+import { stackMergeFlag } from "./stack-merge-flag.mjs";
 import { stackLayerBlockReason } from "./stack-layer-readiness.mjs";
 import { appendMarkReadyInstructions, splitStackWork } from "./stack-work.mjs";
-/**
- * Highest open layer such that it and every open layer below it are ready to
- * merge together. `gh stack merge <PR>` lands that PR and every unmerged layer
- * below it. A merge queue accepts the same prefix and evaluates each layer
- * from the bottom; a failure ejects that layer and those above it.
- */
 function readyPrefixTop(result) {
     const layers = [...result.prs].sort((left, right) => stackPosition(left) - stackPosition(right));
     if (layers.some((item) => item.state === "OPEN" && item.isInMergeQueue))
@@ -29,11 +24,6 @@ function readyPrefixTop(result) {
     }
     return top;
 }
-/**
- * Merge the ready prefix by its highest PR number. `gh stack merge <n>` tries a
- * stack number first, but stack numbers come from the repository's issue and
- * pull request sequence, so a PR number never names a stack.
- */
 export function planPrefixDrain(result, mergeRequested) {
     if (!mergeRequested)
         return undefined;
@@ -49,8 +39,16 @@ export function planPrefixDrain(result, mergeRequested) {
         item.action !== "escalate" &&
         (!isStackLayerReady(item) || staleChildren.has(item.pr))), staleChildren);
     const span = open[0]?.pr === top.pr ? "that layer alone" : `PR #${top.pr} and every unmerged layer below it`;
+    const method = stackMergeFlag(result.allowedMergeMethods);
+    if ("unavailable" in method) {
+        return {
+            action: "escalate",
+            stackMergeable: false,
+            instructions: [`1. ${method.unavailable}`],
+        };
+    }
     const instructions = [
-        `1. PR #${top.pr} is the highest open layer of stack #${top.stack.number} in \`${result.repo}\` whose open lower layers are all ready. Run \`GH_REPO=${result.repo} gh stack merge ${top.pr} --yes --squash\` to merge ${span}. When the base uses a merge queue, the same command queues that prefix together and GitHub evaluates each layer from the bottom; a failure ejects that layer and the layers above it. If \`gh stack\` is an unknown command, run \`gh extension install github/gh-stack\` first.`,
+        `1. PR #${top.pr} is the highest open layer of stack #${top.stack.number} in \`${result.repo}\` whose open lower layers are all ready. Run \`GH_REPO=${result.repo} gh stack merge ${top.pr} --yes ${method.flag}\` to merge ${span}. When the base uses a merge queue, the same command queues that prefix together and GitHub evaluates each layer from the bottom; a failure ejects that layer and the layers above it. If \`gh stack\` is an unknown command, run \`gh extension install github/gh-stack\` first.`,
     ];
     appendAutonomousInstructions(instructions, above.sessions);
     appendMarkReadyInstructions(instructions, above.markReady);
@@ -90,17 +88,29 @@ export function idleWaitPlan(idle) {
         ],
     };
 }
+function sessionInstruction(item) {
+    if (!item.owned)
+        return ` PR #${item.pr} is not owned. Do not run a session for it.`;
+    const removal = item.queueRemoval
+        ? ` PR #${item.pr} was removed from the merge queue (\`${item.queueRemoval.reason ?? "unknown reason"}\`${item.queueRemoval.actor ? ` by @${item.queueRemoval.actor}` : ""}).`
+        : "";
+    if (!item.pollCommand) {
+        return ` PR #${item.pr} needs a one-PR Shepherd session, but no command was available.`;
+    }
+    const queueNote = item.queueRemoval
+        ? " That session fixes failing queue CI, or escalates when the removal has no concrete fix."
+        : "";
+    return `${removal} Run \`${item.pollCommand}\` for PR #${item.pr}.${queueNote}`;
+}
 export function describeIdleLayers(idle) {
     return idle.map((item) => `PR #${item.pr} (${item.reasons.join(", ")})`).join("; ");
 }
 export function appendAutonomousInstructions(instructions, candidates) {
     if (candidates.length === 0)
         return;
-    instructions.push(`${instructions.length + 1}. Start or delegate the relevant one-PR sessions below; review and CI work on separate layers can proceed concurrently.`);
+    instructions.push(`${instructions.length + 1}. Start or delegate one-PR sessions only for rows marked \`owned\`. Leave every other author's layer untouched. Owned layers can proceed concurrently.`);
     for (const item of candidates) {
-        instructions.push(item.pollCommand
-            ? `${instructions.length + 1}. Run \`${item.pollCommand}\` for PR #${item.pr}${item.queueRemoval ? `; GitHub removed it from the merge queue (${item.queueRemoval.reason ?? "unknown reason"})` : ""}.`
-            : `${instructions.length + 1}. PR #${item.pr} needs a one-PR Shepherd session, but no command was available.`);
+        instructions.push(`${instructions.length + 1}.${sessionInstruction(item)}`);
     }
 }
 export function findHumanHandoffs(result) {

package/bin/commands/stack-merge-flag.d.mts

@@ -0,0 +1,7 @@
+import { type MergeMethod } from "../config/merge-method.mts";
+/** Stack commands prefer squash unless config or the repository selects another method. */
+export declare function stackMergeFlag(allowed: readonly MergeMethod[] | undefined): {
+    flag: string;
+} | {
+    unavailable: string;
+};

package/bin/commands/stack-merge-flag.mjs

@@ -0,0 +1,6 @@
+import { loadConfig } from "../config/load.mjs";
+import { configuredMergeMethod, mergeMethodFlag, } from "../config/merge-method.mjs";
+/** Stack commands prefer squash unless config or the repository selects another method. */
+export function stackMergeFlag(allowed) {
+    return mergeMethodFlag(allowed, "squash", configuredMergeMethod(loadConfig().merge ?? {}));
+}

package/bin/config/load.d.mts

@@ -1,3 +1,4 @@
+import { type MergeMethod } from "./merge-method.mts";
 declare const MINIMIZE_COMMENTS_POLICIES: readonly ["all", "bots", "users", "none"];
 export type MinimizeCommentsPolicy = (typeof MINIMIZE_COMMENTS_POLICIES)[number];
 declare const RESOLVE_OTHER_HUMAN_THREADS: readonly ["none", "outdated", "always"];
@@ -70,6 +71,8 @@ export interface PrShepherdConfig {
         blockingReviewerLogins: string[];
     };
     merge?: {
+        /** Preferred merge method. Used only when the repository allows it. */
+        method?: MergeMethod;
         /** Options added to ordinary `gh pr merge` commands. Queue commands never use these. */
         commandArgs: string[];
     };

package/bin/config/load.mjs

@@ -6,6 +6,7 @@ import { parse } from "yaml";
 import builtins from "../config.json" with { type: "json" };
 import { getEffectiveCwd } from "../execution-context.mjs";
 import { findMergeStrategies } from "./merge-command-args.mjs";
+import { parseMergeMethod } from "./merge-method.mjs";
 const MINIMIZE_COMMENTS_POLICIES = ["all", "bots", "users", "none"];
 const RESOLVE_OTHER_HUMAN_THREADS = ["none", "outdated", "always"];
 const RC_FILENAME = ".pr-shepherdrc.yml";
@@ -143,7 +144,7 @@ function parseMergeCommandArgs(value) {
     if (strategies.length > 1) {
         throw new Error(`Invalid config: merge.commandArgs includes multiple merge strategies: ${strategies.join(", ")}`);
     }
-    return strategies.length === 0 ? [...value, "--merge"] : [...value];
+    return [...value];
 }
 function parsePollConfig(value) {
     if (value === null || typeof value !== "object" || Array.isArray(value)) {
@@ -279,7 +280,7 @@ const KNOWN_NESTED_KEYS = {
     resolve: new Set(["shaPoll"]),
     checks: new Set(["ciTriggerEvents", "ignoreLogLines"]),
     mergeStatus: new Set(["blockingReviewerLogins"]),
-    merge: new Set(["commandArgs"]),
+    merge: new Set(["commandArgs", "method"]),
     actions: new Set([
         "autoMinimizeSuppressed",
         "autoMarkReady",
@@ -321,6 +322,12 @@ function parseConfig(value, normalizeMergeArgs = true) {
     config.actions.neverCancelRuns = parseNeverCancelRuns(config.actions.neverCancelRuns);
     if (config.merge && normalizeMergeArgs) {
         config.merge.commandArgs = parseMergeCommandArgs(config.merge.commandArgs);
+        if (config.merge.method !== undefined)
+            config.merge.method = parseMergeMethod(config.merge.method);
+        const fromArgs = findMergeStrategies(config.merge.commandArgs)[0];
+        if (config.merge.method && fromArgs && fromArgs !== config.merge.method) {
+            throw new Error(`Invalid config: merge.method ${config.merge.method} conflicts with merge.commandArgs strategy ${fromArgs}`);
+        }
     }
     config.poll = parsePollConfig(config.poll);
     config.watch.graphqlQuotaWarnings = parseGraphqlQuotaWarnings(config.watch.graphqlQuotaWarnings, config.poll.intervalSeconds);

package/bin/config/merge-method.d.mts

@@ -0,0 +1,27 @@
+export type MergeMethod = "merge" | "squash" | "rebase";
+export interface RepositoryMergeSettings {
+    mergeCommitAllowed?: boolean;
+    squashMergeAllowed?: boolean;
+    rebaseMergeAllowed?: boolean;
+}
+/** `undefined` when the query did not select repository merge settings. */
+export declare function readAllowedMergeMethods(repository: RepositoryMergeSettings | null | undefined): MergeMethod[] | undefined;
+export declare function parseMergeMethod(value: unknown): MergeMethod;
+export declare function configuredMergeMethod(merge: {
+    method?: MergeMethod;
+    commandArgs?: string[];
+}): MergeMethod | null;
+export declare function chooseMergeMethod(input: {
+    allowed: readonly MergeMethod[] | undefined;
+    configured: MergeMethod | null;
+    fallback: MergeMethod;
+}): {
+    method: MergeMethod;
+} | {
+    unavailable: string;
+};
+export declare function mergeMethodFlag(allowed: readonly MergeMethod[] | undefined, fallback: MergeMethod, configured: MergeMethod | null): {
+    flag: string;
+} | {
+    unavailable: string;
+};

package/bin/config/merge-method.mjs

@@ -0,0 +1,56 @@
+import { findMergeStrategies } from "./merge-command-args.mjs";
+const MERGE_METHODS = new Set(["merge", "squash", "rebase"]);
+const METHOD_ORDER = ["merge", "squash", "rebase"];
+/** `undefined` when the query did not select repository merge settings. */
+export function readAllowedMergeMethods(repository) {
+    if (!repository ||
+        (repository.mergeCommitAllowed === undefined &&
+            repository.squashMergeAllowed === undefined &&
+            repository.rebaseMergeAllowed === undefined)) {
+        return undefined;
+    }
+    const allowed = [];
+    if (repository.mergeCommitAllowed)
+        allowed.push("merge");
+    if (repository.squashMergeAllowed)
+        allowed.push("squash");
+    if (repository.rebaseMergeAllowed)
+        allowed.push("rebase");
+    return allowed;
+}
+export function parseMergeMethod(value) {
+    if (typeof value === "string" && MERGE_METHODS.has(value)) {
+        return value;
+    }
+    throw new Error("Invalid config: merge.method must be merge, squash, or rebase");
+}
+export function configuredMergeMethod(merge) {
+    const fromArgs = findMergeStrategies(merge.commandArgs ?? [])[0];
+    return merge.method ?? fromArgs ?? null;
+}
+export function chooseMergeMethod(input) {
+    if (input.allowed === undefined)
+        return { method: input.configured ?? input.fallback };
+    if (input.configured) {
+        if (input.allowed.includes(input.configured))
+            return { method: input.configured };
+        const allowedText = input.allowed.length > 0 ? input.allowed.join(", ") : "none";
+        return {
+            unavailable: `Configured merge method \`${input.configured}\` is not allowed by this repository. Allowed methods: ${allowedText}.`,
+        };
+    }
+    if (input.allowed.includes(input.fallback))
+        return { method: input.fallback };
+    const method = METHOD_ORDER.find((item) => input.allowed?.includes(item));
+    if (method)
+        return { method };
+    return {
+        unavailable: "This repository allows no merge method (merge commits, squash, and rebase are all disabled).",
+    };
+}
+export function mergeMethodFlag(allowed, fallback, configured) {
+    const decision = chooseMergeMethod({ allowed, configured, fallback });
+    if ("unavailable" in decision)
+        return decision;
+    return { flag: `--${decision.method}` };
+}

package/bin/exit-codes.d.mts

@@ -13,7 +13,7 @@ import type { IterateResult } from "./types.mts";
 export declare const EXIT: Readonly<{
     /** `cancel` + `merged` or `ready-delay-elapsed` — shepherd finished cleanly. */
     readonly OK: 0;
-    /** Nothing to do yet; CI still in progress. */
+    /** Nothing to do yet, or a clean PR whose ready-delay is still counting. */
     readonly WAIT: 10;
     /** Draft PR converted to ready for review. */
     readonly MARK_READY: 11;

package/bin/exit-codes.mjs

@@ -12,7 +12,7 @@
 export const EXIT = Object.freeze({
     /** `cancel` + `merged` or `ready-delay-elapsed` — shepherd finished cleanly. */
     OK: 0,
-    /** Nothing to do yet; CI still in progress. */
+    /** Nothing to do yet, or a clean PR whose ready-delay is still counting. */
     WAIT: 10,
     /** Draft PR converted to ready for review. */
     MARK_READY: 11,
@@ -62,6 +62,7 @@ export function iterateResultToExitCode(result) {
         case "cancel":
             return CANCEL_REASON_EXIT_CODE[result.reason];
         case "wait":
+        case "ready":
             return EXIT.WAIT;
         case "mark_ready":
             return EXIT.MARK_READY;

package/bin/github/batch-parse-suites.d.mts

@@ -1,6 +1,9 @@
+import type { WorkflowSuiteSnapshot } from "../checks/unreported-required.mts";
 import type { CheckRun } from "../types.mts";
 import type { RawPr } from "./batch-raw-types.mts";
 export declare function parseCheckSuitesComplete(raw: RawPr): boolean;
 /** True only when the head commit's suite page finished and listed nothing. */
 export declare function parseHeadCheckSuitesEmpty(raw: RawPr): boolean;
+/** Actions suites on the head. Third-party suites with no workflow run are omitted. */
+export declare function parseHeadWorkflowSuites(raw: RawPr): WorkflowSuiteSnapshot[];
 export declare function parseSuiteStartupFailures(raw: RawPr): CheckRun[];

package/bin/github/batch-parse-suites.mjs

@@ -6,6 +6,21 @@ export function parseHeadCheckSuitesEmpty(raw) {
     const suites = raw.commits.nodes[0]?.commit.checkSuites;
     return suites?.pageInfo.hasNextPage === false && suites.nodes.length === 0;
 }
+/** Actions suites on the head. Third-party suites with no workflow run are omitted. */
+export function parseHeadWorkflowSuites(raw) {
+    const nodes = raw.commits.nodes[0]?.commit.checkSuites?.nodes ?? [];
+    return nodes.flatMap((node) => {
+        if (!node.workflowRun)
+            return [];
+        return [
+            {
+                status: node.status ?? null,
+                conclusion: node.conclusion,
+                workflowRun: { event: node.workflowRun.event },
+            },
+        ];
+    });
+}
 export function parseSuiteStartupFailures(raw) {
     const suites = raw.commits.nodes[0]?.commit.checkSuites;
     if (!suites)

package/bin/github/batch-parsers.d.mts

@@ -1,3 +1,3 @@
 import type { BatchPrData } from "../types.mts";
 import type { RawBatchResponse, RawPr, RawThread, RawComment, RawReview, RawReviewSummary, RawContextNode } from "./batch-raw-types.mts";
-export declare function parseRawPr(raw: RawPr, rawThreadPages: RawThread[], rawCommentNodes: RawComment[], rawReviewNodes: RawReview[], rawReviewSummaryNodes: RawReviewSummary[], rawApprovedReviewNodes: RawReviewSummary[], rawCheckNodes: RawContextNode[], repository?: Pick<NonNullable<RawBatchResponse["repository"]>, "viewerPermission" | "viewerCanAdminister">): BatchPrData;
+export declare function parseRawPr(raw: RawPr, rawThreadPages: RawThread[], rawCommentNodes: RawComment[], rawReviewNodes: RawReview[], rawReviewSummaryNodes: RawReviewSummary[], rawApprovedReviewNodes: RawReviewSummary[], rawCheckNodes: RawContextNode[], repository?: Pick<NonNullable<RawBatchResponse["repository"]>, "viewerPermission" | "viewerCanAdminister" | "mergeCommitAllowed" | "squashMergeAllowed" | "rebaseMergeAllowed">): BatchPrData;