@event4u/agent-config 9.10.0 → 9.12.0

package/src/scripts/check_dependency_floors.ts

@@ -0,0 +1,153 @@
+#!/usr/bin/env tsx
+/**
+ * check_dependency_floors — keep every runtime dependency floor at a settled
+ * minor, so consumers on `prefer-offline=true` or a lagging registry mirror
+ * cannot hit `ETARGET — No matching version found`
+ * (road-to-zero-ceremony-install § Phase 2).
+ *
+ * Why a gate and not a retry: `dependencies` are resolved on the CONSUMER's
+ * machine by npm, BEFORE our `bin` is executed. When resolution fails, npx
+ * aborts and no code of ours ever runs — so this failure mode cannot be
+ * caught, retried, or explained from inside the CLI. It can only be made
+ * unreachable at publish time, which is what this gate does. CONTRIBUTING
+ * § "Runtime dependency floors" states the rule in prose; this is its teeth.
+ *
+ * The rule: a caret floor pins the minimum compatible version, so its patch
+ * component is `.0` (`^9.5.0`, never `^9.6.1`). A floor pinned to a
+ * just-published patch fails against cached registry metadata that predates
+ * it, even though the version exists on public npm.
+ *
+ * Exact pins (no range operator) are a different, deliberate mechanism — an
+ * ABI lock — and are allowed only when listed in EXACT_PIN_EXCEPTIONS with a
+ * reason, so a drive-by pin cannot hide among them.
+ *
+ * SECURITY FLOORS OUTRANK THIS RULE. A floor whose patch component is non-zero
+ * *because everything below it carries an advisory* must never be lowered to
+ * satisfy resolvability — that trades a rare install failure for a live CVE.
+ * Those live in SECURITY_FLOOR_EXCEPTIONS with the advisory and the vulnerable
+ * range, and the gate then enforces the floor rather than fighting it.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/check_dependency_floors [--json]
+ *
+ * Exit codes: 0 green · 1 a floor violates the rule · 2 misuse / unreadable manifest.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
+
+/**
+ * Dependencies deliberately pinned to an exact version, with the reason. An
+ * exact pin cannot suffer the freshest-patch failure (the version is either
+ * cached or it is not), but it also forfeits patch fixes — so each one is
+ * named here rather than silently tolerated.
+ */
+export const EXACT_PIN_EXCEPTIONS: Readonly<Record<string, string>> = {
+    'web-tree-sitter': 'ABI-locked against tree-sitter-wasms; see code-graph engine pin',
+    'tree-sitter-wasms': 'ABI-locked against web-tree-sitter; see code-graph engine pin',
+};
+
+/**
+ * Floors that are non-settled ON PURPOSE, because every version below them is
+ * vulnerable. The required range is pinned here so the gate ENFORCES the floor
+ * instead of asking for it to be lowered — lowering one trades a rare install
+ * failure for a live advisory, which is never the right trade.
+ */
+export const SECURITY_FLOOR_EXCEPTIONS: Readonly<Record<string, { required: string; reason: string }>> = {
+    '@fastify/static': {
+        required: '^10.1.2',
+        reason:
+            'high-severity route-guard bypass via path traversal (CVSS 7.5) affects <=10.1.1; ' +
+            '10.1.2 is the fix. Verified with npm audit on a clean 10.1.0 install, 2026-07-31.',
+    },
+};
+
+/** A settled caret floor: `^X.Y.0`. */
+const SETTLED_CARET = /^\^\d+\.\d+\.0$/;
+
+/** An exact version with no range operator: `1.2.3`. */
+const EXACT_VERSION = /^\d+\.\d+\.\d+$/;
+
+/**
+ * Every violation in `dependencies`, as human-readable lines. Empty array
+ * means the manifest cannot produce a freshest-patch `ETARGET` for a consumer.
+ */
+export function evaluate(dependencies: Readonly<Record<string, string>>): string[] {
+    const errors: string[] = [];
+    for (const [name, range] of Object.entries(dependencies)) {
+        const security = SECURITY_FLOOR_EXCEPTIONS[name];
+        if (security !== undefined) {
+            // The floor is the control. Enforce it; never ask for it to settle.
+            if (range !== security.required) {
+                errors.push(
+                    `${name}@${range}: security floor must stay at ${security.required} — ${security.reason}`,
+                );
+            }
+            continue;
+        }
+        if (EXACT_VERSION.test(range)) {
+            if (!(name in EXACT_PIN_EXCEPTIONS)) {
+                errors.push(
+                    `${name}@${range}: exact pin without an entry in EXACT_PIN_EXCEPTIONS — ` +
+                        'add the reason there, or use a settled caret floor (^X.Y.0)',
+                );
+            }
+            continue;
+        }
+        if (SETTLED_CARET.test(range)) continue;
+        if (range.startsWith('^')) {
+            errors.push(
+                `${name}@${range}: caret floor is not a settled minor — lower the patch to ` +
+                    `.0 (e.g. ${range.replace(/\.\d+$/, '.0')}) so a lagging registry mirror ` +
+                    'can still resolve it',
+            );
+            continue;
+        }
+        errors.push(
+            `${name}@${range}: unsupported range shape — use a settled caret floor (^X.Y.0), ` +
+                'or an exact pin listed in EXACT_PIN_EXCEPTIONS',
+        );
+    }
+    return errors;
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const asJson = argv.includes('--json');
+    const manifestPath = path.join(REPO_ROOT, 'package.json');
+    let dependencies: Record<string, string>;
+    try {
+        const raw = JSON.parse(fs.readFileSync(manifestPath, 'utf-8')) as {
+            dependencies?: Record<string, string>;
+        };
+        dependencies = raw.dependencies ?? {};
+    } catch (err) {
+        process.stderr.write(`❌  dependency floors: cannot read ${manifestPath}: ${String(err)}\n`);
+        return 2;
+    }
+    if (Object.keys(dependencies).length === 0) {
+        process.stderr.write('❌  dependency floors: no runtime dependencies found — gate would pass vacuously\n');
+        return 2;
+    }
+    const errors = evaluate(dependencies);
+    if (asJson) {
+        process.stdout.write(`${JSON.stringify({ checked: Object.keys(dependencies).length, errors }, null, 2)}\n`);
+        return errors.length > 0 ? 1 : 0;
+    }
+    if (errors.length > 0) {
+        for (const e of errors) process.stderr.write(`❌  dependency floor: ${e}\n`);
+        return 1;
+    }
+    process.stdout.write(
+        `✅  dependency floors settled (${Object.keys(dependencies).length} runtime deps) — ` +
+            'no freshest-patch ETARGET reachable for a consumer\n',
+    );
+    return 0;
+}
+
+const _selfPath = fileURLToPath(import.meta.url);
+if (process.argv[1] !== undefined && path.resolve(process.argv[1]) === path.resolve(_selfPath)) {
+    process.exit(main());
+}

