pr-shepherd 0.60.1 → 1.1.0

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

@@ -1,19 +1,19 @@
 export const ITERATE_USAGE = `pr-shepherd iterate
 
-Run one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.
-The output contains one action and an action-specific ## Instructions section.
+Run one tick and return without sleeping. The no-subcommand form polls; use this subcommand when the
+caller owns the next wake-up. One PR prints one action and an action-specific ## Instructions section.
+Several same-repository PRs print one aggregate summary. Unless nothing remains to wait for, the output
+carries nextCheck: when to rerun if no GitHub event arrives first.
 
 Usage:
-  pr-shepherd iterate [PR] [iterate-flags]
+  pr-shepherd iterate [PR ...] [iterate-flags]
 
 Iterate flags:
-  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
+  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Default: iterate.ready-delay-minutes (built-in 0). Example: 15m.
   --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
   --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).
-  --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).
+  --instructions playbook|inline Render triage steps inline every tick (default) or fold the invariant ones into a playbook pointer. Default: iterate.instructions (inline).
   --transport auto|graphql|rest  Select GitHub transport. Default: github.transport (auto).
   --format text|json             Output Markdown text or JSON. Default: text.
   --verbose                      Include verbose iterate fields.
@@ -25,7 +25,7 @@ Actions:
   WAIT        No immediate action; continue with the next poll.
   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.
+  TRIAGE      Agent action is required; follow the instructions, then continue polling.
   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.
@@ -34,42 +34,42 @@ Exit codes:
   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
+  12  TRIAGE
   13  ESCALATE
   14  CANCEL (closed without merging)
   15  MERGE
   A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).`;
-export const POLL_USAGE = `pr-shepherd poll
+/** Public help page for the default PR polling invocation. */
+export const DEFAULT_USAGE = `pr-shepherd [PR]
 
-Run iterate repeatedly for one PR, or read compact summaries for an explicit PR set or native
-GitHub stack. Aggregate mode returns when any row needs work, every row is terminal, or timeout.
+Run iterate repeatedly for one PR, or read compact summaries for an explicit same-repository PR set.
+Aggregate mode returns when any row needs work, every row is terminal, or timeout.
+When CLAUDE_CODE_REMOTE=true, the command runs one tick like iterate and prints nextCheck instead.
 Poll exits as soon as iterate returns READY, MARK_READY, CANCEL, or ESCALATE, or when timeout
-returns the last WAIT result. FIX_CODE starts a --debounce settle window (default:
-poll.debounceSeconds; built-in 1m): poll keeps
+returns the last WAIT result. TRIAGE starts a --debounce settle window (default:
+poll.debounce-seconds; built-in 1m): poll keeps
 iterating at --interval, then runs one more tick after the window and returns that result.
 With --until-terminal or --merge, poll also continues through MARK_READY.
 
 Usage:
-  pr-shepherd poll [PR ...] [poll-flags] [iterate-flags]
-  pr-shepherd poll --stack PR [poll-flags] [iterate-flags]
+  pr-shepherd [PR ...] [poll-flags] [iterate-flags]
+
+Use 'pr-shepherd stack PR' for a native GitHub stack.
 
 Poll flags:
-  --stack PR                    Select all entries in PR's native GitHub stack, bottom to top.
-  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stackIntervalFactor (built-in 2) unless this flag is set.
-  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).
-  --debounce <duration>          Settle window after first FIX_CODE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.
-  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.
-  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.
-  --until-terminal               Continue through WAIT/MARK_READY until READY/FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.
+  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.interval-seconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stack-interval-factor (built-in 2) unless this flag is set.
+  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeout-seconds (built-in 4.5m).
+  --debounce <duration>          Settle window after first TRIAGE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounce-seconds (built-in 60s). 0 disables.
+  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quiet-status.
+  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quiet-status.
+  --until-terminal               Continue through WAIT/MARK_READY until READY/TRIAGE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.
 
 Forwarded iterate flags:
-  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
+  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Default: iterate.ready-delay-minutes (built-in 0). Example: 15m.
   --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
   --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).
