@printpractical/cruze 0.0.8 → 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.8 is the eighth preview. It cuts what each step reads and tightens the gates: every step runs in a new session, plan, build and the reviewers read a change's scope through `cruze show` instead of the living docs whole, round 2 of a review is checked by the agent, `cruze approve` refuses a size warning the user hasn't accepted, build waits for the changes it depends on and runs the same check as CI, and neither a file budget nor avoiding a dependency shapes code. 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.8/printpractical-cruze-0.0.8.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.8
+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.8/printpractical-cruze-0.0.8.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:

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/show.js

@@ -14,9 +14,14 @@ function render(report             )         {
   lines.push("## Elements", "", ...blocks(report.elements), "## Scenarios", "", ...blocks(report.scenarios));
   lines.push("## Cited, not shown", "");
   lines.push(...(report.cited.length === 0 ? ["None."] : report.cited.map((c) => `- ${c.id}: ${c.title} (${c.source})`)), "");
-  lines.push("## Settled decisions", "", ...(report.decisions.length === 0 ? ["None."] : report.decisions), "");
+  if (report.feature === undefined) lines.push("## Settled decisions", "", ...(report.decisions.length === 0 ? ["None."] : report.decisions), "");
+  else {
+    lines.push("## Settled decisions of the feature", "", ...(report.decisions.length === 0 ? ["None."] : report.decisions), "");
+    lines.push("## Settled decisions of the change", "", ...(report.changeDecisions.length === 0 ? ["None."] : report.changeDecisions), "");
+  }
   lines.push("## Dispositions", "");
   lines.push(...(report.dispositions.length === 0 ? ["None."] : report.dispositions.map((d) => `- [${d.disposition}, ${d.review}] ${d.finding}: ${d.reason}`)), "");
+  if (report.references.length > 0) lines.push("## References", "", ...report.references.map((r) => `- \`${r.path}\`: ${r.use}`), "");
   if (report.missing.length > 0) lines.push("## Missing", "", ...report.missing.map((id) => `- ${id} is defined nowhere`), "");
   return lines.join("\n").trimEnd();
 }

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/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

@@ -14,6 +14,8 @@ import { listEvents } from "./journal_events.js";
                                                 
                                                                                                                
                               
+                                                                                                        
+                                                   
  
 
 /**
@@ -31,5 +33,5 @@ export async function showScope(deps             , ref        )
     reason: String(entry["reason"] ?? ""),
     review: String(entry["review"] ?? ""),
   }));
-  return { ...scope, dispositions };
+  return { ...scope, dispositions, references: view.config?.config?.references ?? [] };
 }

package/dist/domain/check/budget_text.js

@@ -1,24 +1,61 @@
 /**
  * The part of a source file its budgets measure. Budgets apply to source, not tests, so a Rust
- * file's `#[cfg(test)]` modules are left out: rustfmt closes a top-level module with `}` in column 0.
+ * 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 item = lines[i + 1] ?? "";
-    if (lines[i]?.trim() !== "#[cfg(test)]" || !/^(?:pub(?:\([^)]*\))?\s+)?mod\s+\w+\s*[{;]/.test(item)) {
+    const start = testModuleStart(lines, i);
+    if (start === null) {
       kept.push(lines[i] ?? "");
       continue;
     }
-    if (item.trimEnd().endsWith(";")) {
-      i += 1;
+    if ((lines[start] ?? "").trimEnd().endsWith(";")) {
+      i = start;
       continue;
     }
-    let end = i + 2;
+    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

@@ -55,11 +55,11 @@ export function checkSource(input            )                 {
     const lines = budgeted.split("\n").length - (budgeted.endsWith("\n") ? 1 : 0);
     if (!excepted && lines > config.check.maxLines) {
       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 by responsibility` });
+      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, 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. */
@@ -132,6 +134,15 @@ export function parseConfig(text        )               {
     }),
   };
 
+  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 } : {}),
@@ -148,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];

package/dist/domain/project/scope_view.js

@@ -36,8 +36,10 @@ import { featureOf,                                  } from "./work_items.js";
                             
                                                                                    
                         
-                                                                  
+                                                                         
                       
+                                                                                       
+                            
                                                                               
                     
  
@@ -66,7 +68,7 @@ export function scopeView(view             , item          )            {
       return [shown];
     });
   const elements = show(wanted.elements);
-  const scenarios = show(wanted.scenarios);
+  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))
@@ -74,12 +76,26 @@ export function scopeView(view             , item          )            {
       const found = locate(id);
       return found === undefined ? [] : [{ id, title: found.element.title, source: `${found.path}:${found.element.start + 1}` }];
     });
-  const decisions = feature === undefined ? decisionLines(item.doc) : [...decisionLines(feature.doc), ...decisionLines(item.doc)];
-  const result            = { ref: item.ref, kind: item.kind, elements, scenarios, cited, decisions, missing };
+  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);

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/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/main.js

@@ -1,10 +1,11 @@
 #!/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";
@@ -16,18 +17,21 @@ process.stdout.on("error", (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.8",
+  "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`.
 
@@ -42,4 +43,6 @@ Architect decides the how and the how big. It designs the domain, the ports and
 - 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/build/SKILL.md

@@ -16,7 +16,7 @@ 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`. 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 `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`.
@@ -53,6 +53,7 @@ The plan is design. Within a task you decide only what is local and reversible.
   - 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

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` (a directory ending in `/`, or one file; list several in backticks, never a glob), `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 | |