@event4u/agent-config 14.12.0 → 14.14.0

package/src/scripts/skill_tools/score_skill_relevance.ts

@@ -50,7 +50,25 @@ const _HERE = fileURLToPath(import.meta.url);
 // src/scripts/skill_tools/score_skill_relevance.ts → parents[3] of the .py
 // (skill_tools → scripts → src → repo root) is the package root.
 export const ROOT = path.resolve(path.dirname(_HERE), '..', '..', '..');
-export const DEFAULT_SKILLS_DIR = path.join(ROOT, '.agent-src.uncondensed', 'skills');
+/**
+ * The skills root, resolved the way the two real consumers already resolve it.
+ *
+ * `road-to-inbox-harvest-2026-08-f-skill-selection-evidence` 1.1. This used to be
+ * a hardcoded path to a directory that no longer exists, and the failure was
+ * SILENT: `--task "review a pull request"` printed `(no relevant skills found)`
+ * and exited 0, which is indistinguishable from a task that genuinely matches
+ * nothing. A ranker that reports an empty catalogue as an empty result is worse
+ * than one that crashes.
+ *
+ * `resolveSkillsRoot` is the shared resolver the `skill-route` concern and the
+ * `suggest_skill_for_task` MCP handler use — deliberately shared, because two
+ * resolvers over one catalogue is how a ranker and the tool that exposes it
+ * 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';
+
+export const DEFAULT_SKILLS_DIR: string | null = resolveSkillsRoot(ROOT);
 
 /** Mirror Python len(str) — count Unicode code points, not UTF-16 units. */
 function pyLen(s: string): number {
@@ -364,7 +382,8 @@ const PROG = 'score_skill_relevance.py';
 
 interface Args {
     task: string;
-    skills_dir: string;
+    /** `null` when no catalogue root exists — a DIFFERENT answer from an empty ranking. */
+    skills_dir: string | null;
     top: number;
     json: boolean;
     sample: boolean;
@@ -433,13 +452,75 @@ export const _SAMPLE = {
     task: 'build a livewire component for the user dashboard with reactive state',
 };
 
+/**
+ * Why this catalogue root cannot be ranked, or `null` when it can.
+ *
+ * `road-to-inbox-harvest-2026-08-f-skill-selection-evidence` 1.2. Three states,
+ * and the middle one is the one that actually bit: a root that does not exist, a
+ * root that exists and is EMPTY, and a readable root. `.claude/skills` is a
+ * gitignored projection, so a fresh worktree has the second — and the ranker
+ * reported it as "no relevant skills found", exit 0, on a task that scores 47
+ * against `src/skills`.
+ *
+ * An empty directory is not a missing directory, and neither is an empty result.
+ */
+function catalogueDeficit(dir: string | null): string | null {
+    if (dir === null) {
+        return `no catalogue root resolved — tried ${DEFAULT_CATALOGUE_ROOTS.join(', ')} under ${ROOT}`;
+    }
+    try {
+        if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) {
+            return `${dir} is not a directory`;
+        }
+        if (fs.readdirSync(dir).length === 0) {
+            return `${dir} exists and is EMPTY — an empty catalogue, not an empty result`;
+        }
+    } catch (e) {
+        return `${dir} could not be read: ${e instanceof Error ? e.message : String(e)}`;
+    }
+    return null;
+}
+
 export function main(argv: string[] | null = null): number {
     const args = parse_args(argv ?? process.argv.slice(2));
     const task = args.sample ? _SAMPLE.task : args.task;
     if (!task) {
         _argError('--task is required (or pass --sample)');
     }
-    const rows = rank(task, args.skills_dir);
+    // 1.2 — "no matches" and "no catalogue" are DIFFERENT answers and now have
+    // different exit codes. `missing-skill-recovery` already draws that line for
+    // the MCP tool (`status: no_catalogue`); the CLI did not, and an agent
+    // reading `(no relevant skills found)` from an unreachable catalogue
+    // concludes "no skill covers this" — the exact wrong conclusion that rule
+    // exists to prevent.
+    // The check covers an EXPLICIT --skills-dir too, not only the default. An
+    // 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);
+    if (unreadable !== null) {
+        if (args.json) {
+            process.stdout.write(
+                pyJsonDumpsIndent2({
+                    task,
+                    status: 'no_catalogue',
+                    reason: unreadable,
+                    ...(args.skills_dir === null ? { tried: [...DEFAULT_CATALOGUE_ROOTS] } : { skills_dir: args.skills_dir }),
+                }),
+            );
+            process.stdout.write('\n');
+        } else {
+            process.stderr.write(
+                `(no skills catalogue read — ${unreadable})\n` +
+                    'This is NOT "no skill matches": nothing was read, so no conclusion about ' +
+                    'skill coverage follows from it.\n',
+            );
+        }
+        return 3;
+    }
+    // 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);
     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

@@ -29,6 +29,9 @@ import * as fs from 'node:fs';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 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';
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -211,7 +214,11 @@ function _parseInt(raw: string): number {
 export function parse_args(argv: string[]): Args {
     const args: Args = {
         task: '',
-        skills_dir: DEFAULT_SKILLS_DIR,
+        // `?? ''` is deliberately NOT used here: an empty string re-creates
+        // exactly the silent-empty-catalogue defect that repointing
+        // 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,
         personas_dir: DEFAULT_PERSONAS,
         top: 3,
         json: false,

package/src/scripts/skill_usage_report.ts

@@ -24,6 +24,7 @@ import { assertScanned, DeadScopeError } from './_lib/scan_scope.js';
 // tier-usage re-tier already ships. Imported rather than restated so the sink
 // section and the re-tier decision cannot drift to two different numbers.
 import { DEFAULT_TIER_USAGE_RETIER } from '../agent-src/templates/scripts/telemetry/settings.js';
+import { generatedByQuote } from './_lib/generated_by.js';
 
 const _HERE = path.dirname(fileURLToPath(import.meta.url));
 // parent.parent.parent of the .py file (src/scripts/skill_usage_report.py)
@@ -469,7 +470,7 @@ export function render(
     const lines: string[] = [
         '# Skill Usage Report (baseline)',
         '',
-        '> Generated by `src/scripts/skill_usage_report.ts`. Source:',
+        generatedByQuote('skill_usage_report', 'Source:'),
         '> `agents/runtime/metrics/skill-usage.jsonl` (collector emits per-turn',
         '> exposure/mention records). See',
         '> [`step-2-skill-inventory-rationalization.md`](../roadmaps/step-2-skill-inventory-rationalization.md)',

package/src/scripts/stubs_due.ts

@@ -0,0 +1,211 @@
+#!/usr/bin/env tsx
+/**
+ * `stubs:due` — what in the parked estate is waiting, and on whom.
+ *
+ * `road-to-inbox-harvest-2026-08-f-owner-decision-queue` Phase 2. The estate is
+ * not short of plans; it was short of a front door. 76 stubs sit under
+ * `agents/roadmaps/stubs/`, the progress dashboard excludes that directory ON
+ * PURPOSE, and before this command nothing ever re-read them: exactly one of the
+ * 76 carried a next-read date.
+ *
+ * ── What it does NOT do, and this is the load-bearing part ───────────────────
+ * It is READ-ONLY and it authors nothing inside `agents/roadmaps/stubs/`. The AI
+ * council of 2026-08-21 deleted the hand-maintained index that used to live in
+ * `stubs/README.md`, because an authored append surface conflicted in every open
+ * PR and drifted stale within a day of its own repair;
+ * `check_no_stub_inventory_table` refuses its return.
+ *
+ * That verdict settled *an inventory of the directory living inside the
+ * directory's own README*. This is a frontmatter field plus a query: the stub
+ * files stay the single source, no row is authored twice, and there is no append
+ * surface to conflict on. Different mechanism, so the lock does not apply —
+ * recorded here rather than left for a later reader to re-derive.
+ *
+ * ── Three buckets, because they are three different problems ─────────────────
+ * · OVERDUE — `review_by:` has passed. Late; re-read it.
+ * · NO PROBE — carries `probe: none`. Not late: it has no finish line at all,
+ *   which is an abandonment wearing a directory name.
+ * · OWNER — the text routes a decision to the owner. Not late and not
+ *   abandoned: it is waiting on a person, and no amount of re-reading moves it.
+ *
+ * Collapsing them into one count would tell a reader to re-read a file that
+ * needs a decision, and to decide about a file that needs a probe.
+ *
+ * Exit codes: 0 always on the report path (this is a QUERY, not a gate) ·
+ * 2 usage / unreadable corpus.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+
+/** Where the parked estate lives. */
+export const STUB_DIR = 'agents/roadmaps/stubs';
+
+/**
+ * Phrases that mean "a person has to decide this".
+ *
+ * A literal list, never a heuristic: a general "looks like a decision" match
+ * would flag every stub that mentions the word, and a query that over-reports is
+ * a query nobody runs twice. Each entry is a phrase this repository's own stubs
+ * and roadmaps actually use.
+ */
+const OWNER_ROUTING = [
+    'owner-reserved',
+    'owner reserved',
+    'owner: maintainer',
+    'reserved to the owner',
+    'requires owner',
+    'maintainer decision',
+    'owner decision',
+    'owner sign-off',
+    'awaiting the owner',
+];
+
+export interface StubRecord {
+    /** Repo-relative path. */
+    file: string;
+    /** Parsed `review_by:`, or `null` when absent or unparseable. */
+    reviewBy: string | null;
+    /** True when the file declares `probe: none`. */
+    probeNone: boolean;
+    /** The owner-routing phrase that matched, or `null`. */
+    ownerPhrase: string | null;
+}
+
+/** Read one stub's fields. Frontmatter only — the body is scanned separately. */
+export function readStub(root: string, rel: string): StubRecord {
+    const source = fs.readFileSync(path.join(root, rel), 'utf-8');
+    const fm = /^---\n([\s\S]*?)\n---\n/.exec(source);
+    const front = fm?.[1] ?? '';
+    const dateMatch = /^review_by:\s*(\d{4}-\d{2}-\d{2})\s*$/m.exec(front);
+    const lower = source.toLowerCase();
+    const phrase = OWNER_ROUTING.find((p) => lower.includes(p)) ?? null;
+    return {
+        file: rel,
+        reviewBy: dateMatch?.[1] ?? null,
+        probeNone: /^probe:\s*none\s*$/m.test(front),
+        ownerPhrase: phrase,
+    };
+}
+
+/** Every stub file, sorted. `README.md` is the contract, not a stub. */
+export function listStubs(root: string): string[] {
+    const dir = path.join(root, STUB_DIR);
+    let entries: string[];
+    try {
+        entries = fs.readdirSync(dir);
+    } catch {
+        return [];
+    }
+    return entries
+        .filter((n) => n.endsWith('.md') && n !== 'README.md')
+        .map((n) => `${STUB_DIR}/${n}`)
+        .sort();
+}
+
+export interface DueReport {
+    total: number;
+    /** `review_by:` in the past, or absent — both mean nobody scheduled a read. */
+    overdue: readonly StubRecord[];
+    /** `probe: none` — no finish line, which is not the same as late. */
+    noProbe: readonly StubRecord[];
+    /** Text routes a decision to a person. */
+    owner: readonly StubRecord[];
+}
+
+/**
+ * Classify the corpus against a date.
+ *
+ * `today` is a parameter rather than read from the clock, because a query whose
+ * output depends on an unstated `Date.now()` cannot be tested and cannot be
+ * quoted in a commit. The CLI passes the real date; a test passes a fixed one.
+ */
+export function report(root: string, today: string): DueReport {
+    const records = listStubs(root).map((rel) => readStub(root, rel));
+    return {
+        total: records.length,
+        // An ABSENT date counts as overdue, deliberately. The field is required
+        // by the contract, so a missing one means the file predates the contract
+        // or somebody skipped it — either way nobody has scheduled a read, which
+        // is the state this query exists to surface.
+        overdue: records.filter((r) => r.reviewBy === null || r.reviewBy <= today),
+        noProbe: records.filter((r) => r.probeNone),
+        owner: records.filter((r) => r.ownerPhrase !== null),
+    };
+}
+
+function render(r: DueReport, today: string, write: (s: string) => void): void {
+    write(`stubs:due — ${String(r.total)} stub(s) under ${STUB_DIR}, as of ${today}\n\n`);
+
+    const section = (label: string, rows: readonly StubRecord[], detail: (s: StubRecord) => string): void => {
+        write(`${label}: ${String(rows.length)}\n`);
+        for (const s of rows) write(`  ${s.file}  ${detail(s)}\n`);
+        if (rows.length > 0) write('\n');
+    };
+
+    section('OVERDUE — review_by has passed or is absent', r.overdue, (s) =>
+        s.reviewBy === null ? '(no review_by — nobody scheduled a read)' : `review_by ${s.reviewBy}`,
+    );
+    section('NO PROBE — declares `probe: none`; no finish line, not merely late', r.noProbe, () => '');
+    section('OWNER — the text routes a decision to a person', r.owner, (s) => `matched "${s.ownerPhrase ?? ''}"`);
+
+    write(
+        'This is a QUERY and exits 0 whatever it finds. It writes nothing and authors\n' +
+            `no file under ${STUB_DIR} — see the header for why that boundary matters.\n`,
+    );
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    if (argv.includes('-h') || argv.includes('--help')) {
+        process.stdout.write(
+            'usage: stubs_due [--root DIR] [--today YYYY-MM-DD] [--json] [--counts]\n' +
+                '  --today   classify against this date instead of the system clock\n' +
+                '  --counts  print only the two dashboard integers\n',
+        );
+        return 0;
+    }
+    const rootIdx = argv.indexOf('--root');
+    const rootArg = rootIdx >= 0 ? argv[rootIdx + 1] : undefined;
+    const root = rootArg === undefined ? REPO_ROOT : path.resolve(rootArg);
+    const todayIdx = argv.indexOf('--today');
+    const todayArg = todayIdx >= 0 ? argv[todayIdx + 1] : undefined;
+    const today = todayArg ?? new Date().toISOString().slice(0, 10);
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(today)) {
+        process.stderr.write(`stubs_due: --today must be YYYY-MM-DD, got "${today}"\n`);
+        return 2;
+    }
+
+    const r = report(root, today);
+    if (r.total === 0) {
+        process.stderr.write(
+            `stubs_due: found no stub under ${root}/${STUB_DIR} — the root moved, or this is not the repository root\n`,
+        );
+        return 2;
+    }
+    if (argv.includes('--json')) {
+        process.stdout.write(`${JSON.stringify({ today, ...r }, null, 2)}\n`);
+        return 0;
+    }
+    if (argv.includes('--counts')) {
+        // The two integers Phase 2.3 puts on the dashboard. Two integers are not
+        // an inventory: no row, no link, nothing to conflict on.
+        process.stdout.write(`${String(r.overdue.length)} ${String(r.owner.length)}\n`);
+        return 0;
+    }
+    render(r, today, (s) => void process.stdout.write(s));
+    return 0;
+}
+
+/* c8 ignore start */
+function isCliEntry(): boolean {
+    if (process.argv[1] === undefined) return false;
+    return pathToFileURL(path.resolve(process.argv[1])).href === pathToFileURL(_HERE).href;
+}
+if (isCliEntry()) {
+    process.exit(main());
+}
+/* c8 ignore stop */