speccle 0.12.0 → 0.16.0

package/dist/risk.js

@@ -0,0 +1,243 @@
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { assertPredicate, contentReader, gitChangeSet, gitRangeChangeSet, isDirectory, matching, messageOf, } from "./changeset.js";
+import { claims } from "./claims.js";
+import { readConfig, resolveFacts } from "./config.js";
+import { DEFAULT_DIALECT, resolveDialect } from "./dialects.js";
+import { discoverSpecs } from "./discover.js";
+import { gitStdout } from "./git.js";
+import { parseSpec } from "./spec.js";
+/** Where a repo declares its risk policy (ADR-0041) — judgement, so a single hand-edited file. */
+export const RISK_POLICY_FILE = ".speccle/risk.json";
+/** The shipped weight of each baseline signal; a repo may reweight or mute (0) in its policy. */
+const BASELINE_WEIGHTS = {
+    "spec-silent-change": 3,
+    "criterion-retired": 4,
+    "criterion-reworded": 2,
+    "unclaimed-change": 3,
+};
+const BASELINE_IDS = Object.keys(BASELINE_WEIGHTS);
+/** The review threshold a repo has not overridden. Low by design — most changes supervised (ADR-0041). */
+export const DEFAULT_THRESHOLD = 3;
+export async function risk(target, options = {}) {
+    const root = resolve(target);
+    if (!(await isDirectory(root)))
+        throw new Error(`path not found: ${target}`);
+    const policy = await loadPolicy(root);
+    const threshold = policy.threshold ?? DEFAULT_THRESHOLD;
+    const weightOf = (id) => policy.weights?.[id] ?? BASELINE_WEIGHTS[id];
+    // Read the range once: it carries both the change set and the ref a criterion's baseline
+    // reads from, and the two must agree or the diff is measured against the wrong commit.
+    const range = options.base === undefined ? undefined : gitRangeChangeSet(root, options.base);
+    const changed = (options.changed ?? range?.changed ?? gitChangeSet(root)).slice().sort();
+    // Resolved here rather than where it is used, so a bogus `--dialect` fails loudly even when
+    // every signal that would have read it is muted.
+    const forced = options.dialect === undefined ? undefined : resolveDialect(options.dialect);
+    const baselineRef = range?.baseline ?? "HEAD";
+    const baseline = options.baseline ?? ((file) => gitBaseline(root, file, baselineRef));
+    const read = contentReader(root);
+    const signals = [];
+    const fireBaseline = (id, reason, evidence) => {
+        const weight = weightOf(id);
+        if (weight > 0 && evidence.length > 0) {
+            signals.push({ id, weight, source: "baseline", reason, evidence: unique(evidence) });
+        }
+    };
+    // Baseline signals — the spec-aware facts only Speccle can see. A muted (0-weight) signal is
+    // not computed at all, keeping the git and claims work off the path when a repo has opted out.
+    if (weightOf("spec-silent-change") > 0) {
+        fireBaseline("spec-silent-change", "production source changed in a governed slice whose SPEC.md did not", await specSilentChanges(root, changed, forced));
+    }
+    if (weightOf("criterion-retired") > 0 || weightOf("criterion-reworded") > 0) {
+        const { retired, reworded } = await criterionDiffs(changed, read, baseline);
+        fireBaseline("criterion-retired", "a criterion was retired from a changed SPEC.md", retired);
+        fireBaseline("criterion-reworded", "a criterion's statement was reworded", reworded);
+    }
+    if (weightOf("unclaimed-change") > 0) {
+        fireBaseline("unclaimed-change", "changed code lives in a slice with a criterion no test claims", await unclaimedChanges(root, changed, options.dialect));
+    }
+    // Policy signals — repo-defined predicates over the change set.
+    for (const signal of policy.signals ?? []) {
+        if (signal.weight === 0)
+            continue;
+        const hits = await matching(signal.when, changed, read); // when: present, enforced by loadPolicy.
+        if (hits.length === 0)
+            continue;
+        signals.push({
+            id: signal.id,
+            weight: signal.weight,
+            source: "policy",
+            reason: signal.message,
+            evidence: hits,
+            ...(signal.because !== undefined && { because: signal.because }),
+        });
+    }
+    const score = signals.reduce((sum, signal) => sum + signal.weight, 0);
+    return {
+        root,
+        changed,
+        ...(options.base !== undefined && { base: options.base }),
+        signals,
+        score,
+        threshold,
+        humanRequired: score >= threshold,
+    };
+}
+/**
+ * Governed-slice production source that changed while the slice's SPEC.md stayed silent.
+ *
+ * Whether a changed file is a test is a per-path question, so with no forced dialect each file
+ * is judged under the one the config resolves at its own path (ADR-0040) — a swift slice's
+ * `PlayerTests.swift` is a test even in a repo that defaults to ts-vitest. Resolved at the file
+ * rather than its spec folder: that also honours an override deeper than the folder, and keeps
+ * an outer slice from misreading a nested slice's tests as production source.
+ */
+async function specSilentChanges(root, changed, forced) {
+    const specs = await discoverSpecs(root);
+    const config = forced === undefined ? await readConfig(root) : undefined;
+    const dialectAt = (file) => forced ??
+        resolveDialect(config === undefined ? DEFAULT_DIALECT : resolveFacts(config, file).dialect);
+    const silent = [];
+    for (const spec of specs) {
+        const folder = dirname(spec);
+        if (changed.includes(spec))
+            continue; // the spec moved with its code — not silent.
+        for (const file of changed) {
+            if (!underFolder(file, folder))
+                continue;
+            if (isContractFile(file, folder) || dialectAt(file).isTestFile(file))
+                continue;
+            silent.push(file);
+        }
+    }
+    return silent;
+}
+/** Criterion ids retired or reworded between each changed SPEC.md's baseline and its current text. */
+async function criterionDiffs(changed, read, baseline) {
+    const retired = [];
+    const reworded = [];
+    for (const spec of changed.filter(isSpecPath)) {
+        const before = await baseline(spec);
+        if (before === undefined)
+            continue; // a newly added spec retires and rewords nothing.
+        const past = criteriaOf(before, spec);
+        const now = criteriaOf((await read(spec)) ?? "", spec); // deleted spec → every criterion retired.
+        for (const [id, statement] of past) {
+            if (!now.has(id))
+                retired.push(id);
+            else if (now.get(id) !== statement)
+                reworded.push(id);
+        }
+    }
+    return { retired, reworded };
+}
+/**
+ * Unclaimed criterion ids in the governed slices this change touched. Only an explicit
+ * `--dialect` is passed down: without one, `claims` resolves each slice's own dialect from the
+ * config, so a mixed-language tree is not joined under whichever dialect the repo defaults to.
+ */
+async function unclaimedChanges(root, changed, dialect) {
+    const report = await claims(root, { ...(dialect !== undefined && { dialect }) });
+    const unclaimed = [];
+    for (const feature of report.features) {
+        const folder = dirname(feature.spec);
+        if (!changed.some((file) => underFolder(file, folder)))
+            continue;
+        for (const criterion of feature.criteria) {
+            if (!criterion.claimed)
+                unclaimed.push(criterion.id);
+        }
+    }
+    return unclaimed;
+}
+/** The well-formed criteria of a SPEC.md, id → statement. */
+function criteriaOf(content, file) {
+    const criteria = new Map();
+    for (const criterion of parseSpec(content, file).criteria) {
+        if (criterion.wellFormed)
+            criteria.set(criterion.id, criterion.statement);
+    }
+    return criteria;
+}
+/** The review threshold in force at a repo — its policy override, or the shipped default. */
+export async function reviewThreshold(root) {
+    return (await loadPolicy(root)).threshold ?? DEFAULT_THRESHOLD;
+}
+async function loadPolicy(root) {
+    let raw;
+    try {
+        raw = await readFile(resolve(root, RISK_POLICY_FILE), "utf8");
+    }
+    catch {
+        return {}; // no policy: the conservative baseline defaults apply.
+    }
+    let policy;
+    try {
+        policy = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`${RISK_POLICY_FILE} is not valid JSON: ${messageOf(err)}`);
+    }
+    assertPolicy(policy);
+    return policy;
+}
+// A malformed policy must fail loudly: a silently-ignored weight or signal is exactly the
+// quiet reduction of supervision ADR-0041 is designed to prevent.
+function assertPolicy(policy) {
+    const file = RISK_POLICY_FILE;
+    if (policy.threshold !== undefined && !isNonNegativeNumber(policy.threshold)) {
+        throw new Error(`${file}: "threshold" must be a non-negative number`);
+    }
+    for (const [id, weight] of Object.entries(policy.weights ?? {})) {
+        if (!BASELINE_IDS.includes(id)) {
+            throw new Error(`${file}: unknown baseline signal in "weights": ${id} — known: ${BASELINE_IDS.join(", ")}`);
+        }
+        if (!isNonNegativeNumber(weight)) {
+            throw new Error(`${file}: weight for "${id}" must be a non-negative number`);
+        }
+    }
+    const seen = new Set();
+    for (const signal of policy.signals ?? []) {
+        if (typeof signal.id !== "string" || signal.id === "") {
+            throw new Error(`${file}: a signal needs a non-empty "id"`);
+        }
+        if (BASELINE_IDS.includes(signal.id)) {
+            throw new Error(`${file}: signal id "${signal.id}" collides with a baseline signal — reweight it in "weights" instead`);
+        }
+        if (seen.has(signal.id))
+            throw new Error(`${file}: duplicate signal id "${signal.id}"`);
+        seen.add(signal.id);
+        if (!isNonNegativeNumber(signal.weight)) {
+            throw new Error(`${file}: signal "${signal.id}" needs a non-negative "weight"`);
+        }
+        if (typeof signal.message !== "string" || signal.message === "") {
+            throw new Error(`${file}: signal "${signal.id}" needs a non-empty "message"`);
+        }
+        if (signal.when === undefined) {
+            throw new Error(`${file}: signal "${signal.id}" needs a "when" predicate`);
+        }
+        assertPredicate(signal.when, "when", file);
+    }
+}
+/** Content of a path at `ref`, or undefined when git has no baseline for it (new or no commits). */
+function gitBaseline(root, file, ref) {
+    return gitStdout(root, ["show", `${ref}:./${file}`]);
+}
+function isSpecPath(file) {
+    return file === "SPEC.md" || file.endsWith("/SPEC.md");
+}
+function isContractFile(file, folder) {
+    const base = file.slice(file.lastIndexOf("/") + 1);
+    if (base === "SPEC.md" || base === "CONTEXT.md" || base === "AGENTS.md")
+        return true;
+    return file.startsWith(folder === "." ? "decisions/" : `${folder}/decisions/`);
+}
+function underFolder(file, folder) {
+    return folder === "." || file === folder || file.startsWith(`${folder}/`);
+}
+function isNonNegativeNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+function unique(values) {
+    return [...new Set(values)].sort();
+}

