pr-shepherd 0.50.0 → 0.51.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.50.0",
+  "version": "0.51.1",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -144,10 +144,15 @@ needs agent work, all rows are terminal, the bounded timeout expires, or `--unti
 a configured GraphQL quota-warning band. Check counts use the same ignored, protected-run,
 superseded-run, and event rules as singular iteration and include active merge-queue commit checks.
 Bounded review/check overflow remains visible without permanently forcing work, and clean rows use
-the configured ready-delay before becoming terminal. Each actionable row includes
-an exact single-PR `pollCommand`; run independent actionable rows, then invoke the aggregate selector again.
-Stack rows are ordered bottom-to-top. API and MCP aggregate calls perform one summary tick and leave
-recurrence to the caller.
+the configured ready-delay before becoming terminal. Explicit PR sets give each actionable row an
+exact single-PR `pollCommand`, so independent rows can proceed before the next aggregate poll.
+Stack rows are ordered bottom-to-top and follow the one ordered stack instruction block instead.
+The summary also checks that every open child was based on
+its direct parent's current head. A stale child/parent OID pair is actionable even when GitHub
+reports both PRs clean: without `--merge`, rebase the upstack branches from their parent and push
+them with the emitted `gh stack` commands; with `--merge`, finish the contiguous ready lower
+layers with the emitted `gh stack merge --squash` command, recheck, then repair the child. API and
+MCP aggregate calls perform one summary tick and leave recurrence to the caller.
 
 Polling defaults can be set under `poll` in `.pr-shepherdrc.yml`: `intervalSeconds`, `timeoutSeconds`, `debounceSeconds`, and `quietStatus`. Explicit flags override configuration, including `--no-quiet-status` when a shared config enables quiet output. Quiet status remains off by default.
 
@@ -286,6 +291,8 @@ Environment variables:
 
 See [docs/configuration.md](docs/configuration.md) for the full reference.
 
+For guided noise reduction, use the plugin's `reduce-pr-noise` skill. It loads focused guidance for bot-comment classifiers or settings only when relevant; see [docs/skills.md](docs/skills.md).
+
 ### Classification rules
 
 Drop `.ts` / `.mts` / `.mjs` / `.js` files under `.pr-shepherd/classification/` to suppress and/or auto-resolve specific bot comments — useful for silencing repetitive noise like rate-limit notices from `gemini-code-assist` or "Reviews paused" from `coderabbitai`.

package/bin/checks/log-excerpt.d.mts

@@ -0,0 +1 @@
+export declare function buildLogExcerpt(raw: string): string | undefined;

package/bin/checks/log-excerpt.mjs

@@ -0,0 +1,192 @@
+import { loadConfig } from "../config/load.mjs";
+const LOG_EXCERPT_CONTEXT_LINES = 16;
+const LOG_EXCERPT_TAIL_LINES = 28;
+const LOG_EXCERPT_MAX_CHARS = 4_000;
+const TRUNCATED_MARK = "[truncated]";
+const ANSI_SGR_RE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+const STEP_GROUP_RE = /^##\[group\](?:Run |Post )/;
+const GROUP_RE = /^##\[group\]/;
+const ENDGROUP_RE = /^##\[endgroup\]$/;
+const POST_JOB_RE = /^(?:Post job cleanup\.?|Cleaning up orphan processes)$/;
+export function buildLogExcerpt(raw) {
+    const ignorePatterns = compileIgnoreLogLinePatterns();
+    const prepared = raw
+        .split(/\r?\n/)
+        .map(cleanLogLine)
+        .filter((line) => line.trim() !== "");
+    if (prepared.length === 0)
+        return undefined;
+    const isolated = isolateFailedStep(prepared);
+    const lines = isolated.lines
+        .map(stripGroupMarkers)
+        .filter((line) => line.trim() !== "" && !isNoiseLine(line, ignorePatterns));
+    if (lines.length === 0)
+        return undefined;
+    const aggregateExcerpt = buildAggregateJobResultsExcerpt(lines);
+    if (aggregateExcerpt !== undefined)
+        return aggregateExcerpt;
+    if (isolated.isolated) {
+        const errorIndex = findLogExcerptAnchor(lines);
+        return truncateTail(lines.join("\n"), errorIndex === -1 ? undefined : lines[errorIndex]);
+    }
+    return boundFallbackExcerpt(lines);
+}
+function isolateFailedStep(lines) {
+    const postJob = lines.findIndex((line) => POST_JOB_RE.test(line));
+    const capped = postJob === -1 ? lines : lines.slice(0, postJob);
+    const anchor = findLogExcerptAnchor(capped);
+    const groupStart = findPrecedingStepGroup(capped, anchor === -1 ? capped.length - 1 : anchor);
+    if (groupStart === -1)
+        return { lines: capped, isolated: false };
+    const endgroup = findMatchingEndgroup(capped, groupStart);
+    const after = endgroup === -1 ? groupStart + 1 : endgroup + 1;
+    const next = findNextStepGroup(capped, after);
+    return { lines: capped.slice(after, next === -1 ? capped.length : next), isolated: true };
+}
+function findPrecedingStepGroup(lines, from) {
+    for (let i = Math.min(from, lines.length - 1); i >= 0; i--) {
+        if (STEP_GROUP_RE.test(lines[i] ?? ""))
+            return i;
+    }
+    return -1;
+}
+function findMatchingEndgroup(lines, groupStart) {
+    let depth = 0;
+    for (let i = groupStart; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (GROUP_RE.test(line))
+            depth++;
+        else if (ENDGROUP_RE.test(line) && --depth === 0)
+            return i;
+    }
+    return -1;
+}
+function findNextStepGroup(lines, from) {
+    let depth = 0;
+    for (let i = from; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (GROUP_RE.test(line)) {
+            if (depth === 0 && STEP_GROUP_RE.test(line))
+                return i;
+            depth++;
+        }
+        else if (ENDGROUP_RE.test(line) && depth > 0)
+            depth--;
+    }
+    return -1;
+}
+function boundFallbackExcerpt(lines) {
+    const errorIndex = findLogExcerptAnchor(lines);
+    if (errorIndex === -1) {
+        return truncateLogExcerpt(lines.slice(-LOG_EXCERPT_TAIL_LINES).join("\n"));
+    }
+    const start = Math.max(0, errorIndex - LOG_EXCERPT_CONTEXT_LINES);
+    const excerpt = lines.slice(start, Math.min(lines.length, errorIndex + LOG_EXCERPT_CONTEXT_LINES + 1));
+    return truncateAnchoredExcerpt(excerpt, errorIndex - start);
+}
+function findLogExcerptAnchor(lines) {
+    const explicitError = lines.findIndex((line) => line.includes("##[error]"));
+    if (explicitError !== -1)
+        return explicitError;
+    return lines.findIndex((line) => /\b(error|failed|cancelled)\b/i.test(line));
+}
+function buildAggregateJobResultsExcerpt(lines) {
+    const jobResults = extractJobResults(lines);
+    if (jobResults === undefined)
+        return undefined;
+    const failed = Object.entries(jobResults)
+        .map(([name, value]) => ({ name, result: extractJobResult(value) }))
+        .filter((entry) => entry.result !== undefined && !["success", "skipped"].includes(entry.result));
+    if (failed.length === 0)
+        return undefined;
+    return truncateLogExcerpt([
+        ...lines.filter((line) => /required jobs failed|exit code \d+/i.test(line)),
+        "Job results (non-success):",
+        ...failed.map((entry) => `${entry.name}: ${entry.result}`),
+    ].join("\n"));
+}
+function extractJobResults(lines) {
+    const startIndex = lines.findIndex((line) => line.includes("Job results:"));
+    if (startIndex === -1)
+        return undefined;
+    const block = collectJsonBlock(lines, startIndex);
+    if (block === undefined)
+        return undefined;
+    try {
+        const parsed = JSON.parse(block);
+        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function collectJsonBlock(lines, startIndex) {
+    const startLine = lines[startIndex] ?? "";
+    const objectStart = startLine.indexOf("{");
+    if (objectStart === -1)
+        return undefined;
+    const collected = [startLine.slice(objectStart)];
+    let depth = braceDepth(collected[0]);
+    for (let i = startIndex + 1; i < lines.length && depth > 0; i++) {
+        const line = lines[i] ?? "";
+        collected.push(line);
+        depth += braceDepth(line);
+    }
+    return depth === 0 ? collected.join("\n") : undefined;
+}
+function braceDepth(line) {
+    return [...line].reduce((depth, ch) => {
+        if (ch === "{")
+            return depth + 1;
+        if (ch === "}")
+            return depth - 1;
+        return depth;
+    }, 0);
+}
+function extractJobResult(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const result = value.result;
+    return typeof result === "string" ? result : undefined;
+}
+function truncateLogExcerpt(text) {
+    if (text.length <= LOG_EXCERPT_MAX_CHARS)
+        return text;
+    return `${text.slice(0, LOG_EXCERPT_MAX_CHARS - `\n${TRUNCATED_MARK}`.length).trimEnd()}\n${TRUNCATED_MARK}`;
+}
+function truncateAnchoredExcerpt(lines, anchorIndex) {
+    const text = lines.join("\n");
+    if (text.length <= LOG_EXCERPT_MAX_CHARS)
+        return text;
+    return truncateLogExcerpt(`${TRUNCATED_MARK}\n${lines.slice(anchorIndex).join("\n")}`);
+}
+function truncateTail(text, keep) {
+    if (text.length <= LOG_EXCERPT_MAX_CHARS)
+        return text;
+    const head = `${TRUNCATED_MARK}\n`;
+    const slice = text.slice(-(LOG_EXCERPT_MAX_CHARS - head.length));
+    const nl = slice.indexOf("\n");
+    const tail = `${head}${nl === -1 ? slice : slice.slice(nl + 1)}`;
+    if (!keep || tail.includes(keep))
+        return tail;
+    const from = text.lastIndexOf(keep);
+    return from === -1 ? tail : truncateLogExcerpt(`${head}${text.slice(from)}`);
+}
+function compileIgnoreLogLinePatterns() {
+    return loadConfig().checks.ignoreLogLines.map((pattern) => new RegExp(pattern));
+}
+function isNoiseLine(line, patterns) {
+    return patterns.some((re) => re.test(line));
+}
+function cleanLogLine(line) {
+    return line
+        .replace(/^\uFEFF/, "")
+        .replace(ANSI_SGR_RE, "")
+        .replace(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z\s*/, "")
+        .trimEnd();
+}
+function stripGroupMarkers(line) {
+    return line.replace(/##\[(?:group|endgroup)\]/g, "");
+}

package/bin/checks/triage.mjs

@@ -1,13 +1,8 @@
 /* eslint-disable max-lines */
 import { restWithRateLimit, restText } from "../github/http.mjs";
 import { loadDerived, storeDerived } from "../state/rest-cache.mjs";
-import { loadConfig } from "../config/load.mjs";
+import { buildLogExcerpt } from "./log-excerpt.mjs";
 const STARTUP_FAILURE_STATUS = "startup_failure";
-const LOG_EXCERPT_CONTEXT_LINES = 16;
-const LOG_EXCERPT_TAIL_LINES = 28;
-const LOG_EXCERPT_MAX_CHARS = 4_000;
-const TRUNCATED_SUFFIX = "\n[truncated]";
-const ANSI_SGR_RE = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
 export function triageFailingChecks(failingChecks, repo, stateKey) {
     const jobsCache = new Map();
     return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache, stateKey)));
@@ -163,7 +158,7 @@ function pickJobInfo(jobs, checkName) {
  * never gets frozen into the cache.
  */
 async function fetchJobLogExcerpt(jobId, repo, stateKey, cacheable = false) {
-    const cacheName = `joblog-${jobId}`;
+    const cacheName = `joblog-v2-${jobId}`;
     if (stateKey && cacheable) {
         const cached = await loadDerived(stateKey, cacheName);
         if (cached)
@@ -181,117 +176,3 @@ async function fetchJobLogExcerpt(jobId, repo, stateKey, cacheable = false) {
         return undefined;
     }
 }
-function buildLogExcerpt(raw) {
-    const ignorePatterns = compileIgnoreLogLinePatterns();
-    const lines = raw
-        .split(/\r?\n/)
-        .map(cleanLogLine)
-        .filter((line) => line.trim() !== "" && !isNoiseLine(line, ignorePatterns));
-    if (lines.length === 0)
-        return undefined;
-    const aggregateExcerpt = buildAggregateJobResultsExcerpt(lines);
-    if (aggregateExcerpt !== undefined)
-        return aggregateExcerpt;
-    const errorIndex = findLogExcerptAnchor(lines);
-    if (errorIndex === -1)
-        return truncateLogExcerpt(lines.slice(-LOG_EXCERPT_TAIL_LINES).join("\n"));
-    const start = Math.max(0, errorIndex - LOG_EXCERPT_CONTEXT_LINES);
-    const excerpt = lines.slice(start, Math.min(lines.length, errorIndex + LOG_EXCERPT_CONTEXT_LINES + 1));
-    return truncateAnchoredExcerpt(excerpt, errorIndex - start);
-}
-function findLogExcerptAnchor(lines) {
-    const explicitError = lines.findIndex((line) => line.includes("##[error]"));
-    if (explicitError !== -1)
-        return explicitError;
-    return lines.findIndex((line) => /\b(error|failed|cancelled)\b/i.test(line));
-}
-function buildAggregateJobResultsExcerpt(lines) {
-    const jobResults = extractJobResults(lines);
-    if (jobResults === undefined)
-        return undefined;
-    const failed = Object.entries(jobResults)
-        .map(([name, value]) => ({ name, result: extractJobResult(value) }))
-        .filter((entry) => entry.result !== undefined && !["success", "skipped"].includes(entry.result));
-    if (failed.length === 0)
-        return undefined;
-    const output = [
-        ...lines.filter((line) => /required jobs failed|exit code \d+/i.test(line)),
-        "Job results (non-success):",
-        ...failed.map((entry) => `${entry.name}: ${entry.result}`),
-    ];
-    return truncateLogExcerpt(output.join("\n"));
-}
-function extractJobResults(lines) {
-    const startIndex = lines.findIndex((line) => line.includes("Job results:"));
-    if (startIndex === -1)
-        return undefined;
-    const block = collectJsonBlock(lines, startIndex);
-    if (block === undefined)
-        return undefined;
-    try {
-        const parsed = JSON.parse(block);
-        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
-            ? parsed
-            : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-function collectJsonBlock(lines, startIndex) {
-    const startLine = lines[startIndex] ?? "";
-    const objectStart = startLine.indexOf("{");
-    if (objectStart === -1)
-        return undefined;
-    const collected = [startLine.slice(objectStart)];
-    let depth = braceDepth(collected[0]);
-    for (let i = startIndex + 1; i < lines.length && depth > 0; i++) {
-        const line = lines[i] ?? "";
-        collected.push(line);
-        depth += braceDepth(line);
-    }
-    return depth === 0 ? collected.join("\n") : undefined;
-}
-function braceDepth(line) {
-    return [...line].reduce((depth, ch) => {
-        if (ch === "{")
-            return depth + 1;
-        if (ch === "}")
-            return depth - 1;
-        return depth;
-    }, 0);
-}
-function extractJobResult(value) {
-    if (value === null || typeof value !== "object" || Array.isArray(value))
-        return undefined;
-    const result = value.result;
-    return typeof result === "string" ? result : undefined;
-}
-function truncateLogExcerpt(text) {
-    if (text.length <= LOG_EXCERPT_MAX_CHARS)
-        return text;
-    return `${text.slice(0, LOG_EXCERPT_MAX_CHARS - TRUNCATED_SUFFIX.length).trimEnd()}${TRUNCATED_SUFFIX}`;
-}
-function truncateAnchoredExcerpt(lines, anchorIndex) {
-    const text = lines.join("\n");
-    if (text.length <= LOG_EXCERPT_MAX_CHARS)
-        return text;
-    return truncateLogExcerpt(`${TRUNCATED_SUFFIX.trim()}\n${lines.slice(anchorIndex).join("\n")}`);
-}
-// User-configured via `checks.ignoreLogLines` (regex source strings) — empty by
-// default. What counts as noise varies by CI toolchain, so Shepherd ships no
-// built-in patterns; a project opts in via `.pr-shepherdrc.yml`.
-function compileIgnoreLogLinePatterns() {
-    return loadConfig().checks.ignoreLogLines.map((pattern) => new RegExp(pattern));
-}
-function isNoiseLine(line, patterns) {
-    return patterns.some((re) => re.test(line));
-}
-function cleanLogLine(line) {
-    return line
-        .replace(/^\uFEFF/, "")
-        .replace(ANSI_SGR_RE, "")
-        .replace(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?Z\s*/, "")
-        .replace(/##\[(?:group|endgroup)\]/g, "")
-        .trimEnd();
-}

package/bin/cli/poll-summary-emitter.mjs

@@ -5,6 +5,21 @@ export function emitPollSummaryResult(result, opts) {
     process.exitCode = pollSummaryExitCode(result);
 }
 function pollSummaryExitCode(result) {
+    if (result.nextAction === "cancel" &&
+        result.prs.some((item) => item.reasons.includes("closed"))) {
+        return EXIT.CLOSED;
+    }
+    if (result.nextAction) {
+        const stackExitCode = {
+            escalate: EXIT.ESCALATE,
+            fix_code: EXIT.FIX_CODE,
+            merge: EXIT.MERGE,
+            mark_ready: EXIT.MARK_READY,
+            wait: EXIT.WAIT,
+            cancel: EXIT.OK,
+        };
+        return stackExitCode[result.nextAction] ?? EXIT.OK;
+    }
     const actions = new Set(result.prs.map((item) => item.action));
     if (actions.has("escalate"))
         return EXIT.ESCALATE;

package/bin/cli/poll-summary-formatter.mjs

@@ -1,5 +1,5 @@
 import { formatApiUsage, formatQuotaWarning } from "./api-usage-formatter.mjs";
-import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
+import { withPollSummaryInstructions } from "../commands/poll-summary-instructions.mjs";
 export function formatPollSummaryResult(result) {
     const selection = result.selection.kind === "stack"
         ? `stack #${result.selection.stackNumber} anchored at PR #${result.selection.anchor} (${result.selection.stackSize} PRs)`
