@event4u/agent-config 12.1.0 → 13.0.0

package/src/scripts/hooks/skill_route_hook.ts

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+/**
+ * Skill route — `user_prompt_submit` concern
+ * (road-to-inbox-harvest-2026-08-d-runtime-skill-routing Phase 2).
+ *
+ * THE DEFECT THIS CLOSES. A deterministic task→skill ranker has shipped in
+ * this tree for months and is bound to nothing: `score_skill_relevance.rank`
+ * and its `suggest_skill_for_task` wrapper have no production caller, and
+ * `hook_manifest.yaml` had no concern that reached either. A capability that
+ * ships and never runs is indistinguishable from one that was never built —
+ * the same shape `delegation-nudge` was created to end for `classifyTask`, and
+ * this concern is deliberately its twin rather than a new mechanism.
+ *
+ * POINTERS, NEVER BODIES. The injected line names at most three skill IDs and
+ * their scores. It does not carry descriptions, excerpts, or file contents, and
+ * it never instructs the agent to load anything. The reason is the risk this
+ * roadmap's own register ranks first: a pointer line the agent trusts is worse
+ * than no line when the ranking is poor, so what is injected is the cheapest
+ * thing that can still be acted on — and the cheapest thing to ignore.
+ *
+ * SILENCE IS THE DEFAULT, AND BOTH FLOORS ARE MEASURED, NOT GUESSED. `rank`
+ * already drops every zero-scoring skill, but on real prompts it almost always
+ * returns SOMETHING, so "non-empty" is not a usable trigger. Measured over the
+ * routing-matrix corpus (496 prompt lines, `tests/eval/routing-matrix/*.yaml`,
+ * 2026-08-16): top-score median 18, p75 28, p90 30, max 70, and only 4 prompts
+ * score nothing at all.
+ *
+ * TWO floors are needed, because the score alone cannot express the failure at
+ * the short end. `MIN_TOP_SCORE` gates confidence; `MIN_TASK_TERMS` gates the
+ * denominator that confidence is computed over — the scorer divides by the task
+ * term count, so a one-term prompt scores 70/100 against whatever shares that
+ * term. Together they fire on 9.1 % of the corpus. A score floor at the median
+ * with no term floor would fire on half of all turns AND still hand 70/100 to
+ * `"fix it"` — the per-turn-reminder shape this estate has already measured
+ * failing at a 24/29 miss rate. Each constant carries its own derivation below.
+ *
+ * COST, MEASURED RATHER THAN ASSUMED. Ranking re-reads the skill catalogue per
+ * prompt, uncached. Measured 2026-08-16 on this tree: **12.3 ms warm** for a
+ * prompt that reaches the ranker, against the slot's 250 ms p95 budget — about
+ * 5 % of it. A prompt below `MIN_TASK_TERMS` costs **0 ms**, because the term
+ * floor is checked BEFORE the catalogue read; that ordering is deliberate and
+ * is what keeps conversational turns free. No cache is added: a cache would
+ * need an invalidation story for a tree that changes under the session, and
+ * 12.3 ms does not buy one.
+ *
+ * NO ADOPTION THRESHOLD IS COMMITTED HERE. Whether the line changes behaviour
+ * is a question for data, not for this header: `skill_route_pointer_rate` is
+ * registered in `hook-token-budget.json` under the same owner/review discipline
+ * as its sibling advisories, with the same kill standard — a nudge whose
+ * verdicts are measurably ignored gets its trigger tightened or its line
+ * removed. The score floor above is a TRIGGER calibration and is measured; the
+ * adoption threshold is an OUTCOME claim and is deliberately absent.
+ *
+ * DELIVERY PATH — the verified one, copied rather than re-derived. A
+ * `user_prompt_submit` concern returning `{decision:"allow", context:…}` at
+ * exit 0 produces zero stdout: `host_semantics.emitFor` drops the field for
+ * severity `"allow"`. The only shape that survives to
+ * `hookSpecificOutput.additionalContext` is `{decision:"warn", reason,
+ * additional_context}` at exit 2, which `emitFor` reduces to a real process
+ * exit of 0 — it never blocks the turn. `delegation_nudge_hook.ts` carries the
+ * full proof of that mechanism and this concern follows it exactly.
+ *
+ * PLATFORM SCOPE — `claude` only, for the same reason its twin gives:
+ * `host_semantics.VERIFIED_PLATFORMS` covers only `claude`, `cowork`'s
+ * trampoline discards dispatcher stdout unconditionally, and the other
+ * trampolines were never inspected for that property. Extending an exit-2
+ * delivery to an unverified propagation path is the speculative mapping
+ * `host_semantics.ts` exists to prevent.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { readHookStdin } from "./hook_stdin.js";
+import { isSyntheticPrompt } from "../_lib/prompt_shape.js";
+import { resolveSkillsRoot } from "../_lib/skill_catalogue.js";
+import { _tokenize, rank, type RankRow } from "../skill_tools/score_skill_relevance.js";
+
+const EXIT_ALLOW = 0;
+/** See the header: reduced to a real exit of 0 by `emitFor`'s warn branch. */
+const EXIT_WARN = 2;
+
+/**
+ * Minimum top-1 ranker score before this concern speaks.
+ *
+ * **31, not the measured p90 of 30, and the extra point is load-bearing.** The
+ * scorer is `overlap * 70 + personaHit * 30`, so a skill whose PERSONA slug
+ * appears in the prompt scores exactly 30 with zero keyword overlap. A floor of
+ * 30 with a `>=` test therefore admits a pure persona coincidence as if it were
+ * a ranked match. 31 is the smallest floor strictly above that value; it moves
+ * the corpus fire rate from 13.9 % to 9.1 %.
+ */
+export const MIN_TOP_SCORE = 31;
+
+/**
+ * Minimum distinct task terms before the score is trusted at all.
+ *
+ * The scorer divides by `|task_terms|`, so the score is inversely proportional
+ * to prompt length and degenerates at the short end: `"fix it"` tokenizes to
+ * ONE term and hands 70/100 to whichever skills happen to share it, which on
+ * this catalogue means the alphabetically first three. `MIN_TOP_SCORE` cannot
+ * fix that — the number is not too low, the denominator is too small.
+ *
+ * **3 is the routing-matrix corpus's own minimum**, so this floor excludes
+ * ZERO of the 496 prompt lines the score calibration rests on while removing
+ * every degenerate short prompt measured (`"fix it"` 1, `"mach das"` 2,
+ * `"was denkst du dazu"` 2, `"weiter"` 1). A floor of 4 would have cost 10 real
+ * corpus prompts for one tenth of a percentage point.
+ */
+export const MIN_TASK_TERMS = 3;
+
+/** Pointers per line. Three is the ranker's own default `--top`. */
+export const TOP_K = 3;
+
+type JsonValue = string | number | boolean | null | JsonValue[] | { [k: string]: JsonValue };
+type JsonObject = { [k: string]: JsonValue };
+
+function _isObject(v: unknown): v is JsonObject {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Rank a prompt and return the pointers worth injecting, or `[]` for silence.
+ *
+ * Total by construction: a missing root, an unreadable catalogue, or a ranker
+ * error all resolve to `[]`. A routing advisory that can crash a turn is worse
+ * than one that says nothing.
+ */
+export function routePointers(prompt: string, skillsDir: string | null): RankRow[] {
+  if (skillsDir === null) return [];
+  // Denominator floor BEFORE the catalogue read: a prompt too short to score
+  // meaningfully cannot produce a pointer worth 337 file reads either.
+  try {
+    if (_tokenize(prompt).size < MIN_TASK_TERMS) return [];
+  } catch {
+    return [];
+  }
+  let rows: RankRow[];
+  try {
+    rows = rank(prompt, skillsDir);
+  } catch {
+    return [];
+  }
+  const top = rows[0];
+  if (top === undefined || top[1] < MIN_TOP_SCORE) return [];
+  return rows.slice(0, TOP_K);
+}
+
+/**
+ * The injected line. Names the floor it cleared, so a reader can tell a
+ * confident pointer from a lucky one without opening this file.
+ */
+export function buildRouteLine(rows: readonly RankRow[]): string {
+  const pointers = rows.map(([name, score]) => `${name} (${score})`).join(", ");
+  return (
+    `<skill-route>ranked skill pointers for this prompt: ${pointers}. ` +
+    `Deterministic keyword ranker, top-1 at or above ${MIN_TOP_SCORE}/100 — ` +
+    `pointers only, no bodies loaded. Open one if it fits; ignore the line if it does not.</skill-route>`
+  );
+}
+
+function _extractPrompt(payload: JsonObject): string {
+  for (const key of ["prompt", "userPrompt", "user_prompt", "message", "text"]) {
+    const v = payload[key];
+    if (typeof v === "string" && v.trim()) return v;
+  }
+  return "";
+}
+
+function _workspaceRoot(envelope: JsonObject): string {
+  const v = envelope["workspace_root"];
+  return typeof v === "string" && v ? v : process.cwd();
+}
+
+export function main(): number {
+  let envelope: JsonValue = {};
+  try {
+    const raw = readHookStdin();
+    envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
+  } catch {
+    return EXIT_ALLOW; // malformed envelope — never block
+  }
+  const env: JsonObject = _isObject(envelope) ? envelope : {};
+
+  const event = env["event"];
+  const slot = typeof event === "string" && event !== "" ? event : "user_prompt_submit";
+  if (slot !== "user_prompt_submit") return EXIT_ALLOW;
+
+  const payload = _isObject(env["payload"]) ? (env["payload"] as JsonObject) : env;
+  const prompt = _extractPrompt(payload);
+  if (!prompt) return EXIT_ALLOW;
+  if (isSyntheticPrompt(prompt)) return EXIT_ALLOW; // harness turn, not a task
+
+  const rows = routePointers(prompt, resolveSkillsRoot(_workspaceRoot(env)));
+  if (rows.length === 0) return EXIT_ALLOW; // silence is the default
+
+  process.stdout.write(
+    `${JSON.stringify({
+      decision: "warn",
+      reason: `skill-route: ${rows.length} pointer(s), top ${rows[0]![1]}/100`,
+      additional_context: buildRouteLine(rows),
+    })}\n`,
+  );
+  return EXIT_WARN;
+}
+
+// Bundle-safety: never auto-run when inlined into an esbuild bundle, where
+// every module shares the bundle's `import.meta.url`.
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+function _isCliEntry(): boolean {
+  if (typeof __AGENT_CONFIG_BUNDLE__ !== "undefined" && __AGENT_CONFIG_BUNDLE__) return false;
+  if (process.argv[1] === undefined) return false;
+  const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+  if (import.meta.url === argvUrl) return true;
+  try {
+    const here = fs.realpathSync(fileURLToPath(import.meta.url));
+    const argv = fs.realpathSync(path.resolve(process.argv[1]));
+    return here === argv;
+  } catch {
+    return false;
+  }
+}
+
+if (_isCliEntry()) {
+  process.exit(main());
+}

package/src/scripts/hooks/ui_route_nudge_hook.ts

@@ -30,9 +30,12 @@
  * degradation valve `design_slop_hook` carries, for the same reason: an agent
  * that has decided to proceed must not be re-prompted into a loop.
  *
- * HOST BOUNDARY, STATED RATHER THAN IMPLIED. `pre_tool_use` exists on three
- * hosts. Everywhere else this concern has nowhere to bind and the obligation
- * stays model-carried, exactly as the two rules already declare. Run
+ * HOST BOUNDARY, STATED RATHER THAN IMPLIED. `pre_tool_use` is BOUND on three
+ * hosts. Everywhere else the obligation stays model-carried, exactly as the two
+ * rules already declare. Corrected 2026-08-17: this comment said the concern has
+ * "nowhere to bind" elsewhere, which the manifest's own `native_event_aliases`
+ * table refutes for cursor, cline and gemini — unbound, not unbindable. See
+ * `docs/contracts/hook-architecture-v1.md` § Which hosts carry pre_tool_use. Run
  * `agent-config hooks:status` for the host you are actually on.
  *
  * Default-OFF: no-ops unless `hooks.ui_route_nudge.enabled: true`.

package/src/scripts/lint_design_antipattern_parity.ts

@@ -29,6 +29,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { GateLedger } from './_lib/gate_ledger.js';
 import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const QUIET = process.argv.includes('--quiet');
@@ -44,6 +45,14 @@ export type Status = (typeof STATUSES)[number];
 export interface ParityFinding {
     kind: string;
     msg: string;
+    /**
+     * The catalog id this finding is about, when it is about one.
+     *
+     * Carried explicitly so the per-target ledger can attribute a failure
+     * without parsing it back out of `msg`. Absent on structural findings
+     * (a missing § Detector status section is about the document, not an id).
+     */
+    id?: string;
 }
 
 const ENTRY_ROW = /^\|\s*((?:V|C|T|L|M|CP)\d+)\s*\|/gm;
@@ -89,7 +98,7 @@ export function parityFindings(catalogMd: string, registryTs: string): ParityFin
     const entries = catalogEntries(catalogMd);
     const seen = new Set<string>();
     for (const id of entries) {
-        if (seen.has(id)) out.push({ kind: 'duplicate-entry', msg: `${id}: appears more than once in the catalog tables` });
+        if (seen.has(id)) out.push({ kind: 'duplicate-entry', id, msg: `${id}: appears more than once in the catalog tables` });
         seen.add(id);
     }
 
@@ -98,13 +107,13 @@ export function parityFindings(catalogMd: string, registryTs: string): ParityFin
     // A — every catalog entry is classified.
     for (const id of seen) {
         if (!rows.has(id)) {
-            out.push({ kind: 'unclassified', msg: `${id}: catalog entry missing from § Detector status` });
+            out.push({ kind: 'unclassified', id, msg: `${id}: catalog entry missing from § Detector status` });
         }
     }
     // B — every classified row names a real entry.
     for (const id of rows.keys()) {
         if (!seen.has(id)) {
-            out.push({ kind: 'orphan-status', msg: `${id}: § Detector status row names an entry that no catalog table defines` });
+            out.push({ kind: 'orphan-status', id, msg: `${id}: § Detector status row names an entry that no catalog table defines` });
         }
     }
     // D + E — status vocabulary and reasons.
@@ -112,12 +121,13 @@ export function parityFindings(catalogMd: string, registryTs: string): ParityFin
         if (!(STATUSES as readonly string[]).includes(row.status)) {
             out.push({
                 kind: 'bad-status',
+                id,
                 msg: `${id}: status '${row.status || '(empty)'}' is not one of ${STATUSES.join(', ')}`,
             });
             continue;
         }
         if (row.status !== 'backed' && row.note === '') {
-            out.push({ kind: 'missing-reason', msg: `${id}: status '${row.status}' carries no reason` });
+            out.push({ kind: 'missing-reason', id, msg: `${id}: status '${row.status}' carries no reason` });
         }
     }
 
