@dialecte/core 0.6.4 → 0.8.0

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

@@ -0,0 +1,152 @@
+<!-- dialecte-skills workspace -->
+
+# Briefs
+
+A brief is everything a sub-agent knows. If you cannot write it clearly, you do not understand the lot
+well enough to hand it off.
+
+Every brief, whatever the station, carries these lines (the templates below assume them):
+
+```
+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
+  hand-over folder or the scratchpad.
+```
+
+## Test-station brief
+
+```
+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.
+
+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>
+Read: this brief and the existing code only - not an implementation, not another agent's notes.
+Worktree: <absolute path>, branch <branch>, base <sha>. Work only there. Never commit, stage, push,
+  `git stash` or any git command that writes the index.
+You may change: the test files of the step, and stubs - new exports with their real types whose body throws
+  `new Error('not implemented: <name>')`. Never a behaviour of the production code.
+Each test calls the code under test inside an `expect(...)` a matcher completes, so a stub's error is a
+  red on the behaviour. Remove every `.only` and `only: true` before `tdd red` (it refuses a file holding one).
+A test that reads the disk, spawns a process or measures time carries an explicit bound with wide slack,
+  a named constant (core: `SOURCE_SCAN_TIMEOUT_MS` in `src/test/test-timing.constants.ts`), never the
+  runner's default timeout.
+Done when `npx dialecte tdd red` records a red for every case of the step; a refused case (passes, missing
+  export, type or syntax error, timeout, stub at import or before the assertion) is fixed in the test.
+Report: the `tdd red` output, unfiltered, and the list of stubs.
+```
+
+## Test-review brief
+
+```
+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.
+
+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
+  (`git -C <worktree> diff <base> -- <test paths>` and the new ones) - not the stubs' callers, not the
+  implementer's plans.
+For each test: the behaviour of the brief it pins; a plausible wrong implementation and whether it fails the
+  test (a weak matcher, an `expect(...)` without a matcher, an assertion on a stub's message, an
+  expectation copied from a guess, a helper or snapshot that holds the expected value); a behaviour of the
+  step without a test; a case of the base the change deletes; a test that reads the disk, spawns a process or
+  measures time without an explicit bound with wide slack (a named constant, several times what it takes on
+  a quiet machine): it passes alone and times out when another suite or a commit hook loads the machine.
+Verdict: approve | back to the test station with the findings. Max ~50 lines, file:line for each finding.
+```
+
+## Implementer brief
+
+```
+You implement lot <id> of <plan path>, as the implement station of the dialecte-lot skill.
+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)
+
+Goal: <one sentence: the behaviour a user or caller gets>
+Spec: <the plan section(s) to read, by path and heading; the decisions that bind it>
+Worktree: <absolute path> (made with `dialecte worktree add`), branch <branch>, base <sha>. Work only there. Never commit, stage, push,
+  `git stash` (one stash is shared by every worktree and session) or any git command that writes the index
+  (`git add`, `git rm`, `git reset`, `git restore`, `git checkout --`): read the base with
+  `git show <base>:<file>`.
+Scope: <files / folders this lot may touch>; out of scope: <what a neighbour lot owns>
+Reuse first: <existing functions, hooks, helpers you already know apply - name them>
+Tests: written by the test station, red (`npx dialecte tdd status`), approved by the test review. Change
+  production code only, until `npx dialecte tdd green`; a test you find wrong goes back to the test station
+  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
+  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.
+Report: the implement report shape of dialecte-lot, nothing else.
+```
+
+## Reviewer brief
+
+```
+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.
+
+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
+  orchestrator only. Raise nothing fixed or accepted there again unless the fix is wrong; propose rows, do not
+  write the file.
+Round 1 - full review, every severity. Diff: `git -C <worktree> diff <base>` and untracked files
+  (`git status --porcelain`); compare each file with `git show <base>:<file>`. Answer each angle, even empty:
+  correctness; test soundness (each test fails for the right reason); the consumer's view (build the package:
+  run the build, then read the built dist, the emitted .d.ts, the docs - is the change there?); code rules;
+  docs and CHANGELOG against the code.
+Later rounds - delta review of the fix diff and its blast radius only. Start from each fix's blast-radius line in
+  the findings ledger: does it widen, exclude or replace more than its finding needed, does it reopen a row it did
+  not name? HEAD is still the base; the tree round n-1 reviewed is the snapshot
+  <hand-over folder>/round-<n-1>/ (files at repository-relative paths, beside it round-<n-1>.deleted,
+  NUL-separated). Fix diff, per file (`--no-index` exits 1 on differences and on a missing side alike): in both,
+  `git diff --no-index --no-color --no-ext-diff round-<n-1>/<file> <worktree>/<file>`; not in round-<n-1>/ (at
+  the base then), `git -C <worktree> diff --no-color --no-ext-diff HEAD -- <file>`, or /dev/null as the left
+  side for a file the base does not have or that round-<n-1>.deleted lists; gone from the worktree, /dev/null as
+  the right side (from cli 0.2.0, `dialecte review delta <folder> --round <n>` prints that diff per file).
+  Throwaway worktree: <path - from `dialecte review delta <folder> --round <n> --worktree` (cli 0.2.0; the
+  fixer's, when it made one), or made by the orchestrator with `dialecte worktree add <repository> <lot-branch>-round-<n-1> --from
+  <base>`, round-<n-1>/ copied over, `git -C <throwaway> rm -q --pathspec-from-file=<folder>/round-<n-1>.deleted
+  --pathspec-file-nul` | none>. Verify each fix: copy its new test file in and run it there - it must fail - and in
+  the lot's worktree, where it passes; with none, read the snapshot and say the guard was reasoned, not run.
+  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).
+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`).
+Answer: would you approve? Use the review report shape, with a severity per finding and the proposed findings-ledger rows.
+Max ~80 lines, most severe first, file:line for each finding.
+```
+
+## Fix-mode brief
+
+```
+Fix mode for lot <id> (round <n>). Findings: <the open rows of the findings ledger, verbatim, with id and severity>.
+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.
+Blast radius, one line under each fix: what it widens, excludes or replaces (a pattern, a list, an include, a type
+  now matching more or less; the earlier code or fix it replaces), and the findings-ledger rows it touches - its
+  own and any other whose code it changes ("none beyond <id>" when so). The next round's reviewer starts there.
+A fix's new test: write it before the fix and take its red with `npx dialecte tdd red`; when production already
+  holds the fix, run it on round <n>'s tree - `npx dialecte review delta <hand-over folder> --round <n+1>
+  --worktree` (cli 0.2.0; else the throwaway I made: <path>) makes the throwaway and prints its removal command;
+  copy in the test file and the test code it imports - where it must fail on its assertion, and report "red on
+  round-<n>/: <failing line>" with the throwaway's path. Never edit production back to the old behaviour to get
+  a red.
+Never commit, stage, push, `git stash` (one stash is shared by every worktree and session) or any git command
+  that writes the index; read the base with `git show <base>:<file>`.
+Then the fast gate, and the report per finding.
+```

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

