@printpractical/cruze 0.0.7 → 0.0.9

package/README.md

@@ -10,7 +10,7 @@ It works with any agent that supports the [Agent Skills](https://agentskills.io)
 
 ## Status
 
-Version 0.0.7 is the seventh preview. It fits the structure to the kind of system: layers are roles rather than folders, a context starts as one core module with its adapters, architect starts from the layout that is normal for a library, a daemon, an app or a CLI, and the new `improve` skill restructures existing code to those standards when you choose. 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.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.
 
 ## 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.7/printpractical-cruze-0.0.7.tgz
+npm install -g https://github.com/PrintPractical/cruze/releases/download/v0.0.9/printpractical-cruze-0.0.9.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.7
+npm install -g --install-links github:PrintPractical/cruze#v0.0.9
 ```
 
 ### 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.7/printpractical-cruze-0.0.7.tgz
+cruze init --package https://github.com/PrintPractical/cruze/releases/download/v0.0.9/printpractical-cruze-0.0.9.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:
@@ -121,6 +121,7 @@ Skills call these at fixed points, and CI runs `check` and `trace` on every push
 | `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 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 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 status --overlap` | Lists changes on other branches that touch the same elements as this branch's change |
@@ -135,7 +136,7 @@ Skills call these at fixed points, and CI runs `check` and `trace` on every push
 | `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 feedback export` bundles the journal for improving Cruze itself |
+| `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 |
 
 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.
 

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

@@ -13,6 +13,8 @@
                       
                                                                  
                         
+                                                                                                                  
+                           
  
 
 /** What a command produces: a JSON result for agents, a summary for people, and whether it passed. */

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

@@ -1,9 +1,10 @@
+import { posix } from "node:path";
 import { checkCode, traceTests } from "../../../../app/use_cases/check_code.js";
 import { landChange } from "../../../../app/use_cases/land_change.js";
                                                                             
 
 export async function runCheck(context            , args          , options         )                         {
-  const files = [...options.file, ...args];
+  const files = [...options.file, ...args].map((file) => posix.normalize(posix.join(context.workingDirectory, file)));
   const report = await checkCode(context, { ci: options.ci, ...(files.length === 0 ? {} : { files }) });
   const lines = report.findings.map((f) => `${f.severity} ${f.path}${f.line === undefined ? "" : `:${f.line}`} ${f.message} [${f.rule}]${f.pending === true ? " (pending realign)" : ""}`);
   lines.push(`Checked ${report.checked} file(s): ${report.passed ? "passed" : "failed"}.`);

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

@@ -15,7 +15,7 @@ export async function runJournal(context            , args          , options
     return { json: entry, human: `Recorded ${entry.event}.` };
   }
   if (args[0] === "list") {
-    const entries = await listEvents(context, options.event, options.item);
+    const entries = await listEvents(context, options.event, options.item, options.all);
     return { json: entries, human: entries.map((e) => `${e.at} ${e.event} ${JSON.stringify({ ...e, at: undefined, event: undefined, by: undefined })}`).join("\n") || "No entries." };
   }
   throw new UsageError(`cruze journal takes add or list, not "${args[0]}"`);

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

@@ -0,0 +1,32 @@
+import { showScope,                  } from "../../../../app/use_cases/show_scope.js";
+                                                                             
+import { requireArgs,                                     } from "../cli_context.js";
+
+export async function runShow(context            , args          )                         {
+  requireArgs(args, ["ref"]);
+  const report = await showScope(context, args[0] ?? "");
+  return { json: report, human: render(report) };
+}
+
+/** 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})`}`, ""];
+  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})`)), "");
+  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}`), "");
+  if (report.missing.length > 0) lines.push("## Missing", "", ...report.missing.map((id) => `- ${id} is defined nowhere`), "");
+  return lines.join("\n").trimEnd();
+}
+
+function blocks(elements                )           {
+  if (elements.length === 0) return ["None.", ""];
+  return elements.flatMap((element) => [`<!-- ${element.source} -->`, ...element.body.join("\n").trimEnd().split("\n"), ""]);
+}

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

@@ -32,9 +32,25 @@ export async function runStatus(context            , _args          , options
     }
   }
   for (const change of report.standalone) lines.push(`${describe(`change ${change.ref}`, change.approval)}, tasks ${change.tasksDone}/${change.tasksTotal}`);
-  return { json: report, human: lines.join("\n") };
+  const json = {
+    ...report,
+    documents: report.documents.map(compact),
+    features: report.features.map((f) => ({ ...f, approval: compact(f.approval), changes: f.changes.map((c) => ({ ...c, approval: compact(c.approval) })) })),
+    standalone: report.standalone.map((c) => ({ ...c, approval: compact(c.approval) })),
+  };
+  return { json, human: lines.join("\n") };
 }
 
+/** The state without the record's hashes: an agent reads status often, and the hashes were a third of each read. */
+function compact(status                )                                                                                        {
+  const { record, ...rest } = status;
+  if (record === undefined) return rest;
+  return { ...rest, approvedAt: record.approvedAt, by: record.by, ...(record.basis === undefined ? {} : { basis: record.basis }) };
+}
+
+/** 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.";
+
 const BASIS                         = { "plan-review": " (by the agent, after its plan review)", rethink: " (re-stamped by the agent after a rethink)" };
 
 function describe(label        , status                )         {
@@ -46,6 +62,6 @@ function describe(label        , status                )         {
 export async function runNext(context            )                         {
   const report = await suggestNext(context);
   const describe = (s                                                   )         => `${s.step}${s.target === undefined ? "" : ` ${s.target}`}: ${s.reason}`;
-  const lines = [`Next: ${describe(report.next)}`, ...report.also.map((s) => `Also: ${describe(s)}`)];
-  return { json: report, human: lines.join("\n") };
+  const lines = [`Next: ${describe(report.next)}`, ...report.also.map((s) => `Also: ${describe(s)}`), FRESH_SESSION];
+  return { json: { ...report, session: FRESH_SESSION }, human: lines.join("\n") };
 }

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

@@ -7,6 +7,7 @@ import { runRealign } from "./commands/realign.js";
 import { runFeedback, runJournal } from "./commands/journal.js";
 import { runAbandon, runFeatures, runRoadmap, runTask } from "./commands/progress.js";
 import { runReviewCommand } from "./commands/review.js";
+import { runShow } from "./commands/show.js";
 import { runNext, runStatus } from "./commands/status.js";
 
 /** A command, and the options it takes: one list, or one per subcommand for a command that has them. */
@@ -22,6 +23,7 @@ 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" },
   approve: {
     handler: runApprove,
     options: ["replan", "rebase", "by-agent", "restamp-unchanged"],
@@ -35,7 +37,7 @@ export const COMMANDS                          = {
   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>]" },
   roadmap: { handler: runRoadmap, options: { prune: [] }, usage: "roadmap prune                                     clear landed items from the roadmap status when a release closes" },
-  journal: { handler: runJournal, options: { add: ["set", "item"], list: ["event", "item"] }, usage: "journal <add <event> --set key=value... [--item <ref>]|list [--event <event>] [--item <ref>]>" },
+  journal: { handler: runJournal, options: { add: ["set", "item"], list: ["event", "item", "all"] }, usage: "journal <add <event> --set key=value... [--item <ref>]|list [--event <event>] [--item <ref>] [--all]>" },
   review: { handler: runReviewCommand, options: ["item", "round", "blockers", "base"], usage: "review <role> [--item <ref>] [--round 1|2 --blockers <file>] [--base <commit>]   run a role in a fresh agent context" },
   feedback: { handler: runFeedback, options: { export: ["out", "no-redact"] }, usage: "feedback export [--out <file>] [--no-redact]" },
   trace: { handler: runTrace, options: ["all", "change"], usage: "trace [--all] [--change <ref>]                    link scenarios to the tests that prove them" },

package/dist/adapters/outbound/git_repository.js

@@ -1,4 +1,4 @@
-import { execFile } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { promisify } from "node:util";
                                                                 
 
@@ -37,13 +37,24 @@ export class GitRepository                       {
   }
 
   async filesOnBranch(branch        , dir        )                               {
-    const files = new Map                ();
     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]]                    ])));
