mirror-mind 0.0.1 → 0.33.0

package/ts/src/builder/prepare.ts

@@ -0,0 +1,225 @@
+// CV22.DS7.US8 plateau 3 — Prepare: read the terrain, decide nothing.
+//
+// Port of `prepare_lifecycle_item` and `render_prepare_report` from
+// `src/memory/builder/lifecycle.py`.
+//
+// Prepare is the cheapest event in the lifecycle and the easiest to get subtly
+// wrong, because almost all of its output is derived from ONE field: the active
+// item's level. That field decides whether the story is implementable, whether a
+// granularity decision is required, which rule text appears, and whether the next
+// event renders as `Plan` or `Expand or Plan`. An unknown level is a third case,
+// not an error.
+//
+// It also writes: the cursor moves to `last_delivery_event=prepare` and clears any
+// pending confirmation, which is what lets Plan's `Prepare must be completed`
+// guard mean something.
+//
+// CR114 (D3): which is also why it must not run from anywhere. It ran on any cursor,
+// so a Done story prepared again went back before Plan, where Plan accepted it. It now
+// runs only at Pull, at Prepare again, or on an item with no event, and refuses
+// anywhere else before writing: as already complete from Plan on, by CR067's rule,
+// and as not its place at a Delivery Story's own events or an event it does not know.
+
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import type { WritableDatabase } from "#db/database.ts";
+import { pyTitle } from "#util/pythonText.ts";
+import { cardContextItems, cardPrefixed, cardText, cardWrapped } from "./card.ts";
+import { isImplementableByDefault, 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 { wrapAriadSurface } from "./surfaceProtocol.ts";
+
+/** Python `BuilderPrepareReport`. */
+export interface BuilderPrepareReport {
+  readonly journey: string;
+  readonly method: string;
+  readonly activeItem: string;
+  readonly activeItemTitle: string | null;
+  readonly activeItemLevel: string | null;
+  readonly implementableByDefault: boolean;
+  readonly granularityDecisionRequired: boolean;
+  readonly contextSummary: readonly string[];
+  readonly storyShapeAssessment: string;
+  readonly risks: readonly string[];
+  readonly applicableRules: readonly string[];
+  readonly cursor: BuilderDeliveryCursor;
+  readonly nextEvent: string;
+}
+
+/** Python `_story_shape_assessment`: three cases, the third being an unknown level. */
+function storyShapeAssessment(level: string | null): string {
+  if (isImplementableByDefault(level)) {
+    return "Pulled item is implementable by default. Plan may define the execution contract.";
+  }
+  if (level === "delivery_story") {
+    return (
+      "Pulled item is a Delivery Story. Ariad requires a granularity decision before " +
+      "implementation: expand into User/Technical Stories or approve this Delivery Story " +
+      "as one coherent implementable story."
+    );
+  }
+  return "Pulled item level is unknown. Treat granularity as requiring Navigator decision.";
+}
+
+/** Python `_next_event_rule`. */
+function nextEventRule(level: string | null): string {
+  return isImplementableByDefault(level)
+    ? "Plan is the next event and requires Navigator approval before implementation."
+    : "Expand or explicit single-story approval is required before implementation.";
+}
+
+/** The development guide Prepare reports on, and the one a Plan points to (CR019). */
+export const DEVELOPMENT_GUIDE_PATH = "docs/process/development-guide.md";
+
+/**
+ * A project's own rules for a Plan's Implementation Contract: one pointer to its
+ * development guide when the guide exists, otherwise nothing. The guide is never
+ * parsed, and a missing guide says nothing about the project, whose rules may live
+ * where its agents already read them (CR019).
+ */
+export function projectContractRules(projectPath: string | null): string[] {
+  if (projectPath === null || !existsSync(join(resolve(projectPath), DEVELOPMENT_GUIDE_PATH))) {
+    return [];
+  }
+  return [`Follow the project's development guide: ${DEVELOPMENT_GUIDE_PATH}.`];
+}
+
+/**
+ * Python `_context_summary`.
+ *
+ * Three fixed paths, in Python's order, each reported present or missing. With no
+ * project path the whole block collapses to one line — the shape a journey with no
+ * configured project renders.
+ */
+function contextSummary(projectPath: string | null): string[] {
+  if (projectPath === null) {
+    return ["No project path is configured; Prepare used runtime journey state only."];
+  }
+  const root = resolve(projectPath);
+  return ["README.md", "docs/project/roadmap/index.md", DEVELOPMENT_GUIDE_PATH].map(
+    (relativePath) =>
+      `${relativePath}: ${existsSync(join(root, relativePath)) ? "present" : "missing"}`,
+  );
+}
+
+export interface PrepareOptions {
+  readonly journey: string;
+  readonly method: string;
+  readonly projectPath?: string | null;
+}
+
+/** Python `prepare_lifecycle_item`. */
+export function prepareLifecycleItem(
+  db: WritableDatabase,
+  options: PrepareOptions,
+  deps: CursorWriteDeps,
+): BuilderPrepareReport {
+  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 prepare");
+  if (!existing.activeItem) throw new Error("active item is required before prepare");
+  refuseIfAlreadyComplete("prepare", existing);
+  const event = existing.lastDeliveryEvent;
+  if (event !== null && event !== "pull" && event !== "prepare") {
+    const pending = existing.pendingConfirmation ? `, pending ${existing.pendingConfirmation}` : "";
+    throw new LifecycleRefusal(
+      "prepare",
+      "not_reached",
+      `Prepare follows Pull: ${existing.activeItem} is at ${event}${pending}.`,
+    );
+  }
+
+  const cursor = setDeliveryCursor(
+    db,
+    {
+      journey,
+      method,
+      activeItem: existing.activeItem,
+      activeItemTitle: existing.activeItemTitle,
+      activeItemLevel: existing.activeItemLevel,
+      activeCheckpoint: null,
+      pendingConfirmation: null,
+      lastDeliveryEvent: "prepare",
+      cadenceProfile: existing.cadenceProfile,
+      cadenceLimits: existing.cadenceLimits,
+      navigatorFlowUnit: existing.navigatorFlowUnit,
+      childWorkItems: existing.childWorkItems,
+      aggregateCheckpointStatus: existing.aggregateCheckpointStatus,
+    },
+    deps,
+  );
+
+  const implementable = isImplementableByDefault(existing.activeItemLevel);
+  return {
+    journey,
+    method,
+    activeItem: existing.activeItem,
+    activeItemTitle: existing.activeItemTitle,
+    activeItemLevel: existing.activeItemLevel,
+    implementableByDefault: implementable,
+    granularityDecisionRequired: !implementable,
+    contextSummary: contextSummary(options.projectPath ?? null),
+    storyShapeAssessment: storyShapeAssessment(existing.activeItemLevel),
+    risks: [
+      "Scope may expand during Plan if the item mixes product and technical work.",
+      "Implementation remains blocked until the Plan checkpoint is approved.",
+    ],
+    applicableRules: [
+      "Pull selects active work; Prepare reads terrain.",
+      nextEventRule(existing.activeItemLevel),
+      "No Plan, Implement, Validation, Review, Coherence, or Done work is executed here.",
+    ],
+    cursor,
+    nextEvent: "plan",
+  };
+}
+
+/** Python `render_prepare_report`. */
+export function renderPrepareReport(report: BuilderPrepareReport): string {
+  const body = `${[
+    "Delivery",
+    renderLifecycleRibbon("prepare", report.activeItemLevel),
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    "│        🧭  PREPARE FIELD READING                       │",
+    "│                                                        │",
+    cardText("active item"),
+    cardText(`🟦[${report.activeItem}]`),
+    cardText(`level: ${report.activeItemLevel ?? "unknown"}`),
+    cardText(
+      report.implementableByDefault
+        ? "implementable: yes"
+        : "implementable: requires granularity decision",
+    ),
+    "│                                                        │",
+    cardText("terrain read"),
+    ...cardContextItems(report.contextSummary),
+    "│                                                        │",
+    cardText("story shape"),
+    ...cardWrapped(report.storyShapeAssessment),
+    "│                                                        │",
+    cardText("risks"),
+    ...cardPrefixed(report.risks, "✕"),
+    "│                                                        │",
+    cardText("applicable rules"),
+    ...cardPrefixed(report.applicableRules, "✓"),
+    "│                                                        │",
+    cardText("next event"),
+    cardText(report.granularityDecisionRequired ? "Expand or Plan" : pyTitle(report.nextEvent)),
+    "│                                                        │",
+    cardText("boundary"),
+    cardText("Plan was not created."),
+    cardText("Implementation remains blocked."),
+    "╰────────────────────────────────────────────────────────╯",
+  ].join("\n")}\n`;
+  return wrapAriadSurface("prepare_field_reading", body);
+}

package/ts/src/builder/projectPaths.ts

@@ -0,0 +1,64 @@
+// CR082 with CR009 — how a Builder surface names a place in the journey's project.
+//
+// Paths are resolved absolute inside the runtime, deliberately: `storyPaths`'
+// confinement guard is only sound on absolutes. What a surface PRINTS is another
+// matter. Surfaces are transported verbatim into replies, handoffs, and committed
+// documents, so a path printed as resolved carries the owner's home directory, and a
+// card cuts it into 54-column chunks where the root's length decides, so the same row
+// reads differently on every machine. Every path a card prints therefore goes through
+// `displayPath`, relative to the project, and every message that names a package is
+// built with it where it is raised.
+//
+// One core answers "where is this path in the project", and each caller keeps its own
+// reading of the two answers that are not a plain relative path: the project root
+// itself, and a path outside the project.
+//
+// A relative path names a file only together with its project, so every report of a
+// write also names the project, by its folder, and the journey it was made for, on one
+// row (CR009): a wrong journey, or a journey whose project path names the wrong folder,
+// shows as a wrong name on the card itself.
+
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
+
+/**
+ * The path's relation to the project, in the platform's separators: `""` for the
+ * project root itself, and `null` for a path outside the project.
+ *
+ * Both arguments are resolved first, so an absolute path and a relative one name the
+ * same place when they resolve to it. Outside means `..` itself or `..` followed by a
+ * separator: a project folder may be named `..cache`.
+ */
+export function projectRelative(path: string, projectRoot: string): string | null {
+  const relation = relative(resolve(projectRoot), resolve(path));
+  const outside = relation === ".." || relation.startsWith(`..${sep}`) || isAbsolute(relation);
+  return outside ? null : relation;
+}
+
+/**
+ * A path as a surface prints it: relative to the project, `.` for the project root,
+ * and the path exactly as given when it lies outside the project or there is none.
+ *
+ * Printing the ORIGINAL path in the fallback, not the resolved one, is Python's
+ * `_display_path`, kept: a path outside the project prints as its caller wrote it.
+ */
+export function displayPath(path: string, projectPath: string | null): string {
+  if (projectPath === null) return path;
+  const relation = projectRelative(path, projectPath);
+  if (relation === null) return path;
+  return relation === "" ? "." : relation;
+}
+
+/** The project's folder: the last segment of its path, or the path itself at the root. */
+export function projectFolder(projectRoot: string): string {
+  const resolved = resolve(projectRoot);
+  return basename(resolved) || resolved;
+}
+
+/**
+ * The row a report of a write prints (CR009): where the files went, by the project's
+ * folder, and for which journey. Two checkouts of one repository share a folder name;
+ * the slug on the row tells their journeys apart, and `build load` prints the root.
+ */
+export function targetLine(projectRoot: string, journey: string): string {
+  return `project: ${projectFolder(projectRoot)} · journey: ${journey}`;
+}

package/ts/src/builder/pull.ts

@@ -0,0 +1,356 @@
+// CV22.DS7.US8 plateau 3 — Pull: the Navigator's commitment to an item.
+//
+// Port of `pull_lifecycle_item` and `render_pull_report` from
+// `src/memory/builder/lifecycle.py`.
+//
+// Pull looks like a simple write and is not. Three carry-forward rules decide what
+// survives it, and each one is invisible until it is wrong:
+//
+//   1. **Child work items and aggregate status reset only when the ITEM CHANGED.**
+//      A first Pull (no prior active item) and a re-pull of the same code keep
+//      them; pulling a different code drops them. A port that always resets loses
+//      an expanded Delivery Story's children on a re-pull; one that never resets
+//      carries the previous story's children into the new one, which is how a
+//      Delivery Story ends up reporting siblings that belong to its predecessor.
+//   2. **The generation always advances**, even for a re-pull of the same item.
+//      It is what invalidates a pending authority receipt bound to the old
+//      generation, so "pull the same thing again" is a real state change.
+//   3. **Release intent survives only inside the same Delivery Story.** It is
+//      keyed to the DS ancestor, so pulling a child of the same DS keeps it and
+//      pulling into a different DS clears both fields explicitly.
+//
+// CR113: the card says what happened, at the level that happened, and where the item
+// lives. It was headed DELIVERY STORY ACTIVATED for every level, under a marker
+// naming a Delivery Story; it said Prepare had not run while the same command ran it;
+// it drew a story straight under its CV; and it called any pulled code a roadmap
+// candidate. It now names the level under a marker that names none, claims nothing
+// about Prepare, draws the item's lineage, and says whether the roadmap names the item.
+
+import { join } from "node:path";
+import type { WritableDatabase } from "#db/database.ts";
+import { codePointLength, pyStrip, pyTitle } from "#util/pythonText.ts";
+import { cardClipped, cardText, cardWrapped } from "./card.ts";
+import {
+  ALLOWED_PULL_LEVELS,
+  carriedForward,
+  deliveryStoryCodeForItem,
+  normalizeRequired,
+} from "./cursorTransitions.ts";
+import {
+  type BuilderDeliveryCursor,
+  type CursorWriteDeps,
+  getDeliveryCursor,
+  setDeliveryCursor,
+  setTo,
+} from "./deliveryCursor.ts";
+import { renderLifecycleRibbon } from "./lifecycleRibbon.ts";
+import {
+  inspectPullCandidates,
+  inspectRoadmapSnapshot,
+  type PullCandidate,
+  roadmapPaths,
+} from "./pullCandidates.ts";
+import { linkFreeTitle, matchHeading, parseCandidateStories } from "./roadmapGrammar.ts";
+import { readRoadmapFile } from "./roadmapScan.ts";
+import { resolveRoadmapScope, type ScopeCursor } from "./roadmapScope.ts";
+import { claimedBy, NO_AUTHORED_PACKAGE, NO_PROJECT_PATH, scopeFocus } from "./scopePhrases.ts";
+import { roadmapHeadingDirectories } from "./storyPaths.ts";
+import { wrapAriadSurface } from "./surfaceProtocol.ts";
+
+/** Python `BuilderLifecycleItem`. */
+export interface BuilderLifecycleItem {
+  readonly code: string;
+  readonly title: string;
+  readonly level: string;
+  readonly whyNow: string;
+}
+
+/** Python `BuilderPullReport`. */
+export interface BuilderPullReport {
+  readonly journey: string;
+  readonly method: string;
+  readonly item: BuilderLifecycleItem;
+  readonly cursor: BuilderDeliveryCursor;
+  readonly nextEvent: string;
+}
+
+/**
+ * Python `_normalize_item`.
+ *
+ * Field order is behavior: an empty code is reported before an empty title, and
+ * the level VOCABULARY check runs after all four fields are non-empty, so a blank
+ * level says "must not be empty" rather than listing the allowed values.
+ */
+function normalizeItem(item: BuilderLifecycleItem): BuilderLifecycleItem {
+  const code = normalizeRequired(item.code, "item code");
+  // Link-free from here on, as every roadmap reader delivers a title (CR018).
+  const title = linkFreeTitle(normalizeRequired(item.title, "item title"));
+  const level = normalizeRequired(item.level, "item level");
+  const whyNow = normalizeRequired(item.whyNow, "why now");
+  if (!(ALLOWED_PULL_LEVELS as readonly string[]).includes(level)) {
+    throw new Error(`item level must be one of ${ALLOWED_PULL_LEVELS.join(", ")}`);
+  }
+  return { code, title, level, whyNow };
+}
+
+export interface PullOptions {
+  readonly journey: string;
+  readonly method: string;
+  readonly item: BuilderLifecycleItem;
+}
+
+/** Python `pull_lifecycle_item`. */
+export function pullLifecycleItem(
+  db: WritableDatabase,
+  options: PullOptions,
+  deps: CursorWriteDeps,
+): BuilderPullReport {
+  const journey = normalizeRequired(options.journey, "journey");
+  const method = normalizeRequired(options.method, "method");
+  const item = normalizeItem(options.item);
+
+  const existing = getDeliveryCursor(db, journey);
+  if (existing === null) {
+    throw new Error("delivery cursor is required before pull");
+  }
+
+  const itemChanged = existing.activeItem !== null && existing.activeItem !== item.code;
+  // A flow unit belongs to the Delivery Story it was chosen for (CR117): it survives Pull
+  // only when that Delivery Story is pulled again as the item the cursor already holds.
+  // Any other item starts at the default. Not `itemChanged`, which is false for a cursor
+  // with no item and would let a stale unit through a Delivery Story's first Pull.
+  const keepsFlowUnit = existing.activeItem === item.code && item.level === "delivery_story";
+  const preserveReleaseIntent =
+    existing.releaseIntentDeliveryStory === deliveryStoryCodeForItem(item.code);
+
+  const cursor = setDeliveryCursor(
+    db,
+    {
+      journey,
+      method,
+      activeItem: item.code,
+      activeItemTitle: item.title,
+      activeItemLevel: item.level,
+      activeCheckpoint: null,
+      pendingConfirmation: null,
+      lastDeliveryEvent: "pull",
+      ...carriedForward(existing),
+      navigatorFlowUnit: keepsFlowUnit ? existing.navigatorFlowUnit : null,
+      childWorkItems: itemChanged ? [] : existing.childWorkItems,
+      aggregateCheckpointStatus: itemChanged ? [] : existing.aggregateCheckpointStatus,
+      cursorGeneration: existing.cursorGeneration + 1,
+      // Explicit, not KEEP: Pull is one of the few writes that may CLEAR release
+      // intent, and the sentinel would preserve exactly what must be dropped.
+      releaseIntentDeliveryStory: setTo(
+        preserveReleaseIntent ? existing.releaseIntentDeliveryStory : null,
+      ),
+      releaseIntent: setTo(preserveReleaseIntent ? existing.releaseIntent : null),
+    },
+    deps,
+  );
+
+  return { journey, method, item, cursor, nextEvent: "prepare" };
+}
+
+/**
+ * The title of the CV a pulled item sits under, as the roadmap names it (CR018): the
+ * focus Project Position shows for the same cursor, so the two surfaces cannot
+ * disagree. Python borrowed the head of the item's own title instead. Pull and Ready
+ * both render it, and neither computes it: the caller passes this in.
+ */
+export function placementCvTitle(projectRoot: string | null, cursor: ScopeCursor): string {
+  const items = inspectRoadmapSnapshot(projectRoot, { journey: "", method: "ariad" }).items;
+  return scopeFocus(items, resolveRoadmapScope(projectRoot, cursor))?.title ?? "";
+}
+
+/** A Delivery Story a pulled story sits under, titled by the roadmap. */
+export interface PlacementParent {
+  readonly code: string;
+  readonly title: string;
+}
+
+/** Where a pulled item sits: its CV's title, and its Delivery Story when it is a story. */
+export interface Lineage {
+  readonly cvTitle: string;
+  readonly deliveryStory: PlacementParent | null;
+}
+
+/** The Pull card's placement, and whether the roadmap names the pulled item (CR113). */
+export interface PullPlacement extends Lineage {
+  readonly listed: boolean;
+}
+
+/** The title an authored package's heading gives a code, or why there is none. */
+function packageTitle(
+  projectRoot: string,
+  claims: ReadonlyMap<string, readonly string[]>,
+  code: string,
+): string | null {
+  const directories = claims.get(code) ?? [];
+  if (directories.length > 1) return claimedBy(directories.length);
+  const directory = directories[0];
+  if (directory === undefined) return null;
+  const { roadmapRoot } = roadmapPaths(projectRoot);
+  const content = readRoadmapFile(join(roadmapRoot, directory, "index.md"));
+  const heading = content === null ? null : matchHeading(content);
+  return heading === null ? null : linkFreeTitle(pyStrip(heading.title));
+}
+
+/**
+ * The item's lineage and whether the roadmap names it, from the roadmap as it stands.
+ *
+ * Three readers, each the authority for its fact. The CV's title is the focus Project
+ * Position shows (`placementCvTitle`). A Delivery Story's title is its package's
+ * heading, found by the status-blind heading rule Expand and `resolveStoryDirectory`
+ * share, else the roadmap index's listing of it. The item is named when a package
+ * heading claims it, when its Delivery Story's candidate table lists it, or when it is
+ * a pull candidate. `inspectPullCandidates` alone would not do: it keeps only the
+ * statuses that can be pulled, so a story marked Done, or a row with no package yet,
+ * would read as not in the roadmap.
+ */
+export function pullPlacement(projectRoot: string | null, cursor: ScopeCursor): PullPlacement {
+  const cvTitle = placementCvTitle(projectRoot, cursor);
+  const code = cursor.activeItem ?? "";
+  const cvCode = code.split(".")[0] ?? code;
+  const dsCode = deliveryStoryCodeForItem(code);
+  // A story under a Delivery Story that is not itself the CV row's code.
+  const parentCode = dsCode !== null && dsCode !== code && dsCode !== cvCode ? dsCode : null;
+  if (projectRoot === null) {
+    return {
+      cvTitle,
+      deliveryStory: parentCode === null ? null : { code: parentCode, title: NO_PROJECT_PATH },
+      listed: false,
+    };
+  }
+  const claims = roadmapHeadingDirectories(projectRoot);
+  const candidates = inspectPullCandidates(projectRoot, {
+    journey: "",
+    method: "ariad",
+  }).candidates;
+  const deliveryStory =
+    parentCode === null
+      ? null
+      : {
+          code: parentCode,
+          title:
+            packageTitle(projectRoot, claims, parentCode) ??
+            candidates.find((candidate) => candidate.code === parentCode)?.title ??
+            NO_AUTHORED_PACKAGE,
+        };
+  return {
+    cvTitle,
+    deliveryStory,
+    listed: namedByRoadmap(projectRoot, claims, candidates, code, dsCode),
+  };
+}
+
+/**
+ * Whether the roadmap names `code`, by any of three routes: a package heading claims
+ * it, its Delivery Story's candidate table lists it, or it is a pull candidate. The
+ * candidates are the ones `pullPlacement` already read, so one Pull scans them once
+ * (the handoff review, finding 1).
+ */
+function namedByRoadmap(
+  projectRoot: string,
+  claims: ReadonlyMap<string, readonly string[]>,
+  candidates: readonly PullCandidate[],
+  code: string,
+  dsCode: string | null,
+): boolean {
+  if ((claims.get(code) ?? []).length > 0) return true;
+  const parentDirectories = dsCode === null || dsCode === code ? [] : (claims.get(dsCode) ?? []);
+  if (parentDirectories.length === 1) {
+    const { roadmapRoot } = roadmapPaths(projectRoot);
+    const content = readRoadmapFile(join(roadmapRoot, parentDirectories[0] as string, "index.md"));
+    if (content !== null && parseCandidateStories(content).some((child) => child.code === code)) {
+      return true;
+    }
+  }
+  return candidates.some((candidate) => candidate.code === code);
+}
+
+/** The last segment of a code: the label a tree row carries. */
+function leafOf(code: string): string {
+  const parts = code.split(".");
+  return parts.length > 1 ? (parts.at(-1) ?? "") : code;
+}
+
+/**
+ * The item's lineage as card rows (CR113): the CV, then its Delivery Story when the
+ * item is a story under one, then the item. The colors are the three the Ready card
+ * draws for the three levels. Pull and Ready both draw their tree here, so they
+ * cannot disagree; Ready's is a Delivery Story, one level shorter.
+ */
+export function placementRows(
+  item: { readonly code: string; readonly title: string; readonly level: string },
+  lineage: Lineage,
+): string[] {
+  const cvCode = item.code.split(".")[0] ?? item.code;
+  const glyph = item.level === "delivery_story" ? "🟦" : "🟩";
+  // Whole where the title is read; the tree rows restate it on one line (CR018).
+  const rows = [...cardWrapped(`🟪[${cvCode}] ${lineage.cvTitle}`)];
+  if (lineage.deliveryStory === null) {
+    rows.push(cardClipped(`  └─ ${glyph}[${leafOf(item.code)}] ${item.title}`));
+    return rows;
+  }
+  const parent = lineage.deliveryStory;
+  rows.push(cardClipped(`  └─ 🟦[${leafOf(parent.code)}] ${parent.title}`));
+  rows.push(cardClipped(`     └─ ${glyph}[${leafOf(item.code)}] ${item.title}`));
+  return rows;
+}
+
+/** What the card calls each level it can pull. */
+const ACTIVATED: Readonly<Record<string, string>> = {
+  delivery_story: "DELIVERY STORY",
+  user_story: "USER STORY",
+  technical_story: "TECHNICAL STORY",
+};
+
+/**
+ * The title row, padded to terminal columns like every Builder title literal: 🟪 is
+ * one code point and two columns, so the row is one code point short of the frame
+ * and aligned on screen (see `pullCandidatesRender.ts`). The Delivery Story row keeps
+ * the bytes it always had.
+ */
+function activatedTitleRow(level: string): string {
+  const inner = `        🟪■  ${ACTIVATED[level] ?? "ITEM"} ACTIVATED`;
+  const columns = codePointLength(inner) + 1;
+  return `│${inner}${" ".repeat(Math.max(0, 56 - columns))}│`;
+}
+
+/** Python `render_pull_report`, with the level, the lineage, and a true source (CR113). */
+export function renderPullReport(report: BuilderPullReport, placement: PullPlacement): string {
+  const title = report.item.title;
+  const body = `${[
+    "Delivery",
+    renderLifecycleRibbon("pull", report.item.level),
+    "",
+    "╭────────────────────────────────────────────────────────╮",
+    activatedTitleRow(report.item.level),
+    "│                                                        │",
+    // Whole where the title is read; the tree row below restates it on one line (CR018).
+    ...cardWrapped(title),
+    "│                                                        │",
+    cardText("source"),
+    cardText(placement.listed ? "roadmap candidate" : "not in the roadmap: pulled by its code"),
+    "│                                                        │",
+    cardText("roadmap placement"),
+    ...placementRows(report.item, placement),
+    "│                                                        │",
+    cardText("intent"),
+    ...cardWrapped(report.item.whyNow),
+    "│                                                        │",
+    cardText("commitment"),
+    cardText("pulled into active Delivery Work"),
+    cardText(`active item: ${report.cursor.activeItem ?? "none"}`),
+    "│                                                        │",
+    cardText("next event"),
+    cardText(pyTitle(report.nextEvent)),
+    "│                                                        │",
+    cardText("boundary"),
+    // Prepare's record is its own card, which the command prints next (CR113, D1).
+    cardText("Plan and later lifecycle work were not executed."),
+    "╰────────────────────────────────────────────────────────╯",
+  ].join("\n")}\n`;
+  return wrapAriadSurface("item_activated", body);
+}