mirror-mind 0.0.1 → 0.32.1

package/ts/src/builder/flowUnit.ts

@@ -0,0 +1,339 @@
+// CV22.DS7.US8 — the Navigator flow unit.
+//
+// Port of `src/memory/builder/flow_unit.py`. Plateau 3 took the read side, because
+// Plan needs the EFFECTIVE flow unit before it can record story authority (bounded
+// story authority exists only under `story_by_story`). Plateau 5 completes it: the
+// write side was re-sequenced out of Scope F by the panel, since the DS smoke opens
+// with `set-flow-unit` and seeding the flow unit by a raw cursor write instead
+// would be the unrecorded mutation plateau 3a ruled out.
+//
+// The selection surface is CHOSEN by the unit, not fixed: `delivery_story` renders
+// DELIVERY_STORY_SCOPE_CONFIRMATION over the child work packages, `story_by_story`
+// renders NEXT_STORY_CONFIRMATION over the first child as the recommended story.
+// One function, two surface ids — a port that hard-codes either one fails the
+// corpus guard that compares each recorded id against its own wrapped marker.
+//
+// CR105: choosing also RECORDS the question its surface asks, as the cursor's
+// checkpoint and pending confirmation, and only at a Delivery Story's flow
+// decision: after Prepare or Expand, before its Plan. Until then, Expand's
+// story-by-story stop survived a choice of Delivery Story flow, and every surface
+// that reads the cursor reported a question that flow never asks.
+
+import type { WritableDatabase } from "#db/database.ts";
+import { pyStrip } from "#util/pythonText.ts";
+import { hasDeliveryStoryPlan } from "./aggregateStatus.ts";
+import { cardPrefixed, cardText, cardWrapped } from "./card.ts";
+import { deliveryStoryCodeForItem } from "./cursorTransitions.ts";
+import {
+  type BuilderDeliveryCursor,
+  type CursorWriteDeps,
+  getDeliveryCursor,
+  setDeliveryCursor,
+} from "./deliveryCursor.ts";
+import { wrapAriadSurface } from "./surfaceProtocol.ts";
+
+export const FLOW_UNIT_STORY_BY_STORY = "story_by_story";
+export const FLOW_UNIT_DELIVERY_STORY = "delivery_story";
+export const ALLOWED_FLOW_UNITS = [FLOW_UNIT_STORY_BY_STORY, FLOW_UNIT_DELIVERY_STORY] as const;
+
+/** A Navigator stop as the cursor records it: the checkpoint, and what the Navigator owes. */
+export interface FlowStop {
+  readonly checkpoint: string;
+  readonly confirmation: string;
+}
+
+/**
+ * CR105: the question each flow unit's surface asks, as the cursor records it. The
+ * checkpoint is the surface's own id. Expand records the story-by-story stop, since
+ * its next-story question is the default flow's; choosing a flow unit records its
+ * own. The Delivery Story Plan replaces the scope stop, and nothing enforces it:
+ * CR001 declined a runtime-enforced scope stop, and this is recorded, not enforced.
+ */
+export const FLOW_STOPS: Readonly<Record<(typeof ALLOWED_FLOW_UNITS)[number], FlowStop>> = {
+  story_by_story: {
+    checkpoint: "next_story_confirmation",
+    confirmation: "navigator_story_confirmation",
+  },
+  delivery_story: {
+    checkpoint: "delivery_story_scope_confirmation",
+    confirmation: "navigator_scope_confirmation",
+  },
+};
+
+const FLOW_CONFIRMATIONS: ReadonlySet<string> = new Set(
+  Object.values(FLOW_STOPS).map((stop) => stop.confirmation),
+);
+
+/**
+ * CR105: why a flow unit cannot be chosen on this cursor, or null at a Delivery
+ * Story's flow decision: after Prepare or Expand, before its Plan. The active item is
+ * a Delivery Story, its Plan is not recorded, and nothing is pending but a flow stop,
+ * or nothing at all. Anywhere else the choice would print a question the cursor is not
+ * at, and after a Delivery Story Plan it stranded the Delivery Story: approval started
+ * its implementation under story-by-story flow, and its closure then refused.
+ *
+ * The sentence leads with the consequence, for the agent reading it.
+ */
+export function flowDecisionRefusal(cursor: BuilderDeliveryCursor): string | null {
+  const refused = "no flow unit was chosen";
+  const item = cursor.activeItem;
+  if (!item) {
+    return `${refused}: no item has been pulled yet, and a flow unit is chosen for an active Delivery Story.`;
+  }
+  if (cursor.activeItemLevel !== "delivery_story") {
+    const level = cursor.activeItemLevel
+      ? `is a ${cursor.activeItemLevel.replaceAll("_", " ")}`
+      : "is not a Delivery Story";
+    const deliveryStory = deliveryStoryCodeForItem(item);
+    const whose = deliveryStory ? `its Delivery Story, ${deliveryStory},` : "its Delivery Story";
+    return `${refused}: the active item, ${item}, ${level}. The flow unit is chosen for ${whose} before that Delivery Story's Plan.`;
+  }
+  if (hasDeliveryStoryPlan(cursor.aggregateCheckpointStatus)) {
+    return `${refused}: ${item}'s Delivery Story Plan is already recorded, and the flow unit is chosen before it.`;
+  }
+  const pending = cursor.pendingConfirmation;
+  if (pending !== null && !FLOW_CONFIRMATIONS.has(pending)) {
+    return `${refused}: ${item} is waiting for ${pending}, and the flow unit is chosen before its Plan.`;
+  }
+  return null;
+}
+
+/**
+ * Python `effective_navigator_flow_unit`.
+ *
+ * An unset or UNRECOGNIZED value falls back to `story_by_story` with source
+ * `default`, rather than raising — so a cursor written by a newer engine, or one
+ * carrying a typo, still yields a usable flow unit instead of blocking the
+ * lifecycle. The source is returned because the Navigator-facing surfaces
+ * distinguish "you chose this" from "this is the default".
+ */
+export function effectiveNavigatorFlowUnit(cursor: BuilderDeliveryCursor): {
+  flowUnit: string;
+  source: string;
+} {
+  const current = cursor.navigatorFlowUnit;
+  if (current !== null && (ALLOWED_FLOW_UNITS as readonly string[]).includes(current)) {
+    return { flowUnit: current, source: "cursor" };
+  }
+  return { flowUnit: FLOW_UNIT_STORY_BY_STORY, source: "default" };
+}
+
+export interface NavigatorFlowUnitReport {
+  readonly journey: string;
+  readonly method: string;
+  readonly activeItem: string | null;
+  readonly activeItemTitle: string | null;
+  readonly activeItemLevel: string | null;
+  readonly flowUnit: string;
+  readonly source: string;
+  readonly cursor: BuilderDeliveryCursor;
+}
+
+/**
+ * Python `set_navigator_flow_unit`.
+ *
+ * Validation BEFORE the cursor read, so an unknown unit reports the allowed values
+ * even when no cursor exists. The choice is made only at the Delivery Story's flow
+ * decision, and anywhere else it refuses before writing (`flowDecisionRefusal`). It
+ * is not a lifecycle transition: it writes the unit, `last_delivery_event`, and the
+ * stop its surface asks (CR105). Everything else on the cursor carries forward.
+ */
+export function setNavigatorFlowUnit(
+  db: WritableDatabase,
+  options: { journey: string; method: string; flowUnit: string },
+  deps: CursorWriteDeps,
+): NavigatorFlowUnitReport {
+  if (!(ALLOWED_FLOW_UNITS as readonly string[]).includes(options.flowUnit)) {
+    throw new Error(`navigator flow unit must be one of: ${ALLOWED_FLOW_UNITS.join(", ")}`);
+  }
+  const existing = getDeliveryCursor(db, options.journey);
+  if (existing === null) {
+    throw new Error("delivery cursor is required before choosing navigator flow unit");
+  }
+  const refusal = flowDecisionRefusal(existing);
+  if (refusal !== null) throw new Error(refusal);
+  const stop = FLOW_STOPS[options.flowUnit as (typeof ALLOWED_FLOW_UNITS)[number]];
+  const updated = setDeliveryCursor(
+    db,
+    {
+      journey: options.journey,
+      method: options.method,
+      activeItem: existing.activeItem,
+      activeItemTitle: existing.activeItemTitle,
+      activeItemLevel: existing.activeItemLevel,
+      activeCheckpoint: stop.checkpoint,
+      pendingConfirmation: stop.confirmation,
+      lastDeliveryEvent: "navigator_flow_unit_selected",
+      cadenceProfile: existing.cadenceProfile,
+      cadenceLimits: existing.cadenceLimits,
+      granularityDecision: existing.granularityDecision,
+      navigatorFlowUnit: options.flowUnit,
+      childWorkItems: existing.childWorkItems,
+      aggregateCheckpointStatus: existing.aggregateCheckpointStatus,
+    },
+    deps,
+  );
+  return {
+    journey: options.journey,
+    method: options.method,
+    activeItem: updated.activeItem,
+    activeItemTitle: updated.activeItemTitle,
+    activeItemLevel: updated.activeItemLevel,
+    flowUnit: options.flowUnit,
+    source: "cursor",
+    cursor: updated,
+  };
+}
+
+/** Python `inspect_navigator_flow_unit`. */
+export function inspectNavigatorFlowUnit(
+  db: WritableDatabase,
+  options: { journey: string; method: string },
+): NavigatorFlowUnitReport {
+  const cursor = getDeliveryCursor(db, options.journey);
+  if (cursor === null) {
+    throw new Error("delivery cursor is required before inspecting navigator flow unit");
+  }
+  const { flowUnit, source } = effectiveNavigatorFlowUnit(cursor);
+  return {
+    journey: options.journey,
+    method: options.method,
+    activeItem: cursor.activeItem,
+    activeItemTitle: cursor.activeItemTitle,
+    activeItemLevel: cursor.activeItemLevel,
+    flowUnit,
+    source,
+    cursor,
+  };
+}
+
+/** Python `_active_delivery`. */
+function activeDelivery(report: NavigatorFlowUnitReport): string {
+  if (report.activeItem === null) return "none";
+  const title = report.activeItemTitle ? ` — ${report.activeItemTitle}` : "";
+  return `🟦[${report.activeItem}]${title}`;
+}
+
+/** Python `_scope_item_lines`: an EMPTY list renders nothing, not `none`. */
+function scopeItemLines(label: string, items: readonly string[]): string[] {
+  if (items.length === 0) return [];
+  return [
+    "│                                                        │",
+    cardText(label),
+    ...cardPrefixed(items, "-"),
+  ];
+}
+
+/**
+ * Python `_delivery_story_scope_hypothesis`.
+ *
+ * The checkout/address special case is product copy, not a heuristic worth
+ * generalizing: it is reproduced verbatim because the surface is graded byte for
+ * byte.
+ */
+function deliveryStoryScopeHypothesis(report: NavigatorFlowUnitReport): string {
+  const title = pyStrip(report.activeItemTitle ?? "");
+  const normalized = title.toLowerCase();
+  if (normalized.includes("checkout") && normalized.includes("address")) {
+    return (
+      "This Delivery Story should let the customer enter checkout, provide or confirm " +
+      "a delivery address, and leave the order ready for the next checkout step."
+    );
+  }
+  if (title) return `This Delivery Story should deliver the scope implied by: ${title}.`;
+  return (
+    "I will infer a complete Delivery Story plan from the roadmap and project context; " +
+    "correct or add any scope details before I proceed."
+  );
+}
+
+/** Python `render_flow_unit_scope_confirmation_report`. */
+export function renderFlowUnitScopeConfirmationReport(report: NavigatorFlowUnitReport): string {
+  const deliveryStory = report.flowUnit === FLOW_UNIT_DELIVERY_STORY;
+  const surfaceName = deliveryStory
+    ? "delivery_story_scope_confirmation"
+    : "next_story_confirmation";
+  const title = deliveryStory
+    ? "       🧭  DELIVERY STORY SCOPE CONFIRMATION"
+    : "       🧭  NEXT STORY CONFIRMATION";
+  const understanding = deliveryStory
+    ? deliveryStoryScopeHypothesis(report)
+    : "We will continue story by story. The next step is to confirm which child story " +
+      "becomes the next Navigator-facing lifecycle unit.";
+  const scopeLabel = deliveryStory ? "Work packages in scope" : "Recommended story";
+  const scopeItems = deliveryStory
+    ? report.cursor.childWorkItems
+    : report.cursor.childWorkItems.slice(0, 1);
+  const prompt = deliveryStory
+    ? "Before I create the DS Plan, correct or add anything:"
+    : "Before I create the Story Plan, correct or add anything:";
+  const question = deliveryStory
+    ? "1. Is this the right scope?"
+    : "1. Is this the right next story?";
+  const body = [
+    "Delivery",
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    cardText(title),
+    "│                                                        │",
+    cardText("My understanding"),
+    ...cardWrapped(understanding),
+    "│                                                        │",
+    cardText("Active delivery"),
+    ...cardWrapped(activeDelivery(report)),
+    ...scopeItemLines(scopeLabel, scopeItems),
+    "│                                                        │",
+    ...cardWrapped(prompt),
+    ...cardWrapped(question),
+    "│                                                        │",
+    ...cardWrapped("Choose the next move when ready."),
+    "╰────────────────────────────────────────────────────────╯",
+  ];
+  return wrapAriadSurface(surfaceName, `${body.join("\n")}\n`);
+}
+
+/** Python `_flow_unit_change_summary` / `_description` / `_next_movement`. */
+function flowUnitChangeSummary(flowUnit: string): string {
+  return flowUnit === FLOW_UNIT_DELIVERY_STORY
+    ? "Navigator-facing lifecycle will continue at Delivery Story level."
+    : "Navigator-facing lifecycle will continue story by story.";
+}
+
+function flowUnitDescription(flowUnit: string): string {
+  return flowUnit === FLOW_UNIT_DELIVERY_STORY
+    ? "the Delivery Story becomes the lifecycle unit; child stories remain traceable work packages"
+    : "child stories get their own Navigator checkpoints";
+}
+
+function flowUnitNextMovement(flowUnit: string): string {
+  return flowUnit === FLOW_UNIT_DELIVERY_STORY
+    ? "Plan the Delivery Story as the Navigator-facing unit."
+    : "Confirm the recommended child story, then Plan.";
+}
+
+/** Python `render_navigator_flow_unit_report`: the READ face. */
+export function renderNavigatorFlowUnitReport(report: NavigatorFlowUnitReport): string {
+  const body = [
+    "Delivery",
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    "│        🧭  FLOW UNIT SELECTED                         │",
+    "│                                                        │",
+    cardText("What changed?"),
+    ...cardWrapped(flowUnitChangeSummary(report.flowUnit)),
+    "│                                                        │",
+    cardText("Active delivery"),
+    ...cardWrapped(activeDelivery(report)),
+    "│                                                        │",
+    cardText("Selected flow unit"),
+    cardText(report.flowUnit),
+    ...cardWrapped(flowUnitDescription(report.flowUnit)),
+    "│                                                        │",
+    cardText("Next movement"),
+    ...cardWrapped(flowUnitNextMovement(report.flowUnit)),
+    "│                                                        │",
+    ...cardWrapped("Choose the next move when ready."),
+    "╰────────────────────────────────────────────────────────╯",
+  ];
+  return wrapAriadSurface("navigator_flow_unit", `${body.join("\n")}\n`);
+}

