@printpractical/cruze 0.0.13 → 0.0.15

package/src/app/use_cases/show_scope.ts

@@ -1,51 +0,0 @@
-import { CruzeError } from "../../domain/cruze_error.ts";
-import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
-import { scopeOf } from "../../domain/ids.ts";
-import { notesFor, readNotes, type NotesFor } from "../../domain/project/notes.ts";
-import { scopeView, type ScopeView } from "../../domain/project/scope_view.ts";
-import type { WorkItem } from "../../domain/project/work_items.ts";
-import { loadView, type ProjectDeps } from "../project_context.ts";
-import { listEvents } from "./journal_events.ts";
-
-export interface Disposition {
-  finding: string;
-  disposition: string;
-  reason: string;
-  review: string;
-}
-
-export interface ScopeReport extends ScopeView {
-  /** The settled ledger of the item: the feature's dispositions and its changes', or a standalone change's. */
-  dispositions: Disposition[];
-  /** The external documents the design must comply with, from `references:` in `.cruze/config.yaml`. */
-  references: Array<{ path: string; use: string }>;
-  /** The notes about this work, and the parts of the user's input handed to it. */
-  notes: NotesFor;
-}
-
-/**
- * The design a change builds, or a feature's whole delta, with the elements it cites and the
- * item's settled ledger: what plan, build and the reviewers read instead of the whole living docs.
- */
-export async function showScope(deps: ProjectDeps, ref: string): Promise<ScopeReport> {
-  const view = await loadView(deps.files);
-  const { item } = resolveArtifact(view, ref);
-  if (item === undefined) throw new CruzeError("not-work", `"${ref}" is not a feature or change; show takes a feature or change ID`);
-  const scope = scopeView(view, item);
-  const dispositions = (await listEvents(deps, "disposition", scope.feature ?? item.ref, true)).map((entry) => ({
-    finding: String(entry["finding"] ?? ""),
-    disposition: String(entry["disposition"] ?? ""),
-    reason: String(entry["reason"] ?? ""),
-    review: String(entry["review"] ?? ""),
-  }));
-  const feature = scope.feature === undefined ? item : (view.items.find((i) => i.ref === scope.feature) ?? item);
-  const contexts = [...scope.elements, ...scope.scenarios].flatMap((e) => scopeOf(e.id) ?? []);
-  const notes = notesFor(readNotes(view.snapshot), [...slugsOf(feature), ...contexts]);
-  return { ...scope, dispositions, references: view.config?.config?.references ?? [], notes };
-}
-
-/** The names a note or a hand-off may use for a feature or standalone change: its roadmap slug, and its folder name without the date. */
-export function slugsOf(item: WorkItem): string[] {
-  const roadmap = item.doc.frontmatter?.["roadmap"];
-  return [...new Set([...(typeof roadmap === "string" ? [roadmap] : []), item.folderName.replace(/^\d{4}-\d{2}-\d{2}-/, "")])];
-}

package/src/app/use_cases/upstream_diff.ts

