@event4u/agent-config 9.34.0 → 9.36.0

package/src/scripts/_lib/hook_settings.ts

@@ -0,0 +1,79 @@
+/**
+ * hook_settings — read a `hooks.<section>.enabled` flag out of
+ * `.agent-settings.yml` without dragging a YAML parser into a hook.
+ *
+ * Every default-OFF hook needs the same two-level lookup, and the tree already
+ * carries two hand-rolled copies of it (`code_graph_nudge_hook.enabled` and the
+ * equivalent inside `design_slop_hook`). Adding a third copy for the route
+ * nudge is what this file prevents; the two existing copies are pre-existing
+ * duplication and are deliberately left alone — folding them in is a separate,
+ * behaviour-neutral change, not something to smuggle into a feature diff.
+ *
+ * Fail-closed on the flag, fail-open on the read: an unreadable or malformed
+ * settings file returns `false`, which keeps a default-OFF hook off. A hook
+ * that turned itself ON because it could not read a file would be the worst
+ * possible failure mode for an opt-in nudge.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const SETTINGS_FILE = '.agent-settings.yml';
+
+/**
+ * True when `.agent-settings.yml` under `root` carries
+ * `hooks:\n  <section>:\n    enabled: true`.
+ *
+ * Deliberately indentation-shaped rather than a real parse: the same shape the
+ * existing hooks rely on, and a hook must never fail a tool call because a
+ * dependency could not load.
+ */
+export function hookSectionEnabled(root: string, section: string): boolean {
+    const file = path.join(root, SETTINGS_FILE);
+    let text: string;
+    try {
+        if (!fs.statSync(file).isFile()) return false;
+        text = fs.readFileSync(file, 'utf-8');
+    } catch {
+        return false;
+    }
+
+    const escaped = section.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const sectionPattern = new RegExp(`^(\\s+)${escaped}\\s*:\\s*$`);
+    let inHooks = false;
+    /** Indent width of the matched section header; null while outside it. */
+    let sectionIndent: number | null = null;
+
+    const indentOf = (line: string): number => line.length - line.replace(/^\s+/, '').length;
+
+    for (const raw of text.split(/\r\n|\r|\n/)) {
+        const line = raw.replace(/\s+$/, '');
+        if (!line || line.replace(/^\s+/, '').startsWith('#')) continue;
+
+        // A non-indented line closes both scopes and may open `hooks:`.
+        if (!(line.startsWith(' ') || line.startsWith('\t'))) {
+            inHooks = /^hooks\s*:\s*$/.test(line);
+            sectionIndent = null;
+            continue;
+        }
+
+        if (inHooks) {
+            const opened = sectionPattern.exec(line);
+            if (opened) {
+                // Remember the ACTUAL indent rather than assuming two spaces.
+                // The previous version closed the section on any line indented
+                // <= 3, so on a 4-space file a sibling section never closed and
+                // a default-OFF hook could read another section's enabled: true.
+                sectionIndent = opened[1]!.length;
+                continue;
+            }
+            // A key at or above the section header's own depth closes it.
+            if (sectionIndent !== null && indentOf(line) <= sectionIndent) {
+                sectionIndent = null;
+            }
+        }
+
+        if (sectionIndent !== null && /^\s+enabled\s*:\s*true\b/.test(line)) return true;
+    }
+
+    return false;
+}

package/src/scripts/_lib/session_register.ts

@@ -50,7 +50,16 @@
  *    longer than the TTL means another session may claim your branch.
  * 2. **This is advisory, not a mutex.** Two sessions can claim in the same
  *    millisecond. Nothing here provides exclusion, and no later feature may be
- *    built on it as if it did.
+ *    built on it as if it did. `sessions:claim` refusing to WRITE a claim a peer
+ *    holds is a consistency check on its own write, not exclusion: it protects
+ *    the record from being false, never the peer from being duplicated.
+ * 3. **The claim is per SESSION, and the bridge file has to be too.** The
+ *    paragraph above rules `agents/runtime/state/` out for the register and the
+ *    same argument applies to the claim that feeds it: one shared file per
+ *    checkout means a second session in the same directory reads the first one's
+ *    claim as its own. Measured — four live records carrying one identical,
+ *    already-archived slug. The file is keyed on the host session id where one
+ *    exists, and degrades to the shared path where none does.
  *
  * ## Failure is always open
  *
