@event4u/agent-config 8.13.0 → 9.1.0

package/src/scripts/lint_breaking_changes_index.ts

@@ -0,0 +1,303 @@
+#!/usr/bin/env tsx
+/**
+ * BREAKING_CHANGES.md ↔ CHANGELOG sync linter (road-to-feedback-9.0 P1.4).
+ *
+ * `BREAKING_CHANGES.md` is the discoverable index of consumer-facing breaking
+ * changes, one per major (`X.0.0`). When a diff ships a NEW breaking entry in a
+ * RELEASED CHANGELOG section it must also touch the index in the same change,
+ * or the index silently rots behind the changelog.
+ *
+ * TRIGGER: a git diff (working tree vs `origin/main` — staged + unstaged) that
+ * ADDS a `### BREAKING` / `### BREAKING CHANGES` subheading under a RELEASED
+ * major section (`## [N.0.0]`) in `CHANGELOG.md`, where the same major had no
+ * such subheading at the base ref (a wholly-new released section counts). A
+ * breaking note under `## [Unreleased]` is WIP and never trips the gate.
+ *
+ * REQUIREMENT: when triggered, the same diff must also modify
+ * `BREAKING_CHANGES.md`.
+ *
+ * Escape hatch (mirrors `check_structural_breaking.ts`'s `ci-override` trailer):
+ * an own-line trailer `ci-override: breaking-index-override` (the bare token
+ * `breaking-index-override` on its own line is also accepted) in any commit
+ * body in the range, or the env var `BREAKING_INDEX_OVERRIDE=1`, clears the
+ * gate for an intentional index-deferred change.
+ *
+ * CLI: exit 0 clean/cleared, 1 violation (or selftest failure), 2 usage error.
+ * `--selftest` proves the rule on inline string fixtures (no git needed).
+ */
+import { spawnSync } 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);
+// src/scripts/lint_breaking_changes_index.ts → two levels up is the repo root.
+const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
+const BASE_REF = 'origin/main';
+const CHANGELOG_REL = 'CHANGELOG.md';
+const INDEX_REL = 'BREAKING_CHANGES.md';
+
+// A RELEASED major section heading: `## [N.0.0]…` (minor + patch both 0).
+// `## [Unreleased]` never matches, so WIP breaking notes are out of scope.
+const RELEASED_MAJOR_HEADING_RE = /^## \[(?<version>\d+\.0\.0)\]/;
+// Any other level-1/2 heading closes the current section.
+const SECTION_BOUNDARY_RE = /^##? /;
+// A breaking subheading as emitted by release-please: `### BREAKING` or
+// `### BREAKING CHANGES` (all-caps). Mixed-case `### Breaking changes` under
+// Unreleased is intentionally NOT matched.
+const BREAKING_SUBHEADING_RE = /^### BREAKING\b/;
+// Override trailer — same shape as check_structural_breaking's `ci-override:`
+// mechanism (own line, not an inline mention); the bare token is also accepted.
+const OVERRIDE_RE = /^(?:ci-override:\s*)?breaking-index-override\s*$/m;
+
+/**
+ * Return the set of RELEASED major versions whose CHANGELOG section contains a
+ * `### BREAKING` subheading.
+ */
+export function released_breaking_majors(lines: readonly string[]): Set<string> {
+    const found = new Set<string>();
+    for (let i = 0; i < lines.length; i++) {
+        const m = RELEASED_MAJOR_HEADING_RE.exec(lines[i]!);
+        if (!m) {
+            continue;
+        }
+        const version = m.groups!['version']!;
+        // Section body: heading line down to (exclusive) the next boundary.
+        let end = lines.length;
+        for (let j = i + 1; j < lines.length; j++) {
+            if (SECTION_BOUNDARY_RE.test(lines[j]!)) {
+                end = j;
+                break;
+            }
+        }
+        if (lines.slice(i + 1, end).some((ln) => BREAKING_SUBHEADING_RE.test(ln))) {
+            found.add(version);
+        }
+    }
+    return found;
+}
+
+/**
+ * Core check. Returns the sorted list of RELEASED major versions that GAINED a
+ * `### BREAKING` subheading between `oldLines` and `newLines` — the versions
+ * that should be reflected in `BREAKING_CHANGES.md`.
+ */
+export function added_released_breaking_majors(
+    oldLines: readonly string[],
+    newLines: readonly string[],
+): string[] {
+    const before = released_breaking_majors(oldLines);
+    const after = released_breaking_majors(newLines);
+    const added = [...after].filter((v) => !before.has(v));
+    added.sort();
+    return added;
+}
+
+export interface CheckResult {
+    readonly addedMajors: readonly string[];
+    readonly indexChanged: boolean;
+    readonly overridden: boolean;
+    readonly violation: boolean;
+}
+
+/** Pure decision: violation iff a released BREAKING was added, the index was not touched, and no override cleared it. */
+export function evaluate(
+    oldLines: readonly string[],
+    newLines: readonly string[],
+    indexChanged: boolean,
+    overridden: boolean,
+): CheckResult {
+    const addedMajors = added_released_breaking_majors(oldLines, newLines);
+    const violation = addedMajors.length > 0 && !indexChanged && !overridden;
+    return { addedMajors, indexChanged, overridden, violation };
+}
+
+// ─── git helpers (CLI only) ──────────────────────────────────────────────────
+
+function _git(...args: string[]): string {
+    const proc = spawnSync('git', args, { cwd: REPO_ROOT, encoding: 'utf-8' });
+    return (proc.stdout as string | null) ?? '';
+}
+
+function _base(): string {
+    const mb = _git('merge-base', BASE_REF, 'HEAD').trim();
+    return mb || BASE_REF;
+}
+
+function _splitlines(s: string): string[] {
+    return s.split(/\r\n|\r|\n/);
+}
+
+/** File contents at a ref, or '' when the path did not exist there. */
+function _blob_at(ref: string, rel: string): string {
+    return _git('show', `${ref}:${rel}`);
+}
+
+// ─── selftest fixtures ─────────────────────────────────────────────────────────
+
+function _changelog(sections: string): string[] {
+    return ('# Changelog\n\n## [Unreleased]\n\n' + sections).split('\n');
+}
+
+const _RELEASED_WITH_BREAKING =
+    '## [9.0.0](https://example/compare/8.13.0...9.0.0) (2026-07-13)\n\n' +
+    '### BREAKING CHANGES\n\n* installer path changed ([abc1234](https://example))\n\n';
+const _RELEASED_NO_BREAKING =
+    '## [9.0.0](https://example/compare/8.13.0...9.0.0) (2026-07-13)\n\n' +
+    '### Features\n\n* a feature ([abc1234](https://example))\n\n';
+
+function run_selftest(): number {
+    let failed = 0;
+    const assert = (label: string, ok: boolean): void => {
+        process.stdout.write(`${ok ? '✅' : '❌'}  selftest: ${label}\n`);
+        if (!ok) failed += 1;
+    };
+
+    const oldNoBreaking = _changelog(_RELEASED_NO_BREAKING);
+    const newWithBreaking = _changelog(_RELEASED_WITH_BREAKING);
+
+    // 1. Released BREAKING added, index NOT changed, no override → VIOLATION.
+    const red = evaluate(oldNoBreaking, newWithBreaking, false, false);
+    assert(
+        'released BREAKING added without index change FAILS',
+        red.violation && red.addedMajors.length === 1 && red.addedMajors[0] === '9.0.0',
+    );
+
+    // 2. Same, but the index WAS changed → passes.
+    const greenIdx = evaluate(oldNoBreaking, newWithBreaking, true, false);
+    assert('index change clears the gate', !greenIdx.violation && greenIdx.addedMajors.length === 1);
+
+    // 3. Same, index untouched, but override present → passes.
+    const greenOverride = evaluate(oldNoBreaking, newWithBreaking, false, true);
+    assert('override clears the gate', !greenOverride.violation);
+
+    // 4. BREAKING only under [Unreleased] (WIP) → never trips.
+    const oldEmpty = _changelog('');
+    const newUnreleasedBreaking = (
+        '# Changelog\n\n## [Unreleased]\n\n### BREAKING CHANGES\n\n* wip break ([abc1234](https://example))\n\n'
+    ).split('\n');
+    const wip = evaluate(oldEmpty, newUnreleasedBreaking, false, false);
+    assert('Unreleased BREAKING does not trip the gate', !wip.violation && wip.addedMajors.length === 0);
+
+    // 5. A released BREAKING already present at base (no new addition) → clean.
+    const noop = evaluate(newWithBreaking, newWithBreaking, false, false);
+    assert('pre-existing released BREAKING is not re-flagged', !noop.violation);
+
+    if (failed > 0) {
+        process.stderr.write(`❌  selftest: ${failed} fixture(s) failed.\n`);
+        return 1;
+    }
+    process.stdout.write('✅  selftest: all fixtures behave as specified.\n');
+    return 0;
+}
+
+// ─── CLI ───────────────────────────────────────────────────────────────────────
+
+interface ParsedArgs {
+    selftest: boolean;
+    quiet: boolean;
+}
+
+function _argparse_error(message: string): never {
+    process.stderr.write(`lint_breaking_changes_index: error: ${message}\n`);
+    process.exit(2);
+}
+
+function parse_args(argv: readonly string[]): ParsedArgs {
+    const args: ParsedArgs = { selftest: false, quiet: false };
+    for (const arg of argv) {
+        if (arg === '--selftest') {
+            args.selftest = true;
+        } else if (arg === '--quiet') {
+            args.quiet = true;
+        } else if (arg === '-h' || arg === '--help') {
+            process.stdout.write('usage: lint_breaking_changes_index [-h] [--selftest] [--quiet]\n');
+            process.exit(0);
+        } else {
+            _argparse_error(`unrecognized arguments: ${arg}`);
+        }
+    }
+    return args;
+}
+
+function main(argv?: readonly string[]): number {
+    const args = parse_args(argv ?? process.argv.slice(2));
+    if (args.selftest) {
+        return run_selftest();
+    }
+
+    const base = _base();
+    if (!base) {
+        return 0; // no trunk to diff against (e.g. shallow CI) → no-op
+    }
+
+    const oldLines = _splitlines(_blob_at(base, CHANGELOG_REL));
+    const changelogPath = path.join(REPO_ROOT, CHANGELOG_REL);
+    const newLines = fs.existsSync(changelogPath)
+        ? _splitlines(fs.readFileSync(changelogPath, 'utf-8'))
+        : [];
+
+    // Was BREAKING_CHANGES.md touched (staged or unstaged) vs the base?
+    const indexChanged = _git('diff', '--name-only', base, '--', INDEX_REL).trim() !== '';
+
+    const log = _git('log', '--format=%B', `${base}..HEAD`);
+    const overridden = OVERRIDE_RE.test(log) || process.env['BREAKING_INDEX_OVERRIDE'] === '1';
+
+    const result = evaluate(oldLines, newLines, indexChanged, overridden);
+
+    if (!result.violation) {
+        if (!args.quiet) {
+            if (result.addedMajors.length > 0) {
+                const why = result.overridden ? 'override' : `${INDEX_REL} updated`;
+                process.stdout.write(
+                    `✅ lint-breaking-changes-index: ${result.addedMajors.length} released ` +
+                        `BREAKING addition(s), cleared by ${why}\n`,
+                );
+            } else {
+                process.stdout.write(
+                    '✅ lint-breaking-changes-index: no new released BREAKING entries vs trunk\n',
+                );
+            }
+        }
+        return 0;
+    }
+
+    process.stderr.write(
+        `❌ lint-breaking-changes-index: released BREAKING entr(y/ies) added to ${CHANGELOG_REL} ` +
+            `without a matching ${INDEX_REL} change:\n`,
+    );
+    for (const v of result.addedMajors) {
+        process.stderr.write(`   - ## [${v}] gained a ### BREAKING section\n`);
+    }
+    process.stderr.write(
+        `\nWhen a released major ships a breaking change, ${INDEX_REL} — the discoverable\n` +
+            `index (one entry per major) — must be updated in the same change. Resolve by:\n` +
+            `  • adding the matching entry to ${INDEX_REL}, or\n` +
+            '  • adding an own-line `ci-override: breaking-index-override` trailer to a commit\n' +
+            '    body (or setting BREAKING_INDEX_OVERRIDE=1) for an intentionally deferred index.\n',
+    );
+    return 1;
+}
+
+function _isCliEntry(): boolean {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+    if (import.meta.url === argvUrl) {
+        return true;
+    }
+    try {
+        const here = fs.realpathSync(fileURLToPath(import.meta.url));
+        const argv = fs.realpathSync(path.resolve(process.argv[1]));
+        return here === argv;
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}
+
+export { main, run_selftest, RELEASED_MAJOR_HEADING_RE, BREAKING_SUBHEADING_RE, OVERRIDE_RE };

package/src/scripts/lint_handoffs.ts

@@ -321,9 +321,51 @@ function _pyRepr(s: string): string {
     return `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 }
 
+// ── HANDOFF.md artifact validation (workflow-contracts Phase 2) ─────────
+// SEPARATE concern from the cross-wing skill-handoff lint above: this
+// validates the OPTIONAL standing workflow-resume artifact
+// (agents/runtime/state/HANDOFF.md, written by /agent-handoff --file).
+// Same file on purpose — one linter owns everything named "handoff";
+// the naming reconciliation is this comment.
+
+export const HANDOFF_ARTIFACT_REQUIRED = [
+    'Mode',
+    'Contract received',
+    'Contract owed',
+    'Decisions',
+    'Open questions',
+    'Next command',
+] as const;
+
+/** Returns missing required section headings ([] = valid). */
+export function validate_handoff_artifact(text: string): string[] {
+    const missing: string[] = [];
+    for (const heading of HANDOFF_ARTIFACT_REQUIRED) {
+        const re = new RegExp(`^##\\s+${heading}\\s*$`, 'mi');
+        if (!re.test(text)) {
+            missing.push(heading);
+        }
+    }
+    return missing;
+}
+
 export function main(argv?: readonly string[]): number {
     let skills_dir = SKILLS_DIR;
     const args = argv ?? process.argv.slice(2);
+    if (args.length > 0 && String(args[0]).endsWith('HANDOFF.md')) {
+        // artifact mode — validate the workflow-resume file's required fields
+        const text = fs.readFileSync(_resolve(args[0] as string), 'utf-8');
+        const missing = validate_handoff_artifact(text);
+        if (missing.length === 0) {
+            if (!QUIET) process.stdout.write('✅  HANDOFF artifact: all required fields present\n');
+            return 0;
+        }
+        for (const m of missing) {
+            process.stdout.write(`${args[0]}:1:handoff-artifact-missing-field: missing required section \`## ${m}\`\n`);
+        }
+        process.stderr.write(`❌  ${missing.length} missing HANDOFF field(s)\n`);
+        return 1;
+    }
     if (args.length > 0) {
         skills_dir = _resolve(args[0] as string);
     }

package/src/scripts/lint_skill_descriptions.ts

@@ -0,0 +1,228 @@
+#!/usr/bin/env -S node --import tsx
+/**
+ * lint_skill_descriptions — description-quality gate (ecosystem-harvest
+ * skill-quality-gates, Phase 1).
+ *
+ * Description-driven routing is the suite's core asset: the agent picks a skill
+ * from its `description`. A circular or condition-free description ("Triggers on
+ * X, X" / a description that is just the skill name) makes routing a coin-flip.
+ * This linter rejects the four description defects that break routing:
+ *
+ *   (a) desc-equals-name   — normalized description ≡ normalized name
+ *   (b) duplicated-trigger — the same multi-word trigger phrase repeated verbatim
+ *   (c) triggers-are-name  — every trigger phrase is a substring of the name
+ *                            (no new routing signal beyond the name)
+ *   (d) no-routing-signal  — the description gives the router nothing to
+ *                            disambiguate on: no condition marker (when / before /
+ *                            after / only / for …), no specifics enumeration
+ *                            (em-dash / colon / comma list), no quoted example,
+ *                            no imperative-verb lead. A bare topic restatement.
+ *
+ * (d) is signal-ABSENCE, not a phrase mandate: an imperative house-style
+ * description ("Writes Laravel PHP — Eloquent, Artisan …") carries routing
+ * signal and passes. The farm-generator's name-echo frontmatter is the
+ * must-fail specimen.
+ *
+ * Deterministic, static-config only. Allowlist mirrors lint_skill_originality:
+ * `lint_skill_descriptions_allowlist.json`, capped at 20 (autonomous-execution
+ * allowlist-growth antipattern — over-cap means the linter is wrong).
+ *
+ * Exit codes: 0 = clean (or only allowlisted), 1 = at least one non-allowlisted
+ * violation, 2 = allowlist over cap / usage error.
+ *
+ * Usage:
+ *   ./scripts-run src/scripts/lint_skill_descriptions [--quiet] [--json <path>] [--root <dir>]
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import process from 'node:process';
+import { fileURLToPath } from 'node:url';
+
+import { parse_frontmatter } from './skill_overlap.js';
+
+const _HERE = fileURLToPath(import.meta.url);
+const REPO = path.resolve(path.dirname(_HERE), '..', '..');
+const DEFAULT_SKILLS = path.join(REPO, 'src', 'skills');
+const ALLOWLIST = path.join(path.dirname(_HERE), 'lint_skill_descriptions_allowlist.json');
+const ALLOWLIST_CAP = 20;
+
+// A condition / trigger marker — one of the ways a description signals WHEN it routes.
+const CONDITION_RE =
+    /\b(use when|use to|use for|use on|use during|when |before |after |only when|only for|triggers on|fires when|activ|for [a-z])/i;
+// An imperative / gerund lead verb — the house-style "Writes X", "Convert X" form
+// carries WHAT-it-does routing signal even without a "when" clause.
+const IMPERATIVE_LEAD_RE =
+    /^["'`]*\s*(write|author|convert|review|run|add|build|generate|create|fix|wire|detect|analy[sz]e|optimi[sz]e|draft|extract|route|turn|produce|score|consolidate|rate|model|estimate|plan|check|audit|ship|emit|render|guide|poll|capture|explain|map|prepare|handle|manage|track|compare|validate|verify|enforce|choose|pick|enumerate|investigate|format|scaffold|design|define|describe|gate|block|refactor|migrate|transcribe|summari[sz]e|orchestrate|surface|propose|walk|stress-test|red-team|challenge|bootstrap|seed|install|deploy|package|split|merge|condense|harvest|evaluate|assess|diagnose|reproduce|trace|inspect|lint|test)/i;
+
+interface Violation {
+    slug: string;
+    code: 'desc-equals-name' | 'duplicated-trigger' | 'triggers-are-name' | 'no-routing-signal';
+    detail: string;
+}
+
+/** A description carries routing signal if it names a condition, leads with an
+ * imperative verb, enumerates specifics (em-dash / colon / ≥2 comma segments),
+ * or embeds an example query (a quoted phrase). Absence of all four is the defect. */
+function hasRoutingSignal(desc: string): boolean {
+    if (CONDITION_RE.test(desc)) return true;
+    if (IMPERATIVE_LEAD_RE.test(desc.trim())) return true;
+    if (/[—–:;→]/.test(desc)) return true; // specifics enumeration
+    if (/['"][^'"]{3,}['"]/.test(desc)) return true; // quoted example query
+    if (desc.split(',').filter((s) => s.trim().length >= 3).length >= 2) return true;
+    return false;
+}
+
+function normalize(s: string): string {
+    return s
+        .toLowerCase()
+        .replace(/[`"'*_.,:;!?()[\]{}]/g, ' ')
+        .replace(/[-\s]+/g, ' ')
+        .trim();
+}
+
+/** Split a description into candidate trigger phrases on sentence/list punctuation. */
+function triggerPhrases(desc: string): string[] {
+    return desc
+        .split(/[.;·,|]|\bor\b|\band\b|\/|—|–/i)
+        .map((p) => normalize(p))
+        .filter((p) => p.length >= 3);
+}
+
+function analyseSkill(slug: string, fm: Record<string, string>): Violation[] {
+    const out: Violation[] = [];
+    const name = fm['name'] ?? slug;
+    const desc = (fm['description'] ?? '').trim();
+    if (desc === '') {
+        // Empty description is a frontmatter-schema failure, not this linter's job.
+        return out;
+    }
+    const nName = normalize(name);
+    const nDesc = normalize(desc);
+
+    // (a) description ≡ name
+    if (nDesc === nName) {
+        out.push({ slug, code: 'desc-equals-name', detail: `description normalizes to the name "${name}"` });
+    }
+
+    const phrases = triggerPhrases(desc);
+
+    // (b) duplicated MULTI-WORD trigger phrase repeated verbatim (the farm-specimen
+    // "Triggers on: X, X" defect) — a single recurring domain word is not a defect.
+    const multiWord = phrases.filter((p) => p.includes(' '));
+    const seen = new Set<string>();
+    for (const p of multiWord) {
+        if (seen.has(p)) {
+            out.push({ slug, code: 'duplicated-trigger', detail: `trigger phrase repeated verbatim: "${p}"` });
+            break;
+        }
+        seen.add(p);
+    }
+
+    // (c) every trigger phrase is a substring of the name (no signal beyond name)
+    if (phrases.length > 0 && phrases.every((p) => nName.includes(p) || p.includes(nName))) {
+        out.push({
+            slug,
+            code: 'triggers-are-name',
+            detail: 'every trigger phrase is contained in the skill name — no routing signal beyond the name',
+        });
+    }
+
+    // (d) no routing signal at all — bare topic restatement
+    if (!hasRoutingSignal(desc)) {
+        out.push({
+            slug,
+            code: 'no-routing-signal',
+            detail: 'no condition marker, imperative-verb lead, specifics enumeration, or example query — the router has nothing to disambiguate on',
+        });
+    }
+
+    return out;
+}
+
+function loadAllowlist(): Set<string> {
+    if (!fs.existsSync(ALLOWLIST)) {
+        return new Set();
+    }
+    const data = JSON.parse(fs.readFileSync(ALLOWLIST, 'utf-8')) as {
+        entries?: Array<{ slug: string; code: string }>;
+    };
+    const entries = Array.isArray(data.entries) ? data.entries : [];
+    if (entries.length > ALLOWLIST_CAP) {
+        process.stderr.write(
+            `❌  lint_skill_descriptions: allowlist has ${entries.length} entries (> ${ALLOWLIST_CAP}). ` +
+                `Per the autonomous-execution allowlist-growth antipattern, the linter is wrong, ` +
+                `not the content — tighten the heuristic, do not grow the allowlist.\n`,
+        );
+        process.exit(2);
+    }
+    return new Set(entries.map((e) => `${e.slug}::${e.code}`));
+}
+
+function* skillMds(root: string): Generator<string> {
+    if (!fs.existsSync(root)) return;
+    for (const entry of fs.readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!entry.isDirectory()) continue;
+        const md = path.join(root, entry.name, 'SKILL.md');
+        if (fs.existsSync(md)) yield md;
+    }
+}
+
+interface Args {
+    quiet: boolean;
+    json: string | null;
+    root: string;
+}
+
+function parseArgs(argv: string[]): Args {
+    const a: Args = { quiet: false, json: null, root: DEFAULT_SKILLS };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '--quiet') a.quiet = true;
+        else if (arg === '--json') a.json = argv[(i += 1)] ?? '';
+        else if (arg === '--root') a.root = argv[(i += 1)] ?? DEFAULT_SKILLS;
+        else {
+            process.stderr.write(`lint_skill_descriptions: unrecognized argument: ${arg}\n`);
+            process.exit(2);
+        }
+    }
+    return a;
+}
+
+function main(argv: string[]): number {
+    const args = parseArgs(argv);
+    const allow = loadAllowlist();
+    const violations: Violation[] = [];
+    let scanned = 0;
+    for (const md of skillMds(args.root)) {
+        scanned += 1;
+        const slug = path.basename(path.dirname(md));
+        const [fm] = parse_frontmatter(fs.readFileSync(md, 'utf-8'));
+        for (const v of analyseSkill(slug, fm)) {
+            if (!allow.has(`${v.slug}::${v.code}`)) violations.push(v);
+        }
+    }
+
+    if (args.json) {
+        fs.mkdirSync(path.dirname(args.json), { recursive: true });
+        fs.writeFileSync(args.json, JSON.stringify({ scanned, violations }, null, 2) + '\n');
+    }
+
+    if (violations.length > 0) {
+        process.stderr.write(`❌  lint_skill_descriptions: ${violations.length} description defect(s):\n`);
+        for (const v of violations) {
+            process.stderr.write(`   ${v.slug} [${v.code}] — ${v.detail}\n`);
+        }
+        return 1;
+    }
+    if (!args.quiet) {
+        process.stdout.write(`✅  lint_skill_descriptions: ${scanned} skill(s) scanned, no description defects.\n`);
+    }
+    return 0;
+}
+
+if (path.resolve(process.argv[1] ?? '') === path.resolve(_HERE)) {
+    process.exit(main(process.argv.slice(2)));
+}
+
+export { analyseSkill, normalize, triggerPhrases, main };

package/src/scripts/lint_skill_descriptions_allowlist.json

@@ -0,0 +1 @@
+{ "entries": [] }