speccle 0.11.0 → 0.15.0

package/lenses/security.md

@@ -0,0 +1,42 @@
+# security lens
+
+**Stance:** treat every input in the diff as hostile and every output as reachable by
+someone it was not meant for. Trust nothing the change did not itself validate.
+
+## What to look for
+
+- **Injection** — user input concatenated into SQL, a shell command, an HTML fragment, a
+  file path, a regex, a template, or a log line. Look for the missing parameterization,
+  escape, or allow-list, not just the obvious `eval`.
+- **AuthN / AuthZ** — an endpoint, action, or field newly reachable without the check its
+  neighbours have; an ownership check that trusts a client-supplied id; a role compared by
+  a mutable value.
+- **Secrets** — a key, token, password, or connection string in the diff, a fixture, a log,
+  or an error message returned to the caller. Anything that should have come from the
+  environment and did not.
+- **Sensitive data** — PII or credentials logged, cached, serialized into a response, or
+  widened into a payload that reaches a client that should not see it.
+- **Untrusted deserialization / SSRF** — parsing attacker-controlled data into live objects;
+  a server-side fetch whose URL a caller controls.
+- **Crypto & randomness** — a non-cryptographic RNG for a token, a home-rolled hash or
+  cipher, a comparison of secrets that is not constant-time, a disabled TLS verification.
+- **Dependencies** — a new dependency, a pinned version dropped, a `postinstall` that runs
+  code, a lockfile change that does not match the manifest.
+
+## How to report
+
+Report only findings anchored to a **changed line** in this change set. For each finding
+give:
+
+- `path:line` — the changed line it anchors to
+- **severity** — blocker · major · minor · nit (a reachable, unauthenticated data exposure is
+  a blocker; defence-in-depth is a minor)
+- **what** — the weakness in one line
+- **why** — the **attack**: who supplies what input, and what they gain
+- **fix** — the parameterization, check, or removal that closes it
+- **route** — `criterion` · `check` (e.g. "a handler under `api/` must call the authz guard")
+  · `lens` · `none`
+
+Name the vector concretely — a payload, a request, an actor — not "could be exploited". A
+theoretical concern with no reachable path is a nit; label it as one. An empty report is a
+valid result.

package/lenses/test-quality.md