@@ -1,55 +0,0 @@
-import { evaluateApproval, type ApprovalState } from "../../domain/approvals/evaluate.ts";
-import { rebaseNeeded } from "../../domain/approvals/rebase.ts";
-import { upstreamLines, upstreamPath } from "../../domain/approvals/upstream_text.ts";
-import { lineDiff } from "../../domain/line_diff.ts";
-import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
-import { approvalFolder, approvalsPath } from "../../domain/project/project_view.ts";
-import { loadView, type ProjectDeps } from "../project_context.ts";
-
-export interface UpstreamChange {
-  /** The upstream element ID, or `doc:<path>` for a feature's design. */
-  key: string;
-  path?: string;
-  /** The approved text against the current text, when the approved text was found. */
-  diff?: string[];
-  note?: string;
-}
-
-export interface UpstreamDiffReport {
-  artifact: string;
-  ref?: string;
-  state: ApprovalState;
-  changes: UpstreamChange[];
-  /** Elements the work's delta changes whose living text moved: approval needs --rebase for each. */
-  rebase: string[];
-}
-
-/**
- * What changed upstream of a document since its approval, element by element, so a person can
- * judge a re-stamp from the text rather than the IDs. The approved text comes from the commit
- * that recorded the approval. One project went to a rethink for two file-list merges that
- * changed no behaviour, because status named only the IDs.
- */
-export async function upstreamDiff(deps: ProjectDeps, ref: string): Promise<UpstreamDiffReport> {
-  const view = await loadView(deps.files);
-  const { path, item } = resolveArtifact(view, ref);
-  const status = evaluateApproval(view, path);
-  const report: UpstreamDiffReport = { artifact: path, state: status.state, changes: [], rebase: item === undefined ? [] : rebaseNeeded(view, item) };
-  if (item !== undefined) report.ref = item.ref;
-  const record = status.record;
-  if (record === undefined || status.changed.length === 0) return report;
-  const commit = await deps.repository.firstCommitAdding(approvalsPath(approvalFolder(view, path)), record.approvedAt);
-  for (const key of status.changed) {
-    const where = upstreamPath(view, key);
-    if (where === undefined) {
-      report.changes.push({ key, note: "it no longer exists" });
-      continue;
-    }
-    const now = upstreamLines(key, where, view.snapshot.get(where) ?? "") ?? [];
-    const then = commit === null ? null : await deps.repository.fileAt(commit, where);
-    const approved = then === null ? undefined : upstreamLines(key, where, then, record.upstream[key]);
-    if (approved !== undefined) report.changes.push({ key, path: where, diff: lineDiff(approved, now) });
-    else report.changes.push({ key, path: where, note: commit === null ? "the approval isn't committed yet; compare with git diff" : `its approved text isn't in ${where} at ${commit}, the commit that recorded the approval` });
-  }
-  return report;
-}

package/src/domain/approvals/agent_approval.ts

@@ -1,68 +0,0 @@
-import { CruzeError } from "../cruze_error.ts";
-import type { JournalEntry } from "../journal.ts";
-import type { WorkItem } from "../project/work_items.ts";
-import type { ApprovalStatus } from "./evaluate.ts";
-
-/**
- * Why an approval was given without the user: a plan whose review closed, or work that a
- * rethink left unchanged while something it cites moved. The user can still object, and
- * editing the document makes the approval stale as usual.
- */
-export type AgentBasis = "plan-review" | "rethink";
-
-const byTime = (a: JournalEntry, b: JournalEntry): number => a.at.localeCompare(b.at);
-
-/**
- * A feature's change may be approved by the agent once its plan review has closed: a review
- * recorded since the change was last approved, no blocker left open in its last round, and a
- * disposition for every finding of its first round. The feature's design, and a standalone
- * change's, stay the user's to approve.
- */
-export function requirePlanReviewClosed(journal: JournalEntry[], item: WorkItem): void {
-  if (item.kind !== "change") {
-    throw new CruzeError("needs-user", `${item.ref} carries design, so the user approves it; only a feature's change can be approved after its plan review`);
-  }
-  const entries = journal.filter((e) => e["item"] === item.ref || e["artifact"] === item.path).sort(byTime);
-  const lastApproval = entries.filter((e) => e.event === "approve").at(-1);
-  const reviews = entries.filter((e) => e.event === "review" && e["review"] === "plan" && (lastApproval === undefined || e.at > lastApproval.at));
-  const last = reviews.at(-1);
-  if (last === undefined) {
-    const since = lastApproval === undefined ? "" : " since the change was last approved";
-    throw new CruzeError("plan-review-open", `no plan review is recorded for ${item.ref}${since}; run the plan review first`);
-  }
-  const blockers = Number(last["blockers"] ?? 0);
-  if (blockers > 0 && Number(last["round"]) === 1) {
-    throw new CruzeError("plan-review-open", `the plan review's round 1 found ${blockers} blocker(s); check their fixes in round 2`);
-  }
-  if (blockers > 0) {
-    throw new CruzeError("plan-review-open", `round 2 left ${blockers} blocker(s) open; the user decides them and approves the plan`);
-  }
-  const first = reviews.filter((e) => Number(e["round"]) === 1).at(-1) ?? last;
-  const findings = Number(first["blockers"] ?? 0) + Number(first["concerns"] ?? 0);
-  const decided = entries.filter((e) => e.event === "disposition" && e["review"] === "plan" && e.at > first.at).length;
-  if (decided < findings) {
-    throw new CruzeError("plan-review-open", `the plan review raised ${findings} finding(s) but ${decided} have a disposition; record one for each`);
-  }
-}
-
-/**
- * A rethink may re-approve, for the user, a feature or change it didn't edit: one whose own
- * design is unchanged and that is stale only because something it cites changed. A change
- * with a task reopened since its approval goes back to the user.
- */
-export function requireUnchangedSinceApproval(journal: JournalEntry[], item: WorkItem | undefined, path: string, status: ApprovalStatus): void {
-  if (item === undefined) {
-    throw new CruzeError("needs-user", `${path} is a project document, so the user re-approves it; a rethink re-stamps only features and changes`);
-  }
-  if (status.state === "edited") {
-    throw new CruzeError("needs-user", `${item.ref} itself changed since its approval, so the user re-approves it`);
-  }
-  if (status.state !== "upstream-changed") {
-    throw new CruzeError("not-stale", `${item.ref} is ${status.state}; only work whose upstream changed can be re-stamped`);
-  }
-  const approvedAt = journal.filter((e) => e.event === "approve" && e["artifact"] === path).sort(byTime).at(-1)?.at ?? "";
-  const reopened = journal.filter((e) => e.event === "reopen" && e["change"] === item.ref && e.at > approvedAt).map((e) => String(e["task"]));
-  if (reopened.length > 0) {
-    throw new CruzeError("needs-user", `${item.ref} had ${reopened.join(", ")} reopened since its approval, so the user re-approves it`);
-  }
-}

