@printpractical/cruze 0.0.9 → 0.0.10

package/src/app/ports/repository.ts

@@ -10,4 +10,8 @@ export interface Repository {
   otherBranches(): Promise<string[]>;
   /** Files under a directory as they are on another branch, by project-relative path. */
   filesOnBranch(branch: string, dir: string): Promise<Map<string, string>>;
+  /** The oldest commit whose change to a file added the text, or null. */
+  firstCommitAdding(path: string, text: string): Promise<string | null>;
+  /** A file's contents at a commit, or null when it didn't exist there. */
+  fileAt(commit: string, path: string): Promise<string | null>;
 }

package/src/app/use_cases/approve_artifact.ts

@@ -1,7 +1,8 @@
 import { requirePlanReviewClosed, requireUnchangedSinceApproval, type AgentBasis } from "../../domain/approvals/agent_approval.ts";
 import { evaluateApproval } from "../../domain/approvals/evaluate.ts";
 import { fingerprint, isApprovable } from "../../domain/approvals/fingerprint.ts";
-import { latestApproval, serializeApprovals, withApproval, type ApprovalRecord } from "../../domain/approvals/records.ts";
+import { rebaseNeeded } from "../../domain/approvals/rebase.ts";
+import { serializeApprovals, withApproval } from "../../domain/approvals/records.ts";
 import { CruzeError } from "../../domain/cruze_error.ts";
 import { updateProgress } from "../../domain/edits/progress_block.ts";
 import { setStatus, stampMissingStatuses } from "../../domain/edits/status_lines.ts";
@@ -14,7 +15,7 @@ import { PATHS } from "../../domain/project/layout.ts";
 import { isPlanned, readChangesTable } from "../../domain/project/plan_parts.ts";
 import { readProgress } from "../../domain/project/progress.ts";
 import { approvalFolder, approvalsPath, type ProjectView } from "../../domain/project/project_view.ts";
-import { featureOf } from "../../domain/project/work_items.ts";
+import { featureOf, type WorkItem } from "../../domain/project/work_items.ts";
 import type { Problem } from "../../domain/validation/problem.ts";
 import { SIZE_RULES } from "../../domain/validation/size_rules.ts";
 import { validateProject } from "../../domain/validation/validate_project.ts";
@@ -96,13 +97,14 @@ export async function approveArtifact(deps: ProjectDeps, ref: string, options: A
     throw new CruzeError("invalid", `${path} has ${errors.length} problem(s) to fix before approval:\n${listing}`);
   }
   requireSizesAccepted(problems, path);
+  if (item !== undefined) requireNoDecisionCitations(problems, path);
 
   const { hash, upstream } = fingerprint(view, path, parseMarkdown(text));
   const folder = approvalFolder(view, path);
   const current = view.approvals.get(folder) ?? { version: 1, approvals: [], merged: {} };
   const rebased = options.rebase ?? [];
   const deltaIds = item === undefined || item.kind === "change" ? new Set<string>() : readDelta(item.doc).ids;
