pr-shepherd 0.59.2 → 0.60.0

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.59.2",
+  "version": "0.60.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -33,8 +33,8 @@ $ pr-shepherd 123
 
 1. Fix each warranted item.
 2. Triage `## Failing checks`. Playbook: "CI failure triage".
-3. Commit and push any changes.
-4. Journal key decisions or rejections with URLs or IDs: `pr-shepherd apply journal 123 '- <decision>'`
+3. Optional: If you reject a code review suggestion, journal why: `pr-shepherd apply journal 123 '- <reason>'`.
+4. Commit and push any changes.
 5. `$DISMISS_MESSAGE`: one sentence on what changed. Run even if no code changed: `pr-shepherd apply review 123 --reply-thread-ids PRRT_kwDOSGizTs58XB1L --message "$DISMISS_MESSAGE" --require-sha HEAD`
 6. Rerun Shepherd now.
 ```
@@ -151,7 +151,7 @@ See [docs/graphql-usage.md](docs/graphql-usage.md) and [docs/rest-usage.md](docs
 
 1. **Install the MCP server and the CLI.** See [Install](#install) below.
 2. **Write your policy into a skill or agent instruction.** Examples: "skip non-blocking review comments", "reply instead of fixing nits", "never merge". Shepherd reports state and the next action. Your instructions decide how the agent treats each comment. The shipped `pr-shepherd` skill is a thin dispatcher you can wrap ([docs/skills.md](docs/skills.md)).
-3. **Configure Shepherd.** In `.pr-shepherdrc.yml`, turn on the bundled classification rules. They drop known bot noise before it reaches the agent, which saves more tokens and tool calls. With the default `actions.autoMinimizeSuppressed: true`, several rules also minimize matching comments on GitHub and log a Shepherd Journal entry; set it to `false` to keep comments untouched. See [docs/configuration.md](docs/configuration.md#classifystandard--default-).
+3. **Configure Shepherd.** In `.pr-shepherdrc.yml`, turn on the bundled classification rules. They drop known bot noise before it reaches the agent, which saves more tokens and tool calls. With the default `actions.autoMinimizeSuppressed: true`, several rules also minimize matching comments on GitHub and surface the mutation result without editing the PR body. See [docs/configuration.md](docs/configuration.md#classifystandard--default-).
 
    ```yaml
    classify:

package/bin/api.d.mts

@@ -18,7 +18,7 @@ export interface CreatePrShepherdOptions {
 }
 /** A positive PR number, GitHub pull-request URL, or owner/repo#number reference. */
 export type PrReference = number | string;
