@event4u/agent-config 9.29.0 → 9.31.0

package/src/scripts/measure_turn_end_gate.ts

@@ -0,0 +1,272 @@
+#!/usr/bin/env -S npx tsx
+/**
+ * `measure-turn-end-gate` — the false-positive pass roadmap
+ * `road-to-conformance-round5.md` § 3.4 asks for, run against a REAL
+ * transcript corpus rather than a hand-written one.
+ *
+ * Why this exists as a script and not as a number in a commit message: the
+ * roadmap asks to "record measured precision per detector", and a recorded
+ * figure nobody can re-derive is the same class of claim this whole round
+ * exists to remove. One command, same store, same numbers.
+ *
+ * What it measures, and what it deliberately does NOT:
+ *
+ *   · FIRE RATE of each detector PER TURN, over the last assistant text of the
+ *     turn — the population the shipped gate inspects. R2 finding 1: the first
+ *     version scored every assistant ENTRY and published the result as a
+ *     per-turn rate, which inflated the population ~8.6x and scored a
+ *     closing-paragraph detector over mid-turn prose.
+ *   · The independent scanner's own language total, printed for CONTEXT only.
+ *     It is not an agreement figure and no overlap is claimed from it: the two
+ *     instruments read different spans (its first prose line; this one strips
+ *     code/quotes/paths from the reply and then scores lead-first via the same
+ *     classifier), and this script does no per-turn matching between them.
+ *     R2 finding 7 removed the per-session min/max arithmetic that used to
+ *     report disjoint findings of equal count as full agreement.
+ *   · It does NOT compute recall against the 20 promissory occurrences the
+ *     round-5 audit reported. Those came from subagent transcript READING;
+ *     `conformance_scan.ts` states in its own header that promissory
+ *     closings are "deliberately NOT scanned", so there is no machine-
+ *     readable ground truth to score against. Claiming a recall figure here
+ *     would invent one.
+ *   · KNOWN RESIDUAL, R2 finding 8, not fixed here: this script re-derives the
+ *     language pin with `classify` per user entry, while the gate reads the pin
+ *     `language_mirror_hook` persisted — which also applies a system-locale
+ *     fallback and a keep-previous rule. Where those diverge, a turn can move
+ *     between "pinned de", "pinned en" and "no obligation", so detector B's
+ *     rate here is close to but not identical with the gate's. Reaching parity
+ *     means reusing `nextState`, which is a larger change than a measurement
+ *     correction and would itself need re-measuring.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/measure_turn_end_gate --store <dir> [--limit N]
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { classify, isSyntheticPrompt } from './language_mirror_hook.js';
+import { assistantText, scanSession, userText } from './conformance_scan.js';
+import { detectLanguage, detectPromissory } from './hooks/turn_end_gate_hook.js';
+
+interface Counts {
+    /**
+     * TURNS, not entries. R2 finding 1: the first version incremented a counter
+     * named `assistant_turns` on every assistant entry and ran both detectors on
+     * each one, while the gate only ever evaluates the LAST assistant text of a
+     * turn. A turn with k prose entries contributed k samples to the instrument
+     * and 1 to the gate, so the published "18.0% of turns" was a per-ENTRY rate
+     * wearing a per-turn label — and detector A, a closing-paragraph detector by
+     * construction, was being scored over mid-turn prose.
+     */
+    turns: number;
+    /** Assistant entries seen — kept only to show the ratio the old bug hid. */
+    assistant_entries: number;
+    promissory_fires: number;
+    language_fires: number;
+    /** The independent scanner's own per-session language total, for context. */
+    scanner_language: number;
+    sessions: number;
+}
+
+function sessionFiles(store: string, limit: number): string[] {
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(store).filter((f) => f.endsWith('.jsonl'));
+    } catch {
+        return [];
+    }
+    const withTime = entries.map((f) => {
+        const p = path.join(store, f);
+        let mtime = 0;
+        try {
+            mtime = fs.statSync(p).mtimeMs;
+        } catch {
+            /* unreadable — sorts last */
+        }
+        return { p, mtime };
+    });
+    withTime.sort((a, b) => b.mtime - a.mtime);
+    return withTime.slice(0, limit).map((e) => e.p);
+}
+
+export function measure(store: string, limit: number): Counts {
+    const c: Counts = {
+        turns: 0,
+        assistant_entries: 0,
+        promissory_fires: 0,
+        language_fires: 0,
+        scanner_language: 0,
+        sessions: 0,
+    };
+
+    for (const file of sessionFiles(store, limit)) {
+        let lines: string[];
+        try {
+            lines = fs.readFileSync(file, 'utf-8').split('\n').filter((l) => l.trim() !== '');
+        } catch {
+            continue;
+        }
+        c.sessions += 1;
+        const sessionId = path.basename(file).slice(0, 8);
+
+        // The independent scanner's own language total for this session,
+        // reported side by side and NOT as agreement — see the header for why
+        // no overlap is derivable from two totals (R2 finding 7).
+        //
+        // A throw is surfaced, not swallowed to zero: swallowing silently
+        // reclassified a whole session's fires as scanner-disagreements.
+        try {
+            c.scanner_language += scanSession(sessionId, lines).violations.filter(
+                (v) => v.check === 'language-pin',
+            ).length;
+        } catch (err) {
+            process.stderr.write(
+                `measure-turn-end-gate: scanSession failed for ${sessionId} — excluded from the scanner total: ${String(err)}\n`,
+            );
+        }
+
+        let pinned: 'de' | 'en' | 'und' = 'und';
+        // The LAST assistant text since the last genuine user prompt. This is
+        // the population the gate inspects; anything else is a different
+        // measurement wearing the same label (R2 finding 1).
+        let pendingReply: string | null = null;
+        let pendingPin: 'de' | 'en' | 'und' = 'und';
+
+        const scoreTurn = (): void => {
+            if (pendingReply === null) return;
+            c.turns += 1;
+            if (detectPromissory(pendingReply) !== null) c.promissory_fires += 1;
+            if (detectLanguage(pendingReply, pendingPin) !== null) c.language_fires += 1;
+            pendingReply = null;
+        };
+
+        for (const raw of lines) {
+            let entry: Record<string, unknown>;
+            try {
+                entry = JSON.parse(raw) as Record<string, unknown>;
+            } catch {
+                continue;
+            }
+
+            const u = userText(entry);
+            if (u !== null) {
+                // `isSyntheticPrompt`, the SAME filter the gate uses for the
+                // ordinal — not `isInjectedBody`. R2 round 2, finding 10: the
+                // two filters classify differently, and any entry they disagree
+                // about shifts this instrument's turn boundary away from the
+                // gate's own. Population parity is the entire point of this
+                // correction, so the filter has to be the same one.
+                if (!isSyntheticPrompt(u)) {
+                    scoreTurn(); // the previous turn ends here
+                    const verdict = classify(u);
+                    if (verdict.language !== 'und') pinned = verdict.language;
+                }
+                continue;
+            }
+
+            const a = assistantText(entry);
+            if (a === null || a.trim() === '') continue;
+            c.assistant_entries += 1;
+            // Overwrite: only the last one in the turn is the gate's input.
+            pendingReply = a;
+            pendingPin = pinned;
+        }
+        scoreTurn(); // the transcript's final turn
+    }
+
+    return c;
+}
+
+export function render(c: Counts): string {
+    const pct = (n: number): string => (c.turns === 0 ? '0.0' : ((100 * n) / c.turns).toFixed(1));
+    return [
+        `measure-turn-end-gate · ${c.sessions} sessions · ${c.turns} turns · ${c.assistant_entries} assistant entries`,
+        '',
+        `  detector A (promissory)  fires on ${c.promissory_fires} turns  (${pct(c.promissory_fires)}%)`,
+        `  detector B (language)    fires on ${c.language_fires} turns  (${pct(c.language_fires)}%)`,
+        '',
+        '  Rates are per TURN, over the last assistant text of each turn — the same',
+        '  population the shipped gate inspects. The entry count is printed beside',
+        '  the turn count because the first version of this script scored every',
+        '  assistant ENTRY and labelled the result per-turn; the gap between the two',
+        '  numbers is the size of that error.',
+        '',
+        `  For context only, the independent scanner's own language total: ${c.scanner_language}`,
+        '    NOT an agreement figure. The two instruments read different spans (its',
+        '    first prose line vs. this stripped, lead-first-scored reply) and this',
+        '    script does no per-turn matching between them, so no overlap can be claimed from these',
+        '    two totals — the previous version claimed one from per-session min/max',
+        '    arithmetic, which reports disjoint findings of equal count as full',
+        '    agreement.',
+        '',
+        '  No recall figure for detector A: promissory closings are not machine-',
+        '  scanned anywhere in this tree, so there is no ground truth to score.',
+    ].join('\n');
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    let store = '';
+    let limit = 30;
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] === '--store' && argv[i + 1] !== undefined) {
+            store = argv[i + 1]!;
+            i += 1;
+        } else if (argv[i] === '--limit' && argv[i + 1] !== undefined) {
+            // R2 finding 15: an unvalidated parseInt made `--limit abc` yield
+            // NaN, `slice(0, NaN)` return nothing, and the script exit 2 with
+            // "no .jsonl sessions under <store>" — a real input error reported
+            // as a missing corpus.
+            const parsed = Number.parseInt(argv[i + 1]!, 10);
+            if (!Number.isFinite(parsed) || parsed < 1) {
+                process.stderr.write(
+                    `measure-turn-end-gate: --limit must be a positive integer, got ${JSON.stringify(argv[i + 1])}\n`,
+                );
+                return 2;
+            }
+            limit = parsed;
+            i += 1;
+        }
+    }
+    if (!store) {
+        process.stderr.write('measure-turn-end-gate: --store <transcript dir> is required\n');
+        return 2;
+    }
+    const counts = measure(store, limit);
+    if (counts.sessions === 0) {
+        // A measurement over zero sessions that exits 0 is the repo's own
+        // "gates that scan nothing" failure. Refuse instead.
+        process.stderr.write(`measure-turn-end-gate: no .jsonl sessions under ${store}\n`);
+        return 2;
+    }
+    process.stdout.write(`${render(counts)}\n`);
+    return 0;
+}
+
+// Bundle-safety, same guard as the sibling hook. R2 finding 15: a substring
+// test on argv[1] auto-runs the module when esbuild inlines it into a bundle,
+// where every module shares the bundle's `import.meta.url`.
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+    if (typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__) {
+        return false;
+    }
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/orchestration_record.ts

