pr-shepherd 0.34.0 → 0.36.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.34.0",
+  "version": "0.36.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"
@@ -10,5 +10,6 @@
   "repository": "https://github.com/jonathanong/pr-shepherd",
   "license": "MIT",
   "keywords": ["github", "pull-request", "ci", "code-review", "automation"],
-  "skills": "./plugins/pr-shepherd/skills/"
+  "skills": "./plugins/pr-shepherd/skills/",
+  "mcpServers": "./plugins/pr-shepherd/.mcp.json"
 }

package/.grok-plugin/marketplace.json

@@ -0,0 +1,17 @@
+{
+  "name": "jonathanong",
+  "description": "Jonathan Ong's Grok plugins",
+  "owner": {
+    "name": "Jonathan Ong",
+    "email": "jonathanrichardong@gmail.com"
+  },
+  "plugins": [
+    {
+      "name": "pr-shepherd",
+      "description": "Autonomous PR CI monitor and review-comment resolver",
+      "source": { "type": "local", "path": "./plugins/pr-shepherd" },
+      "category": "productivity",
+      "homepage": "https://github.com/jonathanong/pr-shepherd"
+    }
+  ]
+}

package/README.md

@@ -2,13 +2,30 @@
 
 Autonomous PR CI monitor and review-comment resolver for agentic coding tools, including Claude Code and Codex.
 
-The goal is to help an agent carry a planned change to a human-reviewable PR: passing CI, no unresolved Shepherd-visible work, and a useful PR description/journal.
+## Why
+
+An agent finishing a PR should think about code, not reconstruct GitHub state or invent a next-step policy each tick. Without Shepherd it fans out across GitHub MCP, `gh`, and GraphQL, then guesses what to do with the result.
+
+## What it does
+
+1. **Gather all context for a PR** in one invocation: review threads, comments, replies, summaries, CI, mergeability, merge requirements, first-look / outdated / edited items, and author provenance.
+2. **Provide deterministic actions for the agent**: exactly one of `WAIT`, `MARK_READY`, `FIX_CODE`, `CANCEL`, or `ESCALATE`, plus numbered `## Instructions` and explicit `apply` / `build_suggestion_patch` mutations. The agent still decides whether a comment or CI failure needs a code change. Shepherd does not classify signal vs noise and does not mutate git.
+
+Highlights:
+
+- Batched GraphQL reads and writes (plus REST where GraphQL cannot) so one poll replaces a tool-call fan-out. MCP `iterate` is one tick and the client owns recurrence; `--debounce` is a poll-dispatcher settle window, not an MCP tool.
+- CI summaries include failed checks, and the failed job/step plus a log excerpt when triage can fetch them. Job and log details are omitted for `STARTUP_FAILURE` and `CANCELLED`; agents may still inspect logs.
+- Handles GitHub comment types (comments, threads, replies) and their states, including first-look, outdated, resolved, minimized, and edited.
+- `apply` batches resolve / reply / minimize / dismiss. `build_suggestion_patch` emits a unified diff in output, not a patch file, and does not mutate git.
+- `BEHIND` is mergeability information, not a rebase or a guarantee that the next push is at the default-branch tip. The agent can update the branch before pushing.
+
+Full reference: [docs/README.md](docs/README.md). Feature matrix: [docs/features.md](docs/features.md).
 
 ## How It Works
 
-`pr-shepherd` moves deterministic PR orchestration into a CLI. The CLI fetches GitHub state, emits raw-enough context, and prints a numbered `## Instructions` section for the calling agent to follow. The agent still decides whether a comment or CI failure requires a code change.
+`pr-shepherd` moves deterministic PR orchestration into a local MCP server, with a CLI for shells and CI. Both interfaces fetch the same GitHub state, emit raw-enough context, and return a numbered plan for the calling agent to follow.
 
