@printpractical/cruze 0.0.12 → 0.0.14

package/dist/domain/project/layout.js

@@ -1,4 +1,4 @@
-/** Where Cruze documents live in a project, and the snapshot of them the domain works on. */
+/** Where Cruze documents live in a project. */
 
 /** Project files by path, relative to the project root, with forward slashes. */
                                                    
@@ -6,36 +6,20 @@
 export const PATHS = {
   readme: "README.md",
   vision: "docs/vision.md",
-  glossary: "docs/glossary.md",
   architecture: "docs/architecture.md",
-  roadmap: "docs/roadmap.md",
-  adrDir: "docs/adr",
-  specsDir: "docs/specs",
+  featuresDir: "docs/features",
   config: ".cruze/config.yaml",
-  featuresDir: ".cruze/features",
-  changesDir: ".cruze/changes",
-  archiveDir: ".cruze/archive",
-  notesDir: ".cruze/notes",
-  projectApprovals: ".cruze/approvals.json",
-  projectJournal: ".cruze/journal.jsonl",
+  approvals: ".cruze/approvals.json",
 }         ;
 
-/** Directories whose files make up the snapshot. */
-export const SNAPSHOT_ROOTS = ["docs", ".cruze"]         ;
-
-export function specPath(capability        )         {
-  return `${PATHS.specsDir}/${capability}.md`;
-}
-
-export function filesUnder(snapshot          , dir        )           {
-  const prefix = `${dir}/`;
-  return [...snapshot.keys()].filter((path) => path.startsWith(prefix)).sort();
+export function featurePath(slug        )         {
+  return `${PATHS.featuresDir}/${slug}.md`;
 }
 
-/** Paths directly matching `<dir>/<name><suffix>`, one level deep. */
-export function childFiles(snapshot          , dir        , suffix        )           {
-  return filesUnder(snapshot, dir).filter((path) => {
-    const rest = path.slice(dir.length + 1);
-    return !rest.includes("/") && rest.endsWith(suffix);
-  });
+/** The feature slug of a path directly under docs/features/, or undefined. */
+export function slugOfFeaturePath(path        )                     {
+  const prefix = `${PATHS.featuresDir}/`;
+  if (!path.startsWith(prefix) || !path.endsWith(".md")) return undefined;
+  const rest = path.slice(prefix.length, -3);
+  return rest.includes("/") ? undefined : rest;
 }

package/dist/domain/project/project_docs.js

@@ -0,0 +1,48 @@
+import { parseApprovals,                     } from "../approvals.js";
+import { parseConfig,                   } from "../config.js";
+import { parseMarkdown,                  } from "../markdown.js";
+import { readFeature,              } from "./features.js";
+import { PATHS, slugOfFeaturePath,               } from "./layout.js";
+import { readRelease,                     } from "./release.js";
+
+/** Every Cruze document of a project, parsed: what the use cases work on. */
+                              
+                     
+                                   
+                                  
+                                        
+                            
+                                                   
+                      
+                              
+ 
+
+export function buildProjectDocs(snapshot          )              {
+  const read = (path        )                          => {
+    const text = snapshot.get(path);
+    return text === undefined ? undefined : parseMarkdown(text);
+  };
+  const configText = snapshot.get(PATHS.config);
+  const vision = read(PATHS.vision);
+  const features = [...snapshot.keys()]
+    .flatMap((path) => {
+      const slug = slugOfFeaturePath(path);
+      return slug === undefined ? [] : [readFeature(slug, snapshot.get(path) ?? "")];
+    })
+    .sort((a, b) => a.slug.localeCompare(b.slug));
+  return {
+    snapshot,
+    config: configText === undefined ? undefined : parseConfig(configText),
+    vision,
+    architecture: read(PATHS.architecture),
+    release: vision === undefined ? [] : readRelease(vision),
+    features,
+    approvals: parseApprovals(snapshot.get(PATHS.approvals)),
+  };
+}
+
+/** The document a reference names: `vision`, `architecture`, a feature slug, or a path. */
+export function resolveDocument(docs             , ref        )                     {
+  const path = ref === "vision" ? PATHS.vision : ref === "architecture" ? PATHS.architecture : (docs.features.find((f) => f.slug === ref)?.path ?? ref);
+  return docs.snapshot.has(path) ? path : undefined;
+}

package/dist/domain/project/release.js

@@ -0,0 +1,30 @@
+import { findSection,                  } from "../markdown.js";
+import { tablesIn } from "../markdown_tables.js";
+
+/** One row of the vision's `## Release` table: a feature of the release, in build order, and the features it needs. */
+                                 
+               
+                  
+                  
+                                 
+               
+ 
+
+/** The release's features, from the first table under `## Release` with Feature and Needs columns. */
+export function readRelease(vision             )                   {
+  const section = findSection(vision, "Release");
+  if (section === null) return [];
+  const table = tablesIn(vision.lines, vision.inFence, section.start, section.end).find((t) => t.header.includes("Feature") && t.header.includes("Needs"));
+  if (table === undefined) return [];
+  const at = (name        )         => table.header.indexOf(name);
+  return table.rows.map(({ cells, line }) => ({
+    slug: unquote(cells[at("Feature")] ?? ""),
+    summary: at("Summary") === -1 ? "" : (cells[at("Summary")] ?? ""),
+    needs: (cells[at("Needs")] ?? "").split(",").map(unquote).filter((need) => need !== "" && !/^[-—–]+$/.test(need)),
+    line,
+  }));
+}
+
+function unquote(cell        )         {
+  return cell.trim().replace(/^`(.*)`$/, "$1").trim();
+}

package/dist/domain/scaffold.js

@@ -13,7 +13,6 @@ export const INIT_SCAFFOLD                           = [
   { path: "AGENTS.md", template: "init/AGENTS.md" },
   { path: ".cruze/config.yaml", template: "init/config.yaml" },
   { path: ".github/workflows/ci.yml", template: "init/ci.yml" },
-  { path: ".gitattributes", template: "init/gitattributes" },
 ];
 
 /**

package/dist/domain/skill_budget.js

@@ -7,11 +7,11 @@
 export const MAX_FILE_WORDS = 2100;
 
 /**
- * The words agents may read across the whole bundle. Every retro adds rules, and between 0.0.1 and
- * 0.0.10 the skills grew by half while nothing was removed. Lower this when text is cut. Raising it
- * is the maintainer's decision, with the reason in the commit that raises it.
+ * The words agents may read across the whole bundle. By 0.0.13 the skills had grown to 45,800 words
+ * as every fix added rules and nothing was removed; 0.0.14 cut them to this. Lower it when text is
+ * cut. Raising it is the maintainer's decision, with the reason in the commit that raises it.
  */
-export const BUNDLE_WORD_BUDGET = 45450;
+export const BUNDLE_WORD_BUDGET = 17605;
 
 /** Data the CLI reads or renders, rather than instructions an agent reads. */
 const NOT_INSTRUCTIONS = /(^|\/)(templates|notes)\//;

package/dist/domain/trace.js

@@ -1,44 +1,27 @@
-import { headingElements, statusOf } from "./elements.js";
-import { findIds } from "./ids.js";
-import { PATHS } from "./project/layout.js";
-                                                             
-import { readScope } from "./project/plan_parts.js";
-import { readDelta } from "./project/deltas.js";
-                                                        
+import { findScenarioIds } from "./ids.js";
+                                                     
 
                               
                                                                                  
                                                     
                     
-                                                                          
+                                                                
                                                              
  
 
-/**
- * Links scenarios to the tests that prove them. For a change: every scenario it delivers.
- * For the whole project: every built scenario in the living specs.
- */
-export function traceScenarios(view             , tests                             , change           )              {
-  const required = change === undefined ? builtScenarios(view) : (readScope(change.doc)?.delivers ?? []).filter((id) => id.startsWith("SCN-"));
-  const known = new Set([...view.living.elements.keys()]);
-  for (const item of view.items.filter((i) => !i.archived)) for (const id of readDelta(item.doc).ids) known.add(id);
-
+/** Links the required features' scenarios to the tests that carry their IDs. */
+export function traceScenarios(features                    , required                    , tests                             )              {
+  const known = new Set(features.flatMap((f) => f.scenarios.map((s) => s.id)));
   const carriers = new Map                  ();
   const unknown                         = [];
   for (const [path, text] of tests) {
     text.split("\n").forEach((line, index) => {
-      for (const id of findIds(line).filter((id) => id.startsWith("SCN-"))) {
+      for (const id of findScenarioIds(line)) {
         carriers.set(id, [...new Set([...(carriers.get(id) ?? []), path])]);
         if (!known.has(id)) unknown.push({ id, path, line: index + 1 });
       }
     });
   }
-  const scenarios = required.map((id) => ({ id, tests: carriers.get(id) ?? [] }));
+  const scenarios = required.flatMap((f) => f.scenarios).map((s) => ({ id: s.id, tests: carriers.get(s.id) ?? [] }));
   return { scenarios, missing: scenarios.filter((s) => s.tests.length === 0).map((s) => s.id), unknown };
 }
-
-function builtScenarios(view             )           {
-  return [...view.living.docs]
-    .filter(([path]) => path.startsWith(`${PATHS.specsDir}/`))
-    .flatMap(([, doc]) => headingElements(doc).filter((e) => e.kind === "SCN" && statusOf(doc, e) === "built").map((e) => e.id));
-}

package/dist/domain/validation/document_rules.js

@@ -0,0 +1,70 @@
+import { featureOfScenario } from "../ids.js";
+import { findSection,                  } from "../markdown.js";
+import { FEATURE_SECTIONS, FEATURE_STATUSES, statusLine, strayScenarioIds,              } from "../project/features.js";
+import { PATHS } from "../project/layout.js";
+                                                              
+import { error, warning,              } from "./problem.js";
+
+/** Each document's required sections, its size, its scenarios, and leftover template guides. */
+
+const VISION_SECTIONS = ["Problem", "Users", "Release"];
+const ARCHITECTURE_SECTIONS = ["Overview", "Ports", "Adapters", "Runtime"];
+
+/** Words past which a document stops being something a person reads in one sitting. */
+export const WORD_LIMITS = { vision: 1500, architecture: 3000, feature: 2500 }         ;
+
+const GUIDE = /(?<!`)<(?!!--|\/|https?:|br\b)[A-Za-z][^<>\n]*>(?!`)/;
+const PLACEHOLDER = /\{\{[a-z_]+\}\}/;
+
+export function documentProblems(docs             )            {
+  const problems            = [];
+  if (docs.vision !== undefined) problems.push(...shapeOf(PATHS.vision, docs.vision, VISION_SECTIONS, WORD_LIMITS.vision));
+  if (docs.architecture !== undefined) problems.push(...shapeOf(PATHS.architecture, docs.architecture, ARCHITECTURE_SECTIONS, WORD_LIMITS.architecture));
+  for (const feature of docs.features) {
+    problems.push(...shapeOf(feature.path, feature.doc, [...FEATURE_SECTIONS], WORD_LIMITS.feature), ...featureProblems(feature));
+  }
+  problems.push(...duplicateScenarios(docs.features));
+  return problems;
+}
+
+function shapeOf(path        , doc             , sections          , limit        )            {
+  const problems            = sections.filter((title) => findSection(doc, title) === null).map((title) => error(path, undefined, "missing-section", `needs a ## ${title} section`));
+  const words = doc.lines.filter((_, i) => !doc.inFence[i]).join(" ").split(/\s+/).filter((w) => w !== "").length;
+  if (words > limit) problems.push(warning(path, undefined, "too-long", `${words} words, over the ${limit} a person reads in one sitting; cut what the agent decided and the user needn't read, or split it`));
+  doc.lines.forEach((line, i) => {
+    if (doc.inFence[i]) return;
+    const withoutCode = line.replace(/`[^`]*`/g, "");
+    if (GUIDE.test(withoutCode) || PLACEHOLDER.test(withoutCode)) problems.push(error(path, i, "template-leftover", "replace the template guide or placeholder on this line"));
+  });
+  return problems;
+}
+
+function featureProblems(feature         )            {
+  const problems            = [];
+  const status = statusLine(feature.doc);
+  if (status === undefined) problems.push(error(feature.path, undefined, "status", `needs a "- Status: shaped" line under the title`));
+  else if (feature.status === undefined) problems.push(error(feature.path, status.line, "status", `the status is one of ${FEATURE_STATUSES.join(" or ")}`));
+  if (feature.scenarios.length === 0 && findSection(feature.doc, "Behaviour") !== null) {
+    problems.push(error(feature.path, undefined, "no-scenarios", `## Behaviour needs at least one ### SCN-${feature.slug}.<name>: <title> scenario`));
+  }
+  for (const scenario of feature.scenarios) {
+    if (featureOfScenario(scenario.id) !== feature.slug) problems.push(error(feature.path, scenario.line, "scenario-id", `${scenario.id} belongs to this feature, so it starts SCN-${feature.slug}.`));
+  }
+  for (const stray of strayScenarioIds(feature)) {
+    problems.push(error(feature.path, stray.line, "scenario-heading", `a scenario heading reads exactly "${stray.id}: <title>"`));
+  }
+  return problems;
+}
+
+function duplicateScenarios(features           )            {
+  const seen = new Map                ();
+  const problems            = [];
+  for (const feature of features) {
+    for (const scenario of feature.scenarios) {
+      const first = seen.get(scenario.id);
+      if (first !== undefined) problems.push(error(feature.path, scenario.line, "duplicate-scenario", `${scenario.id} is already defined in ${first}`));
+      else seen.set(scenario.id, feature.path);
+    }
+  }
+  return problems;
+}

package/dist/domain/validation/release_rules.js

@@ -0,0 +1,45 @@
+import { isSlug } from "../ids.js";
+import { PATHS } from "../project/layout.js";
+                                                              
+import { error, warning,              } from "./problem.js";
+
+/** The vision's Release table: feature slugs, what each needs, and no cycles. */
+export function releaseProblems(docs             )            {
+  if (docs.vision === undefined) return [];
+  if (docs.release.length === 0) return [warning(PATHS.vision, undefined, "release", "## Release has no Feature | Summary | Needs table with features in it yet")];
+  const problems            = [];
+  const slugs = new Set        ();
+  for (const row of docs.release) {
+    if (!isSlug(row.slug)) problems.push(error(PATHS.vision, row.line, "release", `"${row.slug}" must be a feature slug: lowercase words joined by single hyphens`));
+    if (slugs.has(row.slug)) problems.push(error(PATHS.vision, row.line, "release", `${row.slug} is listed twice`));
+    slugs.add(row.slug);
+  }
+  for (const row of docs.release) {
+    for (const need of row.needs.filter((n) => !slugs.has(n))) {
+      problems.push(error(PATHS.vision, row.line, "release-needs", `${row.slug} needs ${need}, which isn't a feature of this release`));
+    }
+  }
+  const cycle = findCycle(docs.release.map((r) => [r.slug, r.needs.filter((n) => slugs.has(n))]         ));
+  if (cycle !== undefined) problems.push(error(PATHS.vision, docs.release.find((r) => r.slug === cycle[0])?.line, "release-needs", `features need each other in a circle: ${cycle.join(" → ")}`));
+  return problems;
+}
+
+function findCycle(graph                                                     )                       {
+  const edges = new Map(graph);
+  const done = new Set        ();
+  const visit = (node        , path          )                       => {
+    if (path.includes(node)) return [...path.slice(path.indexOf(node)), node];
+    if (done.has(node)) return undefined;
+    for (const next of edges.get(node) ?? []) {
+      const found = visit(next, [...path, node]);
+      if (found !== undefined) return found;
+    }
+    done.add(node);
+    return undefined;
+  };
+  for (const [node] of graph) {
+    const found = visit(node, []);
+    if (found !== undefined) return found;
+  }
+  return undefined;
+}

package/dist/domain/validation/validate_project.js

@@ -1,36 +1,29 @@
+import { PATHS } from "../project/layout.js";
                                                               
-import { futureProblems } from "./future_rules.js";
-import { livingProblems } from "./living_rules.js";
+import { documentProblems } from "./document_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";
+import { releaseProblems } from "./release_rules.js";
 
 /** Every rule in the cruze-formats skill, applied to the whole project. */
-export function validateProject(view             )            {
-  const approvalProblems = [...view.approvalProblems].map(([path, message]) => error(path, undefined, "approvals-file", message));
-  const journalProblems = [...view.journalProblems].flatMap(([path, lines]) =>
-    lines.map((line) => error(path, line - 1, "journal-line", "this journal line is not a valid entry")),
-  );
-  return sortProblems([
-    ...configProblems(view),
-    ...livingProblems(view),
-    ...visionProblems(view),
-    ...futureProblems(view),
-    ...roadmapProblems(view),
-    ...workItemProblems(view),
-    ...templateLeftovers(view),
-    ...readmeProblems(view),
-    ...approvalProblems,
-    ...journalProblems,
-  ]);
-}
-
-/** Problems that concern one document. */
-export function problemsFor(problems           , path        )            {
-  return problems.filter((problem) => problem.path === path);
+export function validateProject(docs             )            {
+  const config = docs.config === undefined
+    ? [error(PATHS.config, undefined, "config", "the project has no config; run cruze init")]
+    : docs.config.problems.map((message) => error(PATHS.config, undefined, "config", message));
+  const approvals = approvalsFileProblems(docs.snapshot.get(PATHS.approvals));
+  return sortProblems([...config, ...approvals, ...documentProblems(docs), ...releaseProblems(docs)]);
 }
 
 export function hasErrors(problems           )          {
   return problems.some((problem) => problem.severity === "error");
 }
+
+function approvalsFileProblems(text                    )            {
+  if (text === undefined) return [];
+  try {
+    const parsed          = JSON.parse(text);
+    if (!Array.isArray((parsed                           ).approvals)) return [error(PATHS.approvals, undefined, "approvals-file", "needs an approvals list; only cruze approve writes this file")];
+    return [];
+  } catch {
+    return [error(PATHS.approvals, undefined, "approvals-file", "not valid JSON; only cruze approve writes this file")];
+  }
+}

package/dist/domain/versions/cruze_version.js

@@ -36,15 +36,9 @@ export function versionSkew(cli        , recorded                    )
  * after `version:`, so the file's comments and layout survive.
  */
 export function withRecordedVersion(configText        , version        )         {
-  return withVersionLine(configText, "cruze", version);
-}
-
-/** The config text with a top-level version key, such as `cruze:` or `standards:`, set in place. */
-export function withVersionLine(configText        , key                       , version        )         {
-  const line = `${key}: ${JSON.stringify(version)}`;
-  const existing = new RegExp(`^${key}:.*$`, "m");
-  if (existing.test(configText)) return configText.replace(existing, line);
-  const anchor = key === "standards" ? /^cruze:.*$/m.exec(configText) ?? /^version:.*$/m.exec(configText) : /^version:.*$/m.exec(configText);
+  const line = `cruze: ${JSON.stringify(version)}`;
+  if (/^cruze:.*$/m.test(configText)) return configText.replace(/^cruze:.*$/m, line);
+  const anchor = /^version:.*$/m.exec(configText);
   if (anchor === null) return `${line}\n${configText}`;
   const end = anchor.index + anchor[0].length;
   return `${configText.slice(0, end)}\n${line}${configText.slice(end)}`;

package/dist/main.js

@@ -10,7 +10,7 @@ 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.
+// A reader that stops early, such as `cruze status --text | 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@printpractical/cruze",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "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/asking/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: cruze-asking
+description: When to ask the user and when to decide, and how to show a question so the user can answer it cold, with plain words, code sketches and diagrams. Use before asking the user anything during envision, shape, build, review or fix.
+---
+
+# Asking the user
+
+The user's time is the scarcest thing in the project. Every question costs them a context switch, and a long run of questions turns into rubber-stamping: in one project the user answered 71% of 187 design questions with a bare "agree". So ask little, ask what only the user can answer, and show it so it can be answered at a glance.
+
+## What to ask and what to decide
+
+Ask when a choice changes something the user will see or live with:
+
+- behaviour a user of the product will notice, including what they see when something fails;
+- a public API: anything another program, person or team calls, types, or reads;
+- scope: what is in a feature and what is out;
+- a significant dependency, through `.agents/skills/cruze-dependency-approval/SKILL.md`;
+- security, privacy, stored data, compatibility, or a commitment that is costly to reverse.
+
+Decide everything else yourself: internal structure, private names, which module owns what, internal types, file layout, equivalent idioms, limits and timeouts with an obvious value. Pick the conventional option. Uncertainty alone doesn't make a choice the user's: investigate first. Then list the decisions a user might question in the document's `## Decisions`, one line each with the reason, so the user sees them when they approve, without being asked.
+
+## How many
+
+At most one question round per step, of five questions or fewer, before you show the document. When a choice has a sensible default, take it and list it under Decisions instead of asking. When the user defers ("you decide"), decide, and don't ask again.
+
+## Showing a question
+
+The user knows what the product should do, not the design's internals, and is often coming back from other work.
+
+- **Say where things stand** in one line first: the step and the feature, such as "Shaping export-csv."
+- **Explain the part before asking about it:** what it is, what it does, and why the question comes up now.
+- **Use plain words.** Name a scenario or decision by what it says, and add its ID after it in parentheses only when the user may want to look it up. Never let an ID stand alone.
+- **Show each option** with the form that fits:
+
+| The question decides | Show |
+| --- | --- |
+| What a user does or sees | The command and its exact output, or a sketch of the screen, with real values |
+| A public API or a port | A code sketch in the project's language: types, signatures, errors, and one call |
+| Where something lives | A box-and-arrow diagram, or the directory tree |
+| An order of steps, or what happens on failure | A numbered sequence with the failure branch |
+| A stored format or config | A sample of the file |
+| A dependency | The code with it and without it |
+
+- **Keep sketches short:** shape only, bodies left out, about 15 lines per option. Draw diagrams in plain text, which reads in a terminal; documents keep their Mermaid.
+- **Mark your recommendation** and why, in one line.
+
+A shape the user chose from a sketch is part of the decision: write it into the document, so build makes it as the user saw it.
+
+## Challenge, then defer
+
+When the user steers toward something that breaks the architecture or a standard, name the rule, the concrete risk here and your alternative, once. Then the user decides, and their decision stands.

package/skills/behavioural-testing/SKILL.md

@@ -1,30 +1,28 @@
 ---
 name: cruze-behavioural-testing
-description: The testing standard for a Cruze project, covering which tests to write, the seam each one drives, the ID it carries, and fakes instead of mocks. Use when writing a change's test plan, when writing, changing or fixing a test, when building a fake for a port, when deciding whether a unit test is warranted, or when reviewing tests.
+description: The testing standard for a Cruze project, covering which tests to write, the seam each one drives, the ID it carries, and fakes instead of mocks. Use when writing, changing or fixing a test, when building a fake for a port, when deciding whether a unit test is warranted, or when reviewing tests.
 ---
 
 # Behavioural testing
 
-Behaviour is the contract. Every scenario in the specs becomes a test that drives the system through a use case and checks what a caller would see. Tests pin behaviour, not structure, so the code behind them can be rewritten freely.
+Behaviour is the contract. Every scenario in a feature becomes a test that drives the system through a use case and checks what a caller would see. Tests pin behaviour, not structure, so the code behind them can be rewritten freely.
 
-## Writing tests for a task
+## Writing tests for a feature
 
-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.
+1. For each scenario, pick its seam from the table below. Done when you know the seam, test file and kind of every test the feature needs.
+2. Write one test at its seam, carrying the scenario's 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. 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.
+5. Done when every scenario has a passing test carrying its ID, every port with a real adapter has contract tests, and each test fails when the behaviour it checks is removed.
 
 ## The four kinds
 
-These match the test plan in `.agents/skills/cruze-formats/reference/work-items.md`.
-
 | Kind | Subject | Seam | When |
 | --- | --- | --- | --- |
-| `behaviour` | `SCN` | The use case's API with a fake for each driven port, or the inbound adapter when the outcome is what that adapter shows, such as CLI output, an exit code or an HTTP status | One or more per scenario, always |
-| `contract` | `PORT` | The same cases run against the fake and every real adapter | Every driven port that has a real adapter |
-| `domain` | `ENT` | The entity's own API | Only for real logic: state machines, calculations, invariants with edge cases |
-| `smoke` | `FLOW` | The real inbound adapter, wired by the real composition root | The top 1 to 3 flows |
+| `behaviour` | a scenario | The use case's API with a fake for each driven port, or the inbound adapter when the outcome is what that adapter shows, such as CLI output, an exit code or an HTTP status | One or more per scenario, always |
+| `contract` | a port | The same cases run against the fake and every real adapter | Every driven port that has a real adapter |
+| `domain` | a domain type | The entity's own API | Only for real logic: state machines, calculations, invariants with edge cases |
+| `smoke` | the main path | The real inbound adapter, wired by the real composition root | The top 1 to 3 paths through the system |
 
 A behaviour test drives a use case, not a single domain type, so it keeps passing when rules move between entities. In a library with no use cases, the seam is the library's public API. Write a domain test only when a rule's edge cases are too many to reach through use cases one by one.
 
@@ -51,9 +49,9 @@ A behaviour test drives a use case, not a single domain type, so it keeps passin
 
 ## Protecting the check
 
-- Behaviour, contract and smoke tests for approved scenarios, ports and flows are the safety net. Never edit one to get green. When one fails, either the code is wrong, or the spec is. A wrong spec or design goes through the rethink step, and the test changes only with the delta that changes its subject: a spec delta for a `SCN`, an architecture delta for a `PORT` or `FLOW`.
+- Behaviour, contract and smoke tests for approved scenarios and ports are the safety net. Never edit one to get green. When one fails, either the code is wrong, or the scenario is. A wrong scenario goes back through shape, and the test changes only after the user approves the changed scenario.
 - Domain tests are disposable. Rewrite or delete them along with the code they test.
-- Never skip a test, delete one, or weaken an assertion to finish a task. Verify flags any diff to a safety-net test that has no matching delta.
+- Never skip a test, delete one, or weaken an assertion to finish. Review flags any weakened safety-net test.
 
 ## What not to write
 
@@ -65,6 +63,6 @@ Side-by-side examples are in [examples.md](examples.md).
 
 ## Naming and tracing
 
-- Every test carries its subject ID where `.agents/skills/cruze-formats/reference/work-items.md` says, such as `// SCN-access.direct-serial` on the line above it.
+- Every behaviour test carries its scenario's ID in a comment or string, such as `// SCN-open-serial.attach` on the line above it. A test name alone doesn't count, since `cruze trace` looks for the literal ID.
 - A scenario may need several tests, and each of them carries its ID. One test covers one scenario.
-- `cruze trace` checks scenarios only: it fails when a scenario the change delivers has no test carrying its ID, or when a test cites a scenario nobody defined. Run it before calling a change's tests complete, and quote its result. For the `contract`, `domain` and `smoke` rows, list each subject ID next to the test that carries it.
+- `cruze trace <slug>` fails when one of the feature's scenarios has no test carrying its ID, or when a test cites a scenario no feature defines. Run it before calling a feature's tests complete, and quote its result.

package/skills/behavioural-testing/examples.md

@@ -7,7 +7,7 @@ The examples are in Rust, from a console-access tool. The shape is the same in a
 Good. It drives the use case, fakes the ports, and checks what the caller sees:
 
 ```rust
-// SCN-access.second-hop-refused
+// SCN-ssh-hops.second-hop-refused
 #[test]
 fn second_hop_refused_closes_the_first_hop() {
     let catalog = InMemoryDeviceCatalog::with(device("lab-router", ssh_via("jump-1")));
@@ -89,7 +89,6 @@ The file format is the TOML adapter's business. Its contract tests cover it, and
 Good. A state machine with real rules, tested through the entity's own API:
 
 ```rust
-// ENT-access.console-session
 #[test]
 fn a_closed_session_cannot_reopen() {
     let mut session = ConsoleSession::opening();

package/skills/behavioural-testing/fakes.md

@@ -4,7 +4,7 @@ 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`, 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.
+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. 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)`. 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.
@@ -21,7 +21,7 @@ A contract test states the port's contract once and runs it against every implem
 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.
 
-When the contract changes, the port's `Operations` change first through a delta, then the contract suite, then the fake and the adapters.
+When the contract changes, the port's operations in `docs/architecture.md` change first, then the contract suite, then the fake and the adapters.
 
 ## What a fake is not