@printpractical/cruze 0.0.9 → 0.0.10

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

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. */
@@ -32,7 +33,7 @@ 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"],
@@ -40,6 +41,7 @@ export const FIELD_VALUES                           = {
   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. */

package/dist/domain/land/merge_plan.js

@@ -1,3 +1,4 @@
+import { settledIds } from "../approvals/rebase.js";
 import { sectionForKind } from "../architecture_sections.js";
 import { CruzeError } from "../cruze_error.js";
 import { setStatus } from "../edits/status_lines.js";
@@ -26,7 +27,8 @@ import { appendBlock, relevel, removeElement, replaceElement } from "./text_ops.
 /**
  * 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             , change          , source          )            {
   const scope = readScope(change.doc);
@@ -36,6 +38,7 @@ export function planMerge(view             , change          , source          )
   const files = new Map                ();
   const text = (path        )         => files.get(path) ?? view.snapshot.get(path) ?? "";
   const plan            = { 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             , change          , source          )
       }
       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/dist/domain/line_diff.js

@@ -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          , after          , context = 2)           {
+  const ops = diffOps(before, after);
+  const near = new Set        ();
+  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           = [];
+  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;
+}
+
+              
+                        
+               
+ 
+
+/** The edit script of a longest common subsequence: documents are small enough for the quadratic table. */
+function diffOps(a          , b          )       {
+  const width = b.length + 1;
+  const table = new Int32Array((a.length + 1) * width);
+  const at = (i        , j        )         => 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       = [];
+  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/dist/domain/project/element_lookup.js

@@ -0,0 +1,124 @@
+import { elementLines, factsOf, statusOf,                                         } from "../elements.js";
+import { findIds, kindOf, scopeOf,           } from "../ids.js";
+                                                  
+import { readDelta } from "./deltas.js";
+import { PATHS } from "./layout.js";
+                                                     
+                                                    
+                                                
+
+/**
+ * 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.
+ */
+
+                             
+             
+                
+             
+                                                                          
+                 
+                  
+                                                                           
+                 
+                                                        
+                     
+                                                          
+                      
+                                                        
+                   
+ 
+
+                               
+                                                                                                        
+                                                 
+                        
+ 
+
+const DOCS_INDEXED = (path        )          => 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             , scope         )               {
+  const inScope = (id        )          => scope === undefined || scopeOf(id) === scope || id === `CTX-${scope}`;
+  const entries               = [];
+  const byId = new Map                    ();
+  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             , ids          )                                                  {
+  const elements                 = [];
+  const missing           = [];
+  for (const id of ids) {
+    const found                 = [];
+    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        , element         , doc             , source        )             {
+  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             , element         , path        )               {
+  return { id: element.id, title: element.title, source: `${path}:${element.start + 1}`, body: elementLines(doc, element) };
+}
+
+function inFlight(view             )             {
+  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          )                                            {
+  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             , requirement        )         {
+  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             )                                          {
+  const words = (path        )         => (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/dist/domain/project/living_model.js

@@ -1,4 +1,5 @@
 import { headingElements, rowElements,              } from "../elements.js";
+import { VISION_KINDS } from "../ids.js";
 import { parseMarkdown,                  } from "../markdown.js";
 import { PATHS, childFiles,               } from "./layout.js";
 
@@ -49,6 +50,6 @@ function elementsOf(path        , doc             )            {
   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/dist/domain/project/notes.js

@@ -0,0 +1,74 @@
+import { findSection, parseMarkdown } from "../markdown.js";
+import { tablesIn } from "../markdown_tables.js";
+import { PATHS } from "./layout.js";
+                                            
+
+/**
+ * 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"]         ;
+                                                   
+
+/** The step an intake row hands a part to, besides a feature on the map. */
+export const HANDOFF_STEPS = ["vision", "architect", "roadmap", "user"]         ;
+
+                             
+                                                                
+               
+                                                                                            
+                 
+                                                                                
+                 
+                                                                                                 
+                 
+ 
+
+                       
+               
+                
+                
+                                                                   
+                  
+                        
+ 
+
+export function readNotes(snapshot          )         {
+  return [...snapshot.keys()]
+    .filter((path) => path.startsWith(`${PATHS.notesDir}/`) && path.endsWith(".md"))
+    .sort()
+    .map((path) => readNote(path, snapshot.get(path) ?? ""));
+}
+
+function readNote(path        , text        )       {
+  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        )                     =>
+    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 }) };
+}
+
+                           
+                                                                                        
+                
+                                                                                        
+                                                 
+ 
+
+/** 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        , targets          )           {
+  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 }))),
+  };
+}