mirror-mind 0.0.1 → 0.33.0

package/ts/src/builder/scopePhrases.ts

@@ -0,0 +1,146 @@
+// CR002 — the surface vocabulary for a journey's roadmap scope.
+//
+// Every Builder surface that answers "where are we" or "what next" states the
+// scope in the same words. They are behavioral contracts rather than prose: the
+// agent reads them to decide its next move, and the frozen goldens pin their
+// bytes. So they live here, once, and every renderer composes them instead of
+// spelling its own near-synonym. That includes the focus a surface shows
+// (`scopeFocus`), because a focus the roadmap cannot supply is stated in these
+// same words.
+//
+// `no item pulled yet` names a beginning, not a loss: the unscoped state means
+// exactly that no item has been pulled since the cursor was last synchronized
+// (see `roadmapScope.ts`). `none` stays only in fields that are genuinely empty.
+
+import { PROGRAM } from "#util/program.ts";
+import { shellWord } from "#util/shellWord.ts";
+import type { RoadmapSnapshotItem } from "./pullCandidates.ts";
+import type {
+  AuthoredPackage,
+  RoadmapScope,
+  ScopedPullCandidates,
+  ScopePosition,
+} from "./roadmapScope.ts";
+
+/** The value of every position row when the journey is unscoped. */
+export const NO_ITEM_PULLED_YET = "no item pulled yet";
+
+/** The header of a candidate list that no journey scope narrows. */
+export const PROJECT_WIDE_CANDIDATES = "project-wide candidates";
+
+export const NO_AUTHORED_PACKAGE = "no authored package";
+export const NO_PROJECT_PATH = "no project path configured";
+export const claimedBy = (count: number) => `claimed by ${count} packages`;
+
+/**
+ * What stands where a recommendation would when there is none: the literal Pull
+ * command, carrying the journey's real slug and placeholders the Navigator fills
+ * from the item they name. The command itself, not a description of one, because
+ * the agent copies it, so the slug goes through `shellWord` (CR104).
+ */
+export function pullExplicitly(journey: string): string {
+  return (
+    `pull explicitly: ${PROGRAM} build pull-item --journey ${shellWord(journey)} --method ariad ` +
+    `--item-code <code> --item-title "<title>" --item-level <level> --why-now "<why now>"`
+  );
+}
+
+/**
+ * The read-only command that shows a journey's active checkpoint (CR067 with CR020).
+ * A refusal prints it to be copied, so it is quoted exactly as the Pull command is.
+ */
+export function showCheckpoint(journey: string): string {
+  return `${PROGRAM} build show --journey ${shellWord(journey)} --method ariad`;
+}
+
+/** The header of every candidate list: whose candidates these are. */
+export function candidateListHeader(scope: RoadmapScope): string {
+  return scope.kind === "unscoped" ? PROJECT_WIDE_CANDIDATES : `candidates in ${scope.cvCode}`;
+}
+
+/** The one line a scoped list adds for the candidates it leaves out, when it leaves any. */
+export function outsideCountLines(view: ScopedPullCandidates): string[] {
+  if (view.scope.kind === "unscoped" || view.outsideCount === 0) return [];
+  return [`${view.outsideCount} more outside ${view.scope.cvCode}`];
+}
+
+/**
+ * The paragraphs that stand where a recommendation would when there is none:
+ * why, for a scoped CV with nothing left, then the literal command. Unscoped, the
+ * command alone, because the position rows already say no item was pulled.
+ */
+export function noRecommendationLines(view: ScopedPullCandidates): string[] {
+  const pull = pullExplicitly(view.journey);
+  if (view.scope.kind === "unscoped") return [pull];
+  return [`no remaining candidates in ${view.scope.cvCode}`, pull];
+}
+
+/**
+ * `CV22 — <title> (<status>) [<path>]`, the pre-CR002 format; no `()` when there is no
+ * status. The status is the package's clause (CR103): this row once printed CV22's
+ * whole changelog, twenty card lines, on every load.
+ */
+function formatPackage(authored: AuthoredPackage): string {
+  const status = authored.status ? ` (${authored.status})` : "";
+  return `${authored.code} — ${authored.title}${status} [${authored.path}]`;
+}
+
+/**
+ * The `roadmap position` row of `■ BUILDER RESUME`, one entry per paragraph (each
+ * is wrapped onto its own card lines). Every fallback states what is missing or
+ * wrong; none of them throws and none of them guesses.
+ */
+export function roadmapPositionLines(scope: RoadmapScope): string[] {
+  if (scope.kind === "unscoped") return [NO_ITEM_PULLED_YET];
+  const { position, cvCode, activeItem } = scope;
+  switch (position.kind) {
+    case "cv_package":
+      return [formatPackage(position.package)];
+    case "item_package":
+      return [formatPackage(position.package), `${NO_AUTHORED_PACKAGE} for ${cvCode}`];
+    case "no_package":
+      return [
+        activeItem === cvCode
+          ? `${NO_AUTHORED_PACKAGE} for ${cvCode}`
+          : `${NO_AUTHORED_PACKAGE} for ${cvCode} or ${activeItem}`,
+      ];
+    case "ambiguous":
+      return [
+        `${position.code} is ${claimedBy(position.paths.length)}: ${position.paths.join(", ")}`,
+      ];
+    case "no_project":
+      return [NO_PROJECT_PATH];
+  }
+}
+
+/**
+ * The roadmap focus a surface shows as "where are we": the roadmap index row for
+ * the journey's CV, else the CV package's heading, else the position stated in
+ * this vocabulary. `null` when unscoped.
+ *
+ * The index row wins because it is what the focus showed before CR002, for the
+ * same CV; the change is WHICH CV, not where its title is read from.
+ */
+export function scopeFocus(
+  items: readonly RoadmapSnapshotItem[],
+  scope: RoadmapScope,
+): RoadmapSnapshotItem | null {
+  if (scope.kind === "unscoped") return null;
+  const row = items.find((item) => item.code === scope.cvCode);
+  if (row !== undefined) return row;
+  const position = scope.position;
+  if (position.kind === "cv_package") {
+    const { code, title, status } = position.package;
+    return { code, title, status };
+  }
+  return { code: scope.cvCode, title: placeholderTitle(scope.cvCode, position), status: "" };
+}
+
+/** The focus title for a CV the roadmap cannot describe; the focus row already names the CV. */
+function placeholderTitle(cvCode: string, position: ScopePosition): string {
+  if (position.kind === "no_project") return NO_PROJECT_PATH;
+  if (position.kind === "ambiguous" && position.code === cvCode) {
+    return claimedBy(position.paths.length);
+  }
+  return NO_AUTHORED_PACKAGE;
+}

