@mgiles/perk 1.1.0 → 2.0.0

package/extension/doors/ciExecutor.ts

@@ -1,7 +1,8 @@
 // The perk-owned, read-only CI executor (the Run→Report half of Run→Report→Fix→Verify).
 //
-// A deterministic, in-process check runner: it runs the project's configured `[ci]` named checks
-// via `pi.exec` and REPORTS pass/fail + failure output — it never edits, fixes, or loops. The
+// A deterministic, in-process check runner: it runs the project's configured `[[ci.checks]]`
+// named checks via `pi.exec` and REPORTS pass/fail + failure output — it never edits, fixes, or
+// loops. The
 // parent agent (the normal read-write implement session) owns the entire fix loop and all
 // iteration state; this executor is a stateless oracle invoked once per `run_ci` call (the
 // `devrun` discipline: "run and report", never "run and fix").
@@ -13,14 +14,14 @@
 // does NOT call `runReadOnlyChild` (whose `success` means "ran", carrying no exit code).
 //
 // Threat model & the safety boundary (read first):
-//   `pi.exec("bash", ["-lc", cmd])` runs whatever the `[ci]` command string says, with full
-//   filesystem/network access, OUTSIDE perk's tool gate. The defenses, in order, are:
+//   `pi.exec("bash", ["-lc", cmd])` runs whatever the `[[ci.checks]]` command string says, with
+//   full filesystem/network access, OUTSIDE perk's tool gate. The defenses, in order, are:
 //     1. The model never authors the command — it picks a configured NAME (a persuaded model
 //        cannot run `rm -rf` because it cannot supply a command).
 //     2. Untrusted-config scope gate (`decideCiScope`) — running a project-supplied command at
-//        all requires `[trust] ci = "true"` (committed config), `--allow-project-ci`, an
+//        all requires `[ci] trusted = true` (committed config), `--allow-project-ci`, an
 //        interactive confirm, or a per-session approval latch; headless with none REFUSES (fail
-//        closed). This is the real defense against a malicious cloned-repo `[ci]`.
+//        closed). This is the real defense against malicious cloned-repo `[[ci.checks]]` rows.
 //     3. Output isolation — full output to scratch, capped + `<untrusted_ci_output>`-wrapped in
 //        the parent's view (prompt-injection-in-stdout hygiene).
 //   A true OS/tool sandbox around the check command is explicitly OUT OF SCOPE.
