pr-shepherd 0.48.0 → 0.50.0

package/bin/github/poll-summary.mjs

@@ -0,0 +1,110 @@
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { graphqlWithRateLimit } from "./client.mjs";
+import { GitHubRequestError } from "./errors.mjs";
+import { summarizePollSummaryPr } from "./poll-summary-projector.mjs";
+import { POLL_STACK_SUMMARY_QUERY, POLL_SUMMARY_FRAGMENT } from "./queries.mjs";
+const MAX_EXPLICIT_PRS_PER_QUERY = 50;
+export async function fetchPollSummary(opts, repo) {
+    if (opts.stackPrNumber !== undefined)
+        return fetchStackSummary(opts, repo);
+    const requested = deduplicate(opts.prNumbers ?? []);
+    if (requested.length === 0) {
+        throw new ShepherdError("Aggregate poll requires at least two PRs or --stack <PR>", EXIT.USAGE);
+    }
+    const raw = [];
+    let viewerCanAdminister = false;
+    for (let offset = 0; offset < requested.length; offset += MAX_EXPLICIT_PRS_PER_QUERY) {
+        const chunk = requested.slice(offset, offset + MAX_EXPLICIT_PRS_PER_QUERY);
+        const fetched = await fetchExplicitChunk(chunk, repo);
+        viewerCanAdminister = fetched.viewerCanAdminister;
+        raw.push(...fetched.prs);
+    }
+    return {
+        selection: { kind: "prs", requested },
+        prs: await Promise.all(raw.map((pr) => summarizePollSummaryPr(pr, repo, opts, viewerCanAdminister))),
+    };
+}
+async function fetchExplicitChunk(prs, repo) {
+    const declarations = prs.map((_, index) => `$pr${index}: Int!`).join(", ");
+    const aliases = prs
+        .map((_, index) => `pr${index}: pullRequest(number: $pr${index}) { ...PollSummaryPr }`)
+        .join("\n");
+    const query = `${POLL_SUMMARY_FRAGMENT}\nquery PollSummary($owner: String!, $repo: String!, ${declarations}) {\n  _shepherdRateLimit: rateLimit { cost limit nodeCount remaining resetAt used }\n  repository(owner: $owner, name: $repo) {\n    viewerCanAdminister\n    ${aliases}\n  }\n}`;
+    const variables = Object.fromEntries(prs.map((pr, index) => [`pr${index}`, pr]));
+    const result = await graphqlWithRateLimit(query, {
+        owner: repo.owner,
+        repo: repo.name,
+        ...variables,
+    });
+    if (!result.data.repository)
+        throw missingRepository(repo);
+    const rawPrs = prs.map((pr, index) => {
+        const raw = result.data.repository[`pr${index}`];
+        if (!raw)
+            throw new ShepherdError(`PR #${pr} not found`, EXIT.UNAVAILABLE);
+        return raw;
+    });
+    return { prs: rawPrs, viewerCanAdminister: result.data.repository.viewerCanAdminister };
+}
+async function fetchStackSummary(opts, repo) {
+    const anchor = opts.stackPrNumber;
+    let after = null;
+    let stackId = null;
+    let stackNumber = 0;
+    let stackSize = 0;
+    let viewerCanAdminister = false;
+    const entries = [];
+    do {
+        const response = (await graphqlWithRateLimit(POLL_STACK_SUMMARY_QUERY, {
+            owner: repo.owner,
+            repo: repo.name,
+            anchor,
+            after,
+        }));
+        const repository = response.data.repository;
+        if (!repository)
+            throw missingRepository(repo);
+        viewerCanAdminister = repository.viewerCanAdminister;
+        if (!repository.pullRequest) {
+            throw new ShepherdError(`PR #${anchor} not found`, EXIT.UNAVAILABLE);
+        }
+        const stack = repository.pullRequest.stack;
+        if (!stack) {
+            throw new ShepherdError(`PR #${anchor} is not part of a native GitHub stack`, EXIT.UNAVAILABLE);
+        }
+        if (stackId !== null && stack.id !== stackId) {
+            throw new ShepherdError("GitHub stack membership changed while it was being fetched; retry", EXIT.TEMPFAIL);
+        }
+        stackId = stack.id;
+        stackNumber = stack.number;
+        stackSize = stack.size;
+        for (const entry of stack.entries.nodes) {
+            if (!entry.pullRequest) {
+                throw new ShepherdError("GitHub returned an incomplete pull-request stack entry", EXIT.TEMPFAIL);
+            }
+            entries.push({ position: entry.position, pullRequest: entry.pullRequest });
+        }
+        const pageInfo = stack.entries.pageInfo;
+        if (pageInfo.hasNextPage && !pageInfo.endCursor) {
+            throw new ShepherdError("GitHub stack pagination did not include an end cursor", EXIT.TEMPFAIL);
+        }
+        after = pageInfo.hasNextPage ? pageInfo.endCursor : null;
+    } while (after !== null);
+    const unique = new Map();
+    for (const entry of entries)
+        unique.set(entry.pullRequest.number, entry);
+    if (!unique.has(anchor) || unique.size !== stackSize) {
+        throw new ShepherdError(`GitHub returned incomplete stack membership (${unique.size} of ${stackSize} entries)`, EXIT.TEMPFAIL);
+    }
+    const ordered = [...unique.values()].sort((left, right) => left.position - right.position);
+    return {
+        selection: { kind: "stack", anchor, stackNumber, stackSize },
+        prs: await Promise.all(ordered.map((entry) => summarizePollSummaryPr(entry.pullRequest, repo, opts, viewerCanAdminister))),
+    };
+}
+function deduplicate(values) {
+    return [...new Set(values)];
+}
+function missingRepository(repo) {
+    return new GitHubRequestError(`GitHub GraphQL response did not include repository ${repo.owner}/${repo.name} (not found or access denied)`, { status: 200 });
+}

