@mgiles/perk 3.1.0 → 3.3.0

package/extension/authoring/plan/prose.ts

@@ -0,0 +1,41 @@
+// The plan feature's model-facing prose units: the plan-authoring context content builder and
+// the injection marker/customType constants. Prose-unit MEANING lives here (the feature); the
+// v1 adapter only PLACES these units in Pi context payloads (module-contracts.md's prose
+// split). The tool registration prose (descriptions + promptGuidelines) deliberately stays
+// INLINE at the `pi/v1/plan.ts` registration sites — the prose-review workbench edits
+// registration prose through the TypeScript source adapter, which needs literal in-place
+// arrays (an identifier indirection is an unsupported source shape there). Prompting, NOT
+// enforcement — the read-only tool gate is the enforcement.
+//
+// Carve-out doctrine (mirrors `authoring/gist/`): this home is Pi-free (guard Rule D) — the
+// adapter passes config-derived values (the `[workflow] plan_authoring` addendum) in as plain
+// strings; nothing here reads Pi, the config loader, or the surfaces seam.
+
+import { render } from "../../substrate/prompts.ts";
+
+/** The plan-authoring context customType (distinct from the gate's `perk:mode-context`). */
+export const PLAN_CONTEXT_TYPE = "perk:plan-context";
+
+/** The injected plan-authoring context's identity marker (the strip + dedup key). */
+export const PLAN_MARKER = "[PLAN AUTHORING]";
+
+/**
+ * The cooperative gather-then-plan contract. This is prompting, NOT enforcement (the gate is the
+ * enforcement). It never leaks internal policy text — it tells the model how to materialize a
+ * decision-complete plan an executor with zero prior context can follow. Per contracts.md §8.57
+ * this mode context is the plan stage's DESIGNATED FLOW CARRIER in every plan-stage session
+ * shape (seeded doors carry launch-shape deltas only; the `perk-plan` skill is the detail tier).
+ * Durable anchors only, no line numbers.
+ */
+export const PLAN_AUTHORING_CONTEXT = render("contexts/plan-authoring.md", {
+  marker: PLAN_MARKER,
+});
+
+/**
+ * Build the full plan-authoring injection, appending the project-config authoring addendum when
+ * present. Pure over the addendum — the ADAPTER loads `[workflow] plan_authoring` per event and
+ * passes the value in (the narrow-views doctrine).
+ */
+export function planAuthoringContextContent(addendum: string | undefined): string {
+  return addendum ? `${PLAN_AUTHORING_CONTEXT}\n\n${addendum.trim()}` : PLAN_AUTHORING_CONTEXT;
+}

package/extension/authoring/plan/review.ts

