@event4u/agent-config 10.1.0 → 10.3.0

package/src/scripts/lint_settings_classes.ts

@@ -15,7 +15,9 @@
  *   4. every B row's template default is a conservative value
  *      (`false` / `""` / `0` / `[]` / `null` / `{}`) — the invariant that makes
  *      "absent" and "declined" the same outcome in a sparse settings file;
- *   5. the contract's own Counts table matches the tallies computed here.
+ *   5. the contract's own Counts table matches the tallies computed here;
+ *   6. every `REMOVED_KEYS` entry names what decides instead, and no key is
+ *      both removed and live in the template.
  *
  * **Landed at error, not advisory.** The authoring guideline's advisory-first
  * rule exists so a gate cannot be wired to error over a corpus whose hits are
@@ -48,16 +50,24 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 import { load as parseYaml } from 'js-yaml';
 
 import {
+    dispositionOf,
     getSettingsLeaf,
     isConservativeDefault,
     isSettingsClass,
+    isSettingsDisposition,
     parseDeclaredClassCounts,
+    parseDeclaredDispositionCounts,
     parseSettingsClassRows,
+    replacementOf,
     SETTINGS_CLASSES,
+    SETTINGS_DISPOSITIONS,
     type SettingsClass,
     type SettingsClassRow,
+    type SettingsDisposition,
     settingsLeafPaths,
 } from '../shared/settingsClasses.js';
+import { REMOVED_KEYS } from './_lib/agent_settings.js';
+import { checkRatchet } from './_lib/gate_baseline.js';
 import { GateLedger } from './_lib/gate_ledger.js';
 import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
 import { DeadScopeError, reportScanned } from './_lib/scan_scope.js';
