pr-shepherd 0.38.1 → 0.40.0

package/.claude-plugin/plugin.json

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

package/README.md

@@ -67,10 +67,13 @@ Conversations Resolved: No [Not Required]
 
 1. Review each item under `## Review threads` and `## Failing checks` and decide whether it needs a code change.
 2. Apply every warranted review fix in each file referenced above.
-3. Read the included CI log excerpt; fetch the full log if needed, then rerun transient failures or fix real failures.
+3. Triage every failure under `## Failing checks`. See "CI failure triage" in the pr-shepherd skill for `gh run view` / `gh run rerun` rules.
 4. If you changed code, commit any remaining changes and push before review mutations. Otherwise, do not commit or push.
-5. Replace `$HEAD_SHA` and `$DISMISS_MESSAGE`, then run the `apply review:` command shown above.
-6. `[FIX_CODE]` is non-terminal. Continue with the next poll using the same CLI mode and flags, or call MCP `iterate` again.
+5. Before `apply review:`, remove any `--reply-thread-ids` entry whose latest visible comment is your own Shepherd reply. Do not reply to yourself.
+6. Replace `$HEAD_SHA` with the pushed commit SHA, or `$(git rev-parse HEAD)` if you did not push.
+7. Replace `$DISMISS_MESSAGE` with one sentence describing what changed.
+8. Run the `apply review:` command shown above. See "Review-mutation mechanics" in the pr-shepherd skill for dismiss-ID retention.
+9. `[FIX_CODE]` is non-terminal. After completing these steps, iterate again with the same options to continue.
 ```
 
 See [docs/actions.md](docs/actions.md) for the complete output contract. Iterate/poll PR outcomes use exit codes `0` and `10`–`14`; command and GitHub failures use `sysexits.h` codes — [docs/exit-codes.md](docs/exit-codes.md).

package/bin/cli/iterate-instructions.mjs

@@ -2,11 +2,11 @@ export function buildSimpleIterateInstructions(result) {
     switch (result.action) {
         case "wait":
             return [
-                "No action is needed this tick. Continue with the next poll using the same interface and mode: rerun the current `pr-shepherd` CLI invocation with its flags, or call MCP `iterate` again.",
+                "Non-terminal — no action needed this tick. Iterate again with the same options to continue.",
             ];
         case "mark_ready":
             return [
-                "The CLI marked the PR ready for review. Continue with the next poll using the same interface and mode: rerun the current `pr-shepherd` CLI invocation with its flags, or call MCP `iterate` again.",
+                "The CLI marked the PR ready for review. Iterate again with the same options to continue.",
             ];
         case "cancel":
             return ["Stop — the PR loop is complete. No further polling is needed."];

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

@@ -1,8 +1,11 @@
 /**
  * Build the `build-suggestion-patch` instruction step for agent consumers.
- * Currently emitted by iterate `fix_code` for suggestion review threads.
+ * Currently emitted by iterate `fix_code` for suggestion review threads. The CLI keeps
+ * only the trigger and the concrete command; refusal/drift handling is invariant across
+ * every invocation, so it lives in the pr-shepherd skill's "Suggestion patches" playbook
+ * instead of being re-emitted every tick (see CLAUDE.md "Keep skills and loop prompts
+ * minimal").
  * @param sectionName - The markdown section heading where suggestion threads appear,
  *   e.g. `"## Review threads"`.
- * @param includeDriftHint - Whether to add the trailing note about drift on failed apply.
  */
-export declare function buildCommitSuggestionInstruction(prNumber: number, sectionName: string, includeDriftHint: boolean): string[];
+export declare function buildCommitSuggestionInstruction(prNumber: number, sectionName: string): string;

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

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

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

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

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

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

package/bin/commands/iterate/render.mjs

@@ -1,6 +1,6 @@
 import { renderShellCommand } from "../../cli/runner.mjs";
 import { buildFailingCheckInstructions, buildCrStaleClause, buildBehindBaseHintInstruction, buildResolveCommandInstruction, buildFixCompletionInstruction, } from "./check-instructions.mjs";
-import { SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS, buildShepherdJournalInstruction, } from "../shepherd-journal.mjs";
+import { SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE, buildShepherdJournalInstruction, } from "../shepherd-journal.mjs";
 import { isFailingAgentCheck } from "../../checks/conclusions.mjs";
 import { buildCommitSuggestionInstruction } from "../commit-suggestion-instruction.mjs";
 /** Render a resolve command as a shell snippet. Appends `--require-sha "$HEAD_SHA"` when set. */
@@ -42,7 +42,7 @@ isBehind = false) {
     }
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
     if (firstLookTotal > 0) {
-        instructions.push("Review every item under `## First-look items` before acting.", "If a first-look thread also appears under `## Review threads to resolve`, its ID is already in `apply review:`. Do not add first-look-only IDs to mutation flags.");
+        instructions.push("Review every item under `## First-look items` before acting.");
     }
     if (firstLookSummaries.length > 0)
         instructions.push(SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE);
