@printpractical/cruze 0.0.1

package/src/domain/land/bookkeeping.ts

@@ -0,0 +1,54 @@
+import { removeRow, upsertRow } from "../edits/managed_tables.ts";
+import { updateProgress } from "../edits/progress_block.ts";
+import { parseMarkdown } from "../markdown.ts";
+import { PATHS } from "../project/layout.ts";
+import { readChangesTable } from "../project/plan_parts.ts";
+import { readProgress } from "../project/progress.ts";
+import type { ProjectView } from "../project/project_view.ts";
+import type { WorkItem } from "../project/work_items.ts";
+
+export interface Bookkeeping {
+  /** Whether this land finishes the work: a standalone change, or a feature's last change. */
+  finished: boolean;
+  /** The folder to move into the archive when finished. */
+  archive?: { from: string; to: string };
+  release: string;
+}
+
+/** Records the land in progress blocks, the roadmap status and, when a feature finishes, the feature map. */
+export function applyBookkeeping(view: ProjectView, change: WorkItem, source: WorkItem, landed: string, files: Map<string, string>): Bookkeeping {
+  const text = (path: string): string | undefined => files.get(path) ?? view.snapshot.get(path);
+  files.set(change.path, updateProgress(text(change.path) ?? "", (progress) => (progress.landed = landed)));
+
+  let finished = true;
+  if (source !== change) {
+    const featureText = updateProgress(text(source.path) ?? "", (progress) => progress.changes.set(change.folderName, "landed"));
+    files.set(source.path, featureText);
+    const states = readProgress(parseMarkdown(featureText)).changes;
+    finished = readChangesTable(source.doc).every((row) => states.get(row.change) === "landed");
+  }
+
+  const release = releaseName(text(PATHS.roadmap));
+  const slug = typeof source.doc.frontmatter?.["roadmap"] === "string" ? source.doc.frontmatter["roadmap"] : undefined;
+  const roadmap = text(PATHS.roadmap);
+  if (slug !== undefined && roadmap !== undefined && roadmap.includes("## Status")) {
+    files.set(PATHS.roadmap, upsertRow(roadmap, "Status", [slug, source.folderName, finished ? "landed" : "building"]));
+  }
+  const vision = text(PATHS.vision);
+  if (finished && source.kind === "feature" && slug !== undefined && vision !== undefined && vision.includes("### Implemented")) {
+    const { text: withoutFuture, removed } = removeRow(vision, "Future", slug);
+    const summary = removed?.[1] ?? String(source.doc.frontmatter?.["title"] ?? slug);
+    files.set(PATHS.vision, upsertRow(withoutFuture, "Implemented", [slug, release, summary]));
+  }
+
+  const result: Bookkeeping = { finished, release };
+  if (finished) result.archive = { from: source.folder, to: `${PATHS.archiveDir}/${source.folderName}` };
+  return result;
+}
+
+/** The release in progress: the roadmap's `## Release` line up to its colon. */
+export function releaseName(roadmap: string | undefined): string {
+  if (roadmap === undefined) return "unreleased";
+  const line = roadmap.split("## Release")[1]?.split("\n").find((l) => l.trim() !== "");
+  return line?.split(":")[0]?.trim() || "unreleased";
+}

package/src/domain/land/merge_plan.ts

