@event4u/agent-config 14.21.0 → 14.23.0

package/src/scripts/audit_mcp_tools.ts

@@ -29,6 +29,30 @@ const _HERE = fileURLToPath(import.meta.url);
 export const ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 export const CATALOG = path.join(ROOT, 'src/scripts/mcp_server/consumer_tool_catalog.json');
 export const TOOLS_TS = path.join(ROOT, 'src/scripts/mcp_server/tools.ts');
+/**
+ * Modules that contribute records to `ALLOWLIST` from OUTSIDE `tools.ts`.
+ *
+ * `tools.ts` sits past the source-size ceiling, so a tool family whose records
+ * would cost ~250 units of excess there is defined in its own module and spread
+ * into the allowlist. This generator indexed `tools.ts` alone, so the five
+ * `graph_*` tools rendered `_stub-only_` in the published inventory — the doc
+ * asserting the exact opposite of the catalogue's own `implemented_on: ["stdio"]`,
+ * and `--check` staying green because it compared the doc against its own wrong
+ * render. Found by an independent review.
+ *
+ * A LIST rather than a directory walk: a walk would silently pick up any future
+ * file with a matching shape, and the point of this index is to say where a
+ * handler actually is. Adding a family here is one line in the same change that
+ * adds the family.
+ */
+export const HANDLER_MODULES: readonly { file: string; label: string; block: string }[] = [
+    { file: path.join(ROOT, 'src/scripts/mcp_server/tools.ts'), label: 'tools.ts', block: 'export const ALLOWLIST' },
+    {
+        file: path.join(ROOT, 'src/scripts/mcp_server/graph_tools.ts'),
+        label: 'graph_tools.ts',
+        block: 'export const GRAPH_TOOLS',
+    },
+];
 export const OUT = path.join(ROOT, 'docs/contracts/mcp-tool-inventory.md');
 
 // Match `<name>: {` entries at 4-space indent inside the TS ALLOWLIST record
@@ -71,28 +95,36 @@ function _relativeToRoot(p: string): string {
     return path.relative(ROOT, p).split(path.sep).join('/');
 }
 
