speccle 0.11.0 → 0.15.0

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

@@ -0,0 +1,103 @@
+---
+name: feature
+description: Build or change a feature end to end — plan it with the human (settling the open decisions and capturing each one in the slice's docs), gate once on plan approval, then run spec and implement in their own subagent sessions, close with the deterministic checks-gate (lint, claims, tests), and commit on green without asking. Use when the user wants to build, implement, or spec a feature, extend or amend an existing one, hands over a ticket or prose description to turn into a slice, or says "speccle this", "implement this feature", "add this to the checkout feature".
+allowed-tools: Read(/${CLAUDE_PLUGIN_ROOT}/skills/*/references/**)
+---
+
+# feature
+
+The pipeline: **plan → gate → spec → implement → checks → commit**. Planning is a
+dialogue in this session; spec and implement each run in their own subagent session;
+the checks are deterministic oracle commands; the commit is automatic. The pipeline
+has exactly **one human gate** — plan approval — and it sits before anything is
+built. Everything after it runs unattended.
+
+Invoke each sibling skill under whatever namespace this skill itself runs in —
+`speccle:plan-feature` when installed as the plugin, bare `plan-feature` when the
+skills live project-level.
+
+Speccle's words are fixed and mandatory: "criterion id", not "tag"; "amend", not
+"edit" or "update"; "checks-gate", not "review step"; "spec summary", not "approval
+gate".
+
+## 1. Plan — in this session, with the human
+
+Invoke `plan-feature` with the Skill tool, in this session — never in a subagent:
+planning is a dialogue, and a subagent cannot talk to the human. It explores, routes
+(**new** / **amend** / **carve**), settles the open key decisions one question at a
+time, captures each settled decision into the slice's docs the moment it lands, and
+ends with the plan summary.
+
+If the route is **carve**, stop here: hand the user to `carve-feature` — the
+behaviour already runs, and governing it is a different job. A mixed request is a
+carve followed by a `feature` run in amend mode, never one pass.
+
+## 2. The gate — plan approval
+
+The plan summary is the pipeline's one approval. Where plan mode is available, enter
+plan mode and present the summary as the plan — approving it launches everything
+after. Where it is not, show the summary in chat and wait for the go-ahead.
+
+- **Approval starts the machine.** If any decision was captured only in the summary
+  because writes were forbidden during planning (the session was already in plan
+  mode), write those docs now, before the spec stage — the subagents read the folder,
+  not this conversation.
+- **An unattended run cannot approve.** Do not hang: continue with the plan as
+  announced, every open decision defaulted to its recommendation and flagged — in the
+  plan summary and again at the end. A defaulted decision is never silent.
+
+## 3. Spec — a subagent, off the plan
+
+Launch a subagent whose prompt carries the full hand-off: the route, the feature
+folder, the key, the scope, each settled decision (agreed or defaulted), and any
+per-behaviour choice the plan noted for a criterion body. Instruct it to invoke
+`spec-feature` with that input and to return the criteria — ids and statements,
+retirements included — once the folder lints clean.
+
+The subagent never saw the planning dialogue. Everything it needs must be in the
+prompt or on disk — that is the design, not a limitation: if the hand-off feels too
+thin to spec from, the plan was too thin, and the fix is a better plan, not a fatter
+prompt.
+
+Show the returned criteria to the human as an FYI — reading five headings is cheap
+insurance before implementation spends real effort on a wrong spec. Do not wait for
+approval; an interjection is a change request (re-enter the stage it names), silence
+is consent.
+
+## 4. Implement — a subagent, off the spec
+
+Launch a second subagent: the prompt names the feature folder, the route (tracer on
+**new**, none on **amend**), and any retired ids whose tests must go. Instruct it to
+invoke `implement-feature`. It works from the linted spec and the slice's docs — the
+folder is the brief — and returns which criteria went green plus anything it changed
+in the spec along the way.
+
+## 5. The checks-gate — deterministic, no judgement
+
+Run in this session, resolving the oracle as every Speccle skill does — the repo's own
+`<repo-root>/node_modules/.bin/speccle` first (a devDependency is never on
+`PATH`, so test for the file), else `speccle` on `PATH`, else
+`node <speccle-repo>/packages/oracle/src/cli.ts`:
+
+1. `<oracle> lint <feature-folder>` — exit `0`.
+2. `<oracle> claims <target-root>` — exit `0`: every criterion claimed by a test
+   name, every claimed id real.
+3. The project's test suite — green.
+
+A failure returns to the implement subagent with the failing output — not to the
+human. If the same failure comes back twice, stop and show the human what is stuck.
+There is no judgement here and no oracle-strength measurement — the heatmap is
+`strengthen`'s job, on its own cadence, and this gate stays seconds cheap.
+
+## 6. Summary, then commit — no pause
+
+Render one screen, in product voice: every criterion drafted, amended, or retired
+(ids and statements), what claims it, the implement subagent's notes, and every
+decision that was defaulted rather than agreed. This is the spec summary for the
+whole run — the human rules by reading it, not by being asked.
+
+Then commit, automatically: stage the feature folder and only the files this run
+touched, and write the message the repo's conventions ask for, derived from the
+route — a new slice is introduced, an amendment names the behaviour that changed. No
+"commit? y/n": on a green gate the pause is ceremony, and a commit the summary makes
+the human regret is one revert away.

package/skills/implement-feature/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: implement-feature
+description: Implement an already-specced slice — write token-tagged tests first and the code that makes them green, one criterion at a time, tracer criterion first on a new slice. Use when a linted SPEC.md exists and the user wants it implemented, wants tests and code for drafted criteria, or says "make the slice green", "implement the spec". For a feature that has no spec yet, the whole job — plan, spec, implement — is the feature skill.
+allowed-tools: Read(/${CLAUDE_PLUGIN_ROOT}/skills/*/references/**)
+---
+
+# implement-feature
+
+Write the tagged tests and the code that satisfy an existing, linted `SPEC.md` — one
+criterion at a time, tests first. Stage 3 of the `feature` pipeline, and complete on
+its own when the spec already exists — hand-written to the convention, or drafted
+earlier by `spec-feature`.
+
+In the pipeline this skill runs in its own subagent session: the linted spec and the
+slice's docs are the whole brief — read them; there is no earlier conversation to
+consult. The final message is the hand-back in §3.
+
+**This skill starts from a spec.** Handed a feature with no conventioned `SPEC.md`,
+say so and point at the `feature` pipeline (or `spec-feature` for the contract alone)
+rather than drafting one here — drafting has its own skill, and an unlinted spec must
+not reach this one. Verify the precondition rather than assuming it:
+`<oracle> lint <feature-folder>` exits `0` (resolve the oracle as every Speccle skill
+does: the repo's own `<repo-root>/node_modules/.bin/speccle` first — a
+devDependency is never on `PATH`, so test for the file — else `speccle` on
+`PATH`, else `node <speccle-repo>/packages/oracle/src/cli.ts`; if none resolves, point
+at the README's install steps and stop).
+
+The folder shape and test-linking rules are fixed by the convention, bundled beside
+this skill at `${CLAUDE_SKILL_DIR}/references/convention.md`.
+
+Speccle's words are fixed and mandatory: "criterion id", not "tag"; "statement", not
+"title"; "spec summary", not "approval gate".
+
+**This skill does not measure oracle strength.** A slice can finish here
+well-specified and weakly defended; closing that gap is `strengthen`'s job, on its
+own cadence — the pipeline's checks-gate verifies lint, claims, and green tests, not
+how hard the tests bite.
+
+## 1. Scope the work
+
+Everything this skill writes lands in the feature's `src/` — tests beside the code
+they defend; the feature root stays pure markdown.
+
+Keep `src/` flat while it holds **ten files or fewer** directly (code and tests
+together — count the entries, don't judge the crowding). The file that would make it
+eleven triggers grouping: gather the code into shallow, purpose-named subfolders — one
+level, tests still beside the code they defend at that depth — and the same
+ten-file limit then applies inside each subfolder. Before nesting, ask whether the
+pile is really one slice: a `src/` that has grown two clearly separate concerns is
+usually two slices, and splitting into a sibling folder beats burying the seam under
+subfolders. Nest when it is genuinely one cohesive feature that just carries many
+files.
+
+- **New slice** (no code in `src/` yet): every criterion is unimplemented; the tracer
+  rule below applies.
+- **Amended slice** (the spec changed over running code):
+  implement only the criteria no test yet claims, in document order. There is **no
+  tracer** — the slice's path already runs, so there is nothing to prove; the same
+  reason a carve has none.
+  A retired id takes its tests with it: delete them, and confirm the code they
+  defended is either still promised by a live criterion or removed too.
+
+Find the unclaimed criteria mechanically, not by eye:
+`<oracle> claims <feature-folder>` joins every criterion to the test names that
+carry its token — `unclaimed` lists the ids still owed a test, `unknownClaims` the
+tokens pointing at no criterion (a retired id someone's test still claims). One
+caveat, because the scan is static: only string-literal `describe`/`it`/`test`
+titles count, so write the `[KEY-n]` token as literal text, never built up at
+runtime.
+
+## 2. Red-green, one criterion at a time
+
+Tests first, then the code that makes them pass — and **never more than one criterion
+at a time**. Write the criterion's tests, run them, and watch them fail before
+writing any code: a test that has never failed proves nothing. Then make it green,
+then move on. Your instinct will be to build a layer at a time: every criterion's
+parsing, then every criterion's calculation, then every criterion's persistence.
+Resist it. A feature built that way does not execute until the last layer lands, and
+by then the mistake is expensive.
+
+### Fire the tracer criterion first (new slice only)
+
+Pick the criterion whose passing test exercises the thinnest complete path through
+every layer the feature touches — entry to exit, nothing stubbed. Choose it for
+**path length, not importance**: the plainest success case, the one carrying the
+least logic. An edge case or a rejection is never the tracer; it short-circuits the
+very layers it was meant to prove. "When a line item is taxed, tax rounds half-up"
+traces the path; "When a basket exceeds 100 line items, checkout rejects it" throws
+before reaching it.
+
+Make it green. Then say so: name the criterion, and name the layers its test now runs
+through. Do not stop for approval — the green test _is_ the feedback, and this skill
+has no stops.
+
+When a feature has one layer — a pure function, a formatter — there is no path to
+trace. The first criterion is the tracer, nothing special happens, and you should not
+dress it up as though something did.
+
+### Then thicken
+
+Take the remaining criteria in document order, one at a time, each written against a
+skeleton that already runs. The suite is green at every criterion boundary — if it is
+not, finish that criterion before starting the next.
+
+If a criterion cannot be made green without dragging two others in with it, stop and
+look at the spec. That is a compound criterion that lint let through, and finding it
+now is worth more than the detour costs. Amending the spec mid-implement is
+`spec-feature`'s §2 in miniature: next never-used ids, re-lint, announce the change.
+
+### Tagging tests
+
+A test claims a criterion when the `[KEY-n]` token appears in its **full concatenated
+name** — enclosing `describe` titles count. One
+`describe('[CHECKOUT-1] tax rounding', …)` claims every test nested inside it, which
+is the idiom to reach for.
+
+```ts
+describe("[CHECKOUT-1] tax rounding", () => {
+  it("rounds each line's tax half-up before summing", () => {
+    const basket = [line("a", 199), line("b", 199), line("c", 199)];
+    expect(checkout(basket, 0.2).tax).toBe(120);
+  });
+});
+```
+
+Write tests that would fail if the behaviour broke, not tests that merely execute the
+code. Reach for the criterion body's edge cases — they are there because someone
+thought the naïve implementation would miss them.
+
+## 3. Confirm done
+
+Done means all four, verified rather than assumed:
+
+1. The feature folder is named for the feature and has the convention's shape:
+   `SPEC.md`, `CONTEXT.md`, `AGENTS.md` at the root, code and tests in `src/`.
+2. `<oracle> lint <feature-folder>` exits `0`.
+3. `<oracle> claims <feature-folder>` exits `0` — every criterion claimed, and no
+   test still claiming a retired id. An id nobody claims is an unimplemented
+   criterion, so go back to §2.
+4. The **whole project's** test suite is green, not just the slice's — on an amended
+   slice, the pre-existing tests are exactly the ones a change breaks.
+
+Do not report done on a spec with an unclaimed criterion.
+
+Hand back by naming what went green: each criterion implemented this run, id and
+statement. If the spec changed mid-run (a compound criterion found in §2), that is a
+spec change and gets the **spec summary** treatment: list it for the human to rule
+on.
+
+There is no oracle-strength check here, deliberately. Say so when you hand back: the
+slice is green, and how well it is _defended_ is a question `strengthen` answers, on
+its own cadence.