speccle 0.12.0 → 0.15.0

package/dist/cli.js

@@ -1,31 +1,82 @@
 #!/usr/bin/env node
+import { calibrationReport, recordCalibration } from "./calibration.js";
 import { check } from "./check.js";
 import { claims } from "./claims.js";
 import { initConfig } from "./config.js";
 import { DEFAULT_DIALECT, DIALECT_NAMES } from "./dialects.js";
 import { doctor } from "./doctor.js";
 import { init, ownVersion } from "./init.js";
+import { materializeLenses } from "./lenses.js";
 import { lint } from "./lint.js";
-import { renderCheck, renderClaims, renderConfigInit, renderDoctor, renderHuman, renderInit, renderSkillsInit, renderStrength, renderUpdate, } from "./render.js";
+import { recallRemedy, recordRemedy, REMEDY_ROUTES } from "./remedy.js";
+import { renderCalibrateRecord, renderCalibrateReport, renderCheck, renderClaims, renderConfigInit, renderDoctor, renderHuman, renderInit, renderLensesInit, renderRemedyRecall, renderRemedyRecord, renderReviewInit, renderReviewRun, renderRisk, renderSkillsInit, renderStrength, renderUpdate, renderVerify, } from "./render.js";
+import { scaffoldReviewWorkflow } from "./reviewinit.js";
+import { reviewRun } from "./reviewrun.js";
+import { risk } from "./risk.js";
 import { materializeSkills } from "./skills.js";
 import { DEFAULT_COVERAGE_SUMMARY, DEFAULT_MUTATION_REPORT, strength } from "./strength.js";
 import { update } from "./update.js";