@@ -359,3 +368,60 @@ export function foreign_live_records(
     const own = safe_stem(session_id);
     return read_live_records(dir, options).filter((r) => safe_stem(r.session_id) !== own);
 }
+
+// ---------------------------------------------------------------------------
+// Collisions — and why `branch` alone was the wrong axis
+// ---------------------------------------------------------------------------
+
+/**
+ * What two live sessions are colliding over.
+ *
+ * `branch` was the only axis this register checked, and it is the CHEAP one: two
+ * sessions on one branch see each other immediately, and coordinating is a
+ * `git worktree add`. `roadmap` is the expensive one and went unchecked —
+ * measured twice (PR #1277/#1280, PR #1280/#1281), both times two sessions built
+ * the SAME roadmap phase under DIFFERENT branch names
+ * (`feat/dispatch-safety-confirmation` vs `feat/dispatch-safety-confirmed-execution`),
+ * so the branch comparison was silent by construction while a whole
+ * implementation was duplicated. One of the two PRs is thrown away either way.
+ */
+export type CollisionKind = 'roadmap' | 'branch';
+
+export interface Collision {
+    kind: CollisionKind;
+    record: SessionRecord;
+}
+
+/**
+ * Classify what this session collides with, roadmap-first.
+ *
+ * Ordering is the finding, not a preference: a roadmap collision means the work
+ * is being done twice and one branch is already wasted, while a branch collision
+ * means two sessions can see each other's commits. Reporting the cheap one first
+ * is what let the expensive one pass unremarked.
+ *
+ * A `null` slug never collides — "no roadmap claimed" is the state of every
+ * session before it picks one, and treating absence as a match would make the
+ * warning fire on every pair of fresh sessions and be switched off.
+ */
+export function classify_collisions(
+    others: readonly SessionRecord[],
+    here: { branch: string | null; roadmap_slug: string | null },
+): Collision[] {
+    const out: Collision[] = [];
+    for (const r of others) {
+        if (
+            here.roadmap_slug !== null &&
+            r.roadmap_slug !== null &&
+            r.roadmap_slug === here.roadmap_slug
+        ) {
+            out.push({ kind: 'roadmap', record: r });
+        }
+    }
+    for (const r of others) {
+        if (here.branch !== null && r.branch === here.branch) {
+            out.push({ kind: 'branch', record: r });
+        }
+    }
+    return out;
+}

package/src/scripts/_lib/ui_surface.ts

