@printpractical/cruze 0.0.3 → 0.0.5

package/dist/app/use_cases/record_progress.js

@@ -58,6 +58,23 @@ export async function addFutureFeature(deps             , slug        , summary
   return { feature: slug };
 }
 
+/**
+ * Replaces a feature's summary on the feature map, in the future list or the implemented list,
+ * when a decision changed what the feature delivers. Its goals or release stay as they are.
+ */
+export async function updateFeatureSummary(deps             , slug        , summary        )                                                               {
+  if (summary.trim() === "") throw new CruzeError("missing-summary", "a feature needs a summary");
+  const vision = await requireVision(deps);
+  const future = readRows(vision, "Future").find((row) => row[0] === slug);
+  const implemented = readRows(vision, "Implemented").find((row) => row[0] === slug);
+  if (future === undefined && implemented === undefined) throw new CruzeError("not-found", `${slug} is not on the feature map`);
+  const list = future !== undefined ? "Future" : "Implemented";
+  const cells = future !== undefined ? [slug, summary.trim(), future[2] ?? ""] : [slug, implemented?.[1] ?? "", summary.trim()];
+  await deps.files.writeText(PATHS.vision, upsertRow(vision, list, cells));
+  await appendJournal(deps, ".cruze", "feature-map", { action: "update", feature: slug, summary: summary.trim() });
+  return { feature: slug, list };
+}
+
 export async function dropFutureFeature(deps             , slug        , reason        )                               {
   const vision = await requireVision(deps);
   const { text, removed } = removeRow(vision, "Future", slug);

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

@@ -21,6 +21,7 @@ export const RECORDED_EVENTS                           = {
 const OPTIONAL_FIELDS                           = {
   rethink: ["missed_by"],
   review: ["nits"],
+  disposition: ["decided"],
 };
 
 /** The workflow steps and checks that find or miss a problem, so a retro can count them. */
@@ -30,6 +31,7 @@ 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"],
   found_by: STEPS,
@@ -77,6 +79,9 @@ 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 === "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/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/status/work_status.js

@@ -1,5 +1,4 @@
 import { evaluateApproval,                     } from "../approvals/evaluate.js";
-import { findIds } from "../ids.js";
 import { PATHS } from "../project/layout.js";
 import { readDelta } from "../project/deltas.js";
 import { readScope } from "../project/plan_parts.js";
@@ -89,13 +88,12 @@ export function buildGateReasons(view             , branch               )
   });
 }
 
-/** The elements a change touches: its scope plus every ID its documents cite. */
+/** The elements a change touches: its scope and its delta, not the elements it only cites, such as a test seam. */
 export function touchedIds(view             , change          )              {
   const feature = featureOf(view.items, change);
   const scope = readScope(change.doc);
   const ids = new Set([...(scope?.delivers ?? []), ...(scope?.builds ?? []), ...(scope?.removes ?? [])]);
   const deltaDoc = feature?.doc ?? change.doc;
   for (const id of readDelta(deltaDoc).ids) ids.add(id);
-  for (const id of findIds(change.doc.lines.join("\n"))) ids.add(id);
   return new Set([...ids].filter((id) => !id.startsWith("RULE-")));
 }

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.3",
+  "version": "0.0.5",
   "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/about/SKILL.md

@@ -9,7 +9,7 @@ Cruze is a spec-driven development framework. It keeps one living model of the s
 
 This installation is an early preview. It has:
 
-- The `cruze` CLI: `cruze init` sets up a repository, `cruze install` updates the skills after an upgrade, and `cruze help` lists the commands that validate, approve, check, trace and land work.
+- The `cruze` CLI: `cruze init` sets up a repository, `cruze install` updates the skills after an upgrade, and `cruze help` lists the commands that validate, approve, check, trace and land work. Each prints its result on stdout, as JSON when stdout isn't a terminal, or as text with `--text`. A command refuses an option it doesn't take, so check `cruze help` when one is refused.
 - `cruze-formats`, the format of every Cruze document.
 - Knowledge skills holding the standards to design and code to: `cruze-hexagonal-design`, `cruze-behavioural-testing`, `cruze-grilling`, `cruze-domain-language`, `cruze-dependency-approval` and `cruze-research`.
 - The workflow: `explore` (optional), `envision` for the what, `architect` for the how, `roadmap` for the order of work, then `plan`, `build`, `verify` and `land` for each change. `triage` handles bugs, `rethink` steps back from anywhere, and `next` says what to do now.

package/skills/architect/feature.md

@@ -21,11 +21,16 @@ 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.
 
 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/envision/SKILL.md

