speccle 0.12.0 → 0.16.0

package/README.md

@@ -4,23 +4,37 @@ The deterministic tooling the skills invoke — one bin:
 
 ```
 speccle init            # record repo facts + vendor the skills into .claude/skills/
-speccle doctor          # report staleness across the CLI, skills, and strength stack
+speccle doctor          # report staleness across the CLI, skills, CI driver, and strength stack
 speccle update          # refresh the vendored skills; print the CLI + stack fix commands
 speccle lint            # enforce the convention over a repo's specs
 speccle claims          # join criteria to the test names that claim them
+speccle verify          # run .speccle/checks/ over a change set: cross-file invariants
+speccle risk            # score a change set from spec-aware signals; gate on the threshold
+speccle calibrate       # record / report the calibration evidence a threshold moves on
+speccle remedy          # record / recall the known remedy for a class of finding
+speccle review init     # scaffold the opt-in CI review driver (a GitHub Actions workflow)
+speccle review run      # review a pull request with the lens panel and post one review
 speccle strength        # oracle-strength heatmap: per-criterion killed ÷ covered
 speccle strength init   # provision the strength stack into a target
 ```
 
 - `init` / `doctor` / `update` — the setup and staleness surface: `init` records the
   repo's test facts in `.speccle/config.json` and vendors the skills into
