@event4u/agent-config 14.18.0 → 14.20.0

package/src/scripts/autonomy_friction_corpus.ts

@@ -0,0 +1,229 @@
+/**
+ * autonomy_friction_corpus — how many host confirmations each payload class
+ * costs, measured through the real dispatcher.
+ *
+ * WHY A CONFIRMATION COUNT AND NOT A GATE COUNT. "Three gates fire" says
+ * nothing about what the operator experiences; "this call costs one
+ * confirmation" is the quantity the round is about. A corpus counting gates
+ * would go green on a change that fired fewer gates and prompted just as often.
+ *
+ * WHAT IT MEASURES, STATED NARROWLY. The number of confirmations THIS PACKAGE
+ * leaves on the table for a call — 0 when the dispatcher hands the host an
+ * explicit `permissionDecision: allow`, 1 when it emits no permission field and
+ * the host's own machinery decides. It is NOT a measurement of what the host
+ * finally does: a consumer whose settings already allow the call is not
+ * prompted either way, and a confined session ignores our allow entirely
+ * (`permissionDecision=allow ignored: a confined session takes grants only
+ * from its command line`). Reading this as a host-behaviour measurement is the
+ * fact-about-our-plumbing-written-as-a-fact-about-the-host collapse the hook
+ * contract warns about three times.
+ *
+ * A REFUSAL IS NOT A CONFIRMATION. A case the dispatcher blocks (exit 2) is
+ * reported as `refused` and scores no confirmations — counting a refusal as
+ * friction would reward removing a gate, which is the opposite of the point.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/autonomy_friction_corpus [--json]
+ *   ./agent-config …  (no verb — this is a package-internal measurement)
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(HERE, "..", "..");
+const ENTRY = path.join(REPO_ROOT, "src", "scripts", "hooks", "dispatch_entry.ts");
+const TSX_BIN = path.join(
+    REPO_ROOT,
+    "node_modules",
+    ".bin",
+    process.platform === "win32" ? "tsx.cmd" : "tsx",
+);
+
+/** One payload class, with the confirmations it is expected to cost. */
+export interface FrictionCase {
+    id: string;
+    /** The class the owner named, in their words. */
+    klass: string;
+    tool: string;
+    input: Record<string, unknown>;
+    /** Confirmations this call SHOULD cost. */
+    expected: number;
+    /** Why that number, in one line. */
+    because: string;
+}
+
+/** One measured result. */
+export interface FrictionResult extends FrictionCase {
+    observed: number;
+    refused: boolean;
+    pass: boolean;
+}
+
+/**
+ * The six classes the round named, plus the directory-flag form.
+ *
+ * The seventh is not padding: cases 1 and 2 are the shape the canon stopped
+ * teaching, and without the shape that replaced them the corpus would record
+ * the cost and not the fix.
+ */
+export const CASES: readonly FrictionCase[] = [
+    {
+        id: "directory-change",
+        klass: "directory change",
+        tool: "Bash",
+        input: { command: "cd sub" },
+        expected: 1,
+        because:
+            "a bare `cd` is not category A — the canon's answer is a directory flag, " +
+            "not an allow for changing directory",
+    },
+    {
+        id: "directory-change-compounded",
+        klass: "directory change compounded with a status read",
+        tool: "Bash",
+        input: { command: "cd sub && git status" },
+        expected: 1,
+        because:
+            "a compound command is refused before its argv is read — a safe head " +
+            "token must not be able to carry a second command",
+    },
+    {
+        id: "directory-flag-status",
+        klass: "the directory-flag form of the case above",
+        tool: "Bash",
+        input: { command: "git -C sub status" },
+        expected: 0,
+        because: "one simple command, a read-only git subcommand, inside the working tree",
+    },
+    {
+        id: "test-runner-in-subdirectory",
+        klass: "a test runner invoked from a subdirectory",
+        tool: "Bash",
+        input: { command: "vitest run sub" },
+        expected: 0,
+        because: "a test runner admitted by name — the name IS the operation",
+    },
+    {
+        id: "workspace-package-manager",
+        klass: "a workspace package manager",
+        tool: "Bash",
+        input: { command: "npm run test" },
+        expected: 0,
+        because: "a declared subcommand with a declared script name",
+    },
+    {
+        id: "consequence-authorized",
+        klass: "a consequence operation with the authorizing phrase present",
+        tool: "Bash",
+        input: { command: "terraform apply" },
+        expected: 1,
+        because:
+            "the phrase changes the RECORD, never the prompt — after ADR-254 the " +
+            "Hard Floor is model-held and this package grants nothing",
+    },
+    {
+        id: "consequence-unauthorized",
+        klass: "the same operation with the authorizing phrase absent",
+        tool: "Bash",
+        input: { command: "terraform apply" },
+        expected: 1,
+        because:
+            "identical to the case above BY DESIGN — that the two are the same " +
+            "number is the finding, not a defect in the corpus",
+    },
+];
+
+/** Run one case through the real dispatcher and count its confirmations. */
+export function measure(c: FrictionCase, workspace: string): FrictionResult {
+    const payload = JSON.stringify({
+        session_id: "autonomy-friction-corpus",
+        cwd: workspace,
+        hook_event_name: "PreToolUse",
+        tool_name: c.tool,
+        tool_input: c.input,
+    });
+    const r = spawnSync(
+        TSX_BIN,
+        [ENTRY, "--platform", "claude", "--event", "pre_tool_use", "--project-dir", workspace],
+        {
+            encoding: "utf-8",
+            cwd: workspace,
+            input: payload,
+            timeout: 120_000,
+            env: { ...process.env, AGENT_CONFIG_PACKAGE_ROOT: REPO_ROOT },
+        },
+    );
+    const refused = r.status === 2;
+    const allowed = !refused && (r.stdout ?? "").includes('"permissionDecision":"allow"');
+    const observed = refused || allowed ? 0 : 1;
+    return { ...c, observed, refused, pass: refused || observed === c.expected };
+}
+
+export function runCorpus(): FrictionResult[] {
+    const workspace = fs.mkdtempSync(path.join(os.tmpdir(), "ac-friction-"));
+    fs.mkdirSync(path.join(workspace, "sub"), { recursive: true });
+    try {
+        return CASES.map((c) => measure(c, workspace));
+    } finally {
+        fs.rmSync(workspace, { recursive: true, force: true });
+    }
+}
+
+export function render(results: readonly FrictionResult[]): string {
+    const out: string[] = [];
+    out.push("autonomy_friction_corpus — confirmations per payload class");
+    out.push("");
+    out.push("  measured through the real dispatcher; a confirmation is one this");
+    out.push("  package leaves to the host, NOT one the host necessarily shows.");
+    out.push("");
+    for (const r of results) {
+        const mark = r.pass ? "✅" : "❌";
+        const obs = r.refused ? "refused" : String(r.observed);
+        out.push(`  ${mark} ${r.id.padEnd(30)} expected ${r.expected}  observed ${obs}`);
+        out.push(`       ${r.klass}`);
+        out.push(`       ${r.because}`);
+    }
+    const failures = results.filter((r) => !r.pass);
+    out.push("");
+    out.push(
+        failures.length === 0
+            ? `  ${results.length} case(s), every observation matches its expectation`
+            : `  ${failures.length} of ${results.length} case(s) miss their expectation: ` +
+              failures.map((f) => f.id).join(", "),
+    );
+    return out.join("\n") + "\n";
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const json = argv.includes("--json");
+    if (argv.includes("--help") || argv.includes("-h")) {
+        process.stdout.write(
+            "usage: autonomy_friction_corpus [--json]\n" +
+                "  Reports the confirmations each payload class costs, measured\n" +
+                "  through the real dispatcher. Exit 1 when an observation misses\n" +
+                "  its expectation.\n",
+        );
+        return 0;
+    }
+    const results = runCorpus();
+    process.stdout.write(json ? `${JSON.stringify(results, null, 2)}\n` : render(results));
+    return results.every((r) => r.pass) ? 0 : 1;
+}
+
+function _isCliEntry(): boolean {
+    const argv1 = process.argv[1];
+    if (argv1 === undefined) return false;
+    try {
+        return fs.realpathSync(argv1) === fs.realpathSync(fileURLToPath(import.meta.url));
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry()) {
+    process.exit(main());
+}

package/src/scripts/build_proof.ts

@@ -413,10 +413,20 @@ function render(): string {
     {
         const rows = collectEnforcement();
         const s = summariseEnforcement(rows);
+        // The split ships WITH the figure, and the word `yet` travels only with
+        // the half it is true of. `kernel_denied` rules cannot carry an
+        // `enforced_by` field at all — `block_kernel_rule_writes` refuses the
+        // write with no agent-accessible override — so publishing them as "not
+        // declared yet" promises a future that does not exist for them. They
+        // still count as uncovered — the counting policy is unchanged; only the
+        // claim about their future is.
         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).`,
+                `${s.local_only} local-only · ${s.undeclared} undeclared — of which ` +
+                `${s.kernel_denied} kernel-denied (\`block_kernel_rule_writes\` refuses an ` +
+                `\`enforced_by\` write on a kernel rule, so no declaration is reachable ` +
+                `for them at all) and ${s.undeclared - s.kernel_denied} not declared yet.`,
         );
         L.push('');
         // The denominator, WITH the frame that produced it. Until 2026-08-23 the
@@ -436,7 +446,10 @@ function render(): string {
             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(
+            `Undeclared rules (${s.undeclared}, of which ${s.kernel_denied} kernel-denied) ` +
+                'carry no row — an honest gap beats a false claim.',
+        );
     }
     L.push('');
     {

package/src/scripts/build_rule_trigger_matrix.ts

@@ -126,6 +126,11 @@ add('artifact-engagement-recording.md', 'phase-step / task end', 'mechanical-alr
 add('model-recommendation.md', 'task-start / topic-shift', 'hook',
     'output', 'low', '2a', 'no',
     'Phase 5 prototype target. Marker injection at first user msg + topic-change detection.');
+// HISTORICAL row. `src/rules/capture-learnings.md` no longer exists, so this
+// classification is never emitted (the generator keys on files actually present
+// in src/rules/); the live rule for this trigger is `skill-improvement-trigger`,
+// classified two rows below. Kept rather than deleted so the inventory this
+// table records stays readable against the round it was taken in.
 add('capture-learnings.md', 'task completion', 'hook', 'output',
     'medium', '2a', 'no', 'Post-task marker; learning detection is fuzzy');
 add('skill-improvement-trigger.md', 'task completion (settings.skill_improvement)',

package/src/scripts/check_beta_review_markers.ts

@@ -63,28 +63,34 @@ interface LapsedBaseline {
     contracts: string[];
 }
 
-let _baselineCache: Set<string> | null = null;
+// Keyed by root: an unkeyed cache returns the REPO baseline for a fixture root
+// whenever the repo was read first, which silently judges a fixture against
+// production data and is invisible in the result.
+const _baselineCache = new Map<string, Set<string>>();
 
 export function loadLapsedBaseline(root: string = ROOT): Set<string> {
-    if (_baselineCache !== null) {
-        return _baselineCache;
+    const hit = _baselineCache.get(root);
+    if (hit !== undefined) {
+        return hit;
     }
     const p = path.join(root, BASELINE_REL);
     if (!fs.existsSync(p)) {
         // The baseline reaching zero is the SUCCESS state: the file is deleted
         // in the same change that flips the severity. An absent file therefore
         // means "no inherited debt", i.e. every lapse is fresh and errors.
-        _baselineCache = new Set<string>();
-        return _baselineCache;
+        const empty = new Set<string>();
+        _baselineCache.set(root, empty);
+        return empty;
     }
     const parsed = JSON.parse(fs.readFileSync(p, 'utf-8')) as LapsedBaseline;
-    _baselineCache = new Set(parsed.contracts);
-    return _baselineCache;
+    const loaded = new Set(parsed.contracts);
+    _baselineCache.set(root, loaded);
+    return loaded;
 }
 
 /** Test seam — the module-level cache would otherwise outlive a fixture. */
 export function _resetLapsedBaseline(): void {
-    _baselineCache = null;
+    _baselineCache.clear();
 }
 
 /**
@@ -115,12 +121,43 @@ const SUPERSEDED_RE = /^superseded-by:\s*\S+\s*$/m;
 
 const MAX_REVIEW_WINDOW_DAYS = 90;
 
+/**
+ * Forward horizon for the upcoming-lapse report.
+ *
+ * The gate reports a contract on the day it lapses, which is the day it is
+ * already too late to decide anything: a FRESH lapse errors, and every pull
+ * request in the repository reds until someone edits a contract under time
+ * pressure. The horizon names the set that is ABOUT to enter that branch.
+ *
+ * The number is bounded on both sides: too wide and the report names most of
+ * the forward-dated corpus on every run, which is the same as naming none; too
+ * narrow and it arrives after the decision needed to be made.
+ */
+const HORIZON_DAYS = 14;
+
 interface Violation {
     file: string;
     reason: string;
     severity: 'error' | 'warning';
 }
 
+/**
+ * A contract whose window closes within {@link HORIZON_DAYS} and which is NOT
+ * in the frozen baseline — i.e. one that will enter the ERROR branch, not the
+ * inherited-warning one.
+ *
+ * Deliberately NOT a {@link Violation}: it carries no severity and never moves
+ * the exit code. A third severity class printed into the same stream as the 84
+ * standing warnings is the way this work changes nothing (risk 1 on the
+ * roadmap's own register), so the horizon is a separate, clearly-labelled
+ * section and the exit code stays a function of real violations alone.
+ */
+interface Upcoming {
+    file: string;
+    date: string;
+    daysOut: number;
+}
+
 function _exists(p: string): boolean {
     try {
         fs.statSync(p);
@@ -184,7 +221,7 @@ function _ordinalToISO(ordinal: number): string {
     return `${y}-${m}-${d}`;
 }
 
-function check_one(p: string, todayOrdinal: number): Violation[] {
+function check_one(p: string, todayOrdinal: number, root: string = ROOT): Violation[] {
     const fm = read_frontmatter(p);
     if (fm === null) {
         return [];
@@ -199,7 +236,7 @@ function check_one(p: string, todayOrdinal: number): Violation[] {
         ['superseded-by', SUPERSEDED_RE.test(fm)],
     ];
     const setMarkers = markers.filter(([, present]) => present).map(([name]) => name);
-    const rel = _relPosix(p, ROOT);
+    const rel = _relPosix(p, root);
     if (setMarkers.length === 0) {
         return [
             {
@@ -231,7 +268,7 @@ function check_one(p: string, todayOrdinal: number): Violation[] {
         // bound because a lapsed date can never also exceed the forward window,
         // so the order is a readability choice rather than a precedence one.
         if (reviewOrdinal < todayOrdinal) {
-            const inherited = loadLapsedBaseline().has(rel);
+            const inherited = loadLapsedBaseline(root).has(rel);
             const age = todayOrdinal - reviewOrdinal;
             return [
                 {
@@ -263,6 +300,34 @@ function check_one(p: string, todayOrdinal: number): Violation[] {
     return [];
 }
 
+/**
+ * The upcoming-lapse finding for one contract, or `null`.
+ *
+ * Baselined contracts are excluded EXPLICITLY rather than by relying on the
+ * fact that a baselined contract is already lapsed and so cannot also carry a
+ * future date. That implication holds today and is not a property anything
+ * enforces; a guard that is merely vacuous cannot be distinguished from a
+ * guard that is absent, and the difference shows up the first time a baseline
+ * entry is re-dated forward.
+ */
+export function upcoming_one(
+    p: string,
+    todayOrdinal: number,
+    horizonDays: number = HORIZON_DAYS,
+    root: string = ROOT,
+): Upcoming | null {
+    const fm = read_frontmatter(p);
+    if (fm === null || !/^stability:\s*beta\s*$/m.test(fm)) return null;
+    const km = KEEP_RE.exec(fm);
+    if (!km) return null;
+    const rel = _relPosix(p, root);
+    if (loadLapsedBaseline(root).has(rel)) return null;
+    const [ry, rm, rd] = _parseISODate(km[1]!);
+    const reviewOrdinal = _dateOrdinal(ry, rm, rd);
+    const daysOut = reviewOrdinal - todayOrdinal;
+    if (daysOut < 0 || daysOut > horizonDays) return null;
+    return { file: rel, date: _ordinalToISO(reviewOrdinal), daysOut };
+}
 
 /**
  * STABILITY.md's own re-audit condition, as a command instead of as prose.
@@ -302,10 +367,16 @@ interface ParsedArgs {
     trigger: boolean;
     /** Fixture root, for `--self-test`. A fixture is never judged against the repo baseline. */
     root: string | null;
+    horizon: number;
 }
 
 function parse_args(argv: readonly string[]): ParsedArgs {
-    const args: ParsedArgs = { json: false, trigger: false, root: null };
+    const args: ParsedArgs = {
+        json: false,
+        trigger: false,
+        root: null,
+        horizon: HORIZON_DAYS,
+    };
     for (let i = 0; i < argv.length; i += 1) {
         const arg = argv[i] as string;
         if (arg === '--json') {
@@ -313,14 +384,27 @@ function parse_args(argv: readonly string[]): ParsedArgs {
         } else if (arg === '--root') {
             args.root = argv[i + 1] ?? null;
             i += 1;
+        } else if (arg === '--horizon') {
+            const raw = argv[i + 1] ?? '';
+            const n = Number.parseInt(raw, 10);
+            if (!/^\d+$/.test(raw) || Number.isNaN(n)) {
+                process.stderr.write(
+                    `check_beta_review_markers: error: --horizon needs a non-negative integer, got: ${raw || '(nothing)'}\n`,
+                );
+                process.exit(2);
+            }
+            args.horizon = n;
+            i += 1;
         } else if (arg === '--trigger') {
             args.trigger = true;
         } else if (arg === '-h' || arg === '--help') {
             process.stdout.write(
-                'usage: check_beta_review_markers [-h] [--json] [--trigger]\n' +
+                'usage: check_beta_review_markers [-h] [--json] [--trigger] [--horizon N]\n' +
                     '  --trigger  print the lapsed percentage and whether STABILITY.md\n' +
                     '             re-audit condition (>= 25 %) has fired. Reports; never fails.\n' +
-                    '  --root DIR judge a fixture tree instead of the repo (self-test seam).\n',
+                    '  --root DIR judge a fixture tree instead of the repo (self-test seam).\n' +
+                    `  --horizon N  days ahead to report upcoming fresh lapses (default ${String(HORIZON_DAYS)}).\n` +
+                    '             Advisory: never changes the exit code.\n',
             );
             process.exit(0);
         } else {
@@ -400,11 +484,15 @@ function main(): number {
     const scanRoot = args.root ?? ROOT;
     const contracts = _globMdSorted(path.join(scanRoot, CONTRACTS_DIR));
     let betaContracts = 0;
+    const upcoming: Upcoming[] = [];
     for (const p of contracts) {
         const fm = read_frontmatter(p);
         if (fm !== null && /^stability:\s*beta\s*$/m.test(fm)) betaContracts += 1;
-        violations.push(...check_one(p, todayOrdinal));
+        violations.push(...check_one(p, todayOrdinal, scanRoot));
+        const due = upcoming_one(p, todayOrdinal, args.horizon, scanRoot);
+        if (due !== null) upcoming.push(due);
     }
+    upcoming.sort((a, b) => a.daysOut - b.daysOut || a.file.localeCompare(b.file));
     // Count every contract read, not the `stability: beta` subset: over a moved
     // `docs/contracts/` "no beta contracts" and "no contracts at all" produce
     // the same clean line, and only the second is a dead gate. Exit 1 is the
@@ -446,7 +534,9 @@ function main(): number {
         return 0;
     }
     if (args.json) {
-        process.stdout.write(JSON.stringify({ violations }, null, 2) + '\n');
+        process.stdout.write(
+            JSON.stringify({ violations, upcoming, horizonDays: args.horizon }, null, 2) + '\n',
+        );
     } else {
         if (violations.length === 0) {
             process.stdout.write('✅  All beta contracts carry a valid review marker.\n');
@@ -455,7 +545,39 @@ function main(): number {
                 const icon = v.severity === 'error' ? '❌' : '⚠️ ';
                 process.stdout.write(`${icon}  ${v.file}: ${v.reason}\n`);
             }
-            process.stdout.write(`\n${violations.length} violation(s).\n`);
+            // Both counts, and the relationship between them, because a
+            // violation count alone cannot answer "how many contracts is this".
+            // Today they are equal — check_one returns at most one finding per
+            // contract — and printing only one of them hides the fact that it
+            // is the size of the decision, not just the size of the output.
+            const distinct = new Set(violations.map((v) => v.file)).size;
+            const baselineSize = loadLapsedBaseline(scanRoot).size;
+            const reportedInherited = violations.filter((v) =>
+                loadLapsedBaseline(scanRoot).has(v.file),
+            ).length;
+            process.stdout.write(
+                `\n${String(violations.length)} violation(s) across ` +
+                    `${String(distinct)} distinct contract(s) — one line per finding, so the ` +
+                    'two differ only where a contract carries more than one.\n',
+            );
+            process.stdout.write(
+                `Frozen baseline: ${String(baselineSize)} entries · ` +
+                    `${String(reportedInherited)} still reported as lapsed · ` +
+                    `${String(baselineSize - reportedInherited)} inert ` +
+                    '(left the lapsed set by promotion, supersession, or re-dating).\n',
+            );
+        }
+        if (upcoming.length > 0) {
+            process.stdout.write(
+                `\nUpcoming FRESH lapses within ${String(args.horizon)} day(s) — advisory, ` +
+                    'exit code unchanged. These are absent from the frozen baseline, so each\n' +
+                    'becomes an ERROR on its date rather than an inherited warning:\n',
+            );
+            for (const u of upcoming) {
+                process.stdout.write(
+                    `   ${u.file}: keep-beta-until=${u.date} in ${String(u.daysOut)} day(s) [fresh]\n`,
+                );
+            }
         }
     }
     return violations.some((v) => v.severity === 'error') ? 1 : 0;
@@ -495,9 +617,11 @@ if (_isCliEntry() || process.argv[1] === _HERE) {
 
 export {
     type Violation,
+    type Upcoming,
     ROOT,
     CONTRACTS_DIR,
     MAX_REVIEW_WINDOW_DAYS,
+    HORIZON_DAYS,
     read_frontmatter,
     check_one,
     main,

package/src/scripts/check_enforcement_coverage.ts

@@ -118,7 +118,7 @@ export interface RuleCoverage {
     /**
      * Carrier period per hook-capable platform — never a single scalar.
      *
-     * A scalar is wrong twice over: copilot has no hook surface at all, so a
+     * A scalar is wrong twice over: this package binds nothing on copilot, so a
      * weakest-platform collapse turns one platform property into a finding on
      * every hook-carried rule; and cline maps `stop` from `TaskCancel`, so the
      * same slot means per-turn on six platforms and per-interruption there. Both