@event4u/agent-config 9.14.0 → 9.16.0

package/src/scripts/prepack-check.mjs

@@ -3,7 +3,7 @@
  * prepack-check.mjs — guard the published artifact.
  *
  * Runs during `npm pack` / `npm publish` AND as a dry-run on every PR
- * (Static Checks workflow). Two gates:
+ * (Static Checks workflow). Four gates:
  *
  *   1. Compiled-bin shape — the TS CLI binary exists, is executable, and
  *      carries the Node shebang before the tarball is built. Otherwise a
@@ -12,6 +12,11 @@
  *   2. Shipped-import completeness — every relative import reachable from
  *      the shipped `src/` trees resolves to a file the `files` whitelist
  *      actually ships (the 8.3.0 ERR_MODULE_NOT_FOUND class).
+ *   3. Lifecycle-target shape — every consumer-side lifecycle script points
+ *      at a target that exists and ships (the 9.8.0 dead-postinstall class).
+ *   4. Router-target shipping — every `routes_to` target in dist/router.json
+ *      resolves inside the shipped `files[]` set, so a `files[]` narrowing
+ *      cannot ship a dead router pointer.
  *
  * Folded from external council pass 2026-05-18 (Phase 1.3 acceptance).
  *
@@ -176,6 +181,40 @@ if (lifecycleErrors.length > 0) {
 }
 process.stderr.write('prepack-check: lifecycle script targets OK\n');
 
