@mgiles/perk 3.1.0 → 3.3.0

package/extension/{doors → pi/v1/delivery}/land.ts

@@ -1,14 +1,18 @@
-// The warm `/land` door. The in-session twin of the Python cold door
-// (`perk pr land`): a terminating tool + command that DELEGATE the GitHub merge (mutations
-// canonical in Python), then mirror the envelope's `pending_learn` for the in-session path —
-// setting the `pending-learn` marker (an idempotent existence-semaphore; the worker sets it too
-// on the cold path) unless the cold door reports the learn-docs exemption (`pending_learn:
-// false` — no marker, no /learn nudge). Never throws.
+// The per-plan landing bindings: the terminating `land` tool + the `/land` command, the
+// in-session twin of the Python cold door (`perk pr land`). A deliberately ZERO-POLICY adapter
+// module (no feature operation backs it — zero-policy passthrough): the tool DELEGATES the
+// GitHub merge (mutations canonical in Python), then mirrors the envelope's `pending_learn` for
+// the in-session path — setting the `pending-learn` marker (an idempotent existence-semaphore;
+// the worker sets it too on the cold path) unless the cold door reports the learn-docs
+// exemption (`pending_learn: false` — no marker, no /learn nudge). Never throws; a verified
+// land result survives every advisory failure (marker writes, malformed sub-objects) as a loud
+// warning line, never a post-merge rejection.
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { reconcileGuidance } from "../factories/objectivePlan.ts";
-import { bindingSuffix } from "../substrate/bindingDelivery.ts";
-import { PENDING_LEARN, setMarker } from "../substrate/cache.ts";
+import { reconcileGuidance } from "../../../authoring/objective/prose.ts";
+import { planningStageRefusal } from "../../../session/lifecycleGates.ts";
+import { bindingSuffix } from "../../../substrate/bindingDelivery.ts";
+import { PENDING_LEARN, setMarker } from "../../../substrate/cache.ts";
 import {
   booleanField,
   type ColdJson,
@@ -17,15 +21,21 @@ import {
   objectField,
   runColdDoor,
   stringField,
-} from "../substrate/coldDoor.ts";
-import { registerPerkCommand } from "../substrate/command.ts";
-import { failFor, ok, type Result } from "../substrate/result.ts";
-import { report } from "../surfaces/report.ts";
+} from "../../../substrate/coldDoor.ts";
+import { registerPerkCommand } from "../../../substrate/command.ts";
+import { failFor, ok, type Result } from "../../../substrate/result.ts";
+import { report } from "../../../surfaces/report.ts";
 
 // Learn-consume skip reasons that are ordinary, not failures: non-factory plans carry no
 // `consumed_learn` (`no_consumed_learn`), and a dry run reports `dry_run`. Anything else surfaces.
 const BENIGN_LEARN_SKIPS = new Set(["no_consumed_learn", "dry_run"]);
 
