@event4u/agent-config 9.7.0 → 9.9.0

package/src/scripts/build_proof.ts

@@ -24,6 +24,7 @@ import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import { REPO, LEDGER_REL, load_ledger, pointer_unresolved } from './check_claims.js';
+import { collect as collectEnforcement, summarise as summariseEnforcement } from './check_enforcement_coverage.js';
 import { collectSkillGaps } from './check_skill_gaps.js';
 import { loadRows as loadComparisonRows } from './check_comparison.js';
 import { computeStatus as domainSoundnessStatus } from './domain_soundness_status.js';
@@ -41,6 +42,105 @@ class ExitCode extends Error {
     }
 }
 
+/**
+ * The prevented-failure table.
+ *
+ * Every row names a **failure mode that is prevented**, never a feature. That
+ * constraint is the whole discipline: "cross-platform" is a feature and says
+ * nothing; "the same rules do not silently differ between the agent you run
+ * today and the one you switch to" names what goes wrong without it.
+ *
+ * Every row cites a ledger claim, and `backs` is not decoration — a cited id
+ * that is missing or not `backed` throws, so the table cannot outlive its
+ * evidence. This is the guard against the failure it was modelled on: the
+ * reference ships an equivalent table whose headline efficiency figure appears
+ * only there, an order of magnitude below the cheapest scenario in its own
+ * generated benchmark. A number with nowhere to resolve is exactly what this
+ * ledger exists to catch, so the table is held to the ledger's own bar.
+ *
+ * A row with no resolving claim ships WITHOUT a number rather than with an
+ * approximate one.
+ */
+export const PREVENTED_FAILURES: { failure: string; mechanism: string; backs: string }[] = [
+    {
+        failure: 'A rule says MUST, and nothing anywhere enforces it — so the rule reads as a guarantee while being honour-system.',
+        mechanism:
+            'Each rule declares `enforced_by:`, and the check **resolves** it: a validator reachable from no taskfile, workflow, or hook manifest counts as unwired, not as covered. Undeclared counts as uncovered.',
+        backs: 'enforcement-coverage-resolved',
+    },
+    {
+        failure:
+            'A shipped artefact carries a hidden-Unicode or instruction-smuggling payload, and reaches consumers because only the source tree was scanned.',
+        mechanism:
+            'Source **and** the condensed projection are scanned in CI; a finding blocks the release before publish, not merely the merge.',
+        backs: 'shipped-artifacts-hidden-instruction-scanned',
+    },
+    {
+        failure:
+            'A count in public prose drifts from the source, and the marketing number quietly stops being true.',
+        mechanism:
+            'Counts are generated from source and drift-checked; the build fails on a count-shaped prose mention that disagrees, or on two different numbers for the same artefact kind.',
+        backs: 'skill-count',
+    },
+    {
+        failure:
+            'A host-coverage claim understates or overstates what actually works — for months, on the one surface everybody reads.',
+        mechanism: 'The number is pinned by a test over real detection, and the test is re-run as the claim evidence.',
+        backs: 'host-agent-count',
+    },
+    {
+        failure:
+            'A non-coding domain skill implies proven correctness it never had, because it was forged on a different domain and never checked against one.',
+        mechanism:
+            'Domain skills are labelled unvalidated until they pass a sourced domain-truth fixture, and the validated count is ratcheted so it cannot quietly fall.',
+        backs: 'domain-soundness-scoped',
+    },
+    {
+        failure:
+            'Behavioural-eval coverage regresses as skills are added, and the suite looks healthy because only the absolute number is reported.',
+        mechanism: 'Coverage is measured per tier and ratcheted in CI, so it can only rise; the gap is published rather than implied away.',
+        backs: 'eval-coverage-ratcheted',
+    },
+];
+
+export function renderPreventedFailures(ledger: ReturnType<typeof load_ledger>): string {
+    const L: string[] = [];
+    L.push('## What this prevents');
+    L.push('');
+    L.push('Each row is a failure mode, not a feature — and each cites the ledger');
+    L.push('claim that backs it. A row whose claim stopped resolving would fail this');
+    L.push('page\'s own generator, so the table cannot outlive its evidence.');
+    L.push('');
+    L.push('| Failure this prevents | How | Backed by |');
+    L.push('|---|---|---|');
+    for (const row of PREVENTED_FAILURES) {
+        const entry = ledger.get(row.backs);
+        if (!entry) {
+            throw new Error(
+                `build_proof: prevented-failure row cites claim '${row.backs}', which has no ledger entry. ` +
+                    'Bind it in docs/CLAIMS.md or drop the row — the table may not carry an unbacked cell.',
+            );
+        }
+        if (entry.status !== 'backed') {
+            throw new Error(
+                `build_proof: prevented-failure row cites claim '${row.backs}', whose ledger status is ` +
+                    `'${entry.status}', not 'backed'. The table may not carry an unbacked cell.`,
+            );
+        }
+        const reverifies = entry.evidence.trim().startsWith('exec:') ? ' ⟳' : '';
+        L.push(
+            `| ${row.failure.replace(/\|/g, '\\|')} | ${row.mechanism.replace(/\|/g, '\\|')} | ` +
+                `[\`${row.backs}\`](CLAIMS.md)${reverifies} |`,
+        );
+    }
+    L.push('');
+    L.push('⟳ — the claim carries `exec:` evidence: CI re-runs the command and');
+    L.push('compares its exit code, so a stale row turns the build red rather than');
+    L.push('ageing quietly into marketing.');
+    L.push('');
+    return L.join('\n');
+}
+
 function render(): string {
     const ledger = load_ledger();
     const entries = [...ledger.values()].sort((a, b) => a.id.localeCompare(b.id));
@@ -59,6 +159,7 @@ function render(): string {
     L.push('every check below on a fresh checkout. This page is itself generated');
     L.push('from those sources and fails CI if it drifts.');
     L.push('');
+    L.push(renderPreventedFailures(ledger));
     L.push('## See it run (< 60s, real output)');
     L.push('');
     L.push('![The trust surface running green — every "verify it yourself" command below, recorded from a real run](media/proof-demo.gif)');
@@ -86,6 +187,39 @@ function render(): string {
     L.push('');
     L.push(`**${backed.length} backed claim(s)** — all evidence pointers resolve in CI.`);
     L.push('');
+
+    // Re-verifiable vs. merely-resolving. The distinction is the point: a
+    // pointer proves an artefact exists, not that the claim is still true. Any
+    // page that reported only the backed total would hide exactly the gap this
+    // ledger was built to expose.
+    const execBacked = backed.filter((e) => e.evidence.trim().startsWith('exec:'));
+    const pointerOnly = backed.filter((e) => !e.evidence.trim().startsWith('exec:'));
+    L.push('### How many of those re-derive themselves');
+    L.push('');
+    L.push(`**${execBacked.length} of ${backed.length}** backed claims carry \`exec:\` evidence —`);
+    L.push('CI re-runs the command and compares its exit code to the claim, so a');
+    L.push('stale one turns the build red. The other');
+    L.push(`**${pointerOnly.length}** rest on a pointer: CI checks that the artefact`);
+    L.push('exists and contains what it should, which cannot distinguish a live');
+    L.push('claim from one whose producer nobody has run in months.');
+    L.push('');
+    L.push('That residue is not an oversight, and it is listed rather than rounded');
+    L.push('away. A claim can only re-derive itself when a deterministic command');
+    L.push("carries the verdict in its exit code. These cannot, for the reasons");
+    L.push('given:');
+    L.push('');
+    L.push('| Claim | Why it cannot re-execute |');
+    L.push('|---|---|');
+    for (const e of pointerOnly) {
+        const ev = e.evidence.trim();
+        const why = /^https?:\/\//.test(ev)
+            ? 'external cite — CI does not fetch the network'
+            : /benchmark|bench\/|results-/.test(ev)
+              ? 'benchmark output — regenerating it needs paid or stochastic model calls no CI job can re-derive'
+              : 'prose or contract artefact — no exit code carries the verdict';
+        L.push(`| ${e.claim.replace(/\|/g, '\\|').slice(0, 110)} | ${why} |`);
+    }
+    L.push('');
     L.push('Artefact counts in public prose (skills, commands, governed rules,');
     L.push('guidelines, personas) are **generated from source and CI-drift-checked**:');
     L.push('`update_counts.ts` writes the numbers, `check_artefact_count_messaging.ts`');
@@ -224,6 +358,79 @@ function render(): string {
             L.push(`| ${claim} | ${ours} | ${theirs} | ${r.checkable ? '✅' : '—'} |`);
         }
     }
+
+    // Second lens on the SAME rows: what each one prevents, for a reader who has
+    // not asked "compared to what". Membership is a data property — a row appears
+    // here iff it carries a `failure_mode` — so nobody curates a short-list that
+    // then drifts from the table above. The pointer is the same pointer, resolved
+    // by the same gate, so no cell reaches this view unbound.
+    const fmRows = cmpRows.filter((r) => (r.failure_mode ?? '').trim() !== '');
+    if (fmRows.length > 0) {
+        L.push('');
+        L.push('### What each one prevents');
+        L.push('');
+        L.push('The same rows, read as failure modes rather than as comparisons. Each names');
+        L.push('something that goes wrong without the control and carries the identical');
+        L.push('resolvable pointer — a projection of the table above, not a second list to');
+        L.push('keep in sync.');
+        L.push('');
+        L.push('| Without it | The control | Evidence |');
+        L.push('|---|---|---|');
+        for (const r of fmRows) {
+            const fm = (r.failure_mode ?? '').replace(/\|/g, '\\|').trim();
+            const claim = r.claim.replace(/\|/g, '\\|');
+            const filePart = (r.our_evidence.split('#')[0] ?? r.our_evidence).split(':')[0] ?? r.our_evidence;
+            const ours = pointer_unresolved(r.our_evidence) === null
+                ? `[\`${r.our_evidence}\`](../${filePart})`
+                : `\`${r.our_evidence}\``;
+            L.push(`| ${fm} | ${claim} | ${ours} |`);
+        }
+    }
+
+    L.push('');
+    L.push('## 4b. The two existing axes — enforcement level per rule, evidence form per claim');
+    L.push('');
+    L.push('Pure projection of what the repo already knows — the `enforced_by`');
+    L.push('resolution (`check_enforcement_coverage`) and the claims ledger');
+    L.push(`(\`${LEDGER_REL}\`). No new taxonomy, zero hand-written rows.`);
+    L.push('');
+    {
+        const rows = collectEnforcement();
+        const s = summariseEnforcement(rows);
+        L.push(
+            `**Axis 1 — enforcement level per rule.** ${s.total} rules · ` +
+                `${s.blocking} blocking (${s.blocking_pct}%) · ${s.observer} observer · ` +
+                `${s.local_only} local-only · ${s.undeclared} undeclared (no \`enforced_by\` yet).`,
+        );
+        L.push('');
+        L.push('| Rule | Effective level | Declared backstop(s) |');
+        L.push('|---|---|---|');
+        const declared = rows
+            .filter((r) => r.declared.length > 0)
+            .sort((a, b) => a.id.localeCompare(b.id));
+        for (const r of declared) {
+            const decl = r.declared.map((d) => `\`${d}\``).join('<br>');
+            L.push(`| \`${r.id}\` | ${r.effective} | ${decl} |`);
+        }
+        L.push('');
+        L.push(`Undeclared rules (${s.undeclared}) carry no row — an honest gap beats a false claim.`);
+    }
+    L.push('');
+    {
+        const ledger = [...load_ledger().values()].sort((a, b) => a.id.localeCompare(b.id));
+        const backed = ledger.filter((e) => e.status === 'backed').length;
+        L.push(
+            `**Axis 2 — evidence form per public claim.** ${ledger.length} ledger entries · ` +
+                `${backed} backed · ${ledger.length - backed} unbacked inventory.`,
+        );
+        L.push('');
+        L.push('| Claim id | Kind | Status | Evidence pointer |');
+        L.push('|---|---|---|---|');
+        for (const e of ledger) {
+            const ev = e.evidence.length > 0 ? `\`${e.evidence.replace(/\|/g, '\\|')}\`` : '—';
+            L.push(`| \`${e.id}\` | ${e.kind} | ${e.status} | ${ev} |`);
+        }
+    }
     L.push('');
     L.push('## 5. Verify it yourself');
     L.push('');

package/src/scripts/chat_history.ts

@@ -46,6 +46,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { _entry_tokens_estimate } from './memory_lookup.js';
 
 import { load_agent_settings } from './_lib/agent_settings.js';
+import { readHookStdin } from './hooks/hook_stdin.js';
 
 export const DEFAULT_FILE = 'agents/runtime/.agent-chat-history';
 export const DEFAULT_SETTINGS_FILE = '.agent-settings.yml';
@@ -2303,11 +2304,7 @@ function _cmd_rotate(argv: string[]): number {
 }
 
 function _readStdin(): string {
-    try {
-        return fs.readFileSync(0, 'utf-8');
-    } catch {
-        return '';
-    }
+    return readHookStdin();
 }
 
 export function main(argv: string[] = process.argv.slice(2)): number {
@@ -2354,7 +2351,13 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     }
 }
 
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url` (see cmd_migrate.ts).
+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;
     }

package/src/scripts/check_adr_frontmatter.ts

@@ -0,0 +1,195 @@
+#!/usr/bin/env tsx
+/**
+ * ADR frontmatter gate — and the `review_trigger` field that makes a decision
+ * revisitable on purpose rather than by archaeology.
+ *
+ * Two findings drive this. First, ADR frontmatter was **entirely unvalidated**:
+ * `validate_frontmatter.ts` covers skills, rules, commands, and personas, and
+ * nothing covered `docs/decisions/`. That is why `review_date` drifted into 11
+ * ADRs and back out again with nobody noticing.
+ *
+ * Second, of 128 ADRs, zero named the condition under which they should be
+ * reconsidered — while `decision-record` SKILL § step 4 already *mandates* a
+ * "Revisit-if" line and `decision-revisit-gate` already treats an ADR as a lock
+ * that must be re-openable. The doctrine was canon; the template just never
+ * emitted a slot for it, so 33 authors wrote it in prose and it stayed
+ * unfindable. This is a missing field, not a missing idea.
+ *
+ * `review_trigger` is a named CONDITION, never a date. "Review annually" is
+ * ignored by everyone and rots into ceremony; "when a second consumer reports a
+ * preservation surprise" fires exactly when it should.
+ *
+ * Grandfathering is by authorship date, not an allowlist: ADRs dated before the
+ * switch warn, ADRs dated on or after it fail. No list to maintain and no
+ * exemption to forget — a retrofit of 128 files would be busywork that teaches
+ * nobody anything.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/check_adr_frontmatter          # gate
+ *   ./scripts-run src/scripts/check_adr_frontmatter --json
+ *
+ * Exit codes: 0 ok (warnings allowed) · 1 violation · 2 usage/env error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(_HERE, '..', '..');
+const ADR_DIR = path.join(REPO_ROOT, 'docs', 'decisions');
+
+/**
+ * Grandfathering switch. ADRs dated before this warn on a missing
+ * `review_trigger`; ADRs dated on or after it fail.
+ */
+export const REVIEW_TRIGGER_SINCE = '2026-07-25';
+
+/** Fields every ADR must carry — the shape that already exists in practice. */
+const REQUIRED = ['adr', 'status', 'date', 'decision'] as const;
+
+const ALLOWED_STATUS = new Set([
+    'accepted',
+    'proposed',
+    'superseded',
+    'rejected',
+    'deprecated',
+    'draft',
+]);
+
+export interface AdrFinding {
+    file: string;
+    level: 'error' | 'warn';
+    message: string;
+}
+
+export function parse_frontmatter(text: string): Record<string, string> | null {
+    if (!text.startsWith('---\n')) return null;
+    const end = text.indexOf('\n---\n', 4);
+    if (end === -1) return null;
+    const out: Record<string, string> = {};
+    let key: string | null = null;
+    for (const raw of text.slice(4, end).split('\n')) {
+        const line = raw.replace(/\s+$/, '');
+        if (!line || line.trimStart().startsWith('#')) continue;
+        // Continuation of a folded/indented value.
+        if (/^\s/.test(line) && key) {
+            out[key] = `${out[key]} ${line.trim()}`.trim();
+            continue;
+        }
+        const idx = line.indexOf(':');
+        if (idx === -1) continue;
+        key = line.slice(0, idx).trim();
+        out[key] = line
+            .slice(idx + 1)
+            .trim()
+            .replace(/^["'](.*)["']$/, '$1');
+    }
+    return out;
+}
+
+/** A trigger must name a condition. A bare cadence is the failure mode. */
+export function trigger_is_meaningful(value: string): boolean {
+    const v = value.trim();
+    if (v.length < 20) return false;
+    // "annually" / "every 6 months" / a bare date is a calendar, not a condition.
+    if (/^(annually|yearly|quarterly|monthly|every\s+\d+\s+\w+|\d{4}-\d{2}-\d{2})\.?$/i.test(v)) {
+        return false;
+    }
+    return true;
+}
+
+export function check(dir: string = ADR_DIR): AdrFinding[] {
+    const findings: AdrFinding[] = [];
+    if (!fs.existsSync(dir)) return findings;
+
+    for (const name of fs.readdirSync(dir).sort()) {
+        if (!/^ADR-.*\.md$/.test(name)) continue;
+        const rel = path.relative(REPO_ROOT, path.join(dir, name));
+        const fm = parse_frontmatter(fs.readFileSync(path.join(dir, name), 'utf-8'));
+
+        if (fm === null) {
+            findings.push({ file: rel, level: 'error', message: 'no YAML frontmatter block' });
+            continue;
+        }
+        for (const req of REQUIRED) {
+            if (!fm[req]) findings.push({ file: rel, level: 'error', message: `missing \`${req}\`` });
+        }
+        if (fm['status'] && !ALLOWED_STATUS.has(fm['status'])) {
+            findings.push({
+                file: rel,
+                level: 'error',
+                message: `status \`${fm['status']}\` is not one of: ${[...ALLOWED_STATUS].sort().join(', ')}`,
+            });
+        }
+
+        const date = fm['date'] ?? '';
+        const grandfathered = date !== '' && date < REVIEW_TRIGGER_SINCE;
+        const trigger = fm['review_trigger'];
+
+        if (!trigger) {
+            findings.push({
+                file: rel,
+                level: grandfathered ? 'warn' : 'error',
+                message: grandfathered
+                    ? `no \`review_trigger\` (grandfathered — dated ${date}, before ${REVIEW_TRIGGER_SINCE})`
+                    : `missing \`review_trigger\` — name the CONDITION that would reopen this decision`,
+            });
+        } else if (!trigger_is_meaningful(trigger)) {
+            findings.push({
+                file: rel,
+                level: grandfathered ? 'warn' : 'error',
+                message: `\`review_trigger\` is a cadence, not a condition: "${trigger}". A calendar review is ignored; an event fires.`,
+            });
+        }
+    }
+    return findings;
+}
+
+function main(argv: string[]): number {
+    const as_json = argv.includes('--json');
+    const findings = check();
+
+    if (as_json) {
+        process.stdout.write(JSON.stringify({ findings }, null, 2) + '\n');
+        return 0;
+    }
+
+    const errors = findings.filter((f) => f.level === 'error');
+    const warns = findings.filter((f) => f.level === 'warn');
+    const total = fs.existsSync(ADR_DIR)
+        ? fs.readdirSync(ADR_DIR).filter((f) => /^ADR-.*\.md$/.test(f)).length
+        : 0;
+
+    process.stdout.write(
+        `ADR frontmatter: ${total} ADR(s) · ${errors.length} error(s) · ` +
+            `${warns.length} grandfathered without a revisit condition\n`,
+    );
+    for (const e of errors) process.stderr.write(`    ❌ ${e.file}: ${e.message}\n`);
+
+    if (errors.length > 0) {
+        process.stderr.write(
+            `\n❌  check_adr_frontmatter: ${errors.length} error(s). ` +
+                `ADRs dated ${REVIEW_TRIGGER_SINCE} or later must name a \`review_trigger\`.\n`,
+        );
+        return 1;
+    }
+    process.stdout.write('✅  check_adr_frontmatter: no errors\n');
+    return 0;
+}
+
+// Main-guard (realpath-compared, mirrors the repo convention).
+if (process.argv[1] !== undefined) {
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv1 = fs.realpathSync(path.resolve(process.argv[1]));
+        if (here === argv1) {
+            process.exit(main(process.argv.slice(2)));
+        }
+    } catch {
+        const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+        if (import.meta.url === argvUrl) {
+            process.exit(main(process.argv.slice(2)));
+        }
+    }
+}

package/src/scripts/check_artefact_count_messaging.ts

@@ -53,6 +53,10 @@ export const SURFACES: readonly string[] = [
     'docs/featured-skills.md',
     'docs/featured-commands.md',
     'docs/proof.md',
+    // Public submission text: the block here described version 3.2.0 with a
+    // "4929 tests" figure while the package reached 9.7.0, because nothing
+    // watched this file. Added 2026-07-25 so a hand-typed count here fails CI.
+    'docs/distribution/registries.md',
     'site/src/content/docs/index.mdx',
     'site/src/content/docs/claims.md',
 ];