pr-shepherd 0.48.0 → 0.49.0

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

@@ -0,0 +1,82 @@
+import type { ApiUsage, GraphqlQuotaWarning } from "./api-usage.mts";
+import type { MergeableState, MergeStateStatus, ReviewDecision } from "./github.mts";
+import type { ShepherdAction } from "./iterate.mts";
+export interface PollSummaryChecks {
+    passing?: number;
+    failing?: number;
+    inProgress?: number;
+    skipped?: number;
+    filtered?: number;
+    ignored?: number;
+    superseded?: number;
+    incomplete?: true;
+}
+export interface PollSummaryReview {
+    comments?: number;
+    reviews?: number;
+    threads?: number;
+    actionable?: number;
+    incomplete?: true;
+}
+interface PollSummaryStack {
+    number: number;
+    size: number;
+    position: number;
+    baseRefName: string;
+}
+export interface PollSummaryItem {
+    pr: number;
+    repo: string;
+    title: string;
+    url: string;
+    /** Conservative routing hint; the selected one-PR poll makes the authoritative decision. */
+    action: ShepherdAction;
+    reasons: string[];
+    state: "OPEN" | "CLOSED" | "MERGED" | "UNKNOWN";
+    mergeable: MergeableState;
+    mergeStateStatus: MergeStateStatus;
+    reviewDecision?: ReviewDecision;
+    headRefName: string;
+    headRefOid: string;
+    baseRefName: string;
+    isDraft?: true;
+    isInMergeQueue?: true;
+    blockingReviewerInProgress?: true;
+    remainingSeconds?: number;
+    checks?: PollSummaryChecks;
+    review?: PollSummaryReview;
+    stack?: PollSummaryStack;
+    pollCommand?: string;
+}
+export type PollSummarySelection = {
+    kind: "prs";
+    requested: number[];
+} | {
+    kind: "stack";
+    anchor: number;
+    stackNumber: number;
+    stackSize: number;
+};
+export interface PollSummaryResult {
+    mode: "summary";
+    repo: string;
+    selection: PollSummarySelection;
+    reason: "actionable" | "all_terminal" | "waiting" | "timeout";
+    prs: PollSummaryItem[];
+    apiUsage?: ApiUsage;
+    quotaWarning?: GraphqlQuotaWarning;
+}
+export interface PollSummaryCommandOptions {
+    prNumbers?: number[];
+    stackPrNumber?: number;
+    targetRepository?: {
+        owner: string;
+        name: string;
+    };
+    merge?: boolean;
+    readyDelaySeconds?: number;
+    stallTimeoutSeconds?: number;
+    noAutoMarkReady?: boolean;
+    noAutoCancelActionable?: boolean;
+}
+export {};

package/bin/types/poll-summary.mjs

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

package/bin/types.d.mts

@@ -13,3 +13,4 @@ export * from "./types/merge-action.mts";
 export * from "./types/escalate.mts";
 export * from "./types/merge-queue.mts";
 export * from "./types/api-usage.mts";
+export * from "./types/poll-summary.mts";

package/bin/types.mjs

@@ -13,3 +13,4 @@ export * from "./types/merge-action.mjs";
 export * from "./types/escalate.mjs";
 export * from "./types/merge-queue.mjs";
 export * from "./types/api-usage.mjs";
+export * from "./types/poll-summary.mjs";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.48.0",
+  "version": "0.49.0",
   "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.48.0",
+  "version": "0.49.0",
   "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.48.0", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.49.0", "pr-shepherd-mcp"]
     }
   }
 }

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

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

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

@@ -18,9 +18,9 @@ If the requested PR does not exist yet, review and commit the in-scope changes,
 
 ## Arguments: $ARGUMENTS
 
-1. Parse an optional PR number, repository-qualified `owner/repo#N`, or GitHub PR URL and an optional `--merge` flag from `$ARGUMENTS`; 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. 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.
 
-2. For the CLI, convert supplied `owner/repo#N` to `https://github.com/owner/repo/pull/N`; otherwise pass the supplied URL or bare number unchanged, then run the canonical poll command `pr-shepherd [PR] --until-terminal`, omitting `[PR]` when none was supplied and appending `--merge` when requested. This command keeps ordinary `[WAIT]` and `[MARK_READY]` ticks inside the same invocation; it returns for agent-facing work (including an emitted `[MERGE]` command, which is non-terminal and must run before the next invocation), a quota warning, `[CANCEL]`, or `[ESCALATE]`. 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 obtain a repository-qualified reference: use a supplied GitHub PR URL or `owner/repo#N` unchanged; for a bare number, run `gh pr view <number> --json url --jq .url`; when omitted, run `gh pr view --json url --jq .url`. If that does not produce one qualified PR reference, stop and report that MCP cannot safely determine the PR. Otherwise call `iterate` with that qualified reference, plus `merge: true` when `--merge` was supplied, and print its full result.
+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 when any row needs work or all rows are terminal. It also returns for a quota warning or an emitted `[MERGE]` command, which is non-terminal and must run before the next invocation. 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` was supplied, 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.