pr-shepherd 0.58.0 → 0.59.1

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.58.0",
+  "version": "0.59.1",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -4,6 +4,43 @@ Drive a pull request to merge-ready with a coding agent. It works with Claude Co
 
 **Estimated per PR session: −42% cost and −19% turns vs. `gh`, −77% cost vs. the GitHub MCP server. While waiting on CI: ~60 GraphQL points an hour vs. ~360 for `gh pr checks --watch`.**
 
+## What it does
+
+- Gathers the PR's review items, CI failures, and merge requirements in one call.
+- Returns one action with numbered instructions and exact commands. `CANCEL` ends the loop and carries none.
+- Never mutates git. The agent edits, commits, pushes, and decides what each comment deserves.
+
+```text
+$ pr-shepherd 123
+
+# PR #123 [FIX_CODE]
+
+**status** `UNRESOLVED_COMMENTS` · **repo** `owner/repo`
+**summary** 3 passing
+
+## Review threads
+
+### `threadId=PRRT_kwDOSGizTs58XB1L` — `src/commands/iterate/index.mts:42` (@alice · MEMBER)
+
+> The variable name is misleading.
+
+## Failing checks
+
+- `24697658766` — `CI › lint / typecheck / test (22.x)` [conclusion: FAILURE]
+  > oxfmt
+
+## Instructions
+
+1. Fix each warranted item.
+2. Triage `## Failing checks`. Playbook: "CI failure triage".
+3. Commit and push any changes.
+4. Journal key decisions or rejections with URLs or IDs: `pr-shepherd apply journal 123 '- <decision>'`
+5. `$DISMISS_MESSAGE`: one sentence on what changed. Run even if no code changed: `pr-shepherd apply review 123 --reply-thread-ids PRRT_kwDOSGizTs58XB1L --message "$DISMISS_MESSAGE" --require-sha HEAD`
+6. Rerun Shepherd now.
+```
+
+More features are in [docs/features.md](docs/features.md).
+
 ## Outcomes
 
 | Outcome                                                                 | Headline                                                                                                                          | Evidence                                                                 |
@@ -17,23 +54,6 @@ Drive a pull request to merge-ready with a coding agent. It works with Claude Co
 
 **[jongleberry.com/pr-shepherd](https://jongleberry.com/pr-shepherd/)** covers the why and the design principles.
 
-## What it does
-
-- Gathers the PR's review items, CI failures, and merge requirements in one call.
-- Returns one action with numbered instructions and exact commands. `CANCEL` ends the loop and carries none.
-- Never mutates git. The agent edits, commits, pushes, and decides what each comment deserves.
-
-```mermaid
-flowchart LR
-  A[Agent] -->|iterate PR| S[pr-shepherd]
-  S -->|batched, conditional reads| G[(GitHub)]
-  G --> S
-  S -->|one action + numbered instructions| A
-  A -->|fix, push, run the printed commands| G
-```
-
-Without Shepherd, an agent fans out across `gh`, the GitHub MCP server, and GraphQL to rebuild PR state, then guesses the next step. Details for each outcome follow; more features are in [docs/features.md](docs/features.md).
-
 ## Outcome details
 
 ### Context and correctness
@@ -179,34 +199,7 @@ Requirements:
 pr-shepherd 42                       # shell: poll for work (270s cap; --until-terminal removes it)
 ```
 
