@printpractical/cruze 0.0.8 → 0.0.10

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

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

package/dist/domain/validation/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/dist/main.js

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
 // Composition root: the only place that constructs adapters.
-import { basename } from "node:path";
+import { basename, relative } from "node:path";
 import { runCli } from "./adapters/inbound/cli/run_cli.js";
 import { GitRepository } from "./adapters/outbound/git_repository.js";
 import { NodeProjectFiles } from "./adapters/outbound/node_project_files.js";
 import { PackageBundle } from "./adapters/outbound/package_bundle.js";
+import { findProjectRoot } from "./adapters/outbound/project_root.js";
 import { ProcessAgentRunner } from "./adapters/outbound/process_agent_runner.js";
 import { SystemClock } from "./adapters/outbound/system_clock.js";
 import { DefaultAnswerPrompter, TerminalPrompter } from "./adapters/outbound/terminal_prompter.js";
@@ -16,18 +17,21 @@ process.stdout.on("error", (error                       ) => {
 });
 
 const cwd = process.cwd();
+// Every command but init works on the project that holds the working directory, so it runs from any subdirectory.
+const root = process.argv[2] === "init" ? cwd : (findProjectRoot(cwd) ?? cwd);
 const exitCode = await runCli(
   process.argv.slice(2),
   {
-    files: new NodeProjectFiles(cwd),
+    files: new NodeProjectFiles(root),
     bundle: await PackageBundle.locate(),
     clock: new SystemClock(),
-    repository: new GitRepository(cwd),
+    repository: new GitRepository(root),
     interactivePrompter: new TerminalPrompter(),
     unattendedPrompter: new DefaultAnswerPrompter(),
-    runner: new ProcessAgentRunner(cwd),
+    runner: new ProcessAgentRunner(root),
     interactive: process.stdin.isTTY === true,
     directoryName: basename(cwd),
+    workingDirectory: relative(root, cwd).split("\\").join("/"),
   },
   {
     stdout: (text) => process.stdout.write(`${text}\n`),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@printpractical/cruze",
-  "version": "0.0.8",
+  "version": "0.0.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,8 +31,10 @@ 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 and fits the budget in `.cruze/config.yaml`.
+- **Every element with code has a home.** Each `ENT`, `UC`, `PORT`, `ADP` and `FLOW` names its `Module` and `File`. Each file has one responsibility. Never split an owner across files to keep them short.
+- **Comply with the references.** When the project must follow an external document, such as a protocol specification, it is listed under `references:` in `.cruze/config.yaml`; at project scope, ask the user whether there is one, and list it with what it governs. Read the parts each element relies on, and cite the section in the element's body, such as `RFC 4254 §5.2`, so plan, build and the reviewers can check it.
 - **Ask, challenge and defer** as the grilling skill describes. Contexts, ports, public contracts, dependency direction and dependencies are always the user's decisions.
 - **Stepping back is normal.** When the design shows that the vision or an earlier decision is wrong, stop and say so. The vision changes through `envision`, and an approved architecture through `rethink`.
 
@@ -42,4 +44,6 @@ Architect decides the how and the how big. It designs the domain, the ports and
 - Feature scope: `plan` for the feature's first change.
 - Tweak scope: `plan` for the standalone change.
 
+Plan branches from main, so get the approved design onto main first, as a pull request or a merge, together with the vision or feature map it builds on. A plan branched from an unmerged design branch carries the design into the change's pull request.
+
 Start it in a new session, so its context starts empty.

package/skills/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 `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.
 
@@ -53,6 +53,7 @@ The plan is design. Within a task you decide only what is local and reversible.
   - a limit, timeout, buffer size, message or error case the design doesn't give. Picking one in code hides a gap in the design: the user decides it, at feature level. Two projects settled 35 of them as deviations.
 
   Explain what you found, with the evidence, and don't work around it. Completed tasks keep their commits.
+- **Read a deviation back before you record it.** One that says the design gives no value, text, error or outcome and names the one you chose, or that the code can't keep a promise a port or use case makes, is a rethink, not a deviation. In one change, two deviations worded that way came back as code-review blockers and sent it back at verify.
 - Never edit `feature.md`, `docs/architecture.md` or `docs/specs/` during build. Design changes go through `rethink`.
 
 ## Protecting the check

package/skills/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.

package/skills/envision/intake.md

@@ -0,0 +1,28 @@
+# Taking in the user's input
+
+The user may bring anything: a seed, a PRD, a TRD, a design write-up, an old project's notes, a pasted paragraph or a link. Everything in it is open for discussion, and every part of it reaches the step that takes it up. One project's 9,500-word seed held design that no step was told to read, and intent the vision had no room for.
+
+1. **Gather it.** Read every source the user names or pastes, and each note `cruze show --notes` lists with kind `input`. Run `cruze new note intake --title "Intake: <what the input is>" --kind intake --about project`. Under `## Sources`, cite each file in the repository by path, and copy in, verbatim, what would otherwise be lost: pasted text, and a document outside the repository, such as a link or a PDF.
+2. **Sort every part** by the step that takes it up. Name each part by its heading, or by a short quote where the input has none:
+   - `vision`: the problem, users, goals, non-goals, constraints, principles, and what must stay possible.
+   - `architect`: design choices, such as structure, protocols, technologies and data formats.
+   - `roadmap`: delivery order and phases.
+   - a feature's slug: one feature's behaviour, rules, limits and examples. Use the slug the feature map gives it.
+   - `user`: preferences about the process itself, which the user may add to `AGENTS.md`.
+
+   An open question goes to the step that settles it. Done when every part of every source has a place.
+3. **Read its stance.** Note how settled the input says each part is, from its own legend when it has one, or from its wording: "we decided" and "must" are firmer than "maybe", "TBD" or a question. Nothing is settled by being written down. The stance sets only your recommendation: keep what the input settled, with its reason; ask about what it proposed; research what it guesses; settle what it leaves open.
+4. **Write the hand-off** in the intake note, under `## Hand-off`, one row per part:
+
+   ```markdown
+   | Part | Source | Goes to | Status |
+   | --- | --- | --- | --- |
+   | Transport | `.cruze/notes/2026-10-12-seed.md`, "The protocol" | architect | open |
+   ```
+
+   A one-paragraph idea is all `vision`, so its hand-off is a row or two.
+5. **Take up the vision's parts now,** one section at a time. Each section is one question, keep or change, with the input's position as your recommendation. Set each row's status to `settled` or `dropped` as the user decides.
+
+## Taking up a hand-off later
+
+Architect, the roadmap and feature-scope envision take up their own rows. `cruze show --notes <step or feature slug>` lists them, and `cruze show <ref>` lists them for a feature or change. Read each part at its source, ask the user about it as in step 5, record what they keep where the step records decisions, and set the row's status. A row still `open` when the step ends goes to the user: keep it open for a later step, or drop it.

package/skills/envision/possibilities.md

@@ -0,0 +1,13 @@
+# Exploring what may come later
+
+The user knows where the product is heading better than any document does, but rarely says it unprompted. Ask, so designs leave room for it and never close it off.
+
+1. **Find the neighbours.** For each goal, user and capability in scope, name the capabilities that products in this domain commonly grow into, from what you know of the domain and its standards. Name them as the user would recognise them: single sign-on or multi-factor authentication next to sign-in, sync across devices next to local-only storage, teams and shared workspaces next to a single-user app, third-party plugins next to a fixed set of kinds, a second transport next to a local socket. Skip those the vision already records under `## Must stay possible` or `## Non-goals`.
+2. **Ask them as a round,** following `.agents/skills/cruze-grilling/SKILL.md`: whether the product may need each one, how likely, and why. Recommend an answer from what the user has said so far. Keep a round to 3 to 5, the likeliest first. "No" is a good answer too.
+3. **Record each answer:**
+   - **Likely or possible:** a `LATER-<name>` row under `## Must stay possible` in `docs/vision.md`, with the likelihood, why in the user's words, and what no design may close off. Say what must stay possible, never how to build it: the mechanism is decided when a feature builds it.
+   - **No, for a tempting neighbour of a goal:** a non-goal with the reason, so nobody proposes it again.
+   - **No, otherwise:** nothing.
+4. **Check the principles.** For each new `LATER` row, check every `PRINCIPLE` row against it. When one would stand in its way, such as "every record has exactly one owner" against shared workspaces, settle with the user which one gives, and amend the principle or the row.
+
+Done when every capability in scope has had its neighbours asked about once, and each answer is recorded. The vision changed, so the user approves it again with `cruze approve vision`.

package/skills/envision/project.md

@@ -3,18 +3,20 @@
 The result is an approved `docs/vision.md` and a `docs/glossary.md` holding the terms that settled. Formats: `.agents/skills/cruze-formats/reference/durable-docs.md`.
 
 1. **Create the documents.** Run `cruze new vision` and `cruze new glossary` for whichever doesn't exist yet. When the vision exists and you are reworking it, edit it in place. Bounded contexts don't exist yet, so group the glossary's terms under one `##` heading naming the product's domain, such as `## Console access`. `architect` regroups them by context.
-2. **Draft from the input.** Fill every section you can from what the user already gave you, and mark every guess as a question for step 3.
+2. **Take in the input** as [intake.md](intake.md) describes, then draft every section you can from the parts handed to `vision`, marking each as a question for step 3. Done when every part of the input has a hand-off row.
 3. **List the open decisions,** section by section:
    - **Problem:** the problem in the user's words, and who feels it.
    - **Users:** each kind of user and the situation they are in.
    - **Goals:** each goal as a `GOAL-<name>` row, with a measure that says how you would know it's met. A goal without a measure is still open.
    - **Non-goals:** what the product deliberately doesn't do, and why. Ask about the tempting neighbours of each goal.
    - **Constraints:** platforms, the implementation language, dependency policy, performance, security, privacy, licensing and legal limits.
+   - **Principles:** each rule every design must follow, as a `PRINCIPLE-<name>` row with why it holds. Ask about the rules behind the user's choices, such as what state and events are each for.
+   - **Must stay possible:** each capability the product may need after this release, as a `LATER-<name>` row, explored as [possibilities.md](possibilities.md) describes.
    - **Feature map:** the capabilities that deliver the goals, each a slug with a one-line summary and the goals it serves. They are what later `envision "<feature>"` runs pick up.
-4. **Grill in rounds** until every open decision is settled, following the grilling skill. As each domain term settles, add it to the glossary.
+4. **Grill in rounds** until every open decision is settled, following the grilling skill. As each domain term settles, add it to the glossary. Once the goals and feature map have settled, ask about what may come later, as [possibilities.md](possibilities.md) describes.
 5. **Write the vision.** Fill each section, and remove every template guide.
 6. **Fill the feature map.** For each capability, run `cruze features add <slug> --summary "<summary>" --goals <GOAL IDs>`. Put command syntax in backticks, such as `` `consolectl console <device>` ``, so it isn't read as a template guide. Running `add` again for the same slug replaces its entry in place. Done when every goal is served by at least one feature on the map.
-7. **Confirm.** Walk the user through the vision in one short summary: the problem, the goals with their measures, the non-goals, the constraints, and the feature map. Ask whether it matches their understanding, and apply any corrections.
+7. **Confirm.** Walk the user through the vision in one short summary: the problem, the goals with their measures, the non-goals, the constraints, the principles, what must stay possible, and the feature map. Name what the hand-off gives each later step, and anything dropped, and why. Ask whether it matches their understanding, and apply any corrections.
 8. **Approve.** When the user approves, run `cruze approve vision` and quote its result.
 9. **Introduce the project in the README.** Under the title of `README.md`, write one paragraph drawn from the vision's Problem, Users and Goals: what the product is, who it is for, and why it exists, ending with a link to `docs/vision.md`. Keep anything already there that is still true. Done when `cruze validate` reports no `readme-overview` warning.
 10. **Commit,** with a message such as `docs: envision the project`.

package/skills/explore/SKILL.md

@@ -10,7 +10,7 @@ Explore is the optional thinking partner that can come before any other Cruze st
 ## Steps
 
 1. **Frame the problem.** Ask what prompted the idea, who it affects, and what outcome would make it worthwhile. If the user starts from a solution, restate the problem underneath it and confirm it. Done when you can state the problem in one sentence the user agrees with.
-2. **Read what exists.** Read whichever of these exist: `docs/vision.md`, `docs/glossary.md`, `docs/architecture.md`, `docs/roadmap.md`, and the code the idea touches. Run `cruze status` to see work in flight. Use the glossary's words from here on, following `.agents/skills/cruze-domain-language/SKILL.md`.
+2. **Read what exists.** Read whichever of these exist: `docs/vision.md`, `docs/glossary.md`, `docs/architecture.md` as "Reading it" in `.agents/skills/cruze-formats/reference/architecture.md` says, `docs/roadmap.md`, and the code the idea touches. Run `cruze status` to see work in flight. Use the glossary's words from here on, following `.agents/skills/cruze-domain-language/SKILL.md`.
 3. **Separate facts from guesses.** List what is known evidence, what is a hypothesis, and what is a preference. Look up any fact you can rather than asking the user for it.
 4. **Diverge.** Lay out two to four genuinely different approaches, including leaving things as they are when that is credible. For each, give what it changes, what it leaves alone, its benefits, its costs and failure modes, the assumptions it rests on, and what evidence would tell it apart from the others. Show what each approach looks like, following `.agents/skills/cruze-grilling/illustrating.md`.
 5. **Converge.** Compare the strongest options against the user's outcome, the vision's goals and constraints, and the architecture. Challenge assumptions and accidental scope growth, following the challenge rules in `.agents/skills/cruze-grilling/SKILL.md`. Recommend one option only when its trade-offs are understood. Otherwise recommend the smallest step that would settle the question, such as a spike, a measurement or a research question.
@@ -20,7 +20,7 @@ Explore is the optional thinking partner that can come before any other Cruze st
 
 Only when the user says to capture:
 
-1. Run `cruze new note <slug> --title "<title>"` and write the note at the path it returns.
+1. Run `cruze new note <slug> --title "<title>" --kind explore --about <subjects>`, naming the feature slugs or contexts the idea concerns, or `project`, and write the note at the path it returns.
 2. Give the note these sections: `## Problem`, `## Options`, `## Recommendation` and `## Open questions`. Mark each statement as fact, hypothesis, preference or recommendation.
 3. Done when the note stands on its own for a reader who wasn't in the conversation.