@mgiles/perk 2.1.0 → 2.2.0

package/extension/adapters/planAdapterPlannotator.ts

@@ -26,12 +26,23 @@
 // persisted `perk:workflow-state.mode`, the gate's own state twin.
 //
 // EVENT ENVELOPE (pinned against `@plannotator/pi-extension@0.20.0`, `plannotator-events.ts` —
-// verified unchanged through 0.22.0):
+// verified unchanged through 0.26.1):
 //   request  — pi.events.emit("plannotator:request", { requestId, action: "plan-review",
 //              payload: { planContent, origin? }, respond })   // respond = in-payload callback
 //   handshake — respond({ status: "handled", result: { status: "pending", reviewId } })
 //             | respond({ status: "unavailable", error? }) | respond({ status: "error", error })
 //   decision — pi.events.on("plannotator:review-result", { reviewId, approved, feedback?, ... })
+//
+// DIRECT EDITS FEEDBACK FORMAT (pinned against plannotator `packages/editor/directEdits.ts`,
+// `buildDirectEditsSection` / `composeFeedbackWithDirectEdits`, at v0.26.1). The browser's
+// direct-edit mode arrives as PROSE inside the existing `feedback` string, never a new envelope
+// field: `# Direct Edits\n` + blank line + a one-sentence preamble (two wording variants — never
+// couple to it) + blank line + a ```diff fence containing
+// `createTwoFilesPatch('plan.md (original)', 'plan.md (edited)', base, edited, undefined,
+// undefined, { context: 3 }).trimEnd()` against the exact bytes perk submitted. The section is
+// composed FIRST; non-sentinel annotation feedback follows after `\n\n---\n\n`; edits-only
+// feedback is just the section. `extractDirectEdits` below parses it strictly (fail-open — a
+// null degrades to today's verbatim behavior).
 
 import { randomUUID } from "node:crypto";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
@@ -186,6 +197,58 @@ export function createPlannotatorBridge(bus: PlannotatorBus): {
   return { review };
 }
 
