pr-shepherd 0.15.2 → 0.16.1

package/bin/commands/resolve-instructions.mjs

@@ -1,5 +1,6 @@
 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
@@ -32,16 +33,7 @@ export function buildFetchInstructions(prNumber, result, runner) {
         instructions.push(`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) {
-        const commitSuggestionCommand = buildPrShepherdCommand([
-            "commit-suggestion",
-            String(prNumber),
-            "--thread-id",
-            "<id>",
-            "--message",
-            "<one-sentence headline>",
-            "--format=json",
-        ], { runner }).text;
-        instructions.push(`For each Actionable thread marked \`[suggestion]\` in \`## Actionable Review Threads\` above: run \`${commitSuggestionCommand}\` to retrieve the patch and suggested commit. The CLI does not mutate the working tree — apply the patch yourself (run \`git apply\` with the diff shown, or edit the file directly using the line range), then stage the listed file and run the suggested \`git commit\` from the \`## Instructions\` section. Include the thread ID in \`--resolve-thread-ids\` in the resolve command below (the thread is not auto-resolved). If the patch fails to apply (drift since the suggestion was written), fall through to the manual fix step. Do not retry the same \`commit-suggestion\` invocation.`);
+        instructions.push(buildCommitSuggestionInstruction(prNumber, "## Actionable Review Threads", true, runner));
     }
     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.`);

package/bin/commands/resolve-mutate.mjs

@@ -0,0 +1,16 @@
+import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
+import { applyResolveOptions } from "../comments/resolve.mjs";
+export async function runResolveMutate(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.");
+    }
+    return applyResolveOptions(prNumber, repo, {
+        resolveThreadIds: opts.resolveThreadIds,
+        minimizeCommentIds: opts.minimizeCommentIds,
+        dismissReviewIds: opts.dismissReviewIds,
+        dismissMessage: opts.dismissMessage,
+        requireSha: opts.requireSha,
+    });
+}

package/bin/commands/resolve.mjs

@@ -1,11 +1,13 @@
 import { getRepoInfo, getCurrentPrNumber } from "../github/client.mjs";
 import { fetchPrBatch } from "../github/batch.mjs";
 import { getOutdatedThreads } from "../comments/outdated.mjs";
-import { autoResolveOutdated, applyResolveOptions } from "../comments/resolve.mjs";
+import { autoResolveOutdated } from "../comments/resolve.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";
+export { runResolveMutate } from "./resolve-mutate.mjs";
 export async function runResolveFetch(opts) {
     const repo = await getRepoInfo();
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
@@ -15,7 +17,6 @@ export async function runResolveFetch(opts) {
     const { data } = await fetchPrBatch(prNumber, repo);
     const stateKey = { owner: repo.owner, repo: repo.name, pr: prNumber };
     const unresolvedThreads = data.reviewThreads.filter((t) => !t.isResolved);
-    const visibleComments = data.comments.filter((c) => !c.isMinimized);
     const outdatedCandidates = data.reviewThreads.filter((t) => t.isOutdated);
     const resolvedCandidates = data.reviewThreads.filter((t) => t.isResolved && !t.isOutdated);
     const minimizedThreadCandidates = data.reviewThreads.filter((t) => t.isMinimized && !t.isResolved && !t.isOutdated);
@@ -70,6 +71,7 @@ export async function runResolveFetch(opts) {
     const activeThreads = unresolvedThreads.filter((t) => !t.isOutdated && !t.isMinimized);
     const resolutionOnlyThreads = unresolvedThreads.filter((t) => !autoResolvedIds.has(t.id) && (t.isOutdated || t.isMinimized));
     const cfg = loadConfig();
+    const visibleCommentClassification = classifyVisibleComments(data.comments, seenMap, cfg.iterate?.minimizeComments);
     const actionableThreads = activeThreads.map(({ isResolved: _r, isOutdated: _o, ...rest }) => {
         const thread = rest;
         const suggestion = extractSuggestion(rest);
@@ -114,13 +116,14 @@ export async function runResolveFetch(opts) {
     await Promise.allSettled([
         ...firstLookThreads.map((t) => markSeen(stateKey, t.id, t.body)),
         ...firstLookComments.map((c) => markSeen(stateKey, c.id, c.body)),
+        ...visibleCommentClassification.toMarkSeen.map((c) => markSeen(stateKey, c.id, c.body)),
     ]);
     const result = {
         prNumber,
         actionableThreads,
         resolutionOnlyThreads,
         firstLookThreads,
-        actionableComments: visibleComments,
+        actionableComments: visibleCommentClassification.actionable,
         firstLookComments,
         changesRequestedReviews: data.changesRequestedReviews,
         reviewSummaries: cfg.resolve.fetchReviewSummaries ? data.reviewSummaries : [],
@@ -128,17 +131,3 @@ export async function runResolveFetch(opts) {
     };
     return { ...result, instructions: buildFetchInstructions(prNumber, result, cfg.cli?.runner) };
 }
-export async function runResolveMutate(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.");
-    }
-    return applyResolveOptions(prNumber, repo, {
-        resolveThreadIds: opts.resolveThreadIds,
-        minimizeCommentIds: opts.minimizeCommentIds,
-        dismissReviewIds: opts.dismissReviewIds,
-        dismissMessage: opts.dismissMessage,
-        requireSha: opts.requireSha,
-    });
-}

package/bin/commands/shepherd-journal.mjs

@@ -1,7 +1,7 @@
 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 const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review the bodies shown under `## Review summaries (first look)` — you are seeing these for the first time. Any IDs eligible for minimization 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.`,

