@printpractical/cruze 0.0.1

package/src/domain/config.ts

@@ -0,0 +1,128 @@
+import { parse as parseYaml } from "yaml";
+
+/** `.cruze/config.yaml`, as described in the cruze-formats skill. */
+export interface CruzeConfig {
+  version: 1;
+  project: string;
+  tracker: "markdown";
+  source: string[];
+  tests: string[];
+  check: {
+    maxLines: number;
+    maxTypes: number;
+    exceptions: Array<{ path: string; reason: string }>;
+  };
+  layers: Layer[];
+  /** Named project commands, such as `test: cargo test`, shown in AGENTS.md. */
+  commands: Record<string, string>;
+  /** How `cruze review` starts an agent in a fresh context: the program and its arguments. */
+  review: { command: string[] };
+}
+
+/** Claude Code in print mode, allowed to read the project, its history and run `cruze`, but not to edit. */
+export const DEFAULT_REVIEW_COMMAND = ["claude", "-p", "--allowedTools", "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git show:*) Bash(cruze:*)"];
+
+export interface Layer {
+  name: string;
+  paths: string[];
+  mayImport: string[];
+}
+
+export type ConfigResult = { config: CruzeConfig; problems: string[] } | { config: null; problems: string[] };
+
+/** Parses the config, collecting every problem; returns a config only when it is usable. */
+export function parseConfig(text: string): ConfigResult {
+  let raw: unknown;
+  try {
+    raw = parseYaml(text);
+  } catch (error) {
+    return { config: null, problems: [`not valid YAML: ${error instanceof Error ? error.message : String(error)}`] };
+  }
+  const problems: string[] = [];
+  const root = asRecord(raw);
+  if (root === null) return { config: null, problems: ["the file must be a YAML mapping"] };
+
+  if (root["version"] !== 1) problems.push("version must be 1");
+  if (typeof root["project"] !== "string" || root["project"] === "") problems.push("project must be a non-empty string");
+  if (root["tracker"] !== "markdown") problems.push("tracker must be markdown");
+  const source = stringList(root["source"], "source", problems);
+  const tests = stringList(root["tests"], "tests", problems);
+
+  const check = asRecord(root["check"]) ?? {};
+  const maxLines = positiveInt(check["max_lines"], "check.max_lines", problems);
+  const maxTypes = positiveInt(check["max_types"], "check.max_types", problems);
+  const exceptions = (Array.isArray(check["exceptions"]) ? check["exceptions"] : []).flatMap((entry: unknown, i: number) => {
+    const record = asRecord(entry);
+    if (typeof record?.["path"] !== "string" || typeof record["reason"] !== "string" || record["reason"].trim() === "") {
+      problems.push(`check.exceptions[${i}] needs a path and a non-empty reason`);
+      return [];
+    }
+    return [{ path: record["path"], reason: record["reason"] }];
+  });
+
+  const layers = (Array.isArray(root["layers"]) ? root["layers"] : []).flatMap((entry: unknown, i: number) => {
+    const record = asRecord(entry);
+    if (typeof record?.["name"] !== "string") {
+      problems.push(`layers[${i}] needs a name`);
+      return [];
+    }
+    return [{ name: record["name"], paths: stringList(record["paths"], `layers[${i}].paths`, problems), mayImport: stringList(record["may_import"], `layers[${i}].may_import`, problems) }];
+  });
+  const names = layers.map((layer) => layer.name);
+  names.filter((name, i) => names.indexOf(name) !== i).forEach((name) => problems.push(`layer ${name} is defined twice`));
+  for (const layer of layers) {
+    for (const target of layer.mayImport.filter((t) => !names.includes(t))) {
+      problems.push(`layer ${layer.name} may_import names unknown layer ${target}`);
+    }
+  }
+
+  const commands: Record<string, string> = {};
+  const rawCommands = root["commands"];
+  if (rawCommands !== undefined && rawCommands !== null) {
+    const record = asRecord(rawCommands);
+    if (record === null) problems.push("commands must be a mapping of names to commands");
+    for (const [name, command] of Object.entries(record ?? {})) {
+      if (typeof command === "string" && command.trim() !== "") commands[name] = command;
+      else problems.push(`commands.${name} must be a command string`);
+    }
+  }
+  const review = asRecord(root["review"]) ?? {};
+  const reviewCommand = review["command"] === undefined ? DEFAULT_REVIEW_COMMAND : stringList(review["command"], "review.command", problems);
+  if (reviewCommand.length === 0) problems.push("review.command needs at least the program to run");
+
+  const config: CruzeConfig = {
+    version: 1,
+    project: typeof root["project"] === "string" ? root["project"] : "",
+    tracker: "markdown",
+    source,
+    tests,
+    check: { maxLines: maxLines ?? 250, maxTypes: maxTypes ?? 5, exceptions },
+    layers,
+    commands,
+    review: { command: reviewCommand.length === 0 ? DEFAULT_REVIEW_COMMAND : reviewCommand },
+  };
+  return { config, problems };
+}
+
+/** The first layer whose paths match the file, as the formats define. */
+export function layerOf(config: CruzeConfig, path: string, matches: (path: string, globs: string[]) => boolean): Layer | undefined {
+  return config.layers.find((layer) => matches(path, layer.paths));
+}
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : null;
+}
+
+function stringList(value: unknown, key: string, problems: string[]): string[] {
+  if (value === undefined || value === null) return [];
+  if (Array.isArray(value) && value.every((item) => typeof item === "string")) return value as string[];
+  problems.push(`${key} must be a list of strings`);
+  return [];
+}
+
+function positiveInt(value: unknown, key: string, problems: string[]): number | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value === "number" && Number.isInteger(value) && value > 0) return value;
+  problems.push(`${key} must be a positive whole number`);
+  return undefined;
+}

