pr-shepherd 0.59.1 → 0.59.3

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.59.1",
+  "version": "0.59.3",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -33,8 +33,8 @@ $ pr-shepherd 123
 
 1. Fix each warranted item.
 2. Triage `## Failing checks`. Playbook: "CI failure triage".
-3. Commit and push any changes.
-4. Journal key decisions or rejections with URLs or IDs: `pr-shepherd apply journal 123 '- <decision>'`
+3. Optional: If you reject a code review suggestion, journal why: `pr-shepherd apply journal 123 '- <reason>'`.
+4. Commit and push any changes.
 5. `$DISMISS_MESSAGE`: one sentence on what changed. Run even if no code changed: `pr-shepherd apply review 123 --reply-thread-ids PRRT_kwDOSGizTs58XB1L --message "$DISMISS_MESSAGE" --require-sha HEAD`
 6. Rerun Shepherd now.
 ```
@@ -151,7 +151,7 @@ See [docs/graphql-usage.md](docs/graphql-usage.md) and [docs/rest-usage.md](docs
 
 1. **Install the MCP server and the CLI.** See [Install](#install) below.
 2. **Write your policy into a skill or agent instruction.** Examples: "skip non-blocking review comments", "reply instead of fixing nits", "never merge". Shepherd reports state and the next action. Your instructions decide how the agent treats each comment. The shipped `pr-shepherd` skill is a thin dispatcher you can wrap ([docs/skills.md](docs/skills.md)).
-3. **Configure Shepherd.** In `.pr-shepherdrc.yml`, turn on the bundled classification rules. They drop known bot noise before it reaches the agent, which saves more tokens and tool calls. With the default `actions.autoMinimizeSuppressed: true`, several rules also minimize matching comments on GitHub and log a Shepherd Journal entry; set it to `false` to keep comments untouched. See [docs/configuration.md](docs/configuration.md#classifystandard--default-).
+3. **Configure Shepherd.** In `.pr-shepherdrc.yml`, turn on the bundled classification rules. They drop known bot noise before it reaches the agent, which saves more tokens and tool calls. With the default `actions.autoMinimizeSuppressed: true`, several rules also minimize matching comments on GitHub and surface the mutation result without editing the PR body. See [docs/configuration.md](docs/configuration.md#classifystandard--default-).
 
    ```yaml
    classify:

package/bin/classify/types.d.mts

@@ -29,7 +29,7 @@ export interface ClassifyAction {
     readonly autoResolve?: boolean;
     /** When true, hides the item from agent output (seen marker is still written). */
     readonly suppress?: boolean;
-    /** Note included in the auto-resolve report, tick line, and Shepherd Journal when this rule fires. */
+    /** Note included in the auto-resolve report and tick line when this rule fires. */
     readonly reason?: string;
 }
 export type ClassifyRule = (item: ClassifyItem) => ClassifyAction | null | undefined;

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

@@ -253,8 +253,8 @@ 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  --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 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           Leave draft PRs in draft; stop when otherwise ready.\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, ready-delay elapsed, or a clean draft left in draft because auto mark-ready is disabled. 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, ready-delay elapsed, or clean draft left in draft by disabled auto mark-ready)\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           Leave draft PRs in draft; stop when otherwise ready.\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, ready-delay elapsed, or clean draft left in draft by disabled auto mark-ready)\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.

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  --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).";
-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 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).";
+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           Leave draft PRs in draft; stop when otherwise ready.\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, ready-delay elapsed, or a clean draft left in draft because auto mark-ready is disabled. 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, ready-delay elapsed, or clean draft left in draft by disabled auto mark-ready)\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).";
+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 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           Leave draft PRs in draft; stop when otherwise ready.\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, ready-delay elapsed, or clean draft left in draft by disabled auto mark-ready)\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).";
 /** Public help page for the default PR polling invocation. */
 export declare const DEFAULT_USAGE: string;

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

@@ -9,7 +9,7 @@ Usage:
 Iterate flags:
   --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
   --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
-  --no-auto-mark-ready           Do not convert draft PRs to ready for review.
+  --no-auto-mark-ready           Leave draft PRs in draft; stop when otherwise ready.
   --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).
@@ -26,12 +26,12 @@ Actions:
   MARK_READY  Draft PR was marked ready; continue with the next poll.
   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.
   FIX_CODE    Agent action is required; follow the instructions, then continue polling.
