pr-shepherd 0.16.0 → 0.16.2

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

package/README.md

@@ -20,7 +20,7 @@ Example Workflow:
 
 `pr-shepherd` optimizes token management, rate limits, and agentic orchestration by moving **ALL** deterministic logic and prompts to code via a CLI tool, enshrining what would be a large skill or command prompt (of which the agent would inevitably make mistakes) into the code and returning a clear, actionable prompt.
 
-The CLI emits unified sleep/timeout instructions for all runtimes: pick a fresh sleep/timeout between 30 seconds and 4 minutes and rerun the configured pr-shepherd command. Codex is detected with `AGENT=codex` or the current Codex CLI signal `CODEX_CI=1`. Generated commands use `cli.runner` from `.pr-shepherdrc.yml`: `auto` (default), `npx`, `pnpm`, or `yarn`.
+The CLI emits runtime-specific retry instructions. Claude-compatible output schedules exactly one next session-only iteration after a fresh delay between 30 seconds and 4 minutes, then ends the turn. Codex-compatible output sleeps inline for that delay, then reruns the configured pr-shepherd command. Codex is detected with `AGENT=codex` or the current Codex CLI signal `CODEX_CI=1`. Generated commands use `cli.runner` from `.pr-shepherdrc.yml`: `auto` (default), `npx`, `pnpm`, or `yarn`.
 
 At a high level, the skill invokes `pr-shepherd <PR>` through the selected package runner, which provides actionable feedback directly to the agent:
 
@@ -61,7 +61,7 @@ _(schematic — actual steps depend on PR state)_
 4. Rebase and push: `git fetch origin && git rebase origin/main && git push --force-with-lease` — capture `HEAD_SHA=$(git rev-parse HEAD)`.
 5. Run the `resolve:` command above, substituting `"$HEAD_SHA"`.
 6. Add or update a `## Shepherd Journal` section in the PR description for any large decisions made, appending under the existing heading if it already exists.
-7. CI needs time to run on the new push. Pick a fresh sleep/timeout between 30 seconds and 4 minutes, wait that long, then rerun `npx pr-shepherd 123` to recheck.
+7. CI needs time to run on the new push. Schedule one session-only follow-up task to run `npx pr-shepherd 123` to recheck once after a fresh delay between 30 seconds and 4 minutes, then end this turn. Do not sleep or rerun inline.
 ```
 
 On every iteration, a command is returned to instruct the agent exactly what to do. No guessing, no thinking, as few agentic turns as possible:
@@ -97,7 +97,7 @@ Some other workflow improvements:
 
 Recommendations:
 
-- Run `pr-shepherd` on all your PRs before you go to sleep so that you wake up to reviewable PRs. Keep an active goal cycling the reusable command with a fresh sleep/timeout between 30 seconds and 4 minutes before each rerun until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures).
+- Run `pr-shepherd` on all your PRs before you go to sleep so that you wake up to reviewable PRs. Keep an active goal cycling the reusable command until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures). Claude schedules one next session-only iteration per tick; Codex sleeps inline and reruns.
 - Instruct your agents to write comments in a single review (comment, changes requested, or approved). This allows the review's comments/threads to be minimized or resolved together, keeping your pull request history clean. If you write inline comments outside of a review, each comment would still show up in the pull request history and take up space.
 - Avoid sticky comments as they will continue to be hidden. Instead, just make a new comment, especially on reviews. If you really want sticky comments, instruct your agent to unhide/unminimize them when updating them.
 - Avoid having automation edit comments, reviews, or threads in place because updated items get minimized. Instead, always make a new review, comment, thread, etc.
@@ -114,7 +114,7 @@ Recommendations:
 
 ### Iterate a PR to completion
 
-One-tick dispatcher — checks CI and review comments, fixes issues, and marks the PR ready for review when clean. Each non-terminal tick emits an `## Instructions` section telling the agent to pick a fresh 30s–4m delay and rerun; the loop continues until `[CANCEL]` or `[ESCALATE]`.
+One-tick dispatcher — checks CI and review comments, fixes issues, and marks the PR ready for review when clean. Each non-terminal tick emits an `## Instructions` section telling the agent how to run the next tick; the loop continues until `[CANCEL]` or `[ESCALATE]`.
 
 Claude Code (via `pr-shepherd` skill):
 
@@ -134,7 +134,7 @@ npx pr-shepherd iterate 42               # legacy-compatible spelling
 
 ## Iterate decision loop
 
-On each tick: fetch PR state in one GraphQL batch → classify CI, comments, and merge status → take one action (`fix_code`, `mark_ready`, `cancel`, `escalate`, or `wait`). All runtimes pick a fresh sleep/timeout between 30 seconds and 4 minutes for each nonterminal recurrence. See [docs/iterate-flow.md](docs/iterate-flow.md) for the decision table and [docs/flow.md](docs/flow.md) for the end-to-end flow diagram.
+On each tick: fetch PR state in one GraphQL batch → classify CI, comments, and merge status → take one action (`fix_code`, `mark_ready`, `cancel`, `escalate`, or `wait`). Claude schedules one next session-only iteration after a fresh 30s-4m delay; Codex sleeps inline for that delay and reruns. See [docs/iterate-flow.md](docs/iterate-flow.md) for the decision table and [docs/flow.md](docs/flow.md) for the end-to-end flow diagram.
 
 ## Install
 
