specpi 0.26.0 → 0.28.0

package/extensions/jev-advisor/config.mjs

@@ -0,0 +1,270 @@
+// Jev is the first thing in SpecPi that talks to a third party, so its switch is the first thing
+// every other module in this directory consults. Master off means no key value read, no consent
+// read, no network call and no prompt injection: the harness behaves exactly as it did before the
+// extension existed. `/jev status` still reports whether a key exists while the layer is off, by
+// name and never by value, because "how do I configure this" is a question asked before enabling
+// anything -- see key-source.mjs.
+//
+// The file is SpecPi's own, hardened the same way as web-access and capability-policy: atomic
+// write, mode 0600, symlinks refused, and a missing or unreadable file read as off.
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+/** Systems that may run inside a session. Offline scripts are not gated here. */
+export const SYSTEM_NAMES = Object.freeze([
+    "retention",
+    "compaction",
+    "gap",
+    "sources",
+    "progress",
+    "untrusted",
+    "capability",
+    // The command guard, native since schema 3. It used to be a separate pinned package with its own
+    // global configuration file, which is why it used to carry its own switch here: a second switch,
+    // outside the master, with its own startup preference and its own persistence rules. Those rules
+    // disagreed with the layer's often enough to be their own source of defects -- a preference
+    // erased by a command that had decided nothing about the guard, a state written by one command
+    // and reverted by the next session. As a system it is gated, budgeted, reported and toggled by
+    // exactly the same code as the other seven.
+    "guard",
+]);
+
+/**
+ * What a confident stuck verdict is allowed to do. `notify` tells the person and cannot be wrong in
+ * a way that costs anything; `message` appends a fixed line the model reads before its next
+ * request, which changes behaviour.
+ *
+ * It ships on `notify`. Not because the gate cannot tell the cases apart -- it demonstrably can: on
+ * the recorded fixtures a session repeating one failing call scores 0.89 for stuck with the mode at
+ * 0.99 confidence, and a session working steadily scores 0.30 and reports "unknown" below the gate.
+ * The missing number is the false-positive rate on real sessions, and the two things that bear on it
+ * point the other way: running the same taxonomy over the 24 recorded failures left 14 of them
+ * ungated, and a wrong nudge costs a turn, which is the exact quantity this system exists to save.
+ *
+ * So the condition for changing this default is a measurement, not an opinion, and the eval suite
+ * is where it comes from: `--harness=specpi-jev` sets `message` and discloses it, because a
+ * notification in a headless run reaches nobody and would measure the cost of the system with none
+ * of its effect.
+ */
+export const NUDGE_MODES = Object.freeze(["notify", "message"]);
+
+const MAX_SETTINGS_BYTES = 4096;
+const MAX_CALL_BUDGET = 256;
+const MAX_TOTAL_BUDGET = 512;
+
+/**
+ * One shared budget could not survive a turn-level system. A system that fires once per turn would
+ * reach a shared ceiling of 8 inside the first few turns and starve retention for the rest of the
+ * session, and which one won would be decided by event ordering rather than by anyone's policy.
+ *
+ * So the ceiling is two-level: each system gets its own, and the total is a real constraint because
+ * it is deliberately less than their sum. Running out of one system's budget stops that system and
+ * nothing else.
+ *
+ * The per-system numbers follow how often each one can fire: retention on every large read-only
+ * result, compaction once or twice in a long session, gap per report, sources per delegation batch.
+ */
+export const DEFAULT_BUDGETS = Object.freeze({
+    // A backstop, not a working limit, and the number says which. Measured, a full tier-3 task -- a
+    // 120-step repair chain over about 25 model requests -- spends 4 to 7 calls, and the busiest
+    // attempt ever recorded spent 12. A session would have to run for days before 512 bound
+    // anything a person was actually doing, which is the point: the ceiling should only ever be hit
+    // by a loop, and hitting it should therefore be information rather than an inconvenience.
+    //
+    // The earlier 120 was sized against eval attempts, which is the wrong reference. An attempt
+    // runs for two minutes; an interactive session runs for a day, and a turn-level system at one
+    // call every four turns reaches 120 somewhere in the afternoon and then goes quiet without
+    // having found anything wrong. A ceiling that a normal long session reaches is not protecting
+    // anyone, it is just failing later than it looks.
+    //
+    // Cost is not what these are for. A call is about $0.00003, so the whole total is about a cent
+    // and a half. They bound two things that do not get cheaper with scale: how much digest leaves
+    // the machine for a third party, at up to 1 KB a call, and how much awaited latency a runaway
+    // loop can add before something stops it. Half a megabyte of digest and an announced stop is
+    // the shape of the trade.
+    total: 512,
+    retention: 208,
+    compaction: 12,
+    gap: 48,
+    sources: 32,
+    // Turn-level, but gated behind local signals and a four-turn cooldown, so it only spends on
+    // sessions that already look wrong. The ceiling is what stops a genuinely thrashing session
+    // from spending the total on being told it is thrashing.
+    progress: 176,
+    // Usually free: when retention is on, system 7's question rides the call retention was already
+    // making against the same state. This ceiling only binds when retention is off, or when the
+    // fetched result is too small for retention to be interested in it.
+    untrusted: 104,
+    // Once per session by construction, and only when local signals already suggest it. Two rather
+    // than one so a retried first turn is not silently un-served.
+    capability: 2,
+    // Per gated tool call that local rules could not settle, so its frequency is retention's rather
+    // than compaction's -- and like retention, most calls never reach it: read-only commands and
+    // ordinary project writes are answered locally for nothing. Running out means the guard defers
+    // to the permission system for the rest of the session, which is what it does for every other
+    // kind of unavailability.
+    guard: 208,
+});
+
+/** 0 is a real budget meaning no calls. Switching a system off is what `systems[name] = false` is for. */
+export const MAX_BUDGETS = Object.freeze({ system: MAX_CALL_BUDGET, total: MAX_TOTAL_BUDGET });
+
+export function agentDirectory() {
+    const configured = process.env.PI_CODING_AGENT_DIR;
+
+    return path.resolve(configured && configured.length > 0 ? configured : path.join(os.homedir(), ".pi", "agent"));
+}
+
+export function jevDirectory() {
+    return path.join(agentDirectory(), "specpi", "jev");
+}
+
+function settingsFile() {
+    return path.join(jevDirectory(), "settings.json");
+}
+
+/** Refuses links and irregular files so the preference cannot redirect a write. */
+export function regularFile(file, label) {
+    const stat = fs.lstatSync(file, { throwIfNoEntry: false });
+    if (!stat) {
+        return false;
+    }
+
+    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > MAX_SETTINGS_BYTES) {
+        throw new Error(`Unsupported ${label} file`);
+    }
+
+    return true;
+}
+
+/** Every unknown shape collapses to the same all-off default rather than a partial enable. */
+export function defaultSettings() {
+    return {
+        schema: 3,
+        master: false,
+        startup: false,
+        systems: Object.fromEntries(SYSTEM_NAMES.map((name) => [name, false])),
+        budgets: { ...DEFAULT_BUDGETS },
+        progressNudge: "notify",
+    };
+}
+
+function clamp(value, fallback, ceiling) {
+    return Number.isInteger(value) ? Math.min(Math.max(value, 0), ceiling) : fallback;
+}
+
+function normalizeBudgets(raw) {
+    const budgets = { total: clamp(raw?.total, DEFAULT_BUDGETS.total, MAX_TOTAL_BUDGET) };
+    for (const name of SYSTEM_NAMES) {
+        budgets[name] = clamp(raw?.[name], DEFAULT_BUDGETS[name] ?? 0, MAX_CALL_BUDGET);
+    }
+
+    return budgets;
+}
+
+/**
+ * Schema 1 carried one `callBudgetPerSession`. Reading it as an unknown shape would switch the
+ * layer off for anyone who had turned it on, which is a reset the user never asked for -- "unknown
+ * shapes collapse to all-off" is a rule for corrupt input, not for our own previous version. The
+ * one number becomes the total, and each system gets the smaller of its default and that total, so
+ * a user who set a deliberately tight ceiling keeps it.
+ */
+function migrate(raw) {
+    // Schema 1 read 0 as "no ceiling"; schema 2 reads it as "no calls", because a per-system 0 that
+    // silently meant unlimited is the wrong way for a budget to fail. Carrying the old meaning
+    // forward here is what stops the bump from inverting a user's intent.
+    const stored = raw?.callBudgetPerSession === 0 ? MAX_TOTAL_BUDGET : raw?.callBudgetPerSession;
+    const total = clamp(stored, DEFAULT_BUDGETS.total, MAX_TOTAL_BUDGET);
+    const budgets = { total };
+    for (const name of SYSTEM_NAMES) {
+        budgets[name] = Math.min(DEFAULT_BUDGETS[name] ?? 0, total);
+    }
+
+    return { ...raw, schema: 2, budgets, callBudgetPerSession: undefined };
+}
+
+/**
+ * Schema 2 carried the command guard as a separate `guard: { enabled, startup }` pair, because it
+ * was a separate package with its own global configuration file. Schema 3 makes it the eighth
+ * system, so the stored preference becomes `systems.guard`.
+ *
+ * `guard.startup` is what migrates, not `guard.enabled`: the former is what the user chose for new
+ * sessions, and the latter was a session flag that happened to be written to disk. A file where the
+ * guard was wanted at startup but the layer itself was not produces a system that is on inside a
+ * layer that is off, which is inactive -- the guard used to sit outside the master switch and now
+ * does not. That direction is deliberate: a gate quietly becoming inactive is recoverable in one
+ * command, and a gate quietly becoming active is how a session stops being able to run anything.
+ */
+function migrateToThree(raw) {
+    const systems = { ...(raw?.systems ?? {}), guard: raw?.guard?.startup === true };
+
+    const { guard: _guard, ...rest } = raw ?? {};
+
+    return { ...rest, schema: 3, systems };
+}
+
+function normalize(raw) {
+    const one = raw?.schema === 1 ? migrate(raw) : raw;
+    const source = one?.schema === 2 ? migrateToThree(one) : one;
+    if (source?.schema !== 3) {
+        return defaultSettings();
+    }
+
+    const systems = Object.fromEntries(SYSTEM_NAMES.map((name) => [name, source.systems?.[name] === true]));
+
+    return {
+        schema: 3,
+        master: source.master === true,
+        startup: source.startup === true,
+        systems,
+        budgets: normalizeBudgets(source.budgets),
+        progressNudge: NUDGE_MODES.includes(source.progressNudge) ? source.progressNudge : "notify",
+    };
+}
+
+export function loadSettings() {
+    try {
+        const file = settingsFile();
+        if (!regularFile(file, "Jev settings")) {
+            return defaultSettings();
+        }
+
+        return normalize(JSON.parse(fs.readFileSync(file, "utf8")));
+    } catch {
+        return defaultSettings();
+    }
+}
+
+/** Shared atomic write for every file this extension owns. */
+export function writeFileAtomic(file, contents) {
+    const directory = path.dirname(file);
+    fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const temporary = path.join(directory, `.${path.basename(file)}.${randomUUID()}.tmp`);
+    try {
+        fs.writeFileSync(temporary, contents, { mode: 0o600, flag: "wx" });
+        fs.renameSync(temporary, file);
+    } finally {
+        fs.rmSync(temporary, { force: true });
+    }
+}
+
+export function saveSettings(settings) {
+    // A caller handing back a schema-1 shape is migrated rather than reset, so a round trip through
+    // an old reader cannot quietly disable the layer.
+    const next = normalize(settings?.schema === 1 || settings?.schema === 2 ? settings : { ...settings, schema: 3 });
+    const file = settingsFile();
+    if (fs.existsSync(file)) {
+        regularFile(file, "Jev settings");
+    }
+
+    writeFileAtomic(file, `${JSON.stringify(next, null, 4)}\n`);
+
+    return next;
+}
+
+export function settingsPath() {
+    return settingsFile();
+}

