pr-shepherd 0.49.0 → 0.51.0

package/bin/commands/poll-summary.mjs

@@ -4,12 +4,13 @@ import { getRepoInfo } from "../github/client.mjs";
 import { withApiTelemetryScope, summarizeApiTelemetry } from "../github/api-telemetry.mjs";
 import { fetchPollSummary } from "../github/poll-summary.mjs";
 import { sleep } from "../util/sleep.mjs";
-import { graphqlQuotaPollIntervalMs, pollGraphQlRetryAfterMs } from "./poll-quota.mjs";
-import { evaluateWorktreeGraphqlQuotaWarning } from "../state/graphql-quota-warnings.mjs";
+import { aggregateQuotaWarning, graphqlQuotaPollIntervalMs, pollGraphQlRetryAfterMs, } from "./poll-quota.mjs";
+import { withPollSummaryInstructions } from "./poll-summary-instructions.mjs";
+import { summaryStatusSignature } from "./poll-summary-signature.mjs";
 const MAX_TIMER_MS = 2 ** 31 - 1;
 const TIMER_DRIFT_TOLERANCE_MS = 500;
 export function runPollSummary(opts) {
-    return withApiTelemetryScope(async () => attachUsage(await runPollSummaryCore(opts)));
+    return withApiTelemetryScope(async () => attachUsage(await runPollSummaryCore(opts), opts.merge));
 }
 export function runAggregatePoll(opts) {
     return withApiTelemetryScope(() => runAggregatePollCore(opts));
@@ -19,13 +20,14 @@ async function runPollSummaryCore(opts) {
     const fetched = await fetchPollSummary(opts, repo);
     const allTerminal = fetched.prs.every((item) => item.action === "cancel");
     const actionable = fetched.prs.some((item) => item.action !== "wait" && item.action !== "cancel");
-    return {
+    return withPollSummaryInstructions({
         mode: "summary",
         repo: `${repo.owner}/${repo.name}`,
         selection: fetched.selection,
         reason: allTerminal ? "all_terminal" : actionable ? "actionable" : "waiting",
         prs: fetched.prs,
-    };
+        ...(fetched.stackAncestry?.length && { stackAncestry: fetched.stackAncestry }),
+    }, opts.merge === true);
 }
 async function runAggregatePollCore(opts) {
     const intervalMs = Math.min(opts.intervalSeconds * 1000, MAX_TIMER_MS);
@@ -60,7 +62,7 @@ async function runAggregatePollCore(opts) {
                         ...explicit,
                         reason: "all_terminal",
                         ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
-                    });
+                    }, opts.merge);
                 }
             }
             const retryMs = opts.untilTerminal ? pollGraphQlRetryAfterMs(error) : null;
@@ -71,9 +73,15 @@ async function runAggregatePollCore(opts) {
             await sleep(retryMs);
             continue;
         }
-        const allTerminal = last.prs.every((item) => item.action === "cancel");
-        const immediate = last.prs.some((item) => ["escalate", "merge", "mark_ready"].includes(item.action));
-        const hasFix = last.prs.some((item) => item.action === "fix_code");
+        const allTerminal = last.selection.kind === "stack"
+            ? last.nextAction === "cancel"
+            : last.prs.every((item) => item.action === "cancel");
+        const immediate = last.selection.kind === "stack"
+            ? ["escalate", "merge", "mark_ready"].includes(last.nextAction ?? "wait")
+            : last.prs.some((item) => ["escalate", "merge", "mark_ready"].includes(item.action));
+        const hasFix = last.selection.kind === "stack"
+            ? last.nextAction === "fix_code"
+            : last.prs.some((item) => item.action === "fix_code");
         const warning = await aggregateQuotaWarning(last, quotaBands, opts.intervalSeconds);
         if (warning)
             pendingQuotaWarning = warning;
@@ -82,14 +90,14 @@ async function runAggregatePollCore(opts) {
                 ...last,
                 reason: "all_terminal",
                 ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
-            });
+            }, opts.merge);
         }
         if (immediate) {
             return attachUsage({
                 ...last,
                 reason: "actionable",
                 ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
-            });
+            }, opts.merge);
         }
         if (hasFix) {
             if (debounceMs === 0)
@@ -97,19 +105,19 @@ async function runAggregatePollCore(opts) {
                     ...last,
                     reason: "actionable",
                     ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
-                });
+                }, opts.merge);
             debounceUntil ??= Date.now() + debounceMs;
             if (Date.now() >= debounceUntil)
                 return attachUsage({
                     ...last,
                     reason: "actionable",
                     ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
-                });
+                }, opts.merge);
         }
         else {
             debounceUntil = null;
             if (opts.untilTerminal && pendingQuotaWarning) {
-                return attachUsage({ ...last, quotaWarning: pendingQuotaWarning });
+                return attachUsage({ ...last, quotaWarning: pendingQuotaWarning }, opts.merge);
             }
         }
         const elapsedMs = Date.now() - start;
