pr-shepherd 0.8.1 → 0.9.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for Claude Code",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -10,28 +10,130 @@ Example Workflow:
 3. Accept the plan
 4. Switch to Auto Mode
 5. Prompt: `make a PR, then run /pr-shepherd:monitor`
-6. ...
-7. Human reviews PR with passing CI, no open threads, and all comments minimized
+6. Agent makes a draft PR
+7. PR has passing CI -> draft is marked Ready for Review
+8. Review bots begin providing reviews
+9. Agent automatically classifies and fixes review comments based on the Plan
+10. Human reviews PR with a well-documented PR title and description, passing CI, and no open threads/comments/reviews
 
-## Why pr-shepherd
+## How it works
 
-Concrete improvements to an agentic PR-review 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.
 
-- **Faster monitor loops** — one batched GraphQL query per tick (see [docs/graphql.md](docs/graphql.md)) instead of N REST round-trips
-- **Lower context usage per iteration** — classification lives in the CLI; the agent receives one decision per tick and never sees raw GraphQL payloads or resolved threads
-- **Prompt-cache friendly** — the 4-minute default tick is tuned to Claude's 5-minute prompt-cache TTL (tunable via `watch.interval`)
-- **Reduced GitHub rate-limit exposure** — one batched GraphQL read per tick; loop-state files (fix-attempts, stall detection, ready-delay timer) are kept in `$TMPDIR/pr-shepherd-state/`
-- **No MCP surface** — skills call the CLI via `npx`; no long-lived MCP server, no extra auth boundary, smaller reasoning surface
-- **Skills over subagents** — skill prompts inject into the main conversation rather than spawning a subagent that reloads CLAUDE.md every turn
-- **Safe to interrupt** — all state lives in the PR on GitHub; the cron loop self-terminates when the PR is merged, closed, or settles after ready-delay
+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)_:
 
-## Design principles
+```
+/pr-shepherd:monitor
+
+> npx pr-shepherd monitor 123
+
+# PR #123 [MONITOR]
+
+Loop tag: `# pr-shepherd-loop:pr=123`
+Loop args: `4m --max-turns 50 --expires 8h`
+
+## Loop prompt
+
+# pr-shepherd-loop:pr=123
+
+**IMPORTANT — recurrence rules:** Do not call ScheduleWakeup or /loop. End the turn
+after completing the actions below. The cron job handles the next fire.
+
+Run in a single Bash call:
+  npx pr-shepherd iterate 123 --no-cache
+
+…(self-dedup guidance, error-handling instructions)…
+
+## Instructions
+
+1. Run `CronList`. If any job's prompt contains the loop tag, run the ## Loop prompt inline then stop.
+2. Otherwise, invoke the /loop skill with Loop args and the full ## Loop prompt body.
+```
+
+Each iteration calls `npx pr-shepherd iterate <PR>`, which provides actionable feedback directly to the agent:
+
+```
+> npx pr-shepherd iterate 123
+
+# PR #123 [FIX_CODE]
+
+**status** `UNRESOLVED_COMMENTS` · **merge** `BLOCKED` · **state** `OPEN` · **repo** `owner/repo`
+**summary** 3 passing
+
+## Review threads
+
+### `PRRT_kwDOSGizTs58XB1L` — `src/commands/iterate.mts:42` (@alice)
+
+> The variable name is misleading.
+>
+> Consider renaming `x` to `remainingSeconds` so readers don't have to
+> trace back to the declaration to understand its meaning.
+
+## Failing checks
 
