@event4u/agent-config 9.28.0 → 9.30.0

package/src/scripts/lint_rule_enforcement_declaration.ts

@@ -0,0 +1,347 @@
+#!/usr/bin/env node
+/**
+ * `enforced_by`-declaration ratchet — a NEW rule states its enforcement, or
+ * states the gap; only the legacy set may stay silent.
+ *
+ * The enforcement-coverage number moved backwards across 9.23→9.29 (13.5% →
+ * 12.9%) for exactly one reason: rules were added faster than backstops, and
+ * nothing required a new rule to even *declare* where it stands. Coverage
+ * itself cannot be gated (whether a backstop is buildable is a per-rule
+ * judgment), but the *declaration* can: `enforced_by:` accepts an honest
+ * `none`, so requiring the key costs a new rule's author one line of truth,
+ * never a mechanism.
+ *
+ * Ratchet shape (the established baseline-the-legacy pattern):
+ *   - The 84 rules that predate this gate are recorded in
+ *     `src/config/rule-enforcement-baseline.json`. They stay legal while
+ *     undeclared; the list may only shrink.
+ *   - A rule NOT in the baseline must carry `enforced_by:` — a validator/
+ *     hook/test/observer reference, or the explicit `none`.
+ *   - A rule declaring `none` must also state the gap in its body (the
+ *     `enforced_by: none` honesty convention the existing none-rules use) —
+ *     a frontmatter-only `none` nobody reads is a silent gap again.
+ *   - A baseline entry whose rule gained a declaration (or was deleted) must
+ *     leave the baseline in the same change — a stale entry is a freed slot
+ *     a later silent rule could hide in.
+ *
+ * Deliberately NOT checked here: whether a declared validator resolves, is
+ * wired, or can fail a build — that is `check_enforcement_coverage`'s job
+ * (resolution), and `check_backstop_debt`'s (red backstops). This gate owns
+ * the declaration boundary only, on `src/rules/` only — gate scripts and
+ * their `// ledger-exempt:` markers are a different surface
+ * (`check_gate_completeness`) and are not read here.
+ *
+ * **Where the baseline lives, and why it ships.** `src/config/` is a directory
+ * entry in `package.json`'s `files[]`, so `rule-enforcement-baseline.json` is in
+ * the published tarball alongside its nine siblings — `gate-violation-baselines`,
+ * the four `*-budget` files, and the rest. All ten are repo-internal gate state:
+ * this gate is their consumer, it ships too (via `src/scripts/`), and in a
+ * consumer checkout it finds no `src/rules/` and does nothing. That is inert, not
+ * orphaned, and it is the pre-existing shape rather than something this file
+ * introduced — an automated review flagged it as "ships into dist with no
+ * consumer", which is doubly wrong: the file is not in `dist/` at all, and the
+ * consumer is this script. Whether ten repo-internal baselines belong in the
+ * tarball is a real packaging question; it is one decision about ten files, not a
+ * carve-out for the tenth.
+ *
+ * CLI contract: exit 0 = clean, 1 = a finding (or dead scan root), 2 = usage.
+ * `--quiet` mutes the clean-path line; `--root <dir>` re-roots for fixtures;
+ * `--write-baseline` records the current undeclared set (bootstrap/re-anchor —
+ * a deliberate maintainer act, never CI).
+ */
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { read_frontmatter } from './check_enforcement_coverage.js';
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { is_kernel_rule } from './_lib/kernel_rules.js';
+import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
+
+const GATE = 'lint_rule_enforcement_declaration';
+
+const QUIET = process.argv.slice(2).includes('--quiet');
+
+const _HERE = path.resolve(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+const RULES_RELATIVE = path.join('src', 'rules');
+const BASELINE_RELATIVE = path.join('src', 'config', 'rule-enforcement-baseline.json');
+
+function _rootOverride(argv: readonly string[]): string | null {
+    const i = argv.indexOf('--root');
+    const value = i === -1 ? undefined : argv[i + 1];
+    return value === undefined ? null : path.resolve(value);
+}
+
+/** enforced_by as declared, normalised to a string array; null = absent. */
+function _declaration(fm: Record<string, string | string[]>): string[] | null {
+    const raw = fm['enforced_by'];
+    if (raw === undefined) return null;
+    const list = Array.isArray(raw) ? raw : [raw];
+    return list.length === 0 ? null : list;
+}
+
+/** The body must state a `none` gap in prose — the honesty convention. */
+function _bodyStatesNone(text: string): boolean {
+    const end = text.indexOf('\n---\n', 4);
+    const body = end === -1 ? text : text.slice(end + 5);
+    return body.includes('enforced_by: none') || body.includes('`enforced_by: none`');
+}
+
+function _readBaseline(root: string): string[] | null {
+    try {
+        const parsed: unknown = JSON.parse(fs.readFileSync(path.join(root, BASELINE_RELATIVE), 'utf-8'));
+        if (!Array.isArray(parsed) || !parsed.every((e) => typeof e === 'string')) return null;
+        return parsed as string[];
+    } catch {
+        return null;
+    }
+}
+
+interface Findings {
+    findings: string[];
+    undeclared: string[];
+}
+
+function _scan(root: string, baseline: ReadonlySet<string>, ledger: GateLedger | null): Findings {
+    const rulesDir = path.join(root, RULES_RELATIVE);
+    const files = fs
+        .readdirSync(rulesDir)
+        .filter((f) => f.endsWith('.md'))
+        .sort();
+    ledger?.plan(files);
+
+    const findings: string[] = [];
+    const undeclared: string[] = [];
+    const seen = new Set<string>();
+
+    for (const file of files) {
+        seen.add(file);
+        const text = fs.readFileSync(path.join(rulesDir, file), 'utf-8');
+        const decl = _declaration(read_frontmatter(text));
+
+        if (decl === null) {
+            undeclared.push(file);
+            if (baseline.has(file)) {
+                ledger?.outOfScope(file, 'declared_exemption');
+                continue;
+            }
+            const f =
+                `src/rules/${file}  declares no \`enforced_by:\`. A new rule states its enforcement ` +
+                `(validator:/hook:/test:/observer:) or states the gap (\`none\` + a body line saying so). ` +
+                `The baseline covers only rules that predate this gate.`;
+            findings.push(f);
+            ledger?.fail(file, f);
+            continue;
+        }
+
+        // Kernel rules are exempt from the body-prose convention, derived from
+        // _lib/kernel_rules.ts (never a hardcoded list) so the exemption closes
+        // itself the moment a rule leaves the kernel — the same self-closing
+        // shape validate_frontmatter uses for obligation_frequency. Their
+        // projected bytes are stability-gated, so requiring a prose line here
+        // would force an un-editable edit.
+        if (decl.includes('none') && !_bodyStatesNone(text) && !is_kernel_rule(file)) {
+            const f =
+                `src/rules/${file}  declares \`enforced_by: none\` in frontmatter but never states the gap ` +
+                `in its body — the honesty convention is one prose line naming \`enforced_by: none\`, so a ` +
+                `reader of the rule sees the gap, not only a machine.`;
+            findings.push(f);
+            ledger?.fail(file, f);
+            continue;
+        }
+
+        ledger?.complete(file);
+    }
+
+    for (const entry of [...baseline].sort()) {
+        if (!seen.has(entry)) {
+            findings.push(
+                `${BASELINE_RELATIVE}  baseline entry \`${entry}\` names no existing rule — remove it in the ` +
+                    `same change that renamed/deleted the rule. A stale entry is a freed slot a later ` +
+                    `undeclared rule could silently occupy.`,
+            );
+            continue;
+        }
+        if (!undeclared.includes(entry)) {
+            findings.push(
+                `${BASELINE_RELATIVE}  baseline entry \`${entry}\` now declares \`enforced_by:\` — remove it ` +
+                    `from the baseline in the same change. The list may only shrink.`,
+            );
+        }
+    }
+
+    return { findings, undeclared };
+}
+
+/** Prove against the real CLI that the ratchet rejects what it must. */
+export function selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'lred-selftest-'));
+    const declared = '---\ntype: "auto"\nenforced_by:\n  - "validator:src/scripts/example.ts"\n---\n\n# R\n\nBody.\n';
+    const noneHonest =
+        '---\ntype: "auto"\nenforced_by:\n  - "none"\n---\n\n# R\n\nThis rule ships `enforced_by: none` — the obligation is model-carried.\n';
+    const noneSilent = '---\ntype: "auto"\nenforced_by:\n  - "none"\n---\n\n# R\n\nBody with no gap statement.\n';
+    const silent = '---\ntype: "auto"\n---\n\n# R\n\nBody.\n';
+
+    const seed = (name: string, rules: Record<string, string>, baseline: string[]): string => {
+        const root = path.join(tmp, name);
+        fs.mkdirSync(path.join(root, RULES_RELATIVE), { recursive: true });
+        fs.mkdirSync(path.join(root, 'src', 'config'), { recursive: true });
+        for (const [file, text] of Object.entries(rules)) {
+            fs.writeFileSync(path.join(root, RULES_RELATIVE, file), text, 'utf-8');
+        }
+        fs.writeFileSync(path.join(root, BASELINE_RELATIVE), `${JSON.stringify(baseline, null, 2)}\n`, 'utf-8');
+        return root;
+    };
+    const run = (cwd: string): number =>
+        runGateCli(REPO_ROOT, `src/scripts/${GATE}.ts`, ['--quiet', '--root', cwd], REPO_ROOT);
+
+    try {
+        return runSelfTest({
+            gate: GATE,
+            minCases: 6,
+            minRejectCases: 4,
+            cases: [
+                {
+                    name: 'a declared new rule and a baselined legacy rule pass',
+                    expect: 'accept',
+                    run: () => run(seed('clean', { 'a.md': declared, 'legacy.md': silent }, ['legacy.md'])),
+                },
+                {
+                    name: 'an honest none (frontmatter + body gap line) passes',
+                    expect: 'accept',
+                    run: () => run(seed('none-honest', { 'a.md': noneHonest }, [])),
+                },
+                {
+                    name: 'a NEW rule without enforced_by is rejected',
+                    expect: 'reject',
+                    run: () => run(seed('new-silent', { 'a.md': silent }, [])),
+                },
+                {
+                    name: 'a none declaration without the body gap line is rejected',
+                    expect: 'reject',
+                    run: () => run(seed('none-silent', { 'a.md': noneSilent }, [])),
+                },
+                {
+                    name: 'a stale baseline entry (rule deleted/renamed) is rejected',
+                    expect: 'reject',
+                    run: () => run(seed('stale', { 'a.md': declared }, ['gone.md'])),
+                },
+                {
+                    name: 'a baseline entry whose rule gained a declaration is rejected until removed',
+                    expect: 'reject',
+                    run: () => run(seed('shrink', { 'a.md': declared }, ['a.md'])),
+                },
+                {
+                    name: 'a dead scan root is rejected, never passed as nothing-to-check',
+                    expect: 'reject',
+                    run: () => run(path.join(tmp, 'dead-root-does-not-exist')),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+function main(): number {
+    const argv = process.argv.slice(2);
+    if (argv.includes('--self-test')) {
+        return selfTest();
+    }
+    const root = _rootOverride(argv) ?? REPO_ROOT;
+
+    const rulesDir = path.join(root, RULES_RELATIVE);
+    let isDir = false;
+    try {
+        isDir = fs.statSync(rulesDir).isDirectory();
+    } catch {
+        isDir = false;
+    }
+    if (!isDir) {
+        process.stderr.write(`❌  ${GATE}: rules dir not found at ${RULES_RELATIVE} — the scan root is dead.\n`);
+        return 1;
+    }
+
+    if (argv.includes('--write-baseline')) {
+        const { undeclared } = _scan(root, new Set(), null);
+        fs.writeFileSync(
+            path.join(root, BASELINE_RELATIVE),
+            `${JSON.stringify(undeclared, null, 2)}\n`,
+            'utf-8',
+        );
+        process.stdout.write(`${GATE}: baseline written — ${undeclared.length} legacy undeclared rule(s).\n`);
+        return 0;
+    }
+
+    const baseline = _readBaseline(root);
+    if (baseline === null) {
+        process.stderr.write(
+            `❌  ${GATE}: ${BASELINE_RELATIVE} missing or not a string array — run --write-baseline once ` +
+                `(a deliberate maintainer act) or restore the committed file.\n`,
+        );
+        return 1;
+    }
+
+    const ledger = new GateLedger(GATE);
+    const { findings } = _scan(root, new Set(baseline), ledger);
+
+    try {
+        reportScanned({
+            gate: GATE,
+            scanned: fs.readdirSync(rulesDir).filter((f) => f.endsWith('.md')).length,
+            units: 'rule file(s)',
+            roots: [RULES_RELATIVE],
+        });
+    } catch (e) {
+        if (e instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${e.message}\n`);
+            return 1;
+        }
+        throw e;
+    }
+    ledger.report();
+
+    if (findings.length > 0) {
+        for (const f of findings) {
+            process.stderr.write(`❌  ${f}\n`);
+        }
+        return 1;
+    }
+    if (!QUIET) {
+        process.stdout.write(
+            `✅  ${GATE}: every non-baselined rule declares its enforcement (baseline: ${baseline.length}, shrink-only).\n`,
+        );
+    }
+    return 0;
+}
+
+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 argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv1;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}
+
+export { GATE, REPO_ROOT, BASELINE_RELATIVE, main };

package/src/scripts/measure_turn_end_gate.ts

@@ -0,0 +1,194 @@
+#!/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 over every assistant turn in the window.
+ *   · For detector B, the CROSS-TAB against `conformance_scan`'s own
+ *     independent language check. That scanner reads only the first prose
+ *     line and this detector reads the whole stripped reply, so the two are
+ *     related instruments, not the same one — which is exactly what makes
+ *     the disagreement cells informative.
+ *   · 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.
+ *
+ * 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 { classify } from './language_mirror_hook.js';
+import { assistantText, isInjectedBody, scanSession, userText } from './conformance_scan.js';
+import { detectLanguage, detectPromissory } from './hooks/turn_end_gate_hook.js';
+
+interface Counts {
+    assistant_turns: number;
+    promissory_fires: number;
+    language_fires: number;
+    /** Detector B fired AND the scanner also flagged that session-turn. */
+    language_agree: number;
+    /** Detector B fired where the scanner saw nothing — candidate false positives. */
+    language_only: 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 = {
+        assistant_turns: 0,
+        promissory_fires: 0,
+        language_fires: 0,
+        language_agree: 0,
+        language_only: 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 scanner's independent verdict for this session, keyed by the
+        // timestamp-free count of language violations. Used only as a
+        // cross-tab total, never as ground truth for this detector.
+        let scannerLanguage = 0;
+        try {
+            scannerLanguage = scanSession(sessionId, lines).violations.filter(
+                (v) => v.check === 'language-pin',
+            ).length;
+        } catch {
+            scannerLanguage = 0;
+        }
+
+        let pinned: 'de' | 'en' | 'und' = 'und';
+        let myLanguage = 0;
+
+        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) {
+                // A background-task notification occupies the user role but is
+                // not a chat message — the exact shape that made the language
+                // defect invisible. It must never move the pin.
+                if (!isInjectedBody(u)) {
+                    const verdict = classify(u);
+                    if (verdict.language !== 'und') pinned = verdict.language;
+                }
+                continue;
+            }
+
+            const a = assistantText(entry);
+            if (a === null || a.trim() === '') continue;
+            c.assistant_turns += 1;
+
+            if (detectPromissory(a) !== null) c.promissory_fires += 1;
+            if (detectLanguage(a, pinned) !== null) {
+                c.language_fires += 1;
+                myLanguage += 1;
+            }
+        }
+
+        const agree = Math.min(myLanguage, scannerLanguage);
+        c.language_agree += agree;
+        c.language_only += Math.max(0, myLanguage - scannerLanguage);
+    }
+
+    return c;
+}
+
+export function render(c: Counts): string {
+    const pct = (n: number): string =>
+        c.assistant_turns === 0 ? '0.0' : ((100 * n) / c.assistant_turns).toFixed(1);
+    return [
+        `measure-turn-end-gate · ${c.sessions} sessions · ${c.assistant_turns} assistant turns`,
+        '',
+        `  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)}%)`,
+        `    of which the independent scanner also flagged: ${c.language_agree}`,
+        `    fired where the scanner saw nothing:           ${c.language_only}`,
+        '',
+        '  The second line is the one that matters for a BLOCKING guard: those are',
+        '  the turns this detector would have refused and the other instrument would',
+        '  not. They are candidate false positives, not confirmed ones — the two',
+        '  instruments read different spans (first prose line vs. whole stripped',
+        '  reply), so disagreement is expected in both directions.',
+        '',
+        '  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) {
+            limit = parseInt(argv[i + 1]!, 10);
+            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;
+}
+
+if (process.argv[1] !== undefined && process.argv[1].includes('measure_turn_end_gate')) {
+    process.exit(main());
+}

package/src/scripts/orchestration_record.ts

@@ -13,9 +13,12 @@
  *     [--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]
  *
  * Read by `src/scripts/orchestration_savings_report.ts`.
@@ -39,6 +42,7 @@ import {
     type LineOutcome,
     type RecordInput,
     type RouteTaken,
+    type TriggerArm,
 } from './_lib/orchestration_record.js';
 
 // Exported so other writers of the same audit-log-v1 orchestration line
@@ -141,6 +145,13 @@ 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'),
+        saturation_step: int(flags, 'saturation-step'),
+        trigger_arm_earlier: str(flags, 'trigger-arm-earlier') as TriggerArm | undefined,
         phase: str(flags, 'phase') as LinePhase | undefined,
         outcome: str(flags, 'outcome') as LineOutcome | undefined,
         confidence_band: str(flags, 'confidence-band') as Band | undefined,