@printpractical/cruze 0.0.9 → 0.0.10

package/README.md

@@ -10,7 +10,7 @@ It works with any agent that supports the [Agent Skills](https://agentskills.io)
 
 ## Status
 
-Version 0.0.9 is the ninth preview. Designs now say how work flows and recovers: the design reviewer checks full queues, fairness, recovery that fails and cancellation, and `references:` names the specifications a design must follow. `cruze next` sends a change verify sent back to the rethink it needs, file budgets are a backstop rather than a size to design to, and every step reads a change's scope through `cruze show` instead of the living docs whole. Early development. The CLI is complete for the V1 lifecycle. The document formats ship as the `cruze-formats` skill, the standards an agent designs and codes to ship as knowledge skills, and the whole workflow, from explore to land, ships as workflow skills. Claude Code is the agent tested so far.
+Version 0.0.10 is the tenth preview. Intent now survives from the first idea to every design: the vision holds the principles every design follows and the capabilities that must stay possible, envision takes in any input and hands each part to the step that takes it up, and the design reviewer checks every design against them. Steps read less, through an element index and lookup, one rubric per review and a word budget on the skills. Early development. The CLI is complete for the V1 lifecycle. The document formats ship as the `cruze-formats` skill, the standards an agent designs and codes to ship as knowledge skills, and the whole workflow, from explore to land, ships as workflow skills. Claude Code is the agent tested so far.
 
 ## Why
 
@@ -35,7 +35,7 @@ The skills run `cruze` commands, so the agent needs `cruze` on its path. Install
 From a GitHub Release, without npm. Each release attaches the packed package:
 
 ```sh
-npm install -g https://github.com/PrintPractical/cruze/releases/download/v0.0.9/printpractical-cruze-0.0.9.tgz
+npm install -g https://github.com/PrintPractical/cruze/releases/download/v0.0.10/printpractical-cruze-0.0.10.tgz
 ```
 
 From npm, once a version is published there:
@@ -47,7 +47,7 @@ npm install -g @printpractical/cruze
 From the git repository, at a tag or `#main`. This needs git and access to the repository. npm 11 needs `--install-links` for a global git install, and the first `cruze` command builds the CLI, which takes a moment:
 
 ```sh
-npm install -g --install-links github:PrintPractical/cruze#v0.0.9
+npm install -g --install-links github:PrintPractical/cruze#v0.0.10
 ```
 
 ### 2. Set up a repository
@@ -61,7 +61,7 @@ cruze init
 When you didn't install from npm, tell `init` where Cruze came from, so the CI it writes runs the same source instead of the npm package:
 
 ```sh
-cruze init --package https://github.com/PrintPractical/cruze/releases/download/v0.0.9/printpractical-cruze-0.0.9.tgz
+cruze init --package https://github.com/PrintPractical/cruze/releases/download/v0.0.10/printpractical-cruze-0.0.10.tgz
 ```
 
 `init` asks for the project name, and which coding agent you use: `claude` for Claude Code, or `other` for any agent that reads `AGENTS.md` and `.agents/skills/`, such as Codex or OpenCode. It doesn't ask when you pass `--agent claude` or `--agent other`, or when the repository already has `CLAUDE.md` or `.claude/`. With `--yes`, or without a terminal, it sets up Claude Code. Then it creates:
@@ -118,25 +118,29 @@ Skills call these at fixed points, and CI runs `check` and `trace` on every push
 
 | Command | What it does |
 | --- | --- |
-| `cruze validate` | Checks every document against the formats: IDs, elements, deltas, scope rules, task lines, test plans, roadmap and config, and warns when a change falls outside the size band in `changes:` |
+| `cruze validate` | Checks every document against the formats: IDs, elements, deltas, scope rules, task lines, test plans, roadmap and config, and warns when a change falls outside the size band in `changes:` or a document cites a decision recorded elsewhere |
 | `cruze approve <doc>` | Records an approval as a fingerprint: the document's design hash plus the hash of every upstream element it cites. `--replan` sets built elements a rethink changed back to planned; `--rebase` accepts living text a feature must now build on. `--by-agent` approves a change for you once its plan review has closed, and `--restamp-unchanged` re-stamps work a rethink didn't change; both record that the agent gave the approval |
-| `cruze next` | Names the step to run next on this branch, and why, from computed status |
+| `cruze next` | Names the step to run next on this branch, and why, from computed status: for stale work, whether a re-stamp or a rebase is due |
 | `cruze show <ref>` | Prints the design a change builds, or a feature's delta: each element's full body, the delivered scenarios, what they cite with where to find it, the settled decisions and the item's dispositions, so a step reads its scope instead of the whole architecture |
-| `cruze status` | Computes each document's state (approved, edited, upstream changed or unapproved) from content, never from stored state |
-| `cruze status --gate build` | Passes only when this branch's change, its feature and the architecture are approved and current |
+| `cruze show <ID>...` | Prints the chosen elements' bodies, with each in-flight delta's version beside the living one |
+| `cruze show --notes [<target>]` | Lists every note with its kind and what it is about, and the parts of the user's input envision handed to each step or feature; with a target, such as `architect` or a feature slug, only those for it |
+| `cruze show --index [<context>]` | Lists every element of the architecture and specs on one line, with its status, module and the work in flight that changes it, or one context or capability in full, and gives the size of the living docs |
+| `cruze status` | Computes each document's state (approved, edited, upstream changed or unapproved) from content, never from stored state, and counts the findings waiting on a rethink |
+| `cruze diff <ref>` | Shows what changed upstream of a document since its approval, each element's approved text against its current text, and whether the work's delta needs a rebase |
+| `cruze status --gate build` | Passes only when this branch's change, its feature and the architecture are approved and current, and no finding on them waits on a rethink |
 | `cruze status --overlap` | Lists changes on other branches that touch the same elements as this branch's change |
-| `cruze new <kind>` | Creates a project document (`vision`, `glossary`, `architecture`, `roadmap`) or work (`feature`, `change`, `adr`, `note`) from its template, with a dated ID that is never reused |
+| `cruze new <kind>` | Creates a project document (`vision`, `glossary`, `architecture`, `roadmap`) or work (`feature`, `change`, `adr`, `note`) from its template, with a dated ID that is never reused; a note says its kind and what it is about (`--kind`, `--about`) |
 | `cruze task done <T#>` | Ticks a task with its commit; `cruze task reopen` unticks one a rethink changed, and `cruze task deviation` records a small departure from the plan |
 | `cruze features <add\|update\|drop>` | Edits the feature map: adds or drops a future feature, or corrects a summary |
 | `cruze roadmap prune` | Clears landed items from the roadmap's status when a release closes |
 | `cruze trace` | Fails when a delivered scenario has no test carrying its ID; `--all` checks every built scenario |
-| `cruze check` | Enforces the layer rules and the file budgets; `--ci` also fails on budget warnings |
+| `cruze check` | Enforces the layer rules and the file budgets, and warns on decision numbers in code comments; `--ci` also fails on warnings |
 | `cruze review <role>` | Runs a role (design reviewer, code reviewer, verifier, researcher or auditor) in a fresh agent context, through the command in `.cruze/config.yaml`. When no command is set, or its program isn't installed, it prints the role's prompt for the agent to run in a helper of its own |
 | `cruze land` | Merges a verified change into the living docs, re-stamps the approvals the merge would make stale, fills the Commands and Layout sections of `AGENTS.md`, and archives finished work |
 | `cruze realign status` | Lists what the installed Cruze expects of existing code since its `standards:` version, with what the CLI rules find now; `--full` covers every release |
 | `cruze realign done` | Moves `standards:` up once every finding is fixed, waived or scheduled in a change named with `--change` |
 | `cruze abandon <ref>` | Archives a feature or standalone change that stops for good, with its reason, and puts a feature back on the future list |
-| `cruze journal add <event>` | Records a rethink, review round, disposition, verification, override or bug; `cruze journal list` reads the work in flight's entries, or landed work's too with `--all`; `cruze feedback export` bundles the journal for improving Cruze itself |
+| `cruze journal add <event>` | Records a rethink, review round, disposition, verification, override, bug or lesson; `cruze journal list` reads the work in flight's entries, or landed work's too with `--all`; `cruze feedback export` bundles the journal for improving Cruze itself |
 
 Stepping back is editing: change an upstream document and every approval that cites a changed element shows as stale, with the element named. Re-approving is the rewind; there are no phases to reset.
 
@@ -147,7 +151,7 @@ Stepping back is editing: change an upstream document and every approval that ci
 | Skill | What it holds |
 | --- | --- |
 | `cruze-explore` | Optional thinking partner before any step: options and trade-offs, captured as a note only when you ask |
-| `cruze-envision` | The what: the project's vision, goals and feature map, or one feature's intent and requirements with scenarios |
+| `cruze-envision` | The what: the project's vision, goals, principles, what must stay possible later and feature map, asking about the capabilities the product may grow into, or one feature's intent and requirements with scenarios |
 | `cruze-architect` | The how: the architecture, a feature's architecture delta and its changes, or a tweak; ends with a design review and a walkthrough for your approval |
 | `cruze-roadmap` | Orders the release into phases with blocking edges and goal coverage, and closes a release |
 | `cruze-plan` | Turns a change into a test plan and ordered tasks with file targets, reviewed in a fresh context and approved once the review closes |
@@ -170,7 +174,7 @@ Stepping back is editing: change an upstream document and every approval that ci
 
 ## Reporting back
 
-Cruze improves from what goes wrong in real projects. Every rethink, review finding, bug and override is recorded in the project's journal. To send them back:
+Cruze improves from what goes wrong in real projects. Every rethink, review finding, bug and override is recorded in the project's journal, along with each repeated lesson about Cruze's own steps. To send them back, with the `## Known pitfalls` of `AGENTS.md`:
 
 ```sh
 cruze feedback export --out cruze-feedback.json

package/dist/adapters/inbound/cli/cli_context.js

@@ -56,6 +56,10 @@
                    
                    
                             
+                 
+                 
+                
+                 
                  
                    
                 

package/dist/adapters/inbound/cli/commands/diff.js

@@ -0,0 +1,23 @@
+import { upstreamDiff,                         } from "../../../../app/use_cases/upstream_diff.js";
+import { requireArgs,                                     } from "../cli_context.js";
+
+export async function runDiff(context            , args          )                         {
+  requireArgs(args, ["ref"]);
+  const report = await upstreamDiff(context, args[0] ?? "");
+  return { json: report, human: render(report) };
+}
+
+function render(report                    )         {
+  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/dist/adapters/inbound/cli/commands/documents.js

@@ -34,7 +34,7 @@ export async function runNew(context            , args          , options
   }
   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]           ;

package/dist/adapters/inbound/cli/commands/show.js

@@ -1,13 +1,54 @@
+import { showElements, showIndex } from "../../../../app/use_cases/show_elements.js";
+import { showNotes } from "../../../../app/use_cases/show_notes.js";
+                                                                          
 import { showScope,                  } from "../../../../app/use_cases/show_scope.js";
+import { isId } from "../../../../domain/ids.js";
+                                                                                 
                                                                              
-import { requireArgs,                                     } from "../cli_context.js";
+import { UsageError, requireArgs,                                                   } from "../cli_context.js";
 
-export async function runShow(context            , args          )                         {
+export async function runShow(context            , args          , options         )                         {
+  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              )         {
+  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             )         {
   const lines = [`# ${report.ref}${report.feature === undefined ? "" : ` (feature ${report.feature})`}`, ""];
@@ -22,6 +63,7 @@ function render(report             )         {
   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                )           {
   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          )           {
+  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        )         {
+  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/dist/adapters/inbound/cli/commands/status.js

@@ -25,13 +25,13 @@ export async function runStatus(context            , _args          , options
   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                )
   return { ...rest, approvedAt: record.approvedAt, by: record.by, ...(record.basis === undefined ? {} : { basis: record.basis }) };
 }
 
+function pendingNote(findings                      )         {
+  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/dist/adapters/inbound/cli/commands.js

@@ -1,5 +1,6 @@
                                                 
 import { runCheck, runLand, runTrace } from "./commands/code.js";
+import { runDiff } from "./commands/diff.js";
 import { runApprove, runNew, runValidate } from "./commands/documents.js";
 import { runInit } from "./commands/init.js";
 import { runInstall } from "./commands/install.js";
@@ -23,7 +24,12 @@ export const COMMANDS                          = {
   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                          = {
   },
   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/dist/adapters/inbound/cli/parse_command.js

@@ -54,6 +54,10 @@ export function parseCommand(argv          )                {
         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          )                {
     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          )                {
     ...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/dist/adapters/outbound/git_repository.js

@@ -45,6 +45,15 @@ export class GitRepository                       {
     return new Map(paths.flatMap((path, i) => (blobs[i] === undefined ? [] : [[path, blobs[i]]                    ])));
   }
 
+  async firstCommitAdding(path        , text        )                         {
+    const commits = await this.git("log", "--reverse", "--format=%H", `-S${text}`, "--", path);
+    return commits?.split("\n").find((c) => c !== "") ?? null;
+  }
+
+  async fileAt(commit        , path        )                         {
+    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. */
           catFiles(objects          )                                     {
     return new Promise((resolve) => {

package/dist/app/ports/repository.js

@@ -10,4 +10,8 @@
                                      
                                                                                          
                                                                            
+                                                                          
+                                                                        
+                                                                           
+                                                               
  

package/dist/app/use_cases/approve_artifact.js

@@ -1,7 +1,8 @@
 import { requirePlanReviewClosed, requireUnchangedSinceApproval,                 } from "../../domain/approvals/agent_approval.js";
 import { evaluateApproval } from "../../domain/approvals/evaluate.js";
 import { fingerprint, isApprovable } from "../../domain/approvals/fingerprint.js";
-import { latestApproval, serializeApprovals, withApproval,                     } from "../../domain/approvals/records.js";
+import { rebaseNeeded } from "../../domain/approvals/rebase.js";
+import { serializeApprovals, withApproval } from "../../domain/approvals/records.js";
 import { CruzeError } from "../../domain/cruze_error.js";
 import { updateProgress } from "../../domain/edits/progress_block.js";
 import { setStatus, stampMissingStatuses } from "../../domain/edits/status_lines.js";
@@ -14,7 +15,7 @@ import { PATHS } from "../../domain/project/layout.js";
 import { isPlanned, readChangesTable } from "../../domain/project/plan_parts.js";
 import { readProgress } from "../../domain/project/progress.js";
 import { approvalFolder, approvalsPath,                  } from "../../domain/project/project_view.js";
-import { featureOf } from "../../domain/project/work_items.js";
+import { featureOf,               } from "../../domain/project/work_items.js";
                                                                   
 import { SIZE_RULES } from "../../domain/validation/size_rules.js";
 import { validateProject } from "../../domain/validation/validate_project.js";
@@ -96,13 +97,14 @@ export async function approveArtifact(deps             , ref        , options
     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        () : 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             , ref        , options
  * 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             , deltaIds             , previous                            , rebased          )       {
-  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             , item          , rebased          )       {
+  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           , path        )       {
   );
 }
 
+/**
+ * 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           , path        )       {
+  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        )        {
   throw new CruzeError("needs-user", `${path} is a project document, so the user approves it`);
 }

package/dist/app/use_cases/check_code.js

@@ -27,16 +27,18 @@ export async function checkCode(deps             , options
   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          } : f,
   );
   const failing = findings.filter((f) => f.pending !== true && (f.severity === "error" || options.ci));

package/dist/app/use_cases/journal_events.js

@@ -1,4 +1,5 @@
 import { CruzeError } from "../../domain/cruze_error.js";
+import { knownPitfalls } from "../../domain/edits/agents_file.js";
 import { journalPath, parseJournal, recordedEventProblems, recordedFields,                   } from "../../domain/journal.js";
 import { resolveArtifact } from "../../domain/project/artifact_ref.js";
 import { appendJournal, loadView,                  } from "../project_context.js";
@@ -40,10 +41,12 @@ export async function listEvents(deps             , event         , item
                       
                     
                           
+                                                                                                                      
+                     
  
 
 /**
- * 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             , redact         )                          {
@@ -56,5 +59,6 @@ export async function exportFeedback(deps             , redact         )
     return value;
   };
   const entries = redact ? view.journal.map((entry) => ({ ...(scrub(entry)                ), 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)          ) : line));
+  return { format: "cruze-feedback/1", cruze: deps.bundle.version, exported_at: deps.clock.now().toISOString(), redacted: redact, entries, pitfalls };
 }

package/dist/app/use_cases/new_project_doc.js

@@ -1,5 +1,6 @@
 import { CruzeError } from "../../domain/cruze_error.js";
 import { PATHS } from "../../domain/project/layout.js";
+import { NOTE_KINDS } from "../../domain/project/notes.js";
 import { requireSlug } from "../../domain/project/new_items.js";
 import { renderTemplate } from "../../domain/scaffold.js";
 import { appendJournal, loadView,                  } from "../project_context.js";
@@ -27,14 +28,21 @@ export async function createProjectDoc(deps             , kind                )
 }
 
 /** Creates a dated note in `.cruze/notes/`, such as a captured explore session or research evidence. */
-export async function createNote(deps             , slug        , title        )                        {
+/**
+ * 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             , slug        , title        , kind        , about        )                        {
   requireSlug(slug);
   if (title.trim() === "") throw new CruzeError("missing-title", "a title is required");
+  if (!(NOTE_KINDS                     ).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/dist/app/use_cases/run_review.js

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

package/dist/app/use_cases/show_elements.js

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

package/dist/app/use_cases/show_notes.js

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

package/dist/app/use_cases/show_scope.js

@@ -1,6 +1,9 @@
 import { CruzeError } from "../../domain/cruze_error.js";
 import { resolveArtifact } from "../../domain/project/artifact_ref.js";
+import { scopeOf } from "../../domain/ids.js";
+import { notesFor, readNotes,               } from "../../domain/project/notes.js";
 import { scopeView,                } from "../../domain/project/scope_view.js";
+                                                                   
 import { loadView,                  } from "../project_context.js";
 import { listEvents } from "./journal_events.js";
 
@@ -16,6 +19,8 @@ import { listEvents } from "./journal_events.js";
                               
                                                                                                         
                                                    
+                                                                                   
+                  
  
 
 /**
@@ -33,5 +38,14 @@ export async function showScope(deps             , ref        )
     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          )           {
+  const roadmap = item.doc.frontmatter?.["roadmap"];
+  return [...new Set([...(typeof roadmap === "string" ? [roadmap] : []), item.folderName.replace(/^\d{4}-\d{2}-\d{2}-/, "")])];
 }