pr-shepherd 0.15.2 → 0.16.0

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "pr-shepherd",
       "description": "Autonomous PR CI monitor and review-comment resolver",
-      "source": "./plugin",
+      "source": "./",
       "category": "productivity",
       "homepage": "https://github.com/jonathanong/pr-shepherd"
     }

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.2",
+  "version": "0.16.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"
@@ -10,5 +10,5 @@
   "repository": "https://github.com/jonathanong/pr-shepherd",
   "license": "MIT",
   "keywords": ["github", "pull-request", "ci", "code-review", "automation"],
-  "skills": "./plugin/skills/"
+  "skills": "./plugins/pr-shepherd/skills/"
 }

package/README.md

@@ -9,7 +9,7 @@ Example Workflow:
 2. Create a plan
 3. Accept the plan
 4. Switch to Auto Mode
-5. Prompt: `make a PR, then run /pr-shepherd:monitor`
+5. Prompt: `make a PR, then run /pr-shepherd:pr-shepherd`
 6. Agent makes a draft PR
 7. PR has passing CI -> draft is marked Ready for Review
 8. Review bots begin providing reviews
@@ -20,38 +20,9 @@ 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 adapts monitor instructions to the calling agent. Claude Code gets `/loop` bootstrap instructions. Codex is detected with `AGENT=codex` or the current Codex CLI signal `CODEX_CI=1`; it gets a reusable pr-shepherd command and explicit goal-friendly iterate instructions because Codex does not provide `/loop` scheduling in this workflow. Generated commands use `cli.runner` from `.pr-shepherdrc.yml`: `auto` (default), `npx`, `pnpm`, or `yarn`.
+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`.
 
-At a high level, to start the monitor, the skill/command invokes a CLI that returns a prompt to be ingested by the agent _(schematic — paraphrased for brevity; actual output is more detailed; examples use `npx` as the default spelling — a pnpm or yarn repo would emit `pnpm exec` or `yarn run` instead)_:
-
-```
-/pr-shepherd:monitor
-
-> npx pr-shepherd monitor 123
-
-# PR #123 [MONITOR]
-
-Loop tag: `#pr-shepherd-loop:pr=123:`
-
-## Loop prompt
-
-#pr-shepherd-loop:pr=123:
-
-**IMPORTANT — dynamic recurrence rules:** Do not invoke `/loop` again from inside
-this prompt. For nonterminal iterations, call `ScheduleWakeup` with `delaySeconds`
-between 60 and 240 and this same prompt body.
-
-Run in a single Bash call:
-  npx pr-shepherd 123
-
-…(self-dedup guidance, error-handling instructions)…
-
-## Instructions
-
-1. Invoke the /loop skill with the full ## Loop prompt body and no fixed interval.
-```
-
-Each iteration calls `pr-shepherd <PR>` through the selected package runner, which provides actionable feedback directly to the agent:
+At a high level, the skill invokes `pr-shepherd <PR>` through the selected package runner, which provides actionable feedback directly to the agent:
 
 ```
 > npx pr-shepherd 123
@@ -63,7 +34,7 @@ Each iteration calls `pr-shepherd <PR>` through the selected package runner, whi
 
 ## Review threads
 
-### `PRRT_kwDOSGizTs58XB1L` — `src/commands/iterate.mts:42` (@alice)
+### `PRRT_kwDOSGizTs58XB1L` — `src/commands/iterate/index.mts:42` (@alice)
 
 > The variable name is misleading.
 >
@@ -90,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. Stop this iteration.
+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.
 ```
 
 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:
@@ -126,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. 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).
+- 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).
 - 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.
@@ -141,57 +112,29 @@ Recommendations:
 
 ## Usage
 
-### Monitor a PR
+### Iterate a PR to completion
 
-In Claude Code, creates a fixed-interval loop (default every 4 minutes, configurable via `watch.interval`) that checks CI and review comments, fixes issues, and marks the PR ready for review when clean. The loop runs as a cron job that fires on schedule — agents end each turn cleanly and the cron fires again automatically. The loop stops automatically when the PR is merged or closed (auto-expires after 7 days).
+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]`.
 