package/src/domain/cruze_error.ts

@@ -0,0 +1,10 @@
+/** An expected failure the CLI reports to the user, as opposed to a bug. */
+export class CruzeError extends Error {
+  readonly code: string;
+
+  constructor(code: string, message: string) {
+    super(message);
+    this.name = "CruzeError";
+    this.code = code;
+  }
+}

package/src/domain/edits/agents_file.ts

@@ -0,0 +1,44 @@
+import { factsOf, statusOf } from "../elements.ts";
+import type { ProjectView } from "../project/project_view.ts";
+
+/**
+ * The managed sections of a project's `AGENTS.md`: its commands, from `.cruze/config.yaml`,
+ * and its layout, from the built modules in `docs/architecture.md`.
+ */
+
+const OPEN = "<!-- cruze:managed -->";
+const CLOSE = "<!-- /cruze:managed -->";
+
+/** Rewrites the managed blocks under `## Commands` and `## Layout`; other text is left alone. */
+export function renderAgentsFile(text: string, view: ProjectView): string {
+  let next = text;
+  const commands = Object.entries(view.config?.config?.commands ?? {});
+  if (commands.length > 0) next = replaceBlock(next, "Commands", commands.map(([name, command]) => `- ${name}: \`${command}\``));
+  const modules = builtModules(view);
+  if (modules.length > 0) next = replaceBlock(next, "Layout", ["Modules, from `docs/architecture.md`:", "", ...modules]);
+  return next;
+}
+
+function builtModules(view: ProjectView): string[] {
+  return [...view.living.elements.values()]
+    .filter(({ element, doc }) => element.kind === "MOD" && statusOf(doc, element) === "built")
+    .map(({ element, doc }) => {
+      const facts = factsOf(doc, element);
+      const paths = (facts.get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => `\`${m[1] ?? ""}\``));
+      return `- ${paths.join(", ")} (${facts.get("Layer")?.[0] ?? "unknown"}): ${element.title}`;
+    })
+    .sort();
+}
+
+/** Replaces the body of the first managed block after `## <heading>`, before the next `## ` heading. */
+function replaceBlock(text: string, heading: string, body: string[]): string {
+  const lines = text.split("\n");
+  const at = lines.findIndex((line) => line === `## ${heading}`);
+  if (at === -1) return text;
+  const sectionEnd = lines.findIndex((line, i) => i > at && line.startsWith("## "));
+  const end = sectionEnd === -1 ? lines.length : sectionEnd;
+  const open = lines.findIndex((line, i) => i > at && i < end && line.trim() === OPEN);
+  const close = lines.findIndex((line, i) => i > open && i < end && line.trim() === CLOSE);
+  if (open === -1 || close === -1) return text;
+  return [...lines.slice(0, open + 1), ...body, ...lines.slice(close)].join("\n");
+}

package/src/domain/edits/managed_tables.ts

