speccle 0.12.0 → 0.15.0

package/dist/lenses.js

@@ -0,0 +1,68 @@
+import { access, copyFile, mkdir, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+/** Where materialized lenses land in a target repo — the dimensions `review` fans out over. */
+export const LENSES_DIR = ".speccle/lenses";
+/**
+ * The one lens that ships as a template and is the repo's own to author (ADR-0043) — its
+ * house-conventions lens is the real IP Speccle cannot write. It is written once, when
+ * absent, and a refresh never overwrites it: clobbering an authored lens would be exactly
+ * the data loss the "with a lock" property exists to prevent.
+ */
+export const TEMPLATE_LENS = "house-conventions.md";
+/**
+ * Vendors the baseline lenses into the target's `.speccle/lenses/`, so `review` has a panel
+ * to fan out over on any repo day one (ADR-0043). The baseline lenses are Speccle's and are
+ * overwritten on every run — the same "the tarball is the source of truth" posture the skills
+ * take (ADR-0046) — but the house-conventions template is the repo's own and is only ever
+ * written when absent. Any lens the repo authored itself is left untouched: only the bundled
+ * names are considered, so a repo-added lens is never seen, let alone removed.
+ */
+export async function materializeLenses(root, source) {
+    const from = source ?? bundledLensesDir();
+    const names = await lensNames(from);
+    const target = join(root, LENSES_DIR);
+    await mkdir(target, { recursive: true });
+    const lenses = [];
+    for (const name of names) {
+        const dest = join(target, name);
+        const present = await exists(dest);
+        if (name === TEMPLATE_LENS) {
+            if (!present)
+                await copyFile(join(from, name), dest);
+            lenses.push({ name, action: present ? "kept" : "written" });
+            continue;
+        }
+        await copyFile(join(from, name), dest);
+        lenses.push({ name, action: present ? "refreshed" : "written" });
+    }
+    return { root, dir: LENSES_DIR, source: from, lenses };
+}
+async function lensNames(source) {
+    let entries;
+    try {
+        entries = await readdir(source);
+    }
+    catch {
+        throw new Error(`no bundled lenses to materialize at ${source}`);
+    }
+    return entries.filter((entry) => entry.endsWith(".md")).sort();
+}
+/**
+ * The shipped lenses: a top-level `lenses/` beside `dist/` in the published tarball. Unlike
+ * the skills — copied in from the plugin at build time — the lens sources live in this
+ * package already, so the same relative path resolves whether the CLI runs from `dist/` or
+ * straight from `src/`; no build-time bundle and no source fallback are needed.
+ */
+function bundledLensesDir() {
+    return fileURLToPath(new URL("../lenses", import.meta.url));
+}
+async function exists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/remedy.js

@@ -0,0 +1,133 @@
+import { appendFile, mkdir, readFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { isDirectory, messageOf } from "./changeset.js";
+/** Where the meta loop keeps its remedy record (ADR-0043): append-only, one entry per line. */
+export const REMEDY_FILE = ".speccle/remedies.jsonl";
+/**
+ * The prevention routes the remedy record owns — ADR-0043's routing table minus its risk-weight
+ * row, which is the calibration record's ({@link ./calibration.ts}, ADR-0042). `none` is the honest
+ * one-off: a finding whose class is not worth preventing, so it names no artefact.
+ */
+export const REMEDY_ROUTES = ["check", "criterion", "lens", "none"];
+/** Where each route's prevention artefact lives — named in the error when one is missing. */
+const ARTEFACT_HOME = {
+    check: "a .speccle/checks/ path",
+    criterion: "a SPEC.md criterion id",
+    lens: "a .speccle/lenses/ path",
+};
+/**
+ * Appends one remedy: the finding, the fix applied, and the prevention route with its artefact.
+ * Every route but `none` must name its artefact — the record is only worth consulting if it points
+ * at the prevention it chose; a `none` remedy names nothing, because a one-off prevents nothing.
+ */
+export async function recordRemedy(target, input, options = {}) {
+    const root = resolve(target);
+    if (!(await isDirectory(root)))
+        throw new Error(`path not found: ${target}`);
+    const classHandle = input.class.trim();
+    if (classHandle === "")
+        throw new Error("a remedy needs a --class (the finding's class handle)");
+    if (input.finding.trim() === "")
+        throw new Error("a remedy needs a --finding");
+    if (input.fix.trim() === "")
+        throw new Error("a remedy needs a --fix");
+    if (!REMEDY_ROUTES.includes(input.route)) {
+        throw new Error(`unknown route "${input.route}": one of ${REMEDY_ROUTES.join(", ")}`);
+    }
+    const artefact = (input.artefact ?? "").trim();
+    if (input.route === "none" && artefact !== "") {
+        throw new Error("a none remedy prevents nothing — it names no --artefact");
+    }
+    if (input.route !== "none" && artefact === "") {
+        throw new Error(`a ${input.route} remedy needs an --artefact (${ARTEFACT_HOME[input.route]})`);
+    }
+    const entry = {
+        at: (options.now ?? (() => new Date().toISOString()))(),
+        class: classHandle,
+        finding: input.finding.trim(),
+        fix: input.fix.trim(),
+        route: input.route,
+        ...(artefact !== "" && { artefact }),
+        ...(input.note !== undefined && input.note.trim() !== "" && { note: input.note.trim() }),
+    };
+    const file = join(root, REMEDY_FILE);
+    await mkdir(dirname(file), { recursive: true });
+    await appendFile(file, JSON.stringify(entry) + "\n");
+    return { root, file: REMEDY_FILE, entry, count: (await readEntries(root)).length };
+}
+/**
+ * Looks up the known-correct remedy for a finding's class so a repeat gets the same answer. Matches
+ * deterministically on the class handle's tokens (lowercased alphanumeric runs): 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.
+ */
+export async function recallRemedy(target, query) {
+    const root = resolve(target);
+    if (!(await isDirectory(root)))
+        throw new Error(`path not found: ${target}`);
+    const entries = await readEntries(root);
+    const wanted = classTokens(query);
+    const matches = wanted.size === 0
+        ? []
+        : entries
+            .filter((entry) => {
+            const have = classTokens(entry.class);
+            return have.size > 0 && (isSubset(wanted, have) || isSubset(have, wanted));
+        })
+            .reverse();
+    return { root, file: REMEDY_FILE, query, matches, count: entries.length };
+}
+/** A class handle's comparison tokens: lowercased alphanumeric runs, e.g. `model`, `roundtrip`. */
+function classTokens(handle) {
+    return new Set(handle
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter(Boolean));
+}
+function isSubset(a, b) {
+    for (const token of a)
+        if (!b.has(token))
+            return false;
+    return true;
+}
+async function readEntries(root) {
+    let raw;
+    try {
+        raw = await readFile(join(root, REMEDY_FILE), "utf8");
+    }
+    catch {
+        return []; // no record yet: nothing has been remedied.
+    }
+    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(`${REMEDY_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 remedy is a hole in the
+// memory the meta loop consults to fix consistently, exactly what ADR-0043 keeps in one place.
+function assertEntry(entry, line) {
+    const at = `${REMEDY_FILE}:${line}`;
+    const nonEmpty = (value) => typeof value === "string" && value.trim() !== "";
+    if (!nonEmpty(entry.class) || !nonEmpty(entry.finding) || !nonEmpty(entry.fix)) {
+        throw new Error(`${at}: "class", "finding", and "fix" must be non-empty strings`);
+    }
+    if (!REMEDY_ROUTES.includes(entry.route)) {
+        throw new Error(`${at}: "route" must be one of ${REMEDY_ROUTES.join(", ")}`);
+    }
+    if (entry.route === "none" ? entry.artefact !== undefined : !nonEmpty(entry.artefact)) {
+        throw new Error(`${at}: a ${entry.route} remedy ${entry.route === "none" ? "names no" : "needs an"} "artefact"`);
+    }
+}

package/dist/render.js

@@ -29,11 +29,64 @@ export function renderSkillsInit(report) {
     lines.push("these are generated files — commit them; re-run `speccle init` to refresh");
     return lines.join("\n");
 }
+export function renderLensesInit(report) {
+    const lines = [`vendored ${plural(report.lenses.length, "lens", "lenses")} into ${report.dir}/`];
+    for (const { name, action } of report.lenses) {
+        const verb = action === "written" ? "wrote" : action;
+        lines.push(`  ${verb.padEnd(9)} ${name}`);
+    }
+    lines.push("");
+    lines.push("the baseline lenses are Speccle's — refreshed each run; house-conventions.md is yours to author");
+    return lines.join("\n");
+}
+export function renderReviewInit(report) {
+    const verb = report.action === "written" ? "wrote" : "refreshed";
+    const lines = [
+        `${verb} ${report.file} — pinned to speccle@${report.pin}`,
+        "",
+        `the driver is opt-in and needs a metered ${API_KEY_SECRET} repo secret; add it before the`,
+        "next pull request, or the review step fails with no key",
+        "",
+        "it finds and comments — fixes come back through the local `review` skill",
+        "whether the risk gate blocks a merge is branch protection: GitHub's setting, your call",
+    ];
+    if (report.action === "refreshed" && !report.movedPin) {
+        lines.splice(1, 0, "  (unchanged — the workflow already pinned this version)");
+    }
+    return lines.join("\n");
+}
+export function renderReviewRun(report) {
+    if (report.outcome === "already-reviewed") {
+        return join(`${report.repo}#${report.pr} — already reviewed by this driver, so nothing was posted`, "comment `@review` on the pull request to run again");
+    }
+    const lines = [];
+    const findings = report.findings.length;
+    lines.push(`${report.repo}#${report.pr} at ${report.headSha.slice(0, 7)} — ${plural(report.lenses.length, "lens", "lenses")} ran, ${plural(findings, "finding")}`);
+    for (const lens of report.lenses) {
+        lines.push(`  ${String(lens.findings).padStart(3)}  ${lens.name}`);
+    }
+    for (const skip of [...report.skippedLenses, ...report.skippedFiles]) {
+        lines.push(`  skipped  ${skip.name} — ${skip.reason}`);
+    }
+    lines.push("");
+    if (findings > 0) {
+        lines.push(`${report.comments} inline, ${report.unplaced} unplaced in the summary`);
+    }
+    const verdict = report.risk;
+    lines.push(verdict === null
+        ? `risk not computed — no shared history with ${report.base}`
+        : verdict.humanRequired
+            ? `risk ${verdict.score} ≥ threshold ${verdict.threshold} — human required; the gate step fails`
+            : `risk ${verdict.score} < threshold ${verdict.threshold} — the gate step passes`);
+    lines.push(report.outcome === "dry-run" ? "dry run — nothing was posted" : "posted one review");
+    return lines.join("\n");
+}
 export function renderDoctor(report) {
     const lines = [
         `speccle ${report.cli}`,
         "",
-        `skills   ${describeSkills(report.skills)}`,
+        `skills   ${describePayload(report.skills, "materialized")}`,
+        `lenses   ${describePayload(report.lenses, "vendored")}`,
         `stack    ${describeStack(report.stack)}`,
     ];
     if (report.stack.status === "drift") {
@@ -45,7 +98,10 @@ export function renderDoctor(report) {
         }
     }
     lines.push("");
-    if (report.skills.status === "absent" && report.stack.status === "absent") {
+    const allAbsent = report.skills.status === "absent" &&
+        report.lenses.status === "absent" &&
+        report.stack.status === "absent";
+    if (allAbsent) {
         lines.push("Speccle is not set up here — run `speccle init`");
     }
     else if (report.ok) {
@@ -56,18 +112,18 @@ export function renderDoctor(report) {
     }
     return lines.join("\n");
 }
-function describeSkills(skills) {
-    switch (skills.status) {
+function describePayload(payload, verb) {
+    switch (payload.status) {
         case "current":
-            return `current (${skills.bundled})`;
+            return `current (${payload.bundled})`;
         case "stale":
-            return `stale — committed ${skills.recorded}, this CLI ships ${skills.bundled}`;
+            return `stale — committed ${payload.recorded}, this CLI ships ${payload.bundled}`;
         case "ahead":
-            return `ahead — committed ${skills.recorded} is newer than this CLI (${skills.bundled})`;
+            return `ahead — committed ${payload.recorded} is newer than this CLI (${payload.bundled})`;
         case "unstamped":
             return "present but unversioned — re-run `speccle init` to record the version";
         case "absent":
-            return "not materialized — run `speccle init`";
+            return `not ${verb} — run \`speccle init\``;
     }
 }
 function describeStack(stack) {
@@ -90,6 +146,15 @@ export function renderUpdate(report) {
     else {
         lines.push(`skills   ${report.skills.from ?? "unversioned"} → ${report.skills.to} — review & commit the diff`);
     }
+    if (report.lenses.from === null) {
+        lines.push(`lenses   vendored at ${report.lenses.to} — new; review & commit the diff`);
+    }
+    else if (report.lenses.from === report.lenses.to) {
+        lines.push(`lenses   already at ${report.lenses.to} — refreshed in place; review the diff`);
+    }
+    else {
+        lines.push(`lenses   ${report.lenses.from} → ${report.lenses.to} — review & commit the diff`);
+    }
     if (report.stack.status === "absent") {
         lines.push("stack    not provisioned — run `speccle strength init`");
     }
@@ -128,6 +193,143 @@ function describeReport(check) {
         return `${check.path} — stale (${check.staleAgainst} is newer)`;
     return `${check.path} — fresh`;
 }
+import { API_KEY_SECRET } from "./reviewinit.js";
+export function renderVerify(report) {
+    const enforced = report.checks.filter((check) => check.status !== "inactive");
+    if (enforced.length === 0) {
+        const scanned = plural(report.changed.length, "changed file");
+        const authored = report.checks.length === 0 ? "no checks authored" : "no check applied";
+        return join(changeSetLine(report), `${authored} — ${scanned} scanned`);
+    }
+    const lines = [];
+    const header = changeSetLine(report);
+    if (header !== undefined)
+        lines.push(header, "");
+    for (const check of enforced.filter((check) => check.status === "breach")) {
+        lines.push(renderBreach(check));
+    }
+    if (lines.length > 0)
+        lines.push("");
+    const breaches = report.breaches;
+    const checks = plural(enforced.length, "check");
+    lines.push(report.clean ? `${checks}, clean` : `${checks}, ${plural(breaches, "breach", "breaches")}`);
+    return lines.join("\n");
+}
+function renderBreach(check) {
+    const lines = [`${check.id}  ${check.message}`];
+    for (const offender of check.offenders ?? [])
+        lines.push(`  ${offender}`);
+    if (check.because !== undefined)
+        lines.push(`  because ${check.because}`);
+    return lines.join("\n");
+}
+export function renderRisk(report) {
+    const lines = [];
+    const header = changeSetLine(report);
+    if (header !== undefined)
+        lines.push(header, "");
+    for (const signal of report.signals) {
+        lines.push(`${signal.id}  +${signal.weight}  ${signal.reason}`);
+        for (const item of signal.evidence)
+            lines.push(`  ${item}`);
+        if (signal.because !== undefined)
+            lines.push(`  because ${signal.because}`);
+    }
+    if (report.signals.length > 0)
+        lines.push("");
+    else
+        lines.push(`no risk signals fired — ${plural(report.changed.length, "changed file")} scanned`);
+    lines.push(report.humanRequired
+        ? `score ${report.score} ≥ threshold ${report.threshold} — human required, review stops at findings`
+        : `score ${report.score} < threshold ${report.threshold} — review may fix and report`);
+    // Legibility (ADR-0041): the computed score is a floor a risk lens may raise, never lower.
+    lines.push("this score is a floor — a risk lens may escalate it, never lower it");
+    return lines.join("\n");
+}
+export function renderCalibrateRecord(report) {
+    const entry = report.entry;
+    const floor = `score ${entry.score} vs threshold ${entry.threshold}`;
+    const gate = entry.humanRequired ? " — floor required a human" : "";
+    const escalated = entry.escalated ? " — a lens escalated" : "";
+    const verdict = `${entry.verdict.neededHuman ? "needed a human" : "no human needed"}, ${entry.verdict.foundReal ? "found something real" : "found nothing real"}`;
+    const lines = [
+        `recorded ${report.file} — ${plural(report.count, "entry", "entries")}`,
+        `  ${floor}${gate}${escalated}`,
+        `  verdict: ${verdict}`,
+    ];
+    if (entry.signals.length > 0)
+        lines.push(`  signals: ${entry.signals.join(", ")}`);
+    return lines.join("\n");
+}
+export function renderCalibrateReport(report) {
+    if (report.count === 0) {
+        return "no calibration entries yet — review some changes to build the record";
+    }
+    const changes = plural(report.count, "reviewed change");
+    const lines = [
+        `${changes} — ${report.neededByHuman} needed a human, floor gated ${report.gatedByFloor}`,
+    ];
+    if (report.floorMisses > 0) {
+        lines.push(`  ${plural(report.floorMisses, "floor miss", "floor misses")} — needed a human the floor did not catch`);
+    }
+    if (report.overSupervised > 0) {
+        lines.push(`  ${report.overSupervised} over-supervised — floor required a human the verdict did not`);
+    }
+    if (report.signals.length > 0) {
+        lines.push("");
+        const width = Math.max(...report.signals.map((signal) => signal.id.length));
+        for (const signal of report.signals) {
+            const note = signal.neverUseful
+                ? " — never on a change that mattered"
+                : signal.firedOnEveryNeeded
+                    ? " — on every change that needed a human"
+                    : "";
+            lines.push(`  ${signal.id.padEnd(width)}  ${signal.firedOnMattered}/${signal.fired} mattered${note}`);
+        }
+    }
+    lines.push("");
+    lines.push("proposals — evidence, not instructions (only a human reduces supervision):");
+    for (const proposal of report.proposals)
+        lines.push(`  ${proposal}`);
+    return lines.join("\n");
+}
+/** The route with its artefact, or the honest one-off — how a remedy's prevention reads on one line. */
+function remedyDestination(route, artefact) {
+    return route === "none" ? "one-off — no prevention artefact" : `${route} → ${artefact}`;
+}
+export function renderRemedyRecord(report) {
+    const entry = report.entry;
+    const lines = [
+        `recorded ${report.file} — ${plural(report.count, "remedy", "remedies")}`,
+        `  ${entry.class}: ${entry.finding}`,
+        `  fix: ${entry.fix}`,
+        `  remedy: ${remedyDestination(entry.route, entry.artefact)}`,
+    ];
+    if (entry.note !== undefined)
+        lines.push(`  note: ${entry.note}`);
+    return lines.join("\n");
+}
+export function renderRemedyRecall(report) {
+    if (report.count === 0) {
+        return `no remedy record yet — nothing to recall for "${report.query}"`;
+    }
+    if (report.matches.length === 0) {
+        const onRecord = plural(report.count, "remedy", "remedies");
+        return `no prior remedy for "${report.query}" — route it fresh, then record it (${onRecord} on record)`;
+    }
+    const found = plural(report.matches.length, "prior remedy", "prior remedies");
+    const lines = [`${found} for "${report.query}" — reuse to fix consistently:`];
+    for (const entry of report.matches) {
+        lines.push("");
+        lines.push(`  ${entry.class}  (${entry.at})`);
+        lines.push(`    finding: ${entry.finding}`);
+        lines.push(`    fix: ${entry.fix}`);
+        lines.push(`    remedy: ${remedyDestination(entry.route, entry.artefact)}`);
+        if (entry.note !== undefined)
+            lines.push(`    note: ${entry.note}`);
+    }
+    return lines.join("\n");
+}
 export function renderClaims(report) {
     if (report.features.length === 0)
         return "No SPEC.md files found.";
@@ -310,6 +512,19 @@ function ansi(text, code) {
 function bold(text, color) {
     return color ? ansi(text, "1") : text;
 }
-function plural(n, noun) {
-    return `${n} ${noun}${n === 1 ? "" : "s"}`;
+function plural(n, noun, plural = `${noun}s`) {
+    return `${n} ${n === 1 ? noun : plural}`;
+}
+/**
+ * Names the change set a committed-range run was measured over — a score whose change set is
+ * invisible is not auditable, and the CI driver's whole output is read from a log. Absent for
+ * the working tree's pending change, where "what changed" is already in front of you.
+ */
+function changeSetLine(report) {
+    if (report.base === undefined)
+        return undefined;
+    return `change set: ${report.base}...HEAD — ${plural(report.changed.length, "file")}`;
+}
+function join(...lines) {
+    return lines.filter((line) => line !== undefined).join("\n");
 }

package/dist/reviewinit.js

@@ -0,0 +1,139 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { ownVersion } from "./init.js";
+/** Where the scaffolded workflow lands. One file: the driver itself ships in the tarball. */
+export const WORKFLOW_FILE = ".github/workflows/speccle-review.yml";
+/** The repo secret the CI driver cannot run without — and the reason the driver is opt-in. */
+export const API_KEY_SECRET = "ANTHROPIC_API_KEY";
+/**
+ * Scaffolds the review workflow — the CI driver's one artefact in a consumer repo (ADR-0047).
+ * The runner itself is not vendored: the workflow pins `speccle@<version>` and npm serves it, so
+ * the code doing the reviewing never comes from the branch being reviewed, and there is nothing
+ * committed here to drift from the CLI. Re-running is how a repo moves the pin.
+ */
+export async function scaffoldReviewWorkflow(root, version) {
+    const pin = version ?? (await ownVersion());
+    const path = join(root, WORKFLOW_FILE);
+    const existing = await readMaybe(path);
+    const workflow = renderWorkflow(pin);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, workflow);
+    return {
+        root,
+        file: WORKFLOW_FILE,
+        action: existing === undefined ? "written" : "refreshed",
+        pin,
+        movedPin: existing !== undefined && existing !== workflow,
+    };
+}
+/** The pinned version an already-scaffolded workflow names, or undefined when it names none. */
+export function pinnedVersion(workflow) {
+    return /\bspeccle@(\d+\.\d+\.\d+[^\s]*)/.exec(workflow)?.[1];
+}
+/**
+ * The workflow, with every hardening decision stated in a comment beside the line that enforces
+ * it: a scaffolded file is read by people deciding whether to trust it, and a guard whose reason
+ * is undocumented is a guard someone deletes.
+ */
+function renderWorkflow(pin) {
+    return `# Speccle review — the outer loop, running in CI. Written by \`speccle review init\`.
+#
+# It fans this repo's \`.speccle/lenses/\` over a pull request's change set, posts what they find
+# as one review with inline comments, and reports the deterministic risk verdict as a check.
+# It finds and comments; it never pushes a fix — fixes come back through the local \`review\`
+# skill, which can re-run the checks-gate and revert a fix that goes red.
+#
+# Before this can run:
+#   1. Add a metered ${API_KEY_SECRET} repo secret. This driver calls a model once per lens per
+#      pull request, which is why it is opt-in; the local \`review\` skill needs no key.
+#   2. Protect this file. Anyone who can edit a workflow can read the secrets it uses — put
+#      \`.github/\` behind CODEOWNERS or a branch protection rule.
+#
+# Re-run \`speccle review init\` to move the pinned version below.
+
+name: Speccle review
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  # The rerun path: an \`@review\` comment on the pull request, gated on write access below.
+  issue_comment:
+    types: [created]
+
+# Least privilege: post a review, read the tree, nothing else.
+permissions:
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: speccle-review-\${{ github.event.pull_request.number || github.event.issue.number }}
+  cancel-in-progress: true
+
+jobs:
+  review:
+    runs-on: ubuntu-latest
+    # Two ways in, each gated. A pull request must come from a branch of this repo, never a
+    # fork: a fork's pull request must not reach the API key. A comment must come from someone
+    # who can already write here, or \`@review\` would be a way to spend the key from outside.
+    if: >-
+      (github.event_name == 'pull_request' &&
+       github.event.pull_request.head.repo.full_name == github.repository) ||
+      (github.event_name == 'issue_comment' &&
+       github.event.issue.pull_request != null &&
+       startsWith(github.event.comment.body, '@review') &&
+       contains(fromJSON('["OWNER","MEMBER","COLLABORATOR"]'), github.event.comment.author_association))
+    steps:
+      # The comment event carries no refs, so resolve them for both paths the same way.
+      - name: Resolve the pull request
+        id: pr
+        env:
+          GH_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+        run: |
+          number=\${{ github.event.pull_request.number || github.event.issue.number }}
+          pr=$(gh api "repos/\${{ github.repository }}/pulls/$number")
+          {
+            echo "number=$number"
+            echo "base=$(echo "$pr" | jq -r .base.ref)"
+            echo "head=$(echo "$pr" | jq -r .head.sha)"
+          } >> "$GITHUB_OUTPUT"
+
+      - uses: actions/checkout@v5
+        with:
+          # The head commit itself, not the synthetic merge commit: the change set under review
+          # is what the branch says, and the comment path would otherwise land on the default
+          # branch. The head is data here — the reviewing code comes from npm, pinned below.
+          ref: \${{ steps.pr.outputs.head }}
+          # \`risk\` measures from the merge base, which a shallow clone has no history to find.
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      # \`origin/\` prefixes the base ref because checkout leaves it as a remote-tracking ref;
+      # a bare branch name would not resolve.
+      - name: Review the change set
+        env:
+          ${API_KEY_SECRET}: \${{ secrets.${API_KEY_SECRET} }}
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+        run: >-
+          npx -y speccle@${pin} review run
+          --pr \${{ steps.pr.outputs.number }}
+          --base origin/\${{ steps.pr.outputs.base }}
+          \${{ github.event_name == 'issue_comment' && '--force' || '' }}
+
+      # The status check. \`risk\` exits 1 at or above the review threshold, so a failing step is
+      # the failing check. Whether that blocks the merge is branch protection — GitHub's, and
+      # this repo's call to make, not Speccle's. It runs last so the findings post either way.
+      - name: Risk gate
+        run: npx -y speccle@${pin} risk --base origin/\${{ steps.pr.outputs.base }}
+`;
+}
+async function readMaybe(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}