@dialecte/core 0.8.0 → 0.9.0

package/skills/dialecte-lot/SKILL.md

@@ -1,10 +1,11 @@
 ---
 name: dialecte-lot
-description: Deliver one lot of a Dialecte change (core, a dialecte package, create, cli) as a small pipeline of stations - orchestrate, implement red-first, gate, review independently, fix, hand over, retro - alone or with sub-agents. It gives the orchestrator's brief template, the implementer's and reviewer's report shapes, the review passes, the loop cap, when a skill change goes through skill-creator evals, and how findings become skill improvements. Use it whenever a Dialecte change is bigger than a one-file fix, when you split work between agents (implementer, reviewer), when the user asks for TDD with a review loop, a commit-by-lots hand-over, or a retro, even if they do not name the stations. Load dialecte-contributing (gates, code rules) and dialecte (the API) with it.
+description: Deliver one lot of Dialecte-scoped work as stations - test station red, test review, green, review rounds with a findings ledger, the gates, a hand-over a human runs - alone or with sub-agents, with the brief template, the report shapes and the loop cap. In a dialecte package (core, a dialecte, create, cli): whenever a change is bigger than a one-file fix, or the user asks for TDD with a review loop, a commit-by-lots hand-over or a retro. In an app built on a dialecte: whenever the task changes its Dialecte-scoped code - its local dialecte extension (a verb, a query, a hook), a service or composable that calls @dialecte/* APIs, an extension delivered for promotion - even when nobody asks for a lot, TDD or a review: run it yourself as a sub-loop over that part only, handing back to the app's process at the hand-over. Not for the rest of an app (UI, layout, styling, component renames, reviewing a UI change). Load dialecte with it, and in a dialecte package dialecte-contributing too.
 license: MIT
 metadata:
   author: dialecte
   version: '0.1.0'
+  audience: consumer
 ---
 
 <!-- dialecte-skills workspace -->
@@ -20,20 +21,40 @@ compare runs.
 **Memory is the artifacts, not the chat.** The plan file, the station reports, the diff and the retro log
 are what the next station reads. A decision that is not in one of them was not a decision.
 
+**In a dialecte package** (`"dialecte": { "profile": "contributor" }` in its `package.json`), load
+`dialecte-contributing` too: its `references/lot-in-a-package.md` adds the package's own steps to these stations -
+the mutation switch, `dialecte rules`, `dialecte contrib` before the hand-over, the landing rules and merge lots.
+**In an app**, none of them. There a lot is a sub-loop the app's agent runs by itself for the Dialecte-scoped
+part of a task only - the local dialecte extension, the services and composables that call `@dialecte/*` APIs, an
+extension meant for promotion: the same stations, ending at the hand-over (Station 6), then back to the app's own
+pipeline, which carries on with its own steps and its pull request. The rest of the app's change (its UI, layout,
+styling) stays under the app's process and never enters the lot. An extension meant for promotion is delivered to
+the package's bar (node-tier tests, the JSDoc of every public function, its docs), so that promoting it moves the
+folder and rewrites nothing.
+
 ## The stations
 
-| #   | Station     | Who                         | Tier                                                        | Reads                                                                                                | Leaves                                                                                                       |
-| --- | ----------- | --------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| 0   | Orchestrate | orchestrator                | strong                                                      | the plan, the user's decisions                                                                       | one brief per implementer (template in [references/briefs.md](references/briefs.md))                         |
-| 1a  | Test        | test station (own agent)    | standard                                                    | its brief step, the existing code                                                                    | tests + stubs, proven red by `dialecte tdd red` (its receipts)                                               |
-| 1b  | Test review | **a different agent**       | strong                                                      | the tests of the step, the brief                                                                     | a verdict on the tests, before any code                                                                      |
-| 1c  | Implement   | implementer (another agent) | standard or strong, by lot kind                             | its brief, the tests, the code it changes                                                            | production code until `dialecte tdd green`; an implement report                                              |
-| 2   | Fast gate   | implementer                 | no agent                                                    | -                                                                                                    | `dialecte gate --fast` + `dialecte rules`: type-check, lint, format, touched tests, skills check, code rules |
-| 3   | Review      | **a different agent**       | strong, both passes                                         | the brief, the diff, the previous version (`git show <base>:<file>`), the rules, the findings ledger | a review report: pass 1 correctness, pass 2 fit, verdict; proposed findings-ledger rows                      |
-| 4   | Fix         | the implementer, fix mode   | standard for wording or naming, else the implementer's tier | the findings                                                                                         | each finding fixed, disagreed (one line why) or escalated                                                    |
-| 5   | Full gate   | implementer                 | no agent                                                    | -                                                                                                    | `dialecte gate --full`: the package's full Definition of Done, once per lot                                  |
-| 6   | Hand over   | implementer or orchestrator | no agent                                                    | the lot's files                                                                                      | `dialecte handover`: a hand-over folder and its card; a human runs it; nothing committed, nothing pushed     |
-| 7   | Retro       | orchestrator                | strong                                                      | reports, loops, the user's corrections                                                               | retro entries; skill edits drafted, applied on approval                                                      |
+| #   | Station     | Who                         | Tier                                                        | Reads                                                                                                | Leaves                                                                                                   |
+| --- | ----------- | --------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| 0   | Orchestrate | orchestrator                | strong                                                      | the plan, the user's decisions                                                                       | one brief per implementer (template in [references/briefs.md](references/briefs.md))                     |
+| 1a  | Test        | test station (own agent)    | standard                                                    | its brief step, the existing code                                                                    | tests + stubs, proven red by `dialecte tdd red` (its receipts)                                           |
+| 1b  | Test review | **a different agent**       | strong                                                      | the tests of the step, the brief                                                                     | a verdict on the tests, before any code                                                                  |
+| 1c  | Implement   | implementer (another agent) | standard or strong, by lot kind                             | its brief, the tests, the code it changes                                                            | production code until `dialecte tdd green`; an implement report                                          |
+| 2   | Fast gate   | implementer                 | no agent                                                    | -                                                                                                    | `dialecte gate --fast`: type-check, lint, format, touched tests, skills check                            |
+| 3   | Review      | **a different agent**       | strong, both passes                                         | the brief, the diff, the previous version (`git show <base>:<file>`), the rules, the findings ledger | a review report: pass 1 correctness, pass 2 fit, verdict; proposed findings-ledger rows                  |
+| 4   | Fix         | the implementer, fix mode   | standard for wording or naming, else the implementer's tier | the findings                                                                                         | each finding fixed, disagreed (one line why) or escalated                                                |
+| 5   | Full gate   | implementer                 | no agent                                                    | -                                                                                                    | `dialecte gate --full`: the package's full Definition of Done, once per lot                              |
+| 6   | Hand over   | implementer or orchestrator | no agent                                                    | the lot's files                                                                                      | `dialecte handover`: a hand-over folder and its card; a human runs it; nothing committed, nothing pushed |
+| 7   | Retro       | orchestrator                | strong                                                      | reports, loops, the user's corrections                                                               | retro entries; skill edits drafted, applied on approval                                                  |
+
+**After the hand-over, the pull request is the repository's own.** In a dialecte repository Station 7
+follows the hand-over, and the branch goes up by pull request through that repository's landing rules
+(`dialecte-contributing`). In an app that consumes a dialecte, the lot ends at
+Station 6: what comes after belongs to the app's own process - its PR skill and template for the pull
+request, its own retro and clean-up if it has them - and no further station of this skill runs (no Station 7,
+no `dialecte worktree prune`, no dialecte PR or release step). The hand-over's records (`dialecte recap`
+prints a PR's details part from them) feed the app's template only where its rules ask for it. Pushing and
+posting stay the user's (or wait for their approval).
 
 The Tier column names the kind of model a station runs on, never a model: the tiers, the rules that go with
 them (escalate one tier after a failed round, never down-tier a correctness review, effort as a second knob)
@@ -46,12 +67,24 @@ the orchestrator's: a finding the last round acts on is fixed, then the fix and
 decides whether one more round checks it. Findings that keep coming past the cap mean the plan or the brief is
 wrong.
 
+## Station 0 - what the plan and the brief settle
+
+Before the test station, the plan holds what the tests will pin; a gap found by a reviewer costs a round.
+
+- **The standard** (a lot whose rules come from a standard the code implements):
+  [references/standard-check.md](references/standard-check.md) - how it is read, the cross-check for a
+  decision, and what the station records for the hand-over card (`dialecte record standard`).
+- **A tooling lot with shared state or an external tool**: the plan carries the store's transition table, its
+  invariant and the interleavings, the test-station brief asks one forced-order test per interleaving, and the
+  hand-over folder gets a `SMOKE.md` with the lot's one real run; how and where that run happens, and citing
+  third-party values: in a dialecte package, `dialecte-contributing` references/traps.md, Tools with shared state.
+
 ## Station 1 - test, test review, implement (per brief step)
 
 The order matters, not only the outcome: a test written after the code can be shaped to please it. So each
 step of the brief (3-6 behaviours) goes through three agents, and the cli keeps the receipts:
 
-1. **Test station** (own agent, `standard`; `dialecte-test-writer` in Claude Code). Reads the brief step and
+1. **Test station** (own agent, `standard`; station `test-writer`). Reads the brief step and
    the existing code only. Writes the step's tests from the spec and, where the code does not exist yet,
    stubs with their real types whose body throws `new Error('not implemented: <name>')`; each test calls
    the code under test inside an `expect(...)` that a matcher completes (`expect(x).toBe(...)`; a bare
@@ -66,12 +99,12 @@ step of the brief (3-6 behaviours) goes through three agents, and the cli keeps
    a refusal; a changed helper, fixture or snapshot is frozen only by a red of a file that depends on it
    (imports it - relative, tsconfig `paths` or vite alias, through barrels - names it, or owns the snapshot;
    an import that looks local and resolves nowhere refuses the file). Its report is the `tdd red` output.
-2. **Test review** (a different agent, `strong`, read-only; `dialecte-test-reviewer`). Reads only the tests
+2. **Test review** (a different agent, `strong`, read-only; station `test-reviewer`). Reads only the tests
    against the spec, before any code - the changed helpers, fixtures and snapshots too: does each pin a
    behaviour of the brief, would a plausible wrong implementation fail it, does every `expect(...)` have a
    matcher, is a behaviour of the step left without a test. Verdict: approve, or back to the test station
    with the findings (which runs `tdd red` again).
-3. **Implement station** (another agent: `dialecte-implementer`, or `-strong` by lot kind). Changes
+3. **Implement station** (another agent: station `implementer`, or `implementer-strong` by lot kind). Changes
    production code only, until `npx dialecte tdd green` passes: every case of the step with its red
    receipt, its test code as the last red run froze it, production changed since its red, and green. A
    test it finds wrong goes **back to the test station with the reason** (through the orchestrator): it
@@ -119,7 +152,7 @@ Before touching code (the implement station; the test station does the same befo
    can assume things that changed. A contradiction stops you: say it, do not reinterpret the plan.
 2. `git status -sb` in your worktree: right branch, clean (or dirty only with your own earlier work).
    Note the HEAD sha for your report.
-3. Load `dialecte` and `dialecte-contributing`; run the reuse ladder before writing anything.
+3. Load `dialecte` (and `dialecte-contributing` in a dialecte package); run the reuse ladder before writing anything.
 
 Then, within the step:
 
@@ -131,7 +164,8 @@ Then, within the step:
 - Only the lot's scope. A refactor outside it is a new lot, said out loud.
 
 A **skill text change** is code too: when the lot changes what a skill tells agents to do (a new command to
-run, a rule), load `anthropic-skills:skill-creator` with the Skill tool and follow it. A skill change judged
+run, a rule), load the skill-creator skill (`anthropic-skills:skill-creator`) and follow it; a host without it
+runs the same loop by hand, as below. A skill change judged
 by hand, or by the agent that wrote it, looks green on one run and its own reading; skill-creator's loop is
 what shows the change moves behaviour. As it applies here: the eval case under the skill's `evals/` first
 (it describes the behaviour the new text must produce; the text before the change fails it); runs with the
@@ -148,7 +182,7 @@ Base: <branch> @ <sha>
 Files: <list>
 Tests: <n> passing of <m> table cases - command: <the exact command, unfiltered>
 Red seen: <the `tdd red` line of each case: case, kind, failing message>   (one line per behaviour)
-Gates: <the lines `dialecte gate` printed, with their counts>; rules <n errors, m warnings>
+Gates: <the lines `dialecte gate` printed, with their counts>
 Skill evals: <case: pass rate with / before, runs per configuration; benchmark and viewer paths>   | n/a
 Deviations from the brief: <none | what and why>
 Open questions: <none | ...>
@@ -156,10 +190,12 @@ Open questions: <none | ...>
 
 ## Station 2 - fast gate (the counts decide, not the summary)
 
-Run `npx dialecte gate --fast --declare <new path>` and `npx dialecte rules` from the package root. The gate
+Run `npx dialecte gate --fast --declare <new path>` from the package root; in a dialecte package, run
+`npx dialecte rules` with it and fix its errors before the review (`dialecte-contributing`
+references/lot-in-a-package.md, Station 2). The gate
 starts with the worktree's hygiene (nothing staged, the stash as it was when the worktree was made, every new
 file declared: one `--declare` per new file or folder of the lot), then runs each step unfiltered and prints
-one line per step with the counts the step itself printed; paste those lines in the report. Fix every `rules` error before the review. The bullets below are what the gate checks for
+one line per step with the counts the step itself printed; paste those lines in the report. The bullets below are what the gate checks for
 you, and what you check by hand with a cli older than 0.2.0:
 
 - Run every command that decides a gate **unfiltered**: an output-compacting shell wrapper can print a green
@@ -179,7 +215,8 @@ listing them: the missing receipts go back to the test station (no red) or the i
 
 The reviewer did not write the code and does not take the implementer's report as truth. Read-only.
 Inputs: the brief (the spec), the diff of the lot's files, the previous version of each file, the rules
-(`dialecte-contributing` code rules and Definition of Done, `dialecte` reuse ladder).
+(the repository's code rules and Definition of Done - `dialecte-contributing` in a dialecte package -,
+`dialecte` reuse ladder).
 
 **Pass 1 - correctness** (always first): logic, edge cases, async and error handling, a behaviour changed
 without a test, a test that passes for the wrong reason (weak assertion, a matcher that ignores what the
@@ -344,7 +381,7 @@ it from a test-first red (it flags `red after green` only when the case already
 
 ## Station 6 - hand over
 
-The `dialecte-contributing` landing rules apply. Write only the lots file and run `npx dialecte handover
+Write only the lots file and run `npx dialecte handover
 <lots.json>`: it writes the hand-over folder and prints its card. Never a hand-written script, nor a file per
 commit. When the repository has a commit hook (`core.hooksPath`), rehearse first with `npx dialecte handover
 run <folder> --rehearse`: a scratch clone holding your tree, the hooks folder and `node_modules`, so the hook
@@ -359,22 +396,20 @@ commit, merge rehearsal, merge commit). So:
 
 - A second `gate` of the same mode on an unchanged tree runs its hygiene and `tdd` step (they read the worktree,
   not the tree), then answers the rest from its record (`reused: gate --full green on this tree ...`). Run it when
-  you want its lines; never `--rerun` "to be safe": an edit, a lock, a linked dependency already make a new key.
-  `--rerun` is for when the person asks, or when something outside the key changed (a machine fault you suspect).
-- `handover run --rehearse` decides per lot and prints why (the rules: `dialecte-contributing`
-  references/landing-changes.md). Paste those lines with the card; never add `--full` to force a rehearsal the cli
+  you want its lines; never `--no-reuse` "to be safe": an edit, a lock, a linked dependency already make a new key.
+  `--no-reuse` is for when the person asks, or when something outside the key changed (a machine fault you suspect).
+- `handover run --rehearse` decides per lot and prints why (in a dialecte package, its rules are in
+  `dialecte-contributing` references/landing-changes.md). Paste those lines with the card; never add `--full` to force a rehearsal the cli
   skipped, and start no load for it. A lot it does rehearse runs under load as above.
-- 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.
 - The real commit's hook always runs, whatever the records say: it is the person's last net. Nothing passes
   `--no-verify`.
 
-The hand-over message to the user **is the card** `handover` printed - repository, worktree, branch, HEAD,
-gates, the lots with their files and messages, and the command with its absolute `cd` - pasted as printed,
-never retyped. After it: what was not verified, and one usage line (the lot's sub-agent tokens, in total
+**Reporting READY.** From cli 0.3.1 the message to the user points at the hand-over instead of carrying it:
+`READY`, then `cd <worktree> && npx dialecte handover show <name>` (the card recomputed read-only from the
+records, current whenever the person reads it) and `npx dialecte handover run <name>` (the command they run) -
+never a pasted or retyped card, which goes stale as soon as a record changes. With an older cli, the message
+**is the card** `handover` printed - repository, worktree, branch, HEAD, gates, the lots with their files and
+messages, and the command with its absolute `cd` - pasted as printed, never retyped. After it: what was not verified, and one usage line (the lot's sub-agent tokens, in total
 and by station: [references/retro.md](references/retro.md)). A refusal is a finding: fix the file or the
 message, do not loosen the lots. `npx dialecte handover list` shows every hand-over waiting on the machine.
 Never commit, push, stage, or touch a repository's index while a hand-over may be waiting.
@@ -402,21 +437,26 @@ that is rewritten every retro never settles.
 - Write each brief from [references/briefs.md](references/briefs.md): the brief is the agent's whole
   context; synthesise, do not say "based on the findings". Every brief carries its lines for all stations
   (nothing under `.git` by hand, no workflow without the user's opt-in, no `rm` on a variable path).
-- Spawn the station's own agent when the host has it: Claude Code with `.claude/agents/dialecte-<station>.md`
-  (written by `npx @dialecte/cli skills sync`: `dialecte-test-writer`, `dialecte-test-reviewer`,
-  `dialecte-implementer`, `dialecte-implementer-strong`, `dialecte-reviewer`, `dialecte-fixer`,
-  `dialecte-eval-runner`, `dialecte-grader`, `dialecte-standard-reader`, `dialecte-searcher`). The test
-  writer edits tests and stubs; the test reviewer reads; the implementer keeps every edit tool, the freeze
-  of the tests is `tdd green`'s and the gate's. The file sets the model and the tools (the reviewer cannot
-  edit files), so the spawn names neither. Without the file, spawn a general sub-agent on the tier its brief
-  names ([references/model-tiers.md](references/model-tiers.md)). Note the tokens of each completion notice
+- Each station agent is defined once, for every host, in [references/stations.md](references/stations.md):
+  its tier, its access (`read`, `review`: runs commands but edits nothing, `edit`) and its role (`test-writer`,
+  `test-reviewer`, `implementer`, `implementer-strong`, `reviewer`, `fixer`, `eval-runner`, `grader`,
+  `standard-reader`, `searcher`). The test writer edits tests and stubs; the test reviewer reads; the
+  implementer keeps every edit tool, the freeze of the tests is `tdd green`'s and the gate's. A host with an
+  adapter spawns the station's own agent, whose file sets the model and the tools, so the spawn names neither
+  (Per host, below). Without one, spawn a general sub-agent on the station's tier
+  ([references/model-tiers.md](references/model-tiers.md)), restricted to its access, its prompt holding the
+  station's section before the brief. Note the tokens of each completion notice
   against its station as it lands: the ledger the retro and the hand-over message report. When a station
   runs well above the lot's other stations, tell the user then, not at the end.
 - Spawn the reviewer only after the implementer's report; give it the brief, not the implementer's
   conclusions. You review too: read the diff yourself before accepting a verdict.
-- Heavy runs share one machine: one browser test suite at a time (`--no-file-parallelism`), low
-  concurrency for mutation tests. `gate --full` and the heavy gate steps (any test step of a package that
-  runs its tests in a browser) hold a machine-wide lock: a second one waits, naming the holder.
+- Runs use the runner's defaults, whoever else shares the machine: no `nice`, no worker cap added on the
+  command line (a config's own setting, such as mutation tests' measured concurrency, is the runner's default), no
+  `--no-file-parallelism`, no lock - unless the user asks to limit, for the time they say. A failing run is rerun
+  once, the same command with its `--project` flags, on its failing files with `--no-file-parallelism` (the gate
+  does it on its test steps): a pass
+  there is a flake, a finding fixed at its cause, never a reason to throttle; a failure there is real
+  (in a dialecte package, `dialecte-contributing`, Definition of Done).
 - After the user merged: `npx dialecte worktree prune` lists the merged worktrees and branches, the
   committed hand-over folders and the rehearsal clones, each with its command (a worktree just made, one
   holding ignored files, an unmerged branch are kept, with why). `--yes` asks for a confirmation on a
@@ -433,9 +473,9 @@ orchestrator launches in the background gets a **deadline** when it is launched:
 - **How long**: the station's deadline ([references/model-tiers.md](references/model-tiers.md)), or three
   times a duration measured on earlier runs of the same command (a commit hook, a gate, a bench: a hook that
   took 6 minutes gets 18). Write it in the run log.
-- **Armed at launch**: in Claude Code, arm the check in the same turn as the launch - a scheduled check or
-  a wake-up at the deadline, or a monitor on the run's log - so you are woken even if no notice comes. A host
-  without one polls at the deadline.
+- **Armed at launch**: arm the check in the same turn as the launch, with whatever the host has that wakes
+  you - a scheduled check or a wake-up at the deadline, or a monitor on the run's log - so you are woken even
+  if no notice comes. A host with none polls at the deadline.
 - **At the deadline, look at the run itself**: its process tree (`pgrep -P <pid>`, `ps -o pid,stat,time,command`:
   is its CPU time growing?), the agent's last activity or the log's last line and its time, and `dialecte runs`
   once the cli has it (the live runs of the machine, each with its state).
@@ -447,6 +487,20 @@ orchestrator launches in the background gets a **deadline** when it is launched:
   Under `dialecte handover run`, `gate` and `tdd`, the runner's own stall watchdog does the kill; your
   deadline is the backstop that notices a runner that did not.
 
+## Per host
+
+The stations, gates and hand-over are the same everywhere: they run through the `dialecte` cli and the git
+hooks. What differs is how a host starts a session, spawns an agent and wakes you:
+
+- **Every host**: the session starts with `npx --no-install @dialecte/cli doctor --brief` (the synced `AGENTS.md`
+  section says so; where a hook already ran it, its lines are in your context): nothing printed means the skills
+  are in sync, else fix each line first. Station agents come from references/stations.md.
+- **Claude Code**: a `SessionStart` hook runs that check for you (do not run it again); `.claude/agents/dialecte-<station>.md` are the
+  station adapters (the Agent tool spawns them by name); skills load with the Skill tool; the Workflow tool is
+  the multi-agent workflow that needs the user's opt-in; a scheduled wake-up or a monitor arms a deadline.
+- **Another host** (Codex, Cursor, Gemini CLI, Copilot): skills in `.agents/skills/` (or `.github/skills/`); a
+  general sub-agent per station, as above; its own scheduler or a timer arms a deadline, else poll at it.
+
 ## Never
 
 - Skip the red step (`tdd red` from the test station), the test review, the review, or the cap.
@@ -461,8 +515,9 @@ orchestrator launches in the background gets a **deadline** when it is launched:
   lock or a broken config stops that step: read it (`ls`, `cat`), then hand it to the orchestrator - its path,
   what you believe wrote it, the refused command; the orchestrator (or an agent playing every station) takes it
   to the user. The same for the hand-over script a lock names. Every station, every agent.
-- Start a multi-agent workflow (Claude Code's Workflow tool) without the user's explicit opt-in: each sub-agent
-  has its own spawn (Claude Code: the Agent tool), several at once when they are independent, eval runs included.
+- Start a multi-agent workflow (a host tool that fans out many agents from one script) without the user's
+  explicit opt-in: each sub-agent has its own spawn, several at once when they are independent, eval runs
+  included.
 - `rm`, `mv` or `xargs` on a variable path: leave temporary files in the hand-over folder or the scratchpad.
 - Wait on a background run with no deadline, or on its completion notice alone.
 - Hand over a hand-written commit or merge script.

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

@@ -11,8 +11,8 @@ Every brief, whatever the station, carries these lines (the templates below assu
 Never edit, move or remove a file under a repository's .git folder (a lock, a config, a receipt), even one
   your own run left, even when a refusal says to delete it: a stuck lock or config stops the step - read it,
   report its path, what you believe wrote it and the refused command to the orchestrator.
-No multi-agent workflow (Claude Code's Workflow tool) unless the user opted in; a sub-agent of yours has its
-  own spawn (Claude Code: the Agent tool). No rm, mv or xargs on a variable path: leave temporary files in the
+No multi-agent workflow (a host tool that fans out many agents at once) unless the user opted in; a sub-agent
+  of yours has its own spawn. No rm, mv or xargs on a variable path: leave temporary files in the
   hand-over folder or the scratchpad.
 ```
 
@@ -20,7 +20,7 @@ No multi-agent workflow (Claude Code's Workflow tool) unless the user opted in;
 
 ```
 You are the test station (Station 1a of the dialecte-lot skill) of step <n> of lot <id> (<plan path>).
-Tier: standard (model-tiers.md; `npx @dialecte/cli models` says which model). Claude Code: dialecte-test-writer.
+Tier: standard (model-tiers.md; `npx @dialecte/cli models` says which model). Station: test-writer (references/stations.md).
 
 Step: <the 3-6 behaviours of the step, as case keys "<state> → <outcome>">
 Spec: <the plan section(s), by path and heading; the decisions that bind it>
@@ -44,7 +44,7 @@ Report: the `tdd red` output, unfiltered, and the list of stubs.
 ```
 You review the tests (Station 1b of the dialecte-lot skill) of step <n> of lot <id>, before any code.
 Read-only: modify nothing; `npx dialecte tdd status` is the one command to run.
-Tier: strong - never lower. Claude Code: dialecte-test-reviewer.
+Tier: strong - never lower. Station: test-reviewer (references/stations.md).
 
 Spec: <plan path + sections>; the step: <the behaviours>.
 Read: the test code of the step - test files, and the helpers, fixtures and snapshots they changed
@@ -63,6 +63,7 @@ Verdict: approve | back to the test station with the findings. Max ~50 lines, fi
 
 ```
 You implement lot <id> of <plan path>, as the implement station of the dialecte-lot skill.
+Station: implementer | implementer-strong (references/stations.md).
 Tier: <standard for a mechanical or fully specified lot | strong for a design-heavy one> (model-tiers.md;
   `npx @dialecte/cli models` says which model; a failed round may go one tier up, said in the report)
 
@@ -79,13 +80,20 @@ Tests: written by the test station, red (`npx dialecte tdd status`), approved by
   with the reason. Never edit test code (tests, helpers, fixtures, snapshots): an edit after red is refused
   at green; if you made one, undo it by hand first (no git command), then hand the case back. Exempt lot: <none | the
   reason, written in .dialecte/lot.json by the orchestrator>
-Skills: load dialecte, dialecte-contributing, dialecte-lot. A skill text change: load
-  `anthropic-skills:skill-creator` with the Skill tool and follow it - eval case first, failing on the text
+Skills: load dialecte and dialecte-lot (and dialecte-contributing in a dialecte package). A skill text change: load the
+  skill-creator skill (`anthropic-skills:skill-creator`; a host without it runs the loop below by hand) and
+  follow it - eval case first, failing on the text
   before the change; runs with and before the change on the standard and strong tiers, several per
   configuration; graded blind by
   a separate agent, never by you; its benchmark and viewer paths in your report.
 Gates: fast gate per behaviour; full Definition of Done once at the end (<the package's commands>).
-Machine: one heavy browser run at a time; vitest --no-file-parallelism; nice -n 10.
+Mutation (a dialecte package that declares a mutation scope; else no such line): <off | changed | gate | audit, set in .dialecte/lot.json>; once green (a gate lot: again after the last
+  fix), `dialecte mutants run` in the background, survivors judged (`dialecte mutants judge --json`, then a
+  test, `record` or `schedule`), `dialecte mutants status` before the report: no new survivor, no died run, a
+  gate lot's run reported (dialecte-contributing, Mutation testing).
+Machine: the runner's defaults (full parallelism, no nice, no lock); a failing run rerun once, the same command
+  and --project flags on its failing files with --no-file-parallelism: a pass there is a flake to report as a
+  finding, a failure there is real; limit only when the user asks.
 Report: the implement report shape of dialecte-lot, nothing else.
 ```
 
@@ -94,7 +102,7 @@ Report: the implement report shape of dialecte-lot, nothing else.
 ```
 You review lot <id>, round <n> of <rounds> (<risk class>, from the findings ledger), as the review station of
 the dialecte-lot skill. Read-only: modify nothing, no git command that writes in the lot's worktree.
-Tier: strong, effort high, for both passes - never lower.
+Tier: strong, effort high, for both passes - never lower. Station: reviewer (references/stations.md).
 
 Spec: <plan path + sections>; the implementer's brief: <inline or path> - not the implementer's conclusions.
 Findings ledger: <hand-over folder>/findings-ledger.md (round 1: the risk class only), written by the
@@ -122,7 +130,7 @@ Later rounds - delta review of the fix diff and its blast radius only. Start fro
   One line naming what round 1 did not look at. Severity floor: a round before the last, blocking + should fix
   (nits optional); the last round, what the risk class acts on (blocking + should fix, or blocking only for
   guards and tooling). A wrong fix or a reopened row keeps the severity of the row it breaks.
-Rules: dialecte-contributing (code rules, Definition of Done), dialecte (reuse ladder).
+Rules: the repository's code rules and Definition of Done (dialecte-contributing in a dialecte package), dialecte (reuse ladder).
 Run (read-only): the tests of the lot, `skills check`, the type-check - report the real counts.
 Check: every time bound of a test reading the disk, spawning a process or measuring time holds under load;
   a hand-written commit or merge script in the hand-over is a finding (it goes through `dialecte handover`).
@@ -134,6 +142,7 @@ Max ~80 lines, most severe first, file:line for each finding.
 
 ```
 Fix mode for lot <id> (round <n>). Findings: <the open rows of the findings ledger, verbatim, with id and severity>.
+Station: fixer, or the implementer's own station (references/stations.md).
 Tier: <standard for wording or naming findings | the implementer's tier otherwise> (resume the implementer
   when it is on that tier: its context is warm)
 For each: agree (fix, test if behaviour changed) / disagree (one line why) / needs the user.

package/skills/dialecte-lot/references/model-tiers.md

@@ -10,7 +10,7 @@ project uses, `--json` for a script); read it there instead of guessing or writi
 
 | Tier       | For                                                                                                                                                                                                           |
 | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `fast`     | search and locate, graders with a schema, log and diff summaries, format and shape checks, "does file X say Y"                                                                                                |
+| `fast`     | search and locate, graders of a fixed schema (not the blind skill-eval graders: strong), log and diff summaries, format and shape checks, "does file X say Y"                                                 |
 | `standard` | the test station, an implementer on a mechanical or fully specified lot, fix mode on wording or naming findings, skill-eval runs (with strong), independent readers of a standard                             |
 | `strong`   | the orchestrator, the test review, an implementer on a design-heavy lot, the review (one agent, both passes), adjudicating a disagreement, the retro, skill-eval runs (with standard) and their blind graders |
 | `frontier` | rare: a plan challenge, a decision across repositories, a lot still stuck at the review cap, once the user decided to go on                                                                                   |
@@ -28,14 +28,14 @@ gets 3x that duration instead.
 | 1a Test (test station)                    | standard                                                                        | 10 min                       | 20 min                                            |
 | 1b Test review                            | strong: the tests against the spec, before any code                             | 5 min                        | 15 min                                            |
 | 1c Implement                              | standard for a mechanical or fully specified lot; strong for a design-heavy one | 30 min / 45 min              | 60 min / 90 min                                   |
-| 2 Fast gate                               | no agent (`dialecte gate --fast`, `dialecte rules`)                             | 5 min                        | 10 min                                            |
+| 2 Fast gate                               | no agent (`dialecte gate --fast`; `dialecte rules` in a package)                | 5 min                        | 10 min                                            |
 | 3 Review                                  | strong: one reviewer runs pass 1 (correctness) and pass 2 (fit)                 | 10 min                       | 20 min                                            |
 | 4 Fix                                     | standard for wording or naming findings; otherwise the implementer's tier       | 15 min                       | 30 min                                            |
 | 5 Full gate                               | no agent (`dialecte gate --full`)                                               | -                            | 3x a duration measured on earlier runs            |
 | 6 Hand over                               | no agent (`dialecte handover`; `handover run --rehearse` runs the commit hook)  | 20 min, rehearsal with hooks | 45 min, or 3x a duration measured on earlier runs |
 | 7 Retro                                   | strong                                                                          | 15 min                       | 30 min                                            |
 | Skill-eval runs / their graders           | standard and strong (the stations' tiers) / strong, blind to the text           | 1 min / 3 min                | 5 min / 10 min                                    |
-| Reading a standard: readers / adjudicator | standard / strong (`dialecte-contributing`, "Reading the standard")             | -                            | 30 min / 30 min                                   |
+| Reading a standard: readers / adjudicator | standard / strong ([standard-check.md](standard-check.md))                      | -                            | 30 min / 30 min                                   |
 
 ## Rules
 

package/skills/dialecte-lot/references/standard-check.md

@@ -0,0 +1,45 @@
+<!-- dialecte-skills workspace -->
+
+# The standard check
+
+For code that implements a standard - a dialecte, or an app's own Dialecte code that follows one: the standard 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 in [model-tiers.md](model-tiers.md).
+
+## What the station records
+
+The hand-over card carries a `standard` line (`@dialecte/cli` 0.3.0). The cli learns where the text is from
+`DIALECTE_STANDARD` (a file or a folder, from the environment only: never committed, never shipped), and the
+station that read it records its word in the hand-over folder:
+
+- consulted: `npx dialecte record standard <folder> consulted <note>` - the note says what was checked; the
+  `file:line` refs stay in the plan's research folder or the findings ledger, never in committed text. The card
+  shows `✓ standard consulted`.
+- none configured: propose to the user to configure one, then `npx dialecte record standard <folder> not-consulted
+  <reason>`. The card shows `! standard not consulted`, which never blocks.
+- a standard configured and nothing recorded fails the card (`✗ standard`); with one configured, only `consulted`
+  passes, `not-consulted` fails it too.
+
+Every hand-over has the line, so every lot records one. A lot that changes nothing a standard rules (tooling,
+wording, an app's UI-facing service): with none configured, `not-consulted` with that reason; with one
+configured, the station still searches the text for what the lot touches and records `consulted` with what it
+found ("nothing in the text rules <what the lot changes>"), never a `consulted` it did not do.

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

@@ -0,0 +1,110 @@
+<!-- dialecte-skills workspace -->
+
+# Station agents
+
+The stations of a lot that run as their own agent, defined once and for every host. A section is what the agent
+is: its tier ([model-tiers.md](model-tiers.md)), its access, its role. The brief ([briefs.md](briefs.md)) adds
+the lot: which step, which files, which worktree.
+
+**Access** says what the agent may do, whatever the host calls it:
+
+- `read`: reads files; runs nothing, edits nothing.
+- `review`: reads files and runs commands (tests, `dialecte tdd status`, a build); edits no file.
+- `edit`: reads, edits files in its worktree, runs commands.
+
+**Spawning one.** A host with an adapter has the agent ready: its tier and access are set by the adapter's file,
+so the spawn names the station and hands the brief. Claude Code: `.claude/agents/dialecte-<station>.md`,
+written by `npx @dialecte/cli skills sync` whenever it installs `dialecte-lot`. A host without one spawns a general sub-agent:
+the model of the station's tier (`npx @dialecte/cli models`), the narrowest tool or sandbox setting the host has
+that still allows the access (a read-only sandbox for `read` and `review`, workspace edits for `edit`; a host
+that cannot restrict says the access in the prompt), and a prompt holding this station's section, then the
+brief. The lot stations (all but `eval-runner` and `grader`) load `dialecte-lot` and `dialecte` first (and
+`dialecte-contributing` in a dialecte package): they are the source of truth, the section only sets the envelope. The eval runner and the grader
+load only what their brief names: a skill-eval run compares texts of a skill, so the runner reads the text its
+configuration names and the grader none, blind to which text produced a run.
+
+**Never, every station**: commit, stage (`git add`), push, merge, `git stash`, `git reset`, `git restore`,
+`git checkout --`, `rm`; nothing outside the worktree the brief names. The brief is the agent's whole context.
+
+### test-writer
+
+- Tier: standard
+- Access: edit
+
+Station 1a. Writes the tests of one brief step from the spec, never the production code. It may add stubs
+whose body throws `not implemented: <name>` so the tests compile, called inside `expect(...)`. It runs
+`dialecte tdd red` until every case is red on an assertion, and answers with its output.
+
+### test-reviewer
+
+- Tier: strong
+- Access: review
+
+Station 1b. Reads the tests of the step against the brief, before any production code. It modifies nothing
+(`dialecte tdd status` is the one command to run). It answers per test: the behaviour it pins, a plausible
+wrong implementation it lets through, a verdict.
+
+### implementer
+
+- Tier: standard
+- Access: edit
+
+Station 1c on a mechanical or fully specified lot, step mode. The tests are written and red: it changes
+production code only until `dialecte tdd green` passes; a test it finds wrong goes back to the test station
+with the reason. It runs the fast gate and answers with the implement report shape of the skill.
+
+### implementer-strong
+
+- Tier: strong
+- Access: edit
+
+Station 1c on a design-heavy lot: the same job and report as `implementer`.
+
+### reviewer
+
+- Tier: strong
+- Access: review
+
+Station 3, a different agent from the implementer. It modifies nothing: it reads the diff and runs the tests.
+It answers with the review report shape of the skill (both passes, a verdict).
+
+### fixer
+
+- Tier: standard
+- Access: edit
+
+Station 4 (fix mode) on wording and naming findings. For each finding it answers fixed, disagreed (one line
+why) or needs the user, with the blast-radius line of each fix; it never drops one.
+
+### eval-runner
+
+- Tier: standard
+- Access: edit
+
+Runs one skill-eval case of a Dialecte skill (a skill text change goes through skill-creator evals), with or
+without the skill as its brief says, and writes only the outputs the case names. The strong tier runs the
+second configuration.
+
+### grader
+
+- Tier: strong
+- Access: read
+
+Grades the output of a skill-eval run against the grader files its brief names, blind to which text produced
+it. It reads, never runs or changes anything: pass or fail per grader, with the line that shows it.
+
+### standard-reader
+
+- Tier: standard
+- Access: read
+
+Reads the standard for one question ([standard-check.md](standard-check.md)): the standard markdown
+only, answering with line references, never relying on what another agent concluded.
+
+### searcher
+
+- Tier: fast
+- Access: read
+
+Locates code, files or documentation for the question its brief asks, in the Dialecte repositories it names:
+absolute paths and line numbers, nothing speculative.