+  }
+
+  /** 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) => {
+      const child = spawn("git", ["cat-file", "--batch"], { cwd: this.root, stdio: ["pipe", "pipe", "ignore"] });
+      const chunks           = [];
+      child.stdout.on("data", (chunk        ) => 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`);
+    });
   }
 
           async git(...args          )                         {
@@ -55,3 +66,25 @@ export class GitRepository                       {
     }
   }
 }
+
+/** Splits `git cat-file --batch` output: a `<sha> <type> <size>` header, the bytes and a newline, or `<name> missing`. */
+function parseBatch(output        , count        )                            {
+  const results                            = [];
+  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/dist/adapters/outbound/project_root.js

@@ -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        )                     {
+  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/dist/app/use_cases/approve_artifact.js

@@ -15,6 +15,8 @@ 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 { SIZE_RULES } from "../../domain/validation/size_rules.js";
 import { validateProject } from "../../domain/validation/validate_project.js";
 import { appendJournal, loadView, withFiles,                  } from "../project_context.js";
 
@@ -87,11 +89,13 @@ export async function approveArtifact(deps             , ref        , options
   if (text !== view.snapshot.get(path)) edits.set(path, text);
   view = withFiles(view, edits);
 
-  const errors = validateProject(view).filter((p) => p.path === path && p.severity === "error");
+  const problems = validateProject(view).filter((p) => p.path === path);
+  const errors = problems.filter((p) => p.severity === "error");
   if (errors.length > 0) {
     const listing = errors.map((p) => `  ${p.path}:${p.line ?? ""} ${p.message}`).join("\n");
     throw new CruzeError("invalid", `${path} has ${errors.length} problem(s) to fix before approval:\n${listing}`);
   }
+  requireSizesAccepted(problems, path);
 
   const { hash, upstream } = fingerprint(view, path, parseMarkdown(text));
   const folder = approvalFolder(view, path);
@@ -154,6 +158,20 @@ function requireRebased(view             , deltaIds             , previous
   }
 }
 
+/**
+ * A size warning stands until the work is split or the user accepts it under `changes.exceptions`.
+ * A 28-task change approved over its warning went on to 26 deviations, so approval waits for one or the other.
+ */
+function requireSizesAccepted(problems           , path        )       {
+  const standing = problems.filter((p) => SIZE_RULES.includes(p.rule));
+  if (standing.length === 0) return;
+  const listing = standing.map((p) => `  ${p.message} [${p.rule}]`).join("\n");
+  throw new CruzeError(
+    "size-unaccepted",
+    `${path} has ${standing.length} size warning(s). Split the work through rethink, or record the user's acceptance under changes.exceptions in .cruze/config.yaml, as the item's ref and their reason:\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

@@ -6,6 +6,7 @@ import { FIRST_RELEASE, isPending } from "../../domain/versions/rule_versions.js
                                                           
                                                                         
 import { resolveChange } from "../../domain/project/artifact_ref.js";
+import { readDelta } from "../../domain/project/deltas.js";
 import { activeChange } from "../../domain/status/work_status.js";
 import { traceScenarios,                  } from "../../domain/trace.js";
 import { loadView,                  } from "../project_context.js";
@@ -88,8 +89,14 @@ function globBase(glob        )         {
   return fixed.join("/");
 }
 
+/**
+ * Every module's Path: the living docs' modules, and the modules that work in progress adds or
+ * changes in its architecture delta, since their files are written before land merges them.
+ */
 function modulePaths(view             )           {
-  return [...view.living.elements.values()]
-    .filter((e) => e.id.startsWith("MOD-"))
-    .flatMap((e) => (factsOf(e.doc, e.element).get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? "")));
+  const living = [...view.living.elements.values()].filter((e) => e.id.startsWith("MOD-")).map((e) => ({ doc: e.doc, element: e.element }));
+  const inFlight = view.items
+    .filter((item) => item.kind !== "change" && !item.archived)
+    .flatMap((item) => readDelta(item.doc).entries.filter((entry) => entry.element.id.startsWith("MOD-") && entry.element.op !== "REMOVED").map((entry) => ({ doc: item.doc, element: entry.element })));
+  return [...living, ...inFlight].flatMap(({ doc, element }) => (factsOf(doc, element).get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? "")));
 }

package/dist/app/use_cases/journal_events.js

@@ -18,16 +18,19 @@ export async function recordEvent(deps             , event        , fields
   return appendJournal(deps, folder, event, { ...recorded, cruze: deps.bundle.version });
 }
 
-/** The journal, or one feature's or change's part of it: its own journal, and a feature's changes' too. */
-export async function listEvents(deps             , event         , item         )                          {
+/**
+ * The journal of the work in flight and the project, or of one feature or change (a feature's changes' too).
+ * Landed work's entries are history, listed only with `all`, since every entry ever recorded is too much to read.
+ */
+export async function listEvents(deps             , event         , item         , all = false)                          {
   const view = await loadView(deps.files);
-  let entries = view.journal;
+  let folders = [".cruze", ...view.items.filter((i) => all || !i.archived).map((i) => i.folder)];
   if (item !== undefined) {
     const resolved = resolveArtifact(view, item).item;
     if (resolved === undefined) throw new CruzeError("not-found", `"${item}" is not a feature or change`);
-    const parts = [resolved, ...view.items.filter((i) => resolved.kind === "feature" && i.featureRef === resolved.ref)];
-    entries = parts.flatMap((part) => parseJournal(view.snapshot.get(journalPath(part.folder))).entries).sort((a, b) => a.at.localeCompare(b.at));
+    folders = [resolved, ...view.items.filter((i) => resolved.kind === "feature" && i.featureRef === resolved.ref)].map((part) => part.folder);
   }
+  const entries = folders.flatMap((folder) => parseJournal(view.snapshot.get(journalPath(folder))).entries).sort((a, b) => a.at.localeCompare(b.at));
   return event === undefined ? entries : entries.filter((entry) => entry.event === event);
 }
 

package/dist/app/use_cases/project_status.js

@@ -1,4 +1,5 @@
 import { CruzeError } from "../../domain/cruze_error.js";
+import { PATHS } from "../../domain/project/layout.js";
 import { readProgress } from "../../domain/project/progress.js";
 import { buildProjectView } from "../../domain/project/project_view.js";
 import { findWorkItem,               } from "../../domain/project/work_items.js";
@@ -59,7 +60,9 @@ export async function findOverlaps(deps             , ref         )
   const mine = touchedIds(view, change);
   const overlaps            = [];
   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/dist/app/use_cases/show_scope.js

@@ -0,0 +1,37 @@
+import { CruzeError } from "../../domain/cruze_error.js";
+import { resolveArtifact } from "../../domain/project/artifact_ref.js";
+import { scopeView,                } from "../../domain/project/scope_view.js";
+import { loadView,                  } from "../project_context.js";
+import { listEvents } from "./journal_events.js";
+
+                              
+                  
+                      
+                 
+                 
+ 
+
+                                                
+                                                                                                               
+                              
+                                                                                                        
+                                                   
+ 
+
+/**
+ * The design a change builds, or a feature's whole delta, with the elements it cites and the
+ * item's settled ledger: what plan, build and the reviewers read instead of the whole living docs.
+ */
+export async function showScope(deps             , ref        )                       {
+  const view = await loadView(deps.files);
+  const { item } = resolveArtifact(view, ref);
+  if (item === undefined) throw new CruzeError("not-work", `"${ref}" is not a feature or change; show takes a feature or change ID`);
+  const scope = scopeView(view, item);
+  const dispositions = (await listEvents(deps, "disposition", scope.feature ?? item.ref, true)).map((entry) => ({
+    finding: String(entry["finding"] ?? ""),
+    disposition: String(entry["disposition"] ?? ""),
+    reason: String(entry["reason"] ?? ""),
+    review: String(entry["review"] ?? ""),
+  }));
+  return { ...scope, dispositions, references: view.config?.config?.references ?? [] };
+}

package/dist/domain/check/budget_text.js

@@ -0,0 +1,61 @@
+/**
+ * The part of a source file its budgets measure. Budgets apply to source, not tests, so a Rust
+ * file's test-only modules are left out: rustfmt closes a top-level module with `}` in column 0.
+ * A module is test-only when its `cfg` needs `test`, as `#[cfg(test)]` or
+ * `#[cfg(all(test, feature = "schema"))]` do; other attributes may sit between the two.
+ */
+export function budgetedText(path        , text        )         {
+  if (!path.endsWith(".rs")) return text;
+  const lines = text.split("\n");
+  const kept           = [];
+  for (let i = 0; i < lines.length; i++) {
+    const start = testModuleStart(lines, i);
+    if (start === null) {
+      kept.push(lines[i] ?? "");
+      continue;
+    }
+    if ((lines[start] ?? "").trimEnd().endsWith(";")) {
+      i = start;
+      continue;
+    }
+    let end = start + 1;
+    while (end < lines.length && lines[end] !== "}") end++;
+    i = end;
+  }
+  return kept.join("\n");
+}
+
+/** The line of the `mod` a test-only `cfg` at `index` gates, or null when it gates no module. */
+function testModuleStart(lines          , index        )                {
+  if (!needsTest(lines[index]?.trim() ?? "")) return null;
+  let next = index + 1;
+  while (/^\s*#\[/.test(lines[next] ?? "")) next++;
+  return /^(?:pub(?:\([^)]*\))?\s+)?mod\s+\w+\s*[{;]/.test(lines[next] ?? "") ? next : null;
+}
+
+function needsTest(attribute        )          {
+  const predicate = /^#\[cfg\((.*)\)\]$/.exec(attribute)?.[1]?.trim();
+  if (predicate === undefined) return false;
+  if (predicate === "test") return true;
+  const all = /^all\((.*)\)$/.exec(predicate)?.[1];
+  return all !== undefined && topLevelArguments(all).includes("test");
+}
+
+/** Splits `a, b(c, d), e` at its top-level commas. */
+function topLevelArguments(text        )           {
+  const parts           = [];
+  let depth = 0;
+  let current = "";
+  for (const char of text) {
+    if (char === "," && depth === 0) {
+      parts.push(current.trim());
+      current = "";
+      continue;
+    }
+    if (char === "(") depth++;
+    if (char === ")") depth--;
+    current += char;
+  }
+  parts.push(current.trim());
+  return parts;
+}

package/dist/domain/check/check_source.js

@@ -1,5 +1,6 @@
                                                        
 import { matchesAny } from "../glob.js";
+import { budgetedText } from "./budget_text.js";
 import { importsOf, resolveImport } from "./imports.js";
 import { countTypes } from "./type_count.js";
 
@@ -50,13 +51,15 @@ export function checkSource(input            )                 {
       }
     }
     const excepted = config.check.exceptions.some((exception) => exception.path === path);
-    const lines = text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
+    const budgeted = budgetedText(path, text);
+    const lines = budgeted.split("\n").length - (budgeted.endsWith("\n") ? 1 : 0);
     if (!excepted && lines > config.check.maxLines) {
-      findings.push({ path, rule: "max-lines", severity: "warning", message: `${lines} lines, over the budget of ${config.check.maxLines}; split it by responsibility` });
+      const measured = budgeted === text ? "" : ", not counting its inline tests";
+      findings.push({ path, rule: "max-lines", severity: "warning", message: `${lines} lines${measured}, over the budget of ${config.check.maxLines}; split it if it holds a second responsibility, or list it under check.exceptions` });
     }
-    const types = countTypes(path, text);
+    const types = countTypes(path, budgeted);
     if (!excepted && types !== null && types > config.check.maxTypes) {
-      findings.push({ path, rule: "max-types", severity: "warning", message: `${types} top-level types, over the budget of ${config.check.maxTypes}` });
+      findings.push({ path, rule: "max-types", severity: "warning", message: `${types} top-level types, over the budget of ${config.check.maxTypes}; split it if it holds a second responsibility, or list it under check.exceptions` });
     }
     if (!excepted && isRustTestFileInSource(path)) {
       findings.push({ path, rule: "test-placement", severity: "warning", message: "Rust tests that leave their inline module go in the crate's tests/ directory, not under src/" });

package/dist/domain/config.js

@@ -26,6 +26,8 @@ import { parse as parseYaml } from "yaml";
                                                        
                                                                                          
                         
+                                                                                                                     
+                                                   
  
 
 /** Which review findings the user decides: only the exceptions, or every one. */
@@ -38,9 +40,11 @@ import { parse as parseYaml } from "yaml";
                        
                                                  
                    
+                                                                                               
+                                                      
  
 
-export const DEFAULT_CHANGE_LIMITS               = { minBuilds: 3, maxScenarios: 30, maxTasks: 25 };
+export const DEFAULT_CHANGE_LIMITS               = { minBuilds: 3, maxScenarios: 30, maxTasks: 25, exceptions: [] };
 
                         
                
@@ -120,8 +124,25 @@ export function parseConfig(text        )               {
     minBuilds: positiveInt(limits["min_builds"], "changes.min_builds", problems) ?? DEFAULT_CHANGE_LIMITS.minBuilds,
     maxScenarios: positiveInt(limits["max_scenarios"], "changes.max_scenarios", problems) ?? DEFAULT_CHANGE_LIMITS.maxScenarios,
     maxTasks: positiveInt(limits["max_tasks"], "changes.max_tasks", problems) ?? DEFAULT_CHANGE_LIMITS.maxTasks,
+    exceptions: (Array.isArray(limits["exceptions"]) ? limits["exceptions"] : []).flatMap((entry         , i        ) => {
+      const record = asRecord(entry);
+      if (typeof record?.["item"] !== "string" || typeof record["reason"] !== "string" || record["reason"].trim() === "") {
+        problems.push(`changes.exceptions[${i}] needs an item and a non-empty reason`);
+        return [];
+      }
+      return [{ item: record["item"], reason: record["reason"] }];
+    }),
   };
 
+  const references = (Array.isArray(root["references"]) ? root["references"] : root["references"] === undefined ? [] : [null]).flatMap((entry         , i        ) => {
+    const record = asRecord(entry);
+    if (typeof record?.["path"] !== "string" || record["path"].trim() === "" || typeof record["use"] !== "string" || record["use"].trim() === "") {
+      problems.push(`references[${i}] needs a path and a non-empty use`);
+      return [];
+    }
+    return [{ path: record["path"], use: record["use"] }];
+  });
+
   const config              = {
     version: 1,
     ...(typeof cruze === "string" && cruze.trim() !== "" ? { cruze } : {}),
@@ -138,6 +159,7 @@ export function parseConfig(text        )               {
       decide: decide === "all" ? "all" : "exceptions",
     },
     changes,
+    references,
   };
   return { config, problems };
 }

package/dist/domain/edits/agents_file.js

@@ -19,9 +19,14 @@ export function renderAgentsFile(text        , view             )         {
   return next;
 }
 
+/**
+ * The modules whose code exists: those built, and those a land built before a rethink set them
+ * back to `planned` for a change to rebuild, since their directories are still there.
+ */
 function builtModules(view             )           {
+  const everBuilt = new Set(view.journal.filter((e) => e.event === "land").flatMap((e) => (Array.isArray(e["built"]) ? (e["built"]             ).map(String) : [])));
   return [...view.living.elements.values()]
-    .filter(({ element, doc }) => element.kind === "MOD" && statusOf(doc, element) === "built")
+    .filter(({ element, doc }) => element.kind === "MOD" && (statusOf(doc, element) === "built" || everBuilt.has(element.id)))
     .map(({ element, doc }) => {
       const facts = factsOf(doc, element);
       const paths = (facts.get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => `\`${m[1] ?? ""}\``));

package/dist/domain/journal.js

@@ -23,6 +23,7 @@ const OPTIONAL_FIELDS                           = {
   rethink: ["missed_by"],
   review: ["nits", "checked_by"],
   disposition: ["decided"],
+  verification: ["back_to"],
 };
 
 /** The workflow steps and checks that find or miss a problem, so a retro can count them. */
@@ -35,11 +36,21 @@ export const FIELD_VALUES                           = {
   decided: ["agent", "user"],
   review: ["design", "plan", "code", "realign", "improve"],
   result: ["accepted", "sent-back"],
+  back_to: ["build", "rethink"],
   checked_by: ["agent", "reviewer"],
   found_by: STEPS,
   missed_by: STEPS,
 };
 
+/** A defect rethink must say which step missed it, and a sent-back verification where the change goes back to. */
+function conditionallyRequired(event        , fields                        )           {
+  if (event === "rethink" && fields["kind"] === "defect") return ["missed_by"];
+  if (event === "verification" && fields["result"] === "sent-back") return ["back_to"];
+  return [];
+}
+
+const CONDITION_NOTES                         = { missed_by: " for a defect", back_to: " when the change is sent back" };
+
 /** Fields recorded as numbers rather than text. */
 const COUNT_FIELDS = ["round", "blockers", "concerns", "nits"];
 
@@ -71,8 +82,8 @@ export function serializeEntry(entry              )         {
 export function recordedEventProblems(event        , fields                        )           {
   const required = RECORDED_EVENTS[event];
   if (required === undefined) return [`unknown event "${event}"; recordable events: ${Object.keys(RECORDED_EVENTS).join(", ")}`];
-  const needed = event === "rethink" && fields["kind"] === "defect" ? [...required, "missed_by"] : required;
-  const problems = needed.filter((field) => (fields[field] ?? "").trim() === "").map((field) => `${event} needs ${field}${field === "missed_by" ? " for a defect" : ""}`);
+  const needed = [...required, ...conditionallyRequired(event, fields)];
+  const problems = needed.filter((field) => (fields[field] ?? "").trim() === "").map((field) => `${event} needs ${field}${CONDITION_NOTES[field] ?? ""}`);
   const known = [...required, ...(OPTIONAL_FIELDS[event] ?? [])];
   for (const field of known) {
     const value = fields[field];