-  CANCEL      Stop polling this pull request: merged/closed or ready-delay elapsed. Continue remaining work from the original request.
+  CANCEL      Stop polling this pull request: merged/closed, ready-delay elapsed, or a clean draft left in draft because auto mark-ready is disabled. Continue remaining work from the original request.
   ESCALATE    Stop polling until a human provides direction.
   MERGE       Run the emitted merge/queue command, then continue monitoring.
 
 Exit codes:
-  0   CANCEL (merged or ready-delay elapsed)
+  0   CANCEL (merged, ready-delay elapsed, or clean draft left in draft by disabled auto mark-ready)
   10  WAIT or READY
   11  MARK_READY
   12  FIX_CODE
@@ -65,7 +65,7 @@ Poll flags:
 Forwarded iterate flags:
   --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
   --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
-  --no-auto-mark-ready           Do not convert draft PRs to ready for review.
+  --no-auto-mark-ready           Leave draft PRs in draft; stop when otherwise ready.
   --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).
@@ -83,7 +83,7 @@ FIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not
 With --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.
 
 Exit codes: same as iterate (the final tick's action/reason decides the code).
-  0   CANCEL (merged or ready-delay elapsed)
+  0   CANCEL (merged, ready-delay elapsed, or clean draft left in draft by disabled auto mark-ready)
   10  WAIT or READY (including a WAIT returned by --timeout)
   11  MARK_READY
   12  FIX_CODE

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 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.";
+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           Leave draft PRs in draft; stop when otherwise ready.\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, ready-delay elapsed, or clean draft left in draft by disabled auto mark-ready)\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

@@ -49,7 +49,7 @@ Common flags:
 Iterate flags:
   --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
   --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
-  --no-auto-mark-ready           Do not convert draft PRs to ready for review.
+  --no-auto-mark-ready           Leave draft PRs in draft; stop when otherwise ready.
   --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).
@@ -70,7 +70,7 @@ Clean variants:
   all                  Remove all pr-shepherd state.
 
 Exit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).
-  0   CANCEL (merged or ready-delay elapsed)
+  0   CANCEL (merged, ready-delay elapsed, or clean draft left in draft by disabled auto mark-ready)
   10  WAIT or READY
   11  MARK_READY
   12  FIX_CODE

package/bin/cli/help.d.mts

@@ -253,8 +253,8 @@ 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  --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 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           Leave draft PRs in draft; stop when otherwise ready.\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, ready-delay elapsed, or a clean draft left in draft because auto mark-ready is disabled. 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, ready-delay elapsed, or clean draft left in draft by disabled auto mark-ready)\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           Leave draft PRs in draft; stop when otherwise ready.\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, ready-delay elapsed, or clean draft left in draft by disabled auto mark-ready)\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.
@@ -336,7 +336,7 @@ The name is case-insensitive; spaces and hyphens are equivalent ("Fix-code loop"
 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.";
+    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           Leave draft PRs in draft; stop when otherwise ready.\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, ready-delay elapsed, or clean draft left in draft by disabled auto mark-ready)\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/iterate-instructions.mjs

@@ -1,10 +1,7 @@
 import { inlineCode } from "../util/markdown.mjs";
 import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
-import { formatPrUrl } from "../pr-reference.mjs";
-import { AUTO_MARK_READY_DISABLED_HOLD } from "../commands/stack-work.mjs";
-import { buildPrShepherdCommand, renderShellCommand } from "./runner.mjs";
+import { renderShellCommand } from "./runner.mjs";
 import { eventWaitSteps } from "../commands/event-instructions.mjs";
-import { playbookPointer } from "../commands/playbook-pointer.mjs";
 export function buildSimpleIterateInstructions(result) {
     switch (result.action) {
         case "ready": {
@@ -20,8 +17,6 @@ export function buildSimpleIterateInstructions(result) {
             ];
         }
         case "wait":
-            if (result.stackDraftHold)
-                return buildStackDraftHoldInstructions(result, result.stackDraftHold);
             if (result.nextCheck) {
                 return ["Non-terminal — no action needed this tick.", ...eventWaitSteps(result.nextCheck)];
             }
@@ -85,31 +80,6 @@ export function buildSimpleIterateInstructions(result) {
         }
     }
 }