@@ -13,9 +13,10 @@
  *     [--tiers sonnet,opus] [--agent-combo implementer,judge] [--wall-clock-ms 18500] [--dispatch-outcome DONE] \
  *     [--first-pass-success true|false] [--escalated true|false] \
  *     [--init-tokens 1200] [--payload-hash <hex8-64>] [--lookup-class definition|references|string-existence|report-run] \
- *     [--route-taken primitive|subagent] [--budget-hit true|false] [--correctness-match true|false] \
+ *     [--route-taken primitive|subagent|ask] [--budget-hit true|false] [--correctness-match true|false] \
  *     [--cache-hit true|false] [--origin lean-init-2026] \
  *     [--rules-carried 32] [--rules-used 5] \
+ *     [--work-tokens 41000] [--floor-provenance measured|estimated] \
  *     [--capsule-emitted true|false] [--capsule-entries 9] \
  *     [--watermark-step 8] [--saturation-step 4] [--trigger-arm-earlier watermark|saturation|tie] \
  *     [--dir <audit-dir>] [--dry-run]
@@ -144,6 +145,8 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         origin: str(flags, 'origin'),
         rules_carried: int(flags, 'rules-carried'),
         rules_used: int(flags, 'rules-used'),
+        work_tokens: int(flags, 'work-tokens'),
+        floor_provenance: str(flags, 'floor-provenance') as Provenance | undefined,
         capsule_emitted: bool(flags, 'capsule-emitted'),
         capsule_entries: int(flags, 'capsule-entries'),
         watermark_step: int(flags, 'watermark-step'),

