pr-shepherd 0.15.0 → 0.15.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.15.0",
+  "version": "0.15.2",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -89,7 +89,7 @@ _(schematic — actual steps depend on PR state)_
 3. Commit changed files.
 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 a `## Shepherd Journal` entry to the PR description for any large decisions made.
+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. Stop this iteration.
 ```
 
@@ -126,7 +126,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. In Claude Code, `/pr-shepherd:monitor` uses `/loop` and continues working when your rate limit window is reset. In Codex, keep an active goal cycling the reusable command every `watch.interval` (default 4m) 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. In Claude Code, `/pr-shepherd:monitor` uses `/loop` and continues working when your rate limit window is reset. In Codex, keep an active goal cycling the reusable command with a fresh 1-4 minute sleep before each rerun until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures).
 - 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.
@@ -279,7 +279,7 @@ Or ask Codex to use the `pr-shepherd` skill, for example: `run pr-shepherd until
 <runner> pr-shepherd 42
 ```
 
-For an active Codex goal, rerun that command every `watch.interval` (default 4m) until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures). `pr-shepherd iterate 42` remains supported for existing workflows. There is no background `/loop` scheduler in Codex.
+For an active Codex goal, rerun that command after picking a fresh 1-4 minute sleep until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures). `pr-shepherd iterate 42` remains supported for existing workflows. There is no background `/loop` scheduler in Codex.
 
 ### Without the plugin
 

package/bin/cli/fix-formatter.mjs

@@ -6,7 +6,6 @@ import { adaptFixCodeInstructions, numberInstructions } from "./iterate-instruct
 export function formatFixCodeResult(header, result, opts) {
     const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
-    const retryInterval = opts?.retryInterval;
     const runner = opts?.runner;
     const sections = [header];
     if (result.fix.threads.length > 0) {
@@ -118,7 +117,7 @@ export function formatFixCodeResult(header, result, opts) {
     }
     sections.push(postFixLines.join("\n"));
     sections.push("## Instructions");
-    sections.push(numberInstructions(adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, retryInterval, runner)));
+    sections.push(numberInstructions(adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, runner)));
     return joinSections(sections);
 }
 function blockquote(body) {

package/bin/cli/handlers.mjs

@@ -66,7 +66,6 @@ export async function handleIterate(args) {
     const projectionOpts = {
         runtime,
         readyDelaySuffix,
-        retryInterval: cfg.watch.interval,
         runner: cfg.cli?.runner,
     };
     if (globalOpts.format === "json") {

package/bin/cli/iterate-formatter.mjs

@@ -20,7 +20,6 @@ export function formatIterateResult(result, opts) {
     const verbose = opts?.verbose ?? false;
     const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
-    const retryInterval = opts?.retryInterval;
     const runner = opts?.runner;
     const heading = `# PR #${result.pr} [${result.action.toUpperCase()}]`;
     const reviewDecisionSeg = result.mergeStatus === "BLOCKED" && result.reviewDecision
@@ -57,37 +56,36 @@ export function formatIterateResult(result, opts) {
             return joinSections([
                 verbose ? header : heading,
                 adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner))}`,
             ]);
         case "wait":
             return joinSections([
                 header,
                 adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner))}`,
             ]);
         case "mark_ready":
             return joinSections([
                 header,
                 adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner))}`,
             ]);
         case "cancel":
             return joinSections([
                 [`${heading} — ${result.reason}`, "", baseLine, summaryLine].join("\n"),
                 adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner))}`,
             ]);
         case "escalate":
             return joinSections([
                 header,
                 result.escalate.humanMessage,
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner))}`,
+                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner))}`,
             ]);
         case "fix_code":
             return formatFixCodeResult(header, result, {
                 runtime,
                 readyDelaySuffix,
-                retryInterval,
                 runner,
             });
     }

package/bin/cli/iterate-instructions.mjs

@@ -1,28 +1,30 @@
 import { FIX_INSTRUCTION_END_ITERATION, FIX_INSTRUCTION_STOP_AFTER_PUSH, FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK, } from "../commands/iterate/render.mjs";
 import { buildPrShepherdCommand } from "./runner.mjs";
-const DEFAULT_CODEX_RETRY_INTERVAL = "4m";
-const VALID_RETRY_INTERVAL = /^\d+[smhd]$/;
 const CLAUDE_DYNAMIC_WAKEUP = "Schedule the next dynamic wakeup with `ScheduleWakeup` using `delaySeconds` between 60 and 240 and the same loop prompt (skip if running under a fixed-interval cron loop — the next scheduled fire handles it), then end this iteration.";