-/**
- * A held stack draft cannot advance by repeating its one-PR session, so hand control back
- * to the stack selector instead of asking for another immediate iteration.
- */
-function buildStackDraftHoldInstructions(result, hold) {
-    const event = result.pollMode === "event";
-    const stackCommand = buildPrShepherdCommand([
-        "--stack",
-        formatPrUrl(result.repo, result.pr),
-        "--until-terminal",
-        ...(event ? ["--poll-mode", "event"] : []),
-    ]).text;
-    const handoff = `a \`--stack\` selector listed this session, finish that selector's remaining steps and rerun it with its original flags; otherwise run ${inlineCode(stackCommand)}, adding \`--merge\` when merging was requested.`;
-    const reason = hold.kind === "auto-mark-ready-disabled" ? AUTO_MARK_READY_DISABLED_HOLD : hold.kind;
-    const instruction = `PR #${result.pr} stays in draft because ${reason}, so repeating this one-PR session cannot advance it. If ${handoff}`;
-    const step = result.quotaWarning
-        ? buildQuotaAwareContinuation(result.quotaWarning, instruction)
-        : instruction;
-    if (!event)
-        return [step];
-    return [
-        step,
-        `Event mode: do not rerun this one-PR session and keep no wake-up for it. After the handoff, follow only the stack selector's output; it ends the turn and schedules the next tick through its own \`nextCheck\`. ${playbookPointer("Cloud event loop")}`,
-    ];
-}
 export function adaptIterateLog(log) {
     return log.replace(/\s+—\s+\d+s until auto-cancel/g, "");
 }

package/bin/cli/iterate-lean.mjs

@@ -119,7 +119,6 @@ export function projectIterateLean(result, opts) {
                 ...(result.deferredWork && {
                     deferredWork: Object.fromEntries(Object.entries(result.deferredWork).filter(([, n]) => n > 0)),
                 }),
-                ...(result.stackDraftHold && { stackDraftHold: result.stackDraftHold }),
                 log: adaptIterateLog(result.log),
                 instructions: simpleInstructions(result),
             };

package/bin/commands/check.mjs

@@ -350,8 +350,6 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
         enabled: opts.autoMinimizeSuppressed === true,
         partition: authorizedPartition,
         batch: batchData,
-        prNumber,
-        repo,
     });
     const visibleMutationThreadIds = new Set([...threadVisibility.activeThreads, ...threadVisibility.resolutionOnlyThreads].map((thread) => thread.id));
     const ruleAutoResolveThreadIds = [

package/bin/commands/event-mode.mjs

@@ -4,7 +4,7 @@ import { runWithDurableState } from "../state/durable-state.mjs";
 import { eventAggregateStep, eventFixContinuation } from "./event-instructions.mjs";
 import { earliestNextCheck, MERGE_QUEUE_RECHECK_SECONDS, nextCheckCandidates, SAFETY_NET_SECONDS, } from "./next-check.mjs";
 import { isFixCodeContinuation } from "./iterate/check-instructions.mjs";
-import { isHandedOffSelection } from "./poll-summary-explicit-instructions.mjs";
+import { isHandedOffSelection, onlyDraftVerificationSelection, } from "./poll-summary-explicit-instructions.mjs";
 import { runIterate } from "./iterate/index.mjs";
 import { resolvePollMode } from "./poll-mode.mjs";
 import { readStackStallDeadline } from "./stack-stall.mjs";
@@ -56,7 +56,6 @@ async function runIterateEvent(opts) {
         remainingSeconds: result.remainingSeconds,
         queued: result.mergeQueue?.inQueue === true,
         restMerge: result.action === "merge" && result.merge.mode === "rest",
-        stackDraftHold: result.action === "wait" && result.stackDraftHold !== undefined,
         stallDeadlineSeconds,
     }, nowMs), nowMs);
     const tagged = { ...result, pollMode: "event", ...(nextCheck && { nextCheck }) };
@@ -102,11 +101,7 @@ async function withAggregateNextCheck(result, opts) {
         ],
     };
 }
