@printpractical/cruze 0.0.7 → 0.0.9

package/dist/domain/project/scope_view.js

@@ -0,0 +1,134 @@
+import { elementLines,                            } from "../elements.js";
+import { findIds } from "../ids.js";
+import { findSection,                  } from "../markdown.js";
+import { readDelta } from "./deltas.js";
+import { readScope } from "./plan_parts.js";
+                                                     
+import { featureOf,                                  } from "./work_items.js";
+
+/**
+ * The design a piece of work builds, cut out of the documents that hold it, so a step reads
+ * the elements in its scope instead of the whole architecture and the whole feature.
+ */
+
+                               
+             
+                
+               
+                                                       
+                 
+                 
+ 
+
+                               
+             
+                
+                 
+ 
+
+                            
+              
+                     
+                   
+                                                                                                           
+                           
+                                                                                               
+                            
+                                                                                   
+                        
+                                                                         
+                      
+                                                                                       
+                            
+                                                                              
+                    
+ 
+
+                   
+                   
+               
+                   
+ 
+
+export function scopeView(view             , item          )            {
+  const feature = featureOf(view.items, item);
+  const deltaItem = feature ?? item;
+  const locate = locator(view, deltaItem);
+  const wanted = item.kind === "change" || item.kind === "standalone" ? changeIds(item) : featureIds(deltaItem);
+  const missing           = [];
+  const show = (ids          )                 =>
+    ids.flatMap((id) => {
+      const found = locate(id);
+      if (found === undefined) {
+        missing.push(id);
+        return [];
+      }
+      const shown               = { id, title: found.element.title, source: `${found.path}:${found.element.start + 1}`, body: elementLines(found.doc, found.element) };
+      if (found.element.op !== undefined) shown.op = found.element.op;
+      return [shown];
+    });
+  const elements = show(wanted.elements);
+  const scenarios = withoutRepeatedScenarios(show(wanted.scenarios));
+  const shownIds = new Set([...elements, ...scenarios].map((e) => e.id));
+  const cited = [...new Set([...elements, ...scenarios].flatMap((e) => findIds(e.body.join("\n"))))]
+    .filter((id) => !shownIds.has(id))
+    .flatMap((id) => {
+      const found = locate(id);
+      return found === undefined ? [] : [{ id, title: found.element.title, source: `${found.path}:${found.element.start + 1}` }];
+    });
+  const decisions = decisionLines((feature ?? item).doc);
+  const changeDecisions = feature === undefined ? [] : decisionLines(item.doc);
+  const result            = { ref: item.ref, kind: item.kind, elements, scenarios, cited, decisions, changeDecisions, missing };
+  if (feature !== undefined) result.feature = feature.ref;
+  return result;
+}
+
+/**
+ * A requirement shown beside its own scenarios keeps only its own text: its body would repeat
+ * each of them, which made up a third of one change's output.
+ */
+function withoutRepeatedScenarios(shown                )                 {
+  const ids = new Set(shown.map((e) => e.id));
+  return shown.map((element) => {
+    if (!element.id.startsWith("REQ-")) return element;
+    const first = element.body.findIndex((line, i) => i > 0 && /^#{2,6} /.test(line) && findIds(line).some((id) => ids.has(id)));
+    return first === -1 ? element : { ...element, body: element.body.slice(0, first) };
+  });
+}
+
+/** A change shows what its scope builds, removes and delivers. */
+function changeIds(change          )                                              {
+  const scope = readScope(change.doc);
+  return { elements: [...(scope?.builds ?? []), ...(scope?.removes ?? [])], scenarios: scope?.delivers ?? [] };
+}
+
+/** A feature shows its whole delta: every operation, with a requirement's scenarios inside its body. */
+function featureIds(feature          )                                              {
+  const entries = readDelta(feature.doc).entries;
+  return {
+    elements: entries.filter((e) => e.section === "architecture").map((e) => e.element.id),
+    scenarios: entries.filter((e) => e.section === "spec").map((e) => e.element.id),
+  };
+}
+
+/** Finds an element's body in the work's own delta first, since that is the text the work builds, then in the living docs. */
+function locator(view             , deltaItem          )                                      {
+  const delta = readDelta(deltaItem.doc);
+  const inDelta = new Map                 ();
+  for (const entry of delta.entries) {
+    inDelta.set(entry.element.id, entry.element);
+    for (const scenario of entry.scenarios) inDelta.set(scenario.id, scenario);
+  }
+  return (id) => {
+    const own = inDelta.get(id);
+    if (own !== undefined) return { doc: deltaItem.doc, path: deltaItem.path, element: own };
+    const living = view.living.elements.get(id);
+    return living === undefined ? undefined : { doc: living.doc, path: living.path, element: living.element };
+  };
+}
+
+function decisionLines(doc             )           {
+  const section = findSection(doc, "Settled decisions");
+  if (section === null) return [];
+  return doc.lines.slice(section.start, section.end).filter((line) => line.startsWith("- "));
+}

package/dist/domain/status/next_step.js

@@ -7,7 +7,7 @@ import { readRoadmapItems, readRoadmapStatus } from "../project/roadmap.js";
 import { changesOf, featureOf,               } from "../project/work_items.js";
 import { compareVersions } from "../versions/cruze_version.js";
 import { FIRST_RELEASE } from "../versions/rule_versions.js";
-import { isVerified } from "./verification.js";
+import { awaitsRethink, isVerified } from "./verification.js";
 import { activeChange } from "./work_status.js";
 
 /** The Cruze step to run next, computed from the project's state and the current branch. */
@@ -31,7 +31,7 @@ export function nextSteps(view             , branch               )
   const project = projectStep(view);
   if (project !== null) return { next: project, also: [] };
   const active = activeChange(view, branch);
-  const inFlight = view.items.filter((item) => !item.archived && item.kind !== "change").flatMap((item) => itemSteps(view, item, branch));
+  const inFlight = inRoadmapOrder(view, view.items.filter((item) => !item.archived && item.kind !== "change")).flatMap((item) => itemSteps(view, item, branch));
   const roadmap = roadmapStep(view);
   const realign = realignStep(view);
   const candidates = [
@@ -45,6 +45,28 @@ export function nextSteps(view             , branch               )
   return { next: next ?? { step: "roadmap", reason: "every item on the roadmap has landed; close the release and plan the next" }, also };
 }
 
+/**
+ * Work in flight in the roadmap's order, with items whose roadmap blockers haven't all landed
+ * last: a feature designed early still waits for the prefactors the user put before it.
+ */
+function inRoadmapOrder(view             , items            )             {
+  const text = view.snapshot.get(PATHS.roadmap);
+  if (text === undefined) return items;
+  const rows = readRoadmapStatus(text);
+  const state = new Map(rows.map((row) => [row.slug, row.state]));
+  const slugOf = new Map(rows.map((row) => [row.id, row.slug]));
+  const roadmap = readRoadmapItems(text);
+  const rank = (item          )                   => {
+    const at = roadmap.findIndex((r) => r.slug === slugOf.get(item.ref));
+    const blocked = at !== -1 && (roadmap[at]?.blockedBy ?? []).some((b) => state.get(b) !== "landed");
+    return [blocked ? 1 : 0, at === -1 ? roadmap.length : at];
+  };
+  return items
+    .map((item, i) => ({ item, key: [...rank(item), i] }))
+    .sort((a, b) => (a.key[0] ?? 0) - (b.key[0] ?? 0) || (a.key[1] ?? 0) - (b.key[1] ?? 0) || (a.key[2] ?? 0) - (b.key[2] ?? 0))
+    .map(({ item }) => item);
+}
+
 /** Realign comes when nothing else is due: the installed skills expect more than the code meets. */
 function realignStep(view             )                  {
   const config = view.config?.config;
@@ -117,6 +139,7 @@ function changeStep(view             , change          , branch               )
   if (!isPlanned(change.doc)) return { step: "plan", target: change.ref, reason: "the change is designed but has no test plan or tasks yet" };
   if (state.state === "unapproved") return { step: "plan", target: change.ref, reason: "review the plan and approve it on the branch that will build it" };
   if (state.state !== "approved") return { step: "rethink", target: change.ref, reason: `the change or something it cites changed since its approval${state.changed.length > 0 ? ` (${state.changed.join(", ")})` : ""}` };
+  if (awaitsRethink(view.journal, change, feature)) return { step: "rethink", target: feature?.ref ?? change.ref, reason: `verify sent ${change.ref} back for a design change` };
   if (bound !== undefined && bound !== branch) return { step: "switch-branch", target: bound, reason: `${change.ref} is built on branch ${bound}` };
   const progress = readProgress(change.doc);
   if ([...progress.tasks.values()].some((commit) => commit === null)) return { step: "build", target: change.ref, reason: "the change has open tasks" };

package/dist/domain/status/verification.js

@@ -15,3 +15,15 @@ export function isVerified(journal                , change          )          {
   const verifiedHash = approvals.filter((e) => e.at < verification.at).at(-1)?.["hash"];
   return approvals.filter((e) => e.at > verification.at).every((e) => e["hash"] === verifiedHash);
 }
+
+/**
+ * Whether verify sent the change back for a rethink that hasn't been recorded yet. Tasks the
+ * agent reopens at verify would otherwise make the change look ready to build again.
+ */
+export function awaitsRethink(journal                , change          , feature                      )          {
+  const verification = journal.filter((e) => e.event === "verification" && e["item"] === change.ref).sort((a, b) => a.at.localeCompare(b.at)).at(-1);
+  if (verification?.["result"] !== "sent-back" || verification["back_to"] !== "rethink") return false;
+  // An architecture-level rethink records no item, and counts too.
+  const refs = new Set([change.ref, feature?.ref, undefined]);
+  return !journal.some((e) => e.event === "rethink" && e.at > verification.at && refs.has(e["item"]                      ));
+}

package/dist/domain/status/work_status.js

@@ -1,7 +1,7 @@
 import { evaluateApproval,                     } from "../approvals/evaluate.js";
 import { PATHS } from "../project/layout.js";
 import { readDelta } from "../project/deltas.js";
-import { readScope } from "../project/plan_parts.js";
+import { readChangesTable, readScope } from "../project/plan_parts.js";
 import { readProgress } from "../project/progress.js";
                                                               
 import { changesOf, featureOf,               } from "../project/work_items.js";
@@ -80,12 +80,23 @@ export function buildGateReasons(view             , branch               )
   const feature = featureOf(view.items, change);
   if (feature !== undefined) required.push(feature.path);
   if (view.snapshot.has(PATHS.architecture)) required.push(PATHS.architecture);
-  return required.flatMap((path) => {
+  const approvals = required.flatMap((path) => {
     const status = evaluateApproval(view, path);
     if (status.state === "approved") return [];
     const detail = status.changed.length > 0 ? `: ${status.changed.join(", ")} changed` : status.unjournaled === true ? ": the approval has no journal entry" : "";
     return [`${path} is ${status.state}${detail}`];
   });
+  return [...approvals, ...unlandedDependencies(view, change, feature)];
+}
+
+/** The changes this change's row in its feature's Changes table depends on that haven't landed on this branch. */
+function unlandedDependencies(view             , change          , feature                      )           {
+  if (feature === undefined) return [];
+  const row = readChangesTable(feature.doc).find((r) => r.change === change.folderName);
+  const landed = new Set(changesOf(view.items, feature).filter((c) => readProgress(c.doc).landed !== undefined).map((c) => c.folderName));
+  return (row?.dependsOn ?? [])
+    .filter((dependency) => !landed.has(dependency))
+    .map((dependency) => `${change.ref} depends on ${dependency}, which hasn't landed here; land it, then merge main into this branch`);
 }
 
 /** The elements a change touches: its scope and its delta, not the elements it only cites, such as a test seam. */

package/dist/domain/validation/element_rules.js

@@ -41,6 +41,11 @@ export function elementProblems(path        , doc             , element
       problems.push(error(path, element.start, "fact-value", `${element.id} ${key} must be one of ${rule.values.join(", ")}`));
     }
   }
+  if (element.kind === "MOD") {
+    for (const glob of (facts.get("Path") ?? []).flatMap((value) => [...value.matchAll(/`([^`]+)`/g)].map((m) => m[1] ?? "")).filter((p) => /[*?[{]/.test(p))) {
+      problems.push(error(path, element.start, "module-path-glob", `${element.id} Path \`${glob}\` is a glob, which matches no file; name a directory ending in / or a single file, one per Path value`));
+    }
+  }
   const module = facts.get("Module")?.[0];
   if (module !== undefined && !findIds(module).some((id) => id.startsWith("MOD-"))) {
     problems.push(error(path, element.start, "fact-value", `${element.id} Module must name a MOD element`));

package/dist/domain/validation/plan_rules.js

@@ -46,7 +46,7 @@ export function changePlanProblems(
     if (kindOf(id) === "MOD") {
       const modulePaths = modulePathsOf(view, delta.doc, delta.delta, id);
       if (!taskPaths.some((p) => modulePaths.some((m) => p.startsWith(m)))) {
-        problems.push(error(path, scope.line, "unproved-scope", `${id} is in scope but no task writes inside ${modulePaths.join(" or ") || "its path"}`));
+        problems.push(error(path, scope.line, "unproved-scope", `${id} is in scope but no task writes inside ${modulePaths.join(" or ") || "its path"}; a module that owns other files, such as a build script, lists each under its Path`));
       }
     } else if (kindOf(id) === "REQ") {
       const scenarios = delta.delta.entries.find((e) => e.element.id === id)?.scenarios.map((s) => s.id) ?? [];

package/dist/domain/validation/size_rules.js

@@ -12,17 +12,25 @@ export function changeLimits(view             )               {
   return view.config?.config?.changes ?? DEFAULT_CHANGE_LIMITS;
 }
 
+/** The rules a size warning comes from. An item stays outside the band only with the user's recorded acceptance. */
+export const SIZE_RULES = ["feature-size", "change-too-small", "change-too-large", "plan-too-large"];
+
+/** Whether the user accepted this feature or change outside the band, under `changes.exceptions`. */
+export function sizeAccepted(view             , ref        )          {
+  return changeLimits(view).exceptions.some((exception) => exception.item === ref);
+}
+
 /** A feature's changes not yet landed that fall outside the size band. A feature of one change has nothing to merge into. */
-export function changeRowSizeProblems(view             , path        , rows             , landed             )            {
+export function changeRowSizeProblems(view             , feature                               , rows             , landed             )            {
   const limits = changeLimits(view);
   const problems            = [];
-  for (const row of rows.filter((r) => !landed.has(r.change))) {
+  for (const row of rows.filter((r) => !landed.has(r.change) && !sizeAccepted(view, `${feature.ref}/${r.change}`))) {
     if (rows.length > 1 && row.builds.length < limits.minBuilds) {
-      problems.push(warning(path, row.line, "change-too-small", `${row.change} builds ${row.builds.length} element(s), under ${limits.minBuilds}; merge it into the change it continues, since each change pays for its own plan, review and verify`));
+      problems.push(warning(feature.path, row.line, "change-too-small", `${row.change} builds ${row.builds.length} element(s), under ${limits.minBuilds}; merge it into the change it continues, since each change pays for its own plan, review and verify`));
     }
     const scenarios = row.delivers.filter((id) => kindOf(id) === "SCN").length;
     if (scenarios > limits.maxScenarios) {
-      problems.push(warning(path, row.line, "change-too-large", `${row.change} delivers ${scenarios} scenarios, over ${limits.maxScenarios}; split it, since one verifier run has to go through them all`));
+      problems.push(warning(feature.path, row.line, "change-too-large", `${row.change} delivers ${scenarios} scenarios, over ${limits.maxScenarios}; split it, since one verifier run has to go through them all`));
     }
   }
   return problems;
@@ -31,6 +39,7 @@ export function changeRowSizeProblems(view             , path        , rows
 /** A plan with more tasks than one code review and one verify can hold. */
 export function planSizeProblems(view             , path        , tasks        )            {
   const { maxTasks } = changeLimits(view);
-  if (tasks <= maxTasks) return [];
+  const ref = view.items.find((item) => item.path === path)?.ref ?? path;
+  if (tasks <= maxTasks || sizeAccepted(view, ref)) return [];
   return [warning(path, undefined, "plan-too-large", `the plan has ${tasks} tasks, over ${maxTasks}; split the change through rethink at feature level`)];
 }

package/dist/domain/validation/work_item_rules.js

@@ -11,7 +11,7 @@ import { deltaProblems } from "./delta_rules.js";
 import { malformedIdHeadings, lineOf } from "./living_rules.js";
 import { changePlanProblems } from "./plan_rules.js";
 import { error, warning,              } from "./problem.js";
-import { changeRowSizeProblems } from "./size_rules.js";
+import { changeRowSizeProblems, sizeAccepted } from "./size_rules.js";
 
 const REQUIRED_SECTIONS                                     = {
   feature: ["Intent", "Spec delta", "Architecture delta", "Changes"],
@@ -45,6 +45,10 @@ function itemProblems(view             , item          )            {
   for (const cited of findIds(text).filter((cited) => !available.has(cited))) {
     problems.push(error(path, lineOf(text, cited), "unknown-id", `${cited} is cited but defined neither in the living docs nor in this work's deltas`));
   }
+  const dropped = droppedScenarios(view, delta);
+  for (const cited of findIds(text).filter((cited) => dropped.has(cited))) {
+    problems.push(error(path, lineOf(text, cited), "cites-dropped", `${cited} is cited, but ${dropped.get(cited)} in this work's delta leaves it out, so it won't exist once the work lands; describe it in words instead`));
+  }
   if (item.kind !== "change") problems.push(...deltaProblems(view, item));
   if (item.kind === "feature") problems.push(...featureScopeProblems(view, item, delta));
   // A landed change is history: its scope named what it built, which is now built.
@@ -69,10 +73,10 @@ function featureScopeProblems(view             , feature          , delta
   );
   const names = rows.map((row) => row.change);
   const extra = rows[MAX_CHANGES];
-  if (extra !== undefined) {
+  if (extra !== undefined && !sizeAccepted(view, feature.ref)) {
     problems.push(warning(feature.path, extra.line, "feature-size", `the feature has ${rows.length} changes, over ${MAX_CHANGES}; split it into features a single design review can hold`));
   }
-  problems.push(...changeRowSizeProblems(view, feature.path, rows, landedChanges));
+  problems.push(...changeRowSizeProblems(view, feature, rows, landedChanges));
   for (const row of rows) {
     if (!/^\d\d-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(row.change)) problems.push(error(feature.path, row.line, "change-name", `change "${row.change}" must be named NN-slug`));
     if (names.indexOf(row.change) !== names.lastIndexOf(row.change)) problems.push(error(feature.path, row.line, "change-name", `change ${row.change} is listed twice`));
@@ -151,3 +155,21 @@ function scopeIds(item          )           {
   const scope = readScope(item.doc);
   return scope === null ? [] : [...scope.delivers, ...scope.builds, ...scope.removes];
 }
+
+/**
+ * Living scenarios that a MODIFIED requirement in the delta leaves out, each with that requirement.
+ * Land drops them, so a citation of one passes validation now and breaks only at land.
+ */
+function droppedScenarios(view             , delta       )                      {
+  const dropped = new Map                ();
+  for (const entry of delta.entries.filter((e) => e.element.op === "MODIFIED" && kindOf(e.element.id) === "REQ")) {
+    const living = view.living.elements.get(entry.element.id);
+    if (living === undefined) continue;
+    const kept = new Set(entry.scenarios.map((s) => s.id));
+    for (const scenario of view.living.elements.values()) {
+      const nested = scenario.doc === living.doc && scenario.element.start > living.element.start && scenario.element.start < living.element.end;
+      if (nested && kindOf(scenario.id) === "SCN" && !kept.has(scenario.id) && !delta.ids.has(scenario.id)) dropped.set(scenario.id, entry.element.id);
+    }
+  }
+  return dropped;
+}

package/dist/domain/versions/rule_versions.js

@@ -16,6 +16,7 @@ export const RULE_SINCE                         = {
   "validate:change-too-small": "0.0.5",
   "validate:change-too-large": "0.0.5",
   "validate:plan-too-large": "0.0.5",
+  "validate:module-path-glob": "0.0.8",
 };
 
 /** Whether a rule arrived after the version the project's code meets, so it waits for `realign`. */

package/dist/main.js

@@ -1,27 +1,37 @@
 #!/usr/bin/env node
 // Composition root: the only place that constructs adapters.
-import { basename } from "node:path";
+import { basename, relative } from "node:path";
 import { runCli } from "./adapters/inbound/cli/run_cli.js";
 import { GitRepository } from "./adapters/outbound/git_repository.js";
 import { NodeProjectFiles } from "./adapters/outbound/node_project_files.js";
 import { PackageBundle } from "./adapters/outbound/package_bundle.js";
+import { findProjectRoot } from "./adapters/outbound/project_root.js";
 import { ProcessAgentRunner } from "./adapters/outbound/process_agent_runner.js";
 import { SystemClock } from "./adapters/outbound/system_clock.js";
 import { DefaultAnswerPrompter, TerminalPrompter } from "./adapters/outbound/terminal_prompter.js";
 
+// A reader that stops early, such as `cruze journal list | head`, closes the pipe; that is not an error worth a stack trace.
+process.stdout.on("error", (error                       ) => {
+  if (error.code === "EPIPE") process.exit(0);
+  throw error;
+});
+
 const cwd = process.cwd();
+// Every command but init works on the project that holds the working directory, so it runs from any subdirectory.
+const root = process.argv[2] === "init" ? cwd : (findProjectRoot(cwd) ?? cwd);
 const exitCode = await runCli(
   process.argv.slice(2),
   {
-    files: new NodeProjectFiles(cwd),
+    files: new NodeProjectFiles(root),
     bundle: await PackageBundle.locate(),
     clock: new SystemClock(),
-    repository: new GitRepository(cwd),
+    repository: new GitRepository(root),
     interactivePrompter: new TerminalPrompter(),
     unattendedPrompter: new DefaultAnswerPrompter(),
-    runner: new ProcessAgentRunner(cwd),
+    runner: new ProcessAgentRunner(root),
     interactive: process.stdin.isTTY === true,
     directoryName: basename(cwd),
+    workingDirectory: relative(root, cwd).split("\\").join("/"),
   },
   {
     stdout: (text) => process.stdout.write(`${text}\n`),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@printpractical/cruze",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "description": "Spec-driven development for coding agents: one living model of the system, small deltas, convergent review.",
   "license": "Apache-2.0",
   "author": "Chris Buchter",

package/skills/architect/SKILL.md

@@ -32,7 +32,8 @@ Architect decides the how and the how big. It designs the domain, the ports and
 
 - **Design for the roadmap, build for the phase.** Read the whole feature map and roadmap. When a later feature will need a seam, name it now in a `Future` fact, such as "transport will gain MQTT in phase 3, so inbound adapters stay behind `CommandSource`". Build only what the current work needs.
 - **Adopt before you build.** Before designing any component that isn't domain logic, run the researcher role from `.agents/skills/cruze-roles/SKILL.md` on it. Record every decision in `## Adopt or build`, or at project scope in the adapter's `Adopts` fact. Every new dependency goes to the user through the dependency-approval skill.
-- **Every element with code has a home.** Each `ENT`, `UC`, `PORT`, `ADP` and `FLOW` names its `Module` and `File`. Each file has one responsibility and fits the budget in `.cruze/config.yaml`.
+- **Every element with code has a home.** Each `ENT`, `UC`, `PORT`, `ADP` and `FLOW` names its `Module` and `File`. Each file has one responsibility. Never split an owner across files to keep them short.
+- **Comply with the references.** When the project must follow an external document, such as a protocol specification, it is listed under `references:` in `.cruze/config.yaml`; at project scope, ask the user whether there is one, and list it with what it governs. Read the parts each element relies on, and cite the section in the element's body, such as `RFC 4254 §5.2`, so plan, build and the reviewers can check it.
 - **Ask, challenge and defer** as the grilling skill describes. Contexts, ports, public contracts, dependency direction and dependencies are always the user's decisions.
 - **Stepping back is normal.** When the design shows that the vision or an earlier decision is wrong, stop and say so. The vision changes through `envision`, and an approved architecture through `rethink`.
 
@@ -41,3 +42,7 @@ Architect decides the how and the how big. It designs the domain, the ports and
 - Project scope: `plan` for the walking-skeleton change.
 - Feature scope: `plan` for the feature's first change.
 - Tweak scope: `plan` for the standalone change.
+
+Plan branches from main, so get the approved design onto main first, as a pull request or a merge, together with the vision or feature map it builds on. A plan branched from an unmerged design branch carries the design into the change's pull request.
+
+Start it in a new session, so its context starts empty.

package/skills/architect/feature.md

@@ -33,6 +33,6 @@ The result is a `feature.md` with a complete architecture delta and an ordered l
 
     The thresholds are the defaults under `changes:` in `.cruze/config.yaml`; a project can tune them.
 
-    Done when `cruze validate` reports no `change-too-small`, `change-too-large` or `feature-size` warning, or the user has accepted one and a `D<n>` line under the feature's `## Decisions` records why. After approval, only a rethink can split a change.
+    Done when `cruze validate` reports no `change-too-small`, `change-too-large` or `feature-size` warning. When the user accepts one, record it twice: a `D<n>` line under the feature's `## Settled decisions` saying why, and the item under `changes.exceptions` in `.cruze/config.yaml` with the same reason, which is what stops the warning. `cruze approve` refuses an item with a warning still standing (`size-unaccepted`). After approval, only a rethink can split a change.
 
 Then continue with the review and walkthrough steps of the skill. When the user approves, run `cruze approve <feature>` and quote its result. The command takes the feature's full ID, such as `2026-09-25-open-console`, or its slug when no other active item shares it.

package/skills/architect/walkthrough.md

@@ -6,12 +6,15 @@ At feature scope, cover only what the feature adds, changes or removes. At proje
 
 ## The overview
 
-Write it in the glossary's terms, as what callers can do and what happens when they do, not as a list of elements. Keep it to what the user can read in a minute.
+Write it in the glossary's terms, as what callers can do and what happens when they do, not as a list of elements. Keep the prose to what the user can read in a minute, and open it with the line that says where things stand, from `.agents/skills/cruze-grilling/illustrating.md`.
 
 1. **What it does.** The intent in two sentences. Then one line per use case, or at feature scope per requirement: who asks for what, what they get, and the main way it fails.
 2. **What it touches.** Each new external system, and each new dependency named with its purpose and the approval behind it. Also each component you chose to build yourself, with the reason.
-3. **The slices.** The changes in order, one line each, saying what each delivers and why the first is first. At project scope, the roadmap's phases and the walking skeleton instead.
-4. **What is yours to decide.** The review findings the roles skill brings to the user, any `cruze validate` warning still standing, such as a change over its size limit, any point where a fresh implementer could still build something different, and any rule you challenged that the user overrode.
+3. **What it looks like.** Illustrated as `.agents/skills/cruze-grilling/illustrating.md` says:
+   - A plain-text diagram of the main scenario crossing the design: the inbound adapter, the use case, the domain elements and the ports, marking what is new.
+   - A code sketch, in the project's language, of what the new and changed elements look like: the port operations and use case signatures with their errors, the main entity, and the call an inbound adapter makes.
+4. **The slices.** The changes in order, one line each, saying what each delivers and why the first is first. At project scope, the roadmap's phases and the walking skeleton instead.
+5. **What is yours to decide.** The review findings the roles skill brings to the user, any `cruze validate` warning still standing, such as a change over its size limit, any point where a fresh implementer could still build something different, and any rule you challenged that the user overrode.
 
 ## The documents
 
@@ -20,7 +23,7 @@ List each file the user should read in full, with the sections that changed:
 - Feature scope: the feature's `feature.md`, and the ADRs it adds.
 - Project scope: `docs/architecture.md`, the `layers:` in `.cruze/config.yaml`, `docs/roadmap.md`, the walking-skeleton `change.md`, and the ADRs in `docs/adr/`.
 
-The diagrams are Mermaid inside those files. Say where the user can render them, such as an editor preview or GitHub, rather than pasting them.
+The documents' diagrams are Mermaid. Say where the user can render them, such as an editor preview or GitHub, rather than pasting them; the overview's plain-text sketches are for reading in the conversation.
 
 End the message with: "Read these in full, then tell me what to change, or approve. Do you approve this design?"
 

package/skills/build/SKILL.md

@@ -16,11 +16,11 @@ Build turns an approved plan into code, one task at a time. Each task starts wit
    - `.agents/skills/cruze-behavioural-testing/SKILL.md`
    - `.agents/skills/cruze-hexagonal-design/SKILL.md`, and its language file when one exists for the project's language
    - `.agents/skills/cruze-dependency-approval/SKILL.md`
-3. **Read the plan and the design.** Read the change's `change.md` and its feature's `feature.md`. Read the full body of every element the change builds, and every scenario it delivers. Read `commands:` in `.cruze/config.yaml`.
+3. **Read the plan and the design.** Read the change's `change.md`. Run `cruze show <ref>` and read its output: the full body of every element the change builds, every scenario it delivers, and the settled decisions. Read an element it lists as cited only when the task calls it, from the place it names, never `feature.md` or `docs/architecture.md` whole. Read a reference it lists at the sections the change's elements cite. Read `commands:` in `.cruze/config.yaml`.
 4. **Build each open task in order,** following the task loop below. Skip the tasks already ticked in `## Progress`.
 5. **Finish.** When every task is ticked:
    - Run the format, lint and build commands and the full suite, as `.agents/skills/cruze-formats/reference/config.md` defines it under `commands`.
-   - Run `cruze check` and `cruze trace`, and quote their results.
+   - Run `cruze check --ci` and `cruze trace`, and quote their results.
    - When all of them pass, record the commit they ran at with `cruze journal add checks --set commit=<commit> --item <ref>`, where the commit is the output of `git rev-parse --short HEAD`. Verify quotes this instead of running the suite again.
    - Commit the progress record with a message such as `chore: record progress on <change>`.
    - Done when all of them pass and the checks are recorded.
@@ -30,28 +30,30 @@ Build turns an approved plan into code, one task at a time. Each task starts wit
 For task `T<n>`:
 
 1. **Read it.** Note its owner, its files, the IDs it proves, and the test plan rows for those IDs.
-2. **Red.** Write the tests for the IDs it proves, at the seams the test plan names, carrying the IDs. Run them, and see them fail for the reason you expect.
+2. **Red.** Write the tests for the IDs it proves, at the seams the test plan names, carrying the IDs. Run them, and see them fail for the reason you expect. When the task names a break, use it, or any break that compiles and turns the same assertion red.
 3. **Green.** Write the least code that makes them pass, in the task's files. Code that belongs to another task, or another change, waits for it, even when the next change will need it.
-4. **Check.** Run `cruze check <the task's files>`, the formatter and the linter, and fix what they report. Run the tests the task touched. When `commands:` has a `test_full`, run `test` too, since it is the fast tier. Otherwise run the rest of the suite only when it is quick.
+4. **Check.** Run `cruze check --ci <the task's files>`, the formatter and the linter, and fix what they report. Meet a budget as the budget rule in `.agents/skills/cruze-hexagonal-design/SKILL.md` says, never by bending the code. Run the tests the task touched. When `commands:` has a `test_full`, run `test` too, since it is the fast tier. Otherwise run the rest of the suite only when it is quick.
 5. **Commit** with a Conventional Commit message naming the task, such as `feat(access): console session state machine (T2)`.
 6. **Tick it.** Run `cruze task done T<n>`, which records the commit. Its progress edit rides along in the next commit.
 
 A task with no behaviour of its own, such as a package manifest or a plain data type, has no red step. Build it, check it, commit it and tick it, and the first task whose test uses it covers it.
 
-Done for a task when its tests pass, `cruze check` passes for its files, the commit exists and the task is ticked.
+Done for a task when its tests pass, `cruze check --ci` passes for its files, the commit exists and the task is ticked.
 
 ## Deviations
 
 The plan is design. Within a task you decide only what is local and reversible.
 
-- **Record it and carry on** for a task-level choice: a private helper in another file of the same module, a private type, a fixture or harness added to the test support module that the task's tests need, or two tasks' commits swapped for a reason. The test support module is in every test-writing task's scope, so extend it rather than writing a private helper in a test file. Run `cruze task deviation T<n> "<what you did and why>"`.
+- **Record it and carry on** for a task-level choice: a private helper in another file of the same module, a new file of the owner's module that splits off a responsibility, a `check.exceptions` entry with its reason, a private type, a fixture or harness added to the test support module that the task's tests need, or two tasks' commits swapped for a reason. The test support module is in every test-writing task's scope, so extend it rather than writing a private helper in a test file. Run `cruze task deviation T<n> "<what you did and why>"`.
 - **Stop and offer `rethink`** when the code needs any of these:
   - a new element, port operation or scenario;
   - a file outside the owner's module, other than the test support module;
   - a change to an approved scenario's behaviour, or to its test;
-  - a dependency the design doesn't name.
+  - a dependency, or a feature of an approved dependency, that the design doesn't name. Ask for it as `.agents/skills/cruze-dependency-approval/SKILL.md` says, and never write around it with hand-written code or a shell command;
+  - a limit, timeout, buffer size, message or error case the design doesn't give. Picking one in code hides a gap in the design: the user decides it, at feature level. Two projects settled 35 of them as deviations.
 
   Explain what you found, with the evidence, and don't work around it. Completed tasks keep their commits.
+- **Read a deviation back before you record it.** One that says the design gives no value, text, error or outcome and names the one you chose, or that the code can't keep a promise a port or use case makes, is a rethink, not a deviation. In one change, two deviations worded that way came back as code-review blockers and sent it back at verify.
 - Never edit `feature.md`, `docs/architecture.md` or `docs/specs/` during build. Design changes go through `rethink`.
 
 ## Protecting the check
@@ -60,4 +62,4 @@ Never weaken, skip or delete a behaviour, contract or smoke test for an approved
 
 ## Next step
 
-`verify`, once every task is ticked and the finishing checks pass.
+`verify`, once every task is ticked and the finishing checks pass. Start it in a new session, so its context starts empty: one session that ran plan, build, verify and land reached 745k tokens.

package/skills/dependency-approval/SKILL.md

@@ -9,12 +9,19 @@ Every new dependency needs the user's explicit approval before it is declared or
 
 ## Asking
 
-1. Establish the need: the capability, and why the standard library and the project's already-approved dependencies don't provide it.
+1. Establish the need: the capability, and what the design looks like with the dependency and without it, using the standard library and the project's already-approved dependencies. Show both as short code sketches, following `.agents/skills/cruze-grilling/illustrating.md`.
 2. Choose a recommendation, following `.agents/skills/cruze-research/SKILL.md`, which also says where versions come from.
 3. Say where it will sit: the module that owns it, and the port that keeps it out of the core when it is infrastructure.
 4. Name the realistic alternatives, including writing it yourself and what owning that code would cost. Never offer a hand-written alternative for cryptography, TLS or a security protocol.
 5. Ask, then wait. Nothing is declared, installed or written against it until the user answers.
 
+## Weighing
+
+- Recommend the option that gives the cleanest design: the one an experienced developer in the language would write, with the least code to own. A dependency, a new crate or package, or a feature of an approved dependency is not a cost in itself. Weigh its concrete costs: maintenance and release health, security record, licence, and build time or binary size where a stated constraint makes them matter.
+- "No new dependency" is never the reason for a choice. Name what the chosen option does better.
+- A structure the language requires for an idiom, such as a separate crate for a derive macro, is part of that idiom, not an extra cost.
+- When the clean design needs a dependency or feature nobody approved yet, ask for it. Hand-written code, a shell command or a less idiomatic construct that exists only to avoid asking is a design flaw.
+
 ```markdown
 **Dependency: `russh` for SSH hops**
 - Why not std or existing: the standard library has no SSH client, and no approved dependency provides one.

package/skills/envision/SKILL.md

@@ -27,3 +27,5 @@ Envision decides the what: the problem, who has it, and the behaviour that solve
 
 - After project scope: run `architect` at project scope.
 - After feature scope: run `architect "<feature>"`.
+
+Start it in a new session, so its context starts empty.

package/skills/envision/feature.md

@@ -18,6 +18,6 @@ The result is a feature folder whose `feature.md` holds the intent, the settled
    - Name every ID with glossary terms. An ID is never reused.
    - Done when every requirement has a scenario for its main case and one for each failure a user can meet.
 8. **Leave the design to architect.** Set `## Architecture delta` to `None.` and leave the Changes table with its header row only. Remove the remaining template guides.
-9. **Confirm.** Summarize the intent and each requirement with its scenarios, in plain words, and ask the user to confirm them. Apply any corrections.
+9. **Confirm.** Summarize the intent and each requirement with its scenarios, in plain words, showing each requirement's main scenario as the user would see it, and ask the user to confirm them. Apply any corrections.
 
 Done when the user has confirmed, `cruze validate` reports no errors for the feature, only its `not-designed` warning, and the feature is committed.

package/skills/explore/SKILL.md

@@ -12,7 +12,7 @@ Explore is the optional thinking partner that can come before any other Cruze st
 1. **Frame the problem.** Ask what prompted the idea, who it affects, and what outcome would make it worthwhile. If the user starts from a solution, restate the problem underneath it and confirm it. Done when you can state the problem in one sentence the user agrees with.
 2. **Read what exists.** Read whichever of these exist: `docs/vision.md`, `docs/glossary.md`, `docs/architecture.md`, `docs/roadmap.md`, and the code the idea touches. Run `cruze status` to see work in flight. Use the glossary's words from here on, following `.agents/skills/cruze-domain-language/SKILL.md`.
 3. **Separate facts from guesses.** List what is known evidence, what is a hypothesis, and what is a preference. Look up any fact you can rather than asking the user for it.
-4. **Diverge.** Lay out two to four genuinely different approaches, including leaving things as they are when that is credible. For each, give what it changes, what it leaves alone, its benefits, its costs and failure modes, the assumptions it rests on, and what evidence would tell it apart from the others. Sketch an interaction as a Mermaid `sequenceDiagram` or `flowchart` when that makes a difference clearer.
+4. **Diverge.** Lay out two to four genuinely different approaches, including leaving things as they are when that is credible. For each, give what it changes, what it leaves alone, its benefits, its costs and failure modes, the assumptions it rests on, and what evidence would tell it apart from the others. Show what each approach looks like, following `.agents/skills/cruze-grilling/illustrating.md`.
 5. **Converge.** Compare the strongest options against the user's outcome, the vision's goals and constraints, and the architecture. Challenge assumptions and accidental scope growth, following the challenge rules in `.agents/skills/cruze-grilling/SKILL.md`. Recommend one option only when its trade-offs are understood. Otherwise recommend the smallest step that would settle the question, such as a spike, a measurement or a research question.
 6. **Offer to capture.** Summarize the problem, the options, the trade-offs, your recommendation and the open questions, then ask whether to capture them. When the user declines, stop here: the discussion itself was the result.
 

package/skills/formats/reference/architecture.md

@@ -35,7 +35,7 @@ Facts are `- Key: value` items. Keys marked required must be present; the others
 | `PORT` | `Direction` (`driven` or `driving`), `Operations`, `Module`, `File` | `Implemented by`, `Future` |
 | `ADP` | `Implements` (a driven port) or `Drives` (use cases), `Technology`, `Module`, `File` | `Adopts` (library and adopt-or-build reason), `Format` (the stored or wire format it owns, or where its schema lives) |
 | `FLOW` | `Elements`, a Mermaid `sequenceDiagram` | `Serves` (SCN IDs, once they exist), `Failure paths` |
-| `MOD` | `Path`, `Layer` (`core`, `domain`, `application`, `adapter` or `composition`) | |
+| `MOD` | `Path` (a directory ending in `/`, or one file; list several in backticks, never a glob, including every file the module owns outside its directory, such as a build script), `Layer` (`core`, `domain`, `application`, `adapter` or `composition`) | |
 | `RULE` | one or two sentences of rule | `Enforced by` (config layer names) |
 | `XC` | prose | |