-In Codex, run `pr-shepherd monitor <PR>` once through the repo package runner to emit the goal-friendly recurrence prompt, then follow that prompt. Its reusable follow-up command is emitted by the CLI.
-
-Claude Code:
+Claude Code (via `pr-shepherd` skill):
 
 ```
-/pr-shepherd:monitor                     # infer PR from current branch
-/pr-shepherd:monitor 42
-/pr-shepherd:monitor 42 --ready-delay 15m
+/pr-shepherd:pr-shepherd                  # infer PR from current branch
+/pr-shepherd:pr-shepherd 42
+/pr-shepherd:pr-shepherd 42 --ready-delay 15m
 ```
 
-Codex:
+Codex or direct CLI:
 
 ```sh
-npx pr-shepherd monitor                  # bootstrap from current branch, then follow its instructions
-npx pr-shepherd monitor 42               # bootstrap PR #42, then follow its instructions
-npx pr-shepherd 42                       # subsequent explicit check/action tick
+npx pr-shepherd 42
 npx pr-shepherd 42 --ready-delay 15m
 npx pr-shepherd iterate 42               # legacy-compatible spelling
 ```
 
-### Check a PR
-
-One-shot status snapshot — merge state, CI results, and unresolved comments.
-Accepts multiple PR numbers.
-
-```
-/pr-shepherd:check        # infer from branch
-/pr-shepherd:check 42
-/pr-shepherd:check 41 42 43
-```
-
-### Resolve review comments
-
-Fetches all actionable threads and comments, triages them, applies fixes,
-pushes, then resolves/minimizes/dismisses via `--require-sha` (waits until
-GitHub has seen the push before resolving).
-
-```
-/pr-shepherd:resolve       # infer from branch
-/pr-shepherd:resolve 42
-```
-
-See [docs/skills.md](docs/skills.md) for full argument reference.
-
 ## Iterate decision loop
 
-On each dynamic tick: fetch PR state in one GraphQL batch → classify CI, comments, and merge status → take one action (`fix_code`, `mark_ready`, `cancel`, `escalate`, `wait`, or `cooldown`). Claude and Codex both choose a fresh wait between 1 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`). 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.
 
 ## Install
 
@@ -222,11 +165,11 @@ Alternatively, install the Claude skills individually via `npx skills`:
 npx skills add jonathanong/pr-shepherd
 ```
 
-Installs the three skills (`check`, `monitor`, `resolve`) into your agent's skill directory (`.claude/skills/` for project scope, `~/.claude/skills/` with `-g` for global scope). Powered by [skills.sh](https://skills.sh).
+Installs the `pr-shepherd` skill into your agent's skill directory (`.claude/skills/` for project scope, `~/.claude/skills/` with `-g` for global scope). Powered by [skills.sh](https://skills.sh).
 
 ### Codex
 
-Codex uses the repo-shipped Codex plugin rather than the Claude plugin or `/pr-shepherd:*` slash commands. The plugin provides one umbrella `pr-shepherd` skill for check, resolve, monitor, and iterate workflows.
+Codex uses the repo-shipped Codex plugin rather than the Claude plugin or `/pr-shepherd:*` slash commands. The plugin provides one `pr-shepherd` skill for iterating a PR to completion.
 
 Install the Codex plugin marketplace from GitHub:
 
@@ -265,25 +208,15 @@ If your Codex environment does not already set `CODEX_CI=1`, set `AGENT=codex` s
 export AGENT=codex
 ```
 
-Then start a PR monitor from Codex with the target repository's package runner:
-
-```bash
-<runner> pr-shepherd monitor 42
-```
-
-For example, a repo like `~/filaments` that declares `packageManager: "pnpm@..."` and has `pnpm-lock.yaml` should use `pnpm exec pr-shepherd monitor 42`. For npm repos, use `npx --no-install pr-shepherd monitor 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 monitor bootstrap runs one tick and prints the reusable follow-up command, usually:
+Then iterate a PR from Codex with the target repository's package runner:
 
 ```bash
-<runner> pr-shepherd 42
+<runner> pr-shepherd iterate 42
 ```
 
-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
+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`.
 
-See [docs/custom-commands.md](docs/custom-commands.md) for a project-local slash command that wraps the CLI without the plugin.
+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.
 
 ### As a global CLI
 
@@ -297,7 +230,8 @@ Create a `.pr-shepherdrc.yml` in your project root (or any parent directory) to
 
 ```yaml
 iterate:
-  cooldownSeconds: 60 # wait longer after a push before reading CI
+  fixAttemptsPerThread: 5 # raise before escalating to manual review
+  minimizeComments: all # all | bots | users | none
 checks:
   ciTriggerEvents:
     - pull_request

package/bin/cli/args.mjs

@@ -7,7 +7,6 @@ import { parseArgs } from "node:util";
 const FLAGS_WITH_VALUES = new Set([
     "--format",
     "--ready-delay",
-    "--cooldown-seconds",
     "--stall-timeout",
     "--require-sha",
     "--message",

package/bin/cli/default-iterate.mjs

@@ -1,10 +1,5 @@
 import { parsePrNumber } from "./args.mjs";
-const DEFAULT_ITERATE_FLAGS_WITH_VALUES = new Set([
-    "--format",
-    "--ready-delay",
-    "--cooldown-seconds",
-    "--stall-timeout",
-]);
+const DEFAULT_ITERATE_FLAGS_WITH_VALUES = new Set(["--format", "--ready-delay", "--stall-timeout"]);
 const DEFAULT_ITERATE_BOOLEAN_FLAGS = new Set([
     "--verbose",
     "--no-auto-mark-ready",
@@ -48,7 +43,7 @@ function isDefaultIterateFlag(arg) {
 function writeDefaultUsageError(arg) {
     process.stderr.write(`Unknown subcommand: ${arg}\n`);
     process.stderr.write("Usage: pr-shepherd [PR] [options]\n" +
-        "       pr-shepherd <check|resolve|commit-suggestion|iterate|monitor|status|log-file> [options]\n" +
+        "       pr-shepherd <resolve|commit-suggestion|iterate|log-file> [options]\n" +
         "       pr-shepherd --version | -v\n");
     process.exitCode = 1;
 }

package/bin/cli/exit-codes.mjs

@@ -1,5 +1,4 @@
 import { loadConfig } from "../config/load.mjs";
-import { deriveVerdict } from "../commands/status.mjs";
 export function parseDurationToMinutes(s, defaultMinutes) {
     const m = /^(\d+)(m|min|minutes?|h|hours?)?$/.exec(s.trim());
     if (!m)
@@ -34,6 +33,3 @@ export function iterateActionToExitCode(action) {
             return 0;
     }
 }
-export function deriveSimpleReady(s) {
-    return deriveVerdict(s) === "READY";
-}

package/bin/cli/fix-formatter.mjs

@@ -1,7 +1,7 @@
-import { renderResolveCommand } from "../commands/iterate.mjs";
+import { renderResolveCommand } from "../commands/iterate/render.mjs";
 import { joinSections } from "../util/markdown.mjs";
 import { renderSuggestionBlock, renderLineRange } from "./suggestion-renderer.mjs";
-import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderFirstLookStatusTag, renderThreadResolutionStatusTag, } from "./list-formatters.mjs";
+import { renderThreadBullet, renderCommentBullet, renderReviewBullet, renderFirstLookStatusTag, renderThreadResolutionStatusTag, renderAuthor, } from "./list-formatters.mjs";
 import { adaptFixCodeInstructions, numberInstructions } from "./iterate-instructions.mjs";
 export function formatFixCodeResult(header, result, opts) {
     const runtime = opts?.runtime ?? "claude";
@@ -15,7 +15,7 @@ export function formatFixCodeResult(header, result, opts) {
             const loc = t.path ? `\`${t.path}:${lineLabel}\`` : "(no location)";
             const heading = t.url ? `[threadId=${t.id}](${t.url})` : `\`threadId=${t.id}\``;
             const suggestionMarker = t.suggestion ? " [suggestion]" : "";
-            sections.push(`### ${heading} — ${loc} (@${t.author})${suggestionMarker}`);
+            sections.push(`### ${heading} — ${loc} (${renderAuthor(t.author, t.authorType)})${suggestionMarker}`);
             sections.push(blockquote(t.body));
             if (t.suggestion) {
                 sections.push(renderSuggestionBlock(t.suggestion, ""));
@@ -32,7 +32,7 @@ export function formatFixCodeResult(header, result, opts) {
         sections.push("## Actionable comments");
         for (const c of result.fix.actionableComments) {
             const heading = c.url ? `[commentId=${c.id}](${c.url})` : `\`commentId=${c.id}\``;
-            sections.push(`### ${heading} (@${c.author})`);
+            sections.push(`### ${heading} (${renderAuthor(c.author, c.authorType)})`);
             sections.push(blockquote(c.body));
         }
     }
@@ -63,16 +63,16 @@ export function formatFixCodeResult(header, result, opts) {
         sections.push(result.fix.changesRequestedReviews.map((r) => renderReviewBullet(r)).join("\n"));
     }
     if (result.fix.firstLookSummaries.length > 0) {
-        sections.push("## Review summaries (first look — to be minimized)");
+        sections.push("## Review summaries (first look)");
         for (const r of result.fix.firstLookSummaries) {
-            sections.push(`### \`reviewId=${r.id}\` (@${r.author})`);
+            sections.push(`### \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType)})`);
             sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body));
         }
     }
     if (result.fix.editedSummaries.length > 0) {
         sections.push("## Review summaries (edited since first look — already minimized; do not re-minimize)");
         for (const r of result.fix.editedSummaries) {
-            sections.push(`### \`reviewId=${r.id}\` (@${r.author})`);
+            sections.push(`### \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType)})`);
             sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body));
         }
     }
@@ -85,7 +85,7 @@ export function formatFixCodeResult(header, result, opts) {
     if (result.fix.surfacedApprovals.length > 0) {
         sections.push("## Approvals (surfaced — not minimized)");
         for (const r of result.fix.surfacedApprovals) {
-            sections.push(`### \`reviewId=${r.id}\` (@${r.author})`);
+            sections.push(`### \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType)})`);
             sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body));
         }
     }

package/bin/cli/handlers.mjs

@@ -1,12 +1,9 @@
 import { runCommitSuggestion } from "../commands/commit-suggestion.mjs";
-import { runIterate } from "../commands/iterate.mjs";
-import { runMonitor, formatMonitorResult, formatMonitorJson } from "../commands/monitor.mjs";
-import { runStatus, formatStatusTable } from "../commands/status.mjs";
-import { getRepoInfo } from "../github/client.mjs";
+import { runIterate } from "../commands/iterate/index.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { detectAgentRuntime } from "../agent-runtime.mjs";
-import { parseCommonArgs, getFlag, hasFlag, parseStatusPrNumbers, parseIntStrict, } from "./args.mjs";
-import { parseDurationToMinutes, iterateActionToExitCode, deriveSimpleReady, } from "./exit-codes.mjs";
+import { parseCommonArgs, getFlag, hasFlag } from "./args.mjs";
+import { parseDurationToMinutes, iterateActionToExitCode } from "./exit-codes.mjs";
 import { formatCommitSuggestionResult, formatIterateResult, projectIterateLean, projectIterateVerbose, } from "./formatters.mjs";
 import { validateDurationFlag } from "./duration-flag.mjs";
 export async function handleCommitSuggestion(args) {
@@ -44,10 +41,6 @@ export async function handleIterate(args) {
         return;
     const cfg = loadConfig();
     const readyDelaySeconds = parseDurationToMinutes(readyDelaySuffix ?? "", cfg.watch.readyDelayMinutes) * 60;
-    const cooldownSecondsStr = getFlag(extra, "--cooldown-seconds");
-    const cooldownSeconds = cooldownSecondsStr
-        ? parseIntStrict(cooldownSecondsStr, "--cooldown-seconds")
-        : cfg.iterate.cooldownSeconds;
     const noAutoMarkReady = hasFlag(extra, "--no-auto-mark-ready");
     const noAutoCancelActionable = hasFlag(extra, "--no-auto-cancel-actionable");
     const stallTimeoutStr = getFlag(extra, "--stall-timeout");
@@ -58,7 +51,6 @@ export async function handleIterate(args) {
         ...globalOpts,
         prNumber,
         readyDelaySeconds,
-        cooldownSeconds,
         stallTimeoutSeconds,
         noAutoMarkReady,
         noAutoCancelActionable,
@@ -80,64 +72,3 @@ export async function handleIterate(args) {
     }
     process.exitCode = iterateActionToExitCode(result.action);
 }
-export async function handleMonitor(args) {
-    const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
-    const runtime = detectAgentRuntime();
-    const readyDelayStr = getFlag(extra, "--ready-delay");
-    const readyDelaySuffix = validateDurationFlag("pr-shepherd monitor", "--ready-delay", readyDelayStr, hasFlag(extra, "--ready-delay"));
-    if (readyDelaySuffix === null)
-        return;
-    const remaining = [];
-    for (let i = 0; i < extra.length; i++) {
-        const a = extra[i];
-        if (a === "--ready-delay") {
-            i++;
-            continue;
-        }
-        if (a.startsWith("--ready-delay="))
-            continue;
-        remaining.push(a);
-    }
-    const unknownFlags = remaining.filter((a) => a.startsWith("--"));
-    if (unknownFlags.length > 0) {
-        process.stderr.write(`pr-shepherd monitor: ignoring unknown flags: ${unknownFlags.join(" ")}\n`);
-    }
-    const unknownPositionals = remaining.filter((a) => !a.startsWith("--"));
-    if (unknownPositionals.length > 0) {
-        process.stderr.write(`pr-shepherd monitor: unexpected positional arguments ignored: ${unknownPositionals.join(" ")}\n`);
-    }
-    let result;
-    try {
-        result = await runMonitor({
-            ...globalOpts,
-            prNumber,
-            readyDelaySuffix: readyDelaySuffix ?? undefined,
-            runtime,
-        });
-    }
-    catch (err) {
-        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
-        process.exitCode = 1;
-        return;
-    }
-    process.stdout.write(globalOpts.format === "json"
-        ? `${JSON.stringify(formatMonitorJson(result, { runtime }), null, 2)}\n`
-        : `${formatMonitorResult(result, { runtime })}\n`);
-}
-export async function handleStatus(args) {
-    const { global: globalOpts } = parseCommonArgs(args);
-    const prNumbers = parseStatusPrNumbers(args);
-    if (prNumbers.length === 0) {
-        process.stderr.write("Usage: pr-shepherd status PR1 [PR2 …]\n");
-        process.exitCode = 1;
-        return;
-    }
-    const repo = await getRepoInfo();
-    const summaries = await runStatus({ ...globalOpts, prNumbers });
-    const output = globalOpts.format === "json"
-        ? JSON.stringify(summaries, null, 2)
-        : formatStatusTable(summaries, `${repo.owner}/${repo.name}`);
-    process.stdout.write(`${output}\n`);
-    const allReady = summaries.every((s) => deriveSimpleReady(s));
-    process.exitCode = allReady ? 0 : 1;
-}

package/bin/cli/iterate-formatter.mjs

@@ -4,17 +4,16 @@ import { adaptIterateLog, buildSimpleIterateInstructions, numberInstructions, }
 /**
  * Format an IterateResult as human-readable Markdown.
  *
- * Load-bearing conventions the monitor SKILL relies on:
+ * Load-bearing conventions the iterate skill relies on:
  *   1. The H1 heading on line 1 contains `[<ACTION>]` — the action tag identifies
  *      the output for logging and validation. Behavior is driven by `## Instructions`,
  *      not by dispatching on the tag.
- *   2. `[FIX_CODE]` uses the `rebase-and-push` variant: the `resolve` bullet under
- *      `## Post-fix push` wraps the resolve command in backticks — the SKILL
- *      extracts the backticked content for execution.
+ *   2. `[FIX_CODE]` wraps the `resolve` command under `## Post-fix push` in
+ *      backticks — the skill extracts the backticked content for execution.
  *   3. Every action ends with a `## Instructions` section — numbered `1.`, `2.`, … —
- *      that tells the monitor exactly what to do with this output. The section is
+ *      that tells the agent exactly what to do with this output. The section is
  *      unconditional: every action, every variant, always emits at least one step.
- *      The SKILL simply follows those steps; it does not need its own dispatch table.
+ *      The skill simply follows those steps; it does not need its own dispatch table.
  */
 export function formatIterateResult(result, opts) {
     const verbose = opts?.verbose ?? false;
@@ -28,7 +27,7 @@ export function formatIterateResult(result, opts) {
     const baseLine = `**status** \`${result.status}\` · **merge** \`${result.mergeStateStatus}\`${reviewDecisionSeg} · **state** \`${result.state}\` · **repo** \`${result.repo}\``;
     let summaryLine;
     if (verbose) {
-        summaryLine = `**summary** ${result.summary.passing} passing, ${result.summary.skipped} skipped, ${result.summary.filtered} filtered, ${result.summary.inProgress} inProgress · **remainingSeconds** ${result.remainingSeconds} · **copilotReviewInProgress** ${result.copilotReviewInProgress} · **isDraft** ${result.isDraft} · **shouldCancel** ${result.shouldCancel}`;
+        summaryLine = `**summary** ${result.summary.passing} passing, ${result.summary.skipped} skipped, ${result.summary.filtered} filtered, ${result.summary.inProgress} inProgress · **remainingSeconds** ${result.remainingSeconds} · **blockingBotReviewInProgress** ${result.blockingBotReviewInProgress} · **isDraft** ${result.isDraft} · **shouldCancel** ${result.shouldCancel}`;
     }
     else {
         const counts = [`${result.summary.passing} passing`];
@@ -42,22 +41,14 @@ export function formatIterateResult(result, opts) {
         if (result.status === "READY" && result.remainingSeconds > 0) {
             segs.push(`**remainingSeconds** ${result.remainingSeconds}`);
         }
-        if (result.copilotReviewInProgress)
-            segs.push(`**copilotReviewInProgress**`);
+        if (result.blockingBotReviewInProgress)
+            segs.push(`**blockingBotReviewInProgress**`);
         if (result.isDraft)
             segs.push(`**isDraft**`);
         summaryLine = segs.join(" · ");
     }
     const header = [heading, "", baseLine, summaryLine].join("\n");
     switch (result.action) {
-        case "cooldown":
-            // In default mode: suppress base/summary lines — cooldown carries UNKNOWN/empty
-            // placeholders that add no value. Emit only heading + log + Instructions.
-            return joinSections([
-                verbose ? header : heading,
-                adaptIterateLog(result.log, runtime),
-                `## Instructions\n\n${numberInstructions(buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner))}`,
-            ]);
         case "wait":
             return joinSections([
                 header,

package/bin/cli/iterate-instructions.mjs

@@ -1,67 +1,36 @@
-import { FIX_INSTRUCTION_END_ITERATION, FIX_INSTRUCTION_STOP_AFTER_PUSH, FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK, } from "../commands/iterate/render.mjs";
+import { FIX_INSTRUCTION_STOP_AFTER_PUSH, FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK, } from "../commands/iterate/render.mjs";
 import { buildPrShepherdCommand } from "./runner.mjs";
-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.";
-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)}`;
+function buildRecheckInstruction(rerunCommand, tail) {
+    return `Pick a fresh sleep/timeout between 30 seconds and 4 minutes, wait that long, then rerun \`${rerunCommand}\` ${tail}`;
 }
-export function buildSimpleIterateInstructions(result, runtime, readyDelaySuffix, runner) {
+export function buildSimpleIterateInstructions(result, _runtime, readyDelaySuffix, runner) {
     const rerunCommand = buildCodexIterateCommand(result.pr, readyDelaySuffix, runner);
-    const retryDelay = buildCodexRetryDelay();
     switch (result.action) {
-        case "cooldown":
-            return [
-                runtime === "codex"
-                    ? `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 — ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`
-                    : CLAUDE_DYNAMIC_WAKEUP,
-            ];
+            return [buildRecheckInstruction(rerunCommand, "to continue the active goal.")];
         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 — ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`
-                    : `The CLI already marked the PR ready for review. ${CLAUDE_DYNAMIC_WAKEUP}`,
+                `The CLI already marked the PR ready for review. ${buildRecheckInstruction(rerunCommand, "to recheck.")}`,
             ];
         case "cancel":
-            return [
-                runtime === "codex"
-                    ? "Stop — no recurring Codex monitor is running to cancel."
-                    : `Stop — do not schedule another dynamic wakeup. If this loop was started with a fixed-interval \`/loop\` schedule, call \`CronList\`, find the job whose prompt contains \`#pr-shepherd-loop:pr=${result.pr}:\`, and cancel it with \`CronDelete\`.`,
-                "Stop.",
-            ];
+            return ["Stop — the active goal is complete."];
         case "escalate":
-            return [
-                runtime === "codex"
-                    ? "Stop — no recurring Codex monitor is running to cancel."
-                    : `Stop — do not schedule another dynamic wakeup. If this loop was started with a fixed-interval \`/loop\` schedule, call \`CronList\`, find the job whose prompt contains \`#pr-shepherd-loop:pr=${result.pr}:\`, and cancel it with \`CronDelete\`.`,
-                "Stop — the PR needs human direction before monitoring can resume.",
-            ];
+            return ["Stop — the PR needs human direction before iterating can resume."];
     }
 }
-export function adaptFixCodeInstructions(instructions, pr, runtime, readyDelaySuffix, runner) {
-    if (runtime !== "codex")
-        return instructions;
+export function adaptFixCodeInstructions(instructions, pr, _runtime, readyDelaySuffix, runner) {
     const rerunCommand = buildCodexIterateCommand(pr, readyDelaySuffix, runner);
-    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. ${capitalizeFirst(retryDelay)}, then rerun \`${rerunCommand}\` to recheck.`;
+            return `CI needs time to run on the new push. ${buildRecheckInstruction(rerunCommand, "to recheck.")}`;
         }
-        if (instruction === FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK ||
-            instruction === FIX_INSTRUCTION_END_ITERATION) {
-            return `Continue the active Codex goal — ${retryDelay}, then rerun \`${rerunCommand}\` to recheck.`;
+        if (instruction === FIX_INSTRUCTION_STOP_BEFORE_NEXT_TICK) {
+            return buildRecheckInstruction(rerunCommand, "to recheck.");
         }
         return instruction;
     });
 }
-export function adaptIterateLog(log, runtime) {
-    if (runtime !== "codex")
-        return log;
+export function adaptIterateLog(log, _runtime) {
     return log.replace(/\s+—\s+\d+s until auto-cancel/g, "");
 }
 export function buildCodexIterateCommand(pr, readyDelaySuffix, runner) {
@@ -70,9 +39,6 @@ export function buildCodexIterateCommand(pr, readyDelaySuffix, runner) {
         runner,
     }).text;
 }
-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

@@ -18,7 +18,7 @@ export function projectIterateLean(result, opts) {
         mergeStateStatus: result.mergeStateStatus,
         ...(result.mergeStatus === "BLOCKED" &&
             result.reviewDecision !== null && { reviewDecision: result.reviewDecision }),
-        ...(result.copilotReviewInProgress && { copilotReviewInProgress: true }),
+        ...(result.blockingBotReviewInProgress && { blockingBotReviewInProgress: true }),
         ...(result.isDraft && { isDraft: true }),
         summary: {
             passing: result.summary.passing,
@@ -34,12 +34,6 @@ export function projectIterateLean(result, opts) {
         ...(result.baseBranch && { baseBranch: result.baseBranch }),
     };
     switch (result.action) {
-        case "cooldown":
-            return {
-                ...base,
-                log: adaptIterateLog(result.log, runtime),
-                instructions: simpleInstructions(result),
-            };
         case "wait":
             return {
                 ...base,
@@ -66,7 +60,6 @@ export function projectIterateLean(result, opts) {
                 ...(result.checks.length > 0 && { checks: result.checks }),
                 ...(result.cancelled.length > 0 && { cancelled: result.cancelled }),
                 fix: {
-                    mode: result.fix.mode,
                     ...(result.fix.threads.length > 0 && { threads: result.fix.threads }),
                     ...(result.fix.resolutionOnlyThreads.length > 0 && {
                         resolutionOnlyThreads: result.fix.resolutionOnlyThreads,
@@ -119,9 +112,9 @@ export function projectIterateLean(result, opts) {
                     ...(result.escalate.changesRequestedReviews.length > 0 && {
                         changesRequestedReviews: result.escalate.changesRequestedReviews,
                     }),
-                    ...(result.escalate.attemptHistory &&
-                        result.escalate.attemptHistory.length > 0 && {
-                        attemptHistory: result.escalate.attemptHistory,
+                    ...(result.escalate.thrashHistory &&
+                        result.escalate.thrashHistory.length > 0 && {
+                        thrashHistory: result.escalate.thrashHistory,
                     }),
                     suggestion: result.escalate.suggestion,
                     humanMessage: result.escalate.humanMessage,