-/**
- * Event mode replaces polling: the appended event step owns the next wake-up, so a stack
- * step's "recheck at the configured polling cadence" would contradict it. A pending stack
- * merge resumes on that wake-up instead.
- */
+/** The appended event step owns timing, including pending stack merges. */
 function withoutPollingCadence(step) {
     return step
         .replace(/ Recheck(?: them)? at the configured polling cadence\./g, "")
@@ -114,6 +109,7 @@ function withoutPollingCadence(step) {
 }
 function aggregateNextCheck(result, stallDeadlineSeconds) {
     if (isHandedOffSelection(result) ||
+        (onlyDraftVerificationSelection(result) && result.nextAction !== "merge") ||
         result.reason === "all_terminal" ||
         result.nextAction === "cancel" ||
         result.nextAction === "escalate") {

package/bin/commands/iterate/fix-loop-instruction.d.mts

@@ -1,9 +1,3 @@
 import type { InstructionStyle } from "../../config/load.mts";
-/**
- * The generic commit/push step and the journal step. Playbook style folds both into one pointer
- * only when the generic push applies: the "Fix-code loop" playbook tells the caller to push to the
- * PR head branch, which would conflict with a conflict or queue-recovery push step. Without the
- * generic push, the journal step stays inline with its citation clause. The rerun
- * step stays inline because it is the one step a halted loop cannot recover from.
- */
-export declare function buildPushJournalSteps(style: InstructionStyle, prReference: string | number, genericPush: boolean, wantsJournal: boolean): string[];
+/** The generic push stays separate from conflict and queue-recovery push instructions. */
+export declare function buildPushSteps(style: InstructionStyle, genericPush: boolean): string[];

package/bin/commands/iterate/fix-loop-instruction.mjs

@@ -1,35 +1,14 @@
 import { renderShellCommand } from "../../cli/runner.mjs";
 import { loadConfig } from "../../config/load.mjs";
-import { buildShepherdJournalCommand, buildShepherdJournalInstruction, } from "../shepherd-journal.mjs";
 import { playbookPointer } from "../playbook-pointer.mjs";
 const FIX_CODE_LOOP_PLAYBOOK = "Fix-code loop";
-/**
- * Playbook-style replacement for the invariant commit/push and journal steps. The
- * procedure text lives in the "Fix-code loop" playbook; only the trigger and the concrete
- * journal command stay in the per-tick output. `inline` style never calls this.
- */
-function buildFixLoopInstruction(prReference, journal) {
-    const parts = ["Commit and push any changes."];
-    if (journal)
-        parts.push(`Journal substantial decisions or rejections with \`${buildShepherdJournalCommand(prReference)}\`.`);
+/** The generic push stays separate from conflict and queue-recovery push instructions. */
+export function buildPushSteps(style, genericPush) {
+    if (!genericPush)
+        return [];
+    const push = "Commit and push any changes.";
+    if (style === "inline")
+        return [push];
     const cli = renderShellCommand([...loadConfig().cliCommand, "playbook", FIX_CODE_LOOP_PLAYBOOK]);
-    parts.push(`${playbookPointer(FIX_CODE_LOOP_PLAYBOOK)} CLI: \`${cli}\`.`);
-    return parts.join(" ");
-}
-/**
- * The generic commit/push step and the journal step. Playbook style folds both into one pointer
- * only when the generic push applies: the "Fix-code loop" playbook tells the caller to push to the
- * PR head branch, which would conflict with a conflict or queue-recovery push step. Without the
- * generic push, the journal step stays inline with its citation clause. The rerun
- * step stays inline because it is the one step a halted loop cannot recover from.
- */
-export function buildPushJournalSteps(style, prReference, genericPush, wantsJournal) {
-    if (style === "playbook" && genericPush)
-        return [buildFixLoopInstruction(prReference, wantsJournal)];
-    const steps = [];
-    if (genericPush)
-        steps.push("Commit and push any changes.");
-    if (wantsJournal)
-        steps.push(buildShepherdJournalInstruction(prReference));
-    return steps;
+    return [`${push} ${playbookPointer(FIX_CODE_LOOP_PLAYBOOK)} CLI: \`${cli}\`.`];
 }

package/bin/commands/iterate/index.mjs

@@ -23,7 +23,6 @@ import { fingerprintRawSummaryPr } from "../../github/poll-summary-fingerprint.m
 import { currentQueueRemovalEvent } from "../../github/poll-summary-queue-removal.mjs";
 import { isCurrentSummaryReady } from "../../github/poll-summary-readiness.mjs";
 import { clearReadyReceipt, isReadyReceiptCurrent, readReadyReceipt, writeReadyReceipt, } from "../../state/ready-receipts.mjs";
-import { stackDraftHold } from "./parent-first.mjs";
 import { findStaleNativeStackAncestry } from "./stale-ancestry.mjs";
 import { annotateBlockedWait, resolveCheckBlockerGate } from "./check-blocker-gate.mjs";
 import { buildUnreportedFixResult, planUnreportedRequired } from "./unreported-required.mjs";
@@ -261,6 +260,18 @@ async function runIterateCore(opts) {
         };
     }
     const autoMarkReady = !opts.noAutoMarkReady && config.actions.autoMarkReady;
+    if (canMarkReady && !autoMarkReady) {
+        await clearReadyDelay(report.pr, repoOwner, repoName);
+        await clearStallState(stallKey);
+        return {
+            ...base,
+            action: "cancel",
+            reason: "auto-mark-ready-disabled",
+            shouldCancel: false,
+            remainingSeconds: 0,
+            log: `CANCEL: PR #${base.pr} stays in draft because automatic mark-ready is disabled — stopping`,
+        };
+    }
     const markReadyResult = await markReadyIfAuthorized(canMarkReady && autoMarkReady, base, report);
     if (markReadyResult)
         return markReadyResult;
@@ -310,12 +321,10 @@ async function runIterateCore(opts) {
             log: `READY: PR #${base.pr} is ready — ${readyState.remainingSeconds}s of ready-delay remaining — ${buildWaitLog(base).slice("WAIT: ".length)}`,
         };
     }
-    const hold = stackDraftHold(report, autoMarkReady);
     const wait = {
         ...base,
         action: "wait",
         log: buildWaitLog(base),
-        ...(hold && { stackDraftHold: hold }),
     };
     return annotateBlockedWait(await applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, wait, reportForWork, reviewSummaryIds, opts.stallDeadlineSink), blockerGate);
 }