-  --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).
+  --instructions playbook|inline Render triage steps inline every tick (default) or fold the invariant ones into a playbook pointer. Default: iterate.instructions (inline).
   --transport auto|graphql|rest  Select GitHub transport. Default: github.transport (auto).
   --format text|json             Output Markdown text or JSON. Default: text.
   --verbose                      Include verbose iterate fields and detailed per-tick lines.
@@ -78,21 +78,61 @@ Forwarded iterate flags:
 Durations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds
 for --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with
 an explicit unit (4.5m).
-Each 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.
-FIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.
-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.
+Each WAIT tick writes a stderr line naming what it is waiting on by default; poll.quiet-status can change that default, --quiet-status/--no-quiet-status override it, and --verbose emits detailed per-tick lines.
+TRIAGE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.
+With --until-terminal, --timeout is ignored for WAIT ticks and polling continues until READY, TRIAGE, 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, 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
+  12  TRIAGE
   13  ESCALATE
   14  CANCEL (closed without merging)
   15  MERGE
-  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)
   A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).`;
-/** Public help page for the default PR polling invocation. */
-export const DEFAULT_USAGE = POLL_USAGE.replace(/^pr-shepherd poll$/m, "pr-shepherd [PR]")
-    .replace(/^ {2}pr-shepherd poll \[PR \.\.\.\]/m, "  pr-shepherd [PR ...]")
-    .replace(/^ {2}pr-shepherd poll --stack/m, "  pr-shepherd --stack");
+/** Public help page for `pr-shepherd stack`. */
+export const STACK_USAGE = `pr-shepherd stack
+
+Shepherd every open PR in one PR's native GitHub stack, bottom to top. Each poll reads compact
+per-layer summaries and returns when a layer needs work, every layer is terminal, or timeout.
+SHEPHERD lists one-PR sessions to run before rerunning this command.
+--once, or CLAUDE_CODE_REMOTE=true, runs one aggregate tick and prints nextCheck instead of sleeping.
+
+Usage:
+  pr-shepherd stack PR [--once] [poll-flags] [iterate-flags]
+
+Stack flags:
+  --once                         Run one aggregate tick without sleeping; poll flags are ignored.
+
+Poll flags:
+  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.interval-seconds (built-in 60s) multiplied by poll.stack-interval-factor (built-in 2) unless this flag is set.
+  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeout-seconds (built-in 4.5m).
+  --debounce <duration>          Settle window after the first SHEPHERD before returning. Bare number = seconds. Default: poll.debounce-seconds (built-in 60s). 0 disables.
+  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quiet-status.
+  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quiet-status.
+  --until-terminal               Continue through WAIT until SHEPHERD, MERGE, CANCEL, or ESCALATE.
+
+Forwarded iterate flags:
+  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Default: iterate.ready-delay-minutes (built-in 0). 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.
+  --merge                        Shepherd through readiness, then emit the stack merge commands.
+  --instructions playbook|inline Render triage steps inline every tick (default) or fold the invariant ones into a playbook pointer. Default: iterate.instructions (inline).
+  --transport auto|graphql|rest  Select GitHub transport. Default: github.transport (auto).
+  --format text|json             Output Markdown text or JSON. Default: text.
+  --verbose                      Include detailed per-tick lines.
+  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
+
+Durations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds
+for --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with
+an explicit unit (4.5m).
+
+Exit codes:
+  0   CANCEL (every layer merged)
+  10  WAIT
+  13  ESCALATE
+  14  CANCEL (a layer closed without merging)
+  15  MERGE
+  16  SHEPHERD (run the listed one-PR sessions, then rerun this stack command)
+  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).`;

package/bin/cli/help-log-file-page.d.mts

@@ -1 +1 @@
-export declare const LOG_FILE_USAGE = "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.";
+export declare const LOG_FILE_USAGE = "pr-shepherd admin 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 admin log-file [--format text|json]\n\nFlags:\n  --format text|json   Print a raw path or {\"path\": \"...\"} JSON. Default: text.\n  --help, -h           Print this help and exit before logging setup.\n\nEnvironment:\n  PR_SHEPHERD_LOG_DISABLED=1 disables logging.\n  PR_SHEPHERD_STATE_DIR overrides the base state directory.\n  CLAUDE_CODE_REMOTE=true reports the durable log under the git common directory.\n\nExit code: 0 on success; 1 if repository identity cannot be resolved.";

package/bin/cli/help-log-file-page.mjs

@@ -1,20 +1,18 @@
-export const LOG_FILE_USAGE = `pr-shepherd log-file
+export const LOG_FILE_USAGE = `pr-shepherd admin log-file
 
 Print the per-worktree append-only debug log path for the current repository.
 The log is created by the first non-help pr-shepherd command that initializes logging.
 
 Usage:
-  pr-shepherd log-file [--format text|json] [--poll-mode auto|poll|event]
+  pr-shepherd admin log-file [--format text|json]
 
 Flags:
   --format text|json   Print a raw path or {"path": "..."} JSON. Default: text.
-  --poll-mode auto|poll|event
-                       Report the log for that poll mode; event mode keeps it in durable
-                       state under the git common directory. Default: poll.mode (auto).
   --help, -h           Print this help and exit before logging setup.
 
 Environment:
   PR_SHEPHERD_LOG_DISABLED=1 disables logging.
   PR_SHEPHERD_STATE_DIR overrides the base state directory.
+  CLAUDE_CODE_REMOTE=true reports the durable log under the git common directory.
 
 Exit code: 0 on success; 1 if repository identity cannot be resolved.`;

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           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.";
+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 [--once] [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 suggest [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 or an explicit same-repository set.\n  stack                Poll every open PR in one PR's native GitHub stack.\n  iterate              Run one tick for one PR or a same-repository set, and print nextCheck.\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  suggest              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.\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. Default: iterate.ready-delay-minutes (built-in 0). 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  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --instructions playbook|inline Render triage steps inline every tick (default) or fold the invariant ones into a playbook pointer. Default: iterate.instructions (inline).\n\nPolling flags (looping commands; in a Claude Code cloud session, CLAUDE_CODE_REMOTE=true, they run one tick like iterate):\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.interval-seconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stack-interval-factor (built-in 2) unless this flag is set.\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: poll.timeout-seconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first TRIAGE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounce-seconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quiet-status.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quiet-status.\n  --until-terminal               Continue through WAIT/MARK_READY until READY/TRIAGE/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  TRIAGE\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 stack command)\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

@@ -6,8 +6,8 @@ Usage:
   pr-shepherd --version | -v
   pr-shepherd --help | -h
   pr-shepherd [PR ...] [poll-flags] [iterate-flags]
-  pr-shepherd --stack PR [poll-flags] [iterate-flags]
-  pr-shepherd iterate [PR] [iterate-flags]
+  pr-shepherd stack PR [--once] [poll-flags] [iterate-flags]
+  pr-shepherd iterate [PR ...] [iterate-flags]
   pr-shepherd apply merge [PR] --require-sha SHA --merge-action ACTION --transport rest
   pr-shepherd apply review [PR] [review-flags]
   pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]
@@ -15,13 +15,14 @@ Usage:
   pr-shepherd apply check-blocker [PR] --check <name> (--blocked-by <ref>|--clear)
   pr-shepherd apply queue-removal [PR] --require-sha <head> --queue-commit <commit> --removed-at <unix>
   pr-shepherd journal extract --body-file <path>
-  pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]
+  pr-shepherd suggest [PR] --thread-id ID --message MSG [groups...]
   pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]
   pr-shepherd admin log-file [--format text|json]
 
 Commands:
