pr-shepherd 0.60.1 → 1.1.0

package/bin/comments/minimize-policy.mjs

@@ -9,11 +9,9 @@ export function shouldMinimizeAuthor(authorType, policy, author, botUsernames =
             return authorType !== "User" || isConfiguredBot;
         case "bots":
             return isConfiguredBot;
-        case "users":
-            return false;
         case "none":
             return false;
         default:
-            throw new Error(`Invalid minimizeComments policy: ${String(policy)}`);
+            throw new Error(`Invalid iterate.minimize-comments policy: ${String(policy)}`);
     }
 }

package/bin/comments/resolve.d.mts

@@ -8,24 +8,6 @@ export interface ResolveResult {
     minimizedComments: string[];
     dismissedReviews: string[];
     errors: string[];
-    /** @deprecated Direct apply forwards every supplied dismissal ID to GitHub. */
-    skippedDismissals?: string[];
-    /** @deprecated Direct apply no longer applies author policy. */
-    skippedHumanResolves?: string[];
-    /** @deprecated Direct apply no longer applies author policy. */
-    skippedHumanMinimizes?: string[];
-    /** @deprecated Direct apply no longer applies author policy. */
-    skippedHumanDismissals?: string[];
-    /** @deprecated Direct apply forwards every supplied reply ID to GitHub. */
-    skippedNonHumanReplies?: string[];
-    /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
-    skippedUnauthorizedReplies?: string[];
-    /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
-    skippedUnauthorizedResolves?: string[];
-    /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
-    skippedUnauthorizedMinimizes?: string[];
-    /** @deprecated Direct apply requests now rely on GitHub's mutation response. */
-    skippedUnauthorizedDismissals?: string[];
     rateLimit?: ResolveRateLimitStop;
     sessionRefusal?: string;
     instructions?: string[];
@@ -38,11 +20,6 @@ export declare function applyResolveOptions(pr: number, repo: RepoInfo, opts: Re
     headSha?: string;
     evidence: Map<string, ReplyEvidence>;
 }): Promise<ResolveResult>;
-/** @deprecated Compatibility alias; use `autoResolveThreads`. */
-export declare function autoResolveOutdated(threadIds: string[]): Promise<{
-    resolved: string[];
-    errors: string[];
-}>;
 export declare function autoResolveThreads(threadIds: string[]): Promise<{
     resolved: string[];
     errors: string[];

package/bin/comments/resolve.mjs

@@ -88,10 +88,6 @@ export async function applyResolveOptions(pr, repo, opts, preflight) {
         ];
     return result;
 }
