@event4u/agent-config 14.11.0 → 14.13.0

package/src/scripts/_lib/runtime_wiring_checks.ts

@@ -0,0 +1,430 @@
+/**
+ * Runtime-wiring checks for `agent-config doctor`.
+ *
+ * `road-to-skill-ecosystem-runtime-enforcement` Phase 2, Steps 2-5. The gate
+ * estate checks ARTIFACTS — is the rule written, is the projection byte-exact,
+ * does the manifest parse. Nothing checked whether the wiring is LIVE: whether
+ * the settings resolver returns anything, whether the router artifact parses,
+ * whether each registered hook resolves to something executable, and whether an
+ * inherited git-discovery variable is silently re-pointing every gate at another
+ * repository.
+ *
+ * All four are REPORTS. `doctor` writes nothing and always exits zero, so a
+ * check here returns a verdict and never a refusal — the point is that a
+ * disabled or mis-wired estate becomes VISIBLE, not that a diagnostic starts
+ * failing builds. A gate that wanted to refuse would belong in the gate estate.
+ *
+ * Extracted into `_lib/` rather than added to `cmd_doctor.ts` for a stated
+ * reason: that file is 3,700 lines and `check_source_size_budget` counts every
+ * line above 1,500, so four checks written inline would be charged against a
+ * budget while the same code in a new module is free. The seam is also what
+ * makes them unit-testable without booting the CLI.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+
+import { parse as parseYaml } from 'yaml';
+
+import { inheritedGitOverrides } from './repo_root.js';
+
+/** The verdict shape `cmd_doctor` renders. Mirrors its internal `Dict` rows. */
+export interface WiringCheck {
+    id: string;
+    /**
+     * The four the doctor's own report contract publishes. `info` was a fifth
+     * here for one commit and is gone: the MCP `doctor_report` tool asserts the
+     * published union, so a fifth value that never reached that contract failed
+     * the tool's shape test rather than appearing in a report. A vocabulary a
+     * consumer cannot receive is not a vocabulary.
+     */
+    status: 'ok' | 'warn' | 'fail' | 'skipped';
+    message: string;
+    remedy: string;
+}
+
+/**
+ * Step 2 — the settings resolver returns something, and WHICH FILE won.
+ *
+ * The cascade is user-global then project, last write winning. Nearly twenty
+ * rules in this suite tell an agent to read `.agent-settings.yml` to learn
+ * whether a feature is on, and every one of them is wrong about a key set on
+ * another layer. Reporting the winning FILE per key is the part that makes the
+ * check worth running — a value alone cannot be argued with.
+ */
+export function checkSettingsResolution(
+    iterOverrides: () => Iterable<[string, unknown, string]>,
+): WiringCheck {
+    let pairs: [string, unknown, string][];
+    try {
+        pairs = [...iterOverrides()];
+    } catch (e) {
+        return {
+            id: 'settings-resolution',
+            status: 'fail',
+            message: `settings cascade did not resolve: ${e instanceof Error ? e.message : String(e)}`,
+            remedy: 'check the YAML in every layer `agent-config settings:get <key>` reports',
+        };
+    }
+    if (pairs.length === 0) {
+        return {
+            id: 'settings-resolution',
+            // `skipped`, not `ok`: the cascade RESOLVED and there was nothing
+            // in it, which is a check that had nothing to inspect rather than a
+            // check that passed. Reporting `ok` here would read as "settings
+            // resolved fine" on a tree where no setting exists at all — the
+            // same conflation the reach check exists to remove elsewhere.
+            status: 'skipped',
+            message:
+                'settings cascade resolves, and NO layer sets any key — every read falls to the ' +
+                'template default. That is a valid state, not a failure: a fresh project has no settings.',
+            remedy: '',
+        };
+    }
+    // Last writer wins, which is the resolver's own rule — so the winning file
+    // is the LAST occurrence of a key, not the first.
+    const winner = new Map<string, string>();
+    for (const [key, , file] of pairs) winner.set(key, file);
+    const byFile = new Map<string, number>();
+    for (const file of winner.values()) byFile.set(file, (byFile.get(file) ?? 0) + 1);
+    const summary = [...byFile.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .map(([f, n]) => `${path.basename(f)}=${String(n)}`)
+        .join(' · ');
+    return {
+        id: 'settings-resolution',
+        status: 'ok',
+        message: `${String(winner.size)} key(s) resolved across ${String(byFile.size)} layer(s) — ${summary}`,
+        remedy: '',
+    };
+}
+
+/**
+ * Step 3 — the router artifact exists, PARSES, and reports its rule count.
+ *
+ * Parsing is the half that matters. A router file that exists but does not parse
+ * fails silently at load: the host reads no rules and behaves like a tree with
+ * none, which is indistinguishable from a correctly minimal configuration.
+ */
+export function checkRouterArtifact(repoRoot: string, rel = 'dist/router.json'): WiringCheck {
+    const abs = path.join(repoRoot, rel);
+    if (!fs.existsSync(abs)) {
+        return {
+            id: 'router-artifact',
+            status: 'warn',
+            message: `${rel} is absent — no rule router is deployed`,
+            remedy: 'task generate-tools',
+        };
+    }
+    let doc: unknown;
+    try {
+        doc = JSON.parse(fs.readFileSync(abs, 'utf8'));
+    } catch (e) {
+        return {
+            id: 'router-artifact',
+            status: 'fail',
+            message: `${rel} exists but does NOT parse: ${e instanceof Error ? e.message : String(e)}`,
+            remedy: 'task generate-tools (a present-but-unparseable router loads as zero rules)',
+        };
+    }
+    const rules = _routerRuleCount(doc);
+    if (rules === 0) {
+        return {
+            id: 'router-artifact',
+            status: 'warn',
+            message: `${rel} parses and carries ZERO rules — a router with no rules routes nothing`,
+            remedy: 'task generate-tools',
+        };
+    }
+    return { id: 'router-artifact', status: 'ok', message: `${rel} parses · ${String(rules)} rule(s)`, remedy: '' };
+}
+
+/** Count routed rules across whichever shape the artifact uses. */
+export function _routerRuleCount(doc: unknown): number {
+    if (doc === null || typeof doc !== 'object') return 0;
+    const d = doc as Record<string, unknown>;
+    if (Array.isArray(d['rules'])) return d['rules'].length;
+    let n = 0;
+    for (const v of Object.values(d)) {
+        if (Array.isArray(v)) n += v.length;
+        else if (v !== null && typeof v === 'object') n += _routerRuleCount(v);
+    }
+    return n;
+}
+
+export interface HookProbe {
+    id: string;
+    script: string;
+    resolves: boolean;
+    ms: number | null;
+}
+
+/**
+ * Step 4 — every registered hook resolves to a real file, with its cost.
+ *
+ * Cost is reported PER HOOK rather than as a total, because a latency
+ * regression is only actionable where it is incurred: a 300 ms total tells you
+ * nothing, while one 280 ms concern names itself.
+ *
+ * `probe` defaults to a real invocation with `--help`, which every dispatcher
+ * entry point accepts and which does no work. Injectable so the unit tests do
+ * not spawn 53 processes.
+ */
+export function checkHookResolution(
+    repoRoot: string,
+    manifestRel = 'src/scripts/hook_manifest.yaml',
+    probe: ((script: string) => number | null) | null = null,
+): { check: WiringCheck; probes: HookProbe[] } {
+    const abs = path.join(repoRoot, manifestRel);
+    if (!fs.existsSync(abs)) {
+        return {
+            check: {
+                id: 'hook-resolution',
+                status: 'fail',
+                message: `${manifestRel} is absent — the hook estate cannot be enumerated`,
+                remedy: 'restore the manifest; every hook is registered from it',
+            },
+            probes: [],
+        };
+    }
+    let concerns: Record<string, { script?: unknown }>;
+    try {
+        const doc = parseYaml(fs.readFileSync(abs, 'utf8')) as { concerns?: unknown };
+        concerns = (doc.concerns ?? {}) as Record<string, { script?: unknown }>;
+    } catch (e) {
+        return {
+            check: {
+                id: 'hook-resolution',
+                status: 'fail',
+                message: `${manifestRel} does not parse: ${e instanceof Error ? e.message : String(e)}`,
+                remedy: 'fix the manifest YAML',
+            },
+            probes: [],
+        };
+    }
+    const probes: HookProbe[] = [];
+    for (const [id, c] of Object.entries(concerns)) {
+        const script = typeof c.script === 'string' ? c.script : '';
+        const resolves = script !== '' && fs.existsSync(path.join(repoRoot, script));
+        probes.push({ id, script, resolves, ms: resolves && probe !== null ? probe(script) : null });
+    }
+    const broken = probes.filter((p) => !p.resolves);
+    if (broken.length > 0) {
+        return {
+            check: {
+                id: 'hook-resolution',
+                status: 'fail',
+                message:
+                    `${String(broken.length)} of ${String(probes.length)} registered hook(s) do NOT resolve to a file: ` +
+                    broken.map((b) => b.id).join(', '),
+                remedy: 'a registered hook with no script silently no-ops every session — fix the path or drop the entry',
+            },
+            probes,
+        };
+    }
+    const timed = probes.filter((p) => p.ms !== null).sort((a, b) => (b.ms ?? 0) - (a.ms ?? 0));
+    const slowest = timed.length > 0 ? ` · slowest ${timed[0]!.id} ${String(timed[0]!.ms)}ms` : '';
+    return {
+        check: {
+            id: 'hook-resolution',
+            status: 'ok',
+            message: `${String(probes.length)} registered hook(s), all resolving${slowest}`,
+            remedy: '',
+        },
+        probes,
+    };
+}
+
+/** A real `--help` invocation, timed. `null` when it cannot be measured. */
+export function probeHookCost(repoRoot: string, script: string): number | null {
+    const started = Date.now();
+    const r = spawnSync(process.execPath, [path.join(repoRoot, 'scripts-run'), script, '--help'], {
+        cwd: repoRoot,
+        encoding: 'utf8',
+        timeout: 10_000,
+    });
+    if (r.error) return null;
+    return Date.now() - started;
+}
+
+/**
+ * Step 5 — an inherited git-discovery variable.
+ *
+ * The recorded failure: a git hook exports `GIT_DIR` into every child, so a gate
+ * run inside one resolves against whatever that points at — inside a worktree,
+ * the parent checkout. The gate runs, reads the wrong tree, and PASSES. Nothing
+ * about the output says which repository answered.
+ *
+ * Reported as a warning rather than a failure because the variable is legitimate
+ * where git itself set it; what it is not is invisible.
+ */
+export function checkInheritedGitEnv(env: NodeJS.ProcessEnv = process.env): WiringCheck {
+    const found = inheritedGitOverrides(env);
+    if (found.length === 0) {
+        return {
+            id: 'inherited-git-env',
+            status: 'ok',
+            message: 'no git discovery override in the environment — git resolves from the working directory',
+            remedy: '',
+        };
+    }
+    return {
+        id: 'inherited-git-env',
+        status: 'warn',
+        message:
+            `${String(found.length)} git discovery override(s) inherited: ` +
+            found.map((f) => `${f.name}=${f.value}`).join(' · ') +
+            ' — every git call in this process answers for THAT repository, not the working directory',
+        remedy:
+            'unset them before running a gate from inside a git hook (`env -u GIT_DIR -u GIT_WORK_TREE …`), ' +
+            'or resolve the root with _lib/repo_root.ts, which refuses instead of guessing',
+    };
+}
+
+/**
+ * The four runtime-wiring runners, as one table.
+ *
+ * Returned as a map rather than registered inline at each of `cmd_doctor`'s TWO
+ * runner tables: written there it is ~20 lines duplicated, and every line of
+ * that file above 1,500 is charged by `check_source_size_budget`. One factory,
+ * two spreads.
+ */
+/** The four ids, in render order. Spread into `cmd_doctor`'s two id registries. */
+export const WIRING_CHECK_IDS = ['settings-resolution', 'router-artifact', 'hook-resolution', 'inherited-git-env', 'hooks-kill-switch'] as const;
+
+
+/**
+ * The estate kill switch, reported so a DISABLED estate is visible.
+ *
+ * `road-to-skill-ecosystem-runtime-enforcement` Phase 1 Step 7's second clause,
+ * which could not be satisfied until the Phase 2 diagnostic existed. The flag
+ * itself has been implemented since Phase 1; what was missing is that a session
+ * running with every guard switched off looked exactly like one running with
+ * them all armed.
+ *
+ * ONLY the exact value `1` disarms, and the check mirrors that rather than
+ * guessing: a truthy-ish test would report `=0` as disabled, which is the
+ * opposite of what it means.
+ */
+export function checkHooksDisabled(env: NodeJS.ProcessEnv = process.env): WiringCheck {
+    const raw = env['AGENT_CONFIG_DISABLE_HOOKS'];
+    if (raw !== '1') {
+        return {
+            id: 'hooks-kill-switch',
+            status: 'ok',
+            message:
+                raw === undefined || raw === ''
+                    ? 'AGENT_CONFIG_DISABLE_HOOKS is not set — the hook estate is armed'
+                    : `AGENT_CONFIG_DISABLE_HOOKS=${raw} — only the exact value "1" disarms, so the estate is armed`,
+            remedy: '',
+        };
+    }
+    return {
+        id: 'hooks-kill-switch',
+        status: 'warn',
+        message:
+            'AGENT_CONFIG_DISABLE_HOOKS=1 — EVERY hook and shim in this environment is disabled. ' +
+            'A run under this flag enforces nothing, and without this line it would look identical ' +
+            'to one with the whole estate armed.',
+        remedy: 'unset AGENT_CONFIG_DISABLE_HOOKS (it is intended for one command, not a session)',
+    };
+}
+
+export function wiringRunners(opts: {
+    packageRoot: string;
+    iterOverrides: () => Iterable<[string, unknown, string]>;
+}): Record<string, () => WiringCheck> {
+    return {
+        'settings-resolution': () => checkSettingsResolution(opts.iterOverrides),
+        'router-artifact': () => checkRouterArtifact(opts.packageRoot),
+        // Per-hook COST is not probed on the default path: it spawns one process
+        // per registered concern (53 today), turning a read-only diagnostic into
+        // a multi-second one. `probeHookCost` is exported for a caller that wants it.
+        'hook-resolution': () => checkHookResolution(opts.packageRoot).check,
+        'inherited-git-env': () => checkInheritedGitEnv(),
+        'hooks-kill-switch': () => checkHooksDisabled(),
+    };
+}
+
+/**
+ * Managed hook wiring (single-surface model): the deterministic hook matrix
+ * must be registered in ~/.claude/settings.json AND the dispatch target
+ * (`agent-config` binary) must resolve on PATH. Both halves are required —
+ * hooks without a binary silently no-op every session.
+ */
+export interface HookWiringDeps {
+    which: (bin: string) => string | null;
+    packageRoot: string;
+    homeDir: string;
+    buildMatrix: (manifestPath: string) => Record<string, unknown>;
+    managedSignature: string;
+    pluginInstalled: () => boolean;
+}
+
+export function checkHookWiring(deps: HookWiringDeps): WiringCheck {
+    const claude = deps.which('claude');
+    if (claude === null) {
+        return {
+            id: 'hook-wiring',
+            status: 'skipped',
+            message: 'Claude Code CLI not on PATH — hook-wiring check not applicable',
+            remedy: '',
+        };
+    }
+    const settings_path = path.join(deps.homeDir, '.claude', 'settings.json');
+    let missing: string[];
+    try {
+        const matrix = deps.buildMatrix(path.join(deps.packageRoot, 'src', 'scripts', 'hook_manifest.yaml'));
+        const settings = fs.existsSync(settings_path)
+            ? (JSON.parse(fs.readFileSync(settings_path, 'utf8')) as Record<string, unknown>)
+            : {};
+        const hooks = ((settings['hooks'] ?? {}) as Record<string, unknown>) || {};
+        missing = Object.keys(matrix).filter((ev) => {
+            const groups = hooks[ev];
+            if (!Array.isArray(groups)) return true;
+            return !JSON.stringify(groups).includes(deps.managedSignature);
+        });
+    } catch (e) {
+        return {
+            id: 'hook-wiring',
+            status: 'fail',
+            message: `cannot evaluate managed hooks: ${String(e)}`,
+            remedy: 'fix ~/.claude/settings.json (invalid JSON?), then agent-config refresh --global',
+        };
+    }
+    const binary_ok = deps.which('agent-config') !== null;
+    if (missing.length === 0 && binary_ok) {
+        return {
+            id: 'hook-wiring',
+            status: 'ok',
+            message: 'managed hooks registered in ~/.claude/settings.json; dispatch binary on PATH',
+            remedy: '',
+        };
+    }
+    if (missing.length > 0 && deps.pluginInstalled()) {
+        return {
+            id: 'hook-wiring',
+            status: 'warn',
+            message:
+                `managed hooks missing for: ${missing.join(', ')} — currently carried by the ` +
+                'installed plugin (deprecated surface)',
+            remedy: 'agent-config refresh --global (writes the managed settings.json block)',
+        };
+    }
+    const parts: string[] = [];
+    if (missing.length > 0) parts.push(`managed hooks missing for: ${missing.join(', ')}`);
+    if (!binary_ok) parts.push('`agent-config` not on PATH (hooks would silently no-op)');
+    if (parts.length === 0) {
+        // hooks complete, binary missing was the only issue → covered above.
+        parts.push('`agent-config` not on PATH');
+    }
+    return {
+        id: 'hook-wiring',
+        status: 'fail',
+        message: parts.join('; '),
+        remedy: binary_ok
+            ? 'agent-config refresh --global'
+            : 'npm install -g @event4u/agent-config, then agent-config refresh --global',
+    };
+}

package/src/scripts/_lib/skill_catalogue.ts

@@ -93,7 +93,17 @@ export function resolveSkillsRoot(workspaceRoot: string): string | null {
     for (const candidate of DEFAULT_CATALOGUE_ROOTS) {
         const abs = path.join(workspaceRoot, candidate);
         try {
-            if (fs.existsSync(abs) && fs.statSync(abs).isDirectory()) return abs;
+            if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) continue;
+            // NON-EMPTY, and that qualifier is the whole fix. `.claude/skills`
+            // is a gitignored projection, so in a fresh worktree it EXISTS and
+            // holds nothing — and an empty root resolved as a match makes the
+            // ranker report an empty catalogue as an empty RESULT, which is the
+            // silent failure `road-to-inbox-harvest-2026-08-f-skill-selection-evidence`
+            // is about, arriving through a second door. Measured in that run: a
+            // worktree that had never run `generate-tools` ranked zero skills
+            // and exited 0 on a task that scores 47 against `src/skills`.
+            if (fs.readdirSync(abs).length === 0) continue;
+            return abs;
         } catch {
             // Unreadable candidate is not a match; try the next.
         }

package/src/scripts/_lib/skill_estate.ts

@@ -0,0 +1,115 @@
+/**
+ * The skill corpus, measured — the two dimensions `check_estate_count` ratchets.
+ *
+ * WHY TWO. A file count is what a `one_in_one_out` lint can express; it is not
+ * what a skill COSTS. Merging four large skills into one file satisfies a count
+ * ratchet while the description payload a host must carry stays put or grows.
+ * AI council 2/2 (2026-08-24) asked for both dimensions in one gate for exactly
+ * that reason, over the roadmap's own recommendation of a count plus an
+ * informational companion figure: "that supports treating tokens as a coarse
+ * secondary budget — not leaving the only cost-sensitive metric informational
+ * forever."
+ *
+ * WHY NOT THE OTHER TWO CANDIDATES, measured before asking rather than argued:
+ *
+ * - **Catalogue bytes** via `_lib/skill_catalogue.ts` read **0** on this
+ *   checkout. `readProjectedCatalogue` walks `.claude/skills`, which is empty in
+ *   any tree where `task generate-tools` cannot complete — it fails under
+ *   `projection.mode=scoped` without the config package. A ratchet whose reading
+ *   depends on whether a generator ran is a ratchet that reds for the
+ *   environment.
+ * - **Host-listing slots** are the host's decision, not the repository's. A
+ *   measured install published its own budget event stating it had stripped
+ *   every description and dropped 402 entries.
+ *
+ * DEPRECATED SKILLS ARE EXCLUDED, and that is load-bearing rather than tidy:
+ * with them counted, deprecating a skill would create no headroom and the
+ * retirement mechanism would be unusable against its own gate. (Currently 0
+ * skills carry it, so the exclusion is a no-op today and a correctness property
+ * tomorrow.)
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { gpt_tokens } from './token_count.js';
+
+/** Where the corpus lives, POSIX — the same string a base-tree subtree takes. */
+export const SKILLS_POSIX = 'src/skills';
+
+export interface SkillEstate {
+    /** Maintained `SKILL.md` files — `lifecycle: deprecated` excluded. */
+    skill_count: number;
+    /**
+     * Exact-BPE tokens across the maintained skills' `description:` fields.
+     *
+     * `null` when the tokeniser could not resolve. A ratchet must never compare
+     * an exact reading against a proxy one — the numbers differ by more than the
+     * growth a gate is trying to catch, so the metric is reported UNRESOLVED
+     * rather than measured with whatever was available.
+     */
+    skill_description_tokens: number | null;
+    /** Excluded from both figures, reported so the exclusion is visible. */
+    deprecated_count: number;
+}
+
+/** `description:` from a `SKILL.md` frontmatter block, unquoted. */
+export function descriptionOf(text: string): string {
+    const fm = /^---\n([\s\S]*?)\n---/.exec(text);
+    if (fm === null) return '';
+    const m = /^description:\s*(.+)$/m.exec(fm[1]!);
+    if (m === null) return '';
+    return m[1]!.trim().replace(/^["']|["']$/g, '');
+}
+
+/** `lifecycle: deprecated` in the frontmatter — the retirement transition state. */
+export function isDeprecated(text: string): boolean {
+    const fm = /^---\n([\s\S]*?)\n---/.exec(text);
+    if (fm === null) return false;
+    return /^lifecycle:\s*["']?deprecated["']?\s*$/m.test(fm[1]!);
+}
+
+/**
+ * Measure the corpus under `root`.
+ *
+ * `root` is a repository root OR a materialised base-ref tree holding
+ * `src/skills/...`, so the floor side runs this exact function over the base
+ * ref's own tree — the property `check_estate_count` already has for the roadmap
+ * estate, and the reason the "before" side cannot be rewritten by the change
+ * under review.
+ */
+export function measureSkillEstate(root: string): SkillEstate {
+    const base = path.join(root, ...SKILLS_POSIX.split('/'));
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(base, { withFileTypes: true });
+    } catch {
+        return { skill_count: 0, skill_description_tokens: null, deprecated_count: 0 };
+    }
+    let count = 0;
+    let deprecated = 0;
+    let tokens = 0;
+    let exact = true;
+    for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!e.isDirectory()) continue;
+        const p = path.join(base, e.name, 'SKILL.md');
+        let text: string;
+        try {
+            text = fs.readFileSync(p, 'utf-8');
+        } catch {
+            continue;
+        }
+        if (isDeprecated(text)) {
+            deprecated += 1;
+            continue;
+        }
+        count += 1;
+        const r = gpt_tokens(descriptionOf(text));
+        if (!r.exact) exact = false;
+        tokens += r.tokens;
+    }
+    return {
+        skill_count: count,
+        skill_description_tokens: exact ? tokens : null,
+        deprecated_count: deprecated,
+    };
+}