@mgiles/perk 1.0.1 → 2.0.0

package/extension/factories/planReview.ts

@@ -6,8 +6,10 @@
 // (`runFirstPartyReview`): display the draft in pi's built-in `ctx.ui.editor` dialog (scrollable,
 // Ctrl+G opens the user's external $EDITOR), write optional human edits back to the draft via
 // `writePlanDraft` BEFORE the verdict (reviewed bytes == artifact bytes == saved bytes — a failed
-// write-back ABORTS the review fail-open, nothing saved), then a 3-option approve/deny/skip
-// `ctx.ui.select` verdict, with deny feedback via a second editor dialog.
+// write-back ABORTS the review fail-open, nothing saved), then an approve/deny/skip
+// `ctx.ui.select` verdict — on the plan arm with a 4th "Implement here — no issue saved" option
+// (§8.23; suppressed in objective-node planning sessions) — with deny feedback via a second
+// editor dialog.
 //
 // REVIEW SEMANTICS (file-first, approval auto-saves): the review runs while the session is still
 // read-only (the tool is in READ_ONLY_TOOLS — review happens before the gate ever comes off).
@@ -48,11 +50,14 @@ import {
   createPlannotatorBridge,
   isPlannotatorPlanSelected,
 } from "../adapters/planAdapterPlannotator.ts";
+import type { Result } from "../substrate/result.ts";
 import type { ToolGating } from "../substrate/toolGating.ts";
 import { paramsOf, stringParam } from "../substrate/toolParams.ts";
 import { branchOf, rebuildWorkflowState } from "../substrate/workflowState.ts";
+import { implementHereExit, implementHereGuidance } from "./implementHere.ts";
 import { OBJECTIVE_AUTHOR_STAGE } from "./objectiveAuthor.ts";
 import { readObjectiveDraft, renderObjectiveDraft } from "./objectiveDraft.ts";
+import { readNodeClaim } from "./objectivePlan.ts";
 import { type ObjectiveApprovalSaveOutcome, objectiveApprovalSave } from "./objectiveSave.ts";
 import { writePlanDraft } from "./planDraft.ts";
 import { type ApprovalSaveOutcome, approvalSave, resolvePlanSource } from "./planSave.ts";
@@ -62,12 +67,15 @@ import { type ApprovalSaveOutcome, approvalSave, resolvePlanSource } from "./pla
 /**
  * The review outcome a backend produces, mapped into a tool result below (also `details.status`).
  * The `dismissed` arm is FIRST-PARTY ONLY (Esc anywhere = fail-open skip; the plannotator bridge
- * never produces it).
+ * never produces it). The `implement-here` arm is first-party PLAN-arm only (the human chose the
+ * no-save exit — contracts.md §8.23); the plannotator bridge never produces it (its browser
+ * envelope returns only approve/deny) and the objective arm never offers it.
  */
 export type ReviewOutcome =
   | { status: "unavailable"; warning: string }
   | { status: "aborted" }
   | { status: "dismissed" }
