@event4u/agent-config 9.25.0 → 9.26.0

package/src/scripts/schemas/review-findings.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "review-findings.schema.json",
+  "title": "Review findings",
+  "description": "ONE findings shape for both review tracks. All six external reviewers of 9.18.1 converged on a single ask: the R2 gate hand-parses Markdown and carries `unbalanced-fence` and `malformed-row` as first-class violation kinds — i.e. it has defect classes FOR ITS OWN PARSER. This schema is deliberately NOT a new format: it is the shape `self_review_gate.ts` already emits under `--findings-out` and `check_finding_dispositions.ts` already hand-validates in code, lifted into a file both tracks can point at. Inventing a second JSON shape here would have been the exact fragmentation the reviewers complained about.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "findings"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "schema_version": {
+      "enum": [
+        1
+      ],
+      "description": "Pinned. `check_finding_dispositions.parse_ledger` already rejects anything else, so this is a promotion of an existing check rather than a new constraint. Spelled as a one-member `enum` rather than `const`: the repo's own Draft-07 subset validator (validate_frontmatter.ts) enforces `enum` and silently ignores `const`, so `const` here would have been a pin nothing checked."
+    },
+    "release": {
+      "type": "string",
+      "description": "Version the ledger belongs to. Present on the release-findings ledger (agents/evidence/release-findings/<version>.json); absent on a bare --findings-out emission, which is why it is not required here."
+    },
+    "findings": {
+      "type": "array",
+      "description": "May be empty. An empty array is an honest null, not a missing field — the distinction the Markdown track spells with its own §2.3 line. The item shape is INLINED rather than `$ref`-ed for the same measured reason: the subset validator does not resolve `$ref`, so a referenced definition would have validated nothing.",
+      "items": {
+        "type": "object",
+        "required": [
+          "severity",
+          "kind",
+          "title"
+        ],
+        "additionalProperties": true,
+        "properties": {
+          "finding_id": {
+            "type": "string",
+            "pattern": "^[0-9a-f]{12}$",
+            "description": "First 12 hex of sha256(`kind|title|file`), per findingId() in self_review_gate.ts. Stable across runs, which is what lets the disposition ledger key on it. NOT required: an in-flight finding may not have been keyed yet, and requiring it would make the schema reject the shape the model returns before the gate stamps it."
+          },
+          "severity": {
+            "enum": [
+              "critical",
+              "high",
+              "medium",
+              "low"
+            ],
+            "description": "The JSON track's four levels. The Markdown track's own severity vocabulary is a superset in spirit but a different list; mapping between them is a caller's job, not this schema's — see the mapping note in the description of `kind`."
+          },
+          "kind": {
+            "enum": [
+              "security",
+              "claim",
+              "correctness",
+              "style"
+            ],
+            "description": "Finding class. Load-bearing for the id: findingId() hashes kind|title|file, so a kind change is a new finding rather than an edit of the old one."
+          },
+          "title": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 300,
+            "description": "Truncated at 300 by parseFindings() in self_review_gate.ts; the bound is pinned here so a producer cannot emit a title the consumer will silently cut."
+          },
+          "detail": {
+            "type": "string",
+            "maxLength": 2000,
+            "description": "Truncated at 2000 by parseFindings(). Same reasoning as `title`."
+          },
+          "file": {
+            "type": "string",
+            "description": "Repo-relative path. Optional because a finding can be about the change as a whole; findingId() folds an absent file to the empty string so the id stays stable either way."
+          },
+          "status": {
+            "enum": [
+              "open",
+              "fixed",
+              "accepted_risk",
+              "false_positive"
+            ],
+            "description": "Disposition. `fixed` / `false_positive` / `accepted_risk` are the three terminal states check_finding_dispositions accepts; `open` is the initial state. NOTE the underscore spelling — the Markdown track writes `accepted-risk` with a hyphen in its Status cell, and the two vocabularies are deliberately not unified here: renaming either would break committed artefacts on that track."
+          },
+          "rationale": {
+            "type": "string",
+            "description": "Why the disposition. Required by check_finding_dispositions for a non-`fixed` terminal status; enforced there rather than here because the requirement is conditional on the workflow stage, not on the document."
+          },
+          "verified_by": {
+            "type": "string",
+            "description": "Who or what confirmed the disposition."
+          },
+          "date": {
+            "type": "string",
+            "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
+            "description": "ISO calendar date of the disposition."
+          }
+        }
+      }
+    }
+  }
+}

