pr-shepherd 0.59.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.59.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/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";
@@ -96,14 +96,19 @@ async function runIterateCore(opts) {
             reviewSummaryIds = [...reviewSummaryIds, ...unminimized];
     }
     // A first look at an already-minimized comment is only an acknowledgment.
-    // An edited body that no longer matches a noise rule may carry new feedback;
-    // it must restart the ready delay and void an existing READY receipt.
+    // 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 ||
-        report.comments.firstLook.some((comment) => comment.edited === true) ||
+        editedMinimizedFeedback ||
         (report.comments.minimizeIds?.length ?? 0) > 0 ||
         report.changesRequestedReviews.length > 0 ||
         hasCheckDrivenActionableWork(reportForWork.checks, report.mergeStatus.status) ||
@@ -124,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
@@ -386,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;
@@ -394,7 +399,6 @@ async function revalidateReadyReceipt(key, report, hasReadinessWork, context) {
         report.mergeStatus.state === "OPEN" &&
         !report.mergeStatus.isDraft &&
         Boolean(report.headSha && report.baseRefOid);
-    const editedMinimizedFeedback = report.comments.firstLook.some((comment) => comment.isMinimized && comment.edited === true);
     if (report.mergeStatus.state !== "OPEN" ||
         report.mergeStatus.isDraft ||
         !report.headSha ||

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.59.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.59.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.59.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.59.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.59.0", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.59.1", "pr-shepherd-mcp"]
   }
 }