pr-shepherd 0.51.1 → 0.52.0

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.51.1",
+  "version": "0.52.0",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/README.md

@@ -36,7 +36,10 @@ Each tick returns exactly one action:
 - `FIX_CODE` — agent work is required; complete it, push when needed, then continue polling. Push access to the PR head branch is a usage precondition.
 - `MERGE` — run the emitted head-pinned auto-merge or queue command. Ordinary merges include a plain-merge fallback; queue merges include a GraphQL enqueue fallback. GitHub is authoritative for the result and reports any authorization failure.
 - `CANCEL` — stop polling because the PR merged, closed, or completed its ready-delay.
-- `ESCALATE` — stop polling until a human provides direction.
+- `ESCALATE` — stop polling until a human provides direction. Native stacks reach this only after their autonomous one-PR sessions are exhausted.
+
+Native-stack summaries additionally use stack-level `SHEPHERD`: run the listed one-PR sessions,
+then recheck the stack. It is not a per-PR `FIX_CODE` action.
 
 Example shape:
 
@@ -79,7 +82,7 @@ Conversations Resolved: No [Not Required]
 9. `[FIX_CODE]` is non-terminal: if you changed code, commit and push to the PR head branch, then run review mutations using the pushed commit SHA and iterate immediately with the same options; without code changes, complete the authorized review mutations and iterate immediately.
 ```
 
-See [docs/actions.md](docs/actions.md) for the complete output contract and [docs/escalations.md](docs/escalations.md) for the exact finite human-handoff boundary. Iterate/poll PR outcomes use exit codes `0` and `10`–`15`; command and GitHub failures use `sysexits.h` codes — [docs/exit-codes.md](docs/exit-codes.md).
+See [docs/actions.md](docs/actions.md) for the complete output contract and [docs/escalations.md](docs/escalations.md) for the exact finite human-handoff boundary. Iterate/poll PR outcomes use exit codes `0` and `10`–`16`; command and GitHub failures use `sysexits.h` codes — [docs/exit-codes.md](docs/exit-codes.md).
 
 ## Workflow Assumptions
 
@@ -129,7 +132,7 @@ pr-shepherd 42                         # poll until non-WAIT or timeout
 pr-shepherd 42 --interval 60s --timeout 270s
 pr-shepherd 42 --quiet-status          # print only changed WAIT status snapshots
 pr-shepherd 42 --until-terminal        # continue through WAIT/MARK_READY until work or terminal state
-pr-shepherd 42 --debounce 5m           # wait 5m after first FIX_CODE, then return one batched tick
+pr-shepherd 42 --debounce 5m           # wait 5m after first FIX_CODE or stack SHEPHERD, then return one batched tick
 pr-shepherd 42 --ready-delay 15m
 pr-shepherd 42 --merge                  # request head-pinned auto-merge/queue; GitHub reports the result
 pr-shepherd iterate 42                 # single tick
@@ -139,20 +142,25 @@ pr-shepherd 42 43 44                   # summarize an explicit same-repository s
 pr-shepherd --stack 43                 # summarize every PR in a native GitHub stack
 ```
 
-Multi-PR and `--stack` polling use compact, read-only GraphQL summaries. They return when any row
-needs agent work, all rows are terminal, the bounded timeout expires, or `--until-terminal` crosses
-a configured GraphQL quota-warning band. Check counts use the same ignored, protected-run,
-superseded-run, and event rules as singular iteration and include active merge-queue commit checks.
-Bounded review/check overflow remains visible without permanently forcing work, and clean rows use
-the configured ready-delay before becoming terminal. Explicit PR sets give each actionable row an
-exact single-PR `pollCommand`, so independent rows can proceed before the next aggregate poll.
-Stack rows are ordered bottom-to-top and follow the one ordered stack instruction block instead.
-The summary also checks that every open child was based on
-its direct parent's current head. A stale child/parent OID pair is actionable even when GitHub
-reports both PRs clean: without `--merge`, rebase the upstack branches from their parent and push
-them with the emitted `gh stack` commands; with `--merge`, finish the contiguous ready lower
-layers with the emitted `gh stack merge --squash` command, recheck, then repair the child. API and
-MCP aggregate calls perform one summary tick and leave recurrence to the caller.
+Multi-PR and `--stack` polling use compact, read-only GraphQL summaries. They return when work is
+needed, every selected PR is complete, the bounded timeout expires, or `--until-terminal` crosses a
+configured GraphQL quota-warning band. Explicit PR sets give each actionable row an exact single-PR
+`pollCommand`, so independent rows can proceed before the next aggregate poll.
+
+Native-stack rows are ordered bottom-to-top. `--stack` never performs a mutation itself; only
+`--stack --merge` can emit a complete-stack merge command for the agent. An unready layer (draft, missing a READY
+receipt, conflicting, failing, or stale) returns stack-level `SHEPHERD` with one-PR Shepherd instructions for
+the affected layers. A draft or other unready lower layer marks every higher open layer with
+`blockedByPr`; review and CI sessions on independent layers may proceed concurrently, but an upper
+draft cannot transition to ready until every lower layer has its READY receipt. A queued stack
+returns `WAIT`. A terminal READY or fully merged stack returns `CANCEL`. Closed or unverified
+topology returns `ESCALATE` for human direction after any other shepherdable PRs are handled;
+until then, `SHEPHERD` remains the immediate action and lists the human blockers too.
+
+With `--stack --merge`, a fully reconciled and READY stack returns `MERGE` with a `gh stack merge`
+command for the agent to run, checking and installing the optional `github/gh-stack` extension first
+when necessary. It then rechecks until every layer merges and returns `CANCEL`. API and MCP
+aggregate calls perform one summary tick and leave recurrence to the caller.
 
 Polling defaults can be set under `poll` in `.pr-shepherdrc.yml`: `intervalSeconds`, `timeoutSeconds`, `debounceSeconds`, and `quietStatus`. Explicit flags override configuration, including `--no-quiet-status` when a shared config enables quiet output. Quiet status remains off by default.
 