@@ -0,0 +1,97 @@
+/**
+ * ui_surface — the ONE definition of "this path is a UI surface".
+ *
+ * Three consumers need the same answer and were about to disagree about it:
+ * the anti-slop PreToolUse hook (which had the only copy), the UI-turn
+ * definition the catalogue analyzer counts against, and the route nudge.
+ * A UI-turn rate measured against one extension set and a nudge fired against
+ * another would produce a consultation rate that no fix could ever move,
+ * because the denominator and the trigger would be different populations.
+ *
+ * `.blade.php` is deliberately part of the set and was absent from the hook's
+ * original regex: a two-part extension does not match a `\.(…)$` alternation,
+ * so every Blade template — the single largest UI surface in a Laravel
+ * consumer — read as a non-UI file. That is why `isUiPath` matches on the
+ * path tail rather than on `path.extname`, which returns `.php` for
+ * `page.blade.php` and would silently reproduce the same hole.
+ */
+
+/** Single-segment UI extensions, without the leading dot. */
+export const UI_EXTENSIONS = [
+    'html',
+    'htm',
+    'css',
+    'scss',
+    'sass',
+    'less',
+    'vue',
+    'svelte',
+    'astro',
+    'jsx',
+    'tsx',
+] as const;
+
+/**
+ * Multi-segment UI suffixes. These cannot be expressed as an extension
+ * alternation — `path.extname('x.blade.php')` is `.php`.
+ */
+export const UI_COMPOUND_SUFFIXES = ['.blade.php'] as const;
+
+/** Equivalent to the historical hook regex, plus the compound suffixes. */
+export const UI_EXT = new RegExp(
+    `(\\.(${UI_EXTENSIONS.join('|')})|${UI_COMPOUND_SUFFIXES.map((s) => s.replace(/\./g, '\\.')).join('|')})$`,
+    'i',
+);
+
+/** True when `p` names a file on a UI surface. Case-insensitive. */
+export function isUiPath(p: string): boolean {
+    return UI_EXT.test(p);
+}
+
+/**
+ * Directory fragments that mark a UI tree across frameworks. The two UI rules
+ * carried only the Laravel pair (`resources/views/`, `resources/js/`), so a
+ * React, Vue, Next or Svelte consumer writing to `src/components/` matched no
+ * path trigger at all. Kept as fragments, not anchored prefixes: a consumer's
+ * UI tree is rarely at the repo root.
+ *
+ * `app/` is deliberately NOT in this list although it is the Next.js router
+ * directory. In a Laravel consumer `app/` is the entire backend, so the
+ * fragment would fire on every controller, model and job — a trigger that
+ * over-fires on the largest directory of a whole ecosystem is worse than the
+ * gap it closes. Next.js route files are caught by extension instead
+ * (`page.tsx`, `layout.tsx` match `isUiPath`), which is the precise signal.
+ */
+export const UI_PATH_FRAGMENTS = [
+    'resources/views/',
+    'resources/js/',
+    // `components/` already subsumes `src/components/` under substring
+    // matching — listing both here would be dead weight. The rules' own
+    // `path_prefix` list keeps both because matching there is anchored.
+    'components/',
+    'pages/',
+] as const;
+
+/**
+ * Fragments that sit INSIDE a UI tree and are not UI. Checked first, because a
+ * substring fragment cannot express "pages/ but not pages/api/" on its own —
+ * and `pages/api/` is server-only Next.js code, the exact over-fire the `app/`
+ * exclusion above exists to avoid. Leaving it in would have put backend files
+ * in the pre-registered UI-turn denominator, which is worse than the nudge
+ * firing on them: a rate is harder to un-break than a warning.
+ */
+export const UI_TREE_EXCLUSIONS = ['pages/api/'] as const;
+
+/**
+ * True when `p` sits inside a conventional UI tree.
+ *
+ * Note this does NOT require a UI extension — that is the point: a `.js` file
+ * under `resources/js/` is UI. The cost is that a non-code file in a UI tree
+ * (a README, a fixture) also matches; callers that need the narrower answer
+ * combine this with `isUiPath`.
+ */
+export function isUiTreePath(p: string): boolean {
+    const normalized = p.replace(/\\/g, '/').toLowerCase();
+    if (UI_TREE_EXCLUSIONS.some((fragment) => normalized.includes(fragment))) return false;
+    return UI_PATH_FRAGMENTS.some((fragment) => normalized.includes(fragment));
+}

package/src/scripts/ai_council/config.ts

@@ -52,6 +52,11 @@
  *    single absent member into a deadlocked release gate (council-verified
  *    2026-08-09). See `quorum.ts` for the resolver a caller applies to its
  *    own present/total member counts.
+ * 9b. `quorum_min_present` ∈ positive integers (default 2, ADR-224). The
+ *    floor a gate-class pass would want — SHADOW ONLY: it is recorded per
+ *    pass and enforced nowhere, so no value of this key can hold, delay or
+ *    fail a council pass today. See `quorum.ts::wouldSoloFloorHold` for why
+ *    the measurement landed without the enforcement.
  *
  * Parity notes (intentional, documented):
  *   - YAML is parsed with `yaml` (npm) at `version: '1.1'`, matching
@@ -71,6 +76,12 @@ import * as path from 'node:path';
 import { parse as parseYaml } from 'yaml';
 
 import * as user_global_paths from '../_lib/user_global_paths.js';
