pr-shepherd 0.39.0 → 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.39.0",
+  "version": "0.40.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

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/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;

package/bin/journal/markdown-container.mjs

@@ -0,0 +1,110 @@
+function visualColumn(line, end) {
+    let column = 0;
+    for (let i = 0; i < end; i++)
+        column = line[i] === "\t" ? column + (4 - (column % 4)) : column + 1;
+    return column;
+}
+function quoteEnd(line, offset) {
+    let marker = offset;
+    while (marker < offset + 3 && line[marker] === " ")
+        marker++;
+    if (line[marker] !== ">")
+        return null;
+    marker++;
+    return line[marker] === " " || line[marker] === "\t" ? marker + 1 : marker;
+}
+function listEnd(line, offset) {
+    let marker = offset;
+    while (marker < offset + 3 && line[marker] === " ")
+        marker++;
+    const match = line.slice(marker).match(/^(?:[-+*]|\d{1,9}[.)])/)?.[0];
+    if (!match)
+        return null;
+    let end = marker + match.length;
+    const paddingStart = end;
+    const startColumn = visualColumn(line, offset);
+    let column = visualColumn(line, end);
+    let padding = 0;
+    while (line[end] === " " || line[end] === "\t") {
+        const nextColumn = line[end] === "\t" ? column + (4 - (column % 4)) : column + 1;
+        padding += nextColumn - column;
+        column = nextColumn;
+        end++;
+    }
+    if (padding === 0)
+        return null;
+    if (padding > 4) {
+        end = paddingStart + 1;
+        const actualWidth = visualColumn(line, end) - visualColumn(line, paddingStart);
+        column = visualColumn(line, paddingStart) + 1;
+        return { end, indent: actualWidth - 1, width: column - startColumn };
+    }
+    return { end, indent: 0, width: column - startColumn };
+}
+export function markdownContainer(line) {
+    const tokens = [];
+    let indent = 0;
+    let offset = 0;
+    while (true) {
+        const quote = quoteEnd(line, offset);
+        if (quote !== null) {
+            tokens.push({ kind: "quote" });
+            offset = quote;
+            continue;
+        }
+        const list = listEnd(line, offset);
+        if (!list)
+            break;
+        tokens.push({ kind: "list", width: list.width });
+        offset = list.end;
+        indent = list.indent;
+        if (indent)
+            break;
+    }
+    return { content: line.slice(offset), indent, tokens };
+}
+export function resolveMarkdownContainer(line, active) {
+    for (let depth = active.length; depth > 0; depth--) {
+        const retained = active.slice(0, depth);
+        const continuation = stripMarkdownContainer(line, retained);
+        if (continuation === null)
+            continue;
+        const nested = markdownContainer(continuation);
+        return {
+            content: nested.content,
+            indent: nested.indent,
+            tokens: [...retained, ...nested.tokens],
+        };
+    }
+    return markdownContainer(line);
+}
+export function fenceStart(line, parsed = markdownContainer(line)) {
+    const match = `${" ".repeat(parsed.indent)}${parsed.content}`.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+    return match && !(match[1][0] === "`" && match[2].includes("`"))
+        ? { container: parsed.tokens, length: match[1].length, marker: match[1][0] }
+        : null;
+}
+export function stripMarkdownContainer(line, tokens) {
+    let offset = 0;
+    for (const [index, token] of tokens.entries()) {
+        if (token.kind === "quote") {
+            const end = quoteEnd(line, offset);
+            if (end === null)
+                return null;
+            offset = end;
+            continue;
+        }
+        if (line.slice(offset).trim() === "" &&
+            tokens.slice(index).every((item) => item.kind === "list"))
+            return "";
+        const startColumn = visualColumn(line, offset);
+        let column = startColumn;
+        while (column - startColumn < token.width && (line[offset] === " " || line[offset] === "\t")) {
+            column = line[offset] === "\t" ? column + (4 - (column % 4)) : column + 1;
+            offset++;
+        }
+        if (column - startColumn < token.width)
+            return null;
+    }
+    return line.slice(offset);
+}

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

