@printpractical/cruze 0.0.9 → 0.0.10

package/dist/domain/skill_budget.js

@@ -0,0 +1,36 @@
+                                                   
+
+/**
+ * The words one instruction file may hold. A longer file holds material only some runs need, so it
+ * splits by branch, as `docs/contributing/writing-skills.md` says, and each run reads only its part.
+ */
+export const MAX_FILE_WORDS = 2100;
+
+/**
+ * The words agents may read across the whole bundle. Every retro adds rules, and between 0.0.1 and
+ * 0.0.10 the skills grew by half while nothing was removed. Lower this when text is cut. Raising it
+ * is the maintainer's decision, with the reason in the commit that raises it.
+ */
+export const BUNDLE_WORD_BUDGET = 44500;
+
+/** Data the CLI reads or renders, rather than instructions an agent reads. */
+const NOT_INSTRUCTIONS = /(^|\/)(templates|notes)\//;
+
+export function wordCount(text        )         {
+  return text.split(/\s+/).filter((word) => word !== "").length;
+}
+
+/** Instruction files over their limit, and the bundle when it is over its budget. */
+export function budgetProblems(skills              )           {
+  const files = skills.flatMap((skill) =>
+    skill.files.filter((f) => f.path.endsWith(".md") && !NOT_INSTRUCTIONS.test(f.path)).map((f) => ({ path: `${skill.folder}/${f.path}`, words: wordCount(f.text) })),
+  );
+  const problems = files
+    .filter((f) => f.words > MAX_FILE_WORDS)
+    .map((f) => `${f.path}: ${f.words} words, over ${MAX_FILE_WORDS}; move what only some runs need into a sibling file`);
+  const total = files.reduce((sum, f) => sum + f.words, 0);
+  if (total > BUNDLE_WORD_BUDGET) {
+    problems.push(`the skills hold ${total} words, over the budget of ${BUNDLE_WORD_BUDGET}; cut or merge text to make room, or raise the budget with the reason in the commit`);
+  }
+  return problems;
+}

package/dist/domain/status/next_step.js

@@ -1,4 +1,5 @@
-import { evaluateApproval } from "../approvals/evaluate.js";
+import { evaluateApproval,                     } from "../approvals/evaluate.js";
+import { rebaseNeeded } from "../approvals/rebase.js";
 import { PATHS } from "../project/layout.js";
 import { isPlanned, readChangesTable } from "../project/plan_parts.js";
 import { readProgress } from "../project/progress.js";
@@ -7,6 +8,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 { pendingReason, pendingRethinks } from "./pending_rethink.js";
 import { awaitsRethink, isVerified } from "./verification.js";
 import { activeChange } from "./work_status.js";
 
@@ -112,7 +114,9 @@ function itemSteps(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 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(", ")})` : ""}` }];
+  if (state.state !== "approved") return [{ step: "rethink", target: item.ref, reason: staleReason(view, item, "the feature", state) }];
+  const pending = pendingRethinks(view.journal, item);
+  if (pending.length > 0) return [{ step: "rethink", target: item.ref, reason: pendingReason(item, pending) }];
   const changes = changesOf(view.items, item);
   const landed = new Set(changes.filter((c) => readProgress(c.doc).landed !== undefined).map((c) => c.folderName));
   const steps             = [];
@@ -131,14 +135,17 @@ function changeStep(view             , change          , branch               )
   const feature = featureOf(view.items, change);
   const featureState = feature === undefined ? undefined : evaluateApproval(view, feature.path);
   if (feature !== undefined && featureState !== undefined && featureState.state !== "approved") {
-    const why = featureState.changed.length > 0 ? ` (${featureState.changed.join(", ")})` : "";
-    return { step: "rethink", target: feature.ref, reason: `the feature of ${change.ref} changed since its approval${why}` };
+    return { step: "rethink", target: feature.ref, reason: staleReason(view, feature, `the feature of ${change.ref}`, featureState) };
+  }
+  for (const part of [feature, change]) {
+    const pending = part === undefined ? [] : pendingRethinks(view.journal, part);
+    if (part !== undefined && pending.length > 0) return { step: "rethink", target: part.ref, reason: pendingReason(part, pending) };
   }
   const bound = readProgress(change.doc).branch;
   const state = evaluateApproval(view, change.path);
   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 (state.state !== "approved") return { step: "rethink", target: change.ref, reason: staleReason(view, change, "the change", state) };
   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);
@@ -147,6 +154,21 @@ function changeStep(view             , change          , branch               )
   return { step: "land", target: change.ref, reason: "the change is verified and accepted" };
 }
 