-  [PR ...]             Poll one PR, an explicit same-repository set, or a native stack.
-  iterate              Run one iterate tick (single-tick alias).
+  [PR ...]             Poll one PR or an explicit same-repository set.
+  stack                Poll every open PR in one PR's native GitHub stack.
+  iterate              Run one tick for one PR or a same-repository set, and print nextCheck.
   apply merge          Submit or resume a guarded asynchronous merge or enqueue request.
   apply review         Apply review-state mutations after fixes.
   apply files          Mark selected changed files as viewed.
@@ -29,15 +30,14 @@ Commands:
   apply check-blocker  Record that a failing check is blocked on an external PR or issue.
   apply queue-removal  Acknowledge one current CI-driven native-stack queue removal.
   journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.
-  build-suggestion-patches
-                       Convert ordered GitHub suggestion threads into patches and commit instructions.
+  suggest              Convert ordered GitHub suggestion threads into patches and commit instructions.
   playbook             Print a playbook named by an instruction pointer.
   admin clean          Remove pr-shepherd state files.
   admin log-file       Print the per-worktree debug log path.
 
 PR argument:
   PR may be a number, owner/repo#number, or a GitHub pull request URL.
-  Multiple PRs must name one repository. --stack PR selects every entry in PR's native stack.
+  Multiple PRs must name one repository.
   When omitted, pr-shepherd infers the current branch's pull request.
 
 Common flags:
