@printpractical/cruze 0.0.1

package/src/domain/status/next_step.ts

@@ -0,0 +1,119 @@
+import { evaluateApproval } from "../approvals/evaluate.ts";
+import { PATHS } from "../project/layout.ts";
+import { isPlanned, readChangesTable } from "../project/plan_parts.ts";
+import { readProgress } from "../project/progress.ts";
+import type { ProjectView } from "../project/project_view.ts";
+import { readRoadmapItems, readRoadmapStatus } from "../project/roadmap.ts";
+import { changesOf, featureOf, type WorkItem } from "../project/work_items.ts";
+import { isVerified } from "./verification.ts";
+import { activeChange } from "./work_status.ts";
+
+/** The Cruze step to run next, computed from the project's state and the current branch. */
+
+export type Step = "envision" | "architect" | "roadmap" | "plan" | "build" | "verify" | "land" | "rethink" | "switch-branch";
+
+export interface NextStep {
+  step: Step;
+  /** What the step works on: a feature or change ref, a roadmap slug, or a branch. */
+  target?: string;
+  reason: string;
+}
+
+export interface NextReport {
+  next: NextStep;
+  /** Other work that could proceed, such as changes waiting on their own branches. */
+  also: NextStep[];
+}
+
+export function nextSteps(view: ProjectView, branch: string | null): NextReport {
+  const project = projectStep(view);
+  if (project !== null) return { next: project, also: [] };
+  const active = activeChange(view, branch);
+  const inFlight = view.items.filter((item) => !item.archived && item.kind !== "change").flatMap((item) => itemSteps(view, item, branch));
+  const roadmap = roadmapStep(view);
+  const candidates = [...(active === undefined ? [] : [changeStep(view, active, branch)]), ...inFlight, ...(roadmap === null ? [] : [roadmap])];
+  const unique = candidates.filter((c, i) => candidates.findIndex((o) => o.step === c.step && o.target === c.target) === i);
+  const [next, ...also] = unique;
+  return { next: next ?? { step: "roadmap", reason: "every item on the roadmap has landed; close the release and plan the next" }, also };
+}
+
+/** The project documents come first: nothing else can proceed without them. */
+function projectStep(view: ProjectView): NextStep | null {
+  const docs: Array<{ path: string; missing: NextStep; unapproved: NextStep; changed: NextStep }> = [
+    {
+      path: PATHS.vision,
+      missing: { step: "envision", reason: "the project has no vision yet" },
+      unapproved: { step: "envision", reason: "finish the vision and approve it" },
+      changed: { step: "envision", reason: "the vision changed since its approval; review the change and approve it again" },
+    },
+    {
+      path: PATHS.architecture,
+      missing: { step: "architect", reason: "the project has no architecture yet" },
+      unapproved: { step: "architect", reason: "finish the architecture, walk through it and approve it" },
+      changed: { step: "rethink", target: "architecture", reason: "the architecture changed since its approval" },
+    },
+    {
+      path: PATHS.roadmap,
+      missing: { step: "architect", reason: "the project has no roadmap yet" },
+      unapproved: { step: "roadmap", reason: "approve the release ordering" },
+      changed: { step: "roadmap", reason: "the roadmap changed since its approval; approve the new ordering" },
+    },
+  ];
+  for (const doc of docs) {
+    if (!view.snapshot.has(doc.path)) return doc.missing;
+    const state = evaluateApproval(view, doc.path).state;
+    if (state === "unapproved") return doc.unapproved;
+    if (state !== "approved") return doc.changed;
+  }
+  return null;
+}
+
+function itemSteps(view: ProjectView, item: WorkItem, branch: string | null): NextStep[] {
+  if (item.kind === "standalone") return [changeStep(view, item, branch)];
+  const state = evaluateApproval(view, item.path);
+  if (readChangesTable(item.doc).length === 0) return [{ step: "architect", target: item.ref, reason: "the feature has no design or changes yet" }];
+  if (state.state === "unapproved") return [{ step: "architect", target: item.ref, reason: "review the feature's design, walk through it and approve it" }];
+  if (state.state !== "approved") return [{ step: "rethink", target: item.ref, reason: `the feature changed since its approval${state.changed.length > 0 ? ` (${state.changed.join(", ")})` : ""}` }];
+  const changes = changesOf(view.items, item);
+  const landed = new Set(changes.filter((c) => readProgress(c.doc).landed !== undefined).map((c) => c.folderName));
+  const steps: NextStep[] = [];
+  for (const row of readChangesTable(item.doc)) {
+    const change = changes.find((c) => c.folderName === row.change);
+    if (change !== undefined) {
+      if (!landed.has(row.change)) steps.push(changeStep(view, change, branch));
+    } else if (row.dependsOn.every((d) => landed.has(d))) {
+      steps.push({ step: "plan", target: `${item.ref}/${row.change}`, reason: "the next change of an approved feature, with its dependencies landed" });
+    }
+  }
+  return steps;
+}
+
+function changeStep(view: ProjectView, change: WorkItem, branch: string | null): NextStep {
+  const feature = featureOf(view.items, change);
+  const featureState = feature === undefined ? undefined : evaluateApproval(view, feature.path);
+  if (feature !== undefined && featureState !== undefined && featureState.state !== "approved") {
+    const why = featureState.changed.length > 0 ? ` (${featureState.changed.join(", ")})` : "";
+    return { step: "rethink", target: feature.ref, reason: `the feature of ${change.ref} changed since its approval${why}` };
+  }
+  const bound = readProgress(change.doc).branch;
+  const state = evaluateApproval(view, change.path);
+  if (!isPlanned(change.doc)) return { step: "plan", target: change.ref, reason: "the change is designed but has no test plan or tasks yet" };
+  if (state.state === "unapproved") return { step: "plan", target: change.ref, reason: "review the plan and approve it on the branch that will build it" };
+  if (state.state !== "approved") return { step: "rethink", target: change.ref, reason: `the change or something it cites changed since its approval${state.changed.length > 0 ? ` (${state.changed.join(", ")})` : ""}` };
+  if (bound !== undefined && bound !== branch) return { step: "switch-branch", target: bound, reason: `${change.ref} is built on branch ${bound}` };
+  const progress = readProgress(change.doc);
+  if ([...progress.tasks.values()].some((commit) => commit === null)) return { step: "build", target: change.ref, reason: "the change has open tasks" };
+  if (!isVerified(view.journal, change)) return { step: "verify", target: change.ref, reason: "every task is done; verify the change" };
+  return { step: "land", target: change.ref, reason: "the change is verified and accepted" };
+}
+
+/** The first roadmap item that hasn't started and whose blockers have all landed. */
+function roadmapStep(view: ProjectView): NextStep | null {
+  const text = view.snapshot.get(PATHS.roadmap);
+  if (text === undefined) return null;
+  const status = new Map(readRoadmapStatus(text).map((row) => [row.slug, row.state]));
+  const item = readRoadmapItems(text).find((i) => !status.has(i.slug) && i.blockedBy.every((b) => status.get(b) === "landed"));
+  if (item === undefined) return null;
+  if (item.kind === "feature") return { step: "envision", target: item.slug, reason: "the next roadmap feature; skip to architect when its requirements are settled" };
+  return { step: "architect", target: item.slug, reason: "the next roadmap change; design it as a tweak" };
+}