+// LAYERING CONSTRAINT, load-bearing: this is a VALUE import from quorum, while
+// `quorum.ts` imports `QuorumSetting` back from here. That back-edge is
+// `import type` and is erased at build, so there is no runtime cycle today.
+// Converting it to a value import — or adding any other runtime import from
+// quorum into config — creates a real ESM cycle in the loader's init path.
+import { SOLO_FLOOR_MIN_PRESENT } from './quorum.js';
 
 const _VALID_PROVIDERS: ReadonlySet<string> = new Set([
     'anthropic',
@@ -585,6 +596,25 @@ export interface CliCallBudgetConfig {
  */
 export type QuorumSetting = 'majority' | number;
 
+/**
+ * The `min_present` floor ADR-224 authorized, as an operator-visible key.
+ *
+ * A SIBLING key rather than a widened `QuorumSetting`, deliberately.
+ * `QuorumSetting` is consumed by `resolveQuorumThreshold`, `evaluateQuorum`,
+ * `_quorum_setting_from` and their tests; widening it into a union with an
+ * object would touch every one of them to express a value none of them read.
+ * The floor is not a second threshold — `quorum` answers "did enough members
+ * answer to conclude", the floor answers "was that conclusion reached on too
+ * few voices to gate on", and they resolve at different call sites.
+ *
+ * Validated at load like every other key; defaults to
+ * `quorum.ts::SOLO_FLOOR_MIN_PRESENT` so the shadow fire-rate accumulates
+ * without the operator having to opt in — an unset floor that recorded nothing
+ * would leave ADR-224's review trigger (b) with no data to trigger on. Nothing
+ * is enforced at any value: see `wouldSoloFloorHold`.
+ */
+export type QuorumMinPresent = number;
+
 export interface CouncilConfig {
     readonly enabled: boolean;
     readonly defaults: DefaultsConfig;
@@ -594,6 +624,7 @@ export interface CouncilConfig {
     readonly consensus_scoring: ConsensusScoringConfig;
     readonly cli_call_budget: CliCallBudgetConfig;
     readonly quorum: QuorumSetting;
+    readonly quorum_min_present: QuorumMinPresent;
     readonly necessity_classifier: NecessityClassifierConfig;
     readonly model_downgrade: ModelDowngradeConfig;
     readonly debate: DebateConfig;
@@ -822,6 +853,9 @@ export function _build_config(raw: Dict, source_path: PathLike): CouncilConfig {
         _asDict(_getOr(raw, 'cli_call_budget', {})),
     );
     const quorum = _build_quorum(_get(raw, 'quorum', 'majority'));
+    const quorum_min_present = _build_quorum_min_present(
+        _get(raw, 'quorum_min_present', SOLO_FLOOR_MIN_PRESENT),
+    );
     const necessity_classifier = _build_necessity_classifier(
         _asDict(_getOr(raw, 'necessity_classifier', {})),
     );
@@ -871,6 +905,7 @@ export function _build_config(raw: Dict, source_path: PathLike): CouncilConfig {
         consensus_scoring: consensus,
         cli_call_budget,
         quorum,
+        quorum_min_present,
         necessity_classifier,
         model_downgrade,
         debate,
@@ -1905,6 +1940,31 @@ function _build_quorum(raw: Json): QuorumSetting {
     );
 }
 
+/**
+ * Validate `quorum_min_present` — the shadow floor's configured value.
+ *
+ * Rejects the same shapes `_build_quorum` rejects, and for the same reason: a
+ * silently coerced floor produces a fire-rate that is an artefact of the
+ * coercion rather than of the council. `_isInt` already requires
+ * `typeof value === 'number'`, so booleans are excluded by it — the sibling's
+ * extra `!_isBool` conjunct is a Python-ism (there `bool` really is an `int`
+ * subclass) and is not repeated here.
+ *
+ * There is no upper bound — a floor above the roster is clamped per-pass by
+ * `wouldSoloFloorHold`, where the roster is actually known, and rejecting it
+ * at load would refuse a config that is legitimate the moment a member is
+ * added.
+ */
+function _build_quorum_min_present(raw: Json): QuorumMinPresent {
+    if (_isInt(raw) && (raw as number) >= 1) {
+        return raw as number;
+    }
+    throw new CouncilConfigError(
+        `\`quorum_min_present\`=${_pyRepr(raw)} must be an integer >= 1 ` +
+            `(got ${_pyTypeName(raw)}).`,
+    );
+}
+
 function _build_advisor(name: string, cfg: Dict): AdvisorConfig {
     if (!_isDict(cfg)) {
         throw new CouncilConfigError(`advisors.${name}: must be a mapping.`);

package/src/scripts/ai_council/events_log.ts

@@ -6,8 +6,9 @@
  * `<project_root>/agents/runtime/council/events.log`. The schema carries the
  * minimum needed to answer "why did the council skip / block this?" and,
  * since v2, "who actually attended?" — at retro time, without leaking prompt
- * content. v2 added the `quorum_result` action and nothing else; see
- * `appendQuorumEvent`.
+ * content. v2 added the `quorum_result` action and nothing else; v3 added two
+ * booleans to that line (`gate_class`, `floor_would_hold`) and nothing else.
+ * See `appendQuorumEvent`.
  *
  * Privacy floor:
  *     `original_ask` is never written verbatim — the caller passes the raw
@@ -28,7 +29,12 @@ import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { isEnvKillSwitchActive } from '../_lib/env_kill_switch.js';
-import { isSoloConcluded, type QuorumResult } from './quorum.js';
+import {
+    isSoloConcluded,
+    SOLO_FLOOR_MIN_PRESENT,
+    wouldSoloFloorHold,
+    type QuorumResult,
+} from './quorum.js';
 import type { AbsentReason } from './transport_resolver.js';
 
 /**
@@ -36,8 +42,29 @@ import type { AbsentReason } from './transport_resolver.js';
  * `appendQuorumEvent`. Every schema-v1 field keeps its name, type and
  * position, so a v1 reader parses a v2 necessity line unchanged; only the
  * action vocabulary widened.
+ *
+ * v3 adds two booleans to the `quorum_result` line — `gate_class` (declared
+ * by the caller) and `floor_would_hold` (the ADR-224 counterfactual). Purely
+ * additive, in the same sense v2 was: no field is renamed, retyped or moved,
+ * no action is added, and a v2 reader parses a v3 line unchanged because it
+ * reads fields by name and never saw these two. The version moves anyway, so
+ * a consumer computing the shadow fire-rate can tell a line that recorded
+ * `false` from a line written before the field existed — a distinction it
+ * cannot make from the absent field alone.
+ *
+ * v4 adds `min_present` to the same line: the floor value `floor_would_hold`
+ * was actually computed against. Additive in the v2/v3 sense — no field is
+ * renamed, retyped or moved — and it closes a provenance hole rather than
+ * adding a capability. `quorum_min_present` is an operator-facing key in the
+ * **user-global** `.ai-council.yml` (ADR-104), so before v4 two machines
+ * emitted byte-identical lines while measuring different counterfactuals, and
+ * a configured `quorum_min_present: 1` — valid, and provably unable to hold
+ * anything — zeroed `shadow_floor_fire_rate` with no trace on the data. A
+ * boolean whose meaning depends on an unrecorded per-machine value is not a
+ * measurement; recording the value is what makes the series comparable and a
+ * zero reading attributable.
  */
-export const SCHEMA_VERSION = 2;
+export const SCHEMA_VERSION = 4;
 
 export type EventAction = 'proceed' | 'skip_necessity' | 'block_quota' | 'quorum_result';
 
@@ -286,6 +313,42 @@ export interface QuorumEventInput {
     readonly configuredTotal: number;
     readonly result: QuorumResult;
     readonly absent: readonly QuorumAbsence[];
+    /**
+     * Did the CALLER declare this pass gate-class? Declared, never inferred,
+     * and it defaults to `false` — the fail-safe direction, because an
+     * un-declared pass is the one nobody classified and the cost of reading it
+     * as advisory is a missing measurement rather than a held gate.
+     *
+     * Inference from the invocation context was the rejected alternative: it
+     * silently reclassifies passes whenever the context shape changes, which
+     * is the one failure a rate computed over this field could not detect.
+     * `command` + `phase` remain on the line, so a consumer that wants the
+     * inferred reading can still compute it and see it disagree.
+     *
+     * **No producer exists today, by design, and that is not a wiring bug.**
+     * Nothing in the tree branches on `QuorumStatus` to hold a gate, so there
+     * is no gate-class caller to mark; `council_cli.ts::_emitQuorumEvent`
+     * therefore omits it from its context object deliberately rather than by
+     * oversight, and `gate_class` is `false` on every line the tree can emit.
+     * The parameter is kept because the first consumer that holds something on
+     * quorum status IS by construction the first gate-class caller: it sets
+     * this, and `shadow_floor_fire_rate` filtered on it becomes the
+     * enforcement-relevant rate. A field introduced only at that point would
+     * leave every earlier line ambiguous between "not gate-class" and "written
+     * before anyone asked".
+     */
+    readonly gateClass?: boolean;
+    /**
+     * The floor to evaluate the counterfactual against — the operator's
+     * `quorum_min_present`, defaulting to `SOLO_FLOOR_MIN_PRESENT`.
+     *
+     * Written to the line as `min_present` since schema v4, not only consumed:
+     * it comes from the user-global config (ADR-104), so without it on the line
+     * a reader cannot tell which counterfactual a `floor_would_hold` refers to,
+     * and cannot distinguish "the floor never would have fired" from "this
+     * operator configured a floor that cannot fire".
+     */
+    readonly minPresent?: number;
 }
 
 /**
@@ -310,6 +373,10 @@ export function appendQuorumEvent(
     opts: AppendEventOptions = {},
 ): boolean {
     try {
+        // The same default `wouldSoloFloorHold` would have applied, hoisted so
+        // the recorded value and the evaluated value are one expression rather
+        // than two that happen to agree.
+        const minPresent = input.minPresent ?? SOLO_FLOOR_MIN_PRESENT;
         return appendEvent(
             {
                 lens: input.lens,
@@ -328,6 +395,38 @@ export function appendQuorumEvent(
                 // in `quorum.ts`, so a change to it cannot leave a consumer's
                 // copy silently stale.
                 solo: isSoloConcluded(input.result),
+                // Declared class, never inferred — see `QuorumEventInput`.
+                gate_class: input.gateClass ?? false,
+                // The counterfactual, written on every line: would a
+                // `min_present` floor have held this pass? Recorded as a FIELD
+                // on `quorum_result` rather than as a new action, deliberately:
+                // a new action is invisible to every consumer filtering
+                // `action === 'quorum_result'`, which would split the
+                // attendance population in two and silently move the
+                // denominator of all four registered metrics. An additive
+                // boolean moves no existing bucket.
+                //
+                // Mutually exclusive with `verdict: 'inconclusive'` by
+                // construction (`wouldSoloFloorHold` returns false unless the
+                // pass concluded), which is what makes "held by the floor" and
+                // "threshold not met" readable apart from this line alone.
+                // `configuredTotal` is passed, not omitted: post_run `total`
+                // is the roster that CONSTRUCTED, so without it a pass that
+                // lost a member at construction time reads total=1/present=1
+                // and the floor cannot fire on it — the construction-degraded
+                // solo case ADR-224 was actually decided on.
+                //
+                // `min_present` records the floor the counterfactual was
+                // computed against, resolved ONCE below and used for both the
+                // record and the predicate so the line can never disagree with
+                // the boolean it explains — the one-definition discipline
+                // `solo` follows by deferring to `isSoloConcluded`.
+                min_present: minPresent,
+                floor_would_hold: wouldSoloFloorHold(
+                    input.result,
+                    minPresent,
+                    input.configuredTotal,
+                ),
                 absent: input.absent.map((a) => ({ member: a.member, reason: a.reason })),
             },
             opts,

package/src/scripts/ai_council/quorum.ts

@@ -96,12 +96,13 @@ export function evaluateQuorum(
  * ONE such record now exists, and it is deliberately narrow: ADR-224
  * (`docs/decisions/ADR-224-gate-scoped-solo-attendance-floor.md`) authorizes a
  * `min_present: 2` floor to branch on this predicate **for gate-class passes
- * only**, decided against a measured 12.5 % solo-conclusion rate. Nothing has
- * landed yet — no caller branches on it today — so the sentence above still
- * describes the code. It is stated here so a reader finds the authorization
- * instead of re-deriving the prohibition, and so the next branch is visibly a
- * separate argument: the exception is gate-class passes, not solo status
- * generally.
+ * only**, decided against a measured 12.5 % solo-conclusion rate. What landed
+ * from that authorization is `wouldSoloFloorHold` below, which is a
+ * counterfactual and branches nothing — so the sentence above still describes
+ * the code: no caller holds a pass on solo status today. It is stated here so
+ * a reader finds the authorization instead of re-deriving the prohibition, and
+ * so the next branch is visibly a separate argument: the exception is
+ * gate-class passes, not solo status generally.
  *
  * `total` is deliberately NOT consulted. A council configured with a single
  * member concludes solo by construction, and that is still a conclusion
@@ -112,3 +113,79 @@ export function evaluateQuorum(
 export function isSoloConcluded(result: QuorumResult): boolean {
     return result.status === 'concluded' && result.present === 1;
 }
+
+/**
+ * The floor value ADR-224 named: a gate-class pass wants at least two voices.
+ *
+ * A constant rather than a bare `2` at the call site so the shadow telemetry
+ * below and any future enforcement read the same number, and so changing it
+ * is one edit with one place to argue about.
+ */
+export const SOLO_FLOOR_MIN_PRESENT = 2;
+
+/**
+ * WOULD a `min_present` floor have held this pass? Counterfactual only — this
+ * predicate changes nothing and no caller branches on it to hold a gate.
+ *
+ * ADR-224 chose a gate-scoped `min_present: 2` floor against a solo-conclusion
+ * rate of 1 of 8 passes, whose 95 % interval spans roughly 0.3 %–53 %. Two
+ * facts, both read off the tree rather than assumed, decided that what lands
+ * first is the measurement and not the enforcement:
+ *
+ *  - **Nothing in the tree branches on `QuorumStatus` to hold anything.** The
+ *    only non-`quorum.ts` reader of `'inconclusive'` is
+ *    `council_cli.ts::_deserialise_quorum`, which validates a persisted string.
+ *    An enforced floor would therefore change zero behaviour today — there is
+ *    no gate for it to hold — while still being able to hang an advisory pass
+ *    the moment a consumer appears.
+ *  - **ADR-224's own review trigger (b) is "the gate-class floor lands and its
+ *    own fire-rate telemetry accumulates"**, which presumes exactly this
+ *    counterfactual is being recorded.
+ *
+ * So the floor is evaluated on EVERY pass and recorded, never applied. The
+ * fire-rate that accumulates from it is what makes the enforcement decision an
+ * evidence call later instead of a second point estimate.
+ *
+ * `minPresent` is clamped with the same discipline `resolveQuorumThreshold`
+ * applies, and the clamp carries meaning rather than only safety: where the
+ * ceiling resolves to 1 the floor never fires, so a council **configured**
+ * with one member is not counted as a degraded pass. That is the split
+ * `quorum-attendance-budget.json` already insists on for the solo-conclusion
+ * rate — a one-member roster and a two-member roster that lost one are
+ * different findings, and an unclamped floor would merge them.
+ *
+ * **The ceiling is the larger of `result.total` and `configuredTotal`, and it
+ * has to be.** Clamping against `result.total` alone was the first version of
+ * this function and it was structurally unable to fire on the exact case
+ * ADR-224 was decided on: `_postRunQuorum` computes `total` over the roster
+ * that CONSTRUCTED, so a two-member council where one member fails to
+ * construct reads `total = 1, present = 1`, the ceiling collapses to 1, and a
+ * conclusion reached on one of two configured voices records as "the floor
+ * would not have held". The series review trigger (b) accumulates would have
+ * been biased low by construction — a metric blind to its own target
+ * population. `configured_total` exists on the event line precisely to keep
+ * that pass distinguishable, and the fix is to consult it.
+ *
+ * `max`, not `configuredTotal` outright: `total > configuredTotal` is
+ * legitimate and not a shortfall, because `--siblings` fans one enabled config
+ * ENTRY into N clients. `configuredTotal` counts entries, `total` counts
+ * clients, and the honest ceiling is the largest roster the pass could have
+ * drawn on either way.
+ *
+ * A pass that never reached `concluded` is not held by the floor: it failed
+ * the threshold, which is a different outcome with a different cause. The two
+ * are mutually exclusive by construction, which is what makes them readable
+ * apart from the event log alone.
+ */
+export function wouldSoloFloorHold(
+    result: QuorumResult,
+    minPresent: number = SOLO_FLOOR_MIN_PRESENT,
+    configuredTotal?: number,
+): boolean {
+    if (result.status !== 'concluded') {
+        return false;
+    }
+    const ceiling = Math.max(result.total, configuredTotal ?? result.total);
+    const floor = Math.min(Math.max(Math.trunc(minPresent), 1), ceiling);
+    return result.present < floor;
+}