+/**
+ * Why work went stale, and what the rethink will take: a rebase when its delta still changes an
+ * element whose living text moved, or only a check of the diff and a re-stamp when nothing it cites
+ * asks anything of its own text. One project expected a re-stamp and met rebase-required.
+ */
+function staleReason(view             , item          , label        , state                )         {
+  if (state.state === "edited") return `${label} changed since its approval`;
+  const changed = state.changed.join(", ");
+  const rebase = rebaseNeeded(view, item);
+  const then = rebase.length > 0
+    ? `its delta changes ${rebase.join(", ")}, so rebase it, as cruze diff ${item.ref} shows`
+    : `read cruze diff ${item.ref}, and re-stamp it when the work still holds`;
+  return `something ${label} cites changed since its approval (${changed}); ${then}`;
+}
+
 /** The first roadmap item that hasn't started and whose blockers have all landed. */
 function roadmapStep(view             )                  {
   const text = view.snapshot.get(PATHS.roadmap);

package/dist/domain/status/pending_rethink.js

@@ -0,0 +1,22 @@
+                                                  
+                                                         
+
+/**
+ * Findings decided `rethink` for a feature or change that no rethink of it has followed yet.
+ * One project's realign recorded seven design findings on a feature as fixed "by a rethink before
+ * its next change is planned"; nothing showed them, and they surfaced only in a commit message.
+ */
+export function pendingRethinks(journal                , item          )                 {
+  const lastRethink = journal
+    .filter((e) => e.event === "rethink" && e["item"] === item.ref)
+    .map((e) => e.at)
+    .sort()
+    .at(-1);
+  return journal.filter((e) => e.event === "disposition" && e["disposition"] === "rethink" && e["item"] === item.ref && (lastRethink === undefined || e.at > lastRethink));
+}
+
+/** Why work waits on a rethink, naming the first finding. */
+export function pendingReason(item          , pending                )         {
+  const more = pending.length > 1 ? ` and ${pending.length - 1} more` : "";
+  return `${pending.length} finding(s) on ${item.ref} were decided for a rethink that hasn't happened yet: ${String(pending[0]?.["finding"] ?? "")}${more}`;
+}

package/dist/domain/status/work_status.js

@@ -5,6 +5,7 @@ import { readChangesTable, readScope } from "../project/plan_parts.js";
 import { readProgress } from "../project/progress.js";
                                                               
 import { changesOf, featureOf,               } from "../project/work_items.js";
+import { pendingReason, pendingRethinks } from "./pending_rethink.js";
 
                                
               
@@ -15,6 +16,8 @@ import { changesOf, featureOf,               } from "../project/work_items.js";
                      
                                                                  
                   
+                                                                                
+                            
  
 
                                 
@@ -22,6 +25,8 @@ import { changesOf, featureOf,               } from "../project/work_items.js";
                
                            
                           
+                                                                                 
+                            
  
 
                                 
@@ -42,6 +47,7 @@ export function projectStatus(view             , branch               )
       path: feature.path,
       approval: evaluateApproval(view, feature.path),
       changes: changesOf(view.items, feature).map((change) => changeStatus(view, change)),
+      ...withPending(view, feature),
     }));
   const standalone = active.filter((item) => item.kind === "standalone").map((change) => changeStatus(view, change));
   const status                = { documents, features, standalone };
@@ -69,7 +75,12 @@ function changeStatus(view             , change          )               {
   };
   if (progress.branch !== undefined) status.branch = progress.branch;
   if (progress.landed !== undefined) status.landed = progress.landed;
-  return status;
+  return { ...status, ...withPending(view, change) };
+}
+
+function withPending(view             , item          )                                {
+  const pending = pendingRethinks(view.journal, item);
+  return pending.length === 0 ? {} : { rethinkPending: pending.map((e) => String(e["finding"] ?? "")) };
 }
 
 /** Why building may not start on this branch; empty when the build gate passes. */
@@ -86,7 +97,11 @@ export function buildGateReasons(view             , branch               )
     const detail = status.changed.length > 0 ? `: ${status.changed.join(", ")} changed` : status.unjournaled === true ? ": the approval has no journal entry" : "";
     return [`${path} is ${status.state}${detail}`];
   });
-  return [...approvals, ...unlandedDependencies(view, change, feature)];
+  const rethinks = [feature, change].flatMap((part) => {
+    const pending = part === undefined ? [] : pendingRethinks(view.journal, part);
+    return part === undefined || pending.length === 0 ? [] : [`${pendingReason(part, pending)}; run rethink`];
+  });
+  return [...approvals, ...rethinks, ...unlandedDependencies(view, change, feature)];
 }
 
 /** The changes this change's row in its feature's Changes table depends on that haven't landed on this branch. */

package/dist/domain/validation/decision_rules.js