package/bin/github/queries.d.mts

@@ -12,6 +12,10 @@ export declare const BATCH_PR_QUERY: string;
 export declare const BATCH_PR_PAGE_QUERY: string;
 /** Cheap PR fingerprint used to skip an unchanged BatchPr snapshot. */
 export declare const PR_FINGERPRINT_QUERY: string;
+/** Compact per-PR fields shared by explicit-list and native-stack summary queries. */
+export declare const POLL_SUMMARY_FRAGMENT: string;
+/** Discovers and summarizes every entry in one native GitHub pull-request stack. */
+export declare const POLL_STACK_SUMMARY_QUERY: string;
 /** PR head fields plus a single review thread for `commit-suggestion`. */
 export declare const SUGGESTION_THREADS_QUERY: string;
 /** Fetches additional comments for a single review thread when its nested connection paginates. */

package/bin/github/queries.mjs

@@ -16,6 +16,10 @@ export const BATCH_PR_QUERY = withSharedFragments(gql("batch-pr.gql"));
 export const BATCH_PR_PAGE_QUERY = gql("batch-pr-page.gql");
 /** Cheap PR fingerprint used to skip an unchanged BatchPr snapshot. */
 export const PR_FINGERPRINT_QUERY = withSharedFragments(gql("pr-fingerprint.gql"));
+/** Compact per-PR fields shared by explicit-list and native-stack summary queries. */
+export const POLL_SUMMARY_FRAGMENT = gql("poll-summary-fragment.gql");
+/** Discovers and summarizes every entry in one native GitHub pull-request stack. */
+export const POLL_STACK_SUMMARY_QUERY = `${POLL_SUMMARY_FRAGMENT}\n${gql("poll-stack-summary.gql")}`;
 /** PR head fields plus a single review thread for `commit-suggestion`. */
 export const SUGGESTION_THREADS_QUERY = gql("suggestion-threads.gql");
 /** Fetches additional comments for a single review thread when its nested connection paginates. */

package/bin/mcp/server.mjs

@@ -3,9 +3,10 @@ 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 { isRepositoryQualifiedPrReference, normalizeRepositoryIdentity, parsePrReference, } from "../pr-reference.mjs";
 import { formatJournalResult } from "../cli/journal-formatter.mjs";
 import { formatCommitSuggestionResult, formatSuggestionPatchesResult, formatIterateResult, formatMarkFilesAsViewedResult, formatMutateResult, projectIterateLean, } from "../cli/formatters.mjs";
+import { formatPollSummaryResult } from "../cli/poll-summary-formatter.mjs";
 import { formatCliError, serializeGitHubRequestErrorDetails } from "../cli/error-format.mjs";
 import { errorToExitCode, EXIT } from "../exit-codes.mjs";
 const QUALIFIED_PR_ERROR = "pr must be a GitHub pull-request URL or an owner/repo#number reference";