package/ts/src/builder/storyPaths.ts

@@ -0,0 +1,196 @@
+// CV22.DS7.US8 plateau 1 — resolve-then-create for roadmap story packages.
+//
+// Port of `src/memory/builder/story_paths.py`.
+//
+// The rule that matters: an EXISTING package is located by its own heading
+// (`# <code> — <title>`), never by a folder-naming convention or by arithmetic
+// on code+title. An authored package can live under any folder a human chose,
+// and what makes it `CV2.DS1` is its heading. Python learned this twice —
+// CR048 in DS6.TS5, recurring in CV22.DS7 — so the resolver is shared by every
+// call site rather than re-derived per caller.
+//
+// Creating a NEW package is the lower-stakes half: nothing is authored for that
+// code yet, so a new path cannot duplicate or contradict anything, and naming a
+// not-yet-materialized parent degrades gracefully instead of failing.
+//
+// Confinement is not incidental. `createStoryDirectory` builds a path from a
+// caller-supplied code and title — candidate-table cells, which may be
+// Navigator- or model-authored — so the final path is checked to be inside the
+// roadmap root and the code segment is sanitized before it can create nested
+// directories (Python's D-012).
+
+import { relative, resolve, sep } from "node:path";
+import { kebabSlug } from "#util/slug.ts";
+import { displayPath } from "./projectPaths.ts";
+import { inspectRoadmapSnapshot, roadmapPaths } from "./pullCandidates.ts";
+import { matchHeading } from "./roadmapGrammar.ts";
+import { readRoadmapFile, scanRoadmapIndexFiles } from "./roadmapScan.ts";
+
+/** Python `StoryPackageAmbiguityError`: two packages claim one code. */
+export class StoryPackageAmbiguityError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "StoryPackageAmbiguityError";
+  }
+}
+
+/**
+ * Python `_sanitize_code_segment`: dots are the code's own level separator, so
+ * they become hyphens FIRST (preserving `cv2-ds1` folder naming for well-formed
+ * codes), and everything else goes through the same slug sanitizer titles use.
+ * That is what stops a `/` or `..` in a code cell from creating directories.
+ */
+function sanitizeCodeSegment(code: string): string {
+  return kebabSlug(code.replaceAll(".", "-"));
+}
+
+/** Python `story_folder_name`: `<code>-<title-slug>`, or the code alone. */
+export function storyFolderName(code: string, title: string): string {
+  const codePart = sanitizeCodeSegment(code);
+  const slug = kebabSlug(title);
+  return slug ? `${codePart}-${slug}` : codePart;
+}
+
+/** Every code claimed by a non-legacy `index.md` heading, mapped to its directories. */
+function groupRoadmapHeadings(roadmapRoot: string): Map<string, string[]> {
+  const byCode = new Map<string, string[]>();
+  for (const file of scanRoadmapIndexFiles(roadmapRoot)) {
+    const content = readRoadmapFile(file.absolutePath);
+    if (content === null) continue;
+    const heading = matchHeading(content);
+    if (!heading) continue;
+    const code = heading.code.trim();
+    const directory = file.components.slice(0, -1).join("/");
+    const existing = byCode.get(code);
+    if (existing) existing.push(directory);
+    else byCode.set(code, [directory]);
+  }
+  return byCode;
+}
+
+/**
+ * The package resolver over one reading of the roadmap: for a code, the absolute
+ * directory of the authored package whose heading claims it, `null` when none does,
+ * and a throw when more than one does.
+ *
+ * `resolveStoryDirectory` asks it about one code. Expand asks it about every child of
+ * a Delivery Story, and must settle them all before it writes anything, so it reads
+ * the roadmap once and keeps this function (CR018). Both go through the one rule.
+ */
+export function storyDirectoryResolver(projectRoot: string): (code: string) => string | null {
+  // ABSOLUTE, like Python's `(project_path / … ).resolve()`. This was relative until
+  // CV22.DS7.US8 plateau 3, and the divergence was invisible because every test and
+  // every real caller passed an absolute project path: the front door reads it from
+  // the journey row, where `journey set-path` stores an absolute one. A
+  // project-relative path made Python print absolute package paths and TypeScript
+  // print relative ones in the same surface, and — worse — would have compared a
+  // relative candidate against a resolved root inside `createStoryDirectory`'s
+  // confinement guard.
+  const roadmapRoot = resolve(roadmapPaths(projectRoot).roadmapRoot);
+  const claims = groupRoadmapHeadings(roadmapRoot);
+  const absolute = (directory: string): string =>
+    directory ? `${roadmapRoot}${sep}${directory.split("/").join(sep)}` : roadmapRoot;
+  return (code) => {
+    const matches = claims.get(code) ?? [];
+    if (matches.length === 0) return null;
+    if (matches.length > 1) {
+      // Named relative to the project (CR082): Pull prints this message on
+      // `EXPAND_BLOCKED`, and every other command on an `Error:` line.
+      const claimants = matches.map((directory) => displayPath(absolute(directory), projectRoot));
+      throw new StoryPackageAmbiguityError(
+        `${matches.length} roadmap packages claim code '${code}': ${claimants.join(", ")}`,
+      );
+    }
+    return absolute(matches[0] ?? "");
+  };
+}
+
+/**
+ * Python `resolve_story_directory`: the directory of the authored package whose
+ * heading code equals `code`, `null` when none does, and a throw when more than
+ * one does.
+ */
+export function resolveStoryDirectory(projectRoot: string, code: string): string | null {
+  return storyDirectoryResolver(projectRoot)(code);
+}
+
+/**
+ * Every heading code in the roadmap, mapped to the directories that claim it —
+ * relative to the roadmap root, POSIX, in scan order.
+ *
+ * One code, one directory is the healthy case. `resolveStoryDirectory` refuses to
+ * choose among several; CR002's roadmap scope reads the map directly because a
+ * surface must be able to SAY that a package is claimed twice, and to name the
+ * claimants project-relatively, rather than throw from inside `build load`.
+ */
+export function roadmapHeadingDirectories(projectRoot: string): Map<string, string[]> {
+  return groupRoadmapHeadings(resolve(roadmapPaths(projectRoot).roadmapRoot));
+}
+
+/** Python `find_duplicate_roadmap_headings`: the CI-facing whole-tree counterpart. */
+export function findDuplicateRoadmapHeadings(projectRoot: string): Map<string, string[]> {
+  const { roadmapRoot } = roadmapPaths(projectRoot);
+  const duplicates = new Map<string, string[]>();
+  for (const [code, directories] of groupRoadmapHeadings(roadmapRoot)) {
+    if (directories.length > 1) duplicates.set(code, directories);
+  }
+  return duplicates;
+}
+
+/** Python `_parent_code`: `CV2.DS1` -> `CV2`; `DS-35` -> `null`. */
+function parentCode(code: string): string | null {
+  if (!code.includes(".")) return null;
+  return code.slice(0, code.lastIndexOf("."));
+}
+
+/** Python `_snapshot_title`: name a not-yet-materialized coordinate from the root snapshot. */
+function snapshotTitle(projectRoot: string, code: string): string | null {
+  const snapshot = inspectRoadmapSnapshot(projectRoot, { journey: "", method: "ariad" });
+  for (const item of snapshot.items) {
+    if (item.code === code) return item.title;
+  }
+  return null;
+}
+
+/**
+ * Python `_parent_directory`: resolve an existing package by heading, else name
+ * it from the root snapshot, else recurse to the grandparent and fall back to a
+ * bare code segment. Never fails loud — nothing is authored for the code yet.
+ */
+function parentDirectory(projectRoot: string, code: string): string {
+  const resolved = resolveStoryDirectory(projectRoot, code);
+  if (resolved !== null) return resolved;
+  // Resolved for the same reason as above: Python's `_parent_directory` bases every
+  // derived path on the resolved roadmap root.
+  const roadmapRoot = resolve(roadmapPaths(projectRoot).roadmapRoot);
+  const parent = parentCode(code);
+  const base = parent === null ? roadmapRoot : parentDirectory(projectRoot, parent);
+  const title = snapshotTitle(projectRoot, code);
+  const folder = title ? storyFolderName(code, title) : sanitizeCodeSegment(code);
+  return `${base}${sep}${folder}`;
+}
+
+/**
+ * Python `create_story_directory`: the canonical directory for a NEW package,
+ * nested under its best-available parent coordinate, with the story's whole title
+ * slugging its own folder: the rule Expand applies to a child (CR018).
+ *
+ * Throws when the resolved target escapes the roadmap root. That guard is the
+ * reason a `../` code or an absolute-looking title cannot write outside
+ * `docs/project/roadmap/`, and it is checked AFTER resolution so a symlink or a
+ * `..` surviving sanitization is still caught.
+ */
+export function createStoryDirectory(projectRoot: string, code: string, title: string): string {
+  const { roadmapRoot } = roadmapPaths(projectRoot);
+  const resolvedRoadmapRoot = resolve(roadmapRoot);
+  const parent = parentCode(code);
+  const base = parent === null ? resolvedRoadmapRoot : parentDirectory(projectRoot, parent);
+  const target = resolve(base, storyFolderName(code, title));
+  const relation = relative(resolvedRoadmapRoot, target);
+  const escapes =
+    relation.startsWith("..") || relation.startsWith(`${sep}`) || resolve(relation) === relation;
+  if (escapes) {
+    throw new Error(`story directory escapes roadmap root: ${target}`);
+  }
+  return target;
+}