@@ -0,0 +1,76 @@
+import { definedDecisions, findDecisionCitations, workItemSlugs,                       } from "../decision_citations.js";
+                                              
+import { findSection,                  } from "../markdown.js";
+import { readDelta } from "../project/deltas.js";
+import { PATHS } from "../project/layout.js";
+                                                              
+                                                         
+import { warning,              } from "./problem.js";
+
+const INSTEAD = "write what it decided into this text, or cite the ADR that records it";
+
+/**
+ * The architecture cites only the decisions its own `## Decisions` defines. The other living docs
+ * cite none by number, and no living doc cites a feature's or change's, which is archived when it finishes.
+ */
+export function livingDecisionProblems(view             )            {
+  const slugs = slugsOf(view);
+  const project = projectDecisions(view);
+  const problems            = [];
+  for (const [path, doc] of view.living.docs) {
+    for (const citation of citationsIn(doc, slugs)) {
+      if (citation.qualifier !== undefined) {
+        problems.push(warning(path, citation.line, "decision-citation", `cites ${citation.text}, a decision of ${citation.qualifier}, which the living docs don't hold; ${INSTEAD}`));
+      } else if (path !== PATHS.architecture) {
+        problems.push(warning(path, citation.line, "decision-citation", `cites ${citation.text}, but only the architecture cites decisions by number, its own; ${INSTEAD}`));
+      } else {
+        const unknown = citation.numbers.filter((n) => !project.has(n));
+        if (unknown.length > 0) {
+          problems.push(warning(path, citation.line, "decision-citation", `cites ${unknown.map((n) => `D${n}`).join(", ")}, which "## Decisions" doesn't define; ${INSTEAD}`));
+        }
+      }
+    }
+  }
+  return problems;
+}
+
+/**
+ * A delta's elements merge into the living docs, where the work's own decisions don't follow them.
+ * They may cite a project decision the work doesn't renumber, or one the living element already cites.
+ */
+export function deltaDecisionProblems(view             , item          )            {
+  const slugs = slugsOf(view);
+  const project = projectDecisions(view);
+  const local = definedDecisions(sectionLines(item.doc, "Settled decisions"));
+  const problems            = [];
+  for (const { element } of readDelta(item.doc).entries) {
+    const living = view.living.elements.get(element.id);
+    const carried = new Set(living === undefined ? [] : citationsIn(living.doc, slugs, living.element).flatMap((c) => (c.qualifier === undefined ? c.numbers : [])));
+    const allowed = (n        )          => project.has(n) && (!local.has(n) || carried.has(n));
+    for (const citation of citationsIn(item.doc, slugs, element)) {
+      if (citation.qualifier === undefined && citation.numbers.every(allowed)) continue;
+      problems.push(warning(item.path, citation.line, "decision-citation", `${element.id} cites ${citation.text}, which won't mean the same in the living docs once this delta merges; ${INSTEAD}`));
+    }
+  }
+  return problems;
+}
+
+function citationsIn(doc             , slugs             , element          )                     {
+  const from = element === undefined ? doc.bodyStart : element.start + 1;
+  const to = element === undefined ? doc.lines.length : element.end;
+  return findDecisionCitations(doc.lines, slugs, (line) => line < from || line >= to || doc.inFence[line] === true || doc.inManaged[line] === true);
+}
+
+function projectDecisions(view             )              {
+  const architecture = view.living.docs.get(PATHS.architecture);
+  return architecture === undefined ? new Set() : definedDecisions(sectionLines(architecture, "Decisions"));
+}
+
+function sectionLines(doc             , title        )           {
+  const range = findSection(doc, title);
+  return range === null ? [] : doc.lines.slice(range.start, range.end);
+}
+
+function slugsOf(view             )              {
+  return workItemSlugs(view.items.map((item) => item.folderName));
+}

package/dist/domain/validation/delta_rules.js

@@ -4,6 +4,7 @@ import { specPath } from "../project/layout.js";
 import { orphanDeltaElements, readDelta,            } from "../project/deltas.js";
                                                               
                                                          
+import { deltaDecisionProblems } from "./decision_rules.js";
 import { elementProblems } from "./element_rules.js";
 import { error,              } from "./problem.js";
 
@@ -44,6 +45,7 @@ export function deltaProblems(view             , item          )            {
       problems.push(error(path, op.start, "capability-exists", `capability ${op.capability} already has ${specPath(op.capability)}`));
     }
   }
+  problems.push(...deltaDecisionProblems(view, item));
   return problems;
 }
 

package/dist/domain/validation/future_rules.js