-/** @deprecated Compatibility alias; use `autoResolveThreads`. */
-export async function autoResolveOutdated(threadIds) {
-    return autoResolveThreads(threadIds);
-}
 export async function autoResolveThreads(threadIds) {
     if (threadIds.length === 0)
         return { resolved: [], errors: [] };

package/bin/comments/review-output-budget.d.mts

@@ -1,5 +1,5 @@
 /**
- * Per-tick output budget for review items (see `iterate.reviewOutputMaxChars`).
+ * Per-tick output budget for review items (see `iterate.review-output-max-chars`).
  *
  * Fetching is complete; only the rendered volume is capped. When the bodies of every surfaced
  * review item fit the budget, nothing changes. Otherwise items are taken in a fixed priority

package/bin/comments/review-output-budget.mjs

@@ -1,5 +1,5 @@
 /**
- * Per-tick output budget for review items (see `iterate.reviewOutputMaxChars`).
+ * Per-tick output budget for review items (see `iterate.review-output-max-chars`).
  *
  * Fetching is complete; only the rendered volume is capped. When the bodies of every surfaced
  * review item fit the budget, nothing changes. Otherwise items are taken in a fixed priority

package/bin/comments/sha-poll.mjs

@@ -2,7 +2,9 @@ import { getPrHeadSha } from "../github/client.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { sleep } from "../util/sleep.mjs";
 export async function waitForSha(pr, repo, expectedSha) {
-    const { intervalMs: SHA_POLL_INTERVAL_MS, maxAttempts: SHA_POLL_MAX_ATTEMPTS } = loadConfig().resolve.shaPoll;
+    const apply = loadConfig().apply;
+    const SHA_POLL_INTERVAL_MS = apply["sha-poll-interval-seconds"] * 1000;
+    const SHA_POLL_MAX_ATTEMPTS = apply["sha-poll-max-attempts"];
     let lastSha;
     for (let attempt = 0; attempt < SHA_POLL_MAX_ATTEMPTS; attempt++) {
         try {

package/bin/comments/thread-visibility.d.mts

@@ -8,5 +8,11 @@ interface ThreadVisibility {
     firstLookThreads: FirstLookThread[];
     toMarkSeen: ReviewThread[];
 }
+/**
+ * Whether an unresolved thread with a known outdated state keeps returning every tick once seen,
+ * given an authorized mutation. The compact summary calls this so its count cannot drift from
+ * `classifyThreadVisibility`.
+ */
+export declare function unresolvedThreadRepeats(thread: ReviewThread, ended: boolean, botUsernames: NormalizedBotUsernames, policy: ResolveOtherHumanThreads): boolean;
 export declare function classifyThreadVisibility(threads: ReviewThread[], seenMap: Map<string, SeenMarker>, botUsernames?: NormalizedBotUsernames, repeatableThreadIds?: ReadonlySet<string>, resolveOtherHumanThreads?: ResolveOtherHumanThreads): ThreadVisibility;
 export {};

package/bin/comments/thread-visibility.mjs

@@ -3,6 +3,9 @@ import { threadTranscriptBody } from "../threads/transcript.mjs";
 import { isConfiguredBotAuthor, isHumanAuthor, isViewerAuthoredHuman, } from "./authors.mjs";
 import { threadEndedByShepherd } from "./marker.mjs";
 import { shouldResolveOtherHumanThread } from "./thread-resolve-policy.mjs";
+function isOrdinaryHuman(thread, botUsernames) {
+    return isHumanAuthor(thread) && !isConfiguredBotAuthor(thread, botUsernames);
+}
 function withEdited(thread, edited) {
     return edited ? { ...thread, edited: true } : thread;
 }
@@ -20,9 +23,33 @@ function classifyFirstLookThread(thread, seenMap, firstLookStatus) {
         return null;
     return { ...visible, firstLookStatus };
 }
+/** An unresolved, current thread whose author class makes it repeat while a mutation is authorized. */
+function repeatsAsActive(thread, ended, botUsernames, policy) {
+    if (thread.isOutdated !== false || thread.isMinimized === true || ended)
+        return false;
+    return (isConfiguredBotAuthor(thread, botUsernames) ||
+        isViewerAuthoredHuman(thread, botUsernames) ||
+        (isOrdinaryHuman(thread, botUsernames) && policy === "always"));
+}
+/** An unresolved thread that is resolution-only work: outdated, minimized or ended by Shepherd. */
+function isResolutionOnlyCandidate(thread, ended, botUsernames, policy) {
+    if (!ended)
+        return thread.isOutdated === true || thread.isMinimized === true;
+    if (!isOrdinaryHuman(thread, botUsernames))
+        return true;
+    return (isViewerAuthoredHuman(thread, botUsernames) || shouldResolveOtherHumanThread(thread, policy));
+}
+/**
+ * Whether an unresolved thread with a known outdated state keeps returning every tick once seen,
+ * given an authorized mutation. The compact summary calls this so its count cannot drift from
+ * `classifyThreadVisibility`.
+ */
+export function unresolvedThreadRepeats(thread, ended, botUsernames, policy) {
+    return (repeatsAsActive(thread, ended, botUsernames, policy) ||
+        isResolutionOnlyCandidate(thread, ended, botUsernames, policy));
+}
 export function classifyThreadVisibility(threads, seenMap, botUsernames = new Set(), repeatableThreadIds, resolveOtherHumanThreads = "none") {
     const shouldRepeat = (thread) => repeatableThreadIds?.has(thread.id) ?? true;
-    const isOrdinaryHuman = (thread) => isHumanAuthor(thread) && !isConfiguredBotAuthor(thread, botUsernames);
     const unknownStatusThreads = threads.filter((thread) => thread.isResolved === undefined || thread.isOutdated === undefined);
     const unresolvedThreads = threads.filter((thread) => thread.isResolved === false && thread.isOutdated !== undefined);
     const activeThreads = unresolvedThreads
@@ -30,25 +57,13 @@ export function classifyThreadVisibility(threads, seenMap, botUsernames = new Se
         .flatMap((t) => {
         if (threadEndedByShepherd(t))
             return [];
-        const repeatAuthor = isConfiguredBotAuthor(t, botUsernames) ||
-            isViewerAuthoredHuman(t, botUsernames) ||
-            (isOrdinaryHuman(t) && resolveOtherHumanThreads === "always");
-        if (repeatAuthor && shouldRepeat(t))
+        if (repeatsAsActive(t, false, botUsernames, resolveOtherHumanThreads) && shouldRepeat(t))
             return [t];
         const visible = classifyVisibleThread(t, seenMap);
         return visible ? [visible] : [];
     });
     const resolutionOnlyThreads = unresolvedThreads
-        .filter((t) => {
-        const endedByShepherd = threadEndedByShepherd(t);
-        if (endedByShepherd) {
-            if (!isOrdinaryHuman(t))
-                return true;
-            return (isViewerAuthoredHuman(t, botUsernames) ||
-                shouldResolveOtherHumanThread(t, resolveOtherHumanThreads));
-        }
-        return t.isOutdated || t.isMinimized;
-    })
+        .filter((t) => isResolutionOnlyCandidate(t, threadEndedByShepherd(t), botUsernames, resolveOtherHumanThreads))
         .flatMap((t) => {
         const visible = classifyVisibleThread(t, seenMap);
         if (visible)

package/bin/config/default-bot-usernames.d.mts

@@ -0,0 +1,2 @@
+/** Built-in `bot-usernames`: known code-review bot logins treated as bots. */
+export declare const DEFAULT_BOT_USERNAMES: string[];

package/bin/config/default-bot-usernames.mjs

@@ -0,0 +1,15 @@
+/** Built-in `bot-usernames`: known code-review bot logins treated as bots. */
+export const DEFAULT_BOT_USERNAMES = [
+    "chatgpt-connector",
+    "openai-codex",
+    "codex",
+    "claude",
+    "copilot-pull-request-reviewer",
+    "gemini-code-assist",
+    "coderabbitai",
+    "greptile-apps",
+    "qodo-merge-pro",
+    "deepsource-io",
+    "sonarqubecloud",
+    "what-the-diff",
+];

package/bin/config/load.d.mts

@@ -1,143 +1,9 @@
-import { type MergeMethod } from "./merge-method.mts";
-import { type GithubTransport } from "../github/transport-mode.mts";
-declare const MINIMIZE_COMMENTS_POLICIES: readonly ["all", "bots", "users", "none"];
-export type MinimizeCommentsPolicy = (typeof MINIMIZE_COMMENTS_POLICIES)[number];
-declare const RESOLVE_OTHER_HUMAN_THREADS: readonly ["none", "outdated", "always"];
-export type ResolveOtherHumanThreads = (typeof RESOLVE_OTHER_HUMAN_THREADS)[number];
-export declare const INSTRUCTION_STYLES: readonly ["playbook", "inline"];
+import { type PrShepherdConfig } from "./resolve.mts";
+export type { GraphqlQuotaWarningBand, InstructionStyle, MinimizeCommentsPolicy, PrShepherdConfig, ResolveOtherHumanThreads, } from "./resolve.mts";
 /**
- * How `fix_code` `## Instructions` render invariant procedure text. `inline` (default)
- * prints every step each tick; `playbook` points at the shipped "Fix-code loop" playbook.
+ * Load the config for the effective cwd: built-in defaults, then `$HOME`, then each ancestor
+ * down to cwd, closest file winning. Any invalid file throws a `ShepherdError` (exit 78).
  */
-export type InstructionStyle = (typeof INSTRUCTION_STYLES)[number];
-export declare function isInstructionStyle(value: unknown): value is InstructionStyle;
-export declare const POLL_MODES: readonly ["auto", "poll", "event"];
-/**
- * `poll` blocks and loops. `event` runs one tick and reports `nextCheck`. `auto` resolves to
- * `event` when `CLAUDE_CODE_REMOTE=true` and to `poll` everywhere else.
- */
-export type PollMode = (typeof POLL_MODES)[number];
-export declare function isPollMode(value: unknown): value is PollMode;
-export interface GraphqlQuotaWarningBand {
-    remainingPercent: number;
-    pollIntervalMinutes: number;
-}
-interface PollConfig {
-    intervalSeconds: number;
-    /** Multiplier for aggregate polls when `--interval` is omitted. Finite and at least 1. */
-    stackIntervalFactor: number;
-    timeoutSeconds: number;
-    debounceSeconds: number;
-    quietStatus: boolean;
-    mode: PollMode;
-    /**
-     * Longest gap between GraphQL snapshots while conditional REST reads report an idle PR
-     * unchanged. `0` disables the REST change detectors on the GraphQL transport.
-     */
-    reconcileSeconds: number;
-}
-export interface PrShepherdConfig {
-    /** GitHub API settings; auto prefers GraphQL outside Claude Code cloud sessions. */
-    github?: {
-        transport?: GithubTransport;
-    };
-    /**
-     * Optional user classification configuration; preserved for rule consumers. Shepherd reads
-     * only `classify.standard`, a map of bundled rule name (or `all`) to boolean.
-     */
-    classify?: unknown;
-    /** Bundled classification rules enabled by `classify.standard`, resolved and sorted by name. */
-    standardRules: string[];
-    /** Argv prefix for every pr-shepherd command Shepherd emits, e.g. `["pnpm", "exec", "pr-shepherd"]`. */
-    cliCommand: string[];
-    /** GitHub logins that should be treated as bots even when GitHub reports User/Unknown. */
-    botUsernames: string[];
-    /** Case-insensitive glob patterns for check/status context names Shepherd should ignore. */
-    ignoreChecks: string[];
-    iterate: {
-        fixAttemptsPerThread: number;
-        stallTimeoutMinutes: number;
-        /**
-         * When `true`, APPROVED-state reviews are also eligible for minimization — defaults to `false`
-         * so approvals stay visible. `minimizeComments` still filters by GitHub author type.
-         */
-        minimizeApprovals: boolean;
-        /**
-         * Which GitHub author classes should be auto-minimized for minimizable PR comments and review
-         * summaries. Items excluded by this policy are still surfaced once (and after edits) via seen
-         * markers so they do not repeat forever.
-         */
-        minimizeComments: MinimizeCommentsPolicy;
-        /**
-         * One-liner hint appended to the `fix_code` push instruction when the branch is behind its
-         * base — e.g. "rebase --force-with-lease" or "see .agents/skills/git-and-prs.md". Empty
-         * (default) omits the hint entirely; the CLI never prescribes rebase/merge mechanics itself.
-         */
-        behindBaseHint: string;
-        /**
-         * Per-tick budget for review-item bodies in `fix_code` output, in characters. Over budget,
-         * iterate shows a priority-ordered subset and holds the rest (unmarked) for later ticks.
-         * `0` disables the cap.
-         */
-        reviewOutputMaxChars: number;
-        /**
-         * When to resolve other-human inline threads after Shepherd replies. Own and bot threads
-         * always reply-and-resolve. `none` (default) keeps other humans reply-only; `outdated`
-         * also resolves when GitHub reports `isOutdated`; `always` pairs reply-and-resolve.
-         */
-        resolveOtherHumanThreads: ResolveOtherHumanThreads;
-        /**
-         * `inline` (default) prints the commit/push step of `fix_code` instructions
-         * every tick; `playbook` folds it into one `Playbook: "Fix-code loop"` pointer. The
-         * default is inline because the token bench measured playbook as a net cost: it adds a read. The `--instructions` flag and MCP `instructions` input override per call.
-         */
-        instructions: InstructionStyle;
-    };
-    poll: PollConfig;
-    watch: {
-        readyDelayMinutes: number;
-        graphqlQuotaWarnings: GraphqlQuotaWarningBand[];
-    };
-    resolve: {
-        shaPoll: {
-            intervalMs: number;
-            maxAttempts: number;
-        };
-    };
-    checks: {
-        ciTriggerEvents: string[];
-        /** Regex patterns matched against each raw log line; matching lines are dropped from log excerpts. Empty by default — no lines are stripped unless configured. */
-        ignoreLogLines: string[];
-    };
-    mergeStatus: {
-        blockingReviewerLogins: string[];
-    };
-    merge?: {
-        /** Preferred merge method. Used only when the repository allows it. */
-        method?: MergeMethod;
-        /** Options added to ordinary `gh pr merge` commands. Queue commands never use these. */
-        commandArgs: string[];
-    };
-    actions: {
-        autoMinimizeSuppressed: boolean;
-        autoMarkReady: boolean;
-        /** Legacy-named patterns that keep matching Actions checks visible despite ignoreChecks. */
-        neverCancelRuns: string[];
-        /**
-         * When `false` (default), `iterate --merge` defers non-CI actionable work
-         * (review threads, comments, changes-requested reviews, review summaries)
-         * while the PR sits in the merge queue, since a Shepherd-initiated push
-         * would eject it. When `true`, restores pre-existing behavior: actionable
-         * work is handled immediately regardless of queue membership.
-         */
-        workWhileQueued: boolean;
-        /** @deprecated Accepted for compatibility, ignored by the loader. */
-        autoResolveOutdated?: boolean;
-        /** @deprecated Accepted for compatibility, ignored by the loader. */
-        commitSuggestions?: boolean;
-    };
-}
 export declare function loadConfig(): PrShepherdConfig;
 /** Reset the config cache — for use in tests that change directories. */
 export declare function _resetConfigCache(): void;
-export {};