pr-shepherd 0.36.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.36.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/checks/conclusions.d.mts

@@ -0,0 +1,6 @@
+import type { CheckConclusion } from "../types.mts";
+/** Failing-check rows for formatter/instructions — excludes annotation-only carriers. */
+export declare function isFailingAgentCheck(check: {
+    conclusion: CheckConclusion;
+    annotationOnly?: boolean;
+}): boolean;

package/bin/checks/conclusions.mjs

@@ -0,0 +1,9 @@
+const NON_FAILING_CONCLUSIONS = new Set(["SUCCESS", "SKIPPED", "NEUTRAL"]);
+/** True for conclusions that belong under `## Failing checks` (not success/skipped/neutral). */
+function isFailingCheckConclusion(conclusion) {
+    return conclusion == null || !NON_FAILING_CONCLUSIONS.has(conclusion);
+}
+/** Failing-check rows for formatter/instructions — excludes annotation-only carriers. */
+export function isFailingAgentCheck(check) {
+    return !check.annotationOnly && isFailingCheckConclusion(check.conclusion);
+}

package/bin/cli/fix-formatter.mjs

@@ -4,6 +4,7 @@ import { renderSuggestionBlock, renderLineRange } from "./suggestion-renderer.mj
 import { renderThreadBullet, renderReviewBullet, renderThreadResolutionStatusTag, renderAuthor, buildFirstLookBullets, renderThreadConversation, blockquote, } from "./list-formatters.mjs";
 import { numberInstructions } from "./iterate-instructions.mjs";
 import { renderCheckAnnotation, renderProtectedRun } from "./fix-formatter-extra.mjs";