@@ -216,7 +216,7 @@ Then iterate a PR from Codex with the target repository's package runner:
 
 For example, a repo like `~/filaments` that declares `packageManager: "pnpm@..."` and has `pnpm-lock.yaml` should use `pnpm exec pr-shepherd iterate 42`. For npm repos, use `npx pr-shepherd iterate 42`.
 
-Or ask Codex to use the `pr-shepherd` skill, for example: `run pr-shepherd until this PR is ready`. Follow the output's `## Instructions`. The skill runs one tick and the instructions tell you to pick a fresh sleep/timeout between 30 seconds and 4 minutes before the next rerun. Continue until Shepherd emits `[CANCEL]` or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures). `pr-shepherd iterate 42` remains supported for existing workflows.
+Or ask Codex to use the `pr-shepherd` skill, for example: `run pr-shepherd until this PR is ready`. Follow the output's `## Instructions`. The skill runs one tick and Codex-compatible instructions tell you to pick a fresh sleep/timeout between 30 seconds and 4 minutes before the next rerun. Continue until Shepherd emits `[CANCEL]` or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures). `pr-shepherd iterate 42` remains supported for existing workflows.
 
 ### As a global CLI
 
@@ -259,10 +259,6 @@ Full reference: [docs/README.md](docs/README.md) — CLI usage, skills, configur
 
 See [docs/architecture.md](docs/architecture.md) for the module map and dependency rules.
 
-## Forking
-
-See [docs/forking.md](docs/forking.md) if you want to customize pr-shepherd for your own use or team.
-
 ## License
 
 [MIT](LICENSE)

package/bin/cli/exit-codes.mjs