+// ---------------------------------------------------------------------------
+// Router-pointer shipping guard (gate 4): every `routes_to` target in
+// dist/router.json must resolve to a file that exists AND is inside the
+// shipped `files[]` set. A `files[]` narrowing that drops a routed target was
+// caught once by a working gate; this makes that catch structural rather than
+// incidental, and moves it to pack time on the causing PR
+// (road-to-gates-that-can-fail Phase 4). The kind→path table is single-sourced
+// from ./router_target_paths.mjs, shared with
+// cmd_conformance.ts::routeTargetPaths — two copies could disagree about where
+// a pointer lives, which is the packaging↔runtime gap this closes.
+//
+// PREPACK_ROUTER_JSON points the gate at a different index (repo-relative or
+// absolute) — used by tests/scripts/prepack_router_targets.test.ts and by the
+// planted-target proof, so dist/router.json itself is never mutated.
+// ---------------------------------------------------------------------------
+import { checkRouterTargetsShipped } from './prepack_router_targets.mjs';
+
+const routerRel = env.PREPACK_ROUTER_JSON ?? 'dist/router.json';
+const routerResult = checkRouterTargetsShipped({
+    routerPath: resolve(routerRel),
+    isShipped,
+    exists: (relPath) => existsSync(resolve(relPath)),
+    readFile: (p) => readFileSync(p, 'utf8'),
+});
+if (routerResult.errors.length > 0) {
+    for (const e of routerResult.errors) {
+        process.stderr.write(`prepack-check: ${e}\n`);
+    }
+    die(`${routerResult.errors.length} router target(s) do not resolve inside the shipped set.`);
+}
+process.stderr.write(
+    `prepack-check: router targets OK (${routerResult.scanned} routes_to target(s) in ${routerRel})\n`,
+);
+
 // Optional: invoked with --verbose dumps the size for tarball-budget bookkeeping.
 if (argv.includes('--verbose')) {
     process.stderr.write(`prepack-check: size=${st.size} bytes\n`);

package/src/scripts/prepack_router_targets.d.mts

@@ -0,0 +1,7 @@
+/** Type declarations for prepack_router_targets.mjs (prepack gate 4). */
+export declare function checkRouterTargetsShipped(opts: {
+    routerPath: string;
+    isShipped: (relPath: string) => boolean;
+    exists: (relPath: string) => boolean;
+    readFile: (absPath: string) => string;
+}): { errors: string[]; scanned: number };

package/src/scripts/prepack_router_targets.mjs

@@ -0,0 +1,93 @@
+/**
+ * prepack_router_targets.mjs — pure core of prepack gate 4.
+ *
+ * Every `routes_to` target in `dist/router.json` must resolve to a file that
+ * (a) exists and (b) is inside the `files[]` whitelist. A pointer that
+ * resolves in the dev tree but is not in the tarball is dead the moment a
+ * consumer installs it — `agent-config conformance`'s `router-pointers` check
+ * then fails on the consumer's machine, for a defect introduced here.
+ *
+ * The kind→path table is NOT defined here: it is imported from
+ * `router_target_paths.mjs`, which `cmd_conformance.ts::routeTargetPaths` also
+ * consumes. One table, two readers — see that file's header for why.
+ *
+ * Extracted from `prepack-check.mjs` for the same reason
+ * `prepack_lifecycle_check.mjs` was: the entry script has top-level side
+ * effects and `process.exit`, so it cannot be imported by a test.
+ * road-to-gates-that-can-fail Phase 4.
+ */
+import { routeTargetPathsPosix } from './router_target_paths.mjs';
+
+/**
+ * @typedef {object} RouterTargetOptions
+ * @property {string} routerPath        Absolute path to the router index.
+ * @property {(relPath: string) => boolean} isShipped  `files[]` membership test.
+ * @property {(relPath: string) => boolean} exists     Existence test, repo-relative.
+ * @property {(absPath: string) => string} readFile    Reader for `routerPath`.
+ */
+
+/**
+ * @param {RouterTargetOptions} opts
+ * @returns {{ errors: string[], scanned: number }}
+ */
+export function checkRouterTargetsShipped(opts) {
+    const { routerPath, isShipped, exists, readFile } = opts;
+    const errors = [];
+    let scanned = 0;
+
+    let router;
+    try {
+        router = JSON.parse(readFile(routerPath));
+    } catch (e) {
+        return {
+            errors: [`router index ${routerPath} unreadable or not JSON: ${e.message}`],
+            scanned: 0,
+        };
+    }
+
+    for (const tier of ['tier_1', 'tier_2']) {
+        for (const entry of router[tier] ?? []) {
+            const ruleId = String(entry?.id ?? '<unnamed rule>');
+            for (const raw of entry?.routes_to ?? []) {
+                const target = String(raw);
+                scanned += 1;
+                const candidates = routeTargetPathsPosix(target);
+                if (candidates.length === 0) {
+                    errors.push(
+                        `${tier}:${ruleId} routes_to ${JSON.stringify(target)} — unparseable ` +
+                            'target or unknown kind (router_target_paths.mjs has no template ' +
+                            'for it), so nothing can be verified as shipped',
+                    );
+                    continue;
+                }
+                const present = candidates.filter((rel) => exists(rel));
+                if (present.length === 0) {
+                    errors.push(
+                        `${tier}:${ruleId} routes_to '${target}' → none of ` +
+                            `[${candidates.join(', ')}] exists in the tree`,
+                    );
+                    continue;
+                }
+                if (!present.some((rel) => isShipped(rel))) {
+                    errors.push(
+                        `${tier}:${ruleId} routes_to '${target}' → ${present[0]} exists but is ` +
+                            'NOT in the package.json `files` whitelist — the pointer would ' +
+                            'ship dead and fail `agent-config conformance` on the consumer',
+                    );
+                }
+            }
+        }
+    }
+
+    // Zero-scope is a failure (Phase 1 of the same roadmap): a router index
+    // that yields no targets means the shape changed under the gate, not that
+    // the package is clean.
+    if (errors.length === 0 && scanned === 0) {
+        errors.push(
+            `scanned 0 routes_to target(s) in ${routerPath} — the scan scope is dead or the ` +
+                'router schema moved; this gate cannot report clean on nothing',
+        );
+    }
+
+    return { errors, scanned };
+}

package/src/scripts/print_required_checks.ts

@@ -61,28 +61,75 @@ const DOCS_ONLY_ALLOWED_TOP: ReadonlySet<string> = new Set([
     'llms.txt',
 ]);
 
+// Check names below are the strings GitHub actually REPORTS, verified against
+// `gh pr checks 1108` on 2026-08-02 (road-to-renewal-foundation Phase 1).
+//
+// They previously named a matrix that had drifted into fiction — `Consistency`,
+// `Skill Lint`, `Tests / install-tests`, `Tests / node-tests`,
+// `Public Install Smoke / smoke`, `Migration Dry-Run`,
+// `Release Validation / release-shape`, `Release Guard (post-tag)` and, most
+// clearly, `Tests / python-tests`, which cannot exist at all: the Python→TS
+// migration completed and `no-python-in-src.yml` now enforces its absence. A
+// preview tool that prints names no check will ever report is worse than no
+// preview — it reads as a verified list.
+//
+// Matrix families are printed as ONE line with the axis spelled out rather than
+// as N pinned contexts. Shard counts and runner labels are part of the reported
+// name, so pinning them here would re-create the same drift on the next matrix
+// change — the exact failure this reconciliation removed.
 const FEATURE_CHECKS = [
-    'Consistency',
-    'Smoke Contracts',
-    'Skill Lint',
-    'Tests / install-tests',
-    'Tests / install-aux-tests',
-    'Tests / python-tests',
-    'Tests / node-tests',
-    'Public Install Smoke / smoke',
+    'Sync + Generate Tools Consistency',
+    'Smoke — kernel',
+    'Smoke — router',
+    'Smoke — schema',
+    'Smoke — skills',
+    'skill-lint',
+    'Static Checks (ESLint · typecheck · prepack)',
+    'Install Script Tests (matrix: {ubuntu,macos}-latest × shard 1-4/4)',
+    'Install Aux Tests (matrix: {ubuntu,macos}-latest)',
+    'Node Tests (matrix: {ubuntu,macos}-latest × shard 1-4/4)',
+    'Golden Tests (matrix: {ubuntu,macos}-latest)',
+    'Workspace Tests (matrix: {ubuntu,macos}-latest)',
+    'Public Install Smoke (matrix: {ubuntu,macos,windows}-latest × node {20,22})',
+    'Rule backstops',
+    'no-python-in-src',
+    'lint commit subjects',
 ] as const;
 
 const RELEASE_CHECKS = [
-    'Consistency',
-    'Smoke Contracts',
-    'Migration Dry-Run',
-    'Release Validation / release-shape',
-    'Release Validation / changelog-entry',
-    'Release Validation / version-consistency',
-    'Release Guard (post-tag)',
+    'Sync + Generate Tools Consistency',
+    'Smoke — kernel',
+    'Smoke — router',
+    'Smoke — schema',
+    'Smoke — skills',
+    'Release-PR shape detector',
+    'CHANGELOG entry exists for head version',
+    'package.json / marketplace.json / pack manifests agree',
+    'Release install E2E (pack → install → upgrade → boot)',
+    'npm audit (runtime deps, high+)',
+    'skill-lint-strict',
 ] as const;
 
-const DOCS_ONLY_CHECKS = ['Consistency', 'Smoke Contracts'] as const;
+const DOCS_ONLY_CHECKS = [
+    'Sync + Generate Tools Consistency',
+    'Smoke — kernel',
+    'Smoke — router',
+    'Smoke — schema',
+    'Smoke — skills',
+] as const;
+
+/**
+ * The checks that mechanically BLOCK a merge, per the repository ruleset
+ * `main protection` (id 17749383). Everything else above runs and is visible
+ * on the PR but does not gate the merge button.
+ *
+ * Deliberately a constant, not an API read: this script is contractually
+ * offline ("never invokes `gh`, never touches the network"). Re-verify with
+ * `gh api repos/event4u-app/agent-config/rulesets/17749383` when the ruleset
+ * changes — `docs/contracts/branch-protection-policy.md` § Change discipline
+ * owns that procedure.
+ */
+const ENFORCED_CHECKS = ['Sync + Generate Tools Consistency'] as const;
 
 /** `git rev-parse --abbrev-ref HEAD`, mirroring `_git(check=True)`. */
 function current_branch(): string {
@@ -161,12 +208,19 @@ function print_set(shape_label: Shape, files: string[]): void {
         'docs-only': DOCS_ONLY_CHECKS,
     };
     const checks = table[shape_label];
+    const enforced: ReadonlySet<string> = new Set(ENFORCED_CHECKS);
     process.stdout.write(`PR shape: ${shape_label}  (${files.length} file(s) in diff)\n`);
-    process.stdout.write(`Required checks (${checks.length}):\n`);
+    process.stdout.write(`Checks this PR will face (${checks.length}):\n`);
     for (const name of checks) {
-        process.stdout.write(`  - ${name}\n`);
+        // `!` marks the checks that actually block the merge button; the rest
+        // run and are visible but are advisory at the branch-protection layer.
+        process.stdout.write(`  ${enforced.has(name) ? '!' : '-'} ${name}\n`);
     }
     process.stdout.write('\n');
+    process.stdout.write(
+        `! = blocks merge (${ENFORCED_CHECKS.length} of ${checks.length}); ` +
+            '- = runs, visible, advisory\n',
+    );
     process.stdout.write(
         'Contract: docs/contracts/branch-protection-policy.md ' +
             '(per-PR-shape matrix)\n',

package/src/scripts/profile_staleness_hook.ts

@@ -37,6 +37,9 @@ import {
   LOCAL_PROJECT_SUBDIR,
 } from "./_lib/agent_settings.js";
 import { readHookStdin } from "./hooks/hook_stdin.js";
+import { probeRanToday, stampProbeRun } from "./hooks/probe_throttle.js";
+
+const THROTTLE_CONCERN = "profile-staleness";
 
 // --- inlined session_profiles.stale_notice slice (unported dep) ----------
 
@@ -143,6 +146,15 @@ export function main(argv?: string[]): number {
   _readStdinIfNotTty();
 
   const root = rootArg !== null ? rootArg : _project_root();
+
+  // Daily throttle (road-to-hook-latency-repair): the overlay does not
+  // change within a day more often than a session ends — one attempt per
+  // local calendar day is enough. Skipped probe re-runs tomorrow.
+  if (probeRanToday(root, THROTTLE_CONCERN)) {
+    return 0;
+  }
+  stampProbeRun(root, THROTTLE_CONCERN);
+
   let notice: string | null;
   try {
     notice = _stale_notice(root);

package/src/scripts/record_evaluator_measurements.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * record_evaluator_measurements.mjs — write the committed measurement record.
+ *
+ * `cli_help_command_count` drifted 74 → 80 against a value frozen at 79 with
+ * nobody seeing it, because the only place the real number existed was a
+ * transient CI log. The fix (road-to-gates-that-can-fail Phase 5; council route
+ * 2026-08-02) is a COMMITTED artifact: the nightly writes the measurement set
+ * here, and `check_evaluator_budgets --recorded` compares a later fresh run
+ * against it — a contradiction warns on `main` and fails on `release/*`. The
+ * review surface that already exists carries the signal; no notification
+ * channel a single maintainer would mute.
+ *
+ * Lives under `agents/evidence/` (the repo's committed-evidence tree), NOT
+ * under `src/config/` which ships: this is maintainer evidence with nightly
+ * churn, not consumer runtime config, and keeping it out of the tarball also
+ * keeps `evaluator-budgets.json` — the policy — reviewable on its own.
+ *
+ * Sorted keys + 4-space indent + trailing newline: a moved number must be a
+ * one-line diff, or the artifact is not reviewable.
+ *
+ * Usage:
+ *   node src/scripts/record_evaluator_measurements.mjs \
+ *     --measurements <file.json> [--out <file.json>]
+ *     [--sha <git sha>] [--run-url <url>] [--conditions <text>]
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { argv, exit, stdout } from 'node:process';
+
+/** Default (repo-relative) home of the record. */
+export const RECORD_REL = 'agents/evidence/metrics/evaluator-measurements.json';
+
+const RECORD_COMMENT =
+    'Written by src/scripts/record_evaluator_measurements.mjs, invoked from ' +
+    'src/scripts/evaluator_umbrella.sh when UMBRELLA_RECORD=1 (the nightly). ' +
+    'check_evaluator_budgets.ts --recorded compares a fresh measurement set against ' +
+    'this file; a contradiction on a DETERMINISTIC metric warns on main and fails on ' +
+    'release. Do not hand-edit — refresh it from a real run.';
+
+/**
+ * Build the record document. Pure — the caller owns the filesystem.
+ *
+ * @param {Record<string, unknown>} measurements
+ * @param {{ recordedAt?: string, sha?: string, runUrl?: string, conditions?: string }} [meta]
+ */
+export function buildRecord(measurements, meta = {}) {
+    const sorted = {};
+    for (const key of Object.keys(measurements).sort()) {
+        sorted[key] = measurements[key];
+    }
+    return {
+        schema_version: 1,
+        _comment: RECORD_COMMENT,
+        recorded_at: meta.recordedAt ?? new Date().toISOString(),
+        git_sha: meta.sha || null,
+        run_url: meta.runUrl || null,
+        conditions: meta.conditions || null,
+        measurements: sorted,
+    };
+}
+
+/** Canonical serialization — stable so an unchanged run produces no diff. */
+export function serializeRecord(doc) {
+    return `${JSON.stringify(doc, null, 4)}\n`;
+}
+
+function argValue(args, flag) {
+    const i = args.indexOf(flag);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+
+export function main(args = argv.slice(2)) {
+    const measurementsPath = argValue(args, '--measurements');
+    if (measurementsPath === undefined) {
+        process.stderr.write(
+            'usage: record_evaluator_measurements --measurements <file.json> ' +
+                '[--out <file.json>] [--sha <sha>] [--run-url <url>] [--conditions <text>]\n',
+        );
+        return 2;
+    }
+    const out = resolve(argValue(args, '--out') ?? RECORD_REL);
+    let measurements;
+    try {
+        measurements = JSON.parse(readFileSync(resolve(measurementsPath), 'utf8'));
+    } catch (e) {
+        process.stderr.write(`record_evaluator_measurements: ${e.message}\n`);
+        return 2;
+    }
+    const doc = buildRecord(measurements, {
+        sha: argValue(args, '--sha'),
+        runUrl: argValue(args, '--run-url'),
+        conditions: argValue(args, '--conditions'),
+    });
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, serializeRecord(doc));
+    stdout.write(
+        `recorded ${Object.keys(doc.measurements).length} measurement(s) → ${out}\n`,
+    );
+    return 0;
+}
+
+if (process.argv[1] !== undefined && resolve(process.argv[1]).endsWith('record_evaluator_measurements.mjs')) {
+    exit(main());
+}

package/src/scripts/recruit_preflight.sh

@@ -107,7 +107,7 @@ fi
 #    exists. /tmp/agent-config-ci-start.txt is written by _ci-start
 #    at the start of every 'task ci' run; /tmp/agent-config-ci-end.txt
 #    by _ci-end on success. Pre-flight passes when both exist AND
-#    end > start AND no .agent-src.uncondensed file is newer than end.
+#    end > start AND no src/ file is newer than end.
 START_MARKER="/tmp/agent-config-ci-start.txt"
 END_MARKER="/tmp/agent-config-ci-end.txt"
 if [ ! -f "$START_MARKER" ] || [ ! -f "$END_MARKER" ]; then