@mgiles/perk 1.1.0 → 2.0.0

package/extension/factories/planMode.ts

@@ -4,7 +4,8 @@
 // perk owns NO parallel enforcement here — the gate is the single read-only authority.
 //
 // It also injects the cooperative *plan-authoring* prompt layer (the gather-then-plan contract)
-// under its own `perk:plan-context` customType (display:false),
+// under its own `perk:plan-context` customType (display:false, once-only: branch-scan dedup'd on
+// the marker),
 // keyed directly off the read-only gate (read-only ⟹ plan in the main session). The
 // content is stripped from `context` when the gate is off — the same hygiene the gate applies to its
 // `perk:mode-context`. An optional `[workflow] plan_authoring` config addendum (extension/substrate/config.ts)
@@ -30,9 +31,9 @@
 //     handler-time deferral alone is insufficient once the foreign package is loaded).
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { Key } from "@earendil-works/pi-tui";
 import { registerPerkCommand } from "../substrate/command.ts";
 import { loadPerkConfig } from "../substrate/config.ts";
+import { render } from "../substrate/prompts.ts";
 import {
   loadProviders,
   PERK_PLAN_PROVIDER_ID,
@@ -40,8 +41,11 @@ import {
   resolveProviders,
 } from "../substrate/providers.ts";
 import type { ToolGating } from "../substrate/toolGating.ts";
-import { branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
+import { branchCarries, branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
 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 { OBJECTIVE_AUTHOR_STAGE } from "./objectiveAuthor.ts";
 
 /** The plan-authoring context customType (distinct from the gate's `perk:mode-context`). */
@@ -54,40 +58,9 @@ const PLAN_MARKER = "[PLAN AUTHORING]";
  * decision-complete plan an executor with zero prior context can follow (mirrors
  * skills/perk-plan/SKILL.md). Durable anchors only, no line numbers.
  */
-export const PLAN_AUTHORING_CONTEXT = `${PLAN_MARKER}
-You are authoring a perk plan in read-only mode — explore first, then write.
-
-Gather before you plan. Materialize four finding categories from real evidence:
-- Status: what exists today (the current behavior, where it lives).
-- Discoveries: concrete findings with real file paths and function/class names.
-- Corrections: assumptions that turned out wrong, and what is actually true.
-- Codebase evidence: the specific code you verified each decision against.
-
-Check \`docs/learned/\` for relevant prior art and gotchas before you plan. The ambient routing
-index in your system prompt points into the full catalog at \`docs/learned/index.md\`; when a
-routing cue matches your change, \`read\` that doc. This is a check, not a requirement — there may
-be nothing relevant to your change, and your plan does not need to be grounded in prior learnings.
-
-Write the plan so an executor (a future session, or another engineer) with zero prior context can
-implement it without guessing. Anchor every change durably — function/class names, behavioral
-descriptions, structural locations — never line numbers. Resolve every open choice before saving;
-a saved plan must leave no decisions to the implementer.
-
-When the plan is decision-complete, request a human review:
-- Keep the working draft current with plan_draft — the validated plan-draft artifact is what gets
-  reviewed AND auto-saved.
-- Call the plan_review tool — the human reviews the plan in the configured review surface (perk's
-  in-TUI editor review by default).
-- If the review is DENIED: revise per the feedback, rewrite the draft with plan_draft, then call
-  plan_review again.
-- If the review is APPROVED: the plan is auto-saved and the session leaves read-only. Relay the
-  save outcome — do NOT re-dump the plan as a final message and do NOT tell the user to run
-  /plan-save.
-- If the review returns IMPLEMENT HERE: the human chose to implement without saving an issue —
-  the session is read-write; implement the plan now in this checkout (edits only; leave git
-  gestures to the user).
-- If plan_review reports it was skipped or unavailable (headless, dismissed, no surface): present
-  the complete plan as your final message; the human runs /plan-save (the manual failsafe).`;
+export const PLAN_AUTHORING_CONTEXT = render("contexts/plan-authoring.md", {
+  marker: PLAN_MARKER,
+});
 
 /** Build the full plan-authoring injection, appending the project config addendum when present. */
 export function planContextContent(cwd: string): string {
@@ -98,13 +71,19 @@ export function planContextContent(cwd: string): string {
 /**
  * The resolved `[providers] plan` selection id for `cwd`, read fresh per-event (no static state —
  * the same per-event-read shape `planContextContent(ctx.cwd)` uses). Fail-safe to the perk-plan
- * reference: any load/resolution failure (corrupt bundled set, etc.) returns the reference id so
- * perk's own plan mode keeps working — the default path is the hard guarantee.
+ * reference: any load/resolution failure returns the reference id so perk's own plan mode keeps
+ * working — the default path is the hard guarantee. With the resolver's per-seam fail-open
+ * fallbacks this catch narrows to genuine file-read/parse failures — logged loudly (consoleCapture
+ * routes it into the session log), never swallowed: a silent catch here once masked a
+ * version-skew throw and silently swapped the review surface to first-party.
  */
 export function resolvedPlanProviderId(cwd: string): string {
   try {
     return resolveProviders(loadPerkConfig(cwd).providers, loadProviders()).plan.id;
-  } catch {
+  } catch (error) {
+    console.error(
+      `perk: plan provider resolution failed — falling back to ${PERK_PLAN_PROVIDER_ID}: ${error}`,
+    );
     return PERK_PLAN_PROVIDER_ID;
   }
 }
@@ -185,6 +164,9 @@ export function registerPlanMode(pi: ExtensionAPI, gating: ToolGating): void {
     if (!gating.isActive()) return;
     const branch = branchOf(ctx);
     if (rebuildWorkflowState(branch).stage === OBJECTIVE_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;
     return {
       message: {
         customType: PLAN_CONTEXT_TYPE,