-export function buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner) {
+const CODEX_DYNAMIC_WAIT = "pick a fresh sleep/timeout between 1 and 4 minutes, wait that long";
+function capitalizeFirst(value) {
+    return `${value.charAt(0).toUpperCase()}${value.slice(1)}`;
+}
+export function buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner) {
     const rerunCommand = buildCodexIterateCommand(result.pr, readyDelaySuffix, runner);
-    const retryDelay = buildCodexRetryDelay(retryInterval);
+    const retryDelay = buildCodexRetryDelay();
     switch (result.action) {
         case "cooldown":
             return [
                 runtime === "codex"
-                    ? `Continue the active Codex goal — wait about ${retryDelay}, then rerun \`${rerunCommand}\` after CI starts reporting.`
+                    ? `Continue the active Codex goal — ${retryDelay}, then rerun \`${rerunCommand}\` after CI starts reporting.`
                     : `CI still needs time to start reporting. ${CLAUDE_DYNAMIC_WAKEUP}`,
             ];
         case "wait":
             return [
                 runtime === "codex"
-                    ? `Continue the active Codex goal — wait about ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`
+                    ? `Continue the active Codex goal — ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`
                     : CLAUDE_DYNAMIC_WAKEUP,
             ];
         case "mark_ready":
             return [
                 runtime === "codex"
-                    ? `The CLI already marked the PR ready for review. Continue the active Codex goal until the ready-delay completes — wait about ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`
+                    ? `The CLI already marked the PR ready for review. Continue the active Codex goal until the ready-delay completes — ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`
                     : `The CLI already marked the PR ready for review. ${CLAUDE_DYNAMIC_WAKEUP}`,
             ];
         case "cancel":
@@ -41,18 +43,18 @@ export function buildSimpleIterateInstructions(result, runtime, readyDelaySuffix
             ];
     }
 }
-export function adaptFixCodeInstructions(instructions, pr, runtime, readyDelaySuffix, retryInterval, runner) {
+export function adaptFixCodeInstructions(instructions, pr, runtime, readyDelaySuffix, runner) {
     if (runtime !== "codex")
         return instructions;
     const rerunCommand = buildCodexIterateCommand(pr, readyDelaySuffix, runner);
-    const retryDelay = buildCodexRetryDelay(retryInterval);
+    const retryDelay = buildCodexRetryDelay();
     return instructions.map((instruction) => {
         if (instruction === FIX_INSTRUCTION_STOP_AFTER_PUSH) {
-            return `Continue the active Codex goal — CI needs time to run on the new push. Wait about ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`;
+            return `Continue the active Codex goal — CI needs time to run on the new push. ${capitalizeFirst(retryDelay)}, then rerun \`${rerunCommand}\` to recheck.`;
         }
         if (instruction === FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK ||
             instruction === FIX_INSTRUCTION_END_ITERATION) {
-            return `Continue the active Codex goal — wait about ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`;
+            return `Continue the active Codex goal — ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`;
         }
         return instruction;
     });
@@ -68,11 +70,8 @@ export function buildCodexIterateCommand(pr, readyDelaySuffix, runner) {
         runner,
     }).text;
 }
-export function buildCodexRetryDelay(retryInterval) {
-    const interval = typeof retryInterval === "string" ? retryInterval.trim() : "";
-    return VALID_RETRY_INTERVAL.test(interval)
-        ? `the configured interval (${interval})`
-        : `the configured interval (default ${DEFAULT_CODEX_RETRY_INTERVAL})`;
+export function buildCodexRetryDelay() {
+    return CODEX_DYNAMIC_WAIT;
 }
 export function numberInstructions(instructions) {
     return instructions.map((instruction, i) => `${i + 1}. ${instruction}`).join("\n");

package/bin/cli/iterate-lean.mjs

@@ -7,9 +7,8 @@ import { adaptIterateLog, adaptFixCodeInstructions, buildSimpleIterateInstructio
 export function projectIterateLean(result, opts) {
     const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
-    const retryInterval = opts?.retryInterval;
     const runner = opts?.runner;
-    const simpleInstructions = (r) => buildSimpleIterateInstructions(r, runtime, readyDelaySuffix, retryInterval, runner);
+    const simpleInstructions = (r) => buildSimpleIterateInstructions(r, runtime, readyDelaySuffix, runner);
     const base = {
         action: result.action,
         pr: result.pr,
@@ -102,7 +101,7 @@ export function projectIterateLean(result, opts) {
                     }),
                     resolveCommand: result.fix.resolveCommand,
                     ...(result.fix.instructions.length > 0 && {
-                        instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, retryInterval, runner),
+                        instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, runner),
                     }),
                 },
             };