@@ -7,42 +7,28 @@ export function formatPollSummaryResult(result) {
     const lines = [
         `# Poll summary [${result.reason.toUpperCase()}]`,
         "",
-        `**repo** \`${result.repo}\` · **selection** ${selection} · **mode** \`${result.mode}\``,
+        `**repo** \`${result.repo}\` · **selection** ${selection} · **mode** \`${result.mode}\`${result.nextAction ? ` · **next action** \`${result.nextAction}\`` : ""}`,
         "",
         "## Pull requests",
         "",
         ...result.prs.map(formatItem),
     ];
+    if (result.stackAncestry?.length) {
+        lines.push("", "## Stack ancestry", "");
+        for (const pair of result.stackAncestry) {
+            lines.push(`- PR #${pair.childPr} base \`${pair.childBaseRefName}\` at \`${pair.childBaseRefOid}\` differs from parent PR #${pair.parentPr} head \`${pair.parentHeadRefName}\` at \`${pair.parentHeadRefOid}\`.`);
+        }
+    }
     const apiUsage = result.apiUsage ? formatApiUsage(result.apiUsage) : null;
     const quotaWarning = formatQuotaWarning(result.quotaWarning);
     if (quotaWarning)
         lines.push("", quotaWarning);
     if (apiUsage)
         lines.push("", apiUsage);
