@dialecte/core 0.8.0 → 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (17) hide show
  1. package/dist/document/types.extensions.d.ts.map +1 -1
  2. package/dist/errors/types.d.ts.map +1 -1
  3. package/dist/types/dialecte-config.d.ts.map +1 -1
  4. package/package.json +16 -18
  5. package/skills/dialecte/SKILL.md +84 -15
  6. package/skills/dialecte/references/core-api.md +1 -0
  7. package/skills/dialecte-contributing/SKILL.md +94 -48
  8. package/skills/dialecte-contributing/references/code-rules.md +7 -0
  9. package/skills/dialecte-contributing/references/landing-changes.md +10 -6
  10. package/skills/dialecte-contributing/references/lot-in-a-package.md +45 -0
  11. package/skills/dialecte-contributing/references/perf.md +2 -1
  12. package/skills/dialecte-contributing/references/traps.md +20 -0
  13. package/skills/dialecte-lot/SKILL.md +106 -51
  14. package/skills/dialecte-lot/references/briefs.md +18 -9
  15. package/skills/dialecte-lot/references/model-tiers.md +3 -3
  16. package/skills/dialecte-lot/references/standard-check.md +45 -0
  17. package/skills/dialecte-lot/references/stations.md +110 -0
package/skills/dialecte-contributing/references/landing-changes.md CHANGED
@@ -40,9 +40,10 @@ workspace root, outside every repo); the hand-over files are written next to it
40
40
  unstages those files, with its `cd`: give it to the user.
41
41
  - **Guards**, checked when the folder is written (nothing is written on a refusal) and again when it
42
42
  runs: the branch and HEAD, the hooks folder `core.hooksPath` names exists (a missing one makes git skip
43
- every hook), `lots.json` as reviewed, an empty index, every changed file in exactly one lot, no plan tag or standard citation in
44
- a lot's files (skill evals and test fixtures included) nor in its messages; when it runs, every file
45
- against the snapshot taken when it was written, and no other file changed.
43
+ 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
44
+ consuming tool in a lot's files (skill evals and test fixtures included) nor in its messages; when it runs, every file
45
+ 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
46
+ leave (guard `contrib`; a rehearsal runs contrib in its clone when there is none).
46
47
  - **The folder**: the lots file, the snapshot (`files.txt`, `files.sha256`, `files.deleted`) and a one-line
47
48
  `commit.sh` that runs `npx --no-install @dialecte/cli handover run <folder>` (it re-executes itself with
48
49
  bash: people run it with `sh`). Nothing per lot. The repository stays locked for `dialecte gate` until
@@ -78,6 +79,9 @@ as the behaviour for a reader of the history. No plan/ticket tags, no standard c
78
79
 
79
80
  ## Hand-over message
80
81
 
81
- The message is the card `dialecte handover` printed - repository, worktree, branch, HEAD, gates, the lots
82
- with their files and messages, and the command to run with its absolute `cd` - pasted as printed, never
83
- retyped; then what was not verified.
82
+ From cli 0.3.1 the message points at the hand-over, it does not carry it: `READY`, then
83
+ `cd <worktree> && npx dialecte handover show <name>` (the card recomputed from the records, current whenever
84
+ it is read) and `npx dialecte handover run <name>` (what the person runs); then what was not verified. Never
85
+ a pasted or retyped card: it goes stale as soon as a record changes. With an older cli, the message is the
86
+ card `dialecte handover` printed - repository, worktree, branch, HEAD, gates, the lots with their files and
87
+ 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 ADDED
@@ -0,0 +1,45 @@
1
+ <!-- dialecte-skills workspace -->
2
+
3
+ # A lot in a dialecte package
4
+
5
+ The `dialecte-lot` stations run the same in every repository. In a dialecte package - `"dialecte": { "profile":
6
+ "contributor" }` in its `package.json`: core, a dialecte, create, cli - they gain the steps below. An app runs none
7
+ of them: its lot ends at the hand-over.
8
+
9
+ ## Station 0 - the mutation switch
10
+
11
+ - **Mutation switch** (a package that declares a mutation scope): the orchestrator sets it per lot in the worktree's
12
+ `.dialecte/lot.json` with `dialecte lot mutation <mode>` and names it in the brief - the default (`changed` when the
13
+ diff touches the scope, `off` otherwise) for most lots, `gate` only for a robustness lot (its hand-over waits for
14
+ a run reported on the tree it commits: it runs again after the last fix), `audit` on request. The implementer
15
+ starts `dialecte mutants run` in the background once green and judges the survivors as [SKILL.md](../SKILL.md)
16
+ (Mutation testing) says. Before a release, a full audit in the background;
17
+ its survivors become named follow-up lots (`dialecte mutants schedule <follow-up lot> <key>`).
18
+
19
+ ## Station 2 - `dialecte rules`
20
+
21
+ With the fast gate, run `npx dialecte rules` from the package root and fix every error before the review; answer
22
+ every warning ([code-rules.md](code-rules.md)). The implement report's `Gates:` line adds
23
+ `rules <n errors, m warnings>`.
24
+
25
+ ## Station 5 - `dialecte contrib` after the full gate
26
+
27
+ From `@dialecte/cli` 0.3.0, once `gate --full` is green, run `npx dialecte contrib`: `rules` on the files changed
28
+ against HEAD, the package's contrib steps (by default the docs build, its generated docs restored, and the type
29
+ bench), `release` (no dependency named by a local folder) and `mutation` when a scope is declared. A step the full
30
+ gate passed on the same tree and install is not run again (`reused from gate --full`). Paste its lines with the
31
+ gate's. The hand-over's `contrib` guard refuses a tree without a green record of it; a rehearsal runs it in its
32
+ scratch clone when there is none.
33
+
34
+ ## Station 6 - mutation, landing, merges
35
+
36
+ - The landing rules apply: [landing-changes.md](landing-changes.md) (lots, guards, rehearsal, merge lots).
37
+ - In a package with a mutation scope, run `dialecte mutants status`
38
+ before every hand-over and every merge: a `new` survivor or a `died` run blocks the card and the guard until it is
39
+ handled ([SKILL.md](../SKILL.md), Mutation testing); the lot's own run still running blocks only a merge or a `gate`
40
+ lot (on a plain hand-over it is a `!`).
41
+ - A merge onto a main that moved since the cut leaves a tree no check has seen: it is rehearsed. The branch's green
42
+ records say nothing about it - not its suite, nor a gate step the hook does not run (docs, skills check, the
43
+ browser suite). The rehearsal's hook runs the suite on the merged tree; run only the steps the hook does not run,
44
+ in the clone `--rehearse --keep` leaves, never a `gate --full` that would run the suite there again. A `reused`
45
+ line for such a merge is a cli bug to report, never a result to pass on.
package/skills/dialecte-contributing/references/perf.md CHANGED
@@ -36,4 +36,5 @@ before measuring, or you measure old code.
36
36
  ## Reading results