@@ -134,14 +133,13 @@ export function projectIterateLean(result, opts) {
 export function projectIterateVerbose(result, opts) {
     const runtime = opts?.runtime ?? "claude";
     const readyDelaySuffix = opts?.readyDelaySuffix;
-    const retryInterval = opts?.retryInterval;
     const runner = opts?.runner;
     if (result.action === "fix_code") {
         return {
             ...result,
             fix: {
                 ...result.fix,
-                instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, retryInterval, runner),
+                instructions: adaptFixCodeInstructions(result.fix.instructions, result.pr, runtime, readyDelaySuffix, runner),
             },
         };
     }
@@ -151,6 +149,6 @@ export function projectIterateVerbose(result, opts) {
     return {
         ...result,
         ...log,
-        instructions: buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, retryInterval, runner),
+        instructions: buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner),
     };
 }

package/bin/commands/iterate/render.mjs

@@ -1,5 +1,6 @@
 import { buildPrShepherdCommand, renderShellCommand } from "../../cli/runner.mjs";
 import { buildFailingCheckInstructions } from "./check-instructions.mjs";
+import { SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS, buildShepherdJournalInstruction, } from "../shepherd-journal.mjs";
 export const FIX_INSTRUCTION_STOP_AFTER_PUSH = "Stop this iteration — CI needs time to run on the new push before the next tick.";
 export const FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK = "Stop this iteration before the next tick.";
 export const FIX_INSTRUCTION_END_ITERATION = "End this iteration.";
@@ -68,7 +69,7 @@ export function buildFixInstructions(threads, actionableComments, checks, review
         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) {
-        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.`);
+        instructions.push(SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE);
     }
     const editedTotal = editedSummaries.length +
         firstLookThreads.filter((t) => t.edited).length +
@@ -91,7 +92,7 @@ export function buildFixInstructions(threads, actionableComments, checks, review
         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.`);
     }
     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.`);
+        instructions.push(buildShepherdJournalInstruction(prNumber, SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS));
     }
     if (needsPush) {
         instructions.push(FIX_INSTRUCTION_STOP_AFTER_PUSH);

package/bin/commands/monitor.mjs

@@ -20,7 +20,7 @@ export async function runMonitor(opts) {
     const loopTag = `#pr-shepherd-loop:pr=${prNumber}:`;
     const loopArgs = interval;
     const reusableCommand = buildIterateCommand(prNumber, opts.readyDelaySuffix, config.cli?.runner);
-    const loopPrompt = buildLoopPrompt(prNumber, loopTag, reusableCommand, loopArgs, opts.runtime ?? "claude", config.cli?.runner);
+    const loopPrompt = buildLoopPrompt(prNumber, loopTag, reusableCommand, opts.runtime ?? "claude", config.cli?.runner);
     return {
         prNumber,
         loopTag,
@@ -40,8 +40,10 @@ export function formatMonitorResult(result, opts) {
             `# PR #${prNumber} [MONITOR]`,
             "",
             `Loop tag: \`${loopTag}\``,
-            `Loop args: \`${loopArgs}\``,
-        ].join("\n"),
+            runtime === "codex" ? null : `Loop args: \`${loopArgs}\``,
+        ]
+            .filter((line) => line !== null)
+            .join("\n"),
         runtime === "codex" ? `Reusable command: \`${result.reusableCommand}\`` : null,
         "## Loop prompt",
         loopPrompt,
@@ -54,10 +56,20 @@ export function formatMonitorResult(result, opts) {
 }
 export function formatMonitorJson(result, opts) {
     const runtime = opts?.runtime ?? "claude";
-    const { reusableCommand, ...base } = result;
+    if (runtime === "codex") {
+        return {
+            prNumber: result.prNumber,
+            loopTag: result.loopTag,
+            loopPrompt: result.loopPrompt,
+            reusableCommand: result.reusableCommand,
+            instructions: buildMonitorInstructions(result, runtime),
+        };
+    }
     return {
-        ...base,
-        ...(runtime === "codex" && { reusableCommand }),
+        prNumber: result.prNumber,
+        loopTag: result.loopTag,
+        loopArgs: result.loopArgs,
+        loopPrompt: result.loopPrompt,
         instructions: buildMonitorInstructions(result, runtime),
     };
 }
@@ -77,14 +89,14 @@ function buildIterateCommand(prNumber, readyDelaySuffix, runner) {
     const validatedDelay = validateReadyDelaySuffix(readyDelaySuffix);
     return buildPrShepherdCommand([String(prNumber), ...(validatedDelay ? ["--ready-delay", validatedDelay] : [])], { runner }).text;
 }
