@printpractical/cruze 0.0.8 → 0.0.10

package/src/domain/approvals/rebase.ts

@@ -0,0 +1,39 @@
+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/upstream_text.ts

@@ -0,0 +1,36 @@
+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/check/budget_text.ts

@@ -1,24 +1,61 @@
 /**
  * The part of a source file its budgets measure. Budgets apply to source, not tests, so a Rust
- * file's `#[cfg(test)]` modules are left out: rustfmt closes a top-level module with `}` in column 0.
+ * file's test-only modules are left out: rustfmt closes a top-level module with `}` in column 0.
+ * A module is test-only when its `cfg` needs `test`, as `#[cfg(test)]` or
+ * `#[cfg(all(test, feature = "schema"))]` do; other attributes may sit between the two.
  */
 export function budgetedText(path: string, text: string): string {
   if (!path.endsWith(".rs")) return text;
   const lines = text.split("\n");
   const kept: string[] = [];
   for (let i = 0; i < lines.length; i++) {
-    const item = lines[i + 1] ?? "";
-    if (lines[i]?.trim() !== "#[cfg(test)]" || !/^(?:pub(?:\([^)]*\))?\s+)?mod\s+\w+\s*[{;]/.test(item)) {
+    const start = testModuleStart(lines, i);
+    if (start === null) {
       kept.push(lines[i] ?? "");
       continue;
     }
-    if (item.trimEnd().endsWith(";")) {
-      i += 1;
+    if ((lines[start] ?? "").trimEnd().endsWith(";")) {
+      i = start;
       continue;
     }
-    let end = i + 2;
+    let end = start + 1;
     while (end < lines.length && lines[end] !== "}") end++;
     i = end;
   }
   return kept.join("\n");
 }
+
+/** The line of the `mod` a test-only `cfg` at `index` gates, or null when it gates no module. */
+function testModuleStart(lines: string[], index: number): number | null {
+  if (!needsTest(lines[index]?.trim() ?? "")) return null;
+  let next = index + 1;
+  while (/^\s*#\[/.test(lines[next] ?? "")) next++;
+  return /^(?:pub(?:\([^)]*\))?\s+)?mod\s+\w+\s*[{;]/.test(lines[next] ?? "") ? next : null;
+}
+
+function needsTest(attribute: string): boolean {
+  const predicate = /^#\[cfg\((.*)\)\]$/.exec(attribute)?.[1]?.trim();
+  if (predicate === undefined) return false;
+  if (predicate === "test") return true;
+  const all = /^all\((.*)\)$/.exec(predicate)?.[1];
+  return all !== undefined && topLevelArguments(all).includes("test");
+}
+
+/** Splits `a, b(c, d), e` at its top-level commas. */
+function topLevelArguments(text: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let current = "";
+  for (const char of text) {
+    if (char === "," && depth === 0) {
+      parts.push(current.trim());
+      current = "";
+      continue;
+    }
+    if (char === "(") depth++;
+    if (char === ")") depth--;
+    current += char;
+  }
+  parts.push(current.trim());
+  return parts;
+}

package/src/domain/check/check_source.ts

@@ -1,13 +1,14 @@
 import type { CruzeConfig, Layer } from "../config.ts";
 import { matchesAny } from "../glob.ts";
 import { budgetedText } from "./budget_text.ts";
+import { decisionCitationsInComments } from "./decision_comments.ts";
 import { importsOf, resolveImport } from "./imports.ts";
 import { countTypes } from "./type_count.ts";
 
 export interface CheckFinding {
   path: string;
   line?: number;
-  rule: "layer" | "max-lines" | "max-types" | "outside-module-map" | "no-layer" | "test-placement";
+  rule: "layer" | "max-lines" | "max-types" | "outside-module-map" | "no-layer" | "test-placement" | "decision-citation";
   message: string;
   /** Layer violations always fail; the rest fail in CI unless excepted. */
   severity: "error" | "warning";
@@ -21,6 +22,8 @@ export interface CheckInput {
   sources: ReadonlyMap<string, string>;
   /** Paths of the MOD elements in the architecture; files outside all of them are flagged. */
   modulePaths: string[];
+  /** Test files outside config.source, by path: only their comments are checked. */
+  tests?: ReadonlyMap<string, string>;
   /** Check only these files, when given; imports still resolve against every source. */
   only?: string[];
 }
@@ -55,11 +58,11 @@ export function checkSource(input: CheckInput): CheckFinding[] {
     const lines = budgeted.split("\n").length - (budgeted.endsWith("\n") ? 1 : 0);
     if (!excepted && lines > config.check.maxLines) {
       const measured = budgeted === text ? "" : ", not counting its inline tests";
-      findings.push({ path, rule: "max-lines", severity: "warning", message: `${lines} lines${measured}, over the budget of ${config.check.maxLines}; split it by responsibility` });
+      findings.push({ path, rule: "max-lines", severity: "warning", message: `${lines} lines${measured}, over the budget of ${config.check.maxLines}; split it if it holds a second responsibility, or list it under check.exceptions` });
     }
     const types = countTypes(path, budgeted);
     if (!excepted && types !== null && types > config.check.maxTypes) {
-      findings.push({ path, rule: "max-types", severity: "warning", message: `${types} top-level types, over the budget of ${config.check.maxTypes}` });
+      findings.push({ path, rule: "max-types", severity: "warning", message: `${types} top-level types, over the budget of ${config.check.maxTypes}; split it if it holds a second responsibility, or list it under check.exceptions` });
     }
     if (!excepted && isRustTestFileInSource(path)) {
       findings.push({ path, rule: "test-placement", severity: "warning", message: "Rust tests that leave their inline module go in the crate's tests/ directory, not under src/" });
@@ -67,10 +70,24 @@ export function checkSource(input: CheckInput): CheckFinding[] {
     if (modulePaths.length > 0 && !insideModuleMap(path, modulePaths)) {
       findings.push({ path, rule: "outside-module-map", severity: "warning", message: "the file is outside every module in the architecture's module map" });
     }
+    findings.push(...decisionFindings(path, text));
+  }
+  for (const [path, text] of input.tests ?? []) {
+    if (!sources.has(path) && (input.only === undefined || input.only.includes(path))) findings.push(...decisionFindings(path, text));
   }
   return findings;
 }
 
+function decisionFindings(path: string, text: string): CheckFinding[] {
+  return decisionCitationsInComments(path, text).map((citation) => ({
+    path,
+    line: citation.line + 1,
+    rule: "decision-citation",
+    severity: "warning",
+    message: `the comment cites ${citation.text}, a decision number a reader of the code can't follow; say what was decided, or cite the element or ADR that holds it`,
+  }));
+}
+
 /** Whether a module's Path covers the file: a directory path ending in `/` covers everything under it, any other names one file. */
 export function insideModuleMap(path: string, modulePaths: string[]): boolean {
   return modulePaths.some((module) => (module.endsWith("/") ? path.startsWith(module) : path === module));

package/src/domain/check/decision_comments.ts

@@ -0,0 +1,38 @@
+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/config.ts

@@ -26,6 +26,8 @@ export interface CruzeConfig {
   review: { command?: string[]; decide: ReviewDecide };
   /** The size band of a change, so each one is worth its own plan, review and verify. */
   changes: ChangeLimits;
+  /** External documents the design must comply with, such as a protocol specification, each with what it governs. */
+  references: Array<{ path: string; use: string }>;
 }
 
 /** Which review findings the user decides: only the exceptions, or every one. */
@@ -132,6 +134,15 @@ export function parseConfig(text: string): ConfigResult {
     }),
   };
 
+  const references = (Array.isArray(root["references"]) ? root["references"] : root["references"] === undefined ? [] : [null]).flatMap((entry: unknown, i: number) => {
+    const record = asRecord(entry);
+    if (typeof record?.["path"] !== "string" || record["path"].trim() === "" || typeof record["use"] !== "string" || record["use"].trim() === "") {
+      problems.push(`references[${i}] needs a path and a non-empty use`);
+      return [];
+    }
+    return [{ path: record["path"], use: record["use"] }];
+  });
+
   const config: CruzeConfig = {
     version: 1,
     ...(typeof cruze === "string" && cruze.trim() !== "" ? { cruze } : {}),
@@ -148,6 +159,7 @@ export function parseConfig(text: string): ConfigResult {
       decide: decide === "all" ? "all" : "exceptions",
     },
     changes,
+    references,
   };
   return { config, problems };
 }

package/src/domain/decision_citations.ts

@@ -0,0 +1,62 @@
+/**
+ * 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,4 +1,5 @@
 import { factsOf, statusOf } from "../elements.ts";
+import { findSection, parseMarkdown } from "../markdown.ts";
 import type { ProjectView } from "../project/project_view.ts";
 
 /**
@@ -19,9 +20,22 @@ export function renderAgentsFile(text: string, view: ProjectView): string {
   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")
+    .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] ?? ""}\``));

package/src/domain/ids.ts

@@ -1,8 +1,10 @@
 /** Element IDs: `<KIND>-<name>` or `<KIND>-<scope>.<name>`, named and never reused. */
 
-export const KINDS = ["GOAL", "CTX", "ENT", "UC", "PORT", "ADP", "FLOW", "MOD", "RULE", "VIEW", "XC", "REQ", "SCN", "ADR"] as const;
+export const KINDS = ["GOAL", "PRINCIPLE", "LATER", "CTX", "ENT", "UC", "PORT", "ADP", "FLOW", "MOD", "RULE", "VIEW", "XC", "REQ", "SCN", "ADR"] as const;
 export type Kind = (typeof KINDS)[number];
 
+/** Kinds of the vision's row elements: goals, the principles every design follows, and what must stay possible later. */
+export const VISION_KINDS: readonly Kind[] = ["GOAL", "PRINCIPLE", "LATER"];
 /** Kinds that describe code, and so carry a managed planned/built status. */
 export const CODE_KINDS: readonly Kind[] = ["ENT", "UC", "PORT", "ADP", "FLOW", "MOD"];
 /** Kinds whose elements carry a managed status: code kinds and scenarios. */

package/src/domain/journal.ts

@@ -16,6 +16,7 @@ export const RECORDED_EVENTS: Record<string, string[]> = {
   bug: ["summary", "cause"],
   verification: ["result", "summary"],
   checks: ["commit"],
+  lesson: ["summary", "instead", "step"],
 };
 
 /** Fields an event may carry beyond its required ones, checked when present. A defect rethink must say which step missed it. */
@@ -23,6 +24,7 @@ const OPTIONAL_FIELDS: Record<string, string[]> = {
   rethink: ["missed_by"],
   review: ["nits", "checked_by"],
   disposition: ["decided"],
+  verification: ["back_to"],
 };
 
 /** The workflow steps and checks that find or miss a problem, so a retro can count them. */
@@ -31,15 +33,26 @@ export const STEPS = ["envision", "architect", "research", "design-review", "wal
 export const FIELD_VALUES: Record<string, string[]> = {
   level: ["task", "change", "feature", "architecture", "vision"],
   kind: ["defect", "discovery"],
-  disposition: ["fixed", "waived", "deferred", "rejected"],
+  disposition: ["fixed", "waived", "deferred", "rejected", "rethink"],
   decided: ["agent", "user"],
   review: ["design", "plan", "code", "realign", "improve"],
   result: ["accepted", "sent-back"],
+  back_to: ["build", "rethink"],
   checked_by: ["agent", "reviewer"],
   found_by: STEPS,
   missed_by: STEPS,
+  step: STEPS,
 };
 
+/** A defect rethink must say which step missed it, and a sent-back verification where the change goes back to. */
+function conditionallyRequired(event: string, fields: Record<string, string>): string[] {
+  if (event === "rethink" && fields["kind"] === "defect") return ["missed_by"];
+  if (event === "verification" && fields["result"] === "sent-back") return ["back_to"];
+  return [];
+}
+
+const CONDITION_NOTES: Record<string, string> = { missed_by: " for a defect", back_to: " when the change is sent back" };
+
 /** Fields recorded as numbers rather than text. */
 const COUNT_FIELDS = ["round", "blockers", "concerns", "nits"];
 
@@ -71,8 +84,8 @@ export function serializeEntry(entry: JournalEntry): string {
 export function recordedEventProblems(event: string, fields: Record<string, string>): string[] {
   const required = RECORDED_EVENTS[event];
   if (required === undefined) return [`unknown event "${event}"; recordable events: ${Object.keys(RECORDED_EVENTS).join(", ")}`];
-  const needed = event === "rethink" && fields["kind"] === "defect" ? [...required, "missed_by"] : required;
-  const problems = needed.filter((field) => (fields[field] ?? "").trim() === "").map((field) => `${event} needs ${field}${field === "missed_by" ? " for a defect" : ""}`);
+  const needed = [...required, ...conditionallyRequired(event, fields)];
+  const problems = needed.filter((field) => (fields[field] ?? "").trim() === "").map((field) => `${event} needs ${field}${CONDITION_NOTES[field] ?? ""}`);
   const known = [...required, ...(OPTIONAL_FIELDS[event] ?? [])];
   for (const field of known) {
     const value = fields[field];

package/src/domain/land/merge_plan.ts

@@ -1,3 +1,4 @@
+import { settledIds } from "../approvals/rebase.ts";
 import { sectionForKind } from "../architecture_sections.ts";
 import { CruzeError } from "../cruze_error.ts";
 import { setStatus } from "../edits/status_lines.ts";
@@ -26,7 +27,8 @@ export interface MergePlan {
 /**
  * Merges a change's work into the living docs. The first change of a feature to land merges
  * the whole delta; elements it doesn't build arrive as planned, and later changes flip what
- * they build to built. Text is replaced only when nobody else changed it since this work merged it.
+ * they build to built. Text is replaced only when nobody else changed it since this work merged it,
+ * and an element merged and unchanged in the delta since keeps its living text, whoever edited it.
  */
 export function planMerge(view: ProjectView, change: WorkItem, source: WorkItem): MergePlan {
   const scope = readScope(change.doc);
@@ -36,6 +38,7 @@ export function planMerge(view: ProjectView, change: WorkItem, source: WorkItem)
   const files = new Map<string, string>();
   const text = (path: string): string => files.get(path) ?? view.snapshot.get(path) ?? "";
   const plan: MergePlan = { files, merged, mergedIds: [], built: [], removed: [] };
+  const settled = settledIds(source.doc, merged);
 
   for (const op of delta.capabilities) {
     const key = capabilityKey(op.capability);
@@ -56,8 +59,10 @@ export function planMerge(view: ProjectView, change: WorkItem, source: WorkItem)
       }
       continue;
     }
-    mergeEntry(view, source, entry, path, text, files, merged, plan);
+    const kept = settled.has(id) && view.living.elements.has(id);
+    if (!kept) mergeEntry(view, source, entry, path, text, files, merged, plan);
     for (const target of [entry.element, ...entry.scenarios].filter((e) => STATUS_KINDS.includes(e.kind))) {
+      if (kept && !inScope.has(target.id)) continue;
       files.set(path, setStatus(text(path), target.id, statusAfterMerge(view, source, target, inScope)));
       if (inScope.has(target.id)) plan.built.push(target.id);
     }

package/src/domain/line_diff.ts

@@ -0,0 +1,56 @@
+/**
+ * A line diff of two texts as unified-diff lines: "  " for a kept line, "- " removed, "+ " added.
+ * Only the changes and `context` kept lines around each are shown; "…" marks the lines left out.
+ */
+export function lineDiff(before: string[], after: string[], context = 2): string[] {
+  const ops = diffOps(before, after);
+  const near = new Set<number>();
+  ops.forEach((op, i) => {
+    if (op.kind === " ") return;
+    for (let j = Math.max(0, i - context); j <= Math.min(ops.length - 1, i + context); j++) near.add(j);
+  });
+  const lines: string[] = [];
+  let skipped = false;
+  ops.forEach((op, i) => {
+    if (!near.has(i)) {
+      skipped = true;
+      return;
+    }
+    if (skipped && lines.length > 0) lines.push("…");
+    skipped = false;
+    lines.push(`${op.kind} ${op.line}`);
+  });
+  if (skipped && lines.length > 0) lines.push("…");
+  return lines;
+}
+
+interface Op {
+  kind: " " | "-" | "+";
+  line: string;
+}
+
+/** The edit script of a longest common subsequence: documents are small enough for the quadratic table. */
+function diffOps(a: string[], b: string[]): Op[] {
+  const width = b.length + 1;
+  const table = new Int32Array((a.length + 1) * width);
+  const at = (i: number, j: number): number => table[i * width + j] ?? 0;
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      table[i * width + j] = a[i] === b[j] ? at(i + 1, j + 1) + 1 : Math.max(at(i + 1, j), at(i, j + 1));
+    }
+  }
+  const ops: Op[] = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length || j < b.length) {
+    if (i < a.length && j < b.length && a[i] === b[j]) {
+      ops.push({ kind: " ", line: a[i++] ?? "" });
+      j++;
+    } else if (j >= b.length || (i < a.length && at(i + 1, j) >= at(i, j + 1))) {
+      ops.push({ kind: "-", line: a[i++] ?? "" });
+    } else {
+      ops.push({ kind: "+", line: b[j++] ?? "" });
+    }
+  }
+  return ops;
+}

package/src/domain/project/element_lookup.ts

@@ -0,0 +1,124 @@
+import { elementLines, factsOf, statusOf, type DeltaOp, type Element, type Status } from "../elements.ts";
+import { findIds, kindOf, scopeOf, type Kind } from "../ids.ts";
+import type { MarkdownDoc } from "../markdown.ts";
+import { readDelta } from "./deltas.ts";
+import { PATHS } from "./layout.ts";
+import type { ProjectView } from "./project_view.ts";
+import type { ShownElement } from "./scope_view.ts";
+import type { WorkItem } from "./work_items.ts";
+
+/**
+ * Elements one at a time, and an index of all of them, so a step that needs a few elements of a
+ * large architecture fetches those instead of reading the whole file. One project's architecture
+ * held 52k words, and a single architect run read all of it to find what it would extend.
+ */
+
+export interface IndexEntry {
+  id: string;
+  title: string;
+  kind: Kind;
+  /** The living document that holds it, or the work item that adds it. */
+  source: string;
+  status?: Status;
+  /** Where its code lives: the `Module` it names, or a module's `Path`. */
+  place?: string;
+  /** For a requirement, how many scenarios it holds. */
+  scenarios?: number;
+  /** Work in flight whose delta changes or removes it. */
+  changedBy: string[];
+  /** Set when only in-flight work defines it so far. */
+  addedBy?: string;
+}
+
+export interface ElementIndex {
+  /** The words in the living architecture and specs, so a step can judge whether to read them whole. */
+  words: { architecture: number; specs: number };
+  entries: IndexEntry[];
+}
+
+const DOCS_INDEXED = (path: string): boolean => path === PATHS.architecture || path.startsWith(`${PATHS.specsDir}/`);
+
+/**
+ * Every element of the living architecture and specs, one entry each, with what in-flight work
+ * adds. Without a scope, scenarios are counted under their requirement; with a context or
+ * capability name, only its elements are listed, scenarios included.
+ */
+export function elementIndex(view: ProjectView, scope?: string): ElementIndex {
+  const inScope = (id: string): boolean => scope === undefined || scopeOf(id) === scope || id === `CTX-${scope}`;
+  const entries: IndexEntry[] = [];
+  const byId = new Map<string, IndexEntry>();
+  for (const living of view.living.elements.values()) {
+    if (!DOCS_INDEXED(living.path) || !inScope(living.id) || (scope === undefined && kindOf(living.id) === "SCN")) continue;
+    const entry = entryOf(living.id, living.element, living.doc, living.path);
+    if (kindOf(living.id) === "REQ") entry.scenarios = scenarioCount(view, living.id);
+    entries.push(entry);
+    byId.set(entry.id, entry);
+  }
+  for (const item of inFlight(view)) {
+    for (const element of deltaElements(item)) {
+      if (!inScope(element.element.id) || (scope === undefined && element.element.kind === "SCN")) continue;
+      const known = byId.get(element.element.id);
+      if (known !== undefined) {
+        known.changedBy.push(item.ref);
+        continue;
+      }
+      const added = { ...entryOf(element.element.id, element.element, item.doc, item.ref), addedBy: item.ref };
+      entries.push(added);
+      byId.set(added.id, added);
+    }
+  }
+  return { words: livingWords(view), entries };
+}
+
+/** The bodies of the named elements: the living one, then each in-flight delta that changes it. */
+export function lookupElements(view: ProjectView, ids: string[]): { elements: ShownElement[]; missing: string[] } {
+  const elements: ShownElement[] = [];
+  const missing: string[] = [];
+  for (const id of ids) {
+    const found: ShownElement[] = [];
+    const living = view.living.elements.get(id);
+    if (living !== undefined) found.push(shown(living.doc, living.element, living.path));
+    for (const item of inFlight(view)) {
+      const delta = deltaElements(item).find((d) => d.element.id === id);
+      if (delta !== undefined) found.push({ ...shown(item.doc, delta.element, item.path), ...(delta.op === undefined ? {} : { op: delta.op }) });
+    }
+    if (found.length === 0) missing.push(id);
+    elements.push(...found);
+  }
+  return { elements, missing };
+}
+
+function entryOf(id: string, element: Element, doc: MarkdownDoc, source: string): IndexEntry {
+  const facts = factsOf(doc, element);
+  const place = (facts.get("Module") ?? []).flatMap(findIds)[0] ?? (facts.get("Path") ?? [])[0];
+  const status = statusOf(doc, element);
+  return { id, title: element.title, kind: kindOf(id), source, changedBy: [], ...(status === undefined ? {} : { status }), ...(place === undefined ? {} : { place }) };
+}
+
+function shown(doc: MarkdownDoc, element: Element, path: string): ShownElement {
+  return { id: element.id, title: element.title, source: `${path}:${element.start + 1}`, body: elementLines(doc, element) };
+}
+
+function inFlight(view: ProjectView): WorkItem[] {
+  return view.items.filter((item) => !item.archived && item.kind !== "change");
+}
+
+/** Each element a work item's delta defines or changes, scenarios under a requirement included. */
+function deltaElements(item: WorkItem): Array<{ element: Element; op?: DeltaOp }> {
+  return readDelta(item.doc).entries.flatMap((entry) => [
+    { element: entry.element, ...(entry.element.op === undefined ? {} : { op: entry.element.op }) },
+    ...entry.scenarios.map((scenario) => ({ element: scenario })),
+  ]);
+}
+
+function scenarioCount(view: ProjectView, requirement: string): number {
+  const living = view.living.elements.get(requirement);
+  if (living === undefined) return 0;
+  return [...view.living.elements.values()].filter((e) => e.path === living.path && e.id.startsWith("SCN-") && e.element.start > living.element.start && e.element.start < living.element.end).length;
+}
+
+function livingWords(view: ProjectView): { architecture: number; specs: number } {
+  const words = (path: string): number => (view.snapshot.get(path) ?? "").split(/\s+/).filter((w) => w !== "").length;
+  const specs = [...view.living.docs.keys()].filter((path) => path.startsWith(`${PATHS.specsDir}/`));
+  return { architecture: words(PATHS.architecture), specs: specs.reduce((sum, path) => sum + words(path), 0) };
+}