pr-shepherd 0.48.0 → 0.50.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.48.0",
+  "version": "0.50.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -72,7 +72,7 @@ Conversations Resolved: No [Not Required]
 2. Apply every warranted review fix in each file referenced above.
 3. Triage every failure under `## Failing checks`. See "CI failure triage" in the pr-shepherd skill for read-only inspection rules.
 4. If you changed code, commit any remaining changes and push to the PR head branch, then run review mutations using the pushed commit SHA and iterate immediately with the same options. If you did not change code, do not commit and continue.
-5. Run the generated thread IDs unchanged. A latest comment beginning `<!-- pr-shepherd -->` is an earlier Shepherd reply: a marked thread that is still being resolved is emitted resolve-only when authorized.
+5. Substitute any command placeholders and run the generated review mutations.
 6. If you did not change code, replace `$HEAD_SHA` with `$(git rev-parse HEAD)`, which must equal the current remote PR head. If you changed code, commit and push to the PR head branch first, then replace `$HEAD_SHA` with the pushed commit SHA.
 7. Replace `$DISMISS_MESSAGE` with one sentence describing what changed.
 8. Run the `apply review:` command shown above. See "Review-mutation mechanics" in the pr-shepherd skill for dismiss-ID retention.
@@ -92,7 +92,7 @@ This system is opinionated and works best with PRs that use required status chec
 - Draft PRs can be marked ready automatically when clean; disable with `actions.autoMarkReady: false` or `--no-auto-mark-ready`.
 - With `--merge`, actionable review threads/comments/reviews/summaries are held back (`WAIT`, with raw deferred-work counts) while a PR sits in the merge queue, since a Shepherd-initiated push would eject it; set `actions.workWhileQueued: true` to act on them immediately instead. Failing checks and merge conflicts are never deferred.
 - The CLI never performs git mutations itself — it only emits commit/push instructions for the agent to run. Push access to the PR head is a usage precondition; GitHub viewer fields do not create a separate push-authorization handoff.
-- Generated iterate mutations and automatic actions are capability-aware and omit unauthorized commands. Explicit `apply` operations honor the caller's intent and surface GitHub's result; semantic human-content protections still apply.
+- Generated iterate mutations and automatic actions are capability-aware and omit unauthorized commands. Explicit `apply` operations forward the caller's requested IDs without iterate's author or capability policy and surface GitHub's result.
 - `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
@@ -135,8 +135,20 @@ pr-shepherd 42 --merge                  # request head-pinned auto-merge/queue;
 pr-shepherd iterate 42                 # single tick
 pr-shepherd owner/repo#42              # poll a PR in an explicit repository
 pr-shepherd https://github.com/owner/repo/pull/42
+pr-shepherd 42 43 44                   # summarize an explicit same-repository set
+pr-shepherd --stack 43                 # summarize every PR in a native GitHub stack
 ```
 
+Multi-PR and `--stack` polling use compact, read-only GraphQL summaries. They return when any row
+needs agent work, all rows are terminal, the bounded timeout expires, or `--until-terminal` crosses
+a configured GraphQL quota-warning band. Check counts use the same ignored, protected-run,
+superseded-run, and event rules as singular iteration and include active merge-queue commit checks.
+Bounded review/check overflow remains visible without permanently forcing work, and clean rows use
+the configured ready-delay before becoming terminal. Each actionable row includes
+an exact single-PR `pollCommand`; run independent actionable rows, then invoke the aggregate selector again.
+Stack rows are ordered bottom-to-top. API and MCP aggregate calls perform one summary tick and leave
+recurrence to the caller.
+
 Polling defaults can be set under `poll` in `.pr-shepherdrc.yml`: `intervalSeconds`, `timeoutSeconds`, `debounceSeconds`, and `quietStatus`. Explicit flags override configuration, including `--no-quiet-status` when a shared config enables quiet output. Quiet status remains off by default.
 
 ### Apply Review And Journal Changes, Or Select Files

