@dialecte/core 0.8.0 → 0.9.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`)
 
@@ -70,6 +71,7 @@ in the installed `.d.ts` or the repo before calling. Paths are relative to the c
 - Transaction only (`tx`): `addChild`, `clearRecordCache`, `clearStagedOperations`, `commit`, `deepClone`, `delete`, `ensureChild`, `finishStaging`, `getStagedOperations`, `update`
 - Document: `close`, `destroy`, `prepare`, `subscribe`, `transaction`
 - Project: `addBlob`, `attachBlob`, `close`, `createChannel`, `destroy`, `detachBlob`, `export`, `exportBlob`, `getBlob`, `getBlobsByDocument`, `getBlobsByRecord`, `getDatabaseInstance`, `getDocument`, `getDocumentConfig`, `getDocumentStatus`, `getDocuments`, `getStandaloneBlobs`, `import`, `importFile`, `initEmptyDocument`, `open`, `openDocument`, `queryAll`, `queryFirst`, `redo`, `removeBlob`, `removeDocument`, `undo`
+
 <!-- /dialecte-skills:generated -->
 
 ## Query (`document/query/main.ts`)
@@ -183,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-contributing/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: dialecte-contributing
-description: Change Dialecte itself - @dialecte/core, a dialecte package, the generator (create) or the type-perf CLI (cli). Covers how the repos are split, the placement decision (core vs dialecte hook vs dialecte extension vs helper vs consumer code), the red-first table-driven workflow, the Definition of Done gates (check, format, build, test, doc:build, docs + CHANGELOG), the team code rules, the verification traps that give false greens, and how a change is handed over (a commit-by-lots hand-over the user runs, never pushed by the agent). Use it whenever the working directory is inside a dialecte repo, the task says "add to core", "new hook", "new extension method", "fix dialecte", "bump core in a dialecte package", or a consumer feature is blocked on a missing dialecte capability. Load the dialecte skill too for the API map; for a dialecte's own schema knowledge also load its skill (dialecte-<id>).
+description: Change Dialecte itself - @dialecte/core, a dialecte package, the generator (create) or the type-perf CLI (cli). Covers how the repos are split, the placement decision (core vs dialecte hook vs dialecte extension vs helper vs consumer code), the red-first table-driven workflow, the Definition of Done gates (check, format, build, test, doc:build, docs + CHANGELOG), mutation testing and its survivors (`dialecte mutants`), the team code rules, the verification traps that give false greens, and how a change is handed over (a commit-by-lots hand-over the user runs, never pushed by the agent). Use it whenever the working directory is inside a dialecte repo, the task says "add to core", "new hook", "new extension method", "fix dialecte", "bump core in a dialecte package", or a consumer feature is blocked on a missing dialecte capability. Load the dialecte skill too for the API map; for a dialecte's own schema knowledge also load its skill (dialecte-<id>).
 license: MIT
 metadata:
   author: dialecte
   version: '0.1.0'
+  audience: contributor
 ---
 
 <!-- dialecte-skills workspace -->
@@ -79,35 +80,16 @@ rule that contradicts the standard stays out of the engine (consumer override).
 
 ## Reading the standard
 
-For a dialecte that implements a standard: the standard your dialecte implements is the truth its rules come
-from, and a long text read once by one model is not a reliable source.
-
-- **Markdown first.** Read the standard as markdown, citing `file:line`; never the PDF. A document not yet in
-  markdown is converted first: markitdown for PDF, DOCX or PPTX; docling or pymupdf4llm when its tables come
-  out broken.
-- **The converted text stays private**: kept next to the plans, outside every package repository; never
-  committed, never quoted or cited in committed text (code, doc, CHANGELOG, skill) or on GitHub. Committed text
-  states the behaviour.
-- **A confirmation** (a name, a type, a cardinality the code already follows): one reader, with line references.
-- **A decision that changes what the engine does or accepts** gets the cross-check, once per decision:
-  1. Two or three independent readers on the `standard` tier (at least one on another model or vendor when
-     one is available): the same question, no shared notes, a `file:line` for every claim.
-  2. One reader takes the whole relevant part, the others split it by section, so coverage does not rest on
-     one model's retrieval.
-  3. An adjudicator on the `strong` tier compares the answers: an agreed claim with matching lines passes; a
-     disagreement, or a claim without a line, becomes a question for the user or the domain expert. Runs of
-     one model share its biases, so agreement is evidence, not proof.
-  4. The result (question, claims, lines, verdict) goes in the plan's research folder, next to the plan: later
-     lots reuse it instead of reading the standard again.
-
-The tiers are those of the `dialecte-lot` skill (its model-tiers reference).
+The standard check is part of every lot: `dialecte-lot` references/standard-check.md (markdown first, the
+converted text kept private, the cross-check for a decision that changes what the engine does or accepts, and
+what the station records for the hand-over card).
 
 ## The workflow
 
 1. **Orient**: read the nearest existing example of what you build (an extension in the same
    package, a hook sub-file, its test) and the package's `doc/` page for the surface. Copy shapes,
    don't invent them. A new extension verb starts from `npx dialecte new verb <namespace>