-function _index_handlers(): Map<string, number> {
-    const out = new Map<string, number>();
-    const lines = _splitlines(fs.readFileSync(TOOLS_TS, 'utf-8'));
-    // Only index entries inside the `export const ALLOWLIST` block.
-    let inAllowlist = false;
-    for (let idx = 0; idx < lines.length; idx += 1) {
-        const i = idx + 1;
-        const line = lines[idx] as string;
-        if (line.startsWith('export const ALLOWLIST')) {
-            inAllowlist = true;
-            continue;
-        }
-        if (inAllowlist && line.startsWith('};')) {
-            inAllowlist = false;
-            continue;
-        }
-        if (!inAllowlist) {
+function _index_handlers(): Map<string, { label: string; line: number }> {
+    const out = new Map<string, { label: string; line: number }>();
+    for (const mod of HANDLER_MODULES) {
+        let text: string;
+        try {
+            text = fs.readFileSync(mod.file, 'utf-8');
+        } catch {
             continue;
         }
-        const m = HANDLER_RE.exec(line);
-        if (m) {
-            out.set(m[1] as string, i);
+        const lines = _splitlines(text);
+        // Only index entries inside the module's own registration block.
+        let inBlock = false;
+        for (let idx = 0; idx < lines.length; idx += 1) {
+            const i = idx + 1;
+            const line = lines[idx] as string;
+            if (line.startsWith(mod.block)) {
+                inBlock = true;
+                continue;
+            }
+            if (inBlock && line.startsWith('};')) {
+                inBlock = false;
+                continue;
+            }
+            if (!inBlock) {
+                continue;
+            }
+            const m = HANDLER_RE.exec(line);
+            if (m) {
+                out.set(m[1] as string, { label: mod.label, line: i });
+            }
         }
     }
     return out;
@@ -117,7 +149,11 @@ function _joinSorted(obj: Map<string, number>): string {
     return keys.map((k) => `${k}=${obj.get(k)}`).join(', ');
 }
 
-function _render(catalog: Catalog, handlers: Map<string, number>, cat_lines: Map<string, number>): string {
+function _render(
+    catalog: Catalog,
+    handlers: Map<string, { label: string; line: number }>,
+    cat_lines: Map<string, number>,
+): string {
     const tools = catalog.tools;
     const total = tools.length;
     const by_transport = new Map<string, number>();
@@ -145,7 +181,14 @@ function _render(catalog: Catalog, handlers: Map<string, number>, cat_lines: Map
     lines.push('');
     lines.push('# MCP tool inventory');
     lines.push('');
-    lines.push('> Generated by [`audit_mcp_tools`](../../audit_mcp_tools)');
+    // A BARE command name, and deliberately not a link to this file: an
+    // independent review flagged the previous `../../audit_mcp_tools` as a
+    // path that resolves nowhere and proposed `src/scripts/audit_mcp_tools.ts`.
+    // That fix is refused by `generated_by.test.ts` § 1.4, which forbids a
+    // generated artifact from hard-coding its generator's script path — the
+    // broken link and the literal path are two wrong answers, and the
+    // replacement form the rule names is the runnable command.
+    lines.push('> Generated by `audit_mcp_tools`. Do not edit.');
     lines.push('> from the source-of-truth catalog');
     lines.push('> [`src/scripts/mcp_server/consumer_tool_catalog.json`](../../src/scripts/mcp_server/consumer_tool_catalog.json).');
     lines.push('> Do **not** hand-edit; rerun `./scripts-run src/scripts/audit_mcp_tools --write`.');
@@ -172,10 +215,10 @@ function _render(catalog: Catalog, handlers: Map<string, number>, cat_lines: Map
             cat_line !== undefined
                 ? `[\`consumer_tool_catalog.json:${cat_line}\`](../../src/scripts/mcp_server/consumer_tool_catalog.json#L${cat_line})`
                 : '_missing_';
-        const h_line = handlers.get(name);
+        const h = handlers.get(name);
         const h_cite =
-            h_line !== undefined
-                ? `[\`tools.ts:${h_line}\`](../../src/scripts/mcp_server/tools.ts#L${h_line})`
+            h !== undefined
+                ? `[\`${h.label}:${h.line}\`](../../src/scripts/mcp_server/${h.label}#L${h.line})`
                 : '_stub-only_';
         lines.push(`| \`${name}\` | \`${side}\` | ${transports} | ${cat_cite} | ${h_cite} |`);
     }
@@ -240,6 +283,7 @@ export function main(argv: string[] | null = null): number {
             candidates: [
                 path.posix.join('src', 'scripts', 'mcp_server', 'consumer_tool_catalog.json'),
                 path.posix.join('src', 'scripts', 'mcp_server', 'tools.ts'),
+                path.posix.join('src', 'scripts', 'mcp_server', 'graph_tools.ts'),
             ],
             repoRoot: ROOT,
         });

package/src/scripts/build_mcp_catalog.ts

@@ -163,7 +163,30 @@ export function _buildCatalog(): Record<string, unknown> {
     return {
         schema_version: 1,
         description: CATALOG_DESCRIPTION,
-        install_hint_stdio: `npx -y ${_packageName()} mcp-server`,
+        // `agent-config mcp-server`, not an `npx` form — AI council 2026-09-08,
+        // 2/2 convergent (road-to-a-graph-that-is-shipped 4.2, Fork 3 option 5).
+        //
+        // Both npx shapes are unusable here and for different reasons.
+        // `npx -y <pkg>@<version> mcp-server` is what `docs/mcp-server.md:97`
+        // documents and what the pin rationale at `docs/mcp-server.md:82` argues
+        // for, but the step's own verify requires the literal `npx -y` to be
+        // ABSENT from this file. Dropping the `-y` to satisfy that makes npx
+        // PROMPT before installing a package that is not present, which in a
+        // non-interactive MCP client start is a hang rather than a prompt.
+        //
+        // The installed binary is what the setup docs lead with
+        // (`docs/setup/mcp-client-config.md:35`,
+        // `docs/getting-started-local-stdio.md:9` — "the turnkey path … one
+        // command"), is non-interactive, and resolves no dist-tag at all
+        // because it IS whatever the consumer installed. Its cost is stated in
+        // the catalog description rather than hidden: it assumes the package is
+        // on PATH.
+        //
+        // RECORDED CONFLICT, per the same council verdict: this step's verify
+        // and the docs' pinned form contradict each other directly — the test
+        // forbids the string the documentation recommends. That is a defect in
+        // one of the two, and it is named here rather than silently normalised.
+        install_hint_stdio: `${_packageName().split('/').pop() ?? 'agent-config'} mcp-server`,
         tools: entries,
     };
 }

package/src/scripts/capture_skill_catalogue.ts

@@ -71,7 +71,7 @@ import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import {
-    DEFAULT_CATALOGUE_ROOTS,
+    PROJECTION_CATALOGUE_ROOT,
     OBSERVATION_LOG,
     analyzeSelector,
     buildHostEventRecord,
@@ -85,8 +85,9 @@ import {
     measureCatalogueVolume,
     parseHostBudgetEvent,
     readObservationLog,
+    readCatalogueAcross,
     readProjectedCatalogue,
-    resolveSkillsRoot,
+    resolveSkillCatalogueRoots,
     type HostProjectionRow,
     type ProjectionMode,
     type ProjectionModeCounts,
@@ -118,13 +119,18 @@ function resolveCatalogueRoot(explicit: string | null): string {
         }
         return explicit;
     }
-    for (const candidate of DEFAULT_CATALOGUE_ROOTS) {
+    // The PROJECTION first, then the authored tree — deliberately NOT the generic
+    // ranker order, and deliberately not `DEFAULT_CATALOGUE_ROOTS`, which became a
+    // label list on 2026-09-07 (its `~/` entry joins to `<repo>/~/.claude/skills`,
+    // a path that can never exist). This module compares what a host DELIVERED
+    // against what was PROJECTED, so the projection is the subject; ranking it
+    // against `src/skills` would answer a different question with the same words.
+    const CANDIDATES = [PROJECTION_CATALOGUE_ROOT, 'src/skills'] as const;
+    for (const candidate of CANDIDATES) {
         const abs = path.join(REPO, candidate);
         if (fs.existsSync(abs)) return abs;
     }
-    throw new Error(
-        `no catalogue root found — tried ${DEFAULT_CATALOGUE_ROOTS.join(', ')} under ${REPO}`,
-    );
+    throw new Error(`no catalogue root found — tried ${CANDIDATES.join(', ')} under ${REPO}`);
 }
 
 function argValue(flag: string): string | null {
@@ -326,17 +332,24 @@ function projectionModeFlagFor(host: string, counts: ProjectionModeCounts): { fl
  */
 function runPointableBareMode(): number {
     const explicitRoot = argValue('--catalogue-root');
-    const rankerRoot = explicitRoot ? resolveCatalogueRoot(explicitRoot) : resolveSkillsRoot(REPO);
-    if (rankerRoot === null) {
+    // The RANKER'S roots, which is what this join claims to read — corrected twice
+    // in one day. It first used `resolveSkillsRoot`; then, on the reasoning that
+    // "the projection is the subject", `.claude/skills` alone. Both were wrong
+    // after the ADR-236 amendment EMPTIED that directory of skills: the join read
+    // 49 command wrappers as the catalogue and published pointableBare 0 against
+    // unpointableBare 16, with the empty-guard silent because 49 is not 0. An
+    // explicit --catalogue-root still means exactly that one tree.
+    const rankerRoots = explicitRoot ? [resolveCatalogueRoot(explicitRoot)] : resolveSkillCatalogueRoots(REPO);
+    if (rankerRoots.length === 0) {
         process.stderr.write(
-            '❌  no catalogue root resolved for the ranker — tried ' +
-                `${DEFAULT_CATALOGUE_ROOTS.join(', ')} under ${REPO}.\n` +
+            `❌  no catalogue root resolved for the ranker under ${REPO}.\n` +
                 '    An empty catalogue is never a clean join: it would report 0 pointable\n' +
                 '    entries because nothing was read, not because nothing diverged.\n',
         );
         return 1;
     }
-    const catalogueNames = readProjectedCatalogue(rankerRoot).map((entry) => entry.name);
+    const rankerRoot = rankerRoots[0] as string;
+    const catalogueNames = readCatalogueAcross(rankerRoots).map((entry) => entry.name);
     // The guard the error text above already promised, and did not have. A
     // present-but-empty or half-generated projection resolves fine — the
     // resolver returns the first EXISTING directory, not the first non-empty