pr-shepherd 0.24.0 → 0.25.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.24.0",
+  "version": "0.25.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -97,10 +97,11 @@ pr-shepherd poll 42                    # explicit poll command
 ### Resolve Review Items
 
 ```sh
-pr-shepherd resolve 42 --fetch
 pr-shepherd resolve 42 --reply-thread-ids PRRT_abc --message "Renamed the variable for clarity." --require-sha "$(git rev-parse HEAD)"
 ```
 
+Use `pr-shepherd iterate 42` or `pr-shepherd 42` to fetch the next PR action. `resolve` requires at least one action flag and only applies explicit review-state mutations.
+
 ### Apply One Suggestion Thread
 
 ```sh

package/bin/cli/args.mjs

@@ -25,7 +25,6 @@ const FLAGS_WITH_VALUES = new Set([
 // for PR-number detection — so removed flags don't silently cause their
 // numeric value to be misidentified as the PR number.
 const BOOLEAN_FLAGS = new Set([
-    "--fetch",
     "--no-auto-mark-ready",
     "--no-auto-cancel-actionable",
     "--dry-run",

package/bin/cli/formatters.mjs

@@ -4,68 +4,6 @@ export { formatCleanResult } from "./clean-formatter.mjs";
 export { formatMarkFilesAsViewedResult } from "./mark-files-as-viewed-formatter.mjs";
 export { formatMutateResult } from "./mutate-formatter.mjs";
 import { safeFence } from "./fence.mjs";
-import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderThreadResolutionStatusTag, buildFirstLookBullets, renderEditedCommentTag, } from "./list-formatters.mjs";
-import { joinSections } from "../util/markdown.mjs";
-export function formatFetchResult(result) {
-    const activeTotal = result.actionableThreads.length +
-        result.resolutionOnlyThreads.length +
-        result.actionableComments.length +
-        result.changesRequestedReviews.length +
-        result.reviewSummaries.length;
-    const firstLookTotal = result.firstLookThreads.length + result.firstLookComments.length;
-    const total = activeTotal + firstLookTotal;
-    const headingParts = [];
-    if (activeTotal > 0)
-        headingParts.push(`${activeTotal} actionable`);
-    if (firstLookTotal > 0)
-        headingParts.push(`${firstLookTotal} first-look`);
-    const headingSuffix = headingParts.length > 0 ? headingParts.join(", ") : "0 actionable";
-    const sections = [`# PR #${result.prNumber} — Resolve fetch (${headingSuffix})`];
-    if (result.actionableThreads.length > 0) {
-        sections.push(`## Actionable Review Threads (${result.actionableThreads.length})` +
-            (result.commitSuggestionsEnabled ? " [commit-suggestions: enabled]" : ""));
-        sections.push(result.actionableThreads
-            .map((t) => renderThreadBullet(t, { renderSuggestion: true }))
-            .join("\n\n"));
-    }
-    if (result.resolutionOnlyThreads.length > 0) {
-        sections.push(`## Review threads to resolve (${result.resolutionOnlyThreads.length})`);
-        sections.push(result.resolutionOnlyThreads
-            .map((t) => renderThreadBullet(t, { statusTag: renderThreadResolutionStatusTag(t) }))
-            .join("\n"));
-    }
-    if (result.actionableComments.length > 0) {
-        sections.push(`## Actionable PR Comments (${result.actionableComments.length})`);
-        sections.push(result.actionableComments
-            .map((c) => renderCommentBullet(c, { statusTag: renderEditedCommentTag(c) }))
-            .join("\n"));
-    }
-    if (result.changesRequestedReviews.length > 0) {
-        sections.push(`## Pending CHANGES_REQUESTED reviews (${result.changesRequestedReviews.length})`);
-        sections.push(result.changesRequestedReviews.map((r) => renderReviewBullet(r)).join("\n"));
-    }
-    if (result.reviewSummaries.length > 0) {
-        sections.push(`## Review summaries (${result.reviewSummaries.length})`);
-        sections.push(result.reviewSummaries.map((r) => renderReviewBullet(r, { includeBody: true })).join("\n"));
-    }
-    if (firstLookTotal > 0) {
-        sections.push(`## First-look items (${firstLookTotal}) — acknowledge status before acting`);
-        const resolutionOnlyIds = new Set(result.resolutionOnlyThreads.map((t) => t.id));
-        sections.push(buildFirstLookBullets(result.firstLookThreads, resolutionOnlyIds, result.firstLookComments).join("\n"));
-    }
-    sections.push("## Summary");
-    sections.push(total === 0
-        ? "0 actionable, 0 first-look — all items seen"
-        : [
-            activeTotal > 0 ? `${activeTotal} actionable` : null,
-            firstLookTotal > 0 ? `${firstLookTotal} first-look` : null,
-        ]
-            .filter(Boolean)
-            .join(", "));
-    sections.push("## Instructions");
-    sections.push(result.instructions.map((inst, i) => `${i + 1}. ${inst}`).join("\n"));
-    return joinSections(sections);
-}
 export function formatCommitSuggestionResult(result) {
     const lines = [];
     const range = result.startLine === result.endLine

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

@@ -1,24 +1,15 @@
 export const COMMAND_USAGE = {
     resolve: `pr-shepherd resolve
 
-Fetch actionable review items or apply GitHub review-state mutations after fixes.
+Apply GitHub review-state mutations after fixes.
 
 Usage:
-  pr-shepherd resolve [PR] [--fetch] [--format text|json]
   pr-shepherd resolve [PR] --reply-thread-ids A,B --message MSG
   pr-shepherd resolve [PR] --resolve-thread-ids A,B [--minimize-comment-ids X,Y]
                             [--dismiss-review-ids Q] [--message MSG]
                             [--require-sha SHA] [--format text|json]
 
-Modes:
-  fetch                Default when no mutation IDs are provided. Fetches review threads,
-                       comments, first-look items, and instructions.
-  mutate               Runs when any mutation ID flag is present. Resolves threads,
-                       replies to human threads, resolves non-human/manual thread IDs,
-                       minimizes non-human comments/review summaries, and dismisses non-human reviews.
-
 Flags:
-  --fetch                         Force fetch mode.
   --resolve-thread-ids <ids>      Comma-separated review thread IDs to resolve.
                                   Human-authored thread IDs are skipped; use --reply-thread-ids.
   --reply-thread-ids <ids>        Comma-separated human review thread IDs to reply to.
@@ -30,6 +21,9 @@ Flags:
   --format text|json              Output format. Default: text.
   --help, -h                      Print this help and exit before GitHub I/O.
 
+At least one non-empty action flag is required:
+  --reply-thread-ids, --resolve-thread-ids, --minimize-comment-ids, or --dismiss-review-ids.
+
 PR may be a number or GitHub pull request URL. When omitted, the current branch PR is inferred.
 Exit code: 0 on success; 1 on validation, lookup, or mutation failure.`,
     "commit-suggestion": `pr-shepherd commit-suggestion

package/bin/cli/help-top-page.mjs

@@ -18,7 +18,7 @@ Commands:
   [PR]                 Poll until non-WAIT or timeout. This is the default command.
   iterate              Run one iterate tick (single-tick alias).
   poll                 Re-run iterate while the action is WAIT, then print the final tick.
-  resolve              Fetch actionable review items, or resolve/minimize/dismiss IDs.
+  resolve              Apply review-state mutations (requires at least one action flag).
   commit-suggestion    Convert one GitHub suggestion thread into a patch and commit instructions.
   mark-files-as-viewed Mark PR changed files as viewed in GitHub.
   clean                Remove pr-shepherd state files.

package/bin/cli-parser.mjs

@@ -6,7 +6,7 @@
  *   pr-shepherd [PR] [--interval 45s] [--timeout 4m] [--format text|json] [--ready-delay Nm]
  *                  [--stall-timeout <duration>] [--no-auto-mark-ready]
  *                  [--no-auto-cancel-actionable]
- *   pr-shepherd resolve [PR] [--fetch] [--resolve-thread-ids A,B] [--minimize-comment-ids X,Y]
+ *   pr-shepherd resolve [PR] [--resolve-thread-ids A,B] [--minimize-comment-ids X,Y]
  *                            [--reply-thread-ids A,B] [--dismiss-review-ids Q]
  *                            [--message MSG] [--require-sha SHA]
  *   pr-shepherd commit-suggestion [PR] --thread-id ID --message MSG [--description DESC]
@@ -22,12 +22,12 @@
  *   pr-shepherd clean <pr|branch|current|repo|all> [value] [--dry-run] [--format text|json]
  */
 import { readFileSync } from "node:fs";
-import { runResolveFetch, runResolveMutate } from "./commands/resolve.mjs";
+import { runResolveMutate } from "./commands/resolve.mjs";
 import { runLogFile } from "./commands/log-file.mjs";
 import { parseCommonArgs, getFlag, hasFlag, parseList } from "./cli/args.mjs";
 import { isDefaultPollInvocation, validateDefaultPollArgs } from "./cli/default-poll.mjs";
 import { USAGE, maybePrintHelp } from "./cli/help.mjs";
-import { formatFetchResult, formatMutateResult } from "./cli/formatters.mjs";
+import { formatMutateResult } from "./cli/formatters.mjs";
 import { handleClean, handleCommitSuggestion, handleIterate, handleMarkFilesAsViewed, } from "./cli/handlers.mjs";
 import { handlePoll } from "./cli/poll-handler.mjs";
 import { setupLog } from "./log/setup.mjs";
@@ -130,30 +130,31 @@ 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;
-    const fetchMode = hasFlag(extra, "--fetch") ||
-        (resolveThreadIds.length === 0 &&
-            replyThreadIds.length === 0 &&
-            minimizeCommentIds.length === 0 &&
-            dismissReviewIds.length === 0);
-    if (fetchMode) {
-        const result = await runResolveFetch({ ...globalOpts, prNumber });
-        process.stdout.write(globalOpts.format === "json"
-            ? `${JSON.stringify(result, null, 2)}\n`
-            : `${formatFetchResult(result)}\n`);
+    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;
+        return;
     }
-    else {
-        const result = await runResolveMutate({
-            ...globalOpts,
-            prNumber,
-            resolveThreadIds,
-            replyThreadIds,
-            minimizeCommentIds,
-            dismissReviewIds,
-            dismissMessage,
-            requireSha,
-        });
-        process.stdout.write(globalOpts.format === "json"
-            ? `${JSON.stringify(result, null, 2)}\n`
-            : `${formatMutateResult(result)}\n`);
+    const hasAction = resolveThreadIds.length > 0 ||
+        replyThreadIds.length > 0 ||
+        minimizeCommentIds.length > 0 ||
+        dismissReviewIds.length > 0;
+    if (!hasAction) {
+        process.stderr.write("pr-shepherd: resolve: an action flag is required (--reply-thread-ids, --resolve-thread-ids, --minimize-comment-ids, or --dismiss-review-ids).\n");
+        process.exitCode = 1;
+        return;
     }
+    const result = await runResolveMutate({
+        ...globalOpts,
+        prNumber,
+        resolveThreadIds,
+        replyThreadIds,
+        minimizeCommentIds,
+        dismissReviewIds,
+        dismissMessage,
+        requireSha,
+    });
+    process.stdout.write(globalOpts.format === "json"
+        ? `${JSON.stringify(result, null, 2)}\n`
+        : `${formatMutateResult(result)}\n`);
 }

package/bin/commands/commit-suggestion-instruction.mjs

@@ -1,9 +1,9 @@
 import { buildPrShepherdCommand } from "../cli/runner.mjs";
 /**
  * Build the `commit-suggestion` instruction step for agent consumers.
- * Shared between `fix_code` (iterate) and `resolve --fetch` paths.
- * @param sectionName - The markdown section heading where suggestion threads appear
- *   (e.g. `"## Review threads"` for iterate, `"## Actionable Review Threads"` for resolve).
+ * Currently emitted by iterate `fix_code` for suggestion review threads.
+ * @param sectionName - The markdown section heading where suggestion threads appear,
+ *   e.g. `"## Review threads"`.
  * @param includeDriftHint - Whether to add the trailing note about drift on failed apply.
  */
 export function buildCommitSuggestionInstruction(prNumber, sectionName, includeDriftHint) {

package/bin/commands/resolve.mjs

@@ -1,77 +1 @@
-import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
-import { fetchPrBatch } from "../github/batch.mjs";
-import { loadConfig } from "../config/load.mjs";
-import { classifyVisibleComments } from "../comments/visible-comments.mjs";
-import { extractSuggestion } from "../suggestions/extract.mjs";
-import { buildFetchInstructions } from "./resolve-instructions.mjs";
-import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs";
-import { threadTranscriptBody } from "../threads/transcript.mjs";
-import { classifyThreadVisibility } from "../comments/thread-visibility.mjs";
-import { classifyReviewsForDisplay } from "../comments/review-visibility.mjs";
-import { markReviewInlineThreadMarkers } from "../comments/review-thread-markers.mjs";
-import { normalizeBotUsernames } from "../comments/authors.mjs";
 export { runResolveMutate } from "./resolve-mutate.mjs";
-export async function runResolveFetch(opts) {
-    const repo = await getRepoInfo();
-    const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
-    if (prNumber === null) {
-        throw new Error("No open PR found for current branch. Pass a PR number explicitly.");
-    }
-    const { data } = await fetchPrBatch(prNumber, repo);
-    const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
-    const minimizedCommentCandidates = data.comments.filter((c) => c.isMinimized);
-    const seenMap = await loadSeenMap(stateKey);
-    const cfg = loadConfig();
-    const botUsernames = normalizeBotUsernames(cfg.botUsernames);
-    const threadVisibility = classifyThreadVisibility(data.reviewThreads, seenMap, botUsernames);
-    const unseenMinimizedComments = [];
-    const editedMinimizedComments = [];
-    for (const c of minimizedCommentCandidates) {
-        const cls = classifyItem(c.id, c.body, seenMap);
-        if (cls === "new")
-            unseenMinimizedComments.push(c);
-        else if (cls === "edited")
-            editedMinimizedComments.push(c);
-    }
-    const visibleCommentClassification = classifyVisibleComments(data.comments, seenMap, cfg.iterate?.minimizeComments, botUsernames);
-    const changesRequestedReviewVisibility = classifyReviewsForDisplay(data.changesRequestedReviews, seenMap);
-    const reviewSummaryVisibility = cfg.resolve.fetchReviewSummaries
-        ? classifyReviewsForDisplay(data.reviewSummaries, seenMap)
-        : { visible: [], toMarkSeen: [] };
-    const actionableThreads = threadVisibility.activeThreads.map(({ isResolved: _r, isOutdated: _o, ...rest }) => {
-        const thread = rest;
-        const suggestion = extractSuggestion(rest);
-        if (suggestion)
-            thread.suggestion = suggestion;
-        return thread;
-    });
-    const firstLookComments = [
-        ...unseenMinimizedComments.map((c) => ({ ...c, firstLookStatus: "minimized" })),
-        ...editedMinimizedComments.map((c) => ({
-            ...c,
-            firstLookStatus: "minimized",
-            edited: true,
-        })),
-    ];
-    // Mark new and edited items as seen (best-effort — markSeen never throws).
-    await Promise.allSettled([
-        ...threadVisibility.toMarkSeen.map((t) => markSeen(stateKey, t.id, threadTranscriptBody(t))),
-        ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
-        ...visibleCommentClassification.toMarkSeen.map((c) => markSeen(stateKey, c.id, c.body)),
-        ...changesRequestedReviewVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
-        ...reviewSummaryVisibility.toMarkSeen.map((r) => markSeen(stateKey, r.id, r.body)),
-    ]);
-    await markReviewInlineThreadMarkers(stateKey, data.reviewThreads);
-    const result = {
-        prNumber,
-        actionableThreads,
-        resolutionOnlyThreads: threadVisibility.resolutionOnlyThreads,
-        firstLookThreads: threadVisibility.firstLookThreads,
-        actionableComments: visibleCommentClassification.actionable,
-        firstLookComments,
-        changesRequestedReviews: changesRequestedReviewVisibility.visible,
-        reviewSummaries: reviewSummaryVisibility.visible,
-        commitSuggestionsEnabled: cfg.actions.commitSuggestions,
-    };
-    return { ...result, instructions: buildFetchInstructions(prNumber, result) };
-}

package/bin/config.json

@@ -26,8 +26,7 @@
     "shaPoll": {
       "intervalMs": 2000,
       "maxAttempts": 10
-    },
-    "fetchReviewSummaries": true
+    }
   },
   "checks": {
     "ciTriggerEvents": ["pull_request", "pull_request_target"]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -28,8 +28,8 @@
     "@types/node": "^25.6.0",
     "@vitest/coverage-v8": "^4.1.4",
     "husky": "^9.1.7",
-    "knip": "^5.88.1",
-    "oxfmt": "^0.48.0",
+    "knip": "^6.14.1",
+    "oxfmt": "^0.50.0",
     "oxlint": "^1.60.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.4"

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

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

package/bin/commands/resolve-instructions.mjs

@@ -1,62 +0,0 @@
-import { buildPrShepherdCommand } from "../cli/runner.mjs";
-import { SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEMS, buildShepherdJournalInstruction, } from "./shepherd-journal.mjs";
-import { buildCommitSuggestionInstruction } from "./commit-suggestion-instruction.mjs";
-/**
- * Build the numbered triage/fix/resolve instruction steps for the agent to follow.
- * Steps are conditionally emitted based on what the fetch returned (mirrors
- * `buildFixInstructions` in `commands/iterate/render.mts`).
- */
-export function buildFetchInstructions(prNumber, result) {
-    const { actionableThreads, resolutionOnlyThreads, firstLookThreads, actionableComments, firstLookComments, changesRequestedReviews, reviewSummaries, commitSuggestionsEnabled, } = result;
-    const firstLookTotal = firstLookThreads.length + firstLookComments.length;
-    const total = actionableThreads.length +
-        resolutionOnlyThreads.length +
-        actionableComments.length +
-        changesRequestedReviews.length +
-        reviewSummaries.length +
-        firstLookTotal;
-    if (total === 0) {
-        return ["No actionable items and no first-look items — end this invocation."];
-    }
-    const hasCodeItems = actionableThreads.length > 0 ||
-        actionableComments.length > 0 ||
-        changesRequestedReviews.length > 0;
-    const hasSuggestions = commitSuggestionsEnabled && actionableThreads.some((t) => t.suggestion != null);
-    const instructions = [];
-    instructions.push(`Classify every item listed above into exactly one of: Fixed / Actionable / Not relevant / Outdated / Acknowledge. Do not silently skip any item. Bot-authored review summaries (authors whose name contains \`[bot]\` or matches \`copilot-pull-request-reviewer\`, \`gemini-code-assist\`) default to Acknowledge with reason "bot summary — no actionable content" unless the body calls out an unaddressed issue.`);
-    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\`, include its ID in \`--resolve-thread-ids\`; otherwise do not pass first-look-only IDs to mutation flags.`);
-    }
-    const editedTotal = actionableComments.filter((c) => c.edited).length +
-        firstLookThreads.filter((t) => t.edited).length +
-        firstLookComments.filter((c) => c.edited).length;
-    if (editedTotal > 0) {
-        instructions.push(`Actionable comments marked \`[edited since first look]\` and first-look bullets tagged \`, edited\` were updated by their author after you previously acknowledged them. Read the updated body before deciding whether any matching \`## Review threads to resolve\` item should be resolved.`);
-    }
-    if (hasSuggestions) {
-        instructions.push(buildCommitSuggestionInstruction(prNumber, "## Actionable Review Threads", true));
-    }
-    if (hasCodeItems) {
-        instructions.push(`Read and edit each file referenced under \`## Actionable Review Threads\`, \`## Actionable PR Comments\`, and \`## Pending CHANGES_REQUESTED reviews\` above. Reclassify each fixed item as Fixed. If an item is too complex to address, leave it as Actionable for the final report.`);
-        instructions.push(`If you applied code edits: commit them with a descriptive message, cancel any stale in-progress runs, then rebase and push per your repository's conventions.`);
-    }
-    if (resolutionOnlyThreads.length > 0) {
-        instructions.push(`Resolve each thread under \`## Review threads to resolve\` with \`--resolve-thread-ids\`. These threads are already outdated or minimized, so no code edit is required for them unless their body reveals separate work you choose to do.`);
-    }
-    const requireShaHint = hasCodeItems
-        ? ` Include \`--require-sha $(git rev-parse HEAD)\` only when you pushed new commits.`
-        : "";
-    const dismissNote = changesRequestedReviews.length > 0
-        ? ` For \`--dismiss-review-ids\`: \`--message\` is required with one specific sentence describing the fix or the reason for not acting (no boilerplate like "address review comments"); omit \`--message\` when not dismissing. Review-summary IDs (\`PRR_…\` from \`## Review summaries\`) go into \`--minimize-comment-ids\`, never \`--dismiss-review-ids\`.`
-        : reviewSummaries.length > 0
-            ? ` Review-summary IDs (\`PRR_…\` from \`## Review summaries\`) go into \`--minimize-comment-ids\`.`
-            : "";
-    const resolveCommand = `${buildPrShepherdCommand(["resolve", String(prNumber)]).text} [--reply-thread-ids <ids>] [--resolve-thread-ids <ids>] [--minimize-comment-ids <ids>] [--dismiss-review-ids <ids>] [--message "<reason>"]`;
-    if (actionableThreads.length > 0 || resolutionOnlyThreads.length > 0) {
-        instructions.push(`Do not reply to your own thread comments. If the latest visible comment in a thread is your own prior Shepherd reply, leave that thread out of \`--reply-thread-ids\`.`);
-    }
-    instructions.push(`Run \`${resolveCommand}\` with only the non-empty flag subsets. Skip the command entirely if all ID lists are empty.${requireShaHint}${dismissNote}`);
-    instructions.push(buildShepherdJournalInstruction(prNumber, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEMS));
-    instructions.push(`Report: echo the CLI's mutation output, then one line per Acknowledged item: \`Acknowledged <id> (@<author>): <reason>\`. If any fetched item was neither resolved nor acknowledged, stop and escalate: "<N> item(s) fetched but not acted on or acknowledged — need human direction before closing".`);
-    return instructions;
-}