@dialecte/core 0.7.0 → 0.8.1

package/skills/dialecte-contributing/SKILL.md

@@ -0,0 +1,374 @@
+---
+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), 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 -->
+
+# Dialecte (changing it)
+
+Read the `dialecte` skill first: its layer model and reuse ladder apply here even more, because
+in the repo you can see everything and are tempted to write a new primitive next to an old one.
+
+Dialecte is treated as **greenfield**: internal and public APIs may change for clarity or speed.
+When you see something that can be cleaner, faster or shared, do it in the same change rather than
+leaving a note. A **breaking** change to public API or behaviour is always allowed as an option,
+but it is proposed to the maintainer first (what breaks, why, alternatives) - never slipped in,
+never avoided out of caution.
+
+## The repos
+
+Each package is its own git repo; work with them checked out side by side (one folder,
+optionally `$DIALECTE_ROOT`).
+
+| Repo                | Role                                          | Notes                                                                                     |
+| ------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `core`              | schema-agnostic engine                        | no domain knowledge, ever; tests run on a dummy test schema                               |
+| `scl`, `nsd`, `plc` | dialecte packages                             | `src/<version>/` = generated `definition/` + hand-written config, hooks, extensions, test |
+| `create`            | XSD → definition generator + package template | Python XSD reader (via Pyodide) + TS derivation; `npm create @dialecte`                   |
+| `cli`               | `dialecte` dev CLI                            | type coverage, type bench, narrowing, readability audit                                   |
+| `playground`        | Vue/Monaco sandbox                            | run a script against a document; `DIALECTE_LOCAL=../x npm run dev`                        |
+
+All of them are **npm** projects formatted with **oxfmt**, linted with **oxlint**, tested with
+**vitest**: in core, in Node on the in-memory store, and in Playwright Chromium for the tests that
+need a browser ([Test tiers](#test-tiers)). Never run pnpm or prettier inside them.
+
+Inside a dialecte package (`src/<version>/`):
+
+```
+definition/*.generated.ts   DEFINITION, constants, types - generated by create, never hand-edited
+config/                     dialecte config, namespaces, `namespace <Name>` hydrated types
+constants/                  domain registries and literals repeated in several places
+errors/                     defineErrors catalogue, import warning catalogue
+helpers/                    pure record readers
+hooks/<hook-name>/          one sub-file per concern, merged into that hook's result
+hooks/shared/               logic shared by several hooks and by import
+hooks/io/                   two-pass import session (collect, then resolve)
+extensions/<ns>/{query,transaction}/<verb>.ts   business verbs, one per file
+extensions/<ns>/public.ts   constants/guards/types offered to consumers
+test/                       run<Name>TestCases, fixture validators
+```
+
+## Where does the change go? Decide and say it before coding
+
+Walk it top-down, stop at the first yes:
+
+1. **Does it already exist?** Run the reuse ladder from the `dialecte` skill across core AND the
+   dialecte package (grep `extensions/*/{query,transaction}/index.ts`, `hooks/*`, `hooks/shared`,
+   core `helpers/index.ts`, `utils/index.ts`). Test tooling and fixtures included.
+2. **Must it happen on every write or import, whoever writes?** → a **hook** in the dialecte
+   package (`hooks/<hook>/<concern>.ts`). Coherence (ids, names derived from references, cleanup of
+   orphans) is a hook, not a verb the caller must remember.
+3. **Is it a domain verb every consumer of this schema could use?** → an **extension** in the
+   dialecte package (`extensions/<ns>/query|transaction/<verb>.ts`).
+4. **Is it schema-agnostic engine behaviour** (traversal, mutation, IO, store, a missing hook
+   point)? → **core**. Typed against the generic record model, tested on the dummy test schema.
+5. **Only this app needs it?** → consumer code (custom extension in the app), not a dialecte change.
+
+Two smells: a domain rule in core; a query whose only job is to feed a transaction (let the
+transaction read the definition directly).
+
+**Standard vs custom rule** (for a dialecte that implements a standard): the engine implements what
+the standard says, and that is the default. A rule an expert wants that the standard does not
+require is a consumer choice (an option on the verb or a policy hook, default = the standard). A
+rule that contradicts the standard stays out of the engine (consumer override).
+
+## Reading the standard
+
+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
+   `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:
+   a test written after the code can be shaped to please it. Write the table cases (the `dialecte`
+   skill's references/testing.md); where the code does not exist yet, a stub with its real type whose body
+   throws `new Error('not implemented: <name>')`, called inside an `expect(...)` a matcher completes.
+   Remove every focus marker (`.only`, `only: true`) **before** the red: `tdd red` refuses a file holding
+   one, and removing it after would be an edit after red. Then `npx dialecte tdd red`: each new or changed
+   case must fail on an assertion (or the stub's error inside `expect`); a pass, a missing export, a type
+   or syntax error, a timeout is refused with its kind - fix the test. Then the minimum code, the test code
+   untouched (tests, helpers, fixtures, snapshots), until `npx dialecte tdd green` (test code edited after
+   its red is refused there; snapshots are never written by the run: write a snapshot test's snapshot
+   before the red). `npx dialecte tdd status` shows where each case stands. With sub-agents, the test, the
+   test review and the code are three agents (`dialecte-lot`, Station 1). Tests share a loaded machine: a
+   test owns its temporary folder, and a time bound carries slack and never counts a worker's start; a test
+   that reads the disk, spawns a process or measures time carries an explicit bound, named
+   (`SOURCE_SCAN_TIMEOUT_MS` in core's `src/test/test-timing.constants.ts`) and several times what the test
+   takes on a quiet machine; the test review and the review check that every such test has one. A suite that
+   spawns git clears the inherited `GIT_*` variables before any test (a setup file in the `setupFiles` of
+   every vitest project that runs the suite - read the config, add one when none does it), for the code
+   under test as much as for its own calls: under a commit hook in a worktree they point at the outer repository
+   ([references/traps.md](references/traps.md), Tests).
+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): `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.
+6. **Hand over** through `npx dialecte handover <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.
+
+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.
+
+- **Node by default.** Every test file runs in the `node` project, on the in-memory store, unless it is
+  declared browser-only. Iterate with `npx vitest run --project node <path>`. The files of
+  `NODE_STORE_CONTRACT_TEST_FILES` (the store contract, the IndexedDB-specific tests) run in the
+  `node-indexeddb` project instead, on fake-indexeddb: `npx vitest run --project node-indexeddb <path>`.
+  A new IndexedDB-specific test goes in that list AND in `BROWSER_ONLY_TEST_FILES` (real IndexedDB
+  once per lot).
+- **Browser only for a browser API** (`navigator.storage`, OPFS, a worker, real IndexedDB, the page's
+  `DOMParser`, the save dialog or a download link): add the file to `BROWSER_ONLY_TEST_FILES` in
+  `vitest.config.constants.ts`, `{ path, why }`, the `why` naming that API. Iterate with
+  `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 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]`
+  relying on an order the contract leaves open), fix that assertion in the test instead, with the
+  reason in a comment. Then run the file in both tiers (`--project node` and `--project browser-all`).
+- **No test names its store**: the runner's `useTestStorage` chooses (the `node` project's setup file
+  sets the in-memory store, the browser keeps the local one). See the `dialecte` skill's
+  references/testing.md for the assertions: XML text, XPath for small output, record expectations for
+  big files.
+
+## Definition of Done - every change, in the changed package
+
+Run it with `npx dialecte gate --fast` while iterating and `npx dialecte gate --full` once per lot,
+from the package root; before the branch merges, also the whole suite in the browser (step 4
+below). The gate runs each step below unfiltered and judges it on its exit code and on the counts
+the step printed (a test step that counts no test fails), prints one line per step,
+restores the generated docs the package declares after the docs build, and refuses to run while a
+hand-over script holds the repository. With `--fast`, a change that touches no test (a doc edit)
+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). `--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).
+
+Both modes run a **`tdd` step** after the hygiene: every new or changed test case holds a red receipt and a
+later green one (`dialecte tdd red` / `green`), and the test code (helpers, fixtures, snapshots included)
+is as the last red run froze it; a lot that changes no behaviour (wording, rename, docs) is declared
+exempt by the orchestrator in `.dialecte/lot.json` (`{ "tdd": "exempt: <reason>" }`, never committed),
+and the gate prints how many production and test files the change still touches.
+
+`--fast` starts with the worktree's **hygiene**: nothing staged, no stash entry pushed on this
+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.
+
+**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 "[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
+defaults. The gate, `rules`, `new verb`, `handover` and the `skills` check of step 6 come with `@dialecte/cli`
+0.2.0 or later. Read the package's pin first (`npm ls @dialecte/cli`): with an older one, every such command
+runs as `npx @dialecte/cli@^0.2.0 <command>` - never `@latest`, which can be older than 0.2.0 and lacks them -
+or the steps by hand:
+
+1. `npm run check` - type-checks sources AND tests, lint, format. Never a bare `tsc --noEmit`
+   (`tsconfig.json` is a solution file and checks nothing).
+2. `npx oxfmt <changed files>`.
+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`, 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. 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
+   older than 0.2.0 they check neither, so run `npx @dialecte/cli@^0.2.0 skills generate` and
+   `npx @dialecte/cli@^0.2.0 skills check` instead (it fails loudly while 0.2.0 is unpublished, never falls
+   back to an older cli).
+
+If public API or user-visible behaviour changed, it is not done until you also:
+
+- give every new public function or method a JSDoc whose first paragraph says what a caller gets, and an
+  `@intent` tag - comma-separated phrases naming what a caller is trying to do when they reach for it
+  (`@intent validate an exported file against its XSD, find what a document breaks`) - even when the
+  functions beside it carry none. Public means any function exported from an entry of the package's
+  `package.json` `exports` (every entry: the main one, `./utils`, `./helpers`, `./sqlite`, `./test` - other
+  packages' suites import the test entry - a dialecte's version entry) and any method reached from `project`,
+  `doc`, `doc.query` or `tx`. The skills' API index (`skills/dialecte/references/api.md`, `api.json`, what
+  `dialecte api find` answers from) is built from these two: a function without them is one the next agent
+  cannot find, and writes again. An export not meant for callers is tagged `@internal` instead and stays out
+  of the index;
+- update the `doc/` page that describes that surface (types, verbs, contracts),
+- add a line under `## UNRELEASED` in the package's `CHANGELOG.md`, written for the user, and
+- update the package's `skills/` when the change touches what a skill describes (API, hooks,
+  extensions, scripts, layout, rules); `npm run skills:generate` refreshes the generated tables, and the
+  check runs in the gate (step 6).
+
+Type performance: `npm run type-bench:check` compares type instantiations with
+`benchmarks/types/baseline.json` (one per version folder in a dialecte package:
+`benchmarks/types/<version>/baseline.json`; 5 % gate). A breach is a **think point**, not a wall: measure
+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) 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
+
+A dialecte package depends on a **published** core version (an installed copy, not a symlink). A
+core change is invisible to the package until you: build core → put its build where the package
+resolves it (`npm install ../core` in the package, a symlink
+`<package>/node_modules/@dialecte/core -> ../../../core`, or a copied `dist/`) → delete the package's
+`node_modules/.vite` (vitest pre-bundles deps and keeps the old core). Before committing, the
+package must depend on a released core version again; never commit the link. Release order: core
+first, then the packages that pin it, each with its own bump lot.
+
+## Verification traps (false greens)
+
+Read [references/traps.md](references/traps.md) before trusting any gate output. The short list:
+solution tsconfig checks nothing; tests have their own tsconfig; stale `.vite` cache after a core
+swap; output-compacting shell wrappers can turn a failing gate into "ok" (run verdict gates raw and
+read the counts); a doc build can rewrite a generated data file (restore it before the hand-over
+script is written); before `@dialecte/cli` 0.2.0, `dialecte bench --help` runs the
+bench and writes the baseline; a test that passes on its first run may be green by accident.
+
+## Skills ship with the code
+
+Each package carries the skills that describe it in `skills/<name>/` (published in its npm tarball):
+core has `dialecte`, `dialecte-contributing` and `dialecte-lot`, create `dialecte-create`, and every dialecte
+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`); 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
+`<!-- dialecte-skills ignore: token -->`.
+
+## Performance work
+
+Measure, don't guess: [references/perf.md](references/perf.md) (perf helper, node bench harness,
+browser timeline, CPU profile). Classic regressions to avoid in review: per-element ancestor walks,
+per-element queries without a cache, re-reading the same records in several passes, store reads
+during import (import is in-memory two-pass by design, see the hooks rules in the `dialecte` skill).
+
+## Never
+
+- Edit a `*.generated.ts` file (regenerate with `dialecte-create`).
+- 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
+
+List in your hand-over every place where this skill was wrong, missing or misleading for the task,
+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
+  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.
+  Post it only with their approval.
+- Nothing to report: write "skill retro: nothing".

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

@@ -0,0 +1,115 @@
+<!-- dialecte-skills workspace -->
+
+# Code rules for dialecte repos
+
+These are review-blocking. Each has a reason; the reason tells you what to do in a case the rule
+does not name.
+
+## Contents
+
+- Reuse and sources of truth
+- Function shape
+- Files and types
+- Naming
+- Comments and committed text
+- Self-check before hand-over
+
+## Reuse and sources of truth
+
+- **Search before every helper**, test tooling included. Grep the concern in
+  `extensions/*/{query,transaction}/index.ts`, `hooks/*`, `hooks/shared/`, core `helpers/` and
+  `utils/`. When you add a function, be ready to name the existing method that could replace it
+  and why it does not fit.
+- **No new source of truth.** Before declaring a list (`const X = [...] as const`) look for it in
+  the definition (`ATTRIBUTES`, `CHILDREN`, `PARENTS`, identity fields, keyrefs) or in a registry
+  (its keys, its `target` tags). Declare only what neither knows, and declare it once: types derived
+  from the runtime list. A table that repeats registry content drifts silently.
+- **Read derived views at the use site** instead of copying them; never `const LOCAL = GLOBAL` just
+  to rename.
+- **Repeated literals and tag sets** go to the package `constants/` and are imported everywhere;
+  derive the union type with `(typeof LIST)[number]`.
+- **Use Dialecte's attribute API**: `query.getAttributes(ref)` / `getAttribute(ref, { name })`, or
+  `readAttribute(s)` without a query. No `record.attributes.find(...)` helpers.
+- **Accept a `query` / `tx`** in domain functions so they reuse the primitives, rather than taking
+  pre-fetched data and re-implementing lookups.
+
+## Function shape
+
+- **Object parameters.** `fn(query, { targetParent, tagName, matchKey })`, not positional. The only
+  thing outside the object is a leading `query` / `tx`. A positional signature (a single obvious
+  `ref`, a symmetric `equals(a, b)`) is discussed with the maintainer first.
+- **Named `function` declarations**, also for local helpers. Arrows only for tiny inline callbacks
+  (`.map`, `.filter`, `.some`). A closure over a local value becomes a module-level named function
+  taking that value as a parameter.
+- **No `await` nested in an argument.** `const instances = await findInstances(query, {...})`,
+  then pass `instances`.
+- **Immutable, explicit.** Return new values, no hidden state, no mutation of records you received.
+- **Never `any`.** Use the `Any*` core types (`AnyDialecteConfig`, `AnyRawRecord`, ...) in core, the
+  hydrated domain types (`<Name>.*`) in a dialecte package. Narrow types as far as they go.
+- **Extension methods** take `Core.Query<Config>` / `Core.Transaction<Config>` as first parameter
+  (not the hydrated `<Name>.Query`: type cycle). A sibling is called by import, passing the same
+  query. A helper not exported from the folder's `index.ts` is not a method.
+
+## Files and types
+
+- **One function per file**, test co-located: `<name>.ts`, `<name>.test.ts`.
+- **Types live in `<name>.types.ts`** next to the code - never exported or domain types inline in
+  the implementation file. Exception: no `.types.ts` for a one-line alias that just renames an
+  existing type; use the underlying type directly.
+- **Module constants live in `<name>.constants.ts`** (or the extension's `constants/`).
+- **Group by domain, not by technical layer.** Types folders hold only definitions.
+- **Zero runtime cost** for type machinery; watch the type bench when adding generic types.
+
+## Naming
+
+- Full, readable camelCase words: `attribute`, not `attr`; `(attribute) => attribute.name`, not
+  `(a) => a.name`. Existing API names like `ref` are fine; your own variables say what they are.
+
+## Comments and committed text
+
+- Explain the behaviour so the comment stands on its own; a reader without your plan or ticket
+  must understand it.
+- **No plan, lot, phase, ticket or acceptance-criterion tags** (a step id, a lot number, an
+  acceptance-criterion id, an issue number) in code, comments, tests, docs, CHANGELOG or commit messages. They belong in plans and PR
+  descriptions.
+- **No citations of a standard** (a document name with a clause, table, annex or section number)
+  in any committed file, commit message, issue, PR or
+  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.
+
+## Self-check before hand-over
+
+```bash
+npx dialecte rules              # the files changed against HEAD and the new ones
+npx dialecte rules <files...>   # or the files you name; --json for a program
+```
+
+It reads each file's syntax tree, not lines: an exported type outside a `*.types.ts` file, a module
+constant outside a `*.constants.ts` file, a function declared as a `const`, an `await` inside an
+argument, a plan or ticket tag or a standard citation (the package's own patterns included) are
+errors; positional parameters beyond a leading `query` / `tx` and abbreviated names are warnings. Fix
+every error; answer every warning (fix it, or say in the hand-over why the shape is right). It exits 1
+on an error. A finding that is wrong is a cli bug: report it, do not work around it.
+
+`rules` comes with `@dialecte/cli` 0.2.0 or later. Without it, the same checks as greps (not
+tests/types/constants files for the first two); the last two mirror the patterns `rules` and
+`handover` share (the cli's committed-text constants):
+
+```bash
+grep -nE '^(export )?type [A-Z]|^(export )?interface ' <impl files>    # inline types?
+grep -nE '^const [A-Z_]+ ' <impl files>                                # module constants outside *.constants.ts?
+grep -nE 'const [a-zA-Z]+ = (async )?\(' <files>                       # arrow-function declarations?
+grep -nE '\((await |.*, await )' <files>                               # await inside an argument?
+grep -nE '\blot [A-Z0-9]|\bAC[0-9]|#[0-9]{3,}\b' <files>               # plan / ticket tags?
+grep -nE '§ ?[0-9]|Tables? [0-9]|Annex [A-Z]|[Cc]lause [0-9]' <files>  # standard citations? (a dialecte's skill adds its standard's names)
+```

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

@@ -0,0 +1,87 @@
+<!-- dialecte-skills workspace -->
+
+# Landing a change: commit-by-lots, human runs it
+
+The agent prepares; a human reviews and commits. The agent never runs `git commit`, never pushes,
+and never touches a repo's index (`git add`, `git checkout --`, `git stash`) while a hand-over
+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
+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):
+
+```json
+{
+	"repository": "/absolute/path/to/the/repository",
+	"branch": "feat/the-branch",
+	"head": "<sha the lots go on top of>",
+	"gates": "the gate lines, one line, with their real counts",
+	"lots": [
+		{ "paths": ["src/feature/"], "message": "feat(scope): the behaviour\n\nThe body." },
+		{ "paths": ["CHANGELOG.md"], "message": "docs(changelog): the behaviour" }
+	]
+}
+```
+
+- **Lots**: paths are files, or folders ending with `/`. Every lot is build-safe on its own (compiles,
+  tests green) and does not reference a later lot. Typical order: types/constants → implementation +
+  tests → docs → CHANGELOG → bench re-baseline (own lot) → release bump (own lot).
+- **A branch lands on main through a merge lot**, in a lots file whose `repository` is the main checkout:
+  `{ "kind": "merge", "branch": "<branch>", "tip": "<sha>", "resolved": {}, "message": "merge: ..." }` -
+  a merge commit, never a fast-forward. `resolved` maps each conflicting path to the file holding its
+  resolution (`null` removes it). The run needs the merge's `tree`, which the rehearsal prints (`tree <sha>`):
+  copy it into the lot as `"tree"`, then `--rehash`.
+- **Never in a lot**: generated docs data (`.vitepress/data/*`), lockfiles and version bumps (unless
+  the lot is the release lot), local links to sibling repos. Restore them before the hand-over
+  (`git checkout -- <file>` while no hand-over waits): a changed file in no lot makes `handover` refuse.
+- **Interrupted?** A run stopped after staging a lot is refused at its next start with the command that
+  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, 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
+  every lot is committed.
+- **The run** prints each guard with its result and time, then `lot n/N`, the hook's output behind `│`
+  with a heartbeat while it is silent, each commit with its stat, and the card at the end; it never
+  pushes. A lot whose commit fails is unstaged again; the same command resumes after the lots already
+  committed.
+- **Rehearse** when the repository has a commit hook: `npx dialecte handover run <folder> --rehearse`
+  commits the lots in a scratch clone holding the working tree, the hooks folder and a copy of
+  `node_modules`, then removes it (`--keep` keeps it). From cli 0.2.0 it rehearses only what can find
+  something new and prints why per lot. A plain lot is not rehearsed when its exact tree has a green
+  `gate --full` (same lock, linked dependencies and command), the lot leaves the lock alone and the hook
+  stages no files. A merge is not rehearsed when its tree is its branch tip's (main has not moved), the
+  tip's tree has a green record (the branch commit's hook or a `gate --full`) and the merge leaves the lock
+  alone; it still prints the merge's `tree <sha>`. Anything else is rehearsed: a merge onto a moved main, a
+  lock change, a hook that stages files. Paste the per-lot lines with the card; `--full` forces every lot
+  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>`.
+- `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).
+
+## Commit messages
+
+Conventional style (`feat(scope): ...`, `fix`, `docs`, `chore(bench)`, `chore(release)`), written
+as the behaviour for a reader of the history. No plan/ticket tags, no standard citations.
+
+## Hand-over message
+
+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.