mirror-mind 0.0.1 → 0.32.1

package/ts/src/builder/closure.ts

@@ -0,0 +1,964 @@
+// CV22.DS7.US8 plateau 4 — story closure: Validate, Debt Review, Coherence, Done.
+//
+// Port of the second half of `src/memory/builder/lifecycle.py`.
+//
+// The four verbs share one shape, and it is the shape a port gets wrong: each
+// computes a MISSING-EVIDENCE tuple, and that tuple decides three cursor fields at
+// once — `activeCheckpoint`, `pendingConfirmation`, and `lastDeliveryEvent`. So
+// "incomplete" is not an error and not a different surface; it is the same surface
+// over a different persisted state. A port can render the right card and write the
+// wrong three fields, which is why the corpus grades every branch as a sequence.
+//
+// Two of the four allow EXACT-STATE re-entry to answer their own pending
+// confirmation — Review for `navigator_debt_decision`, Coherence for
+// `navigator_coherence` — because without it `--decision pending` deadlocks the
+// lifecycle: every verb refuses while the confirmation it would resolve stays
+// pending. That was found live on another project, not reasoned about. Done allows no
+// re-entry at all and refuses any pending confirmation its predecessors left behind.
+//
+// Until CV22.DS10.TS1 all four ordered a Journey projection refresh after their
+// artifact existed. The projection subsystem retired with the Python core, so the
+// ordering dance is gone and the cursor write is the whole write.
+//
+// They live in one module rather than four because they are one state machine over
+// one cursor, sharing the missing-evidence idiom and the guard vocabulary. Splitting
+// them would duplicate the shared normalizers without separating any concern.
+
+import type { WritableDatabase } from "#db/database.ts";
+import { pyStrip, sortByCodePoint } from "#util/pythonText.ts";
+import type { ArtifactOutcome } from "./artifacts/artifactWriter.ts";
+import {
+  renderCoherenceArtifact,
+  renderDoneArtifact,
+  renderReviewArtifact,
+  renderValidationArtifact,
+  writeClosureArtifact,
+} from "./artifacts/closureArtifacts.ts";
+import { artifactState } from "./artifacts/scaffoldState.ts";
+import { cardPrefixed, cardText, cardWrapped } from "./card.ts";
+import { normalizeRequired } from "./cursorTransitions.ts";
+import {
+  type BuilderDeliveryCursor,
+  type CursorWriteDeps,
+  getDeliveryCursor,
+  setDeliveryCursor,
+} from "./deliveryCursor.ts";
+import { LifecycleRefusal, refuseIfAlreadyComplete } from "./lifecycleRefusal.ts";
+import { renderLifecycleRibbon } from "./lifecycleRibbon.ts";
+import type { ContractDefinition, MethodDefinition } from "./methodDefinition.ts";
+import { displayPath, targetLine } from "./projectPaths.ts";
+import { wrapAriadSurface } from "./surfaceProtocol.ts";
+
+/** Python `_contract_for`. */
+function contractFor(method: MethodDefinition, contractId: string): ContractDefinition {
+  const contract = method.contracts.find((candidate) => candidate.id === contractId);
+  if (contract === undefined) {
+    throw new Error(`method ${method.id} is missing contract ${contractId}`);
+  }
+  return contract;
+}
+
+/**
+ * Python `_normalize_validation_choice`.
+ *
+ * Lowercases and maps `-` to `_` before the membership test, and the refusal lists
+ * the allowed values SORTED — so the message is stable regardless of the order the
+ * call site declared them in.
+ */
+function normalizeChoice(value: string, field: string, allowed: readonly string[]): string {
+  const normalized =
+    typeof value === "string" ? pyStrip(value).toLowerCase().replaceAll("-", "_") : "";
+  if (!allowed.includes(normalized)) {
+    throw new Error(`${field} must be one of ${sortByCodePoint([...allowed]).join(", ")}`);
+  }
+  return normalized;
+}
+
+/** Python's `tuple(x.strip() for x in items if x.strip())`. */
+function normalizedList(items: readonly string[]): string[] {
+  return items.map((item) => pyStrip(item)).filter((item) => item !== "");
+}
+
+/** Python's `(value or default).strip()`. */
+function textOr(value: string | null | undefined, fallback: string): string {
+  return pyStrip(value || fallback);
+}
+
+/** Python's `x.strip() if x and x.strip() else None`. */
+function optionalText(value: string | null | undefined): string | null {
+  if (!value) return null;
+  const stripped = pyStrip(value);
+  return stripped || null;
+}
+
+// --- Validation ------------------------------------------------------------
+
+export interface BuilderValidationReport {
+  readonly journey: string;
+  readonly method: string;
+  readonly activeItem: string;
+  readonly activeItemTitle: string | null;
+  readonly automatedChecks: readonly string[];
+  readonly checksStatus: string;
+  readonly e2eDecision: string;
+  readonly e2eEvidence: string | null;
+  readonly navigatorValidationRoute: string;
+  readonly navigatorAccepted: boolean;
+  readonly expectedObservation: string;
+  readonly passCondition: string;
+  readonly failCondition: string;
+  readonly missingEvidence: readonly string[];
+  readonly validationContract: ContractDefinition;
+  readonly cursor: BuilderDeliveryCursor;
+  readonly validationArtifactPath: string | null;
+  /** The project the record was written under: the card names it relative (CR082). */
+  readonly projectRoot: string | null;
+  /** What the writer did with the record (CR079); absent when there is no artifact path. */
+  readonly validationArtifactOutcome?: ArtifactOutcome | null;
+  readonly nextEvent: string;
+}
+
+/**
+ * Python `_validation_missing_evidence`.
+ *
+ * Order is behavior: the tuple is rendered as a list, so a port that reorders these
+ * produces a different surface. Note the `elif` on acceptance — a MISSING route is
+ * reported instead of an unaccepted one, never both.
+ */
+function validationMissingEvidence(input: {
+  checks: readonly string[];
+  checksStatus: string;
+  e2eDecision: string;
+  e2eEvidence: string | null | undefined;
+  navigatorValidationRoute: string;
+  navigatorAccepted: boolean;
+}): string[] {
+  const missing: string[] = [];
+  if (input.checks.length === 0) missing.push("automated checks are not declared");
+  if (input.checksStatus !== "passed") {
+    missing.push(`automated checks status is ${input.checksStatus}`);
+  }
+  const evidence = input.e2eEvidence && pyStrip(input.e2eEvidence) ? input.e2eEvidence : null;
+  if (input.e2eDecision === "required" && evidence === null) {
+    missing.push("required E2E evidence is missing");
+  }
+  if (input.e2eDecision === "skipped" && evidence === null) {
+    missing.push("skipped E2E requires an explicit reason");
+  }
+  if (!pyStrip(input.navigatorValidationRoute)) {
+    missing.push("Navigator validation route is missing");
+  } else if (!input.navigatorAccepted) {
+    missing.push("Navigator validation has not been accepted");
+  }
+  return missing;
+}
+
+export interface ValidateOptions {
+  readonly journey: string;
+  readonly method: MethodDefinition;
+  readonly automatedChecks?: readonly string[];
+  readonly checksStatus?: string;
+  readonly e2eDecision?: string;
+  readonly e2eEvidence?: string | null;
+  readonly navigatorValidationRoute?: string | null;
+  readonly navigatorAccepted?: boolean;
+  readonly expectedObservation?: string | null;
+  readonly passCondition?: string | null;
+  readonly failCondition?: string | null;
+  readonly implementationComplete?: boolean;
+  readonly validationArtifactPath?: string | null;
+  /** The project the artifact must stay inside (CR079). */
+  readonly projectRoot?: string | null;
+}
+
+const PLAN_EVENTS = new Set(["plan_approved", "delivery_story_plan_approved"]);
+
+/** Python `validate_lifecycle_item`. */
+export function validateLifecycleItem(
+  db: WritableDatabase,
+  options: ValidateOptions,
+  deps: CursorWriteDeps,
+): BuilderValidationReport {
+  const journey = normalizeRequired(options.journey, "journey");
+  const existing = getDeliveryCursor(db, journey);
+  if (existing === null) throw new Error("delivery cursor is required before validation");
+  if (!existing.activeItem) throw new Error("active item is required before validation");
+  refuseIfAlreadyComplete("validate", existing);
+  if (existing.pendingConfirmation && existing.pendingConfirmation !== "navigator_validation") {
+    throw new LifecycleRefusal(
+      "validate",
+      "pending_confirmation",
+      `Validation is blocked: pending confirmation ${existing.pendingConfirmation}.`,
+    );
+  }
+  const navigatorAccepted = options.navigatorAccepted ?? false;
+  if (existing.pendingConfirmation === "navigator_validation" && !navigatorAccepted) {
+    throw new LifecycleRefusal(
+      "validate",
+      "pending_confirmation",
+      "Validation is blocked: pending Navigator validation acceptance.",
+    );
+  }
+  const lastEvent = existing.lastDeliveryEvent ?? "";
+  if (
+    !(
+      PLAN_EVENTS.has(lastEvent) ||
+      lastEvent === "implementation_complete" ||
+      lastEvent === "validate"
+    )
+  ) {
+    throw new LifecycleRefusal(
+      "validate",
+      "not_reached",
+      "Validation requires an approved Plan and completed implementation",
+    );
+  }
+  if (PLAN_EVENTS.has(lastEvent) && !(options.implementationComplete ?? false)) {
+    throw new LifecycleRefusal(
+      "validate",
+      "missing_evidence",
+      "Validation requires implementation completion evidence",
+    );
+  }
+
+  const checks = normalizedList(options.automatedChecks ?? []);
+  const checksStatus = normalizeChoice(options.checksStatus ?? "not_run", "checks_status", [
+    "passed",
+    "failed",
+    "not_run",
+  ]);
+  const e2eDecision = normalizeChoice(options.e2eDecision ?? "not_required", "e2e_decision", [
+    "required",
+    "not_required",
+    "waived",
+    "skipped",
+  ]);
+  const route = textOr(
+    options.navigatorValidationRoute,
+    "Navigator validates the behavior described by the Plan.",
+  );
+  const observation = textOr(
+    options.expectedObservation,
+    "Expected behavior from the Plan is observable.",
+  );
+  const passText = textOr(options.passCondition, "Navigator accepts the observed behavior.");
+  const failText = textOr(options.failCondition, "Navigator cannot observe the planned behavior.");
+  const missing = validationMissingEvidence({
+    checks,
+    checksStatus,
+    e2eDecision,
+    e2eEvidence: options.e2eEvidence,
+    navigatorValidationRoute: route,
+    navigatorAccepted,
+  });
+
+  const cursor = setDeliveryCursor(
+    db,
+    {
+      journey,
+      method: options.method.id,
+      activeItem: existing.activeItem,
+      activeItemTitle: existing.activeItemTitle,
+      activeItemLevel: existing.activeItemLevel,
+      activeCheckpoint: missing.length > 0 ? "after_validation" : null,
+      pendingConfirmation: missing.length > 0 ? "navigator_validation" : null,
+      lastDeliveryEvent: missing.length > 0 ? "validate" : "validation_passed",
+      cadenceProfile: existing.cadenceProfile,
+      cadenceLimits: existing.cadenceLimits,
+      granularityDecision: existing.granularityDecision,
+      navigatorFlowUnit: existing.navigatorFlowUnit,
+      childWorkItems: existing.childWorkItems,
+      aggregateCheckpointStatus: existing.aggregateCheckpointStatus,
+    },
+    deps,
+  );
+
+  const report: BuilderValidationReport = {
+    journey,
+    method: options.method.id,
+    activeItem: existing.activeItem,
+    activeItemTitle: existing.activeItemTitle,
+    automatedChecks: checks,
+    checksStatus,
+    e2eDecision,
+    e2eEvidence: optionalText(options.e2eEvidence),
+    navigatorValidationRoute: route,
+    navigatorAccepted,
+    expectedObservation: observation,
+    passCondition: passText,
+    failCondition: failText,
+    missingEvidence: missing,
+    validationContract: contractFor(options.method, "validation_contract"),
+    cursor,
+    validationArtifactPath: options.validationArtifactPath ?? null,
+    projectRoot: options.projectRoot ?? null,
+    nextEvent: "debt_review",
+  };
+  if (report.validationArtifactPath === null) return report;
+  const validationArtifactOutcome = writeClosureArtifact(
+    report.validationArtifactPath,
+    renderValidationArtifact(report),
+    options.projectRoot,
+  );
+  return { ...report, validationArtifactOutcome };
+}
+
+/** Python `render_validation_checkpoint`. */
+export function renderValidationCheckpoint(report: BuilderValidationReport): string {
+  const blocked = report.missingEvidence.length > 0;
+  const body = `${[
+    "Delivery",
+    renderLifecycleRibbon("validate", report.cursor.activeItemLevel),
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    "│        🧪■  VALIDATION CHECKPOINT                      │",
+    "│                                                        │",
+    cardText("active item"),
+    cardText(report.activeItem),
+    "│                                                        │",
+    cardText("status"),
+    cardText(blocked ? "pending_navigator_validation" : "passed"),
+    "│                                                        │",
+    cardText("automated checks"),
+    ...cardPrefixed(
+      report.automatedChecks.length > 0
+        ? report.automatedChecks
+        : ["No automated checks declared."],
+      "✓",
+    ),
+    "│                                                        │",
+    cardText("checks status"),
+    cardText(report.checksStatus),
+    "│                                                        │",
+    cardText("e2e decision"),
+    cardText(report.e2eDecision),
+    "│                                                        │",
+    cardText("e2e evidence"),
+    ...cardWrapped(report.e2eEvidence || "none"),
+    "│                                                        │",
+    cardText("navigator validation route"),
+    ...cardWrapped(report.navigatorValidationRoute),
+    "│                                                        │",
+    cardText("navigator accepted"),
+    cardText(report.navigatorAccepted ? "yes" : "no"),
+    "│                                                        │",
+    cardText("expected observation"),
+    ...cardWrapped(report.expectedObservation),
+    "│                                                        │",
+    cardText("pass condition"),
+    ...cardWrapped(report.passCondition),
+    "│                                                        │",
+    cardText("fail condition"),
+    ...cardWrapped(report.failCondition),
+    "│                                                        │",
+    cardText("missing evidence"),
+    ...cardPrefixed(blocked ? report.missingEvidence : ["none"], blocked ? "✕" : "✓"),
+    "│                                                        │",
+    cardText("validation contract"),
+    ...cardPrefixed(report.validationContract.rules, "✓"),
+    "│                                                        │",
+    cardText("validation artifact"),
+    ...recordRows(report.validationArtifactPath, report.projectRoot, report.journey),
+    ...preservedNote(report.validationArtifactOutcome),
+    "│                                                        │",
+    cardText("boundary"),
+    ...cardWrapped(
+      blocked
+        ? "Do not move past Validation until missing evidence is resolved."
+        : "Validation is complete; Builder may proceed to Debt Review.",
+    ),
+    "╰────────────────────────────────────────────────────────╯",
+  ].join("\n")}\n`;
+  return wrapAriadSurface("validation_checkpoint", body);
+}
+
+// --- Debt Review -----------------------------------------------------------
+
+export interface BuilderReviewReport {
+  readonly journey: string;
+  readonly method: string;
+  readonly activeItem: string;
+  readonly activeItemTitle: string | null;
+  readonly debtFindings: readonly string[];
+  readonly debtDecision: string;
+  readonly deferReason: string | null;
+  readonly revisitTrigger: string | null;
+  readonly missingDecision: readonly string[];
+  readonly debtReviewContract: ContractDefinition;
+  readonly cursor: BuilderDeliveryCursor;
+  readonly reviewArtifactPath: string | null;
+  /** The project the record was written under: the card names it relative (CR082). */
+  readonly projectRoot: string | null;
+  /** What the writer did with the record (CR079); absent when there is no artifact path. */
+  readonly reviewArtifactOutcome?: ArtifactOutcome | null;
+  readonly nextEvent: string;
+}
+
+/** Python `_review_missing_decision`. */
+function reviewMissingDecision(input: {
+  debtDecision: string;
+  deferReason: string | null | undefined;
+  revisitTrigger: string | null | undefined;
+}): string[] {
+  const missing: string[] = [];
+  if (input.debtDecision === "pending") missing.push("Navigator debt decision is required");
+  if (input.debtDecision === "defer") {
+    if (!(input.deferReason && pyStrip(input.deferReason))) {
+      missing.push("deferred debt requires a reason");
+    }
+    if (!(input.revisitTrigger && pyStrip(input.revisitTrigger))) {
+      missing.push("deferred debt requires a revisit trigger");
+    }
+  }
+  // `pay_now` is never complete here: it must route through a Refactor loop first,
+  // so Debt Review cannot be the thing that closes it.
+  if (input.debtDecision === "pay_now") {
+    missing.push("pay-now debt must route through Refactor before Done");
+  }
+  return missing;
+}
+
+export interface ReviewOptions {
+  readonly journey: string;
+  readonly method: MethodDefinition;
+  readonly debtFindings?: readonly string[];
+  readonly debtDecision?: string;
+  readonly deferReason?: string | null;
+  readonly revisitTrigger?: string | null;
+  readonly reviewArtifactPath?: string | null;
+  /** The project the artifact must stay inside (CR079). */
+  readonly projectRoot?: string | null;
+}
+
+/** Python `review_lifecycle_item`. */
+export function reviewLifecycleItem(
+  db: WritableDatabase,
+  options: ReviewOptions,
+  deps: CursorWriteDeps,
+): BuilderReviewReport {
+  const journey = normalizeRequired(options.journey, "journey");
+  const existing = getDeliveryCursor(db, journey);
+  if (existing === null) throw new Error("delivery cursor is required before review");
+  if (!existing.activeItem) throw new Error("active item is required before review");
+  refuseIfAlreadyComplete("debt_review", existing);
+
+  const reentering =
+    existing.pendingConfirmation === "navigator_debt_decision" &&
+    existing.lastDeliveryEvent === "review";
+  if (existing.pendingConfirmation && !reentering) {
+    throw new LifecycleRefusal(
+      "debt_review",
+      "pending_confirmation",
+      `Review is blocked: pending confirmation ${existing.pendingConfirmation}.`,
+    );
+  }
+  if (existing.lastDeliveryEvent !== "validation_passed" && !reentering) {
+    throw new LifecycleRefusal(
+      "debt_review",
+      "not_reached",
+      "Debt Review requires passed Validation",
+    );
+  }
+
+  const decision = normalizeChoice(options.debtDecision ?? "pending", "debt_decision", [
+    "pending",
+    "no_action",
+    "defer",
+    "pay_now",
+  ]);
+  const findings = normalizedList(options.debtFindings ?? []);
+  const missing = reviewMissingDecision({
+    debtDecision: decision,
+    deferReason: options.deferReason,
+    revisitTrigger: options.revisitTrigger,
+  });
+
+  const cursor = setDeliveryCursor(
+    db,
+    {
+      journey,
+      method: options.method.id,
+      activeItem: existing.activeItem,
+      activeItemTitle: existing.activeItemTitle,
+      activeItemLevel: existing.activeItemLevel,
+      activeCheckpoint: missing.length > 0 ? "review_decision" : null,
+      pendingConfirmation: missing.length > 0 ? "navigator_debt_decision" : null,
+      lastDeliveryEvent: missing.length > 0 ? "review" : "review_complete",
+      cadenceProfile: existing.cadenceProfile,
+      cadenceLimits: existing.cadenceLimits,
+      granularityDecision: existing.granularityDecision,
+      navigatorFlowUnit: existing.navigatorFlowUnit,
+      childWorkItems: existing.childWorkItems,
+      aggregateCheckpointStatus: existing.aggregateCheckpointStatus,
+    },
+    deps,
+  );
+
+  const report: BuilderReviewReport = {
+    journey,
+    method: options.method.id,
+    activeItem: existing.activeItem,
+    activeItemTitle: existing.activeItemTitle,
+    debtFindings: findings,
+    debtDecision: decision,
+    deferReason: optionalText(options.deferReason),
+    revisitTrigger: optionalText(options.revisitTrigger),
+    missingDecision: missing,
+    debtReviewContract: contractFor(options.method, "debt_review_contract"),
+    cursor,
+    reviewArtifactPath: options.reviewArtifactPath ?? null,
+    projectRoot: options.projectRoot ?? null,
+    nextEvent: "coherence",
+  };
+  if (report.reviewArtifactPath === null) return report;
+  const reviewArtifactOutcome = writeClosureArtifact(
+    report.reviewArtifactPath,
+    renderReviewArtifact(report),
+    options.projectRoot,
+  );
+  return { ...report, reviewArtifactOutcome };
+}
+
+/** Python `render_review_checkpoint`. */
+export function renderReviewCheckpoint(report: BuilderReviewReport): string {
+  const blocked = report.missingDecision.length > 0;
+  const body = `${[
+    "Delivery",
+    renderLifecycleRibbon("debt_review", report.cursor.activeItemLevel),
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    "│        🔎■  DEBT REVIEW CHECKPOINT                     │",
+    "│                                                        │",
+    cardText("active item"),
+    cardText(report.activeItem),
+    "│                                                        │",
+    cardText("status"),
+    cardText(blocked ? "pending_debt_decision" : "reviewed"),
+    "│                                                        │",
+    cardText("debt findings"),
+    ...cardPrefixed(
+      report.debtFindings.length > 0 ? report.debtFindings : ["No debt findings declared."],
+      "△",
+    ),
+    "│                                                        │",
+    cardText("debt decision"),
+    cardText(report.debtDecision),
+    "│                                                        │",
+    cardText("defer reason"),
+    ...cardWrapped(report.deferReason || "none"),
+    "│                                                        │",
+    cardText("revisit trigger"),
+    ...cardWrapped(report.revisitTrigger || "none"),
+    "│                                                        │",
+    cardText("missing decision"),
+    ...cardPrefixed(blocked ? report.missingDecision : ["none"], blocked ? "✕" : "✓"),
+    "│                                                        │",
+    cardText("debt review contract"),
+    ...cardPrefixed(report.debtReviewContract.rules, "✓"),
+    "│                                                        │",
+    cardText("review artifact"),
+    ...recordRows(report.reviewArtifactPath, report.projectRoot, report.journey),
+    ...preservedNote(report.reviewArtifactOutcome),
+    "│                                                        │",
+    cardText("boundary"),
+    ...cardWrapped(
+      blocked
+        ? "Do not move past Debt Review until the Navigator debt decision is resolved."
+        : "Debt Review is complete; Builder may proceed to Done.",
+    ),
+    "╰────────────────────────────────────────────────────────╯",
+  ].join("\n")}\n`;
+  return wrapAriadSurface("debt_review_checkpoint", body);
+}
+
+// --- Coherence -------------------------------------------------------------
+
+export interface BuilderCoherenceReport {
+  readonly journey: string;
+  readonly method: string;
+  readonly activeItem: string;
+  readonly activeItemTitle: string | null;
+  readonly processAlignment: string;
+  readonly projectAlignment: string;
+  readonly productAlignment: string;
+  readonly localDifferences: readonly string[];
+  readonly missingCoherence: readonly string[];
+  readonly coherenceContract: ContractDefinition;
+  readonly cursor: BuilderDeliveryCursor;
+  readonly coherenceArtifactPath: string | null;
+  /** The project the record was written under: the card names it relative (CR082). */
+  readonly projectRoot: string | null;
+  /** What the writer did with the record (CR079); absent when there is no artifact path. */
+  readonly coherenceArtifactOutcome?: ArtifactOutcome | null;
+  readonly nextEvent: string;
+}
+
+export interface CoherenceOptions {
+  readonly journey: string;
+  readonly method: MethodDefinition;
+  readonly processAlignment?: string | null;
+  readonly projectAlignment?: string | null;
+  readonly productAlignment?: string | null;
+  readonly localDifferences?: readonly string[];
+  readonly coherenceArtifactPath?: string | null;
+  /** The project the artifact must stay inside (CR079). */
+  readonly projectRoot?: string | null;
+}
+
+/** Python `coherence_lifecycle_item`. */
+export function coherenceLifecycleItem(
+  db: WritableDatabase,
+  options: CoherenceOptions,
+  deps: CursorWriteDeps,
+): BuilderCoherenceReport {
+  const journey = normalizeRequired(options.journey, "journey");
+  const existing = getDeliveryCursor(db, journey);
+  if (existing === null) throw new Error("delivery cursor is required before coherence");
+  if (!existing.activeItem) throw new Error("active item is required before coherence");
+  refuseIfAlreadyComplete("coherence", existing);
+
+  const reentering =
+    existing.pendingConfirmation === "navigator_coherence" &&
+    existing.lastDeliveryEvent === "coherence";
+  if (existing.pendingConfirmation && !reentering) {
+    throw new LifecycleRefusal(
+      "coherence",
+      "pending_confirmation",
+      `Coherence is blocked: pending confirmation ${existing.pendingConfirmation}.`,
+    );
+  }
+  if (existing.lastDeliveryEvent !== "review_complete" && !reentering) {
+    throw new LifecycleRefusal(
+      "coherence",
+      "not_reached",
+      "Coherence requires completed Debt Review",
+    );
+  }
+
+  const process = textOr(
+    options.processAlignment,
+    "Process evidence is aligned with the Ariad lifecycle.",
+  );
+  const project = textOr(
+    options.projectAlignment,
+    "Project docs and artifacts reflect the validated change.",
+  );
+  const product = textOr(
+    options.productAlignment,
+    "Product behavior matches the accepted validation evidence.",
+  );
+  const differences = normalizedList(options.localDifferences ?? []);
+  // Python `_coherence_missing`: a blank string defaults ABOVE, so the only way to
+  // reach these is an argument that was whitespace before the default could apply.
+  const missing: string[] = [];
+  if (!pyStrip(process)) missing.push("process alignment is missing");
+  if (!pyStrip(project)) missing.push("project alignment is missing");
+  if (!pyStrip(product)) missing.push("product alignment is missing");
+
+  const cursor = setDeliveryCursor(
+    db,
+    {
+      journey,
+      method: options.method.id,
+      activeItem: existing.activeItem,
+      activeItemTitle: existing.activeItemTitle,
+      activeItemLevel: existing.activeItemLevel,
+      activeCheckpoint: missing.length > 0 ? "coherence" : null,
+      pendingConfirmation: missing.length > 0 ? "navigator_coherence" : null,
+      lastDeliveryEvent: missing.length > 0 ? "coherence" : "coherence_complete",
+      cadenceProfile: existing.cadenceProfile,
+      cadenceLimits: existing.cadenceLimits,
+      granularityDecision: existing.granularityDecision,
+      navigatorFlowUnit: existing.navigatorFlowUnit,
+      childWorkItems: existing.childWorkItems,
+      aggregateCheckpointStatus: existing.aggregateCheckpointStatus,
+    },
+    deps,
+  );
+
+  const report: BuilderCoherenceReport = {
+    journey,
+    method: options.method.id,
+    activeItem: existing.activeItem,
+    activeItemTitle: existing.activeItemTitle,
+    processAlignment: process,
+    projectAlignment: project,
+    productAlignment: product,
+    localDifferences: differences,
+    missingCoherence: missing,
+    coherenceContract: contractFor(options.method, "coherence_contract"),
+    cursor,
+    coherenceArtifactPath: options.coherenceArtifactPath ?? null,
+    projectRoot: options.projectRoot ?? null,
+    nextEvent: "done",
+  };
+  if (report.coherenceArtifactPath === null) return report;
+  const coherenceArtifactOutcome = writeClosureArtifact(
+    report.coherenceArtifactPath,
+    renderCoherenceArtifact(report),
+    options.projectRoot,
+  );
+  return { ...report, coherenceArtifactOutcome };
+}
+
+/** Python `render_coherence_checkpoint`: note the ribbon says `done`, not `coherence`. */
+export function renderCoherenceCheckpoint(report: BuilderCoherenceReport): string {
+  const blocked = report.missingCoherence.length > 0;
+  const body = `${[
+    "Delivery",
+    renderLifecycleRibbon("done", report.cursor.activeItemLevel),
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    "│        ◉■  COHERENCE CHECKPOINT                        │",
+    "│                                                        │",
+    cardText("active item"),
+    cardText(report.activeItem),
+    "│                                                        │",
+    cardText("status"),
+    cardText(blocked ? "pending_coherence" : "coherent"),
+    "│                                                        │",
+    cardText("process alignment"),
+    ...cardWrapped(report.processAlignment),
+    "│                                                        │",
+    cardText("project alignment"),
+    ...cardWrapped(report.projectAlignment),
+    "│                                                        │",
+    cardText("product alignment"),
+    ...cardWrapped(report.productAlignment),
+    "│                                                        │",
+    cardText("local guide differences"),
+    ...cardPrefixed(report.localDifferences.length > 0 ? report.localDifferences : ["none"], "△"),
+    "│                                                        │",
+    cardText("missing coherence"),
+    ...cardPrefixed(blocked ? report.missingCoherence : ["none"], blocked ? "✕" : "✓"),
+    "│                                                        │",
+    cardText("coherence contract"),
+    ...cardPrefixed(report.coherenceContract.rules, "✓"),
+    "│                                                        │",
+    cardText("coherence artifact"),
+    ...recordRows(report.coherenceArtifactPath, report.projectRoot, report.journey),
+    ...preservedNote(report.coherenceArtifactOutcome),
+    "│                                                        │",
+    cardText("boundary"),
+    ...cardWrapped(
+      blocked
+        ? "Do not move to Done until coherence gaps are resolved."
+        : "Coherence is complete; Builder may proceed to Done.",
+    ),
+    "╰────────────────────────────────────────────────────────╯",
+  ].join("\n")}\n`;
+  return wrapAriadSurface("coherence_checkpoint", body);
+}
+
+// --- Done ------------------------------------------------------------------
+
+export interface BuilderDoneReport {
+  readonly journey: string;
+  readonly method: string;
+  readonly activeItem: string;
+  readonly activeItemTitle: string | null;
+  readonly historyAction: string;
+  readonly roadmapUpdate: string;
+  readonly nextRecommendation: string;
+  readonly missingDone: readonly string[];
+  readonly doneContract: ContractDefinition;
+  readonly cursor: BuilderDeliveryCursor;
+  readonly doneArtifactPath: string | null;
+  /** The project the record was written under: the card names it relative (CR082). */
+  readonly projectRoot: string | null;
+  /** What the writer did with the record (CR079); absent when there is no artifact path. */
+  readonly doneArtifactOutcome?: ArtifactOutcome | null;
+}
+
+export interface DoneOptions {
+  readonly journey: string;
+  readonly method: MethodDefinition;
+  readonly historyAction?: string | null;
+  readonly roadmapUpdate?: string | null;
+  readonly nextRecommendation?: string | null;
+  readonly doneArtifactPath?: string | null;
+  /** The project the artifact must stay inside (CR079). */
+  readonly projectRoot?: string | null;
+  /**
+   * The story's `index.md` (CR112). Done refuses while its placeholder sections are
+   * still the scaffold's; `null` when there is no project, and no file to read.
+   * Required, not optional: `continue-lifecycle` once reached Done without it, and a
+   * story closed with its record still the scaffold (CR112's handoff review).
+   */
+  readonly indexArtifactPath: string | null;
+}
+
+/**
+ * CR112, decision D4: a story does not close while its own record still says what
+ * Expand or Plan wrote -- "I want to <title>". Only the placeholder headings the file
+ * has are judged, so an index in the Driver's own structure is never refused.
+ */
+function refuseUnauthoredIndex(indexPath: string | null, projectRoot: string | null): void {
+  if (indexPath === null) return;
+  const verdict = artifactState("index.md", indexPath);
+  if (verdict.toAuthor.length === 0) return;
+  throw new LifecycleRefusal(
+    "done",
+    "missing_evidence",
+    `Done needs the story's own record. Still to author in ${displayPath(indexPath, projectRoot ?? null)}: ${verdict.toAuthor.join(", ")}.`,
+  );
+}
+
+/** Python `done_lifecycle_item`. */
+export function doneLifecycleItem(
+  db: WritableDatabase,
+  options: DoneOptions,
+  deps: CursorWriteDeps,
+): BuilderDoneReport {
+  const journey = normalizeRequired(options.journey, "journey");
+  const existing = getDeliveryCursor(db, journey);
+  if (existing === null) throw new Error("delivery cursor is required before done");
+  if (!existing.activeItem) throw new Error("active item is required before done");
+  refuseIfAlreadyComplete("done", existing);
+  // No re-entry: Done refuses every pending confirmation, including the ones its own
+  // predecessors left behind.
+  if (existing.pendingConfirmation) {
+    throw new LifecycleRefusal(
+      "done",
+      "pending_confirmation",
+      `Done is blocked: pending confirmation ${existing.pendingConfirmation}.`,
+    );
+  }
+  // `review_complete` is accepted DIRECTLY: Coherence is an option, not a
+  // precondition. A port that requires `coherence_complete` blocks a legal closure.
+  if (
+    existing.lastDeliveryEvent !== "review_complete" &&
+    existing.lastDeliveryEvent !== "coherence_complete"
+  ) {
+    throw new LifecycleRefusal("done", "not_reached", "Done requires completed Debt Review");
+  }
+  refuseUnauthoredIndex(options.indexArtifactPath, options.projectRoot ?? null);
+
+  const history = textOr(
+    options.historyAction,
+    "History action recorded according to project policy.",
+  );
+  const roadmap = textOr(options.roadmapUpdate, "Roadmap/story package reflects the closed story.");
+  const nextStep = textOr(
+    options.nextRecommendation,
+    "Inspect pull candidates for the next Ariad movement.",
+  );
+  const missing: string[] = [];
+  if (!pyStrip(history)) missing.push("history action is missing");
+  if (!pyStrip(roadmap)) missing.push("roadmap update is missing");
+  if (!pyStrip(nextStep)) missing.push("next recommendation is missing");
+
+  const cursor = setDeliveryCursor(
+    db,
+    {
+      journey,
+      method: options.method.id,
+      activeItem: existing.activeItem,
+      activeItemTitle: existing.activeItemTitle,
+      activeItemLevel: existing.activeItemLevel,
+      activeCheckpoint: missing.length > 0 ? "done" : null,
+      pendingConfirmation: missing.length > 0 ? "navigator_done" : null,
+      lastDeliveryEvent: missing.length > 0 ? "done" : "done_complete",
+      cadenceProfile: existing.cadenceProfile,
+      cadenceLimits: existing.cadenceLimits,
+      granularityDecision: existing.granularityDecision,
+      navigatorFlowUnit: existing.navigatorFlowUnit,
+      childWorkItems: existing.childWorkItems,
+      aggregateCheckpointStatus: existing.aggregateCheckpointStatus,
+    },
+    deps,
+  );
+
+  const report: BuilderDoneReport = {
+    journey,
+    method: options.method.id,
+    activeItem: existing.activeItem,
+    activeItemTitle: existing.activeItemTitle,
+    historyAction: history,
+    roadmapUpdate: roadmap,
+    nextRecommendation: nextStep,
+    missingDone: missing,
+    doneContract: contractFor(options.method, "done_contract"),
+    cursor,
+    doneArtifactPath: options.doneArtifactPath ?? null,
+    projectRoot: options.projectRoot ?? null,
+  };
+  if (report.doneArtifactPath === null) return report;
+  const doneArtifactOutcome = writeClosureArtifact(
+    report.doneArtifactPath,
+    renderDoneArtifact(report),
+    options.projectRoot,
+  );
+  return { ...report, doneArtifactOutcome };
+}
+
+/** Python `render_done_checkpoint`. */
+export function renderDoneCheckpoint(report: BuilderDoneReport): string {
+  const blocked = report.missingDone.length > 0;
+  const body = `${[
+    "Delivery",
+    renderLifecycleRibbon("done", report.cursor.activeItemLevel),
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    "│        🟩■  DONE CHECKPOINT                             │",
+    "│                                                        │",
+    cardText("active item"),
+    cardText(report.activeItem),
+    "│                                                        │",
+    cardText("status"),
+    cardText(blocked ? "pending_done" : "done"),
+    "│                                                        │",
+    cardText("history action"),
+    ...cardWrapped(report.historyAction),
+    "│                                                        │",
+    cardText("roadmap update"),
+    ...cardWrapped(report.roadmapUpdate),
+    "│                                                        │",
+    cardText("next recommendation"),
+    ...cardWrapped(report.nextRecommendation),
+    "│                                                        │",
+    cardText("missing done"),
+    ...cardPrefixed(blocked ? report.missingDone : ["none"], blocked ? "✕" : "✓"),
+    "│                                                        │",
+    cardText("done contract"),
+    ...cardPrefixed(report.doneContract.rules, "✓"),
+    "│                                                        │",
+    cardText("done artifact"),
+    ...recordRows(report.doneArtifactPath, report.projectRoot, report.journey),
+    ...preservedNote(report.doneArtifactOutcome),
+    "│                                                        │",
+    cardText("boundary"),
+    ...cardWrapped(
+      blocked
+        ? "Do not close the story until Done gaps are resolved."
+        : "Story closure is complete; Builder may recommend the next Pull.",
+    ),
+    "╰────────────────────────────────────────────────────────╯",
+  ].join("\n")}\n`;
+  return wrapAriadSurface("done_checkpoint", body);
+}
+
+/**
+ * A closure record's rows: the project and journey it was written for (CR009), then its
+ * path relative to that project (CR082), or `not materialized` when the journey has no
+ * project, and nothing was written.
+ */
+function recordRows(path: string | null, projectRoot: string | null, journey: string): string[] {
+  if (path === null) return cardWrapped("not materialized");
+  const target = projectRoot === null ? [] : cardWrapped(targetLine(projectRoot, journey));
+  return [...target, ...cardWrapped(displayPath(path, projectRoot))];
+}
+
+/**
+ * CR079: said only when a closure record was preserved rather than written, the
+ * one case a reader cannot assume. Created and updated records hold this
+ * checkpoint's fields, as they always have.
+ */
+function preservedNote(outcome: ArtifactOutcome | null | undefined): string[] {
+  return outcome === "preserved"
+    ? cardWrapped(
+        "preserved as it is: Ariad did not write this file, or it was edited since. " +
+          "This checkpoint's fields are shown here, not written to it.",
+      )
+    : [];
+}