package/bin/api.d.mts

@@ -1,16 +1,29 @@
 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 { BuildSuggestionPatchesResult, CommitSuggestionResult, IterateCommandOptions, IterateResult } from "./types.mts";
+import type { BuildSuggestionPatchesResult, CommitSuggestionResult, IterateCommandOptions, IterateResult, PollSummaryResult } from "./types.mts";
 export interface CreatePrShepherdOptions {
     /** Working directory used for git, config, and classification-rule lookups. */
     cwd?: string;
 }
 /** 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" | "targetRepository" | "persistSeen" | "fingerprintCache" | "deferQuotaWarning" | "quotaWarningMinimumPollIntervalMinutes"> & {
+type IterateOptions = Omit<IterateCommandOptions, "format" | "prNumber" | "targetRepository" | "persistSeen" | "fingerprintCache" | "deferQuotaWarning" | "quotaWarningMinimumPollIntervalMinutes">;
+export type SingleIterateInput = IterateOptions & {
     pr?: PrReference;
+    prs?: never;
+    stack?: never;
 };
+export type AggregateIterateInput = IterateOptions & ({
+    prs: PrReference[];
+    pr?: never;
+    stack?: never;
+} | {
+    stack: PrReference;
+    pr?: never;
+    prs?: never;
+});
+export type IterateInput = SingleIterateInput | AggregateIterateInput;
 export interface ReviewMutationsOperation {
     type: "review_mutations";
     resolveThreadIds?: string[];
@@ -69,7 +82,9 @@ export interface BuildSuggestionPatchesInput {
     suggestions: SuggestionPatchInput[];
 }
 export interface PrShepherd {
-    iterate(input?: IterateInput): Promise<IterateResult>;
+    iterate(input?: SingleIterateInput): Promise<IterateResult>;
+    iterate(input: AggregateIterateInput): Promise<PollSummaryResult>;
+    iterate(input: IterateInput): Promise<IterateResult | PollSummaryResult>;
     apply(input: ApplyInput): Promise<ApplyResult>;
     buildSuggestionPatches(input: BuildSuggestionPatchesInput): Promise<BuildSuggestionPatchesResult>;
     /** Compatibility adapter; prefer buildSuggestionPatches. */
