@event4u/agent-config 14.7.0 → 14.9.0

package/src/scripts/audit_adr_coverage.ts

@@ -16,12 +16,19 @@
  *   --regen-area-readme <area>  rewrite docs/adrs/<area>/README.md. Idempotent.
  *
  * Historical quirks are preserved deliberately — tests and downstream consumers pin the exact behaviour.
+ *
+ * Record metadata is read by `read_adr_meta`: the shared frontmatter reader
+ * (`_lib/adr_frontmatter`) when a `---` block is present, the transitional
+ * blockquote header otherwise. The seven per-area records carried only the
+ * blockquote until 2026-08-21, so both paths have to work while the two
+ * surfaces overlap.
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { readAdrAxisCells, readAdrFrontmatterScalars } from './_lib/adr_frontmatter.js';
 import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -89,10 +96,26 @@ export function unlistedAreaDirs(adrsRoot: string): string[] {
 
 // ^(\d{4})-([a-z0-9-]+)\.md$
 const NAMED = /^(\d{4})-([a-z0-9-]+)\.md$/;
-// ^---\n(.*?)\n---  (DOTALL)
-const FM = /^---\n([\s\S]*?)\n---/;
-// ^([a-z_]+):\s*(.+?)\s*$  (MULTILINE)
-const FIELD = /^([a-z_]+):[ \t]*(.+?)[ \t]*$/gm;
+
+/**
+ * Metadata keys this script recognises in the transitional blockquote header.
+ *
+ * An allowlist rather than "every `Key: value` pair in a blockquote", because
+ * the blockquote block also carries prose that happens to contain colons — the
+ * `Roadmap:` pointer, a `Contract:` link, and (on `memory/0001`) a whole
+ * supersession banner. Harvesting those would put link markup into the README
+ * table. Keys are matched case-insensitively with spaces folded to `_`.
+ */
+const BLOCKQUOTE_KEYS = new Set([
+    'adr',
+    'area',
+    'status',
+    'date',
+    'decision',
+    'supersedes',
+    'superseded_by',
+    'type',
+]);
 
 interface AdrEntry {
     num: string;
@@ -129,24 +152,87 @@ function _globMdSorted(dir: string): string[] {
     return out;
 }
 
+/**
+ * Read the leading `---` frontmatter block, `{}` when there is none.
+ *
+ * Delegates to the one shared reader (`_lib/adr_frontmatter`) rather than
+ * keeping this script's own regex: the tree carried three divergent ADR
+ * frontmatter parsers plus this one, and the two nested axes (`provenance`,
+ * `evidence`) are exactly the shape a `^([a-z_]+):\s*(.+?)$` regex reads as
+ * absent.
+ *
+ * What is preserved: the `{}`-on-absent return, and the scalar keys this
+ * script's callers read.
+ *
+ * What changed, stated because "preserved" was claimed for it and is false:
+ * the removed `_stripChars(v, ' "\'')` stripped repeated and unbalanced quote
+ * and space characters from both ends (Python `str.strip` semantics), while the
+ * shared reader's `stripQuotes` is `/^["'](.*)["']$/` — exactly one balanced
+ * pair. Two inputs now differ: `key: "value` keeps its opening quote (was
+ * `value`), and `key: ''v''` yields `'v'` (was `v`). No record in the corpus
+ * exercises either shape today, and the old behaviour is deliberately NOT
+ * restored — one shared reader beats a bug-compatible local copy.
+ */
 export function parse_fm(text: string): Record<string, string> {
-    const m = FM.exec(text);
-    if (!m) {
-        return {};
-    }
+    return readAdrFrontmatterScalars(text) ?? {};
+}
+
+/**
+ * Read the transitional blockquote metadata header.
+ *
+ * The seven per-area records predate the frontmatter contract and carry their
+ * metadata as a blockquote line instead:
+ *
+ * ```
+ * > Area: `router` · Status: accepted · Date: 2026-05-16 · Type: retrospective
+ * ```
+ *
+ * Two shapes have to be handled and both occur in the tree. Several fields
+ * share one line separated by `·`, so the split is on the separator first and
+ * the first `:` second. And the value is often wrapped in backticks
+ * (`` `router` ``), which are stripped — a table cell showing `` `accepted` ``
+ * would not match what the frontmatter path produces for the same record.
+ *
+ * Scanning stops at the first `## ` heading: everything above it is the
+ * metadata header, everything below is body prose whose blockquotes are
+ * quotations, not metadata.
+ */
+export function parse_blockquote_meta(text: string): Record<string, string> {
     const out: Record<string, string> = {};
-    const body = m[1] as string;
-    FIELD.lastIndex = 0;
-    let fm: RegExpExecArray | null;
-    while ((fm = FIELD.exec(body)) !== null) {
-        const k = fm[1] as string;
-        const v = fm[2] as string;
-        // v.strip(" \"'") — strip leading/trailing space, double- and single-quote.
-        out[k] = _stripChars(v, ' "\'');
+    for (const raw of text.split('\n')) {
+        const line = raw.trim();
+        if (line.startsWith('## ')) break;
+        if (!line.startsWith('>')) continue;
+        for (const part of line.replace(/^>\s*/, '').split('·')) {
+            const idx = part.indexOf(':');
+            if (idx <= 0) continue;
+            const key = part.slice(0, idx).trim().toLowerCase().replace(/\s+/g, '_');
+            if (!BLOCKQUOTE_KEYS.has(key)) continue;
+            const value = _stripChars(part.slice(idx + 1), ' "\'`');
+            if (value === '') continue;
+            // First occurrence wins — a later body line never overwrites the header.
+            if (!(key in out)) out[key] = value;
+        }
     }
     return out;
 }
 
+/**
+ * One record's metadata: frontmatter when present, the blockquote header
+ * otherwise.
+ *
+ * Frontmatter wins outright rather than merging. During the transition a record
+ * carries both, and the blockquote is explicitly the human-readable duplicate —
+ * merging would make the authoritative surface depend on which of the two
+ * happened to mention a field, and a stale duplicate would then be able to
+ * contribute a value the frontmatter had already corrected.
+ */
+export function read_adr_meta(text: string): Record<string, string> {
+    const fm = readAdrFrontmatterScalars(text);
+    if (fm !== null && Object.keys(fm).length > 0) return fm;
+    return parse_blockquote_meta(text);
+}
+
 /** Mirror Python `str.strip(chars)`. */
 function _stripChars(s: string, chars: string): string {
     let start = 0;
@@ -193,8 +279,13 @@ export function scan_area(area: string): [AdrEntry[], string[]] {
             errs.push(`${area}/${base}: filename does not match NNNN-<slug>.md`);
             continue;
         }
-        const fm = parse_fm(fs.readFileSync(p, 'utf-8'));
-        adrs.push({ num: m[1] as string, slug: m[2] as string, path: base, ...fm });
+        const text = fs.readFileSync(p, 'utf-8');
+        const fm = read_adr_meta(text);
+        // Read apart from `fm`, for the same reason the index does: the two
+        // axes are nested, so the scalar reader keeps them out of its map and
+        // spreading it could never produce these cells.
+        const axes = readAdrAxisCells(text);
+        adrs.push({ num: m[1] as string, slug: m[2] as string, path: base, ...fm, ...axes });
     }
     // Gap check.
     const nums = adrs.map((a) => parseInt(a.num, 10));
@@ -236,7 +327,11 @@ export function render_area_readme(area: string, meta: AreaMeta, adrs: AdrEntry[
     } else {
         lines.push(`Contract: _not yet published_ (\`${repoRel}\`).`);
     }
-    lines.push('', '| # | Title | Status | Date | Supersedes |', '|---|---|---|---|---|');
+    lines.push(
+        '',
+        '| # | Title | Status | Date | Provenance | Evidence | Supersedes |',
+        '|---|---|---|---|---|---|---|',
+    );
     for (const a of adrs) {
         // a.get("decision", a["slug"]).replace("-", " ").title()
         const decision = a['decision'] !== undefined ? a['decision'] : a.slug;
@@ -244,11 +339,12 @@ export function render_area_readme(area: string, meta: AreaMeta, adrs: AdrEntry[
         lines.push(
             `| [${a.num}](${a.path}) | ${title} | ` +
                 `${a['status'] ?? '—'} | ${a['date'] ?? '—'} | ` +
+                `${a['provenance_kind'] ?? '—'} | ${a['evidence_grade'] ?? '—'} | ` +
                 `${a['supersedes'] ?? '—'} |`,
         );
     }
     if (adrs.length === 0) {
-        lines.push('| _none yet_ | — | — | — | — |');
+        lines.push('| _none yet_ | — | — | — | — | — | — |');
     }
     return lines.join('\n') + '\n';
 }
@@ -325,9 +421,26 @@ export function cmd_check(): number {
             process.stderr.write(`❌ ${e}\n`);
             hard += 1;
         }
-        if (adrs.length > 0 && !_exists(path.join(ADR_ROOT, area, 'README.md'))) {
+        const readmePath = path.join(ADR_ROOT, area, 'README.md');
+        if (adrs.length > 0 && !_exists(readmePath)) {
             process.stderr.write(`❌ ${area}/: README.md missing\n`);
             hard += 1;
+        } else if (_exists(readmePath)) {
+            // Existence was the whole check until 2026-08-22, and the six
+            // committed READMEs proved what that costs: every one of them had
+            // been generated before the shared frontmatter reader landed, so
+            // they rendered `—` for `status` and `date` on ADRs that carry
+            // both — stale for months against a gate reporting zero failures.
+            // A generated file with no freshness gate is a file nobody
+            // regenerates.
+            const rendered = render_area_readme(area, meta, adrs);
+            if (fs.readFileSync(readmePath, 'utf-8') !== rendered) {
+                process.stderr.write(
+                    `❌ ${area}/README.md is stale — regenerate with ` +
+                        `\`audit_adr_coverage --regen-area-readme ${area}\`\n`,
+                );
+                hard += 1;
+            }
         }
         if (adrs.length === 0) {
             process.stderr.write(`⚠️  ${area}/: no bootstrap ADR yet (contract: ${meta.contract})\n`);

package/src/scripts/bench_hook_latency.ts

@@ -230,6 +230,159 @@ export function benchEvent(
     };
 }
 
+/**
+ * One dispatcher invocation that reads stdin, parses it, and exits — the
+ * transport-isolation cell of the § 2 matrix.
+ *
+ * `b-payload-read-parse-dominates`, option (a), council 2026-08-20 (2/2
+ * quorum). Phase 1 removed ten of eleven envelope stringifies and moved
+ * nothing; Phase 2 removed the body from six of eleven concerns and moved
+ * nothing. What is left between the small and large cells happens ONCE per
+ * event, before any concern runs: `readFd0ToEnd` drains the pipe and
+ * `_build_envelope` parses it. This measures exactly that, through the SAME
+ * bundle, interpreter and spawn as the slot reading it is a share of — so the
+ * constant terms cancel in the delta.
+ *
+ * Deliberately the real bundle with `--read-exit` rather than a standalone
+ * probe: a probe would re-implement the audited retrying reader, and that copy
+ * is the drift `hook_stdin` exists to prevent.
+ */
+export function benchReadExit(
+    event: string,
+    runs: number,
+    workspace: string,
+): EventResult {
+    const durations: number[] = [];
+    const payload = syntheticPayload(event, workspace);
+    for (let i = 0; i < runs; i += 1) {
+        const started = performance.now();
+        const proc = spawnSync(
+            process.execPath,
+            [
+                BUNDLE_OVERRIDE ?? BUNDLE,
+                '--platform',
+                'claude',
+                '--event',
+                event,
+                '--project-dir',
+                workspace,
+                '--read-exit',
+            ],
+            {
+                input: payload,
+                encoding: 'utf-8',
+                env: { ...process.env, AGENT_CONFIG_REPLAY: '1', CLAUDE_PROJECT_DIR: workspace },
+                timeout: 60000,
+            },
+        );
+        const elapsed = performance.now() - started;
+        if (proc.error) {
+            throw new Error(`read-exit failed on ${event}: ${proc.error.message}`);
+        }
+        if (!(proc.stderr ?? '').includes('--read-exit ok')) {
+            // A silent no-op here would report the fastest possible number and
+            // measure nothing — the failure mode this whole cell exists to avoid
+            // in the OTHER direction. Refuse instead of publishing it.
+            throw new Error(
+                `read-exit produced no confirmation on ${event}; the flag may not be ` +
+                    `wired in the measured bundle (${BUNDLE_OVERRIDE ?? BUNDLE}). ` +
+                    `stderr: ${(proc.stderr ?? '').trim().slice(0, 200)}`,
+            );
+        }
+        durations.push(elapsed);
+    }
+    durations.sort((a, b) => a - b);
+    return {
+        event: `read_exit:${event}`,
+        runs,
+        p50_ms: Math.round(percentile(durations, 50)),
+        p95_ms: Math.round(percentile(durations, 95)),
+        max_ms: Math.round(durations[durations.length - 1] as number),
+    };
+}
+
+/** One row of the transport-share decomposition. */
+export interface ReadExitCell {
+    event: string;
+    payload_bytes: number;
+    slot_small_p50_ms: number;
+    slot_large_p50_ms: number;
+    read_exit_small_p50_ms: number;
+    read_exit_large_p50_ms: number;
+    /** Large-minus-small on the full dispatch. */
+    slot_delta_ms: number;
+    /** Large-minus-small on read + parse alone. */
+    transport_delta_ms: number;
+    /**
+     * `transport_delta / slot_delta`, as a percentage, or `null` when the slot
+     * delta is not positive.
+     *
+     * `null` is a real answer and must not be rendered as 0: a run whose large
+     * cell is no slower than its small one says the fixture did not reproduce
+     * the gap on this machine, which is different from saying transport is free.
+     */
+    transport_share_pct: number | null;
+}
+
+/**
+ * The four measurements the option asks for, in one invocation.
+ *
+ * Both payload sizes are needed for the SHARE, and taking them in one run is
+ * the point: two separate runs would compare across whatever else the machine
+ * was doing, which is the cross-runner shape § 2 of the roadmap refuses as a
+ * repo fact. Arms alternate per repetition for the same reason.
+ */
+export function benchReadExitCell(
+    event: string,
+    runs: number,
+    workspace: string,
+    payloadBytes: number,
+): ReadExitCell {
+    const saved = PAYLOAD_BYTES;
+    try {
+        PAYLOAD_BYTES = 0;
+        const slotSmall = benchEvent(event, runs, workspace, 'bundle');
+        const probeSmall = benchReadExit(event, runs, workspace);
+        PAYLOAD_BYTES = payloadBytes;
+        const slotLarge = benchEvent(event, runs, workspace, 'bundle');
+        const probeLarge = benchReadExit(event, runs, workspace);
+        const slot_delta_ms = slotLarge.p50_ms - slotSmall.p50_ms;
+        const transport_delta_ms = probeLarge.p50_ms - probeSmall.p50_ms;
+        return {
+            event,
+            payload_bytes: payloadBytes,
+            slot_small_p50_ms: slotSmall.p50_ms,
+            slot_large_p50_ms: slotLarge.p50_ms,
+            read_exit_small_p50_ms: probeSmall.p50_ms,
+            read_exit_large_p50_ms: probeLarge.p50_ms,
+            slot_delta_ms,
+            transport_delta_ms,
+            transport_share_pct:
+                slot_delta_ms > 0
+                    ? Math.round((transport_delta_ms / slot_delta_ms) * 100)
+                    : null,
+        };
+    } finally {
+        PAYLOAD_BYTES = saved;
+    }
+}
+
+/** Human-readable decomposition, one line per fact. */
+export function renderReadExitCell(cell: ReadExitCell): string {
+    const share =
+        cell.transport_share_pct === null
+            ? 'n/a — the large cell was not slower than the small one in this run'
+            : `${String(cell.transport_share_pct)}%`;
+    return (
+        `read-exit cell · ${cell.event} · payload ${String(cell.payload_bytes)}B\n` +
+        `  full dispatch    small ${String(cell.slot_small_p50_ms).padStart(5)} ms · ` +
+        `large ${String(cell.slot_large_p50_ms).padStart(5)} ms · delta ${String(cell.slot_delta_ms)} ms\n` +
+        `  read + parse     small ${String(cell.read_exit_small_p50_ms).padStart(5)} ms · ` +
+        `large ${String(cell.read_exit_large_p50_ms).padStart(5)} ms · delta ${String(cell.transport_delta_ms)} ms\n` +
+        `  transport share of the large-payload delta: ${share}\n`
+    );
+}
+
 /**
  * Same-run control: a bare `node -e 0`, measured through the identical
  * spawnSync harness the slots use.
@@ -486,6 +639,37 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         PAYLOAD_BYTES = parsed;
     }
 
+    // `--read-exit-cell <bytes>`: the transport-isolation cell. Measurement-only
+    // for the same reason `--payload-bytes` is — it PADS the payload, so it must
+    // never write a budget row or a regression baseline.
+    const readExitIdx = argv.indexOf('--read-exit-cell');
+    let readExitBytes: number | null = null;
+    if (readExitIdx >= 0) {
+        const raw = argv[readExitIdx + 1];
+        const parsed = raw === undefined ? Number.NaN : Number.parseInt(raw, 10);
+        if (!Number.isFinite(parsed) || parsed <= 0) {
+            process.stderr.write(
+                'bench_hook_latency: --read-exit-cell requires a positive integer byte count\n',
+            );
+            return 2;
+        }
+        if (gate || update || baselineIdx >= 0) {
+            process.stderr.write(
+                'bench_hook_latency: --read-exit-cell is measurement-only — a padded payload must ' +
+                    "never write this tree's budget row or regression baseline\n",
+            );
+            return 2;
+        }
+        if (viaCli) {
+            process.stderr.write(
+                'bench_hook_latency: --read-exit-cell drives the bundle directly and does not use ' +
+                    'the --via-cli shim path — pick one\n',
+            );
+            return 2;
+        }
+        readExitBytes = parsed;
+    }
+
     const bundleIdx = argv.indexOf('--bundle');
     if (bundleIdx >= 0) {
         const raw = argv[bundleIdx + 1];
@@ -539,6 +723,26 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         return 2;
     }
 
+    if (readExitBytes !== null) {
+        // Its own mode: the cell alternates two payload sizes internally, so
+        // running it alongside the ordinary sweep would report a padded number
+        // under an unpadded label.
+        const cellWorkspace = fs.mkdtempSync(path.join(os.tmpdir(), 'ac-hook-readexit-'));
+        try {
+            // `post_tool_use` only. That is where the large cell lives: a
+            // `tool_response` does not exist on a `PreToolUse` payload, which is
+            // the same objection `syntheticPayload` raises against padding `stop`.
+            const cell = benchReadExitCell('post_tool_use', runs, cellWorkspace, readExitBytes);
+            process.stdout.write(renderReadExitCell(cell));
+            process.stdout.write(
+                'ℹ️  measurement only (no gate) — this cell never writes a budget row\n',
+            );
+        } finally {
+            fs.rmSync(cellWorkspace, { recursive: true, force: true });
+        }
+        return 0;
+    }
+
     const workspace = fs.mkdtempSync(path.join(os.tmpdir(), 'ac-hook-bench-'));
     const results: EventResult[] = [];
     let control: EventResult | null = null;

package/src/scripts/build_archive_index.ts

@@ -45,6 +45,7 @@ import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { evaluateDashboardOnDisk, parseModeToken, type DashboardMode } from '../agent-src/scripts/dashboard_mode.js';
 import { GateLedger } from './_lib/gate_ledger.js';
 import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
 import { parse_frontmatter } from './validate_frontmatter.js';
@@ -390,6 +391,39 @@ export function main(argv: readonly string[]): number {
     const json = renderJson(entries);
 
     if (argv.includes('--check')) {
+        // `--untracked-mode` is the same three-state table the dashboard's
+        // `--check` already runs, on a second generated artefact: in-index is a
+        // failure, absent is the declared state, present is still compared
+        // against a fresh render. Untracked never means unchecked. The table
+        // itself lives in `dashboard_mode.ts` and is imported rather than
+        // restated, so the two artefacts cannot drift into different verdicts
+        // for the same observable state.
+        const mode: DashboardMode =
+            argv.map(parseModeToken).find((m) => m !== null) ?? 'tracked';
+        if (mode === 'untracked') {
+            let failed = false;
+            for (const [abs, rel, rendered] of [
+                [mdPath, `${ARCHIVE_REL}/${INDEX_MD}`, md],
+                [jsonPath, `${ARCHIVE_REL}/${INDEX_JSON}`, json],
+            ] as const) {
+                const v = evaluateDashboardOnDisk({
+                    mode,
+                    target: abs,
+                    repo_root: ROOT,
+                    rendered,
+                    rel,
+                    regen: 'Run `task build-archive-index` to regenerate.',
+                    noun: 'archive index',
+                });
+                if (v.stale) {
+                    failed = true;
+                    process.stderr.write(v.error ?? '');
+                } else if (!quiet && v.ok !== null) {
+                    process.stdout.write(v.ok);
+                }
+            }
+            return failed ? 1 : 0;
+        }
         const stale = [
             _read(mdPath) === md ? null : `${ARCHIVE_REL}/${INDEX_MD}`,
             _read(jsonPath) === json ? null : `${ARCHIVE_REL}/${INDEX_JSON}`,