pr-shepherd 0.37.1 → 0.38.0

package/.claude-plugin/plugin.json

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

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

@@ -50,7 +50,7 @@ Selectors:
 --help, -h                      Print this help and exit before GitHub I/O.`;
     readonly "apply journal": `pr-shepherd apply journal
 
-Append a list item to the ## Shepherd Journal section of a PR body.
+Append a list item to the Shepherd Journal details block of a PR body.
 
 Usage:
   pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]
@@ -205,7 +205,7 @@ Flags:
 Exit code: 0 on success (including a no-op --dry-run on a nonexistent target); nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
     readonly journal: `pr-shepherd journal
 
-Append a list item to the ## Shepherd Journal section of a PR body.
+Append a list item to the Shepherd Journal details block of a PR body.
 Creates the section at the end if absent. Idempotent — duplicate items are skipped.
 
 Usage:

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

@@ -53,7 +53,7 @@ Selectors:
 --help, -h                      Print this help and exit before GitHub I/O.`,
     "apply journal": `pr-shepherd apply journal
 
-Append a list item to the ## Shepherd Journal section of a PR body.
+Append a list item to the Shepherd Journal details block of a PR body.
 
 Usage:
   pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]
@@ -208,7 +208,7 @@ Flags:
 Exit code: 0 on success (including a no-op --dry-run on a nonexistent target); nonzero on failure (sysexits.h — see docs/exit-codes.md).`,
     journal: `pr-shepherd journal
 
-Append a list item to the ## Shepherd Journal section of a PR body.
+Append a list item to the Shepherd Journal details block of a PR body.
 Creates the section at the end if absent. Idempotent — duplicate items are skipped.
 
 Usage:

package/bin/cli/help-top-page.d.mts

@@ -1 +1 @@
-export declare const TOP_USAGE = "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR] [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd build-suggestion-patch [PR] --thread-id ID --message MSG [flags]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR]                 Poll until non-WAIT or timeout. This is the default command.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark changed files as viewed in GitHub.\n  apply journal        Append a list item to the ## Shepherd Journal section of a PR body.\n  build-suggestion-patch\n                       Convert one GitHub suggestion thread into a patch and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number such as 42 or a GitHub pull request URL.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\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\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Poll wall-clock cap 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\nClean variants:\n  pr [number]          Remove state for one PR. Defaults to current branch PR.\n  branch [name]        Remove state for a branch's PR. Defaults to current branch.\n  current              Alias for branch against the current branch.\n  repo                 Remove all state for the current repository.\n  all                  Remove all pr-shepherd state.\n\nExit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).\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)\nSee docs/exit-codes.md for the full sysexits.h error-code table.\n\nDuration examples: 30s, 4.5m, 1h. A bare number uses each flag's default unit (see above); decimals are allowed with an explicit unit (4.5m).\n\nRun 'pr-shepherd <command> --help' for command-specific details.";
+export declare const TOP_USAGE = "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR] [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd build-suggestion-patch [PR] --thread-id ID --message MSG [flags]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR]                 Poll until non-WAIT or timeout. This is the default command.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark changed files as viewed in GitHub.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  build-suggestion-patch\n                       Convert one GitHub suggestion thread into a patch and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number such as 42 or a GitHub pull request URL.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\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\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Poll wall-clock cap 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\nClean variants:\n  pr [number]          Remove state for one PR. Defaults to current branch PR.\n  branch [name]        Remove state for a branch's PR. Defaults to current branch.\n  current              Alias for branch against the current branch.\n  repo                 Remove all state for the current repository.\n  all                  Remove all pr-shepherd state.\n\nExit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).\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)\nSee docs/exit-codes.md for the full sysexits.h error-code table.\n\nDuration examples: 30s, 4.5m, 1h. A bare number uses each flag's default unit (see above); decimals are allowed with an explicit unit (4.5m).\n\nRun 'pr-shepherd <command> --help' for command-specific details.";

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

@@ -19,7 +19,7 @@ Commands:
   iterate              Run one iterate tick (single-tick alias).
   apply review         Apply review-state mutations after fixes.
   apply files          Mark changed files as viewed in GitHub.
-  apply journal        Append a list item to the ## Shepherd Journal section of a PR body.
+  apply journal        Append a list item to the Shepherd Journal details block of a PR body.
   build-suggestion-patch
                        Convert one GitHub suggestion thread into a patch and commit instructions.
   admin clean          Remove pr-shepherd state files.

package/bin/cli/help.d.mts

@@ -50,7 +50,7 @@ Selectors:
 --help, -h                      Print this help and exit before GitHub I/O.`;
     readonly "apply journal": `pr-shepherd apply journal
 
-Append a list item to the ## Shepherd Journal section of a PR body.
+Append a list item to the Shepherd Journal details block of a PR body.
 
 Usage:
   pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]
@@ -205,7 +205,7 @@ Flags:
 Exit code: 0 on success (including a no-op --dry-run on a nonexistent target); nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
     readonly journal: `pr-shepherd journal
 