+import { verify } from "./verify.js";
 const USAGE = `Usage: speccle <command> [options]
 
 Commands:
-  init [path] [--json]           Record repo facts in .speccle/config.json and materialize
-                                 the skills into .claude/skills/
-  doctor [path] [--json]         Report staleness across the CLI, skills, and strength stack
-  update [path] [--json]         Refresh the skills as a diff; report the stack and binary fixes
+  init [path] [--json]           Record repo facts in .speccle/config.json, materialize the
+                                 skills into .claude/skills/ and the lenses into .speccle/lenses/
+  doctor [path] [--json]         Report staleness across the CLI, skills, lenses, and strength stack
+  update [path] [--json]         Refresh the skills and lenses as a diff; report stack and binary fixes
   lint [path] [--json]           Lint every SPEC.md under path (default: current directory)
   claims [path] [--json]         Join criteria to the test names that claim them — no reports needed
+  verify [path] [--json]         Run .speccle/checks/ against the change set: cross-file invariants
+  risk [path] [--json]           Score the change set from spec-aware signals; gate on the review threshold
+  calibrate record [path]        Append a calibration entry: the risk floor + your honest verdict
+  calibrate report [path]        Read the calibration record: signal reliability + the supported threshold
+  remedy record [path]           Record a remedy: the finding, the fix, and the prevention artefact
+  remedy recall [path]           Recall the known remedy for a finding's class — fix consistently
+  review init [path] [--json]    Scaffold the opt-in CI driver: a GitHub Actions workflow, pinned
+  review run [path]              Review a pull request with the lens panel and post one review.
+                                 The one command here that calls a model — needs a metered key
   strength [path] [--json]       Oracle-strength heatmap: per-criterion killed ÷ covered
   strength init [path] [--json]  Provision the strength stack: devDependencies + configs
   --version, -v                  Print the installed CLI version
 
-claims options:
+claims / risk options:
   --dialect <name>    Test dialect: ${DIALECT_NAMES.join(", ")} (default: ${DEFAULT_DIALECT})
 
+verify / risk options:
+  --base <ref>        Read the change set from the commits between <ref> and HEAD, instead of the
+                      working tree's pending change — what a CI driver needs, where the tree is
+                      clean. Measured from the merge base, so it needs their shared history
+
+risk exit codes: 0 below the review threshold (review may fix), 1 at or above it (human required)
+
+calibrate record options:
+  --needed-human <true|false>  Did this change actually need a human? (required — the honest verdict)
+  --found-real <true|false>    Did the review find something real? (required)
+  --escalated                  A risk lens escalated beyond the deterministic floor
+  --note <text>                Free-text context for the entry
+  --dialect <name>             Test dialect: ${DIALECT_NAMES.join(", ")} (default: ${DEFAULT_DIALECT})
+
+remedy record options:
+  --class <handle>             Short, stable handle for the finding's class (required — the recall key)
+  --finding <text>             What the finding is (required)
+  --fix <text>                 The fix applied to the code (required)
+  --route <route>              Prevention route: ${REMEDY_ROUTES.join(", ")} (required)
+  --artefact <ref>             The prevention artefact: a .speccle/checks|lenses path or a SPEC
+                               criterion id (required for every route but none)
+  --note <text>                Free-text context for the entry
+
+remedy recall options:
+  --class <handle>             The finding's class to look up (required)
+
+review run options:
+  --pr <number>                The pull request to review (required)
+  --repo <owner/name>          Defaults to GITHUB_REPOSITORY
+  --base <ref>                 Base ref for the risk verdict (default: origin/<the PR's base>)
+  --force                      Review again even if this driver already reviewed the PR
+  --model <id>                 Overrides SPECCLE_REVIEW_MODEL
+  --dry-run                    Report what would be posted, and post nothing
+  Reads ANTHROPIC_API_KEY and GITHUB_TOKEN from the environment
+
 strength options:
   --check             Report whether the reports are fresh, stale, or missing — never runs them
   --mutation <file>   Stryker JSON report   (default: ${DEFAULT_MUTATION_REPORT})
@@ -53,6 +104,34 @@ async function main(argv) {
         return runLint(rest);
     if (command === "claims")
         return runClaims(rest);
+    if (command === "verify")
+        return runVerify(rest);
+    if (command === "risk")
+        return runRisk(rest);
+    if (command === "calibrate" && rest[0] === "record")
+        return runCalibrateRecord(rest.slice(1));
+    if (command === "calibrate" && rest[0] === "report")
+        return runCalibrateReport(rest.slice(1));
+    if (command === "calibrate") {
+        console.error(`calibrate needs a subcommand: record or report\n\n${USAGE}`);
+        return 2;
+    }
+    if (command === "remedy" && rest[0] === "record")
+        return runRemedyRecord(rest.slice(1));
+    if (command === "remedy" && rest[0] === "recall")
+        return runRemedyRecall(rest.slice(1));
+    if (command === "remedy") {
+        console.error(`remedy needs a subcommand: record or recall\n\n${USAGE}`);
+        return 2;
+    }
+    if (command === "review" && rest[0] === "init")
+        return runReviewInit(rest.slice(1));
+    if (command === "review" && rest[0] === "run")
+        return runReviewRun(rest.slice(1));
+    if (command === "review") {
+        console.error(`review needs a subcommand: init or run\n\n${USAGE}`);
+        return 2;
+    }
     if (command === "strength" && rest[0] === "init")
         return runStrengthInit(rest.slice(1));
     if (command === "strength")
@@ -98,6 +177,300 @@ async function runClaims(args) {
     console.log(json ? JSON.stringify(report, null, 2) : renderClaims(report));
     return report.clean ? 0 : 1;
 }
+async function runVerify(args) {
+    let json = false;
+    let base;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--base") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`--base needs a git ref\n\n${USAGE}`);
+                return 2;
+            }
+            base = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`verify takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await verify(positional[0] ?? ".", { ...(base !== undefined && { base }) });
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderVerify(report));
+    return report.clean ? 0 : 1;
+}
+async function runRisk(args) {
+    let json = false;
+    let dialect;
+    let base;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--dialect" || arg === "--base") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`${arg} needs ${arg === "--base" ? "a git ref" : "a dialect name"}\n\n${USAGE}`);
+                return 2;
+            }
+            if (arg === "--dialect")
+                dialect = value;
+            else
+                base = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`risk takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await risk(positional[0] ?? ".", {
+            ...(dialect !== undefined && { dialect }),
+            ...(base !== undefined && { base }),
+        });
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderRisk(report));
+    return report.humanRequired ? 1 : 0;
+}
+async function runCalibrateRecord(args) {
+    let json = false;
+    let dialect;
+    let neededHuman;
+    let foundReal;
+    let escalated = false;
+    let note;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--escalated")
+            escalated = true;
+        else if (arg === "--needed-human" || arg === "--found-real") {
+            const value = args[++i];
+            if (value !== "true" && value !== "false") {
+                console.error(`${arg} needs true or false\n\n${USAGE}`);
+                return 2;
+            }
+            if (arg === "--needed-human")
+                neededHuman = value === "true";
+            else
+                foundReal = value === "true";
+        }
+        else if (arg === "--note" || arg === "--dialect") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`${arg} needs a value\n\n${USAGE}`);
+                return 2;
+            }
+            if (arg === "--note")
+                note = value;
+            else
+                dialect = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`calibrate record takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    // The honest verdict is required, never defaulted — a fabricated verdict is the dishonest
+    // calibration data ADR-0042 exists to keep out of the record.
+    if (neededHuman === undefined || foundReal === undefined) {
+        console.error(`calibrate record needs --needed-human and --found-real\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await recordCalibration(positional[0] ?? ".", { neededHuman, foundReal, escalated, ...(note !== undefined && { note }) }, { ...(dialect !== undefined && { dialect }) });
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderCalibrateRecord(report));
+    return 0;
+}
+async function runCalibrateReport(args) {
+    let json = false;
+    const positional = [];
+    for (const arg of args) {
+        if (arg === "--json")
+            json = true;
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`calibrate report takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await calibrationReport(positional[0] ?? ".");
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderCalibrateReport(report));
+    return 0;
+}
+async function runRemedyRecord(args) {
+    let json = false;
+    let classHandle;
+    let finding;
+    let fix;
+    let route;
+    let artefact;
+    let note;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--class" ||
+            arg === "--finding" ||
+            arg === "--fix" ||
+            arg === "--route" ||
+            arg === "--artefact" ||
+            arg === "--note") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`${arg} needs a value\n\n${USAGE}`);
+                return 2;
+            }
+            if (arg === "--class")
+                classHandle = value;
+            else if (arg === "--finding")
+                finding = value;
+            else if (arg === "--fix")
+                fix = value;
+            else if (arg === "--route")
+                route = value;
+            else if (arg === "--artefact")
+                artefact = value;
+            else
+                note = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`remedy record takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    if (classHandle === undefined ||
+        finding === undefined ||
+        fix === undefined ||
+        route === undefined) {
+        console.error(`remedy record needs --class, --finding, --fix, and --route\n\n${USAGE}`);
+        return 2;
+    }
+    if (!REMEDY_ROUTES.includes(route)) {
+        console.error(`--route must be one of ${REMEDY_ROUTES.join(", ")}\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await recordRemedy(positional[0] ?? ".", {
+            class: classHandle,
+            finding,
+            fix,
+            route: route,
+            ...(artefact !== undefined && { artefact }),
+            ...(note !== undefined && { note }),
+        });
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderRemedyRecord(report));
+    return 0;
+}
+async function runRemedyRecall(args) {
+    let json = false;
+    let classHandle;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--class") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`--class needs a value\n\n${USAGE}`);
+                return 2;
+            }
+            classHandle = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`remedy recall takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    if (classHandle === undefined) {
+        console.error(`remedy recall needs --class\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await recallRemedy(positional[0] ?? ".", classHandle);
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderRemedyRecall(report));
+    return 0;
+}
 async function runDoctor(args) {
     let json = false;
     const positional = [];
@@ -266,10 +639,12 @@ async function runInit(args) {
     const root = positional[0] ?? ".";
     let config;
     let skills;
+    let lenses;
     try {
-        // Materialize first, then stamp the version onto the config — so the recorded anchor
-        // only ever names skills that actually landed on disk.
+        // Materialize first, then stamp the version onto the config — so the recorded anchors
+        // only ever name the skills and lenses that actually landed on disk.
         skills = await materializeSkills(root);
+        lenses = await materializeLenses(root);
         config = await initConfig(root, await ownVersion());
     }
     catch (err) {
@@ -277,13 +652,115 @@ async function runInit(args) {
         return 2;
     }
     if (json) {
-        console.log(JSON.stringify({ config, skills }, null, 2));
+        console.log(JSON.stringify({ config, skills, lenses }, null, 2));
     }
     else {
         console.log(renderConfigInit(config));
         console.log("");
         console.log(renderSkillsInit(skills));
+        console.log("");
+        console.log(renderLensesInit(lenses));
+    }
+    return 0;
+}
+async function runReviewInit(args) {
+    let json = false;
+    const positional = [];
+    for (const arg of args) {
+        if (arg === "--json")
+            json = true;
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`review init takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await scaffoldReviewWorkflow(positional[0] ?? ".");
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
+    }
+    console.log(json ? JSON.stringify(report, null, 2) : renderReviewInit(report));
+    return 0;
+}
+async function runReviewRun(args) {
+    let json = false;
+    let force = false;
+    let dryRun = false;
+    let pr;
+    let repo;
+    let base;
+    let model;
+    const positional = [];
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === "--json")
+            json = true;
+        else if (arg === "--force")
+            force = true;
+        else if (arg === "--dry-run")
+            dryRun = true;
+        else if (arg === "--pr" || arg === "--repo" || arg === "--base" || arg === "--model") {
+            const value = args[++i];
+            if (value === undefined) {
+                console.error(`${arg} needs a value\n\n${USAGE}`);
+                return 2;
+            }
+            if (arg === "--pr") {
+                const number = Number(value);
+                if (!Number.isInteger(number) || number <= 0) {
+                    console.error(`--pr needs a pull request number\n\n${USAGE}`);
+                    return 2;
+                }
+                pr = number;
+            }
+            else if (arg === "--repo")
+                repo = value;
+            else if (arg === "--base")
+                base = value;
+            else
+                model = value;
+        }
+        else if (arg.startsWith("-")) {
+            console.error(`Unknown option: ${arg}\n\n${USAGE}`);
+            return 2;
+        }
+        else
+            positional.push(arg);
+    }
+    if (positional.length > 1) {
+        console.error(`review run takes at most one path\n\n${USAGE}`);
+        return 2;
+    }
+    if (pr === undefined) {
+        console.error(`review run needs --pr\n\n${USAGE}`);
+        return 2;
+    }
+    let report;
+    try {
+        report = await reviewRun(positional[0] ?? ".", {
+            pr,
+            force,
+            dryRun,
+            ...(repo !== undefined && { repo }),
+            ...(base !== undefined && { base }),
+            ...(model !== undefined && { model }),
+        });
+    }
+    catch (err) {
+        console.error(message(err));
+        return 2;
     }
+    console.log(json ? JSON.stringify(report, null, 2) : renderReviewRun(report));
+    // Posting findings is not a failure: the risk gate is the check, and it runs as its own step.
     return 0;
 }
 async function runStrengthInit(args) {

package/dist/config.js

@@ -58,22 +58,25 @@ export async function detectConfig(root) {
  * written record is the source of truth, never the detection (ADR-0040), the same posture
  * `strength init` takes with the stack it provisions.
  *
- * When `skillsVersion` is given, it is (re)stamped even on the kept path: materialization
- * always refreshes the skills to the current version, so the anchor must move with them or
- * a re-run would leave the recorded version behind the files it just wrote. The facts
- * themselves stay kept — only the stamp follows the skills.
+ * When `payloadVersion` is given, it is (re)stamped onto both the skills and the lenses
+ * anchors even on the kept path: `init`/`update` materialize both from the same tarball, so
+ * the two anchors must move with them or a re-run would leave a recorded version behind the
+ * files it just wrote. The facts themselves stay kept — only the stamps follow the payload.
  */
-export async function initConfig(root, skillsVersion) {
+export async function initConfig(root, payloadVersion) {
+    const stamped = (config) => payloadVersion === undefined
+        ? config
+        : { ...config, skillsVersion: payloadVersion, lensesVersion: payloadVersion };
     const existing = await readConfig(root);
     if (existing !== undefined) {
-        const config = skillsVersion !== undefined ? { ...existing, skillsVersion } : existing;
-        if (skillsVersion !== undefined && existing.skillsVersion !== skillsVersion) {
+        const config = stamped(existing);
+        const moved = payloadVersion !== undefined &&
+            (existing.skillsVersion !== payloadVersion || existing.lensesVersion !== payloadVersion);
+        if (moved)
             await writeConfig(root, config);
-        }
         return { root, file: CONFIG_FILE, action: "kept", config };
     }
-    const detected = await detectConfig(root);
-    const config = skillsVersion !== undefined ? { ...detected, skillsVersion } : detected;
+    const config = stamped(await detectConfig(root));
     await writeConfig(root, config);
     return { root, file: CONFIG_FILE, action: "written", config };
 }

package/dist/doctor.js

@@ -2,6 +2,7 @@ import { access, readdir, readFile, stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { readConfig } from "./config.js";
 import { ownVersion, STRENGTH_DEPS, STRYKER_CONFIG_NAMES } from "./init.js";
+import { LENSES_DIR } from "./lenses.js";
 import { SKILLS_DIR } from "./skills.js";
 /**
  * Reports the truth about the three things that drift in a Speccle consumer — the CLI, the
@@ -15,8 +16,10 @@ export async function doctor(target) {
         throw new Error(`path not found: ${target}`);
     const cli = await ownVersion();
     const config = await readConfig(root);
-    const recorded = config?.skillsVersion ?? null;
-    const skillsStatus = deriveSkillsStatus(await hasSkills(root), recorded, cli);
+    const skillsRecorded = config?.skillsVersion ?? null;
+    const skillsStatus = derivePayloadStatus(await hasSkills(root), skillsRecorded, cli);
+    const lensesRecorded = config?.lensesVersion ?? null;
+    const lensesStatus = derivePayloadStatus(await hasLenses(root), lensesRecorded, cli);
     const provisioned = await anyPresent(root, STRYKER_CONFIG_NAMES);
     const declared = await declaredDeps(root);
     const deps = STRENGTH_DEPS.map((spec) => checkDep(spec, declared));
@@ -25,16 +28,18 @@ export async function doctor(target) {
         : deps.some((dep) => dep.status !== "ok")
             ? "drift"
             : "current";
-    const ok = (skillsStatus === "current" || skillsStatus === "absent") && stackStatus !== "drift";
+    const current = (status) => status === "current" || status === "absent";
+    const ok = current(skillsStatus) && current(lensesStatus) && stackStatus !== "drift";
     return {
         root,
         cli,
-        skills: { recorded, bundled: cli, status: skillsStatus },
+        skills: { recorded: skillsRecorded, bundled: cli, status: skillsStatus },
+        lenses: { recorded: lensesRecorded, bundled: cli, status: lensesStatus },
         stack: { provisioned, deps, status: stackStatus },
         ok,
     };
 }
-function deriveSkillsStatus(present, recorded, bundled) {
+function derivePayloadStatus(present, recorded, bundled) {
     if (!present)
         return "absent";
     if (recorded === null)
@@ -82,6 +87,15 @@ async function hasSkills(root) {
         return false;
     }
 }
+async function hasLenses(root) {
+    try {
+        const entries = await readdir(join(root, LENSES_DIR));
+        return entries.some((entry) => entry.endsWith(".md"));
+    }
+    catch {
+        return false;
+    }
+}
 async function anyPresent(root, names) {
     for (const name of names) {
         if (await exists(join(root, name)))