-- **Reduced agent context** — logic lives in the CLI, not the prompt
-- **Reduced GitHub rate-limit exhaustion** — primary PR state is fetched via a batched GraphQL query
-- **Fewer tool calls** — comment resolutions are batched; resolved threads never reach the agent
-- **Skills over subagents** — subagents reload all CLAUDE.md context on every turn; skills inject into the main conversation instead, keeping cost low
-- **JSON/text parity** — `--format=json` and `--format=text` carry equivalent information; every field in one has a representation in the other
+- `24697658766` — `CI › lint / typecheck / test (22.x)`
+  > npx oxfmt
+
+## Post-fix push
+
+- base: `main`
+- resolve: `npx pr-shepherd resolve 123 --resolve-thread-ids PRRT_kwDOSGizTs58XB1L --minimize-comment-ids IC_kwDOSGizTs7_ajT8,IC_kwDOSGizTs7_ajT9 --dismiss-review-ids PRR_kwDOSGizTs58XB1R --message "$DISMISS_MESSAGE" --require-sha "$HEAD_SHA"`
+
+## Instructions
+
+_(schematic — actual steps depend on PR state)_
+
+1. Apply code fixes for each file referenced under `## Review threads`.
+2. For each failing check: examine the log tail to decide — rerun if transient, fix code if real.
+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.
+7. Stop this iteration.
+```
+
+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:
+
+```
+npx pr-shepherd resolve 123 --resolve-thread-ids PRRT_kwDOSGizTs58XB1L --minimize-comment-ids IC_kwDOSGizTs7_ajT8,IC_kwDOSGizTs7_ajT9 --dismiss-review-ids PRR_kwDOSGizTs58XB1R --message "$DISMISS_MESSAGE" --require-sha "$HEAD_SHA"
+```
+
+## Workflow
+
+This system makes opinionated decisions, which may or may not work for your team's workflow.
+
+- The following PR branch protection rules are expected:
+  - There are required status checks
+  - All inline comments are resolved
+- **ALL** comments/threads/reviews will be hidden by default except for PR approvals. The only option here is to hide PR approvals as well.
+  - The primary reason is to optimize tokens by avoiding re-fetching comments and re-adding them to the agent's context.
+  - This also ties hand-in-hand with requiring all inline comments to be resolved.
+  - We also want to avoid storing state as comments can be unresolved/minimized/hidden.
+- `pr-shepherd` keeps the PR title and description up to date, including a journal of decisions with links to comments/threads/reviews (that would be hidden at this point).
+  - This may break your workflow if your PR titles and descriptions are restricted to a specific format.
+- `pr-shepherd` does **NOT** reply to inline comments when resolving them. Doing so would require agentic loops and more tokens. Instead, it updates the PR title & description once per loop with only the relevant information.
+- Branches are currently kept up-to-date with `git push --force-with-lease`. Please make a PR for making `merge <default branch>` an option.
+- Branches are currently only rebased when 1) pushing a commit on a branch that is out of date or 2) there are merge conflicts. It does not continuously rebase the branch (use a merge queue for that).
+- To optimize AI code reviewer tokens, create your pull requests initially as drafts and instruct your AI code reviewers to only code review PRs that are ready for review. `pr-shepherd` will automatically mark PRs as ready for review when all CI passes (can be disabled). If you have no intention of marking your PR as ready for review, then don't run `pr-shepherd`.
+
+Some other workflow improvements:
+
+- `pr-shepherd` knows whether a GitHub Copilot code review is in progress
+- `pr-shepherd` waits 10 minutes (configurable) until after all comments are hidden and CI passes before exiting. The primary reason is to wait for any lingering automated code reviews that do not provide status updates via the GitHub GraphQL API.
+- The agent is instructed to cancel failed CI runs and, when a failure looks transient (e.g. network timeout, runner setup crash), re-run them via `gh run rerun <id> --failed`. The primary reason is to minimize CI costs.
+- `pr-shepherd` supports "commit suggestions" by converting them into a diff, applying them, and then committing them with attribution. This avoids a file read & write. One commit is always made per suggestion to avoid any merge conflicts — in these cases, the agent will resolve the comment manually.
+
+Recommendations:
+
+- Run `pr-shepherd` on all your PRs before you go to sleep so that you wake up to reviewable PRs. As it uses `/loop`, it will continue working when your rate limit window is reset. There is a default timeout of 8 hours and 50 loops before exiting automatically.
+
+## Design Principles
+
+- **Reduced agent context and turns** — logic lives in the CLI, not the prompt. The relevant context is provided automatically to the agent, reducing tool calls.
+- **Reduced GitHub rate-limit exposure** — GraphQL requests are batched when possible
+- **Minimal state** — `pr-shepherd` stores minimal state in `$PR_SHEPHERD_STATE_DIR` (default `$TMPDIR/pr-shepherd-state/`), not in the repository
+- **Classifications and decisions still happen at the agent level** — `pr-shepherd`'s goal is to provide sufficient context to make informed decisions and provide clear actionable steps without writing unreliable code-level heuristics
+- **Configurable** — `pr-shepherd` is configurable via `.pr-shepherdrc.yml`, which is only possible with a light prompt that simply invokes the CLI which returns the prompt.
 
 ## Usage
 
@@ -72,9 +174,9 @@ GitHub has seen the push before resolving).
 
 See [docs/skills.md](docs/skills.md) for full argument reference.
 
-## Workflow
+## Iterate decision loop
 
-On each tick (4-minute default, tunable via `watch.interval`): fetch PR state in one GraphQL batch → classify CI, comments, and merge status → take one action (fix code, rebase, rerun CI, mark ready, or wait). 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 (4-minute default, tunable via `watch.interval`): 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`). 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
 