-function buildLoopPrompt(prNumber, loopTag, iterateCmd, loopArgs, runtime = "claude", runner) {
+function buildLoopPrompt(prNumber, loopTag, iterateCmd, runtime = "claude", runner) {
     if (runtime === "codex") {
         return [
             loopTag,
             "",
             "**IMPORTANT — Codex recurrence rules:**",
             "- Run the command below once and follow its `## Instructions` exactly.",
-            `- If the output tells you to continue the active Codex goal, wait about the configured interval (${loopArgs}) and rerun the reusable command from the monitor output.`,
+            "- If the output tells you to continue the active Codex goal, pick a fresh sleep/timeout between 1 and 4 minutes, wait that long, and rerun the reusable command from the monitor output.",
             "- Stop only when Shepherd emits `[CANCEL]` because the ready-delay completed or the PR was merged/closed, or when Shepherd emits `[ESCALATE]` (including `stall-timeout` for repeated unchanged CI failures).",
             `- Do not call \`/loop\`, \`ScheduleWakeup\`, \`CronCreate\`, or \`${buildPrShepherdCommand(["monitor", String(prNumber)], { runner }).text}\`; Codex recurrence is explicit \`iterate\` command cycles.`,
             "",
@@ -117,7 +129,7 @@ function buildMonitorInstructions(result, runtime) {
     if (runtime === "codex") {
         return [
             "Run the `## Loop prompt` body once inline now.",
-            `For an active Codex goal, keep cycling with \`${result.reusableCommand}\` about every configured interval (${result.loopArgs}) until a terminal condition is reached. Codex does not create a \`/loop\` monitor.`,
+            `For an active Codex goal, keep cycling with \`${result.reusableCommand}\` by picking a fresh sleep/timeout between 1 and 4 minutes before each rerun until a terminal condition is reached. Codex does not create a \`/loop\` monitor.`,
         ];
     }
     return [

package/bin/commands/resolve-instructions.mjs

@@ -1,4 +1,5 @@
 import { buildPrShepherdCommand } from "../cli/runner.mjs";
+import { SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEMS, buildShepherdJournalInstruction, } from "./shepherd-journal.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
@@ -64,7 +65,7 @@ export function buildFetchInstructions(prNumber, result, runner) {
         runner,
     }).text} [--resolve-thread-ids <ids>] [--minimize-comment-ids <ids>] [--dismiss-review-ids <ids> --message "<reason>"]`;
     instructions.push(`Run \`${resolveCommand}\` with only the non-empty flag subsets. Skip the command entirely if all three ID lists are empty.${requireShaHint}${dismissNote}`);
-    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 each item's bullet above; for reviews, reference the review ID.`);
+    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;
 }

package/bin/commands/shepherd-journal.mjs

@@ -0,0 +1,13 @@
+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 — 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 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.`,
+        itemReferenceGuidance,
+        SHEPHERD_JOURNAL_APPEND_HINT,
+    ].join(" ");
+}
+export const SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS = "For threads and comments, use the markdown link shown in its heading above; for reviews, reference the review ID.";
+export const SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEMS = "For threads and comments, use the markdown link shown in each item's bullet above; for reviews, reference the review ID.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.15.0",
+  "version": "0.15.2",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -29,7 +29,7 @@
     "@types/node": "^25.6.0",
     "@vitest/coverage-v8": "^4.1.4",
     "husky": "^9.1.7",
-    "oxfmt": "^0.47.0",
+    "oxfmt": "^0.48.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.15.0",
+  "version": "0.15.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

@@ -1,6 +1,6 @@
 ---
 name: pr-shepherd
-description: 'Codex-only skill for checking, updating, monitoring, or resolving a GitHub pull request with pr-shepherd. Use for requests like "check this PR", "use pr-shepherd", "iterate PR #123", "resolve this PR''s comments", or "run pr-shepherd until this PR is ready". For open-ended requests, create a Codex goal and run explicit pr-shepherd cycles through the target repo package runner, picking a fresh sleep/timeout between 1 and 4 minutes before each rerun until Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or `[ESCALATE]` including repeated unchanged CI failures.'
+description: 'Codex-only skill for iterating a GitHub pull request to completion with pr-shepherd. Use for requests like "use pr-shepherd", "iterate PR #123", or "run pr-shepherd until this PR is ready".'
 ---
 
 # pr-shepherd
@@ -16,10 +16,8 @@ Codex-only workflow for getting actionable PR updates from `pr-shepherd`.
      `gh pr view --json number --jq .number`
    - If no PR is found, report that and stop.
 
-2. Decide whether this is one cycle or an open-ended goal.
-   - For one-off requests such as "check this PR", "run pr-shepherd once", or "resolve this PR's comments", run one explicit CLI command.
-   - For requests such as "continue", "until ready", "until this PR is ready", or "keep iterating", create a Codex goal before the first recurring cycle with this objective:
-     `Run pr-shepherd PR_NUMBER cycles through the target repo package runner, picking a fresh sleep/timeout between 1 and 4 minutes before each rerun, until Shepherd emits [CANCEL] for ready-delay completion or PR #PR_NUMBER is merged/closed, or pr-shepherd escalates, including repeated unchanged CI failures.`
+2. Use this objective for the whole goal:
+   - `Run pr-shepherd PR_NUMBER cycles through the target repo package runner, picking a fresh sleep/timeout between 1 and 4 minutes before each rerun, until Shepherd emits [CANCEL] for ready-delay completion or PR #PR_NUMBER is merged/closed, or pr-shepherd escalates, including repeated unchanged CI failures.`
 
 3. Select the package runner from the target repository root.
    - Prefer `package.json` `packageManager`: `pnpm@...` -> `pnpm exec`, `yarn@...` -> `yarn run`, `npm@...` -> `npx --no-install`.
@@ -32,24 +30,14 @@ Codex-only workflow for getting actionable PR updates from `pr-shepherd`.
    - In other repositories, run through the selected package runner so Codex does not install packages implicitly. If the package is missing, tell the user to install `pr-shepherd` with the matching dev-dependency command: `pnpm add -D pr-shepherd`, `yarn add -D pr-shepherd`, or `npm install --save-dev pr-shepherd`.
 
 5. Run the appropriate command from the repository root.
-   - For a status check:
-     `<runner> pr-shepherd check PR_NUMBER`
-   - For review comment resolution:
-     `<runner> pr-shepherd resolve PR_NUMBER --fetch`
-   - For a monitor bootstrap:
-     `<runner> pr-shepherd monitor PR_NUMBER`
-   - For the recurring explicit monitor tick:
-     `<runner> pr-shepherd PR_NUMBER`
-   - `pr-shepherd iterate PR_NUMBER` remains supported as a legacy alias, but use the default `pr-shepherd PR_NUMBER` form for recurring Codex cycles.
+   - `<runner> pr-shepherd PR_NUMBER`
 
 6. Print or summarize the important status, then follow the output's `## Instructions` exactly.
 
-7. Do not call `/loop`, `ScheduleWakeup`, `CronCreate`, or `pr-shepherd monitor` for recurrence. Codex does explicit `pr-shepherd PR_NUMBER` cycles.
+7. If the output indicates continuation, pick a fresh sleep/timeout between 1 and 4 minutes, wait that long, and run another explicit `<runner> pr-shepherd PR_NUMBER` cycle through the same runner.
 
-8. For open-ended goal requests, complete the CLI-provided instructions for the current cycle. If the output says to continue the active Codex goal, pick a fresh sleep/timeout between 1 and 4 minutes, wait that long, and run another explicit `pr-shepherd PR_NUMBER` cycle through the same runner.
+8. Do not stop on `[WAIT]`, `[COOLDOWN]`, `[MARK_READY]`, or post-fix CI wait states. These are nonterminal Codex recurrence states.
 
-9. Do not stop an open-ended goal only because the output is `[WAIT]`, `[COOLDOWN]`, `[MARK_READY]`, or a post-fix CI wait. These are nonterminal Codex recurrence states.
+9. Stop only when Shepherd emits `[CANCEL]` for ready-delay completion or PR #PR_NUMBER is merged/closed, or when it emits `[ESCALATE]`, including `stall-timeout` for repeated unchanged CI failures.
 
-10. Stop only when Shepherd emits `[CANCEL]` for ready-delay completion or merged/closed, or when it emits `[ESCALATE]`, including `stall-timeout` for repeated unchanged CI failures. If a Codex goal is active, mark it complete only when one of those terminal conditions is actually satisfied.
-
-11. If the output includes fixes, pushes, rebases, or resolve commands, perform only the instructed scoped actions. Do not resolve, minimize, or dismiss comments until the CLI-provided post-push and `--require-sha` instructions are satisfied.
+10. If the output includes fixes, pushes, rebases, or resolve commands, perform only the instructed scoped actions. Do not resolve, minimize, or dismiss comments until the CLI-provided post-push and `--require-sha` instructions are satisfied.