pr-shepherd 0.56.6 → 0.57.0

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 --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 apply check-blocker [PR] --check <name> (--blocked-by <ref>|--clear)\n  pr-shepherd apply queue-removal [PR] --require-sha <head> --queue-commit <commit> --removed-at <unix>\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  apply check-blocker  Record that a failing check is blocked on an external PR or issue.\n  apply queue-removal  Acknowledge one current CI-driven native-stack queue removal.\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). Stack and multi-PR polls multiply that by poll.stackIntervalFactor (built-in 2) unless this flag is set.\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 or stack SHEPHERD 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 READY/FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\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 or READY\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\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 merge [PR] --require-sha SHA --merge-action ACTION --transport rest\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 apply check-blocker [PR] --check <name> (--blocked-by <ref>|--clear)\n  pr-shepherd apply queue-removal [PR] --require-sha <head> --queue-commit <commit> --removed-at <unix>\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 merge          Submit or resume a guarded asynchronous merge or enqueue request.\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  apply check-blocker  Record that a failing check is blocked on an external PR or issue.\n  apply queue-removal  Acknowledge one current CI-driven native-stack queue removal.\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  playbook             Print a playbook named by an instruction pointer.\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  --transport auto|graphql|rest  Select GitHub transport. Default: github.transport (auto).\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  --instructions playbook|inline Render fix_code steps inline every tick (default) or fold the invariant ones into a playbook pointer. Default: iterate.instructions (inline).\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stackIntervalFactor (built-in 2) unless this flag is set.\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 or stack SHEPHERD 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 READY/FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\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 or READY\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\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

@@ -8,6 +8,7 @@ Usage:
   pr-shepherd [PR ...] [poll-flags] [iterate-flags]
   pr-shepherd --stack PR [poll-flags] [iterate-flags]
   pr-shepherd iterate [PR] [iterate-flags]
+  pr-shepherd apply merge [PR] --require-sha SHA --merge-action ACTION --transport rest
   pr-shepherd apply review [PR] [review-flags]
   pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]
   pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]
@@ -21,6 +22,7 @@ Usage:
 Commands:
   [PR ...]             Poll one PR, an explicit same-repository set, or a native stack.
   iterate              Run one iterate tick (single-tick alias).
+  apply merge          Submit or resume a guarded asynchronous merge or enqueue request.
   apply review         Apply review-state mutations after fixes.
   apply files          Mark selected changed files as viewed.
   apply journal        Append a list item to the Shepherd Journal details block of a PR body.
@@ -29,6 +31,7 @@ Commands:
   journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.
   build-suggestion-patches
                        Convert ordered GitHub suggestion threads into patches and commit instructions.
+  playbook             Print a playbook named by an instruction pointer.
   admin clean          Remove pr-shepherd state files.
   admin log-file       Print the per-worktree debug log path.
 
@@ -38,6 +41,7 @@ PR argument:
   When omitted, pr-shepherd infers the current branch's pull request.
 
 Common flags:
+  --transport auto|graphql|rest  Select GitHub transport. Default: github.transport (auto).
   --format text|json   Output Markdown text or JSON. Default: text.
   --verbose            Include verbose iterate fields and detailed poll-tick lines.
   --help, -h           Print help and exit before any GitHub, git, config, or log I/O.
@@ -48,6 +52,7 @@ Iterate flags:
   --no-auto-mark-ready           Do not convert draft PRs to ready for review.
   --no-auto-cancel-actionable    Legacy no-op; workflow runs are never cancelled.
   --merge                        Shepherd through readiness, then emit a merge or merge-queue command.
+  --instructions playbook|inline Render fix_code steps inline every tick (default) or fold the invariant ones into a playbook pointer. Default: iterate.instructions (inline).
 
 Polling flags:
   --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stackIntervalFactor (built-in 2) unless this flag is set.

package/bin/cli/help.d.mts