package/src/shared/interactiveContext.ts

@@ -0,0 +1,98 @@
+/**
+ * Is there a human at the other end of this execution?
+ *
+ * Phase 4 of `road-to-zero-ceremony-settings`: *"Skip cleanly in non-TTY, CI,
+ * and headless contexts: no file, defaults, no questions, ever."* A settings
+ * question posed where nobody can answer it is not a question — it is either a
+ * hang or a silently-taken default wearing a prompt's clothes.
+ *
+ * WHY THIS MODULE EXISTS RATHER THAN A FOURTH INLINE CHECK. The tree already
+ * carries several CI-detection shapes that disagree:
+ *
+ * - `set && !== '0'` — `src/cli/firstRunNotice.ts`, `src/cli/initRouting.ts`
+ * - truthy only — `src/scripts/install.ts`, `src/scripts/release.ts`
+ * - exact match — `src/scripts/_lib/exec_evidence.ts` (`'true' | '1'`)
+ * - widest, three variables — `src/scripts/reach_doctor.ts`
+ *   (`CI`, `GITHUB_ACTIONS`, `AGENT_CONFIG_CI`)
+ *
+ * This module takes the **widest** shape, because the failure modes are
+ * asymmetric: a false "interactive" hangs an automated run or fabricates a
+ * consent, while a false "non-interactive" merely declines to ask and takes a
+ * conservative default — which is the documented behaviour anyway.
+ *
+ * It deliberately does NOT rewrite those four call sites. Their behaviour is
+ * correct for what they gate (a printed notice, a browser launch), and
+ * converting them here would be a drive-by change to code this concern does not
+ * own. The divergence is recorded rather than repaired — see the roadmap note on
+ * Phase 4 step 3.
+ *
+ * Pure — the environment and the TTY flags are arguments, never read from
+ * `process` inside the predicate, so a test never depends on the machine it
+ * runs on.
+ */
+
+/** Why an execution cannot host a question. `null` means it can. */
+export type NonInteractiveReason =
+    | 'ci'
+    | 'no-ui-requested'
+    | 'not-a-tty'
+    | 'headless';
+
+export interface SessionProbe {
+    /** `process.env`, or a fixture. */
+    env: NodeJS.ProcessEnv;
+    /** `process.stdin.isTTY === true`. */
+    stdinTty: boolean;
+    /** `process.stdout.isTTY === true`. */
+    stdoutTty: boolean;
+    /**
+     * A display-less environment (SSH without forwarding, Linux without
+     * `DISPLAY`). Supplied by the caller because probing it is platform work,
+     * and `src/cli/commands/uiServe.ts` already owns that probe.
+     */
+    headless?: boolean;
+}
+
+/**
+ * The CI variables this predicate honours, widest-first.
+ *
+ * A variable counts as set when it is present and not the literal `0` — the
+ * `set && !== '0'` convention already used by the first-run notice, kept so a
+ * consumer who exports `CI=0` to mean "not CI" is believed.
+ */
+const CI_ENV_KEYS = ['CI', 'GITHUB_ACTIONS', 'AGENT_CONFIG_CI'] as const;
+
+function _flagSet(env: NodeJS.ProcessEnv, key: string): boolean {
+    const raw = (env[key] ?? '').trim();
+    return raw !== '' && raw !== '0';
+}
+
+/**
+ * The reason this execution may not ask, or `null` when a human is reachable.
+ *
+ * Order is deliberate and is the order a reader should think in: an explicit
+ * request not to be asked outranks a capability probe, and CI outranks
+ * everything because a CI run that asks is a CI run that hangs.
+ */
+export function nonInteractiveReason(probe: SessionProbe): NonInteractiveReason | null {
+    for (const key of CI_ENV_KEYS) {
+        if (_flagSet(probe.env, key)) {
+            return 'ci';
+        }
+    }
+    if (_flagSet(probe.env, 'AGENT_CONFIG_NO_UI')) {
+        return 'no-ui-requested';
+    }
+    if (!probe.stdinTty || !probe.stdoutTty) {
+        return 'not-a-tty';
+    }
+    if (probe.headless === true) {
+        return 'headless';
+    }
+    return null;
+}
+
+/** Convenience inverse — `true` when a question is answerable. */
+export function isInteractiveSession(probe: SessionProbe): boolean {
+    return nonInteractiveReason(probe) === null;
+}

