pr-shepherd 0.46.3 → 0.46.4

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

package/bin/commands/iterate/check-instructions.d.mts

@@ -11,6 +11,15 @@ export declare function buildCrStaleClause(reviews: Review[]): string;
  * discarding the rest of the user's config.
  */
 export declare function buildBehindBaseHintInstruction(baseBranch: string, hint: string, isBehind: boolean): string[];
+/**
+ * Give one branch-refresh recovery path after Shepherd's single workflow rerun has failed.
+ * The fetched PR base branch is raw context; the caller still owns repository-specific git
+ * mechanics and decides whether the base contains a relevant fix.
+ */
+export declare function buildRepeatedWorkflowBranchRecoveryInstructions(baseBranch: string, hasExhaustedWorkflowRerun: boolean, branch: {
+    isBehind: boolean;
+    hasConflicts: boolean;
+}): string[];
 /**
  * Build the `Run the apply review: command` instruction. Steps stay here (not in the skill)
  * whenever the *unmodified, as-printed* command is unsafe without them:

package/bin/commands/iterate/check-instructions.mjs

@@ -20,6 +20,23 @@ export function buildBehindBaseHintInstruction(baseBranch, hint, isBehind) {
         return [];
     return [`The branch is behind PR base branch \`${baseBranch}\`. ${trimmedHint} before pushing.`];
 }
+/**
+ * Give one branch-refresh recovery path after Shepherd's single workflow rerun has failed.
+ * The fetched PR base branch is raw context; the caller still owns repository-specific git
+ * mechanics and decides whether the base contains a relevant fix.
+ */
+export function buildRepeatedWorkflowBranchRecoveryInstructions(baseBranch, hasExhaustedWorkflowRerun, branch) {
+    if (!hasExhaustedWorkflowRerun || (!branch.isBehind && !branch.hasConflicts))
+        return [];
+    const state = branch.hasConflicts ? "conflicts with" : "is behind";
+    const instructions = [
+        `The workflow rerun still fails while the branch ${state} PR base branch \`${baseBranch}\`. Inspect the current base branch for an existing fix before choosing a remediation.`,
+    ];
+    instructions.push(branch.hasConflicts
+        ? `Rebase or otherwise update the PR branch from \`${baseBranch}\` according to repository conventions, resolving conflicts as part of that update.`
+        : `Rebase or otherwise update the PR branch from \`${baseBranch}\` according to repository conventions.`);
+    return instructions;
+}
 /**
  * Build the `Run the apply review: command` instruction. Steps stay here (not in the skill)
  * whenever the *unmodified, as-printed* command is unsafe without them:

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

@@ -180,7 +180,10 @@ export async function handleFixCode(ctx) {
     const allCommentIds = [...commentMinimizeIds, ...reviewSummaryIds];
     const belongsToActiveWorkflowRun = (check) => check.runId !== null && inProgressWorkflowRunIds.has(check.runId);
     const manualFollowUpChecks = failingAgentChecks.filter((check) => !belongsToActiveWorkflowRun(check) && checkRequiresHumanFollowUp(check));
+    const exhaustedAttempts = manualFollowUpChecks.filter((check) => check.runAttempt !== undefined && check.runAttempt > 1);
+    const hasBehindBaseRecovery = isBehind && exhaustedAttempts.length > 0;
     const hasAutonomousWork = hasConflicts ||
+        hasBehindBaseRecovery ||
         threads.length > 0 ||
         resolutionOnlyThreads.length > 0 ||
         actionableComments.length > 0 ||
@@ -194,7 +197,6 @@ export async function handleFixCode(ctx) {
         checks.some((check) => (check.annotations?.length ?? 0) > 0) ||
         failingAgentChecks.some((check) => belongsToActiveWorkflowRun(check) || !checkRequiresHumanFollowUp(check));
     if (manualFollowUpChecks.length > 0 && !hasAutonomousWork) {
-        const exhaustedAttempts = manualFollowUpChecks.filter((check) => check.runAttempt !== undefined && check.runAttempt > 1);
         const checkSuggestion = exhaustedAttempts.length > 0
             ? `GitHub reports a later workflow attempt (${exhaustedAttempts
                 .map((check) => `${check.runId ?? check.name}: attempt ${check.runAttempt}`)
@@ -257,7 +259,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, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true);
+    const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true, exhaustedAttempts.length > 0);
     const prospectiveResult = {
         ...base,
         baseBranch: baseLookup.branch,

package/bin/commands/iterate/render.d.mts

@@ -2,4 +2,4 @@ import type { AgentThread, AgentComment, AgentCheck, Review, ResolveCommand, Fir
 /** Render a resolve command as a shell snippet. Appends `--require-sha "$HEAD_SHA"` when set. */
 export declare function renderResolveCommand(rc: ResolveCommand): string;
 export declare function buildFixInstructions(threads: AgentThread[], actionableComments: AgentComment[], checks: AgentCheck[], changesRequestedReviews: Review[], baseBranch: string, resolveCommand: ResolveCommand, hasConflicts: boolean, prReference: string | number, cancelledCount: number, firstLookThreads?: FirstLookThread[], firstLookComments?: FirstLookComment[], firstLookSummaries?: Review[], editedSummaries?: Review[], inProgressRunIds?: string[], resolutionOnlyThreads?: ReviewThread[], resolveOnlyCommand?: ResolveCommand, behindBaseHint?: string, // iterate.behindBaseHint — see buildBehindBaseHintInstruction
-isBehind?: boolean, viewerCanUpdate?: boolean): string[];
+isBehind?: boolean, viewerCanUpdate?: boolean, hasExhaustedWorkflowRerun?: boolean): string[];

