@mgiles/perk 1.0.1 → 2.0.0

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 `[models.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,8 +225,8 @@ 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.",
-  "The summary is captured verbatim — write the learnings as markdown (what changed vs. the plan, deviations, residual risks).",
+  "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.",
+  "learn captures the summary verbatim — write the learnings as markdown (what changed vs. the plan, deviations, residual risks).",
 ];
 
 /** Resolve the active plan-ref (worktree first, then the rebuilt workflow-state). */
@@ -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/learnFactory.ts

@@ -0,0 +1,144 @@
+// hop-2 — the two learn plan factories' warm transition surfaces: the `/learn-docs` and
+// `/learn-code` commands (the warm twins of the `perk learn docs` / `perk learn code` cold
+// doors). One shared register parameterized by a kind config — mirroring the Python plane's
+// `factory_common.py` (`LearnFactoryKind` + `DOCS_FACTORY`/`CODE_FACTORY` + `run_factory`).
+//
+// Each door DELEGATES the gather to the Python plane (`perk learn <kind> --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 the plan, and saves it. The save is
+// surface-dependent (the seed spells this out): where `plan_save` is active (a read-write session,
+// the warm doors' usual host) the model passes `consumed_learn` explicitly — load-bearing here,
+// because the warm gather is side-effect-free and writes NO handoff carrier; in a gated read-only
+// session `plan_save` is hidden (toolGating.ts), so the save lands review-first via `plan_review`
+// and the COLD doors' handoff carrier supplies `consumed_learn`. No model tool is registered here.
+//
+// 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 per-door parameter bundle shared by the two warm learn-factory doors (the TS twin of the
+ * frozen `LearnFactoryKind` dataclass). `subcommand` derives the cold argv, the `runColdDoor`
+ * label, and the headless log tail; `seedTemplate` and `bindingTrigger` stay explicit so the
+ * strings remain greppable against `prompts/stages/` and `shared/bindings.yaml`.
+ */
+export interface LearnFactoryDoorKind {
+  /** The command id and `report()` scope. */
+  readonly name: string;
+  /** The cold-door verb under `perk learn`. */
+  readonly subcommand: string;
+  readonly seedTemplate: string;
+  readonly bindingTrigger: string;
+  /** The `registerPerkCommand` description. */
+  readonly description: string;
+  /** The gentle `no_learn_issues` warning. */
+  readonly emptyMessage: string;
+}
+
+export const DOCS_DOOR: LearnFactoryDoorKind = {
+  name: "learn-docs",
+  subcommand: "docs",
+  seedTemplate: "stages/learn-docs.md",
+  bindingTrigger: "command:learn-docs",
+  description:
+    "Start the learned-docs plan factory: gather open perk:learn issues into an inbox and author " +
+    "a docs/learned consolidation plan.",
+  emptyMessage: "nothing to consolidate (no open perk:learn issues).",
+};
+
+export const CODE_DOOR: LearnFactoryDoorKind = {
+  name: "learn-code",
+  subcommand: "code",
+  seedTemplate: "stages/learn-code.md",
+  bindingTrigger: "command: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.",
+  emptyMessage: "nothing to route into code (no SHOULD_BE_CODE perk:learn issues).",
+};
+
+/** The decoded `perk learn <kind> --gather --json` payload slice the warm door consumes. */
+export interface LearnGatherPayload {
+  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): LearnGatherPayload | 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 door injects to start the factory loop (the per-kind skill pointer
+ * rides the skill-binding suffix — not hardcoded here). Pure + exported for offline tests.
+ */
+export function learnFactoryGuidance(
+  kind: LearnFactoryDoorKind,
+  inboxPath: string,
+  learnNumbers: string[],
+): string {
+  return render(kind.seedTemplate, {
+    inbox_path: inboxPath,
+    num_list: learnNumbers.join(", "),
+  });
+}
+
+/** Register one warm learn-factory door: the `/<kind.name>` command (no model tool). */
+export function registerLearnFactoryDoor(pi: ExtensionAPI, kind: LearnFactoryDoorKind): void {
+  registerPerkCommand(pi, kind.name, {
+    description: kind.description,
+    handler: async (_args, ctx: ExtensionContext) => {
+      // Report-only door (no Result type): branch on `errorType` directly (the coldDoor header
+      // convention). A clean empty inbox exits non-zero with error_type=no_learn_issues — the
+      // client's envelope-aware arm surfaces it gently.
+      const r = await runColdDoor<LearnGatherPayload>(
+        pi,
+        ctx,
+        ["learn", kind.subcommand, "--gather", "--json"],
+        { label: `perk learn ${kind.subcommand}`, decode: decodeGather },
+      );
+      if (!r.ok) {
+        if (r.errorType === "no_learn_issues") {
+          report(ctx, kind.name, "warning", kind.emptyMessage);
+        } else {
+          report(ctx, kind.name, "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: /${kind.name} invoked (headless) — gathered ${r.data.learn_numbers.length} ` +
+            `learn issue(s) into ${r.data.inbox_path}; run interactively to author the ` +
+            `${kind.subcommand} plan.`,
+        );
+        return;
+      }
+
+      report(ctx, kind.name, "info", `gathered ${r.data.learn_numbers.length} learn issue(s)`);
+      pi.sendUserMessage(
+        learnFactoryGuidance(kind, r.data.inbox_path, r.data.learn_numbers) +
+          bindingSuffix(ctx.cwd, kind.bindingTrigger),
+      );
+    },
+  });
+}

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) => {