@@ -119,7 +127,7 @@ async function runAggregatePollCore(opts) {
         if (!opts.untilTerminal && debounceUntil === null) {
             const remainingMs = timeoutMs - elapsedMs;
             if (remainingMs <= 0 || remainingMs + TIMER_DRIFT_TOLERANCE_MS < sleepMs) {
-                return attachUsage({ ...last, reason: "timeout" });
+                return attachUsage({ ...last, reason: "timeout" }, opts.merge);
             }
         }
         const statusSignature = summaryStatusSignature(last);
@@ -132,32 +140,10 @@ async function runAggregatePollCore(opts) {
         await sleep(sleepMs);
     }
 }
-async function aggregateQuotaWarning(result, bands, intervalSeconds) {
-    const usage = summarizeApiTelemetry()?.graphql;
-    const [owner, repo] = result.repo.split("/");
-    if (!usage || !owner || !repo)
-        return undefined;
-    return evaluateWorktreeGraphqlQuotaWarning({ owner, repo }, bands.map((band) => ({
-        ...band,
-        pollIntervalMinutes: Math.max(band.pollIntervalMinutes, intervalSeconds / 60),
-    })), usage, true);
-}
-function summaryStatusSignature(result) {
-    return JSON.stringify(result.prs.map((item) => ({
-        pr: item.pr,
-        action: item.action,
-        state: item.state,
-        mergeable: item.mergeable,
-        mergeStateStatus: item.mergeStateStatus,
-        reviewDecision: item.reviewDecision,
-        checks: item.checks,
-        review: item.review,
-    })));
-}
 function isMissingStack(error) {
     return (error instanceof ShepherdError && error.message.includes("not part of a native GitHub stack"));
 }