package/dist/update.js

@@ -2,15 +2,21 @@ import { resolve } from "node:path";
 import { initConfig, readConfig } from "./config.js";
 import { doctor } from "./doctor.js";
 import { detectPackageManager, installCommandFor } from "./init.js";
+import { materializeLenses } from "./lenses.js";
+import { scaffoldReviewWorkflow } from "./reviewinit.js";
 import { materializeSkills } from "./skills.js";
 /** The global-install one-liner. npm is the portable choice: it ships with Node. */
 const BINARY_UPDATE = "npm install -g speccle@latest";
 /**
  * Brings a Speccle consumer current (#182). Only the per-repo halves are touched, and only
- * as a reviewable diff: the skills are re-materialized from the bundled copy and the anchor
- * re-stamped, while the strength stack and global binary are reported, never rewritten — the
+ * as a reviewable diff: the skills and the baseline lenses are re-materialized from the
+ * bundled copy and both anchors re-stamped — the house-conventions lens the repo authored is
+ * left alone — while the strength stack and global binary are reported, never rewritten: the
  * ticket's principle that only the binary may update silently, and it does so through the
  * printed command, not through this deterministic tool.
+ *
+ * The CI driver moves only if it is already there (#187): the workflow spends a metered API
+ * key per run, so scaffolding one into a repo that never asked would be opting it in silently.
  */
 export async function update(target) {
     const root = resolve(target);
@@ -19,8 +25,12 @@ export async function update(target) {
         throw new Error("not initialized — run `speccle init` first");
     }
     const version = diagnosis.cli;
-    const materialized = await materializeSkills(root);
-    await initConfig(root, version); // re-stamp the anchor; the repo facts stay kept
+    const materializedSkills = await materializeSkills(root);
+    const materializedLenses = await materializeLenses(root);
+    await initConfig(root, version); // re-stamp both anchors; the repo facts stay kept
+    const hasDriver = diagnosis.driver.status !== "absent";
+    if (hasDriver)
+        await scaffoldReviewWorkflow(root, version);
     const outstanding = diagnosis.stack.deps.filter((dep) => dep.status !== "ok");
     const fixCommand = diagnosis.stack.status === "drift"
         ? installCommandFor(await detectPackageManager(root), outstanding.map((dep) => `${dep.name}@^${dep.wantedMajor}`))
@@ -31,9 +41,16 @@ export async function update(target) {
         skills: {
             from: diagnosis.skills.recorded,
             to: version,
-            dir: materialized.dir,
-            skills: materialized.skills,
+            dir: materializedSkills.dir,
+            skills: materializedSkills.skills,
         },
+        lenses: {
+            from: diagnosis.lenses.recorded,
+            to: version,
+            dir: materializedLenses.dir,
+            lenses: materializedLenses.lenses,
+        },
+        driver: { from: diagnosis.driver.recorded, to: hasDriver ? version : null },
         stack: { status: diagnosis.stack.status, deps: diagnosis.stack.deps, fixCommand },
     };
 }

