@dialecte/core 0.7.0 → 0.8.0

package/skills/dialecte-contributing/SKILL.md

@@ -0,0 +1,328 @@
+---
+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>).
+license: MIT
+metadata:
+  author: dialecte
+  version: '0.1.0'
+---
+
+<!-- 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
+
+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 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), then 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.
+
+## 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. 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). `--rerun` 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. `--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.
+
+**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
+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 --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`
+   (`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.
+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, mutation testing) once per lot before hand-over,
+not after every fix. Fast targeted runs while iterating.
+
+## 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`); `--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 |
+
+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.
+- 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
+  `anthropic-skills:skill-creator` loaded with the Skill tool - 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,108 @@
+<!-- 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).
+- 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,83 @@
+<!-- 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 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.
+- **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
+
+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.

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

@@ -0,0 +1,39 @@
+<!-- dialecte-skills workspace -->
+
+# Measuring dialecte performance
+
+Measure a fresh build: after a source edit, rebuild (and refresh any consumer's copy of the build)
+before measuring, or you measure old code.
+
+## The perf helper (inside dialecte)
+
+- Enable with `dev: { perf: true }` on project creation (the consumer passes it; dialecte never
+  reads its own env).
+- Marks and measures go on the standard performance timeline as `dialecte::<layer>::<name>`
+  (`core::import::sax`, `core::store::bulkWrite`, `<dialecte>::<operation>`, ...).
+- In node/vitest use `perf.report()` - per name `{ calls, totalMs, avgMs }`. Reset with
+  `perf.reset()` once per scenario (e.g. `beforeEach`), not inside a transaction.
+- Wrap new heavy paths with the helper. Never leave ad-hoc globals or `console.time` in source.
+
+## Node bench harness (large synthetic documents, no browser)
+
+- core: `src/test/fixtures/` has a stress-fixture generator (5 MB to 500 MB, gitignored) and a
+  benchmark runner that imports the BUILT dist. Run `npm run build` first.
+- A dialecte package may ship the same pair for its schema: see its skill.
+- The runner reports per-method rows, setup timings, and the perf-helper breakdown. A coverage
+  guard fails when a public method has no bench row: a new method needs a row. Super-linear
+  counter growth means a round-trip-bound (O(n²)) path.
+- Each fixture has a wall-time ceiling so a regression fails fast instead of hanging.
+
+## In the browser
+
+- Wall time: read `performance.getEntriesByType('measure')` filtered on `dialecte::` (through
+  Playwright `page.evaluate`, in the right frame).
+- CPU self-time: the CDP `Profiler` domain (`Profiler.start` / `Profiler.stop`), ranked by
+  self-time. `console.profile()` is not readable by an agent.
+- IndexedDB `count` iterates; it is not a cheap index lookup on large tables.
+
+## 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.