-Append a list item to the ## Shepherd Journal section of a PR body.
+Append a list item to the Shepherd Journal details block of a PR body.
 Creates the section at the end if absent. Idempotent — duplicate items are skipped.
 
 Usage:
@@ -228,7 +228,7 @@ Flags:
 
 Exit code: 0 on success (including no-change no-op); nonzero on failure (sysexits.h — see docs/exit-codes.md).`;
     readonly "log-file": "pr-shepherd log-file\n\nPrint the per-worktree append-only debug log path for the current repository.\nThe log is created by the first non-help pr-shepherd command that initializes logging.\n\nUsage:\n  pr-shepherd log-file [--format text|json]\n\nFlags:\n  --format text|json   Print a raw path or {\"path\": \"...\"} JSON. Default: text.\n  --help, -h           Print this help and exit before logging setup.\n\nEnvironment:\n  PR_SHEPHERD_LOG_DISABLED=1 disables logging.\n  PR_SHEPHERD_STATE_DIR overrides the base state directory.\n\nExit code: 0 on success; 1 if repository identity cannot be resolved.";
-    readonly top: "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR] [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd build-suggestion-patch [PR] --thread-id ID --message MSG [flags]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR]                 Poll until non-WAIT or timeout. This is the default command.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark changed files as viewed in GitHub.\n  apply journal        Append a list item to the ## Shepherd Journal section of a PR body.\n  build-suggestion-patch\n                       Convert one GitHub suggestion thread into a patch and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number such as 42 or a GitHub pull request URL.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\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\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Poll wall-clock cap 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\nClean variants:\n  pr [number]          Remove state for one PR. Defaults to current branch PR.\n  branch [name]        Remove state for a branch's PR. Defaults to current branch.\n  current              Alias for branch against the current branch.\n  repo                 Remove all state for the current repository.\n  all                  Remove all pr-shepherd state.\n\nExit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).\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)\nSee docs/exit-codes.md for the full sysexits.h error-code table.\n\nDuration examples: 30s, 4.5m, 1h. A bare number uses each flag's default unit (see above); decimals are allowed with an explicit unit (4.5m).\n\nRun 'pr-shepherd <command> --help' for command-specific details.";
+    readonly top: "pr-shepherd\n\nAutonomous PR CI monitor and review-comment resolver for agentic coding tools.\n\nUsage:\n  pr-shepherd --version | -v\n  pr-shepherd --help | -h\n  pr-shepherd [PR] [poll-flags] [iterate-flags]\n  pr-shepherd iterate [PR] [iterate-flags]\n  pr-shepherd apply review [PR] [review-flags]\n  pr-shepherd apply files [PR] [files...] [--tests] [--match REGEX]\n  pr-shepherd apply journal [PR] <item> [--dry-run] [--format text|json]\n  pr-shepherd build-suggestion-patch [PR] --thread-id ID --message MSG [flags]\n  pr-shepherd admin clean <pr|branch|current|repo|all> [value] [flags]\n  pr-shepherd admin log-file [--format text|json]\n\nCommands:\n  [PR]                 Poll until non-WAIT or timeout. This is the default command.\n  iterate              Run one iterate tick (single-tick alias).\n  apply review         Apply review-state mutations after fixes.\n  apply files          Mark changed files as viewed in GitHub.\n  apply journal        Append a list item to the Shepherd Journal details block of a PR body.\n  build-suggestion-patch\n                       Convert one GitHub suggestion thread into a patch and commit instructions.\n  admin clean          Remove pr-shepherd state files.\n  admin log-file       Print the per-worktree debug log path.\n\nPR argument:\n  PR may be a number such as 42 or a GitHub pull request URL.\n  When omitted, pr-shepherd infers the current branch's pull request.\n\nCommon flags:\n  --format text|json   Output Markdown text or JSON. Default: text.\n  --verbose            Include verbose iterate fields and detailed poll-tick lines.\n  --help, -h           Print help and exit before any GitHub, git, config, or log I/O.\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\nPolling flags:\n  --interval <duration>          Delay between WAIT ticks. Bare number = seconds. Default: 60s.\n  --timeout <duration>           Poll wall-clock cap 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\nClean variants:\n  pr [number]          Remove state for one PR. Defaults to current branch PR.\n  branch [name]        Remove state for a branch's PR. Defaults to current branch.\n  current              Alias for branch against the current branch.\n  repo                 Remove all state for the current repository.\n  all                  Remove all pr-shepherd state.\n\nExit codes: 0 done, 10-19 PR state, 64-78 shepherd failed (sysexits.h).\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)\nSee docs/exit-codes.md for the full sysexits.h error-code table.\n\nDuration examples: 30s, 4.5m, 1h. A bare number uses each flag's default unit (see above); decimals are allowed with an explicit unit (4.5m).\n\nRun 'pr-shepherd <command> --help' for command-specific details.";
 };
 /** Resolve help keys for nested public commands before any command I/O. */
 export declare function helpKeyForArgs(args: string[]): keyof typeof USAGE;

package/bin/cli/journal-formatter.mjs

@@ -9,7 +9,7 @@ export function formatJournalResult(result) {
     if (!result.mutated)
         return "No change — entry already present.";
     if (!result.sectionExisted) {
-        return `Created ## Shepherd Journal section in PR #${result.prNumber}.`;
+        return `Created Shepherd Journal details in PR #${result.prNumber}.`;
     }
