pr-shepherd 0.25.1 → 0.25.3

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

package/bin/cli/fix-formatter.mjs

@@ -121,6 +121,8 @@ export function formatFixCodeResult(header, result, opts) {
     }
     sections.push("## Post-fix push");
     const postFixLines = [`- base: \`${result.baseBranch}\``];
+    if (result.fix.resolveOnlyCommand?.hasMutations)
+        postFixLines.push(`- resolve-only: \`${renderResolveCommand(result.fix.resolveOnlyCommand)}\``);
     if (result.fix.resolveCommand.hasMutations) {
         postFixLines.push(`- resolve: \`${renderResolveCommand(result.fix.resolveCommand)}\``);
     }

package/bin/cli/help-command-pages.mjs

@@ -10,14 +10,16 @@ Usage:
                             [--require-sha SHA] [--format text|json]
 
 Flags:
-  --resolve-thread-ids <ids>      Comma-separated review thread IDs to resolve.
+  --resolve-thread-ids <ids>      Comma-separated review thread IDs (PRRT_*) to resolve.
                                   Human-authored thread IDs are skipped; use --reply-thread-ids.
+                                  Note: comment IDs (PRRC_*) from gh api are not thread IDs and will fail.
   --reply-thread-ids <ids>        Comma-separated human review thread IDs to reply to.
   --minimize-comment-ids <ids>    Comma-separated issue/review comment IDs to minimize.
   --dismiss-review-ids <ids>      Comma-separated CHANGES_REQUESTED review IDs to dismiss.
   --message <text>                Reply/dismiss message. Required with --reply-thread-ids
                                   or --dismiss-review-ids.
   --require-sha <sha>             Wait until GitHub reports this PR head SHA before mutating.
+                                  Must be a full 40-character lowercase hex SHA. Use $(git rev-parse HEAD).
   --format text|json              Output format. Default: text.
   --help, -h                      Print this help and exit before GitHub I/O.
 

package/bin/cli/iterate-lean.mjs

@@ -92,6 +92,9 @@ export function projectIterateLean(result, opts) {
                         changesRequestedReviews: result.fix.changesRequestedReviews,
                     }),
                     resolveCommand: result.fix.resolveCommand,
+                    ...(result.fix.resolveOnlyCommand && {
+                        resolveOnlyCommand: result.fix.resolveOnlyCommand,
+                    }),
                     ...(result.fix.instructions.length > 0 && {
                         instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, readyDelaySuffix),
                     }),

package/bin/cli/resolve-validators.mjs

@@ -0,0 +1,24 @@
+export function rejectPrrcMinimizeIds(ids) {
+    const prrcIds = ids.filter((id) => id.startsWith("PRRC_"));
+    if (prrcIds.length > 0) {
+        process.stderr.write(`pr-shepherd: resolve: --minimize-comment-ids contains thread comment IDs (PRRC_*): ${prrcIds.join(", ")}. Thread comments cannot be minimized individually — resolve the parent thread using --resolve-thread-ids with the PRRT_* thread ID instead.\n`);
+        process.exitCode = 1;
+    }
+    return prrcIds;
+}
+export function warnPrrcThreadIds(ids) {
+    const prrcIds = ids.filter((id) => id.startsWith("PRRC_"));
+    if (prrcIds.length > 0) {
+        process.stderr.write(`pr-shepherd: resolve: warning: --resolve-thread-ids contains comment IDs (PRRC_*) instead of thread IDs (PRRT_*): ${prrcIds.join(", ")}. The resolveReviewThread mutation requires PRRT_* thread IDs. Run a GraphQL query for pullRequest.reviewThreads to get the correct IDs.\n`);
+    }
+    return prrcIds;
+}
+export function validateRequireSha(sha) {
+    if (sha === undefined)
+        return true;
+    if (/^[0-9a-f]{40}$/.test(sha))
+        return true;
+    process.stderr.write(`pr-shepherd: resolve: --require-sha must be a full 40-character lowercase hex SHA, got "${sha}". Short SHAs will never match GitHub's headRefOid. Use $(git rev-parse HEAD) to get the full SHA.\n`);
+    process.exitCode = 1;
+    return false;
+}