37
37
 
38
38
  Explain a delta before acting on it. Compare against the previous commit on the same machine,
39
- same fixture, several runs; keep heavy runs one at a time on shared machines.
39
+ same fixture, several runs; a timed bench runs alone, its load recorded beside the numbers: beside another
40
+ suite its timings mean nothing (tests, unlike benches, run at full parallelism whatever the load).
package/skills/dialecte-contributing/references/traps.md CHANGED
@@ -72,6 +72,26 @@ ran what you think it ran.
72
72
  - `dialecte-xmlfmt` reformats `/* xml */` template literals; it can mangle a nested template
73
73
  literal - check the diff.
74
74
 
75
+ ## Tools with shared state
76
+
77
+ For a lot that builds tooling (the cli above all) rather than engine code. Each trap cost a lot several review rounds.
78
+
79
+ - **A store several runs share** (a ledger, a records file, a run store, a cache, a lock) planned as prose is wrong
80
+ in ways only interleavings show: two runs finishing in either order, overlapping runs, a crash between two writes,
81
+ a dead or reused owner. The plan writes it as a transition table (event, from, to, condition), its invariant
82
+ ("an item leaves pending only by ...") and the list of interleavings; the test station writes one forced-order
83
+ test per interleaving before any code. Liveness is the process id plus its start time read in UTC, never the id
84
+ alone.
85
+ - **A fake runner proves the wiring, not the integration.** A lot that drives an external tool (StrykerJS, vitest,
86
+ git, npm) records one real run on a known target with its expected numbers before the hand-over, in `SMOKE.md` in
87
+ the hand-over folder.
88
+ - **That run happens in a scratch `git clone`** (its own `.git`), never a worktree of a real repository: worktrees
89
+ share the git folder, so a store under it (`dialecte-mutation/`, the check records) takes the experiment's state
90
+ and blocks the next real hand-over. State that landed in a real store anyway is cleared through the cli only.
91
+ - **A value a third-party tool produces or consumes** (a report field, a column, a config key) is pinned by a test
92
+ that cites its source: a file and line of the tool, or a recorded real run. A shape from memory merged once one
93
+ column off.
94
+
75
95
  ## Shell
76
96
 
77
97
  - zsh does not word-split `$FILES`: `git diff -- $FILES` with a space-separated list addresses one
package/skills/dialecte-lot/SKILL.md CHANGED
@@ -1,10 +1,11 @@
1
1
  ---
2
2
  name: dialecte-lot
3
- 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.
3
+ 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.
4
4
  license: MIT
5
5
  metadata:
6
6
  author: dialecte
7
7
  version: '0.1.0'
8
+ audience: consumer
8
9
  ---
9
10
 
10
11
  <!-- dialecte-skills workspace -->
@@ -20,20 +21,40 @@ compare runs.
20
21
  **Memory is the artifacts, not the chat.** The plan file, the station reports, the diff and the retro log
21
22
  are what the next station reads. A decision that is not in one of them was not a decision.
22
23
 
24
+ **In a dialecte package** (`"dialecte": { "profile": "contributor" }` in its `package.json`), load
25
+ `dialecte-contributing` too: its `references/lot-in-a-package.md` adds the package's own steps to these stations -
26
+ the mutation switch, `dialecte rules`, `dialecte contrib` before the hand-over, the landing rules and merge lots.
27
+ **In an app**, none of them. There a lot is a sub-loop the app's agent runs by itself for the Dialecte-scoped
28
+ part of a task only - the local dialecte extension, the services and composables that call `@dialecte/*` APIs, an
29
+ extension meant for promotion: the same stations, ending at the hand-over (Station 6), then back to the app's own
30
+ pipeline, which carries on with its own steps and its pull request. The rest of the app's change (its UI, layout,
31
+ styling) stays under the app's process and never enters the lot. An extension meant for promotion is delivered to
32
+ the package's bar (node-tier tests, the JSDoc of every public function, its docs), so that promoting it moves the
33
+ folder and rewrites nothing.
34
+
23
35
  ## The stations