@@ -0,0 +1,132 @@
+import { sectionForKind } from "../architecture_sections.ts";
+import { CruzeError } from "../cruze_error.ts";
+import { setStatus } from "../edits/status_lines.ts";
+import { headingElements, statusOf, type Element } from "../elements.ts";
+import { elementHash } from "../hashing.ts";
+import { STATUS_KINDS, kindOf, scopeOf } from "../ids.ts";
+import { findSection, parseMarkdown } from "../markdown.ts";
+import { readDelta, type DeltaEntry } from "../project/deltas.ts";
+import { PATHS, specPath } from "../project/layout.ts";
+import { readScope } from "../project/plan_parts.ts";
+import type { ProjectView } from "../project/project_view.ts";
+import type { WorkItem } from "../project/work_items.ts";
+import { REMOVED_MARK, capabilityKey } from "../validation/delta_rules.ts";
+import { appendBlock, relevel, removeElement, replaceElement } from "./text_ops.ts";
+
+export interface MergePlan {
+  /** New text of every living document the merge changes. */
+  files: Map<string, string>;
+  /** The work's merge record after this land: element ID to its merged hash. */
+  merged: Record<string, string>;
+  mergedIds: string[];
+  built: string[];
+  removed: string[];
+}
+
+/**
+ * Merges a change's work into the living docs. The first change of a feature to land merges
+ * the whole delta; elements it doesn't build arrive as planned, and later changes flip what
+ * they build to built. Text is replaced only when nobody else changed it since this work merged it.
+ */
+export function planMerge(view: ProjectView, change: WorkItem, source: WorkItem): MergePlan {
+  const scope = readScope(change.doc);
+  const inScope = new Set([...(scope?.delivers ?? []), ...(scope?.builds ?? [])]);
+  const delta = readDelta(source.doc);
+  const merged = { ...(view.approvals.get(source.folder)?.merged ?? {}) };
+  const files = new Map<string, string>();
+  const text = (path: string): string => files.get(path) ?? view.snapshot.get(path) ?? "";
+  const plan: MergePlan = { files, merged, mergedIds: [], built: [], removed: [] };
+
+  for (const op of delta.capabilities) {
+    const key = capabilityKey(op.capability);
+    if (merged[key] !== undefined || view.snapshot.has(specPath(op.capability))) continue;
+    const body = source.doc.lines.slice(op.start + 1, op.end).join("\n").trim();
+    files.set(specPath(op.capability), `# ${op.title}\n\n${body}\n`);
+    merged[key] = "created";
+  }
+
+  for (const entry of delta.entries) {
+    const { id } = entry.element;
+    const path = entry.section === "spec" ? specPath(scopeOf(id) ?? "") : PATHS.architecture;
+    if (entry.element.op === "REMOVED") {
+      if (scope?.removes.includes(id) === true) {
+        files.set(path, removeElement(text(path), id));
+        merged[id] = REMOVED_MARK;
+        plan.removed.push(id);
+      }
+      continue;
+    }
+    mergeEntry(view, source, entry, path, text, files, merged, plan);
+    for (const target of [entry.element, ...entry.scenarios].filter((e) => STATUS_KINDS.includes(e.kind))) {
+      files.set(path, setStatus(text(path), target.id, statusAfterMerge(view, source, target, inScope)));
+      if (inScope.has(target.id)) plan.built.push(target.id);
+    }
+  }
+
+  for (const id of [...inScope].filter((id) => !delta.ids.has(id) && STATUS_KINDS.includes(kindOf(id)))) {
+    const living = view.living.elements.get(id);
+    if (living === undefined) continue;
+    files.set(living.path, setStatus(text(living.path), id, "built"));
+    plan.built.push(id);
+  }
+  verifyMerged(source, delta.entries, text, plan);
+  return plan;
+}
+
+function mergeEntry(
+  view: ProjectView,
+  source: WorkItem,
+  entry: DeltaEntry,
+  path: string,
+  text: (path: string) => string,
+  files: Map<string, string>,
+  merged: Record<string, string>,
+  plan: MergePlan,
+): void {
+  const { id } = entry.element;
+  const block = relevel(source.doc, entry.element.start, entry.element.end, entry.section === "spec" ? 2 : 3);
+  const deltaHash = elementHash(source.doc, entry.element);
+  const doc = parseMarkdown(text(path));
+  const living = headingElements(doc).find((e) => e.id === id);
+  const previous = merged[id];
+  if (living !== undefined) {
+    const livingHash = elementHash(doc, living);
+    if (previous !== undefined && previous !== REMOVED_MARK && livingHash !== previous) {
+      throw new CruzeError("merge-conflict", `${id} in ${path} changed since ${source.ref} merged it; rethink before landing`);
+    }
+    if (livingHash !== deltaHash) {
+      files.set(path, replaceElement(text(path), id, block));
+      plan.mergedIds.push(id);
+    }
+  } else {
+    if (previous !== undefined && previous !== REMOVED_MARK) {
+      throw new CruzeError("merge-conflict", `${id} was removed from ${path} after ${source.ref} merged it; rethink before landing`);
+    }
+    const section = entry.section === "spec" ? undefined : sectionForKind(entry.element.kind);
+    if (section !== undefined && findSection(doc, section) === null) throw new CruzeError("merge-conflict", `${path} has no "## ${section}" section for ${id}`);
+    files.set(path, appendBlock(text(path), block, section));
+    plan.mergedIds.push(id);
+  }
+  merged[id] = deltaHash;
+  for (const scenario of entry.scenarios) merged[scenario.id] = elementHash(source.doc, scenario);
+}
+
+/** Built when this change builds it, or when it was built and its text is unchanged; planned otherwise. */
+function statusAfterMerge(view: ProjectView, source: WorkItem, target: Element, inScope: Set<string>): "planned" | "built" {
+  if (inScope.has(target.id)) return "built";
+  const before = view.living.elements.get(target.id);
+  if (before === undefined || statusOf(before.doc, before.element) !== "built") return "planned";
+  return elementHash(before.doc, before.element) === elementHash(source.doc, target) ? "built" : "planned";
+}
+
+/** After merging, every merged element must hash exactly as it did in the delta. */
+function verifyMerged(source: WorkItem, entries: DeltaEntry[], text: (path: string) => string, plan: MergePlan): void {
+  for (const entry of entries.filter((e) => plan.mergedIds.includes(e.element.id))) {
+    const path = entry.section === "spec" ? specPath(scopeOf(entry.element.id) ?? "") : PATHS.architecture;
+    const doc = parseMarkdown(text(path));
+    const living = headingElements(doc).find((e) => e.id === entry.element.id);
+    if (living === undefined || elementHash(doc, living) !== elementHash(source.doc, entry.element)) {
+      throw new Error(`merge check failed: ${entry.element.id} in ${path} does not match the delta`);
+    }
+  }
+}

