@event4u/agent-config 9.10.0 → 9.11.0

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/council_cli.ts

@@ -69,7 +69,7 @@ import {
     resolve_config_path,
 } from './ai_council/config.js';
 import { AuthCache, select_solo_member } from './ai_council/solo_dispatch.js';
-import { InvalidModeError, resolve_mode } from './ai_council/modes.js';
+import { InvalidModeError, resolve_global_mode, resolve_mode } from './ai_council/modes.js';
 import { appendEvent } from './ai_council/events_log.js';
 import {
     type ClassificationResult,
@@ -564,7 +564,11 @@ function build_members(settings: Dict, opts: BuildMembersOptions = {}): External
         );
     }
     const members_cfg = (ai['members'] as Dict) || {};
-    const global_mode = ai['mode'] as string | null | undefined;
+    // Accepts BOTH the synthesized flat `mode` and the raw `defaults.mode`
+    // shape — see modes.ts::resolve_global_mode. Reading only the flat key
+    // dropped the configured default for every caller that hands this
+    // exported function a raw `.ai-council.yml` dict.
+    const global_mode = resolve_global_mode(ai);
     const cli_budget_cfg = _isDict(ai) ? ((ai['cli_call_budget'] as Dict) || {}) : {};
     const cli_caps = _isDict(cli_budget_cfg)
         ? ((cli_budget_cfg['max_calls_per_day'] as Dict) || {})

package/src/scripts/evaluator_umbrella.sh

@@ -65,11 +65,38 @@ UNPACKED_BYTES="$(npm pack --dry-run --json --ignore-scripts --silent 2>/dev/nul
 step "headless consumer install from the tarball"
 WORK="$(mktemp -d)"
 trap 'rm -rf "$WORK"' EXIT
+COLD_START_T0="$(node -e 'console.log(Date.now())')"
 ( cd "$WORK" && npm init -y >/dev/null 2>&1 \
   && npm install --omit=dev --no-audit --no-fund --silent "$ROOT/$TARBALL" )
 PKG_DIR="$WORK/node_modules/@event4u/agent-config"
 [[ -d "$PKG_DIR" ]] || { echo "❌ install did not produce the package dir" >&2; exit 1; }
 
+# ------------------------------------------- 3b. cold start: install → doctor
+# The bare-machine wall-clock a first-time user lives through, measured end to
+# end from `npm install` to `doctor` having run. This is EVIDENCE, never a
+# promise, and deliberately NOT a budget entry: it is dominated by network and
+# registry latency, which are not ours to guarantee. A gate on it would flap on
+# runner weather and teach the reader to ignore the line
+# (road-to-zero-ceremony-install Phase 6).
+step "cold start: install → doctor (evidence, not a gate)"
+COLD_START_MS="$(node -e '
+const {execFileSync}=require("node:child_process");
+const [bin, t0] = process.argv.slice(1);
+try { execFileSync(bin, ["doctor"], {stdio:"ignore"}); }
+catch { /* doctor may report findings; the run still bounds the wall-clock */ }
+console.log(Date.now() - Number(t0));' "$WORK/node_modules/.bin/agent-config" "$COLD_START_T0")"
+COLD_START_CONDITIONS="$(uname -s)/$(uname -m) · node $(node --version) · npm $(npm --version) · npm install --omit=dev from a LOCAL tarball (no registry round-trip for the package itself; a real first-touch install adds registry latency)"
+printf 'cold_start_install_to_doctor_ms=%s\n' "$COLD_START_MS"
+printf 'cold_start_conditions=%s\n' "$COLD_START_CONDITIONS"
+if [[ -n "${GITHUB_STEP_SUMMARY:-}" ]]; then
+  {
+    printf '### Cold start — install → doctor\n\n'
+    printf '**%s ms**\n\n' "$COLD_START_MS"
+    printf 'Conditions: %s\n\n' "$COLD_START_CONDITIONS"
+    printf 'Evidence, not a promise — no shipped claim states this as a guarantee.\n'
+  } >> "$GITHUB_STEP_SUMMARY"
+fi
+
 # --------------------------------------------------------- 4. staleness lints
 step "staleness lints (pre-migration refs)"
 ./scripts-run src/scripts/lint_pre_migration_refs