-<query|transaction> <name>`: it writes the function, its `.types.ts`, a red table case marked
+   <query|transaction> <name>`: it writes the function, its `.types.ts`, a red table case marked
    `only`, the barrel export and the namespace registration, and lists the `FILL:` placeholders
    (`skills check` refuses them until written).
 2. **Red first, proven by the cli**: the tests come first, from the spec, before any production code:
@@ -133,7 +115,9 @@ The tiers are those of the `dialecte-lot` skill (its model-tiers reference).
 3. **Implement under the code rules**: [references/code-rules.md](references/code-rules.md).
    Read it before writing the first line; most review comments come from it. `npx dialecte rules`
    checks them on the changed files.
-4. **Gates** (below), then docs + CHANGELOG if the surface changed.
+4. **Gates** (below): `gate --fast` and `npx dialecte rules` per step (fix every `rules` error before the
+   review), `gate --full` once per lot, then `dialecte contrib` (`@dialecte/cli` 0.3.0); docs + CHANGELOG if the
+   surface changed.
 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.
@@ -141,6 +125,9 @@ The tiers are those of the `dialecte-lot` skill (its model-tiers reference).
    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.
 
+Run as a `dialecte-lot` lot, each station gains the package's own steps: [references/lot-in-a-package.md](references/lot-in-a-package.md)
+(the mutation switch, `dialecte rules`, `dialecte contrib`, `mutants status`, merges onto a moved main).
+
 ## Test tiers
 
 In a package whose vitest config has a `node` project (core), a test runs in one of two tiers.
@@ -157,7 +144,8 @@ In a package whose vitest config has a `node` project (core), a test runs in one
   `npx vitest run --project browser <path>`. A file that reads the package from disk or starts node goes
   to `NODE_ONLY_TEST_FILES` the same way. The config refuses a listed path that names no file.
 - **A difference between the tiers is a bug**, of the store or of the assertion. Never move a test to
-  the browser list to hide it, never retry it. Reproduce it with `--project node`, pin it with a red
+  the browser list to hide it, never retry it beyond the one serial rerun every failing run gets (a case that
+  fails in one tier only after that rerun is a difference, not a flake). Reproduce it with `--project node`, pin it with a red
   case first: in the store contract (`src/store/contract`) when a store answers differently, beside
   core's assertion helper (`src/test/assert-xml`) when it reads the XML differently between tiers.
   Then fix it. When the test's own assertion depends on something no store promises (an XPath `[1]`
@@ -179,7 +167,7 @@ hand-over script holds the repository. With `--fast`, a change that touches no t
 passes the tests step with the note "no test file is affected by the change"; any other run that
 counts no test fails. Paste its lines in your report: they are the real counts. A gate of the same
 mode on a tree it already passed, with the same lock, linked dependencies and steps, runs its hygiene and `tdd`
-step, then answers the rest from that record (`reused`, from cli 0.2.0). `--rerun` forces a run: only when the
+step, then answers the rest from that record (`reused`, from cli 0.2.0). `--no-reuse` forces a run: only when the
 person asks, or when something outside the key changed (an edit, a lock or a linked dependency already makes a
 new key).
 
@@ -193,21 +181,28 @@ and the gate prints how many production and test files the change still touches.
 worktree's branch since `dialecte worktree add` made it (other branches' entries are only noted), and
 every new file declared (`--declare <path>`, one per new file or folder; an undeclared one is a
 warning). A failure names what changed and the read-only commands
