@dialecte/core 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@dialecte/core",
-	"version": "0.9.0",
+	"version": "0.10.0",
 	"description": "Dialecte - Core functionality for Dialecte SDK",
 	"license": "MIT",
 	"repository": {
@@ -52,9 +52,11 @@
 		"doc:preview": "vitepress preview",
 		"//====== TEST ======//": "",
 		"test": "npm run test:node && npm run test:browser",
-		"test:node": "vitest run --project node --project node-indexeddb --project node-sqlite",
+		"test:node": "vitest run --project node --project node-indexeddb --project node-sqlite --project node-indexeddb-documents",
+		"test:scope": "tsx scripts/test-scope/run-test-scope.ts",
 		"test:browser": "vitest run --project browser",
 		"test:browser:all": "vitest run --project browser-all",
+		"test:browser:release": "STORE_CONTRACT_FULL_TABLE=1 vitest run --project browser-all",
 		"test:perf": "VITE_BENCH=1 vitest run --project perf --mode bench --reporter=verbose",
 		"test:perf:node": "VITE_BENCH=1 vitest run --project perf-node --mode bench --reporter=verbose",
 		"test:hook": "dialecte gate --hook",
@@ -86,7 +88,7 @@
 		"sax": "^1.4.3"
 	},
 	"devDependencies": {
-		"@dialecte/cli": "0.3.1",
+		"@dialecte/cli": "0.4.0",
 		"@tsconfig/node24": "^24.0.4",
 		"@types/node": "^24.12.4",
 		"@typescript/native": "npm:typescript@^7.0.2",
@@ -158,8 +160,42 @@
 				},
 				{
 					"name": "browser tests",
-					"run": "npx vitest run --project browser",
+					"run": "npm run test:scope",
+					"counts": "tests",
+					"scoped": true
+				}
+			],
+			"release": [
+				{
+					"name": "check",
+					"run": "npm run check"
+				},
+				{
+					"name": "skills",
+					"run": "npm run skills:check"
+				},
+				{
+					"name": "build",
+					"run": "npm run build"
+				},
+				{
+					"name": "tests",
+					"run": "npm run test:node",
 					"counts": "tests"
+				},
+				{
+					"name": "browser tests",
+					"run": "npm run test:browser:release",
+					"counts": "tests",
+					"heavy": true
+				},
+				{
+					"name": "type narrowing",
+					"run": "npm run type-narrowing"
+				},
+				{
+					"name": "type bench",
+					"run": "npm run type-bench:check"
 				}
 			]
 		}

package/skills/dialecte/SKILL.md