-    lines.push("", "## Instructions", "", ...formatInstructions(result));
+    const instructions = result.instructions ?? withPollSummaryInstructions(result, false).instructions ?? [];
+    lines.push("", "## Instructions", "", ...instructions);
     return lines.join("\n");
 }
-function formatInstructions(result) {
-    if (result.reason === "all_terminal")
-        return ["1. Stop — every selected PR is terminal."];
-    if (result.quotaWarning && result.reason !== "actionable") {
-        return [
-            buildQuotaAwareContinuation(result.quotaWarning, "1. This aggregate selection is non-terminal. Before continuing,"),
-        ];
-    }
-    if (result.reason === "waiting" || result.reason === "timeout") {
-        return ["1. Run this aggregate selector again when the caller is ready to recheck."];
-    }
-    const instructions = [
-        "1. Choose each non-WAIT, non-CANCEL row that can proceed independently and run or delegate its exact `pollCommand`.",
-        "2. Follow each selected one-PR poll's `## Instructions` until it returns `CANCEL` or `ESCALATE`.",
-        "3. Run this aggregate poll again after selected work completes; one row's `ESCALATE` does not stop work on other rows.",
-    ];
-    if (result.quotaWarning) {
-        instructions[2] = buildQuotaAwareContinuation(result.quotaWarning, "3. After selected work completes,");
-    }
-    return instructions;
-}
 function formatItem(item) {
     const flags = [item.isDraft ? "draft" : null, item.isInMergeQueue ? "queued" : null]
         .filter((value) => value !== null)

package/bin/commands/poll-quota.d.mts

@@ -1,5 +1,5 @@
 import type { GraphqlQuotaWarningBand } from "../config/load.mts";
-import type { GraphqlApiUsage } from "../types.mts";
+import type { GraphqlApiUsage, PollSummaryResult } from "../types.mts";
 /** Sleep at least `--interval`, and at least the active crossed quota band. */
 export declare function graphqlQuotaPollIntervalMs(bands: GraphqlQuotaWarningBand[], usage: Pick<GraphqlApiUsage, "remaining" | "limit"> | undefined, fallbackMs: number, maxMs: number): number;
 /**
@@ -7,3 +7,4 @@ export declare function graphqlQuotaPollIntervalMs(bands: GraphqlQuotaWarningBan
  * limit. `null` means the error is not a retryable rate limit.
  */
 export declare function pollGraphQlRetryAfterMs(err: unknown): number | null;
+export declare function aggregateQuotaWarning(result: PollSummaryResult, bands: GraphqlQuotaWarningBand[], intervalSeconds: number): Promise<PollSummaryResult["quotaWarning"]>;

package/bin/commands/poll-quota.mjs

@@ -1,3 +1,5 @@
+import { evaluateWorktreeGraphqlQuotaWarning } from "../state/graphql-quota-warnings.mjs";
+import { summarizeApiTelemetry } from "../github/api-telemetry.mjs";
 import { GitHubRequestError } from "../github/errors.mjs";
 import { isRateLimitMessage } from "../comments/rate-limit.mjs";
 const GRAPHQL_RETRY_AFTER_DEFAULT_MS = 60_000;
@@ -34,3 +36,13 @@ export function pollGraphQlRetryAfterMs(err) {
     }
     return GRAPHQL_RETRY_AFTER_DEFAULT_MS;
 }