package/src/domain/status/verification.ts

@@ -0,0 +1,16 @@
+import type { JournalEntry } from "../journal.ts";
+import type { WorkItem } from "../project/work_items.ts";
+
+/**
+ * Whether the user accepted a change at verify. The latest verification recorded for the change
+ * counts. A later approval keeps it only when the change's own design is unchanged, as when it is
+ * re-approved because something upstream moved; a changed plan means verifying again.
+ */
+export function isVerified(journal: JournalEntry[], change: WorkItem): boolean {
+  const byTime = (a: JournalEntry, b: JournalEntry): number => a.at.localeCompare(b.at);
+  const verification = journal.filter((e) => e.event === "verification" && e["item"] === change.ref).sort(byTime).at(-1);
+  if (verification?.["result"] !== "accepted") return false;
+  const approvals = journal.filter((e) => e.event === "approve" && e["artifact"] === change.path && e["basis"] === undefined).sort(byTime);
+  const verifiedHash = approvals.filter((e) => e.at < verification.at).at(-1)?.["hash"];
+  return approvals.filter((e) => e.at > verification.at).every((e) => e["hash"] === verifiedHash);
+}

package/src/domain/status/work_status.ts

@@ -0,0 +1,101 @@
+import { evaluateApproval, type ApprovalStatus } from "../approvals/evaluate.ts";
+import { findIds } from "../ids.ts";
+import { PATHS } from "../project/layout.ts";
+import { readDelta } from "../project/deltas.ts";
+import { readScope } from "../project/plan_parts.ts";
+import { readProgress } from "../project/progress.ts";
+import type { ProjectView } from "../project/project_view.ts";
+import { changesOf, featureOf, type WorkItem } from "../project/work_items.ts";
+
+export interface ChangeStatus {
+  ref: string;
+  path: string;
+  approval: ApprovalStatus;
+  branch?: string;
+  tasksDone: number;
+  tasksTotal: number;
+  /** When and in which commit the change landed, once it has. */
+  landed?: string;
+}
+
+export interface FeatureStatus {
+  ref: string;
+  path: string;
+  approval: ApprovalStatus;
+  changes: ChangeStatus[];
+}
+
+export interface ProjectStatus {
+  documents: ApprovalStatus[];
+  features: FeatureStatus[];
+  standalone: ChangeStatus[];
+  /** The change bound to the current branch, if any. */
+  active?: string;
+}
+
+export function projectStatus(view: ProjectView, branch: string | null): ProjectStatus {
+  const documents = [PATHS.vision, PATHS.architecture, PATHS.roadmap].filter((p) => view.snapshot.has(p)).map((p) => evaluateApproval(view, p));
+  const active = view.items.filter((item) => !item.archived);
+  const features = active
+    .filter((item) => item.kind === "feature")
+    .map((feature) => ({
+      ref: feature.ref,
+      path: feature.path,
+      approval: evaluateApproval(view, feature.path),
+      changes: changesOf(view.items, feature).map((change) => changeStatus(view, change)),
+    }));
+  const standalone = active.filter((item) => item.kind === "standalone").map((change) => changeStatus(view, change));
+  const status: ProjectStatus = { documents, features, standalone };
+  const bound = activeChange(view, branch);
+  if (bound !== undefined) status.active = bound.ref;
+  return status;
+}
+
+export function activeChange(view: ProjectView, branch: string | null): WorkItem | undefined {
+  if (branch === null) return undefined;
+  return view.items.find((item) => {
+    const progress = readProgress(item.doc);
+    return !item.archived && item.kind !== "feature" && progress.landed === undefined && progress.branch === branch;
+  });
+}
+
+function changeStatus(view: ProjectView, change: WorkItem): ChangeStatus {
+  const progress = readProgress(change.doc);
+  const status: ChangeStatus = {
+    ref: change.ref,
+    path: change.path,
+    approval: evaluateApproval(view, change.path),
+    tasksDone: [...progress.tasks.values()].filter((commit) => commit !== null).length,
+    tasksTotal: progress.tasks.size,
+  };
+  if (progress.branch !== undefined) status.branch = progress.branch;
+  if (progress.landed !== undefined) status.landed = progress.landed;
+  return status;
+}
+
+/** Why building may not start on this branch; empty when the build gate passes. */
+export function buildGateReasons(view: ProjectView, branch: string | null): string[] {
+  const change = activeChange(view, branch);
+  if (change === undefined) return [`no change is bound to branch ${branch ?? "(none)"}; approve a planned change on this branch first`];
+  const required = [change.path];
+  const feature = featureOf(view.items, change);
+  if (feature !== undefined) required.push(feature.path);
+  if (view.snapshot.has(PATHS.architecture)) required.push(PATHS.architecture);
+  return required.flatMap((path) => {
+    const status = evaluateApproval(view, path);
+    if (status.state === "approved") return [];
+    const detail = status.changed.length > 0 ? `: ${status.changed.join(", ")} changed` : status.unjournaled === true ? ": the approval has no journal entry" : "";
+    return [`${path} is ${status.state}${detail}`];
+  });
+}
+
+/** The elements a change touches: its scope plus every ID its documents cite. */
+export function touchedIds(view: ProjectView, change: WorkItem): Set<string> {
+  const feature = featureOf(view.items, change);
+  const scope = readScope(change.doc);
+  const ids = new Set([...(scope?.delivers ?? []), ...(scope?.builds ?? []), ...(scope?.removes ?? [])]);
+  const deltaDoc = feature?.doc ?? change.doc;
+  for (const id of readDelta(deltaDoc).ids) ids.add(id);
+  for (const id of findIds(change.doc.lines.join("\n"))) ids.add(id);
+  return new Set([...ids].filter((id) => !id.startsWith("RULE-")));
+}