@@ -21,7 +21,7 @@ uuid/name fix-up that a hook already performs on every write. This skill exists
 
 ```
 your app            custom extensions, services, UI           (yours)
-dialecte package    @dialecte/<id>, @acme/widget              (domain)
+a dialecte package  @dialecte/<id>, @acme/widget              (domain)
   ├ definition/*.generated.ts   generated from the XSD - never edited by hand
   ├ config/                     wires the definition into core, `namespace <Name>` types
   ├ hooks/                      automatic coherence on every write and on import
@@ -237,8 +237,9 @@ doc.query.myFeature.findOrphanParts({ assembly })   // first param is bound away
   (no service, store, composable, component, policy file) and carries none of your product's rules.
   Where your product decides differently from the plain behaviour, see policies below.
 - **Tests on the node tier**: table-driven with the package's runner (`<package>/<version>/test` →
-  `run<Name>TestCases`), inline XML fixtures, the function called directly with `source.query` / `tx`,
-  not through the bound method. No test names a store: the runner runs them in Node on the in-memory
+  `run<Name>TestCases`), whole-document XML fixtures, one call of the unit per test (the function
+  with `source.query` / `tx`, or its bound method; never both), see references/testing.md. No test
+  names a store: the runner runs them in Node on the in-memory
   store. See [Testing](#testing).
 
 ### Policies: your product's choices, passed per call
@@ -289,9 +290,10 @@ composable then imports them with `import type`): do not wrap a type only to re-
 Each dialecte package exports table-driven runners from its `/test` entry
 (`<package>/<version>/test` → `run<Name>TestCases`; core's own: `@dialecte/core/test`). Details
 and the case format: [references/testing.md](references/testing.md). Short version: one table per
-behaviour, inline XML fixtures with `dev:db-id` ids that say intent, `.withExport` asserts the
-resulting XML with XPath, `.withoutExport` asserts inside `act`, `.generic` for pure functions.
-Red first, one case at a time. No test names its store: the runner chooses it (in Node on the
+behaviour, whole-document XML fixtures (inline up to 40 lines, else a sibling `?raw` file) with
+`dev:db-id` ids that say intent, one call of the unit per `act`, `.withExport` asserts the resulting
+XML with hand-written XPath, `.withoutExport` asserts inside `act`, `.generic` for pure functions.
+Refusals assert the error key and nothing staged, never a spy. Red first, one case at a time. No test names its store: the runner chooses it (in Node on the
 in-memory store under a node vitest project whose setup file calls `useTestStorage`, core 0.8+).
 Assertions take XML text; on a big file, check record expectations (tag, attributes, parent,
 count) with the query API instead of XPath on the whole export.

package/skills/dialecte/references/api.json

@@ -681,12 +681,12 @@
 			"entry": "@dialecte/core/test",
 			"otherRoutes": [],
 			"signature": "(params: XmlQueriesWithNamespacesParams) => void",
-			"summary": "Asserts that each XPath query selects at least one node of the XML text, parsed once for all of them. A failure names the steps that matched, the step that failed, where the last match sits, what the failing step finds there without its predicates, and the XML around it.",
+			"summary": "Asserts that each XPath query selects at least one node of the XML text, parsed once for all of them. A failure names the steps that matched, the step that failed, where the last match sits, what the failing step finds there without its predicates, and the XML around it. A query that selects nothing throws an `XmlAssertionError`.",
 			"intents": [
 				"assert that XML holds the elements XPath queries select",
 				"check that an export holds an element"
 			],
-			"declaredAt": "src/test/assert-xml/assert-xml.ts:47"
+			"declaredAt": "src/test/assert-xml/assert-xml.ts:49"
 		},
 		{
 			"path": "@dialecte/core/test.assertUnexpectedElementQueries",
@@ -694,12 +694,12 @@
 			"entry": "@dialecte/core/test",
 			"otherRoutes": [],
 			"signature": "(params: XmlQueriesWithNamespacesParams) => void",
-			"summary": "Asserts that no XPath query selects a node of the XML text, parsed once for all of them.",
+			"summary": "Asserts that no XPath query selects a node of the XML text, parsed once for all of them. A query that selects a node throws an `XmlAssertionError`.",
 			"intents": [
 				"assert that XML does not hold an element",
 				"check that an element was removed from an export"
 			],
-			"declaredAt": "src/test/assert-xml/assert-xml.ts:61"
+			"declaredAt": "src/test/assert-xml/assert-xml.ts:64"
 		},
 		{
 			"path": "@dialecte/core/test.createMockRandomUUID",
@@ -775,7 +775,7 @@
 				"make XPath assertions bound to a dialecte's namespaces",
 				"assert exported XML in tests"
 			],
-			"declaredAt": "src/test/assert-xml/assert-xml.ts:26"
+			"declaredAt": "src/test/assert-xml/assert-xml.ts:27"
 		},
 		{
 			"path": "@dialecte/core/test.createXmlSchemaAssertions",

package/skills/dialecte/references/api.md

@@ -481,8 +481,8 @@ ruled out and why in your hand-over.
 
 | Function                         | What it answers                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Reach for it to                                                                                                                                                                                                                               |
 | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `assertExpectedElementQueries`   | Asserts that each XPath query selects at least one node of the XML text, parsed once for all of them. A failure names the steps that matched, the step that failed, where the last match sits, what the failing step finds there without its predicates, and the XML around it.                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | assert that XML holds the elements XPath queries select; check that an export holds an element                                                                                                                                                |
-| `assertUnexpectedElementQueries` | Asserts that no XPath query selects a node of the XML text, parsed once for all of them.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | assert that XML does not hold an element; check that an element was removed from an export                                                                                                                                                    |
+| `assertExpectedElementQueries`   | Asserts that each XPath query selects at least one node of the XML text, parsed once for all of them. A failure names the steps that matched, the step that failed, where the last match sits, what the failing step finds there without its predicates, and the XML around it. A query that selects nothing throws an `XmlAssertionError`.                                                                                                                                                                                                                                                                                                                                                                                                               | assert that XML holds the elements XPath queries select; check that an export holds an element                                                                                                                                                |
+| `assertUnexpectedElementQueries` | Asserts that no XPath query selects a node of the XML text, parsed once for all of them. A query that selects a node throws an `XmlAssertionError`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | assert that XML does not hold an element; check that an element was removed from an export                                                                                                                                                    |
 | `createMockRandomUUID`           | The `crypto.randomUUID` a test case's act runs with: UUID-shaped ids that follow from a seed (0 by default), the same sequence on every run.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | get deterministic uuids in a test; mock crypto.randomUUID                                                                                                                                                                                     |
 | `createTestHelpers`              | Every test helper a dialecte needs, derived from its declaration: the runner, the test project, the record factory, the XPath assertions and the schema assertions. A fixture is checked against the schema of the config it is imported under, then by the dialecte's extra checks, before a case or a test project uses it.                                                                                                                                                                                                                                                                                                                                                                                                                             | get every test helper of a dialecte; set up a dialecte package's tests; check fixtures against the schema                                                                                                                                     |
 | `createTestProject`              | Spin up a Project of the declared dialecte - every config, the default key, its extensions and its own hooks instance; core's own test dialecte when none is given - with the source (and optionally the target) imported under the default config. Returns project + pre-opened documents. Opened inside a running test, the project is destroyed when the test ends (after its other `onTestFinished` hooks); opened outside one (`beforeAll`), the caller destroys it. Spin up a Project from a config, extensions and hooks given one by one, with the source (and optionally the target) imported under the key `default`.                                                                                                                           | open a project in a test with a fixture imported; get documents to test against                                                                                                                                                               |

package/skills/dialecte/references/testing.md

@@ -58,24 +58,180 @@ A dialecte package's runner has the same shape with its own types (`<Name>Test.T
 
 ## Rules
 