+  | { status: "implement-here"; reviewId: string }
   | { status: "completed"; approved: boolean; feedback?: string; reviewId: string };
 
 interface ToolResult {
@@ -76,21 +84,70 @@ interface ToolResult {
   terminate?: boolean;
 }
 
+/**
+ * The subject descriptor parameterizing the shared renderer cores below — the plan and objective
+ * review arms render the same outcome shapes, differing only in these fields. Module-private on
+ * purpose: nothing outside this module needs it (both execute arms live here), and a third review
+ * subject would land here too, constructing its own descriptor and reusing the cores.
+ */
+interface ReviewSubject {
+  /** The display noun in every rendered text ("plan" / "objective"). */
+  noun: string;
+  /** The lowercase present-the-work phrase (dismissed / implement-here arms). */
+  present: string;
+  /** The unavailable-arm phrase (the plan flavor appends "in your next message"). */
+  presentUnavailable: string;
+  /** Where an implement-here verdict "cannot" have come from (the defensive arm's text). */
+  implementHereWhere: string;
+  /** The draft-rewrite tool the DENIED text redirects to. */
+  draftTool: string;
+  /** The manual-failsafe slash command. */
+  failsafeCmd: string;
+  /** Extra keys merged into every details object ({} on the plan arm). */
+  detailsExtra: Record<string, unknown>;
+  /** The defensively-unreachable no-source save arm's error string. */
+  noSourceError: string;
+}
+
+const PLAN_SUBJECT: ReviewSubject = {
+  noun: "plan",
+  present: "the complete plan to the user",
+  presentUnavailable: "the complete plan to the user in your next message",
+  implementHereWhere: "outside the execute path",
+  draftTool: "plan_draft",
+  failsafeCmd: "/plan-save",
+  detailsExtra: {},
+  noSourceError: "no plan source resolved",
+};
+
+const OBJECTIVE_SUBJECT: ReviewSubject = {
+  noun: "objective",
+  present: "the complete objective + structured roadmap to the user",
+  presentUnavailable: "the complete objective + structured roadmap to the user",
+  implementHereWhere: "on the objective path",
+  draftTool: "objective_draft",
+  failsafeCmd: "/objective-save",
+  detailsExtra: { subject: "objective" },
+  noSourceError: "no objective draft resolved",
+};
+
 const SKIP_TEXT =
   "no interactive review surface available — present the complete plan to the user in your next message.";
 
 function skipResult(): ToolResult {
-  return { content: [{ type: "text", text: SKIP_TEXT }], details: { status: "skipped" } };
+  return { content: [{ type: "text", text: SKIP_TEXT }], details: { ok: true, status: "skipped" } };
 }
 
 /**
- * Map a non-approved review outcome into the model-facing tool result (exported for the offline
- * tests). The `completed` case renders the DENIED text — the execute path routes approved
- * outcomes to `approvedSaveResult` first, so callers only reach `completed` here with
- * `approved: false` (kept total for safety). The `dismissed` arm renders as a skip — the human
- * declined to decide, so the present-plan + `/plan-save` manual-failsafe discipline applies.
+ * The shared outcome-mapper core: map a non-approved review outcome into the model-facing tool
+ * result for `subject`. The `completed` case renders the DENIED text — both execute paths route
+ * approved outcomes to their approved-save mapper FIRST, so callers only reach `completed` here
+ * with `approved: false` (kept total for safety; the `approved: outcome.approved` passthrough is
+ * deliberately behavior-preserving — never hardcode `false`). The `dismissed` arm renders as a
+ * skip — the human declined to decide, so the present-the-work + manual-failsafe discipline
+ * applies.
  */
-export function reviewOutcomeResult(outcome: ReviewOutcome): ToolResult {
+function subjectReviewOutcomeResult(subject: ReviewSubject, outcome: ReviewOutcome): ToolResult {
   switch (outcome.status) {
     case "unavailable":
       return {
@@ -99,15 +156,21 @@ export function reviewOutcomeResult(outcome: ReviewOutcome): ToolResult {
             type: "text",
             text:
               `WARNING: ${outcome.warning} — no review performed. ` +
-              "Present the complete plan to the user in your next message instead.",
+              `Present ${subject.presentUnavailable} instead.`,
           },
         ],
-        details: { status: "unavailable" },
+        details: {
+          ok: false,
+          error: outcome.warning,
+          error_type: "unavailable",
+          status: "unavailable",
+          ...subject.detailsExtra,
+        },
       };
     case "aborted":
       return {
-        content: [{ type: "text", text: "plan review aborted (turn interrupted)." }],
-        details: { status: "aborted" },
+        content: [{ type: "text", text: `${subject.noun} review aborted (turn interrupted).` }],
+        details: { ok: true, status: "aborted", ...subject.detailsExtra },
       };
     case "dismissed":
       return {
@@ -115,24 +178,41 @@ export function reviewOutcomeResult(outcome: ReviewOutcome): ToolResult {
           {
             type: "text",
             text:
-              "plan review dismissed — present the complete plan to the user; the human runs " +
-              "/plan-save (the manual failsafe).",
+              `${subject.noun} review dismissed — present ${subject.present}; the human runs ` +
+              `${subject.failsafeCmd} (the manual failsafe).`,
+          },
+        ],
+        details: { ok: true, status: "skipped", reason: "dismissed", ...subject.detailsExtra },
+      };
+    case "implement-here":
+      // Defensively unreachable: the plan execute path routes implement-here to
+      // implementHereResult FIRST (mirror the approved-first routing), and the objective arm
+      // never offers the verdict. Map to a skip shape rather than throwing.
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              `implement-here verdict received ${subject.implementHereWhere} — nothing saved; ` +
+              `present ${subject.present}.`,
           },
         ],
-        details: { status: "skipped", reason: "dismissed" },
+        details: { ok: true, status: "skipped", reason: "implement-here", ...subject.detailsExtra },
       };
     case "completed": {
       const feedback = outcome.feedback ? `\n\nReviewer feedback:\n${outcome.feedback}` : "";
       const text =
-        "plan DENIED — revise per this feedback, rewrite the working draft with plan_draft, " +
-        `then call plan_review again.${feedback}`;
+        `${subject.noun} DENIED — revise per this feedback, rewrite the working draft with ` +
+        `${subject.draftTool}, then call plan_review again.${feedback}`;
       return {
         content: [{ type: "text", text }],
         details: {
+          ok: true,
           status: "completed",
           approved: outcome.approved,
           feedback: outcome.feedback ?? null,
           reviewId: outcome.reviewId,
+          ...subject.detailsExtra,
         },
       };
     }