@@ -21,7 +21,7 @@ Envision decides the what: the problem, who has it, and the behaviour that solve
 - Requirements and scenarios follow `.agents/skills/cruze-formats/reference/specs.md`. Every scenario uses concrete values: real names, real inputs, exact output. The scenarios become the tests, so their values are the expected results.
 - Keep implementation out: no modules, types, libraries or file formats unless the user names one as a constraint. When the user raises one, record it as a constraint or a settled decision and move on.
 - The vision stays within one page, excluding the feature map.
-- Only the CLI writes the feature map. Use `cruze features add` and `cruze features drop`.
+- Only the CLI writes the feature map. Use `cruze features add`, `cruze features update` and `cruze features drop`.
 
 ## Next step
 

package/skills/envision/feature.md

@@ -13,6 +13,7 @@ The result is a feature folder whose `feature.md` holds the intent, the settled
    - **Requirements:** each behaviour the feature adds, changes or removes, and the capability it belongs to. It goes in an existing capability when the behaviour fits one; otherwise it starts a new capability.
    - **Scenarios:** for each requirement, the main case, each edge and failure case a user will meet, and what they observe in each. Invent concrete edge cases to test the boundaries.
 6. **Grill in rounds** until every open decision is settled. Record decisions under `## Settled decisions` and terms in the glossary as they settle.
+   - When a decision changes something the feature's summary on the feature map promises, such as a policy it names, correct the summary with `cruze features update <slug> --summary <text>`.
 7. **Write the spec delta.** Use `ADDED` for new requirements, `MODIFIED` for a requirement whose text or scenarios change (writing its full new body with every scenario it keeps), `REMOVED` with a `Reason` and `Migration` for retired behaviour, and `ADDED CAPABILITY` for a new capability.
    - 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.

package/skills/formats/SKILL.md

@@ -66,7 +66,7 @@ The CLI owns some content so that routine bookkeeping never changes a design:
 - A block between `<!-- cruze:managed -->` and `<!-- /cruze:managed -->` is written only by the CLI.
 - A `- Status: planned` or `- Status: built` item in an element body is written only by the CLI. Elements that have code (`ENT`, `UC`, `PORT`, `ADP`, `FLOW`, `MOD`) and scenarios (`SCN`) carry one.
 - Both are excluded from every hash. Read them freely; change them only through `cruze` commands:
-  - `cruze approve` adds missing statuses to the architecture, sets built elements back to planned with `--replan`, and binds a change to its branch.
+  - `cruze approve` adds missing statuses to the architecture, sets built elements back to planned with `--replan`, and binds a change to its branch. With `--by-agent` it approves a change whose plan review closed, and with `--restamp-unchanged` it re-stamps work a rethink left unchanged, recording that the agent gave the approval.
   - `cruze task` records progress, and `cruze features` edits the feature map.
   - `cruze land` merges work, marks it built and fills the Commands and Layout sections of `AGENTS.md`.
   - `cruze roadmap prune` and `cruze abandon` update the roadmap's status.

package/skills/formats/reference/config.md

@@ -27,6 +27,12 @@ commands:
 
 review:
   command: ["claude", "-p", "--allowedTools", "Read Grep Glob Bash(git diff:*) Bash(git log:*) Bash(git show:*) Bash(cruze:*) Bash(cargo:*)"]
+  decide: exceptions
+
+changes:
+  min_builds: 3
+  max_scenarios: 30
+  max_tasks: 25
 
 layers:
   - name: inventory-domain
@@ -52,6 +58,10 @@ layers:
 | `layers` | Each layer has a `name`, the `paths` it covers, and `may_import`, the layers it may depend on. |
 | `commands` | The project's commands by name, such as `test` or `run`. The walking-skeleton change fills them in, and `cruze land` copies them into the Commands section of `AGENTS.md`. |
 | `review.command` | The program and arguments `cruze review` runs to start an agent in a fresh context, with the prompt on standard input. Optional. `cruze init` sets it for Claude Code to run in print mode, allowed to read the project and run `git diff`, `git log`, `git show` and `cruze`. The verifier runs the system, so add the project's build and run commands. When it is unset, or its program isn't installed, `cruze review` hands the role's prompt back to the calling agent to run in a helper. |
+| `review.decide` | Which review findings the user decides. `exceptions`, the default: only findings whose fix changes behaviour, a designed port or contract, or another decision the user owns, and any the agent wouldn't simply fix as proposed. The agent fixes the rest and lists them. `all`: the user decides every finding. |
+| `changes.min_builds` | A feature's change that builds fewer elements than this gets a `change-too-small` warning: merge it into the change it continues. Default `3`. |
+| `changes.max_scenarios` | A change that delivers more scenarios than this gets a `change-too-large` warning: split it. Default `30`. |
+| `changes.max_tasks` | A plan with more tasks than this gets a `plan-too-large` warning. Default `25`. |
 
 Rules for layers:
 