+A test is read far more often than it is written: by the reviewer, by the next person who changes the code,
+by whoever reads a failure. Every rule below keeps one case readable on its own and keeps each behaviour proven
+in exactly one place.
+
+### The table
+
 - **Red first, one case at a time.** Add one case with `only: true`, run it, see it fail for the
   right reason (an assertion, not a missing module - stub the function with the right type first),
-  write the minimum code, then the next case. Remove every `only` at the end. A table written after
-  the implementation only pins what the code happens to do.
-- **Case keys** read `<initial state> → <outcome>`.
-- **Fixtures are inline XML** in the test file. `dev:db-id` (`CUSTOM_RECORD_ID_ATTRIBUTE`) gives
-  records stable ids; choose ids that say intent (`orphaned-ref`, `a-without-child`). Comment the
-  elements that are deliberately absent. No `<?xml ?>` declaration in template literals.
-- **Expectations are structural XPath with meaningful predicates.** `//default:AA_1` alone proves
-  nothing; a case can pass because ANOTHER element matched. Do not assert on `dev:db-id` in XPath.
-  Pair `unexpectedQueries` with the commented-out source when asserting a deletion.
+  then the next case. Remove every `only` before the red is recorded (`dialecte tdd red` refuses a
+  focused file), then write the minimum code. Record per case where it failed (`<case title>: failed on
+  <assertion>`); a case that never failed is listed with its reason (existing behaviour the change
+  touches). A table written after the implementation only pins what the code happens to do.
+- **One table per behaviour.** `.withExport` with `expectedQueries` when the outcome is XML;
+  `.withoutExport` only for a returned value or warnings; a refusal's table runs `.withExport` (see
+  Refusals below). A case field that picks which assertions run (`check: 'children' | 'references'`,
+  `if (testCase.setup === 'x')`) means two behaviours share a table: split it. A flag marking the
+  refusal cases of a table is fine.
+
+  ```ts
+  // BAD: one table, the case picks what the act checks
+  if (testCase.check === 'children') expect(children).toHaveLength(1)
+  else expect(references).toEqual([])
+
+  // GOOD: one table per behaviour, the same act for every case of a table
+  runTestCases.withExport({ testCases: addsChildCases, act: addsChildAct })
+  runTestCases.withExport({ testCases: keepsReferencesCases, act: keepsReferencesAct })
+  ```
+
+- **Case keys** read `<initial state> → <outcome>`. No plan, round, station or ticket tags in titles
+  or file names (`round 2`, `step 3`, an issue number).
+- **Only the behaviour the change touches.** No preservation cases for code the change leaves alone.
+  Each case is written once, for the Node tier; no browser copy of a case. The package's whole-suite
+  runs on other tiers or stores are its gate, not duplicates.
+- **Readable size.** Aim for 200-300 lines per test file, one verb or behaviour per file. A file
+  growing past that holds two behaviours: split it by behaviour, not by line count.
+
+### One call of the unit
+
+A verb's test proves that verb's behaviour, nothing else. The `act` makes **one call of the unit under
+test** - the function itself (`fn(tx, params)`, `fn(source.query, params)`) or its bound method
+`tx.<ns>.<verb>`; either is one call, never both in one test - then returns or asserts the outcome.
+
+- No second or third call, no retry, no loop over the call.
+- No capture before the call: no snapshot of the staged operations, no copy of the document's metadata,
+  to compare after. The outcome is what the call left: `expectedQueries`, a returned value, a staged
+  list compared with a literal. "Unchanged" is a case of its own only where it is the behaviour.
+- No XPath on the source inside the `act`, no branch on the case.
+- Not in a verb's test: the transaction's rollback, source-document purity, id or date formats, timestamps,
+  provenance details. Their owners test them (core's transaction, the writer of the timestamp, schema
+  validation, one acceptance case for source purity); a verb re-proving them breaks when the owner
+  changes, not when the verb does.
+- A **reshape** keeps every behaviour covered **by the test that owns it**. List each check it removes
+  with the test that covers it, and open that test: it must really assert it, or the reshape adds the case
+  there first.
+
+```ts
+// BAD: a state captured before the call, compared after it
+const before = structuredClone(await source.query.getDocumentInfo())
+await source.transaction(async (tx) => addFirstChild(tx, testCase.params))
+expect(await source.query.getDocumentInfo()).not.toEqual(before)
+
+// GOOD: one call; the case's expectedQueries carry the outcome
+async function act({
+	testCase,
+	source,
+}: ActParams<TestDialecteConfig, TestCase>): Promise<ActResult> {
+	await source.transaction(async (tx) => addFirstChild(tx, testCase.params))
+	return { assertOn: 'source' }
+}
+```
+
+### Refusals assert outcomes, never spies
+
+A refusal is proven by what it leaves: the error key, nothing staged, the documents unchanged.
+
+- Catch the refusal inside its transaction, assert its key, then `tx.getStagedOperations()` equal to
+  `[]`, still inside that transaction.
+- Run the table `.withExport` so the source's `expectedQueries` show the document unchanged.
+- No `vi.spyOn` on a transaction or query method: a spy tests how the code writes, and passes while the
+  document is wrong.
+
+```ts
+// BAD: a spy on how it writes
+const addChild = vi.spyOn(tx, 'addChild')
+await expect(addFirstChild(tx, params)).rejects.toThrow()
+expect(addChild).not.toHaveBeenCalled()
+
+// GOOD: the key, nothing staged, the document checked by expectedQueries
+await source.transaction(async (tx) => {
+	await expect(addFirstChild(tx, testCase.params)).rejects.toMatchObject({
+		cause: { key: 'ELEMENT_NOT_FOUND' },
+	})
+	expect(tx.getStagedOperations()).toEqual([])
+})
+return { assertOn: 'source' }
+```
+
+### Real records, no fakes
+
+- Test through the public interfaces: no mocks of internal collaborators, no hand-written fake `Query`,
+  no mock of a query module.
+- A step that reads real records gets one real-engine case asserting the values it read, before any
+  mock is considered.
+
+### Fixtures are whole documents
+
+Each case's document is written out in full, so a reader sees the exact input without assembling it in
+their head, and holds only the elements the case needs.
+
+- **In the test file** (inline in the case, or one file-level constant used whole) when it is at most
+  **40 lines**. Above, a sibling file
+  `fixtures/<what-it-holds>.xml` read with a static `?raw` import. A fixture file is at most **120 lines**
+  and its name says what it holds (`a-with-two-aa-1.xml`, not `fixture2.xml`).
+- **A variant is its own document**, never a copy edited at runtime: no `.replace()` on a fixture, no
+  shared XML constant spliced into a case's document (`${CHILDREN}`, `${HEADER}`), no fixture builder
+  functions, no `*.test-fixtures.ts` module. Substitutions inside a tag are fine: names (`${ns}`),
+  attribute values (`aA="${UUID}"`), namespace declarations. A shared empty target is fine.
+- A case reading a fixture file carries **one comment** naming what matters in that document
+  (`// A "one" holds no AA_1; A "two" holds one without bAA_1`).
+- `dev:db-id` (`CUSTOM_RECORD_ID_ATTRIBUTE`) gives records stable ids; choose ids that say intent
+  (`orphaned-ref`, `a-without-child`). Comment the elements that are deliberately absent. No
+  `<?xml ?>` declaration in template literals.
+
+```ts
+// BAD: assembled from pieces
+sourceXml: `<Root ${XMLNS_DEFAULT_NAMESPACE}>${A_WITH_CHILDREN.replace('aA="one"', 'aA="two"')}</Root>`,
+
+// GOOD: the whole document, inline or as its own file
+import aWithTwoAa1 from './fixtures/a-with-two-aa-1.xml?raw'
+// A "one" holds two AA_1; the second has no bAA_1
+sourceXml: aWithTwoAa1,
+```
+
+**Making a variant: a throwaway script, never calls in the test.**
+
+1. Start from `dialecte fixture <Tag>` (the smallest valid document holding the tag) or an existing whole
+   fixture.
+2. Write the variant with a throwaway script:
+   `dialecte run make-<what>.ts --in <base>.xml --out fixtures/<what-it-holds>.xml --seed <n> --now <iso>`
+   (seed and clock fixed, so the same command gives the same file). The script may use any tested
+   feature, the verb being changed included: its current output is a valid starting document.
+3. Check the result: valid against the schema, and `--expect <file>` (a JSON array of
+   `{ tag, where?, under?, count? }`) for what the case needs the document to hold.
+4. Commit only the `.xml`. The script is never committed, and never thrown away before the review
+   either: a fixture whose making cannot be rerun cannot be reviewed. Keep it with the change's
+   hand-over notes (the folder handed to the reviewer) as `fixture-scripts/make-<what>.ts`, listed in
+   `fixture-scripts.md` (`| fixture | script | command |`), and delete it with the notes once the change
+   lands. A document written whole by hand needs no script; say so on its line.
+
+### Expectations are written by hand
+
+- **Expectations are structural XPath with meaningful predicates**, written in the test file from the
+  requirement. `//default:AA_1` alone proves nothing; a case can pass because ANOTHER element matched.
+  Do not assert on `dev:db-id` in XPath. Pair `unexpectedQueries` with the commented-out source when
+  asserting a deletion.
+- **Never generated.** For a document outcome, a document produced by the code under test is never
+  the expected result: comparing an export with a saved `.xml` is a snapshot in disguise, it passes on
+  whatever the code did the day it was saved.
+
+```ts
+// BAD: the code's own output as the truth
+expect(exported).toBe(expectedAfterAddXml)
+
+// GOOD: what the requirement says, as queries
+expectedQueries: ['//default:A[@aA="one"]/default:AA_1[@aAA_1="added"]'],
+```
+
+### The runner and the assertions
+
 - **Fixtures are validated against the schema before a case runs** by the runners `createTestHelpers`
   builds - every dialecte package's `run<Name>TestCases` / `create<Name>TestProject` (a dialecte may
   add its own checks, see its skill). Opt out of those extra checks only with a written reason
   (`skipExtraChecks: '<why>'` on `createTestProject`). Core's own `runTestCases` on the dummy
   dialecte (`createTestRunner`) validates nothing.
