pr-shepherd 0.37.2 → 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.2",
+  "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/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/package.json

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