@@ -0,0 +1,269 @@
+// The plan review feature: the `PlanDraftReviewer` role (one production adapter per review
+// backend — plannotator bridge or first-party editor, both built in pi/v1 — plus a scripted fake
+// in the tests), the reviewer-edits mechanical-apply ladder, and the one-entry `reviewPlanDraft`
+// operation.
+//
+// Ordering is the review door's exact discipline: resolve FIRST (artifact → param ONLY — the
+// review surface never sees a transcript tier; none ⇒ `noPlan`) → review → the abort checkpoint
+// → route the verdict. Provider vocabulary (plannotator's `# Direct Edits` prose) is translated
+// INTO `PlanReviewOutcome` at the adapter — the feature sees typed variants only.
+//
+// Cancellation ownership: `signal?.aborted` is checked at entry AND re-checked immediately
+// after `reviewer.review` resolves, BEFORE any effect (apply ladder, save, gate exit) — abort ⇒
+// the `aborted` arm with nothing saved and the gate untouched. The backend save itself is not
+// abortable mid-flight (today's behavior, stated in save.ts).
+//
+// The gate-safety invariant is FEATURE-OWNED: an `implementHere` verdict under
+// `allowImplementHere: false` (an objective-node planning session — a node-linked plan must
+// save) REFUSES with the distinct `implementHereRefused` arm — nothing saved, gate untouched.
+// The adapter's verdict suppression under a node claim remains the UX layer (the option is
+// never offered); this arm is the defensive backstop.
+
+import type { WorkflowSession } from "../../session/workflowSession.ts";
+import { applyUnifiedDiff } from "../../substrate/unifiedDiff.ts";
+import type { ApprovalGate } from "../review/approvalGate.ts";
+import { PLAN_DRAFT_ARTIFACT, resumePlanDraft } from "./draft.ts";
+import {
+  type PlanApprovalSaveOutcome,
+  type PlanBackend,
+  type PlanSaveDeps,
+  planApprovalSave,
+} from "./save.ts";
+import { resolvePlanSource } from "./source.ts";
+
+/**
+ * The reviewer's verdict on the plan bytes. `approvedDirectEdits` carries the reviewer's
+ * extracted unified diff (`remainder` is the annotation feedback surviving after the applied
+ * section is stripped; `rawFeedback` the FULL original — the fail-open ladder saves verbatim
+ * with it). `approvedEditsUnparseable` is the seen-heading/unextractable-diff arm: the section
+ * was seen but cannot be honored — verbatim save of the ORIGINAL bytes with the FULL feedback
+ * preserved and the loud `directEditsFailed` flag.
+ */
+export type PlanReviewOutcome =
+  | { status: "approved"; feedback?: string; reviewId?: string }
+  | {
+      status: "approvedDirectEdits";
+      diff: string;
+      remainder?: string;
+      rawFeedback: string;
+      reviewId?: string;
+    }
+  | { status: "approvedEditsUnparseable"; rawFeedback: string; reviewId?: string }
+  | { status: "denied"; feedback?: string; reviewId?: string }
+  | { status: "implementHere"; reviewId: string }
+  | { status: "dismissed" }
+  | { status: "aborted" }
+  | { status: "unavailable"; warning: string };
+
+/**
+ * What one review round produced: the typed outcome, the FINAL reviewed bytes (`plan`), and
+ * whether the human edited them. The first-party reviewer adapter writes human edits back to
+ * the draft INSIDE the reviewer (before the verdict — a failed write-back is the `unavailable`
+ * abort), so `plan` is the final reviewed bytes and `edited` the differ bit; the plannotator
+ * reviewer returns the input unchanged (`edited: false` — browser edits arrive as the Direct
+ * Edits diff on the outcome, applied feature-side).
+ */
+export type PlanDraftReviewResult = { outcome: PlanReviewOutcome; plan: string; edited: boolean };
+
+/** The reviewer role: judge the resolved plan bytes. */
+export interface PlanDraftReviewer {
+  review(plan: string, signal?: AbortSignal): Promise<PlanDraftReviewResult>;
+}
+
+/**
+ * The plan-arm mechanical-apply ladder for reviewer edits: strict `applyUnifiedDiff` → draft
+ * write-back through the session (reviewed bytes == artifact bytes == saved bytes). Every rung
+ * fails open — the caller renders the loud warning and saves verbatim. Never throws.
+ */
+export function applyReviewerEdits(
+  session: WorkflowSession,
+  basePlan: string,
+  edits: { diff: string },
+): { status: "applied"; plan: string } | { status: "failed" } {
+  const patched = applyUnifiedDiff(basePlan, edits.diff);
+  if (patched === null) return { status: "failed" };
+  const written = session.writeArtifact(PLAN_DRAFT_ARTIFACT, patched);
+  if (written.status !== "applied" && written.status !== "unchanged") return { status: "failed" };
+  return { status: "applied", plan: patched };
+}
+
+/** The review-operation dependency bag (the adapter composes production values). */
+export interface ReviewPlanDraftDeps extends PlanSaveDeps {
+  reviewer: PlanDraftReviewer;
+  backend: PlanBackend;
+  gate: ApprovalGate;
+  /** The `plan` param fallback (the artifact wins; review mode never sees a transcript). */
+  explicit?: string;
+  /** False in an objective-node planning session — the no-save exit refuses there. */
+  allowImplementHere: boolean;
+}
+
+/** The plan-arm save flags every approved arm carries (the adapter's rendering opts). */
+interface ApprovedFlags {
+  feedback?: string;
+  reviewId?: string;
+  paramMismatch: boolean;
+  edited: boolean;
+  directEditsFailed: boolean;
+}
+
+/** The one-entry review outcome — each arm carries exactly what its caller renders. */
+export type ReviewPlanDraftResult =
+  | { status: "noPlan" }
+  | ({
+      status: "approvedSaved";
+      save: Extract<PlanApprovalSaveOutcome, { status: "saved" }>;
+    } & ApprovedFlags)
+  | ({
+      status: "approvedSaveFailed";
+      save: Extract<PlanApprovalSaveOutcome, { status: "save-failed" }>;
+    } & ApprovedFlags)
+  | ({ status: "approvedNoPlan" } & ApprovedFlags)
+  | {
+      status: "implementHere";
+      reviewId: string;
+      gateExited: boolean;
+      plan: string;
+      edited: boolean;
+    }
+  | { status: "implementHereRefused" }
+  | { status: "denied"; feedback?: string; reviewId?: string }
+  | { status: "dismissed" }
+  | { status: "aborted" }
+  | { status: "unavailable"; warning: string };
+
+/**
+ * Review the working plan draft end-to-end: resolve (artifact → param ONLY; none ⇒ `noPlan`) →
+ * review → the abort checkpoint → route. Routing: `approvedDirectEdits` ⇒ the apply ladder
+ * (success ⇒ save the EDITED bytes with `edited: true` + remainder-only feedback; failure ⇒
+ * verbatim save + `directEditsFailed`) · `approvedEditsUnparseable` ⇒ verbatim save + the FULL
+ * raw feedback + `directEditsFailed` (fail-open-but-loud) · `approved` ⇒ `planApprovalSave`
+ * with the reviewed bytes (`edited` rides into the flags) · `implementHere` ⇒ gate exit WITHOUT
+ * save when allowed, else the `implementHereRefused` refusal · everything else passes through.
+ * Never throws.
+ */
+export async function reviewPlanDraft(
+  deps: ReviewPlanDraftDeps,
+  signal?: AbortSignal,
+): Promise<ReviewPlanDraftResult> {
+  if (signal?.aborted) return { status: "aborted" };
+  const src = resolvePlanSource(
+    { draft: resumePlanDraft(deps.session), explicit: deps.explicit },
+    "review",
+  );
+  if (src === null) return { status: "noPlan" };
+
+  const result = await deps.reviewer.review(src.plan, signal);
+  // The abort checkpoint: a turn interrupted while the reviewer ran must produce NO effect —
+  // no apply ladder, no save, no gate exit (the aborted arm wins over any verdict).
+  if (signal?.aborted) return { status: "aborted" };
+  return completePlanReview(deps, result, {
+    source: src.source === "plan-draft" ? "plan-draft" : "param",
+    paramMismatch: src.paramMismatch,
+  });
+}
+
+/** Subject policy only: callers authorize effects before entering this completion seam. */
+export async function completePlanReview(
+  deps: Omit<ReviewPlanDraftDeps, "reviewer" | "explicit">,
+  result: PlanDraftReviewResult,
+  source: { source: "plan-draft" | "param"; paramMismatch: boolean },
+): Promise<ReviewPlanDraftResult> {
+  const outcome = result.outcome;
+  const approvalSave = (reviewedPlan: string): Promise<PlanApprovalSaveOutcome> =>
+    planApprovalSave(deps, { boundSource: { plan: reviewedPlan, ...source } });
+  const flags = (
+    partial: Pick<ApprovedFlags, "feedback" | "reviewId"> &
+      Partial<Pick<ApprovedFlags, "edited" | "directEditsFailed">>,
+  ): ApprovedFlags => ({
+    ...(partial.feedback !== undefined ? { feedback: partial.feedback } : {}),
+    ...(partial.reviewId !== undefined ? { reviewId: partial.reviewId } : {}),
+    paramMismatch: source.paramMismatch,
+    edited: partial.edited ?? false,
+    directEditsFailed: partial.directEditsFailed ?? false,
+  });
+  const savedResult = (save: PlanApprovalSaveOutcome, f: ApprovedFlags): ReviewPlanDraftResult => {
+    switch (save.status) {
+      case "saved":
+        return { status: "approvedSaved", save, ...f };
+      case "save-failed":
+        return { status: "approvedSaveFailed", save, ...f };
+      case "no-plan":
+        return { status: "approvedNoPlan", ...f };
+    }
+  };
+
+  switch (outcome.status) {
+    case "approvedDirectEdits": {
+      // Mechanically apply the reviewer's diff to the exact bytes reviewed, write the patched
+      // bytes back to the draft, and save THOSE (only the annotation remainder survives as
+      // feedback — the applied diff must never render as "apply these exact changes" guidance).
+      // Any rung failing falls open to the verbatim save + the loud directEditsFailed flag.
+      const applied = applyReviewerEdits(deps.session, result.plan, { diff: outcome.diff });
+      if (applied.status === "applied") {
+        return savedResult(
+          await approvalSave(applied.plan),
+          flags({
+            ...(outcome.remainder !== undefined ? { feedback: outcome.remainder } : {}),
+            ...(outcome.reviewId !== undefined ? { reviewId: outcome.reviewId } : {}),
+            edited: true,
+          }),
+        );
+      }
+      return savedResult(
+        await approvalSave(result.plan),
+        flags({
+          feedback: outcome.rawFeedback,
+          ...(outcome.reviewId !== undefined ? { reviewId: outcome.reviewId } : {}),
+          directEditsFailed: true,
+        }),
+      );
+    }
+    case "approvedEditsUnparseable":
+      // The seen-heading/unextractable-diff arm: verbatim save of the ORIGINAL bytes, the FULL
+      // feedback preserved, plus the loud warning flag (fail-open-but-loud).
+      return savedResult(
+        await approvalSave(result.plan),
+        flags({
+          feedback: outcome.rawFeedback,
+          ...(outcome.reviewId !== undefined ? { reviewId: outcome.reviewId } : {}),
+          directEditsFailed: true,
+        }),
+      );
+    case "approved":
+      return savedResult(
+        await approvalSave(result.plan),
+        flags({
+          ...(outcome.feedback !== undefined ? { feedback: outcome.feedback } : {}),
+          ...(outcome.reviewId !== undefined ? { reviewId: outcome.reviewId } : {}),
+          edited: result.edited,
+        }),
+      );
+    case "implementHere": {
+      if (!deps.allowImplementHere) return { status: "implementHereRefused" };
+      // The sanctioned no-save exit (contracts §8.23): gate off WITHOUT saving; the draft
+      // artifact stays intact so /plan-save can still create the canonical issue later.
+      const wasActive = deps.gate.isActive();
+      if (wasActive) deps.gate.exit();
+      return {
+        status: "implementHere",
+        reviewId: outcome.reviewId,
+        gateExited: wasActive,
+        plan: result.plan,
+        edited: result.edited,
+      };
+    }
+    case "denied":
+      return {
+        status: "denied",
+        ...(outcome.feedback !== undefined ? { feedback: outcome.feedback } : {}),
+        ...(outcome.reviewId !== undefined ? { reviewId: outcome.reviewId } : {}),
+      };
+    case "dismissed":
+      return { status: "dismissed" };
+    case "aborted":
+      return { status: "aborted" };
+    case "unavailable":
+      return { status: "unavailable", warning: outcome.warning };
+  }
+}

