@mgiles/perk 1.0.1

package/extension/doors/land.ts

@@ -0,0 +1,222 @@
+// 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.
+
+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 {
+  type ColdJson,
+  nullableStringField,
+  numberField,
+  objectField,
+  runColdDoor,
+  stringField,
+} from "../substrate/coldDoor.ts";
+import { failFor, ok, type Result } from "../substrate/result.ts";
+import { report } from "../surfaces/report.ts";
+
+// Learn-consume skip reasons that are ordinary, not failures: non-factory plans carry no
+// `consumed_learn` (`no_consumed_learn`), and a dry run reports `dry_run`. Anything else surfaces.
+const BENIGN_LEARN_SKIPS = new Set(["no_consumed_learn", "dry_run"]);
+
+export interface ObjectiveLandUpdate {
+  /** Opaque string objective id (GitHub "5", Linear "ENG-5") — §8.21. */
+  id: string | null;
+  nodes_marked: string[];
+  skipped_reason: string | null;
+  closed: boolean;
+}
+
+export interface LearnConsumeUpdate {
+  /** Opaque string learn-issue ids (§8.21). */
+  closed: string[];
+  skipped_reason: string | null;
+}
+
+/** The ok-arm fields — the structured `details` surface doubles as branch-safe persisted state. */
+export interface LandOk {
+  pr: { number: number; state: string };
+  branch?: string;
+  /** Opaque string plan-issue id (§8.21). */
+  issue?: string;
+  pending_learn: boolean;
+  objective?: ObjectiveLandUpdate;
+  learn?: LearnConsumeUpdate;
+}
+
+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`. */
+interface LandPayload {
+  pr: { number: number; state: string };
+  branch?: string;
+  issue?: string;
+  objective?: ObjectiveLandUpdate;
+  learn?: LearnConsumeUpdate;
+}
+
+/** Validate the optional `objective` sub-object; malformed → undefined (advisory, never fatal). */
+function decodeObjective(payload: ColdJson): ObjectiveLandUpdate | undefined {
+  const obj = objectField(payload, "objective");
+  if (obj === undefined) return undefined;
+  const id = obj.id;
+  if (typeof id !== "string" && id !== null) return undefined;
+  const nodesMarked = obj.nodes_marked;
+  if (!Array.isArray(nodesMarked) || !nodesMarked.every((n) => typeof n === "string")) {
+    return undefined;
+  }
+  const skippedReason = nullableStringField(obj, "skipped_reason");
+  if (skippedReason === undefined && obj.skipped_reason !== undefined) return undefined;
+  // `closed` is an advisory display detail: decode leniently (missing/malformed → false) rather
+  // than dropping the whole sub-object.
+  return {
+    id,
+    nodes_marked: nodesMarked,
+    skipped_reason: skippedReason ?? null,
+    closed: obj.closed === true,
+  };
+}
+
+/** Validate the optional `learn` sub-object; malformed → undefined (advisory, never fatal). */
+function decodeLearn(payload: ColdJson): LearnConsumeUpdate | undefined {
+  const learn = objectField(payload, "learn");
+  if (learn === undefined) return undefined;
+  const closed = learn.closed;
+  if (!Array.isArray(closed) || !closed.every((n) => typeof n === "string")) return undefined;
+  const skippedReason = nullableStringField(learn, "skipped_reason");
+  if (skippedReason === undefined && learn.skipped_reason !== undefined) return undefined;
+  return { closed, skipped_reason: skippedReason ?? null };
+}
+
+/**
+ * Narrow the `perk pr land --json` success payload. Strict on `pr` (malformed → bad_output);
+ * the optional `objective`/`learn` sub-objects are validated but dropped when malformed — the
+ * merge already succeeded, so the success report must survive a malformed advisory field.
+ */
+function decodeLand(payload: ColdJson): LandPayload | null {
+  const pr = objectField(payload, "pr");
+  if (pr === undefined) return null;
+  const number = numberField(pr, "number");
+  const state = stringField(pr, "state");
+  if (number === undefined || state === undefined) return null;
+  return {
+    pr: { number, state },
+    branch: stringField(payload, "branch"),
+    issue: stringField(payload, "issue"),
+    objective: decodeObjective(payload),
+    learn: decodeLearn(payload),
+  };
+}
+
+/**
+ * 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).
+ */
+export async function landPr(pi: ExtensionAPI, ctx: ExtensionContext): Promise<LandResult> {
+  const fail = failFor(ctx, "land");
+
+  const r = await runColdDoor<LandPayload>(pi, ctx, ["pr", "land", "--json"], {
+    label: "perk pr land",
+    decode: decodeLand,
+  });
+  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);
+
+  const lines = [`Landed PR #${r.data.pr.number}; run /learn to release the worktree.`];
+  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.
+    lines.push(
+      `Objective #${obj.id} node(s) ${obj.nodes_marked.join(", ")} marked done — ` +
+        `reconciling the roadmap against the merged diff.`,
+    );
+  }
+  if (obj?.closed && obj.id !== null) {
+    lines.push(`Objective #${obj.id} complete — closed.`);
+  }
+  const learn = r.data.learn;
+  if (learn?.closed.length) {
+    // hop-2: the consumed perk:learn issues were closed + labelled perk:consolidated on land.
+    lines.push(
+      `Closed ${learn.closed.length} learn issue(s) (${learn.closed
+        .map((n) => `#${n}`)
+        .join(", ")}) into docs/learned.`,
+    );
+  }
+  // Surface a non-benign learn-consume skip: `no_consumed_learn` is the ordinary
+  // non-factory case, so stay quiet on it; a real failure must be visible, not silent.
+  if (learn?.skipped_reason && !BENIGN_LEARN_SKIPS.has(learn.skipped_reason)) {
+    lines.push(`Warning: learn consume incomplete — ${learn.skipped_reason}.`);
+  }
+
+  return ok(lines.join("\n"), { ...r.data, pending_learn: true }, { terminate: true });
+}
+
+/**
+ * After a successful land that marked at least one objective node done, drive the session into the
+ * reconcile pass by injecting the exact guidance `/objective-reconcile` injects (warm-door driving
+ * pattern). The terminating `land` tool stays terminating — terminate only skips the *automatic*
+ * follow-up LLM call, while a `followUp` user message is a separate deliberate new turn. Short-
+ * circuits (sends nothing) unless the land succeeded with an objective node marked done — the exact
+ * condition that gated the old copy-pasteable nudge.
+ */
+export function driveReconcileAfterLand(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  details: LandDetails,
+): void {
+  if (!details.ok) return;
+  const obj = details.objective;
+  if (!obj || obj.id === null || obj.nodes_marked.length === 0) return;
+  const message = reconcileGuidance(obj.id) + bindingSuffix(ctx.cwd, "command:objective-reconcile");
+  if (ctx.isIdle()) {
+    // The `/land` command path (idle): inject an immediate turn.
+    pi.sendUserMessage(message);
+  } else {
+    // The `land` tool path (streaming): deliver after the terminating land batch.
+    pi.sendUserMessage(message, { deliverAs: "followUp" });
+  }
+}
+
+const TOOL_GUIDELINES = [
+  "Call land only when the PR is approved and ready to merge; it squash-merges the PR (closing the plan issue) and sets pending-learn.",
+  "land operates on the active plan's worktree — it takes no arguments; the PR is discovered from the local plan-ref's branch.",
+];
+
+/** Register the warm door: the `land` terminating tool + the `/land` command twin. */
+export function registerLand(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "land",
+    label: "Land PR",
+    description:
+      "Merge the active plan's approved PR (squash, closing the plan issue) and set pending-learn. " +
+      "Terminating: ends the turn on land. Call only when the PR is ready to merge.",
+    promptSnippet: "Squash-merge the approved PR and set pending-learn (terminates the turn)",
+    promptGuidelines: TOOL_GUIDELINES,
+    executionMode: "sequential",
+    parameters: { type: "object", additionalProperties: false, properties: {} },
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+      const result = await landPr(pi, ctx);
+      driveReconcileAfterLand(pi, ctx, result.details);
+      return result;
+    },
+  });
+
+  pi.registerCommand("land", {
+    description: "Merge the active plan's PR and set pending-learn (submit → land).",
+    handler: async (_args, ctx) => {
+      const result = await landPr(pi, ctx);
+      // Failure already reported loudly via failFor (the single error surface) — success only.
+      if (result.details.ok) {
+        report(ctx, "land", "info", result.content[0]?.text ?? "land done");
+      }
+      driveReconcileAfterLand(pi, ctx, result.details);
+    },
+  });
+}

package/extension/doors/learn.ts

@@ -0,0 +1,235 @@
+// 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`).
+
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { bindingSuffix } from "../substrate/bindingDelivery.ts";
+import {
+  clearMarker,
+  hasMarker,
+  PENDING_LEARN,
+  type PlanRef,
+  readPlanRef,
+} from "../substrate/cache.ts";
+import {
+  booleanField,
+  type ColdJson,
+  objectField,
+  runColdDoor,
+  stringField,
+} from "../substrate/coldDoor.ts";
+import { render } from "../substrate/prompts.ts";
+import { failFor, ok, type Result } from "../substrate/result.ts";
+import { paramsOf, stringParam } from "../substrate/toolParams.ts";
+import { branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
+import { report } from "../surfaces/report.ts";
+import { planReadInstruction } from "./lifecycleGates.ts";
+
+/** The ok-arm fields. */
+export interface LearnOk {
+  was_pending: boolean;
+  captured: boolean;
+  /** `id` is the opaque string issue id (GitHub "42", Linear "ENG-123") — §8.21. */
+  learn_issue?: { id: string; url: string; existed: boolean };
+}
+
+export type LearnResult = Result<LearnOk>;
+
+/** The decoded `perk learn capture --json` payload slice the warm door consumes. */
+interface LearnCapturePayload {
+  learn_issue?: { id: string; url: string; existed: boolean };
+}
+
+/**
+ * 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
+ * `docs/learned/workflow/cold-door-client.md`). `learn_issue` is render-only — it feeds only the
+ * success message text and `details` — and the `success: true` envelope is the cold door's
+ * authoritative statement that the capture mutation completed and the on-disk `pending-learn`
+ * marker was already cleared. So any miss on the sub-object (absent key, a legacy `number` shape,
+ * mistyped fields — e.g. under CLI↔extension version skew) yields
+ * `{ learn_issue: undefined }`, never null: the warm report must survive an undecodable payload,
+ * and the `bad_output` arm is deliberately unreachable for this door. `pending_cleared` is
+ * unconsumed.
+ */
+function decodeLearnCapture(payload: ColdJson): LearnCapturePayload {
+  const issue = objectField(payload, "learn_issue");
+  if (issue === undefined) return { learn_issue: undefined };
+  const id = stringField(issue, "id");
+  const url = stringField(issue, "url");
+  const existed = booleanField(issue, "existed");
+  if (id === undefined || url === undefined || existed === undefined) {
+    return { learn_issue: undefined };
+  }
+  return { learn_issue: { id, url, existed } };
+}
+
+/** Clear `pending-learn` (idempotent — a no-op if it was not set). Reports whether it was set. */
+function clearPending(ctx: ExtensionContext): { wasPending: boolean } {
+  const wasPending = hasMarker(ctx.cwd, PENDING_LEARN);
+  clearMarker(ctx.cwd, PENDING_LEARN);
+  return { wasPending };
+}
+
+/**
+ * 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).
+ */
+export async function learnDone(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  summary?: string,
+): Promise<LearnResult> {
+  const trimmed = (summary ?? "").trim();
+
+  // No summary: the thin, graceful path — just clear the marker (no empty issue).
+  if (trimmed.length === 0) {
+    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.";
+    return ok(text, { was_pending: wasPending, captured: false }, { terminate: true });
+  }
+
+  const fail = failFor(ctx, "learn");
+
+  const r = await runColdDoor<LearnCapturePayload>(pi, ctx, ["learn", "capture", "--json"], {
+    label: "perk learn capture",
+    decode: decodeLearnCapture,
+    stdin: { flag: "--body", content: `${trimmed}\n`, filename: `learn-${Date.now()}.md` },
+  });
+  if (!r.ok) return fail(r.message, r.errorType);
+
+  // Mirror the marker-clear in-session (idempotent; the worker also cleared it on disk). Runs
+  // even when `learn_issue` is undecodable — a success envelope clears the marker.
+  const { wasPending } = clearPending(ctx);
+  const issue = r.data.learn_issue;
+  if (issue === undefined) {
+    return ok(
+      "Captured learnings; pending-learn cleared. (learn issue details undecodable — the perk " +
+        "CLI and the perk extension may be version-skewed.)",
+      { was_pending: wasPending, captured: true },
+      { terminate: true },
+    );
+  }
+  const verb = issue.existed ? "Found existing" : "Created";
+  return ok(
+    `${verb} learn issue #${issue.id}; pending-learn cleared.`,
+    { was_pending: wasPending, captured: true, learn_issue: issue },
+    { terminate: true },
+  );
+}
+
+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).",
+];
+
+/** Resolve the active plan-ref (worktree first, then the rebuilt workflow-state). */
+function activePlanRef(ctx: ExtensionContext): PlanRef | null {
+  const fromWorktree = readPlanRef(ctx.cwd);
+  if (fromWorktree) return fromWorktree;
+  try {
+    const branch = branchOf(ctx);
+    return (rebuildWorkflowState(branch).active_plan_ref as PlanRef | null) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Inject the learn-workflow guidance the model follows (the perk-learn skill pointer rides the
+ * skill-binding suffix — not hardcoded here). The wording lives in the canonical template
+ * `prompts/stages/learn.md`, rendered identically by both planes via the shared render seam
+ * (contracts.md §8.31); the github/linear/other/no-ref branching is the template conditional on
+ * `provider` (+ `pr_id` presence), and `read_cmd` is the node-2.1 plan-read instruction. Unified
+ * onto the cold `_learn_prompt` body — byte-identical to it for every provider arm (the four
+ * `learn-*` golden cases are the cross-plane parity proof). When no plan-ref is known, render the
+ * no-ref arm (learn can proceed without a ref — no dead-end null-guard).
+ */
+export function learnGuidance(planRef: PlanRef | null): string {
+  if (planRef === null) {
+    return render("stages/learn.md", { provider: "", pr_id: "", url: "", read_cmd: "" });
+  }
+  const read_cmd = planReadInstruction(planRef.provider, planRef.pr_id, planRef.url);
+  return render("stages/learn.md", {
+    provider: planRef.provider,
+    pr_id: planRef.pr_id,
+    url: planRef.url,
+    read_cmd,
+  });
+}
+
+/** Register the warm door: the `learn` terminating tool + the `/learn` command twin. */
+export function registerLearn(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "learn",
+    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.",
+    promptSnippet:
+      "Capture learnings (optional summary) and clear pending-learn (terminates the turn)",
+    promptGuidelines: TOOL_GUIDELINES,
+    executionMode: "sequential",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        summary: {
+          type: "string",
+          description: "Markdown learnings to capture in a perk:learn issue. Omit to only clear.",
+        },
+      },
+    },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      // Tool-boundary decode: absent → undefined (the marker-clear path); mistyped →
+      // strict-fail — never silently clear the pending-learn marker on uncertainty.
+      const p = paramsOf(params);
+      const summary = p === null ? undefined : stringParam(p, "summary");
+      if (summary === null) {
+        return failFor(ctx, "learn")("learn `summary` must be a string", "bad_input");
+      }
+      return learnDone(pi, ctx, summary);
+    },
+  });
+
+  pi.registerCommand("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.",
+    handler: async (args, ctx) => {
+      const trimmed = (args ?? "").trim();
+
+      // Explicit text (or `skip`): the existing learnDone path — capture verbatim / marker-clear.
+      if (trimmed.length > 0) {
+        const summary = trimmed === "skip" ? "" : args;
+        const result = await learnDone(pi, ctx, summary);
+        // Failure already reported loudly via failFor (the single error surface) — success only.
+        if (result.details.ok) {
+          report(ctx, "learn", "info", result.content[0]?.text ?? "learn done");
+        }
+        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).
+      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"));
+    },
+  });
+}

