pr-shepherd 0.54.1 → 0.55.1

package/bin/state/ci-retrigger.d.mts

@@ -0,0 +1,25 @@
+/**
+ * One close/reopen of a head that was missing required checks.
+ *
+ * `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/ci-retrigger.json`
+ * Reopening does not change the head SHA, so the next tick must not close the PR again.
+ */
+interface Retrigger {
+    headSha: string;
+    contexts: string[];
+}
+/** The stored head and context set, or undefined when no usable marker exists. */
+export declare function readCiRetrigger(key: {
+    owner: string;
+    repo: string;
+    pr: number;
+}): Promise<Retrigger | undefined>;
+/** Remember that this head was already closed and reopened for these contexts. */
+export declare function writeCiRetrigger(key: {
+    owner: string;
+    repo: string;
+    pr: number;
+}, record: Retrigger): Promise<void>;
+/** True when this head was already retriggered for the same required contexts. */
+export declare function sameCiRetrigger(record: Retrigger | undefined, headSha: string, contexts: readonly string[]): boolean;
+export {};

package/bin/state/ci-retrigger.mjs

@@ -0,0 +1,48 @@
+/**
+ * One close/reopen of a head that was missing required checks.
+ *
+ * `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/ci-retrigger.json`
+ * Reopening does not change the head SHA, so the next tick must not close the PR again.
+ */
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "./base.mjs";
+/** The stored head and context set, or undefined when no usable marker exists. */
+export async function readCiRetrigger(key) {
+    return readRetrigger(resolvePrStatePath(key, "ci-retrigger.json"));
+}
+/** Remember that this head was already closed and reopened for these contexts. */
+export async function writeCiRetrigger(key, record) {
+    const path = resolvePrStatePath(key, "ci-retrigger.json");
+    await mkdir(dirname(path), { recursive: true });
+    const next = {
+        headSha: record.headSha,
+        contexts: [...record.contexts].sort(),
+    };
+    await writeFile(path, JSON.stringify(next));
+}
+/** True when this head was already retriggered for the same required contexts. */
+export function sameCiRetrigger(record, headSha, contexts) {
+    if (!record || record.headSha !== headSha)
+        return false;
+    const stored = [...record.contexts].sort();
+    const current = [...contexts].sort();
+    return stored.length === current.length && stored.every((name, index) => name === current[index]);
+}
+async function readRetrigger(path) {
+    try {
+        const parsed = JSON.parse(await readFile(path, "utf8"));
+        if (parsed === null || typeof parsed !== "object")
+            return undefined;
+        const headSha = parsed.headSha;
+        const contexts = parsed.contexts;
+        if (typeof headSha !== "string" || !Array.isArray(contexts))
+            return undefined;
+        if (!contexts.every((name) => typeof name === "string"))
+            return undefined;
+        return { headSha, contexts };
+    }
+    catch {
+        return undefined;
+    }
+}

package/bin/types/escalate.d.mts

@@ -2,7 +2,7 @@ import type { AgentCheck, AgentComment, AgentThread } from "./report.mts";
 import type { ResolveCommand } from "./iterate.mts";
 import type { CheckStatus, Review } from "./github.mts";
 import type { MergeQueueRemovalStatus } from "./merge-requirements.mts";
