@mgiles/perk 3.1.0 → 3.3.0

package/extension/index.ts

@@ -1,79 +1,101 @@
-// perk Pi extension — the session *interior*.
+// perk Pi extension — the session *interior*: the composition root.
 //
-// The tier-3 session-state mechanics (contracts.md §8.2/§8.3): claim PERK_RUN_ID on
+// The tier-3 session-state mechanics (contracts.md §8.2/§8.3) — claim PERK_RUN_ID on
 // `session_start` (verified-linkage), rebuild `perk:workflow-state` on `session_start` AND
-// `session_tree` (per-field LWW), and derive a child run_id on fork.
+// `session_tree` (per-field LWW), derive a child run_id on fork, reconcile the stage-gated plan
+// linkage — are OWNED by `session/lifecycle.ts` (identity arms + the two-phase startup facts +
+// the navigation facts). This file binds the production ports and keeps the Pi effects visibly
+// ORDERED: gate sync from the pure scope slice → claimed-only refinement import → the post-gate
+// facts → implementation pointer capture → feedback receiver sync → presentation/probe tail.
 
 import { existsSync, mkdirSync } from "node:fs";
 import { basename, join } from "node:path";
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { registerPlanAdapterPlannotator } from "./adapters/planAdapterPlannotator.ts";
-import { registerPlanAdapterTombell } from "./adapters/planAdapterTombell.ts";
-import { registerAddress } from "./doors/address.ts";
-import { registerAnnotationPushTool } from "./doors/annotationPush.ts";
-import { registerAuditWave } from "./doors/auditWaveTools.ts";
-import { registerCiExecutor } from "./doors/ciExecutor.ts";
-import { registerCommitAndCompact } from "./doors/commitCompact.ts";
-import { registerDraftReviewWaveTools } from "./doors/draftReviewWaveTools.ts";
-import { registerDreamWave } from "./doors/dreamWaveTools.ts";
-import { registerHarvestWave } from "./doors/harvestWaveTools.ts";
-import { registerLand } from "./doors/land.ts";
-import { registerLearn } from "./doors/learn.ts";
-import { CODE_DOOR, DOCS_DOOR, registerLearnFactoryDoor } from "./doors/learnFactory.ts";
-import { registerLifecycleGates } from "./doors/lifecycleGates.ts";
+import { createDraftReviewWaveState } from "./authoring/review/draftContext.ts";
+import { createHunkFeedbackReceiver, type HunkFeedbackReceiver } from "./hunkFeedback/receiver.ts";
+import { registerBashScanTimeout } from "./pi/v1/bashScanTimeout.ts";
+import { installAutomatedReviewBindings } from "./pi/v1/codeReview/automated.ts";
+import { installPrReviewBrowserBindings } from "./pi/v1/codeReview/browser.ts";
+import { installReviewWaveBindings } from "./pi/v1/codeReview/reviewWave.ts";
+import { installStackReviewBindings } from "./pi/v1/codeReview/stack.ts";
+import { installCuratedSubmissionBindings } from "./pi/v1/codeReview/submit.ts";
+import { installPrReviewTerminalBindings } from "./pi/v1/codeReview/terminal.ts";
+import { installAddressBindings } from "./pi/v1/delivery/address.ts";
+import { installCiBindings } from "./pi/v1/delivery/ci.ts";
+import { installCommitCompactBindings } from "./pi/v1/delivery/commitCompact.ts";
+import {
+  type ConflictResolverEngineOptions,
+  createConflictResolverEngine,
+} from "./pi/v1/delivery/conflictResolverEngine.ts";
+import { installLandBindings } from "./pi/v1/delivery/land.ts";
+import { installReadyBindings } from "./pi/v1/delivery/ready.ts";
+import { createStackConflictResolver } from "./pi/v1/delivery/stackConflictResolver.ts";
+import { installStackLandBindings } from "./pi/v1/delivery/stackLand.ts";
+import { installStackRecoverBindings } from "./pi/v1/delivery/stackRecover.ts";
+import { installStackStatusBindings } from "./pi/v1/delivery/stackStatus.ts";
+import {
+  installStackSyncBindings,
+  type StackResolutionDelivery,
+} from "./pi/v1/delivery/stackSync.ts";
+import { installSubmitBindings } from "./pi/v1/delivery/submit.ts";
+import { installSubmitConflictBindings } from "./pi/v1/delivery/submitConflict.ts";
+import { createDraftReviewSlot } from "./pi/v1/draftReview.ts";
+import { registerDraftReviewWaveTools } from "./pi/v1/draftReviewWaveTools.ts";
+import { installGistBindings } from "./pi/v1/gist.ts";
+import { installAuditBindings } from "./pi/v1/learning/audit.ts";
+import { installDreamBindings } from "./pi/v1/learning/dream.ts";
+import { installLearnFactoryBindings } from "./pi/v1/learning/factory.ts";
+import { installHarvestBindings } from "./pi/v1/learning/harvest.ts";
+import { installLearnBindings } from "./pi/v1/learning/learn.ts";
+import { registerLifecycleGates } from "./pi/v1/lifecycleGates.ts";
+import { installObjectiveBindings } from "./pi/v1/objective.ts";
+import { installObjectiveAuthoringBindings } from "./pi/v1/objectiveAuthoring.ts";
+import { installObjectivePlanningBindings } from "./pi/v1/objectivePlanning.ts";
+import {
+  importRefinementContextOnClaim,
+  installObjectiveRefinementBindings,
+} from "./pi/v1/objectiveRefinement.ts";
 import {
   openObjectiveReviewSurface,
   registerObjectiveReviewBrowser,
-} from "./doors/objectiveReviewBrowser.ts";
-import { registerObjectiveStack } from "./doors/objectiveStack.ts";
-import { plannotatorPresent } from "./doors/plannotatorHandoff.ts";
-import { openPlanReviewSurface, registerPlanReviewBrowser } from "./doors/planReviewBrowser.ts";
-import { registerPrReview } from "./doors/prReview.ts";
-import { registerPrReviewBrowser } from "./doors/prReviewBrowser.ts";
-import { registerPrReviewDynamic } from "./doors/prReviewDynamic.ts";
-import { registerPrReviewTerminal } from "./doors/prReviewTerminal.ts";
-import { registerReady } from "./doors/ready.ts";
-import { registerReviewWaveTools } from "./doors/reviewWaveTools.ts";
-import { registerSelfcheck } from "./doors/selfcheck.ts";
-import { registerSubmit } from "./doors/submit.ts";
-import { registerSubmitPrReview } from "./doors/submitPrReview.ts";
-import { registerGistAuthor } from "./factories/gistAuthor.ts";
-import { registerGistDraft } from "./factories/gistDraft.ts";
-import { registerGistSave } from "./factories/gistSave.ts";
-import { registerImplementHere } from "./factories/implementHere.ts";
-import { registerObjective } from "./factories/objective.ts";
-import { registerObjectiveAuthor } from "./factories/objectiveAuthor.ts";
-import { registerObjectiveDraft } from "./factories/objectiveDraft.ts";
-import { registerObjectivePlan } from "./factories/objectivePlan.ts";
-import { registerObjectiveSave } from "./factories/objectiveSave.ts";
-import { registerPlanDraft } from "./factories/planDraft.ts";
-import { registerPlanMode } from "./factories/planMode.ts";
-import { registerPlanReview } from "./factories/planReview.ts";
-import { registerPlanSave } from "./factories/planSave.ts";
-import { createHunkFeedbackReceiver } from "./hunkFeedback/receiver.ts";
+} from "./pi/v1/objectiveReviewBrowser.ts";
+import { installPlanBindings } from "./pi/v1/plan.ts";
+import { openPlanReviewSurface, registerPlanReviewBrowser } from "./pi/v1/planReviewBrowser.ts";
+import { createAnnotationState, installAnnotationBindings } from "./pi/v1/providers/annotations.ts";
+import { installPlannotatorPlanAdapter } from "./pi/v1/providers/plannotator.ts";
+import { plannotatorPresent } from "./pi/v1/providers/plannotatorHandoff.ts";
+import { installTombellPlanAdapter } from "./pi/v1/providers/tombell.ts";
+import { installScoutWaveBindings } from "./pi/v1/scoutWave.ts";
+import { registerSelfcheck } from "./pi/v1/selfcheck.ts";
+import {
+  branchSessionStateStore,
+  establishSessionIdentity,
+  reflectSessionReadOnlyFloor,
+  resolveSessionStartFacts,
+  sessionStartToolScope,
+  sessionTreeFacts,
+} from "./session/lifecycle.ts";
 import { createAgentScratchProvisioner, registerAgentScratch } from "./substrate/agentScratch.ts";
 import { registerBindingDelivery } from "./substrate/bindingDelivery.ts";
 import {
   atomicWriteFileSync,
   ensureRunScratch,
+  listRunIds,
   markHandoffConsumed,
   readHandoff,
   readPlanRef,
   setMarker,
   workflowDir,
 } from "./substrate/cache.ts";
