mirror-mind 0.0.1 → 0.33.0

package/ts/src/builder/deliveryStoryReady.ts

@@ -0,0 +1,160 @@
+// CV22.DS7.US8 plateau 3 — the post-Pull orientation for a Delivery Story.
+//
+// Port of `render_delivery_story_ready_report` and its helpers from
+// `src/memory/builder/lifecycle.py`.
+//
+// This is the only surface composed from THREE reports — Pull, Prepare, and Expand —
+// which is why it lives in its own module rather than inside any one event. The CLI
+// renders it instead of the Pull and Prepare surfaces when the pulled item is a
+// Delivery Story, so a port that emits all three has a duplicate-surface defect no
+// renderer-level test can see.
+//
+// Its ribbon is also its own: `DS Plan` rather than `Plan`, from a stage list that
+// exists nowhere else.
+
+import { basename, dirname } from "node:path";
+import { kebabSlug } from "#util/slug.ts";
+import { cardPrefixed, cardText, cardWrapped } from "./card.ts";
+import type { BuilderExpandReport } from "./expand.ts";
+import type { BuilderPrepareReport } from "./prepare.ts";
+import { type BuilderPullReport, placementRows } from "./pull.ts";
+import { wrapAriadSurface } from "./surfaceProtocol.ts";
+
+/** Python `_delivery_story_flow_ribbon`: the Delivery-Story-level stage labels. */
+export function deliveryStoryFlowRibbon(current: string): string {
+  const stages: [string, string][] = [
+    ["pull", "Pull"],
+    ["prepare", "Prepare"],
+    ["expand", "Expand"],
+    ["plan", "DS Plan"],
+    ["implement", "Implement"],
+    ["validate", "Validate"],
+    ["debt_review", "Debt Review"],
+    ["done", "Done"],
+  ];
+  const index = stages.findIndex(([stage]) => stage === current);
+  if (index === -1) throw new Error(`unknown Delivery Story lifecycle stage: ${current}`);
+  const parts = stages.map(([, label], position) => {
+    const marker = position < index ? "✓" : position === index ? "◉" : "○";
+    return `${marker} ${label}`;
+  });
+  return `Delivery Flow: ${parts.join(" → ")}`;
+}
+
+/** Python `_prepare_finding`. */
+function prepareFinding(report: BuilderPrepareReport): string {
+  return report.granularityDecisionRequired
+    ? "Delivery Story requires a granularity decision before implementation."
+    : "Pulled story is implementable after Plan approval.";
+}
+
+/**
+ * Python `_materialized_summary`.
+ *
+ * Three chained guesses at what a materialized path IS, in Python's order, then a
+ * de-duplication that preserves first appearance. The last branch falls back to the
+ * folder NAME, which is why an unexpected layout degrades into something readable
+ * rather than failing.
+ */
+function materializedSummary(report: BuilderExpandReport): string[] {
+  if (report.materializedPaths.length === 0) return ["none"];
+  const deliveryStorySlug = kebabSlug(report.deliveryStory.toLowerCase());
+  const recommendedLeaf = report.recommendedStory.split(".").at(-1) ?? report.recommendedStory;
+  const recommendedSlug = kebabSlug(recommendedLeaf.toLowerCase());
+  const summaries: string[] = [];
+  for (const path of report.materializedPaths) {
+    const parentName = basename(dirname(path));
+    if (parentName === deliveryStorySlug) {
+      summaries.push("DS package");
+    } else if (parentName.endsWith(recommendedSlug)) {
+      summaries.push(`${recommendedLeaf} package`);
+    } else if (path.includes(report.deliveryStory.toLowerCase().replaceAll(".", "-"))) {
+      summaries.push("DS package");
+    } else {
+      summaries.push(parentName);
+    }
+  }
+  const deduped: string[] = [];
+  for (const summary of summaries) {
+    if (!deduped.includes(summary)) deduped.push(summary);
+  }
+  return deduped;
+}
+
+/**
+ * Python `_flow_unit_recommendation`.
+ *
+ * `max(1, len(materialized_artifacts) - 1)` — the artifact list carries the DS
+ * package plus one entry per child, so subtracting one counts children, and the
+ * floor keeps a single-child Delivery Story from reading as zero.
+ */
+function flowUnitRecommendation(report: BuilderExpandReport): string {
+  const childCount = Math.max(1, report.materializedArtifacts.length - 1);
+  return childCount <= 1
+    ? "delivery_story — recommended"
+    : "delivery_story — recommended unless you want separate Navigator validation for each child story";
+}
+
+/** Python `_flow_unit_recommendation_rationale`. */
+function flowUnitRecommendationRationale(report: BuilderExpandReport): string {
+  const childCount = Math.max(1, report.materializedArtifacts.length - 1);
+  return childCount <= 1
+    ? "The Delivery Story appears coherent enough to plan, implement, and validate as one Navigator-facing unit while keeping the child story as a traceable work package."
+    : "The child work packages appear to support one Delivery Story outcome. Use story_by_story only if each child needs separate Navigator checkpoints.";
+}
+
+/** Python `render_delivery_story_ready_report`, with the CV named by `placementCvTitle`. */
+export function renderDeliveryStoryReadyReport(reports: {
+  pull: BuilderPullReport;
+  prepare: BuilderPrepareReport;
+  expand: BuilderExpandReport;
+  cvTitle: string;
+}): string {
+  const { pull, prepare, expand, cvTitle } = reports;
+  const title = pull.item.title;
+  const recommendedLeaf = expand.recommendedStory.split(".").at(-1) ?? expand.recommendedStory;
+  const body = `${[
+    "Delivery",
+    deliveryStoryFlowRibbon("expand"),
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    cardText(`🧭 ${pull.item.code} READY`),
+    "│                                                        │",
+    cardText("What was pulled?"),
+    ...cardWrapped(title),
+    "│                                                        │",
+    cardText("Where are we in the roadmap?"),
+    // The Pull card's lineage renderer, one level shorter: a Delivery Story (CR113).
+    ...placementRows(pull.item, { cvTitle, deliveryStory: null }),
+    "│                                                        │",
+    cardText("What did Prepare find?"),
+    ...cardWrapped(prepareFinding(prepare)),
+    "│                                                        │",
+    cardText("What was materialized?"),
+    ...cardPrefixed(materializedSummary(expand), "✓"),
+    "│                                                        │",
+    cardText("What is recommended next?"),
+    // Whole: the skill tells the agent to pull the confirmed child by this title (CR018).
+    ...cardWrapped(`🟩[${recommendedLeaf}] ${expand.recommendedStoryTitle}`),
+    "│                                                        │",
+    cardText("Recommended flow unit"),
+    ...cardWrapped(flowUnitRecommendation(expand)),
+    "│                                                        │",
+    cardText("Why this recommendation?"),
+    ...cardWrapped(flowUnitRecommendationRationale(expand)),
+    "│                                                        │",
+    cardText("What can we do now?"),
+    ...cardPrefixed(
+      [
+        `confirm ${recommendedLeaf} and continue story_by_story`,
+        "choose delivery_story as the flow unit",
+        "inspect generated story packages",
+      ],
+      "-",
+    ),
+    "│                                                        │",
+    ...cardWrapped("Choose the next flow unit when ready."),
+    "╰────────────────────────────────────────────────────────╯",
+  ].join("\n")}\n`;
+  return wrapAriadSurface("delivery_story_ready", body);
+}

