@mgiles/perk 3.1.0 → 3.3.0

package/extension/pi/v1/objectiveAuthoring.ts

@@ -0,0 +1,672 @@
+// The v1 Pi installer for the objective authoring flow (module-contracts.md's named-installer
+// shape): `installObjectiveAuthoringBindings` owns the objective-authoring context hook pair,
+// the `objective_draft`/`objective_save` tools, and the `/objective-save` command —
+// registration metadata pinned by the suite's registration-parity tests. The feature logic lives in `authoring/objective/`; this
+// module decodes at the tool boundary, builds the cold-door backend + gate + dream-gate
+// adapters, constructs the warm-door Result envelopes, and places the feature-owned prose in Pi
+// fields. `objectiveApprovalSaveV1` is the composed approval→save twin the review arm
+// (`pi/v1/objectiveReview.ts`) and the browser door consume.
+//
+// The objective-authoring injection rides the shared `installInjectedContext` helper
+// (pi/v1/contextInjection.ts — contracts §8.31 semantics): a live copy in the
+// compaction-active window suppresses re-injection, and compaction dropping it from model
+// context re-injects on the next turn.
+//
+// Format doctrine (rides the tools): JSON is the storage/transport format, NEVER the human
+// review surface — the review arm renders markdown via the feature's resume+render helpers; the
+// approval→save orchestration re-reads the STRUCTURED artifact. Carve-out doctrine: the draft
+// tool takes NO path/name parameter (the artifact name is fixed and the bytes flow through the
+// session seam), so allowlisting `objective_draft` in `READ_ONLY_TOOLS` keeps the read-only
+// invariant intact.
+
+import { join } from "node:path";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  DELIVERY_CHOICES,
+  isDeliveryChoice,
+  OBJECTIVE_DRAFT_ARTIFACT,
+  type ObjectiveDraftInput,
+  reviseObjectiveDraft,
+} from "../../authoring/objective/draft.ts";
+import {
+  type DreamReportGateOutcome,
+  resolveDreamReportGate,
+} from "../../authoring/objective/dreamReportGate.ts";
+import {
+  OBJECTIVE_AUTHOR_CONTEXT_TYPE,
+  OBJECTIVE_AUTHOR_MARKER,
+  OBJECTIVE_AUTHOR_STAGE,
+  objectiveAuthoringContextContent,
+  objectiveSaveGuidance,
+} from "../../authoring/objective/prose.ts";
+import {
+  type ObjectiveApprovalSaveDeps,
+  type ObjectiveBackend,
+  objectiveApprovalSave,
+  type SaveObjectiveOutcome,
+  saveObjective,
+} from "../../authoring/objective/save.ts";
+import type { ApprovalGate } from "../../authoring/review/approvalGate.ts";
+import { DREAM_REPORT_INPUT_SCHEMA } from "../../learning/dreamReport.ts";
+import { openBranchWorkflowSession } from "../../session/branchWorkflowSession.ts";
+import type { WorkflowSession } from "../../session/workflowSession.ts";
+import { bindingSuffix } from "../../substrate/bindingDelivery.ts";
+import { atomicWriteFileSync, ensureRunScratch } from "../../substrate/cache.ts";
+import {
+  booleanField,
+  type ColdJson,
+  objectField,
+  runColdDoor,
+  stringField,
+} from "../../substrate/coldDoor.ts";
+import { registerPerkCommand } from "../../substrate/command.ts";
+import { loadPerkConfig } from "../../substrate/config.ts";
+import { failFor, ok, type Result } from "../../substrate/result.ts";
+import type { ToolGating } from "../../substrate/toolGating.ts";
+import { arrayParam, objectParam, paramsOf, stringParam } from "../../substrate/toolParams.ts";
+import { type BranchEntry, branchOf, rebuildWorkflowState } from "../../substrate/workflowState.ts";
+import { report, type Severity } from "../../surfaces/report.ts";
+import { installInjectedContext } from "./contextInjection.ts";
+import { type DraftReviewSlot, recordSaveOutcome } from "./draftReview.ts";
+import { OBJECTIVE_BUDGET_TYPE } from "./objective.ts";
+import { productionDreamGateRecovery } from "./objectiveDreamGate.ts";
+import { isRefinementSession, refinementStageRefusal } from "./objectiveRefinement.ts";
+
+// ------------------------------------------------------------------- the tool-boundary decode
+
+/**
+ * The decoded `objective_save` tool params (shared with `objective_draft`) — an ALIAS of the
+ * feature's draft input, not a second handwritten contract: the tool boundary decodes exactly
+ * the shape the feature operations consume (`dream_report` stays opaque here — deep validation
+ * is the gate resolver's; the save path wraps it as its `{input}` carrier arm).
+ */
+export type ObjectiveSaveParams = ObjectiveDraftInput;
+
+/**
+ * The `delivery` enum property, shared between `objective_save` and `objective_draft` so the
+ * two tools' delivery contracts cannot drift. The description bakes in the explicit-human-choice
+ * discipline: the agent must ASK, with incremental recommended.
+ */
+export const DELIVERY_PARAM_SCHEMA = {
+  type: "string",
+  enum: DELIVERY_CHOICES,
+  description:
+    "The reviewed delivery choice — ask the human explicitly (incremental is the recommended " +
+    "default: each plan lands independently; stacked lands ALL non-skipped roadmap nodes as " +
+    "one atomic PR train — capability-checked at save).",
+} as const;
+
+/**
+ * The `dream_report` property, shared between `objective_save` and `objective_draft` so the
+ * two tools' dream contracts cannot drift: the §8.62 `DREAM_REPORT_INPUT_SCHEMA` embedded by
+ * identifier (the `DELIVERY_PARAM_SCHEMA`/`ROADMAP_PARAM_SCHEMA` shared-schema pattern) plus
+ * the gate description. Structurally reachable only inside a `perk learn dream` session (the
+ * resolver refuses it outside one).
+ */
+export const DREAM_REPORT_PARAM_SCHEMA = {
+  ...DREAM_REPORT_INPUT_SCHEMA,
+  description:
+    "The perk learn dream session's final report input (the parent's decisions only) — " +
+    "required inside a dream session, refused outside one.",
+} as const;
+
+/**
+ * The roadmap-node items JSON schema, shared between `objective_save` and `objective_draft`
+ * so the two tools' roadmap contracts cannot drift.
+ */
+export const ROADMAP_PARAM_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: ["id", "description"],
+  properties: {
+    id: { type: "string", description: 'A stable node id, e.g. "1.1".' },
+    description: { type: "string", description: "What this node delivers." },
+    status: {
+      type: "string",
+      enum: ["pending", "planning", "in_progress", "done", "blocked", "skipped"],
+      description: "Optional initial status (defaults to pending).",
+    },
+    slug: { type: "string", description: "Optional short slug." },
+    pr: { type: "string", description: 'Optional plan/PR backlink, e.g. "#42".' },
+    depends_on: {
+      type: "array",
+      items: { type: "string" },
+      description: "Optional explicit dependency node ids.",
+    },
+    comment: { type: "string", description: "Optional note." },
+    adopt_issue: {
+      type: "string",
+      description:
+        "Optional: the id/identifier of a pre-existing source issue this node adopts in place " +
+        "(objective author --from, Linear only).",
+    },
+  },
+} as const;
+
+/**
+ * Decode unknown `objective_save` tool-call params (the tool-boundary seam). `prose`
+ * absent decodes to `""` (so `saveObjective`'s "no objective prose to save" `invalid_input` arm
+ * keeps owning that message) but present-but-mistyped → null (strict-fail). `roadmap` stays
+ * `unknown[]` — the Python cold door owns node-shape validation.
+ */
+export function decodeObjectiveSaveParams(params: unknown): ObjectiveSaveParams | null {
+  const p = paramsOf(params);
+  if (p === null) return null;
+  const prose = stringParam(p, "prose");
+  const title = stringParam(p, "title");
+  const roadmap = arrayParam(p, "roadmap");
+  const base = stringParam(p, "base");
+  const delivery = stringParam(p, "delivery");
+  // `dream_report` must be a plain object when present (absent → undefined); deep validation
+  // stays with the gate resolver (resolveDreamReportGate).
+  const dreamReport = objectParam(p, "dream_report");
+  if (
+    prose === null ||
+    title === null ||
+    roadmap === null ||
+    base === null ||
+    delivery === null ||
+    dreamReport === null
+  ) {
+    return null;
+  }
+  // The delivery enum is strict beyond `string`: an off-enum value is present-but-mistyped.
+  if (delivery !== undefined && !isDeliveryChoice(delivery)) return null;
+  return { prose: prose ?? "", title, roadmap, base, delivery, dream_report: dreamReport };
+}
+
+// -------------------------------------------------------------- the cold-door backend adapter
+
+/**
+ * The run-scoped dream-report transfer filename (contracts §8.64) — the extension→door handoff
+ * carrying the reviewed CANONICAL parts. The Python mirror is
+ * `perk.learn.dream_companion.DREAM_REPORT_TRANSFER_FILENAME` (parity-pinned by test), beside
+ * the existing `DREAM_MANIFEST_FILENAME` mirror pair.
+ */
+export const DREAM_REPORT_TRANSFER_FILENAME = "dream-report-transfer.json";
+
+/** The ok-arm fields — the structured `details` surface doubles as branch-safe persisted state. */
+export interface ObjectiveSaveOk {
+  /** `id` is the opaque string objective id (GitHub "7", Linear "ENG-7") — §8.21. */
+  objective: { id: string; url: string };
+  existed: boolean | null;
+}
+
+export type ObjectiveSaveResult = Result<ObjectiveSaveOk>;
+
+/** The decoded `perk objective create --json` payload slice the warm door consumes. */
+interface ObjectiveCreatePayload {
+  objective: { id: string; url: string; existed: boolean | undefined };
+}
+
+/** Narrow the `perk objective create --json` success payload; strict on `objective`. */
+function decodeObjectiveCreate(payload: ColdJson): ObjectiveCreatePayload | null {
+  const objective = objectField(payload, "objective");
+  if (objective === undefined) return null;
+  const id = stringField(objective, "id");
+  const url = stringField(objective, "url");
+  if (id === undefined || url === undefined) return null;
+  return { objective: { id, url, existed: booleanField(objective, "existed") } };
+}
+
+/**
+ * The production `ObjectiveBackend` over the Python cold door (`perk objective create --json`
+ * via the shared cold-door client; the prose rides the run-scratch stdin channel; `runId: null`
+ * or blank omits `--run-id` — an identity-less save keeps working). On the dream arm
+ * (`dreamParts` present) the reviewed CANONICAL parts cross to the Python plane through the
+ * run-scoped `dream-report-transfer.json` handoff (§8.64) — staged atomically BEFORE the cold
+ * door (a write failure is the soft `scratch_failed` refusal, the runColdDoor stdin-staging
+ * precedent: the door is NOT invoked, nothing activates, the read-only gate stays on) — and
+ * `perk objective create` re-validates the transfer and converges the companion idempotently.
+ * Non-dream saves write nothing (byte-identical).
+ */
+function coldDoorObjectiveBackend(pi: ExtensionAPI, ctx: ExtensionContext): ObjectiveBackend {
+  return {
+    async create(req) {
+      const runId = req.runId ?? "";
+      if (req.dreamParts !== undefined) {
+        try {
+          const dir = ensureRunScratch(ctx.cwd, runId);
+          const content = `${JSON.stringify(
+            { schema_version: "1", run_id: runId, parts: req.dreamParts },
+            null,
+            2,
+          )}\n`;
+          atomicWriteFileSync(join(dir, DREAM_REPORT_TRANSFER_FILENAME), content);
+        } catch (err) {
+          return {
+            status: "failed",
+            message: `could not stage the dream-report transfer: ${String(err)}`,
+            errorType: "scratch_failed",
+          };
+        }
+      }
+      const args = ["objective", "create", "--json"];
+      if (req.title) args.push("--title", req.title);
+      if (req.base) args.push("--base", req.base);
+      // The reviewed delivery choice rides verbatim; the cold door owns validation + preflight.
+      if (req.delivery) args.push("--delivery", req.delivery);
+      if (runId) args.push("--run-id", runId);
+      if (req.roadmap && req.roadmap.length > 0) {
+        args.push("--roadmap", JSON.stringify(req.roadmap));
+      }
+      const r = await runColdDoor<ObjectiveCreatePayload>(pi, ctx, args, {
+        label: "perk objective create",
+        decode: decodeObjectiveCreate,
+        stdin: { flag: "--body", content: req.prose, filename: "objective.md" },
+      });
+      if (!r.ok) return { status: "failed", message: r.message, errorType: r.errorType };
+      return {
+        status: "saved",
+        id: r.data.objective.id,
+        url: r.data.objective.url,
+        existed: r.data.objective.existed ?? null,
+      };
+    },
+  };
+}
+
+// ------------------------------------------------------------------------- adapter plumbing
+
+/** Open the branch-backed session (always opens; `runId: null` is the identity-less arm). */
+function openSession(pi: ExtensionAPI, ctx: ExtensionContext): WorkflowSession {
+  return openBranchWorkflowSession(pi, ctx);
+}
+
+/** The narrow gate slice the feature releases (D1a: exit only after a verified save). */
+function gateFor(gating: ToolGating, ctx: ExtensionContext): ApprovalGate {
+  return { isActive: () => gating.isActive(), exit: () => gating.exit(ctx) };
+}
+
+/** The ctx-bound §8.63 gate resolver the feature ops consume — the resolver over the
+ * runtime-minted production recovery capability (`pi/v1/objectiveDreamGate.ts`). */
+function dreamGateFor(
+  ctx: ExtensionContext,
+): (input: unknown, generatedAt: string) => DreamReportGateOutcome {
+  return (input, generatedAt) =>
+    resolveDreamReportGate(productionDreamGateRecovery(ctx), input, generatedAt);
+}
+
+/**
+ * The production approval→save dependency bag (the `planSaveDepsFor` mirror): session via the
+ * branch backing, the cold-door backend, the gate slice, and the ctx-bound dream-gate resolver.
+ * The review arm + the browser door consume the composed `objectiveApprovalSaveV1` instead.
+ */
+export function objectiveSaveDepsFor(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  gating: ToolGating,
+): ObjectiveApprovalSaveDeps {
+  return {
+    session: openSession(pi, ctx),
+    backend: coldDoorObjectiveBackend(pi, ctx),
+    gate: gateFor(gating, ctx),
+    resolveDreamGate: dreamGateFor(ctx),
+  };
+}
+
+/**
+ * Seed a fresh `perk:objective-budget` activation marker off a successful save whose linkage
+ * differed (mirrors `/objective <id>`'s activation, so budget tracking starts immediately).
+ * Byte-equivalent to the historical `linked !== objectiveId` guard: the seam's `unchanged` is
+ * the equal case, and applied/unverified/rejected all imply "differed" (the marker never keyed
+ * off the append's read-back result).
+ */
+function activateBudgetIfLinked(pi: ExtensionAPI, save: SaveObjectiveOutcome): void {
+  if (save.status !== "saved") return;
+  if (save.linkage === null || save.linkage.status === "unchanged") return;
+  pi.appendEntry(OBJECTIVE_BUDGET_TYPE, {
+    objective_id: save.id,
+    activated_at: new Date().toISOString(),
+  });
+}
+
+/**
+ * Render a save outcome as the warm-door Result envelope (the ONE result-construction site for
+ * every objective save surface — tool, command relay, review arm, browser door). A `saved`
+ * outcome renders the terminating "Saved/Found existing objective #id → url" twin; a `failed`
+ * outcome reports through the `failFor` seam (byte-identical to the failure the save always
+ * rendered).
+ */
+function objectiveSaveResultOf(
+  ctx: ExtensionContext,
+  save: SaveObjectiveOutcome,
+): ObjectiveSaveResult {
+  if (save.status === "failed") {
+    return failFor(ctx, "objective-save")(save.message, save.errorType);
+  }
+  const verb = save.existed ? "Found existing" : "Saved";
+  return ok(
+    `${verb} objective #${save.id} → ${save.url}`,
+    {
+      objective: { id: save.id, url: save.url },
+      existed: save.existed,
+    },
+    { terminate: true },
+  );
+}
+
+/** The approval→save orchestration outcome, rendered (the door/arm-facing twin).
+ * `refused-draft` passes through unrendered — no `result`, no `gateExited`: nothing was saved,
+ * the gate was never touched, and no budget activation runs. */
+export type ObjectiveApprovalSaveV1Outcome =
+  | { status: "no-draft" }
+  | { status: "refused-draft"; problem: string }
+  | { status: "saved" | "save-failed"; result: ObjectiveSaveResult; gateExited: boolean };
+
+/**
+ * The composed approval→save twin (the shape `plan_review`'s objective arm, the browser door,
+ * and the `/objective-save` failsafe consume): run the feature's `objectiveApprovalSave` over
+ * the production deps, seed the budget activation marker off a linked save, and render the
+ * Result envelope. Flow semantics live in the feature op (artifact re-read, D1a gate exit,
+ * §8.63 re-validation); this twin owns only composition + rendering.
+ */
+export async function objectiveApprovalSaveV1(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  gating: ToolGating,
+  opts: { title?: string } = {},
+): Promise<ObjectiveApprovalSaveV1Outcome> {
+  return renderObjectiveApprovalSave(
+    pi,
+    ctx,
+    await objectiveApprovalSave(objectiveSaveDepsFor(pi, ctx, gating), opts),
+  );
+}
+
+/** Preserve the subject's linkage-budget and rendered save policy for explicit owned sessions. */
+export function renderObjectiveApprovalSave(
+  pi: ExtensionAPI,
+  ctx: ExtensionContext,
+  outcome: Awaited<ReturnType<typeof objectiveApprovalSave>>,
+): ObjectiveApprovalSaveV1Outcome {
+  if (outcome.status === "no-draft") return { status: "no-draft" };
+  if (outcome.status === "refused-draft") {
+    return { status: "refused-draft", problem: outcome.problem };
+  }
+  activateBudgetIfLinked(pi, outcome.result);
+  return {
+    status: outcome.status,
+    result: objectiveSaveResultOf(ctx, outcome.result),
+    gateExited: outcome.gateExited,
+  };
+}
+
+/**
+ * Whether the current branch is an objective-author session (read-only gate AND stage match).
+ * Fail-closed: a throwing state rebuild reports false, so no objective-authoring guidance is
+ * selected. (The runner fence lives in the shared injection helper.)
+ */
+function isObjectiveAuthoring(gating: ToolGating, branch: readonly BranchEntry[]): boolean {
+  if (!gating.isActive()) return false;
+  try {
+    return rebuildWorkflowState(branch).stage === OBJECTIVE_AUTHOR_STAGE;
+  } catch {
+    return false;
+  }
+}
+
+// ------------------------------------------------------------------------------ the installer
+
+const DRAFT_TOOL_GUIDELINES = [
+  "Call objective_draft to persist the current working objective as you author or revise it; pass the FULL prose and the FULL structured roadmap each time (it rewrites the whole draft).",
+  "objective_draft never saves to GitHub and never ends the turn — objective_save//objective-save remain the canonical save surface. Never hand-write roadmap YAML — hand the structured roadmap to the tool.",
+  "Pass objective_draft's `base` only to target a non-default branch; omit it to use the repo default.",
+];
+
+const SAVE_TOOL_GUIDELINES = [
+  "Use objective_save only after the objective + roadmap are decision-complete; it creates the canonical perk:objective issue, activates it, and ends the turn.",
+  "Pass objective_save the objective PROSE in `prose` and the STRUCTURED roadmap in `roadmap` (a JSON array of nodes) — never hand-write roadmap YAML.",
+  'Each objective_save roadmap node needs a stable `id` (e.g. "1.1") and a `description`; `status` defaults to pending. Use `depends_on` for explicit ordering.',
+];
+
+/**
+ * Install every objective-authoring Pi binding: the objective-authoring context hook pair (the
+ * frozen hooks-ordering slot index.ts calls this at — planMode.ts defers when the stage is
+ * objective-author, so exactly one authoring context is injected), the `objective_draft` and
+ * `objective_save` tools, and the `/objective-save` command — registration metadata pinned by
+ * the registration-parity tests. Inert outside objective sessions; never throws.
+ */
+export function installObjectiveAuthoringBindings(
+  pi: ExtensionAPI,
+  gating: ToolGating,
+  reviews: DraftReviewSlot,
+  runnerChild: () => boolean,
+): void {
+  // The objective-authoring context injection (display:false), keyed off (read-only gate AND
+  // stage === objective-author); the inject/strip mechanics (active-window dedup,
+  // selection-driven retention) and the runner fence live in the shared helper.
+  installInjectedContext(
+    pi,
+    {
+      customType: OBJECTIVE_AUTHOR_CONTEXT_TYPE,
+      flavors: {
+        [OBJECTIVE_AUTHOR_MARKER]: (ctx) =>
+          objectiveAuthoringContextContent(loadPerkConfig(ctx.cwd).planAuthoring),
+      },
+      select: (_ctx, branch) =>
+        isObjectiveAuthoring(gating, branch) ? OBJECTIVE_AUTHOR_MARKER : null,
+    },
+    runnerChild,
+  );
+
+  pi.registerTool({
+    name: "objective_draft",
+    label: "Objective draft",
+    description:
+      "Write (or overwrite) the working objective draft — prose + the structured roadmap — to " +
+      "the session data dir and record its provenance pointer. The only sanctioned write surface " +
+      "while read-only. NOT a save — objective_save//objective-save still persist the objective " +
+      "to GitHub.",
+    promptSnippet:
+      "Persist the working objective draft (prose + structured roadmap) to the session data dir (full rewrite)",
+    promptGuidelines: DRAFT_TOOL_GUIDELINES,
+    executionMode: "sequential",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      required: ["prose"],
+      properties: {
+        prose: {
+          type: "string",
+          description: "The objective prose (the why, the design, the boundaries/non-goals).",
+        },
+        title: {
+          type: "string",
+          description: "Optional objective title (defaults to the prose's first heading).",
+        },
+        base: {
+          type: "string",
+          description:
+            "Optional target branch for this objective's plans (omit to use the repo default).",
+        },
+        delivery: DELIVERY_PARAM_SCHEMA,
+        dream_report: DREAM_REPORT_PARAM_SCHEMA,
+        roadmap: {
+          type: "array",
+          description:
+            "The structured roadmap: a JSON array of nodes. Never hand-write roadmap YAML.",
+          items: ROADMAP_PARAM_SCHEMA,
+        },
+      },
+    },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      // The shared param contract: the same decode as `objective_save`, so the two cannot
+      // drift. (The parameter literals are duplicated at both registration sites on purpose —
+      // the prose-review workbench needs in-place literals — and pinned identical by the
+      // registration baselines.)
+      const decoded = decodeObjectiveSaveParams(params);
+      if (decoded === null) {
+        return failFor(
+          ctx,
+          "objective-draft",
+          "objective_draft",
+        )(
+          "objective_draft needs { prose: string, roadmap?: array } per the tool schema",
+          "bad_input",
+        );
+      }
+      const fail = failFor(ctx, "objective-draft");
+      const revised = reviseObjectiveDraft(decoded, {
+        session: openSession(pi, ctx),
+        resolveDreamGate: dreamGateFor(ctx),
+      });
+      switch (revised.status) {
+        case "revised":
+        case "unchanged":
+          // A byte-identical rewrite short-circuits interior-side; the rendered result is
+          // computed from identical content either way, so the surface stays byte-stable.
+          return ok(
+            `Objective draft written → ${revised.receipt.path} (${revised.receipt.digest}; ` +
+              `${revised.roadmapNodes} roadmap nodes)`,
+            {
+              name: OBJECTIVE_DRAFT_ARTIFACT,
+              path: revised.receipt.path,
+              digest: revised.receipt.digest,
+              bytes: revised.bytes,
+              run_id: revised.receipt.runId,
+              roadmap_nodes: revised.roadmapNodes,
+            },
+          );
+        case "rejected":
+          return fail(revised.problem, revised.errorType);
+        case "unverified":
+          return fail(revised.problem, "write_failed");
+      }
+    },
+  });
+
+  pi.registerTool({
+    name: "objective_save",
+    label: "Save objective",
+    description:
+      "Persist a drafted objective + structured roadmap to GitHub as a perk:objective issue, " +
+      "activate it, and start budget tracking. Terminating: ends the turn on save. Call only when " +
+      "the objective and roadmap are decision-complete.",
+    promptSnippet: "Save the decision-complete objective + roadmap to GitHub (terminates the turn)",
+    promptGuidelines: SAVE_TOOL_GUIDELINES,
+    executionMode: "sequential",
+    parameters: {
+      type: "object",
+      additionalProperties: false,
+      required: ["prose"],
+      properties: {
+        prose: {
+          type: "string",
+          description: "The objective prose (the why, the design, the boundaries/non-goals).",
+        },
+        title: {
+          type: "string",
+          description: "Optional objective title (defaults to the prose's first heading).",
+        },
+        base: {
+          type: "string",
+          description:
+            "Optional target branch for this objective's plans (omit to use the repo default).",
+        },
+        delivery: DELIVERY_PARAM_SCHEMA,
+        dream_report: DREAM_REPORT_PARAM_SCHEMA,
+        roadmap: {
+          type: "array",
+          description:
+            "The structured roadmap: a JSON array of nodes. Never hand-write roadmap YAML.",
+          items: ROADMAP_PARAM_SCHEMA,
+        },
+      },
+    },
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const decoded = decodeObjectiveSaveParams(params);
+      if (decoded === null) {
+        return failFor(
+          ctx,
+          "objective-save",
+          "objective_save",
+        )(
+          "objective_save needs { prose: string, roadmap?: array } per the tool schema",
+          "bad_input",
+        );
+      }
+      // A refinement session never creates an objective — independent of tool visibility.
+      if (isRefinementSession(branchOf(ctx)))
+        return failFor(ctx, "objective_save")(
+          refinementStageRefusal("objective_save"),
+          "wrong_stage",
+        );
+      // The direct tool path wraps ONLY a present decoded value as the union's `direct` arm
+      // (the save stamps generated_at); no stored parts, so no byte-compare on this path.
+      const { dream_report, ...rest } = decoded;
+      const save = await saveObjective(
+        {
+          ...rest,
+          ...(dream_report !== undefined
+            ? { dream_report: { source: "direct" as const, input: dream_report } }
+            : {}),
+        },
+        objectiveSaveDepsFor(pi, ctx, gating),
+      );
+      // The manual save never consults the latch (it IS the deliberate retry) but reports into it.
+      recordSaveOutcome(reviews, "objective", {
+        confirmed: save.status === "saved",
+        ...(save.status === "failed" ? { detail: save.message } : {}),
+      });
+      activateBudgetIfLinked(pi, save);
+      return objectiveSaveResultOf(ctx, save);
+    },
+  });
+
+  registerPerkCommand(pi, "objective-save", {
+    description:
+      "Save the working objective draft to GitHub — the manual failsafe for the approval→save " +
+      "flow (artifact-first; drives the structured save only when no draft exists).",
+    handler: async (args, ctx) => {
+      if (isRefinementSession(branchOf(ctx))) {
+        report(ctx, "objective-save", "warning", refinementStageRefusal("/objective-save"));
+        return;
+      }
+      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 drive-the-session fallback covers
+      // draft-LESS sessions — objectives have no transcript scrape by design, so a draftless
+      // session still needs a working save path.
+      const outcome = await objectiveApprovalSaveV1(pi, ctx, gating, { title });
+      // The manual save never consults the latch (it IS the deliberate retry) but reports into it.
+      if (outcome.status === "saved" || outcome.status === "save-failed")
+        recordSaveOutcome(reviews, "objective", {
+          confirmed: outcome.status === "saved",
+          ...(outcome.result.details.ok ? {} : { detail: outcome.result.details.error }),
+        });
+      if (outcome.status === "refused-draft") {
+        // Fail-closed stop: the command's own precondition is a VALID draft — no gate exit,
+        // no driven turn (those fallbacks are for draft-LESS sessions; driving a fresh
+        // model-authored save over a corrupted artifact would silently abandon its bytes).
+        report(
+          ctx,
+          "objective-save",
+          "error",
+          `the working objective draft is invalid: ${outcome.problem} — rewrite it with ` +
+            "objective_draft, then re-run /objective-save",
+        );
+        return;
+      }
+      if (outcome.status === "no-draft") {
+        // Exit the read-only gate so the objective_save tool (excluded from READ_ONLY_TOOLS)
+        // becomes reachable on the driven turn, then drive the turn (mirrors /address and
+        // /objective-plan).
+        if (gating.isActive()) gating.exit(ctx);
+        report(ctx, "objective-save", "info", "handing the structured save to the session");
+        // The perk-objective-author pointer rides the skill-binding suffix (D5) since a
+        // warm /objective-save outside a stage:objective-author session gets none from Mechanism A.
+        pi.sendUserMessage(
+          objectiveSaveGuidance(title) + bindingSuffix(ctx.cwd, "stage:objective-author"),
+        );
+        return;
+      }
+      // Saved or save-failed: relay the save message. No node-link sub-step on the objective path,
+      // so the severity ladder is simpler than /plan-save's (no warning tier).
+      const result = outcome.result;
+      const message = result.content[0]?.text ?? "objective-save done";
+      const severity: Severity = result.details.ok ? "info" : "error";
+      report(ctx, "objective-save", severity, message);
+    },
+  });
+}