package/bin/comments/minimize-policy.mjs

@@ -0,0 +1,15 @@
+export function shouldMinimizeAuthor(authorType, policy) {
+    switch (policy) {
+        case undefined:
+        case "all":
+            return true;
+        case "bots":
+            return authorType === "Bot";
+        case "users":
+            return authorType === "User";
+        case "none":
+            return false;
+        default:
+            throw new Error(`Invalid minimizeComments policy: ${String(policy)}`);
+    }
+}

package/bin/comments/visible-comments.mjs

@@ -0,0 +1,20 @@
+import { shouldMinimizeAuthor } from "./minimize-policy.mjs";
+import { classifyItem } from "../state/seen-comments.mjs";
+export function classifyVisibleComments(comments, seenMap, minimizeComments) {
+    const actionable = [];
+    const minimizeIds = [];
+    const toMarkSeen = [];
+    for (const c of comments.filter((comment) => !comment.isMinimized)) {
+        if (shouldMinimizeAuthor(c.authorType, minimizeComments)) {
+            actionable.push(c);
+            minimizeIds.push(c.id);
+            continue;
+        }
+        const cls = classifyItem(c.id, c.body, seenMap);
+        if (cls === "unchanged")
+            continue;
+        actionable.push(c);
+        toMarkSeen.push(c);
+    }
+    return { actionable, minimizeIds, toMarkSeen };
+}

package/bin/config/load.mjs

@@ -4,6 +4,7 @@ import { homedir } from "node:os";
 import { parse } from "yaml";
 import builtins from "../config.json" with { type: "json" };
 import { parseCliRunner } from "../cli/runner.mjs";
+const MINIMIZE_COMMENTS_POLICIES = ["all", "bots", "users", "none"];
 const RC_FILENAME = ".pr-shepherdrc.yml";
 function findRcFile(startDir) {
     const home = homedir();
@@ -37,6 +38,14 @@ function deepMerge(base, override) {
     }
     return result;
 }
+function isMinimizeCommentsPolicy(value) {
+    return MINIMIZE_COMMENTS_POLICIES.some((policy) => policy === value);
+}
+function parseMinimizeCommentsPolicy(value) {
+    if (isMinimizeCommentsPolicy(value))
+        return value;
+    throw new Error(`Invalid config: iterate.minimizeComments must be one of "all", "bots", "users", or "none", got ${JSON.stringify(value)}`);
+}
 const defaults = builtins;
 const configCache = new Map();
 export function loadConfig() {
@@ -58,9 +67,7 @@ export function loadConfig() {
             throw new Error(`Invalid config: cli must be a plain object, got ${JSON.stringify(config.cli)}`);
         }
         config.cli.runner = parseCliRunner(config.cli.runner);
-        if (typeof config.watch?.interval !== "string" || !/^\d+[smhd]$/.test(config.watch.interval)) {
-            throw new Error(`Invalid config: watch.interval must be a duration string like "4m" or "1h", got ${JSON.stringify(config.watch?.interval)}`);
-        }
+        config.iterate.minimizeComments = parseMinimizeCommentsPolicy(config.iterate.minimizeComments);
         configCache.set(cwd, config);
         return config;
     }

package/bin/config.json