@@ -90,3 +105,4 @@ export declare class PartialApplyError extends Error {
  * read/plan, ordered apply, and suggestion-patch operations.
  */
 export declare function createPrShepherd(options?: CreatePrShepherdOptions): PrShepherd;
+export {};

package/bin/api.mjs

@@ -3,12 +3,14 @@ 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 { runPollSummary } from "./commands/poll-summary.mjs";
 import { runJournal } from "./commands/journal/index.mjs";
 import { validateJournalItem } from "./commands/journal/transform.mjs";
 import { runMarkFilesAsViewed, } from "./commands/mark-files-as-viewed.mjs";
 import { runResolveMutate } from "./commands/resolve-mutate.mjs";
 import { runWithExecutionCwd } from "./execution-context.mjs";
-import { parsePrReference, resolveParsedPrTarget, } from "./pr-reference.mjs";
+import { parsePrReference, normalizeRepositoryIdentity, resolveParsedPrTarget, } from "./pr-reference.mjs";
+import { getRepoInfo } from "./github/client.mjs";
 /** Raised before any API mutation when an input cannot be validated. */
 export class PrShepherdValidationError extends Error {
     constructor(message) {
@@ -34,14 +36,20 @@ export class PartialApplyError extends Error {
  */
 export function createPrShepherd(options = {}) {
     const cwd = options.cwd === undefined ? undefined : resolve(options.cwd);
+    function iterate(input = {}) {
+        return runWithExecutionCwd(cwd, async () => {
+            validateIterateSelectors(input);
+            if ("prs" in input || "stack" in input) {
+                const target = await resolveAggregateIterateInput(input);
+                return runPollSummary(target);
+            }
+            const { pr: _pr, ...iterateOptions } = input;
+            const target = resolvePrReference(input.pr);
+            return runIterate({ ...iterateOptions, ...target, format: "json" });
+        });
+    }
     return Object.freeze({
-        iterate(input = {}) {
-            const { pr: _pr, ...options } = input;
-            return runWithExecutionCwd(cwd, async () => {
-                const target = resolvePrReference(input.pr);
-                return runIterate({ ...options, ...target, format: "json" });
-            });
-        },
+        iterate,
         apply(input) {
             return runWithExecutionCwd(cwd, async () => {
                 validateApplyInput(input);
@@ -114,6 +122,47 @@ export function createPrShepherd(options = {}) {
         },
     });
 }
+async function resolveAggregateIterateInput(input) {
+    const refs = "prs" in input ? input.prs : [input.stack];
+    if (!refs || refs.length === 0) {
+        throw new PrShepherdValidationError("iterate.prs must contain at least one PR reference");
+    }
+    const parsedRefs = refs.map((ref) => {
+        const parsed = parsePrReference(ref);
+        const prNumber = parsed?.number;
+        if (!parsed || !prNumber) {
+            throw new PrShepherdValidationError(`Invalid PR reference: ${String(ref)}`);
+        }
+        return { parsed, prNumber };
+    });
+    const checkout = parsedRefs.some(({ parsed }) => parsed?.repository === undefined)
+        ? await getRepoInfo()
+        : undefined;
+    let repository;
+    const numbers = [];
+    for (const { parsed, prNumber } of parsedRefs) {
+        const target = resolveParsedPrTarget(parsed);
+        const nextRepository = target.targetRepository ?? checkout;
+        if (repository &&
+            normalizeRepositoryIdentity(`${repository.owner}/${repository.name}`) !==
+                normalizeRepositoryIdentity(`${nextRepository.owner}/${nextRepository.name}`)) {
+            throw new PrShepherdValidationError("aggregate iterate only supports PRs from one repository");
+        }
+        repository = nextRepository;
+        if (!numbers.includes(prNumber))
+            numbers.push(prNumber);
+    }
+    const { pr: _pr, prs: _prs, stack: _stack, ...options } = input;
+    return "prs" in input
+        ? { ...options, prNumbers: numbers, targetRepository: repository }
+        : { ...options, stackPrNumber: numbers[0], targetRepository: repository };
+}
+function validateIterateSelectors(input) {
+    const selectorCount = ["pr", "prs", "stack"].filter((key) => key in input).length;
+    if (selectorCount > 1) {
+        throw new PrShepherdValidationError("iterate pr, prs, and stack selectors are mutually exclusive");
+    }
+}
 function validateApplyInput(input) {
     if (!input || !Array.isArray(input.operations) || input.operations.length === 0) {
         throw new PrShepherdValidationError("apply requires a non-empty operations array");

package/bin/classify/apply.d.mts

@@ -1,4 +1,5 @@
 import type { BatchPrData } from "../types.mts";
+import type { ClassifyItem, ClassifyAction } from "./types.mts";
 import type { LoadedRule } from "./loader.mts";
 export interface ClassifyIndex {
     suppressedIds: Set<string>;
@@ -14,5 +15,6 @@ export interface BatchPartition {
     /** COMMENTED review summary IDs — minimized without surfacing to the agent. */
     ruleAutoResolveReviewSummaryIds: string[];
 }
+export declare function applyRules(rules: LoadedRule[], item: ClassifyItem): ClassifyAction;
 export declare function buildClassifyIndex(rules: LoadedRule[], batch: BatchPrData): ClassifyIndex;
 export declare function partitionBatch(index: ClassifyIndex, batch: BatchPrData): BatchPartition;

package/bin/classify/apply.mjs

@@ -1,4 +1,4 @@
-function applyRules(rules, item) {
+export function applyRules(rules, item) {
     let autoResolve = false;
     let suppress = false;
     for (const { rule, name } of rules) {

package/bin/cli/default-poll.mjs

@@ -9,6 +9,7 @@ const DEFAULT_POLL_FLAGS_WITH_VALUES = new Set([
     "--interval",
     "--timeout",
     "--debounce",
+    "--stack",
 ]);
 const DEFAULT_POLL_BOOLEAN_FLAGS = new Set([
     "--verbose",

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

@@ -14,7 +14,8 @@ Run 'pr-shepherd apply <review|files|journal> --help' for command-specific detai
 --help, -h                      Print this help and exit before GitHub I/O.`;
     readonly "apply review": `pr-shepherd apply review
 
-Apply GitHub review-state mutations after fixes.
+Apply user-directed GitHub review-state mutations after fixes. Supplied IDs are forwarded to GitHub;
+GitHub accepts or rejects each mutation.
 
 Usage:
   pr-shepherd apply review [PR] --reply-thread-ids A,B --message MSG
@@ -24,10 +25,9 @@ Usage:
 
 Flags:
   --resolve-thread-ids <ids>      Comma-separated review thread IDs (PRRT_*) to resolve.
-                                  Human-authored thread IDs are skipped; use --reply-thread-ids.
-  --reply-thread-ids <ids>        Comma-separated human review thread IDs to reply to.
+  --reply-thread-ids <ids>        Comma-separated review thread IDs to reply to.
   --minimize-comment-ids <ids>    Comma-separated issue/review comment IDs to minimize.
-  --dismiss-review-ids <ids>      Comma-separated CHANGES_REQUESTED review IDs to dismiss.
+  --dismiss-review-ids <ids>      Comma-separated review IDs to dismiss.
   --message <text>                Reply/dismiss message. Required with reply or dismiss IDs.
   --require-sha <sha>             Wait for this full 40-character lowercase PR head SHA.
   --format text|json              Output format. Default: text.
@@ -121,7 +121,8 @@ Use --dry-run to preview paths without removing them.
     readonly "admin log-file": string;
     readonly resolve: `pr-shepherd resolve
 
-Apply GitHub review-state mutations after fixes.
+Deprecated compatibility alias for user-directed GitHub review-state mutations. Supplied IDs are forwarded to GitHub;
+GitHub accepts or rejects each mutation.
 
 Usage:
   pr-shepherd resolve [PR] --reply-thread-ids A,B --message MSG
@@ -131,11 +132,10 @@ Usage:
 
 Flags:
   --resolve-thread-ids <ids>      Comma-separated review thread IDs (PRRT_*) to resolve.
-                                  Human-authored thread IDs are skipped; use --reply-thread-ids.
                                   Note: comment IDs (PRRC_*) from gh api are not thread IDs and will fail.
-  --reply-thread-ids <ids>        Comma-separated human review thread IDs to reply to.
+  --reply-thread-ids <ids>        Comma-separated review thread IDs to reply to.
   --minimize-comment-ids <ids>    Comma-separated issue/review comment IDs to minimize.
-  --dismiss-review-ids <ids>      Comma-separated CHANGES_REQUESTED review IDs to dismiss.
+  --dismiss-review-ids <ids>      Comma-separated review IDs to dismiss.
   --message <text>                Reply/dismiss message. Required with --reply-thread-ids
                                   or --dismiss-review-ids.
   --require-sha <sha>             Wait until GitHub reports this PR head SHA before mutating.
@@ -194,7 +194,7 @@ Flags:
 PR may be a number or GitHub pull request URL. When omitted, the current branch PR is inferred.
 Exit code: 0 on success; nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
     readonly iterate: "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n  MERGE       Run the emitted merge/queue command, then continue monitoring.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
-    readonly poll: "pr-shepherd poll\n\nRun iterate repeatedly for WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal or --merge, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR] [poll-flags] [iterate-flags]\n\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes an explicit still-running line to stderr by default; poll.quietStatus can change that default, --quiet-status/--no-quiet-status override it, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+    readonly poll: "pr-shepherd poll\n\nRun iterate repeatedly for one PR, or read compact summaries for an explicit PR set or native\nGitHub stack. Aggregate mode returns when any row needs work, every row is terminal, or timeout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default:\npoll.debounceSeconds; built-in 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal or --merge, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR ...] [poll-flags] [iterate-flags]\n  pr-shepherd poll --stack PR [poll-flags] [iterate-flags]\n\nPoll flags:\n  --stack PR                    Select all entries in PR's native GitHub stack, bottom to top.\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes an explicit still-running line to stderr by default; poll.quietStatus can change that default, --quiet-status/--no-quiet-status override it, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
     readonly clean: `pr-shepherd clean
 
 Remove pr-shepherd state files from PR_SHEPHERD_STATE_DIR.

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

@@ -17,7 +17,8 @@ Run 'pr-shepherd apply <review|files|journal> --help' for command-specific detai
 --help, -h                      Print this help and exit before GitHub I/O.`,
     "apply review": `pr-shepherd apply review
 
-Apply GitHub review-state mutations after fixes.
+Apply user-directed GitHub review-state mutations after fixes. Supplied IDs are forwarded to GitHub;
+GitHub accepts or rejects each mutation.
 
 Usage:
   pr-shepherd apply review [PR] --reply-thread-ids A,B --message MSG
@@ -27,10 +28,9 @@ Usage:
 
 Flags:
   --resolve-thread-ids <ids>      Comma-separated review thread IDs (PRRT_*) to resolve.
-                                  Human-authored thread IDs are skipped; use --reply-thread-ids.
-  --reply-thread-ids <ids>        Comma-separated human review thread IDs to reply to.
+  --reply-thread-ids <ids>        Comma-separated review thread IDs to reply to.
   --minimize-comment-ids <ids>    Comma-separated issue/review comment IDs to minimize.
-  --dismiss-review-ids <ids>      Comma-separated CHANGES_REQUESTED review IDs to dismiss.
+  --dismiss-review-ids <ids>      Comma-separated review IDs to dismiss.
   --message <text>                Reply/dismiss message. Required with reply or dismiss IDs.
   --require-sha <sha>             Wait for this full 40-character lowercase PR head SHA.
   --format text|json              Output format. Default: text.
@@ -124,7 +124,8 @@ Use --dry-run to preview paths without removing them.
     "admin log-file": LOG_FILE_USAGE.replaceAll("pr-shepherd log-file", "pr-shepherd admin log-file"),
     resolve: `pr-shepherd resolve
 
-Apply GitHub review-state mutations after fixes.
+Deprecated compatibility alias for user-directed GitHub review-state mutations. Supplied IDs are forwarded to GitHub;
+GitHub accepts or rejects each mutation.
 
 Usage:
   pr-shepherd resolve [PR] --reply-thread-ids A,B --message MSG
@@ -134,11 +135,10 @@ Usage:
 
 Flags:
   --resolve-thread-ids <ids>      Comma-separated review thread IDs (PRRT_*) to resolve.
-                                  Human-authored thread IDs are skipped; use --reply-thread-ids.
                                   Note: comment IDs (PRRC_*) from gh api are not thread IDs and will fail.
-  --reply-thread-ids <ids>        Comma-separated human review thread IDs to reply to.
+  --reply-thread-ids <ids>        Comma-separated review thread IDs to reply to.
   --minimize-comment-ids <ids>    Comma-separated issue/review comment IDs to minimize.
-  --dismiss-review-ids <ids>      Comma-separated CHANGES_REQUESTED review IDs to dismiss.
+  --dismiss-review-ids <ids>      Comma-separated review IDs to dismiss.
   --message <text>                Reply/dismiss message. Required with --reply-thread-ids
                                   or --dismiss-review-ids.
   --require-sha <sha>             Wait until GitHub reports this PR head SHA before mutating.

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

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

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

@@ -37,17 +37,20 @@ Exit codes:
   A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).`;
 export const POLL_USAGE = `pr-shepherd poll
 
-Run iterate repeatedly for WAIT ticks and during the FIX_CODE debounce window. Print only the
-final tick to stdout.
+Run iterate repeatedly for one PR, or read compact summaries for an explicit PR set or native
+GitHub stack. Aggregate mode returns when any row needs work, every row is terminal, or timeout.
 Poll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout
-returns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps
+returns the last WAIT result. FIX_CODE starts a --debounce settle window (default:
+poll.debounceSeconds; built-in 1m): poll keeps
 iterating at --interval, then runs one more tick after the window and returns that result.
 With --until-terminal or --merge, poll also continues through MARK_READY.
 
 Usage:
-  pr-shepherd poll [PR] [poll-flags] [iterate-flags]
+  pr-shepherd poll [PR ...] [poll-flags] [iterate-flags]
+  pr-shepherd poll --stack PR [poll-flags] [iterate-flags]
 
 Poll flags:
+  --stack PR                    Select all entries in PR's native GitHub stack, bottom to top.
   --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).
   --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).
   --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.
@@ -82,4 +85,6 @@ Exit codes: same as iterate (the final tick's action/reason decides the code).
   15  MERGE
   A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).`;
 /** Public help page for the default PR polling invocation. */
-export const DEFAULT_USAGE = POLL_USAGE.replace(/^pr-shepherd poll$/m, "pr-shepherd [PR]").replace(/^ {2}pr-shepherd poll \[PR\]/m, "  pr-shepherd [PR]");
+export const DEFAULT_USAGE = POLL_USAGE.replace(/^pr-shepherd poll$/m, "pr-shepherd [PR]")
+    .replace(/^ {2}pr-shepherd poll \[PR \.\.\.\]/m, "  pr-shepherd [PR ...]")
+    .replace(/^ {2}pr-shepherd poll --stack/m, "  pr-shepherd --stack");

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 journal extract --body-file <path>\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 selected changed files as viewed.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.\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    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\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)\n  15  MERGE\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 --stack 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 journal extract --body-file <path>\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 one PR, an explicit same-repository set, or a native stack.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark selected changed files as viewed.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.\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, owner/repo#number, or a GitHub pull request URL.\n  Multiple PRs must name one repository. --stack PR selects every entry in PR's native stack.\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    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\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)\n  15  MERGE\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

@@ -5,7 +5,8 @@ Autonomous PR CI monitor and review-comment resolver for agentic coding tools.
 Usage:
   pr-shepherd --version | -v
   pr-shepherd --help | -h
-  pr-shepherd [PR] [poll-flags] [iterate-flags]
+  pr-shepherd [PR ...] [poll-flags] [iterate-flags]
+  pr-shepherd --stack PR [poll-flags] [iterate-flags]
   pr-shepherd iterate [PR] [iterate-flags]
   pr-shepherd apply review [PR] [review-flags]
   pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]
@@ -16,7 +17,7 @@ Usage:
   pr-shepherd admin log-file [--format text|json]
 
 Commands:
-  [PR]                 Poll until non-WAIT or timeout. This is the default command.
+  [PR ...]             Poll one PR, an explicit same-repository set, or a native stack.
   iterate              Run one iterate tick (single-tick alias).
   apply review         Apply review-state mutations after fixes.
   apply files          Mark selected changed files as viewed.
@@ -28,7 +29,8 @@ Commands:
   admin log-file       Print the per-worktree debug log path.
 
 PR argument:
-  PR may be a number such as 42 or a GitHub pull request URL.
+  PR may be a number, owner/repo#number, or a GitHub pull request URL.
+  Multiple PRs must name one repository. --stack PR selects every entry in PR's native stack.
   When omitted, pr-shepherd infers the current branch's pull request.
 
 Common flags:

package/bin/cli/help.d.mts

@@ -14,7 +14,8 @@ Run 'pr-shepherd apply <review|files|journal> --help' for command-specific detai
 --help, -h                      Print this help and exit before GitHub I/O.`;
     readonly "apply review": `pr-shepherd apply review
 
-Apply GitHub review-state mutations after fixes.
+Apply user-directed GitHub review-state mutations after fixes. Supplied IDs are forwarded to GitHub;
+GitHub accepts or rejects each mutation.
 
 Usage:
   pr-shepherd apply review [PR] --reply-thread-ids A,B --message MSG
@@ -24,10 +25,9 @@ Usage:
 
 Flags:
   --resolve-thread-ids <ids>      Comma-separated review thread IDs (PRRT_*) to resolve.
-                                  Human-authored thread IDs are skipped; use --reply-thread-ids.
-  --reply-thread-ids <ids>        Comma-separated human review thread IDs to reply to.
+  --reply-thread-ids <ids>        Comma-separated review thread IDs to reply to.
   --minimize-comment-ids <ids>    Comma-separated issue/review comment IDs to minimize.
-  --dismiss-review-ids <ids>      Comma-separated CHANGES_REQUESTED review IDs to dismiss.
+  --dismiss-review-ids <ids>      Comma-separated review IDs to dismiss.
   --message <text>                Reply/dismiss message. Required with reply or dismiss IDs.
   --require-sha <sha>             Wait for this full 40-character lowercase PR head SHA.
   --format text|json              Output format. Default: text.
@@ -121,7 +121,8 @@ Use --dry-run to preview paths without removing them.
     readonly "admin log-file": string;
     readonly resolve: `pr-shepherd resolve
 
-Apply GitHub review-state mutations after fixes.
+Deprecated compatibility alias for user-directed GitHub review-state mutations. Supplied IDs are forwarded to GitHub;
+GitHub accepts or rejects each mutation.
 
 Usage:
   pr-shepherd resolve [PR] --reply-thread-ids A,B --message MSG
@@ -131,11 +132,10 @@ Usage:
 
 Flags:
   --resolve-thread-ids <ids>      Comma-separated review thread IDs (PRRT_*) to resolve.
-                                  Human-authored thread IDs are skipped; use --reply-thread-ids.
                                   Note: comment IDs (PRRC_*) from gh api are not thread IDs and will fail.
-  --reply-thread-ids <ids>        Comma-separated human review thread IDs to reply to.
+  --reply-thread-ids <ids>        Comma-separated review thread IDs to reply to.
   --minimize-comment-ids <ids>    Comma-separated issue/review comment IDs to minimize.
-  --dismiss-review-ids <ids>      Comma-separated CHANGES_REQUESTED review IDs to dismiss.
+  --dismiss-review-ids <ids>      Comma-separated review IDs to dismiss.
   --message <text>                Reply/dismiss message. Required with --reply-thread-ids
                                   or --dismiss-review-ids.
   --require-sha <sha>             Wait until GitHub reports this PR head SHA before mutating.
@@ -194,7 +194,7 @@ Flags:
 PR may be a number or GitHub pull request URL. When omitted, the current branch PR is inferred.
 Exit code: 0 on success; nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
     readonly iterate: "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).\n\nActions:\n  WAIT        No immediate action; continue with the next poll.\n  MARK_READY  Draft PR was marked ready; continue with the next poll.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n  MERGE       Run the emitted merge/queue command, then continue monitoring.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
-    readonly poll: "pr-shepherd poll\n\nRun iterate repeatedly for WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal or --merge, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR] [poll-flags] [iterate-flags]\n\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes an explicit still-running line to stderr by default; poll.quietStatus can change that default, --quiet-status/--no-quiet-status override it, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+    readonly poll: "pr-shepherd poll\n\nRun iterate repeatedly for one PR, or read compact summaries for an explicit PR set or native\nGitHub stack. Aggregate mode returns when any row needs work, every row is terminal, or timeout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default:\npoll.debounceSeconds; built-in 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal or --merge, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR ...] [poll-flags] [iterate-flags]\n  pr-shepherd poll --stack PR [poll-flags] [iterate-flags]\n\nPoll flags:\n  --stack PR                    Select all entries in PR's native GitHub stack, bottom to top.\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --format text|json             Output Markdown text or JSON. Default: text.\n  --verbose                      Include verbose iterate fields and detailed per-tick lines.\n  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.\n\nDurations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds\nfor --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with\nan explicit unit (4.5m).\nEach WAIT tick writes an explicit still-running line to stderr by default; poll.quietStatus can change that default, --quiet-status/--no-quiet-status override it, and --verbose emits detailed per-tick lines.\nFIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.\nWith --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, MERGE, CANCEL, or ESCALATE. With --merge, --timeout still bounds WAIT ticks; it only continues through MARK_READY while polling remains within that timeout.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
     readonly clean: `pr-shepherd clean
 
 Remove pr-shepherd state files from PR_SHEPHERD_STATE_DIR.
@@ -258,7 +258,7 @@ On POSIX, the final body-file path entry must be a readable regular file in a tr
 symlinks, FIFOs, devices, and unreadable paths exit 66. Unsupported platforms fail closed with exit 66.
 --help, -h                      Print this help and exit before any I/O.`;
     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 journal extract --body-file <path>\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 selected changed files as viewed.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.\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    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\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)\n  15  MERGE\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 --stack 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 journal extract --body-file <path>\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 one PR, an explicit same-repository set, or a native stack.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark selected changed files as viewed.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.\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, owner/repo#number, or a GitHub pull request URL.\n  Multiple PRs must name one repository. --stack PR selects every entry in PR's native stack.\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    Legacy no-op; workflow runs are never cancelled.\n  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s).\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.\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)\n  15  MERGE\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/iterate-instructions.mjs

@@ -38,8 +38,15 @@ export function buildSimpleIterateInstructions(result) {
         }
         case "cancel":
             return ["Stop — the PR loop is complete. No further polling is needed."];
-        case "escalate":
-            return ["Stop — human direction is required before automated polling can resume."];
+        case "escalate": {
+            const pending = result.escalate.pendingReviewCommands;
+            if (!pending)
+                return ["Stop — human direction is required before automated polling can resume."];
+            return [
+                "Stop polling. Ask the user whether to run the pending review commands shown above.",
+                "If yes, replace any `$HEAD_SHA` with the full 40-character pushed PR-head SHA and any `$DISMISS_MESSAGE` with a one-sentence disposition, run every pending command, then rerun Shepherd with the same options.",
+            ];
+        }
     }
 }
 export function adaptIterateLog(log) {

package/bin/cli/iterate-lean.mjs

@@ -160,6 +160,14 @@ export function projectIterateLean(result, opts) {
                     ...(result.escalate.changesRequestedReviews.length > 0 && {
                         changesRequestedReviews: result.escalate.changesRequestedReviews,
                     }),
+                    ...(result.escalate.firstLookSummaries &&
+                        result.escalate.firstLookSummaries.length > 0 && {
+                        firstLookSummaries: result.escalate.firstLookSummaries,
+                    }),
+                    ...(result.escalate.editedSummaries &&
+                        result.escalate.editedSummaries.length > 0 && {
+                        editedSummaries: result.escalate.editedSummaries,
+                    }),
                     ...(result.escalate.checks &&
                         result.escalate.checks.length > 0 && {
                         checks: result.escalate.checks,
@@ -182,6 +190,9 @@ export function projectIterateLean(result, opts) {
                         result.escalate.authorization.length > 0 && {
                         authorization: result.escalate.authorization,
                     }),
+                    ...(result.escalate.pendingReviewCommands && {
+                        pendingReviewCommands: result.escalate.pendingReviewCommands,
+                    }),
                     suggestion: result.escalate.suggestion,
                     humanMessage: result.escalate.humanMessage,
                 },