@@ -140,52 +220,82 @@ export function reviewOutcomeResult(outcome: ReviewOutcome): ToolResult {
 }
 
 /**
- * Map an APPROVED review outcome + the `approvalSave` outcome into the model-facing tool result
- * (exported for the offline tests). A successful save TERMINATES the turn (propagating the
- * seam's `terminate: true` intent); a failed save is non-terminating, leaves the gate read-only,
- * and directs the human `/plan-save` failsafe. Reviewer feedback is surfaced loudly as
- * implementation guidance — the approved bytes were saved verbatim, never post-edited. `edited`
- * (first-party only) flags that human edits were written back to the draft pre-verdict, so the
- * saved bytes carry them. The `no-plan` arm is defensively unreachable (the reviewed plan is
- * always non-blank) but maps to the save-failed shape rather than throwing.
+ * Map a non-approved review outcome into the model-facing tool result (exported for the offline
+ * tests) — the plan flavor of `subjectReviewOutcomeResult`. The execute path routes approved
+ * outcomes to `approvedSaveResult` first, so `completed` renders DENIED here.
  */
-export function approvedSaveResult(
+export function reviewOutcomeResult(outcome: ReviewOutcome): ToolResult {
+  return subjectReviewOutcomeResult(PLAN_SUBJECT, outcome);
+}
+
+/**
+ * The normalized approval-save outcome the shared core consumes — each delegator maps its
+ * subject-specific no-source discriminant (`no-plan` / `no-draft`) onto `no-source`. `result`
+ * widens to `Result<object>`: the core reads only `content[0]?.text` and the `details.ok`
+ * discriminant (+ `details.error` on the fail arm), passing `details` through opaquely.
+ */
+type SubjectSaveOutcome =
+  | { status: "no-source" }
+  | { status: "saved" | "save-failed"; result: Result<object>; gateExited: boolean };
+
+/**
+ * The shared approved-save mapper core: map an APPROVED review outcome + the approval-save
+ * outcome into the model-facing tool result for `subject`. A successful save TERMINATES the turn
+ * (propagating the seam's `terminate: true` intent); a failed save is non-terminating, leaves
+ * the gate read-only, and directs the human manual failsafe. Reviewer feedback is surfaced
+ * loudly as implementation guidance — the approved bytes were saved verbatim, never post-edited.
+ * The `paramMismatch`/`edited` opts are plan-arm-only (their literals name "plan"/"draft"): the
+ * objective delegator never passes opts, so the suffixes render empty and `edited` never reaches
+ * its details. The `no-source` arm is defensively unreachable (the reviewed source is always
+ * non-blank) but maps to the save-failed shape rather than throwing.
+ */
+function approvedSubjectSaveResult(
+  subject: ReviewSubject,
   outcome: Extract<ReviewOutcome, { status: "completed" }>,
-  save: ApprovalSaveOutcome,
-  opts: { paramMismatch: boolean; edited?: boolean },
+  save: SubjectSaveOutcome,
+  opts?: { paramMismatch?: boolean; edited?: boolean },
 ): ToolResult {
   const feedback = outcome.feedback
-    ? "\n\nReviewer feedback (implementation guidance — the approved plan was saved verbatim):\n" +
-      outcome.feedback
+    ? `\n\nReviewer feedback (implementation guidance — the approved ${subject.noun} was saved ` +
+      `verbatim):\n${outcome.feedback}`
     : "";
   const base = {
     status: "completed",
     approved: true,
     reviewId: outcome.reviewId,
     feedback: outcome.feedback ?? null,
-    ...(opts.edited === true ? { edited: true } : {}),
+    ...subject.detailsExtra,
+    ...(opts?.edited === true ? { edited: true } : {}),
   };
   if (save.status === "saved") {
     const saveText = save.result.content[0]?.text ?? "";
-    const mismatch = opts.paramMismatch
-      ? "\n\n⚠ differing plan param ignored — the validated draft was reviewed and saved."
-      : "";
     const edited =
-      opts.edited === true ? " · human edits were written back to the draft and saved" : "";
+      opts?.edited === true ? " · human edits were written back to the draft and saved" : "";
+    const mismatch =
+      opts?.paramMismatch === true
+        ? "\n\n⚠ differing plan param ignored — the validated draft was reviewed and saved."
+        : "";
     return {
       content: [
         {
           type: "text",
-          text: `plan APPROVED by reviewer.${feedback}\n\n${saveText}${edited}${mismatch}`,
+          text: `${subject.noun} APPROVED by reviewer.${feedback}\n\n${saveText}${edited}${mismatch}`,
         },
       ],
-      details: { ...base, saved: true, gateExited: save.gateExited, save: save.result.details },
+      // `ok` sits per-branch, NOT in `base` — `base` is spread into the fail branch too.
+      details: {
+        ok: true,
+        ...base,
+        saved: true,
+        gateExited: save.gateExited,
+        save: save.result.details,
+      },
       terminate: true,
     };
   }
   const error =
-    save.status === "no-plan"
-      ? "no plan source resolved"
+    save.status === "no-source"
+      ? subject.noSourceError
       : save.result.details.ok
         ? "unknown save failure"
         : save.result.details.error;
@@ -194,14 +304,68 @@ export function approvedSaveResult(
       {
         type: "text",
         text:
-          `plan APPROVED by reviewer, but the auto-save FAILED (${error}) — the session stays ` +
-          `read-only. Ask the user to run /plan-save (the manual failsafe) to retry.${feedback}`,
+          `${subject.noun} APPROVED by reviewer, but the auto-save FAILED (${error}) — the ` +
+          `session stays read-only. Ask the user to run ${subject.failsafeCmd} (the manual ` +
+          `failsafe) to retry.${feedback}`,
       },
     ],
     details: {
+      ok: false,
+      error,
+      error_type: "save_failed",
       ...base,
       saved: false,
-      save: save.status === "no-plan" ? null : save.result.details,
+      save: save.status === "no-source" ? null : save.result.details,
+    },
+  };
+}
+
+/**
+ * Map an APPROVED review outcome + the `approvalSave` outcome into the model-facing tool result
+ * (exported for the offline tests) — the plan flavor of `approvedSubjectSaveResult`. `edited`
+ * (first-party only) flags that human edits were written back to the draft pre-verdict, so the
+ * saved bytes carry them.
+ */
+export function approvedSaveResult(
+  outcome: Extract<ReviewOutcome, { status: "completed" }>,
+  save: ApprovalSaveOutcome,
+  opts: { paramMismatch: boolean; edited?: boolean },
+): ToolResult {
+  return approvedSubjectSaveResult(
+    PLAN_SUBJECT,
+    outcome,
+    save.status === "no-plan" ? { status: "no-source" } : save,
+    opts,
+  );
+}
+
+/**
+ * Map an IMPLEMENT-HERE review outcome + the `implementHereExit` outcome into the model-facing
+ * tool result (exported for the offline tests). NON-terminating on purpose — the model continues
+ * the turn and implements immediately. The text is the implement-here guidance; when the human
+ * edited the plan during review (`edited`), the final reviewed bytes are inlined so the model
+ * implements THOSE, not its stale in-context version (the draft write-back already happened
+ * pre-verdict). Nothing is saved: no issue, no plan-ref, the draft artifact intact (§8.23).
+ */
+export function implementHereResult(
+  outcome: Extract<ReviewOutcome, { status: "implement-here" }>,
+  exit: { gateExited: boolean },
+  opts: { cwd: string; plan: string; edited: boolean },
+): ToolResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text: implementHereGuidance(opts.cwd, { editedPlan: opts.edited ? opts.plan : undefined }),
+      },
+    ],
+    details: {
+      ok: true,
+      status: "implement-here",
+      saved: false,
+      gateExited: exit.gateExited,
+      reviewId: outcome.reviewId,
+      ...(opts.edited ? { edited: true } : {}),
     },
   };
 }