-export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "stall-state-unavailable" | "check-follow-up-unavailable" | "authorization-required" | "merge-queue-removed";
+export type EscalateTrigger = "fix-thrash" | "base-branch-unknown" | "stall-timeout" | "required-checks-unreported" | "stall-state-unavailable" | "check-follow-up-unavailable" | "authorization-required" | "merge-queue-removed" | "merge-method-unavailable";
 export interface AgentStalledCheck {
     name: string;
     status: CheckStatus;

package/bin/types/github.d.mts

@@ -108,6 +108,8 @@ export interface Review {
     staleBotCr?: boolean;
     /** Commit OID the review was made against, when available from GraphQL. */
     commitOid?: string;
+    /** Review HTML URL, when the batch query selected it. */
+    url?: string;
     /** True when commitOid !== headRefOid AND all associated threads are resolved/outdated. Distinct from `staleBotCr` (time-based). Reviews with no threads are not marked stale. */
     staleReview?: boolean;
 }
@@ -139,10 +141,17 @@ export interface BatchPrData extends BatchPrMergeFields {
     mergeStateStatus: MergeStateStatus;
     reviewDecision: ReviewDecision;
     headRefOid: string;
+    /**
+     * Earliest pull_request check-suite time on the head commit. Omitted when
+     * that signal is unavailable; queue-removal freshness then uses committer time.
+     */
+    headPushedAtUnix?: number;
     headRefName: string;
     /** `"owner/name"` of the head repository; null when the fork has been deleted. */
     headRepoWithOwner: string | null;
     viewerAuthorization?: ViewerAuthorization;
+    /** GitHub `viewer.login` for the token that fetched this batch. */
+    viewerLogin?: string;
     baseRefName: string;
     /** Base commit GitHub recorded for this PR (`PullRequest.baseRefOid`), not the branch's live tip. */
     baseRefOid?: string;
@@ -164,6 +173,8 @@ export interface BatchPrData extends BatchPrMergeFields {
     removedMergeQueueChecks?: CheckRun[];
     removedMergeQueueChecksIncomplete?: true;
     branchProtection: BranchProtection | null;
+    /** Repository merge methods. Omitted when the batch did not select them. Empty when none are enabled. */
+    allowedMergeMethods?: import("../config/merge-method.mts").MergeMethod[];
     activity?: PrActivitySummary;
 }
 export {};

package/bin/types/iterate.d.mts

@@ -1,4 +1,4 @@
-import type { AgentThread, AgentComment, AgentCheck, GlobalOptions, RelevantCheck, ShepherdStatus, FirstLookThread, FirstLookComment } from "./report.mts";
+import type { AgentThread, AgentComment, AgentCheck, GlobalOptions, RelevantCheck, ShepherdStatus, FirstLookThread, FirstLookComment, RuleAutoResolveReport } from "./report.mts";
 import type { ActiveCheck, PrActivitySummary } from "./activity.mts";
 import type { BranchProtection, MergeStateStatus, Review, ReviewDecision, ReviewThread, ShepherdMergeStatus } from "./github.mts";
 import type { MergeRequirements, StackDraftHold } from "./merge-requirements.mts";
@@ -6,7 +6,7 @@ import type { EscalateDetails } from "./escalate.mts";
 import type { MergeCommandPlan } from "./merge-action.mts";
 import type { ProtectedRun } from "./protected-run.mts";
 import type { ApiUsage, GraphqlQuotaWarning } from "./api-usage.mts";
-export type ShepherdAction = "wait" | "fix_code" | "mark_ready" | "merge" | "cancel" | "escalate";
+export type ShepherdAction = "wait" | "ready" | "fix_code" | "mark_ready" | "merge" | "cancel" | "escalate";
 export interface IterateResultSummary {
     passing: number;
     skipped: number;
@@ -45,11 +45,19 @@ export interface IterateResultBase {
     inProgressChecks?: ActiveCheck[];
     ignoredNames?: string[];
     supersededNames?: string[];
+    /** Required merge-target contexts with no check run and no status context. Omitted when empty. */
+    unreportedRequiredChecks?: string[];
+    /** Commits on the stack trunk that the bottom open layer does not contain. Omitted when zero. */
+    trunkBehindBy?: number;
+    /** Commits on the PR base that this head does not contain. Omitted when zero. */
+    baseBehindBy?: number;
     activity?: PrActivitySummary;
     mergeQueue?: import("./merge-queue.mts").MergeQueueReport;
     apiUsage?: ApiUsage;
     quotaWarning?: GraphqlQuotaWarning;
     fingerprintReused?: true;
+    /** Classification-rule resolve/minimize applied during this fetch. Omitted when nothing happened. */
+    ruleAutoResolve?: RuleAutoResolveReport;
 }
 interface IterateResultWait extends IterateResultBase {
     action: "wait";
@@ -57,6 +65,11 @@ interface IterateResultWait extends IterateResultBase {
     deferredWork?: import("./merge-queue.mts").IterateDeferredWork;
     stackDraftHold?: StackDraftHold;
 }
+/** Clean PR whose ready-delay is still counting. `--until-terminal` returns this instead of sleeping. */
+interface IterateResultReady extends IterateResultBase {
+    action: "ready";
+    log: string;
+}
 export type CancelReason = "merged" | "closed" | "ready-delay-elapsed";
 interface IterateResultCancel extends IterateResultBase {
     action: "cancel";
@@ -134,7 +147,7 @@ interface IterateResultEscalate extends IterateResultBase {
     action: "escalate";
     escalate: EscalateDetails;
 }
-export type IterateResult = IterateResultWait | IterateResultCancel | IterateResultFixCode | IterateResultMarkReady | IterateResultMerge | IterateResultEscalate;
+export type IterateResult = IterateResultWait | IterateResultReady | IterateResultCancel | IterateResultFixCode | IterateResultMarkReady | IterateResultMerge | IterateResultEscalate;
 export interface IterateCommandOptions extends GlobalOptions {
     readyDelaySeconds?: number;
     noAutoMarkReady?: boolean;

package/bin/types/poll-summary.d.mts

@@ -11,6 +11,10 @@ export interface PollSummaryChecks {
     ignored?: number;
     superseded?: number;
     incomplete?: true;
+    /** Required contexts with no check run and no status context. Omitted when empty. */
+    unreportedRequired?: string[];
+    /** A relevant Actions workflow suite has not completed. */
+    actionsWorkflowInProgress?: true;
 }
 export interface PollSummaryReview {
     comments?: number;
@@ -39,6 +43,10 @@ export interface PollSummaryItem {
     repo: string;
     title: string;
     url: string;
+    /** GitHub author login, when the summary query returned one. */
+    authorLogin?: string;
+    /** Author login matches the authenticated viewer. */
+    owned?: true;
     /** Conservative routing hint; the selected one-PR poll makes the authoritative decision. */
     action: ShepherdAction;
     reasons: string[];
@@ -89,6 +97,11 @@ export interface PollSummaryResult {
     nextAction?: StackNextAction;
     /** Whether every open layer is independently ready and stack ancestry is linear. */
     stackMergeable?: boolean;
+    /**
+     * Repository merge methods for stack merge commands. Omitted from the lean
+     * stack overview. Empty when the repository enables none.
+     */
+    allowedMergeMethods?: import("../config/merge-method.mts").MergeMethod[];
     instructions?: string[];
     apiUsage?: ApiUsage;
     quotaWarning?: GraphqlQuotaWarning;

package/bin/types/report.d.mts

@@ -4,6 +4,21 @@ import type { AgentThreadComment } from "./agent-thread.mts";
 import type { CheckAnnotation } from "./check-annotations.mts";
 import type { PrActivitySummary } from "./activity.mts";
 import type { MergeQueueReport } from "./merge-queue.mts";
+export interface AutoMinimizedItem {
+    id: string;
+    url?: string;
+    kind: "pr-comment" | "review-summary";
+    ruleReason?: string;
+}
+export type AutoResolvedThread = ReviewThread & {
+    ruleReason?: string;
+};
+export interface RuleAutoResolveReport {
+    summary: string;
+    threads?: AutoResolvedThread[];
+    minimized?: AutoMinimizedItem[];
+    errors?: string[];
+}
 export interface FirstLookThread extends ReviewThread {
     firstLookStatus: "outdated" | "resolved" | "minimized";
     autoResolved?: boolean;
@@ -23,6 +38,8 @@ export interface ShepherdReport {
     nodeId: string;
     /** GitHub PR head OID from the same batch used to decide the action. */
     headSha?: string;
+    /** PR head branch name. Used to compare a native stack against its trunk. */
+    headRefName?: string;
     /** Internal. True when this report was reused from the fingerprint cache. */
     fingerprintReused?: true;
     repo: string;
@@ -54,8 +71,10 @@ export interface ShepherdReport {
         actionable: ReviewThread[];
         /** Unresolved threads that need a GitHub resolve mutation but do not require code edits. */
         resolutionOnly: ReviewThread[];
-        autoResolved: ReviewThread[];
+        autoResolved: AutoResolvedThread[];
         autoResolveErrors: string[];
+        /** Rule reasons for this fetch's auto-resolve errors. Omitted when empty. */
+        autoResolveErrorReasons?: string[];
         /** First-look items — outdated/resolved/minimized threads not yet seen by the agent. */
         firstLook: FirstLookThread[];
         /** Thread IDs matched by user classification rules with autoResolve:true — routed to resolveThreadIds. */
@@ -67,6 +86,8 @@ export interface ShepherdReport {
         minimizeIds?: string[];
         /** First-look items — minimized comments not yet seen by the agent. */
         firstLook: FirstLookComment[];
+        /** PR comments and review summaries minimized by a suppress+autoResolve rule this fetch. */
+        autoMinimized?: AutoMinimizedItem[];
     };
     changesRequestedReviews: Review[];
     /** COMMENTED reviews already seen — eligible for `--minimize-comment-ids` without re-rendering. */
@@ -81,8 +102,20 @@ export interface ShepherdReport {
     ruleAutoResolveReviewSummaryIds?: string[];
     /** Branch protection rule for the PR's base branch. Null when no rule exists or the base ref is unavailable. */
     branchProtection: import("./github.mts").BranchProtection | null;
+    /** Repository merge methods from the same batch. Omitted when that query did not select them. */
+    allowedMergeMethods?: import("../config/merge-method.mts").MergeMethod[];
     activity?: PrActivitySummary;
     mergeQueue?: MergeQueueReport;
+    /** Required merge-target contexts with no check run and no status context. Omitted when empty. */
+    unreportedRequiredChecks?: string[];
+    /** Commits on the stack trunk that the bottom open layer does not contain. Omitted when zero. */
+    trunkBehindBy?: number;
+    /** Commits on the PR base that this head does not contain. Omitted when zero. */
+    baseBehindBy?: number;
+    /** A relevant Actions workflow suite on the head has not completed. */
+    actionsWorkflowInProgress?: true;
+    /** Bottom open layer of this PR's native stack. Starts a trunk rebase. */
+    stackBottomPr?: number;
 }
 export interface ResolveOptions {
     resolveThreadIds?: string[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.54.1",
+  "version": "0.55.1",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

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

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

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

@@ -2,7 +2,7 @@
   "mcpServers": {
     "pr-shepherd": {
       "command": "npx",
-      "args": ["--yes", "--package", "pr-shepherd@0.54.1", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.55.1", "pr-shepherd-mcp"]
     }
   }
 }

package/plugins/pr-shepherd/.mcp.json

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.54.1", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.55.1", "pr-shepherd-mcp"]
   }
 }

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

@@ -18,13 +18,13 @@ If the requested PR does not exist yet, review and commit the in-scope changes,
 
 ## Arguments: $ARGUMENTS
 
-1. Parse optional PR numbers, repository-qualified `owner/repo#N` references, or GitHub PR URLs and an optional `--merge` flag from `$ARGUMENTS`; alternatively parse one `--stack PR` selector. A clear request to merge, land, or enqueue the selected PR or stack also opts into `--merge` without a literal flag; a request only to create or open a PR does not. When the user asks to shepherd or merge a native stack and supplies an anchor PR without a literal `--stack`, use that PR as the `--stack` selector. Otherwise let pr-shepherd infer the current branch PR. Reject any remaining argument. Follow the target repository's local `AGENTS.md` and `CLAUDE.md` standards while making changes.
+1. Parse optional PR numbers, repository-qualified `owner/repo#N` references, or GitHub PR URLs and an optional `--merge` flag from `$ARGUMENTS`; alternatively parse one `--stack PR` selector. A clear request to merge, land, or enqueue the selected PR or stack also opts into `--merge` without a literal flag; a request only to create or open a PR does not. When the user asks to shepherd or merge a native stack and supplies an anchor PR without a literal `--stack`, use that PR as the `--stack` selector. Otherwise let pr-shepherd infer the current branch PR. Reject any remaining argument. Follow the target repository's local `AGENTS.md` standards while making changes.
 
 2. For the CLI, convert supplied `owner/repo#N` references to `https://github.com/owner/repo/pull/N`; otherwise pass supplied URLs or bare numbers unchanged, then run `pr-shepherd [PR ...] --until-terminal`, or `pr-shepherd --stack PR --until-terminal` for a stack, omitting `[PR ...]` when none was supplied and appending `--merge` when requested. This command keeps ordinary `[WAIT]` and `[MARK_READY]` ticks inside the same invocation; aggregate selectors return their next stack action or terminal result. A qualified reference may name a fork or upstream repository: it is the GitHub target, while the current checkout continues to supply local git/config/rules context. Do not run `pr-shepherd iterate`. If the CLI is unavailable and the `iterate` MCP tool is available, first repository-qualify every supplied reference with its GitHub URL or `owner/repo#N`; resolve bare numbers through `gh pr view <number> --json url --jq .url`, and resolve an omitted target with `gh pr view --json url --jq .url`. If that does not produce the required qualified selector, stop and report that MCP cannot safely determine it. Otherwise call `iterate` with `pr`, `prs`, or `stack` as selected, plus `merge: true` when merge intent was requested, and print its full result.
 
-3. Print the full result and follow every returned `## Instructions` step exactly. For CLI output, run each printed mutation command when instructed. For MCP output, use MCP `apply` and `build_suggestion_patches` with the same qualified PR reference; do not run a shell `pr-shepherd apply` command.
+3. Print the full result and follow every returned `## Instructions` step exactly. For CLI output, run each printed mutation command when instructed. For MCP output, use MCP `apply` and `build_suggestion_patches` with the same qualified PR reference; do not run a shell `pr-shepherd apply` command. On a stack overview, run one-PR shepherd, mark-ready, and push steps only for rows marked `owned`. Leave every other author's layer listed and untouched. If every session belongs to someone else, report the overview and stop. If at least one owned layer needs a session, shepherd those, then rerun the same `--stack` command.
 
-4. After completing the returned instructions, immediately repeat step 2 with the same target and canonical options unless the action is `[CANCEL]` or `[ESCALATE]`, or the human directs you to stop. Preserve `--until-terminal` and any requested `--merge`; apply any polling-cadence adjustment printed by the CLI. Every other action is non-terminal: complete its instructions and rerun without asking whether to continue. `[FIX_CODE]` is always non-terminal, as is stack-level `[SHEPHERD]`; only `[ESCALATE]` hands work to a human. After a push or `rerun:`, do not wait for CI to finish first — you may pull check logs, but do not poll with `gh pr checks`, `gh pr watch`, `gh run watch`, or equivalent GitHub MCP check waiters.
+4. After completing the returned instructions, immediately repeat step 2 with the same target and canonical options unless the action is `[CANCEL]` or `[ESCALATE]`, or the human directs you to stop. A stack overview heading includes those same tokens when `nextAction` is `cancel` or `escalate`. On a stack overview, if no row marked `owned` needs a session, stop instead of rerunning. Preserve `--until-terminal` and any requested `--merge`; apply any polling-cadence adjustment printed by the CLI. Every other action is non-terminal: complete its instructions and rerun without asking whether to continue. `[FIX_CODE]` is always non-terminal, as is stack-level `[SHEPHERD]`; only `[ESCALATE]` hands work to a human. `[READY]` is also non-terminal: wait out its `remainingSeconds`, then rerun the same command. Do not start other work during that countdown. After a push or `rerun:`, do not wait for CI to finish first — you may pull check logs, but do not poll with `gh pr checks`, `gh pr watch`, `gh run watch`, or equivalent GitHub MCP check waiters.
 
 ## Playbooks
 

package/plugins/pr-shepherd/skills/reduce-pr-noise/references/classifiers.md

@@ -19,6 +19,6 @@ const rule: ClassifyRule = (item) => {
 export default rule;
 ```
 
-`suppress: true` removes a matched item from agent output. Add `autoResolve: true` only when the requested policy also calls for resolving its thread or minimizing its comment or review summary. It is unsupported for `changes-requested` reviews, whose dismissal needs a message. With both flags, `actions.autoMinimizeSuppressed: true` lets Shepherd perform the authorized mutation silently; when GitHub does not confirm capability, the item returns to normal first-look visibility. Matching rules combine their flags, so inspect existing rules before adding one.
+`suppress: true` removes a matched item from agent output. Add `autoResolve: true` only when the requested policy also calls for resolving its thread or minimizing its comment or review summary. It is unsupported for `changes-requested` reviews, whose dismissal needs a message. Optional `reason` is the note printed, reported, and journaled when the rule fires. With both flags, `actions.autoMinimizeSuppressed: true` (the default) lets Shepherd perform the authorized mutation, then print a `## Classification auto-resolve` line, record `threads.autoResolved` / `comments.autoMinimized`, and append one Shepherd Journal item for the token login. Failed IDs stay on the generated `apply review` command and the failure is listed under that line. Set `actions.autoMinimizeSuppressed: false` to keep the handoff without mutating, journaling, or printing the line. When GitHub does not confirm capability, the item returns to normal first-look visibility. Matching rules combine their flags and keep every non-empty reason, so inspect existing rules before adding one.
 
 Exercise the exported rule against the observed item and negative examples: a different author, kind, and substantive message from the same bot. Confirm only the intended item matches before enabling automatic resolution. After editing a rule, restart a persistent MCP server or long-running poll process; it caches loaded rule modules. A new CLI process loads the change. A classifier does not retroactively remove already displayed output.

package/src/classify/types.mts

@@ -53,7 +53,7 @@ export interface ClassifyAction {
   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. */
+  /** Note included in the auto-resolve report, tick line, and Shepherd Journal when this rule fires. */
   readonly reason?: string;
 }