@event4u/agent-config 14.12.0 → 14.13.0

package/src/scripts/_lib/audit_field_provenance.ts

@@ -0,0 +1,54 @@
+/**
+ * Which audit-log fields are OBSERVED and which are producer constants.
+ *
+ * This module exists because a prose sentence was wrong for months and nothing
+ * could tell. `docs/contracts/audit-log-v1.md` described `rules_applied` as
+ * "stable rule ids whose Iron Law fired this phase" — an observation — while
+ * both shipped producers write the literal `['delegation-policy']` on every
+ * line. A consumer following the contract computes a per-rule win rate of 100 %
+ * for one rule and `undefined` for the other 118, and that reads as a finding.
+ *
+ * It was found by the loop rather than by review: mining the real audit stream
+ * with `extract_audit_patterns --min-count 2` mints exactly ONE pattern,
+ * `implement:success:delegation-policy`, at count 914 over 935 lines. A
+ * regularity that strong in a field that varied would be remarkable; in a field
+ * that does not vary it is arithmetic.
+ *
+ * The prose was DELETED rather than softened, and this check replaces it. A
+ * sentence cannot stop a consumer from aggregating over a constant; a function
+ * the consumer must call can, and it goes stale loudly instead of silently
+ * because the producers are named here and a test asserts they still match.
+ *
+ * road-to-experience-loop-broadening step 9.3 — the removal the loop motivated.
+ */
+
+/**
+ * Fields a shipped producer writes as a fixed value, with the value.
+ *
+ * A field listed here is NOT evidence about the run. Adding a row is how a
+ * future producer records the same honesty; removing one requires that the
+ * producer actually compute the field.
+ */
+export const PRODUCER_CONSTANT_FIELDS: ReadonlyMap<string, readonly string[]> = new Map([
+    // Written identically by `orchestration_record.ts` and
+    // `review_skipped_record.ts`. Neither computes it from rules that fired.
+    ['rules_applied', ['delegation-policy']],
+]);
+
+/** True when a per-asset rate over this field would measure the producer. */
+export function isProducerConstantField(field: string): boolean {
+    return PRODUCER_CONSTANT_FIELDS.has(field);
+}
+
+/**
+ * The reason, for a consumer that wants to say why it skipped a column.
+ * `null` when the field is genuinely observed.
+ */
+export function constantFieldReason(field: string): string | null {
+    const v = PRODUCER_CONSTANT_FIELDS.get(field);
+    if (v === undefined) return null;
+    return (
+        `'${field}' is written as the fixed value [${v.map((x) => `'${x}'`).join(', ')}] by every shipped ` +
+        'producer, so any rate computed over it measures the writer rather than the work.'
+    );
+}

package/src/scripts/_lib/auto_dispatch.ts

