@printpractical/cruze 0.0.4 → 0.0.6

package/README.md

@@ -10,7 +10,7 @@ It works with any agent that supports the [Agent Skills](https://agentskills.io)
 
 ## Status
 
-Version 0.0.4 is the fourth preview. It fixes what the first projects on 0.0.3 ran into: commands print one format on stdout and refuse options they don't take, overlap checks count only work in flight, and the feature map can be corrected when a feature's decisions change it. 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.6 is the sixth preview. It cuts the waiting per change: the full test suite runs once per commit, with an optional fast tier for the task loop, the design walkthrough is one overview followed by the documents to read in full, the agent checks a review's round 2 when the fixes follow the proposals, and research checks every claim the design relies on. 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
 
@@ -22,7 +22,7 @@ Spec-driven workflows tend to fail in the same few ways:
 - Everything is "fully specified", yet the result fails when a person actually uses it.
 - Review loops keep finding new things to change and never converge.
 
-Cruze answers each of these with a specific mechanism. A living `docs/architecture.md` is read at every step and updated by every change. Approvals are bound to document content, so stepping back is just editing. Every task names the file it touches, and `cruze check` enforces layer rules. Scenarios are traced to behavioural tests, and the system is actually run. Reviews use a closed rubric with a hard limit of two rounds.
+Cruze answers each of these with a specific mechanism. A living `docs/architecture.md` is read at every step and updated by every change. Approvals are bound to document content, so stepping back is just editing. Every task names the file it touches, and `cruze check` enforces layer rules. Scenarios are traced to behavioural tests, and the system is actually run. Reviews use a closed rubric with a hard limit of two rounds, and bring you only the findings that are yours to decide: changes to behaviour or to the designed contracts.
 
 ## Quick start
 
@@ -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.4/printpractical-cruze-0.0.4.tgz
+npm install -g https://github.com/PrintPractical/cruze/releases/download/v0.0.6/printpractical-cruze-0.0.6.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.4
+npm install -g --install-links github:PrintPractical/cruze#v0.0.6
 ```
 
 ### 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.4/printpractical-cruze-0.0.4.tgz
+cruze init --package https://github.com/PrintPractical/cruze/releases/download/v0.0.6/printpractical-cruze-0.0.6.tgz
 ```
 
 `init` asks for the project name, and which coding agent you use: `claude` for Claude Code, or `other` for any agent that reads `AGENTS.md` and `.agents/skills/`, such as Codex or OpenCode. It doesn't ask when you pass `--agent claude` or `--agent other`, or when the repository already has `CLAUDE.md` or `.claude/`. With `--yes`, or without a terminal, it sets up Claude Code. Then it creates:
@@ -118,8 +118,8 @@ Skills call these at fixed points, and CI runs `check` and `trace` on every push
 
 | Command | What it does |
 | --- | --- |
-| `cruze validate` | Checks every document against the formats: IDs, elements, deltas, scope rules, task lines, test plans, roadmap and config |
-| `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 |
+| `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 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 |
@@ -149,7 +149,7 @@ Stepping back is editing: change an upstream document and every approval that ci
 | `cruze-envision` | The what: the project's vision, goals and feature map, or one feature's intent and requirements with scenarios |
 | `cruze-architect` | The how: the architecture, a feature's architecture delta and its changes, or a tweak; ends with a design review and a walkthrough for your approval |
 | `cruze-roadmap` | Orders the release into phases with blocking edges and goal coverage, and closes a release |
-| `cruze-plan` | Turns a change into a test plan and ordered tasks with file targets, reviewed in a fresh context |
+| `cruze-plan` | Turns a change into a test plan and ordered tasks with file targets, reviewed in a fresh context and approved once the review closes |
 | `cruze-build` | Builds the change task by task, each test-first, checked and committed, and stops to rethink when the design is wrong |
 | `cruze-verify` | Runs the checks, a fresh-context verifier that uses the real system, a two-lane code review and a manual test script, then asks you to accept |
 | `cruze-land` | Merges the change into the living docs and updates the changelog, README and `AGENTS.md`; also lands bug fixes |

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

@@ -52,6 +52,8 @@
                 
                    
                    
+                   
+                            
                  
                    
                 

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

@@ -13,8 +13,12 @@ export async function runValidate(context            )                         {
 
 export async function runApprove(context            , args          , options         )                         {
   requireArgs(args, ["document"]);
-  const report = await approveArtifact(context, args[0] ?? "", { replan: options.replan, rebase: options.rebase });
+  if (options.byAgent && options.restampUnchanged) throw new UsageError("--by-agent and --restamp-unchanged are alternatives");
+  const agent = options.byAgent ? "plan-review" : options.restampUnchanged ? "rethink" : undefined;
+  const report = await approveArtifact(context, args[0] ?? "", { replan: options.replan, rebase: options.rebase, ...(agent === undefined ? {} : { agent }) });
   const lines = [`Approved ${report.artifact} (${report.hash.slice(0, 19)}), pinned to ${report.upstream.length} upstream element(s).`];
+  if (report.basis === "plan-review") lines.push("Approved for the user: its plan review closed with no blocker open.");
+  if (report.restamped !== undefined) lines.push(`Re-stamped for the user: its own design is unchanged, and only ${report.restamped.join(", ")} changed.`);
   if (report.stamped.length > 0) lines.push(`Marked ${report.stamped.length} element(s) planned.`);
   if (report.bound !== undefined) lines.push(`Bound the change to branch ${report.bound}.`);
   if (report.replanned.length > 0) lines.push(`Set back to planned: ${report.replanned.join(", ")}.`);

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

@@ -35,8 +35,11 @@ export async function runStatus(context            , _args          , options
   return { json: report, human: lines.join("\n") };
 }
 
+const BASIS                         = { "plan-review": " (by the agent, after its plan review)", rethink: " (re-stamped by the agent after a rethink)" };
+
 function describe(label        , status                )         {
-  const detail = status.changed.length > 0 ? ` (${status.changed.join(", ")})` : status.unjournaled === true ? " (no journal entry)" : "";
+  const byAgent = status.state === "approved" ? BASIS[status.record?.basis ?? ""] ?? "" : "";
+  const detail = status.changed.length > 0 ? ` (${status.changed.join(", ")})` : status.unjournaled === true ? " (no journal entry)" : byAgent;
   return `${label}: ${status.state}${detail}`;
 }
 

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

@@ -22,7 +22,11 @@ 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" },
-  approve: { handler: runApprove, options: ["replan", "rebase"], usage: "approve <vision|architecture|roadmap|ref|path> [--replan <ID>...] [--rebase <ID>...]   record your approval of a document" },
+  approve: {
+    handler: runApprove,
+    options: ["replan", "rebase", "by-agent", "restamp-unchanged"],
+    usage: "approve <vision|architecture|roadmap|ref|path> [--replan <ID>...] [--rebase <ID>...] [--by-agent|--restamp-unchanged]   record an approval of a document",
+  },
   new: {
     handler: runNew,
     options: { vision: [], glossary: [], architecture: [], roadmap: [], feature: ["title", "roadmap"], change: ["title", "feature", "roadmap"], adr: ["title"], note: ["title"] },

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

@@ -52,6 +52,8 @@ export function parseCommand(argv          )                {
         rebase: { type: "string", multiple: true, default: [] },
         base: { type: "string" },
         blockers: { type: "string" },
+        "by-agent": { type: "boolean", default: false },
+        "restamp-unchanged": { type: "boolean", default: false },
       },
     });
   } catch (error) {
@@ -74,6 +76,8 @@ export function parseCommand(argv          )                {
     full: values.full,
     replan: values.replan,
     rebase: values.rebase,
+    byAgent: values["by-agent"],
+    restampUnchanged: values["restamp-unchanged"],
     ...optional("name", values.name),
     ...optional("title", values.title),
     ...optional("feature", values.feature),

package/dist/app/use_cases/approve_artifact.js

@@ -1,3 +1,4 @@
+import { requirePlanReviewClosed, requireUnchangedSinceApproval,                 } from "../../domain/approvals/agent_approval.js";
 import { evaluateApproval } from "../../domain/approvals/evaluate.js";
 import { fingerprint, isApprovable } from "../../domain/approvals/fingerprint.js";
 import { latestApproval, serializeApprovals, withApproval,                     } from "../../domain/approvals/records.js";
@@ -29,6 +30,10 @@ import { appendJournal, loadView, withFiles,                  } from "../project
                       
                                                                                         
                     
+                                                                    
+                     
+                                                                        
+                       
  
 
                                  
@@ -36,6 +41,8 @@ import { appendJournal, loadView, withFiles,                  } from "../project
                     
                                                                                                                                      
                     
+                                                                                                   
+                     
  
 
 /**
@@ -53,6 +60,9 @@ export async function approveArtifact(deps             , ref        , options
   if (item !== undefined && item.kind !== "feature" && !isPlanned(item.doc)) {
     throw new CruzeError("not-planned", `${path} has no test plan or tasks yet; plan it before approving`);
   }
+  const before = evaluateApproval(view, path);
+  if (options.agent === "plan-review") requirePlanReviewClosed(view.journal, item ?? notWork(path));
+  if (options.agent === "rethink") requireUnchangedSinceApproval(view.journal, item, path, before);
 
   const edits = new Map                ();
   let text = view.snapshot.get(path) ?? "";
@@ -103,12 +113,23 @@ export async function approveArtifact(deps             , ref        , options
     upstream,
     approvedAt: deps.clock.now().toISOString(),
     by: (await deps.repository.userName()) ?? "unknown",
+    ...(options.agent === undefined ? {} : { basis: options.agent }),
   });
   for (const [changed, content] of edits) await deps.files.writeText(changed, content);
   await deps.files.writeText(approvalsPath(folder), serializeApprovals(approvals));
-  await appendJournal(deps, folder, "approve", { artifact: path, hash, ...(replanned.length > 0 ? { replanned } : {}), ...(rebased.length > 0 ? { rebased } : {}) });
+  const restamped = options.agent === "rethink" ? before.changed : undefined;
+  await appendJournal(deps, folder, "approve", {
+    artifact: path,
+    hash,
+    ...(replanned.length > 0 ? { replanned } : {}),
+    ...(rebased.length > 0 ? { rebased } : {}),
+    ...(options.agent === undefined ? {} : { basis: options.agent }),
+    ...(restamped === undefined ? {} : { restamped }),
+  });
   const report                = { artifact: path, hash, upstream: Object.keys(upstream), stamped, replanned, rebased };
   if (bound !== undefined) report.bound = bound;
+  if (options.agent !== undefined) report.basis = options.agent;
+  if (restamped !== undefined) report.restamped = restamped;
   return report;
 }
 
@@ -133,6 +154,10 @@ function requireRebased(view             , deltaIds             , previous
   }
 }
 
+function notWork(path        )        {
+  throw new CruzeError("needs-user", `${path} is a project document, so the user approves it`);
+}
+
 /** A change needs its feature approved; a feature or standalone change needs the architecture approved. */
 function requireUpstreamApproved(view             , path        )       {
   const item = view.items.find((i) => i.path === path);

package/dist/app/use_cases/new_work_item.js

@@ -28,7 +28,7 @@ import { appendJournal, loadView,                  } from "../project_context.js
 export async function createWorkItem(deps             , request            )                     {
   const view = await loadView(deps.files);
   const date = deps.clock.today();
-  const values = { id: "", title: request.title, date, project_name: "" };
+  const values = { id: "", title: request.title, title_quoted: JSON.stringify(request.title), date, project_name: "" };
   if (request.title.trim() === "") throw new CruzeError("missing-title", "a title is required");
 
   if (request.kind === "adr") {

package/dist/domain/approvals/agent_approval.js

@@ -0,0 +1,68 @@
+import { CruzeError } from "../cruze_error.js";
+                                                  
+                                                         
+                                                    
+
+/**
+ * Why an approval was given without the user: a plan whose review closed, or work that a
+ * rethink left unchanged while something it cites moved. The user can still object, and
+ * editing the document makes the approval stale as usual.
+ */
+                                                   
+
+const byTime = (a              , b              )         => a.at.localeCompare(b.at);
+
+/**
+ * A feature's change may be approved by the agent once its plan review has closed: a review
+ * recorded since the change was last approved, no blocker left open in its last round, and a
+ * disposition for every finding of its first round. The feature's design, and a standalone
+ * change's, stay the user's to approve.
+ */
+export function requirePlanReviewClosed(journal                , item          )       {
+  if (item.kind !== "change") {
+    throw new CruzeError("needs-user", `${item.ref} carries design, so the user approves it; only a feature's change can be approved after its plan review`);
+  }
+  const entries = journal.filter((e) => e["item"] === item.ref || e["artifact"] === item.path).sort(byTime);
+  const lastApproval = entries.filter((e) => e.event === "approve").at(-1);
+  const reviews = entries.filter((e) => e.event === "review" && e["review"] === "plan" && (lastApproval === undefined || e.at > lastApproval.at));
+  const last = reviews.at(-1);
+  if (last === undefined) {
+    const since = lastApproval === undefined ? "" : " since the change was last approved";
+    throw new CruzeError("plan-review-open", `no plan review is recorded for ${item.ref}${since}; run the plan review first`);
+  }
+  const blockers = Number(last["blockers"] ?? 0);
+  if (blockers > 0 && Number(last["round"]) === 1) {
+    throw new CruzeError("plan-review-open", `the plan review's round 1 found ${blockers} blocker(s); check their fixes in round 2`);
+  }
+  if (blockers > 0) {
+    throw new CruzeError("plan-review-open", `round 2 left ${blockers} blocker(s) open; the user decides them and approves the plan`);
+  }
+  const first = reviews.filter((e) => Number(e["round"]) === 1).at(-1) ?? last;
+  const findings = Number(first["blockers"] ?? 0) + Number(first["concerns"] ?? 0);
+  const decided = entries.filter((e) => e.event === "disposition" && e["review"] === "plan" && e.at > first.at).length;
+  if (decided < findings) {
+    throw new CruzeError("plan-review-open", `the plan review raised ${findings} finding(s) but ${decided} have a disposition; record one for each`);
+  }
+}
+
+/**
+ * A rethink may re-approve, for the user, a feature or change it didn't edit: one whose own
+ * design is unchanged and that is stale only because something it cites changed. A change
+ * with a task reopened since its approval goes back to the user.
+ */
+export function requireUnchangedSinceApproval(journal                , item                      , path        , status                )       {
+  if (item === undefined) {
+    throw new CruzeError("needs-user", `${path} is a project document, so the user re-approves it; a rethink re-stamps only features and changes`);
+  }
+  if (status.state === "edited") {
+    throw new CruzeError("needs-user", `${item.ref} itself changed since its approval, so the user re-approves it`);
+  }
+  if (status.state !== "upstream-changed") {
+    throw new CruzeError("not-stale", `${item.ref} is ${status.state}; only work whose upstream changed can be re-stamped`);
+  }
+  const approvedAt = journal.filter((e) => e.event === "approve" && e["artifact"] === path).sort(byTime).at(-1)?.at ?? "";
+  const reopened = journal.filter((e) => e.event === "reopen" && e["change"] === item.ref && e.at > approvedAt).map((e) => String(e["task"]));
+  if (reopened.length > 0) {
+    throw new CruzeError("needs-user", `${item.ref} had ${reopened.join(", ")} reopened since its approval, so the user re-approves it`);
+  }
+}

package/dist/domain/config.js

@@ -23,9 +23,25 @@ import { parse as parseYaml } from "yaml";
                                                                                           
                                                                                   
      
-                                 
+                                                       
+                                                                                         
+                        
+ 
+
+/** Which review findings the user decides: only the exceptions, or every one. */
+                                                
+
+                               
+                                                                                      
+                    
+                                                             
+                       
+                                                 
+                   
  
 
+export const DEFAULT_CHANGE_LIMITS               = { minBuilds: 3, maxScenarios: 30, maxTasks: 25 };
+
                         
                
                   
@@ -97,6 +113,14 @@ export function parseConfig(text        )               {
   const review = asRecord(root["review"]) ?? {};
   const reviewCommand = review["command"] === undefined ? undefined : stringList(review["command"], "review.command", problems);
   if (reviewCommand?.length === 0) problems.push("review.command needs at least the program to run");
+  const decide = review["decide"] ?? "exceptions";
+  if (decide !== "exceptions" && decide !== "all") problems.push("review.decide must be exceptions or all");
+  const limits = asRecord(root["changes"]) ?? {};
+  const changes               = {
+    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,
+  };
 
   const config              = {
     version: 1,
@@ -109,7 +133,11 @@ export function parseConfig(text        )               {
     check: { maxLines: maxLines ?? 250, maxTypes: maxTypes ?? 5, exceptions },
     layers,
     commands,
-    review: reviewCommand === undefined || reviewCommand.length === 0 ? {} : { command: reviewCommand },
+    review: {
+      ...(reviewCommand === undefined || reviewCommand.length === 0 ? {} : { command: reviewCommand }),
+      decide: decide === "all" ? "all" : "exceptions",
+    },
+    changes,
   };
   return { config, problems };
 }

package/dist/domain/journal.js

@@ -15,12 +15,14 @@ export const RECORDED_EVENTS                           = {
   override: ["gate", "reason"],
   bug: ["summary", "cause"],
   verification: ["result", "summary"],
+  checks: ["commit"],
 };
 
 /** Fields an event may carry beyond its required ones, checked when present. A defect rethink must say which step missed it. */
 const OPTIONAL_FIELDS                           = {
   rethink: ["missed_by"],
-  review: ["nits"],
+  review: ["nits", "checked_by"],
+  disposition: ["decided"],
 };
 
 /** The workflow steps and checks that find or miss a problem, so a retro can count them. */
@@ -30,8 +32,10 @@ export const FIELD_VALUES                           = {
   level: ["task", "change", "feature", "architecture", "vision"],
   kind: ["defect", "discovery"],
   disposition: ["fixed", "waived", "deferred", "rejected"],
+  decided: ["agent", "user"],
   review: ["design", "plan", "code", "realign"],
   result: ["accepted", "sent-back"],
+  checked_by: ["agent", "reviewer"],
   found_by: STEPS,
   missed_by: STEPS,
 };
@@ -77,6 +81,12 @@ export function recordedEventProblems(event        , fields
     if (allowed !== undefined && !allowed.includes(value)) problems.push(`${field} must be one of ${allowed.join(", ")}`);
     if (COUNT_FIELDS.includes(field) && !/^\d+$/.test(value)) problems.push(`${field} must be a whole number`);
   }
+  if (event === "checks" && fields["commit"] !== undefined && !/^[0-9a-f]{7,40}$/.test(fields["commit"])) {
+    problems.push("commit must be a commit hash, such as the output of git rev-parse --short HEAD");
+  }
+  if (event === "disposition" && fields["decided"] === "agent" && fields["disposition"] !== "fixed") {
+    problems.push("the agent decides only fixes; the user waives, defers or rejects a finding (decided=user)");
+  }
   return problems;
 }
 

package/dist/domain/status/next_step.js

@@ -66,7 +66,7 @@ function projectStep(view             )                  {
     {
       path: PATHS.architecture,
       missing: { step: "architect", reason: "the project has no architecture yet" },
-      unapproved: { step: "architect", reason: "finish the architecture, walk through it and approve it" },
+      unapproved: { step: "architect", reason: "finish the architecture, review it and approve it" },
       changed: { step: "rethink", target: "architecture", reason: "the architecture changed since its approval" },
     },
     {
@@ -89,7 +89,7 @@ function itemSteps(view             , item          , branch               )
   if (item.kind === "standalone") return [changeStep(view, item, branch)];
   const state = evaluateApproval(view, item.path);
   if (readChangesTable(item.doc).length === 0) return [{ step: "architect", target: item.ref, reason: "the feature has no design or changes yet" }];
-  if (state.state === "unapproved") return [{ step: "architect", target: item.ref, reason: "review the feature's design, walk through it and approve it" }];
+  if (state.state === "unapproved") return [{ step: "architect", target: item.ref, reason: "review the feature's design and approve it" }];
   if (state.state !== "approved") return [{ step: "rethink", target: item.ref, reason: `the feature changed since its approval${state.changed.length > 0 ? ` (${state.changed.join(", ")})` : ""}` }];
   const changes = changesOf(view.items, item);
   const landed = new Set(changes.filter((c) => readProgress(c.doc).landed !== undefined).map((c) => c.folderName));

package/dist/domain/status/verification.js

@@ -4,13 +4,14 @@
 /**
  * Whether the user accepted a change at verify. The latest verification recorded for the change
  * counts. A later approval keeps it only when the change's own design is unchanged, as when it is
- * re-approved because something upstream moved; a changed plan means verifying again.
+ * re-approved because something upstream moved; a changed plan means verifying again. Land's
+ * re-stamps don't count, since they follow the merge; an approval the agent gave does.
  */
 export function isVerified(journal                , change          )          {
   const byTime = (a              , b              )         => a.at.localeCompare(b.at);
   const verification = journal.filter((e) => e.event === "verification" && e["item"] === change.ref).sort(byTime).at(-1);
   if (verification?.["result"] !== "accepted") return false;
-  const approvals = journal.filter((e) => e.event === "approve" && e["artifact"] === change.path && e["basis"] === undefined).sort(byTime);
+  const approvals = journal.filter((e) => e.event === "approve" && e["artifact"] === change.path && !String(e["basis"] ?? "").startsWith("land ")).sort(byTime);
   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);
 }

package/dist/domain/validation/plan_rules.js

@@ -7,6 +7,7 @@ import { findIds, kindOf } from "../ids.js";
 import { isPlanned, readScope, readTasks, readTestPlan,                       } from "../project/plan_parts.js";
                                                               
 import { error, warning,              } from "./problem.js";
+import { planSizeProblems } from "./size_rules.js";
 
 const TEST_KINDS = ["behaviour", "contract", "domain", "smoke"];
 
@@ -31,6 +32,7 @@ export function changePlanProblems(
     problems.push(error(path, line, "task-format", "task lines read: - T<n>: `<owner>` in `<path>`[, `<path>`], proves <ID>[, <ID>]"));
   }
   if (tasks.length === 0 && malformed.length === 0) problems.push(error(path, undefined, "missing-tasks", "the change has no tasks"));
+  problems.push(...planSizeProblems(view, path, tasks.length));
 
   const proved = new Set(tasks.flatMap((task) => task.proves));
   const taskPaths = tasks.flatMap((task) => task.paths);

package/dist/domain/validation/size_rules.js

@@ -0,0 +1,36 @@
+import { DEFAULT_CHANGE_LIMITS,                   } from "../config.js";
+import { kindOf } from "../ids.js";
+                                                          
+                                                              
+import { warning,              } from "./problem.js";
+
+/**
+ * Every change pays for its own plan review, code review, verifier run and land, so a change
+ * should carry enough work to be worth them, and no more than one review and one run can hold.
+ */
+export function changeLimits(view             )               {
+  return view.config?.config?.changes ?? DEFAULT_CHANGE_LIMITS;
+}
+
+/** 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             )            {
+  const limits = changeLimits(view);
+  const problems            = [];
+  for (const row of rows.filter((r) => !landed.has(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`));
+    }
+    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`));
+    }
+  }
+  return problems;
+}
+
+/** 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 [];
+  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,6 +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";
 
 const REQUIRED_SECTIONS                                     = {
   feature: ["Intent", "Spec delta", "Architecture delta", "Changes"],
@@ -71,6 +72,7 @@ function featureScopeProblems(view             , feature          , delta
   if (extra !== undefined) {
     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));
   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`));

package/dist/domain/versions/rule_versions.js

@@ -13,6 +13,9 @@ export const RULE_SINCE                         = {
   "validate:outside-module-map": "0.0.2",
   "validate:readme-overview": "0.0.2",
   "validate:feature-size": "0.0.2",
+  "validate:change-too-small": "0.0.5",
+  "validate:change-too-large": "0.0.5",
+  "validate:plan-too-large": "0.0.5",
 };
 
 /** Whether a rule arrived after the version the project's code meets, so it waits for `realign`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@printpractical/cruze",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "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

@@ -5,7 +5,7 @@ description: Decides how to build and how big, at project scope (domain model, c
 
 # Architect
 
-Architect decides the how and the how big. It designs the domain, the ports and adapters, and where every element lives in the source tree, before any code exists. It ends with the one heavy human gate, the design walkthrough, where the user sees the entities, their interactions, the ports and the files, and approves the design.
+Architect decides the how and the how big. It designs the domain, the ports and adapters, and where every element lives in the source tree, before any code exists. It ends with the one heavy human gate, the design walkthrough: a short overview in plain terms, after which the user reads the design documents in full and approves or comments.
 
 ## Steps
 
@@ -25,7 +25,7 @@ Architect decides the how and the how big. It designs the domain, the ports and
    - `.agents/skills/cruze-formats/reference/architecture.md`
 5. **Design.** Follow the scope's procedure: [project.md](project.md), [feature.md](feature.md) or [tweak.md](tweak.md). Tweak scope ends there and hands off to `plan`.
 6. **Review the design.** Run the design review in `.agents/skills/cruze-roles/SKILL.md`, with the design reviewer role. Done when every finding has a journaled disposition and no blocker is open without the user's decision.
-7. **Walk the user through it.** Follow [walkthrough.md](walkthrough.md). Apply what the user changes, run `cruze validate` again, and repeat the parts of the walkthrough those changes affect.
+7. **Hand the design to the user.** Follow [walkthrough.md](walkthrough.md): one overview message, then the documents to read in full. Apply what the user changes, run `cruze validate` again, and say what changed.
 8. **Record the approval.** Only after the user says they approve, run the scope's `cruze approve` command and quote its result, then commit. At project scope, the roadmap follows as its own approval, described in [project.md](project.md).
 
 ## Rules

package/skills/architect/feature.md

@@ -21,11 +21,18 @@ The result is a `feature.md` with a complete architecture delta and an ordered l
 
 ## Split it into changes
 
-9. **Slice vertically.** Each change delivers one or more scenarios end to end, through every layer they need, and can land on its own. The first change is the thinnest slice that proves the design, a tracer bullet. Later changes widen it.
+9. **Slice vertically.** Each change delivers scenarios end to end, through every layer they need, and can land on its own. Every change pays for its own plan review, code review, verifier run and land, so slice by what is worth that cost, not by the smallest piece that could land. The feature's first change proves the design end to end; later changes widen it in steps of real work.
 10. **Fill the Changes table.** Give each row a number and a slug, such as `01-local-serial`. List the scenario and requirement IDs it `Delivers`, the architecture IDs it `Builds`, any IDs it `Removes`, and the changes it `Depends on`.
     - A change builds an element only when its scenarios prove the whole element. Each delta element is built by exactly one change, so when an element's duties arrive in different changes, split it into elements that each arrive whole, such as frame limits split out of a concurrency rule.
     - `Depends on` names every earlier change that builds something this change's scenarios need.
 11. **Cover everything exactly once.** Every delta ID appears in exactly one change. A module the delta adds, or one still `planned` in the living docs, is built by the first change that writes a file in it. A module already `built` isn't listed. Done when `cruze validate` reports no errors for the feature, and no `not-designed` warning.
-12. **Size each change, and the feature.** A change that would need more than about 12 tasks, or touches more than one context's domain, splits in two. A feature of more than 6 changes is more than one design review can hold: split it into features that each serve part of its goals, and run `cruze features add` for the later ones. `cruze validate` warns `feature-size` until it is split.
+12. **Size each change, and the feature.** Aim for changes of about 8 to 25 tasks, each one a sitting's worth of review and verify:
+    - **Merge** a change that builds fewer than 3 elements into the change it continues, when they share adapters or screens, or form a chain where each depends on the one before. Several small changes to the same screens are one change. `cruze validate` warns `change-too-small`.
+    - **Split** a change that delivers more than 30 scenarios, or would need more than 25 tasks, or touches more than one context's domain. One verifier run and one code review can't hold more. `cruze validate` warns `change-too-large`, and `plan-too-large` once a plan passes 25 tasks.
+    - A feature of more than 6 changes is more than one design review can hold: split it into features that each serve part of its goals, and run `cruze features add` for the later ones. `cruze validate` warns `feature-size` until it is split.
+
+    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.
 
 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.