package/skills/formats/reference/durable-docs.md

@@ -16,7 +16,7 @@ What the product is for. At most one page, excluding the feature map.
 | `## Feature map` | Managed. `### Implemented` is a table of Feature, Release and Summary. `### Future` is a table of Feature, Summary and Goals |
 
 - Feature-map entries are named by slug, such as `jump-hosts`. A future entry gets a folder ID only when its feature starts.
-- Only the CLI writes the feature map. `cruze features add` puts an entry on the future list, `cruze features drop` removes one, and `land` moves a finished feature to implemented, tagged with the release in progress.
+- Only the CLI writes the feature map. `cruze features add` puts an entry on the future list, `cruze features update` corrects an entry's summary on either list, `cruze features drop` removes one from the future list, and `land` moves a finished feature to implemented, tagged with the release in progress.
 
 ## docs/glossary.md
 

package/skills/formats/reference/work-items.md

@@ -35,7 +35,7 @@ Templates: [../templates/feature.md](../templates/feature.md), [../templates/cha
 
 A standalone change adds `## Intent`, `## Adopt or build`, `## Spec delta` and `## Architecture delta` before its `## Scope`, in the same format as a feature's. Its scope covers every ID in its own deltas, plus any `planned` elements from the living docs that it builds.
 
-A feature is designed in two steps. Feature-scope `envision` writes the intent, settled decisions and spec delta, and leaves `## Architecture delta` as `None.` and the Changes table empty. `architect` writes the architecture delta and the changes. Until the Changes table has a row, `cruze validate` reports the feature as `not-designed` (a warning), skips the coverage rules, and `cruze approve` refuses it. A feature of more than 6 changes gets a `feature-size` warning: split it, because one design review can't hold it.
+A feature is designed in two steps. Feature-scope `envision` writes the intent, settled decisions and spec delta, and leaves `## Architecture delta` as `None.` and the Changes table empty. `architect` writes the architecture delta and the changes. Until the Changes table has a row, `cruze validate` reports the feature as `not-designed` (a warning), skips the coverage rules, and `cruze approve` refuses it. A feature of more than 6 changes gets a `feature-size` warning: split it, because one design review can't hold it. A change outside the size band in `changes:` of `.cruze/config.yaml` gets `change-too-small` (it builds fewer than 3 elements, in a feature of several changes) or `change-too-large` (it delivers more than 30 scenarios), and a plan of more than 25 tasks gets `plan-too-large`.
 
 `architect` writes a standalone change's design sections and its scope, and leaves the test plan table empty and the tasks section blank. Until `plan` fills them, `cruze validate` reports the change as `not-planned` (a warning), skips the task and test plan rules, and `cruze approve` refuses it.
 

package/skills/land/SKILL.md

@@ -20,6 +20,7 @@ Land makes finished work part of the living model. `cruze land` merges the chang
    - When they don't hold, stop and offer `rethink`.
 4. **Run `cruze land`** and quote its report: what it merged, what is now built, and whether the work finished and was archived.
    - A `merge-conflict` means someone changed an element this feature merged earlier. Stop and run `rethink`, which reconciles it.
+   - When the work finished, read the feature's row under `### Implemented` in `docs/vision.md` against its settled decisions and spec delta. When the summary no longer describes what landed, correct it with `cruze features update <slug> --summary <text>`.
    - A `merge-invalid` means the merged docs, or the feature and changes being landed, wouldn't validate, such as a decision citing an ID the change removes. Nothing was written. Stop and run `rethink`.
 5. **Update the changelog.** Under `## [Unreleased]` in `CHANGELOG.md`, add one line per user-visible behaviour the change delivers, in the user's words, under `### Added`, `### Changed` or `### Removed`. Name the behaviour, not the code, including any rule a user can now run into that no scenario covers yet.
 6. **Update the README** when the change altered how someone installs, runs or uses the product. Run every command you add, to check it works.

package/skills/plan/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cruze-plan
-description: Turns the next change into a test plan and ordered tasks with file targets, reviews the plan in a fresh context, and records your approval on the branch that will build it.
+description: Turns the next change into a test plan and ordered tasks with file targets, reviews the plan in a fresh context, and approves it on the branch that will build it once the review closes, leaving you to object or go straight to build.
 ---
 
 # Plan
@@ -26,7 +26,7 @@ Plan turns one designed change into work an implementer can do without guessing:
 10. **Record decisions and risks.** Put task-level choices you made under `## Settled decisions`. Under `## Risks`, name the riskiest task and how its test catches the failure. Remove every template guide.
 11. **Validate.** Run `cruze validate`. Done when it reports no errors for the change.
 12. **Review the plan.** Commit the plan, then run the review in `.agents/skills/cruze-roles/SKILL.md` with the design reviewer and its plan rubric, `review=plan`, and `--item <ref>`.
-13. **Approve.** Show the user the test plan table, the tasks in order and the risks. When they approve, run `cruze approve <ref>` on this branch and quote its result. The approval binds the change to the branch.
+13. **Approve.** Run `cruze approve <ref> --by-agent` on this branch and quote its result. The plan carries no design of its own, so once its review has closed, with no blocker open and a disposition for every finding, you approve it for the user. The approval binds the change to the branch. When it refuses with `plan-review-open`, do what it names. A blocker still open after round 2 goes to the user, and once they decide it, they approve the plan themselves with `cruze approve <ref>`.
 14. **Commit** with a message such as `docs: plan <change>`.
 
 ## When the plan needs design
@@ -49,4 +49,4 @@ The walking-skeleton change also makes CI and the project's tooling real. Its pl
 
 ## Next step
 
-`build`, on this branch.
+Show the user the test plan table, the tasks in order and the risks, and say the plan is approved. They can object, and you amend the plan, run its review on the diff, and approve again. Otherwise the next step is `build`, on this branch.

package/skills/realign/notes/0.0.4.md

@@ -0,0 +1,27 @@
+# Realign notes: 0.0.4
+
+## New work only
+
+### argument-files-anywhere: Files named on the command line may be outside the project
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/SKILL.md`, "Running a role"
+
+### cli-output-format: The CLI prints one format on stdout, JSON for agents and text with --text
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-about/SKILL.md`
+
+### overlap-scope: Overlap counts only in-flight changes, and only the elements their scope and delta name
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-plan/SKILL.md`, "Steps", step 7
+
+### refused-options: The CLI refuses an option its command doesn't take
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-about/SKILL.md`
+
+### feature-map-summary: A feature's summary on the feature map follows its decisions
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-land/SKILL.md`, "Landing a change", step 4
+
+### journal-list-item: Journal list narrows to one feature or change with --item
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-about/SKILL.md`

package/skills/realign/notes/0.0.5.md

@@ -0,0 +1,38 @@
+# Realign notes: 0.0.5
+
+## New work only
+
+### review-exceptions: The user decides only the review findings that are theirs
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/SKILL.md`, "Running a review", round 1, steps 3 to 5
+
+### plan-approved-by-agent: A plan is approved once its review closes, without stopping for the user
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-plan/SKILL.md`, "Steps", step 13
+
+### rethink-restamps: A rethink re-stamps the work it didn't change
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-rethink/SKILL.md`, "Steps", step 6
+
+### change-too-small: A feature's change builds at least 3 elements
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-architect/feature.md`, step 12
+- Detect: validate:change-too-small
+
+### change-too-large: A change delivers at most 30 scenarios
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-architect/feature.md`, step 12
+- Detect: validate:change-too-large
+
+### plan-too-large: A plan has at most 25 tasks
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-architect/feature.md`, step 12
+- Detect: validate:plan-too-large
+
+### concerns-per-size: Reviewers list concerns in proportion to the work
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-roles/code-reviewer.md`, "Findings"
+
+### reverify-changed-plan: A plan changed after verify needs verifying again, whoever approved it
+- Applies to: new work only
+- Rule: `.agents/skills/cruze-verify/SKILL.md`

package/skills/realign/notes.md

@@ -6,6 +6,8 @@ Each release that changes what Cruze expects of a project ships a notes file, `n
 
 - [0.0.2](notes/0.0.2.md)
 - [0.0.3](notes/0.0.3.md)
+- [0.0.4](notes/0.0.4.md)
+- [0.0.5](notes/0.0.5.md)
 
 ## Format
 

package/skills/rethink/SKILL.md

@@ -18,7 +18,11 @@ Finding a design flaw mid-build is information, not failure. Rethink amends the
 3. **Load the standards.** Read `.agents/skills/cruze-grilling/SKILL.md`. At feature or architecture level, also read `.agents/skills/cruze-hexagonal-design/SKILL.md`. Also read the format reference for the document you will amend: `.agents/skills/cruze-formats/reference/architecture.md`, `specs.md`, `work-items.md` or `durable-docs.md`.
 4. **Amend that level,** following the level's section in [levels.md](levels.md). Settle any decision the amendment needs with the user, and record it as that level records decisions.
 5. **Keep completed work.** A ticked task stays ticked unless the amendment changes its owner, its files, or what it proves. Reopen each task that changed with `cruze task reopen T<n> "<what changed>"`. Its commits stay in history, and build redoes the task.
-6. **Re-approve what went stale.** Run `cruze status` and work from the top down: the amended document first, then each document it lists as `upstream changed`. For each one, show the user the diff of the elements it names, and re-approve it with `cruze approve <ref>` once they agree. A change's verification carries over when its own design didn't change.
+6. **Re-approve what went stale.** Run `cruze status` and work from the top down. The amended document comes first, and the user approves it as its level says. Then take each feature or change it lists as `upstream changed`, whose own text you didn't edit:
+   - Read the diff of the elements it names, and check the work still holds against them. When it doesn't, amend it too, and the user approves it as an amended document.
+   - When it holds, re-stamp it with `cruze approve <ref> --restamp-unchanged`. The CLI refuses work whose own text changed, a project document, and a change with a task reopened since its approval; the user re-approves those.
+
+   Tell the user, in one line each, what you re-stamped and why it still holds. They can object, and that document goes to them. A change's verification carries over when its own design didn't change.
 7. **Record the rethink.** Draft the entry and show it to the user in one line. When they confirm, run:
 
    ```sh

package/skills/rethink/levels.md

@@ -5,14 +5,14 @@
 1. Edit the change's `## Test plan` or `## Tasks` so they are right. The scope doesn't change at this level; a scope change is a feature-level rethink.
 2. Run `cruze validate`. Done when it reports no errors for the change.
 3. Run the plan review from `.agents/skills/cruze-roles/SKILL.md` on the diff alone, with the design reviewer's plan rubric and `review=plan`.
-4. Re-approve with `cruze approve <change>`.
+4. Re-approve with `cruze approve <change> --by-agent` once the review has closed, as plan does.
 
 ## Feature
 
 1. Edit the feature's `## Spec delta`, `## Architecture delta` or `## Changes`. For a standalone change, edit its own deltas and scope. Write complete bodies, as `architect` does, and keep the scope rules.
 2. Run `cruze validate`. Done when it reports no errors for the feature or its changes.
 3. Run the design review from the roles skill on the diff alone, with `review=design`. Walk the user through the changed parts, following `.agents/skills/cruze-architect/walkthrough.md`.
-4. Re-approve the feature. For each of its changes that shows as stale, update the change's scope, test plan and tasks to match. Reopen touched tasks, and re-approve the change.
+4. Re-approve the feature. For each of its changes that shows as stale, check it against the diff. When the amendment touches the change's scope, test plan or tasks, update them to match, reopen touched tasks, run the plan review on the diff, and re-approve it with `cruze approve <change> --by-agent`. When it doesn't, re-stamp the change as the skill's step 6 describes.
 5. When a change hasn't been created yet, only the feature's Changes row changes; `plan` picks it up.
 
 ## Architecture
@@ -26,11 +26,11 @@
    - **A prefactor**, otherwise. From an up-to-date main, run `architect "<prefactor>"`, which designs it as a standalone change, then `plan`, `build`, `verify` and `land` it before the current change continues.
 6. Run `cruze status`. Every document citing a changed element shows `upstream changed`:
    - When the document's own delta changes that element, rewrite the delta so it keeps your amendment. `cruze approve` refuses it with `rebase-required` until you do. Then approve it with `--rebase <ID>`.
-   - Otherwise, show the user the element's diff, and re-approve the document as the skill's step 6 describes.
+   - Otherwise, check the document against the element's diff, and re-stamp it or amend it as the skill's step 6 describes.
 
 ## Vision
 
-1. Edit `docs/vision.md` with the user: goals, non-goals or constraints. The feature map changes only through `cruze features add` and `cruze features drop`. When the problem, users or goals changed, update the overview under the title of `README.md` to match.
+1. Edit `docs/vision.md` with the user: goals, non-goals or constraints. The feature map changes only through `cruze features add`, `cruze features update` and `cruze features drop`. When the problem, users or goals changed, update the overview under the title of `README.md` to match.
 2. Update `docs/roadmap.md` to match, following `.agents/skills/cruze-roadmap/SKILL.md`.
 3. For each feature in progress that served a dropped goal, the user decides: keep it, or stop it with `cruze abandon <ref> --reason "<why>"`. Abandoning archives the folder and puts the feature back on the future list; changes that already landed stay.
 4. Re-approve with `cruze approve vision`, then `cruze approve roadmap`.