@@ -156,14 +156,43 @@ const LOOKUP_PATTERNS: Array<{ cls: LookupClass; primitive: LookupPrimitive; re:
  * silently degraded answer; an index-miss at execution time escalates the
  * same way (runtime concern, documented in the classification context).
  */
-export function classifyLookup(taskText: string): LookupRoute {
+export function classifyLookup(
+    taskText: string,
+    opts: { codeGraphEnabled?: boolean | undefined } = {},
+): LookupRoute {
+    // The graph is an OPPORTUNISTIC ACCELERANT, gated on the setting — which is
+    // what `auto-dispatch-classification.md` § Task pattern has always said and
+    // what this function did not do.
+    //
+    // road-to-inbox-harvest-2026-08-f-code-graph-evidence-refresh 2.1 required
+    // deciding which of the two was right and changing the other, not splitting
+    // the difference. The CONTRACT is right, on the only evidence that exists:
+    // the pre-registered benchmark behind `claim:code-graph-retrieval-null`
+    // measured native-graph recall 0.365 against grep's 0.797 on exactly these
+    // graph-shaped questions. Routing to the graph unconditionally routed to the
+    // arm that lost, and no re-measurement has replaced that figure — Phase 3.1
+    // is blocked on inputs this repository does not hold.
+    //
+    // Default FALSE, deliberately, and not because the setting's default is
+    // false: an absent flag means nobody said the index is present and fresh,
+    // and an accelerant taken on an absent index is a miss that escalates —
+    // slower than the grep it replaced. When the flag is on, the class still
+    // routes to `code-graph-query`, so turning it on is the whole change needed
+    // to use the graph.
+    const graphOk = opts.codeGraphEnabled === true;
     for (const p of LOOKUP_PATTERNS) {
         if (p.re.test(taskText)) {
+            const primitive: LookupPrimitive =
+                p.primitive === 'code-graph-query' && !graphOk ? 'fts-or-capped-grep' : p.primitive;
             return {
                 lookup_class: p.cls,
                 route: 'primitive',
-                primitive: p.primitive,
-                reason: `lookup-class ${p.cls} — deterministic primitive, no spawn`,
+                primitive,
+                reason:
+                    primitive === p.primitive
+                        ? `lookup-class ${p.cls} — deterministic primitive, no spawn`
+                        : `lookup-class ${p.cls} — capped grep; the code-graph accelerant is ` +
+                          'gated on hooks.code_graph.enabled and it is not on',
             };
         }
     }

package/src/scripts/_lib/bench_ab_size_claim.ts

@@ -13,6 +13,8 @@
  * change to either has to touch the record and the code together.
  */
 
+import { decidePairedVerdict, floorWarning, MIN_DISCORDANT } from './paired_verdict.js';
+
 /** T1 — median added lines must fall by at least this much. */
 export const T1_MEDIAN_LINES_PCT = -10;
 /** Two-sided significance for every endpoint in the pair. */
@@ -25,7 +27,15 @@ export interface PairedContinuous {
     /** `null` when the baseline median is 0 — no percent change exists. */
     median_delta_pct: number | null;
     median_delta: number;
+    /**
+     * Retained for TRIAGE and reporting. Since PREREG amendment v2 it decides
+     * nothing — see {@link evaluateSizeClaim}.
+     */
     wilcoxon_p: number;
+    /** Non-tied pairs in the direction of interest. Absent on a pre-amendment report. */
+    direction_wins?: number | undefined;
+    /** Non-tied pairs against the direction of interest. Absent on a pre-amendment report. */
+    direction_losses?: number | undefined;
 }
 
 /** A paired binary endpoint (the safety tier). */
@@ -56,6 +66,44 @@ export interface SizeClaimVerdict {
     safety_measured: boolean;
 }
 
+
+
+/** One clause naming the directional evidence, printable in a verdict reason. */
+function describeDirection(v: ReturnType<typeof decidePairedVerdict> | null): string {
+    if (v === null) {
+        return `no direction counts in the report — pre-amendment or unmeasured, so the direction bar is not met`;
+    }
+    if (v.kind === 'underpowered') {
+        return `underpowered: ${String(v.discordant)} non-tied pair(s) below the derived floor of ${String(MIN_DISCORDANT)}`;
+    }
+    const warn = floorWarning(v);
+    return `${String(v.wins)}/${String(v.discordant)} non-tied pairs, one-sided exact p=${v.p.toFixed(4)}` +
+        (warn === null ? '' : ` — ${warn}`);
+}
+
+/**
+ * The directional verdict for one endpoint, or `null` when it cannot be formed.
+ *
+ * `null` means the report carries no direction counts — a pre-amendment report,
+ * or an unmeasured endpoint. The caller treats that as "not significant" rather
+ * than reaching for `wilcoxon_p`, which is the whole point of the amendment.
+ *
+ * The counts are reconstructed into a delta vector of ±1 rather than carrying
+ * raw deltas through the report: the exact sign test needs direction only, and
+ * a council seat noted the raw deltas are preferable for auditability but not
+ * mathematically required. The raw values remain in the trial artifacts.
+ */
+function directionVerdict(e: PairedContinuous): ReturnType<typeof decidePairedVerdict> | null {
+    if (!e.measured) return null;
+    const w = e.direction_wins;
+    const l = e.direction_losses;
+    if (w === undefined || l === undefined) return null;
+    return decidePairedVerdict({
+        deltas: [...Array<number>(w).fill(1), ...Array<number>(l).fill(-1)],
+        alpha: ALPHA,
+    });
+}
+
 /**
  * Evaluate the size claim for one comparison — binding, and structurally unable
  * to report a win on size alone.
@@ -98,9 +146,52 @@ export function evaluateSizeClaim(input: SizeClaimInput): SizeClaimVerdict {
         };
     }
 
-    const cx_rose = cx.measured && cx.median_delta > 0 && cx.wilcoxon_p < ALPHA;
+    // ── PREREG amendment v2, 2026-08-26 — direction decides significance ────
+    //
+    // The significance half of every endpoint below was a Wilcoxon signed-rank
+    // p, which ranks by |difference| and is therefore magnitude-weighted. That
+    // was shown to disagree with the exact test on twelve records up to ten
+    // trials, PERMISSIVE in every one, with the visible symptom inverted: an
+    // artifact winning every trial still failed, because a few large
+    // opposite-direction deltas outweighed a clean sweep of small ones.
+    //
+    // TWO PROPOSITIONS, KEPT SEPARATE — this is the refinement both council
+    // seats independently required (2026-08-26, 2/2) and it is the half that
+    // makes the amendment safe. A sign test answers "did this help more often
+    // than it hurt" and says NOTHING about how much. Replacing Wilcoxon with it
+    // outright would let a clean sweep of negligible improvements claim a SIZE
+    // win. So:
+    //   · directional reliability → exact one-sided sign test over non-tied pairs
+    //   · practical magnitude     → the pre-registered T1_MEDIAN_LINES_PCT bar,
+    //                               unchanged and still independently binding
+    // Both must hold. Dropping either is a different claim and needs its own
+    // amendment.
+    //
+    // A report predating the amendment carries no direction counts. It is
+    // treated as UNMEASURED for the significance half rather than falling back
+    // to `wilcoxon_p`, because a silent fallback to the defective test is
+    // exactly what this amendment removes.
+    const sizeDir = directionVerdict(size);
+    const cxDir = directionVerdict(cx);
+    // ASYMMETRY, deliberate and the conservative direction of it. A PASS needs
+    // the direction bar MET; a REFUSAL fires on EITHER signal. Applying the
+    // strict reading to both would make the anti-golfing refusal disappear on
+    // any report without direction counts — a missing input silently rescuing
+    // an arm is the failure mode a refusal exists to prevent, and it is the
+    // opposite of what the amendment is for. So the refusal keeps the legacy
+    // Wilcoxon signal as a second trigger; the claim does not.
+    const cx_rose =
+        cx.measured &&
+        cx.median_delta > 0 &&
+        (cxDir === null ? cx.wilcoxon_p < ALPHA : cxDir.kind === 'regression');
+    // `regression`, NOT `pass`, and the distinction cost a test run to find.
+    // `direction_wins` counts the endpoint's IMPROVEMENT direction — a negative
+    // delta — for every continuous endpoint, so on complexity a `pass` means
+    // complexity FELL. What `cx_rose` needs is the opposite tail, which is
+    // exactly what `regression` names. Writing `pass` here reads correctly in
+    // English and inverts the anti-golfing guard.
     const pct = size.measured ? size.median_delta_pct : null;
-    const lines_fell = pct !== null && pct <= T1_MEDIAN_LINES_PCT && size.wilcoxon_p < ALPHA;
+    const lines_fell = pct !== null && pct <= T1_MEDIAN_LINES_PCT && sizeDir?.kind === 'pass';
 
     // (2b) Golfing is refused as soon as T2 shows it, and does NOT wait for T4.
     //
@@ -161,8 +252,11 @@ export function evaluateSizeClaim(input: SizeClaimInput): SizeClaimVerdict {
         ...base,
         verdict: lines_fell ? 'PASS' : 'NO-SIZE-WIN',
         reason: lines_fell
-            ? `median added lines ${pct}% at p=${size.wilcoxon_p} with no significant complexity rise and no safety regression`
-            : `T1 not met (median added lines ${pct}% at p=${size.wilcoxon_p}; bar is <= ${T1_MEDIAN_LINES_PCT}% at p<${ALPHA})`,
+            ? `median added lines ${pct}% (magnitude bar) AND ${describeDirection(sizeDir)} (direction bar) ` +
+              'with no significant complexity rise and no safety regression'
+            : `T1 not met (median added lines ${pct}%, bar <= ${T1_MEDIAN_LINES_PCT}%; ` +
+              `direction: ${describeDirection(sizeDir)}). Wilcoxon p=${size.wilcoxon_p} is reported for ` +
+              'triage and decides nothing.',
         lines_fell,
         size_measured: true,
         complexity_measured: true,

package/src/scripts/_lib/benchmark_cache_fields.ts

@@ -0,0 +1,158 @@
+/**
+ * The `cache` block of a benchmark / cost report — required fields, and the one
+ * legitimate way to not have a number (`road-to-runtime-context-floors` step 4.1).
+ *
+ * Both fields are REQUIRED. A report that cannot compute one states a reason; it
+ * does not omit the key and it does not emit a zero. A blank reads as "no cache
+ * activity" and a zero reads as "the worst possible ratio" — both are claims, and
+ * neither is the claim "this was not measured".
+ *
+ * Contract: `docs/contracts/benchmark-report-schema.md` § The `cache` block.
+ */
+
+export const REQUIRED_CACHE_FIELDS = ['read_write_ratio', 'stable_prefix_share'] as const;
+export type RequiredCacheField = (typeof REQUIRED_CACHE_FIELDS)[number];
+
+/**
+ * What produced the report (`road-to-delivered-cost-truth` step 4.2).
+ *
+ * A benchmark number without its provenance cannot be reproduced or challenged,
+ * and this repository carries a measured instance of that failure: an external
+ * round's headline figures are recorded `unverifiable` precisely because the run
+ * behind them is unreachable. These four keep a report here from becoming that.
+ */
+export const REQUIRED_PROVENANCE_FIELDS = [
+    'host_binary_hash',
+    'harness_commit',
+    'harness_dirty',
+    'reproducibility',
+] as const;
+export type RequiredProvenanceField = (typeof REQUIRED_PROVENANCE_FIELDS)[number];
+
+/** A measured number, or a stated reason there is none. Never a bare absence. */
+export type CacheFieldValue = number | { unavailable: string };
+
+export interface CacheBlock {
+    read_write_ratio: CacheFieldValue;
+    stable_prefix_share: CacheFieldValue;
+}
+
+export type AnyRequiredField = RequiredCacheField | RequiredProvenanceField;
+
+export type FieldProblem =
+    | { field: AnyRequiredField; kind: 'missing' }
+    | { field: AnyRequiredField; kind: 'blank-unavailable' }
+    | { field: AnyRequiredField; kind: 'not-a-number'; value: unknown }
+    | { field: AnyRequiredField; kind: 'out-of-range'; value: number }
+    | { field: AnyRequiredField; kind: 'blank-value' };
+
+export function unavailable(reason: string): CacheFieldValue {
+    return { unavailable: reason };
+}
+
+function validateField(field: RequiredCacheField, raw: unknown): FieldProblem | null {
+    if (raw === undefined || raw === null) return { field, kind: 'missing' };
+    if (typeof raw === 'object') {
+        const reason = (raw as { unavailable?: unknown }).unavailable;
+        if (typeof reason !== 'string' || reason.trim().length === 0) {
+            return { field, kind: 'blank-unavailable' };
+        }
+        return null;
+    }
+    if (typeof raw !== 'number' || !Number.isFinite(raw)) return { field, kind: 'not-a-number', value: raw };
+    // A share is a fraction; a ratio is unbounded above but never negative.
+    if (raw < 0) return { field, kind: 'out-of-range', value: raw };
+    if (field === 'stable_prefix_share' && raw > 1) return { field, kind: 'out-of-range', value: raw };
+    return null;
+}
+
+/** Validate a report's `cache` block. Empty array = valid. */
+export function validateCacheBlock(report: unknown): FieldProblem[] {
+    const cache = (report as { cache?: unknown } | null)?.cache;
+    if (cache === undefined || cache === null || typeof cache !== 'object') {
+        return REQUIRED_CACHE_FIELDS.map((field) => ({ field, kind: 'missing' as const }));
+    }
+    const rec = cache as Record<string, unknown>;
+    return REQUIRED_CACHE_FIELDS.map((f) => validateField(f, rec[f])).filter((p): p is FieldProblem => p !== null);
+}
+
+function blockOf(field: AnyRequiredField): string {
+    return (REQUIRED_PROVENANCE_FIELDS as readonly string[]).includes(field) ? 'provenance' : 'cache';
+}
+
+export function describeProblem(p: FieldProblem): string {
+    const q = `${blockOf(p.field)}.${p.field}`;
+    switch (p.kind) {
+        case 'missing':
+            return `${q} is missing — it is required; emit { unavailable: "<reason>" } when it cannot be supplied`;
+        case 'blank-unavailable':
+            return `${q} declares itself unavailable with no reason — a reason is the whole point of the form`;
+        case 'blank-value':
+            return `${q} is an empty string, which states nothing; emit { unavailable: "<reason>" } instead`;
+        case 'not-a-number':
+            return `${q} is ${JSON.stringify(p.value)}, which is neither a number nor { unavailable: "<reason>" }`;
+        case 'out-of-range':
+            return `${q} is ${String(p.value)}, outside its valid range`;
+    }
+}
+
+/**
+ * Validate a report's `provenance` block.
+ *
+ * `harness_dirty` is a BOOLEAN and the others are strings, so the shape check is
+ * per-field rather than uniform — and `false` must pass, which a truthiness
+ * check would silently reject. That is the bug this comment exists to prevent on
+ * the next edit: a dirty flag of `false` is the good case.
+ */
+export function validateProvenanceBlock(report: unknown): FieldProblem[] {
+    const block = (report as { provenance?: unknown } | null)?.provenance;
+    if (block === undefined || block === null || typeof block !== 'object') {
+        return REQUIRED_PROVENANCE_FIELDS.map((field) => ({ field, kind: 'missing' as const }));
+    }
+    const rec = block as Record<string, unknown>;
+    const out: FieldProblem[] = [];
+    for (const field of REQUIRED_PROVENANCE_FIELDS) {
+        const raw = rec[field];
+        if (raw === undefined || raw === null) {
+            out.push({ field, kind: 'missing' });
+            continue;
+        }
+        if (typeof raw === 'object') {
+            const reason = (raw as { unavailable?: unknown }).unavailable;
+            if (typeof reason !== 'string' || reason.trim().length === 0) out.push({ field, kind: 'blank-unavailable' });
+            continue;
+        }
+        if (field === 'harness_dirty') {
+            if (typeof raw !== 'boolean') out.push({ field, kind: 'not-a-number', value: raw });
+            continue;
+        }
+        if (typeof raw !== 'string') out.push({ field, kind: 'not-a-number', value: raw });
+        else if (raw.trim().length === 0) out.push({ field, kind: 'blank-value' });
+    }
+    return out;
+}
+
+/**
+ * Compute the ratio from token totals, or state why not.
+ *
+ * Zero cache-creation tokens is the interesting case: the ratio is undefined,
+ * not infinite and not zero, and the honest report says so.
+ */
+export function readWriteRatio(cacheRead: number, cacheCreation: number): CacheFieldValue {
+    if (!Number.isFinite(cacheRead) || !Number.isFinite(cacheCreation)) {
+        return unavailable('the session source carries no cache_read/cache_creation token fields');
+    }
+    if (cacheCreation === 0) {
+        return unavailable('no cache-creation tokens were recorded in this window, so the ratio is undefined rather than zero');
+    }
+    return cacheRead / cacheCreation;
+}
+
+/** The STABLE cohort as a fraction of dispatches carrying the field, or why not. */
+export function stablePrefixShare(stableN: number, unstableN: number): CacheFieldValue {
+    const total = stableN + unstableN;
+    if (total === 0) {
+        return unavailable('no dispatch in this window recorded both payload_hash and cache_hit');
+    }
+    return stableN / total;
+}