@mgiles/perk 3.1.0 → 3.2.0

package/extension/doors/address.ts

@@ -46,6 +46,7 @@ import {
   runReviewClassifierWave,
 } from "../waves/reviewClassifierWave.ts";
 import { createRpcWaveAdapter } from "../waves/rpcAdapter.ts";
+import { planningStageRefusal } from "./lifecycleGates.ts";
 import { driveConflictResolution, type SubmitOk, submitPr } from "./submit.ts";
 
 export interface ThreadInput {
@@ -284,6 +285,10 @@ export async function finalizeAddress(
   params: ResolveParams,
 ): Promise<FinalizeAddressResult> {
   const fail = failFor<FinalizeAddressFailExtras>(ctx, "address", "finalize_address");
+  // Planning sessions never legitimately publish review fixes — the first check (a positioned
+  // stacked planning session's cwd binding is the PREDECESSOR).
+  const planningRefusal = planningStageRefusal(ctx, "address");
+  if (planningRefusal !== null) return fail(planningRefusal, "planning_session");
   if (params.threads.length === 0) {
     return fail("no threads to finalize (pass { threads: [{thread_id, comment?}] })", "bad_input");
   }
@@ -529,6 +534,12 @@ export function registerAddress(pi: ExtensionAPI): void {
       "Classify PR review feedback (isolated child) and resolve threads (submit → address). " +
       "Pass --preview to classify only (take no action).",
     handler: async (args, ctx) => {
+      // Planning sessions never legitimately run the review loop — the first check.
+      const planningRefusal = planningStageRefusal(ctx, "address");
+      if (planningRefusal !== null) {
+        report(ctx, "address", "warning", planningRefusal);
+        return;
+      }
       const preview = /(^|\s)--preview(\s|$)/.test(args ?? "");
       // `/address` needs an active plan-ref (the converged body carries the PR identity, and the
       // classifier child's `perk pr feedback` hard-errors `no_plan_ref` without one). Mirror the

package/extension/doors/dreamWaveTools.ts

@@ -131,12 +131,13 @@ function resultText(details: DreamWaveOk): string {
  * record) and returns whether the cleared state was VERIFIED (append + read-back) — a false
  * return stops the wave before any filesystem work or spawn, because proceeding over an
  * unverified invalidation could leave a prior bundle + prior digest pair recoverable; `set`
- * publishes the finalized bytes' digest and stays loud-but-non-fatal (a failed set leaves the
- * marker cleared by the entry clear, so recovery refuses — fail-closed, never silent). The
- * registered execute wires the production `appendWorkflowState` pair; tests inject fakes. */
+ * publishes the finalized bytes' digest and returns the append+read-back verification — a
+ * failed set makes the wave outcome honestly incomplete (the marker stays cleared by the
+ * entry clear, so recovery refuses — fail-closed, never silent). The registered execute wires
+ * the production `appendWorkflowState` pair; tests inject fakes. */
 export interface DreamBundleMarkers {
   clear(): boolean;
-  set(digest: string): void;
+  set(digest: string): boolean;
 }
 
 /**
@@ -175,7 +176,10 @@ export interface DreamBundleMarkers {
  *     undraftable), returning ok with `complete: false` and the bracket recorded;
  *  8. bracket ok ⇒ the finalize-in-place rewrite of the same fixed name; a throw ⇒ the second
  *     post-launch `io_error` fail arm (mirroring arm 5's extras); on success
- *     `markers.set(digest)` with the sha256 of the finalized bytes.
+ *     `markers.set(digest)` with the sha256 of the finalized bytes — a failed set (an
+ *     unverified append) makes the OK aggregate `complete: false` with a named
+ *     `digest-marker` failure entry (the wave ran; the outcome is honestly incomplete —
+ *     never the `io_error` fail arm), and the marker stays cleared so recovery refuses.
  */
 export async function executeDreamWave(
   adapter: WaveAdapter,
@@ -324,6 +328,7 @@ export async function executeDreamWave(
     // honest coverage reporting.
     bracket = opts.bracket();
   }
+  let markerSet = false;
   if (bracket?.ok === true) {
     // Finalize in place — the SAME fixed name gains the reducers section (never a second
     // file), then the digest marker publishes the finalized bytes for the recovery consumer.
@@ -344,13 +349,24 @@ export async function executeDreamWave(
         attempts,
       });
     }
-    // A failed marker append warns loudly via the seam's read-back check and leaves the
-    // marker cleared — recovery refuses (fail-closed); re-running the wave repairs it.
-    opts.markers.set(digestSessionData(finalized));
+    // A failed marker append (an unverified read-back) leaves the marker cleared by the
+    // entry clear — recovery refuses (fail-closed) — and the aggregate reports the outcome
+    // as honestly incomplete; re-running the wave repairs it.
+    markerSet = opts.markers.set(digestSessionData(finalized));
   }
 
+  const failures = [...reducers.failures];
+  if (bracket?.ok === true && !markerSet) {
+    failures.push({
+      angle: "digest-marker",
+      reason: "run-failed",
+      detail:
+        "dream_bundle_digest marker append failed its read-back — the marker stays cleared, " +
+        "so recovery refuses this bundle; re-run perk learn dream",
+    });
+  }
   const details: DreamWaveOk = {
-    complete: analysis.complete && reducers.complete && bracket?.ok === true,
+    complete: analysis.complete && reducers.complete && bracket?.ok === true && markerSet,
     analysis: analysisDetails,
     bracket,
     bundle: {
@@ -365,7 +381,7 @@ export async function executeDreamWave(
       skip_reason: null,
       complete: reducers.complete,
       reports: reducers.reports,
-      failures: reducers.failures,
+      failures,
     },
     attempts,
   };
@@ -444,8 +460,8 @@ export function registerDreamWave(pi: ExtensionAPI): void {
       const reducerModel = subagentModel(ctx.cwd, "dream-reducer");
       // The production digest-marker pair: the ordinary strict-append session-entry channel.
       // The boolean is the seam's verified append+read-back result — the execute core refuses
-      // the wave on an unverified CLEAR (fail-closed); a failed SET stays loud-but-non-fatal
-      // (the entry clear already invalidated, so recovery refuses).
+      // the wave on an unverified CLEAR (fail-closed); a failed SET makes the aggregate
+      // honestly incomplete (the entry clear already invalidated, so recovery refuses).
       const marker = (digest: string): boolean =>
         appendWorkflowState(pi, ctx, {
           data: { dream_bundle_digest: digest },
@@ -462,9 +478,7 @@ export function registerDreamWave(pi: ExtensionAPI): void {
         bracket: () => revalidationBracket(ctx.cwd, decoded.manifest.commit_sha),
         markers: {
           clear: () => marker(""),
-          set: (digest) => {
-            marker(digest);
-          },
+          set: (digest) => marker(digest),
         },
         ...(analystModel !== undefined ? { analystModel } : {}),
         ...(reducerModel !== undefined ? { reducerModel } : {}),

package/extension/doors/land.ts

@@ -21,6 +21,7 @@ import {
 import { registerPerkCommand } from "../substrate/command.ts";
 import { failFor, ok, type Result } from "../substrate/result.ts";
 import { report } from "../surfaces/report.ts";
+import { planningStageRefusal } from "./lifecycleGates.ts";
 
 // Learn-consume skip reasons that are ordinary, not failures: non-factory plans carry no
 // `consumed_learn` (`no_consumed_learn`), and a dry run reports `dry_run`. Anything else surfaces.
@@ -132,6 +133,11 @@ function decodeLand(payload: ColdJson): LandPayload | null {
 export async function landPr(pi: ExtensionAPI, ctx: ExtensionContext): Promise<LandResult> {
   const fail = failFor(ctx, "land");
 
+  // Planning sessions never legitimately land — the first check, before any cold-door
+  // delegation (a positioned stacked planning session's cwd binding is the PREDECESSOR).
+  const planningRefusal = planningStageRefusal(ctx, "land");
+  if (planningRefusal !== null) return fail(planningRefusal, "planning_session");
+
   const r = await runColdDoor<LandPayload>(pi, ctx, ["pr", "land", "--json"], {
     label: "perk pr land",
     decode: decodeLand,

package/extension/doors/learn.ts

@@ -13,8 +13,8 @@
 // it validates the angle selection in code (2–4 angles, `session-deviations` mandatory — the
 // §8.35 policy as tested implementation), derives the manifest path from the relayed
 // `bundle_dir`, resolves the analyst model from `[models.subagents] learn-analyst` (because
-// `subagents.agentOverrides` does NOT reach project agents, the model rides the wave as the
-// workflow-level `model` default), and runs 2–4 fresh-context `perk.learn-analyst` lanes through
+// an `agentOverrides` model can never displace the def's frontmatter-pinned `model:`, the model
+// rides the wave as the workflow-level `model` default), and runs 2–4 fresh-context `perk.learn-analyst` lanes through
 // `runLearnWave` (best-effort completeness: a failed analyst is an explicitly-reported skipped
 // angle). A wave-level failure soft-fails LOUDLY — never a silent fallback to model-authored
 // scripts; the guidance routes the parent to a single-context analysis of the bundle instead.
@@ -71,7 +71,7 @@ import {
   type WaveAttemptReceipt,
 } from "../waves/reportWave.ts";
 import { createRpcWaveAdapter } from "../waves/rpcAdapter.ts";
-import { planReadInstruction } from "./lifecycleGates.ts";
+import { planningStageRefusal, planReadInstruction } from "./lifecycleGates.ts";
 
 /** The ok-arm fields. */
 export interface LearnOk {
@@ -190,6 +190,12 @@ export async function learnDone(
   const trimmed = (summary ?? "").trim();
   const fail = failFor(ctx, "learn");
 
+  // Planning sessions never legitimately run the learn cycle — the first check, before any
+  // cold-door delegation (a positioned stacked planning session's cwd binding is the
+  // PREDECESSOR).
+  const planningRefusal = planningStageRefusal(ctx, "learn");
+  if (planningRefusal !== null) return fail(planningRefusal, "planning_session");
+
   // No summary: record the deliberate skip canonically (the cold door stamps the plan-header and
   // clears the marker; the skip carries no classification, so `decision`/`target` are
   // intentionally ignored on this arm). On failure the marker is NOT cleared — never silently
@@ -567,6 +573,13 @@ export function registerLearn(pi: ExtensionAPI): void {
       "/learn skip records the skip on the plan and clears pending-learn; " +
       "/learn <text> captures the text verbatim.",
     handler: async (args, ctx) => {
+      // Planning sessions never legitimately run the learn cycle — the first check (the
+      // orchestrating bare-/learn arm below never reaches learnDone, so it needs its own gate).
+      const planningRefusal = planningStageRefusal(ctx, "learn");
+      if (planningRefusal !== null) {
+        report(ctx, "learn", "warning", planningRefusal);
+        return;
+      }
       const trimmed = (args ?? "").trim();
 
       // Explicit text (or `skip`): the existing learnDone path — capture verbatim / record skip.

package/extension/doors/lifecycleGates.ts

@@ -16,9 +16,44 @@ import type {
 import type { PlanRef } from "../substrate/cache.ts";
 import { registerPerkCommand } from "../substrate/command.ts";
 import { render } from "../substrate/prompts.ts";
-import { branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
+import { type BranchSource, branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
 import { report } from "../surfaces/report.ts";
 
+// The planning stages whose sessions never legitimately run lifecycle doors. After an approved
+// save, a still-live planning session holds TWO plan identities — the cwd binding (a positioned
+// stacked session's predecessor checkout, read via readPlanRef(ctx.cwd)) and the just-saved plan
+// on active_plan_ref — so a door invocation there could act on the predecessor. At the repo root
+// the same invocation fails confusingly today; the refusal is honest in both shapes.
+const PLANNING_STAGES = new Set(["plan", "objective-plan"]);
+
+/**
+ * The planning-stage lifecycle-door refusal (the shared first check of the warm /submit,
+ * /address, /land, and /learn doors): when this session's workflow-state `stage` is a planning
+ * stage, return the refusal message directing the human at the fresh-session implement door;
+ * `null` otherwise (non-planning stages — and stage-less sessions — are unaffected). Fail-CLOSED
+ * on an unreadable branch: without the state this guard cannot prove the session is not a
+ * positioned planning session (whose cwd binding is the PREDECESSOR — the exact target it
+ * protects), so an unreadable read refuses rather than letting the door act.
+ */
+export function planningStageRefusal(ctx: BranchSource, door: string): string | null {
+  let stage: string | undefined;
+  try {
+    stage = rebuildWorkflowState(branchOf(ctx)).stage;
+  } catch (error) {
+    return (
+      `${door} is unavailable: the session's workflow state could not be read ` +
+      `(${String(error)}), so this cannot be proven not to be a planning session — ` +
+      "retry, or implement the saved plan with `perk impl <N>` in a fresh session."
+    );
+  }
+  if (stage === undefined || !PLANNING_STAGES.has(stage)) return null;
+  return (
+    `${door} is unavailable in a planning session (stage ${stage}): a planning session can ` +
+    "hold two plan identities (its checkout's own binding and the just-saved plan) — " +
+    "implement the saved plan with `perk impl <N>` in a fresh session instead."
+  );
+}
+
 const DIRTY_MESSAGE = "uncommitted changes — commit or stash before switching/forking this stage.";
 const HANDOFF_DIRTY_MESSAGE =
   "uncommitted changes — commit before a fresh-context /implement handoff (the plan is the " +