mirror-mind 0.0.1 → 0.32.1

package/ts/src/builder/pullCandidates.ts

@@ -0,0 +1,463 @@
+// CV22.DS7.US8 plateau 1 — roadmap snapshot and pull candidates.
+//
+// Port of `src/memory/builder/pull_candidates.py` (the inspection half; the
+// three rendered surfaces live in `pullCandidatesRender.ts`).
+//
+// Three snapshot grammars with precedence, and they are not interchangeable:
+//
+//   * `cvTableItems` reads `| Code | Capability Value | Status |` and STOPS at
+//     the first non-empty, non-table line;
+//   * `dsTableItems` reads `| Code | Delivery Story | Status |` and merely
+//     leaves table mode at such a line, so it ACCUMULATES across
+//     `## Chapter N —` sections;
+//   * `cvHeadingItems` reads `## CV<n>: <title>` followed by `**Status:**`.
+//
+// The first grammar that yields anything wins, so a file carrying a CV table
+// and a DS table returns only the CV rows. A port that merges them, or that
+// gives the DS table the CV table's termination rule, reads a different roadmap.
+
+import { PYTHON_WHITESPACE_CLASS, pySplitLines, pyStrip } from "#util/pythonText.ts";
+import {
+  linkFreeTitle,
+  matchHeading,
+  matchStatus,
+  matchType,
+  statusClause,
+  stripMarkdownLink,
+  tableRowCells,
+} from "./roadmapGrammar.ts";
+import { readRoadmapFile, scanRoadmapIndexFiles } from "./roadmapScan.ts";
+
+// Every line walk below is Python `content.splitlines()` via `pySplitLines`, not
+// `split("\n")`: Python knows ELEVEN line boundaries (including \v, \f, U+001C
+// \u2028, and \u2029), and a roadmap file carrying a form feed would otherwise
+// parse as one long line here and as two lines there. Likewise every `.strip()`
+// is `pyStrip`, because Python's whitespace set includes U+001C-U+001F and
+// U+0085 and excludes U+FEFF — the exact opposite of `String.prototype.trim()`
+// on both counts.
+
+/** Python `_CANDIDATE_STATUSES`: substring markers, not an enum. */
+const CANDIDATE_STATUSES = ["Planned", "Active", "Blocked", "Candidate"] as const;
+
+const CV_TABLE_HEADER = "| Code | Capability Value | Status |";
+const DS_TABLE_HEADER = "| Code | Delivery Story | Status |";
+
+/** Python `_TOP_LEVEL_DS_RE`: a bare `DS-35`, anchored. */
+const TOP_LEVEL_DS_RE = /^DS-\d+$/u;
+
+// These three are Python `re.match` against an ALREADY-STRIPPED single line, so
+// they anchor at the start and end of that line. `\s` is spelled out as Python's
+// set for the same reason as in `roadmapGrammar.ts`, and `.` as `[^\n]`.
+const WS = `[${PYTHON_WHITESPACE_CLASS}]`;
+
+/** Python's `^##\s+(CV\d+):\s+(.+?)\s*$`. */
+const CV_HEADING_RE = new RegExp(`^##${WS}+(CV\\d+):${WS}+([^\\n]+?)${WS}*$`, "u");
+
+/** Python's `^\*\*Status:\*\*\s*(.+?)\s*$`. */
+const LINE_STATUS_RE = new RegExp(`^\\*\\*Status:\\*\\*${WS}*([^\\n]+?)${WS}*$`, "u");
+
+/** Python's `^-\s+(DS\d+)\s+(.+?)\.?$`. */
+const DS_BULLET_RE = new RegExp(`^-${WS}+(DS\\d+)${WS}+([^\\n]+?)\\.?$`, "u");
+
+export interface RoadmapSnapshotItem {
+  code: string;
+  title: string;
+  /** The status cell's clause, never the cell (CR103). */
+  status: string;
+}
+
+export interface RoadmapSnapshotReport {
+  journey: string;
+  method: string;
+  items: RoadmapSnapshotItem[];
+  source: string | null;
+}
+
+export type CandidateLevel = "cv" | "delivery_story" | "user_story" | "technical_story";
+
+export interface PullCandidate {
+  code: string;
+  title: string;
+  level: string;
+  /** The status line's clause, never the line (CR103). */
+  status: string;
+  /** POSIX path relative to the project root, as Python's `relative_to(root)`. */
+  path: string;
+}
+
+/**
+ * The raw project scan. It carries no recommendation: since CR002 a
+ * recommendation exists only for a journey's scope (`scopePullCandidates` in
+ * `roadmapScope.ts`), never for the project as a whole.
+ */
+export interface PullCandidatesReport {
+  journey: string;
+  method: string;
+  candidates: PullCandidate[];
+}
+
+export interface ProjectPaths {
+  /** Absolute project root. */
+  root: string;
+  /** Absolute `<root>/docs/project/roadmap`. */
+  roadmapRoot: string;
+}
+
+/** `<root>/docs/project/roadmap`, the only roadmap location Python looks in. */
+export function roadmapPaths(root: string): ProjectPaths {
+  return { root, roadmapRoot: `${root}/docs/project/roadmap` };
+}
+
+function hasCandidateStatus(status: string): boolean {
+  return CANDIDATE_STATUSES.some((marker) => status.includes(marker));
+}
+
+/**
+ * Python `inspect_roadmap_snapshot`: the compact snapshot from
+ * `docs/project/roadmap/index.md` alone — not the whole tree.
+ *
+ * `source` is the project-relative path of that one file, or `null` when the
+ * project path is absent, the file is missing, or it cannot be read.
+ */
+export function inspectRoadmapSnapshot(
+  root: string | null,
+  options: { journey: string; method: string },
+): RoadmapSnapshotReport {
+  const empty: RoadmapSnapshotReport = {
+    journey: options.journey,
+    method: options.method,
+    items: [],
+    source: null,
+  };
+  if (root === null) return empty;
+  const indexPath = `${root}/docs/project/roadmap/index.md`;
+  const content = readRoadmapFile(indexPath);
+  if (content === null) return empty;
+  return {
+    journey: options.journey,
+    method: options.method,
+    items: snapshotItemsFromContent(content),
+    source: "docs/project/roadmap/index.md",
+  };
+}
+
+export function snapshotItemsFromContent(content: string): RoadmapSnapshotItem[] {
+  const cv = cvTableItems(content);
+  if (cv.length > 0) return cv;
+  const ds = dsTableItems(content);
+  if (ds.length > 0) return ds;
+  return cvHeadingItems(content);
+}
+
+/**
+ * Python `_cv_table_items`. Note the termination: any non-empty line that does
+ * not start with `|` BREAKS the scan, so only the first CV table is read.
+ */
+function cvTableItems(content: string): RoadmapSnapshotItem[] {
+  const items: RoadmapSnapshotItem[] = [];
+  let inTable = false;
+  for (const rawLine of pySplitLines(content)) {
+    const line = pyStrip(rawLine);
+    if (line === CV_TABLE_HEADER) {
+      inTable = true;
+      continue;
+    }
+    if (inTable && line.startsWith("|---")) continue;
+    if (inTable && line.startsWith("|")) {
+      const parts = tableRowCells(line);
+      if (parts.length >= 3) {
+        items.push({
+          code: stripMarkdownLink(parts[0] ?? ""),
+          title: linkFreeTitle(parts[1] ?? ""),
+          status: statusClause(parts[2] ?? ""),
+        });
+      }
+      continue;
+    }
+    if (inTable && line) break;
+  }
+  return items;
+}
+
+/**
+ * Python `_ds_table_items`. Same shape as the CV table with one crucial
+ * difference: a non-table line only leaves table mode (`in_table = False`), so
+ * a later `| Code | Delivery Story | Status |` header resumes and the rows
+ * ACCUMULATE across chapters.
+ */
+function dsTableItems(content: string): RoadmapSnapshotItem[] {
+  const items: RoadmapSnapshotItem[] = [];
+  let inTable = false;
+  for (const rawLine of pySplitLines(content)) {
+    const line = pyStrip(rawLine);
+    if (line === DS_TABLE_HEADER) {
+      inTable = true;
+      continue;
+    }
+    if (inTable && line.startsWith("|---")) continue;
+    if (inTable && line.startsWith("|")) {
+      const parts = tableRowCells(line);
+      if (parts.length >= 3) {
+        items.push({
+          code: stripMarkdownLink(parts[0] ?? ""),
+          title: linkFreeTitle(parts[1] ?? ""),
+          status: statusClause(parts[2] ?? ""),
+        });
+      }
+      continue;
+    }
+    if (inTable) inTable = false;
+  }
+  return items;
+}
+
+/**
+ * Python `_cv_heading_items`: `## CV<n>: <title>` then the next `**Status:**`.
+ * The pairing is consumed — `current_cv` is cleared after a status matches — so
+ * a second status line without an intervening heading is ignored.
+ */
+function cvHeadingItems(content: string): RoadmapSnapshotItem[] {
+  const items: RoadmapSnapshotItem[] = [];
+  let currentCv: { code: string; title: string } | null = null;
+  for (const rawLine of pySplitLines(content)) {
+    const line = pyStrip(rawLine);
+    const cvMatch = CV_HEADING_RE.exec(line);
+    if (cvMatch) {
+      currentCv = { code: cvMatch[1] ?? "", title: linkFreeTitle(pyStrip(cvMatch[2] ?? "")) };
+      continue;
+    }
+    const statusMatch = LINE_STATUS_RE.exec(line);
+    if (statusMatch && currentCv) {
+      items.push({
+        code: currentCv.code,
+        title: currentCv.title,
+        status: statusClause(statusMatch[1] ?? ""),
+      });
+      currentCv = null;
+    }
+  }
+  return items;
+}
+
+/**
+ * Python `inspect_pull_candidates`: scan every non-legacy `index.md`, collect
+ * the package's own candidate plus any `Candidate Delivery Stories:` bullets,
+ * then drop everything a `done.md` covers.
+ */
+export function inspectPullCandidates(
+  root: string | null,
+  options: { journey: string; method: string },
+): PullCandidatesReport {
+  if (root === null) {
+    return { journey: options.journey, method: options.method, candidates: [] };
+  }
+  const { roadmapRoot } = roadmapPaths(root);
+  const files = scanRoadmapIndexFiles(roadmapRoot);
+
+  // Python's path is relative to the PROJECT root, not the roadmap root.
+  const projectPrefix = "docs/project/roadmap/";
+  const raw: PullCandidate[] = [];
+  const contents = new Map<string, string>();
+  for (const file of files) {
+    const content = readRoadmapFile(file.absolutePath);
+    if (content === null) continue;
+    contents.set(file.relativePath, content);
+    const projectRelative = `${projectPrefix}${file.relativePath}`;
+    const own = candidateFromIndexContent(projectRelative, content);
+    if (own !== null) raw.push(own);
+    raw.push(...candidateDeliveryStoriesFromContent(projectRelative, content));
+  }
+
+  const candidates = raw.filter(
+    (candidate) => !candidateHasDoneArtifact(root, candidate, files, contents),
+  );
+  return { journey: options.journey, method: options.method, candidates };
+}
+
+function candidateFromIndexContent(
+  projectRelativePath: string,
+  content: string,
+): PullCandidate | null {
+  const heading = matchHeading(content);
+  const status = matchStatus(content);
+  if (!heading || status === null) return null;
+  const statusText = statusClause(status);
+  if (!hasCandidateStatus(statusText)) return null;
+  const code = pyStrip(heading.code);
+  return {
+    code,
+    title: linkFreeTitle(pyStrip(heading.title)),
+    level: levelFor(code, content),
+    status: statusText,
+    path: projectRelativePath,
+  };
+}
+
+/**
+ * Python `_candidate_delivery_stories_from_content`: the `Candidate Delivery
+ * Stories:` bullet list under a `## CV<n>:` heading.
+ *
+ * Each Delivery Story carries its own title. Python prefixed the CV's as
+ * `"<CV title> / <DS title>"`, and five readers cut every title at a `/` to undo
+ * it, so any title with a slash of its own reached the Navigator as a fragment.
+ * CR018 removed the prefix and the cuts together; a surface that needs the CV's
+ * title reads the CV's own row.
+ */
+function candidateDeliveryStoriesFromContent(
+  projectRelativePath: string,
+  content: string,
+): PullCandidate[] {
+  const candidates: PullCandidate[] = [];
+  let currentCv: string | null = null;
+  let currentStatus: string | null = null;
+  let inCandidateDeliveryStories = false;
+
+  for (const rawLine of pySplitLines(content)) {
+    const line = pyStrip(rawLine);
+    const cvMatch = CV_HEADING_RE.exec(line);
+    if (cvMatch) {
+      currentCv = cvMatch[1] ?? null;
+      currentStatus = null;
+      inCandidateDeliveryStories = false;
+      continue;
+    }
+    const statusMatch = LINE_STATUS_RE.exec(line);
+    if (statusMatch && currentCv) {
+      currentStatus = statusClause(statusMatch[1] ?? "");
+      continue;
+    }
+    if (line === "Candidate Delivery Stories:") {
+      inCandidateDeliveryStories = true;
+      continue;
+    }
+    if (inCandidateDeliveryStories && line.startsWith("- ") && currentCv) {
+      const dsMatch = DS_BULLET_RE.exec(line);
+      if (!dsMatch) continue;
+      const status = currentStatus || "Candidate";
+      if (!hasCandidateStatus(status)) continue;
+      candidates.push({
+        code: `${currentCv}.${dsMatch[1]}`,
+        title: linkFreeTitle(pyStrip(dsMatch[2] ?? "")),
+        level: "delivery_story",
+        status,
+        path: projectRelativePath,
+      });
+      continue;
+    }
+    if (inCandidateDeliveryStories && line && !line.startsWith("- ")) {
+      inCandidateDeliveryStories = false;
+    }
+  }
+  return candidates;
+}
+
+/**
+ * Python `_candidate_has_done_artifact`. Two-step, and the second step is the
+ * one a port drops: when the candidate's own file does not claim its code (a
+ * bullet-derived candidate, whose path is the CV index), Python searches the
+ * WHOLE tree for a package whose heading claims that code, then checks for a
+ * `done.md` at that package or any ancestor up to the roadmap root.
+ *
+ * So a child package with no `done.md` of its own is still filtered out when an
+ * ancestor has one.
+ */
+function candidateHasDoneArtifact(
+  root: string,
+  candidate: PullCandidate,
+  files: readonly { components: string[]; relativePath: string; absolutePath: string }[],
+  contents: ReadonlyMap<string, string>,
+): boolean {
+  const projectPrefix = "docs/project/roadmap/";
+  const candidateRelative = candidate.path.startsWith(projectPrefix)
+    ? candidate.path.slice(projectPrefix.length)
+    : null;
+
+  let searchRelatives: string[] = [];
+  if (candidateRelative !== null) {
+    const ownContent = contents.get(candidateRelative);
+    const ownHeading = ownContent ? matchHeading(ownContent) : null;
+    const ownCode = ownHeading ? pyStrip(ownHeading.code) : undefined;
+    if (ownCode === candidate.code) searchRelatives = [candidateRelative];
+  }
+  if (searchRelatives.length === 0) {
+    searchRelatives = files
+      .filter((file) => {
+        const heading = matchHeading(contents.get(file.relativePath) ?? "");
+        return heading !== null && pyStrip(heading.code) === candidate.code;
+      })
+      .map((file) => file.relativePath);
+  }
+
+  for (const relativePath of searchRelatives) {
+    const packageComponents = relativePath.split("/").slice(0, -1);
+    if (hasDoneArtifact(root, packageComponents)) return true;
+  }
+  return false;
+}
+
+/** Python `_has_done_artifact`: walk up to (and including) the roadmap root. */
+function hasDoneArtifact(root: string, packageComponents: readonly string[]): boolean {
+  const { roadmapRoot } = roadmapPaths(root);
+  for (let depth = packageComponents.length; depth >= 0; depth -= 1) {
+    const current = [roadmapRoot, ...packageComponents.slice(0, depth)].join("/");
+    if (readRoadmapFile(`${current}/done.md`) !== null) return true;
+  }
+  return false;
+}
+
+/**
+ * Python `_level_for`: `**Type:**` decides by SUBSTRING, so "Technical Story"
+ * and "a technical spike" both mean `technical_story`. Falls back to the code
+ * shape.
+ */
+export function levelFor(code: string, content: string): string {
+  const type = matchType(content);
+  if (type !== null) {
+    const storyType = pyStrip(type).toLowerCase();
+    if (storyType.includes("technical")) return "technical_story";
+    if (storyType.includes("user")) return "user_story";
+  }
+  if (code.includes(".DS") || TOP_LEVEL_DS_RE.test(code)) return "delivery_story";
+  return "cv";
+}
+
+/**
+ * Python `_recommend`: status is the OUTER loop and level the inner one, so a
+ * Planned delivery story beats a Candidate user story. Falls back to the first
+ * candidate in scan order — which is why the scan order matters.
+ */
+export function recommend(candidates: readonly PullCandidate[]): PullCandidate | null {
+  for (const preferredStatus of ["Planned", "Candidate", "Active", "Blocked"]) {
+    for (const preferredLevel of ["user_story", "technical_story", "delivery_story"]) {
+      for (const candidate of candidates) {
+        if (candidate.level === preferredLevel && candidate.status.includes(preferredStatus)) {
+          return candidate;
+        }
+      }
+    }
+  }
+  return candidates[0] ?? null;
+}
+
+/**
+ * Python `_status_marker`. Order matters: Active is tested before Candidate. Given a
+ * clause (CR103), so its fallback prints at most `○ ` and `STATUS_CLAUSE_WIDTH`, and a
+ * Blocked CV in focus keeps its title on the snapshot's focus row.
+ */
+export function statusMarker(status: string): string {
+  if (status.includes("Active") || status.includes("In Progress")) return "◉ active";
+  if (status.includes("Candidate")) return "◉ candidate";
+  if (status.includes("Planned")) return "○ planned";
+  if (status.includes("Done")) return "✓ done";
+  return `○ ${status.toLowerCase()}`;
+}
+
+/** Python `_format_candidate`, given a candidate whose status is its clause (CR103). */
+export function formatCandidate(candidate: PullCandidate): string {
+  return `${candidate.code} — ${candidate.title} [${candidate.level}] ${candidate.status} (${candidate.path})`;
+}
+
+/** Python `_candidate_lines`. */
+export function candidateLines(candidates: readonly PullCandidate[]): string[] {
+  return candidates.map(formatCandidate);
+}