package/bin/cli/iterate-lean.mjs

@@ -183,9 +183,6 @@ export function projectIterateLean(result, opts) {
                     ...(result.escalate.mergeQueueRemoval && {
                         mergeQueueRemoval: result.escalate.mergeQueueRemoval,
                     }),
-                    ...(result.escalate.stack && {
-                        stack: result.escalate.stack,
-                    }),
                     ...(result.escalate.authorization &&
                         result.escalate.authorization.length > 0 && {
                         authorization: result.escalate.authorization,

package/bin/cli/poll-summary-emitter.mjs

@@ -12,13 +12,12 @@ function pollSummaryExitCode(result) {
     if (result.nextAction) {
         const stackExitCode = {
             escalate: EXIT.ESCALATE,
-            fix_code: EXIT.FIX_CODE,
+            shepherd: EXIT.SHEPHERD,
             merge: EXIT.MERGE,
-            mark_ready: EXIT.MARK_READY,
             wait: EXIT.WAIT,
             cancel: EXIT.OK,
         };
-        return stackExitCode[result.nextAction] ?? EXIT.OK;
+        return stackExitCode[result.nextAction];
     }
     const actions = new Set(result.prs.map((item) => item.action));
     if (actions.has("escalate"))

package/bin/cli/poll-summary-formatter.mjs

@@ -7,7 +7,7 @@ export function formatPollSummaryResult(result) {
     const lines = [
         `# Poll summary [${result.reason.toUpperCase()}]`,
         "",
-        `**repo** \`${result.repo}\` · **selection** ${selection} · **mode** \`${result.mode}\`${result.nextAction ? ` · **next action** \`${result.nextAction}\`` : ""}`,
+        `**repo** \`${result.repo}\` · **selection** ${selection} · **mode** \`${result.mode}\`${result.stackMergeable !== undefined ? ` · **stack mergeable** \`${result.stackMergeable}\`` : ""}${result.nextAction ? ` · **next action** \`${result.nextAction}\`` : ""}`,
         "",
         "## Pull requests",
         "",
@@ -42,11 +42,13 @@ function formatItem(item) {
         ? " · blocking reviewer `in progress`"
         : "";
     const readyDelay = item.remainingSeconds !== undefined ? ` · ready delay \`${item.remainingSeconds}s\`` : "";
+    const readyReceipt = item.readyReceipt ? " · Shepherd READY completion `verified`" : "";
+    const blockedBy = item.blockedByPr ? ` · stack blocked by PR #${item.blockedByPr}` : "";
     const checks = item.checks;
     const review = item.review;
     return [
         `- [PR #${item.pr}: ${escapeMarkdownText(item.title)}](${item.url}) [${item.action.toUpperCase()}]`,
-        `  - state \`${item.state}\` · mergeable \`${item.mergeable}\` · merge \`${item.mergeStateStatus}\`${reviewDecision}${stateFlags}${blockingReviewer}${readyDelay}${stack}`,
+        `  - state \`${item.state}\` · mergeable \`${item.mergeable}\` · merge \`${item.mergeStateStatus}\`${reviewDecision}${stateFlags}${blockingReviewer}${readyDelay}${readyReceipt}${blockedBy}${stack}`,
         `  - head \`${item.headRefName}\` at \`${item.headRefOid}\` · base \`${item.baseRefName}\``,
         ...(checks
             ? [`  - checks: ${formatCounts(checks, checks.incomplete ? ", incomplete" : "")}`]
@@ -54,6 +56,11 @@ function formatItem(item) {
         ...(review
             ? [`  - review: ${formatCounts(review, review.incomplete ? ", incomplete" : "")}`]
             : []),
+        ...(item.queueRemoval
+            ? [
+                `  - queue removal: reason \`${item.queueRemoval.reason ?? "UNKNOWN"}\` · at \`${item.queueRemoval.createdAtUnix}\`${item.queueRemoval.actor ? ` · actor \`@${item.queueRemoval.actor}\`` : ""}${item.queueRemoval.beforeCommitOid ? ` · commit \`${item.queueRemoval.beforeCommitOid}\`` : ""}${item.queueRemoval.beforeCommitParentOids?.length ? ` · parents \`${item.queueRemoval.beforeCommitParentOids.join(",")}\`` : ""}`,
+            ]
+            : []),
         `  - reasons: ${item.reasons.map((reason) => `\`${reason}\``).join(", ")}`,
         ...(item.pollCommand ? [`  - pollCommand: \`${item.pollCommand}\``] : []),
     ].join("\n");

package/bin/commands/check.mjs

@@ -249,6 +249,7 @@ export async function runCheck(opts) {
         ...(batchData.viewerAuthorization && { viewerAuthorization: batchData.viewerAuthorization }),
         status,
         baseBranch: batchData.baseRefName,
+        ...(batchData.baseRefOid && { baseRefOid: batchData.baseRefOid }),
         mergeStatus,
         checks: {
             passing: merged.passing,

package/bin/commands/iterate/escalate.mjs

@@ -1,5 +1,4 @@
 import { loadConfig } from "../../config/load.mjs";
-import { inlineCode } from "../../util/markdown.mjs";
 import { renderResolveCommand } from "./render.mjs";
 function renderEscalateAuthor(item) {
     return [`@${item.author}`, item.authorType, item.authorAssociation].filter(Boolean).join(" · ");
@@ -194,10 +193,6 @@ export function buildEscalateHumanMessage(escalate, pr, opts) {
         if (removal.beforeCommitOid)
             lines.push(`- queue commit: \`${removal.beforeCommitOid}\``);
     }
-    if (escalate.stack) {
-        const s = escalate.stack;
-        lines.push("", "## GitHub stack", "", `- layer: \`${s.position}\` of \`${s.size}\` in stack \`${s.number}\``, `- stack base: ${inlineCode(s.baseRefName)}`);
-    }
     if (escalate.authorization && escalate.authorization.length > 0) {
         lines.push("");
         lines.push("## Authorization");
@@ -231,10 +226,6 @@ export function buildEscalateHumanMessage(escalate, pr, opts) {
     return lines.join("\n");
 }
 export function buildEscalateSuggestion(triggers, detail) {
-    if (triggers.includes("stacked-pr")) {
-        const selector = detail ?? "<pr>";
-        return `This PR belongs to a GitHub stack, so Shepherd will not emit a merge command. \`gh pr merge\` targets the PR's own base branch — for a mid-stack layer that is the unmerged parent branch, not the stack's base — and auto-merge is unsupported on stacked PRs. Merge from the GitHub stack UI, or run \`gh stack merge --squash ${selector}\` (requires the \`github/gh-stack\` extension — run \`gh extension install github/gh-stack\` first if it's not installed), which lands this PR and every unmerged layer below it.`;
-    }
     if (triggers.includes("check-follow-up-unavailable")) {
         return "One or more failing checks have no autonomous follow-up available. Use the displayed conclusion, run or URL, and included evidence to handle them manually.";
     }
@@ -257,9 +248,5 @@ export function buildEscalateSuggestion(triggers, detail) {
         const attempts = loadConfig().iterate.fixAttemptsPerThread;
         return `The same thread(s) remain unresolved after their pending review commands were returned for ${attempts} FIX_CODE ticks. Automated iteration is paused for a manual decision.`;
     }
-    if (triggers.includes("bot-cr-not-dismissed")) {
-        const ids = detail ? ` (review IDs: ${detail})` : "";
-        return `Bot CHANGES_REQUESTED review(s) remained undismissed past the stall window${ids}. The agent likely dropped \`--dismiss-review-ids\` from a prior apply command. Dismiss the review(s) manually (or re-run \`pr-shepherd apply review\` with the IDs) to unblock the PR.`;
-    }
     return "Ambiguous state — automated handling cannot proceed safely. Inspect the PR and act manually.";
 }

package/bin/commands/iterate/fix-code.d.mts

@@ -20,6 +20,8 @@ interface HandleFixCodeContext {
     surfacedApprovals: Review[];
     botUsernames: NormalizedBotUsernames;
     ruleAutoResolveThreadIds?: string[];
+    /** Verified stack-repair guidance, when ancestry is stale. */
+    repairInstructions?: string[];
 }
 export declare function handleFixCode(ctx: HandleFixCodeContext): Promise<IterateResult>;
 export {};

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

@@ -1,6 +1,5 @@
 /* eslint-disable max-lines */
 import { readFixAttempts, writeFixAttempts, } from "../../state/fix-attempts.mjs";
-import { readBotCrSeenState, writeBotCrSeenState, updateBotCrSeenState, } from "../../state/bot-cr-seen.mjs";
 import { toAgentThread, toAgentComment, toAgentChecks } from "../../reporters/agent.mjs";
 import { hashBody, markSeen } from "../../state/seen-comments.mjs";
 import { checkEscalateTriggers, validateBaseBranch, buildEscalateSuggestion, buildEscalateHumanMessage, } from "./escalate.mjs";
@@ -17,15 +16,15 @@ import { formatPrUrl } from "../../pr-reference.mjs";
 function checkRequiresHumanFollowUp(check) {
     if (check.rerunCommand)
         return false;
-    // Once GitHub advances beyond the original attempt, Shepherd's one autonomous rerun has
-    // already been consumed. Hand the repeated failure off even when logs are available; the
-    // human still receives that evidence in the escalation payload.
-    if (check.runAttempt !== undefined && check.runAttempt > 1)
-        return true;
     if (check.conclusion === "ACTION_REQUIRED" ||
         check.conclusion === "CANCELLED" ||
         check.conclusion === "STARTUP_FAILURE")
         return true;
+    // A later attempt cannot be rerun automatically, but its included log can still
+    // identify a code or configuration fix for the agent. Only a later failure with
+    // no actionable evidence needs a human handoff.
+    if (check.runAttempt !== undefined && check.runAttempt > 1)
+        return !check.logExcerpt?.trim();
     // An external check's direct URL is actionable evidence: the agent can inspect the
     // provider and/or reproduce the reported failure locally. Only a truly bare check
     // has no autonomous investigation path.
@@ -68,7 +67,7 @@ function pendingReviewCommands(resolveCommand, resolveOnlyCommand) {
     return Object.keys(pending).length > 0 ? pending : undefined;
 }
 export async function handleFixCode(ctx) {
-    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, ruleAutoResolveThreadIds, } = ctx;
+    const { base, report, opts, headSha, stallKey, prNumber, stallTimeoutSeconds, repoOwner, repoName, reviewSummaryIds, firstLookSummaries, editedSummaries, surfacedApprovals, botUsernames, ruleAutoResolveThreadIds, repairInstructions, } = ctx;
     const prReference = formatPrUrl(report.repo, prNumber);
     const failingChecks = report.checks.failing;
     const annotatedExtra = checksWithActionableAnnotations(report).filter((c) => c.category !== "failing");
@@ -105,37 +104,6 @@ export async function handleFixCode(ctx) {
         ...(report.comments.minimizeIds ?? report.comments.actionable.map((comment) => comment.id)),
         ...reviewSummaryIds,
     ], changesRequestedReviewsForWork, checks, prReference, botUsernames, ruleAutoResolveThreadIds, report.viewerAuthorization, allThreads, resolveOtherHumanThreads);
-    const botCrReviews = report.changesRequestedReviews.filter((r) => (!isHumanAuthor(r) || isConfiguredBotAuthor(r, botUsernames)) &&
-        report.viewerAuthorization?.viewerCanAdminister === true);
-    const botCrStateKey = { owner: repoOwner, repo: repoName, pr: prNumber };
-    const previousBotCrState = await readBotCrSeenState(botCrStateKey);
-    const nowSeconds = Math.floor(Date.now() / 1000);
-    const { next: nextBotCrState, staleIds: staleBotCrIds } = updateBotCrSeenState(previousBotCrState, botCrReviews, nowSeconds, stallTimeoutSeconds);
-    await writeBotCrSeenState(botCrStateKey, nextBotCrState);
-    if (staleBotCrIds.length > 0) {
-        const { resolveCommand, resolveOnlyCommand } = buildReviewCommands(toAgentChecks(failingChecks));
-        const pending = pendingReviewCommands(resolveCommand, resolveOnlyCommand);
-        const escalateBase = {
-            triggers: ["bot-cr-not-dismissed"],
-            unresolvedThreads: [...report.threads.actionable, ...report.threads.resolutionOnly].map(toAgentThread),
-            ambiguousComments: report.comments.actionable.map(toAgentComment),
-            changesRequestedReviews: report.changesRequestedReviews,
-            ...(firstLookSummaries.length > 0 && { firstLookSummaries }),
-            ...(editedSummaries.length > 0 && { editedSummaries }),
-            ...(pending && { pendingReviewCommands: pending }),
-            suggestion: buildEscalateSuggestion(["bot-cr-not-dismissed"], staleBotCrIds.join(", ")),
-        };
-        return {
-            ...base,
-            action: "escalate",
-            escalate: {
-                ...escalateBase,
-                humanMessage: buildEscalateHumanMessage(escalateBase, prReference, {
-                    merge: opts.merge,
-                }),
-            },
-        };
-    }
     const escalateTriggers = countFixCodeAttempt
         ? checkEscalateTriggers(retryableActionableThreads, priorThreadAttempts)
         : { triggers: [], thrashHistory: undefined };
@@ -216,8 +184,9 @@ export async function handleFixCode(ctx) {
     const commentMinimizeIds = report.comments.minimizeIds ?? actionableComments.map((c) => c.id);
     const belongsToActiveWorkflowRun = (check) => check.runId !== null && inProgressWorkflowRunIds.has(check.runId);
     const manualFollowUpChecks = failingAgentChecks.filter((check) => !belongsToActiveWorkflowRun(check) && checkRequiresHumanFollowUp(check));
-    const exhaustedAttempts = manualFollowUpChecks.filter((check) => check.runAttempt !== undefined && check.runAttempt > 1);
-    const hasBehindBaseRecovery = isBehind && exhaustedAttempts.length > 0;
+    const exhaustedAttempts = failingAgentChecks.filter((check) => check.runAttempt !== undefined && check.runAttempt > 1);
+    const manualExhaustedAttempts = exhaustedAttempts.filter((check) => manualFollowUpChecks.includes(check));
+    const hasBehindBaseRecovery = isBehind && manualExhaustedAttempts.length > 0;
     const hasAutonomousWork = hasConflicts ||
         hasBehindBaseRecovery ||
         threads.length > 0 ||
@@ -235,8 +204,8 @@ export async function handleFixCode(ctx) {
     if (manualFollowUpChecks.length > 0 && !hasAutonomousWork) {
         const { resolveCommand, resolveOnlyCommand } = buildReviewCommands(failingAgentChecks);
         const pending = pendingReviewCommands(resolveCommand, resolveOnlyCommand);
-        const checkSuggestion = exhaustedAttempts.length > 0
-            ? `GitHub reports a later workflow attempt (${exhaustedAttempts
+        const checkSuggestion = manualExhaustedAttempts.length > 0
+            ? `GitHub reports a later workflow attempt (${manualExhaustedAttempts
                 .map((check) => `${check.runId ?? check.name}: attempt ${check.runAttempt}`)
                 .join(", ")}), so Shepherd's single rerun allowance is exhausted. Use the included evidence to handle the repeated failure manually before resuming.`
             : buildEscalateSuggestion(["check-follow-up-unavailable"]);
@@ -303,6 +272,9 @@ export async function handleFixCode(ctx) {
     const firstLookThreads = report.threads.firstLook;
     const firstLookComments = report.comments.firstLook;
     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);
+    if (repairInstructions && repairInstructions.length > 0) {
+        instructions.unshift(...repairInstructions);
+    }
     const prospectiveResult = {
         ...base,
         baseBranch: baseLookup.branch,

package/bin/commands/iterate/index.mjs

@@ -16,6 +16,14 @@ import { buildReadyMergeOutcome, handleActiveMergeState } from "./merge-state.mj
 import { buildIterateBase } from "./base.mjs";
 import { markReadyIfAuthorized } from "./mark-ready.mjs";
 import { withIterateApiUsage } from "./run.mjs";
+import { fetchRawSummaryPr } from "../../github/poll-summary.mjs";
+import { summarizePollSummaryPr } from "../../github/poll-summary-projector.mjs";
+import { fingerprintRawSummaryPr } from "../../github/poll-summary-fingerprint.mjs";
+import { currentQueueRemovalEvent } from "../../github/poll-summary-queue-removal.mjs";
+import { isCurrentSummaryReady } from "../../github/poll-summary-readiness.mjs";
+import { clearReadyReceipt, isReadyReceiptCurrent, readReadyReceipt, writeReadyReceipt, } from "../../state/ready-receipts.mjs";
+import { parentBlocksMarkReady } from "./parent-first.mjs";
+import { findStaleNativeStackAncestry } from "./stale-ancestry.mjs";
 export function runIterate(opts) {
     return withIterateApiUsage(opts, () => runIterateCore(opts));
 }
@@ -80,8 +88,19 @@ async function runIterateCore(opts) {
         editedSummaries.length > 0 ||
         (config.iterate.minimizeApprovals && surfacedApprovals.length > 0);
     const activeMerge = Boolean(opts.merge && (report.mergeQueue?.inQueue || report.mergeQueue?.autoMergeRequest));
-    const isCleanReadyState = report.status === "READY" && !hasActionableWork && !activeMerge;
+    const staleAncestry = await findStaleNativeStackAncestry(report, {
+        owner: repoOwner,
+        name: repoName,
+    });
+    const isCleanReadyState = report.status === "READY" &&
+        !report.mergeStatus.isDraft &&
+        !hasActionableWork &&
+        !activeMerge &&
+        staleAncestry === null;
     const readyState = await updateReadyDelay(report.pr, isCleanReadyState, readyDelaySeconds, repoOwner, repoName);
+    if (report.mergeStatus.mergeRequirements?.stack) {
+        await invalidateStaleReadyReceipt({ owner: repoOwner, repo: repoName, pr: report.pr }, report, hasActionableWork);
+    }
     const base = buildIterateBase(report, readyState);
     const headSha = (await getCurrentHeadSha()) ?? "unknown";
     // Checks (including merge-queue synthetic-commit checks) and hard conflicts are signals
@@ -126,13 +145,50 @@ async function runIterateCore(opts) {
     });
     if (mergeStateResult)
         return mergeStateResult;
+    if (staleAncestry) {
+        return handleFixCode({
+            base,
+            report,
+            opts: { ...opts, prNumber, neverCancelRuns },
+            headSha,
+            stallKey,
+            prNumber,
+            stallTimeoutSeconds,
+            repoOwner,
+            repoName,
+            reviewSummaryIds,
+            firstLookSummaries,
+            editedSummaries,
+            surfacedApprovals,
+            botUsernames,
+            repairInstructions: staleAncestry.instructions,
+            ruleAutoResolveThreadIds: report.threads.ruleAutoResolveIds,
+        });
+    }
     const canMarkReady = report.status === "READY" &&
         report.mergeStatus.isDraft &&
         !report.mergeStatus.blockingBotReviewInProgress;
-    const markReadyResult = await markReadyIfAuthorized(canMarkReady && !opts.noAutoMarkReady && config.actions.autoMarkReady, base, report);
+    const blockedByParent = canMarkReady
+        ? await parentBlocksMarkReady(report, { owner: repoOwner, name: repoName })
+        : false;
+    const markReadyResult = await markReadyIfAuthorized(canMarkReady && !blockedByParent && !opts.noAutoMarkReady && config.actions.autoMarkReady, base, report);
     if (markReadyResult)
         return markReadyResult;
-    if (readyState.shouldCancel) {
+    if (readyState.shouldCancel && !report.mergeStatus.isDraft) {
+        const needsStackReceipt = report.mergeStatus.mergeRequirements?.stack !== undefined;
+        const receiptWritten = needsStackReceipt
+            ? await recordReadyReceipt({ owner: repoOwner, repo: repoName, pr: report.pr }, report)
+            : true;
+        if (!receiptWritten) {
+            const receiptWait = {
+                ...base,
+                action: "wait",
+                shouldCancel: false,
+                remainingSeconds: readyDelaySeconds,
+                log: `WAIT: PR #${base.pr} reached ready-delay but its stack readiness receipt could not be persisted`,
+            };
+            return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, receiptWait, report, reviewSummaryIds);
+        }
         await clearStallState(stallKey);
         const mergeResult = buildReadyMergeOutcome(opts.merge, true, base, report);
         if (mergeResult)
@@ -147,3 +203,84 @@ async function runIterateCore(opts) {
     }
     return applyStallGuard(stallKey, stallTimeoutSeconds, headSha, base, prNumber, { ...base, action: "wait", log: buildWaitLog(base) }, report, reviewSummaryIds);
 }
+async function recordReadyReceipt(key, report) {
+    if (report.status !== "READY" ||
+        report.mergeStatus.state !== "OPEN" ||
+        report.mergeStatus.isDraft ||
+        !report.headSha ||
+        !report.baseRefOid)
+        return false;
+    try {
+        const raw = await fetchRawSummaryPr(report.pr, { owner: key.owner, name: key.repo });
+        const fingerprint = fingerprintRawSummaryPr(raw);
+        if (fingerprint === null ||
+            raw.state !== "OPEN" ||
+            raw.isDraft ||
+            raw.headRefOid !== report.headSha ||
+            raw.baseRefOid !== report.baseRefOid)
+            return false;
+        const summary = await summarizePollSummaryPr(raw, { owner: key.owner, name: key.repo }, { stackPrNumber: report.pr });
+        if (!isCurrentSummaryReady(raw, summary.checks ?? {}, summary.review ?? {}))
+            return false;
+        const removalEvent = currentQueueRemovalEvent(raw);
+        await writeReadyReceipt({
+            version: 1,
+            ...key,
+            headRefOid: raw.headRefOid,
+            baseRefOid: raw.baseRefOid,
+            status: "READY",
+            isDraft: false,
+            readinessFingerprint: fingerprint,
+            ...(removalEvent?.id && {
+                acknowledgedQueueRemovalId: removalEvent.id,
+            }),
+            recordedAtUnix: Math.floor(Date.now() / 1000),
+        });
+        return true;
+    }
+    catch {
+        // The receipt is supplementary evidence. A transient summary fetch or
+        // state-directory failure must not turn a completed one-PR poll into a
+        // different Shepherd action.
+        return false;
+    }
+}
+async function invalidateStaleReadyReceipt(key, report, hasActionableWork) {
+    const receipt = await readReadyReceipt(key);
+    if (!receipt)
+        return;
+    const retainQueuedReceipt = report.mergeQueue?.inQueue === true &&
+        report.mergeStatus.state === "OPEN" &&
+        !report.mergeStatus.isDraft &&
+        Boolean(report.headSha && report.baseRefOid);
+    if (report.mergeStatus.state !== "OPEN" ||
+        report.mergeStatus.isDraft ||
+        !report.headSha ||
+        !report.baseRefOid ||
+        (!retainQueuedReceipt && (report.status !== "READY" || hasActionableWork))) {
+        await clearReadyReceipt(key);
+        return;
+    }
+    try {
+        const raw = await fetchRawSummaryPr(report.pr, { owner: key.owner, name: key.repo });
+        // Queue predecessors can advance the target branch without changing this
+        // PR's source. Compare against the receipt's base only while both fresh
+        // views still place the PR in the queue.
+        const queuedBaseAdvanced = retainQueuedReceipt && raw.isInMergeQueue;
+        const fingerprint = fingerprintRawSummaryPr(queuedBaseAdvanced ? { ...raw, baseRefOid: receipt.baseRefOid } : raw);
+        if (fingerprint === null ||
+            !isReadyReceiptCurrent(receipt, {
+                headRefOid: raw.headRefOid,
+                baseRefOid: queuedBaseAdvanced ? receipt.baseRefOid : raw.baseRefOid,
+                readinessFingerprint: fingerprint,
+                status: "READY",
+                isDraft: raw.isDraft,
+            })) {
+            await clearReadyReceipt(key);
+        }
+    }
+    catch {
+        // Fail closed: an unreadable current snapshot cannot validate old evidence.
+        await clearReadyReceipt(key);
+    }
+}

package/bin/commands/iterate/merge-state.mjs

@@ -2,26 +2,41 @@ import { clearStallState } from "../../state/iterate-stall.mjs";
 import { buildEscalateHumanMessage, buildEscalateSuggestion } from "./escalate.mjs";
 import { buildMergeCommandPlan } from "./merge.mjs";
 import { formatPrUrl } from "../../pr-reference.mjs";
-/** A stacked PR's merge is human-only: `gh pr merge` targets the PR's own base, which for a
- * mid-stack layer is an unmerged parent branch, and auto-merge is unsupported on stacks. */
-function buildStackedEscalateResult(base, report, stack) {
-    const escalateBase = {
-        triggers: ["stacked-pr"],
-        unresolvedThreads: [],
-        ambiguousComments: [],
-        changesRequestedReviews: [],
-        stack,
-        suggestion: buildEscalateSuggestion(["stacked-pr"], String(report.pr)),
-    };
+/**
+ * A one-PR poll cannot prove every native-stack layer is ready or linear. Route it through the
+ * aggregate stack selector, which does that reconciliation before emitting the whole-stack merge.
+ */
+function buildStackedRouteResult(base, report, stack) {
+    const prUrl = formatPrUrl(report.repo, report.pr);
     return {
         ...base,
-        action: "escalate",
-        escalate: {
-            ...escalateBase,
-            humanMessage: buildEscalateHumanMessage(escalateBase, formatPrUrl(report.repo, report.pr), {
-                merge: true,
-            }),
+        action: "fix_code",
+        fix: {
+            threads: [],
+            resolutionOnlyThreads: [],
+            actionableComments: [],
+            reviewSummaryIds: [],
+            firstLookSummaries: [],
+            editedSummaries: [],
+            surfacedApprovals: [],
+            checks: [],
+            changesRequestedReviews: [],
+            resolveCommand: {
+                argv: ["pr-shepherd", "apply", "review", prUrl],
+                requiresHeadSha: false,
+                requiresDismissMessage: false,
+                hasMutations: false,
+            },
+            instructions: [
+                `PR #${report.pr} is layer ${stack.position} of ${stack.size} in native stack #${stack.number}; do not run \`gh pr merge\` for this layer.`,
+                `Run \`pr-shepherd --stack ${prUrl} --until-terminal --merge\` to reconcile the complete stack and run its emitted whole-stack merge command.`,
+            ],
+            inProgressRunIds: [],
+            protectedRuns: [],
+            firstLookThreads: [],
+            firstLookComments: [],
         },
+        cancelled: [],
     };
 }
 export function buildReadyMergeOutcome(enabled, readyElapsed, base, report) {
@@ -29,7 +44,7 @@ export function buildReadyMergeOutcome(enabled, readyElapsed, base, report) {
         return null;
     const stack = report.mergeStatus.mergeRequirements?.stack;
     if (stack)
-        return buildStackedEscalateResult(base, report, stack);
+        return buildStackedRouteResult(base, report, stack);
     const queue = Boolean(report.mergeStatus.mergeRequirements?.mergeQueue?.required ||
         report.mergeStatus.mergeRequirements?.mergeQueue?.enabled);
     return {

package/bin/commands/iterate/parent-first.d.mts

@@ -0,0 +1,9 @@
+import type { RepoInfo } from "../../github/client.mts";
+import type { ShepherdReport } from "../../types.mts";
+/**
+ * Draft children may only be converted after their immediate parent has
+ * independently completed a one-PR ready-delay and the stack boundary is
+ * still linear.  A failed or incomplete stack read blocks this mutation but
+ * does not block ordinary review/CI work in the caller.
+ */
+export declare function parentBlocksMarkReady(report: ShepherdReport, repo: RepoInfo): Promise<boolean>;

package/bin/commands/iterate/parent-first.mjs

@@ -0,0 +1,57 @@
+import { fetchPollSummary } from "../../github/poll-summary.mjs";
+/**
+ * Draft children may only be converted after their immediate parent has
+ * independently completed a one-PR ready-delay and the stack boundary is
+ * still linear.  A failed or incomplete stack read blocks this mutation but
+ * does not block ordinary review/CI work in the caller.
+ */
+export async function parentBlocksMarkReady(report, repo) {
+    const stack = report.mergeStatus.mergeRequirements?.stack;
+    if (!stack || stack.position === 1)
+        return false;
+    if (stack.position < 1)
+        return true;
+    try {
+        const summary = await fetchPollSummary({ stackPrNumber: report.pr }, repo);
+        const child = summary.prs.find((item) => item.pr === report.pr);
+        const lowerLayers = summary.prs
+            .filter((item) => (item.stack?.position ?? Number.MAX_SAFE_INTEGER) < stack.position)
+            .sort((left, right) => (left.stack?.position ?? Number.MAX_SAFE_INTEGER) -
+            (right.stack?.position ?? Number.MAX_SAFE_INTEGER));
+        if (!child || child.state !== "OPEN" || lowerLayers.length !== stack.position - 1)
+            return true;
+        // Any stale boundary up through the child means at least one lower layer
+        // is no longer the base it was reviewed against. Ignore gaps above this
+        // child because they do not affect its immediate promotion boundary.
+        const checkedLayers = new Set([report.pr, ...lowerLayers.map((item) => item.pr)]);
+        if (summary.stackAncestry?.some((gap) => checkedLayers.has(gap.childPr)))
+            return true;
+        for (const parent of lowerLayers) {
+            // A merged parent is already satisfied; GitHub may have retargeted the
+            // child to the trunk as part of the merge.
+            if (parent.state === "MERGED")
+                continue;
+            if (parent.state !== "OPEN")
+                return true;
+            if (parent.isDraft || parent.mergeable === "CONFLICTING")
+                return true;
+            if (["DIRTY", "BEHIND", "UNKNOWN"].includes(parent.mergeStateStatus))
+                return true;
+            // A receipt only establishes readiness after a merge-queue removal once
+            // the one-PR session has observed and acknowledged that exact removal.
+            // The aggregate projection preserves an unacknowledged removal here, so
+            // do not let its otherwise-current receipt promote a child draft.
+            if (parent.queueRemoval)
+                return true;
+            // A parent that looks ready but has not completed its own one-PR receipt
+            // is not sufficient evidence for a child draft transition.
+            if (parent.readyReceipt !== true)
+                return true;
+        }
+        return false;
+    }
+    catch {
+        // Never convert a child draft based on an unverifiable parent.
+        return true;
+    }
+}