pr-shepherd 0.19.0 → 0.21.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.19.0",
+  "version": "0.21.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -20,12 +20,12 @@ Example Workflow:
 
 `pr-shepherd` optimizes token management, rate limits, and agentic orchestration by moving **ALL** deterministic logic and prompts to code via a CLI tool, enshrining what would be a large skill or command prompt (of which the agent would inevitably make mistakes) into the code and returning a clear, actionable prompt.
 
-The CLI emits unified recheck instructions. Generated commands use `cli.runner` from `.pr-shepherdrc.yml`: `auto` (default), `npx`, `pnpm`, `yarn`, or `bun`.
+The CLI emits unified recheck instructions. Generated commands call `pr-shepherd` directly.
 
-At a high level, the skill invokes `pr-shepherd <PR>` through the selected package runner, which provides actionable feedback directly to the agent:
+At a high level, the skill invokes `pr-shepherd <PR>` (which polls by default), providing actionable feedback directly to the agent:
 
-```
-> npx pr-shepherd 123
+```text
+> pr-shepherd 123
 
 # PR #123 [FIX_CODE]
 
@@ -44,12 +44,12 @@ At a high level, the skill invokes `pr-shepherd <PR>` through the selected packa
 ## Failing checks
 
 - `24697658766` — `CI › lint / typecheck / test (22.x)`
-  > npx oxfmt
+  > oxfmt
 
 ## Post-fix push
 
 - base: `main`
-- resolve: `npx pr-shepherd resolve 123 --resolve-thread-ids PRRT_kwDOSGizTs58XB1L --minimize-comment-ids IC_kwDOSGizTs7_ajT8,IC_kwDOSGizTs7_ajT9 --dismiss-review-ids PRR_kwDOSGizTs58XB1R --message "$DISMISS_MESSAGE" --require-sha "$HEAD_SHA"`
+- resolve: `pr-shepherd resolve 123 --resolve-thread-ids PRRT_kwDOSGizTs58XB1L --minimize-comment-ids IC_kwDOSGizTs7_ajT8,IC_kwDOSGizTs7_ajT9 --dismiss-review-ids PRR_kwDOSGizTs58XB1R --message "$DISMISS_MESSAGE" --require-sha "$HEAD_SHA"`
 
 ## Instructions
 
@@ -61,13 +61,13 @@ _(schematic — actual steps depend on PR state)_
 4. Rebase and push: `git fetch origin && git rebase origin/main && git push --force-with-lease` — capture `HEAD_SHA=$(git rev-parse HEAD)`.
 5. Run the `resolve:` command above, substituting `"$HEAD_SHA"`.
 6. Add or update a `## Shepherd Journal` section in the PR description for any large decisions made, appending under the existing heading if it already exists.
-7. CI needs time to run on the new push. Schedule one session-only follow-up task to run `npx pr-shepherd 123` to recheck once after a fresh delay between 30 seconds and 4 minutes, then end this turn. Do not sleep or rerun inline.
+7. CI needs time to run on the new push. Run `pr-shepherd 123` again to continue until Shepherd returns `[CANCEL]` or `[ESCALATE]`.
 ```
 
 On every iteration, a command is returned to instruct the agent exactly what to do. No guessing, no thinking, as few agentic turns as possible:
 
-```
-npx pr-shepherd resolve 123 --resolve-thread-ids PRRT_kwDOSGizTs58XB1L --minimize-comment-ids IC_kwDOSGizTs7_ajT8,IC_kwDOSGizTs7_ajT9 --dismiss-review-ids PRR_kwDOSGizTs58XB1R --message "$DISMISS_MESSAGE" --require-sha "$HEAD_SHA"
+```text
+pr-shepherd resolve 123 --resolve-thread-ids PRRT_kwDOSGizTs58XB1L --minimize-comment-ids IC_kwDOSGizTs7_ajT8,IC_kwDOSGizTs7_ajT9 --dismiss-review-ids PRR_kwDOSGizTs58XB1R --message "$DISMISS_MESSAGE" --require-sha "$HEAD_SHA"
 ```
 
 ## Workflow
