pr-shepherd 0.38.0 → 0.39.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.38.0",
+  "version": "0.39.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -67,10 +67,13 @@ Conversations Resolved: No [Not Required]
 
 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.
+3. Triage every failure under `## Failing checks`. See "CI failure triage" in the pr-shepherd skill for `gh run view` / `gh run rerun` rules.
 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.
+5. Before `apply review:`, remove any `--reply-thread-ids` entry whose latest visible comment is your own Shepherd reply. Do not reply to yourself.
+6. Replace `$HEAD_SHA` with the pushed commit SHA, or `$(git rev-parse HEAD)` if you did not push.
+7. Replace `$DISMISS_MESSAGE` with one sentence describing what changed.
+8. Run the `apply review:` command shown above. See "Review-mutation mechanics" in the pr-shepherd skill for dismiss-ID retention.
+9. `[FIX_CODE]` is non-terminal. After completing these steps, iterate again with the same options to continue.
 ```
 
 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

@@ -177,7 +177,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 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 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 an explicit still-running line 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
 
 Remove pr-shepherd state files from PR_SHEPHERD_STATE_DIR.

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

@@ -1,4 +1,4 @@
 export declare const ITERATE_USAGE = "pr-shepherd iterate\n\nRun one iterate tick for a pull request. The no-subcommand form polls; use this subcommand for a single tick.\nThe output contains one action and an action-specific ## Instructions section.\n\nUsage:\n  pr-shepherd iterate [PR] [iterate-flags]\n\nIterate flags:\n  --ready-delay <duration>       Settle window before a clean PR cancels. Bare number = minutes. Example: 15m.\n  --stall-timeout <duration>     Escalate repeated unchanged failures after this duration. Bare number = minutes. 0 disables.\n  --no-auto-mark-ready           Do not convert draft PRs to ready for review.\n  --no-auto-cancel-actionable    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).";
+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 an explicit still-running line 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

@@ -63,7 +63,7 @@ Forwarded iterate flags:
 Durations accept s/m/h suffixes: 30s, 4.5m, 1h. A bare number uses each flag's default unit (seconds
 for --interval/--timeout/--debounce, minutes for --ready-delay/--stall-timeout); decimals are allowed only with
 an explicit unit (4.5m).
-Each WAIT tick writes a single dot to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.
+Each WAIT tick writes an explicit still-running line to stderr by default; --quiet-status prints only changed WAIT snapshots, and --verbose emits detailed per-tick lines.
 FIX_CODE debounce writes a remaining-seconds line to stderr. --timeout does not cut an in-flight debounce short.
 With --until-terminal, --timeout is ignored for WAIT ticks and polling continues until FIX_CODE, CANCEL, or ESCALATE.
 
@@ -76,4 +76,4 @@ Exit codes: same as iterate (the final tick's action/reason decides the code).
   14  CANCEL (closed without merging)
   A command/validation/GitHub failure exits with a sysexits.h code instead (see docs/exit-codes.md).`;
 /** Public help page for the default PR polling invocation. */
-export const DEFAULT_USAGE = POLL_USAGE.replaceAll("pr-shepherd poll", "pr-shepherd [PR]");
+export const DEFAULT_USAGE = POLL_USAGE.replace(/^pr-shepherd poll$/m, "pr-shepherd [PR]").replace(/^ {2}pr-shepherd poll \[PR\]/m, "  pr-shepherd [PR]");

package/bin/cli/help.d.mts

@@ -177,7 +177,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 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 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 an explicit still-running line 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
 
 Remove pr-shepherd state files from PR_SHEPHERD_STATE_DIR.

package/bin/cli/iterate-instructions.mjs