@@ -117,15 +127,27 @@ export function selfTest(): number {
         `\n## Counts\n\n| Class | Keys |\n|---|---|\n| A — preference | ${String(a)} |\n` +
         `| B — consent | ${String(b)} |\n| C — guarded | ${String(c)} |\n` +
         `| **Total** | **${String(total)}** |\n`;
-    const table = (rows: string): string => `# Fixture\n${counts(0, 1, 1, 2)}\n## The table\n\n| Key | Class | Default | Why |\n|---|---|---|---|\n${rows}`;
+    // The disposition tallies, in the section the parser scopes to. Defaulted to
+    // the clean fixture's shape so a case that does not care about them says so
+    // by omission rather than by restating four rows.
+    const dispositions = (d: number, u: number, co: number, p: number, total: number): string =>
+        `\n## Dispositions\n\n| Disposition | Keys |\n|---|---|\n| derivable | ${String(d)} |\n` +
+        `| un-inferrable | ${String(u)} |\n| consent | ${String(co)} |\n| policy | ${String(p)} |\n` +
+        `| **Total** | **${String(total)}** |\n`;
+    const table = (rows: string, disp = dispositions(0, 1, 1, 0, 2)): string =>
+        `# Fixture\n${counts(0, 1, 1, 2)}\n${disp}\n## The table\n\n` +
+        `| Key | Class | Default | Why | Disposition |\n|---|---|---|---|---|\n${rows}`;
 
-    const clean = table('| `alpha.one` | B | `false` | fixture |\n| `beta` | C | `"keep"` | fixture |\n');
+    const clean = table(
+        '| `alpha.one` | B | `false` | fixture | consent |\n' +
+            '| `beta` | C | `"keep"` | fixture | un-inferrable |\n',
+    );
 
     try {
         return runSelfTest({
             gate: GATE,
-            minCases: 6,
-            minRejectCases: 5,
+            minCases: 12,
+            minRejectCases: 10,
             cases: [
                 {
                     name: 'a template whose every leaf is classified passes',
@@ -140,7 +162,7 @@ export function selfTest(): number {
                             seed(
                                 'unclassified',
                                 template,
-                                table('| `beta` | C | `"keep"` | fixture |\n') + counts(0, 0, 1, 1),
+                                table('| `beta` | C | `"keep"` | fixture | un-inferrable |\n') + counts(0, 0, 1, 1),
                             ),
                         ),
                 },
@@ -153,8 +175,9 @@ export function selfTest(): number {
                                 'stale-row',
                                 template,
                                 table(
-                                    '| `alpha.one` | B | `false` | fixture |\n| `beta` | C | `"keep"` | fixture |\n' +
-                                        '| `gamma.gone` | A | `1` | fixture |\n',
+                                    '| `alpha.one` | B | `false` | fixture | consent |\n' +
+                                        '| `beta` | C | `"keep"` | fixture | un-inferrable |\n' +
+                                        '| `gamma.gone` | A | `1` | fixture | policy |\n',
                                 ),
                             ),
                         ),
@@ -167,7 +190,90 @@ export function selfTest(): number {
                             seed(
                                 'bad-class',
                                 template,
-                                table('| `alpha.one` | D | `false` | fixture |\n| `beta` | C | `"keep"` | fixture |\n'),
+                                table(
+                                    '| `alpha.one` | D | `false` | fixture | consent |\n' +
+                                        '| `beta` | C | `"keep"` | fixture | un-inferrable |\n',
+                                ),
+                            ),
+                        ),
+                },
+                {
+                    name: 'a leaf with a class but no disposition is rejected',
+                    expect: 'reject',
+                    run: () =>
+                        run(
+                            seed(
+                                'no-disposition',
+                                template,
+                                table(
+                                    '| `alpha.one` | B | `false` | fixture | consent |\n' +
+                                        '| `beta` | C | `"keep"` | fixture |\n',
+                                    dispositions(0, 0, 1, 0, 2),
+                                ),
+                            ),
+                        ),
+                },
+                {
+                    name: 'a disposition outside the closed vocabulary is rejected',
+                    expect: 'reject',
+                    run: () =>
+                        run(
+                            seed(
+                                'bad-disposition',
+                                template,
+                                table(
+                                    '| `alpha.one` | B | `false` | fixture | consent |\n' +
+                                        '| `beta` | C | `"keep"` | fixture | obsolete |\n',
+                                    dispositions(0, 0, 1, 0, 2),
+                                ),
+                            ),
+                        ),
+                },
+                {
+                    name: 'a `derivable` row that names no replacement is rejected — the clause IS the falsifier',
+                    expect: 'reject',
+                    run: () =>
+                        run(
+                            seed(
+                                'derivable-without-replacement',
+                                template,
+                                table(
+                                    '| `alpha.one` | B | `false` | fixture | consent |\n' +
+                                        '| `beta` | C | `"keep"` | fixture | derivable |\n',
+                                    dispositions(1, 0, 1, 0, 2),
+                                ),
+                            ),
+                        ),
+                },
+                {
+                    name: 'a `derivable` row that names its replacement passes',
+                    expect: 'accept',
+                    run: () =>
+                        run(
+                            seed(
+                                'derivable-with-replacement',
+                                template,
+                                table(
+                                    '| `alpha.one` | B | `false` | fixture | consent |\n' +
+                                        '| `beta` | C | `"keep"` | fixture | derivable — the probe reads it |\n',
+                                    dispositions(1, 0, 1, 0, 2),
+                                ),
+                            ),
+                        ),
+                },
+                {
+                    name: 'a Dispositions table that disagrees with the rows is rejected',
+                    expect: 'reject',
+                    run: () =>
+                        run(
+                            seed(
+                                'bad-disposition-counts',
+                                template,
+                                table(
+                                    '| `alpha.one` | B | `false` | fixture | consent |\n' +
+                                        '| `beta` | C | `"keep"` | fixture | un-inferrable |\n',
+                                    dispositions(7, 7, 7, 7, 28),
+                                ),
                             ),
                         ),
                 },
@@ -191,8 +297,10 @@ export function selfTest(): number {
                             seed(
                                 'bad-counts',
                                 template,
-                                `# Fixture\n${counts(9, 9, 9, 27)}\n## The table\n\n| Key | Class | Default | Why |\n|---|---|---|---|\n` +
-                                    '| `alpha.one` | B | `false` | fixture |\n| `beta` | C | `"keep"` | fixture |\n',
+                                `# Fixture\n${counts(9, 9, 9, 27)}\n${dispositions(0, 1, 1, 0, 2)}\n` +
+                                    '## The table\n\n| Key | Class | Default | Why | Disposition |\n|---|---|---|---|---|\n' +
+                                    '| `alpha.one` | B | `false` | fixture | consent |\n' +
+                                    '| `beta` | C | `"keep"` | fixture | un-inferrable |\n',
                             ),
                         ),
                 },
@@ -201,6 +309,29 @@ export function selfTest(): number {
                     expect: 'reject',
                     run: () => run(seed('dead-root', null, clean)),
                 },
+                {
+                    name: 'a template leaf that is also a REMOVED_KEYS entry is rejected (check 6)',
+                    expect: 'reject',
+                    // `REMOVED_KEYS` is compiled into the loader, so a fixture root
+                    // cannot seed it — but it can seed the other side of the
+                    // contradiction. A fixture that declares `quality.wait_for_remote_ci`
+                    // as a live, fully classified leaf is a tree where the loader
+                    // would warn "ignored" about a value the schema honours, which
+                    // is exactly the state check 6 exists to refuse. Classified and
+                    // counted correctly on purpose: every other check passes here,
+                    // so a rejection can only come from check 6.
+                    run: () =>
+                        run(
+                            seed(
+                                'removed-and-live',
+                                'quality:\n  wait_for_remote_ci: false\nbeta: "keep"\n',
+                                table(
+                                    '| `quality.wait_for_remote_ci` | B | `false` | fixture | consent |\n' +
+                                        '| `beta` | C | `"keep"` | fixture | un-inferrable |\n',
+                                ),
+                            ),
+                        ),
+                },
             ],
         });
     } finally {
@@ -331,6 +462,98 @@ function main(): number {
         ledger.complete(target);
     }
 
+    // --- the disposition axis -------------------------------------------------
+    // Orthogonal to A/B/C: that answers who may WRITE a key, this answers whether
+    // the key should EXIST. Checked against the same leaf set, in the same gate,
+    // so a key with no disposition fails the mechanism that already counts it —
+    // rather than sitting in a second artefact that can drift from the template.
+    const dispositionTally: Record<SettingsDisposition, number> = {
+        derivable: 0,
+        'un-inferrable': 0,
+        consent: 0,
+        policy: 0,
+    };
+    for (const leaf of leaves) {
+        const row = rowByKey.get(leaf);
+        if (row === undefined) {
+            continue; // already reported as unclassified above
+        }
+        const label = dispositionOf(row.disposition);
+        if (label === null || label === '') {
+            findings.push(
+                `${CONTRACT_RELATIVE}:${String(row.line)}  \`${leaf}\` has no disposition — add one of ` +
+                    `${SETTINGS_DISPOSITIONS.join(' | ')}. A key with no disposition is the finding: ` +
+                    'nobody has said whether it should exist.',
+            );
+            continue;
+        }
+        if (!isSettingsDisposition(label)) {
+            findings.push(
+                `${CONTRACT_RELATIVE}:${String(row.line)}  \`${leaf}\` has disposition '${label}' — ` +
+                    `allowed: ${SETTINGS_DISPOSITIONS.join(' | ')}.`,
+            );
+            continue;
+        }
+        dispositionTally[label] += 1;
+        if (label === 'derivable' && replacementOf(row.disposition) === '') {
+            // The replacement clause is what makes `derivable` falsifiable. Without
+            // it the label degrades into a synonym for "inconvenient to keep", and
+            // the direction of this axis pushes every borderline row toward it.
+            findings.push(
+                `${CONTRACT_RELATIVE}:${String(row.line)}  \`${leaf}\` is \`derivable\` but names no ` +
+                    'replacement — write `derivable — <what decides instead>`. A derivable row that ' +
+                    'cannot name its replacement is reclassified, not deleted.',
+            );
+        }
+    }
+
+    // The anti-regrowth ratchet. `derivable` is a deletion queue, so its size is
+    // a debt count and may only fall: a NEW key classified `derivable` is a key
+    // that should not have been added, and it raises the number. The 56-day
+    // non-stagnation clause in the shared baseline mechanism is the other half —
+    // a queue that never drains is a direction nobody is walking.
+    //
+    // Deliberately scoped to the real repo root. Under `--root` (self-test
+    // fixtures) the baseline describes a different tree entirely, and judging a
+    // two-key fixture against this repository's surface would make every fixture
+    // report a loose ratchet.
+    if (_rootOverride(process.argv.slice(2)) === null) {
+        const verdict = checkRatchet({
+            gate: `${GATE}:derivable-surface`,
+            actual: dispositionTally.derivable,
+            repoRoot: REPO_ROOT,
+        });
+        if (!verdict.ok) {
+            findings.push(verdict.message);
+        } else if (verdict.status === 'improved' && !QUIET) {
+            process.stdout.write(`ℹ️  ${verdict.message}\n`);
+        }
+    }
+
+    const declaredDisposition = parseDeclaredDispositionCounts(contractText);
+    const dispositionExpected: Array<[string, number | null, number]> = [
+        ['derivable', declaredDisposition.derivable, dispositionTally.derivable],
+        ['un-inferrable', declaredDisposition['un-inferrable'], dispositionTally['un-inferrable']],
+        ['consent', declaredDisposition.consent, dispositionTally.consent],
+        ['policy', declaredDisposition.policy, dispositionTally.policy],
+        ['Total', declaredDisposition.total, leaves.length],
+    ];
+    for (const [label, stated, actual] of dispositionExpected) {
+        if (stated === null) {
+            findings.push(
+                `${CONTRACT_RELATIVE}  the Dispositions table has no '${label}' row — a published count ` +
+                    'with no row is a count nothing can check.',
+            );
+            continue;
+        }
+        if (stated !== actual) {
+            findings.push(
+                `${CONTRACT_RELATIVE}  Dispositions says ${label} = ${String(stated)}, the table holds ` +
+                    `${String(actual)} — a derived number beside a mechanism that can compute it.`,
+            );
+        }
+    }
+
     const declared = parseDeclaredClassCounts(contractText);
     const expected: Array<[string, number | null, number]> = [
         ['A', declared.A, tally.A],
@@ -354,6 +577,45 @@ function main(): number {
         }
     }
 
+    // Check 6 — the DELETION side of the surface.
+    //
+    // Checks 1-5 all police what is added: a new leaf needs a row, a class, a
+    // disposition, a conservative default. Nothing policed what is removed, and
+    // that is the asymmetry this axis lives on — the whole direction of the
+    // roadmap behind it is deletion, so the un-gated half was the half doing the
+    // work. Two contradictions are decidable here and neither is visible to the
+    // loader that prints the warning:
+    //
+    //   a. a reason that names no replacement. The `derivable` rows above are
+    //      already held to "name what decides instead" because that clause is the
+    //      falsifier; a deleted key is the same claim after the fact, and a
+    //      warning that says only "removed" sends the reader looking for a
+    //      successor key that does not exist.
+    //   b. a key that is BOTH removed and live. Re-adding a leaf while its
+    //      `REMOVED_KEYS` entry stands makes the loader warn "ignored" about a
+    //      value the schema now honours — the reader is told the opposite of what
+    //      happens.
+    //
+    // What this does NOT check, stated because the step it serves asks for it:
+    // that the replacement mechanism actually EXISTS, and that its commit
+    // precedes the deletion. Neither is decidable from these two files; both stay
+    // model-carried, exactly as the A/B/C judgement itself does.
+    const liveLeaves = new Set(leaves);
+    for (const [removedKey, reason] of REMOVED_KEYS) {
+        if (reason.trim() === '') {
+            findings.push(
+                `src/scripts/_lib/agent_settings.ts  \`${removedKey}\` is in REMOVED_KEYS with an empty ` +
+                    'reason — name what decides instead, not that it is gone.',
+            );
+        }
+        if (liveLeaves.has(removedKey)) {
+            findings.push(
+                `${TEMPLATE_RELATIVE}  \`${removedKey}\` is a live template leaf AND a REMOVED_KEYS ` +
+                    'entry — the loader would warn that a honoured value is ignored. Drop one side.',
+            );
+        }
+    }
+
     ledger.report();
 
     if (findings.length > 0) {

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 };