@@ -128,10 +155,16 @@ const m={
   mcp_boot_to_initialize_ms: Number(process.argv[6]),
   cli_help_command_count: Number(process.argv[7]),
   mcp_public_tool_count: Number(process.argv[8]),
+  // Evidence-only: carried in the artifact with its conditions, never gated.
+  // check_evaluator_budgets iterates the BUDGET entries, so an extra
+  // measurement is recorded and ignored by the gate — by design.
+  cold_start_install_to_doctor_ms: Number(process.argv[9]),
+  cold_start_conditions: process.argv[10],
 };
 fs.writeFileSync(process.argv[1], JSON.stringify(m, null, 2));
 console.log(JSON.stringify(m, null, 1));' \
-  "$MEASURE_TMP" "$UNPACKED_BYTES" "$NM_MB" "$DEP_COUNT" "$CLI_MS" "$MCP_MS" "$CLI_COUNT" "$MCP_TOOLS"
+  "$MEASURE_TMP" "$UNPACKED_BYTES" "$NM_MB" "$DEP_COUNT" "$CLI_MS" "$MCP_MS" "$CLI_COUNT" "$MCP_TOOLS" \
+  "$COLD_START_MS" "$COLD_START_CONDITIONS"
 
 step "budget gate (absolute + >regression_pct creep)"
 ./scripts-run src/scripts/check_evaluator_budgets --measurements "$MEASURE_TMP"

package/src/scripts/lint_eval_fixture_citations.ts

