pr-shepherd 0.7.0 → 0.8.0

package/bin/cli/args.mjs

@@ -1,20 +1,31 @@
 /**
  * CLI argument-parsing helpers extracted from cli.mts for testability.
- * Note: parseCommonArgs calls loadConfig() for cache TTL defaults.
  */
 import { parseArgs } from "node:util";
-import { loadConfig } from "../config/load.mjs";
-import { deriveVerdict } from "../commands/status.mjs";
 // Flags that consume the next argument as their value (used for PR-number
 // detection only — prevents a flag's value from being mistaken for a PR number).
 const FLAGS_WITH_VALUES = new Set([
     "--format",
-    "--cache-ttl",
-    "--last-push-time",
     "--ready-delay",
     "--cooldown-seconds",
+    "--stall-timeout",
     "--require-sha",
     "--message",
+    "--description",
+    "--thread-id",
+    "--resolve-thread-ids",
+    "--minimize-comment-ids",
+    "--dismiss-review-ids",
+]);
+// Boolean flags that do NOT consume the next argument. Any --flag not in this
+// set and not in FLAGS_WITH_VALUES is treated conservatively as value-taking
+// for PR-number detection — so removed flags don't silently cause their
+// numeric value to be misidentified as the PR number.
+const BOOLEAN_FLAGS = new Set([
+    "--fetch",
+    "--no-auto-mark-ready",
+    "--no-auto-cancel-actionable",
+    "--dry-run",
 ]);
 // ---------------------------------------------------------------------------
 // Strict integer parsing
