mirror-mind 0.0.1 → 0.32.1

package/ts/src/builder/roadmapGrammar.ts

@@ -0,0 +1,300 @@
+// CV22.DS7.US8 plateau 1 — shared parsing primitives for the roadmap grammars.
+//
+// Port of `src/memory/builder/roadmap_grammar.py`. Both the legacy
+// `CV → Epic → Story` grammar and the Delivery Story grammar are parsed with
+// these, and keeping them in one module is what stopped the heading/status
+// regex drift that once made DS-grammar roadmaps unreadable while the CV
+// grammar still worked.
+//
+// Three dialect traps, each of which a literal transcription of the Python
+// patterns would walk into:
+//
+//   1. **`\s` is not `\s`.** In a Python `str` pattern `\s` is `str.isspace()`:
+//      it INCLUDES U+001C–U+001F and U+0085 and EXCLUDES U+FEFF. JavaScript's
+//      `\s` is the opposite on both counts. So these patterns are built from
+//      `PYTHON_WHITESPACE_CLASS`, the set US6 established, rather than `\s`.
+//   2. **`.` diverges on line separators.** Python's `.` (no DOTALL) excludes
+//      only `\n`; JavaScript's excludes `\n`, `\r`, U+2028, and U+2029. A title
+//      containing U+2028 therefore continues in Python and stops in JavaScript.
+//      `[^\n]` restores Python's meaning.
+//   3. **`str.strip()` is not `.trim()`**, same separator-set reason, so cell
+//      trimming goes through `pyStrip`.
+//
+// And one that cost a test failure before it was found: **`re.MULTILINE` is not
+// the `m` flag.** Python's MULTILINE `^`/`$` anchor at `\n` only, while
+// JavaScript's `m` also anchors at `\r`, U+2028, and U+2029. With `m`, a lazy
+// title followed by `$` stops at an embedded U+2028 and silently truncates —
+// which is what the `line_separator` fixture caught. So the anchors are written
+// out as `(?<=^|\n)` and `(?=\n|$)` and the `m` flag is deliberately absent.
+//
+// `re.fullmatch` maps to anchoring the pattern, not to `.test()` on a substring.
+
+import { clipCodePoints } from "#util/clipCodePoints.ts";
+import { PYTHON_WHITESPACE_CLASS, pyStrip } from "#util/pythonText.ts";
+
+const WS = `[${PYTHON_WHITESPACE_CLASS}]`;
+
+/**
+ * `# <code> — <title>`, multiline. Codes may carry dots (`CV2.DS1`), hyphens
+ * (`DS-35`), dotted hyphenated children (`DS-35.US-1`), and a lowercase
+ * sub-story suffix (`CV21.E2.S1b`). The separator is an em dash OR a hyphen.
+ */
+export const HEADING_RE = new RegExp(
+  `(?<=^|\\n)#${WS}+(?<code>[A-Za-z0-9.\\-]+)${WS}+[—-]${WS}+(?<title>[^\\n]+?)${WS}*(?=\\n|$)`,
+  "u",
+);
+
+/** `**Status:** <status>`. Unanchored at the start, exactly as Python's is. */
+export const STATUS_RE = new RegExp(
+  `\\*\\*Status:\\*\\*${WS}*(?<status>[^\\n]+?)${WS}*(?=\\n|$)`,
+  "u",
+);
+
+/** `**Type:** <type>`. Lives beside the patterns it is parsed with. */
+export const TYPE_RE = new RegExp(`\\*\\*Type:\\*\\*${WS}*(?<type>[^\\n]+?)${WS}*(?=\\n|$)`, "u");
+
+/** A whole-cell `[label](target)` link. Anchored, to mean `re.fullmatch`. */
+const MARKDOWN_LINK_RE = /^\[(?<label>[^\]]+)\]\((?<target>[^)]*)\)$/u;
+
+export interface HeadingMatch {
+  code: string;
+  title: string;
+}
+
+/** First `# <code> — <title>` heading in a document, or `null`. */
+export function matchHeading(content: string): HeadingMatch | null {
+  const match = HEADING_RE.exec(content);
+  if (!match?.groups) return null;
+  return { code: match.groups.code, title: match.groups.title };
+}
+
+/** First `**Status:**` value in a document, or `null`. */
+export function matchStatus(content: string): string | null {
+  return STATUS_RE.exec(content)?.groups?.status ?? null;
+}
+
+/** First `**Type:**` value in a document, or `null`. */
+export function matchType(content: string): string | null {
+  return TYPE_RE.exec(content)?.groups?.type ?? null;
+}
+
+/**
+ * Python `is_legacy_path`: true when the path sits under a `legacy/` component
+ * of the roadmap root. Component-wise, not a substring test — a directory named
+ * `non-legacy-notes` is not legacy.
+ *
+ * Python resolves both sides and returns `False` when the path lies outside the
+ * root (`relative_to` raises). Callers here pass components already relative to
+ * the root, so that case is an empty list.
+ */
+export function isLegacyPath(relativeComponents: readonly string[]): boolean {
+  return relativeComponents.includes("legacy");
+}
+
+export interface MarkdownLink {
+  label: string;
+  target: string;
+}
+
+/** Python `parse_markdown_link`: a whole-cell link, or `null`. */
+export function parseMarkdownLink(value: string): MarkdownLink | null {
+  const match = MARKDOWN_LINK_RE.exec(pyStrip(value));
+  if (!match?.groups) return null;
+  return { label: match.groups.label, target: match.groups.target };
+}
+
+/** Python `strip_markdown_link`: the link's label, or the stripped raw value. */
+export function stripMarkdownLink(value: string): string {
+  return parseMarkdownLink(value)?.label ?? pyStrip(value);
+}
+
+/** A code span: a run of backticks up to the next run of the same length. */
+const CODE_SPAN_RE = /(?<!`)(`+)(?!`)[\s\S]*?(?<!`)\1(?!`)/gu;
+
+/** An inline link or image with a label, not escaped. The target may carry a quoted title. */
+const INLINE_LINK_RE = /(?<!\\)!?\[([^\]\n]+)\]\([^)\n]*\)/gu;
+
+/**
+ * A title with every inline Markdown link or image reduced to its label (CR018).
+ *
+ * A relative link is true only in the file it was written in, and Ariad carries a title
+ * into terminal cards, into files at other depths, and into folder names. So a title
+ * enters Ariad this way, from the roadmap and from `--item-title` alike. What
+ * `stripMarkdownLink` does for a cell that is one whole link is a case of this rule;
+ * that function stays for codes.
+ *
+ * A link inside a code span is code and stays as written, as does a link with an empty
+ * label, which has nothing to keep. Reference links (`[label][ref]`) and labels with
+ * nested brackets are left alone.
+ */
+export function linkFreeTitle(title: string): string {
+  let result = "";
+  let last = 0;
+  for (const span of title.matchAll(CODE_SPAN_RE)) {
+    result += title.slice(last, span.index).replace(INLINE_LINK_RE, "$1");
+    result += span[0];
+    last = span.index + span[0].length;
+  }
+  return result + title.slice(last).replace(INLINE_LINK_RE, "$1");
+}
+
+/** The most a status clause takes on a card row; the widest status on this roadmap. */
+export const STATUS_CLAUSE_WIDTH = 24;
+
+/** The separators after which a status line stops being its status (CR103). */
+const STATUS_SEPARATOR_RE = /\s(?:\u2014|\u2013|-|\u00b7)\s|\s\(|[;,.:]\s/u;
+
+/** `**`, `__`, and the backticks of a code span: Markdown a card cannot render. */
+const STATUS_MARKS_RE = /\*\*|__|`/gu;
+
+/**
+ * A status line as the status its author declared: its first clause, Markdown
+ * reduced, bounded to `STATUS_CLAUSE_WIDTH` (CR103).
+ *
+ * Several roadmaps write a package's `**Status:**` line as a running changelog, and
+ * every Builder reader read it whole: the rows printed a hundred card lines of it, and
+ * the classifiers found a status word in its prose. The clause is what a row prints
+ * and what a classifier reads, so the two cannot disagree. It is applied where a status
+ * leaves a reader, so every `PullCandidate`, `RoadmapSnapshotItem`, `AuthoredPackage`,
+ * and `CandidateChild` carries a clause by construction; `matchStatus` still returns the
+ * line, for the reader that wants it.
+ *
+ * In order: `pyStrip`; links and images to their labels, then `**`, `__`, and backticks
+ * out, so a separator inside a link's target cannot cut, a label's words cut like the
+ * author's own, and a `**` that closes after the separator still goes; the cut before the first separator, never at the
+ * start; trailing punctuation off, and an empty clause gives way to the reduced line;
+ * then the clip, by the card's rule.
+ */
+export function statusClause(status: string): string {
+  const reduced = pyStrip(linkFreeTitle(pyStrip(status)).replace(STATUS_MARKS_RE, ""));
+  const cut = reduced.search(STATUS_SEPARATOR_RE);
+  const clause = pyStrip((cut > 0 ? reduced.slice(0, cut) : reduced).replace(/[.:;,]+$/u, ""));
+  return clipCodePoints(clause === "" ? reduced : clause, STATUS_CLAUSE_WIDTH);
+}
+
+/**
+ * The cells of a Markdown table row, each `pyStrip`ped, with GFM's escape honored
+ * (CR107): `\|` is a pipe inside the cell, a code span included, and `\\` is a backslash,
+ * so `\\|` is a backslash and a border. Every other character is itself, as every other
+ * reader leaves it. The row's leading pipes go, and its trailing unescaped ones, as
+ * Python's `strip("|")` took them; an escaped trailing pipe is content.
+ *
+ * Three readers split on every pipe before this: the roadmap index's CV and DS tables,
+ * a Delivery Story's candidate table, and the Done preflight's status tables. A cell
+ * with an escape split in two and shifted every column after it, so Expand recommended
+ * a fragment, the index read a status from the wrong cell, and the preflight refused a
+ * Done row. One reader now, and `tableCell` is its inverse.
+ */
+export function tableRowCells(line: string): string[] {
+  let start = 0;
+  while (start < line.length && line[start] === "|") start += 1;
+  let end = line.length;
+  while (end > start && line[end - 1] === "|" && !escapedAt(line, end - 1)) end -= 1;
+  const cells: string[] = [];
+  let cell = "";
+  for (let at = start; at < end; at += 1) {
+    const char = line[at];
+    const next = line[at + 1];
+    if (char === "\\" && at + 1 < end && (next === "|" || next === "\\")) {
+      cell += next;
+      at += 1;
+      continue;
+    }
+    if (char === "|") {
+      cells.push(pyStrip(cell));
+      cell = "";
+      continue;
+    }
+    cell += char;
+  }
+  cells.push(pyStrip(cell));
+  return cells;
+}
+
+/** Whether the pipe at `index` is escaped: preceded by an odd run of backslashes. */
+function escapedAt(line: string, index: number): boolean {
+  let backslashes = 0;
+  for (let at = index - 1; at >= 0 && line[at] === "\\"; at -= 1) backslashes += 1;
+  return backslashes % 2 === 1;
+}
+
+/**
+ * `text` as a table cell: every backslash doubled, then every pipe escaped, so
+ * `tableRowCells` gives the text back exactly (CR107). The Delivery Story scaffold writes
+ * a title into two cells through it; nothing else Ariad writes is a table cell.
+ */
+export function tableCell(text: string): string {
+  return text.replace(/\\/gu, "\\\\").replace(/\|/gu, "\\|");
+}
+
+/** Python `_CandidateChild`. Its `status` is the cell's clause (CR103). */
+export interface CandidateChild {
+  readonly code: string;
+  readonly title: string;
+  readonly level: string;
+  readonly status: string;
+}
+
+const REQUIRED_COLUMNS = ["code", "story", "type", "status"] as const;
+
+/**
+ * Python `_parse_candidate_stories`: a Delivery Story's `## Candidate Stories` table,
+ * header-driven. Expand reads its children with it, and Pull asks it whether a
+ * Delivery Story names a story (CR113), so the two read the table by one rule.
+ *
+ * Line-by-line rather than block-by-block, and the details matter:
+ *
+ *   * a non-table line BREAKS the scan once a header was found, but is SKIPPED
+ *     before — so the first canonical table wins and nothing after it is read;
+ *   * `line.strip("|")` removes every leading and trailing pipe, not one;
+ *   * duplicate header names keep the LAST index, because Python builds the map
+ *     with a dict comprehension over `enumerate`;
+ *   * a row shorter than the widest required column is skipped, not an error,
+ *     which is how a ragged authored table degrades instead of blocking.
+ */
+export function parseCandidateStories(content: string): CandidateChild[] {
+  const children: CandidateChild[] = [];
+  let columns: Map<string, number> | null = null;
+
+  for (const rawLine of content.split("\n")) {
+    const line = pyStrip(rawLine);
+    if (!line.startsWith("|")) {
+      if (columns !== null) break;
+      continue;
+    }
+    const cells = tableRowCells(line);
+
+    if (columns === null) {
+      // `cell.lower()` — ASCII header names in practice; Python's `str.lower()`
+      // and JavaScript's `toLowerCase()` differ only on characters no canonical
+      // header uses (`İ`, `ẞ`), and a divergence there fails closed by not
+      // matching the required set.
+      const lowered = cells.map((cell) => cell.toLowerCase());
+      if (REQUIRED_COLUMNS.every((name) => lowered.includes(name))) {
+        columns = new Map();
+        lowered.forEach((name, index) => {
+          columns?.set(name, index);
+        });
+      }
+      continue;
+    }
+
+    if (line.startsWith("|---")) continue;
+    if (cells.every((cell) => cell === "")) continue;
+    if (cells.every((cell) => [...cell].every((character) => character === "-"))) continue;
+
+    const widest = Math.max(...[...columns.values()]);
+    if (cells.length <= widest) continue;
+
+    const code = stripMarkdownLink(cells[columns.get("code") ?? 0] ?? "");
+    if (!code) continue;
+    const typeText = (cells[columns.get("type") ?? 0] ?? "").toLowerCase();
+    children.push({
+      code,
+      title: linkFreeTitle(cells[columns.get("story") ?? 0] ?? ""),
+      level: typeText.includes("technical") ? "technical_story" : "user_story",
+      status: statusClause(cells[columns.get("status") ?? 0] ?? ""),
+    });
+  }
+  return children;
+}

package/ts/src/builder/roadmapScan.ts

@@ -0,0 +1,97 @@
+// CV22.DS7.US8 plateau 1 — the one filesystem scan every roadmap reader shares.
+//
+// Python has three call sites that all do `sorted(roadmap_root.rglob("index.md"))`
+// and then skip `legacy/`: `pull_candidates.inspect_pull_candidates`,
+// `roadmap_position.resolve_roadmap_position`, and
+// `story_paths._group_roadmap_headings`. They are one function here for the same
+// reason `roadmap_grammar.py` exists in Python — three copies of a scan is three
+// chances for the ordering to drift. CR002 deleted the position reader: a
+// journey's position now comes from its cursor (`roadmapScope.ts`), not from the
+// first file whose status reads "Active".
+//
+// The ordering is the whole point. `sorted()` over `Path` objects compares
+// COMPONENT LISTS, so `a/b` precedes `a-x/c`; a JavaScript `sort()` over joined
+// paths puts `a-x/c` first because `-` (0x2D) sorts before `/` (0x2F). That
+// order decides which candidate `_recommend` returns and the order of the
+// rendered Backlog, so a naive sort changes what the Navigator is told to pull
+// next. Measured: Python 3.10 and 3.12 agree with each other, and on this
+// project's real 352-file tree the two orders happen to coincide today — which
+// is why the fixture stages the collision deliberately rather than trusting an
+// accident of directory naming.
+
+import { type Dirent, readdirSync, readFileSync } from "node:fs";
+import { relative, sep } from "node:path";
+import { comparePathComponents } from "#util/pythonText.ts";
+import { isLegacyPath } from "./roadmapGrammar.ts";
+
+export interface RoadmapFile {
+  /** Path components relative to the roadmap root, ending in `index.md`. */
+  components: string[];
+  /** POSIX path relative to the roadmap root. */
+  relativePath: string;
+  /** Absolute path on disk. */
+  absolutePath: string;
+}
+
+export interface RoadmapScanOptions {
+  /**
+   * Keep `legacy/` in the result. Default `false`, which is what the three
+   * grammar call sites need.
+   *
+   * It is an OPTION rather than a second function because Python has a fourth
+   * call site that does the same walk and does NOT skip the archive:
+   * `delivery_story_roadmap_closure.inspect_authored_closure`, whose status scan
+   * reads every `index.md` under the roadmap. So an archived table row for a known
+   * code blocks a Delivery Story's Done. Reusing this scan with its default would
+   * let TypeScript close a Delivery Story that Python refuses — the exact defect
+   * shape the plateau-5 panel stopped, and `authored_closure_reads_legacy_rows`
+   * fails a port that does it.
+   */
+  readonly includeLegacy?: boolean;
+}
+
+/**
+ * Python `sorted(roadmap_root.rglob("index.md"))`, minus `legacy/` unless asked.
+ *
+ * A missing or unreadable root yields an empty list, matching Python's
+ * `is_dir()` guard at every call site.
+ */
+export function scanRoadmapIndexFiles(
+  roadmapRoot: string,
+  options: RoadmapScanOptions = {},
+): RoadmapFile[] {
+  let entries: Dirent<string>[];
+  try {
+    entries = readdirSync(roadmapRoot, { recursive: true, withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const found: string[][] = [];
+  for (const entry of entries) {
+    if (entry.name !== "index.md") continue;
+    if (!entry.isFile()) continue;
+    const parents = relative(roadmapRoot, entry.parentPath).split(sep).filter(Boolean);
+    found.push([...parents, entry.name]);
+  }
+  found.sort(comparePathComponents);
+  return found
+    .filter((components) => options.includeLegacy === true || !isLegacyPath(components))
+    .map((components) => ({
+      components,
+      relativePath: components.join("/"),
+      absolutePath: [roadmapRoot, ...components].join(sep),
+    }));
+}
+
+/**
+ * Python's `try: path.read_text(encoding="utf-8") except OSError: continue`.
+ * An unreadable file is skipped, not fatal — a permission error in one package
+ * must not empty the whole roadmap.
+ */
+export function readRoadmapFile(absolutePath: string): string | null {
+  try {
+    return readFileSync(absolutePath, "utf8");
+  } catch {
+    return null;
+  }
+}

package/ts/src/builder/roadmapScope.ts

@@ -0,0 +1,210 @@
+// CR002 — the journey's roadmap scope, derived from its delivery cursor.
+//
+// Every Builder surface that answers "where are we" or "what next" reads this
+// scope instead of the whole project. Before CR002 two readers did: one returned
+// the first `index.md` whose status contained "Active", the other recommended
+// across every candidate in the tree. Neither knew which journey was asking, so a
+// project holding several journeys' work told each of them the same answer, and
+// usually a wrong one.
+//
+// The only roadmap fact a journey owns is the active item in its delivery cursor.
+// Pull is the one cursor writer that sets it and `sync-cursor` the one that clears
+// it — every other writer carries it forward — so "unscoped" always means no item
+// has been pulled since the cursor was last synchronized.
+//
+// Identity is the authored heading code, never a folder. A package can live under
+// any directory a human chose (the rule `storyPaths.ts` states), so the CV is the
+// active item's code up to the first `.`, its package is found by its heading, and
+// membership is strict descent by code. Strict, because the CV is the position,
+// not a candidate: `recommend()` falls back to its first candidate at ANY level,
+// so a CV still marked Active with nothing left under it would otherwise be
+// recommended as its own next pull.
+
+import { pyStrip } from "#util/pythonText.ts";
+import {
+  type PullCandidate,
+  type PullCandidatesReport,
+  recommend,
+  roadmapPaths,
+} from "./pullCandidates.ts";
+import { linkFreeTitle, matchHeading, matchStatus, statusClause } from "./roadmapGrammar.ts";
+import { readRoadmapFile } from "./roadmapScan.ts";
+import { roadmapHeadingDirectories } from "./storyPaths.ts";
+
+export type UnscopedReason = "no_cursor" | "no_active_item";
+
+/** An authored roadmap package, as its own `index.md` describes it. */
+export interface AuthoredPackage {
+  readonly code: string;
+  readonly title: string;
+  /** The clause of the package's `**Status:**` line (CR103), or `""` when it has none. */
+  readonly status: string;
+  /** POSIX, relative to the project root, ending in `index.md`. */
+  readonly path: string;
+}
+
+/** Where the journey stands, as far as the authored roadmap can say. */
+export type ScopePosition =
+  /** The CV's own package. */
+  | { readonly kind: "cv_package"; readonly package: AuthoredPackage }
+  /** The CV has no package; the active item's own stands in for it. */
+  | { readonly kind: "item_package"; readonly package: AuthoredPackage }
+  /** Neither the CV nor the active item has an authored package. */
+  | { readonly kind: "no_package" }
+  /** Two or more packages claim `code` (the CV's, or the item's when the CV has none). */
+  | { readonly kind: "ambiguous"; readonly code: string; readonly paths: readonly string[] }
+  /** The journey has no project path, so there is no roadmap to read. */
+  | { readonly kind: "no_project" };
+
+export type RoadmapScope =
+  | { readonly kind: "unscoped"; readonly reason: UnscopedReason }
+  | {
+      readonly kind: "active_item";
+      readonly activeItem: string;
+      readonly cvCode: string;
+      readonly position: ScopePosition;
+    };
+
+/** The one cursor field the scope reads; every cursor view in the builder has it. */
+export interface ScopeCursor {
+  readonly activeItem: string | null;
+}
+
+/** The candidate list a journey sees, and the one recommendation it may get. */
+export interface ScopedPullCandidates {
+  readonly journey: string;
+  readonly method: string;
+  readonly scope: RoadmapScope;
+  /** Unscoped: every candidate. Scoped: the CV's strict descendants, minus the active item. */
+  readonly shown: readonly PullCandidate[];
+  /** Scoped: candidates outside the CV, the CV itself not counted. Unscoped: 0. */
+  readonly outsideCount: number;
+  /** Scoped: `recommend(shown)`. Unscoped: always `null`. */
+  readonly recommended: PullCandidate | null;
+}
+
+/** The CV a roadmap code belongs to: everything before the first `.`. */
+export function cvCodeOf(code: string): string {
+  return code.split(".", 1)[0] ?? code;
+}
+
+/** Strict descent: `CV2.DS1` is inside `CV2`; `CV2` and `CV20.DS1` are not. */
+export function isInsideCv(code: string, cvCode: string): boolean {
+  return code.startsWith(`${cvCode}.`);
+}
+
+/** The code one level up: everything before the last `.`. A CV has no parent. */
+export function parentCodeOf(code: string): string | null {
+  const cut = code.lastIndexOf(".");
+  return cut === -1 ? null : code.slice(0, cut);
+}
+
+/**
+ * The active item's siblings: the other items with the same parent, in the order
+ * given. Its ancestors, its cousins, and its parent's own siblings never qualify,
+ * and exact comparison keeps `CV1.DS1` from claiming `CV1.DS10`'s children (CR019).
+ */
+export function siblingsOf<T extends { readonly code: string }>(
+  items: readonly T[],
+  activeItem: string,
+): T[] {
+  const parent = parentCodeOf(activeItem);
+  if (parent === null) return [];
+  return items.filter((item) => item.code !== activeItem && parentCodeOf(item.code) === parent);
+}
+
+/** The scope a journey's cursor implies. Never throws for a roadmap defect. */
+export function resolveRoadmapScope(
+  projectRoot: string | null,
+  cursor: ScopeCursor | null,
+): RoadmapScope {
+  if (cursor === null) return { kind: "unscoped", reason: "no_cursor" };
+  const activeItem = cursor.activeItem;
+  if (!activeItem) return { kind: "unscoped", reason: "no_active_item" };
+  const cvCode = cvCodeOf(activeItem);
+  return {
+    kind: "active_item",
+    activeItem,
+    cvCode,
+    position: resolvePosition(projectRoot, activeItem, cvCode),
+  };
+}
+
+function resolvePosition(
+  projectRoot: string | null,
+  activeItem: string,
+  cvCode: string,
+): ScopePosition {
+  if (projectRoot === null) return { kind: "no_project" };
+  const claims = roadmapHeadingDirectories(projectRoot);
+  const cv = claimFor(projectRoot, claims, cvCode);
+  if (cv.kind === "one") return { kind: "cv_package", package: cv.package };
+  if (cv.kind === "many") return { kind: "ambiguous", code: cvCode, paths: cv.paths };
+  if (activeItem === cvCode) return { kind: "no_package" };
+  const item = claimFor(projectRoot, claims, activeItem);
+  if (item.kind === "one") return { kind: "item_package", package: item.package };
+  if (item.kind === "many") return { kind: "ambiguous", code: activeItem, paths: item.paths };
+  return { kind: "no_package" };
+}
+
+type Claim =
+  | { readonly kind: "none" }
+  | { readonly kind: "one"; readonly package: AuthoredPackage }
+  | { readonly kind: "many"; readonly paths: readonly string[] };
+
+function claimFor(
+  projectRoot: string,
+  claims: ReadonlyMap<string, readonly string[]>,
+  code: string,
+): Claim {
+  const directories = claims.get(code) ?? [];
+  if (directories.length > 1) return { kind: "many", paths: directories.map(indexPath) };
+  const only = directories[0];
+  if (only === undefined) return { kind: "none" };
+  const authored = readPackage(projectRoot, only);
+  return authored === null ? { kind: "none" } : { kind: "one", package: authored };
+}
+
+/** A roadmap-relative package directory as the project-relative path of its `index.md`. */
+function indexPath(directory: string): string {
+  return directory ? `docs/project/roadmap/${directory}/index.md` : "docs/project/roadmap/index.md";
+}
+
+function readPackage(projectRoot: string, directory: string): AuthoredPackage | null {
+  const { roadmapRoot } = roadmapPaths(projectRoot);
+  const file = directory ? `${roadmapRoot}/${directory}/index.md` : `${roadmapRoot}/index.md`;
+  const content = readRoadmapFile(file);
+  if (content === null) return null;
+  const heading = matchHeading(content);
+  if (heading === null) return null;
+  const status = matchStatus(content);
+  return {
+    code: pyStrip(heading.code),
+    title: linkFreeTitle(pyStrip(heading.title)),
+    status: status === null ? "" : statusClause(status),
+    path: indexPath(directory),
+  };
+}
+
+/**
+ * The candidate list scoped to the journey. Unscoped, every candidate is shown and
+ * nothing is recommended: there is no journey position to recommend from, and a
+ * project-wide ranking is exactly the answer CR002 removed.
+ */
+export function scopePullCandidates(
+  report: PullCandidatesReport,
+  scope: RoadmapScope,
+): ScopedPullCandidates {
+  const { journey, method, candidates } = report;
+  if (scope.kind === "unscoped") {
+    return { journey, method, scope, shown: candidates, outsideCount: 0, recommended: null };
+  }
+  const { cvCode, activeItem } = scope;
+  const shown = candidates.filter(
+    (candidate) => isInsideCv(candidate.code, cvCode) && candidate.code !== activeItem,
+  );
+  const outsideCount = candidates.filter(
+    (candidate) => candidate.code !== cvCode && !isInsideCv(candidate.code, cvCode),
+  ).length;
+  return { journey, method, scope, shown, outsideCount, recommended: recommend(shown) };
+}