@@ -97,7 +97,7 @@ Some other workflow improvements:
 
 Recommendations:
 
-- Run `pr-shepherd` on all your PRs before you go to sleep so that you wake up to reviewable PRs. Keep an active goal cycling the reusable command until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures).
+- Run `pr-shepherd` on all your PRs before you go to sleep so that you wake up to reviewable PRs. Keep an active goal cycling `pr-shepherd <PR>` until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures).
 - Instruct your agents to write comments in a single review (comment, changes requested, or approved). This allows the review's comments/threads to be minimized or resolved together, keeping your pull request history clean. If you write inline comments outside of a review, each comment would still show up in the pull request history and take up space.
 - Avoid sticky comments as they will continue to be hidden. Instead, just make a new comment, especially on reviews. If you really want sticky comments, instruct your agent to unhide/unminimize them when updating them.
 - Avoid having automation edit comments, reviews, or threads in place because updated items get minimized. Instead, always make a new review, comment, thread, etc.
@@ -114,7 +114,7 @@ Recommendations:
 
 ### Iterate a PR to completion
 
-One-tick dispatcher — checks CI and review comments, fixes issues, and marks the PR ready for review when clean. Each non-terminal tick emits an `## Instructions` section telling the agent how to run the next tick; the loop continues until `[CANCEL]` or `[ESCALATE]`.
+Poll dispatcher — checks CI and review comments, fixes issues, and marks the PR ready for review when clean. Each non-terminal tick emits an `## Instructions` section; the skill follows it, then invokes `pr-shepherd <PR>` again until `[CANCEL]` or `[ESCALATE]`.
 
 Claude Code (via `pr-shepherd` skill):
 
@@ -127,9 +127,10 @@ Claude Code (via `pr-shepherd` skill):
 Codex or direct CLI:
 
 ```sh
-npx pr-shepherd 42
-npx pr-shepherd 42 --ready-delay 15m
-npx pr-shepherd iterate 42               # legacy-compatible spelling
+pr-shepherd 42
+pr-shepherd 42 --interval 45s --timeout 4m
+pr-shepherd 42 --ready-delay 15m
+pr-shepherd iterate 42               # single tick
 ```
 
 ## Iterate decision loop
@@ -141,25 +142,16 @@ On each tick: fetch PR state in one GraphQL batch → classify CI, comments, and
 `pr-shepherd` accumulates state under `$PR_SHEPHERD_STATE_DIR` (seen markers, fix-attempt counters, stall fingerprints, etc.). To reset it:
 
 ```sh
-npx pr-shepherd clean current    # remove state for the current branch's PR
-npx pr-shepherd clean repo       # remove all state for this repo
-npx pr-shepherd clean all        # remove all pr-shepherd state
+pr-shepherd clean current    # remove state for the current branch's PR
+pr-shepherd clean repo       # remove all state for this repo
+pr-shepherd clean all        # remove all pr-shepherd state
 ```
 
 Add `--dry-run` to preview what would be removed. See [docs/cli-usage.md](docs/cli-usage.md) for the full `clean` reference.
 
 ## Install
 
-> **Note:** Skill and plugin install methods add the skill definitions only — they do not install the `pr-shepherd` CLI. The skills invoke `pr-shepherd` through the repo package runner, so you also need the CLI available. If you're using `pr-shepherd` as development tooling for your repo, install it as a dev dependency so the selected runner resolves it without prompting:
->
-> ```bash
-> pnpm add -D pr-shepherd      # pnpm repos
-> yarn add -D pr-shepherd      # yarn repos
-> bun add -d pr-shepherd       # bun repos
-> npm install --save-dev pr-shepherd
-> ```
->
-> A plain `npm install pr-shepherd` adds it to regular dependencies instead; use that only if you specifically want it under `dependencies`. Or install globally: `npm install -g pr-shepherd`.
+> **Note:** Skill and plugin install methods add the skill definitions only — they do not install the `pr-shepherd` CLI. Ensure `pr-shepherd` is available on `PATH` wherever the skill runs.
 
 ### Claude Code
 