package/bin/commands/iterate/render.d.mts

@@ -8,6 +8,6 @@ import type { InstructionStyle } from "../../config/load.mts";
  */
 export declare function renderResolveCommand(rc: ResolveCommand): string;
 export declare function buildFixInstructions(threads: AgentThread[], actionableComments: AgentComment[], checks: AgentCheck[], changesRequestedReviews: Review[], baseBranch: string, resolveCommand: ResolveCommand, hasConflicts: boolean, prReference: string | number, _cancelledCount: number, firstLookThreads?: FirstLookThread[], firstLookComments?: FirstLookComment[], firstLookSummaries?: Review[], editedSummaries?: Review[], _inProgressRunIds?: string[], resolutionOnlyThreads?: ReviewThread[], resolveOnlyCommand?: ResolveCommand, behindBaseHint?: string, // iterate.behindBaseHint — see buildBehindBaseHintInstruction
-isBehind?: boolean, viewerCanUpdate?: boolean, hasExhaustedWorkflowRerun?: boolean, stackRebase?: string, // native stack layers rebase with gh-stack, not branch by branch
+isBehind?: boolean, _viewerCanUpdate?: boolean, hasExhaustedWorkflowRerun?: boolean, stackRebase?: string, // native stack layers rebase with gh-stack, not branch by branch
 queueEjection?: QueueEjectionRecovery, // current merge-queue removal with failing queue checks
 instructionStyle?: InstructionStyle): string[];

package/bin/commands/iterate/render.mjs

@@ -1,12 +1,11 @@
-import { renderShellCommand } from "../../cli/runner.mjs";
+import { buildPrShepherdCommand, renderShellCommand } from "../../cli/runner.mjs";
 import { buildFailingCheckInstructions, buildCrStaleClause, buildBehindBaseHintInstruction, buildRepeatedWorkflowBranchRecoveryInstructions, buildResolveCommandInstruction, buildFixCompletionInstruction, } from "./check-instructions.mjs";
-import { SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE } from "../shepherd-journal.mjs";
 import { isFailingAgentCheck } from "../../checks/conclusions.mjs";
 import { buildCommitSuggestionInstruction } from "../commit-suggestion-instruction.mjs";
 import { partitionFixThreads } from "./fix-instruction-threads.mjs";
 import { buildBranchPushInstruction, buildConflictInstruction } from "./native-stack-rebase.mjs";
 import { queueEjectionSteps } from "./queue-recovery-instructions.mjs";