24
36
 
25
- | # | Station | Who | Tier | Reads | Leaves |
26
- | --- | ----------- | --------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
27
- | 0 | Orchestrate | orchestrator | strong | the plan, the user's decisions | one brief per implementer (template in [references/briefs.md](references/briefs.md)) |
28
- | 1a | Test | test station (own agent) | standard | its brief step, the existing code | tests + stubs, proven red by `dialecte tdd red` (its receipts) |
29
- | 1b | Test review | **a different agent** | strong | the tests of the step, the brief | a verdict on the tests, before any code |
30
- | 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 |
31
- | 2 | Fast gate | implementer | no agent | - | `dialecte gate --fast` + `dialecte rules`: type-check, lint, format, touched tests, skills check, code rules |
32
- | 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 |
33
- | 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 |
34
- | 5 | Full gate | implementer | no agent | - | `dialecte gate --full`: the package's full Definition of Done, once per lot |
35
- | 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 |
36
- | 7 | Retro | orchestrator | strong | reports, loops, the user's corrections | retro entries; skill edits drafted, applied on approval |
37
+ | # | Station | Who | Tier | Reads | Leaves |
38
+ | --- | ----------- | --------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
39
+ | 0 | Orchestrate | orchestrator | strong | the plan, the user's decisions | one brief per implementer (template in [references/briefs.md](references/briefs.md)) |
40
+ | 1a | Test | test station (own agent) | standard | its brief step, the existing code | tests + stubs, proven red by `dialecte tdd red` (its receipts) |
41
+ | 1b | Test review | **a different agent** | strong | the tests of the step, the brief | a verdict on the tests, before any code |
42
+ | 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 |
43
+ | 2 | Fast gate | implementer | no agent | - | `dialecte gate --fast`: type-check, lint, format, touched tests, skills check |
44
+ | 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 |
45
+ | 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 |
46
+ | 5 | Full gate | implementer | no agent | - | `dialecte gate --full`: the package's full Definition of Done, once per lot |
47
+ | 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 |
48
+ | 7 | Retro | orchestrator | strong | reports, loops, the user's corrections | retro entries; skill edits drafted, applied on approval |
49
+
50
+ **After the hand-over, the pull request is the repository's own.** In a dialecte repository Station 7
51
+ follows the hand-over, and the branch goes up by pull request through that repository's landing rules
52
+ (`dialecte-contributing`). In an app that consumes a dialecte, the lot ends at
53
+ Station 6: what comes after belongs to the app's own process - its PR skill and template for the pull
54
+ request, its own retro and clean-up if it has them - and no further station of this skill runs (no Station 7,
55
+ no `dialecte worktree prune`, no dialecte PR or release step). The hand-over's records (`dialecte recap`
56
+ prints a PR's details part from them) feed the app's template only where its rules ask for it. Pushing and
57
+ posting stay the user's (or wait for their approval).
37
58
 
38
59
  The Tier column names the kind of model a station runs on, never a model: the tiers, the rules that go with
39
60
  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
46
67
  decides whether one more round checks it. Findings that keep coming past the cap mean the plan or the brief is
47
68
  wrong.
48
69
 
70
+ ## Station 0 - what the plan and the brief settle
71
+
72
+ Before the test station, the plan holds what the tests will pin; a gap found by a reviewer costs a round.
73
+
74
+ - **The standard** (a lot whose rules come from a standard the code implements):
75
+ [references/standard-check.md](references/standard-check.md) - how it is read, the cross-check for a
76
+ decision, and what the station records for the hand-over card (`dialecte record standard`).
77
+ - **A tooling lot with shared state or an external tool**: the plan carries the store's transition table, its
78
+ invariant and the interleavings, the test-station brief asks one forced-order test per interleaving, and the
79
+ hand-over folder gets a `SMOKE.md` with the lot's one real run; how and where that run happens, and citing
80
+ third-party values: in a dialecte package, `dialecte-contributing` references/traps.md, Tools with shared state.
81
+
49
82
  ## Station 1 - test, test review, implement (per brief step)
50
83
 
51
84
  The order matters, not only the outcome: a test written after the code can be shaped to please it. So each
52
85
  step of the brief (3-6 behaviours) goes through three agents, and the cli keeps the receipts:
53
86
 
54
- 1. **Test station** (own agent, `standard`; `dialecte-test-writer` in Claude Code). Reads the brief step and
87
+ 1. **Test station** (own agent, `standard`; station `test-writer`). Reads the brief step and
55
88
  the existing code only. Writes the step's tests from the spec and, where the code does not exist yet,
56
89
  stubs with their real types whose body throws `new Error('not implemented: <name>')`; each test calls
57
90
  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
66
99
  a refusal; a changed helper, fixture or snapshot is frozen only by a red of a file that depends on it
