pr-shepherd 0.40.0 → 0.41.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.41.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.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 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.
 
 Each tick returns exactly one action:
 
@@ -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_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.
 
 The CLI remains useful for shell workflows. Its canonical polling form is:
 
@@ -133,6 +133,24 @@ pr-shepherd iterate 42                 # single tick
 
 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.
 
+### 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
 
 `pr-shepherd` stores seen markers, fix-attempt counters, stall fingerprints, ready-delay markers, and logs under `$PR_SHEPHERD_STATE_DIR` (default `$TMPDIR/pr-shepherd-state`).

package/bin/api.d.mts

@@ -6,7 +6,7 @@ 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;

package/bin/api.mjs

@@ -8,6 +8,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) {
@@ -108,7 +109,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") {
@@ -192,38 +193,21 @@ 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]}` };
-            }
-        }
-        catch {
-            // Construct the uniform public validation error below.
-        }
-    }
-    throw new PrShepherdValidationError("pr must be a positive number or a GitHub pull-request URL");
+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 = parsePrReference(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/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.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 { 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,
@@ -65,7 +70,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,7 +80,7 @@ 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_patch", {
         description: "Build, but never apply, a patch from an eligible review suggestion.",
         inputSchema: suggestionPatchInputSchema,
@@ -85,9 +90,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.40.0",
+  "version": "0.41.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.41.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.41.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.41.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_patch` 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.