@@ -170,15 +162,7 @@ claude /plugin marketplace add jonathanong/pr-shepherd
 claude /plugin install pr-shepherd
 ```
 
-This repo ships two `marketplace.json` files that serve different Claude install flows: the root `marketplace.json` resolves the plugin from the npm registry (used by the `claude /plugin marketplace add` command above); `.claude-plugin/marketplace.json` is the owner-level registry manifest that resolves the plugin from the local plugin directory (used when Claude Code installs from a local or git-based source). Both files are needed to support these two install paths.
-
-Alternatively, install the Claude skills individually via `npx skills`:
-
-```bash
-npx skills add jonathanong/pr-shepherd
-```
-
-Installs the `pr-shepherd` skill into your agent's skill directory (`.claude/skills/` for project scope, `~/.claude/skills/` with `-g` for global scope). Powered by [skills.sh](https://skills.sh).
+This repo ships two `marketplace.json` files that serve different Claude install flows: the root `marketplace.json` resolves the published plugin (used by the `claude /plugin marketplace add` command above); `.claude-plugin/marketplace.json` is the owner-level registry manifest that resolves the plugin from the local plugin directory (used when Claude Code installs from a local or git-based source). Both files are needed to support these two install paths.
 
 ### Codex
 
@@ -205,33 +189,16 @@ codex plugin marketplace add ~/.codex/plugin-sources/pr-shepherd
 
 After adding the marketplace, open the Codex plugin directory, choose the `jonathanong` marketplace, and install/enable `pr-shepherd`. The marketplace root must contain `.agents/plugins/marketplace.json` and `plugins/pr-shepherd/`.
 
-Install the CLI where Codex will run it:
+Install the CLI where Codex will run it so `pr-shepherd` is available on `PATH`. The plugin only installs the skill; it does not install the CLI into target repositories.
 
-```bash
-pnpm add -D pr-shepherd      # pnpm repos
-yarn add -D pr-shepherd      # yarn repos
-bun add -d pr-shepherd       # bun repos
-npm install --save-dev pr-shepherd
-```
-
-The plugin only installs the skill; it does not install the CLI into target repositories. To install the CLI globally instead, use `npm install -g pr-shepherd`.
-
-Iterate a PR from Codex with the target repository's package runner:
+Iterate a PR from Codex:
 
 ```bash
-<runner> pr-shepherd iterate 42
+pr-shepherd iterate 42
 ```
 
-For example, a repo like `~/filaments` that declares `packageManager: "pnpm@..."` and has `pnpm-lock.yaml` should use `pnpm exec pr-shepherd iterate 42`. For Bun repos (with `bun.lock` or `bun.lockb`), use `bunx pr-shepherd iterate 42`. For npm repos, use `npx pr-shepherd iterate 42`.
-
 Or ask Codex to use the `pr-shepherd` skill, for example: `run pr-shepherd until this PR is ready`. Follow the output's `## Instructions`. Continue until Shepherd emits `[CANCEL]` or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures). `pr-shepherd iterate 42` remains supported for existing workflows.
 
-### As a global CLI
-
-```bash
-npm install -g pr-shepherd
-```
-
 ## Configuration
 
 Create a `.pr-shepherdrc.yml` in your project root (or any parent directory) to override defaults. The loader walks up from `cwd` to `$HOME` (if `$HOME` is on that path) or the filesystem root; the first match wins.

package/bin/checks/triage.test-support.mjs

@@ -1,5 +1,4 @@
-// @ts-nocheck
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { vi, beforeEach } from "vitest";
 // ---------------------------------------------------------------------------
 // Stub fetch globally so http.mts uses our mock.
 // ---------------------------------------------------------------------------

package/bin/cli/default-poll.mjs