-    return `Appended to ## Shepherd Journal in PR #${result.prNumber}.`;
+    return `Appended to Shepherd Journal details in PR #${result.prNumber}.`;
 }

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

@@ -19,9 +19,12 @@ export function buildCommitSuggestionInstruction(prNumber, sectionName, includeD
     const driftHint = includeDriftHint
         ? "If the patch does not apply because the suggestion drifted, use the manual-fix step below. Do not retry the command."
         : "If the patch does not apply, use the manual-edit step below. Do not retry the command.";
+    const manualStep = includeDriftHint ? "manual-fix step" : "manual-edit step";
     return [
         `For each thread marked \`[suggestion]\` under \`${sectionName}\`, run \`${command}\` to retrieve its patch and suggested commit.`,
         "The CLI only builds the patch. Apply it, stage the listed file, and follow the returned commit instructions.",
+        `If the command refuses because the suggestion is unsafe (an unsafe anchored range or nested/unbalanced suggestion fences), skip patch application and use the ${manualStep} below. Do not retry the command.`,
+        "For any other refusal, follow the CLI error's stated recovery action; do not manually edit the suggestion.",
         driftHint,
         "Keep human-authored thread IDs in `apply review:` so Shepherd replies instead of resolving them.",
     ];

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/render.mjs

@@ -68,7 +68,7 @@ isBehind = false) {
         const filesRef = threads.length > 0 ? "each file referenced above" : "the relevant files";
         instructions.push(`Apply every warranted review fix in ${filesRef}.`);
         if (hasSuggestions) {
-            instructions.push("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.");
+            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) {

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

@@ -0,0 +1,11 @@
+type ValidationOk = {
+    ok: true;
+    item: string;
+};
+type ValidationError = {
+    ok: false;
+    error: string;
+};
+export type ValidationResult = ValidationOk | ValidationError;
+export declare function validateJournalItem(input: string): ValidationResult;
+export {};

package/bin/commands/journal/journal-item.mjs

@@ -0,0 +1,29 @@
+import { isJournalLikeSummary, isReservedJournalMarker } from "./journal-markdown.mjs";
+export function validateJournalItem(input) {
+    const lines = input.split("\n").map((line) => line.trimEnd());
+    const nonBlank = lines.filter((line) => line.trim() !== "");
+    if (nonBlank.length === 0) {
+        return { ok: false, error: 'journal item must not be empty; expected a "- <text>" list item' };
+    }
+    if (!/^- \S/.test(nonBlank[0])) {
+        return {
+            ok: false,
+            error: `journal item must start with "- <text>"; got: ${JSON.stringify(nonBlank[0].slice(0, 40))}`,
+        };
+    }
+    for (const line of nonBlank.slice(1)) {
+        if (line.startsWith("#")) {
+            return {
+                ok: false,
+                error: "journal item lines must not start with # (would break section structure)",
+            };
+        }
+        if (isReservedJournalMarker(line.trim()) || isJournalLikeSummary(line.trim())) {
+            return {
+                ok: false,
+                error: `journal item must not contain standalone journal container marker ${JSON.stringify(line.trim())}`,
+            };
+        }
+    }
+    return { ok: true, item: lines.join("\n").trim() };
+}

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

@@ -0,0 +1,13 @@
+type Fence = {
+    marker: "`" | "~";
+    length: number;
+};
+export type MarkdownScanState = {
+    comment: boolean;
+    fence: Fence | null;
+};
+export declare function findDetailsClose(lines: string[], startIdx: number): number;
+export declare function isJournalLikeSummary(line: string): boolean;
+export declare function isReservedJournalMarker(line: string): boolean;
+export declare function skipMarkdownLine(state: MarkdownScanState, line: string): boolean;
+export {};

package/bin/commands/journal/journal-markdown.mjs

@@ -0,0 +1,66 @@
+import { SHEPHERD_JOURNAL_DETAILS_CLOSE, SHEPHERD_JOURNAL_DETAILS_SUMMARY, } from "../shepherd-journal.mjs";
+export function findDetailsClose(lines, startIdx) {
+    let depth = 1;
+    const state = { fence: null, comment: false };
+    for (let i = startIdx; i < lines.length; i++) {
+        if (skipMarkdownLine(state, lines[i]))
+            continue;
+        if (isJournalLikeSummary(lines[i].trimStart())) {
+            throw new Error("duplicate Shepherd Journal details summary inside canonical container");
+        }
+        if (isDetailsOpening(lines[i]))
+            depth++;
+        if (lines[i].trim() === SHEPHERD_JOURNAL_DETAILS_CLOSE) {
+            if (lines[i] !== SHEPHERD_JOURNAL_DETAILS_CLOSE) {
+                throw new Error("malformed Shepherd Journal details container: closing marker must be unindented");
+            }
+            if (--depth === 0)
+                return i;
+        }
+    }
+    throw new Error("unterminated or unsafe nested Shepherd Journal details container");
+}
+export function isJournalLikeSummary(line) {
+    return /^<summary>\s*Shepherd\s+Journal\b/i.test(line);
+}
+export function isReservedJournalMarker(line) {
+    return (isDetailsOpening(line) ||
+        line === SHEPHERD_JOURNAL_DETAILS_SUMMARY ||
+        line === SHEPHERD_JOURNAL_DETAILS_CLOSE);
+}
+function isDetailsOpening(line) {
+    return /^<details(?:\s+[^>]*)?>$/.test(line);
+}
+function advanceHtmlComment(active, line) {
+    return active ? !line.includes("-->") : line.includes("<!--") && !line.includes("-->");
+}
+export function skipMarkdownLine(state, line) {
+    if (state.comment) {
+        state.comment = advanceHtmlComment(true, line);
+        return true;
+    }
+    if (state.fence) {
+        state.fence = advanceFence(state.fence, line);
+        return true;
+    }
+    if (line.includes("<!--")) {
+        state.comment = advanceHtmlComment(false, line);
+        return true;
+    }
+    state.fence = advanceFence(null, line);
+    return state.fence !== null;
+}
+function advanceFence(activeFence, line) {
+    const match = line.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+    if (!activeFence) {
+        if (match?.[1][0] === "`" && match[2].includes("`"))
+            return null;
+        return match ? { marker: match[1][0], length: match[1].length } : null;
+    }
+    return match &&
+        match[1][0] === activeFence.marker &&
+        match[1].length >= activeFence.length &&
+        /^[ \t]*$/.test(match[2])
+        ? null
+        : activeFence;
+}

package/bin/commands/journal/transform.d.mts

@@ -1,22 +1,7 @@
+export { validateJournalItem } from "./journal-item.mts";
 export interface AppendResult {
     body: string;
     mutated: boolean;
     sectionExisted: boolean;
 }
-type ValidationOk = {
-    ok: true;
-    item: string;
-};
-type ValidationError = {
-    ok: false;
-    error: string;
-};
-export type ValidationResult = ValidationOk | ValidationError;
-/** Validates that the input is a properly formed markdown list item. */
-export declare function validateJournalItem(input: string): ValidationResult;
-/**
- * Appends a validated list item to the ## Shepherd Journal section of a PR body.
- * Creates the section at the end if absent. Skips if the exact item is already present (idempotent).
- */
 export declare function appendJournalItem(body: string, item: string): AppendResult;
-export {};

package/bin/commands/journal/transform.mjs

@@ -1,112 +1,135 @@
-import { SHEPHERD_JOURNAL_SECTION, SHEPHERD_JOURNAL_SECTION_PATTERN, } from "../shepherd-journal.mjs";
-/** Validates that the input is a properly formed markdown list item. */
-export function validateJournalItem(input) {
-    const lines = input.split("\n").map((l) => l.trimEnd());
-    const nonBlank = lines.filter((l) => l.trim() !== "");
-    if (nonBlank.length === 0) {
-        return { ok: false, error: 'journal item must not be empty; expected a "- <text>" list item' };
-    }
-    if (!/^- \S/.test(nonBlank[0])) {
-        return {
-            ok: false,
-            error: `journal item must start with "- <text>"; got: ${JSON.stringify(nonBlank[0].slice(0, 40))}`,
-        };
-    }
-    for (const line of nonBlank.slice(1)) {
-        if (line.startsWith("#")) {
-            return {
-                ok: false,
-                error: "journal item lines must not start with # (would break section structure)",
-            };
-        }
-    }
-    const trimmed = lines
-        .map((l) => l.trimEnd())
-        .join("\n")
-        .trim();
-    return { ok: true, item: trimmed };
-}
-/**
- * Appends a validated list item to the ## Shepherd Journal section of a PR body.
- * Creates the section at the end if absent. Skips if the exact item is already present (idempotent).
- */
+import { SHEPHERD_JOURNAL_DETAILS_OPEN, SHEPHERD_JOURNAL_DETAILS_CLOSE, SHEPHERD_JOURNAL_DETAILS_SUMMARY, SHEPHERD_JOURNAL_SECTION_PATTERN, } from "../shepherd-journal.mjs";
+import { findDetailsClose, isJournalLikeSummary, skipMarkdownLine, } from "./journal-markdown.mjs";
+export { validateJournalItem } from "./journal-item.mjs";
 export function appendJournalItem(body, item) {
-    const lines = body.split("\n");
-    const bounds = findSectionBounds(lines);
-    if (!bounds) {
-        return createSection(lines, item);
-    }
-    const { headingIdx, endIdx } = bounds;
-    const sectionLines = lines.slice(headingIdx + 1, endIdx);
-    if (itemAlreadyPresent(sectionLines, item)) {
-        return { body, mutated: false, sectionExisted: true };
+    const lines = body.replaceAll("\r\n", "\n").split("\n");
+    const canonical = findCanonicalJournal(lines);
+    const legacy = findLegacyJournal(lines);
+    if (canonical && legacy)
+        throw new Error("ambiguous Shepherd Journal: both canonical details and legacy ## section exist");
+    if (canonical)
+        return appendToCanonical(lines, canonical, item, body);
+    if (legacy)
+        return migrateLegacyJournal(lines, legacy, item);
+    return createCanonicalJournal(lines, item);
+}
+function findCanonicalJournal(lines) {
+    const journals = [];
+    const state = { fence: null, comment: false };
+    for (let i = 0; i < lines.length; i++) {
+        if (skipMarkdownLine(state, lines[i]) || !isJournalLikeSummary(lines[i].trimStart()))
+            continue;
+        if (lines[i] !== SHEPHERD_JOURNAL_DETAILS_SUMMARY) {
+            throw new Error("malformed Shepherd Journal details container: expected exact summary line");
+        }
+        if (i === 0 || lines[i - 1] !== SHEPHERD_JOURNAL_DETAILS_OPEN) {
+            throw new Error("malformed Shepherd Journal details container: summary must immediately follow <details>");
+        }
+        if (lines[i + 1] !== "") {
+            throw new Error("malformed Shepherd Journal details container: expected blank line after summary");
+        }
+        const closeIdx = findDetailsClose(lines, i + 1);
+        journals.push({ summaryIdx: i, closeIdx });
+        i = closeIdx;
     }
-    return appendToSection(lines, headingIdx, endIdx, sectionLines, item);
+    if (journals.length > 1)
+        throw new Error("duplicate Shepherd Journal details containers");
+    return journals[0] ?? null;
 }
-function findSectionBounds(lines) {
-    let inFence = false;
+function findLegacyJournal(lines) {
+    const state = { fence: null, comment: false };
     let headingIdx = -1;
+    let endIdx = null;
     for (let i = 0; i < lines.length; i++) {
-        const trimmed = lines[i].trim();
-        if (trimmed.startsWith("```") || trimmed.startsWith("~~~")) {
-            inFence = !inFence;
+        if (skipMarkdownLine(state, lines[i]))
             continue;
+        if (SHEPHERD_JOURNAL_SECTION_PATTERN.test(lines[i].trimEnd())) {
+            if (headingIdx !== -1)
+                throw new Error("duplicate legacy Shepherd Journal sections");
+            headingIdx = i;
+        }
+        else if (headingIdx !== -1 &&
+            endIdx === null &&
+            lines[i].trim() === SHEPHERD_JOURNAL_DETAILS_CLOSE) {
+            throw new Error("unsafe legacy Shepherd Journal section: standalone </details> line");
         }
-        if (!inFence) {
-            if (headingIdx === -1) {
-                if (SHEPHERD_JOURNAL_SECTION_PATTERN.test(lines[i].trimEnd())) {
-                    headingIdx = i;
-                }
-            }
-            else if (/^#{1,2} /.test(lines[i])) {
-                return { headingIdx, endIdx: i };
-            }
+        else if (headingIdx !== -1 && endIdx === null && /^#{1,2} /.test(lines[i])) {
+            endIdx = i;
         }
     }
-    if (headingIdx === -1)
-        return null;
-    return { headingIdx, endIdx: lines.length };
+    return headingIdx === -1 ? null : { headingIdx, endIdx: endIdx ?? lines.length };
 }
-function itemAlreadyPresent(sectionLines, item) {
-    const itemLines = item.split("\n").map((l) => l.trimEnd());
-    const normalizedSection = sectionLines.map((l) => l.trimEnd());
-    for (let i = 0; i <= normalizedSection.length - itemLines.length; i++) {
-        let match = true;
-        for (let j = 0; j < itemLines.length; j++) {
-            if (normalizedSection[i + j] !== itemLines[j]) {
-                match = false;
-                break;
-            }
-        }
-        if (match)
+function appendToCanonical(lines, bounds, item, originalBody) {
+    const journalLines = lines.slice(bounds.summaryIdx + 1, bounds.closeIdx);
+    if (itemAlreadyPresent(journalLines, item))
+        return { body: originalBody, mutated: false, sectionExisted: true };
+    const trimmed = trimTrailingBlankLines(journalLines);
+    const content = trimmed.length === 0 ? ["", ...item.split("\n")] : [...trimmed, ...item.split("\n")];
+    return {
+        body: [
+            ...lines.slice(0, bounds.summaryIdx + 1),
+            ...content,
+            ...lines.slice(bounds.closeIdx),
+        ].join("\n"),
+        mutated: true,
+        sectionExisted: true,
+    };
+}
+function migrateLegacyJournal(lines, bounds, item) {
+    const journalLines = trimBlankLines(lines.slice(bounds.headingIdx + 1, bounds.endIdx));
+    const content = itemAlreadyPresent(journalLines, item)
+        ? journalLines
+        : journalLines.length === 0
+            ? ["", ...item.split("\n")]
+            : [...journalLines, ...item.split("\n")];
+    const canonical = [
+        SHEPHERD_JOURNAL_DETAILS_OPEN,
+        SHEPHERD_JOURNAL_DETAILS_SUMMARY,
+        "",
+        ...content,
+        SHEPHERD_JOURNAL_DETAILS_CLOSE,
+    ];
+    const after = lines.slice(bounds.endIdx);
+    return {
+        body: [
+            ...lines.slice(0, bounds.headingIdx),
+            ...canonical,
+            ...(after.length > 0 ? ["", ...after] : []),
+        ].join("\n"),
+        mutated: true,
+        sectionExisted: true,
+    };
+}
+function createCanonicalJournal(lines, item) {
+    const existing = trimTrailingBlankLines(lines);
+    const canonical = [
+        SHEPHERD_JOURNAL_DETAILS_OPEN,
+        SHEPHERD_JOURNAL_DETAILS_SUMMARY,
+        "",
+        ...item.split("\n"),
+        SHEPHERD_JOURNAL_DETAILS_CLOSE,
+    ];
+    return {
+        body: [...existing, ...(existing.length > 0 ? [""] : []), ...canonical].join("\n"),
+        mutated: true,
+        sectionExisted: false,
+    };
+}
+function itemAlreadyPresent(journalLines, item) {
+    const itemLines = item.split("\n").map((line) => line.trimEnd());
+    for (let i = 0; i <= journalLines.length - itemLines.length; i++) {
+        if (itemLines.every((line, offset) => journalLines[i + offset].trimEnd() === line))
             return true;
     }
     return false;
 }
-function appendToSection(lines, headingIdx, endIdx, sectionLines, item) {
-    const before = lines.slice(0, headingIdx + 1);
-    const after = lines.slice(endIdx);
-    // Strip trailing blank lines from section body.
-    let sectionEnd = sectionLines.length;
-    while (sectionEnd > 0 && sectionLines[sectionEnd - 1].trim() === "") {
-        sectionEnd--;
-    }
-    const trimmedSection = sectionLines.slice(0, sectionEnd);
-    // Insert blank line after heading when section was empty, then the item.
-    const newSection = trimmedSection.length === 0
-        ? ["", ...item.split("\n")]
-        : [...trimmedSection, ...item.split("\n")];
-    // One blank line before the next section (or trailing newline at EOF).
-    const newBody = [...before, ...newSection, ...(after.length > 0 ? ["", ...after] : [])].join("\n");
-    return { body: newBody, mutated: true, sectionExisted: true };
-}
-function createSection(lines, item) {
-    // Strip trailing blank lines from the existing body.
+function trimTrailingBlankLines(lines) {
     let end = lines.length;
-    while (end > 0 && lines[end - 1].trim() === "") {
+    while (end > 0 && lines[end - 1].trim() === "")
         end--;
-    }
-    const trimmedLines = lines.slice(0, end);
-    const newBody = [...trimmedLines, "", SHEPHERD_JOURNAL_SECTION, "", ...item.split("\n")].join("\n");
-    return { body: newBody, mutated: true, sectionExisted: false };
+    return lines.slice(0, end);
+}
+function trimBlankLines(lines) {
+    const first = lines.findIndex((line) => line.trim() !== "");
+    return first === -1 ? [] : trimTrailingBlankLines(lines.slice(first));
 }

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

@@ -1,6 +1,9 @@
-export declare const SHEPHERD_JOURNAL_SECTION = "## Shepherd Journal";
+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_DETAILS_OPEN = "<details>";
+export declare const SHEPHERD_JOURNAL_DETAILS_SUMMARY = "<summary>Shepherd Journal</summary>";
+export declare const SHEPHERD_JOURNAL_DETAILS_CLOSE = "</details>";
+export declare const SHEPHERD_JOURNAL_APPEND_HINT = "If Shepherd Journal details already exist, append entries inside them instead of creating another container.";
 export declare const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review each body under `## Review summaries (first look)`. Eligible non-human IDs are already in `--minimize-comment-ids`. Record any warranted Shepherd Journal note before review mutations.";
 export declare function buildShepherdJournalInstruction(prNumber: number, itemReferenceGuidance: string): string[];
 export declare const SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS = "Link threads and comments from their headings. Cite reviews by ID.";

package/bin/commands/shepherd-journal.mjs

@@ -1,10 +1,13 @@
-export const SHEPHERD_JOURNAL_SECTION = "## Shepherd Journal";
+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_DETAILS_OPEN = "<details>";
+export const SHEPHERD_JOURNAL_DETAILS_SUMMARY = "<summary>Shepherd Journal</summary>";
+export const SHEPHERD_JOURNAL_DETAILS_CLOSE = "</details>";
+export const SHEPHERD_JOURNAL_APPEND_HINT = "If Shepherd Journal details already exist, append entries inside them instead of creating another container.";
 export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review each body under `## Review summaries (first look)`. Eligible non-human IDs are already in `--minimize-comment-ids`. Record any warranted Shepherd Journal note before review mutations.";
 export function buildShepherdJournalInstruction(prNumber, itemReferenceGuidance) {
     return [
-        `For any substantial decision or rejection, append \`- <decision>\` to \`${SHEPHERD_JOURNAL_SECTION}\` with \`pr-shepherd apply journal ${prNumber} '- <decision>'\`.`,
+        `For any substantial decision or rejection, append \`- <decision>\` to Shepherd Journal with \`pr-shepherd apply journal ${prNumber} '- <decision>'\`.`,
         itemReferenceGuidance,
     ];
 }

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.1",
+  "version": "0.38.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

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

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

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

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

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

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