@@ -26,7 +37,6 @@ export function parseIntStrict(value, flag) {
     return parseInt(value, 10);
 }
 export function parseCommonArgs(args) {
-    const config = loadConfig();
     const { values, tokens } = parseArgs({
         args,
         strict: false,
@@ -34,22 +44,14 @@ export function parseCommonArgs(args) {
         tokens: true,
         options: {
             format: { type: "string" },
-            "cache-ttl": { type: "string" },
-            "no-cache": { type: "boolean" },
         },
     });
     const format = (values.format ?? "text");
-    const noCache = (values["no-cache"] ?? false);
-    const cacheTtlStr = values["cache-ttl"];
-    const cacheTtlSeconds = cacheTtlStr
-        ? parseIntStrict(cacheTtlStr, "--cache-ttl")
-        : config.cache.ttlSeconds;
     // Build the set of arg indices consumed by global flags so we can strip
     // them from `extra`.  Subcommand-specific flags are left untouched.
     const consumedIndices = new Set();
     for (const tok of tokens ?? []) {
-        if (tok.kind === "option" &&
-            (tok.name === "format" || tok.name === "cache-ttl" || tok.name === "no-cache")) {
+        if (tok.kind === "option" && tok.name === "format") {
             consumedIndices.add(tok.index);
             // When the value is a separate arg (--flag value, not --flag=value),
             // inlineValue is false and the value occupies tok.index + 1.
@@ -59,7 +61,9 @@ export function parseCommonArgs(args) {
         }
     }
     // Find the first positional arg that looks like a PR number, skipping values
-    // that belong to flags in FLAGS_WITH_VALUES (subcommand flags included).
+    // that belong to value-taking flags. Any --flag not in BOOLEAN_FLAGS is
+    // treated conservatively as value-taking so that removed flags don't cause
+    // their numeric value to be misidentified as the PR number.
     const skipForPrDetect = new Set();
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
@@ -69,6 +73,14 @@ export function parseCommonArgs(args) {
                 skipForPrDetect.add(i + 1);
             i += 1;
         }
+        else if (arg.startsWith("--") && !arg.includes("=") && !BOOLEAN_FLAGS.has(arg)) {
+            // Unknown non-boolean flag: conservatively skip the next non-flag arg.
+            skipForPrDetect.add(i);
+            if (i + 1 < args.length && !args[i + 1].startsWith("--")) {
+                skipForPrDetect.add(i + 1);
+                i += 1;
+            }
+        }
         else {
             const eqIdx = arg.indexOf("=");
             if (eqIdx > 0 && FLAGS_WITH_VALUES.has(arg.slice(0, eqIdx))) {
@@ -85,7 +97,7 @@ export function parseCommonArgs(args) {
     const extra = args.filter((_, i) => !consumedIndices.has(i));
     return {
         prNumber,
-        global: { format, noCache, cacheTtlSeconds },
+        global: { format },
         extra,
     };
 }
@@ -127,47 +139,3 @@ export function parseStatusPrNumbers(args) {
     }
     return prNumbers;
 }
-// ---------------------------------------------------------------------------
-// Duration parsing
-// ---------------------------------------------------------------------------
-export function parseDurationToMinutes(s, defaultMinutes) {
-    const m = /^(\d+)(m|min|minutes?|h|hours?)?$/.exec(s.trim());
-    if (!m)
-        return defaultMinutes ?? loadConfig().watch.readyDelayMinutes;
-    const n = parseInt(m[1], 10);
-    const unit = m[2] ?? "m";
-    if (unit.startsWith("h"))
-        return n * 60;
-    return n;
-}
-// ---------------------------------------------------------------------------
-// Exit code mapping
-// ---------------------------------------------------------------------------
-export function statusToExitCode(status) {
-    switch (status) {
-        case "READY":
-            return 0;
-        case "IN_PROGRESS":
-            return 2;
-        case "UNRESOLVED_COMMENTS":
-            return 3;
-        default:
-            return 1;
-    }
-}
-export function iterateActionToExitCode(action) {
-    switch (action) {
-        case "fix_code":
-        case "rebase":
-            return 1;
-        case "cancel":
-            return 2;
-        case "escalate":
-            return 3;
-        default:
-            return 0;
-    }
-}
-export function deriveSimpleReady(s) {
-    return deriveVerdict(s) === "READY";
-}

package/bin/cli/exit-codes.mjs

@@ -0,0 +1,39 @@
+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)
+        return defaultMinutes ?? loadConfig().watch.readyDelayMinutes;
+    const n = parseInt(m[1], 10);
+    const unit = m[2] ?? "m";
+    if (unit.startsWith("h"))
+        return n * 60;
+    return n;
+}
+export function statusToExitCode(status) {
+    switch (status) {
+        case "READY":
+            return 0;
+        case "IN_PROGRESS":
+            return 2;
+        case "UNRESOLVED_COMMENTS":
+            return 3;
+        default:
+            return 1;
+    }
+}
+export function iterateActionToExitCode(action) {
+    switch (action) {
+        case "fix_code":
+            return 1;
+        case "cancel":
+            return 2;
+        case "escalate":
+            return 3;
+        default:
+            return 0;
+    }
+}
+export function deriveSimpleReady(s) {
+    return deriveVerdict(s) === "READY";
+}

package/bin/cli/fix-formatter.mjs

@@ -0,0 +1,76 @@
+import { renderResolveCommand } from "../commands/iterate.mjs";
+export function formatFixCodeResult(header, result) {
+    const sections = [header];
+    if (result.fix.threads.length > 0) {
+        sections.push("## Review threads");
+        for (const t of result.fix.threads) {
+            const loc = t.path ? `\`${t.path}:${t.line ?? "?"}\`` : "(no location)";
+            sections.push(`### \`${t.id}\` — ${loc} (@${t.author})`);
+            sections.push(blockquote(t.body));
+        }
+    }
+    if (result.fix.actionableComments.length > 0) {
+        sections.push("## Actionable comments");
+        for (const c of result.fix.actionableComments) {
+            sections.push(`### \`${c.id}\` (@${c.author})`);
+            sections.push(blockquote(c.body));
+        }
+    }
+    if (result.fix.checks.length > 0) {
+        sections.push("## Failing checks");
+        const bullets = result.fix.checks.map((ch) => {
+            const prefix = ch.workflowName ? `${ch.workflowName} › ` : "";
+            const locator = ch.runId
+                ? `\`${ch.runId}\``
+                : ch.detailsUrl
+                    ? `external \`${ch.detailsUrl}\``
+                    : "(no runId)";
+            const lines = [`- ${locator} — \`${prefix}${ch.name}\``];
+            if (ch.failedStep)
+                lines.push(`  > ${ch.failedStep}`);
+            if (ch.summary)
+                lines.push(`  > ${ch.summary}`);
+            return lines.join("\n");
+        });
+        sections.push(bullets.join("\n\n"));
+    }
+    if (result.fix.changesRequestedReviews.length > 0) {
+        sections.push("## Changes-requested reviews");
+        sections.push(result.fix.changesRequestedReviews.map((r) => `- \`${r.id}\` (@${r.author})`).join("\n"));
+    }
+    if (result.fix.noiseCommentIds.length > 0) {
+        sections.push("## Noise (minimize only)");
+        sections.push(result.fix.noiseCommentIds.map((id) => `\`${id}\``).join(", "));
+    }
+    if (result.fix.reviewSummaryIds.length > 0) {
+        sections.push("## Review summaries (minimize only)");
+        sections.push(result.fix.reviewSummaryIds.map((id) => `\`${id}\``).join(", "));
+    }
+    if (result.fix.surfacedSummaries.length > 0) {
+        sections.push("## Review summaries (surfaced — not minimized)");
+        for (const r of result.fix.surfacedSummaries) {
+            sections.push(`### \`${r.id}\` (@${r.author})`);
+            sections.push(blockquote(r.body));
+        }
+    }
+    if (result.cancelled.length > 0) {
+        sections.push("## Cancelled runs");
+        sections.push(result.cancelled.map((id) => `\`${id}\``).join(", "));
+    }
+    sections.push("## Post-fix push");
+    const postFixLines = [`- base: \`${result.baseBranch}\``];
+    if (result.fix.resolveCommand.hasMutations) {
+        postFixLines.push(`- resolve: \`${renderResolveCommand(result.fix.resolveCommand)}\``);
+    }
+    sections.push(postFixLines.join("\n"));
+    sections.push("## Instructions");
+    sections.push(result.fix.instructions.map((inst, i) => `${i + 1}. ${inst}`).join("\n"));
+    return sections.join("\n\n");
+}
+export function blockquote(body) {
+    return body
+        .replace(/\r\n/g, "\n")
+        .split("\n")
+        .map((line) => (line === "" ? ">" : `> ${line}`))
+        .join("\n");
+}

package/bin/cli/formatters.mjs

@@ -0,0 +1,108 @@
+export { formatIterateResult } from "./iterate-formatter.mjs";
+export function formatFetchResult(result) {
+    const total = result.actionableThreads.length +
+        result.actionableComments.length +
+        result.changesRequestedReviews.length +
+        result.reviewSummaries.length;
+    const sections = [];
+    sections.push(`# PR #${result.prNumber} — Resolve fetch (${total === 0 ? "0 actionable" : `${total} actionable`})`);
+    if (result.actionableThreads.length > 0) {
+        sections.push(`## Actionable Review Threads (${result.actionableThreads.length})` +
+            (result.commitSuggestionsEnabled ? " [commit-suggestions: enabled]" : ""));
+        sections.push(result.actionableThreads
+            .map((t) => {
+            const suggestionMarker = t.suggestion ? " [suggestion]" : "";
+            return `- \`threadId=${t.id}\` \`${t.path ?? ""}:${t.line ?? "?"}\` (@${t.author})${suggestionMarker}: ${t.body.split("\n")[0]?.slice(0, 100) ?? ""}`;
+        })
+            .join("\n"));
+    }
+    if (result.actionableComments.length > 0) {
+        sections.push(`## Actionable PR Comments (${result.actionableComments.length})`);
+        sections.push(result.actionableComments
+            .map((c) => `- \`commentId=${c.id}\` (@${c.author}): ${c.body.split("\n")[0]?.slice(0, 100) ?? ""}`)
+            .join("\n"));
+    }
+    if (result.changesRequestedReviews.length > 0) {
+        sections.push(`## Pending CHANGES_REQUESTED reviews (${result.changesRequestedReviews.length})`);
+        sections.push(result.changesRequestedReviews.map((r) => `- \`reviewId=${r.id}\` (@${r.author})`).join("\n"));
+    }
+    if (result.reviewSummaries.length > 0) {
+        sections.push(`## Review summaries (${result.reviewSummaries.length})`);
+        sections.push(result.reviewSummaries
+            .map((r) => `- \`reviewId=${r.id}\` (@${r.author}): ${r.body.split("\n")[0].slice(0, 100)}`)
+            .join("\n"));
+    }
+    sections.push("## Summary");
+    sections.push(total === 0 ? "0 actionable — all threads resolved/minimized" : `${total} actionable item(s)`);
+    sections.push("## Instructions");
+    sections.push(result.instructions.map((inst, i) => `${i + 1}. ${inst}`).join("\n"));
+    return `${sections.join("\n\n")}\n`;
+}
+export function formatCommitSuggestionResult(result) {
+    const lines = [];
+    if (result.dryRun) {
+        const range = result.startLine === result.endLine
+            ? `line ${result.startLine}`
+            : `lines ${result.startLine}-${result.endLine}`;
+        if (result.valid) {
+            lines.push(`Dry-run: would apply suggestion from @${result.author}:`);
+            lines.push(`  ${result.path} (${range})`);
+        }
+        else {
+            lines.push(`Dry-run: suggestion cannot apply cleanly:`);
+            lines.push(`- path: ${result.path} (${range})`);
+            lines.push(`- author: @${result.author}`);
+            lines.push(`- reason: ${result.reason ?? "unknown"}`);
+        }
+        if (result.patch) {
+            lines.push("");
+            lines.push("```diff");
+            lines.push(result.patch.trimEnd());
+            lines.push("```");
+        }
+    }
+    else if (result.applied) {
+        lines.push(`Applied suggestion from @${result.author}:`);
+        const range = result.startLine === result.endLine
+            ? `line ${result.startLine}`
+            : `lines ${result.startLine}-${result.endLine}`;
+        lines.push(`  ${result.path} (${range})`);
+        if (result.commitSha)
+            lines.push(`Commit: ${result.commitSha}`);
+        if (result.patch) {
+            lines.push("");
+            lines.push("```diff");
+            lines.push(result.patch.trimEnd());
+            lines.push("```");
+        }
+    }
+    else {
+        lines.push(`Failed to apply suggestion ${result.threadId}:`);
+        lines.push(`- path: ${result.path} (lines ${result.startLine}–${result.endLine})`);
+        lines.push(`- author: @${result.author}`);
+        lines.push(`- reason: ${result.reason ?? "unknown"}`);
+        if (result.patch) {
+            lines.push("");
+            lines.push("```diff");
+            lines.push(result.patch.trimEnd());
+            lines.push("```");
+        }
+    }
+    if (result.postActionInstruction) {
+        lines.push("");
+        lines.push(result.postActionInstruction);
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function formatMutateResult(result) {
+    const lines = [];
+    if (result.resolvedThreads.length)
+        lines.push(`Resolved threads (${result.resolvedThreads.length}): ${result.resolvedThreads.join(", ")}`);
+    if (result.minimizedComments.length)
+        lines.push(`Minimized comments (${result.minimizedComments.length}): ${result.minimizedComments.join(", ")}`);
+    if (result.dismissedReviews.length)
+        lines.push(`Dismissed reviews (${result.dismissedReviews.length}): ${result.dismissedReviews.join(", ")}`);
+    if (result.errors.length)
+        lines.push(`Errors:\n  ${result.errors.join("\n  ")}`);
+    return `${lines.join("\n")}\n`;
+}

package/bin/cli/handlers.mjs

@@ -0,0 +1,138 @@
+import { runCommitSuggestion } from "../commands/commit-suggestion.mjs";
+import { runIterate } from "../commands/iterate.mjs";
+import { runMonitor, formatMonitorResult } from "../commands/monitor.mjs";
+import { runStatus, formatStatusTable } from "../commands/status.mjs";
+import { getRepoInfo } from "../github/client.mjs";
+import { loadConfig } from "../config/load.mjs";
+import { parseCommonArgs, getFlag, hasFlag, parseStatusPrNumbers, parseIntStrict, } from "./args.mjs";
+import { parseDurationToMinutes, iterateActionToExitCode, deriveSimpleReady, } from "./exit-codes.mjs";
+import { formatCommitSuggestionResult, formatIterateResult } from "./formatters.mjs";
+export async function handleCommitSuggestion(args) {
+    const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
+    const threadId = getFlag(extra, "--thread-id");
+    if (!threadId) {
+        process.stderr.write("Usage: pr-shepherd commit-suggestion [PR] --thread-id ID [--message MSG] [--description DESC] [--dry-run]\n" +
+            "       (--message is required unless --dry-run is set)\n");
+        process.exitCode = 1;
+        return;
+    }
+    const dryRun = hasFlag(extra, "--dry-run");
+    const message = getFlag(extra, "--message") ?? undefined;
+    if (!dryRun && (!message || message.trim() === "")) {
+        process.stderr.write("--message is required and must be non-empty\n");
+        process.exitCode = 1;
+        return;
+    }
+    const description = getFlag(extra, "--description") ?? undefined;
+    const result = await runCommitSuggestion({
+        ...globalOpts,
+        prNumber,
+        threadId,
+        message,
+        description,
+        dryRun,
+    });
+    process.stdout.write(globalOpts.format === "json"
+        ? `${JSON.stringify(result, null, 2)}\n`
+        : formatCommitSuggestionResult(result));
+    if (result.dryRun) {
+        process.exitCode = result.valid ? 0 : 1;
+    }
+    else {
+        process.exitCode = result.applied ? 0 : 1;
+    }
+}
+export async function handleIterate(args) {
+    const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
+    const readyDelayStr = getFlag(extra, "--ready-delay");
+    const cfg = loadConfig();
+    const readyDelaySeconds = parseDurationToMinutes(readyDelayStr ?? "", 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");
+    const stallTimeoutSeconds = stallTimeoutStr
+        ? parseDurationToMinutes(stallTimeoutStr, cfg.iterate.stallTimeoutMinutes) * 60
+        : cfg.iterate.stallTimeoutMinutes * 60;
+    const result = await runIterate({
+        ...globalOpts,
+        prNumber,
+        readyDelaySeconds,
+        cooldownSeconds,
+        stallTimeoutSeconds,
+        noAutoMarkReady,
+        noAutoCancelActionable,
+    });
+    if (globalOpts.format === "json") {
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+    }
+    else {
+        process.stdout.write(`${formatIterateResult(result)}\n`);
+    }
+    process.exitCode = iterateActionToExitCode(result.action);
+}
+export async function handleMonitor(args) {
+    const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
+    const readyDelayStr = getFlag(extra, "--ready-delay");
+    if (hasFlag(extra, "--ready-delay") &&
+        (readyDelayStr === null || readyDelayStr.startsWith("--"))) {
+        process.stderr.write("pr-shepherd monitor: --ready-delay requires a value (e.g. --ready-delay 15m)\n");
+        process.exitCode = 1;
+        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: readyDelayStr ?? undefined,
+        });
+    }
+    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(result, null, 2)}\n`
+        : `${formatMonitorResult(result)}\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

@@ -0,0 +1,78 @@
+import { formatFixCodeResult } from "./fix-formatter.mjs";
+/**
+ * Format an IterateResult as human-readable Markdown.
+ *
+ * Load-bearing conventions the monitor 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.
+ *   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
+ *      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.
+ */
+export function formatIterateResult(result) {
+    const heading = `# PR #${result.pr} [${result.action.toUpperCase()}]`;
+    const baseLine = `**status** \`${result.status}\` · **merge** \`${result.mergeStateStatus}\` · **state** \`${result.state}\` · **repo** \`${result.repo}\``;
+    const 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}`;
+    const header = [heading, "", baseLine, summaryLine].join("\n");
+    switch (result.action) {
+        case "cooldown":
+            return [
+                header,
+                "",
+                result.log,
+                "",
+                "## Instructions",
+                "",
+                "1. End this iteration — the next cron fire will recheck once CI starts reporting.",
+            ].join("\n");
+        case "wait": {
+            const parts = [
+                header,
+                result.log,
+                "## Instructions",
+                "1. End this iteration — the next cron fire will recheck.",
+            ];
+            return parts.join("\n\n").replace(/\n\n\n+/g, "\n\n");
+        }
+        case "rerun_ci": {
+            const rerunInstructions = result.reran.map((r, i) => `${i + 1}. Run: \`gh run rerun ${r.runId} --failed\``);
+            rerunInstructions.push(`${rerunInstructions.length + 1}. End this iteration — wait for CI to report results after the re-run.`);
+            const parts = [header, result.log, "## Instructions", rerunInstructions.join("\n")];
+            return parts.join("\n\n").replace(/\n\n\n+/g, "\n\n");
+        }
+        case "mark_ready": {
+            const parts = [
+                header,
+                result.log,
+                "## Instructions",
+                "1. The CLI already marked the PR ready for review — end this iteration.",
+            ];
+            return parts.join("\n\n").replace(/\n\n\n+/g, "\n\n");
+        }
+        case "cancel": {
+            const parts = [
+                header,
+                result.log,
+                "## Instructions",
+                "1. Invoke `/loop cancel` via the Skill tool.\n2. Stop.",
+            ];
+            return parts.join("\n\n").replace(/\n\n\n+/g, "\n\n");
+        }
+        case "escalate": {
+            const parts = [
+                header,
+                result.escalate.humanMessage,
+                "## Instructions",
+                "1. Invoke `/loop cancel` via the Skill tool.\n2. Stop — the PR needs human direction before monitoring can resume.",
+            ];
+            return parts.join("\n\n").replace(/\n\n\n+/g, "\n\n");
+        }
+        case "fix_code":
+            return formatFixCodeResult(header, result);
+    }
+}