-to look at it. `--full` and the heavy steps hold a machine-wide lock: a step the package marks `heavy`, a
-command naming a browser project, and any test step of a package that runs its tests in a browser (a
-`@vitest/browser*` or playwright dependency, a `browser` in its vitest config). A second heavy run waits
-with a line every 30 s naming the holder (`--no-wait` refuses). A heavy run outside the gate (a browser suite,
-mutation tests, a bench) starts with `npx dialecte lock run -- <command>`, which takes the same lock; a cli
-whose `npx dialecte --help` lists no `lock` does not have it yet: run nothing heavy while another heavy run is
-on the machine (`uptime`, and `ps` or `pgrep -fl` for a browser, vitest or Stryker process), and never write a
-lock script of your own.
+to look at it.
+
+**Test runs use the runner's defaults**: full parallelism, no `nice`, no `--maxWorkers`, no
+`--no-file-parallelism`, no lock and no waiting on other sessions' runs or on the load - the machine is shared,
+and that is the user's to manage: when they ask you to limit (to leave room for other sessions), do it for the
+time they say. A run that fails is rerun **once, serially, on its failing files**: the same command, its
+`--project` flags kept so the rerun stays in the failing tier, with the failing files and `--no-file-parallelism`
+added (through an npm script, after `--`). Failing there too, it is a real failure; passing there, it is **flaky in
+parallel** - a defect of the test or the code, reported with its files and fixed at its cause (a wall-clock bound
+tuned on a quiet machine, a shared temporary folder, port or build output, browser state, an inherited environment
+variable), never answered by throttling the next runs. The gate does this rerun itself on a vitest test step: a
+step that passes on it is green and its line says `flaky in parallel` with one `flaky <file>` line per file - read
+the flag on a green gate; one that fails again says `real failure`. A failing step line that says neither comes
+from a cli without the rerun: rerun its files by hand. Such a cli may still hold a machine lock around `--full`,
+its heavy steps and `tdd`: let it wait.
 
 **Waiting on a long run** (`gate --full`, a mutation run, a bench): start it in the background with its output in
 a log - your harness's background run, or `cmd > "$log" 2>&1 & echo $! > "$pidfile"` - then wait for the
 harness's completion notice or on that PID (`while kill -0 "$(cat "$pidfile")" 2>/dev/null; do sleep 5; done`),
 with an upper bound tied to the run's expected duration; at the bound, report "timed out" with the log's tail.
 Never wait with `pgrep -f "<text>"` when that text is in your own wait command: the loop finds itself and never
-ends (`pgrep -f "[m]utants.ts"` if it is unavoidable). When the wait ends, read the exit code and the log's
+ends (`pgrep -f "[v]itest run"` if it is unavoidable). When the wait ends, read the exit code and the log's
 summary line: "no process found" is not a pass.
 
 Read the step list in the package's `package.json` (`"dialecte": { "gate" }`) when it overrides the
@@ -222,12 +217,16 @@ or the steps by hand:
 3. `npm run build` - runs the type-check in parallel and emits declarations (vite-plugin-dts),
    which catches union-assignability errors the editor misses.
 4. The tests, by tier: `npm run test:node` per step (the fast gate runs its changed files), the