+// ------------------------------------------------------------------ Direct Edits extraction
+
+const DIRECT_EDITS_HEADING = "# Direct Edits";
+const DIFF_FENCE_OPEN = "```diff\n";
+const REMAINDER_SEPARATOR = "\n\n---\n\n";
+
+/**
+ * Whether `feedback` OPENS with the Direct Edits heading (plan-review feedback composes the
+ * section first — a heading anywhere else is quoted prose, not a section). Callers pair this
+ * with `extractDirectEdits`: heading present but extraction null means the section was seen but
+ * could not be honored (the fail-open ladder's loud-warning arm).
+ */
+export function hasDirectEditsHeading(feedback: string): boolean {
+  return feedback === DIRECT_EDITS_HEADING || feedback.startsWith(`${DIRECT_EDITS_HEADING}\n`);
+}
+
+/**
+ * Strictly extract the Direct Edits unified diff from a plannotator review-result `feedback`
+ * string (the format pin lives in the module header). Returns the fence body as `diff` plus the
+ * annotation `remainder` after the section (one leading `\n\n---\n\n` separator stripped;
+ * `undefined` when blank). Null means "no extractable Direct Edits section" — both the
+ * no-section case AND a present-heading-but-unparseable body (callers distinguish the two via
+ * `hasDirectEditsHeading`). The preamble prose between the heading and the fence is skipped
+ * without inspecting its wording (plannotator ships two variants).
+ */
+export function extractDirectEdits(feedback: string): { diff: string; remainder?: string } | null {
+  if (!hasDirectEditsHeading(feedback)) return null;
+  const openIdx = feedback.indexOf(`\n${DIFF_FENCE_OPEN}`, DIRECT_EDITS_HEADING.length);
+  if (openIdx === -1) return null;
+  const bodyStart = openIdx + 1 + DIFF_FENCE_OPEN.length;
+  // The closing fence is the first line that is exactly ``` — unambiguous inside the body,
+  // because every diff body line carries a prefix char (` `/`-`/`+`/`\`/`@`), so no body line
+  // can start with a backtick.
+  let close = -1;
+  let searchFrom = bodyStart;
+  while (close === -1) {
+    const idx = feedback.indexOf("\n```", searchFrom);
+    if (idx === -1) return null;
+    const after = feedback[idx + 4];
+    if (after === undefined || after === "\n") {
+      close = idx;
+    } else {
+      searchFrom = idx + 4;
+    }
+  }
+  const diff = feedback.slice(bodyStart, close);
+  if (diff.trim() === "") return null;
+  let rest = feedback.slice(close + 4);
+  if (rest.startsWith(REMAINDER_SEPARATOR)) rest = rest.slice(REMAINDER_SEPARATOR.length);
+  return { diff, remainder: rest.trim() === "" ? undefined : rest };
+}
+
 // ----------------------------------------------------------------------------- registration
 
 /**

package/extension/doors/commitCompact.ts

@@ -0,0 +1,163 @@
+// The warm `/commit-and-compact` door: commit the work so far, then compact the session.
+//
+// Human-only slash command (no model-facing tool twin, no cold door, no workflow-state field —
+// warm-plane only). The commit half needs the model (real staging judgment + a real commit
+// message), so the dirty arm DRIVES the session (`pi.sendUserMessage`, warm-door discipline);
+// the compaction half is deterministic extension work keyed on `agent_settled` (the one-shot
+// "the driven run fully settled" hook — `turn_end` would compact mid-run). Fail-safe posture:
+// never compact when uncommitted work might exist — the undeterminable-git-state and no-commit
+// arms skip compaction with a loud warning naming pi's builtin `/compact` escape hatch. Clean
+// and read-only trees compact immediately (the commit half is vacuous there).
+//
+// The pending record is in-memory by design (lost on `/reload` — the user re-runs the command);
+// re-invoking while a drive is in flight simply overwrites it.
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { bindingSuffix } from "../substrate/bindingDelivery.ts";
+import { registerPerkCommand } from "../substrate/command.ts";
+import { commitsSince, headSha, worktreeDirty } from "../substrate/git.ts";
+import { render } from "../substrate/prompts.ts";
+import type { ToolGating } from "../substrate/toolGating.ts";
+import { report, type Severity } from "../surfaces/report.ts";
+
+/** The driven-commit guidance (pure + exported for offline tests and the drive-coverage guard). */
+export function commitAndCompactGuidance(): string {
+  return render("commit-and-compact.md", {});
+}
+
+/**
+ * Compaction instructions for the arms with nothing to commit (read-only / clean tree). Inline,
+ * not a `prompts/` template — compaction `customInstructions` stay inline (the objective
+ * threshold-compaction precedent); only injected user-message prose goes to `prompts/`.
+ */
+export const DIRECT_COMPACT_INSTRUCTIONS =
+  "Preserve the current task's intent, progress so far, and the concrete next steps.";
+
+/**
+ * Compaction instructions for the committed arm: embed the `git log --oneline` listing of the
+ * new commit(s) so the summary references them. Pure + exported for offline tests.
+ */
+export function compactInstructions(commits: string | null): string {
+  return [
+    "The work completed so far was just committed:",
+    "",
+    commits ?? "(commit list unavailable)",
+    "",
+    "Preserve in the summary: the task being implemented and its current progress, what the new " +
+      "commit(s) contain, and the concrete next steps for the remaining work. The committed diff " +
+      "is recoverable via git, so prefer intent and next steps over restating the diff.",
+  ].join("\n");
+}
+
+/** The one-shot record the dirty/drive arm leaves for the `agent_settled` handler. */
+export interface PendingCompact {
+  cwd: string;
+  /** HEAD at invocation (null on an unborn HEAD) — the advance gate compares against this. */
+  headBefore: string | null;
+}
+
+/** The door's side-effect surface — `ExtensionContext`-backed in wiring, recorder fakes in tests. */
+export interface CommitCompactIo {
+  report(severity: Severity, message: string): void;
+  /** Inject the driving user message (wiring appends the skill-binding suffix). */
+  send(guidance: string): void;
+  compact(customInstructions: string): void;
+}
+
+/**
+ * The invocation arms (gate → undeterminable → clean → dirty, in that order). Returns the
+ * pending record only on the dirty/drive arm — every other arm resolves immediately.
+ */
+export function startCommitAndCompact(
+  cwd: string,
+  gateActive: boolean,
+  io: CommitCompactIo,
+): PendingCompact | null {
+  if (gateActive) {
+    io.report("info", "read-only session — nothing to commit; compacting…");
+    io.compact(DIRECT_COMPACT_INSTRUCTIONS);
+    return null;
+  }
+  const dirty = worktreeDirty(cwd);
+  if (dirty === null) {
+    // Fail-safe: never compact when uncommitted work might exist.
+    io.report(
+      "warning",
+      "cannot determine the git worktree state — compaction skipped; run /compact to compact anyway.",
+    );
+    return null;
+  }
+  if (!dirty) {
+    io.report("info", "worktree clean — nothing to commit; compacting…");
+    io.compact(DIRECT_COMPACT_INSTRUCTIONS);
+    return null;
+  }
+  io.report("info", "driving a commit of the work completed so far…");
+  const headBefore = headSha(cwd);
+  io.send(commitAndCompactGuidance());
+  return { cwd, headBefore };
+}
+
+/**
+ * The settle arms: compact only when HEAD actually advanced past the invocation-time sha;
+ * otherwise (model declined / commit failed / HEAD unreadable) warn and skip — same fail-safe.
+ */
+export function settleCommitAndCompact(pending: PendingCompact, io: CommitCompactIo): void {
+  const headNow = headSha(pending.cwd);
+  if (headNow === null || headNow === pending.headBefore) {
+    io.report(
+      "warning",
+      "no commit was made — compaction skipped; run /compact to compact anyway.",
+    );
+    return;
+  }
+  io.report("info", "committed — compacting the session…");
+  io.compact(compactInstructions(commitsSince(pending.cwd, pending.headBefore)));
+}
+
+/** Register the `/commit-and-compact` command + its one-shot `agent_settled` consumer. */
+export function registerCommitAndCompact(pi: ExtensionAPI, gating: ToolGating): void {
+  let pending: PendingCompact | null = null;
+
+  const ioFor = (ctx: ExtensionContext): CommitCompactIo => ({
+    report: (severity, message) => {
+      report(ctx, "commit-and-compact", severity, message);
+    },
+    send: (guidance) => {
+      // The trigger lets repos bind a skill via `[[bindings]]`; drive unconditionally — report()
+      // already carries the headless stderr fallback.
+      pi.sendUserMessage(guidance + bindingSuffix(ctx.cwd, "command:commit-and-compact"));
+    },
+    compact: (customInstructions) => {
+      // No onComplete: pi's own UI signals compaction, and callbacks must not touch a possibly-
+      // stale ctx after session replacement (the documented compaction race).
+      ctx.compact({
+        customInstructions,
+        onError: (error) => {
+          console.error(`perk: commit-and-compact — compaction failed — ${error}`);
+        },
+      });
+    },
+  });
+
+  pi.on("agent_settled", async (_event, ctx) => {
+    if (pending === null) return;
+    const record = pending;
+    pending = null; // consume-then-clear: the record is strictly one-shot
+    try {
+      settleCommitAndCompact(record, ioFor(ctx));
+    } catch (error) {
+      console.error(`perk: commit-and-compact — settle handling failed — ${error}`);
+    }
+  });
+
+  registerPerkCommand(pi, "commit-and-compact", {
+    description:
+      "Commit the work completed so far (a driven model turn stages and writes the message), " +
+      "then compact the session. Clean or read-only sessions compact immediately; if no commit " +
+      "results, compaction is skipped.",
+    handler: async (_args, ctx) => {
+      pending = startCommitAndCompact(ctx.cwd, gating.isActive(), ioFor(ctx));
+    },
+  });
+}