-The shipped skills invoke the default poll dispatcher (`pr-shepherd <PR>`, equivalent to `pr-shepherd poll <PR>`). Use `pr-shepherd iterate <PR>` for one single tick.
+The MCP server exposes three tools: `iterate`, `apply`, and `build_suggestion_patch`. `apply` accepts ordered review mutations, file-view mutations, and journal entries. The shipped skills are thin dispatchers for those tools.
 
 Each tick returns exactly one action:
 
@@ -25,12 +42,14 @@ Example shape:
 
 # PR #123 [FIX_CODE]
 
-**status** `UNRESOLVED_COMMENTS` · **merge** `BLOCKED` · **state** `OPEN` · **repo** `owner/repo`
+**status** `UNRESOLVED_COMMENTS` · **merge** `CLEAN` · **state** `OPEN` · **repo** `owner/repo`
 **summary** 3 passing
+Approvals: None [Not Required]
+Conversations Resolved: No [Not Required]
 
 ## Review threads
 
-### `threadId=PRRT_kwDOSGizTs58XB1L` — `src/commands/iterate/index.mts:42` (@alice)
+### `threadId=PRRT_kwDOSGizTs58XB1L` — `src/commands/iterate/index.mts:42` (@alice · User · MEMBER)
 
 > The variable name is misleading.
 
@@ -42,17 +61,17 @@ Example shape:
 ## Post-fix push
 
 - base: `main`
-- resolve: `pr-shepherd resolve 123 --reply-thread-ids PRRT_kwDOSGizTs58XB1L --message "$DISMISS_MESSAGE" --require-sha "$HEAD_SHA"`
+- apply review: `pr-shepherd apply review 123 --reply-thread-ids PRRT_kwDOSGizTs58XB1L --message "$DISMISS_MESSAGE" --require-sha "$HEAD_SHA"`
 
 ## Instructions
 
-1. Decide for each item under `## Review threads` and `## Failing checks` whether a code change is warranted. If code changes are needed, apply edits, commit, rebase/push according to the repository's conventions, then run the `resolve:` command.
+1. Decide for each item under `## Review threads` and `## Failing checks` whether a code change is warranted. If code changes are needed, apply edits, commit, push, then run the `apply review:` command.
 2. For each failing check under `## Failing checks`: fetch logs when needed and decide whether to rerun or fix.
-3. Run the `resolve:` command shown above with a specific `$DISMISS_MESSAGE` and the relevant `$HEAD_SHA`.
+3. Run the `apply review:` command shown above, substituting `$HEAD_SHA` and `$DISMISS_MESSAGE`.
 4. Stop this iteration.
 ```
 
-See [docs/actions.md](docs/actions.md) for the complete output contract.
+See [docs/actions.md](docs/actions.md) for the complete output contract. Iterate/poll PR outcomes use exit codes `0` and `10`–`14`; command and GitHub failures use `sysexits.h` codes — [docs/exit-codes.md](docs/exit-codes.md).
 
 ## Workflow Assumptions
 
@@ -64,7 +83,7 @@ This system is opinionated and works best with PRs that use required status chec
 - Every review thread/comment/review summary is surfaced at least once, even if already outdated, resolved, or minimized; edited items re-surface through seen markers.
 - Draft PRs can be marked ready automatically when clean; disable with `actions.autoMarkReady: false` or `--no-auto-mark-ready`.
 - The CLI never performs git mutations. It emits instructions; the caller commits, rebases, pushes, and handles repository hooks.
-- `commit-suggestion` turns one GitHub suggestion thread into a patch and commit instructions, but still does not edit the working tree or git history.
+- `build_suggestion_patch` turns one GitHub suggestion thread into a patch and commit metadata, but never edits the working tree or git history.
 
 ## Usage
 
@@ -84,57 +103,47 @@ Codex:
 /goal $pr-shepherd 42
 ```
 