-- **Test the function directly** (`fn(source.query, params)` / `fn(tx, params)`), not through the
-  bound extension method. Use public interfaces; no mocks of internal collaborators.
 - **No test names its store: the runner chooses it.** A node vitest project whose setup file calls
   `useTestStorage({ type: 'inMemory' })` (core 0.8+) runs your tests in Node on the in-memory store;
   without one, the runner's default store. A second project whose setup imports

package/skills/dialecte-contributing/SKILL.md

@@ -121,7 +121,7 @@ what the station records for the hand-over card).
 5. **Independent review**: have a fresh reviewer (a sub-agent with only the spec, the diff and
    these rules, or a human) read the diff against the previous version before hand-over. Self-review
    re-reads your own intent and misses weakened assertions and unusable types.
-6. **Hand over** through `npx dialecte handover <lots.json>`: the agent writes only the lots file, the
+6. **Hand over** through `npx dialecte handover write <lots.json>`: the agent writes only the lots file, the
    command writes the hand-over folder and prints the card the user gets
    ([references/landing-changes.md](references/landing-changes.md)). The agent never commits or pushes.
 

package/skills/dialecte-contributing/references/code-rules.md

@@ -12,6 +12,7 @@ does not name.
 - Files and types
 - Naming
 - Comments and committed text