+export 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);
+}

package/bin/commands/poll-summary-explicit-instructions.d.mts

@@ -0,0 +1,2 @@
+import type { PollSummaryResult } from "../types.mts";
+export declare function explicitInstructions(result: PollSummaryResult): string[];

package/bin/commands/poll-summary-explicit-instructions.mjs

@@ -0,0 +1,22 @@
+import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
+export function explicitInstructions(result) {
+    if (result.reason === "all_terminal")
+        return ["1. Stop — every selected PR is terminal."];
+    if (result.quotaWarning && result.reason !== "actionable") {
+        return [
+            buildQuotaAwareContinuation(result.quotaWarning, "1. This aggregate selection is non-terminal. Before continuing,"),
+        ];
+    }
+    if (result.reason === "waiting" || result.reason === "timeout") {
+        return ["1. Run this aggregate selector again when the caller is ready to recheck."];
+    }
+    const instructions = [
+        "1. Choose each non-WAIT, non-CANCEL row that can proceed independently and run or delegate its exact `pollCommand`.",
+        "2. Follow each selected one-PR poll's `## Instructions` until it returns `CANCEL` or `ESCALATE`.",
+        "3. Run this aggregate poll again after selected work completes; one row's `ESCALATE` does not stop work on other rows.",
+    ];
+    if (result.quotaWarning) {
+        instructions[2] = buildQuotaAwareContinuation(result.quotaWarning, "3. After selected work completes,");
+    }
+    return instructions;
+}

