pr-shepherd 0.15.1 → 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.1",
+  "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.
 ```
 

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/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.1",
+  "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.1",
+  "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.