@event4u/agent-config 9.13.0 → 9.15.0

package/src/scripts/check_iron_law_prominence.ts

@@ -5,7 +5,7 @@
  *
  * Ported from the retired Python `src/scripts/check_iron_law_prominence.py` (ADR-200,
  * Phase 4 / Wave 4c). The CLI contract is pinned — positional
- * paths (default `.agent-src.uncondensed/rules`), `--format` / `--quiet`
+ * paths (default `src/rules`), `--format` / `--quiet`
  * flags, exit codes (0 clean, 1 violations, 3 internal error),
  * stdout/stderr split, byte-identical finding messages, and the same
  * heading parse / code-fence skipping. No behaviour changes — latent bugs

package/src/scripts/check_kernel_rule_bundle.ts

@@ -11,7 +11,7 @@
  * historical quirks preserved (consumers pin the exact behaviour).
  *
  * Fails when a single PR (or commit range) modifies more than one
- * kernel rule under `.agent-src.uncondensed/rules/`. Override via the
+ * kernel rule under `src/rules/`. Override via the
  * PR label `bundled-always-rules-acknowledged`.
  *
  * Kernel set is the locked 9-rule list in

package/src/scripts/check_no_new_legacy_path.ts

@@ -45,12 +45,20 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { checkRatchet } from './_lib/gate_baseline.js';
+
 const LEGACY = '.agent-src.uncondensed/';
 const EXEMPT: ReadonlySet<string> = new Set([
     'src/scripts/_lib/agent_src.py',
     'src/scripts/check_references.py',
     'src/scripts/check_condensed_paths.py',
     'src/scripts/check_no_new_legacy_path.py', // this file documents the literal
+    // The `.ts` twin needs its own entry now: the docstring above says the
+    // faithful-twin rule covers it, but that rule reads a `.py` sibling from
+    // disk and the py2ts final deletion removed every sibling — so since then
+    // ANY edit to this guard's own message strings flags the guard. Surfaced
+    // by the Phase-5 edit that added the existing-literal pass below.
+    'src/scripts/check_no_new_legacy_path.ts',
     'src/scripts/check_source_pointer_freshness.ts', // forbidden-substring detector for the legacy tree
 ]);
 
@@ -131,6 +139,154 @@ function find_offenders(diffText: string, twinCheck: TwinCheck = _is_faithful_tw
     return offenders;
 }
 
