@event4u/agent-config 13.0.0 → 14.0.0

package/src/scripts/condense.ts

@@ -1297,7 +1297,7 @@ function _CLAUDE_COMMANDS_DIR(): string {
     return path.join(MODULE_STATE.PROJECT_ROOT, '.claude', 'commands');
 }
 
-function _parse_frontmatter(content: string): [Record<string, unknown>, string] {
+export function _parse_frontmatter(content: string): [Record<string, unknown>, string] {
     if (!content.startsWith('---')) {
         return [{}, content];
     }

package/src/scripts/council_cli.ts

@@ -48,7 +48,9 @@ import {
     PerplexityCliClient,
     XAIClient,
     XAICliClient,
+    CLI_CONSUMER_COUNCIL,
     load_anthropic_key,
+    load_cli_call_attribution,
     load_cli_call_counts,
     load_openai_key,
     quota_summary_line,
@@ -64,27 +66,38 @@ import { format_install_hints } from './ai_council/cli_hints.js';
 import {
     type AdvisorConfig,
     type CouncilConfig,
-    type QuorumSetting,
     COUNCIL_CONFIG_ENV,
     COUNCIL_CONFIG_USER_GLOBAL_REL,
     CouncilConfigError,
     load_council_config,
     resolve_api_key,
+    resolve_cli_call_caps,
     resolve_config_path,
 } from './ai_council/config.js';
 import { AuthCache, select_solo_member } from './ai_council/solo_dispatch.js';
 import { InvalidModeError, resolve_global_mode } from './ai_council/modes.js';
 import { resolveMemberTransport } from './ai_council/transport_resolver.js';
-import { absentReasonFromCliFailure, classifyCliFailure, type AbsentReason } from './ai_council/transport_resolver.js';
-import { evaluateQuorum, SOLO_FLOOR_MIN_PRESENT, type QuorumResult } from './ai_council/quorum.js';
+import { classifyCliFailure, type AbsentReason } from './ai_council/transport_resolver.js';
+import { evaluateQuorum, type QuorumResult } from './ai_council/quorum.js';
 import {
-    appendEvent,
-    appendQuorumEvent,
-    type QuorumAbsence,
-    type QuorumCommand,
-    type QuorumDispatch,
-    type QuorumEventPhase,
-} from './ai_council/events_log.js';
+    _emitQuorumEvent,
+    _format_quorum_line,
+    _postRunQuorum,
+    _quorum_min_present_from,
+    _quorum_setting_from,
+} from './ai_council/quorum_wiring.js';
+import { formatQualificationLine, type MemberQualification } from './ai_council/qualification.js';
+import {
+    absenceReasonFor,
+    attendanceGate,
+    countableSeats,
+    qualificationJson,
+    qualificationStatusLines,
+    qualifySeat,
+    recordRoundObservations,
+} from './ai_council/qualification_wiring.js';
+import { PROBE_STORE_RELPATH, readProbeStore, type ProbeStore } from './ai_council/probe_store.js';
+import { appendEvent, type QuorumCommand, type QuorumDispatch } from './ai_council/events_log.js';
 import {
     type ClassificationResult,
     type SizeFitVerdict,
@@ -609,6 +622,18 @@ interface BuildMembersOptions {
      * state that differs per machine and per CI run.
      */
     environment_report?: EnvironmentReport | null;
+    /**
+     * Recorded provider observations. Supplied ⇒ presence is gated on the
+     * qualification ladder; omitted ⇒ not evaluated at all, and presence keeps
+     * its constructibility-only meaning. Why omission is the safe default:
+     * `qualification_wiring.ts` § The injection contract.
+     */
+    probe_store?: ProbeStore | null;
+    /**
+     * Out-param: the verdict per enabled member, in roster order. Empty from a
+     * caller that passed no store means "not evaluated" — NOT "all qualified".
+     */
+    qualification_out?: MemberQualification[] | null;
 }
 
 /**
@@ -632,172 +657,6 @@ function _member_api_key_present(cfg: Dict): boolean | undefined {
     }
 }
 
-/**
- * `ai['quorum']` as forwarded by `_synthesize_ai_council_block` (already
- * validated by `config.ts::_build_quorum` on that path) — or, for a caller
- * that hands `build_members` a hand-built dict bypassing the loader
- * entirely, a defensive re-check that fails soft to `'majority'` rather
- * than throwing. `build_members` is not the config-validation layer;
- * `evaluateQuorum` degrades an unrecognisable setting toward
- * `inconclusive`, never toward a false `concluded`, so failing soft here
- * costs nothing on the safety side.
- */
-function _quorum_setting_from(ai: Dict): QuorumSetting {
-    const raw = ai['quorum'];
-    if (raw === 'majority') {
-        return 'majority';
-    }
-    if (typeof raw === 'number' && Number.isInteger(raw) && raw >= 1) {
-        return raw;
-    }
-    return 'majority';
-}
-
-/**
- * `ai['quorum_min_present']` with the same fail-soft posture as
- * `_quorum_setting_from`: the loader has already validated it on the normal
- * path, and a hand-built dict that bypasses the loader falls back to the
- * ADR-224 default rather than throwing.
- *
- * Failing soft costs nothing on the safety side here, and less than it does
- * for `quorum`: this value feeds a counterfactual boolean that no gate reads,
- * so the worst outcome of a wrong fallback is one mis-recorded telemetry line,
- * never a pass that concluded when it should not have.
- */
-function _quorum_min_present_from(ai: Dict): number {
-    const raw = ai['quorum_min_present'];
-    if (typeof raw === 'number' && Number.isInteger(raw) && raw >= 1) {
-        return raw;
-    }
-    return SOLO_FLOOR_MIN_PRESENT;
-}
-
-/**
- * Emit one `quorum_result` line for a resolved quorum.
- *
- * Both `evaluateQuorum` call sites route through here, tagged by `phase`, so
- * a solo-concluded pass is distinguishable from a full-attendance one in the
- * event log — the gap `road-to-always-on-orchestration`'s Risk 6 asserted was
- * already closed and was not.
- *
- * The emit sits at the call sites rather than inside `_postRunQuorum` on
- * purpose: that function is exported and unit-tested as a pure derivation,
- * and a write buried in it would make every test of it a log writer.
- *
- * `absent` entries arrive as the CLI's own `{member, reason, detail}` dicts;
- * `detail` is dropped by `appendQuorumEvent`'s input type, which cannot carry
- * free-form text at all.
- */
-function _emitQuorumEvent(
-    phase: QuorumEventPhase,
-    quorum: QuorumResult,
-    absent: readonly Dict[],
-    ctx: {
-        command: QuorumCommand;
-        dispatch?: QuorumDispatch;
-        /** Enabled members before `--single` filtering; defaults to the roster that ran. */
-        configuredTotal?: number;
-        lens?: string;
-        invocation?: string;
-        /**
-         * The ADR-224 shadow floor for this pass. `gateClass` is deliberately
-         * NOT in this context object: no CLI path declares itself gate-class,
-         * so a parameter here would be one no caller ever sets, and its
-         * absence is what the `false` on every line honestly records.
-         */
-        minPresent?: number;
-    },
-): void {
-    appendQuorumEvent({
-        lens: ctx.lens ?? '',
-        invocation: ctx.invocation ?? '',
-        phase,
-        command: ctx.command,
-        dispatch: ctx.dispatch ?? 'full',
-        configuredTotal: ctx.configuredTotal ?? quorum.total,
-        result: quorum,
-        ...(ctx.minPresent !== undefined ? { minPresent: ctx.minPresent } : {}),
-        absent: absent.map(
-            (a): QuorumAbsence => ({
-                member: String(a['member'] ?? ''),
-                reason: (a['reason'] as QuorumAbsence['reason']) ?? 'unavailable',
-            }),
-        ),
-    });
-}
-
-/**
- * Re-derive quorum AFTER the provider calls, over what was actually USABLE —
- * never what merely CONSTRUCTED (M3, independent-review finding). `members`
- * and `responses` must be index-aligned (`consult()`'s own contract: one
- * `CouncilResponse` per member, from the final round); `members.length` is
- * the `n` — deliberately the roster that actually ran (post `--single` /
- * `--siblings` filtering), never the full config roster a filtered run
- * never attempted. A response carrying `.error` (or a missing response
- * entry altogether) counts as absent, classified through the same
- * `AbsentReason` vocabulary a static (pre-call) resolution failure uses, so
- * one artefact buckets every absence — construction-time and mid-flight —
- * under one taxonomy.
- */
-function _postRunQuorum(
-    members: ExternalAIClient[],
-    responses: CouncilResponse[],
-    ai_cfg: Dict,
-): { quorum: QuorumResult; absent: Dict[] } {
-    const absent: Dict[] = [];
-    let present = 0;
-    for (let i = 0; i < members.length; i++) {
-        const m = members[i] as ExternalAIClient;
-        const r = responses[i];
-        // Round 7 § 5.2 — attendance is a NON-EMPTY answer, not the absence of an
-        // error. `!r.error` alone counted a member that returned zero bytes, and
-        // that is not hypothetical: a 290 s curl timeout returned an empty body
-        // with no error set in two sessions (`9fc9ba3e`, `4ac2f7ac`) and the
-        // banner printed `2/2 present` — a single-voice verdict presented as
-        // convergence, on a paid run. An empty answer contributes nothing to a
-        // quorum by definition, whatever the transport thought of it.
-        if (r !== undefined && !r.error && r.text.trim() !== '') {
-            present += 1;
-            continue;
-        }
-        const raw = r?.error ?? (r !== undefined && r.text.trim() === '' ? 'empty response body' : 'no response');
-        const failure = classifyCliFailure(raw);
-        absent.push({
-            member: m.name,
-            reason: absentReasonFromCliFailure(failure) ?? 'unavailable',
-            detail: raw,
-        });
-    }
-    return { quorum: evaluateQuorum(members.length, present, _quorum_setting_from(ai_cfg)), absent };
-}
-
-/**
- * One-line k-of-n banner, mirrored from `orchestrator.ts::_render_quorum_line`
- * but for the CLI's own stdout stream rather than the rendered report —
- * "attendance is telemetry, never a silent drop" applies to the estimate
- * preview too, not only to a completed pass.
- */
-function _format_quorum_line(q: QuorumResult, phase?: QuorumEventPhase): string {
-    // The phase tag is not decoration. A degraded run prints attendance TWICE —
-    // the pre-run reading before the estimate table, the post-run reading after
-    // the consult — and the two disagree by construction: `2/2 present …
-    // concluded` then `0/2 present … INCONCLUSIVE`. Same prefix, opposite
-    // content, and until 2026-08-12 neither line said which was which, so an
-    // operator skimming (or anything grepping `council:quorum ·`) could take the
-    // stale one. The event log had solved this from the start with an explicit
-    // `phase` field; stdout had not. Optional, because the estimate path prints
-    // exactly one line and a tag there would claim a distinction it does not make.
-    const tag = phase === undefined ? '' : `${phase === 'pre_run' ? 'before the run' : 'after the run'} · `;
-    const verdict = q.status === 'concluded' ? 'concluded' : 'INCONCLUSIVE — release gate holds';
-    // Round 7 § 5.3 — a degraded pass says so. `1/2 present, needed 1 —
-    // concluded` is literally true and reads as agreement; with a threshold of 1
-    // a solo answer concludes, and nothing in the line distinguishes "both
-    // members agreed" from "one member answered". The counts were always there;
-    // what was missing is the word that stops a reader inferring convergence.
-    const degraded =
-        q.present < q.total ? `  ⚠️  DEGRADED — ${String(q.total - q.present)} member(s) did not answer; this is not convergence.` : '';
-    return `council:quorum · ${tag}${q.present}/${q.total} present, needed ${q.threshold} — ${verdict}.${degraded}`;
-}
 
 function build_members(settings: Dict, opts: BuildMembersOptions = {}): ExternalAIClient[] {
     const invocation_mode = opts.invocation_mode ?? null;
@@ -805,6 +664,9 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
     const siblings_overrides = opts.siblings_overrides ?? null;
     const skipped = opts.skipped ?? null;
     const quorum_out = opts.quorum_out ?? null;
+    const probe_store = opts.probe_store ?? null;
+    const qualification_out = opts.qualification_out ?? null;
+    const qualifications: MemberQualification[] = [];
     // Read-only, per-process-memoised (`detectEnvironment` caches the
     // no-argument call) — cheap to call once per `build_members` invocation.
     // A caller may inject a fixed report (tests only); production leaves
@@ -837,10 +699,16 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
     // dropped the configured default for every caller that hands this
     // exported function a raw `.ai-council.yml` dict.
     const global_mode = resolve_global_mode(ai);
+    // ENFORCED cap source. This function accepts BOTH config shapes (see the
+    // `resolve_global_mode` note above), and for a RAW `.ai-council.yml` dict a
+    // commented-out `cli_call_budget:` leaves the map empty — the lookup below
+    // used to fall back to `null`, which `ask()` reads as uncapped while still
+    // booking. Resolution runs through `resolve_cli_call_caps`, the same
+    // authority `cmd_quota` uses, so uncapped is unreachable by omission.
     const cli_budget_cfg = _isDict(ai) ? ((ai['cli_call_budget'] as Dict) || {}) : {};
-    const cli_caps = _isDict(cli_budget_cfg)
-        ? ((cli_budget_cfg['max_calls_per_day'] as Dict) || {})
-        : {};
+    const cli_caps = resolve_cli_call_caps(
+        _isDict(cli_budget_cfg) ? cli_budget_cfg['max_calls_per_day'] : undefined,
+    );
     const cli_warn_at = _isDict(cli_budget_cfg)
         ? _pyFloat(cli_budget_cfg['warn_at'] ?? 0.8, 0.8)
         : 0.8;
@@ -928,6 +796,20 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
             // same pattern.
             ...(api_key_present !== undefined ? { apiKeyPresent: api_key_present } : {}),
         });
+        // Qualification runs on the resolved transport, before any branch
+        // decides whether this seat constructs — ONE call site, because the
+        // branches differ in how a member is built, not in what would qualify
+        // it. `||` matches the construction path below (R2 finding 11).
+        if (probe_store !== null) {
+            qualifications.push(
+                qualifySeat(
+                    name,
+                    resolved,
+                    (overrides[name] as string | undefined) || (cfg['model'] as string | undefined) || null,
+                    probe_store,
+                ),
+            );
+        }
         if (name in siblings) {
             if (resolved.transport !== 'api') {
                 throw new CouncilDisabledError(
@@ -1015,7 +897,7 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
                 members.push(
                     _construct_cli_member(name, model, {
                         binary: (cfg['binary'] as string | null) ?? null,
-                        max_calls_per_day: (cli_caps[name] as number | undefined) ?? null,
+                        max_calls_per_day: cli_caps[name] as number,
                         warn_at: cli_warn_at,
                     }),
                 );
@@ -1055,6 +937,26 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
             );
         }
     }
+    // Phase 3 step 4 — presence is gated on qualification, and the roster is
+    // NOT. Dropping an unqualified seat from `total` would lower the threshold
+    // (`ceil(n/2)`) and make a short pass EASIER to conclude, which inverts the
+    // intent; withholding it from `present` is what makes the pass report being
+    // short. A seat already recorded absent is excluded here so it is not
+    // subtracted twice.
+    //
+    // Routed through `record_absent`, never subtracted separately — that keeps
+    // the event's `total - present == absent.length` invariant. The seat is
+    // still dispatched: see `qualification_wiring.ts::attendanceGate`.
+    const gate = attendanceGate(qualifications, new Set(absent_entries.map((e) => String(e['member']))));
+    for (const q of gate.toRecordAbsent) {
+        record_absent({ member: q.name, reason: absenceReasonFor(q), detail: formatQualificationLine(q) });
+    }
+    if (gate.noticeLine !== null) {
+        _stderr(`${gate.noticeLine}\n`);
+    }
+    if (qualification_out !== null) {
+        qualification_out.push(...qualifications);
+    }
     if (quorum_out !== null) {
         const present = total_enabled - absent_count;
         quorum_out.result = evaluateQuorum(total_enabled, present, _quorum_setting_from(ai));
@@ -1239,7 +1141,13 @@ function _construct_cli_member(
     const warn_at = opts.warn_at ?? 0.8;
     if (name in _CLI_FACTORY) {
         const [cls, default_model] = _CLI_FACTORY[name] as [
-            new (opts: { model: string; binary?: string | null; max_calls_per_day?: number | null; warn_at?: number }) => CliClient,
+            new (opts: {
+                model: string;
+                binary?: string | null;
+                max_calls_per_day?: number | null;
+                warn_at?: number;
+                consumer?: string;
+            }) => CliClient,
             string,
             string,
         ];
@@ -1248,6 +1156,9 @@ function _construct_cli_member(
             binary,
             max_calls_per_day,
             warn_at,
+            // Declared at the construction site — the client cannot know its
+            // caller. The council half of the two enumerated consumers.
+            consumer: CLI_CONSUMER_COUNCIL,
         });
     }
     throw new CouncilDisabledError(
@@ -1836,6 +1747,7 @@ function cmd_estimate(
             siblings_overrides: _parse_siblings_overrides(_getattr<string[] | null>(args, 'siblings', null)),
             skipped,
             quorum_out,
+            probe_store: readProbeStore(REPO_ROOT),
             // A cost preview spends nothing and runs no pass. The line is
             // still written — tagged, so a consumer excludes it deliberately
             // instead of never learning it was there.
@@ -2401,6 +2313,14 @@ export function cmd_status(args: Args, opts: { env?: Record<string, string | und
     // because only one of the two is fixed by writing a config.
     const configured = cfg !== null && cfg.enabled && enabledMembers.length > 0;
 
+    // `configured` above is a boolean off the config file — exactly what let a
+    // dead seat report as healthy. It stays (it answers a real question) but is
+    // no longer the only thing this command says.
+    const probeStore = readProbeStore(REPO_ROOT);
+    const qualifications = enabledMembers.map(([name, m]) =>
+        qualifySeat(name, _resolvedTransportFor(name, m), m.model, probeStore),
+    );
+
     if (_getattr(args, 'json', false)) {
         _stdout(
             `${JSON.stringify({
@@ -2427,8 +2347,14 @@ export function cmd_status(args: Args, opts: { env?: Record<string, string | und
                     }),
                 ),
                 ignored_transport_keys: cfg?.ignored_transport_keys ?? [],
+                qualification: qualificationJson(qualifications),
+                qualified_members: countableSeats(qualifications),
                 parse_error,
+                // Scoped to CONFIG (ADR-104); the probe read is named beside
+                // it — `qualification_wiring.ts` § What the status surface consulted.
+                project_tree_consulted_for_config: false,
                 project_tree_consulted: false,
+                probe_store_path: PROBE_STORE_RELPATH,
             })}\n`,
         );
         return 0;
@@ -2458,6 +2384,11 @@ export function cmd_status(args: Args, opts: { env?: Record<string, string | und
             const detail = t.available ? t.transport : `unavailable — ${t.reason ?? 'no usable transport'}`;
             _stdout(`  transport        ${name}: ${detail}${billing}\n`);
         }
+        // The four-value verdict per seat, then the advice — TWO warnings, so
+        // an `unavailable` seat is not told to re-run (R2 finding 12).
+        for (const line of qualificationStatusLines(qualifications)) {
+            _stdout(`${line}\n`);
+        }
         if (cfg.ignored_transport_keys.length > 0) {
             _stdout('\n');
             _stdout('  Ignored transport keys — transport is resolved, not configured:\n');
@@ -2468,7 +2399,7 @@ export function cmd_status(args: Args, opts: { env?: Record<string, string | und
         }
     }
     _stdout('\n');
-    _stdout('  The project tree is NEVER consulted (ADR-104). No project file —\n');
+    _stdout('  The project tree is NEVER consulted FOR CONFIG (ADR-104). No project file —\n');
     _stdout('  `.agent-settings.yml` included — indicates council availability in\n');
     _stdout('  either direction. Do not infer it from one; run this instead.\n');
     if (!configured) {
@@ -2559,6 +2490,7 @@ function cmd_run(
             siblings_overrides: _parse_siblings_overrides(_getattr<string[] | null>(args, 'siblings', null)),
             skipped,
             quorum_out,
+            probe_store: readProbeStore(REPO_ROOT),
         });
     }
     // Measured, never assumed: `_apply_solo_dispatch` escalates back to the
@@ -2773,6 +2705,7 @@ function cmd_run(
     const post_run = _postRunQuorum(members, responses, ai_cfg);
     quorum_out.result = post_run.quorum;
     skipped.push(...post_run.absent);
+    recordRoundObservations(REPO_ROOT, members, responses, classifyCliFailure);
     // Attendance telemetry for the reading that actually decided the pass.
     // `post_run.absent` is the mid-flight set only; the construction-time
     // skips already went out under `phase: 'pre_run'` from `build_members`,
@@ -3092,6 +3025,7 @@ function cmd_debate(
             siblings_overrides: _parse_siblings_overrides(_getattr<string[] | null>(args, 'siblings', null)),
             skipped,
             quorum_out,
+            probe_store: readProbeStore(REPO_ROOT),
             command: 'debate',
         });
     }
@@ -3305,6 +3239,12 @@ function cmd_debate(
         throw exc;
     }
 
+    // Debate consumes qualification, so it produces observations too —
+    // otherwise a debate-only operator's seats stay `unknown` forever
+    // (R2 finding 14). Not a post-run quorum: recording and re-deriving are
+    // different jobs, and the debate path deliberately has no quorum.
+    recordRoundObservations(REPO_ROOT, members, all_rounds[all_rounds.length - 1] ?? [], classifyCliFailure);
+
     let actual_total = 0.0;
     for (const rnd of [...all_rounds, restate_responses]) {
         for (const r of rnd) {
@@ -3450,7 +3390,13 @@ function cmd_quota(args: Args, opts: { settings?: Dict | null } = {}): number {
     const s = opts.settings !== undefined && opts.settings !== null ? opts.settings : load_settings();
     const ai_cfg = _isDict(s) ? ((s['ai_council'] as Dict) || {}) : {};
     const cli_budget_cfg = _isDict(ai_cfg) ? ((ai_cfg['cli_call_budget'] as Dict) || {}) : {};
-    const caps = _isDict(cli_budget_cfg) ? ((cli_budget_cfg['max_calls_per_day'] as Dict) || {}) : {};
+    // REPORTED cap source — the same authority the gate uses. It used to read
+    // the settings mapping directly and print "no providers have a configured
+    // cap", which was misleading: the gate seeds a default for every provider,
+    // so an operator reading "no cap" was capped and already booked past it.
+    const caps = resolve_cli_call_caps(
+        _isDict(cli_budget_cfg) ? cli_budget_cfg['max_calls_per_day'] : undefined,
+    );
     const warn_at = _isDict(cli_budget_cfg) ? _pyFloat(cli_budget_cfg['warn_at'] ?? 0.8, 0.8) : 0.8;
 
     if (_getattr<string | null>(args, 'reset', null)) {
@@ -3465,13 +3411,9 @@ function cmd_quota(args: Args, opts: { settings?: Dict | null } = {}): number {
     }
 
     const counts = load_cli_call_counts();
-    if (Object.keys(caps).length === 0) {
-        _stdout(
-            'council:quota · no providers have a configured ' +
-                'cli_call_budget.max_calls_per_day cap.\n',
-        );
-        return 0;
-    }
+    const attribution = load_cli_call_attribution();
+    // No empty-caps branch: the resolver seeds every provider, so there is no
+    // configuration in which this command has nothing to report.
     for (const provider of _pySortedStr(Object.keys(caps))) {
         const limit = _pyInt(caps[provider]);
         const used = _pyInt(counts[provider] ?? 0, 0);
@@ -3482,7 +3424,15 @@ function cmd_quota(args: Args, opts: { settings?: Dict | null } = {}): number {
         } else if (ratio >= warn_at) {
             status = 'warn';
         }
-        _stdout(`council:quota · ${provider} · ${used}/${limit} · ${status}\n`);
+        // Named when the sidecar knows them. An empty suffix is the honest
+        // reading for a bucket booked before attribution existed — not a claim
+        // that nobody spent it.
+        const perConsumer = attribution[provider] ?? {};
+        const consumers = _pySortedStr(Object.keys(perConsumer));
+        const by = consumers.length > 0
+            ? ` · by ${consumers.map((c) => `${c} ${_pyInt(perConsumer[c] ?? 0, 0)}`).join(' + ')}`
+            : '';
+        _stdout(`council:quota · ${provider} · ${used}/${limit} · ${status}${by}\n`);
     }
     return 0;
 }

package/src/scripts/dispatch_r2_reviewer.ts

@@ -685,12 +685,19 @@ function findingsSkeleton(args: {
     return [
         `# Findings: ${args.slug}`,
         `<!-- completion-review: v1 | reviewed: ${args.reviewedDate} | scope: ${args.scopeHash} | diff: ${args.headSha} | reviewer: r2-fresh-subagent-${args.slug} | prompt_hash: ${args.promptHash} -->`,
+        // Set at CREATION, never inferred later: an inferred type reads filename
+        // and location, which are exactly the signals that already fail to
+        // distinguish an input from a binding. This artifact binds a scope from
+        // its first byte, so `current-binding` is what it IS — an empty table is
+        // a RESULT, and a reviewer returning zero findings flips the type to
+        // `honest-null` in the same edit that replaces the table.
+        `<!-- evidence-type: v1 | type: current-binding | declared: ${args.reviewedDate} -->`,
         '',
         args.manifest,
         '',
         '| # | Severity | File:Line | Finding | Status | Reason/Ref |',
         '|---|----------|-----------|---------|--------|------------|',
-        '<!-- reviewer fills the table; 0 findings => replace the table with the exact honest-null line per docs/contracts/plan-review-gates.md §2.3 -->',
+        '<!-- reviewer fills the table; 0 findings => replace the table with the exact honest-null line per docs/contracts/plan-review-gates.md §2.3 AND change the evidence-type to `honest-null` per docs/contracts/evidence-artifact-types.md §4 -->',
         '',
     ].join('\n');
 }

package/src/scripts/hook_manifest.yaml

@@ -74,6 +74,21 @@ concerns:
   # Phase 5 — Tier-1 hook for the minimal-safe-diff rule. Counts unique
   # files touched per turn into agents/runtime/state/minimal-safe-diff.json and
   # flips warning=true past hooks.minimal_safe_diff.threshold.
+  # road-to-metric-loop-and-review-integrity Phase 4 — shipping-intent gate on
+  # diff VOLUME, complementary to `minimal-safe-diff` rather than a duplicate:
+  # that concern counts unique files touched PER TURN, this one counts changed
+  # lines on the branch AT A SHIP VERB. Threshold 1695 is the corrected p90 of
+  # this repository's own last 40 merged PRs, and the exclusion set (review-input
+  # snapshots, generated indexes, projection trees) is part of the metric's
+  # definition, not a tuning knob — the replay measured the naive metric
+  # double-counting the diff it was measuring. Warn-level first; escalation waits
+  # for one release of recorded firings. Evidence:
+  # agents/evidence/eval-findings/metric-loop-s04.md
+  ship-diff-volume:
+    script: src/scripts/hooks/ship_diff_volume_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
   minimal-safe-diff:
     script: src/scripts/minimal_safe_diff_hook.ts
     args: []
@@ -474,6 +489,16 @@ concerns:
     args: []
     fail_closed: false
     severity: advisory
+    # road-to-stop-gate-honesty step 3.1 — skipped on a refusal RETRY.
+    # ARGUMENT, per concern as that step requires: the F2 fire gate is a
+    # once-per-session marker, and this concern's own header records that a
+    # second run "reads the marker and returns silently, without re-running the
+    # transcript scan". The retry therefore cannot change its artefact — the
+    # telemetry line was already written, or already suppressed, on the first
+    # Stop. Idempotence is the concern's own construction, not our assumption
+    # about it. The saving is the module load rather than a large read, which is
+    # the smaller of the two flags below it and is stated as such.
+    skip_on_refusal_retry: true
   # road-to-conformance-round5 Phase 3 — the FIRST concern that can refuse a
   # turn-END. Round 5 measured the reason: both blocking carriers reached zero
   # violations, neither advisory carrier did, and 19 language violations
@@ -557,6 +582,43 @@ concerns:
     args: []
     fail_closed: false
     severity: advisory
+  # road-to-user-out-of-the-loop Phase 0 Step 1 — the interruption ledger.
+  # Every Stop, classifies whether the turn that just ended put a synchronous
+  # contact to the user and appends one `{run_id, turn, kind, class, roadmap}`
+  # line to gitignored runtime state (agents/runtime/state/interruptions.jsonl,
+  # file shape after gate-metrics.jsonl). Three classes, not two: a hand-back
+  # ("das entscheidest Du", "your call") ends the turn and waits for the user
+  # exactly as a question does, so counting only `?` would report this
+  # package's own preferred shape as zero contacts.
+  #
+  # CAPTURE ONLY, and that is the point rather than caution: Phase 0's two
+  # pre-registered claims are baselines, and a baseline can only be read off a
+  # window no mechanism reacted to. It emits nothing, never warns, and always
+  # returns 0 — so it carries no src/config/hook-token-budget.json row, the
+  # same as subagent-ledger and orchestration-record.
+  #
+  # Reply-shape detection is IMPORTED from turn-end-gate (readTranscriptTail,
+  # finalParagraph, HANDBACK) rather than copied — a second copy would drift
+  # from the measured corpus's detector and the drift would land silently in
+  # the baseline. Dedupe on the turn ordinal, the same identity that hook
+  # derives, because a host may fire Stop twice for one turn. fail_closed: false.
+  interruption-ledger:
+    script: src/scripts/hooks/interruption_ledger_hook.ts
+    args: []
+    fail_closed: false
+    severity: advisory
+    # road-to-stop-gate-honesty step 3.1 — skipped on a refusal RETRY, and this
+    # is the flag with the real saving.
+    # ARGUMENT, per concern: `alreadyRecorded(ledgerPath, run_id, turn)` dedupes
+    # on the TURN ORDINAL, and a refusal retry is the same turn by construction
+    # — the gate's layer-2 marker is keyed on that same ordinal. So the ledger
+    # already writes nothing on the retry and the artefact is provably identical.
+    # What it does NOT already avoid is the cost: `main()` calls
+    # `readTranscriptTail` (up to 8 MB, walking the whole file) BEFORE reaching
+    # `alreadyRecorded`, so today every refused Stop pays a full transcript walk
+    # and then discards the result. That is the "pure duplicate cost" § D-3
+    # names, measured in the source rather than assumed.
+    skip_on_refusal_retry: true
   # road-to-subagent-lifecycle-integrity Phase 1 (Steps 2+3) — the subagent
   # lifecycle ledger. Binds ONLY the two new events; on every other slot it is
   # not listed at all. Appends `subagent_start` / `subagent_stop` lines to
@@ -665,22 +727,27 @@ roles:
     # is on it: a worker was handed a bounded slice by an orchestrator that
     # already chose the approach, so a routing pointer there advises nobody who
     # can act on it and costs the dispatch anyway.
-    drop: [delegation-nudge, skill-route, end-review-nudge, council-availability, team-review-gate, self-repair, session-eol]
+    # `interruption-ledger` joins it on the first clause verbatim — "a worker
+    # never talks to the user". Its whole measurement is synchronous user
+    # contacts, so a worker turn that ends in a question to its orchestrator
+    # would be recorded as a contact that never reached a human, inflating the
+    # exact baseline Phase 0 pre-registers.
+    drop: [delegation-nudge, skill-route, end-review-nudge, council-availability, team-review-gate, self-repair, session-eol, interruption-ledger]
 
 platforms:
   augment:
     session_start:    [chat-history, hot-context, handoff-context, session-canary, council-availability, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
     session_end:      [chat-history, memory-learn, session-register]
     stop:             [chat-history, hot-context, verify-before-complete, self-repair, session-register]
-    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, reread-guard]
+    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, ship-diff-volume, reread-guard]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape]
 
   claude:
     session_start:    [chat-history, hot-context, handoff-context, session-canary, council-availability, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe, session-register]
     session_end:      [chat-history, memory-learn, session-register]
-    stop:             [chat-history, hot-context, verify-before-complete, team-review-gate, end-review-nudge, turn-end-gate, self-repair, session-register, session-eol]
+    stop:             [chat-history, hot-context, verify-before-complete, team-review-gate, end-review-nudge, turn-end-gate, self-repair, session-register, session-eol, interruption-ledger]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, delegation-nudge, skill-route, git-authorization, session-canary, self-repair, session-register]
-    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, reread-guard, spawn-guard-shadow]
+    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, ship-diff-volume, reread-guard, spawn-guard-shadow]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape, language-mirror]
     # `language-mirror` — round-5 § 6.1. `pre_compact` sets a pin-lost marker;
     # the `post_tool_use` entry above re-emits the pin exactly once while that
@@ -734,7 +801,7 @@ platforms:
     # still costs the dispatch, and its entire output is thrown away.
     stop:             [chat-history, hot-context, verify-before-complete, self-repair, session-register]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff, language-mirror, git-authorization, session-canary, self-repair, session-register]
-    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, reread-guard, spawn-guard-shadow]
+    pre_tool_use:     [block-no-verify, block-unauthorized-git, evidence-independence, block-kernel-rule-writes, block-config-weakening, rtk-wrap, design-slop, ui-route-nudge, code-graph-nudge, ship-diff-volume, reread-guard, spawn-guard-shadow]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan, pr-url-reminder, orchestration-record, tool-result-bytes, edit-shape]
     # subagent-ledger IS bound here, unlike the two nudges above, and the
     # difference is the delivery channel rather than the platform: the nudges