@mgiles/perk 2.3.0 → 3.1.0

package/README.md

@@ -65,7 +65,7 @@ For the guided first run, follow
 
 ## Documentation
 
-Operator docs live under [`docs/user-docs/`](docs/user-docs/index.md):
+Operator docs live under [`docs/user-docs/`](docs/user-docs/index.mdx):
 
 - **[Tutorials](docs/user-docs/tutorials/index.md)** — learn by doing; start with
   [Get started with perk](docs/user-docs/tutorials/get-started.md).

package/extension/adapters/planAdapterPlannotator.ts

@@ -7,12 +7,17 @@
 // INJECTION + BRIDGE ONLY: the `plan_review` TOOL lives in `extension/factories/planReview.ts`
 // (perk's backend-neutral review door); this module is the injection-only adapter shape. It owns
 // (1) the plannotator review-step authoring context (injected while the gate is active AND
-// plannotator is selected — TWO content flavors, one customType, each once-only: branch-scan
-// dedup'd on the flavor's marker: the plan bridge context, or the
-// objective flavor when the stage is `objective-author`) and (2) the pure event-bus bridge
-// (`createPlannotatorBridge`) that planReview.ts dispatches to when plannotator is the
-// selected plan provider. The bridge speaks plannotator's published `plannotator:request` event
-// API (in-process `pi.events` bus).
+// plannotator is selected — THREE content flavors, one customType, each once-only: branch-scan
+// dedup'd on the flavor's marker: the plan bridge context, the objective flavor when the stage
+// is `objective-author` or `objective-save` (both objective stages route to the objective
+// review arm), or the gist flavor when the stage is `gist-author`) and (2) the pure
+// event-bus bridge
+// (`requestPlannotatorPlanReview`; `createPlannotatorBridge` is its thin structural wrapper)
+// that planReview.ts dispatches to when plannotator is the selected plan provider and the
+// plan-review browser open (plannotatorHandoff.ts) launches. The bridge speaks plannotator's
+// published `plannotator:request` event API (in-process `pi.events` bus); the decision wait is
+// a per-review `plannotator:review-result` listener disposed via the unsubscribe pi's
+// `EventBus.on` returns.
 //
 // INERT BY DEFAULT. The shim is ALWAYS registered in index.ts but the injection fires only when
 // the resolved `[providers] plan` selection is `plannotator-plan` (read fresh per-event, same
@@ -46,7 +51,9 @@
 
 import { randomUUID } from "node:crypto";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { GIST_AUTHOR_STAGE } from "../factories/gistAuthor.ts";
 import { OBJECTIVE_AUTHOR_STAGE } from "../factories/objectiveAuthor.ts";
+import { OBJECTIVE_SAVE_STAGE } from "../factories/objectiveSave.ts";
 import { resolvedPlanProviderId } from "../factories/planMode.ts";
 // Type-only (erased at runtime — no cycle): the outcome vocabulary lives with the review door.
 import type { ReviewOutcome } from "../factories/planReview.ts";
@@ -58,6 +65,7 @@ import { branchCarries, branchOf, rebuildWorkflowState } from "../substrate/work
 export const PLAN_ADAPTER_PLANNOTATOR_CONTEXT_TYPE = "perk:plan-adapter-plannotator";
 const PLAN_ADAPTER_PLANNOTATOR_MARKER = "[PLAN ADAPTER: PLANNOTATOR]";
 const OBJECTIVE_ADAPTER_PLANNOTATOR_MARKER = "[OBJECTIVE ADAPTER: PLANNOTATOR]";
