pr-shepherd 0.60.1 → 1.1.0

package/bin/cli-parser.mjs

@@ -1,24 +1,25 @@
 /* eslint-disable max-lines */
 /** CLI argument parsing and subcommand dispatch for pr-shepherd. See --help for usage. */
 import { readFileSync } from "node:fs";
-import { EXIT, applyReviewResultToExitCode, errorToExitCode } from "./exit-codes.mjs";
+import { EXIT, ShepherdError, applyReviewResultToExitCode, errorToExitCode, } from "./exit-codes.mjs";
+import { loadConfig } from "./config/load.mjs";
 import { runResolveMutate } from "./commands/resolve.mjs";
 import { runLogFile } from "./commands/log-file.mjs";
 import { handleClean } from "./cli/clean-handler.mjs";
 import { parseCommonArgs, getFlag, hasFlag, parseList } from "./cli/args.mjs";
+import { rejectUnknownFlags } from "./cli/unknown-flags.mjs";
 import { isDefaultPollInvocation, validateDefaultPollArgs } from "./cli/default-poll.mjs";
 import { USAGE, helpKeyForArgs, maybePrintHelp } from "./cli/help.mjs";
 import { formatMutateResult } from "./cli/formatters.mjs";
-import { handleCommitSuggestion, handleSuggestionPatches, handleIterate, handleMarkFilesAsViewed, } from "./cli/handlers.mjs";
+import { handleSuggest, handleIterate, handleMarkFilesAsViewed } from "./cli/handlers.mjs";
 import { handleJournal } from "./cli/journal-handler.mjs";
 import { handleJournalExtract } from "./cli/journal-extract-handler.mjs";
 import { handlePlaybook } from "./cli/playbook-handler.mjs";
-import { handlePoll } from "./cli/poll-handler.mjs";
+import { handlePoll, handleStack } from "./cli/poll-handler.mjs";
 import { warnPrrcThreadIds, validateRequireSha, rejectPrrcMinimizeIds, } from "./cli/resolve-validators.mjs";
 import { handleCheckBlocker } from "./cli/check-blocker-handler.mjs";
 import { handleQueueRemoval } from "./cli/queue-removal-handler.mjs";
 import { setupLog } from "./log/setup.mjs";
-import { rejectInvalidPollModeFlag, runInEventStateScope, runInPollModeScope, } from "./cli/event-state-scope.mjs";
 import { handleApplyMerge } from "./cli/apply-merge-handler.mjs";
 import { getLocalHeadSha } from "./commands/suggestion-patch-git.mjs";
 import { extractTransportArgs } from "./cli/transport-args.mjs";
