speccle 0.11.0 → 0.12.0

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.

package/skills/strengthen/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: strengthen
+description: Evaluate how well a feature's tests defend its code — check report freshness first, hand the human the exact coverage and mutation commands when reports are stale or missing, then read the per-criterion oracle-strength heatmap and route every surviving mutant to a killing test or a sharper criterion, marking the heatmap evaluated when done. Use when the user wants to strengthen tests, check oracle strength, asks whether tests would catch a bug, wants to kill surviving mutants, or says "strengthen this", "how well is this defended", "run the heatmap".
+allowed-tools: Read(/${CLAUDE_PLUGIN_ROOT}/skills/*/references/**)
+---
+
+# strengthen
+
+A slice can be green and badly defended: `implement-feature` leaves it that way on
+purpose, and the `feature` pipeline's checks-gate never measures it. This skill is the
+periodic audit that closes the gap — catching what no deterministic check sees:
+behaviour no criterion covers, and tests that run without asserting.
+
+The division of labour is fixed: **the human runs the expensive commands; this skill
+evaluates what they produce.** Coverage and mutation are minutes of compute — never
+run them yourself; hand over the exact commands and stop. Everything this skill runs
+itself finishes in seconds.
+
+Measure oracle strength per criterion, then act on every **surviving mutant** — the
+exact code change no test noticed. The routing call is the whole job; §5 is how to
+make it.
+
+Speccle's words are mandatory: "oracle strength", not "mutation score"; "surviving
+mutant", not "missed mutation"; "test-fitting", not "gaming the score"; "fresh" /
+"stale" / "evaluated" as the freshness check reports them.
+
+## 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, 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.
+
+## 2. Check freshness before anything else
+
+```sh
+<oracle> strength <path> --check
+```
+
+Seconds, no reports run: each report comes back **fresh**, **stale** (naming the
+slice file that post-dates it), or **missing**, plus whether the current heatmap was
+already **evaluated** and the marker path that records it. `--json` gives
+`{ root, mutation, coverage, evaluated, marker }`; pass `--mutation` / `--coverage`
+when the target writes reports somewhere non-default. Exit `0` means both fresh.
+
+Route on what it says:
+
+- **Fresh and not evaluated** — there is a heatmap waiting to be read. Go to §4.
+- **Fresh and evaluated** — this heatmap has already been worked. Say so and stop;
+  re-evaluate only if the human asks for a second pass.
+- **Stale or missing** — hand the human the exact commands and stop. Name the
+  target's own coverage and mutation commands (read its `package.json` scripts), and
+  when the work concerns one slice, scope the mutation run to it — mutating
+  `features/<name>/src/**` is minutes where the whole target is tens of them:
+
+  ```sh
+  pnpm coverage
+  pnpm mutation -- --mutate 'features/basket/src/**/*.ts'
+  ```
+
+  The run resumes when the human says the reports are in — re-run `--check` to
+  confirm rather than taking it on faith.
+
+## 3. Require the stack, and never install it silently
+
+Oracle strength needs to know which tests covered each mutant, and that constrains the
+target to TypeScript + vitest + StrykerJS. When `--check` says missing and the stack
+itself is absent, check the four requirements in
+`${CLAUDE_SKILL_DIR}/references/stack.md` before asking anyone to run anything.
+
+**If something is missing, stop and offer.** Show what is absent, then offer the one
+command that provisions all of it — `speccle strength init <path>` — and wait for
+the user's go-ahead before running it. Never write to the target's `package.json`,
+lockfile, or test config without the user agreeing first — this skill measures someone
+else's project; it does not quietly re-tool it.
+
+## 4. Read the heatmap
+
+```sh
+<oracle> strength <path>
+```
+
+The reports are already on disk — §2 proved it. Show the human heatmap to the user: a
+bar and `killed/covered` per criterion, each criterion's survivors listed beneath it. Use
+`--json` for the routing work and never scrape the human output — the output shape and
+the full `--json` schema are in `${CLAUDE_SKILL_DIR}/references/heatmap.md`. `strength`
+is a report, not a gate: it exits `0` with survivors present, `2` on a bad or missing
+report.
+
+Four of the `--json` fields — `unclaimed`, `unknownClaims`, `unclaimedMutants`,
+`staticMutants` — are **not** routing work: none is a survivor to route. Say them out
+loud before you start; `references/heatmap.md` gives each one's shape and what it asks of
+you instead.
+
+## 5. Route every surviving mutant
+
+Never route a criterion, and never route a percentage — a criterion under 100% always has
+at least one survivor to act on, and one at 100% has none, so the number carries nothing
+the survivor list does not.
+Route each survivor, and ask one question of it:
+
+> Can I write an assertion that **follows from the criterion's statement**, and that fails
+> against this mutant?
+
+**Machine path — yes.** The statement already promises the behaviour this mutant breaks;
+the suite just never checked it. Write the killing test under that criterion id, exactly
+as `implement-feature` does — the `[KEY-n]` token in the full concatenated name. Run the
+test suite — it must be green — and batch the machine-path work across survivors: each
+killing test makes the reports staler, and only the human's re-run confirms the kills.
+
+**Human path — no, and the behaviour matters.** No criterion entails it, so the spec is
+silent or too vague to test. Draft a sharper statement, or the new criterion the spec
+owes, taking the next never-used number under the key. Draft it in the target's `SPEC.md`
+itself — the spec edit _is_ the draft, and lint reads the real file. Lint it clean,
+**announce it** — id and statement — and keep going: the survivor takes the machine path
+under the new id.
+The human rules on every criterion this run added at the summary in §6; an overruled
+one is reverted from the spec along with its test, returning its survivor to the report.
+
+**Equivalent mutant — no, and no test ever could.** The mutated code means the same thing.
+Annotate it where it lives and move on:
+
+```ts
+// Stryker disable next-line ArithmeticOperator: x * 1 and x / 1 are the same value
+```
+
+Argue it from the semantics. "The test is awkward to write" is not equivalence, and
+reaching for this exit more than rarely means the answer was the machine or human path.
+
+### The trap
+
+`[CHECKOUT-3]` above says _"checkout rejects it"_ of an oversized basket. Its two
+survivors are the error's message string and `this.name`; the test asserts
+`toThrow(TooManyLineItems)`, so `instanceof` reads neither.
+
+Asserting the message text under `[CHECKOUT-3]` kills both mutants and turns the bar
+green. Do not. "Rejects" promises a refusal and says nothing about what the refusal
+_says_ — the test would pass because someone typed that string, and the next person to
+reword the message gets a failure that teaches them nothing. That is test-fitting the
+mutant, and it is how mutation testing rots into a score chase.
+
+These survivors are the human path. The spec owes a criterion about what the rejection
+tells the caller. Draft it, announce it, test it — and watch `[CHECKOUT-3]` reach 100%
+untouched, because a kill counts for every criterion covering the mutant.
+
+If oracle strength rose but the spec did not change, check that you did not fit a test to
+a mutant.
+
+## 6. Confirm, mark evaluated, hand back
+
+Confirmation needs fresh evidence, and producing it is the human's run: after your
+last edit, hand back the same commands from §2 and stop. When the new reports land,
+`--check` again, re-read the heatmap, and verify every machine-path survivor is gone.
+A heatmap from before the change is not evidence.
+
+When the evaluation is done — routed, confirmed, or explicitly parked — touch the
+marker `--check` named, so the next run knows this heatmap was read:
+
+```sh
+touch <marker-path>
+```
+
+Then report, verified rather than assumed:
+
+1. The test suite is green.
+2. Every survivor you took the machine path on is gone from the fresh report.
+3. Oracle strength, before and after, headline and per criterion.
+4. The **spec summary**: every criterion this run added to the spec, id and statement.
+   The human rules here — an overruled criterion is reverted along with its killing
+   test, returning its survivor to the report.
+5. What is left, and why: each remaining survivor is annotated as equivalent, with its
+   argument, or named as a gap awaiting the human's ruling.
+
+A survivor you cannot explain is not finished — say so plainly rather than letting a
+nicer headline imply otherwise.

package/skills/strengthen/references/heatmap.md

@@ -0,0 +1,39 @@
+<!-- Generated from docs/strength-heatmap.md by scripts/sync-plugin-references.mjs — do not edit.
+     Edit the source and run `pnpm sync:plugin-refs`. -->
+
+# The oracle-strength heatmap
+
+`<oracle> strength <path>` prints a bar and `killed/covered` per criterion, with each
+criterion's survivors listed beneath it:
+
+```
+features/checkout/SPEC.md
+  CHECKOUT-1  ████████████████████  100.0%    14/14  When a line item is taxed, tax rounds half-up to 2dp
+  CHECKOUT-3  ██████████████████░░   88.2%    15/17  When a basket exceeds 100 line items, checkout rejects it
+      features/checkout/checkout.ts:13:11  StringLiteral → ``
+      features/checkout/checkout.ts:14:17  StringLiteral → ""
+```
+
+Use `--json` for the routing work: `{ root, strength, lineCoverage, features[], unclaimed,
+unknownClaims, unclaimedMutants, staticMutants }`, each criterion carrying `survivors[]`
+with `file`, `line`, `column`, `mutator`, `replacement`. `strength` is a report, not a
+gate: it exits `0` with survivors present, `2` on a bad or missing report. Never scrape
+the human output.
+
+## The four fields that are not routing work
+
+Say these out loud before you start — none of them is a survivor to route.
+
+- **`unclaimed`** — a criterion no test's name carries. It scores nothing rather than
+  zero. It needs a test written against it before it can be weak; that is
+  `implement-feature`'s job, not a survivor to route.
+- **`unknownClaims`** — a test claims an id no spec declares. Someone renamed or deleted a
+  criterion. Fix the test name or restore the criterion.
+- **`unclaimedMutants`** — code the criteria do not reach at all, each entry naming its
+  `file`, `line`, `column`, `mutator`, `replacement`. Not weak criteria; a map of the
+  regions the spec is silent about. Do not route these as survivors — name the region to
+  the human and let them decide whether a feature owes a spec there.
+- **`staticMutants`** — mutants that run at module load (word lists, regex literals), so
+  per-test coverage can attribute them to no criterion: `{ killed, survivors[] }`. The
+  killed ones are fine — some test noticed. A survivor is a real gap, but it can never be
+  claimed by a criterion id; name it to the human alongside the unclaimed mutants.

package/skills/strengthen/references/stack.md

@@ -0,0 +1,23 @@
+<!-- Generated from docs/strength-stack.md by scripts/sync-plugin-references.mjs — do not edit.
+     Edit the source and run `pnpm sync:plugin-refs`. -->
+
+# The oracle-strength stack
+
+Oracle strength needs to know which tests covered each mutant, and that constrains the
+target to TypeScript + vitest + StrykerJS. When `--check` says missing and the stack
+itself is absent, check for all four before asking anyone to run anything:
+
+| Requirement                       | Where                                |
+| --------------------------------- | ------------------------------------ |
+| `@stryker-mutator/core` + runner  | `package.json` devDependencies       |
+| `coverageAnalysis: "perTest"`     | `stryker.config.json`                |
+| the `json` reporter, and its path | `stryker.config.json` `jsonReporter` |
+| istanbul provider, `json-summary` | `vitest.config.ts` `test.coverage`   |
+
+`perTest` is the hard one: without it Stryker never records `coveredBy`, the join has
+nothing to walk back to criterion ids, and `oracle strength` exits `2` saying so.
+
+`speccle strength init <path>` provisions all of it — it installs the missing
+devDependencies and writes the preset configs, keeping any that already exist. It runs
+only on the user's explicit go-ahead; this skill measures someone else's project, it does
+not quietly re-tool it.