package/src/domain/trace.ts

@@ -0,0 +1,44 @@
+import { headingElements, statusOf } from "./elements.ts";
+import { findIds } from "./ids.ts";
+import { PATHS } from "./project/layout.ts";
+import type { ProjectView } from "./project/project_view.ts";
+import { readScope } from "./project/plan_parts.ts";
+import { readDelta } from "./project/deltas.ts";
+import type { WorkItem } from "./project/work_items.ts";
+
+export interface TraceReport {
+  /** Scenarios that must have a test, and the test files that carry each one. */
+  scenarios: Array<{ id: string; tests: string[] }>;
+  missing: string[];
+  /** Scenario IDs in tests that no living doc or active delta defines. */
+  unknown: Array<{ id: string; path: string; line: number }>;
+}
+
+/**
+ * Links scenarios to the tests that prove them. For a change: every scenario it delivers.
+ * For the whole project: every built scenario in the living specs.
+ */
+export function traceScenarios(view: ProjectView, tests: ReadonlyMap<string, string>, change?: WorkItem): TraceReport {
+  const required = change === undefined ? builtScenarios(view) : (readScope(change.doc)?.delivers ?? []).filter((id) => id.startsWith("SCN-"));
+  const known = new Set([...view.living.elements.keys()]);
+  for (const item of view.items.filter((i) => !i.archived)) for (const id of readDelta(item.doc).ids) known.add(id);
+
+  const carriers = new Map<string, string[]>();
+  const unknown: TraceReport["unknown"] = [];
+  for (const [path, text] of tests) {
+    text.split("\n").forEach((line, index) => {
+      for (const id of findIds(line).filter((id) => id.startsWith("SCN-"))) {
+        carriers.set(id, [...new Set([...(carriers.get(id) ?? []), path])]);
+        if (!known.has(id)) unknown.push({ id, path, line: index + 1 });
+      }
+    });
+  }
+  const scenarios = required.map((id) => ({ id, tests: carriers.get(id) ?? [] }));
+  return { scenarios, missing: scenarios.filter((s) => s.tests.length === 0).map((s) => s.id), unknown };
+}
+
+function builtScenarios(view: ProjectView): string[] {
+  return [...view.living.docs]
+    .filter(([path]) => path.startsWith(`${PATHS.specsDir}/`))
+    .flatMap(([, doc]) => headingElements(doc).filter((e) => e.kind === "SCN" && statusOf(doc, e) === "built").map((e) => e.id));
+}