package/dist/verify.js

@@ -0,0 +1,92 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { anyMatches, assertPredicate, contentReader, gitChangeSet, gitRangeChangeSet, isDirectory, matching, messageOf, } from "./changeset.js";
+/** Where a repo keeps its hand- and meta-loop-authored checks (ADR-0043). */
+export const CHECKS_DIR = ".speccle/checks";
+export async function verify(target, options = {}) {
+    const root = resolve(target);
+    if (!(await isDirectory(root)))
+        throw new Error(`path not found: ${target}`);
+    const checks = await loadChecks(root);
+    const changed = (options.changed ?? changeSetOf(root, options.base)).slice().sort();
+    const read = contentReader(root);
+    const results = [];
+    for (const { check, file } of checks) {
+        results.push(await evaluate(check, file, changed, read));
+    }
+    const breaches = results.filter((result) => result.status === "breach").length;
+    return {
+        root,
+        changed,
+        ...(options.base !== undefined && { base: options.base }),
+        checks: results,
+        breaches,
+        clean: breaches === 0,
+    };
+}
+/** The working tree's pending change, or the commits a base ref and HEAD differ by. */
+function changeSetOf(root, base) {
+    return base === undefined ? gitChangeSet(root) : gitRangeChangeSet(root, base).changed;
+}
+async function evaluate(check, file, changed, read) {
+    const base = {
+        id: check.id ?? basename(file),
+        file,
+        message: check.message,
+        ...(check.because !== undefined && { because: check.because }),
+    };
+    if (check.when !== undefined && !(await anyMatches(check.when, changed, read))) {
+        return { ...base, status: "inactive" };
+    }
+    if (check.forbid !== undefined) {
+        const offenders = await matching(check.forbid, changed, read);
+        return offenders.length === 0
+            ? { ...base, status: "pass" }
+            : { ...base, status: "breach", offenders };
+    }
+    // require: enforced above by loadChecks, so it is defined here.
+    const satisfied = await anyMatches(check.require, changed, read);
+    return { ...base, status: satisfied ? "pass" : "breach" };
+}
+async function loadChecks(root) {
+    let entries;
+    try {
+        entries = await readdir(join(root, CHECKS_DIR));
+    }
+    catch {
+        return []; // no checks dir: a repo that has authored none passes trivially.
+    }
+    const loaded = [];
+    for (const name of entries.filter((name) => name.endsWith(".json")).sort()) {
+        const file = `${CHECKS_DIR}/${name}`;
+        const raw = await readFile(join(root, file), "utf8");
+        let check;
+        try {
+            check = JSON.parse(raw);
+        }
+        catch (err) {
+            throw new Error(`${file} is not valid JSON: ${messageOf(err)}`);
+        }
+        assertCheck(check, file);
+        loaded.push({ check, file });
+    }
+    return loaded;
+}
+// A malformed check must fail loudly, naming the file — a check that silently does nothing is
+// worse than no check, because the meta loop trusts it to hold the invariant.
+function assertCheck(check, file) {
+    if (typeof check.message !== "string" || check.message === "") {
+        throw new Error(`${file}: a check needs a non-empty "message"`);
+    }
+    const requirements = [check.require, check.forbid].filter((r) => r !== undefined);
+    if (requirements.length !== 1) {
+        throw new Error(`${file}: a check needs exactly one of "require" or "forbid"`);
+    }
+    assertPredicate(check.when, "when", file);
+    assertPredicate(check.require, "require", file);
+    assertPredicate(check.forbid, "forbid", file);
+}
+function basename(file) {
+    const name = file.slice(file.lastIndexOf("/") + 1);
+    return name.endsWith(".json") ? name.slice(0, -".json".length) : name;
+}