package/src/shared/nicknamePrefill.ts

@@ -0,0 +1,96 @@
+/**
+ * What to put in the nickname field before the user types anything.
+ *
+ * Phase 4 step 2 of `road-to-zero-ceremony-settings`: *"Ask the nickname once,
+ * prefilled from git user name then `$USER`, so accepting is one keypress."*
+ * `src/rules/settings-ask-protocol.md` states the chain and closes it with a
+ * negation — **"Never `$USER` alone."**
+ *
+ * WHY THIS MODULE EXISTS. The rule shipped that chain; the one surface that
+ * actually prefills shipped a different one. `src/server/routes/ping.ts` read
+ * `userInfo().username` and nothing else — precisely the `$USER`-alone shape the
+ * rule forbids. A rule and the code it describes disagreeing is drift, not a
+ * preference, so the chain now has exactly one implementation and both the
+ * server route and the tests read it from here.
+ *
+ * WHY GIT COMES FIRST. `$USER` is a login handle (`mathiasberg`); `git config
+ * user.name` is the name the human chose to be called by (`Mathias Berg`). The
+ * whole point of the prefill is that accepting costs one keypress, and that only
+ * holds when the prefilled value is the one they would have typed. Note the
+ * lookup is deliberately NOT `--local`: the merged config includes
+ * `~/.gitconfig`, so the wizard still finds a name when it runs outside a repo.
+ *
+ * Pure: the git lookup is injected, so the resolver is a function of its probe
+ * alone and a test never depends on the machine it runs on — the same shape as
+ * `interactiveContext.ts` and `settingsConsent.ts`. The Node-side half (running
+ * git, falling back to `userInfo()`) lives in `src/server/nicknameResolver.ts`,
+ * because `src/shared/**` may not import Node built-ins and the lint enforces it.
+ *
+ * @see src/server/nicknameResolver.ts — the impure half
+ * @see src/rules/settings-ask-protocol.md § Worked example — the nickname
+ * @see docs/contracts/settings-classes.md
+ */
+
+/**
+ * Where a candidate name came from, so a caller can say so.
+ *
+ * `os-account` is the `userInfo()` floor, and it is a distinct member rather
+ * than a reuse of `env-user` on purpose: the whole claim of the floor is that
+ * its RANK changed (last, not first), and a rank nothing can observe is not a
+ * rank. A caller reporting provenance would otherwise name the wrong rung on
+ * exactly the path the floor exists to serve.
+ *
+ * `none` is a real outcome, not an error: a machine with no git identity, no
+ * `USER` and no resolvable account is unusual but legal, and the ask still
+ * works — it just starts empty.
+ */
+export type NicknameSource =
+    | 'git-user-name'
+    | 'env-user'
+    | 'env-username'
+    | 'os-account'
+    | 'none';
+
+export interface NicknamePrefill {
+    /** The prefill value, or `''` when nothing resolved. */
+    name: string;
+    source: NicknameSource;
+}
+
+export interface NicknameProbe {
+    /** `process.env`, or a fixture. */
+    env: NodeJS.ProcessEnv;
+    /**
+     * `git config user.name`, or `undefined` when git is absent, unconfigured,
+     * or too slow. Injected so the resolver stays pure.
+     */
+    gitUserName?: string | undefined;
+}
+
+/** Trim, and treat a whitespace-only value as absent. */
+function _clean(value: string | undefined): string {
+    return (value ?? '').trim();
+}
+
+/**
+ * The prefill for the nickname ask, following the documented chain.
+ *
+ * Order is the rule's, and the negation at the end of it is the load-bearing
+ * part: `$USER` is a fallback, never the first answer.
+ */
+export function nicknamePrefill(probe: NicknameProbe): NicknamePrefill {
+    const git = _clean(probe.gitUserName);
+    if (git !== '') {
+        return { name: git, source: 'git-user-name' };
+    }
+    const user = _clean(probe.env['USER']);
+    if (user !== '') {
+        return { name: user, source: 'env-user' };
+    }
+    // Windows spells it differently; the rule names it explicitly.
+    const username = _clean(probe.env['USERNAME']);
+    if (username !== '') {
+        return { name: username, source: 'env-username' };
+    }
+    return { name: '', source: 'none' };
+}