+- Tests
 - Self-check before hand-over
 
 ## Reuse and sources of truth
@@ -87,6 +88,12 @@ does not name.
 - Do not create documentation that was not asked for, beyond the docs + CHANGELOG the Definition
   of Done requires.
 
+## Tests
+
+Tests follow the rules of the `dialecte` skill's references/testing.md (section Rules): the one source for
+how a table, a case, a fixture and an expectation are written. Read it before writing a case; this page
+does not repeat it.
+
 ## Self-check before hand-over
 
 ```bash

package/skills/dialecte-contributing/references/landing-changes.md

@@ -8,7 +8,7 @@ script may be waiting or running in the human's terminal.
 
 ## The hand-over
 
-The agent writes only a lots file; `npx dialecte handover <lots.json>` does the rest. One lots file per lot
+The agent writes only a lots file; `npx dialecte handover write <lots.json>` does the rest. One lots file per lot
 group, in an uncommitted hand-over folder (for example `_commit-plan/<topic>-<yyyy-mm-dd>/lots.json` at the
 workspace root, outside every repo); the hand-over files are written next to it (`--out <dir>` elsewhere):
 
@@ -64,13 +64,13 @@ workspace root, outside every repo); the hand-over files are written next to it
   and is for when the person asks. A heavy hook that does run is rehearsed while another suite loads the
   machine, as it will be when the user commits; when that is not possible, the hand-over notes the machine's
   load at rehearsal time (`uptime`). The real commit's hook always runs.
-- Edited a file after the snapshot (a review fix)? `npx dialecte handover --rehash <lots.json>`.
+- Edited a file after the snapshot (a review fix)? `npx dialecte handover write <lots.json> --rehash` (a cli from 0.2.0 to 0.3: `npx dialecte handover <lots.json> --rehash`).
 - `npx dialecte handover list` shows every hand-over folder with its state (pending, partly committed,
   committed, stale); after a merge, `npx dialecte worktree prune` lists the committed ones with the merged
   worktrees and prints their removal commands: an agent hands them (or the `--yes` command, which asks on
   a terminal) to the user with their `cd`.
-- `handover` comes with `@dialecte/cli` 0.2.0 or later; with an older cli in the package, run
-  `npx @dialecte/cli@^0.2.0 handover <lots.json>` (never `@latest`, which can be older).
+- `handover write` comes with `@dialecte/cli` 0.4.0 or later; a cli from 0.2.0 to 0.3 takes
+  `npx dialecte handover <lots.json>` (the same command 0.4.0 keeps as an alias).
 
 ## Commit messages
 

package/skills/dialecte-lot/SKILL.md

@@ -52,7 +52,7 @@ follows the hand-over, and the branch goes up by pull request through that repos
 (`dialecte-contributing`). In an app that consumes a dialecte, the lot ends at
 Station 6: what comes after belongs to the app's own process - its PR skill and template for the pull
 request, its own retro and clean-up if it has them - and no further station of this skill runs (no Station 7,
-no `dialecte worktree prune`, no dialecte PR or release step). The hand-over's records (`dialecte recap`
+no `dialecte worktree prune`, no dialecte PR or release step). The hand-over's records (`dialecte lot recap <folder>`
 prints a PR's details part from them) feed the app's template only where its rules ask for it. Pushing and
 posting stay the user's (or wait for their approval).
 
@@ -71,9 +71,27 @@ wrong.
 
 Before the test station, the plan holds what the tests will pin; a gap found by a reviewer costs a round.
 
+- **Discovery first**, before any test or code: list what already covers the concept with the whole cli
+  surface - `dialecte api find` and the API index, `explain`, `schema`, `fixture`, `standard find` / `show`, the
+  package skills - then a code search for what they do not index. The list goes into the lot's `decisions.md`,
+  each hit reused or with why not; a shared read found wrong is fixed in place, never forked. Reviewers check the
+  diff against that list. The list records evidence: it never limits what a station may use.
+- **An automatic destructive action** (a command or hook that deletes, moves or resets without the person
+  running it): the brief opens with its invariant - "never <act> on <thing> unless it is proven <X>, <Y>, <Z>" -
+  and a list of adversarial cases written before the tests: for checkouts, other lots, reused or switched
+  worktrees and branches, locks, live processes, links; for content, what the target touches, references to
+  it, a target emptied and refilled; for both, concurrent runs and an interrupted step. Where proving costs more than
+  asking, print the command for the person instead of acting. Keep rules alone let every round find one more
+  state.
+- **A step that removes content** (a prune, a redaction, a dedupe): a preservation check per unit (file, page,
+  element) proves only the targeted content went, loss counted per unit and never by a summary that hides a
+  one-off, and a boundary case (the target touching what must stay) is written before the code.
+- **A rename across many cases** (an output prefix, a message: behaviour, so never an exempt lot): the
+  test-station brief states the mapping as a rule (`<call>` → `<expected text>`) and asks for one audit pass
+  of every touched file against it before `tdd red`; a text replace without it swaps names in both directions.
 - **The standard** (a lot whose rules come from a standard the code implements):
   [references/standard-check.md](references/standard-check.md) - how it is read, the cross-check for a
-  decision, and what the station records for the hand-over card (`dialecte record standard`).
+  decision, and what the station records for the hand-over card (`dialecte lot standard`).
 - **A tooling lot with shared state or an external tool**: the plan carries the store's transition table, its
   invariant and the interleavings, the test-station brief asks one forced-order test per interleaving, and the
   hand-over folder gets a `SMOKE.md` with the lot's one real run; how and where that run happens, and citing
@@ -131,7 +149,13 @@ test edited after red; the test code changed since its freeze; the cases the cha
 --fast` and `--full` check the receipts in their `tdd` step: every test-code file of the change as frozen,
 every new or changed case red then green (or unchanged), the flags and deleted cases listed.
 
