pr-shepherd 0.25.3 → 0.26.0

package/bin/commands/poll.mjs

@@ -10,6 +10,37 @@ function writeTickProgress(tick, elapsedSeconds, sleepSeconds, verbose) {
         process.stderr.write(".");
     }
 }
+function waitSignature(result) {
+    const activity = result.activity ?? {
+        commitCount: 0,
+        reviewRoundCount: 0,
+        latestCommitCommittedAtUnix: null,
+        reviewItemsSinceLatestCommit: [],
+    };
+    return JSON.stringify({
+        status: result.status,
+        mergeStateStatus: result.mergeStateStatus,
+        reviewDecision: result.reviewDecision,
+        state: result.state,
+        active: (result.inProgressChecks ?? []).map((c) => [c.name, c.status, c.runId]),
+        commitCount: activity.commitCount,
+        latestCommitCommittedAtUnix: activity.latestCommitCommittedAtUnix,
+        reviewRoundCount: activity.reviewRoundCount,
+        reviewItemsSinceLatestCommit: activity.reviewItemsSinceLatestCommit.length,
+    });
+}
+function writeQuietStatus(tick, elapsedSeconds, sleepSeconds, result) {
+    const activeChecks = result.inProgressChecks ?? [];
+    const activeCheckText = activeChecks.map((c) => `${c.name} (${c.status})`).join(", ");
+    const active = activeChecks.length > 0 ? ` · active: ${activeCheckText}` : "";
+    const commitCount = result.activity?.commitCount ?? 0;
+    const reviewItems = result.activity?.reviewItemsSinceLatestCommit.length ?? 0;
+    const reviewRounds = result.activity?.reviewRoundCount ?? 0;
+    const commitSeg = commitCount > 0 ? ` · ${commitCount} commits` : "";
+    const reviewRoundSeg = reviewRounds > 0 ? ` · ${reviewRounds} review rounds` : "";
+    const reviewSeg = reviewItems > 0 ? ` · ${reviewItems} review items since latest commit` : "";
+    process.stderr.write(`[poll tick ${tick} / +${elapsedSeconds}s] WAIT ${result.status}/${result.mergeStateStatus}/${result.reviewDecision ?? "NO_REVIEW_DECISION"}${active}${commitSeg}${reviewRoundSeg}${reviewSeg} — sleeping ${sleepSeconds}s\n`);
+}
 const MAX_TIMER_MS = 2 ** 31 - 1;
 export async function runPoll(opts) {
     const { intervalSeconds, timeoutSeconds, ...iterateOpts } = opts;
@@ -19,7 +50,9 @@ export async function runPoll(opts) {
     let tick = 0;
     let lastResult;
     const verbose = opts.verbose === true;
+    const quietStatus = opts.quietStatus === true;
     let dotsPrinted = false;
+    let lastWaitSignature = null;
     while (true) {
         tick += 1;
         lastResult = await runIterate(iterateOpts);
@@ -30,9 +63,18 @@ export async function runPoll(opts) {
         if (remainingMs <= 0)
             break;
         const nextSleepMs = Math.min(intervalMs, remainingMs);
-        writeTickProgress(tick, Math.round(elapsedMs / 1000), Math.round(nextSleepMs / 1000), verbose);
-        if (!verbose)
-            dotsPrinted = true;
+        if (quietStatus) {
+            const signature = waitSignature(lastResult);
+            if (signature !== lastWaitSignature) {
+                writeQuietStatus(tick, Math.round(elapsedMs / 1000), Math.round(nextSleepMs / 1000), lastResult);
+            }
+            lastWaitSignature = signature;
+        }
+        else {
+            writeTickProgress(tick, Math.round(elapsedMs / 1000), Math.round(nextSleepMs / 1000), verbose);
+            if (!verbose)
+                dotsPrinted = true;
+        }
         await sleep(nextSleepMs);
     }
     if (dotsPrinted)

package/bin/commands/ready-mergeability.mjs

@@ -8,10 +8,10 @@ export async function refreshUnknownMergeability(prNumber, repo, batchData) {
     }
     return { batchData: await readMergeability(prNumber, repo, batchData), didRefresh: true };
 }
-export async function refreshReadyMergeability(prNumber, repo, batchData, verdict, unresolvedThreads, unresolvedComments) {
+export async function refreshReadyMergeability(prNumber, repo, batchData, verdict, unresolvedThreads, unresolvedComments, changesRequestedCount) {
     const refreshedBatchData = await readMergeability(prNumber, repo, batchData);
     const mergeStatus = deriveMergeStatus(refreshedBatchData);
-    const status = computeStatus(verdict, unresolvedThreads, unresolvedComments, mergeStatus, refreshedBatchData.changesRequestedReviews.length);
+    const status = computeStatus(verdict, unresolvedThreads, unresolvedComments, mergeStatus, changesRequestedCount);
     return { batchData: refreshedBatchData, mergeStatus, status };
 }
 export function isBlockedByFilteredCheck(mergeStatus, verdict) {

package/bin/commands/shepherd-journal.mjs

@@ -4,9 +4,9 @@ export const SHEPHERD_JOURNAL_APPEND_HINT = "If this section already exists, app
 export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Review the bodies shown under `## Review summaries (first look)` — you are seeing these for the first time. Eligible non-human IDs, when present, are already included in `--minimize-comment-ids` in the resolve or resolve-only command above; if any warrants a Shepherd Journal note, append it before running resolve.";
 export function buildShepherdJournalInstruction(prNumber, itemReferenceGuidance) {
     return [
-        `For any large decisions or rejections you made this iteration, add or update a \`${SHEPHERD_JOURNAL_SECTION}\` section in the PR description (\`gh pr edit ${prNumber} --body …\`) summarizing each decision.`,
+        `For any large decisions or rejections you made this iteration, run \`pr-shepherd journal ${prNumber} '- <decision>'\` to append an entry to the \`${SHEPHERD_JOURNAL_SECTION}\` section.`,
         itemReferenceGuidance,
-        SHEPHERD_JOURNAL_APPEND_HINT,
+        `The command is idempotent — re-running with the same text is a no-op.`,
     ].join(" ");
 }
 export const SHEPHERD_JOURNAL_REFERENCE_GUIDANCE_THREADS_AND_COMMENTS_IN_ITEM_HEADINGS = "For threads and comments, use the markdown link shown in its heading above; for reviews, reference the review ID.";

package/bin/config/load.mjs

@@ -51,6 +51,12 @@ function parseBotUsernames(value) {
     }
     return value;
 }
+function parseIgnoreChecks(value) {
+    if (!Array.isArray(value) || !value.every((item) => typeof item === "string")) {
+        throw new Error(`Invalid config: ignoreChecks must be an array of strings`);
+    }
+    return value;
+}
 const defaults = builtins;
 const configCache = new Map();
 export function loadConfig() {
@@ -67,6 +73,7 @@ export function loadConfig() {
         const parsed = (parse(raw) ?? {});
         const config = deepMerge(defaults, parsed);
         config.botUsernames = parseBotUsernames(config.botUsernames);
+        config.ignoreChecks = parseIgnoreChecks(config.ignoreChecks);
         config.iterate.minimizeComments = parseMinimizeCommentsPolicy(config.iterate.minimizeComments);
         configCache.set(cwd, config);
         return config;

package/bin/config.json

@@ -13,6 +13,7 @@
     "sonarqubecloud",
     "what-the-diff"
   ],
+  "ignoreChecks": [],
   "iterate": {
     "fixAttemptsPerThread": 3,
     "stallTimeoutMinutes": 60,

package/bin/github/activity.mjs

@@ -0,0 +1,57 @@
+import { parseCreatedAt } from "./batch-parser-helpers.mjs";
+function reviewActivityItems(reviews, latestCommitCommittedAtUnix, kind) {
+    return reviews
+        .filter((r) => (r.createdAtUnix ?? 0) > latestCommitCommittedAtUnix)
+        .filter((r) => r.body.trim() !== "")
+        .map((r) => ({
+        kind,
+        id: r.id,
+        author: r.author,
+        authorType: r.authorType,
+        body: r.body,
+        createdAtUnix: r.createdAtUnix ?? 0,
+    }));
+}
+export function buildPrActivitySummary(raw, comments, reviewThreads, reviewSummaries, changesRequestedReviews, approvedReviews) {
+    const latestCommitCommittedAtUnix = raw.commits.nodes[0]?.commit.committedDate
+        ? parseCreatedAt(raw.commits.nodes[0].commit.committedDate)
+        : null;
+    const reviewItemsSinceLatestCommit = latestCommitCommittedAtUnix === null
+        ? []
+        : [
+            ...comments
+                .filter((c) => c.createdAtUnix > latestCommitCommittedAtUnix)
+                .map((c) => ({
+                kind: "pr-comment",
+                id: c.id,
+                author: c.author,
+                authorType: c.authorType,
+                body: c.body,
+                url: c.url,
+                createdAtUnix: c.createdAtUnix,
+            })),
+            ...reviewThreads.flatMap((t) => (t.comments ?? [])
+                .filter((c) => c.createdAtUnix > latestCommitCommittedAtUnix)
+                .map((c) => ({
+                kind: "review-thread-comment",
+                id: c.id,
+                author: c.author,
+                authorType: c.authorType,
+                body: c.body,
+                url: c.url,
+                createdAtUnix: c.createdAtUnix,
+                threadId: t.id,
+                path: t.path,
+                line: t.line,
+            }))),
+            ...reviewActivityItems(reviewSummaries, latestCommitCommittedAtUnix, "review-summary"),
+            ...reviewActivityItems(changesRequestedReviews, latestCommitCommittedAtUnix, "changes-requested-review"),
+            ...reviewActivityItems(approvedReviews, latestCommitCommittedAtUnix, "approved-review"),
+        ].sort((a, b) => a.createdAtUnix - b.createdAtUnix);
+    return {
+        commitCount: raw.commits.totalCount ?? raw.commits.nodes.length,
+        reviewRoundCount: raw.allReviews?.totalCount ?? 0,
+        latestCommitCommittedAtUnix,
+        reviewItemsSinceLatestCommit,
+    };
+}

package/bin/github/batch-parser-helpers.mjs

@@ -22,6 +22,11 @@ export function extractCheckRunSummary(title, summary) {
         ?.trim();
     return firstLine || undefined;
 }
+export function latestApprovedLogins(latest) {
+    return new Set(latest
+        .filter((r) => r.login !== "unknown" && (r.state === "APPROVED" || r.state === "DISMISSED"))
+        .map((r) => r.login));
+}
 export function mapStatusContextState(state) {
     switch (state) {
         case "SUCCESS":

package/bin/github/batch-parsers.mjs

@@ -1,4 +1,15 @@
-import { mapAuthorType, parseCreatedAt, extractRunId, extractCheckRunSummary, mapStatusContextState, } from "./batch-parser-helpers.mjs";
+import { mapAuthorType, parseCreatedAt, extractRunId, extractCheckRunSummary, mapStatusContextState, latestApprovedLogins, } from "./batch-parser-helpers.mjs";
+import { buildPrActivitySummary } from "./activity.mjs";
+import { parseBranchProtection } from "./branch-protection.mjs";
+function parseReviewNode(r) {
+    return {
+        id: r.id,
+        author: r.author?.login ?? "unknown",
+        authorType: mapAuthorType(r.author?.__typename, r.author?.login),
+        body: r.body,
+        createdAtUnix: r.createdAt ? parseCreatedAt(r.createdAt) : 0,
+    };
+}
 export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes, rawReviewSummaryNodes, rawApprovedReviewNodes, rawCheckNodes) {
     const reviewRequests = (raw.reviewRequests?.nodes ?? []).flatMap((n) => {
         const login = n.requestedReviewer?.login ?? n.requestedReviewer?.name;
@@ -8,6 +19,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         login: n.author?.login ?? "unknown",
         state: n.state,
     }));
+    const crDone = latestApprovedLogins(latestReviews);
     const reviewThreads = rawThreadPages.map((t) => {
         const comment = t.comments.nodes[0];
         const comments = t.comments.nodes.map((c) => ({
@@ -18,7 +30,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
             authorType: mapAuthorType(c.author?.__typename, c.author?.login),
             body: c.body,
             url: c.url,
-            createdAtUnix: parseCreatedAt(c.createdAt),
+            createdAtUnix: c.createdAt ? parseCreatedAt(c.createdAt) : 0,
         }));
         return {
             id: t.id,
@@ -33,7 +45,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
             authorType: mapAuthorType(comment?.author?.__typename, comment?.author?.login),
             body: comment?.body ?? "",
             url: comment?.url ?? "",
-            createdAtUnix: comment ? parseCreatedAt(comment.createdAt) : 0,
+            createdAtUnix: comment?.createdAt ? parseCreatedAt(comment.createdAt) : 0,
             comments,
         };
     });
@@ -44,33 +56,19 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         authorType: mapAuthorType(c.author?.__typename, c.author?.login),
         body: c.body,
         url: c.url,
-        createdAtUnix: parseCreatedAt(c.createdAt),
-    }));
-    const changesRequestedReviews = rawReviewNodes.map((r) => ({
-        id: r.id,
-        author: r.author?.login ?? "unknown",
-        authorType: mapAuthorType(r.author?.__typename, r.author?.login),
-        body: r.body,
+        createdAtUnix: c.createdAt ? parseCreatedAt(c.createdAt) : 0,
     }));
+    const allChangesRequestedReviews = rawReviewNodes.map((r) => parseReviewNode(r));
+    const changesRequestedReviews = allChangesRequestedReviews.filter((r) => !crDone.has(r.author));
     const reviewSummaries = rawReviewSummaryNodes
         .filter((r) => !r.isMinimized && r.body.trim() !== "")
-        .map((r) => ({
-        id: r.id,
-        author: r.author?.login ?? "unknown",
-        authorType: mapAuthorType(r.author?.__typename, r.author?.login),
-        body: r.body,
-    }));
+        .map((r) => parseReviewNode(r));
     // APPROVED reviews often have empty bodies (clicking "Approve" without a comment), so
     // we keep them — only the isMinimized filter applies. Monitor/iterate uses these IDs
     // when the user opts in to minimizing approvals.
     const approvedReviews = rawApprovedReviewNodes
         .filter((r) => !r.isMinimized)
-        .map((r) => ({
-        id: r.id,
-        author: r.author?.login ?? "unknown",
-        authorType: mapAuthorType(r.author?.__typename, r.author?.login),
-        body: r.body,
-    }));
+        .map((r) => parseReviewNode(r));
     const checks = rawCheckNodes.flatMap((node) => {
         if (node.__typename === "CheckRun") {
             const event = node.checkSuite?.workflowRun?.event ?? null;
@@ -122,16 +120,6 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         }
         return [];
     });
-    const rawProtection = raw.baseRef?.branchProtectionRule ?? null;
-    const branchProtection = rawProtection
-        ? {
-            requiresApprovingReviews: rawProtection.requiresApprovingReviews,
-            requiredApprovingReviewCount: rawProtection.requiredApprovingReviewCount,
-            requiresConversationResolution: rawProtection.requiresConversationResolution,
-            requiresStatusChecks: rawProtection.requiresStatusChecks,
-            requiredStatusCheckContexts: rawProtection.requiredStatusCheckContexts ?? [],
-        }
-        : null;
     return {
         nodeId: raw.id,
         number: raw.number,
@@ -152,6 +140,7 @@ export function parseRawPr(raw, rawThreadPages, rawCommentNodes, rawReviewNodes,
         reviewSummaries,
         approvedReviews,
         checks,
-        branchProtection,
+        branchProtection: parseBranchProtection(raw),
+        activity: buildPrActivitySummary(raw, comments, reviewThreads, reviewSummaries, allChangesRequestedReviews, approvedReviews),
     };
 }

package/bin/github/branch-protection.mjs

@@ -0,0 +1,12 @@
+export function parseBranchProtection(raw) {
+    const rule = raw.baseRef?.branchProtectionRule ?? null;
+    return rule
+        ? {
+            requiresApprovingReviews: rule.requiresApprovingReviews,
+            requiredApprovingReviewCount: rule.requiredApprovingReviewCount,
+            requiresConversationResolution: rule.requiresConversationResolution,
+            requiresStatusChecks: rule.requiresStatusChecks,
+            requiredStatusCheckContexts: rule.requiredStatusCheckContexts ?? [],
+        }
+        : null;
+}

package/bin/github/client.mjs

@@ -8,7 +8,7 @@
 import { execFile as execFileCb } from "node:child_process";
 import { promisify } from "node:util";
 import { graphql as httpGraphql, rest } from "./http.mjs";
-import { PR_NUMBER_BY_BRANCH_QUERY, GET_PR_HEAD_SHA_QUERY } from "./queries.mjs";
+import { PR_NUMBER_BY_BRANCH_QUERY, GET_PR_HEAD_SHA_QUERY, GET_PR_BODY_QUERY, UPDATE_PR_BODY_MUTATION, } from "./queries.mjs";
 const execFile = promisify(execFileCb);
 // ---------------------------------------------------------------------------
 // GraphQL — thin re-exports so callers don't need to import http.mts directly
@@ -63,6 +63,22 @@ export async function getPrHeadSha(pr, owner, name) {
     }
     return sha;
 }
+/** Fetches the node ID and body text for a PR. GitHub returns null body for empty bodies — coerced to "". */
+export async function getPullRequestBody(pr, owner, name) {
+    const result = await httpGraphql(GET_PR_BODY_QUERY, { owner, repo: name, pr });
+    const pullRequest = result.data.repository?.pullRequest;
+    if (!pullRequest) {
+        const detail = !result.data.repository
+            ? "repository not found or access denied"
+            : "PR not found or access denied";
+        throw new Error(`Could not fetch body for ${owner}/${name} PR #${pr}: ${detail}`);
+    }
+    return { nodeId: pullRequest.id, body: pullRequest.body ?? "" };
+}
+/** Overwrites the PR body. */
+export async function updatePullRequestBody(pullRequestId, body) {
+    await httpGraphql(UPDATE_PR_BODY_MUTATION, { pullRequestId, body });
+}
 /**
  * Fetches `mergeable` and `mergeStateStatus` via the REST API.
  *

package/bin/github/gql/batch-pr.gql

@@ -49,6 +49,9 @@ query BatchPr(
           }
         }
       }
+      # Not paginated — capped at 100 distinct reviewers; PRs with more are not plausible
+      # in practice. Used to derive which CHANGES_REQUESTED rows are superseded by a later
+      # APPROVED/DISMISSED review from the same author.
       latestReviews(last: 100) {
         nodes {
           author {
@@ -128,6 +131,7 @@ query BatchPr(
             login
           }
           body
+          createdAt
         }
       }
       reviewSummaries: reviews(states: COMMENTED, last: 50, before: $reviewSummariesCursor) {
@@ -143,8 +147,12 @@ query BatchPr(
             login
           }
           body
+          createdAt
         }
       }
+      allReviews: reviews(last: 1) {
+        totalCount
+      }
       approvedReviews: reviews(states: APPROVED, last: 50, before: $approvedReviewsCursor) {
         pageInfo {
           hasPreviousPage
@@ -158,12 +166,15 @@ query BatchPr(
             login
           }
           body
+          createdAt
         }
       }
       commits(last: 1) {
+        totalCount
         nodes {
           commit {
             oid
+            committedDate
             statusCheckRollup {
               contexts(first: 100, after: $checksCursor) {
                 pageInfo {

package/bin/github/gql/get-pr-body.gql

@@ -0,0 +1,8 @@
+query GetPrBody($owner: String!, $repo: String!, $pr: Int!) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $pr) {
+      id
+      body
+    }
+  }
+}

package/bin/github/gql/update-pr-body.gql

@@ -0,0 +1,7 @@
+mutation UpdatePrBody($pullRequestId: ID!, $body: String!) {
+  updatePullRequest(input: { pullRequestId: $pullRequestId, body: $body }) {
+    pullRequest {
+      id
+    }
+  }
+}

package/bin/github/queries.mjs

@@ -21,3 +21,7 @@ export const GET_PR_HEAD_SHA_QUERY = gql("get-pr-head-sha.gql");
 export const PR_NUMBER_BY_BRANCH_QUERY = gql("pr-number-by-branch.gql");
 /** Convert a draft PR to ready for review. */
 export const MARK_PR_READY_MUTATION = gql("mark-pr-ready.gql");
+/** Fetch the PR body and node ID. */
+export const GET_PR_BODY_QUERY = gql("get-pr-body.gql");
+/** Update the PR body. */
+export const UPDATE_PR_BODY_MUTATION = gql("update-pr-body.gql");

package/bin/types/activity.mjs

@@ -0,0 +1 @@
+export {};

package/bin/types/iterate.mjs

@@ -1,2 +1 @@
-// Iterate command types.
 export {};

package/bin/types.mjs

@@ -1,5 +1,6 @@
 /** Shared type definitions for the shepherd CLI. */
 export * from "./types/github.mjs";
+export * from "./types/activity.mjs";
 export * from "./types/review-thread.mjs";
 export * from "./types/agent-thread.mjs";
 export * from "./types/check-annotations.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.25.3",
+  "version": "0.26.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "license": "MIT",
   "author": "Jonathan Ong",
@@ -10,6 +10,7 @@
   },
   "files": [
     "bin/**",
+    "src/classify/types.mts",
     "plugins/**",
     "plugins/**/.codex-plugin/**",
     ".claude-plugin/**",
@@ -22,14 +23,23 @@
     "node": ">=22.0.0"
   },
   "dependencies": {
+    "picomatch": "^4.0.4",
+    "tsx": "^4.22.4",
     "yaml": "^2.7.0"
   },
+  "exports": {
+    "./classify": {
+      "types": "./src/classify/types.mts",
+      "default": "./bin/classify/types.mjs"
+    }
+  },
   "devDependencies": {
     "@types/node": "^25.6.0",
+    "@types/picomatch": "^4.0.3",
     "@vitest/coverage-v8": "^4.1.4",
     "husky": "^9.1.7",
     "knip": "^6.14.1",
-    "oxfmt": "^0.50.0",
+    "oxfmt": "^0.51.0",
     "oxlint": "^1.60.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.4"

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.25.3",
+  "version": "0.26.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/plugins/pr-shepherd/skills/pr-shepherd/SKILL.md

@@ -14,30 +14,15 @@ Poll dispatcher for iterating a PR to completion.
 
 ## Steps
 
-1. **Resolve PR number:**
-   - If `$ARGUMENTS` contains a PR number, use it.
-   - If `$ARGUMENTS` contains a GitHub PR URL, extract the number.
-   - Otherwise, infer: `gh pr view --json number --jq .number`
-   - If no PR found, report an error and stop.
+1. **Resolve the PR number** (`$N`): use the number or URL in `$ARGUMENTS`; otherwise infer it with `gh pr view --json number --jq .number`. If none is found, report an error and stop.
 
-2. **Run `pr-shepherd`:**
+2. **Define the poll command once:** `pr-shepherd $N --interval 45s --timeout 4m`. Do not forward `$ARGUMENTS` as extra flags. Run `pr-shepherd --help` to inspect supported options.
 
-   ```bash
-   pr-shepherd <N> --interval 45s --timeout 4m
-   ```
+3. **Loop:** Run the poll, print its full output, and follow its `## Instructions` section exactly. Then run the poll again. Repeat until the CLI emits `[CANCEL]` or `[ESCALATE]`, unless the human directs you to stop. Every other action (`[WAIT]`, `[MARK_READY]`, `[FIX_CODE]`) is non-terminal: do its instructions, then poll again. The poll already bounds each wait via `--interval`/`--timeout`; do not add manual `sleep`s between ticks.
 
-   Do not pass `$ARGUMENTS` through as extra flags. If you need to inspect supported options, run `pr-shepherd --help`.
+4. **Nonzero exit codes:** Treat a nonzero poll exit as PR state only when the output contains a matching `# PR #$N [ACTION]` heading. Exit `1` can also mean a command or validation failure; if there is no `[ACTION]` heading, surface the error and stop instead of looping.
 
-   Print the full output. Follow the `## Instructions` section exactly for the current action.
-
-3. **Persistence:** Continuously call `pr-shepherd <N> --interval 45s --timeout 4m` until the CLI returns `[CANCEL]` or `[ESCALATE]`, unless the human directs you to stop. Every other action is non-terminal:
-   - `[WAIT]`: call `pr-shepherd <N> --interval 45s --timeout 4m` again.
-   - `[MARK_READY]`: call `pr-shepherd <N> --interval 45s --timeout 4m` again.
-   - `[FIX_CODE]`: follow the output's `## Instructions`, then call `pr-shepherd <N> --interval 45s --timeout 4m` again.
-
-   Treat a nonzero poll exit code as PR state only when the output contains a matching `# PR #N [ACTION]` heading. Exit code `1` can also mean a command or validation failure; if there is no `[FIX_CODE]` heading, surface the error and stop instead of looping.
-
-4. **Stop conditions (terminal states):**
-   - Stop when the CLI emits `[CANCEL]` (ready-delay completed, or PR merged/closed).
-   - Stop when the CLI emits `[ESCALATE]`, including `stall-timeout` for repeated unchanged CI failures or CI that never starts.
+5. **Terminal states (stop):**
+   - `[CANCEL]` — ready-delay completed, or PR merged/closed.
+   - `[ESCALATE]` — needs human direction (includes `stall-timeout` for repeated unchanged CI failures or CI that never starts).
    - **Do NOT merge the pull request** unless the human has explicitly requested or allowed it.

package/src/classify/types.mts

@@ -0,0 +1,48 @@
+export type ClassifyItemKind =
+  | "review-thread"
+  | "pr-comment"
+  | "review-summary"
+  | "changes-requested";
+
+export interface ClassifyItemBase {
+  readonly kind: ClassifyItemKind;
+  readonly id: string;
+  readonly author: string;
+  readonly authorType: "User" | "Bot" | "Unknown";
+  readonly body: string;
+  readonly url?: string;
+}
+
+export interface ClassifyReviewThread extends ClassifyItemBase {
+  readonly kind: "review-thread";
+  readonly path?: string | null;
+}
+
+export interface ClassifyPrComment extends ClassifyItemBase {
+  readonly kind: "pr-comment";
+}
+
+export interface ClassifyReviewSummary extends ClassifyItemBase {
+  readonly kind: "review-summary";
+}
+
+export interface ClassifyChangesRequested extends ClassifyItemBase {
+  readonly kind: "changes-requested";
+}
+
+export type ClassifyItem =
+  | ClassifyReviewThread
+  | ClassifyPrComment
+  | ClassifyReviewSummary
+  | ClassifyChangesRequested;
+
+export interface ClassifyAction {
+  /** When true, routes the item's ID to the appropriate resolve/minimize GitHub mutation. Not supported for changes-requested reviews. */
+  readonly autoResolve?: boolean;
+  /** When true, hides the item from agent output (seen marker is still written). */
+  readonly suppress?: boolean;
+  /** Optional note recorded to the debug log when this rule fires. */
+  readonly reason?: string;
+}
+
+export type ClassifyRule = (item: ClassifyItem) => ClassifyAction | null | undefined;