@event4u/agent-config 14.20.0 → 14.22.0

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

package/src/scripts/_lib/carrier_status.ts

@@ -1,118 +0,0 @@
-/**
- * The `status: carrier` predicate, and the reasoning five readers share.
- *
- * A carrier is a roadmap whose job is to hold obligations deferred out of a
- * parent that is already archived. Every item in it has an unmet resumption
- * trigger, and it has no `## Phase` headings, so it is skipped wherever a draft
- * is: the dashboard, `/roadmap:process-*`, the trackability check and the plan
- * risk register. It differs from a draft in what it costs to remove — a draft
- * may be deleted freely, a carrier may not.
- *
- * This module exists because the predicate had two implementations within one
- * change and five callers within one week. Two implementations of one frontmatter
- * test drift, and the one nobody runs locally drifts first — the same
- * memory-twin failure this repository has already recorded against a fixture
- * corpus. One test, one place, and the reasoning above lives beside it rather
- * than being restated in each caller.
- *
- * The read is frontmatter-scoped on purpose. A fenced `status: carrier` inside a
- * roadmap that documents the syntax is not a declaration, and a body-wide match
- * turned exactly that into a hard failure before a review caught it.
- */
-
-/** The frontmatter values that mean "not schedulable work, and not disposable". */
-export const CARRIER_VALUES: ReadonlySet<string> = new Set(['carrier']);
-
-/** The leading `---\n…\n---` block, or null when the text carries none. */
-export function frontmatterBlock(text: string): string | null {
-    const m = /^---\n([\s\S]*?)\n---/.exec(text);
-    return m === null ? null : (m[1] ?? '');
-}
-
-/** True when `text`'s FRONTMATTER declares one of {@link CARRIER_VALUES}. */
-export function declaresCarrier(text: string | null | undefined): boolean {
-    if (text === null || text === undefined) {
-        return false;
-    }
-    const fm = frontmatterBlock(text);
-    if (fm === null) {
-        return false;
-    }
-    const m = /^status:[ \t]*([A-Za-z-]+)[ \t]*$/m.exec(fm);
-    return m !== null && CARRIER_VALUES.has((m[1] ?? '').toLowerCase());
-}
-
-/**
- * Count the top-level roadmaps in `roadmapRoot` that declare themselves carriers.
- *
- * Lives here rather than in the estate gate because it is the same fact as the
- * predicate above, read over a directory instead of a string, and the gate that
- * needs it is already at its source-size ceiling.
- *
- * @param isCandidate the caller's own roadmap-filename test, so this module does
- *        not acquire a second opinion about what counts as a roadmap.
- */
-export function countDeclaredCarriers(
-    roadmapRoot: string,
-    isCandidate: (name: string) => boolean,
-    fsLike: {
-        readdirSync: (p: string) => string[];
-        statSync: (p: string) => { isFile: () => boolean };
-        readFileSync: (p: string, enc: 'utf-8') => string;
-    },
-    join: (...parts: string[]) => string,
-): number {
-    let names: string[];
-    try {
-        names = fsLike.readdirSync(roadmapRoot);
-    } catch {
-        return 0;
-    }
-    let n = 0;
-    for (const name of names) {
-        if (!name.endsWith('.md') || !isCandidate(name)) {
-            continue;
-        }
-        const abs = join(roadmapRoot, name);
-        try {
-            if (!fsLike.statSync(abs).isFile()) {
-                continue;
-            }
-            if (declaresCarrier(fsLike.readFileSync(abs, 'utf-8'))) {
-                n += 1;
-            }
-        } catch {
-            continue;
-        }
-    }
-    return n;
-}
-
-/**
- * Fixture design — why two of the estate self-test cases are shaped as they are.
- *
- * The reasoning behind two of `check_estate_count`'s self-test cases, kept here
- * because the gate that holds them is at its source-size ceiling and because
- * both facts are about the carrier status rather than about that gate.
- *
- * **The deletion case's addition is a DRAFT, and that is the whole design.**
- * A carrier holds obligations lifted out of an already-archived parent, so
- * paying an offset for removing one rewards the loss: the deletion buys nothing
- * and the addition stays unpaid. With an *ordinary* addition the growth half and
- * the unpaid half coincide — growth iff `n > a`, unpaid iff `n > a` — so the
- * case rejected on two independent grounds and stayed red with the carrier
- * branch reverted, asserting nothing about the feature it named. A draft is
- * invisible to `collect()`, so the count half cannot move and only the offset
- * scoring decides.
- *
- * **The count case asserts the flip BACK, not the flip TO.** A reclassification
- * is not a disposal in either direction, but the flip *to* carrier cannot be
- * asserted by exit code: it lowers the count, a count below the floor is a
- * drawdown, and a drawdown is free whichever way carriers are counted. Its
- * consequence is assertable — with carriers uncounted the flip lowers the floor,
- * so flipping the same file back reads as growth and must be paid for. That is
- * the fixture's state, with the carrier already in the base tree, and it rejects
- * with the carrier term removed from the count. The neutrality of the forward
- * flip is asserted directly in `check_estate_count.test.ts`, where a count is
- * readable.
- */

