pr-shepherd 0.41.0 → 0.43.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.41.0",
+  "version": "0.43.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -9,14 +9,14 @@ An agent finishing a PR should think about code, not reconstruct GitHub state or
 ## What it does
 
 1. **Gather all context for a PR** in one invocation: review threads, comments, replies, summaries, CI, mergeability, merge requirements, first-look / outdated / edited items, and author provenance.
-2. **Provide deterministic actions for the agent**: exactly one of `WAIT`, `MARK_READY`, `FIX_CODE`, `CANCEL`, or `ESCALATE`, plus numbered `## Instructions` and explicit `apply` / `build_suggestion_patch` mutations. The agent still decides whether a comment or CI failure needs a code change. Shepherd does not classify signal vs noise and does not mutate git.
+2. **Provide deterministic actions for the agent**: exactly one of `WAIT`, `MARK_READY`, `FIX_CODE`, `MERGE`, `CANCEL`, or `ESCALATE`, plus numbered `## Instructions` and explicit commands. The agent still decides whether a comment or CI failure needs a code change. Shepherd does not classify signal vs noise and does not mutate git.
 
 Highlights:
 
 - Batched GraphQL reads and writes (plus REST where GraphQL cannot) so one poll replaces a tool-call fan-out. MCP `iterate` is one tick and the client owns recurrence; `--debounce` is a poll-dispatcher settle window, not an MCP tool.
 - CI summaries include failed checks, and the failed job/step plus a log excerpt when triage can fetch them. Job and log details are omitted for `STARTUP_FAILURE` and `CANCELLED`; agents may still inspect logs.
 - Handles GitHub comment types (comments, threads, replies) and their states, including first-look, outdated, resolved, minimized, and edited.
-- `apply` batches resolve / reply / minimize / dismiss. `build_suggestion_patch` emits a unified diff in output, not a patch file, and does not mutate git.
+- `apply` batches resolve / reply / minimize / dismiss. `build_suggestion_patches` validates and returns ordered diffs without mutating git.
 - `BEHIND` is mergeability information, not a rebase or a guarantee that the next push is at the default-branch tip. The agent can update the branch before pushing.
 
 Full reference: [docs/README.md](docs/README.md). Feature matrix: [docs/features.md](docs/features.md).