@@ -218,10 +382,22 @@ export interface PlanReviewUI {
   ): Promise<string | undefined>;
 }
 
-/** The verdict options (plain text — charter D3: no emoji outside the footer). */
-const VERDICT_APPROVE = "Approve — auto-save to GitHub";
-const VERDICT_DENY = "Deny — send feedback for revision";
-const VERDICT_SKIP = "Skip — decide later (manual /plan-save)";
+/**
+ * Derive a subject's verdict options (plain text — charter D3: no emoji outside the footer);
+ * only the skip label's manual-failsafe command varies by subject. `VERDICT_IMPLEMENT_HERE`
+ * stays a standalone constant on purpose — the no-save exit is plan-arm-only by contract
+ * (§8.23), never part of the descriptor.
+ */
+function verdictsFor(subject: ReviewSubject): { approve: string; deny: string; skip: string } {
+  return {
+    approve: "Approve — auto-save to GitHub",
+    deny: "Deny — send feedback for revision",
+    skip: `Skip — decide later (manual ${subject.failsafeCmd})`,
+  };
+}
+
+/** The optional 4th verdict (plan arm only): the no-save implement-here exit (§8.23). */
+const VERDICT_IMPLEMENT_HERE = "Implement here — no issue saved";
 
 const REVIEW_EDITOR_TITLE =
   "Plan review — Enter: continue to verdict · Esc: skip · Ctrl+G: $EDITOR";