package/bin/commands/poll-summary-instructions.d.mts

@@ -0,0 +1,3 @@
+import type { PollSummaryResult } from "../types.mts";
+/** Keep aggregate JSON, Markdown, and MCP instructions on one projection. */
+export declare function withPollSummaryInstructions(result: PollSummaryResult, mergeRequested: boolean): PollSummaryResult;

package/bin/commands/poll-summary-instructions.mjs

@@ -0,0 +1,139 @@
+import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
+import { explicitInstructions } from "./poll-summary-explicit-instructions.mjs";
+/** Keep aggregate JSON, Markdown, and MCP instructions on one projection. */
+export function withPollSummaryInstructions(result, mergeRequested) {
+    if (result.selection.kind !== "stack") {
+        return { ...result, instructions: explicitInstructions(result) };
+    }
+    const planned = planStack(result, mergeRequested);
+    const reason = planned.action === "cancel"
+        ? "all_terminal"
+        : planned.action === "wait"
+            ? result.reason === "timeout"
+                ? "timeout"
+                : "waiting"
+            : "actionable";
+    const instructions = [...planned.instructions];
+    if (result.quotaWarning && planned.action !== "wait" && planned.action !== "cancel") {
+        instructions.push(buildQuotaAwareContinuation(result.quotaWarning, `${instructions.length + 1}. After completing the stack action,`));
+    }
+    return { ...result, reason, nextAction: planned.action, instructions };
+}
+function planStack(result, mergeRequested) {
+    const open = result.prs.filter((item) => item.state === "OPEN");
+    if (open.length === 0) {
+        return { action: "cancel", instructions: ["1. Stop — every selected PR is terminal."] };
+    }
+    const lastOpenPosition = positionOf(result, open.at(-1).pr);
+    const closedBelowOpen = result.prs.find((item) => item.state === "CLOSED" && positionOf(result, item.pr) < lastOpenPosition);
+    if (closedBelowOpen) {
+        return {
+            action: "escalate",
+            instructions: [
+                `1. PR #${closedBelowOpen.pr} is closed without merging below an open stack layer. Stop stack merge and rebase operations here; the closed dependency must be restored or the higher branches rebuilt on a valid base.`,
+                "2. Ask the stack owner which recovery path to take, then rerun the same aggregate `--stack` selector after the stack is repaired.",
+            ],
+        };
+    }
+    const gap = result.stackAncestry?.[0];
+    const firstOpen = open[0];
+    if (firstOpen.mergeStateStatus === "BEHIND")
+        return rebaseWholeStack(result, firstOpen);
+    if (mergeRequested) {
+        const mergeTarget = readyLowerStackTarget(open, result.stackAncestry ?? []);
+        if (mergeTarget) {
+            const stackNumber = result.selection.kind === "stack" ? result.selection.stackNumber : 0;
+            return {
+                action: "merge",
+                instructions: [
+                    `1. The contiguous ready lower stack ends at PR #${mergeTarget.pr}. Merge the native stack through that PR with \`gh stack merge --squash ${mergeTarget.pr}\`; verify that the selector names PR #${mergeTarget.pr} in stack #${stackNumber} before running it. This includes still-open lower layers and leaves higher layers open.`,
+                    "2. After GitHub completes the stack merge and updates the remaining branches, rerun the same aggregate `--stack` selector. If an ancestry mismatch remains, follow the rebase instructions returned then.",
+                ],
+            };
+        }
+        if (firstOpen.action === "wait") {
+            return waitingStack(result);
+        }
+    }
+    const firstWork = open.find((item) => ["fix_code", "mark_ready", "escalate"].includes(item.action));
+    if (firstWork && (!gap || positionOf(result, firstWork.pr) <= positionOf(result, gap.childPr))) {
+        return pollOneLayer(firstWork);
+    }
+    if (gap) {
+        return {
+            action: "fix_code",
+            instructions: [
+                `1. PR #${gap.childPr} still records base \`${gap.childBaseRefName}\` at \`${gap.childBaseRefOid}\`, while parent PR #${gap.parentPr} now ends at \`${gap.parentHeadRefName}\` \`${gap.parentHeadRefOid}\`. From a clean checkout of \`${result.repo}\`, check out the parent stack branch \`${gap.parentHeadRefName}\`.`,
+                "2. Rebase the upstack branches onto that parent with `gh stack rebase --upstack --no-trunk`, resolve any conflicts, and push the rewritten branches with `gh stack push`.",
+                "3. Rerun the same aggregate `--stack` selector and follow the next returned action.",
+            ],
+        };
+    }
+    const behind = open.find((item) => item.mergeStateStatus === "BEHIND");
+    if (behind)
+        return rebaseWholeStack(result, behind);
+    if (firstWork)
+        return pollOneLayer(firstWork);
+    if (!mergeRequested && open.every((item) => item.action === "cancel")) {
+        return {
+            action: "cancel",
+            instructions: ["1. Stop — every open stack layer is ready and the stack is linear."],
+        };
+    }
+    return waitingStack(result);
+}
+function rebaseWholeStack(result, behind) {
+    return {
+        action: "fix_code",
+        instructions: [
+            `1. GitHub reports PR #${behind.pr} is behind its base \`${behind.baseRefName}\`. From a clean checkout of \`${result.repo}\`, check out its stack branch \`${behind.headRefName}\`.`,
+            "2. Rebase that native stack from its trunk with `gh stack rebase`, resolving any conflicts.",
+            "3. Push the updated stack with `gh stack push` and rerun the same aggregate `--stack` selector.",
+        ],
+    };
+}
+function readyLowerStackTarget(open, gaps) {
+    const mismatchedChildren = new Set(gaps.map((gap) => gap.childPr));
+    let target;
+    for (const item of open) {
+        if (mismatchedChildren.has(item.pr) || item.action !== "merge")
+            break;
+        target = item;
+    }
+    return target;
+}
+function positionOf(result, pr) {
+    return result.prs.find((item) => item.pr === pr)?.stack?.position ?? Number.MAX_SAFE_INTEGER;
+}
+function pollOneLayer(item) {
+    if (!item.pollCommand) {
+        return {
+            action: "escalate",
+            instructions: [
+                `1. PR #${item.pr} needs attention, but GitHub returned no one-PR poll command.`,
+            ],
+        };
+    }
+    return {
+        action: item.action,
+        instructions: [
+            `1. Work on the lowest actionable layer, PR #${item.pr}: run \`${item.pollCommand}\`.`,
+            "2. Follow that one-PR poll's `## Instructions` until it returns `CANCEL` or `ESCALATE`.",
+            "3. Rerun the aggregate `--stack` selector before acting on a higher layer.",
+        ],
+    };
+}
+function waitingStack(result) {
+    if (result.quotaWarning) {
+        return {
+            action: "wait",
+            instructions: [
+                buildQuotaAwareContinuation(result.quotaWarning, "1. This native stack is non-terminal. Before continuing,"),
+            ],
+        };
+    }
+    return {
+        action: "wait",
+        instructions: ["1. Recheck this native stack after the lowest open layer changes state."],
+    };
+}

