@mgiles/perk 3.1.0 → 3.3.0

package/extension/factories/gistDraft.ts

@@ -1,265 +0,0 @@
-// The `gist_draft` file tool: the third member of the draft carve-out family
-// (planDraft.ts, objectiveDraft.ts) — the gist twin, minus the roadmap.
-//
-// Carve-out doctrine: the tool takes NO path/name parameter — the artifact name is the fixed
-// constant `GIST_DRAFT_ARTIFACT` and the path is derived exclusively through the session-data
-// accessor seam (`writeSessionArtifact`, sessionData.ts), so the only bytes it can ever write are
-// the one working-gist artifact in the current run's data dir (gitignored scratch). Allowlisting
-// its name in `READ_ONLY_TOOLS` (toolGating.ts) is therefore safe: the read-only invariant (the
-// worktree stays untouched) holds, and the gate's `tool_call` edit/write/bash blocking logic is
-// UNCHANGED. Full rewrite per call, non-terminating; NOT a save — `gist_save`/`/gist-save` still
-// persist the gist to the issue backend.
-//
-// Format doctrine: JSON is the storage/transport format, NEVER the human review surface. The
-// artifact carries `{schema_version, title?, scope?, prose}` — deliberately light: a gist is a
-// problem-space statement of intent with no structured roadmap (contracts.md §8.41). The review
-// surface reads the draft via `readGistDraft` (over `readSessionArtifact` — digest-validated,
-// fail-open) and renders markdown via `renderGistDraft` (title + a `Scope:` line + the prose) —
-// never raw JSON.
-//
-// Vocabulary ownership: this module owns the shared draft/save param vocabulary
-// (`GistSaveParams`, `decodeGistSaveParams`, `GIST_SCOPES`) — gistDraft is the LEAF (mirroring
-// planDraft←planSave's direction); gistSave.ts consumes it, so it may value-import
-// `readGistDraft` cycle-free for the approval→save orchestration.
-//
-// Imports stay node builtins + sibling seams (sessionData.ts, result.ts) so the module loads
-// under `node --test`; no manual `scratch`/`runs` path segments (cacheGuard.test.ts).
-
-import { relative } from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { failFor, ok, type Result } from "../substrate/result.ts";
-import {
-  activeSessionRunId,
-  digestSessionData,
-  readSessionArtifact,
-  type SessionDataCtx,
-  writeSessionArtifact,
-} from "../substrate/sessionData.ts";
-import { paramsOf, stringParam } from "../substrate/toolParams.ts";
-import type { EntrySink } from "../substrate/workflowState.ts";
-import type { ReportTarget } from "../surfaces/report.ts";
-
-/** The gist consumption tiers (`scope` — contracts.md §8.41). */
-export const GIST_SCOPES = ["plan", "objective"] as const;
-
-export type GistScope = (typeof GIST_SCOPES)[number];
-
-/** The decoded `gist_save` tool params (shared with `gist_draft`). */
-export interface GistSaveParams {
-  prose: string;
-  title?: string;
-  scope?: GistScope;
-}
-
-/**
- * Decode unknown `gist_save` tool-call params (the tool-boundary seam). `prose` absent decodes
- * to `""` (so `saveGist`'s "no gist prose to save" `invalid_input` arm keeps owning that
- * message) but present-but-mistyped → null (strict-fail); a present `scope` outside the enum is
- * likewise a strict-fail (the schema already declares the enum — a bad value means a malformed
- * call, never a silent default).
- */
-export function decodeGistSaveParams(params: unknown): GistSaveParams | null {
-  const p = paramsOf(params);
-  if (p === null) return null;
-  const prose = stringParam(p, "prose");
-  const title = stringParam(p, "title");
-  const scope = stringParam(p, "scope");
-  if (prose === null || title === null || scope === null) return null;
-  if (scope !== undefined && !(GIST_SCOPES as readonly string[]).includes(scope)) return null;
-  return { prose: prose ?? "", title, scope: scope as GistScope | undefined };
-}
-
-/** The fixed working-gist artifact name (one JSON file: the prose + the optional scope hint). */
-export const GIST_DRAFT_ARTIFACT = "gist-draft.json";
-
-/** The ok-arm details — provenance-consistent with the recorded `session_artifacts` pointer. */
-export interface GistDraftOk {
-  name: string;
-  path: string;
-  digest: string;
-  bytes: number;
-  run_id: string;
-}
-
-export type GistDraftResult = Result<GistDraftOk>;
-
-/**
- * The core both the tool handler and tests call: serialize the working gist (prose + the
- * optional title/scope) as one JSON artifact and write it through the accessor seam (file +
- * `session_artifacts` provenance pointer). Soft result, never throws — failure taxonomy: empty
- * prose → `invalid_input`; no session run_id → `no_run_id`; file-or-pointer write failure →
- * `write_failed` (the seam already warned).
- */
-export function writeGistDraft(
-  sink: EntrySink,
-  ctx: SessionDataCtx & ReportTarget,
-  opts: { prose: string; title?: string; scope?: GistScope },
-): GistDraftResult {
-  const fail = failFor(ctx, "gist-draft");
-
-  if (!opts.prose.trim()) {
-    return fail("no gist prose to write (pass the full working draft)", "invalid_input");
-  }
-
-  const runId = activeSessionRunId(ctx);
-  if (runId === null) {
-    return fail("session has no run_id — cannot write the gist-draft artifact", "no_run_id");
-  }
-
-  // Deterministic key order via the explicit literal; `title`/`scope` are omitted when blank.
-  const title = opts.title?.trim();
-  const payload = {
-    schema_version: 1,
-    ...(title ? { title } : {}),
-    ...(opts.scope ? { scope: opts.scope } : {}),
-    prose: opts.prose,
-  };
-  const content = `${JSON.stringify(payload, null, 2)}\n`;
-
-  const written = writeSessionArtifact(sink, ctx, GIST_DRAFT_ARTIFACT, content);
-  if (written === null) {
-    return fail(
-      `could not write the ${GIST_DRAFT_ARTIFACT} artifact (see warnings)`,
-      "write_failed",
-    );
-  }
-
-  // Derive digest/relative path consistently with the pointer the seam recorded.
-  const digest = digestSessionData(content);
-  const relPath = relative(ctx.cwd, written);
-  return ok(`Gist draft written → ${relPath} (${digest})`, {
-    name: GIST_DRAFT_ARTIFACT,
-    path: relPath,
-    digest,
-    bytes: Buffer.byteLength(content, "utf8"),
-    run_id: runId,
-  });
-}
-
-// ------------------------------------------------------------------- the reader + the renderer
-
-/** The validated working-gist draft shape consumers receive from `readGistDraft`. */
-export interface GistDraft {
-  title?: string;
-  scope?: GistScope;
-  prose: string;
-}
-
-/**
- * Read + validate the working-gist draft artifact. Fail-open `null` everywhere (mirroring
- * `readSessionArtifact`'s loud tier): no pointer/file/digest → `null` (the seam already spoke);
- * malformed JSON, a non-object payload, an unsupported `schema_version`, or blank prose → a
- * stderr warning + `null`. `title` is kept only when a non-blank string; `scope` only when a
- * member of the enum (an unknown scope degrades to absent, never poisons the draft). Never
- * throws.
- */
-export function readGistDraft(ctx: SessionDataCtx): GistDraft | null {
-  const artifact = readSessionArtifact(ctx, GIST_DRAFT_ARTIFACT);
-  if (artifact === null) return null;
-
-  const refuse = (why: string): null => {
-    console.error(`perk: warning: ${GIST_DRAFT_ARTIFACT} ${why} — refusing the draft`);
-    return null;
-  };
-  let parsed: unknown;
-  try {
-    parsed = JSON.parse(artifact.content);
-  } catch {
-    return refuse("is not valid JSON");
-  }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    return refuse("is not a JSON object");
-  }
-  const payload = parsed as Record<string, unknown>;
-  if (payload.schema_version !== 1) {
-    return refuse(`has an unsupported schema_version (${JSON.stringify(payload.schema_version)})`);
-  }
-  const prose = payload.prose;
-  if (typeof prose !== "string" || !prose.trim()) {
-    return refuse("has no prose");
-  }
-  const title =
-    typeof payload.title === "string" && payload.title.trim() ? payload.title : undefined;
-  const scope =
-    typeof payload.scope === "string" && (GIST_SCOPES as readonly string[]).includes(payload.scope)
-      ? (payload.scope as GistScope)
-      : undefined;
-  return {
-    ...(title !== undefined ? { title } : {}),
-    ...(scope !== undefined ? { scope } : {}),
-    prose,
-  };
-}
-
-/**
- * Render the draft as the markdown review surface (JSON is storage/transport only — contracts
- * §8.1): the optional `# title` heading, a `Scope:` line when the hint is set, and the prose
- * verbatim. Pure; never throws.
- */
-export function renderGistDraft(draft: GistDraft): string {
-  let out = "";
-  if (draft.title) out += `# ${draft.title}\n\n`;
-  if (draft.scope) out += `Scope: ${draft.scope}\n\n`;
-  return out + draft.prose;
-}
-
-const TOOL_GUIDELINES = [
-  "Call gist_draft to persist the current working gist as you author or revise it; pass the FULL prose each time (it rewrites the whole draft).",
-  "gist_draft never saves to the issue backend and never ends the turn — gist_save//gist-save remain the canonical save surface.",
-  "Pass gist_draft's `scope` only once the consumption tier is settled: `plan` for plan-sized intent, `objective` for objective-sized intent.",
-];
-
-/** Register the `gist_draft` tool (the carve-out producer; interior-only). */
-export function registerGistDraft(pi: ExtensionAPI): void {
-  pi.registerTool({
-    name: "gist_draft",
-    label: "Gist draft",
-    description:
-      "Write (or overwrite) the working gist draft — the statement-of-intent prose + an " +
-      "optional scope hint — to the session data dir and record its provenance pointer. The " +
-      "only sanctioned write surface while read-only. NOT a save — gist_save//gist-save still " +
-      "persist the gist to the issue backend.",
-    promptSnippet:
-      "Persist the working gist draft (statement-of-intent prose) to the session data dir (full rewrite)",
-    promptGuidelines: TOOL_GUIDELINES,
-    executionMode: "sequential",
-    parameters: {
-      type: "object",
-      additionalProperties: false,
-      required: ["prose"],
-      properties: {
-        prose: {
-          type: "string",
-          description:
-            "The gist prose (the problem-space intent: what we want, why it matters, what " +
-            "bounds it, and any high-level solution leanings — no implementation steps).",
-        },
-        title: {
-          type: "string",
-          description: "Optional gist title (defaults to the prose's first heading).",
-        },
-        scope: {
-          type: "string",
-          enum: [...GIST_SCOPES],
-          description:
-            "Optional consumption tier: plan (plan-sized intent) or objective (objective-sized).",
-        },
-      },
-    },
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      // The shared param contract: the same decode as `gist_save`, so the two cannot drift.
-      const decoded = decodeGistSaveParams(params);
-      if (decoded === null) {
-        return failFor(
-          ctx,
-          "gist-draft",
-          "gist_draft",
-        )(
-          "gist_draft needs { prose: string, scope?: plan|objective } per the tool schema",
-          "bad_input",
-        );
-      }
-      return writeGistDraft(pi, ctx, decoded);
-    },
-  });
-}