67
100
  (imports it - relative, tsconfig `paths` or vite alias, through barrels - names it, or owns the snapshot;
68
101
  an import that looks local and resolves nowhere refuses the file). Its report is the `tdd red` output.
69
- 2. **Test review** (a different agent, `strong`, read-only; `dialecte-test-reviewer`). Reads only the tests
102
+ 2. **Test review** (a different agent, `strong`, read-only; station `test-reviewer`). Reads only the tests
70
103
  against the spec, before any code - the changed helpers, fixtures and snapshots too: does each pin a
71
104
  behaviour of the brief, would a plausible wrong implementation fail it, does every `expect(...)` have a
72
105
  matcher, is a behaviour of the step left without a test. Verdict: approve, or back to the test station
73
106
  with the findings (which runs `tdd red` again).
74
- 3. **Implement station** (another agent: `dialecte-implementer`, or `-strong` by lot kind). Changes
107
+ 3. **Implement station** (another agent: station `implementer`, or `implementer-strong` by lot kind). Changes
75
108
  production code only, until `npx dialecte tdd green` passes: every case of the step with its red
76
109
  receipt, its test code as the last red run froze it, production changed since its red, and green. A
77
110
  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
119
152
  can assume things that changed. A contradiction stops you: say it, do not reinterpret the plan.
120
153
  2. `git status -sb` in your worktree: right branch, clean (or dirty only with your own earlier work).
121
154
  Note the HEAD sha for your report.
122
- 3. Load `dialecte` and `dialecte-contributing`; run the reuse ladder before writing anything.
155
+ 3. Load `dialecte` (and `dialecte-contributing` in a dialecte package); run the reuse ladder before writing anything.
123
156
 
124
157
  Then, within the step:
125
158
 
@@ -131,7 +164,8 @@ Then, within the step:
131
164
  - Only the lot's scope. A refactor outside it is a new lot, said out loud.
132
165
 
133
166
  A **skill text change** is code too: when the lot changes what a skill tells agents to do (a new command to
134
- run, a rule), load `anthropic-skills:skill-creator` with the Skill tool and follow it. A skill change judged
167
+ run, a rule), load the skill-creator skill (`anthropic-skills:skill-creator`) and follow it; a host without it
168
+ runs the same loop by hand, as below. A skill change judged
135
169
  by hand, or by the agent that wrote it, looks green on one run and its own reading; skill-creator's loop is
136
170
  what shows the change moves behaviour. As it applies here: the eval case under the skill's `evals/` first
137
171
  (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>
148
182
  Files: <list>
149
183
  Tests: <n> passing of <m> table cases - command: <the exact command, unfiltered>
150
184
  Red seen: <the `tdd red` line of each case: case, kind, failing message> (one line per behaviour)
151
- Gates: <the lines `dialecte gate` printed, with their counts>; rules <n errors, m warnings>
185
+ Gates: <the lines `dialecte gate` printed, with their counts>
152
186
  Skill evals: <case: pass rate with / before, runs per configuration; benchmark and viewer paths> | n/a
153
187
  Deviations from the brief: <none | what and why>
154
188
  Open questions: <none | ...>
@@ -156,10 +190,12 @@ Open questions: <none | ...>
156
190
 
157
191
  ## Station 2 - fast gate (the counts decide, not the summary)
158
192
 
159
- Run `npx dialecte gate --fast --declare <new path>` and `npx dialecte rules` from the package root. The gate
193
+ Run `npx dialecte gate --fast --declare <new path>` from the package root; in a dialecte package, run
194
+ `npx dialecte rules` with it and fix its errors before the review (`dialecte-contributing`
195
+ references/lot-in-a-package.md, Station 2). The gate
160
196
  starts with the worktree's hygiene (nothing staged, the stash as it was when the worktree was made, every new
161
197
  file declared: one `--declare` per new file or folder of the lot), then runs each step unfiltered and prints
162
- 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
198
+ 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
163
199
  you, and what you check by hand with a cli older than 0.2.0:
164
200
 
165
201
  - 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
179
215
 
180
216
  The reviewer did not write the code and does not take the implementer's report as truth. Read-only.
181
217
  Inputs: the brief (the spec), the diff of the lot's files, the previous version of each file, the rules
182
- (`dialecte-contributing` code rules and Definition of Done, `dialecte` reuse ladder).
218
+ (the repository's code rules and Definition of Done - `dialecte-contributing` in a dialecte package -,
219
+ `dialecte` reuse ladder).
183
220
 
184
221
  **Pass 1 - correctness** (always first): logic, edge cases, async and error handling, a behaviour changed
185
222
  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
344
381
 
345
382
  ## Station 6 - hand over
346
383
 
347
- The `dialecte-contributing` landing rules apply. Write only the lots file and run `npx dialecte handover
384
+ Write only the lots file and run `npx dialecte handover
348
385
  <lots.json>`: it writes the hand-over folder and prints its card. Never a hand-written script, nor a file per
349
386
  commit. When the repository has a commit hook (`core.hooksPath`), rehearse first with `npx dialecte handover
350
387
  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:
359
396
 
360
397
  - A second `gate` of the same mode on an unchanged tree runs its hygiene and `tdd` step (they read the worktree,
361
398
  not the tree), then answers the rest from its record (`reused: gate --full green on this tree ...`). Run it when