@@ -126,7 +228,7 @@ checks:
     - pull_request_target
     - merge_group # add for merge-queue repos
 actions:
-  autoRebase: false # disable for repos that enforce merge commits
+  autoMarkReady: false # disable to stay draft until you manually promote
 ```
 
 Environment variables: `GH_TOKEN` / `GITHUB_TOKEN` (auth; falls back to `gh auth token`), `PR_SHEPHERD_STATE_DIR` (override loop-state base dir).

package/bin/checks/classify.mjs

@@ -49,6 +49,7 @@ export function getCiVerdict(classified) {
     // When there are no relevant checks (e.g. docs-only PR where all checks are filtered/skipped),
     // treat as allPassed rather than blocking — there's nothing to fail.
     const allPassed = !anyInProgress && !anyFailing;
+    const hasChecks = relevant.length > 0;
     const filteredNames = classified.filter((c) => c.category === "filtered").map((c) => c.name);
-    return { allPassed, anyInProgress, anyFailing, filteredNames };
+    return { allPassed, hasChecks, anyInProgress, anyFailing, filteredNames };
 }

package/bin/checks/triage.mjs

@@ -1,64 +1,53 @@
 /**
- * Triage failing check runs into three categories based solely on GitHub's
- * own conclusion field — no log-content classification:
- *   - timeout: conclusion is TIMED_OUT.
- *   - cancelled: conclusion is CANCELLED, STARTUP_FAILURE, or STALE.
- *   - actionable: everything else (FAILURE, ACTION_REQUIRED, …).
+ * Triage failing check runs: call the jobs API once per runId to fetch
+ * workflow name, job name, and the first failed step name. Then fetch the
+ * last N lines of the failing job's log so the agent can diagnose failures
+ * without a separate tool call.
  *
- * Exception: checks with runId === null are always classified as "actionable"
- * regardless of conclusion, so they surface in fix_code where the monitor
- * escalates to the user (no run to rerun/inspect).
+ * No heuristic classification is applied — the raw GitHub `conclusion` field
+ * is preserved as-is. The agent decides whether a failure is transient or
+ * real based on the log tail and other context.
  *
- * For all checks with a non-null runId, the jobs API is called once per runId
- * (results are cached across checks that share a run) to fetch workflow name
- * and, for actionable checks, the first failed step name. No log fetching is done.
+ * For checks with runId === null (external StatusContexts) no API calls are
+ * made; workflowName, jobName, failedStep, and logTail are all absent.
  *
- * Note on infrastructure-killed FAILURE runs: GitHub reports these as
- * conclusion === "FAILURE", so they classify as "actionable". The jobs API
- * surfaces their failedStep (e.g. "Set up job") which gives the agent a
- * GitHub-native signal to distinguish runner setup deaths from real test
- * failures — without any log-pattern analysis at the CLI level.
+ * Jobs responses are cached by runId so checks that share a run (e.g. matrix
+ * builds or multiple required steps in one workflow) make only one API call.
+ * Log tails are fetched per job ID, not per runId.
  */
-import { rest } from "../github/http.mjs";
+import { rest, restText } from "../github/http.mjs";
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
 /**
- * Triage each failing check: classify by GitHub conclusion and call the jobs
- * API for each check with a non-null runId to fetch workflow name and (for
- * actionable failures) the name of the first failed step.
- *
- * Jobs responses are cached by runId so checks that share a run (e.g. matrix
- * builds or multiple required steps in one workflow) make only one API call.
+ * Triage each failing check: call the jobs API for each check with a non-null
+ * runId to fetch workflow name, job name, and the first failed step name, then
+ * fetch the last `logTailLines` lines of the failing job's log.
  */
-export function triageFailingChecks(failingChecks, repo) {
+export function triageFailingChecks(failingChecks, repo, logTailLines) {
     const jobsCache = new Map();
-    return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache)));
+    return Promise.all(failingChecks.map((c) => triageCheck(c, repo, jobsCache, logTailLines)));
 }
 // ---------------------------------------------------------------------------
 // Internal
 // ---------------------------------------------------------------------------
-async function triageCheck(check, repo, jobsCache) {
-    const failureKind = check.runId === null ? "actionable" : classifyConclusion(check.conclusion);
+async function triageCheck(check, repo, jobsCache, logTailLines) {
     if (check.runId === null) {
-        return { ...check, failureKind };
+        return { ...check };
     }
     const jobs = await fetchJobs(check.runId, repo, jobsCache);
-    const jobInfo = jobs ? pickJobInfo(jobs, check.name, failureKind) : undefined;
+    const jobInfo = jobs ? pickJobInfo(jobs, check.name) : undefined;
+    const logTail = jobInfo?.jobId !== undefined && logTailLines > 0
+        ? await fetchLogTail(jobInfo.jobId, repo, logTailLines)
+        : undefined;
     return {
         ...check,
-        failureKind,
-        workflowName: jobInfo?.workflowName,
-        ...(failureKind === "actionable" && { failedStep: jobInfo?.failedStep }),
+        ...(jobInfo?.workflowName !== undefined && { workflowName: jobInfo.workflowName }),
+        ...(jobInfo?.jobName !== undefined && { jobName: jobInfo.jobName }),
+        ...(jobInfo?.failedStep !== undefined && { failedStep: jobInfo.failedStep }),
+        ...(logTail !== undefined && { logTail }),
     };
 }
-function classifyConclusion(c) {
-    if (c === "TIMED_OUT")
-        return "timeout";
-    if (c === "CANCELLED" || c === "STARTUP_FAILURE" || c === "STALE")
-        return "cancelled";
-    return "actionable";
-}
 function fetchJobs(runId, repo, cache) {
     const cached = cache.get(runId);
     if (cached)
@@ -90,17 +79,38 @@ async function fetchJobsUncached(runId, repo) {
     }
     return allJobs;
 }
-function pickJobInfo(jobs, checkName, failureKind) {
+function pickJobInfo(jobs, checkName) {
     // Match by name. For matrix jobs sharing a check name, prefer a failing one.
     // Fall back to prefix matching for matrix jobs whose workflow-API name includes
     // a suffix like "(ubuntu)" while checkName is just the base name.
     const exactMatches = jobs.filter((j) => j.name === checkName);
     const matchedJobs = exactMatches.length > 0 ? exactMatches : jobs.filter((j) => j.name.startsWith(checkName));
-    const job = matchedJobs.find((j) => j.conclusion === "failure") ?? matchedJobs[0];
+    const job = matchedJobs.find((j) => j.conclusion === "failure") ??
+        matchedJobs.find((j) => j.conclusion !== null && j.conclusion !== "success") ??
+        matchedJobs[0];
     if (!job)
         return undefined;
-    const failedStep = failureKind === "actionable"
-        ? job.steps?.find((s) => s.conclusion === "failure")?.name
-        : undefined;
-    return { workflowName: job.workflow_name, failedStep };
+    const failedStep = job.steps?.find((s) => s.conclusion !== null &&
+        s.conclusion !== "success" &&
+        s.conclusion !== "skipped" &&
+        s.conclusion !== "neutral")?.name;
+    return {
+        workflowName: job.workflow_name,
+        jobName: job.name,
+        failedStep,
+        jobId: job.id,
+    };
+}
+async function fetchLogTail(jobId, repo, logTailLines) {
+    const { owner, name } = repo;
+    try {
+        const text = await restText(`/repos/${owner}/${name}/actions/jobs/${jobId}/logs`);
+        const lines = text.split("\n");
+        if (lines.length <= logTailLines)
+            return text;
+        return lines.slice(-logTailLines).join("\n");
+    }
+    catch {
+        return undefined;
+    }
 }

package/bin/cli/args.mjs

@@ -26,6 +26,7 @@ const BOOLEAN_FLAGS = new Set([
     "--no-auto-mark-ready",
     "--no-auto-cancel-actionable",
     "--dry-run",
+    "--verbose",
 ]);
 // ---------------------------------------------------------------------------
 // Strict integer parsing
@@ -44,18 +45,23 @@ export function parseCommonArgs(args) {
         tokens: true,
         options: {
             format: { type: "string" },
+            verbose: { type: "boolean" },
         },
     });
     const format = (values.format ?? "text");
+    const verbose = values.verbose === true;
     // 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") {
+        if (tok.kind === "option" && (tok.name === "format" || tok.name === "verbose")) {
             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.
-            if ("inlineValue" in tok && tok.inlineValue === false && tok.value != null) {
+            if (tok.name === "format" &&
+                "inlineValue" in tok &&
+                tok.inlineValue === false &&
+                tok.value != null) {
                 consumedIndices.add(tok.index + 1);
             }
         }
@@ -97,7 +103,7 @@ export function parseCommonArgs(args) {
     const extra = args.filter((_, i) => !consumedIndices.has(i));
     return {
         prNumber,
-        global: { format },
+        global: { format, verbose },
         extra,
     };
 }

package/bin/cli/fix-formatter.mjs

@@ -1,35 +1,48 @@
 import { renderResolveCommand } from "../commands/iterate.mjs";
+function safeFence(content) {
+    const maxRun = Math.max(0, ...Array.from(content.matchAll(/`+/g), (m) => m[0].length));
+    return "`".repeat(Math.max(3, maxRun + 1));
+}
 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})`);
+            const heading = t.url ? `[${t.id}](${t.url})` : `\`${t.id}\``;
+            sections.push(`### ${heading} — ${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})`);
+            const heading = c.url ? `[${c.id}](${c.url})` : `\`${c.id}\``;
+            sections.push(`### ${heading} (@${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 workflowPrefix = ch.workflowName ? `${ch.workflowName} › ` : "";
+            const jobLabel = ch.jobName ? ch.jobName : ch.name;
             const locator = ch.runId
                 ? `\`${ch.runId}\``
                 : ch.detailsUrl
                     ? `external \`${ch.detailsUrl}\``
                     : "(no runId)";
-            const lines = [`- ${locator} — \`${prefix}${ch.name}\``];
+            const lines = [`- ${locator} — \`${workflowPrefix}${jobLabel}\``];
             if (ch.failedStep)
                 lines.push(`  > ${ch.failedStep}`);
             if (ch.summary)
                 lines.push(`  > ${ch.summary}`);
+            if (ch.logTail) {
+                const fence = safeFence(ch.logTail);
+                lines.push(`  ${fence}`);
+                lines.push(ch.logTail.replace(/^/gm, "  ").trimEnd());
+                lines.push(`  ${fence}`);
+            }
             return lines.join("\n");
         });
         sections.push(bullets.join("\n\n"));