package/extension/authoring/plan/save.ts

@@ -0,0 +1,256 @@
+// The plan save feature: the narrow exterior `PlanBackend` port (one production adapter — the
+// `perk plan save` cold door in pi/v1 — plus one deterministic fake in the tests: the port
+// admission rule), the `savePlan` operation, and the shared APPROVED-review → save orchestration
+// `planApprovalSave` (the exported name contracts.md §8.23 pins — the `gistApprovalSave`
+// mirror).
+//
+// Identity-less saves stay legal and fully specified: `session.runId === null` ⇒ the backend
+// sees `runId: null` (the adapter omits `--run-id`), pointer capture no-ops in the adapter, and
+// the LINKAGE + CLAIM ops still run — workflow-state appends are branch-backed and
+// identity-independent (today's behavior, preserved). Backend saves are not abortable
+// mid-flight (today's behavior — stated, not changed).
+
+import type {
+  PlanRef,
+  WorkflowChangeResult,
+  WorkflowSession,
+} from "../../session/workflowSession.ts";
+import { type ApprovalGate, saveThroughApprovalGate } from "../review/approvalGate.ts";
+import { resumePlanDraft } from "./draft.ts";
+import { type PlanSource, resolvePlanSource } from "./source.ts";
+
+/** The atomic objective node→plan commit surfaced by `perk plan save`. */
+export interface ObjectiveNodeLink {
+  linked: boolean;
+  node: string | null;
+  status: string | null;
+  error: string | null;
+}
+
+/** The backend save facts (`ref.pr_id` is the opaque string issue id — contracts §8.21). */
+export type PlanBackendSaveResult =
+  | {
+      status: "saved";
+      ref: PlanRef;
+      existed: boolean | null;
+      updated: boolean;
+      cached: boolean;
+      nodeLink: ObjectiveNodeLink | null;
+    }
+  | { status: "failed"; message: string; errorType: string };
+
+/**
+ * The narrow exterior port the save operation writes through. `runId: null` means the caller
+ * has no session identity — the backend omits its run linkage (an identity-less save keeps
+ * working).
+ */
+export interface PlanBackend {
+  save(req: {
+    plan: string;
+    title?: string;
+    runId: string | null;
+    objectiveId?: string;
+    nodeId?: string;
+    consumedLearn?: string[];
+  }): Promise<PlanBackendSaveResult>;
+}
+
+/**
+ * The save outcome. The saved arm carries the backend facts PLUS the resolution facts
+ * (`source`/`paramMismatch` ride through for the adapter's message assembly) and the two
+ * workflow-state results — the session seam's own `WorkflowChangeResult` values passed through
+ * VERBATIM (lossless by construction; `null` means not attempted: `linkage` when the save
+ * failed before it, `claimClear` when there was no matching claim / no node link). The
+ * production adapter's rendering ignores both fields (byte-stable output); they exist so the
+ * feature outcome is honest and the direct feature tests can pin every arm — the seam's type,
+ * not new API surface.
+ */
+export type SavePlanOutcome =
+  | {
+      status: "saved";
+      ref: PlanRef;
+      existed: boolean | null;
+      updated: boolean;
+      cached: boolean;
+      nodeLink: ObjectiveNodeLink | null;
+      source: PlanSource | null;
+      paramMismatch: boolean;
+      linkage: WorkflowChangeResult | null;
+      claimClear: WorkflowChangeResult | null;
+    }
+  | { status: "failed"; message: string; errorType: string };
+
+/** The dependency bag the save operation runs over (the adapter composes production values). */
+export interface PlanSaveDeps {
+  session: WorkflowSession;
+  backend: PlanBackend;
+  /** Best-effort planning-pointer capture (contracts §8.35; no-ops on absent identity). */
+  capturePlanningPointer(): void;
+}
+
+/**
+ * The single save operation every plan-save surface calls. Ordering preserved exactly: validate
+ * the non-blank plan → resolve the title (an explicit title is trimmed and forwarded; else omitted
+ * so the cold door derives it) → warm node-claim recovery (BOTH link params absent ⇒ fill both from
+ * `session.nodeClaim()`; any explicit value — even one — wins outright, never mixed) →
+ * `backend.save` → `capturePlanningPointer()` (best-effort thunk) → link the live session
+ * (`apply({kind:"link-plan-ref"})` — append iff the ref differs) → on a node-linked save whose
+ * FULL claim identity matches (resolved objective + linked node), clear the claim
+ * (`apply({kind:"clear-node-claim"})` — an unrelated claim is never clobbered). Never throws.
+ */
+export async function savePlan(
+  input: {
+    plan: string;
+    title?: string;
+    objectiveId?: string;
+    nodeId?: string;
+    consumedLearn?: string[];
+    /** The resolved plan source — surfaced in the adapter's message when non-param. */
+    source?: PlanSource;
+    /** A differing explicit param was ignored in favor of the artifact (visibly flagged). */
+    paramMismatch?: boolean;
+  },
+  deps: PlanSaveDeps,
+): Promise<SavePlanOutcome> {
+  const plan = input.plan.trim();
+  if (!plan) {
+    return {
+      status: "failed",
+      message: "no plan markdown to save (propose a plan first)",
+      errorType: "invalid_input",
+    };
+  }
+
+  // Forward an explicit (trimmed, non-blank) title; when absent the flag is omitted and the cold
+  // door derives one from the plan's first `# ` heading (`plan.derive_title`).
+  const title = input.title?.trim() || undefined;
+
+  // Warm node-link recovery. When BOTH link params are absent (an approval-triggered save
+  // carries no model params), fill both-or-neither from the rebuilt `objective_node_claim`. Any
+  // explicit value (even one) wins outright — a half-specified link is the caller's, never
+  // mixed with the claim. Fail-open: a malformed/missing claim never blocks a save
+  // (`nodeClaim()` returns null). Mirrors the cold `_link_from_handoff`.
+  let objectiveId = input.objectiveId;
+  let nodeId = input.nodeId;
+  if (objectiveId === undefined && nodeId === undefined) {
+    const claim = deps.session.nodeClaim();
+    if (claim !== null) {
+      objectiveId = claim.objective;
+      nodeId = claim.node;
+    }
+  }
+
+  const saved = await deps.backend.save({
+    plan,
+    ...(title !== undefined ? { title } : {}),
+    runId: deps.session.runId,
+    ...(objectiveId !== undefined ? { objectiveId } : {}),
+    ...(nodeId !== undefined ? { nodeId } : {}),
+    ...(input.consumedLearn !== undefined ? { consumedLearn: input.consumedLearn } : {}),
+  });
+  if (saved.status === "failed") return saved;
+
+  // Capture the planning session pointer (contracts.md §8.35): best-effort + non-fatal (the
+  // carrier warns + no-ops on absent identity; a successful save must stand).
+  deps.capturePlanningPointer();
+
+  // Link the live session: the seam appends iff the rebuilt ref differs, with a strict
+  // read-back — verbatim into the outcome (the adapter's rendering ignores it; the append
+  // helper's report() stays the loudness channel).
+  const linkage = deps.session.apply({ kind: "link-plan-ref", ref: saved.ref });
+
+  // A successful node-linked save clears the matching claim (best-effort — failure only risks
+  // a stale claim silently linking a later, unrelated save; surfaced via the seam's loud
+  // report()). The FULL claim identity must match — the resolved objective AND the linked node
+  // — so a save linked to objective B node 1.1 never clears objective A's standing 1.1 claim.
+  let claimClear: WorkflowChangeResult | null = null;
+  if (saved.nodeLink?.linked === true) {
+    const linkedNode = saved.nodeLink.node ?? nodeId ?? null;
+    const claim = deps.session.nodeClaim();
+    if (
+      linkedNode !== null &&
+      claim !== null &&
+      claim.node === linkedNode &&
+      claim.objective === objectiveId
+    ) {
+      claimClear = deps.session.apply({
+        kind: "clear-node-claim",
+        claim: { objective: claim.objective, node: linkedNode },
+      });
+    }
+  }
+
+  return {
+    status: "saved",
+    ref: saved.ref,
+    existed: saved.existed,
+    updated: saved.updated,
+    cached: saved.cached,
+    nodeLink: saved.nodeLink,
+    source: input.source ?? null,
+    paramMismatch: input.paramMismatch ?? false,
+    linkage,
+    claimClear,
+  };
+}
+
+/** The approval→save orchestration outcome (the plan `GistApprovalSaveOutcome` mirror). */
+export type PlanApprovalSaveOutcome =
+  | { status: "no-plan" }
+  | { status: "saved"; result: Extract<SavePlanOutcome, { status: "saved" }>; gateExited: boolean }
+  | {
+      status: "save-failed";
+      result: Extract<SavePlanOutcome, { status: "failed" }>;
+      gateExited: false;
+    };
+
+/** The approval→save dependency bag: the save deps + the gate + the save-mode transcript tier. */
+export interface PlanApprovalSaveDeps extends PlanSaveDeps {
+  gate: ApprovalGate;
+  /** The transcript-scrape thunk (save-mode last resort); omit where the tier cannot apply. */
+  transcript?: () => string | null;
+}
+
+/**
+ * The shared APPROVED-review → save orchestration (an APPROVED `plan_review` outcome and the
+ * manual `/plan-save` failsafe both run THIS — contracts §8.23 pins the name). Flow:
+ * explicit `boundSource` for review completion, otherwise artifact-first resolution
+ * (`resolvePlanSource` — `reviewedPlan` is the explicit fallback, the transcript scrape last) → `savePlan` (warm node-claim recovery happens inside) through
+ * `saveThroughApprovalGate` (the D1a invariant: snapshot before the save; exit only after a
+ * successful save while read-only; a failed save leaves the gate ON). No resolvable plan
+ * source → `no-plan` (nothing saved, the gate untouched); callers render their own fallback.
+ */
+export async function planApprovalSave(
+  deps: PlanApprovalSaveDeps,
+  opts: {
+    reviewedPlan?: string;
+    title?: string;
+    /** Explicit reviewed bytes; never re-resolve a partially written patch from the artifact. */
+    boundSource?: { plan: string; source: "plan-draft" | "param"; paramMismatch: boolean };
+  } = {},
+): Promise<PlanApprovalSaveOutcome> {
+  const src =
+    opts.boundSource ??
+    resolvePlanSource(
+      {
+        draft: resumePlanDraft(deps.session),
+        ...(opts.reviewedPlan !== undefined ? { explicit: opts.reviewedPlan } : {}),
+        ...(deps.transcript !== undefined ? { transcript: deps.transcript } : {}),
+      },
+      "save",
+    );
+  if (src === null) return { status: "no-plan" };
+  const { outcome: result, gateExited } = await saveThroughApprovalGate(deps.gate, () =>
+    savePlan(
+      {
+        plan: src.plan,
+        source: src.source,
+        paramMismatch: src.paramMismatch,
+        ...(opts.title !== undefined ? { title: opts.title } : {}),
+      },
+      deps,
+    ),
+  );
+  if (result.status === "failed") return { status: "save-failed", result, gateExited: false };
+  return { status: "saved", result, gateExited };
+}