-Leave out the PR number to use the current branch. Example `FIX_CODE` output:
-
-```text
-# PR #123 [FIX_CODE]
-
-**status** `UNRESOLVED_COMMENTS` · **repo** `owner/repo`
-**summary** 3 passing
-
-## Review threads
-
-### `threadId=PRRT_kwDOSGizTs58XB1L` — `src/commands/iterate/index.mts:42` (@alice · MEMBER)
-
-> The variable name is misleading.
-
-## Failing checks
-
-- `24697658766` — `CI › lint / typecheck / test (22.x)` [conclusion: FAILURE]
-  > oxfmt
-
-## Instructions
-
-1. Fix each warranted item.
-2. Triage `## Failing checks`. Playbook: "CI failure triage".
-3. Commit and push any changes.
-4. Journal key decisions or rejections with URLs or IDs: `pr-shepherd apply journal 123 '- <decision>'`
-5. `$DISMISS_MESSAGE`: one sentence on what changed. Run even if no code changed: `pr-shepherd apply review 123 --reply-thread-ids PRRT_kwDOSGizTs58XB1L --message "$DISMISS_MESSAGE" --require-sha HEAD`
-6. Rerun Shepherd now.
-```
+Leave out the PR number to use the current branch.
 
 ## Documentation
 

package/bin/classify/standard/coderabbit-notices.d.mts

@@ -1,8 +1,8 @@
 import type { ClassifyRule } from "../types.mts";
 /**
  * CodeRabbit progress, rate-limit, review-skipped and draft notices, plus its "Action not
- * completed" command replies. The summarize comment is later edited in place into the PR
- * walkthrough, so the rule only hides it from agent output and never minimizes it.
+ * completed" command replies. If the comment is later edited into a PR walkthrough, its new
+ * body no longer matches and Shepherd surfaces the edited minimized comment to the agent.
  */
 declare const rule: ClassifyRule;
 export default rule;

package/bin/classify/standard/coderabbit-notices.mjs

@@ -1,14 +1,54 @@
 import { isBotItem } from "./author.mjs";
 const NOTICE_ENVELOPE = /^<!-- This is an auto-generated comment: (rate limited|skip review|review in progress) by coderabbit.ai -->\n([\s\S]*?)\n<!-- end of auto-generated comment: \1 by coderabbit.ai -->$/;
 const COMMAND_REPLY = /^<!-- This is an auto-generated reply by CodeRabbit -->\n<!-- CodeRabbit review command invocation: v2:[a-f0-9]+ -->\n<details>\n<summary>⚠️ Action not completed<\/summary>\n\n(?:Review rate limited\.|Review skipped: \d+ files exceed the limit of \d+\.)\n\n(?:> Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits\. This command is applicable only when automatic reviews are paused\.|---\n\nYour included review limit is currently reached under our \[Fair Usage Limits Policy\]\(https:\/\/docs.coderabbit.ai\/management\/plans#fair-usage-limits-policy\)\. This review may still proceed through usage-based billing if eligible\. Your next included review will be available in \d+ minutes?\.)\n\n<\/details>$/;
+const FINISHING_TOUCH_BLOCK = `<!-- finishing_touch_checkbox_start -->
+
+<details>
+<summary><strong>✨ Finishing Touches</strong></summary>
+<dl>
+<dd>
+
+<details open>
+<summary><strong>📝 Generate docstrings</strong></summary>
+<dl>
+<dd>
+
+- [ ] <!-- {"checkboxId":"3e1879ae-f29b-4d0d-8e06-d12b7ba33d98"} --> Commit to this branch
+- [ ] <!-- {"checkboxId":"7962f53c-55bc-4827-bfbf-6a18da830691"} --> Create a new PR
+
+</dd>
+</dl>
+</details>
+<details open>
+<summary><strong>🧪 Generate unit tests (beta)</strong></summary>
+<dl>
+<dd>
+
+- [ ] <!-- {"checkboxId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8", "radioGroupId": "utg-output-choice-group-unknown_comment_id"} --> Commit to this branch
+- [ ] <!-- {"checkboxId": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "radioGroupId": "utg-output-choice-group-unknown_comment_id"} --> Create a new PR
+
+</dd>
+</dl>
+</details>
+
+</dd>
+</dl>
+</details>
+
+<!-- finishing_touch_checkbox_end -->`;
+const AUTOPILOT_BLOCK = /\n<!-- autopilot:start -->\n- \[ \] <!-- \{"checkboxId":"2708ad07-9f24-4260-9c11-7dc76a49f2e3"\} --> <strong title="Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts">Autofix<\/strong> · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts\n<!-- autopilot:end -->$/;
 /** Strips CodeRabbit's footer and header blocks so only the notice envelope remains. */
 function stripChrome(body) {
-    return body
+    const withoutFooter = body
         .trim()
         .replace(/\n<!-- tips_start -->[\s\S]*?<!-- tips_end -->$/, "")
         .trim()
-        .replace(/\n<!-- autopilot:start -->[\s\S]*?<!-- autopilot:end -->$/, "")
-        .trim()
+        .replace(AUTOPILOT_BLOCK, "")
+        .trim();
+    const withoutFinishingTouch = withoutFooter.endsWith(`\n\n${FINISHING_TOUCH_BLOCK}`)
+        ? withoutFooter.slice(0, -FINISHING_TOUCH_BLOCK.length).trim()
+        : withoutFooter;
+    return withoutFinishingTouch
         .replace(/^<!-- This is an auto-generated comment: summarize by coderabbit.ai -->\s*/, "")
         .replace(/^<!-- review_stack_entry_start -->[\s\S]*?<!-- review_stack_entry_end -->\s*/, "");
 }
@@ -23,8 +63,8 @@ function isQuotedNotice(quoted) {
 }
 /**
  * CodeRabbit progress, rate-limit, review-skipped and draft notices, plus its "Action not
- * completed" command replies. The summarize comment is later edited in place into the PR
- * walkthrough, so the rule only hides it from agent output and never minimizes it.
+ * completed" command replies. If the comment is later edited into a PR walkthrough, its new
+ * body no longer matches and Shepherd surfaces the edited minimized comment to the agent.
  */
 const rule = (item) => {
     if (!isBotItem(item, ["coderabbitai"], ["pr-comment"]))
@@ -33,6 +73,10 @@ const rule = (item) => {
     const quoted = body.match(NOTICE_ENVELOPE)?.[2]?.trim();
     if (!(quoted && isQuotedNotice(quoted)) && !COMMAND_REPLY.test(body))
         return null;
-    return { suppress: true, reason: "CodeRabbit progress, review-limit, or skipped-review notice" };
+    return {
+        autoResolve: true,
+        suppress: true,
+        reason: "CodeRabbit progress, review-limit, or skipped-review notice",
+    };
 };
 export default rule;

package/bin/classify/standard/codex-notices.mjs

@@ -6,7 +6,7 @@ const QUOTA_NOTICES = [
     /^Codex usage limits have been reached\. Please try again later\.$/,
 ];
 const ABOUT_BLOCK = /\n\n<details> <summary>ℹ️ About Codex (?:in GitHub|security reviews in GitHub)<\/summary>[\s\S]*?<\/details>$/;
-const ACTIVITY_SUMMARY = /^<!-- codex-pull-request-review-summary -->\n(?:<!-- codex-security-review:v1 \{[^\n]*\} -->\n)?\n?## Codex Review Summary\n\nThis comment shows the latest Codex review activity on this pull request\.\n\n\| Review \| Status \| Commit \| Review trigger \|\n\| --- \| --- \| --- \| --- \|\n(?:\|[^\n]+\|\n?)+$/;
+const ACTIVITY_SUMMARY = /^<!-- codex-pull-request-review-summary -->\n(?:<!-- codex-review-state:v1 \{[^\n]*\} -->\n)?(?:<!-- codex-security-review:v1 \{[^\n]*\} -->\n)?\n?## Codex Review Summary\n\nThis comment shows the latest Codex review activity on this pull request\.\n\n\| Review \| Status \| Commit \| Review trigger \|\n\| --- \| --- \| --- \| --- \|\n(?:\|[^\n]+\|\n?)+$/;
 const CLEAN_REVIEW = /^Codex Review: Didn't find any major issues\. (?:Bravo\.|Breezy!|Hooray!|:\+1:)\n\n\*\*Reviewed commit:\*\* `[a-f0-9]+`$/;
 const CLEAN_SECURITY = /^### 🛡️ Codex Security Review(?: · _Automatically triggered_)?\n\nSecurity review completed\. No security issues were found in this pull request\.\n\n\*\*Reviewed commit:\*\* `[a-f0-9]+`\n\n\[View security finding report\]\(https:\/\/chatgpt.com\/codex\/cloud\/tasks\/[a-zA-Z0-9_]+\)\n\n_Only the user who started this review can view the report in Codex\._$/;
 /**

package/bin/classify/standard/gemini-notices.d.mts

@@ -1,4 +1,4 @@
 import type { ClassifyRule } from "../types.mts";
-/** Gemini Code Assist daily-quota and review-limit notices on conversation comments. A heading means a real review. */
+/** Complete Gemini Code Assist quota and review-limit notices. */
 declare const rule: ClassifyRule;
 export default rule;

package/bin/classify/standard/gemini-notices.mjs

@@ -1,13 +1,14 @@
 import { isBotItem } from "./author.mjs";
-/** Gemini Code Assist daily-quota and review-limit notices on conversation comments. A heading means a real review. */
+const NOTICES = [
+    "You have reached your daily quota limit. Please wait up to 24 hours and I will start processing your requests again!",
+    "Review limit reached. I'll be able to review this pull request again tomorrow.",
+];
+/** Complete Gemini Code Assist quota and review-limit notices. */
 const rule = (item) => {
     if (!isBotItem(item, ["gemini-code-assist"], ["pr-comment"]))
         return null;
-    if (/^#{1,6}\s/m.test(item.body))
+    if (!NOTICES.includes(item.body.trim()))
         return null;
-    if (!/You have reached your daily quota limit|Review limit reached/i.test(item.body)) {
-        return null;
-    }
     return { autoResolve: true, suppress: true, reason: "Gemini quota or review-limit notice" };
 };
 export default rule;

package/bin/classify/standard/kilo-no-issues.d.mts

@@ -1,4 +1,4 @@
 import type { ClassifyRule } from "../types.mts";
-/** Kilo Code conversation comment whose status line reads "No Issues Found" and that carries no findings. */
+/** Complete Kilo Code no-issues status or report with a file list and no extra prose. */
 declare const rule: ClassifyRule;
 export default rule;

package/bin/classify/standard/kilo-no-issues.mjs

@@ -1,16 +1,20 @@
 import { isBotItem } from "./author.mjs";
-const STATUS_LINE = /^[^\S\n]*(?:\*\*)?Status:?(?:\*\*)?:?[^\S\n]*(?:\p{Extended_Pictographic}️?[^\S\n]*)?No Issues Found\b/imu;
-/** Headings a no-issues report carries; any other heading means real feedback. */
-const REPORT_HEADING = /^(?:Code Review Summary|Files Reviewed\b.*)$/i;
-/** Kilo Code conversation comment whose status line reads "No Issues Found" and that carries no findings. */
+const PLAIN_STATUS = /^Status: ✅ No Issues Found \| Recommendation: Merge$/;
+const REVIEW_REPORT = /^## Code Review Summary\n\n\*\*Status:\*\* No Issues Found \| \*\*Recommendation:\*\* Merge(?:\n\n### Files Reviewed \((\d+) files\)\n((?:- `[^`\n]+`(?:\n|$))+))?$/;
+/** Complete Kilo Code no-issues status or report with a file list and no extra prose. */
 const rule = (item) => {
     if (!isBotItem(item, ["kilo-code-bot"], ["pr-comment"]))
         return null;
-    if (!STATUS_LINE.test(item.body))
-        return null;
-    for (const [, heading] of item.body.matchAll(/^#{1,6}\s+(.*)$/gm)) {
-        if (!REPORT_HEADING.test(heading.trim()))
+    const body = item.body.trim();
+    if (!PLAIN_STATUS.test(body)) {
+        const report = body.match(REVIEW_REPORT);
+        if (!report)
             return null;
+        if (report[1] !== undefined) {
+            const listed = report[2].trimEnd().split("\n").length;
+            if (listed !== Number(report[1]))
+                return null;
+        }
     }
     return { autoResolve: true, suppress: true, reason: "Kilo Code no-issues report" };
 };

package/bin/classify/standard/sourcery-notices.d.mts

@@ -1,8 +1,4 @@
 import type { ClassifyRule } from "../types.mts";
-/**
- * Sourcery's private-repo upsell and weekly rate-limit notices on conversation comments. A real review opens
- * with a Markdown heading ("Reviewer's Guide", "Summary by Sourcery"); the notices carry none,
- * so a heading means genuine feedback that merely quotes the phrase.
- */
+/** Complete Sourcery private-repo upsell and weekly rate-limit notices. */
 declare const rule: ClassifyRule;
 export default rule;

package/bin/classify/standard/sourcery-notices.mjs

@@ -1,18 +1,15 @@
 import { isBotItem } from "./author.mjs";
-/**
- * Sourcery's private-repo upsell and weekly rate-limit notices on conversation comments. A real review opens
- * with a Markdown heading ("Reviewer's Guide", "Summary by Sourcery"); the notices carry none,
- * so a heading means genuine feedback that merely quotes the phrase.
- */
+const NO_ACCESS = /^Hi @[A-Za-z0-9-]+! 👋\n\nYour private repo does not have access to Sourcery\.\n\nPlease \[upgrade\]\(https:\/\/app\.sourcery\.ai\/login\?connection=github(?:&git_namespace_id=\d+)?&from_surface=github_bot&intent=private_repo_upsell\) to continue using Sourcery ✨$/;
+const RATE_LIMIT = /^Sorry @[A-Za-z0-9-]+, you have reached your weekly rate limit for Sourcery\. Please try again later\.$/;
+/** Complete Sourcery private-repo upsell and weekly rate-limit notices. */
 const rule = (item) => {
     if (!isBotItem(item, ["sourcery-ai"], ["pr-comment"]))
         return null;
-    if (/^#{1,6}\s/m.test(item.body))
-        return null;
-    if (/does not have access to Sourcery/i.test(item.body)) {
+    const body = item.body.trim();
+    if (NO_ACCESS.test(body)) {
         return { autoResolve: true, suppress: true, reason: "Sourcery no-access upsell" };
     }
-    if (/reached your weekly rate limit/i.test(item.body)) {
+    if (RATE_LIMIT.test(body)) {
         return { autoResolve: true, suppress: true, reason: "Sourcery rate-limit notice" };
     }
     return null;

package/bin/commands/iterate/index.mjs

@@ -9,7 +9,7 @@ import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { clearStallState } from "../../state/iterate-stall.mjs";
 import { handleFixCode } from "./fix-code.mjs";
-import { normalizeBotUsernames } from "../../comments/authors.mjs";
+import { isConfiguredBotAuthor, normalizeBotUsernames } from "../../comments/authors.mjs";
 import { autoMinimizeComments } from "../../comments/resolve.mjs";
 import { hasCheckDrivenActionableWork } from "../check-annotations.mjs";
 import { buildReadyMergeOutcome, handleActiveMergeState } from "./merge-state.mjs";
@@ -95,14 +95,20 @@ async function runIterateCore(opts) {
         if (unminimized.length > 0)
             reviewSummaryIds = [...reviewSummaryIds, ...unminimized];
     }
-    // Hidden PR comments surface once so the agent can acknowledge them, but
-    // they are not readiness evidence: bots keep editing hidden notices after a
-    // PR settles. They never restart the ready-delay or void a READY receipt.
+    // A first look at an already-minimized comment is only an acknowledgment.
+    // A non-bot edit that no longer matches a noise rule may carry new feedback;
+    // it must restart the ready delay and void an existing READY receipt. Bots
+    // regenerate minimized summaries on their own, so their edits surface for
+    // acknowledgment without restarting the countdown.
+    const editedMinimizedFeedback = report.comments.firstLook.some((comment) => comment.isMinimized === true &&
+        comment.edited === true &&
+        !isConfiguredBotAuthor(comment, botUsernames));
     const hasReadinessWork = report.threads.actionable.length > 0 ||
         report.threads.resolutionOnly.length > 0 ||
         report.threads.firstLook.length > 0 ||
         (report.threads.ruleAutoResolveIds?.length ?? 0) > 0 ||
         report.comments.actionable.length > 0 ||
+        editedMinimizedFeedback ||
         (report.comments.minimizeIds?.length ?? 0) > 0 ||
         report.changesRequestedReviews.length > 0 ||
         hasCheckDrivenActionableWork(reportForWork.checks, report.mergeStatus.status) ||
@@ -123,7 +129,7 @@ async function runIterateCore(opts) {
         !hasReadinessWork &&
         !activeMerge &&
         staleAncestry === null;
-    const receiptCurrent = await revalidateReadyReceipt(receiptKey, report, hasReadinessWork, checkContext);
+    const receiptCurrent = await revalidateReadyReceipt(receiptKey, report, hasReadinessWork, editedMinimizedFeedback, checkContext);
     const headSha = report.headSha ?? "unknown";
     // The elapsed marker survives a hidden-comment acknowledgement tick and is
     // consumed only when this tick cancels or merges. A receipt that is still
@@ -385,7 +391,7 @@ async function recordReadyReceipt(key, report, context) {
     }
 }
 /** Clear a stale READY receipt; return whether a current receipt remains. */
-async function revalidateReadyReceipt(key, report, hasReadinessWork, context) {
+async function revalidateReadyReceipt(key, report, hasReadinessWork, editedMinimizedFeedback, context) {
     const receipt = await readReadyReceipt(key);
     if (!receipt)
         return false;
@@ -398,6 +404,7 @@ async function revalidateReadyReceipt(key, report, hasReadinessWork, context) {
         !report.headSha ||
         !report.baseRefOid ||
         transportReadinessGaps(report, report.mergeStatus.mergeStateStatus).length > 0 ||
+        editedMinimizedFeedback ||
         (!retainQueuedReceipt && (report.status !== "READY" || hasReadinessWork))) {
         await clearReadyReceipt(key);
         return false;

package/bin/github/poll-summary-review.mjs

@@ -18,8 +18,7 @@ export async function summarizePollSummaryReview(raw, seen, viewerCanAdminister)
         raw.reviews.pageInfo.hasPreviousPage ||
         raw.reviewThreads.pageInfo.hasPreviousPage;
     for (const comment of raw.comments.nodes) {
-        if (!comment.isMinimized &&
-            !isSuppressed(rules, "pr-comment", comment) &&
+        if (!isSuppressed(rules, "pr-comment", comment, comment.id, undefined, comment.body, comment.isMinimized) &&
             classifyItem(comment.id, comment.body, seen) !== "unchanged")
             actionable += 1;
     }

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

@@ -0,0 +1,6 @@
+import type { scanMarkdownLines } from "./markdown-line.mts";
+export declare const LEGACY: RegExp;
+export declare const JOURNAL_SUMMARY: RegExp;
+export declare const CLOSE = "</details>";
+/** Return the line of the canonical `</details>` closing a journal container, or null. */
+export declare function closeJournalContainer(lines: string[], syntax: ReturnType<typeof scanMarkdownLines>, start: number): number | null;

package/bin/journal/journal-container.mjs

@@ -0,0 +1,33 @@
+import { detailsTags, rawDetailsTags, rawHtmlState } from "./markdown-details.mjs";
+export const LEGACY = /^ {0,3}##[ \t]+Shepherd[ \t]+Journal(?:[ \t]+#+)?[ \t]*$/;
+export const JOURNAL_SUMMARY = /^<summary>\s*Shepherd\s+Journal\b/i;
+export const CLOSE = "</details>";
+/** Return the line of the canonical `</details>` closing a journal container, or null. */
+export function closeJournalContainer(lines, syntax, start) {
+    let depth = 1;
+    let html = rawHtmlState();
+    for (let i = start; i < lines.length; i++) {
+        if (syntax[i].nested)
+            continue;
+        if (syntax[i].rawHtml) {
+            for (const tag of rawDetailsTags(lines[i], html))
+                if ((depth += tag) === 0)
+                    return null;
+            continue;
+        }
+        html = rawHtmlState();
+        if (syntax[i].ignored)
+            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;
+}

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

@@ -0,0 +1,15 @@
+export declare function detailsTags(line: string, closing: boolean): number;
+/** Tokenizer state carried across the lines of one raw HTML block. */
+export type RawHtmlState = {
+    mode: "comment" | "data" | "raw-text" | "tag";
+    quote: '"' | "'" | null;
+    rawTag: string | null;
+    terminator: RegExp;
+};
+export declare const rawHtmlState: () => RawHtmlState;
+/**
+ * Return `1` per `<details>` opener and `-1` per closer that the browser
+ * creates from a raw HTML block line. Tags inside comments, CDATA, raw-text
+ * elements, and (possibly multiline) attribute values do not count.
+ */
+export declare function rawDetailsTags(line: string, state: RawHtmlState): Array<1 | -1>;

package/bin/journal/markdown-details.mjs

@@ -0,0 +1,92 @@
+import { inQuotedHtmlAttribute } from "./markdown-html.mjs";
+import { structuralDetailsStart } from "./markdown-structure.mjs";
+export 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;
+}
+const RAW_TEXT = new Set([
+    "iframe",
+    "noembed",
+    "noframes",
+    "script",
+    "style",
+    "textarea",
+    "title",
+    "xmp",
+]);
+export const rawHtmlState = () => ({
+    mode: "data",
+    quote: null,
+    rawTag: null,
+    terminator: /--!?>/,
+});
+// Comments, CDATA sections, and bogus comments such as `<!x>`, `<?x>`, and `</ x>`.
+const COMMENTS = [
+    [/^<!--/, /--!?>/],
+    [/^<!\[CDATA\[/, /\]\]>/],
+    [/^<(?:[!?]|\/[^A-Za-z>])/, />/],
+];
+/**
+ * Return `1` per `<details>` opener and `-1` per closer that the browser
+ * creates from a raw HTML block line. Tags inside comments, CDATA, raw-text
+ * elements, and (possibly multiline) attribute values do not count.
+ */
+export function rawDetailsTags(line, state) {
+    const tags = [];
+    let i = 0;
+    while (i < line.length) {
+        if (state.mode === "comment") {
+            const end = state.terminator.exec(line.slice(i));
+            if (!end)
+                break;
+            state.mode = "data";
+            i += end.index + end[0].length;
+        }
+        else if (state.mode === "raw-text") {
+            const end = new RegExp(`</${state.rawTag}(?=[\\s/>]|$)`, "i").exec(line.slice(i));
+            if (!end)
+                break;
+            state.mode = "tag";
+            state.rawTag = null;
+            i += end.index + end[0].length;
+        }
+        else if (state.mode === "tag") {
+            const char = line[i++];
+            if (state.quote) {
+                if (char === state.quote)
+                    state.quote = null;
+            }
+            else if (char === '"' || char === "'")
+                state.quote = char;
+            else if (char === ">")
+                state.mode = state.rawTag ? "raw-text" : "data";
+        }
+        else {
+            const open = line.indexOf("<", i);
+            if (open === -1)
+                break;
+            const comment = COMMENTS.map(([start, end]) => [start.exec(line.slice(open)), end]).find(([start]) => start);
+            if (comment) {
+                state.mode = "comment";
+                state.terminator = comment[1];
+                i = open + comment[0][0].length;
+                continue;
+            }
+            // Tag names run until whitespace, `/`, or `>`, so `details:x` is not `details`.
+            const tag = /^<(\/?)([A-Za-z][^\s/>]*)/.exec(line.slice(open));
+            if (!tag) {
+                i = open + 1;
+                continue;
+            }
+            const name = tag[2].toLowerCase();
+            if (name === "details")
+                tags.push(tag[1] ? -1 : 1);
+            state.mode = "tag";
+            state.rawTag = !tag[1] && RAW_TEXT.has(name) ? name : null;
+            i = open + tag[0].length;
+        }
+    }
+    return tags;
+}

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

@@ -1,6 +1,8 @@
+/** `rawHtml` marks lines inside a blank-line-terminated raw HTML block, whose tags still render. */
 type MarkdownLine = {
     ignored: boolean;
     nested: boolean;
+    rawHtml: boolean;
     visiblePrefix: string;
 };
 /** Return whether a Markdown line starts a block that interrupts inline content. */

package/bin/journal/markdown-line.mjs

@@ -35,7 +35,7 @@ function scanMarkdown(lines) {
         const container = resolveMarkdownContainer(line, activeContainer);
         activeContainer = container.tokens;
         const nested = container.tokens.length > 0;
-        const push = (ignored, visiblePrefix) => result.push({ ignored, nested, visiblePrefix });
+        const push = (ignored, visiblePrefix, rawHtml = false) => result.push({ ignored, nested, rawHtml, visiblePrefix });
         if (indentedCodeContainer) {
             if (stripMarkdownContainer(line, indentedCodeContainer) !== null) {
                 push(true, "");
@@ -53,7 +53,7 @@ function scanMarkdown(lines) {
             else {
                 const end = rawHtmlEnd(html, content);
                 if (end === null) {
-                    push(true, "");
+                    push(true, "", html.kind === "blank-line");
                     continue;
                 }
                 html = null;
@@ -100,7 +100,7 @@ function scanMarkdown(lines) {
                 const end = rawHtmlEnd(openingHtml, content);
                 if (end === null) {
                     html = openingHtml;
-                    push(true, "");
+                    push(true, "", openingHtml.kind === "blank-line");
                     continue;
                 }
                 allowCodeOpeners = false;

package/bin/journal/reconcile.mjs

@@ -1,42 +1,16 @@
-import { inQuotedHtmlAttribute } from "./markdown-html.mjs";
+import { detailsTags, rawDetailsTags, rawHtmlState } from "./markdown-details.mjs";
+import { CLOSE, closeJournalContainer, JOURNAL_SUMMARY, LEGACY } from "./journal-container.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 html = rawHtmlState();
     let legacy = null;
     for (let i = 0; i < lines.length; i++) {
         if (!syntax[i].ignored &&
@@ -48,7 +22,16 @@ export function scanShepherdJournal(lines) {
             legacy.contentEnd = legacy.end = i;
             continue;
         }
-        if (syntax[i].ignored || syntax[i].nested)
+        if (syntax[i].nested)
+            continue;
+        if (syntax[i].rawHtml) {
+            // Raw-HTML details stay open past the block; stray closers are ignored, as in the browser.
+            for (const tag of rawDetailsTags(lines[i], html))
+                detailsDepth = Math.max(0, detailsDepth + tag);
+            continue;
+        }
+        html = rawHtmlState();
+        if (syntax[i].ignored)
             continue;
         const visible = syntax[i].visiblePrefix;
         detailsDepth += detailsTags(visible, false);
@@ -66,7 +49,7 @@ export function scanShepherdJournal(lines) {
                 lines[i - 1] !== OPEN ||
                 lines[i + 1] !== "")
                 return "error";
-            const end = close(lines, syntax, i + 2);
+            const end = closeJournalContainer(lines, syntax, i + 2);
             if (end === null)
                 return "error";
             detailsDepth--;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.58.0",
+  "version": "0.59.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

package/plugins/pr-shepherd/.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.58.0",
+  "version": "0.59.1",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

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

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

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

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