@event4u/agent-config 8.13.0 → 9.0.0

package/src/scripts/check_council_config_location.ts

@@ -3,11 +3,17 @@
  * CI guard: council config lives in `.ai-council.yml`, never `.agent-settings.yml`.
  *
  * Ported from the retired Python `src/scripts/check_council_config_location.py` (ADR-200).
- * The CLI contract is pinned — `--quiet` flag, exit codes (0 clean,
- * 1 at least one violation), byte-identical finding messages, same scan globs
- * (sorted), same fence tracking, same negation / `ai_council:` block detection,
- * and the same `<!-- council-config-allowed -->` escape pragma. No behaviour
- * changes — historical quirks preserved (consumers pin the exact behaviour).
+ * The original two checks keep their pinned CLI contract — `--quiet` flag,
+ * exit codes (0 clean, 1 at least one violation), byte-identical finding
+ * messages, same `SCAN_GLOBS` (sorted), same fence tracking, same negation /
+ * `ai_council:` block detection, and the same `<!-- council-config-allowed -->`
+ * escape pragma.
+ *
+ * Additive since ADR-104: a third check (§3 below) flags project-tree
+ * *placement* of the council file. The original two checks are unchanged; the
+ * path check runs over its own `PATH_CHECK_GLOBS` (the council surfaces + the
+ * settings template + the `.ai-council.yml.example`) so the settings template's
+ * many legitimate `.agent-settings.yml` self-references never trip check §1.
  *
  * Per ADR-104 (superseding ADR-093) the council reads a dedicated
  * `.ai-council.yml` resolved ALWAYS from the user-global location
@@ -16,19 +22,26 @@
  * path). Keys are top-level in that file; the legacy `ai_council.*` block
  * under `.agent-settings.yml` was removed in Phase 0.
  *
- * What it flags, in the council command/skill surfaces + the config contract:
+ * What it flags:
  *
  *   1. A `.agent-settings.yml` reference that is NOT negated — i.e. an
  *      instruction to read/use it for council config. Corrective mentions
  *      ("NOT in `.agent-settings.yml`", "was removed", "never read") carry a
- *      negation marker on the same line and are allowed.
+ *      negation marker on the same line and are allowed. (SCAN_GLOBS)
  *   2. A bare `ai_council:` YAML parent-block declaration — post-ADR-093 the
  *      keys are top-level in `.ai-council.yml`; there is no `ai_council:`
- *      namespace to nest under.
+ *      namespace to nest under. (SCAN_GLOBS)
+ *   3. A project-tree PLACEMENT of the council file — `agents/.ai-council.yml`,
+ *      `agents/settings/.ai-council.yml`, or a `<project_root>/…/.ai-council.yml`
+ *      path — that is NOT negated. The council file is user-global ONLY
+ *      (ADR-104); any project-tree path is drift. Corrective mentions ("is
+ *      ignored", "never read", "no project-local", "superseded") pass on the
+ *      same line. (PATH_CHECK_GLOBS)
  *
  * Escape hatch: a line carrying `<!-- council-config-allowed -->` is exempt
  * (for a legitimate non-council `.agent-settings.yml` reference, e.g.
- * `personal.autonomy`).
+ * `personal.autonomy`, or a historical placement mention in a section
+ * explicitly marked superseded).
  *
  * Exit codes:
  *   0 — clean.