@@ -46,12 +59,28 @@ export function formatFixCodeResult(header, result) {
         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) {
+    if (result.fix.surfacedApprovals.length > 0) {
+        sections.push("## Approvals (surfaced — not minimized)");
+        for (const r of result.fix.surfacedApprovals) {
             sections.push(`### \`${r.id}\` (@${r.author})`);
-            sections.push(blockquote(r.body));
+            sections.push(r.body.trim() === "" ? "(no review body)" : blockquote(r.body));
+        }
+    }
+    const firstLookTotal = result.fix.firstLookThreads.length + result.fix.firstLookComments.length;
+    if (firstLookTotal > 0) {
+        sections.push(`## First-look items (${firstLookTotal}) — already closed on GitHub; acknowledge only`);
+        const bullets = [];
+        for (const t of result.fix.firstLookThreads) {
+            const statusTag = t.autoResolved
+                ? `[status: outdated, auto-resolved]`
+                : `[status: ${t.firstLookStatus}]`;
+            const loc = t.path ? `\`${t.path}:${t.line ?? "?"}\`` : "(no location)";
+            bullets.push(`- \`${t.id}\` ${loc} (@${t.author}) ${statusTag}: ${t.body.split("\n")[0]?.slice(0, 100) ?? ""}`);
+        }
+        for (const c of result.fix.firstLookComments) {
+            bullets.push(`- \`${c.id}\` (@${c.author}) [status: minimized]: ${c.body.split("\n")[0]?.slice(0, 100) ?? ""}`);
         }
+        sections.push(bullets.join("\n"));
     }
     if (result.cancelled.length > 0) {
         sections.push("## Cancelled runs");

package/bin/cli/formatters.mjs

@@ -1,25 +1,38 @@
 export { formatIterateResult } from "./iterate-formatter.mjs";
+export { projectIterateLean } from "./iterate-lean.mjs";
 export function formatFetchResult(result) {
-    const total = result.actionableThreads.length +
+    const activeTotal = result.actionableThreads.length +
         result.actionableComments.length +
         result.changesRequestedReviews.length +
         result.reviewSummaries.length;
+    const firstLookTotal = result.firstLookThreads.length + result.firstLookComments.length;
+    const total = activeTotal + firstLookTotal;
+    const headingParts = [];
+    if (activeTotal > 0)
+        headingParts.push(`${activeTotal} actionable`);
+    if (firstLookTotal > 0)
+        headingParts.push(`${firstLookTotal} first-look`);
+    const headingSuffix = headingParts.length > 0 ? headingParts.join(", ") : "0 actionable";
     const sections = [];
-    sections.push(`# PR #${result.prNumber} — Resolve fetch (${total === 0 ? "0 actionable" : `${total} actionable`})`);
+    sections.push(`# PR #${result.prNumber} — Resolve fetch (${headingSuffix})`);
     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) ?? ""}`;
+            const link = t.url ? ` [↗](${t.url})` : "";
+            return `- \`threadId=${t.id}\`${link} \`${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) ?? ""}`)
+            .map((c) => {
+            const link = c.url ? ` [↗](${c.url})` : "";
+            return `- \`commentId=${c.id}\`${link} (@${c.author}): ${c.body.split("\n")[0]?.slice(0, 100) ?? ""}`;
+        })
             .join("\n"));
     }
     if (result.changesRequestedReviews.length > 0) {
@@ -32,8 +45,30 @@ export function formatFetchResult(result) {
             .map((r) => `- \`reviewId=${r.id}\` (@${r.author}): ${r.body.split("\n")[0].slice(0, 100)}`)
             .join("\n"));
     }
