@mgiles/perk 1.0.1

package/README.md

@@ -0,0 +1,105 @@
+# perk
+
+A Pi-native, plan-oriented engineering workflow — a Python `perk` CLI (the session
+*exterior*) plus a TypeScript Pi extension (the session *interior*).
+
+> Start at [`docs/user-docs/`](docs/user-docs/index.md).
+
+> Originally based on prior art `erk`, by the team at [dagster](https://github.com/dagster-io/dagster)
+
+## What perk is
+
+perk implements a plan-oriented engineering workflow (explore read-only → save a plan →
+implement on a branch → submit → land → learn) to [Pi](https://github.com/earendil-works),
+split across **two planes**:
+
+- 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.
+
+A language-neutral [`shared/`](shared/) contract (the stage registry + cross-plane specs)
+is the single source both planes read, so the two stay in lockstep without a codegen step.
+
+perk is built to **bootstrap its own development**: each phase leaves perk capable of
+driving the next, and perk's own repo is the first thing it scaffolds.
+
+## Quickstart
+
+perk targets any git repo. From the 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
+```
+
+`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).
+
+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
+the four [Divio](https://docs.divio.com/documentation-system/) quadrants:
+
+- **[Tutorials](docs/user-docs/tutorials/index.md)** — learning-oriented lessons; 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.
+
+perk's internal research and planning record lives under [`docs/`](docs/index.md) and is for
+perk's own developers.
+
+## 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.
+
+## Develop
+
+Two pinned toolchains:
+
+- **Python** — [uv](https://docs.astral.sh/uv/) (3.13, pinned in `.python-version`),
+  [ruff](https://docs.astral.sh/ruff/) (lint/format), [ty](https://docs.astral.sh/ty/) (types).
+- **TypeScript** — npm (Node ≥ 22, `.npmrc`), [Biome](https://biomejs.dev/) (lint/format),
+  `tsc` (types).
+
+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
+```
+
+After `just setup` (or `just install-cli`), call `perk` directly — no `uv run`. The install is
+**editable**, so a `git pull` reflects Python changes live; re-run `just install-cli` after a
+dependency change. It lands in uv's tool bin (`~/.local/bin`) — if `perk` isn't found, that dir
+is not on your `PATH`; run `uv tool update-shell` (then restart your shell). Remove it with
+`uv tool uninstall perk`.
+
+Releasing perk → see [docs/releasing.md](docs/releasing.md) (version SSOT, dual-plane runbook,
+the `validate-release-versions` tag gate).
+
+`just setup` also runs `just hooks` (`prek install`), wiring a [prek](https://prek.j178.dev)
+pre-commit hook that runs `ruff check` on staged Python (config in `prek.toml`; the ruff
+env is built by prek from the remote ruff-pre-commit repo, so it never depends on a
+system/`.venv` ruff). Re-run `just hooks` after a fresh clone.
+
+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
+(`npm run lint`, `npm run typecheck`).

package/extension/adapters/planAdapterPlannotator.ts

@@ -0,0 +1,269 @@
+// The SECOND 3rd-party plan adapter — and the first with the AUGMENT posture. A perk-owned shim
+// that enables `@plannotator/pi-extension` as a REAL, selectable plan provider: unlike the tombell
+// adapter (REPLACE posture — perk's plan surface fully vacates), plannotator AUGMENTS perk's plan
+// flow. perk's `/plan` mode, authoring injection, and read-only gate STAY (planMode skips only the
+// `--plan` flag + `Ctrl+Alt+P` shortcut — the two real registration collisions).
+//
+// 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
+// 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
+// API (in-process `pi.events` bus).
+//
+// INERT BY DEFAULT. The shim is ALWAYS registered in index.ts but the injection fires only when
+// the resolved `[providers] plan` selection is `plannotator-plan` (read fresh per-event, same
+// shape as planMode/planAdapterTombell). On any other selection the context handler only strips
+// its own stale marker — zero behavior change on the default path.
+//
+// INVARIANTS HELD: never calls `setActiveTools`, never registers a `tool_call` handler, never
+// restamps `cache.plan-ref.provider` (stays `"github"`). The adapter is INJECTION-ONLY again
+// (Invariant 1: composes, never owns) — the review tool, the `approvalSave` composition, and the
+// 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`):
+//   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 } })
+//             | respond({ status: "unavailable", error? }) | respond({ status: "error", error })
+//   decision — pi.events.on("plannotator:review-result", { reviewId, approved, feedback?, ... })
+
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+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 { PLANNOTATOR_PLAN_PROVIDER_ID } from "../substrate/providers.ts";
+import { 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";
+const PLAN_ADAPTER_PLANNOTATOR_MARKER = "[PLAN ADAPTER: PLANNOTATOR]";
+const OBJECTIVE_ADAPTER_PLANNOTATOR_MARKER = "[OBJECTIVE ADAPTER: PLANNOTATOR]";
+
+/**
+ * The handshake timeout for plannotator's immediate `respond` callback (mirrors plannotator's own
+ * `PLANNOTATOR_TIMEOUT_MS = 5_000`). Overridable for tests via PERK_PLANNOTATOR_HANDSHAKE_MS.
+ */
+export const PLANNOTATOR_HANDSHAKE_TIMEOUT_MS = 5_000;
+
+function handshakeTimeoutMs(): number {
+  const raw = Number(process.env.PERK_PLANNOTATOR_HANDSHAKE_MS ?? "");
+  return Number.isFinite(raw) && raw > 0 ? raw : PLANNOTATOR_HANDSHAKE_TIMEOUT_MS;
+}
+
+/**
+ * The augment-posture bridge prompt: perk's plan-authoring discipline plus the plannotator review
+ * 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).`;
+
+/**
+ * The objective flavor of the bridge prompt, injected in an
+ * `objective-author` session instead of the plan flavor. An APPROVED review auto-saves the
+ * 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).`;
+
+/** Whether the foreign `plannotator-plan` provider is the selected plan provider for `cwd`. */
+export function isPlannotatorPlanSelected(cwd: string): boolean {
+  return resolvedPlanProviderId(cwd) === PLANNOTATOR_PLAN_PROVIDER_ID;
+}
+
+// ------------------------------------------------------------------ the event-bus bridge core
+
+/** The minimal `pi.events` surface the bridge needs (mirrors pi's EventBus). */
+export interface PlannotatorBus {
+  emit(channel: string, data: unknown): void;
+  on(channel: string, handler: (data: unknown) => void): void;
+}
+
+/** Plannotator's immediate `respond` handshake payload (pinned envelope, see header). */
+interface HandshakeResponse {
+  status?: string;
+  error?: string;
+  result?: { status?: string; reviewId?: string };
+}
+
+/** The human decision arriving on `plannotator:review-result`. */
+interface ReviewDecision {
+  approved: boolean;
+  feedback?: string;
+}
+
+/**
+ * Create the plannotator bridge over an event bus: ONE persistent `plannotator:review-result`
+ * listener registered up front, resolving pending reviews from a Map keyed by reviewId (no
+ * dependence on an undocumented `pi.events.off`). Pure over the bus → unit-testable offline with a
+ * fake plannotator listener.
+ */
+export function createPlannotatorBridge(bus: PlannotatorBus): {
+  review(plan: string, signal?: AbortSignal): Promise<ReviewOutcome>;
+} {
+  const pending = new Map<string, (decision: ReviewDecision) => void>();
+
+  bus.on("plannotator:review-result", (data) => {
+    const d = data as { reviewId?: unknown; approved?: unknown; feedback?: unknown };
+    if (typeof d?.reviewId !== "string") return;
+    const resolve = pending.get(d.reviewId);
+    if (resolve === undefined) return;
+    pending.delete(d.reviewId);
+    resolve({
+      approved: d.approved === true,
+      feedback: typeof d.feedback === "string" && d.feedback.trim() ? d.feedback : undefined,
+    });
+  });
+
+  async function review(plan: string, signal?: AbortSignal): Promise<ReviewOutcome> {
+    if (signal?.aborted) return { status: "aborted" };
+
+    // 1. Emit the request and await the immediate `respond` handshake (bounded — fail-open).
+    const requestId = randomUUID();
+    let respondResolve: (response: HandshakeResponse) => void = () => {};
+    const handshake = new Promise<HandshakeResponse | "timeout">((resolve) => {
+      respondResolve = resolve;
+    });
+    const timer = setTimeout(() => respondResolve("timeout" as never), handshakeTimeoutMs());
+    bus.emit("plannotator:request", {
+      requestId,
+      action: "plan-review",
+      payload: { planContent: plan, origin: "perk" },
+      respond: (response: unknown) => respondResolve(response as HandshakeResponse),
+    });
+    const response = await handshake;
+    clearTimeout(timer);
+
+    if (response === "timeout") {
+      return {
+        status: "unavailable",
+        warning: "plannotator did not respond to the review request (handshake timeout)",
+      };
+    }
+    if (response?.status !== "handled") {
+      const detail = response?.error ? `: ${response.error}` : "";
+      return {
+        status: "unavailable",
+        warning: `plannotator reported ${response?.status ?? "an invalid response"}${detail}`,
+      };
+    }
+    const reviewId = response.result?.reviewId;
+    if (response.result?.status !== "pending" || typeof reviewId !== "string") {
+      return {
+        status: "unavailable",
+        warning: "plannotator handshake returned no pending reviewId",
+      };
+    }
+
+    // 2. Await the human decision (no timeout — the reviewer takes as long as they take), but
+    //    honor a turn abort so an interrupted session never leaks a wedged promise.
+    return await new Promise<ReviewOutcome>((resolve) => {
+      const onAbort = (): void => {
+        pending.delete(reviewId);
+        resolve({ status: "aborted" });
+      };
+      pending.set(reviewId, (decision) => {
+        signal?.removeEventListener("abort", onAbort);
+        resolve({ status: "completed", reviewId, ...decision });
+      });
+      signal?.addEventListener("abort", onAbort, { once: true });
+    });
+  }
+
+  return { review };
+}
+
+// ----------------------------------------------------------------------------- registration
+
+/**
+ * Register the plannotator plan adapter: the augment-posture authoring-context injection, inert
+ * unless `[providers] plan = "plannotator-plan"`. INJECTION-ONLY (Invariant 1: composes, never
+ * owns) — the `plan_review` tool lives in planReview.ts (the backend-neutral review door), which
+ * dispatches to this module's bridge when plannotator is selected; the adapter itself never
+ * arbitrates tools and needs no gating.
+ */
+export function registerPlanAdapterPlannotator(pi: ExtensionAPI): void {
+  // Inject the bridge context while the read-only gate is active AND plannotator is selected.
+  // Two content flavors, one customType: an objective-author session (also read-only) gets the
+  // objective flavor (the review surface renders the objective draft); any other
+  // gated stage gets the plan flavor. The gate-active check reads the persisted
+  // `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));
+    if (state.mode !== "read-only") return;
+    const content =
+      state.stage === OBJECTIVE_AUTHOR_STAGE
+        ? OBJECTIVE_ADAPTER_PLANNOTATOR_CONTEXT
+        : PLAN_ADAPTER_PLANNOTATOR_CONTEXT;
+    return {
+      message: {
+        customType: PLAN_ADAPTER_PLANNOTATOR_CONTEXT_TYPE,
+        content,
+        display: false,
+      },
+    };
+  });
+
+  // Strip the stale bridge markers (BOTH flavors) from context when plannotator-plan is no
+  // longer selected (same hygiene as the tombell shim), so they never linger across a deselect.
+  const hasMarker = (text: string): boolean =>
+    text.includes(PLAN_ADAPTER_PLANNOTATOR_MARKER) ||
+    text.includes(OBJECTIVE_ADAPTER_PLANNOTATOR_MARKER);
+  pi.on("context", async (event, ctx) => {
+    if (isPlannotatorPlanSelected(ctx.cwd)) return;
+    return {
+      messages: event.messages.filter((m) => {
+        const msg = m as { customType?: string; role?: string; content?: unknown };
+        if (msg.customType === PLAN_ADAPTER_PLANNOTATOR_CONTEXT_TYPE) return false;
+        if (msg.role !== "user") return true;
+        const content = msg.content;
+        if (typeof content === "string") return !hasMarker(content);
+        if (Array.isArray(content)) {
+          return !content.some(
+            (c) =>
+              (c as { type?: string; text?: string }).type === "text" &&
+              hasMarker((c as { text?: string }).text ?? ""),
+          );
+        }
+        return true;
+      }),
+    };
+  });
+}

package/extension/adapters/planAdapterTombell.ts

@@ -0,0 +1,147 @@
+// The FIRST 3rd-party plan adapter. A perk-owned, injection-only bridge that re-enables
+// `@tombell/pi-plan` as a REAL, selectable plan provider: it bridges that package's free-form prose
+// `/plan` surface to perk's canonical produced contract (`plan_save` → `cache.plan-ref`).
+//
+// INERT BY DEFAULT. This shim is ALWAYS registered in index.ts but does nothing unless the resolved
+// `[providers] plan` selection is `tombell-plan` (read fresh per-event, same shape as planMode). On
+// any non-tombell selection it injects nothing and only strips its own stale marker — zero behavior
+// 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
+//     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
+//     first-party in-TUI editor review, and whose APPROVED outcome auto-saves via the
+//     `approvalSave` seam. The injection is CONDITIONED: it fires only when perk's read-only gate
+//     is active (per the persisted `perk:workflow-state.mode`) OR tombell's own persisted
+//     `plan-mode-state` entry says plan mode is enabled — never in an objective-author session
+//     (objectiveAuthor.ts owns that authoring context).
+//   - The present + `/plan-save` flow is the explicit FAIL-OPEN fallback, not the primary path:
+//     it applies when the review reports skipped/unavailable, or when `@tombell/pi-plan`'s own
+//     interactive `/plan` `setActiveTools` restriction hides `plan_draft`/`plan_review` from the
+//     tool set. `/plan-save` prefers the validated draft artifact and falls back to the
+//     `extractPlanMarkdown` transcript scrape (planSave.ts) — no new save machinery; the shim
+//     only directs flow.
+//   - It does NOT own, replace, or duplicate the read-only gate (Invariant 1) and NEVER calls
+//     `setActiveTools` / registers a `tool_call` handler. The read-only tier during foreign planning
+//     comes from (a) perk's gate, already engaged by the cold-door launch (session_start →
+//     syncFromState(handoff.mode=read-only)), and (b) the foreign package's own self-enforcement for
+//     ad-hoc interactive `pi --plan`. The shim is purely a prompting bridge.
+//   - It does NOT restamp `cache.plan-ref.provider` — a tombell-authored prose plan lands with
+//     `provider="github"` exactly like a perk-authored plan (the authoring-provider id lives only in
+//     the `[providers] plan` selection; `provider` is the issue storage backend). All downstream
+//     stages bind only to the provider-agnostic plan-ref and are unchanged.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { OBJECTIVE_AUTHOR_STAGE } from "../factories/objectiveAuthor.ts";
+import { resolvedPlanProviderId } from "../factories/planMode.ts";
+import { TOMBELL_PLAN_PROVIDER_ID } from "../substrate/providers.ts";
+import { type BranchEntry, 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";
+const PLAN_ADAPTER_TOMBELL_MARKER = "[PLAN ADAPTER: TOMBELL]";
+
+/**
+ * The bridge prompt: directs the foreign free-form prose `/plan` surface into perk's review-first
+ * discipline (mirrors PLAN_AUTHORING_CONTEXT's review-first ending), with the present +
+ * `/plan-save` flow as the explicit fail-open fallback. Prompting, NOT enforcement (perk's gate,
+ * 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).`;
+
+/** Whether the foreign `tombell-plan` provider is the selected plan provider for `cwd`. */
+export function isTombellPlanSelected(cwd: string): boolean {
+  return resolvedPlanProviderId(cwd) === TOMBELL_PLAN_PROVIDER_ID;
+}
+
+/**
+ * Whether @tombell/pi-plan's own plan mode is enabled, per the latest `plan-mode-state` custom
+ * entry on the branch (the package's persisted state twin — it writes one per toggle via
+ * `pi.appendEntry`, latest wins, mirroring its own `session_start` rebuild). Defensive: any
+ * missing / malformed entry ⇒ false.
+ */
+export function isTombellPlanModeEnabled(branch: readonly BranchEntry[]): boolean {
+  for (let i = branch.length - 1; i >= 0; i--) {
+    const entry = branch[i];
+    if (entry?.type !== "custom" || entry.customType !== "plan-mode-state") continue;
+    return entry.data?.enabled === true;
+  }
+  return false;
+}
+
+/**
+ * Register the tombell plan adapter: an injection-only bridge, inert unless `[providers] plan =
+ * "tombell-plan"`. It NEVER touches tool gating / setActiveTools (Invariant 1) and never throws.
+ */
+export function registerPlanAdapterTombell(pi: ExtensionAPI): void {
+  // Inject the bridge context while the foreign tombell-plan provider is selected AND a plan
+  // authoring mode is on — perk's read-only gate (per the persisted `perk:workflow-state.mode`,
+  // the gate's state twin — never the gate object) OR tombell's own persisted `plan-mode-state`
+  // entry (the ad-hoc interactive `/plan` arm). Objective-author sessions are excepted
+  // (objectiveAuthor owns that session; mirrors the plannotator adapter's recipe).
+  pi.on("before_agent_start", async (_event, ctx) => {
+    if (!isTombellPlanSelected(ctx.cwd)) return;
+    const branch = branchOf(ctx);
+    const state = rebuildWorkflowState(branch);
+    if (state.stage === OBJECTIVE_AUTHOR_STAGE) return;
+    if (state.mode !== "read-only" && !isTombellPlanModeEnabled(branch)) return;
+    return {
+      message: {
+        customType: PLAN_ADAPTER_TOMBELL_CONTEXT_TYPE,
+        content: PLAN_ADAPTER_TOMBELL_CONTEXT,
+        display: false,
+      },
+    };
+  });
+
+  // Strip the stale bridge marker from context when tombell-plan is no longer selected (same
+  // hygiene planMode/objectiveAuthor/toolGating apply), so it never lingers across a deselect.
+  pi.on("context", async (event, ctx) => {
+    if (isTombellPlanSelected(ctx.cwd)) return;
+    return {
+      messages: event.messages.filter((m) => {
+        const msg = m as { customType?: string; role?: string; content?: unknown };
+        if (msg.customType === PLAN_ADAPTER_TOMBELL_CONTEXT_TYPE) return false;
+        if (msg.role !== "user") return true;
+        const content = msg.content;
+        if (typeof content === "string") return !content.includes(PLAN_ADAPTER_TOMBELL_MARKER);
+        if (Array.isArray(content)) {
+          return !content.some(
+            (c) =>
+              (c as { type?: string; text?: string }).type === "text" &&
+              ((c as { text?: string }).text ?? "").includes(PLAN_ADAPTER_TOMBELL_MARKER),
+          );
+        }
+        return true;
+      }),
+    };
+  });
+}

package/extension/adapters/todoAdapterJuicesharp.ts

@@ -0,0 +1,105 @@
+// The FIRST 3rd-party todo adapter. A perk-owned, injection-only bridge that re-enables
+// `@juicesharp/rpiv-todo` as a REAL, selectable todo provider: it carries perk's implement-progress
+// discipline onto that package's checklist-overlay surface (the todo-seam mirror of
+// planAdapterTombell, which bridges the plan seam).
+//
+// INERT BY DEFAULT. This shim is ALWAYS registered in index.ts but does nothing unless the resolved
+// `[providers] todo` selection is `juicesharp-todo` (read fresh per-event via the same
+// `resolvedTodoProviderId` the reference checkpoints provider uses) AND the session is an active
+// workflow (`active_plan_ref != null`, the same gate the reference checkpoints provider seeds on).
+// On any non-juicesharp selection it injects nothing and only strips its own stale marker — zero
+// 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
+//     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
+//     mark each item complete in order — the same gather-then-advance flow perk's checkpoints embody.
+//   - It does NOT own, replace, or duplicate the read-only gate (Invariant 1) and NEVER calls
+//     `setActiveTools` / registers a `tool_call` handler (the todo seam composes no shared primitive).
+//   - It does NOT write perk's `perk:checkpoint` entry and does NOT revive perk's deferred marker
+//     scanner (Correction 2): that entry is a transient TS-only progress overlay nothing downstream
+//     consumes, and perk's render + scanner are already deferred. Re-populating it would
+//     be dead duplication — the foreign overlay is the sole, uncontested progress surface.
+//   - It adds NO registration-time vacating (Correction 1): unlike the plan seam (where perk and the
+//     foreign package both register `/plan`, forcing Pi to suffix the duplicate), the todo seam has
+//     no command-name collision — perk registers `/checkpoints`; the foreign overlay registers its
+//     own differently-named command(s) — so the runtime deferral is already sufficient.
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { resolvedTodoProviderId } from "../checkpoints/checkpoints.ts";
+import { JUICESHARP_TODO_PROVIDER_ID } from "../substrate/providers.ts";
+import { 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";
+const TODO_ADAPTER_JUICESHARP_MARKER = "[TODO ADAPTER: JUICESHARP]";
+
+/**
+ * The bridge prompt: carries perk's implement-progress discipline onto the foreign checklist
+ * 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.`;
+
+/** Whether the foreign `juicesharp-todo` provider is the selected todo provider for `cwd`. */
+export function isJuicesharpTodoSelected(cwd: string): boolean {
+  return resolvedTodoProviderId(cwd) === JUICESHARP_TODO_PROVIDER_ID;
+}
+
+/**
+ * Register the juicesharp todo adapter: an injection-only bridge, inert unless `[providers] todo =
+ * "juicesharp-todo"` AND the session is an active workflow. It NEVER touches tool gating /
+ * setActiveTools (Invariant 1) and never throws.
+ */
+export function registerTodoAdapterJuicesharp(pi: ExtensionAPI): void {
+  // Inject the bridge context while the foreign juicesharp-todo provider is selected AND a workflow
+  // is active (active_plan_ref != null) — the same active-workflow scope the reference checkpoints
+  // provider seeds on, so the bridge never reaches planning/objective sessions (display:false).
+  pi.on("before_agent_start", async (_event, ctx) => {
+    if (!isJuicesharpTodoSelected(ctx.cwd)) return;
+    const branch = branchOf(ctx);
+    if (rebuildWorkflowState(branch).active_plan_ref == null) return;
+    return {
+      message: {
+        customType: TODO_ADAPTER_JUICESHARP_CONTEXT_TYPE,
+        content: TODO_ADAPTER_JUICESHARP_CONTEXT,
+        display: false,
+      },
+    };
+  });
+
+  // Strip the stale bridge marker from context when juicesharp-todo is no longer selected (same
+  // hygiene the sibling adapters apply), so it never lingers across a deselect.
+  pi.on("context", async (event, ctx) => {
+    if (isJuicesharpTodoSelected(ctx.cwd)) return;
+    return {
+      messages: event.messages.filter((m) => {
+        const msg = m as { customType?: string; role?: string; content?: unknown };
+        if (msg.customType === TODO_ADAPTER_JUICESHARP_CONTEXT_TYPE) return false;
+        if (msg.role !== "user") return true;
+        const content = msg.content;
+        if (typeof content === "string") return !content.includes(TODO_ADAPTER_JUICESHARP_MARKER);
+        if (Array.isArray(content)) {
+          return !content.some(
+            (c) =>
+              (c as { type?: string; text?: string }).type === "text" &&
+              ((c as { text?: string }).text ?? "").includes(TODO_ADAPTER_JUICESHARP_MARKER),
+          );
+        }
+        return true;
+      }),
+    };
+  });
+}