@printpractical/cruze 0.0.8 → 0.0.10

package/src/adapters/inbound/cli/commands/show.ts

@@ -1,22 +1,69 @@
+import { showElements, showIndex } from "../../../../app/use_cases/show_elements.ts";
+import { showNotes } from "../../../../app/use_cases/show_notes.ts";
+import type { Note, NotesFor } from "../../../../domain/project/notes.ts";
 import { showScope, type ScopeReport } from "../../../../app/use_cases/show_scope.ts";
+import { isId } from "../../../../domain/ids.ts";
+import type { ElementIndex } from "../../../../domain/project/element_lookup.ts";
 import type { ShownElement } from "../../../../domain/project/scope_view.ts";
-import { requireArgs, type CliContext, type CommandResult } from "../cli_context.ts";
+import { UsageError, requireArgs, type CliContext, type CommandResult, type Options } from "../cli_context.ts";
 
-export async function runShow(context: CliContext, args: string[]): Promise<CommandResult> {
+export async function runShow(context: CliContext, args: string[], options: Options): Promise<CommandResult> {
+  if (options.notes) {
+    if (args.length > 1 || options.index) throw new UsageError("--notes takes at most one target: project, a step, a feature slug or a context");
+    const report = await showNotes(context, args[0]);
+    return { json: report, human: "target" in report ? renderNotesFor(report).join("\n").trimEnd() : renderNotes(report.notes) };
+  }
+  if (options.index) {
+    if (args.length > 1) throw new UsageError("--index takes at most one context or capability");
+    const index = await showIndex(context, args[0]);
+    return { json: index, human: renderIndex(index) };
+  }
   requireArgs(args, ["ref"]);
+  if (args.every(isId)) {
+    const report = await showElements(context, args);
+    return { json: report, human: blocks(report.elements).join("\n").trimEnd() };
+  }
+  if (args.length > 1) throw new UsageError("show takes one feature or change, or one or more element IDs");
   const report = await showScope(context, args[0] ?? "");
   return { json: report, human: render(report) };
 }
 
+/** The index as a list an agent scans for what exists, before fetching bodies with `cruze show <ID>`. */
+function renderIndex(index: ElementIndex): string {
+  const { architecture, specs } = index.words;
+  const lines = [`# Elements`, "", `docs/architecture.md holds ${architecture} words, and docs/specs/ ${specs}. Read an element's body with \`cruze show <ID>\`.`];
+  let source = "";
+  for (const entry of [...index.entries].sort((a, b) => Number(a.addedBy !== undefined) - Number(b.addedBy !== undefined))) {
+    const heading = entry.addedBy === undefined ? entry.source : "In flight, not yet merged";
+    if (heading !== source) lines.push("", `## ${heading}`, "");
+    source = heading;
+    const facts = [
+      entry.status,
+      entry.place,
+      entry.scenarios === undefined ? undefined : `${entry.scenarios} scenarios`,
+      entry.addedBy === undefined ? undefined : `added by ${entry.addedBy}`,
+      entry.changedBy.length === 0 ? undefined : `changed by ${entry.changedBy.join(", ")}`,
+    ].filter((f) => f !== undefined);
+    lines.push(`- ${entry.id}: ${entry.title}${facts.length === 0 ? "" : ` (${facts.join("; ")})`}`);
+  }
+  return lines.join("\n");
+}
+
 /** The scope as a document an agent reads in place of the living docs. */
 function render(report: ScopeReport): string {
   const lines = [`# ${report.ref}${report.feature === undefined ? "" : ` (feature ${report.feature})`}`, ""];
   lines.push("## Elements", "", ...blocks(report.elements), "## Scenarios", "", ...blocks(report.scenarios));
   lines.push("## Cited, not shown", "");
   lines.push(...(report.cited.length === 0 ? ["None."] : report.cited.map((c) => `- ${c.id}: ${c.title} (${c.source})`)), "");
-  lines.push("## Settled decisions", "", ...(report.decisions.length === 0 ? ["None."] : report.decisions), "");
+  if (report.feature === undefined) lines.push("## Settled decisions", "", ...(report.decisions.length === 0 ? ["None."] : report.decisions), "");
+  else {
+    lines.push("## Settled decisions of the feature", "", ...(report.decisions.length === 0 ? ["None."] : report.decisions), "");
+    lines.push("## Settled decisions of the change", "", ...(report.changeDecisions.length === 0 ? ["None."] : report.changeDecisions), "");
+  }
   lines.push("## Dispositions", "");
   lines.push(...(report.dispositions.length === 0 ? ["None."] : report.dispositions.map((d) => `- [${d.disposition}, ${d.review}] ${d.finding}: ${d.reason}`)), "");
+  if (report.references.length > 0) lines.push("## References", "", ...report.references.map((r) => `- \`${r.path}\`: ${r.use}`), "");
+  lines.push(...renderNotesFor(report.notes));
   if (report.missing.length > 0) lines.push("## Missing", "", ...report.missing.map((id) => `- ${id} is defined nowhere`), "");
   return lines.join("\n").trimEnd();
 }
@@ -25,3 +72,25 @@ function blocks(elements: ShownElement[]): string[] {
   if (elements.length === 0) return ["None.", ""];
   return elements.flatMap((element) => [`<!-- ${element.source} -->`, ...element.body.join("\n").trimEnd().split("\n"), ""]);
 }
+
+/** The notes about a piece of work and the parts of the user's input handed to it; nothing when there are none. */
+function renderNotesFor(found: NotesFor): string[] {
+  if (found.notes.length === 0 && found.handoffs.length === 0) return [];
+  return [
+    "## Notes",
+    "",
+    ...found.notes.map((n) => `- \`${n.path}\`: ${n.title}${n.kind === undefined ? "" : ` (${n.kind})`}`),
+    ...found.handoffs.map((h) => `- ${h.part}, from ${h.source} (${h.status}, handed off in \`${h.note}\`)`),
+    "",
+  ];
+}
+
+function renderNotes(notes: Note[]): string {
+  if (notes.length === 0) return "No notes.";
+  return notes
+    .flatMap((n) => [
+      `- \`${n.path}\`: ${n.title} (${n.kind ?? "no kind"}; about ${n.about.length === 0 ? "nothing named" : n.about.join(", ")})`,
+      ...n.handoff.map((h) => `  - ${h.part} goes to ${h.goesTo} (${h.status})`),
+    ])
+    .join("\n");
+}

package/src/adapters/inbound/cli/commands/status.ts

@@ -25,13 +25,13 @@ export async function runStatus(context: CliContext, _args: string[], options: O
   const lines = [`Branch: ${report.branch ?? "(none)"}${report.active === undefined ? "" : `, building ${report.active}`}`];
   for (const doc of report.documents) lines.push(describe(doc.artifact, doc));
   for (const feature of report.features) {
-    lines.push(describe(`feature ${feature.ref}`, feature.approval));
+    lines.push(`${describe(`feature ${feature.ref}`, feature.approval)}${pendingNote(feature.rethinkPending)}`);
     for (const change of feature.changes) {
       const name = change.ref.split("/")[1] ?? change.ref;
-      lines.push(change.landed !== undefined ? `  ${name}: landed ${change.landed}` : `  ${describe(name, change.approval)}, tasks ${change.tasksDone}/${change.tasksTotal}`);
+      lines.push(change.landed !== undefined ? `  ${name}: landed ${change.landed}` : `  ${describe(name, change.approval)}, tasks ${change.tasksDone}/${change.tasksTotal}${pendingNote(change.rethinkPending)}`);
     }
   }
-  for (const change of report.standalone) lines.push(`${describe(`change ${change.ref}`, change.approval)}, tasks ${change.tasksDone}/${change.tasksTotal}`);
+  for (const change of report.standalone) lines.push(`${describe(`change ${change.ref}`, change.approval)}, tasks ${change.tasksDone}/${change.tasksTotal}${pendingNote(change.rethinkPending)}`);
   const json = {
     ...report,
     documents: report.documents.map(compact),
@@ -48,6 +48,10 @@ function compact(status: ApprovalStatus): Omit<ApprovalStatus, "record"> & { app
   return { ...rest, approvedAt: record.approvedAt, by: record.by, ...(record.basis === undefined ? {} : { basis: record.basis }) };
 }
 
+function pendingNote(findings: string[] | undefined): string {
+  return findings === undefined ? "" : `, ${findings.length} finding(s) waiting on a rethink`;
+}
+
 /** Every step starts a new session: one session that ran plan, build, verify and land reached 745k tokens of context. */
 const FRESH_SESSION = "Run it in a new session, so its context starts empty.";
 

package/src/adapters/inbound/cli/commands.ts

@@ -1,5 +1,6 @@
 import type { Handler } from "./cli_context.ts";
 import { runCheck, runLand, runTrace } from "./commands/code.ts";
+import { runDiff } from "./commands/diff.ts";
 import { runApprove, runNew, runValidate } from "./commands/documents.ts";
 import { runInit } from "./commands/init.ts";
 import { runInstall } from "./commands/install.ts";
@@ -23,7 +24,12 @@ export const COMMANDS: Record<string, Command> = {
   validate: { handler: runValidate, options: [], usage: "validate                                          check every document against the formats" },
   status: { handler: runStatus, options: ["gate", "override", "overlap", "change"], usage: "status [--gate build [--override <reason>]] [--overlap [--change <ref>]]" },
   next: { handler: runNext, options: [], usage: "next                                              the step to run next on this branch, and why" },
-  show: { handler: runShow, options: [], usage: "show <ref>                                        the design a change builds, or a feature's delta, with what it cites and its settled ledger" },
+  diff: { handler: runDiff, options: [], usage: "diff <ref>                                        what changed upstream of a document since its approval, and whether its delta needs a rebase" },
+  show: {
+    handler: runShow,
+    options: ["index", "notes"],
+    usage: "show <ref> | show <ID>... | show --index [<context>] | show --notes [<target>]   a change's design, chosen elements, one line per element, or the notes and hand-offs for a target",
+  },
   approve: {
     handler: runApprove,
     options: ["replan", "rebase", "by-agent", "restamp-unchanged"],
@@ -31,8 +37,8 @@ export const COMMANDS: Record<string, Command> = {
   },
   new: {
     handler: runNew,
-    options: { vision: [], glossary: [], architecture: [], roadmap: [], feature: ["title", "roadmap"], change: ["title", "feature", "roadmap"], adr: ["title"], note: ["title"] },
-    usage: "new <vision|glossary|architecture|roadmap> | new <feature|change|adr|note> <slug> --title <title> [--feature <ref>] [--roadmap <slug>]",
+    options: { vision: [], glossary: [], architecture: [], roadmap: [], feature: ["title", "roadmap"], change: ["title", "feature", "roadmap"], adr: ["title"], note: ["title", "kind", "about"] },
+    usage: "new <vision|glossary|architecture|roadmap> | new <feature|change|adr> <slug> --title <title> [--feature <ref>] [--roadmap <slug>] | new note <slug> --title <title> --kind <input|intake|explore|research> --about <subjects>",
   },
   task: { handler: runTask, options: { done: ["change", "commit"], deviation: ["change"], reopen: ["change"] }, usage: "task <done|deviation|reopen> <T#> [text] [--change <ref>] [--commit <sha>]" },
   features: { handler: runFeatures, options: { add: ["summary", "goals"], update: ["summary"], drop: ["reason"] }, usage: "features <add|update|drop> <slug> [--summary <text>] [--goals <ids>] [--reason <text>]" },

package/src/adapters/inbound/cli/parse_command.ts

@@ -54,6 +54,10 @@ export function parseCommand(argv: string[]): ParsedCommand {
         blockers: { type: "string" },
         "by-agent": { type: "boolean", default: false },
         "restamp-unchanged": { type: "boolean", default: false },
+        index: { type: "boolean", default: false },
+        notes: { type: "boolean", default: false },
+        kind: { type: "string" },
+        about: { type: "string" },
       },
     });
   } catch (error) {
@@ -78,6 +82,8 @@ export function parseCommand(argv: string[]): ParsedCommand {
     rebase: values.rebase,
     byAgent: values["by-agent"],
     restampUnchanged: values["restamp-unchanged"],
+    index: values.index,
+    notes: values.notes,
     ...optional("name", values.name),
     ...optional("title", values.title),
     ...optional("feature", values.feature),
@@ -96,6 +102,8 @@ export function parseCommand(argv: string[]): ParsedCommand {
     ...optional("package", values.package),
     ...optional("base", values.base),
     ...optional("blockers", values.blockers),
+    ...optional("kind", values.kind),
+    ...optional("about", values.about),
   };
   const given = [...new Set(tokens.flatMap((token) => (token.kind === "option" ? [token.name] : [])))];
   return { words: positionals, options, given, help: values.help, version: values.version };

package/src/adapters/outbound/git_repository.ts

@@ -1,4 +1,4 @@
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
 import type { Repository } from "../../app/ports/repository.ts";
 
@@ -37,13 +37,33 @@ export class GitRepository implements Repository {
   }
 
   async filesOnBranch(branch: string, dir: string): Promise<Map<string, string>> {
-    const files = new Map<string, string>();
     const listing = await this.git("ls-tree", "-r", "--name-only", branch, "--", dir);
-    for (const path of (listing ?? "").split("\n").filter((p) => p !== "")) {
-      const text = await this.git("show", `${branch}:${path}`);
-      if (text !== null) files.set(path, text);
-    }
-    return files;
+    const paths = (listing ?? "").split("\n").filter((p) => p !== "");
+    if (paths.length === 0) return new Map();
+    // One git process for every file: a process per file took up to two minutes on a project with 26 branches.
+    const blobs = await this.catFiles(paths.map((path) => `${branch}:${path}`));
+    return new Map(paths.flatMap((path, i) => (blobs[i] === undefined ? [] : [[path, blobs[i]] as [string, string]])));
+  }
+
+  async firstCommitAdding(path: string, text: string): Promise<string | null> {
+    const commits = await this.git("log", "--reverse", "--format=%H", `-S${text}`, "--", path);
+    return commits?.split("\n").find((c) => c !== "") ?? null;
+  }
+
+  async fileAt(commit: string, path: string): Promise<string | null> {
+    return (await this.catFiles([`${commit}:${path}`]))[0] ?? null;
+  }
+
+  /** The contents of each object, in order, through one `git cat-file --batch`; undefined for one that is missing. */
+  private catFiles(objects: string[]): Promise<Array<string | undefined>> {
+    return new Promise((resolve) => {
+      const child = spawn("git", ["cat-file", "--batch"], { cwd: this.root, stdio: ["pipe", "pipe", "ignore"] });
+      const chunks: Buffer[] = [];
+      child.stdout.on("data", (chunk: Buffer) => chunks.push(chunk));
+      child.on("error", () => resolve(objects.map(() => undefined)));
+      child.on("close", () => resolve(parseBatch(Buffer.concat(chunks), objects.length)));
+      child.stdin.end(`${objects.join("\n")}\n`);
+    });
   }
 
   private async git(...args: string[]): Promise<string | null> {
@@ -55,3 +75,25 @@ export class GitRepository implements Repository {
     }
   }
 }
+
+/** Splits `git cat-file --batch` output: a `<sha> <type> <size>` header, the bytes and a newline, or `<name> missing`. */
+function parseBatch(output: Buffer, count: number): Array<string | undefined> {
+  const results: Array<string | undefined> = [];
+  let at = 0;
+  while (results.length < count && at < output.length) {
+    const headerEnd = output.indexOf(10, at);
+    if (headerEnd === -1) break;
+    const header = output.subarray(at, headerEnd).toString("utf8");
+    const size = /^[0-9a-f]+ \w+ (\d+)$/.exec(header)?.[1];
+    if (size === undefined) {
+      results.push(undefined);
+      at = headerEnd + 1;
+      continue;
+    }
+    const start = headerEnd + 1;
+    results.push(output.subarray(start, start + Number(size)).toString("utf8"));
+    at = start + Number(size) + 1;
+  }
+  while (results.length < count) results.push(undefined);
+  return results;
+}

package/src/adapters/outbound/project_root.ts

@@ -0,0 +1,13 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+/** The nearest directory at or above `start` that holds `.cruze/config.yaml`, or undefined when none does. */
+export function findProjectRoot(start: string): string | undefined {
+  let dir = start;
+  for (;;) {
+    if (existsSync(join(dir, ".cruze", "config.yaml"))) return dir;
+    const parent = dirname(dir);
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}

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/project_status.ts

@@ -1,4 +1,5 @@
 import { CruzeError } from "../../domain/cruze_error.ts";
+import { PATHS } from "../../domain/project/layout.ts";
 import { readProgress } from "../../domain/project/progress.ts";
 import { buildProjectView } from "../../domain/project/project_view.ts";
 import { findWorkItem, type WorkItem } from "../../domain/project/work_items.ts";
@@ -59,7 +60,9 @@ export async function findOverlaps(deps: ProjectDeps, ref?: string): Promise<{ c
   const mine = touchedIds(view, change);
   const overlaps: Overlap[] = [];
   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/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";
 
@@ -14,6 +17,10 @@ export interface Disposition {
 export interface ScopeReport extends ScopeView {
   /** The settled ledger of the item: the feature's dispositions and its changes', or a standalone change's. */
   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;
 }
 
 /**
@@ -31,5 +38,14 @@ export async function showScope(deps: ProjectDeps, ref: string): Promise<ScopeRe
     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: 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;
+}