package/src/scripts/_lib/estate_carrier_cases.ts

@@ -1,72 +0,0 @@
-/**
- * The three `check_estate_count` self-test cases that exercise `status: carrier`.
- *
- * They live outside that gate because it sits at the 1,500-line source ceiling
- * `check_source_size_budget` enforces, and because the doctrine that gate states
- * for an oversized file is a split rather than a raised baseline. The reasoning
- * behind the fixture shapes is in `carrier_status.ts` § Fixture design.
- */
-
-import type { SelfTestCase } from './gate_self_test.js';
-
-/** What the caller must supply: its own fixture harness and roadmap bodies. */
-export interface EstateCaseDeps {
-    fixture: (opts: {
-        roadmaps: number;
-        base?: string;
-        before?: (dir: string) => void;
-        after: (dir: string) => void;
-    }) => number;
-    write: (dir: string, rel: string, body: string) => void;
-    remove: (dir: string, rel: string) => void;
-    roadmap: (name: string, extra?: string) => string;
-    CARRIER: string;
-    DRAFT: string;
-}
-
-export function carrierEstateCases(d: EstateCaseDeps): SelfTestCase[] {
-    const { fixture, write, remove, roadmap, CARRIER, DRAFT } = d;
-    return [
-        {
-            name: 'deleting a carrier does not offset a new draft → reject',
-            expect: 'reject',
-            run: () =>
-                fixture({
-                    roadmaps: 3,
-                    base: 'main',
-                    before: (dir) => write(dir, 'agents/roadmaps/road-to-carrier.md', CARRIER),
-                    after: (dir) => {
-                        remove(dir, 'agents/roadmaps/road-to-carrier.md');
-                        write(dir, 'agents/roadmaps/road-to-new.md', DRAFT);
-                    },
-                }),
-        },
-        {
-            // The control that proves the case above tests the STATUS rather
-            // than the deletion: only the removed file's status differs.
-            name: 'deleting an ordinary roadmap still offsets a new draft → accept',
-            expect: 'accept',
-            run: () =>
-                fixture({
-                    roadmaps: 3,
-                    base: 'main',
-                    before: (dir) => write(dir, 'agents/roadmaps/road-to-spare.md', roadmap('S')),
-                    after: (dir) => {
-                        remove(dir, 'agents/roadmaps/road-to-spare.md');
-                        write(dir, 'agents/roadmaps/road-to-new.md', DRAFT);
-                    },
-                }),
-        },
-        {
-            name: 'flipping a carrier back to an ordinary roadmap costs nothing → accept',
-            expect: 'accept',
-            run: () =>
-                fixture({
-                    roadmaps: 3,
-                    base: 'main',
-                    before: (dir) => write(dir, 'agents/roadmaps/road-to-2.md', CARRIER),
-                    after: (dir) => write(dir, 'agents/roadmaps/road-to-2.md', roadmap('R2')),
-                }),
-        },
-    ];
-}

package/src/scripts/hooks/code_graph_nudge_hook.ts

