mirror-mind 0.0.0-stage → 0.32.1

package/ts/src/builder/deliveryStoryPlan.ts

@@ -0,0 +1,536 @@
+// CV22.DS7.US8 plateau 5 — the Delivery Story Plan checkpoint and its approval.
+//
+// Port of `src/memory/builder/delivery_story_plan.py`.
+//
+// This is the aggregate face of Plan: one checkpoint over a whole Delivery Story
+// and its child work packages, chosen by the Navigator through `set-flow-unit`.
+// The story-level Plan in `plan.ts` stays exactly as it was — the two are separate
+// state machines over the same cursor, and the flow unit decides which one may run.
+//
+// Three things a port gets wrong here, all pinned by the corpus:
+//
+//   1. **`replaceStatus` APPENDS.** `aggregate_checkpoint_status` is an ordered
+//      list cell, and replacing an entry removes it and pushes the new value to the
+//      END. Re-validating after a debt review therefore REORDERS the list without
+//      changing its set — and the cursor's compare-and-swap matches on the
+//      serialized bytes, so an in-place replace passes every set-wise assertion and
+//      breaks the swap of a cursor the Python engine wrote.
+//   2. **`plan.md` is preserved, not upserted.** Python's own docstring says it is
+//      "upserted on every call"; both branches of its `if report.status ==
+//      "approved"` guard write only `if not plan_existed`, so the branches are
+//      identical and the file survives. The corpus pins the CODE
+//      (`delivery_story_plan_preserves_authored_plan`), and this comment exists so
+//      nobody ports the docstring.
+//   3. **Approval under authority uses compare-and-swap.** `expectedCursor` is
+//      passed only on the preauthorized path, and a conflict there is answered by
+//      re-reading: a concurrent writer that already consumed the receipt yields
+//      `already_approved`, anything else is a bounded mismatch. That branch cannot
+//      be reached from the corpus (the replay has no way to interpose a write
+//      between the read and the swap), so it is graded by an injected-conflict test
+//      instead, and declared as corpus-unreachable rather than implied.
+
+import type { WritableDatabase } from "#db/database.ts";
+import { pyStrip } from "#util/pythonText.ts";
+import { replaceStatus } from "./aggregateStatus.ts";
+import type { MaterializedArtifact } from "./artifacts/artifactSurfaces.ts";
+import {
+  unfilledDeliveryStoryPlanSections,
+  writeDeliveryStoryPackage,
+} from "./artifacts/deliveryStoryArtifacts.ts";
+import { cardPrefixed, cardText, cardWrapped } from "./card.ts";
+import {
+  type BuilderDeliveryCursor,
+  type CursorWriteDeps,
+  DeliveryCursorConflict,
+  getDeliveryCursor,
+  type PlanPreauthorizationReceipt,
+  setDeliveryCursor,
+} from "./deliveryCursor.ts";
+import { FLOW_UNIT_DELIVERY_STORY } from "./flowUnit.ts";
+import {
+  createPlanPreauthorizationReceipt,
+  DELIVERY_STORY_PLAN_CONTRACT,
+  invalidatePlanPreauthorization,
+  PlanPreauthorizationMismatch,
+  PREAUTHORIZATION_STOP,
+  planPreauthorizationMismatchReason,
+} from "./planPreauthorization.ts";
+import { wrapAriadSurface } from "./surfaceProtocol.ts";
+
+export interface DeliveryStoryPlanReport {
+  readonly journey: string;
+  readonly method: string;
+  readonly deliveryStory: string;
+  readonly deliveryStoryTitle: string | null;
+  readonly childWorkItems: readonly string[];
+  readonly objective: string;
+  readonly status: string;
+  readonly cursor: BuilderDeliveryCursor;
+  readonly planArtifactPath: string | null;
+  readonly materializedArtifacts: readonly MaterializedArtifact[];
+  readonly unfilledSections: readonly string[];
+  readonly implementationStarted: boolean;
+}
+
+/** Python `_normalize_items`: strip, drop empties, preserve order. */
+function normalizeItems(items: readonly string[]): string[] {
+  return items.map((item) => pyStrip(item)).filter((item) => item !== "");
+}
+
+export interface PlanDeliveryStoryOptions {
+  readonly journey: string;
+  readonly method: string;
+  readonly objective: string;
+  readonly childWorkItems?: readonly string[];
+  readonly planArtifactPath?: string | null;
+  /** The project the package must stay inside (CR079). */
+  readonly projectRoot?: string | null;
+  readonly preauthorize?: boolean;
+  readonly stopBoundary?: string;
+}
+
+/**
+ * Python `plan_delivery_story_checkpoint`.
+ *
+ * The four guards run in Python's order, and the order is behavior: cursor, then
+ * level, then flow unit, then active item — so a story-level cursor under
+ * `delivery_story` flow reports the LEVEL, not the flow unit.
+ */
+export function planDeliveryStoryCheckpoint(
+  db: WritableDatabase,
+  options: PlanDeliveryStoryOptions,
+  deps: CursorWriteDeps,
+): DeliveryStoryPlanReport {
+  const cursor = getDeliveryCursor(db, options.journey);
+  if (cursor === null) {
+    throw new Error("delivery cursor is required before Delivery Story Plan");
+  }
+  if (cursor.activeItemLevel !== "delivery_story") {
+    throw new Error("Delivery Story Plan requires an active Delivery Story");
+  }
+  if (cursor.navigatorFlowUnit !== FLOW_UNIT_DELIVERY_STORY) {
+    throw new Error("Delivery Story Plan requires navigator_flow_unit=delivery_story");
+  }
+  if (!cursor.activeItem) {
+    throw new Error("active Delivery Story is required before Delivery Story Plan");
+  }
+  const requested = normalizeItems(options.childWorkItems ?? []);
+  const children = requested.length > 0 ? requested : [...cursor.childWorkItems];
+  if (children.length === 0) {
+    throw new Error("Delivery Story Plan requires at least one child work item");
+  }
+  const objective = pyStrip(options.objective);
+  if (objective === "") {
+    throw new Error("Delivery Story Plan objective must not be empty");
+  }
+  const stopBoundary = options.stopBoundary ?? PREAUTHORIZATION_STOP;
+  let receipt: PlanPreauthorizationReceipt | null = null;
+  if (options.preauthorize) {
+    if (stopBoundary !== PREAUTHORIZATION_STOP) {
+      throw new Error("unsupported Plan preauthorization stop boundary");
+    }
+    receipt = createPlanPreauthorizationReceipt(cursor, {
+      method: options.method,
+      childWorkItems: children,
+      planContractVersion: DELIVERY_STORY_PLAN_CONTRACT,
+      stopBoundary,
+    });
+  }
+  const updated = setDeliveryCursor(
+    db,
+    {
+      journey: options.journey,
+      method: options.method,
+      activeItem: cursor.activeItem,
+      activeItemTitle: cursor.activeItemTitle,
+      activeItemLevel: cursor.activeItemLevel,
+      activeCheckpoint: "after_delivery_story_plan",
+      pendingConfirmation: "navigator_delivery_story_plan_approval",
+      lastDeliveryEvent: "delivery_story_plan",
+      cadenceProfile: cursor.cadenceProfile,
+      cadenceLimits: cursor.cadenceLimits,
+      granularityDecision: cursor.granularityDecision,
+      navigatorFlowUnit: cursor.navigatorFlowUnit,
+      childWorkItems: children,
+      aggregateCheckpointStatus: replaceStatus(cursor.aggregateCheckpointStatus, "plan", "pending"),
+      cursorGeneration: cursor.cursorGeneration,
+      planPreauthorization: { kind: "set", value: receipt },
+    },
+    deps,
+  );
+  const report: DeliveryStoryPlanReport = {
+    journey: options.journey,
+    method: options.method,
+    deliveryStory: cursor.activeItem,
+    deliveryStoryTitle: cursor.activeItemTitle,
+    childWorkItems: children,
+    objective,
+    status: "pending_approval",
+    cursor: updated,
+    planArtifactPath: options.planArtifactPath ?? null,
+    materializedArtifacts: [],
+    unfilledSections: [],
+    implementationStarted: false,
+  };
+  const materialized = materializePackage(report, options.projectRoot);
+  return { ...report, materializedArtifacts: materialized };
+}
+
+export interface ApproveDeliveryStoryPlanOptions {
+  readonly journey: string;
+  readonly method: string;
+  readonly planArtifactPath?: string | null;
+  /** The project the package must stay inside (CR079). */
+  readonly projectRoot?: string | null;
+  readonly usePreauthorization?: boolean;
+}
+
+/** Python `_is_consumed_approval`: the idempotence test for a repeated consume. */
+function isConsumedApproval(cursor: BuilderDeliveryCursor): boolean {
+  const receipt = cursor.planPreauthorization;
+  return (
+    receipt !== null &&
+    receipt.status === "consumed" &&
+    cursor.lastDeliveryEvent === "delivery_story_plan_approved" &&
+    cursor.aggregateCheckpointStatus.includes("plan:approved")
+  );
+}
+
+function alreadyApprovedReport(
+  cursor: BuilderDeliveryCursor,
+  options: ApproveDeliveryStoryPlanOptions,
+): DeliveryStoryPlanReport {
+  return {
+    journey: options.journey,
+    method: options.method,
+    deliveryStory: cursor.activeItem ?? "",
+    deliveryStoryTitle: cursor.activeItemTitle,
+    childWorkItems: cursor.childWorkItems,
+    objective: "Delivery Story Plan was already approved.",
+    status: "already_approved",
+    cursor,
+    planArtifactPath: options.planArtifactPath ?? null,
+    materializedArtifacts: [],
+    unfilledSections: [],
+    implementationStarted: false,
+  };
+}
+
+/** Python `approve_delivery_story_plan`. */
+export function approveDeliveryStoryPlan(
+  db: WritableDatabase,
+  options: ApproveDeliveryStoryPlanOptions,
+  deps: CursorWriteDeps,
+): DeliveryStoryPlanReport {
+  const usePreauthorization = options.usePreauthorization ?? false;
+  const cursor = getDeliveryCursor(db, options.journey);
+  if (cursor === null) {
+    throw new Error("delivery cursor is required before Delivery Story Plan approval");
+  }
+  if (usePreauthorization && isConsumedApproval(cursor)) {
+    return alreadyApprovedReport(cursor, options);
+  }
+  if (cursor.activeCheckpoint !== "after_delivery_story_plan") {
+    throw new Error(
+      "Delivery Story Plan approval requires an after_delivery_story_plan checkpoint",
+    );
+  }
+  if (cursor.pendingConfirmation !== "navigator_delivery_story_plan_approval") {
+    throw new Error("Delivery Story Plan approval requires navigator approval");
+  }
+  if (!cursor.activeItem) {
+    throw new Error("active Delivery Story is required before Delivery Story Plan approval");
+  }
+  // The DS rule, not the story rule: see `unfilledDeliveryStoryPlanSections`.
+  const unfilled = unfilledDeliveryStoryPlanSections(options.planArtifactPath ?? null);
+  if (usePreauthorization) {
+    const mismatch = planPreauthorizationMismatchReason(cursor, {
+      journey: options.journey,
+      method: options.method,
+      flowUnit: FLOW_UNIT_DELIVERY_STORY,
+      childWorkItems: cursor.childWorkItems,
+      planContractVersion: DELIVERY_STORY_PLAN_CONTRACT,
+      unfilledSections: unfilled,
+    });
+    if (mismatch !== null) {
+      invalidatePlanPreauthorization(db, cursor, mismatch, deps);
+      throw new PlanPreauthorizationMismatch(mismatch);
+    }
+  }
+  let receipt = cursor.planPreauthorization;
+  if (receipt !== null && receipt.status === "pending") {
+    receipt = {
+      ...receipt,
+      status: usePreauthorization ? "consumed" : "invalidated",
+      reason: usePreauthorization ? null : "ordinary_approval_used",
+    };
+  }
+  let updated: BuilderDeliveryCursor;
+  try {
+    updated = setDeliveryCursor(
+      db,
+      {
+        journey: options.journey,
+        method: options.method,
+        activeItem: cursor.activeItem,
+        activeItemTitle: cursor.activeItemTitle,
+        activeItemLevel: cursor.activeItemLevel,
+        activeCheckpoint: null,
+        pendingConfirmation: null,
+        lastDeliveryEvent: "delivery_story_plan_approved",
+        cadenceProfile: cursor.cadenceProfile,
+        cadenceLimits: cursor.cadenceLimits,
+        granularityDecision: cursor.granularityDecision,
+        navigatorFlowUnit: cursor.navigatorFlowUnit,
+        childWorkItems: cursor.childWorkItems,
+        aggregateCheckpointStatus: replaceStatus(
+          cursor.aggregateCheckpointStatus,
+          "plan",
+          "approved",
+        ),
+        cursorGeneration: cursor.cursorGeneration,
+        planPreauthorization: { kind: "set", value: receipt },
+        expectedCursor: usePreauthorization ? cursor : null,
+      },
+      deps,
+    );
+  } catch (error) {
+    if (!(error instanceof DeliveryCursorConflict)) throw error;
+    // Corpus-unreachable by construction: reaching it needs a write between the
+    // read above and the swap. Graded by an injected-conflict test instead.
+    const current = getDeliveryCursor(db, options.journey);
+    if (usePreauthorization && current !== null && isConsumedApproval(current)) {
+      return alreadyApprovedReport(current, options);
+    }
+    if (usePreauthorization) {
+      throw new PlanPreauthorizationMismatch("cursor_changed");
+    }
+    throw new Error("delivery cursor changed before Plan approval");
+  }
+  const report: DeliveryStoryPlanReport = {
+    journey: options.journey,
+    method: options.method,
+    deliveryStory: cursor.activeItem,
+    deliveryStoryTitle: cursor.activeItemTitle,
+    childWorkItems: cursor.childWorkItems,
+    objective: "Delivery Story Plan approved.",
+    status: "approved",
+    cursor: updated,
+    planArtifactPath: options.planArtifactPath ?? null,
+    materializedArtifacts: [],
+    unfilledSections: [],
+    implementationStarted: true,
+  };
+  const materialized = materializePackage(report, options.projectRoot);
+  return { ...report, materializedArtifacts: materialized, unfilledSections: unfilled };
+}
+
+/** Python `cancel_delivery_story_plan_preauthorization`. */
+export function cancelDeliveryStoryPlanPreauthorization(
+  db: WritableDatabase,
+  options: { journey: string; method: string },
+  deps: CursorWriteDeps,
+): BuilderDeliveryCursor {
+  const cursor = getDeliveryCursor(db, options.journey);
+  if (cursor === null) {
+    throw new Error("delivery cursor is required before Plan preauthorization cancellation");
+  }
+  if (cursor.method !== options.method) {
+    throw new Error("active Builder method does not match cancellation method");
+  }
+  const receipt = cursor.planPreauthorization;
+  if (receipt === null || receipt.status !== "pending") {
+    throw new Error("pending Plan preauthorization is required before cancellation");
+  }
+  invalidatePlanPreauthorization(db, cursor, "navigator_cancelled", deps);
+  const cancelled = getDeliveryCursor(db, options.journey);
+  if (cancelled === null) {
+    throw new Error("delivery cursor disappeared during cancellation");
+  }
+  return cancelled;
+}
+
+// --- package materialization ------------------------------------------------
+
+/**
+ * Python `_write_delivery_story_package`, called with the report's own plan path.
+ *
+ * Both branches of Python's `status == "approved"` test write `plan.md` only when
+ * it is absent, so the branches are IDENTICAL and an authored plan survives both
+ * Plan and approval. Python's docstring claims an upsert; the code does not. The
+ * writer keeps one branch, and the corpus proves it is the right one.
+ */
+function materializePackage(
+  report: DeliveryStoryPlanReport,
+  projectRoot: string | null | undefined,
+): readonly MaterializedArtifact[] {
+  const planPath = report.planArtifactPath;
+  if (planPath === null) return [];
+  return writeDeliveryStoryPackage(planPath, report, projectRoot);
+}
+
+// --- surfaces ---------------------------------------------------------------
+
+/** Python `_active_delivery`. */
+function activeDelivery(report: DeliveryStoryPlanReport): string {
+  const title = report.deliveryStoryTitle ? ` — ${report.deliveryStoryTitle}` : "";
+  return `🟦[${report.deliveryStory}]${title}`;
+}
+
+const RIBBON_PLANNING =
+  "Delivery Flow: ✓ Pull → ✓ Prepare → ✓ Expand → ◉ DS Plan → ○ Implement → ○ Validate → ○ Debt Review → ○ Done";
+const RIBBON_IMPLEMENTING =
+  "Delivery Flow: ✓ Pull → ✓ Prepare → ✓ Expand → ✓ DS Plan → ◉ Implement → ○ Validate → ○ Debt Review → ○ Done";
+
+const APPROVED_STATUSES = ["approved", "already_approved"];
+
+/** Python `_next_movement`. */
+function nextMovement(report: DeliveryStoryPlanReport): string {
+  if (report.status === "already_approved") {
+    return "No transition was repeated; continue from the existing approved state.";
+  }
+  if (report.status === "approved") return "Begin implementation under the approved plan.";
+  return "Review the plan artifact, then approve or revise.";
+}
+
+/** Python `render_delivery_story_plan_report`. */
+export function renderDeliveryStoryPlanReport(report: DeliveryStoryPlanReport): string {
+  const approved = APPROVED_STATUSES.includes(report.status);
+  const body: string[] = [
+    "Delivery",
+    report.status === "approved" ? RIBBON_IMPLEMENTING : RIBBON_PLANNING,
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    cardText(
+      approved ? "       🧭  DELIVERY STORY PLAN APPROVED" : "       🧭  DELIVERY STORY PLAN",
+    ),
+    "│                                                        │",
+  ];
+  if (approved) {
+    body.push(
+      cardText("What was approved?"),
+      ...cardWrapped(activeDelivery(report)),
+      "│                                                        │",
+      cardText("Approved work packages"),
+      ...cardPrefixed(report.childWorkItems, "-"),
+    );
+    if (report.unfilledSections.length > 0) {
+      body.push(
+        "│                                                        │",
+        cardText("Sections still pending"),
+        ...cardPrefixed(report.unfilledSections, "-"),
+      );
+    }
+  } else {
+    body.push(
+      cardText("What is being planned?"),
+      ...cardWrapped(activeDelivery(report)),
+      "│                                                        │",
+      cardText("Plan objective"),
+      ...cardWrapped(report.objective),
+      "│                                                        │",
+      cardText("Work packages"),
+      ...cardPrefixed(report.childWorkItems, "-"),
+    );
+  }
+  body.push(
+    "│                                                        │",
+    cardText("Next movement"),
+    ...cardWrapped(nextMovement(report)),
+  );
+  if (!approved) {
+    body.push(
+      "│                                                        │",
+      ...cardWrapped("Choose the next move when ready."),
+    );
+  }
+  body.push("╰────────────────────────────────────────────────────────╯");
+  return wrapAriadSurface("delivery_story_plan_checkpoint", `${body.join("\n")}\n`);
+}
+
+/** Python `render_plan_preauthorization_recorded`. */
+export function renderPlanPreauthorizationRecorded(report: DeliveryStoryPlanReport): string {
+  const receipt = report.cursor.planPreauthorization;
+  if (receipt === null) {
+    throw new Error("Plan preauthorization receipt is required");
+  }
+  const body = [
+    "Delivery",
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    "│        🧭  PLAN PREAUTHORIZATION RECORDED              │",
+    "│                                                        │",
+    cardText("Authorized delivery"),
+    ...cardWrapped(receipt.activeItem),
+    "│                                                        │",
+    cardText("Policy"),
+    ...cardWrapped(receipt.policy),
+    "│                                                        │",
+    cardText("Exact child set"),
+    ...cardPrefixed(receipt.childWorkItems, "-"),
+    "│                                                        │",
+    cardText("Fixed stop"),
+    ...cardWrapped(receipt.stopBoundary),
+    "│                                                        │",
+    cardText("Boundary"),
+    ...cardWrapped(
+      "Single-use authority remains pending until the Driver completes the Plan and every structural coordinate matches.",
+    ),
+    "╰────────────────────────────────────────────────────────╯",
+  ];
+  return wrapAriadSurface("plan_preauthorization_recorded", `${body.join("\n")}\n`);
+}
+
+/** Python `render_plan_preauthorization_mismatch`. */
+export function renderPlanPreauthorizationMismatch(options: {
+  activeItem: string | null;
+  reason: string;
+}): string {
+  const body = [
+    "Delivery",
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    "│        ⛔  PLAN PREAUTHORIZATION NOT CONSUMED          │",
+    "│                                                        │",
+    cardText("Active delivery"),
+    ...cardWrapped(options.activeItem || "none"),
+    "│                                                        │",
+    cardText("Bounded reason"),
+    ...cardWrapped(options.reason),
+    "│                                                        │",
+    cardText("Result"),
+    ...cardWrapped("Plan approval remains blocked; ordinary Navigator approval is available."),
+    "╰────────────────────────────────────────────────────────╯",
+  ];
+  return wrapAriadSurface("plan_preauthorization_mismatch", `${body.join("\n")}\n`);
+}
+
+/** Python `render_delivery_story_implementation_started`. */
+export function renderDeliveryStoryImplementationStarted(report: DeliveryStoryPlanReport): string {
+  const body = [
+    "Delivery",
+    RIBBON_IMPLEMENTING,
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    "│        🟧  IMPLEMENTATION STARTED                     │",
+    "│                                                        │",
+    cardText("What changed?"),
+    ...cardWrapped("The approved Delivery Story Plan now authorizes implementation work."),
+    "│                                                        │",
+    cardText("Active delivery"),
+    ...cardWrapped(activeDelivery(report)),
+    "│                                                        │",
+    cardText("Work packages"),
+    ...cardPrefixed(report.childWorkItems, "-"),
+    "│                                                        │",
+    cardText("Boundary"),
+    ...cardWrapped(
+      "Implementation may mutate local project files under the approved plan. Push, release, deploy, purchase, or externally irreversible actions still require explicit Navigator authorization.",
+    ),
+    "│                                                        │",
+    cardText("Driver action"),
+    ...cardWrapped("Begin implementing the approved plan now."),
+    "╰────────────────────────────────────────────────────────╯",
+  ];
+  return wrapAriadSurface("implementation_started", `${body.join("\n")}\n`);
+}