@@ -0,0 +1,40 @@
+import { factsOf, headingElements } from "../elements.js";
+import { readRows } from "../edits/managed_tables.js";
+import { findIds, kindOf } from "../ids.js";
+                                                  
+import { PATHS } from "../project/layout.js";
+import { readDelta } from "../project/deltas.js";
+                                                              
+import { readRoadmapItems } from "../project/roadmap.js";
+import { warning,              } from "./problem.js";
+
+/**
+ * A `Future` fact keeps room for a need someone stated: a `LATER` capability of the vision, or a
+ * feature on the feature map or the roadmap. One that names neither reserves room for a need nobody
+ * stated, which the design reviewer treats as a finding; this makes it visible without a review.
+ */
+export function futureProblems(view             )            {
+  const slugs = anchorSlugs(view);
+  const unanchored = (text        )          =>
+    !findIds(text).some((id) => kindOf(id) === "LATER") && ![...slugs].some((slug) => new RegExp(`(^|[^a-z0-9-])${slug}([^a-z0-9-]|$)`).test(text));
+  const check = (path        , doc             , from = 0, to = doc.lines.length)            =>
+    headingElements(doc, from, to).flatMap((element) =>
+      (factsOf(doc, element).get("Future") ?? [])
+        .filter(unanchored)
+        .map(() => warning(path, element.start, "future-unanchored", `${element.id} keeps room for a need its Future fact doesn't name; cite the LATER capability, or the feature on the map or roadmap, that it serves`)),
+    );
+  const living = view.living.docs.get(PATHS.architecture);
+  const deltas = view.items
+    .filter((item) => !item.archived && item.kind !== "change")
+    .flatMap((item) => readDelta(item.doc).entries.flatMap((entry) => check(item.path, item.doc, entry.element.start, entry.element.end)));
+  return [...(living === undefined ? [] : check(PATHS.architecture, living)), ...deltas];
+}
+
+/** Feature slugs a Future fact may name: the feature map's, implemented or future, and the roadmap's items. */
+function anchorSlugs(view             )              {
+  const vision = view.snapshot.get(PATHS.vision) ?? "";
+  const roadmap = view.snapshot.get(PATHS.roadmap);
+  const mapped = ["Implemented", "Future"].flatMap((heading) => readRows(vision, heading).map((row) => row[0] ?? ""));
+  const planned = roadmap === undefined ? [] : readRoadmapItems(roadmap).map((item) => item.slug);
+  return new Set([...mapped, ...planned].map((slug) => slug.trim()).filter((slug) => /^[a-z0-9-]+$/.test(slug)));
+}

package/dist/domain/validation/living_rules.js

@@ -4,6 +4,7 @@ import { findIds, scopeOf, STATUS_KINDS } from "../ids.js";
                                                   
 import { PATHS } from "../project/layout.js";
                                                               
+import { livingDecisionProblems } from "./decision_rules.js";
 import { elementProblems } from "./element_rules.js";
 import { error, warning,              } from "./problem.js";
 
@@ -26,6 +27,7 @@ export function livingProblems(view             )            {
       if (!view.living.elements.has(id)) problems.push(error(path, lineOf(text, id), "unknown-id", `${id} is cited but not defined in the living docs`));
     }
   }
+  problems.push(...livingDecisionProblems(view));
   return problems;
 }
 

package/dist/domain/validation/validate_project.js

@@ -1,7 +1,9 @@
                                                               
+import { futureProblems } from "./future_rules.js";
 import { livingProblems } from "./living_rules.js";
 import { error, sortProblems,              } from "./problem.js";
 import { configProblems, readmeProblems, roadmapProblems, templateLeftovers } from "./project_rules.js";
+import { visionProblems } from "./vision_rules.js";
 import { workItemProblems } from "./work_item_rules.js";
 
 /** Every rule in the cruze-formats skill, applied to the whole project. */
