@printpractical/cruze 0.0.8 → 0.0.10

package/dist/app/use_cases/project_status.js

@@ -1,4 +1,5 @@
 import { CruzeError } from "../../domain/cruze_error.js";
+import { PATHS } from "../../domain/project/layout.js";
 import { readProgress } from "../../domain/project/progress.js";
 import { buildProjectView } from "../../domain/project/project_view.js";
 import { findWorkItem,               } from "../../domain/project/work_items.js";
@@ -59,7 +60,9 @@ export async function findOverlaps(deps             , ref         )
   const mine = touchedIds(view, change);
   const overlaps            = [];
   for (const other of await deps.repository.otherBranches()) {
-    const theirs = buildProjectView(new Map([...view.snapshot].filter(([p]) => p.startsWith("docs/")).concat([...(await deps.repository.filesOnBranch(other, ".cruze"))])));
+    // Landed work is archived, so a branch's work in flight is under features/ and changes/ only.
+    const inFlight = [...(await deps.repository.filesOnBranch(other, PATHS.featuresDir)), ...(await deps.repository.filesOnBranch(other, PATHS.changesDir))];
+    const theirs = buildProjectView(new Map([...view.snapshot].filter(([p]) => p.startsWith("docs/")).concat(inFlight)));
     // Work in flight on a branch is the change bound to it that hasn't landed, there or here.
     const boundThere = theirs.items.filter((i) => {
       const bound = readProgress(i.doc).branch;

package/dist/app/use_cases/run_review.js

@@ -1,6 +1,7 @@
 import { CruzeError } from "../../domain/cruze_error.js";
 import { resolveArtifact } from "../../domain/project/artifact_ref.js";
-import { featureOf } from "../../domain/project/work_items.js";
+import { isPlanned } from "../../domain/project/plan_parts.js";
+import { featureOf,               } from "../../domain/project/work_items.js";
                                                             
 import { loadView,                  } from "../project_context.js";
 
@@ -44,7 +45,7 @@ export async function runReview(deps                                       , req
     context.push(`Under review: ${item?.ref ?? path} (\`${path}\`)`);
     const feature = item === undefined ? undefined : featureOf(view.items, item);
     if (feature !== undefined) context.push(`Its feature: \`${feature.path}\``);
-    if (role === "design-reviewer" && item !== undefined && item.kind !== "feature") context.push("This is a change's plan: review it with the plan rubric.");
+    if (role === "design-reviewer" && item !== undefined) context.push(rubricLine(item));
   } else {
     context.push("Under review: the project documents the role lists for project scope");
   }
@@ -83,3 +84,10 @@ async function bundledRole(deps             , role      )                  {
   if (file === undefined) throw new CruzeError("role-missing", `the ${role} role is not installed; run cruze install`);
   return file.text;
 }
+
+/** A design reviewer reads one rubric: the plan rubric for a planned change, the design rubric otherwise. */
+function rubricLine(item          )         {
+  return item.kind !== "feature" && isPlanned(item.doc)
+    ? "This is a change's plan: review it against `.agents/skills/cruze-roles/plan-rubric.md`."
+    : "This is a design: review it against `.agents/skills/cruze-roles/design-rubric.md`.";
+}

package/dist/app/use_cases/show_elements.js

@@ -0,0 +1,18 @@
+import { CruzeError } from "../../domain/cruze_error.js";
+import { elementIndex, lookupElements,                   } from "../../domain/project/element_lookup.js";
+                                                                       
+import { loadView,                  } from "../project_context.js";
+
+/** The bodies of the named elements, living and in each in-flight delta that changes them. */
+export async function showElements(deps             , ids          )                                        {
+  const { elements, missing } = lookupElements(await loadView(deps.files), ids);
+  if (missing.length > 0) throw new CruzeError("unknown-id", `${missing.join(", ")} ${missing.length === 1 ? "is" : "are"} defined nowhere in the living docs or the work in flight; cruze show --index lists every element`);
+  return { elements };
+}
+
+/** One line per element of the living architecture and specs, with what work in flight adds or changes. */
+export async function showIndex(deps             , scope         )                                             {
+  const index = elementIndex(await loadView(deps.files), scope);
+  if (scope !== undefined && index.entries.length === 0) throw new CruzeError("unknown-scope", `no element belongs to "${scope}"; name a context or capability, such as the part of an ID before its dot`);
+  return scope === undefined ? index : { ...index, scope };
+}

package/dist/app/use_cases/show_notes.js

@@ -0,0 +1,11 @@
+import { notesFor, readNotes,                          } from "../../domain/project/notes.js";
+import { loadView,                  } from "../project_context.js";
+
+/**
+ * Every note with what it is about and the hand-off it holds, or, given a target such as
+ * `project`, `architect` or a feature slug, the notes and hand-off rows for it.
+ */
+export async function showNotes(deps             , target         )                                                               {
+  const notes = readNotes((await loadView(deps.files)).snapshot);
+  return target === undefined ? { notes } : { target, ...notesFor(notes, [target]) };
+}

package/dist/app/use_cases/show_scope.js

@@ -1,6 +1,9 @@
 import { CruzeError } from "../../domain/cruze_error.js";
 import { resolveArtifact } from "../../domain/project/artifact_ref.js";
+import { scopeOf } from "../../domain/ids.js";
+import { notesFor, readNotes,               } from "../../domain/project/notes.js";
 import { scopeView,                } from "../../domain/project/scope_view.js";
+                                                                   
 import { loadView,                  } from "../project_context.js";
 import { listEvents } from "./journal_events.js";
 
@@ -14,6 +17,10 @@ import { listEvents } from "./journal_events.js";
                                                 
                                                                                                                
                               
+                                                                                                        
+                                                   
+                                                                                   
+                  
  
 
 /**
@@ -31,5 +38,14 @@ export async function showScope(deps             , ref        )
     reason: String(entry["reason"] ?? ""),
     review: String(entry["review"] ?? ""),
   }));
-  return { ...scope, dispositions };
+  const feature = scope.feature === undefined ? item : (view.items.find((i) => i.ref === scope.feature) ?? item);
+  const contexts = [...scope.elements, ...scope.scenarios].flatMap((e) => scopeOf(e.id) ?? []);
+  const notes = notesFor(readNotes(view.snapshot), [...slugsOf(feature), ...contexts]);
+  return { ...scope, dispositions, references: view.config?.config?.references ?? [], notes };
+}
+
+/** The names a note or a hand-off may use for a feature or standalone change: its roadmap slug, and its folder name without the date. */
+export function slugsOf(item          )           {
+  const roadmap = item.doc.frontmatter?.["roadmap"];
+  return [...new Set([...(typeof roadmap === "string" ? [roadmap] : []), item.folderName.replace(/^\d{4}-\d{2}-\d{2}-/, "")])];
 }

package/dist/app/use_cases/upstream_diff.js

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

package/dist/domain/approvals/rebase.js

@@ -0,0 +1,39 @@
+import { elementHash } from "../hashing.js";
+                                                  
+import { readDelta } from "../project/deltas.js";
+import { approvalFolder,                  } from "../project/project_view.js";
+                                                         
+import { latestApproval } from "./records.js";
+
+/**
+ * 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             , merged                        )              {
+  const settled = new Set        ();
+  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             , item          )           {
+  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/dist/domain/approvals/upstream_text.js

@@ -0,0 +1,36 @@
+import { isStatusLine } from "../elements.js";
+import { designHash, elementHash } from "../hashing.js";
+import { parseMarkdown,                  } from "../markdown.js";
+import { buildLivingModel } from "../project/living_model.js";
+                                                              
+
+/** The document that holds an upstream key now: an element's living document, or the path of a `doc:` key. */
+export function upstreamPath(view             , key        )                     {
+  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        , path        , text        , pinned         )                       {
+  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             , start        , end        )           {
+  const lines           = [];
+  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/dist/domain/check/budget_text.js

@@ -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        , text        )         {
   if (!path.endsWith(".rs")) return text;
   const lines = text.split("\n");
   const kept           = [];
   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          , index        )                {
+  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        )          {
+  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        )           {
+  const parts           = [];
+  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/dist/domain/check/check_source.js

@@ -1,13 +1,14 @@
                                                        
 import { matchesAny } from "../glob.js";
 import { budgetedText } from "./budget_text.js";
+import { decisionCitationsInComments } from "./decision_comments.js";
 import { importsOf, resolveImport } from "./imports.js";
 import { countTypes } from "./type_count.js";
 
                                
                
                 
-                                                                                                   
+                                                                                                                         
                   
                                                                            
                                 
@@ -21,6 +22,8 @@ import { countTypes } from "./type_count.js";
                                        
                                                                                               
                         
+                                                                                    
+                                      
                                                                                         
                   
  
@@ -55,11 +58,11 @@ export function checkSource(input            )                 {
     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            )                 {
     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        , text        )                 {
+  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        , modulePaths          )          {
   return modulePaths.some((module) => (module.endsWith("/") ? path.startsWith(module) : path === module));

package/dist/domain/check/decision_comments.js

@@ -0,0 +1,38 @@
+import { findDecisionCitations,                       } from "../decision_citations.js";
+
+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        , text        )                     {
+  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        , lines          )           {
+  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        , marker        )         {
+  const match = marker.exec(line);
+  return match === null ? "" : line.slice(match.index);
+}

package/dist/domain/config.js

@@ -26,6 +26,8 @@ import { parse as parseYaml } from "yaml";
                                                        
                                                                                          
                         
+                                                                                                                     
+                                                   
  
 
 /** Which review findings the user decides: only the exceptions, or every one. */
@@ -132,6 +134,15 @@ export function parseConfig(text        )               {
     }),
   };
 
+  const references = (Array.isArray(root["references"]) ? root["references"] : root["references"] === undefined ? [] : [null]).flatMap((entry         , i        ) => {
+    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              = {
     version: 1,
     ...(typeof cruze === "string" && cruze.trim() !== "" ? { cruze } : {}),
@@ -148,6 +159,7 @@ export function parseConfig(text        )               {
       decide: decide === "all" ? "all" : "exceptions",
     },
     changes,
+    references,
   };
   return { config, problems };
 }

package/dist/domain/decision_citations.js

@@ -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`. */
+                                   
+                      
+               
+               
+                    
+                                                                             
+                     
+ 
+
+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                   , slugs                     , skip                            = () => false)                     {
+  const citations                     = [];
+  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                   )              {
+  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                  )              {
+  const slugs = new Set        ();
+  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/dist/domain/edits/agents_file.js

@@ -1,4 +1,5 @@
 import { factsOf, statusOf } from "../elements.js";
+import { findSection, parseMarkdown } from "../markdown.js";
                                                               
 
 /**
@@ -19,9 +20,22 @@ export function renderAgentsFile(text        , view             )         {
   return next;
 }
 
+/** The lines under `## Known pitfalls`, one per pitfall, which the feedback export carries back to Cruze. */
+export function knownPitfalls(text        )           {
+  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             )           {
+  const everBuilt = new Set(view.journal.filter((e) => e.event === "land").flatMap((e) => (Array.isArray(e["built"]) ? (e["built"]             ).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/dist/domain/ids.js

@@ -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"]         ;
+export const KINDS = ["GOAL", "PRINCIPLE", "LATER", "CTX", "ENT", "UC", "PORT", "ADP", "FLOW", "MOD", "RULE", "VIEW", "XC", "REQ", "SCN", "ADR"]         ;
                                           
 
+/** Kinds of the vision's row elements: goals, the principles every design follows, and what must stay possible later. */
+export const VISION_KINDS                  = ["GOAL", "PRINCIPLE", "LATER"];
 /** Kinds that describe code, and so carry a managed planned/built status. */
 export const CODE_KINDS                  = ["ENT", "UC", "PORT", "ADP", "FLOW", "MOD"];
 /** Kinds whose elements carry a managed status: code kinds and scenarios. */

package/dist/domain/journal.js

@@ -16,6 +16,7 @@ export const RECORDED_EVENTS                           = {
   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                           = {
   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                           = {
   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        , fields                        )           {
+  if (event === "rethink" && fields["kind"] === "defect") return ["missed_by"];
+  if (event === "verification" && fields["result"] === "sent-back") return ["back_to"];
+  return [];
+}
+
+const CONDITION_NOTES                         = { 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              )         {
 export function recordedEventProblems(event        , fields                        )           {
   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];