package/bin/cli-parser.mjs

@@ -30,6 +30,7 @@ import { USAGE, maybePrintHelp } from "./cli/help.mjs";
 import { formatMutateResult } from "./cli/formatters.mjs";
 import { handleClean, handleCommitSuggestion, handleIterate, handleMarkFilesAsViewed, } from "./cli/handlers.mjs";
 import { handlePoll } from "./cli/poll-handler.mjs";
+import { warnPrrcThreadIds, validateRequireSha, rejectPrrcMinimizeIds, } from "./cli/resolve-validators.mjs";
 import { setupLog } from "./log/setup.mjs";
 // ---------------------------------------------------------------------------
 // Entry
@@ -130,6 +131,11 @@ async function handleResolve(args) {
     const dismissReviewIds = parseList(getFlag(extra, "--dismiss-review-ids"));
     const dismissMessage = getFlag(extra, "--message") ?? undefined;
     const requireSha = getFlag(extra, "--require-sha") ?? undefined;
+    warnPrrcThreadIds(resolveThreadIds);
+    if (!validateRequireSha(requireSha))
+        return;
+    if (rejectPrrcMinimizeIds(minimizeCommentIds).length > 0)
+        return;
     if (hasFlag(extra, "--fetch")) {
         process.stderr.write("pr-shepherd: resolve: --fetch has been removed; run pr-shepherd iterate or poll to fetch the next action.\n");
         process.exitCode = 1;

package/bin/commands/iterate/classify.mjs

@@ -44,7 +44,6 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals,
     };
 }
 export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, _reviews, checks, prNumber, botUsernames = new Set()) {
-    const argv = buildPrShepherdCommand(["resolve", String(prNumber)]).argv;
     const allThreads = [...threads, ...resolutionOnlyThreads];
     const replyThreadIds = dedupeIds(allThreads
         .filter((t) => isHumanAuthor(t) && !isConfiguredBotAuthor(t, botUsernames))
@@ -52,6 +51,41 @@ export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentId
     const resolveThreadIds = dedupeIds(allThreads
         .filter((t) => !isHumanAuthor(t) || isConfiguredBotAuthor(t, botUsernames))
         .map((t) => t.id));
+    const hasReply = replyThreadIds.length > 0;
+    const hasResolveOrMinimize = resolveThreadIds.length > 0 || allCommentIds.length > 0;
+    if (hasReply && hasResolveOrMinimize) {
+        // Split: reply command needs SHA; resolve/minimize command does not.
+        const resolveArgv = buildPrShepherdCommand(["resolve", String(prNumber)]).argv;
+        resolveArgv.push("--reply-thread-ids", replyThreadIds.join(","));
+        resolveArgv.push("--message", "$DISMISS_MESSAGE");
+        // `requiresHeadSha` is only true when actionable thread fixes or failing
+        // checks are being addressed — mutations that can race with a moving HEAD.
+        const requiresHeadSha = threads.length > 0 || checks.length > 0;
+        const resolveCommand = {
+            argv: resolveArgv,
+            requiresHeadSha,
+            requiresDismissMessage: true,
+            replyThreadIds,
+            hasMutations: true,
+        };
+        const resolveOnlyArgv = buildPrShepherdCommand(["resolve", String(prNumber)]).argv;
+        if (resolveThreadIds.length > 0) {
+            resolveOnlyArgv.push("--resolve-thread-ids", resolveThreadIds.join(","));
+        }
+        if (allCommentIds.length > 0) {
+            resolveOnlyArgv.push("--minimize-comment-ids", allCommentIds.join(","));
+        }
+        const resolveOnlyCommand = {
+            argv: resolveOnlyArgv,
+            requiresHeadSha: false,
+            requiresDismissMessage: false,
+            ...(resolveThreadIds.length > 0 ? { resolveThreadIds } : undefined),
+            hasMutations: true,
+        };
+        return { resolveCommand, resolveOnlyCommand };
+    }
+    // Single command: either reply-only or resolve/minimize-only (no split needed).
+    const argv = buildPrShepherdCommand(["resolve", String(prNumber)]).argv;
     if (replyThreadIds.length > 0) {
         argv.push("--reply-thread-ids", replyThreadIds.join(","));
         argv.push("--message", "$DISMISS_MESSAGE");
@@ -62,16 +96,11 @@ export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentId
     if (allCommentIds.length > 0) {
         argv.push("--minimize-comment-ids", allCommentIds.join(","));
     }
-    // hasMutations = we appended at least one reply, resolve, or minimize mutation. Returned explicitly
-    // (rather than derived from argv.length) so callers don't couple to the
-    // base-argv shape.
-    const hasMutations = replyThreadIds.length > 0 || resolveThreadIds.length > 0 || allCommentIds.length > 0;
-    // `requiresHeadSha` is only added when this resolve command includes a
-    // mutation that can race with a moving HEAD: replying after actionable
-    // thread fixes or addressing failing checks.
-    const hasCodeMutations = hasMutations && (threads.length > 0 || checks.length > 0);
-    const requiresHeadSha = hasCodeMutations;
-    return {
+    const hasMutations = hasReply || hasResolveOrMinimize;
+    // SHA is only required when replying after actionable fixes or failing checks.
+    // Resolve/minimize-only mutations never need SHA.
+    const requiresHeadSha = hasReply && (threads.length > 0 || checks.length > 0);
+    const resolveCommand = {
         argv,
         requiresHeadSha,
         requiresDismissMessage: replyThreadIds.length > 0,
@@ -79,4 +108,5 @@ export function buildResolveCommand(threads, resolutionOnlyThreads, allCommentId
         ...(resolveThreadIds.length > 0 ? { resolveThreadIds } : undefined),
         hasMutations,
     };
+    return { resolveCommand };
 }

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

@@ -76,7 +76,7 @@ export async function handleFixCode(ctx) {
     const inProgressRunIds = pushLikely ? buildInProgressRunIds(report, cancelledSet) : [];
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
     const allCommentIds = [...commentMinimizeIds, ...reviewSummaryIds];
-    const resolveCommand = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber, botUsernames);
+    const { resolveCommand, resolveOnlyCommand } = buildResolveCommand(threads, resolutionOnlyThreads, allCommentIds, changesRequestedReviews, checks, prNumber, botUsernames);
     // Safety: if the base branch is unknown, escalate when a push is plausible — the agent
     // would need the correct base to rebase safely. This is a conservative guard, not a
     // prediction that the agent *will* push. Intentionally broader than `pushLikely` above:
@@ -106,7 +106,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, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads);
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prNumber, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand);
     const prospectiveResult = {
         ...base,
         baseBranch: baseLookup.branch,
@@ -122,6 +122,7 @@ export async function handleFixCode(ctx) {
             checks,
             changesRequestedReviews,
             resolveCommand,
+            ...(resolveOnlyCommand !== undefined ? { resolveOnlyCommand } : undefined),
             instructions,
             firstLookThreads,
             firstLookComments,

package/bin/commands/iterate/render.mjs

@@ -15,7 +15,7 @@ export function renderResolveCommand(rc) {
     }
     return renderShellCommand(parts);
 }
-export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = []) {
+export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prNumber, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand) {
     const instructions = [];
     const hasNonConflictHints = threads.length > 0 ||
         checks.length > 0 ||
@@ -55,9 +55,8 @@ export function buildFixInstructions(threads, actionableComments, checks, change
         instructions.push(`If you decide to push new commits: cancel each in-progress run listed under \`## In-progress runs\` before applying code fixes (e.g. \`gh run cancel <id>\`). Runs may complete between the tick and your action; treat cancellation errors on already-finished runs as non-fatal. Skip this step if you are only resolving threads without pushing — the existing runs remain relevant.`);
     }
     const hasSuggestions = threads.some((t) => t.suggestion);
-    if (hasSuggestions) {
+    if (hasSuggestions)
         instructions.push(buildCommitSuggestionInstruction(prNumber, "## Review threads", false));
-    }
     if (threads.length > 0 || actionableComments.length > 0) {
         const suggestionFallback = hasSuggestions
             ? ` When applying a \`[suggestion]\` thread manually (e.g. after a failed \`commit-suggestion\` run), replace the exact line range shown in the heading (\`path:startLine-endLine\`) with the replacement shown in its \`Replaces lines …\` block verbatim — an empty replacement deletes those lines, a single blank line replaces the range with one blank line.`
@@ -74,9 +73,10 @@ export function buildFixInstructions(threads, actionableComments, checks, change
     if (changesRequestedReviews.length > 0) {
         instructions.push(`For each bullet under \`## Changes-requested reviews\` above: read the review body and apply the requested changes.`);
     }
-    if (hasNonConflictHints) {
+    if (hasNonConflictHints)
         instructions.push(`If you applied code edits: commit them with a descriptive message, then rebase onto \`origin/${baseBranch}\` per your repository's conventions before pushing.`);
-    }
+    if (resolveOnlyCommand?.hasMutations)
+        instructions.push(`Run the \`resolve-only:\` command shown above — no substitutions needed.`);
     if (resolveCommand.hasMutations) {
         if ((resolveCommand.replyThreadIds?.length ?? 0) > 0) {
             instructions.push(`Before running the \`resolve:\` command, remove any thread from \`--reply-thread-ids\` if the latest visible comment in that thread is your own prior Shepherd reply. Do not reply to your own comments.`);
@@ -98,9 +98,8 @@ export function buildFixInstructions(threads, actionableComments, checks, change
     if (firstLookTotal > 0) {
         instructions.push(`Items in \`## First-look items\` are shown so you can acknowledge their current status before acting. If a first-look thread also appears under \`## Review threads to resolve\`, its ID is already included in the \`resolve:\` command; otherwise do not pass first-look-only IDs to mutation flags.`);
     }
-    if (firstLookSummaries.length > 0) {
+    if (firstLookSummaries.length > 0)
         instructions.push(SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE);
-    }
     const editedTotal = editedSummaries.length +
         actionableComments.filter((c) => c.edited).length +
         firstLookThreads.filter((t) => t.edited).length +

package/bin/commands/shepherd-journal.mjs

@@ -1,7 +1,7 @@
 export const SHEPHERD_JOURNAL_SECTION = "## Shepherd Journal";
 export const SHEPHERD_JOURNAL_SECTION_PATTERN = /^##\s+Shepherd\s+Journal$/;
 export const SHEPHERD_JOURNAL_APPEND_HINT = "If this section already exists, append your entries under it instead of creating a duplicate heading.";
-export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review the bodies shown under `## Review summaries (first look)` — you are seeing these for the first time. Eligible non-human IDs, when present, are already included in the resolve command's `--minimize-comment-ids`; if any warrants a Shepherd Journal note, append it before running resolve.";
+export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review the bodies shown under `## Review summaries (first look)` — you are seeing these for the first time. Eligible non-human IDs, when present, are already included in `--minimize-comment-ids` in the resolve or resolve-only command above; if any warrants a Shepherd Journal note, append it before running resolve.";
 export function buildShepherdJournalInstruction(prNumber, itemReferenceGuidance) {
     return [
         `For any large decisions or rejections you made this iteration, add or update a \`${SHEPHERD_JOURNAL_SECTION}\` section in the PR description (\`gh pr edit ${prNumber} --body …\`) summarizing each decision.`,

package/bin/comments/visible-comments.mjs

@@ -8,6 +8,7 @@ export function classifyVisibleComments(comments, seenMap, minimizeComments, bot
         if (shouldMinimizeAuthor(c.authorType, minimizeComments, c.author, botUsernames)) {
             actionable.push(c);
             minimizeIds.push(c.id);
+            toMarkSeen.push(c); // prevents re-surfacing as first-look after GitHub marks it minimized
             continue;
         }
         const cls = classifyItem(c.id, c.body, seenMap);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.25.1",
+  "version": "0.25.3",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",

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

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.25.1",
+  "version": "0.25.3",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",