pr-shepherd 0.56.5 → 0.56.6

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pr-shepherd",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
-  "version": "0.56.5",
+  "version": "0.56.6",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/bin/commands/iterate/fix-code.mjs

@@ -301,16 +301,20 @@ export async function handleFixCode(ctx) {
             baseRefOid: report.baseRefOid,
         })
         : [];
-    // Only an upper layer can be dirty against trunk while already containing its parent.
-    const trunkConflict = hasConflicts && stack && headRef && baseLookup.branch !== stack.baseRefName
-        ? await lookupUpperLayerTrunkConflict({
-            owner: repoOwner,
-            name: repoName,
-            pr: prNumber,
-            headRef,
-            trunk: stack.baseRefName,
-        })
-        : undefined;
+    // A bottom open layer can still retain its merged parent's PR base. Its update starts
+    // at trunk regardless of that base comparison; true upper layers first check the parent.
+    const trunkConflict = hasConflicts && stack && report.stackBottomPr === prNumber
+        ? { trunk: stack.baseRefName, bottomPr: prNumber }
+        : hasConflicts && stack && headRef && baseLookup.branch !== stack.baseRefName
+            ? await lookupUpperLayerTrunkConflict({
+                owner: repoOwner,
+                name: repoName,
+                pr: prNumber,
+                headRef,
+                trunk: stack.baseRefName,
+                bottomPr: report.stackBottomPr,
+            })
+            : undefined;
     const requeue = buildRemovedQueueRecovery(report, failingAgentChecks, opts.merge);
     const queueRemovalAcknowledgment = buildStackQueueRemovalAcknowledgment(report, failingAgentChecks);
     const queueEjection = !currentEjectionCommit(report, failingAgentChecks)
