@mgiles/perk 3.1.0 → 3.3.0

package/extension/authoring/objective/planning.ts

@@ -0,0 +1,124 @@
+// The objective planning feature: the roadmap-node → plan-generation policy — the bounded
+// node-transition operation (with the completion-audit gate and the warm node-claim carrier
+// maintenance). The reconcile/add-node writes carry no feature policy beyond their decoders,
+// so they live adapter-tier in pi/v1/objectivePlanning.ts (direct cold-door calls — no port).
+//
+// The completion-audit gate is a property of the MODEL-FACING boundary only — NOT an invariant
+// on the node-`done` state: the canonical `perk objective node --status done` (human/CI cold
+// CLI) has no audit gate, and the auto-on-merge node-done deliberately sets `done` without one.
+// Both are intentional non-audited paths; the structural refusal protects the model's path
+// only. The "are we done?" judgment text lives in the perk-objective-plan skill.
+//
+// Decode-once-at-the-edge: inputs arrive TYPED (the pi/v1 decoders own the tool-boundary
+// shape), so the ops re-validate nothing. Canonical mutations stay in the Python plane — the
+// backends delegate; the objective's canonical state is the issue (re-read on demand), and the
+// only session state these ops maintain is the warm `objective_node_claim` carrier, THROUGH the
+// session seam.
+
+import type { WorkflowChangeResult, WorkflowSession } from "../../session/workflowSession.ts";
+
+/** The valid node statuses (mirrors the Python `objective.NodeStatus` StrEnum). */
+export const NODE_STATUSES = [
+  "pending",
+  "planning",
+  "in_progress",
+  "done",
+  "blocked",
+  "skipped",
+] as const;
+export type NodeStatus = (typeof NODE_STATUSES)[number];
+
+/** The minimum trimmed length of a non-trivial completion `audit` (the pinnable predicate). */
+export const MIN_AUDIT_LENGTH = 40;
+
+/** A non-trivial audit iff it is a string whose value after `.trim()` is ≥ MIN_AUDIT_LENGTH. */
+export function isNonTrivialAudit(audit: unknown): boolean {
+  return typeof audit === "string" && audit.trim().length >= MIN_AUDIT_LENGTH;
+}
+
+/** The typed `objective_node` input (`objective` is the opaque §8.21 string id). */
+export interface ObjectiveNodeInput {
+  objective: string;
+  node: string;
+  status?: NodeStatus;
+  pr?: string;
+  description?: string;
+  audit?: string;
+}
+
+/** The narrow exterior port the node transition writes through (the cold door in pi/v1). */
+export interface ObjectiveNodeBackend {
+  transition(req: {
+    objective: string;
+    node: string;
+    status?: NodeStatus;
+    pr?: string;
+    description?: string;
+  }): Promise<
+    | { status: "ok"; commentUpdated: boolean }
+    | { status: "failed"; message: string; errorType: string }
+  >;
+}
+
+/**
+ * The transition outcome. `claimChange` is the session seam's own `WorkflowChangeResult`
+ * VERBATIM (`null` = not attempted: a pr/description-only call leaves the carrier untouched);
+ * the adapter's rendering ignores it (the seam's report() stays the loudness channel — a failed
+ * claim append never fails the tool result).
+ */
+export type TransitionObjectiveNodeOutcome =
+  | { status: "ok"; commentUpdated: boolean; claimChange: WorkflowChangeResult | null }
+  | { status: "failed"; message: string; errorType: string };
+
+/**
+ * The bounded `objective_node` transition: the completion-audit gate (`status:"done"` requires
+ * a non-trivial `audit` — model-path-only) → the no-change refusal (neither status nor pr nor
+ * description) → `backend.transition` → on success, maintain the warm node-link carrier
+ * THROUGH THE SEAM: `planning` records the claim (the exact moment the warm factory learns the
+ * node id; an idempotent re-claim short-circuits `unchanged`); any other explicit status clears
+ * it (the seam's both-field match — an unrelated claim is never clobbered); no status change
+ * leaves it untouched. Never throws.
+ */
+export async function transitionObjectiveNode(
+  input: ObjectiveNodeInput,
+  deps: { backend: ObjectiveNodeBackend; session: WorkflowSession },
+): Promise<TransitionObjectiveNodeOutcome> {
+  // The completion-audit gate (model-path-only): `status:"done"` requires a non-trivial `audit`.
+  if (input.status === "done" && !isNonTrivialAudit(input.audit)) {
+    return {
+      status: "failed",
+      message:
+        `setting a node to "done" requires a completion audit (a requirement→evidence mapping of ` +
+        `at least ${MIN_AUDIT_LENGTH} characters) — confirm the work actually landed first.`,
+      errorType: "audit_required",
+    };
+  }
+  if (input.status === undefined && input.pr === undefined && input.description === undefined) {
+    return {
+      status: "failed",
+      message: "objective_node needs a `status`, a `pr`, or a `description` to change",
+      errorType: "bad_input",
+    };
+  }
+
+  const transitioned = await deps.backend.transition({
+    objective: input.objective,
+    node: input.node,
+    ...(input.status !== undefined ? { status: input.status } : {}),
+    ...(input.pr !== undefined ? { pr: input.pr } : {}),
+    ...(input.description !== undefined ? { description: input.description } : {}),
+  });
+  if (transitioned.status === "failed") return transitioned;
+
+  // Maintain the warm node-link carrier off the successful transition (best-effort: a failed
+  // append is loud via the seam's report() but never fails the tool result).
+  let claimChange: WorkflowChangeResult | null = null;
+  if (input.status !== undefined) {
+    const claim = { objective: input.objective, node: input.node };
+    claimChange =
+      input.status === "planning"
+        ? deps.session.apply({ kind: "record-node-claim", claim })
+        : deps.session.apply({ kind: "clear-node-claim", claim });
+  }
+  return { status: "ok", commentUpdated: transitioned.commentUpdated, claimChange };
+}