-**Exempt lots.** A lot that changes no behaviour - a wording, a rename, a doc-only or a CHANGELOG-only
+**Checks run per step, not at the end of the lot**: the other tests related to the touched files (`vitest
+related` or `--changed <base>`), `check` (its type-check covers the tests) and, in a dialecte package, `dialecte
+rules` on the touched files. The whole suite runs once, at `gate --full`. After any edit of a test (a test-review
+return included, a type-only one too), the test station takes `tdd red` again before `tdd green`: a case greened
+over an unproven edit ends up accepted, not proven.
+
+**Exempt lots.** A lot that changes no behaviour - a wording, a rename nothing outputs, a doc-only or a CHANGELOG-only
 lot - has no red to prove. The orchestrator declares it in the brief and writes
 `{ "tdd": "exempt: <reason>" }` to `.dialecte/lot.json` at the package root of the worktree; the gate's
 `tdd` step passes with the reason and what the change touches ("exempt: <reason> (n production files, m
@@ -152,7 +176,8 @@ Before touching code (the implement station; the test station does the same befo
    can assume things that changed. A contradiction stops you: say it, do not reinterpret the plan.
 2. `git status -sb` in your worktree: right branch, clean (or dirty only with your own earlier work).
    Note the HEAD sha for your report.
-3. Load `dialecte` (and `dialecte-contributing` in a dialecte package); run the reuse ladder before writing anything.
+3. Load `dialecte` (and `dialecte-contributing` in a dialecte package); run the reuse ladder before writing anything,
+   starting from the lot's discovery list in `decisions.md` (Station 0).
 
 Then, within the step:
 
@@ -261,8 +286,10 @@ copy of every file `git status --porcelain -z --untracked-files=all` lists at th
 untracked, at its path relative to the repository root, and beside it `round-<n>.deleted`, NUL-separated, naming
 each deleted file and the old path of each rename (beside the copy, never in it: it is no file of the lot). A copy,
 not a patch: nothing to apply, binary files included. The lot stays uncommitted until the hand-over, so HEAD is the
-base for the whole loop: these snapshots are the only refs the later rounds have. From cli 0.2.0,
-`dialecte record snapshot <folder> --round <n>` takes it (and `dialecte review delta` reads it); the text here is
+base for the whole loop: these snapshots are the only refs the later rounds have. Every round gets one, round 1
+and a verify-only round included: without it a throwaway worktree holds the only copy of that round's state,
+lost when the throwaway is removed. From cli 0.4.0,
+`dialecte lot snapshot <folder> --round <n>` takes it (and `dialecte lot delta` reads it); the text here is
 the manual fallback for an older cli.
 
 - **Round 1 - full review**, blind to the implementer's conclusions, every severity. The checklist, each angle
@@ -276,8 +303,8 @@ the manual fallback for an older cli.
   the findings ledger. The last round reports what its class acts on; anything below is logged as a follow-up, not
   fixed in the lot. A finding the last round acts on is fixed; the round that would verify the fix goes to the user
   (above). The floor rises so the rounds converge. The review has three parts:
-  - (a) **Each fix verified on the old code.** From cli 0.2.0,
-    `dialecte review delta <folder> --round <n> --worktree` makes the throwaway worktree holding `round-<n-1>/`
+  - (a) **Each fix verified on the old code.** From cli 0.4.0,
+    `dialecte lot delta <folder> --round <n> --worktree` makes the throwaway worktree holding `round-<n-1>/`
     (the fixer's, when it made one: Station 4, reused, never a second); with an older cli, the orchestrator makes one by hand on its own branch
     (never the lot's), copies the snapshot over it, removes its deleted files - the one place a `git rm` is
     allowed, never in the lot's worktree - and passes the path (`worktree prune` lists it after the lot):
@@ -313,13 +340,15 @@ the manual fallback for an older cli.
   - (c) **One line naming what round 1 did not look at.**
 
 **The findings ledger** (`findings-ledger.md` in the hand-over folder) is the lot's memory across rounds. Only the
-orchestrator writes it, by hand or, from cli 0.2.0, with `dialecte record review` (a new row, `open`) and
-`dialecte record decision` (the states `open`, `fix to verify`, `fixed <n> [note]`, `accepted`, `logged`). The
-cli writes neither the risk-class line nor `reopened`, and its `fix to verify` carries no blast radius: write
-those by hand, or keep the blast-radius lines in a fixes file beside the ledger. Reviewers propose rows. It
-opens with the risk class (`Risk class: <class> - <rounds> rounds, last round acts on <floor>, a further round
-only with the user - set by <files>`). One row per finding: id, round
-raised, severity, file:line, state - `open`, `fix to verify - <blast radius>` (the fixer says fixed; its
+orchestrator writes it, by hand or, from cli 0.4.0, with
+`dialecte lot finding <folder> --round <n> --severity <blocking|should-fix|nit> --at <file:line> <finding>`
+(a new row, `open`) and
+`dialecte lot decide <folder> <finding> <open | fix-to-verify | fixed <round> [note] | accepted <reason> | logged <where>>`
+(the ledger row spells the state `fix to verify`). The cli writes neither the risk-class line nor `reopened`,
+and its `fix-to-verify` carries no blast radius: write those by hand, or keep the blast-radius lines in a fixes
+file beside the ledger. Reviewers propose rows. It opens with the risk class (`Risk class: <class> - <rounds>
+rounds, last round acts on <floor>, a further round only with the user - set by <files>`). One row per finding:
+id, round raised, severity, file:line, state - `open`, `fix to verify - <blast radius>` (the fixer says fixed; its
 blast-radius line comes with it), `fixed <n>` (n = the round that verified the fix; `fixed <n> (reasoned)` when the
 guard was not run), `reopened <n> by <id>` (a later fix broke it again), `accepted <reason>`, `logged <follow-up>`.
 Every reviewer reads it; a finding fixed or accepted is not raised again unless the fix is wrong. Outside every
@@ -362,8 +391,8 @@ that fixes one finding and hides another, a fix that undoes an earlier one.
 
 **The red of a fix's new test comes from the tree the round reviewed, never from production put back.** Write the
 test before the fix and take its red with `npx dialecte tdd red` while the code it pins is still the reviewed one.
-When production already holds the fix, run the new test where the old code still lives: `npx dialecte review delta
-<folder> --round <n+1> --worktree` (n = the round whose findings you fix; cli 0.2.0, else the orchestrator's
+When production already holds the fix, run the new test where the old code still lives: `npx dialecte lot delta
+<folder> --round <n+1> --worktree` (n = the round whose findings you fix; cli 0.4.0, else the orchestrator's
 hand-made throwaway of Station 3 (a)) makes a throwaway worktree holding `round-<n>/` and prints its removal
 command; copy the new test file in, with the test code it imports that the round changed, run it there - it must
 fail on its assertion - and in the lot's worktree, where it passes. The report says the red was taken on
@@ -381,12 +410,13 @@ it from a test-first red (it flags `red after green` only when the case already
 
 ## Station 6 - hand over
 
-Write only the lots file and run `npx dialecte handover
-<lots.json>`: it writes the hand-over folder and prints its card. Never a hand-written script, nor a file per
-commit. When the repository has a commit hook (`core.hooksPath`), rehearse first with `npx dialecte handover
-run <folder> --rehearse`: a scratch clone holding your tree, the hooks folder and `node_modules`, so the hook
-runs as it will for the user. Rehearse a heavy hook while another suite loads the machine, or at least note
-the load at rehearsal time (`uptime`) after the card: a quiet rehearsal hides a time bound that fails under load.
+Write only the lots file and run
+`npx dialecte handover write <lots.json>`: it writes the hand-over folder and prints its card. Never a
+hand-written script, nor a file per commit. When the repository has a commit hook (`core.hooksPath`),
+rehearse first with `npx dialecte handover run <folder> --rehearse`: a scratch clone holding your tree, the
+hooks folder and `node_modules`, so the hook runs as it will for the user. Rehearse a heavy hook while another
+suite loads the machine, or at least note the load at rehearsal time (`uptime`) after the card: a quiet
+rehearsal hides a time bound that fails under load.
 
 **A check's result belongs to the tree it ran on.** From cli 0.2.0 every gate and hook result is recorded with
 what it checked - the tree, the installed lock, the linked `file:` dependencies and the command - and a run with
@@ -411,7 +441,9 @@ never a pasted or retyped card, which goes stale as soon as a record changes. Wi
 **is the card** `handover` printed - repository, worktree, branch, HEAD, gates, the lots with their files and
 messages, and the command with its absolute `cd` - pasted as printed, never retyped. After it: what was not verified, and one usage line (the lot's sub-agent tokens, in total
 and by station: [references/retro.md](references/retro.md)). A refusal is a finding: fix the file or the
-message, do not loosen the lots. `npx dialecte handover list` shows every hand-over waiting on the machine.
+message, do not loosen the lots. Before reporting, stop every background task you started and check with `ps`
+that none is left: a forgotten wait loop holds the worktree, and `lot close` keeps it, for as long as it runs.
+`npx dialecte handover list` shows every hand-over waiting on the machine.
 Never commit, push, stage, or touch a repository's index while a hand-over may be waiting.
 
 ## Station 7 - retro
@@ -433,10 +465,15 @@ that is rewritten every retro never settles.
   in its worktree before anything else. Its hygiene step fails on a staged file or a stash added since the
   worktree was made, whatever wrote it. A failure is a finding: look with the read-only commands it prints
   and report it; never repair it with a git command that writes. When the agent changed nothing, the gate
-  still runs its hygiene and `tdd` step and answers the rest from its record of that tree.
+  still runs its hygiene and `tdd` step and answers the rest from its record of that tree. Then check with `ps`
+  that no task the agent started is still running in its worktree: one left is stopped and reported.
 - Write each brief from [references/briefs.md](references/briefs.md): the brief is the agent's whole
   context; synthesise, do not say "based on the findings". Every brief carries its lines for all stations
-  (nothing under `.git` by hand, no workflow without the user's opt-in, no `rm` on a variable path).
+  (nothing under `.git` by hand, no workflow without the user's opt-in, no `rm` on a variable path, files
+  edited with the edit tool, a rewriting script reads before it opens for writing, no ad-hoc file-writing
+  script with a lot's worktree as its working folder: it runs from the scratchpad or the hand-over folder; no
+  real person's name or handle in any file, test values included; every background task it started stopped,
+  checked with `ps`, before it reports).
 - Each station agent is defined once, for every host, in [references/stations.md](references/stations.md):
   its tier, its access (`read`, `review`: runs commands but edits nothing, `edit`) and its role (`test-writer`,
   `test-reviewer`, `implementer`, `implementer-strong`, `reviewer`, `fixer`, `eval-runner`, `grader`,
@@ -477,8 +514,8 @@ orchestrator launches in the background gets a **deadline** when it is launched:
   you - a scheduled check or a wake-up at the deadline, or a monitor on the run's log - so you are woken even
   if no notice comes. A host with none polls at the deadline.
 - **At the deadline, look at the run itself**: its process tree (`pgrep -P <pid>`, `ps -o pid,stat,time,command`:
-  is its CPU time growing?), the agent's last activity or the log's last line and its time, and `dialecte runs`
-  once the cli has it (the live runs of the machine, each with its state).
+  is its CPU time growing?), the agent's last activity or the log's last line and its time, and a list of the
+  machine's live runs, each with its state, once the cli has one.
 - **Kill on what you see, never on the clock.** No new output and no CPU time gained by the tree since the
   last look: it is stuck - tell the user what you saw (the tree, the last line, since when) and stop or
   restart it. Still gaining CPU time or writing output: set one more deadline. Past that second deadline it
@@ -521,6 +558,8 @@ hooks. What differs is how a host starts a session, spawns an agent and wakes yo
 - `rm`, `mv` or `xargs` on a variable path: leave temporary files in the hand-over folder or the scratchpad.
 - Wait on a background run with no deadline, or on its completion notice alone.
 - Hand over a hand-written commit or merge script.
+- Write a real person's name or handle in any file, test values included: neutral names (`reviewer`,
+  `person-a`).
 - Implement two lots in one station "because they are small".
 - Reach for `any`, `@ts-ignore` or a skipped test to get green.
 - Let an output live only in the chat.