@@ -323,7 +327,7 @@ export async function handleFixCode(ctx) {
     // Conflicts, a behind branch whose rerun already failed, and a queue ejection that may be
     // reproduced on the latest base all print the branch update route.
     const stackRebase = hasConflicts || (isBehind && exhaustedAttempts.length > 0) || queueEjection
-        ? buildNativeStackLayerRebase(report.repo, { number: prNumber, baseBranch: baseLookup.branch }, stack, trunkConflict)
+        ? buildNativeStackLayerRebase(report.repo, { number: prNumber, baseBranch: baseLookup.branch }, stack, trunkConflict, report.stackBottomPr)
         : undefined;
     const instructions = buildFixInstructions(threads, actionableComments, checks, changesRequestedReviews, baseLookup.branch, resolveCommand, hasConflicts, prReference, cancelled.length, firstLookThreads, firstLookComments, firstLookSummaries, editedSummaries, inProgressRunIds, resolutionOnlyThreads, resolveOnlyCommand, behindBaseHint, isBehind, report.viewerAuthorization?.viewerCanUpdate === true, exhaustedAttempts.length > 0, stackRebase, queueEjection);
     if (failingAgentChecks.some((check) => releasedCheckNames.has(check.name))) {

package/bin/commands/iterate/native-stack-rebase.d.mts

@@ -22,10 +22,11 @@ export declare function buildNativeStackRebaseInstruction(repo: string, stackNum
 /**
  * The stack-aware branch update for a native stack layer (a conflict, or a behind branch whose
  * workflow keeps failing); undefined outside a stack.
- * A layer whose PR targets the stack's trunk (`stack.baseRefName`) is the bottom open layer —
- * position 1, or a higher layer GitHub retargeted after every layer below it merged. Any other
- * layer is an upper layer whose parent is its own PR base branch. `trunkConflict` means that
- * upper layer already contains its parent, so the rebase starts at the bottom open layer.
+ * The first open layer in validated stack order is the bottom open layer, even when GitHub
+ * retains its merged parent's branch as its PR base. Without that topology, a PR base matching
+ * the stack trunk also identifies a bottom layer. Other layers rebase from their PR base.
+ * `trunkConflict` means an upper layer already contains its parent, so the rebase starts
+ * at the bottom open layer.
  */
 export declare function buildNativeStackLayerRebase(repo: string, pr: {
     number: number;
@@ -33,7 +34,7 @@ export declare function buildNativeStackLayerRebase(repo: string, pr: {
 }, stack: StackStatus | undefined, trunkConflict?: {
     trunk: string;
     bottomPr?: number;
-}): string | undefined;
+}, stackBottomPr?: number): string | undefined;
 /** Point at the conflicts, and at the stack rebase when the PR is a native stack layer. */
 export declare function buildConflictInstruction(stackRebase: string | undefined): string;
 /**

package/bin/commands/iterate/native-stack-rebase.mjs

@@ -15,26 +15,32 @@ export function buildNativeStackRebaseInstruction(repo, stackNumber, start) {
         ]
         : "bottomPr" in start
             ? [`check out the head branch of PR #${start.bottomPr}`, "gh stack rebase"]
-            : [`check out the bottom open layer whose base is \`${start.trunk}\``, "gh stack rebase"];
+            : [
+                `check out the bottom open layer of the stack to rebase onto \`${start.trunk}\``,
+                "gh stack rebase",
+            ];
     const prepare = `if \`gh stack\` does not track stack #${stackNumber} locally, import it with \`gh stack checkout ${stackNumber}\``;
     return `From a clean checkout of \`${repo}\`, ${prepare}. Then ${checkout} and run \`${command}\`. ${playbookPointer("Branch update")}`;
 }
 /**
  * The stack-aware branch update for a native stack layer (a conflict, or a behind branch whose
  * workflow keeps failing); undefined outside a stack.
- * A layer whose PR targets the stack's trunk (`stack.baseRefName`) is the bottom open layer —
- * position 1, or a higher layer GitHub retargeted after every layer below it merged. Any other
- * layer is an upper layer whose parent is its own PR base branch. `trunkConflict` means that
- * upper layer already contains its parent, so the rebase starts at the bottom open layer.
+ * The first open layer in validated stack order is the bottom open layer, even when GitHub
+ * retains its merged parent's branch as its PR base. Without that topology, a PR base matching
+ * the stack trunk also identifies a bottom layer. Other layers rebase from their PR base.
+ * `trunkConflict` means an upper layer already contains its parent, so the rebase starts
+ * at the bottom open layer.
  */
-export function buildNativeStackLayerRebase(repo, pr, stack, trunkConflict) {
+export function buildNativeStackLayerRebase(repo, pr, stack, trunkConflict, stackBottomPr) {
     if (!stack)
         return undefined;
     const start = trunkConflict
         ? trunkConflict.bottomPr !== undefined
             ? { bottomPr: trunkConflict.bottomPr }
             : { trunk: trunkConflict.trunk }
-        : pr.baseBranch === stack.baseRefName
+        : (stackBottomPr !== undefined
+            ? pr.number === stackBottomPr
+            : pr.baseBranch === stack.baseRefName)
             ? { bottomPr: pr.number }
             : { parentBranch: pr.baseBranch };
     return buildNativeStackRebaseInstruction(repo, stack.number, start);

package/bin/commands/iterate/stack-trunk-conflict.d.mts

@@ -1,7 +1,7 @@
-/** An upper layer already contains its parent, so the dirty state is against trunk. */
+/** A bottom open layer, or an upper layer that already contains its parent, updates from trunk. */
 export interface UpperLayerTrunkConflict {
     trunk: string;
-    /** Open layer whose PR base is the trunk. Omitted when that layer is not on this page. */
+    /** First open layer after a verified merged prefix. Omitted when topology is unavailable. */
     bottomPr?: number;
 }
 export declare function lookupUpperLayerTrunkConflict(input: {
@@ -10,4 +10,6 @@ export declare function lookupUpperLayerTrunkConflict(input: {
     pr: number;
     headRef: string;
     trunk: string;
+    /** Reuse the bottom layer already resolved for the report, avoiding a topology fetch. */
+    bottomPr?: number;
 }): Promise<UpperLayerTrunkConflict | undefined>;

package/bin/commands/iterate/stack-trunk-conflict.mjs

@@ -1,18 +1,34 @@
 import { graphql } from "../../github/client.mjs";
+import { readStackTopology, verifiedBottomOpenLayer } from "../../github/stack-read.mjs";
 import { UPPER_LAYER_CONFLICT_TARGET_QUERY } from "../../github/queries.mjs";
 import { pollRateLimitRetryAfterMs } from "../poll-quota.mjs";
-/** Lowest-position open layer whose base is the stack trunk, if this page contains one. */
-function selectBottomOpenLayer(nodes, trunk) {
-    const onTrunk = nodes.flatMap((node) => {
-        const pull = node?.pullRequest;
-        if (!node || !pull || pull.state !== "OPEN" || pull.baseRefName !== trunk)
-            return [];
-        return [{ position: node.position, number: pull.number }];
-    });
-    onTrunk.sort((a, b) => a.position - b.position);
-    return onTrunk[0]?.number;
-}
 export async function lookupUpperLayerTrunkConflict(input) {
+    let bottomPr = input.bottomPr;
+    if (bottomPr === undefined) {
+        let topology;
+        try {
+            topology = await readStackTopology(input.pr, { owner: input.owner, name: input.name });
+        }
+        catch (err) {
+            if (pollRateLimitRetryAfterMs(err) !== null)
+                throw err;
+            ignore(input.pr, err instanceof Error ? err.message : String(err));
+        }
+        if (topology) {
+            try {
+                bottomPr = verifiedBottomOpenLayer(topology.ordered, input.pr).number;
+            }
+            catch (err) {
+                ignore(input.pr, err instanceof Error ? err.message : String(err));
+                // A base comparison cannot prove that a closed or unverified predecessor merged.
+                return undefined;
+            }
+        }
+    }
+    // Merged lower layers need not cause GitHub to retarget this PR to trunk. Even when its
+    // head is behind that old parent branch, the first open layer rebases the stack onto trunk.
+    if (bottomPr === input.pr)
+        return { trunk: input.trunk, bottomPr };
     let data;
     try {
         ({ data } = await graphql(UPPER_LAYER_CONFLICT_TARGET_QUERY, {
@@ -37,13 +53,6 @@ export async function lookupUpperLayerTrunkConflict(input) {
     // behindBy > 0: the layer is still behind its parent. Keep the parent rebase.
     if (behindBy !== 0)
         return undefined;
-    const entries = pull.stack?.entries;
-    const bottomPr = entries ? selectBottomOpenLayer(entries.nodes, input.trunk) : undefined;
-    if (bottomPr === undefined) {
-        ignore(input.pr, entries?.pageInfo.hasNextPage
-            ? "stack entry page truncated before the trunk layer"
-            : "bottom open layer not found");
-    }
     return { trunk: input.trunk, ...(bottomPr !== undefined && { bottomPr }) };
 }
 function ignore(pr, message) {

package/bin/github/gql/upper-layer-conflict-target.gql

@@ -16,21 +16,6 @@ query UpperLayerConflictTarget($owner: String!, $name: String!, $number: Int!, $
           behindBy
         }
       }
-      stack {
-        entries(first: 100) {
-          pageInfo {
-            hasNextPage
-          }
-          nodes {
-            position
-            pullRequest {
-              number
-              state
-              baseRefName
-            }
-          }
-        }
-      }
     }
   }
 }

package/bin/github/merge-target-rules.d.mts

@@ -27,3 +27,7 @@ export declare function loadMergeTargetStatus(input: {
  * is also open, so this compare is the behind count that status hides.
  */
 export declare function loadBaseBehindBy(owner: string, name: string, baseRefName: string, headRef: string): Promise<number>;
+export declare function loadRefRules(owner: string, name: string, qualifiedName: string, headRef: string): Promise<{
+    contexts: string[];
+    behindBy: number;
+}>;

package/bin/github/merge-target-rules.mjs

@@ -3,7 +3,7 @@ import { parseBranchRules } from "./batch-parsers-rules.mjs";
 import { graphqlWithRateLimit } from "./client.mjs";
 import { missingRepositoryError } from "./errors.mjs";
 import { BASE_BEHIND_QUERY, REF_RULES_QUERY } from "./queries.mjs";
-import { readStackTopology } from "./stack-read.mjs";
+import { readStackTopology, verifiedBottomOpenLayer } from "./stack-read.mjs";
 /**
  * Required status contexts for the branch GitHub actually merges into.
  * A native stack uses the trunk ref, and `behindBy` is that trunk against the bottom open layer.
@@ -15,24 +15,22 @@ export async function loadMergeTargetStatus(input, context) {
     let headRef = input.headRefName;
     let stackBottomPr = input.pr;
     if (trunk !== input.baseRefName) {
-        const bottom = await bottomOpenLayer(input.pr, { owner: input.owner, name: input.name }, trunk, context);
-        headRef = bottom.headRefName;
+        const bottom = await bottomOpenLayer(input.pr, { owner: input.owner, name: input.name }, context);
+        headRef = bottom.headRefOid;
         stackBottomPr = bottom.number;
     }
-    const loaded = await fetchRefRules(input.owner, input.name, `refs/heads/${trunk}`, headRef);
+    const loaded = await loadRefRules(input.owner, input.name, `refs/heads/${trunk}`, headRef);
     return {
         contexts: loaded.contexts,
         ...(loaded.behindBy > 0 && { trunkBehindBy: loaded.behindBy }),
         stackBottomPr,
     };
 }
-async function bottomOpenLayer(pr, repo, trunk, context) {
+async function bottomOpenLayer(pr, repo, context) {
     const topology = await (context?.readStackTopology(pr, repo) ?? readStackTopology(pr, repo));
-    const bottom = topology.ordered.find((member) => member.state === "OPEN" && member.baseRefName === trunk);
-    if (!bottom) {
-        throw new ShepherdError(`Native stack for PR #${pr} has no open layer based on ${trunk}`, EXIT.TEMPFAIL);
-    }
-    return bottom;
+    // GitHub can retain a merged parent's branch as the lowest open layer's
+    // base. Stack order, rather than retargeting, determines the review target.
+    return verifiedBottomOpenLayer(topology.ordered, pr);
 }
 /**
  * Commits on the PR base that `headRef` does not contain.
@@ -57,7 +55,7 @@ export async function loadBaseBehindBy(owner, name, baseRefName, headRef) {
     }
     return ref.compare?.behindBy ?? 0;
 }
-async function fetchRefRules(owner, name, qualifiedName, headRef) {
+export async function loadRefRules(owner, name, qualifiedName, headRef) {
     const { data } = await graphqlWithRateLimit(REF_RULES_QUERY, {
         owner,
         repo: name,

package/bin/github/poll-summary-unreported.d.mts

@@ -1,6 +1,7 @@
+import type { RepoInfo } from "./client.mts";
 import type { PollSummaryChecks } from "../types.mts";
 import type { RawSummaryPr } from "./poll-summary-raw.mts";
-/** Required contexts from the open layer whose base is the stack trunk. */
-export declare function trunkRequiredContexts(ordered: readonly RawSummaryPr[]): string[] | undefined;
+/** Current trunk rules may remain available on a merged layer's base ref. */
+export declare function trunkRequiredContexts(ordered: readonly RawSummaryPr[], repo: RepoInfo): Promise<string[] | undefined>;
 /** Record missing required contexts. A running Actions workflow does not clear the names. */
 export declare function applyUnreportedRequiredChecks(raw: RawSummaryPr, checks: PollSummaryChecks, mergeTargetContexts: readonly string[] | undefined): void;

package/bin/github/poll-summary-unreported.mjs

@@ -1,15 +1,20 @@
 import { loadConfig } from "../config/load.mjs";
 import { actionsWorkflowInProgress, selectMergeTargetContexts, unreportedRequiredContexts, } from "../checks/unreported-required.mjs";
 import { parseBranchRules } from "./batch-parsers-rules.mjs";
-/** Required contexts from the open layer whose base is the stack trunk. */
-export function trunkRequiredContexts(ordered) {
+import { loadRefRules } from "./merge-target-rules.mjs";
+/** Current trunk rules may remain available on a merged layer's base ref. */
+export async function trunkRequiredContexts(ordered, repo) {
     const trunk = ordered.find((pr) => pr.stack)?.stack?.baseRefName;
     if (!trunk)
         return undefined;
-    const bottom = ordered.find((pr) => pr.state === "OPEN" && pr.baseRefName === trunk);
+    const bottom = ordered.find((pr) => pr.state === "OPEN");
     if (!bottom)
         return undefined;
-    return parseBranchRules(bottom.baseRef).requiredStatusCheckContexts;
+    const trunkLayer = ordered.find((pr) => pr.baseRefName === trunk && pr.baseRef != null);
+    if (trunkLayer)
+        return parseBranchRules(trunkLayer.baseRef).requiredStatusCheckContexts;
+    const loaded = await loadRefRules(repo.owner, repo.name, `refs/heads/${trunk}`, bottom.headRefOid);
+    return loaded.contexts;
 }
 /** Record missing required contexts. A running Actions workflow does not clear the names. */
 export function applyUnreportedRequiredChecks(raw, checks, mergeTargetContexts) {

package/bin/github/poll-summary.mjs

@@ -72,7 +72,7 @@ async function fetchStackSummary(opts, repo) {
         await refreshUnknownSummaryMergeability(pr, repo);
     }
     const stackAncestry = stackAncestryGaps(ordered);
-    const required = trunkRequiredContexts(ordered);
+    const required = await trunkRequiredContexts(ordered, repo);
     return {
         selection: { kind: "stack", anchor, stackNumber, stackSize },
         prs: await Promise.all(ordered.map((pr) => summarizePollSummaryPr(pr, repo, opts, viewerCanAdminister, required, viewerLogin))),

package/bin/github/queries.d.mts

@@ -35,8 +35,8 @@ export declare const POLL_STACK_SUMMARY_QUERY: string;
 /** Reads only native-stack membership and the refs that link adjacent entries. */
 export declare const POLL_STACK_TOPOLOGY_QUERY: string;
 /**
- * Whether a conflicting upper stack layer already contains its PR base, plus
- * the open stack entries needed to name the bottom layer. Not part of BatchPr.
+ * Whether a conflicting upper stack layer already contains its PR base.
+ * Bottom-layer identity comes from the validated stack topology. Not part of BatchPr.
  */
 export declare const UPPER_LAYER_CONFLICT_TARGET_QUERY: string;
 /** Merged PRs whose head may be the stale base of a non-stack conflict. */

package/bin/github/queries.mjs

@@ -40,8 +40,8 @@ export const POLL_STACK_SUMMARY_QUERY = `${POLL_SUMMARY_FRAGMENT}\n${gql("poll-s
 /** Reads only native-stack membership and the refs that link adjacent entries. */
 export const POLL_STACK_TOPOLOGY_QUERY = gql("poll-stack-topology.gql");
 /**
- * Whether a conflicting upper stack layer already contains its PR base, plus
- * the open stack entries needed to name the bottom layer. Not part of BatchPr.
+ * Whether a conflicting upper stack layer already contains its PR base.
+ * Bottom-layer identity comes from the validated stack topology. Not part of BatchPr.
  */
 export const UPPER_LAYER_CONFLICT_TARGET_QUERY = gql("upper-layer-conflict-target.gql");
 /** Merged PRs whose head may be the stale base of a non-stack conflict. */

package/bin/github/stack-read.d.mts

@@ -31,6 +31,8 @@ export interface StackRead<Pr extends StackMemberRefs> {
 export declare function readStack<Pr extends StackMemberRefs>(query: string, anchor: number, repo: RepoInfo, variables?: Record<string, unknown>): Promise<StackRead<Pr>>;
 /** Membership and linking refs only — no per-PR CI or review hydration. */
 export declare function readStackTopology(anchor: number, repo: RepoInfo): Promise<StackRead<StackMemberRefs>>;
+/** The first open member can replace merged lower layers only after a fully merged prefix. */
+export declare function verifiedBottomOpenLayer<Pr extends StackMemberRefs>(ordered: readonly Pr[], anchor: number): Pr;
 /**
  * Adjacent entries, both open, whose child base no longer matches the parent
  * head. Both sides come from the same read, so each gap was observed together.

package/bin/github/stack-read.mjs

@@ -77,6 +77,19 @@ export async function readStack(query, anchor, repo, variables = {}) {
 export function readStackTopology(anchor, repo) {
     return readStack(POLL_STACK_TOPOLOGY_QUERY, anchor, repo);
 }
+/** The first open member can replace merged lower layers only after a fully merged prefix. */
+export function verifiedBottomOpenLayer(ordered, anchor) {
+    const index = ordered.findIndex((member) => member.state === "OPEN");
+    const bottom = ordered[index];
+    if (!bottom) {
+        throw new ShepherdError(`Native stack for PR #${anchor} has no open layer`, EXIT.TEMPFAIL);
+    }
+    const predecessor = ordered.slice(0, index).find((member) => member.state !== "MERGED");
+    if (predecessor) {
+        throw new ShepherdError(`Native stack for PR #${anchor} has PR #${predecessor.number} in state ${predecessor.state} before open PR #${bottom.number}; cannot verify the bottom open layer`, EXIT.TEMPFAIL);
+    }
+    return bottom;
+}
 /**
  * Adjacent entries, both open, whose child base no longer matches the parent
  * head. Both sides come from the same read, so each gap was observed together.

package/package.json

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

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

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