pr-shepherd 0.37.0 → 0.37.1

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

package/README.md

@@ -29,11 +29,11 @@ The MCP server exposes three tools: `iterate`, `apply`, and `build_suggestion_pa
 
 Each tick returns exactly one action:
 
-- `WAIT` — no immediate action; poll can recheck until timeout.
-- `MARK_READY` — the CLI already converted an eligible draft PR to ready for review.
-- `FIX_CODE` — review items, failing CI, conflicts, or minimization work need agent action.
-- `CANCEL` — terminal success for merged/closed PRs or elapsed ready-delay.
-- `ESCALATE` — manual direction is needed.
+- `WAIT` — no immediate action; continue with the next poll.
+- `MARK_READY` — the CLI converted an eligible draft PR to ready; continue polling.
+- `FIX_CODE` — agent work is required; complete it, then continue polling.
+- `CANCEL` — stop polling because the PR merged, closed, or completed its ready-delay.
+- `ESCALATE` — stop polling until a human provides direction.
 
 Example shape:
 
@@ -65,10 +65,12 @@ Conversations Resolved: No [Not Required]
 
 ## Instructions
 
-1. Decide for each item under `## Review threads` and `## Failing checks` whether a code change is warranted. If code changes are needed, apply edits, commit, push, then run the `apply review:` command.
-2. For each failing check under `## Failing checks`: fetch logs when needed and decide whether to rerun or fix.
-3. Run the `apply review:` command shown above, substituting `$HEAD_SHA` and `$DISMISS_MESSAGE`.
-4. Stop this iteration.
+1. Review each item under `## Review threads` and `## Failing checks` and decide whether it needs a code change.
+2. Apply every warranted review fix in each file referenced above.
+3. Read the included CI log excerpt; fetch the full log if needed, then rerun transient failures or fix real failures.
+4. If you changed code, commit any remaining changes and push before review mutations. Otherwise, do not commit or push.
+5. Replace `$HEAD_SHA` and `$DISMISS_MESSAGE`, then run the `apply review:` command shown above.
+6. `[FIX_CODE]` is non-terminal. Continue with the next poll using the same CLI mode and flags, or call MCP `iterate` again.
 ```
 
 See [docs/actions.md](docs/actions.md) for the complete output contract. Iterate/poll PR outcomes use exit codes `0` and `10`–`14`; command and GitHub failures use `sysexits.h` codes — [docs/exit-codes.md](docs/exit-codes.md).

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

@@ -176,7 +176,7 @@ Flags:
 
 PR may be a number or GitHub pull request URL. When omitted, the current branch PR is inferred.
 Exit code: 0 on success; nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
-    readonly iterate: "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\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 code action; run another iterate tick later.\n  MARK_READY  Draft PR was marked ready for review.\n  FIX_CODE    Apply fixes, commit, push, and run the printed apply command.\n  CANCEL      Terminal state: merged/closed or ready-delay elapsed.\n  ESCALATE    Terminal state requiring human direction.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+    readonly iterate: "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\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  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\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 WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR] [poll-flags] [iterate-flags]\n\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\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 single dot to stderr by default; --quiet-status prints only changed WAIT snapshots, 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 FIX_CODE, CANCEL, or ESCALATE.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
     readonly clean: `pr-shepherd clean
 

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

@@ -1,4 +1,4 @@
-export declare const ITERATE_USAGE = "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\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 code action; run another iterate tick later.\n  MARK_READY  Draft PR was marked ready for review.\n  FIX_CODE    Apply fixes, commit, push, and run the printed apply command.\n  CANCEL      Terminal state: merged/closed or ready-delay elapsed.\n  ESCALATE    Terminal state requiring human direction.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+export declare const ITERATE_USAGE = "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\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  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\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 WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR] [poll-flags] [iterate-flags]\n\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\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 single dot to stderr by default; --quiet-status prints only changed WAIT snapshots, 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 FIX_CODE, CANCEL, or ESCALATE.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
 /** Public help page for the default PR polling invocation. */
 export declare const DEFAULT_USAGE: string;

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

@@ -18,11 +18,11 @@ Iterate flags:
 Durations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number is minutes; decimals are allowed only with an explicit unit (4.5m).
 
 Actions:
-  WAIT        No immediate code action; run another iterate tick later.
-  MARK_READY  Draft PR was marked ready for review.
-  FIX_CODE    Apply fixes, commit, push, and run the printed apply command.
-  CANCEL      Terminal state: merged/closed or ready-delay elapsed.
-  ESCALATE    Terminal state requiring human direction.
+  WAIT        No immediate action; continue with the next poll.
+  MARK_READY  Draft PR was marked ready; continue with the next poll.
+  FIX_CODE    Agent action is required; follow the instructions, then continue polling.
+  CANCEL      Stop polling: merged/closed or ready-delay elapsed.
+  ESCALATE    Stop polling until a human provides direction.
 
 Exit codes:
   0   CANCEL (merged or ready-delay elapsed)

package/bin/cli/help.d.mts

@@ -176,7 +176,7 @@ Flags:
 
 PR may be a number or GitHub pull request URL. When omitted, the current branch PR is inferred.
 Exit code: 0 on success; nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
-    readonly iterate: "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\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 code action; run another iterate tick later.\n  MARK_READY  Draft PR was marked ready for review.\n  FIX_CODE    Apply fixes, commit, push, and run the printed apply command.\n  CANCEL      Terminal state: merged/closed or ready-delay elapsed.\n  ESCALATE    Terminal state requiring human direction.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
+    readonly iterate: "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\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  FIX_CODE    Agent action is required; follow the instructions, then continue polling.\n  CANCEL      Stop polling: merged/closed or ready-delay elapsed.\n  ESCALATE    Stop polling until a human provides direction.\n\nExit codes:\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\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 WAIT ticks and during the FIX_CODE debounce window. Print only the\nfinal tick to stdout.\nPoll exits as soon as iterate returns MARK_READY, CANCEL, or ESCALATE, or when timeout\nreturns the last WAIT result. FIX_CODE starts a --debounce settle window (default 1m): poll keeps\niterating at --interval, then runs one more tick after the window and returns that result.\nWith --until-terminal, poll also continues through MARK_READY.\n\nUsage:\n  pr-shepherd poll [PR] [poll-flags] [iterate-flags]\n\nPoll flags:\n  --interval <duration>          Sleep between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Maximum wall-clock wait for WAIT ticks. Bare number = seconds. Default: 4.5m.\n  --debounce <duration>          Settle window after first FIX_CODE before returning. Bare number = seconds. Default: 60s. 0 disables.\n  --quiet-status                 During WAIT polling, print only changed status snapshots.\n  --until-terminal               Continue through WAIT/MARK_READY until FIX_CODE/CANCEL/ESCALATE.\n\nForwarded iterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    Do not cancel in-progress runs before actionable fixes.\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 single dot to stderr by default; --quiet-status prints only changed WAIT snapshots, 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 FIX_CODE, CANCEL, or ESCALATE.\n\nExit codes: same as iterate (the final tick's action/reason decides the code).\n  0   CANCEL (merged or ready-delay elapsed)\n  10  WAIT (including a WAIT returned by --timeout)\n  11  MARK_READY\n  12  FIX_CODE\n  13  ESCALATE\n  14  CANCEL (closed without merging)\n  A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).";
     readonly clean: `pr-shepherd clean
 

package/bin/cli/iterate-instructions.mjs

@@ -1,17 +1,17 @@
 export function buildSimpleIterateInstructions(result) {
     switch (result.action) {
         case "wait":
-            return ["No action this tick — the poll loop reruns automatically."];
+            return [
+                "No action is needed this tick. Continue with the next poll using the same interface and mode: rerun the current `pr-shepherd` CLI invocation with its flags, or call MCP `iterate` again.",
+            ];
         case "mark_ready":
             return [
-                "The CLI already marked the PR ready for review. No further action this tick — the poll loop reruns automatically.",
+                "The CLI marked the PR ready for review. Continue with the next poll using the same interface and mode: rerun the current `pr-shepherd` CLI invocation with its flags, or call MCP `iterate` again.",
             ];
         case "cancel":
-            return ["Stop — the active goal is complete."];
+            return ["Stop — the PR loop is complete. No further polling is needed."];
         case "escalate":
-            return [
-                "Stop — the PR needs human direction before iterating can resume. This is a manual handoff; do not continue automated fix attempts.",
-            ];
+            return ["Stop — human direction is required before automated polling can resume."];
     }
 }
 export function adaptIterateLog(log) {

package/bin/commands/commit-suggestion-instruction.d.mts

@@ -5,4 +5,4 @@
  *   e.g. `"## Review threads"`.
  * @param includeDriftHint - Whether to add the trailing note about drift on failed apply.
  */
-export declare function buildCommitSuggestionInstruction(prNumber: number, sectionName: string, includeDriftHint: boolean): string;
+export declare function buildCommitSuggestionInstruction(prNumber: number, sectionName: string, includeDriftHint: boolean): string[];

package/bin/commands/commit-suggestion-instruction.mjs

@@ -17,7 +17,12 @@ export function buildCommitSuggestionInstruction(prNumber, sectionName, includeD
         "--format=json",
     ]).text;
     const driftHint = includeDriftHint
-        ? " If the patch fails to apply (drift since the suggestion was written), fall through to the manual fix step."
-        : " If the patch fails to apply, fall through to the manual-edit step.";
-    return `For each thread marked \`[suggestion]\` under \`${sectionName}\`: run \`${command}\` to retrieve the patch and suggested commit. The CLI does not mutate the working tree — apply the patch yourself (run \`git apply\` with the diff shown, or edit the file directly using the line range), then stage the listed file and run the suggested \`git commit\` from the \`## Instructions\` section. Human-authored thread IDs are replied to by the apply command below; Shepherd does not auto-resolve them.${driftHint} Do not retry the same command.`;
+        ? "If the patch does not apply because the suggestion drifted, use the manual-fix step below. Do not retry the command."
+        : "If the patch does not apply, use the manual-edit step below. Do not retry the command.";
+    return [
+        `For each thread marked \`[suggestion]\` under \`${sectionName}\`, run \`${command}\` to retrieve its patch and suggested commit.`,
+        "The CLI only builds the patch. Apply it, stage the listed file, and follow the returned commit instructions.",
+        driftHint,
+        "Keep human-authored thread IDs in `apply review:` so Shepherd replies instead of resolving them.",
+    ];
 }