@@ -61,6 +74,35 @@ const NEGATION_RE = /\b(not|never|removed|no\s+longer|neither|instead)\b/i;
 const AI_COUNCIL_BLOCK_RE = /^\s*ai_council:\s*(#.*)?$/;
 const ALLOW_PRAGMA = '<!-- council-config-allowed -->';
 
+// ── §3 project-tree placement check (ADR-104) ──────────────────────
+// The council file is user-global ONLY. These are the surfaces where a
+// stray project-tree placement instruction does real damage — the council
+// command/skill surfaces + contract (SCAN_GLOBS) PLUS the settings template
+// and the copy-from example. The template carries countless legitimate
+// `.agent-settings.yml` self-references, so it is scanned ONLY by §3, never
+// by §1.
+const PATH_CHECK_GLOBS = [
+    ...SCAN_GLOBS,
+    'src/config/agent-settings.template.yml',
+    'agents/templates/.ai-council.yml.example',
+] as const;
+
+// A project-tree PLACEMENT of the council file: `agents/.ai-council.yml`,
+// `agents/settings/.ai-council.yml`, or any `<project_root>/…/.ai-council.yml`.
+// Deliberately does NOT match the user-global `…/agent-config/settings/
+// .ai-council.yml` (no literal `agents/` segment) nor the copy-from
+// `agents/templates/.ai-council.yml.example` (segment is `templates/`, and
+// `.example` is not the config file).
+const PROJECT_PATH_COUNCIL_RE =
+    /(?:agents\/(?:settings\/)?\.ai-council\.yml(?!\.example)|<project[_-]?root>[^\n`]*\.ai-council\.yml)/;
+
+// Broader negation set for §3 — corrective placement mentions use vocabulary
+// the §1 NEGATION_RE does not cover ("is ignored", "no project-local
+// lookup", "superseded"). A match on the same line marks the reference
+// corrective and is allowed.
+const PATH_NEGATION_RE =
+    /\b(not|never|removed|no\s+longer|neither|instead|ignored|superseded|no\s+project-local|not\s+read|does\s+not\s+read)\b/i;
+
 /**
  * Mirror Python `str.lstrip()` — strips all leading Unicode whitespace.
  * Python's `str.lstrip()` (no args) strips the Unicode whitespace class;
@@ -79,9 +121,12 @@ function _lstrip(s: string): string {
  * the same sort (component-wise via Path comparison). We approximate with a
  * recursive walk per glob pattern, sorting POSIX paths.
  */
-function* iter_files(root: string): Generator<string> {
+function* iter_files(
+    root: string,
+    globs: readonly string[] = SCAN_GLOBS,
+): Generator<string> {
     const seen = new Set<string>();
-    for (const pattern of SCAN_GLOBS) {
+    for (const pattern of globs) {
         for (const p of _glob(root, pattern)) {
             if (_isFile(p) && !seen.has(p)) {
                 seen.add(p);
@@ -220,18 +265,69 @@ function find_violations(root: string): string[] {
     return findings;
 }
 
+/**
+ * §3 — flag project-tree PLACEMENT of the council config file (ADR-104).
+ *
+ * The council file is user-global only; any `agents/(settings/)?.ai-council.yml`
+ * or `<project_root>/…/.ai-council.yml` path is drift. Corrective mentions
+ * (same-line `PATH_NEGATION_RE`) and the `<!-- council-config-allowed -->`
+ * pragma pass. Fenced code is skipped, mirroring §1/§2.
+ */
+function find_path_violations(root: string): string[] {
+    const findings: string[] = [];
+    for (const p of iter_files(root, PATH_CHECK_GLOBS)) {
+        const rel = _relPosix(root, p);
+        let in_fence = false;
+        const lines = fs.readFileSync(p, 'utf-8').split('\n');
+        if (lines.length > 0 && lines[lines.length - 1] === '') {
+            lines.pop();
+        }
+        for (let i = 0; i < lines.length; i++) {
+            const lineno = i + 1;
+            const raw = lines[i]!;
+            const stripped = _lstrip(raw);
+            if (stripped.startsWith('```') || stripped.startsWith('~~~')) {
+                in_fence = !in_fence;
+                continue;
+            }
+            if (in_fence || raw.includes(ALLOW_PRAGMA)) {
+                continue;
+            }
+            // Corrective sentences often wrap, leaving the negation
+            // ("never reads", "no project-local lookup") on the previous
+            // line and the path on this one. Check both lines for negation
+            // so a correctly-negated wrapped mention is not flagged. A real
+            // "place it here" instruction never carries a negation one line up.
+            const prev = i > 0 ? lines[i - 1]! : '';
+            const negated =
+                PATH_NEGATION_RE.test(raw) || PATH_NEGATION_RE.test(prev);
+            if (PROJECT_PATH_COUNCIL_RE.test(raw) && !negated) {
+                findings.push(
+                    `${rel}:${lineno}: council config placed in the project tree ` +
+                        '— the `.ai-council.yml` file is user-global ONLY ' +
+                        '(`~/.event4u/agent-config/settings/.ai-council.yml`, ADR-104). ' +
+                        'The project tree is never searched. Point at the user-global ' +
+                        'path, add a negation marker, or add ' +
+                        `\`${ALLOW_PRAGMA}\` for a historical/superseded reference.`,
+                );
+            }
+        }
+    }
+    return findings;
+}
+
 function main(): number {
     const root = process.cwd();
-    const findings = find_violations(root);
+    const findings = [...find_violations(root), ...find_path_violations(root)];
     if (findings.length) {
         process.stdout.write('❌  Council config-location violations:\n\n');
         for (const f of findings) {
             process.stdout.write(`  - ${f}\n`);
         }
         process.stdout.write(
-            '\nRule: council config lives in `.ai-council.yml` ' +
-                '(docs/contracts/ai-council-config.md + ADR-093), never in ' +
-                '`.agent-settings.yml`.\n',
+            '\nRule: council config lives in the user-global `.ai-council.yml` ' +
+                '(`~/.event4u/agent-config/settings/.ai-council.yml`, ADR-104) — ' +
+                'never in `.agent-settings.yml`, never in a project `agents/` tree.\n',
         );
         return 1;
     }
@@ -270,11 +366,15 @@ if (_isCliEntry() || process.argv[1] === _HERE) {
 
 export {
     SCAN_GLOBS,
+    PATH_CHECK_GLOBS,
     AGENT_SETTINGS_RE,
     NEGATION_RE,
     AI_COUNCIL_BLOCK_RE,
+    PROJECT_PATH_COUNCIL_RE,
+    PATH_NEGATION_RE,
     ALLOW_PRAGMA,
     iter_files,
     find_violations,
+    find_path_violations,
     main,
 };

package/src/scripts/check_host_loadability.ts

@@ -0,0 +1,81 @@
+/**
+ * check_host_loadability.ts — U4 real-host loadability smoke
+ * (road-to-ecosystem-harvest-reliability-measurement).
+ *
+ * The condensation-hash + linter gates prove the SOURCE tree's shape; this
+ * check proves the GENERATED host trees are actually loadable by their hosts:
+ *   - .claude/skills/<dir>/SKILL.md — frontmatter parses, has name +
+ *     description, and name matches the directory (Claude Code's load rule).
+ *   - .cursor/rules/*.mdc — frontmatter parses (Cursor rejects the file
+ *     silently otherwise).
+ * Run AFTER the projection is generated (CI: the sync-consistency job).
+ * Exit 1 on the first malformed artefact, naming it.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+import { parse as parseYaml } from 'yaml';
+
+export function check_claude_skills(root: string, errors: string[]): void {
+    const dir = path.join(root, '.claude', 'skills');
+    if (!fs.existsSync(dir)) return;
+    for (const name of fs.readdirSync(dir)) {
+        const skillMd = path.join(dir, name, 'SKILL.md');
+        if (!fs.existsSync(skillMd)) {
+            errors.push(`${skillMd}: missing SKILL.md`);
+            continue;
+        }
+        const src = fs.readFileSync(skillMd, 'utf-8');
+        const m = src.match(/^---\n([\s\S]*?)\n---/);
+        if (!m) { errors.push(`${skillMd}: no frontmatter`); continue; }
+        let meta: Record<string, unknown>;
+        try { meta = parseYaml(m[1] ?? '') as Record<string, unknown>; }
+        catch (e) { errors.push(`${skillMd}: frontmatter YAML invalid (${(e as Error).message})`); continue; }
+        if (typeof meta['name'] !== 'string' || !meta['name']) errors.push(`${skillMd}: missing name`);
+        else if (meta['name'] !== name) errors.push(`${skillMd}: name '${meta['name']}' != dir '${name}'`);
+        if (typeof meta['description'] !== 'string' || !meta['description']) errors.push(`${skillMd}: missing description`);
+    }
+}
+
+export function check_cursor_rules(root: string, errors: string[]): void {
+    const dir = path.join(root, '.cursor', 'rules');
+    if (!fs.existsSync(dir)) return;
+    for (const name of fs.readdirSync(dir)) {
+        if (!name.endsWith('.mdc')) continue;
+        const p = path.join(dir, name);
+        const src = fs.readFileSync(p, 'utf-8');
+        const m = src.match(/^---\n([\s\S]*?)\n---/);
+        if (!m) { errors.push(`${p}: no frontmatter`); continue; }
+        // Cursor's documented .mdc format writes `globs: *.php` UNQUOTED —
+        // valid for Cursor's parser, invalid strict YAML (`*` starts an
+        // alias). Quote the globs value before the strict parse so the check
+        // mirrors the host's acceptance, not the YAML spec's.
+        const lenient = (m[1] ?? '').replace(
+            /^(globs:[ \t]*)([^"'\s[][^\n]*)$/m,
+            (_all, key: string, val: string) => `${key}"${val.trim()}"`,
+        );
+        try { parseYaml(lenient); }
+        catch (e) { errors.push(`${p}: frontmatter YAML invalid (${(e as Error).message})`); }
+    }
+}
+
+export function run(root: string): string[] {
+    const errors: string[] = [];
+    check_claude_skills(root, errors);
+    check_cursor_rules(root, errors);
+    return errors;
+}
+
+const isMain = process.argv[1] !== undefined
+    && path.resolve(process.argv[1]) === path.resolve(new URL(import.meta.url).pathname);
+if (isMain) {
+    const rootIdx = process.argv.indexOf('--root');
+    const root = rootIdx !== -1 ? process.argv[rootIdx + 1] ?? '.' : '.';
+    const errors = run(root);
+    if (errors.length > 0) {
+        for (const e of errors) process.stderr.write(`❌  ${e}\n`);
+        process.exit(1);
+    }
+    process.stdout.write('✅  host trees loadable (.claude skills + .cursor mdc)\n');
+    process.exit(0);
+}

package/src/scripts/condense.ts

@@ -1670,6 +1670,10 @@ export function generate_claude_subagents(): number {
         const tools = Array.isArray(toolsRaw) ? toolsRaw.map((t) => String(t)).join(', ') : String(toolsRaw ?? '');
         const tier = typeof fm['model_tier'] === 'string' ? (fm['model_tier'] as string) : 'inherit';
         const model = tier === 'inherit' ? 'inherit' : (_TIER_TO_CLAUDE_MODEL[tier] ?? 'inherit');
+        // Optional pinned reasoning effort (skill-quality-gates Phase 4, Source S):
+        // pass through to the native frontmatter only when the source declares it —
+        // hosts without an effort knob never see the key.
+        const effort = typeof fm['effort'] === 'string' ? (fm['effort'] as string) : null;
 
         const guardedBody =
             defense !== '' && !body.includes('prompt-defense-preamble')
@@ -1681,6 +1685,7 @@ export function generate_claude_subagents(): number {
             `description: ${description}\n` +
             `tools: ${tools}\n` +
             `model: ${model}\n` +
+            (effort !== null ? `effort: ${effort}\n` : '') +
             '---\n' +
             guardedBody;
 

package/src/scripts/hook_manifest.yaml

@@ -134,6 +134,17 @@ concerns:
     script: src/scripts/surface_probe_hook.ts
     args: []
     fail_closed: false
+  # road-to-team-mode Phase 4 — managed Review-Gate circuit breaker.
+  # Runs AFTER the plugin's own Stop gate: reads the persisted gate job
+  # record, counts consecutive BLOCK verdicts per session, injects the
+  # circuit-breaker notice exactly once at ai_team.review_gate.
+  # max_consecutive_blocks. No-op (byte-identical Stop path) while
+  # ai_team.review_gate.managed is false — the shipped default.
+  # Never blocks, exit 0 always.
+  team-review-gate:
+    script: src/scripts/team_review_gate_hook.ts
+    args: []
+    fail_closed: false
 
 platforms:
   augment:
@@ -146,7 +157,7 @@ platforms:
   claude:
     session_start:    [chat-history, hot-context, first-run-gate, onboarding-gate, verify-before-complete, minimal-safe-diff, profile-staleness, wrapper-freshness, surface-probe]
     session_end:      [chat-history]
-    stop:             [chat-history, hot-context, verify-before-complete]
+    stop:             [chat-history, hot-context, verify-before-complete, team-review-gate]
     user_prompt_submit: [chat-history, verify-before-complete, minimal-safe-diff]
     pre_tool_use:     [block-no-verify, rtk-wrap, design-slop]
     post_tool_use:    [chat-history, roadmap-progress, context-hygiene, verify-before-complete, minimal-safe-diff, injection-scan]

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": [] }