package/ts/src/builder/homeSurface.ts

@@ -0,0 +1,122 @@
+// CV22.DS7.US8 plateau 1 — the Builder Orientation surface.
+//
+// Port of `render_builder_orientation_surface` in
+// `src/memory/builder/home_surface.py`. This is what `build load` shows an Ariad
+// journey with no active item, and it is almost entirely branches — which is what
+// a port collapses. Three of them are worth naming because each is a silent
+// behavior change if merged:
+//
+//   * `_available_refinement_moves` RETURNS EARLY for a canonical index, so the
+//     Workbench-storage move below it is unreachable in that state. An
+//     `if/elif` chain written without the early return appends it.
+//   * `_refinement_orientation_lines` has two shapes since CV22.DS10.TS4: a
+//     canonical index, and none.
+//   * It renders only without an active item, so since CR002 it takes the raw
+//     project-wide report, never a scope. Python placed the journey in the CV of
+//     a project-wide recommendation, synthesizing `🟪[CV99] roadmap focus` when
+//     that CV was absent from the snapshot. Now the journey is told no item was
+//     pulled, the list is labelled project-wide, and the first move is the
+//     literal Pull command. Its scoped branches were unreachable and went in
+//     CR002's handoff review.
+//
+// `render_builder_home_surface` was ported and never called: `build load`
+// renders `PROJECT_POSITION` and this surface. CR002 deleted it rather than
+// scope a surface no journey could see, whose one distinctive line was a
+// project-wide "recommended pull".
+//
+// CR115: it asks how the next item will run, and answers with the journey's cadence,
+// which shapes the next Plan; `build load` passes the cursor's, so every caller decides.
+
+import { type CadenceView, cadenceOrientationLines } from "./cadence.ts";
+import { cardPrefixed, cardText, cardWrapped } from "./card.ts";
+import type { PullCandidatesReport } from "./pullCandidates.ts";
+import { CANONICAL_REFINEMENT_INDEX, type RefinementFieldSnapshot } from "./refinementField.ts";
+import { NO_ITEM_PULLED_YET, PROJECT_WIDE_CANDIDATES, pullExplicitly } from "./scopePhrases.ts";
+import { wrapAriadSurface } from "./surfaceProtocol.ts";
+
+const FRAME_TOP = "╭────────────────────────────────────────────────────────╮";
+const FRAME_BOTTOM = "╰────────────────────────────────────────────────────────╯";
+const FRAME_BLANK = "│                                                        │";
+
+/**
+ * Python `_pull_candidate_lines`, project-wide. Python marked its project-wide
+ * recommendation with `▸`; without a journey scope there is none, so every
+ * candidate is a `·`.
+ */
+function pullCandidateLines(report: PullCandidatesReport): string[] {
+  const lines = [cardText(PROJECT_WIDE_CANDIDATES)];
+  if (report.candidates.length === 0) lines.push(cardText("none"));
+  for (const candidate of report.candidates) {
+    lines.push(...cardWrapped(`· ${candidate.code} ${candidate.title}`));
+  }
+  return lines;
+}
+
+/** Python `_refinement_orientation_lines`. Two shapes since CV22.DS10.TS4. */
+function refinementOrientationLines(refinement: RefinementFieldSnapshot): string[] {
+  if (refinement.canonicalIndex) {
+    return [
+      cardText("authority: project files"),
+      ...cardWrapped(`index: ${refinement.canonicalIndex}`),
+    ];
+  }
+  return [
+    cardText("authority: project files (not started)"),
+    ...cardWrapped(`create: ${CANONICAL_REFINEMENT_INDEX}`),
+  ];
+}
+
+/**
+ * Python `_available_refinement_moves`. The canonical-index path returns after
+ * three moves; the legacy path always appends a fourth. The first move is the
+ * literal Pull command: the surface renders only when no item has been pulled.
+ */
+export function availableRefinementMoves(
+  refinement: RefinementFieldSnapshot,
+  journey: string,
+): string[] {
+  const moves = [pullExplicitly(journey), "inspect roadmap"];
+  if (refinement.canonicalIndex) {
+    moves.push("inspect canonical Refinement index");
+    return moves;
+  }
+  moves.push(`create ${CANONICAL_REFINEMENT_INDEX}`);
+  return moves;
+}
+
+/**
+ * Python `render_builder_orientation_surface`, for a journey with no active item:
+ * `build load`'s only caller. `candidates` is the raw project-wide scan.
+ */
+export function renderBuilderOrientationSurface(options: {
+  candidates: PullCandidatesReport;
+  refinement: RefinementFieldSnapshot;
+  cadence: CadenceView;
+}): string {
+  const { candidates, refinement, cadence } = options;
+  const lines: string[] = [
+    "Builder Orientation",
+    "",
+    FRAME_TOP,
+    "│        ■  BUILDER ORIENTATION                          │",
+    FRAME_BLANK,
+    cardText("Where are we in the roadmap?"),
+    cardText(NO_ITEM_PULLED_YET),
+    FRAME_BLANK,
+    cardText("What can be pulled next?"),
+    ...pullCandidateLines(candidates),
+    FRAME_BLANK,
+    cardText("What is open for refinement?"),
+    ...refinementOrientationLines(refinement),
+    FRAME_BLANK,
+    cardText("How will the next item run?"),
+    ...cadenceOrientationLines(cadence),
+    FRAME_BLANK,
+    cardText("What can we do now?"),
+    ...cardPrefixed(availableRefinementMoves(refinement, candidates.journey), "-"),
+    FRAME_BLANK,
+    ...cardWrapped("Choose a move when ready."),
+    FRAME_BOTTOM,
+  ];
+  return wrapAriadSurface("builder_orientation", `${lines.join("\n")}\n`);
+}

