pr-shepherd 0.37.0 → 0.37.2

package/.claude-plugin/plugin.json

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

package/README.md

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

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

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

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

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

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

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

package/bin/cli/help.d.mts

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

package/bin/cli/iterate-instructions.mjs

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

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

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

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

@@ -17,7 +17,15 @@ 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.";
+    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.",
+    ];
 }

package/bin/commands/commit-suggestion.mjs

@@ -6,6 +6,7 @@ import { getRepoInfo, getCurrentPrNumber, getCurrentBranch } from "../github/cli
 import { fetchSuggestionThread } from "../github/suggestion-thread.mjs";
 import { parseSuggestion, isCommittableSuggestion } from "../suggestions/parse.mjs";
 import { buildUnifiedDiff } from "../suggestions/patch.mjs";
+import { getUnsafeSuggestionRangeReason } from "../suggestions/range.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { buildPrShepherdCommand } from "../cli/runner.mjs";
 import { getEffectiveCwd, getExecutionCwd } from "../execution-context.mjs";
@@ -80,6 +81,18 @@ export async function runCommitSuggestion(opts) {
         throw new ShepherdError(`Thread ${opts.threadId} path escapes the working tree.`, EXIT.UNAVAILABLE);
     }
     const originalContent = await readFile(resolvedPath, "utf8");
