speccle 0.12.0 → 0.15.0

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.12.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",
@@ -27,11 +27,12 @@
   },
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "lenses"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.build.json && node ../../scripts/bundle-skills.mjs",
-    "prepublishOnly": "pnpm build && pnpm test",
+    "prepublishOnly": "node ../../scripts/check-plugin-version.mjs --release && pnpm build && pnpm test",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "coverage": "vitest run --coverage",

package/skills/review/SKILL.md

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