pr-shepherd 0.60.0 → 1.0.0

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

@@ -1,5 +1,5 @@
 export declare const COMMAND_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,8 +188,7 @@ 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.";
 };

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

@@ -1,6 +1,6 @@
 /* eslint-disable max-lines */
 import { LOG_FILE_USAGE } from "./help-log-file-page.mjs";
-import { DEFAULT_USAGE, ITERATE_USAGE, POLL_USAGE } from "./help-iterate-poll-pages.mjs";
+import { DEFAULT_USAGE, ITERATE_USAGE, STACK_USAGE } from "./help-iterate-poll-pages.mjs";
 export const COMMAND_USAGE = {
     default: DEFAULT_USAGE,
     "apply merge": `pr-shepherd apply merge
@@ -121,13 +121,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.`,
-    "build-suggestion-patches": `pr-shepherd build-suggestion-patches
+    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]
@@ -137,22 +137,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.`,
-    "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.`,
     admin: `pr-shepherd admin
 
@@ -169,147 +153,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.`,
-    "admin log-file": LOG_FILE_USAGE.replaceAll("pr-shepherd log-file", "pr-shepherd admin log-file"),
-    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).`,
-    "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.`,
-    "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).`,
+    "admin log-file": LOG_FILE_USAGE,
     iterate: ITERATE_USAGE,
-    poll: POLL_USAGE,
-    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).`,
-    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).`,
+    stack: STACK_USAGE,
     "journal extract": `pr-shepherd journal extract
 
 Extract one visible, structurally valid Shepherd Journal from a local PR-body file.
@@ -335,8 +191,7 @@ 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.`,
-    "log-file": LOG_FILE_USAGE,
 };

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

@@ -1,4 +1,5 @@
-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).";
+export declare const ITERATE_USAGE = "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).";
 /** Public help page for the default PR polling invocation. */
-export declare const DEFAULT_USAGE: string;
+export declare const DEFAULT_USAGE = "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).";
+/** Public help page for `pr-shepherd stack`. */
+export declare const STACK_USAGE = "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).";