@mgiles/perk 1.0.1 → 1.1.0

package/README.md

@@ -1,17 +1,16 @@
 # perk
 
-A Pi-native, plan-oriented engineering workflow — a Python `perk` CLI (the session
+A Pi-native, plan-oriented engineering workflow: a Python `perk` CLI (the session
 *exterior*) plus a TypeScript Pi extension (the session *interior*).
 
-> Start at [`docs/user-docs/`](docs/user-docs/index.md).
+> Inspired by `erk`, formely maintained by the team at [dagster](https://github.com/dagster-io/dagster)
 
-> Originally based on prior art `erk`, by the team at [dagster](https://github.com/dagster-io/dagster)
+perk was built with perk.
 
 ## What perk is
 
-perk implements a plan-oriented engineering workflow (explore read-only → save a plan →
-implement on a branch → submit → land → learn) to [Pi](https://github.com/earendil-works),
-split across **two planes**:
+perk implements a plan-oriented engineering workflow (plan → implement → submit → review →
+address → land → learn) for [Pi](https://github.com/earendil-works), split across **two planes**:
 
 - the **exterior** — a Python `perk` CLI that scaffolds repos, positions worktrees, mints
   run ids, and launches primed `pi` sessions (everything that happens *outside* a session);
@@ -19,10 +18,7 @@ split across **two planes**:
   *inside* a running session.
 
 A language-neutral [`shared/`](shared/) contract (the stage registry + cross-plane specs)
-is the single source both planes read, so the two stay in lockstep without a codegen step.
-
-perk is built to **bootstrap its own development**: each phase leaves perk capable of
-driving the next, and perk's own repo is the first thing it scaffolds.
+is the single source both planes read, hopefully staying in lockstep without codegen.
 
 ## Quickstart
 
@@ -42,8 +38,7 @@ For the guided first run, follow
 
 ## Documentation
 
-The operator-facing docs live under [`docs/user-docs/`](docs/user-docs/index.md), organized as
-the four [Divio](https://docs.divio.com/documentation-system/) quadrants:
+The operator-facing docs live under [`docs/user-docs/`](docs/user-docs/index.md), organized as:
 
 - **[Tutorials](docs/user-docs/tutorials/index.md)** — learning-oriented lessons; start with
   [Get started with perk](docs/user-docs/tutorials/get-started.md).
@@ -86,15 +81,6 @@ just test         # pytest + node:test (the regression gate)
 just ci           # setup + lint + typecheck + test
 ```
 
-After `just setup` (or `just install-cli`), call `perk` directly — no `uv run`. The install is
-**editable**, so a `git pull` reflects Python changes live; re-run `just install-cli` after a
-dependency change. It lands in uv's tool bin (`~/.local/bin`) — if `perk` isn't found, that dir
-is not on your `PATH`; run `uv tool update-shell` (then restart your shell). Remove it with
-`uv tool uninstall perk`.
-
-Releasing perk → see [docs/releasing.md](docs/releasing.md) (version SSOT, dual-plane runbook,
-the `validate-release-versions` tag gate).
-
 `just setup` also runs `just hooks` (`prek install`), wiring a [prek](https://prek.j178.dev)
 pre-commit hook that runs `ruff check` on staged Python (config in `prek.toml`; the ruff
 env is built by prek from the remote ruff-pre-commit repo, so it never depends on a

package/extension/checkpoints/checkpoints.ts

@@ -29,6 +29,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import { readHandoff, readPlanBody } from "../substrate/cache.ts";
+import { registerPerkCommand } from "../substrate/command.ts";
 import { loadPerkConfig } from "../substrate/config.ts";
 import {
   loadProviders,
@@ -516,7 +517,7 @@ export function registerCheckpoints(pi: ExtensionAPI, status: PerkStatusHandle):
     }
   });
 
-  pi.registerCommand("checkpoints", {
+  registerPerkCommand(pi, "checkpoints", {
     description: "Show perk implementation checkpoints (read-only).",
     handler: async (_args, ctx) => {
       // Todo-provider deferral: announce the deferral headless-safe and step aside when a

package/extension/doors/address.ts

@@ -20,6 +20,7 @@ import {
   runColdDoor,
   stringField,
 } from "../substrate/coldDoor.ts";
+import { registerPerkCommand } from "../substrate/command.ts";
 import { loadPerkConfig } from "../substrate/config.ts";
 import { render } from "../substrate/prompts.ts";
 import { failFor, ok, type Result } from "../substrate/result.ts";
@@ -324,7 +325,7 @@ export function registerAddress(pi: ExtensionAPI): void {
     },
   });
 
-  pi.registerCommand("address", {
+  registerPerkCommand(pi, "address", {
     description:
       "Classify PR review feedback (isolated child) and resolve threads (submit → address). " +
       "Pass --preview to classify only (take no action).",

package/extension/doors/ciExecutor.ts

@@ -29,6 +29,7 @@ import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { ensureRunScratch, scratchDir } from "../substrate/cache.ts";
+import { registerPerkCommand } from "../substrate/command.ts";
 import { type CiCheck, loadPerkConfig } from "../substrate/config.ts";
 import { paramsOf, stringParam } from "../substrate/toolParams.ts";
 import { branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
@@ -367,7 +368,7 @@ export function renderCiProse(report: CiReport): string {
     );
   }
   if (report.error_type === "no_checks_configured") {
-    return "No CI checks configured ([[ci]] in .pi/perk.toml is empty). Nothing to run.";
+    return "No CI checks configured ([[ci]] in .perk/config.toml is empty). Nothing to run.";
   }
   if (report.error_type === "unknown_check") {
     return `perk CI: ${report.error}`;
@@ -565,7 +566,7 @@ export function registerCiExecutor(pi: ExtensionAPI): void {
     },
   });
 
-  pi.registerCommand("ci", {
+  registerPerkCommand(pi, "ci", {
     description: "Run the project's configured CI checks and report results (never auto-fixes).",
     handler: async (args, ctx) => {
       const check = args.trim() === "" ? undefined : args.trim();

package/extension/doors/land.ts

@@ -15,6 +15,7 @@ import {
   runColdDoor,
   stringField,
 } from "../substrate/coldDoor.ts";
+import { registerPerkCommand } from "../substrate/command.ts";
 import { failFor, ok, type Result } from "../substrate/result.ts";
 import { report } from "../surfaces/report.ts";
 
@@ -208,7 +209,7 @@ export function registerLand(pi: ExtensionAPI): void {
     },
   });
 
-  pi.registerCommand("land", {
+  registerPerkCommand(pi, "land", {
     description: "Merge the active plan's PR and set pending-learn (submit → land).",
     handler: async (_args, ctx) => {
       const result = await landPr(pi, ctx);

package/extension/doors/learn.ts

@@ -1,13 +1,34 @@
-// The deepened warm `/learn` door. Graduates the thin marker-clear into a real knowledge-capture
-// pass: when a `summary` is given, DELEGATE to `perk learn capture --json` via the shared cold-door
-// client (`runColdDoor` — the body rides the run-scratch stdin channel; GitHub writes canonical in
-// Python), which creates a `perk:learn` issue + clears
-// `pending-learn`; then mirror the marker-clear in-session (idempotent). With no `summary`, stay
-// the thin TS-only marker-clear (graceful — no empty issue). Never throws (soft `details.ok`);
-// the capture decode is fully LENIENT — a `success: true` envelope always yields the captured-ok
-// terminating result even when `learn_issue` is undecodable (render-only field; see
-// `decodeLearnCapture`).
+// The warm `/learn` door — a multi-angle knowledge-capture orchestrator (mirrors `/pr-review`).
+//
+// Bare interactive `/learn` gathers a reproducible evidence bundle ONCE via the cold door
+// (`perk learn evidence --render --json`; the parent owns the gather per §8.35), then branches:
+// a learn-docs plan short-circuits to a deterministic marker-clear no-op; a gather failure (or a
+// bundle-less success) degrades to the simple `learnGuidance` injection (/learn is never a dead
+// end); otherwise it injects the orchestration seed (`learnOrchestrateGuidance`) so the model spawns
+// 2–4 fresh-context `perk.learn-analyst` children, reconciles their reports into ONE classified
+// decision, and captures (via the `learn` tool, with the routable `decision`/`target` persisted on
+// the issue header — both backends) or skips.
+//
+// The `learn` tool is the capture half: with a `summary`, DELEGATE to `perk learn capture --json`
+// via the shared cold-door client (`runColdDoor` — the body rides the run-scratch stdin channel,
+// the `decision`/`target` classification rides flags; canonical write in Python), creating a
+// `perk:learn` issue + clearing `pending-learn`, then mirror the marker-clear in-session
+// (idempotent). With no `summary`, DELEGATE to `perk learn skip --json` (contracts.md §8.36) —
+// the deliberate skip is recorded canonically on the plan-header (`learn_state: skipped`, unless
+// already `captured`), never a TS-only marker-clear.
+// Never throws (soft `details.ok`); both decodes are fully LENIENT — a `success: true`
+// envelope always yields the terminating ok result even when the payload is undecodable
+// (render-only fields; see `decodeLearnCapture` / `decodeLearnSkip`).
+//
+// Headless bare `/learn` stays the safe no-summary path (cannot drive a turn / spawn children).
+// `/learn <text>` / `/learn skip` stay the existing verbatim-capture / skip-recording paths
+// (decision-less escape hatches). Cold `perk learn` launch stays the simple investigate+capture.
+//
+// The analyst model is configurable via `[subagents] learn-analyst` in `.perk/config.toml`; because
+// `subagents.agentOverrides` does NOT reach project agents, the orchestration seed injects that
+// model as a per-call inline `model` override on every analyst spawn.
 
+import { join } from "node:path";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { bindingSuffix } from "../substrate/bindingDelivery.ts";
 import {
@@ -24,6 +45,8 @@ import {
   runColdDoor,
   stringField,
 } from "../substrate/coldDoor.ts";
+import { registerPerkCommand } from "../substrate/command.ts";
+import { loadPerkConfig } from "../substrate/config.ts";
 import { render } from "../substrate/prompts.ts";
 import { failFor, ok, type Result } from "../substrate/result.ts";
 import { paramsOf, stringParam } from "../substrate/toolParams.ts";
@@ -46,6 +69,61 @@ interface LearnCapturePayload {
   learn_issue?: { id: string; url: string; existed: boolean };
 }
 
+/** The decoded `perk learn skip --json` payload slice (render-only fields). */
+interface LearnSkipPayload {
+  learn_state: string | null;
+  pending_cleared: boolean | null;
+}
+
+/**
+ * Decode the `perk learn skip --json` success payload — fully LENIENT (mirrors `decodeEvidence`):
+ * it **never returns null**, so any success envelope yields a usable object and the `bad_output`
+ * arm is deliberately unreachable for this door. Both fields are render-only (they flavor the
+ * report text); the `success: true` envelope is the cold door's authoritative statement that the
+ * skip was recorded and the on-disk marker cleared.
+ */
+function decodeLearnSkip(payload: ColdJson): LearnSkipPayload {
+  return {
+    learn_state: stringField(payload, "learn_state") ?? null,
+    pending_cleared: booleanField(payload, "pending_cleared") ?? null,
+  };
+}
+
+/**
+ * The closed CAPTURED-classification set persisted on a `perk:learn` header (contracts.md §8.35) —
+ * the reconciliation DECISION set minus `SKIP` (a skip creates no issue). Mirrors
+ * `plan.CapturedDecision` (the Python SSOT) and the `learn` tool's JSON-schema enum.
+ */
+const CAPTURED_DECISIONS = [
+  "CAPTURE_LEARN",
+  "SHOULD_BE_CODE",
+  "UPDATE_EXISTING_DOC",
+  "NEW_DOC",
+  "STALE_DOC",
+] as const;
+
+/** The decoded `perk learn evidence --json` slice the orchestrator branches on. */
+interface EvidenceDecode {
+  skipped: boolean;
+  skip_reason: string | null;
+  bundle_dir: string | null;
+}
+
+/**
+ * Decode the `perk learn evidence --render --json` success payload — fully LENIENT (mirrors
+ * `decodeLearnCapture`): it **never returns null**, so any success envelope yields a usable object
+ * and the `runColdDoor` `bad_output` arm is deliberately unreachable for this door. A missing/
+ * mistyped `skipped` defaults false; `bundle_dir`/`skip_reason` default null. `!r.ok` (exec /
+ * transport / `success:false`) routes to the gather-failure fallback, not here.
+ */
+function decodeEvidence(payload: ColdJson): EvidenceDecode {
+  return {
+    skipped: booleanField(payload, "skipped") ?? false,
+    skip_reason: stringField(payload, "skip_reason") ?? null,
+    bundle_dir: stringField(payload, "bundle_dir") ?? null,
+  };
+}
+
 /**
  * Narrow the `perk learn capture --json` success payload — fully LENIENT, per the decode-policy
  * criterion (strict iff the field is appended to workflow-state; see
@@ -78,29 +156,48 @@ function clearPending(ctx: ExtensionContext): { wasPending: boolean } {
 }
 
 /**
- * The single learn implementation both surfaces call. With a `summary`, delegate the capture to the
- * Python cold door (then mirror the marker-clear); without one, stay the thin marker-clear. Returns
- * a soft result (never throws).
+ * The single learn implementation both surfaces call. With a `summary`, delegate the capture to
+ * the Python cold door; without one, delegate the skip-recording to `perk learn skip` (§8.36 —
+ * the canonical `learn_state: skipped` stamp, no empty issue). Both arms mirror the marker-clear
+ * in-session on success. Returns a soft result (never throws).
  */
 export async function learnDone(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
   summary?: string,
+  decision?: string,
+  target?: string,
 ): Promise<LearnResult> {
   const trimmed = (summary ?? "").trim();
+  const fail = failFor(ctx, "learn");
 
-  // No summary: the thin, graceful path — just clear the marker (no empty issue).
+  // 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
+  // close the learn cycle on uncertainty (the marker is the retry signal).
   if (trimmed.length === 0) {
+    const r = await runColdDoor<LearnSkipPayload>(pi, ctx, ["learn", "skip", "--json"], {
+      label: "perk learn skip",
+      decode: decodeLearnSkip,
+    });
+    if (!r.ok) return fail(r.message, r.errorType);
+    // Mirror the marker-clear in-session (idempotent; the worker already cleared it on disk).
     const { wasPending } = clearPending(ctx);
-    const text = wasPending
-      ? "Cleared pending-learn — the worktree is releasable. (No summary given; no learn issue created.)"
-      : "No pending-learn set — nothing to clear.";
+    const text =
+      r.data.learn_state === "captured"
+        ? "Learnings were already captured — kept; pending-learn cleared."
+        : "Skip recorded on the plan; pending-learn cleared — the worktree is releasable. " +
+          "(No summary given; no learn issue created.)";
     return ok(text, { was_pending: wasPending, captured: false }, { terminate: true });
   }
 
-  const fail = failFor(ctx, "learn");
+  // The captured classification (contracts.md §8.35) rides flags on the capture argv; Click parses
+  // them regardless of order, and the `--body` stdin channel is unchanged.
+  const argv = ["learn", "capture", "--json"];
+  if (decision !== undefined) argv.push("--decision", decision);
+  if (target !== undefined) argv.push("--target", target);
 
-  const r = await runColdDoor<LearnCapturePayload>(pi, ctx, ["learn", "capture", "--json"], {
+  const r = await runColdDoor<LearnCapturePayload>(pi, ctx, argv, {
     label: "perk learn capture",
     decode: decodeLearnCapture,
     stdin: { flag: "--body", content: `${trimmed}\n`, filename: `learn-${Date.now()}.md` },
@@ -128,7 +225,7 @@ export async function learnDone(
 }
 
 const TOOL_GUIDELINES = [
-  "Call learn after a plan has landed; pass a `summary` of the durable learnings to capture them in a perk:learn issue (and clear pending-learn). Omit `summary` to just clear the marker.",
+  "Call learn after a plan has landed; pass a `summary` of the durable learnings to capture them in a perk:learn issue (and clear pending-learn). Omit `summary` to record the skip on the plan and clear the marker.",
   "The summary is captured verbatim — write the learnings as markdown (what changed vs. the plan, deviations, residual risks).",
 ];
 
@@ -167,6 +264,26 @@ export function learnGuidance(planRef: PlanRef | null): string {
   });
 }
 
+/**
+ * The orchestration seed the warm bare `/learn` injects to spawn the angle-specialized analysts and
+ * reconcile their reports into one classified capture/skip (the perk-learn skill pointer rides the
+ * skill-binding suffix — stage:learn — not hardcoded here). Pure + exported for offline tests
+ * (mirrors `prReviewGuidance`). When `model` is set, EVERY analyst spawn carries an inline `model`
+ * override; otherwise the agent's default is used. `manifestPath` is absolute; `bundleDir` is the
+ * absolute bundle directory.
+ */
+export function learnOrchestrateGuidance(opts: {
+  model?: string;
+  manifestPath: string;
+  bundleDir: string;
+}): string {
+  return render("stages/learn-orchestrate.md", {
+    model: opts.model ?? "",
+    manifest_path: opts.manifestPath,
+    bundle_dir: opts.bundleDir,
+  });
+}
+
 /** Register the warm door: the `learn` terminating tool + the `/learn` command twin. */
 export function registerLearn(pi: ExtensionAPI): void {
   pi.registerTool({
@@ -174,8 +291,8 @@ export function registerLearn(pi: ExtensionAPI): void {
     label: "Finish learn",
     description:
       "Capture learnings from a landed plan into a perk:learn issue (pass `summary`), then clear " +
-      "the pending-learn semaphore and release the worktree. Omit `summary` to only clear the marker. " +
-      "Terminating: ends the turn.",
+      "the pending-learn semaphore and release the worktree. Omit `summary` to record the skip " +
+      "on the plan and clear pending-learn. Terminating: ends the turn.",
     promptSnippet:
       "Capture learnings (optional summary) and clear pending-learn (terminates the turn)",
     promptGuidelines: TOOL_GUIDELINES,
@@ -186,30 +303,60 @@ export function registerLearn(pi: ExtensionAPI): void {
       properties: {
         summary: {
           type: "string",
-          description: "Markdown learnings to capture in a perk:learn issue. Omit to only clear.",
+          description:
+            "Markdown learnings to capture in a perk:learn issue. Omit to record the skip.",
+        },
+        decision: {
+          type: "string",
+          enum: [...CAPTURED_DECISIONS],
+          description:
+            "The reconciled captured-classification token, persisted on the perk:learn header. " +
+            "Omit on a verbatim /learn <text> capture (the decision-less escape hatch).",
+        },
+        target: {
+          type: "string",
+          description:
+            "An optional routable pointer (e.g. an existing doc path) for the classification.",
         },
       },
     },
     async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      // Tool-boundary decode: absent → undefined (the marker-clear path); mistyped →
+      // Tool-boundary decode (mirrors the `summary` strictness): absent → undefined (the
+      // marker-clear / decision-less path); a present-but-mistyped/out-of-enum value →
       // strict-fail — never silently clear the pending-learn marker on uncertainty.
       const p = paramsOf(params);
+      const fail = failFor(ctx, "learn");
       const summary = p === null ? undefined : stringParam(p, "summary");
       if (summary === null) {
-        return failFor(ctx, "learn")("learn `summary` must be a string", "bad_input");
+        return fail("learn `summary` must be a string", "bad_input");
       }
-      return learnDone(pi, ctx, summary);
+      const decision = p === null ? undefined : stringParam(p, "decision");
+      if (decision === null) {
+        return fail("learn `decision` must be a string", "bad_input");
+      }
+      if (decision !== undefined && !(CAPTURED_DECISIONS as readonly string[]).includes(decision)) {
+        return fail(
+          `learn \`decision\` must be one of ${CAPTURED_DECISIONS.join(", ")}`,
+          "bad_input",
+        );
+      }
+      const target = p === null ? undefined : stringParam(p, "target");
+      if (target === null) {
+        return fail("learn `target` must be a string", "bad_input");
+      }
+      return learnDone(pi, ctx, summary, decision, target);
     },
   });
 
-  pi.registerCommand("learn", {
+  registerPerkCommand(pi, "learn", {
     description:
       "Investigate the landed change and capture learnings (bare /learn drives the workflow); " +
-      "/learn skip clears pending-learn only; /learn <text> captures the text verbatim.",
+      "/learn skip records the skip on the plan and clears pending-learn; " +
+      "/learn <text> captures the text verbatim.",
     handler: async (args, ctx) => {
       const trimmed = (args ?? "").trim();
 
-      // Explicit text (or `skip`): the existing learnDone path — capture verbatim / marker-clear.
+      // Explicit text (or `skip`): the existing learnDone path — capture verbatim / record skip.
       if (trimmed.length > 0) {
         const summary = trimmed === "skip" ? "" : args;
         const result = await learnDone(pi, ctx, summary);
@@ -220,16 +367,75 @@ export function registerLearn(pi: ExtensionAPI): void {
         return;
       }
 
-      // Bare `/learn`: headless can't drive a turn — stay the safe marker-clear (fail-safe). An
-      // interactive session injects the perk-learn guidance so the agent does the capture pass
-      // (it clears the marker itself by calling the `learn` tool — do NOT clear it here).
+      // Bare `/learn`: headless can't drive a turn or spawn children — take the safe no-summary
+      // path (the canonical skip recording; fail-safe).
       if (!ctx.hasUI) {
         const result = await learnDone(pi, ctx, "");
         console.error(`perk: /learn invoked (headless) — ${result.content[0]?.text ?? "cleared"}`);
         return;
       }
-      report(ctx, "learn", "info", "investigate the landed change and capture learnings");
-      pi.sendUserMessage(learnGuidance(activePlanRef(ctx)) + bindingSuffix(ctx.cwd, "stage:learn"));
+
+      // Interactive bare `/learn`: the multi-angle orchestrator (mirrors /pr-review). Gather the
+      // evidence bundle ONCE (the parent owns the gather — §8.35), then branch.
+      const fallback = () => {
+        // Graceful degrade — /learn is never a dead end. Fall back to the simple learn pass (the
+        // prior behavior); the agent clears the marker itself via the `learn` tool.
+        pi.sendUserMessage(
+          learnGuidance(activePlanRef(ctx)) + bindingSuffix(ctx.cwd, "stage:learn"),
+        );
+      };
+
+      const r = await runColdDoor<EvidenceDecode>(
+        pi,
+        ctx,
+        ["learn", "evidence", "--render", "--json"],
+        { label: "perk learn evidence", decode: decodeEvidence },
+      );
+
+      // Gather failure (exec / transport / success:false): degrade to the simple learn pass.
+      if (!r.ok) {
+        report(
+          ctx,
+          "learn",
+          "info",
+          "evidence gather unavailable — falling back to the simple learn pass",
+        );
+        fallback();
+        return;
+      }
+
+      // Short-circuit: a learn-docs consolidation plan — clear the local marker only, inject
+      // nothing (land already stamped `learn_state: skipped` for a `consumed_learn` plan, §8.36 —
+      // no cold skip delegation needed here).
+      if (r.data.skipped) {
+        clearPending(ctx);
+        report(ctx, "learn", "info", "learn-docs plan; learn capture skipped");
+        return;
+      }
+
+      // Defensive: a success envelope with no bundle dir — same graceful fallback.
+      if (r.data.bundle_dir === null) {
+        report(
+          ctx,
+          "learn",
+          "info",
+          "evidence bundle unavailable — falling back to the simple learn pass",
+        );
+        fallback();
+        return;
+      }
+
+      // Orchestrate: spawn analysts over the shared bundle, reconcile, capture-or-skip. `bundle_dir`
+      // is repo_root-relative; the door's cwd is the worktree root the command resolved against.
+      const bundleDir = join(ctx.cwd, r.data.bundle_dir);
+      const manifestPath = join(bundleDir, "manifest.json");
+      const model = loadPerkConfig(ctx.cwd).subagents["learn-analyst"];
+      report(ctx, "learn", "info", "multi-angle learn: spawn analysts → reconcile → capture");
+      // The agent captures via the `learn` tool (clearing the marker itself) — do NOT clear here.
+      pi.sendUserMessage(
+        learnOrchestrateGuidance({ model, manifestPath, bundleDir }) +
+          bindingSuffix(ctx.cwd, "stage:learn"),
+      );
     },
   });
 }

package/extension/doors/learnCode.ts

@@ -0,0 +1,100 @@
+// hop-2 — the learn-code plan factory's warm transition surface: the `/learn-code` command.
+//
+// The warm twin of the `perk learn code` cold door (sibling of `/learn-docs`). It DELEGATES the
+// gather to the Python plane (`perk learn code --gather --json` via the shared cold-door client
+// `runColdDoor` — gate-safe, not subject to the read-only bash allowlist), decodes
+// `{ inbox_path, learn_numbers }`, then injects the factory guidance via `pi.sendUserMessage` so
+// the model reads the inbox, authors a code plan, and calls `plan_save` with `consumed_learn`. No
+// model tool — the model uses the existing `plan_save` tool.
+//
+// Headless-safe: rich UI is guarded by `ctx.hasUI`; without a UI it logs to stderr and returns
+// (the gather still runs so the inbox is materialized, but no turn is driven).
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { bindingSuffix } from "../substrate/bindingDelivery.ts";
+import { type ColdJson, runColdDoor, stringField } from "../substrate/coldDoor.ts";
+import { registerPerkCommand } from "../substrate/command.ts";
+import { render } from "../substrate/prompts.ts";
+import { report } from "../surfaces/report.ts";
+
+/** The decoded `perk learn code --gather --json` payload slice the warm door consumes. */
+interface LearnCodeGatherPayload {
+  inbox_path: string;
+  /** Opaque string learn-issue ids (GitHub "45", Linear "ENG-45") — §8.21. */
+  learn_numbers: string[];
+}
+
+/** Strict decode — the guidance dereferences both fields; `launched` is unconsumed. Exported for offline reject-branch tests. */
+export function decodeGather(payload: ColdJson): LearnCodeGatherPayload | null {
+  const inboxPath = stringField(payload, "inbox_path");
+  const numbers = payload.learn_numbers;
+  if (inboxPath === undefined) return null;
+  // String ids are canonical (§8.21); numbers are tolerated + coerced (older envelopes).
+  if (
+    !Array.isArray(numbers) ||
+    !numbers.every((n) => typeof n === "string" || typeof n === "number")
+  ) {
+    return null;
+  }
+  return { inbox_path: inboxPath, learn_numbers: numbers.map((n) => String(n)) };
+}
+
+/**
+ * The seed guidance the warm `/learn-code` injects to start the factory loop (the perk-learn-code
+ * skill pointer rides the skill-binding suffix — not hardcoded here). Pure + exported
+ * for offline tests.
+ */
+export function learnCodeGuidance(inboxPath: string, learnNumbers: string[]): string {
+  return render("stages/learn-code.md", {
+    inbox_path: inboxPath,
+    num_list: learnNumbers.join(", "),
+  });
+}
+
+/** Register the warm learn-code door: the `/learn-code` command (no model tool). */
+export function registerLearnCode(pi: ExtensionAPI): void {
+  registerPerkCommand(pi, "learn-code", {
+    description:
+      "Start the learn-code plan factory: gather pre-stamped SHOULD_BE_CODE perk:learn issues into " +
+      "an inbox and author a plan routing each into its real code home.",
+    handler: async (_args, ctx: ExtensionContext) => {
+      // Report-only door (no Result type): branch on `errorType` directly (the coldDoor header
+      // convention). A clean "nothing to route" exits non-zero with error_type=no_learn_issues —
+      // the client's envelope-aware arm surfaces it gently.
+      const r = await runColdDoor<LearnCodeGatherPayload>(
+        pi,
+        ctx,
+        ["learn", "code", "--gather", "--json"],
+        { label: "perk learn code", decode: decodeGather },
+      );
+      if (!r.ok) {
+        if (r.errorType === "no_learn_issues") {
+          report(
+            ctx,
+            "learn-code",
+            "warning",
+            "nothing to route into code (no SHOULD_BE_CODE perk:learn issues).",
+          );
+        } else {
+          report(ctx, "learn-code", "error", `gather failed: ${r.message}`);
+        }
+        return;
+      }
+
+      if (!ctx.hasUI) {
+        // Headless can't drive a turn — the inbox is materialized; log and return (fail-safe).
+        console.error(
+          `perk: /learn-code invoked (headless) — gathered ${r.data.learn_numbers.length} ` +
+            `learn issue(s) into ${r.data.inbox_path}; run interactively to author the code plan.`,
+        );
+        return;
+      }
+
+      report(ctx, "learn-code", "info", `gathered ${r.data.learn_numbers.length} learn issue(s)`);
+      pi.sendUserMessage(
+        learnCodeGuidance(r.data.inbox_path, r.data.learn_numbers) +
+          bindingSuffix(ctx.cwd, "command:learn-code"),
+      );
+    },
+  });
+}

package/extension/doors/learnDocs.ts

@@ -13,6 +13,7 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { bindingSuffix } from "../substrate/bindingDelivery.ts";
 import { type ColdJson, runColdDoor, stringField } from "../substrate/coldDoor.ts";
+import { registerPerkCommand } from "../substrate/command.ts";
 import { render } from "../substrate/prompts.ts";
 import { report } from "../surfaces/report.ts";
 
@@ -23,8 +24,8 @@ interface LearnDocsGatherPayload {
   learn_numbers: string[];
 }
 
-/** Strict decode — the guidance dereferences both fields; `launched` is unconsumed. */
-function decodeGather(payload: ColdJson): LearnDocsGatherPayload | null {
+/** Strict decode — the guidance dereferences both fields; `launched` is unconsumed. Exported for offline reject-branch tests. */
+export function decodeGather(payload: ColdJson): LearnDocsGatherPayload | null {
   const inboxPath = stringField(payload, "inbox_path");
   const numbers = payload.learn_numbers;
   if (inboxPath === undefined) return null;
@@ -52,7 +53,7 @@ export function learnDocsGuidance(inboxPath: string, learnNumbers: string[]): st
 
 /** Register the warm learned-docs door: the `/learn-docs` command (no model tool). */
 export function registerLearnDocs(pi: ExtensionAPI): void {
-  pi.registerCommand("learn-docs", {
+  registerPerkCommand(pi, "learn-docs", {
     description:
       "Start the learned-docs plan factory: gather open perk:learn issues into an inbox and author " +
       "a docs/learned consolidation plan.",

package/extension/doors/lifecycleGates.ts

@@ -14,6 +14,7 @@ import type {
   ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 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 { report } from "../surfaces/report.ts";
@@ -104,7 +105,7 @@ export function implementHandoffPrompt(ref: PlanRef): string {
  * either way), fail-safe-headless.
  */
 function registerImplementGuard(pi: ExtensionAPI): void {
-  pi.registerCommand("implement", {
+  registerPerkCommand(pi, "implement", {
     description:
       "Refresh implement context (in-worktree handoff); cross-worktree is `perk implement`.",
     handler: async (_args, ctx) => {