pr-shepherd 0.60.1 → 1.0.0

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

@@ -51,7 +51,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

@@ -60,7 +60,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 +125,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 +194,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 +202,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 +211,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 +288,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,

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.";
 }

package/bin/commands/iterate/index.mjs

@@ -8,7 +8,7 @@ import { buildWaitLog, buildTerminalCancelResult, blockedCancelNote } from "./he
 import { classifyReviewSummaries } from "./classify.mjs";
 import { applyStallGuard } from "./stall.mjs";
 import { clearStallState } from "../../state/iterate-stall.mjs";
-import { handleFixCode } from "./fix-code.mjs";
+import { handleTriage } from "./triage.mjs";
 import { normalizeBotUsernames } from "../../comments/authors.mjs";
 import { autoMinimizeComments } from "../../comments/resolve.mjs";
 import { hasCheckDrivenActionableWork } from "../check-annotations.mjs";
@@ -60,24 +60,21 @@ async function attachEditedComments(result, tick, opts) {
 }
 async function runIterateCore(opts, tick) {
     const config = loadConfig();
-    const botUsernames = normalizeBotUsernames(config.botUsernames);
-    const readyDelaySeconds = opts.readyDelaySeconds ?? config.watch.readyDelayMinutes * 60;
-    const stallTimeoutSeconds = opts.stallTimeoutSeconds ?? config.iterate.stallTimeoutMinutes * 60;
+    const botUsernames = normalizeBotUsernames(config["bot-usernames"]);
+    const readyDelaySeconds = opts.readyDelaySeconds ?? config.iterate["ready-delay-minutes"] * 60;
+    const stallTimeoutSeconds = opts.stallTimeoutSeconds ?? config.iterate["stall-timeout-minutes"] * 60;
     const prNumber = opts.prNumber ?? (await getCurrentPrNumber());
     if (prNumber === null) {
         throw new ShepherdError("No open PR found for current branch. Pass a PR number explicitly.", EXIT.UNAVAILABLE);
     }
-    const neverCancelRuns = opts.neverCancelRuns ?? config.actions.neverCancelRuns;
     const checkContext = createCheckExecutionContext(readyDelaySeconds);
     const report = await runCheck({
         ...opts,
         prNumber,
-        // Outdated Shepherd-visible threads are always resolved by iterate. The
-        // old actions.autoResolveOutdated switch is retained only as an ignored
-        // compatibility key in the config loader.
+        // Outdated Shepherd-visible threads are always resolved by iterate.
         autoResolve: true,
-        autoMinimizeSuppressed: config.actions.autoMinimizeSuppressed,
-        reviewOutputMaxChars: config.iterate.reviewOutputMaxChars,
+        autoMinimizeSuppressed: config.actions["auto-minimize-suppressed"],
+        reviewOutputMaxChars: config.iterate["review-output-max-chars"],
     }, checkContext);
     tick.report = report;
     const [repoOwner, repoName] = report.repo.split("/");
@@ -107,7 +104,7 @@ async function runIterateCore(opts, tick) {
         firstLook: report.firstLookSummaries,
         seen: report.reviewSummaries,
         edited: report.editedSummaries,
-    }, report.approvedReviews, config.iterate.minimizeApprovals, config.iterate.minimizeComments, botUsernames, [
+    }, report.approvedReviews, config.iterate["minimize-approvals"], config.iterate["minimize-comments"], botUsernames, [
         ...report.threads.actionable,
         ...report.threads.resolutionOnly,
         ...(report.heldThreadReviewIds ?? []).map((reviewId) => ({ reviewId })),
@@ -128,7 +125,7 @@ async function runIterateCore(opts, tick) {
     }
     // A first look at an already-minimized comment is only an acknowledgment. Edited PR comments
     // (report.comments.edited) are neither: they never block readiness or restart the ready delay.
-    // Review items held back by iterate.reviewOutputMaxChars keep the PR out of ready/merge: a
+    // Review items held back by iterate.review-output-max-chars keep the PR out of ready/merge: a
     // capped tick that shows only first-look comments still counts, since held work follows.
     const hasReadinessWork = (report.reviewItems !== undefined && report.comments.firstLook.length > 0) ||
         report.threads.actionable.length > 0 ||
@@ -142,7 +139,7 @@ async function runIterateCore(opts, tick) {
         reviewSummaryIds.length > 0 ||
         firstLookSummaries.length > 0 ||
         editedSummaries.length > 0 ||
-        (config.iterate.minimizeApprovals && surfacedApprovals.length > 0);
+        (config.iterate["minimize-approvals"] && surfacedApprovals.length > 0);
     const hasActionableWork = hasReadinessWork || report.comments.firstLook.length > 0;
     const activeMerge = Boolean(opts.merge &&
         (report.mergeQueue?.inQueue ||
@@ -183,12 +180,12 @@ async function runIterateCore(opts, tick) {
     const checkDrivenActionableWork = hasCheckDrivenActionableWork(reportForWork.checks, report.mergeStatus.status);
     const deferWhileQueued = opts.merge === true &&
         report.mergeQueue?.inQueue === true &&
-        config.actions.workWhileQueued !== true;
+        config.actions["work-while-queued"] !== true;
     if (hasActionableWork && !(deferWhileQueued && !checkDrivenActionableWork)) {
-        return handleFixCode({
+        return handleTriage({
             base,
             report: reportForWork,
-            opts: { ...opts, prNumber, neverCancelRuns },
+            opts: { ...opts, prNumber },
             headSha,
             stallKey,
             prNumber,
@@ -208,10 +205,10 @@ async function runIterateCore(opts, tick) {
         });
     }
     if (unreportedRepair.length > 0 && staleAncestry) {
-        return handleFixCode({
+        return handleTriage({
             base,
             report: reportForWork,
-            opts: { ...opts, prNumber, neverCancelRuns },
+            opts: { ...opts, prNumber },
             headSha,
             stallKey,
             prNumber,
@@ -241,15 +238,15 @@ async function runIterateCore(opts, tick) {
         firstLookSummaries,
         editedSummaries,
         surfacedApprovals,
-        minimizeApprovals: config.iterate.minimizeApprovals,
+        minimizeApprovals: config.iterate["minimize-approvals"],
     });
     if (mergeStateResult)
         return annotateBlockedWait(mergeStateResult, blockerGate);
     if (staleAncestry) {
-        return handleFixCode({
+        return handleTriage({
             base,
             report: reportForWork,
-            opts: { ...opts, prNumber, neverCancelRuns },
+            opts: { ...opts, prNumber },
             headSha,
             stallKey,
             prNumber,
@@ -287,7 +284,7 @@ async function runIterateCore(opts, tick) {
             escalate: { ...escalation, humanMessage: buildEscalateHumanMessage(escalation, report.pr) },
         };
     }
-    const autoMarkReady = !opts.noAutoMarkReady && config.actions.autoMarkReady;
+    const autoMarkReady = !opts.noAutoMarkReady && config["mark-ready"].auto;
     if (canMarkReady && !autoMarkReady) {
         await clearReadyDelay(report.pr, repoOwner, repoName);
         await clearStallState(stallKey);
@@ -307,7 +304,7 @@ async function runIterateCore(opts, tick) {
         const receipt = receiptCurrent
             ? "written"
             : await recordReadyReceipt(receiptKey, report, checkContext);
-        // Aggregate --stack routing trusts only a layer's receipt, so an unwritten
+        // Aggregate `stack` routing trusts only a layer's receipt, so an unwritten
         // one keeps the elapsed marker and retries next tick. A one-PR receipt
         // only lets a rerun skip the wait, so its failure never changes the action.
         // A layer GitHub reports BLOCKED gets no receipt, so aggregate routing

package/bin/commands/iterate/merge-plan.mjs

@@ -7,7 +7,7 @@ import { getGithubTransport } from "../../github/transport.mjs";
 const ENQUEUE_MUTATION = "mutation EnqueuePullRequest($pullRequestId: ID!, $expectedHeadOid: GitObjectID!) { enqueuePullRequest(input: { pullRequestId: $pullRequestId, expectedHeadOid: $expectedHeadOid }) { mergeQueueEntry { id } } }";
 export function buildMergeCommandPlan(input) {
     if (input.transport === "rest" || getGithubTransport() === "rest") {
-        const configured = configuredMergeMethod(loadConfig().merge ?? {});
+        const configured = configuredMergeMethod(loadConfig().merge);
         if (!input.queue && input.queueKnown !== true && configured)
             return {
                 unavailable: "REST cannot verify merge-queue policy and cannot apply a configured direct merge method to an automatic merge request. Refresh branch policy before merging.",
@@ -70,10 +70,10 @@ export function buildMergeCommandPlan(input) {
         };
     }
     const mergeConfig = loadConfig().merge;
-    const configuredArgs = mergeConfig?.commandArgs ?? [];
+    const configuredArgs = mergeConfig["command-args"];
     const decision = chooseMergeMethod({
         allowed: input.allowedMergeMethods,
-        configured: configuredMergeMethod(mergeConfig ?? {}),
+        configured: configuredMergeMethod(mergeConfig),
         fallback: "merge",
     });
     if ("unavailable" in decision)

package/bin/commands/iterate/merge-state.mjs

@@ -6,14 +6,14 @@ import { buildPrShepherdCommand } from "../../cli/runner.mjs";
 import { inlineCode } from "../../util/markdown.mjs";
 /**
  * A one-PR poll cannot prove the layers below it merged or that its PR number is a safe merge
- * selector. Route it through the aggregate stack selector, which merges one bottom layer at a time.
+ * selector. Route it through the aggregate stack command, which merges one bottom layer at a time.
  */
 function buildStackedRouteResult(base, report, stack) {
     const prUrl = formatPrUrl(report.repo, report.pr);
     return {
         ...base,
-        action: "fix_code",
-        fix: {
+        action: "triage",
+        triage: {
             threads: [],
             resolutionOnlyThreads: [],
             actionableComments: [],
@@ -31,14 +31,11 @@ function buildStackedRouteResult(base, report, stack) {
             },
             instructions: [
                 `PR #${report.pr} is layer ${stack.position} of ${stack.size} in native stack #${stack.number}; do not run \`gh pr merge\` for this layer.`,
-                `Run ${inlineCode(buildPrShepherdCommand(["--stack", prUrl, "--until-terminal", "--merge"]).text)} to reconcile the stack and run each bottom-layer merge command it emits.`,
+                `Run ${inlineCode(buildPrShepherdCommand(["stack", prUrl, "--until-terminal", "--merge"]).text)} to reconcile the stack and run each bottom-layer merge command it emits.`,
             ],
-            inProgressRunIds: [],
-            protectedRuns: [],
             firstLookThreads: [],
             firstLookComments: [],
         },
-        cancelled: [],
     };
 }
 export function buildReadyMergeOutcome(enabled, readyElapsed, base, report) {

package/bin/commands/iterate/native-stack-rebase.mjs

@@ -15,7 +15,7 @@ export function buildNativeStackRebaseInstruction(repo, stackNumber, start) {
             : "trunk" in start
                 ? `trunk \`${start.trunk}\``
                 : `bottom open layer PR #${start.bottomPr}`;
-        return `Use the repository's stack-update procedure for native stack #${stackNumber} in \`${repo}\`, starting at ${boundary} and preserving the ordered parent boundaries of every affected upper layer. Read membership with REST-backed Shepherd \`--stack\` output and update and push affected branches using the caller's git workflow. ${playbookPointer("Branch update")}`;
+        return `Use the repository's stack-update procedure for native stack #${stackNumber} in \`${repo}\`, starting at ${boundary} and preserving the ordered parent boundaries of every affected upper layer. Read membership with REST-backed Shepherd \`stack\` output and update and push affected branches using the caller's git workflow. ${playbookPointer("Branch update")}`;
     }
     const [checkout, command] = "parentBranch" in start
         ? [

package/bin/commands/iterate/render.d.mts

@@ -7,7 +7,7 @@ import type { InstructionStyle } from "../../config/load.mts";
  * if it is not. `apply review` reads that HEAD itself with a read-only `git rev-parse HEAD`.
  */
 export declare function renderResolveCommand(rc: ResolveCommand): string;
-export declare function buildFixInstructions(threads: AgentThread[], actionableComments: AgentComment[], checks: AgentCheck[], changesRequestedReviews: Review[], baseBranch: string, resolveCommand: ResolveCommand, hasConflicts: boolean, prReference: string | number, _cancelledCount: number, firstLookThreads?: FirstLookThread[], firstLookComments?: FirstLookComment[], firstLookSummaries?: Review[], editedSummaries?: Review[], _inProgressRunIds?: string[], resolutionOnlyThreads?: ReviewThread[], resolveOnlyCommand?: ResolveCommand, behindBaseHint?: string, // iterate.behindBaseHint — see buildBehindBaseHintInstruction
+export declare function buildFixInstructions(threads: AgentThread[], actionableComments: AgentComment[], checks: AgentCheck[], changesRequestedReviews: Review[], baseBranch: string, resolveCommand: ResolveCommand, hasConflicts: boolean, prReference: string | number, firstLookThreads?: FirstLookThread[], firstLookComments?: FirstLookComment[], firstLookSummaries?: Review[], editedSummaries?: Review[], resolutionOnlyThreads?: ReviewThread[], resolveOnlyCommand?: ResolveCommand, behindBaseHint?: string, // iterate.behind-base-hint — see buildBehindBaseHintInstruction
 isBehind?: boolean, _viewerCanUpdate?: boolean, hasExhaustedWorkflowRerun?: boolean, stackRebase?: string, // native stack layers rebase with gh-stack, not branch by branch
 queueEjection?: QueueEjectionRecovery, // current merge-queue removal with failing queue checks
 instructionStyle?: InstructionStyle): string[];

package/bin/commands/iterate/render.mjs

@@ -5,7 +5,7 @@ import { buildCommitSuggestionInstruction } from "../commit-suggestion-instructi
 import { partitionFixThreads } from "./fix-instruction-threads.mjs";
 import { buildBranchPushInstruction, buildConflictInstruction } from "./native-stack-rebase.mjs";
 import { queueEjectionSteps } from "./queue-recovery-instructions.mjs";
-import { buildPushSteps } from "./fix-loop-instruction.mjs";
+import { buildPushSteps } from "./triage-loop-instruction.mjs";
 /**
  * Render a resolve command as a shell snippet. Appends `--require-sha HEAD` when set: run after
  * the push step, the local HEAD is the pushed PR head, and `apply review` rejects the mutations
@@ -16,7 +16,7 @@ export function renderResolveCommand(rc) {
     return rc.requiresHeadSha ? `${command} ${REQUIRE_HEAD_SHA}` : command;
 }
 const REQUIRE_HEAD_SHA = "--require-sha HEAD";
-export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prReference, _cancelledCount, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], _inProgressRunIds = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behindBaseHint — see buildBehindBaseHintInstruction
+export function buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseBranch, resolveCommand, hasConflicts, prReference, firstLookThreads = [], firstLookComments = [], firstLookSummaries = [], editedSummaries = [], resolutionOnlyThreads = [], resolveOnlyCommand, behindBaseHint = "", // iterate.behind-base-hint — see buildBehindBaseHintInstruction
 isBehind = false, _viewerCanUpdate = false, hasExhaustedWorkflowRerun = false, stackRebase, // native stack layers rebase with gh-stack, not branch by branch
 queueEjection, // current merge-queue removal with failing queue checks
 instructionStyle = "inline") {

package/bin/commands/iterate/stall.mjs

@@ -5,25 +5,27 @@ import { buildEscalateSuggestion, buildEscalateHumanMessage, formatDurationAppro
 import { checksWithActionableAnnotations } from "../check-annotations.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
 function pendingReviewCommandsFromResult(result) {
-    if (result.action !== "fix_code")
+    if (result.action !== "triage")
         return undefined;
     const pending = {
-        ...(result.fix.resolveOnlyCommand?.hasMutations && {
-            resolveOnlyCommand: result.fix.resolveOnlyCommand,
+        ...(result.triage.resolveOnlyCommand?.hasMutations && {
+            resolveOnlyCommand: result.triage.resolveOnlyCommand,
+        }),
+        ...(result.triage.resolveCommand.hasMutations && {
+            resolveCommand: result.triage.resolveCommand,
         }),
-        ...(result.fix.resolveCommand.hasMutations && { resolveCommand: result.fix.resolveCommand }),
     };
     return Object.keys(pending).length > 0 ? pending : undefined;
 }
 function surfacedSummariesFromResult(result) {
-    if (result.action !== "fix_code")
+    if (result.action !== "triage")
         return {};
     return {
-        ...(result.fix.firstLookSummaries.length > 0 && {
-            firstLookSummaries: result.fix.firstLookSummaries,
+        ...(result.triage.firstLookSummaries.length > 0 && {
+            firstLookSummaries: result.triage.firstLookSummaries,
         }),
-        ...(result.fix.editedSummaries.length > 0 && {
-            editedSummaries: result.fix.editedSummaries,
+        ...(result.triage.editedSummaries.length > 0 && {
+            editedSummaries: result.triage.editedSummaries,
         }),
     };
 }

package/bin/commands/iterate/{fix-loop-instruction.mjs → triage-loop-instruction.mjs}

@@ -1,7 +1,7 @@
 import { renderShellCommand } from "../../cli/runner.mjs";
 import { loadConfig } from "../../config/load.mjs";
 import { playbookPointer } from "../playbook-pointer.mjs";
-const FIX_CODE_LOOP_PLAYBOOK = "Fix-code loop";
+const TRIAGE_LOOP_PLAYBOOK = "Triage loop";
 /** The generic push stays separate from conflict and queue-recovery push instructions. */
 export function buildPushSteps(style, genericPush) {
     if (!genericPush)
@@ -9,6 +9,10 @@ export function buildPushSteps(style, genericPush) {
     const push = "Commit and push any changes.";
     if (style === "inline")
         return [push];
-    const cli = renderShellCommand([...loadConfig().cliCommand, "playbook", FIX_CODE_LOOP_PLAYBOOK]);
-    return [`${push} ${playbookPointer(FIX_CODE_LOOP_PLAYBOOK)} CLI: \`${cli}\`.`];
+    const cli = renderShellCommand([
+        ...loadConfig()["cli-command"],
+        "playbook",
+        TRIAGE_LOOP_PLAYBOOK,
+    ]);
+    return [`${push} ${playbookPointer(TRIAGE_LOOP_PLAYBOOK)} CLI: \`${cli}\`.`];
 }

package/bin/commands/iterate/{fix-code.d.mts → triage.d.mts}

@@ -1,6 +1,6 @@
 import type { IterateCommandOptions, IterateResult, IterateResultBase, Review, ShepherdReport } from "../../types.mts";
 import type { NormalizedBotUsernames } from "../../comments/authors.mts";
-interface HandleFixCodeContext {
+interface HandleTriageContext {
     base: IterateResultBase;
     report: ShepherdReport;
     opts: IterateCommandOptions;
@@ -25,5 +25,5 @@ interface HandleFixCodeContext {
     /** Verified stack-repair guidance, when ancestry is stale. */
     repairInstructions?: string[];
 }
-export declare function handleFixCode(ctx: HandleFixCodeContext): Promise<IterateResult>;
+export declare function handleTriage(ctx: HandleTriageContext): Promise<IterateResult>;
 export {};