package/lenses/accessibility.md

@@ -0,0 +1,39 @@
+# accessibility lens
+
+**Stance:** someone reaches this change with a keyboard, a screen reader, and a magnified
+low-contrast display. Read the diff as the interface they actually meet.
+
+## What to look for
+
+- **Semantics** — a real `<button>` / `<a>` / `<label>` / heading where a styled `<div>`
+  was used; a control with no accessible name; a landmark or list expressed only visually.
+- **Keyboard** — an interactive element that is not focusable, a focus trap, a custom widget
+  with no key handlers, an action reachable only by hover or click, focus lost after a
+  route or modal change.
+- **Screen reader** — an image, icon button, or input with no text alternative; state
+  (expanded, selected, busy, invalid) conveyed only by colour or position; a live region
+  missing where content updates silently.
+- **ARIA** — a role or `aria-*` that contradicts the element, a required attribute for the
+  role omitted, ARIA used to paper over a non-semantic element that should just be the right
+  element.
+- **Contrast & zoom** — text or an essential icon below the contrast threshold; a tap target
+  too small; a fixed pixel layout that breaks at 200% zoom or reflow.
+- **Motion & media** — animation with no reduced-motion path; media with no captions or
+  transcript.
+
+## How to report
+
+Report only findings anchored to a **changed line** in this change set. For each finding
+give:
+
+- `path:line` — the changed line it anchors to
+- **severity** — blocker (blocks a task for an assistive-tech user) · major · minor · nit
+- **what** — the barrier in one line
+- **why** — who is blocked and from what: "a screen-reader user cannot tell this toggle is
+  on"; cite the WCAG success criterion when you know it
+- **fix** — the semantic element, name, or attribute that removes the barrier
+- **route** — `criterion` · `check` (e.g. "an `<img>` under `components/` must carry `alt`")
+  · `lens` · `none`
+
+Prefer a real semantic element over an ARIA patch, and say so in the fix. An empty report is
+a valid result.