@@ -94,7 +95,7 @@ export type CiScope = "run" | "confirm" | "refuse";
 
 /**
  * Decide how to treat project-supplied CI. Pure (the load-bearing safety boundary):
- *   - `[trust] ci` (committed config), `--allow-project-ci`, or a per-session latch ⇒ "run"
+ *   - `[ci] trusted` (committed config), `--allow-project-ci`, or a per-session latch ⇒ "run"
  *     (trust runs on EVERY surface, overriding the headless refuse below)
  *   - else with UI ⇒ "confirm" (ask the human)
  *   - else (headless, no trust/flag) ⇒ "refuse" (fail closed)
@@ -164,7 +165,9 @@ export async function runOneCheck(
     writeError = err instanceof Error ? err.message : String(err);
   }
 
-  const capped = capForModel(outcome.output, cap, scratchPath);
+  // Tail-keep: pytest/tsc failure summaries live at the END of the output, so the model-visible
+  // slice keeps the last `cap` bytes; the scratch file still holds the full output.
+  const capped = capForModel(outcome.output, cap, scratchPath, "tail");
   return {
     name,
     command,
@@ -368,7 +371,7 @@ export function renderCiProse(report: CiReport): string {
     );
   }
   if (report.error_type === "no_checks_configured") {
-    return "No CI checks configured ([[ci]] in .perk/config.toml is empty). Nothing to run.";
+    return "No CI checks configured ([[ci.checks]] in .perk/config.toml is empty). Nothing to run.";
   }
   if (report.error_type === "unknown_check") {
     return `perk CI: ${report.error}`;
@@ -398,6 +401,9 @@ export function renderCiProse(report: CiReport): string {
     lines.push(c.shown || "(no output captured)");
     lines.push("</untrusted_ci_output>");
   }
+  // Deliberately head-capped (unlike the per-check tail cap): the prose leads with the ✓/✗
+  // per-check summary and the scratch-path pointers — the actionable routing info a tail cap
+  // would drop.
   return capForModel(lines.join("\n"), DEFAULT_MODEL_VISIBLE_CAP).shown;
 }
 
@@ -433,8 +439,9 @@ interface ApprovalLatch {
 }
 
 /**
- * The single `run_ci`/`/ci` implementation. Loads `[ci]`, scopes the run (the untrusted-config
- * gate), runs the selected check(s) deterministically, and returns double-delivery. Never throws.
+ * The single `run_ci`/`/ci` implementation. Loads `[[ci.checks]]`, scopes the run (the
+ * untrusted-config gate), runs the selected check(s) deterministically, and returns
+ * double-delivery. Never throws.
  */
 async function runCiImpl(
   pi: ExtensionAPI,
@@ -444,7 +451,7 @@ async function runCiImpl(
   deps: RunCiDeps = {},
 ): Promise<CiResult> {
   const cfg = loadPerkConfig(ctx.cwd);
-  const checks: CiCheck[] = cfg.ci;
+  const checks: CiCheck[] = cfg.ci.checks;
   const wrap = (report: CiReport): CiResult => ({
     content: [{ type: "text", text: renderCiProse(report) }],
     details: report,
@@ -456,7 +463,7 @@ async function runCiImpl(
   if (checks.length > 0) {
     const decideScope = deps.decideScope ?? decideCiScope;
     const allowFlag = pi.getFlag("allow-project-ci") === true;
-    const trusted = cfg.trust.ci === true;
+    const trusted = cfg.ci.trusted;
     const scope = decideScope({ hasUI: ctx.hasUI, allowFlag, approved: latch.approved, trusted });
 
     if (scope === "refuse") {
@@ -507,7 +514,7 @@ async function runCiImpl(
 const TOOL_GUIDELINES = [
   "run_ci RUNS the configured CI checks and REPORTS results — it never edits, fixes, or loops.",
   "Analyze any failure yourself, fix it in your own turn, then call run_ci again to re-verify.",
-  "Optionally pass a single configured check name; omit it to run all checks in declared order.",
+  "Pass run_ci a single configured check name to run just that check; omit it to run all checks in declared order.",
   "You own the Run→Report→Fix→Verify loop; run_ci is a stateless oracle, not an auto-fixer.",
 ];
 

package/extension/doors/hunkHandoff.ts

@@ -0,0 +1,202 @@
+// The hunk terminal-review substrate serving `/pr-review-terminal`: the strict
+// `perk pr review checkout` decode, the `hunk --version` presence probe, and the R7 launch
+// handoff (clipboard copy + terminal auto-launch raced against a soft deadline) — plus the
+// door-common PR-token arg grammar (`parseReviewArgs`) that `/pr-review-browser` also consumes
+// via `parseReviewDoorArgs`. Re-homing the door-common pieces to a neutral module is a deferred
+// residual (accepted — no code moves yet).
+
+import { copyToClipboard } from "../substrate/clipboard.ts";
+import { type ColdJson, type ExecHost, numberField, stringField } from "../substrate/coldDoor.ts";
+import { LAUNCH_SURFACE, launchInTerminal } from "../substrate/terminalLaunch.ts";
+import { type ReportTarget, report } from "../surfaces/report.ts";
+
+/** The install hint for the absent hunk binary — the exact `HUNK_INSTALL_HINT` wording
+ * (src/perk/convergence/init/review_cli.py). */
+export const HUNK_INSTALL_HINT = "npm i -g hunkdiff (or brew install hunk)";
+
+// ------------------------------------------------------------------------ the PR arg grammar
+
+/** A parsed PR-review invocation: the PR number + the optional free-form focus directive. */
+export interface ReviewArgs {
+  pr: number;
+  directive: string;
+}
+
+/** Extracts the PR number from a GitHub PR URL (with optional trailing /path, #fragment, ?query). */
+export const PR_URL_RE = /\/pull\/(\d+)(?:\/|$|#|\?)/;
+
+/**
+ * Parse a PR-review arg string: the first token is a bare PR number or a GitHub PR URL; the rest
+ * is the optional free-form focus directive. Null on a missing/unparseable PR (usage failure).
+ * Cross-repo URLs are NOT validated against the session repo — the number is extracted as-is.
+ */
+export function parseReviewArgs(args: string): ReviewArgs | null {
+  const trimmed = args.trim();
+  if (trimmed.length === 0) return null;
+  const split = trimmed.match(/^(\S+)(?:\s+([\s\S]*))?$/);
+  if (split === null) return null;
+  const first = split[1] ?? "";
+  const directive = (split[2] ?? "").trim();
+  let pr: number | null = null;
+  if (/^\d+$/.test(first)) {
+    pr = Number(first);
+  } else {
+    const url = first.match(PR_URL_RE);
+    if (url?.[1] !== undefined) pr = Number(url[1]);
+  }
+  if (pr === null || !Number.isSafeInteger(pr) || pr <= 0) return null;
+  return { pr, directive };
+}
+
+// ------------------------------------------------------------------------ checkout decode
+
+/** The `perk pr review checkout --json` ok-arm (all six fields always emitted — strict). */
+export interface CheckoutOk {
+  path: string;
+  pr: number;
+  url: string;
+  head_sha: string;
+  base_sha: string;
+  base_ref: string;
+}
+
+/** Strict decode of the checkout payload — the guidance dereferences `path`/`base_sha`/`url`. */
+export function decodeCheckout(payload: ColdJson): CheckoutOk | null {
+  const path = stringField(payload, "path");
+  const pr = numberField(payload, "pr");
+  const url = stringField(payload, "url");
+  const headSha = stringField(payload, "head_sha");
+  const baseSha = stringField(payload, "base_sha");
+  const baseRef = stringField(payload, "base_ref");
+  if (
+    path === undefined ||
+    pr === undefined ||
+    url === undefined ||
+    headSha === undefined ||
+    baseSha === undefined ||
+    baseRef === undefined
+  ) {
+    return null;
+  }
+  return { path, pr, url, head_sha: headSha, base_sha: baseSha, base_ref: baseRef };
+}
+
+// ------------------------------------------------------------------------ the hunk probe
+
+/**
+ * Whether the `hunk` review CLI is present — the `hunk --version` probe (`!killed && code === 0`;
+ * any throw ⇒ false). The terminal door refuses-at-start on a false, before any cold-door call.
+ */
+export async function hunkPresent(
+  pi: ExecHost,
+  ctx: { cwd: string; signal?: AbortSignal },
+): Promise<boolean> {
+  try {
+    const probe = await pi.exec("hunk", ["--version"], { cwd: ctx.cwd, signal: ctx.signal });
+    return !probe.killed && probe.code === 0;
+  } catch {
+    return false;
+  }
+}
+
+// ------------------------------------------------------------------------ the R7 handoff
+
+/** The minimal ctx slice the hunk launch handoff needs (report + the exec cwd/signal). */
+interface ReviewLaunchCtx extends ReportTarget {
+  cwd: string;
+  signal?: AbortSignal;
+}
+
+/** The default soft deadline the launch is raced against (ms) — see `handleHunkLaunch`. */
+const LAUNCH_SOFT_DEADLINE_MS = 2000;
+
+/**
+ * The soft-deadline knob: `PERK_REVIEW_LAUNCH_DEADLINE_MS` (an internal test seam — documented
+ * in contracts §8.4 beside the two human-facing seams, never in user docs; tests drive the whole
+ * command handler, so an env knob is the only injectable surface). Falls back to the 2s default.
+ */
+function softDeadlineMs(): number {
+  const raw = process.env.PERK_REVIEW_LAUNCH_DEADLINE_MS;
+  if (raw !== undefined) {
+    const n = Number(raw);
+    if (Number.isFinite(n) && n >= 0) return n;
+  }
+  return LAUNCH_SOFT_DEADLINE_MS;
+}
+
+/**
+ * A cancellable `null`-resolving timer — the soft-deadline arm of the launch race. The caller
+ * cancels it once the race settles so a won race never leaves a live timer behind (a leak in
+ * production; a hang/latency drag under test runners that wait for pending timers).
+ */
+function delay(ms: number): { promise: Promise<null>; cancel: () => void } {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const promise = new Promise<null>((resolve) => {
+    timer = setTimeout(() => resolve(null), ms);
+  });
+  return {
+    promise,
+    cancel: () => {
+      if (timer !== undefined) clearTimeout(timer);
+    },
+  };
+}
+
+/**
+ * The hunk R7 handoff (contracts §8.4). Copies the launch command to the clipboard, then
+ * auto-launches hunk in a terminal the human can see — raced against a soft deadline so a
+ * first-run macOS Automation/TCC dialog (which blocks `osascript` until answered) never inserts
+ * ~18s of silence before the guidance injection. Reports the outcome under `opts.scope` (the
+ * invoking door's report scope): an **info** "opened hunk" when the launch settled cleanly within
+ * the deadline, else a **warning** "ACTION NEEDED" (the launch failed, no rung matched, or it is
+ * still pending). For the pending case, a background follow-up info note lands if/when consent is
+ * granted and the launch succeeds. Non-blocking: the caller injects the guidance immediately
+ * either way. The `hunk session get` handshake (driven by the model per the template) — never a
+ * spawn success — remains the only verification hunk is up.
+ */
+export async function handleHunkLaunch(
+  pi: ExecHost,
+  ctx: ReviewLaunchCtx,
+  opts: { cwd: string; hunkCmd: string; launchLine: string; scope: string },
+): Promise<void> {
+  const copied = await copyToClipboard(pi, ctx, opts.launchLine);
+  const clip = copied ? " (it's on your clipboard)" : "";
+  const settled = launchInTerminal(pi, ctx, { cwd: opts.cwd, command: opts.hunkCmd });
+  const deadline = delay(softDeadlineMs());
+  const quick = await Promise.race([settled, deadline.promise]);
+  deadline.cancel();
+  if (quick?.launched) {
+    report(
+      ctx,
+      opts.scope,
+      "info",
+      `opened hunk in a new ${LAUNCH_SURFACE[quick.via ?? "terminal-app"]} — if nothing ` +
+        `appeared, run this in another terminal:\n  ${opts.launchLine}${clip}`,
+    );
+    return;
+  }
+  report(
+    ctx,
+    opts.scope,
+    "warning",
+    `ACTION NEEDED — run hunk in another terminal:\n  ${opts.launchLine}${clip}`,
+  );
+  if (quick === null) {
+    // Still pending past the soft deadline (a first-run TCC dialog): proceed now, and note it if
+    // consent is granted and the launch lands so the human can ignore the manual step.
+    // `launchInTerminal` never rejects by contract — the `.catch` is belt-and-braces.
+    void settled
+      .then((r) => {
+        if (r.launched) {
+          report(
+            ctx,
+            opts.scope,
+            "info",
+            `hunk opened in a new ${LAUNCH_SURFACE[r.via ?? "terminal-app"]} — ignore the ` +
+              "manual step above",
+          );
+        }
+      })
+      .catch(() => {});
+  }
+}

package/extension/doors/land.ts

@@ -1,13 +1,16 @@
 // The warm `/land` door. The in-session twin of the Python cold door
 // (`perk pr land`): a terminating tool + command that DELEGATE the GitHub merge (mutations
-// canonical in Python), then set the `pending-learn` marker for the in-session path (the worker
-// sets it too on the cold path; the marker is an idempotent existence-semaphore). Never throws.
+// canonical in Python), then mirror the envelope's `pending_learn` for the in-session path —
+// setting the `pending-learn` marker (an idempotent existence-semaphore; the worker sets it too
+// on the cold path) unless the cold door reports the learn-docs exemption (`pending_learn:
+// false` — no marker, no /learn nudge). Never throws.
 
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { reconcileGuidance } from "../factories/objectivePlan.ts";
 import { bindingSuffix } from "../substrate/bindingDelivery.ts";
 import { PENDING_LEARN, setMarker } from "../substrate/cache.ts";
 import {
+  booleanField,
   type ColdJson,
   nullableStringField,
   numberField,
@@ -37,7 +40,8 @@ export interface LearnConsumeUpdate {
   skipped_reason: string | null;
 }
 
-/** The ok-arm fields — the structured `details` surface doubles as branch-safe persisted state. */
+/** The ok-arm fields — the structured `details` surface doubles as branch-safe persisted state.
+ * `pending_learn` mirrors the cold envelope: `false` is the learn-docs exemption (no marker). */
 export interface LandOk {
   pr: { number: number; state: string };
   branch?: string;
@@ -51,11 +55,13 @@ export interface LandOk {
 export type LandResult = Result<LandOk>;
 export type LandDetails = LandResult["details"];
 
-/** The decoded `perk pr land --json` payload — `LandOk` minus the warm-door-owned `pending_learn`. */
+/** The decoded `perk pr land --json` payload — the cold door owns `pending_learn` (the
+ * learn-docs-exemption decision point); decoded leniently so skew degrades to legacy. */
 interface LandPayload {
   pr: { number: number; state: string };
   branch?: string;
   issue?: string;
+  pending_learn: boolean;
   objective?: ObjectiveLandUpdate;
   learn?: LearnConsumeUpdate;
 }
@@ -108,6 +114,10 @@ function decodeLand(payload: ColdJson): LandPayload | null {
     pr: { number, state },
     branch: stringField(payload, "branch"),
     issue: stringField(payload, "issue"),
+    // Lenient: a missing/mistyped `pending_learn` (an older cold CLI under version skew)
+    // defaults to the legacy behavior (marker + /learn nudge) — never a silently-unreleased
+    // marker with no visible nudge.
+    pending_learn: booleanField(payload, "pending_learn") ?? true,
     objective: decodeObjective(payload),
     learn: decodeLearn(payload),
   };
@@ -115,7 +125,9 @@ function decodeLand(payload: ColdJson): LandPayload | null {
 
 /**
  * The single land implementation both surfaces call. Delegates the merge to the Python cold door,
- * then sets `pending-learn` (in-session path). Returns a soft result (never throws).
+ * then mirrors the envelope's `pending_learn` (in-session path): marker + /learn nudge on the
+ * ordinary arm; no marker, no nudge on the learn-docs exemption. Returns a soft result
+ * (never throws).
  */
 export async function landPr(pi: ExtensionAPI, ctx: ExtensionContext): Promise<LandResult> {
   const fail = failFor(ctx, "land");
@@ -126,10 +138,16 @@ export async function landPr(pi: ExtensionAPI, ctx: ExtensionContext): Promise<L
   });
   if (!r.ok) return fail(r.message, r.errorType);
 
-  // Set the semaphore for the in-session path (idempotent; the worker also set it on disk).
-  setMarker(ctx.cwd, PENDING_LEARN);
+  if (r.data.pending_learn) {
+    // Set the semaphore for the in-session path (idempotent; the cold door also set it on disk).
+    setMarker(ctx.cwd, PENDING_LEARN);
+  }
 
-  const lines = [`Landed PR #${r.data.pr.number}; run /learn to release the worktree.`];
+  const lines = [
+    r.data.pending_learn
+      ? `Landed PR #${r.data.pr.number}; run /learn to release the worktree.`
+      : `Landed PR #${r.data.pr.number}; learn-docs plan — no learn pass needed; the worktree is releasable.`,
+  ];
   const obj = r.data.objective;
   if (obj?.nodes_marked.length && obj.id !== null) {
     // The reconcile pass is auto-driven after land (see driveReconcileAfterLand); just report it.
@@ -156,7 +174,11 @@ export async function landPr(pi: ExtensionAPI, ctx: ExtensionContext): Promise<L
     lines.push(`Warning: learn consume incomplete — ${learn.skipped_reason}.`);
   }
 
-  return ok(lines.join("\n"), { ...r.data, pending_learn: true }, { terminate: true });
+  return ok(
+    lines.join("\n"),
+    { ...r.data, pending_learn: r.data.pending_learn },
+    { terminate: true },
+  );
 }
 
 /**

package/extension/doors/learn.ts

@@ -24,7 +24,7 @@
 // `/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
+// 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.
 
@@ -226,7 +226,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 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).",
+  "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). */

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),
+      );
+    },
+  });
+}