@@ -2,11 +2,11 @@ export function buildSimpleIterateInstructions(result) {
     switch (result.action) {
         case "wait":
             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.",
+                "Non-terminal — no action needed this tick. Iterate again with the same options to continue.",
             ];
         case "mark_ready":
             return [
-                "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.",
+                "The CLI marked the PR ready for review. Iterate again with the same options to continue.",
             ];
         case "cancel":
             return ["Stop — the PR loop is complete. No further polling is needed."];

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

@@ -1,5 +1,5 @@
 import type { CheckAnnotation, ClassifiedCheck, ShepherdReport, TriagedCheck } from "../types.mts";
-export declare function checksWithUnseenAnnotations(report: ShepherdReport): TriagedCheck[];
+export declare function checksWithActionableAnnotations(report: ShepherdReport): TriagedCheck[];
 export declare function attachAndMergeCheckAnnotations(buckets: {
     passing: ClassifiedCheck[];
     failing: TriagedCheck[];

package/bin/commands/check-annotations.mjs

@@ -2,14 +2,14 @@ import { fetchCheckRunAnnotations } from "../github/check-annotations.mjs";
 function shouldFetchCheckAnnotations(check) {
     return check.id != null && check.status === "COMPLETED" && check.hasAnnotations === true;
 }
-export function checksWithUnseenAnnotations(report) {
+export function checksWithActionableAnnotations(report) {
     return [
         ...report.checks.failing,
         ...report.checks.passing,
         ...report.checks.skipped,
         ...report.checks.filtered,
         ...(report.checks.ignored ?? []),
-    ].filter((c) => (c.annotations?.length ?? 0) > 0);
+    ].filter((c) => c.conclusion !== "SUCCESS" && (c.annotations?.length ?? 0) > 0);
 }
 export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber) {
     const candidates = [

package/bin/commands/check.mjs

@@ -7,7 +7,7 @@ import { deriveMergeStatus } from "../merge-status/derive.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { classifyVisibleComments } from "../comments/visible-comments.mjs";
 import { computeStatus } from "./check-status.mjs";
-import { attachAndMergeCheckAnnotations } from "./check-annotations.mjs";
+import { annotationMarkerBody, attachAndMergeCheckAnnotations } from "./check-annotations.mjs";
 import { buildTerminalReport } from "./check-terminal-report.mjs";
 import { isBlockedByFilteredCheck, refreshReadyMergeability, refreshUnknownMergeability, } from "./ready-mergeability.mjs";
 import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs";
@@ -85,7 +85,16 @@ export async function runCheck(opts) {
     const changesRequestedReviewVisibility = classifyChangesRequestedReviewsForDisplay(batchData.changesRequestedReviews.filter((r) => !partition.suppressedChangesRequestedIds.has(r.id)), seenMap, botUsernames);
     const approvedReviewVisibility = classifyReviewsForDisplay(batchData.approvedReviews, seenMap);
     if (opts.persistSeen !== false) {
+        const successfulAnnotations = [
+            ...merged.passing,
+            ...merged.skipped,
+            ...merged.filtered,
+            ...merged.ignored,
+        ]
+            .filter((check) => check.conclusion === "SUCCESS")
+            .flatMap((check) => check.annotations ?? []);
         await Promise.allSettled([
+            ...successfulAnnotations.map((a) => markSeen(stateKey, a.id, annotationMarkerBody(a))),
             ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
             ...threadVisibility.toMarkSeen.map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
             ...visibleCommentClassification.toMarkSeen.map((c) => markSeen(stateKey, c.id, c.body)),
@@ -117,6 +126,9 @@ export async function runCheck(opts) {
         batchData = refreshed.batchData;
         mergeStatus = refreshed.mergeStatus;
         status = refreshed.status;
+        if (mergeStatus.state === "MERGED" || mergeStatus.state === "CLOSED") {
+            return buildTerminalReport(prNumber, repo, batchData, mergeStatus, mergeStatus.state);
+        }
     }
     const blockedByFilteredCheck = isBlockedByFilteredCheck(mergeStatus, verdict);
     return {

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

@@ -1,8 +1,11 @@
 /**
  * Build the `build-suggestion-patch` instruction step for agent consumers.
- * Currently emitted by iterate `fix_code` for suggestion review threads.
+ * Currently emitted by iterate `fix_code` for suggestion review threads. The CLI keeps
+ * only the trigger and the concrete command; refusal/drift handling is invariant across
+ * every invocation, so it lives in the pr-shepherd skill's "Suggestion patches" playbook
+ * instead of being re-emitted every tick (see CLAUDE.md "Keep skills and loop prompts
+ * minimal").
  * @param sectionName - The markdown section heading where suggestion threads appear,
  *   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): string;

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

@@ -1,12 +1,15 @@
 import { buildPrShepherdCommand } from "../cli/runner.mjs";
 /**
  * Build the `build-suggestion-patch` instruction step for agent consumers.
- * Currently emitted by iterate `fix_code` for suggestion review threads.
+ * Currently emitted by iterate `fix_code` for suggestion review threads. The CLI keeps
+ * only the trigger and the concrete command; refusal/drift handling is invariant across
+ * every invocation, so it lives in the pr-shepherd skill's "Suggestion patches" playbook
+ * instead of being re-emitted every tick (see CLAUDE.md "Keep skills and loop prompts
+ * minimal").
  * @param sectionName - The markdown section heading where suggestion threads appear,
  *   e.g. `"## Review threads"`.
- * @param includeDriftHint - Whether to add the trailing note about drift on failed apply.
  */
-export function buildCommitSuggestionInstruction(prNumber, sectionName, includeDriftHint) {
+export function buildCommitSuggestionInstruction(prNumber, sectionName) {
     const command = buildPrShepherdCommand([
         "build-suggestion-patch",
         String(prNumber),
@@ -16,16 +19,5 @@ export function buildCommitSuggestionInstruction(prNumber, sectionName, includeD
         "<one-sentence headline>",
         "--format=json",
     ]).text;
-    const driftHint = includeDriftHint
-        ? "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.";
-    const manualStep = includeDriftHint ? "manual-fix step" : "manual-edit step";
-    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.",
-        `If the command refuses because the suggestion is unsafe (an unsafe anchored range or nested/unbalanced suggestion fences), skip patch application and use the ${manualStep} below. Do not retry the command.`,
-        "For any other refusal, follow the CLI error's stated recovery action; do not manually edit the suggestion.",
-        driftHint,
-        "Keep human-authored thread IDs in `apply review:` so Shepherd replies instead of resolving them.",
-    ];
+    return `For each thread marked \`[suggestion]\` under \`${sectionName}\`, run \`${command}\` and apply the returned patch. See "Suggestion patches" in the pr-shepherd skill for refusals and drift.`;
 }

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

@@ -11,7 +11,37 @@ export declare function buildCrStaleClause(reviews: Review[]): string;
  * discarding the rest of the user's config.
  */
 export declare function buildBehindBaseHintInstruction(baseBranch: string, hint: string, isBehind: boolean): string[];
-/** Build the `Run the apply review: command` instruction, including its optional substitution hint. */
+/**
+ * Build the `Run the apply review: command` instruction. Steps stay here (not in the skill)
+ * whenever the *unmodified, as-printed* command is unsafe without them:
+ *
+ * - `$HEAD_SHA`/`$DISMISS_MESSAGE` substitution: without it, the printed command has an
+ *   empty `--message`/invalid `--require-sha` and `apply review` rejects the mutation.
+ * - Self-reply exclusion: a human thread whose latest visible comment is already Shepherd's
+ *   own prior reply still has its ID in `--reply-thread-ids` by default. Running the
+ *   printed command as-is replies to Shepherd's own reply, which can re-surface the thread
+ *   and produce a self-perpetuating reply loop — worse than a rejected mutation, and not
+ *   something a caller can discover by inspecting the command alone.
+ *
+ * Contrast with what *does* stay in the skill's "Review-mutation mechanics" playbook —
+ * dismiss-ID retention and the first-look/annotation ID-exclusion rules. Those only matter
+ * if the caller *edits* the printed command (removes an ID, or adds one back); the printed
+ * command run unmodified is already correct for them. The pointer below is load-bearing:
+ * without it, nothing in CLI output tells the agent that playbook exists.
+ */
 export declare function buildResolveCommandInstruction(resolveCommand: ResolveCommand): string[];
+/**
+ * Build the CI-triage instruction. The per-conclusion rerun policy (GitHub Actions log
+ * excerpts, `gh run view`/`gh run rerun` rules for CANCELLED/STARTUP_FAILURE/external
+ * failures) is invariant text keyed on the `[conclusion: …]` tags already rendered in
+ * `## Failing checks` — it lives in the pr-shepherd skill's "CI failure triage" playbook
+ * instead of being re-emitted every tick. This supersedes the "CI budget rules" example in
+ * CLAUDE.md's "Keep skills and loop prompts minimal" section (see that section's amendment
+ * note). The `(no runId)` case stays here because it flips `buildFixCompletionInstruction`
+ * to a human-handoff terminal state — that trigger, unlike the others, is CLI-decided. The
+ * CLI sentence does not claim every failure has a log excerpt to read (only GitHub Actions
+ * checks with a runId do — CANCELLED, STARTUP_FAILURE, and external checks may not); that
+ * per-kind detail is exactly what the skill playbook table disambiguates.
+ */
 export declare function buildFailingCheckInstructions(checks: AgentCheck[]): string[];
 export declare function buildFixCompletionInstruction(checks: AgentCheck[]): string;

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

@@ -20,7 +20,24 @@ export function buildBehindBaseHintInstruction(baseBranch, hint, isBehind) {
         return [];
     return [`The branch is behind \`origin/${baseBranch}\`. ${trimmedHint} before pushing.`];
 }
-/** Build the `Run the apply review: command` instruction, including its optional substitution hint. */
+/**
+ * Build the `Run the apply review: command` instruction. Steps stay here (not in the skill)
+ * whenever the *unmodified, as-printed* command is unsafe without them:
+ *
+ * - `$HEAD_SHA`/`$DISMISS_MESSAGE` substitution: without it, the printed command has an
+ *   empty `--message`/invalid `--require-sha` and `apply review` rejects the mutation.
+ * - Self-reply exclusion: a human thread whose latest visible comment is already Shepherd's
+ *   own prior reply still has its ID in `--reply-thread-ids` by default. Running the
+ *   printed command as-is replies to Shepherd's own reply, which can re-surface the thread
+ *   and produce a self-perpetuating reply loop — worse than a rejected mutation, and not
+ *   something a caller can discover by inspecting the command alone.
+ *
+ * Contrast with what *does* stay in the skill's "Review-mutation mechanics" playbook —
+ * dismiss-ID retention and the first-look/annotation ID-exclusion rules. Those only matter
+ * if the caller *edits* the printed command (removes an ID, or adds one back); the printed
+ * command run unmodified is already correct for them. The pointer below is load-bearing:
+ * without it, nothing in CLI output tells the agent that playbook exists.
+ */
 export function buildResolveCommandInstruction(resolveCommand) {
     if (!resolveCommand.hasMutations)
         return [];
@@ -34,29 +51,30 @@ export function buildResolveCommandInstruction(resolveCommand) {
     if (resolveCommand.requiresDismissMessage) {
         instructions.push("Replace `$DISMISS_MESSAGE` with one sentence describing what changed.");
     }
-    instructions.push("Run the `apply review:` command shown above.");
+    instructions.push('Run the `apply review:` command shown above. See "Review-mutation mechanics" in the pr-shepherd skill for dismiss-ID retention.');
     return instructions;
 }
+/**
+ * Build the CI-triage instruction. The per-conclusion rerun policy (GitHub Actions log
+ * excerpts, `gh run view`/`gh run rerun` rules for CANCELLED/STARTUP_FAILURE/external
+ * failures) is invariant text keyed on the `[conclusion: …]` tags already rendered in
+ * `## Failing checks` — it lives in the pr-shepherd skill's "CI failure triage" playbook
+ * instead of being re-emitted every tick. This supersedes the "CI budget rules" example in
+ * CLAUDE.md's "Keep skills and loop prompts minimal" section (see that section's amendment
+ * note). The `(no runId)` case stays here because it flips `buildFixCompletionInstruction`
+ * to a human-handoff terminal state — that trigger, unlike the others, is CLI-decided. The
+ * CLI sentence does not claim every failure has a log excerpt to read (only GitHub Actions
+ * checks with a runId do — CANCELLED, STARTUP_FAILURE, and external checks may not); that
+ * per-kind detail is exactly what the skill playbook table disambiguates.
+ */
 export function buildFailingCheckInstructions(checks) {
     if (checks.length === 0)
         return [];
-    const hasRunId = checks.some((c) => c.runId && c.conclusion !== "CANCELLED" && c.conclusion !== "STARTUP_FAILURE");
-    const hasCancelled = checks.some((c) => c.runId && c.conclusion === "CANCELLED");
-    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 hasTriageable = checks.some((c) => c.runId || c.detailsUrl);
     const instructions = [];
-    if (hasRunId) {
-        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) {
-        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) {
-        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) {
-        instructions.push("For each `external` failure, open its URL and inspect it.");
+    if (hasTriageable) {
+        instructions.push('Triage every failure under `## Failing checks`. See "CI failure triage" in the pr-shepherd skill for `gh run view` / `gh run rerun` rules.');
     }
     if (hasBare) {
         instructions.push("For each `(no runId)` failure, escalate to a human because no log or URL is available.");
@@ -68,5 +86,5 @@ export function buildFixCompletionInstruction(checks) {
     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 "`[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.";
+    return "`[FIX_CODE]` is non-terminal. After completing these steps, iterate again with the same options to continue.";
 }

package/bin/commands/iterate/fix-code.mjs

@@ -8,7 +8,7 @@ import { buildResolveCommand } from "./classify.mjs";
 import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { tryCancelRun, buildAutoCancelRunIdsWithOptions, buildInProgressRunIds, buildRunProtection, } from "./helpers.mjs";
-import { annotationMarkerBody, checksWithUnseenAnnotations } from "../check-annotations.mjs";
+import { annotationMarkerBody, checksWithActionableAnnotations } from "../check-annotations.mjs";
 import { threadTranscriptBody } from "../../threads/transcript.mjs";
 import { isHumanAuthor, isConfiguredBotAuthor } from "../../comments/authors.mjs";
 import { loadConfig } from "../../config/load.mjs";
@@ -30,7 +30,7 @@ function nextFixAttempts(stored, headSha, threads) {
 export async function handleFixCode(ctx) {
     const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, ruleAutoResolveThreadIds, } = ctx;
     const failingChecks = report.checks.failing;
-    const annotatedExtra = checksWithUnseenAnnotations(report).filter((c) => c.category !== "failing");
+    const annotatedExtra = checksWithActionableAnnotations(report).filter((c) => c.category !== "failing");
     const { protectedRunIds, protectedRuns } = buildRunProtection([...failingChecks, ...report.checks.inProgress], opts.neverCancelRuns);
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
     const { threadAttempts, threadBodyHashes } = nextFixAttempts(stored, headSha, report.threads.actionable);

package/bin/commands/iterate/index.mjs

@@ -12,7 +12,7 @@ import { clearStallState } from "../../state/iterate-stall.mjs";
 import { handleFixCode } from "./fix-code.mjs";
 import { normalizeBotUsernames } from "../../comments/authors.mjs";
 import { autoMinimizeComments } from "../../comments/resolve.mjs";
-import { checksWithUnseenAnnotations } from "../check-annotations.mjs";
+import { checksWithActionableAnnotations } from "../check-annotations.mjs";
 export async function runIterate(opts) {
     const config = loadConfig();
     const botUsernames = normalizeBotUsernames(config.botUsernames);
@@ -70,7 +70,7 @@ export async function runIterate(opts) {
         report.comments.firstLook.length > 0 ||
         report.changesRequestedReviews.length > 0 ||
         report.checks.failing.length > 0 ||
-        checksWithUnseenAnnotations(report).length > 0 ||
+        checksWithActionableAnnotations(report).length > 0 ||
         report.mergeStatus.status === "CONFLICTS" ||
         reviewSummaryIds.length > 0 ||
         firstLookSummaries.length > 0 ||

package/bin/commands/iterate/render.mjs

@@ -1,6 +1,6 @@
 import { renderShellCommand } from "../../cli/runner.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 { SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE, buildShepherdJournalInstruction, } from "../shepherd-journal.mjs";
 import { isFailingAgentCheck } from "../../checks/conclusions.mjs";
 import { buildCommitSuggestionInstruction } from "../commit-suggestion-instruction.mjs";
 /** Render a resolve command as a shell snippet. Appends `--require-sha "$HEAD_SHA"` when set. */
@@ -42,7 +42,7 @@ isBehind = false) {
     }
     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.");
+        instructions.push("Review every item under `## First-look items` before acting.");
     }
     if (firstLookSummaries.length > 0)
         instructions.push(SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE);
@@ -54,35 +54,30 @@ isBehind = false) {
         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.");
     }
     if (inProgressRunIds.length > 0) {
-        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.");
+        instructions.push("If you will push, first cancel every ID under `## In-progress runs` with `gh run cancel <id>` (ignore errors for runs that already finished). If you will not push, leave them 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"));
     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";
         instructions.push(`Apply every warranted review fix in ${filesRef}.`);
-        if (hasSuggestions) {
-            instructions.push("After source drift prevents a generated suggestion patch from applying, 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.", "When `build-suggestion-patch` refuses because the suggestion is unsafe (an unsafe anchored range or nested/unbalanced suggestion fences), do not apply the replacement block verbatim. Inspect the surrounding source and reviewer intent, then make the intended edit manually.");
-        }
     }
     if (resolutionOnlyThreads.length > 0) {
-        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('Review the threads under `## Review threads to resolve` before running mutations. Use the generated commands as shown — see "Review-mutation routing" in the pr-shepherd skill for which flag applies to which ID.');
     }
     instructions.push(...buildFailingCheckInstructions(failingChecks));
     if (hasAnnotations) {
-        instructions.push("Inspect every referenced range under `## Check annotations` and apply any warranted change.", "Do not add annotation IDs to resolve or minimize mutations.");
+        instructions.push("Inspect every referenced range under `## Check annotations` and apply any warranted change.");
     }
     if (changesRequestedReviews.length > 0) {
         const staleClause = buildCrStaleClause(changesRequestedReviews);
         instructions.push(`Read every body under \`## Changes-requested reviews\` and apply any warranted change.${staleClause}`);
-        if ((resolveCommand.dismissReviewIds?.length ?? 0) > 0)
-            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`.");
     }
     instructions.push(...buildBehindBaseHintInstruction(baseBranch, behindBaseHint, isBehind));
     const hasReviewMutations = resolveCommand.hasMutations || resolveOnlyCommand?.hasMutations === true;
@@ -98,7 +93,7 @@ isBehind = false) {
         firstLookTotal > 0 ||
         firstLookSummaries.length > 0 ||
         editedTotal > 0) {
-        instructions.push(...buildShepherdJournalInstruction(prNumber, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS));
+        instructions.push(buildShepherdJournalInstruction(prNumber));
     }
     if (resolveOnlyCommand?.hasMutations)
         instructions.push("Run the `resolve-only:` command shown above.");

package/bin/commands/iterate/stall.mjs

@@ -1,7 +1,7 @@
 import { readStallState, writeStallState } from "../../state/iterate-stall.mjs";
 import { toAgentThread, toAgentComment, toAgentStalledCheck } from "../../reporters/agent.mjs";
 import { buildEscalateSuggestion, buildEscalateHumanMessage, formatDurationApprox, } from "./escalate.mjs";
-import { checksWithUnseenAnnotations } from "../check-annotations.mjs";
+import { checksWithActionableAnnotations } from "../check-annotations.mjs";
 function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds) {
     const checks = [
         ...report.checks.failing.map((f) => `failing:${f.name}:${f.conclusion}`),
@@ -14,7 +14,7 @@ function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds
     const reviews = report.changesRequestedReviews.map((r) => r.id).sort();
     const summaries = [...reviewSummaryIds].sort();
     const ruleAutoResolveSummaries = (report.ruleAutoResolveReviewSummaryIds ?? []).sort((a, b) => a.localeCompare(b));
-    const annotations = checksWithUnseenAnnotations(report)
+    const annotations = checksWithActionableAnnotations(report)
         .flatMap((c) => (c.annotations ?? []).map((a) => a.id))
         .sort((a, b) => a.localeCompare(b));
     return JSON.stringify({

package/bin/commands/poll.mjs

@@ -6,7 +6,7 @@ function writeTickProgress(tick, elapsedSeconds, sleepSeconds, verbose) {
         process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT — sleeping ${sleepSeconds}s\n`);
     }
     else {
-        process.stderr.write(".");
+        process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT — still running; next tick in ${sleepSeconds}s\n`);
     }
 }
 function waitSignature(result) {
@@ -73,7 +73,6 @@ export async function runPoll(opts) {
     const verbose = opts.verbose === true;
     const quietStatus = quietStatusOpt === true;
     const untilTerminal = untilTerminalOpt === true;
-    let dotsPrinted = false;
     let lastWaitSignature = null;
     // When prNumber is omitted, iterateOpts.prNumber starts undefined and each tick would otherwise
     // re-infer the PR from the current branch. That inference query only matches OPEN PRs, so once
@@ -110,8 +109,6 @@ export async function runPoll(opts) {
                 verbose,
                 lastWaitSignature,
             });
-            if (!quietStatus && !verbose)
-                dotsPrinted = true;
             await sleep(intervalMs);
             continue;
         }
@@ -124,10 +121,6 @@ export async function runPoll(opts) {
             debounceUntil ??= Date.now() + debounceMs;
             const remainingMs = debounceUntil - Date.now();
             if (remainingMs > 0) {
-                if (dotsPrinted) {
-                    process.stderr.write("\n");
-                    dotsPrinted = false;
-                }
                 writeDebounceProgress(tick, Date.now() - start, remainingMs);
                 await sleep(Math.min(intervalMs, remainingMs));
             }
@@ -138,7 +131,5 @@ export async function runPoll(opts) {
         }
         break;
     }
-    if (dotsPrinted)
-        process.stderr.write("\n");
     return lastResult;
 }

package/bin/commands/ready-mergeability.mjs

@@ -24,6 +24,7 @@ async function readMergeability(prNumber, repo, batchData) {
     const restState = await getMergeableState(prNumber, repo.owner, repo.name);
     return {
         ...batchData,
+        state: restState.state ?? batchData.state,
         mergeable: restState.mergeable ?? batchData.mergeable,
         mergeStateStatus: restState.mergeStateStatus ?? batchData.mergeStateStatus,
     };

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

@@ -5,6 +5,10 @@ export declare const SHEPHERD_JOURNAL_DETAILS_SUMMARY = "<summary>Shepherd Journ
 export declare const SHEPHERD_JOURNAL_DETAILS_CLOSE = "</details>";
 export declare const SHEPHERD_JOURNAL_APPEND_HINT = "If Shepherd Journal details already exist, append entries inside them instead of creating another container.";
 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.";
+/**
+ * Build the Shepherd Journal instruction step. The reference-citation convention (link
+ * threads/comments from their headings, cite reviews by ID) is invariant across every
+ * invocation, so it lives in the pr-shepherd skill's "Shepherd Journal" playbook instead
+ * of being re-emitted every tick (see CLAUDE.md "Keep skills and loop prompts minimal").
+ */
+export declare function buildShepherdJournalInstruction(prNumber: number): string;

package/bin/commands/shepherd-journal.mjs

@@ -5,11 +5,12 @@ export const SHEPHERD_JOURNAL_DETAILS_SUMMARY = "<summary>Shepherd Journal</summ
 export const SHEPHERD_JOURNAL_DETAILS_CLOSE = "</details>";
 export const SHEPHERD_JOURNAL_APPEND_HINT = "If Shepherd Journal details already exist, append entries inside them instead of creating another container.";
 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 substantial decision or rejection, append \`- <decision>\` to Shepherd Journal with \`pr-shepherd apply journal ${prNumber} '- <decision>'\`.`,
-        itemReferenceGuidance,
-    ];
+/**
+ * Build the Shepherd Journal instruction step. The reference-citation convention (link
+ * threads/comments from their headings, cite reviews by ID) is invariant across every
+ * invocation, so it lives in the pr-shepherd skill's "Shepherd Journal" playbook instead
+ * of being re-emitted every tick (see CLAUDE.md "Keep skills and loop prompts minimal").
+ */
+export function buildShepherdJournalInstruction(prNumber) {
+    return `For any substantial decision or rejection, append \`- <decision>\` to Shepherd Journal with \`pr-shepherd apply journal ${prNumber} '- <decision>'\`. See "Shepherd Journal" in the pr-shepherd skill for citation conventions.`;
 }
-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/bin/github/client.d.mts

@@ -34,13 +34,15 @@ export declare function getPullRequestBody(pr: number, owner: string, name: stri
 /** Overwrites the PR body. */
 export declare function updatePullRequestBody(pullRequestId: string, body: string): Promise<void>;
 /**
- * Fetches `mergeable` and `mergeStateStatus` via the REST API.
+ * Fetches PR state, `mergeable`, and `mergeStateStatus` via the REST API.
  *
- * Used as a fallback when the GraphQL API returns `UNKNOWN` for these fields —
- * a known GitHub quirk where GraphQL lags behind the REST layer.
+ * Used when the GraphQL API returns `UNKNOWN` for mergeability or before a
+ * READY handoff. The same response carries state so a concurrent merge or
+ * close can supersede the earlier GraphQL snapshot without another request.
  */
 export declare function getMergeableState(pr: number, owner: string, repo: string): Promise<{
     mergeable: MergeableState;
     mergeStateStatus: MergeStateStatus;
+    state?: "OPEN" | "CLOSED" | "MERGED";
 }>;
 export declare function getCurrentBranch(): Promise<string>;

package/bin/github/client.mjs

@@ -83,16 +83,23 @@ export async function updatePullRequestBody(pullRequestId, body) {
     await httpGraphql(UPDATE_PR_BODY_MUTATION, { pullRequestId, body });
 }
 /**
- * Fetches `mergeable` and `mergeStateStatus` via the REST API.
+ * Fetches PR state, `mergeable`, and `mergeStateStatus` via the REST API.
  *
- * Used as a fallback when the GraphQL API returns `UNKNOWN` for these fields —
- * a known GitHub quirk where GraphQL lags behind the REST layer.
+ * Used when the GraphQL API returns `UNKNOWN` for mergeability or before a
+ * READY handoff. The same response carries state so a concurrent merge or
+ * close can supersede the earlier GraphQL snapshot without another request.
  */
 export async function getMergeableState(pr, owner, repo) {
     const data = await rest("GET", `/repos/${owner}/${repo}/pulls/${pr}`);
     const mergeable = data.mergeable === true ? "MERGEABLE" : data.mergeable === false ? "CONFLICTING" : "UNKNOWN";
     const mergeStateStatus = data.mergeable_state.toUpperCase();
-    return { mergeable, mergeStateStatus };
+    const rawState = data.state?.toUpperCase();
+    const state = data.merged_at != null
+        ? "MERGED"
+        : rawState === "OPEN" || rawState === "CLOSED"
+            ? rawState
+            : undefined;
+    return { mergeable, mergeStateStatus, ...(state !== undefined && { state }) };
 }
 // ---------------------------------------------------------------------------
 // Internal helpers

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

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

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "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.38.0", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.39.0", "pr-shepherd-mcp"]
     }
   }
 }

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

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

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

@@ -19,3 +19,47 @@ Thin dispatcher for iterating a PR. Poll with the CLI; use MCP `iterate` only wh
 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.
+
+## Playbooks
+
+`## Instructions` steps reference these playbooks by name instead of repeating their
+mechanics every tick. Apply the referenced playbook in full whenever a step points here.
+
+### Suggestion patches
+
+- The CLI only builds the patch. Apply it, stage the listed file, and follow the returned commit instructions.
+- If the command refuses because the suggestion is unsafe (an unsafe anchored range or nested/unbalanced suggestion fences), skip patch application and edit the file manually. Do not retry the command.
+- For any other refusal, follow the CLI error's stated recovery action; do not manually edit the suggestion.
+- If the patch does not apply for any other reason, edit the file manually instead. Do not retry the command.
+- After source drift prevents a generated suggestion patch from applying, 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.
+- Keep human-authored thread IDs in `apply review:` so Shepherd replies instead of resolving them.
+
+### CI failure triage
+
+Match each failure's `[conclusion: …]` tag under `## Failing checks` to a rule:
+
+More specific rows win over the general "GitHub Actions failure" row — check conclusion first.
+
+| Tag / kind                                                               | Do                                                                                                                                                                                                                                                                               |
+| ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| GitHub Actions failure (has a run ID, not `CANCELLED`/`STARTUP_FAILURE`) | Read the included log excerpt if one is rendered. If missing or insufficient, run a bounded command such as `gh run view <runId> --log-failed \| tail -n 200` — the unbounded form can dump excessive log output into context. Open the run URL only if that still lacks detail. |
+| Transient infrastructure failure                                         | Rerun with `gh run rerun <runId> --failed`.                                                                                                                                                                                                                                      |
+| Real test or build failure                                               | Apply a code fix — do not rerun.                                                                                                                                                                                                                                                 |
+| `[conclusion: CANCELLED]`                                                | No log excerpt is rendered for this conclusion. Run `gh run rerun <runId>` unless this tick will push new commits. Not resolved by a rerun classification — `## Cancelled runs` is a different section.                                                                          |
+| `[conclusion: STARTUP_FAILURE]`                                          | No log excerpt is rendered for this conclusion. Inspect with `gh run view <runId>`, rerun with `gh run rerun <runId>` if warranted.                                                                                                                                              |
+| `external` (no run ID, has a URL)                                        | Open its URL and inspect it.                                                                                                                                                                                                                                                     |
+
+### Review-mutation mechanics
+
+Applies to every `apply review:` / `resolve-only:` command the CLI prints. Covers only what stays safe if you run the printed command **unmodified** — `$HEAD_SHA`/`$DISMISS_MESSAGE` substitution and the self-reply exclusion rule are separate CLI-printed steps, not covered here, because the printed command is unsafe by default without them.
+
+- Never add first-look-only or check-annotation IDs to `--reply-thread-ids`, `--resolve-thread-ids`, `--dismiss-review-ids`, or `--minimize-comment-ids` — those flags are pre-populated by the CLI.
+- Keep every existing `--dismiss-review-ids` ID the CLI already included. Each is a bot or non-human review that must be dismissed; omitting one leaves the PR in `CHANGES_REQUESTED`.
+
+### Review-mutation routing
+
+For threads under `## Review threads to resolve`: human-authored IDs use `--reply-thread-ids` (Shepherd replies instead of resolving them); bot and non-human IDs use `--resolve-thread-ids`. Use the commands as generated — do not move an ID between flags.
+
+### Shepherd Journal
+
+Link threads and comments in a journal entry from their headings in the CLI output. Cite reviews by ID.