pr-shepherd 0.54.1 → 0.55.0

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,18 @@ 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;
+    /** 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.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.54.1",
+  "version": "0.55.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.54.1", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.55.0", "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.0", "pr-shepherd-mcp"]
   }
 }

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

@@ -22,9 +22,9 @@ If the requested PR does not exist yet, review and commit the in-scope 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;
 }