package/bin/commands/iterate/check-instructions.d.mts

@@ -14,3 +14,4 @@ export declare function buildBehindBaseHintInstruction(baseBranch: string, hint:
 /** Build the `Run the apply review: command` instruction, including its optional substitution hint. */
 export declare function buildResolveCommandInstruction(resolveCommand: ResolveCommand): string[];
 export declare function buildFailingCheckInstructions(checks: AgentCheck[]): string[];
+export declare function buildFixCompletionInstruction(checks: AgentCheck[]): string;

package/bin/commands/iterate/check-instructions.mjs

@@ -1,12 +1,9 @@
 /** Build the stale-CR clause appended to the `## Changes-requested reviews` instruction. */
 export function buildCrStaleClause(reviews) {
-    const bot = reviews.some((r) => r.staleBotCr)
-        ? " `[pending dismissal — already surfaced]` bullets are bot CRs from a prior tick."
-        : "";
     const human = reviews.some((r) => r.staleReview && !r.staleBotCr)
-        ? " `[stale]` bullets are human CRs on an old commit; ask reviewer to re-review."
+        ? " `[stale]` bullets are human CRs on an old commit. Ask the reviewer to re-review."
         : "";
-    return bot + human;
+    return human;
 }
 /**
  * Build the optional behind-base push hint. Empty unless the branch is actually behind its base
@@ -21,7 +18,7 @@ export function buildBehindBaseHintInstruction(baseBranch, hint, isBehind) {
     const trimmedHint = typeof hint === "string" ? hint.trim() : "";
     if (!isBehind || trimmedHint === "")
         return [];
-    return [`The branch is behind \`origin/${baseBranch}\` — ${trimmedHint} before pushing.`];
+    return [`The branch is behind \`origin/${baseBranch}\`. ${trimmedHint} before pushing.`];
 }
 /** Build the `Run the apply review: command` instruction, including its optional substitution hint. */
 export function buildResolveCommandInstruction(resolveCommand) {
@@ -29,17 +26,15 @@ export function buildResolveCommandInstruction(resolveCommand) {
         return [];
     const instructions = [];
     if ((resolveCommand.replyThreadIds?.length ?? 0) > 0) {
-        instructions.push(`Before running the \`apply review:\` command, remove any thread from \`--reply-thread-ids\` if the latest visible comment in that thread is your own prior Shepherd reply. Do not reply to your own comments.`);
+        instructions.push("Before `apply review:`, remove any `--reply-thread-ids` entry whose latest visible comment is your own Shepherd reply. Do not reply to yourself.");
     }
-    const substituteParts = [];
     if (resolveCommand.requiresHeadSha) {
-        substituteParts.push(`\`$HEAD_SHA\` with the pushed commit SHA (or \`$(git rev-parse HEAD)\` if you did not push)`);
+        instructions.push("Replace `$HEAD_SHA` with the pushed commit SHA, or `$(git rev-parse HEAD)` if you did not push.");
     }
     if (resolveCommand.requiresDismissMessage) {
-        substituteParts.push(`\`$DISMISS_MESSAGE\` with a one-sentence reply/description of what you changed`);
+        instructions.push("Replace `$DISMISS_MESSAGE` with one sentence describing what changed.");
     }
-    const substituteHint = substituteParts.length > 0 ? `, substituting ${substituteParts.join(" and ")}` : "";
-    instructions.push(`Run the \`apply review:\` command shown above${substituteHint}.`);
+    instructions.push("Run the `apply review:` command shown above.");
     return instructions;
 }
 export function buildFailingCheckInstructions(checks) {
@@ -50,21 +45,28 @@ export function buildFailingCheckInstructions(checks) {
     const hasStartupFailure = checks.some((c) => c.runId && c.conclusion === "STARTUP_FAILURE");
     const hasExternal = checks.some((c) => !c.runId && c.detailsUrl);
     const hasBare = checks.some((c) => !c.runId && !c.detailsUrl);
-    const parts = [];
+    const instructions = [];
     if (hasRunId) {
-        parts.push("read any included log excerpt first; fetch the full log with `gh run view <runId> --log-failed` if insufficient; rerun with `gh run rerun <runId> --failed` for transient infra failures, or apply a code fix for real test/build failures; if API/log output lacks detail, open the run URL in the GitHub UI");
+        instructions.push("For each GitHub Actions failure under `## Failing checks`, read the included log excerpt first.", "If the excerpt is insufficient, run `gh run view <runId> --log-failed`. Open the run URL only if the API still lacks detail.", "Rerun transient infrastructure failures with `gh run rerun <runId> --failed`. Apply a code fix for real test or build failures.");
     }
     if (hasCancelled) {
-        parts.push("for `[conclusion: CANCELLED]` entries (not concurrency-superseded — see `**superseded**`): rerun with `gh run rerun <runId>` unless already pushing new commits this tick, in which case the fresh run supersedes it; don't treat as resolved — distinct from `## Cancelled runs`");
+        instructions.push("For each `[conclusion: CANCELLED]` failure, run `gh run rerun <runId>` unless this tick will push new commits.", "Do not treat a cancelled failure as resolved. `## Cancelled runs` is a different section.");
     }
     if (hasStartupFailure) {
-        parts.push("for `[conclusion: STARTUP_FAILURE]` entries: inspect with `gh run view <runId>`, rerun with `gh run rerun <runId>` if warranted");
+        instructions.push("For each `[conclusion: STARTUP_FAILURE]` failure, inspect it with `gh run view <runId>` and rerun it with `gh run rerun <runId>` if warranted.");
     }
     if (hasExternal) {
-        parts.push("for `external` entries: open the URL to inspect the failure");
+        instructions.push("For each `external` failure, open its URL and inspect it.");
     }
     if (hasBare) {
-        parts.push("for `(no runId)` entries: no log or URL available — escalate to a human");
+        instructions.push("For each `(no runId)` failure, escalate to a human because no log or URL is available.");
+    }
+    return instructions;
+}
+export function buildFixCompletionInstruction(checks) {
+    const requiresHumanHandoff = checks.some((check) => !check.runId && !check.detailsUrl);
+    if (requiresHumanHandoff) {
+        return "`[FIX_CODE]` requires a human handoff for an uninspectable failing check. Stop polling after escalating, and resume only after human direction.";
     }
-    return [`For each failing check under \`## Failing checks\`: ${parts.join("; ")}.`];
+    return "`[FIX_CODE]` is non-terminal. After completing these steps, continue with the next poll using the same interface and mode: rerun the current `pr-shepherd` CLI invocation with its flags, or call MCP `iterate` again.";
 }

package/bin/commands/iterate/render.mjs

@@ -1,9 +1,8 @@
 import { renderShellCommand } from "../../cli/runner.mjs";
-import { buildFailingCheckInstructions, buildCrStaleClause, buildBehindBaseHintInstruction, buildResolveCommandInstruction, } from "./check-instructions.mjs";
+import { buildFailingCheckInstructions, buildCrStaleClause, buildBehindBaseHintInstruction, buildResolveCommandInstruction, buildFixCompletionInstruction, } from "./check-instructions.mjs";
 import { SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS, buildShepherdJournalInstruction, } from "../shepherd-journal.mjs";
 import { isFailingAgentCheck } from "../../checks/conclusions.mjs";
 import { buildCommitSuggestionInstruction } from "../commit-suggestion-instruction.mjs";
-const FIX_INSTRUCTION_STOP = "Stop this iteration — if you pushed new commits, CI needs time before the next tick; otherwise stop before the next tick.";
 /** Render a resolve command as a shell snippet. Appends `--require-sha "$HEAD_SHA"` when set. */
 export function renderResolveCommand(rc) {
     const parts = [...rc.argv];
@@ -21,7 +20,7 @@ isBehind = false) {
         hasAnnotations ||
         changesRequestedReviews.length > 0 ||
         actionableComments.length > 0;
-    // Leading decision or mandatory instruction depending on what actionable items exist.
+    // Start with interpretation. The agent decides what raw feedback warrants a code change.
     if (hasNonConflictHints) {
         const actionableSections = [];
         if (threads.length > 0)
@@ -36,74 +35,74 @@ isBehind = false) {
         if (changesRequestedReviews.length > 0)
             actionableSections.push("`## Changes-requested reviews`");
         const sectionRef = actionableSections.length > 0 ? `under ${actionableSections.join(", ")}` : "above";
-        const resolveClause = resolveCommand.hasMutations
-            ? ", then run the `apply review:` command"
-            : "";
-        if (hasConflicts) {
-            // Conflicts make push mandatory regardless of whether code edits are needed.
-            instructions.push(`The branch has merge conflicts that must be resolved before merging (see \`**branch**\` above). Apply any code edits for items ${sectionRef}, then commit and push${resolveClause}.`);
-        }
-        else {
-            const skipClause = resolveCommand.hasMutations
-                ? "skip the commit/push and run the `apply review:` command"
-                : "no push is needed";
-            instructions.push(`Decide for each item ${sectionRef} whether a code change is warranted. **If any code changes are needed:** apply edits, commit, push${resolveClause}. **If no code changes are needed:** ${skipClause}.`);
-        }
+        instructions.push(`Review each item ${sectionRef} and decide whether it needs a code change.`);
     }
-    else if (hasConflicts) {
-        instructions.push(`The branch has merge conflicts that must be resolved before merging (see \`**branch**\` above). Resolve them and push.`);
+    if (hasConflicts) {
+        instructions.push("The branch has merge conflicts (see `**branch**` above). Resolve them before committing and pushing.");
+    }
+    const firstLookTotal = firstLookThreads.length + firstLookComments.length;
+    if (firstLookTotal > 0) {
+        instructions.push("Review every item under `## First-look items` before acting.", "If a first-look thread also appears under `## Review threads to resolve`, its ID is already in `apply review:`. Do not add first-look-only IDs to mutation flags.");
+    }
+    if (firstLookSummaries.length > 0)
+        instructions.push(SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE);
+    const editedTotal = editedSummaries.length +
+        actionableComments.filter((c) => c.edited).length +
+        firstLookThreads.filter((t) => t.edited).length +
+        firstLookComments.filter((c) => c.edited).length;
+    if (editedTotal > 0) {
+        instructions.push("Read every item marked `[edited since first look]`, including edited summaries and edited first-look bullets, before deciding whether to resolve a matching thread.");
     }
-    instructions.push(...buildBehindBaseHintInstruction(baseBranch, behindBaseHint, isBehind));
     if (inProgressRunIds.length > 0) {
-        instructions.push(`If you decide to push new commits: cancel each in-progress run listed under \`## In-progress runs\` before applying code fixes (e.g. \`gh run cancel <id>\`). Runs may complete between the tick and your action; treat cancellation errors on already-finished runs as non-fatal. Skip this step if you are only resolving threads without pushing — the existing runs remain relevant.`);
+        instructions.push("If you will push, first cancel every ID under `## In-progress runs` with `gh run cancel <id>`.", "Ignore cancellation errors for runs that already finished.", "If you will not push, leave the in-progress runs alone.");
+    }
+    if (cancelledCount > 0) {
+        instructions.push("Do not cancel the IDs under `## Cancelled runs` again. The CLI already cancelled them.");
     }
     const hasSuggestions = threads.some((t) => t.suggestion);
     if (hasSuggestions)
-        instructions.push(buildCommitSuggestionInstruction(prNumber, "## Review threads", false));
+        instructions.push(...buildCommitSuggestionInstruction(prNumber, "## Review threads", false));
     if (threads.length > 0 || actionableComments.length > 0) {
         // Actionable comments carry no file/line location (unlike threads), so "referenced above"
         // is only accurate when threads are present.
         const filesRef = threads.length > 0 ? "each file referenced above" : "the relevant files";
-        const suggestionFallback = hasSuggestions
-            ? ` When applying a \`[suggestion]\` thread manually (e.g. after a failed \`build-suggestion-patch\` run), replace the exact line range shown in the heading (\`path:startLine-endLine\`) with the replacement shown in its \`Replaces lines …\` block verbatim — an empty replacement deletes those lines, a single blank line replaces the range with one blank line.`
-            : "";
-        instructions.push(`Apply code fixes: read and edit ${filesRef}.${suggestionFallback}`);
+        instructions.push(`Apply every warranted review fix in ${filesRef}.`);
+        if (hasSuggestions) {
+            instructions.push("For a manual `[suggestion]` fix, replace the heading's exact `path:startLine-endLine` range with the `Replaces lines …` block verbatim. An empty replacement deletes the range. One blank line replaces it with one blank line.");
+        }
     }
     if (resolutionOnlyThreads.length > 0) {
-        instructions.push(`Review the threads under \`## Review threads to resolve\`. Human-authored threads are replied to by the \`apply review:\` command shown below; Shepherd does not resolve them. Bot/non-human threads are included in \`--resolve-thread-ids\`.`);
+        instructions.push("Review the threads under `## Review threads to resolve` before running mutations.", "Use the generated commands as shown. Human-authored IDs use `--reply-thread-ids`. Bot and non-human IDs use `--resolve-thread-ids`. Shepherd does not resolve human-authored threads.");
     }
     instructions.push(...buildFailingCheckInstructions(failingChecks));
     if (hasAnnotations) {
-        instructions.push(`For each item under \`## Check annotations\`: inspect the referenced file range and decide whether the annotation requires a code change. These annotations are surfaced once per PR and do not need any resolve/minimize mutation.`);
+        instructions.push("Inspect every referenced range under `## Check annotations` and apply any warranted change.", "Do not add annotation IDs to resolve or minimize mutations.");
     }
     if (changesRequestedReviews.length > 0) {
         const staleClause = buildCrStaleClause(changesRequestedReviews);
-        instructions.push(`For each bullet under \`## Changes-requested reviews\` above: read the review body and apply the requested changes.${staleClause}`);
+        instructions.push(`Read every body under \`## Changes-requested reviews\` and apply any warranted change.${staleClause}`);
         if ((resolveCommand.dismissReviewIds?.length ?? 0) > 0)
-            instructions.push(`Pass every ID listed in \`--dismiss-review-ids\` to the \`apply review:\` command verbatim — these are bot/non-human CR reviews that the agent (not the author) must dismiss. Dropping an ID leaves the PR in \`CHANGES_REQUESTED\` state; the next tick re-surfaces it as \`[pending dismissal]\` and an unattended bot CR escalates after \`iterate.stallTimeoutMinutes\`.`);
+            instructions.push("Keep every existing `--dismiss-review-ids` ID in `apply review:`. Each is a bot or non-human review that must be dismissed. Omitting one leaves the PR in `CHANGES_REQUESTED`.");
     }
-    if (resolveOnlyCommand?.hasMutations)
-        instructions.push(`Run the \`resolve-only:\` command shown above — no substitutions needed.`);
-    instructions.push(...buildResolveCommandInstruction(resolveCommand));
-    if (cancelledCount > 0) {
-        instructions.push(`Do not re-run \`gh run cancel\` on the IDs listed under \`## Cancelled runs\` — those runs were already cancelled by the CLI before this turn.`);
-    }
-    const firstLookTotal = firstLookThreads.length + firstLookComments.length;
-    if (firstLookTotal > 0) {
-        instructions.push(`Items in \`## First-look items\` are shown so you can acknowledge their current status before acting. If a first-look thread also appears under \`## Review threads to resolve\`, its ID is already included in the \`apply review:\` command; otherwise do not pass first-look-only IDs to mutation flags.`);
+    instructions.push(...buildBehindBaseHintInstruction(baseBranch, behindBaseHint, isBehind));
+    const hasReviewMutations = resolveCommand.hasMutations || resolveOnlyCommand?.hasMutations === true;
+    const mutationSuffix = hasReviewMutations ? " before review mutations" : "";
+    if (hasConflicts) {
+        instructions.push(`Commit any remaining changes and push the conflict resolution${mutationSuffix}.`);
     }
-    if (firstLookSummaries.length > 0)
-        instructions.push(SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE);
-    const editedTotal = editedSummaries.length +
-        actionableComments.filter((c) => c.edited).length +
-        firstLookThreads.filter((t) => t.edited).length +
-        firstLookComments.filter((c) => c.edited).length;
-    if (editedTotal > 0) {
-        instructions.push(`Items marked \`[edited since first look]\`, items under \`## Review summaries (edited since first look)\`, and any first-look bullet tagged \`, edited\` were updated by their author after you previously acknowledged them. Read the updated body before deciding whether any matching \`## Review threads to resolve\` item should be resolved.`);
+    else if (hasNonConflictHints) {
+        instructions.push(`If you changed code, commit any remaining changes and push${mutationSuffix}. Otherwise, do not commit or push.`);
     }
-    if (resolveCommand.hasMutations || hasNonConflictHints || firstLookTotal > 0) {
-        instructions.push(buildShepherdJournalInstruction(prNumber, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS));
+    if (hasReviewMutations ||
+        hasNonConflictHints ||
+        firstLookTotal > 0 ||
+        firstLookSummaries.length > 0 ||
+        editedTotal > 0) {
+        instructions.push(...buildShepherdJournalInstruction(prNumber, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS));
     }
-    instructions.push(FIX_INSTRUCTION_STOP);
+    if (resolveOnlyCommand?.hasMutations)
+        instructions.push("Run the `resolve-only:` command shown above.");
+    instructions.push(...buildResolveCommandInstruction(resolveCommand));
+    instructions.push(buildFixCompletionInstruction(failingChecks));
     return instructions;
 }

package/bin/commands/shepherd-journal.d.mts

@@ -1,7 +1,7 @@
 export declare const SHEPHERD_JOURNAL_SECTION = "## Shepherd Journal";
 export declare const SHEPHERD_JOURNAL_SECTION_PATTERN: RegExp;
 export declare const SHEPHERD_JOURNAL_APPEND_HINT = "If this section already exists, append your entries under it instead of creating a duplicate heading.";
-export declare const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review the bodies shown under `## Review summaries (first look)` \u2014 you are seeing these for the first time. Eligible non-human IDs, when present, are already included in `--minimize-comment-ids` in the `apply review:` or `resolve-only:` command above; if any warrants a Shepherd Journal note, append it before applying review mutations.";
-export declare function buildShepherdJournalInstruction(prNumber: number, itemReferenceGuidance: string): string;
-export declare const SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS = "For threads and comments, use the markdown link shown in its heading above; for reviews, reference the review ID.";
-export declare const SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEMS = "For threads and comments, use the markdown link shown in each item's bullet above; for reviews, reference the review ID.";
+export declare const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review each body under `## Review summaries (first look)`. Eligible non-human IDs are already in `--minimize-comment-ids`. Record any warranted Shepherd Journal note before review mutations.";
+export declare function buildShepherdJournalInstruction(prNumber: number, itemReferenceGuidance: string): string[];
+export declare const SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS = "Link threads and comments from their headings. Cite reviews by ID.";
+export declare const SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEMS = "Link threads and comments from their item bullets. Cite reviews by ID.";

package/bin/commands/shepherd-journal.mjs

@@ -1,13 +1,12 @@
 export const SHEPHERD_JOURNAL_SECTION = "## Shepherd Journal";
 export const SHEPHERD_JOURNAL_SECTION_PATTERN = /^##\s+Shepherd\s+Journal$/;
 export const SHEPHERD_JOURNAL_APPEND_HINT = "If this section already exists, append your entries under it instead of creating a duplicate heading.";
-export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review the bodies shown under `## Review summaries (first look)` — you are seeing these for the first time. Eligible non-human IDs, when present, are already included in `--minimize-comment-ids` in the `apply review:` or `resolve-only:` command above; if any warrants a Shepherd Journal note, append it before applying review mutations.";
+export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review each body under `## Review summaries (first look)`. Eligible non-human IDs are already in `--minimize-comment-ids`. Record any warranted Shepherd Journal note before review mutations.";
 export function buildShepherdJournalInstruction(prNumber, itemReferenceGuidance) {
     return [
-        `For any large decisions or rejections you made this iteration, run \`pr-shepherd apply journal ${prNumber} '- <decision>'\` to append an entry to the \`${SHEPHERD_JOURNAL_SECTION}\` section.`,
+        `For any substantial decision or rejection, append \`- <decision>\` to \`${SHEPHERD_JOURNAL_SECTION}\` with \`pr-shepherd apply journal ${prNumber} '- <decision>'\`.`,
         itemReferenceGuidance,
-        `The command is idempotent — re-running with the same text is a no-op.`,
-    ].join(" ");
+    ];
 }
-export const SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS = "For threads and comments, use the markdown link shown in its heading above; for reviews, reference the review ID.";
-export const SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEMS = "For threads and comments, use the markdown link shown in each item's bullet above; for reviews, reference the review ID.";
+export const SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS = "Link threads and comments from their headings. Cite reviews by ID.";
+export const SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEMS = "Link threads and comments from their item bullets. Cite reviews by ID.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.37.0",
+  "version": "0.37.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",
@@ -82,7 +82,7 @@
     "@vitest/coverage-v8": "^4.1.4",
     "husky": "^9.1.7",
     "knip": "^6.14.1",
-    "oxfmt": "^0.62.0",
+    "oxfmt": "^0.63.0",
     "oxlint": "^1.60.0",
     "typescript": "^7.0.2",
     "vitest": "^4.1.4"

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.37.0",
+  "version": "0.37.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/plugins/pr-shepherd/.codex.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "pr-shepherd": {
       "command": "npx",
-      "args": ["--yes", "--package", "pr-shepherd@0.37.0", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.37.1", "pr-shepherd-mcp"]
     }
   }
 }

package/plugins/pr-shepherd/.mcp.json

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.37.0", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.37.1", "pr-shepherd-mcp"]
   }
 }

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -16,4 +16,6 @@ Thin dispatcher for iterating a PR. Poll with the CLI; use MCP `iterate` only wh
 
 2. Run the poll command `pr-shepherd` with the optional PR argument and print its full result. Do not run `pr-shepherd iterate`. If the CLI is unavailable and the `iterate` MCP tool is available, call `iterate` and print its full result.
 
-3. Follow the returned instructions exactly. If this tick used MCP `iterate`, use MCP `apply` and `build_suggestion_patch` for the returned review mutations and suggestion patches — do not run a `pr-shepherd apply` shell command. If this tick used the CLI poll, run the printed apply command. After completing an action, run `pr-shepherd` again (or call `iterate` if only MCP is available) until a terminal action or the human directs you to stop.
+3. Print the full result and follow every returned `## Instructions` step exactly. For CLI output, run each printed mutation command when instructed. For MCP output, use MCP `apply` and `build_suggestion_patch`; do not run a shell `pr-shepherd apply` command.
+
+4. After completing the returned instructions, repeat step 2 unless the action is `[CANCEL]` or `[ESCALATE]`, the instructions require a human handoff, or the human directs you to stop.