-type IterateOptions = Omit<IterateCommandOptions, "format" | "prNumber" | "targetRepository" | "persistSeen" | "fingerprintCache" | "stallDeadlineSink" | "deferQuotaWarning" | "quotaWarningMinimumPollIntervalMinutes">;
+type IterateOptions = Omit<IterateCommandOptions, "format" | "prNumber" | "targetRepository" | "persistSeen" | "deferEditedCommentMarkers" | "fingerprintCache" | "stallDeadlineSink" | "deferQuotaWarning" | "quotaWarningMinimumPollIntervalMinutes">;
 export type SingleIterateInput = IterateOptions & {
     pr?: PrReference;
     prs?: never;

package/bin/classify/types.d.mts

@@ -29,7 +29,7 @@ export interface ClassifyAction {
     readonly autoResolve?: boolean;
     /** When true, hides the item from agent output (seen marker is still written). */
     readonly suppress?: boolean;
-    /** Note included in the auto-resolve report, tick line, and Shepherd Journal when this rule fires. */
+    /** Note included in the auto-resolve report and tick line when this rule fires. */
     readonly reason?: string;
 }
 export type ClassifyRule = (item: ClassifyItem) => ClassifyAction | null | undefined;

package/bin/cli/edited-comments-format.d.mts

@@ -0,0 +1,14 @@
+import type { EditedComment } from "../types.mts";
+/** Insert the edited-comments section before `## Instructions` (or append it). */
+export declare function insertEditedCommentsSection(text: string, comments: readonly EditedComment[] | undefined, verbose: boolean): string;
+/** JSON projection matching the text section: the agent comment plus its minimized status. */
+export declare function projectEditedComments(comments: readonly EditedComment[]): {
+    id: string;
+    viewerCanMinimize?: boolean;
+    author: string;
+    authorType?: import("../types.mts").AuthorType;
+    authorAssociation?: import("../types.mts").CommentAuthorAssociation;
+    body: string;
+    url: string;
+    isMinimized?: boolean | undefined;
+}[];

package/bin/cli/edited-comments-format.mjs

@@ -0,0 +1,39 @@
+import { blockquote, renderAuthor } from "./list-formatters.mjs";
+import { BODY_TRUNCATE_MAX_CHARS } from "./body-truncate.mjs";
+import { toAgentComment } from "../reporters/agent.mjs";
+const HEADING = "Edited comments";
+function editedTag(c) {
+    return c.isMinimized ? "[status: minimized, edited]" : "[edited since first look]";
+}
+/** Markdown for `editedComments`; null when there are none. Edits are informational only. */
+function formatEditedCommentsSection(comments, verbose) {
+    if (!comments?.length)
+        return null;
+    const cap = verbose ? undefined : BODY_TRUNCATE_MAX_CHARS;
+    const parts = [
+        `## ${HEADING} (${comments.length}) — informational; edits do not block readiness`,
+    ];
+    for (const c of comments) {
+        const heading = c.url ? `[commentId=${c.id}](${c.url})` : `\`commentId=${c.id}\``;
+        parts.push(`### ${heading} (${renderAuthor(c.author, c.authorType, c.authorAssociation)}) ${editedTag(c)}`);
+        parts.push(blockquote(c.body, cap, c.url));
+    }
+    return parts.join("\n\n");
+}
+/** Insert the edited-comments section before `## Instructions` (or append it). */
+export function insertEditedCommentsSection(text, comments, verbose) {
+    const section = formatEditedCommentsSection(comments, verbose);
+    if (!section)
+        return text;
+    const index = text.lastIndexOf("## Instructions");
+    if (index === -1)
+        return `${text}\n\n${section}`;
+    return `${text.slice(0, index)}${section}\n\n${text.slice(index)}`;
+}
+/** JSON projection matching the text section: the agent comment plus its minimized status. */
+export function projectEditedComments(comments) {
+    return comments.map((c) => ({
+        ...toAgentComment(c),
+        ...(c.isMinimized && { isMinimized: true }),
+    }));
+}

package/bin/cli/fix-formatter.mjs

@@ -13,6 +13,10 @@ export function formatFixCodeResult(header, result, opts = {}) {
     const verbose = opts.verbose ?? false;
     const topCap = verbose ? undefined : BODY_TRUNCATE_MAX_CHARS;
     const sections = [header];
+    if (result.fix.reviewItems) {
+        const { shown, total } = result.fix.reviewItems;
+        sections.push(`**showing** ${shown} of ${total} review items`);
+    }
     if (result.mergedBasePullRequests?.length) {
         sections.push("## Merged PRs matching the current base");
         sections.push(result.mergedBasePullRequests
@@ -50,9 +54,8 @@ 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}\``;
-            const editedMarker = c.edited ? " [edited since first look]" : "";
             const authorizationMarker = c.viewerCanMinimize === false ? " [viewer cannot minimize]" : "";
-            sections.push(`### ${heading} (${renderAuthor(c.author, c.authorType, c.authorAssociation)})${authorizationMarker}${editedMarker}`);
+            sections.push(`### ${heading} (${renderAuthor(c.author, c.authorType, c.authorAssociation)})${authorizationMarker}`);
             sections.push(blockquote(c.body, topCap, c.url));
         }
     }

package/bin/cli/iterate-activity-formatter.d.mts

@@ -1,2 +1,2 @@
 import type { IterateResult } from "../types.mts";
-export declare function formatActivityLine(result: IterateResult): string | null;
+export declare function formatActivityLine(result: IterateResult, verbose?: boolean): string | null;

package/bin/cli/iterate-activity-formatter.mjs

@@ -1,4 +1,5 @@
-export function formatActivityLine(result) {
+import { formatNameList } from "./iterate-check-names.mjs";
+export function formatActivityLine(result, verbose = false) {
     const activity = result.activity ?? {
         commitCount: 0,
         reviewRoundCount: 0,
@@ -17,10 +18,8 @@ export function formatActivityLine(result) {
         parts.push(`${activity.reviewItemsSinceLatestCommit.length} review items since latest commit`);
     }
     if (hasActiveChecks) {
-        parts.push(`active: ${result
-            .inProgressChecks.slice(0, 5)
-            .map((check) => `\`${check.name}\``)
-            .join(", ")}`);
+        const names = result.inProgressChecks.map((check) => check.name);
+        parts.push(`active: ${formatNameList(names, verbose)}`);
     }
     return `**activity** ${parts.join(" · ")}`;
 }

package/bin/cli/iterate-check-names.d.mts

@@ -0,0 +1,5 @@
+import type { IterateResult } from "../types.mts";
+/** Backticked inline name list; lean output caps it and appends `+N more`. */
+export declare function formatNameList(names: readonly string[], verbose: boolean): string;
+/** `**ignored**` and `**superseded**` header lines, omitted when their lists are empty. */
+export declare function formatSuppressedNameLines(result: IterateResult, verbose: boolean): string[];

package/bin/cli/iterate-check-names.mjs

@@ -0,0 +1,17 @@
+import { capList, moreSuffix } from "../util/cap-list.mjs";
+/** Backticked inline name list; lean output caps it and appends `+N more`. */
+export function formatNameList(names, verbose) {
+    const { shown, hidden } = verbose ? { shown: names, hidden: 0 } : capList(names);
+    return shown.map((n) => "`" + n + "`").join(", ") + moreSuffix(hidden);
+}
+/** `**ignored**` and `**superseded**` header lines, omitted when their lists are empty. */
+export function formatSuppressedNameLines(result, verbose) {
+    const lines = [];
+    if (result.ignoredNames && result.ignoredNames.length > 0) {
+        lines.push(`**ignored** ${formatNameList(result.ignoredNames, verbose)}`);
+    }
+    if (result.supersededNames && result.supersededNames.length > 0) {
+        lines.push(`**superseded** ${formatNameList(result.supersededNames, verbose)}`);
+    }
+    return lines;
+}

package/bin/cli/iterate-formatter.mjs

@@ -1,3 +1,5 @@
+/* eslint-disable max-lines */
+import { insertEditedCommentsSection } from "./edited-comments-format.mjs";
 import { formatFixCodeResult } from "./fix-formatter.mjs";
 import { formatRelevantChecks } from "./iterate-checks-formatter.mjs";
 import { joinSections } from "../util/markdown.mjs";
@@ -6,6 +8,7 @@ import { formatMergeRequirementLines } from "../merge-status/requirements-format
 import { appendMergeQueueHeader, formatDeferredWorkLine, formatMergeAction, } from "./iterate-merge-formatter.mjs";
 import { formatApiUsage, formatQuotaWarning } from "./api-usage-formatter.mjs";
 import { formatActivityLine } from "./iterate-activity-formatter.mjs";
+import { formatSuppressedNameLines } from "./iterate-check-names.mjs";
 import { branchStateSegment } from "./iterate-branch-segment.mjs";
 import { insertRuleAutoResolveSection } from "../commands/rule-auto-resolve-format.mjs";
 import { formatTransportEvidence } from "./transport-formatter.mjs";
@@ -41,7 +44,7 @@ export function formatIterateResult(result, opts) {
                 instructions.includes(`--repo ${result.repo} `));
         return generated ? full.replace(repoSeg, "") : full;
     };
-    const finish = (text) => dropRepeatedRepo(insertRuleAutoResolveSection(text, result.ruleAutoResolve));
+    const finish = (text) => dropRepeatedRepo(insertEditedCommentsSection(insertRuleAutoResolveSection(text, result.ruleAutoResolve), result.editedComments, verbose));
     const heading = `# PR #${result.pr} [${result.action.toUpperCase()}]`;
     const reviewDecisionSeg = result.mergeStatus === "BLOCKED" && result.reviewDecision
         ? ` · **reviewDecision** \`${result.reviewDecision}\``
@@ -57,7 +60,7 @@ export function formatIterateResult(result, opts) {
     let summaryLine;
     if (verbose) {
         const verboseBranch = branchSeg ? ` · ${branchSeg}` : "";
-        summaryLine = `**summary** ${result.summary.passing} passing, ${result.summary.skipped} skipped, ${result.summary.filtered} filtered, ${result.summary.inProgress} inProgress, ${result.summary.superseded} superseded · **remainingSeconds** ${result.remainingSeconds} · **blockingBotReviewInProgress** ${result.blockingBotReviewInProgress} · **isDraft** ${result.isDraft} · **shouldCancel** ${result.shouldCancel}${verboseBranch}${readyDelaySuffix ? ` · **ready-delay** \`${readyDelaySuffix}\` (override)` : ""}`;
+        summaryLine = `**summary** ${result.summary.passing} passing, ${result.summary.skipped} skipped, ${result.summary.filtered} filtered, ${result.summary.inProgress} inProgress, ${result.summary.queued} queued, ${result.summary.superseded} superseded · **remainingSeconds** ${result.remainingSeconds} · **blockingBotReviewInProgress** ${result.blockingBotReviewInProgress} · **isDraft** ${result.isDraft} · **shouldCancel** ${result.shouldCancel}${verboseBranch}${readyDelaySuffix ? ` · **ready-delay** \`${readyDelaySuffix}\` (override)` : ""}`;
     }
     else {
         const counts = [];
@@ -69,6 +72,8 @@ export function formatIterateResult(result, opts) {
             counts.push(`${result.summary.filtered} filtered`);
         if (result.summary.inProgress > 0)
             counts.push(`${result.summary.inProgress} inProgress`);
+        if (result.summary.queued > 0)
+            counts.push(`${result.summary.queued} queued`);
         if (result.summary.superseded > 0)
             counts.push(`${result.summary.superseded} superseded`);
         const segs = counts.length > 0 ? [`**summary** ${counts.join(", ")}`] : [];
@@ -114,17 +119,10 @@ export function formatIterateResult(result, opts) {
     else if (requiredLine) {
         headerLines.push(requiredLine);
     }
-    if (result.ignoredNames && result.ignoredNames.length > 0) {
-        const names = result.ignoredNames.map((n) => "`" + n + "`").join(", ");
-        headerLines.push(`**ignored** ${names}`);
-    }
-    if (result.supersededNames && result.supersededNames.length > 0) {
-        const names = result.supersededNames.map((n) => "`" + n + "`").join(", ");
-        headerLines.push(`**superseded** ${names}`);
-    }
+    headerLines.push(...formatSuppressedNameLines(result, verbose));
     appendUnreportedLines(headerLines, result);
     appendMergeQueueHeader(headerLines, result);
-    const activityLine = formatActivityLine(result);
+    const activityLine = formatActivityLine(result, verbose);
     if (activityLine)
         headerLines.push(activityLine);
     headerLines.push(...formatNextCheckLines(result.nextCheck));
@@ -176,14 +174,7 @@ export function formatIterateResult(result, opts) {
             else if (requiredLine) {
                 cancelHeaderLines.push(requiredLine);
             }
-            if (result.ignoredNames && result.ignoredNames.length > 0) {
-                const ignoredStr = result.ignoredNames.map((n) => "`" + n + "`").join(", ");
-                cancelHeaderLines.push(`**ignored** ${ignoredStr}`);
-            }
-            if (result.supersededNames && result.supersededNames.length > 0) {
-                const supersededStr = result.supersededNames.map((n) => "`" + n + "`").join(", ");
-                cancelHeaderLines.push(`**superseded** ${supersededStr}`);
-            }
+            cancelHeaderLines.push(...formatSuppressedNameLines(result, verbose));
             appendUnreportedLines(cancelHeaderLines, result);
             appendMergeQueueHeader(cancelHeaderLines, result);
             if (activityLine)
@@ -198,6 +189,11 @@ export function formatIterateResult(result, opts) {
         case "escalate":
             return finish(joinSections([
                 header,
+                ...(result.escalate.reviewItems
+                    ? [
+                        `**showing** ${result.escalate.reviewItems.shown} of ${result.escalate.reviewItems.total} review items`,
+                    ]
+                    : []),
                 ...(apiUsage ? [apiUsage] : []),
                 ...(verboseChecks ? [verboseChecks] : []),
                 result.escalate.humanMessage,

package/bin/cli/iterate-lean.mjs

@@ -1,8 +1,10 @@
 import { adaptIterateLog, buildSimpleIterateInstructions } from "./iterate-instructions.mjs";
 import { projectRuleAutoResolve } from "../commands/rule-auto-resolve-format.mjs";
+import { projectEditedComments } from "./edited-comments-format.mjs";
 import { projectMergeRequirements } from "../merge-status/requirements-format.mjs";
 import { branchSegmentShowsBase } from "./iterate-branch-segment.mjs";
 import { isRedundantMergeQueue } from "./iterate-merge-formatter.mjs";
+import { capList } from "../util/cap-list.mjs";
 /**
  * Project an IterateResult to a lean JSON shape for the default (non-verbose) output.
  * Omits fields that are the trivial default (false, 0, empty) or state-gated fields
@@ -31,7 +33,7 @@ export function projectIterateLean(result, opts) {
             }),
         };
     }
-    const counts = Object.fromEntries(["passing", "skipped", "filtered", "inProgress", "superseded"]
+    const counts = Object.fromEntries(["passing", "skipped", "filtered", "inProgress", "queued", "superseded"]
         .filter((k) => result.summary[k] > 0)
         .map((k) => [k, result.summary[k]]));
     const summary = Object.keys(counts).length > 0 ? counts : null;
@@ -82,15 +84,9 @@ export function projectIterateLean(result, opts) {
                 }),
             },
         }),
-        ...((result.inProgressChecks?.length ?? 0) > 0 && {
-            inProgressChecks: result.inProgressChecks,
-        }),
-        ...((result.ignoredNames?.length ?? 0) > 0 && {
-            ignoredNames: result.ignoredNames,
-        }),
-        ...((result.supersededNames?.length ?? 0) > 0 && {
-            supersededNames: result.supersededNames,
-        }),
+        ...cappedList("inProgressChecks", result.inProgressChecks),
+        ...cappedList("ignoredNames", result.ignoredNames),
+        ...cappedList("supersededNames", result.supersededNames),
         ...((result.unreportedRequiredChecks?.length ?? 0) > 0 && {
             unreportedRequiredChecks: result.unreportedRequiredChecks,
         }),
@@ -104,6 +100,9 @@ export function projectIterateLean(result, opts) {
         ...(result.ruleAutoResolve && {
             ruleAutoResolve: projectRuleAutoResolve(result.ruleAutoResolve),
         }),
+        ...(result.editedComments?.length && {
+            editedComments: projectEditedComments(result.editedComments),
+        }),
     };
     switch (result.action) {
         case "ready":
@@ -144,7 +143,7 @@ export function projectIterateLean(result, opts) {
         case "fix_code":
             return {
                 ...base,
-                ...(result.checks.length > 0 && { checks: result.checks }),
+                // Passing checks stay summary counts and failures stay in `fix.checks`, as in lean text.
                 ...(result.cancelled.length > 0 && { cancelled: result.cancelled }),
                 fix: {
                     ...(result.fix.threads.length > 0 && { threads: result.fix.threads }),
@@ -190,6 +189,7 @@ export function projectIterateLean(result, opts) {
                     ...(result.fix.resolveOnlyCommand && {
                         resolveOnlyCommand: result.fix.resolveOnlyCommand,
                     }),
+                    ...(result.fix.reviewItems && { reviewItems: result.fix.reviewItems }),
                     ...(result.fix.instructions.length > 0 && {
                         instructions: result.fix.instructions,
                     }),
@@ -229,6 +229,7 @@ export function projectIterateLean(result, opts) {
                         result.escalate.thrashHistory.length > 0 && {
                         thrashHistory: result.escalate.thrashHistory,
                     }),
+                    ...(result.escalate.reviewItems && { reviewItems: result.escalate.reviewItems }),
                     ...(result.escalate.mergeQueueRemoval && {
                         mergeQueueRemoval: result.escalate.mergeQueueRemoval,
                     }),
@@ -246,4 +247,11 @@ export function projectIterateLean(result, opts) {
             };
     }
 }
+/** `{ [key]: first 5, [key + "More"]: hidden count }`, matching the capped Markdown lists. */
+function cappedList(key, items) {
+    if (!items || items.length === 0)
+        return {};
+    const { shown, hidden } = capList(items);
+    return { [key]: shown, ...(hidden > 0 && { [`${key}More`]: hidden }) };
+}
 export { projectIterateVerbose } from "./iterate-verbose.mjs";

package/bin/cli/iterate-verbose.mjs

@@ -1,11 +1,16 @@
 import { adaptIterateLog, buildSimpleIterateInstructions } from "./iterate-instructions.mjs";
+import { projectEditedComments } from "./edited-comments-format.mjs";
 export function projectIterateVerbose(result, opts) {
     const readyDelaySuffix = opts?.readyDelaySuffix;
     const readyDelayOverride = readyDelaySuffix ? { readyDelayOverride: readyDelaySuffix } : {};
+    // Edited comments use the lean projection: their bookkeeping fields have no Markdown form.
+    const edited = result.editedComments && {
+        editedComments: projectEditedComments(result.editedComments),
+    };
     if (result.action === "fix_code")
-        return { ...result, ...readyDelayOverride };
+        return { ...result, ...readyDelayOverride, ...edited };
     const log = "log" in result && typeof result.log === "string" ? { log: adaptIterateLog(result.log) } : {};
     // `cancel` has no instructions, so verbose JSON omits the field as verbose Markdown omits the section.
     const instructions = result.action === "cancel" ? {} : { instructions: buildSimpleIterateInstructions(result) };
-    return { ...result, ...log, ...readyDelayOverride, ...instructions };
+    return { ...result, ...log, ...readyDelayOverride, ...instructions, ...edited };
 }

package/bin/cli/list-formatters.d.mts

@@ -49,9 +49,6 @@ export declare function renderCommentBullet(c: {
 }, opts?: {
     statusTag?: string;
 }): string;
-export declare function renderEditedCommentTag(c: {
-    edited?: boolean;
-}): string | undefined;
 export declare function renderReviewBullet(r: {
     id: string;
     author: string;

package/bin/cli/list-formatters.mjs

@@ -101,9 +101,6 @@ export function renderCommentBullet(c, opts = {}) {
     const statusSuffix = opts.statusTag ? ` ${opts.statusTag}` : "";
     return `- \`commentId=${c.id}\`${link} (${renderAuthor(c.author, c.authorType, c.authorAssociation)})${statusSuffix}: ${renderBodyPreview(c.body)}`;
 }
-export function renderEditedCommentTag(c) {
-    return c.edited ? "[edited since first look]" : undefined;
-}
 export function renderReviewBullet(r, opts = {}) {
     const base = `- \`reviewId=${r.id}\` (${renderAuthor(r.author, r.authorType, r.authorAssociation)})`;
     const staleTag = r.staleReview
@@ -138,8 +135,7 @@ export function buildFirstLookBullets(firstLookThreads, resolutionOnlyIds, first
         }));
     }
     for (const c of firstLookComments) {
-        const editedSuffix = c.edited ? ", edited" : "";
-        bullets.push(renderCommentBullet(c, { statusTag: `[status: minimized${editedSuffix}]` }));
+        bullets.push(renderCommentBullet(c, { statusTag: "[status: minimized]" }));
     }
     return bullets;
 }

package/bin/commands/check-review-budget.d.mts

@@ -0,0 +1,39 @@
+import { type ReviewItemRollup } from "../comments/review-output-budget.mts";
+import type { ActionableComment, EditedComment, FirstLookComment, FirstLookThread, Review, ReviewThread } from "../types.mts";
+/** Every check.mts list that renders a review item, generates a mutation for it, or marks it seen. */
+export interface ReviewOutputBuckets {
+    changesRequested: {
+        visible: Review[];
+        toMarkSeen: Review[];
+    };
+    threads: {
+        activeThreads: ReviewThread[];
+        resolutionOnlyThreads: ReviewThread[];
+        firstLookThreads: FirstLookThread[];
+        toMarkSeen: ReviewThread[];
+    };
+    comments: {
+        actionable: ActionableComment[];
+        minimizeIds: string[];
+        toMarkSeen: ActionableComment[];
+    };
+    firstLookComments: FirstLookComment[];
+    firstLookSummaries: Review[];
+    editedSummaries: Review[];
+    editedComments: EditedComment[];
+}
+/**
+ * Applies `iterate.reviewOutputMaxChars` to one tick's review buckets. Priority: changes-requested
+ * reviews, active threads and comments, first-look items, review summaries, edited comments.
+ * Approved reviews are opt-in minimize targets, not review work, and are never held.
+ * Held items leave every list — the report, the generated mutation IDs, and the seen-marker
+ * writes — so the next tick shows them. `rollup` is set only when something was held.
+ * Edited comments are held only alongside other held work: edits never block readiness, so a
+ * ready or terminal tick must not leave some of them unshown. `heldThreadReviewIds` names the
+ * parent reviews of held unresolved threads, which must not be minimized while those wait.
+ */
+export declare function applyReviewOutputBudget(buckets: ReviewOutputBuckets, maxChars: number): {
+    buckets: ReviewOutputBuckets;
+    rollup?: ReviewItemRollup;
+    heldThreadReviewIds?: string[];
+};

package/bin/commands/check-review-budget.mjs

@@ -0,0 +1,78 @@
+import { selectReviewOutput, } from "../comments/review-output-budget.mjs";
+import { threadTranscriptBody } from "../threads/transcript.mjs";
+const bodyItem = (item) => ({
+    id: item.id,
+    cost: item.body.length,
+    ...(item.createdAtUnix !== undefined && { createdAtUnix: item.createdAtUnix }),
+});
+const threadItem = (thread) => ({
+    ...bodyItem(thread),
+    cost: threadTranscriptBody(thread).length,
+});
+/**
+ * Applies `iterate.reviewOutputMaxChars` to one tick's review buckets. Priority: changes-requested
+ * reviews, active threads and comments, first-look items, review summaries, edited comments.
+ * Approved reviews are opt-in minimize targets, not review work, and are never held.
+ * Held items leave every list — the report, the generated mutation IDs, and the seen-marker
+ * writes — so the next tick shows them. `rollup` is set only when something was held.
+ * Edited comments are held only alongside other held work: edits never block readiness, so a
+ * ready or terminal tick must not leave some of them unshown. `heldThreadReviewIds` names the
+ * parent reviews of held unresolved threads, which must not be minimized while those wait.
+ */
+export function applyReviewOutputBudget(buckets, maxChars) {
+    const { changesRequested, threads, comments } = buckets;
+    const selection = selectReviewOutput([
+        changesRequested.visible.map(bodyItem),
+        [
+            ...threads.activeThreads.map(threadItem),
+            ...threads.resolutionOnlyThreads.map(threadItem),
+            ...comments.actionable.map(bodyItem),
+        ],
+        [...threads.firstLookThreads.map(threadItem), ...buckets.firstLookComments.map(bodyItem)],
+        [...buckets.firstLookSummaries.map(bodyItem), ...buckets.editedSummaries.map(bodyItem)],
+        buckets.editedComments.map(bodyItem),
+    ], maxChars);
+    if (selection.rollup === undefined)
+        return { buckets };
+    const nonEditedIds = [
+        ...changesRequested.visible,
+        ...threads.activeThreads,
+        ...threads.resolutionOnlyThreads,
+        ...comments.actionable,
+        ...threads.firstLookThreads,
+        ...buckets.firstLookComments,
+        ...buckets.firstLookSummaries,
+        ...buckets.editedSummaries,
+    ].map((item) => item.id);
+    if (nonEditedIds.every(selection.keep))
+        return { buckets };
+    const heldThreadReviewIds = [...threads.activeThreads, ...threads.resolutionOnlyThreads]
+        .filter((thread) => !selection.keep(thread.id))
+        .flatMap((thread) => (thread.reviewId !== undefined ? [thread.reviewId] : []));
+    const keep = (items) => items.filter((item) => selection.keep(item.id));
+    return {
+        buckets: {
+            changesRequested: {
+                visible: keep(changesRequested.visible),
+                toMarkSeen: keep(changesRequested.toMarkSeen),
+            },
+            threads: {
+                activeThreads: keep(threads.activeThreads),
+                resolutionOnlyThreads: keep(threads.resolutionOnlyThreads),
+                firstLookThreads: keep(threads.firstLookThreads),
+                toMarkSeen: keep(threads.toMarkSeen),
+            },
+            comments: {
+                actionable: keep(comments.actionable),
+                minimizeIds: comments.minimizeIds.filter(selection.keep),
+                toMarkSeen: keep(comments.toMarkSeen),
+            },
+            firstLookComments: keep(buckets.firstLookComments),
+            firstLookSummaries: keep(buckets.firstLookSummaries),
+            editedSummaries: keep(buckets.editedSummaries),
+            editedComments: keep(buckets.editedComments),
+        },
+        rollup: selection.rollup,
+        ...(heldThreadReviewIds.length > 0 && { heldThreadReviewIds }),
+    };
+}

package/bin/commands/check-wait-detectors.d.mts

@@ -10,7 +10,11 @@ type StateKey = {
 /**
  * Outcome of the GraphQL transport's REST change detectors. `reused` replays the stored report
  * without any GraphQL request. Otherwise `digest` is what the detectors read before this tick's
- * GraphQL snapshot, recorded beside the new report by `recordWaitDetectors`.
+ * GraphQL snapshot, recorded beside the new report by `recordWaitDetectors`. `changed` is set
+ * when this read differs from the digest stored beside the report, or no digest is stored yet
+ * (the seeding tick): the stored report may predate what the detectors saw, so the tick must
+ * not reuse it through the GraphQL fingerprint either. A same-digest read past
+ * `poll.reconcileSeconds` leaves `changed` unset.
  */
 export type WaitDetectorResult = {
     reused: ShepherdReport;
@@ -18,6 +22,7 @@ export type WaitDetectorResult = {
 } | {
     digest: string;
     readAt: number;
+    changed?: true;
 };
 /**
  * On the GraphQL transport, run the REST change detectors for an idle stored report. Returns

package/bin/commands/check-wait-detectors.mjs

@@ -83,7 +83,8 @@ export async function readWaitDetectors(prNumber, repo, stateKey, config, now =
             baseTipOid: observed.baseTipOid,
         };
     }
-    return { digest: state.digest, readAt: now };
+    const changed = previous?.digest !== state.digest;
+    return { digest: state.digest, readAt: now, ...(changed && { changed: true }) };
 }
 /**
  * After a GraphQL tick, store the digest its detectors read beside the report that tick built.

package/bin/commands/check.d.mts

@@ -7,6 +7,8 @@ type CheckOptions = GlobalOptions & {
     persistSeen?: boolean;
     fingerprintCache?: boolean;
     merge?: boolean;
+    /** Per-tick review-item body budget (`iterate.reviewOutputMaxChars`). Omitted or 0: no cap. */
+    reviewOutputMaxChars?: number;
 };
 export declare function runCheck(opts: CheckOptions, context?: CheckExecutionContext): Promise<ShepherdReport>;
 export {};