@@ -0,0 +1,60 @@
+import { parseMarkdown } from "../markdown.ts";
+import { splitRow, tablesIn } from "../markdown_tables.ts";
+
+/**
+ * Edits to the managed tables: the feature map in vision.md and the status table
+ * in roadmap.md. Rows are keyed by their first cell.
+ */
+
+/** Replaces or appends the row keyed by `cells[0]` in the table under a heading. */
+export function upsertRow(text: string, heading: string, cells: string[]): string {
+  return editTable(text, heading, (rows) => {
+    const index = rows.findIndex((row) => row[0] === cells[0]);
+    if (index === -1) rows.push(cells);
+    else rows[index] = cells;
+  });
+}
+
+export function removeRow(text: string, heading: string, key: string): { text: string; removed: string[] | null } {
+  let removed: string[] | null = null;
+  const next = editTable(text, heading, (rows) => {
+    const index = rows.findIndex((row) => row[0] === key);
+    if (index !== -1) removed = rows.splice(index, 1)[0] ?? null;
+  });
+  return { text: next, removed };
+}
+
+export function readRows(text: string, heading: string): string[][] {
+  const doc = parseMarkdown(text);
+  const at = doc.headings.find((h) => h.text === heading);
+  if (at === undefined) return [];
+  const end = doc.headings.find((h) => h.line > at.line && h.level <= at.level)?.line ?? doc.lines.length;
+  return tablesIn(doc.lines, doc.inFence, at.line + 1, end)[0]?.rows.map((row) => row.cells) ?? [];
+}
+
+function editTable(text: string, heading: string, edit: (rows: string[][]) => void): string {
+  const doc = parseMarkdown(text);
+  const at = doc.headings.find((h) => h.text === heading);
+  if (at === undefined) throw new Error(`No "${heading}" heading to edit`);
+  const end = doc.headings.find((h) => h.line > at.line && h.level <= at.level)?.line ?? doc.lines.length;
+  let first = -1;
+  let last = -1;
+  for (let i = at.line + 1; i < end; i++) {
+    if (/^\s*\|.*\|\s*$/.test(doc.lines[i] ?? "")) {
+      if (first === -1) first = i;
+      last = i;
+    } else if (first !== -1) break;
+  }
+  if (first === -1) throw new Error(`No table under "${heading}"`);
+  const header = splitRow(doc.lines[first] ?? "");
+  const rows = doc.lines.slice(first + 2, last + 1).map(splitRow);
+  edit(rows);
+  const rendered = [renderRow(header), renderRow(header.map(() => "---")), ...rows.map(renderRow)];
+  const lines = [...doc.lines];
+  lines.splice(first, last - first + 1, ...rendered);
+  return lines.join("\n");
+}
+
+function renderRow(cells: string[]): string {
+  return `| ${cells.join(" | ")} |`;
+}

package/src/domain/edits/progress_block.ts

@@ -0,0 +1,33 @@
+import { MANAGED_CLOSE, MANAGED_OPEN, parseMarkdown } from "../markdown.ts";
+import { readTasks } from "../project/plan_parts.ts";
+import { progressRange, readProgress, type Progress } from "../project/progress.ts";
+
+/** Rewrites the managed `## Progress` block of a feature or change from a changed Progress. */
+export function updateProgress(text: string, change: (progress: Progress) => void): string {
+  const doc = parseMarkdown(text);
+  const progress = readProgress(doc);
+  for (const task of readTasks(doc).tasks) if (!progress.tasks.has(task.number)) progress.tasks.set(task.number, null);
+  change(progress);
+  const block = [MANAGED_OPEN, "## Progress", ...renderProgress(progress), MANAGED_CLOSE];
+  const range = progressRange(doc);
+  const lines = [...doc.lines];
+  if (range === null) {
+    while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+    return [...lines, "", ...block, ""].join("\n");
+  }
+  lines.splice(range.open, range.end - range.open + 1, ...block);
+  return lines.join("\n");
+}
+
+function renderProgress(progress: Progress): string[] {
+  const lines: string[] = [];
+  if (progress.branch !== undefined) lines.push(`- Branch: ${progress.branch}`);
+  for (const [change, state] of progress.changes) lines.push(`- ${change}: ${state}`);
+  const ordered = [...progress.tasks].sort(([a], [b]) => Number(a.slice(1)) - Number(b.slice(1)));
+  for (const [task, commit] of ordered) {
+    lines.push(commit === null ? `- [ ] ${task}` : commit === "" ? `- [x] ${task}` : `- [x] ${task} (${commit})`);
+  }
+  for (const deviation of progress.deviations) lines.push(`- Deviation ${deviation}`);
+  if (progress.landed !== undefined) lines.push(`- Landed: ${progress.landed}`);
+  return lines;
+}