+import { isFailingAgentCheck } from "../checks/conclusions.mjs";
 export function formatFixCodeResult(header, result) {
     const sections = [header];
     if (result.fix.threads.length > 0) {
@@ -37,9 +38,10 @@ export function formatFixCodeResult(header, result) {
             sections.push(blockquote(c.body));
         }
     }
-    if (result.fix.checks.length > 0) {
+    const failingChecks = result.fix.checks.filter((ch) => isFailingAgentCheck(ch));
+    if (failingChecks.length > 0) {
         sections.push("## Failing checks");
-        const bullets = result.fix.checks.map((ch) => {
+        const bullets = failingChecks.map((ch) => {
             const workflowPrefix = ch.workflowName ? `${ch.workflowName} › ` : "";
             const jobLabel = ch.jobName ? ch.jobName : ch.name;
             const locator = ch.runId

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/check-annotations.d.mts

@@ -1,5 +1,18 @@
-import type { CheckAnnotation, TriagedCheck } from "../types.mts";
-export declare function attachUnseenCheckAnnotations(checks: TriagedCheck[], seenMap: Map<string, {
+import type { CheckAnnotation, ClassifiedCheck, ShepherdReport, TriagedCheck } from "../types.mts";
+export declare function checksWithUnseenAnnotations(report: ShepherdReport): TriagedCheck[];
+export declare function attachAndMergeCheckAnnotations(buckets: {
+    passing: ClassifiedCheck[];
+    failing: TriagedCheck[];
+    skipped: ClassifiedCheck[];
+    filtered: ClassifiedCheck[];
+    ignored: ClassifiedCheck[];
+}, seenMap: Map<string, {
     seenAt: number;
-}>, prNumber: number): Promise<TriagedCheck[]>;
+}>, prNumber: number): Promise<{
+    passing: ClassifiedCheck[];
+    failing: TriagedCheck[];
+    skipped: ClassifiedCheck[];
+    filtered: ClassifiedCheck[];
+    ignored: ClassifiedCheck[];
+}>;
 export declare function annotationMarkerBody(a: CheckAnnotation): string;

package/bin/commands/check-annotations.mjs

@@ -1,5 +1,41 @@
 import { fetchCheckRunAnnotations } from "../github/check-annotations.mjs";
-export async function attachUnseenCheckAnnotations(checks, seenMap, prNumber) {
+function shouldFetchCheckAnnotations(check) {
+    return check.id != null && check.status === "COMPLETED" && check.hasAnnotations === true;
+}
+export function checksWithUnseenAnnotations(report) {
+    return [
+        ...report.checks.failing,
+        ...report.checks.passing,
+        ...report.checks.skipped,
+        ...report.checks.filtered,
+        ...(report.checks.ignored ?? []),
+    ].filter((c) => (c.annotations?.length ?? 0) > 0);
+}
+export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber) {
+    const candidates = [
+        ...buckets.failing,
+        ...buckets.passing,
+        ...buckets.skipped,
+        ...buckets.filtered,
+        ...buckets.ignored,
+    ].filter(shouldFetchCheckAnnotations);
+    const annotated = await attachUnseenCheckAnnotations(candidates, seenMap, prNumber);
+    const byId = new Map(annotated.flatMap((c) => (c.id != null ? [[c.id, c]] : [])));
+    const apply = (list) => list.map((c) => {
+        if (c.id == null)
+            return c;
+        const next = byId.get(c.id);
+        return next !== undefined ? next : c;
+    });
+    return {
+        passing: apply(buckets.passing),
+        failing: apply(buckets.failing),
+        skipped: apply(buckets.skipped),
+        filtered: apply(buckets.filtered),
+        ignored: apply(buckets.ignored),
+    };
+}
+async function attachUnseenCheckAnnotations(checks, seenMap, prNumber) {
     const checksWithAnnotations = [];
     for (const check of checks) {
         // eslint-disable-next-line no-await-in-loop

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 { attachUnseenCheckAnnotations } from "./check-annotations.mjs";
+import { 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";
@@ -49,6 +49,7 @@ export async function runCheck(opts) {
     const inProgress = classifiedChecks.filter((c) => c.category === "in_progress");
     const skipped = classifiedChecks.filter((c) => c.category === "skipped");
     const filtered = classifiedChecks.filter((c) => c.category === "filtered");
+    const ignored = classifiedChecks.filter((c) => c.category === "ignored");
     const triagedBase = failing.length > 0 && !opts.skipTriage ? await triageFailingChecks(failing, repo) : failing;
     const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
     const seenMap = await loadSeenMap(stateKey);
@@ -56,7 +57,8 @@ export async function runCheck(opts) {
     const ruleSet = await loadRules(discoverRuleFiles(getEffectiveCwd()));
     const classifyIndex = buildClassifyIndex(ruleSet, batchData);
     const partition = partitionBatch(classifyIndex, batchData);
-    const triaged = await attachUnseenCheckAnnotations(triagedBase, seenMap, prNumber);
+    const merged = await attachAndMergeCheckAnnotations({ passing, failing: triagedBase, skipped, filtered, ignored }, seenMap, prNumber);
+    const ignoredAnnotated = merged.ignored.filter((c) => (c.annotations?.length ?? 0) > 0);
     const minimizedCommentCandidates = batchData.comments.filter((c) => c.isMinimized && !partition.suppressedCommentIds.has(c.id));
     const visibleCommentClassification = classifyVisibleComments(batchData.comments.filter((c) => !partition.suppressedCommentIds.has(c.id)), seenMap, config.iterate.minimizeComments, botUsernames);
     const threadVisibility = classifyThreadVisibility(batchData.reviewThreads.filter((t) => !partition.suppressedThreadIds.has(t.id)), seenMap, botUsernames);
@@ -125,11 +127,12 @@ export async function runCheck(opts) {
         baseBranch: batchData.baseRefName,
         mergeStatus,
         checks: {
-            passing,
-            failing: triaged,
+            passing: merged.passing,
+            failing: merged.failing,
             inProgress: inProgress,
-            skipped,
-            filtered,
+            skipped: merged.skipped,
+            filtered: merged.filtered,
+            ...(ignoredAnnotated.length > 0 && { ignored: ignoredAnnotated }),
             filteredNames: verdict.filteredNames,
             blockedByFilteredCheck,
             ...(verdict.ignoredNames.length > 0 && { ignoredNames: verdict.ignoredNames }),

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/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 } from "../check-annotations.mjs";
+import { annotationMarkerBody, checksWithUnseenAnnotations } from "../check-annotations.mjs";
 import { threadTranscriptBody } from "../../threads/transcript.mjs";
 import { isHumanAuthor, isConfiguredBotAuthor } from "../../comments/authors.mjs";
 import { loadConfig } from "../../config/load.mjs";
@@ -30,6 +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 { 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);
@@ -89,7 +90,11 @@ export async function handleFixCode(ctx) {
     const threads = report.threads.actionable.map(toAgentThread);
     const resolutionOnlyThreads = report.threads.resolutionOnly;
     const actionableComments = report.comments.actionable.map(toAgentComment);
-    const checks = toAgentChecks(failingChecks);
+    const failingAgentChecks = toAgentChecks(failingChecks);
+    const checks = [
+        ...failingAgentChecks,
+        ...toAgentChecks(annotatedExtra).map((c) => ({ ...c, annotationOnly: true })),
+    ];
     const { changesRequestedReviews } = report;
     const hasConflicts = report.mergeStatus.status === "CONFLICTS";
     const isBehind = report.mergeStatus.status === "BEHIND";
@@ -98,7 +103,8 @@ export async function handleFixCode(ctx) {
     // summary-only iterations have no path to a push, so listing runs would prompt
     // unnecessary cancellation.
     const pushLikely = threads.length > 0 ||
-        checks.length > 0 ||
+        failingAgentChecks.length > 0 ||
+        annotatedExtra.length > 0 ||
         hasConflicts ||
         changesRequestedReviews.length > 0 ||
         actionableComments.length > 0;
@@ -110,13 +116,14 @@ export async function handleFixCode(ctx) {
         : [];
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
     const allCommentIds = [...commentMinimizeIds, ...reviewSummaryIds];
-    const { resolveCommand, resolveOnlyCommand } = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber, botUsernames, ruleAutoResolveThreadIds);
+    const { resolveCommand, resolveOnlyCommand } = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, failingAgentChecks, prNumber, botUsernames, ruleAutoResolveThreadIds);
     // Safety: if the base branch is unknown, escalate when a push is plausible — the agent
     // would need the correct base to rebase safely. This is a conservative guard, not a
     // prediction that the agent *will* push. Intentionally broader than `pushLikely` above:
     // resolution-only threads also need a known base in case the agent does push.
     const pushIsPlausible = threads.length > 0 ||
-        checks.length > 0 ||
+        failingAgentChecks.length > 0 ||
+        annotatedExtra.length > 0 ||
         hasConflicts ||
         changesRequestedReviews.length > 0 ||
         actionableComments.length > 0 ||

package/bin/commands/iterate/index.mjs

@@ -12,6 +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";
 export async function runIterate(opts) {
     const config = loadConfig();
     const botUsernames = normalizeBotUsernames(config.botUsernames);
@@ -69,6 +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 ||
         report.mergeStatus.status === "CONFLICTS" ||
         reviewSummaryIds.length > 0 ||
         firstLookSummaries.length > 0 ||

package/bin/commands/iterate/render.mjs

@@ -1,8 +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];
@@ -13,93 +13,96 @@ export function renderResolveCommand(rc) {
 export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behindBaseHint — see buildBehindBaseHintInstruction
 isBehind = false) {
     const instructions = [];
+    const failingChecks = checks.filter((c) => isFailingAgentCheck(c));
+    const hasAnnotations = checks.some((c) => (c.annotations?.length ?? 0) > 0);
     const hasNonConflictHints = threads.length > 0 ||
-        checks.length > 0 ||
+        failingChecks.length > 0 ||
+        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)
             actionableSections.push("`## Review threads`");
         if (actionableComments.length > 0)
             actionableSections.push("`## Actionable comments`");
-        if (checks.length > 0)
+        if (failingChecks.length > 0)
             actionableSections.push("`## Failing checks`");
-        if (checks.some((c) => (c.annotations?.length ?? 0) > 0)) {
+        if (hasAnnotations) {
             actionableSections.push("`## Check annotations`");
         }
         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(checks));
-    if (checks.some((c) => (c.annotations?.length ?? 0) > 0)) {
-        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(...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.");
     }
     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/iterate/stall.mjs

@@ -1,6 +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";
 function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds) {
     const checks = [
         ...report.checks.failing.map((f) => `failing:${f.name}:${f.conclusion}`),
@@ -13,6 +14,9 @@ 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)
+        .flatMap((c) => (c.annotations ?? []).map((a) => a.id))
+        .sort((a, b) => a.localeCompare(b));
     return JSON.stringify({
         action,
         headSha,
@@ -28,6 +32,7 @@ function computeStallFingerprint(action, headSha, base, report, reviewSummaryIds
         reviews,
         summaries,
         ruleAutoResolveSummaries,
+        annotations,
     });
 }
 export async function applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, prospectiveResult, report, reviewSummaryIds) {

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/bin/github/batch-parser-helpers.mjs

@@ -45,6 +45,7 @@ export function mapCheckRunNode(node) {
         ...(completedAtUnix !== undefined && { completedAtUnix }),
         ...(updatedAtUnix !== undefined && { updatedAtUnix }),
         ...(summary !== undefined && { summary }),
+        ...((node.annotations?.nodes.length ?? 0) > 0 && { hasAnnotations: true }),
     };
 }
 function extractCheckRunSummary(title, summary) {

package/bin/github/batch-raw-types.d.mts

@@ -192,6 +192,11 @@ export type RawContextNode = {
     startedAt?: string | null;
     title: string | null;
     summary: string | null;
+    annotations?: {
+        nodes: Array<{
+            message: string;
+        }>;
+    };
     checkSuite: {
         createdAt?: string;
         updatedAt?: string;

package/bin/github/gql/batch-pr-page.gql

@@ -157,6 +157,11 @@ query BatchPrPage(
                     startedAt
                     title
                     summary
+                    annotations(first: 1) {
+                      nodes {
+                        message
+                      }
+                    }
                     checkSuite {
                       createdAt
                       updatedAt

package/bin/github/gql/batch-pr.gql

@@ -254,6 +254,11 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
                     startedAt
                     title
                     summary
+                    annotations(first: 1) {
+                      nodes {
+                        message
+                      }
+                    }
                     checkSuite {
                       createdAt
                       updatedAt

package/bin/reporters/agent.mjs

@@ -50,9 +50,6 @@ export function toAgentComment(c) {
     };
 }
 export function toAgentCheck(c) {
-    if (c.conclusion === "SKIPPED" || c.conclusion === "NEUTRAL") {
-        throw new Error(`Unexpected conclusion ${c.conclusion} in toAgentCheck`);
-    }
     return {
         name: c.name,
         runId: c.runId,

package/bin/types/check-classification.d.mts

@@ -3,6 +3,8 @@ import type { CheckRun } from "./github.mts";
 type CheckCategory = "passed" | "failing" | "in_progress" | "skipped" | "filtered" | "ignored" | "superseded";
 export interface ClassifiedCheck extends CheckRun {
     category: CheckCategory;
+    /** Inline annotations attached to this check run, surfaced once per PR. */
+    annotations?: CheckAnnotation[];
 }
 export interface TriagedCheck extends ClassifiedCheck {
     /** Workflow display name (e.g. `"CI"`). Populated when available from the jobs API; may be `undefined` on fetch failure or when no matching job is found. */
@@ -13,7 +15,5 @@ export interface TriagedCheck extends ClassifiedCheck {
     failedStep?: string;
     /** Bounded raw excerpt from the matched failed job log, when GitHub exposes one. */
     logExcerpt?: string;
-    /** Inline annotations attached to this failing check run, surfaced once per PR. */
-    annotations?: CheckAnnotation[];
 }
 export {};

package/bin/types/github.d.mts

@@ -28,6 +28,8 @@ export interface CheckRun {
     /** Workflow display name for GitHub Actions check runs, when GraphQL exposes it. */
     workflowName?: string;
     workflowId?: string;
+    /** True when GraphQL reported at least one CheckRun annotation. Omitted when false. */
+    hasAnnotations?: boolean;
 }
 export interface ReviewThread {
     id: string;

package/bin/types/report.d.mts

@@ -32,6 +32,8 @@ export interface ShepherdReport {
         skipped: ClassifiedCheck[];
         /** Checks filtered out because they were triggered by a non-PR event (push, schedule, etc.). */
         filtered: ClassifiedCheck[];
+        /** Ignored checks with unseen annotations; omitted when empty. */
+        ignored?: ClassifiedCheck[];
         filteredNames: string[];
         blockedByFilteredCheck: boolean;
         ignoredNames?: string[];
@@ -104,16 +106,14 @@ export interface AgentComment {
     url: string;
     edited?: boolean;
 }
-/** Check shape emitted to the iterate agent under `fix_code`. Cancelled checks
- * should be handled from `name`/`runId`/`detailsUrl`/`conclusion`; optional
- * workflow/job/step metadata may still be present when available. */
+/** Check shape emitted to the iterate agent under `fix_code`. */
 export interface AgentCheck {
     name: string;
     runId: string | null;
     /** Fallback for checks where runId is null (e.g. external status checks). */
     detailsUrl: string | null;
     /** Raw GitHub check conclusion; may be null for some completed checks from upstream data. */
-    conclusion: Exclude<CheckConclusion, "SKIPPED" | "NEUTRAL">;
+    conclusion: CheckConclusion;
     /** Workflow display name (e.g. `"CI"`). Populated on a best-effort basis when available from the jobs API. */
     workflowName?: string;
     /** Name of the matched job (e.g. `"tests (ubuntu)"`). Distinct from check name for matrix builds. */
@@ -123,8 +123,8 @@ export interface AgentCheck {
     /** One-line status text shown in the GitHub UI (e.g. "67.68% of diff hit (target 85.00%)"). */
     summary?: string;
     logExcerpt?: string;
-    /** Marker-gated inline annotations from this failing check. */
     annotations?: CheckAnnotation[];
+    annotationOnly?: true;
 }
 /**
  * A single CI check that is relevant to PR readiness — triggered by a PR event

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.36.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.36.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.36.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.36.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.