@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/_lib/arith_claims.ts

@@ -0,0 +1,181 @@
+/**
+ * Check an arithmetic claim written in prose against itself.
+ *
+ * The defect this exists for, observed rather than imagined: a fixture states
+ * the same number twice — once as a declared `expected` and once inside the
+ * rationale that derives it — and the two disagree. A judge then prefers the
+ * declared value over the recomputed one and scores a correct response as a
+ * loss. Both numbers are in the file, so nothing has to be inferred; they
+ * simply were never compared.
+ *
+ * The scanner reads CHAINS (`a x b / c = d / c = e`), because that is how the
+ * derivations in this tree are actually written. Comparing only the outermost
+ * pair would mis-read every intermediate step as a claim of its own — the
+ * first version of this check did exactly that and produced three false
+ * findings on a corpus that was correct.
+ *
+ * Prose rounding is legitimate and is tolerated to the PRECISION THE PROSE
+ * ITSELF USES: `1.333` agrees with 4/3, `1.33` does not have to. A fixed
+ * epsilon would either reject honest rounding or accept a real disagreement,
+ * depending on the magnitude of the numbers, which is the wrong axis.
+ */
+
+/** One prose arithmetic chain and what it evaluates to. */
+export interface ArithChain {
+    /** The chain as written. */
+    text: string;
+    /** Every `=`-separated segment that evaluated to a number. */
+    values: readonly { segment: string; value: number }[];
+}
+
+/** A chain whose segments disagree beyond the precision the prose claims. */
+export interface ArithDisagreement {
+    text: string;
+    leftSegment: string;
+    left: number;
+    rightSegment: string;
+    right: number;
+    /** The tolerance the right-hand segment's own precision earns it. */
+    tolerance: number;
+}
+
+const CHAIN = /(?:[-+]?[\d,]*\.?\d+[\s\d,.+\-*/x×^()%]*=\s*)+[-+]?[\d,]*\.?\d+/g;
+
+/**
+ * Evaluate one prose segment, or `null` when it is not pure arithmetic.
+ *
+ * Deliberately narrow: digits, the four operators, `^`, parentheses and the
+ * separators prose uses. Anything else returns `null` rather than being
+ * coerced — a segment carrying a word is a sentence, not a claim, and guessing
+ * at it is how a checker starts inventing findings.
+ */
+export function evaluateSegment(segment: string): number | null {
+    const t = segment
+        .trim()
+        .replace(/,/g, '')
+        .replace(/[×x]/g, '*')
+        .replace(/%/g, '')
+        .replace(/\$/g, '');
+    if (!/\d/.test(t)) return null;
+    if (!/^[\d\s.+\-*/^()]+$/.test(t)) return null;
+    // `^` is exponentiation in prose and XOR in JS — translate before eval.
+    const js = t.replace(/\^/g, '**');
+    try {
+        // Input is whitelisted above to digits, operators and parentheses — a
+        // segment carrying anything else returned null before reaching here.
+        const fn = new Function(`"use strict"; return (${js});`) as () => unknown;
+        const v = fn();
+        return typeof v === 'number' && Number.isFinite(v) ? v : null;
+    } catch {
+        return null;
+    }
+}
+
+/** Decimal places written in a literal, used as the rounding tolerance. */
+function precisionTolerance(segment: string, magnitude: number): number {
+    const m = /\.(\d+)\s*$/.exec(segment.trim());
+    const decimals = m?.[1];
+    if (decimals !== undefined) return 0.5 * 10 ** -decimals.length;
+    // An integer-looking claim is tolerated to half a unit, plus float noise
+    // proportional to the magnitude — `20,000` may legitimately stand for
+    // 20000.000000001 produced by a chain of divisions.
+    return Math.max(0.5, Math.abs(magnitude) * 1e-9);
+}
+
+/** Every arithmetic chain in a piece of prose. */
+export function findArithChains(prose: string): ArithChain[] {
+    const out: ArithChain[] = [];
+    for (const m of prose.matchAll(CHAIN)) {
+        const values: { segment: string; value: number }[] = [];
+        for (const segment of m[0].split('=')) {
+            const value = evaluateSegment(segment);
+            if (value !== null) values.push({ segment, value });
+        }
+        if (values.length >= 2) out.push({ text: m[0], values });
+    }
+    return out;
+}
+
+/**
+ * Every chain whose own segments disagree.
+ *
+ * Each segment is compared against the FIRST evaluable one rather than against
+ * its neighbour: a chain is a claim that all of its forms are the same number,
+ * and comparing neighbours lets an error accumulate quietly across three steps.
+ */
+export function findArithDisagreements(prose: string): ArithDisagreement[] {
+    const out: ArithDisagreement[] = [];
+    for (const chain of findArithChains(prose)) {
+        const first = chain.values[0];
+        if (first === undefined) continue;
+        for (const later of chain.values.slice(1)) {
+            const tolerance = precisionTolerance(later.segment, first.value);
+            if (Math.abs(later.value - first.value) > tolerance) {
+                out.push({
+                    text: chain.text,
+                    leftSegment: first.segment.trim(),
+                    left: first.value,
+                    rightSegment: later.segment.trim(),
+                    right: later.value,
+                    tolerance,
+                });
+                break;
+            }
+        }
+    }
+    return out;
+}
+
+/**
+ * Does a prose derivation ever state the declared value?
+ *
+ * Returns `null` when the prose carries no evaluable chain at all — an absent
+ * derivation is not a disagreement, and treating it as one would make the
+ * check fire on every fixture that simply cites a source instead.
+ */
+export function chainSupportsExpected(
+    prose: string,
+    expected: number,
+    tolerance: number,
+): boolean | null {
+    const chains = findArithChains(prose);
+    if (chains.length === 0) return null;
+    for (const chain of chains) {
+        for (const v of chain.values) {
+            const tol = Math.max(tolerance, precisionTolerance(v.segment, expected));
+            if (Math.abs(v.value - expected) <= tol) return true;
+            if (sameMantissa(v.value, expected, tol)) return true;
+        }
+    }
+    return false;
+}
+
+/**
+ * Do two numbers agree once a UNIT SCALE is allowed?
+ *
+ * A measured false positive is what this exists for, not a hypothetical: a
+ * fixture derives `4,200,000,000 x 0.006 = 25,200,000 = $25.2M` and declares
+ * `expected: 25.2`, because the scenario asks for the figure "in $M". The
+ * derivation works in dollars and the expectation in millions. Nothing in the
+ * file states the unit in a machine-readable way, so demanding exact agreement
+ * reports a correct fixture as broken.
+ *
+ * **The weakening this accepts, stated rather than buried.** A real defect that
+ * happens to be a pure power of ten away — `0.85` written where `8.5` is meant —
+ * is no longer caught by THIS check. It is a narrow hole: a transcription or
+ * arithmetic error almost always changes the digit sequence, and the
+ * self-consistency check above still reads the derivation on its own terms,
+ * where no scale tolerance applies at all. The alternative was worse: a check
+ * that fires on every unit-scaled fixture is a check that gets suppressed.
+ *
+ * Bounded to 10^±12 so an unrelated number cannot be dragged into agreement by
+ * an arbitrarily large exponent.
+ */
+function sameMantissa(a: number, b: number, tolerance: number): boolean {
+    if (a === 0 || b === 0) return false;
+    const ratio = Math.abs(a / b);
+    const exp = Math.round(Math.log10(ratio));
+    if (!Number.isFinite(exp) || Math.abs(exp) > 12 || exp === 0) return false;
+    const scaled = a / 10 ** exp;
+    return Math.abs(scaled - b) <= Math.max(tolerance, Math.abs(b) * 1e-9);
+}