package/src/domain/validation/delta_rules.ts

@@ -0,0 +1,79 @@
+import { ARCHITECTURE_KINDS } from "../architecture_sections.ts";
+import { scopeOf } from "../ids.ts";
+import { specPath } from "../project/layout.ts";
+import { orphanDeltaElements, readDelta, type Delta } from "../project/deltas.ts";
+import type { ProjectView } from "../project/project_view.ts";
+import type { WorkItem } from "../project/work_items.ts";
+import { elementProblems } from "./element_rules.ts";
+import { error, type Problem } from "./problem.ts";
+
+/** Merge records use this key for a spec file a delta created. */
+export function capabilityKey(capability: string): string {
+  return `CAPABILITY-${capability}`;
+}
+
+/** Marks an element a landed change removed. */
+export const REMOVED_MARK = "removed";
+
+/** Rules for the spec and architecture deltas of a feature or standalone change. */
+export function deltaProblems(view: ProjectView, item: WorkItem): Problem[] {
+  const { path, doc } = item;
+  const delta = readDelta(doc);
+  const merged = view.approvals.get(item.folder)?.merged ?? {};
+  const problems: Problem[] = [];
+
+  for (const orphan of orphanDeltaElements(doc)) {
+    problems.push(error(path, orphan.start, "delta-shape", `${orphan.id} must sit under an ADDED, MODIFIED or REMOVED requirement`));
+  }
+  for (const { element, section, scenarios } of delta.entries) {
+    const allowed = section === "spec" ? element.kind === "REQ" : ARCHITECTURE_KINDS.includes(element.kind);
+    if (!allowed) problems.push(error(path, element.start, "delta-shape", `${element.id} does not belong in the ${section} delta`));
+    problems.push(...elementProblems(path, doc, element));
+    for (const scenario of scenarios) {
+      problems.push(...elementProblems(path, doc, scenario));
+      if (scopeOf(scenario.id) !== scopeOf(element.id)) {
+        problems.push(error(path, scenario.start, "id-scope", `${scenario.id} must share its requirement's scope`));
+      }
+      problems.push(...opProblems(view, path, scenario.id, "ADDED", scenario.start, merged, element.op === "ADDED"));
+    }
+    problems.push(...opProblems(view, path, element.id, element.op ?? "ADDED", element.start, merged, false));
+    if (element.kind === "REQ" && element.op === "ADDED") problems.push(...capabilityProblems(view, item, delta, element.id, element.start));
+  }
+  for (const op of delta.capabilities) {
+    if (view.snapshot.has(specPath(op.capability)) && merged[capabilityKey(op.capability)] === undefined) {
+      problems.push(error(path, op.start, "capability-exists", `capability ${op.capability} already has ${specPath(op.capability)}`));
+    }
+  }
+  return problems;
+}
+
+function opProblems(
+  view: ProjectView,
+  path: string,
+  id: string,
+  op: "ADDED" | "MODIFIED" | "REMOVED",
+  line: number,
+  merged: Record<string, string>,
+  underAddedRequirement: boolean,
+): Problem[] {
+  const exists = view.living.elements.has(id);
+  const mergedHere = merged[id] !== undefined;
+  if (view.retired.has(id)) return [error(path, line, "retired-id", `${id} was removed earlier and can never be reused`)];
+  if (op === "ADDED" && exists && !mergedHere) {
+    // A scenario under a MODIFIED requirement may already exist; only a new requirement's scenarios must be new.
+    if (!id.startsWith("SCN-") || underAddedRequirement) return [error(path, line, "delta-op", `ADDED ${id} already exists in the living docs`)];
+  }
+  if ((op === "MODIFIED" || op === "REMOVED") && !exists && merged[id] !== REMOVED_MARK) {
+    return [error(path, line, "delta-op", `${op} ${id} does not exist in the living docs`)];
+  }
+  return [];
+}
+
+function capabilityProblems(view: ProjectView, item: WorkItem, delta: Delta, id: string, line: number): Problem[] {
+  const capability = scopeOf(id);
+  if (capability === undefined) return [];
+  const hasFile = view.snapshot.has(specPath(capability));
+  const addsFile = delta.capabilities.some((op) => op.capability === capability);
+  if (hasFile || addsFile) return [];
+  return [error(item.path, line, "capability-missing", `${id} needs ${specPath(capability)}, or an "ADDED CAPABILITY ${capability}" operation`)];
+}

