pr-shepherd 0.40.0 → 0.42.0

package/bin/github/suggestion-thread.d.mts

@@ -1,9 +1,9 @@
 import type { ReviewThread } from "../types.mts";
 import type { RepoInfo } from "./client.mts";
-export interface SuggestionThreadResult {
+export interface SuggestionThreadsResult {
     headRefOid: string;
     headRefName: string;
     headRepoWithOwner: string | null;
-    thread: ReviewThread | null;
+    threads: (ReviewThread | null)[];
 }
-export declare function fetchSuggestionThread(pr: number, repo: RepoInfo, threadId: string): Promise<SuggestionThreadResult>;
+export declare function fetchSuggestionThreads(pr: number, repo: RepoInfo, threadIds: readonly string[]): Promise<SuggestionThreadsResult>;

package/bin/github/suggestion-thread.mjs

@@ -1,12 +1,12 @@
 import { graphql } from "./client.mjs";
-import { COMMIT_SUGGESTION_THREAD_QUERY } from "./queries.mjs";
+import { SUGGESTION_THREADS_QUERY } from "./queries.mjs";
 import { mapAuthorType, parseCreatedAt } from "./batch-parser-helpers.mjs";
-export async function fetchSuggestionThread(pr, repo, threadId) {
-    const result = await graphql(COMMIT_SUGGESTION_THREAD_QUERY, {
+export async function fetchSuggestionThreads(pr, repo, threadIds) {
+    const result = await graphql(SUGGESTION_THREADS_QUERY, {
         owner: repo.owner,
         repo: repo.name,
         pr,
-        threadId,
+        threadIds,
     });
     const pull = result.data.repository.pullRequest;
     if (!pull) {
@@ -16,7 +16,10 @@ export async function fetchSuggestionThread(pr, repo, threadId) {
         headRefOid: pull.headRefOid,
         headRefName: pull.headRefName,
         headRepoWithOwner: pull.headRepository?.nameWithOwner ?? null,
-        thread: parseThread(result.data.node, pr, threadId),
+        threads: threadIds.map((threadId) => {
+            const raw = result.data.nodes.find((candidate) => candidate?.id === threadId) ?? null;
+            return parseThread(raw, pr, threadId);
+        }),
     };
 }
 function parseThread(raw, pr, threadId) {

package/bin/journal/extract.d.mts

@@ -0,0 +1,16 @@
+/** Result of extracting the single visible structural Shepherd Journal from Markdown. */
+export type ShepherdJournalExtraction = {
+    journal: null;
+    ok: true;
+} | {
+    journal: {
+        entries: string[];
+        format: "details" | "legacy";
+    };
+    ok: true;
+} | {
+    error: string;
+    ok: false;
+};
+/** Extract ordered journal entries while failing closed on malformed or ambiguous content. */
+export declare function extractShepherdJournal(body: string): ShepherdJournalExtraction;

package/bin/journal/extract.mjs

@@ -0,0 +1,71 @@
+import { parseShepherdJournalEntries, scanShepherdJournal } from "./reconcile.mjs";
+import { isMarkdownBlockStart, scanMarkdownLines } from "./markdown-line.mjs";
+import { stripMarkdownContainer } from "./markdown-container.mjs";
+import { isIndentedCode } from "./markdown-structure.mjs";
+function hasUnrecognizedJournalContent(lines) {
+    const syntax = scanMarkdownLines(lines);
+    let foundEntry = false;
+    let lazyContinuation = false;
+    let nestedBlock = false;
+    for (const [index, line] of lines.entries()) {
+        const scanned = syntax[index];
+        if (scanned.visiblePrefix.startsWith("- ") && /^- \S/.test(line)) {
+            foundEntry = true;
+            lazyContinuation = true;
+            nestedBlock = false;
+            continue;
+        }
+        if (line.trim() === "") {
+            if (foundEntry)
+                lazyContinuation = false;
+            continue;
+        }
+        if (!foundEntry)
+            return true;
+        const content = stripMarkdownContainer(line, [{ kind: "list", width: 2 }]);
+        if (content === null) {
+            if (!lazyContinuation || isMarkdownBlockStart(line))
+                return true;
+            continue;
+        }
+        if (scanned.ignored || isMarkdownBlockStart(content) || isIndentedCode(content)) {
+            lazyContinuation = false;
+            nestedBlock = true;
+            continue;
+        }
+        if (nestedBlock && /^[ \t]/.test(content)) {
+            lazyContinuation = false;
+            continue;
+        }
+        lazyContinuation = true;
+        nestedBlock = false;
+    }
+    return false;
+}
+/** Extract ordered journal entries while failing closed on malformed or ambiguous content. */
+export function extractShepherdJournal(body) {
+    const lines = body.replaceAll("\r\n", "\n").replaceAll("\r", "\n").split("\n");
+    const journal = scanShepherdJournal(lines);
+    if (journal === "error") {
+        return {
+            error: "malformed, duplicate, or ambiguous Shepherd Journal container",
+            ok: false,
+        };
+    }
+    if (!journal)
+        return { journal: null, ok: true };
+    const content = lines.slice(journal.contentStart, journal.contentEnd);
+    if (hasUnrecognizedJournalContent(content)) {
+        return {
+            error: "Shepherd Journal content uses an unrecognized entry format",
+            ok: false,
+        };
+    }
+    return {
+        journal: {
+            entries: parseShepherdJournalEntries(content).map((entry) => entry.join("\n")),
+            format: journal.format,
+        },
+        ok: true,
+    };
+}

package/bin/journal/index.d.mts

@@ -1,3 +1,4 @@
 /** GitHub-free Shepherd Journal helpers for programmatic PR-body reconciliation. */
 export { appendJournalItem, validateJournalItem, type AppendResult } from "./append.mts";
+export { extractShepherdJournal, type ShepherdJournalExtraction } from "./extract.mts";
 export { reconcileShepherdJournal, type ShepherdJournalReconcileResult } from "./reconcile.mts";

package/bin/journal/index.mjs

@@ -1,3 +1,4 @@
 /** GitHub-free Shepherd Journal helpers for programmatic PR-body reconciliation. */
 export { appendJournalItem, validateJournalItem } from "./append.mjs";
+export { extractShepherdJournal } from "./extract.mjs";
 export { reconcileShepherdJournal } from "./reconcile.mjs";

package/bin/journal/markdown-line.d.mts

@@ -3,6 +3,8 @@ type MarkdownLine = {
     nested: boolean;
     visiblePrefix: string;
 };
+/** Return whether a Markdown line starts a block that interrupts inline content. */
+export declare function isMarkdownBlockStart(line: string): boolean;
 export declare const scanMarkdownLines: (lines: string[]) => MarkdownLine[];
 export declare const isSafeMarkdownInsertionPoint: (lines: string[]) => boolean;
 export {};

package/bin/journal/markdown-line.mjs

@@ -2,18 +2,20 @@ import { fenceStart, resolveMarkdownContainer, stripMarkdownContainer, } from ".
 import { inQuotedHtmlAttribute, rawHtmlEnd, rawHtmlStart, } from "./markdown-html.mjs";
 import { backtickRuns, nextBacktickRun, nextCodeOpener } from "./markdown-backticks.mjs";
 import { isIndentedCode, structuralDetailsStart } from "./markdown-structure.mjs";
-function interruptsInlineContent(line) {
+/** Return whether a Markdown line starts a block that interrupts inline content. */
+export function isMarkdownBlockStart(line) {
     return (line.trim() === "" ||
         /^ {0,3}(?:#{1,6}(?:[ \t]+|$)|>)/.test(line) ||
         /^ {0,3}(?:[-+*]|\d{1,9}[.)])[ \t]+/.test(line) ||
         /^ {0,3}(?:(?:\*[ \t]*){3,}|-+[ \t]*|(?:_[ \t]*){3,}|=+[ \t]*)$/.test(line) ||
+        /^ {0,3}<!--/.test(line) ||
         fenceStart(line) !== null ||
         rawHtmlStart(line) !== null ||
         structuralDetailsStart(line) !== null);
 }
 function hasCloser(lines, lineIndex, offset, length) {
     for (let i = lineIndex; i < lines.length; i++) {
-        if (i > lineIndex && interruptsInlineContent(lines[i]))
+        if (i > lineIndex && isMarkdownBlockStart(lines[i]))
             return false;
         if (backtickRuns(lines[i]).some((run) => run.length === length && (i > lineIndex || run.index > offset)))
             return true;

package/bin/journal/reconcile.d.mts

@@ -13,5 +13,6 @@ export type ShepherdJournalBounds = {
     start: number;
 };
 export declare function scanShepherdJournal(lines: string[]): ShepherdJournalBounds | null | "error";
+export declare function parseShepherdJournalEntries(lines: string[]): string[][];
 export declare function containsJournalEntry(lines: string[], item: string): boolean;
 export declare function reconcileShepherdJournal(suppliedBody: string, liveBody: string): ShepherdJournalReconcileResult;

package/bin/journal/reconcile.mjs

@@ -61,7 +61,10 @@ export function scanShepherdJournal(lines) {
             return "error";
         }
         if (JOURNAL_SUMMARY.test(visible.trimStart())) {
-            if (lines[i] !== SUMMARY || lines[i - 1] !== OPEN || lines[i + 1] !== "")
+            if (detailsDepth !== 1 ||
+                lines[i] !== SUMMARY ||
+                lines[i - 1] !== OPEN ||
+                lines[i + 1] !== "")
                 return "error";
             const end = close(lines, syntax, i + 2);
             if (end === null)
@@ -78,7 +81,7 @@ export function scanShepherdJournal(lines) {
             continue;
         }
         if (LEGACY.test(visible)) {
-            if (legacy)
+            if (detailsDepth !== 0 || legacy)
                 return "error";
             legacy = {
                 contentEnd: lines.length,
@@ -108,7 +111,7 @@ function trim(lines) {
         b--;
     return lines.slice(a, b);
 }
-function entries(lines) {
+export function parseShepherdJournalEntries(lines) {
     const result = [];
     const syntax = scanMarkdownLines(lines.map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line)));
     let current = null;
@@ -125,7 +128,7 @@ function entries(lines) {
         result.push(trim(current));
     return result;
 }
-function hasUnrecognizedLeadingContent(lines) {
+function hasUnrecognizedLeadingJournalContent(lines) {
     const syntax = scanMarkdownLines(lines.map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line)));
     const firstEntry = syntax.findIndex((line) => line.visiblePrefix.startsWith("- "));
     if (firstEntry === -1)
@@ -137,7 +140,7 @@ function contains(a, b) {
 }
 export function containsJournalEntry(lines, item) {
     const target = item.split("\n");
-    return entries(lines).some((entry) => contains(target, entry));
+    return parseShepherdJournalEntries(lines).some((entry) => contains(target, entry));
 }
 function fail(reason) {
     return {
@@ -169,11 +172,11 @@ export function reconcileShepherdJournal(suppliedBody, liveBody) {
             ok: true,
         };
     }
-    const liveEntries = entries(liveLines.slice(live.contentStart, live.contentEnd));
     const liveJournalLines = liveLines.slice(live.contentStart, live.contentEnd);
-    if (!liveEntries.length || hasUnrecognizedLeadingContent(liveJournalLines))
+    const liveEntries = parseShepherdJournalEntries(liveJournalLines);
+    if (!liveEntries.length || hasUnrecognizedLeadingJournalContent(liveJournalLines))
         return fail("live Shepherd Journal content uses an unrecognized entry format");
-    const target = entries(suppliedLines.slice(supplied.contentStart, supplied.contentEnd));
+    const target = parseShepherdJournalEntries(suppliedLines.slice(supplied.contentStart, supplied.contentEnd));
     for (const entry of liveEntries) {
         const match = target.findIndex((candidate) => contains(entry, candidate));
         if (match === -1)

package/bin/mcp/server.d.mts

@@ -4,5 +4,5 @@ export interface CreatePrShepherdMcpServerOptions extends CreatePrShepherdOption
     /** Optional injection point for embedding hosts and focused tests. */
     shepherd?: PrShepherd;
 }
-/** Creates a local-only MCP server with the three public Shepherd operations. */
+/** Creates a local-only MCP server with Shepherd's public operations. */
 export declare function createPrShepherdMcpServer(options?: CreatePrShepherdMcpServerOptions): McpServer;

package/bin/mcp/server.mjs

@@ -3,10 +3,15 @@ import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { createPrShepherd, PartialApplyError, PrShepherdValidationError, } from "../api.mjs";
+import { isRepositoryQualifiedPrReference } from "../pr-reference.mjs";
 import { formatJournalResult } from "../cli/journal-formatter.mjs";
-import { formatCommitSuggestionResult, formatIterateResult, formatMarkFilesAsViewedResult, formatMutateResult, } from "../cli/formatters.mjs";
+import { formatCommitSuggestionResult, formatSuggestionPatchesResult, formatIterateResult, formatMarkFilesAsViewedResult, formatMutateResult, } from "../cli/formatters.mjs";
 import { errorToExitCode, EXIT } from "../exit-codes.mjs";
-const pr = z.union([z.number().int().positive(), z.string().url()]).optional();
+const QUALIFIED_PR_ERROR = "pr must be a GitHub pull-request URL or an owner/repo#number reference";
+const pr = z
+    .string()
+    .refine(isRepositoryQualifiedPrReference, { message: QUALIFIED_PR_ERROR })
+    .describe("GitHub pull-request URL or owner/repo#number");
 const ids = z.array(z.string().min(1)).optional();
 const iterateInputSchema = z.object({
     pr,
@@ -52,7 +57,17 @@ const suggestionPatchInputSchema = z.object({
     message: z.string().min(1),
     description: z.string().optional(),
 });
-/** Creates a local-only MCP server with the three public Shepherd operations. */
+const suggestionPatchesInputSchema = z.object({
+    pr,
+    suggestions: z
+        .array(z.object({
+        threadId: z.string().min(1),
+        message: z.string().min(1),
+        description: z.string().optional(),
+    }))
+        .min(1),
+});
+/** Creates a local-only MCP server with Shepherd's public operations. */
 export function createPrShepherdMcpServer(options = {}) {
     const shepherd = options.shepherd ?? createPrShepherd({ cwd: options.cwd });
     const server = new McpServer({ name: "pr-shepherd", version: readPackageVersion() });
@@ -65,7 +80,7 @@ export function createPrShepherdMcpServer(options = {}) {
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async (input) => runTool(() => shepherd.iterate(input), formatIterateResult));
+    }, async (input) => runTool(() => shepherd.iterate(requireRepositoryQualifiedPr(input)), formatIterateResult));
     server.registerTool("apply", {
         description: "Apply ordered review, file-view, and journal operations after prevalidation.",
         inputSchema: applyInputSchema,
@@ -75,9 +90,19 @@ export function createPrShepherdMcpServer(options = {}) {
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async (input) => runTool(() => shepherd.apply(input), formatApplyResult));
+    }, async (input) => runTool(() => shepherd.apply(requireRepositoryQualifiedPr(input)), formatApplyResult));
+    server.registerTool("build_suggestion_patches", {
+        description: "Build, but never apply, an ordered list of eligible review suggestion patches.",
+        inputSchema: suggestionPatchesInputSchema,
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: true,
+        },
+    }, async (input) => runTool(() => shepherd.buildSuggestionPatches(requireRepositoryQualifiedPr(input)), formatSuggestionPatchesResult));
     server.registerTool("build_suggestion_patch", {
-        description: "Build, but never apply, a patch from an eligible review suggestion.",
+        description: "Deprecated: use build_suggestion_patches with a one-item suggestions array.",
         inputSchema: suggestionPatchInputSchema,
         annotations: {
             readOnlyHint: true,
@@ -85,9 +110,15 @@ export function createPrShepherdMcpServer(options = {}) {
             idempotentHint: true,
             openWorldHint: true,
         },
-    }, async (input) => runTool(() => shepherd.buildSuggestionPatch(input), formatCommitSuggestionResult));
+    }, async (input) => runTool(() => shepherd.buildSuggestionPatch(requireRepositoryQualifiedPr(input)), formatCommitSuggestionResult));
     return server;
 }
+function requireRepositoryQualifiedPr(input) {
+    if (!isRepositoryQualifiedPrReference(input.pr)) {
+        throw new PrShepherdValidationError(QUALIFIED_PR_ERROR);
+    }
+    return input;
+}
 function readPackageVersion() {
     const packageJson = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
     return packageJson.version;

package/bin/pr-reference.d.mts

@@ -0,0 +1,7 @@
+export interface ParsedPrReference {
+    number?: number;
+    repository?: string;
+}
+/** Parses API PR references without performing repository or GitHub I/O. */
+export declare function parsePrReference(pr: number | string | undefined): ParsedPrReference | null;
+export declare function isRepositoryQualifiedPrReference(pr: unknown): pr is string;

package/bin/pr-reference.mjs

@@ -0,0 +1,36 @@
+/** Parses API PR references without performing repository or GitHub I/O. */
+export function parsePrReference(pr) {
+    if (pr === undefined)
+        return {};
+    if (typeof pr === "number" && Number.isInteger(pr) && pr > 0)
+        return { number: pr };
+    if (typeof pr !== "string")
+        return null;
+    const shorthand = /^([^/#\s]+)\/([^/#\s]+)#([1-9][0-9]*)$/.exec(pr);
+    if (shorthand) {
+        return {
+            number: Number(shorthand[3]),
+            repository: `${shorthand[1]}/${shorthand[2]}`,
+        };
+    }
+    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]}` };
+        }
+    }
+    catch {
+        // Return the uniform invalid result below.
+    }
+    return null;
+}
+export function isRepositoryQualifiedPrReference(pr) {
+    if (typeof pr !== "string")
+        return false;
+    return parsePrReference(pr)?.repository !== undefined;
+}

package/bin/types/report.d.mts

@@ -150,25 +150,6 @@ export interface RelevantCheck {
     /** Marker-gated inline annotations from this check. */
     annotations?: CheckAnnotation[];
 }
-export interface CommitSuggestionResult {
-    pr: number;
-    repo: string;
-    threadId: string;
-    path: string;
-    startLine: number;
-    endLine: number;
-    author: string;
-    /** The unified diff generated for this suggestion. */
-    patch: string;
-    /** The commit subject line (user-supplied --message). */
-    commitMessage: string;
-    /** The commit body (optional description + Co-authored-by trailer). */
-    commitBody: string;
-    /** Files the agent should stage before committing. */
-    filesToStage: string[];
-    /** Numbered steps the agent must execute to apply, commit, resolve, and push. */
-    postActionInstructions: string[];
-}
 export interface GlobalOptions {
     prNumber?: number;
     format: "text" | "json";

package/bin/types/suggestion-patch.d.mts

@@ -0,0 +1,30 @@
+export interface SuggestionPatchResult {
+    threadId: string;
+    path: string;
+    startLine: number;
+    endLine: number;
+    author: string;
+    /** The unified diff generated for this suggestion. */
+    patch: string;
+    /** The commit subject line supplied by the caller. */
+    commitMessage: string;
+    /** The optional description plus Co-authored-by trailer. */
+    commitBody: string;
+    /** Files the agent should stage before committing. */
+    filesToStage: string[];
+}
+export interface BuildSuggestionPatchesResult {
+    pr: number;
+    repo: string;
+    /** Suggestion patches in caller-supplied application order. */
+    patches: SuggestionPatchResult[];
+    /** Steps for applying and committing every patch, then pushing once. */
+    postActionInstructions: string[];
+}
+/** Compatibility result for the singular suggestion-patch adapter. */
+export interface CommitSuggestionResult extends SuggestionPatchResult {
+    pr: number;
+    repo: string;
+    /** Numbered steps for the deprecated singular workflow. */
+    postActionInstructions: string[];
+}

package/bin/types/suggestion-patch.mjs

@@ -0,0 +1 @@
+export {};

package/bin/types.d.mts

@@ -6,5 +6,6 @@ export * from "./types/review-thread.mts";
 export * from "./types/agent-thread.mts";
 export * from "./types/check-annotations.mts";
 export * from "./types/report.mts";
+export * from "./types/suggestion-patch.mts";
 export * from "./types/iterate.mts";
 export * from "./types/merge-requirements.mts";

package/bin/types.mjs

@@ -6,5 +6,6 @@ export * from "./types/review-thread.mjs";
 export * from "./types/agent-thread.mjs";
 export * from "./types/check-annotations.mjs";
 export * from "./types/report.mjs";
+export * from "./types/suggestion-patch.mjs";
 export * from "./types/iterate.mjs";
 export * from "./types/merge-requirements.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.40.0",
+  "version": "0.42.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

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

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.40.0",
+  "version": "0.42.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

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

@@ -2,7 +2,7 @@
   "mcpServers": {
     "pr-shepherd": {
       "command": "npx",
-      "args": ["--yes", "--package", "pr-shepherd@0.40.0", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.42.0", "pr-shepherd-mcp"]
     }
   }
 }

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

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.40.0", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.42.0", "pr-shepherd-mcp"]
   }
 }

package/plugins/pr-shepherd/skills/mark-files-as-viewed/SKILL.md

@@ -12,6 +12,6 @@ Thin dispatcher for marking PR files viewed. Use the MCP server when it is avail
 
 ## Arguments: $ARGUMENTS
 
-1. Parse an optional PR number or GitHub PR URL. Treat standalone `tests` as `--tests`; preserve explicit paths and `--match <regex>` selectors.
+1. Parse an optional PR number, repository-qualified `owner/repo#N`, or GitHub PR URL. Treat standalone `tests` as `--tests`; preserve explicit paths and `--match <regex>` selectors.
 
-2. If the `apply` MCP tool is available, call it with one `mark_files_viewed` operation, then print the full result. Otherwise run `pr-shepherd apply files` with the parsed PR and selectors and print the full result.
+2. If the `apply` MCP tool is available, first obtain a repository-qualified reference: use a supplied GitHub PR URL or `owner/repo#N` unchanged; for a bare number, run `gh pr view <number> --json url --jq .url`; when omitted, run `gh pr view --json url --jq .url`. If that does not produce one qualified PR reference, stop and report that MCP cannot safely determine the PR. Otherwise call `apply` with that qualified reference and one `mark_files_viewed` operation, then print the full result. If MCP is unavailable and the parsed PR is repository-qualified, run `gh repo view --json nameWithOwner --jq .nameWithOwner` and verify that repository matches the reference case-insensitively. Stop on a mismatch or failed lookup; the CLI does not validate the URL repository. Convert a verified `owner/repo#N` to `https://github.com/owner/repo/pull/N`, then run `pr-shepherd apply files` with the parsed PR and selectors and print the full result.

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -12,11 +12,11 @@ Thin dispatcher for iterating a PR. Poll with the CLI; use MCP `iterate` only wh
 
 ## Arguments: $ARGUMENTS
 
-1. Parse an optional PR number or GitHub PR URL from `$ARGUMENTS`; otherwise let pr-shepherd infer the current branch PR.
+1. Parse an optional PR number, repository-qualified `owner/repo#N`, or GitHub PR URL from `$ARGUMENTS`; otherwise let pr-shepherd infer the current branch PR.
 
-2. Run the poll command `pr-shepherd` with the optional PR argument and print its full result. Do not run `pr-shepherd iterate`. If the CLI is unavailable and the `iterate` MCP tool is available, call `iterate` and print its full result.
+2. Before passing a supplied GitHub PR URL or `owner/repo#N` to the CLI, run `gh repo view --json nameWithOwner --jq .nameWithOwner` and verify that repository matches the reference case-insensitively. Stop on a mismatch or failed lookup; the CLI does not validate the URL repository. Convert a verified `owner/repo#N` to `https://github.com/owner/repo/pull/N`, then run the poll command `pr-shepherd` with the optional PR argument and print its full result. Do not run `pr-shepherd iterate`. If the CLI is unavailable and the `iterate` MCP tool is available, first obtain a repository-qualified reference: use a supplied GitHub PR URL or `owner/repo#N` unchanged; for a bare number, run `gh pr view <number> --json url --jq .url`; when omitted, run `gh pr view --json url --jq .url`. If that does not produce one qualified PR reference, stop and report that MCP cannot safely determine the PR. Otherwise call `iterate` with that qualified reference and print its full result.
 
-3. Print the full result and follow every returned `## Instructions` step exactly. For CLI output, run each printed mutation command when instructed. For MCP output, use MCP `apply` and `build_suggestion_patch`; do not run a shell `pr-shepherd apply` command.
+3. Print the full result and follow every returned `## Instructions` step exactly. For CLI output, run each printed mutation command when instructed. For MCP output, use MCP `apply` and `build_suggestion_patches` with the same qualified PR reference; do not run a shell `pr-shepherd apply` command.
 
 4. After completing the returned instructions, repeat step 2 unless the action is `[CANCEL]` or `[ESCALATE]`, the instructions require a human handoff, or the human directs you to stop.
 
@@ -27,11 +27,11 @@ mechanics every tick. Apply the referenced playbook in full whenever a step poin
 
 ### Suggestion patches
 
-- The CLI only builds the patch. Apply it, stage the listed file, and follow the returned commit instructions.
-- If the command refuses because the suggestion is unsafe (an unsafe anchored range or nested/unbalanced suggestion fences), skip patch application and edit the file manually. Do not retry the command.
-- For any other refusal, follow the CLI error's stated recovery action; do not manually edit the suggestion.
-- If the patch does not apply for any other reason, edit the file manually instead. Do not retry the command.
-- After source drift prevents a generated suggestion patch from applying, replace the heading's exact `path:startLine-endLine` range with the `Replaces lines …` block verbatim. An empty replacement deletes the range. One blank line replaces it with one blank line.
+- Run one plural `build-suggestion-patches` command with a repeated `--thread-id … --message … [--description …]` group for every marked thread in displayed order.
+- The CLI only builds patches. Apply, stage, and commit the returned patches in order, then push once.
+- The command builds from the fetched PR head and accepts a clean local descendant only when the complete ordered patch stream passes `git apply --check`.
+- If the command refuses because a suggestion is unsafe or no longer applies, inspect the current source, the displayed replacement block, and reviewer intent before editing manually. Do not apply a stale numeric range blindly or retry unchanged input.
+- A returned patch was checked against the then-current worktree. If it later fails, re-inspect the worktree because it changed after validation.
 - Keep human-authored thread IDs in `apply review:` so Shepherd replies instead of resolving them.
 
 ### CI failure triage
@@ -53,12 +53,13 @@ More specific rows win over the general "GitHub Actions failure" row — check c
 
 Applies to every `apply review:` / `resolve-only:` command the CLI prints. Covers only what stays safe if you run the printed command **unmodified** — `$HEAD_SHA`/`$DISMISS_MESSAGE` substitution and the self-reply exclusion rule are separate CLI-printed steps, not covered here, because the printed command is unsafe by default without them.
 
+- Run every generated `apply review:` / `resolve-only:` command even when no code change is warranted. The command records the agent's disposition of the included review items; skipping it leaves bot threads active and can eventually trigger `fix-thrash`.
 - Never add first-look-only or check-annotation IDs to `--reply-thread-ids`, `--resolve-thread-ids`, `--dismiss-review-ids`, or `--minimize-comment-ids` — those flags are pre-populated by the CLI.
 - Keep every existing `--dismiss-review-ids` ID the CLI already included. Each is a bot or non-human review that must be dismissed; omitting one leaves the PR in `CHANGES_REQUESTED`.
 
 ### Review-mutation routing
 
-For threads under `## Review threads to resolve`: human-authored IDs use `--reply-thread-ids` (Shepherd replies instead of resolving them); bot and non-human IDs use `--resolve-thread-ids`. Use the commands as generated — do not move an ID between flags.
+For threads under both `## Review threads` and `## Review threads to resolve`, evaluate every thread before running mutations. Keep bot and non-human IDs in `--resolve-thread-ids`, including when the feedback is advisory, already satisfied, or otherwise warrants no code change. Human-authored IDs use `--reply-thread-ids`; Shepherd replies instead of resolving them. Never move a human-authored ID to `--resolve-thread-ids`. Use the commands as generated — do not move an ID between flags.
 
 ### Shepherd Journal