package/src/domain/approvals/evaluate.ts

@@ -1,36 +0,0 @@
-import { parseMarkdown } from "../markdown.ts";
-import { approvalFolder, type ProjectView } from "../project/project_view.ts";
-import { currentUpstreamHash, fingerprint } from "./fingerprint.ts";
-import { latestApproval, type ApprovalRecord } from "./records.ts";
-
-export type ApprovalState = "approved" | "edited" | "upstream-changed" | "unapproved";
-
-export interface ApprovalStatus {
-  artifact: string;
-  state: ApprovalState;
-  /** Upstream IDs or documents that changed or disappeared since approval. */
-  changed: string[];
-  record?: ApprovalRecord;
-  /** Set when an approval exists but the journal has no matching entry. */
-  unjournaled?: boolean;
-}
-
-/**
- * Computes an artifact's approval state from content, never from stored state:
- * editing an upstream document is all it takes to make downstream work stale.
- */
-export function evaluateApproval(view: ProjectView, artifact: string): ApprovalStatus {
-  const record = latestApproval(view.approvals.get(approvalFolder(view, artifact)) ?? { version: 1, approvals: [], merged: {} }, artifact);
-  if (record === undefined) return { artifact, state: "unapproved", changed: [] };
-  const journaled = view.journal.some((e) => e.event === "approve" && e.artifact === artifact && e.hash === record.hash);
-  if (!journaled) return { artifact, state: "unapproved", changed: [], record, unjournaled: true };
-
-  const text = view.snapshot.get(artifact);
-  if (text === undefined) return { artifact, state: "unapproved", changed: [], record };
-  const { hash } = fingerprint(view, artifact, parseMarkdown(text));
-  if (hash !== record.hash) return { artifact, state: "edited", changed: [], record };
-  const changed = Object.entries(record.upstream)
-    .filter(([key, pinned]) => currentUpstreamHash(view, key) !== pinned)
-    .map(([key]) => key);
-  return { artifact, state: changed.length > 0 ? "upstream-changed" : "approved", changed, record };
-}

package/src/domain/approvals/fingerprint.ts