package/src/scripts/_lib/arm_ranking.ts

@@ -0,0 +1,62 @@
+/**
+ * Arm ranking metrics (`road-to-runtime-context-floors` step 4.2).
+ *
+ * `tokens` stays the default and `cost-per-solved` becomes AVAILABLE — not a
+ * replacement. The reason it has to exist at all is the same one behind the
+ * mandatory cache fields: an arm can reduce token volume and cost more, because
+ * rewriting a prefix pays the cache-write rate rather than the cache-read rate.
+ * A comparison that can only rank on tokens cannot see that.
+ *
+ * The reason it must NOT become the default is the sibling risk: a single
+ * mandatory score invites tuning the score. Keeping both available, and keeping
+ * the cache ratio diagnostic rather than scored, is what stops this from being
+ * the Goodhart shape that `road-to-cache-economy`'s falsified C-5 already
+ * demonstrated for token count.
+ */
+
+export const RANKING_METRICS = ['tokens', 'cost-per-solved'] as const;
+export type RankingMetric = (typeof RANKING_METRICS)[number];
+export const DEFAULT_RANKING_METRIC: RankingMetric = 'tokens';
+
+export interface ArmResult {
+    arm: string;
+    /** Total tokens consumed by the arm across the run. */
+    tokens: number;
+    /** Total cost in USD. */
+    cost_usd: number;
+    /** Tasks the arm actually solved — the denominator of cost-per-solved. */
+    solved: number;
+}
+
+export interface RankedArm extends ArmResult {
+    /** The value ranked on. `null` when the metric is undefined for this arm. */
+    score: number | null;
+    /** Present only when `score` is null. */
+    reason?: string;
+}
+
+export function isRankingMetric(v: unknown): v is RankingMetric {
+    return typeof v === 'string' && (RANKING_METRICS as readonly string[]).includes(v);
+}
+
+function score(arm: ArmResult, metric: RankingMetric): { score: number | null; reason?: string } {
+    if (metric === 'tokens') return { score: arm.tokens };
+    if (arm.solved === 0) {
+        // Not Infinity and not 0: an arm that solved nothing has no
+        // cost-per-solved, and ranking it as "infinitely expensive" would be a
+        // number nobody measured.
+        return { score: null, reason: 'the arm solved nothing, so cost-per-solved is undefined' };
+    }
+    return { score: arm.cost_usd / arm.solved };
+}
+
+/**
+ * Rank ascending — lower is better under both metrics. Arms with an undefined
+ * score sort last, in input order, and carry their reason.
+ */
+export function rankArms(arms: readonly ArmResult[], metric: RankingMetric = DEFAULT_RANKING_METRIC): RankedArm[] {
+    const scored: RankedArm[] = arms.map((a) => ({ ...a, ...score(a, metric) }));
+    const defined = scored.filter((a) => a.score !== null).sort((a, b) => (a.score as number) - (b.score as number) || a.arm.localeCompare(b.arm));
+    const undef = scored.filter((a) => a.score === null);
+    return [...defined, ...undef];
+}