package/src/domain/edits/status_lines.ts

@@ -0,0 +1,52 @@
+import { headingElements, isStatusLine, statusOf, type Status } from "../elements.ts";
+import { STATUS_KINDS } from "../ids.ts";
+import { parseMarkdown, type MarkdownDoc } from "../markdown.ts";
+
+/** Managed `- Status:` lines: only the CLI adds or changes them. */
+
+/** Sets one element's status, adding the line after its facts when it has none. Returns the new text. */
+export function setStatus(text: string, id: string, status: Status): string {
+  const doc = parseMarkdown(text);
+  const element = headingElements(doc).find((e) => e.id === id);
+  if (element === undefined) throw new Error(`${id} is not in this document`);
+  const lines = [...doc.lines];
+  const at = statusLineIndex(doc, element.start, element.end);
+  if (at !== null) lines[at] = `- Status: ${status}`;
+  else lines.splice(insertionPoint(doc, element.start, element.end), 0, `- Status: ${status}`);
+  return lines.join("\n");
+}
+
+/** Adds `- Status: planned` to every status-carrying element that has none. */
+export function stampMissingStatuses(text: string): { text: string; stamped: string[] } {
+  let current = text;
+  const stamped: string[] = [];
+  for (const element of headingElements(parseMarkdown(text))) {
+    if (!STATUS_KINDS.includes(element.kind)) continue;
+    const doc = parseMarkdown(current);
+    const fresh = headingElements(doc).find((e) => e.id === element.id);
+    if (fresh === undefined || statusOf(doc, fresh) !== undefined) continue;
+    current = setStatus(current, element.id, "planned");
+    stamped.push(element.id);
+  }
+  return { text: current, stamped };
+}
+
+function statusLineIndex(doc: MarkdownDoc, start: number, end: number): number | null {
+  for (let i = start + 1; i < end; i++) {
+    if (!doc.inFence[i] && /^#{1,6} /.test(doc.lines[i] ?? "")) return null;
+    if (!doc.inFence[i] && isStatusLine(doc.lines[i] ?? "")) return i;
+  }
+  return null;
+}
+
+/** After the element's last top-level fact or step, before any diagram or nested heading. */
+function insertionPoint(doc: MarkdownDoc, start: number, end: number): number {
+  let point = start + 1;
+  for (let i = start + 1; i < end; i++) {
+    const line = doc.lines[i] ?? "";
+    if (doc.inFence[i] || /^#{1,6} /.test(line)) break;
+    if (/^(- |\s{2,}- )/.test(line)) point = i + 1;
+    else if (line.trim() !== "" && point > start + 1) break;
+  }
+  return point;
+}

package/src/domain/elements.ts

@@ -0,0 +1,126 @@
+import { ID_PATTERN, STATUS_KINDS, kindOf, type Kind } from "./ids.ts";
+import { sectionEnd, type MarkdownDoc } from "./markdown.ts";
+
+export type DeltaOp = "ADDED" | "MODIFIED" | "REMOVED";
+export type Status = "planned" | "built";
+
+/** One element: a heading `<ID>: <Title>` and its body, or a table row whose first cell is an ID. */
+export interface Element {
+  id: string;
+  kind: Kind;
+  title: string;
+  form: "heading" | "row";
+  /** Set when the heading is a delta operation, such as `### ADDED PORT-x: Title`. */
+  op?: DeltaOp;
+  level: number;
+  /** Line range [start, end) in the document. */
+  start: number;
+  end: number;
+}
+
+/** A delta heading that creates a spec file: `### ADDED CAPABILITY <name>: <Title>`. */
+export interface CapabilityOp {
+  capability: string;
+  title: string;
+  start: number;
+  end: number;
+}
+
+const HEADING = new RegExp(`^(?:(ADDED|MODIFIED|REMOVED) )?(${ID_PATTERN}): (.+)$`);
+const CAPABILITY = /^ADDED CAPABILITY ([a-z0-9]+(?:-[a-z0-9]+)*): (.+)$/;
+const ROW = new RegExp(`^\\|\\s*(${ID_PATTERN})\\s*\\|(.*)\\|\\s*$`);
+const STATUS_LINE = /^- Status: (planned|built)\s*$/;
+
+/** Heading elements whose heading lies in [from, to). */
+export function headingElements(doc: MarkdownDoc, from = 0, to = doc.lines.length): Element[] {
+  const elements: Element[] = [];
+  for (const heading of doc.headings) {
+    if (heading.line < from || heading.line >= to) continue;
+    const match = HEADING.exec(heading.text);
+    if (match?.[2] === undefined || match[3] === undefined) continue;
+    const element: Element = {
+      id: match[2],
+      kind: kindOf(match[2]),
+      title: match[3],
+      form: "heading",
+      level: heading.level,
+      start: heading.line,
+      end: Math.min(sectionEnd(doc, heading), to),
+    };
+    if (match[1] !== undefined) element.op = match[1] as DeltaOp;
+    elements.push(element);
+  }
+  return elements;
+}
+
+export function capabilityOps(doc: MarkdownDoc, from = 0, to = doc.lines.length): CapabilityOp[] {
+  return doc.headings
+    .filter((h) => h.line >= from && h.line < to)
+    .flatMap((heading) => {
+      const match = CAPABILITY.exec(heading.text);
+      if (match?.[1] === undefined || match[2] === undefined) return [];
+      return [{ capability: match[1], title: match[2], start: heading.line, end: Math.min(sectionEnd(doc, heading), to) }];
+    });
+}
+
+/** Row elements: table rows, outside code fences, whose first cell is an ID. */
+export function rowElements(doc: MarkdownDoc): Element[] {
+  return doc.lines.flatMap((line, index) => {
+    if (doc.inFence[index]) return [];
+    const match = ROW.exec(line);
+    if (match?.[1] === undefined) return [];
+    const title = match[2]?.split("|")[0]?.trim() ?? "";
+    return [{ id: match[1], kind: kindOf(match[1]), title, form: "row" as const, level: 0, start: index, end: index + 1 }];
+  });
+}
+
+export function elementLines(doc: MarkdownDoc, element: { start: number; end: number }): string[] {
+  return doc.lines.slice(element.start, element.end);
+}
+
+export function isStatusLine(line: string): boolean {
+  return STATUS_LINE.test(line);
+}
+
+/** The element's own managed status: the first status line before any nested heading. */
+/**
+ * Whether an element is still to be built: marked `planned`, or a kind that carries a status
+ * but not stamped yet, because the document holding it has never been approved.
+ */
+export function isUnbuilt(doc: MarkdownDoc, element: Element): boolean {
+  const status = statusOf(doc, element);
+  return status === "planned" || (status === undefined && STATUS_KINDS.includes(element.kind));
+}
+
+export function statusOf(doc: MarkdownDoc, element: Element): Status | undefined {
+  for (let i = element.start + 1; i < element.end; i++) {
+    if (/^#{1,6} /.test(doc.lines[i] ?? "") && !doc.inFence[i]) return undefined;
+    const match = STATUS_LINE.exec(doc.lines[i] ?? "");
+    if (match?.[1] !== undefined) return match[1] as Status;
+  }
+  return undefined;
+}
+
+/**
+ * The element's top-level facts: `- Key: value` items and their indented sub-items.
+ * Nested elements' facts are excluded.
+ */
+export function factsOf(doc: MarkdownDoc, element: Element): Map<string, string[]> {
+  const facts = new Map<string, string[]>();
+  let current: string[] | null = null;
+  for (let i = element.start + 1; i < element.end; i++) {
+    const line = doc.lines[i] ?? "";
+    if (doc.inFence[i]) continue;
+    if (/^#{1,6} /.test(line)) break;
+    const fact = /^- ([A-Z][A-Za-z ]*): ?(.*)$/.exec(line);
+    if (fact?.[1] !== undefined) {
+      current = fact[2] === undefined || fact[2] === "" ? [] : [fact[2]];
+      facts.set(fact[1], current);
+      continue;
+    }
+    const sub = /^\s{2,}- (.+)$/.exec(line);
+    if (sub?.[1] !== undefined && current !== null) current.push(sub[1]);
+    else if (line.trim() !== "") current = null;
+  }
+  return facts;
+}

package/src/domain/glob.ts

@@ -0,0 +1,46 @@
+/**
+ * Glob matching for config paths: `**` matches any number of directories,
+ * `*` anything within one path segment, `?` one character, `{a,b}` either.
+ */
+
+const cache = new Map<string, RegExp>();
+
+export function matchesGlob(path: string, glob: string): boolean {
+  let regex = cache.get(glob);
+  if (regex === undefined) {
+    regex = new RegExp(`^${globToRegex(glob)}$`);
+    cache.set(glob, regex);
+  }
+  return regex.test(path);
+}
+
+export function matchesAny(path: string, globs: readonly string[]): boolean {
+  return globs.some((glob) => matchesGlob(path, glob));
+}
+
+function globToRegex(glob: string): string {
+  let out = "";
+  for (let i = 0; i < glob.length; i++) {
+    const char = glob[i] ?? "";
+    if (char === "*" && glob[i + 1] === "*") {
+      const slashAfter = glob[i + 2] === "/";
+      out += slashAfter ? "(?:.*/)?" : ".*";
+      i += slashAfter ? 2 : 1;
+    } else if (char === "*") {
+      out += "[^/]*";
+    } else if (char === "?") {
+      out += "[^/]";
+    } else if (char === "{") {
+      const close = glob.indexOf("}", i);
+      if (close === -1) {
+        out += "\\{";
+        continue;
+      }
+      out += `(?:${glob.slice(i + 1, close).split(",").map(globToRegex).join("|")})`;
+      i = close;
+    } else {
+      out += char.replace(/[.+^$()|[\]\\]/g, "\\$&");
+    }
+  }
+  return out;
+}

package/src/domain/hashing.ts

@@ -0,0 +1,52 @@
+import { createHash } from "node:crypto";
+import { elementLines, isStatusLine, type Element } from "./elements.ts";
+import type { MarkdownDoc } from "./markdown.ts";
+
+/**
+ * Hashes cover design content only. Managed blocks and status lines are
+ * excluded, so bookkeeping by the CLI never makes a design look edited.
+ */
+
+export function sha256(text: string): string {
+  return `sha256:${createHash("sha256").update(text).digest("hex")}`;
+}
+
+/** Hash of a whole document's design content. */
+export function designHash(doc: MarkdownDoc): string {
+  const kept = doc.lines.filter((line, i) => !doc.inManaged[i] && (doc.inFence[i] || !isStatusLine(line)));
+  return sha256(normalize(kept));
+}
+
+/**
+ * Hash of one element, independent of where it sits: heading levels are made
+ * relative to the element and a delta operation prefix is dropped, so an element
+ * hashes the same in a delta and after it is merged into a living document.
+ */
+export function elementHash(doc: MarkdownDoc, element: Element): string {
+  if (element.form === "row") return sha256(normalize(elementLines(doc, element)));
+  const kept: string[] = [];
+  for (let i = element.start; i < element.end; i++) {
+    const line = doc.lines[i] ?? "";
+    if (doc.inManaged[i] || (!doc.inFence[i] && isStatusLine(line))) continue;
+    kept.push(doc.inFence[i] ? line : relativeHeading(line, element.level, i === element.start));
+  }
+  return sha256(normalize(kept));
+}
+
+function relativeHeading(line: string, baseLevel: number, isOwnHeading: boolean): string {
+  const match = /^(#{1,6}) (.*)$/.exec(line);
+  if (match?.[1] === undefined || match[2] === undefined) return line;
+  const text = isOwnHeading ? match[2].replace(/^(ADDED|MODIFIED|REMOVED) /, "") : match[2];
+  return `${"#".repeat(match[1].length - baseLevel + 1)} ${text}`;
+}
+
+function normalize(lines: string[]): string {
+  const out: string[] = [];
+  for (const raw of lines) {
+    const line = raw.trimEnd();
+    if (line === "" && (out.length === 0 || out[out.length - 1] === "")) continue;
+    out.push(line);
+  }
+  while (out.length > 0 && out[out.length - 1] === "") out.pop();
+  return out.join("\n");
+}

package/src/domain/ids.ts

@@ -0,0 +1,37 @@
+/** Element IDs: `<KIND>-<name>` or `<KIND>-<scope>.<name>`, named and never reused. */
+
+export const KINDS = ["GOAL", "CTX", "ENT", "UC", "PORT", "ADP", "FLOW", "MOD", "RULE", "VIEW", "XC", "REQ", "SCN", "ADR"] as const;
+export type Kind = (typeof KINDS)[number];
+
+/** Kinds that describe code, and so carry a managed planned/built status. */
+export const CODE_KINDS: readonly Kind[] = ["ENT", "UC", "PORT", "ADP", "FLOW", "MOD"];
+/** Kinds whose elements carry a managed status: code kinds and scenarios. */
+export const STATUS_KINDS: readonly Kind[] = [...CODE_KINDS, "SCN"];
+/** Kinds that must name their context or capability as a scope. */
+export const SCOPED_KINDS: readonly Kind[] = ["ENT", "UC", "PORT", "ADP", "FLOW", "REQ", "SCN"];
+
+const WORD = "[a-z0-9]+(?:-[a-z0-9]+)*";
+export const ID_PATTERN = `(?:${KINDS.join("|")})-${WORD}(?:\\.${WORD})?`;
+
+const EXACT = new RegExp(`^${ID_PATTERN}$`);
+const ANYWHERE = new RegExp(`(?<![A-Za-z0-9_-])${ID_PATTERN}(?![A-Za-z0-9_-])`, "g");
+
+export function isId(text: string): boolean {
+  return EXACT.test(text);
+}
+
+export function kindOf(id: string): Kind {
+  return id.slice(0, id.indexOf("-")) as Kind;
+}
+
+/** The context or capability an ID belongs to, if it has one. */
+export function scopeOf(id: string): string | undefined {
+  const rest = id.slice(id.indexOf("-") + 1);
+  const dot = rest.indexOf(".");
+  return dot === -1 ? undefined : rest.slice(0, dot);
+}
+
+/** Every ID mentioned in the text, once each, in order of first mention. */
+export function findIds(text: string): string[] {
+  return [...new Set(text.match(ANYWHERE) ?? [])];
+}

package/src/domain/journal.ts

@@ -0,0 +1,62 @@
+/** The append-only journal: one JSON object per line, written only by the CLI. */
+
+export interface JournalEntry {
+  at: string;
+  event: string;
+  by: string;
+  [field: string]: unknown;
+}
+
+/** Events other tools and skills record, with the fields each requires. */
+export const RECORDED_EVENTS: Record<string, string[]> = {
+  rethink: ["level", "kind", "summary", "wrong", "caught_by"],
+  disposition: ["finding", "disposition", "reason", "review"],
+  review: ["review", "round", "blockers", "concerns"],
+  override: ["gate", "reason"],
+  bug: ["summary", "cause"],
+  verification: ["result", "summary"],
+};
+
+export const FIELD_VALUES: Record<string, string[]> = {
+  level: ["task", "change", "feature", "architecture", "vision"],
+  kind: ["defect", "discovery"],
+  disposition: ["fixed", "waived", "deferred", "rejected"],
+  review: ["design", "plan", "code"],
+  result: ["accepted", "sent-back"],
+};
+
+export function journalPath(folder: string): string {
+  return `${folder}/journal.jsonl`;
+}
+
+export function parseJournal(text: string | undefined): { entries: JournalEntry[]; badLines: number[] } {
+  const entries: JournalEntry[] = [];
+  const badLines: number[] = [];
+  (text ?? "").split("\n").forEach((line, index) => {
+    if (line.trim() === "") return;
+    try {
+      const entry = JSON.parse(line) as JournalEntry;
+      if (typeof entry.event === "string" && typeof entry.at === "string") entries.push(entry);
+      else badLines.push(index + 1);
+    } catch {
+      badLines.push(index + 1);
+    }
+  });
+  return { entries, badLines };
+}
+
+export function serializeEntry(entry: JournalEntry): string {
+  return `${JSON.stringify(entry)}\n`;
+}
+
+/** Problems with an event a caller asks to record; empty when it can be recorded. */
+export function recordedEventProblems(event: string, fields: Record<string, string>): string[] {
+  const required = RECORDED_EVENTS[event];
+  if (required === undefined) return [`unknown event "${event}"; recordable events: ${Object.keys(RECORDED_EVENTS).join(", ")}`];
+  const problems = required.filter((field) => (fields[field] ?? "").trim() === "").map((field) => `${event} needs ${field}`);
+  for (const [field, allowed] of Object.entries(FIELD_VALUES)) {
+    const value = fields[field];
+    if (value !== undefined && required.includes(field) && !allowed.includes(value)) problems.push(`${field} must be one of ${allowed.join(", ")}`);
+  }
+  return problems;
+}