@@ -1,52 +0,0 @@
-import { headingElements, rowElements } from "../elements.ts";
-import { designHash, elementHash } from "../hashing.ts";
-import { findIds } from "../ids.ts";
-import type { MarkdownDoc } from "../markdown.ts";
-import { PATHS } from "../project/layout.ts";
-import type { ProjectView } from "../project/project_view.ts";
-import { featureOf } from "../project/work_items.ts";
-
-/** What an approval pins: the document's design hash and the hash of everything upstream it relies on. */
-export interface Fingerprint {
-  hash: string;
-  upstream: Record<string, string>;
-}
-
-/** Documents a person can approve. Specs, the glossary and ADRs change only through approved work. */
-export function isApprovable(view: ProjectView, path: string): boolean {
-  return [PATHS.vision, PATHS.architecture, PATHS.roadmap].includes(path as never) || view.items.some((i) => i.path === path && !i.archived);
-}
-
-export function fingerprint(view: ProjectView, path: string, doc: MarkdownDoc): Fingerprint {
-  const upstream: Record<string, string> = {};
-  const ownIds = new Set([...headingElements(doc), ...rowElements(doc)].filter((e) => e.op !== "ADDED").map((e) => e.id));
-  const isLivingDoc = !view.items.some((item) => item.path === path);
-  const designText = doc.lines.filter((_, i) => !doc.inManaged[i]).join("\n");
-
-  for (const id of findIds(designText)) {
-    if (isLivingDoc && ownIds.has(id)) continue;
-    const living = view.living.elements.get(id);
-    if (living !== undefined) upstream[id] = elementHash(living.doc, living.element);
-  }
-  const item = view.items.find((i) => i.path === path);
-  if (item !== undefined) {
-    // Work always depends on the dependency rules, cited or not.
-    for (const [id, living] of view.living.elements) {
-      if (id.startsWith("RULE-")) upstream[id] = elementHash(living.doc, living.element);
-    }
-    const feature = item.kind === "change" ? featureOf(view.items, item) : undefined;
-    if (feature !== undefined) upstream[`doc:${feature.path}`] = designHash(feature.doc);
-  }
-  return { hash: designHash(doc), upstream };
-}
-
-/** The current hash of one upstream key, or undefined when it no longer exists. */
-export function currentUpstreamHash(view: ProjectView, key: string): string | undefined {
-  if (key.startsWith("doc:")) {
-    const path = key.slice("doc:".length);
-    const item = view.items.find((i) => i.path === path);
-    return item === undefined ? undefined : designHash(item.doc);
-  }
-  const living = view.living.elements.get(key);
-  return living === undefined ? undefined : elementHash(living.doc, living.element);
-}

package/src/domain/approvals/rebase.ts

@@ -1,39 +0,0 @@
-import { elementHash } from "../hashing.ts";
-import type { MarkdownDoc } from "../markdown.ts";
-import { readDelta } from "../project/deltas.ts";
-import { approvalFolder, type ProjectView } from "../project/project_view.ts";
-import type { WorkItem } from "../project/work_items.ts";
-import { latestApproval } from "./records.ts";
-
-/**
- * Delta elements a feature or standalone change merged and hasn't changed since. The merge did
- * their job, so the living text is the one to keep: an edit there by a rethink, a realign or
- * another land asks nothing of the delta. One project's delta went stale this way, and every
- * later edit of an element its first change had merged forced a rebase of text with no work left in it.
- */
-export function settledIds(doc: MarkdownDoc, merged: Record<string, string>): Set<string> {
-  const settled = new Set<string>();
-  for (const entry of readDelta(doc).entries) {
-    for (const element of [entry.element, ...entry.scenarios]) {
-      if (merged[element.id] === elementHash(doc, element)) settled.add(element.id);
-    }
-  }
-  return settled;
-}
-
-/**
- * Elements the work's delta still changes whose living text moved since its last approval:
- * approving the delta as it stands would overwrite that edit. A change's own approval pins no delta.
- */
-export function rebaseNeeded(view: ProjectView, item: WorkItem): string[] {
-  if (item.kind === "change") return [];
-  const file = view.approvals.get(approvalFolder(view, item.path));
-  const previous = file === undefined ? undefined : latestApproval(file, item.path);
-  if (previous === undefined) return [];
-  const settled = settledIds(item.doc, file?.merged ?? {});
-  return [...readDelta(item.doc).ids].filter((id) => {
-    const living = view.living.elements.get(id);
-    const before = previous.upstream[id];
-    return !settled.has(id) && living !== undefined && before !== undefined && before !== elementHash(living.doc, living.element);
-  });
-}