package/src/domain/land/text_ops.ts

@@ -0,0 +1,66 @@
+import { headingElements, isStatusLine } from "../elements.ts";
+import { parseMarkdown, type MarkdownDoc } from "../markdown.ts";
+
+/** Line-level edits land makes to living documents. Every function takes and returns whole text. */
+
+/**
+ * A delta block ready for a living document: headings shifted so the element's own heading
+ * sits at `level`, the operation prefix dropped, status lines removed, trailing blanks trimmed.
+ */
+export function relevel(doc: MarkdownDoc, start: number, end: number, level: number): string[] {
+  const own = /^(#{1,6}) /.exec(doc.lines[start] ?? "")?.[1]?.length ?? level;
+  const shift = level - own;
+  const out: string[] = [];
+  for (let i = start; i < end; i++) {
+    let line = doc.lines[i] ?? "";
+    if (!doc.inFence[i]) {
+      if (isStatusLine(line)) continue;
+      const heading = /^(#{1,6}) (.*)$/.exec(line);
+      if (heading?.[1] !== undefined && heading[2] !== undefined) {
+        const text = i === start ? heading[2].replace(/^(ADDED|MODIFIED|REMOVED) /, "") : heading[2];
+        line = `${"#".repeat(heading[1].length + shift)} ${text}`;
+      }
+    }
+    out.push(line);
+  }
+  while (out.length > 0 && out[out.length - 1]?.trim() === "") out.pop();
+  return out;
+}
+
+/** Replaces an element's whole block, keeping one blank line before whatever follows. */
+export function replaceElement(text: string, id: string, block: string[]): string {
+  const doc = parseMarkdown(text);
+  const element = headingElements(doc).find((e) => e.id === id);
+  if (element === undefined) throw new Error(`${id} is not in the document`);
+  const lines = [...doc.lines];
+  const follows = element.end < lines.length;
+  lines.splice(element.start, element.end - element.start, ...block, ...(follows ? [""] : []));
+  return lines.join("\n");
+}
+
+export function removeElement(text: string, id: string): string {
+  const doc = parseMarkdown(text);
+  const element = headingElements(doc).find((e) => e.id === id);
+  if (element === undefined) return text;
+  const lines = [...doc.lines];
+  lines.splice(element.start, element.end - element.start);
+  return lines.join("\n");
+}
+
+/** Appends a block at the end of a `##` section, or at the end of the document when none is named. */
+export function appendBlock(text: string, block: string[], section?: string): string {
+  const doc = parseMarkdown(text);
+  const lines = [...doc.lines];
+  let at = lines.length;
+  if (section !== undefined) {
+    const heading = doc.headings.find((h) => h.level === 2 && h.text === section);
+    if (heading === undefined) throw new Error(`the document has no "## ${section}" section`);
+    at = doc.headings.find((h) => h.line > heading.line && h.level <= 2)?.line ?? lines.length;
+  }
+  let insertAt = at;
+  while (insertAt > 0 && lines[insertAt - 1]?.trim() === "") insertAt--;
+  const trailing = at < lines.length ? [""] : [];
+  lines.splice(insertAt, at - insertAt, "", ...block, ...trailing);
+  const joined = lines.join("\n");
+  return joined.endsWith("\n") ? joined : `${joined}\n`;
+}

package/src/domain/markdown.ts

@@ -0,0 +1,79 @@
+import { parse as parseYaml } from "yaml";
+
+/** A Markdown document split into lines, with the structure Cruze relies on. */
+export interface MarkdownDoc {
+  lines: string[];
+  frontmatter: Record<string, unknown> | null;
+  /** First line after the frontmatter. */
+  bodyStart: number;
+  headings: Heading[];
+  /** True for lines inside a fenced code block, fences included. */
+  inFence: boolean[];
+  /** True for lines inside a managed block, markers included. */
+  inManaged: boolean[];
+}
+
+export interface Heading {
+  level: number;
+  text: string;
+  line: number;
+}
+
+export const MANAGED_OPEN = "<!-- cruze:managed -->";
+export const MANAGED_CLOSE = "<!-- /cruze:managed -->";
+
+export function parseMarkdown(text: string): MarkdownDoc {
+  const lines = text.replace(/\r\n/g, "\n").split("\n");
+  const { frontmatter, bodyStart } = readFrontmatter(lines);
+  const inFence: boolean[] = [];
+  const inManaged: boolean[] = [];
+  const headings: Heading[] = [];
+  let fence: string | null = null;
+  let managed = false;
+
+  lines.forEach((line, index) => {
+    const fenceMatch = /^(```|~~~)/.exec(line.trimStart());
+    if (fence === null && fenceMatch?.[1] !== undefined && index >= bodyStart) {
+      fence = fenceMatch[1];
+      inFence.push(true);
+    } else if (fence !== null) {
+      inFence.push(true);
+      if (line.trimStart().startsWith(fence)) fence = null;
+    } else {
+      inFence.push(false);
+    }
+
+    const trimmed = line.trim();
+    if (!inFence[index] && trimmed === MANAGED_OPEN) managed = true;
+    inManaged.push(managed);
+    if (!inFence[index] && trimmed === MANAGED_CLOSE) managed = false;
+
+    const heading = /^(#{1,6}) (.+?)\s*$/.exec(line);
+    if (heading?.[1] !== undefined && heading[2] !== undefined && !inFence[index] && index >= bodyStart) {
+      headings.push({ level: heading[1].length, text: heading[2], line: index });
+    }
+  });
+  return { lines, frontmatter, bodyStart, headings, inFence, inManaged };
+}
+
+/** The line range [start, end) of a heading's section: up to the next heading at the same or a higher level. */
+export function sectionEnd(doc: MarkdownDoc, heading: Heading): number {
+  const next = doc.headings.find((h) => h.line > heading.line && h.level <= heading.level);
+  return next === undefined ? doc.lines.length : next.line;
+}
+
+/** The body lines of the first `##` section with this title, or null when absent. */
+export function findSection(doc: MarkdownDoc, title: string, level = 2): { heading: Heading; start: number; end: number } | null {
+  const heading = doc.headings.find((h) => h.level === level && h.text === title);
+  if (heading === undefined) return null;
+  return { heading, start: heading.line + 1, end: sectionEnd(doc, heading) };
+}
+
+function readFrontmatter(lines: string[]): { frontmatter: Record<string, unknown> | null; bodyStart: number } {
+  if (lines[0] !== "---") return { frontmatter: null, bodyStart: 0 };
+  const end = lines.indexOf("---", 1);
+  if (end === -1) return { frontmatter: null, bodyStart: 0 };
+  const parsed: unknown = parseYaml(lines.slice(1, end).join("\n"));
+  const frontmatter = parsed !== null && typeof parsed === "object" ? (parsed as Record<string, unknown>) : {};
+  return { frontmatter, bodyStart: end + 1 };
+}

package/src/domain/markdown_tables.ts

@@ -0,0 +1,34 @@
+/** Pipe tables: header cells and body rows, each row with its line number. */
+export interface Table {
+  header: string[];
+  rows: Array<{ cells: string[]; line: number }>;
+}
+
+/** Tables found in lines [from, to), skipping fenced code. */
+export function tablesIn(lines: string[], inFence: boolean[], from: number, to: number): Table[] {
+  const tables: Table[] = [];
+  let current: Table | null = null;
+  for (let i = from; i < to; i++) {
+    const line = lines[i] ?? "";
+    const isRow = !inFence[i] && /^\s*\|.*\|\s*$/.test(line);
+    if (!isRow) {
+      current = null;
+      continue;
+    }
+    const cells = splitRow(line);
+    if (current === null) {
+      current = { header: cells, rows: [] };
+      tables.push(current);
+    } else if (cells.every((cell) => /^:?-{3,}:?$/.test(cell))) {
+      continue;
+    } else {
+      current.rows.push({ cells, line: i });
+    }
+  }
+  return tables;
+}
+
+export function splitRow(line: string): string[] {
+  const inner = line.trim().replace(/^\|/, "").replace(/\|$/, "");
+  return inner.split("|").map((cell) => cell.trim());
+}

package/src/domain/project/artifact_ref.ts

@@ -0,0 +1,42 @@
+import { CruzeError } from "../cruze_error.ts";
+import { PATHS } from "./layout.ts";
+import type { ProjectView } from "./project_view.ts";
+import { findWorkItem, type WorkItem } from "./work_items.ts";
+
+const NAMED: Record<string, string> = { vision: PATHS.vision, architecture: PATHS.architecture, roadmap: PATHS.roadmap };
+
+/**
+ * Resolves what a person or skill names on the command line: `vision`, `architecture`,
+ * `roadmap`, a work item ref such as `2026-09-25-open-console/01-local-serial`, the same ref
+ * without its date (`open-console/local-serial`) when that names one active item, or a path.
+ */
+export function resolveArtifact(view: ProjectView, ref: string): { path: string; item?: WorkItem } {
+  const named = NAMED[ref];
+  if (named !== undefined) {
+    if (!view.snapshot.has(named)) throw new CruzeError("not-found", `${named} does not exist yet`);
+    return { path: named };
+  }
+  const item = findWorkItem(view.items, ref.replace(/\/$/, "")) ?? bySlug(view.items, ref.replace(/\/$/, ""));
+  if (item !== undefined) return { path: item.path, item };
+  if (view.snapshot.has(ref)) return { path: ref };
+  throw new CruzeError("not-found", `nothing called "${ref}"; use vision, architecture, roadmap, a feature or change ID, or a path`);
+}
+
+/** An active item named by its slug, without the date or the change number. */
+function bySlug(items: WorkItem[], ref: string): WorkItem | undefined {
+  const [head = "", change] = ref.split("/");
+  const undated = (name: string): string => name.replace(/^\d{4}-\d{2}-\d{2}-/, "");
+  const matches = items.filter((i) => !i.archived && i.kind !== "change" && undated(i.folderName) === head);
+  if (matches.length > 1) throw new CruzeError("ambiguous", `"${head}" names ${matches.map((m) => m.ref).join(" and ")}; use the full ID`);
+  const base = matches[0];
+  if (base === undefined || change === undefined) return base;
+  return items.find((i) => i.featureRef === base.ref && (i.folderName === change || i.folderName.replace(/^\d\d-/, "") === change));
+}
+
+/** Resolves a change: a feature's change or a standalone change, never archived. */
+export function resolveChange(view: ProjectView, ref: string): WorkItem {
+  const { item } = resolveArtifact(view, ref);
+  if (item === undefined || item.kind === "feature") throw new CruzeError("not-a-change", `"${ref}" is not a change`);
+  if (item.archived) throw new CruzeError("archived", `${item.ref} has already landed`);
+  return item;
+}

package/src/domain/project/deltas.ts

@@ -0,0 +1,49 @@
+import { capabilityOps, headingElements, type CapabilityOp, type Element } from "../elements.ts";
+import { findSection, type MarkdownDoc } from "../markdown.ts";
+
+/** One delta operation on a living element, with its nested scenarios when it is a requirement. */
+export interface DeltaEntry {
+  element: Element;
+  section: "spec" | "architecture";
+  /** Scenario elements nested under a requirement operation. */
+  scenarios: Element[];
+}
+
+export interface Delta {
+  entries: DeltaEntry[];
+  capabilities: CapabilityOp[];
+  /** Every ID a delta defines or changes, including nested scenarios. */
+  ids: Set<string>;
+}
+
+export function readDelta(doc: MarkdownDoc): Delta {
+  const entries: DeltaEntry[] = [];
+  const capabilities: CapabilityOp[] = [];
+  for (const [title, section] of [["Spec delta", "spec"], ["Architecture delta", "architecture"]] as const) {
+    const range = findSection(doc, title);
+    if (range === null) continue;
+    capabilities.push(...capabilityOps(doc, range.start, range.end));
+    const elements = headingElements(doc, range.start, range.end);
+    for (const element of elements.filter((e) => e.op !== undefined)) {
+      const scenarios = elements.filter((e) => e.op === undefined && e.start > element.start && e.start < element.end);
+      entries.push({ element, section, scenarios });
+    }
+  }
+  const ids = new Set(entries.flatMap((entry) => [entry.element.id, ...entry.scenarios.map((s) => s.id)]));
+  return { entries, capabilities, ids };
+}
+
+/** Scenario elements that sit under no requirement operation: always a format error. */
+export function orphanDeltaElements(doc: MarkdownDoc): Element[] {
+  const orphans: Element[] = [];
+  for (const title of ["Spec delta", "Architecture delta"]) {
+    const range = findSection(doc, title);
+    if (range === null) continue;
+    const elements = headingElements(doc, range.start, range.end);
+    const ops = elements.filter((e) => e.op !== undefined);
+    for (const element of elements.filter((e) => e.op === undefined)) {
+      if (!ops.some((op) => element.start > op.start && element.start < op.end)) orphans.push(element);
+    }
+  }
+  return orphans;
+}

package/src/domain/project/layout.ts

@@ -0,0 +1,40 @@
+/** Where Cruze documents live in a project, and the snapshot of them the domain works on. */
+
+/** Project files by path, relative to the project root, with forward slashes. */
+export type Snapshot = ReadonlyMap<string, string>;
+
+export const PATHS = {
+  vision: "docs/vision.md",
+  glossary: "docs/glossary.md",
+  architecture: "docs/architecture.md",
+  roadmap: "docs/roadmap.md",
+  adrDir: "docs/adr",
+  specsDir: "docs/specs",
+  config: ".cruze/config.yaml",
+  featuresDir: ".cruze/features",
+  changesDir: ".cruze/changes",
+  archiveDir: ".cruze/archive",
+  notesDir: ".cruze/notes",
+  projectApprovals: ".cruze/approvals.json",
+  projectJournal: ".cruze/journal.jsonl",
+} as const;
+
+/** Directories whose files make up the snapshot. */
+export const SNAPSHOT_ROOTS = ["docs", ".cruze"] as const;
+
+export function specPath(capability: string): string {
+  return `${PATHS.specsDir}/${capability}.md`;
+}
+
+export function filesUnder(snapshot: Snapshot, dir: string): string[] {
+  const prefix = `${dir}/`;
+  return [...snapshot.keys()].filter((path) => path.startsWith(prefix)).sort();
+}
+
+/** Paths directly matching `<dir>/<name><suffix>`, one level deep. */
+export function childFiles(snapshot: Snapshot, dir: string, suffix: string): string[] {
+  return filesUnder(snapshot, dir).filter((path) => {
+    const rest = path.slice(dir.length + 1);
+    return !rest.includes("/") && rest.endsWith(suffix);
+  });
+}

package/src/domain/project/living_model.ts

@@ -0,0 +1,54 @@
+import { headingElements, rowElements, type Element } from "../elements.ts";
+import { parseMarkdown, type MarkdownDoc } from "../markdown.ts";
+import { PATHS, childFiles, type Snapshot } from "./layout.ts";
+
+/** An element of the living docs, with the document it lives in. */
+export interface LivingElement {
+  id: string;
+  path: string;
+  doc: MarkdownDoc;
+  element: Element;
+}
+
+/** The living docs: vision, architecture, specs and ADRs, indexed by element ID. */
+export interface LivingModel {
+  docs: Map<string, MarkdownDoc>;
+  elements: Map<string, LivingElement>;
+  /** IDs defined more than once, with every place they appear. */
+  duplicates: Array<{ id: string; places: string[] }>;
+}
+
+export function livingDocPaths(snapshot: Snapshot): string[] {
+  const fixed = [PATHS.vision, PATHS.architecture].filter((path) => snapshot.has(path));
+  return [...fixed, ...childFiles(snapshot, PATHS.specsDir, ".md"), ...childFiles(snapshot, PATHS.adrDir, ".md")];
+}
+
+export function buildLivingModel(snapshot: Snapshot): LivingModel {
+  const docs = new Map<string, MarkdownDoc>();
+  const elements = new Map<string, LivingElement>();
+  const places = new Map<string, string[]>();
+
+  for (const path of livingDocPaths(snapshot)) {
+    const doc = parseMarkdown(snapshot.get(path) ?? "");
+    docs.set(path, doc);
+    for (const element of elementsOf(path, doc)) {
+      places.set(element.id, [...(places.get(element.id) ?? []), `${path}:${element.start + 1}`]);
+      if (!elements.has(element.id)) elements.set(element.id, { id: element.id, path, doc, element });
+    }
+  }
+  const duplicates = [...places].filter(([, at]) => at.length > 1).map(([id, at]) => ({ id, places: at }));
+  return { docs, elements, duplicates };
+}
+
+/** The ID an ADR file defines: `ADR-<file stem>`. */
+export function adrId(path: string): string {
+  return `ADR-${path.slice(path.lastIndexOf("/") + 1, -".md".length)}`;
+}
+
+function elementsOf(path: string, doc: MarkdownDoc): Element[] {
+  if (path.startsWith(`${PATHS.adrDir}/`)) {
+    return [{ id: adrId(path), kind: "ADR", title: doc.headings[0]?.text ?? "", form: "heading", level: 1, start: 0, end: doc.lines.length }];
+  }
+  if (path === PATHS.vision) return rowElements(doc).filter((element) => element.kind === "GOAL");
+  return headingElements(doc);
+}

package/src/domain/project/new_items.ts

@@ -0,0 +1,48 @@
+import { CruzeError } from "../cruze_error.ts";
+import { readChangesTable } from "./plan_parts.ts";
+import type { ProjectView } from "./project_view.ts";
+import type { WorkItem } from "./work_items.ts";
+
+const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export function requireSlug(slug: string): void {
+  if (!SLUG.test(slug)) throw new CruzeError("invalid-slug", `"${slug}" must be lowercase words joined by single hyphens`);
+}
+
+/**
+ * A new feature or standalone change ID: the date plus the slug, with `-2`, `-3`… added
+ * on a clash with any live or archived work. IDs are never reused.
+ */
+export function allocateId(view: ProjectView, date: string, slug: string): string {
+  requireSlug(slug);
+  const taken = new Set(view.items.filter((item) => item.kind !== "change").map((item) => item.folderName));
+  const base = `${date}-${slug}`;
+  if (!taken.has(base)) return base;
+  for (let n = 2; ; n++) if (!taken.has(`${base}-${n}`)) return `${base}-${n}`;
+}
+
+/**
+ * The change folder name for a feature's change: the row of the feature's Changes table it
+ * names, by full name (`01-local-serial`) or slug (`local-serial`).
+ */
+export function changeRow(view: ProjectView, feature: WorkItem, name: string): ReturnType<typeof readChangesTable>[number] {
+  const rows = readChangesTable(feature.doc);
+  const row = rows.find((r) => r.change === name) ?? rows.find((r) => r.change.replace(/^\d\d-/, "") === name);
+  if (row === undefined) {
+    throw new CruzeError("change-not-listed", `${feature.ref} has no change "${name}" in its Changes table; add the row first`);
+  }
+  if (view.items.some((item) => item.featureRef === feature.ref && item.folderName === row.change)) {
+    throw new CruzeError("exists", `${feature.ref}/${row.change} already exists`);
+  }
+  return row;
+}
+
+/** Fills the template's frontmatter, title and scope lines for a new document. */
+export function fillTemplate(template: string, values: { roadmap?: string; delivers?: string[]; builds?: string[] }): string {
+  let text = template;
+  if (values.roadmap !== undefined) text = text.replace(/^roadmap: .*$/m, `roadmap: ${values.roadmap}`);
+  else text = text.replace(/^roadmap: <.*\n/m, "");
+  if (values.delivers !== undefined) text = text.replace(/^- Delivers: .*$/m, `- Delivers: ${values.delivers.join(", ")}`);
+  if (values.builds !== undefined) text = text.replace(/^- Builds: .*$/m, `- Builds: ${values.builds.join(", ")}`);
+  return text;
+}