@event4u/agent-config 9.28.0 → 9.30.0

package/src/scripts/explain_run.ts

@@ -19,6 +19,14 @@
  *   4. Subagent dispatches in window — mode, tiers, token deltas,
  *      first_pass_success/escalated. Source: same audit-log-v1 files,
  *      `orchestration` sub-object.
+ *   4b. (opt-in via `--decision "<task text>"`) Dispatch-decision trace —
+ *      the judgment-ladder rung taken, every rung rejected with its
+ *      detector's own reason (why-not-team / why-not-council /
+ *      why-no-spawn), and the token/cost estimate from the most recent
+ *      matching orchestration-telemetry record. No record in window → an
+ *      honest "no telemetry record" line, never a fabricated estimate.
+ *      Sources: `_lib/judgment_ladder.ts::explainLadder` + the same
+ *      audit-log-v1 files as §4.
  *   5. Hook / loop / freshness state snapshot. Source:
  *      `agents/state/context-hygiene.json` (the code path the hook
  *      actually writes — see `context_hygiene_hook.ts::STATE_FILE`) or
@@ -39,7 +47,10 @@
  *   ./scripts-run src/scripts/explain_run \
  *     [--task <id>] [--since <ISO-8601>] \
  *     [--router <path>] [--audit-dir <path>] [--engagement <path>] \
- *     [--hygiene <path>] [--output <path>]
+ *     [--hygiene <path>] [--output <path>] \
+ *     [--decision "<task text>"] [--size-estimate <n>] [--slices <n>] \
+ *     [--ordered-plan] [--agent-teams] [--halted] [--no-spawn-primitive] \
+ *     [--inside-subagent] [--approval-required]
  *
  * Defaults: --router dist/router.json · --audit-dir agents/runtime/state/audit
  * · --engagement .agent-engagement.jsonl · --hygiene tries
@@ -51,6 +62,7 @@ import * as path from 'node:path';
 import { pathToFileURL } from 'node:url';
 
 import { EngagementSchemaError, parse_event, type EngagementEvent } from '../agent-src/templates/scripts/telemetry/engagement.js';
+import { explainLadder, type LadderExplanation, type LadderInputs } from './_lib/judgment_ladder.js';
 import { readAuditLines } from './orchestration_savings_report.js';
 
 // ── CLI ──────────────────────────────────────────────────────────────────