-   browser-only list once per lot (`npx vitest run --project browser --no-file-parallelism`, in the full
-   gate), and `npm run test:browser:all` - the whole suite in the browser - once before the branch
-   merges: any difference fails it, never retried. A package without a `node` project: `npx vitest run`
+   browser-only list once per lot (`npx vitest run --project browser`, in the full gate), and
+   `npm run test:browser:all` - the whole suite in the browser - once before the branch merges. A failing run of
+   any tier first gets its one serial rerun (above); a case that still fails there while it passes in the other
+   tier is a tier difference - a bug, never retried further, never hidden ([Test tiers](#test-tiers)). A package without a `node` project: `npx vitest run`
    (`npm run test` is watch mode in some packages; create uses `npm run test:ts` + `test:py`).
    One file while iterating: [Test tiers](#test-tiers).
-5. `npm run doc:build` - the VitePress docs build.
+5. `npm run doc:build` - the VitePress docs build. From cli 0.3.0 a dialecte package
+   (`"dialecte": { "profile": "contributor" }`) runs it, with the type bench, the code rules and the release
+   check, in `npx dialecte contrib` after a green `gate --full` and before the hand-over, whose `contrib`
+   guard refuses a tree without a green record of it.
 6. `npm run skills:generate`, then `npm run skills:check` - every change, not only one that touches a skill:
    the check fails on a name, path or script a skill cites that no longer exists, and on a public function
    without its JSDoc summary and `@intent` (below). The scripts run the package's pinned cli; with a pin
@@ -259,8 +258,54 @@ Type performance: `npm run type-bench:check` compares type instantiations with
 and explain the growth; if it is legitimate, re-baseline with `npm run type-bench` in its own lot.
 Never hand-edit `baseline.json`, never twist code to dodge the gate.
 
-Run slow gates (create's `npm run proof`, corpora, mutation testing) once per lot before hand-over,
-not after every fix. Fast targeted runs while iterating.
+Run slow gates (create's `npm run proof`, corpora) once per lot before hand-over, not after every fix.
+Fast targeted runs while iterating. Mutation testing runs beside the lot instead (below).
+
+## Mutation testing
+
+In a package that declares a mutation scope (`package.json` `"dialecte": { "mutation" }`), `dialecte mutants`
+(`@dialecte/cli` 0.2.0) runs StrykerJS on it and keeps every survivor in a ledger until it is handled; `dialecte
+mutants` with no verb prints each verb's usage. The scripts do the bookkeeping, so your tokens go to judgment only.
+
+- **The switch is per lot**, in `.dialecte/lot.json`: `dialecte lot mutation off|changed|audit|gate`. Without it, a
+  lot whose diff touches the scope runs `changed` (its changed lines), any other lot `off`. `gate` is for a
+  robustness lot only: its hand-over waits for a run reported on the tree it commits, so it runs again after the
+  last fix. `audit` mutates the whole scope.
+- **Off the critical path.** Start `dialecte mutants run` as a background run of your harness (the cli has no
+  background flag): the run is written `running` in the store before Stryker starts, so a killed session leaves a
+  `died` run, never nothing. Go on working (to wait on it: Waiting on a long run, above). A hand-over does not wait
+  for it, except a `gate` lot's; a merge does.
+- **Before every hand-over and every merge: `dialecte mutants status`.** Pending items block the card and the
+  `handover run` guard: `new` survivors of the package (whatever their lot), `died` runs, and a `running` run of the
+  branch for a merge or a `gate` lot (on a plain hand-over it is a `!`). `scheduled` survivors belong to their
+  follow-up lot and do not block.
+- **Judge one file at a time**: `dialecte mutants judge [--file <file>] --json` gives each file's packet (code,
+  covering tests, a family guess). Per survivor, one of:
+  - a test that kills it (a `gap`: red first like any test), then run again;
+  - `dialecte mutants record --key <key> --family <family> --reason "<why>"`, the reason saying in 200 characters at
+    most why no tested behaviour changes. An `invariant-guard` or `fallback-never-taken` also gets a follow-up lot
+    that deletes the guard or tightens the type: `dialecte mutants schedule <follow-up lot> <key>` first, then
+    `record ... --removable` (a scheduled survivor keeps its follow-up when recorded; a recorded one can no longer be
+    scheduled);
+  - `dialecte mutants schedule <follow-up lot> <key>` when another lot owns it.
+
+  The families are a closed list, the words of the judgment: `invariant-guard` (a check the types, or internal
+  callers only, already guarantee), `fallback-never-taken` (a default no input reaches), `exhaustive-default` (the
+  default of a switch that covers every case), `no-op-on-empty` (a skip of work that would do nothing),
+  `perf-shortcut` (a cache or an early exit that only saves time), `static-init` (module-level setup),
+  `schema-default-read` (a read of a value the schema already defaults), `wording` (message or log text). None
+  fits: it is a `gap`. Judge on the standard tier; the strong tier only for a `gap` with no obvious test.
+
+- **The cli is the only writer** of `.dialecte/mutation-records.json` and of the store under
+  `<git-common-dir>/dialecte-mutation/`: never edit either by hand (nor anything else under `.git`).
+- **Runs**: a `died` run is rerun, or `dialecte mutants abandon <run id>`; `dialecte mutants drop <run id>` removes
+  only an abandoned run or a reported one the ledger took in.
+- **Full audit** (`dialecte mutants run --mode audit`): before a release or on request, in the background; its
+  survivors are scheduled as named follow-up lots, not fixed in the release.
+
+A lot that builds tooling with shared state or drives an external tool has its own traps (plan it as a transition
+table, one real run in a scratch clone, cited third-party values): [references/traps.md](references/traps.md), Tools
+with shared state.
 
 ## Cross-package changes
 
@@ -288,11 +333,11 @@ core has `dialecte`, `dialecte-contributing` and `dialecte-lot`, create `dialect
 package its own `dialecte-<id>` with the knowledge of its schema. A skill changes in the same PR as the code it describes - never
 in another repository afterwards. `@dialecte/cli` maintains them:
 
-| Command                    | Does                                                                                                                                                                                                                                                             |
-| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `dialecte skills sync`     | installs the skills of the app's dependencies into `.claude/skills` + `.agents/skills` (`--agent claude,copilot,agents`, `--copy`); `--from <workspace>` takes them from local checkouts                                                                         |
-| `dialecte skills generate` | rewrites the `<!-- dialecte-skills:generated ... -->` blocks (verb map, method and export index, hook files) from the source                                                                                                                                     |
-| `dialecte skills check`    | frontmatter, links, and every API / path / npm script a page cites must exist; generated blocks must be fresh; every public function and method has a JSDoc summary and an `@intent`; `--workspace <dir>` also verifies pages that describe several repositories |
+| Command                    | Does                                                                                                                                                                                                                                                                      |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `dialecte skills sync`     | installs the skills of the app's dependencies into `.claude/skills` + `.agents/skills` (`--agent claude,copilot,agents`, `--copy`); consumer skills only unless `--contributing` (remembered); `--from <workspace> --contributing` takes every skill from local checkouts |
+| `dialecte skills generate` | rewrites the `<!-- dialecte-skills:generated ... -->` blocks (verb map, method and export index, hook files) from the source                                                                                                                                              |
+| `dialecte skills check`    | frontmatter, links, and every API / path / npm script a page cites must exist; generated blocks must be fresh; every public function and method has a JSDoc summary and an `@intent`; `--workspace <dir>` also verifies pages that describe several repositories          |
 
 Write claims so the check can verify them: API as `query.<method>` / `tx.<ns>.<verb>`, paths
 relative to a package, scripts as `npm run <script>`. A deliberate mention of something outside the package goes in
@@ -311,6 +356,7 @@ during import (import is in-memory two-pass by design, see the hooks rules in th
 - Add a domain rule to core because it was convenient.
 - Restate a registry or the definition by hand (see code-rules).
 - Commit, push, or touch a repo's git index while a hand-over script may be running.
+- Name a tool that consumes the package in a committed file or message ([code-rules](references/code-rules.md)).
 - Leave a known improvement as a "note for later" without doing it or explaining why you cannot.
 
 ## Retro gate - before you hand over
@@ -320,7 +366,7 @@ and every correction the user made that a skill should have prevented. Then:
 
 - **Inside a dialecte repository**: draft each skill edit as before/after and show it to the user; an
   approved edit goes in the same change (skills ship with the package that owns the code), through
-  `anthropic-skills:skill-creator` loaded with the Skill tool - the eval case first, failing on the text
+  the skill-creator skill (`anthropic-skills:skill-creator`) loaded - the eval case first, failing on the text
   before the change, as `dialecte-lot` describes - then `npm run skills:generate` and `npm run skills:check`.
 - **In an app**: draft an issue for the package that ships the skill - the statement that was wrong
   or missing, the evidence (file, behaviour), the wording you propose - and show it to the user.

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

@@ -77,6 +77,13 @@ does not name.
   review comment. Write the rule itself ("a name stays unique among its siblings"). Citations
   live only in uncommitted plan notes. Naming the standard a library implements (site tagline, the
   XSD it is generated from, the namespace prefixes of the schema, the schema's version ids) is not a citation. Never quote the standard's text anywhere (copyright).
+- **No name of a tool that consumes the package** (an app, a pipeline or a product built on a dialecte) in
+  any committed file or commit message - code, comments, tests, skill text and its evals, docs, CHANGELOG. A
+  dialecte serves every app alike: say what the behaviour is, not who asked for it ("an app", "a consumer").
+  The names live on the machine only, `git config --global dialecte.consumerNames "<name>, <name>"`, never in a
+  repository; from cli 0.3.0, `dialecte rules` and `dialecte handover` refuse each as a whole word in a
+  contributor package (`consumer tool name`). A file your lot touches that already names one is refused too:
+  reword that line only, and list it in the hand-over.
 - Do not create documentation that was not asked for, beyond the docs + CHANGELOG the Definition
   of Done requires.
 

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

@@ -40,9 +40,10 @@ workspace root, outside every repo); the hand-over files are written next to it
   unstages those files, with its `cd`: give it to the user.
 - **Guards**, checked when the folder is written (nothing is written on a refusal) and again when it
   runs: the branch and HEAD, the hooks folder `core.hooksPath` names exists (a missing one makes git skip
-  every hook), `lots.json` as reviewed, an empty index, every changed file in exactly one lot, no plan tag or standard citation in
-  a lot's files (skill evals and test fixtures included) nor in its messages; when it runs, every file
-  against the snapshot taken when it was written, and no other file changed.
+  every hook), `lots.json` as reviewed, an empty index, every changed file in exactly one lot, no plan tag, standard citation or (from cli 0.3.0) name of a
+  consuming tool in a lot's files (skill evals and test fixtures included) nor in its messages; when it runs, every file
+  against the snapshot taken when it was written, and no other file changed; and, in a contributor package (cli 0.3.0), a green `dialecte contrib` record of the tree the lots
+  leave (guard `contrib`; a rehearsal runs contrib in its clone when there is none).
 - **The folder**: the lots file, the snapshot (`files.txt`, `files.sha256`, `files.deleted`) and a one-line
   `commit.sh` that runs `npx --no-install @dialecte/cli handover run <folder>` (it re-executes itself with
   bash: people run it with `sh`). Nothing per lot. The repository stays locked for `dialecte gate` until
@@ -78,6 +79,9 @@ as the behaviour for a reader of the history. No plan/ticket tags, no standard c
 
 ## Hand-over message
 
-The message is the card `dialecte handover` printed - repository, worktree, branch, HEAD, gates, the lots
-with their files and messages, and the command to run with its absolute `cd` - pasted as printed, never
-retyped; then what was not verified.
+From cli 0.3.1 the message points at the hand-over, it does not carry it: `READY`, then
+`cd <worktree> && npx dialecte handover show <name>` (the card recomputed from the records, current whenever
+it is read) and `npx dialecte handover run <name>` (what the person runs); then what was not verified. Never
+a pasted or retyped card: it goes stale as soon as a record changes. With an older cli, the message is the
+card `dialecte handover` printed - repository, worktree, branch, HEAD, gates, the lots with their files and
+messages, and the command to run with its absolute `cd` - pasted as printed, never retyped.

package/skills/dialecte-contributing/references/lot-in-a-package.md

@@ -0,0 +1,45 @@
+<!-- dialecte-skills workspace -->
+
+# A lot in a dialecte package
+
+The `dialecte-lot` stations run the same in every repository. In a dialecte package - `"dialecte": { "profile":
+"contributor" }` in its `package.json`: core, a dialecte, create, cli - they gain the steps below. An app runs none
+of them: its lot ends at the hand-over.
+
+## Station 0 - the mutation switch
+
+- **Mutation switch** (a package that declares a mutation scope): the orchestrator sets it per lot in the worktree's
+  `.dialecte/lot.json` with `dialecte lot mutation <mode>` and names it in the brief - the default (`changed` when the
+  diff touches the scope, `off` otherwise) for most lots, `gate` only for a robustness lot (its hand-over waits for
+  a run reported on the tree it commits: it runs again after the last fix), `audit` on request. The implementer
+  starts `dialecte mutants run` in the background once green and judges the survivors as [SKILL.md](../SKILL.md)
+  (Mutation testing) says. Before a release, a full audit in the background;
+  its survivors become named follow-up lots (`dialecte mutants schedule <follow-up lot> <key>`).
+
+## Station 2 - `dialecte rules`
+
+With the fast gate, run `npx dialecte rules` from the package root and fix every error before the review; answer
+every warning ([code-rules.md](code-rules.md)). The implement report's `Gates:` line adds
+`rules <n errors, m warnings>`.
+
+## Station 5 - `dialecte contrib` after the full gate
+
+From `@dialecte/cli` 0.3.0, once `gate --full` is green, run `npx dialecte contrib`: `rules` on the files changed
+against HEAD, the package's contrib steps (by default the docs build, its generated docs restored, and the type
+bench), `release` (no dependency named by a local folder) and `mutation` when a scope is declared. A step the full
+gate passed on the same tree and install is not run again (`reused from gate --full`). Paste its lines with the
+gate's. The hand-over's `contrib` guard refuses a tree without a green record of it; a rehearsal runs it in its
+scratch clone when there is none.
+
+## Station 6 - mutation, landing, merges
+
+- The landing rules apply: [landing-changes.md](landing-changes.md) (lots, guards, rehearsal, merge lots).
+- In a package with a mutation scope, run `dialecte mutants status`
+  before every hand-over and every merge: a `new` survivor or a `died` run blocks the card and the guard until it is
+  handled ([SKILL.md](../SKILL.md), Mutation testing); the lot's own run still running blocks only a merge or a `gate`
+  lot (on a plain hand-over it is a `!`).
+- A merge onto a main that moved since the cut leaves a tree no check has seen: it is rehearsed. The branch's green
+  records say nothing about it - not its suite, nor a gate step the hook does not run (docs, skills check, the
+  browser suite). The rehearsal's hook runs the suite on the merged tree; run only the steps the hook does not run,
+  in the clone `--rehearse --keep` leaves, never a `gate --full` that would run the suite there again. A `reused`
+  line for such a merge is a cli bug to report, never a result to pass on.

package/skills/dialecte-contributing/references/perf.md

@@ -36,4 +36,5 @@ before measuring, or you measure old code.
 ## Reading results
 
 Explain a delta before acting on it. Compare against the previous commit on the same machine,
-same fixture, several runs; keep heavy runs one at a time on shared machines.
+same fixture, several runs; a timed bench runs alone, its load recorded beside the numbers: beside another
+suite its timings mean nothing (tests, unlike benches, run at full parallelism whatever the load).

package/skills/dialecte-contributing/references/traps.md

@@ -72,6 +72,26 @@ ran what you think it ran.
 - `dialecte-xmlfmt` reformats `/* xml */` template literals; it can mangle a nested template
   literal - check the diff.
 
+## Tools with shared state
+
+For a lot that builds tooling (the cli above all) rather than engine code. Each trap cost a lot several review rounds.
+
+- **A store several runs share** (a ledger, a records file, a run store, a cache, a lock) planned as prose is wrong
+  in ways only interleavings show: two runs finishing in either order, overlapping runs, a crash between two writes,
+  a dead or reused owner. The plan writes it as a transition table (event, from, to, condition), its invariant
+  ("an item leaves pending only by ...") and the list of interleavings; the test station writes one forced-order
+  test per interleaving before any code. Liveness is the process id plus its start time read in UTC, never the id
+  alone.
+- **A fake runner proves the wiring, not the integration.** A lot that drives an external tool (StrykerJS, vitest,
+  git, npm) records one real run on a known target with its expected numbers before the hand-over, in `SMOKE.md` in
+  the hand-over folder.
+- **That run happens in a scratch `git clone`** (its own `.git`), never a worktree of a real repository: worktrees
+  share the git folder, so a store under it (`dialecte-mutation/`, the check records) takes the experiment's state
+  and blocks the next real hand-over. State that landed in a real store anyway is cleared through the cli only.
+- **A value a third-party tool produces or consumes** (a report field, a column, a config key) is pinned by a test
+  that cites its source: a file and line of the tool, or a recorded real run. A shape from memory merged once one
+  column off.
+
 ## Shell
 
 - zsh does not word-split `$FILES`: `git diff -- $FILES` with a space-separated list addresses one