@mgiles/perk 2.3.0 → 3.1.0

package/extension/factories/objectiveSave.ts

@@ -15,8 +15,10 @@
 // FAILSAFE invocation of the same seam, keeping the legacy drive-the-session behavior as the
 // no-draft fallback (objectives have no transcript scrape by design).
 
+import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { bindingSuffix } from "../substrate/bindingDelivery.ts";
+import { atomicWriteFileSync, ensureRunScratch } from "../substrate/cache.ts";
 import {
   booleanField,
   type ColdJson,
@@ -32,10 +34,25 @@ import { appendWorkflowState, branchOf, rebuildWorkflowState } from "../substrat
 import { report, type Severity } from "../surfaces/report.ts";
 import { OBJECTIVE_BUDGET_TYPE } from "./objective.ts";
 import {
+  DELIVERY_PARAM_SCHEMA,
+  type DeliveryChoice,
+  DREAM_REPORT_PARAM_SCHEMA,
   decodeObjectiveSaveParams,
   ROADMAP_PARAM_SCHEMA,
   readObjectiveDraft,
 } from "./objectiveDraft.ts";
+import { resolveDreamReportGate } from "./objectiveDreamReport.ts";
+
+/** The `objective-save` registry stage id (the objectiveAuthor.ts constant's sibling). */
+export const OBJECTIVE_SAVE_STAGE = "objective-save";
+
+/**
+ * The run-scoped dream-report transfer filename (contracts §8.64) — the extension→door handoff
+ * carrying the reviewed CANONICAL parts. The Python mirror is
+ * `perk.learn.dream_companion.DREAM_REPORT_TRANSFER_FILENAME` (parity-pinned by test), beside
+ * the existing `DREAM_MANIFEST_FILENAME` mirror pair.
+ */
+export const DREAM_REPORT_TRANSFER_FILENAME = "dream-report-transfer.json";
 
 /** The ok-arm fields — the structured `details` surface doubles as branch-safe persisted state. */
 export interface ObjectiveSaveOk {
@@ -65,11 +82,25 @@ function decodeObjectiveCreate(payload: ColdJson): ObjectiveCreatePayload | null
  * The single save implementation both surfaces call. Delegates the GitHub write to the Python cold
  * door, then links the live session (`active_objective` + budget marker). Returns a soft result
  * (never throws); failures set `details.ok = false` and append no linkage.
+ *
+ * `dream_report` is ONE carrier with two sources (§8.63): the direct tool path supplies
+ * `{input}` and the save stamps `generated_at`; the approval path passes the artifact block
+ * through with its stored stamp AND stored parts — the stored parts are byte-compared against
+ * the freshly re-rendered ones, so run-scratch drift or artifact tamper between draft-write
+ * and save refuses `bad_state` (nothing saved, the gate stays on). The parts do NOT cross to
+ * the Python plane yet — companion persistence is deferred (explicit in §8.63, not silent).
  */
 export async function saveObjective(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
-  opts: { prose: string; title?: string; roadmap?: unknown[]; base?: string },
+  opts: {
+    prose: string;
+    title?: string;
+    roadmap?: unknown[];
+    base?: string;
+    delivery?: DeliveryChoice;
+    dream_report?: { input: unknown; generated_at?: string; parts?: string[] };
+  },
 ): Promise<ObjectiveSaveResult> {
   const fail = failFor(ctx, "objective-save");
 
@@ -80,12 +111,57 @@ export async function saveObjective(
     return fail("roadmap must be a JSON array of nodes", "invalid_input");
   }
 
+  // The §8.63 fail-closed re-validation, before anything reaches the cold door. Presence is
+  // the `opts.dream_report === undefined` boundary — an `{input: undefined}` carrier is never
+  // constructed (the execute wraps only a present decoded value; the approval path passes the
+  // validated artifact block).
+  const generatedAt = opts.dream_report?.generated_at ?? new Date().toISOString();
+  const gate =
+    opts.dream_report === undefined
+      ? resolveDreamReportGate(ctx, undefined, generatedAt)
+      : resolveDreamReportGate(ctx, opts.dream_report.input, generatedAt);
+  if (gate.kind === "refuse") {
+    return fail(gate.detail, gate.errorType);
+  }
+  if (gate.kind === "block" && opts.dream_report?.parts !== undefined) {
+    // The approval path: the reviewed (stored) parts must byte-match the re-render against
+    // freshly recovered context — the same stored `generated_at` stamp keeps the comparison
+    // deterministic.
+    if (JSON.stringify(gate.block.parts) !== JSON.stringify(opts.dream_report.parts)) {
+      return fail(
+        "the reviewed report no longer matches the wave state — re-draft and re-review",
+        "bad_state",
+      );
+    }
+  }
+
   const branch = () => branchOf(ctx);
   const runId = rebuildWorkflowState(branch()).run_id ?? "";
 
+  if (gate.kind === "block") {
+    // The §8.64 transfer write (the dream arm only): the reviewed CANONICAL parts cross to the
+    // Python save door through the run-scoped scratch handoff — written atomically BEFORE the
+    // cold door is invoked. A write failure is the soft `scratch_failed` failure (the
+    // runColdDoor stdin-staging precedent): the cold door is NOT invoked, nothing activates,
+    // and the read-only gate stays on. Non-dream saves write nothing (byte-identical).
+    try {
+      const dir = ensureRunScratch(ctx.cwd, runId);
+      const content = `${JSON.stringify(
+        { schema_version: "1", run_id: runId, parts: gate.block.parts },
+        null,
+        2,
+      )}\n`;
+      atomicWriteFileSync(join(dir, DREAM_REPORT_TRANSFER_FILENAME), content);
+    } catch (err) {
+      return fail(`could not stage the dream-report transfer: ${String(err)}`, "scratch_failed");
+    }
+  }
+
   const args = ["objective", "create", "--json"];
   if (opts.title) args.push("--title", opts.title);
   if (opts.base) args.push("--base", opts.base);
+  // The reviewed delivery choice rides verbatim; the cold door owns validation + preflight.
+  if (opts.delivery) args.push("--delivery", opts.delivery);
   if (runId) args.push("--run-id", runId);
   if (opts.roadmap && opts.roadmap.length > 0) {
     args.push("--roadmap", JSON.stringify(opts.roadmap));
@@ -161,6 +237,10 @@ export async function objectiveApprovalSave(
     title: opts.title ?? draft.title,
     roadmap: draft.roadmap,
     base: draft.base,
+    delivery: draft.delivery,
+    // The approval path passes the artifact block through whole — stored stamp + stored parts
+    // (the save re-validates and byte-compares, §8.63).
+    ...(draft.dream_report !== undefined ? { dream_report: draft.dream_report } : {}),
   });
   let gateExited = false;
   if (result.details.ok && wasReadOnly) {
@@ -216,6 +296,8 @@ export function registerObjectiveSave(pi: ExtensionAPI, gating: ToolGating): voi
           description:
             "Optional target branch for this objective's plans (omit to use the repo default).",
         },
+        delivery: DELIVERY_PARAM_SCHEMA,
+        dream_report: DREAM_REPORT_PARAM_SCHEMA,
         roadmap: {
           type: "array",
           description:
@@ -236,7 +318,13 @@ export function registerObjectiveSave(pi: ExtensionAPI, gating: ToolGating): voi
           "bad_input",
         );
       }
-      return saveObjective(pi, ctx, decoded);
+      // The direct tool path wraps ONLY a present decoded value as the `{input}` carrier (the
+      // save stamps generated_at); no stored parts, so no byte-compare on this path.
+      const { dream_report, ...rest } = decoded;
+      return saveObjective(pi, ctx, {
+        ...rest,
+        ...(dream_report !== undefined ? { dream_report: { input: dream_report } } : {}),
+      });
     },
   });
 

package/extension/factories/planMode.ts

@@ -13,7 +13,7 @@
 //
 // Grounded in pi's official `examples/extensions/plan-mode/` recipe, but perk adopts ONLY the
 // read-only authoring half: there is no in-session "execution mode" flip — perk separates plan
-// (read-only session) from implement (cold-door fresh worktree session), and `[DONE:n]` tracking
+// (read-only session) from implement (cold-door fresh worktree session), and progress tracking
 // lives in the implement session.
 //
 // REGISTRATION-TIME DEFERRAL, now THREE-TIER. `registerPlanMode` resolves the plan
@@ -56,8 +56,10 @@ 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 (mirrors
- * skills/perk-plan/SKILL.md). Durable anchors only, no line numbers.
+ * 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,