@@ -1,10 +1,29 @@
 export declare const USAGE: {
     readonly default: string;
+    readonly "apply merge": `pr-shepherd apply merge
+
+Submit one SHA-guarded asynchronous merge or enqueue request with REST.
+Rerun the same command to resume its persisted UUID. Pending and enqueued requests are not merged.
+An enqueued result records that request's outcome; it does not confirm current queue membership.
+An uncertain submission is never repeated automatically.
+
+Usage:
+  pr-shepherd apply merge [PR] --require-sha SHA --merge-action direct_merge|merge_queue|default
+    [--method merge|squash|rebase] [--expected-stack JSON] --transport rest [--format text|json]
+
+--require-sha <sha>             Full 40-character lowercase PR head SHA.
+--merge-action <action>         direct_merge, merge_queue, or default.
+--method <method>               Optional merge method, only for direct_merge.
+--expected-stack <json>         Bind native stack number, baseRefName, and ordered prefix PRs/refs/head SHAs.
+--transport rest               Required REST transport; repository rules are never bypassed.
+--format text|json              Output format. Default: text.
+--help, -h                     Print this help before validation or I/O.`;
     readonly apply: `pr-shepherd apply
 
 Apply review mutations, mark selected changed files as viewed, append a PR journal item, or record an external check blocker.
 
 Usage:
+  pr-shepherd apply merge [PR] --require-sha SHA --merge-action ACTION --transport rest
   pr-shepherd apply review [PR] [review-flags]
   pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]
   pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]
@@ -13,7 +32,7 @@ Usage:
   pr-shepherd apply check-blocker [PR] --check <name> --clear
   pr-shepherd apply queue-removal [PR] --require-sha <head> --queue-commit <commit> --removed-at <unix>
 
-Run 'pr-shepherd apply <review|files|journal|check-blocker|queue-removal> --help' for command-specific details.
+Run 'pr-shepherd apply <merge|review|files|journal|check-blocker|queue-removal> --help' for command-specific details.
 --help, -h                      Print this help and exit before GitHub I/O.`;
     readonly "apply review": `pr-shepherd apply review
 
@@ -32,7 +51,11 @@ Flags:
   --minimize-comment-ids <ids>    Comma-separated issue/review comment IDs to minimize.
   --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.
+  --require-sha <sha>             Wait for this full 40-character lowercase PR head SHA, or HEAD
+                                  for this checkout's commit.
+  --adopt-existing-replies        Generated durable-state commands only: count a thread whose last
+                                  comment is already this exact Shepherd reply from you as replied
+                                  instead of posting it again. Omit it to forward every reply ID.
   --format text|json              Output format. Default: text.
 
 At least one action flag is required.
@@ -143,14 +166,16 @@ Run 'pr-shepherd admin <clean|log-file> --help' for command-specific details.
 Remove pr-shepherd state files from PR_SHEPHERD_STATE_DIR.
 
 Usage:
-  pr-shepherd admin clean pr [number] [--dry-run] [--format text|json]
-  pr-shepherd admin clean branch [name] [--dry-run] [--format text|json]
-  pr-shepherd admin clean current [--dry-run] [--format text|json]
-  pr-shepherd admin clean repo [--dry-run] [--format text|json]
-  pr-shepherd admin clean all [--dry-run] [--format text|json]
+  pr-shepherd admin clean pr [number] [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
+  pr-shepherd admin clean branch [name] [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
+  pr-shepherd admin clean current [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
+  pr-shepherd admin clean repo [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
+  pr-shepherd admin clean all [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
 
 Variants remove state for one PR, branch, current branch, repository, or all repositories.
 Use --dry-run to preview paths without removing them.
+--poll-mode auto|poll|event      Clean the state for that poll mode; event mode keeps it in durable
+                                state under the git common directory. Default: poll.mode (auto).
 --help, -h                      Print this help and exit before any cleanup.`;
     readonly "admin log-file": string;
     readonly resolve: `pr-shepherd resolve
@@ -172,9 +197,10 @@ Flags:
   --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.
-                                  Must be a full 40-character lowercase hex SHA. Local HEAD is valid
-                                  only when it equals the current remote PR head.
+  --require-sha <sha>             Wait until GitHub reports this PR head SHA (or HEAD) before mutating.
+                                  Must be a full 40-character lowercase hex SHA, or HEAD for this
+                                  checkout's commit. Local HEAD is valid only when it equals the
+                                  current remote PR head.
   --format text|json              Output format. Default: text.
   --help, -h                      Print this help and exit before GitHub I/O.
 
@@ -227,18 +253,18 @@ 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  READY       Clean PR is inside the ready-delay. Schedule the rerun for when remainingSeconds elapses. Do not invent unrelated work. Already-owned later work may continue.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling this pull request: merged/closed or ready-delay elapsed. Continue remaining work from the original request.\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 or READY\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 READY, 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). Stack and multi-PR polls multiply that by poll.stackIntervalFactor (built-in 2) unless this flag is set.\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 or stack SHEPHERD 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 READY/FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\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 a stderr line naming what it is waiting on 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 READY, 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 or READY (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  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (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  --instructions playbook|inline Render fix_code steps inline every tick (default) or fold the invariant ones into a playbook pointer. Default: iterate.instructions (inline).\n  --poll-mode auto|poll|event    event runs one tick, never sleeps, and prints nextCheck; auto picks event when CLAUDE_CODE_REMOTE=true. Default: poll.mode (auto).\n  --transport auto|graphql|rest  Select GitHub transport. Default: github.transport (auto).\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  READY       Clean PR is inside the ready-delay. Schedule the rerun for when remainingSeconds elapses. Do not invent unrelated work. Already-owned later work may continue.\n  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling this pull request: merged/closed or ready-delay elapsed. Continue remaining work from the original request.\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 or READY\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 READY, 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). Stack and multi-PR polls multiply that by poll.stackIntervalFactor (built-in 2) unless this flag is set.\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 or stack SHEPHERD 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 READY/FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\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  --instructions playbook|inline Render fix_code steps inline every tick (default) or fold the invariant ones into a playbook pointer. Default: iterate.instructions (inline).\n  --poll-mode auto|poll|event    event runs one tick, never sleeps, and prints nextCheck; auto picks event when CLAUDE_CODE_REMOTE=true. Default: poll.mode (auto).\n  --transport auto|graphql|rest  Select GitHub transport. Default: github.transport (auto).\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 a stderr line naming what it is waiting on 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 READY, 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 or READY (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  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\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.
 
 Usage:
-  pr-shepherd clean pr [number] [--dry-run] [--format text|json]
-  pr-shepherd clean branch [name] [--dry-run] [--format text|json]
-  pr-shepherd clean current [--dry-run] [--format text|json]
-  pr-shepherd clean repo [--dry-run] [--format text|json]
-  pr-shepherd clean all [--dry-run] [--format text|json]
+  pr-shepherd clean pr [number] [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
+  pr-shepherd clean branch [name] [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
+  pr-shepherd clean current [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
+  pr-shepherd clean repo [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
+  pr-shepherd clean all [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
 
 Variants:
   pr [number]          Remove state for one PR. Defaults to current branch PR.
@@ -251,6 +277,9 @@ Variants:
 Flags:
   --dry-run            Preview paths without removing them.
   --format text|json   Output format. Default: text.
+  --poll-mode auto|poll|event
+                       Clean the state for that poll mode; event mode keeps it in durable
+                       state under the git common directory. Default: poll.mode (auto).
   --help, -h           Print this help and exit before any cleanup.
 
 Exit code: 0 on success (including a no-op --dry-run on a nonexistent target); nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
@@ -291,8 +320,23 @@ Malformed or unrecognized journal content is returned as {"ok":false,...} with e
 On POSIX, the final body-file path entry must be a readable regular file in a trusted parent directory;
 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 --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 apply check-blocker [PR] --check <name> (--blocked-by <ref>|--clear)\n  pr-shepherd apply queue-removal [PR] --require-sha <head> --queue-commit <commit> --removed-at <unix>\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  apply check-blocker  Record that a failing check is blocked on an external PR or issue.\n  apply queue-removal  Acknowledge one current CI-driven native-stack queue removal.\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). Stack and multi-PR polls multiply that by poll.stackIntervalFactor (built-in 2) unless this flag is set.\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 or stack SHEPHERD 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 READY/FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\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 or READY\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\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 playbook: `pr-shepherd playbook
+
+Print a playbook named by a playbook pointer in the output's ## Instructions. Playbooks ship with the
+package, so this works without the pr-shepherd skill installed. With no name, lists every playbook.
+This command performs no GitHub, git, or log I/O.
+
+Usage:
+  pr-shepherd playbook [name] [--format text|json]
+
+Flags:
+  --format text|json   Markdown text (default) or one JSON line: {"name","content"} or {"playbooks":[...]}.
+
+The name is case-insensitive; spaces and hyphens are equivalent ("Fix-code loop" and fix-code-loop match).
+Unknown names exit 64 and list the available playbooks.
+--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] [--poll-mode auto|poll|event]\n\nFlags:\n  --format text|json   Print a raw path or {\"path\": \"...\"} JSON. Default: text.\n  --poll-mode auto|poll|event\n                       Report the log for that poll mode; event mode keeps it in durable\n                       state under the git common directory. Default: poll.mode (auto).\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 --stack PR [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply merge [PR] --require-sha SHA --merge-action ACTION --transport rest\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 apply check-blocker [PR] --check <name> (--blocked-by <ref>|--clear)\n  pr-shepherd apply queue-removal [PR] --require-sha <head> --queue-commit <commit> --removed-at <unix>\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 merge          Submit or resume a guarded asynchronous merge or enqueue request.\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  apply check-blocker  Record that a failing check is blocked on an external PR or issue.\n  apply queue-removal  Acknowledge one current CI-driven native-stack queue removal.\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  playbook             Print a playbook named by an instruction pointer.\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  --transport auto|graphql|rest  Select GitHub transport. Default: github.transport (auto).\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  --instructions playbook|inline Render fix_code steps inline every tick (default) or fold the invariant ones into a playbook pointer. Default: iterate.instructions (inline).\n\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stackIntervalFactor (built-in 2) unless this flag is set.\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 or stack SHEPHERD 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 READY/FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\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 or READY\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  15  MERGE\n  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)\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/help.mjs

@@ -7,6 +7,8 @@ export const USAGE = {
 };
 /** Resolve help keys for nested public commands before any command I/O. */
 export function helpKeyForArgs(args) {
+    if (args[0] === "apply" && args[1] === "merge")
+        return "apply merge";
     if (args[0] === "apply" && args[1] === "review")
         return "apply review";
     if (args[0] === "apply" && args[1] === "files")

package/bin/cli/iterate-branch-segment.d.mts

@@ -1,3 +1,5 @@
 import type { IterateResult } from "../types.mts";
+/** True when the summary-line branch phrase names the PR base branch. */
+export declare function branchSegmentShowsBase(result: IterateResult): boolean;
 /** Summary-line branch phrase. Empty when the PR is not behind or conflicting. */
 export declare function branchStateSegment(result: IterateResult): string;

package/bin/cli/iterate-branch-segment.mjs

@@ -1,13 +1,18 @@
+/** True when the summary-line branch phrase names the PR base branch. */
+export function branchSegmentShowsBase(result) {
+    if (!result.baseBranch)
+        return false;
+    if (result.mergeStatus === "BEHIND")
+        return true;
+    return result.mergeStatus === "CONFLICTS" && !result.stackTrunkConflict;
+}
 /** Summary-line branch phrase. Empty when the PR is not behind or conflicting. */
 export function branchStateSegment(result) {
-    if (result.mergeStatus === "BEHIND" && result.baseBranch) {
-        return `**branch** behind PR base \`${result.baseBranch}\``;
-    }
     if (result.mergeStatus === "CONFLICTS" && result.stackTrunkConflict) {
         return `**branch** conflicts with stack trunk \`${result.stackTrunkConflict}\``;
     }
-    if (result.mergeStatus === "CONFLICTS" && result.baseBranch) {
-        return `**branch** conflicts with PR base \`${result.baseBranch}\``;
-    }
-    return "";
+    if (!branchSegmentShowsBase(result))
+        return "";
+    const state = result.mergeStatus === "BEHIND" ? "behind" : "conflicts with";
+    return `**branch** ${state} PR base \`${result.baseBranch}\``;
 }

package/bin/cli/iterate-flags.d.mts

@@ -1,4 +1,4 @@
-import type { loadConfig } from "../config/load.mts";
+import { type loadConfig, type InstructionStyle, type PollMode } from "../config/load.mts";
 interface IterateFlags {
     readyDelaySuffix: string | undefined | null;
     readyDelaySeconds: number;
@@ -7,6 +7,12 @@ interface IterateFlags {
     noAutoMarkReady: boolean;
     noAutoCancelActionable: boolean;
     merge: boolean;
+    /** `null` when `--instructions` was invalid (an error was already printed). */
+    instructions: InstructionStyle | null | undefined;
+    /** `null` when `--poll-mode` was invalid (an error was already printed). */
+    pollMode: PollMode | null | undefined;
 }
+/** True when any flag failed validation; the usage error is already printed. */
+export declare function hasInvalidIterateFlags(flags: IterateFlags): boolean;
 export declare function parseIterateFlags(extra: string[], cfg: ReturnType<typeof loadConfig>): IterateFlags;
 export {};

package/bin/cli/iterate-flags.mjs

@@ -1,9 +1,18 @@
+import { INSTRUCTION_STYLES, POLL_MODES, isInstructionStyle, isPollMode, } from "../config/load.mjs";
+import { EXIT } from "../exit-codes.mjs";
 import { getFlag, hasFlag } from "./args.mjs";
 import { parseDurationToSeconds } from "./duration.mjs";
 import { validateSecondsDurationFlag } from "./duration-flag.mjs";
 // --ready-delay and --stall-timeout are minute-family flags: a bare number means minutes, and 0 is a
 // valid value (it disables the ready-delay settle window / stall-timeout escalation, respectively).
 const MINUTE_FLAG_OPTS = { defaultUnit: "m", allowZero: true };
+/** True when any flag failed validation; the usage error is already printed. */
+export function hasInvalidIterateFlags(flags) {
+    return (flags.readyDelaySuffix === null ||
+        flags.stallTimeoutSuffix === null ||
+        flags.instructions === null ||
+        flags.pollMode === null);
+}
 export function parseIterateFlags(extra, cfg) {
     const readyDelayStr = getFlag(extra, "--ready-delay");
     const readyDelaySuffix = validateSecondsDurationFlag("pr-shepherd", "--ready-delay", readyDelayStr, hasFlag(extra, "--ready-delay"), MINUTE_FLAG_OPTS);
@@ -14,7 +23,10 @@ export function parseIterateFlags(extra, cfg) {
     const stallTimeoutStr = getFlag(extra, "--stall-timeout");
     const stallTimeoutSuffix = validateSecondsDurationFlag("pr-shepherd", "--stall-timeout", stallTimeoutStr, hasFlag(extra, "--stall-timeout"), MINUTE_FLAG_OPTS);
     const stallTimeoutSeconds = parseDurationToSeconds(stallTimeoutSuffix ?? "", cfg.iterate.stallTimeoutMinutes * 60, MINUTE_FLAG_OPTS);
+    const instructions = parseInstructionsFlag(extra);
     return {
+        instructions,
+        pollMode: parsePollModeFlag(extra),
         readyDelaySuffix,
         readyDelaySeconds,
         stallTimeoutSuffix,
@@ -24,3 +36,29 @@ export function parseIterateFlags(extra, cfg) {
         merge,
     };
 }
+/** Validate `--instructions`. Returns `undefined` when absent, `null` after printing a usage error. */
+function parseInstructionsFlag(extra) {
+    const value = getFlag(extra, "--instructions");
+    if (!hasInstructionsFlag(extra))
+        return undefined;
+    if (isInstructionStyle(value))
+        return value;
+    process.stderr.write(`pr-shepherd: --instructions must be one of ${INSTRUCTION_STYLES.join(", ")}, got ${JSON.stringify(value ?? "")}\n`);
+    process.exitCode = EXIT.USAGE;
+    return null;
+}
+function hasInstructionsFlag(extra) {
+    return extra.some((arg) => arg === "--instructions" || arg.startsWith("--instructions="));
+}
+/** Validate `--poll-mode`. Returns `undefined` when absent, `null` after printing a usage error. */
+function parsePollModeFlag(extra) {
+    const value = getFlag(extra, "--poll-mode");
+    if (!extra.some((arg) => arg === "--poll-mode" || arg.startsWith("--poll-mode="))) {
+        return undefined;
+    }
+    if (isPollMode(value))
+        return value;
+    process.stderr.write(`pr-shepherd: --poll-mode must be one of ${POLL_MODES.join(", ")}, got ${JSON.stringify(value ?? "")}\n`);
+    process.exitCode = EXIT.USAGE;
+    return null;
+}

package/bin/cli/iterate-formatter.d.mts

@@ -6,12 +6,12 @@ import type { IterateResult } from "../types.mts";
  *   1. The H1 heading on line 1 contains `[<ACTION>]` — the action tag identifies
  *      the output for logging and validation. Behavior is driven by `## Instructions`,
  *      not by dispatching on the tag.
- *   2. `[FIX_CODE]` wraps the `resolve` command under `## Post-fix actions` in
- *      backticks — the skill extracts the backticked content for execution.
- *   3. Every action ends with a `## Instructions` section — numbered `1.`, `2.`, … —
- *      that tells the agent exactly what to do with this output. The section is
- *      unconditional: every action, every variant, always emits at least one step.
- *      The skill simply follows those steps; it does not need its own dispatch table.
+ *   2. `[FIX_CODE]` prints the `apply review` command inline, in backticks, in its
+ *      `## Instructions` step; the agent runs that backticked command as printed.
+ *   3. Every action except `cancel` ends with a `## Instructions` section — numbered
+ *      `1.`, `2.`, … — that tells the agent exactly what to do with this output, with at
+ *      least one step. `cancel` has no section: the `[CANCEL]` tag already means stop this
+ *      PR's loop. The skill follows those steps; it does not need its own dispatch table.
  */
 export declare function formatIterateResult(result: IterateResult, opts?: {
     verbose?: boolean;

package/bin/cli/iterate-formatter.mjs

@@ -8,6 +8,9 @@ import { formatApiUsage, formatQuotaWarning } from "./api-usage-formatter.mjs";
 import { formatActivityLine } from "./iterate-activity-formatter.mjs";
 import { branchStateSegment } from "./iterate-branch-segment.mjs";
 import { insertRuleAutoResolveSection } from "../commands/rule-auto-resolve-format.mjs";
+import { formatTransportEvidence } from "./transport-formatter.mjs";
+import { formatNextCheckLines, formatPollModeSegment } from "./next-check-format.mjs";
+import { formatPrUrl } from "../pr-reference.mjs";
 /**
  * Format an IterateResult as human-readable Markdown.
  *
@@ -15,31 +18,51 @@ import { insertRuleAutoResolveSection } from "../commands/rule-auto-resolve-form
  *   1. The H1 heading on line 1 contains `[<ACTION>]` — the action tag identifies
  *      the output for logging and validation. Behavior is driven by `## Instructions`,
  *      not by dispatching on the tag.
- *   2. `[FIX_CODE]` wraps the `resolve` command under `## Post-fix actions` in
- *      backticks — the skill extracts the backticked content for execution.
- *   3. Every action ends with a `## Instructions` section — numbered `1.`, `2.`, … —
- *      that tells the agent exactly what to do with this output. The section is
- *      unconditional: every action, every variant, always emits at least one step.
- *      The skill simply follows those steps; it does not need its own dispatch table.
+ *   2. `[FIX_CODE]` prints the `apply review` command inline, in backticks, in its
+ *      `## Instructions` step; the agent runs that backticked command as printed.
+ *   3. Every action except `cancel` ends with a `## Instructions` section — numbered
+ *      `1.`, `2.`, … — that tells the agent exactly what to do with this output, with at
+ *      least one step. `cancel` has no section: the `[CANCEL]` tag already means stop this
+ *      PR's loop. The skill follows those steps; it does not need its own dispatch table.
  */
 export function formatIterateResult(result, opts) {
     const verbose = opts?.verbose ?? false;
     const readyDelaySuffix = opts?.readyDelaySuffix;
-    const finish = (text) => insertRuleAutoResolveSection(text, result.ruleAutoResolve);
+    const repoSeg = ` · **repo** \`${result.repo}\``;
+    // Lean: the repo segment repeats what a generated command's PR URL or `--repo` flag already
+    // shows. Only the CLI-generated `## Instructions` section counts: review bodies and logs above
+    // it are untrusted and may name any repository.
+    const dropRepeatedRepo = (full) => {
+        if (verbose)
+            return full;
+        const instructions = full.slice(full.lastIndexOf("\n## Instructions\n") + 1);
+        const generated = instructions.startsWith("## Instructions\n") &&
+            (instructions.includes(formatPrUrl(result.repo, result.pr)) ||
+                instructions.includes(`--repo ${result.repo} `));
+        return generated ? full.replace(repoSeg, "") : full;
+    };
+    const finish = (text) => dropRepeatedRepo(insertRuleAutoResolveSection(text, result.ruleAutoResolve));
     const heading = `# PR #${result.pr} [${result.action.toUpperCase()}]`;
     const reviewDecisionSeg = result.mergeStatus === "BLOCKED" && result.reviewDecision
         ? ` · **reviewDecision** \`${result.reviewDecision}\``
         : "";
     const baseBranchSeg = verbose && result.baseBranch ? ` · **baseBranch** \`${result.baseBranch}\`` : "";
-    const baseLine = `**status** \`${result.status}\` · **merge** \`${result.mergeStateStatus}\`${reviewDecisionSeg} · **state** \`${result.state}\` · **repo** \`${result.repo}\`${baseBranchSeg}`;
+    // A CLEAN merge state and an OPEN PR are the trivial defaults; verbose output keeps them.
+    const mergeSeg = verbose || result.mergeStateStatus !== "CLEAN"
+        ? ` · **merge** \`${result.mergeStateStatus}\``
+        : "";
+    const stateSeg = verbose || result.state !== "OPEN" ? ` · **state** \`${result.state}\`` : "";
+    const baseLine = `**status** \`${result.status}\`${mergeSeg}${reviewDecisionSeg}${stateSeg}${repoSeg}${baseBranchSeg}${formatPollModeSegment(result)}`;
     const branchSeg = branchStateSegment(result);
     let summaryLine;
     if (verbose) {
         const verboseBranch = branchSeg ? ` · ${branchSeg}` : "";
-        summaryLine = `**summary** ${result.summary.passing} passing, ${result.summary.skipped} skipped, ${result.summary.filtered} filtered, ${result.summary.inProgress} inProgress, ${result.summary.superseded} superseded · **remainingSeconds** ${result.remainingSeconds} · **blockingBotReviewInProgress** ${result.blockingBotReviewInProgress} · **isDraft** ${result.isDraft} · **shouldCancel** ${result.shouldCancel}${verboseBranch}`;
+        summaryLine = `**summary** ${result.summary.passing} passing, ${result.summary.skipped} skipped, ${result.summary.filtered} filtered, ${result.summary.inProgress} inProgress, ${result.summary.superseded} superseded · **remainingSeconds** ${result.remainingSeconds} · **blockingBotReviewInProgress** ${result.blockingBotReviewInProgress} · **isDraft** ${result.isDraft} · **shouldCancel** ${result.shouldCancel}${verboseBranch}${readyDelaySuffix ? ` · **ready-delay** \`${readyDelaySuffix}\` (override)` : ""}`;
     }
     else {
-        const counts = [`${result.summary.passing} passing`];
+        const counts = [];
+        if (result.summary.passing > 0)
+            counts.push(`${result.summary.passing} passing`);
         if (result.summary.skipped > 0)
             counts.push(`${result.summary.skipped} skipped`);
         if (result.summary.filtered > 0)
@@ -48,7 +71,7 @@ export function formatIterateResult(result, opts) {
             counts.push(`${result.summary.inProgress} inProgress`);
         if (result.summary.superseded > 0)
             counts.push(`${result.summary.superseded} superseded`);
-        const segs = [`**summary** ${counts.join(", ")}`];
+        const segs = counts.length > 0 ? [`**summary** ${counts.join(", ")}`] : [];
         if (result.status === "READY" && result.remainingSeconds > 0) {
             segs.push(`**remainingSeconds** ${result.remainingSeconds}`);
         }
@@ -58,13 +81,13 @@ export function formatIterateResult(result, opts) {
             segs.push(`**isDraft**`);
         if (branchSeg)
             segs.push(branchSeg);
-        summaryLine = segs.join(" · ");
-    }
-    // Surface an explicit `--ready-delay` override (set only when the user passed the flag)
-    // so the active settle window stays visible on every tick. Replaces the rerun command
-    if (readyDelaySuffix) {
-        summaryLine += ` · **ready-delay** \`${readyDelaySuffix}\` (override)`;
+        // Surface an explicit `--ready-delay` override (set only when the user passed the flag)
+        // so the active settle window stays visible on every tick.
+        if (readyDelaySuffix)
+            segs.push(`**ready-delay** \`${readyDelaySuffix}\` (override)`);
+        summaryLine = segs.length > 0 ? segs.join(" · ") : null;
     }
+    const summaryLines = summaryLine ? [summaryLine] : [];
     const bp = result.branchProtection;
     const requiredParts = [];
     if (bp) {
@@ -84,7 +107,7 @@ export function formatIterateResult(result, opts) {
         }
     }
     const requiredLine = requiredParts.length > 0 ? `**required** ${requiredParts.join(", ")}` : null;
-    const headerLines = [heading, "", baseLine, summaryLine];
+    const headerLines = [heading, "", baseLine, ...summaryLines, ...formatTransportEvidence(result)];
     if (result.mergeRequirements) {
         headerLines.push(...formatMergeRequirementLines(result.mergeRequirements));
     }
@@ -104,6 +127,7 @@ export function formatIterateResult(result, opts) {
     const activityLine = formatActivityLine(result);
     if (activityLine)
         headerLines.push(activityLine);
+    headerLines.push(...formatNextCheckLines(result.nextCheck));
     const header = headerLines.join("\n");
     const quotaWarning = formatQuotaWarning(result.quotaWarning);
     const apiUsage = verbose ? formatApiUsage(result.apiUsage) : null;
@@ -111,12 +135,12 @@ export function formatIterateResult(result, opts) {
     const telemetrySections = [quotaWarning, apiUsage, verboseChecks];
     switch (result.action) {
         case "ready":
-            return joinSections([
+            return dropRepeatedRepo(joinSections([
                 header,
                 ...telemetrySections,
                 adaptIterateLog(result.log),
                 `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
-            ]);
+            ]));
         case "wait": {
             const waitLines = [header, ...telemetrySections, adaptIterateLog(result.log)];
             if (result.deferredWork)
@@ -134,7 +158,18 @@ export function formatIterateResult(result, opts) {
         case "merge":
             return finish(formatMergeAction(joinSections([header, ...telemetrySections]), result));
         case "cancel": {
-            const cancelHeaderLines = [`${heading} — ${result.reason}`, "", baseLine, summaryLine];
+            // A merged or closed PR needs no more data: the `[CANCEL]` heading is enough. Cancel has no
+            // instruction steps; the skill's recurrence rule says what to do after it.
+            if (!verbose && (result.reason === "merged" || result.reason === "closed")) {
+                return finish(`${heading} — ${result.reason}`);
+            }
+            const cancelHeaderLines = [
+                `${heading} — ${result.reason}`,
+                "",
+                baseLine,
+                ...summaryLines,
+                ...formatTransportEvidence(result),
+            ];
             if (result.mergeRequirements) {
                 cancelHeaderLines.push(...formatMergeRequirementLines(result.mergeRequirements));
             }
@@ -158,7 +193,6 @@ export function formatIterateResult(result, opts) {
                 ...(apiUsage ? [apiUsage] : []),
                 ...(verboseChecks ? [verboseChecks] : []),
                 adaptIterateLog(result.log),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result))}`,
             ]));
         }
         case "escalate":