@@ -126,7 +136,7 @@ export function parityFindings(catalogMd: string, registryTs: string): ParityFin
     const registry = new Set(registryCatalogIds(registryTs));
     for (const id of backed) {
         if (!registry.has(id)) {
-            out.push({ kind: 'backed-without-rule', msg: `${id}: marked backed but no registry rule declares that catalogId` });
+            out.push({ kind: 'backed-without-rule', id, msg: `${id}: marked backed but no registry rule declares that catalogId` });
         }
     }
     for (const id of registry) {
@@ -134,6 +144,7 @@ export function parityFindings(catalogMd: string, registryTs: string): ParityFin
             const known = rows.get(id);
             out.push({
                 kind: 'rule-without-backed',
+                id,
                 msg: known
                     ? `${id}: a registry rule declares this catalogId but § Detector status marks it '${known.status}'`
                     : `${id}: a registry rule declares this catalogId and no catalog entry carries it`,
@@ -167,8 +178,31 @@ export function main(): number {
     const registryTs = fs.readFileSync(REGISTRY, 'utf-8');
     const findings = parityFindings(catalogMd, registryTs);
 
+    const rows = statusRows(catalogMd);
     const entries = catalogEntries(catalogMd).length;
-    const backed = [...statusRows(catalogMd).values()].filter((r) => r.status === 'backed').length;
+    const backed = [...rows.values()].filter((r) => r.status === 'backed').length;
+
+    // Per-target completeness accounting. The target is a catalog ID, and the
+    // planned set is the UNION of the three places an id can appear — catalog
+    // tables, the § Detector status table, and the rule registry — because this
+    // gate's whole subject is parity BETWEEN those sets. Planning only the
+    // catalog would leave an orphan status row or a registry-only id
+    // unaccounted, which is the direction the gate exists to catch.
+    const ledger = new GateLedger('lint_design_antipattern_parity');
+    const targets = [
+        ...new Set([
+            ...catalogEntries(catalogMd),
+            ...rows.keys(),
+            ...registryCatalogIds(registryTs),
+        ]),
+    ].sort();
+    ledger.plan(targets);
+    const failedIds = new Set(findings.map((f) => f.id).filter((v): v is string => v !== undefined));
+    for (const id of targets) {
+        if (failedIds.has(id)) ledger.fail(id, 'parity finding');
+        else ledger.complete(id);
+    }
+    ledger.report();
 
     if (findings.length === 0) {
         _print(`✅  catalog ↔ rule parity OK — ${entries} entries classified, ${backed} detector-backed`);

package/src/scripts/lint_harvest_provenance.ts

@@ -49,6 +49,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { GateLedger } from './_lib/gate_ledger.js';
 import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const _FILE = fileURLToPath(import.meta.url);
@@ -432,7 +433,40 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     const text = fs.readFileSync(ledgerPath, 'utf-8');
     const { records, findings } = lintLedgerText(text, REPO);
     const citations = [...collectCitations(REPO), ...collectPersonaSources(REPO)];
-    const allFindings = [...findings, ...findOrphanCitations(citations, records)];
+    const orphans = findOrphanCitations(citations, records);
+    const allFindings = [...findings, ...orphans];
+
+    // Per-target completeness accounting over the two populations this gate
+    // reasons about: the ledger's own rows, and the citations that point at
+    // them. Both are legitimately EMPTY today, and that is exactly why the
+    // accounting is worth having — a green line over zero rows and a green line
+    // over a hundred checked rows read identically without it, which is the
+    // failure the success message above already tries to talk its way out of in
+    // prose. The ledger states it structurally instead.
+    const ledger = new GateLedger('lint_harvest_provenance');
+    const known = new Set(records.map((r) => r.harvest_id));
+    // The row population is every PARSED ledger line, not `records`: a row that
+    // fails validation or uniqueness is `continue`d and never reaches `records`,
+    // so planning `records` would plan exactly the rows that passed and account
+    // for none of the ones that did not — an accounting that can only ever read
+    // 100 %. Lines are the stable key; a Finding already carries one.
+    const { parsed } = parseLedgerText(text);
+    const badLines = new Set(findings.filter((f) => f.line > 0).map((f) => f.line));
+    ledger.plan([
+        ...parsed.map((r) => `row:${String(r.line)}`),
+        ...citations.map((c) => `citation:${c.id}@${c.file}`),
+    ]);
+    for (const r of parsed) {
+        const id = `row:${String(r.line)}`;
+        if (badLines.has(r.line)) ledger.fail(id, 'ledger-row finding');
+        else ledger.complete(id);
+    }
+    for (const c of citations) {
+        const id = `citation:${c.id}@${c.file}`;
+        if (known.has(c.id)) ledger.complete(id);
+        else ledger.fail(id, 'orphan citation — no ledger row carries this harvest id');
+    }
+    ledger.report();
 
     if (allFindings.length > 0) {
         for (const f of allFindings) {

package/src/scripts/lint_rule_skill_pack_reach.ts

@@ -66,6 +66,7 @@ import { fileURLToPath } from 'node:url';
 
 import { parse as parseYaml } from 'yaml';
 
+import { GateLedger } from './_lib/gate_ledger.js';
 import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -404,6 +405,48 @@ function main(argv: readonly string[] = process.argv.slice(2)): number {
     const errors = findings.filter((f) => f.kind === 'unreachable-route');
     const advisories = findings.filter((f) => f.kind === 'unrouted-skill');
 
+    // Per-target completeness accounting over BOTH populations this gate
+    // reasons about, id-prefixed so they stay distinguishable in one tally.
+    // The skips are the point: check 1 walks past every unscoped rule and
+    // check 2 past every unscoped skill, because "ships everywhere" makes the
+    // reachability question inapplicable rather than satisfied. Without the
+    // ledger those walk-pasts were indistinguishable from checks that passed —
+    // the exact "checked 20 of 300, printed one green line" shape.
+    //
+    // This tally is deliberately NOT the `scanned:` line below. That line is
+    // the machine-read coverage contract and stays the rule count; this is the
+    // human-auditable breakdown beside it, per `_lib/gate_ledger` § report.
+    const ledger = new GateLedger('lint_rule_skill_pack_reach');
+    const routedSkills = [...new Set(rules.flatMap((r) => r.routesToSkills))]
+        .filter((sk) => skillPacks.has(sk))
+        .sort();
+    ledger.plan([
+        ...rules.map((r) => `rule:${r.name}`),
+        ...routedSkills.map((sk) => `skill:${sk}`),
+    ]);
+    const failedSubjects = new Set(findings.map((f) => f.subject));
+    for (const rule of rules) {
+        const id = `rule:${rule.name}`;
+        if (rule.packs.length === 0) {
+            ledger.skip(id, 'not_applicable_kind');
+        } else if ([...failedSubjects].some((sub) => sub.startsWith(`${rule.name} → skill:`))) {
+            ledger.fail(id, 'unreachable-route');
+        } else {
+            ledger.complete(id);
+        }
+    }
+    for (const sk of routedSkills) {
+        const id = `skill:${sk}`;
+        if ((skillPacks.get(sk) ?? []).length === 0) {
+            ledger.skip(id, 'not_applicable_kind');
+        } else if (failedSubjects.has(id)) {
+            ledger.fail(id, 'unrouted-skill');
+        } else {
+            ledger.complete(id);
+        }
+    }
+    ledger.report();
+
     // --quiet suppresses the per-finding lines but never the count line: this
     // gate is expected to stay non-empty for a while, and a quiet run that
     // printed nothing at all would read as clean.

package/src/scripts/lint_skill_router_head.ts

@@ -38,6 +38,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { GateLedger } from './_lib/gate_ledger.js';
 import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
 
 const _FILE = fileURLToPath(import.meta.url);
@@ -204,6 +205,26 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     const heads = collectSkillHeads(path.join(REPO, SKILLS_REL));
     const { findings, staleAllowlist } = evaluate(heads);
 
+    // Per-target completeness accounting. The interesting outcome here is the
+    // SKIP: a grandfathered head is over the cap and deliberately unchecked, so
+    // without a ledger it was indistinguishable from a head that passed. The
+    // allowlist size is already printed, but only the ledger ties each skipped
+    // name to the reason it went unchecked.
+    const ledger = new GateLedger('lint_skill_router_head');
+    ledger.plan(heads.map((h) => h.name));
+    const failed = new Set(findings.map((f) => f.skill));
+    const allow = new Set(GRANDFATHERED);
+    for (const h of heads) {
+        if (failed.has(h.name)) {
+            ledger.fail(h.name, `${String(h.lines)} lines over the ${String(MAX_HEAD_LINES)}-line cap with no mode bodies`);
+        } else if (h.lines > MAX_HEAD_LINES && allow.has(h.name)) {
+            ledger.skip(h.name, 'declared_exemption');
+        } else {
+            ledger.complete(h.name);
+        }
+    }
+    ledger.report();
+
     for (const s of staleAllowlist) {
         process.stderr.write(
             `⚠️   lint_skill_router_head: '${s}' is grandfathered but no longer over the cap — remove it from GRANDFATHERED so the ratchet keeps its teeth\n`,

package/src/scripts/mcp_server/consumer_tool_catalog.json

@@ -544,10 +544,33 @@
     },
     {
       "name": "suggest_skill_for_task",
-      "description": "[stub — implemented on demand] Match a free-form task description to the most relevant skills, ranked by their frontmatter triggers. Use to pick a skill for a described task before starting work. Read-only. Returns a ranked list of skills with name, description, and match reason.",
+      "description": "Match a free-form task description to the most relevant skills, ranked by a deterministic keyword scorer over SKILL.md frontmatter. Use when a skill you need is not in the catalogue the host delivered — a measured host dropped 402 entries from its model-visible list — so asking by name is impossible while asking by task is not. Read-only: no shell, no writes, and no skill bodies are returned, only names, scores and declared personas.",
       "side_effect": "ro",
-      "implemented_on": [],
-      "input_schema": {}
+      "implemented_on": [
+        "stdio"
+      ],
+      "input_schema": {
+        "type": "object",
+        "required": [
+          "task"
+        ],
+        "properties": {
+          "task": {
+            "type": "string",
+            "description": "Free-form description of the task to match skills against."
+          },
+          "limit": {
+            "type": "integer",
+            "minimum": 1,
+            "default": 5,
+            "description": "Maximum number of skills to return. Defaults to 5."
+          }
+        },
+        "additionalProperties": false
+      },
+      "annotations": {
+        "readOnlyHint": true
+      }
     },
     {
       "name": "sync_agent_settings",

package/src/scripts/mcp_server/tool_catalog_source.ts

@@ -96,30 +96,12 @@ export const STUB_TOOLS: readonly StubToolSource[] = [
             additionalProperties: false,
         },
     },
-    {
-        name: 'suggest_skill_for_task',
-        description:
-            'Match a free-form task description to the most relevant ' +
-            'skills, ranked by their frontmatter triggers. Use to pick a ' +
-            'skill for a described task before starting work. Read-only. ' +
-            'Returns a ranked list of skills with name, description, and ' +
-            'match reason.',
-        side_effect: 'ro',
-        input_schema: {
-            type: 'object',
-            properties: {
-                task: { type: 'string', description: 'Free-form description of the task to find a skill for.' },
-                limit: {
-                    type: 'integer',
-                    minimum: 1,
-                    default: 5,
-                    description: 'Maximum number of skills to return. Defaults to 5.',
-                },
-            },
-            required: ['task'],
-            additionalProperties: false,
-        },
-    },
+    // `suggest_skill_for_task` moved to ALLOWLIST in mcp_server/tools.ts
+    // (road-to-inbox-harvest-2026-08-d-runtime-skill-routing 4.1) — it is
+    // implemented now, and `build_mcp_catalog` refuses a name registered in
+    // both places. Its published input schema (`task` + `limit`) was carried
+    // over verbatim rather than re-designed: the stub is a contract consumers
+    // may already have read.
     {
         name: 'mine_session',
         description:

package/src/scripts/mcp_server/tools.ts

@@ -1210,7 +1210,94 @@ async function _readResourceBodyHandler(
 // unlisted tool. Boot-time stderr log enumerates the registered set.
 // ---------------------------------------------------------------------
 
+/**
+ * `suggest_skill_for_task` — the recovery path for a truncated catalogue.
+ *
+ * Promoted from a discovery stub because the defect it answers is measured, not
+ * hypothetical: on the one host that publishes its own truncation, a default
+ * install had 402 entries dropped from the model-visible skills list — the
+ * host's own count against its own denominator, not a subtraction over ours
+ * (`agents/evidence/analysis/scoped-projection-host-delivery.md`). An agent
+ * that cannot see a skill also cannot ask for it by name, so the only reachable
+ * question is "what fits this task" — which is what the deterministic ranker
+ * answers, over the TREE rather than over the host's catalogue.
+ *
+ * Read-only and shell-free by construction: it reads SKILL.md frontmatter and
+ * returns names, scores and declared personas. No skill BODY is returned — the
+ * caller opens what it picked, so a wrong rank costs one read rather than a
+ * context payload.
+ */
+async function _suggestSkillForTaskHandler(
+    args: Record<string, unknown>,
+    consumerRoot: string,
+): Promise<Record<string, unknown>> {
+    const task = typeof args['task'] === 'string' ? args['task'] : '';
+    if (task.trim() === '') {
+        return { status: 'error', error: 'task must be a non-empty string', suggestions: [] };
+    }
+    // `limit`, not `top` — the stub published `limit` and a consumer may have
+    // read that contract already. Renaming it on promotion would break a
+    // caller for cosmetic reasons.
+    const limitRaw = args['limit'];
+    const limit =
+        typeof limitRaw === 'number' && Number.isFinite(limitRaw) ? Math.floor(limitRaw) : 5;
+
+    const catalogue = await import('../_lib/skill_catalogue.js');
+    const skillsDir = catalogue.resolveSkillsRoot(consumerRoot);
+    if (skillsDir === null) {
+        // A missing catalogue is UNKNOWN, never "no skill fits this task". The
+        // second reads as a ranked answer and would be a confident empty list —
+        // the same zero-from-silence failure `capture_skill_catalogue` refuses.
+        return {
+            status: 'no_catalogue',
+            searched: [...catalogue.DEFAULT_CATALOGUE_ROOTS],
+            consumer_root: consumerRoot,
+            suggestions: [],
+        };
+    }
+
+    const { rank } = await import('../skill_tools/score_skill_relevance.js');
+    const rows = rank(task, skillsDir).slice(0, Math.max(1, limit));
+    return {
+        status: 'ok',
+        skills_root: skillsDir,
+        suggestions: rows.map(([name, score, personas]) => ({ skill: name, score, personas })),
+    };
+}
+
 export const ALLOWLIST: Record<string, BuiltinTool> = {
+    suggest_skill_for_task: {
+        name: 'suggest_skill_for_task',
+        side_effect: 'ro',
+        description:
+            'Match a free-form task description to the most relevant skills, ' +
+            'ranked by a deterministic keyword scorer over SKILL.md ' +
+            'frontmatter. Use when a skill you need is not in the catalogue ' +
+            'the host delivered — a measured host dropped 402 entries from ' +
+            'its model-visible list — so asking by name is impossible while ' +
+            'asking by task is not. ' +
+            'Read-only: no shell, no writes, and no skill bodies are returned, ' +
+            'only names, scores and declared personas.',
+        input_schema: {
+            type: 'object',
+            required: ['task'],
+            properties: {
+                task: {
+                    type: 'string',
+                    description:
+                        'Free-form description of the task to match skills against.',
+                },
+                limit: {
+                    type: 'integer',
+                    minimum: 1,
+                    default: 5,
+                    description: 'Maximum number of skills to return. Defaults to 5.',
+                },
+            },
+            additionalProperties: false,
+        },
+        handler: _suggestSkillForTaskHandler,
+    },
     lint_skills: {
         name: 'lint_skills',
         side_effect: 'ro',