package/ts/src/builder/pullCandidatesRender.ts

@@ -0,0 +1,238 @@
+// CV22.DS7.US8 plateau 1 — the three roadmap-inspection surfaces.
+//
+// Port of the renderers in `src/memory/builder/pull_candidates.py`:
+// `PROJECT POSITION`, `ROADMAP SNAPSHOT`, and `PULL CANDIDATES`. All three are
+// `transport=verbatim`, so what matters is bytes, not layout intent.
+//
+// The hardcoded frame lines in Python are RAGGED, measured in code points of
+// their inner width:
+//
+//   ╭…╮ / ╰…╯ and the blank rows   56   (what `cardText` also produces)
+//   `🧭  PROJECT POSITION`         54   (two short)
+//   `🟪■  PULL CANDIDATES`         55   (one short)
+//
+// That is not a defect to fix here. The author padded them by eye against a
+// terminal, where an astral-plane glyph occupies two columns but one code point,
+// so the literals are visually aligned and numerically inconsistent. A port that
+// normalizes them to 56 produces a prettier card and fails parity. They are
+// copied verbatim and the golden grades them. Two more, the empty `roadmap field`
+// and `Backlog` rows, left with CR002: an unscoped snapshot now states the
+// scope in `cardLine`'s own width instead.
+//
+// CR002: "where are we" and "what next" come from the journey's scoped view
+// (`roadmapScope.ts`), never from the whole project. Unscoped, a surface names no
+// focus and no recommendation, labels its list project-wide, and gives the literal
+// Pull command; the words are `scopePhrases.ts`'s.
+//
+// CR103: every status these surfaces print or mark is a clause, read once by the
+// roadmap readers. The focus row and the progress line mark it; the candidate rows
+// print it. A Blocked CV in focus once printed its whole status on the right of the
+// focus row and pushed the border off the card.
+
+import { cardClipped, cardLine, cardPrefixed, cardText, cardWrapped } from "./card.ts";
+import {
+  candidateLines,
+  formatCandidate,
+  type PullCandidate,
+  type RoadmapSnapshotItem,
+  type RoadmapSnapshotReport,
+  statusMarker,
+} from "./pullCandidates.ts";
+import type { ScopedPullCandidates } from "./roadmapScope.ts";
+import {
+  candidateListHeader,
+  NO_ITEM_PULLED_YET,
+  noRecommendationLines,
+  outsideCountLines,
+  scopeFocus,
+} from "./scopePhrases.ts";
+import { wrapAriadSurface } from "./surfaceProtocol.ts";
+
+const FRAME_TOP = "╭────────────────────────────────────────────────────────╮";
+const FRAME_BOTTOM = "╰────────────────────────────────────────────────────────╯";
+const FRAME_BLANK = "│                                                        │";
+
+/** Python `_format_project_recommendation`, for a recommendation that exists. */
+function formatProjectRecommendation(candidate: PullCandidate): string {
+  return `🟦[${candidate.code}] ${candidate.title} — recommended next pull`;
+}
+
+/**
+ * Python `_project_focus_lines`, minus its `available candidates: none` line:
+ * "What looks next?" now says what is left in the scope, so the focus does not
+ * repeat it. The progress line strips the marker glyphs from `statusMarker`'s
+ * output with three sequential replaces, so a status whose text itself contains
+ * `◉ ` would lose it too. A focus with no status (a stated placeholder) has no
+ * progress to show.
+ */
+function projectFocusLines(focus: RoadmapSnapshotItem | null): string[] {
+  if (focus === null) return [cardText(NO_ITEM_PULLED_YET)];
+  const lines = cardWrapped(`🟪[${focus.code}] ${focus.title}`);
+  if (focus.status) {
+    const marker = statusMarker(focus.status);
+    const progress = marker.replace("◉ ", "").replace("○ ", "").replace("✓ ", "");
+    lines.push(...cardWrapped(`progress: ${progress}`));
+  }
+  return lines;
+}
+
+/** The scoped candidate list: its header, the candidates, and what it leaves out. */
+function candidateListLines(view: ScopedPullCandidates): string[] {
+  return [
+    cardText(candidateListHeader(view.scope)),
+    ...cardPrefixed(candidateLines(view.shown), "-"),
+    ...outsideCountLines(view).flatMap(cardWrapped),
+  ];
+}
+
+/** The recommendation, formatted by the surface; or what stands in its place. */
+function nextMoveLines(
+  view: ScopedPullCandidates,
+  format: (candidate: PullCandidate) => string,
+): string[] {
+  if (view.recommended !== null) return cardWrapped(format(view.recommended));
+  return noRecommendationLines(view).flatMap(cardWrapped);
+}
+
+/** Python `render_project_position_report`, over the journey's scoped view. */
+export function renderProjectPositionReport(
+  report: RoadmapSnapshotReport,
+  options: { view: ScopedPullCandidates; justMoved?: string | null },
+): string {
+  const { view } = options;
+  const justMoved = options.justMoved ?? null;
+  const focus = scopeFocus(report.items, view.scope);
+  const lines: string[] = [
+    "Roadmap",
+    "",
+    FRAME_TOP,
+    "│        🧭  PROJECT POSITION                           │",
+    FRAME_BLANK,
+    cardText("Where are we now?"),
+    ...projectFocusLines(focus),
+    FRAME_BLANK,
+  ];
+  if (justMoved) {
+    lines.push(cardText("What just moved?"), ...cardWrapped(justMoved), FRAME_BLANK);
+  }
+  lines.push(
+    cardText("What looks next?"),
+    ...nextMoveLines(view, formatProjectRecommendation),
+    FRAME_BLANK,
+    ...candidateListLines(view),
+    FRAME_BLANK,
+    ...cardWrapped("Choose a pull when ready."),
+    FRAME_BOTTOM,
+  );
+  return wrapAriadSurface("project_position", `${lines.join("\n")}\n`);
+}
+
+/**
+ * Python `render_roadmap_snapshot_report`.
+ *
+ * Since CR002 the focus is the journey's CV and the `current` row is the scoped
+ * recommendation: one question, where Python asked two. Python chose `current` by
+ * running `_recommend` over only the focus CV's OWN delivery candidates
+ * (`code.startswith(f"{focus.code}.")`), a different question from the
+ * report-level recommendation — so the two rows can
+ * name different stories, and do whenever the recommended pull belongs to
+ * another CV.
+ */
+export function renderRoadmapSnapshotReport(
+  report: RoadmapSnapshotReport,
+  options: { view: ScopedPullCandidates },
+): string {
+  const { view } = options;
+  const focus = scopeFocus(report.items, view.scope);
+  const result = view.shown.length > 0 ? "ready to pull" : "no pull candidates";
+  const lines: string[] = [
+    "ROADMAP SNAPSHOT",
+    "Delivery field overview",
+    "",
+    "view                         overview",
+    `result of roadmap-snapshot      ${result}`,
+    "",
+    FRAME_TOP,
+  ];
+
+  if (focus === null) {
+    lines.push(cardLine("roadmap field", NO_ITEM_PULLED_YET));
+  } else {
+    lines.push(
+      // The value row says the CV's title whole, so the focus row may cut it (CR018).
+      cardLine(
+        `🟪[${focus.code}]  ${focus.title}`,
+        focus.status ? statusMarker(focus.status) : "",
+        {
+          clip: true,
+        },
+      ),
+      ...cardWrapped(`value: ${focus.title}`),
+      FRAME_BLANK,
+    );
+    const current = view.recommended;
+    if (current !== null) {
+      const codeTail = current.code.split(".").pop() ?? current.code;
+      lines.push(
+        cardLine(`   └─ 🟦[${codeTail}] ${current.title}`, "◉ current", { clip: true }),
+        cardText("      progress: not started"),
+        FRAME_BLANK,
+      );
+    }
+    lines.push(cardText("      Backlog"));
+    if (view.shown.length > 0) {
+      for (const candidate of view.shown) {
+        // Pull Candidates, rendered with this surface, lists each title whole (CR018).
+        lines.push(cardClipped(`      ○ 🟦[${candidate.code}] ${candidate.title}`));
+      }
+    } else {
+      lines.push(cardText("      none"));
+    }
+    lines.push(
+      FRAME_BLANK,
+      cardText("      Recently promoted from Exploration"),
+      cardText("      none"),
+      FRAME_BLANK,
+      cardText("      Active constraints"),
+      cardText("      ✕ do not start candidates automatically"),
+      cardText("      ✓ Navigator explicitly chooses Pull"),
+    );
+  }
+
+  lines.push(
+    FRAME_BOTTOM,
+    "",
+    "source",
+    report.source ?? "none",
+    "",
+    "boundary",
+    "Roadmap was inspected only. No item was pulled. No lifecycle work was executed.",
+  );
+  return wrapAriadSurface("roadmap_snapshot", `${lines.join("\n")}\n`);
+}
+
+/** Python `render_pull_candidates_report`, over the journey's scoped view. */
+export function renderPullCandidatesReport(view: ScopedPullCandidates): string {
+  const lines: string[] = [
+    "Delivery",
+    "",
+    FRAME_TOP,
+    "│        🟪■  PULL CANDIDATES                            │",
+    FRAME_BLANK,
+    cardText("journey"),
+    cardText(view.journey),
+    FRAME_BLANK,
+    cardText("method"),
+    cardText(view.method),
+    FRAME_BLANK,
+    ...candidateListLines(view),
+    FRAME_BLANK,
+    cardText("recommended pull"),
+    ...nextMoveLines(view, formatCandidate),
+    FRAME_BLANK,
+    cardText("boundary"),
+    ...cardWrapped("No item was pulled. No lifecycle work was executed."),
+    FRAME_BOTTOM,
+  ];
+  return wrapAriadSurface("pull_candidates", `${lines.join("\n")}\n`);
+}