-  requireRebased(view, deltaIds, latestApproval(current, path), rebased);
+  if (item !== undefined) requireRebased(view, item, rebased);
   const merged = { ...current.merged };
   for (const id of rebased) {
     const living = view.living.elements.get(id);
@@ -143,13 +145,8 @@ export async function approveArtifact(deps: ProjectDeps, ref: string, options: A
  * a rethink or another land, the delta would overwrite that edit, so approval waits until the
  * delta is reconciled and the element is named with --rebase.
  */
-function requireRebased(view: ProjectView, deltaIds: Set<string>, previous: ApprovalRecord | undefined, rebased: string[]): void {
-  if (previous === undefined) return;
-  const moved = [...deltaIds].filter((id) => {
-    const living = view.living.elements.get(id);
-    const before = previous.upstream[id];
-    return living !== undefined && before !== undefined && before !== elementHash(living.doc, living.element) && !rebased.includes(id);
-  });
+function requireRebased(view: ProjectView, item: WorkItem, rebased: string[]): void {
+  const moved = rebaseNeeded(view, item).filter((id) => !rebased.includes(id));
   if (moved.length > 0) {
     throw new CruzeError(
       "rebase-required",
@@ -172,6 +169,17 @@ function requireSizesAccepted(problems: Problem[], path: string): void {
   );
 }
 
+/**
+ * A delta that cites decisions by number would merge them into the living docs, where they dangle once
+ * the work is archived. Existing docs only warn, so approval of new or redesigned work is where it stops.
+ */
+function requireNoDecisionCitations(problems: Problem[], path: string): void {
+  const standing = problems.filter((p) => p.rule === "decision-citation");
+  if (standing.length === 0) return;
+  const listing = standing.map((p) => `  ${p.path}:${p.line ?? ""} ${p.message}`).join("\n");
+  throw new CruzeError("decision-cited", `${path} cites decisions by number in its delta, which merges into the living docs:\n${listing}`);
+}
+
 function notWork(path: string): never {
   throw new CruzeError("needs-user", `${path} is a project document, so the user approves it`);
 }

package/src/app/use_cases/check_code.ts

@@ -27,16 +27,18 @@ export async function checkCode(deps: ProjectDeps, options: { files?: string[];
   const view = await loadView(deps.files);
   const config = requireConfig(view);
   const sources = await readMatching(deps.files, config.source);
+  const tests = await readMatching(deps.files, config.tests);
   for (const file of options.files ?? []) {
-    if (!sources.has(file)) {
+    if (!sources.has(file) && !tests.has(file)) {
       const text = await deps.files.readText(file);
       if (text === undefined) throw new CruzeError("not-found", `${file} does not exist`);
       if (matchesAny(file, config.source)) sources.set(file, text);
+      else if (matchesAny(file, config.tests)) tests.set(file, text);
     }
   }
-  const only = options.files?.filter((file) => sources.has(file));
+  const only = options.files?.filter((file) => sources.has(file) || tests.has(file));
   const standards = config.standards ?? FIRST_RELEASE;
-  const findings = checkSource({ config, sources, modulePaths: modulePaths(view), ...(only === undefined ? {} : { only }) }).map((f) =>
+  const findings = checkSource({ config, sources, tests, modulePaths: modulePaths(view), ...(only === undefined ? {} : { only }) }).map((f) =>
     isPending("check", f.rule, standards) ? { ...f, pending: true as const } : f,
   );
   const failing = findings.filter((f) => f.pending !== true && (f.severity === "error" || options.ci));

package/src/app/use_cases/journal_events.ts

@@ -1,4 +1,5 @@
 import { CruzeError } from "../../domain/cruze_error.ts";
+import { knownPitfalls } from "../../domain/edits/agents_file.ts";
 import { journalPath, parseJournal, recordedEventProblems, recordedFields, type JournalEntry } from "../../domain/journal.ts";
 import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
 import { appendJournal, loadView, type ProjectDeps } from "../project_context.ts";
@@ -40,10 +41,12 @@ export interface FeedbackExport {
   exported_at: string;
   redacted: boolean;
   entries: JournalEntry[];
+  /** The lines under `## Known pitfalls` in `AGENTS.md`: lessons that may belong in Cruze rather than the project. */
+  pitfalls: string[];
 }
 
 /**
- * Bundles the journal for the framework feedback loop. By default the project name and
+ * Bundles the journal, and the project's known pitfalls, for the framework feedback loop. By default the project name and
  * the approver's identity are redacted, since the bundle may leave the project.
  */
 export async function exportFeedback(deps: ProjectDeps, redact: boolean): Promise<FeedbackExport> {
@@ -56,5 +59,6 @@ export async function exportFeedback(deps: ProjectDeps, redact: boolean): Promis
     return value;
   };
   const entries = redact ? view.journal.map((entry) => ({ ...(scrub(entry) as JournalEntry), by: "<redacted>" })) : view.journal;
-  return { format: "cruze-feedback/1", cruze: deps.bundle.version, exported_at: deps.clock.now().toISOString(), redacted: redact, entries };
+  const pitfalls = knownPitfalls((await deps.files.readText("AGENTS.md")) ?? "").map((line) => (redact ? (scrub(line) as string) : line));
+  return { format: "cruze-feedback/1", cruze: deps.bundle.version, exported_at: deps.clock.now().toISOString(), redacted: redact, entries, pitfalls };
 }

package/src/app/use_cases/new_project_doc.ts

@@ -1,5 +1,6 @@
 import { CruzeError } from "../../domain/cruze_error.ts";
 import { PATHS } from "../../domain/project/layout.ts";
+import { NOTE_KINDS } from "../../domain/project/notes.ts";
 import { requireSlug } from "../../domain/project/new_items.ts";
 import { renderTemplate } from "../../domain/scaffold.ts";
 import { appendJournal, loadView, type ProjectDeps } from "../project_context.ts";
@@ -27,14 +28,21 @@ export async function createProjectDoc(deps: ProjectDeps, kind: ProjectDocKind):
 }
 
 /** Creates a dated note in `.cruze/notes/`, such as a captured explore session or research evidence. */
-export async function createNote(deps: ProjectDeps, slug: string, title: string): Promise<NewDocReport> {
+/**
+ * A dated note, saying what kind it is and what it is about, so `cruze show` finds it for the work it
+ * informs: `project`, feature slugs, or context and capability names.
+ */
+export async function createNote(deps: ProjectDeps, slug: string, title: string, kind: string, about: string): Promise<NewDocReport> {
   requireSlug(slug);
   if (title.trim() === "") throw new CruzeError("missing-title", "a title is required");
+  if (!(NOTE_KINDS as readonly string[]).includes(kind)) throw new CruzeError("note-kind", `a note's kind is one of ${NOTE_KINDS.join(", ")}`);
+  const subjects = about.split(",").map((a) => a.trim()).filter((a) => a !== "");
+  if (subjects.length === 0) throw new CruzeError("note-about", "name what the note is about: project, feature slugs, or contexts, comma-separated");
   const view = await loadView(deps.files);
   const date = deps.clock.today();
   const base = `${PATHS.notesDir}/${date}-${slug}`;
   let path = `${base}.md`;
   for (let n = 2; view.snapshot.has(path); n++) path = `${base}-${n}.md`;
-  await deps.files.writeText(path, `# ${title}\n\n- Date: ${date}\n\n`);
+  await deps.files.writeText(path, `# ${title}\n\n- Date: ${date}\n- Kind: ${kind}\n- About: ${subjects.join(", ")}\n\n`);
   return { kind: "note", path };
 }

package/src/app/use_cases/run_review.ts

@@ -1,6 +1,7 @@
 import { CruzeError } from "../../domain/cruze_error.ts";
 import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
-import { featureOf } from "../../domain/project/work_items.ts";
+import { isPlanned } from "../../domain/project/plan_parts.ts";
+import { featureOf, type WorkItem } from "../../domain/project/work_items.ts";
 import type { AgentRunner } from "../ports/agent_runner.ts";
 import { loadView, type ProjectDeps } from "../project_context.ts";
 
@@ -44,7 +45,7 @@ export async function runReview(deps: ProjectDeps & { runner: AgentRunner }, 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: ProjectDeps, role: Role): Promise<string> {
   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: WorkItem): string {
+  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/src/app/use_cases/show_elements.ts

@@ -0,0 +1,18 @@
+import { CruzeError } from "../../domain/cruze_error.ts";
+import { elementIndex, lookupElements, type ElementIndex } from "../../domain/project/element_lookup.ts";
+import type { ShownElement } from "../../domain/project/scope_view.ts";
+import { loadView, type ProjectDeps } from "../project_context.ts";
+
+/** The bodies of the named elements, living and in each in-flight delta that changes them. */
+export async function showElements(deps: ProjectDeps, ids: string[]): Promise<{ elements: ShownElement[] }> {
+  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: ProjectDeps, scope?: string): Promise<ElementIndex & { scope?: string }> {
+  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/src/app/use_cases/show_notes.ts

@@ -0,0 +1,11 @@
+import { notesFor, readNotes, type Note, type NotesFor } from "../../domain/project/notes.ts";
+import { loadView, type ProjectDeps } from "../project_context.ts";
+
+/**
+ * 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: ProjectDeps, target?: string): Promise<{ notes: Note[] } | (NotesFor & { target: string })> {
+  const notes = readNotes((await loadView(deps.files)).snapshot);
+  return target === undefined ? { notes } : { target, ...notesFor(notes, [target]) };
+}

package/src/app/use_cases/show_scope.ts

@@ -1,6 +1,9 @@
 import { CruzeError } from "../../domain/cruze_error.ts";
 import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
+import { scopeOf } from "../../domain/ids.ts";
+import { notesFor, readNotes, type NotesFor } from "../../domain/project/notes.ts";
 import { scopeView, type ScopeView } from "../../domain/project/scope_view.ts";
+import type { WorkItem } from "../../domain/project/work_items.ts";
 import { loadView, type ProjectDeps } from "../project_context.ts";
 import { listEvents } from "./journal_events.ts";
 
@@ -16,6 +19,8 @@ export interface ScopeReport extends ScopeView {
   dispositions: Disposition[];
   /** The external documents the design must comply with, from `references:` in `.cruze/config.yaml`. */
   references: Array<{ path: string; use: string }>;
+  /** The notes about this work, and the parts of the user's input handed to it. */
+  notes: NotesFor;
 }
 
 /**
@@ -33,5 +38,14 @@ export async function showScope(deps: ProjectDeps, ref: string): Promise<ScopeRe
     reason: String(entry["reason"] ?? ""),
     review: String(entry["review"] ?? ""),
   }));
-  return { ...scope, dispositions, references: view.config?.config?.references ?? [] };
+  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: WorkItem): string[] {
+  const roadmap = item.doc.frontmatter?.["roadmap"];
+  return [...new Set([...(typeof roadmap === "string" ? [roadmap] : []), item.folderName.replace(/^\d{4}-\d{2}-\d{2}-/, "")])];
 }

package/src/app/use_cases/upstream_diff.ts

@@ -0,0 +1,55 @@
+import { evaluateApproval, type ApprovalState } from "../../domain/approvals/evaluate.ts";
+import { rebaseNeeded } from "../../domain/approvals/rebase.ts";
+import { upstreamLines, upstreamPath } from "../../domain/approvals/upstream_text.ts";
+import { lineDiff } from "../../domain/line_diff.ts";
+import { resolveArtifact } from "../../domain/project/artifact_ref.ts";
+import { approvalFolder, approvalsPath } from "../../domain/project/project_view.ts";
+import { loadView, type ProjectDeps } from "../project_context.ts";
+
+export interface UpstreamChange {
+  /** The upstream element ID, or `doc:<path>` for a feature's design. */
+  key: string;
+  path?: string;
+  /** The approved text against the current text, when the approved text was found. */
+  diff?: string[];
+  note?: string;
+}
+
+export interface UpstreamDiffReport {
+  artifact: string;
+  ref?: string;
+  state: ApprovalState;
+  changes: UpstreamChange[];
+  /** Elements the work's delta changes whose living text moved: approval needs --rebase for each. */
+  rebase: string[];
+}
+
+/**
+ * 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: ProjectDeps, ref: string): Promise<UpstreamDiffReport> {
+  const view = await loadView(deps.files);
+  const { path, item } = resolveArtifact(view, ref);
+  const status = evaluateApproval(view, path);
+  const report: UpstreamDiffReport = { 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/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. */
@@ -32,7 +33,7 @@ export const STEPS = ["envision", "architect", "research", "design-review", "wal
 export const FIELD_VALUES: Record<string, string[]> = {
   level: ["task", "change", "feature", "architecture", "vision"],
   kind: ["defect", "discovery"],
-  disposition: ["fixed", "waived", "deferred", "rejected"],
+  disposition: ["fixed", "waived", "deferred", "rejected", "rethink"],
   decided: ["agent", "user"],
   review: ["design", "plan", "code", "realign", "improve"],
   result: ["accepted", "sent-back"],
@@ -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. */

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