-import { loadRegistry, type Registry, stageConsumesPlanRef } from "./substrate/registry.ts";
+import { decodeReadOnlyFloor, isRunnerChild } from "./substrate/childRestrictions.ts";
+import { loadRegistry, type Registry } from "./substrate/registry.ts";
 import { perkVersion, sharedDir, versionStamp } from "./substrate/resources.ts";
 import { mintRunId } from "./substrate/runId.ts";
 import { captureSessionPointer } from "./substrate/sessionPointers.ts";
 import { registerToolGating } from "./substrate/toolGating.ts";
 import {
-  appendWorkflowState,
   branchOf,
-  decideClaim,
-  planRefsEqual,
   rebuildWorkflowState,
-  resolveRunStage,
   WORKFLOW_STATE_TYPE,
   type WorkflowState,
 } from "./substrate/workflowState.ts";
@@ -90,6 +112,7 @@ import {
 } from "./surfaces/surfaces.ts";
 import { registerBtw } from "./vendor/btw/btw.ts";
 import { registerWhimsical } from "./vendor/whimsical/whimsical.ts";
+import { createReportWave } from "./waves/reportWave.ts";
 
 // Cross-plane proof marker (TS writes via cache.ts; the Python helper reads it — gate check 3).
 const T3_MARKER = "t3-extension-cache-write";
@@ -123,18 +146,43 @@ function writeT3Sentinel(
   }
 }
 