@@ -0,0 +1,52 @@
+<!-- dialecte-skills workspace -->
+
+# Model tiers
+
+A brief names a **tier**, never a model: the same skill serves every coding agent, whatever its vendor.
+Which model a tier is for your project comes from `npx @dialecte/cli models` (the map for the vendor the
+project uses, `--json` for a script); read it there instead of guessing or writing a name in a brief.
+
+## The tiers
+
+| Tier       | For                                                                                                                                                                                                           |
+| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fast`     | search and locate, graders with a schema, 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                                                                                   |
+| no agent   | gates, counts, hashes, generated blocks, scaffolds, hand-over scripts: a `dialecte` command run by the station that needs it, never a sub-agent spawned to read its output                                    |
+
+## Station to tier
+
+"Usual" is what the station's agent or command took on the runs measured so far; "deadline" (about 2-3x
+usual) is when the orchestrator looks at a background run (Rules, below). A command timed on earlier runs
+gets 3x that duration instead.
+
+| Station                                   | Tier                                                                            | Usual                        | Deadline                                          |
+| ----------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------- |
+| 0 Orchestrate                             | strong                                                                          | -                            | -                                                 |
+| 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                                            |
+| 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                                   |
+
+## Rules
+
+- **Per station**, not per lot: one lot spawns agents on several tiers.
+- **Escalate, do not start high.** A station starts at its tier; after a failed round it may go one tier up,
+  and the report says so. The next lot starts at the table's tier again.
+- **Never down-tier a correctness review** to save tokens: pass 1 stays on strong.
+- **Effort is a second knob**: low for fast-tier jobs, the default elsewhere, high only for the review and
+  adjudication.
+- **The brief names the tier** (`Tier:` in [briefs.md](briefs.md)); the orchestrator spawns accordingly.
+- **Every background run has a deadline**: the station's deadline above, or three times a duration measured
+  on earlier runs of the same command (a hook, a gate, a bench). The deadline is when you look, never a
+  reason to kill: a run is stopped on what you see (no new output and no CPU time gained by its process tree),
+  never on the clock. See "Deadlines" in the skill.

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

@@ -0,0 +1,51 @@
+<!-- dialecte-skills workspace -->
+
+# Retro
+
+The loop that makes the skills better instead of just used. Run it at the end of every lot (short) and of
+every larger change (complete). Write the moment a mistake is caught, not from memory at the end.
+
+## 1. Facts first
+
+- **Loops**: review rounds per lot; what each round found.
+- **Late findings**: what review (or the user) caught that an earlier station should have - and which one.
+- **False greens**: a gate that said ok while something was wrong (wrong tsconfig, filtered output, a test
+  green by accident). These are the most expensive findings.
+- **Corrections by the user**: verbatim, with what they corrected.
+- **Plan drift**: deviations, and whether they were a plan flaw or a discovery.
+- **Token ledger**: sub-agent tokens per station, from the completion notices (implementer, each review and
+  fix round, skill-eval runs, graders), the tier each ran on, and every escalation with its reason. No fixed
+  budget: the ledger is what shows where a lot's tokens went, and what later lots compare against.
+
+The **hand-over message** carries the ledger as one usage line for the user, for example "this lot cost
+~1.1M tokens: implementer 450k, review 320k, fix 90k, evals 240k". A station far above the others in that line is a
+retro fact too: why it ran long, and whether its tier or its brief was wrong.
+
+## 2. From facts to improvements
+
+For each pattern, name the responsible skill (or script) and the smallest change that would have
+prevented it:
+
+| Category  | Means                                                  | Fix goes to                                                                |
+| --------- | ------------------------------------------------------ | -------------------------------------------------------------------------- |
+| skill     | an instruction was missing or wrong                    | a before/after edit of that skill, with an eval case that fails without it |
+| tooling   | a script or a check would enforce it better than prose | a cli command, a gate, a guard in the hand-over script                     |
+| knowledge | a domain or tool fact nobody had                       | the package docs, or the skill reference that owns the topic               |
+| one-off   | unusual, no change                                     | the retro entry only                                                       |
+
+No "be more careful" edits: if you cannot point to a missing instruction, it is not a skill improvement.
+
+## 3. Entry shape
+
+```
+### <id> <one-line title>
+- What happened: facts, who caught it, the cost.
+- Root cause: why it slipped through.
+- Category: skill | tooling | knowledge | one-off
+- Fix: the smallest change that prevents it (which skill / script / rule).
+- Status: open | applied (<where>) | dropped (<why>)
+```
+
+Keep the entries where the team keeps its retro log (a folder outside the repositories, so plan tags and
+references are allowed there), one file per lot or session, with an index. Skill edits are drafted
+before/after, applied on the user's approval, one per finding.

package/dist/project/io/import-document.d.ts

@@ -1,7 +0,0 @@
-import { ImportDocumentParams, ImportDocumentResult } from '../types';
-/**
- * Import a File into the project: register document, parse XML, persist records, resolve root.
- * Pure orchestration - no class state mutation.
- */
-export declare function importDocument(params: ImportDocumentParams): Promise<ImportDocumentResult>;
-//# sourceMappingURL=import-document.d.ts.map

package/dist/project/io/import-document.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"import-document.d.ts","sourceRoot":"","sources":["../../../src/project/io/import-document.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAA;AAG1E;;;GAGG;AACH,wBAAsB,cAAc,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAsDhG"}

package/dist/test/assert-xml/types.d.ts

@@ -1,2 +0,0 @@
-export type NsResolver = (prefix: string | null) => string | null;
-//# sourceMappingURL=types.d.ts.map

package/dist/test/assert-xml/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/test/assert-xml/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,KAAK,MAAM,GAAG,IAAI,CAAA"}