@@ -0,0 +1,113 @@
+#!/usr/bin/env tsx
+/**
+ * Every design-artifact eval fixture id must be cited by some surface.
+ *
+ * The fixtures file used to assert that the lifecycle contract's branch table
+ * "references these ids". It cites nine of them; the rest are gated elsewhere
+ * (the design-fidelity mechanics guideline, the lane-matrix test) — and a
+ * handful were cited by nothing at all. An uncited fixture is an eval nobody
+ * runs and no contract depends on, which is exactly the shape of coverage that
+ * looks real in a count and is absent in practice.
+ *
+ * This checks citation, not correctness: an id must appear outside its own
+ * definition. Which surface cites it is the author's call.
+ *
+ * Exit codes: 0 every id cited, 1 one or more uncited.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const QUIET = process.argv.includes('--quiet');
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+const FIXTURES = path.join(REPO, 'tests', 'design-artifacts', 'eval-fixtures.md');
+
+/** Surfaces allowed to satisfy a citation. */
+const SCAN_ROOTS: readonly string[] = [
+    path.join(REPO, 'docs', 'contracts'),
+    path.join(REPO, 'docs', 'guidelines'),
+    path.join(REPO, 'src', 'skills'),
+    path.join(REPO, 'src', 'rules'),
+    path.join(REPO, 'tests', 'scripts'),
+];
+
+const SCAN_EXTS: ReadonlySet<string> = new Set(['.md', '.ts']);
+
+function walk(dir: string, out: string[]): void {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+        return;
+    }
+    for (const entry of entries) {
+        const p = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            walk(p, out);
+        } else if (SCAN_EXTS.has(path.extname(entry.name))) {
+            out.push(p);
+        }
+    }
+}
+
+function main(): number {
+    let fixtureText: string;
+    try {
+        fixtureText = fs.readFileSync(FIXTURES, { encoding: 'utf-8' });
+    } catch {
+        process.stderr.write(`lint-eval-fixture-citations: cannot read ${FIXTURES}\n`);
+        return 1;
+    }
+
+    // Ids are declared as `### daf-...` headings or as leading table cells.
+    const ids = new Set<string>();
+    for (const m of fixtureText.matchAll(/^###\s+(daf-[a-z0-9-]+)\s*$/gm)) {
+        ids.add(m[1] as string);
+    }
+    for (const m of fixtureText.matchAll(/^\|\s*`(daf-[a-z0-9-]+)`\s*\|/gm)) {
+        ids.add(m[1] as string);
+    }
+    if (ids.size === 0) {
+        process.stderr.write('lint-eval-fixture-citations: no fixture ids found — parser drift.\n');
+        return 1;
+    }
+
+    const files: string[] = [];
+    for (const root of SCAN_ROOTS) {
+        walk(root, files);
+    }
+    const haystack = files
+        .map((f) => {
+            try {
+                return fs.readFileSync(f, { encoding: 'utf-8' });
+            } catch {
+                return '';
+            }
+        })
+        .join('\n');
+
+    const uncited = [...ids].filter((id) => !haystack.includes(id)).sort();
+    if (uncited.length > 0) {
+        for (const id of uncited) {
+            process.stdout.write(
+                `lint-eval-fixture-citations: \`${id}\` is cited by no contract, ` +
+                    'guideline, skill, rule, or test — an eval nobody runs.\n',
+            );
+        }
+        process.stderr.write(
+            `lint-eval-fixture-citations: ${uncited.length} of ${ids.size} fixture id(s) uncited.\n`,
+        );
+        return 1;
+    }
+    if (!QUIET) {
+        process.stdout.write(
+            `lint-eval-fixture-citations: ${ids.size} fixture id(s), all cited.\n`,
+        );
+    }
+    return 0;
+}
+
+process.exit(main());

package/src/scripts/lint_ui_stack_bundles.ts

@@ -0,0 +1,170 @@
+#!/usr/bin/env tsx
+/**
+ * Lint the UI-track verb → skill-bundle map.
+ *
+ * The stack-dispatched UI steps halt with a directive verb
+ * (`ui-apply-<stack>` and friends). Those verbs are agent-interpreted, not
+ * skill paths — only 2 of the engine's 11 literal verbs name a real skill — so
+ * the mapping from verb to the skills that implement it is a separate fact.
+ * It used to live only in a prose table in `docs/contracts/ui-track-flow.md`,
+ * unverified, and two of its four rows were wrong: `vue` named the verb itself
+ * (no skill at all) and `plain` — the fallback for every unrecognised project —
+ * named `blade-ui`, a `packs: [laravel]` skill that a non-Laravel consumer does
+ * not have installed.
+ *
+ * Two assertions, both decidable in this repo:
+ *
+ *   1. RESOLUTION — every bundle member is a real skill (`src/skills/<n>/SKILL.md`).
+ *   2. PACK REACH — a lane declared `pack_agnostic` names only skills that ship
+ *      in a stack-neutral pack. This is the assertion that actually matters: CI
+ *      here cannot see a consumer's installed pack combination, so "the skill
+ *      exists in our tree" would have passed the `plain → blade-ui` defect
+ *      unchanged.
+ *
+ * Exit codes: 0 clean, 1 one or more findings.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import {
+    STACK_BUNDLES,
+    type StackBundle,
+} from '../agent-src/templates/scripts/work_engine/directives/ui/stack_bundles.js';
+
+const QUIET = process.argv.includes('--quiet');
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+const SKILLS_DIR = path.join(REPO, 'src', 'skills');
+
+/**
+ * Packs that ship regardless of the project's framework. A `pack_agnostic`
+ * lane may only draw on these — anything else is unavailable to some consumer.
+ */
+const STACK_NEUTRAL_PACKS: ReadonlySet<string> = new Set(['engineering-base', 'core', 'meta']);
+
+const findings: string[] = [];
+
+function skill_path(name: string): string {
+    return path.join(SKILLS_DIR, name, 'SKILL.md');
+}
+
+/** Return the `packs:` list from a skill's frontmatter, or `null` if absent. */
+function packs_of(name: string): string[] | null {
+    let text: string;
+    try {
+        text = fs.readFileSync(skill_path(name), { encoding: 'utf-8' });
+    } catch {
+        return null;
+    }
+    // Frontmatter only — a `packs:` mention in the body is not a declaration.
+    const end = text.indexOf('\n---', 4);
+    const front = end === -1 ? text : text.slice(0, end);
+    // `[ \t]*`, not `\s*`: `\s` matches a newline, so the greedy form swallowed
+    // the line break and captured the first block-list item as if it were an
+    // inline value — which made every block-list skill parse as "no packs".
+    const match = /^packs:[ \t]*(.*)$/m.exec(front);
+    if (match === null) return null;
+    const inline = (match[1] ?? '').trim();
+    if (inline.startsWith('[')) {
+        return inline
+            .replace(/^\[|\]$/g, '')
+            .split(',')
+            .map((s) => s.trim().replace(/^['"]|['"]$/g, ''))
+            .filter((s) => s !== '');
+    }
+    // Block list: consume the `  - name` lines that follow. `match[0]` stops
+    // before the newline, so the first split element is the empty tail of the
+    // matched line itself — dropping it is required, not cosmetic: treating it
+    // as a non-item ended the loop immediately and made every block-list skill
+    // parse as "no packs", which is how this linter first shipped green against
+    // the very defect it exists to catch.
+    const rest = front.slice(match.index + match[0].length).split('\n').slice(1);
+    const out: string[] = [];
+    for (const line of rest) {
+        const item = /^\s*-\s*(.+?)\s*$/.exec(line);
+        if (item === null) break;
+        out.push((item[1] ?? '').replace(/^['"]|['"]$/g, ''));
+    }
+    return out;
+}
+
+function check_lane(lane: string, bundle: StackBundle): void {
+    const members = [...bundle.build, ...bundle.review];
+    if (members.length === 0) {
+        findings.push(`${lane}: bundle is empty — a lane must name at least one skill.`);
+        return;
+    }
+    for (const name of new Set(members)) {
+        // 1. RESOLUTION
+        if (!fs.existsSync(skill_path(name))) {
+            findings.push(
+                `${lane}: bundle member \`${name}\` has no ` +
+                    `\`src/skills/${name}/SKILL.md\` — the verb would resolve to nothing.`,
+            );
+            continue;
+        }
+        // 2. PACK REACH
+        if (!bundle.pack_agnostic) continue;
+        const packs = packs_of(name);
+        if (packs === null) {
+            findings.push(
+                `${lane}: bundle member \`${name}\` declares no \`packs:\` — ` +
+                    'a pack-agnostic lane cannot verify it ships everywhere.',
+            );
+            continue;
+        }
+        const offenders = packs.filter((p) => !STACK_NEUTRAL_PACKS.has(p));
+        if (offenders.length > 0) {
+            findings.push(
+                `${lane}: lane is \`pack_agnostic\` but member \`${name}\` ships only in ` +
+                    `[${offenders.join(', ')}] — a consumer without that pack gets nothing. ` +
+                    'This is the `plain → blade-ui` defect class.',
+            );
+        }
+    }
+}
+
+function main(): number {
+    const lanes = Object.keys(STACK_BUNDLES).sort();
+    if (lanes.length === 0) {
+        process.stderr.write('lint-ui-stack-bundles: STACK_BUNDLES is empty — nothing to check.\n');
+        return 1;
+    }
+    for (const lane of lanes) {
+        check_lane(lane, STACK_BUNDLES[lane] as StackBundle);
+    }
+
+    // A lane usable as a fallback must be pack-agnostic, else the fallback
+    // itself is the thing that fails for an unpredictable consumer.
+    const plain = STACK_BUNDLES['plain'];
+    if (plain === undefined) {
+        findings.push('plain: missing — it is the documented DEFAULT_DIRECTIVE lane.');
+    } else if (!plain.pack_agnostic) {
+        findings.push(
+            'plain: the fallback lane must be `pack_agnostic` — every unrecognised ' +
+                'project lands here and its packs are unknown.',
+        );
+    }
+
+    if (findings.length > 0) {
+        for (const f of findings) {
+            process.stdout.write(`lint-ui-stack-bundles: ${f}\n`);
+        }
+        process.stderr.write(
+            `lint-ui-stack-bundles: ${findings.length} finding(s) across ${lanes.length} lane(s).\n`,
+        );
+        return 1;
+    }
+    if (!QUIET) {
+        process.stdout.write(
+            `lint-ui-stack-bundles: ${lanes.length} lane(s) clean — every bundle member ` +
+                'resolves, and every pack-agnostic lane stays stack-neutral.\n',
+        );
+    }
+    return 0;
+}
+
+process.exit(main());