package/src/scripts/rebuild_hook_bundle.ts

@@ -47,6 +47,7 @@ import { fileURLToPath } from "node:url";
 
 import { check } from "./check_hook_bundle_freshness.js";
 
+// ledger-exempt: self-heal builder, not a checker — one build → probe → atomic-rename transaction whose outcome is a single aggregate heal verdict; the per-source staleness accounting lives in check_hook_bundle_freshness, which carries the ledger.
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT = path.resolve(HERE, "..", "..");
 const LIVE_REL = path.join("dist", "hooks", "dispatch.js");

package/src/scripts/report_carrier_divergence.ts

@@ -35,16 +35,30 @@
  * ignored, which is the failure `check-rule-invariants` already paid for once.
  * The point is that the condition becomes VISIBLE, not that it becomes illegal.
  *
- * THE THREE CLASSES, AND WHICH ONE A READER MUST ACT ON
- * ----------------------------------------------------
- *   body-diff        the two carriers deliver different TEXT. This is the class
+ * THE FOUR CLASSES, AND WHICH ONE A READER MUST ACT ON
+ * ---------------------------------------------------
+ *   body-diff        the two carriers deliver different PROSE. This is the class
  *                    round 5's contradiction lived in, and the only one that
- *                    needs a decision. Precedence when it appears: the project
- *                    projection is generated from `src/` at the current commit,
- *                    so it is the newer copy and it wins; the global install is
- *                    a release snapshot. Printed with the report so the
- *                    precedence is read at the moment it matters rather than
- *                    looked up.
+ *                    needs a decision. What the host does about it: NOTHING —
+ *                    both copies load at launch with the same priority and no
+ *                    precedence marker between them, so the divergence is
+ *                    binding-undefined rather than resolved in either
+ *                    direction. Cited, not inferred:
+ *                    `agents/evidence/analysis/claude-code-rules-dir-contract.md`
+ *                    (host 2.1.226, first-party observation plus the host's own
+ *                    documentation). The project copy is the NEWER text, which
+ *                    is a fact about recency and not a precedence rule — the
+ *                    earlier wording of this header called it a win, and a
+ *                    reader acting on that would have believed the host resolves
+ *                    something it does not.
+ *   frontmatter-only the prose is byte-identical and only the metadata block
+ *                    differs. The host delivers the prose without that block, so
+ *                    nothing a reader must act on reaches the model differently.
+ *                    Split out because it was, measured, the ENTIRE content of
+ *                    the `body-diff` class: 109 of 109 on 2026-08-10. Left inside
+ *                    body-diff it manufactured the report's only actionable
+ *                    class out of a metadata difference — the same mistake the
+ *                    `unreadable` branch below already refuses to make.
  *   provenance-only  identical after removing the two installer ownership keys.
  *                    Structural, expected, and decided against closing —
  *                    `agents/settings/contexts/dedup-reachability-refusal.md`.
