pr-shepherd 0.10.0 → 0.10.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/bin/cli/fix-formatter.mjs

@@ -56,9 +56,18 @@ export function formatFixCodeResult(header, result) {
         sections.push("## Changes-requested reviews");
         sections.push(result.fix.changesRequestedReviews.map((r) => renderReviewBullet(r)).join("\n"));
     }
-    if (result.fix.reviewSummaryIds.length > 0) {
-        sections.push("## Review summaries (minimize only)");
-        sections.push(result.fix.reviewSummaryIds.map((id) => `- \`${id}\``).join("\n"));
+    if (result.fix.firstLookSummaries.length > 0) {
+        sections.push("## Review summaries (first look — to be minimized)");
+        for (const r of result.fix.firstLookSummaries) {
+            sections.push(`### \`reviewId=${r.id}\` (@${r.author})`);
+            sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body));
+        }
+    }
+    const firstLookSummaryIds = new Set(result.fix.firstLookSummaries.map((r) => r.id));
+    const seenSummaryIds = result.fix.reviewSummaryIds.filter((id) => !firstLookSummaryIds.has(id));
+    if (seenSummaryIds.length > 0) {
+        sections.push("## Review IDs to minimize queue");
+        sections.push(seenSummaryIds.map((id) => `- \`${id}\``).join("\n"));
     }
     if (result.fix.surfacedApprovals.length > 0) {
         sections.push("## Approvals (surfaced — not minimized)");

package/bin/cli/iterate-lean.mjs

@@ -52,6 +52,9 @@ export function projectIterateLean(result) {
                     ...(result.fix.reviewSummaryIds.length > 0 && {
                         reviewSummaryIds: result.fix.reviewSummaryIds,
                     }),
+                    ...(result.fix.firstLookSummaries.length > 0 && {
+                        firstLookSummaries: result.fix.firstLookSummaries,
+                    }),
                     ...(result.fix.surfacedApprovals.length > 0 && {
                         surfacedApprovals: result.fix.surfacedApprovals,
                     }),

package/bin/cli-parser.iterate-fixtures.mjs

@@ -30,6 +30,7 @@ export function makeIterateResult(action = "wait") {
                 threads: [],
                 actionableComments: [],
                 reviewSummaryIds: [],
+                firstLookSummaries: [],
                 surfacedApprovals: [],
                 checks: [],
                 changesRequestedReviews: [],

package/bin/commands/check.mjs

@@ -46,7 +46,6 @@ export async function runCheck(opts) {
             mergeStateStatus: restState.mergeStateStatus ?? batchData.mergeStateStatus,
         };
     }
-    // Classify checks.
     const classifiedChecks = classifyChecks(batchData.checks);
     const verdict = getCiVerdict(classifiedChecks);
     const passing = classifiedChecks.filter((c) => c.category === "passed");
@@ -58,7 +57,6 @@ export async function runCheck(opts) {
         ? await triageFailingChecks(failing, repo, config.checks.logTailLines, config.checks.logTailChars)
         : failing;
     const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
-    // Resolve threads and comments.
     const unresolvedThreads = batchData.reviewThreads.filter((t) => !t.isResolved && !t.isMinimized);
     const visibleComments = batchData.comments.filter((c) => !c.isMinimized);
     // Auto-resolve outdated threads.
@@ -96,10 +94,14 @@ export async function runCheck(opts) {
     const firstLookComments = minimizedCommentCandidates
         .filter((c) => !seenSet.has(c.id))
         .map((c) => ({ ...c, firstLookStatus: "minimized" }));
+    // Split review summaries into first-look (unseen — surface body) vs seen (minimize silently).
+    const firstLookSummaries = batchData.reviewSummaries.filter((r) => !seenSet.has(r.id));
+    const seenSummaries = batchData.reviewSummaries.filter((r) => seenSet.has(r.id));
     // Mark first-look items as seen (best-effort — markSeen never throws).
     await Promise.allSettled([
         ...firstLookThreads.map((t) => markSeen(stateKey, t.id)),
         ...firstLookComments.map((c) => markSeen(stateKey, c.id)),
+        ...firstLookSummaries.map((r) => markSeen(stateKey, r.id)),
     ]);
     // Actionable: all active threads and all visible comments (no classification — LLM handles triage).
     const actionableThreads = activeThreads;
@@ -140,7 +142,8 @@ export async function runCheck(opts) {
             firstLook: firstLookComments,
         },
         changesRequestedReviews: batchData.changesRequestedReviews,
-        reviewSummaries: batchData.reviewSummaries,
+        reviewSummaries: seenSummaries,
+        firstLookSummaries,
         approvedReviews: batchData.approvedReviews,
     };
 }

package/bin/commands/iterate/classify.mjs

@@ -1,11 +1,13 @@
 export function classifyReviewSummaries(summaries, approvals, minimizeApprovals) {
-    const minimizeIds = summaries.map((r) => r.id);
+    // Both first-look and seen summaries go into the minimize mutation; first-look bodies are
+    // rendered in the output so the agent sees them before the minimize happens.
+    const minimizeIds = [...summaries.firstLook, ...summaries.seen].map((r) => r.id);
     if (minimizeApprovals) {
         for (const r of approvals)
             minimizeIds.push(r.id);
-        return { minimizeIds, surfacedApprovals: [] };
+        return { minimizeIds, firstLookSummaries: summaries.firstLook, surfacedApprovals: [] };
     }
-    return { minimizeIds, surfacedApprovals: approvals };
+    return { minimizeIds, firstLookSummaries: summaries.firstLook, surfacedApprovals: approvals };
 }
 export function buildResolveCommand(threads, allCommentIds, reviews, checks, prNumber) {
     const argv = ["npx", "pr-shepherd", "resolve", String(prNumber)];

package/bin/commands/iterate/fix-code.mjs

@@ -6,7 +6,7 @@ import { buildFixInstructions } from "./render.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { tryCancelRun } from "./helpers.mjs";
 export async function handleFixCode(ctx) {
-    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, surfacedApprovals, } = ctx;
+    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, surfacedApprovals, } = ctx;
     const failingChecks = report.checks.failing;
     const stored = await readFixAttempts({ owner: repoOwner, repo: repoName, pr: prNumber });
     const isNewSha = stored?.headSha !== headSha;
@@ -73,7 +73,7 @@ export async function handleFixCode(ctx) {
     }
     const firstLookThreads = report.threads.firstLook;
     const firstLookComments = report.comments.firstLook;
-    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments);
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries);
     return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, {
         ...base,
         baseBranch: baseLookup.branch,
@@ -83,6 +83,7 @@ export async function handleFixCode(ctx) {
             threads,
             actionableComments,
             reviewSummaryIds,
+            firstLookSummaries,
             surfacedApprovals,
             checks,
             changesRequestedReviews,

package/bin/commands/iterate/index.mjs

@@ -91,7 +91,7 @@ export async function runIterate(opts) {
     }
     const headSha = (await getCurrentHeadSha()) ?? "unknown";
     const stallKey = { owner: repoOwner, repo: repoName, pr: prNumber };
-    const { minimizeIds: reviewSummaryIds, surfacedApprovals } = classifyReviewSummaries(report.reviewSummaries, report.approvedReviews, config.iterate.minimizeApprovals);
+    const { minimizeIds: reviewSummaryIds, firstLookSummaries, surfacedApprovals, } = classifyReviewSummaries({ firstLook: report.firstLookSummaries, seen: report.reviewSummaries }, report.approvedReviews, config.iterate.minimizeApprovals);
     const hasActionableWork = report.threads.actionable.length > 0 ||
         report.comments.actionable.length > 0 ||
         report.changesRequestedReviews.length > 0 ||
@@ -110,6 +110,7 @@ export async function runIterate(opts) {
             repoOwner,
             repoName,
             reviewSummaryIds,
+            firstLookSummaries,
             surfacedApprovals,
         });
     }