package/lenses/architecture.md

@@ -0,0 +1,38 @@
+# architecture lens
+
+**Stance:** read the change for the shape it leaves behind. A change that works today but
+puts a seam in the wrong place, or leaks a detail across one, costs every change after it.
+
+## What to look for
+
+- **Misplaced seams** — logic that belongs behind an interface written in the caller; a
+  boundary that exposes its internals; a module that now knows a neighbour's private shape.
+- **Coupling the change adds** — a new import that points the wrong way (a domain reaching
+  into the UI, a core reaching into a plugin); a circular dependency; a change here that
+  forces an unrelated change there.
+- **Shallow modules** — a wrapper that adds a layer without hiding complexity; an interface
+  as wide as its implementation; a "manager"/"util"/"helper" that names a grab-bag, not a
+  responsibility.
+- **Leaked abstraction** — callers that must know the order to call things in, pass a flag
+  that toggles two behaviours, or handle an error type from three layers down.
+- **Duplicated decision** — the same rule, constant, or shape now expressed in two places
+  that will drift; a copy where a call belonged.
+- **Change amplification** — a single conceptual change the diff had to make in many files:
+  a sign the knowledge is not held in one place.
+
+## How to report
+
+Report only findings anchored to a **changed line** in this change set — the structure this
+change introduced or worsened, not the whole codebase's debt. For each finding give:
+
+- `path:line` — the changed line it anchors to
+- **severity** — major (a seam that will be expensive to move later) · minor · nit
+- **what** — the structural problem in one line
+- **why** — the future change it makes harder, concretely
+- **fix** — where the seam or knowledge should sit instead
+- **route** — `criterion` · `check` (e.g. "nothing under `domain/` may import from `ui/`") ·
+  `lens` · `none`
+
+Judge the change, not the pre-existing design around it — unless the change deepens an
+existing problem, in which case say which. Prefer the smallest move that puts the seam right.
+An empty report is a valid result.

