@mgiles/perk 3.1.0 → 3.2.0

package/extension/doors/plannotatorHandoff.ts

@@ -372,6 +372,57 @@ export function respondMessage(outcome: CodeReviewOutcome): string | null {
   return parts.join("\n\n");
 }
 
+/**
+ * The stack-flow respond → injection mapping (`/stack-review-browser`): the same arms as
+ * `respondMessage`, re-worded for the stack posting policy — a local-diff session has NO
+ * attached PR, so the browser posted nothing and ALL GitHub posting is perk-side after triage
+ * (per-PR, judgment-routed, human-approved). Returned annotations are treated as COMBINED-DIFF
+ * coordinates (stack base → top head).
+ */
+export function stackRespondMessage(outcome: CodeReviewOutcome): string | null {
+  if (outcome.status !== "handled") return null;
+  if (outcome.exit) {
+    return (
+      "The human closed the plannotator review without submitting — ask them how they want " +
+      "to proceed."
+    );
+  }
+  if (outcome.approved && outcome.annotations.length === 0) {
+    return (
+      "The human approved the stack review in plannotator (no annotations) — the review is " +
+      "complete. This local-diff session has no attached PR, so nothing was posted from the " +
+      "browser: ask the human whether they want per-PR COMMENT reviews posted (the routing + " +
+      "per-PR posting protocol via `submit_pr_review`) or nothing — perk posts only what the " +
+      "human approves."
+    );
+  }
+  const parts: string[] = [outcome.feedback ?? "The plannotator stack review returned."];
+  if (outcome.annotations.length > 0) {
+    parts.push(`\`\`\`json\n${JSON.stringify(outcome.annotations, null, 2)}\n\`\`\``);
+    parts.push(
+      "These annotations are in COMBINED-DIFF coordinates (stack base → top head): " +
+        "source-less ones are human-authored; `perk:*`-badged ones are your own findings " +
+        "returning. This local-diff session has no attached PR — nothing was posted from the " +
+        "browser, so ALL GitHub posting is perk-side: run the routing + per-PR posting " +
+        "protocol from the guidance (route each finding to the PR that introduced it over the " +
+        "per-PR diffs, sanity-check each quoted context against the target PR's diff, dry-run " +
+        "ALL per-PR batches first, then post bottom→top via `submit_pr_review`) — posting only " +
+        "what the human approves.",
+    );
+  } else {
+    // Feedback without annotations still needs the stack posting framing — the human may
+    // expect their words to reach GitHub, and nothing was posted from the browser.
+    parts.push(
+      "No annotations came back with this feedback. This local-diff session has no attached " +
+        "PR — nothing was posted from the browser, so any GitHub posting stays perk-side: if " +
+        "the feedback warrants per-PR reviews, run the guidance's routing + per-PR posting " +
+        "protocol (dry-run ALL per-PR batches first, then post bottom→top via " +
+        "`submit_pr_review`) — posting only what the human approves.",
+    );
+  }
+  return parts.join("\n\n");
+}
+
 /** The minimal message sink `routeBrowserRespond` needs (an `ExtensionAPI` slice). */
 export interface RespondSink {
   sendUserMessage(content: string, options?: { deliverAs?: "steer" | "followUp" }): void;
@@ -379,20 +430,24 @@ export interface RespondSink {
 
 /**
  * Route a settled PR-mode respond into the session (the idle-vs-streaming injection route),
- * shared by `/pr-review-browser`'s PR modes. `scope` is the invoking surface's report scope.
+ * shared by `/pr-review-browser`'s PR modes and `/stack-review-browser`. `scope` is the
+ * invoking surface's report scope; `messageFor` is the injectable respond → message mapper
+ * (default `respondMessage` — the single-PR posting contract; the stack flow supplies
+ * `stackRespondMessage`).
  */
 export function routeBrowserRespond(
   pi: RespondSink,
   ctx: ReportTarget & Pick<ExtensionContext, "isIdle">,
   out: CodeReviewOutcome,
   scope: string,
+  messageFor: (outcome: CodeReviewOutcome) => string | null = respondMessage,
 ): void {
   if (out.status === "unavailable" || out.status === "error") {
     // Degrade-mid-flow: the flow continues in-session (findings table; posting unchanged).
     report(ctx, scope, "error", out.warning, { alsoLog: true });
     return;
   }
-  const message = respondMessage(out);
+  const message = messageFor(out);
   if (message === null) return; // aborted: the turn was interrupted — no-op
   if (ctx.isIdle()) {
     pi.sendUserMessage(message);
@@ -539,18 +594,35 @@ async function startPlannotatorSurface<T>(
 
 /**
  * The composable code-review browser open: the engine with launch = the `code-review` bridge
- * request (the PR-mode payload `{prUrl, cwd}` byte-for-byte — plannotator's defaults, including
- * its own local checkout for Ask AI / Full-stack: deliberately NOT `useLocal: false`, the human
- * chose the full surface) and the `/api/diff` readiness route (`bridgePromise` is the single
- * respond — code-review has no handshake).
+ * request and the `/api/diff` readiness route (`bridgePromise` is the single respond —
+ * code-review has no handshake). PR mode passes `{prUrl, cwd}` — the payload stays
+ * byte-identical to the original shape because the optional local-mode fields (`diffType`,
+ * `defaultBranch`) render ONLY when defined (`requestPlannotatorCodeReview` builds the payload
+ * conditionally). The stack door supplies the local-mode trio
+ * `{cwd, diffType: "since-base", defaultBranch: "origin/<stack base>"}` instead of a PR URL.
+ * Plannotator's defaults are otherwise untouched (deliberately NOT `useLocal: false` — the
+ * human chose the full surface).
  */
 export async function startPlannotatorBrowser(
   bus: PlannotatorBus,
-  opts: { prUrl: string; cwd: string; signal?: AbortSignal },
+  opts: {
+    cwd: string;
+    prUrl?: string;
+    diffType?: string;
+    defaultBranch?: string;
+    signal?: AbortSignal;
+  },
   deps: StartBrowserDeps = {},
 ): Promise<StartedBrowser> {
   return await startPlannotatorSurface(
-    (signal) => requestPlannotatorCodeReview(bus, { prUrl: opts.prUrl, cwd: opts.cwd, signal }),
+    (signal) =>
+      requestPlannotatorCodeReview(bus, {
+        cwd: opts.cwd,
+        ...(opts.prUrl !== undefined ? { prUrl: opts.prUrl } : {}),
+        ...(opts.diffType !== undefined ? { diffType: opts.diffType } : {}),
+        ...(opts.defaultBranch !== undefined ? { defaultBranch: opts.defaultBranch } : {}),
+        ...(signal !== undefined ? { signal } : {}),
+      }),
     CODE_REVIEW_READINESS_PROBE_PATH,
     opts.signal,
     deps,

package/extension/doors/prReview.ts

@@ -21,7 +21,8 @@
 // (soft `details.ok`, mirrors resolveReviewThreads). This is documented in shared/contracts.md §8.3.
 //
 // The review model is configurable via `[models.subagents] pr-reviewer` in `.perk/config.toml`; because
-// `subagents.agentOverrides` does NOT reach project agents, `run_pr_review_wave` applies that model
+// an `agentOverrides` model can never displace a perk def's frontmatter-pinned `model:` (the ≥0.52
+// custom-agent override path is a frontmatter-sensitive fill), `run_pr_review_wave` applies that model
 // as the wave's workflow-level `model` default applied to every lane (the agent's frontmatter model
 // is the default).
 //

package/extension/doors/prReviewBrowser.ts

@@ -45,6 +45,7 @@ import { type ReportTarget, report } from "../surfaces/report.ts";
 import { clearAnnotationSurface, primeAnnotationSurface } from "./annotationPush.ts";
 import { type CheckoutOk, decodeCheckout } from "./hunkHandoff.ts";
 import {
+  type CodeReviewOutcome,
   decodePrUrl,
   LOCAL_REVIEW_DIFF_TYPE,
   plannotatorPresent,
@@ -95,8 +96,9 @@ export function prReviewBrowserGuidance(opts: PrReviewBrowserGuidanceOpts): stri
 /**
  * The degrade notice injected when the browser never comes up — the model renders the findings
  * in-session and runs the same triage conversationally; the posting contract is unchanged.
+ * Exported as the `openReviewBrowserCore` default (the stack door supplies its own).
  */
-const DEGRADE_NOTICE =
+export const DEGRADE_NOTICE =
   "The plannotator browser review is unavailable (the review server never became ready) — " +
   "degrade in-session: render the reviewers' reconciled findings as a table in your reply and " +
   "run the same triage loop conversationally. The annotation surface is cleared — " +
@@ -116,10 +118,13 @@ export async function observeBrowserReadiness(
   pi: RespondSink,
   ctx: ReportTarget & Pick<ExtensionContext, "isIdle">,
   started: StartedBrowser,
+  opts?: { scope?: string; degradeNotice?: string },
 ): Promise<void> {
+  const scope = opts?.scope ?? SCOPE;
+  const degradeNotice = opts?.degradeNotice ?? DEGRADE_NOTICE;
   const state = await started.readiness;
   if (state === "ready") {
-    report(ctx, SCOPE, "info", `plannotator is up at ${started.url} — browser opening`);
+    report(ctx, scope, "info", `plannotator is up at ${started.url} — browser opening`);
     return;
   }
   if (state === "aborted") return; // the turn was interrupted — no-op
@@ -129,71 +134,95 @@ export async function observeBrowserReadiness(
   }
   report(
     ctx,
-    SCOPE,
+    scope,
     "error",
     `the plannotator review server did not become ready at ${started.url} — the browser ` +
       "review is unavailable",
     { alsoLog: true },
   );
   if (ctx.isIdle()) {
-    pi.sendUserMessage(DEGRADE_NOTICE);
+    pi.sendUserMessage(degradeNotice);
   } else {
-    pi.sendUserMessage(DEGRADE_NOTICE, { deliverAs: "followUp" });
+    pi.sendUserMessage(degradeNotice, { deliverAs: "followUp" });
   }
   // Consistent with "render findings in-session": a post-degrade push_annotations refuses
   // loudly (`no_surface`). Idempotent beside the bridge-settle clear.
   clearAnnotationSurface();
 }
 
+/** The parameterized browser-lifecycle core's options (see `openReviewBrowserCore`). */
+export interface ReviewBrowserCoreOpts {
+  /** The invoking door's report scope. */
+  scope: string;
+  /** The `startPlannotatorBrowser` opts minus `signal` (the core threads `ctx.signal`). */
+  browserOpts: { cwd: string; prUrl?: string; diffType?: string; defaultBranch?: string };
+  /** The fully composed guidance to inject (binding suffix included by the caller). */
+  guidance: string;
+  /** The degrade notice for the browser-never-ready arm (default: the PR-mode notice). */
+  degradeNotice?: string;
+  /** The respond → injection mapper (default: `respondMessage` — the single-PR contract). */
+  respondMessageFor?: (outcome: CodeReviewOutcome) => string | null;
+  /**
+   * Whether the core injects `guidance` as a user message at the end (default true — the warm
+   * doors). The `open_stack_review` tool passes false and returns the guidance as its ok text
+   * instead (the tool result is the seeded session's delivery channel).
+   */
+  injectGuidance?: boolean;
+}
+
 /**
- * The shared PR-mode arm (foreign + active): start the browser open in the background, inject
- * the mode guidance immediately (the URL is deterministic once the port is picked), and return —
- * the readiness observation and the bridge respond both ride background tasks. While plannotator
- * sets up, its in-process `console.error` chatter re-routes through the TUI-safe report() seam
- * (the debounce restores once setup goes quiet, with the `finally` as a backstop).
+ * The full browser-lifecycle core, extracted from the PR-mode arm and parameterized for the
+ * stack door: start the browser open in the background, prime the annotation surface the
+ * moment the port is picked (push_annotations now serves this browser session), observe
+ * readiness in the background (degrade notice on never-ready), route the bridge respond
+ * through the injectable mapper, clear the surface on settle, and inject the guidance
+ * immediately (the URL is deterministic once the port is picked). While plannotator sets up,
+ * its in-process `console.error` chatter re-routes through the TUI-safe report() seam (the
+ * debounce restores once setup goes quiet, with the `finally` as a backstop).
+ *
+ * Accepted stale-clear edge (unchanged from the pre-extraction arm): a second browser door
+ * while this browser is still open re-primes (a new browser session supersedes everything),
+ * and THIS bridge's later settle would clear the second session's surface — rare and loud
+ * (the fixed-port EADDRINUSE caveat, contracts §8.4), noted, not engineered around.
  */
-async function openBrowserAndGuide(
+export async function openReviewBrowserCore(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
-  opts: PrReviewBrowserGuidanceOpts,
-): Promise<void> {
+  opts: ReviewBrowserCoreOpts,
+): Promise<boolean> {
   let started: StartedBrowser;
   try {
     started = await startPlannotatorBrowser(pi.events, {
-      prUrl: opts.prUrl,
-      cwd: ctx.cwd,
+      ...opts.browserOpts,
       signal: ctx.signal,
     });
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error);
     report(
       ctx,
-      SCOPE,
+      opts.scope,
       "error",
       `could not pick a free local port for the plannotator review server: ${detail}`,
       { alsoLog: true },
     );
-    return;
+    return false;
   }
 
-  // Prime the annotation surface the moment the port is picked (the URL is deterministic — see
-  // the background-open header note): push_annotations now serves this browser session. Accepted
-  // stale-clear edge: a second /pr-review-browser while this browser is still open re-primes (a
-  // new browser session supersedes everything), and THIS bridge's later settle would clear the
-  // second session's surface — the overlap is already rare and loud (the fixed-port EADDRINUSE
-  // caveat, contracts §8.4), so it is noted, not engineered around.
   primeAnnotationSurface({ mode: "review", url: started.url });
 
-  void observeBrowserReadiness(pi, ctx, started);
+  void observeBrowserReadiness(pi, ctx, started, {
+    scope: opts.scope,
+    ...(opts.degradeNotice !== undefined ? { degradeNotice: opts.degradeNotice } : {}),
+  });
 
   void (async () => {
-    const interceptor = interceptConsoleError((line) => report(ctx, SCOPE, "info", line), {
+    const interceptor = interceptConsoleError((line) => report(ctx, opts.scope, "info", line), {
       // plannotator can pause up to ~4s between setup lines — keep the quiet window above that.
       quietMs: 6000,
     });
     try {
       const out = await started.bridgePromise;
-      routeBrowserRespond(pi, ctx, out, SCOPE);
+      routeBrowserRespond(pi, ctx, out, opts.scope, opts.respondMessageFor);
     } finally {
       // The browser session is over — drop the surface so a later push refuses (`no_surface`).
       clearAnnotationSurface();
@@ -201,7 +230,26 @@ async function openBrowserAndGuide(
     }
   })();
 
-  pi.sendUserMessage(prReviewBrowserGuidance(opts) + bindingSuffix(ctx.cwd, `command:${SCOPE}`));
+  if (opts.injectGuidance !== false) pi.sendUserMessage(opts.guidance);
+  return true;
+}
+
+/**
+ * The shared PR-mode arm (foreign + active): the extracted core with this door's values —
+ * PR-mode browser opts, the mode guidance + binding suffix, and the default degrade notice /
+ * respond mapper (the byte-stability of the pre-extraction behavior is proven by this door's
+ * untouched tests).
+ */
+async function openBrowserAndGuide(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  opts: PrReviewBrowserGuidanceOpts,
+): Promise<void> {
+  await openReviewBrowserCore(pi, ctx, {
+    scope: SCOPE,
+    browserOpts: { prUrl: opts.prUrl, cwd: ctx.cwd },
+    guidance: prReviewBrowserGuidance(opts) + bindingSuffix(ctx.cwd, `command:${SCOPE}`),
+  });
 }
 
 // ------------------------------------------------------------------------ registration

package/extension/doors/ready.ts

@@ -1,10 +1,17 @@
-// The warm `/ready` door: the deliberate draft→ready review gate. The in-session twin
-// of the Python cold door (`perk pr ready`): a terminating tool + command that DELEGATE the GitHub
-// mark-ready (mutations canonical in Python). perk deliberately does NOT auto-publish on
-// submit; `/ready` is the explicit gesture that opens the PR for review. Mirrors `submit.ts`: write
-// nothing, delegate via `pi.exec`, surface the structured result, never throw.
+// The warm `/ready` door: the deliberate ready gesture. The in-session twin of the Python
+// cold door (`perk pr ready`): a terminating tool + command that DELEGATE the mechanics
+// (mutations canonical in Python). For an incremental plan this is the review gate — perk
+// deliberately does NOT auto-publish on submit; `/ready` is the explicit gesture that opens the
+// draft PR for review. For a STACKED layer it is the deliberate HUMAN handoff made after review +
+// address: it stamps the exact verified published head into the delivery journal (draft AND
+// non-draft PRs — mark-ready mechanics first, then the journal append), and every successful
+// stacked stamp continues into the ready-time reconcile pass (`driveReadyReconcile` — the warm
+// continuation, contracts.md §8.66). Mirrors `submit.ts`: write nothing, delegate via `pi.exec`,
+// surface the structured result, never throw.
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { fetchObjectiveUrl, objectiveReadInstruction } from "../factories/objectivePlan.ts";
+import { bindingSuffix } from "../substrate/bindingDelivery.ts";
 import {
   booleanField,
   type ColdJson,
@@ -14,25 +21,92 @@ import {
   stringField,
 } from "../substrate/coldDoor.ts";
 import { registerPerkCommand } from "../substrate/command.ts";
+import { resolveIssueBackendId } from "../substrate/config.ts";
+import { render } from "../substrate/prompts.ts";
 import { failFor, ok, type Result } from "../substrate/result.ts";
+import type { ToolGating } from "../substrate/toolGating.ts";
 import { report } from "../surfaces/report.ts";
 
-/** The ok-arm fields — the structured `details` surface doubles as branch-safe persisted state. */
+// The drive's strict evidence vocabulary (contracts.md §8.66), local on purpose: this is
+// exact-evidence validation at the continuation boundary, NOT the lenient render vocabulary
+// other stack surfaces use. Both diff-range endpoints must be the full 40-hex lowercase
+// object id; ids must be marker-safe segments.
+const READY_EVIDENCE_ID_RE = /^[A-Za-z0-9._-]{1,64}$/;
+const READY_FULL_SHA_RE = /^[0-9a-f]{40}$/;
+
+/** The stacked handoff cohort — decoded all-or-nothing (advisory detail, never half-rendered).
+ * Deliberately facts-only: the worker envelope's `reconcile_notice`/`reconcile_retry` are cold
+ * presentation strings — the warm door derives its own retry gesture from `plan`, so missing
+ * presentation data can never suppress an otherwise valid continuation. */
+export interface ReadyHandoff {
+  objective: string;
+  node: string;
+  stamped_head: string;
+  stamp_advanced: boolean;
+  plan: string;
+  parent_checkpoint: string;
+}
+
+/** The ok-arm fields — the structured `details` surface doubles as branch-safe persisted state.
+ * `stacked` is the worker's own routing fact, passed through so a malformed cohort
+ * (`stacked === true`, `handoff` absent) is distinguishable from an incremental result. */
 export interface ReadyOk {
   pr: { number: number; url: string };
   was_draft?: boolean;
+  stacked?: boolean;
+  handoff?: ReadyHandoff;
 }
 
 export type ReadyResult = Result<ReadyOk>;
+export type ReadyDetails = ReadyResult["details"];
 
-/** Narrow the `perk pr ready --json` success payload; strict on `pr`, lenient on the rest. */
+/**
+ * Narrow the `perk pr ready --json` success payload; strict on `pr`, lenient on the rest.
+ *
+ * The stacked continuation decodes as ONE cohort: the handoff augmentation is attached only when
+ * `stacked === true` AND every cohort field decodes (the two continuation fields `plan` /
+ * `parent_checkpoint` included); a partial/wrong-typed cohort is validated-and-dropped whole
+ * (the worker's own success already proved the mechanics — advisory detail is never
+ * half-rendered), leaving the `stacked` passthrough as the visible mismatch signal. An absent
+ * `stacked` (an old worker) is the same no-augmentation arm.
+ */
 function decodeReady(payload: ColdJson): ReadyOk | null {
   const pr = objectField(payload, "pr");
   if (pr === undefined) return null;
   const number = numberField(pr, "number");
   const url = stringField(pr, "url");
   if (number === undefined || url === undefined) return null;
-  return { pr: { number, url }, was_draft: booleanField(payload, "was_draft") };
+  const result: ReadyOk = {
+    pr: { number, url },
+    was_draft: booleanField(payload, "was_draft"),
+    stacked: booleanField(payload, "stacked"),
+  };
+  if (result.stacked === true) {
+    const objective = stringField(payload, "objective");
+    const node = stringField(payload, "node");
+    const stampedHead = stringField(payload, "stamped_head");
+    const stampAdvanced = booleanField(payload, "stamp_advanced");
+    const plan = stringField(payload, "plan");
+    const parentCheckpoint = stringField(payload, "parent_checkpoint");
+    if (
+      objective !== undefined &&
+      node !== undefined &&
+      stampedHead !== undefined &&
+      stampAdvanced !== undefined &&
+      plan !== undefined &&
+      parentCheckpoint !== undefined
+    ) {
+      result.handoff = {
+        objective,
+        node,
+        stamped_head: stampedHead,
+        stamp_advanced: stampAdvanced,
+        plan,
+        parent_checkpoint: parentCheckpoint,
+      };
+    }
+  }
+  return result;
 }
 
 /**
@@ -49,39 +123,157 @@ export async function markReady(pi: ExtensionAPI, ctx: ExtensionContext): Promis
   if (!r.ok) return fail(r.message, r.errorType);
 
   const verb = r.data.was_draft ? "Marked ready" : "Already ready";
-  return ok(`${verb}: PR #${r.data.pr.number} is open for review.`, r.data, { terminate: true });
+  let message = `${verb}: PR #${r.data.pr.number} is open for review.`;
+  const handoff = r.data.handoff;
+  if (handoff !== undefined) {
+    // Stamp facts only — the continuation is announced by driveReadyReconcile, and only once
+    // its refusal arms (gate, cohort, evidence) have actually accepted the drive.
+    const stamped = handoff.stamp_advanced ? "Handoff stamped" : "Handoff already stamped";
+    message +=
+      ` ${stamped}: objective #${handoff.objective} node ${handoff.node} at ` +
+      `${handoff.stamped_head}.`;
+  }
+  return ok(message, r.data, { terminate: true });
+}
+
+/** One loud skipped-pass warning (the stamp itself stands; re-running `/ready` re-enters). */
+function warnSkippedPass(ctx: ExtensionContext, reason: string, retry: string): void {
+  report(
+    ctx,
+    "ready",
+    "warning",
+    `ready-time reconcile pass not driven — ${reason}. The handoff stamp stands; re-run ${retry} to enter the pass.`,
+  );
+}
+
+/**
+ * After a successful stacked stamp, drive the session into the ready-time reconcile pass
+ * (contracts.md §8.66): inject the rendered `stages/objective-reconcile-ready.md` guidance —
+ * the warm twin of the cold wrapper's seeded launch. Fires on EVERY successful stacked stamp,
+ * `existed=true` re-stamps included (re-running `/ready` re-enters reconciliation). The
+ * refusal arms are LOUD, never silent: a gate-active session (the pass's write tools are
+ * gated off — a drive would dead-end), a malformed/mixed-version stacked cohort, and evidence
+ * failing the strict vocabulary all warn and skip; the stamp itself always stands.
+ * Incremental results and failures drive nothing, quietly.
+ */
+export async function driveReadyReconcile(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  gating: ToolGating,
+  details: ReadyDetails,
+): Promise<void> {
+  if (details.ok !== true) return;
+  const handoff = details.handoff;
+  if (handoff === undefined) {
+    if (details.stacked === true) {
+      // A successful stacked stamp whose continuation cohort failed to decode — a
+      // malformed/mixed-version envelope must never fail silent.
+      warnSkippedPass(
+        ctx,
+        "the worker reported a stacked stamp but its continuation facts were malformed " +
+          "(a mixed-version envelope?)",
+        "/ready",
+      );
+    }
+    return; // incremental / old worker: nothing to drive
+  }
+  const retry = `\`perk ready ${READY_EVIDENCE_ID_RE.test(handoff.plan) ? handoff.plan : "<plan>"}\``;
+  if (gating.isActive()) {
+    warnSkippedPass(
+      ctx,
+      "this session is read-only (the pass's write tools are gated off); exit the read-only " +
+        "session or run the pass from a terminal",
+      retry,
+    );
+    return;
+  }
+  const idsValid =
+    READY_EVIDENCE_ID_RE.test(handoff.objective) &&
+    READY_EVIDENCE_ID_RE.test(handoff.node) &&
+    READY_EVIDENCE_ID_RE.test(handoff.plan);
+  const shasValid =
+    READY_FULL_SHA_RE.test(handoff.stamped_head) &&
+    READY_FULL_SHA_RE.test(handoff.parent_checkpoint);
+  if (!idsValid || !shasValid || !Number.isInteger(details.pr.number)) {
+    warnSkippedPass(
+      ctx,
+      "the stamp evidence failed strict validation (ids marker-safe; both diff-range " +
+        "endpoints full 40-hex lowercase)",
+      retry,
+    );
+    return;
+  }
+  const backend = resolveIssueBackendId(ctx.cwd);
+  const url = backend === "linear" ? await fetchObjectiveUrl(pi, ctx, handoff.objective) : "";
+  const readClause = objectiveReadInstruction(backend, handoff.objective, url);
+  const message =
+    render("stages/objective-reconcile-ready.md", {
+      objective: handoff.objective,
+      node: handoff.node,
+      plan: handoff.plan,
+      pr: String(details.pr.number),
+      parent_checkpoint: handoff.parent_checkpoint,
+      stamped_head: handoff.stamped_head,
+      read_clause: readClause,
+    }) + bindingSuffix(ctx.cwd, "command:objective-reconcile");
+  // Announce the continuation only HERE — after every refusal arm has accepted the drive.
+  report(
+    ctx,
+    "ready",
+    "info",
+    `continuing into the ready-time reconcile pass — objective #${handoff.objective}, ` +
+      `pinned range ${handoff.parent_checkpoint}..${handoff.stamped_head}`,
+  );
+  if (ctx.isIdle()) {
+    // The `/ready` command path (idle): inject an immediate turn.
+    pi.sendUserMessage(message);
+  } else {
+    // The `ready` tool path (streaming): deliver after the terminating ready batch.
+    pi.sendUserMessage(message, { deliverAs: "followUp" });
+  }
 }
 
 const TOOL_GUIDELINES = [
-  "Call ready only when the PR is ready for human review; it marks the draft PR ready (the deliberate review gate). submit keeps the PR draft on purpose.",
-  "ready operates on the active plan's worktree — it takes no arguments; the PR is discovered from the local plan-ref's branch. Idempotent: an already-ready PR is success.",
+  "For an incremental plan, call ready only when the PR is ready for human review; it marks the draft PR ready (the deliberate review gate). submit keeps the PR draft on purpose.",
+  "For a STACKED plan, /ready is the deliberate HUMAN handoff made AFTER review + address: it stamps the exact verified published head into the delivery journal (draft and non-draft PRs alike), and the recorded stamp unblocks planning of the layer's direct dependents. Never call it as routine post-submit choreography — review happens on the draft layer PR; only invoke it when the human explicitly asks.",
+  "ready operates on the active plan's worktree — it takes no arguments; the PR is discovered from the local plan-ref's branch. Idempotent: an already-ready PR is success, and a re-run converges on the same stamp.",
+  "A failed stamp (error_type ready_stamp_failed) names its own remediation: the ambiguous/transient arms converge on re-run; deterministic failures need their named repair first.",
 ];
 
 /** Register the warm door: the `ready` terminating tool + the `/ready` command twin. */
-export function registerReady(pi: ExtensionAPI): void {
+export function registerReady(pi: ExtensionAPI, gating: ToolGating): void {
   pi.registerTool({
     name: "ready",
     label: "Mark PR ready",
     description:
-      "Mark the active plan's draft PR ready for review (the deliberate review gate). " +
-      "Terminating: ends the turn. submit keeps the PR draft; ready is the explicit publish gesture.",
-    promptSnippet: "Mark the draft PR ready for review (terminates the turn)",
+      "Ready the active plan's PR. Incremental: mark the draft PR ready for review (the " +
+      "deliberate review gate; submit keeps the PR draft). Stacked: the deliberate post-review " +
+      "HUMAN handoff — stamps the exact verified published head (draft and non-draft PRs); " +
+      "never routine post-submit choreography, never auto-run. Terminating: ends the turn.",
+    promptSnippet:
+      "Ready the PR: open the draft for review (incremental) or record the post-review " +
+      "handoff stamp (stacked; human-asked only). Terminates the turn.",
     promptGuidelines: TOOL_GUIDELINES,
     executionMode: "sequential",
     parameters: { type: "object", additionalProperties: false, properties: {} },
     async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
-      return markReady(pi, ctx);
+      const result = await markReady(pi, ctx);
+      await driveReadyReconcile(pi, ctx, gating, result.details);
+      return result;
     },
   });
 
   registerPerkCommand(pi, "ready", {
-    description: "Mark the active plan's draft PR ready for review (submit → ready).",
+    description:
+      "Ready the plan's PR: open the draft for review (incremental) or record the " +
+      "post-review handoff stamp (stacked).",
     handler: async (_args, ctx) => {
       const result = await markReady(pi, ctx);
       // Failure already reported loudly via failFor (the single error surface) — success only.
       if (result.details.ok) {
         report(ctx, "ready", "info", result.content[0]?.text ?? "ready done");
       }
+      await driveReadyReconcile(pi, ctx, gating, result.details);
     },
   });
 }