@@ -238,7 +414,10 @@ const DENY_FEEDBACK_TITLE = "Deny feedback (optional) — Enter to send";
  * AbortSignal — `signal?.aborted` is checked before each dialog (the aborted arm wins).
  *
  * Presentation options (defaults preserve the plan-path behavior byte-for-byte):
- * `editorTitle`/`verdicts` swap the displayed strings; `viewOnly: true` skips the write-back
+ * `editorTitle`/`verdicts` swap the displayed strings; `verdicts.implementHere`, when present,
+ * makes the verdict select 4 options — approve, implement-here, deny, skip (implement-here sits
+ * adjacent to approve: both are "accept the plan" outcomes) — and selecting it returns the
+ * `implement-here` outcome arm; `viewOnly: true` skips the write-back
  * branch entirely — the editor output is used only for Esc/dismissed detection, `plan` is
  * returned unchanged and `edited` stays false (deny+feedback is the change channel).
  */
@@ -249,16 +428,13 @@ export async function runFirstPartyReview(args: {
   writeDraft(plan: string): boolean;
   signal?: AbortSignal;
   editorTitle?: string;
-  verdicts?: { approve: string; deny: string; skip: string };
+  verdicts?: { approve: string; deny: string; skip: string; implementHere?: string };
   viewOnly?: boolean;
 }): Promise<{ outcome: ReviewOutcome; plan: string; edited: boolean }> {
   const { ui, writeDraft, signal } = args;
   const editorTitle = args.editorTitle ?? REVIEW_EDITOR_TITLE;
-  const verdicts = args.verdicts ?? {
-    approve: VERDICT_APPROVE,
-    deny: VERDICT_DENY,
-    skip: VERDICT_SKIP,
-  };
+  const verdicts: { approve: string; deny: string; skip: string; implementHere?: string } =
+    args.verdicts ?? verdictsFor(PLAN_SUBJECT);
   let plan = args.plan;
   let edited = false;
   const result = (
@@ -291,15 +467,18 @@ export async function runFirstPartyReview(args: {
   }
 
   if (signal?.aborted) return result({ status: "aborted" });
-  const verdict = await ui.select(
-    "Plan review verdict",
-    [verdicts.approve, verdicts.deny, verdicts.skip],
-    { signal },
-  );
+  const options =
+    verdicts.implementHere === undefined
+      ? [verdicts.approve, verdicts.deny, verdicts.skip]
+      : [verdicts.approve, verdicts.implementHere, verdicts.deny, verdicts.skip];
+  const verdict = await ui.select("Plan review verdict", options, { signal });
   if (signal?.aborted) return result({ status: "aborted" });
   if (verdict === verdicts.approve) {
     return result({ status: "completed", approved: true, reviewId: randomUUID() });
   }
+  if (verdicts.implementHere !== undefined && verdict === verdicts.implementHere) {
+    return result({ status: "implement-here", reviewId: randomUUID() });
+  }
   if (verdict === verdicts.deny) {
     const feedback = await ui.editor(DENY_FEEDBACK_TITLE, "");
     if (signal?.aborted) return result({ status: "aborted" });
@@ -316,135 +495,38 @@ export async function runFirstPartyReview(args: {
 
 // ------------------------------------------------------------------- the objective review arm
 
-/** The objective-flavored verdict options (approval auto-saves). */
-const OBJECTIVE_VERDICTS = {
-  approve: "Approve — auto-save to GitHub",
-  deny: "Deny — send feedback for revision",
-  skip: "Skip — decide later (manual /objective-save)",
-};
-
 const OBJECTIVE_REVIEW_EDITOR_TITLE =
   "Objective review (view only — edits are not saved) — Enter: continue to verdict · Esc: skip · " +
   "Ctrl+G: $EDITOR";
 
 /**
  * Map a non-approved objective review outcome into the model-facing tool result (exported for
- * the offline tests) — the objective-flavored sibling of `reviewOutcomeResult`. Every arm
- * carries `details.subject: "objective"`; the texts redirect to `objective_draft` /
- * `/objective-save`. The `completed` case renders the DENIED text — the execute path routes
- * approved outcomes to `approvedObjectiveSaveResult` first, so callers only reach `completed`
- * here with `approved: false` (kept total for safety).
+ * the offline tests) — the objective-flavored sibling of `reviewOutcomeResult`, delegating to
+ * `subjectReviewOutcomeResult` with `OBJECTIVE_SUBJECT`. Every arm carries
+ * `details.subject: "objective"`; the texts redirect to `objective_draft` / `/objective-save`.
+ * The execute path routes approved outcomes to `approvedObjectiveSaveResult` first, so
+ * `completed` renders DENIED here.
  */
 export function objectiveReviewOutcomeResult(outcome: ReviewOutcome): ToolResult {
-  switch (outcome.status) {
-    case "unavailable":
-      return {
-        content: [
-          {
-            type: "text",
-            text:
-              `WARNING: ${outcome.warning} — no review performed. ` +
-              "Present the complete objective + structured roadmap to the user instead.",
-          },
-        ],
-        details: { status: "unavailable", subject: "objective" },
-      };
-    case "aborted":
-      return {
-        content: [{ type: "text", text: "objective review aborted (turn interrupted)." }],
-        details: { status: "aborted", subject: "objective" },
-      };
-    case "dismissed":
-      return {
-        content: [
-          {
-            type: "text",
-            text:
-              "objective review dismissed — present the complete objective + structured roadmap " +
-              "to the user; the human runs /objective-save (the manual failsafe).",
-          },
-        ],
-        details: { status: "skipped", reason: "dismissed", subject: "objective" },
-      };
-    case "completed": {
-      const feedback = outcome.feedback ? `\n\nReviewer feedback:\n${outcome.feedback}` : "";
-      return {
-        content: [
-          {
-            type: "text",
-            text:
-              "objective DENIED — revise per this feedback, rewrite the working draft with " +
-              `objective_draft, then call plan_review again.${feedback}`,
-          },
-        ],
-        details: {
-          status: "completed",
-          approved: outcome.approved,
-          feedback: outcome.feedback ?? null,
-          reviewId: outcome.reviewId,
-          subject: "objective",
-        },
-      };
-    }
-  }
+  return subjectReviewOutcomeResult(OBJECTIVE_SUBJECT, outcome);
 }
 
 /**
  * Map an APPROVED objective review outcome + the `objectiveApprovalSave` outcome into the
  * model-facing tool result (exported for the offline tests) — the objective sibling of
- * `approvedSaveResult` (no `paramMismatch`/`edited` opts: the objective path reviews only the
- * rendered draft, view-only). A successful save TERMINATES the turn; a failed save is
- * non-terminating, leaves the gate read-only, and directs the human `/objective-save` failsafe.
- * The `no-draft` arm is defensively unreachable (the review just read the draft) but maps to
- * the save-failed shape rather than throwing.
+ * `approvedSaveResult`, delegating to `approvedSubjectSaveResult` with `OBJECTIVE_SUBJECT` and
+ * no opts (the objective path reviews only the rendered draft, view-only — no
+ * `paramMismatch`/`edited`).
  */
 export function approvedObjectiveSaveResult(
   outcome: Extract<ReviewOutcome, { status: "completed" }>,
   save: ObjectiveApprovalSaveOutcome,
 ): ToolResult {
-  const feedback = outcome.feedback
-    ? "\n\nReviewer feedback (implementation guidance — the approved objective was saved " +
-      `verbatim):\n${outcome.feedback}`
-    : "";
-  const base = {
-    status: "completed",
-    approved: true,
-    reviewId: outcome.reviewId,
-    feedback: outcome.feedback ?? null,
-    subject: "objective",
-  };
-  if (save.status === "saved") {
-    const saveText = save.result.content[0]?.text ?? "";
-    return {
-      content: [
-        { type: "text", text: `objective APPROVED by reviewer.${feedback}\n\n${saveText}` },
-      ],
-      details: { ...base, saved: true, gateExited: save.gateExited, save: save.result.details },
-      terminate: true,
-    };
-  }
-  const error =
-    save.status === "no-draft"
-      ? "no objective draft resolved"
-      : save.result.details.ok
-        ? "unknown save failure"
-        : save.result.details.error;
-  return {
-    content: [
-      {
-        type: "text",
-        text:
-          `objective APPROVED by reviewer, but the auto-save FAILED (${error}) — the session ` +
-          "stays read-only. Ask the user to run /objective-save (the manual failsafe) to " +
-          `retry.${feedback}`,
-      },
-    ],
-    details: {
-      ...base,
-      saved: false,
-      save: save.status === "no-draft" ? null : save.result.details,
-    },
-  };
+  return approvedSubjectSaveResult(
+    OBJECTIVE_SUBJECT,
+    outcome,
+    save.status === "no-draft" ? { status: "no-source" } : save,
+  );
 }
 
 /**
@@ -477,7 +559,13 @@ export async function executeObjectiveReview(
             "(prose + the structured roadmap), then call plan_review again.",
         },
       ],
-      details: { status: "skipped", reason: "no_objective_draft" },
+      details: {
+        ok: false,
+        error: "no objective draft to review — write it with objective_draft first",
+        error_type: "no_objective_draft",
+        status: "skipped",
+        reason: "no_objective_draft",
+      },
     };
   }
   // 3. The reviewed bytes are the RENDERED markdown (prose + roadmap table) — never raw JSON.
@@ -495,7 +583,7 @@ export async function executeObjectiveReview(
       writeDraft: () => true, // unreachable under viewOnly — the branch is skipped
       signal: sig,
       editorTitle: OBJECTIVE_REVIEW_EDITOR_TITLE,
-      verdicts: OBJECTIVE_VERDICTS,
+      verdicts: verdictsFor(OBJECTIVE_SUBJECT),
       viewOnly: true,
     });
     outcome = fp.outcome;
@@ -542,7 +630,13 @@ export async function executePlanReview(
           text: "plan_review takes { plan?: string } — omit it (the plan-draft artifact is preferred) or pass a string.",
         },
       ],
-      details: { status: "skipped", reason: "bad_input" },
+      details: {
+        ok: false,
+        error: "plan must be a string",
+        error_type: "bad_input",
+        status: "skipped",
+        reason: "bad_input",
+      },
     };
   }
   // 1. Objective-author session → the objective review arm: the rendered
@@ -565,7 +659,13 @@ export async function executePlanReview(
             "param), then call plan_review again.",
         },
       ],
-      details: { status: "skipped", reason: "no_plan" },
+      details: {
+        ok: false,
+        error: "no plan to review — write the draft with plan_draft first",
+        error_type: "no_plan",
+        status: "skipped",
+        reason: "no_plan",
+      },
     };
   }
   // 4. Backend dispatch: plannotator-selected → the event-bus bridge; ANY other selection
@@ -577,17 +677,31 @@ export async function executePlanReview(
   if (isPlannotatorPlanSelected(ctx.cwd)) {
     outcome = await bridge.review(src.plan, sig);
   } else {
+    // The 4th verdict (implement-here, the no-save exit) is offered UNLESS this is an
+    // objective-node planning session — a node-linked plan must save (the node advance and
+    // backlink depend on it), so the claim suppresses it back to the 3-option select.
     const fp = await runFirstPartyReview({
       ui: ctx.ui,
       plan: src.plan,
       writeDraft: (text) => writePlanDraft(pi, ctx, text).details.ok,
       signal: sig,
+      verdicts:
+        readNodeClaim(ctx) === null
+          ? { ...verdictsFor(PLAN_SUBJECT), implementHere: VERDICT_IMPLEMENT_HERE }
+          : undefined,
     });
     outcome = fp.outcome;
     reviewedPlan = fp.plan;
     edited = fp.edited;
   }
-  // 5. An APPROVED decision (either backend) wires into the approvalSave seam (auto-save → D1a
+  // 5. IMPLEMENT-HERE (first-party only) routes before the generic mapper (mirror the
+  //    approved-first split): gate exit WITHOUT save through the implementHereExit seam → a
+  //    NON-terminating result carrying the implement-now guidance.
+  if (outcome.status === "implement-here") {
+    const exit = implementHereExit(ctx, gating);
+    return implementHereResult(outcome, exit, { cwd: ctx.cwd, plan: reviewedPlan, edited });
+  }
+  // 6. An APPROVED decision (either backend) wires into the approvalSave seam (auto-save → D1a
   //    gate exit → terminating result); everything else maps via reviewOutcomeResult.
   if (outcome.status === "completed" && outcome.approved) {
     const save = await approvalSave(pi, ctx, gating, { reviewedPlan });
@@ -621,7 +735,7 @@ export function registerPlanReview(pi: ExtensionAPI, gating: ToolGating): void {
       "Keep the working draft current with plan_draft — the validated plan-draft artifact is what plan_review reviews AND auto-saves; the plan param is only a fallback when no draft exists.",
       "Call plan_review only when the plan is decision-complete.",
       "On a DENIED review, revise per the feedback, rewrite the draft with plan_draft, then call plan_review again.",
-      "On an APPROVED review, the plan is auto-saved and the turn ends — never re-dump the plan as a final message and never tell the user to run /plan-save; relay the save outcome instead.",
+      "On an APPROVED plan_review, the plan is auto-saved and the turn ends — never re-dump the plan as a final message and never tell the user to run /plan-save; relay the save outcome instead.",
       "If plan_review reports it was skipped or unavailable (headless, dismissed), fall back to presenting the complete plan; the human runs /plan-save (the manual failsafe).",
     ],
     executionMode: "sequential",