pr-shepherd 0.60.1 → 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.1",
+  "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/cli/arg-flags.mjs

@@ -8,13 +8,11 @@ export const FLAGS_WITH_VALUES = new Set([
     "--ready-delay",
     "--stall-timeout",
     "--instructions",
-    "--poll-mode",
     "--require-sha",
     "--message",
     "--description",
     "--body-file",
     "--file",
-    "--stack",
     "--thread-id",
     "--resolve-thread-ids",
     "--reply-thread-ids",
@@ -35,7 +33,6 @@ export const FLAGS_WITH_VALUES = new Set([
 // numeric value to be misidentified as the PR number.
 export const BOOLEAN_FLAGS = new Set([
     "--no-auto-mark-ready",
-    "--no-auto-cancel-actionable",
     "--quiet-status",
     "--no-quiet-status",
     "--until-terminal",

package/bin/cli/clean-handler.d.mts

@@ -1 +1 @@
-export declare function handleClean(args: string[], command?: "admin clean" | "clean"): Promise<void>;
+export declare function handleClean(args: string[]): Promise<void>;

package/bin/cli/clean-handler.mjs

@@ -2,10 +2,10 @@ import { runClean } from "../commands/clean.mjs";
 import { EXIT } from "../exit-codes.mjs";
 import { USAGE } from "./help.mjs";
 import { formatCleanResult } from "./formatters.mjs";
-import { rejectInvalidPollModeFlag, runInPollModeScope } from "./event-state-scope.mjs";
 const CLEAN_VARIANTS = new Set(["pr", "branch", "current", "repo", "all"]);
-export async function handleClean(args, command = "admin clean") {
-    const usage = command === "admin clean" ? USAGE["admin clean"] : USAGE.clean;
+export async function handleClean(args) {
+    const command = "admin clean";
+    const usage = USAGE["admin clean"];
     const variant = args[0];
     if (!variant || !CLEAN_VARIANTS.has(variant)) {
         process.stderr.write(`${usage}\n`);
@@ -18,8 +18,6 @@ export async function handleClean(args, command = "admin clean") {
             continue;
         if (a === "--dry-run" || a === "--format" || a.startsWith("--format="))
             continue;
-        if (a === "--poll-mode" || a.startsWith("--poll-mode="))
-            continue;
         process.stderr.write(`pr-shepherd: ${command}: unknown flag: "${a}"\n`);
         process.exitCode = EXIT.USAGE;
         return;
@@ -38,21 +36,14 @@ export async function handleClean(args, command = "admin clean") {
         process.exitCode = EXIT.USAGE;
         return;
     }
-    if (rejectInvalidPollModeFlag(rest, command))
-        return;
     const jsonOut = formatValue === "json";
     const dryRun = rest.includes("--dry-run");
-    // Skip values consumed by --format <value> / --poll-mode <value> so they aren't positionals.
+    // Skip values consumed by --format <value> so they aren't positionals.
     const flagConsumedIndices = new Set();
     if (fmtIdx !== -1 && fmtIdx + 1 < rest.length && !rest[fmtIdx + 1].startsWith("--")) {
         flagConsumedIndices.add(fmtIdx);
         flagConsumedIndices.add(fmtIdx + 1);
     }
-    const pollModeIdx = rest.indexOf("--poll-mode");
-    if (pollModeIdx !== -1) {
-        flagConsumedIndices.add(pollModeIdx);
-        flagConsumedIndices.add(pollModeIdx + 1);
-    }
     const positionals = rest.filter((a, i) => !flagConsumedIndices.has(i) && !a.startsWith("--"));
     if (positionals.length > 1) {
         process.stderr.write(`pr-shepherd: ${command}: too many positional arguments (expected at most 1, got ${positionals.length})\n`);
@@ -60,8 +51,7 @@ export async function handleClean(args, command = "admin clean") {
         return;
     }
     const value = positionals[0];
-    // Event mode keeps its state under the durable state base; clean must target that same scope.
-    const result = await runInPollModeScope(rest, () => runClean({ variant: variant, value, dryRun }));
+    const result = await runClean({ variant: variant, value, dryRun });
     if (!result.ok) {
         process.stderr.write(`pr-shepherd: ${command}: ${result.error}\n`);
         process.exitCode = EXIT.SOFTWARE;

package/bin/cli/default-poll.d.mts

@@ -1,2 +1,4 @@
+export declare const DEFAULT_POLL_FLAGS_WITH_VALUES: Set<string>;
+export declare const DEFAULT_POLL_BOOLEAN_FLAGS: Set<string>;
 export declare function isDefaultPollInvocation(subcommand: string | undefined): boolean;
 export declare function validateDefaultPollArgs(args: string[]): boolean;

package/bin/cli/default-poll.mjs

@@ -2,22 +2,20 @@ import { EXIT } from "../exit-codes.mjs";
 import { parsePrNumber } from "./args.mjs";
 import { validateDefaultArgs } from "./validate-default-args.mjs";
 import { USAGE } from "./help.mjs";
-const DEFAULT_POLL_FLAGS_WITH_VALUES = new Set([
+import { isRemovedFlag, rejectRemovedFlags } from "./removed-flags.mjs";
+export const DEFAULT_POLL_FLAGS_WITH_VALUES = new Set([
     "--transport",
     "--format",
     "--ready-delay",
     "--stall-timeout",
     "--instructions",
-    "--poll-mode",
     "--interval",
     "--timeout",
     "--debounce",
-    "--stack",
 ]);
-const DEFAULT_POLL_BOOLEAN_FLAGS = new Set([
+export const DEFAULT_POLL_BOOLEAN_FLAGS = new Set([
     "--verbose",
     "--no-auto-mark-ready",
-    "--no-auto-cancel-actionable",
     "--quiet-status",
     "--no-quiet-status",
     "--until-terminal",
@@ -29,11 +27,16 @@ export function isDefaultPollInvocation(subcommand) {
     return (subcommand === undefined || parsePrNumber(subcommand) !== null || isDefaultPollFlag(subcommand));
 }
 export function validateDefaultPollArgs(args) {
+    if (rejectRemovedFlags(args))
+        return false;
     return validateDefaultArgs(args, DEFAULT_POLL_FLAGS_WITH_VALUES, DEFAULT_POLL_BOOLEAN_FLAGS, writeDefaultUsageError);
 }
 function isDefaultPollFlag(arg) {
     const name = arg.split("=", 1)[0];
-    return DEFAULT_POLL_FLAGS_WITH_VALUES.has(name) || DEFAULT_POLL_BOOLEAN_FLAGS.has(arg);
+    // A removed flag routes here so its usage error names the replacement.
+    return (DEFAULT_POLL_FLAGS_WITH_VALUES.has(name) ||
+        DEFAULT_POLL_BOOLEAN_FLAGS.has(arg) ||
+        isRemovedFlag(arg));
 }
 function writeDefaultUsageError(arg) {
     process.stderr.write(`Unknown subcommand: ${arg}\n`);

package/bin/cli/formatters.d.mts

@@ -3,6 +3,5 @@ export { projectIterateLean, projectIterateVerbose } from "./iterate-lean.mts";
 export { formatCleanResult } from "./clean-formatter.mts";
 export { formatMarkFilesAsViewedResult } from "./mark-files-as-viewed-formatter.mts";
 export { formatMutateResult } from "./mutate-formatter.mts";
-import type { BuildSuggestionPatchesResult, CommitSuggestionResult } from "../types.mts";
-export declare function formatSuggestionPatchesResult(result: BuildSuggestionPatchesResult): string;
-export declare function formatCommitSuggestionResult(result: CommitSuggestionResult): string;
+import type { SuggestResult } from "../types.mts";
+export declare function formatSuggestionPatchesResult(result: SuggestResult): string;

package/bin/cli/formatters.mjs

@@ -12,32 +12,6 @@ export function formatSuggestionPatchesResult(result) {
     appendInstructions(lines, result.postActionInstructions);
     return lines.join("\n");
 }
-export function formatCommitSuggestionResult(result) {
-    const lines = [];
-    const range = result.startLine === result.endLine
-        ? `line ${result.startLine}`
-        : `lines ${result.startLine}–${result.endLine}`;
-    lines.push(`Suggestion from @${result.author} for PR #${result.pr} — thread ${result.threadId}:`);
-    lines.push(`  repo: ${result.repo}`);
-    lines.push(`  ${result.path} (${range})`);
-    if (result.patch) {
-        const fence = safeFence(result.patch);
-        lines.push("");
-        lines.push(`${fence}diff`);
-        lines.push(result.patch.trimEnd());
-        lines.push(fence);
-    }
-    lines.push("", "## Suggested commit message", "", result.commitMessage, "", result.commitBody);
-    if (result.postActionInstructions.length > 0) {
-        lines.push("");
-        lines.push("## Instructions");
-        lines.push("");
-        result.postActionInstructions.forEach((inst, i) => {
-            lines.push(`${i + 1}. ${inst}`);
-        });
-    }
-    return lines.join("\n");
-}
 function formatPatch(patch, heading) {
     const range = patch.startLine === patch.endLine
         ? `line ${patch.startLine}`

package/bin/cli/handlers.d.mts

@@ -1,4 +1,4 @@
-export declare function handleCommitSuggestion(args: string[], command?: "build-suggestion-patch" | "commit-suggestion"): Promise<void>;
-export declare function handleSuggestionPatches(args: string[]): Promise<void>;
+export declare function handleSuggest(args: string[]): Promise<void>;
+/** `iterate [PR...]`: one tick for one PR, or one aggregate tick for several. */
 export declare function handleIterate(args: string[]): Promise<void>;
-export declare function handleMarkFilesAsViewed(args: string[], command?: "apply files" | "mark-files-as-viewed"): Promise<void>;
+export declare function handleMarkFilesAsViewed(args: string[]): Promise<void>;