-Direct CLI:
+Grok:
+
+```text
+/pr-shepherd                          # infer PR from current branch
+/pr-shepherd 42
+```
+
+MCP clients call `iterate` once per tick, then use `apply` for review/file/journal mutations and `build_suggestion_patch` for an anchored suggestion. `iterate` returns the same structured action data as the CLI, including its review mutation arguments. The client owns recurrence, so this works consistently in Codex, Claude Code, Grok, and any other stdio MCP client.
+
+The CLI remains useful for shell workflows. Its canonical polling form is:
 
 ```sh
 pr-shepherd 42                         # poll until non-WAIT or timeout
 pr-shepherd 42 --interval 60s --timeout 270s
 pr-shepherd 42 --quiet-status          # print only changed WAIT status snapshots
 pr-shepherd 42 --until-terminal        # continue through WAIT/MARK_READY until work or terminal state
+pr-shepherd 42 --debounce 5m           # wait 5m after first FIX_CODE, then return one batched tick
 pr-shepherd 42 --ready-delay 15m
 pr-shepherd iterate 42                 # single tick
-pr-shepherd poll 42                    # explicit poll command
-```
-
-### Resolve Review Items
-
-```sh
-pr-shepherd resolve 42 --reply-thread-ids PRRT_abc --message "Renamed the variable for clarity." --require-sha "$(git rev-parse HEAD)"
-```
-
-Use `pr-shepherd iterate 42` or `pr-shepherd 42` to fetch the next PR action. `resolve` requires at least one action flag and only applies explicit review-state mutations.
-
-### Apply One Suggestion Thread
-
-```sh
-pr-shepherd commit-suggestion 42 --thread-id PRRT_abc --message "rename value for clarity"
 ```
 
-The output contains a diff and numbered instructions for applying, staging, committing, resolving, and pushing.
-
-### Mark Files As Viewed
-
-```sh
-pr-shepherd mark-files-as-viewed 42 --tests
-pr-shepherd mark-files-as-viewed 42 src/a.ts --match '^docs/'
-```
+### Apply Review, File, And Journal Changes
 
-The shipped `mark-files-as-viewed` skill maps a standalone `tests` argument to `--tests`.
+Use `apply` with ordered operations to reply/resolve/minimize/dismiss review items, mark changed files viewed, or append an idempotent Shepherd Journal item. Use `build_suggestion_patch` to turn one review suggestion into a validated patch and commit metadata; it never changes the worktree or git history.
 
 ### Clean Local State
 
 `pr-shepherd` stores seen markers, fix-attempt counters, stall fingerprints, ready-delay markers, and logs under `$PR_SHEPHERD_STATE_DIR` (default `$TMPDIR/pr-shepherd-state`).
 
 ```sh
-pr-shepherd clean current
-pr-shepherd clean repo
-pr-shepherd clean all --dry-run
-pr-shepherd log-file
+pr-shepherd admin clean current
+pr-shepherd admin clean repo
+pr-shepherd admin clean all --dry-run
+pr-shepherd admin log-file
 ```
 
 ## Install
 
-Skill and plugin install methods add the skill definitions only. Install the `pr-shepherd` CLI separately wherever the skill runs.
+The plugin launches the version-matched `pr-shepherd-mcp` binary from the `pr-shepherd` npm package automatically. Install the `pr-shepherd` CLI separately only when you want the shell interface.
+
+To register the MCP server without the plugin, or to wire a local checkout, see [docs/mcp.md](docs/mcp.md).
 
 ### Claude Code
 
@@ -164,9 +173,33 @@ codex plugin marketplace add ~/.codex/plugin-sources/pr-shepherd
 
 After adding the marketplace, install/enable the `pr-shepherd` plugin from Codex. The marketplace root must contain `.agents/plugins/marketplace.json` and `plugins/pr-shepherd/`.
 
