@event4u/agent-config 14.21.0 → 14.22.0

package/src/scripts/report_skill_menu_census.ts

@@ -0,0 +1,341 @@
+#!/usr/bin/env tsx
+/**
+ * Every shipped skill, and the entry paths that can reach it.
+ *
+ * `road-to-skill-menu-economy` step 1.1. The roadmap's lever is COUNT ON THE
+ * MENU — the description corpus already sits at the schema cap, so there is no
+ * byte-shaving budget to spend (K2). Deciding which skills may leave the model
+ * menu needs to know, per skill, whether anything other than the menu can
+ * reach it. This report answers that mechanically and publishes the rule it
+ * used, so a later reader can disagree with the rule rather than with a number.
+ *
+ * WHAT IT IS NOT
+ * --------------
+ * It is a REPORT, deliberately: no threshold, no exit code that carries a
+ * verdict, and a `report_` prefix so `_lib/gate_population.ts` classifies it
+ * out of the gate population rather than by whoever last edited a manifest.
+ *
+ * It also does NOT decide "sole entry path", and that limit is load-bearing
+ * rather than an apology. A command reference proves a command CAN reach the
+ * skill; it cannot prove the menu never does. The roadmap's own Risk 1 is
+ * precisely this — marking a skill `user-invocable: false` is correct only if
+ * the command or flow path really is the only one — so this report produces
+ * the evidence for that judgement and never the judgement.
+ *
+ * THE CLASSIFICATION RULE, stated because it is the whole content
+ * -------------------------------------------------------------
+ * For each `src/skills/<name>/SKILL.md`, three signals are read:
+ *
+ *   command_refs  files under `src/domains/**\/command.md` that reference the
+ *                 skill in one of three DISAMBIGUATING shapes — `skill:<name>`,
+ *                 a `skills/<name>` path, or the bare name in backticks. A
+ *                 plain word-boundary match is deliberately NOT used: skill
+ *                 names like `security`, `database` and `docker` are ordinary
+ *                 English and would hit on every prose mention.
+ *   flow_refs     files under `src/flows/` whose own `skills:` list names it.
+ *                 Flows carry YAML name lists rather than the shapes above, so
+ *                 the command regex read 0 for all 299 on the first pass — a
+ *                 false zero, and the reason `flowSkillNames` exists.
+ *   menu_present  true unless the frontmatter carries `user-invocable: false`
+ *                 or `disable-model-invocation: true` — the two menu-economy
+ *                 keys the roadmap measures as nearly unused.
+ *
+ * and the row is classified:
+ *
+ *   both          command_refs > 0 AND flow_refs > 0
+ *   command-only  command_refs > 0, flow_refs = 0
+ *   flow-only     flow_refs > 0, command_refs = 0
+ *   model-routed  neither, and the skill is on the menu — the menu is then the
+ *                 only entry path this repository can point at
+ *   orphan        neither, and the skill is off the menu: nothing in the tree
+ *                 reaches it. Reported, never deleted (K3).
+ *
+ * `command-only` and `flow-only` name a CANDIDATE for `user-invocable: false`,
+ * never a decision — see the sole-entry limit above.
+ *
+ * Usage:
+ *     ./scripts-run src/scripts/report_skill_menu_census                # stdout summary
+ *     ./scripts-run src/scripts/report_skill_menu_census --emit         # write the artifact
+ *     ./scripts-run src/scripts/report_skill_menu_census --emit --pin <sha>
+ *
+ * Deterministic: rows sort by skill name, no timestamp is written, and the pin
+ * is an argument rather than "now", so a re-run at the same pin over the same
+ * tree is byte-identical.
+ */
+
+import { execFileSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+export const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+export const ARTIFACT_REL = path.join('agents', 'evidence', 'analysis', 'skill-menu-census-2026-09.md');
+
+export type EntryPath = 'both' | 'command-only' | 'flow-only' | 'model-routed' | 'orphan';
+
+export interface SkillRow {
+    readonly name: string;
+    readonly commandRefs: number;
+    readonly flowRefs: number;
+    readonly menuPresent: boolean;
+    readonly hasTriggerCorpus: boolean;
+    readonly entryPath: EntryPath;
+    /** One command or flow file, for an operator to start from. Empty when none. */
+    readonly firstRef: string;
+}
+
+/** Escape a skill name for use inside a RegExp. Names are kebab-case, so this is cheap insurance. */
+function escapeRe(s: string): string {
+    return s.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+}
+
+/**
+ * The three disambiguating reference shapes, as one regex.
+ *
+ * A bare word-boundary match was tried first and rejected on inspection: 299
+ * skill names include `security`, `database`, `docker`, `performance` and
+ * `mode`, each of which appears in ordinary command prose. A reference that
+ * cannot be told from a sentence is not evidence of an entry path.
+ */
+export function referenceRe(skill: string): RegExp {
+    const n = escapeRe(skill);
+    const tick = String.fromCharCode(96);
+    return new RegExp(
+        'skill:\\s*' + n + '(?![a-z0-9-])' +
+            '|skills/' + n + '(?:[/\\s' + tick + ')\\]]|$)' +
+            '|' + tick + n + tick,
+        'u',
+    );
+}
+
+/** Every file under `dir` matching `pred`, sorted, as repo-relative paths. */
+export function walk(root: string, dir: string, pred: (rel: string) => boolean): string[] {
+    const out: string[] = [];
+    const abs = path.join(root, dir);
+    if (!fs.existsSync(abs)) return out;
+    const stack: string[] = [dir];
+    while (stack.length > 0) {
+        const cur = stack.pop() as string;
+        let entries: fs.Dirent[];
+        try {
+            entries = fs.readdirSync(path.join(root, cur), { withFileTypes: true });
+        } catch {
+            continue;
+        }
+        for (const e of entries) {
+            const rel = path.join(cur, e.name);
+            if (e.isDirectory()) stack.push(rel);
+            else if (e.isFile() && pred(rel)) out.push(rel);
+        }
+    }
+    return out.sort();
+}
+
+/** Frontmatter values this report needs. Hand-parsed: only two boolean keys matter. */
+export function menuFlags(text: string): { userInvocable: boolean | null; disableModel: boolean | null } {
+    const head = text.slice(0, 4000);
+    const ui = /^user-invocable:\s*(true|false)\s*$/mu.exec(head);
+    const dm = /^disable-model-invocation:\s*(true|false)\s*$/mu.exec(head);
+    return {
+        userInvocable: ui === null ? null : ui[1] === 'true',
+        disableModel: dm === null ? null : dm[1] === 'true',
+    };
+}
+
+/**
+ * The skill names a flow file declares, from its own `skills:` lists.
+ *
+ * Flows do NOT use the three reference shapes commands use — they carry YAML
+ * lists of bare names (`skills: [code-review, adversarial-review]`, or a block
+ * sequence). Running the command-shaped regex over them returned flow_refs = 0
+ * for all 299 skills on the first pass, which was a false zero and is why this
+ * parser exists rather than a wider word-boundary match: a bare name is safe
+ * HERE precisely because the `skills:` key bounds where it may be read.
+ */
+export function flowSkillNames(text: string): Set<string> {
+    const out = new Set<string>();
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] as string;
+        const inline = /^\s*skills:\s*\[([^\]]*)\]\s*$/u.exec(line);
+        if (inline !== null) {
+            for (const raw of (inline[1] as string).split(',')) {
+                const n = raw.trim().replace(/^['"]|['"]$/gu, '');
+                if (n !== '') out.add(n);
+            }
+            continue;
+        }
+        if (!/^\s*skills:\s*$/u.test(line)) continue;
+        const indent = (/^\s*/u.exec(line) as RegExpExecArray)[0].length;
+        for (let j = i + 1; j < lines.length; j += 1) {
+            const item = /^(\s*)-\s*(\S.*?)\s*$/u.exec(lines[j] as string);
+            if (item === null || (item[1] as string).length <= indent) break;
+            out.add((item[2] as string).replace(/^['"]|['"]$/gu, ''));
+        }
+    }
+    return out;
+}
+
+export function classify(commandRefs: number, flowRefs: number, menuPresent: boolean): EntryPath {
+    if (commandRefs > 0 && flowRefs > 0) return 'both';
+    if (commandRefs > 0) return 'command-only';
+    if (flowRefs > 0) return 'flow-only';
+    return menuPresent ? 'model-routed' : 'orphan';
+}
+
+export function census(root: string): SkillRow[] {
+    const skillsDir = path.join(root, 'src', 'skills');
+    const names = fs
+        .readdirSync(skillsDir, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && fs.existsSync(path.join(skillsDir, e.name, 'SKILL.md')))
+        .map((e) => e.name)
+        .sort();
+
+    const commandFiles = walk(root, path.join('src', 'domains'), (rel) => path.basename(rel) === 'command.md');
+    const flowFiles = walk(root, path.join('src', 'flows'), () => true);
+    const commandText = commandFiles.map((rel) => [rel, fs.readFileSync(path.join(root, rel), 'utf-8')] as const);
+    const flowDecl = flowFiles.map(
+        (rel) => [rel, flowSkillNames(fs.readFileSync(path.join(root, rel), 'utf-8'))] as const,
+    );
+
+    const rows: SkillRow[] = [];
+    for (const name of names) {
+        const skillMd = path.join(skillsDir, name, 'SKILL.md');
+        const text = fs.readFileSync(skillMd, 'utf-8');
+        const flags = menuFlags(text);
+        const menuPresent = flags.userInvocable !== false && flags.disableModel !== true;
+        const re = referenceRe(name);
+        const cmdHits = commandText.filter(([, t]) => re.test(t)).map(([rel]) => rel);
+        const flowHits = flowDecl.filter(([, names]) => names.has(name)).map(([rel]) => rel);
+        rows.push({
+            name,
+            commandRefs: cmdHits.length,
+            flowRefs: flowHits.length,
+            menuPresent,
+            hasTriggerCorpus: fs.existsSync(path.join(skillsDir, name, 'evals', 'triggers.json')),
+            entryPath: classify(cmdHits.length, flowHits.length, menuPresent),
+            firstRef: cmdHits[0] ?? flowHits[0] ?? '',
+        });
+    }
+    return rows;
+}
+
+export function tally(rows: readonly SkillRow[]): Record<EntryPath, number> {
+    const t: Record<EntryPath, number> = {
+        both: 0,
+        'command-only': 0,
+        'flow-only': 0,
+        'model-routed': 0,
+        orphan: 0,
+    };
+    for (const r of rows) t[r.entryPath] += 1;
+    return t;
+}
+
+export function renderArtifact(rows: readonly SkillRow[], pin: string): string {
+    const t = tally(rows);
+    const candidates = t['command-only'] + t['flow-only'];
+    const L: string[] = [];
+    L.push('<!-- evidence-type: analysis -->');
+    L.push('# Skill menu census — every skill, and what can reach it');
+    L.push('');
+    L.push(`Pinned to commit \`${pin}\`. Generated by \`./scripts-run src/scripts/report_skill_menu_census --emit --pin ${pin}\`;`);
+    L.push('re-running it at the same pin over the same tree is byte-identical, which is what');
+    L.push('`road-to-skill-menu-economy` step 1.1 asks to be checkable.');
+    L.push('');
+    L.push('## The rule this census applied');
+    L.push('');
+    L.push('**Commands.** A `src/domains/**/command.md` file counts as reaching a skill when it');
+    L.push('references it in one of three disambiguating shapes — `skill:<name>`, a `skills/<name>`');
+    L.push('path, or the bare name in backticks. A plain word-boundary match is NOT used: names');
+    L.push('like `security`, `database` and `docker` are ordinary English and would hit on every');
+    L.push('prose mention. The `skill:<name>` shape is closed with a negative lookahead rather');
+    L.push('than a word boundary: `\\b` sits between `w` and `-`, so `skill:code-review-lens` was a');
+    L.push('hit for `code-review` and a skill would have inherited a longer sibling\'s references.');
+    L.push('Tightening it moved no figure in this corpus, which is recorded rather than assumed.');
+    L.push('');
+    L.push('**Flows.** A `src/flows/*.yaml` file counts when its own `skills:` list names the skill.');
+    L.push('Flows carry YAML name lists rather than the shapes above, so applying the command regex');
+    L.push('to them returned `flow_refs = 0` for all 299 skills on the first pass. That was a false');
+    L.push('zero, corrected before publication; a bare name is safe here precisely because the');
+    L.push('`skills:` key bounds where it may be read.');
+    L.push('');
+    L.push('**Menu.** `menu_present` is true unless the frontmatter carries `user-invocable: false`');
+    L.push('or `disable-model-invocation: true`.');
+    L.push('');
+    L.push('| Class | Meaning |');
+    L.push('|---|---|');
+    L.push('| `both` | reachable from a command AND from a flow |');
+    L.push('| `command-only` | a command references it; no flow does |');
+    L.push('| `flow-only` | a flow references it; no command does |');
+    L.push('| `model-routed` | neither, and it is on the menu — the menu is the only entry path this tree can point at |');
+    L.push('| `orphan` | neither, and it is off the menu: nothing here reaches it |');
+    L.push('');
+    L.push('## What this census does NOT establish');
+    L.push('');
+    L.push('It does not decide **sole entry path**. A command reference proves a command CAN');
+    L.push('reach the skill; nothing here proves the menu never does. `command-only` and');
+    L.push('`flow-only` are therefore CANDIDATES for `user-invocable: false` and never the');
+    L.push('marking decision — the roadmap\'s Risk 1 is exactly this misclassification, and its');
+    L.push('stated mitigation is a successful command invocation per marked skill, which is a');
+    L.push('step 1.2 obligation and not something a static scan can discharge.');
+    L.push('');
+    L.push('An `orphan` row is a question, not a deletion list (K3).');
+    L.push('');
+    L.push('## Totals');
+    L.push('');
+    L.push('| Class | Count |');
+    L.push('|---|---:|');
+    for (const k of ['both', 'command-only', 'flow-only', 'model-routed', 'orphan'] as EntryPath[]) {
+        L.push(`| \`${k}\` | ${String(t[k])} |`);
+    }
+    L.push(`| **total** | **${String(rows.length)}** |`);
+    L.push('');
+    L.push(`Menu-removal candidates (\`command-only\` + \`flow-only\`): **${String(candidates)}**.`);
+    L.push('');
+    L.push('## Rows');
+    L.push('');
+    L.push('| Skill | Entry path | cmd refs | flow refs | on menu | triggers.json | first reference |');
+    L.push('|---|---|---:|---:|:-:|:-:|---|');
+    for (const r of rows) {
+        L.push(
+            `| \`${r.name}\` | \`${r.entryPath}\` | ${String(r.commandRefs)} | ${String(r.flowRefs)} | ` +
+                `${r.menuPresent ? 'yes' : 'no'} | ${r.hasTriggerCorpus ? 'yes' : 'no'} | ` +
+                `${r.firstRef === '' ? '—' : `\`${r.firstRef}\``} |`,
+        );
+    }
+    L.push('');
+    return L.join('\n');
+}
+
+function headSha(root: string): string {
+    return execFileSync('git', ['-C', root, 'rev-parse', 'HEAD'], { encoding: 'utf-8' }).trim();
+}
+
+export function main(argv: readonly string[]): number {
+    const root = REPO_ROOT;
+    const emit = argv.includes('--emit');
+    const pinIdx = argv.indexOf('--pin');
+    const pin = pinIdx !== -1 && pinIdx + 1 < argv.length ? (argv[pinIdx + 1] as string) : headSha(root);
+    const rows = census(root);
+    const t = tally(rows);
+    if (emit) {
+        const out = path.join(root, ARTIFACT_REL);
+        fs.mkdirSync(path.dirname(out), { recursive: true });
+        fs.writeFileSync(out, renderArtifact(rows, pin), 'utf-8');
+        process.stdout.write(`wrote ${ARTIFACT_REL} · ${String(rows.length)} row(s) · pin ${pin}\n`);
+    }
+    process.stdout.write(`scanned: ${String(rows.length)} skill(s)\n`);
+    for (const k of ['both', 'command-only', 'flow-only', 'model-routed', 'orphan'] as EntryPath[]) {
+        process.stdout.write(`  ${k.padEnd(14)} ${String(t[k]).padStart(4)}\n`);
+    }
+    process.stdout.write(
+        `  menu-removal candidates (command-only + flow-only): ${String(t['command-only'] + t['flow-only'])}\n`,
+    );
+    return 0;
+}
+
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/skill_tools/score_skill_relevance.ts

@@ -66,9 +66,16 @@ export const ROOT = path.resolve(path.dirname(_HERE), '..', '..', '..');
  * start ranking different trees. `null` when no candidate root exists, and the
  * CLI turns that into a distinct exit code rather than an empty list.
  */
-import { DEFAULT_CATALOGUE_ROOTS, resolveSkillsRoot } from '../_lib/skill_catalogue.js';
+import { DEFAULT_CATALOGUE_ROOTS, resolveSkillCatalogueRoots } from '../_lib/skill_catalogue.js';
 
-export const DEFAULT_SKILLS_DIR: string | null = resolveSkillsRoot(ROOT);
+/**
+ * Every readable catalogue root, in precedence order — possibly empty.
+ *
+ * The default the CLI and the hook rank across. `DEFAULT_SKILLS_DIR` below is
+ * the first of them and stays exported for the surfaces that name one directory.
+ */
+export const DEFAULT_SKILLS_ROOTS: readonly string[] = resolveSkillCatalogueRoots(ROOT);
+export const DEFAULT_SKILLS_DIR: string | null = DEFAULT_SKILLS_ROOTS[0] ?? null;
 
 /** Mirror Python len(str) — count Unicode code points, not UTF-16 units. */
 function pyLen(s: string): number {
@@ -164,6 +171,27 @@ export interface Skill {
     triggerText: string[];
 }
 
+/**
+ * Load one root, or several with the FIRST occurrence of a name winning.
+ *
+ * Precedence by name, never by root: every root is read, and a collision
+ * resolves to the earliest root that carries it — `resolveSkillCatalogueRoots`
+ * owns what that order means. Reading only the first root is the defect this
+ * replaced; silently ranking one name twice would be the next one.
+ */
+function _load_skills_across(roots: readonly string[]): Skill[] {
+    const out: Skill[] = [];
+    const seen = new Set<string>();
+    for (const root of roots) {
+        for (const s of _load_skills(root)) {
+            if (seen.has(s.name)) continue;
+            seen.add(s.name);
+            out.push(s);
+        }
+    }
+    return out;
+}
+
 function _load_skills(skillsDir: string): Skill[] {
     const skills: Skill[] = [];
     for (const skillMd of _globSkillMd(skillsDir)) {
@@ -246,9 +274,16 @@ function _score(taskTerms: Set<string>, skill: Skill, opts: RankOptions = {}): n
 
 export type RankRow = [string, number, string[]];
 
-export function rank(task: string, skillsDir: string, opts: RankOptions = {}): RankRow[] {
+/**
+ * @param skillsDir one root, or several to rank across (see `_load_skills_across`).
+ */
+export function rank(
+    task: string,
+    skillsDir: string | readonly string[],
+    opts: RankOptions = {},
+): RankRow[] {
     const taskTerms = _tokenize(task);
-    const skills = _load_skills(skillsDir);
+    const skills = _load_skills_across(typeof skillsDir === 'string' ? [skillsDir] : skillsDir);
     const rows: RankRow[] = [];
     for (const s of skills) {
         const score = _score(taskTerms, s, opts);
@@ -384,6 +419,15 @@ interface Args {
     task: string;
     /** `null` when no catalogue root exists — a DIFFERENT answer from an empty ranking. */
     skills_dir: string | null;
+    /**
+     * Did the operator NAME the directory?
+     *
+     * An explicit `--skills-dir` means one root and only that root: an operator
+     * pointing at a tree is asking about that tree, and quietly unioning the
+     * host catalogue into their answer would make the flag mean something else.
+     * Absent, the default ranks across every readable root.
+     */
+    skills_dir_explicit: boolean;
     top: number;
     json: boolean;
     sample: boolean;
@@ -407,6 +451,7 @@ export function parse_args(argv: string[]): Args {
     const args: Args = {
         task: '',
         skills_dir: DEFAULT_SKILLS_DIR,
+        skills_dir_explicit: false,
         top: 0,
         json: false,
         sample: false,
@@ -431,8 +476,10 @@ export function parse_args(argv: string[]): Args {
                 _argError('argument --skills-dir: expected one argument');
             }
             args.skills_dir = v;
+            args.skills_dir_explicit = true;
         } else if (a.startsWith('--skills-dir=')) {
             args.skills_dir = a.slice('--skills-dir='.length);
+            args.skills_dir_explicit = true;
         } else if (a === '--top') {
             const v = argv[++i];
             if (v === undefined) {
@@ -497,7 +544,24 @@ export function main(argv: string[] | null = null): number {
     // operator who passes a wrong path is in exactly the position the silent
     // failure was about, and answering them with "(no relevant skills found)"
     // is the same wrong answer with a different cause.
-    const unreadable = catalogueDeficit(args.skills_dir);
+    // One root when the operator named it; otherwise every readable root, so the
+    // ranking covers what the session can actually reach.
+    const roots: readonly string[] = args.skills_dir_explicit
+        ? args.skills_dir === null
+            ? []
+            : [args.skills_dir]
+        : DEFAULT_SKILLS_ROOTS;
+    // An EXPLICIT directory is always deficit-checked, even when it resolved to a
+    // one-element list: a wrong path must not degrade to "(no relevant skills
+    // found)", which is the silent failure the check exists for and which the
+    // first draft of this branch reintroduced. For the DEFAULT, the deficit is
+    // "not one readable root anywhere" — a single empty candidate is no longer a
+    // deficit, because the others may still carry the catalogue.
+    const unreadable = args.skills_dir_explicit
+        ? catalogueDeficit(args.skills_dir)
+        : roots.length === 0
+          ? catalogueDeficit(null)
+          : null;
     if (unreadable !== null) {
         if (args.json) {
             process.stdout.write(
@@ -520,7 +584,7 @@ export function main(argv: string[] | null = null): number {
     }
     // Non-null past the deficit check above, which returns before this line
     // whenever the root cannot be ranked.
-    const rows = rank(task, args.skills_dir as string);
+    const rows = rank(task, roots);
     if (args.json) {
         const sliced = args.top ? rows.slice(0, args.top) : rows;
         const payload = sliced.map(([n, s, p]) => ({ name: n, score: s, personas: p }));

package/src/scripts/skill_tools/suggest_skill_for_task.ts

@@ -32,7 +32,7 @@ import { audit, type PersonaRow } from './audit_persona_coverage.js';
 /** Sentinel for "no catalogue root resolved" — never a readable path. */
 const NO_CATALOGUE = '<no-skills-catalogue>';
 
-import { DEFAULT_SKILLS_DIR, rank } from './score_skill_relevance.js';
+import { DEFAULT_SKILLS_DIR, DEFAULT_SKILLS_ROOTS, rank } from './score_skill_relevance.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/skill_tools/suggest_skill_for_task.ts → parents[3] of the .py
@@ -78,13 +78,27 @@ export interface Combo {
     why: string;
 }
 
+/**
+ * @param skillsDir the root the PERSONA audit reads — one directory by necessity.
+ * @param rankRoots roots to RANK across; defaults to `[skillsDir]`.
+ *
+ * The two parameters are separate because the two questions are. Ranking wants
+ * every catalogue the session can reach (`resolveSkillCatalogueRoots`); the
+ * persona-coverage audit walks one tree and pairs it with one persona directory.
+ * Collapsing them was the state a neutral review found on 2026-09-07: the MCP
+ * handler ranked the union while this CLI ranked the first root, so a consumer
+ * carrying its own project skills got a different answer from each — exactly the
+ * two-resolvers-over-one-catalogue split the resolver's docstring warns about,
+ * reproduced by the change that claimed to fix it.
+ */
 export function suggest(
     task: string,
     skillsDir: string,
     personasDir: string,
     top = 3,
+    rankRoots: readonly string[] = [skillsDir],
 ): Combo[] {
-    const ranked = rank(task, skillsDir).slice(0, top);
+    const ranked = rank(task, rankRoots).slice(0, top);
     const personaRows = audit(skillsDir, personasDir);
     const status = _persona_status(personaRows);
     return ranked.map(([name, score, personas]) => ({
@@ -193,6 +207,8 @@ const PROG = 'suggest_skill_for_task.py';
 interface Args {
     task: string;
     skills_dir: string;
+    /** Did the operator NAME the directory? One tree then, and only that tree. */
+    skills_dir_explicit: boolean;
     personas_dir: string;
     top: number;
     json: boolean;
@@ -219,6 +235,7 @@ export function parse_args(argv: string[]): Args {
         // DEFAULT_SKILLS_DIR removed. When no catalogue resolves, this reads
         // as the literal marker below and the caller's own check reports it.
         skills_dir: DEFAULT_SKILLS_DIR ?? NO_CATALOGUE,
+        skills_dir_explicit: false,
         personas_dir: DEFAULT_PERSONAS,
         top: 3,
         json: false,
@@ -244,8 +261,10 @@ export function parse_args(argv: string[]): Args {
                 _argError('argument --skills-dir: expected one argument');
             }
             args.skills_dir = v;
+            args.skills_dir_explicit = true;
         } else if (a.startsWith('--skills-dir=')) {
             args.skills_dir = a.slice('--skills-dir='.length);
+            args.skills_dir_explicit = true;
         } else if (a === '--personas-dir') {
             const v = argv[++i];
             if (v === undefined) {
@@ -279,7 +298,22 @@ export function main(argv: string[] | null = null): number {
     if (!task) {
         _argError('--task is required (or pass --sample)');
     }
-    const combos = suggest(task, args.skills_dir, args.personas_dir, args.top);
+    // Rank across every readable root; audit personas against the first. An
+    // explicit --skills-dir names one tree and is honoured as one tree.
+    //
+    // Keyed on the FLAG, not on value-equality against the default. Corrected
+    // after a second neutral review: comparing paths meant
+    // `--skills-dir <the resolved default>` silently ranked the union including
+    // `~/.claude/skills`, so the comment above was false for exactly the operator
+    // who spelled the default out. And when no catalogue resolves at all,
+    // `skills_dir` is the `NO_CATALOGUE` sentinel while `DEFAULT_SKILLS_DIR` is
+    // null, so the old comparison was false there too — the branch was dead in
+    // the state it was written for.
+    const rankRoots =
+        !args.skills_dir_explicit && DEFAULT_SKILLS_ROOTS.length > 0
+            ? DEFAULT_SKILLS_ROOTS
+            : [args.skills_dir];
+    const combos = suggest(task, args.skills_dir, args.personas_dir, args.top, rankRoots);
     if (args.json) {
         process.stdout.write(pyJsonDumpsIndent2({ task, suggestions: combos }));
         process.stdout.write('\n');

package/src/vendor/grammars/README.md

@@ -0,0 +1,61 @@
+# Vendored tree-sitter grammars
+
+Compiled WebAssembly grammars for the native code-graph engine
+(`src/scripts/code_graph/`). They are vendored — carried in this repository and
+published inside the npm tarball — so that a consumer who runs
+`npm install @event4u/agent-config` can build a code graph on the next command
+with no manual parser install (ADR-259).
+
+## Why vendored rather than a dependency
+
+`tree-sitter-wasms` carries 36 grammars (49 MiB on disk). Depending on it at
+runtime would hand every consumer all 36, which is the option ADR-259 §
+Alternatives rejects on exactly that measurement. Only the three grammars below
+are loadable by the engine — `GRAMMAR_WASM` in `src/scripts/code_graph/types.ts`
+has three entries — so the other 33 would be payload with no reader.
+
+**No grammar is ever fetched at runtime** (Kill register K1). These files are in
+the tarball; the loader reads them from disk.
+
+## The set
+
+| Language | File | SHA-256 |
+|---|---|---|
+| php | `tree-sitter-php.wasm` | `55bb617b6f01e14bab997861f0b20a2420cf6ba3199ffeb295b9ec398966d8a3` |
+| typescript (also serves `.tsx`) | `tree-sitter-typescript.wasm` | `8515404dceed38e1ed86aa34b09fcf3379fff1b4ff9dd3967bcd6d1eb5ac3d8f` |
+| javascript | `tree-sitter-javascript.wasm` | `63812b9e275d26851264734868d27a1656bd44a2ef6eb3e85e6b03728c595ab5` |
+
+All three are built against **grammar ABI 14** (`EXPECTED_GRAMMAR_ABI` in
+`src/scripts/code_graph/types.ts`). The loader asserts the ABI on every load, so
+a drifted grammar fails loudly rather than parsing wrongly.
+
+## Provenance
+
+Copied byte-for-byte from `tree-sitter-wasms@0.1.13`
+(<https://github.com/Gregoor/tree-sitter-wasms>, Unlicense), which compiles them
+from the upstream `tree-sitter/tree-sitter-{php,typescript,javascript}` grammars
+(MIT). The compiled artifacts are derivatives of the MIT grammar sources, so
+they are annotated MIT in `REUSE.toml` and credited in `CREDITS.md`.
+
+`tree-sitter-wasms` remains a **devDependency**: it is the source these copies
+are refreshed from, and the ABI smoke test in `tests/scripts/code_graph.test.ts`
+runs against it. It is deliberately not a runtime dependency.
+
+## Refreshing
+
+The pair is ABI-coupled and must move together:
+
+```bash
+npm i -D web-tree-sitter@<v> tree-sitter-wasms@<v>
+for g in php typescript javascript; do
+  cp node_modules/tree-sitter-wasms/out/tree-sitter-$g.wasm src/vendor/grammars/
+done
+shasum -a 256 src/vendor/grammars/*.wasm   # update the table above
+```
+
+Then update, in the same change:
+
+- the three `BINARY_PAYLOAD_EXCEPTIONS` entries in `src/scripts/check_pack_size.ts`
+  (they are path-and-size-bound, so any size change invalidates them by design);
+- `EXPECTED_GRAMMAR_ABI` in `src/scripts/code_graph/types.ts` if the ABI moved;
+- the install-size line in `MIGRATION.md`.