package/ts/src/builder/deliveryStoryRoadmapClosure.ts

@@ -0,0 +1,151 @@
+// CV22.DS7.US8 plateau 5 — the authored-roadmap preflight for Delivery Story Done.
+//
+// Port of `src/memory/builder/delivery_story_roadmap_closure.py`.
+//
+// Every other Builder guard reads the delivery cursor. This one reads the
+// NAVIGATOR'S REPOSITORY: before a Delivery Story may close, its own package, every
+// known child package, and every canonical table row naming those codes must
+// already say Done in authored Markdown. The agent owns the semantic edit; this
+// verifies explicit evidence and never invents project meaning.
+//
+// Three details decide whether a port refuses the same closures Python refuses:
+//
+//   1. **The walk includes `legacy/`.** Python calls `rglob("index.md")` with no
+//      exclusion here, unlike the three grammar call sites. An archived row for a
+//      known code blocks Done — reproduced, and pinned by
+//      `authored_closure_reads_legacy_rows`.
+//   2. **The status pattern is LINE-ANCHORED.** `_STATUS_RE` is
+//      `^\*\*Status:\*\*...$` under `re.MULTILINE`, so unlike `roadmapGrammar`'s
+//      unanchored `STATUS_RE` the marker must open its line. Written with explicit
+//      `(?<=^|\n)` / `(?=\n|$)` anchors because JavaScript's `m` flag also anchors
+//      at U+2028/U+2029, where Python's does not.
+//   3. **`_is_done` is a SUFFIX test:** `strip().casefold().endswith("done")`. So
+//      `Done` and `✅ DONE` pass while `✅ Done (2026-09-14)` does not — the dated
+//      form this repository's own roadmap uses. Parity-bound, recorded as a CR
+//      candidate rather than smoothed here.
+//
+// Read-only by construction: nothing in this module writes.
+
+import { readFileSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+import { PYTHON_WHITESPACE_CLASS, pyStrip } from "#util/pythonText.ts";
+import { projectRelative } from "./projectPaths.ts";
+import { stripMarkdownLink, tableRowCells } from "./roadmapGrammar.ts";
+import { scanRoadmapIndexFiles } from "./roadmapScan.ts";
+import { resolveStoryDirectory } from "./storyPaths.ts";
+
+const WS = `[${PYTHON_WHITESPACE_CLASS}]`;
+
+/** Python `_STATUS_RE`: line-anchored, first match wins. */
+const STATUS_LINE_RE = new RegExp(
+  `(?<=^|\\n)\\*\\*Status:\\*\\*${WS}*(?<status>[^\\n]+?)${WS}*(?=\\n|$)`,
+  "u",
+);
+
+export interface AuthoredClosureReport {
+  /** True when nothing blocks Done. */
+  readonly ready: boolean;
+  /** Project-relative evidence, in the order Python discovers it. */
+  readonly issues: readonly string[];
+}
+
+/** Python `_is_done`. */
+function isDone(status: string): boolean {
+  return pyStrip(status).toLowerCase().endsWith("done");
+}
+
+/**
+ * Python `_relative`: project-relative POSIX, raising when the path escapes. The
+ * relation comes from the core every surface names paths with (CR082); this caller
+ * refuses the project root and a path outside, where a surface prints `.` or the path
+ * as given.
+ */
+export function relativeOrRefuse(path: string, projectRoot: string): string {
+  const relation = projectRelative(path, projectRoot);
+  if (relation === null || relation === "") {
+    // Python raises `ValueError` from `relative_to` here and the CLI prints
+    // CPython's own prose. Recorded divergence (plan, Parity Contract): the
+    // message is ours, the refusal is the same.
+    throw new Error(
+      `roadmap file ${path} is not inside the project at ${projectRoot}; ` +
+        "refusing to name a path outside the project in a closure refusal",
+    );
+  }
+  return relation.split(sep).join("/");
+}
+
+/** Python `_status_table_rows`: header-driven `Code`/`Status` extraction. */
+function statusTableRows(indexPath: string): [string, string][] {
+  const rows: [string, string][] = [];
+  let columns: { code: number; status: number } | null = null;
+  let content: string;
+  try {
+    content = readFileSync(indexPath, "utf8");
+  } catch {
+    return rows;
+  }
+  for (const rawLine of content.split("\n")) {
+    const line = pyStrip(rawLine);
+    if (!line.startsWith("|")) {
+      // A non-table line CLOSES the table: a second table later in the file needs
+      // its own header, exactly as Python's loop resets `columns`.
+      columns = null;
+      continue;
+    }
+    const cells = tableRowCells(line);
+    if (columns === null) {
+      const lowered = cells.map((cell) => cell.toLowerCase());
+      const code = lowered.indexOf("code");
+      const status = lowered.indexOf("status");
+      if (code !== -1 && status !== -1) columns = { code, status };
+      continue;
+    }
+    if (cells.every((cell) => cell === "" || /^[-:]+$/u.test(cell))) continue;
+    if (cells.length <= Math.max(columns.code, columns.status)) continue;
+    rows.push([stripMarkdownLink(cells[columns.code] ?? ""), cells[columns.status] ?? ""]);
+  }
+  return rows;
+}
+
+/**
+ * Python `inspect_authored_closure`.
+ *
+ * Package evidence first, in cursor order (the Delivery Story, then each child),
+ * then every table row under the roadmap in path order. The issue ORDER is part of
+ * the refusal message the CLI joins with `; `, so it is behavior.
+ */
+export function inspectAuthoredClosure(
+  projectPath: string,
+  options: { deliveryStory: string; childWorkItems: readonly string[] },
+): AuthoredClosureReport {
+  const projectRoot = resolve(projectPath);
+  const issues: string[] = [];
+  const codes = [options.deliveryStory, ...options.childWorkItems];
+  for (const code of codes) {
+    const packagePath = resolveStoryDirectory(projectRoot, code);
+    if (packagePath === null) {
+      issues.push(`docs/project/roadmap: package ${code} was not found`);
+      continue;
+    }
+    const indexPath = join(packagePath, "index.md");
+    const content = readFileSync(indexPath, "utf8");
+    const status = STATUS_LINE_RE.exec(content)?.groups?.status;
+    if (status === undefined || !isDone(status)) {
+      issues.push(`${relativeOrRefuse(indexPath, projectRoot)}: package status is not Done`);
+    }
+  }
+
+  const roadmapRoot = join(projectRoot, "docs", "project", "roadmap");
+  const known = new Set(codes);
+  for (const file of scanRoadmapIndexFiles(roadmapRoot, { includeLegacy: true })) {
+    for (const [code, status] of statusTableRows(file.absolutePath)) {
+      if (known.has(code) && !isDone(status)) {
+        issues.push(
+          `${relativeOrRefuse(file.absolutePath, projectRoot)}: table row ${code} is not Done`,
+        );
+      }
+    }
+  }
+
+  return { ready: issues.length === 0, issues };
+}

package/ts/src/builder/expand.ts

@@ -0,0 +1,336 @@
+// CV22.DS7.US8 plateau 3 — Expand: a Delivery Story becomes implementable stories.
+//
+// Port of `expand_delivery_story` and its renderers from
+// `src/memory/builder/lifecycle.py`.
+//
+// Expand is the highest-consequence command in this plateau, because it is the one
+// that WRITES INTO AUTHORED CONTENT. Three properties are load-bearing and each
+// has already cost this project a defect:
+//
+//   * **It resolves the package by heading code, never by arithmetic on code and
+//     title** (`storyPaths`). An authored package lives wherever a human put it.
+//     CR048 was this, twice.
+//   * **It refuses rather than fabricates.** An authored package whose candidate
+//     table does not parse blocks Expand. The alternative — inventing a generic
+//     `US1` on top of real authored content — is the CV22.DS7 secondary defect,
+//     and it is worse than failing because the fabrication looks like work.
+//   * **It never overwrites.** Every write is guarded by "does this exist", so
+//     re-expanding an authored package reports `existing` and changes nothing.
+//     "Exists" means a package whose heading claims the child's code, wherever it
+//     lives, not a file at the folder Expand would have named. Until CR018 it meant
+//     the folder, so a child a human had filed elsewhere was written a second time.
+//
+// The candidate-table parser is header-driven on purpose: it accepts the 4-column
+// authored shape and the 5-column generated one, in any column order, with extra
+// columns ignored. What it does not accept is a table that fails to declare Code,
+// Story, Type, and Status — which is precisely the refusal above.
+
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { WritableDatabase } from "#db/database.ts";
+import { existingArtifact, type MaterializedArtifact } from "./artifacts/artifactSurfaces.ts";
+import { writeBuilderArtifact } from "./artifacts/artifactWriter.ts";
+import { artifactState, describeArtifactState } from "./artifacts/scaffoldState.ts";
+import {
+  renderDeliveryStoryIndex,
+  renderStoryIndex,
+  renderUserStoryIndex,
+} from "./artifacts/storyIndex.ts";
+import { cardText, cardWrapped } from "./card.ts";
+import { normalizeRequired } from "./cursorTransitions.ts";
+import {
+  type BuilderDeliveryCursor,
+  type CursorWriteDeps,
+  getDeliveryCursor,
+  setDeliveryCursor,
+} from "./deliveryCursor.ts";
+import { FLOW_STOPS } from "./flowUnit.ts";
+import { renderLifecycleRibbon } from "./lifecycleRibbon.ts";
+import { displayPath } from "./projectPaths.ts";
+import { type CandidateChild, parseCandidateStories } from "./roadmapGrammar.ts";
+import { createStoryDirectory, storyDirectoryResolver, storyFolderName } from "./storyPaths.ts";
+import { wrapAriadSurface } from "./surfaceProtocol.ts";
+
+/**
+ * Python `ExpandBlockedError`.
+ *
+ * A distinct type, not a bare `Error`: the CLI catches it alongside
+ * `StoryPackageAmbiguityError` to render `EXPAND_BLOCKED`, while an ordinary
+ * `ValueError` from a guard stays a plain stderr refusal.
+ */
+export class ExpandBlockedError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ExpandBlockedError";
+  }
+}
+
+/** Python `BuilderExpandReport`. */
+export interface BuilderExpandReport {
+  readonly journey: string;
+  readonly method: string;
+  readonly deliveryStory: string;
+  readonly deliveryStoryTitle: string;
+  readonly materializedPaths: readonly string[];
+  readonly materializedArtifacts: readonly MaterializedArtifact[];
+  readonly recommendedStory: string;
+  readonly recommendedStoryTitle: string;
+  readonly cursor: BuilderDeliveryCursor;
+  readonly nextEvent: string;
+}
+
+/**
+ * Python `_first_pending_child`.
+ *
+ * "Done" is matched as a SUBSTRING of the status cell in both cases, so `✅ Done`
+ * and `done` both count and `Doneness` would too. Falls back to the first child
+ * when every child is done, so Expand always recommends something.
+ */
+function firstPendingChild(children: readonly CandidateChild[]): CandidateChild {
+  for (const child of children) {
+    if (!child.status.includes("Done") && !child.status.includes("done")) return child;
+  }
+  return children[0] as CandidateChild;
+}
+
+/**
+ * Python `_materialize_child_package`: the child's FULL title slugs its folder.
+ *
+ * `authored` is the package that already claims the child's code, found by heading
+ * before Expand wrote anything. It is reported where it lives and never written.
+ */
+/** An existing child index, named with what it is: a scaffold or an authored file (CR112). */
+function existingIndex(label: string, path: string): MaterializedArtifact {
+  return existingArtifact(
+    label,
+    path,
+    describeArtifactState(artifactState("index.md", path).state),
+  );
+}
+
+function materializeChildPackage(
+  dsDirectory: string,
+  child: CandidateChild,
+  authored: string | null,
+  projectRoot: string,
+): { path: string; artifact: MaterializedArtifact } {
+  const label = `${child.code.split(".").at(-1) ?? child.code} package`;
+  if (authored !== null) {
+    const authoredIndex = join(authored, "index.md");
+    return { path: authoredIndex, artifact: existingIndex(label, authoredIndex) };
+  }
+  // The whole title slugs the folder, as it does for any new package (CR018).
+  const childDirectory = join(dsDirectory, storyFolderName(child.code, child.title));
+  const childIndex = join(childDirectory, "index.md");
+  const outcome = writeBuilderArtifact({
+    path: childIndex,
+    content: renderStoryIndex(child.code, child.title, child.level),
+    policy: "create-only",
+    projectRoot,
+  });
+  return {
+    path: childIndex,
+    artifact:
+      outcome === "existing"
+        ? existingIndex(label, childIndex)
+        : { kind: label, path: childIndex, status: "created" },
+  };
+}
+
+export interface ExpandOptions {
+  readonly journey: string;
+  readonly method: string;
+  readonly projectPath: string;
+}
+
+/** Python `expand_delivery_story`. */
+export function expandDeliveryStory(
+  db: WritableDatabase,
+  options: ExpandOptions,
+  deps: CursorWriteDeps,
+): BuilderExpandReport {
+  const journey = normalizeRequired(options.journey, "journey");
+  const method = normalizeRequired(options.method, "method");
+
+  const existing = getDeliveryCursor(db, journey);
+  if (existing === null) throw new Error("delivery cursor is required before expand");
+  // Level before item: a cursor with no active item but the wrong level reports
+  // the LEVEL problem. Guard order is observable, so it is preserved.
+  if (existing.activeItemLevel !== "delivery_story") {
+    throw new Error("expand requires an active Delivery Story");
+  }
+  if (!existing.activeItem) throw new Error("active item is required before expand");
+
+  const activeItem = existing.activeItem;
+  const title = existing.activeItemTitle || activeItem;
+  // One reading of the roadmap answers for the Delivery Story and for every child, so
+  // each is settled before the first write (CR018).
+  const packageOf = storyDirectoryResolver(options.projectPath);
+  const dsDirectory =
+    packageOf(activeItem) ?? createStoryDirectory(options.projectPath, activeItem, title);
+  const dsIndex = join(dsDirectory, "index.md");
+  const dsExists = existsSync(dsIndex);
+  const children = dsExists ? parseCandidateStories(readFileSync(dsIndex, "utf8")) : [];
+
+  // CR082: a refusal names the package relative to the project, where it is raised, so
+  // `EXPAND_BLOCKED` prints the reason as given and copies no home directory anywhere.
+  if (dsExists && children.length === 0) {
+    throw new ExpandBlockedError(
+      `authored package at ${displayPath(dsDirectory, options.projectPath)} has no ` +
+        "canonical candidate-stories table " +
+        "(a Markdown table header must include Code, Story, Type, and Status columns); " +
+        "refusing to fabricate a generic story",
+    );
+  }
+
+  const materializedPaths: string[] = [dsIndex];
+  const materializedArtifacts: MaterializedArtifact[] = [];
+  let recommendedCode: string;
+  let recommendedTitle: string;
+  let childWorkItems: string[];
+
+  if (children.length > 0) {
+    const recommended = firstPendingChild(children);
+    recommendedCode = recommended.code;
+    recommendedTitle = recommended.title;
+    // Before any write: a child two packages claim throws here, while EXPAND_BLOCKED's
+    // "No files were materialized" is still true.
+    const placements = children.map((child) => ({ child, authored: packageOf(child.code) }));
+    mkdirSync(dsDirectory, { recursive: true });
+    const dsOutcome = writeBuilderArtifact({
+      path: dsIndex,
+      content: renderDeliveryStoryIndex(activeItem, title, recommendedCode, recommendedTitle),
+      policy: "create-only",
+      projectRoot: options.projectPath,
+    });
+    materializedArtifacts.push(
+      dsOutcome === "existing"
+        ? existingArtifact("DS package", dsIndex)
+        : { kind: "DS package", path: dsIndex, status: "created" },
+    );
+    for (const { child, authored } of placements) {
+      const materialized = materializeChildPackage(
+        dsDirectory,
+        child,
+        authored,
+        options.projectPath,
+      );
+      materializedPaths.push(materialized.path);
+      materializedArtifacts.push(materialized.artifact);
+    }
+    childWorkItems = children.map((child) => child.code);
+  } else {
+    // No authored package at all: synthesize one child so the Delivery Story has
+    // something implementable. This is not fabrication on top of authored content
+    // — the refusal above already covers that case — it is the empty-field case.
+    recommendedCode = `${activeItem}.US1`;
+    recommendedTitle = title;
+    const claimed = packageOf(recommendedCode);
+    if (claimed !== null) {
+      throw new ExpandBlockedError(
+        `${activeItem} has no package, and an authored package already claims ` +
+          `${recommendedCode} at ${displayPath(claimed, options.projectPath)}; ` +
+          "refusing to invent a story over it",
+      );
+    }
+    const usDirectory = join(dsDirectory, storyFolderName(recommendedCode, recommendedTitle));
+    const usIndex = join(usDirectory, "index.md");
+    mkdirSync(dsDirectory, { recursive: true });
+    mkdirSync(usDirectory, { recursive: true });
+    const dsOutcome = writeBuilderArtifact({
+      path: dsIndex,
+      content: renderDeliveryStoryIndex(activeItem, title, recommendedCode, recommendedTitle),
+      policy: "create-only",
+      projectRoot: options.projectPath,
+    });
+    const usOutcome = writeBuilderArtifact({
+      path: usIndex,
+      content: renderUserStoryIndex(recommendedCode, recommendedTitle),
+      policy: "create-only",
+      projectRoot: options.projectPath,
+    });
+    materializedArtifacts.push(
+      dsOutcome === "existing"
+        ? existingArtifact("DS package", dsIndex)
+        : { kind: "DS package", path: dsIndex, status: "created" },
+    );
+    const label = `${recommendedCode.split(".").at(-1) ?? recommendedCode} package`;
+    materializedArtifacts.push(
+      usOutcome === "existing"
+        ? existingArtifact(label, usIndex)
+        : { kind: label, path: usIndex, status: "created" },
+    );
+    materializedPaths.push(usIndex);
+    childWorkItems = [recommendedCode];
+  }
+
+  const cursor = setDeliveryCursor(
+    db,
+    {
+      journey,
+      method,
+      activeItem: existing.activeItem,
+      activeItemTitle: existing.activeItemTitle,
+      activeItemLevel: existing.activeItemLevel,
+      // The default flow's question, the one DELIVERY_STORY_READY recommends answering
+      // or replacing with a choice of Delivery Story flow (CR105).
+      activeCheckpoint: FLOW_STOPS.story_by_story.checkpoint,
+      pendingConfirmation: FLOW_STOPS.story_by_story.confirmation,
+      lastDeliveryEvent: "expand",
+      cadenceProfile: existing.cadenceProfile,
+      cadenceLimits: existing.cadenceLimits,
+      granularityDecision: "expanded_to_implementable_stories",
+      navigatorFlowUnit: existing.navigatorFlowUnit,
+      // Replaced wholesale, so a previous Delivery Story's children cannot survive.
+      childWorkItems,
+      aggregateCheckpointStatus: existing.aggregateCheckpointStatus,
+    },
+    deps,
+  );
+
+  return {
+    journey,
+    method,
+    deliveryStory: activeItem,
+    deliveryStoryTitle: title,
+    materializedPaths,
+    materializedArtifacts,
+    recommendedStory: recommendedCode,
+    recommendedStoryTitle: recommendedTitle,
+    cursor,
+    nextEvent: "plan",
+  };
+}
+
+/** Python `render_expand_blocked`. */
+export function renderExpandBlocked(activeItem: string, reason: string): string {
+  const body = `${[
+    "Delivery",
+    // Expand is a Delivery Story's stage; only a Delivery Story reaches it (CR113).
+    renderLifecycleRibbon("expand", "delivery_story"),
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    "│        🧭◆  EXPAND BLOCKED                             │",
+    "│                                                        │",
+    cardText("delivery story"),
+    cardText(`🟦[${activeItem}]`),
+    "│                                                        │",
+    cardText("why blocked"),
+    ...cardWrapped(reason),
+    "│                                                        │",
+    cardText("required Navigator action"),
+    // Names the Delivery Story rather than "the resolved package": the refusal CR018
+    // added is for a Delivery Story that has no package to resolve.
+    ...cardWrapped(
+      "Add a canonical candidate-stories table (Markdown table header including " +
+        `Code, Story, Type, and Status columns) to ${activeItem}'s index.md, ` +
+        "creating it if the Delivery Story has none, or resolve the duplicate heading, " +
+        "then Expand again.",
+    ),
+    "│                                                        │",
+    cardText("boundary"),
+    ...cardWrapped("No files were materialized. Expand refuses to fabricate a generic story."),
+    "╰────────────────────────────────────────────────────────╯",
+  ].join("\n")}\n`;
+  return wrapAriadSurface("expand_blocked", body);
+}