@@ -3,13 +3,12 @@
     "runner": "auto"
   },
   "iterate": {
-    "cooldownSeconds": 30,
     "fixAttemptsPerThread": 3,
     "stallTimeoutMinutes": 30,
-    "minimizeApprovals": false
+    "minimizeApprovals": false,
+    "minimizeComments": "all"
   },
   "watch": {
-    "interval": "4m",
     "readyDelayMinutes": 10
   },
   "resolve": {

package/bin/github/batch-parsers.mjs

@@ -18,6 +18,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
             line: comment?.line ?? null,
             startLine: comment?.startLine ?? null,
             author: comment?.author?.login ?? "unknown",
+            authorType: mapAuthorType(comment?.author?.__typename),
             body: comment?.body ?? "",
             url: comment?.url ?? "",
             createdAtUnix: comment ? parseCreatedAt(comment.createdAt) : 0,
@@ -27,6 +28,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         id: c.id,
         isMinimized: c.isMinimized,
         author: c.author?.login ?? "unknown",
+        authorType: mapAuthorType(c.author?.__typename),
         body: c.body,
         url: c.url,
         createdAtUnix: parseCreatedAt(c.createdAt),
@@ -34,6 +36,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
     const changesRequestedReviews = rawReviewNodes.map((r) => ({
         id: r.id,
         author: r.author?.login ?? "unknown",
+        authorType: mapAuthorType(r.author?.__typename),
         body: r.body,
     }));
     const reviewSummaries = rawReviewSummaryNodes
@@ -41,6 +44,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         .map((r) => ({
         id: r.id,
         author: r.author?.login ?? "unknown",
+        authorType: mapAuthorType(r.author?.__typename),
         body: r.body,
     }));
     // APPROVED reviews often have empty bodies (clicking "Approve" without a comment), so
@@ -51,6 +55,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         .map((r) => ({
         id: r.id,
         author: r.author?.login ?? "unknown",
+        authorType: mapAuthorType(r.author?.__typename),
         body: r.body,
     }));
     const checks = rawCheckNodes.flatMap((node) => {
@@ -109,6 +114,11 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         checks,
     };
 }
+function mapAuthorType(typeName) {
+    if (typeName === "User" || typeName === "Bot")
+        return typeName;
+    return "Unknown";
+}
 function parseCreatedAt(iso) {
     const ms = new Date(iso).getTime();
     return Number.isFinite(ms) ? Math.floor(ms / 1000) : 0;

package/bin/github/gql/batch-pr.gql

@@ -43,6 +43,7 @@ query BatchPr(
       latestReviews(last: 100) {
         nodes {
           author {
+            __typename
             login
           }
           state
@@ -64,6 +65,7 @@ query BatchPr(
               isMinimized
               url
               author {
+                __typename
                 login
               }
               body
@@ -85,6 +87,7 @@ query BatchPr(
           isMinimized
           url
           author {
+            __typename
             login
           }
           body
@@ -103,6 +106,7 @@ query BatchPr(
         nodes {
           id
           author {
+            __typename
             login
           }
           body
@@ -117,6 +121,7 @@ query BatchPr(
           id
           isMinimized
           author {
+            __typename
             login
           }
           body
@@ -131,6 +136,7 @@ query BatchPr(
           id
           isMinimized
           author {
+            __typename
             login
           }
           body

package/bin/github/queries.mjs

@@ -13,8 +13,6 @@ const gql = (name) => readFileSync(join(import.meta.dirname, "gql", name), "utf8
 export const BATCH_PR_QUERY = gql("batch-pr.gql");
 /** Returns the current head commit SHA for a PR. Used by waitForSha polling. */
 export const GET_PR_HEAD_SHA_QUERY = gql("get-pr-head-sha.gql");
-/** Paginated follow-up for `shepherd status` — used when reviewThreads is truncated (totalCount > 100). */
-export const MULTI_PR_STATUS_QUERY_WITH_CURSOR = gql("multi-pr-status-paged.gql");
 /** Look up PR number by branch name (for getCurrentPrNumber). */
 export const PR_NUMBER_BY_BRANCH_QUERY = gql("pr-number-by-branch.gql");
 /** Convert a draft PR to ready for review. */

package/bin/index.mjs

@@ -4,10 +4,8 @@
  *
  * Usage:
  *   pr-shepherd [PR]
- *   pr-shepherd check [PR]
  *   pr-shepherd resolve [PR]
  *   pr-shepherd iterate [PR]
- *   pr-shepherd status PR1 [PR2 …]
  */
 import { main } from "./cli-parser.mjs";
 function formatCause(cause, seen = new Set(), depth = 0) {

package/bin/merge-status/derive.mjs

@@ -6,7 +6,7 @@
  *
  * Interpretation order for `status` — first match wins:
  *   1. mergeable == CONFLICTING       → CONFLICTS (hard conflict even for drafts)
- *   2. copilotReviewInProgress        → BLOCKED
+ *   2. blockingBotReviewInProgress        → BLOCKED
  *   3. mergeStateStatus DIRTY         → CONFLICTS (GitHub merge conflicts, even for drafts)
  *   4. isDraft                        → DRAFT
  *   5. mergeStateStatus BEHIND        → BEHIND
@@ -17,12 +17,12 @@
  */
 import { loadConfig } from "../config/load.mjs";
 export function deriveMergeStatus(pr) {
-    const copilotReviewInProgress = detectCopilotReview(pr);
+    const blockingBotReviewInProgress = detectBlockingBotReview(pr);
     let status;
     if (pr.mergeable === "CONFLICTING") {
         status = "CONFLICTS";
     }
-    else if (copilotReviewInProgress) {
+    else if (blockingBotReviewInProgress) {
         status = "BLOCKED";
     }
     else if (pr.mergeStateStatus === "DIRTY") {
@@ -53,14 +53,14 @@ export function deriveMergeStatus(pr) {
         isDraft: pr.isDraft,
         mergeable: pr.mergeable,
         reviewDecision: pr.reviewDecision,
-        copilotReviewInProgress,
+        blockingBotReviewInProgress,
         mergeStateStatus: pr.mergeStateStatus,
     };
 }
 // ---------------------------------------------------------------------------
-// Copilot review detection
+// Blocking bot review detection
 // ---------------------------------------------------------------------------
-function detectCopilotReview(pr) {
+function detectBlockingBotReview(pr) {
     // A blocking bot review is "in progress" when:
     //   1. Any reviewRequest has a login starting with one of the configured prefixes, OR
     //   2. Any latestReview has such a login AND state == "PENDING"

package/bin/reporters/agent.mjs

@@ -3,10 +3,10 @@
  *
  * These strip fields that are always-false by the time items reach iterate
  * (isResolved, isOutdated, isMinimized, createdAtUnix) and check metadata the
- * monitor prompt never reads (event, status, category).
+ * agent/iterate prompt never reads (event, status, category).
  * conclusion is preserved on AgentCheck so the formatter can branch on run-level conclusions.
  * detailsUrl is preserved in AgentCheck as a fallback for external status checks.
- * The original domain types are preserved for check command output.
+ * The original domain types are preserved as internal snapshot types.
  */
 import { extractSuggestion } from "../suggestions/extract.mjs";
 export function toAgentThread(t) {
@@ -19,13 +19,20 @@ export function toAgentThread(t) {
             t.startLine !== null &&
             t.startLine !== t.line && { startLine: t.startLine }),
         author: t.author,
+        ...(t.authorType !== undefined && { authorType: t.authorType }),
         body: t.body,
         url: t.url,
         ...(suggestion !== undefined && { suggestion }),
     };
 }
 export function toAgentComment(c) {
-    return { id: c.id, author: c.author, body: c.body, url: c.url };
+    return {
+        id: c.id,
+        author: c.author,
+        ...(c.authorType !== undefined && { authorType: c.authorType }),
+        body: c.body,
+        url: c.url,
+    };
 }
 export function toAgentCheck(c) {
     if (c.conclusion === "SKIPPED" || c.conclusion === "NEUTRAL") {

package/bin/state/iterate-stall.mjs

@@ -32,6 +32,15 @@ export async function readStallState(key) {
         return null;
     }
 }
+/** Clear stall state so the next invocation starts a fresh timer (fire-and-forget — never throws). */
+export async function clearStallState(key) {
+    try {
+        await unlink(resolvePath(key));
+    }
+    catch {
+        // Best-effort — file may not exist.
+    }
+}
 /** Write stall state (fire-and-forget — never throws). */
 export async function writeStallState(key, state) {
     let tmp;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.15.2",
+  "version": "0.16.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -10,7 +10,6 @@
   },
   "files": [
     "bin/**",
-    "plugin/**",
     "plugins/**",
     "plugins/**/.codex-plugin/**",
     ".claude-plugin/**",
@@ -36,12 +35,12 @@
   },
   "scripts": {
     "build": "node scripts/build.mjs",
-    "prepare": "node scripts/install-husky.mjs && node scripts/install-plugin-symlink.mjs && npm run build",
+    "prepare": "node scripts/install-husky.mjs && npm run build",
     "prepublishOnly": "npm run typecheck && npm test && npm run build",
     "typecheck": "tsc --noEmit",
-    "lint": "oxlint src/ plugin/skills/ plugins/ .agents/plugins/",
-    "format": "oxfmt src/ plugin/skills/ plugins/ .agents/plugins/ docs/ README.md",
-    "format:check": "oxfmt --check src/ plugin/skills/ plugins/ .agents/plugins/ docs/ README.md",
+    "lint": "oxlint src/ plugins/ .agents/plugins/",
+    "format": "oxfmt src/ plugins/ .agents/plugins/ docs/ README.md",
+    "format:check": "oxfmt --check src/ plugins/ .agents/plugins/ docs/ README.md",
     "test": "vitest run",
     "test:coverage": "vitest run --coverage",
     "test:watch": "vitest"

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

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.15.2",
+  "version": "0.16.1",
   "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,43 +1,48 @@
 ---
 name: pr-shepherd
-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".'
+description: 'Iterate 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".'
+user-invocable: true
+argument-hint: "[PR number or URL]"
+allowed-tools: ["Bash", "Read", "Grep", "Edit", "Write", "Glob", "Skill"]
 ---
 
 # pr-shepherd
 
-Codex-only workflow for getting actionable PR updates from `pr-shepherd`.
+One-tick dispatcher for iterating a PR to completion.
 
-## Workflow
+## Arguments: $ARGUMENTS
 
-1. Resolve the PR number.
-   - If the user provides a PR number, use it.
-   - If the user provides a GitHub PR URL, extract the PR number.
-   - If no PR is provided, infer it from the current branch with:
-     `gh pr view --json number --jq .number`
-   - If no PR is found, report that and stop.
+## Steps
 
-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.`
+1. **Resolve PR number:**
+   - If `$ARGUMENTS` contains a PR number, use it.
+   - If `$ARGUMENTS` contains a GitHub PR URL, extract the number.
+   - Otherwise, infer: `gh pr view --json number --jq .number`
+   - If no PR found, report an error and stop.
 
-3. Select the package runner from the target repository root.
-   - Prefer `package.json` `packageManager`: `pnpm@...` -> `pnpm exec`, `yarn@...` -> `yarn run`, `npm@...` -> `npx --no-install`.
-   - If `packageManager` is absent, use lockfiles: `pnpm-lock.yaml` -> `pnpm exec`, `yarn.lock` -> `yarn run`, `package-lock.json` or no signal -> `npx --no-install`.
-   - Example: in `~/filaments`, use `pnpm exec pr-shepherd ...` because the root package declares `packageManager: "pnpm@..."` and has `pnpm-lock.yaml`.
+2. **Short-circuit if merged or closed:**
 
-4. Verify the CLI is available.
-   - Only when the target repository itself is the pr-shepherd source checkout, verify `bin/` and `node_modules/` exist before any local CLI invocation. If either is missing, run the source checkout's package-manager install command. This repository currently uses npm, so run:
-     `npm install`
-   - 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`.
+   ```bash
+   gh pr view <N> --json state --jq '.state'
+   ```
 
-5. Run the appropriate command from the repository root.
-   - `<runner> pr-shepherd PR_NUMBER`
+   If `MERGED` or `CLOSED`, output: `PR #N is already merged/closed. Nothing to do.` and stop.
 
-6. Print or summarize the important status, then follow the output's `## Instructions` exactly.
+3. **Select the package runner** from the target repository root:
+   - Prefer `package.json` `packageManager`: `pnpm@...` → `pnpm exec`, `yarn@...` → `yarn run`, `npm@...` → `npx`.
+   - If `packageManager` is absent, use lockfiles: `pnpm-lock.yaml` → `pnpm exec`, `yarn.lock` → `yarn run`, `package-lock.json` or no signal → `npx`.
 
-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.
+4. **Run one iterate tick:**
 
-8. Do not stop on `[WAIT]`, `[COOLDOWN]`, `[MARK_READY]`, or post-fix CI wait states. These are nonterminal Codex recurrence states.
+   If the package is missing in the target repository, 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`.
 
-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.
+   ```bash
+   <runner> pr-shepherd <N>
+   ```
 
-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.
+   Print the full output. Follow the `## Instructions` section exactly.
+
+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.

package/bin/commands/iterate.mjs

@@ -1,2 +0,0 @@
-export { runIterate } from "./iterate/index.mjs";
-export { FIX_INSTRUCTION_END_ITERATION, FIX_INSTRUCTION_STOP_AFTER_PUSH, FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK, renderResolveCommand, } from "./iterate/render.mjs";