speccle 0.11.0 → 0.15.0

package/skills/review/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: review
+description: Review a change set the way the outer loop does — fan a panel of lenses over the working diff, let `oracle risk` decide whether a human is needed, then below that threshold fix what the lenses find (re-running the checks-gate after each fix and reverting any that goes red) and above it report findings and stop, closing with an overruleable summary that proposes a remedy for each finding — recalled from and recorded to the remedy record — and records the change to the calibration record. Use when the user wants to review a branch or the pending change, asks to "review this", "review my changes", "run the lenses", find-and-fix issues before a PR, or check a change set for correctness, security, accessibility, architecture, performance, test-quality, or house-convention problems.
+allowed-tools: Read(/${CLAUDE_PLUGIN_ROOT}/skills/*/references/**)
+---
+
+# review
+
+The outer loop. Its unit is the **change set** — the branch or PR's pending change,
+not a slice — which is why it is separate from `feature`. It fans a panel of **lenses**
+over the working diff, and — gated by the change's **risk score** — either fixes what it
+finds or reports and stops for a human. It generates feedback; it does not itself change
+the inner loop.
+
+Speccle's words are fixed and mandatory: "change set", not "diff" or "PR"; "lens", not
+"reviewer" or "rule"; "finding", not "issue" or "comment"; "remedy", not "fix" alone;
+"risk score" / "review threshold" / "floor"; "escalate", never "de-escalate". Speccle's
+posture is **announce, never gate**: below the threshold the fixes just land and the
+summary reports them; there is no "apply? y/n".
+
+## 1. Resolve the oracle
+
+Once, in this order, and reuse what works:
+
+1. `<repo-root>/node_modules/.bin/speccle` — the repo's own pinned copy. A devDependency
+   is never on `PATH` in this shell, so test for the file; in a monorepo check the package
+   you are working in as well as the root. It wins over a global install: the pin is a
+   committed choice, and rules change between versions.
+2. `speccle` on `PATH` — a global install.
+3. Otherwise, from a clone of the speccle repo, run it from source — Node ≥ 24 executes
+   TypeScript directly: `node <speccle-repo>/packages/oracle/src/cli.ts`.
+
+If none resolves, point the user at the install steps in Speccle's README and stop. If
+`.speccle/lenses/` is missing, the repo was never initialized for review — offer
+`speccle init` and stop.
+
+## 2. The change set
+
+Everything here runs over the same change set: the working tree's pending change against
+its last commit. Read it once — `git status --porcelain --untracked-files=all` for the
+files, `git diff HEAD` for the lines — and hand the changed files and their diff to every
+lens. A finding must anchor to a **changed line**; a lens does not audit the whole repo.
+
+If the working tree is clean, there is nothing to review — say so and stop.
+
+## 3. Risk — the authority gate, before any fixing
+
+Fix authority is not a global setting; it depends on the change. Decide it first, because
+it decides whether the panel may fix at all.
+
+```sh
+<oracle> risk <path> --json
+```
+
+This returns the deterministic **floor**: `score`, `threshold`, `humanRequired`, and the
+spec-aware `signals` that fired, each with its evidence. Then apply the **risk lens**
+(`.speccle/lenses/risk.md`) yourself: read the diff for the consequential change no signal
+could see, and emit its one escalation decision. The lens may **raise** the floor or
+require a human outright; it may **never lower** either. A concern that the floor is too
+high goes in the summary for the human — you do not act on it.
+
+The verdict a human is required when **any** of these holds: `risk.humanRequired` is true,
+the risk lens set `requireHuman`, or `score + raiseFloorBy ≥ threshold`.
+
+- **Below the threshold, no escalation** → `review` may fix unasked (§5).
+- **At or above, or the lens escalated** → `review` still runs the panel to report, but
+  **fixes nothing**; a human is required.
+
+Both the computed floor and any escalation must be legible in the summary — a risk verdict
+with no visible reasoning is not auditable.
+
+## 4. The lens panel — fan out over the diff
+
+Fan out one subagent per lens in `.speccle/lenses/*.md`, in parallel — this is the local
+driver, so the panel runs as subagents in this session, no API key. Skip two:
+
+- `risk.md` — already applied in §3; it escalates authority, it is not a finding lens.
+- `house-conventions.md` **when it still reads as the shipped template** — its body carries
+  the `speccle:lens-template` marker until a repo authors it. An unauthored lens is inert;
+  skip it and note that the repo has not written its house-conventions lens yet.
+
+Each subagent's prompt carries the lens file verbatim (its stance, what to look for, how to
+report), the changed files and their diff, and the instruction to return findings anchored
+to changed lines only, in the shape the lens describes: `path:line`, severity, what, why,
+the fix, and a remedy route. A lens that finds nothing returns an empty list — the common,
+valid result. Collect every finding across the panel.
+
+## 5. Fix — only with authority, and never without the checks-gate
+
+If §3 said a human is required, **fix nothing**; go to §6 and report.
+
+Otherwise fix each finding, smallest change first, and guard every one:
+
+1. Apply the fix the finding names.
+2. **Re-run the checks-gate** — resolve the same oracle and run `<oracle> lint` on any
+   governed slice the fix touched, `<oracle> claims <root>`, `<oracle> verify <root>` (the
+   cross-file invariants), and the project's own test suite.
+3. **Green** — keep the fix. **Red** — **revert it, do not salvage**: restore the file to its
+   pre-fix state and carry the finding forward as unfixed. A fix that cannot pass the gate is
+   the human's call, not a thing to patch around.
+
+Batch sensibly, but keep each fix independently revertible — a fix you cannot back out on
+its own is one you cannot safely apply. The fixes join the working change set; `review` does
+**not** commit — the change set is the human's or the inner loop's to land.
+
+## 6. Route each finding to a remedy
+
+For every finding — fixed, reverted, or left for the human — name the durable artefact that
+stops the class recurring, routed on **what the finding is**, never on a count, the same
+posture `strengthen` takes to a surviving mutant. The **remedy record** is the meta loop's
+memory of that routing: consult it before deriving, add to it after applying.
+
+**Recall first — answer a repeat the way you answered it before.** Give the finding a short,
+stable class handle (kebab-case, e.g. `missing-model-roundtrip-test`) and ask the record:
+
+```sh
+<oracle> remedy recall <path> --class <handle>
+```
+
+A hit is the known-correct remedy — reuse its route and artefact rather than re-deriving, so
+the same finding gets the same answer. A miss means route it fresh:
+
+- a deterministic, cross-file invariant → an `oracle verify` check in `.speccle/checks/`.
+- behaviour a criterion should own → a new acceptance criterion, and its tagged test, in the
+  owning `SPEC.md`.
+- a dimension a lens missed or stated too weakly → sharpen the lens in `.speccle/lenses/`,
+  the house-conventions lens above all.
+- a genuine one-off → none.
+
+**Then record what you applied**, so the next review recalls it:
+
+```sh
+<oracle> remedy record <path> --class <handle> --finding <what> --fix <what you did> \
+  --route <check|criterion|lens|none> [--artefact <ref>]
+```
+
+`--artefact` names the prevention home — the `.speccle/checks/` or `.speccle/lenses/` path, or
+the `SPEC.md` criterion id — and is required for every route but `none`. Record the remedies you
+**applied** this run; a finding left for the human (§3 required one, so nothing was fixed) is
+proposed in the summary, never recorded — the record holds enacted remedies, not intentions, the
+same honesty §8 keeps for the verdict.
+
+## 7. Summary — announce, never gate
+
+Render one screen, in product voice. The human rules by reading it, not by being asked:
+
+1. **The risk verdict** — `score` against `threshold`, the floor's fired signals with their
+   evidence, any risk-lens escalation with its reason, and whether a human was required.
+2. **Every finding** — its lens, `path:line`, severity, what and why, and its outcome:
+   **fixed**, **reverted** (the checks-gate went red — say what failed), or **left for the
+   human** (a human was required, so nothing was fixed).
+3. **The proposed remedy** per finding (§6).
+4. **The checks-gate now** — green or red, named.
+
+There is no approval gate. Below the threshold the fixes already landed and the human
+reverts what the summary makes them regret; at or above it nothing was fixed and the findings
+await the human. Either way the summary is the whole interaction — overruleable, never a
+"proceed? y/n".
+
+## 8. Calibrate — record the change, then surface the evidence
+
+The review is the outer loop's eyes; the **calibration record** is its memory — one entry per
+reviewed change, the evidence a **review threshold** earns a move on. Close every review by
+adding this change to it.
+
+The floor is known (§3) and the panel's outcome is known (§4). The one thing neither can
+answer is the honest verdict — _did this change actually need a human?_ That answer is the
+human's, and the record is worthless without it, so never invent it:
+
+```sh
+<oracle> calibrate record <path> --found-real <true|false> --needed-human <true|false> [--escalated]
+```
+
+- `--found-real` — true when any lens returned a real finding this run; you know this.
+- `--escalated` — include it only if the risk lens escalated the floor in §3.
+- `--needed-human` — the human's honest call, whatever the floor said. With a human here to
+  answer, ask once and record it; with none, print the command for them to run and stop. A
+  threshold that rose on a guessed verdict is worse than one that never rose.
+
+Then read the record back and fold its proposals into the close:
+
+```sh
+<oracle> calibrate report <path>
+```
+
+It names the signals that have never fired on a change that mattered, the signals that fired
+on every change that needed a human, and the threshold the record would support. These are
+**evidence, not instructions**: escalation is free, but only a human moves a weight or the
+review threshold, and only on this evidence. Surface them so ignoring them is a choice — never
+act on them here.

package/skills/spec-feature/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: spec-feature
+description: Draft or amend a feature's markdown contract — SPEC.md, CONTEXT.md, AGENTS.md, decisions/ — from a plan or any raw input, lint it clean with the oracle (product-voiced When/Then statements included), and hand back the criteria, without writing any tests or code. Use when the user wants a spec drafted or amended but not yet implemented, wants acceptance criteria written for a behaviour, or says "spec this", "draft the criteria", "add a criterion to this slice".
+allowed-tools: Read(/${CLAUDE_PLUGIN_ROOT}/skills/*/references/**)
+---
+
+# spec-feature
+
+Produce the markdown contract — `SPEC.md`, `CONTEXT.md`, `AGENTS.md`, `decisions/` —
+for one feature, and lint it clean. Stage 2 of the `feature` pipeline, and complete
+on its own when the user wants a spec without an implementation. This skill writes
+markdown only — tests and code are `implement-feature`'s job.
+
+In the pipeline this skill runs in its own subagent session: the hand-off in the
+prompt and the feature folder on disk are everything — there is no planning
+conversation to consult, and nobody to ask mid-run. The final message is the
+hand-back.
+
+The shape of the contract is fixed by the convention, bundled beside this skill. Read
+`${CLAUDE_SKILL_DIR}/references/convention.md` before drafting — it is the written
+contract, and this skill only restates the parts drafts get wrong.
+
+Speccle's words are fixed and mandatory: "criterion id", not "tag"; "statement", not
+"title"; "body", not "notes"; "lint violation", not "error" or "warning"; "amend",
+not "edit" or "update".
+
+## 1. Start from a plan
+
+In the pipeline, the hand-off carries the route, the feature folder, the key, the
+scope, and every key decision the plan settled — each marked agreed or defaulted, the
+cross-criterion ones already captured as ADRs in the slice's `decisions/`, the
+per-behaviour ones noted for a criterion body. Land those notes where they belong as
+you draft; flag anything marked defaulted again in your hand-back. A decision the
+hand-off genuinely leaves open is taken on its recommendation and flagged defaulted —
+never guessed silently, and never a reason to stall.
+
+Standalone, settle those the way `plan-feature` does — route on where the behaviour
+lives, read every other `SPEC.md`'s frontmatter before picking a key, and put key
+decisions the input leaves open to the user before drafting. Record each by the
+routing rule below: spanning criteria → an ADR in `decisions/`, about one behaviour →
+that criterion's body. No key decision lives only in the conversation.
+
+If the input is already a conventioned `SPEC.md`, adopt it as-is. Do not "improve"
+the criteria; the human already owns them.
+
+## 2. Draft (new) or amend the contract
+
+**New route** — scaffold the convention's shape: `SPEC.md`, `CONTEXT.md`, and
+`AGENTS.md` at the feature root, `decisions/` when the first cross-criterion choice
+lands. The parts worth restating because they are where drafts go wrong:
+
+- **Statements speak product, When/Then by default.** "When X, Y" — the trigger,
+  then the outcome, readable by someone who has never seen the code. A simple
+  invariant may stay plain declarative ("An empty basket totals zero"). Code-level
+  precision that is genuinely contractual — exact messages, ordering, rounding,
+  identifiers — goes in the body, never the statement; the `code-voice` lint rule
+  enforces the boundary.
+- **A statement is one testable clause.** If you cannot picture the single assertion
+  that fails when it breaks, it is not one criterion. "Tax rounds half-up and the
+  basket rejects over 100 items" is two criteria wearing one heading.
+- **Ids are names, not order.** A new criterion takes the next never-used number under
+  its key. Never renumber, never reuse — deleting `[CHECKOUT-2]` retires that number.
+- **The body is free and never linted.** Rationale, edge cases, worked examples.
+  Prefer a worked number over an adjective — and make it one the reader cannot
+  misread: "three line items of £1.99 at 20% → £1.20 tax; taxing the £5.97 basket
+  total would give £1.19" beats "3 × £1.99 → £1.20", which silently depends on
+  whether that is one line item or three.
+- **The routing rule.** About a word → `CONTEXT.md`, a glossary only — every term
+  gets an _Avoid_ line naming the synonyms the feature will not use.
+  About one behaviour → that criterion's body. A choice spanning criteria → an ADR in
+  `decisions/`.
+- **`SPEC.md`'s intro prose carries the product intent** — what the feature is for
+  and its scope, a paragraph, not a line. There is no separate product document; this
+  is where a future reader learns why the slice exists.
+- **`AGENTS.md` states how to work the slice**, not what it does: how to run its
+  tests, and where the contract lives. Behaviour stays in `SPEC.md` — duplicating it
+  here is drift waiting to happen.
+
+`SPEC.md`, `CONTEXT.md`, and `AGENTS.md` are the floor, even for a tiny feature;
+`decisions/` appears with the first decision.
+
+**Amend route** — the contract already exists; change it in place, never re-scaffold:
+
+- **New criteria take the next never-used numbers** under the slice's existing key.
+  Read the whole spec first — including the numbers no longer present; a deleted id
+  stays retired.
+- **A reworded statement keeps its id only if it promises the same behaviour**,
+  sharpened. A statement that now promises something different is a retire-plus-draft:
+  the old id goes, a new id arrives, and the old id's tests go with it (flag them for
+  `implement-feature`).
+- **Adopt the slice's language.** Read its `CONTEXT.md` and write new criteria in
+  those terms; add a glossary entry only for a genuinely new term, with its _Avoid_
+  line. Introducing a synonym for an existing term is the drift the glossary exists
+  to prevent.
+- **A change that spans criteria gets an ADR** in the slice's `decisions/`, same as
+  on the new route.
+- **Leave unrelated criteria untouched.** The diff of an amendment reads as the
+  request: statements the request did not mention do not change.
+
+## 3. Lint until clean
+
+Resolve the oracle once, in this order, and reuse what works:
+
+1. `<repo-root>/node_modules/.bin/speccle` — the repo's own pinned copy, put
+   there by `strength init`. A devDependency is never on `PATH` in this shell, so test
+   for the file; in a monorepo check the package you are working in as well as the
+   root. It wins over a global install: the pin is a committed choice, and lint rules
+   change between versions.
+2. `speccle` on `PATH` — a global install.
+3. Otherwise, from a clone of the speccle repo, run it from source — Node ≥ 24 executes
+   TypeScript directly, so no build is needed:
+   `node <speccle-repo>/packages/oracle/src/cli.ts`.
+
+If none resolves, point the user at the install steps in Speccle's README and stop.
+Do not hand-check the convention in the oracle's place: a spec that has not been
+linted has not been linted, and claiming otherwise is the one thing this workflow
+cannot survive.
+
+```sh
+<oracle> lint <feature-folder>
+```
+
+Fix and re-run until it reports clean. Exit `0` clean, `1` violations, `2` usage
+error. `--json` gives `{ root, files, violations, clean }` with each violation
+carrying `rule`, `file`, `line`, `message` — parse that rather than scraping the
+human output.
+
+Quality violations (`weasel-wording`, `compound-criterion`, `unmeasurable`,
+`code-voice`) judge the heading statement only. When one fires, rewrite the
+statement — do not move the offending words down into the body to dodge the rule.
+Two of them deserve their own note:
+
+- A `compound-criterion` usually means you owe the spec a second criterion, not a
+  shorter sentence.
+- A `code-voice` violation means the statement names the mechanism. Push the code
+  fragment into the body — where that precision belongs — and say what the user
+  observes instead: "When a basket exceeds 100 line items, checkout rejects it", not
+  "`addItem` throws `BasketLimitError`".
+
+`unmeasurable` does not police vocabulary — any domain verb passes ("a refund
+**credits** the customer…"). It fires only on a statement that asserts nothing: a
+vacuous predicate ("refunds **are handled**") or a bare property ("the dashboard **is
+beautiful**"). Say what is observably true instead; the rule is telling you the
+criterion has no outcome to test, not that it dislikes your wording.
+
+The rules are fixed and unconfigurable, and there is one severity: a spec lints clean
+or it does not.
+
+## 4. Hand back the criteria
+
+In the pipeline, the hand-back is your final message: every criterion drafted,
+amended, or retired — ids and statements — every decision recorded and where, and
+each one flagged that was defaulted rather than agreed. The orchestrator shows it to
+the human; you do not wait, and you do not ask.
+
+Standalone, the same content is the **spec summary**, announced in chat: the human
+owns the criteria, and that ownership is exercised by interrupting or amending — not
+at a blocking pre-approval. Treat "looks good, and also…" as a change request: amend
+the spec, re-lint, announce again. Say what the contract does not yet have: tests
+and code are `implement-feature`'s job, and nothing is claimed until it runs.
+
+When the input was already a conventioned `SPEC.md` adopted unchanged, there is
+nothing new to announce; say you adopted it and move on.

package/skills/spec-feature/references/convention.md

@@ -0,0 +1,239 @@
+<!-- Generated from docs/convention.md by scripts/sync-plugin-references.mjs — do not edit.
+     Edit the source and run `pnpm sync:plugin-refs`. -->
+
+# The Speccle convention
+
+The written contract every skill and every Speccle tool implements. Terminology is
+defined in `CONTEXT.md`; decisions behind this shape are in
+`docs/adr`.
+
+## The feature folder
+
+A feature is a directory **named for the feature**, owning one vertical slice. The name
+announces the slice — `scanner/`, never an unnamed catch-all like `src/` or `lib/` —
+and holds even when a project has only one feature: the slice is self-announcing, and a
+second feature has an obvious home beside it.
+
+Every feature folder has the same shape:
+
+```
+scanner/
+├── SPEC.md          ← the acceptance criteria
+├── CONTEXT.md       ← the feature's language (a glossary, nothing else)
+├── AGENTS.md        ← how an agent works the slice
+├── decisions/       ← the feature's ADRs, one file per decision
+│   └── 0001-<slug>.md
+└── src/
+    ├── scanner.ts
+    └── scanner.test.ts
+```
+
+The root holds the markdown contract and nothing else. All code and tests sit in
+`src/`, tests beside the code they defend, and the code subfolder is always named
+`src` — every feature folder in every project opens the same way. `decisions/` appears
+with the feature's first decision; the other four entries are the floor, even for a
+tiny feature.
+
+Inside `src/`, subfolders are allowed but not the default
+(ADR-0037). Keep
+`src/` flat while it holds **ten files or fewer** directly — count the code and test
+files sitting in it, subfolders excluded. The file that would make it eleven triggers
+grouping: gather the code into shallow (prefer one level), purpose-named subfolders,
+and the same ten-file limit applies within each subfolder. A `src/` that has grown into
+a pile is often a signal to split the slice into siblings instead; nest when it is
+genuinely one cohesive feature that simply carries many files. Tests stay beside the
+code they defend at whatever depth it sits.
+
+Everything about the feature lives inside the subtree. An agent landing in the folder
+needs nothing else to understand it — and `AGENTS.md` is where it starts reading.
+
+## SPEC.md
+
+```markdown
+---
+key: CHECKOUT
+---
+
+# Checkout
+
+Optional intro prose about the feature.
+
+## [CHECKOUT-1] When a line item is taxed, tax rounds half-up
+
+Tax is computed per line item and rounded half-up to 2dp before summing.
+
+Edge cases:
+
+- three line items of £1.99 at 20% → £1.20 tax; taxing the £5.97 basket total would give
+  £1.19
+
+## [CHECKOUT-2] An empty basket totals zero
+```
+
+Rules:
+
+1. **Frontmatter declares the feature key**: `key: <KEY>` where `<KEY>` matches
+   `[A-Z][A-Z0-9]{1,9}`. Keys are unique across the repo.
+2. **Each criterion is an H2**: `## [KEY-n] <statement>`. The statement is one testable
+   clause — single behaviour, no weasel words, measurable.
+3. **Statements speak product, defaulting to a When/Then shape**
+   (ADR-0032):
+   "When X, Y" — the trigger, then the outcome, readable without seeing code. A simple
+   invariant may stay plain declarative (`An empty basket totals zero`). Code-level
+   precision that is contractual — exact messages, ordering, regexes — lives in the
+   body, never the statement.
+4. **The body is free.** Rationale, edge cases, examples — anything about that one
+   behaviour. A body may be empty.
+5. **Ids are names, not order.** Document position carries order. A new criterion takes
+   the next never-used number under its key. An id is never renumbered or reused —
+   deleting `[CHECKOUT-2]` retires the number forever.
+6. **H2s in a spec are criteria.** Non-criterion structure belongs in intro prose,
+   criterion bodies, or `CONTEXT.md`.
+
+## CONTEXT.md (per feature)
+
+The feature's glossary, in the style of this repo's own root `CONTEXT.md`: the domain
+language — each term defined once, with an _Avoid_ line naming the synonyms not to use.
+
+A glossary only. Decisions never live here — they are ADRs in `decisions/`
+(ADR-0021). The
+boundary: about a word → `CONTEXT.md`; about one behaviour → that criterion's body in
+`SPEC.md`; a choice spanning criteria → `decisions/`.
+
+## AGENTS.md (per feature)
+
+The slice's agent-facing entry point, following the cross-tool convention of the same
+name. It orients in one screenful, stating only what the folder cannot show:
+
+- what the slice does — a sentence or two
+- how to run its tests (and any other commands the slice needs)
+- where the contract lives: `SPEC.md` for the criteria, `CONTEXT.md` for the language,
+  `decisions/` for the choices — and that tests claim criteria by `[KEY-n]` token
+
+Facts about _working_ the slice belong here; facts about the feature's _behaviour_
+belong in `SPEC.md`. Duplicating either in the other is drift waiting to happen.
+
+## decisions/ (per feature)
+
+The feature's architecture decision records: choices that span criteria, one numbered
+file per decision — `decisions/0001-<slug>.md`, in the same form as any ADR (status,
+context, decision, consequences). The folder appears with the first decision. A choice
+about one behaviour is not a decision record — it is that criterion's body.
+
+## Test linking
+
+A test defends a criterion when the criterion id appears anywhere in its **full
+concatenated name** — enclosing group titles included. One
+`describe('[CHECKOUT-1] tax rounding', …)` claims every test inside it. Mutation and
+coverage reports already carry full names, so the join is mechanical.
+
+What counts as a test file, and what counts as its name, is the **test dialect**'s
+business (ADR-0038).
+Where a framework gives a test a string name, the id is claimed bracketed —
+`[CHECKOUT-1]`. Where the name _is_ an identifier, the id takes its identifier-safe
+spelling: `func test_CHECKOUT_1_taxRounds()` claims `CHECKOUT-1`. The two spellings are
+one id, not two — `SPEC.md` headings and every report use the bracketed form
+(ADR-0039).
+
+## Spec discovery
+
+Tools find every `SPEC.md` under the target root. Directories named `node_modules`,
+`dist`, `fixtures`, or `__fixtures__` — and dot-directories — are never entered. The
+skip list is fixed, not configuration
+(ADR-0016): a project that
+fixtures deliberately dirty specs for its own tests still lints clean at its root,
+and a feature directory may not take one of the skipped names.
+
+## Lint
+
+`oracle lint` enforces this contract deterministically. Fixed rules, one severity, no
+configuration. The rule set:
+
+| Rule                 | Judges                                                         |
+| -------------------- | -------------------------------------------------------------- |
+| `missing-key`        | Frontmatter `key` absent or malformed                          |
+| `key-collision`      | Two specs declare the same key                                 |
+| `key-mismatch`       | A criterion id's key differs from the spec's declared key      |
+| `malformed-id`       | H2 without a well-formed `[KEY-n]` token                       |
+| `duplicate-id`       | The same id appears twice                                      |
+| `empty-statement`    | Criterion heading has a token but no statement                 |
+| `weasel-wording`     | Statement hedges (`should`, `appropriately`, `as expected`, …) |
+| `compound-criterion` | Statement contains more than one testable clause               |
+| `unmeasurable`       | Statement asserts nothing observable                           |
+| `code-voice`         | Statement reads as code rather than product language           |
+
+Quality rules (`weasel-wording`, `compound-criterion`, `unmeasurable`, `code-voice`)
+judge the heading statement only — the body is never linted.
+
+`compound-criterion` exempts one bare `and`/`or` — a compound noun phrase names one
+thing (`restores stock and credit`). A second bare conjunction in the main clause flags:
+it reads as a list of behaviours (`restores stock and credits the customer and emails
+them`). Conjunctions inside a condition (`when the card is expired and the retry limit
+is reached`) qualify one outcome and are not counted.
+
+`unmeasurable` never allow-lists the verbs a statement may use. It flags a closed list of
+predicates that name activity without an outcome (`is handled`, `works`, `supports`, …)
+and main clauses that name a property (`The dashboard is beautiful`). Any other verb
+passes, including a domain verb the rule has never seen (`a refund credits the
+customer`). It under-flags by design
+(ADR-0010).
+
+`code-voice` judges the raw statement — here a code span is the strongest signal, not a
+stripped literal. Signals, first match wins: a code span; a file path, recognised by a
+closed extension list (`cjs`, `css`, `html`, `js`, `json`, `jsx`, `md`, `mjs`, `sh`,
+`toml`, `ts`, `tsx`, `txt`, `yaml`, `yml`); an identifier — camelCase with at least two
+leading lowercase letters (brand names like iPhone pass), snake_case, or call
+parentheses. Plain acronyms (JSON, HTTP) and unlisted extensions pass — the rule
+under-flags by design
+(ADR-0032).
+
+## Supported stacks
+
+Speccle is **multi-language across a supported set, not language-agnostic**. A repo
+declares which test dialect it is on; it never declares how that dialect works, so a
+clean `claims` run means the same thing in every repo
+(ADR-0038). An
+unsupported stack is unsupported, and says so.
+
+Two frontiers, and they are not the same:
+
+- **The contract, the lint, and the claim join** reach every supported dialect.
+  `ts-vitest` reads `describe`/`it`/`test` titles out of `*.test.*` and `*.spec.*`
+  files. `swift` reads Swift Testing `@Test("…")` and `@Suite("…")` display names, and
+  XCTest `func test…()` identifiers, out of `*Tests.swift` files and anything under a
+  `Tests` directory.
+- **The oracle-strength heatmap** reaches TypeScript. It needs a mutation tool that
+  attributes coverage per test: StrykerJS with `perTest` coverage analysis, plus
+  Istanbul `json-summary` coverage. Elsewhere the reports are simply missing, and the
+  heatmap degrades on its own.
+
+Adding a language is a Speccle change with tests behind it, never a regex a repo
+supplies.
+
+## Repo facts
+
+Two things Speccle needs are true about a repo, not decidable by Speccle: which **test
+dialect** the repo is on, and the **suite command** that runs its tests — the checks gate
+cannot infer `xcodebuild test -scheme Ladder`. They live in `.speccle/config.json` at the
+repo root:
+
+```json
+{
+  "dialect": "swift",
+  "suite": "xcodebuild test -scheme Ladder",
+  "overrides": [{ "path": "web", "dialect": "ts-vitest", "suite": "pnpm test" }]
+}
+```
+
+`speccle init` auto-detects the dialect — `swift` from a `Package.swift`, `ts-vitest`
+otherwise — and a default suite command, then **writes the result down**: the written
+record is the source of truth, never the detection, and `init` never overwrites a config
+it finds. A mixed-language tree corrects the defaults under a subtree with `overrides`,
+where the longest matching path wins
+(ADR-0040).
+
+This is the one thing Speccle reads from a repo, and it never grows into a knob on
+judgement. "Speccle has no configuration" is really **"Speccle has no configurable
+judgement"**: a dialect name or a shell command is a fact — Speccle cannot know it and
+there is nothing to game — while a lint rule or the claim join decides whether you pass,
+and stays fixed so a clean run keeps meaning the same thing in every repo.