-function attachUsage(result) {
+function attachUsage(result, mergeRequested) {
     const apiUsage = summarizeApiTelemetry();
-    return apiUsage ? { ...result, apiUsage } : result;
+    return withPollSummaryInstructions(apiUsage ? { ...result, apiUsage } : result, mergeRequested === true);
 }

package/bin/commands/resolve-mutate.mjs

@@ -1,12 +1,9 @@
 import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
 import { applyResolveOptions } from "../comments/resolve.mjs";
 import { fetchPrBatch } from "../github/batch.mjs";
-import { loadConfig } from "../config/load.mjs";
-import { isConfiguredBotAuthor, isHumanAuthor, isViewerAuthoredHuman, normalizeBotUsernames, } from "../comments/authors.mjs";
-import { shouldResolveOtherHumanThread } from "./iterate/thread-mutation-routing.mjs";
 import { markReplySeen } from "../state/seen-comments.mjs";
 import { threadTranscriptBody } from "../threads/transcript.mjs";
-import { addPrShepherdMarker, threadEndedByShepherd } from "../comments/marker.mjs";
+import { addPrShepherdMarker } from "../comments/marker.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 /** @deprecated Hidden implementation for `resolve`; use `apply review`. */
 export async function runResolveMutate(opts) {
@@ -15,73 +12,30 @@ export async function runResolveMutate(opts) {
     if (prNumber === null) {
         throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
     }
-    const { data } = await fetchPrBatch(prNumber, repo, { paginateApprovedReviews: true });
-    const config = loadConfig();
-    const botUsernames = normalizeBotUsernames(config.botUsernames);
-    const threadById = new Map(data.reviewThreads.map((t) => [t.id, t]));
-    const humanThreadIds = new Set(data.reviewThreads
-        .filter((t) => isHumanAuthor(t) && !isConfiguredBotAuthor(t, botUsernames))
-        .map((t) => t.id));
-    const humanCommentIds = new Set(data.comments
-        .filter((c) => isHumanAuthor(c) && !isConfiguredBotAuthor(c, botUsernames))
-        .map((c) => c.id));
-    const humanReviewIds = new Set([...data.reviewSummaries, ...data.approvedReviews, ...data.changesRequestedReviews]
-        .filter((r) => isHumanAuthor(r) && !isConfiguredBotAuthor(r, botUsernames))
-        .map((r) => r.id));
-    // Iterate uses viewer capability fields while deciding which commands to
-    // print. Once a caller explicitly runs apply, GitHub's mutation response is
-    // authoritative and this path must not second-guess that intent.
-    const requestedReplyIds = new Set(opts.replyThreadIds ?? []);
-    const policy = config.iterate?.resolveOtherHumanThreads ?? "none";
-    const allowedHumanResolveIds = new Set(data.reviewThreads
-        .filter((thread) => {
-        if (!humanThreadIds.has(thread.id))
-            return false;
-        const paired = requestedReplyIds.has(thread.id) || threadEndedByShepherd(thread);
-        if (!paired)
-            return false;
-        if (isViewerAuthoredHuman(thread, botUsernames))
-            return true;
-        return shouldResolveOtherHumanThread(thread, policy);
-    })
-        .map((thread) => thread.id));
-    const resolveThreadIds = (opts.resolveThreadIds ?? []).filter((id) => !humanThreadIds.has(id) || allowedHumanResolveIds.has(id));
-    const skippedHumanResolves = (opts.resolveThreadIds ?? []).filter((id) => humanThreadIds.has(id) && !allowedHumanResolveIds.has(id));
-    const knownThreadIds = new Set(data.reviewThreads.map((thread) => thread.id));
-    const replyThreadIds = opts.replyThreadIds?.filter((id) => knownThreadIds.has(id));
-    const skippedNonHumanReplies = (opts.replyThreadIds ?? []).filter((id) => !knownThreadIds.has(id));
-    const minimizeCommentIds = (opts.minimizeCommentIds ?? []).filter((id) => !humanCommentIds.has(id) && !humanReviewIds.has(id));
-    const skippedHumanMinimizes = (opts.minimizeCommentIds ?? []).filter((id) => humanCommentIds.has(id) || humanReviewIds.has(id));
-    const dismissReviewIds = (opts.dismissReviewIds ?? []).filter((id) => !humanReviewIds.has(id) && data.changesRequestedReviews.some((review) => review.id === id));
-    const skippedHumanDismissals = (opts.dismissReviewIds ?? []).filter((id) => humanReviewIds.has(id));
-    const skippedIneligibleDismissals = (opts.dismissReviewIds ?? []).filter((id) => !humanReviewIds.has(id) && !dismissReviewIds.includes(id));
-    const hasMutation = resolveThreadIds.length > 0 ||
-        (replyThreadIds?.length ?? 0) > 0 ||
-        minimizeCommentIds.length > 0 ||
-        dismissReviewIds.length > 0;
+    // Fetch only to retain the pre-reply transcript for successful-reply seen
+    // markers. It never determines which user-supplied IDs are sent to GitHub.
+    let threadById;
+    if (opts.replyThreadIds?.length) {
+        try {
+            threadById = new Map((await fetchPrBatch(prNumber, repo, { paginateApprovedReviews: true })).data.reviewThreads.map((thread) => [thread.id, thread]));
+        }
+        catch {
+            // Seen-marker bookkeeping is best-effort. A failed read must not block
+            // the explicit mutation request; GitHub's mutation response is authoritative.
+        }
+    }
+    // Iterate capability-checks and routes its generated commands. Direct apply
+    // requests are user-directed: forward every supplied ID unchanged and let
+    // GitHub report whether each requested mutation is permitted or applicable.
     const result = await applyResolveOptions(prNumber, repo, {
-        resolveThreadIds,
-        replyThreadIds,
-        minimizeCommentIds,
-        dismissReviewIds,
+        resolveThreadIds: opts.resolveThreadIds,
+        replyThreadIds: opts.replyThreadIds,
+        minimizeCommentIds: opts.minimizeCommentIds,
+        dismissReviewIds: opts.dismissReviewIds,
         dismissMessage: opts.dismissMessage,
-        requireSha: hasMutation ? opts.requireSha : undefined,
+        requireSha: opts.requireSha,
     });
-    if (skippedHumanResolves.length > 0)
-        result.skippedHumanResolves = skippedHumanResolves;
-    if (skippedHumanMinimizes.length > 0)
-        result.skippedHumanMinimizes = skippedHumanMinimizes;
-    if (skippedHumanDismissals.length > 0)
-        result.skippedHumanDismissals = skippedHumanDismissals;
-    if (skippedNonHumanReplies.length > 0)
-        result.skippedNonHumanReplies = skippedNonHumanReplies;
-    if (skippedIneligibleDismissals.length > 0) {
-        result.skippedDismissals = [
-            ...(result.skippedDismissals ?? []),
-            ...skippedIneligibleDismissals,
-        ];
-    }
-    if (opts.dismissMessage) {
+    if (opts.dismissMessage && threadById) {
         const markedMessage = addPrShepherdMarker(opts.dismissMessage);
         await Promise.all(result.repliedThreads.map((id) => {
             const thread = threadById.get(id);

package/bin/comments/resolve.d.mts

@@ -7,10 +7,15 @@ export interface ResolveResult {
     minimizedComments: string[];
     dismissedReviews: string[];
     errors: string[];
+    /** @deprecated Direct apply forwards every supplied dismissal ID to GitHub. */
     skippedDismissals?: string[];
+    /** @deprecated Direct apply no longer applies author policy. */
     skippedHumanResolves?: string[];
+    /** @deprecated Direct apply no longer applies author policy. */
     skippedHumanMinimizes?: string[];
+    /** @deprecated Direct apply no longer applies author policy. */
     skippedHumanDismissals?: string[];
+    /** @deprecated Direct apply forwards every supplied reply ID to GitHub. */
     skippedNonHumanReplies?: string[];
     /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
     skippedUnauthorizedReplies?: string[];

package/bin/comments/resolve.mjs

@@ -35,9 +35,6 @@ export async function applyResolveOptions(pr, repo, opts) {
     const replyThreadIds = dedupeIds(opts.replyThreadIds ?? []);
     const minimizeCommentIds = opts.minimizeCommentIds ?? [];
     const dismissReviewIds = dedupeIds(opts.dismissReviewIds ?? []);
-    const minimizeCommentIdSet = new Set(minimizeCommentIds);
-    const filteredDismissReviewIds = dismissReviewIds.filter((id) => !minimizeCommentIdSet.has(id));
-    const overlappingDismissIds = dismissReviewIds.filter((id) => minimizeCommentIdSet.has(id));
     const result = {
         repliedThreads: [],
         resolvedThreads: [],
@@ -45,13 +42,7 @@ export async function applyResolveOptions(pr, repo, opts) {
         dismissedReviews: [],
         errors: [],
     };
-    if (overlappingDismissIds.length > 0) {
-        result.skippedDismissals = [];
-        for (const id of overlappingDismissIds) {
-            result.skippedDismissals.push(id);
-        }
-    }
-    if ((filteredDismissReviewIds.length > 0 || replyThreadIds.length > 0) && !opts.dismissMessage) {
+    if ((dismissReviewIds.length > 0 || replyThreadIds.length > 0) && !opts.dismissMessage) {
         throw new Error("--message is required when replying to threads or dismissing reviews");
     }
     if (opts.requireSha) {
@@ -59,7 +50,7 @@ export async function applyResolveOptions(pr, repo, opts) {
         // before reviewers see the fix.
         await waitForSha(pr, repo, opts.requireSha);
     }
-    await bulkApply(replyThreadIds, resolveThreadIds, minimizeCommentIds, filteredDismissReviewIds, opts.dismissMessage ?? "", result);
+    await bulkApply(replyThreadIds, resolveThreadIds, minimizeCommentIds, dismissReviewIds, opts.dismissMessage ?? "", result);
     return result;
 }
 /** @deprecated Compatibility alias; use `autoResolveThreads`. */

package/bin/github/gql/poll-summary-fragment.gql

@@ -8,6 +8,7 @@ fragment PollSummaryPr on PullRequest {
   headRefName
   headRefOid
   baseRefName
+  baseRefOid
   mergeable
   mergeStateStatus
   reviewDecision

package/bin/github/poll-summary-projector.mjs

@@ -55,7 +55,8 @@ export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdministe
         ...(Object.keys(checks).length > 0 && { checks }),
         ...(Object.keys(review).length > 0 && { review }),
         ...(stack && { stack }),
-        ...(!["wait", "cancel"].includes(action) && {
+        ...(!["wait", "cancel"].includes(action) &&
+            !(opts.stackPrNumber !== undefined && raw.stack && action === "merge") && {
             pollCommand: buildPollCommand(repoName, raw.number, opts),
         }),
     };

package/bin/github/poll-summary-raw.d.mts

@@ -52,6 +52,7 @@ export interface RawSummaryPr {
     viewerCanUpdate: boolean;
     headRefName: string;
     headRefOid: string;
+    baseRefOid: string;
     baseRefName: string;
     mergeable: string;
     mergeStateStatus: string;

package/bin/github/poll-summary-route.mjs

@@ -35,9 +35,12 @@ export function routePollSummary(raw, checks, review, opts) {
     if (opts.merge && raw.isInMergeQueue) {
         return { action: "wait", reasons: ["already-in-merge-queue"] };
     }
-    if (opts.merge && raw.stack) {
+    if (opts.merge && raw.stack && opts.stackPrNumber === undefined) {
         return { action: "fix_code", reasons: ["authoritative-poll-required"] };
     }
+    if (opts.merge && raw.stack) {
+        return { action: "merge", reasons: ["appears-ready"] };
+    }
     if (opts.merge && !raw.stack)
         return { action: "merge", reasons: ["appears-ready"] };
     return { action: "cancel", reasons: ["appears-ready"] };

package/bin/github/poll-summary.d.mts

@@ -1,7 +1,8 @@
-import type { PollSummaryCommandOptions, PollSummaryItem, PollSummarySelection } from "../types.mts";
+import type { PollSummaryCommandOptions, PollSummaryItem, PollSummarySelection, PollSummaryStackAncestry } from "../types.mts";
 import { type RepoInfo } from "./client.mts";
 export interface FetchedPollSummary {
     selection: PollSummarySelection;
     prs: PollSummaryItem[];
+    stackAncestry?: PollSummaryStackAncestry[];
 }
 export declare function fetchPollSummary(opts: PollSummaryCommandOptions, repo: RepoInfo): Promise<FetchedPollSummary>;

package/bin/github/poll-summary.mjs

@@ -97,9 +97,28 @@ async function fetchStackSummary(opts, repo) {
         throw new ShepherdError(`GitHub returned incomplete stack membership (${unique.size} of ${stackSize} entries)`, EXIT.TEMPFAIL);
     }
     const ordered = [...unique.values()].sort((left, right) => left.position - right.position);
+    const stackAncestry = [];
+    for (let index = 1; index < ordered.length; index++) {
+        const parent = ordered[index - 1].pullRequest;
+        const child = ordered[index].pullRequest;
+        if (parent.state !== "OPEN" || child.state !== "OPEN")
+            continue;
+        if (child.baseRefName === parent.headRefName && child.baseRefOid === parent.headRefOid) {
+            continue;
+        }
+        stackAncestry.push({
+            parentPr: parent.number,
+            parentHeadRefName: parent.headRefName,
+            parentHeadRefOid: parent.headRefOid,
+            childPr: child.number,
+            childBaseRefName: child.baseRefName,
+            childBaseRefOid: child.baseRefOid,
+        });
+    }
     return {
         selection: { kind: "stack", anchor, stackNumber, stackSize },
         prs: await Promise.all(ordered.map((entry) => summarizePollSummaryPr(entry.pullRequest, repo, opts, viewerCanAdminister))),
+        ...(stackAncestry.length > 0 && { stackAncestry }),
     };
 }
 function deduplicate(values) {

package/bin/state/fix-attempts.d.mts

@@ -1,14 +1,13 @@
 /**
  * Persistent attempt counter for the iterate escalation guard.
  *
- * Tracks how many times each review thread has been dispatched to the fix_code
- * handler without being resolved. Counts are reset automatically when the HEAD
- * commit SHA changes (i.e. a new push landed).
+ * Tracks how many caller-visible times each review thread has been dispatched to
+ * the fix_code handler without being resolved. Body edits reset the count.
  *
  * State lives in `$TMPDIR/pr-shepherd-state/<owner>-<repo>/<pr>/fix-attempts.json`.
  */
 export interface FixAttemptsState {
-    /** HEAD SHA at the time the counts were last written. Reset key. */
+    /** HEAD SHA at the time the counts were last written, retained for observability/compatibility. */
     headSha: string;
     /** Map from thread ID → number of fix_code dispatches that included this thread. */
     threadAttempts: Record<string, number>;

package/bin/state/fix-attempts.mjs

@@ -1,9 +1,8 @@
 /**
  * Persistent attempt counter for the iterate escalation guard.
  *
- * Tracks how many times each review thread has been dispatched to the fix_code
- * handler without being resolved. Counts are reset automatically when the HEAD
- * commit SHA changes (i.e. a new push landed).
+ * Tracks how many caller-visible times each review thread has been dispatched to
+ * the fix_code handler without being resolved. Body edits reset the count.
  *
  * State lives in `$TMPDIR/pr-shepherd-state/<owner>-<repo>/<pr>/fix-attempts.json`.
  */

package/bin/types/escalate.d.mts

@@ -1,4 +1,5 @@
 import type { AgentCheck, AgentComment, AgentThread } from "./report.mts";
+import type { ResolveCommand } from "./iterate.mts";
 import type { CheckStatus, Review } from "./github.mts";
 import type { MergeQueueRemovalStatus, StackStatus } from "./merge-requirements.mts";
 export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "check-follow-up-unavailable" | "authorization-required" | "bot-cr-not-dismissed" | "merge-queue-removed" | "stacked-pr";
@@ -19,6 +20,10 @@ export interface EscalateDetails {
     unresolvedThreads: AgentThread[];
     ambiguousComments: AgentComment[];
     changesRequestedReviews: Review[];
+    /** First-look review summaries that must be shown before any pending minimization. */
+    firstLookSummaries?: Review[];
+    /** Previously seen review summaries whose edited bodies must be shown again. */
+    editedSummaries?: Review[];
     /** Failing checks whose next step requires human attention. */
     checks?: AgentCheck[];
     stalledChecks?: AgentStalledCheck[];
@@ -26,6 +31,11 @@ export interface EscalateDetails {
         threadId: string;
         attempts: number;
     }>;
+    /** Review mutations generated for this tick, retained so an escalation cannot strand them. */
+    pendingReviewCommands?: {
+        resolveOnlyCommand?: ResolveCommand;
+        resolveCommand?: ResolveCommand;
+    };
     suggestion: string;
     humanMessage: string;
     mergeQueueRemoval?: MergeQueueRemovalStatus;

package/bin/types/poll-summary.d.mts

@@ -18,6 +18,15 @@ export interface PollSummaryReview {
     actionable?: number;
     incomplete?: true;
 }
+/** The two GitHub refs at an adjacent, still-open stack boundary. */
+export interface PollSummaryStackAncestry {
+    parentPr: number;
+    parentHeadRefName: string;
+    parentHeadRefOid: string;
+    childPr: number;
+    childBaseRefName: string;
+    childBaseRefOid: string;
+}
 interface PollSummaryStack {
     number: number;
     size: number;
@@ -63,6 +72,11 @@ export interface PollSummaryResult {
     selection: PollSummarySelection;
     reason: "actionable" | "all_terminal" | "waiting" | "timeout";
     prs: PollSummaryItem[];
+    /** Present only for native-stack boundaries whose recorded refs differ. */
+    stackAncestry?: PollSummaryStackAncestry[];
+    /** The next stack-level transition, which may differ from an individual row's hint. */
+    nextAction?: ShepherdAction;
+    instructions?: string[];
     apiUsage?: ApiUsage;
     quotaWarning?: GraphqlQuotaWarning;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/plugins/pr-shepherd/.codex.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "pr-shepherd": {
       "command": "npx",
-      "args": ["--yes", "--package", "pr-shepherd@0.49.0", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.51.0", "pr-shepherd-mcp"]
     }
   }
 }

package/plugins/pr-shepherd/.mcp.json

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.49.0", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.51.0", "pr-shepherd-mcp"]
   }
 }

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -2,7 +2,7 @@
 name: pr-shepherd
 description: 'Create or iterate a GitHub pull request with pr-shepherd (MCP or CLI). Use for requests like "make a PR and use pr-shepherd", "iterate PR #123", or "run pr-shepherd until this PR is ready".'
 user-invocable: true
-argument-hint: "[PR number or URL] [--merge]"
+argument-hint: "[PR number or URL | --stack PR] [--merge]"
 allowed-tools: ["MCP", "Bash", "Read", "Grep", "Glob", "Edit", "Write"]
 ---
 
@@ -18,9 +18,9 @@ If the requested PR does not exist yet, review and commit the in-scope changes,
 
 ## Arguments: $ARGUMENTS
 
-1. Parse optional PR numbers, repository-qualified `owner/repo#N` references, or GitHub PR URLs and an optional `--merge` flag from `$ARGUMENTS`; alternatively parse one `--stack PR` selector. Otherwise let pr-shepherd infer the current branch PR. Reject any remaining argument. Follow the target repository's local `AGENTS.md` and `CLAUDE.md` standards while making changes.
+1. Parse optional PR numbers, repository-qualified `owner/repo#N` references, or GitHub PR URLs and an optional `--merge` flag from `$ARGUMENTS`; alternatively parse one `--stack PR` selector. A clear request to merge, land, or enqueue the selected PR or stack also opts into `--merge` without a literal flag; a request only to create or open a PR does not. When the user asks to shepherd or merge a native stack and supplies an anchor PR without a literal `--stack`, use that PR as the `--stack` selector. Otherwise let pr-shepherd infer the current branch PR. Reject any remaining argument. Follow the target repository's local `AGENTS.md` and `CLAUDE.md` standards while making changes.
 
-2. For the CLI, convert supplied `owner/repo#N` references to `https://github.com/owner/repo/pull/N`; otherwise pass supplied URLs or bare numbers unchanged, then run `pr-shepherd [PR ...] --until-terminal`, or `pr-shepherd --stack PR --until-terminal` for a stack, omitting `[PR ...]` when none was supplied and appending `--merge` when requested. This command keeps ordinary `[WAIT]` and `[MARK_READY]` ticks inside the same invocation; aggregate selectors return when any row needs work or all rows are terminal. It also returns for a quota warning or an emitted `[MERGE]` command, which is non-terminal and must run before the next invocation. A qualified reference may name a fork or upstream repository: it is the GitHub target, while the current checkout continues to supply local git/config/rules context. Do not run `pr-shepherd iterate`. If the CLI is unavailable and the `iterate` MCP tool is available, first repository-qualify every supplied reference with its GitHub URL or `owner/repo#N`; resolve bare numbers through `gh pr view <number> --json url --jq .url`, and resolve an omitted target with `gh pr view --json url --jq .url`. If that does not produce the required qualified selector, stop and report that MCP cannot safely determine it. Otherwise call `iterate` with `pr`, `prs`, or `stack` as selected, plus `merge: true` when `--merge` was supplied, and print its full result.
+2. For the CLI, convert supplied `owner/repo#N` references to `https://github.com/owner/repo/pull/N`; otherwise pass supplied URLs or bare numbers unchanged, then run `pr-shepherd [PR ...] --until-terminal`, or `pr-shepherd --stack PR --until-terminal` for a stack, omitting `[PR ...]` when none was supplied and appending `--merge` when requested. This command keeps ordinary `[WAIT]` and `[MARK_READY]` ticks inside the same invocation; aggregate selectors return when any row needs work or all rows are terminal. It also returns for a quota warning or an emitted `[MERGE]` command, which is non-terminal and must run before the next invocation. A qualified reference may name a fork or upstream repository: it is the GitHub target, while the current checkout continues to supply local git/config/rules context. Do not run `pr-shepherd iterate`. If the CLI is unavailable and the `iterate` MCP tool is available, first repository-qualify every supplied reference with its GitHub URL or `owner/repo#N`; resolve bare numbers through `gh pr view <number> --json url --jq .url`, and resolve an omitted target with `gh pr view --json url --jq .url`. If that does not produce the required qualified selector, stop and report that MCP cannot safely determine it. Otherwise call `iterate` with `pr`, `prs`, or `stack` as selected, plus `merge: true` when merge intent was requested, and print its full result.
 
 3. Print the full result and follow every returned `## Instructions` step exactly. For CLI output, run each printed mutation command when instructed. For MCP output, use MCP `apply` and `build_suggestion_patches` with the same qualified PR reference; do not run a shell `pr-shepherd apply` command.
 
@@ -51,7 +51,7 @@ annotations, or CI log excerpts.
 - The command builds from the fetched PR head and accepts a clean local descendant only when the complete ordered patch stream passes `git apply --check`.
 - If the command refuses because a suggestion is unsafe or no longer applies, inspect the current source, the displayed replacement block, and reviewer intent before editing manually. Do not apply a stale numeric range blindly or retry unchanged input.
 - A returned patch was checked against the then-current worktree. If it later fails, re-inspect the worktree because it changed after validation.
-- Keep the generated thread IDs and flag placement unchanged. Viewer-authored human feedback may intentionally appear in both reply and resolve flags; unmarked other-human feedback remains reply-only. Marker-ended other-human feedback is already acknowledged and has no generated mutation.
+- Use the generated thread IDs and flag placement returned with the patch command.
 
 ### CI failure triage
 
@@ -77,16 +77,11 @@ When several bullets share one runId (matrix jobs from the same run), the `rerun
 
 Applies to every `apply review:` / `resolve-only:` command the CLI prints. Covers only what stays safe if you run the printed command **unmodified** — `$HEAD_SHA`/`$DISMISS_MESSAGE` substitution remains a separate CLI-printed step because the command is unsafe by default without those placeholders.
 
-The CLI only includes IDs whose per-object GitHub viewer capability and semantic routing authorize the corresponding generated action. Direct `apply review` honors those emitted IDs without a second authorization preflight and surfaces GitHub's per-operation result. Do not reconstruct omitted review reply, thread resolution, or bot-review dismissal IDs and do not hand them off: denied or unverifiable generated mutations are one-look skips that Shepherd suppresses until the item is edited. Location is not required for generated reply/resolve mutations; unauthorized threads without a path or line remain one-look skips.
+The CLI only includes IDs whose per-object GitHub viewer capability and semantic routing authorize the corresponding generated action. Generated commands are pre-populated; omission is not a prohibition. A separate, user-directed `apply review` request may supply any reply, resolve, minimize, or dismiss IDs; it forwards them without Shepherd author, capability, or current-state filtering, and GitHub's per-operation response is authoritative.
 
-- Run every generated `apply review:` / `resolve-only:` command even when no code change is warranted. The command records the agent's disposition of the included review items; skipping it leaves authorized threads active and can eventually trigger `fix-thrash`.
-- Never add first-look-only or check-annotation IDs to `--reply-thread-ids`, `--resolve-thread-ids`, `--dismiss-review-ids`, or `--minimize-comment-ids` — those flags are pre-populated by the CLI.
+- When `## Instructions` says to run a generated `apply review:` / `resolve-only:` command, run it even when no code change is warranted. An `[ESCALATE]` instruction may require user direction first. The command records the agent's disposition of the included review items; skipping it leaves authorized threads active and can eventually trigger `fix-thrash`.
 - Keep every existing `--dismiss-review-ids` ID the CLI already included. Each is a bot or non-human review that must be dismissed; omitting one leaves the PR in `CHANGES_REQUESTED`.
 
-### Review-mutation routing
-
-For threads under both `## Review threads` and `## Review threads to resolve`, evaluate every thread before running mutations. Keep unmarked bot/non-human and viewer-authored IDs in both `--reply-thread-ids` and `--resolve-thread-ids`, including when the feedback is advisory, already satisfied, or otherwise warrants no code change: the reply runs before the resolve. Unmarked other-human IDs use `--reply-thread-ids` only unless the CLI also put them in `--resolve-thread-ids`. When the latest comment begins `<!-- pr-shepherd -->`, it is an established Shepherd reply—not merely a same-account comment. A marked thread that is still being resolved is resolve-only for retry. Do not add IDs the CLI omitted, and do not move IDs between flags.
-
 ### Shepherd Journal
 
 Link threads and comments in a journal entry from their headings in the CLI output. Cite reviews by ID.

package/plugins/pr-shepherd/skills/reduce-pr-noise/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: reduce-pr-noise
+description: Reduce repetitive pr-shepherd output by configuring bot-comment classification rules or existing noise settings. Use for requests to silence a specific bot notice, quiet polling, trim CI logs, or tune comment visibility; use pr-shepherd for PR iteration itself.
+user-invocable: true
+argument-hint: "[noisy bot comment or output]"
+allowed-tools: ["Bash", "Read", "Grep", "Glob", "Edit", "Write"]
+---
+
+# Reduce pr-shepherd noise
+
+Identify the unwanted output from the request, a representative Shepherd result, and the current configuration. If a content-specific rule needs a message pattern and none is available, ask for an example before writing that rule.
+
+- For a recurring bot message identified by its author and text, read [bot-comment classifiers](references/classifiers.md).
+- For polling status, CI checks or logs, and broad comment visibility, read [noise settings](references/settings.md).
+- Read both references only when the request needs both kinds of change.
+
+Make the smallest change that addresses the observed noise. Use project-local files for project-specific policy; use the user's home configuration only when they request a personal default. Validate the match or setting and explain what will become less visible. If the user asks only how to configure it, give the relevant instructions without editing files.

package/plugins/pr-shepherd/skills/reduce-pr-noise/references/classifiers.md

@@ -0,0 +1,24 @@
+# Bot-comment classifiers
+
+Use a classification rule when the unwanted item has a recognizable author and message pattern. Inspect a representative item first so the rule does not hide other feedback from the same bot. Prefer an existing settings control for polling- or output-wide behavior.
+
+Place an `.mts` file in `.pr-shepherd/classification/` in the project. Shepherd uses the first classification directory on the working directory's ancestor chain; it stops at the home directory if reached, otherwise at the filesystem root. A home-level rule directory is not discovered when the project is outside the home tree. Rule directories do not merge. Files ending in `.ts`, `.mts`, `.mjs`, or `.js` load, except names beginning with `_` or `.`. An `.mts` rule can use erasable TypeScript syntax and `import type`, without transpilation-only features such as enums.
+
+Each file default-exports a `ClassifyRule` from `pr-shepherd/classify`. A rule receives one of `review-thread`, `pr-comment`, `review-summary`, or `changes-requested`, with `author`, `authorType`, `body`, `id`, and optional `url` or thread `path`. Match the observed `kind`, login, and distinctive body text. For example:
+
+```ts
+import type { ClassifyRule } from "pr-shepherd/classify";
+
+const rule: ClassifyRule = (item) => {
+  if (item.kind !== "pr-comment" && item.kind !== "review-summary") return null;
+  if (item.author.toLowerCase() !== "gemini-code-assist") return null;
+  if (!/^You have reached your daily quota limit\b/i.test(item.body)) return null;
+  return { suppress: true };
+};
+
+export default rule;
+```
+
+`suppress: true` removes a matched item from agent output. Add `autoResolve: true` only when the requested policy also calls for resolving its thread or minimizing its comment or review summary. It is unsupported for `changes-requested` reviews, whose dismissal needs a message. With both flags, `actions.autoMinimizeSuppressed: true` lets Shepherd perform the authorized mutation silently; when GitHub does not confirm capability, the item returns to normal first-look visibility. Matching rules combine their flags, so inspect existing rules before adding one.
+
+Exercise the exported rule against the observed item and negative examples: a different author, kind, and substantive message from the same bot. Confirm only the intended item matches before enabling automatic resolution. After editing a rule, restart a persistent MCP server or long-running poll process; it caches loaded rule modules. A new CLI process loads the change. A classifier does not retroactively remove already displayed output.