@printpractical/cruze 0.0.9 → 0.0.11

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/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[];
 }
@@ -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/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,6 +20,14 @@ 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.

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,16 +24,16 @@ const OPTIONAL_FIELDS: Record<string, string[]> = {
   rethink: ["missed_by"],
   review: ["nits", "checked_by"],
   disposition: ["decided"],
-  verification: ["back_to"],
+  verification: ["back_to", "commit"],
 };
 
 /** The workflow steps and checks that find or miss a problem, so a retro can count them. */
 export const STEPS = ["envision", "architect", "research", "design-review", "walkthrough", "plan", "plan-review", "build", "code-review", "verify", "land", "realign", "improve", "validate", "check", "user"];
 
 export const FIELD_VALUES: Record<string, string[]> = {
-  level: ["task", "change", "feature", "architecture", "vision"],
+  level: ["task", "detail", "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"],
@@ -40,6 +41,7 @@ export const FIELD_VALUES: Record<string, string[]> = {
   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. */
@@ -92,7 +94,7 @@ export function recordedEventProblems(event: string, fields: Record<string, stri
     if (allowed !== undefined && !allowed.includes(value)) problems.push(`${field} must be one of ${allowed.join(", ")}`);
     if (COUNT_FIELDS.includes(field) && !/^\d+$/.test(value)) problems.push(`${field} must be a whole number`);
   }
-  if (event === "checks" && fields["commit"] !== undefined && !/^[0-9a-f]{7,40}$/.test(fields["commit"])) {
+  if ((event === "checks" || event === "verification") && fields["commit"] !== undefined && !/^[0-9a-f]{7,40}$/.test(fields["commit"])) {
     problems.push("commit must be a commit hash, such as the output of git rev-parse --short HEAD");
   }
   if (event === "disposition" && fields["decided"] === "agent" && fields["disposition"] !== "fixed") {

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) };
+}

package/src/domain/project/living_model.ts

@@ -1,4 +1,5 @@
 import { headingElements, rowElements, type Element } from "../elements.ts";
+import { VISION_KINDS } from "../ids.ts";
 import { parseMarkdown, type MarkdownDoc } from "../markdown.ts";
 import { PATHS, childFiles, type Snapshot } from "./layout.ts";
 
@@ -49,6 +50,6 @@ function elementsOf(path: string, doc: MarkdownDoc): Element[] {
   if (path.startsWith(`${PATHS.adrDir}/`)) {
     return [{ id: adrId(path), kind: "ADR", title: doc.headings[0]?.text ?? "", form: "heading", level: 1, start: 0, end: doc.lines.length }];
   }
-  if (path === PATHS.vision) return rowElements(doc).filter((element) => element.kind === "GOAL");
+  if (path === PATHS.vision) return rowElements(doc).filter((element) => VISION_KINDS.includes(element.kind));
   return headingElements(doc);
 }

package/src/domain/project/notes.ts

@@ -0,0 +1,74 @@
+import { findSection, parseMarkdown } from "../markdown.ts";
+import { tablesIn } from "../markdown_tables.ts";
+import { PATHS } from "./layout.ts";
+import type { Snapshot } from "./layout.ts";
+
+/**
+ * Notes under `.cruze/notes/`: what the user brought, what explore captured, the evidence research
+ * gathered, and the hand-off envision wrote from them. Each says what it is about, so a step reads
+ * the notes for its work rather than guessing from file names: one project held 21 notes, and a
+ * 9,500-word seed whose design sections no step was told to read.
+ */
+
+export const NOTE_KINDS = ["input", "intake", "explore", "research"] as const;
+export type NoteKind = (typeof NOTE_KINDS)[number];
+
+/** The step an intake row hands a part to, besides a feature on the map. */
+export const HANDOFF_STEPS = ["vision", "architect", "roadmap", "user"] as const;
+
+export interface HandoffRow {
+  /** The part of the input, by its heading or a short quote. */
+  part: string;
+  /** Where it is: a note path and heading, or "below" for text saved in the intake note. */
+  source: string;
+  /** A step from HANDOFF_STEPS, or the slug of the feature that takes it up. */
+  goesTo: string;
+  /** `open` until the step that takes it up settles it with the user: `settled` or `dropped`. */
+  status: string;
+}
+
+export interface Note {
+  path: string;
+  title: string;
+  kind?: string;
+  /** `project`, feature slugs, or context and capability names. */
+  about: string[];
+  handoff: HandoffRow[];
+}
+
+export function readNotes(snapshot: Snapshot): Note[] {
+  return [...snapshot.keys()]
+    .filter((path) => path.startsWith(`${PATHS.notesDir}/`) && path.endsWith(".md"))
+    .sort()
+    .map((path) => readNote(path, snapshot.get(path) ?? ""));
+}
+
+function readNote(path: string, text: string): Note {
+  const doc = parseMarkdown(text);
+  const title = doc.headings.find((h) => h.level === 1)?.text ?? path.slice(path.lastIndexOf("/") + 1, -".md".length);
+  const firstSection = doc.headings.find((h) => h.level === 2)?.line ?? doc.lines.length;
+  const fact = (key: string): string | undefined =>
+    doc.lines.slice(0, firstSection).map((line) => new RegExp(`^- ${key}: (.+)$`).exec(line)?.[1]?.trim()).find((v) => v !== undefined);
+  const about = (fact("About") ?? "").split(",").map((a) => a.trim()).filter((a) => a !== "");
+  const kind = fact("Kind");
+  const section = findSection(doc, "Hand-off");
+  const rows = section === null ? [] : (tablesIn(doc.lines, doc.inFence, section.start, section.end)[0]?.rows ?? []);
+  const handoff = rows.map(({ cells }) => ({ part: cells[0] ?? "", source: cells[1] ?? "", goesTo: (cells[2] ?? "").replace(/`/g, ""), status: cells[3] ?? "open" }));
+  return { path, title, about, handoff, ...(kind === undefined ? {} : { kind }) };
+}
+
+export interface NotesFor {
+  /** Notes about one of the targets, or about the whole project when it is a target. */
+  notes: Note[];
+  /** Intake rows handed to one of the targets, with the intake note that holds them. */
+  handoffs: Array<HandoffRow & { note: string }>;
+}
+
+/** The notes and hand-off rows for a piece of work, named by its targets: `project`, a step, a feature slug or a context. */
+export function notesFor(notes: Note[], targets: string[]): NotesFor {
+  const wanted = new Set(targets);
+  return {
+    notes: notes.filter((note) => note.about.some((a) => wanted.has(a))),
+    handoffs: notes.flatMap((note) => note.handoff.filter((row) => wanted.has(row.goesTo)).map((row) => ({ ...row, note: note.path }))),
+  };
+}

package/src/domain/skill_budget.ts

@@ -0,0 +1,36 @@
+import type { SkillFiles } from "./skill_links.ts";
+
+/**
+ * The words one instruction file may hold. A longer file holds material only some runs need, so it
+ * splits by branch, as `docs/contributing/writing-skills.md` says, and each run reads only its part.
+ */
+export const MAX_FILE_WORDS = 2100;
+
+/**
+ * The words agents may read across the whole bundle. Every retro adds rules, and between 0.0.1 and
+ * 0.0.10 the skills grew by half while nothing was removed. Lower this when text is cut. Raising it
+ * is the maintainer's decision, with the reason in the commit that raises it.
+ */
+export const BUNDLE_WORD_BUDGET = 44800;
+
+/** Data the CLI reads or renders, rather than instructions an agent reads. */
+const NOT_INSTRUCTIONS = /(^|\/)(templates|notes)\//;
+
+export function wordCount(text: string): number {
+  return text.split(/\s+/).filter((word) => word !== "").length;
+}
+
+/** Instruction files over their limit, and the bundle when it is over its budget. */
+export function budgetProblems(skills: SkillFiles[]): string[] {
+  const files = skills.flatMap((skill) =>
+    skill.files.filter((f) => f.path.endsWith(".md") && !NOT_INSTRUCTIONS.test(f.path)).map((f) => ({ path: `${skill.folder}/${f.path}`, words: wordCount(f.text) })),
+  );
+  const problems = files
+    .filter((f) => f.words > MAX_FILE_WORDS)
+    .map((f) => `${f.path}: ${f.words} words, over ${MAX_FILE_WORDS}; move what only some runs need into a sibling file`);
+  const total = files.reduce((sum, f) => sum + f.words, 0);
+  if (total > BUNDLE_WORD_BUDGET) {
+    problems.push(`the skills hold ${total} words, over the budget of ${BUNDLE_WORD_BUDGET}; cut or merge text to make room, or raise the budget with the reason in the commit`);
+  }
+  return problems;
+}