-export default function (pi: ExtensionAPI) {
+export default function perk(
+  pi: ExtensionAPI,
+  options: {
+    resolverEngine?: Pick<ConflictResolverEngineOptions, "configPath" | "acquire">;
+    stackResolutionDelivery?: StackResolutionDelivery;
+    /**
+     * Construction-only: the hunk feedback receiver factory (default `createHunkFeedbackReceiver`).
+     * Constructed ONCE per activation exactly like production; the registered-path suites bind a
+     * recording receiver to observe the startup/navigation sync order and inputs.
+     */
+    feedbackReceiverFactory?: (pi: ExtensionAPI) => HunkFeedbackReceiver;
+  } = {},
+) {
   const version = perkVersion();
 
   // The read-only tool-gating primitive. Attaches to perk:workflow-state.mode; synced on
   // both session_start AND session_tree below. enter/exit are the surface the gated stages consume.
-  const gating = registerToolGating(pi);
+  // The two native-child booleans (§8.3), re-read at every session_start: the runner bit (also the
+  // `() => runnerChild` closure every injected authoring/adapter context takes as its fence — the
+  // REAL closure, never a constant), and the read-only floor a runner child derives from the
+  // report restriction packet — latched for the activation (`||=`) so no later session_start,
+  // gate exit, or tree navigation can clear it.
+  let runnerChild = false;
+  let readOnlyFloor = false;
+  const gating = registerToolGating(pi, () => readOnlyFloor);
+
+  // The bash scan-timeout guard: always on in every perk session — gated or not, runner children
+  // included (the slow gitignore-blind scans were observed in read-write sessions too). The gate's
+  // `tool_call` hook runs first only because it registers first; a gate block short-circuits
+  // before injection matters.
+  registerBashScanTimeout(pi);
 
   // Run-owned disposable scratch guidance for every eligible write-capable model turn. One
   // activation-scoped provisioner shares retry/warning suppression with the isolated /btw side
   // session; no model tool or process-global temp environment is introduced.
   const agentScratch = createAgentScratchProvisioner();
-  registerAgentScratch(pi, agentScratch);
+  registerAgentScratch(pi, agentScratch, () => !gating.isActive() && !runnerChild);
 
   // Vendored `btw`: a `/btw` human-only side-chat popover backed by an isolated in-memory
   // AgentSession. Takes `gating` for the gate-mirror — its side-session toolset + cache key follow
@@ -147,46 +195,123 @@ export default function (pi: ExtensionAPI) {
   // turn, via the headless-no-op `setWorkingMessage` surfaces seam. Always on, no config toggle.
   registerWhimsical(pi);
 
-  // perk-owned plan mode: the `/plan` + Ctrl+Alt+P + `--plan` toggle surface over the
-  // read-only gate, plus the plan-authoring context injection. perk owns plan mode end-to-end now (the
-  // borrowed `@tombell/pi-plan` is retired).
-  registerPlanMode(pi, gating);
+  // The draft-review pair's per-activation state: ONE instance serves the `plan_review` wave
+  // arm (via the closures below), the two draft-review browser doors, and the
+  // `start_draft_review_wave`/`collect_draft_review_wave` tool pair — per activation, never per
+  // process (two bound sessions in one process share nothing). Plain object construction, so
+  // creating it before any registration is order-safe.
+  const draftReviewWave = createDraftReviewWaveState();
+
+  // The annotation-push per-activation state: ONE instance serves the `push_annotations`
+  // installer and every priming door — the PR/stack review doors (review mode) and the
+  // plan/objective review doors (plan mode) — per activation, never per process (the
+  // `draftReviewWave` threading pattern).
+  const annotations = createAnnotationState();
+
+  // The composition root's ONE per-activation report-wave instance (the `draftReviewWave`
+  // threading pattern): the wave owns adapter selection (a fresh rpc adapter per launch over
+  // pi's event bus) and pending execution (instance-owned refs), and is threaded into every
+  // wave-consuming installer — no installer touches the transport tier. Plain construction, no
+  // Pi registration, order-safe.
+  const reportWave = createReportWave(pi.events);
+
+  const conflictResolver = createConflictResolverEngine({
+    events: pi.events,
+    enginePresent: () => pi.getAllTools().some((tool) => tool.name === "subagent"),
+    readOnly: () => gating.isActive(),
+    authorized: (request) =>
+      request.mode === "pr-rebase"
+        ? submitConflict.authorized(request)
+        : stackConflict.authorized(request),
+    ...options.resolverEngine,
+  });
+  const submitConflict = installSubmitConflictBindings(pi, conflictResolver, () =>
+    gating.isActive(),
+  );
+  const stackConflict = createStackConflictResolver(conflictResolver, () => gating.isActive());
+
+  // The v1 plan installer: perk-owned plan mode (the `/plan` + Ctrl+Alt+P + `--plan` toggle
+  // surface over the read-only gate, plus the plan-authoring context injection — this call
+  // sits at the frozen hooks-ordering slot the mode surface always held), the
+  // `plan_draft`/`plan_save` tools, the `/plan-save` + `/implement-here` commands, and
+  // `plan_review` — perk's UNIVERSAL review door (plannotator-selected → the event-bus bridge;
+  // ANY other selection → the first-party in-TUI editor review). Takes `gating` to toggle plan
+  // mode and to COMPOSE the approval→save seam (auto-save → D1a gate exit) — Invariant 1 holds:
+  // the surfaces compose the gate through the seams, never own it. The injected wave-launch
+  // deps power the plannotator launch chooser (§8.23): the presence probe + the two door open
+  // cores are composed HERE so plan.ts/planReview.ts import nothing from the browser modules
+  // (planReviewBrowser.ts/objectiveReviewBrowser.ts — the value-import cycle break:
+  // planReviewBrowser.ts value-imports the review arms). `draftReviews` is the ONE
+  // per-activation current-review slot + unconfirmed-save latch every review surface shares
+  // (§8.23 "Draft-review guards") — in-memory, nothing persisted.
+  const draftReviews = createDraftReviewSlot(pi);
+
+  // The composed `perk` status handle (charter D2): one slot carrying the objective segment +
+  // the ref-counted browser-wait activity. Created once here (no hidden module state) and
+  // threaded into the objective publisher, the plan installer (the warm plannotator arm) and
+  // the browser doors; the footer reads it back via get/subscribe.
+  const perkStatus = createPerkStatus();
+
+  installPlanBindings(pi, gating, draftReviews, () => runnerChild, perkStatus, {
+    present: () => plannotatorPresent(pi),
+    plan: (ctx, opts) =>
+      openPlanReviewSurface(
+        pi,
+        ctx,
+        gating,
+        opts,
+        draftReviewWave,
+        annotations,
+        draftReviews,
+        perkStatus,
+      ),
+    objective: (ctx, opts) =>
+      openObjectiveReviewSurface(
+        pi,
+        ctx,
+        gating,
+        opts,
+        draftReviewWave,
+        annotations,
+        draftReviews,
+        perkStatus,
+      ),
+  });
 
   // The first 3rd-party plan adapter: a perk-owned, injection-only bridge that re-enables
   // `@tombell/pi-plan` as a real plan provider. Always registered, but INERT unless
   // `[providers] plan = "tombell-plan"`; it directs the foreign free-form prose `/plan` surface into
   // perk's canonical `plan_save` → `cache.plan-ref` contract. It needs no `gating` (Invariant 1: the
   // read-only gate stays perk's, engaged by the cold-door launch — the shim never arbitrates tools).
-  registerPlanAdapterTombell(pi);
+  installTombellPlanAdapter(pi, () => runnerChild);
 
   // The second 3rd-party plan adapter — AUGMENT posture: `@plannotator/pi-extension` contributes
-  // its browser plan-review UI while perk's plan surface + gate stay (planMode skips only
-  // `--plan`/`Ctrl+Alt+P` under this selection). Always registered, but INERT unless
-  // `[providers] plan = "plannotator-plan"`. Injection-only — the `plan_review`
-  // tool moved to planReview.ts (below), which dispatches to this adapter's event-bus bridge
-  // when plannotator is selected.
-  registerPlanAdapterPlannotator(pi);
-
-  // `plan_review`, perk's UNIVERSAL review door: plannotator-selected → the event-bus
-  // bridge; ANY other selection → the first-party in-TUI editor review. It takes `gating` only to
-  // COMPOSE the approvalSave seam on an APPROVED review (auto-save → D1a gate exit) — Invariant 1
-  // holds: the door composes the gate through the seam, never owns it. The injected wave-launch
-  // deps power the plannotator launch chooser (§8.23): the presence probe + the two door open
-  // cores are composed HERE so planReview.ts imports nothing from door modules (the value-import
-  // cycle break — planReviewBrowser.ts already value-imports planReview.ts).
-  registerPlanReview(pi, gating, {
-    present: () => plannotatorPresent(pi),
-    plan: (ctx, opts) => openPlanReviewSurface(pi, ctx, gating, opts),
-    objective: (ctx, opts) => openObjectiveReviewSurface(pi, ctx, gating, opts),
-  });
-
-  // Objective-author context injection (the objective mirror of plan mode's authoring
-  // half). Keyed off (read-only gate AND stage === objective-author); planMode defers to it.
-  registerObjectiveAuthor(pi, gating);
-
-  // Gist-author context injection (the gist mirror). Keyed off (read-only gate AND
-  // stage === gist-author); planMode defers to it too.
-  registerGistAuthor(pi, gating);
+  // its browser plan-review UI while perk's plan surface + gate stay (the plan installer skips
+  // only `--plan`/`Ctrl+Alt+P` under this selection). Always registered, but INERT unless
+  // `[providers] plan = "plannotator-plan"`. Injection-only — the `plan_review` tool lives in
+  // the plan installer (above), which dispatches to this adapter's event-bus bridge when
+  // plannotator is selected.
+  installPlannotatorPlanAdapter(pi, () => runnerChild);
+
+  // The v1 objective-authoring installer: the objective-author context hook pair (this call
+  // sits at the frozen hooks-ordering slot the injection always held — keyed off (read-only
+  // gate AND stage === objective-author); planMode defers to it), plus the
+  // `objective_draft`/`objective_save` tools and the `/objective-save` command (registration is
+  // name-keyed — only the hooks ordering is frozen).
+  installObjectiveAuthoringBindings(pi, gating, draftReviews, () => runnerChild);
+
+  // The v1 gist installer: the gist-authoring context hook pair (this call sits at the frozen
+  // hooks-ordering slot the injection always held; planMode defers to it too), plus the
+  // `gist_draft`/`gist_save` tools and the `/gist-save` command (registration is name-keyed —
+  // only the hooks ordering is frozen).
+  installGistBindings(pi, gating, draftReviews, () => runnerChild);
+
+  // The v1 objective-refinement installer (contracts.md §8.67/§8.68): the refinement context hook
+  // pair (keyed off (read-only gate AND stage === objective-refine); plan mode and the provider
+  // adapters defer to it), the ONE model-facing `objective_refinement_draft` tool, the warm
+  // `/objective-refine` entry and the human `/objective-refinement-save` failsafe. Registered
+  // before the tool snapshots.
+  installObjectiveRefinementBindings(pi, gating, draftReviews, () => runnerChild);
   let sharedOk = false;
   try {
     sharedDir();
@@ -206,11 +331,6 @@ export default function (pi: ExtensionAPI) {
   }
   const registryOk = registryStages > 0;
 
-  // The single-value `perk` status handle (charter D2): one slot carrying the objective
-  // segment. Created once here (no hidden module state) and threaded into the objective
-  // publisher below; the footer reads it back via get/subscribe.
-  const perkStatus = createPerkStatus();
-
   // The generic full report-detail entry and the `perk:workflow-state` transition marker. Renderer
   // bodies live in surfaces.ts; registration is wiring through the pre-0.80.4-safe seam. The report
   // family is appended by command-attached sinks; one workflow registration covers every appender.
@@ -221,13 +341,23 @@ export default function (pi: ExtensionAPI) {
   // globals). Synced from session_start/session_tree below; closed on session_shutdown so the
   // consumer lease releases with the session. A stale /reload predecessor instance is retired
   // by the lease fencing (fresh token per same-identity reacquire + verify-before-inject).
-  const feedbackReceiver = createHunkFeedbackReceiver(pi);
-  pi.on("session_shutdown", async () => {
+  const feedbackReceiver = (options.feedbackReceiverFactory ?? createHunkFeedbackReceiver)(pi);
+  pi.on("session_shutdown", async (_event, ctx) => {
+    submitConflict.shutdown();
+    stackConflict.shutdown();
+    await conflictResolver.shutdown();
     feedbackReceiver.close();
+    // A browser-wait activity cannot outlive the session.
+    perkStatus.clearActivity(ctx);
   });
 
   pi.on("session_start", async (_event, ctx) => {
-    const branchEntries = () => branchOf(ctx);
+    // Read the two native-child booleans and latch the floor before lifecycle work or tool rebuilds.
+    runnerChild = isRunnerChild(process.env);
+    readOnlyFloor ||= decodeReadOnlyFloor(runnerChild, process.env.PI_SUBAGENT_EXTENSION_BINDINGS);
+
+    submitConflict.setContext(ctx);
+    stackConflict.setContext(ctx);
     const sessionFile = ctx.sessionManager.getSessionFile();
     const currentSessionId = sessionFile ? basename(sessionFile) : null;
 
@@ -237,209 +367,108 @@ export default function (pi: ExtensionAPI) {
       report(ctx, "workflow-state linkage error", "error", message, { alsoLog: true });
     };
 
-    const decision = decideClaim({
-      state: rebuildWorkflowState(branchEntries()),
-      currentSessionId,
-      envRunId: process.env.PERK_RUN_ID ?? null,
-      cwd: ctx.cwd,
-    });
-
-    // The session-audit exact-vintage stamp (§8.3), recorded by every run-identity arm below
+    // The session-audit exact-vintage stamp (§8.3), recorded by every run-identity arm
     // (claim/fork/adopt/mint); undefined on the perkVersion() failure sentinel, which drops the
     // key on serialize and leaves the session on the timestamp-estimate arm.
     const stamp = versionStamp(version);
 
-    // `claim`/`adopt` carry no prior branch state (adopt's is written by its arm below).
-    let resolved: WorkflowState =
-      decision.action === "claim" || decision.action === "adopt" ? {} : decision.state;
-    let minted = false;
-
-    if (decision.action === "claim") {
-      // Cold claim — establish before consume (strict).
-      const handoff = readHandoff(ctx.cwd, decision.runId);
-      if (handoff === null || handoff.run_id !== decision.runId) {
-        reportError(`handoff missing or mismatched for run ${decision.runId}`);
-      } else {
-        const data: WorkflowState = {
-          run_id: decision.runId,
-          pi_session_id: currentSessionId ?? undefined,
-          mode: handoff.mode,
-          perk_version: stamp,
-          // Record the launched stage so the interior can tell e.g. objective-author from plan
-          // (both are read-only) and inject the right authoring context (planMode vs objectiveAuthor).
-          stage: handoff.stage,
-        };
-        const okAppend = appendWorkflowState(pi, ctx, {
-          data,
-          field: "run_id",
-          expected: decision.runId,
-          scope: "workflow-state linkage error",
-          failure: `read-back failed for run ${decision.runId}`,
-        });
-        if (!okAppend) {
-          // do NOT consume
-        } else {
-          markHandoffConsumed(ctx.cwd, decision.runId, {
-            piSessionId: currentSessionId ?? undefined,
-          });
-          resolved = data;
-        }
-      }
-    } else if (decision.action === "fork") {
-      // Inherited a run_id from a different session file → isolate the child's scratch. A static
-      // redirect or filesystem failure is loud but does not prevent the derived workflow identity
-      // from settling; later eligible turns retry through the agent-scratch resolver.
-      try {
-        ensureRunScratch(ctx.cwd, decision.childRunId);
-      } catch (error) {
-        report(
-          ctx,
-          "run scratch",
-          "warning",
-          `could not create fork run root for ${decision.childRunId}: ${String(error)}`,
-          { alsoLog: true },
-        );
-      }
-      const data: WorkflowState = {
-        run_id: decision.childRunId,
-        pi_session_id: currentSessionId ?? undefined,
-        predecessor: decision.parentRunId,
-        mode: decision.state.mode,
-        perk_version: stamp,
-      };
-      pi.appendEntry(WORKFLOW_STATE_TYPE, data);
-      resolved = data;
-    } else if (decision.action === "adopt") {
-      // An env-inherited run id whose handoff was already consumed by a different session: a
-      // spawned child (contracts §8.2). Mirror the fork arm — derived child identity, isolated
-      // scratch, inherited mode (read-only gating survives) — minus everything that belongs to
-      // the launched session: never re-consume the handoff (its pi_session_id keeps the true
-      // claimer), no `stage` (no stage impersonation / stage-binding injection), and no
-      // implementation/main pointer capture (resolveRunStage stays null for adopt).
-      try {
-        ensureRunScratch(ctx.cwd, decision.childRunId);
-      } catch (error) {
+    // The identity lifecycle (claim / fork / adopt / mint / keep) is the named session
+    // operation (session/lifecycle.ts owns the arms); this handler binds the production ports
+    // and renders the outcome's per-arm problems/warnings with the exact report scopes the
+    // arms always used. The strict appends keep reporting read-back failures through the
+    // strict-append seam's own loudness channel. The same cwd-bound handoff reader serves the
+    // post-gate facts below (ONE handoff authority).
+    const identityPorts = {
+      readHandoff: (runId: string) => readHandoff(ctx.cwd, runId),
+      listRunIds: () => listRunIds(ctx.cwd),
+      markHandoffConsumed: (runId: string, opts: { piSessionId?: string }) =>
+        markHandoffConsumed(ctx.cwd, runId, opts),
+      ensureRunScratch: (runId: string) => {
+        ensureRunScratch(ctx.cwd, runId);
+      },
+      mintRunId,
+      versionStamp: stamp,
+    };
+    const stateStore = branchSessionStateStore(pi, ctx);
+    let identity = establishSessionIdentity(stateStore, identityPorts, {
+      currentSessionId,
+      envRunId: process.env.PERK_RUN_ID ?? null,
+    });
+    if (readOnlyFloor) {
+      const reflected = reflectSessionReadOnlyFloor(stateStore, identity);
+      identity = reflected.outcome;
+      if (reflected.unexpectedFailure) {
         report(
           ctx,
-          "run scratch",
-          "warning",
-          `could not create adopted run root for ${decision.childRunId}: ${String(error)}`,
+          "child restriction",
+          "error",
+          "could not persist child read-only restriction; in-memory restriction remains active",
           { alsoLog: true },
         );
       }
-      const data: WorkflowState = {
-        run_id: decision.childRunId,
-        pi_session_id: currentSessionId ?? undefined,
-        predecessor: decision.parentRunId,
-        mode: decision.mode,
-        perk_version: stamp,
-      };
-      pi.appendEntry(WORKFLOW_STATE_TYPE, data);
-      resolved = data;
-    } else if (decision.action === "none") {
-      // A warm session with no identity mints its own run_id so
-      // per-run state (the session data dir) can key off it. No disk artifacts —
-      // dirs are the accessor's job; provenance is recorded separately. A failed cold claim above never
-      // falls here (claim stays a loud unclaimed error).
-      const runId = mintRunId();
-      const data: WorkflowState = {
-        run_id: runId,
-        pi_session_id: currentSessionId ?? undefined,
-        perk_version: stamp,
-      };
-      const okAppend = appendWorkflowState(pi, ctx, {
-        data,
-        field: "run_id",
-        expected: runId,
-        scope: "workflow-state linkage error",
-        failure: `read-back failed for minted run ${runId}`,
-      });
-      if (okAppend) {
-        resolved = { ...decision.state, ...data };
-        minted = true;
-      }
     }
-
-    // Reapply the read-only allowlist + stage scoping from the resolved mode/stage — FIRST,
-    // before the plan-ref/stage reconciliation below. `resolved.mode` is final once the
-    // claim/fork/none arms settle (the later blocks only touch `active_plan_ref` / capture
-    // pointers), and ordering the sync ahead of them guarantees no cache read or reconciliation
-    // failure can leave the gate unsynced (defense in depth on top of the total cache readers).
-    // The scope stage is the workflow-state `stage` key (§8.40): claim → the handoff-recorded
-    // stage just appended; keep/none → the branch-LWW stage; fork INHERITS the parent's stage (a
-    // forked implement session is an implement session); adopt NEVER impersonates (subagent
-    // children stay unscoped — their fresh branch carries no stage, so session_tree agrees). A
-    // failed claim leaves `resolved` empty → no stage → unscoped (stage scoping is fail-open).
-    // Fail-closed on the gate: if the sync throws, leave it as-is (a failed sync never opens it).
-    const scopeStage =
-      decision.action === "adopt"
-        ? undefined
-        : (resolved.stage ?? (decision.action === "fork" ? decision.state.stage : undefined));
+    for (const problem of identity.problems) reportError(problem);
+    for (const warning of identity.warnings) {
+      report(ctx, "run scratch", "warning", warning, { alsoLog: true });
+    }
+    const decision = identity.decision;
+    const minted = identity.arm === "minted";
+
+    // PHASE 1 — reapply the read-only allowlist + stage scoping from the established identity
+    // FIRST, before the fallible post-gate facts below. The scope derivation is pure (no store,
+    // handoff, registry, or checkout read), so no read failure can leave the gate unsynced
+    // (defense in depth on top of the total cache readers); `resolved.mode` is final once the
+    // arms settle. Fail-closed on the gate: if the sync throws, leave it as-is (a failed sync
+    // never opens it).
+    const toolScope = sessionStartToolScope(identity);
     try {
-      gating.syncFromState(resolved.mode, scopeStage);
+      gating.syncFromState(toolScope.mode, toolScope.stage);
     } catch (error) {
       console.error(`perk: tool-gating sync failed on session_start — ${error}`);
     }
 
-    // Plan-ref linkage (stage-gated): reconcile the cache.plan-ref file into
-    // active_plan_ref — but ONLY when the launched stage *consumes* the ref (its registry
-    // `requires`/`reads` list `cache.plan-ref`). That is the worktree binding stages
-    // (implement/submit/address/land/learn); the root `worktree: none` stages
-    // (plan/objective-plan/save) must NOT inherit the root *selector* into a fresh planning
-    // session. Idempotent by (provider, pr_id), strict read-back, headless-safe. Runs after the
-    // run_id claim so the run is settled first; the two append independent LWW fields.
-    // Reload/fork/tree (no launched stage) rely on the LWW rebuild — never re-read the file.
-    const linked = rebuildWorkflowState(branchEntries()).active_plan_ref ?? null;
-    const runStage = resolveRunStage(decision, ctx.cwd);
-    // Registry-missing is permissive when a stage is present, to preserve implement linkage.
-    const consumesPlanRef =
-      runStage !== null && (registry === null || stageConsumesPlanRef(registry, runStage));
-    if (consumesPlanRef) {
-      const cachedRef = readPlanRef(ctx.cwd);
-      if (cachedRef !== null) {
-        if (planRefsEqual(linked, cachedRef)) {
-          resolved = { ...resolved, active_plan_ref: linked };
-        } else {
-          if (
-            appendWorkflowState(pi, ctx, {
-              data: { active_plan_ref: cachedRef },
-              field: "active_plan_ref",
-              expected: cachedRef,
-              scope: "workflow-state linkage error",
-              failure: `plan-ref read-back failed for ${cachedRef.provider}:${cachedRef.pr_id}`,
-              equals: planRefsEqual,
-            })
-          ) {
-            resolved = { ...resolved, active_plan_ref: cachedRef };
-          }
-        }
-      } else if (linked !== null) {
-        resolved = { ...resolved, active_plan_ref: linked };
-      }
-    } else if (linked !== null) {
-      // Non-consuming stage (or no launched stage): preserve any already-linked ref via LWW,
-      // but NEVER read the cache file — the root selector must not leak in.
-      resolved = { ...resolved, active_plan_ref: linked };
+    // The refinement cold claim's ONE-TIME context import (contracts.md §8.67): only on the
+    // actual cold claim of an `objective-refine` handoff (never keep/fork/adopt/mint), after the
+    // identity settled and the gate synced. A refusal is loud and leaves the session gated
+    // without a usable context (no orphan repair, no reimport on reload).
+    if (identity.arm === "claimed" && typeof identity.resolved.run_id === "string") {
+      importRefinementContextOnClaim(pi, ctx, {
+        runId: identity.resolved.run_id,
+        stage: identity.resolved.stage,
+      });
     }
 
+    // PHASE 2 — the post-gate facts (session/lifecycle.ts owns the decision tree): the lazy,
+    // stage-gated `cache.plan-ref` → `active_plan_ref` reconciliation (only a launched stage
+    // that *consumes* the ref reads the checkout; claim/keep read the handoff, fork/adopt/none
+    // never do; one strict verified append, idempotent by (provider, pr_id)), plus the derived
+    // implementation-capture and receiver inputs. Called HERE — after the gate and the
+    // refinement import — never while constructing gate inputs. A throwing branch/handoff read
+    // propagates to Pi's hook error boundary with the gate already synced: unreadability is
+    // never turned into confirmed absence, and no later effect runs from guessed facts.
+    const facts = resolveSessionStartFacts(
+      stateStore,
+      { readHandoff: identityPorts.readHandoff, readPlanRef: () => readPlanRef(ctx.cwd) },
+      { identity, registry, currentSessionId },
+    );
+    const resolved: WorkflowState = facts.resolved;
+
     // Implementation session pointer (contracts.md §8.35): an implement session self-keys its own
     // session file into the shared main checkout so a later/other session resolves it cross-run.
-    // The headless worker's inner session lands here too (.main); driveStage records the matching
+    // The headless worker's inner session lands here too (.main); runStage records the matching
     // .worker. A forked implement session inherits the parent's launched stage + threads the
     // inherited parent session id as fork provenance. Best-effort + non-fatal (carrier warns).
     // First-write-wins (`preserveForeign`): this is the corroborated shadowing defect site — the
     // claimer's original capture stays authoritative, and any future shadow vector warns loudly
     // instead of silently corrupting /learn evidence.
-    const implStage =
-      runStage ?? (decision.action === "fork" ? (decision.state.stage ?? null) : null);
-    if (resolved.run_id && implStage === "implement") {
+    if (facts.implementationCapture !== null) {
       captureSessionPointer({
         cwd: ctx.cwd,
-        runId: resolved.run_id,
+        runId: facts.implementationCapture.runId,
         klass: "implementation",
         site: "main",
         sessionFile,
-        parentSessionId: decision.action === "fork" ? (decision.state.pi_session_id ?? null) : null,
+        parentSessionId: facts.implementationCapture.parentSessionId,
         preserveForeign: true,
       });
     }
@@ -449,14 +478,7 @@ export default function (pi: ExtensionAPI) {
     // outbox. Eligibility (interactive TUI + implement stage + non-adopted + settled identity +
     // plan-ref match against one fresh cache read) is evaluated inside sync; every ineligible
     // shape closes any open inbox. Never throws (the controller contains its own failures).
-    feedbackReceiver.sync(ctx, {
-      stage: implStage,
-      adopted: decision.action === "adopt",
-      runId: resolved.run_id ?? null,
-      piSessionId: currentSessionId,
-      activePlanRef: resolved.active_plan_ref ?? null,
-      mode: ctx.mode ?? null,
-    });
+    feedbackReceiver.sync(ctx, { ...facts.feedback, mode: ctx.mode ?? null });
 
     // Soft version-parity drift signal: pi can lazy-install / load a stale `npm:@mgiles/perk`, so the
     // extension actually running may differ from the `perk` CLI that launched it. The local launch
@@ -521,165 +543,153 @@ export default function (pi: ExtensionAPI) {
 
   // Non-negotiable: rebuild on branch navigation too, or state goes stale after /tree (§8.3).
   pi.on("session_tree", async (_event, ctx) => {
+    stackConflict.setContext(ctx);
+    // ONE fresh full-branch rebuild; the navigation facts derive purely from it (no handoff/
+    // checkout read, claim, linkage, or capture on navigation — session/lifecycle.ts owns the
+    // asymmetry with startup).
     const state = rebuildWorkflowState(branchOf(ctx));
+    const facts = sessionTreeFacts(state);
     // Non-negotiable: re-sync the gate + stage scoping on tree navigation too (mode and stage are
     // per-field LWW — the branch-rebuilt stage is the §8.40 key). Fail-closed on the gate.
     try {
-      gating.syncFromState(state.mode, state.stage);
+      gating.syncFromState(facts.toolScope.mode, facts.toolScope.stage);
     } catch (error) {
       console.error(`perk: tool-gating sync failed on session_tree — ${error}`);
     }
-    // Re-sync the feedback receiver from the LWW-rebuilt state (§8.58). `adopted: false` is
-    // right here: an env-adopted child's fresh branch carries no stage, so the stage gate
-    // alone keeps it inert on tree navigation.
-    feedbackReceiver.sync(ctx, {
-      stage: state.stage ?? null,
-      adopted: false,
-      runId: state.run_id ?? null,
-      piSessionId: state.pi_session_id ?? null,
-      activePlanRef: state.active_plan_ref ?? null,
-      mode: ctx.mode ?? null,
-    });
+    // Re-sync the feedback receiver from the LWW-rebuilt state (§8.58) — gate first, then
+    // receiver; `adopted: false` is right here: an env-adopted child's fresh branch carries no
+    // stage, so the stage gate alone keeps it inert on tree navigation.
+    feedbackReceiver.sync(ctx, { ...facts.feedback, mode: ctx.mode ?? null });
     if (process.env.PERK_SELFCHECK) {
       writeT3Sentinel(ctx.cwd, "tree", state, ctx.mode ?? null);
     }
   });
 
-  // Warm door: the `plan_save` tool + `/plan-save` command. Takes `gating`:
-  // a successful command-path save exits read-only mode (the read-only → read-write boundary).
-  registerPlanSave(pi, gating);
-
-  // The `/implement-here` command: the human-only no-save exit from plan mode (§8.23) —
-  // implement the reviewed draft in-session, no issue created. Composes the gate through the
-  // implementHereExit seam; no model tool is registered (machine-unreachable by construction).
-  registerImplementHere(pi, gating);
-
-  // The `plan_draft` working-draft file tool. Registered in the factory so it
-  // exists before the gate snapshots tools; its name is in READ_ONLY_TOOLS (the structural
-  // session-data carve-out), so it survives plan mode.
-  registerPlanDraft(pi);
-
-  // The `objective_draft` working-objective file tool (the plan_draft twin).
-  registerObjectiveDraft(pi);
-
-  // The `gist_draft` working-gist file tool (the third draft carve-out).
-  registerGistDraft(pi);
-
   // Lifecycle gates: the dirty-repo switch/fork guard + the guard-only `/implement`.
   registerLifecycleGates(pi);
 
   // Warm door: the `submit` tool + `/submit` command.
-  registerSubmit(pi);
-
-  // The warm `ready` door: the deliberate draft→ready review gate (submit keeps draft).
-  registerReady(pi);
-
-  // Warm doors: `land` merges + sets pending-learn; `learn` clears it (TS-only).
-  registerLand(pi);
-  registerLearn(pi);
-
-  // The warm stacked-delivery surface (§8.51): `/objective-stack` (read) +
-  // `/objective-sync`/`/objective-recover` (drives) + the four typed stack tools. Takes
-  // `gating` for the driving commands' gate-on soft refusal (stack sync/recovery mutates
-  // published branches; the stack tools never join READ_ONLY_TOOLS).
-  registerObjectiveStack(pi, gating);
+  installSubmitBindings(pi, submitConflict);
+
+  // The warm ready + handoff bindings: the deliberate draft→ready review gate (submit keeps
+  // draft). Takes `gating`: the warm ready→reconcile continuation refuses (loudly) to drive
+  // the ready-time pass into a read-only session (contracts.md §8.66).
+  installReadyBindings(pi, gating);
+
+  // Warm bindings: `land` merges + sets pending-learn; the v1 learn installer (the `learn` +
+  // `run_learn_wave` tools and the `/learn` command over the `learning/` feature ops) clears it.
+  installLandBindings(pi);
+  installLearnBindings(pi, reportWave);
+
+  // The warm stacked-delivery mutating surface (§8.51): the `/objective-sync`/
+  // `/objective-recover`/`/objective-land` drives + the four typed stack tools over the
+  // `delivery/stackConflict.ts` + `delivery/stackReconcile.ts` feature ops. Takes `gating` for
+  // the driving commands' gate-on soft refusal (stack sync/recovery mutates published
+  // branches; the stack tools never join READ_ONLY_TOOLS).
+  installStackSyncBindings(pi, gating, stackConflict, options.stackResolutionDelivery);
+  installStackRecoverBindings(pi, gating);
+  installStackLandBindings(pi, gating);
+
+  // The stacked-delivery status read: the `objective_stack_status` tool + the `/objective-stack`
+  // command (read-only end to end — the command works gate-on; the tool stays gate-off).
+  installStackStatusBindings(pi);
 
   // The warm `/address` review loop: the submit-then-resolve `finalize_address` tool + `/address`
   // command. Classify-then-act (the verbose feedback fetch + classification runs in an isolated
   // spawned child; the parent fixes actionable items and finalizes the committed repairs).
-  registerAddress(pi);
+  installAddressBindings(pi, reportWave, submitConflict);
 
   // The warm `/pr-review` door: automated code review in a FRESH, isolated subagent that
   // POSTS its review to the PR (the deliberate departure from /address's read-only-child rule).
-  registerPrReview(pi);
-
-  // The EXPERIMENTAL warm `/pr-review-dynamic` door: the selector-driven sibling — angle
-  // selection delegated to a fresh perk.review-angle-selector lane, normalized in
-  // module-rendered code; posting shares /pr-review's post_pr_review + clean guard. The
-  // baseline /pr-review stays canonical; promotion/retire is a later dogfood's call.
-  registerPrReviewDynamic(pi);
+  installAutomatedReviewBindings(pi, reportWave);
 
   // The warm `submit_pr_review` tool: the human-gated curated-posting surface both review
   // doors ride (contracts §8.4) — neither door registers tools of its own.
-  registerSubmitPrReview(pi);
+  installCuratedSubmissionBindings(pi);
 
   // The flow-scoped review-wave pair (`start_review_wave`/`collect_review_wave`) both human
   // review doors drive: non-blocking adversarial-review launch + the typed collect, flow-scoped
   // via the session's pending-wave guard.
-  registerReviewWaveTools(pi);
-  registerAuditWave(pi);
-  registerHarvestWave(pi);
-  registerDreamWave(pi);
+  installReviewWaveBindings(pi, reportWave);
+  installAuditBindings(pi, reportWave);
+  installHarvestBindings(pi, reportWave);
+  installDreamBindings(pi, reportWave);
+
+  // The scout launcher (`run_scout_wave`, contracts.md §8.70): the authoring sessions' blocking
+  // fan-out of self-contained read-only briefs onto fresh `perk.scout` lanes — one attempt,
+  // no retry, reachable in every gated stage except refinement.
+  installScoutWaveBindings(pi, reportWave);
 
   // The flow-scoped draft-review-wave pair (`start_draft_review_wave`/
   // `collect_draft_review_wave`) the draft-review door drives: non-blocking draft-review
   // launch over the door-primed context + the typed collect.
-  registerDraftReviewWaveTools(pi);
+  registerDraftReviewWaveTools(pi, draftReviewWave, reportWave);
 
   // The door-primed browser annotation tool (`push_annotations`): the browser door primes the
   // surface handle on open and clears it on settle/degrade — the tool refuses outside a
   // door-opened flow.
-  registerAnnotationPushTool(pi);
+  installAnnotationBindings(pi, annotations);
 
   // The warm `/pr-review-terminal` door: the terminal review entry — hunk always, no provider
   // dispatch (the command IS the selection); posting rides `submit_pr_review` above.
-  registerPrReviewTerminal(pi);
+  installPrReviewTerminalBindings(pi);
 
   // The warm `/pr-review-browser` door: the browser review entry — plannotator always, opened
   // in the background (pre-PR it absorbs the since-base local browser review); posting is the
   // human's own platform-post from the UI, with `submit_pr_review` for request-changes only.
-  registerPrReviewBrowser(pi);
+  installPrReviewBrowserBindings(pi, annotations, perkStatus);
+
+  // The warm `/stack-review-browser` door + its cold-launch twin (`open_stack_review`): the
+  // stacked-PR browser review over the combined base→top diff — one reviewer wave with
+  // `stack: true`, then judgment-routed per-PR posting through `submit_pr_review`.
+  installStackReviewBindings(pi, annotations, perkStatus);
 
   // The warm `/plan-review-browser` door: the summonable streaming draft review — the
   // plannotator plan-review browser on the working plan draft, draft reviewers streaming
   // phrase-anchored findings in; APPROVE auto-saves via the approvalSave seam, DENY returns a
   // model-mediated revision round.
-  registerPlanReviewBrowser(pi, gating);
+  registerPlanReviewBrowser(pi, gating, draftReviewWave, annotations, draftReviews, perkStatus);
 
   // The warm `/objective-review-browser` door: the summonable streaming objective-draft review
   // — the plannotator plan-review browser on the RENDERED working objective draft, draft
   // reviewers streaming phrase-anchored findings in; APPROVE auto-saves via the
   // objectiveApprovalSave seam, Direct Edits = a model-mediated revise round (never auto-saved).
-  registerObjectiveReviewBrowser(pi, gating);
+  registerObjectiveReviewBrowser(
+    pi,
+    gating,
+    draftReviewWave,
+    annotations,
+    draftReviews,
+    perkStatus,
+  );
 
   // The read-only CI executor: the `run_ci` tool + `/ci` command + `--allow-project-ci`
   // flag. Runs the project's `[ci]` named checks deterministically and reports (never fixes/loops).
-  registerCiExecutor(pi);
+  installCiBindings(pi);
 
   // The objective substrate: `/objective` set/clear, budget accounting, threshold
   // compaction, all keyed off the now-live `active_objective`. Inert when no objective is active.
   // (The deterministic objective mechanics live in the Python plane: `perk objective …`.)
-  registerObjective(pi, perkStatus);
+  installObjectiveBindings(pi, perkStatus);
 
   // The warm `/commit-and-compact` utility door: drive a commit of the work so far, compact once
   // a successful outcome is known, then completion-gate an automatic evidence-first continuation
   // (clean/read-only trees compact immediately; no commit → no compaction or continuation).
   // Human-only — no tool twin.
-  registerCommitAndCompact(pi, gating);
-
-  // The warm `objective_save` door: the `objective_save` tool + `/objective-save` command
-  // (the objective mirror of plan-save). Takes `gating` for the read-only → read-write boundary.
-  registerObjectiveSave(pi, gating);
-
-  // The warm `gist_save` door: the `gist_save` tool + `/gist-save` command (the gist mirror).
-  registerGistSave(pi, gating);
+  installCommitCompactBindings(pi, gating);
 
   // The objective plan factory's warm transition surface: the `objective_node` bounded
   // tool (delegates to the Python cold door; `status:"done"` requires a completion audit) + the
   // `/objective-plan` command (select the next node and author a bounded plan). The command now
   // enters the read-only gate on invocation (parity with the cold door's `mode: read-only`
   // handoff; exit stays with plan_save / `/plan` off) — hence `gating`.
-  registerObjectivePlan(pi, gating);
-
-  // The learned-docs plan factory's warm surface: the `/learn-docs` command gathers open
-  // perk:learn issues into an inbox (via the `perk learn docs --gather` cold door) and injects the
-  // factory guidance so the model authors a docs/learned consolidation plan (no model tool).
-  registerLearnFactoryDoor(pi, DOCS_DOOR);
+  installObjectivePlanningBindings(pi, gating, reportWave);
 
-  // The learn-code plan factory's warm surface: the `/learn-code` command gathers pre-stamped
-  // SHOULD_BE_CODE perk:learn issues into an inbox (via the `perk learn code --gather` cold door)
-  // and injects the factory guidance so the model authors a code-routing plan (no model tool).
-  registerLearnFactoryDoor(pi, CODE_DOOR);
+  // The two learn plan factories' warm surfaces: `/learn-docs` gathers open perk:learn issues
+  // (via the `perk learn docs --gather` cold door) toward a docs/learned consolidation plan;
+  // `/learn-code` gathers pre-stamped SHOULD_BE_CODE issues (via `perk learn code --gather`)
+  // toward a code-routing plan. Guidance-injection only (no model tool).
+  installLearnFactoryBindings(pi);
 
   // Warm-door skill-binding delivery: Mechanism A's `before_agent_start` injection of
   // the launched stage's user-originated bindings (+ the stale-context strip). Mechanism B (the