@@ -11,6 +11,8 @@ export function parseDurationToMinutes(s, defaultMinutes) {
 }
 export function statusToExitCode(status) {
     switch (status) {
+        case "MERGED":
+        case "CLOSED":
         case "READY":
             return 0;
         case "IN_PROGRESS":

package/bin/cli/iterate-instructions.mjs

@@ -1,16 +1,19 @@
 import { FIX_INSTRUCTION_STOP_AFTER_PUSH, FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK, } from "../commands/iterate/render.mjs";
 import { buildPrShepherdCommand } from "./runner.mjs";
-function buildRecheckInstruction(rerunCommand, tail) {
-    return `Pick a fresh sleep/timeout between 30 seconds and 4 minutes, wait that long, then rerun \`${rerunCommand}\` ${tail}`;
+function buildRecheckInstruction(runtime, rerunCommand, purpose) {
+    if (runtime === "codex") {
+        return `Pick a fresh sleep/timeout between 30 seconds and 4 minutes, wait that long, then rerun \`${rerunCommand}\` to ${purpose}.`;
+    }
+    return `Schedule one session-only follow-up task to run \`${rerunCommand}\` to ${purpose} once after a fresh delay between 30 seconds and 4 minutes, then end this turn. Do not sleep or rerun inline.`;
 }
-export function buildSimpleIterateInstructions(result, _runtime, readyDelaySuffix, runner) {
-    const rerunCommand = buildCodexIterateCommand(result.pr, readyDelaySuffix, runner);
+export function buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner) {
+    const rerunCommand = buildIterateCommand(result.pr, readyDelaySuffix, runner);
     switch (result.action) {
         case "wait":
-            return [buildRecheckInstruction(rerunCommand, "to continue the active goal.")];
+            return [buildRecheckInstruction(runtime, rerunCommand, "continue the active goal")];
         case "mark_ready":
             return [
-                `The CLI already marked the PR ready for review. ${buildRecheckInstruction(rerunCommand, "to recheck.")}`,
+                `The CLI already marked the PR ready for review. ${buildRecheckInstruction(runtime, rerunCommand, "recheck")}`,
             ];
         case "cancel":
             return ["Stop — the active goal is complete."];
@@ -18,14 +21,14 @@ export function buildSimpleIterateInstructions(result, _runtime, readyDelaySuffi
             return ["Stop — the PR needs human direction before iterating can resume."];
     }
 }
-export function adaptFixCodeInstructions(instructions, pr, _runtime, readyDelaySuffix, runner) {
-    const rerunCommand = buildCodexIterateCommand(pr, readyDelaySuffix, runner);
+export function adaptFixCodeInstructions(instructions, pr, runtime, readyDelaySuffix, runner) {
+    const rerunCommand = buildIterateCommand(pr, readyDelaySuffix, runner);
     return instructions.map((instruction) => {
         if (instruction === FIX_INSTRUCTION_STOP_AFTER_PUSH) {
-            return `CI needs time to run on the new push. ${buildRecheckInstruction(rerunCommand, "to recheck.")}`;
+            return `CI needs time to run on the new push. ${buildRecheckInstruction(runtime, rerunCommand, "recheck")}`;
         }
         if (instruction === FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK) {
-            return buildRecheckInstruction(rerunCommand, "to recheck.");
+            return buildRecheckInstruction(runtime, rerunCommand, "recheck");
         }
         return instruction;
     });
@@ -33,7 +36,7 @@ export function adaptFixCodeInstructions(instructions, pr, _runtime, readyDelayS
 export function adaptIterateLog(log, _runtime) {
     return log.replace(/\s+—\s+\d+s until auto-cancel/g, "");
 }
-export function buildCodexIterateCommand(pr, readyDelaySuffix, runner) {
+export function buildIterateCommand(pr, readyDelaySuffix, runner) {
     const suffix = readyDelaySuffix?.trim();
     return buildPrShepherdCommand([String(pr), ...(suffix ? ["--ready-delay", suffix] : [])], {
         runner,

package/bin/commands/check-terminal-report.mjs

@@ -0,0 +1,35 @@
+export function buildTerminalReport(prNumber, repo, batchData, mergeStatus, status) {
+    return {
+        pr: prNumber,
+        nodeId: batchData.nodeId,
+        repo: `${repo.owner}/${repo.name}`,
+        status,
+        baseBranch: batchData.baseRefName,
+        mergeStatus,
+        checks: {
+            passing: [],
+            failing: [],
+            inProgress: [],
+            skipped: [],
+            filtered: [],
+            filteredNames: [],
+            blockedByFilteredCheck: false,
+        },
+        threads: {
+            actionable: [],
+            resolutionOnly: [],
+            autoResolved: [],
+            autoResolveErrors: [],
+            firstLook: [],
+        },
+        comments: {
+            actionable: [],
+            firstLook: [],
+        },
+        changesRequestedReviews: [],
+        reviewSummaries: [],
+        firstLookSummaries: [],
+        editedSummaries: [],
+        approvedReviews: [],
+    };
+}

package/bin/commands/check.mjs

@@ -9,6 +9,7 @@ import { deriveMergeStatus } from "../merge-status/derive.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { classifyVisibleComments } from "../comments/visible-comments.mjs";
 import { computeStatus } from "./check-status.mjs";
+import { buildTerminalReport } from "./check-terminal-report.mjs";
 import { loadSeenMap, markSeen, classifyItem } from "../state/seen-comments.mjs";
 export async function runCheck(opts) {
     const repo = await getRepoInfo();
@@ -30,6 +31,10 @@ export async function runCheck(opts) {
             mergeStateStatus: restState.mergeStateStatus ?? batchData.mergeStateStatus,
         };
     }
+    const mergeStatus = deriveMergeStatus(batchData);
+    if (mergeStatus.state === "MERGED" || mergeStatus.state === "CLOSED") {
+        return buildTerminalReport(prNumber, repo, batchData, mergeStatus, mergeStatus.state);
+    }
     const startupFailureChecks = await fetchStartupFailureChecks(repo, batchData.headRefOid, prNumber);
     const allChecks = mergeStartupFailureChecks(batchData.checks, startupFailureChecks);
     const classifiedChecks = classifyChecks(allChecks);
@@ -111,7 +116,6 @@ export async function runCheck(opts) {
         ...[...firstLookSummaries, ...editedSummaries].map((r) => markSeen(stateKey, r.id, r.body)),
     ]);
     const resolutionOnlyThreads = unresolvedThreads.filter((t) => !autoResolvedIds.has(t.id) && (t.isOutdated || t.isMinimized));
-    const mergeStatus = deriveMergeStatus(batchData);
     const blockedByFilteredCheck = mergeStatus.status === "BLOCKED" &&
         !verdict.anyFailing &&
         !verdict.anyInProgress &&

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.16.0",
+  "version": "0.16.2",
   "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.16.0",
+  "version": "0.16.2",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

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

@@ -45,4 +45,4 @@ One-tick dispatcher for iterating a PR to completion.
 5. **Stop conditions:**
    - Stop when the CLI emits `[CANCEL]` (ready-delay completed, or PR merged/closed).
    - Stop when the CLI emits `[ESCALATE]`, including `stall-timeout` for repeated unchanged CI failures.
-   - All other actions (`[WAIT]`, `[MARK_READY]`, `[FIX_CODE]`) are non-terminal: follow the `## Instructions` to sleep/wait and rerun.
+   - All other actions (`[WAIT]`, `[MARK_READY]`, `[FIX_CODE]`) are non-terminal: follow the `## Instructions`. For Claude, schedule exactly one next session-only iteration and end the turn; do not sleep inline and do not create a recurring cron.