@mgiles/perk 3.2.0 → 3.3.0

package/extension/pi/v1/plan.ts

@@ -0,0 +1,812 @@
+// The v1 Pi installer for the plan feature (module-contracts.md's named-installer shape):
+// `installPlanBindings` owns EVERY plan registration — perk-owned plan mode (the `/plan`
+// command, `Ctrl+Alt+P` shortcut, `--plan` flag, and the plan-authoring context hook pair, with
+// the three-tier provider deferral), the `plan_draft`/`plan_save` tools, the `/plan-save` and
+// `/implement-here` commands, and the `plan_review` registration — registration metadata
+// pinned by the suite's registration-parity tests. The feature logic lives in `authoring/plan/`; this module decodes at
+// the tool boundary, builds the provider/backend/gate adapters (`planSaveDepsFor` — the ONE
+// production composition point every plan-save surface AND the review door consume), constructs
+// the warm-door Result envelopes (the byte-stable message assembly), and places the
+// feature-owned prose units in Pi fields.
+//
+// PLAN MODE (the toggle surface over the read-only gate): grounded in pi's official
+// `examples/extensions/plan-mode/` recipe, but perk adopts ONLY the read-only authoring half —
+// there is no in-session "execution mode" flip (perk separates plan from implement). The
+// plan-authoring injection dedups on the COMPACTION-ACTIVE window (contracts §8.31 — the gist
+// precedent): a live copy suppresses re-injection; compaction dropping it re-injects next turn.
+//
+// REGISTRATION-TIME DEFERRAL, THREE-TIER. The plan-mode surface resolves the plan provider id
+// once at install time and branches:
+//   - `perk-plan` (and the fail-safe error path) → register EVERYTHING (the default path is the
+//     hard guarantee, zero behavior change).
+//   - `plannotator-plan` (AUGMENT posture) → register everything EXCEPT the `--plan` flag, the
+//     `Ctrl+Alt+P` shortcut, and the `--plan` session_start handler: `@plannotator/pi-extension`
+//     also registers that flag + shortcut, and duplicate flag/shortcut registration is the known
+//     potentially-fatal Pi behavior — plannotator owns `--plan`/`Ctrl+Alt+P` exclusively while
+//     perk keeps `/plan`, the authoring injection, and the read-only gate (plannotator augments
+//     perk's plan flow via the providers/plannotator.ts `plan_review` bridge; it does not
+//     replace it).
+//   - any other foreign id (tombell, REPLACE posture) → register NOTHING of the mode surface;
+//     the foreign package owns `/plan`/`Ctrl+Alt+P`/`--plan` unambiguously (Pi suffixes
+//     duplicate command names, so handler-time deferral alone is insufficient once the foreign
+//     package is loaded).
+//
+// SEAM-SHARED SUBSTRATE. `savePlan`/the `plan_save` tool/`/plan-save`/the read-only gate
+// are the produced-contract landing for the PLAN seam (`adapter-architecture.md` Invariant 1) —
+// the adapter bridges a foreign plan surface *to* `plan_save`/`cache.plan-ref`/the gate, so
+// they must stay always-registered. They do NOT defer when a foreign `[providers] plan` is
+// selected — only perk's own authoring surface (the mode tier above) steps aside.
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { PLAN_DRAFT_ARTIFACT, revisePlanDraft } from "../../authoring/plan/draft.ts";
+import {
+  PLAN_CONTEXT_TYPE,
+  PLAN_MARKER,
+  planAuthoringContextContent,
+} from "../../authoring/plan/prose.ts";
+import {
+  type ObjectiveNodeLink,
+  type PlanBackend,
+  planApprovalSave,
+  type SavePlanOutcome,
+  savePlan,
+} from "../../authoring/plan/save.ts";
+import { extractPlanMarkdown, resolvePlanSource } from "../../authoring/plan/source.ts";
+import { openBranchWorkflowSession } from "../../session/branchWorkflowSession.ts";
+import type { PlanRef } from "../../substrate/cache.ts";
+import {
+  booleanField,
+  type ColdJson,
+  nullableStringField,
+  objectField,
+  runColdDoor,
+  stringField,
+} from "../../substrate/coldDoor.ts";
+import { registerPerkCommand } from "../../substrate/command.ts";
+import { loadPerkConfig } from "../../substrate/config.ts";
+// Re-resolved here (not imported from providers/selection.ts) would drift — import the probe
+// and compare against the provider registry ids at install time.
+import { PERK_PLAN_PROVIDER_ID, PLANNOTATOR_PLAN_PROVIDER_ID } from "../../substrate/providers.ts";
+import { failFor, ok } from "../../substrate/result.ts";
+import { captureSessionPointer } from "../../substrate/sessionPointers.ts";
+import type { ToolGating } from "../../substrate/toolGating.ts";
+import { idArrayParam, paramsOf, stringParam } from "../../substrate/toolParams.ts";
+import { branchOf, rebuildWorkflowState } from "../../substrate/workflowState.ts";
+import { report, type Severity } from "../../surfaces/report.ts";
+// `Key` via the surfaces re-export (keybinding vocabulary, not rich UI) — keeps pi-tui imports
+// structurally confined to the surfaces module (the surfacesGuard pi-tui import rule).
+import { type ActivityHandle, Key } from "../../surfaces/surfaces.ts";
+import { installInjectedContext, isPlanGuidanceStage } from "./contextInjection.ts";
+import { type DraftReviewSlot, recordSaveOutcome } from "./draftReview.ts";
+import { isRefinementSession, refinementStageRefusal } from "./objectiveRefinement.ts";
+import {
+  type ApprovalSaveOutcome,
+  executePlanReview,
+  type PlanReviewV1Deps,
+  runImplementHereCommand,
+  type SaveResult,
+} from "./planReview.ts";
+import { createPlannotatorBridge } from "./providers/plannotator.ts";
+import { resolvedPlanProviderId } from "./providers/selection.ts";
+import type { WaveLaunch } from "./review.ts";
+
+// ------------------------------------------------------------------- the tool-boundary decode
+
+/**
+ * Decode unknown `plan_draft` tool-call params (the tool-boundary seam). `plan` absent decodes to
+ * `""` (so the core's `invalid_input` arm owns the empty-plan message); present-but-mistyped →
+ * null (strict-fail `bad_input`). Decode-before-side-effect.
+ */
+export function decodePlanDraftParams(params: unknown): { plan: string } | null {
+  const p = paramsOf(params);
+  if (p === null) return null;
+  const plan = stringParam(p, "plan");
+  if (plan === null) return null;
+  return { plan: plan ?? "" };
+}
+
+/** The decoded `plan_save` tool params (snake_case, as the schema declares them). */
+interface PlanSaveParams {
+  plan?: string;
+  title?: string;
+  objective_id?: string;
+  node_id?: string;
+  consumed_learn?: string[];
+}
+
+/**
+ * Decode unknown `plan_save` tool-call params (the tool-boundary seam). `plan` is
+ * optional (the validated plan-draft artifact is preferred) — absent decodes to
+ * `undefined`, but present-but-mistyped → null (strict-fail); the optional fields likewise.
+ */
+export function decodePlanSaveParams(params: unknown): PlanSaveParams | null {
+  const p = paramsOf(params);
+  if (p === null) return null;
+  const plan = stringParam(p, "plan");
+  if (plan === null) return null;
+  const title = stringParam(p, "title");
+  const objectiveId = stringParam(p, "objective_id");
+  const nodeId = stringParam(p, "node_id");
+  // Opaque string ids (§8.21); numbers are coerced — the learn-docs guidance renders bare
+  // numeric ids on GitHub, so the model may echo them un-quoted.
+  const consumedLearn = idArrayParam(p, "consumed_learn");
+  if (title === null || objectiveId === null || nodeId === null || consumedLearn === null) {
+    return null;
+  }
+  return {
+    plan: plan ?? undefined,
+    title,
+    objective_id: objectiveId,
+    node_id: nodeId,
+    consumed_learn: consumedLearn,
+  };
+}
+
+// -------------------------------------------------------------- the cold-door backend adapter
+
+/**
+ * The decoded `perk plan save --json` payload slice the warm door consumes. Decode policy
+ * (`docs/learned/workflow/cold-door-client.md`: strict iff appended to workflow-state): only
+ * `plan_ref` is strict. The rendered `issue.id`/`url` are DERIVED from the strict ref — the cold
+ * door constructs the ref from the issue (`pr_id == issue.id`, `url == issue.url`), so they are
+ * byte-identical by construction; `existed` and `objective_node` are advisory.
+ */
+interface PlanSavePayload {
+  issue: { id: string; url: string; existed: boolean | undefined };
+  plan_ref: PlanRef;
+  cached?: boolean;
+  updated?: boolean;
+  objective_node: ObjectiveNodeLink | null;
+}
+
+/**
+ * Fully strict `plan_ref` decode — a half-formed ref appended to workflow-state would poison
+ * `planRefsEqual` and every downstream consumer, so any miss → null → bad_output.
+ */
+function decodePlanRef(payload: ColdJson): PlanRef | null {
+  const ref = objectField(payload, "plan_ref");
+  if (ref === undefined) return null;
+  const provider = stringField(ref, "provider");
+  const prId = stringField(ref, "pr_id");
+  const url = stringField(ref, "url");
+  const labels = ref.labels;
+  const objectiveId = nullableStringField(ref, "objective_id");
+  if (
+    provider === undefined ||
+    prId === undefined ||
+    url === undefined ||
+    !Array.isArray(labels) ||
+    !labels.every((l) => typeof l === "string") ||
+    objectiveId === undefined
+  ) {
+    return null;
+  }
+  // `base` stays Python-owned for all behavior; carrying it keeps the workflow-state
+  // `active_plan_ref` copy byte-consistent with the cold door's `--json` plan_ref. Parity-only +
+  // lenient: a present null/string is carried, an absent/mistyped value is simply omitted (never a
+  // decode failure — legacy plan-refs lack the field).
+  const base = nullableStringField(ref, "base");
+  return { provider, pr_id: prId, url, labels, objective_id: objectiveId, base };
+}
+
+/** Validate the optional `objective_node` sub-object; malformed → null (advisory, never fatal). */
+function decodeObjectiveNode(payload: ColdJson): ObjectiveNodeLink | null {
+  const node = objectField(payload, "objective_node");
+  if (node === undefined) return null;
+  const linked = booleanField(node, "linked");
+  const name = nullableStringField(node, "node");
+  const status = nullableStringField(node, "status");
+  const error = nullableStringField(node, "error");
+  if (linked === undefined || name === undefined || status === undefined || error === undefined) {
+    return null;
+  }
+  return { linked, node: name, status, error };
+}
+
+/**
+ * Narrow the `perk plan save --json` success payload. Strict ONLY on `plan_ref` (malformed →
+ * bad_output — it is appended to workflow-state, where a half-formed ref would poison
+ * `planRefsEqual`). The rendered issue id/url are derived from the strict ref instead of decoded
+ * independently — the cold door builds the ref FROM the issue, so they are byte-identical by
+ * construction; this makes any `issue` sub-object shape change (e.g. a `number`→`id`
+ * rename under CLI↔extension version skew) skew-harmless. `existed` and
+ * `objective_node` are advisory — the plan genuinely saved, so the success report must survive
+ * them. With `plan_ref` the only strict field, `bad_output` is reachable only for a payload whose
+ * persistence would corrupt workflow-state.
+ */
+function decodePlanSave(payload: ColdJson): PlanSavePayload | null {
+  const ref = decodePlanRef(payload);
+  if (ref === null) return null;
+  const issue = objectField(payload, "issue");
+  const existed = issue === undefined ? undefined : booleanField(issue, "existed");
+  return {
+    issue: { id: ref.pr_id, url: ref.url, existed },
+    plan_ref: ref,
+    cached: booleanField(payload, "cached"),
+    updated: booleanField(payload, "updated"),
+    objective_node: decodeObjectiveNode(payload),
+  };
+}
+
+/**
+ * The production `PlanBackend` over the Python cold door (`perk plan save --json` via the
+ * shared cold-door client; the plan markdown rides the run-scratch stdin channel). Argv
+ * assembly byte-identical to what the save always emitted; `runId: null` omits `--run-id`
+ * (an identity-less save keeps working).
+ */
+function coldDoorPlanBackend(pi: ExtensionAPI, ctx: ExtensionContext): PlanBackend {
+  return {
+    async save(req) {
+      const args = ["plan", "save", "--json"];
+      if (req.runId !== null && req.runId !== "") args.push("--run-id", req.runId);
+      // An explicit title; when absent the cold door derives it (`plan.derive_title`).
+      if (req.title) args.push("--title", req.title);
+      // The plan→objective link. The objective plan-factory passes the active objective
+      // number; non-objective plans omit it (unchanged behavior).
+      if (req.objectiveId) args.push("--objective-id", req.objectiveId);
+      // The objective plan factory passes the node id alongside the objective id; the cold
+      // door commits the node→plan backlink + `in_progress` advance atomically. Non-factory
+      // plans omit it (unchanged behavior).
+      if (req.nodeId) args.push("--node-id", req.nodeId);
+      // The learn-docs factory passes the consumed perk:learn issue numbers; docs plans land
+      // them (close + label perk:consolidated). Non-factory plans omit it (unchanged behavior).
+      if (req.consumedLearn && req.consumedLearn.length > 0) {
+        args.push("--consumed-learn", req.consumedLearn.join(","));
+      }
+      const r = await runColdDoor<PlanSavePayload>(pi, ctx, args, {
+        label: "perk plan save",
+        decode: decodePlanSave,
+        stdin: { flag: "--plan-file", content: req.plan, filename: "plan.md" },
+      });
+      if (!r.ok) return { status: "failed", message: r.message, errorType: r.errorType };
+      return {
+        status: "saved",
+        ref: r.data.plan_ref,
+        existed: r.data.issue.existed ?? null,
+        updated: r.data.updated ?? false,
+        cached: r.data.cached ?? false,
+        nodeLink: r.data.objective_node,
+      };
+    },
+  };
+}
+
+// ---------------------------------------------------------------- the byte-stable rendering
+
+/**
+ * Render a feature `SavePlanOutcome` as the warm-door SaveResult — the ONE message-assembly
+ * site every plan-save surface shares (tool, command, approval seam, review arm). Byte-stable:
+ * verb/existed, the node-link suffix (all THREE outcomes — a failed advance is a non-fatal
+ * sub-step but must be VISIBLE, the §8.3 "surfaced, never swallowed" intent), the source suffix
+ * + param-mismatch flag. The outcome's `linkage`/`claimClear` seam results are deliberately NOT
+ * rendered (append/read-back failures stay loud through the seam's report() path exactly as
+ * always); a `failed` outcome reports through the `failFor` seam (same scope, same bytes).
+ */
+function renderSavePlanOutcome(ctx: ExtensionContext, save: SavePlanOutcome): SaveResult {
+  if (save.status === "failed") {
+    return failFor(ctx, "plan-save")(save.message, save.errorType);
+  }
+  const ref = save.ref;
+  const verb = save.existed ? "Updated" : "Saved";
+  const nodeLink = save.nodeLink;
+  // Render all THREE node-link outcomes (the silent-partial-failure fix). Both surfaces render
+  // content[0].text, so this one site fixes the tool path (the model relays it) and the command
+  // path (the user sees the notify) at once.
+  let linkSuffix = "";
+  if (nodeLink?.linked === true) {
+    linkSuffix = ` · linked objective node ${nodeLink.node} → in_progress`;
+  } else if (nodeLink && nodeLink.linked === false) {
+    linkSuffix = ` · ⚠ objective node ${nodeLink.node} NOT advanced — re-run /plan-save to retry${
+      nodeLink.error ? ` (${nodeLink.error})` : ""
+    }`;
+  }
+  // Surface NON-param sources in the message (param-path success messages stay
+  // byte-stable); a differing ignored param is visibly flagged, never silent.
+  let sourceSuffix = "";
+  if (save.source === "plan-draft" || save.source === "transcript") {
+    sourceSuffix =
+      save.source === "plan-draft"
+        ? " · plan source: plan-draft artifact"
+        : " · plan source: transcript";
+    if (save.paramMismatch) {
+      sourceSuffix += " (⚠ differing plan param ignored — the validated artifact was saved)";
+    }
+  }
+  return ok(
+    `${verb} plan #${ref.pr_id} → ${ref.url}${sourceSuffix}${linkSuffix}`,
+    {
+      issue: { id: ref.pr_id, url: ref.url },
+      plan_ref: ref,
+      cached: save.cached,
+      existed: save.existed,
+      updated: save.updated,
+      objective_node: nodeLink,
+      plan_source: save.source,
+    },
+    { terminate: true },
+  );
+}
+
+// ------------------------------------------------------------------------ the composition seam
+
+/**
+ * Build the full production dependency bag every plan-save surface consumes (the `plan_save`
+ * tool, `/plan-save`, `approvalSave`, AND the `plan_review` registration — ONE composition
+ * point, so no reverse edges and no duplicated composition): the branch-backed session, the
+ * cold-door `PlanBackend`, the D1a gate slice over `gating`, the best-effort planning-pointer
+ * capture (§8.35 — no-ops on absent identity), the transcript scrape thunk, and the byte-stable
+ * save rendering.
+ */
+export function planSaveDepsFor(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  gating: ToolGating,
+): PlanReviewV1Deps {
+  const session = openBranchWorkflowSession(pi, ctx);
+  return {
+    session,
+    backend: coldDoorPlanBackend(pi, ctx),
+    gate: { isActive: () => gating.isActive(), exit: () => gating.exit(ctx) },
+    capturePlanningPointer: () => {
+      // Capture the planning session pointer (contracts.md §8.35): this planning run self-keys
+      // by its own run_id into the shared main checkout, so a later/other session can resolve
+      // it cross-run. Best-effort + non-fatal (the carrier warns + returns false; a successful
+      // save must stand — and it no-ops on a blank/absent run id, the identity-less arm).
+      captureSessionPointer({
+        cwd: ctx.cwd,
+        runId: session.runId ?? "",
+        klass: "planning",
+        site: "main",
+        // Optional-chained: best-effort, and some side-session fakes have no getSessionFile.
+        sessionFile: ctx.sessionManager.getSessionFile?.(),
+      });
+    },
+    transcript: () => extractPlanMarkdown(branchOf(ctx)),
+    renderSave: (save) => renderSavePlanOutcome(ctx, save),
+  };
+}
+
+/**
+ * The shared approval→save orchestration seam, adapter-composed: an APPROVED review outcome
+ * (the `plan_review` door — the plannotator bridge AND the first-party in-TUI editor review;
+ * the `/plan-review-browser` door's decision routing) and the manual `/plan-save` failsafe all
+ * run THIS. Flow: artifact-first plan resolution (the reviewed plan text is the explicit
+ * fallback, the transcript scrape last) → `savePlan` (warm node-link recovery inside) → gate
+ * exit on a successful save while read-only (the D1a pattern). The returned rendered
+ * `SaveResult` keeps `terminate: true` for tool-path callers.
+ */
+export async function approvalSave(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  gating: ToolGating,
+  opts: { reviewedPlan?: string; title?: string } = {},
+): Promise<ApprovalSaveOutcome> {
+  const deps = planSaveDepsFor(pi, ctx, gating);
+  const outcome = await planApprovalSave(deps, opts);
+  if (outcome.status === "no-plan") return { status: "no-plan" };
+  return {
+    status: outcome.status,
+    result: deps.renderSave(outcome.result),
+    gateExited: outcome.gateExited,
+  };
+}
+
+// ------------------------------------------------------------------------------ the installer
+
+/**
+ * Install every plan Pi binding. Hook order is the frozen composition sequence — the plan-mode
+ * hook pair registers FIRST inside this installer (index.ts calls this at the slot the mode
+ * surface always held; the tombell/plannotator adapters follow); every tool/command
+ * registration is name-keyed and order-insensitive. `status` is the perk status handle's
+ * activity slice the plannotator arm's browser-wait activity rides. `wave` is the injected
+ * wave-launch deps (index.ts composes them from the door open cores); absent ⇒ the chooser never
+ * appears and every review path is byte-stable.
+ */
+export function installPlanBindings(
+  pi: ExtensionAPI,
+  gating: ToolGating,
+  reviews: DraftReviewSlot,
+  runnerChild: () => boolean,
+  status: ActivityHandle,
+  wave?: WaveLaunch,
+): void {
+  installPlanMode(pi, gating, runnerChild);
+
+  // ------------------------------------------------------------------- the plan_draft tool
+  // The working-draft file tool: the first session-data PRODUCER and the narrow structural
+  // read-only-gate carve-out (session data dir only). The tool takes NO path/name parameter —
+  // the artifact name is the fixed constant and the bytes flow through the session seam, so
+  // allowlisting its name in READ_ONLY_TOOLS (toolGating.ts) is safe.
+  pi.registerTool({
+    name: "plan_draft",
+    label: "Plan draft",
+    description:
+      "Write (or overwrite) the working plan draft to the session data dir and record its " +
+      "provenance pointer. The only sanctioned write surface while read-only. NOT a save — " +
+      "plan_save//plan-save still persist the plan to GitHub.",
+    promptSnippet: "Persist the working plan draft to the session data dir (full rewrite)",
+    // Registration prose stays INLINE (not a prose.ts constant): the prose-review workbench
+    // edits these arrays through the TypeScript source adapter, which needs literal in-place
+    // values — an identifier indirection is an unsupported source shape there.
+    promptGuidelines: [
+      "Call plan_draft to persist the current working draft as you author or revise the plan; pass the FULL plan markdown each time (it rewrites the whole draft).",
+      "plan_draft never saves to GitHub and never ends the turn — plan_save//plan-save remain the canonical save surface.",
+    ],
+    executionMode: "sequential",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      required: ["plan"],
+      properties: {
+        plan: {
+          type: "string",
+          description: "The full working-plan markdown (rewrites the whole draft).",
+        },
+      },
+    },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const decoded = decodePlanDraftParams(params);
+      if (decoded === null) {
+        return failFor(
+          ctx,
+          "plan-draft",
+          "plan_draft",
+        )("plan_draft needs { plan: string } per the tool schema", "bad_input");
+      }
+      const fail = failFor(ctx, "plan-draft");
+      const revised = revisePlanDraft(decoded, openBranchWorkflowSession(pi, ctx));
+      switch (revised.status) {
+        case "revised":
+        case "unchanged":
+          // A byte-identical rewrite short-circuits interior-side; the rendered result is
+          // computed from identical content either way, so the surface stays byte-stable.
+          return ok(`Plan draft written → ${revised.receipt.path} (${revised.receipt.digest})`, {
+            name: PLAN_DRAFT_ARTIFACT,
+            path: revised.receipt.path,
+            digest: revised.receipt.digest,
+            bytes: revised.bytes,
+            run_id: revised.receipt.runId,
+          });
+        case "rejected":
+          return fail(
+            revised.problem,
+            revised.reason === "blank_plan"
+              ? "invalid_input"
+              : revised.reason === "no_identity"
+                ? "no_run_id"
+                : "write_failed",
+          );
+        case "unverified":
+          return fail(revised.problem, "write_failed");
+      }
+    },
+  });
+
+  // ------------------------------------------------- the plan_save tool + /plan-save command
+  pi.registerTool({
+    name: "plan_save",
+    label: "Save plan",
+    description:
+      "Persist the current plan to GitHub as the canonical perk plan and link this session to it. " +
+      "Terminating: ends the turn on save. Call only when the plan is decision-complete.",
+    promptSnippet: "Save the decision-complete plan to GitHub (terminates the turn)",
+    promptGuidelines: [
+      "Use plan_save only after the plan is decision-complete and the user has agreed; it creates the canonical GitHub plan and ends the turn.",
+      "Keep the working draft current with plan_draft — the validated plan-draft artifact is what plan_save saves; the `plan` parameter is only a fallback when no draft exists. Never reference line numbers — use durable anchors (function names, behavioral descriptions, structural locations).",
+      "Pass plan_save's consumed_learn (the gathered perk:learn issue ids) only from the learned-docs factory — it links the issues the docs plan consolidates so /land closes + labels them.",
+      "When saving an objective-factory plan, pass plan_save BOTH objective_id and node_id — this links the node to the plan and advances it planning → in_progress (no separate backlink call).",
+    ],
+    executionMode: "sequential",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        plan: {
+          type: "string",
+          description:
+            "Optional — the validated plan-draft.md artifact is preferred when present; this " +
+            "param is the fallback for sessions that never wrote a draft (no line-number " +
+            "references).",
+        },
+        title: {
+          type: "string",
+          description: "Optional issue title (defaults to the plan's first heading).",
+        },
+        objective_id: {
+          type: "string",
+          description:
+            "Optional objective issue number to link this plan to (the objective plan factory " +
+            "passes the active objective; omit for a standalone plan).",
+        },
+        node_id: {
+          type: "string",
+          description:
+            "Objective node id to commit on save — the objective plan factory passes it with " +
+            "`objective_id` (links the node and advances it to `in_progress`); omit for a " +
+            "standalone plan.",
+        },
+        consumed_learn: {
+          type: "array",
+          items: { type: ["string", "number"] },
+          description:
+            "Optional perk:learn issue ids this docs plan consumes (the learned-docs factory " +
+            "passes the gathered ids; omit for a standalone plan). /land closes + labels them.",
+        },
+      },
+    },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const decoded = decodePlanSaveParams(params);
+      if (decoded === null) {
+        // The `label` arg matters: this handler-level closure renders "plan_save failed: …" while
+        // the save's internal failFor(ctx, "plan-save") stays as-is.
+        return failFor(
+          ctx,
+          "plan-save",
+          "plan_save",
+        )("plan_save needs { plan: string, … } per the tool schema", "bad_input");
+      }
+      // A refinement session never saves a plan — independent of the gate (a human toggle
+      // never makes an old plan draft routable here).
+      if (isRefinementSession(branchOf(ctx))) {
+        return failFor(
+          ctx,
+          "plan-save",
+          "plan_save",
+        )(refinementStageRefusal("plan_save"), "wrong_stage");
+      }
+      const deps = planSaveDepsFor(pi, ctx, gating);
+      // No read-only fail-fast here (D1a): the `plan_save` TOOL is structurally unreachable
+      // while read-only (the read-only allowlist excludes it), so reaching this handler means
+      // the gate is already off; the `/plan-save` COMMAND is allowed to run while read-only and
+      // exits the gate on a successful save (the read-only → read-write boundary in one gesture).
+      const src = resolvePlanSource(
+        {
+          draft: (() => {
+            const read = deps.session.readArtifact(PLAN_DRAFT_ARTIFACT);
+            return read.status === "found" ? read.content : null;
+          })(),
+          ...(decoded.plan !== undefined ? { explicit: decoded.plan } : {}),
+          transcript: deps.transcript,
+        },
+        "save",
+      );
+      if (src === null) {
+        return failFor(
+          ctx,
+          "plan-save",
+          "plan_save",
+        )(
+          "no plan to save — write the working draft with plan_draft, or pass the plan parameter",
+          "invalid_input",
+        );
+      }
+      const outcome = await savePlan(
+        {
+          plan: src.plan,
+          source: src.source,
+          paramMismatch: src.paramMismatch,
+          ...(decoded.title !== undefined ? { title: decoded.title } : {}),
+          ...(decoded.objective_id !== undefined ? { objectiveId: decoded.objective_id } : {}),
+          ...(decoded.node_id !== undefined ? { nodeId: decoded.node_id } : {}),
+          ...(decoded.consumed_learn !== undefined
+            ? { consumedLearn: decoded.consumed_learn }
+            : {}),
+        },
+        deps,
+      );
+      // The manual save never consults the latch (it IS the deliberate retry) but reports into it.
+      recordSaveOutcome(reviews, "plan", {
+        confirmed: outcome.status === "saved",
+        ...(outcome.status === "failed" ? { detail: outcome.message } : {}),
+      });
+      return deps.renderSave(outcome);
+    },
+  });
+
+  registerPerkCommand(pi, "plan-save", {
+    description:
+      "Save the latest proposed plan to GitHub — the manual failsafe for the approval→save flow " +
+      "(the read-only → read-write boundary).",
+    handler: async (args, ctx) => {
+      if (isRefinementSession(branchOf(ctx))) {
+        report(ctx, "plan-save", "warning", refinementStageRefusal("/plan-save"));
+        return;
+      }
+      const title = args.trim() || undefined;
+      // The manual-failsafe invocation of the shared approval→save seam. Artifact-first
+      // (no explicit param on the command path ⇒ paramMismatch is always false); the D1a gate exit
+      // lives in the seam. (The tool path never exits the gate — it is structurally unreachable
+      // while read-only.)
+      const outcome = await approvalSave(pi, ctx, gating, { title });
+      if (outcome.status === "no-plan") {
+        report(
+          ctx,
+          "plan-save",
+          "warning",
+          "no plan to save; write a draft with plan_draft, propose a plan, or call the plan_save tool.",
+          { alsoLog: true },
+        );
+        return;
+      }
+      // The manual save never consults the latch (it IS the deliberate retry) but reports into it.
+      recordSaveOutcome(reviews, "plan", {
+        confirmed: outcome.status === "saved",
+        ...(outcome.result.details.ok ? {} : { detail: outcome.result.details.error }),
+      });
+      // Severity reflects a failed objective-node advance: not-ok → error; saved-but-link-failed →
+      // warning; otherwise info. A failed node-link never blocks the gate exit above (the plan was
+      // saved) — but it MUST surface (the silent-partial-failure fix), in headless runs too.
+      const result = outcome.result;
+      const message = result.content[0]?.text ?? "plan-save done";
+      // `SaveResult` flows through `approvalSave` concretely — `details.ok` narrows the union,
+      // so the node-link severity read is typed (no assertion).
+      const details = result.details;
+      const severity: Severity = !details.ok
+        ? "error"
+        : details.objective_node?.linked === false
+          ? "warning"
+          : "info";
+      report(ctx, "plan-save", severity, message);
+    },
+  });
+
+  // -------------------------------------------------------------- the /implement-here command
+  // The sanctioned "implement here" exit from plan authoring (contracts.md §8.23): the
+  // read-only gate comes off WITHOUT saving to the issue backend. Human-only by construction:
+  // the two surfaces are the first-party review's 4th verdict (planReview.ts) and this command
+  // — no model tool exists, so the model can never choose to skip the backend on its own (the
+  // /btw posture). Deliberately OUTSIDE the PR lifecycle: no issue, no plan-ref, no branch —
+  // /submit, /address, and /land all key off `cache.plan-ref` and stay inapplicable. The
+  // plan-draft artifact is left untouched, so /plan-save can still create the canonical issue.
+  registerPerkCommand(pi, "implement-here", {
+    description:
+      "Exit plan mode WITHOUT saving an issue and implement the current plan draft in this " +
+      "session (the human-owned lightweight path).",
+    // The handler body lives in planReview.ts (next to the seam it composes — and so the
+    // sendUserMessage call sites stay out of this installer file, whose registration prose the
+    // prose-review workbench edits through the whole-file-validating TypeScript adapter).
+    handler: async (_args, ctx) => runImplementHereCommand(pi, ctx, gating, reviews),
+  });
+
+  // ---------------------------------------------------------------- the plan_review tool
+  // perk's universal review door. In READ_ONLY_TOOLS so it is callable INSIDE plan mode (the
+  // whole point — review happens before the gate ever comes off). Fail-open everywhere:
+  // headless / dismissed / backend-unavailable all soft-skip so authoring never wedges.
+  pi.registerTool({
+    name: "plan_review",
+    label: "Plan review",
+    description:
+      "Present the plan to the configured review surface — the Plannotator browser UI when " +
+      "selected, otherwise perk's in-TUI editor review — and wait for the human decision. " +
+      "Reviews the validated plan-draft artifact (keep it current with plan_draft); on approval " +
+      "the plan is auto-saved and the turn terminates. On deny, revise per the returned " +
+      "feedback, rewrite the draft with plan_draft, and call again. On the Plannotator surface " +
+      "the human may first opt into a streamed reviewer wave — the call then returns immediately " +
+      'with wave guidance (status "wave_launched") to follow in the same turn, and the browser ' +
+      "decision routes back automatically. No-op skip when the session is headless or the " +
+      "review is dismissed.",
+    promptSnippet: "Request a human review of the working plan draft",
+    promptGuidelines: [
+      "Keep the working draft current with plan_draft — the validated plan-draft artifact is what plan_review reviews AND auto-saves; the plan param is only a fallback when no draft exists.",
+      "Call plan_review only when the plan is decision-complete.",
+      "On a DENIED review, revise per the feedback, rewrite the draft with plan_draft, then call plan_review again.",
+      "On an APPROVED plan_review, the plan is auto-saved and the turn ends — never re-dump the plan as a final message and never tell the user to run /plan-save; relay the save outcome instead.",
+      "On a wave_launched result (the human opted into the reviewer wave), follow the returned guidance in the same turn — launch the wave and relay its findings; the human's browser decision routes back automatically, so never re-call plan_review while that browser review is open.",
+      "If plan_review reports it was skipped or unavailable (headless, dismissed), fall back to presenting the complete plan; the human runs /plan-save (the manual failsafe).",
+    ],
+    executionMode: "sequential",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        plan: {
+          type: "string",
+          description:
+            "Optional — the validated plan-draft.md artifact is preferred when present; this " +
+            "param is the fallback for sessions that never wrote a draft.",
+        },
+      },
+    },
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      // Per call: the activity wait binds the live `ctx` (the bridge itself is a thin object).
+      const bridge = createPlannotatorBridge(pi.events, (text) => status.beginActivity(ctx, text));
+      return executePlanReview(
+        pi,
+        ctx,
+        gating,
+        bridge,
+        reviews,
+        planSaveDepsFor(pi, ctx, gating),
+        params,
+        signal,
+        wave,
+      );
+    },
+  });
+}
+
+// -------------------------------------------------------------------------------- plan mode
+
+/**
+ * The perk-owned plan-mode toggle surface over the read-only gate: idempotent enter/exit (the
+ * gate tracks its own on/off transition), fail-safe-headless (notify when UI, else stderr), and
+ * the plan-authoring context injection. Three-tier registration branch (see the module header):
+ * full registration for the reference (fail-safe default), a PARTIAL vacate (skip only `--plan`
+ * + `Ctrl+Alt+P`) under the augment-posture plannotator selection, and a full vacate under any
+ * other foreign selection (tombell).
+ */
+function installPlanMode(pi: ExtensionAPI, gating: ToolGating, runnerChild: () => boolean): void {
+  const providerId = resolvedPlanProviderId(process.cwd());
+  const plannotatorSelected = providerId === PLANNOTATOR_PLAN_PROVIDER_ID;
+  if (providerId !== PERK_PLAN_PROVIDER_ID && !plannotatorSelected) return;
+
+  if (!plannotatorSelected) {
+    pi.registerFlag("plan", {
+      description: "Start in perk plan mode (read-only exploration + plan authoring).",
+      type: "boolean",
+      default: false,
+    });
+  }
+
+  function announce(ctx: ExtensionContext, on: boolean): void {
+    const message = on
+      ? "plan mode ON — read-only exploration; author the plan, then review with plan_review (approval auto-saves; /plan-save is the manual failsafe)."
+      : "plan mode OFF — full tool access restored.";
+    report(ctx, "plan-mode", "info", message);
+  }
+
+  function toggle(ctx: ExtensionContext): void {
+    if (gating.isActive()) {
+      gating.exit(ctx);
+      announce(ctx, false);
+    } else {
+      gating.enter(ctx);
+      announce(ctx, true);
+    }
+  }
+
+  registerPerkCommand(pi, "plan", {
+    description: "Toggle perk plan mode (read-only exploration + plan authoring).",
+    handler: async (_args, ctx) => toggle(ctx),
+  });
+
+  if (!plannotatorSelected) {
+    pi.registerShortcut(Key.ctrlAlt("p"), {
+      description: "Toggle perk plan mode",
+      handler: async (ctx) => toggle(ctx),
+    });
+
+    // `--plan` cold start: enter read-only on session_start when the flag is set and the gate is
+    // off. (index.ts's session_start already syncs the gate from the rebuilt `mode`; this layers
+    // the flag on top for ad-hoc `pi --plan` interactive starts — the cold plan door drives
+    // read-only via the handoff `mode`, not this flag.) Skipped under the plannotator selection
+    // along with the flag itself (the flag no longer exists on perk's side).
+    pi.on("session_start", async (_event, ctx) => {
+      if (pi.getFlag("plan") === true && !gating.isActive()) {
+        gating.enter(ctx);
+      }
+    });
+  }
+
+  // Inject the plan-authoring context while the read-only gate is active (display:false) for
+  // every stage no other authoring context owns (`isPlanGuidanceStage` over the FULL-branch
+  // stage): the stage-less warm `/plan`, the cold `plan`/`objective-plan` claims, a worktree stage
+  // with `/plan` toggled on. The objective/gist/refinement installers own their stages, so a
+  // plan-mode turn followed by a warm `/objective-refine` retires the plan context there
+  // (selection is also the retention decision — the shared helper strips the owned custom once
+  // selection turns null). The runner fence lives in the shared helper.
+  installInjectedContext(
+    pi,
+    {
+      customType: PLAN_CONTEXT_TYPE,
+      flavors: {
+        [PLAN_MARKER]: (ctx) => planAuthoringContextContent(loadPerkConfig(ctx.cwd).planAuthoring),
+      },
+      select: (_ctx, branch) =>
+        gating.isActive() && isPlanGuidanceStage(rebuildWorkflowState(branch).stage)
+          ? PLAN_MARKER
+          : null,
+    },
+    runnerChild,
+  );
+}