package/ts/src/builder/implementationGuard.ts

@@ -0,0 +1,125 @@
+// CV22.DS7.US8 plateau 2 — the implementation guard.
+//
+// Port of `assert_implementation_allowed`,
+// `render_implementation_guard_allowed`, and
+// `render_implementation_guard_blocked` from `src/memory/builder/lifecycle.py`.
+// This is the leaf `build check-implementation` answers, and the reason it moved
+// out of plateau 1: it reads the delivery cursor.
+//
+// It is not a boolean. Four outcomes, and the order of the checks decides which
+// message a Navigator sees:
+//
+//   1. no cursor at all                       -> requires a delivery cursor
+//   2. ANY pending confirmation               -> blocked on that confirmation,
+//      even when the Plan is approved, because an unanswered checkpoint outranks
+//      an approval
+//   3. `last_delivery_event == "plan_approved"` -> allowed
+//   4. the Delivery Story combination        -> allowed, but only with ALL FOUR
+//      conditions: event `delivery_story_plan_approved`, level `delivery_story`,
+//      flow unit `delivery_story`, and `plan:approved` present in the aggregate
+//      checkpoint status. Miss any one and the generic refusal is what prints.
+//
+// Note what is NOT required: an active item. A cursor whose event is
+// `plan_approved` with no active item is ALLOWED, and the surface renders
+// `active item / none`. That reads like an oversight and is Python's behavior.
+
+import type { Database } from "#db/database.ts";
+import { cardText, cardWrapped } from "./card.ts";
+import type { BuilderDeliveryCursor } from "./deliveryCursor.ts";
+import { getDeliveryCursor } from "./deliveryCursor.ts";
+import { renderLifecycleRibbon } from "./lifecycleRibbon.ts";
+import { wrapAriadSurface } from "./surfaceProtocol.ts";
+
+const FRAME_TOP = "╭────────────────────────────────────────────────────────╮";
+const FRAME_BOTTOM = "╰────────────────────────────────────────────────────────╯";
+const FRAME_BLANK = "│                                                        │";
+const GUARD_TITLE = "│        🟧■  IMPLEMENTATION GUARD                       │";
+
+/** Python's `PermissionError` from the guard. */
+export class ImplementationBlockedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ImplementationBlockedError";
+  }
+}
+
+/** Python `_has_approved_delivery_story_plan`: all four conditions. */
+export function hasApprovedDeliveryStoryPlan(cursor: BuilderDeliveryCursor): boolean {
+  return (
+    cursor.lastDeliveryEvent === "delivery_story_plan_approved" &&
+    cursor.activeItemLevel === "delivery_story" &&
+    cursor.navigatorFlowUnit === "delivery_story" &&
+    cursor.aggregateCheckpointStatus.includes("plan:approved")
+  );
+}
+
+/** Python `assert_implementation_allowed`. */
+export function assertImplementationAllowed(db: Database, journey: string): BuilderDeliveryCursor {
+  const normalized = typeof journey === "string" ? journey.trim() : "";
+  if (!normalized) throw new Error("journey must not be empty");
+  const cursor = getDeliveryCursor(db, normalized);
+  if (cursor === null) {
+    throw new ImplementationBlockedError("Implementation requires a Builder delivery cursor");
+  }
+  if (cursor.pendingConfirmation) {
+    throw new ImplementationBlockedError(
+      `Implementation is blocked: pending confirmation ${cursor.pendingConfirmation}.`,
+    );
+  }
+  if (cursor.lastDeliveryEvent === "plan_approved") return cursor;
+  if (hasApprovedDeliveryStoryPlan(cursor)) return cursor;
+  throw new ImplementationBlockedError(
+    "Implementation is blocked: approved Plan is required before Implement.",
+  );
+}
+
+/** Python `render_implementation_guard_allowed`. */
+export function renderImplementationGuardAllowed(cursor: BuilderDeliveryCursor): string {
+  const body = [
+    "Delivery",
+    renderLifecycleRibbon("implement", cursor.activeItemLevel),
+    "",
+    FRAME_TOP,
+    GUARD_TITLE,
+    FRAME_BLANK,
+    cardText("status"),
+    cardText("allowed"),
+    FRAME_BLANK,
+    cardText("active item"),
+    cardText(cursor.activeItem || "none"),
+    FRAME_BLANK,
+    cardText("last delivery event"),
+    cardText(cursor.lastDeliveryEvent || "none"),
+    FRAME_BLANK,
+    cardText("boundary"),
+    ...cardWrapped("Implementation may begin under the approved Plan contract."),
+    FRAME_BOTTOM,
+  ].join("\n");
+  return wrapAriadSurface("implementation_guard", `${body}\n`);
+}
+
+/**
+ * Python `render_implementation_guard_blocked`. The level is the cursor's, when there
+ * is one: the refusal carries only its reason, and a story's ribbon must still say
+ * Expand never applied (CR113).
+ */
+export function renderImplementationGuardBlocked(reason: string, level: string | null): string {
+  const body = [
+    "Delivery",
+    renderLifecycleRibbon("implement", level),
+    "",
+    FRAME_TOP,
+    GUARD_TITLE,
+    FRAME_BLANK,
+    cardText("status"),
+    cardText("blocked"),
+    FRAME_BLANK,
+    cardText("missing checkpoint"),
+    ...cardWrapped(reason),
+    FRAME_BLANK,
+    cardText("boundary"),
+    ...cardWrapped("No implementation files may be mutated until the guard allows Implement."),
+    FRAME_BOTTOM,
+  ].join("\n");
+  return wrapAriadSurface("implementation_guard", `${body}\n`);
+}

package/ts/src/builder/index.ts

@@ -0,0 +1,11 @@
+// Lazy Builder boundary for the front door (CV22.DS7.US8 plateau 8).
+//
+// `frontDoor/cli.ts` imports this module only when a `build` command is routed.
+// Keeping the whole Builder command tree behind one module is what keeps every
+// other command working when this one cannot load.
+
+export {
+  invokeBuilderArgv,
+  invokeReadOnlyBuilderArgv,
+  READ_ONLY_BUILDER_SUBCOMMANDS,
+} from "./argv.ts";