@event4u/agent-config 12.0.0 → 13.0.0

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',

package/src/scripts/migration_status.ts

@@ -21,6 +21,8 @@ import { dirname, resolve } from 'node:path';
 import process from 'node:process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
+import { workspaceIdentity } from './_lib/git_common_dir.js';
+
 // ---------------------------------------------------------------------------
 // Categories and phase mapping
 // ---------------------------------------------------------------------------
@@ -157,8 +159,22 @@ function git(args: readonly string[], cwd: string): string {
     return execFileSync('git', [...args], { cwd, encoding: 'utf-8' }).trim();
 }
 
+/**
+ * Census row R8 — the tree's only exported `repoRoot()`, which is why nothing
+ * imports it: it lives in a report script.
+ *
+ * It used to spawn `rev-parse --show-toplevel` with no env scrub, so an
+ * inherited `GIT_DIR` answered about the hook's repository, and it threw an
+ * `execFileSync` error outside a repo. The throw is preserved deliberately —
+ * every caller here treats a missing root as fatal — but it is now a message
+ * that names the reason instead of a git subprocess failure.
+ */
 export function repoRoot(): string {
-    return git(['rev-parse', '--show-toplevel'], process.cwd());
+    const root = workspaceIdentity(process.cwd()).repoRoot;
+    if (!root.resolved) {
+        throw new Error(`cannot resolve repo root: ${root.reason}`);
+    }
+    return root.value;
 }
 
 export function trackedPythonFiles(root: string): string[] {