package/bin/commands/iterate/render.mjs

@@ -1,22 +1,23 @@
 /**
- * Render a ResolveCommand as a single-line command string for the monitor loop
- * to print or execute. This is NOT a general-purpose POSIX escaper — it wraps
- * the two known placeholders ($DISMISS_MESSAGE, $HEAD_SHA) and any whitespace-
- * bearing arg in double quotes so multi-word values don't split across flags.
+ * Render a resolve command as a shell snippet for the narrow placeholder-based
+ * invocation used by iterate.
  *
- * Contract for callers substituting placeholders: replace the entire quoted
- * token (including the surrounding `"`) with a properly shell-quoted literal.
- * Do not splice raw text inside the existing quotes — the output would then
- * re-expand `$…` / `$(…)` / embedded `"` and break.
+ * This is not a general-purpose shell escaper. It only wraps
+ * `$DISMISS_MESSAGE` and whitespace-bearing `rc.argv` entries in double quotes
+ * so the surrounding command template can later substitute placeholder values.
+ *
+ * Callers must preserve that contract:
+ * - placeholder substitution must replace the entire quoted token (for example,
+ *   replace `"$DISMISS_MESSAGE"` as a whole, not text inside the quotes);
+ * - `rc.argv` must not contain `"`, `$`, `` ` ``, or `\`, because this helper
+ *   does not escape them and will throw if they are present;
+ * - `$HEAD_SHA` must not appear in `rc.argv`; when `requiresHeadSha` is set it
+ *   is appended separately below as the already-quoted token `"$HEAD_SHA"`.
  */
 export function renderResolveCommand(rc) {
-    // `$HEAD_SHA` is never in `rc.argv` — it is appended pre-quoted below when
-    // `requiresHeadSha`. Only `$DISMISS_MESSAGE` (or whitespace-bearing values)
-    // need quoting here.
     const needsQuoting = (arg) => {
         if (arg === "$DISMISS_MESSAGE")
             return true;
-        // Assert no characters that would break the naive escaper are present in arg
         if (/["$`\\]/.test(arg)) {
             throw new Error(`Unexpected character in argv arg that needsQuoting can't handle: ${JSON.stringify(arg)}`);
         }
@@ -28,7 +29,7 @@ export function renderResolveCommand(rc) {
     }
     return parts.join(" ");
 }
-export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = []) {
+export function buildFixInstructions(threads, actionableComments, checks, reviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = []) {
     const instructions = [];
     const hasSuggestions = threads.some((t) => t.suggestion);
     if (hasSuggestions) {
@@ -72,8 +73,13 @@ export function buildFixInstructions(threads, actionableComments, checks, review
             instructions.push(`Rebase and push: \`git fetch origin && git rebase origin/${baseBranch} && git push --force-with-lease\`${captureHint}`);
         }
     }
-    // Only tell the agent to run `resolve:` if the command actually mutates
-    // GitHub state. A CONFLICTS-only flow has nothing to mutate on GitHub.
+    const firstLookTotal = firstLookThreads.length + firstLookComments.length;
+    if (firstLookTotal > 0) {
+        instructions.push(`Items in \`## First-look items\` are for acknowledgement only — do not pass their IDs to \`--resolve-thread-ids\`, \`--minimize-comment-ids\`, or \`--dismiss-review-ids\`. Acknowledge each one with a one-line classification (e.g. "outdated — addressed by commit abc1234", "resolved — already fixed", "minimized — noise").`);
+    }
+    if (firstLookSummaries.length > 0) {
+        instructions.push(`Review the bodies shown under \`## Review summaries (first look — to be minimized)\` — you are seeing these for the first time. Their IDs are already included in the \`resolve:\` command's \`--minimize-comment-ids\`; if any warrants a \`## Shepherd Journal\` entry, record it before running resolve.`);
+    }
     if (resolveCommand.hasMutations) {
         const substituteParts = [];
         if (resolveCommand.requiresHeadSha) {
@@ -88,10 +94,6 @@ export function buildFixInstructions(threads, actionableComments, checks, review
     if (needsPush && cancelledCount > 0) {
         instructions.push(`Do not re-run \`gh run cancel\` on the IDs listed under \`## Cancelled runs\` — the CLI cancelled those runs before your push, and your push has already triggered new runs with different IDs.`);
     }
-    const firstLookTotal = firstLookThreads.length + firstLookComments.length;
-    if (firstLookTotal > 0) {
-        instructions.push(`Items in \`## First-look items\` are for acknowledgement only — do not pass their IDs to \`--resolve-thread-ids\`, \`--minimize-comment-ids\`, or \`--dismiss-review-ids\`. Acknowledge each one with a one-line classification (e.g. "outdated — addressed by commit abc1234", "resolved — already fixed", "minimized — noise").`);
-    }
     if (resolveCommand.hasMutations) {
         instructions.push(`For any large decisions or rejections you made this iteration, add or update a \`## Shepherd Journal\` section in the PR description (\`gh pr edit ${prNumber} --body …\`) summarizing each decision. For threads and comments, use the markdown link shown in its heading above; for reviews, reference the review ID.`);
     }

package/bin/reporters/text.mjs

@@ -98,7 +98,8 @@ export function formatText(report) {
         commentsSection = `## PR Comments\n\n${lines.join("\n")}`;
     }
     const changesRequestedSection = reviewListSection("CHANGES_REQUESTED Reviews", report.changesRequestedReviews);
-    const reviewSummariesSection = reviewListSection("Review Summaries", report.reviewSummaries);
+    const allSummaries = [...report.firstLookSummaries, ...report.reviewSummaries];
+    const reviewSummariesSection = reviewListSection("Review Summaries", allSummaries);
     const approvedReviewsSection = reviewListSection("Approved Reviews", report.approvedReviews);
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
     let firstLookSection = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.10.0",
+  "version": "0.10.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -24,15 +24,16 @@
   },
   "devDependencies": {
     "@types/node": "^25.6.0",
+    "@vitest/coverage-v8": "^4.1.4",
+    "husky": "^9.1.7",
     "oxfmt": "^0.46.0",
     "oxlint": "^1.60.0",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.4",
-    "@vitest/coverage-v8": "^4.1.4"
+    "vitest": "^4.1.4"
   },
   "scripts": {
     "build": "node scripts/build.mjs",
-    "prepare": "node scripts/install-hooks.mjs && node scripts/install-plugin-symlink.mjs && npm run build",
+    "prepare": "node scripts/install-husky.mjs && node scripts/install-plugin-symlink.mjs && npm run build",
     "prepublishOnly": "npm run typecheck && npm test && npm run build",
     "typecheck": "tsc --noEmit",
     "lint": "oxlint src/ plugin/skills/",