+/** The marker-safe id vocabulary the reconcile drive requires of the objective id — the
+ * interpolated guidance is a steering message rendering the id as an unquoted CLI argument,
+ * so an out-of-vocabulary id never drives and an option-shaped `-`-leading id never passes
+ * (alphanumeric-first). */
+const OBJECTIVE_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
 export interface ObjectiveLandUpdate {
   /** Opaque string objective id (GitHub "5", Linear "ENG-5") — §8.21. */
   id: string | null;
@@ -42,7 +52,7 @@ export interface LearnConsumeUpdate {
 
 /** The ok-arm fields — the structured `details` surface doubles as branch-safe persisted state.
  * `pending_learn` mirrors the cold envelope: `false` is the learn-docs exemption (no marker). */
-export interface LandOk {
+interface LandOk {
   pr: { number: number; state: string };
   branch?: string;
   /** Opaque string plan-issue id (§8.21). */
@@ -52,8 +62,16 @@ export interface LandOk {
   learn?: LearnConsumeUpdate;
 }
 
-export type LandResult = Result<LandOk>;
-export type LandDetails = LandResult["details"];
+type LandResult = Result<LandOk>;
+type LandDetails = LandResult["details"];
+
+/** An optional advisory sub-object's three-state decode: absent is ordinary; malformed is
+ * DISTINGUISHED (the merge already succeeded, so the success report survives — but the
+ * unverified state is reported loudly, never silently dropped). */
+type AdvisoryDecode<T> =
+  | { state: "absent" }
+  | { state: "malformed" }
+  | { state: "present"; value: T };
 
 /** The decoded `perk pr land --json` payload — the cold door owns `pending_learn` (the
  * learn-docs-exemption decision point); decoded leniently so skew degrades to legacy. */
@@ -62,47 +80,59 @@ interface LandPayload {
   branch?: string;
   issue?: string;
   pending_learn: boolean;
-  objective?: ObjectiveLandUpdate;
-  learn?: LearnConsumeUpdate;
+  objective: AdvisoryDecode<ObjectiveLandUpdate>;
+  learn: AdvisoryDecode<LearnConsumeUpdate>;
 }
 
-/** Validate the optional `objective` sub-object; malformed → undefined (advisory, never fatal). */
-function decodeObjective(payload: ColdJson): ObjectiveLandUpdate | undefined {
+/** Validate the optional `objective` sub-object — three-state (absent/malformed/present). */
+function decodeObjective(payload: ColdJson): AdvisoryDecode<ObjectiveLandUpdate> {
+  if (payload.objective === undefined) return { state: "absent" };
   const obj = objectField(payload, "objective");
-  if (obj === undefined) return undefined;
+  if (obj === undefined) return { state: "malformed" };
   const id = obj.id;
-  if (typeof id !== "string" && id !== null) return undefined;
+  if (typeof id !== "string" && id !== null) return { state: "malformed" };
   const nodesMarked = obj.nodes_marked;
   if (!Array.isArray(nodesMarked) || !nodesMarked.every((n) => typeof n === "string")) {
-    return undefined;
+    return { state: "malformed" };
   }
   const skippedReason = nullableStringField(obj, "skipped_reason");
-  if (skippedReason === undefined && obj.skipped_reason !== undefined) return undefined;
+  if (skippedReason === undefined && obj.skipped_reason !== undefined) {
+    return { state: "malformed" };
+  }
   // `closed` is an advisory display detail: decode leniently (missing/malformed → false) rather
   // than dropping the whole sub-object.
   return {
-    id,
-    nodes_marked: nodesMarked,
-    skipped_reason: skippedReason ?? null,
-    closed: obj.closed === true,
+    state: "present",
+    value: {
+      id,
+      nodes_marked: nodesMarked,
+      skipped_reason: skippedReason ?? null,
+      closed: obj.closed === true,
+    },
   };
 }
 
-/** Validate the optional `learn` sub-object; malformed → undefined (advisory, never fatal). */
-function decodeLearn(payload: ColdJson): LearnConsumeUpdate | undefined {
+/** Validate the optional `learn` sub-object — three-state (absent/malformed/present). */
+function decodeLearn(payload: ColdJson): AdvisoryDecode<LearnConsumeUpdate> {
+  if (payload.learn === undefined) return { state: "absent" };
   const learn = objectField(payload, "learn");
-  if (learn === undefined) return undefined;
+  if (learn === undefined) return { state: "malformed" };
   const closed = learn.closed;
-  if (!Array.isArray(closed) || !closed.every((n) => typeof n === "string")) return undefined;
+  if (!Array.isArray(closed) || !closed.every((n) => typeof n === "string")) {
+    return { state: "malformed" };
+  }
   const skippedReason = nullableStringField(learn, "skipped_reason");
-  if (skippedReason === undefined && learn.skipped_reason !== undefined) return undefined;
-  return { closed, skipped_reason: skippedReason ?? null };
+  if (skippedReason === undefined && learn.skipped_reason !== undefined) {
+    return { state: "malformed" };
+  }
+  return { state: "present", value: { closed, skipped_reason: skippedReason ?? null } };
 }
 
 /**
  * Narrow the `perk pr land --json` success payload. Strict on `pr` (malformed → bad_output);
- * the optional `objective`/`learn` sub-objects are validated but dropped when malformed — the
- * merge already succeeded, so the success report must survive a malformed advisory field.
+ * the optional `objective`/`learn` sub-objects decode three-state — a malformed advisory field
+ * is dropped from the details (the merge already succeeded, so the success report must
+ * survive it) but reported as an UNVERIFIED-state warning line, never silently.
  */
 function decodeLand(payload: ColdJson): LandPayload | null {
   const pr = objectField(payload, "pr");
@@ -123,32 +153,58 @@ function decodeLand(payload: ColdJson): LandPayload | null {
   };
 }
 
+/** The malformed-advisory warning line (the `<objective|learn>` slots are the report name and
+ * its unverified-state name). */
+function malformedAdvisoryWarning(field: "objective" | "learn"): string {
+  const stateName = field === "objective" ? "objective reconcile" : "learn";
+  return (
+    `Warning: the land envelope's ${field} report was malformed — ${stateName} state ` +
+    "UNVERIFIED; inspect the objective (or run /objective-reconcile) manually."
+  );
+}
+
 /**
- * The single land implementation both surfaces call. Delegates the merge to the Python cold door,
- * then mirrors the envelope's `pending_learn` (in-session path): marker + /learn nudge on the
- * ordinary arm; no marker, no nudge on the learn-docs exemption. Returns a soft result
+ * The single land implementation both surfaces call. Delegates the merge to the Python cold
+ * door, then mirrors the envelope's `pending_learn` (in-session path): marker + /learn nudge on
+ * the ordinary arm; no marker, no nudge on the learn-docs exemption. A marker WRITE failure is
+ * loud-not-fatal: the merge is already verified, so the success result (and the reconcile
+ * drive) survive with a warning line naming the /learn remediation. Returns a soft result
  * (never throws).
  */
-export async function landPr(pi: ExtensionAPI, ctx: ExtensionContext): Promise<LandResult> {
+async function landPr(pi: ExtensionAPI, ctx: ExtensionContext): Promise<LandResult> {
   const fail = failFor(ctx, "land");
 
+  // Planning sessions never legitimately land — the first check, before any cold-door
+  // delegation (a positioned stacked planning session's cwd binding is the PREDECESSOR).
+  const planningRefusal = planningStageRefusal(ctx, "land");
+  if (planningRefusal !== null) return fail(planningRefusal, "planning_session");
+
   const r = await runColdDoor<LandPayload>(pi, ctx, ["pr", "land", "--json"], {
     label: "perk pr land",
     decode: decodeLand,
   });
   if (!r.ok) return fail(r.message, r.errorType);
 
-  if (r.data.pending_learn) {
-    // Set the semaphore for the in-session path (idempotent; the cold door also set it on disk).
-    setMarker(ctx.cwd, PENDING_LEARN);
-  }
-
   const lines = [
     r.data.pending_learn
       ? `Landed PR #${r.data.pr.number}; run /learn to release the worktree.`
       : `Landed PR #${r.data.pr.number}; learn-docs plan — no learn pass needed; the worktree is releasable.`,
   ];
-  const obj = r.data.objective;
+  if (r.data.pending_learn) {
+    // Set the semaphore for the in-session path (idempotent; the cold door also set it on
+    // disk). Guarded: a filesystem failure must never erase a VERIFIED land result — the
+    // success report + reconcile drive survive, with the /learn remediation named loudly.
+    try {
+      setMarker(ctx.cwd, PENDING_LEARN);
+    } catch (error) {
+      const detail = error instanceof Error ? error.message : String(error);
+      lines.push(
+        `Warning: the pending-learn marker could not be written (${detail}); run /learn ` +
+          "before releasing the worktree.",
+      );
+    }
+  }
+  const obj = r.data.objective.state === "present" ? r.data.objective.value : undefined;
   if (obj?.nodes_marked.length && obj.id !== null) {
     // The reconcile pass is auto-driven after land (see driveReconcileAfterLand); just report it.
     lines.push(
@@ -159,7 +215,7 @@ export async function landPr(pi: ExtensionAPI, ctx: ExtensionContext): Promise<L
   if (obj?.closed && obj.id !== null) {
     lines.push(`Objective #${obj.id} complete — closed.`);
   }
-  const learn = r.data.learn;
+  const learn = r.data.learn.state === "present" ? r.data.learn.value : undefined;
   if (learn?.closed.length) {
     // hop-2: the consumed perk:learn issues were closed + labelled perk:consolidated on land.
     lines.push(
@@ -173,21 +229,31 @@ export async function landPr(pi: ExtensionAPI, ctx: ExtensionContext): Promise<L
   if (learn?.skipped_reason && !BENIGN_LEARN_SKIPS.has(learn.skipped_reason)) {
     lines.push(`Warning: learn consume incomplete — ${learn.skipped_reason}.`);
   }
+  // A malformed advisory sub-object leaves the merge verified but its state UNKNOWN: the
+  // details omit the field (as before) and the drive stays suppressed, but the miss is loud.
+  if (r.data.objective.state === "malformed") lines.push(malformedAdvisoryWarning("objective"));
+  if (r.data.learn.state === "malformed") lines.push(malformedAdvisoryWarning("learn"));
 
-  return ok(
-    lines.join("\n"),
-    { ...r.data, pending_learn: r.data.pending_learn },
-    { terminate: true },
-  );
+  const details: LandOk = {
+    pr: r.data.pr,
+    branch: r.data.branch,
+    issue: r.data.issue,
+    pending_learn: r.data.pending_learn,
+    objective: obj,
+    learn: learn,
+  };
+  return ok(lines.join("\n"), details, { terminate: true });
 }
 
 /**
- * After a successful land that marked at least one objective node done, drive the session into the
- * reconcile pass by injecting the exact guidance `/objective-reconcile` injects (warm-door driving
- * pattern). The terminating `land` tool stays terminating — terminate only skips the *automatic*
- * follow-up LLM call, while a `followUp` user message is a separate deliberate new turn. Short-
- * circuits (sends nothing) unless the land succeeded with an objective node marked done — the exact
- * condition that gated the old copy-pasteable nudge.
+ * After a successful land that marked at least one objective node done, drive the session into
+ * the reconcile pass by injecting the exact guidance `/objective-reconcile` injects (warm-door
+ * driving pattern). The terminating `land` tool stays terminating — terminate only skips the
+ * *automatic* follow-up LLM call, while a `followUp` user message is a separate deliberate new
+ * turn. Short-circuits (sends nothing) unless the land succeeded with an objective node marked
+ * done AND the id passes the marker-safe vocabulary — the id is interpolated into a steering
+ * message, so a poisoned envelope id never drives. Exported for the offline suite (the
+ * streaming `followUp` branch is unreachable through the idle harness).
  */
 export function driveReconcileAfterLand(
   pi: ExtensionAPI,
@@ -197,6 +263,7 @@ export function driveReconcileAfterLand(
   if (!details.ok) return;
   const obj = details.objective;
   if (!obj || obj.id === null || obj.nodes_marked.length === 0) return;
+  if (!OBJECTIVE_ID_RE.test(obj.id)) return;
   const message = reconcileGuidance(obj.id) + bindingSuffix(ctx.cwd, "command:objective-reconcile");
   if (ctx.isIdle()) {
     // The `/land` command path (idle): inject an immediate turn.
@@ -213,8 +280,9 @@ const TOOL_GUIDELINES = [
   "land refuses a stacked-delivery plan (`delivery_lineage`): stacked layers land as one atomic train, never individually.",
 ];
 
-/** Register the warm door: the `land` terminating tool + the `/land` command twin. */
-export function registerLand(pi: ExtensionAPI): void {
+/** Install the per-plan landing bindings: the `land` terminating tool + the `/land` command
+ * twin. */
+export function installLandBindings(pi: ExtensionAPI): void {
   pi.registerTool({
     name: "land",
     label: "Land PR",

package/extension/pi/v1/delivery/ready.ts

@@ -0,0 +1,322 @@
+// The ready + handoff bindings: the `ready` terminating tool + the `/ready` command twin,
+// adapting the Pi-free ready operation in `delivery/ready.ts`. The in-session twin of the Python
+// cold door (`perk pr ready`): a terminating surface that DELEGATES 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 (`driveReadyContinuation` — the warm
+// continuation, contracts.md §8.66). Write nothing, delegate via the cold-door seam, surface the
+// structured result, never throw. This tier is pure decoding, rendering, process invocation, and
+// Pi delivery — the arm order, the strict evidence vocabulary, and the continuation decision
+// live in the feature op.
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { objectiveReadInstruction } from "../../../authoring/objective/prose.ts";
+import {
+  type ReadyDeps,
+  type ReadyDriveEvidence,
+  type ReadyFacts,
+  type ReadyHandoff,
+  type ReadyOutcome,
+  type ReadyPr,
+  readyChange,
+} from "../../../delivery/ready.ts";
+import { bindingSuffix } from "../../../substrate/bindingDelivery.ts";
+import {
+  booleanField,
+  type ColdJson,
+  numberField,
+  objectField,
+  runColdDoor,
+  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 } from "../../../substrate/result.ts";
+import type { ToolGating } from "../../../substrate/toolGating.ts";
+import { report } from "../../../surfaces/report.ts";
+import { fetchObjectiveUrl } from "../objective.ts";
+
+/**
+ * Narrow the `perk pr ready --json` success payload into the correlated facts variants; strict
+ * on `pr`, lenient on the rest. The stacked continuation decodes as ONE cohort: a
+ * partial/wrong-typed cohort is validated-and-dropped whole into `stacked_unverified` (the
+ * worker's own success already proved the mechanics — advisory detail is never half-rendered),
+ * keeping the routing fact as the visible mismatch signal. An absent-or-false `stacked` (an old
+ * worker included) is the `incremental` variant, false-vs-absent preserved for the wire.
+ */
+function decodeReady(payload: ColdJson): ReadyFacts | null {
+  const prField = objectField(payload, "pr");
+  if (prField === undefined) return null;
+  const number = numberField(prField, "number");
+  const url = stringField(prField, "url");
+  if (number === undefined || url === undefined) return null;
+  const pr: ReadyPr = { number, url };
+  const wasDraft = booleanField(payload, "was_draft");
+  const stacked = booleanField(payload, "stacked");
+  if (stacked !== true) {
+    return { route: "incremental", pr, was_draft: wasDraft, stacked };
+  }
+  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
+  ) {
+    return { route: "stacked_unverified", pr, was_draft: wasDraft };
+  }
+  return {
+    route: "stacked",
+    pr,
+    was_draft: wasDraft,
+    handoff: {
+      objective,
+      node,
+      stamped_head: stampedHead,
+      stamp_advanced: stampAdvanced,
+      plan,
+      parent_checkpoint: parentCheckpoint,
+    },
+  };
+}
+
+/** The ONE production `MarkReady` adapter: `perk pr ready --json` through the cold-door seam
+ * (cancellation, envelope validation, and version-skew diagnostics ride the seam).
+ * Module-private: production composes only through `readyDepsFor`. */
+function createReadyMarker(pi: ExtensionAPI, ctx: ExtensionContext): ReadyDeps["markReady"] {
+  return async () => {
+    const r = await runColdDoor<ReadyFacts>(pi, ctx, ["pr", "ready", "--json"], {
+      label: "perk pr ready",
+      decode: decodeReady,
+    });
+    if (!r.ok) return { ok: false, message: r.message, errorType: r.errorType };
+    return { ok: true, facts: r.data };
+  };
+}
+
+/** The one production `ReadyDeps` composition (module-private: the one-composition invariant
+ * is structural). The gate read is the injected capability — the feature op reads it only on
+ * the stamped-with-cohort path. */
+function readyDepsFor(pi: ExtensionAPI, ctx: ExtensionContext, gating: ToolGating): ReadyDeps {
+  return {
+    markReady: createReadyMarker(pi, ctx),
+    sessionReadOnly: () => gating.isActive(),
+  };
+}
+
+/** The wire-identical ok-arm details rebuilt from the facts variants: incremental ⇒ `stacked`
+ * passthrough (false or absent), no `handoff`; `stacked_unverified` ⇒ `stacked: true`, no
+ * `handoff`; `stacked` ⇒ `stacked: true` + the six-field cohort. Optional keys carry
+ * `undefined` exactly where the old decode left them absent (the JSON round-trip drops them). */
+interface ReadyDetails {
+  pr: ReadyPr;
+  was_draft?: boolean;
+  stacked?: boolean;
+  handoff?: ReadyHandoff;
+}
+
+function readyDetails(facts: ReadyFacts): ReadyDetails {
+  switch (facts.route) {
+    case "incremental":
+      return { pr: facts.pr, was_draft: facts.was_draft, stacked: facts.stacked };
+    case "stacked_unverified":
+      return { pr: facts.pr, was_draft: facts.was_draft, stacked: true };
+    case "stacked":
+      return { pr: facts.pr, was_draft: facts.was_draft, stacked: true, handoff: facts.handoff };
+  }
+}
+
+/** Render the success message: the ready line, plus — exactly when the facts route is
+ * `stacked` — the handoff-stamped line. Stamp facts only: the continuation is announced by
+ * `driveReadyContinuation`, and only once the feature op's refusal arms have accepted. */
+function renderReadyMessage(facts: ReadyFacts): string {
+  const verb = facts.was_draft ? "Marked ready" : "Already ready";
+  let message = `${verb}: PR #${facts.pr.number} is open for review.`;
+  if (facts.route === "stacked") {
+    const handoff = facts.handoff;
+    const stamped = handoff.stamp_advanced ? "Handoff stamped" : "Handoff already stamped";
+    message +=
+      ` ${stamped}: objective #${handoff.objective} node ${handoff.node} at ` +
+      `${handoff.stamped_head}.`;
+  }
+  return message;
+}
+
+/** 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.`,
+  );
+}
+
+/** The retry gesture from the feature op's safe-interpolation policy: a marker-safe plan id
+ * interpolates; `null` renders the `<plan>` placeholder. */
+function retryGesture(retryPlan: string | null): string {
+  return `\`perk ready ${retryPlan ?? "<plan>"}\``;
+}
+
+/** Inject the rendered ready-time reconcile pass (contracts.md §8.66) — the warm twin of the
+ * cold wrapper's seeded launch. Interpolates exclusively from the mint-only evidence. */
+async function driveReconcilePass(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  evidence: ReadyDriveEvidence,
+): Promise<void> {
+  const backend = resolveIssueBackendId(ctx.cwd);
+  const url = backend === "linear" ? await fetchObjectiveUrl(pi, ctx, evidence.objective) : "";
+  const readClause = objectiveReadInstruction(backend, evidence.objective, url);
+  const message =
+    render("stages/objective-reconcile-ready.md", {
+      objective: evidence.objective,
+      node: evidence.node,
+      plan: evidence.plan,
+      pr: String(evidence.pr),
+      parent_checkpoint: evidence.parent_checkpoint,
+      stamped_head: evidence.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 #${evidence.objective}, ` +
+      `pinned range ${evidence.parent_checkpoint}..${evidence.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" });
+  }
+}
+
+/**
+ * Translate the feature op's outcome into the warm continuation (contracts.md §8.66): the drive
+ * fires on EVERY accepted stacked stamp (`stamp_advanced: false` re-stamps included — re-running
+ * `/ready` re-enters reconciliation). The refusal arms are LOUD, never silent; the stamp itself
+ * always stands. `failed` and `completed` are explicit quiet arms. Exported as the one direct
+ * test seam — the streaming `followUp` branch is unreachable through the idle harness.
+ */
+export async function driveReadyContinuation(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  outcome: ReadyOutcome,
+): Promise<void> {
+  switch (outcome.kind) {
+    case "failed":
+    case "completed":
+      return; // exterior failure / incremental: nothing to drive, quietly
+    case "stamp_facts_unverified":
+      // 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;
+    case "stamped": {
+      const continuation = outcome.continuation;
+      switch (continuation.kind) {
+        case "refused_read_only":
+          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",
+            retryGesture(continuation.retryPlan),
+          );
+          return;
+        case "evidence_invalid":
+          warnSkippedPass(
+            ctx,
+            "the stamp evidence failed strict validation (ids marker-safe; both diff-range " +
+              "endpoints full 40-hex lowercase)",
+            retryGesture(continuation.retryPlan),
+          );
+          return;
+        case "drive":
+          await driveReconcilePass(pi, ctx, continuation.evidence);
+          return;
+      }
+      // Exhaustive over the continuation (no catch-all): union growth breaks the adapter here.
+      const exhaustiveContinuation: never = continuation;
+      throw new Error(`unreachable ready continuation: ${JSON.stringify(exhaustiveContinuation)}`);
+    }
+  }
+  // Exhaustive over the outcome (no catch-all): union growth breaks the adapter here.
+  const exhaustive: never = outcome;
+  throw new Error(`unreachable ready outcome: ${JSON.stringify(exhaustive)}`);
+}
+
+const TOOL_GUIDELINES = [
+  "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.",
+];
+
+/** Install the ready + handoff bindings: the `ready` terminating tool + the `/ready` command
+ * twin. */
+export function installReadyBindings(pi: ExtensionAPI, gating: ToolGating): void {
+  pi.registerTool({
+    name: "ready",
+    label: "Mark PR ready",
+    description:
+      "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) {
+      const fail = failFor(ctx, "ready");
+      const outcome = await readyChange(readyDepsFor(pi, ctx, gating));
+      if (outcome.kind === "failed") return fail(outcome.message, outcome.errorType);
+      const result = ok(renderReadyMessage(outcome.facts), readyDetails(outcome.facts), {
+        terminate: true,
+      });
+      await driveReadyContinuation(pi, ctx, outcome);
+      return result;
+    },
+  });
+
+  registerPerkCommand(pi, "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 fail = failFor(ctx, "ready");
+      const outcome = await readyChange(readyDepsFor(pi, ctx, gating));
+      // Failure is reported loudly via failFor (the single error surface) — success only.
+      if (outcome.kind === "failed") {
+        fail(outcome.message, outcome.errorType);
+        return;
+      }
+      // Report-before-drive (load-bearing order): the success line lands before the injected
+      // reconcile turn.
+      report(ctx, "ready", "info", renderReadyMessage(outcome.facts));
+      await driveReadyContinuation(pi, ctx, outcome);
+    },
+  });
+}