package/src/scripts/_lib/asset_delivery_ledger.ts

@@ -0,0 +1,303 @@
+/**
+ * Per-asset delivery ledger — which assets produce the standing payload
+ * (`road-to-delivered-cost-truth` step 2.1).
+ *
+ * `check_preamble_payload_budget` measures three BUCKET totals and refuses
+ * growth. It cannot say which asset inside a bucket is producing the cost, so a
+ * reduction effort has a number and no target. This module ranks the assets.
+ *
+ * WHAT "DELIVERY" MEANS PER BUCKET, because the two are not the same shape:
+ *
+ * - a RULE in the standing set delivers its whole body on every spawn;
+ * - a SKILL delivers only its catalogue line — `- <name>: <description>` — on
+ *   every spawn. Its body is loaded on activation, which is not standing cost
+ *   and is deliberately not counted here.
+ *
+ * Ranking the two together without that distinction would put every skill body
+ * above every rule and send a reduction effort at the wrong half of the tree.
+ *
+ * MEASUREMENT HONESTY. Each row states whether it was measured with the exact
+ * BPE tokenizer or the `chars/4` proxy, and a proxy reading within its own error
+ * margin of a threshold is reported `unresolved` rather than classified — the
+ * discipline `lint_token_budget_discipline` already applies to the rich band,
+ * reused here rather than reinvented.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { parseFrontmatter } from '../preamble_byte_census.js';
+import { gpt_tokens, gpt_tokens_proxy } from './token_count.js';
+
+/** Worst-case per-file error of the character proxy, as measured for the rich band. */
+export const PROXY_ERROR_MARGIN = 0.06;
+
+export type AssetKind = 'rule' | 'skill-catalogue-line';
+
+export interface AssetRow {
+    /** Repo-relative path of the asset. */
+    file: string;
+    /** Asset name as the preamble names it. */
+    name: string;
+    kind: AssetKind;
+    /** Tokens this asset contributes to EVERY spawn. */
+    tokens: number;
+    /**
+     * The same asset under the `chars/4` proxy.
+     *
+     * Carried alongside the BPE figure, not instead of it, because the payload
+     * gate counts chars/4 and reconciling a BPE total against a chars/4 total
+     * measures the METHODS, not the ledger. See {@link reconcile}.
+     */
+    proxy_tokens: number;
+    /** `exact` when the BPE tokenizer resolved, `proxy` otherwise. */
+    method: 'exact' | 'proxy';
+    /** Share of the ledger total. */
+    share: number;
+}
+
+export interface LedgerVerdict {
+    rows: AssetRow[];
+    total_tokens: number;
+    /** True only when EVERY row came from the exact tokenizer. */
+    exact_throughout: boolean;
+    by_kind: Record<AssetKind, { count: number; tokens: number; proxy_tokens: number }>;
+}
+
+/**
+ * Is a proxy reading too close to `threshold` to be classified?
+ *
+ * Symmetric, deliberately: the measured proxy error runs in BOTH directions
+ * (−5.3 % on the largest rich artifact), so a band that straddles the threshold
+ * yields no verdict rather than a confident wrong one.
+ */
+export function unresolvedAgainst(tokens: number, method: 'exact' | 'proxy', threshold: number): boolean {
+    if (method === 'exact') return false;
+    const margin = Math.ceil(tokens * PROXY_ERROR_MARGIN);
+    return tokens - margin <= threshold && tokens + margin > threshold;
+}
+
+/** Walk the standing rule directory. Each rule delivers its whole body. */
+export function measureRules(rulesDir: string, repoRoot: string): AssetRow[] {
+    if (!fs.existsSync(rulesDir)) return [];
+    const rows: AssetRow[] = [];
+    for (const entry of fs.readdirSync(rulesDir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+        const abs = path.join(rulesDir, entry.name);
+        const text = fs.readFileSync(abs, 'utf-8');
+        const count = gpt_tokens(text);
+        rows.push({
+            file: path.relative(repoRoot, abs),
+            name: entry.name.replace(/\.md$/, ''),
+            kind: 'rule',
+            tokens: count.tokens,
+            proxy_tokens: gpt_tokens_proxy(text).tokens,
+            method: count.exact ? 'exact' : 'proxy',
+            share: 0,
+        });
+    }
+    return rows;
+}
+
+/**
+ * Walk the skill catalogue. Each skill delivers ONE line, not its body.
+ *
+ * The line is built the same way `censusSkillsCatalog` builds it — `- <name>:
+ * <description>\n` — because a ledger that measured the body would rank a skill
+ * that is never activated above a rule that is always delivered.
+ */
+export function measureSkillCatalogue(skillsDir: string, repoRoot: string): AssetRow[] {
+    if (!fs.existsSync(skillsDir)) return [];
+    const rows: AssetRow[] = [];
+    for (const entry of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        const skillMd = path.join(skillsDir, entry.name, 'SKILL.md');
+        let text: string;
+        try {
+            text = fs.readFileSync(skillMd, 'utf-8');
+        } catch {
+            continue;
+        }
+        // The SAME parser the payload census uses, not a second reader of the
+        // same bytes. A regex version reconciled 17.1 % low because a folded
+        // multi-line `description:` truncates at the first newline.
+        const fm = parseFrontmatter(text);
+        const name = typeof fm.name === 'string' && fm.name.length > 0 ? fm.name : entry.name;
+        const description = typeof fm.description === 'string' ? fm.description : '';
+        const line = `- ${name}: ${description}\n`;
+        const count = gpt_tokens(line);
+        rows.push({
+            file: path.relative(repoRoot, skillMd),
+            name,
+            kind: 'skill-catalogue-line',
+            tokens: count.tokens,
+            proxy_tokens: gpt_tokens_proxy(line).tokens,
+            method: count.exact ? 'exact' : 'proxy',
+            share: 0,
+        });
+    }
+    return rows;
+}
+
+export function buildLedger(rulesDir: string, skillsDir: string, repoRoot: string): LedgerVerdict {
+    const rows = [...measureRules(rulesDir, repoRoot), ...measureSkillCatalogue(skillsDir, repoRoot)];
+    const total = rows.reduce((n, r) => n + r.tokens, 0);
+    for (const r of rows) r.share = total > 0 ? r.tokens / total : 0;
+    rows.sort((a, b) => b.tokens - a.tokens || a.file.localeCompare(b.file));
+
+    const byKind: Record<AssetKind, { count: number; tokens: number; proxy_tokens: number }> = {
+        rule: { count: 0, tokens: 0, proxy_tokens: 0 },
+        'skill-catalogue-line': { count: 0, tokens: 0, proxy_tokens: 0 },
+    };
+    for (const r of rows) {
+        byKind[r.kind].count += 1;
+        byKind[r.kind].tokens += r.tokens;
+        byKind[r.kind].proxy_tokens += r.proxy_tokens;
+    }
+    return { rows, total_tokens: total, exact_throughout: rows.every((r) => r.method === 'exact'), by_kind: byKind };
+}
+
+export interface Reconciliation {
+    kind: AssetKind;
+    bucket: string;
+    /** The ledger's chars/4 total — the SAME method the bucket uses. */
+    ledger_proxy_tokens: number;
+    /** The ledger's BPE total, reported for contrast, never reconciled against. */
+    ledger_exact_tokens: number;
+    bucket_tokens: number;
+    /** Absolute relative difference, like-for-like. */
+    drift: number;
+    within_margin: boolean;
+}
+
+/**
+ * Reconcile the ledger against the payload gate's own bucket totals.
+ *
+ * LIKE-FOR-LIKE, and this took a correction. The first cut compared the
+ * ledger's BPE total against the gate's `chars/4` bucket and set a 15 % margin
+ * to absorb the difference. That margin was GUESSED, which is the exact defect
+ * this roadmap's own budget file is careful about — and it did not even work:
+ * rules reconciled at 1.6 % while skill catalogue lines drifted 28.1 %, because
+ * `chars/4` overestimates short structured lines far more than it does prose.
+ * The 15 % would have hidden the rule drift and failed the skill drift, and
+ * neither verdict would have been about the ledger.
+ *
+ * So the ledger carries BOTH figures and reconciles the proxy against the
+ * proxy. What remains is real disagreement — a different corpus, a different
+ * line format, a missed file — which is what a reconciliation is for. The
+ * margin can then be tight, because two implementations of one arithmetic
+ * should agree closely or one of them is wrong.
+ */
+export const RECONCILE_MARGIN = 0.02;
+
+export function reconcile(
+    ledger: LedgerVerdict,
+    buckets: ReadonlyArray<{ name: string; tokens: number }>,
+): Reconciliation[] {
+    const map: Array<{ kind: AssetKind; bucket: string }> = [
+        { kind: 'rule', bucket: 'project-scope rules' },
+        { kind: 'skill-catalogue-line', bucket: 'preloaded skills catalog' },
+    ];
+    const out: Reconciliation[] = [];
+    for (const m of map) {
+        const bucket = buckets.find((b) => b.name === m.bucket);
+        if (bucket === undefined) continue;
+        const proxyTokens = ledger.by_kind[m.kind].proxy_tokens;
+        const drift =
+            bucket.tokens === 0 ? (proxyTokens === 0 ? 0 : 1) : Math.abs(proxyTokens - bucket.tokens) / bucket.tokens;
+        out.push({
+            kind: m.kind,
+            bucket: m.bucket,
+            ledger_proxy_tokens: proxyTokens,
+            ledger_exact_tokens: ledger.by_kind[m.kind].tokens,
+            bucket_tokens: bucket.tokens,
+            drift,
+            within_margin: drift <= RECONCILE_MARGIN,
+        });
+    }
+    return out;
+}
+
+// ─────────────────────────────────────────── growth attribution (step 2.2)
+
+export interface GrowthEntry {
+    name: string;
+    kind: AssetKind;
+    /** Positive = this asset grew or arrived. */
+    delta: number;
+    status: 'added' | 'grew' | 'shrank' | 'removed';
+}
+
+export interface GrowthAttribution {
+    /** Assets that grew or arrived, largest first. */
+    increases: GrowthEntry[];
+    /** Assets that shrank or left, largest saving first. */
+    decreases: GrowthEntry[];
+    net_delta: number;
+}
+
+/**
+ * Attribute a payload change to the assets that caused it (step 2.2).
+ *
+ * A ratchet that says "the payload grew past the ceiling" states a fact and
+ * leaves the reader to find the cause; the same refusal naming the asset and its
+ * token delta reads as a quantified saving instead of an obstacle. That is the
+ * whole difference this function buys, and it is a presentation difference with
+ * a real consequence: a refusal nobody can act on gets suppressed rather than
+ * fixed.
+ *
+ * Pure and order-independent — both sides are keyed on `kind:name`, so a
+ * reordered ledger produces the same attribution.
+ */
+export function attributeGrowth(before: readonly AssetRow[], after: readonly AssetRow[]): GrowthAttribution {
+    const key = (r: AssetRow): string => `${r.kind}:${r.name}`;
+    const b = new Map(before.map((r) => [key(r), r.tokens]));
+    const a = new Map(after.map((r) => [key(r), r.tokens]));
+
+    const entries: GrowthEntry[] = [];
+    for (const [k, tokens] of a) {
+        const prev = b.get(k);
+        const [kind, ...rest] = k.split(':');
+        const name = rest.join(':');
+        if (prev === undefined) {
+            entries.push({ name, kind: kind as AssetKind, delta: tokens, status: 'added' });
+        } else if (tokens !== prev) {
+            entries.push({ name, kind: kind as AssetKind, delta: tokens - prev, status: tokens > prev ? 'grew' : 'shrank' });
+        }
+    }
+    for (const [k, tokens] of b) {
+        if (a.has(k)) continue;
+        const [kind, ...rest] = k.split(':');
+        entries.push({ name: rest.join(':'), kind: kind as AssetKind, delta: -tokens, status: 'removed' });
+    }
+
+    const increases = entries.filter((e) => e.delta > 0).sort((x, y) => y.delta - x.delta || x.name.localeCompare(y.name));
+    const decreases = entries.filter((e) => e.delta < 0).sort((x, y) => x.delta - y.delta || x.name.localeCompare(y.name));
+    return { increases, decreases, net_delta: entries.reduce((n, e) => n + e.delta, 0) };
+}
+
+/**
+ * Render an attribution as the lines a refusing gate appends to its message.
+ *
+ * Capped, because a refusal listing 400 assets is as unactionable as one listing
+ * none — and the cap is stated rather than silent, so a reader knows the list is
+ * a head and not the whole story.
+ */
+export function renderAttribution(g: GrowthAttribution, limit = 5): string[] {
+    if (g.increases.length === 0 && g.decreases.length === 0) return [];
+    const out: string[] = [];
+    const sign = (n: number): string => (n >= 0 ? `+${String(n)}` : String(n));
+    out.push(`    net delivered-token change: ${sign(g.net_delta)} tok`);
+    if (g.increases.length > 0) {
+        out.push(`    grew or arrived (top ${String(Math.min(limit, g.increases.length))} of ${String(g.increases.length)}):`);
+        for (const e of g.increases.slice(0, limit)) {
+            out.push(`      ${sign(e.delta).padStart(7)} tok  ${e.name} (${e.kind}, ${e.status})`);
+        }
+    }
+    if (g.decreases.length > 0) {
+        out.push(`    shrank or left (top ${String(Math.min(limit, g.decreases.length))} of ${String(g.decreases.length)}):`);
+        for (const e of g.decreases.slice(0, limit)) {
+            out.push(`      ${sign(e.delta).padStart(7)} tok  ${e.name} (${e.kind}, ${e.status})`);
+        }
+    }
+    return out;
+}

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',
             };
         }
     }