+### Grok
+
+```bash
+grok plugin marketplace add jonathanong/pr-shepherd
+grok plugin install pr-shepherd --trust
+```
+
+Grok starts a plugin's MCP server only after the plugin is trusted. Confirm with `grok mcp list` or `/mcps`.
+
+### MCP server only
+
+Any stdio MCP client can run the published binary without installing the plugin:
+
+```bash
+claude mcp add --transport stdio --scope user pr-shepherd -- \
+  npx --yes --package pr-shepherd@<version> pr-shepherd-mcp
+codex mcp add pr-shepherd -- \
+  npx --yes --package pr-shepherd@<version> pr-shepherd-mcp
+grok mcp add pr-shepherd -- \
+  npx --yes --package pr-shepherd@<version> pr-shepherd-mcp
+```
+
+Replace `<version>` with a published version. Full config-file examples, tool schemas, and local-checkout wiring are in [docs/mcp.md](docs/mcp.md).
+
 ## Configuration
 
-Create `.pr-shepherdrc.yml` in your project root or an ancestor directory.
+Create `.pr-shepherdrc.yml` in your project root, an ancestor directory, or `$HOME`. Every file on the walk is deep-merged; closer directories override farther ones.
 
 ```yaml
 ignoreChecks:
@@ -175,7 +208,7 @@ iterate:
   fixAttemptsPerThread: 5
   stallTimeoutMinutes: 60
   minimizeApprovals: false
-  minimizeComments: all # all | bots | users | none
+  minimizeComments: all # all | bots | none
 checks:
   ciTriggerEvents:
     - pull_request
@@ -218,6 +251,10 @@ TypeScript rules are loaded by the runtime's native TypeScript support; keep the
 
 Ready-to-use examples for common patterns are in [`examples/classification/`](examples/classification/).
 
+## CLI aliases
+
+`poll`, `resolve`, `commit-suggestion`, `mark-files-as-viewed`, `journal`, `clean`, and `log-file` are CLI aliases. Prefer default polling/`iterate` in a shell and the MCP `iterate`, `apply`, and `build_suggestion_patch` tools in an agent client.
+
 ## Requirements
 
 - Node.js >= 22.18.0, Bun, or Deno
@@ -226,7 +263,7 @@ Ready-to-use examples for common patterns are in [`examples/classification/`](ex
 
 ## Docs
 
-Full reference: [docs/README.md](docs/README.md).
+Full reference, grouped by the two jobs (gather context / emit actions): [docs/README.md](docs/README.md).
 
 ## Harness Ecosystem
 

package/bin/api.d.mts

@@ -0,0 +1,80 @@
+import { type JournalResult } from "./commands/journal/index.mts";
+import { type MarkFilesAsViewedResult } from "./commands/mark-files-as-viewed.mts";
+import type { ResolveResult } from "./comments/resolve.mts";
+import type { CommitSuggestionResult, IterateCommandOptions, IterateResult } from "./types.mts";
+export interface CreatePrShepherdOptions {
+    /** Working directory used for git, config, and classification-rule lookups. */
+    cwd?: string;
+}
+/** A positive PR number or canonical GitHub pull-request URL. */
+export type PrReference = number | string;
+export type IterateInput = Omit<IterateCommandOptions, "format" | "prNumber"> & {
+    pr?: PrReference;
+};
+export interface ReviewMutationsOperation {
+    type: "review_mutations";
+    resolveThreadIds?: string[];
+    replyThreadIds?: string[];
+    minimizeCommentIds?: string[];
+    dismissReviewIds?: string[];
+    /** Required when replying to a thread or dismissing a review. */
+    message?: string;
+    requireSha?: string;
+}
+export interface MarkFilesViewedOperation {
+    type: "mark_files_viewed";
+    files?: string[];
+    tests?: boolean;
+    matchPatterns?: string[];
+}
+export interface AppendJournalOperation {
+    type: "append_journal";
+    item: string;
+    dryRun?: boolean;
+}
+/** Mutations are run in this exact list order after every operation is validated. */
+export type ApplyOperation = ReviewMutationsOperation | MarkFilesViewedOperation | AppendJournalOperation;
+export interface ApplyInput {
+    /** PR shared by every operation in this ordered apply request. */
+    pr?: PrReference;
+    operations: ApplyOperation[];
+}
+export type ApplyOperationResult = {
+    type: "review_mutations";
+    result: ResolveResult;
+} | {
+    type: "mark_files_viewed";
+    result: MarkFilesAsViewedResult;
+} | {
+    type: "append_journal";
+    result: JournalResult;
+};
+export interface ApplyResult {
+    operations: ApplyOperationResult[];
+}
+export interface BuildSuggestionPatchInput {
+    pr?: PrReference;
+    threadId: string;
+    message: string;
+    description?: string;
+}
+export interface PrShepherd {
+    iterate(input?: IterateInput): Promise<IterateResult>;
+    apply(input: ApplyInput): Promise<ApplyResult>;
+    buildSuggestionPatch(input: BuildSuggestionPatchInput): Promise<CommitSuggestionResult>;
+}
+/** Raised before any API mutation when an input cannot be validated. */
+export declare class PrShepherdValidationError extends Error {
+    constructor(message: string);
+}
+/** Raised when a later ordered apply operation fails after earlier operations completed. */
+export declare class PartialApplyError extends Error {
+    readonly failedIndex: number;
+    readonly completed: ApplyOperationResult[];
+    constructor(failedIndex: number, completed: ApplyOperationResult[], cause: unknown);
+}
+/**
+ * Creates the programmatic API. The returned object intentionally exposes only
+ * read/plan, ordered apply, and suggestion-patch operations.
+ */
+export declare function createPrShepherd(options?: CreatePrShepherdOptions): PrShepherd;

package/bin/api.mjs

@@ -0,0 +1,236 @@
+/* eslint-disable max-lines */
+import { resolve } from "node:path";
+import { runCommitSuggestion } from "./commands/commit-suggestion.mjs";
+import { runIterate } from "./commands/iterate/index.mjs";
+import { runJournal } from "./commands/journal/index.mjs";
+import { validateJournalItem } from "./commands/journal/transform.mjs";
+import { runMarkFilesAsViewed, } from "./commands/mark-files-as-viewed.mjs";
+import { runResolveMutate } from "./commands/resolve-mutate.mjs";
+import { runWithExecutionCwd } from "./execution-context.mjs";
+import { getRepoInfo } from "./github/client.mjs";
+/** Raised before any API mutation when an input cannot be validated. */
+export class PrShepherdValidationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PrShepherdValidationError";
+    }
+}
+/** Raised when a later ordered apply operation fails after earlier operations completed. */
+export class PartialApplyError extends Error {
+    failedIndex;
+    completed;
+    constructor(failedIndex, completed, cause) {
+        const message = cause instanceof Error ? cause.message : String(cause);
+        super(`apply operation ${failedIndex} failed: ${message}`, { cause });
+        this.name = "PartialApplyError";
+        this.failedIndex = failedIndex;
+        this.completed = completed;
+    }
+}
+/**
+ * Creates the programmatic API. The returned object intentionally exposes only
+ * read/plan, ordered apply, and suggestion-patch operations.
+ */
+export function createPrShepherd(options = {}) {
+    const cwd = options.cwd === undefined ? undefined : resolve(options.cwd);
+    return Object.freeze({
+        iterate(input = {}) {
+            const { pr: _pr, ...options } = input;
+            return runWithExecutionCwd(cwd, async () => {
+                const prNumber = await resolvePrReference(input.pr);
+                return runIterate({ ...options, prNumber, format: "json" });
+            });
+        },
+        apply(input) {
+            return runWithExecutionCwd(cwd, async () => {
+                validateApplyInput(input);
+                const prNumber = await resolvePrReference(input.pr);
+                const results = [];
+                for (let index = 0; index < input.operations.length; index += 1) {
+                    const operation = input.operations[index];
+                    try {
+                        switch (operation.type) {
+                            case "review_mutations": {
+                                const { type: _type, message, ...options } = operation;
+                                const result = await runResolveMutate({
+                                    ...options,
+                                    prNumber,
+                                    dismissMessage: message,
+                                    format: "json",
+                                });
+                                results.push({ type: operation.type, result });
+                                break;
+                            }
+                            case "mark_files_viewed": {
+                                const result = await runMarkFilesAsViewed({
+                                    prNumber,
+                                    files: operation.files ?? [],
+                                    tests: operation.tests,
+                                    matchPatterns: operation.matchPatterns,
+                                    format: "json",
+                                });
+                                results.push({ type: operation.type, result });
+                                break;
+                            }
+                            case "append_journal": {
+                                const result = await runJournal({
+                                    prNumber,
+                                    rawItem: operation.item,
+                                    dryRun: operation.dryRun ?? false,
+                                });
+                                results.push({ type: operation.type, result });
+                                break;
+                            }
+                        }
+                    }
+                    catch (error) {
+                        if (results.length === 0)
+                            throw error;
+                        throw new PartialApplyError(index, results, error);
+                    }
+                }
+                return { operations: results };
+            });
+        },
+        buildSuggestionPatch(input) {
+            validateSuggestionPatchInput(input);
+            const { pr: _pr, ...options } = input;
+            return runWithExecutionCwd(cwd, async () => {
+                const prNumber = await resolvePrReference(input.pr);
+                return runCommitSuggestion({ ...options, prNumber, format: "json" });
+            });
+        },
+    });
+}
+function validateApplyInput(input) {
+    if (!input || !Array.isArray(input.operations) || input.operations.length === 0) {
+        throw new PrShepherdValidationError("apply requires a non-empty operations array");
+    }
+    for (const operation of input.operations)
+        validateOperation(operation);
+    parsePrReference(input.pr);
+}
+function validateOperation(operation) {
+    if (!operation || typeof operation !== "object") {
+        throw new PrShepherdValidationError("apply operation must be an object");
+    }
+    switch (operation.type) {
+        case "review_mutations":
+            validateReviewMutations(operation);
+            return;
+        case "mark_files_viewed":
+            validateMarkFilesViewed(operation);
+            return;
+        case "append_journal":
+            if (typeof operation.item !== "string") {
+                throw new PrShepherdValidationError("append_journal.item must be a string");
+            }
+            if (operation.dryRun !== undefined && typeof operation.dryRun !== "boolean") {
+                throw new PrShepherdValidationError("append_journal.dryRun must be a boolean");
+            }
+            {
+                const validation = validateJournalItem(operation.item);
+                if (!validation.ok)
+                    throw new PrShepherdValidationError(validation.error);
+            }
+            return;
+        default:
+            throw new PrShepherdValidationError(`Unsupported apply operation: ${JSON.stringify(operation.type)}`);
+    }
+}
+function validateReviewMutations(operation) {
+    const ids = [
+        operation.resolveThreadIds,
+        operation.replyThreadIds,
+        operation.minimizeCommentIds,
+        operation.dismissReviewIds,
+    ];
+    if (!ids.some((value) => value !== undefined && value.length > 0)) {
+        throw new PrShepherdValidationError("review_mutations requires at least one mutation ID");
+    }
+    for (const value of ids)
+        validateStringArray(value, "review mutation IDs");
+    const needsMessage = (operation.replyThreadIds?.length ?? 0) > 0 || (operation.dismissReviewIds?.length ?? 0) > 0;
+    if (needsMessage && (!operation.message || operation.message.trim() === "")) {
+        throw new PrShepherdValidationError("review_mutations.message is required for replies or review dismissals");
+    }
+    if (operation.message !== undefined && typeof operation.message !== "string") {
+        throw new PrShepherdValidationError("review_mutations.message must be a string");
+    }
+    if (operation.requireSha !== undefined && !/^[0-9a-f]{40}$/.test(operation.requireSha)) {
+        throw new PrShepherdValidationError("review_mutations.requireSha must be a full 40-character lowercase hex SHA");
+    }
+}
+function validateMarkFilesViewed(operation) {
+    validateStringArray(operation.files, "mark_files_viewed.files");
+    validateStringArray(operation.matchPatterns, "mark_files_viewed.matchPatterns");
+    if (operation.tests !== undefined && typeof operation.tests !== "boolean") {
+        throw new PrShepherdValidationError("mark_files_viewed.tests must be a boolean");
+    }
+    if ((operation.files?.length ?? 0) === 0 &&
+        (operation.matchPatterns?.length ?? 0) === 0 &&
+        operation.tests !== true) {
+        throw new PrShepherdValidationError("mark_files_viewed requires files, matchPatterns, or tests: true");
+    }
+    for (const pattern of operation.matchPatterns ?? []) {
+        try {
+            new RegExp(pattern, "i");
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new PrShepherdValidationError(`Invalid mark_files_viewed match pattern ${JSON.stringify(pattern)}: ${message}`);
+        }
+    }
+}
+function validateSuggestionPatchInput(input) {
+    if (!input || typeof input.threadId !== "string" || input.threadId === "") {
+        throw new PrShepherdValidationError("buildSuggestionPatch.threadId is required");
+    }
+    if (typeof input.message !== "string" || input.message.trim() === "") {
+        throw new PrShepherdValidationError("buildSuggestionPatch.message is required and must be non-empty");
+    }
+    if (input.description !== undefined && typeof input.description !== "string") {
+        throw new PrShepherdValidationError("buildSuggestionPatch.description must be a string");
+    }
+    parsePrReference(input.pr);
+}
+function parsePrReference(pr) {
+    if (pr === undefined)
+        return {};
+    if (typeof pr === "number" && Number.isInteger(pr) && pr > 0)
+        return { number: pr };
+    if (typeof pr === "string") {
+        try {
+            const url = new URL(pr);
+            const parts = url.pathname.split("/").filter(Boolean);
+            if ((url.protocol === "https:" || url.protocol === "http:") &&
+                (url.hostname === "github.com" || url.hostname === "www.github.com") &&
+                parts.length === 4 &&
+                parts[2] === "pull" &&
+                /^[1-9][0-9]*$/.test(parts[3])) {
+                return { number: Number(parts[3]), repository: `${parts[0]}/${parts[1]}` };
+            }
+        }
+        catch {
+            // Construct the uniform public validation error below.
+        }
+    }
+    throw new PrShepherdValidationError("pr must be a positive number or a GitHub pull-request URL");
+}
+async function resolvePrReference(pr) {
+    const parsed = parsePrReference(pr);
+    if (parsed.repository !== undefined) {
+        const repo = await getRepoInfo();
+        const currentRepository = `${repo.owner}/${repo.name}`;
+        if (parsed.repository.toLowerCase() !== currentRepository.toLowerCase()) {
+            throw new PrShepherdValidationError(`PR URL repository ${parsed.repository} does not match the configured repository ${currentRepository}`);
+        }
+    }
+    return parsed.number;
+}
+function validateStringArray(value, label) {
+    if (value !== undefined &&
+        (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item === ""))) {
+        throw new PrShepherdValidationError(`${label} must be an array of non-empty strings`);
+    }
+}

package/bin/checks/classify.d.mts

@@ -0,0 +1,41 @@
+/**
+ * Classifies check runs into shepherd categories and filters out irrelevant ones.
+ *
+ * Rules:
+ *   1. Skip checks whose workflow event is NOT `pull_request` or `pull_request_target`.
+ *      Push-triggered, merge-queue, schedule, and workflow-dispatch runs are irrelevant
+ *      to PR readiness.
+ *   2. Drop checks with `conclusion == SKIPPED` or `conclusion == NEUTRAL` from the
+ *      pass/fail tally. Report them as "skipped" for transparency but don't block on them.
+ *   3. Reclassify `CANCELLED` checks as "superseded" (non-blocking) when a newer run of
+ *      the same workflow exists on the same commit — this is GitHub's concurrency-group
+ *      eviction behavior, not a real failure. GitHub branch protection itself resolves
+ *      required status checks by latest-run-per-name and merges past these; mirroring
+ *      that here keeps shepherd's verdict aligned with what GitHub will actually allow.
+ */
+import type { CheckRun, ClassifiedCheck } from "../types.mts";
+/**
+ * Classify a list of raw check runs into shepherd categories.
+ *
+ * @param checks Raw check runs from the batch query.
+ * @returns Classified checks. "filtered" items were excluded from the tally.
+ */
+export declare function classifyChecks(checks: CheckRun[]): ClassifiedCheck[];
+export interface CiVerdict {
+    /** True when all relevant (non-filtered, non-skipped, non-ignored) checks passed. */
+    allPassed: boolean;
+    /** True when at least one relevant (non-filtered, non-skipped, non-ignored) check exists. */
+    hasChecks: boolean;
+    /** True when at least one check is still running/queued. */
+    anyInProgress: boolean;
+    /** True when at least one check failed. */
+    anyFailing: boolean;
+    /** Names of checks that were filtered out (triggered by non-PR events). */
+    filteredNames: string[];
+    /** Names of checks suppressed by the user's ignoreChecks config. */
+    ignoredNames: string[];
+    /** Names of CANCELLED checks superseded by a newer run of the same workflow (concurrency-group eviction). */
+    supersededNames: string[];
+}
+/** Compute a high-level CI verdict from a list of classified checks. */
+export declare function getCiVerdict(classified: ClassifiedCheck[]): CiVerdict;

package/bin/checks/startup-failures.d.mts

@@ -0,0 +1,2 @@
+import type { CheckRun } from "../types.mts";
+export declare function mergeStartupFailureChecks(checks: CheckRun[], startupFailureChecks: CheckRun[]): CheckRun[];

package/bin/checks/superseded.d.mts

@@ -0,0 +1,21 @@
+/**
+ * Detects check runs that are `CANCELLED` because a newer run of the *same workflow*
+ * superseded them on the same commit (concurrency-group eviction), rather than a genuine
+ * cancellation. Split out of classify.mts to stay under the file-length cap.
+ */
+import type { CheckRun } from "../types.mts";
+/**
+ * Grouping key is `workflowId ?? workflowName` — the numeric GitHub Actions workflow database
+ * ID when available, falling back to the display name. Checks with neither a workflow identity
+ * nor a numeric `runId` (status contexts, startup-failure synthetics) never participate: they
+ * can neither be marked superseded nor count as evidence of a newer run.
+ *
+ * A check is superseded iff its own conclusion is `CANCELLED` and some other check sharing its
+ * workflow key has a strictly greater `runId`. The newest run for a workflow is therefore never
+ * superseded, even if it is itself cancelled — that case stays "failing" so the agent can decide
+ * whether to rerun it.
+ *
+ * @returns Indices into `checks` (not object identities, since check-run objects are not
+ *   deduplicated by reference elsewhere) that should be reclassified as "superseded".
+ */
+export declare function buildSupersededIndices(checks: CheckRun[]): Set<number>;

package/bin/checks/triage.d.mts

@@ -0,0 +1,4 @@
+import type { CheckRun, ClassifiedCheck, TriagedCheck } from "../types.mts";
+import type { RepoInfo } from "../github/client.mts";
+export declare function triageFailingChecks(failingChecks: ClassifiedCheck[], repo: RepoInfo): Promise<TriagedCheck[]>;
+export declare function fetchStartupFailureChecks(repo: RepoInfo, headSha: string, prNumber: number): Promise<CheckRun[]>;