362
- you want its lines; never `--rerun` "to be safe": an edit, a lock, a linked dependency already make a new key.
363
- `--rerun` is for when the person asks, or when something outside the key changed (a machine fault you suspect).
364
- - `handover run --rehearse` decides per lot and prints why (the rules: `dialecte-contributing`
365
- references/landing-changes.md). Paste those lines with the card; never add `--full` to force a rehearsal the cli
399
+ you want its lines; never `--no-reuse` "to be safe": an edit, a lock, a linked dependency already make a new key.
400
+ `--no-reuse` is for when the person asks, or when something outside the key changed (a machine fault you suspect).
401
+ - `handover run --rehearse` decides per lot and prints why (in a dialecte package, its rules are in
402
+ `dialecte-contributing` references/landing-changes.md). Paste those lines with the card; never add `--full` to force a rehearsal the cli
366
403
  skipped, and start no load for it. A lot it does rehearse runs under load as above.
367
- - A merge onto a main that moved since the cut leaves a tree no check has seen: it is rehearsed. The branch's green
368
- records say nothing about it - not its suite, nor a gate step the hook does not run (docs, skills check, the
369
- browser suite). The rehearsal's hook runs the suite on the merged tree; run only the steps the hook does not run,
370
- in the clone `--rehearse --keep` leaves, never a `gate --full` that would run the suite there again. A `reused`
371
- line for such a merge is a cli bug to report, never a result to pass on.
372
404
  - The real commit's hook always runs, whatever the records say: it is the person's last net. Nothing passes
373
405
  `--no-verify`.
374
406
 
375
- The hand-over message to the user **is the card** `handover` printed - repository, worktree, branch, HEAD,
376
- gates, the lots with their files and messages, and the command with its absolute `cd` - pasted as printed,
377
- never retyped. After it: what was not verified, and one usage line (the lot's sub-agent tokens, in total
407
+ **Reporting READY.** From cli 0.3.1 the message to the user points at the hand-over instead of carrying it:
408
+ `READY`, then `cd <worktree> && npx dialecte handover show <name>` (the card recomputed read-only from the
409
+ records, current whenever the person reads it) and `npx dialecte handover run <name>` (the command they run) -
410
+ never a pasted or retyped card, which goes stale as soon as a record changes. With an older cli, the message
411
+ **is the card** `handover` printed - repository, worktree, branch, HEAD, gates, the lots with their files and
412
+ 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
378
413
  and by station: [references/retro.md](references/retro.md)). A refusal is a finding: fix the file or the
379
414
  message, do not loosen the lots. `npx dialecte handover list` shows every hand-over waiting on the machine.
380
415
  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.
402
437
  - Write each brief from [references/briefs.md](references/briefs.md): the brief is the agent's whole
403
438
  context; synthesise, do not say "based on the findings". Every brief carries its lines for all stations
