@event4u/agent-config 10.2.0 → 10.4.0

package/src/scripts/lint_rule_skill_pack_reach.ts

@@ -51,19 +51,40 @@
  * findings under `--strict` · 2 usage or IO error. A scan that walked no rules
  * exits 2 rather than green — a gate that scanned nothing must never read as a
  * pass.
+ *
+ * `--self-test` proves those rejections still fire in the binary a contributor
+ * runs, not merely in the imported functions `tests/scripts/pack_reach.test.ts`
+ * exercises. `--root <dir>` exists for it: the three inputs are ordinary tree
+ * reads, so a temporary fixture repo can reproduce every verdict, which is why
+ * this gate adopts the harness rather than claiming the exemption.
  */
 
 import * as fs from 'node:fs';
+import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { parse as parseYaml } from 'yaml';
 
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 const REPO = path.resolve(path.dirname(_HERE), '..', '..');
-const RULES_DIR = path.join(REPO, 'src', 'rules');
-const SKILLS_DIR = path.join(REPO, 'src', 'skills');
-const PACKS_FILE = path.join(REPO, 'src', 'config', 'discovery', 'packs.yml');
+
+interface Roots {
+    rulesDir: string;
+    skillsDir: string;
+    packsFile: string;
+}
+
+/** The three inputs, resolved against `root` so a fixture tree can stand in. */
+function rootsFor(root: string): Roots {
+    return {
+        rulesDir: path.join(root, 'src', 'rules'),
+        skillsDir: path.join(root, 'src', 'skills'),
+        packsFile: path.join(root, 'src', 'config', 'discovery', 'packs.yml'),
+    };
+}
 
 export interface PackDef {
     id: string;
@@ -212,10 +233,165 @@ export function analyze(
     return findings;
 }
 
-function main(): number {
-    const packs = readPacks(PACKS_FILE);
-    const rules = readRules(RULES_DIR);
-    const skillPacks = readSkillPacks(SKILLS_DIR);
+interface Args {
+    quiet: boolean;
+    strict: boolean;
+    selfTest: boolean;
+    root: string;
+}
+
+function _parseArgs(argv: readonly string[]): Args {
+    const args: Args = { quiet: false, strict: false, selfTest: false, root: REPO };
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--quiet') args.quiet = true;
+        else if (a === '--strict') args.strict = true;
+        else if (a === '--self-test') args.selfTest = true;
+        else if (a === '--root') {
+            // Never fall back to the real repo. A self-test whose root argument
+            // went missing would otherwise scan the live tree instead of its
+            // fixture and could still exit 0 — a green run proving nothing,
+            // which is the exact failure `_lib/gate_self_test.ts` exists for.
+            const value = argv[i + 1];
+            if (value === undefined || value.startsWith('--')) {
+                throw new Error('--root requires a directory argument');
+            }
+            args.root = value;
+            i += 1;
+        }
+    }
+    return args;
+}
+
+/**
+ * Build a fixture tree. `packsYml` is written verbatim; each rule and skill is
+ * a minimal frontmatter block, which is all `readRules` / `readSkillPacks`
+ * ever look at.
+ */
+function _fixture(
+    tmp: string,
+    name: string,
+    packsYml: string,
+    rules: ReadonlyArray<{ name: string; packs?: string[]; routes: string[] }>,
+    skills: ReadonlyArray<{ name: string; packs?: string[] }>,
+): string {
+    const root = path.join(tmp, name);
+    const { rulesDir, skillsDir, packsFile } = rootsFor(root);
+    fs.mkdirSync(rulesDir, { recursive: true });
+    fs.mkdirSync(skillsDir, { recursive: true });
+    fs.mkdirSync(path.dirname(packsFile), { recursive: true });
+    fs.writeFileSync(packsFile, packsYml, 'utf-8');
+    const list = (key: string, values?: string[]): string =>
+        values === undefined ? '' : `${key}: [${values.join(', ')}]\n`;
+    for (const rule of rules) {
+        fs.writeFileSync(
+            path.join(rulesDir, `${rule.name}.md`),
+            `---\n${list('packs', rule.packs)}${list('routes_to', rule.routes)}---\n\n# ${rule.name}\n`,
+            'utf-8',
+        );
+    }
+    for (const skill of skills) {
+        fs.mkdirSync(path.join(skillsDir, skill.name), { recursive: true });
+        fs.writeFileSync(
+            path.join(skillsDir, skill.name, 'SKILL.md'),
+            `---\n${list('packs', skill.packs)}---\n\n# ${skill.name}\n`,
+            'utf-8',
+        );
+    }
+    return root;
+}
+
+function _selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'lrspr-selftest-'));
+    const runRaw = (args: readonly string[]): number =>
+        runGateCli(REPO, 'src/scripts/lint_rule_skill_pack_reach.ts', args, REPO);
+    const run = (root: string, extra: readonly string[] = []): number =>
+        runRaw(['--root', root, '--quiet', ...extra]);
+
+    // `alpha` stands alone; `beta` pulls `alpha` in transitively.
+    const PACKS = '- id: alpha\n- id: beta\n  requires: [alpha]\n- id: gamma\n';
+
+    try {
+        const unreachable = _fixture(
+            tmp,
+            'unreachable',
+            PACKS,
+            [{ name: 'r', packs: ['gamma'], routes: ['skill:s'] }],
+            [{ name: 's', packs: ['alpha'] }],
+        );
+        const viaRequires = _fixture(
+            tmp,
+            'via-requires',
+            PACKS,
+            [{ name: 'r', packs: ['beta'], routes: ['skill:s'] }],
+            [{ name: 's', packs: ['alpha'] }],
+        );
+        const unscopedRule = _fixture(
+            tmp,
+            'unscoped-rule',
+            PACKS,
+            [{ name: 'r', routes: ['skill:s'] }],
+            [{ name: 's', packs: ['alpha'] }],
+        );
+        const unscopedSkill = _fixture(
+            tmp,
+            'unscoped-skill',
+            PACKS,
+            [{ name: 'r', packs: ['gamma'], routes: ['skill:s'] }],
+            [{ name: 's' }],
+        );
+        const empty = _fixture(tmp, 'empty', PACKS, [], [{ name: 's', packs: ['alpha'] }]);
+
+        return runSelfTest({
+            gate: 'lint_rule_skill_pack_reach',
+            minCases: 6,
+            minRejectCases: 3,
+            cases: [
+                {
+                    name: 'a rule routing into a pack its own closure never reaches is rejected under --strict',
+                    expect: 'reject',
+                    run: () => run(unreachable, ['--strict']),
+                },
+                {
+                    name: 'an empty rule corpus refuses to report a pass',
+                    expect: 'reject',
+                    run: () => run(empty, ['--strict']),
+                },
+                {
+                    name: 'the same route passes when `requires` pulls the skill pack in transitively',
+                    expect: 'accept',
+                    run: () => run(viaRequires, ['--strict']),
+                },
+                {
+                    name: 'an unscoped rule ships everywhere, so its route is always reachable',
+                    expect: 'accept',
+                    run: () => run(unscopedRule, ['--strict']),
+                },
+                {
+                    name: 'an unscoped skill ships everywhere, so no route into it can be unreachable',
+                    expect: 'accept',
+                    run: () => run(unscopedSkill, ['--strict']),
+                },
+                {
+                    name: '--root with no value is refused rather than silently scanning the real tree',
+                    expect: 'reject',
+                    run: () => runRaw(['--quiet', '--root']),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const args = _parseArgs(argv);
+    if (args.selfTest) return _selfTest();
+
+    const { rulesDir, skillsDir, packsFile } = rootsFor(args.root);
+    const packs = readPacks(packsFile);
+    const rules = readRules(rulesDir);
+    const skillPacks = readSkillPacks(skillsDir);
 
     if (rules.length === 0 || skillPacks.size === 0 || packs.size === 0) {
         process.stderr.write(
@@ -231,8 +407,7 @@ function main(): number {
     // --quiet suppresses the per-finding lines but never the count line: this
     // gate is expected to stay non-empty for a while, and a quiet run that
     // printed nothing at all would read as clean.
-    const quiet = process.argv.includes('--quiet');
-    if (!quiet) {
+    if (!args.quiet) {
         for (const finding of errors) {
             process.stdout.write(`❌  ${finding.subject} — ${finding.detail}\n`);
         }
@@ -241,16 +416,22 @@ function main(): number {
         }
     }
 
-    const strict = process.argv.includes('--strict');
+    // Two lines on purpose. `check_gate_coverage`'s SCANNED_RE is
+    // `/^\s*scanned:\s*(\d+)\s*$/m` — the count must END the line — so the
+    // detailed breakdown below can never satisfy it. This gate was registered
+    // `enforced` with `min_scanned: 90` and had therefore reported `null` since
+    // 924cad87f: an enforced floor that no output could ever meet. Emit the
+    // machine-readable contract line first, then the human breakdown.
+    process.stdout.write(`scanned: ${rules.length}\n`);
     process.stdout.write(
-        `scanned: ${rules.length} rule(s), ${skillPacks.size} skill(s), ${packs.size} pack(s) — ${errors.length} unreachable-route, ${advisories.length} unrouted-skill\n`,
+        `${rules.length} rule(s), ${skillPacks.size} skill(s), ${packs.size} pack(s) — ${errors.length} unreachable-route, ${advisories.length} unrouted-skill\n`,
     );
-    if (errors.length > 0 && !strict) {
+    if (errors.length > 0 && !args.strict) {
         process.stdout.write(
             `advisory run: ${errors.length} unreachable-route finding(s) reported, exit 0. Promote with --strict once the set is empty.\n`,
         );
     }
-    return strict && errors.length > 0 ? 1 : 0;
+    return args.strict && errors.length > 0 ? 1 : 0;
 }
 
 if (process.argv[1] && path.resolve(process.argv[1]) === path.resolve(_HERE)) {

package/src/scripts/lint_skill_router_head.ts

@@ -0,0 +1,254 @@
+#!/usr/bin/env tsx
+/**
+ * Router-head gate — makes the published K6 cap true for NEW skills.
+ *
+ * `src/agent-src/templates/skill.md` has carried "K6: Under 400 lines" as a
+ * checklist item since long before this gate. A checklist item is a statement
+ * of intent that nothing checks; four skills exceed it today. This gate turns
+ * the existing contract into an enforced one, without re-litigating the number.
+ *
+ * The rule: a SKILL.md over MAX_HEAD_LINES must be a router head — an entry
+ * file (when-to-use, mode table, routing) plus per-mode bodies in `tasks/` or
+ * `references/` inside the skill folder. Over the cap with neither directory
+ * present is a monolith and fails.
+ *
+ * WHAT THIS GATE DOES NOT CLAIM. It is not an activation or token argument.
+ * The host loads SKILL.md whole on trigger, and whether it then follows a
+ * pointer into `tasks/` is host behaviour nothing in this tree observes — so
+ * "splitting saves tokens on trigger" is unmeasurable here and is not asserted.
+ * ADR-202's lesson binds: an activation claim goes behind a measured instrument
+ * or it is not made. The defensible claim is narrower and sufficient: the cap
+ * was already the repo's position, and now a new skill cannot quietly ignore it.
+ *
+ * GRANDFATHERING is a shrink-only ratchet. GRANDFATHERED below is seeded with
+ * the measured offender set. Entries may be REMOVED when a skill is
+ * restructured or drops under the cap; adding one is the move this gate exists
+ * to prevent, and the diff makes any addition visible in review. The list is an
+ * inline constant rather than a JSON baseline on purpose — a baseline file
+ * grows without anyone reading it, and this one should be read every time.
+ *
+ * Usage:
+ *     ./scripts-run src/scripts/lint_skill_router_head
+ *     ./scripts-run src/scripts/lint_skill_router_head --quiet
+ *
+ * Exit codes: 0 = clean · 2 = any finding OR usage error.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { assertWatchlistResolves, DeadScopeError } from './_lib/scan_scope.js';
+
+const _FILE = fileURLToPath(import.meta.url);
+const _HERE = path.dirname(_FILE);
+const REPO = path.resolve(_HERE, '..', '..');
+const SKILLS_REL = 'src/skills';
+
+/** The K6 cap, in lines. Mirrors src/agent-src/templates/skill.md § K6. */
+export const MAX_HEAD_LINES = 400;
+
+/** Directories a router head may route into. `references/` is the established
+ *  convention (9 skills use it today); `tasks/` is permitted by the contract
+ *  for per-mode procedure bodies. */
+export const MODE_BODY_DIRS: readonly string[] = ['tasks', 'references'];
+
+/**
+ * Shrink-only allowlist — skills already over the cap when the gate landed.
+ * Measured, not guessed. REMOVE entries as skills are restructured; never add.
+ */
+export const GRANDFATHERED: readonly string[] = [
+    'ai-council',          // 1055
+    'skill-writing',       //  767
+    'roadmap-management',  //  552
+    'quality-tools',       //  445
+];
+
+export interface Finding {
+    readonly skill: string;
+    readonly lines: number;
+    readonly message: string;
+}
+
+/** Count lines the way `wc -l` does, so the gate and a shell check agree. */
+export function countLines(text: string): number {
+    if (text.length === 0) return 0;
+    const n = text.split('\n').length;
+    return text.endsWith('\n') ? n - 1 : n;
+}
+
+/** Does this skill folder carry at least one mode-body directory? */
+export function hasModeBodies(skillDir: string, dirs: readonly string[] = MODE_BODY_DIRS): boolean {
+    return dirs.some((d) => {
+        try {
+            return fs.statSync(path.join(skillDir, d)).isDirectory();
+        } catch {
+            return false;
+        }
+    });
+}
+
+export interface SkillHead {
+    readonly name: string;
+    readonly lines: number;
+    readonly hasBodies: boolean;
+}
+
+/** Read every `<skillsRoot>/<name>/SKILL.md`. */
+export function collectSkillHeads(skillsRoot: string): SkillHead[] {
+    let entries: fs.Dirent[];
+    try {
+        entries = fs.readdirSync(skillsRoot, { withFileTypes: true });
+    } catch {
+        return [];
+    }
+    const heads: SkillHead[] = [];
+    for (const e of entries) {
+        if (!e.isDirectory()) continue;
+        const dir = path.join(skillsRoot, e.name);
+        const head = path.join(dir, 'SKILL.md');
+        let text: string;
+        try {
+            text = fs.readFileSync(head, 'utf-8');
+        } catch {
+            continue;
+        }
+        heads.push({ name: e.name, lines: countLines(text), hasBodies: hasModeBodies(dir) });
+    }
+    return heads.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * A head fails when it is over the cap, carries no mode-body directory, and is
+ * not grandfathered. Two separate results are reported so the caller can
+ * distinguish a live violation from allowlist drift.
+ */
+export function evaluate(
+    heads: readonly SkillHead[],
+    grandfathered: readonly string[] = GRANDFATHERED,
+    max: number = MAX_HEAD_LINES,
+): { readonly findings: Finding[]; readonly staleAllowlist: string[] } {
+    const allow = new Set(grandfathered);
+    const findings: Finding[] = [];
+    const stillOver = new Set<string>();
+
+    for (const h of heads) {
+        if (h.lines <= max) continue;
+        stillOver.add(h.name);
+        if (allow.has(h.name)) continue;
+        if (h.hasBodies) continue;
+        findings.push({
+            skill: h.name,
+            lines: h.lines,
+            message:
+                `SKILL.md is ${h.lines} lines (cap ${max}) with no ${MODE_BODY_DIRS.map((d) => `${d}/`).join(' or ')} ` +
+                'directory — over the cap a skill restructures as a router head (entry head + one file per mode), ' +
+                'per templates/skill.md § The router-head contract. The allowlist is shrink-only and does not accept new entries.',
+        });
+    }
+
+    // An allowlist entry for a skill that no longer exceeds the cap (or no
+    // longer exists) is the ratchet failing to tighten: the entry silently
+    // buys nothing and would re-permit a regression. Reported, not fatal —
+    // removing it is a one-line follow-up, not a reason to red the build.
+    const staleAllowlist = grandfathered.filter((g) => !stillOver.has(g));
+
+    return { findings, staleAllowlist };
+}
+
+// ─── CLI ─────────────────────────────────────────────────────────────────────
+
+class ExitCode extends Error {
+    readonly code: number;
+    constructor(code: number) {
+        super(`exit ${code}`);
+        this.code = code;
+    }
+}
+
+function parseArgs(argv: string[]): { readonly quiet: boolean } {
+    let quiet = false;
+    for (const a of argv) {
+        if (a === '--quiet') {
+            quiet = true;
+        } else if (a === '-h' || a === '--help') {
+            process.stdout.write('usage: lint_skill_router_head [--quiet]\n');
+            throw new ExitCode(0);
+        } else {
+            process.stderr.write(`❌  lint_skill_router_head: unrecognized argument: ${a}\n`);
+            throw new ExitCode(2);
+        }
+    }
+    return { quiet };
+}
+
+export function main(argv: string[] = process.argv.slice(2)): number {
+    const args = parseArgs(argv);
+
+    // The scanned root is the scope signal. A moved or renamed src/skills would
+    // otherwise produce zero heads and a clean green over nothing at all.
+    try {
+        assertWatchlistResolves({
+            gate: 'lint_skill_router_head',
+            candidates: [`${SKILLS_REL}/skill-writing/SKILL.md`],
+            repoRoot: REPO,
+        });
+    } catch (exc) {
+        if (exc instanceof DeadScopeError) {
+            process.stderr.write(`❌  ${exc.message}\n`);
+            return 2;
+        }
+        throw exc;
+    }
+
+    const heads = collectSkillHeads(path.join(REPO, SKILLS_REL));
+    const { findings, staleAllowlist } = evaluate(heads);
+
+    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`,
+        );
+    }
+
+    if (findings.length > 0) {
+        for (const f of findings) {
+            process.stderr.write(`❌  ${SKILLS_REL}/${f.skill}/SKILL.md: ${f.message}\n`);
+        }
+        process.stderr.write(`❌  lint_skill_router_head: ${findings.length} finding(s)\n`);
+        return 2;
+    }
+
+    if (!args.quiet) {
+        const over = heads.filter((h) => h.lines > MAX_HEAD_LINES).length;
+        process.stdout.write(
+            `✅  lint_skill_router_head: ${heads.length} skill head(s) scanned · ` +
+            `${over} over the ${MAX_HEAD_LINES}-line cap, all grandfathered or routed · ` +
+            `allowlist holds ${GRANDFATHERED.length} entry(ies), shrink-only\n`,
+        );
+    }
+    return 0;
+}
+
+/** Robust "am I the entry script?" — realpath-compares argv[1] to this file. */
+function _isCliEntry(): boolean {
+    const a = process.argv[1];
+    if (!a) return false;
+    if (a === _FILE || pathToFileURL(path.resolve(a)).href === import.meta.url) return true;
+    try {
+        return fs.realpathSync(a) === fs.realpathSync(_FILE);
+    } catch {
+        return false;
+    }
+}
+if (_isCliEntry()) {
+    try {
+        process.exit(main());
+    } catch (exc) {
+        if (exc instanceof ExitCode) {
+            process.exit(exc.code);
+        }
+        throw exc;
+    }
+}
+
+export { REPO, SKILLS_REL, ExitCode };