package/bin/commands/iterate/render.mjs

@@ -1,5 +1,5 @@
 import { renderShellCommand } from "../../cli/runner.mjs";
-import { buildFailingCheckInstructions, buildCrStaleClause, buildBehindBaseHintInstruction, buildResolveCommandInstruction, buildFixCompletionInstruction, } from "./check-instructions.mjs";
+import { buildFailingCheckInstructions, buildCrStaleClause, buildBehindBaseHintInstruction, buildRepeatedWorkflowBranchRecoveryInstructions, buildResolveCommandInstruction, buildFixCompletionInstruction, } from "./check-instructions.mjs";
 import { SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE, buildShepherdJournalInstruction, } from "../shepherd-journal.mjs";
 import { isFailingAgentCheck } from "../../checks/conclusions.mjs";
 import { buildCommitSuggestionInstruction } from "../commit-suggestion-instruction.mjs";
@@ -11,11 +11,16 @@ export function renderResolveCommand(rc) {
     return renderShellCommand(parts);
 }
 export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prReference, cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behindBaseHint — see buildBehindBaseHintInstruction
-isBehind = false, viewerCanUpdate = false) {
+isBehind = false, viewerCanUpdate = false, hasExhaustedWorkflowRerun = false) {
     const instructions = [];
     const locatedThreads = threads.filter((thread) => thread.path !== null && thread.line !== null);
     const unlocatedThreads = threads.filter((thread) => thread.path === null || thread.line === null);
     const failingChecks = checks.filter((c) => isFailingAgentCheck(c));
+    const repeatedWorkflowBranchRecoveryInstructions = buildRepeatedWorkflowBranchRecoveryInstructions(baseBranch, hasExhaustedWorkflowRerun, {
+        isBehind,
+        hasConflicts,
+    });
+    const hasRepeatedWorkflowBranchRecovery = repeatedWorkflowBranchRecoveryInstructions.length > 0;
     const hasAnnotations = checks.some((c) => (c.annotations?.length ?? 0) > 0);
     const hasNonConflictHints = threads.length > 0 ||
         failingChecks.length > 0 ||
@@ -41,7 +46,7 @@ isBehind = false, viewerCanUpdate = false) {
         const sectionRef = actionableSections.length > 0 ? `under ${actionableSections.join(", ")}` : "above";
         instructions.push(`Review each item ${sectionRef} and decide whether it needs a code change.`);
     }
