pr-shepherd 0.59.1 → 0.59.3

package/bin/commands/poll-summary-explicit-instructions.mjs

@@ -1,12 +1,24 @@
 import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
+import { isDraftReadinessVerification } from "./stack-work.mjs";
 /** Every selected row already returned `CANCEL` or `ESCALATE`: no autonomous work remains. */
 export function isHandedOffSelection(result) {
     return (result.prs.length > 0 &&
         result.prs.every((item) => item.action === "cancel" || item.action === "escalate"));
 }
+/** A final full-review probe can finish this selection without another aggregate read. */
+export function onlyDraftVerificationSelection(result) {
+    return (result.prs.some(isDraftReadinessVerification) &&
+        result.prs.every((item) => item.action === "cancel" ||
+            item.action === "escalate" ||
+            isDraftReadinessVerification(item)));
+}
 export function explicitInstructions(result) {
     if (result.reason === "all_terminal")
-        return ["1. Stop — every selected PR is terminal."];
+        return [
+            result.prs.some((item) => item.reasons.includes("draft-auto-mark-ready-disabled"))
+                ? "1. Stop — every selected PR is complete for this Shepherd run."
+                : "1. Stop — every selected PR is terminal.",
+        ];
     if (result.quotaWarning && result.reason !== "actionable") {
         return [
             buildQuotaAwareContinuation(result.quotaWarning, "1. This aggregate selection is non-terminal. Before continuing,"),
@@ -20,7 +32,11 @@ export function explicitInstructions(result) {
         "2. Follow each selected one-PR poll's `## Instructions` until it returns `CANCEL` or `ESCALATE`.",
         "3. Run this aggregate poll again after selected work completes; one row's `ESCALATE` does not stop work on other rows.",
     ];
-    if (isHandedOffSelection(result)) {
+    if (onlyDraftVerificationSelection(result)) {
+        instructions[2] =
+            "3. If every draft verification probe returns `[CANCEL]` with reason `auto-mark-ready-disabled`, stop this selection and report any `ESCALATE` rows; leave the drafts unchanged. If any probe returns `[ESCALATE]`, report that handoff and stop after the other probes finish. Otherwise follow the probes' instructions and rerun this aggregate selector when that work completes.";
+    }
+    else if (isHandedOffSelection(result)) {
         instructions[2] =
             "3. Stop after reporting each `ESCALATE` handoff; every selected row is `CANCEL` or `ESCALATE`, so do not run this aggregate poll again.";
     }

package/bin/commands/poll-summary-instructions.mjs

@@ -2,7 +2,7 @@
 import { buildQuotaAwareContinuation } from "../quota-warning.mjs";
 import { explicitInstructions } from "./poll-summary-explicit-instructions.mjs";
 import { appendAutonomousInstructions, appendHumanHandoffInstructions, findHumanHandoffs, idleWaitPlan, isStackLayerReady, planPrefixDrain, retargetWaitPlan, stackPosition, } from "./stack-drain.mjs";
-import { appendMarkReadyInstructions, appendStackRerunInstruction, splitStackWork, } from "./stack-work.mjs";
+import { appendStackRerunInstruction, onlyDraftReadinessVerification, splitStackWork, } from "./stack-work.mjs";
 /** Keep aggregate JSON, Markdown, and MCP instructions on one projection. */
 export function withPollSummaryInstructions(result, mergeRequested) {
     return planPollSummary(result, mergeRequested).result;
@@ -19,7 +19,8 @@ export function planPollSummary(result, mergeRequested) {
         prs: prs.map((item) => {
             const needsOwnSession = item.state === "OPEN" &&
                 (!isStackLayerReady(item) || staleChildren.has(item.pr)) &&
-                ["cancel", "merge"].includes(item.action);
+                ["cancel", "merge"].includes(item.action) &&
+                (!item.reasons.includes("draft-auto-mark-ready-disabled") || staleChildren.has(item.pr));
             const layer = needsOwnSession
                 ? {
                     ...item,
@@ -51,6 +52,11 @@ export function planPollSummary(result, mergeRequested) {
                     reasons: [...layer.reasons, "unverified-stack-state"],
                 };
             }
+            if (layer.reasons.includes("draft-auto-mark-ready-disabled") &&
+                !staleChildren.has(layer.pr)) {
+                const { pollCommand: _pollCommand, pollProbe: _pollProbe, ...held } = layer;
+                return held;
+            }
             return layer;
         }),
     };
@@ -84,9 +90,9 @@ function planStack(result, mergeRequested) {
     const work = splitStackWork(open.filter((item) => (!isStackLayerReady(item) || staleChildren.has(item.pr)) && item.action !== "escalate"), staleChildren);
     const runnableCandidates = work.sessions.filter((item) => item.pollCommand);
     const missingCommands = work.sessions.filter((item) => !item.pollCommand);
-    const agentWork = runnableCandidates.length > 0 || work.markReady.length > 0;
+    const agentWork = runnableCandidates.length > 0;
     // Only owned work defers a human handoff: rerunning cannot advance another author's layer.
-    const ownedWork = [...runnableCandidates, ...work.markReady].some((item) => item.owned);
+    const ownedWork = runnableCandidates.some((item) => item.owned);
     const drain = planPrefixDrain(result, mergeRequested);
     if (drain)
         return drain;
@@ -94,14 +100,17 @@ function planStack(result, mergeRequested) {
     if (handoffs) {
         const instructions = [];
         appendAutonomousInstructions(instructions, runnableCandidates);
-        appendMarkReadyInstructions(instructions, work.markReady);
         const stop = !ownedWork;
         appendHumanHandoffInstructions(instructions, handoffs, stop);
         for (const item of missingCommands) {
             instructions.push(`${instructions.length + 1}. PR #${item.pr} needs a one-PR session, but Shepherd could not produce its command. Ask for direction.`);
         }
         if (ownedWork) {
-            appendStackRerunInstruction(instructions, [...runnableCandidates, ...work.markReady], "After the listed one-PR sessions, rerun this same `--stack` selector. Stop for the human handoff only when no autonomous shepherding remains.");
+            const rerun = onlyDraftReadinessVerification(work.sessions, work.idle) &&
+                work.sessions.every((item) => item.owned)
+                ? "If every listed one-PR probe returns `[CANCEL]` with reason `auto-mark-ready-disabled`, report the human handoff above and stop this selector. If any probe returns `[ESCALATE]`, report that handoff and stop after the other probes finish. Otherwise follow each probe's instructions and rerun this same `--stack` selector when that work completes."
+                : "After the listed one-PR sessions, rerun this same `--stack` selector. Stop for the human handoff only when no autonomous shepherding remains.";
+            appendStackRerunInstruction(instructions, runnableCandidates, rerun);
         }
         return { action: stop ? "escalate" : "shepherd", stackMergeable: false, instructions };
     }
@@ -116,21 +125,34 @@ function planStack(result, mergeRequested) {
         if (missingCommands.length > 0) {
             const instructions = [];
             appendAutonomousInstructions(instructions, runnableCandidates);
-            appendMarkReadyInstructions(instructions, work.markReady);
             for (const item of missingCommands) {
                 instructions.push(`${instructions.length + 1}. PR #${item.pr} needs a one-PR session, but Shepherd could not produce its command. ${ownedWork ? "After autonomous shepherding, ask" : "Stop and ask"} for direction.`);
             }
             if (ownedWork) {
-                appendStackRerunInstruction(instructions, [...runnableCandidates, ...work.markReady], "After the listed one-PR sessions, rerun this same `--stack` selector. Stop for the human handoff only when no autonomous shepherding remains.");
+                appendStackRerunInstruction(instructions, runnableCandidates, "After the listed one-PR sessions, rerun this same `--stack` selector. Stop for the human handoff only when no autonomous shepherding remains.");
             }
             return { action: ownedWork ? "shepherd" : "escalate", stackMergeable: false, instructions };
         }
-        if (!agentWork)
+        if (!agentWork) {
+            if (work.held.length > 0 && work.idle.length === 0) {
+                return {
+                    action: "cancel",
+                    stackMergeable: false,
+                    instructions: [
+                        `1. Stop shepherding this stack. Automatic mark-ready is disabled and ${work.held.map((item) => `PR #${item.pr}`).join(", ")} ${work.held.length === 1 ? "is" : "are"} clean but still in draft.`,
+                    ],
+                };
+            }
             return idleWaitPlan(work.idle);
+        }
         const instructions = [];
         appendAutonomousInstructions(instructions, work.sessions);
-        appendMarkReadyInstructions(instructions, work.markReady);
-        const action = appendStackRerunInstruction(instructions, [...work.sessions, ...work.markReady], "After the selected one-PR sessions, rerun this same `--stack` selector.");
+        if (onlyDraftReadinessVerification(work.sessions, work.idle) &&
+            work.sessions.every((item) => item.owned)) {
+            instructions.push(`${instructions.length + 1}. If every listed one-PR probe returns \`[CANCEL]\` with reason \`auto-mark-ready-disabled\`, stop shepherding this stack and leave those drafts unchanged. If any probe returns \`[ESCALATE]\`, report that handoff and stop after the other probes finish. Otherwise follow each probe's instructions and rerun this same \`--stack\` selector when that work completes.`);
+            return { action: "shepherd", stackMergeable: false, instructions };
+        }
+        const action = appendStackRerunInstruction(instructions, work.sessions, "After the selected one-PR sessions, rerun this same `--stack` selector.");
         return { action, stackMergeable: false, instructions };
     }
     if (open.some((item) => item.isInMergeQueue)) {

package/bin/commands/rule-auto-resolve-format.d.mts

@@ -1,17 +1,5 @@
 import type { AutoMinimizedItem, AutoResolvedThread, RuleAutoResolveReport, ShepherdReport } from "../types.mts";
 export declare function uniqueReasons(reasons: readonly string[]): string[];
-export declare function reasonClause(reasons: readonly string[]): string | undefined;
-export declare function ruleAutoResolveBody(counts: {
-    threads: number;
-    comments: number;
-    reviewSummaries: number;
-}): string | undefined;
-export declare function formatRuleAutoResolveJournalItem(input: {
-    body: string;
-    reasons: readonly string[];
-    viewerLogin?: string;
-    urls: readonly string[];
-}): string;
 export declare function decorateAutoResolveError(error: string, reasons: readonly string[]): string;
 export declare function reasonsForError(error: string, ids: readonly string[], ruleReasons: ReadonlyMap<string, readonly string[]>): string[];
 export declare function ruleAutoResolveFromReport(report: ShepherdReport): RuleAutoResolveReport | undefined;

package/bin/commands/rule-auto-resolve-format.mjs

@@ -7,7 +7,7 @@ export function uniqueReasons(reasons) {
     }
     return unique;
 }
-export function reasonClause(reasons) {
+function reasonClause(reasons) {
     const unique = uniqueReasons(reasons);
     if (unique.length === 0)
         return undefined;
@@ -21,7 +21,7 @@ function joinedReason(reasons) {
 function plural(count, singular, pluralForm = `${singular}s`) {
     return `${count} ${count === 1 ? singular : pluralForm}`;
 }
-export function ruleAutoResolveBody(counts) {
+function ruleAutoResolveBody(counts) {
     const parts = [];
     if (counts.threads > 0)
         parts.push(`auto-resolved ${plural(counts.threads, "thread")}`);
@@ -39,15 +39,6 @@ function withReasonClause(body, reasons) {
     const clause = reasonClause(reasons);
     return clause ? `${body} ${clause}` : body;
 }
-export function formatRuleAutoResolveJournalItem(input) {
-    const login = input.viewerLogin?.trim();
-    const actor = login ? `as @${login}` : "(token login unavailable)";
-    const clause = reasonClause(input.reasons);
-    const links = input.urls.map((url) => url.trim()).filter(Boolean);
-    const reasonSuffix = clause ? ` ${clause}` : "";
-    const linkSuffix = links.length > 0 ? `: ${links.join(", ")}` : "";
-    return `- ${input.body} ${actor}${reasonSuffix}${linkSuffix}`;
-}
 export function decorateAutoResolveError(error, reasons) {
     const clause = reasonClause(reasons);
     return clause ? `${error} ${clause}` : error;

package/bin/commands/rule-auto-resolve.d.mts

@@ -13,9 +13,4 @@ export declare function applySuppressedRuleAutoResolve(input: {
     enabled: boolean;
     partition: BatchPartition;
     batch: BatchPrData;
-    prNumber: number;
-    repo: {
-        owner: string;
-        name: string;
-    };
 }): Promise<RuleAutoResolveApplied>;

package/bin/commands/rule-auto-resolve.mjs

@@ -1,7 +1,6 @@
 import { autoMinimizeComments, autoResolveThreads } from "../comments/resolve.mjs";
-import { runJournal } from "./journal/index.mjs";
 import { canGenerateGithubMutation } from "../github/mutation-policy.mjs";
-import { decorateAutoResolveError, formatRuleAutoResolveJournalItem, minimizedItem, reasonClause, reasonsForError, resolvedThread, ruleAutoResolveBody, uniqueReasons, } from "./rule-auto-resolve-format.mjs";
+import { decorateAutoResolveError, minimizedItem, reasonsForError, resolvedThread, uniqueReasons, } from "./rule-auto-resolve-format.mjs";
 const EMPTY = {
     threadIds: [],
     commentIds: [],
@@ -17,9 +16,6 @@ function idsIn(ids, confirmed) {
 function decorateErrors(errors, ids, ruleReasons) {
     return errors.map((error) => decorateAutoResolveError(error, reasonsForError(error, ids, ruleReasons)));
 }
-function successReasons(ids, ruleReasons) {
-    return uniqueReasons(ids.flatMap((id) => [...(ruleReasons.get(id) ?? [])]));
-}
 export async function applySuppressedRuleAutoResolve(input) {
     if (!input.enabled) {
         return {
@@ -70,9 +66,6 @@ export async function applySuppressedRuleAutoResolve(input) {
         ...minimized.errors.flatMap((error) => reasonsForError(error, minimizeIds, input.partition.ruleReasons)),
         ...resolved.errors.flatMap((error) => reasonsForError(error, threadIds, input.partition.ruleReasons)),
     ]);
-    const journalError = await journalSuccesses(input, autoResolved, autoMinimized);
-    if (journalError)
-        autoResolveErrors.push(journalError);
     return {
         threadIds: input.partition.ruleAutoResolveThreadIds.filter((id) => !resolvedSet.has(id)),
         commentIds: input.partition.ruleAutoResolveCommentIds.filter((id) => !minimizedSet.has(id)),
@@ -83,37 +76,3 @@ export async function applySuppressedRuleAutoResolve(input) {
         errorReasons,
     };
 }
-async function journalSuccesses(input, autoResolved, autoMinimized) {
-    const body = ruleAutoResolveBody({
-        threads: autoResolved.length,
-        comments: autoMinimized.filter((item) => item.kind === "pr-comment").length,
-        reviewSummaries: autoMinimized.filter((item) => item.kind === "review-summary").length,
-    });
-    if (!body)
-        return undefined;
-    const ids = [...autoResolved.map((thread) => thread.id), ...autoMinimized.map((item) => item.id)];
-    const reasons = successReasons(ids, input.partition.ruleReasons);
-    const item = formatRuleAutoResolveJournalItem({
-        body,
-        reasons,
-        ...(input.batch.viewerLogin ? { viewerLogin: input.batch.viewerLogin } : {}),
-        urls: [
-            ...autoResolved.map((thread) => thread.url),
-            ...autoMinimized.map((item) => item.url ?? ""),
-        ],
-    });
-    try {
-        await runJournal({
-            prNumber: input.prNumber,
-            targetRepository: { owner: input.repo.owner, name: input.repo.name },
-            rawItem: item,
-            dryRun: false,
-        });
-        return undefined;
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        const clause = reasonClause(reasons);
-        return clause ? `journal: ${message} ${clause}` : `journal: ${message}`;
-    }
-}

package/bin/commands/shepherd-journal.d.mts

@@ -4,12 +4,3 @@ export declare const SHEPHERD_JOURNAL_DETAILS_OPEN = "<details>";
 export declare const SHEPHERD_JOURNAL_DETAILS_SUMMARY = "<summary>Shepherd Journal</summary>";
 export declare const SHEPHERD_JOURNAL_DETAILS_CLOSE = "</details>";
 export declare const SHEPHERD_JOURNAL_APPEND_HINT = "If Shepherd Journal details already exist, append entries inside them instead of creating another container.";
-export declare const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = "Read each body under `## Review summaries (first look)` and journal any warranted note before review mutations.";
-/** The concrete `apply journal` command. The placeholder is single-quoted so a substituted decision stays literal in the shell. */
-export declare function buildShepherdJournalCommand(prReference: string | number): string;
-/**
- * Build the Shepherd Journal instruction step. The reference-citation convention (link
- * threads/comments by heading URL, cite reviews by ID) is a short clause, so it stays inline:
- * a separate playbook would cost the agent an extra read turn that outweighs the clause.
- */
-export declare function buildShepherdJournalInstruction(prReference: string | number): string;

package/bin/commands/shepherd-journal.mjs

@@ -1,21 +1,6 @@
-import { buildPrShepherdCommand } from "../cli/runner.mjs";
 export const SHEPHERD_JOURNAL_SECTION = "Shepherd Journal";
 export const SHEPHERD_JOURNAL_SECTION_PATTERN = /^##\s+Shepherd\s+Journal$/;
 export const SHEPHERD_JOURNAL_DETAILS_OPEN = "<details>";
 export const SHEPHERD_JOURNAL_DETAILS_SUMMARY = "<summary>Shepherd Journal</summary>";
 export const SHEPHERD_JOURNAL_DETAILS_CLOSE = "</details>";
 export const SHEPHERD_JOURNAL_APPEND_HINT = "If Shepherd Journal details already exist, append entries inside them instead of creating another container.";
-export const SHEPHERD_JOURNAL_FIRST_LOOK_GUIDANCE = `Read each body under \`## Review summaries (first look)\` and journal any warranted note before review mutations.`;
-/** The concrete `apply journal` command. The placeholder is single-quoted so a substituted decision stays literal in the shell. */
-export function buildShepherdJournalCommand(prReference) {
-    return `${buildPrShepherdCommand(["apply", "journal", String(prReference)]).text} '- <decision>'`;
-}
-/**
- * Build the Shepherd Journal instruction step. The reference-citation convention (link
- * threads/comments by heading URL, cite reviews by ID) is a short clause, so it stays inline:
- * a separate playbook would cost the agent an extra read turn that outweighs the clause.
- */
-export function buildShepherdJournalInstruction(prReference) {
-    const command = buildShepherdJournalCommand(prReference);
-    return `Journal key decisions or rejections with URLs or IDs: \`${command}\``;
-}

package/bin/commands/stack-drain.mjs

@@ -2,7 +2,7 @@ import { findHumanHandoffs, appendHumanHandoffInstructions } from "./stack-hando
 export { findHumanHandoffs, appendHumanHandoffInstructions } from "./stack-handoffs.mjs";
 import { stackMergeFlag } from "./stack-merge-flag.mjs";
 import { stackLayerBlockReason } from "./stack-layer-readiness.mjs";
-import { appendMarkReadyInstructions, splitStackWork } from "./stack-work.mjs";
+import { splitStackWork } from "./stack-work.mjs";
 import { getGithubTransport } from "../github/transport.mjs";
 import { buildMergeCommandPlan, renderMergeCommand } from "./iterate/merge.mjs";
 function readyPrefixTop(result) {
@@ -89,7 +89,6 @@ export function planPrefixDrain(result, mergeRequested) {
         instructions[0] = `1. PR #${top.pr} is the highest open layer of stack #${top.stack.number} in \`${result.repo}\` whose open lower layers are all ready. Run \`GH_REPO=${result.repo} gh stack merge ${top.pr} --yes ${method.flag}\` to merge ${span}. If \`gh stack\` is an unknown command, run \`gh extension install github/gh-stack\`, then rerun that merge command. Do not rebase, push, or run \`gh stack push\`.`;
     }
     appendAutonomousInstructions(instructions, above.sessions);
-    appendMarkReadyInstructions(instructions, above.markReady);
     const handoffs = findHumanHandoffs(result);
     if (handoffs)
         appendHumanHandoffInstructions(instructions, handoffs, false);

package/bin/commands/stack-work.d.mts

@@ -1,37 +1,24 @@
 import type { PollSummaryItem } from "../types.mts";
-type ProbedLayer = PollSummaryItem & {
-    pollCommand: string;
-    pollProbe: true;
-};
-/**
- * The one-PR hold reason for a `READY` draft that only the disabled setting keeps in draft. The
- * probe re-reads the draft, so this phrase, not a bare `[WAIT]`, proves it is still clean.
- */
-export declare const AUTO_MARK_READY_DISABLED_HOLD = "automatic mark-ready is disabled for this session";
 /** How the stack selector routes the autonomous layers that still need work. */
 export interface StackWork {
     /** Layers that need a one-PR Shepherd session, with or without a known command. */
     sessions: PollSummaryItem[];
-    /** Clean, unblocked drafts that the agent marks ready because the poll loop will not. */
-    markReady: ProbedLayer[];
+    /** Clean drafts held by the disabled ready transition. No more work is scheduled for them. */
+    held: PollSummaryItem[];
     /** Layers whose bounded probe could only report that they are still waiting. */
-    idle: ProbedLayer[];
+    idle: PollSummaryItem[];
 }
+export declare function isDraftReadinessVerification(item: PollSummaryItem): boolean;
+/** A full one-PR check is the final task when the compact review sample was incomplete. */
+export declare function onlyDraftReadinessVerification(sessions: PollSummaryItem[], idle: PollSummaryItem[]): boolean;
 /**
- * Split autonomous stack candidates by what the agent can do for each. A bounded probe cannot
- * mark a draft ready, so rerunning it for a waiting layer cannot change the stack. A probed wait
- * kept in draft only by the disabled mark-ready setting is the agent's ready-for-review step.
+ * Split autonomous stack candidates by what the agent can do for each. A clean draft held by
+ * disabled mark-ready is complete for this run. Other bounded waits stay idle.
  * A stale-ancestry child keeps its session, which returns the ancestry repair.
  */
 export declare function splitStackWork(candidates: PollSummaryItem[], staleChildren: ReadonlySet<number>): StackWork;
-/**
- * The poll loop leaves a disabled draft's ready transition to the agent. The bounded probe runs
- * first because only the one-PR session reads the full review context.
- */
-export declare function appendMarkReadyInstructions(instructions: string[], layers: ProbedLayer[]): void;
 /**
  * The closing step after routed sessions: rerun the selector, or stop when nothing is owned.
  * Returns the plan action: a stop is a handoff, so no rerun, quota cadence, or wake-up follows it.
  */
 export declare function appendStackRerunInstruction(instructions: string[], layers: PollSummaryItem[], rerun: string): "shepherd" | "escalate";
-export {};

package/bin/commands/stack-work.mjs

@@ -1,24 +1,23 @@
-import { buildPrShepherdCommand } from "../cli/runner.mjs";
-import { formatPrUrl } from "../pr-reference.mjs";
-/**
- * The one-PR hold reason for a `READY` draft that only the disabled setting keeps in draft. The
- * probe re-reads the draft, so this phrase, not a bare `[WAIT]`, proves it is still clean.
- */
-export const AUTO_MARK_READY_DISABLED_HOLD = "automatic mark-ready is disabled for this session";
+export function isDraftReadinessVerification(item) {
+    return item.reasons?.includes("draft-readiness-verification-required") === true;
+}
+/** A full one-PR check is the final task when the compact review sample was incomplete. */
+export function onlyDraftReadinessVerification(sessions, idle) {
+    return sessions.length > 0 && idle.length === 0 && sessions.every(isDraftReadinessVerification);
+}
 /**
- * Split autonomous stack candidates by what the agent can do for each. A bounded probe cannot
- * mark a draft ready, so rerunning it for a waiting layer cannot change the stack. A probed wait
- * kept in draft only by the disabled mark-ready setting is the agent's ready-for-review step.
+ * Split autonomous stack candidates by what the agent can do for each. A clean draft held by
+ * disabled mark-ready is complete for this run. Other bounded waits stay idle.
  * A stale-ancestry child keeps its session, which returns the ancestry repair.
  */
 export function splitStackWork(candidates, staleChildren) {
-    const work = { sessions: [], markReady: [], idle: [] };
+    const work = { sessions: [], held: [], idle: [] };
     for (const item of candidates) {
-        if (!isProbed(item) || item.action !== "wait" || staleChildren.has(item.pr)) {
-            work.sessions.push(item);
+        if (item.reasons.includes("draft-auto-mark-ready-disabled") && !staleChildren.has(item.pr)) {
+            work.held.push(item);
         }
-        else if (item.reasons.includes("draft-auto-mark-ready-disabled")) {
-            work.markReady.push(item);
+        else if (!isProbed(item) || item.action !== "wait" || staleChildren.has(item.pr)) {
+            work.sessions.push(item);
         }
         else {
             work.idle.push(item);
@@ -26,29 +25,6 @@ export function splitStackWork(candidates, staleChildren) {
     }
     return work;
 }
-/**
- * The poll loop leaves a disabled draft's ready transition to the agent. The bounded probe runs
- * first because only the one-PR session reads the full review context.
- */
-export function appendMarkReadyInstructions(instructions, layers) {
-    for (const item of layers) {
-        if (!item.owned) {
-            instructions.push(`${instructions.length + 1}. PR #${item.pr} is not owned. Leave its draft state unchanged.`);
-            continue;
-        }
-        if (item.transport === "rest") {
-            const command = buildPrShepherdCommand([
-                "iterate",
-                formatPrUrl(item.repo, item.pr),
-                "--transport",
-                "rest",
-            ]).text;
-            instructions.push(`${instructions.length + 1}. Run \`${item.pollCommand}\` first for PR #${item.pr}. If it returns \`[WAIT]\` saying the draft is held only because automatic mark-ready is disabled, run \`${command}\` to authorize the CCR ready transition; otherwise follow the probe's instructions.`);
-            continue;
-        }
-        instructions.push(`${instructions.length + 1}. Automatic mark-ready is disabled, so marking PR #${item.pr} ready for review is your step. Run \`${item.pollCommand}\` first. If it returns \`[WAIT]\` saying PR #${item.pr} stays in draft because ${AUTO_MARK_READY_DISABLED_HOLD}, run \`gh pr ready ${item.pr} -R ${item.repo}\`; otherwise complete its instructions and leave PR #${item.pr} in draft this round.`);
-    }
-}
 function isProbed(item) {
     return item.pollProbe === true && item.pollCommand !== undefined;
 }

package/bin/config/load.d.mts

@@ -81,8 +81,8 @@ export interface PrShepherdConfig {
          */
         resolveOtherHumanThreads: ResolveOtherHumanThreads;
         /**
-         * `inline` (default) prints the commit/push and journal steps of `fix_code` instructions
-         * every tick; `playbook` folds them into one `Playbook: "Fix-code loop"` pointer. The
+         * `inline` (default) prints the commit/push step of `fix_code` instructions
+         * every tick; `playbook` folds it into one `Playbook: "Fix-code loop"` pointer. The
          * default is inline because the token bench measured playbook as a net cost: it adds a read. The `--instructions` flag and MCP `instructions` input override per call.
          */
         instructions: InstructionStyle;

package/bin/exit-codes.d.mts

@@ -12,7 +12,7 @@
 import type { IterateResult } from "./types.mts";
 import type { ResolveResult } from "./comments/resolve.mts";
 export declare const EXIT: Readonly<{
-    /** `cancel` + `merged` or `ready-delay-elapsed` — shepherd finished cleanly. */
+    /** Clean terminal stop, including a draft held by disabled automatic mark-ready. */
     readonly OK: 0;
     /** Nothing to do yet, or a clean PR whose ready-delay is still counting. */
     readonly WAIT: 10;

package/bin/exit-codes.mjs

@@ -10,7 +10,7 @@
  * ran to completion and is reporting PR state. See docs/exit-codes.md.
  */
 export const EXIT = Object.freeze({
-    /** `cancel` + `merged` or `ready-delay-elapsed` — shepherd finished cleanly. */
+    /** Clean terminal stop, including a draft held by disabled automatic mark-ready. */
     OK: 0,
     /** Nothing to do yet, or a clean PR whose ready-delay is still counting. */
     WAIT: 10,
@@ -55,6 +55,7 @@ export class ShepherdError extends Error {
 const CANCEL_REASON_EXIT_CODE = {
     merged: EXIT.OK,
     "ready-delay-elapsed": EXIT.OK,
+    "auto-mark-ready-disabled": EXIT.OK,
     closed: EXIT.CLOSED,
 };
 export function iterateResultToExitCode(result) {

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

@@ -28,7 +28,9 @@ export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdministe
     let remainingSeconds;
     if (raw.isDraft &&
         blockingReviewerInProgress &&
-        (action === "mark_ready" || reasons.includes("draft-auto-mark-ready-disabled"))) {
+        (action === "mark_ready" ||
+            reasons.includes("draft-auto-mark-ready-disabled") ||
+            reasons.includes("draft-readiness-verification-required"))) {
         action = "wait";
         reasons = ["blocking-reviewer-in-progress"];
     }

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

@@ -40,18 +40,17 @@ export function routePollSummary(raw, checks, review, opts) {
     }
     if (raw.isDraft) {
         const autoMarkReadyDisabled = opts.noAutoMarkReady || actions.autoMarkReady === false;
-        // The stack selector asks the agent to mark a disabled draft ready, so
-        // that transition needs the same capability as the automatic one.
-        if (!canGenerateGithubMutation(raw.viewerCanUpdate, "ready") &&
-            (!autoMarkReadyDisabled || opts.stackPrNumber !== undefined)) {
+        if (autoMarkReadyDisabled && (checks.incomplete || review.incomplete))
+            return { action: "fix_code", reasons: ["draft-readiness-verification-required"] };
+        if (autoMarkReadyDisabled)
+            return { action: "cancel", reasons: ["draft-auto-mark-ready-disabled"] };
+        if (!canGenerateGithubMutation(raw.viewerCanUpdate, "ready")) {
             const unsupported = getGithubTransport() === "rest" && raw.viewerCanUpdate !== false && !isCcrTransport();
             if (unsupported)
                 return { action: "escalate", reasons: ["transport-unsupported"] };
             return { action: "escalate", reasons: ["mark-ready-authorization-required"] };
         }
-        return autoMarkReadyDisabled
-            ? { action: "wait", reasons: ["draft-auto-mark-ready-disabled"] }
-            : { action: "mark_ready", reasons: ["draft-appears-ready"] };
+        return { action: "mark_ready", reasons: ["draft-appears-ready"] };
     }
     if (opts.merge && (raw.isInMergeQueue || raw.autoMergeRequest)) {
         return {

package/bin/mcp/server.mjs

@@ -33,7 +33,7 @@ const iterateInputSchema = z
     instructions: z
         .enum(["playbook", "inline"])
         .optional()
-        .describe("fix_code instruction style. inline (default) prints every step each tick; playbook folds commit, push and journal into the Fix-code loop playbook."),
+        .describe("fix_code instruction style. inline (default) prints every step each tick; playbook folds commit and push into the Fix-code loop playbook."),
     pollMode: z
         .enum(["auto", "poll", "event"])
         .optional()

package/bin/types/iterate.d.mts

@@ -1,7 +1,7 @@
 import type { AgentThread, AgentComment, AgentCheck, GlobalOptions, RelevantCheck, ShepherdStatus, FirstLookThread, FirstLookComment, RuleAutoResolveReport } from "./report.mts";
 import type { ActiveCheck, PrActivitySummary } from "./activity.mts";
 import type { BranchProtection, MergeStateStatus, MergedBasePullRequest, Review, ReviewDecision, ReviewThread, ShepherdMergeStatus } from "./github.mts";
-import type { MergeRequirements, StackDraftHold } from "./merge-requirements.mts";
+import type { MergeRequirements } from "./merge-requirements.mts";
 import type { EscalateDetails } from "./escalate.mts";
 import type { MergeCommandPlan } from "./merge-action.mts";
 import type { ProtectedRun } from "./protected-run.mts";
@@ -75,14 +75,13 @@ interface IterateResultWait extends IterateResultBase {
     action: "wait";
     log: string;
     deferredWork?: import("./merge-queue.mts").IterateDeferredWork;
-    stackDraftHold?: StackDraftHold;
 }
 /** Clean PR whose ready-delay is still counting. `--until-terminal` returns this instead of sleeping. */
 interface IterateResultReady extends IterateResultBase {
     action: "ready";
     log: string;
 }
-export type CancelReason = "merged" | "closed" | "ready-delay-elapsed";
+export type CancelReason = "merged" | "closed" | "ready-delay-elapsed" | "auto-mark-ready-disabled";
 interface IterateResultCancel extends IterateResultBase {
     action: "cancel";
     reason: CancelReason;

package/bin/types/merge-requirements.d.mts

@@ -41,13 +41,6 @@ export interface StackStatus {
 }
 /** Why an open native stack layer is not ready to merge. */
 export type StackLayerBlockReason = "closed" | "draft" | "conflicting" | "queue-removal" | "failing-checks" | "review-work" | "checks-in-progress" | "merge-state" | "no-ready-receipt" | "stale-ancestry";
-/**
- * A native stack draft stays in draft on a WAIT tick because this session will not
- * mark it ready. The caller returns to the stack selector.
- */
-export type StackDraftHold = {
-    kind: "auto-mark-ready-disabled";
-};
 /** Extra batch-PR fields for merge-queue, stacks, and folded branch rules. */
 export interface BatchPrMergeFields {
     branchRules?: BranchRules;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.59.1",
+  "version": "0.59.3",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

package/plugins/pr-shepherd/.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.59.1",
+  "version": "0.59.3",
   "author": {
     "name": "Jonathan Ong",
     "email": "jonathanrichardong@gmail.com"

package/plugins/pr-shepherd/.codex-plugin/plugin.json

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

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

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