+    const unsafeRangeReason = getUnsafeSuggestionRangeReason({
+        originalContent,
+        startLine,
+        endLine,
+        replacementLines: parsed.lines,
+    });
+    if (unsafeRangeReason) {
+        const range = startLine === endLine ? `${startLine}` : `${startLine}-${endLine}`;
+        throw new ShepherdError(`Thread ${opts.threadId}'s suggestion does not safely fit GitHub's anchored range ` +
+            `${filePath}:${range}: ${unsafeRangeReason} Refusing to build a patch; inspect the surrounding ` +
+            `source and reviewer intent, then apply the change manually.`, EXIT.UNAVAILABLE);
+    }
     const patch = buildUnifiedDiff({
         path: filePath,
         originalContent,

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

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

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

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

package/bin/commands/iterate/render.mjs

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

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

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

package/bin/commands/shepherd-journal.mjs

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

package/bin/suggestions/lines.d.mts

@@ -0,0 +1,12 @@
+export declare const normalizeLine: (line: string) => string;
+export declare function splitFileLines(originalContent: string): string[];
+/**
+ * Strip leading/trailing replacement lines that exactly duplicate file lines
+ * immediately outside the anchored range.
+ */
+export declare function analyzeReplacementContext(fileLines: readonly string[], startLine: number, endLine: number, replacementLines: readonly string[]): {
+    leadingLength: number;
+    replacementLines: string[];
+    trailingLength: number;
+};
+export declare function trimReplacementToContext(fileLines: readonly string[], startLine: number, endLine: number, replacementLines: readonly string[]): readonly string[];

package/bin/suggestions/lines.mjs

@@ -0,0 +1,56 @@
+export const normalizeLine = (line) => line.endsWith("\r") ? line.slice(0, -1) : line;
+function linesEqual(left, right) {
+    return (left.length === right.length &&
+        left.every((line, index) => normalizeLine(line) === normalizeLine(right[index])));
+}
+export function splitFileLines(originalContent) {
+    const body = originalContent.endsWith("\n") ? originalContent.slice(0, -1) : originalContent;
+    return originalContent === "" ? [] : body.split("\n");
+}
+function retainsBoundaryAnchor(replacementLines, removedLines) {
+    return (removedLines.length > 0 &&
+        (linesEqual(replacementLines.slice(0, removedLines.length), removedLines) ||
+            linesEqual(replacementLines.slice(-removedLines.length), removedLines)));
+}
+function largestPermittedContextTrim({ maxLength, matchesContext, remainingAfterTrim, mustRetainAnchor, removedLines, }) {
+    for (let length = maxLength; length >= 1; length--) {
+        if (!matchesContext(length))
+            continue;
+        if (mustRetainAnchor && !retainsBoundaryAnchor(remainingAfterTrim(length), removedLines)) {
+            continue;
+        }
+        return length;
+    }
+    return 0;
+}
+/**
+ * Strip leading/trailing replacement lines that exactly duplicate file lines
+ * immediately outside the anchored range.
+ */
+export function analyzeReplacementContext(fileLines, startLine, endLine, replacementLines) {
+    const removedLines = fileLines.slice(startLine - 1, endLine);
+    const leadingMayBeAnchor = removedLines.length > 0 &&
+        linesEqual(replacementLines.slice(0, removedLines.length), removedLines);
+    const leadingLength = largestPermittedContextTrim({
+        maxLength: Math.min(startLine - 1, replacementLines.length),
+        matchesContext: (length) => linesEqual(replacementLines.slice(0, length), fileLines.slice(startLine - 1 - length, startLine - 1)),
+        remainingAfterTrim: (length) => replacementLines.slice(length),
+        mustRetainAnchor: leadingMayBeAnchor,
+        removedLines,
+    });
+    const remainder = replacementLines.slice(leadingLength);
+    const trailingMayBeAnchor = removedLines.length > 0 && linesEqual(remainder.slice(-removedLines.length), removedLines);
+    const trailingLength = largestPermittedContextTrim({
+        maxLength: Math.min(fileLines.length - endLine, remainder.length),
+        matchesContext: (length) => linesEqual(remainder.slice(-length), fileLines.slice(endLine, endLine + length)),
+        remainingAfterTrim: (length) => remainder.slice(0, -length),
+        mustRetainAnchor: trailingMayBeAnchor,
+        removedLines,
+    });
+    const trimmedLines = trailingLength === 0 ? remainder : remainder.slice(0, -trailingLength);
+    return { leadingLength, replacementLines: trimmedLines, trailingLength };
+}
+export function trimReplacementToContext(fileLines, startLine, endLine, replacementLines) {
+    return analyzeReplacementContext(fileLines, startLine, endLine, replacementLines)
+        .replacementLines;
+}

package/bin/suggestions/patch.mjs

@@ -4,53 +4,10 @@
  * The diff uses `--- a/<path>` / `+++ b/<path>` headers so `git apply` and
  * `git apply --check` accept it without a `diff --git` preamble.
  */
-/**
- * Strip leading/trailing replacement lines that are identical to the adjacent
- * file lines just outside the removed range.
- *
- * GitHub stores a suggestion as a verbatim replacement for the *highlighted*
- * line range, but reviewers often paste surrounding context into the box. Those
- * context-duplicating lines must not appear as additions in the diff — they
- * belong to the surrounding unchanged file content. Stripping them here produces
- * a minimal diff that applies cleanly without duplicating lines.
- *
- * Comparison normalises trailing `\r` from file lines so CRLF files (which
- * carry `\r` on each entry after `split("\n")`) still match suggestion lines
- * delivered as LF-only by the GitHub API.
- */
-function trimReplacementToContext(fileLines, startLine, endLine, replacementLines) {
-    const norm = (s) => (s.endsWith("\r") ? s.slice(0, -1) : s);
-    // Leading trim: largest L where replacement[0..L) == fileLines[startLine-1-L..startLine-1)
-    const maxL = Math.min(startLine - 1, replacementLines.length);
-    let L = 0;
-    leading: for (let l = maxL; l >= 1; l--) {
-        for (let i = 0; i < l; i++) {
-            if (norm(replacementLines[i]) !== norm(fileLines[startLine - 1 - l + i]))
-                continue leading;
-        }
-        L = l;
-        break;
-    }
-    const remainder = replacementLines.slice(L);
-    // Trailing trim: largest T where remainder[len-T..len) == fileLines[endLine..endLine+T)
-    const maxT = Math.min(fileLines.length - endLine, remainder.length);
-    let T = 0;
-    trailing: for (let t = maxT; t >= 1; t--) {
-        for (let j = 0; j < t; j++) {
-            if (norm(remainder[remainder.length - t + j]) !== norm(fileLines[endLine + j]))
-                continue trailing;
-        }
-        T = t;
-        break;
-    }
-    if (L === 0 && T === 0)
-        return replacementLines;
-    return T === 0 ? remainder : remainder.slice(0, remainder.length - T);
-}
+import { splitFileLines, trimReplacementToContext } from "./lines.mjs";
 export function buildUnifiedDiff({ path, originalContent, startLine, endLine, replacementLines, context = 3, }) {
     const endsWithNewline = originalContent.endsWith("\n");
-    const body = endsWithNewline ? originalContent.slice(0, -1) : originalContent;
-    const fileLines = body === "" ? [] : body.split("\n");
+    const fileLines = splitFileLines(originalContent);
     const removedLines = fileLines.slice(startLine - 1, endLine);
     const beforeStart = Math.max(0, startLine - 1 - context);
     const beforeLines = fileLines.slice(beforeStart, startLine - 1);

package/bin/suggestions/range-adjacent.d.mts

@@ -0,0 +1,7 @@
+export declare function getAdjacentSuggestionRangeReason({ fileLines, removedLines, startLine, endLine, replacementLines, }: {
+    fileLines: readonly string[];
+    removedLines: readonly string[];
+    startLine: number;
+    endLine: number;
+    replacementLines: readonly string[];
+}): string | null;

package/bin/suggestions/range-adjacent.mjs

@@ -0,0 +1,100 @@
+import { findLineSequenceOffsets } from "./range-anchor.mjs";
+import { sharesExactProperPrefix, sharesExactProperSuffix } from "./range-exact-overlap.mjs";
+import { likelyRewritesChangedLineSubrange, likelyRewritesAdjacentSpan, } from "./range-similarity.mjs";
+import { createScanWorkBudget } from "./range-work.mjs";
+function adjacentSpansBefore(fileLines, startLine, replacementLineCount) {
+    const endIndex = startLine - 1;
+    const limit = Math.min(endIndex, Math.max(2, replacementLineCount * 2));
+    return Array.from({ length: limit }, (_, index) => fileLines.slice(endIndex - index - 1, endIndex));
+}
+function adjacentSpansAfter(fileLines, endLine, replacementLineCount) {
+    const limit = Math.min(fileLines.length - endLine, Math.max(2, replacementLineCount * 2));
+    return Array.from({ length: limit }, (_, index) => fileLines.slice(endLine, endLine + index + 1));
+}
+function likelyRewritesAdjacentSource(replacementLines, adjacentSpans, allowSingleLinePair) {
+    if (adjacentSpans
+        .slice(0, 8)
+        .some((span) => likelyRewritesAdjacentSpan(replacementLines, span, allowSingleLinePair))) {
+        return true;
+    }
+    return likelyRewritesChangedLineSubrange(replacementLines, adjacentSpans);
+}
+function extensionRewritesAfter(fileLines, endLine, extension) {
+    if (extension.length === 0)
+        return false;
+    const adjacentLines = fileLines.slice(endLine, endLine + extension.length);
+    return (sharesExactProperPrefix(extension, adjacentLines) ||
+        likelyRewritesAdjacentSource(extension, adjacentSpansAfter(fileLines, endLine, extension.length), true));
+}
+function extensionRewritesBefore(fileLines, startLine, extension) {
+    if (extension.length === 0)
+        return false;
+    const adjacentStart = startLine - 1 - extension.length;
+    const adjacentLines = fileLines.slice(Math.max(0, adjacentStart), startLine - 1);
+    return (sharesExactProperSuffix(extension, adjacentLines) ||
+        likelyRewritesAdjacentSource(extension, adjacentSpansBefore(fileLines, startLine, extension.length), true));
+}
+function scanExtension(fileLines, startLine, endLine, extension, direction, chargeScanWork) {
+    const available = direction === "before" ? startLine - 1 : fileLines.length - endLine;
+    if (chargeScanWork(extension.length, available))
+        return "work";
+    const rewrites = direction === "before"
+        ? extensionRewritesBefore(fileLines, startLine, extension)
+        : extensionRewritesAfter(fileLines, endLine, extension);
+    return rewrites ? direction : null;
+}
+function retainedAnchorRewriteDirection(fileLines, removedLines, startLine, endLine, replacementLines, chargeScanWork) {
+    const offsets = findLineSequenceOffsets(replacementLines, removedLines);
+    // Bound repeated extension scans while rejecting ambiguous bodies safely.
+    if (offsets.length * replacementLines.length > 4_096)
+        return "ambiguous";
+    if (offsets.length === 0)
+        return null;
+    for (const offset of offsets) {
+        const before = replacementLines.slice(0, offset);
+        const after = replacementLines.slice(offset + removedLines.length);
+        const scans = [
+            [after, "after"],
+            [after, "before"],
+            [before, "before"],
+            [before, "after"],
+        ];
+        for (const [extension, direction] of scans) {
+            const result = scanExtension(fileLines, startLine, endLine, extension, direction, chargeScanWork);
+            if (result !== null)
+                return result;
+        }
+    }
+    return "safe";
+}
+export function getAdjacentSuggestionRangeReason({ fileLines, removedLines, startLine, endLine, replacementLines, }) {
+    const chargeScanWork = createScanWorkBudget();
+    const retainedAnchorDirection = retainedAnchorRewriteDirection(fileLines, removedLines, startLine, endLine, replacementLines, chargeScanWork);
+    if (retainedAnchorDirection === "after") {
+        return "The replacement retains the complete anchored range and appears to rewrite source immediately after it.";
+    }
+    if (retainedAnchorDirection === "before") {
+        return "The replacement retains the complete anchored range and appears to rewrite source immediately before it.";
+    }
+    if (retainedAnchorDirection === "ambiguous") {
+        return "The replacement repeats the complete anchored range too many times to validate its surrounding source safely.";
+    }
+    if (retainedAnchorDirection === "work") {
+        return "The replacement and adjacent source require too much similarity work to validate the anchored range safely.";
+    }
+    if (retainedAnchorDirection === "safe")
+        return null;
+    if (chargeScanWork(replacementLines.length, startLine - 1)) {
+        return "The replacement and adjacent source require too much similarity work to validate the anchored range safely.";
+    }
+    if (likelyRewritesAdjacentSource(replacementLines, adjacentSpansBefore(fileLines, startLine, replacementLines.length), false)) {
+        return "The replacement partially rewrites a source block before the anchored range.";
+    }
+    if (chargeScanWork(replacementLines.length, fileLines.length - endLine)) {
+        return "The replacement and adjacent source require too much similarity work to validate the anchored range safely.";
+    }
+    if (likelyRewritesAdjacentSource(replacementLines, adjacentSpansAfter(fileLines, endLine, replacementLines.length), false)) {
+        return "The replacement partially rewrites a source block after the anchored range.";
+    }
+    return null;
+}

package/bin/suggestions/range-anchor.d.mts

@@ -0,0 +1 @@
+export declare function findLineSequenceOffsets(lines: readonly string[], sequence: readonly string[]): readonly number[];

package/bin/suggestions/range-anchor.mjs

@@ -0,0 +1,40 @@
+import { normalizeLine } from "./lines.mjs";
+function buildPrefixTable(pattern) {
+    const table = Array.from({ length: pattern.length }, () => 0);
+    let prefixLength = 0;
+    for (let index = 1; index < pattern.length;) {
+        if (pattern[index] === pattern[prefixLength]) {
+            prefixLength++;
+            table[index] = prefixLength;
+            index++;
+        }
+        else if (prefixLength > 0) {
+            prefixLength = table[prefixLength - 1];
+        }
+        else {
+            index++;
+        }
+    }
+    return table;
+}
+export function findLineSequenceOffsets(lines, sequence) {
+    if (sequence.length === 0)
+        return [];
+    const pattern = sequence.map(normalizeLine);
+    const prefixTable = buildPrefixTable(pattern);
+    const offsets = [];
+    let matchedLength = 0;
+    for (let index = 0; index < lines.length; index++) {
+        const line = normalizeLine(lines[index]);
+        while (matchedLength > 0 && line !== pattern[matchedLength]) {
+            matchedLength = prefixTable[matchedLength - 1];
+        }
+        if (line === pattern[matchedLength])
+            matchedLength++;
+        if (matchedLength !== pattern.length)
+            continue;
+        offsets.push(index - pattern.length + 1);
+        matchedLength = prefixTable[matchedLength - 1];
+    }
+    return offsets;
+}

package/bin/suggestions/range-exact-overlap.d.mts

@@ -0,0 +1,2 @@
+export declare function sharesExactProperPrefix(replacementLines: readonly string[], adjacentLines: readonly string[]): boolean;
+export declare function sharesExactProperSuffix(replacementLines: readonly string[], adjacentLines: readonly string[]): boolean;

package/bin/suggestions/range-exact-overlap.mjs

@@ -0,0 +1,28 @@
+import { normalizeLine } from "./lines.mjs";
+function sharedExactPrefixLength(replacementLines, adjacentLines) {
+    const limit = Math.min(replacementLines.length, adjacentLines.length);
+    let length = 0;
+    while (length < limit &&
+        normalizeLine(replacementLines[length]) === normalizeLine(adjacentLines[length])) {
+        length++;
+    }
+    return length;
+}
+function sharedExactSuffixLength(replacementLines, adjacentLines) {
+    const limit = Math.min(replacementLines.length, adjacentLines.length);
+    let length = 0;
+    while (length < limit &&
+        normalizeLine(replacementLines[replacementLines.length - 1 - length]) ===
+            normalizeLine(adjacentLines[adjacentLines.length - 1 - length])) {
+        length++;
+    }
+    return length;
+}
+export function sharesExactProperPrefix(replacementLines, adjacentLines) {
+    const sharedLength = sharedExactPrefixLength(replacementLines, adjacentLines);
+    return sharedLength > 0 && sharedLength < replacementLines.length;
+}
+export function sharesExactProperSuffix(replacementLines, adjacentLines) {
+    const sharedLength = sharedExactSuffixLength(replacementLines, adjacentLines);
+    return sharedLength > 0 && sharedLength < replacementLines.length;
+}

package/bin/suggestions/range-similarity.d.mts

@@ -0,0 +1,2 @@
+export declare function likelyRewritesAdjacentSpan(replacementLines: readonly string[], adjacentLines: readonly string[], allowSingleLinePair: boolean): boolean;
+export declare function likelyRewritesChangedLineSubrange(replacementLines: readonly string[], adjacentSpans: readonly (readonly string[])[]): boolean;

package/bin/suggestions/range-similarity.mjs

@@ -0,0 +1,135 @@
+import { normalizeLine } from "./lines.mjs";
+import { hasLetterOrNumber, isSubstantiveExactAlignedBlock, isSubstantiveLine, isSubstantiveSharedRun, } from "./range-substantive.mjs";
+function closelyRewritesText(replacement, adjacent) {
+    const shorterLength = Math.min(replacement.length, adjacent.length);
+    let prefixLength = 0;
+    while (prefixLength < shorterLength && replacement[prefixLength] === adjacent[prefixLength]) {
+        prefixLength++;
+    }
+    let suffixLength = 0;
+    while (prefixLength + suffixLength < shorterLength &&
+        replacement[replacement.length - 1 - suffixLength] ===
+            adjacent[adjacent.length - 1 - suffixLength]) {
+        suffixLength++;
+    }
+    const sharedLength = prefixLength + suffixLength;
+    return sharedLength >= 12 && sharedLength >= Math.ceil(shorterLength * 0.6);
+}
+function normalizeBlockText(lines) {
+    return lines.map(normalizeLine).join(" ").trim().replace(/\s+/g, " ");
+}
+const normalizeSharedLine = (line) => normalizeLine(line).trim().replace(/\s+/g, " ");
+function sharedInternalRunAt(replacementLines, adjacentLines, replacementStart, adjacentStart) {
+    const sharedLines = [];
+    while (replacementStart + sharedLines.length < replacementLines.length - 1 &&
+        adjacentStart + sharedLines.length < adjacentLines.length - 1) {
+        const replacement = normalizeSharedLine(replacementLines[replacementStart + sharedLines.length]);
+        const adjacent = normalizeSharedLine(adjacentLines[adjacentStart + sharedLines.length]);
+        if (replacement !== adjacent)
+            break;
+        sharedLines.push(replacement);
+    }
+    return sharedLines;
+}
+function hasSubstantiveInternalOverlap(replacementLines, adjacentLines) {
+    if (replacementLines.length < 4 || adjacentLines.length < 4)
+        return false;
+    for (let replacementStart = 1; replacementStart < replacementLines.length - 1; replacementStart++) {
+        for (let adjacentStart = 1; adjacentStart < adjacentLines.length - 1; adjacentStart++) {
+            if (isSubstantiveSharedRun(sharedInternalRunAt(replacementLines, adjacentLines, replacementStart, adjacentStart))) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+export function likelyRewritesAdjacentSpan(replacementLines, adjacentLines, allowSingleLinePair) {
+    if (replacementLines.length === 0 || adjacentLines.length === 0)
+        return false;
+    if (!allowSingleLinePair && replacementLines.length === 1 && adjacentLines.length === 1) {
+        return false;
+    }
+    const replacement = normalizeBlockText(replacementLines);
+    const adjacent = normalizeBlockText(adjacentLines);
+    return (replacement === adjacent ||
+        closelyRewritesText(replacement, adjacent) ||
+        hasSubstantiveInternalOverlap(replacementLines, adjacentLines));
+}
+function alignedLineRelation(replacementLine, adjacentLine) {
+    const replacement = normalizeSharedLine(replacementLine);
+    const adjacent = normalizeSharedLine(adjacentLine);
+    if (replacement === adjacent) {
+        const isNeutral = replacement === "" || !hasLetterOrNumber(replacement);
+        return isNeutral || isSubstantiveLine(replacementLine) ? "exact" : null;
+    }
+    if (!isSubstantiveLine(replacementLine) || !isSubstantiveLine(adjacentLine))
+        return null;
+    return closelyRewritesText(replacement, adjacent) ? "changed" : null;
+}
+function isMixedAlignedRewrite(candidate, adjacentSpan) {
+    for (let index = 0; index < candidate.length - 1; index++) {
+        const first = alignedLineRelation(candidate[index], adjacentSpan[index]);
+        const second = alignedLineRelation(candidate[index + 1], adjacentSpan[index + 1]);
+        if ((first === "exact" && second === "changed") ||
+            (first === "changed" && second === "exact")) {
+            return true;
+        }
+    }
+    return false;
+}
+function isChangedWithUnrelatedSubstantiveNeighbors(candidate, adjacentSpan) {
+    const relations = new Set(candidate.map((line, index) => alignedLineRelation(line, adjacentSpan[index])));
+    if (!relations.has("changed") || relations.has("exact"))
+        return false;
+    if (![...candidate, ...adjacentSpan].every((line) => isSubstantiveLine(line) || !hasLetterOrNumber(line))) {
+        return false;
+    }
+    return (candidate.filter((line, index) => isSubstantiveLine(line) && isSubstantiveLine(adjacentSpan[index])).length >= 2);
+}
+function likelyRewritesChangedWindow(replacementLines, adjacentSpan) {
+    const length = adjacentSpan.length;
+    for (let start = 0; start <= replacementLines.length - length; start++) {
+        const candidate = replacementLines.slice(start, start + length);
+        if (isMixedAlignedRewrite(candidate, adjacentSpan))
+            return true;
+        if (isChangedWithUnrelatedSubstantiveNeighbors(candidate, adjacentSpan))
+            return true;
+        const isProperSubrange = start > 0 || start + length < replacementLines.length;
+        if (isProperSubrange && isSubstantiveExactAlignedBlock(candidate, adjacentSpan)) {
+            return true;
+        }
+        if (!candidate.every(isSubstantiveLine) || !adjacentSpan.every(isSubstantiveLine))
+            continue;
+        const hasExactLine = candidate.some((line, index) => normalizeSharedLine(line) === normalizeSharedLine(adjacentSpan[index]));
+        if (length > 8 || hasExactLine)
+            continue;
+        if (likelyRewritesAdjacentSpan(candidate, adjacentSpan, true))
+            return true;
+    }
+    return false;
+}
+export function likelyRewritesChangedLineSubrange(replacementLines, adjacentSpans) {
+    if (replacementLines.length < 2)
+        return false;
+    const adjacentLine = adjacentSpans.find((span) => span.length === 1)?.[0];
+    if (adjacentLine !== undefined && isSubstantiveLine(adjacentLine)) {
+        const adjacent = normalizeSharedLine(adjacentLine);
+        if (replacementLines.some((line) => {
+            if (!isSubstantiveLine(line))
+                return false;
+            const replacement = normalizeSharedLine(line);
+            return replacement !== adjacent && closelyRewritesText(replacement, adjacent);
+        })) {
+            return true;
+        }
+    }
+    const maxLength = Math.min(replacementLines.length, adjacentSpans.length);
+    for (let length = 2; length <= maxLength; length++) {
+        const adjacentSpan = adjacentSpans.find((span) => span.length === length);
+        if (adjacentSpan === undefined)
+            continue;
+        if (likelyRewritesChangedWindow(replacementLines, adjacentSpan))
+            return true;
+    }
+    return false;
+}

package/bin/suggestions/range-substantive.d.mts

@@ -0,0 +1,4 @@
+export declare const hasLetterOrNumber: (line: string) => boolean;
+export declare const isSubstantiveLine: (line: string) => boolean;
+export declare function isSubstantiveSharedRun(sharedLines: readonly string[]): boolean;
+export declare function isSubstantiveExactAlignedBlock(candidate: readonly string[], adjacentLines: readonly string[]): boolean;

package/bin/suggestions/range-substantive.mjs

@@ -0,0 +1,12 @@
+import { normalizeLine } from "./lines.mjs";
+export const hasLetterOrNumber = (line) => /[\p{L}\p{N}]/u.test(line);
+export const isSubstantiveLine = (line) => hasLetterOrNumber(line) && line.replace(/\s/g, "").length >= 8;
+export function isSubstantiveSharedRun(sharedLines) {
+    const substantiveLines = sharedLines.filter(isSubstantiveLine);
+    return substantiveLines.length >= 2 && substantiveLines.join("").replace(/\s/g, "").length >= 24;
+}
+export function isSubstantiveExactAlignedBlock(candidate, adjacentLines) {
+    return (isSubstantiveSharedRun(candidate) &&
+        candidate.every((line, index) => normalizeLine(line).trim().replace(/\s+/g, " ") ===
+            normalizeLine(adjacentLines[index]).trim().replace(/\s+/g, " ")));
+}

package/bin/suggestions/range-work.d.mts

@@ -0,0 +1,2 @@
+export type ChargeScanWork = (replacementLineCount: number, availableLineCount: number) => boolean;
+export declare function createScanWorkBudget(): ChargeScanWork;

package/bin/suggestions/range-work.mjs

@@ -0,0 +1,12 @@
+const MAX_ADJACENT_SCAN_WORK = 1_000_000;
+function estimatedScanWork(replacementLineCount, availableLineCount) {
+    const changedWindowLimit = Math.min(availableLineCount, replacementLineCount);
+    return replacementLineCount * changedWindowLimit ** 2;
+}
+export function createScanWorkBudget() {
+    let work = 0;
+    return (replacementLineCount, availableLineCount) => {
+        work += estimatedScanWork(replacementLineCount, availableLineCount);
+        return work > MAX_ADJACENT_SCAN_WORK;
+    };
+}

package/bin/suggestions/range.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Return why a suggestion body cannot be reconciled safely with GitHub's
+ * anchored line range, or null when the exact range is safe to use.
+ *
+ * The range is authoritative: this validator never shifts or expands it. It
+ * only detects bodies that appear to reach beyond the anchor, leaving manual
+ * interpretation to the caller instead of emitting a structurally unsafe diff.
+ */
+export declare function getUnsafeSuggestionRangeReason({ originalContent, startLine, endLine, replacementLines, }: {
+    originalContent: string;
+    startLine: number;
+    endLine: number;
+    replacementLines: readonly string[];
+}): string | null;

package/bin/suggestions/range.mjs

@@ -0,0 +1,56 @@
+import { analyzeReplacementContext, normalizeLine, splitFileLines } from "./lines.mjs";
+import { getAdjacentSuggestionRangeReason } from "./range-adjacent.mjs";
+import { findLineSequenceOffsets } from "./range-anchor.mjs";
+import { hasLetterOrNumber } from "./range-substantive.mjs";
+function discardedContextContainsAnchorLine({ leadingLength, removedLines, replacementLines, trailingLength, }) {
+    if (removedLines.length < 2)
+        return false;
+    const discardedLines = [
+        ...replacementLines.slice(0, leadingLength),
+        ...replacementLines.slice(replacementLines.length - trailingLength),
+    ];
+    const normalizedAnchorLines = new Set(removedLines.map(normalizeLine).filter(hasLetterOrNumber));
+    return discardedLines.some((line) => normalizedAnchorLines.has(normalizeLine(line)));
+}
+/**
+ * Return why a suggestion body cannot be reconciled safely with GitHub's
+ * anchored line range, or null when the exact range is safe to use.
+ *
+ * The range is authoritative: this validator never shifts or expands it. It
+ * only detects bodies that appear to reach beyond the anchor, leaving manual
+ * interpretation to the caller instead of emitting a structurally unsafe diff.
+ */
+export function getUnsafeSuggestionRangeReason({ originalContent, startLine, endLine, replacementLines, }) {
+    const fileLines = splitFileLines(originalContent);
+    if (!Number.isInteger(startLine) ||
+        !Number.isInteger(endLine) ||
+        startLine < 1 ||
+        endLine < startLine ||
+        endLine > fileLines.length) {
+        return `GitHub reported an invalid or out-of-bounds range (${startLine}-${endLine}) for a ${fileLines.length}-line file.`;
+    }
+    const removedLines = fileLines.slice(startLine - 1, endLine);
+    const contextTrim = analyzeReplacementContext(fileLines, startLine, endLine, replacementLines);
+    if (contextTrim.leadingLength > 0 || contextTrim.trailingLength > 0) {
+        const originalOccurrences = findLineSequenceOffsets(replacementLines, removedLines).length;
+        const trimmedOccurrences = findLineSequenceOffsets(contextTrim.replacementLines, removedLines).length;
+        if (originalOccurrences > trimmedOccurrences) {
+            return "Exact-context trimming would discard a complete copy of the anchored range, so the intended duplicate insertion is ambiguous.";
+        }
+        if (discardedContextContainsAnchorLine({
+            leadingLength: contextTrim.leadingLength,
+            removedLines,
+            replacementLines,
+            trailingLength: contextTrim.trailingLength,
+        })) {
+            return "Exact-context trimming would discard a partial copy of the anchored range, so the intended duplicate insertion is ambiguous.";
+        }
+    }
+    return getAdjacentSuggestionRangeReason({
+        fileLines,
+        removedLines,
+        startLine,
+        endLine,
+        replacementLines: contextTrim.replacementLines,
+    });
+}

package/package.json

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

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

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

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

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

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

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.37.0", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.37.2", "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.