package/lenses/correctness.md

@@ -0,0 +1,36 @@
+# correctness lens
+
+**Stance:** assume the change is subtly wrong and go looking for the input that proves it.
+Read the diff as an adversary would — the value the author did not picture.
+
+## What to look for
+
+- **Boundaries** — off-by-one, empty collection, single element, the maximum, zero,
+  negative, the exact threshold a comparison turns on. `<` where `<=` was meant.
+- **Absent values** — null / undefined / None threaded into code that assumes presence; a
+  default that silently swallows a real value; an optional unwrapped without a branch.
+- **Error paths** — a thrown error caught and dropped; a rejected promise nobody awaits; a
+  failure that leaves state half-written; a `catch` that hides the cause.
+- **Async** — an unawaited promise, a race between two writers, a shared mutable read
+  mid-update, iteration that mutates what it iterates.
+- **Logic the change moved** — an inverted condition, a De Morgan slip, a `&&` that should
+  be `||`, a guard that no longer guards because the code around it moved.
+- **Contract drift** — a caller and callee that now disagree about units, order, nullability,
+  or what an empty result means; a return type widened without every caller noticing.
+
+## How to report
+
+Report only findings anchored to a **changed line** — not a pre-existing bug the change did
+not touch. For each finding give:
+
+- `path:line` — the changed line it anchors to
+- **severity** — blocker · major · minor · nit
+- **what** — the defect in one line
+- **why** — the concrete input or interleaving that triggers it, and what goes wrong
+- **fix** — the change that closes it
+- **route** — the artefact that stops the class recurring: `criterion` (the behaviour a
+  test should have claimed) · `check` (a cross-file invariant) · `lens` · `none`
+
+State the triggering case concretely — "a basket with exactly one line item", not "edge
+cases". A finding you cannot reduce to an input is a hunch; hold it or say so. An empty
+report is a valid and common result.

package/lenses/house-conventions.md

@@ -0,0 +1,37 @@
+<!-- speccle:lens-template — this lens is unauthored. Replace the body with your repo's own
+     conventions and delete this comment. Until you do, `review` runs it as inert and it
+     reports nothing. A refresh (`speccle update`) never overwrites this file. -->
+
+# house-conventions lens
+
+**Stance:** _this is your lens to write._ The shipped lenses cover what is true of good code
+everywhere; this one covers what is true of code **in this repo** — the taste, the patterns,
+and the mistakes only your team keeps making. It is the most valuable lens you have, and
+Speccle cannot write it for you.
+
+## What to look for
+
+_Replace the prompts below with your own. Good sources: your CONTRIBUTING guide, past review
+comments you have made more than once, the ADRs your code must honour, the bug that shipped
+last quarter._
+
+- The naming, layering, or error-handling pattern this codebase follows that a newcomer
+  would break.
+- The library or idiom you have standardized on — and the one you have banned.
+- The invariant that is not a lint rule yet but should never be violated.
+- The class of mistake that has bitten this team before and will again.
+
+## How to report
+
+Report only findings anchored to a **changed line** in this change set. For each finding
+give:
+
+- `path:line` — the changed line it anchors to
+- **severity** — major · minor · nit
+- **what** — the convention broken, in one line
+- **why** — the house rule, and why it holds here
+- **fix** — the change that follows the convention
+- **route** — `criterion` · `check` (many house conventions become an `oracle verify` check
+  once they are stable) · `lens` (sharpen this file) · `none`
+
+> While this file still reads as the shipped template, report nothing.

package/lenses/performance.md