@@ -54,35 +54,30 @@ isBehind = false) {
         instructions.push("Read every item marked `[edited since first look]`, including edited summaries and edited first-look bullets, before deciding whether to resolve a matching thread.");
     }
     if (inProgressRunIds.length > 0) {
-        instructions.push("If you will push, first cancel every ID under `## In-progress runs` with `gh run cancel <id>`.", "Ignore cancellation errors for runs that already finished.", "If you will not push, leave the in-progress runs alone.");
+        instructions.push("If you will push, first cancel every ID under `## In-progress runs` with `gh run cancel <id>` (ignore errors for runs that already finished). If you will not push, leave them alone.");
     }
     if (cancelledCount > 0) {
         instructions.push("Do not cancel the IDs under `## Cancelled runs` again. The CLI already cancelled them.");
     }
     const hasSuggestions = threads.some((t) => t.suggestion);
     if (hasSuggestions)
-        instructions.push(...buildCommitSuggestionInstruction(prNumber, "## Review threads", false));
+        instructions.push(buildCommitSuggestionInstruction(prNumber, "## Review threads"));
     if (threads.length > 0 || actionableComments.length > 0) {
         // Actionable comments carry no file/line location (unlike threads), so "referenced above"
         // is only accurate when threads are present.
         const filesRef = threads.length > 0 ? "each file referenced above" : "the relevant files";
         instructions.push(`Apply every warranted review fix in ${filesRef}.`);
-        if (hasSuggestions) {
-            instructions.push("After source drift prevents a generated suggestion patch from applying, replace the heading's exact `path:startLine-endLine` range with the `Replaces lines …` block verbatim. An empty replacement deletes the range. One blank line replaces it with one blank line.", "When `build-suggestion-patch` refuses because the suggestion is unsafe (an unsafe anchored range or nested/unbalanced suggestion fences), do not apply the replacement block verbatim. Inspect the surrounding source and reviewer intent, then make the intended edit manually.");
-        }
     }
     if (resolutionOnlyThreads.length > 0) {
-        instructions.push("Review the threads under `## Review threads to resolve` before running mutations.", "Use the generated commands as shown. Human-authored IDs use `--reply-thread-ids`. Bot and non-human IDs use `--resolve-thread-ids`. Shepherd does not resolve human-authored threads.");
+        instructions.push('Review the threads under `## Review threads to resolve` before running mutations. Use the generated commands as shown — see "Review-mutation routing" in the pr-shepherd skill for which flag applies to which ID.');
     }
     instructions.push(...buildFailingCheckInstructions(failingChecks));
     if (hasAnnotations) {
-        instructions.push("Inspect every referenced range under `## Check annotations` and apply any warranted change.", "Do not add annotation IDs to resolve or minimize mutations.");
+        instructions.push("Inspect every referenced range under `## Check annotations` and apply any warranted change.");
     }
     if (changesRequestedReviews.length > 0) {
         const staleClause = buildCrStaleClause(changesRequestedReviews);
         instructions.push(`Read every body under \`## Changes-requested reviews\` and apply any warranted change.${staleClause}`);
-        if ((resolveCommand.dismissReviewIds?.length ?? 0) > 0)
-            instructions.push("Keep every existing `--dismiss-review-ids` ID in `apply review:`. Each is a bot or non-human review that must be dismissed. Omitting one leaves the PR in `CHANGES_REQUESTED`.");
     }
     instructions.push(...buildBehindBaseHintInstruction(baseBranch, behindBaseHint, isBehind));
     const hasReviewMutations = resolveCommand.hasMutations || resolveOnlyCommand?.hasMutations === true;
@@ -98,7 +93,7 @@ isBehind = false) {
         firstLookTotal > 0 ||
         firstLookSummaries.length > 0 ||
         editedTotal > 0) {
-        instructions.push(...buildShepherdJournalInstruction(prNumber, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS));
+        instructions.push(buildShepherdJournalInstruction(prNumber));
     }
     if (resolveOnlyCommand?.hasMutations)
         instructions.push("Run the `resolve-only:` command shown above.");

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