package/src/domain/approvals/records.ts

@@ -1,50 +0,0 @@
-/** What `approvals.json` holds. Only the CLI writes it. */
-
-export interface ApprovalRecord {
-  /** Path of the approved document. */
-  artifact: string;
-  /** Design hash of the document when approved. */
-  hash: string;
-  /** Hash of each upstream element or document the approval depends on, by ID or `doc:<path>`. */
-  upstream: Record<string, string>;
-  approvedAt: string;
-  by: string;
-  /** Why the approval exists when no person gave it, such as a merge by `land`. */
-  basis?: string;
-}
-
-export interface ApprovalsFile {
-  version: 1;
-  approvals: ApprovalRecord[];
-  /** For a feature or standalone change: hash of each living element it merged, by ID. */
-  merged: Record<string, string>;
-}
-
-export function emptyApprovals(): ApprovalsFile {
-  return { version: 1, approvals: [], merged: {} };
-}
-
-export function parseApprovals(text: string | undefined): { file: ApprovalsFile; problem?: string } {
-  if (text === undefined) return { file: emptyApprovals() };
-  try {
-    const raw = JSON.parse(text) as Partial<ApprovalsFile>;
-    if (raw.version !== 1 || !Array.isArray(raw.approvals)) return { file: emptyApprovals(), problem: "approvals.json has an unknown format" };
-    return { file: { version: 1, approvals: raw.approvals, merged: raw.merged ?? {} } };
-  } catch {
-    return { file: emptyApprovals(), problem: "approvals.json is not valid JSON" };
-  }
-}
-
-export function serializeApprovals(file: ApprovalsFile): string {
-  return `${JSON.stringify(file, null, 2)}\n`;
-}
-
-/** The latest approval of an artifact, if any. */
-export function latestApproval(file: ApprovalsFile, artifact: string): ApprovalRecord | undefined {
-  return file.approvals.filter((record) => record.artifact === artifact).at(-1);
-}
-
-/** Replaces the artifact's approval: one current approval per artifact; history lives in the journal. */
-export function withApproval(file: ApprovalsFile, record: ApprovalRecord): ApprovalsFile {
-  return { ...file, approvals: [...file.approvals.filter((r) => r.artifact !== record.artifact), record] };
-}

package/src/domain/approvals/upstream_text.ts

@@ -1,36 +0,0 @@
-import { isStatusLine } from "../elements.ts";
-import { designHash, elementHash } from "../hashing.ts";
-import { parseMarkdown, type MarkdownDoc } from "../markdown.ts";
-import { buildLivingModel } from "../project/living_model.ts";
-import type { ProjectView } from "../project/project_view.ts";
-
-/** The document that holds an upstream key now: an element's living document, or the path of a `doc:` key. */
-export function upstreamPath(view: ProjectView, key: string): string | undefined {
-  if (key.startsWith("doc:")) return view.snapshot.has(key.slice("doc:".length)) ? key.slice("doc:".length) : undefined;
-  return view.living.elements.get(key)?.path;
-}
-
-/**
- * The design lines behind an upstream key in one version of the document at `path`, without the
- * managed blocks and status lines no hash covers. With `pinned`, only when they hash as pinned.
- */
-export function upstreamLines(key: string, path: string, text: string, pinned?: string): string[] | undefined {
-  if (key.startsWith("doc:")) {
-    const doc = parseMarkdown(text);
-    if (pinned !== undefined && designHash(doc) !== pinned) return undefined;
-    return designLines(doc, 0, doc.lines.length);
-  }
-  const living = buildLivingModel(new Map([[path, text]])).elements.get(key);
-  if (living === undefined) return undefined;
-  if (pinned !== undefined && elementHash(living.doc, living.element) !== pinned) return undefined;
-  return designLines(living.doc, living.element.start, living.element.end);
-}
-
-function designLines(doc: MarkdownDoc, start: number, end: number): string[] {
-  const lines: string[] = [];
-  for (let i = start; i < end; i++) {
-    const line = doc.lines[i] ?? "";
-    if (!doc.inManaged[i] && (doc.inFence[i] || !isStatusLine(line))) lines.push(line);
-  }
-  return lines;
-}