package/src/shared/settingsAsks.ts

@@ -0,0 +1,176 @@
+/**
+ * The one-question budget, as a function rather than as a promise.
+ *
+ * Phase 5 of `road-to-zero-ceremony-settings`. The rule
+ * `src/rules/settings-ask-protocol.md` states the budget — at most ONE settings
+ * question per command execution, every further undecided key taking its
+ * conservative default silently and being named in the end-summary. Prose is
+ * where that obligation has to live, because no gate can count the questions in
+ * a chat turn.
+ *
+ * But the *split* is not a judgement call: given the keys an execution needs
+ * decided, which one is asked and what the others resolve to is fully
+ * determined. Leaving that determined part in prose too would mean the roadmap's
+ * own exit criterion — "a planted fixture needing three B decisions asks once,
+ * assumes two conservatively, and lists both in the summary" — had nothing to
+ * run against. So the split is computed here and the rule points at it.
+ *
+ * What this module does NOT do, stated so nobody mistakes it for the fence:
+ * it does not ask, it does not write, and it cannot stop an agent that ignores
+ * it. The write fence is one layer down and is real —
+ * `src/scripts/_cli/cmd_settings_set.ts` and the Fastify settings route both
+ * refuse every C-class key and fail closed on an unreadable class contract.
+ *
+ * Pure — no I/O, no clock, no environment.
+ *
+ * @see src/rules/settings-ask-protocol.md
+ * @see docs/contracts/settings-classes.md
+ */
+
+import { classOfPath, isConservativeDefault, type SettingsClass } from './settingsClasses.js';
+
+/** A key this execution resolved without asking, and how to change it later. */
+export interface SilentDefault {
+    key: string;
+    /** The value taken — the template default, which for B is conservative. */
+    value: unknown;
+    /** The exact command that changes it, for the end-summary line. */
+    command: string;
+}
+
+/** A key that never reaches the ask path, and the reason it does not. */
+export interface SkippedKey {
+    key: string;
+    reason:
+        | 'class-a-never-asked'
+        | 'class-c-guarded'
+        | 'unclassified'
+        | 'already-decided'
+        | 'non-conservative-default';
+}
+
+export interface AskPlan {
+    /** The single key that gets this execution's question, or `null` for none. */
+    ask: string | null;
+    /** Undecided keys that took their default silently, in the order given. */
+    silent: SilentDefault[];
+    /** Keys excluded from the ask path entirely, with the reason. */
+    skipped: SkippedKey[];
+}
+
+/**
+ * The end-summary line for a silently defaulted key.
+ *
+ * `--source manual` and not `jit-answer`: the user did not answer a question, so
+ * stamping the write as a just-in-time answer would record a consent nobody
+ * gave. The provenance vocabulary exists to keep exactly that distinction.
+ */
+export function changeCommand(key: string): string {
+    return `agent-config settings:set ${key} <value> --source manual`;
+}
+
+/**
+ * Plan one execution's settings asks.
+ *
+ * `needed` is the keys this execution genuinely cannot proceed without, in the
+ * order they became needed — the caller's own ordering is respected because the
+ * first key to actually block the run is the one that earned the question.
+ *
+ * `decided` is every key already settled on any resolution layer. A decided key
+ * is not a candidate: re-asking a settled question is the cheap question the
+ * ask-discipline rules forbid, and it is the single most likely way this budget
+ * gets spent on nothing.
+ *
+ * `defaultOf` supplies the template default. It returns `undefined` for a key
+ * the template does not carry, which is treated as unclassified rather than as
+ * a default of `undefined` — a missing template entry is a defect, not a value.
+ */
+export function planSettingsAsks(
+    needed: readonly string[],
+    classes: ReadonlyMap<string, SettingsClass>,
+    defaultOf: (key: string) => unknown,
+    decided: ReadonlySet<string> = new Set(),
+    options: { interactive?: boolean } = {},
+): AskPlan {
+    const plan: AskPlan = { ask: null, silent: [], skipped: [] };
+    const seen = new Set<string>();
+    // Non-TTY / CI / headless: nobody can answer, so the budget is ZERO rather
+    // than one. Every candidate takes its conservative default and the plan
+    // carries no ask — "no questions, ever", as a computed fact rather than as a
+    // promise the caller has to remember. Nothing is written either: this
+    // function never persists, and with no ask there is no `jit-answer` write.
+    const interactive = options.interactive ?? true;
+
+    for (const key of needed) {
+        // A duplicate in the caller's list must not consume the budget twice.
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+
+        if (decided.has(key)) {
+            plan.skipped.push({ key, reason: 'already-decided' });
+            continue;
+        }
+
+        const cls = classOfPath(classes, key);
+        if (cls === undefined) {
+            // Unclassified is guarded everywhere else in this system; it is
+            // guarded here too. Never fall back to "probably fine".
+            plan.skipped.push({ key, reason: 'unclassified' });
+            continue;
+        }
+        if (cls === 'A') {
+            plan.skipped.push({ key, reason: 'class-a-never-asked' });
+            continue;
+        }
+        if (cls === 'C') {
+            // A C key set to `ask` still produces a RUNTIME question, but that
+            // answer lasts one run and is never persisted, so it is not this
+            // budget's business. Persisting it stays on the human path.
+            plan.skipped.push({ key, reason: 'class-c-guarded' });
+            continue;
+        }
+
+        const fallback = defaultOf(key);
+        if (fallback === undefined) {
+            plan.skipped.push({ key, reason: 'unclassified' });
+            continue;
+        }
+
+        if (interactive && plan.ask === null) {
+            plan.ask = key;
+            continue;
+        }
+
+        if (!isConservativeDefault(fallback)) {
+            // Taking a permissive value silently would be a decision made in
+            // the user's name — the one outcome the Iron Law names outright.
+            // Surfacing it as skipped forces the caller to deal with it instead
+            // of inheriting a permission nobody granted.
+            plan.skipped.push({ key, reason: 'non-conservative-default' });
+            continue;
+        }
+
+        plan.silent.push({ key, value: fallback, command: changeCommand(key) });
+    }
+
+    return plan;
+}
+
+/**
+ * The end-summary block for a plan, or `null` when nothing was defaulted.
+ *
+ * `null` rather than an empty string so a caller cannot append a heading with no
+ * rows under it. This text rides INSIDE the single end-summary that
+ * `direct-answers` already requires — it is never a second summary.
+ */
+export function silentDefaultsSummary(plan: AskPlan): string | null {
+    if (plan.silent.length === 0) {
+        return null;
+    }
+    const lines = plan.silent.map(
+        (s) => `- \`${s.key}\` → ${JSON.stringify(s.value)} (default) · change: \`${s.command}\``,
+    );
+    return `Settings resolved without asking this run:\n${lines.join('\n')}`;
+}