package/extension/authoring/plan/source.ts

@@ -0,0 +1,82 @@
+// The plan-source feature: where saved/reviewed plan bytes come from. The FILE-FIRST resolution
+// law both save surfaces and the review door share: the validated `plan-draft.md` artifact wins;
+// the explicit `plan` param is the fallback; the transcript scrape is the universal last resort
+// FOR SAVES ONLY — the review surface never sees a transcript tier (an approval auto-saves the
+// reviewed bytes, and scraped conversation bytes must never be those).
+//
+// Pi-free (guard Rule D): the tiers arrive as plain values/thunks — the ADAPTER reads the draft
+// through the session seam and binds the transcript scrape over its branch.
+
+/** Where the saved plan bytes came from (the file-first resolution order). */
+export type PlanSource = "plan-draft" | "param" | "transcript";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+/** The joined text of a message's content blocks (fail-open: malformed blocks contribute ""). */
+function textOf(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((block) =>
+      isRecord(block) && block.type === "text" && typeof block.text === "string" ? block.text : "",
+    )
+    .filter(Boolean)
+    .join("\n");
+}
+
+/**
+ * Best-effort, deterministic: the whole text of the latest assistant message, or null. This is
+ * the universal fail-open transcript FALLBACK behind the validated plan-draft artifact (see
+ * `resolvePlanSource`) — never a review source. Inherently fragile (it cannot tell a clean plan
+ * from conversation): keep the working draft current with `plan_draft` so the validated
+ * artifact wins. (There is no tag/marker convention to extract — the borrowed plan-mode package
+ * emits no structured plan, only free-form prose.) Fail-open by construction: entries are
+ * UNTRUSTED session history, so every field is proven before dereference — a null/sparse entry,
+ * a primitive, or a malformed content block is skipped, never thrown on.
+ */
+export function extractPlanMarkdown(entries: readonly unknown[]): string | null {
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (!isRecord(entry) || entry.type !== "message") continue;
+    const message = entry.message;
+    if (!isRecord(message) || message.role !== "assistant") continue;
+    const text = textOf(message.content).trim();
+    if (!text) continue;
+    return text;
+  }
+  return null;
+}
+
+/**
+ * The shared plan-source resolver every plan surface uses. Resolution order: (1) a non-blank
+ * validated draft (the caller has already collapsed absent/invalid reads to `null`); (2) a
+ * non-blank explicit param; (3) — save mode only — the transcript scrape thunk; else null.
+ *
+ * `paramMismatch` is true iff the artifact won AND a non-blank explicit param was passed whose
+ * trimmed bytes differ from the artifact's — surfaced by the save rendering, never silently
+ * dropped and never a hard-fail. Review mode NEVER sees a transcript tier (the review-surface
+ * law): a caller that passes a transcript thunk in review mode still resolves null.
+ */
+export function resolvePlanSource(
+  tiers: { draft: string | null; explicit?: string; transcript?: () => string | null },
+  mode: "save" | "review",
+): { plan: string; source: PlanSource; paramMismatch: boolean } | null {
+  if (tiers.draft !== null && tiers.draft.trim().length > 0) {
+    const param = tiers.explicit?.trim() ?? "";
+    return {
+      plan: tiers.draft,
+      source: "plan-draft",
+      paramMismatch: param.length > 0 && param !== tiers.draft.trim(),
+    };
+  }
+  if (tiers.explicit !== undefined && tiers.explicit.trim().length > 0) {
+    return { plan: tiers.explicit, source: "param", paramMismatch: false };
+  }
+  if (mode === "save" && tiers.transcript !== undefined) {
+    const scraped = tiers.transcript();
+    if (scraped !== null) return { plan: scraped, source: "transcript", paramMismatch: false };
+  }
+  return null;
+}