@dialecte/core 0.8.1 → 0.10.0

package/skills/dialecte/references/core-api.md

@@ -21,13 +21,13 @@ in the installed `.d.ts` or the repo before calling. Paths are relative to the c
 
 ## Entry points
 
-| Import                   | What is there                                                                                                                                    |
-| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `@dialecte/core`         | Project, Document, Query, Transaction, `defineDialecte`, `createProjectFactory`, stores, XML parse/build, errors, diagnostics, perf, all types   |
-| `@dialecte/core/helpers` | record converters, guards, `readAttribute(s)`, `standardizeRecord`, `mergeExtensions`, `stripAttributes`, write-path guards, namespace constants |
-| `@dialecte/core/utils`   | attribute rules, definition resolution, xsi:type, namespaces, ordering, `invariant`, `formatXml` / `formatEmbeddedXml`, `saveToDisk`             |
-| `@dialecte/core/test`    | `createTestHelpers`, `createTestRunner`, `createTestProject`, XML/XPath assertions, test dialecte, `normalizeUuids`                              |
-| `@dialecte/core/sqlite`  | opt-in SQLite storage: importing it registers `{ type: 'sqlite' }`; `connectHub`, `adoptHubPort`, `listProjects`                                 |
+| Import                   | What is there                                                                                                                                                                                                     |
+| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `@dialecte/core`         | Project, Document, Query, Transaction, `defineDialecte`, `createProjectFactory`, stores, XML parse/build, errors, diagnostics, perf, all types                                                                    |
+| `@dialecte/core/helpers` | record converters, guards, `readAttribute(s)`, `standardizeRecord`, `mergeExtensions`, `stripAttributes`, write-path guards, namespace constants                                                                  |
+| `@dialecte/core/utils`   | attribute rules, definition resolution, xsi:type, namespaces, ordering, `invariant`, `formatXml` / `formatEmbeddedXml`, `saveToDisk`                                                                              |
+| `@dialecte/core/test`    | `createTestHelpers`, `createTestRunner`, `createTestProject`, XML/XPath assertions, test dialecte, `normalizeUuids`                                                                                               |
+| `@dialecte/core/sqlite`  | opt-in SQLite storage: importing it registers `{ type: 'sqlite' }`; `serveSqliteEngine` (the app's one engine worker file), `registerSqliteEngine` (the page, once), `connectHub`, `adoptHubPort`, `listProjects` |
 
 ## Project (`project/project.ts`)
 
@@ -53,7 +53,8 @@ in the installed `.d.ts` or the repo before calling. Paths are relative to the c
   in-memory) the channel is the Project's own and reposts what the store tells; on `local` (IndexedDB) it is
   shared by project name.
 - `listProjects({ dialecteId? })` from `@dialecte/core/sqlite` (SQLite projects of the origin, read from the private
-  file system) and `factory.destroyProject({ name })` (delete one without opening it).
+  file system) and `factory.destroyProject({ name, storage })` (delete one without opening it, from the storage named:
+  `storage: { type: 'sqlite' }` for a project on SQLite; any kind works the same way).
 
 ## Document (`document/document.ts`)
 
@@ -184,13 +185,39 @@ needs the parent's `updated` (children list) too.
 
 ## Stores (`store/`)
 
