@mgiles/perk 2.1.0 → 2.2.0

package/extension/factories/gistSave.ts

@@ -0,0 +1,251 @@
+// The warm `gist_save` door, the gist mirror of objectiveSave.ts. The in-session twin of the
+// Python cold door (`perk gist create`): a deterministic, terminating tool + command that WRAP
+// the existing storage — they do NOT reimplement the backend write. `saveGist()` delegates to
+// `perk gist create --json` via the shared cold-door client (`runColdDoor`, the prose rides the
+// run-scratch stdin channel). Unlike the plan/objective twins there is NO session linkage after
+// the save — nothing consumes a gist in-session (adoption happens later via the cold doors), so
+// a successful save just relays the envelope's id/url/consumption story.
+//
+// APPROVAL→SAVE ORCHESTRATION (mirroring objectiveSave.ts's `objectiveApprovalSave`). The
+// exported `gistApprovalSave` seam is the shared APPROVED-review → save flow: re-read the
+// artifact (`readGistDraft` — never the rendered markdown, never the transcript) → `saveGist` →
+// D1a gate exit on a successful save (snapshot `gating.isActive()` BEFORE the save; a failed
+// save leaves the gate ON). `plan_review`'s gist arm (planReview.ts) wires its APPROVED outcome
+// into it; the `/gist-save` command is the artifact-first MANUAL FAILSAFE invocation of the same
+// seam, keeping the legacy drive-the-session behavior as the no-draft fallback (gists have no
+// transcript scrape by design).
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { bindingSuffix } from "../substrate/bindingDelivery.ts";
+import {
+  booleanField,
+  type ColdJson,
+  objectField,
+  runColdDoor,
+  stringField,
+} from "../substrate/coldDoor.ts";
+import { registerPerkCommand } from "../substrate/command.ts";
+import { render } from "../substrate/prompts.ts";
+import { failFor, ok, type Result } from "../substrate/result.ts";
+import type { ToolGating } from "../substrate/toolGating.ts";
+import { branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
+import { report, type Severity } from "../surfaces/report.ts";
+import { decodeGistSaveParams, GIST_SCOPES, type GistScope, readGistDraft } from "./gistDraft.ts";
+
+/** The ok-arm fields — the structured `details` surface doubles as branch-safe persisted state. */
+export interface GistSaveOk {
+  /** `id` is the opaque string gist id (GitHub "7", Linear "ENG-7"/project id) — §8.21. */
+  gist: { id: string; url: string };
+  scope: string | null;
+  existed: boolean | null;
+}
+
+export type GistSaveResult = Result<GistSaveOk>;
+
+/** The decoded `perk gist create --json` payload slice the warm door consumes. */
+interface GistCreatePayload {
+  gist: { id: string; url: string; existed: boolean | undefined };
+  scope: string | undefined;
+}
+
+/** Narrow the `perk gist create --json` success payload; strict on `gist`. */
+function decodeGistCreate(payload: ColdJson): GistCreatePayload | null {
+  const gist = objectField(payload, "gist");
+  if (gist === undefined) return null;
+  const id = stringField(gist, "id");
+  const url = stringField(gist, "url");
+  if (id === undefined || url === undefined) return null;
+  return {
+    gist: { id, url, existed: booleanField(gist, "existed") },
+    scope: stringField(payload, "scope"),
+  };
+}
+
+/** The consumption pointer relayed after a save — the adoption door matching the saved scope. */
+function consumptionHint(id: string, scope: string | undefined): string {
+  return scope === "objective"
+    ? `Consume with: perk objective author --from ${id}`
+    : `Consume with: perk plan from ${id}`;
+}
+
+/**
+ * The single save implementation both surfaces call. Delegates the backend write to the Python
+ * cold door (which owns scope resolution: an explicit `scope` wins, else the launch handoff's
+ * pre-seeded `gist_scope`, else `plan`). Returns a soft result (never throws); failures set
+ * `details.ok = false`. No session linkage on success — nothing consumes a gist in-session.
+ */
+export async function saveGist(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  opts: { prose: string; title?: string; scope?: GistScope },
+): Promise<GistSaveResult> {
+  const fail = failFor(ctx, "gist-save");
+
+  const prose = opts.prose.trim();
+  if (!prose) return fail("no gist prose to save (draft the gist first)", "invalid_input");
+  if (opts.scope !== undefined && !(GIST_SCOPES as readonly string[]).includes(opts.scope)) {
+    return fail("scope must be plan or objective", "invalid_input");
+  }
+
+  const runId = rebuildWorkflowState(branchOf(ctx)).run_id ?? "";
+
+  const args = ["gist", "create", "--json"];
+  if (opts.title) args.push("--title", opts.title);
+  if (opts.scope) args.push("--scope", opts.scope);
+  if (runId) args.push("--run-id", runId);
+  const r = await runColdDoor<GistCreatePayload>(pi, ctx, args, {
+    label: "perk gist create",
+    decode: decodeGistCreate,
+    stdin: { flag: "--body", content: prose, filename: "gist.md" },
+  });
+  if (!r.ok) return fail(r.message, r.errorType);
+
+  const gist = r.data.gist;
+  const verb = gist.existed ? "Found existing" : "Saved";
+  return ok(
+    `${verb} gist ${gist.id} → ${gist.url}\n${consumptionHint(gist.id, r.data.scope)}`,
+    {
+      gist: { id: gist.id, url: gist.url },
+      scope: r.data.scope ?? null,
+      existed: gist.existed ?? null,
+    },
+    { terminate: true },
+  );
+}
+
+/** The approval→save orchestration outcome (the gist `ApprovalSaveOutcome`). */
+export type GistApprovalSaveOutcome =
+  | { status: "no-draft" }
+  | { status: "saved" | "save-failed"; result: GistSaveResult; gateExited: boolean };
+
+/**
+ * The shared approval→save orchestration seam (the gist sibling of objectiveSave.ts's
+ * `objectiveApprovalSave`): an APPROVED gist review (`plan_review`'s gist arm) and the manual
+ * `/gist-save` failsafe both run THIS. Flow: re-read the draft artifact at save time
+ * (`readGistDraft` — never the rendered markdown, never in-hand bytes) → `saveGist` → gate exit
+ * on a successful save while read-only (the D1a pattern: snapshot `gating.isActive()` before the
+ * save; a failed save leaves the gate ON). No draft → `no-draft` (nothing saved, the gate
+ * untouched); callers render their own fallback. Title/scope precedence: explicit opts win; else
+ * the draft's; else the cold door derives/defaults. The returned result keeps `saveGist`'s
+ * `terminate: true` for tool-path callers.
+ */
+export async function gistApprovalSave(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  gating: ToolGating,
+  opts: { title?: string } = {},
+): Promise<GistApprovalSaveOutcome> {
+  const draft = readGistDraft(ctx);
+  if (draft === null) return { status: "no-draft" };
+  // D1a: snapshot the gate BEFORE the save; on success, exit it so save marks the read-only →
+  // read-write boundary in one gesture. A failed save leaves the gate on.
+  const wasReadOnly = gating.isActive();
+  const result = await saveGist(pi, ctx, {
+    prose: draft.prose,
+    title: opts.title ?? draft.title,
+    scope: draft.scope,
+  });
+  let gateExited = false;
+  if (result.details.ok && wasReadOnly) {
+    gating.exit(ctx);
+    gateExited = true;
+  }
+  return { status: result.details.ok ? "saved" : "save-failed", result, gateExited };
+}
+
+const TOOL_GUIDELINES = [
+  "Use gist_save only after the gist says what it means; it creates the tracked gist in the issue backend and ends the turn.",
+  "Pass gist_save the statement-of-intent PROSE in `prose` — problem-space only, no implementation steps or roadmap.",
+  "Pass gist_save's `scope` only once the consumption tier is settled (plan or objective); omit it to keep the pre-seeded/default scope.",
+];
+
+/**
+ * The seed guidance the warm `/gist-save` injects to drive the save (the perk-gist-author skill
+ * pointer rides the skill-binding suffix — not hardcoded here). Pure + exported for offline
+ * tests.
+ */
+export function gistSaveGuidance(title?: string): string {
+  const named = title?.trim() || "";
+  return render("stages/gist-save.md", { title: named });
+}
+
+/** Register the warm door: the `gist_save` tool (canonical) + the `/gist-save` twin. */
+export function registerGistSave(pi: ExtensionAPI, gating: ToolGating): void {
+  pi.registerTool({
+    name: "gist_save",
+    label: "Save gist",
+    description:
+      "Persist a drafted gist (a statement of intent) to the issue backend as a tracked " +
+      "perk:gist. Terminating: ends the turn on save. Call only when the gist says what it " +
+      "means.",
+    promptSnippet: "Save the converged gist to the issue backend (terminates the turn)",
+    promptGuidelines: TOOL_GUIDELINES,
+    executionMode: "sequential",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      required: ["prose"],
+      properties: {
+        prose: {
+          type: "string",
+          description:
+            "The gist prose (the problem-space intent: what we want, why it matters, what " +
+            "bounds it — no implementation steps).",
+        },
+        title: {
+          type: "string",
+          description: "Optional gist title (defaults to the prose's first heading).",
+        },
+        scope: {
+          type: "string",
+          enum: [...GIST_SCOPES],
+          description:
+            "Optional consumption tier: plan (plan-sized intent) or objective (objective-sized).",
+        },
+      },
+    },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const decoded = decodeGistSaveParams(params);
+      if (decoded === null) {
+        return failFor(
+          ctx,
+          "gist-save",
+          "gist_save",
+        )(
+          "gist_save needs { prose: string, scope?: plan|objective } per the tool schema",
+          "bad_input",
+        );
+      }
+      return saveGist(pi, ctx, decoded);
+    },
+  });
+
+  registerPerkCommand(pi, "gist-save", {
+    description:
+      "Save the working gist draft to the issue backend — the manual failsafe for the " +
+      "approval→save flow (artifact-first; drives the save only when no draft exists).",
+    handler: async (args, ctx) => {
+      const title = args.trim() || undefined;
+      // The artifact-first manual-failsafe invocation of the shared approval→save seam (the D1a
+      // gate exit lives in the seam). The legacy drive-the-session behavior is kept as the
+      // NO-DRAFT fallback — gists have no transcript scrape by design, so a draftless session
+      // still needs a working save path.
+      const outcome = await gistApprovalSave(pi, ctx, gating, { title });
+      if (outcome.status === "no-draft") {
+        // Exit the read-only gate so the gist_save tool (excluded from READ_ONLY_TOOLS) becomes
+        // reachable on the driven turn, then drive the turn (mirrors /objective-save).
+        if (gating.isActive()) gating.exit(ctx);
+        report(ctx, "gist-save", "info", "handing the save to the session");
+        // The perk-gist-author pointer rides the skill-binding suffix (D5) since a warm
+        // /gist-save outside a stage:gist-author session gets none from Mechanism A.
+        pi.sendUserMessage(gistSaveGuidance(title) + bindingSuffix(ctx.cwd, "stage:gist-author"));
+        return;
+      }
+      // Saved or save-failed: relay the save message (which carries the consumption hint).
+      const result = outcome.result;
+      const message = result.content[0]?.text ?? "gist-save done";
+      const severity: Severity = result.details.ok ? "info" : "error";
+      report(ctx, "gist-save", severity, message);
+    },
+  });
+}