@@ -0,0 +1,39 @@
+# test-quality lens
+
+**Stance:** a test's only job is to fail when the behaviour breaks. Read each test the change
+adds or touches and ask what broken code it would let through.
+
+## What to look for
+
+- **Asserts nothing** — a test that exercises code but checks no outcome; an `expect` with no
+  matcher; a snapshot accepted without reading it; a `try/catch` that passes on either path.
+- **Cannot fail** — an assertion tautologically true (`expect(x).toBe(x)`), a mock asserted
+  against its own return, a condition that guards the only assertion so it never runs.
+- **Tests the mock** — every collaborator stubbed until the test only proves the stubs were
+  called in the order the test wrote; nothing of the real unit is left under test.
+- **Behaviour changed, test did not** — production logic in the diff whose test file is
+  untouched, or touched only to keep it compiling; a new branch with no case.
+- **Coupled to implementation** — assertions on private internals, call order, or log
+  strings rather than observable behaviour, so a safe refactor breaks the test and a real
+  regression slips by.
+- **Weak oracle** — asserts a value is truthy where the exact value matters; `toThrow()`
+  with no error type; checks a collection's length but not its contents.
+- **Missing negative space** — only the happy path; the error, the empty, and the rejected
+  input the change introduced go unchecked.
+
+## How to report
+
+Report only findings anchored to a **changed line** — a test in the diff, or production
+behaviour the diff added that no test claims. For each finding give:
+
+- `path:line` — the test line, or the unclaimed production line
+- **severity** — major (a real regression would pass) · minor · nit
+- **what** — the gap in one line
+- **why** — the broken implementation this test would wave through
+- **fix** — the assertion to add, or the case the suite owes
+- **route** — `criterion` (behaviour the spec never named, so no test could claim it) ·
+  `check` · `lens` · `none`
+
+Route to `criterion` when the gap is that nothing specifies the behaviour — a missing
+assertion is a test fix, a missing specification is not. Do not reward a test that raises a
+coverage number while asserting nothing. An empty report is a valid result.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "speccle",
-  "version": "0.11.0",
-  "description": "Speccle's deterministic tooling: spec lint and the oracle-strength heatmap. Never calls an LLM.",
+  "version": "0.15.0",
+  "description": "Speccle's deterministic tooling: spec lint and the oracle-strength heatmap. No LLM, bar the opt-in CI review driver.",
   "license": "MIT",
   "author": {
     "name": "Matt Alton",
@@ -26,11 +26,13 @@
     "speccle": "./dist/cli.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "skills",
+    "lenses"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
-    "prepublishOnly": "pnpm build && pnpm test",
+    "build": "tsc -p tsconfig.build.json && node ../../scripts/bundle-skills.mjs",
+    "prepublishOnly": "node ../../scripts/check-plugin-version.mjs --release && pnpm build && pnpm test",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "coverage": "vitest run --coverage",

package/skills/carve-feature/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: carve-feature
+description: Bring existing, ungoverned code under the convention without changing it — derive SPEC.md and CONTEXT.md from what the code observably does, lint them clean, announce the derived criteria and findings, then claim every criterion by tagging the tests that already defend it and writing tests for what nothing claims, ending with a spec summary the human rules on. Use when the user wants to retrofit a spec onto working code, govern an existing module, bring legacy code into a slice, or says "carve this", "carve it into a slice", "spec what this already does".
+allowed-tools: Read(/${CLAUDE_PLUGIN_ROOT}/skills/*/references/**)
+---
+
+# carve-feature
+
+Take a region of code that already works and make it a governed feature folder: the
+markdown contract — `SPEC.md`, `CONTEXT.md`, `AGENTS.md`, `decisions/` — derived from
+its observed behaviour, and every criterion claimed by a tagged test. The code's
+behaviour does not change — a carve is a change of governance, not of code.
+
+If the user is describing behaviour that does not exist yet, that is the `feature`
+pipeline, not a carve. A request that mixes the two ("spec this up and fix the
+rounding while you're in there") is a carve followed by governed work — never one
+pass.
+
+The shape of the folder is fixed by the convention, bundled beside this skill. Read
+`${CLAUDE_SKILL_DIR}/references/convention.md` before deriving anything.
+
+Speccle's words are fixed and mandatory: "criterion id", not "tag"; "statement", not
+"title"; "carve", not "retrofit" or "migration"; "spec summary", not "approval gate".
+
+**This skill does not measure oracle strength.** A carve can finish well-specified and
+weakly defended; a fresh carve is `strengthen`'s natural next target, and saying so is
+part of handing back.
+
+## 1. Pick the carve boundary
+
+The boundary is the directory that owns the code being carved; the markdown contract
+lands at its root. A carve never moves or edits source files, so the boundary must
+already have the convention's shape — where it does not, the fix is a **pre-carve
+refactor** the user does before carving, under whatever safety net they trust. Stop
+and show them exactly what is wrong; do not do it for them.
+
+- **The boundary is named for the feature.** An unnamed catch-all (`src/`, `lib/`) is
+  never a feature folder, even when it holds the project's only feature — renaming it
+  is the pre-carve refactor case, not a valid boundary.
+- **Source must already sit in the boundary's `src/`.** Source loose at the boundary
+  root, or smeared across the tree, is the same case: show the user which files live
+  where and what the shape should be.
+- **Tests may live outside it** — a parallel `test/` tree is normal in existing
+  projects. Tests are the one thing a carve does move: they land in `src/` beside the
+  code in phase 6.
+
+Settle the feature key as `plan-feature` does: `[A-Z][A-Z0-9]{1,9}`, unique across
+the repo — read the frontmatter of every other `SPEC.md` before guessing.
+
+If a conventioned `SPEC.md` already sits at the root, the criteria are already owned:
+adopt them unchanged and go straight to phase 6 for whatever they leave unclaimed.
+
+## 2. Derive the criteria from what is, not what should be
+
+Read in this order, because it is the order of reliability:
+
+1. **The existing tests** — executable claims about behaviour someone once cared about.
+2. **The source** — for observable behaviour no test asserts.
+3. **Docs and comments last** — they drift, and a carve documents the code, not the
+   folklore around it.
+
+Every criterion is one testable clause the code **verifiably does today**. If you
+cannot point at the code that makes a statement true, it is not observed behaviour and
+it does not go in the spec. Criteria describe the feature at its boundary — what a
+caller can see — not one per function; a spec that mirrors the file listing is an
+implementation inventory, not acceptance criteria.
+
+**When something looks wrong, do not write the criterion you wish were true.** The
+code's spec fails against the code — that is a broken carve. Do not quietly fix the
+code either. Record it as a finding: what the code does, why it looks unintended, and
+where. Findings are announced in phase 5 and ruled on by the human at the spec summary,
+not by you.
+
+## 3. Draft the markdown contract
+
+Follow the convention exactly — the drafting pitfalls `spec-feature` restates
+(one clause per statement, ids are names not order, the body is free) all apply
+unchanged. `SPEC.md`, `CONTEXT.md`, and `AGENTS.md` are the floor, even for a small
+carve; `decisions/` appears with the first cross-criterion choice the code turns out
+to embody.
+
+The carve-specific part is `CONTEXT.md`: adopt the language the code already uses.
+The terms are the names in the source, and the _Avoid_ lines retire the synonyms the
+codebase mixes — a carve is often the first time anyone writes down which of three
+interchangeable names is canonical.
+It is a glossary only: a choice the code embodies that spans criteria (a keying
+strategy, a rounding policy) is an ADR in `decisions/`, recording what the code does
+and whatever "why" survives.
+In `AGENTS.md`, state how to work the slice — run its tests, find the contract — and
+nothing about behaviour.
+
+## 4. 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.
+
+```sh
+<oracle> lint <feature-folder>
+```
+
+Fix and re-run until clean — exit `0` clean, `1` violations, `2` usage error; parse
+`--json` rather than scraping the human output. When a quality violation fires on a
+derived statement, rewrite the statement without changing what it observes: the fix for
+"the parser handles bad input" is naming what the parser observably does with bad
+input, which usually means going back to the code to look.
+
+## 5. Announce the derivation — and keep going
+
+Show two things, then proceed straight into phase 6 without waiting:
+
+- **The criteria** — ids and statements, as `implement-feature` does. What the human
+  will rule on later is more than wording: whether your reading of the code matches
+  their intent.
+- **The findings** — each behaviour you suspect is unintended. Spec what the code
+  observably does, suspicious or not — a carved spec is honest before it is
+  aspirational — and flag each finding here and again in the spec summary, where the
+  human rules: **intended**, and its criterion stands, stating what the code does; or
+  **a bug**, and the criterion comes out of the spec and the behaviour is recorded as
+  future work in whatever tracker the project uses. A carve never fixes one.
+
+If the human interjects — now or at any point — treat "looks good, and also…" as a
+change request: amend, re-lint, announce again.
+
+## 6. Claim every criterion, changing nothing
+
+The carve's whole discipline in one check: when this phase ends, the diff shows test
+files and the markdown contract — `SPEC.md`, `CONTEXT.md`, `AGENTS.md`, `decisions/` —
+**nothing else**.
+
+- **Tag the existing tests.** A test claims a criterion when the `[KEY-n]` token
+  appears in its full concatenated name — renaming the enclosing `describe` is the
+  idiom.
+  Tag only tests that assert the criterion's behaviour, not every test that happens to
+  execute the code. Tests that map to no criterion stay as they are — untagged is
+  honest; do not delete or reword them.
+- **Move outside tests into `src/`, beside the code they defend.** Colocation is the
+  convention's point. Fix the moved files' own imports and confirm the runner still
+  finds them — an include pattern that no longer matches loses tests silently.
+- **Write tests for unclaimed criteria**, tagged the same way. They run against code
+  that already works, so they pass on first run. **A new test that fails is a
+  discovery, not a draft to iterate on**: either you misread the code — fix the
+  statement, re-lint, and announce the change — or you found a bug — it comes out of
+  the spec and into the tracker, like any phase-5 finding. The failing test is never a
+  reason to touch the source.
+
+There is no tracer criterion — the tracer proves a path connects, and a carve's path is
+proven by the code already running.
+Claim criteria in document order, suite green at every criterion boundary.
+
+## 7. Confirm done
+
+Done means all five, verified rather than assumed:
+
+1. The feature folder is named for the feature and holds the markdown contract —
+   `SPEC.md`, `CONTEXT.md`, `AGENTS.md` — with all code and tests in `src/`.
+2. `<oracle> lint <feature-folder>` exits `0`.
+3. Every criterion id appears in at least one full test name — run the suite with a
+   JSON reporter and check each id against the concatenated names.
+4. The **whole project's** suite is green, not just the carved folder's — moved test
+   files are exactly the change that breaks a sibling.
+5. The diff touches test files and the markdown contract only. Check `git status`
+   and `git diff` rather than asserting it — this is the invariant the carve exists to
+   keep, and it is the first thing to say when handing back.
+
+Hand back with the **spec summary**: the derived criteria (ids and statements) and
+every finding awaiting a ruling. The human rules each finding intended-or-bug here —
+a criterion ruled a bug is reverted with its tests, and the behaviour goes to the
+tracker.
+
+Then say what done does not include: how well the new claims _defend_ the code is
+`strengthen`'s question, and a fresh carve is its natural next target.

package/skills/carve-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/conform/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: conform
+description: Bring already-governed feature folders up to the current convention after it changes — sweep every SPEC.md, diagnose each slice's drift against the convention (folder shape, an over-full flat src/, missing contract files, decisions content in CONTEXT.md, lint violations), announce the drift report, then apply form-only fixes with the suite green throughout, ending with a spec summary. Use when the user upgrades Speccle or its convention and wants existing features updated, asks to bring features up to convention or check for drift, or says "conform this", "conform the features", "the convention changed".
+allowed-tools: Read(/${CLAUDE_PLUGIN_ROOT}/skills/*/references/**)
+---
+
+# conform
+
+Bring slices that are **already governed** up to the convention as it stands today.
+The convention moves — a folder shape tightens, a new contract file becomes the floor,
+a lint rule sharpens — and a feature scaffolded correctly last month drifts without a
+line of it changing.
+Conform is the remedy: form changes only, behaviour never.
+
+Two neighbours this skill is not. Ungoverned code — no `SPEC.md` — is a **carve**
+(`carve-feature`); changing what a criterion _means_ is an **amend** (`spec-feature`).
+A request that mixes conforming with either is two passes, never one.
+
+The shape being conformed _to_ is fixed by the convention, bundled beside this skill.
+Read `${CLAUDE_SKILL_DIR}/references/convention.md` before diagnosing anything — the
+checklist below is applied against it, not from memory.
+
+Speccle's words are fixed and mandatory: "conform", not "migrate" or "upgrade";
+"criterion id", not "tag"; "lint violation", not "error"; "spec summary", not
+"approval gate".
+
+## 1. Find the governed slices
+
+Given a project root, find every `SPEC.md` under it by the convention's discovery
+rules — never entering `node_modules`, `dist`, `fixtures`, `__fixtures__`, or
+dot-directories — and conform each. Given a single feature folder, conform just it.
+
+No `SPEC.md` found means there is nothing governed to conform: the work is a carve or
+a new feature. Say so and stop.
+
+## 2. Diagnose each slice against the bundled convention
+
+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 spec rules in the oracle's place.
+
+Then walk the checklist for each slice — every item is what the convention requires
+today, and the bundled copy is the authority:
+
+- **The folder is named for the feature.** An unnamed catch-all (`src/`, `lib/`)
+  flags, even for a project's only feature.
+- **The markdown contract is complete at the root**: `SPEC.md`, `CONTEXT.md`,
+  `AGENTS.md`; `decisions/` whenever the feature has a decision to hold.
+- **All code and tests sit under `src/`**, tests beside the code they defend, and the
+  root holds the markdown contract and nothing else. `src/` may nest into subfolders —
+  legal nesting is not drift. What flags is an **over-full flat directory**: `src/`
+  itself, or any subfolder under it, holding **more than ten files directly**. Count
+  the entries; subfolders don't count toward their parent's total.
+- **`CONTEXT.md` is a glossary only.** Decisions content — a Decisions section,
+  mini-ADR bullets, any recorded choice spanning criteria — belongs in `decisions/`
+  as numbered ADR files.
+- **`<oracle> lint <feature-folder>` exits 0.** Parse `--json` rather than scraping
+  the human output. A rule that did not exist when the spec was written flags here
+  like any other lint violation.
+- **Every criterion id appears in at least one full test name.** An unclaimed
+  criterion is a **finding**, not a fix — writing tests is `carve-feature` and
+  `strengthen` territory, and conform names the gap rather than filling it.
+
+## 3. Announce the drift report — and keep going
+
+Per slice: each drift item found and the fix planned for it; slices with no drift
+listed as clean. Then proceed straight into phase 4 without waiting — a misjudged fix
+is corrected by interrupt, like any other announcement.
+
+## 4. Apply the fixes, suite green at every boundary
+
+Run the project's suite before touching anything. Conform never starts on red without
+saying so — a pre-existing failure is the user's to rule on, not yours to absorb into
+the diff.
+
+Per slice, in this order:
+
+- **Structural moves first.** Code and tests into `src/`; a catch-all folder renamed
+  for its feature. Fix the moved files' own imports, everything that imports them,
+  and the runner and tsconfig include patterns — a pattern that no longer matches
+  loses tests silently, so re-run the suite and check the test count, not just the
+  colour.
+- **Regroup an over-full directory.** A `src/` or subfolder over the ten-file limit
+  gets its files gathered by concern into shallow, purpose-named subfolders — a pure
+  relocation, imports and config fixed, test count held, exactly like the moves above.
+  **Never split the slice into siblings**: a new feature folder redraws boundaries and
+  is a re-slice, not a form fix. When the pile reads as two behaviours rather than one
+  crowded feature, regroup it anyway — the subfolders you draw are the natural split
+  lines — and carry "consider splitting into siblings via a `feature` amend" into the
+  spec summary as a finding. That better fix is the human's to make, not conform's.
+- **Generate a missing `AGENTS.md`** from what the folder shows: what the slice does
+  in a sentence or two, how to run its tests, where the contract lives. Facts about
+  working the slice, never about its behaviour.
+- **Split decisions content out of `CONTEXT.md`** into `decisions/0001-<slug>.md`
+  onward, same form as any ADR. The original wording becomes the Decision; a "why"
+  that was never recorded is stated as unrecorded, not invented.
+- **Reword statements only as far as lint requires, meaning unchanged.** The fix for
+  a quality violation on an old statement is naming what the code observably does —
+  which usually means reading the code, not polishing the sentence. Ids are names:
+  never renumbered, never reused. Re-run lint until the slice is clean.
+
+## 5. Confirm done
+
+Done means all four, verified rather than assumed:
+
+1. `<oracle> lint` exits `0` for every slice swept.
+2. The **whole project's** suite is green with the same test count as before the
+   moves — moved test files are exactly the change that loses a sibling silently.
+3. The diff shows markdown, file moves with their import and config fixes, and
+   criterion-id tags in test names — nothing source-semantic. Check `git status` and
+   `git diff` rather than asserting it; this is the invariant conform exists to keep.
+4. Every drift item announced in phase 3 is either fixed or carried into the spec
+   summary as a finding.
+
+Hand back with the **spec summary**: per-slice changes; every reworded statement, old
+and new side by side under its unchanged id, for the human to overrule; and the
+findings — unclaimed criteria and anything suspicious met along the way — naming
+`strengthen` as the natural next step where the claims look thin.