@@ -1,4 +1,53 @@
-import { isJournalLikeSummary, isReservedJournalMarker } from "./journal-markdown.mjs";
+import { inQuotedHtmlAttribute, rawHtmlEnd, rawHtmlStart } from "../../journal/markdown-html.mjs";
+import { stripMarkdownContainer } from "../../journal/markdown-container.mjs";
+import { scanMarkdownLines } from "../../journal/markdown-line.mjs";
+const RESERVED_CONTAINER_TAG = /(?:<details(?:\s+[^>]*)?\/?>|<\/details>)|<summary(?:\s+[^>]*)?>\s*Shepherd\s+Journal\b/i;
+function reservedContainerTag(lines) {
+    const syntax = scanMarkdownLines(lines);
+    for (const [index] of lines.entries()) {
+        const match = RESERVED_CONTAINER_TAG.exec(syntax[index].visiblePrefix);
+        if (match)
+            return match[0];
+    }
+    return reservedContainerTagInRawHtml(lines);
+}
+function reservedContainerTagInRawHtml(lines) {
+    let block = null;
+    for (const line of lines) {
+        if (block) {
+            const content = stripMarkdownContainer(line, block.container);
+            if (content === null) {
+                block = null;
+            }
+            else {
+                const marker = reservedContainerTagOutsideHtmlAttributes(content);
+                if (marker)
+                    return marker;
+                if (rawHtmlEnd(block, content) !== null)
+                    block = null;
+                continue;
+            }
+        }
+        const opening = rawHtmlStart(line);
+        if (!opening)
+            continue;
+        const content = stripMarkdownContainer(line, opening.container) ?? "";
+        const marker = reservedContainerTagOutsideHtmlAttributes(content);
+        if (marker)
+            return marker;
+        if (rawHtmlEnd(opening, content) === null)
+            block = opening;
+    }
+    return null;
+}
+function reservedContainerTagOutsideHtmlAttributes(line) {
+    const expression = new RegExp(RESERVED_CONTAINER_TAG.source, "gi");
+    for (const match of line.matchAll(expression)) {
+        if (!inQuotedHtmlAttribute(line, match.index))
+            return match[0];
+    }
+    return null;
+}
 export function validateJournalItem(input) {
     const lines = input.split("\n").map((line) => line.trimEnd());
     const nonBlank = lines.filter((line) => line.trim() !== "");
@@ -11,6 +60,13 @@ export function validateJournalItem(input) {
             error: `journal item must start with "- <text>"; got: ${JSON.stringify(nonBlank[0].slice(0, 40))}`,
         };
     }
