pr-shepherd 0.60.0 → 1.0.0

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.60.0",
+  "version": "1.0.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -13,7 +13,7 @@ Drive a pull request to merge-ready with a coding agent. It works with Claude Co
 ```text
 $ pr-shepherd 123
 
-# PR #123 [FIX_CODE]
+# PR #123 [TRIAGE]
 
 **status** `UNRESOLVED_COMMENTS` · **repo** `owner/repo`
 **summary** 3 passing
@@ -96,7 +96,7 @@ These are offline estimates at 3.5 characters per token over recorded sessions,
 
 ### Clearer agent direction
 
-For a single PR, each tick returns exactly one action: `WAIT`, `READY`, `MARK_READY`, `FIX_CODE`, `MERGE`, `CANCEL`, or `ESCALATE`. A `--stack` poll can also return `SHEPHERD`, which starts one-PR sessions for owned layers. Every action except `CANCEL` comes with numbered `## Instructions` and exact commands, so the agent does not invent policy. In the [behavior evals](evals/README.md), Sonnet 5.5 at low effort scores **0.94** with the plugin and **0.82** without it on the 36 GitHub-gotcha cases, so it misses about two-thirds fewer graded checks (0.18 → 0.06). On the eight gotchas listed under [Context and correctness](#context-and-correctness) it goes from 0.50 to 0.92. Weighted toward those gotchas, the mean Δ over all 52 cases is **+0.14**, and no case has a regression whose interval excludes 0. See [docs/actions.md](docs/actions.md) for the output contract.
+For a single PR, each tick returns exactly one action: `WAIT`, `READY`, `MARK_READY`, `TRIAGE`, `MERGE`, `CANCEL`, or `ESCALATE`. A `stack` poll can also return `SHEPHERD`, which starts one-PR sessions for owned layers. Every action except `CANCEL` comes with numbered `## Instructions` and exact commands, so the agent does not invent policy. In the [behavior evals](evals/README.md), Sonnet 5.5 at low effort scores **0.94** with the plugin and **0.82** without it on the 36 GitHub-gotcha cases, so it misses about two-thirds fewer graded checks (0.18 → 0.06). On the eight gotchas listed under [Context and correctness](#context-and-correctness) it goes from 0.50 to 0.92. Weighted toward those gotchas, the mean Δ over all 52 cases is **+0.14**, and no case has a regression whose interval excludes 0. See [docs/actions.md](docs/actions.md) for the output contract.
 
 ### Lower GitHub API quota use
 
@@ -139,8 +139,8 @@ See [docs/graphql-usage.md](docs/graphql-usage.md) and [docs/rest-usage.md](docs
 - The plugin ships [skills](docs/skills.md) for Claude Code, Codex, and Grok.
 - Cursor and other stdio clients use the [MCP server](docs/mcp.md).
 - Shell and CI use the [CLI](docs/cli-usage.md).
-- In Claude Code cloud sessions, Shepherd switches to the [REST transport](docs/rest.md) and [event mode](docs/cloud.md).
-- `--stack` reports every layer of a native GitHub stacked PR and shepherds the layers you own.
+- In Claude Code cloud sessions, Shepherd switches to the [REST transport](docs/rest.md) and [single ticks](docs/cloud.md).
+- `stack` reports every layer of a native GitHub stacked PR and shepherds the layers you own.
 
 ## Use cases
 
@@ -151,9 +151,10 @@ See [docs/graphql-usage.md](docs/graphql-usage.md) and [docs/rest-usage.md](docs
 
 1. **Install the MCP server and the CLI.** See [Install](#install) below.
 2. **Write your policy into a skill or agent instruction.** Examples: "skip non-blocking review comments", "reply instead of fixing nits", "never merge". Shepherd reports state and the next action. Your instructions decide how the agent treats each comment. The shipped `pr-shepherd` skill is a thin dispatcher you can wrap ([docs/skills.md](docs/skills.md)).
-3. **Configure Shepherd.** In `.pr-shepherdrc.yml`, turn on the bundled classification rules. They drop known bot noise before it reaches the agent, which saves more tokens and tool calls. With the default `actions.autoMinimizeSuppressed: true`, several rules also minimize matching comments on GitHub and surface the mutation result without editing the PR body. See [docs/configuration.md](docs/configuration.md#classifystandard--default-).
+3. **Configure Shepherd.** In `.pr-shepherdrc.yml`, turn on the bundled classification rules. They drop known bot noise before it reaches the agent, which saves more tokens and tool calls. With the default `actions.auto-minimize-suppressed: true`, several rules also minimize matching comments on GitHub and surface the mutation result without editing the PR body. See [docs/configuration.md](docs/configuration.md#classifystandard--default-).
 
    ```yaml
+   version: 1
    classify:
      standard:
        all: true
@@ -212,6 +213,7 @@ Leave out the PR number to use the current branch.
 | Configuration and classification rules       | [docs/configuration.md](docs/configuration.md), [examples/classification/](examples/classification/) |
 | Journal, library API                         | [docs/api.md](docs/api.md)                                                                           |
 | Compared with Cursor, Copilot, CodeRabbit, … | [docs/comparison.md](docs/comparison.md)                                                             |
+| Upgrading from 0.x                           | [docs/migrating-to-v1.md](docs/migrating-to-v1.md)                                                   |
 
 ## Harness ecosystem
 

package/bin/api.d.mts

@@ -4,11 +4,20 @@ import { type ApplyMergeResult } from "./commands/apply-merge.mts";
 import type { RestMergeAction, RestMergeStackGuard } from "./github/rest-merge.mts";
 export type { RestMergeStackGuard } from "./github/rest-merge.mts";
 import type { MergeMethod } from "./config/merge-method.mts";
+import { type CheckBlockerCommandResult } from "./commands/apply-check-blocker.mts";
 import { type JournalResult } from "./commands/journal/index.mts";
 import { type MarkFilesAsViewedResult } from "./commands/mark-files-as-viewed.mts";
 import { type ApplyQueueRemovalResult } from "./commands/apply-queue-removal.mts";
 import type { ResolveResult } from "./comments/resolve.mts";
-import type { BuildSuggestionPatchesResult, CommitSuggestionResult, IterateCommandOptions, IterateResult, PollSummaryResult } from "./types.mts";
+import type { SuggestResult, IterateCommandOptions, IterateResult, PollSummaryResult } from "./types.mts";
+export type { CancelReason, IterateResult, IterateResultTriage, IterateResultMerge, NextCheck, PollSummaryItem, PollSummaryResult, ShepherdAction, ShepherdMergeStatus, ShepherdStatus, StackNextAction, SuggestResult, SuggestionPatchResult, } from "./types.mts";
+export type { ApplyMergeResult } from "./commands/apply-merge.mts";
+export type { MarkFilesAsViewedResult } from "./commands/mark-files-as-viewed.mts";
+export type { ApplyQueueRemovalResult } from "./commands/apply-queue-removal.mts";
+export type { CheckBlockerCommandResult } from "./commands/apply-check-blocker.mts";
+export type { JournalResult } from "./commands/journal/index.mts";
+export type { ResolveResult } from "./comments/resolve.mts";
+export type { ShepherdJournalExtraction } from "./journal/index.mts";
 import { type ShepherdJournalExtraction } from "./journal/index.mts";
 export interface CreatePrShepherdOptions {
     /** GitHub transport retained for this client; individual calls may override it. */
@@ -22,18 +31,17 @@ type IterateOptions = Omit<IterateCommandOptions, "format" | "prNumber" | "targe
 export type SingleIterateInput = IterateOptions & {
     pr?: PrReference;
     prs?: never;
-    stack?: never;
 };
-export type AggregateIterateInput = IterateOptions & ({
+/** One aggregate tick over several PRs from one repository. */
+export type MultiIterateInput = IterateOptions & {
     prs: PrReference[];
     pr?: never;
-    stack?: never;
-} | {
-    stack: PrReference;
-    pr?: never;
-    prs?: never;
-});
-export type IterateInput = SingleIterateInput | AggregateIterateInput;
+};
+export type IterateInput = SingleIterateInput | MultiIterateInput;
+/** One aggregate tick over the native stack containing `pr`. */
+export type StackInput = IterateOptions & {
+    pr: PrReference;
+};
 export interface ReviewMutationsOperation {
     type: "review_mutations";
     resolveThreadIds?: string[];
@@ -63,6 +71,14 @@ export interface AcknowledgeQueueRemovalOperation {
     queueCommitOid: string;
     removedAtUnix: number;
 }
+export interface CheckBlockerOperation {
+    /** Record (`blockedBy`) or clear (`clear: true`) an external blocker for one failing check. */
+    type: "check_blocker";
+    check: string;
+    /** PR/issue URL, `owner/repo#N`, or `issue:owner/repo#N`. */
+    blockedBy?: string;
+    clear?: boolean;
+}
 export interface MergeOperation {
     type: "merge";
     requireSha: string;
@@ -71,7 +87,7 @@ export interface MergeOperation {
     expectedStack?: RestMergeStackGuard;
 }
 /** Operations run in this exact list order after validation. */
-export type ApplyOperation = MergeOperation | ReviewMutationsOperation | MarkFilesViewedOperation | AppendJournalOperation | AcknowledgeQueueRemovalOperation;
+export type ApplyOperation = MergeOperation | ReviewMutationsOperation | MarkFilesViewedOperation | AppendJournalOperation | AcknowledgeQueueRemovalOperation | CheckBlockerOperation;
 export interface ApplyInput {
     transport?: GithubTransport;
     /** PR shared by every operation in this ordered apply request. */
@@ -93,23 +109,19 @@ export type ApplyOperationResult = {
 } | {
     type: "acknowledge_queue_removal";
     result: ApplyQueueRemovalResult;
+} | {
+    type: "check_blocker";
+    result: CheckBlockerCommandResult;
 };
 export interface ApplyResult {
     operations: ApplyOperationResult[];
 }
-export interface BuildSuggestionPatchInput {
-    transport?: GithubTransport;
-    pr?: PrReference;
-    threadId: string;
-    message: string;
-    description?: string;
-}
 export interface SuggestionPatchInput {
     threadId: string;
     message: string;
     description?: string;
 }
-export interface BuildSuggestionPatchesInput {
+export interface SuggestInput {
     transport?: GithubTransport;
     pr?: PrReference;
     suggestions: SuggestionPatchInput[];
@@ -120,13 +132,12 @@ export interface GetJournalInput {
 }
 export interface PrShepherd {
     iterate(input?: SingleIterateInput): Promise<IterateResult>;
-    iterate(input: AggregateIterateInput): Promise<PollSummaryResult>;
+    iterate(input: MultiIterateInput): Promise<PollSummaryResult>;
     iterate(input: IterateInput): Promise<IterateResult | PollSummaryResult>;
+    stack(input: StackInput): Promise<PollSummaryResult>;
     apply(input: ApplyInput): Promise<ApplyResult>;
-    buildSuggestionPatches(input: BuildSuggestionPatchesInput): Promise<BuildSuggestionPatchesResult>;
+    suggest(input: SuggestInput): Promise<SuggestResult>;
     getJournal(input: GetJournalInput): Promise<ShepherdJournalExtraction>;
-    /** Compatibility adapter; prefer buildSuggestionPatches. */
-    buildSuggestionPatch(input: BuildSuggestionPatchInput): Promise<CommitSuggestionResult>;
 }
 /** Raised before any API mutation when an input cannot be validated. */
 export declare class PrShepherdValidationError extends Error {
@@ -140,6 +151,6 @@ export declare class PartialApplyError extends Error {
 }
 /**
  * Creates the programmatic API. The returned object intentionally exposes only
- * read/plan, ordered apply, and suggestion-patch operations.
+ * read/plan (`iterate`, `stack`), ordered apply, and suggestion-patch (`suggest`) operations.
  */
 export declare function createPrShepherd(options?: CreatePrShepherdOptions): PrShepherd;

package/bin/api.mjs

@@ -2,15 +2,17 @@
 import { resolve } from "node:path";
 import { createGithubTransportRunner } from "./github/transport.mjs";
 import { runApplyMerge, validateApplyMergeOptions, } from "./commands/apply-merge.mjs";
-import { runCommitSuggestion } from "./commands/commit-suggestion.mjs";
 import { runSuggestionPatches } from "./commands/suggestion-patches.mjs";
-import { runIterateForMode, runPollSummaryForMode } from "./commands/event-mode.mjs";
+import { runIterateTick, runPollSummaryTick } from "./commands/tick.mjs";
+import { applyCheckBlocker, } from "./commands/apply-check-blocker.mjs";
+import { parseBlockedByRef } from "./commands/check-blocker-ref.mjs";
 import { runJournal } from "./commands/journal/index.mjs";
 import { validateJournalItem } from "./commands/journal/transform.mjs";
 import { runMarkFilesAsViewed, } from "./commands/mark-files-as-viewed.mjs";
 import { runResolveMutate } from "./commands/resolve-mutate.mjs";
 import { applyQueueRemovalAck, } from "./commands/apply-queue-removal.mjs";
 import { runWithExecutionCwd } from "./execution-context.mjs";
+import { loadConfig } from "./config/load.mjs";
 import { parsePrReference, normalizeRepositoryIdentity, resolveParsedPrTarget, } from "./pr-reference.mjs";
 import { getPullRequestBody, getRepoInfo } from "./github/client.mjs";
 import { getLocalHeadSha } from "./commands/suggestion-patch-git.mjs";
@@ -36,28 +38,49 @@ export class PartialApplyError extends Error {
 }
 /**
  * Creates the programmatic API. The returned object intentionally exposes only
- * read/plan, ordered apply, and suggestion-patch operations.
+ * read/plan (`iterate`, `stack`), ordered apply, and suggestion-patch (`suggest`) operations.
  */
 export function createPrShepherd(options = {}) {
     const cwd = options.cwd === undefined ? undefined : resolve(options.cwd);
     const transportRunner = createGithubTransportRunner(options.transport);
     function runInClient(input, work) {
-        return runWithExecutionCwd(cwd, () => transportRunner(work, input?.transport));
+        // Validate config first, as the CLI does, so a bad or pre-v1 file rejects before GitHub I/O.
+        return runWithExecutionCwd(cwd, async () => {
+            loadConfig();
+            return transportRunner(work, input?.transport);
+        });
     }
     function iterate(input = {}) {
         return runInClient(input, async () => {
-            validateIterateSelectors(input);
-            if ("prs" in input || "stack" in input) {
-                const target = await resolveAggregateIterateInput(input);
-                return runPollSummaryForMode(target);
+            if ("pr" in input && "prs" in input) {
+                throw new PrShepherdValidationError("iterate pr and prs selectors are mutually exclusive");
+            }
+            if ("prs" in input) {
+                const { prs, pr: _pr, ...options } = input;
+                const { numbers, repository } = await resolveSameRepositoryRefs(prs, "iterate.prs");
+                return runPollSummaryTick({ ...options, prNumbers: numbers, targetRepository: repository });
             }
-            const { pr: _pr, ...iterateOptions } = input;
+            const { pr: _pr, prs: _prs, ...iterateOptions } = input;
             const target = resolvePrReference(input.pr);
-            return runIterateForMode({ ...iterateOptions, ...target, format: "json" });
+            return runIterateTick({ ...iterateOptions, ...target, format: "json" });
         });
     }
     return Object.freeze({
         iterate,
+        stack(input) {
+            return runInClient(input ?? {}, async () => {
+                if (!input || input.pr === undefined) {
+                    throw new PrShepherdValidationError("stack requires a PR reference");
+                }
+                const { pr, ...options } = input;
+                const { numbers, repository } = await resolveSameRepositoryRefs([pr], "stack.pr");
+                return runPollSummaryTick({
+                    ...options,
+                    stackPrNumber: numbers[0],
+                    targetRepository: repository,
+                });
+            });
+        },
         getJournal(input) {
             return runInClient(input, async () => {
                 const { prNumber, targetRepository } = resolvePrReference(input.pr);
@@ -127,6 +150,18 @@ export function createPrShepherd(options = {}) {
                                 results.push({ type: operation.type, result });
                                 break;
                             }
+                            case "check_blocker": {
+                                const result = await applyCheckBlocker({
+                                    prNumber,
+                                    targetRepository,
+                                    checkName: operation.check,
+                                    ...(operation.clear
+                                        ? { clear: true }
+                                        : { blocker: parseBlockedByRef(operation.blockedBy) }),
+                                });
+                                results.push({ type: operation.type, result });
+                                break;
+                            }
                             case "acknowledge_queue_removal": {
                                 const result = await applyQueueRemovalAck({
                                     prNumber,
@@ -149,16 +184,8 @@ export function createPrShepherd(options = {}) {
                 return { operations: results };
             });
         },
-        buildSuggestionPatch(input) {
-            validateSuggestionPatchInput(input);
-            const { pr: _pr, ...options } = input;
-            return runInClient(input, async () => {
-                const target = resolvePrReference(input.pr);
-                return runCommitSuggestion({ ...options, ...target, format: "json" });
-            });
-        },
-        buildSuggestionPatches(input) {
-            validateSuggestionPatchesInput(input);
+        suggest(input) {
+            validateSuggestInput(input);
             const { pr: _pr, ...options } = input;
             return runInClient(input, async () => {
                 const target = resolvePrReference(input.pr);
@@ -167,10 +194,9 @@ export function createPrShepherd(options = {}) {
         },
     });
 }
-async function resolveAggregateIterateInput(input) {
-    const refs = "prs" in input ? input.prs : [input.stack];
-    if (!refs || refs.length === 0) {
-        throw new PrShepherdValidationError("iterate.prs must contain at least one PR reference");
+async function resolveSameRepositoryRefs(refs, label) {
+    if (!Array.isArray(refs) || refs.length === 0) {
+        throw new PrShepherdValidationError(`${label} must contain at least one PR reference`);
     }
     const parsedRefs = refs.map((ref) => {
         const parsed = parsePrReference(ref);
@@ -197,16 +223,7 @@ async function resolveAggregateIterateInput(input) {
         if (!numbers.includes(prNumber))
             numbers.push(prNumber);
     }
-    const { pr: _pr, prs: _prs, stack: _stack, ...options } = input;
-    return "prs" in input
-        ? { ...options, prNumbers: numbers, targetRepository: repository }
-        : { ...options, stackPrNumber: numbers[0], targetRepository: repository };
-}
-function validateIterateSelectors(input) {
-    const selectorCount = ["pr", "prs", "stack"].filter((key) => key in input).length;
-    if (selectorCount > 1) {
-        throw new PrShepherdValidationError("iterate pr, prs, and stack selectors are mutually exclusive");
-    }
+    return { numbers, repository: repository };
 }
 function validateApplyInput(input) {
     if (!input || !Array.isArray(input.operations) || input.operations.length === 0) {
@@ -254,6 +271,21 @@ function validateOperation(operation) {
                     throw new PrShepherdValidationError(validation.error);
             }
             return;
+        case "check_blocker":
+            if (typeof operation.check !== "string" || operation.check === "") {
+                throw new PrShepherdValidationError("check_blocker.check must be the exact check name");
+            }
+            if (operation.clear !== undefined && typeof operation.clear !== "boolean") {
+                throw new PrShepherdValidationError("check_blocker.clear must be a boolean");
+            }
+            if (operation.clear === true && operation.blockedBy !== undefined) {
+                throw new PrShepherdValidationError("check_blocker takes either blockedBy or clear, not both");
+            }
+            if (operation.clear !== true &&
+                (typeof operation.blockedBy !== "string" || !parseBlockedByRef(operation.blockedBy))) {
+                throw new PrShepherdValidationError("check_blocker.blockedBy must be a PR/issue URL, owner/repo#N, or issue:owner/repo#N");
+            }
+            return;
         case "acknowledge_queue_removal":
             if (typeof operation.requireSha !== "string" ||
                 !/^[0-9a-f]{40}$/.test(operation.requireSha)) {
@@ -317,21 +349,9 @@ function validateMarkFilesViewed(operation) {
         }
     }
 }
-function validateSuggestionPatchInput(input) {
-    if (!input || typeof input.threadId !== "string" || input.threadId.trim() === "") {
-        throw new PrShepherdValidationError("buildSuggestionPatch.threadId is required");
-    }
-    if (typeof input.message !== "string" || input.message.trim() === "") {
-        throw new PrShepherdValidationError("buildSuggestionPatch.message is required and must be non-empty");
-    }
-    if (input.description !== undefined && typeof input.description !== "string") {
-        throw new PrShepherdValidationError("buildSuggestionPatch.description must be a string");
-    }
-    validatePrReference(input.pr);
-}
-function validateSuggestionPatchesInput(input) {
+function validateSuggestInput(input) {
     if (!input || !Array.isArray(input.suggestions) || input.suggestions.length === 0) {
-        throw new PrShepherdValidationError("buildSuggestionPatches.suggestions must be a non-empty array");
+        throw new PrShepherdValidationError("suggest.suggestions must be a non-empty array");
     }
     const seen = new Set();
     for (const suggestion of input.suggestions) {

package/bin/checks/classify.d.mts

@@ -34,7 +34,7 @@ export interface CiVerdict {
     anyFailing: boolean;
     /** Names of checks that were filtered out (triggered by non-PR events). */
     filteredNames: string[];
-    /** Names of checks suppressed by the user's ignoreChecks config. */
+    /** Names of checks suppressed by the user's checks.ignore config. */
     ignoredNames: string[];
     /** Names of CANCELLED checks covered by another run of the same workflow and event. */
     supersededNames: string[];

package/bin/checks/classify.mjs

@@ -24,11 +24,11 @@ import picomatch from "picomatch";
 export function classifyChecks(checks, opts = {}) {
     const config = loadConfig();
     const relevantEvents = new Set([
-        ...config.checks.ciTriggerEvents,
+        ...config.checks["ci-trigger-events"],
         ...(opts.additionalRelevantEvents ?? []),
     ]);
-    const isIgnored = buildMatcher(config.ignoreChecks ?? []);
-    const isProtected = buildMatcher(config.actions.neverCancelRuns ?? []);
+    const isIgnored = buildMatcher(config.checks.ignore ?? []);
+    const isProtected = buildMatcher(config.checks["never-ignore"] ?? []);
     const protectedRunIds = buildProtectedRunIds(checks, isProtected);
     const supersededIndices = buildSupersededIndices(checks, opts.requiredContexts);
     return checks.map((c, index) => {
@@ -69,7 +69,7 @@ function checkMatchesProtection(check, isProtected) {
 }
 function classify(check, relevantEvents) {
     // Filter: runs from non-PR events don't count toward PR readiness.
-    // event === null means a commit StatusContext — these are always relevant regardless of ciTriggerEvents.
+    // event === null means a commit StatusContext — these are always relevant regardless of checks.ci-trigger-events.
     if (check.event !== null && !relevantEvents.has(check.event)) {
         return { ...check, category: "filtered" };
     }

package/bin/checks/log-excerpt.mjs

@@ -175,7 +175,7 @@ function truncateTail(text, keep) {
     return from === -1 ? tail : truncateLogExcerpt(`${head}${text.slice(from)}`);
 }
 function compileIgnoreLogLinePatterns() {
-    return loadConfig().checks.ignoreLogLines.map((pattern) => new RegExp(pattern));
+    return loadConfig().checks["ignore-log-lines"].map((pattern) => new RegExp(pattern));
 }
 function isNoiseLine(line, patterns) {
     return patterns.some((re) => re.test(line));

package/bin/classify/standard/codecov-report.d.mts

@@ -1,4 +1,4 @@
 import type { ClassifyRule } from "../types.mts";
-/** Codecov's coverage report comment. Coverage gates still report through their status checks. */
+/** Codecov's coverage report and first-run welcome. Coverage gates still report through checks. */
 declare const rule: ClassifyRule;
 export default rule;

package/bin/classify/standard/codecov-report.mjs

@@ -1,9 +1,14 @@
 import { isBotItem } from "./author.mjs";
-/** Codecov's coverage report comment. Coverage gates still report through their status checks. */
+const WELCOME = /^## Welcome to \[Codecov\]\(https:\/\/codecov\.io[^\s)]*\) :tada:\n\nOnce you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests\.\n\nThanks for integrating Codecov - We've got you covered :open_umbrella:$/;
+/** Codecov's coverage report and first-run welcome. Coverage gates still report through checks. */
 const rule = (item) => {
     if (!isBotItem(item, ["codecov"], ["pr-comment"]))
         return null;
-    if (!/^#{1,6}\s*\[?Codecov\b/i.test(item.body.trimStart()))
+    const body = item.body.trim();
+    if (WELCOME.test(body)) {
+        return { autoResolve: true, suppress: true, reason: "Codecov welcome notice" };
+    }
+    if (!/^#{1,6}\s*\[?Codecov\b/i.test(body))
         return null;
     return { autoResolve: true, suppress: true, reason: "Codecov coverage report" };
 };

package/bin/classify/standard/coderabbit-notices.d.mts

@@ -1,8 +1,9 @@
 import type { ClassifyRule } from "../types.mts";
 /**
- * CodeRabbit progress, rate-limit, review-skipped and draft notices, plus its "Action not
- * completed" command replies. If the comment is later edited into a PR walkthrough, its new
- * body no longer matches and Shepherd surfaces the edited minimized comment to the agent.
+ * CodeRabbit progress, rate-limit, review-skipped and draft notices, its status-only command
+ * replies, and its zero-findings, skipped-autofix, and failed-edit status comments. If the
+ * comment is later edited into a PR walkthrough, its new body no longer matches and Shepherd
+ * surfaces the edited minimized comment to the agent.
  */
 declare const rule: ClassifyRule;
 export default rule;

package/bin/classify/standard/coderabbit-notices.mjs

@@ -1,54 +1,33 @@
 import { isBotItem } from "./author.mjs";
 const NOTICE_ENVELOPE = /^<!-- This is an auto-generated comment: (rate limited|skip review|review in progress) by coderabbit.ai -->\n([\s\S]*?)\n<!-- end of auto-generated comment: \1 by coderabbit.ai -->$/;
-const COMMAND_REPLY = /^<!-- This is an auto-generated reply by CodeRabbit -->\n<!-- CodeRabbit review command invocation: v2:[a-f0-9]+ -->\n<details>\n<summary>⚠️ Action not completed<\/summary>\n\n(?:Review rate limited\.|Review skipped: \d+ files exceed the limit of \d+\.)\n\n(?:> Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits\. This command is applicable only when automatic reviews are paused\.|---\n\nYour included review limit is currently reached under our \[Fair Usage Limits Policy\]\(https:\/\/docs.coderabbit.ai\/management\/plans#fair-usage-limits-policy\)\. This review may still proceed through usage-based billing if eligible\. Your next included review will be available in \d+ minutes?\.)\n\n<\/details>$/;
-const FINISHING_TOUCH_BLOCK = `<!-- finishing_touch_checkbox_start -->
-
-<details>
-<summary><strong>✨ Finishing Touches</strong></summary>
-<dl>
-<dd>
-
-<details open>
-<summary><strong>📝 Generate docstrings</strong></summary>
-<dl>
-<dd>
-
-- [ ] <!-- {"checkboxId":"3e1879ae-f29b-4d0d-8e06-d12b7ba33d98"} --> Commit to this branch
-- [ ] <!-- {"checkboxId":"7962f53c-55bc-4827-bfbf-6a18da830691"} --> Create a new PR
-
-</dd>
-</dl>
-</details>
-<details open>
-<summary><strong>🧪 Generate unit tests (beta)</strong></summary>
-<dl>
-<dd>
-
-- [ ] <!-- {"checkboxId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "radioGroupId": "utg-output-choice-group-unknown_comment_id"} --> Commit to this branch
-- [ ] <!-- {"checkboxId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "radioGroupId": "utg-output-choice-group-unknown_comment_id"} --> Create a new PR
-
-</dd>
-</dl>
-</details>
-
-</dd>
-</dl>
-</details>
-
-<!-- finishing_touch_checkbox_end -->`;
-const AUTOPILOT_BLOCK = /\n<!-- autopilot:start -->\n- \[ \] <!-- \{"checkboxId":"2708ad07-9f24-4260-9c11-7dc76a49f2e3"\} --> <strong title="Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts">Autofix<\/strong> · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts\n<!-- autopilot:end -->$/;
+/**
+ * Command replies that only report a known status, optionally followed by one of CodeRabbit's
+ * fixed explanations. The invocation id varies between releases; any other text stays visible.
+ */
+const COMMAND_REPLY = /^<!-- This is an auto-generated reply by CodeRabbit -->\n<!-- CodeRabbit review command invocation: [^\n]* -->\n<details>\n<summary>(?:⚠️ Action not completed|✅ Action performed)<\/summary>\n\n(?:Review rate limited\.|Review skipped: \d+ files exceed the limit of \d+\.|(?:Full review|Review) finished\.|Pull request base or head changed\.|Pull request is closed\.)\n\n(?:(?:> Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits\. This command is applicable only when automatic reviews are paused\.|---\n\nYour included review limit is currently reached under our \[Fair Usage Limits Policy\]\(https:\/\/docs\.coderabbit\.ai\/[^\s)]*\)\. This review may still proceed through usage-based billing if eligible\. Your next included review will be available in \d+ minutes?\.)\n\n)?<\/details>$/;
+/** Standalone status comments: zero-findings completion, skipped autofix, and a failed edit. */
+const STATUS_COMMENTS = [
+    /^<!-- coderabbit-review-completion-marker -->\n\*\*Actionable comments posted: 0\*\*$/,
+    /^<!-- This is an auto-generated comment: autofix status by CodeRabbit -->\n> \[!NOTE\]\n> Autofix is a beta feature\.[^\n]*\n\nAutofix skipped\. No unresolved CodeRabbit review comments with fix instructions found\.\n<!-- autofix-run-id: [^\n]* -->$/,
+    /^> \[!CAUTION\]\n> Failed to replace \(edit\) comment\. This is likely due to insufficient permissions or the comment being deleted\.\n> \n> <details>\n> <summary>Error details<\/summary>\n> \n> ```\n> [^`\n]*\n> ```\n> \n> <\/details>$/,
+];
+/** One "Finishing Touches" option group: a bold title and only checkbox lines with plain labels. */
+const FINISHING_TOUCH_GROUP = "<details open>\\n<summary><strong>[^<\\n]+<\\/strong><\\/summary>\\n<dl>\\n<dd>\\n\\n(?:- \\[ \\] <!-- \\{[^\\n]*\\} --> [^<\\n]+\\n)+\\n<\\/dd>\\n<\\/dl>\\n<\\/details>\\n";
+/** The finishing-touch checkbox UI, with any checkbox ids and any number of option groups. */
+const FINISHING_TOUCH_BLOCK = new RegExp(`\\n\\n<!-- finishing_touch_checkbox_start -->\\n\\n<details>\\n<summary><strong>✨ Finishing Touches<\\/strong><\\/summary>\\n<dl>\\n<dd>\\n\\n(?:${FINISHING_TOUCH_GROUP})+\\n<\\/dd>\\n<\\/dl>\\n<\\/details>\\n\\n<!-- finishing_touch_checkbox_end -->$`);
+/** The Autofix/Autopilot checkbox, with any checkbox id, one-word label, and description. */
+const AUTOPILOT_BLOCK = /\n<!-- autopilot:start -->\n- \[ \] <!-- \{[^\n]*\} --> <strong title="[^"\n]*">\w+<\/strong> · [^<\n]+\n<!-- autopilot:end -->$/;
 /** Strips CodeRabbit's footer and header blocks so only the notice envelope remains. */
 function stripChrome(body) {
-    const withoutFooter = body
+    return body
         .trim()
         .replace(/\n<!-- tips_start -->[\s\S]*?<!-- tips_end -->$/, "")
         .trim()
         .replace(AUTOPILOT_BLOCK, "")
-        .trim();
-    const withoutFinishingTouch = withoutFooter.endsWith(`\n\n${FINISHING_TOUCH_BLOCK}`)
-        ? withoutFooter.slice(0, -FINISHING_TOUCH_BLOCK.length).trim()
-        : withoutFooter;
-    return withoutFinishingTouch
+        .trim()
+        .replace(FINISHING_TOUCH_BLOCK, "")
+        .trim()
+        .replace(/^<!-- coderabbit-ai-generated:\S* -->\s*/, "")
         .replace(/^<!-- This is an auto-generated comment: summarize by coderabbit.ai -->\s*/, "")
         .replace(/^<!-- review_stack_entry_start -->[\s\S]*?<!-- review_stack_entry_end -->\s*/, "");
 }
@@ -57,21 +36,24 @@ function isQuotedNotice(quoted) {
     if (!onlyQuotedLines)
         return false;
     return (quoted.includes("> ## Review limit reached\n") ||
+        quoted.includes("> ## Rate limit exceeded\n") ||
         quoted.includes("> ## Draft PR not reviewed\n") ||
         quoted.includes("> ## Review skipped\n") ||
         quoted.includes("> Currently processing new changes in this PR. This may take a few minutes, please wait..."));
 }
 /**
- * CodeRabbit progress, rate-limit, review-skipped and draft notices, plus its "Action not
- * completed" command replies. If the comment is later edited into a PR walkthrough, its new
- * body no longer matches and Shepherd surfaces the edited minimized comment to the agent.
+ * CodeRabbit progress, rate-limit, review-skipped and draft notices, its status-only command
+ * replies, and its zero-findings, skipped-autofix, and failed-edit status comments. If the
+ * comment is later edited into a PR walkthrough, its new body no longer matches and Shepherd
+ * surfaces the edited minimized comment to the agent.
  */
 const rule = (item) => {
     if (!isBotItem(item, ["coderabbitai"], ["pr-comment"]))
         return null;
     const body = stripChrome(item.body);
     const quoted = body.match(NOTICE_ENVELOPE)?.[2]?.trim();
-    if (!(quoted && isQuotedNotice(quoted)) && !COMMAND_REPLY.test(body))
+    const isStatus = COMMAND_REPLY.test(body) || STATUS_COMMENTS.some((notice) => notice.test(body));
+    if (!(quoted && isQuotedNotice(quoted)) && !isStatus)
         return null;
     return {
         autoResolve: true,