-- `storage` param: `{ type: 'local' }` (IndexedDB, the default), `{ type: 'sqlite' }` (the SQLite
-  engine in a worker, one per project shared by every tab through the hub; opt-in: the app imports
-  `@dialecte/core/sqlite` once, else `PROJECT_SQLITE_NOT_IMPORTED`; opened from a dialecte's project
-  factory, which names its engine worker),
-  `{ type: 'inMemory', writable? }`,
-  `{ type: 'custom', store }`. The store is a switch: results must be identical on every store,
-  only speed changes. A difference is a store bug.
+- `storage` param: `{ type: 'local' }` (IndexedDB, the default), `{ type: 'inMemory', writable? }`,
+  `{ type: 'custom', store }` - core's own kinds - and any kind an entry registers: `{ type: 'sqlite' }` (the SQLite
+  engine in a worker, one per project shared by every tab through the hub; setup below) exists once
+  `@dialecte/core/sqlite` is imported. The store is a switch: results must be identical on every store, only speed
+  changes. A difference is a store bug.
+- Storage kinds are a registry: an entry adds its kind with `registerStorageKind({ type, kind: { id, storeOf } })`
+  (from `@dialecte/core`) and widens `StorageParam` by augmenting `interface StorageKinds` of `@dialecte/core`
+  (`declare module '@dialecte/core' { interface StorageKinds { mine: { type: 'mine'; url: string } } }`) - how a
+  store package plugs in like SQLite does. A type nobody registered (an app that never imported
+  `@dialecte/core/sqlite`) is refused `PROJECT_STORAGE_NOT_REGISTERED`; another kind under a taken type,
+  `STORE_KIND_TAKEN`.
+- SQLite storage is opt-in and **the app assembles its engine**; a dialecte package ships its declaration
+  only, no worker. The SQLite calls come from `@dialecte/core/sqlite`, which the app imports once (the factory and
+  the rest of the API stay in `@dialecte/core`):
+  - the app's one engine worker file (say `engine.worker.ts` in its sources) calls `serveSqliteEngine({ dialectes })`
+    with every dialecte the app opens on SQLite - one file for all of them, not one per dialecte;
+  - the page calls `registerSqliteEngine({ url, dialectes })` once, before the first project opens: `url` a
+    `?worker&url` import of that file, `dialectes` the same list (declarations fit);
+  - `createProjectFactory({ dialecte })` takes the declaration only, no engine URL; a project opens with
+    `storage: { type: 'sqlite' }`; `connectHub()` takes no parameter (optional: a project opening on
+    `sqlite` offers the registered engines too).
+- SQLite refusals: entry never imported → `PROJECT_STORAGE_NOT_REGISTERED` (core: no `sqlite` kind); no
+  registration, or one that does not name the project's dialecte → `PROJECT_SQLITE_ENGINE_NOT_REGISTERED`, nothing
+  started; a worker file that fails to load, or cannot load the engine's chunk (a precache list that leaves it out)
+  → `PROJECT_ENGINE_UNAVAILABLE`; a project stored by another layout → `PROJECT_LAYOUT_OUTDATED`. The keys only SQLite
+  raises (`PROJECT_SQLITE_*`, `PROJECT_ENGINE_*`, `PROJECT_LAYOUT_OUTDATED`, `PROJECT_DATABASE_LOST`, the hub's
+  `STORE_HUB_*`, `STORE_REALM_*`, `STORE_PROTOCOL_MISMATCH`, `STORE_SQLITE_ENGINE_FIXED`) are declared by
+  `SQLITE_ERRORS` from `@dialecte/core/sqlite`, codes unchanged: match them with
+  `isKnownDialecteError(error, { catalogues: [SQLITE_ERRORS] })` or `SQLITE_ERRORS.<KEY>.key`.
+- A store behind a connection (SQLite's worker, a remote store) that loses it refuses the call
+  `STORE_CONNECTION_LOST` (core); for a write, `meta.writeId` and `meta.outcome` (`applied`, `not-applied`,
+  `running`, `unknown`) say whether it landed - a Document's commit and a Project's import ask it once themselves;
+  never write again blindly (`store.getWriteOutcome({ writeId })`).
 - `Store` interface is public surface for custom stores. The patch merge every built-in store uses
   is internal to the stores (not exported): a custom store merges a `RecordPatch` itself.
 

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.

package/skills/dialecte-lot/references/briefs.md

@@ -14,6 +14,14 @@ Never edit, move or remove a file under a repository's .git folder (a lock, a co
 No multi-agent workflow (a host tool that fans out many agents at once) unless the user opted in; a sub-agent
   of yours has its own spawn. No rm, mv or xargs on a variable path: leave temporary files in the
   hand-over folder or the scratchpad.
+Edit files with the edit tool. A script that rewrites a file reads it fully before it opens the file for
+  writing, never both in one expression (opening for writing empties the file before the read).
+Never run an ad-hoc script that writes files with a lot's worktree as its working folder: cd to the scratchpad
+  or the hand-over folder first, and name a worktree file by its absolute path.
+No real person's name or handle in any file you write, test values included: use neutral names (`reviewer`,
+  `person-a`).
+Before you report, stop every background task you started (a wait loop, a watcher, a server) and check with
+  `ps` that none is left.
 ```
 
 ## Test-station brief
@@ -24,6 +32,10 @@ Tier: standard (model-tiers.md; `npx @dialecte/cli models` says which model). St
 
 Step: <the 3-6 behaviours of the step, as case keys "<state> → <outcome>">
 Spec: <the plan section(s), by path and heading; the decisions that bind it>
+Invariant (a lot that deletes, moves or resets on its own; else no such line): <never <act> on <thing> unless
+  proven <X>, <Y>>; every test checks it, and the adversarial cases are written first.
+Preservation (a step that removes content; else no such line): a check per unit that only the target went, and
+  a boundary case where the target touches what must stay.
 Read: this brief and the existing code only - not an implementation, not another agent's notes.
 Worktree: <absolute path>, branch <branch>, base <sha>. Work only there. Never commit, stage, push,
   `git stash` or any git command that writes the index.
@@ -31,9 +43,15 @@ You may change: the test files of the step, and stubs - new exports with their r
   `new Error('not implemented: <name>')`. Never a behaviour of the production code.
 Each test calls the code under test inside an `expect(...)` a matcher completes, so a stub's error is a
   red on the behaviour. Remove every `.only` and `only: true` before `tdd red` (it refuses a file holding one).
+Each case spells its full title: `tdd` keys a case by its title, and vitest cuts each `$` field of an
+  `it.each(...)` title (`'$name'`) at 40 characters, so long names collide - never a `$` field for them.
 A test that reads the disk, spawns a process or measures time carries an explicit bound with wide slack,
   a named constant (core: `SOURCE_SCAN_TIMEOUT_MS` in `src/test/test-timing.constants.ts`), never the
   runner's default timeout.
+Rename mapping (a lot that renames an output across many cases; else no such line): <the rule, `<call>` →
+  `<expected text>`>. Before `tdd red`, one audit pass of every touched file against it.
+Per step: the other tests related to the files you touched, `check`, and `dialecte rules` on them (a dialecte
+  package). After any edit of a test - a test-review return included - you take `tdd red` again.
 Done when `npx dialecte tdd red` records a red for every case of the step; a refused case (passes, missing
   export, type or syntax error, timeout, stub at import or before the assertion) is fixed in the test.
 Report: the `tdd red` output, unfiltered, and the list of stubs.
@@ -86,7 +104,9 @@ Skills: load dialecte and dialecte-lot (and dialecte-contributing in a dialecte
   before the change; runs with and before the change on the standard and strong tiers, several per
   configuration; graded blind by
   a separate agent, never by you; its benchmark and viewer paths in your report.
-Gates: fast gate per behaviour; full Definition of Done once at the end (<the package's commands>).
+Gates: per step, the tests related to the touched files, `check` and `dialecte rules` on them (a dialecte
+  package); fast gate per behaviour; full Definition of Done once at the end (<the package's commands>).
+Discovery: <the lot's decisions.md> lists what already covers the concept; reuse it, or add why not there.
 Mutation (a dialecte package that declares a mutation scope; else no such line): <off | changed | gate | audit, set in .dialecte/lot.json>; once green (a gate lot: again after the last
   fix), `dialecte mutants run` in the background, survivors judged (`dialecte mutants judge --json`, then a
   test, `record` or `schedule`), `dialecte mutants status` before the report: no new survivor, no died run, a
@@ -121,8 +141,8 @@ Later rounds - delta review of the fix diff and its blast radius only. Start fro
   `git diff --no-index --no-color --no-ext-diff round-<n-1>/<file> <worktree>/<file>`; not in round-<n-1>/ (at
   the base then), `git -C <worktree> diff --no-color --no-ext-diff HEAD -- <file>`, or /dev/null as the left
   side for a file the base does not have or that round-<n-1>.deleted lists; gone from the worktree, /dev/null as
-  the right side (from cli 0.2.0, `dialecte review delta <folder> --round <n>` prints that diff per file).
-  Throwaway worktree: <path - from `dialecte review delta <folder> --round <n> --worktree` (cli 0.2.0; the
+  the right side (from cli 0.4.0, `dialecte lot delta <folder> --round <n>` prints that diff per file).
+  Throwaway worktree: <path - from `dialecte lot delta <folder> --round <n> --worktree` (cli 0.4.0; the
   fixer's, when it made one), or made by the orchestrator with `dialecte worktree add <repository> <lot-branch>-round-<n-1> --from
   <base>`, round-<n-1>/ copied over, `git -C <throwaway> rm -q --pathspec-from-file=<folder>/round-<n-1>.deleted
   --pathspec-file-nul` | none>. Verify each fix: copy its new test file in and run it there - it must fail - and in
@@ -133,7 +153,11 @@ Later rounds - delta review of the fix diff and its blast radius only. Start fro
 Rules: the repository's code rules and Definition of Done (dialecte-contributing in a dialecte package), dialecte (reuse ladder).
 Run (read-only): the tests of the lot, `skills check`, the type-check - report the real counts.
 Check: every time bound of a test reading the disk, spawning a process or measuring time holds under load;
-  a hand-written commit or merge script in the hand-over is a finding (it goes through `dialecte handover`).
+  a hand-written commit or merge script in the hand-over is a finding (it goes through `dialecte handover`);
+  the diff against the discovery list in <the lot's decisions.md> (a hand-rolled helper it missed is a
+  finding); `git -C <worktree> grep -i -w -f <names file>` over the changed files for real people's names and
+  handles, test values included (<names file: one name or handle per line, kept outside every repository, the
+  brief carries only its path>).
 Answer: would you approve? Use the review report shape, with a severity per finding and the proposed findings-ledger rows.
 Max ~80 lines, most severe first, file:line for each finding.
 ```
@@ -150,8 +174,8 @@ Blast radius, one line under each fix: what it widens, excludes or replaces (a p
   now matching more or less; the earlier code or fix it replaces), and the findings-ledger rows it touches - its
   own and any other whose code it changes ("none beyond <id>" when so). The next round's reviewer starts there.
 A fix's new test: write it before the fix and take its red with `npx dialecte tdd red`; when production already
-  holds the fix, run it on round <n>'s tree - `npx dialecte review delta <hand-over folder> --round <n+1>
-  --worktree` (cli 0.2.0; else the throwaway I made: <path>) makes the throwaway and prints its removal command;
+  holds the fix, run it on round <n>'s tree - `npx dialecte lot delta <hand-over folder> --round <n+1>
+  --worktree` (cli 0.4.0; else the throwaway I made: <path>) makes the throwaway and prints its removal command;
   copy in the test file and the test code it imports - where it must fail on its assertion, and report "red on
   round-<n>/: <failing line>" with the throwaway's path. Never edit production back to the old behaviour to get
   a red.