+const GIST_ADAPTER_PLANNOTATOR_MARKER = "[GIST ADAPTER: PLANNOTATOR]";
 
 /**
  * The handshake timeout for plannotator's immediate `respond` callback (mirrors plannotator's own
@@ -80,8 +88,8 @@ export const PLAN_ADAPTER_PLANNOTATOR_CONTEXT = render("contexts/adapters/planno
 });
 
 /**
- * The objective flavor of the bridge prompt, injected in an
- * `objective-author` session instead of the plan flavor. An APPROVED review auto-saves the
+ * The objective flavor of the bridge prompt, injected in an objective-authoring session
+ * (stage `objective-author` or `objective-save`) instead of the plan flavor. An APPROVED review auto-saves the
  * objective via the `objectiveApprovalSave` seam; `/objective-save` is the manual failsafe on
  * the skipped/unavailable arms.
  */
@@ -90,6 +98,16 @@ export const OBJECTIVE_ADAPTER_PLANNOTATOR_CONTEXT = render(
   { marker: OBJECTIVE_ADAPTER_PLANNOTATOR_MARKER },
 );
 
+/**
+ * The gist flavor of the bridge prompt, injected in a `gist-author` session instead of the
+ * plan/objective flavors. The review surface renders the gist draft (title + scope line +
+ * prose); an approval carrying `# Direct Edits` does NOT auto-save — the model folds the diff
+ * into the matching `gist_draft` fields and re-reviews (contracts.md §8.23's gist arm).
+ */
+export const GIST_ADAPTER_PLANNOTATOR_CONTEXT = render("contexts/adapters/plannotator-gist.md", {
+  marker: GIST_ADAPTER_PLANNOTATOR_MARKER,
+});
+
 /** Whether the foreign `plannotator-plan` provider is the selected plan provider for `cwd`. */
 export function isPlannotatorPlanSelected(cwd: string): boolean {
   return resolvedPlanProviderId(cwd) === PLANNOTATOR_PLAN_PROVIDER_ID;
@@ -97,10 +115,10 @@ export function isPlannotatorPlanSelected(cwd: string): boolean {
 
 // ------------------------------------------------------------------ the event-bus bridge core
 
-/** The minimal `pi.events` surface the bridge needs (mirrors pi's EventBus). */
+/** The minimal `pi.events` surface the bridge needs (mirrors pi's EventBus, whose `on` returns an unsubscribe function). */
 export interface PlannotatorBus {
   emit(channel: string, data: unknown): void;
-  on(channel: string, handler: (data: unknown) => void): void;
+  on(channel: string, handler: (data: unknown) => void): () => void;
 }
 
 /** Plannotator's immediate `respond` handshake payload (pinned envelope, see header). */
@@ -117,84 +135,96 @@ interface ReviewDecision {
 }
 
 /**
- * Create the plannotator bridge over an event bus: ONE persistent `plannotator:review-result`
- * listener registered up front, resolving pending reviews from a Map keyed by reviewId (no
- * dependence on an undocumented `pi.events.off`). Pure over the bus → unit-testable offline with a
- * fake plannotator listener.
+ * The pure, offline-testable plan-review bridge (the ergonomic mirror of
+ * `requestPlannotatorCodeReview` in plannotatorHandoff.ts): emit ONE `plannotator:request` with
+ * `action: "plan-review"`, await the bounded `respond` handshake, then await the human decision
+ * on a PER-REVIEW `plannotator:review-result` listener — filtered on the handshake's `reviewId`
+ * and disposed via the unsubscribe `bus.on` returns when the decision arrives or the turn
+ * aborts. Pure over the bus → unit-testable offline with a fake plannotator listener.
  */
-export function createPlannotatorBridge(bus: PlannotatorBus): {
-  review(plan: string, signal?: AbortSignal): Promise<ReviewOutcome>;
-} {
-  const pending = new Map<string, (decision: ReviewDecision) => void>();
+export async function requestPlannotatorPlanReview(
+  bus: PlannotatorBus,
+  plan: string,
+  signal?: AbortSignal,
+): Promise<ReviewOutcome> {
+  if (signal?.aborted) return { status: "aborted" };
 
-  bus.on("plannotator:review-result", (data) => {
-    const d = data as { reviewId?: unknown; approved?: unknown; feedback?: unknown };
-    if (typeof d?.reviewId !== "string") return;
-    const resolve = pending.get(d.reviewId);
-    if (resolve === undefined) return;
-    pending.delete(d.reviewId);
-    resolve({
-      approved: d.approved === true,
-      feedback: typeof d.feedback === "string" && d.feedback.trim() ? d.feedback : undefined,
-    });
+  // 1. Emit the request and await the immediate `respond` handshake (bounded — fail-open).
+  const requestId = randomUUID();
+  let respondResolve: (response: HandshakeResponse) => void = () => {};
+  const handshake = new Promise<HandshakeResponse | "timeout">((resolve) => {
+    respondResolve = resolve;
   });
+  const timer = setTimeout(() => respondResolve("timeout" as never), handshakeTimeoutMs());
+  bus.emit("plannotator:request", {
+    requestId,
+    action: "plan-review",
+    payload: { planContent: plan, origin: "perk" },
+    respond: (response: unknown) => respondResolve(response as HandshakeResponse),
+  });
+  const response = await handshake;
+  clearTimeout(timer);
 
-  async function review(plan: string, signal?: AbortSignal): Promise<ReviewOutcome> {
-    if (signal?.aborted) return { status: "aborted" };
-
-    // 1. Emit the request and await the immediate `respond` handshake (bounded — fail-open).
-    const requestId = randomUUID();
-    let respondResolve: (response: HandshakeResponse) => void = () => {};
-    const handshake = new Promise<HandshakeResponse | "timeout">((resolve) => {
-      respondResolve = resolve;
-    });
-    const timer = setTimeout(() => respondResolve("timeout" as never), handshakeTimeoutMs());
-    bus.emit("plannotator:request", {
-      requestId,
-      action: "plan-review",
-      payload: { planContent: plan, origin: "perk" },
-      respond: (response: unknown) => respondResolve(response as HandshakeResponse),
-    });
-    const response = await handshake;
-    clearTimeout(timer);
+  if (response === "timeout") {
+    return {
+      status: "unavailable",
+      warning: "plannotator did not respond to the review request (handshake timeout)",
+    };
+  }
+  if (response?.status !== "handled") {
+    const detail = response?.error ? `: ${response.error}` : "";
+    return {
+      status: "unavailable",
+      warning: `plannotator reported ${response?.status ?? "an invalid response"}${detail}`,
+    };
+  }
+  const reviewId = response.result?.reviewId;
+  if (response.result?.status !== "pending" || typeof reviewId !== "string") {
+    return {
+      status: "unavailable",
+      warning: "plannotator handshake returned no pending reviewId",
+    };
+  }
 
-    if (response === "timeout") {
-      return {
-        status: "unavailable",
-        warning: "plannotator did not respond to the review request (handshake timeout)",
-      };
-    }
-    if (response?.status !== "handled") {
-      const detail = response?.error ? `: ${response.error}` : "";
-      return {
-        status: "unavailable",
-        warning: `plannotator reported ${response?.status ?? "an invalid response"}${detail}`,
-      };
-    }
-    const reviewId = response.result?.reviewId;
-    if (response.result?.status !== "pending" || typeof reviewId !== "string") {
-      return {
-        status: "unavailable",
-        warning: "plannotator handshake returned no pending reviewId",
-      };
-    }
+  // A turn aborted DURING the handshake wait must not wedge: `addEventListener("abort", …)` on
+  // an already-aborted signal never fires, so re-check before registering the decision wait.
+  if (signal?.aborted) return { status: "aborted" };
 
-    // 2. Await the human decision (no timeout — the reviewer takes as long as they take), but
-    //    honor a turn abort so an interrupted session never leaks a wedged promise.
-    return await new Promise<ReviewOutcome>((resolve) => {
-      const onAbort = (): void => {
-        pending.delete(reviewId);
-        resolve({ status: "aborted" });
+  // 2. Await the human decision (no timeout — the reviewer takes as long as they take), but
+  //    honor a turn abort so an interrupted session never leaks a wedged promise. Either exit
+  //    disposes the result listener via the unsubscribe.
+  return await new Promise<ReviewOutcome>((resolve) => {
+    let settled = false;
+    const finish = (outcome: ReviewOutcome): void => {
+      if (settled) return;
+      settled = true;
+      unsubscribe();
+      signal?.removeEventListener("abort", onAbort);
+      resolve(outcome);
+    };
+    const onAbort = (): void => finish({ status: "aborted" });
+    const unsubscribe = bus.on("plannotator:review-result", (data) => {
+      const d = data as { reviewId?: unknown; approved?: unknown; feedback?: unknown };
+      if (d?.reviewId !== reviewId) return;
+      const decision: ReviewDecision = {
+        approved: d.approved === true,
+        feedback: typeof d.feedback === "string" && d.feedback.trim() ? d.feedback : undefined,
       };
-      pending.set(reviewId, (decision) => {
-        signal?.removeEventListener("abort", onAbort);
-        resolve({ status: "completed", reviewId, ...decision });
-      });
-      signal?.addEventListener("abort", onAbort, { once: true });
+      finish({ status: "completed", reviewId, ...decision });
     });
-  }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
 
-  return { review };
+/**
+ * Create the plannotator bridge over an event bus — the thin structural slice
+ * (`{ review(plan, signal) }`) that `registerPlanReview` injects into the review door; the body
+ * lives in `requestPlannotatorPlanReview`.
+ */
+export function createPlannotatorBridge(bus: PlannotatorBus): {
+  review(plan: string, signal?: AbortSignal): Promise<ReviewOutcome>;
+} {
+  return { review: (plan, signal) => requestPlannotatorPlanReview(bus, plan, signal) };
 }
 
 // ------------------------------------------------------------------ Direct Edits extraction
@@ -260,8 +290,10 @@ export function extractDirectEdits(feedback: string): { diff: string; remainder?
  */
 export function registerPlanAdapterPlannotator(pi: ExtensionAPI): void {
   // Inject the bridge context while the read-only gate is active AND plannotator is selected.
-  // Two content flavors, one customType: an objective-author session (also read-only) gets the
-  // objective flavor (the review surface renders the objective draft); any other
+  // Three content flavors, one customType: an objective-authoring session (also read-only —
+  // BOTH objective stages: `plan_review` routes objective-author AND objective-save to the
+  // objective review arm) gets the objective flavor (the review surface renders the objective
+  // draft), a gist-author session gets the gist flavor (the rendered gist draft); any other
   // gated stage gets the plan flavor. The gate-active check reads the persisted
   // `perk:workflow-state.mode` (the gate's state twin) — never the gate itself.
   pi.on("before_agent_start", async (_event, ctx) => {
@@ -269,17 +301,28 @@ export function registerPlanAdapterPlannotator(pi: ExtensionAPI): void {
     const branch = branchOf(ctx);
     const state = rebuildWorkflowState(branch);
     if (state.mode !== "read-only") return;
-    const objectiveFlavor = state.stage === OBJECTIVE_AUTHOR_STAGE;
-    const content = objectiveFlavor
-      ? OBJECTIVE_ADAPTER_PLANNOTATOR_CONTEXT
-      : PLAN_ADAPTER_PLANNOTATOR_CONTEXT;
+    const flavor =
+      state.stage === OBJECTIVE_AUTHOR_STAGE || state.stage === OBJECTIVE_SAVE_STAGE
+        ? "objective"
+        : state.stage === GIST_AUTHOR_STAGE
+          ? "gist"
+          : "plan";
+    const content =
+      flavor === "objective"
+        ? OBJECTIVE_ADAPTER_PLANNOTATOR_CONTEXT
+        : flavor === "gist"
+          ? GIST_ADAPTER_PLANNOTATOR_CONTEXT
+          : PLAN_ADAPTER_PLANNOTATOR_CONTEXT;
     // Once-only PER FLAVOR: the dedup key is the flavor's marker (not the shared customType), so
-    // a stage change still delivers the missing flavor while a prior copy of the other flavor
+    // a stage change still delivers the missing flavor while a prior copy of another flavor
     // sits on the branch. Injected customs persist, so a live copy suppresses re-injection;
     // compaction dropping it makes the scan come up clean and the next turn re-injects.
-    const marker = objectiveFlavor
-      ? OBJECTIVE_ADAPTER_PLANNOTATOR_MARKER
-      : PLAN_ADAPTER_PLANNOTATOR_MARKER;
+    const marker =
+      flavor === "objective"
+        ? OBJECTIVE_ADAPTER_PLANNOTATOR_MARKER
+        : flavor === "gist"
+          ? GIST_ADAPTER_PLANNOTATOR_MARKER
+          : PLAN_ADAPTER_PLANNOTATOR_MARKER;
     if (branchCarries(branch, marker)) return;
     return {
       message: {
@@ -290,11 +333,12 @@ export function registerPlanAdapterPlannotator(pi: ExtensionAPI): void {
     };
   });
 
-  // Strip the stale bridge markers (BOTH flavors) from context when plannotator-plan is no
+  // Strip the stale bridge markers (ALL THREE flavors) from context when plannotator-plan is no
   // longer selected (same hygiene as the tombell shim), so they never linger across a deselect.
   const hasMarker = (text: string): boolean =>
     text.includes(PLAN_ADAPTER_PLANNOTATOR_MARKER) ||
-    text.includes(OBJECTIVE_ADAPTER_PLANNOTATOR_MARKER);
+    text.includes(OBJECTIVE_ADAPTER_PLANNOTATOR_MARKER) ||
+    text.includes(GIST_ADAPTER_PLANNOTATOR_MARKER);
   pi.on("context", async (event, ctx) => {
     if (isPlannotatorPlanSelected(ctx.cwd)) return;
     return {

package/extension/adapters/planAdapterTombell.ts

@@ -35,6 +35,7 @@
 //     stages bind only to the provider-agnostic plan-ref and are unchanged.
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { GIST_AUTHOR_STAGE } from "../factories/gistAuthor.ts";
 import { OBJECTIVE_AUTHOR_STAGE } from "../factories/objectiveAuthor.ts";
 import { resolvedPlanProviderId } from "../factories/planMode.ts";
 import { render } from "../substrate/prompts.ts";
@@ -89,13 +90,14 @@ export function registerPlanAdapterTombell(pi: ExtensionAPI): void {
   // Inject the bridge context while the foreign tombell-plan provider is selected AND a plan
   // authoring mode is on — perk's read-only gate (per the persisted `perk:workflow-state.mode`,
   // the gate's state twin — never the gate object) OR tombell's own persisted `plan-mode-state`
-  // entry (the ad-hoc interactive `/plan` arm). Objective-author sessions are excepted
-  // (objectiveAuthor owns that session; mirrors the plannotator adapter's recipe).
+  // entry (the ad-hoc interactive `/plan` arm). Objective-author and gist-author sessions are
+  // excepted (objectiveAuthor/gistAuthor own those sessions; mirrors the plannotator adapter's
+  // recipe — the tombell REPLACE posture covers the plan surface only).
   pi.on("before_agent_start", async (_event, ctx) => {
     if (!isTombellPlanSelected(ctx.cwd)) return;
     const branch = branchOf(ctx);
     const state = rebuildWorkflowState(branch);
-    if (state.stage === OBJECTIVE_AUTHOR_STAGE) return;
+    if (state.stage === OBJECTIVE_AUTHOR_STAGE || state.stage === GIST_AUTHOR_STAGE) return;
     if (state.mode !== "read-only" && !isTombellPlanModeEnabled(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.