pr-shepherd 0.40.0 → 0.42.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.40.0",
+  "version": "0.42.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`, `CANCEL`, or `ESCALATE`, plus numbered `## Instructions` and explicit `apply` / `build_suggestion_patches` operations. 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,7 +25,7 @@ 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. 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:
 
@@ -88,7 +88,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 +115,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. `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:
 
@@ -131,7 +131,25 @@ 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
+
+The pure `pr-shepherd/journal` entry point can extract one validated journal without GitHub access:
+
+```ts
+import { extractShepherdJournal } from "pr-shepherd/journal";
+
+const result = extractShepherdJournal(prBody);
+if (!result.ok) throw new Error(result.error);
+
+for (const entry of result.journal?.entries ?? []) console.log(entry);
+```
+
+The result identifies canonical `details` versus historical `legacy` H2 journals and returns each
+complete Markdown list item with LF line endings. It fails closed for malformed or ambiguous
+containers and ignores journal-shaped examples hidden in Markdown constructs. The full journal API,
+including append and reconciliation helpers, is documented in [docs/api.md](docs/api.md).
 
 ### Clean Local State
 
@@ -258,7 +276,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,12 +1,12 @@
 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;
 }
-/** A positive PR number or canonical GitHub pull-request URL. */
+/** A positive PR number, GitHub pull-request URL, or owner/repo#number reference. */
 export type PrReference = number | string;
 export type IterateInput = Omit<IterateCommandOptions, "format" | "prNumber"> & {
     pr?: PrReference;
@@ -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";
@@ -8,6 +9,7 @@ import { runMarkFilesAsViewed, } from "./commands/mark-files-as-viewed.mjs";
 import { runResolveMutate } from "./commands/resolve-mutate.mjs";
 import { runWithExecutionCwd } from "./execution-context.mjs";
 import { getRepoInfo } from "./github/client.mjs";
+import { parsePrReference } from "./pr-reference.mjs";
 /** Raised before any API mutation when an input cannot be validated. */
 export class PrShepherdValidationError extends Error {
     constructor(message) {
@@ -100,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) {
@@ -108,7 +118,7 @@ function validateApplyInput(input) {
     }
     for (const operation of input.operations)
         validateOperation(operation);
-    parsePrReference(input.pr);
+    validatePrReference(input.pr);
 }
 function validateOperation(operation) {
     if (!operation || typeof operation !== "object") {
@@ -183,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() === "") {
@@ -192,38 +202,45 @@ function validateSuggestionPatchInput(input) {
     if (input.description !== undefined && typeof input.description !== "string") {
         throw new PrShepherdValidationError("buildSuggestionPatch.description must be a string");
     }
-    parsePrReference(input.pr);
+    validatePrReference(input.pr);
 }
-function parsePrReference(pr) {
-    if (pr === undefined)
-        return {};
-    if (typeof pr === "number" && Number.isInteger(pr) && pr > 0)
-        return { number: pr };
-    if (typeof pr === "string") {
-        try {
-            const url = new URL(pr);
-            const parts = url.pathname.split("/").filter(Boolean);
-            if ((url.protocol === "https:" || url.protocol === "http:") &&
-                (url.hostname === "github.com" || url.hostname === "www.github.com") &&
-                parts.length === 4 &&
-                parts[2] === "pull" &&
-                /^[1-9][0-9]*$/.test(parts[3])) {
-                return { number: Number(parts[3]), repository: `${parts[0]}/${parts[1]}` };
-            }
+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");
         }
-        catch {
-            // Construct the uniform public validation error below.
+        if (seen.has(suggestion.threadId)) {
+            throw new PrShepherdValidationError(`duplicate suggestion thread ID: ${suggestion.threadId}`);
         }
+        seen.add(suggestion.threadId);
     }
-    throw new PrShepherdValidationError("pr must be a positive number or a GitHub pull-request URL");
+    validatePrReference(input.pr);
 }
-async function resolvePrReference(pr) {
+function validatePrReference(pr) {
     const parsed = parsePrReference(pr);
+    if (parsed !== null)
+        return parsed;
+    throw new PrShepherdValidationError("pr must be a positive number, a GitHub pull-request URL, or owner/repo#number");
+}
+async function resolvePrReference(pr) {
+    const parsed = validatePrReference(pr);
     if (parsed.repository !== undefined) {
         const repo = await getRepoInfo();
         const currentRepository = `${repo.owner}/${repo.name}`;
         if (parsed.repository.toLowerCase() !== currentRepository.toLowerCase()) {
-            throw new PrShepherdValidationError(`PR URL repository ${parsed.repository} does not match the configured repository ${currentRepository}`);
+            throw new PrShepherdValidationError(`PR reference repository ${parsed.repository} does not match the configured repository ${currentRepository}`);
         }
     }
     return parsed.number;

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();

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

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-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.";

package/bin/cli/help-top-page.mjs

@@ -10,7 +10,7 @@ Usage:
   pr-shepherd apply review [PR] [review-flags]
   pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]
   pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]
-  pr-shepherd build-suggestion-patch [PR] --thread-id ID --message MSG [flags]
+  pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]
   pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]
   pr-shepherd admin log-file [--format text|json]
 
@@ -20,8 +20,8 @@ Commands:
   apply review         Apply review-state mutations after fixes.
   apply files          Mark changed files as viewed in GitHub.
   apply journal        Append a list item to the Shepherd Journal details block of a PR body.
-  build-suggestion-patch
-                       Convert one GitHub suggestion thread into a patch and commit instructions.
+  build-suggestion-patches
+                       Convert ordered GitHub suggestion threads into patches and commit instructions.
   admin clean          Remove pr-shepherd state files.
   admin log-file       Print the per-worktree debug log path.
 

package/bin/cli/help.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
@@ -228,7 +244,7 @@ Flags:
 
 Exit code: 0 on success (including no-change no-op); nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
     readonly "log-file": "pr-shepherd log-file\n\nPrint the per-worktree append-only debug log path for the current repository.\nThe log is created by the first non-help pr-shepherd command that initializes logging.\n\nUsage:\n  pr-shepherd log-file [--format text|json]\n\nFlags:\n  --format text|json   Print a raw path or {\"path\": \"...\"} JSON. Default: text.\n  --help, -h           Print this help and exit before logging setup.\n\nEnvironment:\n  PR_SHEPHERD_LOG_DISABLED=1 disables logging.\n  PR_SHEPHERD_STATE_DIR overrides the base state directory.\n\nExit code: 0 on success; 1 if repository identity cannot be resolved.";
-    readonly top: "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.";
+    readonly top: "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.";
 };
 /** Resolve help keys for nested public commands before any command I/O. */
 export declare function helpKeyForArgs(args: string[]): keyof typeof USAGE;

package/bin/cli/suggestion-patch-flags.d.mts

@@ -0,0 +1,11 @@
+import type { SuggestionPatchRequest } from "../commands/suggestion-patch-item.mts";
+type ParseFailure = {
+    ok: false;
+    error: string;
+};
+type ParseResult = {
+    ok: true;
+    suggestions: SuggestionPatchRequest[];
+} | ParseFailure;
+export declare function parseSuggestionPatchGroups(args: readonly string[]): ParseResult;
+export {};