package/extensions/jev-advisor/consent.mjs

@@ -0,0 +1,133 @@
+// A config flag records an intention. It does not record that a human was told what the intention
+// costs. This file holds the separate, explicit grant: the first time any system would put session
+// state on the wire, a dialog names the endpoint, the shape of the data and the byte budget, and
+// nothing is sent until someone says yes.
+//
+// Mirrors capability-policy: SpecPi's own file, atomic, mode 0600, symlinks refused, missing or
+// unreadable read as "ask". No interactive UI means no send, ever.
+
+import fs from "node:fs";
+import path from "node:path";
+import { jevDirectory, regularFile, writeFileAtomic } from "./config.mjs";
+import { baseUrl } from "./client.mjs";
+import { MAX_STATE_BYTES } from "./sanitize.mjs";
+
+/**
+ * The host the bytes will actually reach, not the service they are nominally for. This was a fixed
+ * "api.typesafe.ai" until the default backend became OpenRouter, at which point the dialog named a
+ * host the data no longer went to, which is the one thing a consent dialog may never do. It is
+ * derived now, so each of the three selectable destinations (OpenRouter, the direct TypeSafe API,
+ * and a TYPESAFE_BASE_URL override) names itself, and so the rule below is true rather than
+ * aspirational: a grant is keyed on this string, so repointing the client really does ask again.
+ */
+export function endpointLabel() {
+    const base = baseUrl();
+    try {
+        return new URL(base).host;
+    } catch {
+        // Unparseable means the fetch will fail anyway. Returning the raw value keeps the dialog
+        // honest and cannot collide with a host a real grant was given for.
+        return base;
+    }
+}
+
+function consentFile() {
+    return path.join(jevDirectory(), "consent.json");
+}
+
+export function loadConsent() {
+    try {
+        const file = consentFile();
+        if (!regularFile(file, "Jev consent")) {
+            return undefined;
+        }
+
+        const stored = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (stored?.schema !== 1 || stored.granted !== true || typeof stored.endpoint !== "string") {
+            return undefined;
+        }
+
+        // A grant is for the endpoint it was given for. Repointing the client asks again.
+        return stored.endpoint === endpointLabel() ? stored : undefined;
+    } catch {
+        return undefined;
+    }
+}
+
+export function granted() {
+    return loadConsent() !== undefined;
+}
+
+export function saveConsent() {
+    const file = consentFile();
+    if (fs.existsSync(file)) {
+        regularFile(file, "Jev consent");
+    }
+
+    const stored = {
+        schema: 1,
+        granted: true,
+        endpoint: endpointLabel(),
+        maxStateBytes: MAX_STATE_BYTES,
+        grantedAt: new Date().toISOString(),
+    };
+    writeFileAtomic(file, `${JSON.stringify(stored, null, 4)}\n`);
+
+    return stored;
+}
+
+export function revokeConsent() {
+    try {
+        fs.rmSync(consentFile(), { force: true });
+    } catch {
+        // A consent file that cannot be removed still reads as granted; the master switch is the
+        // reliable stop, and /jev status reports both.
+    }
+}
+
+export function consentPath() {
+    return consentFile();
+}
+
+export const CONSENT_TITLE = "Allow SpecPi to send task summaries to Jev?";
+
+export function consentBody(systemLabel) {
+    return [
+        `${systemLabel} wants to ask TypeSafe's Jev classifier a question about this session.`,
+        "",
+        `What is sent: a summary object of at most ${MAX_STATE_BYTES} bytes to ${endpointLabel()}, over HTTPS.`,
+        "It carries tool names, byte counts, relative paths and short descriptions.",
+        "It never carries file contents, command output, credentials, URLs or session history.",
+        "",
+        "Every call is recorded locally in transmissions.jsonl with a hash of exactly what was sent,",
+        "which you can read with /jev ledger. Turn this off at any time with /jev off.",
+    ].join("\n");
+}
+
+/**
+ * Resolve consent for a system, prompting once. Returns false without prompting when there is no
+ * interactive human: an advisor must never be the reason a headless run sends data.
+ */
+export async function ensureConsent(ctx, systemLabel) {
+    if (granted()) {
+        return true;
+    }
+
+    if (!ctx?.hasUI || typeof ctx.ui?.confirm !== "function") {
+        return false;
+    }
+
+    const accepted = await ctx.ui.confirm(CONSENT_TITLE, consentBody(systemLabel));
+    if (!accepted) {
+        return false;
+    }
+
+    try {
+        saveConsent();
+    } catch {
+        // An unwritable grant means asking again next time, which is the safe direction.
+        return true;
+    }
+
+    return true;
+}

