@mgiles/perk 1.1.0 → 2.0.0

package/README.md

@@ -1,64 +1,89 @@
 # perk
 
-A Pi-native, plan-oriented engineering workflow: a Python `perk` CLI (the session
-*exterior*) plus a TypeScript Pi extension (the session *interior*).
+perk is a [Pi](https://pi.dev)-native workflow for plan-driven software engineering.
 
-> Inspired by `erk`, formely maintained by the team at [dagster](https://github.com/dagster-io/dagster)
+It combines a Python CLI that manages the **session exterior**, a TypeScript Pi extension
+that governs the **session interior**, and an **issue backend** for durable workflow state,
+GitHub by default. The workflow is organized around _planning_, _implementation_,
+_code review_, and _learning_.
 
-perk was built with perk.
+Workflow stages and surfaces can use perk’s built-in defaults or pluggable third-party
+extensions, such as [plannonator](https://github.com/backnotprop/plannotator) for plan
+review.
+
+perk is built for work that may be interrupted, resumed elsewhere, superseded, or moved
+across machines. Resumability, human feedback, and remote execution are not special cases;
+they are part of the core model.
+
+`perk` is inspired by `erk`, formerly maintained by the team at
+[Dagster](https://github.com/dagster-io/dagster).
 
 ## What perk is
 
-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**:
+perk's unit of work is a **plan**: a reviewed, durable description of a change,
+written before files are edited and saved as canonical workflow state. The core spine is
+`plan -> save -> implement -> submit -> address -> land -> learn`; `address` only happens
+when review feedback needs a response. Longer-running **objectives** can emit bounded plans
+into the same spine.
+
+The implementation is 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);
-- the **interior** — a TypeScript Pi extension that drives stage transitions and state
-  *inside* a running session.
+- **exterior** — the Python `perk` CLI, which scaffolds repos, manages worktrees,
+  mints run ids, and launches primed `pi` sessions;
+- **interior** — a TypeScript Pi extension, which owns in-session stage transitions,
+  tool gates, context, and warm `/...` commands.
 
-A language-neutral [`shared/`](shared/) contract (the stage registry + cross-plane specs)
-is the single source both planes read, hopefully staying in lockstep without codegen.
+Both planes read the language-neutral [`shared/`](shared/) registry and contracts directly.
+There is no codegen layer to drift.
+
+The operating model is deliberately simple: canonical state lives in GitHub by default
+(Linear is supported), `.perk/workflow/` is a local cache, and session state is throwaway.
+Cold doors launch fresh context from a shell (`perk implement`, `perk plan resume`); warm
+doors keep context inside a session (`/submit`, `/land`, `/learn`). `implement` and
+`address` can dispatch to CI; review, merge, and learning stay local.
 
 ## Quickstart
 
-perk targets any git repo. From the repo you want to wire:
+From the git repo you want to wire:
 
 ```bash
-uv tool install perk        # (or run from source — see Develop)
-perk init                   # scaffold/converge Pi wiring (idempotent; safe to re-run)
-perk doctor                 # report health; perk doctor --fix repairs drift
+uv tool install perk
+perk init
+perk doctor
+perk plan
 ```
 
-`perk init` requires a git repo + `git`, `gh`, `node ≥ 22`, `ast-grep`, and `pi` on PATH. GitHub auth
-is verified but never required (it is reported, never fatal).
+`perk init` is idempotent and safe to re-run. `perk doctor` reports health;
+`perk doctor --fix` repairs managed drift.
+
+You need a git repo plus `git`, `gh`, `node >= 22`, `pi`, and `uv`. `ast-grep` is preferred
+for structural search and reported when absent, but it is advisory. GitHub auth is verified
+and reported by init; it becomes required when you drive real plans, PRs, and merges.
 
 For the guided first run, follow
 [Get started with perk](docs/user-docs/tutorials/get-started.md).
 
 ## Documentation
 
-The operator-facing docs live under [`docs/user-docs/`](docs/user-docs/index.md), organized as:
+Operator docs live under [`docs/user-docs/`](docs/user-docs/index.md):
 
-- **[Tutorials](docs/user-docs/tutorials/index.md)** — learning-oriented lessons; start with
+- **[Tutorials](docs/user-docs/tutorials/index.md)** — learn by doing; start with
   [Get started with perk](docs/user-docs/tutorials/get-started.md).
-- **[How-to guides](docs/user-docs/how-to/index.md)** — goal-oriented recipes (resume a plan,
-  address review feedback, switch to Linear, attach a skill, …).
-- **[Reference](docs/user-docs/reference/index.md)** — the CLI surface, in-session commands &
-  tools, the objective roadmap model, configuration, and providers & backends.
-- **[Explanation](docs/user-docs/explanation/index.md)** — how perk thinks; headless/remote
-  maturity.
+- **[How-to guides](docs/user-docs/how-to/index.md)** — recipes for specific jobs:
+  resume a plan, address review feedback, switch to Linear, attach a skill, dispatch to CI.
+- **[Reference](docs/user-docs/reference/index.md)** — CLI commands, in-session commands
+  and tools, objectives, configuration, providers, backends, and schemas.
+- **[Explanation](docs/user-docs/explanation/index.md)** — the mental model: plans,
+  planes, state tiers, doors, and remote maturity.
 
-perk's internal research and planning record lives under [`docs/`](docs/index.md) and is for
-perk's own developers.
+Internal research, design notes, and durable learnings live under [`docs/`](docs/index.md).
 
 ## Layout
 
-- `perk/` — the Python CLI (the session exterior).
-- `extension/` — the TypeScript Pi extension (the session interior).
-- `shared/` — cross-plane contracts (the stage registry + specs), bundled into both build
-  artifacts.
-- `docs/` — research inputs, design notes, and durable learnings.
+- `perk/` — Python CLI, the session exterior.
+- `extension/` — TypeScript Pi extension, the session interior.
+- `shared/` — stage registry and cross-plane contracts.
+- `docs/` — operator docs, research, design notes, and learnings.
 
 ## Develop
 
@@ -72,19 +97,18 @@ Two pinned toolchains:
 With [`just`](https://github.com/casey/just):
 
 ```bash
-just setup        # uv sync + npm install + git hooks + install-cli (the `perk` CLI on PATH)
-just install-cli  # just the `perk` CLI on PATH (editable: tracks this clone)
-just fmt          # ruff format + biome format
-just lint         # ruff check + biome check
-just typecheck    # ty + tsc
-just test         # pytest + node:test (the regression gate)
-just ci           # setup + lint + typecheck + test
+just setup
+just install-cli
+just fmt
+just lint
+just typecheck
+just test
+just ci
 ```
 
-`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
-system/`.venv` ruff). Re-run `just hooks` after a fresh clone.
+`just setup` runs `uv sync`, `npm install`, `just hooks`, and `just install-cli`. The hook is
+managed by [prek](https://prek.j178.dev) and runs `ruff check` on staged Python. Re-run
+`just hooks` after a fresh clone if hooks are missing.
 
 Without `just`: `uv run …` for Python (`uv run perk init`, `uv run pytest`,
 `uv run ruff check perk tests`, `uv run ty check`) and `npm run …` for TypeScript

package/extension/adapters/planAdapterPlannotator.ts

@@ -7,7 +7,8 @@
 // INJECTION + BRIDGE ONLY: the `plan_review` TOOL lives in `extension/factories/planReview.ts`
 // (perk's backend-neutral review door); this module is the injection-only adapter shape. It owns
 // (1) the plannotator review-step authoring context (injected while the gate is active AND
-// plannotator is selected — TWO content flavors, one customType: the plan bridge context, or the
+// plannotator is selected — TWO content flavors, one customType, each once-only: branch-scan
+// dedup'd on the flavor's marker: the plan bridge context, or the
 // objective flavor when the stage is `objective-author`) and (2) the pure event-bus bridge
 // (`createPlannotatorBridge`) that planReview.ts dispatches to when plannotator is the
 // selected plan provider. The bridge speaks plannotator's published `plannotator:request` event
@@ -24,7 +25,8 @@
 // gate exit all live behind planReview.ts's seams; the injection's gate-active check reads the
 // persisted `perk:workflow-state.mode`, the gate's own state twin.
 //
-// EVENT ENVELOPE (pinned against `@plannotator/pi-extension@0.20.0`, `plannotator-events.ts`):
+// EVENT ENVELOPE (pinned against `@plannotator/pi-extension@0.20.0`, `plannotator-events.ts` —
+// verified unchanged through 0.22.0):
 //   request  — pi.events.emit("plannotator:request", { requestId, action: "plan-review",
 //              payload: { planContent, origin? }, respond })   // respond = in-payload callback
 //   handshake — respond({ status: "handled", result: { status: "pending", reviewId } })
@@ -37,8 +39,9 @@ import { OBJECTIVE_AUTHOR_STAGE } from "../factories/objectiveAuthor.ts";
 import { resolvedPlanProviderId } from "../factories/planMode.ts";
 // Type-only (erased at runtime — no cycle): the outcome vocabulary lives with the review door.
 import type { ReviewOutcome } from "../factories/planReview.ts";
+import { render } from "../substrate/prompts.ts";
 import { PLANNOTATOR_PLAN_PROVIDER_ID } from "../substrate/providers.ts";
-import { branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
+import { branchCarries, branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
 
 /** The plannotator plan-adapter bridge customType (distinct from planMode's `perk:plan-context`). */
 export const PLAN_ADAPTER_PLANNOTATOR_CONTEXT_TYPE = "perk:plan-adapter-plannotator";
@@ -61,21 +64,9 @@ function handshakeTimeoutMs(): number {
  * step. Prompting, NOT enforcement (perk's own gate is the read-only authority). Durable anchors
  * only — mirrors PLAN_AUTHORING_CONTEXT, which is also injected (perk's plan mode stays).
  */
-export const PLAN_ADAPTER_PLANNOTATOR_CONTEXT = `${PLAN_ADAPTER_PLANNOTATOR_MARKER}
-A Plannotator browser review surface is configured for plan authoring in this repo. Author the plan
-read-only exactly as the plan-authoring contract describes; then add one review step:
-
-- Keep the working draft current with plan_draft — the validated plan-draft artifact is what gets
-  reviewed AND auto-saved; the plan param is only a fallback for sessions that never wrote a draft.
-- When the plan is decision-complete, call the plan_review tool. The Plannotator browser UI opens
-  for the human reviewer.
-- If the review is DENIED: revise per the returned annotations/feedback, rewrite the working draft
-  with plan_draft, then call plan_review again.
-- If the review is APPROVED: the plan is auto-saved to GitHub and the session leaves read-only.
-  Do NOT re-dump the plan as a final message and do NOT tell the user to run /plan-save — relay
-  the save outcome (and any reviewer feedback) instead.
-- If plan_review reports it was skipped or no review surface is available: fall back to presenting
-  the complete plan to the user; the human runs /plan-save (the manual failsafe).`;
+export const PLAN_ADAPTER_PLANNOTATOR_CONTEXT = render("contexts/adapters/plannotator-plan.md", {
+  marker: PLAN_ADAPTER_PLANNOTATOR_MARKER,
+});
 
 /**
  * The objective flavor of the bridge prompt, injected in an
@@ -83,24 +74,10 @@ read-only exactly as the plan-authoring contract describes; then add one review
  * objective via the `objectiveApprovalSave` seam; `/objective-save` is the manual failsafe on
  * the skipped/unavailable arms.
  */
-export const OBJECTIVE_ADAPTER_PLANNOTATOR_CONTEXT = `${OBJECTIVE_ADAPTER_PLANNOTATOR_MARKER}
-A Plannotator browser review surface is configured for objective authoring in this repo. Author
-the objective read-only exactly as the objective-authoring contract describes; then add one
-review step:
-
-- Keep the working objective current with objective_draft — pass the FULL prose and the FULL
-  structured roadmap each call (it rewrites the whole draft); never hand-write roadmap YAML.
-- When the objective + roadmap are decision-complete, call the plan_review tool. The Plannotator
-  browser UI shows the RENDERED objective (the prose + a roadmap table) derived from the draft
-  artifact — never raw JSON.
-- If the review is DENIED: revise per the returned annotations/feedback, rewrite the working
-  draft with objective_draft, then call plan_review again.
-- If the review is APPROVED: the objective is auto-saved to GitHub and the session leaves
-  read-only — do NOT re-dump the objective as a final message and do NOT tell the user to run
-  /objective-save; relay the save outcome (and any reviewer feedback) instead.
-- If plan_review reports it was skipped or no review surface is available: present the complete
-  objective + structured roadmap to the user; the human runs /objective-save (the manual
-  failsafe).`;
+export const OBJECTIVE_ADAPTER_PLANNOTATOR_CONTEXT = render(
+  "contexts/adapters/plannotator-objective.md",
+  { marker: OBJECTIVE_ADAPTER_PLANNOTATOR_MARKER },
+);
 
 /** Whether the foreign `plannotator-plan` provider is the selected plan provider for `cwd`. */
 export function isPlannotatorPlanSelected(cwd: string): boolean {
@@ -226,12 +203,21 @@ export function registerPlanAdapterPlannotator(pi: ExtensionAPI): void {
   // `perk:workflow-state.mode` (the gate's state twin) — never the gate itself.
   pi.on("before_agent_start", async (_event, ctx) => {
     if (!isPlannotatorPlanSelected(ctx.cwd)) return;
-    const state = rebuildWorkflowState(branchOf(ctx));
+    const branch = branchOf(ctx);
+    const state = rebuildWorkflowState(branch);
     if (state.mode !== "read-only") return;
-    const content =
-      state.stage === OBJECTIVE_AUTHOR_STAGE
-        ? OBJECTIVE_ADAPTER_PLANNOTATOR_CONTEXT
-        : PLAN_ADAPTER_PLANNOTATOR_CONTEXT;
+    const objectiveFlavor = state.stage === OBJECTIVE_AUTHOR_STAGE;
+    const content = objectiveFlavor
+      ? OBJECTIVE_ADAPTER_PLANNOTATOR_CONTEXT
+      : PLAN_ADAPTER_PLANNOTATOR_CONTEXT;
+    // Once-only PER FLAVOR: the dedup key is the flavor's marker (not the shared customType), so
+    // a stage change still delivers the missing flavor while a prior copy of the other flavor
+    // sits on the branch. Injected customs persist, so a live copy suppresses re-injection;
+    // compaction dropping it makes the scan come up clean and the next turn re-injects.
+    const marker = objectiveFlavor
+      ? OBJECTIVE_ADAPTER_PLANNOTATOR_MARKER
+      : PLAN_ADAPTER_PLANNOTATOR_MARKER;
+    if (branchCarries(branch, marker)) return;
     return {
       message: {
         customType: PLAN_ADAPTER_PLANNOTATOR_CONTEXT_TYPE,

package/extension/adapters/planAdapterTombell.ts

@@ -8,7 +8,8 @@
 // change on the default path.
 //
 // WHAT IT DOES (and does NOT do):
-//   - It injects a hidden (`display:false`) `perk:plan-adapter-tombell` context that tells the model
+//   - It injects a hidden (`display:false`, once-only: branch-scan dedup'd on the marker)
+//     `perk:plan-adapter-tombell` context that tells the model
 //     the foreign `/plan` surface authors a FREE-FORM PROSE plan, and directs it through perk's
 //     review-first discipline: keep the draft current with `plan_draft`, then call
 //     `plan_review` — which (for any non-plannotator selection, tombell included) runs the
@@ -36,8 +37,14 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { OBJECTIVE_AUTHOR_STAGE } from "../factories/objectiveAuthor.ts";
 import { resolvedPlanProviderId } from "../factories/planMode.ts";
+import { render } from "../substrate/prompts.ts";
 import { TOMBELL_PLAN_PROVIDER_ID } from "../substrate/providers.ts";
-import { type BranchEntry, branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
+import {
+  type BranchEntry,
+  branchCarries,
+  branchOf,
+  rebuildWorkflowState,
+} from "../substrate/workflowState.ts";
 
 /** The tombell plan-adapter bridge customType (distinct from planMode's `perk:plan-context`). */
 export const PLAN_ADAPTER_TOMBELL_CONTEXT_TYPE = "perk:plan-adapter-tombell";
@@ -50,32 +57,9 @@ const PLAN_ADAPTER_TOMBELL_MARKER = "[PLAN ADAPTER: TOMBELL]";
  * engaged by the cold-door launch, is the read-only authority). Durable anchors only, no line
  * numbers.
  */
-export const PLAN_ADAPTER_TOMBELL_CONTEXT = `${PLAN_ADAPTER_TOMBELL_MARKER}
-You are authoring a plan through the @tombell/pi-plan \`/plan\` surface — a read-only exploration mode
-that produces a FREE-FORM PROSE plan (it emits no structured plan and no save tool of its own).
-
-Gather before you plan, then write the plan so an executor with zero prior context can implement it
-without guessing: anchor every change durably — function/class names, behavioral descriptions,
-structural locations — never line numbers, and resolve every open choice before you save.
-
-perk persists the plan to the provider-agnostic plan reference (cache.plan-ref); the objective/node
-linkage and any consumed-learn numbers are recovered automatically from the launch handoff — never
-try to write the plan reference yourself.
-
-- Keep the working draft current with the plan_draft tool — the validated plan-draft artifact is
-  what gets reviewed AND auto-saved.
-- When the plan is decision-complete, call the plan_review tool — the human reviews the draft in
-  perk's in-TUI editor review.
-- If the review is DENIED: revise per the feedback, rewrite the draft with plan_draft, then call
-  plan_review again.
-- If the review is APPROVED: the plan is auto-saved and the session leaves read-only. Relay the
-  save outcome — do NOT re-dump the plan as a final message and do NOT tell the user to run
-  /plan-save.
-- If plan_review reports it was skipped or unavailable, OR the plan_draft/plan_review tools are not
-  in your tool set (this plan surface restricts tools): write the COMPLETE final plan as your last
-  message and present it to the user — the human runs the /plan-save command when satisfied (it
-  prefers the validated draft artifact and falls back to scraping your latest message, so that
-  final message must be the clean, complete plan and nothing else).`;
+export const PLAN_ADAPTER_TOMBELL_CONTEXT = render("contexts/adapters/tombell-plan.md", {
+  marker: PLAN_ADAPTER_TOMBELL_MARKER,
+});
 
 /** Whether the foreign `tombell-plan` provider is the selected plan provider for `cwd`. */
 export function isTombellPlanSelected(cwd: string): boolean {
@@ -113,6 +97,9 @@ export function registerPlanAdapterTombell(pi: ExtensionAPI): void {
     const state = rebuildWorkflowState(branch);
     if (state.stage === OBJECTIVE_AUTHOR_STAGE) return;
     if (state.mode !== "read-only" && !isTombellPlanModeEnabled(branch)) return;
+    // Once-only: injected customs persist to the branch, so a live copy suppresses re-injection;
+    // compaction dropping it makes the scan come up clean and the next turn re-injects.
+    if (branchCarries(branch, PLAN_ADAPTER_TOMBELL_MARKER)) return;
     return {
       message: {
         customType: PLAN_ADAPTER_TOMBELL_CONTEXT_TYPE,

package/extension/adapters/todoAdapterJuicesharp.ts

@@ -11,7 +11,8 @@
 // behavior change on the default path.
 //
 // WHAT IT DOES (and does NOT do):
-//   - It injects a hidden (`display:false`) `perk:todo-adapter-juicesharp` context that tells the
+//   - It injects a hidden (`display:false`, once-only: branch-scan dedup'd on the marker)
+//     `perk:todo-adapter-juicesharp` context that tells the
 //     model the foreign `@juicesharp/rpiv-todo` checklist overlay is the sole progress surface here
 //     (perk's own checkpoints stepped aside) and directs it to carry perk's
 //     implement-progress DISCIPLINE onto that overlay: seed it from the plan body's `## Steps` and
@@ -29,8 +30,9 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { resolvedTodoProviderId } from "../checkpoints/checkpoints.ts";
+import { render } from "../substrate/prompts.ts";
 import { JUICESHARP_TODO_PROVIDER_ID } from "../substrate/providers.ts";
-import { branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
+import { branchCarries, branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
 
 /** The juicesharp todo-adapter bridge customType (distinct from checkpoints' `perk:checkpoint`). */
 export const TODO_ADAPTER_JUICESHARP_CONTEXT_TYPE = "perk:todo-adapter-juicesharp";
@@ -41,17 +43,9 @@ const TODO_ADAPTER_JUICESHARP_MARKER = "[TODO ADAPTER: JUICESHARP]";
  * overlay. Prompting, NOT enforcement (perk's checkpoint scanner is deferred under this selection).
  * Durable anchors only, no line numbers.
  */
-export const TODO_ADAPTER_JUICESHARP_CONTEXT = `${TODO_ADAPTER_JUICESHARP_MARKER}
-This implement session tracks progress through the \`@juicesharp/rpiv-todo\` checklist overlay — the
-selected todo provider (\`[providers] todo = "juicesharp-todo"\`). perk's own checkpoint surface has
-stepped aside (Node 3.1), so the foreign overlay is the sole progress surface here.
-
-Carry perk's implement-progress discipline onto that overlay: seed it from the plan body's
-\`## Steps\` numbered list — one checklist item per step, in order — then mark each item complete as
-you finish the corresponding step, the same gather-then-advance flow perk's checkpoints embody. Use
-the overlay's own controls to add and complete items; you do not need perk's \`[WIP:n]\`/\`[DONE:n]\`
-markers here (perk's checkpoint scanner is deferred under this selection). If the plan has no
-\`## Steps\` list, there is nothing to seed — let the overlay behave as its defaults suggest.`;
+export const TODO_ADAPTER_JUICESHARP_CONTEXT = render("contexts/adapters/juicesharp-todo.md", {
+  marker: TODO_ADAPTER_JUICESHARP_MARKER,
+});
 
 /** Whether the foreign `juicesharp-todo` provider is the selected todo provider for `cwd`. */
 export function isJuicesharpTodoSelected(cwd: string): boolean {
@@ -71,6 +65,9 @@ export function registerTodoAdapterJuicesharp(pi: ExtensionAPI): void {
     if (!isJuicesharpTodoSelected(ctx.cwd)) return;
     const branch = branchOf(ctx);
     if (rebuildWorkflowState(branch).active_plan_ref == null) return;
+    // Once-only: injected customs persist to the branch, so a live copy suppresses re-injection;
+    // compaction dropping it makes the scan come up clean and the next turn re-injects.
+    if (branchCarries(branch, TODO_ADAPTER_JUICESHARP_MARKER)) return;
     return {
       message: {
         customType: TODO_ADAPTER_JUICESHARP_CONTEXT_TYPE,

package/extension/checkpoints/checkpoints.ts

@@ -27,7 +27,6 @@
 // config-read error → treated as the reference → zero change on the default selection.
 
 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";
@@ -42,11 +41,14 @@ import {
   writeSessionArtifact,
 } from "../substrate/sessionData.ts";
 import type { BranchEntry } from "../substrate/workflowState.ts";
-import { branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
+import { branchCarries, branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
 import {
+  checkpointEntryRenderer,
   MARK_CHECKPOINTS,
   type PerkStatusHandle,
   progressLine,
+  registerTranscriptRenderer,
+  renderCoarsePlanLines,
   renderProgressLines,
   report,
   setStandingWidget,
@@ -67,13 +69,17 @@ export const STEPS_ARTIFACT_NAME = "plan-steps.json";
 /**
  * The resolved `[providers] todo` selection id for `cwd`, read fresh per-event (no static state —
  * the same per-event-read shape `resolvedPlanProviderId` uses in planMode.ts). Fail-safe to the
- * perk-checkpoints reference: any load/resolution failure (corrupt bundled set, etc.) returns the
- * reference id so perk's own checkpoints keep working — the default path is the hard guarantee.
+ * perk-checkpoints reference: any load/resolution failure returns the reference id so perk's own
+ * checkpoints keep working — the default path is the hard guarantee. The catch narrows to genuine
+ * file-read/parse failures (the resolver is per-seam fail-open) and is logged, never silent.
  */
 export function resolvedTodoProviderId(cwd: string): string {
   try {
     return resolveProviders(loadPerkConfig(cwd).providers, loadProviders()).todo.id;
-  } catch {
+  } catch (error) {
+    console.error(
+      `perk: todo provider resolution failed — falling back to ${PERK_CHECKPOINTS_PROVIDER_ID}: ${error}`,
+    );
     return PERK_CHECKPOINTS_PROVIDER_ID;
   }
 }
@@ -339,12 +345,7 @@ function renderStatus(
         ctx,
         WIDGET_SLOT_CHECKPOINTS,
         (_tui: unknown, theme: ThemeLike) => ({
-          render: (width: number) => [
-            truncateToWidth(
-              theme.fg("dim", `Plan #${coarse.planId}: prose plan — no \`## Steps\` checklist`),
-              width,
-            ),
-          ],
+          render: (width: number) => renderCoarsePlanLines(coarse.planId, theme, width),
           invalidate: () => {},
         }),
         { placement: "belowEditor" },
@@ -376,6 +377,12 @@ function renderStatus(
  * `session_start` AND `session_tree`; advances on `turn_end`; lists via `/checkpoints`.
  */
 export function registerCheckpoints(pi: ExtensionAPI, status: PerkStatusHandle): void {
+  // Transcript marker for `perk:checkpoint` snapshots (audit §2.3): renderer body in surfaces.ts,
+  // registration = wiring, feature-detect inside the seam (pre-0.80.4 hosts stay inert). No
+  // todo-provider deferral here: entries exist only when perk's checkpoints appended them, so
+  // rendering history stays correct under any later provider selection.
+  registerTranscriptRenderer(pi, CHECKPOINT_TYPE, checkpointEntryRenderer);
+
   pi.on("session_start", async (_event, ctx) => {
     try {
       // Todo-provider deferral: when a foreign `[providers] todo` is selected, step the progress
@@ -502,7 +509,7 @@ export function registerCheckpoints(pi: ExtensionAPI, status: PerkStatusHandle):
     try {
       if (!isPerkCheckpointsReferenceSelected(ctx.cwd)) return;
       const branch = branchOf(ctx);
-      if (branch.some((entry) => JSON.stringify(entry).includes(STEPS_CONTEXT_TYPE))) return;
+      if (branchCarries(branch, STEPS_CONTEXT_TYPE)) return;
       const state = rebuildCheckpoint(branch);
       if (isInert(state) || !isGeneratedState(ctx.cwd, state)) return;
       return {

package/extension/doors/address.ts

@@ -227,8 +227,8 @@ export async function resolveReviewThreads(
 
 const TOOL_GUIDELINES = [
   "Call resolve_review_threads only AFTER you have applied (and committed) fixes for the actionable items — it replies-then-resolves the threads you pass.",
-  "Pass threads as [{thread_id, comment?}] using the thread_id values from the perk.review-classifier child's structured output; the optional comment is posted as a reply before resolving.",
-  "Judgment and edits stay with you (the parent) — never delegate the fix; the spawned classifier is read-only and classification-only.",
+  "Pass resolve_review_threads `threads` as [{thread_id, comment?}] using the thread_id values from the perk.review-classifier child's structured output; the optional comment is posted as a reply before resolving.",
+  "Judgment and edits stay with you (the parent) — never delegate the fix; the classifier child that feeds resolve_review_threads is read-only and classification-only.",
 ];
 
 /** Resolve the active plan-ref (worktree first, then the rebuilt workflow-state). The converged
@@ -248,7 +248,7 @@ function activePlanRef(ctx: ExtensionContext): PlanRef | null {
 
 /** Inject the address-workflow guidance the model follows (the perk-address skill pointer is
  * delivered by the skill-binding suffix — not hardcoded here). When `model` is set, the
- * `perk.review-classifier` spawn carries an inline `model` override ([subagents] review-classifier);
+ * `perk.review-classifier` spawn carries an inline `model` override ([models.subagents] review-classifier);
  * otherwise the agent's frontmatter default is used.
  *
  * The wording lives in the shared canonical templates `prompts/stages/address/*` rendered via the
@@ -258,7 +258,7 @@ function activePlanRef(ctx: ExtensionContext): PlanRef | null {
  * `model_clause` render var. */
 export function addressGuidance(ref: PlanRef, preview: boolean, model?: string): string {
   const modelClause = model
-    ? `, passing \`model: "${model}"\` on that call (the configured [subagents] review-classifier model)`
+    ? `, passing \`model: "${model}"\` on that call (the configured [models.subagents] review-classifier model)`
     : "";
   const variables = {
     provider: ref.provider,

package/extension/doors/askUser.ts

@@ -120,22 +120,26 @@ export function decodeAskUserParams(params: unknown): { question: string; option
 }
 
 const TOOL_GUIDELINES = [
-  "Prefer this during planning to resolve genuine ambiguity rather than guessing.",
-  "Ask ONE focused question at a time, and wait for the answer before the next.",
-  "Provide `options` when the answer is a choice — a free-text escape is always added.",
-  "Explore the codebase first: if a question is answerable from the code, read it instead of asking.",
+  "Prefer ask_user_question during planning to resolve genuine ambiguity rather than guessing.",
+  "Ask ONE focused question per ask_user_question call, and wait for the answer before the next.",
+  "Provide ask_user_question `options` when the answer is a choice — a free-text escape is always added.",
+  "Explore the codebase before calling ask_user_question: if a question is answerable from the code, read it instead of asking.",
 ];
 
 /**
  * The resolved `[providers] askuser` selection id for `cwd`. Fail-safe to the perk-ask-user
- * reference: any load/resolution failure (corrupt bundled set, etc.) returns the reference id so
- * perk's own tool keeps registering — the default path is the hard guarantee. Mirror of
- * `resolvedPlanProviderId`.
+ * reference: any load/resolution failure returns the reference id so perk's own tool keeps
+ * registering — the default path is the hard guarantee. Mirror of `resolvedPlanProviderId`: the
+ * catch narrows to genuine file-read/parse failures (the resolver is per-seam fail-open) and is
+ * logged, never silent.
  */
 export function resolvedAskUserProviderId(cwd: string): string {
   try {
     return resolveProviders(loadPerkConfig(cwd).providers, loadProviders()).askuser.id;
-  } catch {
+  } catch (error) {
+    console.error(
+      `perk: askuser provider resolution failed — falling back to ${PERK_ASK_USER_PROVIDER_ID}: ${error}`,
+    );
     return PERK_ASK_USER_PROVIDER_ID;
   }
 }