package/src/domain/validation/element_rules.ts

@@ -0,0 +1,99 @@
+import { factsOf, type Element } from "../elements.ts";
+import { findIds, scopeOf, SCOPED_KINDS, type Kind } from "../ids.ts";
+import type { MarkdownDoc } from "../markdown.ts";
+import { error, type Problem } from "./problem.ts";
+
+/** Rules for a single element's body, shared by living documents and deltas. */
+
+const REQUIRED_FACTS: Partial<Record<Kind, string[]>> = {
+  CTX: ["Purpose"],
+  ENT: ["Kind", "Module", "File"],
+  UC: ["Input", "Output", "Errors", "Uses", "Module", "File"],
+  PORT: ["Direction", "Operations", "Module", "File"],
+  ADP: ["Technology", "Module", "File"],
+  FLOW: ["Elements"],
+  MOD: ["Path", "Layer"],
+};
+
+const ALLOWED_VALUES: Record<string, { kinds: Kind[]; values: string[] }> = {
+  Kind: { kinds: ["ENT"], values: ["aggregate", "entity", "value", "service", "policy", "event"] },
+  Direction: { kinds: ["PORT"], values: ["driven", "driving"] },
+  Layer: { kinds: ["MOD"], values: ["domain", "application", "adapter", "composition"] },
+};
+
+export function elementProblems(path: string, doc: MarkdownDoc, element: Element): Problem[] {
+  const problems: Problem[] = [];
+  if (SCOPED_KINDS.includes(element.kind) && scopeOf(element.id) === undefined) {
+    problems.push(error(path, element.start, "id-scope", `${element.id} needs a scope: ${element.kind}-<scope>.<name>`));
+  }
+  if (element.op === "REMOVED") return [...problems, ...removedProblems(path, doc, element)];
+
+  const facts = factsOf(doc, element);
+  for (const key of REQUIRED_FACTS[element.kind] ?? []) {
+    if (!facts.has(key)) problems.push(error(path, element.start, "required-fact", `${element.id} is missing "- ${key}:"`));
+  }
+  if (element.kind === "ADP" && !facts.has("Implements") && !facts.has("Drives")) {
+    problems.push(error(path, element.start, "required-fact", `${element.id} needs "- Implements:" or "- Drives:"`));
+  }
+  for (const [key, rule] of Object.entries(ALLOWED_VALUES)) {
+    const value = facts.get(key)?.[0];
+    if (rule.kinds.includes(element.kind) && value !== undefined && !rule.values.includes(value)) {
+      problems.push(error(path, element.start, "fact-value", `${element.id} ${key} must be one of ${rule.values.join(", ")}`));
+    }
+  }
+  const module = facts.get("Module")?.[0];
+  if (module !== undefined && !findIds(module).some((id) => id.startsWith("MOD-"))) {
+    problems.push(error(path, element.start, "fact-value", `${element.id} Module must name a MOD element`));
+  }
+  if (element.kind === "FLOW" && !bodyText(doc, element).includes("sequenceDiagram")) {
+    problems.push(error(path, element.start, "flow-diagram", `${element.id} needs a Mermaid sequenceDiagram`));
+  }
+  if (element.kind === "REQ") problems.push(...requirementProblems(path, doc, element));
+  if (element.kind === "SCN") problems.push(...scenarioProblems(path, doc, element));
+  return problems;
+}
+
+function removedProblems(path: string, doc: MarkdownDoc, element: Element): Problem[] {
+  const facts = factsOf(doc, element);
+  const problems: Problem[] = [];
+  if (!facts.has("Reason")) problems.push(error(path, element.start, "removed-reason", `REMOVED ${element.id} needs "- Reason:"`));
+  if (element.kind === "REQ" && !facts.has("Migration")) {
+    problems.push(error(path, element.start, "removed-reason", `REMOVED ${element.id} needs "- Migration:"`));
+  }
+  return problems;
+}
+
+function requirementProblems(path: string, doc: MarkdownDoc, element: Element): Problem[] {
+  const problems: Problem[] = [];
+  const ownBody = ownLines(doc, element).join("\n");
+  if (!/\b(SHALL|MUST)\b/.test(ownBody)) problems.push(error(path, element.start, "req-keyword", `${element.id} must state SHALL or MUST`));
+  const hasScenario = doc.headings.some((h) => h.line > element.start && h.line < element.end && h.level === element.level + 1 && h.text.startsWith("SCN-"));
+  if (!hasScenario) problems.push(error(path, element.start, "req-scenario", `${element.id} needs at least one scenario`));
+  return problems;
+}
+
+function scenarioProblems(path: string, doc: MarkdownDoc, element: Element): Problem[] {
+  const steps = ownLines(doc, element)
+    .map((line) => /^- (GIVEN|WHEN|THEN|AND) /.exec(line)?.[1])
+    .filter((step) => step !== undefined);
+  const order = steps.filter((step) => step !== "AND").join(" ");
+  if (!/^(GIVEN )*WHEN( THEN)+$/.test(order)) {
+    return [error(path, element.start, "scenario-steps", `${element.id} needs GIVEN steps (optional), one WHEN, then one or more THEN`)];
+  }
+  if (steps[0] === "AND") return [error(path, element.start, "scenario-steps", `${element.id} cannot start with AND`)];
+  return [];
+}
+
+/** The element's lines before its first nested heading, without the heading itself. */
+function ownLines(doc: MarkdownDoc, element: Element): string[] {
+  const lines: string[] = [];
+  for (let i = element.start + 1; i < element.end; i++) {
+    if (!doc.inFence[i] && /^#{1,6} /.test(doc.lines[i] ?? "")) break;
+    lines.push(doc.lines[i] ?? "");
+  }
+  return lines;
+}
+
+function bodyText(doc: MarkdownDoc, element: Element): string {
+  return doc.lines.slice(element.start, element.end).join("\n");
+}

package/src/domain/validation/living_rules.ts

@@ -0,0 +1,97 @@
+import { ARCHITECTURE_KINDS, sectionForKind } from "../architecture_sections.ts";
+import { headingElements, statusOf, type Element } from "../elements.ts";
+import { findIds, scopeOf, STATUS_KINDS } from "../ids.ts";
+import type { MarkdownDoc } from "../markdown.ts";
+import { PATHS } from "../project/layout.ts";
+import type { ProjectView } from "../project/project_view.ts";
+import { elementProblems } from "./element_rules.ts";
+import { error, warning, type Problem } from "./problem.ts";
+
+/** Rules for the living docs: vision, architecture, specs, ADRs and the IDs they cite. */
+export function livingProblems(view: ProjectView): Problem[] {
+  const problems: Problem[] = [];
+  for (const { id, places } of view.living.duplicates) {
+    problems.push(error(places[0]?.split(":")[0] ?? "", undefined, "duplicate-id", `${id} is defined more than once: ${places.join(", ")}`));
+  }
+  for (const [path, doc] of view.living.docs) {
+    problems.push(...malformedIdHeadings(path, doc));
+    if (path === PATHS.architecture) problems.push(...architectureProblems(path, doc, everApproved(view, path)));
+    else if (path.startsWith(`${PATHS.specsDir}/`)) problems.push(...specProblems(path, doc));
+    else if (path.startsWith(`${PATHS.adrDir}/`)) problems.push(...adrProblems(path, doc));
+  }
+  for (const path of [...view.living.docs.keys(), PATHS.roadmap]) {
+    const text = view.snapshot.get(path);
+    if (text === undefined) continue;
+    for (const id of findIds(text)) {
+      if (!view.living.elements.has(id)) problems.push(error(path, lineOf(text, id), "unknown-id", `${id} is cited but not defined in the living docs`));
+    }
+  }
+  return problems;
+}
+
+/** A heading shaped like `<KIND>-...: Title` whose ID breaks the grammar. */
+export function malformedIdHeadings(path: string, doc: MarkdownDoc): Problem[] {
+  return doc.headings.flatMap((heading) => {
+    const match = /^(?:(?:ADDED|MODIFIED|REMOVED) )?([A-Z]{2,5}-\S*):\s/.exec(heading.text);
+    if (match?.[1] === undefined || findIds(match[1])[0] === match[1]) return [];
+    return [error(path, heading.line, "malformed-id", `"${match[1]}" is not a valid ID`)];
+  });
+}
+
+/** Statuses are stamped by the first approval, so their absence before it is expected. */
+function everApproved(view: ProjectView, path: string): boolean {
+  return [...view.approvals.values()].some((file) => file.approvals.some((record) => record.artifact === path));
+}
+
+function architectureProblems(path: string, doc: MarkdownDoc, approved: boolean): Problem[] {
+  const problems: Problem[] = [];
+  for (const element of headingElements(doc)) {
+    const section = [...doc.headings].reverse().find((h) => h.level === 2 && h.line < element.start);
+    if (!ARCHITECTURE_KINDS.includes(element.kind)) {
+      problems.push(error(path, element.start, "misplaced-element", `${element.id} does not belong in the architecture`));
+    } else if (element.kind !== "VIEW" && section?.text !== sectionForKind(element.kind)) {
+      problems.push(error(path, element.start, "misplaced-element", `${element.id} belongs under "## ${sectionForKind(element.kind)}"`));
+    }
+    problems.push(...elementProblems(path, doc, element), ...(approved ? statusProblems(path, doc, element) : []));
+  }
+  return problems;
+}
+
+function specProblems(path: string, doc: MarkdownDoc): Problem[] {
+  const capability = path.slice(path.lastIndexOf("/") + 1, -".md".length);
+  const problems: Problem[] = [];
+  const elements = headingElements(doc);
+  for (const element of elements) {
+    const expectedLevel = element.kind === "REQ" ? 2 : element.kind === "SCN" ? 3 : 0;
+    if (expectedLevel === 0) problems.push(error(path, element.start, "misplaced-element", `${element.id} does not belong in a spec`));
+    else if (element.level !== expectedLevel) problems.push(error(path, element.start, "heading-level", `${element.id} must be a level ${expectedLevel} heading`));
+    if (scopeOf(element.id) !== undefined && scopeOf(element.id) !== capability) {
+      problems.push(error(path, element.start, "id-scope", `${element.id} must use the scope "${capability}", the capability of this file`));
+    }
+    problems.push(...elementProblems(path, doc, element), ...statusProblems(path, doc, element));
+  }
+  return problems;
+}
+
+function adrProblems(path: string, doc: MarkdownDoc): Problem[] {
+  const text = doc.lines.join("\n");
+  return ["Status", "Date"]
+    .filter((key) => !new RegExp(`^- ${key}: `, "m").test(text))
+    .map((key) => error(path, undefined, "adr-fact", `the ADR is missing "- ${key}:"`));
+}
+
+function statusProblems(path: string, doc: MarkdownDoc, element: Element): Problem[] {
+  const status = statusOf(doc, element);
+  if (STATUS_KINDS.includes(element.kind) && status === undefined) {
+    return [warning(path, element.start, "missing-status", `${element.id} has no status yet; approving the document adds it`)];
+  }
+  if (!STATUS_KINDS.includes(element.kind) && status !== undefined) {
+    return [error(path, element.start, "unexpected-status", `${element.id} is not a kind that carries a status`)];
+  }
+  return [];
+}
+
+export function lineOf(text: string, needle: string): number | undefined {
+  const index = text.indexOf(needle);
+  return index === -1 ? undefined : text.slice(0, index).split("\n").length - 1;
+}