@@ -0,0 +1,40 @@
+# performance lens
+
+**Stance:** find the cost the change adds that grows with the data. A slowdown that only
+shows at production scale will not show in the diff — picture the input ten thousand times
+larger.
+
+## What to look for
+
+- **N+1 and hidden loops** — a query, fetch, or read inside a loop that a batch or join
+  would collapse; an `await` in a loop that serializes independent work; a nested scan that
+  turns linear into quadratic.
+- **Work that grows** — an algorithm a size class worse than it needs (a linear scan for a
+  set membership, a sort where a heap suffices); a data structure that forces it (an array
+  where a map's keys were the point).
+- **Repeated work** — a pure computation redone every render or every call that memoization
+  or hoisting removes; a value recomputed inside a loop that is constant across it.
+- **Unbounded growth** — a cache, list, or map with no eviction; a subscription or listener
+  added without a matching teardown; a closure that retains a large object.
+- **Payload & I/O** — over-fetching columns or rows the caller drops; a whole file read to
+  use one line; a round-trip per item where one call would do; a missing index behind a hot
+  query.
+- **Frontend cost** — a re-render triggered by a new object identity each pass; a large
+  synchronous computation on the main thread; a bundle-heavy import for a small need.
+
+## How to report
+
+Report only findings anchored to a **changed line** in this change set. For each finding
+give:
+
+- `path:line` — the changed line it anchors to
+- **severity** — major (cost grows with production-scale input) · minor (fixed overhead) ·
+  nit
+- **what** — the cost in one line
+- **why** — how it scales: "one query per line item, so a 500-item order is 500 round-trips"
+- **fix** — the batch, index, memo, structure, or bound that flattens it
+- **route** — `criterion` (a performance budget worth asserting) · `check` · `lens` · `none`
+
+Reach for scaling arguments, not micro-optimizations — a quadratic loop matters, a saved
+allocation rarely does. Do not trade clarity for speed on a cold path; say when a cost is
+fine. An empty report is a valid result.

package/lenses/risk.md

@@ -0,0 +1,45 @@
+# risk lens
+
+**Stance:** the deterministic risk score is a floor, not a ceiling. Your one job is to catch
+the consequential change the signals could not see — and, when you find it, to **raise**
+supervision. You may escalate. You may never lower.
+
+This lens does not produce findings. It produces one escalation decision over the whole
+change set, and it runs before the panel, because it decides whether `review` may fix at all.
+
+## What to look for — subtlety no deterministic signal catches
+
+- **Blast radius** — a small diff on a hot path: an auth check, a payment or money
+  calculation, a permissions boundary, a data-deletion or migration, a public API contract
+  many callers depend on.
+- **Irreversibility** — a change that is hard or impossible to undo once it ships: a
+  destructive migration, a data backfill, a webhook or email that fires, a format written to
+  storage that must be read back forever.
+- **Silent semantic shift** — behaviour that changed while its shape did not: a default
+  flipped, a rounding or timezone rule altered, an ordering guarantee dropped, a currency or
+  unit reinterpreted.
+- **Concurrency & state** — a new shared write, a lock removed, an assumption of
+  single-threaded execution the change quietly breaks.
+- **Security surface** — a boundary newly reachable, a trust assumption relaxed, a secret's
+  handling changed — even where no single line is itself the bug.
+
+## How to report
+
+Emit one decision:
+
+- **escalate** — `true` or `false`
+- **requireHuman** — `true` forces human review regardless of the floor; `false` leaves the
+  deterministic verdict standing
+- **raiseFloorBy** — a non-negative number added to the score, or `0`. Never negative.
+- **reasons** — for every escalation, the specific change and the consequence that justifies
+  it, anchored to `path:line`. An escalation with no legible reason is not auditable and does
+  not count.
+
+Rules that bind you:
+
+- You may only **add** supervision. If you believe the floor is too high, say so in reasons
+  for a human to weigh — do not lower it. Lowering supervision is never automatic.
+- Silence is not safety. If nothing here is consequential, return `escalate: false` plainly;
+  do not invent risk to look thorough.
+- When in doubt on a genuinely consequential change, escalate. A needless human review costs
+  minutes; an unsupervised bad change on a hot path costs more.