-    if (hasConflicts) {
+    if (hasConflicts && !hasRepeatedWorkflowBranchRecovery) {
         instructions.push("The branch has merge conflicts (see `**branch**` above). Resolve them before committing.");
     }
     const firstLookTotal = firstLookThreads.length + firstLookComments.length;
@@ -76,7 +81,7 @@ isBehind = false, viewerCanUpdate = false) {
     if (resolutionOnlyThreads.length > 0) {
         instructions.push('Review the threads under `## Review threads to resolve` before running mutations. Use the generated commands as shown — see "Review-mutation routing" in the pr-shepherd skill for which flag applies to which ID.');
     }
-    instructions.push(...buildFailingCheckInstructions(failingChecks));
+    instructions.push(...buildFailingCheckInstructions(failingChecks), ...repeatedWorkflowBranchRecoveryInstructions);
     if (hasAnnotations) {
         instructions.push("Inspect every referenced range under `## Check annotations` and apply any warranted change.");
     }
@@ -90,6 +95,9 @@ isBehind = false, viewerCanUpdate = false) {
     if (hasConflicts) {
         instructions.push(`Commit any remaining conflict-resolution changes and push to the PR head branch${mutationSuffix}.`);
     }
+    else if (hasRepeatedWorkflowBranchRecovery) {
+        instructions.push("Push the updated PR head branch before iterating again.");
+    }
     else if (hasNonConflictHints) {
         instructions.push("If you changed code, commit any remaining changes and push to the PR head branch, then run the remaining review mutations using the pushed commit SHA and iterate again with the same options. If you did not change code, do not commit and continue with the remaining steps.");
     }

package/package.json

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

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

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

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

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

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -20,11 +20,11 @@ If the requested PR does not exist yet, review and commit the in-scope changes,
 
 1. Parse an optional PR number, repository-qualified `owner/repo#N`, or GitHub PR URL and an optional `--merge` flag from `$ARGUMENTS`; otherwise let pr-shepherd infer the current branch PR. Reject any remaining argument. Follow the target repository's local `AGENTS.md` and `CLAUDE.md` standards while making changes.
 
-2. For the CLI, convert supplied `owner/repo#N` to `https://github.com/owner/repo/pull/N`; otherwise pass the supplied URL or bare number unchanged, then run the poll command `pr-shepherd` with the optional PR argument and forward `--merge` when supplied. A qualified reference may name a fork or upstream repository: it is the GitHub target, while the current checkout continues to supply local git/config/rules context. Do not run `pr-shepherd iterate`. If the CLI is unavailable and the `iterate` MCP tool is available, first obtain a repository-qualified reference: use a supplied GitHub PR URL or `owner/repo#N` unchanged; for a bare number, run `gh pr view <number> --json url --jq .url`; when omitted, run `gh pr view --json url --jq .url`. If that does not produce one qualified PR reference, stop and report that MCP cannot safely determine the PR. Otherwise call `iterate` with that qualified reference, plus `merge: true` when `--merge` was supplied, and print its full result.
+2. For the CLI, convert supplied `owner/repo#N` to `https://github.com/owner/repo/pull/N`; otherwise pass the supplied URL or bare number unchanged, then run the canonical poll command `pr-shepherd [PR] --until-terminal`, omitting `[PR]` when none was supplied and appending `--merge` when requested. This command keeps ordinary `[WAIT]` and `[MARK_READY]` ticks inside the same invocation; it returns for agent-facing work, a quota warning, `[CANCEL]`, or `[ESCALATE]`. A qualified reference may name a fork or upstream repository: it is the GitHub target, while the current checkout continues to supply local git/config/rules context. Do not run `pr-shepherd iterate`. If the CLI is unavailable and the `iterate` MCP tool is available, first obtain a repository-qualified reference: use a supplied GitHub PR URL or `owner/repo#N` unchanged; for a bare number, run `gh pr view <number> --json url --jq .url`; when omitted, run `gh pr view --json url --jq .url`. If that does not produce one qualified PR reference, stop and report that MCP cannot safely determine the PR. Otherwise call `iterate` with that qualified reference, plus `merge: true` when `--merge` was supplied, and print its full result.
 
 3. Print the full result and follow every returned `## Instructions` step exactly. For CLI output, run each printed mutation command when instructed. For MCP output, use MCP `apply` and `build_suggestion_patches` with the same qualified PR reference; do not run a shell `pr-shepherd apply` command.
 
-4. After completing the returned instructions, repeat step 2 unless the action is `[CANCEL]` or `[ESCALATE]`, or the human directs you to stop. `[FIX_CODE]` is always non-terminal: complete its instructions and rerun the same canonical command without asking whether to continue. Only `[ESCALATE]` hands work to a human.
+4. After completing the returned instructions, repeat step 2 with the same target and canonical options unless the action is `[CANCEL]` or `[ESCALATE]`, or the human directs you to stop. Preserve `--until-terminal` and any requested `--merge`; apply any polling-cadence adjustment printed by the CLI. Every other action is non-terminal: complete its instructions and rerun without asking whether to continue. `[FIX_CODE]` is always non-terminal, and only `[ESCALATE]` hands work to a human.
 
 ## Playbooks