package/extension/authoring/objective/prose.ts

@@ -0,0 +1,103 @@
+// Feature-owned prose + identity constants for the objective flows — the stage ids the
+// providers/doors key off, the objective-authoring context (contracts.md §8.57: live state +
+// pointers only; the flow is stated by the launch statement, the detail by the bound skill),
+// and the seed guidance the warm doors inject (`/objective-plan`, `/objective-reconcile`,
+// `/objective-save`). Everything renders through the shared template seam
+// (`substrate/prompts.ts` — a mechanism import, §8.31); branching stays in code.
+//
+// Pi-free (guard Rule D covers `authoring/` by prefix). Tool-guideline arrays deliberately do
+// NOT live here: they stay inline at the `pi/v1` registration sites (the prose-review
+// workbench's source-shape constraint).
+
+import { render } from "../../substrate/prompts.ts";
+
+/** The registry stage id of the objective-authoring session (shared with planMode's defer check). */
+export const OBJECTIVE_AUTHOR_STAGE = "objective-author";
+
+/** The registry stage id of the structured-save session (`perk objective save`). */
+export const OBJECTIVE_SAVE_STAGE = "objective-save";
+
+/** The objective-authoring context customType (distinct from planMode's `perk:plan-context`). */
+export const OBJECTIVE_AUTHOR_CONTEXT_TYPE = "perk:objective-author-context";
+
+/** The dedup/strip marker carried by the injected objective-authoring context. */
+export const OBJECTIVE_AUTHOR_MARKER = "[OBJECTIVE AUTHORING]";
+
+/**
+ * The objective-authoring session context: live state + pointers only (contracts.md §8.57 — the
+ * flow is stated by the launch statement, the detail by the `perk-objective-author` skill). It
+ * names the working-draft artifact (`objective_draft`), the review tool (`plan_review`), and
+ * the bound skill; it never restates the flow. Prompting, NOT enforcement (the tool gate is the
+ * enforcement).
+ */
+export const OBJECTIVE_AUTHORING_CONTEXT = render("contexts/objective-authoring.md", {
+  marker: OBJECTIVE_AUTHOR_MARKER,
+});
+
+/**
+ * Build the full objective-authoring injection, appending the project-config addendum when
+ * present. Pure: the adapter passes `loadPerkConfig(cwd).planAuthoring` (the same `[workflow]
+ * plan_authoring` addendum the plan-authoring injection consumes — verbatim reuse).
+ */
+export function objectiveAuthoringContextContent(addendum: string | undefined): string {
+  return addendum
+    ? `${OBJECTIVE_AUTHORING_CONTEXT}\n\n${addendum.trim()}`
+    : OBJECTIVE_AUTHORING_CONTEXT;
+}
+
+/**
+ * Backend-aware supplemental clause for the objective-read step of the factory prompts.
+ * The wording lives in `prompts/common/objective-read/linear.md`, rendered identically by both
+ * planes via the shared render seam (contracts.md §8.31); branching stays in code. github (and any
+ * non-linear) → "" (the `perk objective show` step already covers it); linear → the Project URL +
+ * the linear_get_issue/linear_list_comments tools (an `open <url>` fallback when the url is known).
+ */
+export function objectiveReadInstruction(
+  backend: string,
+  objectiveId: string,
+  url: string,
+): string {
+  if (backend !== "linear") return "";
+  const where = url ? `(${url})` : `(run \`perk objective show ${objectiveId}\` for its URL)`;
+  const fallback = url ? `; if the linear tools are unavailable, open ${url}` : "";
+  return render("common/objective-read/linear.md", { where, fallback });
+}
+
+/** The seed guidance the warm `/objective-plan` injects to start the factory loop (the
+ * perk-objective-plan skill pointer rides the skill-binding suffix — not hardcoded).
+ * The loop is file-first (`plan_draft` → `plan_review` → approval-driven save); the node link
+ * rides the `objective_node_claim` carrier recorded by the unconditional `planning` mark.
+ * The OPTIONAL explore step is ONE `explore_objective_node` call — the tool owns the wave
+ * mechanics, the report schema, and reads the configured `[models.subagents] objective-explorer`
+ * model at execute time. */
+export function factoryGuidance(
+  objective: string,
+  node: string | null,
+  backend = "github",
+  url = "",
+): string {
+  const readClause = objectiveReadInstruction(backend, objective, url);
+  return render("stages/objective-plan/guidance.md", {
+    objective,
+    node: node ?? "",
+    read_clause: readClause,
+  });
+}
+
+/** The seed guidance the warm `/objective-reconcile` injects to start the reconcile pass (the
+ * perk-objective-reconcile skill pointer rides the skill-binding suffix — not
+ * hardcoded). */
+export function reconcileGuidance(objective: string, backend = "github", url = ""): string {
+  const readClause = objectiveReadInstruction(backend, objective, url);
+  return render("stages/objective-reconcile.md", { objective, read_clause: readClause });
+}
+
+/**
+ * The seed guidance the warm `/objective-save` injects to drive the structured save (the
+ * perk-objective-author skill pointer rides the skill-binding suffix — not hardcoded
+ * here). Pure + exported for offline tests.
+ */
+export function objectiveSaveGuidance(title?: string): string {
+  const named = title?.trim() || "";
+  return render("stages/objective-save.md", { title: named });
+}