package/extension/factories/gistAuthor.ts

@@ -0,0 +1,94 @@
+// Gist-authoring context injection (the gist mirror of objectiveAuthor.ts). A `perk gist
+// author` cold launch opens a READ-ONLY session whose handoff `stage` is `gist-author`; this
+// module injects the gist-authoring contract under its own `perk:gist-author-context` customType
+// (once-only: branch-scan dedup'd on the marker), keyed off (read-only gate AND stage ===
+// gist-author), optionally extended by the same `[workflow] plan_authoring` addendum the
+// plan-authoring injection consumes (verbatim reuse, read per-event via loadPerkConfig).
+// planMode.ts defers when the stage is gist-author, so exactly one authoring context is injected.
+//
+// The `gist_save` warm door (the tool + `/gist-save` command) lives in gistSave.ts, the mirror
+// of objectiveSave.ts.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { loadPerkConfig } from "../substrate/config.ts";
+import { render } from "../substrate/prompts.ts";
+import type { ToolGating } from "../substrate/toolGating.ts";
+import {
+  type BranchEntry,
+  branchCarries,
+  branchOf,
+  rebuildWorkflowState,
+} from "../substrate/workflowState.ts";
+
+/** The registry stage id of the gist-authoring session (shared with planMode's defer check). */
+export const GIST_AUTHOR_STAGE = "gist-author";
+
+/** The gist-authoring context customType (distinct from planMode's `perk:plan-context`). */
+export const GIST_AUTHOR_CONTEXT_TYPE = "perk:gist-author-context";
+const GIST_AUTHOR_MARKER = "[GIST AUTHORING]";
+
+/**
+ * The cooperative gather-then-author contract for gists. Prompting, NOT enforcement (the tool
+ * gate is the enforcement). Mirrors skills/perk-gist-author/SKILL.md: clarify the intent,
+ * explore lightly, keep the draft current with `gist_draft`, review via `plan_review`, approval
+ * auto-saves — no implementation strategy in the artifact.
+ */
+export const GIST_AUTHORING_CONTEXT = render("contexts/gist-authoring.md", {
+  marker: GIST_AUTHOR_MARKER,
+});
+
+/** Build the full gist-authoring injection, appending the project config addendum when present. */
+export function gistAuthoringContextContent(cwd: string): string {
+  const addendum = loadPerkConfig(cwd).planAuthoring;
+  return addendum ? `${GIST_AUTHORING_CONTEXT}\n\n${addendum.trim()}` : GIST_AUTHORING_CONTEXT;
+}
+
+/** Whether the current branch is a gist-author session (read-only gate AND stage match). */
+function isGistAuthoring(gating: ToolGating, branch: readonly BranchEntry[]): boolean {
+  return gating.isActive() && rebuildWorkflowState(branch).stage === GIST_AUTHOR_STAGE;
+}
+
+/**
+ * Register the gist-authoring context injection (display:false), the gist mirror of
+ * objectiveAuthor's injection. Inert outside a gist-author session; never throws.
+ */
+export function registerGistAuthor(pi: ExtensionAPI, gating: ToolGating): void {
+  pi.on("before_agent_start", async (_event, ctx) => {
+    const branch = branchOf(ctx);
+    if (!isGistAuthoring(gating, branch)) 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, GIST_AUTHOR_MARKER)) return;
+    return {
+      message: {
+        customType: GIST_AUTHOR_CONTEXT_TYPE,
+        content: gistAuthoringContextContent(ctx.cwd),
+        display: false,
+      },
+    };
+  });
+
+  // Strip the stale gist-authoring marker from context once the session is no longer authoring
+  // (gate off, or the stage moved on) so it never lingers — the same hygiene planMode applies.
+  pi.on("context", async (event, ctx) => {
+    const branch = branchOf(ctx);
+    if (isGistAuthoring(gating, branch)) return;
+    return {
+      messages: event.messages.filter((m) => {
+        const msg = m as { customType?: string; role?: string; content?: unknown };
+        if (msg.customType === GIST_AUTHOR_CONTEXT_TYPE) return false;
+        if (msg.role !== "user") return true;
+        const content = msg.content;
+        if (typeof content === "string") return !content.includes(GIST_AUTHOR_MARKER);
+        if (Array.isArray(content)) {
+          return !content.some(
+            (c) =>
+              (c as { type?: string; text?: string }).type === "text" &&
+              ((c as { text?: string }).text ?? "").includes(GIST_AUTHOR_MARKER),
+          );
+        }
+        return true;
+      }),
+    };
+  });
+}

