@printpractical/cruze 0.0.6 → 0.0.8

package/dist/domain/validation/size_rules.js

@@ -12,17 +12,25 @@ export function changeLimits(view             )               {
   return view.config?.config?.changes ?? DEFAULT_CHANGE_LIMITS;
 }
 
+/** The rules a size warning comes from. An item stays outside the band only with the user's recorded acceptance. */
+export const SIZE_RULES = ["feature-size", "change-too-small", "change-too-large", "plan-too-large"];
+
+/** Whether the user accepted this feature or change outside the band, under `changes.exceptions`. */
+export function sizeAccepted(view             , ref        )          {
+  return changeLimits(view).exceptions.some((exception) => exception.item === ref);
+}
+
 /** A feature's changes not yet landed that fall outside the size band. A feature of one change has nothing to merge into. */
-export function changeRowSizeProblems(view             , path        , rows             , landed             )            {
+export function changeRowSizeProblems(view             , feature                               , rows             , landed             )            {
   const limits = changeLimits(view);
   const problems            = [];
-  for (const row of rows.filter((r) => !landed.has(r.change))) {
+  for (const row of rows.filter((r) => !landed.has(r.change) && !sizeAccepted(view, `${feature.ref}/${r.change}`))) {
     if (rows.length > 1 && row.builds.length < limits.minBuilds) {
-      problems.push(warning(path, row.line, "change-too-small", `${row.change} builds ${row.builds.length} element(s), under ${limits.minBuilds}; merge it into the change it continues, since each change pays for its own plan, review and verify`));
+      problems.push(warning(feature.path, row.line, "change-too-small", `${row.change} builds ${row.builds.length} element(s), under ${limits.minBuilds}; merge it into the change it continues, since each change pays for its own plan, review and verify`));
     }
     const scenarios = row.delivers.filter((id) => kindOf(id) === "SCN").length;
     if (scenarios > limits.maxScenarios) {
-      problems.push(warning(path, row.line, "change-too-large", `${row.change} delivers ${scenarios} scenarios, over ${limits.maxScenarios}; split it, since one verifier run has to go through them all`));
+      problems.push(warning(feature.path, row.line, "change-too-large", `${row.change} delivers ${scenarios} scenarios, over ${limits.maxScenarios}; split it, since one verifier run has to go through them all`));
     }
   }
   return problems;
@@ -31,6 +39,7 @@ export function changeRowSizeProblems(view             , path        , rows
 /** A plan with more tasks than one code review and one verify can hold. */
 export function planSizeProblems(view             , path        , tasks        )            {
   const { maxTasks } = changeLimits(view);
-  if (tasks <= maxTasks) return [];
+  const ref = view.items.find((item) => item.path === path)?.ref ?? path;
+  if (tasks <= maxTasks || sizeAccepted(view, ref)) return [];
   return [warning(path, undefined, "plan-too-large", `the plan has ${tasks} tasks, over ${maxTasks}; split the change through rethink at feature level`)];
 }

package/dist/domain/validation/work_item_rules.js

@@ -11,7 +11,7 @@ import { deltaProblems } from "./delta_rules.js";
 import { malformedIdHeadings, lineOf } from "./living_rules.js";
 import { changePlanProblems } from "./plan_rules.js";
 import { error, warning,              } from "./problem.js";
-import { changeRowSizeProblems } from "./size_rules.js";
+import { changeRowSizeProblems, sizeAccepted } from "./size_rules.js";
 
 const REQUIRED_SECTIONS                                     = {
   feature: ["Intent", "Spec delta", "Architecture delta", "Changes"],
@@ -45,6 +45,10 @@ function itemProblems(view             , item          )            {
   for (const cited of findIds(text).filter((cited) => !available.has(cited))) {
     problems.push(error(path, lineOf(text, cited), "unknown-id", `${cited} is cited but defined neither in the living docs nor in this work's deltas`));
   }
+  const dropped = droppedScenarios(view, delta);
+  for (const cited of findIds(text).filter((cited) => dropped.has(cited))) {
+    problems.push(error(path, lineOf(text, cited), "cites-dropped", `${cited} is cited, but ${dropped.get(cited)} in this work's delta leaves it out, so it won't exist once the work lands; describe it in words instead`));
+  }
   if (item.kind !== "change") problems.push(...deltaProblems(view, item));
   if (item.kind === "feature") problems.push(...featureScopeProblems(view, item, delta));
   // A landed change is history: its scope named what it built, which is now built.
@@ -69,10 +73,10 @@ function featureScopeProblems(view             , feature          , delta
   );
   const names = rows.map((row) => row.change);
   const extra = rows[MAX_CHANGES];
-  if (extra !== undefined) {
+  if (extra !== undefined && !sizeAccepted(view, feature.ref)) {
     problems.push(warning(feature.path, extra.line, "feature-size", `the feature has ${rows.length} changes, over ${MAX_CHANGES}; split it into features a single design review can hold`));
   }
-  problems.push(...changeRowSizeProblems(view, feature.path, rows, landedChanges));
+  problems.push(...changeRowSizeProblems(view, feature, rows, landedChanges));
   for (const row of rows) {
     if (!/^\d\d-[a-z0-9]+(?:-[a-z0-9]+)*$/.test(row.change)) problems.push(error(feature.path, row.line, "change-name", `change "${row.change}" must be named NN-slug`));
     if (names.indexOf(row.change) !== names.lastIndexOf(row.change)) problems.push(error(feature.path, row.line, "change-name", `change ${row.change} is listed twice`));
@@ -151,3 +155,21 @@ function scopeIds(item          )           {
   const scope = readScope(item.doc);
   return scope === null ? [] : [...scope.delivers, ...scope.builds, ...scope.removes];
 }
+
+/**
+ * Living scenarios that a MODIFIED requirement in the delta leaves out, each with that requirement.
+ * Land drops them, so a citation of one passes validation now and breaks only at land.
+ */
+function droppedScenarios(view             , delta       )                      {
+  const dropped = new Map                ();
+  for (const entry of delta.entries.filter((e) => e.element.op === "MODIFIED" && kindOf(e.element.id) === "REQ")) {
+    const living = view.living.elements.get(entry.element.id);
+    if (living === undefined) continue;
+    const kept = new Set(entry.scenarios.map((s) => s.id));
+    for (const scenario of view.living.elements.values()) {
+      const nested = scenario.doc === living.doc && scenario.element.start > living.element.start && scenario.element.start < living.element.end;
+      if (nested && kindOf(scenario.id) === "SCN" && !kept.has(scenario.id) && !delta.ids.has(scenario.id)) dropped.set(scenario.id, entry.element.id);
+    }
+  }
+  return dropped;
+}

package/dist/domain/versions/rule_versions.js

@@ -16,6 +16,7 @@ export const RULE_SINCE                         = {
   "validate:change-too-small": "0.0.5",
   "validate:change-too-large": "0.0.5",
   "validate:plan-too-large": "0.0.5",
+  "validate:module-path-glob": "0.0.8",
 };
 
 /** Whether a rule arrived after the version the project's code meets, so it waits for `realign`. */

package/dist/main.js

@@ -9,6 +9,12 @@ 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";
 
+// A reader that stops early, such as `cruze journal list | head`, closes the pipe; that is not an error worth a stack trace.
+process.stdout.on("error", (error                       ) => {
+  if (error.code === "EPIPE") process.exit(0);
+  throw error;
+});
+
 const cwd = process.cwd();
 const exitCode = await runCli(
   process.argv.slice(2),

package/package.json

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

@@ -41,3 +41,5 @@ Architect decides the how and the how big. It designs the domain, the ports and
 - Project scope: `plan` for the walking-skeleton change.
 - Feature scope: `plan` for the feature's first change.
 - Tweak scope: `plan` for the standalone change.
+
+Start it in a new session, so its context starts empty.

package/skills/architect/feature.md

@@ -33,6 +33,6 @@ The result is a `feature.md` with a complete architecture delta and an ordered l
 
     The thresholds are the defaults under `changes:` in `.cruze/config.yaml`; a project can tune them.
 
-    Done when `cruze validate` reports no `change-too-small`, `change-too-large` or `feature-size` warning, or the user has accepted one and a `D<n>` line under the feature's `## Decisions` records why. After approval, only a rethink can split a change.
+    Done when `cruze validate` reports no `change-too-small`, `change-too-large` or `feature-size` warning. When the user accepts one, record it twice: a `D<n>` line under the feature's `## Settled decisions` saying why, and the item under `changes.exceptions` in `.cruze/config.yaml` with the same reason, which is what stops the warning. `cruze approve` refuses an item with a warning still standing (`size-unaccepted`). After approval, only a rethink can split a change.
 
 Then continue with the review and walkthrough steps of the skill. When the user approves, run `cruze approve <feature>` and quote its result. The command takes the feature's full ID, such as `2026-09-25-open-console`, or its slug when no other active item shares it.

package/skills/architect/project.md

@@ -16,7 +16,7 @@ The result has four parts, reviewed together and shown at one walkthrough:
 5. **Ports (`PORT`).** Define every capability the use cases need from outside, named by capability. Write each operation's contract, following `.agents/skills/cruze-hexagonal-design/contracts.md`. Add driving ports only where the hexagonal-design skill calls for them.
 6. **Adapters (`ADP`).** Name the technology behind each driven port and each inbound adapter that drives use cases. Run the researcher role on every adapter's technology first, and record the result in the adapter's `Adopts` fact. Take every new dependency to the user.
 7. **Flows (`FLOW`).** Write a `sequenceDiagram` for each of the 2 to 5 most important interactions, including their failure paths. Leave out `Serves` until scenarios exist.
-8. **Modules (`MOD`).** Give each context its hexagonal modules, 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`.
+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`.

package/skills/architect/walkthrough.md

@@ -6,12 +6,15 @@ At feature scope, cover only what the feature adds, changes or removes. At proje
 
 ## The overview
 
-Write it in the glossary's terms, as what callers can do and what happens when they do, not as a list of elements. Keep it to what the user can read in a minute.
+Write it in the glossary's terms, as what callers can do and what happens when they do, not as a list of elements. Keep the prose to what the user can read in a minute, and open it with the line that says where things stand, from `.agents/skills/cruze-grilling/illustrating.md`.
 
 1. **What it does.** The intent in two sentences. Then one line per use case, or at feature scope per requirement: who asks for what, what they get, and the main way it fails.
 2. **What it touches.** Each new external system, and each new dependency named with its purpose and the approval behind it. Also each component you chose to build yourself, with the reason.
-3. **The slices.** The changes in order, one line each, saying what each delivers and why the first is first. At project scope, the roadmap's phases and the walking skeleton instead.
-4. **What is yours to decide.** The review findings the roles skill brings to the user, any `cruze validate` warning still standing, such as a change over its size limit, any point where a fresh implementer could still build something different, and any rule you challenged that the user overrode.
+3. **What it looks like.** Illustrated as `.agents/skills/cruze-grilling/illustrating.md` says:
+   - A plain-text diagram of the main scenario crossing the design: the inbound adapter, the use case, the domain elements and the ports, marking what is new.
+   - A code sketch, in the project's language, of what the new and changed elements look like: the port operations and use case signatures with their errors, the main entity, and the call an inbound adapter makes.
+4. **The slices.** The changes in order, one line each, saying what each delivers and why the first is first. At project scope, the roadmap's phases and the walking skeleton instead.
+5. **What is yours to decide.** The review findings the roles skill brings to the user, any `cruze validate` warning still standing, such as a change over its size limit, any point where a fresh implementer could still build something different, and any rule you challenged that the user overrode.
 
 ## The documents
 
@@ -20,7 +23,7 @@ List each file the user should read in full, with the sections that changed:
 - Feature scope: the feature's `feature.md`, and the ADRs it adds.
 - Project scope: `docs/architecture.md`, the `layers:` in `.cruze/config.yaml`, `docs/roadmap.md`, the walking-skeleton `change.md`, and the ADRs in `docs/adr/`.
 
-The diagrams are Mermaid inside those files. Say where the user can render them, such as an editor preview or GitHub, rather than pasting them.
+The documents' diagrams are Mermaid. Say where the user can render them, such as an editor preview or GitHub, rather than pasting them; the overview's plain-text sketches are for reading in the conversation.
 
 End the message with: "Read these in full, then tell me what to change, or approve. Do you approve this design?"
 

package/skills/build/SKILL.md

@@ -16,11 +16,11 @@ 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` and its feature's `feature.md`. Read the full body of every element the change builds, and every scenario it delivers. Read `commands:` in `.cruze/config.yaml`.
+3. **Read the plan and the design.** Read the change's `change.md`. Run `cruze show <ref>` and read its output: the full body of every element the change builds, every scenario it delivers, and the settled decisions. Read an element it lists as cited only when the task calls it, from the place it names, never `feature.md` or `docs/architecture.md` whole. Read `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`.
-   - Run `cruze check` and `cruze trace`, and quote their results.
+   - Run `cruze check --ci` and `cruze trace`, and quote their results.
    - When all of them pass, record the commit they ran at with `cruze journal add checks --set commit=<commit> --item <ref>`, where the commit is the output of `git rev-parse --short HEAD`. Verify quotes this instead of running the suite again.
    - Commit the progress record with a message such as `chore: record progress on <change>`.
    - Done when all of them pass and the checks are recorded.
@@ -30,26 +30,27 @@ Build turns an approved plan into code, one task at a time. Each task starts wit
 For task `T<n>`:
 
 1. **Read it.** Note its owner, its files, the IDs it proves, and the test plan rows for those IDs.
-2. **Red.** Write the tests for the IDs it proves, at the seams the test plan names, carrying the IDs. Run them, and see them fail for the reason you expect.
+2. **Red.** Write the tests for the IDs it proves, at the seams the test plan names, carrying the IDs. Run them, and see them fail for the reason you expect. When the task names a break, use it, or any break that compiles and turns the same assertion red.
 3. **Green.** Write the least code that makes them pass, in the task's files. Code that belongs to another task, or another change, waits for it, even when the next change will need it.
-4. **Check.** Run `cruze check <the task's files>`, the formatter and the linter, and fix what they report. Run the tests the task touched. When `commands:` has a `test_full`, run `test` too, since it is the fast tier. Otherwise run the rest of the suite only when it is quick.
+4. **Check.** Run `cruze check --ci <the task's files>`, the formatter and the linter, and fix what they report. Meet a budget as the budget rule in `.agents/skills/cruze-hexagonal-design/SKILL.md` says, never by bending the code. Run the tests the task touched. When `commands:` has a `test_full`, run `test` too, since it is the fast tier. Otherwise run the rest of the suite only when it is quick.
 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.
 
-Done for a task when its tests pass, `cruze check` passes for its files, the commit exists and the task is ticked.
+Done for a task when its tests pass, `cruze check --ci` passes for its files, the commit exists and the task is ticked.
 
 ## Deviations
 
 The plan is design. Within a task you decide only what is local and reversible.
 
-- **Record it and carry on** for a task-level choice: a private helper in another file of the same module, a private type, a fixture or harness added to the test support module that the task's tests need, or two tasks' commits swapped for a reason. The test support module is in every test-writing task's scope, so extend it rather than writing a private helper in a test file. Run `cruze task deviation T<n> "<what you did and why>"`.
+- **Record it and carry on** for a task-level choice: a private helper in another file of the same module, a new file of the owner's module that splits off a responsibility, a `check.exceptions` entry with its reason, a private type, a fixture or harness added to the test support module that the task's tests need, or two tasks' commits swapped for a reason. The test support module is in every test-writing task's scope, so extend it rather than writing a private helper in a test file. Run `cruze task deviation T<n> "<what you did and why>"`.
 - **Stop and offer `rethink`** when the code needs any of these:
   - a new element, port operation or scenario;
   - a file outside the owner's module, other than the test support module;
   - a change to an approved scenario's behaviour, or to its test;
-  - a dependency the design doesn't name.
+  - a dependency, or a feature of an approved dependency, that the design doesn't name. Ask for it as `.agents/skills/cruze-dependency-approval/SKILL.md` says, and never write around it with hand-written code or a shell command;
+  - 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.
 - Never edit `feature.md`, `docs/architecture.md` or `docs/specs/` during build. Design changes go through `rethink`.
@@ -60,4 +61,4 @@ Never weaken, skip or delete a behaviour, contract or smoke test for an approved
 
 ## Next step
 
-`verify`, once every task is ticked and the finishing checks pass.
+`verify`, once every task is ticked and the finishing checks pass. Start it in a new session, so its context starts empty: one session that ran plan, build, verify and land reached 745k tokens.

package/skills/dependency-approval/SKILL.md

@@ -9,12 +9,19 @@ Every new dependency needs the user's explicit approval before it is declared or
 
 ## Asking
 
-1. Establish the need: the capability, and why the standard library and the project's already-approved dependencies don't provide it.
+1. Establish the need: the capability, and what the design looks like with the dependency and without it, using the standard library and the project's already-approved dependencies. Show both as short code sketches, following `.agents/skills/cruze-grilling/illustrating.md`.
 2. Choose a recommendation, following `.agents/skills/cruze-research/SKILL.md`, which also says where versions come from.
 3. Say where it will sit: the module that owns it, and the port that keeps it out of the core when it is infrastructure.
 4. Name the realistic alternatives, including writing it yourself and what owning that code would cost. Never offer a hand-written alternative for cryptography, TLS or a security protocol.
 5. Ask, then wait. Nothing is declared, installed or written against it until the user answers.
 
+## Weighing
+
+- Recommend the option that gives the cleanest design: the one an experienced developer in the language would write, with the least code to own. A dependency, a new crate or package, or a feature of an approved dependency is not a cost in itself. Weigh its concrete costs: maintenance and release health, security record, licence, and build time or binary size where a stated constraint makes them matter.
+- "No new dependency" is never the reason for a choice. Name what the chosen option does better.
+- A structure the language requires for an idiom, such as a separate crate for a derive macro, is part of that idiom, not an extra cost.
+- When the clean design needs a dependency or feature nobody approved yet, ask for it. Hand-written code, a shell command or a less idiomatic construct that exists only to avoid asking is a design flaw.
+
 ```markdown
 **Dependency: `russh` for SSH hops**
 - Why not std or existing: the standard library has no SSH client, and no approved dependency provides one.

package/skills/envision/SKILL.md

@@ -27,3 +27,5 @@ Envision decides the what: the problem, who has it, and the behaviour that solve
 
 - After project scope: run `architect` at project scope.
 - After feature scope: run `architect "<feature>"`.
+
+Start it in a new session, so its context starts empty.

package/skills/envision/feature.md

@@ -18,6 +18,6 @@ The result is a feature folder whose `feature.md` holds the intent, the settled
    - 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.
 8. **Leave the design to architect.** Set `## Architecture delta` to `None.` and leave the Changes table with its header row only. Remove the remaining template guides.
-9. **Confirm.** Summarize the intent and each requirement with its scenarios, in plain words, and ask the user to confirm them. Apply any corrections.
+9. **Confirm.** Summarize the intent and each requirement with its scenarios, in plain words, showing each requirement's main scenario as the user would see it, and ask the user to confirm them. Apply any corrections.
 
 Done when the user has confirmed, `cruze validate` reports no errors for the feature, only its `not-designed` warning, and the feature is committed.

package/skills/explore/SKILL.md

@@ -12,7 +12,7 @@ Explore is the optional thinking partner that can come before any other Cruze st
 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`.
 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. Sketch an interaction as a Mermaid `sequenceDiagram` or `flowchart` when that makes a difference clearer.
+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.
 6. **Offer to capture.** Summarize the problem, the options, the trade-offs, your recommendation and the open questions, then ask whether to capture them. When the user declines, stop here: the discussion itself was the result.
 

package/skills/formats/reference/architecture.md

@@ -35,7 +35,7 @@ Facts are `- Key: value` items. Keys marked required must be present; the others
 | `PORT` | `Direction` (`driven` or `driving`), `Operations`, `Module`, `File` | `Implemented by`, `Future` |
 | `ADP` | `Implements` (a driven port) or `Drives` (use cases), `Technology`, `Module`, `File` | `Adopts` (library and adopt-or-build reason), `Format` (the stored or wire format it owns, or where its schema lives) |
 | `FLOW` | `Elements`, a Mermaid `sequenceDiagram` | `Serves` (SCN IDs, once they exist), `Failure paths` |
-| `MOD` | `Path`, `Layer` (`domain`, `application`, `adapter` or `composition`) | |
+| `MOD` | `Path` (a directory ending in `/`, or one file; list several in backticks, never a glob), `Layer` (`core`, `domain`, `application`, `adapter` or `composition`) | |
 | `RULE` | one or two sentences of rule | `Enforced by` (config layer names) |
 | `XC` | prose | |
 

package/skills/formats/reference/config.md

@@ -33,6 +33,9 @@ changes:
   min_builds: 3
   max_scenarios: 30
   max_tasks: 25
+  exceptions:
+    - item: 2026-09-25-open-console/02-ssh-hops
+      reason: every scenario runs through one reconcile, which can't be split without building it twice
 
 layers:
   - name: inventory-domain
@@ -52,7 +55,7 @@ layers:
 | `tracker` | Where work items live. `markdown` is the only value in V1. |
 | `source` | Globs of the source files `cruze check` inspects. |
 | `tests` | Globs of the files `cruze trace` searches for scenario IDs. |
-| `check.max_lines` | Line budget per source file. Test files outside `source` have no budget. |
+| `check.max_lines` | Line budget per source file. Test files outside `source` have no budget, and a Rust file's `#[cfg(test)]` modules don't count. |
 | `check.max_types` | Budget of top-level types per source file. |
 | `check.exceptions` | Files allowed past a budget, or Rust test files allowed under `src/` (`test-placement`), each with a `path` and a `reason`. `realign` adds entries whose reason ends `scheduled in <ref>`, and landing that change removes them. |
 | `layers` | Each layer has a `name`, the `paths` it covers, and `may_import`, the layers it may depend on. |
@@ -62,6 +65,7 @@ layers:
 | `changes.min_builds` | A feature's change that builds fewer elements than this gets a `change-too-small` warning: merge it into the change it continues. Default `3`. |
 | `changes.max_scenarios` | A change that delivers more scenarios than this gets a `change-too-large` warning: split it. Default `30`. |
 | `changes.max_tasks` | A plan with more tasks than this gets a `plan-too-large` warning. Default `25`. |
+| `changes.exceptions` | Features and changes the user accepted outside the band, each with the `item` (a feature's ID, `<feature>/<change>`, or a standalone change's ID) and the `reason`. The item's size warning stops. `cruze approve` refuses an item whose size warning still stands (`size-unaccepted`) until it is listed here or split. |
 
 Rules for layers:
 

package/skills/formats/reference/specs.md

@@ -60,6 +60,6 @@ The full new requirement text.
 
 - `ADDED CAPABILITY` creates a new spec file, with its title and purpose paragraph. It is only needed for a capability that has no file yet.
 - `ADDED` introduces a new requirement with all its scenarios.
-- `MODIFIED` replaces a requirement's whole block, including every scenario it keeps. A scenario left out is removed.
+- `MODIFIED` replaces a requirement's whole block, including every scenario it keeps. A scenario left out is removed, so no part of the work may cite it by ID (`cites-dropped`); describe it in words.
 - `REMOVED` retires a requirement and its scenarios, and needs a `Reason` and a `Migration`.
 - `land` shifts heading levels to fit the spec file and keeps the managed status of scenarios that were already built.

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

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

package/skills/formats/templates/architecture.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-<One paragraph: what the system is, how it is used, and the architectural style.>
+<One paragraph: what the system is and what kind (a library, a daemon or service, a mobile or desktop app, a CLI, or several deliverables), how it is used, and the architectural style.>
 
 ### VIEW-context: System context
 
@@ -81,7 +81,7 @@ sequenceDiagram
 
 ### MOD-<context>.<name>: <Module title>
 - Path: `<directory or file>`
-- Layer: <domain | application | adapter | composition>
+- Layer: <core | domain | application | adapter | composition>
 
 ## Dependency rules
 

package/skills/grilling/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cruze-grilling
-description: How to interview the user until design decisions are settled. Questions go in rounds over a tree of decisions, facts are looked up rather than asked, each question carries a recommendation, and challenges the user overrides are recorded. Use when a design step needs decisions from the user, when shaping an idea, vision, feature, architecture or plan with them, when the user steers toward something that breaks a rule, or when the user asks to be grilled or to stress-test a plan.
+description: How to interview the user until design decisions are settled. Questions go in rounds over a tree of decisions, facts are looked up rather than asked, each question carries a recommendation and shows what each option looks like, and challenges the user overrides are recorded. Use when a design step needs decisions from the user, when shaping an idea, vision, feature, architecture or plan with them, when the user steers toward something that breaks a rule, or when the user asks to be grilled or to stress-test a plan, and when showing the user review findings or a design to decide on.
 ---
 
 # Grilling
@@ -12,25 +12,37 @@ Interview the user until you both understand the design the same way. Decisions
 1. List the open decisions this step must settle, as a tree in which each decision hangs off the ones it depends on. Take them from the sections of the document the step writes and from what the user has already said. Done when every section the step writes has its decisions listed.
 2. Settle the facts yourself. Anything the repository, the living docs, a `cruze` command or a primary source can answer is a fact, so look it up rather than asking. Where the agent can run a helper in parallel, send it to look while you ask about everything that doesn't depend on the answer.
 3. Find the frontier: every open decision whose prerequisites are settled. A question that depends on another open question waits for a later round.
-4. Ask the frontier as one round, in the format below. Every question carries your recommended answer and the reason for it.
+4. Ask the frontier as one round, in the format below. Every question shows what each option looks like and carries your recommended answer and the reason for it. Read [illustrating.md](illustrating.md) before the first round.
 5. Wait for the answers. Record each settled decision as described under Recording, then recompute the frontier.
 6. Repeat until the frontier is empty: every branch visited, and nothing silently assumed.
-7. Write the sections the step produces from the settled decisions, then summarize them and ask the user to confirm that they match their understanding. Done when the user confirms. Decisions and glossary terms are recorded as they settle, and nothing is approved before the confirmation.
+7. Write the sections the step produces from the settled decisions, then summarize them, illustrated as [illustrating.md](illustrating.md) says, and ask the user to confirm that they match their understanding. Done when the user confirms. Decisions and glossary terms are recorded as they settle, and nothing is approved before the confirmation.
 
 ## A round
 
-```markdown
+````markdown
+Where we are: architect for 2026-09-25-open-console, round 2. Settled: D1 (a console session may cross jump hosts), D2 (credentials come from the vault).
+
 **Q4. Where the jump-host list lives**
 Per device in the device config, or as named hosts that devices reference. Named hosts avoid repeating a host's address and credentials across devices, but add a second lookup.
+
+```yaml
+# A: per device                    # B: named hosts (recommended)
+devices:                           jump_hosts:
+  core-sw-01:                        lab-gw: { address: 10.0.0.5 }
+    jump: { address: 10.0.0.5 }    devices:
+  core-sw-02:                        core-sw-01: { jump: lab-gw }
+    jump: { address: 10.0.0.5 }      core-sw-02: { jump: lab-gw }
+```
+
 Recommended: named hosts, because the lab config already shares two jump hosts across 30 devices.
 
 **Q5. What a refused second hop reports**
 ...
-```
+````
 
 - Number questions across the whole session, not per round, so an answer such as "Q7: yes" is never ambiguous.
-- Keep a round to what the user can answer in one reply, about 3 to 7 questions. When the frontier is bigger, ask first the questions that others depend on.
-- Ask about behaviour and trade-offs in the user's terms and the glossary's words, not about implementation mechanics.
+- Keep a round to what the user can answer in one reply, about 3 to 5 questions. When the frontier is bigger, ask first the questions that others depend on.
+- Ask about behaviour and trade-offs in the user's terms and the glossary's words, not about implementation mechanics. Where the trade-off is in the code's shape, show the shape.
 - When the user answers "you decide" or "I don't know", take your recommendation and record it with "(recommended; the user deferred)".
 - When an answer contradicts an earlier decision, point to that decision and ask which one stands.
 

package/skills/grilling/illustrating.md

@@ -0,0 +1,37 @@
+# Illustrating a question
+
+The user decides from what they can picture. A question about a port's errors or a module's place is hard to answer from words alone, and the user is often coming back from other work. So every question, review exception and confirmation shows what each option looks like, and reads on its own without the conversation before it.
+
+## Reading cold
+
+- Open each round, and each message of review exceptions, with one line saying where things stand: the work item, the step, and the earlier decisions this round builds on, such as `Where we are: architect for 2026-10-08-subscriptions, round 3. Settled: D2 (one stream per session), D4 (events carry revisions).`
+- Say what an ID means in plain words the first time a message uses it, such as `SCN-configuration.reject-taken-priority (a second set asking for a priority already taken is refused)`.
+- Each question says what it decides and why it matters now, without pointing back to an earlier message.
+
+## Choosing the illustration
+
+Show each option, side by side, with the form that fits what the question decides:
+
+| The question decides | Show |
+| --- | --- |
+| What a user does or sees | The command they type and its exact output, or a plain-text sketch of the screen, using the scenario's concrete values |
+| A port, a use case's input and errors, or a public API | A code sketch in the project's language: the types and signatures, and the call a caller writes |
+| Where something lives: contexts, modules, dependency direction | A box-and-arrow diagram, or the directory tree with the files the option adds |
+| An order of steps, or what happens on failure | A numbered sequence or a plain-text sequence diagram, with the failure branch |
+| States and what moves between them | The states with their transitions, one per line |
+| A stored format or a config file | A sample of the file |
+| A dependency | The code with it and the code without it |
+
+Leave out the illustration only when the question is about a name, a number or the wording of a sentence, where it would repeat the words.
+
+## Writing it
+
+- Use the design's names and the glossary's words, and the values of a real scenario, so the user sees this project's code, not a generic example.
+- A code sketch shows shape: types, signatures, the error variants, and one call site. Leave bodies out, writing `...` or the language's placeholder. Keep each option to about 15 lines.
+- Draw diagrams in plain text, so they read in a terminal, where Mermaid shows only as source. The documents keep their Mermaid diagrams; the illustration is for the conversation.
+- At envision, show behaviour only: interactions and screens, never code, since envision keeps implementation out.
+- Mark your recommended option in the illustration itself, and show the failure case when the options differ in how they fail.
+
+## After the answer
+
+A shape the user chose from a sketch is part of the decision. Write it into the document in that document's format: the port's `Operations`, the entity's facts, the module's `Path`, or the scenario's values. Build follows the documents, so the code comes out as the user saw it.

package/skills/hexagonal-design/SKILL.md

@@ -37,6 +37,7 @@ When two rules pull apart, the earlier one wins. Prefer the simplest design that
 
 | Layer | Owns | May depend on |
 | --- | --- | --- |
+| `core` | A context's concepts, use cases and ports together (`ENT`, `UC`, `PORT`), when its domain needs no boundary of its own | The standard library, and approved libraries with no infrastructure in them |
 | `domain` | Concepts, state, rules, invariants and domain errors (`ENT`) | Domain code, the standard library, and approved libraries with no infrastructure in them, such as an error-derive crate |
 | `application` | Use cases (`UC`) and the ports they define (`PORT`) | The domain |
 | `adapter` | Inbound adapters that drive use cases, and outbound adapters that implement driven ports (`ADP`) | Application, domain and third-party libraries |
@@ -44,6 +45,10 @@ When two rules pull apart, the earlier one wins. Prefer the simplest design that
 
 `cruze check` enforces imports between the project's own layers. It allows every third-party import, so review checks that infrastructure libraries appear only in adapters.
 
+Use the fewest layers that keep the rules. A context starts with `core`, its adapters and the composition root. The boundary that matters most is between the core and infrastructure, because it is what lets tests fake the outside world. Split a context's core into `domain` and `application` when its domain has rules and invariants that several use cases share and a workflow could break, and record the split as a `D<n>` decision. A `core` module follows the domain and the application rules below together.
+
+Layers are roles, not folders. Choose the layout that is normal for the kind of system and its language, following [shapes.md](shapes.md), and give each module the layer of what it holds.
+
 Layers are dependency boundaries, not runtime hops. A port can be a plain function call. Add a task, thread, channel or process only for a concrete ownership, concurrency, isolation or backpressure need, and read [runtime.md](runtime.md) first.
 
 ### Domain
@@ -83,13 +88,14 @@ Layers are dependency boundaries, not runtime hops. A port can be a plain functi
 
 ## Many small modules
 
-- Give each responsibility its own module, grouped by domain concept, with the hexagonal roles inside. A file may hold a few closely related types.
+- Give each responsibility its own module, grouped by domain concept, with the hexagonal roles inside. A context's core is usually one module, with each port beside the use cases that define it, and grows submodules by concept, not by layer. A file may hold a few closely related types.
 - When a file passes its budget (`check:` in `.cruze/config.yaml`, enforced by `cruze check`) or gains a second responsibility, split it into a submodule named for what it owns.
+- A budget is a prompt to look for a second responsibility, never a shape to write code to. Write the code as you would with no budget: no type alias, string where an error type belongs, merged types or function moved away from its owner to stay under a limit. When a file over budget holds one responsibility, such as the related types of one grammar, list it under `check.exceptions` with that reason.
 - Entry-point and namespace files, such as `main`, `lib.rs`, `mod.rs` and `index.ts`, hold only wiring and declarations.
 - Don't create generic modules such as `utils`, `helpers`, `common`, `services`, `models`, `types` or `manager`. Shared behaviour belongs with the concept that owns it.
 - Duplication is semantic. Two implementations of one rule are duplication even when the text differs, so consolidate them in the owner, not in a helper.
-- Structure follows the module map, never a per-language template. Write idiomatic code for the language and use its standard tooling. [languages/rust.md](languages/rust.md) and [languages/cpp.md](languages/cpp.md) add rules for those languages.
-- In an existing codebase, its established layout and naming win over these structure rules. Ownership and dependency direction still apply.
+- Structure follows the module map, never a per-language template. Write idiomatic code for the language and use its standard tooling. [languages/rust.md](languages/rust.md), [languages/swift.md](languages/swift.md) and [languages/cpp.md](languages/cpp.md) add rules for those languages.
+- In an existing codebase, its established layout and naming win over these structure rules until the user restructures it with the improve skill. Ownership and dependency direction still apply.
 
 ## Representations and errors
 
@@ -119,6 +125,7 @@ These are review signals, not automatic failures. When one could be checked mech
 
 ## Further reading
 
+- [shapes.md](shapes.md): choosing the layout for a library, a daemon or service, a mobile or desktop app, or a CLI.
 - [contracts.md](contracts.md): writing a port's `Operations`, a public API, an IPC protocol or a stored format.
 - [runtime.md](runtime.md): concurrency, long-lived resources (connections, sessions, devices, subprocesses), state machines, cancellation or a hot path.
 - [fundamentals.md](fundamentals.md): choosing a data structure, a state representation or an abstraction mechanism; defining equality or ordering; bounding loops, retries and fan-out.

package/skills/hexagonal-design/languages/rust.md

@@ -6,7 +6,7 @@ These add to the hexagonal design rules for Rust projects. The module map decide
 
 - `main.rs` is the composition root and stays thin. `lib.rs` and every `mod.rs` hold only module declarations, visibility and deliberate re-exports, and `lib.rs` exposes the use cases, ports and domain types that tests drive.
 - Name modules for the concept they own. Don't put domain definitions in a `mod.rs`, and don't create `domain.rs`, `services.rs`, `models.rs` or `utils.rs` catch-alls.
-- Where the layer rules need a hard boundary, a Cargo workspace with one crate per layer makes the compiler enforce it. The walking-skeleton change decides this.
+- Split crates by deliverable, such as the library, a client, a daemon and a CLI, in a Cargo workspace when there is more than one. Inside a crate, modules carry the concepts and the layers, and `cruze check` enforces the layer rules between them. A crate per layer is unusual in Rust and puts a public API between the layers: use one only when the user wants the compiler to enforce a boundary, and record it as a decision.
 
 ## Modelling
 
@@ -40,6 +40,7 @@ These add to the hexagonal design rules for Rust projects. The module map decide
 - No `unsafe` unless the user approves it or an unavoidable low-level boundary needs it, with a `// SAFETY:` comment giving the reason.
 - Format with `cargo fmt`, lint with `cargo clippy -- -D warnings`, and test with `cargo test`.
 - Behaviour, contract and smoke tests live in the crate's `tests/` directory and reach the code through the library's public API. Domain tests sit in a `#[cfg(test)] mod tests` beside the code and need no fakes.
-- When a module's inline tests would take its file past the budget, move them to the crate's `tests/`, named for the module: `tests/<module>.rs`, or `tests/<module>/main.rs` declaring one file per topic, such as `tests/generation/add_generation.rs`. Cargo builds each `tests/*.rs` and each `tests/*/main.rs` as a test binary, and nothing deeper. Never move them to `src/<module>/tests.rs` or `src/<module>/tests/`: `cruze check` reports those as `test-placement`. A test that needs a private item is testing structure, so drive the public API instead. When a private seam really is the contract, such as a filesystem trait a crash test injects, list the file under `check.exceptions` with that reason.
+- `cruze check` leaves a file's `#[cfg(test)]` modules out of its budgets, so domain tests stay inline however long they grow. Never move them to `src/<module>/tests.rs` or `src/<module>/tests/`: `cruze check` reports those as `test-placement`.
+- Name test files in `tests/` for what they cover: `tests/<module>.rs`, or `tests/<module>/main.rs` declaring one file per topic, such as `tests/generation/add_generation.rs`. Cargo builds each `tests/*.rs` and each `tests/*/main.rs` as a test binary, and nothing deeper.
 - Group integration tests into a few binaries by area, `tests/<area>/main.rs` with one module per topic, since every binary links the crate again.
 - Share fakes, fixtures and harnesses within a crate through `tests/support/mod.rs`, which each test binary declares with `mod support;`. In a workspace, put what several crates' tests share in one dev-only crate, such as `<project>-test-support`, listed under `[dev-dependencies]`. Never share them with `#[path]` includes.

package/skills/hexagonal-design/languages/swift.md

@@ -0,0 +1,46 @@
+# Swift
+
+These add to the hexagonal design rules for Swift projects, such as iOS and macOS apps and Swift packages. The module map decides the layout; this file never does.
+
+## Packages and targets
+
+- Every target is a Swift module, and anything another target uses must be `public`. Each target boundary costs access-control boilerplate and build time, so use few:
+  - one core target for the app's contexts, with a folder per feature or concept;
+  - adapter targets only where a framework or package must stay out of the core, or one adapters target for all of them;
+  - the app target, holding the screens, their models and the composition root, or a feature target per feature once the app is large enough to build and preview features alone;
+  - one test-support target with the fakes and fixtures every test target shares.
+- Keep `internal`, the default, for everything used inside its target. Use `package` for what the package's own targets share, and `public` only for what the app target or another package needs.
+- A target can import only the targets and packages it declares in `Package.swift`, so declared dependencies enforce those boundaries. They don't stop a target importing a platform framework, such as `CoreLocation` or `SwiftUI`, which any target can import. Review checks framework imports against the layer rules, or a short CI script lists them per target.
+- Keep the core free of UIKit, SwiftUI and other platform frameworks. Its tests then build and run without the app, and with a macOS platform in `Package.swift`, without a simulator.
+
+## Modelling
+
+- Use structs for values and entities, enums for closed alternatives and states, and classes only where identity needs reference semantics. Wrap primitives with meaning, such as `struct OfficeName { let value: String }`, with a failable or throwing initializer that enforces the invariant.
+- Use concrete types for single-strategy behaviour. Use protocols for ports and for strategies that really vary.
+
+## Ports and injection
+
+- Ports are protocols owned by the core, named for the capability. Platform types, such as `CLLocation` or `UNNotificationRequest`, never appear in their signatures.
+- Inject through initializers. The composition root at the app's entry point builds the adapters and the use cases, and hands each screen's model what it calls.
+
+## Screens
+
+- A SwiftUI view and its `@Observable` model are the screen's inbound adapter. The model calls use cases and maps their results to what the view shows. Domain rules stay out of both.
+- Test the model with fakes behind its use cases' ports. Keep UI tests for what only the running screen can show.
+
+## Errors and logging
+
+- Throw a typed error, `throws(OfficeChangeError)`, where callers handle its cases differently, and use plain `throws` elsewhere. Never `try!` or `fatalError` for a condition that can happen in production. Tests may use them.
+- Log with `os.Logger` in adapters, use cases and screen models. The domain doesn't log.
+
+## Concurrency
+
+- Use the Swift 6 language mode. Domain values are `Sendable` structs and enums. A use case is a struct, or an actor when it owns mutable state that several callers reach.
+- `@MainActor` belongs on views and their models, not on the core.
+- Don't mark a type `@unchecked Sendable` without a comment giving the reason.
+
+## Tooling and tests
+
+- Format with `swift format format --in-place --recursive`, and lint with `swift format lint --strict --recursive`.
+- Package tests live in `Tests/<Target>Tests/`. They import the target with `@testable import`, which makes its `internal` declarations visible, so nothing is made `public` only for tests. UI tests live in the app's UI test target.
+- Put the package's tests in the `test` command and the app's UI tests in `test_full`, as `.agents/skills/cruze-formats/reference/config.md` describes, since UI tests run through the simulator and are by far the slowest.