@@ -69,7 +83,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
-import { comparePair, type PairVerdict } from './_lib/carrier_divergence.js';
+import { comparePair, type PairVerdict, proseEqual } from './_lib/carrier_divergence.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -103,6 +117,13 @@ export interface CarrierDivergence {
     shared: number;
     identical: string[];
     provenanceOnly: string[];
+    /**
+     * Prose byte-identical, metadata block different. A real byte difference — so
+     * `comparePair` still calls it `body-diff` and the dedup predicate is
+     * unchanged — but not a difference in what the host delivers, so it is not
+     * something a reader has to act on.
+     */
+    frontmatterOnly: string[];
     bodyDiff: string[];
     projectOnly: string[];
     globalOnly: string[];
@@ -171,6 +192,7 @@ export function compareCarriers(
         shared: 0,
         identical: [],
         provenanceOnly: [],
+        frontmatterOnly: [],
         bodyDiff: [],
         projectOnly: [],
         globalOnly: [],
@@ -196,11 +218,12 @@ export function compareCarriers(
         }
         out.shared += 1;
         let verdict: PairVerdict;
+        let proseSame: boolean;
         try {
-            verdict = comparePair(
-                fs.readFileSync(path.join(projectDir, rule)),
-                fs.readFileSync(path.join(globalDir, rule)),
-            );
+            const projectCopy = fs.readFileSync(path.join(projectDir, rule));
+            const globalCopy = fs.readFileSync(path.join(globalDir, rule));
+            verdict = comparePair(projectCopy, globalCopy);
+            proseSame = proseEqual(projectCopy.toString('utf-8'), globalCopy.toString('utf-8'));
         } catch {
             // An unreadable copy is not a body difference and must not be
             // reported as one — a permission error would otherwise manufacture
@@ -213,6 +236,7 @@ export function compareCarriers(
         }
         if (verdict === 'identical') out.identical.push(rule);
         else if (verdict === 'provenance-only') out.provenanceOnly.push(rule);
+        else if (proseSame) out.frontmatterOnly.push(rule);
         else out.bodyDiff.push(rule);
     }
     return out;
@@ -244,7 +268,8 @@ export function render(d: CarrierDivergence): string {
     lines.push(`  shared rule names                    ${d.shared}`);
     lines.push(`    byte-identical                     ${d.identical.length}`);
     lines.push(`    differ ONLY in the install stamp   ${d.provenanceOnly.length}`);
-    lines.push(`    differ in BODY                     ${d.bodyDiff.length}`);
+    lines.push(`    differ ONLY in frontmatter         ${d.frontmatterOnly.length}`);
+    lines.push(`    differ in PROSE                    ${d.bodyDiff.length}`);
     if (d.unreadable.length > 0) {
         lines.push(`    unreadable on one side             ${d.unreadable.length}  (${d.unreadable.join(', ')})`);
         lines.push('      Not counted as shared and NOT a body difference — a dangling entry is');
@@ -255,16 +280,34 @@ export function render(d: CarrierDivergence): string {
     lines.push('');
 
     if (d.bodyDiff.length > 0) {
-        lines.push('  BODY DIVERGENCE — the two carriers deliver different text for these rules.');
-        lines.push('  Both copies reach the model, with no precedence marker between them, so a');
-        lines.push('  claim one copy retracts can be re-asserted by the other. PRECEDENCE: the');
-        lines.push('  project projection is generated from src/ at this commit and wins; the');
-        lines.push('  global install is a release snapshot. Close it by reinstalling the global');
-        lines.push('  copy, or by reading the project copy as authoritative.');
+        lines.push('  PROSE DIVERGENCE — the two carriers deliver different governed text for');
+        lines.push('  these rules. Both copies reach the model, and the host resolves NOTHING:');
+        lines.push('  rules without a `paths` key load at launch with the same priority as');
+        lines.push('  CLAUDE.md, with no precedence marker between the layers, so a claim one');
+        lines.push('  copy retracts can be re-asserted by the other and which text binds is');
+        lines.push('  UNDEFINED. Cited, not inferred — agents/evidence/analysis/');
+        lines.push('  claude-code-rules-dir-contract.md (host 2.1.226, the host\'s own docs plus');
+        lines.push('  a first-party observation). The project copy is the NEWER text, which is a');
+        lines.push('  fact about recency and NOT a host precedence rule: close the divergence by');
+        lines.push('  reinstalling the global copy, or decide which text binds — do not assume');
+        lines.push('  the newer one already won.');
         for (const r of d.bodyDiff) lines.push(`    - ${r}`);
         lines.push('');
     }
 
+    if (d.frontmatterOnly.length > 0) {
+        lines.push(`  ${String(d.frontmatterOnly.length)} pair(s) differ ONLY in the frontmatter block — prose byte-identical.`);
+        lines.push('  Not a governed-text difference and nothing to act on: the host delivers the');
+        lines.push('  prose without that block, and none of the keys in it is one this host reads');
+        lines.push('  (claude-code-rules-dir-contract.md: it reads `paths`, and agent-config\'s own');
+        lines.push('  vocabulary is not read at all). Two writers, two frontmatter policies —');
+        lines.push('  `generate-tools` emits `paths` where a rule is path-scoped and nothing');
+        lines.push('  otherwise; `install.ts` writes the full vocabulary plus its ownership stamp.');
+        lines.push('  Reported as a count on purpose: naming every pair would bury the class');
+        lines.push('  above, which is the one a reader must act on.');
+        lines.push('');
+    }
+
     if (d.provenanceOnly.length > 0) {
         lines.push(`  ${String(d.provenanceOnly.length)} pair(s) differ only by the installer's package:/source_path: stamp.`);
         lines.push('  Not a content difference and NOT a defect: install.ts stamps every installed');
@@ -302,9 +345,14 @@ export function render(d: CarrierDivergence): string {
 
     if (d.bodyDiff.length === 0) {
         lines.push('');
-        lines.push('  No body divergence. The condition is transient — it returns whenever the');
-        lines.push('  checkout moves ahead of the installed release — so this is a reading of');
-        lines.push('  right now, not a property of the repo. Re-run it, do not cite it.');
+        lines.push('  No prose divergence — no rule\'s governed text differs between the carriers.');
+        lines.push('  The condition is transient — it returns whenever the checkout moves ahead of');
+        lines.push('  the installed release — so this is a reading of right now, not a property of');
+        lines.push('  the repo. Re-run it, do not cite it. That holds doubly here: the reading also');
+        lines.push('  depends on WHICH GENERATION of the emitter produced the project tree (a');
+        lines.push('  frontmatter-carrying symlink tree and a frontmatter-less real-file tree');
+        lines.push('  classify the same commit differently), so a number from another checkout is');
+        lines.push('  not comparable to this one.');
     }
     return lines.join('\n');
 }