@@ -13,6 +15,8 @@ export function validateProject(view             )            {
   return sortProblems([
     ...configProblems(view),
     ...livingProblems(view),
+    ...visionProblems(view),
+    ...futureProblems(view),
     ...roadmapProblems(view),
     ...workItemProblems(view),
     ...templateLeftovers(view),

package/dist/domain/validation/vision_rules.js

@@ -0,0 +1,41 @@
+import { rowElements } from "../elements.js";
+import { findSection } from "../markdown.js";
+import { splitRow } from "../markdown_tables.js";
+import { PATHS } from "../project/layout.js";
+                                                              
+import { error,              } from "./problem.js";
+
+/** The section and the cells after the ID that each long-term row of the vision holds. */
+const INTENT_ROWS                                                       = {
+  PRINCIPLE: { section: "Principles", cells: ["Principle", "Why"] },
+  LATER: { section: "Must stay possible", cells: ["Capability", "Likelihood", "Why", "Leave room for"] },
+};
+
+export const LIKELIHOODS = ["likely", "possible"];
+
+/**
+ * The vision's principles and the capabilities that must stay possible are rows, so designs cite
+ * them and approvals pin them. One project kept its principles in a seed note and its long-term
+ * plans in the user's head: a feature reversed a principle unnoticed, and a later review proposed
+ * removing what those plans needed.
+ */
+export function visionProblems(view             )            {
+  const doc = view.living.docs.get(PATHS.vision);
+  if (doc === undefined) return [];
+  return rowElements(doc).flatMap((row) => {
+    const shape = INTENT_ROWS[row.kind];
+    if (shape === undefined) return [];
+    const section = findSection(doc, shape.section);
+    if (section === null || row.start < section.start || row.start >= section.end) {
+      return [error(PATHS.vision, row.start, "vision-row", `${row.id} belongs in the table under ## ${shape.section}`)];
+    }
+    const cells = splitRow(doc.lines[row.start] ?? "").slice(1);
+    if (cells.length !== shape.cells.length || cells.some((cell) => cell === "")) {
+      return [error(PATHS.vision, row.start, "vision-row", `${row.id} needs ${shape.cells.join(", ")}, each filled`)];
+    }
+    if (row.kind === "LATER" && !LIKELIHOODS.includes(cells[1] ?? "")) {
+      return [error(PATHS.vision, row.start, "vision-row", `${row.id}'s likelihood must be ${LIKELIHOODS.join(" or ")}`)];
+    }
+    return [];
+  });
+}

package/dist/domain/versions/rule_versions.js

@@ -17,6 +17,9 @@ export const RULE_SINCE                         = {
   "validate:change-too-large": "0.0.5",
   "validate:plan-too-large": "0.0.5",
   "validate:module-path-glob": "0.0.8",
+  "validate:decision-citation": "0.0.10",
+  "check:decision-citation": "0.0.10",
+  "validate:future-unanchored": "0.0.10",
 };
 
 /** 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.9",
+  "version": "0.0.10",
   "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

@@ -15,7 +15,7 @@ Architect decides the how and the how big. It designs the domain, the ports and
    - **Tweak scope:** the user asks for a small change to existing behaviour. When the design shows it needs any architecture change, it becomes a feature: say so and continue at feature scope.
    - Done when you can say which, and why.
 2. **Check what it builds on.** Run `cruze status`. `docs/vision.md` must be approved and current. At feature and tweak scope, `docs/architecture.md` must be approved and current as well. When a document isn't, stop and name the step that fixes it: `envision` for the vision, and `rethink` for an architecture that changed since its approval.
-3. **Read the living model.** Read `docs/vision.md`, `docs/glossary.md`, `docs/architecture.md`, the ADRs in `docs/adr/`, `docs/roadmap.md`, `.cruze/config.yaml`, and the specs and code the work touches. Read any note in `.cruze/notes/` the user points to.
+3. **Read the living model.** Read `docs/vision.md`, `docs/glossary.md`, `docs/architecture.md` as "Reading it" in `.agents/skills/cruze-formats/reference/architecture.md` says, the ADRs in `docs/adr/`, `docs/roadmap.md`, `.cruze/config.yaml`, and the specs and code the work touches. Take up the notes and the parts of the user's input handed to this work, as "Taking up a hand-off later" in `.agents/skills/cruze-envision/intake.md` describes: at project scope, `cruze show --notes architect`, `cruze show --notes roadmap` and `cruze show --notes project`; at feature or tweak scope, the Notes section of `cruze show <feature>`. Read any other note the user points to.
 4. **Load the standards.** Read these, and follow them for the rest of this step:
    - `.agents/skills/cruze-hexagonal-design/SKILL.md`
    - `.agents/skills/cruze-grilling/SKILL.md`
@@ -31,6 +31,7 @@ Architect decides the how and the how big. It designs the domain, the ports and
 ## Rules
 
 - **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.
+- **Answer to the vision's long-term intent.** Read `## Principles` and `## Must stay possible` in `docs/vision.md`. Every design follows each principle. Check the design against every `LATER` row, not only those in its area: nothing in it may rule one out. Where the design touches a capability's area, leave the room its row names, in a `Future` fact that cites its ID, and build nothing for it. A design that would depart from a principle or close off a capability goes to the user first, as "Long-term intent" in `.agents/skills/cruze-grilling/SKILL.md` describes.
 - **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. 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.

package/skills/architect/feature.md

@@ -9,15 +9,17 @@ The result is a `feature.md` with a complete architecture delta and an ordered l
 
 ## Design the delta
 
-3. **Trace each scenario through the model.** For every scenario in the spec delta, name the inbound adapter it enters through, the use case that runs it, the domain elements that decide it, and the ports it crosses. Done when every scenario has a path, and each missing piece is a named gap.
+3. **Trace each scenario through the model.** Find the elements with `cruze show --index`, and read each one the path crosses with `cruze show <ID>`. For every scenario in the spec delta, name the inbound adapter it enters through, the use case that runs it, the domain elements that decide it, and the ports it crosses. Done when every scenario has a path, and each missing piece is a named gap.
 4. **Place each gap,** following "Placing an owner" in the hexagonal-design skill. Prefer extending an existing element when it is the right owner. Each change to the living model becomes an operation under `## Architecture delta`:
    - `ADDED` for a new element, with its full body.
-   - `MODIFIED` for an existing element, with its full new body. Copy the current body from `docs/architecture.md` and edit it, so nothing is lost by accident.
+   - `MODIFIED` for an existing element, with its full new body. Copy the current body from `cruze show <ID>` and edit it, so nothing is lost by accident.
    - `REMOVED` with a `Reason`, for an element the feature retires.
+   - When the delta changes or retires a rule, find every element, ADR, decision and sentence in the living docs and this feature that states the old rule, and modify or reword each.
+   - A new use of an existing port operation, such as the clock stamping a new kind of time, is a `MODIFIED` port whose `Operations` name the use, and each use case lists every port it calls under `Uses`.
 5. **Link behaviour to design.** Each use case that runs a requirement lists it under `Serves`. Add or modify a `FLOW` for each key scenario, with `Serves` naming its scenarios and the failure paths they need.
 6. **Research and decide.** For each new component that isn't domain logic, run the researcher role and record a row in `## Adopt or build`. Take every new dependency to the user. Then verify every claim the design relies on, following step 7 of adopt or build in `.agents/skills/cruze-research/SKILL.md`. Done when no claim in the design is unverified.
-7. **Keep later seams open.** When the feature map shows a later feature that will extend this area, record the seam in a `Future` fact, and don't build it.
-8. Done when `cruze validate` reports no errors in the delta itself, and every cited ID exists in the living docs or this delta.
+7. **Keep later seams open.** Check the design against every row of the vision's `## Must stay possible`: nothing in it may rule one out. When the feature map shows a later feature that will extend this area, or a capability needs room in it, record the seam in a `Future` fact on the element that keeps it, citing the `LATER` ID or the feature's slug, and don't build it.
+8. Done when `cruze validate` reports no errors and no `decision-citation` warning in the delta itself, and every cited ID exists in the living docs or this delta.
 
 ## Split it into changes
 

package/skills/architect/project.md

@@ -19,7 +19,7 @@ The result has four parts, reviewed together and shown at one walkthrough:
 8. **Modules (`MOD`).** Name the kind of system in the Overview, and choose the layout that is normal for that kind and the language, following `.agents/skills/cruze-hexagonal-design/shapes.md` and the language file. Give each context the fewest modules that keep its layer rules, usually one `core` module and its adapters, and give the shared CLI shell and the composition root the `system` scope. Add a `system` module in the `composition` layer for the build and CI files, such as the package manifest and `.github/workflows/`, so the tasks that write them have an owner. Every source file must fall inside some module's `Path`, including namespace files that join a context's modules, such as `src/inventory/mod.rs` or `index.ts`; list them in a `composition` module's `Path` when no other module fits. Every module gets a `Path` and a `Layer`, and every element above gets its `Module` and `File`.
 9. **Dependency rules (`RULE`).** State what may import what, in one or two sentences each.
 10. **Cross-cutting concerns (`XC`).** Cover errors, configuration, logging, concurrency and security, plus build and delivery (CI, formatting, linting). Read `.agents/skills/cruze-hexagonal-design/runtime.md` for concurrency.
-11. **Decisions.** Write an ADR, with `cruze new adr <slug> --title "<title>"`, for each decision that passes the ADR test. Record the other project decisions as `D<n>` lines under `## Decisions`.
+11. **Decisions.** Write an ADR, with `cruze new adr <slug> --title "<title>"`, for each decision that passes the ADR test. Record the other project decisions as `D<n>` lines under `## Decisions`, including each design choice handed to `architect` that the user keeps.
 12. **Overview (`VIEW-context`).** Draw the context diagram last, once the adapters and external systems are known.
 
 Done when `cruze validate` reports no errors in `docs/architecture.md`. At this stage it warns that elements have no status yet; approval adds the statuses.
@@ -34,7 +34,7 @@ Add the language's build output and tool caches to `.gitignore` now, such as `/t
 
 ## Plan the release
 
-1. **Create the roadmap.** Run `cruze new roadmap`. Agree the first release with the user: its name, and which features from the vision's feature map it delivers.
+1. **Create the roadmap.** Run `cruze new roadmap`. Agree the first release with the user: its name, and which features from the vision's feature map it delivers. Take up the delivery order handed to `roadmap`, as for any hand-off.
 2. **Order the work.** Phase 1 holds only the `walking-skeleton` change. Later phases hold the release's features. Done when the roadmap passes the rules in step 5 of `.agents/skills/cruze-roadmap/SKILL.md`.
 3. **Design the walking skeleton.** Run `cruze new change walking-skeleton --title "Walking skeleton"`. Then:
    - Size the elements it builds for the skeleton. Anything the walking skeleton lists under `Builds` is marked built when it lands, so write those elements, such as the CLI adapter or the first entity, at the size the skeleton needs. Record their planned growth in `Future` facts; later features grow them through `MODIFIED` operations.

package/skills/behavioural-testing/SKILL.md

@@ -11,7 +11,7 @@ Behaviour is the contract. Every scenario in the specs becomes a test that drive
 
 1. Find the test plan rows whose Subject the task proves. Done when you know the seam, test file and kind of every test the task needs.
 2. Write one test at its seam, carrying its subject ID. Take the inputs and expected values from the scenario's GIVEN, WHEN and THEN.
-3. Run it and watch it fail for the reason you expect (red). A test that passes before the code exists proves nothing, so fix the test.
+3. Run it and watch it fail for the reason you expect (red). A test that passes before the code exists proves nothing, so fix the test. A test that guards a race or an ordering must be seen failing against code that has the flaw: run the racing work concurrently, on a multi-threaded runtime where there is one, and wait for a signal the system gives, such as a watch having opened, never for a fixed sleep.
 4. Write the least code that makes it pass (green). Then write the next test. Work in tracer bullets, one test and one slice of code at a time, never all the tests first.
 5. Done when every test plan row whose Subject the task proves has a passing test carrying that ID, and each test fails when the behaviour it checks is removed. Tasks that prove only a `UC`, `ADP` or `MOD` are proved by the rows of the scenarios and ports they serve.
 
@@ -39,13 +39,14 @@ A behaviour test drives a use case, not a single domain type, so it keeps passin
 ## Test support
 
 - Share fixtures and harnesses the way you share fakes. Keep one builder or constant for each domain value tests keep needing, such as a valid configuration or an ID from a string, and one harness per seam, such as an in-process service or the real binary started on a temporary directory. They live in the test support module the language file names.
-- Before writing a helper in a test file, look in the test support module. Use or extend what is there, and never redefine it.
+- Before writing a helper in a test file, look in the test support module and in the test binary's other files. Use or extend what is there, and never redefine it. When a second test file needs a helper, move it into the test support module then, and use it from both.
 - Split a test file by the behaviour it covers, one use case, port or flow per file. File budgets apply to source, not to tests, so never split a test file to meet one.
 
 ## Expected values
 
 - Take expected values from an independent source: the scenario's worked example, a spec, or a known-good literal. Never compute the expected value the way the code does.
 - For a failure scenario, check both the error and the state left behind. After a refused second hop, the first hop is closed.
+- Compare through the constructors and values the code already has. A test is not a caller: never add an accessor, variant or equality to production code only so a test can observe something.
 - Where a plausible wrong outcome exists, assert that it didn't happen.
 
 ## Protecting the check

package/skills/behavioural-testing/fakes.md

@@ -4,9 +4,9 @@ A fake is a real, working implementation of a driven port that keeps its state i
 
 ## Writing a fake
 
-1. Read the port's `Operations` in `docs/architecture.md`. The fake implements every operation with the guarantees and failures listed there, and nothing more.
+1. Read the port's `Operations`, with `cruze show <PORT ID>`. The fake implements every operation with the guarantees and failures listed there, and nothing more. That includes every way the real adapter ends on its own, such as a session closed when its stream ends or its server shuts down.
 2. Keep state in plain in-memory structures: a map for a catalog, a list for recorded effects, a settable value for a clock.
-3. Give tests a way to arrange state and to inject each failure the contract lists. Use a constructor that takes the initial state, and a method such as `fail_next_with(HopError::Refused)`.
+3. Give tests a way to arrange state and to inject each failure the contract lists. Use a constructor that takes the initial state, and a method such as `fail_next_with(HopError::Refused)`. When a use case writes through the port, also let a test stall an operation, and fail one that writes several things partway through, so each partial failure and cancellation can be tested from every state it can leave.
 4. Record effects the contract makes observable, such as the order hops were closed in, so tests can assert them.
 5. Put the fake where every test can reach it, such as `tests/support/` or the language's test-only module, never in production code paths. One fake per port, shared by all tests.
 
@@ -17,7 +17,7 @@ Done when the fake passes the port's contract tests.
 A contract test states the port's contract once and runs it against every implementation.
 
 1. Write the cases as a function or suite that takes a constructor for the implementation under test.
-2. Cover each operation's success, each failure the contract names, and the state after a failure.
+2. Cover each operation's success, each failure the contract names, each way the implementation ends on its own, and the state after a failure.
 3. Run the suite against the fake in the ordinary test run.
 4. Run it against each real adapter too. When the real adapter needs something external, such as an SSH server, a serial device or a database, use a local stand-in (a test server, a pseudo-terminal, a container), and mark the run so CI can provide it.
 

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 a reference it lists at the sections the change's elements cite. 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, with `cruze show <ID>`, 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`.
@@ -36,7 +36,7 @@ For task `T<n>`:
 5. **Commit** with a Conventional Commit message naming the task, such as `feat(access): console session state machine (T2)`.
 6. **Tick it.** Run `cruze task done T<n>`, which records the commit. Its progress edit rides along in the next commit.
 
-A task with no behaviour of its own, such as a package manifest or a plain data type, has no red step. Build it, check it, commit it and tick it, and the first task whose test uses it covers it.
+A task with no behaviour of its own, such as a package manifest or a plain data type, has no red step. Build it, check it, commit it and tick it, and the first task whose test uses it covers it. Neither has a prefactor's task: run the tests its plan names under `## Risks` before the first task, and after each task, and they pass unchanged.
 
 Done for a task when its tests pass, `cruze check --ci` passes for its files, the commit exists and the task is ticked.
 

package/skills/envision/SKILL.md

@@ -10,7 +10,7 @@ Envision decides the what: the problem, who has it, and the behaviour that solve
 ## Steps
 
 1. **Pick the scope.** It is project scope when `docs/vision.md` doesn't exist yet, or when the user asks to rework the project's goals. It is feature scope when the user names a feature. When unsure, ask. Done when you can say which.
-2. **Gather the input.** Read what the user gave you: pasted drafts, files they point to, and notes in `.cruze/notes/`. Read whichever of `docs/vision.md`, `docs/glossary.md`, `docs/roadmap.md` and `docs/architecture.md` exist, and run `cruze status`.
+2. **Gather the input.** Read what the user gave you: pasted drafts, files they point to, and the notes `cruze show --notes` lists. Read whichever of `docs/vision.md`, `docs/glossary.md`, `docs/roadmap.md` and `docs/architecture.md` exist, and run `cruze status`.
 3. **Load the standards.** Read `.agents/skills/cruze-grilling/SKILL.md` and `.agents/skills/cruze-domain-language/SKILL.md`, and follow them for the rest of this step.
 4. **Follow the scope's procedure.** For project scope, follow [project.md](project.md). For feature scope, follow [feature.md](feature.md). Each one ends with the user's confirmation.
 5. **Check the documents.** Run `cruze validate`. Done when it reports no errors in the documents this step wrote. At feature scope, expect one `not-designed` warning for the feature, which `architect` clears.
@@ -20,7 +20,8 @@ Envision decides the what: the problem, who has it, and the behaviour that solve
 - Write in the user's terms and the glossary's words. Behaviour is described from outside the system: what a user does and what they observe.
 - 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.
+- Problem through Constraints stay within one page. A principle or a capability that must stay possible takes as much as its intent needs: never shorten one to fit.
+- The product's long-term intent lives in the vision, in its Principles and Must stay possible tables, at either scope. Designs answer to it for the product's whole life, long after the conversation that settled it.
 - 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

@@ -7,13 +7,15 @@ The result is a feature folder whose `feature.md` holds the intent, the settled
    - When it isn't in the roadmap's phases, ask the user whether it belongs in this release. If it does, add it by following "Adding an item" in `.agents/skills/cruze-roadmap/SKILL.md`, and re-approve the roadmap. If it doesn't, put it on the future list with `cruze features add` and stop here.
    - When its `Blocked by` items haven't landed (see the roadmap's `## Status`), tell the user. Continue only if they want to design ahead, and record that as a settled decision.
 3. **Create the folder.** When the feature has no folder yet, run `cruze new feature <slug> --title "<title>" --roadmap <slug>`, using its roadmap slug. When a folder exists, edit its `feature.md`.
-4. **Read the behaviour it touches.** Read the specs in `docs/specs/` for every capability the feature changes, so you know each requirement and scenario it builds on.
+4. **Read the behaviour it touches.** Read the specs in `docs/specs/` for every capability the feature changes, so you know each requirement and scenario it builds on. Run `cruze show --notes <slug>`, and take up the notes about this feature and the parts of the user's input handed to it, open questions included, as "Taking up a hand-off later" in [intake.md](intake.md) describes.
 5. **List the open decisions:**
    - **Intent:** the problem and outcome in the user's words, who it is for, the constraints, and what is out of scope.
    - **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.
+   - **Later:** the vision's `PRINCIPLE` and `LATER` rows this feature touches, and the capabilities it may grow into, asked about as [possibilities.md](possibilities.md) describes. A feature that adds sign-in asks about single sign-on and multi-factor authentication, for example.
 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>`.
+   - When an answer names something the product may need later, or a decision departs from a principle, the vision changes, as "Long-term intent" in the grilling skill describes. A settled decision of this feature is archived when it lands, so it can't hold either.
 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.