package/extension/factories/planMode.ts

@@ -46,6 +46,7 @@ import { report } 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 { Key } from "../surfaces/surfaces.ts";
+import { GIST_AUTHOR_STAGE } from "./gistAuthor.ts";
 import { OBJECTIVE_AUTHOR_STAGE } from "./objectiveAuthor.ts";
 
 /** The plan-authoring context customType (distinct from the gate's `perk:mode-context`). */
@@ -156,14 +157,16 @@ export function registerPlanMode(pi: ExtensionAPI, gating: ToolGating): void {
     });
   }
 
-  // Inject the plan-authoring context while the read-only gate is active (display:false). The one
-  // exception: an objective-author session is ALSO read-only, but objectiveAuthor.ts injects its
-  // own authoring context there — so plan mode defers when the launched stage is objective-author
-  // (the coupling break: plan-authoring context is no longer keyed off the bare read-only gate).
+  // Inject the plan-authoring context while the read-only gate is active (display:false). The
+  // exceptions: objective-author and gist-author sessions are ALSO read-only, but
+  // objectiveAuthor.ts / gistAuthor.ts inject their own authoring contexts there — so plan mode
+  // defers when the launched stage is either (the coupling break: plan-authoring context is no
+  // longer keyed off the bare read-only gate).
   pi.on("before_agent_start", async (_event, ctx) => {
     if (!gating.isActive()) return;
     const branch = branchOf(ctx);
-    if (rebuildWorkflowState(branch).stage === OBJECTIVE_AUTHOR_STAGE) return;
+    const launchedStage = rebuildWorkflowState(branch).stage;
+    if (launchedStage === OBJECTIVE_AUTHOR_STAGE || launchedStage === GIST_AUTHOR_STAGE) return;
     // Once-only: injected customs persist to the branch, so a live copy suppresses re-injection;
     // compaction dropping it makes the scan come up clean and the next turn re-injects.
     if (branchCarries(branch, PLAN_MARKER)) return;

package/extension/factories/planReview.ts

@@ -19,7 +19,12 @@
 // `plan_draft` redirect). An APPROVED outcome (either backend) wires into the shared
 // `approvalSave` seam (planSave.ts): auto-save → D1a gate exit → terminating result,
 // node link recovered from the `objective_node_claim` carrier inside `savePlan`. A DENY returns
-// feedback and directs a `plan_draft` rewrite + re-review. Strict on deny, FAIL-OPEN everywhere
+// feedback and directs a `plan_draft` rewrite + re-review. Plannotator's browser "Direct Edits"
+// (a `# Direct Edits` unified diff opening the feedback) are handled asymmetrically per arm: the
+// PLAN arm mechanically applies an approved diff (strict apply → draft write-back → save the
+// edited bytes; any failure falls open to the verbatim save + a loud warning); the OBJECTIVE arm
+// cannot fold rendered-markdown edits into the structured draft, so an approve-with-edits SKIPS
+// the save and returns one model-mediated revise round; DENY stays model-mediated on both arms. Strict on deny, FAIL-OPEN everywhere
 // else: headless / dismissed (Esc anywhere = skip, mirroring ask_user_question's dismissal — deny
 // is always explicit) / backend-unavailable all soft-skip so plan authoring never wedges — those
 // arms keep the present-the-plan + human-`/plan-save` discipline (the manual failsafe).
@@ -40,6 +45,12 @@
 // exit → a TERMINATING result; a failed save is non-terminating, leaves the gate read-only, and
 // directs the human `/objective-save` failsafe.
 //
+// THE GIST ARM: a gist-author session (read-only, stage `gist-author`) routes through
+// `executeGistReview` the same way — the reviewed bytes are the RENDERED gist draft
+// (`readGistDraft` + `renderGistDraft`, gistDraft.ts), first-party VIEW-ONLY, implement-here
+// never offered, APPROVED → the `gistApprovalSave` seam (gistSave.ts), no draft soft-skips with
+// `reason: "no_gist_draft"`.
+//
 // INVARIANTS HELD: never calls `setActiveTools`, never registers a `tool_call` handler, never
 // restamps `cache.plan-ref.provider`. The door composes the gate AND the save EXCLUSIVELY
 // through the `approvalSave` seam (Invariant 1: composes, never owns).
@@ -48,12 +59,18 @@ import { randomUUID } from "node:crypto";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
   createPlannotatorBridge,
+  extractDirectEdits,
+  hasDirectEditsHeading,
   isPlannotatorPlanSelected,
 } from "../adapters/planAdapterPlannotator.ts";
 import type { Result } from "../substrate/result.ts";
 import type { ToolGating } from "../substrate/toolGating.ts";
 import { paramsOf, stringParam } from "../substrate/toolParams.ts";
+import { applyUnifiedDiff } from "../substrate/unifiedDiff.ts";
 import { branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
+import { GIST_AUTHOR_STAGE } from "./gistAuthor.ts";
+import { readGistDraft, renderGistDraft } from "./gistDraft.ts";
+import { type GistApprovalSaveOutcome, gistApprovalSave } from "./gistSave.ts";
 import { implementHereExit, implementHereGuidance } from "./implementHere.ts";
 import { OBJECTIVE_AUTHOR_STAGE } from "./objectiveAuthor.ts";
 import { readObjectiveDraft, renderObjectiveDraft } from "./objectiveDraft.ts";
@@ -131,6 +148,17 @@ const OBJECTIVE_SUBJECT: ReviewSubject = {
   noSourceError: "no objective draft resolved",
 };
 
+const GIST_SUBJECT: ReviewSubject = {
+  noun: "gist",
+  present: "the complete gist to the user",
+  presentUnavailable: "the complete gist to the user",
+  implementHereWhere: "on the gist path",
+  draftTool: "gist_draft",
+  failsafeCmd: "/gist-save",
+  detailsExtra: { subject: "gist" },
+  noSourceError: "no gist draft resolved",
+};
+
 const SKIP_TEXT =
   "no interactive review surface available — present the complete plan to the user in your next message.";
 
@@ -244,16 +272,19 @@ type SubjectSaveOutcome =
  * (propagating the seam's `terminate: true` intent); a failed save is non-terminating, leaves
  * the gate read-only, and directs the human manual failsafe. Reviewer feedback is surfaced
  * loudly as implementation guidance — the approved bytes were saved verbatim, never post-edited.
- * The `paramMismatch`/`edited` opts are plan-arm-only (their literals name "plan"/"draft"): the
- * objective delegator never passes opts, so the suffixes render empty and `edited` never reaches
- * its details. The `no-source` arm is defensively unreachable (the reviewed source is always
+ * The `paramMismatch`/`edited`/`directEditsFailed` opts are plan-arm-only (their literals name
+ * "plan"/"draft"): the objective delegator never passes opts, so the suffixes render empty and
+ * `edited` never reaches its details. `directEditsFailed` (plannotator-only) flags that a Direct
+ * Edits section was seen but could not be honored — the saved arm gains a loud warning that the
+ * plan was saved WITHOUT the reviewer's edits, and details carry `direct_edits_applied: false`.
+ * The `no-source` arm is defensively unreachable (the reviewed source is always
  * non-blank) but maps to the save-failed shape rather than throwing.
  */
 function approvedSubjectSaveResult(
   subject: ReviewSubject,
   outcome: Extract<ReviewOutcome, { status: "completed" }>,
   save: SubjectSaveOutcome,
-  opts?: { paramMismatch?: boolean; edited?: boolean },
+  opts?: { paramMismatch?: boolean; edited?: boolean; directEditsFailed?: boolean },
 ): ToolResult {
   const feedback = outcome.feedback
     ? `\n\nReviewer feedback (implementation guidance — the approved ${subject.noun} was saved ` +
@@ -266,6 +297,7 @@ function approvedSubjectSaveResult(
     feedback: outcome.feedback ?? null,
     ...subject.detailsExtra,
     ...(opts?.edited === true ? { edited: true } : {}),
+    ...(opts?.directEditsFailed === true ? { direct_edits_applied: false } : {}),
   };
   if (save.status === "saved") {
     const saveText = save.result.content[0]?.text ?? "";
@@ -275,11 +307,17 @@ function approvedSubjectSaveResult(
       opts?.paramMismatch === true
         ? "\n\n⚠ differing plan param ignored — the validated draft was reviewed and saved."
         : "";
+    const editsWarning =
+      opts?.directEditsFailed === true
+        ? "\n\n⚠ WARNING: the reviewer's Direct Edits could NOT be auto-applied — the plan was " +
+          "saved WITHOUT them. The diff remains in the reviewer feedback above; apply it to the " +
+          "plan issue manually or via a follow-up."
+        : "";
     return {
       content: [
         {
           type: "text",
-          text: `${subject.noun} APPROVED by reviewer.${feedback}\n\n${saveText}${edited}${mismatch}`,
+          text: `${subject.noun} APPROVED by reviewer.${feedback}\n\n${saveText}${edited}${mismatch}${editsWarning}`,
         },
       ],
       // `ok` sits per-branch, NOT in `base` — `base` is spread into the fail branch too.
@@ -323,13 +361,15 @@ function approvedSubjectSaveResult(
 /**
  * Map an APPROVED review outcome + the `approvalSave` outcome into the model-facing tool result
  * (exported for the offline tests) — the plan flavor of `approvedSubjectSaveResult`. `edited`
- * (first-party only) flags that human edits were written back to the draft pre-verdict, so the
- * saved bytes carry them.
+ * flags that human edits were written back to the draft pre-verdict (the first-party editor, or
+ * the plannotator Direct Edits auto-apply), so the saved bytes carry them. `directEditsFailed`
+ * (plannotator-only, optional — absent keeps every existing call site byte-stable) flags a
+ * Direct Edits section that could not be honored: the plan saved verbatim, a loud warning added.
  */
 export function approvedSaveResult(
   outcome: Extract<ReviewOutcome, { status: "completed" }>,
   save: ApprovalSaveOutcome,
-  opts: { paramMismatch: boolean; edited?: boolean },
+  opts: { paramMismatch: boolean; edited?: boolean; directEditsFailed?: boolean },
 ): ToolResult {
   return approvedSubjectSaveResult(
     PLAN_SUBJECT,
@@ -535,7 +575,12 @@ export function approvedObjectiveSaveResult(
  * the transcript). First-party reviews run VIEW-ONLY (edits are never written back;
  * deny+feedback is the change channel). An APPROVED outcome wires into the
  * `objectiveApprovalSave` seam (re-read the STRUCTURED artifact → `saveObjective` → D1a gate
- * exit → terminating); every other outcome maps via `objectiveReviewOutcomeResult`.
+ * exit → terminating); every other outcome maps via `objectiveReviewOutcomeResult`. ONE
+ * carve-out (plannotator only): an approval whose feedback opens a Direct Edits section SKIPS
+ * the save — rendered-markdown edits cannot be folded back into the structured draft
+ * mechanically — and returns a NON-terminating revise round with the gate untouched (fold the
+ * diff in via `objective_draft`, re-review to confirm); perk never saves an objective the
+ * reviewer explicitly edited away from.
  */
 export async function executeObjectiveReview(
   pi: ExtensionAPI,
@@ -576,6 +621,42 @@ export async function executeObjectiveReview(
   let outcome: ReviewOutcome;
   if (isPlannotatorPlanSelected(ctx.cwd)) {
     outcome = await bridge.review(rendered, sig);
+    // APPROVE + Direct Edits (browser edits of the RENDERED markdown), checked BEFORE the
+    // approved-save routing (the approved-first discipline): the save seam re-reads the
+    // STRUCTURED artifact, so rendered-markdown edits — roadmap-table rows included — cannot be
+    // folded back without model judgment. Skip the save, keep the gate read-only, and route ONE
+    // revise round: the model folds the diff into `objective_draft`, then re-reviews to confirm.
+    // The heading check suffices (extraction success is irrelevant here — the diff goes to the
+    // model verbatim either way).
+    if (
+      outcome.status === "completed" &&
+      outcome.approved &&
+      outcome.feedback !== undefined &&
+      hasDirectEditsHeading(outcome.feedback)
+    ) {
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              "objective APPROVED with direct browser edits — these cannot be auto-applied to " +
+              "the structured draft, so nothing was saved. Fold the Direct Edits diff below into " +
+              "the working draft with objective_draft (prose hunks → the prose; roadmap-table " +
+              "hunks → the matching node fields), then call plan_review again to confirm.\n\n" +
+              `Reviewer feedback:\n${outcome.feedback}`,
+          },
+        ],
+        details: {
+          ok: true,
+          status: "revise",
+          reason: "direct_edits",
+          approved: true,
+          feedback: outcome.feedback,
+          reviewId: outcome.reviewId,
+          subject: "objective",
+        },
+      };
+    }
   } else {
     const fp = await runFirstPartyReview({
       ui: ctx.ui,
@@ -599,6 +680,111 @@ export async function executeObjectiveReview(
   return objectiveReviewOutcomeResult(outcome);
 }
 
+// ------------------------------------------------------------------------ the gist review arm
+
+const GIST_REVIEW_EDITOR_TITLE =
+  "Gist review (view only — edits are not saved) — Enter: continue to verdict · Esc: skip · " +
+  "Ctrl+G: $EDITOR";
+
+/**
+ * Map a non-approved gist review outcome into the model-facing tool result (exported for the
+ * offline tests) — the gist-flavored sibling of `objectiveReviewOutcomeResult`, delegating to
+ * `subjectReviewOutcomeResult` with `GIST_SUBJECT`. Every arm carries `details.subject: "gist"`;
+ * the texts redirect to `gist_draft` / `/gist-save`. The execute path routes approved outcomes
+ * to `approvedGistSaveResult` first, so `completed` renders DENIED here.
+ */
+export function gistReviewOutcomeResult(outcome: ReviewOutcome): ToolResult {
+  return subjectReviewOutcomeResult(GIST_SUBJECT, outcome);
+}
+
+/**
+ * Map an APPROVED gist review outcome + the `gistApprovalSave` outcome into the model-facing
+ * tool result (exported for the offline tests) — the gist sibling of
+ * `approvedObjectiveSaveResult`, delegating to `approvedSubjectSaveResult` with `GIST_SUBJECT`
+ * and no opts (the gist path reviews only the rendered draft, view-only — no
+ * `paramMismatch`/`edited`).
+ */
+export function approvedGistSaveResult(
+  outcome: Extract<ReviewOutcome, { status: "completed" }>,
+  save: GistApprovalSaveOutcome,
+): ToolResult {
+  return approvedSubjectSaveResult(
+    GIST_SUBJECT,
+    outcome,
+    save.status === "no-draft" ? { status: "no-source" } : save,
+  );
+}
+
+/**
+ * The gist review arm, mirroring `executeObjectiveReview`'s shape with the rendered gist draft
+ * as the SOLE review source (never the `plan` param, never the transcript). First-party reviews
+ * run VIEW-ONLY (edits are never written back; deny+feedback is the change channel); the
+ * implement-here verdict is never offered (a gist is not implementable — it has no strategy).
+ * An APPROVED outcome wires into the `gistApprovalSave` seam (re-read the artifact → `saveGist`
+ * → D1a gate exit → terminating); every other outcome maps via `gistReviewOutcomeResult`.
+ */
+export async function executeGistReview(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  gating: ToolGating,
+  bridge: { review(plan: string, signal?: AbortSignal): Promise<ReviewOutcome> },
+  signal?: AbortSignal,
+): Promise<ToolResult> {
+  // 1. Headless → soft skip (fail-open; never wedges CI/supervisor runs on an interactive UI).
+  if (!ctx.hasUI) return skipResult();
+  // 2. The draft artifact is the sole review source — no draft → soft skip with the gist_draft
+  //    redirect.
+  const draft = readGistDraft(ctx);
+  if (draft === null) {
+    return {
+      content: [
+        {
+          type: "text",
+          text:
+            "no gist draft to review — write the working gist with gist_draft (the " +
+            "statement-of-intent prose), then call plan_review again.",
+        },
+      ],
+      details: {
+        ok: false,
+        error: "no gist draft to review — write it with gist_draft first",
+        error_type: "no_gist_draft",
+        status: "skipped",
+        reason: "no_gist_draft",
+      },
+    };
+  }
+  // 3. The reviewed bytes are the RENDERED markdown (title + scope + prose) — never raw JSON.
+  const rendered = renderGistDraft(draft);
+  // 4. Backend dispatch (mirrors the objective path): plannotator-selected → the bridge; ANY
+  //    other selection → the first-party editor, view-only.
+  const sig = signal ?? ctx.signal;
+  let outcome: ReviewOutcome;
+  if (isPlannotatorPlanSelected(ctx.cwd)) {
+    outcome = await bridge.review(rendered, sig);
+  } else {
+    const fp = await runFirstPartyReview({
+      ui: ctx.ui,
+      plan: rendered,
+      writeDraft: () => true, // unreachable under viewOnly — the branch is skipped
+      signal: sig,
+      editorTitle: GIST_REVIEW_EDITOR_TITLE,
+      verdicts: verdictsFor(GIST_SUBJECT),
+      viewOnly: true,
+    });
+    outcome = fp.outcome;
+  }
+  // 5. An APPROVED decision (either backend) wires into the gistApprovalSave seam (the artifact
+  //    is re-read at save time — never the rendered bytes; auto-save → D1a gate exit →
+  //    terminating result); everything else maps via gistReviewOutcomeResult. Approved-first
+  //    routing: gistReviewOutcomeResult's completed case renders DENIED.
+  if (outcome.status === "completed" && outcome.approved) {
+    const save = await gistApprovalSave(pi, ctx, gating);
+    return approvedGistSaveResult(outcome, save);
+  }
+  return gistReviewOutcomeResult(outcome);
+}
+
 // ------------------------------------------------------------------------- the execute core
 
 /**
@@ -641,9 +827,14 @@ export async function executePlanReview(
   }
   // 1. Objective-author session → the objective review arm: the rendered
   //    objective draft is the sole review source; a well-typed `plan` param is ignored here.
-  if (rebuildWorkflowState(branchOf(ctx)).stage === OBJECTIVE_AUTHOR_STAGE) {
+  //    A gist-author session likewise routes to the gist arm (the rendered gist draft).
+  const launchedStage = rebuildWorkflowState(branchOf(ctx)).stage;
+  if (launchedStage === OBJECTIVE_AUTHOR_STAGE) {
     return executeObjectiveReview(pi, ctx, gating, bridge, signal ?? ctx.signal);
   }
+  if (launchedStage === GIST_AUTHOR_STAGE) {
+    return executeGistReview(pi, ctx, gating, bridge, signal ?? ctx.signal);
+  }
   // 2. Headless → soft skip (fail-open; never wedges CI/supervisor runs on an interactive UI).
   if (!ctx.hasUI) return skipResult();
   // 3. File-first resolution: artifact → param, NEVER transcript — an approval
@@ -674,8 +865,34 @@ export async function executePlanReview(
   let outcome: ReviewOutcome;
   let reviewedPlan = src.plan;
   let edited = false;
+  let directEditsFailed = false;
   if (isPlannotatorPlanSelected(ctx.cwd)) {
     outcome = await bridge.review(src.plan, sig);
+    // APPROVE + Direct Edits (browser plan edits, contracts.md §8.23): mechanically apply the
+    // reviewer's diff to the exact bytes reviewed, write it back to the draft (reviewed bytes ==
+    // artifact bytes == saved bytes — the first-party pre-verdict write-back, replayed here
+    // post-verdict because the bridge only reports the diff), and save the EDITED bytes. Every
+    // rung fails open to the verbatim path: no section → untouched; a heading that cannot be
+    // parsed / applied / written back → verbatim save + a loud warning (never save bytes the
+    // artifact doesn't carry). DENY stays model-mediated — the feedback (diff included) passes
+    // through for the plan_draft rewrite.
+    if (outcome.status === "completed" && outcome.approved && outcome.feedback !== undefined) {
+      const section = extractDirectEdits(outcome.feedback);
+      if (section !== null) {
+        const patched = applyUnifiedDiff(src.plan, section.diff);
+        if (patched !== null && writePlanDraft(pi, ctx, patched).details.ok) {
+          reviewedPlan = patched;
+          edited = true;
+          // The applied diff must NOT survive into the result as "apply these exact changes"
+          // guidance — only the annotation remainder (when any) stays reviewer feedback.
+          outcome = { ...outcome, feedback: section.remainder };
+        } else {
+          directEditsFailed = true;
+        }
+      } else if (hasDirectEditsHeading(outcome.feedback)) {
+        directEditsFailed = true;
+      }
+    }
   } else {
     // The 4th verdict (implement-here, the no-save exit) is offered UNLESS this is an
     // objective-node planning session — a node-linked plan must save (the node advance and
@@ -705,7 +922,11 @@ export async function executePlanReview(
   //    gate exit → terminating result); everything else maps via reviewOutcomeResult.
   if (outcome.status === "completed" && outcome.approved) {
     const save = await approvalSave(pi, ctx, gating, { reviewedPlan });
-    return approvedSaveResult(outcome, save, { paramMismatch: src.paramMismatch, edited });
+    return approvedSaveResult(outcome, save, {
+      paramMismatch: src.paramMismatch,
+      edited,
+      directEditsFailed,
+    });
   }
   return reviewOutcomeResult(outcome);
 }