@@ -0,0 +1,32 @@
+import { parsePrNumber } from "./args.mjs";
+import { validateDefaultArgs } from "./validate-default-args.mjs";
+import { USAGE } from "./help.mjs";
+const DEFAULT_POLL_FLAGS_WITH_VALUES = new Set([
+    "--format",
+    "--ready-delay",
+    "--stall-timeout",
+    "--interval",
+    "--timeout",
+]);
+const DEFAULT_POLL_BOOLEAN_FLAGS = new Set([
+    "--verbose",
+    "--no-auto-mark-ready",
+    "--no-auto-cancel-actionable",
+]);
+export function isDefaultPollInvocation(subcommand) {
+    if (subcommand === "--help" || subcommand === "-h")
+        return false;
+    return (subcommand === undefined || parsePrNumber(subcommand) !== null || isDefaultPollFlag(subcommand));
+}
+export function validateDefaultPollArgs(args) {
+    return validateDefaultArgs(args, DEFAULT_POLL_FLAGS_WITH_VALUES, DEFAULT_POLL_BOOLEAN_FLAGS, writeDefaultUsageError);
+}
+function isDefaultPollFlag(arg) {
+    const name = arg.split("=", 1)[0];
+    return DEFAULT_POLL_FLAGS_WITH_VALUES.has(name) || DEFAULT_POLL_BOOLEAN_FLAGS.has(arg);
+}
+function writeDefaultUsageError(arg) {
+    process.stderr.write(`Unknown subcommand: ${arg}\n`);
+    process.stderr.write(`${USAGE.top}\n`);
+    process.exitCode = 1;
+}

package/bin/cli/fix-formatter.mjs