+    if (firstLookTotal > 0) {
+        sections.push(`## First-look items (${firstLookTotal}) — already closed on GitHub; acknowledge only`);
+        const bullets = [];
+        for (const t of result.firstLookThreads) {
+            const statusTag = t.autoResolved
+                ? `[status: outdated, auto-resolved]`
+                : `[status: ${t.firstLookStatus}]`;
+            const loc = t.path ? `\`${t.path}:${t.line ?? "?"}\`` : "(no location)";
+            bullets.push(`- \`threadId=${t.id}\` ${loc} (@${t.author}) ${statusTag}: ${t.body.split("\n")[0]?.slice(0, 100) ?? ""}`);
+        }
+        for (const c of result.firstLookComments) {
+            bullets.push(`- \`commentId=${c.id}\` (@${c.author}) [status: minimized]: ${c.body.split("\n")[0]?.slice(0, 100) ?? ""}`);
+        }
+        sections.push(bullets.join("\n"));
+    }
     sections.push("## Summary");
-    sections.push(total === 0 ? "0 actionable — all threads resolved/minimized" : `${total} actionable item(s)`);
+    sections.push(total === 0
+        ? "0 actionable, 0 first-look — all items seen"
+        : [
+            activeTotal > 0 ? `${activeTotal} actionable` : null,
+            firstLookTotal > 0 ? `${firstLookTotal} first-look` : null,
+        ]
+            .filter(Boolean)
+            .join(", "));
     sections.push("## Instructions");
     sections.push(result.instructions.map((inst, i) => `${i + 1}. ${inst}`).join("\n"));
     return `${sections.join("\n\n")}\n`;