package/extension/authoring/objective/review.ts

@@ -0,0 +1,128 @@
+// The objective review feature: the `ObjectiveDraftReviewer` role (one production adapter per
+// review backend — plannotator bridge or first-party editor, both built in pi/v1 — plus a
+// scripted fake in the tests) and the one-entry `reviewObjectiveDraft` operation.
+//
+// Ordering is the review door's exact discipline: resume FIRST (the validated artifact only —
+// objectives have no param/transcript tier; none ⇒ `noDraft`) → render (the reviewed bytes are
+// ALWAYS the rendered markdown — the review-surface law: JSON is storage/transport, never the
+// human surface) → review → the abort checkpoint → route the verdict. Provider vocabulary
+// (plannotator's `# Direct Edits` heading) is translated INTO `ObjectiveReviewOutcome` at the
+// adapter — the feature sees typed variants only.
+//
+// No implement-here arm (the no-save exit is plan-arm-only — contracts §8.23) and no
+// edited-bytes channel: objective reviews are VIEW-ONLY (rendered-markdown edits cannot fold
+// back into the structured draft mechanically), so `approvedDirectEdits` is the revise-round
+// refusal arm — NOTHING saved, the gate untouched; deny+feedback is the change channel.
+//
+// Cancellation ownership: `signal?.aborted` is checked at entry AND re-checked immediately
+// after `reviewer.review` resolves, BEFORE any effect (save, gate exit) — abort ⇒ the `aborted`
+// arm with nothing saved and the gate untouched.
+
+import type { WorkflowSession } from "../../session/workflowSession.ts";
+import { renderObjectiveDraft, resumeObjectiveDraft } from "./draft.ts";
+
+/**
+ * The reviewer's verdict on the rendered objective bytes. `approvedDirectEdits` carries the
+ * FULL raw feedback (the adapter renders the revise-round guidance with it); the heading check
+ * that produces it stays adapter-side (provider vocabulary).
+ */
+export type ObjectiveReviewOutcome =
+  | { status: "approved"; feedback?: string; reviewId?: string }
+  | { status: "approvedDirectEdits"; rawFeedback: string; reviewId?: string }
+  | { status: "denied"; feedback?: string; reviewId?: string }
+  | { status: "dismissed" }
+  | { status: "aborted" }
+  | { status: "unavailable"; warning: string };
+
+/** The reviewer role: judge the rendered objective markdown (view-only). */
+export interface ObjectiveDraftReviewer {
+  review(rendered: string, signal?: AbortSignal): Promise<ObjectiveReviewOutcome>;
+}
+
+/**
+ * The structural approval-save shape the review op routes over. The adapter binds a RICHER twin
+ * (`objectiveApprovalSaveV1` — arms carrying rendered results + `gateExited`); the arms flow
+ * through VERBATIM via the generic, so no information is erased and no cast is needed.
+ */
+export interface ObjectiveApprovalSaveShape {
+  status: "no-draft" | "refused-draft" | "saved" | "save-failed";
+}
+
+/** The one-entry review outcome — each arm carries exactly what its caller renders.
+ * `refusedDraft` is the pre-review fail-closed stop for an invalid artifact (the approval-time
+ * race arm rides the save shape verbatim through `approvedSave`). */
+export type ReviewObjectiveDraftResult<A extends ObjectiveApprovalSaveShape> =
+  | { status: "noDraft" }
+  | { status: "refusedDraft"; problem: string }
+  | { status: "approvedSave"; save: A; feedback?: string; reviewId?: string }
+  | { status: "approvedDirectEdits"; rawFeedback: string; reviewId?: string }
+  | { status: "denied"; feedback?: string; reviewId?: string }
+  | { status: "dismissed" }
+  | { status: "aborted" }
+  | { status: "unavailable"; warning: string };
+
+/**
+ * Review the working objective draft end-to-end: resume (none ⇒ `noDraft` — the adapter renders
+ * the `no_objective_draft` skip) → render → review → the abort checkpoint → route. Routing:
+ * `approved` ⇒ `approvalSave()` (the injected orchestration re-resumes the draft itself — the
+ * artifact is the save source, never the rendered bytes; one extra validated read, no
+ * observable delta) · `approvedDirectEdits` ⇒ the revise-round refusal arm — NOTHING saved, the
+ * gate untouched · `denied`/`dismissed`/`aborted`/`unavailable` pass through. Never throws.
+ */
+export async function reviewObjectiveDraft<A extends ObjectiveApprovalSaveShape>(
+  deps: {
+    session: WorkflowSession;
+    reviewer: ObjectiveDraftReviewer;
+    approvalSave: () => Promise<A>;
+  },
+  signal?: AbortSignal,
+): Promise<ReviewObjectiveDraftResult<A>> {
+  if (signal?.aborted) return { status: "aborted" };
+  const resumed = resumeObjectiveDraft(deps.session);
+  if (resumed.kind === "absent") return { status: "noDraft" };
+  if (resumed.kind === "refused") return { status: "refusedDraft", problem: resumed.problem };
+
+  const outcome = await deps.reviewer.review(renderObjectiveDraft(resumed.draft), signal);
+  // The abort checkpoint: a turn interrupted while the reviewer ran must produce NO effect —
+  // no save, no gate exit (the aborted arm wins over any verdict).
+  if (signal?.aborted) return { status: "aborted" };
+
+  return completeObjectiveReview(outcome, deps.approvalSave);
+}
+
+/** Subject policy only: callers authorize effects before entering this completion seam. */
+export async function completeObjectiveReview<A extends ObjectiveApprovalSaveShape>(
+  outcome: ObjectiveReviewOutcome,
+  approvalSave: () => Promise<A>,
+): Promise<ReviewObjectiveDraftResult<A>> {
+  switch (outcome.status) {
+    case "approved":
+      return {
+        status: "approvedSave",
+        save: await approvalSave(),
+        ...(outcome.feedback !== undefined ? { feedback: outcome.feedback } : {}),
+        ...(outcome.reviewId !== undefined ? { reviewId: outcome.reviewId } : {}),
+      };
+    case "approvedDirectEdits":
+      // The revise-round refusal: rendered-markdown edits cannot fold back into the structured
+      // draft mechanically — nothing saved, the gate untouched; the adapter renders the
+      // revise guidance with the FULL feedback.
+      return {
+        status: "approvedDirectEdits",
+        rawFeedback: outcome.rawFeedback,
+        ...(outcome.reviewId !== undefined ? { reviewId: outcome.reviewId } : {}),
+      };
+    case "denied":
+      return {
+        status: "denied",
+        ...(outcome.feedback !== undefined ? { feedback: outcome.feedback } : {}),
+        ...(outcome.reviewId !== undefined ? { reviewId: outcome.reviewId } : {}),
+      };
+    case "dismissed":
+      return { status: "dismissed" };
+    case "aborted":
+      return { status: "aborted" };
+    case "unavailable":
+      return { status: "unavailable", warning: outcome.warning };
+  }
+}