-import { buildPushJournalSteps } from "./fix-loop-instruction.mjs";
+import { buildPushSteps } from "./fix-loop-instruction.mjs";
 /**
  * Render a resolve command as a shell snippet. Appends `--require-sha HEAD` when set: run after
  * the push step, the local HEAD is the pushed PR head, and `apply review` rejects the mutations
@@ -18,7 +17,7 @@ export function renderResolveCommand(rc) {
 }
 const REQUIRE_HEAD_SHA = "--require-sha HEAD";
 export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prReference, _cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], _inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behindBaseHint — see buildBehindBaseHintInstruction
-isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false, stackRebase, // native stack layers rebase with gh-stack, not branch by branch
+isBehind = false, _viewerCanUpdate = false, hasExhaustedWorkflowRerun = false, stackRebase, // native stack layers rebase with gh-stack, not branch by branch
 queueEjection, // current merge-queue removal with failing queue checks
 instructionStyle = "inline") {
     const instructions = [];
@@ -48,8 +47,8 @@ instructionStyle = "inline") {
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
     if (firstLookTotal > 0)
         instructions.push("Review every item under `## First-look items` before acting.");
-    if (firstLookSummaries.length > 0 && viewerCanUpdate)
-        instructions.push(SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE);
+    if (firstLookSummaries.length > 0)
+        instructions.push("Read each body under `## Review summaries (first look)` before acting.");
     const editedTotal = editedSummaries.length +
         actionableComments.filter((c) => c.edited).length +
         firstLookThreads.filter((t) => t.edited).length +
@@ -72,19 +71,24 @@ instructionStyle = "inline") {
         instructions.push(staleClause);
     if (!hintWithConflictStep)
         instructions.push(...branchUpdateHint);
+    const hasReviewFeedback = threads.length > 0 ||
+        resolutionOnlyThreads.length > 0 ||
+        firstLookThreads.length > 0 ||
+        changesRequestedReviews.length > 0 ||
+        actionableComments.length > 0 ||
+        firstLookSummaries.length > 0 ||
+        editedSummaries.length > 0;
+    if (hasReviewFeedback) {
+        const journalCommand = buildPrShepherdCommand(["apply", "journal", String(prReference)]).text;
+        instructions.push(`Optional: If you reject a code review suggestion, journal why: \`${journalCommand} '- <reason>'\`.`);
+    }
     const hasReviewMutations = resolveCommand.hasMutations || resolveOnlyCommand?.hasMutations === true;
     const mutationSuffix = hasReviewMutations ? " before review mutations" : "";
     const genericPush = !(branchRecovery || queueEjection) && hasNonConflictHints;
-    const wantsJournal = viewerCanUpdate &&
-        (hasReviewMutations ||
-            hasNonConflictHints ||
-            firstLookTotal > 0 ||
-            firstLookSummaries.length > 0 ||
-            editedTotal > 0);
     if (branchRecovery || queueEjection) {
         instructions.push(buildBranchPushInstruction(stackRebase, hasConflicts, mutationSuffix, !branchRecovery));
     }
-    instructions.push(...buildPushJournalSteps(instructionStyle, prReference, genericPush, wantsJournal));
+    instructions.push(...buildPushSteps(instructionStyle, genericPush));
     if (resolveOnlyCommand?.hasMutations)
         instructions.push(`Run: \`${renderResolveCommand(resolveOnlyCommand)}\``);
     instructions.push(...buildResolveCommandInstruction(resolveCommand, renderResolveCommand(resolveCommand)), buildFixCompletionInstruction());

package/bin/commands/next-check.d.mts

@@ -17,8 +17,6 @@ interface NextCheckFacts {
     queued?: boolean;
     /** A `merge` tick whose printed command is a REST merge request, which can stay `pending`. */
     restMerge?: boolean;
-    /** A native-stack draft hold: repeating this one-PR session cannot advance it. */
-    stackDraftHold?: boolean;
     /** Unix seconds when an unchanged state would trip the stall timeout. */
     stallDeadlineSeconds?: number;
 }

package/bin/commands/next-check.mjs

@@ -24,7 +24,7 @@ export function nextCheckCandidates(facts, nowMs) {
         return [{ reason: "merge-pending", seconds: MERGE_QUEUE_RECHECK_SECONDS }];
     }
     const terminal = ["cancel", "escalate", "merge", "mark_ready"].includes(facts.action);
-    if (terminal || facts.stackDraftHold)
+    if (terminal)
         return [];
     const candidates = [];
     if (facts.action === "ready" && (facts.remainingSeconds ?? 0) > 0) {

package/bin/commands/poll-summary-explicit-instructions.d.mts

@@ -1,4 +1,6 @@
 import type { PollSummaryResult } from "../types.mts";
 /** Every selected row already returned `CANCEL` or `ESCALATE`: no autonomous work remains. */
 export declare function isHandedOffSelection(result: PollSummaryResult): boolean;
+/** A final full-review probe can finish this selection without another aggregate read. */
+export declare function onlyDraftVerificationSelection(result: PollSummaryResult): boolean;
 export declare function explicitInstructions(result: PollSummaryResult): string[];