package/extension/factories/gistSave.ts

@@ -1,251 +0,0 @@
-// The warm `gist_save` door, the gist mirror of objectiveSave.ts. The in-session twin of the
-// Python cold door (`perk gist create`): a deterministic, terminating tool + command that WRAP
-// the existing storage — they do NOT reimplement the backend write. `saveGist()` delegates to
-// `perk gist create --json` via the shared cold-door client (`runColdDoor`, the prose rides the
-// run-scratch stdin channel). Unlike the plan/objective twins there is NO session linkage after
-// the save — nothing consumes a gist in-session (adoption happens later via the cold doors), so
-// a successful save just relays the envelope's id/url/consumption story.
-//
-// APPROVAL→SAVE ORCHESTRATION (mirroring objectiveSave.ts's `objectiveApprovalSave`). The
-// exported `gistApprovalSave` seam is the shared APPROVED-review → save flow: re-read the
-// artifact (`readGistDraft` — never the rendered markdown, never the transcript) → `saveGist` →
-// D1a gate exit on a successful save (snapshot `gating.isActive()` BEFORE the save; a failed
-// save leaves the gate ON). `plan_review`'s gist arm (planReview.ts) wires its APPROVED outcome
-// into it; the `/gist-save` command is the artifact-first MANUAL FAILSAFE invocation of the same
-// seam, keeping the legacy drive-the-session behavior as the no-draft fallback (gists have no
-// transcript scrape by design).
-
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { bindingSuffix } from "../substrate/bindingDelivery.ts";
-import {
-  booleanField,
-  type ColdJson,
-  objectField,
-  runColdDoor,
-  stringField,
-} from "../substrate/coldDoor.ts";
-import { registerPerkCommand } from "../substrate/command.ts";
-import { render } from "../substrate/prompts.ts";
-import { failFor, ok, type Result } from "../substrate/result.ts";
-import type { ToolGating } from "../substrate/toolGating.ts";
-import { branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
-import { report, type Severity } from "../surfaces/report.ts";
-import { decodeGistSaveParams, GIST_SCOPES, type GistScope, readGistDraft } from "./gistDraft.ts";
-
-/** The ok-arm fields — the structured `details` surface doubles as branch-safe persisted state. */
-export interface GistSaveOk {
-  /** `id` is the opaque string gist id (GitHub "7", Linear "ENG-7"/project id) — §8.21. */
-  gist: { id: string; url: string };
-  scope: string | null;
-  existed: boolean | null;
-}
-
-export type GistSaveResult = Result<GistSaveOk>;
-
-/** The decoded `perk gist create --json` payload slice the warm door consumes. */
-interface GistCreatePayload {
-  gist: { id: string; url: string; existed: boolean | undefined };
-  scope: string | undefined;
-}
-
-/** Narrow the `perk gist create --json` success payload; strict on `gist`. */
-function decodeGistCreate(payload: ColdJson): GistCreatePayload | null {
-  const gist = objectField(payload, "gist");
-  if (gist === undefined) return null;
-  const id = stringField(gist, "id");
-  const url = stringField(gist, "url");
-  if (id === undefined || url === undefined) return null;
-  return {
-    gist: { id, url, existed: booleanField(gist, "existed") },
-    scope: stringField(payload, "scope"),
-  };
-}
-
-/** The consumption pointer relayed after a save — the adoption door matching the saved scope. */
-function consumptionHint(id: string, scope: string | undefined): string {
-  return scope === "objective"
-    ? `Consume with: perk objective author --from ${id}`
-    : `Consume with: perk plan from ${id}`;
-}
-
-/**
- * The single save implementation both surfaces call. Delegates the backend write to the Python
- * cold door (which owns scope resolution: an explicit `scope` wins, else the launch handoff's
- * pre-seeded `gist_scope`, else `plan`). Returns a soft result (never throws); failures set
- * `details.ok = false`. No session linkage on success — nothing consumes a gist in-session.
- */
-export async function saveGist(
-  pi: ExtensionAPI,
-  ctx: ExtensionContext,
-  opts: { prose: string; title?: string; scope?: GistScope },
-): Promise<GistSaveResult> {
-  const fail = failFor(ctx, "gist-save");
-
-  const prose = opts.prose.trim();
-  if (!prose) return fail("no gist prose to save (draft the gist first)", "invalid_input");
-  if (opts.scope !== undefined && !(GIST_SCOPES as readonly string[]).includes(opts.scope)) {
-    return fail("scope must be plan or objective", "invalid_input");
-  }
-
-  const runId = rebuildWorkflowState(branchOf(ctx)).run_id ?? "";
-
-  const args = ["gist", "create", "--json"];
-  if (opts.title) args.push("--title", opts.title);
-  if (opts.scope) args.push("--scope", opts.scope);
-  if (runId) args.push("--run-id", runId);
-  const r = await runColdDoor<GistCreatePayload>(pi, ctx, args, {
-    label: "perk gist create",
-    decode: decodeGistCreate,
-    stdin: { flag: "--body", content: prose, filename: "gist.md" },
-  });
-  if (!r.ok) return fail(r.message, r.errorType);
-
-  const gist = r.data.gist;
-  const verb = gist.existed ? "Found existing" : "Saved";
-  return ok(
-    `${verb} gist ${gist.id} → ${gist.url}\n${consumptionHint(gist.id, r.data.scope)}`,
-    {
-      gist: { id: gist.id, url: gist.url },
-      scope: r.data.scope ?? null,
-      existed: gist.existed ?? null,
-    },
-    { terminate: true },
-  );
-}
-
-/** The approval→save orchestration outcome (the gist `ApprovalSaveOutcome`). */
-export type GistApprovalSaveOutcome =
-  | { status: "no-draft" }
-  | { status: "saved" | "save-failed"; result: GistSaveResult; gateExited: boolean };
-
-/**
- * The shared approval→save orchestration seam (the gist sibling of objectiveSave.ts's
- * `objectiveApprovalSave`): an APPROVED gist review (`plan_review`'s gist arm) and the manual
- * `/gist-save` failsafe both run THIS. Flow: re-read the draft artifact at save time
- * (`readGistDraft` — never the rendered markdown, never in-hand bytes) → `saveGist` → gate exit
- * on a successful save while read-only (the D1a pattern: snapshot `gating.isActive()` before the
- * save; a failed save leaves the gate ON). No draft → `no-draft` (nothing saved, the gate
- * untouched); callers render their own fallback. Title/scope precedence: explicit opts win; else
- * the draft's; else the cold door derives/defaults. The returned result keeps `saveGist`'s
- * `terminate: true` for tool-path callers.
- */
-export async function gistApprovalSave(
-  pi: ExtensionAPI,
-  ctx: ExtensionContext,
-  gating: ToolGating,
-  opts: { title?: string } = {},
-): Promise<GistApprovalSaveOutcome> {
-  const draft = readGistDraft(ctx);
-  if (draft === null) return { status: "no-draft" };
-  // D1a: snapshot the gate BEFORE the save; on success, exit it so save marks the read-only →
-  // read-write boundary in one gesture. A failed save leaves the gate on.
-  const wasReadOnly = gating.isActive();
-  const result = await saveGist(pi, ctx, {
-    prose: draft.prose,
-    title: opts.title ?? draft.title,
-    scope: draft.scope,
-  });
-  let gateExited = false;
-  if (result.details.ok && wasReadOnly) {
-    gating.exit(ctx);
-    gateExited = true;
-  }
-  return { status: result.details.ok ? "saved" : "save-failed", result, gateExited };
-}
-
-const TOOL_GUIDELINES = [
-  "Use gist_save only after the gist says what it means; it creates the tracked gist in the issue backend and ends the turn.",
-  "Pass gist_save the statement-of-intent PROSE in `prose` — problem-focused, with at most high-level solution leanings; no implementation steps or roadmap.",
-  "Pass gist_save's `scope` only once the consumption tier is settled (plan or objective); omit it to keep the pre-seeded/default scope.",
-];
-
-/**
- * The seed guidance the warm `/gist-save` injects to drive the save (the perk-gist-author skill
- * pointer rides the skill-binding suffix — not hardcoded here). Pure + exported for offline
- * tests.
- */
-export function gistSaveGuidance(title?: string): string {
-  const named = title?.trim() || "";
-  return render("stages/gist-save.md", { title: named });
-}
-
-/** Register the warm door: the `gist_save` tool (canonical) + the `/gist-save` twin. */
-export function registerGistSave(pi: ExtensionAPI, gating: ToolGating): void {
-  pi.registerTool({
-    name: "gist_save",
-    label: "Save gist",
-    description:
-      "Persist a drafted gist (a statement of intent) to the issue backend as a tracked " +
-      "perk:gist. Terminating: ends the turn on save. Call only when the gist says what it " +
-      "means.",
-    promptSnippet: "Save the converged gist to the issue backend (terminates the turn)",
-    promptGuidelines: TOOL_GUIDELINES,
-    executionMode: "sequential",
-    parameters: {
-      type: "object",
-      additionalProperties: false,
-      required: ["prose"],
-      properties: {
-        prose: {
-          type: "string",
-          description:
-            "The gist prose (the problem-space intent: what we want, why it matters, what " +
-            "bounds it, and any high-level solution leanings — no implementation steps).",
-        },
-        title: {
-          type: "string",
-          description: "Optional gist title (defaults to the prose's first heading).",
-        },
-        scope: {
-          type: "string",
-          enum: [...GIST_SCOPES],
-          description:
-            "Optional consumption tier: plan (plan-sized intent) or objective (objective-sized).",
-        },
-      },
-    },
-    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-      const decoded = decodeGistSaveParams(params);
-      if (decoded === null) {
-        return failFor(
-          ctx,
-          "gist-save",
-          "gist_save",
-        )(
-          "gist_save needs { prose: string, scope?: plan|objective } per the tool schema",
-          "bad_input",
-        );
-      }
-      return saveGist(pi, ctx, decoded);
-    },
-  });
-
-  registerPerkCommand(pi, "gist-save", {
-    description:
-      "Save the working gist draft to the issue backend — the manual failsafe for the " +
-      "approval→save flow (artifact-first; drives the save only when no draft exists).",
-    handler: async (args, ctx) => {
-      const title = args.trim() || undefined;
-      // The artifact-first manual-failsafe invocation of the shared approval→save seam (the D1a
-      // gate exit lives in the seam). The legacy drive-the-session behavior is kept as the
-      // NO-DRAFT fallback — gists have no transcript scrape by design, so a draftless session
-      // still needs a working save path.
-      const outcome = await gistApprovalSave(pi, ctx, gating, { title });
-      if (outcome.status === "no-draft") {
-        // Exit the read-only gate so the gist_save tool (excluded from READ_ONLY_TOOLS) becomes
-        // reachable on the driven turn, then drive the turn (mirrors /objective-save).
-        if (gating.isActive()) gating.exit(ctx);
-        report(ctx, "gist-save", "info", "handing the save to the session");
-        // The perk-gist-author pointer rides the skill-binding suffix (D5) since a warm
-        // /gist-save outside a stage:gist-author session gets none from Mechanism A.
-        pi.sendUserMessage(gistSaveGuidance(title) + bindingSuffix(ctx.cwd, "stage:gist-author"));
-        return;
-      }
-      // Saved or save-failed: relay the save message (which carries the consumption hint).
-      const result = outcome.result;
-      const message = result.content[0]?.text ?? "gist-save done";
-      const severity: Severity = result.details.ok ? "info" : "error";
-      report(ctx, "gist-save", severity, message);
-    },
-  });
-}