package/extension/authoring/objective/save.ts

@@ -0,0 +1,224 @@
+// The objective save feature: the narrow exterior `ObjectiveBackend` port (one production
+// adapter — the `perk objective create` cold door in pi/v1 — plus one deterministic fake in the
+// tests: the port admission rule), the `saveObjective` operation, and the shared
+// APPROVED-review → save orchestration `objectiveApprovalSave` (the `gistApprovalSave`/
+// `planApprovalSave` mirror — three sibling flows, deliberately unshared shapes).
+//
+// Identity-less saves stay legal: `session.runId === null` ⇒ the backend sees `runId: null`
+// (the adapter omits `--run-id`) and the LINKAGE op still runs — workflow-state appends are
+// branch-backed and identity-independent (today's behavior, preserved). Backend saves are not
+// abortable mid-flight (stated, not changed).
+//
+// The §8.63 dream gate arrives INJECTED (ctx-bound by the adapter); the §8.64 transfer staging
+// (the reviewed CANONICAL parts crossing to the Python plane) is the ADAPTER's — the port's
+// `dreamParts` carries the gate-proven parts and the adapter stages the run-scoped
+// `dream-report-transfer.json` handoff atomically before the cold door.
+
+import type { WorkflowChangeResult, WorkflowSession } from "../../session/workflowSession.ts";
+import { type ApprovalGate, saveThroughApprovalGate } from "../review/approvalGate.ts";
+import type { DeliveryChoice } from "./draft.ts";
+import { resumeObjectiveDraft } from "./draft.ts";
+import type { DreamReportGateOutcome, ObjectiveDreamReportBlock } from "./dreamReportGate.ts";
+
+/** The backend save facts (`id` is the opaque string objective id — contracts §8.21). */
+export type ObjectiveBackendSaveResult =
+  | { status: "saved"; id: string; url: string; existed: boolean | null }
+  | { status: "failed"; message: string; errorType: string };
+
+/**
+ * The narrow exterior port the save operation writes through. `runId: null` means the caller
+ * has no session identity — the adapter omits its run linkage (an identity-less save keeps
+ * working). `dreamParts` (the §8.63 gate-proven CANONICAL parts) makes the adapter stage the
+ * §8.64 transfer handoff before invoking the door.
+ */
+export interface ObjectiveBackend {
+  create(req: {
+    prose: string;
+    title?: string;
+    base?: string;
+    delivery?: DeliveryChoice;
+    roadmap?: unknown[];
+    runId: string | null;
+    dreamParts?: string[];
+  }): Promise<ObjectiveBackendSaveResult>;
+}
+
+/**
+ * The §8.63 dream-report carrier's two proven sources, as a discriminated union so a partial
+ * "reviewed" bag cannot compile: the direct tool path supplies only the raw `input` (the save
+ * stamps `generated_at` fresh); the approval path passes the reviewed artifact block through
+ * WHOLE — stored stamp AND stored parts (byte-compared against the fresh re-render).
+ */
+export type DreamReportCarrier =
+  | { source: "direct"; input: unknown }
+  | { source: "reviewed"; block: ObjectiveDreamReportBlock };
+
+/** The typed save input — decode owns the shape at the tool boundary (pi/v1). */
+export interface SaveObjectiveInput {
+  prose: string;
+  title?: string;
+  roadmap?: unknown[];
+  base?: string;
+  delivery?: DeliveryChoice;
+  dream_report?: DreamReportCarrier;
+}
+
+/**
+ * The save outcome. The saved arm carries the backend facts plus the session seam's own
+ * `WorkflowChangeResult` linkage VERBATIM (the `SavePlanOutcome` precedent; `null` = not
+ * attempted — a failed save never touches the session). The adapter renders the terminating
+ * "Saved/Found existing objective #id → url" twin and appends the budget activation marker iff
+ * the linkage was attempted and not `unchanged` (byte-equivalent to the historical
+ * `linked !== objectiveId` guard — applied/unverified/rejected all imply "differed", and the
+ * marker never keyed off the append's read-back result).
+ */
+export type SaveObjectiveOutcome =
+  | {
+      status: "saved";
+      id: string;
+      url: string;
+      existed: boolean | null;
+      linkage: WorkflowChangeResult | null;
+    }
+  | { status: "failed"; message: string; errorType: string };
+
+/** The dependency bag the save operation runs over (the adapter composes production values). */
+export interface ObjectiveSaveDeps {
+  session: WorkflowSession;
+  backend: ObjectiveBackend;
+  /** The §8.63 gate, adapter-bound (`resolveDreamReportGate` over the production recovery capability). */
+  resolveDreamGate: (input: unknown, generatedAt: string) => DreamReportGateOutcome;
+}
+
+/**
+ * The single save operation every objective-save surface calls. Ordering preserved exactly:
+ * validate the non-blank prose → the §8.63 fail-closed gate re-validation (presence is the
+ * `input.dream_report === undefined` boundary — an `{input: undefined}` carrier is never
+ * constructed) → the approval path's stored-parts byte-compare (the same stored `generated_at`
+ * stamp keeps the comparison deterministic; drift/tamper between draft-write and save refuses
+ * `bad_state`, nothing saved) → `backend.create` with `runId: session.runId` → on success,
+ * link the live session (`apply({kind: "link-objective"})` — the seam appends iff the rebuilt
+ * `active_objective` differs, strict read-back). Whitespace-only `title`/`base` normalize to
+ * absent (trim-or-omit, matching the draft path — a blank `--title` can no longer reach the
+ * cold door). Never throws.
+ */
+export async function saveObjective(
+  input: SaveObjectiveInput,
+  deps: ObjectiveSaveDeps,
+): Promise<SaveObjectiveOutcome> {
+  const prose = input.prose.trim();
+  if (!prose) {
+    return {
+      status: "failed",
+      message: "no objective prose to save (draft the objective first)",
+      errorType: "invalid_input",
+    };
+  }
+  const title = input.title?.trim() || undefined;
+  const base = input.base?.trim() || undefined;
+
+  const carrier = input.dream_report;
+  const generatedAt =
+    carrier?.source === "reviewed" ? carrier.block.generated_at : new Date().toISOString();
+  const gate =
+    carrier === undefined
+      ? deps.resolveDreamGate(undefined, generatedAt)
+      : deps.resolveDreamGate(
+          carrier.source === "reviewed" ? carrier.block.input : carrier.input,
+          generatedAt,
+        );
+  if (gate.kind === "refuse") {
+    return { status: "failed", message: gate.detail, errorType: gate.errorType };
+  }
+  if (gate.kind === "block" && carrier?.source === "reviewed") {
+    // The approval path: the reviewed (stored) parts must byte-match the re-render against
+    // freshly recovered context.
+    if (JSON.stringify(gate.block.parts) !== JSON.stringify(carrier.block.parts)) {
+      return {
+        status: "failed",
+        message: "the reviewed report no longer matches the wave state — re-draft and re-review",
+        errorType: "bad_state",
+      };
+    }
+  }
+
+  const saved = await deps.backend.create({
+    prose,
+    ...(title !== undefined ? { title } : {}),
+    ...(base !== undefined ? { base } : {}),
+    ...(input.delivery !== undefined ? { delivery: input.delivery } : {}),
+    ...(input.roadmap !== undefined ? { roadmap: input.roadmap } : {}),
+    runId: deps.session.runId,
+    ...(gate.kind === "block" ? { dreamParts: gate.block.parts } : {}),
+  });
+  if (saved.status === "failed") return saved;
+
+  // Link the live session: the seam appends iff the rebuilt `active_objective` differs, with a
+  // strict read-back — verbatim into the outcome (the seam's report() stays the loudness
+  // channel; a linkage failure is loud-but-non-fatal, the save stands).
+  const linkage = deps.session.apply({ kind: "link-objective", objective: saved.id });
+  return { status: "saved", id: saved.id, url: saved.url, existed: saved.existed, linkage };
+}
+
+/** The approval→save dependency bag: the save deps + the gate. */
+export interface ObjectiveApprovalSaveDeps extends ObjectiveSaveDeps {
+  gate: ApprovalGate;
+}
+
+/** The approval→save orchestration outcome (the objective `ApprovalSaveOutcome`).
+ * `refused-draft` is the fail-closed stop for an invalid artifact: nothing saved, the gate
+ * never touched — distinct from `no-draft` (the genuine draft-less fallback arm). */
+export type ObjectiveApprovalSaveOutcome =
+  | { status: "no-draft" }
+  | { status: "refused-draft"; problem: string }
+  | {
+      status: "saved";
+      result: Extract<SaveObjectiveOutcome, { status: "saved" }>;
+      gateExited: boolean;
+    }
+  | {
+      status: "save-failed";
+      result: Extract<SaveObjectiveOutcome, { status: "failed" }>;
+      gateExited: false;
+    };
+
+/**
+ * The shared APPROVED-review → save orchestration (the objective sibling of `planApprovalSave`):
+ * an APPROVED objective review (`plan_review`'s objective arm) and the manual `/objective-save`
+ * failsafe both run THIS. Flow: re-read the STRUCTURED draft artifact at save time
+ * (`resumeObjectiveDraft` — never the rendered markdown, never in-hand bytes; the artifact's
+ * `dream_report` block passes through whole: stored stamp + stored parts) → `saveObjective`
+ * through `saveThroughApprovalGate` (the D1a invariant: snapshot before the save; exit only
+ * after a successful save while read-only; a failed save leaves the gate ON). No draft → `no-draft`
+ * (nothing saved, the gate untouched); a REFUSED draft → `refused-draft` before the gate
+ * snapshot (fail-closed stop — `gateExited` semantics never arise). Title precedence: an
+ * explicit `opts.title` wins; else the draft's `title`; else the cold door derives from the
+ * prose heading.
+ */
+export async function objectiveApprovalSave(
+  deps: ObjectiveApprovalSaveDeps,
+  opts: { title?: string } = {},
+): Promise<ObjectiveApprovalSaveOutcome> {
+  const resumed = resumeObjectiveDraft(deps.session);
+  if (resumed.kind === "absent") return { status: "no-draft" };
+  if (resumed.kind === "refused") return { status: "refused-draft", problem: resumed.problem };
+  const draft = resumed.draft;
+  const title = opts.title ?? draft.title;
+  const { outcome: result, gateExited } = await saveThroughApprovalGate(deps.gate, () =>
+    saveObjective(
+      {
+        prose: draft.prose,
+        ...(title !== undefined ? { title } : {}),
+        roadmap: draft.roadmap,
+        ...(draft.base !== undefined ? { base: draft.base } : {}),
+        ...(draft.delivery !== undefined ? { delivery: draft.delivery } : {}),
+        ...(draft.dream_report !== undefined
+          ? { dream_report: { source: "reviewed" as const, block: draft.dream_report } }
+          : {}),
+      },
+      deps,
+    ),
+  );
+  if (result.status === "failed") return { status: "save-failed", result, gateExited: false };
+  return { status: "saved", result, gateExited };
+}