@@ -5,7 +5,6 @@ import { renderThreadBullet, renderReviewBullet, renderThreadResolutionStatusTag
 import { adaptFixCodeInstructions, numberInstructions } from "./iterate-instructions.mjs";
 export function formatFixCodeResult(header, result, opts) {
     const readyDelaySuffix = opts?.readyDelaySuffix;
-    const runner = opts?.runner;
     const sections = [header];
     if (result.fix.threads.length > 0) {
         sections.push("## Review threads");
@@ -31,7 +30,8 @@ export function formatFixCodeResult(header, result, opts) {
         sections.push("## Actionable comments");
         for (const c of result.fix.actionableComments) {
             const heading = c.url ? `[commentId=${c.id}](${c.url})` : `\`commentId=${c.id}\``;
-            sections.push(`### ${heading} (${renderAuthor(c.author, c.authorType)})`);
+            const editedMarker = c.edited ? " [edited since first look]" : "";
+            sections.push(`### ${heading} (${renderAuthor(c.author, c.authorType)})${editedMarker}`);
             sections.push(blockquote(c.body));
         }
     }
@@ -109,7 +109,7 @@ export function formatFixCodeResult(header, result, opts) {
     }
     sections.push(postFixLines.join("\n"));
     sections.push("## Instructions");
-    sections.push(numberInstructions(adaptFixCodeInstructions(result.fix.instructions, result.pr, readyDelaySuffix, runner)));
+    sections.push(numberInstructions(adaptFixCodeInstructions(result.fix.instructions, result.pr, readyDelaySuffix)));
     return joinSections(sections);
 }
 function blockquote(body) {

package/bin/cli/formatters.mjs

@@ -2,7 +2,7 @@ export { formatIterateResult } from "./iterate-formatter.mjs";
 export { projectIterateLean, projectIterateVerbose } from "./iterate-lean.mjs";
 export { formatCleanResult } from "./clean-formatter.mjs";
 import { safeFence } from "./fence.mjs";
-import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderThreadResolutionStatusTag, buildFirstLookBullets, } from "./list-formatters.mjs";
+import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderThreadResolutionStatusTag, buildFirstLookBullets, renderEditedCommentTag, } from "./list-formatters.mjs";
 import { joinSections } from "../util/markdown.mjs";
 export function formatFetchResult(result) {
     const activeTotal = result.actionableThreads.length +
@@ -18,8 +18,7 @@ export function formatFetchResult(result) {
     if (firstLookTotal > 0)
         headingParts.push(`${firstLookTotal} first-look`);
     const headingSuffix = headingParts.length > 0 ? headingParts.join(", ") : "0 actionable";
-    const sections = [];
-    sections.push(`# PR #${result.prNumber} — Resolve fetch (${headingSuffix})`);
+    const sections = [`# PR #${result.prNumber} — Resolve fetch (${headingSuffix})`];
     if (result.actionableThreads.length > 0) {
         sections.push(`## Actionable Review Threads (${result.actionableThreads.length})` +
             (result.commitSuggestionsEnabled ? " [commit-suggestions: enabled]" : ""));
@@ -35,7 +34,9 @@ export function formatFetchResult(result) {
     }
     if (result.actionableComments.length > 0) {
         sections.push(`## Actionable PR Comments (${result.actionableComments.length})`);
-        sections.push(result.actionableComments.map((c) => renderCommentBullet(c)).join("\n"));
+        sections.push(result.actionableComments
+            .map((c) => renderCommentBullet(c, { statusTag: renderEditedCommentTag(c) }))
+            .join("\n"));
     }
     if (result.changesRequestedReviews.length > 0) {
         sections.push(`## Pending CHANGES_REQUESTED reviews (${result.changesRequestedReviews.length})`);

package/bin/cli/handlers.mjs

@@ -106,6 +106,5 @@ export async function handleIterate(args) {
         format: globalOpts.format,
         verbose: globalOpts.verbose ?? false,
         readyDelaySuffix: flags.readyDelaySuffix ?? undefined,
-        runner: cfg.cli?.runner,
     });
 }

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

@@ -0,0 +1,153 @@
+export const COMMAND_USAGE = {
+    resolve: `pr-shepherd resolve
+
+Fetch actionable review items or apply GitHub review-state mutations after fixes.
+
+Usage:
+  pr-shepherd resolve [PR] [--fetch] [--format text|json]
+  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]
+
+Modes:
+  fetch                Default when no mutation IDs are provided. Fetches review threads,
+                       comments, first-look items, and instructions.
+  mutate               Runs when any mutation ID flag is present. Resolves threads,
+                       minimizes comments/review summaries, and dismisses reviews.
+
+Flags:
+  --fetch                         Force fetch mode.
+  --resolve-thread-ids <ids>      Comma-separated review thread IDs to resolve.
+  --minimize-comment-ids <ids>    Comma-separated issue/review comment IDs to minimize.
+  --dismiss-review-ids <ids>      Comma-separated CHANGES_REQUESTED review IDs to dismiss.
+  --message <text>                Dismiss message. Required with --dismiss-review-ids.
+  --require-sha <sha>             Wait until GitHub reports this PR head SHA before mutating.
+  --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; 1 on validation, lookup, or mutation failure.`,
+    "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, and local HEAD must match the PR head SHA.
+
+Exit codes:
+  0  suggestion patch and instructions produced
+  1  validation, lookup, precondition, or suggestion parsing failure`,
+    iterate: `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.
+
+Usage:
+  pr-shepherd iterate [PR] [iterate-flags]
+
+Iterate flags:
+  --ready-delay <duration>       Settle window before a clean PR cancels. Example: 15m.
+  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration.
+  --no-auto-mark-ready           Do not convert draft PRs to ready for review.
+  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
+  --format text|json             Output Markdown text or JSON. Default: text.
+  --verbose                      Include verbose iterate fields.
+  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
+
+Actions:
+  WAIT        No immediate code action; recheck later or use pr-shepherd poll.
+  MARK_READY  Draft PR was marked ready for review.
+  FIX_CODE    Apply fixes, commit, push, and run the printed resolve command.
+  CANCEL      Terminal state: merged/closed or ready-delay elapsed.
+  ESCALATE    Terminal state requiring human direction.
+
+Exit codes:
+  0  WAIT or MARK_READY
+  1  FIX_CODE, or a command/validation error
+  2  CANCEL
+  3  ESCALATE`,
+    poll: `pr-shepherd poll
+
+Run iterate repeatedly while the action is WAIT. Print only the final tick to stdout.
+Poll exits as soon as iterate returns MARK_READY, FIX_CODE, CANCEL, or ESCALATE, or when timeout
+returns the last WAIT result.
+
+Usage:
+  pr-shepherd poll [PR] [poll-flags] [iterate-flags]
+
+Poll flags:
+  --interval <duration>          Sleep between WAIT ticks. Default: 30s.
+  --timeout <duration>           Maximum wall-clock wait. Default: 5m.
+
+Forwarded iterate flags:
+  --ready-delay <duration>       Settle window before a clean PR cancels. Example: 15m.
+  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration.
+  --no-auto-mark-ready           Do not convert draft PRs to ready for review.
+  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
+  --format text|json             Output Markdown text or JSON. Default: text.
+  --verbose                      Include verbose iterate fields and detailed per-tick lines.
+  --help, -h                     Print this help and exit before GitHub, git, config, or log I/O.
+
+Durations accept seconds, minutes, or hours: 30s, 2m, 1h, or bare seconds.
+Each WAIT tick writes a single dot to stderr; --verbose emits the detailed per-tick line.
+
+Exit codes:
+  0  WAIT timeout or MARK_READY
+  1  FIX_CODE, or a command/validation error
+  2  CANCEL
+  3  ESCALATE`,
+    clean: `pr-shepherd clean
+
+Remove pr-shepherd state files from PR_SHEPHERD_STATE_DIR.
+
+Usage:
+  pr-shepherd clean pr [number] [--dry-run] [--format text|json]
+  pr-shepherd clean branch [name] [--dry-run] [--format text|json]
+  pr-shepherd clean current [--dry-run] [--format text|json]
+  pr-shepherd clean repo [--dry-run] [--format text|json]
+  pr-shepherd clean all [--dry-run] [--format text|json]
+
+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.
+  --help, -h           Print this help and exit before any cleanup.
+
+Exit code: 0 on success; 1 on validation or cleanup failure.`,
+    "log-file": `pr-shepherd 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]
+
+Flags:
+  --format text|json   Print a raw path or {"path": "..."} JSON. Default: text.
+  --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.
+
+Exit code: 0 on success; 1 if repository identity cannot be resolved.`,
+};

package/bin/cli/help-top-page.mjs

@@ -0,0 +1,59 @@
+export const TOP_USAGE = `pr-shepherd
+
+Autonomous PR CI monitor and review-comment resolver for agentic coding tools.
+
+Usage:
+  pr-shepherd --version | -v
+  pr-shepherd --help | -h
+  pr-shepherd [PR] [poll-flags] [iterate-flags]
+  pr-shepherd iterate [PR] [iterate-flags]
+  pr-shepherd poll [PR] [poll-flags] [iterate-flags]
+  pr-shepherd resolve [PR] [resolve-flags]
+  pr-shepherd commit-suggestion [PR] --thread-id ID --message MSG [flags]
+  pr-shepherd clean <pr|branch|current|repo|all> [value] [flags]
+  pr-shepherd log-file [--format text|json]
+
+Commands:
+  [PR]                 Poll until non-WAIT or timeout. This is the default command.
+  iterate              Run one iterate tick (single-tick alias).
+  poll                 Re-run iterate while the action is WAIT, then print the final tick.
+  resolve              Fetch actionable review items, or resolve/minimize/dismiss IDs.
+  commit-suggestion    Convert one GitHub suggestion thread into a patch and commit instructions.
+  clean                Remove pr-shepherd state files.
+  log-file             Print the per-worktree debug log path.
+
+PR argument:
+  PR may be a number such as 42 or a GitHub pull request URL.
+  When omitted, pr-shepherd infers the current branch's pull request.
+
+Common flags:
+  --format text|json   Output Markdown text or JSON. Default: text.
+  --verbose            Include verbose iterate fields and detailed poll-tick lines.
+  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.
+
+Iterate flags:
+  --ready-delay <duration>       Settle window before a clean PR cancels. Example: 15m.
+  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration.
+  --no-auto-mark-ready           Do not convert draft PRs to ready for review.
+  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.
+
+Poll flags:
+  --interval <duration>          Sleep between WAIT ticks. Default: 30s.
+  --timeout <duration>           Maximum poll wall-clock wait. Default: 5m.
+
+Clean variants:
+  pr [number]          Remove state for one PR. Defaults to current branch PR.
+  branch [name]        Remove state for a branch's PR. Defaults to current branch.
+  current              Alias for branch against the current branch.
+  repo                 Remove all state for the current repository.
+  all                  Remove all pr-shepherd state.
+
+Exit codes for iterate and poll:
+  0  WAIT or MARK_READY
+  1  FIX_CODE, or a command/validation error
+  2  CANCEL
+  3  ESCALATE
+
+Durations accept seconds, minutes, or hours: 30s, 2m, 1h, or bare seconds.
+
+Run 'pr-shepherd <command> --help' for command-specific details.`;

package/bin/cli/help.mjs

@@ -1,35 +1,9 @@
 import { hasFlag } from "./args.mjs";
+import { COMMAND_USAGE } from "./help-command-pages.mjs";
+import { TOP_USAGE } from "./help-top-page.mjs";
 export const USAGE = {
-    top: "Usage:\n" +
-        "  pr-shepherd --version | -v\n" +
-        "  pr-shepherd [PR] [--format text|json] [--ready-delay Nm]\n" +
-        "                 [--stall-timeout <duration>] [--no-auto-mark-ready]\n" +
-        "                 [--no-auto-cancel-actionable]\n" +
-        "  pr-shepherd resolve [PR] [--fetch] [--resolve-thread-ids A,B] [--minimize-comment-ids X,Y]\n" +
-        "                           [--dismiss-review-ids Q] [--message MSG] [--require-sha SHA]\n" +
-        "  pr-shepherd commit-suggestion [PR] --thread-id ID --message MSG [--description DESC]\n" +
-        "                                     [--format text|json]\n" +
-        "  pr-shepherd iterate [PR] [--format text|json] [--ready-delay Nm]\n" +
-        "                             [--stall-timeout <duration>] [--no-auto-mark-ready]\n" +
-        "                             [--no-auto-cancel-actionable]\n" +
-        "  pr-shepherd poll [PR] [--interval 30s] [--timeout 5m] [--format text|json] [--ready-delay Nm]\n" +
-        "                        [--stall-timeout <duration>] [--no-auto-mark-ready]\n" +
-        "                        [--no-auto-cancel-actionable]\n" +
-        "  pr-shepherd clean <pr|branch|current|repo|all> [value] [--dry-run] [--format text|json]\n" +
-        "  pr-shepherd log-file [--format text|json]",
-    resolve: "Usage: pr-shepherd resolve [PR] [--fetch] [--resolve-thread-ids A,B]\n" +
-        "                               [--minimize-comment-ids X,Y] [--dismiss-review-ids Q]\n" +
-        "                               [--message MSG] [--require-sha SHA]",
-    "commit-suggestion": "Usage: pr-shepherd commit-suggestion [PR] --thread-id ID --message MSG\n" +
-        "                                          [--description DESC] [--format text|json]",
-    iterate: "Usage: pr-shepherd iterate [PR] [--format text|json] [--ready-delay Nm]\n" +
-        "                                [--stall-timeout <duration>] [--no-auto-mark-ready]\n" +
-        "                                [--no-auto-cancel-actionable]",
-    poll: "Usage: pr-shepherd poll [PR] [--interval 30s] [--timeout 5m] [--format text|json]\n" +
-        "                             [--ready-delay Nm] [--stall-timeout <duration>]\n" +
-        "                             [--no-auto-mark-ready] [--no-auto-cancel-actionable]",
-    clean: "Usage: pr-shepherd clean <pr|branch|current|repo|all> [value] [--dry-run] [--format text|json]",
-    "log-file": "Usage: pr-shepherd log-file [--format text|json]",
+    top: TOP_USAGE,
+    ...COMMAND_USAGE,
 };
 /** Prints usage for `key` to stdout and returns true if `--help` or `-h` is in args. */
 export function maybePrintHelp(args, key) {

package/bin/cli/iterate-emitter.mjs

@@ -3,7 +3,6 @@ import { formatIterateResult, projectIterateLean, projectIterateVerbose } from "
 export function emitIterateResult(result, opts) {
     const projectionOpts = {
         readyDelaySuffix: opts.readyDelaySuffix,
-        runner: opts.runner,
     };
     if (opts.format === "json") {
         const output = opts.verbose

package/bin/cli/iterate-formatter.mjs

@@ -18,7 +18,6 @@ import { adaptIterateLog, buildSimpleIterateInstructions, numberInstructions, }
 export function formatIterateResult(result, opts) {
     const verbose = opts?.verbose ?? false;
     const readyDelaySuffix = opts?.readyDelaySuffix;
-    const runner = opts?.runner;
     const heading = `# PR #${result.pr} [${result.action.toUpperCase()}]`;
     const reviewDecisionSeg = result.mergeStatus === "BLOCKED" && result.reviewDecision
         ? ` · **reviewDecision** \`${result.reviewDecision}\``
@@ -87,13 +86,13 @@ export function formatIterateResult(result, opts) {
             return joinSections([
                 header,
                 adaptIterateLog(result.log),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix, runner))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix))}`,
             ]);
         case "mark_ready":
             return joinSections([
                 header,
                 adaptIterateLog(result.log),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix, runner))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix))}`,
             ]);
         case "cancel": {
             const cancelHeaderLines = [`${heading} — ${result.reason}`, "", baseLine, summaryLine];
@@ -102,19 +101,18 @@ export function formatIterateResult(result, opts) {
             return joinSections([
                 cancelHeaderLines.join("\n"),
                 adaptIterateLog(result.log),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix, runner))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix))}`,
             ]);
         }
         case "escalate":
             return joinSections([
                 header,
                 result.escalate.humanMessage,
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix, runner))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, readyDelaySuffix))}`,
             ]);
         case "fix_code":
             return formatFixCodeResult(header, result, {
                 readyDelaySuffix,
-                runner,
             });
     }
 }