package/extension/doors/learnDocs.ts

@@ -0,0 +1,99 @@
+// hop-2 — the learned-docs plan factory's warm transition surface: the `/learn-docs` command.
+//
+// The warm twin of the `perk learn docs` cold door. It DELEGATES the gather to the Python plane
+// (`perk learn docs --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 docs 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 { render } from "../substrate/prompts.ts";
+import { report } from "../surfaces/report.ts";
+
+/** The decoded `perk learn docs --gather --json` payload slice the warm door consumes. */
+interface LearnDocsGatherPayload {
+  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. */
+function decodeGather(payload: ColdJson): LearnDocsGatherPayload | 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-docs` injects to start the factory loop (the perk-learn-docs
+ * skill pointer rides the skill-binding suffix — not hardcoded here). Pure + exported
+ * for offline tests.
+ */
+export function learnDocsGuidance(inboxPath: string, learnNumbers: string[]): string {
+  return render("stages/learn-docs.md", {
+    inbox_path: inboxPath,
+    num_list: learnNumbers.join(", "),
+  });
+}
+
+/** Register the warm learned-docs door: the `/learn-docs` command (no model tool). */
+export function registerLearnDocs(pi: ExtensionAPI): void {
+  pi.registerCommand("learn-docs", {
+    description:
+      "Start the learned-docs plan factory: gather open perk:learn issues into an inbox and author " +
+      "a docs/learned consolidation plan.",
+    handler: async (_args, ctx: ExtensionContext) => {
+      // Report-only door (no Result type): branch on `errorType` directly (the coldDoor header
+      // convention). A clean "nothing to consolidate" exits non-zero with
+      // error_type=no_learn_issues — the client's envelope-aware arm surfaces it gently.
+      const r = await runColdDoor<LearnDocsGatherPayload>(
+        pi,
+        ctx,
+        ["learn", "docs", "--gather", "--json"],
+        { label: "perk learn docs", decode: decodeGather },
+      );
+      if (!r.ok) {
+        if (r.errorType === "no_learn_issues") {
+          report(
+            ctx,
+            "learn-docs",
+            "warning",
+            "nothing to consolidate (no open perk:learn issues).",
+          );
+        } else {
+          report(ctx, "learn-docs", "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-docs invoked (headless) — gathered ${r.data.learn_numbers.length} ` +
+            `learn issue(s) into ${r.data.inbox_path}; run interactively to author the docs plan.`,
+        );
+        return;
+      }
+
+      report(ctx, "learn-docs", "info", `gathered ${r.data.learn_numbers.length} learn issue(s)`);
+      pi.sendUserMessage(
+        learnDocsGuidance(r.data.inbox_path, r.data.learn_numbers) +
+          bindingSuffix(ctx.cwd, "command:learn-docs"),
+      );
+    },
+  });
+}