@@ -14,8 +15,11 @@ const pr = z
     .refine(isRepositoryQualifiedPrReference, { message: QUALIFIED_PR_ERROR })
     .describe("GitHub pull-request URL or owner/repo#number; the explicit repository may differ from the server working directory");
 const ids = z.array(z.string().min(1)).optional();
-const iterateInputSchema = z.object({
-    pr,
+const iterateInputSchema = z
+    .object({
+    pr: pr.optional(),
+    prs: z.array(pr).min(1).optional(),
+    stack: pr.optional(),
     readyDelaySeconds: z.number().nonnegative().optional(),
     stallTimeoutSeconds: z.number().nonnegative().optional(),
     noAutoMarkReady: z.boolean().optional(),
@@ -28,7 +32,12 @@ const iterateInputSchema = z.object({
         .array(z.string())
         .optional()
         .describe("Deprecated per-call no-op retained for compatibility."),
-});
+})
+    .refine((input) => [input.pr, input.prs, input.stack].filter((value) => value !== undefined).length === 1, {
+    message: "exactly one of pr, prs, or stack is required",
+})
+    .refine((input) => !input.prs ||
+    new Set(input.prs.map((ref) => normalizeRepositoryIdentity(parsePrReference(ref)?.repository ?? ""))).size === 1, { message: "all prs must belong to the same repository" });
 const reviewMutationsOperationSchema = z.object({
     type: z.literal("review_mutations"),
     resolveThreadIds: ids,
@@ -80,7 +89,7 @@ export function createPrShepherdMcpServer(options = {}) {
     const shepherd = options.shepherd ?? createPrShepherd({ cwd: options.cwd });
     const server = new McpServer({ name: "pr-shepherd", version: readPackageVersion() });
     server.registerTool("iterate", {
-        description: "Inspect the specified pull request and return the next Shepherd state.",
+        description: "Inspect one pull request, an explicit same-repository set, or a native stack and return one Shepherd tick.",
         inputSchema: iterateInputSchema,
         annotations: {
             readOnlyHint: false,
@@ -93,7 +102,9 @@ export function createPrShepherdMcpServer(options = {}) {
         const opts = {
             readyDelaySuffix: input.readyDelaySeconds === undefined ? undefined : `${input.readyDelaySeconds}s`,
         };
-        return runTool(() => shepherd.iterate(requireRepositoryQualifiedPr(input)), (result) => formatIterateResult(result, opts), (result) => projectIterateLean(result, opts));
+        return runTool(() => runIterateSelector(shepherd, requireRepositoryQualifiedIterate(input)), (result) => isPollSummary(result)
+            ? formatPollSummaryResult(result)
+            : formatIterateResult(result, opts), (result) => isPollSummary(result) ? result : projectIterateLean(result, opts));
     });
     server.registerTool("apply", {
         description: "Apply ordered review, journal, and file-view operations after prevalidation; explicit requests rely on GitHub's mutation response.",
@@ -127,6 +138,28 @@ export function createPrShepherdMcpServer(options = {}) {
     }, async (input) => runTool(() => shepherd.buildSuggestionPatch(requireRepositoryQualifiedPr(input)), formatCommitSuggestionResult));
     return server;
 }
+function runIterateSelector(shepherd, input) {
+    return "prs" in input || "stack" in input
+        ? shepherd.iterate(input)
+        : shepherd.iterate(input);
+}
+function requireRepositoryQualifiedIterate(input) {
+    if ([input.pr, input.prs, input.stack].filter((value) => value !== undefined).length !== 1) {
+        throw new PrShepherdValidationError("exactly one of pr, prs, or stack is required");
+    }
+    const refs = Array.isArray(input.prs) ? input.prs : [input.pr ?? input.stack];
+    if (refs.length === 0 || refs.some((ref) => !isRepositoryQualifiedPrReference(ref))) {
+        throw new PrShepherdValidationError(QUALIFIED_PR_ERROR);
+    }
+    const repositories = new Set(refs.map((ref) => normalizeRepositoryIdentity(parsePrReference(ref)?.repository ?? "")));
+    if (repositories.size !== 1) {
+        throw new PrShepherdValidationError("all prs must belong to the same repository");
+    }
+    return input;
+}
+function isPollSummary(result) {
+    return "mode" in result && result.mode === "summary";
+}
 function requireRepositoryQualifiedPr(input) {
     if (!isRepositoryQualifiedPrReference(input.pr)) {
         throw new PrShepherdValidationError(QUALIFIED_PR_ERROR);

package/bin/pr-reference.d.mts

@@ -18,3 +18,5 @@ export declare function resolveParsedPrTarget(parsed: ParsedPrReference): Resolv
 /** Canonical collision-safe PR reference for generated commands and escalation messages. */
 export declare function formatPrUrl(repository: string, prNumber: number): string;
 export declare function isRepositoryQualifiedPrReference(pr: unknown): pr is string;
+/** GitHub owner and repository names are case-insensitive. */
+export declare function normalizeRepositoryIdentity(repository: string): string;

package/bin/pr-reference.mjs

@@ -56,3 +56,7 @@ export function isRepositoryQualifiedPrReference(pr) {
         return false;
     return parsePrReference(pr)?.repository !== undefined;
 }
+/** GitHub owner and repository names are case-insensitive. */
+export function normalizeRepositoryIdentity(repository) {
+    return repository.toLowerCase();
+}

package/bin/state/fix-attempts.d.mts

@@ -1,14 +1,13 @@
 /**
  * Persistent attempt counter for the iterate escalation guard.
  *
- * Tracks how many times each review thread has been dispatched to the fix_code
- * handler without being resolved. Counts are reset automatically when the HEAD
- * commit SHA changes (i.e. a new push landed).
+ * Tracks how many caller-visible times each review thread has been dispatched to
+ * the fix_code handler without being resolved. Body edits reset the count.
  *
  * State lives in `$TMPDIR/pr-shepherd-state/<owner>-<repo>/<pr>/fix-attempts.json`.
  */
 export interface FixAttemptsState {
-    /** HEAD SHA at the time the counts were last written. Reset key. */
+    /** HEAD SHA at the time the counts were last written, retained for observability/compatibility. */
     headSha: string;
     /** Map from thread ID → number of fix_code dispatches that included this thread. */
     threadAttempts: Record<string, number>;

package/bin/state/fix-attempts.mjs

@@ -1,9 +1,8 @@
 /**
  * Persistent attempt counter for the iterate escalation guard.
  *
- * Tracks how many times each review thread has been dispatched to the fix_code
- * handler without being resolved. Counts are reset automatically when the HEAD
- * commit SHA changes (i.e. a new push landed).
+ * Tracks how many caller-visible times each review thread has been dispatched to
+ * the fix_code handler without being resolved. Body edits reset the count.
  *
  * State lives in `$TMPDIR/pr-shepherd-state/<owner>-<repo>/<pr>/fix-attempts.json`.
  */

package/bin/types/escalate.d.mts

@@ -1,4 +1,5 @@
 import type { AgentCheck, AgentComment, AgentThread } from "./report.mts";
+import type { ResolveCommand } from "./iterate.mts";
 import type { CheckStatus, Review } from "./github.mts";
 import type { MergeQueueRemovalStatus, StackStatus } from "./merge-requirements.mts";
 export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "check-follow-up-unavailable" | "authorization-required" | "bot-cr-not-dismissed" | "merge-queue-removed" | "stacked-pr";
@@ -19,6 +20,10 @@ export interface EscalateDetails {
     unresolvedThreads: AgentThread[];
     ambiguousComments: AgentComment[];
     changesRequestedReviews: Review[];
+    /** First-look review summaries that must be shown before any pending minimization. */
+    firstLookSummaries?: Review[];
+    /** Previously seen review summaries whose edited bodies must be shown again. */
+    editedSummaries?: Review[];
     /** Failing checks whose next step requires human attention. */
     checks?: AgentCheck[];
     stalledChecks?: AgentStalledCheck[];
@@ -26,6 +31,11 @@ export interface EscalateDetails {
         threadId: string;
         attempts: number;
     }>;
+    /** Review mutations generated for this tick, retained so an escalation cannot strand them. */
+    pendingReviewCommands?: {
+        resolveOnlyCommand?: ResolveCommand;
+        resolveCommand?: ResolveCommand;
+    };
     suggestion: string;
     humanMessage: string;
     mergeQueueRemoval?: MergeQueueRemovalStatus;

package/bin/types/poll-summary.d.mts

@@ -0,0 +1,82 @@
+import type { ApiUsage, GraphqlQuotaWarning } from "./api-usage.mts";
+import type { MergeableState, MergeStateStatus, ReviewDecision } from "./github.mts";
+import type { ShepherdAction } from "./iterate.mts";
+export interface PollSummaryChecks {
+    passing?: number;
+    failing?: number;
+    inProgress?: number;
+    skipped?: number;
+    filtered?: number;
+    ignored?: number;
+    superseded?: number;
+    incomplete?: true;
+}
+export interface PollSummaryReview {
+    comments?: number;
+    reviews?: number;
+    threads?: number;
+    actionable?: number;
+    incomplete?: true;
+}
+interface PollSummaryStack {
+    number: number;
+    size: number;
+    position: number;
+    baseRefName: string;
+}
+export interface PollSummaryItem {
+    pr: number;
+    repo: string;
+    title: string;
+    url: string;
+    /** Conservative routing hint; the selected one-PR poll makes the authoritative decision. */
+    action: ShepherdAction;
+    reasons: string[];
+    state: "OPEN" | "CLOSED" | "MERGED" | "UNKNOWN";
+    mergeable: MergeableState;
+    mergeStateStatus: MergeStateStatus;
+    reviewDecision?: ReviewDecision;
+    headRefName: string;
+    headRefOid: string;
+    baseRefName: string;
+    isDraft?: true;
+    isInMergeQueue?: true;
+    blockingReviewerInProgress?: true;
+    remainingSeconds?: number;
+    checks?: PollSummaryChecks;
+    review?: PollSummaryReview;
+    stack?: PollSummaryStack;
+    pollCommand?: string;
+}
+export type PollSummarySelection = {
+    kind: "prs";
+    requested: number[];
+} | {
+    kind: "stack";
+    anchor: number;
+    stackNumber: number;
+    stackSize: number;
+};
+export interface PollSummaryResult {
+    mode: "summary";
+    repo: string;
+    selection: PollSummarySelection;
+    reason: "actionable" | "all_terminal" | "waiting" | "timeout";
+    prs: PollSummaryItem[];
+    apiUsage?: ApiUsage;
+    quotaWarning?: GraphqlQuotaWarning;
+}
+export interface PollSummaryCommandOptions {
+    prNumbers?: number[];
+    stackPrNumber?: number;
+    targetRepository?: {
+        owner: string;
+        name: string;
+    };
+    merge?: boolean;
+    readyDelaySeconds?: number;
+    stallTimeoutSeconds?: number;
+    noAutoMarkReady?: boolean;
+    noAutoCancelActionable?: boolean;
+}
+export {};

package/bin/types/poll-summary.mjs

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

package/bin/types.d.mts

@@ -13,3 +13,4 @@ export * from "./types/merge-action.mts";
 export * from "./types/escalate.mts";
 export * from "./types/merge-queue.mts";
 export * from "./types/api-usage.mts";
+export * from "./types/poll-summary.mts";

package/bin/types.mjs

@@ -13,3 +13,4 @@ export * from "./types/merge-action.mjs";
 export * from "./types/escalate.mjs";
 export * from "./types/merge-queue.mjs";
 export * from "./types/api-usage.mjs";
+export * from "./types/poll-summary.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.48.0",
+  "version": "0.50.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.48.0",
+  "version": "0.50.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.48.0", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.50.0", "pr-shepherd-mcp"]
     }
   }
 }

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

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

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

@@ -18,9 +18,9 @@ If the requested PR does not exist yet, review and commit the in-scope changes,
 
 ## Arguments: $ARGUMENTS
 
-1. Parse an optional PR number, repository-qualified `owner/repo#N`, or GitHub PR URL and an optional `--merge` flag from `$ARGUMENTS`; otherwise let pr-shepherd infer the current branch PR. Reject any remaining argument. Follow the target repository's local `AGENTS.md` and `CLAUDE.md` standards while making changes.
+1. Parse optional PR numbers, repository-qualified `owner/repo#N` references, or GitHub PR URLs and an optional `--merge` flag from `$ARGUMENTS`; alternatively parse one `--stack PR` selector. Otherwise let pr-shepherd infer the current branch PR. Reject any remaining argument. Follow the target repository's local `AGENTS.md` and `CLAUDE.md` standards while making changes.
 
-2. For the CLI, convert supplied `owner/repo#N` to `https://github.com/owner/repo/pull/N`; otherwise pass the supplied URL or bare number unchanged, then run the canonical poll command `pr-shepherd [PR] --until-terminal`, omitting `[PR]` when none was supplied and appending `--merge` when requested. This command keeps ordinary `[WAIT]` and `[MARK_READY]` ticks inside the same invocation; it returns for agent-facing work (including an emitted `[MERGE]` command, which is non-terminal and must run before the next invocation), a quota warning, `[CANCEL]`, or `[ESCALATE]`. A qualified reference may name a fork or upstream repository: it is the GitHub target, while the current checkout continues to supply local git/config/rules context. 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, plus `merge: true` when `--merge` was supplied, and print its full result.
+2. For the CLI, convert supplied `owner/repo#N` references to `https://github.com/owner/repo/pull/N`; otherwise pass supplied URLs or bare numbers unchanged, then run `pr-shepherd [PR ...] --until-terminal`, or `pr-shepherd --stack PR --until-terminal` for a stack, omitting `[PR ...]` when none was supplied and appending `--merge` when requested. This command keeps ordinary `[WAIT]` and `[MARK_READY]` ticks inside the same invocation; aggregate selectors return when any row needs work or all rows are terminal. It also returns for a quota warning or an emitted `[MERGE]` command, which is non-terminal and must run before the next invocation. A qualified reference may name a fork or upstream repository: it is the GitHub target, while the current checkout continues to supply local git/config/rules context. Do not run `pr-shepherd iterate`. If the CLI is unavailable and the `iterate` MCP tool is available, first repository-qualify every supplied reference with its GitHub URL or `owner/repo#N`; resolve bare numbers through `gh pr view <number> --json url --jq .url`, and resolve an omitted target with `gh pr view --json url --jq .url`. If that does not produce the required qualified selector, stop and report that MCP cannot safely determine it. Otherwise call `iterate` with `pr`, `prs`, or `stack` as selected, plus `merge: true` when `--merge` was supplied, 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_patches` with the same qualified PR reference; do not run a shell `pr-shepherd apply` command.
 
@@ -51,7 +51,7 @@ annotations, or CI log excerpts.
 - 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 the generated thread IDs and flag placement unchanged. Viewer-authored human feedback may intentionally appear in both reply and resolve flags; unmarked other-human feedback remains reply-only. Marker-ended other-human feedback is already acknowledged and has no generated mutation.
+- Use the generated thread IDs and flag placement returned with the patch command.
 
 ### CI failure triage
 
@@ -77,16 +77,11 @@ When several bullets share one runId (matrix jobs from the same run), the `rerun
 
 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 remains a separate CLI-printed step because the command is unsafe by default without those placeholders.
 
-The CLI only includes IDs whose per-object GitHub viewer capability and semantic routing authorize the corresponding generated action. Direct `apply review` honors those emitted IDs without a second authorization preflight and surfaces GitHub's per-operation result. Do not reconstruct omitted review reply, thread resolution, or bot-review dismissal IDs and do not hand them off: denied or unverifiable generated mutations are one-look skips that Shepherd suppresses until the item is edited. Location is not required for generated reply/resolve mutations; unauthorized threads without a path or line remain one-look skips.
+The CLI only includes IDs whose per-object GitHub viewer capability and semantic routing authorize the corresponding generated action. Generated commands are pre-populated; omission is not a prohibition. A separate, user-directed `apply review` request may supply any reply, resolve, minimize, or dismiss IDs; it forwards them without Shepherd author, capability, or current-state filtering, and GitHub's per-operation response is authoritative.
 
-- 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 authorized 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.
+- When `## Instructions` says to run a generated `apply review:` / `resolve-only:` command, run it even when no code change is warranted. An `[ESCALATE]` instruction may require user direction first. The command records the agent's disposition of the included review items; skipping it leaves authorized threads active and can eventually trigger `fix-thrash`.
 - 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 both `## Review threads` and `## Review threads to resolve`, evaluate every thread before running mutations. Keep unmarked bot/non-human and viewer-authored IDs in both `--reply-thread-ids` and `--resolve-thread-ids`, including when the feedback is advisory, already satisfied, or otherwise warrants no code change: the reply runs before the resolve. Unmarked other-human IDs use `--reply-thread-ids` only unless the CLI also put them in `--resolve-thread-ids`. When the latest comment begins `<!-- pr-shepherd -->`, it is an established Shepherd reply—not merely a same-account comment. A marked thread that is still being resolved is resolve-only for retry. Do not add IDs the CLI omitted, and do not move IDs between flags.
-
 ### Shepherd Journal
 
 Link threads and comments in a journal entry from their headings in the CLI output. Cite reviews by ID.