package/bin/cli/iterate-instructions.mjs

@@ -3,8 +3,8 @@ import { buildPrShepherdCommand } from "./runner.mjs";
 function buildRecheckInstruction(rerunCommand, purpose) {
     return `Recheck: rerun \`${rerunCommand}\` to ${purpose} once after a fresh 30s–4m delay.`;
 }
-export function buildSimpleIterateInstructions(result, readyDelaySuffix, runner) {
-    const rerunCommand = buildIterateCommand(result.pr, readyDelaySuffix, runner);
+export function buildSimpleIterateInstructions(result, readyDelaySuffix) {
+    const rerunCommand = buildIterateCommand(result.pr, readyDelaySuffix);
     switch (result.action) {
         case "wait":
             return [buildRecheckInstruction(rerunCommand, "continue the active goal")];
@@ -20,8 +20,8 @@ export function buildSimpleIterateInstructions(result, readyDelaySuffix, runner)
             ];
     }
 }
-export function adaptFixCodeInstructions(instructions, pr, readyDelaySuffix, runner) {
-    const rerunCommand = buildIterateCommand(pr, readyDelaySuffix, runner);
+export function adaptFixCodeInstructions(instructions, pr, readyDelaySuffix) {
+    const rerunCommand = buildIterateCommand(pr, readyDelaySuffix);
     return instructions.map((instruction) => {
         if (instruction === FIX_INSTRUCTION_STOP) {
             return `${instruction} ${buildRecheckInstruction(rerunCommand, "recheck")}`;
@@ -32,11 +32,9 @@ export function adaptFixCodeInstructions(instructions, pr, readyDelaySuffix, run
 export function adaptIterateLog(log) {
     return log.replace(/\s+—\s+\d+s until auto-cancel/g, "");
 }
-export function buildIterateCommand(pr, readyDelaySuffix, runner) {
+export function buildIterateCommand(pr, readyDelaySuffix) {
     const suffix = readyDelaySuffix?.trim();
-    return buildPrShepherdCommand([String(pr), ...(suffix ? ["--ready-delay", suffix] : [])], {
-        runner,
-    }).text;
+    return buildPrShepherdCommand([String(pr), ...(suffix ? ["--ready-delay", suffix] : [])]).text;
 }
 export function numberInstructions(instructions) {
     return instructions.map((instruction, i) => `${i + 1}. ${instruction}`).join("\n");