+    const marker = reservedContainerTag(lines);
+    if (marker) {
+        return {
+            ok: false,
+            error: `journal item must not contain journal container marker ${JSON.stringify(marker)}`,
+        };
+    }
     for (const line of nonBlank.slice(1)) {
         if (line.startsWith("#")) {
             return {
@@ -18,12 +74,6 @@ export function validateJournalItem(input) {
                 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

@@ -8,6 +8,5 @@ export type MarkdownScanState = {
 };
 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

@@ -1,4 +1,4 @@
-import { SHEPHERD_JOURNAL_DETAILS_CLOSE, SHEPHERD_JOURNAL_DETAILS_SUMMARY, } from "../shepherd-journal.mjs";
+import { SHEPHERD_JOURNAL_DETAILS_CLOSE } from "../shepherd-journal.mjs";
 export function findDetailsClose(lines, startIdx) {
     let depth = 1;
     const state = { fence: null, comment: false };
@@ -23,11 +23,6 @@ export function findDetailsClose(lines, startIdx) {
 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);
 }

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

@@ -5,6 +5,10 @@ export declare const SHEPHERD_JOURNAL_DETAILS_SUMMARY = "<summary>Shepherd Journ
 export declare const SHEPHERD_JOURNAL_DETAILS_CLOSE = "</details>";
 export declare const SHEPHERD_JOURNAL_APPEND_HINT = "If Shepherd Journal details already exist, append entries inside them instead of creating another container.";
 export declare const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review each body under `## Review summaries (first look)`. Eligible non-human IDs are already in `--minimize-comment-ids`. Record any warranted Shepherd Journal note before review mutations.";
-export declare function buildShepherdJournalInstruction(prNumber: number, itemReferenceGuidance: string): string[];
-export declare const SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS = "Link threads and comments from their headings. Cite reviews by ID.";
-export declare const SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEMS = "Link threads and comments from their item bullets. Cite reviews by ID.";
+/**
+ * Build the Shepherd Journal instruction step. The reference-citation convention (link
+ * threads/comments from their headings, cite reviews by ID) is invariant across every
+ * invocation, so it lives in the pr-shepherd skill's "Shepherd Journal" playbook instead
+ * of being re-emitted every tick (see CLAUDE.md "Keep skills and loop prompts minimal").
+ */
+export declare function buildShepherdJournalInstruction(prNumber: number): string;

package/bin/commands/shepherd-journal.mjs

@@ -5,11 +5,12 @@ export const SHEPHERD_JOURNAL_DETAILS_SUMMARY = "<summary>Shepherd Journal</summ
 export const SHEPHERD_JOURNAL_DETAILS_CLOSE = "</details>";
 export const SHEPHERD_JOURNAL_APPEND_HINT = "If Shepherd Journal details already exist, append entries inside them instead of creating another container.";
 export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review each body under `## Review summaries (first look)`. Eligible non-human IDs are already in `--minimize-comment-ids`. Record any warranted Shepherd Journal note before review mutations.";
-export function buildShepherdJournalInstruction(prNumber, itemReferenceGuidance) {
-    return [
-        `For any substantial decision or rejection, append \`- <decision>\` to Shepherd Journal with \`pr-shepherd apply journal ${prNumber} '- <decision>'\`.`,
-        itemReferenceGuidance,
-    ];
+/**
+ * Build the Shepherd Journal instruction step. The reference-citation convention (link
+ * threads/comments from their headings, cite reviews by ID) is invariant across every
+ * invocation, so it lives in the pr-shepherd skill's "Shepherd Journal" playbook instead
+ * of being re-emitted every tick (see CLAUDE.md "Keep skills and loop prompts minimal").
+ */
+export function buildShepherdJournalInstruction(prNumber) {
+    return `For any substantial decision or rejection, append \`- <decision>\` to Shepherd Journal with \`pr-shepherd apply journal ${prNumber} '- <decision>'\`. See "Shepherd Journal" in the pr-shepherd skill for citation conventions.`;
 }
-export const SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS = "Link threads and comments from their headings. Cite reviews by ID.";
-export const SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEMS = "Link threads and comments from their item bullets. Cite reviews by ID.";

package/bin/journal/append.d.mts

@@ -0,0 +1,8 @@
+import { validateJournalItem } from "../commands/journal/journal-item.mts";
+export { validateJournalItem };
+export interface AppendResult {
+    body: string;
+    mutated: boolean;
+    sectionExisted: boolean;
+}
+export declare function appendJournalItem(body: string, item: string): AppendResult;

package/bin/journal/append.mjs

@@ -0,0 +1,96 @@
+import { validateJournalItem } from "../commands/journal/journal-item.mjs";
+import { fenceStart } from "./markdown-container.mjs";
+import { rawHtmlStart } from "./markdown-html.mjs";
+import { containsJournalEntry, scanShepherdJournal } from "./reconcile.mjs";
+import { isSafeMarkdownInsertionPoint } from "./markdown-line.mjs";
+const OPEN = "<details>";
+const SUMMARY = "<summary>Shepherd Journal</summary>";
+const CLOSE = "</details>";
+export { validateJournalItem };
+export function appendJournalItem(body, item) {
+    const validated = validateJournalItem(item);
+    if (!validated.ok)
+        throw new Error(validated.error);
+    if (validated.item
+        .split("\n")
+        .slice(1)
+        .some((line) => /^(?:[-+*]|\d{1,9}[.)])[ \t]+/.test(line)))
+        throw new Error("journal item must contain exactly one top-level list item");
+    item = validated.item;
+    if (item
+        .split("\n")
+        .some((line, index) => fenceStart(index === 0 ? line.slice(2) : line) ||
+        rawHtmlStart(index === 0 ? line.slice(2) : line)))
+        throw new Error("journal item must not start with a fenced or raw HTML block");
+    const newline = body.includes("\r\n") ? "\r\n" : "\n";
+    const lines = body.replaceAll("\r\n", "\n").split("\n");
+    const bounds = scanShepherdJournal(lines);
+    if (bounds === "error")
+        throw new Error("malformed, duplicate, or ambiguous Shepherd Journal container");
+    if (!bounds) {
+        if (!isSafeMarkdownInsertionPoint(lines))
+            throw new Error("cannot append Shepherd Journal inside an unterminated Markdown construct");
+        return create(lines, item, newline);
+    }
+    const content = lines.slice(bounds.contentStart, bounds.contentEnd);
+    if (bounds.format === "details" && containsJournalEntry(content, item))
+        return { body, mutated: false, sectionExisted: true };
+    const next = [...trimEnd(content), ...item.split("\n")];
+    if (bounds.format === "details") {
+        return {
+            body: [
+                ...lines.slice(0, bounds.contentStart),
+                ...next,
+                ...lines.slice(bounds.contentEnd),
+            ].join(newline),
+            mutated: true,
+            sectionExisted: true,
+        };
+    }
+    const legacyContent = trim(content);
+    const canonical = [
+        OPEN,
+        SUMMARY,
+        "",
+        ...legacyContent,
+        ...(containsJournalEntry(content, item) ? [] : item.split("\n")),
+        CLOSE,
+    ];
+    const suffix = lines.slice(bounds.end);
+    return {
+        body: [
+            ...lines.slice(0, bounds.start),
+            ...canonical,
+            ...(suffix[0]?.trim() ? [""] : []),
+            ...suffix,
+        ].join(newline),
+        mutated: true,
+        sectionExisted: true,
+    };
+}
+function create(lines, item, newline) {
+    const existing = trimEnd(lines);
+    return {
+        body: [
+            ...existing,
+            ...(existing.length ? [""] : []),
+            OPEN,
+            SUMMARY,
+            "",
+            ...item.split("\n"),
+            CLOSE,
+        ].join(newline),
+        mutated: true,
+        sectionExisted: false,
+    };
+}
+function trimEnd(lines) {
+    let end = lines.length;
+    while (end > 0 && lines[end - 1].trim() === "")
+        end--;
+    return lines.slice(0, end);
+}
+function trim(lines) {
+    const start = lines.findIndex((line) => line.trim() !== "");
+    return start === -1 ? [] : trimEnd(lines.slice(start));
+}

package/bin/journal/index.d.mts

@@ -0,0 +1,3 @@
+/** GitHub-free Shepherd Journal helpers for programmatic PR-body reconciliation. */
+export { appendJournalItem, validateJournalItem, type AppendResult } from "./append.mts";
+export { reconcileShepherdJournal, type ShepherdJournalReconcileResult } from "./reconcile.mts";

package/bin/journal/index.mjs

@@ -0,0 +1,3 @@
+/** GitHub-free Shepherd Journal helpers for programmatic PR-body reconciliation. */
+export { appendJournalItem, validateJournalItem } from "./append.mjs";
+export { reconcileShepherdJournal } from "./reconcile.mjs";

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

@@ -0,0 +1,9 @@
+export type BacktickRun = {
+    escaped: boolean;
+    index: number;
+    length: number;
+    quoted: boolean;
+};
+export declare function backtickRuns(line: string): BacktickRun[];
+export declare function nextBacktickRun(runs: BacktickRun[], offset: number, length?: number): BacktickRun | undefined;
+export declare function nextCodeOpener(runs: BacktickRun[], offset: number): BacktickRun | undefined;

package/bin/journal/markdown-backticks.mjs

@@ -0,0 +1,34 @@
+export function backtickRuns(line) {
+    const runs = [];
+    let inTag = false;
+    let quote = null;
+    for (let i = 0; i < line.length; i++) {
+        if (!inTag && line[i] === "<" && /^\/?[A-Za-z]/.test(line.slice(i + 1)))
+            inTag = true;
+        else if (inTag && quote) {
+            if (line[i] === quote)
+                quote = null;
+        }
+        else if (inTag && (line[i] === '"' || line[i] === "'"))
+            quote = line[i] === '"' ? '"' : "'";
+        else if (inTag && line[i] === ">")
+            inTag = false;
+        if (line[i] !== "`")
+            continue;
+        let slashes = 0;
+        while (line[i - slashes - 1] === "\\")
+            slashes++;
+        let end = i;
+        while (line[end] === "`")
+            end++;
+        runs.push({ escaped: slashes % 2 === 1, index: i, length: end - i, quoted: quote !== null });
+        i = end - 1;
+    }
+    return runs;
+}
+export function nextBacktickRun(runs, offset, length) {
+    return runs.find((run) => run.index >= offset && (length === undefined || run.length === length));
+}
+export function nextCodeOpener(runs, offset) {
+    return runs.find((run) => run.index >= offset && !run.quoted);
+}

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

@@ -0,0 +1,22 @@
+export type MarkdownContainer = Array<{
+    kind: "list";
+    width: number;
+} | {
+    kind: "quote";
+}>;
+export declare function markdownContainer(line: string): {
+    content: string;
+    indent: number;
+    tokens: MarkdownContainer;
+};
+export declare function resolveMarkdownContainer(line: string, active: MarkdownContainer): ReturnType<typeof markdownContainer>;
+export declare function fenceStart(line: string, parsed?: {
+    content: string;
+    indent: number;
+    tokens: MarkdownContainer;
+}): {
+    container: MarkdownContainer;
+    length: number;
+    marker: string;
+} | null;
+export declare function stripMarkdownContainer(line: string, tokens: MarkdownContainer): string | null;