@@ -47,20 +47,19 @@ Common flags:
   --help, -h           Print help and exit before any GitHub, git, config, or log I/O.
 
 Iterate flags:
-  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.
+  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Default: iterate.ready-delay-minutes (built-in 0). Example: 15m.
   --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.
   --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).
+  --instructions playbook|inline Render triage steps inline every tick (default) or fold the invariant ones into a playbook pointer. Default: iterate.instructions (inline).
 
-Polling flags:
-  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.intervalSeconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stackIntervalFactor (built-in 2) unless this flag is set.
-  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: poll.timeoutSeconds (built-in 4.5m).
-  --debounce <duration>          Settle window after first FIX_CODE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounceSeconds (built-in 60s). 0 disables.
-  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quietStatus.
-  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quietStatus.
-  --until-terminal               Continue through WAIT/MARK_READY until READY/FIX_CODE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.
+Polling flags (looping commands; in a Claude Code cloud session, CLAUDE_CODE_REMOTE=true, they run one tick like iterate):
+  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.interval-seconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stack-interval-factor (built-in 2) unless this flag is set.
+  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: poll.timeout-seconds (built-in 4.5m).
+  --debounce <duration>          Settle window after first TRIAGE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounce-seconds (built-in 60s). 0 disables.
+  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quiet-status.
+  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quiet-status.
+  --until-terminal               Continue through WAIT/MARK_READY until READY/TRIAGE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.
 
 Clean variants:
   pr [number]          Remove state for one PR. Defaults to current branch PR.
@@ -73,11 +72,11 @@ Exit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).
   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
+  12  TRIAGE
   13  ESCALATE
   14  CANCEL (closed without merging)
   15  MERGE
-  16  SHEPHERD (--stack only: run the listed one-PR sessions, then rerun the selector)
+  16  SHEPHERD (stack only: run the listed one-PR sessions, then rerun the stack command)
 See docs/exit-codes.md for the full sysexits.h error-code table.
 
 Duration 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).

package/bin/cli/help.d.mts