package/bin/cli-parser.iterate-fixtures.mjs

@@ -0,0 +1,65 @@
+export function makeIterateResult(action = "wait") {
+    const base = {
+        pr: 42,
+        repo: "owner/repo",
+        status: "IN_PROGRESS",
+        state: "OPEN",
+        mergeStateStatus: "BLOCKED",
+        copilotReviewInProgress: false,
+        isDraft: false,
+        shouldCancel: false,
+        remainingSeconds: 60,
+        summary: { passing: 0, skipped: 0, filtered: 0, inProgress: 1 },
+        baseBranch: "main",
+        checks: [],
+    };
+    if (action === "cooldown")
+        return { ...base, action: "cooldown", log: "SKIP: CI still starting" };
+    if (action === "wait")
+        return { ...base, action: "wait", log: "WAIT: 0 passing, 1 in-progress" };
+    if (action === "rerun_ci")
+        return { ...base, action: "rerun_ci", log: "RERAN: run-99 (typecheck — transient)", reran: [] };
+    if (action === "mark_ready")
+        return { ...base, action: "mark_ready", markedReady: true, log: "MARKED READY: PR 42" };
+    if (action === "fix_code") {
+        return {
+            ...base,
+            action: "fix_code",
+            fix: {
+                mode: "rebase-and-push",
+                threads: [],
+                actionableComments: [],
+                noiseCommentIds: [],
+                reviewSummaryIds: [],
+                surfacedSummaries: [],
+                checks: [],
+                changesRequestedReviews: [],
+                resolveCommand: {
+                    argv: ["npx", "pr-shepherd", "resolve", "42"],
+                    requiresHeadSha: true,
+                    requiresDismissMessage: false,
+                    hasMutations: false,
+                },
+                instructions: ["End this iteration."],
+            },
+            cancelled: [],
+        };
+    }
+    if (action === "cancel")
+        return { ...base, action: "cancel", log: "CANCEL: PR #42 — stopping monitor" };
+    if (action === "escalate") {
+        return {
+            ...base,
+            action: "escalate",
+            escalate: {
+                triggers: [],
+                unresolvedThreads: [],
+                ambiguousComments: [],
+                changesRequestedReviews: [],
+                suggestion: "check manually",
+                humanMessage: "⚠️  /pr-shepherd:monitor paused — needs human direction",
+            },
+        };
+    }
+    return { ...base, action: "wait", log: "WAIT: 0 passing, 1 in-progress" };
+}