@@ -1,191 +0,0 @@
-#!/usr/bin/env tsx
-/**
- * PreToolUse code-graph nudge (ADR-124 Phase 4) — deterministic, warn-only.
- *
- * When a code-graph source is available and the agent is about to search or
- * read source files, surface a one-line reminder to query the graph first.
- * NEVER blocks (dispatcher contract: 0 allow · 2 warn) — Source G's strict
- * block-the-first-read mode is deliberately NOT ported (blocking reads on a
- * possibly-stale index violates the minimal-safe-diff posture). Once per
- * session (a latch keyed by session id), so it cannot nag.
- *
- * Default-OFF. Fires only when `hooks.code_graph.enabled: true`. Disabled /
- * missing / already-latched → no-op exit 0. fail_closed: false — any error
- * returns allow; a token optimisation must never break a tool call.
- *
- * Branches (first eligible search/read this session):
- *   present + fresh → "query the graph first"
- *   present + stale → "index N commits behind — rebuild"
- *   absent          → "no graph — build one?"
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-import { detectSources, pickSource } from '../code_graph/detect.js';
-import { readHookStdin } from './hook_stdin.js';
-
-const SETTINGS_FILE = '.agent-settings.yml';
-const EXIT_ALLOW = 0;
-const EXIT_WARN = 2;
-const CODE_EXT = /\.(php|ts|tsx|mts|cts|js|jsx|mjs|cjs)$/i;
-
-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);
-}
-
-/** `hooks.code_graph.enabled: true` mini-parser (mirrors rtk_wrap_hook). */
-export function enabled(root: string): boolean {
-    const f = path.join(root, SETTINGS_FILE);
-    let text: string;
-    try {
-        if (!fs.statSync(f).isFile()) return false;
-        text = fs.readFileSync(f, 'utf-8');
-    } catch {
-        return false;
-    }
-    let inHooks = false;
-    let inCg = false;
-    for (const raw of text.split(/\r\n|\r|\n/)) {
-        const line = raw.replace(/\s+$/, '');
-        if (!line || line.replace(/^\s+/, '').startsWith('#')) continue;
-        if (!(line.startsWith(' ') || line.startsWith('\t'))) {
-            inHooks = /^hooks\s*:\s*$/.test(line);
-            inCg = false;
-            continue;
-        }
-        if (inHooks) {
-            if (/^\s+code_graph\s*:\s*$/.test(line)) {
-                inCg = true;
-                continue;
-            }
-            if (inCg && /^\s{0,3}\S/.test(line)) inCg = false;
-        }
-        if (inCg && /^\s+enabled\s*:\s*true\b/.test(line)) return true;
-    }
-    return false;
-}
-
-interface ToolIntent {
-    isSearch: boolean;
-    isCodeRead: boolean;
-}
-
-/** Best-effort read of the intercepted tool + its target from the envelope. */
-export function classifyTool(envelope: JsonObject): ToolIntent {
-    const payload = isObject(envelope['payload']) ? envelope['payload'] : envelope;
-    const nameVal =
-        payload['tool_name'] ?? payload['toolName'] ?? payload['tool'] ?? envelope['tool_name'] ?? envelope['tool'];
-    const name = typeof nameVal === 'string' ? nameVal : '';
-    const ti = (isObject(payload['tool_input']) ? payload['tool_input'] : envelope['tool_input']) as
-        | JsonObject
-        | undefined;
-    const isSearch = name === 'Grep' || name === 'Glob';
-    let isCodeRead = false;
-    if (name === 'Read' && isObject(ti)) {
-        const fp = ti['file_path'] ?? ti['path'];
-        if (typeof fp === 'string') isCodeRead = CODE_EXT.test(fp);
-    }
-    return { isSearch, isCodeRead };
-}
-
-function sessionId(envelope: JsonObject): string {
-    const s = envelope['session_id'] ?? envelope['sessionId'];
-    return typeof s === 'string' && s ? s : 'default';
-}
-
-function latchFile(root: string): string {
-    return path.join(root, 'agents', 'runtime', 'state', 'code-graph-nudge.json');
-}
-function alreadyNudged(root: string, session: string): boolean {
-    try {
-        const state = JSON.parse(fs.readFileSync(latchFile(root), 'utf-8')) as Record<string, boolean>;
-        return state[session] === true;
-    } catch {
-        return false;
-    }
-}
-function latch(root: string, session: string): void {
-    try {
-        const p = latchFile(root);
-        let state: Record<string, boolean> = {};
-        try {
-            state = JSON.parse(fs.readFileSync(p, 'utf-8')) as Record<string, boolean>;
-        } catch {
-            /* fresh */
-        }
-        state[session] = true;
-        fs.mkdirSync(path.dirname(p), { recursive: true });
-        fs.writeFileSync(p, JSON.stringify(state));
-    } catch {
-        /* fail-open: a persistence failure must not break the tool call */
-    }
-}
-
-const NATIVE_CACHE = path.join('agents', 'runtime', 'state', 'code-graph-v1.json');
-
-/** The nudge line for the current source state (≤40 tokens, one line). */
-export function nudgeReason(root: string): string {
-    const verdicts = detectSources(root, path.join(root, NATIVE_CACHE));
-    const picked = pickSource(verdicts);
-    if (!picked) {
-        return 'No code-graph found. For "who calls / where used / impact" run `agent-config code-graph refresh` once, then `agent-config code-graph query <symbol>` instead of grepping blind.';
-    }
-    if (picked.stale) {
-        return `code-graph is ${picked.commits_behind ?? 'N'} commit(s) behind — rebuild with \`agent-config code-graph refresh\` before trusting relationship answers.`;
-    }
-    return 'A fresh code-graph is present — for structure questions run `agent-config code-graph query|affected <symbol>` first; grep is the fallback (say which answered).';
-}
-
-export function main(): number {
-    let envelope: JsonValue;
-    try {
-        const raw = readHookStdin();
-        envelope = raw.trim() ? (JSON.parse(raw) as JsonValue) : {};
-    } catch {
-        return EXIT_ALLOW;
-    }
-    if (!isObject(envelope)) return EXIT_ALLOW;
-
-    const cwd = envelope['cwd'];
-    const pr = envelope['workspace_root'] ?? envelope['project_root'];
-    const root = typeof cwd === 'string' && cwd ? cwd : typeof pr === 'string' && pr ? pr : '.';
-    if (!enabled(root)) return EXIT_ALLOW;
-
-    const { isSearch, isCodeRead } = classifyTool(envelope);
-    if (!isSearch && !isCodeRead) return EXIT_ALLOW;
-
-    const session = sessionId(envelope);
-    if (alreadyNudged(root, session)) return EXIT_ALLOW; // once per session
-
-    let reason: string;
-    try {
-        reason = nudgeReason(root);
-    } catch {
-        return EXIT_ALLOW;
-    }
-    latch(root, session);
-    process.stdout.write(`${JSON.stringify({ decision: 'warn', reason })}\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` (see cmd_migrate.ts).
-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 {
-        return fs.realpathSync(fileURLToPath(import.meta.url)) === fs.realpathSync(path.resolve(process.argv[1]));
-    } catch {
-        return false;
-    }
-}
-if (isCliEntry()) process.exit(main());