package/src/domain/architecture_sections.ts

@@ -1,23 +0,0 @@
-import type { Kind } from "./ids.ts";
-
-/** The `##` sections of architecture.md, in order, and the element kind each holds. */
-export const ARCHITECTURE_SECTIONS: ReadonlyArray<{ title: string; kind: Kind | null }> = [
-  { title: "Overview", kind: "VIEW" },
-  { title: "Bounded contexts", kind: "CTX" },
-  { title: "Domain model", kind: "ENT" },
-  { title: "Use cases", kind: "UC" },
-  { title: "Ports", kind: "PORT" },
-  { title: "Adapters", kind: "ADP" },
-  { title: "Flows", kind: "FLOW" },
-  { title: "Modules", kind: "MOD" },
-  { title: "Dependency rules", kind: "RULE" },
-  { title: "Cross-cutting concerns", kind: "XC" },
-  { title: "Decisions", kind: null },
-];
-
-export const ARCHITECTURE_KINDS: readonly Kind[] = ["VIEW", "CTX", "ENT", "UC", "PORT", "ADP", "FLOW", "MOD", "RULE", "XC"];
-export const SPEC_KINDS: readonly Kind[] = ["REQ", "SCN"];
-
-export function sectionForKind(kind: Kind): string | undefined {
-  return ARCHITECTURE_SECTIONS.find((section) => section.kind === kind)?.title;
-}

package/src/domain/check/decision_comments.ts