-  `.claude/skills/`; `doctor` reports whether those skills and the strength stack still
-  match this CLI; `update` refreshes the skills forward and prints the CLI + stack fix
-  commands. See [Install](https://github.com/matthewalton/speccle/blob/main/README.md#install)
+  `.claude/skills/`; `doctor` reports whether those skills, the CI driver's pinned
+  version, and the strength stack still match this CLI; `update` refreshes the skills
+  forward and prints the CLI + stack fix commands. See
+  [Install](https://github.com/matthewalton/speccle/blob/main/README.md#install)
   and [Updating](https://github.com/matthewalton/speccle/blob/main/README.md#updating).
 - `lint` — enforce the [convention](https://github.com/matthewalton/speccle/blob/main/docs/convention.md) over a repo's specs.
 - `claims` — join every criterion to the test names carrying its id, statically. No
   reports needed, so it is cheap enough to gate on.
+- `verify` / `risk` — the change-set surface. Both read the working tree's pending change
+  by default, or a committed range with `--base <ref>`, measured at the merge base — which
+  is what a CI run needs, where the working tree is clean. `risk` exits 1 at or above the
+  review threshold, so it works as a status check.
+- `calibrate` / `remedy` — the meta loop's two records: the evidence a review threshold
+  moves on, and the known-correct remedy for a class of finding.
+- `review init` / `review run` — the CI driver. See [review](#review) below.
 - `strength` — join specs + Stryker mutation report + coverage into per-criterion
   `killed ÷ covered`.
 - `strength init` — the setup `strength` measures against: install the stack's
@@ -30,8 +44,9 @@ The bin is named after the package; every command is an explicit subcommand (a b
 invocation is a usage error, exit code 2). `strength` names the measurement — oracle
 strength — not the heatmap rendering of it.
 
-Everything here is a **Speccle tool**: deterministic, independently runnable, emits
-typed JSON, never calls an LLM (see [CONTEXT.md](https://github.com/matthewalton/speccle/blob/main/CONTEXT.md)).
+Every command here but one is a **Speccle tool**: deterministic, independently runnable,
+emits typed JSON, never calls an LLM (see [CONTEXT.md](https://github.com/matthewalton/speccle/blob/main/CONTEXT.md)).
+The exception is `review run`, the CI driver, which calls a model by definition.
 
 ## lint
 
@@ -75,11 +90,252 @@ test no string name, the criterion id takes its identifier-safe spelling:
 `func test_CHECKOUT_1_taxRounds()` claims `CHECKOUT-1`. Reports always render the
 bracketed form.
 
+With no `--dialect`, the dialect comes from `.speccle/config.json`, resolved **per spec
+folder** — so a mixed-language tree is joined in one pass, each slice under its own dialect
+(the config's longest matching `overrides` path wins). `--dialect` forces one dialect across
+every folder instead. The report names every dialect in play, and each feature the one its
+folder joined under:
+
+```
+ios/ladder/SPEC.md  (swift)
+  LADDER-1  1 test name  A rung raises the climber by one
+web/basket/SPEC.md  (ts-vitest)
+  BASKET-1  1 test name  When an item is added, its line quantity increments by exactly 1
+
+swift, ts-vitest — 2 spec files, 2 criteria, 2 claimed, clean
+```
+
 Names are read statically, so a name built dynamically shows up as unclaimed — the
 failure mode is a false alarm, never a silent pass. `--json` emits the typed
 `ClaimsReport` (see [`src/claims.ts`](src/claims.ts)). Exit codes: `0` every criterion
 claimed and no unknown claims, `1` otherwise, `2` usage error.
 
+## verify
+
+```sh
+speccle verify [path] [--json] [--base <ref>]
+```
+
+Runs every check in `.speccle/checks/` over a **change set**. Its reason to exist is the
+class of invariant no linter can hold, because the fact is about the whole change rather
+than any one file: _a changed `@Model` requires a round-trip test in the same change._
+
+One check, one JSON file:
+
+```json
+{
+  "when": { "path": "features/**/src/*.ts", "contains": "@Model" },
+  "require": { "path": "features/**/src/*.test.ts", "contains": "roundTrip" },
+  "message": "a changed @Model needs a round-trip test in the same change",
+  "because": "PR #412 shipped a schema change with no round-trip coverage"
+}
+```
+
+`when` is the trigger — absent means always enforced, and a check whose trigger never fires
+reports as **inactive**, not as a pass. Then exactly one requirement: `require` breaches when
+no changed file matches it, `forbid` breaches when any does, naming the offenders. Each is a
+**predicate** — a glob over root-relative posix paths (`**` spans directories), optionally
+narrowed by a `contains` regex the file's current content must match. `because` records the
+finding that created the check and prints on breach, so a breach still explains itself a year
+later.
+
+```
+model-roundtrip  a changed @Model needs a round-trip test in the same change
+  because PR #412 shipped a schema change with no round-trip coverage
+
+1 check, 1 breach
+```
+
+The change set is the working tree's pending change by default, or the commits between
+`--base <ref>` and HEAD, measured from their merge base — what a CI run needs, where the tree
+is clean and the change is committed. A repo that has authored no checks passes trivially; a
+malformed check file is a hard error naming the file, because a check that silently does
+nothing is worse than no check at all.
+
+`--json` emits the typed `VerifyReport` (see [`src/verify.ts`](src/verify.ts)). Exit codes:
+`0` no breach, `1` at least one breach, `2` usage error.
+
+## risk
+
+```sh
+speccle risk [path] [--json] [--base <ref>] [--dialect <name>]
+```
+
+Scores a change set from spec-aware signals — facts only Speccle can see, because only
+Speccle knows which code is governed by which spec. The score decides **how supervised the
+change is**: at or above the review threshold a human is required, and review stops at
+findings instead of fixing unasked.
+
+Four baseline signals ship with the CLI and apply in every repo unmodified:
+
+| signal               | weight | fires on                                                              |
+| -------------------- | -----: | --------------------------------------------------------------------- |
+| `criterion-retired`  |      4 | a criterion vanished from a changed `SPEC.md`                         |
+| `spec-silent-change` |      3 | production source changed in a governed slice whose `SPEC.md` did not |
+| `unclaimed-change`   |      3 | changed code lives in a slice with a criterion no test claims         |
+| `criterion-reworded` |      2 | a criterion's statement changed                                       |
+
+```
+spec-silent-change  +3  production source changed in a governed slice whose SPEC.md did not
+  features/checkout/src/checkout.ts
+unclaimed-change  +3  changed code lives in a slice with a criterion no test claims
+  CHECKOUT-2
+
+score 6 ≥ threshold 3 — human required, review stops at findings
+this score is a floor — a risk lens may escalate it, never lower it
+```
+
+Every fired signal carries its evidence — the files, criterion ids, or slices it fired on —
+so the number is auditable rather than asserted. The score is a **floor**: a risk lens reading
+the change may escalate beyond it, never below it.
+
+The default review threshold is `3`, deliberately low, so most changes are supervised. A repo
+may reweight in `.speccle/risk.json` — the one sanctioned piece of configurable judgement here,
+because what counts as consequential really is repo-specific:
+
+```json
+{
+  "threshold": 4,
+  "weights": { "criterion-reworded": 0 },
+  "signals": [
+    {
+      "id": "migration-without-rollback",
+      "weight": 5,
+      "when": { "path": "db/migrations/*.sql" },
+      "message": "a migration changed",
+      "because": "the incident on 2026-03-02"
+    }
+  ]
+}
+```
+
+A `0` weight mutes a baseline signal, and a muted signal is not computed at all. Only a human
+edits this file, and a malformed one is a hard error rather than a silently-ignored weight —
+a quietly dropped signal is exactly the invisible reduction of supervision the score exists to
+prevent.
+
+Whether a changed file is production source or a test is a per-path question, and
+`spec-silent-change` answers it from `.speccle/config.json`, resolved **at each changed file's
+own path** — so in a mixed tree an `ios/` slice's `PlayerTests.swift` reads as a test even
+where the repo defaults to `ts-vitest`. `--dialect` forces one dialect across every path instead.
+
+`--base` moves both the change set and the criterion baseline to the merge base. That pairing
+is load-bearing: on a branch, HEAD already contains the change, so diffing a changed `SPEC.md`
+against HEAD would compare it with itself and no criterion would ever read as retired or
+reworded.
+
+`--json` emits the typed `RiskReport` (see [`src/risk.ts`](src/risk.ts)). Exit codes: `0`
+below the review threshold (review may fix and report), `1` at or above it (a human is
+required), `2` usage error. Exit `1` is the verdict, not a failure — it is what makes the
+command usable as a status check.
+
+## calibrate
+
+```sh
+speccle calibrate record [path] --needed-human <true|false> --found-real <true|false>
+                                [--escalated] [--note <text>] [--dialect <name>] [--json]
+speccle calibrate report [path] [--json]
+```
+
+The evidence a review threshold moves on. `record` appends one line to
+`.speccle/calibration.jsonl` per reviewed change: `risk` computes the deterministic floor —
+score, threshold, the signals that fired — and the caller supplies the honest human verdict.
+
+The two are recorded side by side and never conflated, which is the whole point. `--needed-human`
+and `--found-real` are required and never defaulted, because recording the gate's verdict as if
+it were the human's produces exactly the dishonest data a threshold must not rise on.
+
+```
+recorded .speccle/calibration.jsonl — 1 entry
+  score 6 vs threshold 3 — floor required a human
+  verdict: needed a human, found something real
+  signals: spec-silent-change, unclaimed-change
+```
+
+`report` reads the record back and answers three questions arithmetically: which signals fired
+but never on a change that mattered, which fired on every change that genuinely needed a human,
+and what threshold the record would support.
+
+```
+1 reviewed change — 1 needed a human, floor gated 1
+
+  spec-silent-change  1/1 mattered — on every change that needed a human
+  unclaimed-change    1/1 mattered — on every change that needed a human
+
+proposals — evidence, not instructions (only a human reduces supervision):
+  spec-silent-change and unclaimed-change fired on every change that needed a human — reliable so far
+  the record would support a review threshold up to 6 (now 3) — only a human may raise it
+```
+
+`supportedThreshold` is the cheapest change that needed a human — conservative on purpose,
+since a floor any higher would have missed it. Escalation is excluded from that arithmetic: a
+safety net must never be the reason a floor sits high. Two counters name the failure directions
+in plain terms — `floorMisses` (needed a human, and neither the floor nor a lens caught it) and
+`overSupervised` (the floor gated a change the verdict says was fine).
+
+The report **proposes and never applies**. Nothing here edits `.speccle/risk.json`; only a
+human reduces supervision.
+
+`--json` emits the typed `RecordReport` / `CalibrationReport` (see
+[`src/calibration.ts`](src/calibration.ts)). Both subcommands exit `0` whenever they produced a
+report — the verdict is `risk`'s job — and `2` on a usage error, including a missing verdict
+flag or a malformed record line, which is reported with its line number rather than skipped.
+
+## remedy
+
+```sh
+speccle remedy record [path] --class <handle> --finding <text> --fix <text>
+                             --route <check|criterion|lens|none> [--artefact <ref>]
+                             [--note <text>] [--json]
+speccle remedy recall [path] --class <handle> [--json]
+```
+
+The memory that makes a repeat finding get the same answer twice. `record` appends one line to
+`.speccle/remedies.jsonl`: what the finding was, the fix applied to the code this time, and the
+**prevention route** chosen so the class stops recurring.
+
+| route       | prevention artefact            |
+| ----------- | ------------------------------ |
+| `check`     | a `.speccle/checks/` path      |
+| `criterion` | a `SPEC.md` criterion id       |
+| `lens`      | a `.speccle/lenses/` path      |
+| `none`      | names none — an honest one-off |
+
+Every route but `none` must name its `--artefact`: a record is only worth consulting if it
+points at the prevention it chose. `none` is the honest escape — a finding whose class is not
+worth preventing prevents nothing, and must not pretend otherwise.
+
+```
+recorded .speccle/remedies.jsonl — 1 remedy
+  missing-model-roundtrip-test: a changed @Model shipped with no round-trip test
+  fix: added a round-trip test over the changed model
+  remedy: check → .speccle/checks/model-roundtrip.json
+```
+
+`recall` looks a class up before routing a finding fresh. Matching is deterministic on the
+class handle's tokens — lowercased alphanumeric runs — and an entry matches when one side's
+tokens are a subset of the other's, so `missing-roundtrip` still recalls
+`missing-model-roundtrip-test`. Most-recent first: the latest answer to a class wins.
+
+```
+1 prior remedy for "missing-roundtrip" — reuse to fix consistently:
+
+  missing-model-roundtrip-test  (2026-07-24T19:39:15.815Z)
+    finding: a changed @Model shipped with no round-trip test
+    fix: added a round-trip test over the changed model
+    remedy: check → .speccle/checks/model-roundtrip.json
+```
+
+The `--class` handle is the reviewer's judgement, not the tool's — it only stores and retrieves,
+the same honesty split `calibrate` draws around the human verdict.
+
+`--json` emits the typed `RemedyRecordReport` / `RemedyRecallReport` (see
+[`src/remedy.ts`](src/remedy.ts)). Both subcommands exit `0` whenever they produced a report,
+**including a recall that matched nothing** — no prior remedy is an answer ("route it fresh,
+then record it"), not a failure. `2` is a usage error: a missing required flag, an unknown
+route, an artefact on a `none` remedy, or a malformed record line, reported with its line
+number rather than skipped.
+
 ## strength
 
 ```sh
@@ -125,6 +381,55 @@ no spec declares are reported too.
 command exits `0` whenever it produced a report — judging a diff against a threshold is a
 separate concern.
 
+## review
+
+The outer loop has two drivers. The **local driver** is the `review` skill: it fans the
+lenses as subagents in a session and needs no key. The **CI driver** is these two commands,
+and it is **opt-in**, because it needs a metered `ANTHROPIC_API_KEY`.
+
+```sh
+speccle review init [path] [--json]
+```
+
+Writes one file — `.github/workflows/speccle-review.yml` — pinned to the version of the CLI
+that wrote it. Nothing else is vendored: the driver ships in this tarball and the workflow
+fetches it from npm, so the code doing the reviewing never comes from the branch under
+review. Re-running moves the pin, which is how a repo updates the driver.
+
+`doctor` reports that pin as its `driver` row, so a workflow left behind on an old version
+shows up as stale rather than sitting there unnoticed; a repo that never opted in reads
+`not installed` and is not a failure. `update` moves the pin **only when the workflow is
+already there** — it will not scaffold one, because opting a repo into a driver that spends
+a metered key per run has to be deliberate.
+
+```sh
+speccle review run --pr <number> [path] [--repo <owner/name>] [--base <ref>]
+                                        [--force] [--model <id>] [--dry-run] [--json]
+```
+
+Fans every lens in `.speccle/lenses/` over the pull request's change set — one model call
+per lens, findings forced into shape by a tool schema — and posts them as a single review
+with inline comments. It **finds and comments only**: it never edits the tree, commits, or
+pushes, because a fix has to re-run the checks-gate and be revertible, which is the local
+driver's job.
+
+- Skips `risk.md` (it escalates authority rather than reporting findings) and an unauthored
+  `house-conventions.md`, exactly as the local driver does.
+- Posts one automatic review per pull request, recognised by a marker in its own body;
+  `--force` overrides that, which is what the workflow's `@review` rerun path passes.
+- A finding that cannot anchor to a line in the diff is carried in the summary rather than
+  dropped, and if GitHub rejects the anchors outright the retry carries every finding in
+  the body.
+- Reads `ANTHROPIC_API_KEY` and `GITHUB_TOKEN` from the environment; `--dry-run` reports
+  what would be posted and posts nothing. The default model is overridable with
+  `SPECCLE_REVIEW_MODEL`.
+
+The risk verdict leads the summary, and the workflow runs `speccle risk --base` as its own
+step so the **status check stays deterministic** — it survives a bad API day. Whether a
+failing check blocks the merge is branch protection: GitHub's setting, the repo's call.
+
+This is the one command here that calls a model.
+
 ## strength init
 
 ```sh
@@ -147,9 +452,16 @@ instead of a hand-assembled config recipe. In one run it:
   `features/**/*.ts`; override with `--mutate`, repeatable);
 - writes a `vitest.config.ts` with the istanbul provider and `json-summary` reporter.
 
-Init also warns (best-effort, via `~/.claude/settings.json`) when the target vendors
-the speccle skills project-level in `.claude/skills/` while a user-level speccle plugin
-is still enabled — two copies of every skill would load.
+It also reports a `speccle-oracle` devDependency as **superseded** — the name this CLI
+published under before 0.11.0. A repo provisioned back then keeps that package beside the
+current one, exposing a stale binary in `node_modules/.bin/`. Init names the removal
+command and stops there: your `package.json` is yours to change.
+
+Both init commands warn (best-effort, via `~/.claude/settings.json`) when the target
+vendors the speccle skills project-level in `.claude/skills/` while a user-level speccle
+plugin is still enabled — two copies of every skill would load. `speccle init` is the run
+that vendors them, so it warns too rather than leaving the discovery to a `strength init`
+a contract-only user may never run.
 
 An existing Stryker or vitest/vite config is **kept, never overwritten** — init reports
 it and names the fields it must carry itself. The command is idempotent: re-running

package/dist/calibration.js

@@ -0,0 +1,156 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { isDirectory, messageOf } from "./changeset.js";
+import { reviewThreshold, risk } from "./risk.js";
+/** Where the meta loop keeps its calibration record (ADR-0042): append-only, one entry per line. */
+export const CALIBRATION_FILE = ".speccle/calibration.jsonl";
+/**
+ * Appends one calibration entry: `risk` computes the deterministic floor (score, signals,
+ * threshold, humanRequired) over the change set, the caller supplies the honest human verdict.
+ * The floor and the verdict are recorded side by side and never conflated.
+ */
+export async function recordCalibration(target, input, options = {}) {
+    const root = resolve(target);
+    if (!(await isDirectory(root)))
+        throw new Error(`path not found: ${target}`);
+    const { now, ...riskOptions } = options;
+    const assessment = await risk(root, riskOptions);
+    const stamp = (now ?? (() => new Date().toISOString()))();
+    const entry = {
+        at: stamp,
+        score: assessment.score,
+        threshold: assessment.threshold,
+        humanRequired: assessment.humanRequired,
+        escalated: input.escalated ?? false,
+        signals: assessment.signals.map((signal) => signal.id),
+        verdict: { neededHuman: input.neededHuman, foundReal: input.foundReal },
+        ...(input.note !== undefined && input.note !== "" && { note: input.note }),
+    };
+    const file = join(root, CALIBRATION_FILE);
+    await mkdir(dirname(file), { recursive: true });
+    await appendFile(file, JSON.stringify(entry) + "\n");
+    return { root, file: CALIBRATION_FILE, entry, count: (await readEntries(root)).length };
+}
+/**
+ * Reads the calibration record and answers ADR-0042's three questions deterministically: which
+ * signals never corresponded to a real problem, which fired on every change a human was needed
+ * for, and the threshold the record would support. It proposes; it never applies.
+ */
+export async function calibrationReport(target) {
+    const root = resolve(target);
+    if (!(await isDirectory(root)))
+        throw new Error(`path not found: ${target}`);
+    const entries = await readEntries(root);
+    const currentThreshold = await reviewThreshold(root);
+    const mattered = (entry) => entry.verdict.neededHuman || entry.verdict.foundReal;
+    const neededEntries = entries.filter((entry) => entry.verdict.neededHuman);
+    const ids = [...new Set(entries.flatMap((entry) => entry.signals))].sort();
+    const signals = ids.map((id) => {
+        const fired = entries.filter((entry) => entry.signals.includes(id));
+        const firedOnMattered = fired.filter(mattered).length;
+        return {
+            id,
+            fired: fired.length,
+            firedOnMattered,
+            neverUseful: fired.length > 0 && firedOnMattered === 0,
+            firedOnEveryNeeded: neededEntries.length > 0 && neededEntries.every((entry) => entry.signals.includes(id)),
+        };
+    });
+    // Conservative on purpose (ADR-0041 favours more supervision): the floor could rise no higher
+    // than the cheapest change that genuinely needed a human, or the floor alone would have missed
+    // it. Escalation is ignored here — a safety net must not be the reason a floor sits high.
+    const supportedThreshold = neededEntries.length === 0 ? null : Math.min(...neededEntries.map((entry) => entry.score));
+    const floorMisses = entries.filter((entry) => entry.verdict.neededHuman && !entry.humanRequired && !entry.escalated).length;
+    const overSupervised = entries.filter((entry) => entry.humanRequired && !entry.verdict.neededHuman).length;
+    return {
+        root,
+        file: CALIBRATION_FILE,
+        count: entries.length,
+        neededByHuman: neededEntries.length,
+        gatedByFloor: entries.filter((entry) => entry.humanRequired).length,
+        floorMisses,
+        overSupervised,
+        currentThreshold,
+        supportedThreshold,
+        signals,
+        proposals: proposalsFrom(entries.length, signals, currentThreshold, supportedThreshold),
+    };
+}
+function proposalsFrom(count, signals, currentThreshold, supportedThreshold) {
+    if (count === 0)
+        return ["no calibration entries yet — review some changes to build the record"];
+    const out = [];
+    const never = signals.filter((signal) => signal.neverUseful).map((signal) => signal.id);
+    if (never.length > 0) {
+        out.push(`${and(never)} fired but never on a change that mattered — weigh their weight, not a licence to delete`);
+    }
+    const reliable = signals.filter((signal) => signal.firedOnEveryNeeded).map((signal) => signal.id);
+    if (reliable.length > 0) {
+        out.push(`${and(reliable)} fired on every change that needed a human — reliable so far`);
+    }
+    if (supportedThreshold === null) {
+        out.push("no change has needed a human yet — the record cannot support a threshold move");
+    }
+    else if (supportedThreshold > currentThreshold) {
+        out.push(`the record would support a review threshold up to ${supportedThreshold} (now ${currentThreshold}) — only a human may raise it`);
+    }
+    else if (supportedThreshold < currentThreshold) {
+        out.push(`a change that needed a human scored ${supportedThreshold}, below the threshold of ${currentThreshold} — the floor would miss it; only a human may lower the threshold`);
+    }
+    else {
+        out.push(`the threshold of ${currentThreshold} matches the record — no move indicated`);
+    }
+    return out;
+}
+async function readEntries(root) {
+    let raw;
+    try {
+        raw = await readFile(join(root, CALIBRATION_FILE), "utf8");
+    }
+    catch {
+        return []; // no record yet: nothing has been calibrated.
+    }
+    const entries = [];
+    const lines = raw.split("\n");
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i].trim();
+        if (line === "")
+            continue;
+        let entry;
+        try {
+            entry = JSON.parse(line);
+        }
+        catch (err) {
+            throw new Error(`${CALIBRATION_FILE}:${i + 1} is not valid JSON: ${messageOf(err)}`);
+        }
+        assertEntry(entry, i + 1);
+        entries.push(entry);
+    }
+    return entries;
+}
+// A malformed entry must fail loudly, naming the line — a silently-dropped entry is dishonest
+// calibration data, the one thing ADR-0042 will not tolerate in the record.
+function assertEntry(entry, line) {
+    const at = `${CALIBRATION_FILE}:${line}`;
+    const isNumber = (value) => typeof value === "number" && Number.isFinite(value);
+    if (!isNumber(entry.score) || !isNumber(entry.threshold)) {
+        throw new Error(`${at}: "score" and "threshold" must be numbers`);
+    }
+    if (typeof entry.humanRequired !== "boolean" || typeof entry.escalated !== "boolean") {
+        throw new Error(`${at}: "humanRequired" and "escalated" must be booleans`);
+    }
+    if (!Array.isArray(entry.signals) || entry.signals.some((id) => typeof id !== "string")) {
+        throw new Error(`${at}: "signals" must be an array of signal ids`);
+    }
+    const verdict = entry.verdict;
+    const fields = verdict;
+    if (typeof verdict !== "object" ||
+        verdict === null ||
+        typeof fields.neededHuman !== "boolean" ||
+        typeof fields.foundReal !== "boolean") {
+        throw new Error(`${at}: "verdict" needs boolean "neededHuman" and "foundReal"`);
+    }
+}
+function and(ids) {
+    return ids.length <= 1 ? (ids[0] ?? "") : `${ids.slice(0, -1).join(", ")} and ${ids.at(-1)}`;
+}

package/dist/changeset.js

@@ -0,0 +1,136 @@
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { gitStdout } from "./git.js";
+/** The changed files a predicate matches — by path glob, then by content when `contains` is set. */
+export async function matching(predicate, changed, read) {
+    const pattern = globToRegExp(predicate.path);
+    const contains = predicate.contains === undefined ? undefined : new RegExp(predicate.contains);
+    const matches = [];
+    for (const file of changed) {
+        if (!pattern.test(file))
+            continue;
+        if (contains !== undefined) {
+            const source = await read(file);
+            if (source === undefined || !contains.test(source))
+                continue;
+        }
+        matches.push(file);
+    }
+    return matches;
+}
+export async function anyMatches(predicate, changed, read) {
+    return (await matching(predicate, changed, read)).length > 0;
+}
+/**
+ * A reader for the change set's current content, caching each file so a file read by several
+ * predicates is only touched once. Missing files read as undefined rather than throwing.
+ */
+export function contentReader(root) {
+    const cache = new Map();
+    return async (file) => {
+        if (!cache.has(file))
+            cache.set(file, await readMaybe(join(root, file)));
+        return cache.get(file);
+    };
+}
+/** The pending change set: everything the working tree differs from its last commit by. */
+export function gitChangeSet(root) {
+    // --untracked-files=all lists new files individually; the default collapses a wholly
+    // untracked directory to its name, hiding the files that must be seen.
+    const args = ["status", "--porcelain", "--untracked-files=all"];
+    const stdout = gitStdout(root, args);
+    if (stdout === undefined) {
+        throw new Error("could not read a change set from git — run this inside a git repository");
+    }
+    const changed = new Set();
+    for (const line of stdout.split("\n")) {
+        if (line === "")
+            continue;
+        // Porcelain: two status chars, a space, then the path — or "old -> new" for a rename.
+        const path = line.slice(3);
+        changed.add(path.includes(" -> ") ? path.slice(path.indexOf(" -> ") + 4) : path);
+    }
+    return [...changed];
+}
+/**
+ * The committed change set between a base ref and HEAD — the change set a CI driver reviews,
+ * where the working tree is clean and the change lives in commits instead. Measured from the
+ * **merge base**, not the base's tip, so commits that landed on the base after this branch
+ * left it are not attributed to this change; that is the set a pull request shows.
+ */
+export function gitRangeChangeSet(root, base) {
+    const mergeBase = gitStdout(root, ["merge-base", base, "HEAD"])?.trim();
+    if (mergeBase === undefined || mergeBase === "") {
+        // The likeliest cause in CI by far: a shallow checkout that fetched no shared history.
+        throw new Error(`no merge base between "${base}" and HEAD — fetch enough history for the two to share a commit`);
+    }
+    // A rename reports its destination path only, matching the working tree's "old -> new".
+    const stdout = gitStdout(root, ["diff", "--name-only", mergeBase, "HEAD"]);
+    if (stdout === undefined)
+        throw new Error(`could not diff "${base}" against HEAD`);
+    const changed = stdout.split("\n").filter((line) => line !== "");
+    return { changed: [...new Set(changed)], baseline: mergeBase };
+}
+/** Validates a predicate's shape, naming the offending file — a silently broken predicate is worse than none. */
+export function assertPredicate(predicate, key, file) {
+    if (predicate === undefined)
+        return;
+    if (typeof predicate.path !== "string" || predicate.path === "") {
+        throw new Error(`${file}: "${key}" needs a non-empty "path" glob`);
+    }
+    if (predicate.contains !== undefined) {
+        try {
+            new RegExp(predicate.contains);
+        }
+        catch (err) {
+            throw new Error(`${file}: "${key}.contains" is not a valid regex: ${messageOf(err)}`);
+        }
+    }
+}
+/**
+ * A minimatch-style glob over posix paths: `**` spans directory boundaries, a single `*`
+ * and `?` stay within one segment.
+ */
+function globToRegExp(glob) {
+    let re = "";
+    for (let i = 0; i < glob.length; i++) {
+        const char = glob[i];
+        if (char === "*") {
+            if (glob[i + 1] === "*") {
+                i++;
+                if (glob[i + 1] === "/") {
+                    i++;
+                    re += "(?:.*/)?"; // `**/` also matches zero directories
+                }
+                else
+                    re += ".*";
+            }
+            else
+                re += "[^/]*";
+        }
+        else if (char === "?")
+            re += "[^/]";
+        else
+            re += char.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    return new RegExp(`^${re}$`);
+}
+async function readMaybe(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function isDirectory(path) {
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function messageOf(err) {
+    return err instanceof Error ? err.message : String(err);
+}