package/extension/factories/gistDraft.ts

@@ -0,0 +1,265 @@
+// The `gist_draft` file tool: the third member of the draft carve-out family
+// (planDraft.ts, objectiveDraft.ts) — the gist twin, minus the roadmap.
+//
+// Carve-out doctrine: the tool takes NO path/name parameter — the artifact name is the fixed
+// constant `GIST_DRAFT_ARTIFACT` and the path is derived exclusively through the session-data
+// accessor seam (`writeSessionArtifact`, sessionData.ts), so the only bytes it can ever write are
+// the one working-gist artifact in the current run's data dir (gitignored scratch). Allowlisting
+// its name in `READ_ONLY_TOOLS` (toolGating.ts) is therefore safe: the read-only invariant (the
+// worktree stays untouched) holds, and the gate's `tool_call` edit/write/bash blocking logic is
+// UNCHANGED. Full rewrite per call, non-terminating; NOT a save — `gist_save`/`/gist-save` still
+// persist the gist to the issue backend.
+//
+// Format doctrine: JSON is the storage/transport format, NEVER the human review surface. The
+// artifact carries `{schema_version, title?, scope?, prose}` — deliberately light: a gist is a
+// problem-space statement of intent with no structured roadmap (contracts.md §8.41). The review
+// surface reads the draft via `readGistDraft` (over `readSessionArtifact` — digest-validated,
+// fail-open) and renders markdown via `renderGistDraft` (title + a `Scope:` line + the prose) —
+// never raw JSON.
+//
+// Vocabulary ownership: this module owns the shared draft/save param vocabulary
+// (`GistSaveParams`, `decodeGistSaveParams`, `GIST_SCOPES`) — gistDraft is the LEAF (mirroring
+// planDraft←planSave's direction); gistSave.ts consumes it, so it may value-import
+// `readGistDraft` cycle-free for the approval→save orchestration.
+//
+// Imports stay node builtins + sibling seams (sessionData.ts, result.ts) so the module loads
+// under `node --test`; no manual `scratch`/`runs` path segments (cacheGuard.test.ts).
+
+import { relative } from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { failFor, ok, type Result } from "../substrate/result.ts";
+import {
+  activeSessionRunId,
+  digestSessionData,
+  readSessionArtifact,
+  type SessionDataCtx,
+  writeSessionArtifact,
+} from "../substrate/sessionData.ts";
+import { paramsOf, stringParam } from "../substrate/toolParams.ts";
+import type { EntrySink } from "../substrate/workflowState.ts";
+import type { ReportTarget } from "../surfaces/report.ts";
+
+/** The gist consumption tiers (`scope` — contracts.md §8.41). */
+export const GIST_SCOPES = ["plan", "objective"] as const;
+
+export type GistScope = (typeof GIST_SCOPES)[number];
+
+/** The decoded `gist_save` tool params (shared with `gist_draft`). */
+export interface GistSaveParams {
+  prose: string;
+  title?: string;
+  scope?: GistScope;
+}
+
+/**
+ * Decode unknown `gist_save` tool-call params (the tool-boundary seam). `prose` absent decodes
+ * to `""` (so `saveGist`'s "no gist prose to save" `invalid_input` arm keeps owning that
+ * message) but present-but-mistyped → null (strict-fail); a present `scope` outside the enum is
+ * likewise a strict-fail (the schema already declares the enum — a bad value means a malformed
+ * call, never a silent default).
+ */
+export function decodeGistSaveParams(params: unknown): GistSaveParams | null {
+  const p = paramsOf(params);
+  if (p === null) return null;
+  const prose = stringParam(p, "prose");
+  const title = stringParam(p, "title");
+  const scope = stringParam(p, "scope");
+  if (prose === null || title === null || scope === null) return null;
+  if (scope !== undefined && !(GIST_SCOPES as readonly string[]).includes(scope)) return null;
+  return { prose: prose ?? "", title, scope: scope as GistScope | undefined };
+}
+
+/** The fixed working-gist artifact name (one JSON file: the prose + the optional scope hint). */
+export const GIST_DRAFT_ARTIFACT = "gist-draft.json";
+
+/** The ok-arm details — provenance-consistent with the recorded `session_artifacts` pointer. */
+export interface GistDraftOk {
+  name: string;
+  path: string;
+  digest: string;
+  bytes: number;
+  run_id: string;
+}
+
+export type GistDraftResult = Result<GistDraftOk>;
+
+/**
+ * The core both the tool handler and tests call: serialize the working gist (prose + the
+ * optional title/scope) as one JSON artifact and write it through the accessor seam (file +
+ * `session_artifacts` provenance pointer). Soft result, never throws — failure taxonomy: empty
+ * prose → `invalid_input`; no session run_id → `no_run_id`; file-or-pointer write failure →
+ * `write_failed` (the seam already warned).
+ */
+export function writeGistDraft(
+  sink: EntrySink,
+  ctx: SessionDataCtx & ReportTarget,
+  opts: { prose: string; title?: string; scope?: GistScope },
+): GistDraftResult {
+  const fail = failFor(ctx, "gist-draft");
+
+  if (!opts.prose.trim()) {
+    return fail("no gist prose to write (pass the full working draft)", "invalid_input");
+  }
+
+  const runId = activeSessionRunId(ctx);
+  if (runId === null) {
+    return fail("session has no run_id — cannot write the gist-draft artifact", "no_run_id");
+  }
+
+  // Deterministic key order via the explicit literal; `title`/`scope` are omitted when blank.
+  const title = opts.title?.trim();
+  const payload = {
+    schema_version: 1,
+    ...(title ? { title } : {}),
+    ...(opts.scope ? { scope: opts.scope } : {}),
+    prose: opts.prose,
+  };
+  const content = `${JSON.stringify(payload, null, 2)}\n`;
+
+  const written = writeSessionArtifact(sink, ctx, GIST_DRAFT_ARTIFACT, content);
+  if (written === null) {
+    return fail(
+      `could not write the ${GIST_DRAFT_ARTIFACT} artifact (see warnings)`,
+      "write_failed",
+    );
+  }
+
+  // Derive digest/relative path consistently with the pointer the seam recorded.
+  const digest = digestSessionData(content);
+  const relPath = relative(ctx.cwd, written);
+  return ok(`Gist draft written → ${relPath} (${digest})`, {
+    name: GIST_DRAFT_ARTIFACT,
+    path: relPath,
+    digest,
+    bytes: Buffer.byteLength(content, "utf8"),
+    run_id: runId,
+  });
+}
+
+// ------------------------------------------------------------------- the reader + the renderer
+
+/** The validated working-gist draft shape consumers receive from `readGistDraft`. */
+export interface GistDraft {
+  title?: string;
+  scope?: GistScope;
+  prose: string;
+}
+
+/**
+ * Read + validate the working-gist draft artifact. Fail-open `null` everywhere (mirroring
+ * `readSessionArtifact`'s loud tier): no pointer/file/digest → `null` (the seam already spoke);
+ * malformed JSON, a non-object payload, an unsupported `schema_version`, or blank prose → a
+ * stderr warning + `null`. `title` is kept only when a non-blank string; `scope` only when a
+ * member of the enum (an unknown scope degrades to absent, never poisons the draft). Never
+ * throws.
+ */
+export function readGistDraft(ctx: SessionDataCtx): GistDraft | null {
+  const artifact = readSessionArtifact(ctx, GIST_DRAFT_ARTIFACT);
+  if (artifact === null) return null;
+
+  const refuse = (why: string): null => {
+    console.error(`perk: warning: ${GIST_DRAFT_ARTIFACT} ${why} — refusing the draft`);
+    return null;
+  };
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(artifact.content);
+  } catch {
+    return refuse("is not valid JSON");
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return refuse("is not a JSON object");
+  }
+  const payload = parsed as Record<string, unknown>;
+  if (payload.schema_version !== 1) {
+    return refuse(`has an unsupported schema_version (${JSON.stringify(payload.schema_version)})`);
+  }
+  const prose = payload.prose;
+  if (typeof prose !== "string" || !prose.trim()) {
+    return refuse("has no prose");
+  }
+  const title =
+    typeof payload.title === "string" && payload.title.trim() ? payload.title : undefined;
+  const scope =
+    typeof payload.scope === "string" && (GIST_SCOPES as readonly string[]).includes(payload.scope)
+      ? (payload.scope as GistScope)
+      : undefined;
+  return {
+    ...(title !== undefined ? { title } : {}),
+    ...(scope !== undefined ? { scope } : {}),
+    prose,
+  };
+}
+
+/**
+ * Render the draft as the markdown review surface (JSON is storage/transport only — contracts
+ * §8.1): the optional `# title` heading, a `Scope:` line when the hint is set, and the prose
+ * verbatim. Pure; never throws.
+ */
+export function renderGistDraft(draft: GistDraft): string {
+  let out = "";
+  if (draft.title) out += `# ${draft.title}\n\n`;
+  if (draft.scope) out += `Scope: ${draft.scope}\n\n`;
+  return out + draft.prose;
+}
+
+const TOOL_GUIDELINES = [
+  "Call gist_draft to persist the current working gist as you author or revise it; pass the FULL prose each time (it rewrites the whole draft).",
+  "gist_draft never saves to the issue backend and never ends the turn — gist_save//gist-save remain the canonical save surface.",
+  "Pass gist_draft's `scope` only once the consumption tier is settled: `plan` for plan-sized intent, `objective` for objective-sized intent.",
+];
+
+/** Register the `gist_draft` tool (the carve-out producer; interior-only). */
+export function registerGistDraft(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "gist_draft",
+    label: "Gist draft",
+    description:
+      "Write (or overwrite) the working gist draft — the statement-of-intent prose + an " +
+      "optional scope hint — to the session data dir and record its provenance pointer. The " +
+      "only sanctioned write surface while read-only. NOT a save — gist_save//gist-save still " +
+      "persist the gist to the issue backend.",
+    promptSnippet:
+      "Persist the working gist draft (statement-of-intent prose) to the session data dir (full rewrite)",
+    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) {
+      // The shared param contract: the same decode as `gist_save`, so the two cannot drift.
+      const decoded = decodeGistSaveParams(params);
+      if (decoded === null) {
+        return failFor(
+          ctx,
+          "gist-draft",
+          "gist_draft",
+        )(
+          "gist_draft needs { prose: string, scope?: plan|objective } per the tool schema",
+          "bad_input",
+        );
+      }
+      return writeGistDraft(pi, ctx, decoded);
+    },
+  });
+}