+// ---------------------------------------------------------------------------
+// Pass 2 — EXISTING hardcoded legacy scan roots (ratcheted).
+//
+// The diff pass above stops the debt from growing. It is structurally blind to
+// the debt that is already there — and every one of the 14 dead gates found in
+// 2026-07 was pre-existing, so a new-violations-only check could never have
+// seen them (road-to-gates-that-can-fail Phase 5).
+//
+// WHY THIS IS NOT THE FULL-TREE LINT THAT WAS ALREADY REJECTED. The note in
+// `find_offenders` records a measured rejection: a full-tree lint over `tests/`
+// hits 44 files / 213 lines, most of them legitimate (the legacy detectors'
+// own test data, `validator_ignore` substrings, synthetic tmpdir fixtures), so
+// the signal drowns. That measurement stands and this pass does not repeat it.
+// Three things make this scope different:
+//
+//   1. It reads EXECUTABLE code only — `src/scripts/**/*.{ts,mts,mjs}`. No
+//      prose, no docs, no tests, no fixtures.
+//   2. It counts only lines that CONSTRUCT A PATH — the literal must reach
+//      `path.join(...)` inside a string. A detector holding the literal as
+//      data to match, strip, or print is not a scan root and is not counted.
+//      Measured on 2026-08-02: 236 raw mentions in src/scripts → 147 string
+//      literals → 70 path-constructing lines. The narrowing is the point.
+//   3. It is a RATCHET, not a hard fail. The current count is committed to
+//      `src/config/gate-violation-baselines.json`; the gate goes red only when
+//      the count RISES. Every Phase-1 repair lowers it, and the baseline's
+//      56-day expiry (see `_lib/gate_baseline.ts`) stops a stalled number from
+//      hardening into configuration.
+// ---------------------------------------------------------------------------
+
+/** Gate key in `src/config/gate-violation-baselines.json`. */
+export const HARDCODED_ROOT_GATE = 'check_no_new_legacy_path:hardcoded-scan-roots';
+
+/** The executable-code root this pass reads. */
+export const HARDCODED_ROOT_SCAN_DIR = 'src/scripts';
+
+/** Bare directory name — the form that appears inside a `path.join(...)` call. */
+const LEGACY_DIRNAME = LEGACY.replace(/\/+$/, '');
+
+/**
+ * Files allowed to construct a legacy path forever.
+ *
+ * `_lib/agent_src.ts` is the shared resolver — owning the constant is its whole
+ * job, and every gate that routes through it survived the ADR-051 move. Exempting
+ * it is what makes the count mean "gates that bypassed the resolver".
+ */
+const HARDCODED_ROOT_EXEMPT: ReadonlySet<string> = new Set(['src/scripts/_lib/agent_src.ts']);
+
+const _STRING_LITERAL_LEGACY = new RegExp(
+    `['"\`][^'"\`]*${LEGACY_DIRNAME.replace(/\./g, '\\.')}`,
+);
+
+function _isCommentLine(trimmed: string): boolean {
+    return (
+        trimmed.startsWith('//') ||
+        trimmed.startsWith('*') ||
+        trimmed.startsWith('/*') ||
+        trimmed.startsWith('#')
+    );
+}
+
+function* _walkScripts(dir: string): Generator<string> {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return;
+    }
+    for (const e of entries) {
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) {
+            yield* _walkScripts(full);
+        } else if (/\.(ts|mts|mjs)$/.test(e.name) && !/\.d\.m?ts$/.test(e.name)) {
+            yield full;
+        }
+    }
+}
+
+/**
+ * Lines under `src/scripts/` that build a filesystem path against the retired
+ * tree. Returns `file:line: <source>` strings, sorted by path.
+ *
+ * `repoRoot` defaults to cwd (CI runs the guard at the repo root) and is
+ * injectable so tests can point at a fixture tree.
+ */
+export function find_hardcoded_scan_roots(
+    repoRoot: string = process.cwd(),
+    twinCheck: TwinCheck = _is_faithful_twin,
+): string[] {
+    const root = path.join(repoRoot, HARDCODED_ROOT_SCAN_DIR);
+    const findings: string[] = [];
+    for (const abs of _walkScripts(root)) {
+        const rel = path.relative(repoRoot, abs).split(path.sep).join('/');
+        if (EXEMPT.has(rel) || HARDCODED_ROOT_EXEMPT.has(rel) || twinCheck(rel)) {
+            continue;
+        }
+        let text: string;
+        try {
+            text = fs.readFileSync(abs, 'utf-8');
+        } catch {
+            continue;
+        }
+        if (!text.includes(LEGACY_DIRNAME)) {
+            continue;
+        }
+        text.split('\n').forEach((line, i) => {
+            if (!line.includes(LEGACY_DIRNAME)) return;
+            const trimmed = line.trim();
+            if (_isCommentLine(trimmed)) return;
+            if (!/path\.join\s*\(/.test(line)) return;
+            if (!_STRING_LITERAL_LEGACY.test(line)) return;
+            findings.push(`${rel}:${i + 1}: ${trimmed.slice(0, 100)}`);
+        });
+    }
+    findings.sort();
+    return findings;
+}
+
+/**
+ * Run the existing-literal pass and judge it against the committed baseline.
+ * Returns 0 when the count is at or below the baseline (and the baseline is
+ * fresh), 1 otherwise. Prints either way — a passing ratchet still reports the
+ * live number, which is the whole point of committing it.
+ */
+export function checkHardcodedScanRoots(repoRoot: string = process.cwd()): number {
+    const findings = find_hardcoded_scan_roots(repoRoot);
+    const verdict = checkRatchet({
+        gate: HARDCODED_ROOT_GATE,
+        actual: findings.length,
+        repoRoot,
+    });
+    if (verdict.ok) {
+        process.stdout.write(`✅  ${verdict.message}\n`);
+        return 0;
+    }
+    process.stdout.write(
+        `❌  Hardcoded \`${LEGACY}\` scan root(s) under ${HARDCODED_ROOT_SCAN_DIR}/ ` +
+            'above the recorded baseline:\n',
+    );
+    for (const f of findings.slice(0, 20)) {
+        process.stdout.write(`  🔴 ${f}\n`);
+    }
+    if (findings.length > 20) {
+        process.stdout.write(`  … and ${findings.length - 20} more\n`);
+    }
+    process.stdout.write(`\n${verdict.message}\n`);
+    return 1;
+}
+
 function main(): number {
     // --stdin: read a unified diff from stdin (CI pipes `gh pr diff` — auth-safe,
     // no `git fetch <base>` extraheader race on shallow PR-merge checkouts, the
@@ -170,6 +326,7 @@ function main(): number {
         offenders = find_offenders((proc.stdout as string | null) ?? '');
     }
 
+    let rc = 0;
     if (offenders.length) {
         process.stdout.write(
             '❌  New `.agent-src.uncondensed/` reference(s) added under src/ ' +
@@ -182,11 +339,18 @@ function main(): number {
             '\nFix: reference the real `src/` target. Existing stale prose is ' +
                 'migrated opportunistically; do not ADD new dead-path references.\n',
         );
-        return 1;
+        rc = 1;
+    } else {
+        process.stdout.write('✅  No new `.agent-src.uncondensed/` references added under src/.\n');
     }
 
-    process.stdout.write('✅  No new `.agent-src.uncondensed/` references added under src/.\n');
-    return 0;
+    // Pass 2 — the pre-existing hardcoded scan roots the diff pass cannot see.
+    // Skippable for the golden-parity harness, which compares this guard's
+    // diff behaviour against a pinned reference implementation.
+    if (!process.argv.includes('--no-existing')) {
+        rc = Math.max(rc, checkHardcodedScanRoots());
+    }
+    return rc;
 }
 
 const _HERE = fileURLToPath(import.meta.url);

package/src/scripts/check_pack_size.ts

@@ -55,12 +55,26 @@ export interface PackSizeBudget {
 /**
  * Parse `npm pack --json` stdout. npm runs the `prepare` lifecycle script even
  * under `--ignore-scripts` on some versions, and this repo's `prepare` prints a
- * banner — straight into the stream we parse. Slice from the first `[` so a
- * lifecycle banner is tolerated instead of becoming a SyntaxError.
+ * banner — straight into the stream we parse. Slice from a `[` so a lifecycle
+ * banner is tolerated instead of becoming a SyntaxError.
+ *
+ * Not the FIRST `[`: npm echoes the lifecycle command line, and this repo's own
+ * `prepare` is `[ -d .git ] && bash src/scripts/install-hooks.sh || true` — its
+ * `[` precedes the payload's. Try each candidate offset in order and keep the
+ * first that actually parses (road-to-gates-that-can-fail Phase 6.2).
  */
 export function parsePackJson(stdout: string): PackResult {
-    const start = stdout.indexOf('[');
-    const parsed = JSON.parse(start >= 0 ? stdout.slice(start) : stdout) as PackResult[];
+    let parsed: PackResult[] | null = null;
+    for (let i = stdout.indexOf('['); i >= 0; i = stdout.indexOf('[', i + 1)) {
+        try {
+            parsed = JSON.parse(stdout.slice(i)) as PackResult[];
+            break;
+        } catch {
+            // Not the payload — a banner bracket. Keep scanning.
+        }
+    }
+    // No candidate parsed: reproduce the original SyntaxError from the raw text.
+    parsed ??= JSON.parse(stdout) as PackResult[];
     const first = parsed[0];
     if (first === undefined) throw new Error('npm pack --json returned an empty array');
     return first;

package/src/scripts/check_portability.ts

@@ -8,7 +8,7 @@
  * same finding text, same scan scope and file-walk order. No behaviour
  * changes; latent bugs are replicated and flagged as divergence candidates.
  *
- * Scans dist/agent-src/ and .agent-src.uncondensed/ for project-specific
+ * Scans src/ and dist/agent-src/ for project-specific
  * references that violate package portability (the package must work in ANY
  * project).
  *
@@ -271,10 +271,25 @@ const ALLOWLIST: string[] = [
     'package repository', // "package repository" concept
     'src/scripts/mcp_server/', // MCP server module path (road-to-mcp-server.md Phase 1)
     String.raw`scripts\.mcp_server`, // MCP server Python module entrypoint
+    // ── Revealed 2026-08-02 when `src/` entered SCAN_DIRS (dead-root repair,
+    // road-to-renewal-foundation Phase 1). Both live under `src/templates/`,
+    // which is never projected into `dist/agent-src/`, so this gate had never
+    // seen them. Neither is a CONSUMER-project leak — they are the package's
+    // own published identifiers, which a consumer must type verbatim:
+    String.raw`plugin install agent-conf@`, // real marketplace install command
+    String.raw`\.event4u-bridge\.yml`, // real shipped anchor filename (src/scripts/install.ts, lint_agents_layout.ts)
 ];
 
-// Directories to scan (only package files, not project-specific agents/)
-const SCAN_DIRS = ['dist/agent-src', '.agent-src.uncondensed'];
+// Directories to scan (only package files, not project-specific agents/).
+//
+// DEAD-ROOT REPAIR (road-to-renewal-foundation Phase 1): the second entry was
+// `.agent-src.uncondensed`, deleted by ADR-051. The loops below `continue` on a
+// missing directory, so half this gate's declared corpus — the whole authoring
+// tree — was silently skipped. A project identifier authored in `src/` was only
+// ever caught once a condense run projected it into `dist/agent-src/`, i.e. one
+// step later than the gate claims to catch it. `src/` is the source of truth
+// now and is scanned directly.
+const SCAN_DIRS = ['src', 'dist/agent-src'];
 
 // Additional root-level files shipped by the package that must also stay
 // portable. These are read by agents working on the package itself and —
@@ -608,11 +623,20 @@ function check_cli_invocations(filepath: string): Violation[] {
     return violations;
 }
 
-function scan_all(root: string): { violations: Violation[]; detected: string[] } {
+function scan_all(root: string): {
+    violations: Violation[];
+    detected: string[];
+    scanned: number;
+} {
     const { patterns, detected } = _compile_patterns(root);
     const forbidden = _compile_forbidden_patterns();
     const allowlist = _compile_allowlist();
     const violations: Violation[] = [];
+    // Distinct files actually read, for the gate-coverage contract
+    // (src/config/gate-coverage.yml): a gate that inspected nothing has not
+    // passed. Counted as a set because the layer-3/4 passes revisit files the
+    // layer-1 pass already read.
+    const scannedFiles = new Set<string>();
 
     // Layer 1 + 2: full package content
     for (const scanDir of SCAN_DIRS) {
@@ -621,6 +645,7 @@ function scan_all(root: string): { violations: Violation[]; detected: string[] }
             continue;
         }
         for (const f of _rglobMdSorted(d)) {
+            scannedFiles.add(f);
             violations.push(...check_file(f, [...patterns, ...forbidden], allowlist));
         }
     }
@@ -629,6 +654,7 @@ function scan_all(root: string): { violations: Violation[]; detected: string[] }
     for (const rel of SCAN_ROOT_FILES) {
         const f = path.join(root, rel);
         if (_isFile(f)) {
+            scannedFiles.add(f);
             violations.push(...check_file(f, forbidden, allowlist));
         }
     }
@@ -664,7 +690,7 @@ function scan_all(root: string): { violations: Violation[]; detected: string[] }
         }
     }
 
-    return { violations, detected };
+    return { violations, detected, scanned: scannedFiles.size };
 }
 
 function format_text(violations: Violation[], detected: string[]): string {
@@ -816,7 +842,7 @@ function parseArgs(argv: readonly string[]): ParsedArgs {
 function main(): number {
     const args = parseArgs(process.argv.slice(2));
 
-    let result: { violations: Violation[]; detected: string[] };
+    let result: { violations: Violation[]; detected: string[]; scanned: number };
     try {
         result = scan_all(args.root);
     } catch (e) {
@@ -825,7 +851,11 @@ function main(): number {
         return 3;
     }
 
-    const { violations, detected } = result;
+    const { violations, detected, scanned } = result;
+    // gate-coverage contract (src/config/gate-coverage.yml): one machine-readable
+    // count on stderr so `check_gate_coverage` can assert this gate read a real
+    // corpus. It scanned a deleted root for months and still exited 0.
+    process.stderr.write(`scanned: ${String(scanned)}\n`);
     if (args.format === 'json') {
         const payload = { detected, violations };
         process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);

package/src/scripts/check_references.ts

@@ -452,9 +452,12 @@ function _extract_personas_frontmatter(text: string): Array<[number, string]> {
 
 function _find_suggestion(p: string, root: string): string {
     const name = path.basename(p);
+    // DEAD-ROOT REPAIR (road-to-renewal-foundation Phase 1): the middle entry
+    // was `.agent-src.uncondensed`, deleted by ADR-051. `src/` is the source of
+    // truth, so a file that exists only there produced no suggestion at all.
     for (const d of [
         path.join(root, 'dist/agent-src'),
-        path.join(root, '.agent-src.uncondensed'),
+        path.join(root, 'src'),
         path.join(root, 'agents'),
     ]) {
         if (_exists(d)) {
@@ -586,10 +589,15 @@ function check_file(filepath: string, artifacts: Artifacts, root: string): Broke
             } else {
                 // Strip leading ./ and try with prefixes
                 const ref = rawRef.replace(/^[./]+/, '');
+                // DEAD-ROOT REPAIR: `.agent-src.uncondensed` (ADR-051) never
+                // resolved, so a reference that only exists under the source of
+                // truth was reported BROKEN. `src/` and its category roots
+                // replace it.
                 for (const prefix of [
                     root,
                     path.join(root, 'dist/agent-src'),
-                    path.join(root, '.agent-src.uncondensed'),
+                    path.join(root, 'src'),
+                    path.join(root, 'src/agent-src'),
                 ]) {
                     if (_exists(path.join(prefix, ref))) {
                         resolved = true;
@@ -605,7 +613,7 @@ function check_file(filepath: string, artifacts: Artifacts, root: string): Broke
                     const rel = rawRef.slice('.augment/'.length);
                     for (const prefix of [
                         path.join(root, 'dist/agent-src'),
-                        path.join(root, '.agent-src.uncondensed'),
+                        path.join(root, 'src/agent-src'),
                     ]) {
                         if (_exists(path.join(prefix, rel))) {
                             resolved = true;
@@ -774,6 +782,10 @@ function check_memory_yaml(filepath: string, artifacts: Artifacts, root: string)
 function scan_all(root: string): BrokenRef[] {
     const artifacts = collect_artifacts(root);
     const broken: BrokenRef[] = [];
+    // gate-coverage contract (src/config/gate-coverage.yml): a machine-readable
+    // count of files actually read, so `check_gate_coverage` can assert this
+    // gate saw a real corpus rather than a moved root.
+    let scannedFiles = 0;
     for (const scanDir of SCAN_DIRS) {
         const d = path.join(root, scanDir);
         if (!_exists(d)) {
@@ -785,18 +797,22 @@ function scan_all(root: string): BrokenRef[] {
             if (SKIP_DIRS.some((skip) => f.startsWith(path.join(root, skip)))) {
                 continue;
             }
+            scannedFiles += 1;
             broken.push(...check_file(f, artifacts, root));
         }
     }
     const memoryDir = path.join(root, MEMORY_YAML_ROOT);
     if (_isDir(memoryDir)) {
         for (const f of _rglob(memoryDir, '.yml').sort()) {
+            scannedFiles += 1;
             broken.push(...check_memory_yaml(f, artifacts, root));
         }
         for (const f of _rglob(memoryDir, '.yaml').sort()) {
+            scannedFiles += 1;
             broken.push(...check_memory_yaml(f, artifacts, root));
         }
     }
+    process.stderr.write(`scanned: ${String(scannedFiles)}\n`);
     return broken;
 }
 

package/src/scripts/check_release_pr_shape.ts

@@ -24,6 +24,9 @@ const _HERE = fileURLToPath(import.meta.url);
 
 const ALLOWLIST_GLOBS = [
     'package.json',
+    // Lockfile version fields — bumped by release.ts set_lockfile_version in
+    // lockstep with package.json (road-to-gates-that-can-fail Phase 5).
+    'package-lock.json',
     'CHANGELOG.md',
     '.claude-plugin/marketplace.json',
     'src/packs/*/pack.yaml',
@@ -131,6 +134,16 @@ function check(files: readonly string[]): number {
         for (const f of bad) {
             process.stdout.write(`OUT-OF-SHAPE: ${f}\n`);
         }
+        process.stdout.write(
+            '\n' +
+                'A release PR may only contain the version-bump allowlist — the heavy\n' +
+                'test matrix skips on release/* heads, so code must not ride a release PR\n' +
+                '(docs/contracts/release-pr-gating.md § Mid-release fixes).\n' +
+                'Fix: land the files above on main via their own PR, then\n' +
+                '  git checkout release/X.Y.Z && git merge origin/main && git push\n' +
+                '— their release-PR diff becomes empty and this check goes green.\n' +
+                'Then resume with: task release -- --resume --yes\n',
+        );
         return 1;
     }
     process.stdout.write(

package/src/scripts/check_token_regression.ts

@@ -17,7 +17,9 @@
  *   - thin_rule_load     — thin_projection.thin_gpt
  *   - skill_descriptions — description_catalog.skills_core_source.tokens_gpt
  *   - command_descriptions — description_catalog.commands_core_source.tokens_gpt
- *   - mcp_schemas        — Σ mcp_tool_schemas[*].tokens_gpt
+ *   - mcp_schemas        — max mcp_tool_schemas[*].tokens_gpt (per-transport;
+ *                          a client connects over ONE transport, so Σ would
+ *                          double-bill the tools both transports serve)
  *
  * A baseline captured under a different `token_method` (e.g. proxy → exact)
  * is a legitimate reset, not a regression — the gate WARNS and asks for a
@@ -74,10 +76,15 @@ function _num(obj: unknown, ...keys: string[]): number {
 
 /** Extract the flat gated-metric map from a projection-cost report. */
 function extract_metrics(report: Json): Metrics {
+  // MAX, not Σ. The report keys one entry per SERVER-TRANSPORT pair, and a
+  // client connects over exactly one transport of a given server — summing
+  // `agent-config (stdio)` and `agent-config (worker)` would bill the 19
+  // shared tools twice and read as a regression the moment the transports were
+  // split apart. The gated metric is what the worst-case single client loads.
   const mcp = (report['mcp_tool_schemas'] as Json) ?? {};
   let mcp_total = 0;
   for (const server of Object.values(mcp)) {
-    mcp_total += _num(server, 'tokens_gpt');
+    mcp_total = Math.max(mcp_total, _num(server, 'tokens_gpt'));
   }
   return {
     token_method: String(report['token_method'] ?? 'unknown'),