pr-shepherd 0.60.0 → 1.0.0

package/bin/config/renames.mjs

@@ -0,0 +1,87 @@
+/**
+ * Pre-v1 camelCase config keys and their v1 replacements. Used only to word the error for an
+ * unknown key: an old key never takes effect. `[]` stands for any array index.
+ */
+const RENAMED_KEYS = {
+    cliCommand: "cli-command",
+    botUsernames: "bot-usernames",
+    ignoreChecks: "checks.ignore",
+    "actions.neverCancelRuns": "checks.never-ignore",
+    "checks.ciTriggerEvents": "checks.ci-trigger-events",
+    "checks.ignoreLogLines": "checks.ignore-log-lines",
+    "iterate.fixAttemptsPerThread": "iterate.triage-attempts-per-thread",
+    "iterate.stallTimeoutMinutes": "iterate.stall-timeout-minutes",
+    "watch.readyDelayMinutes": "iterate.ready-delay-minutes",
+    "iterate.minimizeApprovals": "iterate.minimize-approvals",
+    "iterate.minimizeComments": "iterate.minimize-comments",
+    "iterate.behindBaseHint": "iterate.behind-base-hint",
+    "iterate.reviewOutputMaxChars": "iterate.review-output-max-chars",
+    "iterate.resolveOtherHumanThreads": "iterate.resolve-other-human-threads",
+    "poll.intervalSeconds": "poll.interval-seconds",
+    "poll.stackIntervalFactor": "poll.stack-interval-factor",
+    "poll.timeoutSeconds": "poll.timeout-seconds",
+    "poll.debounceSeconds": "poll.debounce-seconds",
+    "poll.quietStatus": "poll.quiet-status",
+    "poll.reconcileSeconds": "poll.reconcile-seconds",
+    "watch.graphqlQuotaWarnings": "poll.quota-warnings (item keys: remaining-percent, interval-minutes, interval-factor)",
+    "poll.quota-warnings[].remainingPercent": "poll.quota-warnings[].remaining-percent",
+    "poll.quota-warnings[].pollIntervalMinutes": "poll.quota-warnings[].interval-minutes",
+    "poll.quota-warnings[].pollIntervalFactor": "poll.quota-warnings[].interval-factor",
+    "resolve.shaPoll.intervalMs": "apply.sha-poll-interval-seconds (seconds, not milliseconds)",
+    "resolve.shaPoll.maxAttempts": "apply.sha-poll-max-attempts",
+    "mergeStatus.blockingReviewerLogins": "mark-ready.blocking-reviewer-logins",
+    "actions.autoMarkReady": "mark-ready.auto",
+    "merge.commandArgs": "merge.command-args",
+    "actions.autoMinimizeSuppressed": "actions.auto-minimize-suppressed",
+    "actions.workWhileQueued": "actions.work-while-queued",
+};
+/** Pre-v1 keys with no replacement key, and what to do instead. */
+const REMOVED_KEYS = {
+    "poll.mode": "use `pr-shepherd iterate` for single ticks",
+};
+export function formatPath(path) {
+    return path.reduce((text, segment) => {
+        if (typeof segment === "number")
+            return `${text}[${segment}]`;
+        return text === "" ? segment : `${text}.${segment}`;
+    }, "");
+}
+function renameLookupKey(path) {
+    return path.reduce((text, segment) => {
+        if (typeof segment === "number")
+            return `${text}[]`;
+        return text === "" ? segment : `${text}.${segment}`;
+    }, "");
+}
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+/**
+ * Describe one unrecognized key at `path`. Old keys get a rename hint; an unknown section is
+ * searched for renamed keys inside it before it is reported as unknown as a whole.
+ */
+export function describeUnknownKey(path, value) {
+    const hints = describeNestedKey(path, value);
+    return hints.length > 0 ? hints : [`unknown key \`${formatPath(path)}\``];
+}
+function describeNestedKey(path, value) {
+    const lookupKey = renameLookupKey(path);
+    const removed = REMOVED_KEYS[lookupKey];
+    if (removed !== undefined)
+        return [`\`${formatPath(path)}\` was removed: ${removed}`];
+    const renamed = RENAMED_KEYS[lookupKey];
+    if (renamed !== undefined) {
+        const [to, note] = renamed.split(" (");
+        return [`\`${formatPath(path)}\` → \`${to}\`${note === undefined ? "" : ` (${note}`}`];
+    }
+    if (!isPlainObject(value))
+        return [];
+    const children = Object.entries(value).map(([key, child]) => {
+        const childPath = [...path, key];
+        return { childPath, hints: describeNestedKey(childPath, child) };
+    });
+    // A section with no old keys is reported whole; otherwise every other child is reported too.
+    if (children.every(({ hints }) => hints.length === 0))
+        return [];
+    return children.flatMap(({ childPath, hints }) => hints.length > 0 ? hints : [`unknown key \`${formatPath(childPath)}\``]);
+}

package/bin/config/resolve.d.mts

@@ -0,0 +1,31 @@
+import type { z } from "zod";
+import { ShepherdError } from "../exit-codes.mts";
+import { type ConfigFile } from "./schema.mts";
+export type MinimizeCommentsPolicy = ConfigFile["iterate"]["minimize-comments"];
+export type ResolveOtherHumanThreads = ConfigFile["iterate"]["resolve-other-human-threads"];
+export declare const INSTRUCTION_STYLES: readonly ["playbook", "inline"];
+/**
+ * How `triage` `## Instructions` render invariant procedure text. `inline` (default)
+ * prints every step each tick; `playbook` folds them into one `Playbook: "Triage loop".` pointer.
+ */
+export type InstructionStyle = (typeof INSTRUCTION_STYLES)[number];
+export declare function isInstructionStyle(value: unknown): value is InstructionStyle;
+/** One `poll.quota-warnings` band resolved against `poll.interval-seconds`. */
+export interface GraphqlQuotaWarningBand {
+    remainingPercent: number;
+    pollIntervalMinutes: number;
+}
+/** The validated v1 config: file keys as written, plus values derived from them. */
+export type PrShepherdConfig = ConfigFile & {
+    /** Bundled classification rules enabled by `classify.standard`, resolved and sorted by name. */
+    standardRules: string[];
+    /** `poll.quota-warnings` resolved to absolute intervals, highest `remaining-percent` first. */
+    quotaWarningBands: GraphqlQuotaWarningBand[];
+};
+export declare function issueLines(issue: z.core.$ZodIssue, raw: unknown): string[];
+export declare function configError(source: string, lines: string[]): ShepherdError;
+/**
+ * Validate a merged raw config, apply defaults, and derive the resolved values. `source` names
+ * the files the raw object came from; it appears in errors.
+ */
+export declare function resolveConfig(raw: Record<string, unknown>, source?: string): PrShepherdConfig;

package/bin/config/resolve.mjs

@@ -0,0 +1,89 @@
+import { STANDARD_RULE_NAMES } from "../classify/standard/index.mjs";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { findMergeStrategies } from "./merge-command-args.mjs";
+import { describeUnknownKey, formatPath } from "./renames.mjs";
+import { configSchema } from "./schema.mjs";
+export const INSTRUCTION_STYLES = ["playbook", "inline"];
+export function isInstructionStyle(value) {
+    return INSTRUCTION_STYLES.some((style) => style === value);
+}
+function valueAt(root, path) {
+    let current = root;
+    for (const segment of path) {
+        if (current === null || typeof current !== "object")
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+export function issueLines(issue, raw) {
+    const path = issue.path.filter((segment) => typeof segment !== "symbol");
+    if (issue.code === "unrecognized_keys") {
+        return issue.keys.flatMap((key) => describeUnknownKey([...path, key], valueAt(raw, [...path, key])));
+    }
+    return [`\`${formatPath(path)}\`: ${issue.message}`];
+}
+export function configError(source, lines) {
+    return new ShepherdError(`invalid config in ${source}:\n${lines.map((line) => `  - ${line}`).join("\n")}`, EXIT.CONFIG);
+}
+/** Longest `setTimeout` delay, in seconds. A bigger aggregate sleep would clamp to ~24.8 days. */
+const MAX_POLL_INTERVAL_SECONDS = (2 ** 31 - 1) / 1000;
+function resolveQuotaWarnings(config) {
+    const intervalSeconds = config.poll["interval-seconds"];
+    const errors = [];
+    const bands = config.poll["quota-warnings"].map((band, index) => {
+        const factor = band["interval-factor"];
+        const factorMinutes = factor === undefined ? 0 : (intervalSeconds * factor) / 60;
+        const pollIntervalMinutes = Math.max(band["interval-minutes"] ?? 0, factorMinutes);
+        if (!Number.isFinite(pollIntervalMinutes)) {
+            errors.push(`\`poll.quota-warnings[${index}]\`: resolves to a non-finite poll interval`);
+        }
+        return { remainingPercent: band["remaining-percent"], pollIntervalMinutes };
+    });
+    bands.sort((left, right) => right.remainingPercent - left.remainingPercent);
+    const decreasing = bands.some((band, index) => index > 0 && band.pollIntervalMinutes < (bands[index - 1]?.pollIntervalMinutes ?? 0));
+    if (decreasing) {
+        errors.push("`poll.quota-warnings`: the resolved interval must not decrease as remaining-percent decreases");
+    }
+    return { bands, errors };
+}
+/** Checks that span keys which may come from different files, so run after merging. */
+function crossKeyErrors(config) {
+    const errors = [];
+    const aggregate = config.poll["interval-seconds"] * config.poll["stack-interval-factor"];
+    if (!(aggregate <= MAX_POLL_INTERVAL_SECONDS)) {
+        errors.push(`\`poll.interval-seconds\` × \`poll.stack-interval-factor\` must be at most ${MAX_POLL_INTERVAL_SECONDS} seconds, got ${aggregate}`);
+    }
+    const method = config.merge.method;
+    const fromArgs = findMergeStrategies(config.merge["command-args"])[0];
+    if (method !== undefined && fromArgs !== undefined && fromArgs !== method) {
+        errors.push(`\`merge.method\` ${method} conflicts with the \`merge.command-args\` strategy ${fromArgs}`);
+    }
+    return errors;
+}
+function resolveStandardRules(config) {
+    const flags = config.classify.standard;
+    const all = flags["all"] ?? false;
+    return STANDARD_RULE_NAMES.filter((name) => flags[name] ?? all).sort();
+}
+/**
+ * Validate a merged raw config, apply defaults, and derive the resolved values. `source` names
+ * the files the raw object came from; it appears in errors.
+ */
+export function resolveConfig(raw, source = "built-in defaults") {
+    const result = configSchema.safeParse(raw);
+    if (!result.success) {
+        throw configError(source, result.error.issues.flatMap((issue) => issueLines(issue, raw)));
+    }
+    const config = result.data;
+    const quota = resolveQuotaWarnings(config);
+    const errors = [...crossKeyErrors(config), ...quota.errors];
+    if (errors.length > 0)
+        throw configError(source, errors);
+    const resolved = {
+        ...config,
+        standardRules: resolveStandardRules(config),
+        quotaWarningBands: quota.bands,
+    };
+    return resolved;
+}

package/bin/config/schema.d.mts

@@ -0,0 +1,161 @@
+import { z } from "zod";
+/** The config format version this release reads. It tracks the package's semver major. */
+export declare const CONFIG_VERSION = 1;
+export declare const configSchema: z.ZodObject<{
+    version: z.ZodOptional<z.ZodLiteral<1>>;
+    github: z.ZodPrefault<z.ZodObject<{
+        transport: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            graphql: "graphql";
+            rest: "rest";
+        }>>;
+    }, z.core.$strict>>;
+    "cli-command": z.ZodDefault<z.ZodArray<z.ZodString>>;
+    "bot-usernames": z.ZodDefault<z.ZodArray<z.ZodString>>;
+    checks: z.ZodPrefault<z.ZodObject<{
+        ignore: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        "never-ignore": z.ZodDefault<z.ZodArray<z.ZodString>>;
+        "ci-trigger-events": z.ZodDefault<z.ZodArray<z.ZodString>>;
+        "ignore-log-lines": z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    iterate: z.ZodPrefault<z.ZodObject<{
+        "triage-attempts-per-thread": z.ZodDefault<z.ZodNumber>;
+        "stall-timeout-minutes": z.ZodDefault<z.ZodNumber>;
+        "ready-delay-minutes": z.ZodDefault<z.ZodNumber>;
+        "minimize-approvals": z.ZodDefault<z.ZodBoolean>;
+        "minimize-comments": z.ZodDefault<z.ZodEnum<{
+            all: "all";
+            bots: "bots";
+            none: "none";
+        }>>;
+        "behind-base-hint": z.ZodDefault<z.ZodString>;
+        "review-output-max-chars": z.ZodDefault<z.ZodNumber>;
+        "resolve-other-human-threads": z.ZodDefault<z.ZodEnum<{
+            always: "always";
+            none: "none";
+            outdated: "outdated";
+        }>>;
+        instructions: z.ZodDefault<z.ZodEnum<{
+            inline: "inline";
+            playbook: "playbook";
+        }>>;
+    }, z.core.$strict>>;
+    poll: z.ZodPrefault<z.ZodObject<{
+        "interval-seconds": z.ZodDefault<z.ZodNumber>;
+        "stack-interval-factor": z.ZodDefault<z.ZodNumber>;
+        "timeout-seconds": z.ZodDefault<z.ZodNumber>;
+        "debounce-seconds": z.ZodDefault<z.ZodNumber>;
+        "quiet-status": z.ZodDefault<z.ZodBoolean>;
+        "reconcile-seconds": z.ZodDefault<z.ZodNumber>;
+        "quota-warnings": z.ZodDefault<z.ZodArray<z.ZodObject<{
+            "remaining-percent": z.ZodNumber;
+            "interval-minutes": z.ZodOptional<z.ZodNumber>;
+            "interval-factor": z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    apply: z.ZodPrefault<z.ZodObject<{
+        "sha-poll-interval-seconds": z.ZodDefault<z.ZodNumber>;
+        "sha-poll-max-attempts": z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    "mark-ready": z.ZodPrefault<z.ZodObject<{
+        auto: z.ZodDefault<z.ZodBoolean>;
+        "blocking-reviewer-logins": z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    merge: z.ZodPrefault<z.ZodObject<{
+        method: z.ZodOptional<z.ZodEnum<{
+            merge: "merge";
+            rebase: "rebase";
+            squash: "squash";
+        }>>;
+        "command-args": z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    actions: z.ZodPrefault<z.ZodObject<{
+        "auto-minimize-suppressed": z.ZodDefault<z.ZodBoolean>;
+        "work-while-queued": z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    classify: z.ZodPrefault<z.ZodObject<{
+        standard: z.ZodDefault<z.ZodRecord<z.ZodEnum<{
+            [x: string]: string;
+        }> & z.core.$partial, z.ZodBoolean>>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+/** One non-empty config file on disk, which must declare `version`. */
+export declare const configFileSchema: z.ZodObject<{
+    github: z.ZodPrefault<z.ZodObject<{
+        transport: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
+            graphql: "graphql";
+            rest: "rest";
+        }>>;
+    }, z.core.$strict>>;
+    "cli-command": z.ZodDefault<z.ZodArray<z.ZodString>>;
+    "bot-usernames": z.ZodDefault<z.ZodArray<z.ZodString>>;
+    checks: z.ZodPrefault<z.ZodObject<{
+        ignore: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        "never-ignore": z.ZodDefault<z.ZodArray<z.ZodString>>;
+        "ci-trigger-events": z.ZodDefault<z.ZodArray<z.ZodString>>;
+        "ignore-log-lines": z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    iterate: z.ZodPrefault<z.ZodObject<{
+        "triage-attempts-per-thread": z.ZodDefault<z.ZodNumber>;
+        "stall-timeout-minutes": z.ZodDefault<z.ZodNumber>;
+        "ready-delay-minutes": z.ZodDefault<z.ZodNumber>;
+        "minimize-approvals": z.ZodDefault<z.ZodBoolean>;
+        "minimize-comments": z.ZodDefault<z.ZodEnum<{
+            all: "all";
+            bots: "bots";
+            none: "none";
+        }>>;
+        "behind-base-hint": z.ZodDefault<z.ZodString>;
+        "review-output-max-chars": z.ZodDefault<z.ZodNumber>;
+        "resolve-other-human-threads": z.ZodDefault<z.ZodEnum<{
+            always: "always";
+            none: "none";
+            outdated: "outdated";
+        }>>;
+        instructions: z.ZodDefault<z.ZodEnum<{
+            inline: "inline";
+            playbook: "playbook";
+        }>>;
+    }, z.core.$strict>>;
+    poll: z.ZodPrefault<z.ZodObject<{
+        "interval-seconds": z.ZodDefault<z.ZodNumber>;
+        "stack-interval-factor": z.ZodDefault<z.ZodNumber>;
+        "timeout-seconds": z.ZodDefault<z.ZodNumber>;
+        "debounce-seconds": z.ZodDefault<z.ZodNumber>;
+        "quiet-status": z.ZodDefault<z.ZodBoolean>;
+        "reconcile-seconds": z.ZodDefault<z.ZodNumber>;
+        "quota-warnings": z.ZodDefault<z.ZodArray<z.ZodObject<{
+            "remaining-percent": z.ZodNumber;
+            "interval-minutes": z.ZodOptional<z.ZodNumber>;
+            "interval-factor": z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+    apply: z.ZodPrefault<z.ZodObject<{
+        "sha-poll-interval-seconds": z.ZodDefault<z.ZodNumber>;
+        "sha-poll-max-attempts": z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strict>>;
+    "mark-ready": z.ZodPrefault<z.ZodObject<{
+        auto: z.ZodDefault<z.ZodBoolean>;
+        "blocking-reviewer-logins": z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    merge: z.ZodPrefault<z.ZodObject<{
+        method: z.ZodOptional<z.ZodEnum<{
+            merge: "merge";
+            rebase: "rebase";
+            squash: "squash";
+        }>>;
+        "command-args": z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    actions: z.ZodPrefault<z.ZodObject<{
+        "auto-minimize-suppressed": z.ZodDefault<z.ZodBoolean>;
+        "work-while-queued": z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    classify: z.ZodPrefault<z.ZodObject<{
+        standard: z.ZodDefault<z.ZodRecord<z.ZodEnum<{
+            [x: string]: string;
+        }> & z.core.$partial, z.ZodBoolean>>;
+    }, z.core.$strict>>;
+    version: z.ZodLiteral<1>;
+}, z.core.$strict>;
+export type ConfigFile = z.output<typeof configSchema>;

package/bin/config/schema.mjs

@@ -0,0 +1,168 @@
+import { z } from "zod";
+import { STANDARD_RULE_NAMES } from "../classify/standard/index.mjs";
+import { DEFAULT_BOT_USERNAMES } from "./default-bot-usernames.mjs";
+import { findMergeStrategies } from "./merge-command-args.mjs";
+/**
+ * The strict v1 `.pr-shepherdrc.yml` schema. Keys are kebab-case, durations carry their unit in
+ * the key name, and unknown keys or invalid values are hard errors. The defaults declared here
+ * are the built-in defaults; `pr-shepherd.schema.json` is generated from `configFileSchema`.
+ */
+const DEFAULT_QUOTA_WARNINGS = [
+    { "remaining-percent": 30, "interval-factor": 2 },
+    { "remaining-percent": 20, "interval-factor": 5 },
+    { "remaining-percent": 10, "interval-factor": 10 },
+];
+const SHEPHERD_OWNED_MERGE_FLAGS = [
+    "--repo",
+    "-R",
+    "--auto",
+    "--disable-auto",
+    "--match-head-commit",
+    "--admin",
+    "--body-file",
+    "-F",
+    "--help",
+    "-h",
+];
+const strings = () => z.array(z.string());
+const positive = () => z.number().positive();
+const nonNegative = () => z.number().nonnegative();
+const positiveInt = () => z.number().int().positive();
+const regexPattern = z
+    .string()
+    .superRefine((pattern, ctx) => {
+    try {
+        new RegExp(pattern);
+    }
+    catch {
+        ctx.addIssue({ code: "custom", message: `invalid regular expression: ${pattern}` });
+    }
+})
+    // `z.toJSONSchema` drops the refine, so let editors check the pattern.
+    .meta({ format: "regex" });
+const escapeRegex = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+// The same Shepherd-owned flag test as the refine below, stated for editors: the exact flag or
+// `--flag=value`, and any argument that starts with a short flag.
+const SHEPHERD_OWNED_MERGE_FLAG_PATTERN = `^(?:${SHEPHERD_OWNED_MERGE_FLAGS.map((flag) => flag.startsWith("--") ? `${escapeRegex(flag)}(?:=|$)` : escapeRegex(flag)).join("|")})`;
+const mergeCommandArgs = z
+    .array(z.string().meta({ not: { pattern: SHEPHERD_OWNED_MERGE_FLAG_PATTERN } }))
+    .superRefine((args, ctx) => {
+    for (const arg of args) {
+        const owned = SHEPHERD_OWNED_MERGE_FLAGS.some((flag) => arg === flag ||
+            arg.startsWith(`${flag}=`) ||
+            (flag.startsWith("-") && !flag.startsWith("--") && arg.startsWith(flag)));
+        if (owned)
+            ctx.addIssue({ code: "custom", message: `cannot include Shepherd-owned ${arg}` });
+    }
+    let strategies;
+    try {
+        strategies = findMergeStrategies(args);
+    }
+    catch (err) {
+        ctx.addIssue({ code: "custom", message: err instanceof Error ? err.message : String(err) });
+        return;
+    }
+    if (strategies.length > 1) {
+        ctx.addIssue({
+            code: "custom",
+            message: `includes multiple merge strategies: ${strategies.join(", ")}`,
+        });
+    }
+});
+const quotaWarningBand = z
+    .strictObject({
+    "remaining-percent": z.number().int().min(1).max(100),
+    "interval-minutes": positive().optional(),
+    "interval-factor": z.number().min(1).optional(),
+})
+    .refine((band) => band["interval-minutes"] !== undefined || band["interval-factor"] !== undefined, { message: "must define interval-minutes, interval-factor, or both" })
+    // `z.toJSONSchema` drops the refine, so state the same requirement for editors.
+    .meta({ anyOf: [{ required: ["interval-minutes"] }, { required: ["interval-factor"] }] });
+const quotaWarnings = z.array(quotaWarningBand).superRefine((bands, ctx) => {
+    const seen = new Set();
+    for (const band of bands) {
+        const percent = band["remaining-percent"];
+        if (seen.has(percent)) {
+            ctx.addIssue({ code: "custom", message: `duplicate remaining-percent ${percent}` });
+        }
+        seen.add(percent);
+    }
+});
+const standardRuleName = z.enum(["all", ...STANDARD_RULE_NAMES]);
+/** The config format version this release reads. It tracks the package's semver major. */
+export const CONFIG_VERSION = 1;
+// The merged config: `version` is optional because the built-in defaults come from no file.
+export const configSchema = z.strictObject({
+    version: z.literal(CONFIG_VERSION).optional(),
+    github: z
+        .strictObject({ transport: z.enum(["auto", "graphql", "rest"]).default("auto") })
+        .prefault({}),
+    "cli-command": z
+        .array(z.string().regex(/\S/, "must be a non-empty string"))
+        .min(1)
+        .default(() => ["pr-shepherd"]),
+    "bot-usernames": strings().default(() => [...DEFAULT_BOT_USERNAMES]),
+    checks: z
+        .strictObject({
+        ignore: strings().default(() => []),
+        "never-ignore": strings().default(() => []),
+        "ci-trigger-events": strings().default(() => ["pull_request", "pull_request_target"]),
+        "ignore-log-lines": z.array(regexPattern).default(() => []),
+    })
+        .prefault({}),
+    iterate: z
+        .strictObject({
+        "triage-attempts-per-thread": positiveInt().default(3),
+        "stall-timeout-minutes": nonNegative().default(60),
+        "ready-delay-minutes": nonNegative().default(0),
+        "minimize-approvals": z.boolean().default(false),
+        "minimize-comments": z.enum(["all", "bots", "none"]).default("bots"),
+        "behind-base-hint": z.string().default(""),
+        "review-output-max-chars": z.number().int().nonnegative().default(50000),
+        "resolve-other-human-threads": z.enum(["none", "outdated", "always"]).default("none"),
+        instructions: z.enum(["inline", "playbook"]).default("inline"),
+    })
+        .prefault({}),
+    poll: z
+        .strictObject({
+        "interval-seconds": positive().default(60),
+        "stack-interval-factor": z.number().min(1).default(2),
+        "timeout-seconds": positive().default(270),
+        "debounce-seconds": nonNegative().default(60),
+        "quiet-status": z.boolean().default(false),
+        "reconcile-seconds": nonNegative().default(900),
+        "quota-warnings": quotaWarnings.default(() => structuredClone(DEFAULT_QUOTA_WARNINGS)),
+    })
+        .prefault({}),
+    apply: z
+        .strictObject({
+        "sha-poll-interval-seconds": positive().default(2),
+        "sha-poll-max-attempts": positiveInt().default(10),
+    })
+        .prefault({}),
+    "mark-ready": z
+        .strictObject({
+        auto: z.boolean().default(true),
+        "blocking-reviewer-logins": strings().default(() => []),
+    })
+        .prefault({}),
+    merge: z
+        .strictObject({
+        method: z.enum(["merge", "squash", "rebase"]).optional(),
+        "command-args": mergeCommandArgs.default(() => []),
+    })
+        .prefault({}),
+    actions: z
+        .strictObject({
+        "auto-minimize-suppressed": z.boolean().default(true),
+        "work-while-queued": z.boolean().default(false),
+    })
+        .prefault({}),
+    classify: z
+        .strictObject({
+        standard: z.partialRecord(standardRuleName, z.boolean()).default(() => ({})),
+    })
+        .prefault({}),
+});
+/** One non-empty config file on disk, which must declare `version`. */
+export const configFileSchema = configSchema.extend({ version: z.literal(CONFIG_VERSION) });

package/bin/exit-codes.d.mts

@@ -19,7 +19,7 @@ export declare const EXIT: Readonly<{
     /** Draft PR converted to ready for review. */
     readonly MARK_READY: 11;
     /** Agent work required. */
-    readonly FIX_CODE: 12;
+    readonly TRIAGE: 12;
     /** Human attention required. */
     readonly ESCALATE: 13;
     /** `cancel` + `closed` — PR closed without merging. */

package/bin/exit-codes.mjs

@@ -17,7 +17,7 @@ export const EXIT = Object.freeze({
     /** Draft PR converted to ready for review. */
     MARK_READY: 11,
     /** Agent work required. */
-    FIX_CODE: 12,
+    TRIAGE: 12,
     /** Human attention required. */
     ESCALATE: 13,
     /** `cancel` + `closed` — PR closed without merging. */
@@ -67,8 +67,8 @@ export function iterateResultToExitCode(result) {
             return EXIT.WAIT;
         case "mark_ready":
             return EXIT.MARK_READY;
-        case "fix_code":
-            return EXIT.FIX_CODE;
+        case "triage":
+            return EXIT.TRIAGE;
         case "escalate":
             return EXIT.ESCALATE;
         case "merge":

package/bin/github/poll-summary-check-blockers.mjs

@@ -7,7 +7,7 @@ import { failingSummaryCheckNames } from "./poll-summary-checks.mjs";
  * does not start a one-PR session for a wait it would otherwise shepherd.
  */
 export async function applyOpenCheckBlockers(raw, repo, routed, checks, review, stack, requiredContexts) {
-    if (routed.action !== "fix_code" || !routed.reasons.includes("failing-checks"))
+    if (routed.action !== "triage" || !routed.reasons.includes("failing-checks"))
         return routed;
     if ((review.actionable ?? 0) > 0 || checks.incomplete)
         return routed;

package/bin/github/poll-summary-command.mjs

@@ -2,11 +2,15 @@ import { loadConfig } from "../config/load.mjs";
 import { formatPrUrl } from "../pr-reference.mjs";
 import { buildPrShepherdCommand } from "../cli/runner.mjs";
 export function pollCommandFields(repo, pr, isDraft, opts) {
-    const autoMarkReadyDisabled = opts.noAutoMarkReady || loadConfig().actions.autoMarkReady === false;
+    const autoMarkReadyDisabled = opts.noAutoMarkReady || loadConfig()["mark-ready"].auto === false;
     const boundedDraft = isDraft && autoMarkReadyDisabled;
-    const args = boundedDraft
-        ? [formatPrUrl(repo, pr), "--timeout", "1s", "--debounce", "0s", "--no-auto-mark-ready"]
-        : [formatPrUrl(repo, pr), "--until-terminal"];
+    const url = formatPrUrl(repo, pr);
+    // A single tick routes each PR to one `iterate` tick rather than a sleeping poll.
+    const args = opts.tick
+        ? ["iterate", url, ...(boundedDraft ? ["--no-auto-mark-ready"] : [])]
+        : boundedDraft
+            ? [url, "--timeout", "1s", "--debounce", "0s", "--no-auto-mark-ready"]
+            : [url, "--until-terminal"];
     if (opts.merge && opts.stackPrNumber === undefined)
         args.push("--merge");
     if (opts.readyDelaySeconds !== undefined)
@@ -15,8 +19,6 @@ export function pollCommandFields(repo, pr, isDraft, opts) {
         args.push("--stall-timeout", `${opts.stallTimeoutSeconds}s`);
     if (opts.instructions)
         args.push("--instructions", opts.instructions);
-    if (opts.pollMode === "event")
-        args.push("--poll-mode", "event");
     if (opts.noAutoMarkReady && !boundedDraft)
         args.push("--no-auto-mark-ready");
     const pollCommand = buildPrShepherdCommand(args).text;

package/bin/github/poll-summary-projector.mjs

@@ -36,7 +36,7 @@ export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdministe
     }
     const appearsReady = reasons.includes("appears-ready");
     if (opts.stackPrNumber === undefined) {
-        const readyDelaySeconds = opts.readyDelaySeconds ?? (loadConfig().watch?.readyDelayMinutes ?? 10) * 60;
+        const readyDelaySeconds = opts.readyDelaySeconds ?? loadConfig().iterate["ready-delay-minutes"] * 60;
         const readyState = await updateReadyDelay(raw.number, appearsReady, readyDelaySeconds, repo.owner, repo.name, { headSha: raw.headRefOid });
         if (appearsReady && !readyState.shouldCancel) {
             action = "wait";
@@ -134,7 +134,7 @@ function projectQueueRemoval(removal) {
     };
 }
 function detectBlockingReviewer(raw) {
-    const prefixes = (loadConfig().mergeStatus?.blockingReviewerLogins ?? []).map((login) => login.toLowerCase());
+    const prefixes = loadConfig()["mark-ready"]["blocking-reviewer-logins"].map((login) => login.toLowerCase());
     // A team reviewer has a name, not a login, so it never matches a login prefix.
     const matches = (author) => typeof author?.login === "string" &&
         prefixes.some((prefix) => author.login.toLowerCase().startsWith(prefix));

package/bin/github/poll-summary-review.mjs

@@ -11,7 +11,7 @@ import { threadEndedByShepherd } from "../comments/marker.mjs";
 const THREAD_COMMENT_SEPARATOR = "\n\n--- thread comment ---\n\n";
 export async function summarizePollSummaryReview(raw, seen, viewerCanAdminister) {
     const config = loadConfig();
-    const bots = normalizeBotUsernames(config.botUsernames);
+    const bots = normalizeBotUsernames(config["bot-usernames"]);
     const rules = await loadClassifyRules(getEffectiveCwd(), config.standardRules);
     let actionable = 0;
     let incomplete = raw.comments.pageInfo.hasPreviousPage ||