package/src/scripts/check_installer_import_purity.ts

@@ -0,0 +1,295 @@
+#!/usr/bin/env tsx
+/**
+ * Guard against a maintainer-only CLI being bundled into the consumer installer.
+ *
+ * ## The incident this exists to prevent (road-to-consistent-rule-scoping, 2026-07-31)
+ *
+ * `src/install/rule_scope.ts` imported the rule-scoping predicate from
+ * `src/scripts/condense.ts` — deliberately, so install semantics could not drift
+ * from projection semantics. Correct intent. But `condense.ts` is maintainer CLI
+ * tooling that ends in a module-level self-invoke:
+ *
+ *     const isMain = _isCliEntry();
+ *     if (isMain) { process.exit(main()); }
+ *
+ * `_isCliEntry()` compares `import.meta.url` against `process.argv[1]`. That is
+ * right for a file run directly — and wrong once esbuild BUNDLES the module,
+ * because `import.meta.url` then resolves to the BUNDLE's own URL, which *is*
+ * `argv[1]` when a consumer runs `node dist/install/install.mjs`. The guard
+ * fired inside the installer, `condense.main()` ran, found no maintainer source
+ * tree in a consumer checkout, printed "No source directory found" and called
+ * `process.exit(1)` — killing the install AFTER the payload had already synced.
+ *
+ * All four `smoke-public-install` legs went red. Nothing caught it earlier:
+ * `prepack-check` verifies that imports resolve to SHIPPED paths (they did),
+ * the bundle-freshness gate only byte-diffs the rebuilt output, and the
+ * behavioural smoke test only runs post-push in its own workflow.
+ *
+ * ## What this checks
+ *
+ * The transitive relative-import closure of the installer bundle entry must
+ * contain NO module-level `process.exit(` outside the entry itself.
+ *
+ * "Module-level" is decided structurally, not textually: the AST walk descends
+ * through top-level statements and nested blocks/ifs/try but STOPS at any
+ * function, method, class, arrow or accessor body. So
+ * `function main() { process.exit(1) }` is fine — it only runs when called —
+ * while `if (isMain) { process.exit(main()) }` is not, because importing the
+ * module runs it.
+ *
+ * The entry module is exempt: it IS the CLI, and its own exit is the point.
+ *
+ * ## Why this shape and not the alternatives
+ *
+ * - **Not a string scan of the built bundle.** That reports a mystery literal
+ *   with no cause. This reports the import CHAIN
+ *   (`install.ts → rule_scope.ts → condense.ts`), which is the actionable fact.
+ * - **Not "forbid importing condense.ts".** A denylist of one file rots the
+ *   moment a second CLI module grows an entry guard. The hazard is the
+ *   module-level exit, so that is what is detected.
+ * - **Runs on SOURCE, so it needs no build.** It fails in `task ci` before a
+ *   push instead of on four CI legs after one.
+ *
+ * Exit 0 clean, 1 on any finding. No network, no build, no spend.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import ts from 'typescript';
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(_HERE, '..', '..');
+
+/**
+ * Bundle entry points that ship to consumers as a single file.
+ *
+ * Keep in sync with the `build:*bundle` scripts in package.json. Each entry is
+ * exempt from the check for its own module-level exit — it is the CLI.
+ */
+const BUNDLE_ENTRIES: readonly string[] = [
+    'src/scripts/install.ts', // → dist/install/install.mjs (build:install-bundle)
+];
+
+interface Finding {
+    /** The offending module, repo-relative POSIX. */
+    readonly module: string;
+    /** 1-indexed line of the offending call. */
+    readonly line: number;
+    /** How the entry reaches it, entry first. */
+    readonly chain: readonly string[];
+}
+
+function toPosix(p: string): string {
+    return p.split(path.sep).join('/');
+}
+
+function relToRepo(abs: string, root: string = REPO_ROOT): string {
+    return toPosix(path.relative(root, abs));
+}
+
+/**
+ * Resolve a relative import specifier to a source file on disk.
+ *
+ * The codebase imports with `.js` extensions (NodeNext) while the sources are
+ * `.ts`, so try the TypeScript twin first, then the literal path, then an
+ * `index` file. Returns `null` for anything unresolvable — a bare package
+ * specifier, a type-only path that no longer exists, or a `.json` asset.
+ */
+function resolveImport(fromFile: string, specifier: string): string | null {
+    if (!specifier.startsWith('.')) return null;
+    const base = path.resolve(path.dirname(fromFile), specifier);
+    const candidates = [
+        base.replace(/\.js$/, '.ts'),
+        base.replace(/\.js$/, '.tsx'),
+        base,
+        `${base}.ts`,
+        path.join(base, 'index.ts'),
+    ];
+    for (const c of candidates) {
+        try {
+            if (fs.statSync(c).isFile()) return c;
+        } catch {
+            // next candidate
+        }
+    }
+    return null;
+}
+
+/** Relative import specifiers declared by `source`, in source order. */
+function importSpecifiers(source: ts.SourceFile): string[] {
+    const out: string[] = [];
+    const visit = (node: ts.Node): void => {
+        if (
+            (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
+            node.moduleSpecifier !== undefined &&
+            ts.isStringLiteral(node.moduleSpecifier)
+        ) {
+            out.push(node.moduleSpecifier.text);
+        } else if (
+            ts.isCallExpression(node) &&
+            node.expression.kind === ts.SyntaxKind.ImportKeyword &&
+            node.arguments.length > 0 &&
+            ts.isStringLiteral(node.arguments[0] as ts.Node)
+        ) {
+            // A dynamic import() is still bundled by esbuild unless code-split,
+            // so it carries the same hazard as a static one.
+            out.push((node.arguments[0] as ts.StringLiteral).text);
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(source, visit);
+    return out;
+}
+
+/** True for nodes whose body only runs when called — the walk stops here. */
+function isDeferredScope(node: ts.Node): boolean {
+    return (
+        ts.isFunctionDeclaration(node) ||
+        ts.isFunctionExpression(node) ||
+        ts.isArrowFunction(node) ||
+        ts.isMethodDeclaration(node) ||
+        ts.isConstructorDeclaration(node) ||
+        ts.isGetAccessorDeclaration(node) ||
+        ts.isSetAccessorDeclaration(node) ||
+        ts.isClassDeclaration(node) ||
+        ts.isClassExpression(node)
+    );
+}
+
+/** Is `node` a `process.exit(...)` call? */
+function isProcessExitCall(node: ts.Node): boolean {
+    if (!ts.isCallExpression(node)) return false;
+    const callee = node.expression;
+    if (!ts.isPropertyAccessExpression(callee)) return false;
+    return (
+        ts.isIdentifier(callee.expression) &&
+        callee.expression.text === 'process' &&
+        callee.name.text === 'exit'
+    );
+}
+
+/**
+ * 1-indexed lines of every `process.exit(` that executes at MODULE LOAD.
+ *
+ * Descends through statement-level structure (blocks, if/else, try/catch/finally,
+ * loops, labels) and stops at any deferred scope, so a call inside a function is
+ * not reported while one inside a top-level `if` is.
+ */
+function moduleLevelExitLines(source: ts.SourceFile): number[] {
+    const lines: number[] = [];
+    const visit = (node: ts.Node): void => {
+        if (isDeferredScope(node)) return;
+        if (isProcessExitCall(node)) {
+            lines.push(source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1);
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(source, visit);
+    return lines;
+}
+
+function parse(file: string): ts.SourceFile | null {
+    let text: string;
+    try {
+        text = fs.readFileSync(file, 'utf-8');
+    } catch {
+        return null;
+    }
+    return ts.createSourceFile(file, text, ts.ScriptTarget.ESNext, true);
+}
+
+/**
+ * Walk one entry's closure; return every module-level exit found below it.
+ *
+ * `root` defaults to the repo; tests pass a fixture tree so the chain-reporting
+ * itself is covered, not only the per-file detector.
+ */
+function auditEntry(entryRel: string, root: string = REPO_ROOT): Finding[] {
+    const entryAbs = path.join(root, entryRel);
+    if (!fs.existsSync(entryAbs)) {
+        process.stderr.write(
+            `check-installer-import-purity: entry ${entryRel} does not exist — ` +
+                'update BUNDLE_ENTRIES\n',
+        );
+        process.exitCode = 1;
+        return [];
+    }
+    const findings: Finding[] = [];
+    const seen = new Set<string>([entryAbs]);
+    // BFS so the reported chain is a shortest path — the least confusing one.
+    const queue: Array<{ file: string; chain: string[] }> = [
+        { file: entryAbs, chain: [entryRel] },
+    ];
+    while (queue.length > 0) {
+        const { file, chain } = queue.shift() as { file: string; chain: string[] };
+        const source = parse(file);
+        if (source === null) continue;
+
+        // The entry is the CLI; its own module-level exit is intended.
+        if (file !== entryAbs) {
+            for (const line of moduleLevelExitLines(source)) {
+                findings.push({ module: relToRepo(file, root), line, chain });
+            }
+        }
+
+        for (const spec of importSpecifiers(source)) {
+            const target = resolveImport(file, spec);
+            if (target === null || seen.has(target)) continue;
+            seen.add(target);
+            queue.push({ file: target, chain: [...chain, relToRepo(target, root)] });
+        }
+    }
+    return findings;
+}
+
+function main(): number {
+    const all: Finding[] = [];
+    for (const entry of BUNDLE_ENTRIES) {
+        all.push(...auditEntry(entry));
+    }
+    if (all.length === 0) {
+        process.stdout.write(
+            `✅  installer import purity: ${BUNDLE_ENTRIES.length} bundle entr` +
+                `${BUNDLE_ENTRIES.length === 1 ? 'y' : 'ies'} reach no module-level ` +
+                'process.exit()\n',
+        );
+        return 0;
+    }
+    process.stdout.write('❌  installer import purity — module-level process.exit() reachable:\n');
+    for (const f of all) {
+        process.stdout.write(`\n    ${f.module}:${f.line}\n`);
+        process.stdout.write(`      reached via: ${f.chain.join(' → ')}\n`);
+    }
+    process.stdout.write(
+        '\n  Why this fails the build: esbuild bundles the whole closure into\n' +
+            '  dist/install/install.mjs. A module-level process.exit() then runs when a\n' +
+            '  CONSUMER loads the installer — and a CLI entry guard comparing\n' +
+            '  import.meta.url to process.argv[1] evaluates TRUE inside a bundle, because\n' +
+            '  the bundle IS argv[1].\n\n' +
+            '  Fix: move the code the installer actually needs into a module with no CLI\n' +
+            '  entry and no top-level exit, and let the CLI re-export it. Do NOT relax\n' +
+            '  this gate — the failure it prevents kills a consumer install after the\n' +
+            '  payload has already been written.\n',
+    );
+    return 1;
+}
+
+const _isCliEntry = (): boolean => {
+    if (process.argv[1] === undefined) return false;
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+};
+
+if (_isCliEntry()) {
+    process.exit(main());
+}
+
+export { auditEntry, moduleLevelExitLines, BUNDLE_ENTRIES };

package/src/scripts/check_pack_size.ts

@@ -0,0 +1,188 @@
+#!/usr/bin/env tsx
+/**
+ * check_pack_size — enforce the published-tarball payload budget
+ * (road-to-zero-ceremony-install Phase 4).
+ *
+ * Two metrics, both ungated before this script existed:
+ *   1. COMPRESSED tarball size — absolute max, plus the >regression_pct creep
+ *      rule (fails even under the absolute budget, so slow rot cannot hide
+ *      under a generous cap).
+ *   2. PER-SKILL share of the skills subtree — no single skill may silently
+ *      reclaim space freed elsewhere. Named exceptions carry a reason.
+ *
+ * The UNPACKED size is deliberately NOT re-gated here: it is already owned by
+ * `evaluator-budgets.unpacked_size_mb`, measured at release time on the BUILT
+ * artifact. Two gates for one lever is how conflicting numbers start.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/check_pack_size [--json]
+ *   ./scripts-run src/scripts/check_pack_size --pack-json <file>   # test/offline
+ *
+ * Exit codes: 0 green · 1 over budget · 2 misuse / unreadable input.
+ */
+
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const REPO_ROOT = path.resolve(fileURLToPath(import.meta.url), '..', '..', '..');
+const BUDGET_PATH = path.join(REPO_ROOT, 'src', 'config', 'pack-size-budget.json');
+const SKILL_PREFIX = 'dist/agent-src/skills/';
+
+export interface PackFile {
+    path: string;
+    size: number;
+}
+
+export interface PackResult {
+    size: number;
+    unpackedSize: number;
+    files: PackFile[];
+}
+
+export interface PackSizeBudget {
+    regression_pct: number;
+    budgets: Record<string, { max: number; last_measured: number; method: string }>;
+    per_skill_share: {
+        max_pct: number;
+        basis: string;
+        rationale: string;
+        exceptions: Record<string, { max_pct: number; measured_pct: number; reason: string }>;
+    };
+}
+
+/**
+ * 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.
+ */
+export function parsePackJson(stdout: string): PackResult {
+    const start = stdout.indexOf('[');
+    const parsed = JSON.parse(start >= 0 ? stdout.slice(start) : stdout) as PackResult[];
+    const first = parsed[0];
+    if (first === undefined) throw new Error('npm pack --json returned an empty array');
+    return first;
+}
+
+/** Bytes per skill under `dist/agent-src/skills/`, plus the subtree total. */
+export function skillBytes(files: readonly PackFile[]): { perSkill: Record<string, number>; total: number } {
+    const perSkill: Record<string, number> = {};
+    let total = 0;
+    for (const file of files) {
+        if (!file.path.startsWith(SKILL_PREFIX)) continue;
+        const name = file.path.slice(SKILL_PREFIX.length).split('/')[0];
+        if (name === undefined || name === '') continue;
+        perSkill[name] = (perSkill[name] ?? 0) + file.size;
+        total += file.size;
+    }
+    return { perSkill, total };
+}
+
+/** Every violation, as human-readable lines. Empty array means green. */
+export function evaluate(budget: PackSizeBudget, pack: PackResult): string[] {
+    const errors: string[] = [];
+
+    const packedMb = pack.size / 1e6;
+    const entry = budget.budgets['packed_size_mb'];
+    if (entry === undefined) {
+        errors.push('packed_size_mb: missing from the budget file — gate would pass vacuously');
+    } else if (packedMb > entry.max) {
+        errors.push(`packed_size_mb: measured ${packedMb.toFixed(3)} exceeds budget ${entry.max}`);
+    } else {
+        const pct = budget.regression_pct;
+        const ceiling = entry.last_measured * (1 + pct / 100);
+        if (entry.last_measured > 0 && packedMb > ceiling) {
+            errors.push(
+                `packed_size_mb: measured ${packedMb.toFixed(3)} regressed >${pct}% vs ` +
+                    `last_measured ${entry.last_measured} (ceiling ${ceiling.toFixed(3)}) — ` +
+                    'fails even under the absolute budget',
+            );
+        }
+    }
+
+    const { perSkill, total } = skillBytes(pack.files);
+    if (total === 0) {
+        errors.push(`per_skill_share: no files under ${SKILL_PREFIX} — gate would pass vacuously`);
+        return errors;
+    }
+    const { max_pct: defaultMax, exceptions } = budget.per_skill_share;
+    for (const [name, bytes] of Object.entries(perSkill)) {
+        const share = (bytes / total) * 100;
+        const exception = exceptions[name];
+        const cap = exception?.max_pct ?? defaultMax;
+        if (share > cap) {
+            errors.push(
+                exception === undefined
+                    ? `per_skill_share: ${name} is ${share.toFixed(2)}% of the skills payload, over the ${cap}% cap — ` +
+                      'shrink it, or add a named exception with a reason'
+                    : `per_skill_share: ${name} is ${share.toFixed(2)}%, over its own exception cap of ${cap}% — ` +
+                      'the exception is not a blank cheque; shrink it or raise the cap with a reason',
+            );
+        }
+    }
+    for (const name of Object.keys(exceptions)) {
+        if (!(name in perSkill)) {
+            errors.push(`per_skill_share: exception for '${name}' is stale — no such skill ships`);
+        }
+    }
+    return errors;
+}
+
+function readPack(argv: readonly string[]): PackResult {
+    const idx = argv.indexOf('--pack-json');
+    if (idx >= 0) {
+        const file = argv[idx + 1];
+        if (file === undefined) throw new Error('--pack-json needs a path');
+        return parsePackJson(fs.readFileSync(file, 'utf-8'));
+    }
+    const stdout = execFileSync('npm', ['pack', '--dry-run', '--json', '--ignore-scripts', '--silent'], {
+        cwd: REPO_ROOT,
+        encoding: 'utf-8',
+        maxBuffer: 64 * 1024 * 1024,
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    return parsePackJson(stdout);
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    let budget: PackSizeBudget;
+    let pack: PackResult;
+    try {
+        budget = JSON.parse(fs.readFileSync(BUDGET_PATH, 'utf-8')) as PackSizeBudget;
+    } catch (err) {
+        process.stderr.write(`❌  pack size: cannot read ${BUDGET_PATH}: ${String(err)}\n`);
+        return 2;
+    }
+    try {
+        pack = readPack(argv);
+    } catch (err) {
+        process.stderr.write(`❌  pack size: npm pack failed: ${String(err)}\n`);
+        return 2;
+    }
+
+    const errors = evaluate(budget, pack);
+    const { perSkill, total } = skillBytes(pack.files);
+    if (argv.includes('--json')) {
+        process.stdout.write(
+            `${JSON.stringify({ packed_mb: pack.size / 1e6, skills_total_bytes: total, skills: Object.keys(perSkill).length, errors }, null, 2)}\n`,
+        );
+        return errors.length > 0 ? 1 : 0;
+    }
+    if (errors.length > 0) {
+        for (const e of errors) process.stderr.write(`❌  pack size: ${e}\n`);
+        return 1;
+    }
+    process.stdout.write(
+        `✅  pack size within budget — ${(pack.size / 1e6).toFixed(3)} MB packed, ` +
+            `${Object.keys(perSkill).length} skills, largest share ` +
+            `${Math.max(...Object.values(perSkill).map((b) => (b / total) * 100)).toFixed(2)}%\n`,
+    );
+    return 0;
+}
+
+const _selfPath = fileURLToPath(import.meta.url);
+if (process.argv[1] !== undefined && path.resolve(process.argv[1]) === path.resolve(_selfPath)) {
+    process.exit(main());
+}

package/src/scripts/condense.ts

@@ -238,6 +238,13 @@ function _stripChars(s: string, chars: string): string {
 // the repo root.
 // =============================================================================
 
+// road-to-consistent-rule-scoping: the predicate moved to a side-effect-free
+// module so the consumer installer can import it WITHOUT pulling this file's
+// module-level CLI self-invoke into its bundle. Re-exported here because four
+// in-repo consumers import it from `condense.js`.
+export { rule_in_scope } from '../install/ruleInScope.js';
+import { rule_in_scope } from '../install/ruleInScope.js';
+
 const _HERE = path.dirname(fileURLToPath(import.meta.url)); // <repo>/src/scripts
 const _DEFAULT_PROJECT_ROOT = path.resolve(_HERE, '..', '..');
 
@@ -1014,34 +1021,6 @@ function _read_rule_packs(): string[] | null {
  * `null` (no role filtering), so every existing 2- and 3-arg call site
  * compiles and behaves unchanged.
  */
-export function rule_in_scope(
-    source_path: string,
-    scope: readonly string[] | null,
-    pack_scope: readonly string[] | null = null,
-    role_scope: readonly string[] | null = null,
-): boolean {
-    if (scope === null && pack_scope === null && role_scope === null) {
-        return true;
-    }
-    const [meta] = _parse_frontmatter(_readText(source_path));
-    if (meta['type'] === 'always' || meta['alwaysApply'] === true) {
-        return true; // kernel always projects
-    }
-    const axis = (key: string, configured: readonly string[] | null): boolean => {
-        if (configured === null) {
-            return true;
-        }
-        const values = Array.isArray(meta[key])
-            ? (meta[key] as unknown[]).map((w) => String(w))
-            : [];
-        if (values.length === 0) {
-            return true; // untagged → fail safe: ship it
-        }
-        return values.some((v) => configured.includes(v));
-    };
-    return axis('workspaces', scope) && axis('packs', pack_scope) && axis('roles', role_scope);
-}
-
 /** List rule basenames under RULES_SOURCE, workspace/pack scope applied. */
 function _scoped_rule_basenames(): string[] {
     const scope = _read_rule_workspaces();