package/ts/src/builder/storyPlanPreauthorization.ts

@@ -0,0 +1,287 @@
+// CV22.DS7.US8 plateau 3 — consuming story authority, once.
+//
+// Port of `src/memory/builder/story_plan_preauthorization.py`.
+//
+// The consume is a compare-and-swap against the observed cursor, and every branch
+// around it is a safety property:
+//
+//   * an already-consumed receipt returns `already_approved` and starts NO second
+//     implementation, so a retried command is idempotent rather than additive;
+//   * a lost CAS re-reads the cursor and returns `already_approved` if another
+//     writer got there first, and otherwise refuses with `cursor_changed`;
+//   * a mismatch invalidates the receipt BEFORE raising, so a refused authority
+//     cannot be retried into acceptance;
+//   * the refusal path still leaves the Plan checkpoint pending, which is what makes
+//     "fall back to ordinary Navigator approval" true rather than aspirational.
+
+import type { WritableDatabase } from "#db/database.ts";
+import { planSectionsToAuthor } from "./artifacts/scaffoldState.ts";
+import { cardPrefixed, cardText } from "./card.ts";
+import {
+  type BuilderDeliveryCursor,
+  type CursorWriteDeps,
+  DeliveryCursorConflict,
+  getDeliveryCursor,
+  setDeliveryCursor,
+  setTo,
+} from "./deliveryCursor.ts";
+import { FLOW_UNIT_STORY_BY_STORY } from "./flowUnit.ts";
+import {
+  invalidatePlanPreauthorization,
+  PlanPreauthorizationMismatch,
+  planPreauthorizationMismatchReason,
+  STORY_PLAN_CONTRACT,
+} from "./planPreauthorization.ts";
+import { wrapAriadSurface } from "./surfaceProtocol.ts";
+
+const STORY_LEVELS = new Set(["user_story", "technical_story"]);
+
+/** Python `StoryPlanPreauthorizationReport`. */
+export interface StoryPlanPreauthorizationReport {
+  readonly cursor: BuilderDeliveryCursor;
+  readonly status: string;
+  readonly unfilledSections: readonly string[];
+  readonly implementationStarted: boolean;
+}
+
+/** Python `_is_consumed_story_approval`: all six conditions, or it is not consumed. */
+function isConsumedStoryApproval(cursor: BuilderDeliveryCursor): boolean {
+  const receipt = cursor.planPreauthorization;
+  return (
+    receipt !== null &&
+    receipt.status === "consumed" &&
+    receipt.planContractVersion === STORY_PLAN_CONTRACT &&
+    cursor.lastDeliveryEvent === "plan_approved" &&
+    cursor.activeCheckpoint === null &&
+    cursor.pendingConfirmation === null
+  );
+}
+
+export interface ApproveWithAuthorityOptions {
+  readonly journey: string;
+  readonly method: string;
+  readonly planArtifactPath: string | null;
+}
+
+/** Python `approve_story_plan_with_preauthorization`. */
+export function approveStoryPlanWithPreauthorization(
+  db: WritableDatabase,
+  options: ApproveWithAuthorityOptions,
+  deps: CursorWriteDeps,
+): StoryPlanPreauthorizationReport {
+  const { journey, method } = options;
+  const cursor = getDeliveryCursor(db, journey);
+  if (cursor === null) throw new Error("delivery cursor is required before story Plan approval");
+  if (isConsumedStoryApproval(cursor)) {
+    return {
+      cursor,
+      status: "already_approved",
+      unfilledSections: [],
+      implementationStarted: false,
+    };
+  }
+  if (cursor.activeItemLevel === null || !STORY_LEVELS.has(cursor.activeItemLevel)) {
+    throw new Error("story Plan preauthorization requires a User or Technical Story");
+  }
+  if (
+    cursor.activeCheckpoint !== "after_plan" ||
+    cursor.pendingConfirmation !== "navigator_approval"
+  ) {
+    throw new Error("story Plan approval requires a pending after_plan checkpoint");
+  }
+
+  // The same rule the ordinary route applies (CR112), and the list `build show` prints
+  // (CR111 D4): a section still holding the scaffold's sentences is not authored,
+  // whatever its structure.
+  const unfilled = planSectionsToAuthor(options.planArtifactPath);
+  const mismatch = planPreauthorizationMismatchReason(cursor, {
+    journey,
+    method,
+    flowUnit: FLOW_UNIT_STORY_BY_STORY,
+    childWorkItems: [],
+    planContractVersion: STORY_PLAN_CONTRACT,
+    unfilledSections: unfilled,
+  });
+  if (mismatch !== null) {
+    invalidatePlanPreauthorization(db, cursor, mismatch, deps);
+    throw new PlanPreauthorizationMismatch(
+      mismatch,
+      mismatch === "plan_incomplete" ? unfilled : [],
+    );
+  }
+
+  const receipt = cursor.planPreauthorization;
+  // Unreachable: the mismatch guard establishes a pending receipt. Kept because
+  // Python keeps it, and because the type system cannot see that.
+  if (receipt === null) throw new PlanPreauthorizationMismatch("authorization_missing");
+
+  let updated: BuilderDeliveryCursor;
+  try {
+    updated = setDeliveryCursor(
+      db,
+      {
+        journey,
+        method,
+        activeItem: cursor.activeItem,
+        activeItemTitle: cursor.activeItemTitle,
+        activeItemLevel: cursor.activeItemLevel,
+        activeCheckpoint: null,
+        pendingConfirmation: null,
+        lastDeliveryEvent: "plan_approved",
+        cadenceProfile: cursor.cadenceProfile,
+        cadenceLimits: cursor.cadenceLimits,
+        granularityDecision: cursor.granularityDecision,
+        navigatorFlowUnit: cursor.navigatorFlowUnit,
+        childWorkItems: cursor.childWorkItems,
+        aggregateCheckpointStatus: cursor.aggregateCheckpointStatus,
+        cursorGeneration: cursor.cursorGeneration,
+        planPreauthorization: setTo({ ...receipt, status: "consumed", reason: null }),
+        expectedCursor: cursor,
+      },
+      deps,
+    );
+  } catch (error) {
+    if (!(error instanceof DeliveryCursorConflict)) throw error;
+    const current = getDeliveryCursor(db, journey);
+    if (current !== null && isConsumedStoryApproval(current)) {
+      return {
+        cursor: current,
+        status: "already_approved",
+        unfilledSections: [],
+        implementationStarted: false,
+      };
+    }
+    throw new PlanPreauthorizationMismatch("cursor_changed");
+  }
+
+  return {
+    cursor: updated,
+    status: "approved",
+    unfilledSections: unfilled,
+    implementationStarted: true,
+  };
+}
+
+/** Python `cancel_story_plan_preauthorization`. */
+export function cancelStoryPlanPreauthorization(
+  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");
+  }
+  if (cursor.activeItemLevel === null || !STORY_LEVELS.has(cursor.activeItemLevel)) {
+    throw new Error("story Plan cancellation requires a User or Technical Story");
+  }
+  const receipt = cursor.planPreauthorization;
+  if (receipt === null || receipt.status !== "pending") {
+    throw new Error("pending Plan preauthorization is required before cancellation");
+  }
+  return invalidatePlanPreauthorization(db, cursor, "navigator_cancelled", deps);
+}
+
+/** Python `render_story_plan_preauthorization_recorded`. */
+export function renderStoryPlanPreauthorizationRecorded(cursor: BuilderDeliveryCursor): string {
+  const receipt = cursor.planPreauthorization;
+  if (receipt === null) throw new Error("Plan preauthorization receipt is required");
+  const body = `${[
+    "Delivery",
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    "│        🧭  PLAN PREAUTHORIZATION RECORDED              │",
+    "│                                                        │",
+    cardText("Authorized story"),
+    cardText(receipt.activeItem),
+    "│                                                        │",
+    cardText("Story level"),
+    cardText(receipt.activeItemLevel),
+    "│                                                        │",
+    cardText("Policy"),
+    cardText(receipt.policy),
+    "│                                                        │",
+    cardText("Fixed stop"),
+    cardText(receipt.stopBoundary),
+    "│                                                        │",
+    cardText("Boundary"),
+    cardText("Single-use authority remains pending until the"),
+    cardText("Driver completes the exact story Plan."),
+    "╰────────────────────────────────────────────────────────╯",
+  ].join("\n")}\n`;
+  return wrapAriadSurface("plan_preauthorization_recorded", body);
+}
+
+/** Python `render_story_implementation_started`. */
+export function renderStoryImplementationStarted(cursor: BuilderDeliveryCursor): string {
+  const body = `${[
+    "Delivery",
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    "│        🟧  IMPLEMENTATION STARTED                     │",
+    "│                                                        │",
+    cardText("Active story"),
+    cardText(cursor.activeItem ?? "none"),
+    "│                                                        │",
+    cardText("Boundary"),
+    cardText("Local implementation may proceed under the exact"),
+    cardText("approved Plan and stops at Navigator Validation."),
+    "╰────────────────────────────────────────────────────────╯",
+  ].join("\n")}\n`;
+  return wrapAriadSurface("implementation_started", body);
+}
+
+/** Python `render_story_preauthorization_already_consumed`. */
+export function renderStoryPreauthorizationAlreadyConsumed(cursor: BuilderDeliveryCursor): string {
+  const body = `${[
+    "Delivery",
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    "│        ✓  PLAN PREAUTHORIZATION ALREADY CONSUMED       │",
+    "│                                                        │",
+    cardText("Active story"),
+    cardText(cursor.activeItem ?? "none"),
+    "│                                                        │",
+    cardText("Outcome"),
+    cardText("No approval or implementation start was repeated."),
+    "╰────────────────────────────────────────────────────────╯",
+  ].join("\n")}\n`;
+  return wrapAriadSurface("plan_preauthorization_already_consumed", body);
+}
+
+/** Python `render_story_plan_preauthorization_mismatch`: payload-free by construction. */
+export function renderStoryPlanPreauthorizationMismatch(options: {
+  activeItem: string | null;
+  reason: string;
+  /** The `plan.md` sections still to author, when the reason is `plan_incomplete`. */
+  toAuthor?: readonly string[];
+}): string {
+  const toAuthor = options.toAuthor ?? [];
+  const body = `${[
+    "Delivery",
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    "│        ✕  PLAN PREAUTHORIZATION MISMATCH               │",
+    "│                                                        │",
+    cardText("Active story"),
+    cardText(options.activeItem ?? "none"),
+    "│                                                        │",
+    cardText("Reason"),
+    cardText(options.reason),
+    "│                                                        │",
+    ...(toAuthor.length > 0
+      ? [
+          cardText("To author in plan.md"),
+          ...cardPrefixed(toAuthor, "-"),
+          "│                                                        │",
+        ]
+      : []),
+    cardText("Fallback"),
+    cardText("Ordinary Navigator Plan approval remains required."),
+    "╰────────────────────────────────────────────────────────╯",
+  ].join("\n")}\n`;
+  return wrapAriadSurface("plan_preauthorization_mismatch", body);
+}