package/bin/cli/handlers.mjs

@@ -6,7 +6,7 @@ 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";
+import { formatCommitSuggestionResult, formatIterateResult, projectIterateLean, } from "./formatters.mjs";
 export async function handleCommitSuggestion(args) {
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const threadId = getFlag(extra, "--thread-id");
@@ -67,10 +67,11 @@ export async function handleIterate(args) {
         noAutoCancelActionable,
     });
     if (globalOpts.format === "json") {
-        process.stdout.write(`${JSON.stringify(result)}\n`);
+        const output = globalOpts.verbose ? result : projectIterateLean(result);
+        process.stdout.write(`${JSON.stringify(output)}\n`);
     }
     else {
-        process.stdout.write(`${formatIterateResult(result)}\n`);
+        process.stdout.write(`${formatIterateResult(result, { verbose: globalOpts.verbose })}\n`);
     }
     process.exitCode = iterateActionToExitCode(result.action);
 }

package/bin/cli/iterate-formatter.mjs

@@ -14,15 +14,42 @@ import { formatFixCodeResult } from "./fix-formatter.mjs";
  *      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) {
+export function formatIterateResult(result, opts) {
+    const verbose = opts?.verbose ?? false;
     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 reviewDecisionSeg = result.mergeStatus === "BLOCKED" && result.reviewDecision
+        ? ` · **reviewDecision** \`${result.reviewDecision}\``
+        : "";
+    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}`;
+    }
+    else {
+        const counts = [`${result.summary.passing} passing`];
+        if (result.summary.skipped > 0)
+            counts.push(`${result.summary.skipped} skipped`);
+        if (result.summary.filtered > 0)
+            counts.push(`${result.summary.filtered} filtered`);
+        if (result.summary.inProgress > 0)
+            counts.push(`${result.summary.inProgress} inProgress`);
+        const segs = [`**summary** ${counts.join(", ")}`];
+        if (result.status === "READY" && result.remainingSeconds > 0) {
+            segs.push(`**remainingSeconds** ${result.remainingSeconds}`);
+        }
+        if (result.copilotReviewInProgress)
+            segs.push(`**copilotReviewInProgress**`);
+        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 [
-                header,
+                verbose ? header : heading,
                 "",
                 result.log,
                 "",
@@ -39,12 +66,6 @@ export function formatIterateResult(result) {
             ];
             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,