@@ -25,13 +25,14 @@ Full reference: [docs/README.md](docs/README.md). Feature matrix: [docs/features
 
 `pr-shepherd` moves deterministic PR orchestration into a local MCP server, with a CLI for shells and CI. Both interfaces fetch the same GitHub state, emit raw-enough context, and return a numbered plan for the calling agent to follow.
 
-The MCP server exposes three tools: `iterate`, `apply`, and `build_suggestion_patch`. `apply` accepts ordered review mutations, file-view mutations, and journal entries. Direct MCP calls require a repository-qualified `pr`: a GitHub PR URL or `owner/repo#N`, matching the repository where the server started. The CLI and programmatic API also retain bare-number and current-branch PR discovery. The shipped skills are thin dispatchers for those tools.
+The MCP server exposes canonical `iterate`, `apply`, and `build_suggestion_patches` tools. `apply` accepts ordered review mutations, file-view mutations, and journal entries; the deprecated singular suggestion tool remains temporarily as an adapter. Direct MCP calls require a repository-qualified `pr`: a GitHub PR URL or `owner/repo#N`, matching the repository where the server started. The CLI and programmatic API also retain bare-number and current-branch PR discovery. The shipped skills are thin dispatchers for those tools.
 
 Each tick returns exactly one action:
 
 - `WAIT` — no immediate action; continue with the next poll.
 - `MARK_READY` — the CLI converted an eligible draft PR to ready; continue polling.
 - `FIX_CODE` — agent work is required; complete it, then continue polling.
+- `MERGE` — run the emitted auto-merge or merge-queue command, then continue polling.
 - `CANCEL` — stop polling because the PR merged, closed, or completed its ready-delay.
 - `ESCALATE` — stop polling until a human provides direction.
 
@@ -76,7 +77,7 @@ Conversations Resolved: No [Not Required]
 9. `[FIX_CODE]` is non-terminal. After completing these steps, iterate again with the same options to continue.
 ```
 
-See [docs/actions.md](docs/actions.md) for the complete output contract. Iterate/poll PR outcomes use exit codes `0` and `10`–`14`; command and GitHub failures use `sysexits.h` codes — [docs/exit-codes.md](docs/exit-codes.md).
+See [docs/actions.md](docs/actions.md) for the complete output contract. Iterate/poll PR outcomes use exit codes `0` and `10`–`15`; command and GitHub failures use `sysexits.h` codes — [docs/exit-codes.md](docs/exit-codes.md).
 
 ## Workflow Assumptions
 
@@ -88,7 +89,7 @@ This system is opinionated and works best with PRs that use required status chec
 - Every review thread/comment/review summary is surfaced at least once, even if already outdated, resolved, or minimized; edited items re-surface through seen markers.
 - Draft PRs can be marked ready automatically when clean; disable with `actions.autoMarkReady: false` or `--no-auto-mark-ready`.
 - The CLI never performs git mutations. It emits instructions; the caller commits, rebases, pushes, and handles repository hooks.
-- `build_suggestion_patch` turns one GitHub suggestion thread into a patch and commit metadata, but never edits the working tree or git history.
+- `build_suggestion_patches` turns one or more ordered GitHub suggestion threads into checked patches and commit metadata, but never edits the working tree or git history. Local HEAD may be ahead when the live PR head is its ancestor.
 
 ## Usage
 
@@ -115,7 +116,7 @@ Grok:
 /pr-shepherd 42
 ```
 
-MCP clients call `iterate` once per tick, then use `apply` for review/file/journal mutations and `build_suggestion_patch` for an anchored suggestion. Every direct MCP call supplies the same repository-qualified PR reference. `iterate` returns the same structured action data as the CLI, including its review mutation arguments. The client owns recurrence, so this works consistently in Codex, Claude Code, Grok, and any other stdio MCP client.
+MCP clients call `iterate` once per tick, then use `apply` for review/file/journal mutations and `build_suggestion_patches` for anchored suggestions. Every direct MCP call supplies the same repository-qualified PR reference. `iterate` returns the same structured action data as the CLI, including its review mutation arguments. The client owns recurrence, so this works consistently in Codex, Claude Code, Grok, and any other stdio MCP client.
 
 The CLI remains useful for shell workflows. Its canonical polling form is:
 
@@ -126,12 +127,13 @@ pr-shepherd 42 --quiet-status          # print only changed WAIT status snapshot
 pr-shepherd 42 --until-terminal        # continue through WAIT/MARK_READY until work or terminal state
 pr-shepherd 42 --debounce 5m           # wait 5m after first FIX_CODE, then return one batched tick
 pr-shepherd 42 --ready-delay 15m
+pr-shepherd 42 --merge                  # enable auto-merge or enter an enabled/required merge queue when ready
 pr-shepherd iterate 42                 # single tick
 ```
 
 ### Apply Review, File, And Journal Changes
 
-Use `apply` with ordered operations to reply/resolve/minimize/dismiss review items, mark changed files viewed, or append an idempotent Shepherd Journal item. Use `build_suggestion_patch` to turn one review suggestion into a validated patch and commit metadata; it never changes the worktree or git history.
+Use `apply` with ordered operations to reply/resolve/minimize/dismiss review items, mark changed files viewed, or append an idempotent Shepherd Journal item. Use `build_suggestion_patches` to turn ordered review suggestions into checked patches and commit metadata; it never changes the worktree or git history.
 
 ### Extract Shepherd Journal Entries
 
@@ -236,7 +238,10 @@ checks:
   ciTriggerEvents:
     - pull_request
     - pull_request_target
-    - merge_group
+merge:
+  commandArgs:
+    - --squash
+    - --delete-branch
 actions:
   autoMinimizeSuppressed: true
   autoMarkReady: false
@@ -276,7 +281,7 @@ Ready-to-use examples for common patterns are in [`examples/classification/`](ex
 
 ## CLI aliases
 
-`poll`, `resolve`, `commit-suggestion`, `mark-files-as-viewed`, `journal`, `clean`, and `log-file` are CLI aliases. Prefer default polling/`iterate` in a shell and the MCP `iterate`, `apply`, and `build_suggestion_patch` tools in an agent client.
+`poll`, `resolve`, `build-suggestion-patch`, `commit-suggestion`, `mark-files-as-viewed`, `journal`, `clean`, and `log-file` are CLI aliases or deprecated adapters. Prefer default polling/`iterate` in a shell and the MCP `iterate`, `apply`, and `build_suggestion_patches` tools in an agent client.
 
 ## Requirements
 

package/bin/api.d.mts

@@ -1,7 +1,7 @@
 import { type JournalResult } from "./commands/journal/index.mts";
 import { type MarkFilesAsViewedResult } from "./commands/mark-files-as-viewed.mts";
 import type { ResolveResult } from "./comments/resolve.mts";
-import type { CommitSuggestionResult, IterateCommandOptions, IterateResult } from "./types.mts";
+import type { BuildSuggestionPatchesResult, CommitSuggestionResult, IterateCommandOptions, IterateResult } from "./types.mts";
 export interface CreatePrShepherdOptions {
     /** Working directory used for git, config, and classification-rule lookups. */
     cwd?: string;
@@ -58,9 +58,20 @@ export interface BuildSuggestionPatchInput {
     message: string;
     description?: string;
 }
+export interface SuggestionPatchInput {
+    threadId: string;
+    message: string;
+    description?: string;
+}
+export interface BuildSuggestionPatchesInput {
+    pr?: PrReference;
+    suggestions: SuggestionPatchInput[];
+}
 export interface PrShepherd {
     iterate(input?: IterateInput): Promise<IterateResult>;
     apply(input: ApplyInput): Promise<ApplyResult>;
+    buildSuggestionPatches(input: BuildSuggestionPatchesInput): Promise<BuildSuggestionPatchesResult>;
+    /** Compatibility adapter; prefer buildSuggestionPatches. */
     buildSuggestionPatch(input: BuildSuggestionPatchInput): Promise<CommitSuggestionResult>;
 }
 /** Raised before any API mutation when an input cannot be validated. */

package/bin/api.mjs

@@ -1,6 +1,7 @@
 /* eslint-disable max-lines */
 import { resolve } from "node:path";
 import { runCommitSuggestion } from "./commands/commit-suggestion.mjs";
+import { runSuggestionPatches } from "./commands/suggestion-patches.mjs";
 import { runIterate } from "./commands/iterate/index.mjs";
 import { runJournal } from "./commands/journal/index.mjs";
 import { validateJournalItem } from "./commands/journal/transform.mjs";
@@ -101,6 +102,14 @@ export function createPrShepherd(options = {}) {
                 return runCommitSuggestion({ ...options, prNumber, format: "json" });
             });
         },
+        buildSuggestionPatches(input) {
+            validateSuggestionPatchesInput(input);
+            const { pr: _pr, ...options } = input;
+            return runWithExecutionCwd(cwd, async () => {
+                const prNumber = await resolvePrReference(input.pr);
+                return runSuggestionPatches({ ...options, prNumber, format: "json" });
+            });
+        },
     });
 }
 function validateApplyInput(input) {
@@ -184,7 +193,7 @@ function validateMarkFilesViewed(operation) {
     }
 }
 function validateSuggestionPatchInput(input) {
-    if (!input || typeof input.threadId !== "string" || input.threadId === "") {
+    if (!input || typeof input.threadId !== "string" || input.threadId.trim() === "") {
         throw new PrShepherdValidationError("buildSuggestionPatch.threadId is required");
     }
     if (typeof input.message !== "string" || input.message.trim() === "") {
@@ -195,6 +204,30 @@ function validateSuggestionPatchInput(input) {
     }
     validatePrReference(input.pr);
 }
+function validateSuggestionPatchesInput(input) {
+    if (!input || !Array.isArray(input.suggestions) || input.suggestions.length === 0) {
+        throw new PrShepherdValidationError("buildSuggestionPatches.suggestions must be a non-empty array");
+    }
+    const seen = new Set();
+    for (const suggestion of input.suggestions) {
+        if (!suggestion ||
+            typeof suggestion.threadId !== "string" ||
+            suggestion.threadId.trim() === "") {
+            throw new PrShepherdValidationError("each suggestion.threadId is required");
+        }
+        if (typeof suggestion.message !== "string" || suggestion.message.trim() === "") {
+            throw new PrShepherdValidationError("each suggestion.message must be non-empty");
+        }
+        if (suggestion.description !== undefined && typeof suggestion.description !== "string") {
+            throw new PrShepherdValidationError("each suggestion.description must be a string");
+        }
+        if (seen.has(suggestion.threadId)) {
+            throw new PrShepherdValidationError(`duplicate suggestion thread ID: ${suggestion.threadId}`);
+        }
+        seen.add(suggestion.threadId);
+    }
+    validatePrReference(input.pr);
+}
 function validatePrReference(pr) {
     const parsed = parsePrReference(pr);
     if (parsed !== null)

package/bin/checks/classify.d.mts

@@ -20,7 +20,9 @@ import type { CheckRun, ClassifiedCheck } from "../types.mts";
  * @param checks Raw check runs from the batch query.
  * @returns Classified checks. "filtered" items were excluded from the tally.
  */
-export declare function classifyChecks(checks: CheckRun[]): ClassifiedCheck[];
+export declare function classifyChecks(checks: CheckRun[], opts?: {
+    additionalRelevantEvents?: string[];
+}): ClassifiedCheck[];
 export interface CiVerdict {
     /** True when all relevant (non-filtered, non-skipped, non-ignored) checks passed. */
     allPassed: boolean;

package/bin/checks/classify.mjs

@@ -22,9 +22,12 @@ import picomatch from "picomatch";
  * @param checks Raw check runs from the batch query.
  * @returns Classified checks. "filtered" items were excluded from the tally.
  */
-export function classifyChecks(checks) {
+export function classifyChecks(checks, opts = {}) {
     const config = loadConfig();
-    const relevantEvents = new Set(config.checks.ciTriggerEvents);
+    const relevantEvents = new Set([
+        ...config.checks.ciTriggerEvents,
+        ...(opts.additionalRelevantEvents ?? []),
+    ]);
     const isIgnored = buildMatcher(config.ignoreChecks ?? []);
     const isProtected = buildMatcher(config.actions.neverCancelRuns ?? []);
     const protectedRunIds = buildProtectedRunIds(checks, isProtected);

package/bin/cli/args.mjs

@@ -30,6 +30,7 @@ const BOOLEAN_FLAGS = new Set([
     "--no-auto-cancel-actionable",
     "--quiet-status",
     "--until-terminal",
+    "--merge",
     "--dry-run",
     "--verbose",
 ]);

package/bin/cli/default-poll.mjs

@@ -16,6 +16,7 @@ const DEFAULT_POLL_BOOLEAN_FLAGS = new Set([
     "--no-auto-cancel-actionable",
     "--quiet-status",
     "--until-terminal",
+    "--merge",
 ]);
 export function isDefaultPollInvocation(subcommand) {
     if (subcommand === "--help" || subcommand === "-h")

package/bin/cli/fix-formatter.mjs

@@ -1,10 +1,11 @@
 import { renderResolveCommand } from "../commands/iterate/render.mjs";
-import { joinSections } from "../util/markdown.mjs";
+import { inlineCode, joinSections } from "../util/markdown.mjs";
 import { renderSuggestionBlock, renderLineRange } from "./suggestion-renderer.mjs";
 import { renderThreadBullet, renderReviewBullet, renderThreadResolutionStatusTag, renderAuthor, buildFirstLookBullets, renderThreadConversation, blockquote, } from "./list-formatters.mjs";
 import { numberInstructions } from "./iterate-instructions.mjs";
 import { renderCheckAnnotation, renderProtectedRun } from "./fix-formatter-extra.mjs";
 import { isFailingAgentCheck } from "../checks/conclusions.mjs";
+import { renderMergeCommand } from "../commands/iterate/merge.mjs";
 export function formatFixCodeResult(header, result) {
     const sections = [header];
     if (result.fix.threads.length > 0) {
@@ -50,7 +51,10 @@ export function formatFixCodeResult(header, result) {
                     ? `external \`${ch.detailsUrl}\``
                     : "(no runId)";
             const conclusionTag = ch.conclusion !== null ? ` [conclusion: ${ch.conclusion}]` : "";
-            const lines = [`- ${locator} — \`${workflowPrefix}${jobLabel}\`${conclusionTag}`];
+            const scopeTag = ch.scope
+                ? ` [scope: ${ch.scope}${ch.commitOid ? `, commit: ${ch.commitOid}` : ""}]`
+                : "";
+            const lines = [`- ${locator} — \`${workflowPrefix}${jobLabel}\`${conclusionTag}${scopeTag}`];
             if (ch.conclusion !== "CANCELLED") {
                 if (ch.failedStep)
                     lines.push(`  > ${ch.failedStep}`);
@@ -133,6 +137,12 @@ export function formatFixCodeResult(header, result) {
     if (result.fix.resolveCommand.hasMutations) {
         postFixLines.push(`- apply review: \`${renderResolveCommand(result.fix.resolveCommand)}\``);
     }
+    if (result.fix.requeue) {
+        postFixLines.push(`- requeue: ${inlineCode(renderMergeCommand(result.fix.requeue.command))}`);
+        if (result.fix.requeue.queueApiFallbackCommand) {
+            postFixLines.push(`- requeue API fallback: ${inlineCode(renderMergeCommand(result.fix.requeue.queueApiFallbackCommand))}`);
+        }
+    }
     sections.push(postFixLines.join("\n"));
     sections.push("## Instructions");
     sections.push(numberInstructions(result.fix.instructions));

package/bin/cli/formatters.d.mts

@@ -3,5 +3,6 @@ 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 { CommitSuggestionResult } from "../types.mts";
+import type { BuildSuggestionPatchesResult, CommitSuggestionResult } from "../types.mts";
+export declare function formatSuggestionPatchesResult(result: BuildSuggestionPatchesResult): string;
 export declare function formatCommitSuggestionResult(result: CommitSuggestionResult): string;

package/bin/cli/formatters.mjs

@@ -4,6 +4,14 @@ export { formatCleanResult } from "./clean-formatter.mjs";
 export { formatMarkFilesAsViewedResult } from "./mark-files-as-viewed-formatter.mjs";
 export { formatMutateResult } from "./mutate-formatter.mjs";
 import { safeFence } from "./fence.mjs";
+export function formatSuggestionPatchesResult(result) {
+    const lines = [`Suggestion patches for PR #${result.pr}:`, `  repo: ${result.repo}`];
+    result.patches.forEach((patch, index) => {
+        lines.push("", ...formatPatch(patch, `## Patch ${index + 1}`).split("\n"));
+    });
+    appendInstructions(lines, result.postActionInstructions);
+    return lines.join("\n");
+}
 export function formatCommitSuggestionResult(result) {
     const lines = [];
     const range = result.startLine === result.endLine
@@ -30,3 +38,28 @@ export function formatCommitSuggestionResult(result) {
     }
     return lines.join("\n");
 }
+function formatPatch(patch, heading) {
+    const range = patch.startLine === patch.endLine
+        ? `line ${patch.startLine}`
+        : `lines ${patch.startLine}–${patch.endLine}`;
+    const lines = [
+        heading,
+        "",
+        `Suggestion from @${patch.author} — thread ${patch.threadId}:`,
+        `  ${patch.path} (${range})`,
+    ];
+    if (patch.patch) {
+        const fence = safeFence(patch.patch);
+        lines.push("", `${fence}diff`, patch.patch.trimEnd(), fence);
+    }
+    lines.push("", "### Suggested commit message", "", patch.commitMessage, "", patch.commitBody);
+    return lines.join("\n");
+}
+function appendInstructions(lines, instructions) {
+    if (instructions.length === 0)
+        return;
+    lines.push("", "## Instructions", "");
+    instructions.forEach((instruction, index) => {
+        lines.push(`${index + 1}. ${instruction}`);
+    });
+}

package/bin/cli/handlers.d.mts

@@ -1,4 +1,5 @@
 export declare function handleClean(args: string[], command?: "admin clean" | "clean"): Promise<void>;
 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 handleIterate(args: string[]): Promise<void>;
 export declare function handleMarkFilesAsViewed(args: string[], command?: "apply files" | "mark-files-as-viewed"): Promise<void>;

package/bin/cli/handlers.mjs

@@ -1,4 +1,5 @@
 import { runCommitSuggestion } from "../commands/commit-suggestion.mjs";
+import { runSuggestionPatches } from "../commands/suggestion-patches.mjs";
 import { runMarkFilesAsViewed } from "../commands/mark-files-as-viewed.mjs";
 import { runIterate } from "../commands/iterate/index.mjs";
 import { runClean } from "../commands/clean.mjs";
@@ -6,7 +7,8 @@ import { loadConfig } from "../config/load.mjs";
 import { EXIT } from "../exit-codes.mjs";
 import { parseCommonArgs, getFlag } from "./args.mjs";
 import { USAGE } from "./help.mjs";
-import { formatCommitSuggestionResult, formatCleanResult, formatMarkFilesAsViewedResult, } from "./formatters.mjs";
+import { formatCommitSuggestionResult, formatSuggestionPatchesResult, formatCleanResult, formatMarkFilesAsViewedResult, } from "./formatters.mjs";
+import { parseSuggestionPatchGroups } from "./suggestion-patch-flags.mjs";
 import { parseIterateFlags } from "./iterate-flags.mjs";
 import { emitIterateResult } from "./iterate-emitter.mjs";
 import { parseMarkFilesAsViewedArgs } from "./mark-files-as-viewed-flags.mjs";
@@ -92,6 +94,23 @@ export async function handleCommitSuggestion(args, command = "build-suggestion-p
         ? `${JSON.stringify(result, null, 2)}\n`
         : `${formatCommitSuggestionResult(result)}\n`);
 }
+export async function handleSuggestionPatches(args) {
+    const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
+    const parsed = parseSuggestionPatchGroups(extra);
+    if (!parsed.ok) {
+        process.stderr.write(`${parsed.error}\n${USAGE["build-suggestion-patches"]}\n`);
+        process.exitCode = EXIT.USAGE;
+        return;
+    }
+    const result = await runSuggestionPatches({
+        ...globalOpts,
+        prNumber,
+        suggestions: parsed.suggestions,
+    });
+    process.stdout.write(globalOpts.format === "json"
+        ? `${JSON.stringify(result, null, 2)}\n`
+        : `${formatSuggestionPatchesResult(result)}\n`);
+}
 export async function handleIterate(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const cfg = loadConfig();
@@ -105,6 +124,7 @@ export async function handleIterate(args) {
         stallTimeoutSeconds: flags.stallTimeoutSeconds,
         noAutoMarkReady: flags.noAutoMarkReady,
         noAutoCancelActionable: flags.noAutoCancelActionable,
+        merge: flags.merge,
     });
     emitIterateResult(result, {
         format: globalOpts.format,

package/bin/cli/help-command-pages.d.mts

@@ -61,11 +61,27 @@ PR may be a number or GitHub pull request URL. An item must start with '- ' foll
 Use --file to read an item from a file, or --file - to read it from stdin. Exactly one item source
 is required. --dry-run previews the resulting body without writing it.
 --help, -h                      Print this help and exit before GitHub I/O.`;
-    readonly "build-suggestion-patch": `pr-shepherd build-suggestion-patch
+    readonly "build-suggestion-patches": `pr-shepherd build-suggestion-patches
 
-Build a patch and commit instructions for one GitHub review thread containing a suggestion block.
+Build an ordered list of patches and commit instructions from GitHub review suggestions.
 The command does not edit files or mutate git history.
 
+Usage:
+  pr-shepherd build-suggestion-patches [PR]
+    --thread-id ID --message MSG [--description DESC]
+    [--thread-id ID --message MSG [--description DESC] ...]
+    [--format text|json]
+
+Each --thread-id starts a suggestion group. Its following --message and optional --description
+belong to that suggestion. Groups are validated and returned in command-line order.
+
+The current branch must match the PR head ref. Local HEAD may equal or descend from the PR head;
+every generated patch is dry-run in order with git apply --check before output.
+--help, -h                      Print this help and exit before GitHub, git, config, or log I/O.`;
+    readonly "build-suggestion-patch": `pr-shepherd build-suggestion-patch
+
+Deprecated one-suggestion adapter. Use build-suggestion-patches.
+
 Usage:
   pr-shepherd build-suggestion-patch [PR] --thread-id ID --message MSG
                                       [--description DESC] [--format text|json]
@@ -76,7 +92,7 @@ Flags:
   --description <text>   Optional longer commit body.
   --format text|json     Output format. Default: text.
 
-The current branch must match the PR head ref and local HEAD must match the PR head SHA.
+The current branch must match the PR head ref. Local HEAD may equal or descend from the PR head.
 --help, -h                      Print this help and exit before GitHub, git, config, or log I/O.`;
     readonly admin: `pr-shepherd admin
 
@@ -149,7 +165,7 @@ Flags:
   --help, -h             Print this help and exit before GitHub, git, config, or log I/O.
 
 Preconditions:
-  The current branch must match the PR head ref, and local HEAD must match the PR head SHA.
+  The current branch must match the PR head ref. Local HEAD may equal or descend from the PR head.
 
 Exit codes:
   0   suggestion patch and instructions produced
@@ -176,8 +192,8 @@ Flags:
 
 PR may be a number or GitHub pull request URL. When omitted, the current branch PR is inferred.
 Exit code: 0 on success; nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
-    readonly iterate: "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
-    readonly poll: "pr-shepherd poll\n\nRun iterate repeatedly for WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR] [poll-flags] [iterate-flags]\n\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes an explicit still-running line to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, CANCEL, or ESCALATE.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+    readonly iterate: "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n  MERGE       Run the emitted merge/queue command, then continue monitoring.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+    readonly poll: "pr-shepherd poll\n\nRun iterate repeatedly for WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal or --merge, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR] [poll-flags] [iterate-flags]\n\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes an explicit still-running line to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
     readonly clean: `pr-shepherd clean
 
 Remove pr-shepherd state files from PR_SHEPHERD_STATE_DIR.

package/bin/cli/help-command-pages.mjs

@@ -64,11 +64,27 @@ PR may be a number or GitHub pull request URL. An item must start with '- ' foll
 Use --file to read an item from a file, or --file - to read it from stdin. Exactly one item source
 is required. --dry-run previews the resulting body without writing it.
 --help, -h                      Print this help and exit before GitHub I/O.`,
-    "build-suggestion-patch": `pr-shepherd build-suggestion-patch
+    "build-suggestion-patches": `pr-shepherd build-suggestion-patches
 
-Build a patch and commit instructions for one GitHub review thread containing a suggestion block.
+Build an ordered list of patches and commit instructions from GitHub review suggestions.
 The command does not edit files or mutate git history.
 
+Usage:
+  pr-shepherd build-suggestion-patches [PR]
+    --thread-id ID --message MSG [--description DESC]
+    [--thread-id ID --message MSG [--description DESC] ...]
+    [--format text|json]
+
+Each --thread-id starts a suggestion group. Its following --message and optional --description
+belong to that suggestion. Groups are validated and returned in command-line order.
+
+The current branch must match the PR head ref. Local HEAD may equal or descend from the PR head;
+every generated patch is dry-run in order with git apply --check before output.
+--help, -h                      Print this help and exit before GitHub, git, config, or log I/O.`,
+    "build-suggestion-patch": `pr-shepherd build-suggestion-patch
+
+Deprecated one-suggestion adapter. Use build-suggestion-patches.
+
 Usage:
   pr-shepherd build-suggestion-patch [PR] --thread-id ID --message MSG
                                       [--description DESC] [--format text|json]
@@ -79,7 +95,7 @@ Flags:
   --description <text>   Optional longer commit body.
   --format text|json     Output format. Default: text.
 
-The current branch must match the PR head ref and local HEAD must match the PR head SHA.
+The current branch must match the PR head ref. Local HEAD may equal or descend from the PR head.
 --help, -h                      Print this help and exit before GitHub, git, config, or log I/O.`,
     admin: `pr-shepherd admin
 
@@ -152,7 +168,7 @@ Flags:
   --help, -h             Print this help and exit before GitHub, git, config, or log I/O.
 
 Preconditions:
-  The current branch must match the PR head ref, and local HEAD must match the PR head SHA.
+  The current branch must match the PR head ref. Local HEAD may equal or descend from the PR head.
 
 Exit codes:
   0   suggestion patch and instructions produced

package/bin/cli/help-iterate-poll-pages.d.mts

@@ -1,4 +1,4 @@
-export declare const ITERATE_USAGE = "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
-export declare const POLL_USAGE = "pr-shepherd poll\n\nRun iterate repeatedly for WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR] [poll-flags] [iterate-flags]\n\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes an explicit still-running line to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, CANCEL, or ESCALATE.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+export declare const ITERATE_USAGE = "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n  MERGE       Run the emitted merge/queue command, then continue monitoring.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+export declare const POLL_USAGE = "pr-shepherd poll\n\nRun iterate repeatedly for WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal or --merge, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR] [poll-flags] [iterate-flags]\n\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes an explicit still-running line to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
 /** Public help page for the default PR polling invocation. */
 export declare const DEFAULT_USAGE: string;

package/bin/cli/help-iterate-poll-pages.mjs

@@ -11,6 +11,7 @@ Iterate flags:
   --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
   --no-auto-mark-ready           Do not convert draft PRs to ready for review.
   --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
+  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.
   --format text|json             Output Markdown text or JSON. Default: text.
   --verbose                      Include verbose iterate fields.
   --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
@@ -23,6 +24,7 @@ Actions:
   FIX_CODE    Agent action is required; follow the instructions, then continue polling.
   CANCEL      Stop polling: merged/closed or ready-delay elapsed.
   ESCALATE    Stop polling until a human provides direction.
+  MERGE       Run the emitted merge/queue command, then continue monitoring.
 
 Exit codes:
   0   CANCEL (merged or ready-delay elapsed)
@@ -31,6 +33,7 @@ Exit codes:
   12  FIX_CODE
   13  ESCALATE
   14  CANCEL (closed without merging)
+  15  MERGE
   A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).`;
 export const POLL_USAGE = `pr-shepherd poll
 
@@ -39,7 +42,7 @@ final tick to stdout.
 Poll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout
 returns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps
 iterating at --interval, then runs one more tick after the window and returns that result.
-With --until-terminal, poll also continues through MARK_READY.
+With --until-terminal or --merge, poll also continues through MARK_READY.
 
 Usage:
   pr-shepherd poll [PR] [poll-flags] [iterate-flags]
@@ -56,6 +59,7 @@ Forwarded iterate flags:
   --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
   --no-auto-mark-ready           Do not convert draft PRs to ready for review.
   --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
+  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.
   --format text|json             Output Markdown text or JSON. Default: text.
   --verbose                      Include verbose iterate fields and detailed per-tick lines.
   --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
@@ -65,7 +69,7 @@ for --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout);
 an explicit unit (4.5m).
 Each WAIT tick writes an explicit still-running line to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.
 FIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.
-With --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, CANCEL, or ESCALATE.
+With --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.
 
 Exit codes: same as iterate (the final tick's action/reason decides the code).
   0   CANCEL (merged or ready-delay elapsed)
@@ -74,6 +78,7 @@ Exit codes: same as iterate (the final tick's action/reason decides the code).
   12  FIX_CODE
   13  ESCALATE
   14  CANCEL (closed without merging)
+  15  MERGE
   A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).`;
 /** Public help page for the default PR polling invocation. */
 export const DEFAULT_USAGE = POLL_USAGE.replace(/^pr-shepherd poll$/m, "pr-shepherd [PR]").replace(/^ {2}pr-shepherd poll \[PR\]/m, "  pr-shepherd [PR]");

package/bin/cli/help-top-page.d.mts

@@ -1 +1 @@
-export declare const TOP_USAGE = "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR] [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd build-suggestion-patch [PR] --thread-id ID --message MSG [flags]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR]                 Poll until non-WAIT or timeout. This is the default command.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark changed files as viewed in GitHub.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  build-suggestion-patch\n                       Convert one GitHub suggestion thread into a patch and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number such as 42 or a GitHub pull request URL.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nClean variants:\n  pr [number]          Remove state for one PR. Defaults to current branch PR.\n  branch [name]        Remove state for a branch's PR. Defaults to current branch.\n  current              Alias for branch against the current branch.\n  repo                 Remove all state for the current repository.\n  all                  Remove all pr-shepherd state.\n\nExit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\nSee docs/exit-codes.md for the full sysexits.h error-code table.\n\nDuration examples: 30s, 4.5m, 1h. A bare number uses each flag's default unit (see above); decimals are allowed with an explicit unit (4.5m).\n\nRun 'pr-shepherd <command> --help' for command-specific details.";
+export declare const TOP_USAGE = "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR] [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR]                 Poll until non-WAIT or timeout. This is the default command.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark changed files as viewed in GitHub.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  build-suggestion-patches\n                       Convert ordered GitHub suggestion threads into patches and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number such as 42 or a GitHub pull request URL.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nClean variants:\n  pr [number]          Remove state for one PR. Defaults to current branch PR.\n  branch [name]        Remove state for a branch's PR. Defaults to current branch.\n  current              Alias for branch against the current branch.\n  repo                 Remove all state for the current repository.\n  all                  Remove all pr-shepherd state.\n\nExit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\nSee docs/exit-codes.md for the full sysexits.h error-code table.\n\nDuration examples: 30s, 4.5m, 1h. A bare number uses each flag's default unit (see above); decimals are allowed with an explicit unit (4.5m).\n\nRun 'pr-shepherd <command> --help' for command-specific details.";