package/ts/src/builder/surfaceProtocol.ts

@@ -0,0 +1,42 @@
+// CV22.DS7.US8 plateau 1 — the Ariad surface transport boundary.
+//
+// Port of `src/memory/builder/surface_protocol.py`, all ten lines of it, and it
+// earns its own module for the same reason Python gives it one: every Ariad
+// surface passes through here, and the marked block is a transport contract the
+// runtime harness parses. A re-indent, a doubled newline, or a lost marker is a
+// protocol break, not a formatting difference.
+//
+// Two details a port drops:
+//
+//   * the id is normalized — `strip()`, `upper()`, and spaces to underscores —
+//     so callers pass `"plan_checkpoint"` or `"Plan Checkpoint"` and both emit
+//     `PLAN_CHECKPOINT`;
+//   * the body is `rstrip()`ed, and call sites are INCONSISTENT about whether
+//     they append a trailing newline (`body + "\n"` in most of `builder/`, bare
+//     `body` in three places in `lifecycle.py`). Because the body is stripped
+//     either way the output is identical, which is exactly why a port that
+//     forgets the strip appears to work until it meets the other call style.
+
+import { PYTHON_WHITESPACE_CLASS, pyStrip } from "#util/pythonText.ts";
+
+const TRAILING_WS_RE = new RegExp(`[${PYTHON_WHITESPACE_CLASS}]+$`, "u");
+
+/** Python `str.rstrip()` with no argument — Python's whitespace set, not `.trimEnd()`. */
+function pyRStripAll(text: string): string {
+  return text.replace(TRAILING_WS_RE, "");
+}
+
+/**
+ * Python `wrap_ariad_surface`: wrap a rendered surface in explicit transport
+ * boundaries.
+ *
+ * Normalization is `surface_id.strip().upper().replace(" ", "_")`. Note it
+ * replaces spaces only — a tab or a newline in an id would survive into the
+ * marker, which no caller does but which the port must not silently "fix" by
+ * normalizing all whitespace.
+ */
+export function wrapAriadSurface(surfaceId: string, body: string): string {
+  const normalized = pyStrip(surfaceId).toUpperCase().replaceAll(" ", "_");
+  const content = pyRStripAll(body);
+  return `<<<ARIAD:${normalized}>>>\n${content}\n<<<END:${normalized}>>>\n`;
+}