@@ -34,7 +35,6 @@ export async function main(argv) {
     if (extracted.args.some((arg) => arg === "--help" || arg === "-h") ||
         extracted.args[0] === "--version" ||
         extracted.args[0] === "-v" ||
-        extracted.args[0] === "log-file" ||
         extracted.args[0] === "playbook" ||
         (extracted.args[0] === "admin" && extracted.args[1] === "log-file") ||
         (extracted.args[0] === "journal" && extracted.args[1] === "extract")) {
@@ -50,6 +50,17 @@ export async function main(argv) {
         process.exitCode = EXIT.USAGE;
         return;
     }
+    // Validate config before any GitHub work, so a bad or pre-v1 config file exits 78 up front.
+    try {
+        loadConfig();
+    }
+    catch (error) {
+        if (!(error instanceof ShepherdError))
+            throw error;
+        process.stderr.write(`pr-shepherd: ${error.message}\n`);
+        process.exitCode = error.exitCode;
+        return;
+    }
     return runWithGithubTransport(mode, () => dispatch(dispatched), {
         verbose: extracted.args.includes("--verbose"),
     });
@@ -65,12 +76,7 @@ async function dispatch(argv) {
         process.stdout.write(`${USAGE.top}\n`);
         return;
     }
-    // log-file must run before the stdout tee and log init to avoid recursion.
-    if (subcommand === "log-file") {
-        await handleLogFile(args.slice(1));
-        return;
-    }
-    // Extraction deliberately precedes legacy warnings and logging: it is a local,
+    // Extraction deliberately precedes logging: it is a local,
     // GitHub/config/log-free read path for automation that already has a PR body.
     if (subcommand === "journal" && args[1] === "extract") {
         await handleJournalExtract(args.slice(2));
@@ -80,7 +86,7 @@ async function dispatch(argv) {
     // command namespace. Keep this before setupLog because log-file reads the
     // log path and must not initialize/tee the log it is reporting.
     if (subcommand === "admin" && args[1] === "log-file") {
-        await handleLogFile(args.slice(2), "admin log-file");
+        await handleLogFile(args.slice(2));
         return;
     }
     // Short-circuit all --help/-h before any I/O or logging.
@@ -93,24 +99,12 @@ async function dispatch(argv) {
         }
         return;
     }
-    const legacyReplacement = {
-        poll: "pr-shepherd [PR] (the default PR polling command)",
-        resolve: "apply review",
-        "mark-files-as-viewed": "apply files",
-        journal: "apply journal",
-        "build-suggestion-patch": "build-suggestion-patches",
-        "commit-suggestion": "build-suggestion-patches",
-    };
-    if (subcommand !== undefined && legacyReplacement[subcommand] !== undefined) {
-        warnLegacyAlias(subcommand, legacyReplacement[subcommand]);
-    }
     // A local read of shipped files: no GitHub, git, or log I/O.
     if (subcommand === "playbook") {
         handlePlaybook(args.slice(1));
         return;
     }
-    // Event mode enters the durable state scope before the log resolves its path.
-    return runInEventStateScope(args, () => dispatchLogged(argv));
+    return dispatchLogged(argv);
 }
 async function dispatchLogged(argv) {
     const args = argv.slice(2);
@@ -127,36 +121,18 @@ async function dispatchLogged(argv) {
         case "apply":
             await handleApply(args.slice(1));
             break;
-        case "build-suggestion-patches":
-            await handleSuggestionPatches(args.slice(1));
+        case "suggest":
+            await handleSuggest(args.slice(1));
             break;
-        case "build-suggestion-patch":
-            await handleCommitSuggestion(args.slice(1));
+        case "stack":
+            await handleStack(args.slice(1));
             break;
         case "admin":
             await handleAdmin(args.slice(1));
             break;
-        case "resolve":
-            await handleResolve(args.slice(1), "resolve");
-            break;
-        case "commit-suggestion":
-            await handleCommitSuggestion(args.slice(1), "commit-suggestion");
-            break;
-        case "mark-files-as-viewed":
-            await handleMarkFilesAsViewed(args.slice(1), "mark-files-as-viewed");
-            break;
         case "iterate":
             await handleIterate(args.slice(1));
             break;
-        case "poll":
-            await handlePoll(args.slice(1));
-            break;
-        case "clean":
-            await handleClean(args.slice(1), "clean");
-            break;
-        case "journal":
-            await handleJournal(args.slice(1), "journal");
-            break;
         default:
             process.stderr.write(`Unknown subcommand: ${subcommand ?? "(none)"}\n`);
             process.stderr.write(`${USAGE.top}\n`);
@@ -164,9 +140,6 @@ async function dispatchLogged(argv) {
             return;
     }
 }
-function warnLegacyAlias(alias, replacement) {
-    process.stderr.write(`pr-shepherd: ${alias} is deprecated; use ${replacement.startsWith("pr-shepherd") ? replacement : `pr-shepherd ${replacement}`} instead.\n`);
-}
 async function handleApply(args) {
     const action = args[0];
     switch (action) {
@@ -213,10 +186,10 @@ function readVersion() {
 // ---------------------------------------------------------------------------
 // Subcommand handlers
 // ---------------------------------------------------------------------------
-async function handleLogFile(args, usageKey = "log-file") {
-    if (maybePrintHelp(args, usageKey))
+async function handleLogFile(args) {
+    if (maybePrintHelp(args, "admin log-file"))
         return;
-    if (rejectInvalidPollModeFlag(args, usageKey))
+    if (rejectUnknownFlags(args, "admin log-file", []))
         return;
     const jsonOut = args.some((a) => a === "--format=json") ||
         (() => {
@@ -224,16 +197,27 @@ async function handleLogFile(args, usageKey = "log-file") {
             return idx !== -1 && args[idx + 1] === "json";
         })();
     try {
-        // Report the log the matching tick writes: event mode keeps it in durable state.
-        const result = await runInPollModeScope(args, () => runLogFile());
+        const result = await runLogFile();
         process.stdout.write(jsonOut ? `${JSON.stringify(result, null, 2)}\n` : `${result.path}\n`);
     }
     catch (e) {
-        process.stderr.write(`pr-shepherd: log-file: ${String(e)}\n`);
+        process.stderr.write(`pr-shepherd: admin log-file: ${String(e)}\n`);
         process.exitCode = errorToExitCode(e);
     }
 }
-async function handleResolve(args, command = "apply review") {
+const APPLY_REVIEW_FLAGS = [
+    "--resolve-thread-ids",
+    "--reply-thread-ids",
+    "--minimize-comment-ids",
+    "--dismiss-review-ids",
+    "--message",
+    "--require-sha",
+    "--adopt-existing-replies",
+];
+async function handleResolve(args) {
+    const command = "apply review";
+    if (rejectUnknownFlags(args, command, APPLY_REVIEW_FLAGS))
+        return;
     const { prNumber, global: globalOpts, extra } = parseCommonArgs(args);
     const resolveThreadIds = parseList(getFlag(extra, "--resolve-thread-ids"));
     const replyThreadIds = parseList(getFlag(extra, "--reply-thread-ids"));
@@ -247,11 +231,6 @@ async function handleResolve(args, command = "apply review") {
         return;
     if (rejectPrrcMinimizeIds(minimizeCommentIds).length > 0)
         return;
-    if (hasFlag(extra, "--fetch")) {
-        process.stderr.write(`pr-shepherd: ${command}: --fetch has been removed; run pr-shepherd iterate to fetch the next action.\n`);
-        process.exitCode = EXIT.USAGE;
-        return;
-    }
     const hasAction = resolveThreadIds.length > 0 ||
         replyThreadIds.length > 0 ||
         minimizeCommentIds.length > 0 ||

package/bin/commands/check-activity.d.mts

@@ -0,0 +1,8 @@
+import type { BatchPartition } from "../classify/apply.mts";
+import type { PrActivitySummary } from "../types.mts";
+/**
+ * Drop rule-suppressed items from the activity digest, matching what `check` hides from the
+ * agent. IDs whose automatic minimize/resolve was denied stay visible: `check` surfaces those
+ * once so the caller can act. `reviewRoundCount` is raw review history and stays unchanged.
+ */
+export declare function filterSuppressedActivity(activity: PrActivitySummary | undefined, partition: BatchPartition, denied: Iterable<string>): PrActivitySummary | undefined;

package/bin/commands/check-activity.mjs

@@ -0,0 +1,26 @@
+/**
+ * Drop rule-suppressed items from the activity digest, matching what `check` hides from the
+ * agent. IDs whose automatic minimize/resolve was denied stay visible: `check` surfaces those
+ * once so the caller can act. `reviewRoundCount` is raw review history and stays unchanged.
+ */
+export function filterSuppressedActivity(activity, partition, denied) {
+    if (!activity)
+        return activity;
+    const deniedIds = new Set(denied);
+    const hidden = (id, suppressed) => suppressed.has(id) && !deniedIds.has(id);
+    const reviewItemsSinceLatestCommit = activity.reviewItemsSinceLatestCommit.filter((item) => {
+        switch (item.kind) {
+            case "pr-comment":
+                return !hidden(item.id, partition.suppressedCommentIds);
+            case "review-thread-comment":
+                return !item.threadId || !hidden(item.threadId, partition.suppressedThreadIds);
+            case "review-summary":
+                return !hidden(item.id, partition.suppressedReviewSummaryIds);
+            case "changes-requested-review":
+                return !partition.suppressedChangesRequestedIds.has(item.id);
+            default:
+                return true;
+        }
+    });
+    return { ...activity, reviewItemsSinceLatestCommit };
+}

package/bin/commands/check-annotations.d.mts

@@ -6,7 +6,7 @@ export declare function checksWithActionableAnnotations(report: ShepherdReport):
  * check, an unseen check-run annotation, or a hard merge conflict) — the categories that
  * `commands/iterate/index.mts` never defers while a PR is queued. Shared with `check.mts` so
  * the seen-marker suppression gate there can't drift from the actual iterate dispatch
- * decision (a queued PR with a failing check still renders review items via `fix_code`; their
+ * decision (a queued PR with a failing check still renders review items via `triage`; their
  * seen markers must not be suppressed just because the PR happens to be queued).
  */
 export declare function hasCheckDrivenActionableWork(checks: {

package/bin/commands/check-annotations.mjs

@@ -20,7 +20,7 @@ export function checksWithActionableAnnotations(report) {
  * check, an unseen check-run annotation, or a hard merge conflict) — the categories that
  * `commands/iterate/index.mts` never defers while a PR is queued. Shared with `check.mts` so
  * the seen-marker suppression gate there can't drift from the actual iterate dispatch
- * decision (a queued PR with a failing check still renders review items via `fix_code`; their
+ * decision (a queued PR with a failing check still renders review items via `triage`; their
  * seen markers must not be suppressed just because the PR happens to be queued).
  */
 export function hasCheckDrivenActionableWork(checks, mergeStatusValue) {
@@ -42,7 +42,8 @@ export async function attachAndMergeCheckAnnotations(buckets, seenMap, prNumber,
         ...buckets.filtered,
         ...buckets.ignored,
     ].filter(shouldFetchCheckAnnotations);
-    const annotated = await attachUnseenCheckAnnotations(candidates, seenMap, prNumber, cacheOpts);
+    const expectedCounts = new Map(candidates.flatMap((c) => c.id != null && c.annotationCount ? [[c.id, c.annotationCount]] : []));
+    const annotated = await attachUnseenCheckAnnotations(candidates, seenMap, prNumber, cacheOpts && { ...cacheOpts, expectedCounts });
     const byId = new Map(annotated.flatMap((c) => (c.id != null ? [[c.id, c]] : [])));
     const apply = (list) => list.map((c) => {
         const next = (c.id == null ? undefined : byId.get(c.id)) ?? c;

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

@@ -23,7 +23,7 @@ export interface ReviewOutputBuckets {
     editedComments: EditedComment[];
 }
 /**
- * Applies `iterate.reviewOutputMaxChars` to one tick's review buckets. Priority: changes-requested
+ * Applies `iterate.review-output-max-chars` 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

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

@@ -10,7 +10,7 @@ const threadItem = (thread) => ({
     cost: threadTranscriptBody(thread).length,
 });
 /**
- * Applies `iterate.reviewOutputMaxChars` to one tick's review buckets. Priority: changes-requested
+ * Applies `iterate.review-output-max-chars` 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

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

@@ -14,7 +14,7 @@ type StateKey = {
  * 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.
+ * `poll.reconcile-seconds` leaves `changed` unset.
  */
 export type WaitDetectorResult = {
     reused: ShepherdReport;

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

@@ -30,6 +30,17 @@ function detectorsCover(stored) {
  * Read the PR's REST change detectors: the pull, the head's check runs, check suites and
  * statuses, the three feedback lists, and the base branch. Every read is conditional, so an
  * unchanged resource answers a free 304.
+ *
+ * The feedback lists are deliberately not rule-aware (#635 gap 7). An edited bot comment, even
+ * a rule-suppressed or minimized one, answers 200 and wakes the tick. The wake costs one
+ * charged list read plus one `BatchPr` first page (a complete fingerprint needs no more),
+ * the same point a fingerprint hit spends. Once the digest is re-recorded, a later eligible
+ * tick can replay for free again, but only if every detector answers 304 with that digest and
+ * the stored snapshot is within `poll.reconcile-seconds`; otherwise it goes to `BatchPr`. Being
+ * rule-aware would need the loaded rules, a persisted set of hidden comment ids (REST has no
+ * `isMinimized`), and a content digest in place of the ETag. That is more code, and more risk
+ * of sleeping through a real change (a rule-suppressed comment edited so it no longer matches,
+ * an edited minimized human comment, which `check` surfaces), than the one point it saves.
  */
 async function readDetectors(prNumber, repo, report) {
     const prefix = restRepoPath(repo);
@@ -51,7 +62,7 @@ async function readDetectors(prNumber, repo, report) {
  * is rethrown so the tick aborts and polling backs off.
  */
 export async function readWaitDetectors(prNumber, repo, stateKey, config, now = Date.now()) {
-    const reconcileMs = config.poll.reconcileSeconds * 1000;
+    const reconcileMs = config.poll["reconcile-seconds"] * 1000;
     if (reconcileMs === 0 || getGithubTransport() === "rest")
         return undefined;
     const stored = await loadPrFingerprint(stateKey);

package/bin/commands/check.d.mts

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

package/bin/commands/check.mjs

@@ -33,6 +33,7 @@ import { markReviewInlineThreadMarkers } from "../comments/review-thread-markers
 import { isConfiguredBotAuthor, isHumanAuthor, normalizeBotUsernames, } from "../comments/authors.mjs";
 import { buildThreadMutationRouting, threadHasAuthorizedMutation, } from "./iterate/thread-mutation-routing.mjs";
 import { loadClassifyRules } from "../classify/loader.mjs";
+import { filterSuppressedActivity } from "./check-activity.mjs";
 import { buildClassifyIndex, partitionBatch } from "../classify/apply.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { getEffectiveCwd } from "../execution-context.mjs";
@@ -60,7 +61,7 @@ export async function runCheck(opts, context) {
 async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
     const config = loadConfig();
     const reuseFingerprint = opts.fingerprintCache === true;
-    const paginateApprovedReviews = config.iterate.minimizeApprovals;
+    const paginateApprovedReviews = config.iterate["minimize-approvals"];
     const includeReceiptSummary = (await context?.wantsReceiptSummary(prNumber, repo)) ?? false;
     // GraphQL transport: conditional REST change detectors can replay an idle report for free.
     // Changed trunk rules invalidate a cached report; check again without reuse.
@@ -125,7 +126,7 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
         owner: repo.owner,
         name: repo.name,
         pr: prNumber,
-        relevantEvents: config.checks.ciTriggerEvents,
+        relevantEvents: config.checks["ci-trigger-events"],
     }, context);
     const classifiedPrChecks = classifyChecks(allChecks, {
         requiredContexts: unreported.requiredContexts,
@@ -194,7 +195,7 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
     const seenMap = await loadSeenMap(stateKey);
     await aliasThreadSeenMarkers(repo, prNumber, batchData.reviewThreads.map((thread) => thread.id), seenMap);
     const canGenerateItemMutation = (id, body, capability, operation) => !mutationWasDenied(id, body, seenMap) && canGenerateGithubMutation(capability, operation);
-    const botUsernames = normalizeBotUsernames(config.botUsernames);
+    const botUsernames = normalizeBotUsernames(config["bot-usernames"]);
     const ruleSet = await loadClassifyRules(getEffectiveCwd(), config.standardRules);
     const classifyIndex = buildClassifyIndex(ruleSet, batchData);
     const partition = partitionBatch(classifyIndex, batchData);
@@ -202,7 +203,7 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
     const ignoredAnnotated = merged.ignored.filter((c) => (c.annotations?.length ?? 0) > 0);
     const minimizedCommentCandidates = batchData.comments.filter((c) => c.isMinimized && !partition.suppressedCommentIds.has(c.id));
     const deniedRuleAutoResolveCommentIds = new Set(partition.ruleAutoResolveCommentIds.filter((id) => !canGenerateItemMutation(id, batchData.comments.find((comment) => comment.id === id)?.body ?? "", batchData.comments.find((comment) => comment.id === id)?.viewerCanMinimize, "minimize")));
-    const visibleCommentClassification = classifyVisibleComments(batchData.comments.filter((c) => !partition.suppressedCommentIds.has(c.id) || deniedRuleAutoResolveCommentIds.has(c.id)), seenMap, config.iterate.minimizeComments, botUsernames, new Set(batchData.comments
+    const visibleCommentClassification = classifyVisibleComments(batchData.comments.filter((c) => !partition.suppressedCommentIds.has(c.id) || deniedRuleAutoResolveCommentIds.has(c.id)), seenMap, config.iterate["minimize-comments"], botUsernames, new Set(batchData.comments
         .filter((comment) => mutationWasDenied(comment.id, comment.body, seenMap))
         .map((comment) => comment.id)));
     const deniedRuleAutoResolveThreadIds = new Set(partition.ruleAutoResolveThreadIds.filter((id) => {
@@ -211,7 +212,7 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
             !canGenerateItemMutation(thread.id, threadTranscriptBody(thread), thread.viewerCanResolve, "resolve"));
     }));
     const visibleThreadCandidates = batchData.reviewThreads.filter((t) => !partition.suppressedThreadIds.has(t.id) || deniedRuleAutoResolveThreadIds.has(t.id));
-    const resolveOtherHumanThreads = config.iterate.resolveOtherHumanThreads ?? "none";
+    const resolveOtherHumanThreads = config.iterate["resolve-other-human-threads"] ?? "none";
     const threadMutationRouting = buildThreadMutationRouting(visibleThreadCandidates, botUsernames, partition.ruleAutoResolveThreadIds, resolveOtherHumanThreads);
     const replyThreadIds = new Set(threadMutationRouting.replyThreadIds);
     const resolveThreadIds = new Set(threadMutationRouting.resolveThreadIds);
@@ -288,11 +289,11 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
     // persisting seen markers for it now would make it silently vanish from every later tick
     // once it's no longer "new" or "edited", even after the PR leaves the queue. A queued PR
     // that also has check-driven work (failing checks, actionable annotations, conflicts) is
-    // NOT deferred — index.mts still renders these items via fix_code — so this must stay false
+    // NOT deferred — index.mts still renders these items via triage — so this must stay false
     // in that case too, or their seen markers would be suppressed while actually being shown.
     const deferWhileQueued = opts.merge === true &&
         batchData.isInMergeQueue === true &&
-        config.actions.workWhileQueued !== true &&
+        config.actions["work-while-queued"] !== true &&
         !hasCheckDrivenActionableWork({
             failing: merged.failing,
             passing: merged.passing,
@@ -449,7 +450,11 @@ async function runScopedCheck(opts, context, repo, prNumber, stateKey) {
         ...(batchData.allowedMergeMethods && {
             allowedMergeMethods: batchData.allowedMergeMethods,
         }),
-        activity: batchData.activity,
+        activity: filterSuppressedActivity(batchData.activity, partition, [
+            ...deniedRuleAutoResolveCommentIds,
+            ...deniedRuleAutoResolveThreadIds,
+            ...deniedRuleAutoResolveReviewSummaryIds,
+        ]),
         ...(hasQueueState && {
             mergeQueue: {
                 enabled: Boolean(batchData.isMergeQueueEnabled),

package/bin/commands/commit-suggestion-instruction.d.mts

@@ -1,6 +1,6 @@
 /**
- * Build the `build-suggestion-patches` instruction step for agent consumers.
- * Currently emitted by iterate `fix_code` for suggestion review threads. The CLI keeps
+ * Build the `suggest` instruction step for agent consumers.
+ * Currently emitted by iterate `triage` for suggestion review threads. The CLI keeps
  * only the trigger and the concrete command; refusal/drift handling is invariant across
  * every invocation, so it lives in the pr-shepherd skill's "Suggestion patches" playbook
  * instead of being re-emitted every tick (see AGENTS.md "Keep skills and loop prompts

package/bin/commands/commit-suggestion-instruction.mjs

@@ -1,8 +1,8 @@
 import { buildPrShepherdCommand } from "../cli/runner.mjs";
 import { playbookPointer } from "./playbook-pointer.mjs";
 /**
- * Build the `build-suggestion-patches` instruction step for agent consumers.
- * Currently emitted by iterate `fix_code` for suggestion review threads. The CLI keeps
+ * Build the `suggest` instruction step for agent consumers.
+ * Currently emitted by iterate `triage` for suggestion review threads. The CLI keeps
  * only the trigger and the concrete command; refusal/drift handling is invariant across
  * every invocation, so it lives in the pr-shepherd skill's "Suggestion patches" playbook
  * instead of being re-emitted every tick (see AGENTS.md "Keep skills and loop prompts
@@ -12,7 +12,7 @@ import { playbookPointer } from "./playbook-pointer.mjs";
  */
 export function buildCommitSuggestionInstruction(prReference, sectionName) {
     const command = buildPrShepherdCommand([
-        "build-suggestion-patches",
+        "suggest",
         String(prReference),
         "--thread-id",
         "<id>",

package/bin/commands/iterate/api-usage.mjs

@@ -3,9 +3,9 @@ import { summarizeApiTelemetry } from "../../github/api-telemetry.mjs";
 import { selectQuotaWarning } from "../quota-selection.mjs";
 import { buildQuotaAwareContinuation } from "../../quota-warning.mjs";
 import { getGithubTransport } from "../../github/transport.mjs";
-import { isFixCodeContinuation } from "./check-instructions.mjs";
+import { isTriageContinuation } from "./check-instructions.mjs";
 function shouldWarn(result) {
-    return ["wait", "mark_ready", "merge", "fix_code"].includes(result.action);
+    return ["wait", "mark_ready", "merge", "triage"].includes(result.action);
 }
 export async function attachApiUsage(result, persistWarning, preservePersistedWarning = false, minimumPollIntervalMinutes = 0) {
     const apiUsage = summarizeApiTelemetry();
@@ -16,7 +16,7 @@ export async function attachApiUsage(result, persistWarning, preservePersistedWa
     if (quotaWarning === undefined && shouldWarn(result) && (apiUsage.graphql || core)) {
         const [owner, repo] = result.repo.split("/");
         if (owner && repo) {
-            const bands = loadConfig().watch.graphqlQuotaWarnings.map((band) => ({
+            const bands = loadConfig().quotaWarningBands.map((band) => ({
                 ...band,
                 pollIntervalMinutes: Math.max(band.pollIntervalMinutes, minimumPollIntervalMinutes),
             }));
@@ -29,14 +29,14 @@ export async function attachApiUsage(result, persistWarning, preservePersistedWa
         apiUsage,
         ...(quotaWarning !== undefined && { quotaWarning }),
     };
-    if (quotaWarning === undefined || withWarning.action !== "fix_code")
+    if (quotaWarning === undefined || withWarning.action !== "triage")
         return withWarning;
-    const instructions = [...withWarning.fix.instructions];
+    const instructions = [...withWarning.triage.instructions];
     const completion = instructions.at(-1);
     if (completion !== undefined) {
-        if (isFixCodeContinuation(completion)) {
-            instructions[instructions.length - 1] = buildQuotaAwareContinuation(quotaWarning, "`[FIX_CODE]` is non-terminal. After completing these steps,");
+        if (isTriageContinuation(completion)) {
+            instructions[instructions.length - 1] = buildQuotaAwareContinuation(quotaWarning, "`[TRIAGE]` is non-terminal. After completing these steps,");
         }
     }
-    return { ...withWarning, fix: { ...withWarning.fix, instructions } };
+    return { ...withWarning, triage: { ...withWarning.triage, instructions } };
 }

package/bin/commands/iterate/check-instructions.d.mts

@@ -1,11 +1,11 @@
 import type { AgentCheck, ResolveCommand, Review } from "../../types.mts";
-/** The `[FIX_CODE]` recurrence step, whether plain or rewritten by the quota warning. */
-export declare function isFixCodeContinuation(step: string): boolean;
+/** The `[TRIAGE]` recurrence step, whether plain or rewritten by the quota warning. */
+export declare function isTriageContinuation(step: string): boolean;
 /** Build the stale-CR step for `## Changes-requested reviews`. Empty when no human CR is stale. */
 export declare function buildCrStaleClause(reviews: Review[]): string;
 /**
  * Build the optional branch-update hint. Empty unless the branch is behind or conflicts with its
- * base and the user configured a non-blank `iterate.behindBaseHint` — the CLI never prescribes
+ * base and the user configured a non-blank `iterate.behind-base-hint` — the CLI never prescribes
  * rebase/merge mechanics itself (see "Keep skills and loop prompts minimal" in AGENTS.md); this
  * only echoes back the caller's own configured pointer. `hint` is trimmed and type-checked at the
  * point of use (rather than at config load) so a malformed rc file value (non-string, or
@@ -37,7 +37,7 @@ export declare function buildResolveCommandInstruction(resolveCommand: ResolveCo
 export declare function buildFailingCheckInstructions(checks: AgentCheck[]): string[];
 /** Update the PR branch after an external blocker merges or closes. Never rerun that job. */
 export declare function buildReleasedBlockerInstruction(prNumber: number): string;
-/** `iterate.reviewOutputMaxChars` held review items back; the rerun step that follows shows them. */
+/** `iterate.review-output-max-chars` held review items back; the rerun step that follows shows them. */
 export declare function buildReviewSubsetInstruction(reviewItems: {
     shown: number;
     total: number;

package/bin/commands/iterate/check-instructions.mjs

@@ -1,9 +1,9 @@
 import { playbookPointer } from "../playbook-pointer.mjs";
-// The `[FIX_CODE]` heading and the skill already say the action is non-terminal.
-const FIX_CODE_CONTINUATION = "Rerun Shepherd now.";
-/** The `[FIX_CODE]` recurrence step, whether plain or rewritten by the quota warning. */
-export function isFixCodeContinuation(step) {
-    return step === FIX_CODE_CONTINUATION || /\[FIX_CODE\].*non-terminal/i.test(step);
+// The `[TRIAGE]` heading and the skill already say the action is non-terminal.
+const TRIAGE_CONTINUATION = "Rerun Shepherd now.";
+/** The `[TRIAGE]` recurrence step, whether plain or rewritten by the quota warning. */
+export function isTriageContinuation(step) {
+    return step === TRIAGE_CONTINUATION || /\[TRIAGE\].*non-terminal/i.test(step);
 }
 /** Build the stale-CR step for `## Changes-requested reviews`. Empty when no human CR is stale. */
 export function buildCrStaleClause(reviews) {
@@ -13,7 +13,7 @@ export function buildCrStaleClause(reviews) {
 }
 /**
  * Build the optional branch-update hint. Empty unless the branch is behind or conflicts with its
- * base and the user configured a non-blank `iterate.behindBaseHint` — the CLI never prescribes
+ * base and the user configured a non-blank `iterate.behind-base-hint` — the CLI never prescribes
  * rebase/merge mechanics itself (see "Keep skills and loop prompts minimal" in AGENTS.md); this
  * only echoes back the caller's own configured pointer. `hint` is trimmed and type-checked at the
  * point of use (rather than at config load) so a malformed rc file value (non-string, or
@@ -74,12 +74,12 @@ export function buildReleasedBlockerInstruction(prNumber) {
         ? "Update this PR branch from its base using the repository's branch-update procedure. Do not rerun the job; a rerun retests the old merge ref."
         : `Update this PR branch from its base with \`gh pr update-branch ${prNumber} --rebase\`. Do not rerun the job; a rerun retests the old merge ref.`;
 }
-/** `iterate.reviewOutputMaxChars` held review items back; the rerun step that follows shows them. */
+/** `iterate.review-output-max-chars` held review items back; the rerun step that follows shows them. */
 export function buildReviewSubsetInstruction(reviewItems) {
     return `This is a subset: ${reviewItems.shown} of ${reviewItems.total} review items are shown, and only their IDs are in the commands above. After handling these items, rerun Shepherd for the next batch; do not fetch the held items yourself.`;
 }
 /** Recurrence only. Commit, push, rerun, and SHA steps are earlier instructions. */
 export function buildFixCompletionInstruction() {
-    return FIX_CODE_CONTINUATION;
+    return TRIAGE_CONTINUATION;
 }
 import { getGithubTransport } from "../../github/transport.mjs";

package/bin/commands/iterate/classify.mjs

@@ -24,7 +24,7 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals,
     // so their minimize IDs ride in the agent-facing apply command. Seen summaries
     // (already surfaced in a prior tick) have no new content to show — the CLI
     // self-minimizes them in-process (selfMinimizeIds) instead of routing a
-    // cosmetic-only mutation through fix_code (issue #313). Edited summaries are
+    // cosmetic-only mutation through triage (issue #313). Edited summaries are
     // excluded entirely: they are already minimized server-side (body changed after
     // minimize was applied).
     const minimizeIds = summaries.firstLook.filter(eligible).map((r) => r.id);
@@ -61,7 +61,7 @@ export function classifyReviewSummaries(summaries, approvals, minimizeApprovals,
     };
 }
 /**
- * A durable-state session (event mode or a cloud session) can lose its uncertain-reply records
+ * A durable-state (cloud) session can lose its uncertain-reply records
  * between ticks. Its generated reply command opts in to adopting a reply GitHub already shows,
  * so rerunning the same printed command cannot double-post. Direct apply requests never do.
  */

package/bin/commands/iterate/escalate.mjs

@@ -64,11 +64,11 @@ function renderEscalateCheck(check) {
 }
 export function checkEscalateTriggers(actionableThreads, threadAttempts) {
     const triggers = [];
-    const maxAttempts = loadConfig().iterate.fixAttemptsPerThread;
-    // Trigger 1: fix thrash — same thread dispatched too many times without resolving.
+    const maxAttempts = loadConfig().iterate["triage-attempts-per-thread"];
+    // Trigger 1: triage thrash — same thread dispatched too many times without resolving.
     const thrashThreads = actionableThreads.filter((t) => (threadAttempts[t.id] ?? 0) >= maxAttempts);
     if (thrashThreads.length > 0) {
-        triggers.push("fix-thrash");
+        triggers.push("triage-thrash");
     }
     return {
         triggers,
@@ -265,9 +265,9 @@ export function buildEscalateSuggestion(triggers, detail) {
         const reason = detail ? ` (${detail})` : "";
         return `Could not determine the PR's base branch${reason} — automated rebases are paused because branch safety is unclear. Run the rebase manually against the PR's real target branch.`;
     }
-    if (triggers.includes("fix-thrash")) {
-        const attempts = loadConfig().iterate.fixAttemptsPerThread;
-        return `The same thread(s) remain unresolved after their pending review commands were returned for ${attempts} FIX_CODE ticks. Automated iteration is paused for a manual decision.`;
+    if (triggers.includes("triage-thrash")) {
+        const attempts = loadConfig().iterate["triage-attempts-per-thread"];
+        return `The same thread(s) remain unresolved after their pending review commands were returned for ${attempts} TRIAGE ticks. Automated iteration is paused for a manual decision.`;
     }
     return "Ambiguous state — automated handling cannot proceed safely. Inspect the PR and act manually.";
 }