package/extensions/jev-advisor/gate.mjs

@@ -0,0 +1,263 @@
+// A probability is not a decision. This file is the only place that turns one into the other, so
+// every system gates the same way and a threshold change is a one-line diff with one test to move.
+//
+// The three primitives do not gate alike. A Noul returns a bare probability with no confidence
+// field, so a confidence test cannot be applied to it. A Choice can be confident and still be a
+// coin flip between its top two options, so the margin matters as much as the confidence. A Score
+// is only actionable when it sits clear of a level boundary rather than straddling one.
+//
+// MEASURED, not guessed. Every number here is now read off `evals/runs/jev-calibration.json`, which
+// `node scripts/jev-calibrate.mjs` writes from 259 recorded eval attempts plus a fixed reachability
+// pass of six synthetic cases run five times each. `tests/jev-calibration.test.mjs` pins each number
+// to that file, so moving one takes new evidence rather than a new opinion.
+//
+// Two questions were asked of the evidence, because a threshold can fail in two different ways.
+//
+// 1. DOES THE CONFIDENCE FIELD SEPARATE RIGHT FROM WRONG? Measured against labels this repository
+//    already owns: predicting an attempt's pass (Noul), its task category (Choice) and its tier
+//    (Score) from behavioural metadata alone, with the labels withheld from the state.
+//
+//    Score:  yes, weakly. At scoreConfidence 0.60 and boundary 0.30 the answer is exactly right
+//            about two thirds of the time and within one level about 96%, on roughly a fifth of
+//            answers, against a 43.2% majority class. The exact figures are in CALIBRATION below,
+//            which a test compares against the artifact; they moved from 68.4% to 64.7% between two
+//            runs over the same 259 attempts, so any single decimal here is a sample, not a
+//            constant, and the honest summary is "a lift of about 1.5".
+//    Noul:   no. Precision tracks the 90.7% base rate at every threshold (lift 1.01-1.02), and no
+//            answer to that question ever exceeded 0.80.
+//    Choice: no. About 30% accuracy against a 29.7% majority class, and accuracy falls as
+//            confidence rises. The margin changes nothing, because the top-two gap is almost always
+//            wide.
+//
+//    None of the systems' pre-registered precision targets (0.75 to 0.95) is met anywhere on any of
+//    those curves, and the artifact records UNMET rather than a number chosen to fill the gap. The
+//    Score point below is the best available operating point, not a met target. That is a real
+//    limit on what this layer can claim, and it is published rather than smoothed over.
+//
+//    It is also a fair reading that the proxy questions are much harder than the production ones:
+//    the eval state is a row of counters, while a production state carries the material being
+//    judged. Question 2 is what tests that, and the answer is yes.
+//
+// 2. CAN THE GATE EVER FIRE? This is the one that found a shipped defect. Against the fixture cases
+//    the real question sets separate cleanly -- a planted secret scores 0.96 and a clean report
+//    0.04; a page carrying an injected instruction scores 0.97 and an ordinary one 0.04; the one
+//    relevant file among noise scores 1.99 while the other two score 0.01 -- but the Score gate
+//    shipped at confidence 0.80 with boundary 0.35, and on a maximally obvious "spent" result (a
+//    listing of vendor icons during a changelog edit) Jev answered 0.10-0.18 with confidence
+//    0.73-0.85 across ten runs, most of them under 0.80. Boundary 0.35 demands the value sit within
+//    0.15 of a level, which 0.16 and 0.17 miss. So retention could gate through to "keep this
+//    result" and essentially never to "this result is spent": the only branch that does anything
+//    was unreachable, and running the layer could never have revealed it, because a system that
+//    never fires looks exactly like a system whose advice was always to do nothing.
+//
+//    compaction's `unresolved_thread` had the same problem at high 0.85: the clearest open
+//    investigation the fixture can express scores 0.63-0.65. It is lowered to 0.60, which is
+//    defensible only because of what that branch does -- add one sentence to a summariser prompt
+//    that is being rebuilt from scratch anyway. It is the cheapest action in the layer, so it can
+//    afford the loosest gate. gap keeps 0.85 because its Noul reaches 0.96 on the case that matters
+//    and because a firing there blocks a write.
+
+/**
+ * The figures the comment above cites, in a form a test can check against the artifact. A citation
+ * that drifts from its source is worse than no citation, because it reads like evidence. If these
+ * stop matching `evals/runs/jev-calibration.json`, `tests/jev-calibration.test.mjs` fails and
+ * whoever re-ran the calibration has to update the prose too.
+ */
+export const CALIBRATION = Object.freeze({
+    artifact: "evals/runs/jev-calibration.json",
+    attempts: 259,
+    passBaseRate: 0.907,
+    tierBaseRate: 0.432,
+    categoryBaseRate: 0.297,
+    // At the shipped scoreConfidence 0.60 / boundary 0.30. Tolerance is deliberate: see above.
+    scoreExact: 0.647,
+    scoreWithinOne: 0.961,
+    scoreCoverage: 0.197,
+    tolerance: 0.05,
+});
+
+export const THRESHOLDS = Object.freeze({
+    // One Score operating point, applied to every system, because one proxy question produced one
+    // curve. Four different per-system numbers would be four claims from a single measurement. The
+    // per-system asymmetry lives where it belongs instead: retention needs two independent answers
+    // to agree before it shortens anything, and sources only ever reorders.
+    retention: Object.freeze({
+        scoreConfidence: 0.6,
+        boundary: 0.3,
+        choiceConfidence: 0.75,
+        margin: 0.3,
+        // Unused by retention, which reads only the low side; kept so every system has a full set.
+        high: 0.9,
+        // Measured 0.06-0.07 on the spent case, so this clears with room.
+        low: 0.1,
+    }),
+    compaction: Object.freeze({
+        scoreConfidence: 0.6,
+        boundary: 0.3,
+        choiceConfidence: 0.75,
+        margin: 0.25,
+        // Lowered from 0.85: the clearest open investigation scores 0.63-0.65, and the action is
+        // one sentence added to a prompt that is being rebuilt regardless.
+        high: 0.6,
+        low: 0.15,
+    }),
+    gap: Object.freeze({
+        scoreConfidence: 0.6,
+        boundary: 0.3,
+        choiceConfidence: 0.75,
+        margin: 0.2,
+        // Measured 0.96 on a report carrying a machine-specific path and 0.04 on a clean one.
+        high: 0.85,
+        low: 0.15,
+    }),
+    progress: Object.freeze({
+        scoreConfidence: 0.6,
+        boundary: 0.3,
+        // The strictest Choice gate in the layer, because it is the only system whose action can
+        // change what the model does next. Running the same taxonomy over the 24 recorded failures
+        // left 14 of them below this bar, which is the intended behaviour: silence is the correct
+        // answer to a session whose trouble is not yet legible.
+        choiceConfidence: 0.8,
+        margin: 0.25,
+        high: 0.85,
+        low: 0.15,
+    }),
+    capability: Object.freeze({
+        scoreConfidence: 0.6,
+        boundary: 0.3,
+        choiceConfidence: 0.75,
+        margin: 0.2,
+        // Asymmetric on purpose. A false positive costs the group's schema on every request for
+        // the rest of the session -- a turn-1 arming measured 16% more than never arming -- plus a
+        // confirmation the human did not need. A false negative costs nothing: it leaves today's
+        // behaviour exactly as it is, and `request_capability` is still there for the moment the
+        // need becomes real.
+        //
+        // This shipped at 0.90 for exactly as long as it took to measure it, which is the same
+        // defect described above, in code written the same day, caught by the same check. On a
+        // request that unambiguously needs a browser -- open the pricing page at 375px and fix what
+        // overflows -- `needs_browser` answers 0.86-0.87, five times out of five, while the same
+        // question on a rename answers 0.09-0.10. 0.90 sits inside the yes cluster and rejects all
+        // of it; 0.85 sits below it with a margin of 0.76 to the nearest no. No Noul anywhere in
+        // the fixture set has ever exceeded 0.97, so "higher is safer" stops being true well before
+        // it stops being tempting.
+        high: 0.85,
+        low: 0.1,
+    }),
+    untrusted: Object.freeze({
+        scoreConfidence: 0.6,
+        boundary: 0.3,
+        choiceConfidence: 0.75,
+        margin: 0.2,
+        // A banner is cheap and a missed injection is not, so this is the one place where the
+        // asymmetry runs the other way from gap's. It is still 0.85 rather than lower, because a
+        // banner on ordinary prose is exactly the false positive that teaches a model to stop
+        // reading the channel -- the objection this system had to answer before it could exist.
+        high: 0.85,
+        low: 0.15,
+    }),
+    guard: Object.freeze({
+        // The same measured Score operating point as every other system, written out rather than
+        // inherited by falling through `thresholdsFor`'s default. The guard asked under the name
+        // "gap" for exactly as long as it took to notice that adding a `guard` entry would then have
+        // changed nothing -- a silent no-op on the one system whose action takes a tool call away.
+        scoreConfidence: 0.6,
+        boundary: 0.3,
+        choiceConfidence: 0.75,
+        margin: 0.2,
+        // Unused: this system reads only the Score side. Kept so every system has a full set, and
+        // so the calibration tests cover this entry like any other.
+        high: 0.85,
+        low: 0.15,
+    }),
+    sources: Object.freeze({
+        scoreConfidence: 0.6,
+        boundary: 0.3,
+        choiceConfidence: 0.7,
+        margin: 0.15,
+        // Not reached by any fixture case: `worth_delegating` scored 0.20-0.21 on a question that
+        // reads as self-contained to a human. Left at 0.85 rather than tuned down, because the only
+        // thing that reads it warns and never blocks, and a threshold moved to make a fixture pass
+        // is a threshold set by the fixture.
+        high: 0.85,
+        low: 0.15,
+    }),
+});
+
+export function thresholdsFor(system) {
+    return THRESHOLDS[system] ?? THRESHOLDS.gap;
+}
+
+/** True when the Noul is confidently yes. */
+export function nounTrue(answer, system) {
+    const limits = thresholdsFor(system);
+
+    return answer?.kind === "noul" && answer.value >= limits.high;
+}
+
+/** True when the Noul is confidently no. Not the negation of nounTrue: the middle band is silence. */
+export function nounFalse(answer, system) {
+    const limits = thresholdsFor(system);
+
+    return answer?.kind === "noul" && answer.value <= limits.low;
+}
+
+function topTwo(probabilities) {
+    const values = Object.values(probabilities ?? {})
+        .filter((value) => typeof value === "number")
+        .sort((a, b) => b - a);
+
+    return { first: values[0] ?? 0, second: values[1] ?? 0 };
+}
+
+/**
+ * A Choice is actionable when it is both confident and clearly separated from its runner-up.
+ * Without a distribution the margin cannot be checked, so the answer is treated as ungated.
+ *
+ * The reachability pass confirms all 40 Choice answers from this backend carried a distribution, so
+ * the margin is a live test rather than a branch that silently never runs.
+ */
+export function choiceValue(answer, system) {
+    if (answer?.kind !== "choice" || typeof answer.confidence !== "number") {
+        return undefined;
+    }
+
+    const limits = thresholdsFor(system);
+    if (answer.confidence < limits.choiceConfidence) {
+        return undefined;
+    }
+
+    const { first, second } = topTwo(answer.probabilities);
+    if (answer.probabilities && first - second < limits.margin) {
+        return undefined;
+    }
+
+    return answer.value;
+}
+
+/**
+ * A Score is actionable when it is confident and sits clear of the nearest level boundary. The
+ * returned level is the rounded band; callers compare against their own rubric.
+ */
+export function scoreLevel(answer, system) {
+    if (answer?.kind !== "score" || typeof answer.confidence !== "number") {
+        return undefined;
+    }
+
+    const limits = thresholdsFor(system);
+    if (answer.confidence < limits.scoreConfidence) {
+        return undefined;
+    }
+
+    const level = Math.round(answer.value);
+    if (Math.abs(answer.value - level) > 0.5 - limits.boundary) {
+        return undefined;
+    }
+
+    return level;
+}
+
+/** Raw probability for logging and calibration, with no gate applied. */
+export function rawValue(answer) {
+    return answer?.value;
+}