package/bin/commands/poll-summary-signature.d.mts

@@ -0,0 +1,2 @@
+import type { PollSummaryResult } from "../types.mts";
+export declare function summaryStatusSignature(result: PollSummaryResult): string;

package/bin/commands/poll-summary-signature.mjs

@@ -0,0 +1,16 @@
+export function summaryStatusSignature(result) {
+    return JSON.stringify({
+        nextAction: result.nextAction,
+        stackAncestry: result.stackAncestry,
+        prs: 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,
+        })),
+    });
+}

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/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/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.50.0",
+  "version": "0.51.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",
@@ -85,14 +85,14 @@
   "devDependencies": {
     "@types/node": "^26.0.0",
     "@types/picomatch": "^4.0.3",
-    "@vitest/coverage-v8": "^4.1.4",
+    "@vitest/coverage-v8": "^5.0.0",
     "husky": "^9.1.7",
     "knip": "^6.14.1",
     "marked": "^18.0.11",
-    "oxfmt": "^0.65.0",
+    "oxfmt": "^0.66.0",
     "oxlint": "^1.60.0",
     "typescript": "^7.0.2",
-    "vitest": "^4.1.4"
+    "vitest": "^5.0.0"
   },
   "engines": {
     "node": ">=22.18.0"

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

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.50.0",
+  "version": "0.51.1",
   "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.50.0", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.51.1", "pr-shepherd-mcp"]
     }
   }
 }

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

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.50.0", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.51.1", "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.
 

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.

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