package/extension/authoring/plan/draft.ts

@@ -0,0 +1,84 @@
+// The plan working-draft feature: the fixed artifact constant and the two draft operations over
+// the WorkflowSession seam. Unlike the gist sibling there is NO encode/decode layer — the
+// artifact is raw plan markdown (no JSON envelope), so a revision is the bytes themselves.
+//
+// Carve-out doctrine (mirrors `authoring/gist/`): the artifact name is the fixed constant
+// `PLAN_DRAFT_ARTIFACT` and every byte flows through the session seam (file + verified
+// `session_artifacts` pointer), so the only thing the draft ops can ever touch is the one
+// working-plan artifact in the current run's data dir (gitignored scratch). A revision is a
+// WHOLE-VALUE replacement — full rewrite per call, never a save (`plan_save`/`/plan-save` still
+// persist to GitHub).
+
+import type { SessionArtifactReceipt, WorkflowSession } from "../../session/workflowSession.ts";
+
+/** The fixed working-plan artifact name (NOT `plan.md` — `cache.plan` is a different file). */
+export const PLAN_DRAFT_ARTIFACT = "plan-draft.md";
+
+/**
+ * The revise outcome. `rejected` splits by `reason` so the adapter renders the exact failure
+ * taxonomy it always had: `blank_plan` (input refused), `no_identity` (an identity-less
+ * session), and `write_refused` (the seam refused before any effect); `unverified` means an
+ * effect may have landed but the read-back proof failed. `problem` carries the caller-facing
+ * message bytes.
+ */
+export type RevisePlanDraftResult =
+  | { status: "revised"; receipt: SessionArtifactReceipt; bytes: number }
+  | { status: "unchanged"; receipt: SessionArtifactReceipt; bytes: number }
+  | { status: "rejected"; reason: "blank_plan" | "no_identity" | "write_refused"; problem: string }
+  | { status: "unverified"; problem: string };
+
+/**
+ * Rewrite the working plan draft (a whole-value replacement) through the session seam.
+ * Diagnostic precedence preserved: a blank plan is refused FIRST, missing identity second (the
+ * identity-optional session classifies `runId: null` — an identity-less caller still opens),
+ * then the verified artifact write. A byte-identical rewrite short-circuits `unchanged` (the
+ * session engine owns the probe). Never throws.
+ */
+export function revisePlanDraft(
+  input: { plan: string },
+  session: WorkflowSession,
+): RevisePlanDraftResult {
+  if (!input.plan.trim()) {
+    return {
+      status: "rejected",
+      reason: "blank_plan",
+      problem: "no plan markdown to write (pass the full working draft)",
+    };
+  }
+  if (session.runId === null) {
+    return {
+      status: "rejected",
+      reason: "no_identity",
+      problem: "session has no run_id — cannot write the plan-draft artifact",
+    };
+  }
+  const bytes = Buffer.byteLength(input.plan, "utf8");
+  const written = session.writeArtifact(PLAN_DRAFT_ARTIFACT, input.plan);
+  switch (written.status) {
+    case "applied":
+      return { status: "revised", receipt: written.receipt, bytes };
+    case "unchanged":
+      return { status: "unchanged", receipt: written.receipt, bytes };
+    case "rejected":
+      return {
+        status: "rejected",
+        reason: "write_refused",
+        problem: `could not write the ${PLAN_DRAFT_ARTIFACT} artifact (see warnings)`,
+      };
+    case "unverified":
+      return {
+        status: "unverified",
+        problem: `could not write the ${PLAN_DRAFT_ARTIFACT} artifact (see warnings)`,
+      };
+  }
+}
+
+/**
+ * Resume the working plan draft from the session. Fail-open `null` everywhere: `absent` is the
+ * silent no-draft arm; `invalid` was already warned by the seam. Raw markdown — blankness is
+ * the RESOLVER's concern (`resolvePlanSource` treats a blank draft as no draft). Never throws.
+ */
+export function resumePlanDraft(session: WorkflowSession): string | null {
+  const read = session.readArtifact(PLAN_DRAFT_ARTIFACT);
+  return read.status === "found" ? read.content : null;
+}