@printpractical/cruze 0.0.9 → 0.0.11

package/skills/triage/SKILL.md

@@ -11,7 +11,7 @@ Triage starts from a symptom and ends with a fix, or with the right step to fix
 
 1. **Capture the symptom.** Get the exact steps, what happened (output, error, exit code), what the user expected, and the environment. Done when you can write the steps as commands.
 2. **Reproduce it.** Run the steps against the real system. Done when you can make it fail on demand and have quoted the output. When you can't reproduce it, ask the user for what differs in their environment, and stop until you can.
-3. **Place it in the living docs.** Find the requirement and scenarios in `docs/specs/` that cover this behaviour, and the flow in `docs/architecture.md` that runs it. Then classify it:
+3. **Place it in the living docs.** Find the requirement and scenarios in `docs/specs/` that cover this behaviour, and the flow in `docs/architecture.md` that runs it, with `cruze show --index` and `cruze show <ID>`. Then classify it:
    - **Code defect:** a scenario says what should happen, and the code does something else.
    - **Spec gap:** no scenario covers this case.
    - **Design flaw:** the design as written can't deliver what the scenario says.

package/skills/verify/SKILL.md

@@ -9,14 +9,14 @@ Verify answers one question: does this change work when someone uses it? Green t
 
 ## Steps
 
-1. **Check it is ready.** Run `cruze next`. It must name `verify` for this change, on this branch. Find the base commit the change branched from with `git merge-base main HEAD`.
+1. **Check it is ready.** Run `cruze next`. It must name `verify` for this change, on this branch. Find the base commit the change branched from with `git merge-base main HEAD`. The code review's base is the same, unless `cruze journal list --event verification --item <ref>` shows an earlier verify: then it is that entry's commit, or `git rev-list -1 --before=<its at> HEAD` for one without, since the code before it was reviewed.
 2. **Run the mechanical checks.** Run `cruze validate`, `cruze check --ci` and `cruze trace --change <ref>`, and quote each result.
    - Run `cruze journal list --event checks --item <ref>`. When its last entry's commit has no code changes since, that is when `git diff --quiet <commit> HEAD -- . ':(exclude)docs' ':(exclude).cruze'` succeeds, quote that entry for the format, lint, build and test commands instead of running them again.
    - Otherwise run the format, lint and build commands and the full suite, as `.agents/skills/cruze-formats/reference/config.md` defines it under `commands`. When they pass, record them with `cruze journal add checks --set commit=<commit> --item <ref>`, where the commit is the output of `git rev-parse --short HEAD`.
    - When one fails, fix the code in a commit and run them again. When a fix needs design, stop and offer `rethink`.
-3. **Check the dependencies.** Follow "Checking" in `.agents/skills/cruze-dependency-approval/SKILL.md` against the base commit. An unrecorded dependency is a blocker.
+3. **Check the dependencies.** Follow "Checking" in `.agents/skills/cruze-dependency-approval/SKILL.md` against the merge base. An unrecorded dependency is a blocker.
 4. **Run the verifier.** Run the verifier role from `.agents/skills/cruze-roles/SKILL.md` for the change, with the mechanical checks' results and the commit they ran at. It must be able to build and run the system. When it runs through `cruze review`, check that `review.command` in `.cruze/config.yaml` allows the project's build and run commands, and add them with the user's agreement. Done when you have its report, with a result for every delivered scenario.
-5. **Review the code.** Run the review in the roles skill with the code reviewer, `review=code`, `--item <ref>` and the base commit. Fix each finding whose disposition is `fixed` in a commit, running the tests each fix touches, and `test` when `commands:` has a `test_full`. Then check the fixes yourself, as round 2 in the roles skill says.
+5. **Review the code.** Run the review in the roles skill with the code reviewer, `review=code`, `--item <ref>` and the code review's base. Fix each finding whose disposition is `fixed` in a commit, through a detail amendment when it needs one, running the tests each fix touches, and `test` when `commands:` has a `test_full`. Then check the fixes yourself, as round 2 in the roles skill says.
 6. **Write the manual test script** as `manual-test.md` in the change folder, following [manual-test.md](manual-test.md). Commit it.
 7. **Check the fixes once.** When code changed since the last `checks` entry, run the format, lint and build commands and the full suite once more, and record them as in step 2. Done when the last `checks` entry is at a commit with no code changes since.
 8. **Report.** Show the user four things:
@@ -25,7 +25,7 @@ Verify answers one question: does this change work when someone uses it? Green t
    - The review's outcome, with each finding's disposition.
    - The path to `manual-test.md`, with a recommendation to run it before accepting.
 9. **Ask for the decision:** "Do you accept this change, or send it back?"
-10. **Record it** with `cruze journal add verification --set result=accepted --set summary="<one line>" --item <ref>`, or `--set result=sent-back --set back_to=<build|rethink>`. On sent-back, say what goes back:
+10. **Record it** with `cruze journal add verification --set result=<accepted|sent-back> --set summary="<one line>" --set commit=<commit> --item <ref>`, where the commit is the output of `git rev-parse --short HEAD`, adding `--set back_to=<build|rethink>` when it is sent back. On sent-back, say what goes back:
    - A defect in code a task already built: `back_to=build`, then `cruze task reopen T<n> "<reason>"`.
    - A design that can't deliver the scenario: `back_to=rethink`. Leave the tasks to the rethink, which reopens the ones its amendment changes, and `cruze next` names `rethink` until it is recorded.
 
@@ -34,8 +34,8 @@ Done when the decision is recorded.
 ## Rules
 
 - A scenario the verifier couldn't run isn't passed. Mark it clearly in the report and in `manual-test.md`.
-- Findings from the review are dispositions in the journal, never edits to `change.md`.
-- Fixes made during verify are code commits that stay within the tasks' files. When a fix needs a new file or owner, it is a deviation or a rethink, exactly as in build.
+- Findings from the review are dispositions in the journal. They edit `change.md` only through a detail amendment.
+- Fixes made during verify are code commits that stay within the tasks' files. When a fix needs a new file or owner, or a detail, handle it exactly as build does.
 
 ## Next step
 

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

@@ -56,6 +56,10 @@ export interface Options {
   rebase: string[];
   byAgent: boolean;
   restampUnchanged: boolean;
+  index: boolean;
+  notes: boolean;
+  kind?: string;
+  about?: string;
   round?: string;
   package?: string;
   base?: string;

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

@@ -0,0 +1,23 @@
+import { upstreamDiff, type UpstreamDiffReport } from "../../../../app/use_cases/upstream_diff.ts";
+import { requireArgs, type CliContext, type CommandResult } from "../cli_context.ts";
+
+export async function runDiff(context: CliContext, args: string[]): Promise<CommandResult> {
+  requireArgs(args, ["ref"]);
+  const report = await upstreamDiff(context, args[0] ?? "");
+  return { json: report, human: render(report) };
+}
+
+function render(report: UpstreamDiffReport): string {
+  const lines = [`${report.artifact}: ${report.state}`];
+  if (report.changes.length === 0) lines.push("Nothing it cites changed since its approval.");
+  for (const change of report.changes) {
+    lines.push("", `${change.key}${change.path === undefined ? "" : ` in ${change.path}`}:`);
+    lines.push(...(change.diff ?? [change.note ?? ""]).map((line) => `  ${line}`));
+  }
+  if (report.rebase.length > 0) {
+    lines.push("", `Its delta changes ${report.rebase.join(", ")}: rewrite the delta to keep the new text, then approve with ${report.rebase.map((id) => `--rebase ${id}`).join(" ")}.`);
+  } else if (report.ref !== undefined && report.state === "upstream-changed") {
+    lines.push("", `No rebase needed. When the work still holds against this, re-stamp it with cruze approve ${report.ref} --restamp-unchanged.`);
+  }
+  return lines.join("\n");
+}

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

@@ -34,7 +34,7 @@ export async function runNew(context: CliContext, args: string[], options: Optio
   }
   requireArgs(args, ["kind", "slug"]);
   if (args[0] === "note") {
-    const report = await createNote(context, args[1] ?? "", requireOption(options.title, "--title"));
+    const report = await createNote(context, args[1] ?? "", requireOption(options.title, "--title"), requireOption(options.kind, "--kind"), requireOption(options.about, "--about"));
     return { json: report, human: `Created ${report.path}` };
   }
   const kind = args[0] as NewKind;

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

@@ -1,13 +1,54 @@
+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})`}`, ""];
@@ -22,6 +63,7 @@ function render(report: ScopeReport): string {
   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();
 }
@@ -30,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

@@ -45,6 +45,15 @@ export class GitRepository implements Repository {
     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) => {

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