@@ -76,7 +88,48 @@ export interface Options {
     engagement: string;
     hygiene: string | null;
     output: string | null;
-}
+    /**
+     * Dispatch-decision task text (§4b); null/absent → the section is not
+     * rendered. Optional (with the flags below) so pre-existing callers
+     * constructing `Options` literals stay source-compatible.
+     */
+    decision?: string | null;
+    /** Ladder signal flags — map 1:1 onto `LadderInputs`; nothing is inferred. */
+    sizeEstimate?: number;
+    slices?: number;
+    orderedPlan?: boolean;
+    agentTeams?: boolean;
+    halted?: boolean;
+    noSpawnPrimitive?: boolean;
+    insideSubagent?: boolean;
+    approvalRequired?: boolean;
+}
+
+const USAGE = `usage: explain_run [--task <id>] [--since <ISO-8601>] [--output <path>]
+                   [--decision "<task text>"] [--size-estimate <int>] [--slices <int>]
+                   [--ordered-plan] [--agent-teams] [--halted] [--no-spawn-primitive]
+                   [--inside-subagent] [--approval-required]
+
+Window:
+  --task <id>            restrict to one task id in the audit log
+  --since <ISO-8601>     cutoff timestamp / date
+  --output <path>        write the report to a file instead of stdout
+
+Dispatch decision (all optional; absent --decision omits the section):
+  --decision <text>      classify this task text through the judgment ladder and
+                         render the rung taken, the rungs rejected with their
+                         detector's reason, and the rungs never reached
+  --size-estimate <int>  size signal; at or below the floor nothing delegates
+  --slices <int>         number of independent slices
+  --ordered-plan         the slices are ordered, not independent
+  --agent-teams          the host reports the agent_teams capability
+  --halted               emergency.orchestration_halt is set
+  --no-spawn-primitive   the host has no subagent_spawn primitive
+  --inside-subagent      classification runs inside a subagent (recursive guard)
+  --approval-required    a human decision is pending; resolves before every rung
+
+Exit: 0 report rendered · 2 bad argument.
+`;
 
 function parseArgs(argv: string[]): Options {
     const opts: Options = {
@@ -87,6 +140,23 @@ function parseArgs(argv: string[]): Options {
         engagement: DEFAULT_ENGAGEMENT,
         hygiene: null,
         output: null,
+        decision: null,
+        sizeEstimate: 0,
+        slices: 0,
+        orderedPlan: false,
+        agentTeams: false,
+        halted: false,
+        noSpawnPrimitive: false,
+        insideSubagent: false,
+        approvalRequired: false,
+    };
+    const intValue = (flag: string, raw: string | undefined): number => {
+        const n = Number(raw);
+        if (raw === undefined || raw === '' || !Number.isInteger(n)) {
+            process.stderr.write(`explain_run: ${flag} requires an integer, got: ${raw ?? '(missing)'}\n`);
+            process.exit(2);
+        }
+        return n;
     };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
@@ -106,8 +176,38 @@ function parseArgs(argv: string[]): Options {
         else if (a.startsWith('--hygiene=')) opts.hygiene = a.slice('--hygiene='.length);
         else if (a === '--output') opts.output = next() ?? opts.output;
         else if (a.startsWith('--output=')) opts.output = a.slice('--output='.length);
-        else {
-            process.stderr.write(`explain_run: unrecognized argument: ${a}\n`);
+        else if (a === '--decision') {
+            const v = next();
+            // Exit rather than no-op: silently dropping the value produced a full
+            // report with the dispatch section absent and exit 0, so a typo read
+            // as "this run had no dispatch decision". `--size-estimate` already
+            // exits 2 on the same mistake; the flags now behave alike.
+            if (v === undefined || v === '') {
+                process.stderr.write('explain_run: --decision requires a value (the task text to classify)\n');
+                process.exit(2);
+            }
+            opts.decision = v;
+        } else if (a.startsWith('--decision=')) opts.decision = a.slice('--decision='.length);
+        else if (a === '--size-estimate') opts.sizeEstimate = intValue('--size-estimate', next());
+        else if (a.startsWith('--size-estimate=')) opts.sizeEstimate = intValue('--size-estimate', a.slice('--size-estimate='.length));
+        else if (a === '--slices') opts.slices = intValue('--slices', next());
+        else if (a.startsWith('--slices=')) opts.slices = intValue('--slices', a.slice('--slices='.length));
+        else if (a === '--ordered-plan') opts.orderedPlan = true;
+        else if (a === '--agent-teams') opts.agentTeams = true;
+        else if (a === '--halted') opts.halted = true;
+        else if (a === '--no-spawn-primitive') opts.noSpawnPrimitive = true;
+        else if (a === '--inside-subagent') opts.insideSubagent = true;
+        else if (a === '--approval-required') opts.approvalRequired = true;
+        else if (a === '--help' || a === '-h') {
+            process.stdout.write(USAGE);
+            process.exit(0);
+        } else {
+            // The usage text goes to stderr with the error, so a typo shows the
+            // whole surface rather than only the rejected token. Nine of these
+            // flags landed at once (the dispatch-decision trace); a script whose
+            // only discovery path is reading its source is a script whose flags
+            // do not exist for the person at the terminal.
+            process.stderr.write(`explain_run: unrecognized argument: ${a}\n\n${USAGE}`);
             process.exit(2);
         }
     }
@@ -486,6 +586,104 @@ function renderOrchestrationSection(opts: Options, auditDirExists: boolean, disp
     return out;
 }
 
+// ── Dispatch-decision trace (§4b — judgment ladder + telemetry estimate) ─
+
+/** Map the CLI signal flags 1:1 onto `LadderInputs` — nothing inferred. */
+export function ladderInputsFromOptions(opts: Options): LadderInputs {
+    return {
+        taskText: opts.decision ?? '',
+        signals: {
+            size_estimate: opts.sizeEstimate ?? 0,
+            independent_slices: opts.slices ?? 0,
+            ordered_plan: opts.orderedPlan ?? false,
+        },
+        activation: { halted: opts.halted ?? false, subagent_spawn: !(opts.noSpawnPrimitive ?? false) },
+        agentTeams: opts.agentTeams ?? false,
+        interactiveApprovalRequired: opts.approvalRequired ?? false,
+        insideSubagentSession: opts.insideSubagent ?? false,
+    };
+}
+
+/** Most recent dispatch line by `ts` (undefined ts sorts oldest). */
+export function latestDispatch(dispatches: ExplainAuditLine[]): ExplainAuditLine | null {
+    let latest: ExplainAuditLine | null = null;
+    let latestTs = Number.NEGATIVE_INFINITY;
+    for (const line of dispatches) {
+        const t = line.ts === undefined ? Number.NEGATIVE_INFINITY : Date.parse(line.ts);
+        const ts = Number.isFinite(t) ? t : Number.NEGATIVE_INFINITY;
+        if (latest === null || ts >= latestTs) {
+            latest = line;
+            latestTs = ts;
+        }
+    }
+    return latest;
+}
+
+function renderDecisionSection(
+    opts: Options,
+    explanation: LadderExplanation,
+    auditDirExists: boolean,
+    dispatches: ExplainAuditLine[],
+): string[] {
+    const out: string[] = [];
+    out.push('## Dispatch decision (judgment ladder)');
+    out.push(
+        `_Source: \`src/scripts/_lib/judgment_ladder.ts\` (\`explainLadder\`) over the \`--decision\` text + signal flags; token/cost estimate from \`${opts.auditDir}/*.jsonl\` orchestration telemetry_`,
+    );
+    out.push('');
+    out.push(`Decision text: ${JSON.stringify(opts.decision ?? '')}`);
+    const r = explanation.result;
+    const rungLabel = r.rung === null ? '∅ (never spawns)' : String(r.rung);
+    const modeSuffix = r.mode !== undefined && r.mode !== null ? ` (mode ${r.mode})` : '';
+    const degradedSuffix = r.degraded_from !== undefined ? ` [degraded from rung ${r.degraded_from}]` : '';
+    out.push(`Resolved: rung ${rungLabel} — verdict \`${r.verdict}\`${modeSuffix}${degradedSuffix} — ${r.reason}`);
+    out.push('');
+    out.push('### Ladder trail (priority order 0 → 4 → 3 → 2 → 1)');
+    out.push('');
+    out.push('| rung | resolves to | status | reason |');
+    out.push('|---|---|---|---|');
+    for (const step of explanation.trail) {
+        out.push(`| ${step.rung} | ${step.resolves_to} | ${step.status} | ${step.reason} |`);
+    }
+    if (explanation.no_spawn_reason !== undefined) {
+        out.push('');
+        out.push(`Why no spawn: ${explanation.no_spawn_reason}`);
+    }
+    out.push('');
+    out.push('### Token/cost estimate');
+    if (!auditDirExists) {
+        out.push(`no telemetry record — \`${opts.auditDir}\` absent; no token/cost estimate (a fabricated number would be worse than none)`);
+        return out;
+    }
+    const latest = latestDispatch(dispatches);
+    if (latest === null) {
+        out.push(`no telemetry record matches ${windowLabel(opts)}; no token/cost estimate (a fabricated number would be worse than none)`);
+        return out;
+    }
+    const o = latest.orchestration ?? {};
+    // NOT matched to this decision, and the label must say so. The record shape
+    // carries no key that ties a line to a decision text — `latestDispatch` sorts
+    // by `ts` alone — so calling it "matching" made an unrelated run's cost read
+    // as this decision's estimate, in a section whose own header promises never
+    // to fabricate one. Printing it is still useful (it is the freshest real
+    // measurement on this host); claiming correspondence was the defect.
+    out.push(
+        `most recent dispatch in ${windowLabel(opts)} — NOT matched to this decision ` +
+            `(the record carries no decision key; sorted by ts alone): ` +
+            `ts ${latest.ts ?? '(unset)'}, work_id ${latest.work_id ?? '(unset)'}, ` +
+            `token_delta ${o.token_delta ?? 0} (${o.token_delta_provenance ?? 'estimated'}), ` +
+            `mode ${o.dispatch_mode ?? '(unset)'}, tiers ${(o.tiers ?? []).join(',') || '(unset)'}`,
+    );
+    const resolved = explanation.result.verdict;
+    const recordMode = o.dispatch_mode;
+    if (recordMode !== undefined && resolved === 'in-session') {
+        out.push(
+            `  ⚠️  this decision resolves to \`${resolved}\` (no dispatch), so the mode above describes a different run.`,
+        );
+    }
+    return out;
+}
+
 function renderHygieneSection(hygiene: HygieneReadResult): string[] {
     const out: string[] = [];
     out.push('## Hook / loop state (context-hygiene)');
@@ -568,6 +766,10 @@ export function buildReport(opts: Options): string {
     out.push('');
     out.push(...renderOrchestrationSection(opts, auditDirExists, dispatches));
     out.push('');
+    if (opts.decision !== null && opts.decision !== undefined) {
+        out.push(...renderDecisionSection(opts, explainLadder(ladderInputsFromOptions(opts)), auditDirExists, dispatches));
+        out.push('');
+    }
     out.push(...renderHygieneSection(hygiene));
     out.push('');
     out.push(...renderParkedSection());

package/src/scripts/forensics_report.ts

@@ -0,0 +1,333 @@
+/**
+ * Forensic analyzers — hotspot risk + change coupling from `git log` alone
+ * (road-to-judgment-and-forensic-evidence Phase 3; pack `forensics`,
+ * default-off, read-only, advisory).
+ *
+ * Two deterministic analyzers over a PINNED revision range:
+ *
+ *   hotspot(file)   = norm(change_frequency) × norm(complexity)
+ *                     complexity = LOC + total indentation units (tabs = 1,
+ *                     4 spaces = 1) of the file in the working tree — a cheap,
+ *                     language-agnostic indentation proxy, documented rather
+ *                     than clever. A hotspot is a place to LOOK, never a code
+ *                     quality verdict (both inputs can be correct for a file).
+ *
+ *   coupling(A,B)   = co_changes(A,B) / min(changes(A), changes(B))
+ *                     over commits with ≤ max_commit_files files (bulk sweeps
+ *                     poison coupling; skipped commits are counted in the
+ *                     report, never silently dropped).
+ *
+ *   boundary_contradictions — coupling pairs ABOVE the threshold whose files
+ *   live in different top-level modules. Recorded as a finding CLASS (the
+ *   intended boundaries and the actual change pattern disagree), not as a
+ *   failure — per the roadmap's step 3.6.
+ *
+ * Determinism bar (step 3.3): byte-stable output on a frozen fixture — same
+ * inputs, same bytes. Inputs are the git log for the pinned range plus file
+ * metrics; `--log-file` + `--metrics-file` inject both for fixture tests, so
+ * the analyzer's whole pipeline is exercised without a live repo. All maps
+ * are sorted before emission; scores are rounded to 4 decimals.
+ *
+ * Advisory wiring (step 3.4): `--findings-out` emits
+ * review-findings.schema.json-shaped items with kind `correctness` and
+ * severity `low|medium` — non-blocking by construction in
+ * `check_finding_dispositions.isBlocking` — for ingestion into the existing
+ * release findings ledger (`check_finding_dispositions --ingest`).
+ *
+ * Gaming risk: an empty scan (dead range, wrong cwd) yielding a green "no
+ * hotspots" report — mitigated by the shared scan-scope helper: zero scanned
+ * commits throws (DeadScopeError), it never publishes an empty finding set
+ * (step 3.2). Residual: a range that is real but trivially small still
+ * produces low-signal output; the report publishes commit + file counts so a
+ * reader can judge the denominator.
+ */
+// ledger-exempt: on-demand advisory analyzer, not a CI gate — the report JSON
+// itself carries the full denominator (scanned commits/files) per run.
+import * as fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+
+import { reportScanned } from './_lib/scan_scope.js';
+
+interface Params {
+    max_commit_files: number;
+    coupling_threshold: number;
+    min_cochanges: number;
+    top_hotspots: number;
+}
+const DEFAULTS: Params = {
+    max_commit_files: 50,
+    coupling_threshold: 0.5,
+    min_cochanges: 3,
+    top_hotspots: 25,
+};
+
+interface Commit {
+    hash: string;
+    files: string[];
+}
+
+/** Parse `git log --pretty=format:'C %H' --name-only` output. */
+export function parseLog(text: string): Commit[] {
+    const commits: Commit[] = [];
+    let current: Commit | null = null;
+    for (const raw of text.split('\n')) {
+        const line = raw.trimEnd();
+        if (line.startsWith('C ')) {
+            if (current) commits.push(current);
+            current = { hash: line.slice(2).trim(), files: [] };
+        } else if (line.length > 0 && current) {
+            current.files.push(line);
+        }
+    }
+    if (current) commits.push(current);
+    return commits;
+}
+
+function gitLog(range: string): string {
+    return execFileSync('git', ['log', '--pretty=format:C %H', '--name-only', range], {
+        encoding: 'utf8',
+        maxBuffer: 256 * 1024 * 1024,
+    });
+}
+
+/** LOC + indentation units — the documented complexity proxy. */
+export function complexityOf(content: string): number {
+    const lines = content.split('\n');
+    let indent = 0;
+    for (const l of lines) {
+        const m = /^[\t ]*/.exec(l);
+        const ws = m ? m[0] : '';
+        let units = 0;
+        let spaces = 0;
+        for (const ch of ws) {
+            if (ch === '\t') units += 1;
+            else spaces += 1;
+        }
+        units += Math.floor(spaces / 4);
+        indent += units;
+    }
+    return lines.length + indent;
+}
+
+function liveComplexity(file: string): number | null {
+    try {
+        const st = fs.statSync(file);
+        if (!st.isFile()) return null;
+        const buf = fs.readFileSync(file);
+        if (buf.includes(0)) return null; // binary
+        return complexityOf(buf.toString('utf8'));
+    } catch {
+        return null; // deleted / renamed away — frequency without complexity
+    }
+}
+
+function round4(n: number): number {
+    return Math.round(n * 10000) / 10000;
+}
+
+/** First path segment — the module boundary the router treats as independent. */
+export function moduleOf(file: string): string {
+    const parts = file.split('/');
+    if (parts.length >= 2 && (parts[0] === 'src' || parts[0] === 'tests' || parts[0] === 'docs')) {
+        return `${parts[0]}/${parts[1] ?? ''}`;
+    }
+    return parts[0] ?? file;
+}
+
+interface Hotspot {
+    file: string;
+    changes: number;
+    complexity: number | null;
+    score: number;
+}
+interface CouplingPair {
+    a: string;
+    b: string;
+    co_changes: number;
+    changes_a: number;
+    changes_b: number;
+    coupling: number;
+    cross_module: boolean;
+}
+
+export interface Report {
+    mode: string;
+    range: string;
+    params: Params;
+    scanned: { commits: number; commits_skipped_bulk: number; files: number };
+    hotspots: Hotspot[];
+    coupling: CouplingPair[];
+    boundary_contradictions: CouplingPair[];
+}
+
+export function analyze(
+    commits: Commit[],
+    params: Params,
+    complexity: (file: string) => number | null,
+    range: string,
+    mode: string,
+): Report {
+    const changes = new Map<string, number>();
+    const co = new Map<string, number>();
+    let skipped = 0;
+    for (const c of commits) {
+        const files = [...new Set(c.files)].sort();
+        if (files.length > params.max_commit_files) {
+            skipped++;
+            continue;
+        }
+        for (const f of files) changes.set(f, (changes.get(f) ?? 0) + 1);
+        for (let i = 0; i < files.length; i++) {
+            for (let j = i + 1; j < files.length; j++) {
+                const key = `${files[i]}\u0000${files[j]}`;
+                co.set(key, (co.get(key) ?? 0) + 1);
+            }
+        }
+    }
+
+    const files = [...changes.keys()].sort();
+    const complexities = new Map<string, number | null>();
+    for (const f of files) complexities.set(f, complexity(f));
+    let maxChanges = 0;
+    for (const v of changes.values()) if (v > maxChanges) maxChanges = v;
+    let maxComplexity = 0;
+    for (const v of complexities.values()) if (v !== null && v > maxComplexity) maxComplexity = v;
+
+    const hotspots: Hotspot[] = files
+        .map((f) => {
+            const ch = changes.get(f) ?? 0;
+            const cx = complexities.get(f) ?? null;
+            const score =
+                cx === null || maxChanges === 0 || maxComplexity === 0
+                    ? 0
+                    : round4((ch / maxChanges) * (cx / maxComplexity));
+            return { file: f, changes: ch, complexity: cx, score };
+        })
+        .filter((h) => h.score > 0)
+        .sort((a, b) => b.score - a.score || a.file.localeCompare(b.file))
+        .slice(0, params.top_hotspots);
+
+    const coupling: CouplingPair[] = [];
+    for (const [key, n] of [...co.entries()].sort()) {
+        if (n < params.min_cochanges) continue;
+        const [a, b] = key.split('\u0000') as [string, string];
+        const ca = changes.get(a) ?? 0;
+        const cb = changes.get(b) ?? 0;
+        const denom = Math.min(ca, cb);
+        if (denom === 0) continue;
+        const strength = round4(n / denom);
+        if (strength < params.coupling_threshold) continue;
+        coupling.push({
+            a,
+            b,
+            co_changes: n,
+            changes_a: ca,
+            changes_b: cb,
+            coupling: strength,
+            cross_module: moduleOf(a) !== moduleOf(b),
+        });
+    }
+    coupling.sort((x, y) => y.coupling - x.coupling || x.a.localeCompare(y.a) || x.b.localeCompare(y.b));
+
+    return {
+        mode,
+        range,
+        params,
+        scanned: {
+            commits: commits.length - skipped,
+            commits_skipped_bulk: skipped,
+            files: files.length,
+        },
+        hotspots,
+        coupling,
+        boundary_contradictions: coupling.filter((p) => p.cross_module),
+    };
+}
+
+/** Same id convention as self_review_gate.findingId — the schema pins ^[0-9a-f]{12}$. */
+function forensicsFindingId(kind: string, title: string, file: string): string {
+    return createHash('sha256').update(`${kind}|${title}|${file}`).digest('hex').slice(0, 12);
+}
+
+/** Findings-schema-shaped advisory items — non-blocking by construction. */
+export function toFindings(report: Report): Record<string, unknown> {
+    const findings: Record<string, unknown>[] = [];
+    for (const h of report.hotspots.slice(0, 10)) {
+        const title = `hotspot: ${h.file} (score ${String(h.score)})`;
+        findings.push({
+            finding_id: forensicsFindingId('correctness', title, h.file),
+            severity: 'low',
+            kind: 'correctness',
+            title,
+            detail: `${String(h.changes)} changes in range × complexity ${String(h.complexity ?? 'n/a')} — a place to look, not a quality verdict.`,
+            file: h.file,
+        });
+    }
+    for (const p of report.boundary_contradictions) {
+        const title = `boundary contradiction: ${p.a} <-> ${p.b} (coupling ${String(p.coupling)})`;
+        findings.push({
+            finding_id: forensicsFindingId('correctness', title, p.a),
+            severity: 'medium',
+            kind: 'correctness',
+            title,
+            detail: `Cross-module co-change ${String(p.co_changes)}/${String(Math.min(p.changes_a, p.changes_b))} above threshold ${String(report.params.coupling_threshold)} — the intended module boundary and the actual change pattern disagree. A finding class, not a failure.`,
+            file: p.a,
+        });
+    }
+    return { schema_version: 1, findings };
+}
+
+function stringifyReport(report: Report): string {
+    return JSON.stringify(report, null, 2) + '\n';
+}
+
+function argValue(argv: string[], flag: string): string | null {
+    const i = argv.indexOf(flag);
+    return i >= 0 ? (argv[i + 1] ?? null) : null;
+}
+
+function main(argv: string[]): number {
+    const range = argValue(argv, '--range');
+    const logFile = argValue(argv, '--log-file');
+    const metricsFile = argValue(argv, '--metrics-file');
+    const outFile = argValue(argv, '--out');
+    const findingsOut = argValue(argv, '--findings-out');
+    if (!range && !logFile) {
+        process.stderr.write(
+            'usage: forensics_report (--range <rev-range> | --log-file <fixture>) [--metrics-file <json>] [--out <file>] [--findings-out <file>]\n',
+        );
+        return 2;
+    }
+    const params: Params = { ...DEFAULTS };
+    const text = logFile ? fs.readFileSync(logFile, 'utf8') : gitLog(range as string);
+    const commits = parseLog(text);
+    let complexity: (file: string) => number | null = liveComplexity;
+    if (metricsFile) {
+        const metrics = JSON.parse(fs.readFileSync(metricsFile, 'utf8')) as Record<string, number>;
+        complexity = (f) => (Object.prototype.hasOwnProperty.call(metrics, f) ? metrics[f]! : null);
+    }
+    const report = analyze(commits, params, complexity, range ?? `log-file:${logFile ?? ''}`, 'run');
+
+    // Loud-fail on an empty scan BEFORE anything is written — a report over
+    // nothing is not a report, and it must not exist on disk either (throws
+    // DeadScopeError when zero commits were analyzed).
+    reportScanned({
+        gate: 'forensics_report',
+        scanned: report.scanned.commits,
+        units: 'commit(s)',
+        roots: [range ?? (logFile as string)],
+    });
+
+    const json = stringifyReport(report);
+    if (outFile) fs.writeFileSync(outFile, json);
+    process.stdout.write(json);
+    if (findingsOut) fs.writeFileSync(findingsOut, JSON.stringify(toFindings(report), null, 2) + '\n');
+    return 0;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+    process.exit(main(process.argv.slice(2)));
+}
+
+export { main };

package/src/scripts/generate_settings_reference.ts

@@ -43,6 +43,7 @@ import {
 } from '../shared/settingsClasses.js';
 import { flattenSurface, type SurfaceEntry } from '../shared/settingsSurface.js';
 
+// ledger-exempt: single-artifact generator — renders ONE derived page from the zod schema and byte-compares it against the committed copy in --check mode; the verdict is one aggregate drift comparison over the whole page, so per-target findings do not exist.
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 export const ROOT = path.resolve(_HERE, '..', '..');