@@ -1,5 +1,5 @@
 export declare const USAGE: {
-    readonly default: string;
+    readonly default: "pr-shepherd [PR]\n\nRun iterate repeatedly for one PR, or read compact summaries for an explicit same-repository PR set.\nAggregate mode returns when any row needs work, every row is terminal, or timeout.\nWhen CLAUDE_CODE_REMOTE=true, the command runs one tick like iterate and prints nextCheck instead.\nPoll exits as soon as iterate returns READY, MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. TRIAGE starts a --debounce settle window (default:\npoll.debounce-seconds; 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 [PR ...] [poll-flags] [iterate-flags]\n\nUse 'pr-shepherd stack PR' for a native GitHub stack.\n\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.interval-seconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stack-interval-factor (built-in 2) unless this flag is set.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeout-seconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first TRIAGE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounce-seconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quiet-status.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quiet-status.\n  --until-terminal               Continue through WAIT/MARK_READY until READY/TRIAGE/MERGE/CANCEL/ESCALATE or stack SHEPHERD.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Default: iterate.ready-delay-minutes (built-in 0). 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  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --instructions playbook|inline Render triage steps inline every tick (default) or fold the invariant ones into a playbook pointer. Default: iterate.instructions (inline).\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.quiet-status can change that default, --quiet-status/--no-quiet-status override it, and --verbose emits detailed per-tick lines.\nTRIAGE 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, TRIAGE, 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  TRIAGE\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 "apply merge": `pr-shepherd apply merge
 
 Submit one SHA-guarded asynchronous merge or enqueue request with REST.
@@ -118,13 +118,13 @@ Usage:
 --removed-at <unix>       Removal time in Unix seconds.
 --format text|json        Output format. Default: text.
 --help, -h                Print this help and exit before any I/O.`;
-    readonly "build-suggestion-patches": `pr-shepherd build-suggestion-patches
+    readonly suggest: `pr-shepherd suggest
 
 Build an ordered list of patches and commit instructions from GitHub review suggestions.
 The command does not edit files or mutate git history.
 
 Usage:
-  pr-shepherd build-suggestion-patches [PR]
+  pr-shepherd suggest [PR]
     --thread-id ID --message MSG [--description DESC]
     [--thread-id ID --message MSG [--description DESC] ...]
     [--format text|json]
@@ -134,22 +134,6 @@ belong to that suggestion. Groups are validated and returned in command-line ord
 
 The current branch must match the PR head ref. Local HEAD may equal or descend from the PR head;
 every generated patch is dry-run in order with git apply --check before output.
---help, -h                      Print this help and exit before GitHub, git, config, or log I/O.`;
-    readonly "build-suggestion-patch": `pr-shepherd build-suggestion-patch
-
-Deprecated one-suggestion adapter. Use build-suggestion-patches.
-
-Usage:
-  pr-shepherd build-suggestion-patch [PR] --thread-id ID --message MSG
-                                      [--description DESC] [--format text|json]
-
-Flags:
-  --thread-id <id>       Review thread containing exactly one suggestion block. Required.
-  --message <text>       Suggested commit subject. Required and non-empty.
-  --description <text>   Optional longer commit body.
-  --format text|json     Output format. Default: text.
-
-The current branch must match the PR head ref. Local HEAD may equal or descend from the PR head.
 --help, -h                      Print this help and exit before GitHub, git, config, or log I/O.`;
     readonly admin: `pr-shepherd admin
 
@@ -166,147 +150,19 @@ Run 'pr-shepherd admin <clean|log-file> --help' for command-specific details.
 Remove pr-shepherd state files from PR_SHEPHERD_STATE_DIR.
 
 Usage:
-  pr-shepherd admin clean pr [number] [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
-  pr-shepherd admin clean branch [name] [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
-  pr-shepherd admin clean current [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
-  pr-shepherd admin clean repo [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
-  pr-shepherd admin clean all [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
+  pr-shepherd admin clean pr [number] [--dry-run] [--format text|json]
+  pr-shepherd admin clean branch [name] [--dry-run] [--format text|json]
+  pr-shepherd admin clean current [--dry-run] [--format text|json]
+  pr-shepherd admin clean repo [--dry-run] [--format text|json]
+  pr-shepherd admin clean all [--dry-run] [--format text|json]
 
 Variants remove state for one PR, branch, current branch, repository, or all repositories.
 Use --dry-run to preview paths without removing them.
---poll-mode auto|poll|event      Clean the state for that poll mode; event mode keeps it in durable
-                                state under the git common directory. Default: poll.mode (auto).
+When CLAUDE_CODE_REMOTE=true, state is the durable copy under the git common directory.
 --help, -h                      Print this help and exit before any cleanup.`;
-    readonly "admin log-file": string;
-    readonly resolve: `pr-shepherd resolve
-
-Deprecated compatibility alias for user-directed GitHub review-state mutations. Supplied IDs are forwarded to GitHub;
-GitHub accepts or rejects each mutation.
-
-Usage:
-  pr-shepherd resolve [PR] --reply-thread-ids A,B --message MSG
-  pr-shepherd resolve [PR] --resolve-thread-ids A,B [--minimize-comment-ids X,Y]
-                            [--dismiss-review-ids Q] [--message MSG]
-                            [--require-sha SHA] [--format text|json]
-
-Flags:
-  --resolve-thread-ids <ids>      Comma-separated review thread IDs (PRRT_*) to resolve.
-                                  Note: comment IDs (PRRC_*) from gh api are not thread IDs and will fail.
-  --reply-thread-ids <ids>        Comma-separated review thread IDs to reply to.
-  --minimize-comment-ids <ids>    Comma-separated issue/review comment IDs to minimize.
-  --dismiss-review-ids <ids>      Comma-separated review IDs to dismiss.
-  --message <text>                Reply/dismiss message. Required with --reply-thread-ids
-                                  or --dismiss-review-ids.
-  --require-sha <sha>             Wait until GitHub reports this PR head SHA (or HEAD) before mutating.
-                                  Must be a full 40-character lowercase hex SHA, or HEAD for this
-                                  checkout's commit. Local HEAD is valid only when it equals the
-                                  current remote PR head.
-  --format text|json              Output format. Default: text.
-  --help, -h                      Print this help and exit before GitHub I/O.
-
-At least one non-empty action flag is required:
-  --reply-thread-ids, --resolve-thread-ids, --minimize-comment-ids, or --dismiss-review-ids.
-
-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 "commit-suggestion": `pr-shepherd commit-suggestion
-
-Build a patch and commit instructions for one GitHub review thread containing a suggestion block.
-The command does not edit files or mutate git history.
-
-Usage:
-  pr-shepherd commit-suggestion [PR] --thread-id ID --message MSG
-                                      [--description DESC] [--format text|json]
-
-Flags:
-  --thread-id <id>       Review thread ID containing exactly one suggestion to apply. Required.
-  --message <text>       Suggested commit subject. Required and must be non-empty.
-  --description <text>   Optional longer commit body.
-  --format text|json     Output format. Default: text.
-  --help, -h             Print this help and exit before GitHub, git, config, or log I/O.
-
-Preconditions:
-  The current branch must match the PR head ref. Local HEAD may equal or descend from the PR head.
-
-Exit codes:
-  0   suggestion patch and instructions produced
-  64  usage error (missing/invalid flag)
-  69  precondition unmet (thread ineligible, branch/SHA mismatch, no open PR)
-  See docs/exit-codes.md for the full sysexits.h table.`;
-    readonly "mark-files-as-viewed": `pr-shepherd mark-files-as-viewed
-
-Deprecated compatibility alias for marking selected PR files as viewed.
-
-Usage:
-  pr-shepherd mark-files-as-viewed [PR] [files...] [--tests] [--match REGEX]
-                                      [--format text|json]
-
-Selectors:
-  files...          Exact changed-file paths from the PR diff.
-  --tests           Select changed test files.
-  --match <regex>   Select changed files whose paths match a case-insensitive JavaScript regex.
-                    May be repeated.
-
-Flags:
-  --format text|json  Output format. Default: text.
-  --help, -h          Print this help and exit before GitHub I/O.
-
-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           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.
-
-Usage:
-  pr-shepherd clean pr [number] [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
-  pr-shepherd clean branch [name] [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
-  pr-shepherd clean current [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
-  pr-shepherd clean repo [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
-  pr-shepherd clean all [--dry-run] [--format text|json] [--poll-mode auto|poll|event]
-
-Variants:
-  pr [number]          Remove state for one PR. Defaults to current branch PR.
-  branch [name]        Resolve a branch to its open PR, then remove that PR's state.
-                       Defaults to current branch.
-  current              Alias for branch against the current branch.
-  repo                 Remove all state for the current repository, including worktree logs.
-  all                  Remove all pr-shepherd state.
-
-Flags:
-  --dry-run            Preview paths without removing them.
-  --format text|json   Output format. Default: text.
-  --poll-mode auto|poll|event
-                       Clean the state for that poll mode; event mode keeps it in durable
-                       state under the git common directory. Default: poll.mode (auto).
-  --help, -h           Print this help and exit before any cleanup.
-
-Exit code: 0 on success (including a no-op --dry-run on a nonexistent target); nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
-    readonly journal: `pr-shepherd journal
-
-Append a list item to the Shepherd Journal details block of a PR body.
-Creates the section at the end if absent. Idempotent — duplicate items are skipped.
-
-Usage:
-  pr-shepherd journal [PR] <item> [--dry-run] [--format text|json]
-  pr-shepherd journal [PR] --file <path> [--dry-run] [--format text|json]
-  pr-shepherd journal [PR] --file - [--dry-run] [--format text|json]
-
-  PR     PR number or GitHub pull request URL. Defaults to current branch PR.
-  item   Markdown list item: must start with "- " followed by non-whitespace text.
-         Example: '- Rejected suggestion: kept existing pattern for consistency.'
-         Provide it as a positional argument, or via --file to avoid shell-escaping
-         backticks and multi-line Markdown. Exactly one of the two is required.
-
-Flags:
-  --file <path>        Read the entry from a file instead of a positional argument.
-                        Pass --file - to read from stdin.
-  --dry-run            Preview the new PR body without writing it to GitHub.
-  --format text|json   Output format. Default: text.
-  --help, -h           Print this help and exit before any GitHub I/O.
-
-Exit code: 0 on success (including no-change no-op); nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
+    readonly "admin log-file": "pr-shepherd admin 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 admin log-file [--format text|json]\n\nFlags:\n  --format text|json   Print a raw path or {\"path\": \"...\"} JSON. Default: text.\n  --help, -h           Print this help and exit before logging setup.\n\nEnvironment:\n  PR_SHEPHERD_LOG_DISABLED=1 disables logging.\n  PR_SHEPHERD_STATE_DIR overrides the base state directory.\n  CLAUDE_CODE_REMOTE=true reports the durable log under the git common directory.\n\nExit code: 0 on success; 1 if repository identity cannot be resolved.";
+    readonly iterate: "pr-shepherd iterate\n\nRun one tick and return without sleeping. The no-subcommand form polls; use this subcommand when the\ncaller owns the next wake-up. One PR prints one action and an action-specific ## Instructions section.\nSeveral same-repository PRs print one aggregate summary. Unless nothing remains to wait for, the output\ncarries nextCheck: when to rerun if no GitHub event arrives first.\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. Default: iterate.ready-delay-minutes (built-in 0). 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  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --instructions playbook|inline Render triage steps inline every tick (default) or fold the invariant ones into a playbook pointer. Default: iterate.instructions (inline).\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  TRIAGE      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  TRIAGE\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 stack: "pr-shepherd stack\n\nShepherd every open PR in one PR's native GitHub stack, bottom to top. Each poll reads compact\nper-layer summaries and returns when a layer needs work, every layer is terminal, or timeout.\nSHEPHERD lists one-PR sessions to run before rerunning this command.\n--once, or CLAUDE_CODE_REMOTE=true, runs one aggregate tick and prints nextCheck instead of sleeping.\n\nUsage:\n  pr-shepherd stack PR [--once] [poll-flags] [iterate-flags]\n\nStack flags:\n  --once                         Run one aggregate tick without sleeping; poll flags are ignored.\n\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: poll.interval-seconds (built-in 60s) multiplied by poll.stack-interval-factor (built-in 2) unless this flag is set.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: poll.timeout-seconds (built-in 4.5m).\n  --debounce <duration>          Settle window after the first SHEPHERD before returning. Bare number = seconds. Default: poll.debounce-seconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quiet-status.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quiet-status.\n  --until-terminal               Continue through WAIT until SHEPHERD, MERGE, CANCEL, or ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Default: iterate.ready-delay-minutes (built-in 0). 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  --merge                        Shepherd through readiness, then emit the stack merge commands.\n  --instructions playbook|inline Render triage steps inline every tick (default) or fold the invariant ones into a playbook pointer. Default: iterate.instructions (inline).\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 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).\n\nExit codes:\n  0   CANCEL (every layer merged)\n  10  WAIT\n  13  ESCALATE\n  14  CANCEL (a layer closed without merging)\n  15  MERGE\n  16  SHEPHERD (run the listed one-PR sessions, then rerun this stack command)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
     readonly "journal extract": `pr-shepherd journal extract
 
 Extract one visible, structurally valid Shepherd Journal from a local PR-body file.
@@ -332,11 +188,10 @@ Usage:
 Flags:
   --format text|json   Markdown text (default) or one JSON line: {"name","content"} or {"playbooks":[...]}.
 
-The name is case-insensitive; spaces and hyphens are equivalent ("Fix-code loop" and fix-code-loop match).
+The name is case-insensitive; spaces and hyphens are equivalent ("Triage loop" and triage-loop match).
 Unknown names exit 64 and list the available playbooks.
 --help, -h                      Print this help and exit before any I/O.`;
-    readonly "log-file": "pr-shepherd log-file\n\nPrint the per-worktree append-only debug log path for the current repository.\nThe log is created by the first non-help pr-shepherd command that initializes logging.\n\nUsage:\n  pr-shepherd log-file [--format text|json] [--poll-mode auto|poll|event]\n\nFlags:\n  --format text|json   Print a raw path or {\"path\": \"...\"} JSON. Default: text.\n  --poll-mode auto|poll|event\n                       Report the log for that poll mode; event mode keeps it in durable\n                       state under the git common directory. Default: poll.mode (auto).\n  --help, -h           Print this help and exit before logging setup.\n\nEnvironment:\n  PR_SHEPHERD_LOG_DISABLED=1 disables logging.\n  PR_SHEPHERD_STATE_DIR overrides the base state directory.\n\nExit code: 0 on success; 1 if repository identity cannot be resolved.";
-    readonly top: "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR ...] [poll-flags] [iterate-flags]\n  pr-shepherd --stack PR [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply merge [PR] --require-sha SHA --merge-action ACTION --transport rest\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd apply check-blocker [PR] --check <name> (--blocked-by <ref>|--clear)\n  pr-shepherd apply queue-removal [PR] --require-sha <head> --queue-commit <commit> --removed-at <unix>\n  pr-shepherd journal extract --body-file <path>\n  pr-shepherd build-suggestion-patches [PR] --thread-id ID --message MSG [groups...]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR ...]             Poll one PR, an explicit same-repository set, or a native stack.\n  iterate              Run one iterate tick (single-tick alias).\n  apply merge          Submit or resume a guarded asynchronous merge or enqueue request.\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark selected changed files as viewed.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  apply check-blocker  Record that a failing check is blocked on an external PR or issue.\n  apply queue-removal  Acknowledge one current CI-driven native-stack queue removal.\n  journal extract      Extract a validated Shepherd Journal from a local PR-body file as JSON.\n  build-suggestion-patches\n                       Convert ordered GitHub suggestion threads into patches and commit instructions.\n  playbook             Print a playbook named by an instruction pointer.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number, owner/repo#number, or a GitHub pull request URL.\n  Multiple PRs must name one repository. --stack PR selects every entry in PR's native stack.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --transport auto|graphql|rest  Select GitHub transport. Default: github.transport (auto).\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           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.";
+    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 [--once] [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 suggest [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 or an explicit same-repository set.\n  stack                Poll every open PR in one PR's native GitHub stack.\n  iterate              Run one tick for one PR or a same-repository set, and print nextCheck.\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  suggest              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.\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. Default: iterate.ready-delay-minutes (built-in 0). 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  --merge                        Shepherd through readiness, then emit a merge or merge-queue command.\n  --instructions playbook|inline Render triage steps inline every tick (default) or fold the invariant ones into a playbook pointer. Default: iterate.instructions (inline).\n\nPolling flags (looping commands; in a Claude Code cloud session, CLAUDE_CODE_REMOTE=true, they run one tick like iterate):\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: poll.interval-seconds (built-in 60s). Stack and multi-PR polls multiply that by poll.stack-interval-factor (built-in 2) unless this flag is set.\n  --timeout <duration>           Poll wall-clock cap for WAIT ticks. Bare number = seconds. Default: poll.timeout-seconds (built-in 4.5m).\n  --debounce <duration>          Settle window after first TRIAGE or stack SHEPHERD before returning. Bare number = seconds. Default: poll.debounce-seconds (built-in 60s). 0 disables.\n  --quiet-status                 Print only changed WAIT snapshots. Overrides poll.quiet-status.\n  --no-quiet-status              Print every WAIT snapshot. Overrides poll.quiet-status.\n  --until-terminal               Continue through WAIT/MARK_READY until READY/TRIAGE/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  TRIAGE\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 stack command)\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-checks-formatter.mjs

@@ -1,5 +1,5 @@
 import { renderRelatedJobLines } from "./related-jobs-format.mjs";
-import { renderCheckAnnotation } from "./fix-formatter-extra.mjs";
+import { renderCheckAnnotation } from "./triage-formatter-extra.mjs";
 export function formatRelevantChecks(checks) {
     if (checks.length === 0)
         return null;