@@ -0,0 +1,27 @@
+# Noise settings
+
+Inspect the unwanted Shepherd output, any active `.pr-shepherdrc.yml` files, and the built-in defaults before editing. Shepherd deep-merges files from the user's home directory through the working directory: closer scalar values win, nested maps merge, and closer arrays replace farther arrays. Put shared policy in the project file and personal preferences in the home file. Preserve unrelated values and existing list entries when changing an array.
+
+Choose the narrowest control for the observed source:
+
+| Source                                    | Setting                                              | Effect                                                                                                                                                                                                                   |
+| ----------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Repeated unchanged `WAIT` status          | `poll.quietStatus: true` or one-run `--quiet-status` | Hides unchanged polling snapshots; it does not affect single-tick `iterate` or MCP calls.                                                                                                                                |
+| Repetitive CI log lines                   | `checks.ignoreLogLines`                              | Drops matching raw log lines from failure excerpts and annotation deduplication input. Patterns are regex source strings.                                                                                                |
+| An irrelevant check context               | `ignoreChecks`                                       | Removes detailed check status and readiness, triage, and stall effects; names remain in the `**ignored**` rollup. Patterns are case-insensitive globs; `actions.neverCancelRuns` can keep matching Actions runs visible. |
+| Non-human PR comments or review summaries | `iterate.minimizeComments: all`, `bots`, or `none`   | Controls eligible minimization; `all` is already the default. Excluded items still appear on first look and after edits.                                                                                                 |
+| Non-human approval reviews                | `iterate.minimizeApprovals: true`                    | Also makes eligible approvals minimizable; the default is `false`.                                                                                                                                                       |
+
+For example, a project that wants quieter polling and to remove a known teardown line from CI excerpts can use:
+
+```yaml
+poll:
+  quietStatus: true
+checks:
+  ignoreLogLines:
+    - "^\\[vitest-teardown\\]"
+```
+
+Do not use `ignoreChecks` merely to hide a failing or required check: the check no longer contributes to Shepherd's readiness decision. `botUsernames` extends bot detection and handling, but configured-bot threads remain visible every tick until resolved, so it is not a general suppression setting. For a specific bot message, use the classifier guide instead. `actions.autoMinimizeSuppressed` only changes the treatment of classifier matches that set both `suppress` and `autoResolve` and is already `true` by default.
+
+After editing, validate the YAML and regex syntax, check that the intended config file wins in the cascade, and compare representative output with the expected effect. If a live PR is used to verify behavior, account for any review mutation the configured action may authorize.