pr-shepherd 0.41.0 → 0.43.0

package/bin/types/report.d.mts

@@ -3,6 +3,7 @@ import type { ClassifiedCheck, TriagedCheck } from "./check-classification.mts";
 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 FirstLookThread extends ReviewThread {
     firstLookStatus: "outdated" | "resolved" | "minimized";
     autoResolved?: boolean;
@@ -20,6 +21,8 @@ export interface ShepherdReport {
     pr: number;
     /** GitHub node ID of the PR — used for mutations (e.g. markPullRequestReadyForReview). */
     nodeId: string;
+    /** GitHub PR head OID from the same batch used to decide the action. */
+    headSha?: string;
     repo: string;
     status: ShepherdStatus;
     /** PR base branch from the GraphQL batch. */
@@ -71,6 +74,7 @@ export interface ShepherdReport {
     /** 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;
     activity?: PrActivitySummary;
+    mergeQueue?: MergeQueueReport;
 }
 export interface ResolveOptions {
     resolveThreadIds?: string[];
@@ -125,6 +129,8 @@ export interface AgentCheck {
     logExcerpt?: string;
     annotations?: CheckAnnotation[];
     annotationOnly?: true;
+    scope?: "merge_group";
+    commitOid?: string;
 }
 /**
  * A single CI check that is relevant to PR readiness — triggered by a PR event
@@ -149,25 +155,8 @@ export interface RelevantCheck {
     logExcerpt?: string;
     /** Marker-gated inline annotations from this check. */
     annotations?: CheckAnnotation[];
-}
-export interface CommitSuggestionResult {
-    pr: number;
-    repo: string;
-    threadId: string;
-    path: string;
-    startLine: number;
-    endLine: number;
-    author: string;
-    /** The unified diff generated for this suggestion. */
-    patch: string;
-    /** The commit subject line (user-supplied --message). */
-    commitMessage: string;
-    /** The commit body (optional description + Co-authored-by trailer). */
-    commitBody: string;
-    /** Files the agent should stage before committing. */
-    filesToStage: string[];
-    /** Numbered steps the agent must execute to apply, commit, resolve, and push. */
-    postActionInstructions: string[];
+    scope?: "merge_group";
+    commitOid?: string;
 }
 export interface GlobalOptions {
     prNumber?: number;

package/bin/types/suggestion-patch.d.mts

@@ -0,0 +1,30 @@
+export interface SuggestionPatchResult {
+    threadId: string;
+    path: string;
+    startLine: number;
+    endLine: number;
+    author: string;
+    /** The unified diff generated for this suggestion. */
+    patch: string;
+    /** The commit subject line supplied by the caller. */
+    commitMessage: string;
+    /** The optional description plus Co-authored-by trailer. */
+    commitBody: string;
+    /** Files the agent should stage before committing. */
+    filesToStage: string[];
+}
+export interface BuildSuggestionPatchesResult {
+    pr: number;
+    repo: string;
+    /** Suggestion patches in caller-supplied application order. */
+    patches: SuggestionPatchResult[];
+    /** Steps for applying and committing every patch, then pushing once. */
+    postActionInstructions: string[];
+}
+/** Compatibility result for the singular suggestion-patch adapter. */
+export interface CommitSuggestionResult extends SuggestionPatchResult {
+    pr: number;
+    repo: string;
+    /** Numbered steps for the deprecated singular workflow. */
+    postActionInstructions: string[];
+}

package/bin/types/suggestion-patch.mjs

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

package/bin/types.d.mts

@@ -6,5 +6,9 @@ export * from "./types/review-thread.mts";
 export * from "./types/agent-thread.mts";
 export * from "./types/check-annotations.mts";
 export * from "./types/report.mts";
+export * from "./types/suggestion-patch.mts";
 export * from "./types/iterate.mts";
 export * from "./types/merge-requirements.mts";
+export * from "./types/merge-action.mts";
+export * from "./types/escalate.mts";
+export * from "./types/merge-queue.mts";

package/bin/types.mjs

@@ -6,5 +6,9 @@ export * from "./types/review-thread.mjs";
 export * from "./types/agent-thread.mjs";
 export * from "./types/check-annotations.mjs";
 export * from "./types/report.mjs";
+export * from "./types/suggestion-patch.mjs";
 export * from "./types/iterate.mjs";
 export * from "./types/merge-requirements.mjs";
+export * from "./types/merge-action.mjs";
+export * from "./types/escalate.mjs";
+export * from "./types/merge-queue.mjs";

package/bin/util/markdown.d.mts

@@ -1 +1,3 @@
 export declare function joinSections(sections: (string | null | undefined)[]): string;
+/** Wrap arbitrary text in a CommonMark code span without colliding with embedded backticks. */
+export declare function inlineCode(value: string): string;

package/bin/util/markdown.mjs

@@ -5,3 +5,10 @@ export function joinSections(sections) {
         .filter((s) => s !== "")
         .join("\n\n");
 }
+/** Wrap arbitrary text in a CommonMark code span without colliding with embedded backticks. */
+export function inlineCode(value) {
+    const longestRun = Math.max(0, ...Array.from(value.matchAll(/`+/g), (match) => match[0].length));
+    const delimiter = "`".repeat(longestRun + 1);
+    const padding = value.startsWith("`") || value.endsWith("`") ? " " : "";
+    return `${delimiter}${padding}${value}${padding}${delimiter}`;
+}

package/package.json

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

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

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

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

@@ -2,7 +2,7 @@
 name: pr-shepherd
 description: 'Iterate a GitHub pull request with pr-shepherd (MCP or CLI). Use for requests like "use pr-shepherd", "iterate PR #123", or "run pr-shepherd until this PR is ready".'
 user-invocable: true
-argument-hint: "[PR number or URL]"
+argument-hint: "[PR number or URL] [--merge]"
 allowed-tools: ["MCP", "Bash", "Read", "Grep", "Glob", "Edit", "Write"]
 ---
 
@@ -12,11 +12,11 @@ Thin dispatcher for iterating a PR. Poll with the CLI; use MCP `iterate` only wh
 
 ## Arguments: $ARGUMENTS
 
-1. Parse an optional PR number, repository-qualified `owner/repo#N`, or GitHub PR URL from `$ARGUMENTS`; otherwise let pr-shepherd infer the current branch PR.
+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.
 
-2. Before passing a supplied GitHub PR URL or `owner/repo#N` to the CLI, run `gh repo view --json nameWithOwner --jq .nameWithOwner` and verify that repository matches the reference case-insensitively. Stop on a mismatch or failed lookup; the CLI does not validate the URL repository. Convert a verified `owner/repo#N` to `https://github.com/owner/repo/pull/N`, then run the poll command `pr-shepherd` with the optional PR argument and print its full result. 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 and print its full result.
+2. Before passing a supplied GitHub PR URL or `owner/repo#N` to the CLI, run `gh repo view --json nameWithOwner --jq .nameWithOwner` and verify that repository matches the reference case-insensitively. Stop on a mismatch or failed lookup; the CLI does not validate the URL repository. Convert a verified `owner/repo#N` to `https://github.com/owner/repo/pull/N`, then run the poll command `pr-shepherd` with the optional PR argument and forward `--merge` when supplied; print its full result. 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.
 
-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_patch` 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.
 
 4. After completing the returned instructions, repeat step 2 unless the action is `[CANCEL]` or `[ESCALATE]`, the instructions require a human handoff, or the human directs you to stop.
 
@@ -27,11 +27,11 @@ mechanics every tick. Apply the referenced playbook in full whenever a step poin
 
 ### Suggestion patches
 
-- The CLI only builds the patch. Apply it, stage the listed file, and follow the returned commit instructions.
-- If the command refuses because the suggestion is unsafe (an unsafe anchored range or nested/unbalanced suggestion fences), skip patch application and edit the file manually. Do not retry the command.
-- For any other refusal, follow the CLI error's stated recovery action; do not manually edit the suggestion.
-- If the patch does not apply for any other reason, edit the file manually instead. Do not retry the command.
-- After source drift prevents a generated suggestion patch from applying, replace the heading's exact `path:startLine-endLine` range with the `Replaces lines …` block verbatim. An empty replacement deletes the range. One blank line replaces it with one blank line.
+- Run one plural `build-suggestion-patches` command with a repeated `--thread-id … --message … [--description …]` group for every marked thread in displayed order.
+- The CLI only builds patches. Apply, stage, and commit the returned patches in order, then push once.
+- The command builds from the fetched PR head and accepts a clean local descendant only when the complete ordered patch stream passes `git apply --check`.
+- If the command refuses because a suggestion is unsafe or no longer applies, inspect the current source, the displayed replacement block, and reviewer intent before editing manually. Do not apply a stale numeric range blindly or retry unchanged input.
+- A returned patch was checked against the then-current worktree. If it later fails, re-inspect the worktree because it changed after validation.
 - Keep human-authored thread IDs in `apply review:` so Shepherd replies instead of resolving them.
 
 ### CI failure triage
@@ -53,12 +53,13 @@ More specific rows win over the general "GitHub Actions failure" row — check c
 
 Applies to every `apply review:` / `resolve-only:` command the CLI prints. Covers only what stays safe if you run the printed command **unmodified** — `$HEAD_SHA`/`$DISMISS_MESSAGE` substitution and the self-reply exclusion rule are separate CLI-printed steps, not covered here, because the printed command is unsafe by default without them.
 
+- Run every generated `apply review:` / `resolve-only:` command even when no code change is warranted. The command records the agent's disposition of the included review items; skipping it leaves bot threads active and can eventually trigger `fix-thrash`.
 - Never add first-look-only or check-annotation IDs to `--reply-thread-ids`, `--resolve-thread-ids`, `--dismiss-review-ids`, or `--minimize-comment-ids` — those flags are pre-populated by the CLI.
 - Keep every existing `--dismiss-review-ids` ID the CLI already included. Each is a bot or non-human review that must be dismissed; omitting one leaves the PR in `CHANGES_REQUESTED`.
 
 ### Review-mutation routing
 
-For threads under `## Review threads to resolve`: human-authored IDs use `--reply-thread-ids` (Shepherd replies instead of resolving them); bot and non-human IDs use `--resolve-thread-ids`. Use the commands as generated — do not move an ID between flags.
+For threads under both `## Review threads` and `## Review threads to resolve`, evaluate every thread before running mutations. Keep bot and non-human IDs in `--resolve-thread-ids`, including when the feedback is advisory, already satisfied, or otherwise warrants no code change. Human-authored IDs use `--reply-thread-ids`; Shepherd replies instead of resolving them. Never move a human-authored ID to `--resolve-thread-ids`. Use the commands as generated — do not move an ID between flags.
 
 ### Shepherd Journal