@@ -1,38 +0,0 @@
-import { findDecisionCitations, type DecisionCitation } from "../decision_citations.ts";
-
-const HASH_COMMENTS = new Set(["py", "rb", "sh", "bash", "zsh", "pl", "r", "ex", "exs", "jl", "nim", "cr", "ps1"]);
-const DASH_COMMENTS = new Set(["sql", "lua", "hs", "elm", "ada"]);
-
-/**
- * Decisions a source file's comments cite by number, such as `(D22)` or `(events D23)`. Each work
- * item numbers its decisions from D1 and is archived when it finishes, so a number in code points
- * at nothing a reader can find.
- */
-export function decisionCitationsInComments(path: string, text: string): DecisionCitation[] {
-  const comments = commentText(path, text.split("\n"));
-  return findDecisionCitations(comments, new Set());
-}
-
-/** Each line with everything but its comment blanked, so a citation's line number stays right. */
-function commentText(path: string, lines: string[]): string[] {
-  const extension = path.slice(path.lastIndexOf(".") + 1).toLowerCase();
-  if (HASH_COMMENTS.has(extension)) return lines.map((line) => after(line, /(^|\s)#/));
-  if (DASH_COMMENTS.has(extension)) return lines.map((line) => after(line, /--/));
-  let inBlock = false;
-  return lines.map((line) => {
-    if (inBlock) {
-      if (line.includes("*/")) inBlock = false;
-      return line;
-    }
-    const open = line.indexOf("/*");
-    if (open !== -1 && !line.includes("*/", open + 2)) inBlock = true;
-    const slash = line.indexOf("//");
-    const start = [open, slash].filter((at) => at !== -1).sort((a, b) => a - b)[0];
-    return start === undefined ? "" : line.slice(start);
-  });
-}
-
-function after(line: string, marker: RegExp): string {
-  const match = marker.exec(line);
-  return match === null ? "" : line.slice(match.index);
-}

package/src/domain/decision_citations.ts

@@ -1,62 +0,0 @@
-/**
- * Settled decisions are numbered `D<n>` within the document that records them: the architecture's
- * `## Decisions`, or one feature or change, which is archived when it finishes. A number cited
- * anywhere else either dangles or silently means another document's decision.
- */
-
-/** One citation of decisions by number, such as `D5`, `D5, D19` or `events D17`. */
-export interface DecisionCitation {
-  /** 0-based line. */
-  line: number;
-  text: string;
-  numbers: number[];
-  /** The work item named with it, as in `events D17` or `D1 of 02-links`. */
-  qualifier?: string;
-}
-
-const SLUG = "[a-z0-9]+(?:-[a-z0-9]+)*";
-const CITATION = new RegExp(`(?:(?<![\\w-])(${SLUG})\\s+)?(?<![\\w-])(D\\d+(?:\\s*(?:,|and)\\s*D\\d+)*)(?![\\w-])(?:\\s+of\\s+(${SLUG}))?`, "g");
-const DEFINITION = /^\s*- D(\d+):/;
-
-/**
- * Every citation of decisions by number in the lines given, skipping the `- D<n>:` that defines one
- * and anything inside backticks. `slugs` are the work items a citation may name.
- */
-export function findDecisionCitations(lines: readonly string[], slugs: ReadonlySet<string>, skip: (line: number) => boolean = () => false): DecisionCitation[] {
-  const citations: DecisionCitation[] = [];
-  lines.forEach((raw, line) => {
-    if (skip(line)) return;
-    const text = raw.replace(DEFINITION, (m) => " ".repeat(m.length)).replace(/`[^`]*`/g, (m) => " ".repeat(m.length));
-    for (const match of text.matchAll(CITATION)) {
-      const before = match[1] !== undefined && slugs.has(match[1]) ? match[1] : undefined;
-      const after = match[3] !== undefined && slugs.has(match[3]) ? match[3] : undefined;
-      const numbers = [...(match[2] ?? "").matchAll(/D(\d+)/g)].map((m) => Number(m[1]));
-      const qualifier = before ?? after;
-      const cited = qualifier === undefined ? (match[2] ?? "") : (match[0] ?? "").trim();
-      citations.push(qualifier === undefined ? { line, text: cited, numbers } : { line, text: cited, numbers, qualifier });
-    }
-  });
-  return citations;
-}
-
-/** The decisions a `## Decisions` section, or any lines, define as `- D<n>: ...`. */
-export function definedDecisions(lines: readonly string[]): Set<number> {
-  return new Set(lines.flatMap((line) => {
-    const match = DEFINITION.exec(line);
-    return match?.[1] === undefined ? [] : [Number(match[1])];
-  }));
-}
-
-/**
- * The names a citation may give a work item: a feature's slug with and without its date, and a
- * change's folder name, such as `events`, `2026-10-08-events` and `02-links`.
- */
-export function workItemSlugs(folderNames: Iterable<string>): Set<string> {
-  const slugs = new Set<string>();
-  for (const name of folderNames) {
-    slugs.add(name);
-    const undated = name.replace(/^\d{4}-\d{2}-\d{2}-/, "");
-    if (undated !== "") slugs.add(undated);
-  }
-  return slugs;
-}

package/src/domain/edits/agents_file.ts

@@ -1,58 +0,0 @@
-import { factsOf, statusOf } from "../elements.ts";
-import { findSection, parseMarkdown } from "../markdown.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;
-}
-
-/** The lines under `## Known pitfalls`, one per pitfall, which the feedback export carries back to Cruze. */
-export function knownPitfalls(text: string): string[] {
-  const doc = parseMarkdown(text);
-  const range = findSection(doc, "Known pitfalls");
-  if (range === null) return [];
-  return doc.lines.slice(range.start, range.end).filter((line) => line.startsWith("- ")).map((line) => line.slice(2).trim());
-}
-
-/**
- * The modules whose code exists: those built, and those a land built before a rethink set them
- * back to `planned` for a change to rebuild, since their directories are still there.
- */
-function builtModules(view: ProjectView): string[] {
-  const everBuilt = new Set(view.journal.filter((e) => e.event === "land").flatMap((e) => (Array.isArray(e["built"]) ? (e["built"] as unknown[]).map(String) : [])));
-  return [...view.living.elements.values()]
-    .filter(({ element, doc }) => element.kind === "MOD" && (statusOf(doc, element) === "built" || everBuilt.has(element.id)))
-    .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

@@ -1,60 +0,0 @@
-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(" | ")} |`;
-}