@event4u/agent-config 14.12.0 → 14.14.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/semantic_noop.ts

@@ -0,0 +1,167 @@
+/**
+ * The semantic no-op gate — `road-to-harness-promotion-bridge` step 7.4.
+ *
+ * > *Reject semantic no-ops. A no-op detector plus a minimum
+ * > material-improvement threshold. The master kept the cooldown and lineage
+ * > from the same attack and dropped both gates.*
+ * > verify: **a paraphrase-only candidate is refused before the cascade.**
+ *
+ * ## "Before the cascade" — what that resolves to in this tree
+ *
+ * There is no artefact named "cascade" here; the evaluation cascade is the
+ * lifecycle spine, `proposed -> diagnostic-evaluated -> selection-evaluated ->
+ * …`. So "before the cascade" means: while the candidate is still `proposed`,
+ * before the first transition and before anything expensive runs.
+ * {@link screenSemanticNoOps} is that stage, and it is SYNCHRONOUS for the same
+ * reason `screenNearDuplicates` is — a synchronous function cannot await a
+ * network call, so the zero-model-call property follows from the signature
+ * rather than from a promise the body has to keep.
+ *
+ * ## Two gates, because the step asks for two
+ *
+ * 1. **The no-op detector.** {@link isSemanticNoOp} — a candidate whose text is
+ *    a paraphrase of what it replaces. Measured with `shingleOverlap`, the same
+ *    primitive `curator_ops`'s near-duplicate screen and `lint_originality` use.
+ * 2. **The minimum material-improvement threshold.** A candidate that is not a
+ *    paraphrase can still be a rounding error;
+ *    {@link MIN_MATERIAL_IMPROVEMENT_PERCENT} is the floor its measured delta
+ *    must clear.
+ *
+ * Both are needed and neither implies the other: a total rewrite that changes
+ * nothing measurable passes (1) and fails (2); a one-word change with a large
+ * measured delta passes (2) and fails (1). Shipping one of the two is what the
+ * master did.
+ */
+import { NEAR_DUPLICATE_THRESHOLD } from './curator_ops.js';
+import { shingleOverlap } from './shingle_similarity.js';
+
+/**
+ * Containment-overlap percent at which a candidate is a paraphrase of what it
+ * replaces.
+ *
+ * **Measured bound, stated rather than left for a reader to discover.**
+ * `shingleOverlap` uses 8-word shingles, so ONE substitution breaks eight
+ * shingles. On a one-sentence candidate (~10 shingles) that is already a
+ * 45-point drop and no paraphrase can reach 70 %; on rule-body-sized text
+ * (~60 words, 56 shingles) the same edit measures 85.7 %. The detector is
+ * therefore meaningful for the corpus it will see — rule and skill bodies — and
+ * weak for one-liners. `revisit-if` candidates turn out to be short.
+ *
+ * Pinned EQUAL to {@link NEAR_DUPLICATE_THRESHOLD} rather than given its own
+ * number, and the equality is the argument: both questions are "is this text
+ * substantially the text we already have", measured on the same primitive, and
+ * two independently-tuned constants for one question is how they drift. If one
+ * moves, the reason has to cover both.
+ */
+export const PARAPHRASE_OVERLAP_THRESHOLD = NEAR_DUPLICATE_THRESHOLD;
+
+/**
+ * The smallest measured improvement that counts as material, in percentage
+ * points.
+ *
+ * A STATED default, not a measured optimum — the honest label this repository
+ * uses for a number nobody has derived. `revisit-if` a real promotion is refused
+ * for a delta a human calls material, or admitted for one a human calls noise.
+ * It is deliberately small: the gate exists to reject ZERO, not to set a bar for
+ * ambition.
+ */
+export const MIN_MATERIAL_IMPROVEMENT_PERCENT = 1;
+
+export interface NoOpVerdict {
+    readonly isNoOp: boolean;
+    /** Why, in one clause. Empty when it is not a no-op. */
+    readonly reason: string;
+    readonly overlapPercent: number;
+    /** Literal 0. This stage is deterministic; a model call here would be a defect. */
+    readonly modelCalls: 0;
+}
+
+/**
+ * Is this candidate a semantic no-op against the text it replaces?
+ *
+ * Two ways to be one, and the second is the one a paraphrase detector alone
+ * misses: the text barely moved, or the text moved and the measured effect did
+ * not.
+ */
+export function isSemanticNoOp(
+    baselineText: string,
+    candidateText: string,
+    deltaPercent: number,
+    overlapThreshold: number = PARAPHRASE_OVERLAP_THRESHOLD,
+    minDelta: number = MIN_MATERIAL_IMPROVEMENT_PERCENT,
+): NoOpVerdict {
+    const overlapPercent = shingleOverlap(baselineText, candidateText);
+    if (overlapPercent >= overlapThreshold) {
+        return {
+            isNoOp: true,
+            reason:
+                `paraphrase-only: ${String(overlapPercent)}% shingle overlap with the text it replaces ` +
+                `(threshold ${String(overlapThreshold)}%)`,
+            overlapPercent,
+            modelCalls: 0,
+        };
+    }
+    if (deltaPercent < minDelta) {
+        return {
+            isNoOp: true,
+            reason:
+                `no material improvement: measured delta ${String(deltaPercent)} pp is below the ` +
+                `${String(minDelta)} pp floor`,
+            overlapPercent,
+            modelCalls: 0,
+        };
+    }
+    return { isNoOp: false, reason: '', overlapPercent, modelCalls: 0 };
+}
+
+export class SemanticNoOpError extends Error {
+    readonly candidateId: string;
+    constructor(candidateId: string, reason: string) {
+        super(
+            `candidate '${candidateId}' is a semantic no-op and is refused before the cascade: ${reason}. ` +
+                'Evaluating it would spend trials to measure nothing, and promoting it would grow the ' +
+                'estate by an artefact that says what the estate already says.',
+        );
+        this.name = 'SemanticNoOpError';
+        this.candidateId = candidateId;
+    }
+}
+
+/** @throws {SemanticNoOpError} when the candidate is a no-op. */
+export function assertNotSemanticNoOp(candidateId: string, verdict: NoOpVerdict): void {
+    if (verdict.isNoOp) {
+        throw new SemanticNoOpError(candidateId, verdict.reason);
+    }
+}
+
+export interface NoOpScreenInput {
+    readonly id: string;
+    readonly baselineText: string;
+    readonly candidateText: string;
+    readonly deltaPercent: number;
+}
+
+export interface NoOpScreenResult {
+    readonly admitted: readonly string[];
+    readonly refused: readonly { readonly id: string; readonly reason: string }[];
+    /** Literal 0 — the whole point of a pre-stage is that it is cheaper than what follows. */
+    readonly modelCalls: 0;
+}
+
+/**
+ * The pre-stage: refuse no-ops while every candidate is still `proposed`.
+ *
+ * Synchronous, and it takes TEXT rather than records on purpose — it must be
+ * callable before a candidate has any evaluation results attached, which is the
+ * whole meaning of "before the cascade".
+ */
+export function screenSemanticNoOps(candidates: readonly NoOpScreenInput[]): NoOpScreenResult {
+    const admitted: string[] = [];
+    const refused: { id: string; reason: string }[] = [];
+    for (const c of candidates) {
+        const verdict = isSemanticNoOp(c.baselineText, c.candidateText, c.deltaPercent);
+        if (verdict.isNoOp) refused.push({ id: c.id, reason: verdict.reason });
+        else admitted.push(c.id);
+    }
+    return { admitted, refused, modelCalls: 0 };
+}

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.
         }