package/extension/factories/implementHere.ts

@@ -1,116 +0,0 @@
-// The sanctioned "implement here" exit from plan authoring (contracts.md §8.23): the read-only
-// gate comes off WITHOUT saving to the issue backend, and the model is instructed to implement
-// the reviewed plan draft directly in the current session/checkout — edits only, git gestures
-// stay with the human. Human-only by construction: the two surfaces are the first-party review's
-// 4th verdict (planReview.ts) and the `/implement-here` command registered here — no model tool
-// exists, so the model can never choose to skip the backend on its own (the /btw posture).
-//
-// The seam, the guidance builder, and the command live in ONE module with no cycles:
-// planReview.ts imports from here, never the reverse. `implementHereExit` is the
-// gate-exit-WITHOUT-save sibling of `approvalSave`'s D1a arm — the review door composes the gate
-// through this seam, never owns it (Invariant 1).
-//
-// Deliberately OUTSIDE the PR lifecycle: no issue, no plan-ref, no branch — /submit, /address,
-// and /land all key off `cache.plan-ref` and stay inapplicable. The plan-draft artifact is left
-// untouched, so /plan-save can still create the canonical issue afterwards.
-
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { bindingSuffix } from "../substrate/bindingDelivery.ts";
-import { registerPerkCommand } from "../substrate/command.ts";
-import type { ToolGating } from "../substrate/toolGating.ts";
-import { report } from "../surfaces/report.ts";
-import { readNodeClaim } from "./objectivePlan.ts";
-
-/** The core instruction text (exported for the offline content pins). */
-export const IMPLEMENT_HERE_GUIDANCE = `The human chose IMPLEMENT HERE: implement the reviewed plan directly in this session — no plan issue was created and none will be.
-
-- The read-only gate is off: make the plan's edits now, in this checkout.
-- Run the checks the plan calls for before declaring done.
-- Do NOT commit, branch, or push unless the user explicitly asks — git gestures stay with the human.
-- perk's lifecycle doors (/submit, /land, /learn) do not apply — there is no plan issue or plan-ref.
-- The plan draft artifact is untouched: /plan-save can still create the canonical issue later.`;
-
-/**
- * Build the implement-here instruction text. When `editedPlan` is set (review-path human edits
- * were written back to the draft pre-verdict), the final reviewed bytes are inlined so the model
- * implements THOSE, not its stale in-context version. Always appends the Mechanism-B skill-binding
- * suffix for `command:implement-here` (a `[[bindings]]` hook; delivers nothing by default).
- */
-export function implementHereGuidance(cwd: string, opts: { editedPlan?: string }): string {
-  const edited =
-    opts.editedPlan === undefined
-      ? ""
-      : `\n\nThe human edited the plan during review; implement THESE final bytes:\n\n${opts.editedPlan}`;
-  return `${IMPLEMENT_HERE_GUIDANCE}${edited}${bindingSuffix(cwd, "command:implement-here")}`;
-}
-
-/**
- * The gate-exit-WITHOUT-save seam — the no-save sibling of `approvalSave`'s D1a arm. If the gate
- * is active, exit it and report one info line; otherwise a no-op. Keeps Invariant 1: callers
- * (the review door's implement-here verdict, the `/implement-here` command) compose the gate
- * through this seam, never own it.
- */
-export function implementHereExit(
-  ctx: ExtensionContext,
-  gating: ToolGating,
-): { gateExited: boolean } {
-  if (!gating.isActive()) return { gateExited: false };
-  gating.exit(ctx);
-  report(
-    ctx,
-    "implement-here",
-    "info",
-    "plan mode off — implementing here; no issue saved (draft intact; /plan-save can still create it)",
-  );
-  return { gateExited: true };
-}
-
-/**
- * Register `/implement-here` — the universal manual gesture for the no-save exit (and the ONLY
- * reachable surface when the plannotator review is selected, whose browser envelope returns only
- * approve/deny). Handler order: the objective-node carve-out (a node-linked plan must save — the
- * node advance and backlink depend on it) → the gate-off warning (the command's meaning is
- * exiting plan mode without saving) → gate exit + guidance injection (the submit.ts routing:
- * idle → an immediate turn; streaming → a followUp).
- */
-export function registerImplementHere(pi: ExtensionAPI, gating: ToolGating): void {
-  registerPerkCommand(pi, "implement-here", {
-    description:
-      "Exit plan mode WITHOUT saving an issue and implement the current plan draft in this " +
-      "session (the human-owned lightweight path).",
-    handler: async (_args, ctx) => {
-      // 1. Objective-node planning sessions must save: an implement-here would strand the node in
-      //    `planning` (the claim is only cleared by a node-linked save or a non-planning
-      //    transition). Gate untouched, nothing injected.
-      if (readNodeClaim(ctx) !== null) {
-        report(
-          ctx,
-          "implement-here",
-          "warning",
-          "this is an objective-node planning session — a node-linked plan must be saved " +
-            "(the node advance and backlink depend on it). Use plan_review / /plan-save instead.",
-        );
-        return;
-      }
-      // 2. Nothing to exit: the command's meaning is *exiting plan mode without saving*.
-      if (!gating.isActive()) {
-        report(
-          ctx,
-          "implement-here",
-          "warning",
-          "not in plan mode — nothing to exit; just ask the model to implement.",
-        );
-        return;
-      }
-      // 3. Gate off → instruct the model. No inlined plan: the model authored the draft in its
-      //    own context (the review-path edited-bytes inlining lives in planReview.ts).
-      implementHereExit(ctx, gating);
-      const message = implementHereGuidance(ctx.cwd, {});
-      if (ctx.isIdle()) {
-        pi.sendUserMessage(message);
-      } else {
-        pi.sendUserMessage(message, { deliverAs: "followUp" });
-      }
-    },
-  });
-}