404
439
  (nothing under `.git` by hand, no workflow without the user's opt-in, no `rm` on a variable path).
405
- - Spawn the station's own agent when the host has it: Claude Code with `.claude/agents/dialecte-<station>.md`
406
- (written by `npx @dialecte/cli skills sync`: `dialecte-test-writer`, `dialecte-test-reviewer`,
407
- `dialecte-implementer`, `dialecte-implementer-strong`, `dialecte-reviewer`, `dialecte-fixer`,
408
- `dialecte-eval-runner`, `dialecte-grader`, `dialecte-standard-reader`, `dialecte-searcher`). The test
409
- writer edits tests and stubs; the test reviewer reads; the implementer keeps every edit tool, the freeze
410
- of the tests is `tdd green`'s and the gate's. The file sets the model and the tools (the reviewer cannot
411
- edit files), so the spawn names neither. Without the file, spawn a general sub-agent on the tier its brief
412
- names ([references/model-tiers.md](references/model-tiers.md)). Note the tokens of each completion notice
440
+ - Each station agent is defined once, for every host, in [references/stations.md](references/stations.md):
441
+ its tier, its access (`read`, `review`: runs commands but edits nothing, `edit`) and its role (`test-writer`,
442
+ `test-reviewer`, `implementer`, `implementer-strong`, `reviewer`, `fixer`, `eval-runner`, `grader`,
443
+ `standard-reader`, `searcher`). The test writer edits tests and stubs; the test reviewer reads; the
444
+ implementer keeps every edit tool, the freeze of the tests is `tdd green`'s and the gate's. A host with an
445
+ adapter spawns the station's own agent, whose file sets the model and the tools, so the spawn names neither
446
+ (Per host, below). Without one, spawn a general sub-agent on the station's tier
447
+ ([references/model-tiers.md](references/model-tiers.md)), restricted to its access, its prompt holding the
448
+ station's section before the brief. Note the tokens of each completion notice
413
449
  against its station as it lands: the ledger the retro and the hand-over message report. When a station
414
450
  runs well above the lot's other stations, tell the user then, not at the end.
415
451
  - Spawn the reviewer only after the implementer's report; give it the brief, not the implementer's
416
452
  conclusions. You review too: read the diff yourself before accepting a verdict.
417
- - Heavy runs share one machine: one browser test suite at a time (`--no-file-parallelism`), low
418
- concurrency for mutation tests. `gate --full` and the heavy gate steps (any test step of a package that
419
- runs its tests in a browser) hold a machine-wide lock: a second one waits, naming the holder.
453
+ - Runs use the runner's defaults, whoever else shares the machine: no `nice`, no worker cap added on the
454
+ command line (a config's own setting, such as mutation tests' measured concurrency, is the runner's default), no
455
+ `--no-file-parallelism`, no lock - unless the user asks to limit, for the time they say. A failing run is rerun
456
+ once, the same command with its `--project` flags, on its failing files with `--no-file-parallelism` (the gate
457
+ does it on its test steps): a pass
458
+ there is a flake, a finding fixed at its cause, never a reason to throttle; a failure there is real
459
+ (in a dialecte package, `dialecte-contributing`, Definition of Done).
420
460
  - After the user merged: `npx dialecte worktree prune` lists the merged worktrees and branches, the
421
461
  committed hand-over folders and the rehearsal clones, each with its command (a worktree just made, one
422
462
  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:
433
473
  - **How long**: the station's deadline ([references/model-tiers.md](references/model-tiers.md)), or three
434
474
  times a duration measured on earlier runs of the same command (a commit hook, a gate, a bench: a hook that
435
475
  took 6 minutes gets 18). Write it in the run log.
436
- - **Armed at launch**: in Claude Code, arm the check in the same turn as the launch - a scheduled check or
437
- 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
438
- without one polls at the deadline.
476
+ - **Armed at launch**: arm the check in the same turn as the launch, with whatever the host has that wakes
477
+ you - a scheduled check or a wake-up at the deadline, or a monitor on the run's log - so you are woken even
478
+ if no notice comes. A host with none polls at the deadline.
439
479
  - **At the deadline, look at the run itself**: its process tree (`pgrep -P <pid>`, `ps -o pid,stat,time,command`:
440
480
  is its CPU time growing?), the agent's last activity or the log's last line and its time, and `dialecte runs`
441
481
  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:
447
487
  Under `dialecte handover run`, `gate` and `tdd`, the runner's own stall watchdog does the kill; your
448
488
  deadline is the backstop that notices a runner that did not.
449
489
 
490
+ ## Per host
491
+
492
+ The stations, gates and hand-over are the same everywhere: they run through the `dialecte` cli and the git
493
+ hooks. What differs is how a host starts a session, spawns an agent and wakes you:
494
+
495
+ - **Every host**: the session starts with `npx --no-install @dialecte/cli doctor --brief` (the synced `AGENTS.md`
496
+ section says so; where a hook already ran it, its lines are in your context): nothing printed means the skills
497
+ are in sync, else fix each line first. Station agents come from references/stations.md.
498
+ - **Claude Code**: a `SessionStart` hook runs that check for you (do not run it again); `.claude/agents/dialecte-<station>.md` are the
499
+ station adapters (the Agent tool spawns them by name); skills load with the Skill tool; the Workflow tool is
500
+ the multi-agent workflow that needs the user's opt-in; a scheduled wake-up or a monitor arms a deadline.
501
+ - **Another host** (Codex, Cursor, Gemini CLI, Copilot): skills in `.agents/skills/` (or `.github/skills/`); a
502
+ general sub-agent per station, as above; its own scheduler or a timer arms a deadline, else poll at it.
503
+
450
504
  ## Never
451
505
 
452
506
  - 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:
461
515
  lock or a broken config stops that step: read it (`ls`, `cat`), then hand it to the orchestrator - its path,
462
516
  what you believe wrote it, the refused command; the orchestrator (or an agent playing every station) takes it
463
517
  to the user. The same for the hand-over script a lock names. Every station, every agent.
464
- - Start a multi-agent workflow (Claude Code's Workflow tool) without the user's explicit opt-in: each sub-agent
465
- has its own spawn (Claude Code: the Agent tool), several at once when they are independent, eval runs included.
518
+ - Start a multi-agent workflow (a host tool that fans out many agents from one script) without the user's
519
+ explicit opt-in: each sub-agent has its own spawn, several at once when they are independent, eval runs
520
+ included.
466
521
  - `rm`, `mv` or `xargs` on a variable path: leave temporary files in the hand-over folder or the scratchpad.
467
522
  - Wait on a background run with no deadline, or on its completion notice alone.
468
523
  - Hand over a hand-written commit or merge script.
package/skills/dialecte-lot/references/briefs.md CHANGED
@@ -11,8 +11,8 @@ Every brief, whatever the station, carries these lines (the templates below assu
11
11
  Never edit, move or remove a file under a repository's .git folder (a lock, a config, a receipt), even one
12
12
  your own run left, even when a refusal says to delete it: a stuck lock or config stops the step - read it,
13
13
  report its path, what you believe wrote it and the refused command to the orchestrator.
14
- No multi-agent workflow (Claude Code's Workflow tool) unless the user opted in; a sub-agent of yours has its
15
- own spawn (Claude Code: the Agent tool). No rm, mv or xargs on a variable path: leave temporary files in the
14
+ No multi-agent workflow (a host tool that fans out many agents at once) unless the user opted in; a sub-agent
15
+ of yours has its own spawn. No rm, mv or xargs on a variable path: leave temporary files in the
16
16
  hand-over folder or the scratchpad.
17
17
  ```
18
18
 
@@ -20,7 +20,7 @@ No multi-agent workflow (Claude Code's Workflow tool) unless the user opted in;
20
20
 
21
21
  ```
22
22
  You are the test station (Station 1a of the dialecte-lot skill) of step <n> of lot <id> (<plan path>).
23
- Tier: standard (model-tiers.md; `npx @dialecte/cli models` says which model). Claude Code: dialecte-test-writer.
23
+ Tier: standard (model-tiers.md; `npx @dialecte/cli models` says which model). Station: test-writer (references/stations.md).
24
24
 
25
25
  Step: <the 3-6 behaviours of the step, as case keys "<state> → <outcome>">
26
26
  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.
44
44
  ```
45
45
  You review the tests (Station 1b of the dialecte-lot skill) of step <n> of lot <id>, before any code.
46
46
  Read-only: modify nothing; `npx dialecte tdd status` is the one command to run.
47
- Tier: strong - never lower. Claude Code: dialecte-test-reviewer.
47
+ Tier: strong - never lower. Station: test-reviewer (references/stations.md).
48
48
 
49
49
  Spec: <plan path + sections>; the step: <the behaviours>.
50
50
  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
63
63
 
64
64
  ```
65
65
  You implement lot <id> of <plan path>, as the implement station of the dialecte-lot skill.
66
+ Station: implementer | implementer-strong (references/stations.md).
66
67
  Tier: <standard for a mechanical or fully specified lot | strong for a design-heavy one> (model-tiers.md;
67
68
  `npx @dialecte/cli models` says which model; a failed round may go one tier up, said in the report)
68
69
 
@@ -79,13 +80,20 @@ Tests: written by the test station, red (`npx dialecte tdd status`), approved by
79
80
  with the reason. Never edit test code (tests, helpers, fixtures, snapshots): an edit after red is refused
80
81
  at green; if you made one, undo it by hand first (no git command), then hand the case back. Exempt lot: <none | the
81
82
  reason, written in .dialecte/lot.json by the orchestrator>
82
- Skills: load dialecte, dialecte-contributing, dialecte-lot. A skill text change: load
83
- `anthropic-skills:skill-creator` with the Skill tool and follow it - eval case first, failing on the text
83
+ Skills: load dialecte and dialecte-lot (and dialecte-contributing in a dialecte package). A skill text change: load the
84
+ skill-creator skill (`anthropic-skills:skill-creator`; a host without it runs the loop below by hand) and
85
+ follow it - eval case first, failing on the text
84
86
  before the change; runs with and before the change on the standard and strong tiers, several per
85
87
  configuration; graded blind by
86
88
  a separate agent, never by you; its benchmark and viewer paths in your report.
87
89
  Gates: fast gate per behaviour; full Definition of Done once at the end (<the package's commands>).
88
- Machine: one heavy browser run at a time; vitest --no-file-parallelism; nice -n 10.
90
+ 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
91
+ fix), `dialecte mutants run` in the background, survivors judged (`dialecte mutants judge --json`, then a
92
+ test, `record` or `schedule`), `dialecte mutants status` before the report: no new survivor, no died run, a
93
+ gate lot's run reported (dialecte-contributing, Mutation testing).
94
+ Machine: the runner's defaults (full parallelism, no nice, no lock); a failing run rerun once, the same command
95
+ and --project flags on its failing files with --no-file-parallelism: a pass there is a flake to report as a
96
+ finding, a failure there is real; limit only when the user asks.
89
97
  Report: the implement report shape of dialecte-lot, nothing else.
90
98
  ```
91
99
 
@@ -94,7 +102,7 @@ Report: the implement report shape of dialecte-lot, nothing else.
94
102
  ```
95
103
  You review lot <id>, round <n> of <rounds> (<risk class>, from the findings ledger), as the review station of
96
104
  the dialecte-lot skill. Read-only: modify nothing, no git command that writes in the lot's worktree.
97
- Tier: strong, effort high, for both passes - never lower.
105
+ Tier: strong, effort high, for both passes - never lower. Station: reviewer (references/stations.md).
98
106
 
99
107
  Spec: <plan path + sections>; the implementer's brief: <inline or path> - not the implementer's conclusions.
100
108
  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
122
130
  One line naming what round 1 did not look at. Severity floor: a round before the last, blocking + should fix
123
131
  (nits optional); the last round, what the risk class acts on (blocking + should fix, or blocking only for
124
132
  guards and tooling). A wrong fix or a reopened row keeps the severity of the row it breaks.
125
- Rules: dialecte-contributing (code rules, Definition of Done), dialecte (reuse ladder).
133
+ Rules: the repository's code rules and Definition of Done (dialecte-contributing in a dialecte package), dialecte (reuse ladder).
126
134
  Run (read-only): the tests of the lot, `skills check`, the type-check - report the real counts.
127
135
  Check: every time bound of a test reading the disk, spawning a process or measuring time holds under load;
128
136
  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.
134
142
 
135
143
  ```
136
144
  Fix mode for lot <id> (round <n>). Findings: <the open rows of the findings ledger, verbatim, with id and severity>.
145
+ Station: fixer, or the implementer's own station (references/stations.md).
137
146
  Tier: <standard for wording or naming findings | the implementer's tier otherwise> (resume the implementer
138
147
  when it is on that tier: its context is warm)
139
148
  For each: agree (fix, test if behaviour changed) / disagree (one line why) / needs the user.
package/skills/dialecte-lot/references/model-tiers.md CHANGED
@@ -10,7 +10,7 @@ project uses, `--json` for a script); read it there instead of guessing or writi
10
10
 
11
11
  | Tier | For |
12
12
  | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
13
- | `fast` | search and locate, graders with a schema, log and diff summaries, format and shape checks, "does file X say Y" |
13
+ | `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" |
14
14
  | `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 |
15
15
  | `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 |
16
16
  | `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.
28
28
  | 1a Test (test station) | standard | 10 min | 20 min |
29
29
  | 1b Test review | strong: the tests against the spec, before any code | 5 min | 15 min |
30
30
  | 1c Implement | standard for a mechanical or fully specified lot; strong for a design-heavy one | 30 min / 45 min | 60 min / 90 min |
31
- | 2 Fast gate | no agent (`dialecte gate --fast`, `dialecte rules`) | 5 min | 10 min |
31
+ | 2 Fast gate | no agent (`dialecte gate --fast`; `dialecte rules` in a package) | 5 min | 10 min |
32
32
  | 3 Review | strong: one reviewer runs pass 1 (correctness) and pass 2 (fit) | 10 min | 20 min |
33
33
  | 4 Fix | standard for wording or naming findings; otherwise the implementer's tier | 15 min | 30 min |
34
34
  | 5 Full gate | no agent (`dialecte gate --full`) | - | 3x a duration measured on earlier runs |
35
35
  | 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 |
36
36
  | 7 Retro | strong | 15 min | 30 min |
37
37
  | Skill-eval runs / their graders | standard and strong (the stations' tiers) / strong, blind to the text | 1 min / 3 min | 5 min / 10 min |
38
- | Reading a standard: readers / adjudicator | standard / strong (`dialecte-contributing`, "Reading the standard") | - | 30 min / 30 min |
38
+ | Reading a standard: readers / adjudicator | standard / strong ([standard-check.md](standard-check.md)) | - | 30 min / 30 min |
39
39
 
40
40
  ## Rules
41
41
 
package/skills/dialecte-lot/references/standard-check.md ADDED
@@ -0,0 +1,45 @@
1
+ <!-- dialecte-skills workspace -->
2
+
3
+ # The standard check
4
+
5
+ For code that implements a standard - a dialecte, or an app's own Dialecte code that follows one: the standard is
6
+ the truth its rules come from, and a long text read once by one model is not a reliable source.
7
+
8
+ - **Markdown first.** Read the standard as markdown, citing `file:line`; never the PDF. A document not yet in
9
+ markdown is converted first: markitdown for PDF, DOCX or PPTX; docling or pymupdf4llm when its tables come
10
+ out broken.
11
+ - **The converted text stays private**: kept next to the plans, outside every package repository; never
12
+ committed, never quoted or cited in committed text (code, doc, CHANGELOG, skill) or on GitHub. Committed text
13
+ states the behaviour.
14
+ - **A confirmation** (a name, a type, a cardinality the code already follows): one reader, with line references.
15
+ - **A decision that changes what the engine does or accepts** gets the cross-check, once per decision:
16
+ 1. Two or three independent readers on the `standard` tier (at least one on another model or vendor when
17
+ one is available): the same question, no shared notes, a `file:line` for every claim.
18
+ 2. One reader takes the whole relevant part, the others split it by section, so coverage does not rest on
19
+ one model's retrieval.
20
+ 3. An adjudicator on the `strong` tier compares the answers: an agreed claim with matching lines passes; a
21
+ disagreement, or a claim without a line, becomes a question for the user or the domain expert. Runs of
22
+ one model share its biases, so agreement is evidence, not proof.
23
+ 4. The result (question, claims, lines, verdict) goes in the plan's research folder, next to the plan: later
24
+ lots reuse it instead of reading the standard again.
25
+
26
+ The tiers are in [model-tiers.md](model-tiers.md).
27
+
28
+ ## What the station records
29
+
30
+ The hand-over card carries a `standard` line (`@dialecte/cli` 0.3.0). The cli learns where the text is from
31
+ `DIALECTE_STANDARD` (a file or a folder, from the environment only: never committed, never shipped), and the
32
+ station that read it records its word in the hand-over folder:
33
+
34
+ - consulted: `npx dialecte record standard <folder> consulted <note>` - the note says what was checked; the
35
+ `file:line` refs stay in the plan's research folder or the findings ledger, never in committed text. The card
36
+ shows `✓ standard consulted`.
37
+ - none configured: propose to the user to configure one, then `npx dialecte record standard <folder> not-consulted
38
+ <reason>`. The card shows `! standard not consulted`, which never blocks.
39
+ - a standard configured and nothing recorded fails the card (`✗ standard`); with one configured, only `consulted`
40
+ passes, `not-consulted` fails it too.
41
+
42
+ Every hand-over has the line, so every lot records one. A lot that changes nothing a standard rules (tooling,
43
+ wording, an app's UI-facing service): with none configured, `not-consulted` with that reason; with one
44
+ configured, the station still searches the text for what the lot touches and records `consulted` with what it
45
+ found ("nothing in the text rules <what the lot changes>"), never a `consulted` it did not do.