package/src/shared/settingsConsent.ts

@@ -0,0 +1,136 @@
+/**
+ * Is a permissive B-class value a RECORDED CONSENT, or just a value?
+ *
+ * Phase 5 of `road-to-zero-ceremony-settings`, and the answer to that
+ * roadmap's Risk 3 — *"the provenance stamp becomes decoration; an unread stamp
+ * is cost with no return"*. Before this module the sidecar
+ * `settings/.agent-settings.provenance.json` was written by `settings:set` and
+ * read by exactly one caller, the GUI, to **display** it. Nothing decided
+ * anything on it. This is the reader that makes it load-bearing.
+ *
+ * The distinction it draws, which a bare value cannot: `true` that a human chose
+ * and `true` that the machine inferred are the same byte and are not the same
+ * permission. `auto-detected` is the provenance a machine writes about itself —
+ * a locale, an installed binary, a detected host. Letting it grant a consent
+ * would mean the agent could arrive at its own permission by observing the
+ * world, which is the confused-deputy shape in miniature.
+ *
+ * Modelled on `src/scripts/hooks/block_unauthorized_git.ts`: answer from a
+ * recorded fact rather than from the model's recollection, and treat a missing
+ * record as NOT granted rather than as probably-fine.
+ *
+ * WHAT THIS IS NOT. It is not a hook and it does not intercept anything. No
+ * B-class key currently gates an action through a guard — the two that gate
+ * behaviour at all (`personal.open_edited_files`, `memory.learn_on_session_end`)
+ * are read as values by the installer, the wizard and one session_end concern,
+ * and the *action* they govern is prose. So the enforcement gradient is honest
+ * and steep: this function is deterministic, the obligation to call it is
+ * model-carried, and on a prose-only host ask-once can degrade to ask-never.
+ *
+ * Pure — no I/O. Callers supply the value and the sidecar entry.
+ *
+ * @see src/rules/settings-ask-protocol.md
+ * @see docs/contracts/settings-classes.md
+ */
+
+import { isConservativeDefault, type SettingsClass } from './settingsClasses.js';
+
+/** The provenance vocabulary `settings:set` writes. Mirrors its own enum. */
+export type ConsentSource = 'auto-detected' | 'jit-answer' | 'manual' | 'gui';
+
+/**
+ * The sources that can carry a human decision.
+ *
+ * `jit-answer` is a question the user answered. `gui` is a human at the settings
+ * editor. `manual` is a hand-edit or an explicit CLI write on the user's
+ * instruction. `auto-detected` is excluded on purpose — see the module header.
+ */
+const HUMAN_SOURCES: readonly ConsentSource[] = ['jit-answer', 'gui', 'manual'];
+
+export type ConsentVerdict =
+    /** A human decided, and the value permits the action. */
+    | 'granted'
+    /** The value is the conservative default — absent and no are the same thing. */
+    | 'withheld-default'
+    /** Permissive, but nothing records who decided it. Fail closed. */
+    | 'withheld-unrecorded'
+    /** Permissive and recorded, but recorded as a machine inference. */
+    | 'withheld-machine-inferred'
+    /** Not a consent question at all: A needs none, C is human-only. */
+    | 'not-a-consent-key';
+
+export interface ConsentQuery {
+    /** The key's class, from the contract — `undefined` means unclassified. */
+    cls: SettingsClass | undefined;
+    /** The effective value after normal resolution. */
+    value: unknown;
+    /**
+     * The sidecar entry for this key, or `undefined` when none exists.
+     *
+     * `undefined` covers both "the sidecar has no row" and "there is no sidecar",
+     * which are the same fact from here: nothing records a decision.
+     */
+    source?: ConsentSource | undefined;
+    /**
+     * `true` when the value came from a file only a human can write — a
+     * project-local `.agent-settings.yml` or a hand-edited user file.
+     *
+     * The class contract is explicit that *"the user may edit anything in their
+     * own file with an editor"*, so a hand-edit IS the consent even though it
+     * carries no stamp. Without this the check would refuse the one path the
+     * contract guarantees, which is how a fence becomes a bug.
+     */
+    handEdited?: boolean;
+}
+
+/**
+ * The verdict for one consent-gated action.
+ *
+ * Order matters: class first (a C key never reaches a consent question at all),
+ * then the value (conservative means no, regardless of provenance), then the
+ * record.
+ */
+export function consentVerdict(query: ConsentQuery): ConsentVerdict {
+    if (query.cls !== 'B') {
+        return 'not-a-consent-key';
+    }
+    if (isConservativeDefault(query.value)) {
+        return 'withheld-default';
+    }
+    if (query.handEdited === true) {
+        return 'granted';
+    }
+    if (query.source === undefined) {
+        return 'withheld-unrecorded';
+    }
+    if (!HUMAN_SOURCES.includes(query.source)) {
+        return 'withheld-machine-inferred';
+    }
+    return 'granted';
+}
+
+/** `true` only for `granted` — every other verdict withholds. */
+export function consentGranted(query: ConsentQuery): boolean {
+    return consentVerdict(query) === 'granted';
+}
+
+/**
+ * One line explaining a withheld verdict, for the surface that refused.
+ *
+ * `null` for `granted`, so a caller cannot accidentally print a refusal reason
+ * on the allow path.
+ */
+export function withheldReason(verdict: ConsentVerdict, key: string): string | null {
+    switch (verdict) {
+        case 'granted':
+            return null;
+        case 'withheld-default':
+            return `${key} is at its conservative default — absent and no are the same answer.`;
+        case 'withheld-unrecorded':
+            return `${key} permits this, but nothing records who decided it. Ask, or set it via the GUI.`;
+        case 'withheld-machine-inferred':
+            return `${key} was auto-detected, not decided. A machine inference is not a consent.`;
+        case 'not-a-consent-key':
+            return `${key} is not a class-B consent key — this gate does not apply to it.`;
+    }
+}