@@ -0,0 +1,20 @@
+import { type MarkdownContainer } from "./markdown-container.mts";
+export type RawHtmlBlock = {
+    container: MarkdownContainer;
+    kind: "closing-tag";
+    tag: string;
+} | {
+    container: MarkdownContainer;
+    kind: "blank-line";
+} | {
+    container: MarkdownContainer;
+    kind: "terminator";
+    terminator: string;
+};
+export declare function rawHtmlStart(line: string, parsed?: {
+    content: string;
+    indent: number;
+    tokens: MarkdownContainer;
+}): RawHtmlBlock | null;
+export declare function rawHtmlEnd(block: RawHtmlBlock, content: string): number | null;
+export declare function inQuotedHtmlAttribute(line: string, offset: number): boolean;

package/bin/journal/markdown-html.mjs

@@ -0,0 +1,119 @@
+import { markdownContainer } from "./markdown-container.mjs";
+const BLOCK_TAGS = new Set([
+    "address",
+    "article",
+    "aside",
+    "base",
+    "basefont",
+    "blockquote",
+    "body",
+    "caption",
+    "center",
+    "col",
+    "colgroup",
+    "dd",
+    "dialog",
+    "dir",
+    "div",
+    "dl",
+    "dt",
+    "fieldset",
+    "figcaption",
+    "figure",
+    "footer",
+    "form",
+    "frame",
+    "frameset",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "head",
+    "header",
+    "hr",
+    "html",
+    "iframe",
+    "legend",
+    "li",
+    "link",
+    "main",
+    "menu",
+    "menuitem",
+    "nav",
+    "noframes",
+    "ol",
+    "optgroup",
+    "option",
+    "p",
+    "param",
+    "plaintext",
+    "search",
+    "section",
+    "table",
+    "tbody",
+    "td",
+    "tfoot",
+    "th",
+    "thead",
+    "title",
+    "tr",
+    "track",
+    "ul",
+    "wbr",
+]);
+export function rawHtmlStart(line, parsed = markdownContainer(line)) {
+    const { content, indent, tokens } = parsed;
+    const visible = `${" ".repeat(indent)}${content}`;
+    const tag = visible.match(/^ {0,3}<(pre|script|style|textarea)(?:\s|>|$)/i)?.[1];
+    if (tag)
+        return { container: tokens, kind: "closing-tag", tag };
+    if (/^ {0,3}<\?(?:.|\n)*/.test(visible))
+        return { container: tokens, kind: "terminator", terminator: "?>" };
+    if (/^ {0,3}<!\[CDATA\[/.test(visible))
+        return { container: tokens, kind: "terminator", terminator: "]]>" };
+    if (/^ {0,3}<![A-Z]/.test(visible))
+        return { container: tokens, kind: "terminator", terminator: ">" };
+    const block = visible
+        .match(/^ {0,3}<\/?([A-Za-z][A-Za-z0-9-]*)(?:\s|\/?>|$)/)?.[1]
+        ?.toLowerCase();
+    if (!block || block === "details" || block === "summary")
+        return null;
+    if (!BLOCK_TAGS.has(block) &&
+        !/^ {0,3}<\/?[A-Za-z][A-Za-z0-9-]*(?:\s[^<>]*?|\/?)>$/.test(visible))
+        return null;
+    return { container: tokens, kind: "blank-line" };
+}
+export function rawHtmlEnd(block, content) {
+    if (block.kind === "blank-line")
+        return content.trim() === "" ? 0 : null;
+    if (block.kind === "terminator") {
+        const index = content.indexOf(block.terminator);
+        return index === -1 ? null : index + block.terminator.length;
+    }
+    const close = new RegExp(`</${block.tag}>`, "i").exec(content);
+    return close ? close.index + close[0].length : null;
+}
+export function inQuotedHtmlAttribute(line, offset) {
+    let inTag = false;
+    let quote = null;
+    for (let i = 0; i < offset; i++) {
+        const char = line[i];
+        if (!inTag) {
+            if (char === "<" && /^\/?[A-Za-z]/.test(line.slice(i + 1)))
+                inTag = true;
+            continue;
+        }
+        if (quote) {
+            if (char === quote)
+                quote = null;
+            continue;
+        }
+        if (char === '"' || char === "'")
+            quote = char;
+        else if (char === ">")
+            inTag = false;
+    }
+    return inTag && quote !== null;
+}

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

@@ -0,0 +1,8 @@
+type MarkdownLine = {
+    ignored: boolean;
+    nested: boolean;
+    visiblePrefix: string;
+};
+export declare const scanMarkdownLines: (lines: string[]) => MarkdownLine[];
+export declare const isSafeMarkdownInsertionPoint: (lines: string[]) => boolean;
+export {};

package/bin/journal/markdown-line.mjs

@@ -0,0 +1,166 @@
+import { fenceStart, resolveMarkdownContainer, stripMarkdownContainer, } from "./markdown-container.mjs";
+import { inQuotedHtmlAttribute, rawHtmlEnd, rawHtmlStart, } from "./markdown-html.mjs";
+import { backtickRuns, nextBacktickRun, nextCodeOpener } from "./markdown-backticks.mjs";
+import { isIndentedCode, structuralDetailsStart } from "./markdown-structure.mjs";
+function interruptsInlineContent(line) {
+    return (line.trim() === "" ||
+        /^ {0,3}(?:#{1,6}(?:[ \t]+|$)|>)/.test(line) ||
+        /^ {0,3}(?:[-+*]|\d{1,9}[.)])[ \t]+/.test(line) ||
+        /^ {0,3}(?:(?:\*[ \t]*){3,}|-+[ \t]*|(?:_[ \t]*){3,}|=+[ \t]*)$/.test(line) ||
+        fenceStart(line) !== null ||
+        rawHtmlStart(line) !== null ||
+        structuralDetailsStart(line) !== null);
+}
+function hasCloser(lines, lineIndex, offset, length) {
+    for (let i = lineIndex; i < lines.length; i++) {
+        if (i > lineIndex && interruptsInlineContent(lines[i]))
+            return false;
+        if (backtickRuns(lines[i]).some((run) => run.length === length && (i > lineIndex || run.index > offset)))
+            return true;
+    }
+    return false;
+}
+function scanMarkdown(lines) {
+    const result = [];
+    let codeSpan = null;
+    let comment = null;
+    let fence = null;
+    let html = null;
+    let activeContainer = [];
+    let indentedCodeContainer = null;
+    for (let lineIndex = 0; lineIndex < lines.length; lineIndex++) {
+        const line = lines[lineIndex];
+        const container = resolveMarkdownContainer(line, activeContainer);
+        activeContainer = container.tokens;
+        const nested = container.tokens.length > 0;
+        const push = (ignored, visiblePrefix) => result.push({ ignored, nested, visiblePrefix });
+        if (indentedCodeContainer) {
+            if (stripMarkdownContainer(line, indentedCodeContainer) !== null) {
+                push(true, "");
+                continue;
+            }
+            indentedCodeContainer = null;
+        }
+        let allowCodeOpeners = true;
+        let forceIgnored = false;
+        let scanOffset = 0;
+        if (html) {
+            const content = stripMarkdownContainer(line, html.container);
+            if (content === null)
+                html = null;
+            else {
+                const end = rawHtmlEnd(html, content);
+                if (end === null) {
+                    push(true, "");
+                    continue;
+                }
+                html = null;
+                allowCodeOpeners = false;
+                forceIgnored = true;
+                scanOffset = line.length - content.length + end;
+            }
+        }
+        if (!forceIgnored && fence) {
+            const content = stripMarkdownContainer(line, fence.container);
+            if (content === null)
+                fence = null;
+            else {
+                const match = content.match(/^ {0,3}(`{3,}|~{3,})(.*)$/);
+                if (match &&
+                    match[1][0] === fence.marker &&
+                    match[1].length >= fence.length &&
+                    /^[ \t]*$/.test(match[2]))
+                    fence = null;
+                push(true, "");
+                continue;
+            }
+        }
+        if (comment &&
+            (stripMarkdownContainer(line, comment.container) === null ||
+                (comment.inline && line.trim() === "")))
+            comment = null;
+        if (!forceIgnored && codeSpan === null && !comment) {
+            if (isIndentedCode(`${" ".repeat(container.indent)}${container.content}`)) {
+                if (container.tokens.length)
+                    indentedCodeContainer = container.tokens;
+                push(true, "");
+                continue;
+            }
+            const openingFence = fenceStart(line, container);
+            if (openingFence) {
+                fence = openingFence;
+                push(true, "");
+                continue;
+            }
+            const openingHtml = rawHtmlStart(line, container);
+            if (openingHtml) {
+                const content = stripMarkdownContainer(line, openingHtml.container) ?? "";
+                const end = rawHtmlEnd(openingHtml, content);
+                if (end === null) {
+                    html = openingHtml;
+                    push(true, "");
+                    continue;
+                }
+                allowCodeOpeners = false;
+                forceIgnored = true;
+                scanOffset = line.length - content.length + end;
+            }
+        }
+        const startsMasked = forceIgnored || codeSpan !== null || comment !== null;
+        const visible = line.split("");
+        const runs = backtickRuns(line);
+        const mask = (start, end) => visible.fill(" ", start, end);
+        let offset = scanOffset;
+        while (offset < line.length) {
+            if (comment) {
+                const close = /--!?>/.exec(line.slice(offset));
+                const end = close === null ? line.length : offset + close.index + close[0].length;
+                mask(offset, end);
+                if (close === null)
+                    break;
+                comment = null;
+                offset = end;
+                continue;
+            }
+            if (codeSpan !== null) {
+                const close = nextBacktickRun(runs, offset, codeSpan);
+                mask(offset, close ? close.index + close.length : line.length);
+                if (!close)
+                    break;
+                codeSpan = null;
+                offset = close.index + close.length;
+                continue;
+            }
+            const commentAt = line.indexOf("<!--", offset);
+            const nextRun = allowCodeOpeners ? nextCodeOpener(runs, offset) : undefined;
+            if (commentAt !== -1 && (!nextRun || commentAt < nextRun.index)) {
+                let slashes = 0;
+                while (line[commentAt - slashes - 1] === "\\")
+                    slashes++;
+                if (slashes % 2 === 1 || inQuotedHtmlAttribute(line, commentAt)) {
+                    offset = commentAt + 4;
+                    continue;
+                }
+                mask(commentAt, commentAt + 4);
+                comment = { container: activeContainer, inline: line.slice(0, commentAt).trim() !== "" };
+                offset = commentAt + 4;
+                continue;
+            }
+            if (!nextRun)
+                break;
+            if (!nextRun.escaped && hasCloser(lines, lineIndex, nextRun.index, nextRun.length)) {
+                codeSpan = nextRun.length;
+                mask(nextRun.index, nextRun.index + nextRun.length);
+            }
+            offset = nextRun.index + nextRun.length;
+        }
+        const visiblePrefix = visible.join("");
+        push(startsMasked || visiblePrefix === "", visiblePrefix);
+    }
+    return {
+        lines: result,
+        safeAtEof: comment === null && fence === null && (html === null || html.kind === "blank-line"),
+    };
+}
+export const scanMarkdownLines = (lines) => scanMarkdown(lines).lines;
+export const isSafeMarkdownInsertionPoint = (lines) => scanMarkdown(lines).safeAtEof;

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

@@ -0,0 +1,7 @@
+type MarkdownLine = {
+    ignored: boolean;
+    nested: boolean;
+    visiblePrefix: string;
+};
+export declare function setextParagraphStart(lines: string[], syntax: MarkdownLine[], underline: number): number | null;
+export {};

package/bin/journal/markdown-setext.mjs

@@ -0,0 +1,15 @@
+const NON_PARAGRAPH = /^ {0,3}(?:#{1,6}(?:[ \t]+|$)|>|(?:[-+*]|\d{1,9}[.)])[ \t]+)/;
+function isParagraphText(line, syntax) {
+    return (!syntax.ignored &&
+        !syntax.nested &&
+        line.trim() !== "" &&
+        !NON_PARAGRAPH.test(syntax.visiblePrefix));
+}
+export function setextParagraphStart(lines, syntax, underline) {
+    let start = underline - 1;
+    if (start < 0 || !isParagraphText(lines[start], syntax[start]))
+        return null;
+    while (start > 0 && isParagraphText(lines[start - 1], syntax[start - 1]))
+        start--;
+    return start;
+}

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

@@ -0,0 +1,2 @@
+export declare function isIndentedCode(line: string): boolean;
+export declare function structuralDetailsStart(line: string): number | null;

package/bin/journal/markdown-structure.mjs

@@ -0,0 +1,35 @@
+export function isIndentedCode(line) {
+    let columns = 0;
+    for (const char of line) {
+        if (char !== " " && char !== "\t")
+            break;
+        columns += char === "\t" ? 4 - (columns % 4) : 1;
+    }
+    return columns >= 4;
+}
+export function structuralDetailsStart(line) {
+    let index = 0;
+    while (line[index] === " " && index < 4)
+        index++;
+    if (index > 3 || line[index] === "\t")
+        return null;
+    if (/^<(?:details(?:\s+[^>]*)?\/?|\/details)>/i.test(line.slice(index)))
+        return index;
+    const marker = line.slice(index).match(/^(?:[-+*]|\d{1,9}[.)])/);
+    if (!marker)
+        return null;
+    index += marker[0].length;
+    let column = index;
+    let padding = 0;
+    while (line[index] === " " || line[index] === "\t") {
+        const nextColumn = line[index] === "\t" ? column + (4 - (column % 4)) : column + 1;
+        padding += nextColumn - column;
+        column = nextColumn;
+        index++;
+    }
+    return padding > 0 &&
+        padding <= 4 &&
+        /^<(?:details(?:\s+[^>]*)?\/?|\/details)>/i.test(line.slice(index))
+        ? index
+        : null;
+}

package/bin/journal/reconcile.d.mts

@@ -0,0 +1,17 @@
+export type ShepherdJournalReconcileResult = {
+    body: string;
+    ok: true;
+} | {
+    error: string;
+    ok: false;
+};
+export type ShepherdJournalBounds = {
+    contentEnd: number;
+    contentStart: number;
+    end: number;
+    format: "details" | "legacy";
+    start: number;
+};
+export declare function scanShepherdJournal(lines: string[]): ShepherdJournalBounds | null | "error";
+export declare function containsJournalEntry(lines: string[], item: string): boolean;
+export declare function reconcileShepherdJournal(suppliedBody: string, liveBody: string): ShepherdJournalReconcileResult;

package/bin/journal/reconcile.mjs

@@ -0,0 +1,184 @@
+import { inQuotedHtmlAttribute } from "./markdown-html.mjs";
+import { isSafeMarkdownInsertionPoint, scanMarkdownLines } from "./markdown-line.mjs";
+import { setextParagraphStart } from "./markdown-setext.mjs";
+import { structuralDetailsStart } from "./markdown-structure.mjs";
+const LEGACY = /^ {0,3}##[ \t]+Shepherd[ \t]+Journal(?:[ \t]+#+)?[ \t]*$/;
+const JOURNAL_SUMMARY = /^<summary>\s*Shepherd\s+Journal\b/i;
+const SETEXT = /^ {0,3}(?:=+|-+)[ \t]*$/;
+const CLOSE = "</details>";
+const OPEN = "<details>";
+const SUMMARY = "<summary>Shepherd Journal</summary>";
+const stripCr = (s) => s.replace(/\r$/, "");
+function detailsTags(line, closing) {
+    if (structuralDetailsStart(line) === null)
+        return 0;
+    const expression = closing ? /<\/details>/gi : /<details(?:\s+[^>]*)?\/?>/gi;
+    return [...line.matchAll(expression)].filter((match) => !inQuotedHtmlAttribute(line, match.index)).length;
+}
+function close(lines, syntax, start) {
+    let depth = 1;
+    for (let i = start; i < lines.length; i++) {
+        if (syntax[i].ignored || syntax[i].nested)
+            continue;
+        const visible = syntax[i].visiblePrefix;
+        if (JOURNAL_SUMMARY.test(visible.trimStart()) || LEGACY.test(visible))
+            return null;
+        depth += detailsTags(visible, false);
+        const closes = detailsTags(visible, true);
+        if (closes) {
+            depth -= closes;
+            if (depth <= 0)
+                return depth === 0 && lines[i] === CLOSE ? i : null;
+        }
+    }
+    return null;
+}
+export function scanShepherdJournal(lines) {
+    const syntax = scanMarkdownLines(lines);
+    const found = [];
+    let detailsDepth = 0;
+    let legacy = null;
+    for (let i = 0; i < lines.length; i++) {
+        if (!syntax[i].ignored &&
+            !syntax[i].nested &&
+            legacy?.end === lines.length &&
+            /^ {0,3}#{1,2}(?:[ \t]+|$)/.test(lines[i])) {
+            if (LEGACY.test(syntax[i].visiblePrefix))
+                return "error";
+            legacy.contentEnd = legacy.end = i;
+            continue;
+        }
+        if (syntax[i].ignored || syntax[i].nested)
+            continue;
+        const visible = syntax[i].visiblePrefix;
+        detailsDepth += detailsTags(visible, false);
+        const closes = detailsTags(visible, true);
+        if (closes) {
+            if (detailsDepth >= closes) {
+                detailsDepth -= closes;
+                continue;
+            }
+            return "error";
+        }
+        if (JOURNAL_SUMMARY.test(visible.trimStart())) {
+            if (lines[i] !== SUMMARY || lines[i - 1] !== OPEN || lines[i + 1] !== "")
+                return "error";
+            const end = close(lines, syntax, i + 2);
+            if (end === null)
+                return "error";
+            detailsDepth--;
+            found.push({
+                contentEnd: end,
+                contentStart: i + 2,
+                end: end + 1,
+                format: "details",
+                start: i - 1,
+            });
+            i = end;
+            continue;
+        }
+        if (LEGACY.test(visible)) {
+            if (legacy)
+                return "error";
+            legacy = {
+                contentEnd: lines.length,
+                contentStart: i + 1,
+                end: lines.length,
+                format: "legacy",
+                start: i,
+            };
+            found.push(legacy);
+            continue;
+        }
+        const start = SETEXT.test(visible) ? setextParagraphStart(lines, syntax, i) : null;
+        if (legacy && legacy.end === lines.length && start !== null && start >= legacy.contentStart) {
+            legacy.contentEnd = legacy.end = start;
+        }
+        if (legacy && legacy.end === lines.length && lines[i].trim() === CLOSE)
+            return "error";
+    }
+    return detailsDepth !== 0 || found.length > 1 ? "error" : (found[0] ?? null);
+}
+function trim(lines) {
+    let a = 0;
+    let b = lines.length;
+    while (a < b && lines[a].trim() === "")
+        a++;
+    while (b > a && lines[b - 1].trim() === "")
+        b--;
+    return lines.slice(a, b);
+}
+function entries(lines) {
+    const result = [];
+    const syntax = scanMarkdownLines(lines.map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line)));
+    let current = null;
+    for (const [index, line] of lines.entries()) {
+        if (syntax[index].visiblePrefix.startsWith("- ")) {
+            if (current)
+                result.push(trim(current));
+            current = [line];
+        }
+        else if (current)
+            current.push(line);
+    }
+    if (current)
+        result.push(trim(current));
+    return result;
+}
+function hasUnrecognizedLeadingContent(lines) {
+    const syntax = scanMarkdownLines(lines.map((line) => (line.endsWith("\r") ? line.slice(0, -1) : line)));
+    const firstEntry = syntax.findIndex((line) => line.visiblePrefix.startsWith("- "));
+    if (firstEntry === -1)
+        return lines.some((line) => line.trim() !== "");
+    return lines.slice(0, firstEntry).some((line) => line.trim() !== "");
+}
+function contains(a, b) {
+    return a.length === b.length && a.every((s, i) => stripCr(s) === stripCr(b[i]));
+}
+export function containsJournalEntry(lines, item) {
+    const target = item.split("\n");
+    return entries(lines).some((entry) => contains(target, entry));
+}
+function fail(reason) {
+    return {
+        error: `${reason}. Supply every live Shepherd Journal entry verbatim, or omit the journal from the supplied body to preserve it automatically.`,
+        ok: false,
+    };
+}
+export function reconcileShepherdJournal(suppliedBody, liveBody) {
+    const liveLines = liveBody.split("\n");
+    const live = scanShepherdJournal(liveBody.replaceAll("\r\n", "\n").split("\n"));
+    const suppliedLines = suppliedBody.split("\n");
+    const supplied = scanShepherdJournal(suppliedBody.replaceAll("\r\n", "\n").split("\n"));
+    if (supplied === "error" || live === "error")
+        return fail("malformed, duplicate, or ambiguous Shepherd Journal container");
+    if (!live)
+        return { body: suppliedBody, ok: true };
+    if (live.format === "details" && supplied?.format === "legacy")
+        return fail("canonical Shepherd Journal details container cannot be downgraded to legacy H2");
+    const liveContent = trim(liveLines.slice(live.contentStart, live.contentEnd));
+    if (!liveContent.length)
+        return { body: suppliedBody, ok: true };
+    if (!supplied) {
+        if (!isSafeMarkdownInsertionPoint(suppliedBody.replaceAll("\r\n", "\n").split("\n")))
+            return fail("supplied body ends inside a Markdown construct that would hide the preserved journal");
+        const journal = liveLines.slice(live.start, live.end).join("\n");
+        const preservedJournal = journal.endsWith("\r") ? `${journal}\n` : journal;
+        return {
+            body: `${suppliedBody}${suppliedBody === "" ? "" : suppliedBody.endsWith("\n") ? "\n" : "\n\n"}${preservedJournal}`,
+            ok: true,
+        };
+    }
+    const liveEntries = entries(liveLines.slice(live.contentStart, live.contentEnd));
+    const liveJournalLines = liveLines.slice(live.contentStart, live.contentEnd);
+    if (!liveEntries.length || hasUnrecognizedLeadingContent(liveJournalLines))
+        return fail("live Shepherd Journal content uses an unrecognized entry format");
+    const target = entries(suppliedLines.slice(supplied.contentStart, supplied.contentEnd));
+    for (const entry of liveEntries) {
+        const match = target.findIndex((candidate) => contains(entry, candidate));
+        if (match === -1)
+            return fail(`supplied Shepherd Journal would drop live entry ${JSON.stringify(entry[0])}`);
+        target.splice(match, 1);
+    }
+    return { body: suppliedBody, ok: true };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.39.0",
+  "version": "0.40.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",
@@ -53,6 +53,10 @@
     "./classify": {
       "types": "./src/classify/types.mts",
       "default": "./bin/classify/types.mjs"
+    },
+    "./journal": {
+      "types": "./bin/journal/index.d.mts",
+      "default": "./bin/journal/index.mjs"
     }
   },
   "scripts": {

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

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

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

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