@printpractical/cruze 0.0.1

package/dist/domain/skill_links.js

@@ -0,0 +1,103 @@
+import { posix } from "node:path";
+import { SKILL_FILE, SKILL_PREFIX } from "./skill.js";
+
+/**
+ * Pointers between bundled skill files. A skill reaches its own sibling files
+ * through relative Markdown links, and other Cruze skills through their
+ * installed path, `.agents/skills/cruze-<name>/<file>`.
+ */
+
+                             
+                 
+                                          
+ 
+
+                                    
+                                                           
+                
+                                                                       
+               
+ 
+
+const INSTALLED_REF = /\.agents\/skills\/(cruze-[a-z0-9]+(?:-[a-z0-9]+)*)\/([\w./-]*\w)/g;
+const MARKDOWN_LINK = /\]\(([^)\s]+)\)/g;
+
+/** Every file of another Cruze skill that a text names by its installed path, in order, without repeats. */
+export function installedSkillRefs(text        )                      {
+  const seen = new Set        ();
+  const refs                      = [];
+  for (const match of text.matchAll(INSTALLED_REF)) {
+    const ref = { skill: match[1] ?? "", path: match[2] ?? "" };
+    const key = `${ref.skill}/${ref.path}`;
+    if (!seen.has(key)) refs.push(ref);
+    seen.add(key);
+  }
+  return refs;
+}
+
+/** Targets of the relative Markdown links outside code fences, without any `#fragment`. */
+export function relativeLinks(text        )           {
+  const targets           = [];
+  let inFence = false;
+  for (const line of text.split("\n")) {
+    if (/^\s*(```|~~~)/.test(line)) inFence = !inFence;
+    if (inFence) continue;
+    for (const match of line.matchAll(MARKDOWN_LINK)) {
+      const target = (match[1] ?? "").split("#")[0] ?? "";
+      if (target !== "" && !/^[a-z][a-z0-9+.-]*:/i.test(target)) targets.push(target);
+    }
+  }
+  return targets;
+}
+
+/**
+ * Every broken pointer in the bundled skills: a link to a missing sibling, a link
+ * that leaves its skill, an installed path to a missing file, and a Markdown file
+ * that its skill's SKILL.md can't reach through links.
+ */
+export function skillLinkProblems(skills              )           {
+  const exists = new Set(skills.flatMap((skill) => skill.files.map((file) => `${skill.folder}/${file.path}`)));
+  const problems           = [];
+  for (const skill of skills) {
+    for (const file of skill.files.filter((f) => f.path.endsWith(".md"))) {
+      const where = `${skill.folder}/${file.path}`;
+      for (const target of relativeLinks(file.text)) {
+        const resolved = resolveLink(file.path, target);
+        if (resolved === null) problems.push(`${where}: link ${target} leaves the skill; name another skill by its installed path`);
+        else if (!exists.has(`${skill.folder}/${resolved}`)) problems.push(`${where}: link ${target} points to a missing file`);
+      }
+      for (const ref of installedSkillRefs(file.text)) {
+        const folder = ref.skill.slice(SKILL_PREFIX.length);
+        if (!exists.has(`${folder}/${ref.path}`)) problems.push(`${where}: .agents/skills/${ref.skill}/${ref.path} is not in the bundle`);
+      }
+    }
+    const reachable = reachableFromSkillFile(skill);
+    for (const file of skill.files.filter((f) => f.path.endsWith(".md") && !reachable.has(f.path))) {
+      problems.push(`${skill.folder}/${file.path}: no link reaches it from ${SKILL_FILE}`);
+    }
+  }
+  return problems;
+}
+
+/** A link's path inside the skill folder, or null when it leaves the folder. */
+function resolveLink(fromPath        , target        )                {
+  const resolved = posix.normalize(posix.join(posix.dirname(fromPath), target));
+  return resolved.startsWith("../") || resolved === ".." ? null : resolved;
+}
+
+function reachableFromSkillFile(skill            )              {
+  const texts = new Map(skill.files.map((file) => [file.path, file.text]));
+  const reached = new Set        ();
+  const queue = [SKILL_FILE];
+  while (queue.length > 0) {
+    const path = queue.shift() ?? "";
+    const text = texts.get(path);
+    if (reached.has(path) || text === undefined) continue;
+    reached.add(path);
+    for (const target of relativeLinks(text)) {
+      const resolved = resolveLink(path, target);
+      if (resolved !== null) queue.push(resolved);
+    }
+  }
+  return reached;
+}

package/dist/domain/status/next_step.js

@@ -0,0 +1,119 @@
+import { evaluateApproval } from "../approvals/evaluate.js";
+import { PATHS } from "../project/layout.js";
+import { isPlanned, readChangesTable } from "../project/plan_parts.js";
+import { readProgress } from "../project/progress.js";
+                                                              
+import { readRoadmapItems, readRoadmapStatus } from "../project/roadmap.js";
+import { changesOf, featureOf,               } from "../project/work_items.js";
+import { isVerified } from "./verification.js";
+import { activeChange } from "./work_status.js";
+
+/** The Cruze step to run next, computed from the project's state and the current branch. */
+
+                                                                                                                             
+
+                           
+             
+                                                                                      
+                  
+                 
+ 
+
+                             
+                 
+                                                                                      
+                   
+ 
+
+export function nextSteps(view             , branch               )             {
+  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             )                  {
+  const docs                                                                                      = [
+    {
+      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             , item          , branch               )             {
+  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             = [];
+  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             , change          , branch               )           {
+  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             )                  {
+  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/dist/domain/status/verification.js

@@ -0,0 +1,16 @@
+                                                  
+                                                         
+
+/**
+ * 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                , change          )          {
+  const byTime = (a              , b              )         => 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/dist/domain/status/work_status.js

@@ -0,0 +1,101 @@
+import { evaluateApproval,                     } from "../approvals/evaluate.js";
+import { findIds } from "../ids.js";
+import { PATHS } from "../project/layout.js";
+import { readDelta } from "../project/deltas.js";
+import { readScope } from "../project/plan_parts.js";
+import { readProgress } from "../project/progress.js";
+                                                              
+import { changesOf, featureOf,               } from "../project/work_items.js";
+
+                               
+              
+               
+                           
+                  
+                    
+                     
+                                                                 
+                  
+ 
+
+                                
+              
+               
+                           
+                          
+ 
+
+                                
+                              
+                            
+                             
+                                                        
+                  
+ 
+
+export function projectStatus(view             , branch               )                {
+  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                = { documents, features, standalone };
+  const bound = activeChange(view, branch);
+  if (bound !== undefined) status.active = bound.ref;
+  return status;
+}
+
+export function activeChange(view             , branch               )                       {
+  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             , change          )               {
+  const progress = readProgress(change.doc);
+  const status               = {
+    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             , branch               )           {
+  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             , change          )              {
+  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/dist/domain/trace.js

@@ -0,0 +1,44 @@
+import { headingElements, statusOf } from "./elements.js";
+import { findIds } from "./ids.js";
+import { PATHS } from "./project/layout.js";
+                                                             
+import { readScope } from "./project/plan_parts.js";
+import { readDelta } from "./project/deltas.js";
+                                                        
+
+                              
+                                                                                 
+                                                    
+                    
+                                                                          
+                                                             
+ 
+
+/**
+ * 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             , tests                             , change           )              {
+  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                  ();
+  const 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             )           {
+  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/dist/domain/validation/delta_rules.js

@@ -0,0 +1,79 @@
+import { ARCHITECTURE_KINDS } from "../architecture_sections.js";
+import { scopeOf } from "../ids.js";
+import { specPath } from "../project/layout.js";
+import { orphanDeltaElements, readDelta,            } from "../project/deltas.js";
+                                                              
+                                                         
+import { elementProblems } from "./element_rules.js";
+import { error,              } from "./problem.js";
+
+/** Merge records use this key for a spec file a delta created. */
+export function capabilityKey(capability        )         {
+  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             , item          )            {
+  const { path, doc } = item;
+  const delta = readDelta(doc);
+  const merged = view.approvals.get(item.folder)?.merged ?? {};
+  const problems            = [];
+
+  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             ,
+  path        ,
+  id        ,
+  op                                  ,
+  line        ,
+  merged                        ,
+  underAddedRequirement         ,
+)            {
+  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             , item          , delta       , id        , line        )            {
+  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/dist/domain/validation/element_rules.js

@@ -0,0 +1,99 @@
+import { factsOf,              } from "../elements.js";
+import { findIds, scopeOf, SCOPED_KINDS,           } from "../ids.js";
+                                                  
+import { error,              } from "./problem.js";
+
+/** Rules for a single element's body, shared by living documents and deltas. */
+
+const REQUIRED_FACTS                                  = {
+  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                                                      = {
+  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        , doc             , element         )            {
+  const problems            = [];
+  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        , doc             , element         )            {
+  const facts = factsOf(doc, element);
+  const problems            = [];
+  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        , doc             , element         )            {
+  const problems            = [];
+  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        , doc             , element         )            {
+  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             , element         )           {
+  const lines           = [];
+  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             , element         )         {
+  return doc.lines.slice(element.start, element.end).join("\n");
+}

package/dist/domain/validation/living_rules.js

@@ -0,0 +1,97 @@
+import { ARCHITECTURE_KINDS, sectionForKind } from "../architecture_sections.js";
+import { headingElements, statusOf,              } from "../elements.js";
+import { findIds, scopeOf, STATUS_KINDS } from "../ids.js";
+                                                  
+import { PATHS } from "../project/layout.js";
+                                                              
+import { elementProblems } from "./element_rules.js";
+import { error, warning,              } from "./problem.js";
+
+/** Rules for the living docs: vision, architecture, specs, ADRs and the IDs they cite. */
+export function livingProblems(view             )            {
+  const problems            = [];
+  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        , doc             )            {
+  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             , path        )          {
+  return [...view.approvals.values()].some((file) => file.approvals.some((record) => record.artifact === path));
+}
+
+function architectureProblems(path        , doc             , approved         )            {
+  const problems            = [];
+  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        , doc             )            {
+  const capability = path.slice(path.lastIndexOf("/") + 1, -".md".length);
+  const problems            = [];
+  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        , doc             )            {
+  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        , doc             , element         )            {
+  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        , needle        )                     {
+  const index = text.indexOf(needle);
+  return index === -1 ? undefined : text.slice(0, index).split("\n").length - 1;
+}