@event4u/agent-config 9.32.0 → 9.34.0

package/src/scripts/lint_workflow_paths.ts

@@ -0,0 +1,384 @@
+#!/usr/bin/env tsx
+/**
+ * lint_workflow_paths — a workflow `paths:` filter that matches nothing runs
+ * nothing, silently, forever.
+ *
+ * ## The defect class
+ *
+ * A GitHub `on.<event>.paths` filter is a promise: "run this job when these
+ * files change". When the named tree is renamed, retired, or gitignored, the
+ * promise stops being kept and nothing says so — the workflow does not error,
+ * it simply never triggers. The job still appears in the Actions list, still
+ * shows green from its last real run, and a reader auditing the pipeline reads
+ * an intent the pipeline no longer has.
+ *
+ * That is strictly worse than a missing filter. A missing filter over-triggers
+ * and wastes minutes; a dead one under-triggers and hides regressions, and it
+ * is invisible to every other gate in this suite: `actionlint` validates the
+ * schema (a string is a valid string), and no reference checker resolves a
+ * glob against the tree.
+ *
+ * ## Measured, not assumed
+ *
+ * The census that motivated this gate found **20** dead entries across 6
+ * workflow files in four classes: a source tree retired by ADR-051, a
+ * **gitignored** projection tree (matched by no diff, ever), two paths that
+ * moved during the Python-to-TS migration, and two bare repo-root paths whose
+ * real files live under `src/`. All 20 were classified before this gate was
+ * written, and all 20 were repaired in the same change — so the gate ships
+ * **strict** over a corpus verified empty, rather than advisory over a corpus
+ * nobody looked at. A gate that reports zero findings on a corpus it has never
+ * been proven able to fail on is blind, not clean; `--self-test` is what
+ * separates those two.
+ *
+ * ## What counts as a match
+ *
+ * A glob matches when at least one **tracked** file matches it. Tracked, not
+ * on-disk, is the correct universe on purpose: a `paths:` filter is evaluated
+ * against a diff, and only tracked files appear in diffs. This is exactly why
+ * `.augment/**` is dead here despite the directory existing locally — it is
+ * gitignored, so no change to it can ever reach a pull request.
+ *
+ * Directory-shaped entries (`taskfiles/**`, or a bare `src/scripts`) match by
+ * prefix, mirroring GitHub's own semantics.
+ *
+ * ## The escape, and why it is inline
+ *
+ * A filter naming a path that does not exist *yet* — a tree an in-flight PR
+ * introduces — declares itself on the entry:
+ *
+ *     - "future/tree/ **"  # workflow-path-allow: lands in PR #1234, filter pre-staged
+ *
+ * The reason is required and must be more than one word. There is deliberately
+ * no allowlist JSON: a side-channel file is the shape that grows past twenty
+ * entries and quietly becomes the budget bypass `autonomous-execution` names.
+ */
+import * as fs from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+import { GateLedger } from './_lib/gate_ledger.js';
+import { runGateCli, runSelfTest } from './_lib/gate_self_test.js';
+import { reportScanned } from './_lib/scan_scope.js';
+
+const SCRIPTS_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REAL_REPO_ROOT = path.resolve(SCRIPTS_DIR, '..', '..');
+
+const ALLOW_RE = /#\s*workflow-path-allow:\s*(.+?)\s*$/;
+/** A reason must carry real content — two words minimum, eight characters. */
+const MIN_REASON_WORDS = 2;
+const MIN_REASON_CHARS = 8;
+
+export interface PathFinding {
+    readonly file: string;
+    readonly line: number;
+    readonly glob: string;
+    readonly why: 'no-match' | 'thin-reason';
+}
+
+/**
+ * Translate the subset of glob syntax GitHub path filters use into a RegExp.
+ *
+ * `**` crosses directory separators, `*` and `?` do not. Everything else is a
+ * literal — no brace expansion, no character classes, because GitHub does not
+ * document them for this field and guessing at unsupported syntax would make
+ * the gate disagree with the thing it is auditing.
+ */
+export function globToRegExp(glob: string): RegExp {
+    let out = '';
+    for (let i = 0; i < glob.length; i += 1) {
+        const c = glob[i] as string;
+        if (c === '*') {
+            if (glob[i + 1] === '*') {
+                out += '.*';
+                i += 1;
+                if (glob[i + 1] === '/') {
+                    i += 1;
+                }
+            } else {
+                out += '[^/]*';
+            }
+        } else if (c === '?') {
+            out += '[^/]';
+        } else {
+            out += c.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+        }
+    }
+    return new RegExp(`^${out}$`);
+}
+
+/** Does `glob` match at least one path in `tracked`? */
+export function globMatchesAny(glob: string, tracked: readonly string[]): boolean {
+    const re = globToRegExp(glob);
+    const prefix = `${glob.replace(/\/?\*\*$/, '').replace(/\/$/, '')}/`;
+    return tracked.some((t) => re.test(t) || t === glob || t.startsWith(prefix));
+}
+
+/**
+ * Extract every `paths:` / `paths-ignore:` list entry from one workflow body.
+ *
+ * A hand-rolled scan rather than a YAML parse, deliberately: the gate must
+ * report the LINE an entry sits on so a maintainer can jump to it, and a parsed
+ * document has thrown that away. The block ends at the first non-comment,
+ * non-list line — which is how YAML block sequences end anyway.
+ */
+export function extractPathEntries(
+    body: string,
+): { line: number; glob: string; allow: string | null }[] {
+    const out: { line: number; glob: string; allow: string | null }[] = [];
+    let inBlock = false;
+    const lines = body.split('\n');
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] as string;
+        if (/^\s*paths(-ignore)?:\s*$/.test(line)) {
+            inBlock = true;
+            continue;
+        }
+        if (!inBlock) {
+            continue;
+        }
+        if (line.trim() === '' || line.trim().startsWith('#')) {
+            continue;
+        }
+        const m = line.match(/^\s*-\s*(?:'([^']*)'|"([^"]*)"|([^#\s]+))\s*(#.*)?$/);
+        if (m === null) {
+            inBlock = false;
+            continue;
+        }
+        const glob = (m[1] ?? m[2] ?? m[3] ?? '').trim();
+        if (glob === '') {
+            continue;
+        }
+        const allowMatch = (m[4] ?? '').match(ALLOW_RE);
+        out.push({ line: i + 1, glob, allow: allowMatch ? (allowMatch[1] as string) : null });
+    }
+    return out;
+}
+
+function _trackedFiles(repoRoot: string): string[] {
+    try {
+        return execFileSync('git', ['ls-files'], {
+            cwd: repoRoot,
+            encoding: 'utf-8',
+            maxBuffer: 256 * 1024 * 1024,
+        })
+            .split('\n')
+            .filter((l) => l !== '');
+    } catch {
+        return [];
+    }
+}
+
+function _reasonIsThin(reason: string): boolean {
+    return (
+        reason.trim().length < MIN_REASON_CHARS ||
+        reason.trim().split(/\s+/).filter(Boolean).length < MIN_REASON_WORDS
+    );
+}
+
+export interface ScanOptions {
+    readonly repoRoot: string;
+    readonly workflowDir: string;
+    readonly tracked: readonly string[];
+}
+
+export function scanWorkflowDir(
+    opts: ScanOptions,
+    ledger: GateLedger,
+): PathFinding[] {
+    const findings: PathFinding[] = [];
+    let files: string[] = [];
+    try {
+        files = fs
+            .readdirSync(opts.workflowDir)
+            .filter((f) => /\.ya?ml$/.test(f))
+            .sort();
+    } catch {
+        files = [];
+    }
+    ledger.plan(files);
+
+    for (const f of files) {
+        let body: string;
+        try {
+            body = fs.readFileSync(path.join(opts.workflowDir, f), 'utf-8');
+        } catch {
+            ledger.fail(f, 'unreadable');
+            continue;
+        }
+        const before = findings.length;
+        for (const entry of extractPathEntries(body)) {
+            if (entry.allow !== null) {
+                if (_reasonIsThin(entry.allow)) {
+                    findings.push({ file: f, line: entry.line, glob: entry.glob, why: 'thin-reason' });
+                }
+                continue;
+            }
+            if (!globMatchesAny(entry.glob, opts.tracked)) {
+                findings.push({ file: f, line: entry.line, glob: entry.glob, why: 'no-match' });
+            }
+        }
+        if (findings.length > before) {
+            ledger.fail(f, `${String(findings.length - before)} dead path filter(s)`);
+        } else {
+            ledger.complete(f);
+        }
+    }
+    return findings;
+}
+
+interface Args {
+    quiet: boolean;
+    selfTest: boolean;
+    root: string | null;
+}
+
+function _parseArgs(argv: readonly string[]): Args {
+    const args: Args = { quiet: false, selfTest: false, root: null };
+    for (let i = 0; i < argv.length; i += 1) {
+        const a = argv[i];
+        if (a === '--quiet') {
+            args.quiet = true;
+        } else if (a === '--self-test') {
+            args.selfTest = true;
+        } else if (a === '--root') {
+            args.root = argv[i + 1] ?? null;
+            i += 1;
+        }
+    }
+    return args;
+}
+
+function _selfTest(): number {
+    const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'lwp-selftest-'));
+    const mkRepo = (name: string, workflow: string): string => {
+        const repo = path.join(tmp, name);
+        fs.mkdirSync(path.join(repo, '.github', 'workflows'), { recursive: true });
+        fs.mkdirSync(path.join(repo, 'src'), { recursive: true });
+        fs.writeFileSync(path.join(repo, 'src', 'real.ts'), '// real\n');
+        execFileSync('git', ['init', '-q'], { cwd: repo });
+        execFileSync('git', ['add', '-A'], { cwd: repo });
+        fs.writeFileSync(path.join(repo, '.github', 'workflows', 'w.yml'), workflow, 'utf-8');
+        execFileSync('git', ['add', '-A'], { cwd: repo });
+        return repo;
+    };
+    const run = (repo: string): number =>
+        runGateCli(
+            REAL_REPO_ROOT,
+            'src/scripts/lint_workflow_paths.ts',
+            ['--root', repo, '--quiet'],
+            REAL_REPO_ROOT,
+        );
+
+    const HEAD = 'on:\n  pull_request:\n    paths:\n';
+    try {
+        const dead = mkRepo('dead', `${HEAD}      - "retired/tree/**"\n`);
+        const live = mkRepo('live', `${HEAD}      - "src/**"\n`);
+        const allowed = mkRepo(
+            'allowed',
+            `${HEAD}      - "future/tree/**"  # workflow-path-allow: lands in the follow-up PR\n`,
+        );
+        const thin = mkRepo('thin', `${HEAD}      - "future/tree/**"  # workflow-path-allow: soon\n`);
+        const bareDir = mkRepo('baredir', `${HEAD}      - "src"\n`);
+        return runSelfTest({
+            gate: 'lint_workflow_paths',
+            minCases: 4,
+            minRejectCases: 2,
+            cases: [
+                {
+                    name: 'a filter naming a retired tree is rejected',
+                    expect: 'reject',
+                    run: () => run(dead),
+                },
+                { name: 'a filter that matches tracked files passes', expect: 'accept', run: () => run(live) },
+                {
+                    name: 'a bare directory entry matches by prefix, as GitHub does',
+                    expect: 'accept',
+                    run: () => run(bareDir),
+                },
+                {
+                    name: 'a declared pre-staged filter with a real reason passes',
+                    expect: 'accept',
+                    run: () => run(allowed),
+                },
+                {
+                    name: 'a one-word reason is rejected — an unclassifiable exception is boilerplate',
+                    expect: 'reject',
+                    run: () => run(thin),
+                },
+            ],
+        });
+    } finally {
+        fs.rmSync(tmp, { recursive: true, force: true });
+    }
+}
+
+export function main(argv: readonly string[] = process.argv.slice(2)): number {
+    const args = _parseArgs(argv);
+    if (args.selfTest) {
+        return _selfTest();
+    }
+    const repoRoot = args.root !== null ? path.resolve(args.root) : REAL_REPO_ROOT;
+    const workflowDir = path.join(repoRoot, '.github', 'workflows');
+    const tracked = _trackedFiles(repoRoot);
+
+    const ledger = new GateLedger('lint_workflow_paths');
+    const findings = scanWorkflowDir({ repoRoot, workflowDir, tracked }, ledger);
+    const tally = ledger.finalize();
+
+    if (!args.quiet && findings.length > 0) {
+        process.stdout.write('\nlint_workflow_paths — path filters that can never fire:\n\n');
+        for (const f of findings) {
+            const why =
+                f.why === 'no-match'
+                    ? 'matches no tracked file'
+                    : 'workflow-path-allow reason is too thin to classify';
+            process.stdout.write(
+                `  ${f.file}:${String(f.line)}  ${f.glob}\n      ${why}\n`,
+            );
+        }
+        process.stdout.write(
+            '\n  Fix: delete the entry if the tree is retired, or repoint it if the path moved.\n' +
+                '  A filter that matches nothing does not over-trigger — it never triggers.\n',
+        );
+    }
+    if (!args.quiet) {
+        process.stdout.write(
+            `\nlint_workflow_paths: ${String(findings.length)} dead filter(s) across ` +
+                `${String(new Set(findings.map((f) => f.file)).size)} workflow file(s)\n`,
+        );
+        ledger.report();
+    }
+    reportScanned({
+        gate: 'lint_workflow_paths',
+        scanned: tally.completed + tally.failed,
+        units: 'workflow file(s)',
+        roots: ['.github/workflows'],
+    });
+    return findings.length > 0 ? 1 : 0;
+}
+
+const _HERE = fileURLToPath(import.meta.url);
+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 {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+}
+
+if (_isCliEntry() || process.argv[1] === _HERE) {
+    process.exit(main());
+}

package/src/scripts/preamble_byte_census.ts

@@ -557,7 +557,15 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     return 0;
 }
 
-if (process.argv[1] !== undefined) {
+// `__AGENT_CONFIG_BUNDLE__` is defined true by every esbuild target. Inside a
+// bundle `import.meta.url` is the OUTPUT file's URL for every bundled module,
+// so the guard below would match whenever the bundle is invoked directly — and
+// importing this module from a bundled CLI entry (`cmd_doctor` bundles under
+// `build:cli-delegate`) would run the census and exit before that entry's own
+// main. Same shape as the guard in `dispatch_economy_report.ts`.
+declare const __AGENT_CONFIG_BUNDLE__: boolean | undefined;
+const _isBundled = typeof __AGENT_CONFIG_BUNDLE__ !== 'undefined' && __AGENT_CONFIG_BUNDLE__;
+if (!_isBundled && process.argv[1] !== undefined) {
     const invokedUrl = pathToFileURL(path.resolve(process.argv[1])).href;
     if (import.meta.url === invokedUrl) process.exit(main());
 }

package/src/scripts/report_carrier_divergence.ts

@@ -35,6 +35,16 @@
  * ignored, which is the failure `check-rule-invariants` already paid for once.
  * The point is that the condition becomes VISIBLE, not that it becomes illegal.
  *
+ * BEFORE QUOTING A COUNT FROM THIS REPORT
+ * ---------------------------------------
+ * Read `agents/settings/contexts/carrier-divergence-109-vs-24.md` first. The
+ * figure "109 divergent pairs, binding undefined" reached five independent
+ * release reviews as the tree's largest technical debt; all 109 carry
+ * byte-identical prose, and the real actionable set is the 24-pair `paths:`
+ * subset below, in the over-delivery direction. That correction had no stable
+ * surface, which is why every fresh reader re-derived the wrong number from
+ * this report's own output.
+ *
  * THE FOUR CLASSES, AND WHICH ONE A READER MUST ACT ON
  * ---------------------------------------------------
  *   body-diff        the two carriers deliver different PROSE. This is the class

package/src/scripts/report_conformance_funnel.ts

@@ -11,6 +11,11 @@
  * conformance sources, so the three questions that were answered in three
  * places read as the funnel they are:
  *
+ *   OPPORTUNITY in how many scanned sessions a skill was in context at all —
+ *               derived from `report_skill_obligation_violations.scanStore`'s
+ *               own `sessionsWithASkill`, so it adds no classifier. It is the
+ *               denominator ACTIVATION was missing: `skills.total` is supply,
+ *               not opportunity.
  *   DELIVERY    what rule text the carriers put in front of the model, and
  *               whether the two carriers agree —
  *               `conformance_scan.measureDelivered` (carrier census) +
@@ -176,6 +181,41 @@ export function render(r: FunnelReport): string {
     }
     lines.push('');
 
+    // ── OPPORTUNITY ────────────────────────────────────────────────────────
+    // The stage the funnel was missing. ACTIVATION below reports against
+    // `skills.total`, which is a SUPPLY number: how many skills exist. That
+    // denominator can only fall as the catalogue grows, and it says nothing
+    // about whether any skill had a chance to fire. Opportunity is the
+    // denominator that belongs between delivery and activation — sessions in
+    // which a skill was actually in context.
+    //
+    // DERIVED, never re-measured: `sessionsWithASkill` is the SK-2 scan's own
+    // field, so this stage adds no classifier and cannot disagree with the
+    // COMPLIANCE stage that already prints it.
+    lines.push('OPPORTUNITY — in how many sessions could a skill fire at all?');
+    if (!r.storePresent) {
+        lines.push('    NO DATA: no transcript store — opportunity is not measurable here.');
+        lines.push('    An absent store is an answer, not a zero.');
+    } else {
+        lines.push(`    sessions scanned                      ${r.sk2.sessions}`);
+        lines.push(
+            `    with a skill in context               ${r.sk2.sessionsWithASkill} ` +
+                `(${_pct(r.sk2.sessionsWithASkill, r.sk2.sessions)})`,
+        );
+        lines.push(
+            '    Skill invocations per such session     ' +
+                (r.sk2.sessionsWithASkill === 0
+                    ? 'n/a'
+                    : (r.usage.invocations / r.sk2.sessionsWithASkill).toFixed(2)),
+        );
+    }
+    lines.push("    Honest scope: \"in context\" is the SK-2 scan's reading — a skill was");
+    lines.push('    LOADED, not that the task needed it. So this bounds activation from');
+    lines.push('    above; it never claims a missed invocation was a defect. Report-only and');
+    lines.push('    deliberately without a threshold: a joined funnel with a denominator');
+    lines.push('    invites one, and the activation red-baseline null is terminal.');
+    lines.push('');
+
     // ── ACTIVATION ─────────────────────────────────────────────────────────
     lines.push('ACTIVATION — are the delivered skills invoked?');
     lines.push(`    skills shipped                        ${r.skills.total}`);

package/src/scripts/schemas/subagent.schema.json

@@ -49,9 +49,10 @@
       "uniqueItems": true,
       "items": {
         "type": "string",
-        "enum": ["Read", "Write", "Edit", "Grep", "Glob", "Bash", "WebFetch", "WebSearch", "NotebookEdit"]
+        "pattern": "^(Read|Write|Edit|Grep|Glob|Bash|WebFetch|WebSearch|NotebookEdit)(\\([^()]+\\))?$"
       },
-      "description": "Enum-validated at build time against the Claude Code tool set, so a bad value fails CI rather than producing broken `.claude/agents/` YAML in the user's IDE."
+      "description": "A tool grant: one of the Claude Code tool names, optionally scoped — `Bash(npm test:*)` grants one command family where a bare `Bash` grants a shell. The base name stays closed, so a typo still fails CI rather than producing broken `.claude/agents/` YAML in the user's IDE; only the optional `(...)` suffix is new. Prefer the narrowest grant the task actually needs, per tool-safety Least Agency.",
+      "$comment": "Was a bare enum, which made the scoped-grant syntax `tool-safety` prescribes literally inexpressible here — a schema forbidding what the rule asks for. skill.schema.json's allowed_tools permits that syntax by validating nothing at all; this pattern permits it while keeping the base-name guarantee that made the enum worth having."
     },
     "trust": {
       "type": "object",

package/src/scripts/self_repair_cli.ts

@@ -37,6 +37,7 @@ import {
     type EgressChoice,
     type EgressRoute,
     egressBlockedReason,
+    NEW_RECORDS_PER_SOURCE_PER_WINDOW,
     patchDeniedReason,
     type PushVia,
     renderReport,
@@ -48,6 +49,7 @@ import {
     listRecords,
     markReleased,
     openRecords,
+    readOverflow,
     readRecord,
 } from './_lib/self_repair_store.js';
 
@@ -400,11 +402,33 @@ export function executeRelease(
     return { published: null, attempts };
 }
 
+/**
+ * The creation cap's drop tally, printed whenever it is non-zero. This is the
+ * half that keeps the cap honest: a bounded store is only an improvement if
+ * "records were refused" is readable, otherwise the bound is indistinguishable
+ * from defects that never happened.
+ */
+function overflowLines(root: string): string {
+    const counts = readOverflow(root);
+    const rows = Object.entries(counts).filter(([, v]) => (v?.dropped ?? 0) > 0);
+    if (rows.length === 0) {
+        return '';
+    }
+    let out = '\n';
+    for (const [source, v] of rows) {
+        out +=
+            `  ! creation cap refused ${v?.dropped ?? 0} new ${source} record(s) ` +
+            `(cap ${NEW_RECORDS_PER_SOURCE_PER_WINDOW} per source per 24h, last ${v?.last_seen ?? '?'})\n`;
+    }
+    return out;
+}
+
 function statusCmd(root: string): number {
     const open = openRecords(root);
     const all = listRecords(root);
     if (all.length === 0) {
-        process.stdout.write('self-repair: no records.\n');
+        const overflow = overflowLines(root);
+        process.stdout.write(`self-repair: no records.\n${overflow}`);
         return EXIT_OK;
     }
     process.stdout.write(`self-repair: ${open.length} open of ${all.length} record(s)\n\n`);
@@ -415,6 +439,7 @@ function statusCmd(root: string): number {
                 `      ${r.evidence}\n`,
         );
     }
+    process.stdout.write(overflowLines(root));
     process.stdout.write('\nRelease one: agent-config self-repair:release <fingerprint>\n');
     return EXIT_OK;
 }

package/src/scripts/skill_linter.ts

@@ -106,6 +106,44 @@ const SECTION_ALIASES: Record<string, Set<string>> = {
 
 const RECOMMENDED_SKILL_SECTIONS: string[] = [];
 
+/**
+ * Sections `skill-writing` labels required for a NAMED SUBSET of skills, paired
+ * with the predicate that decides the subset.
+ *
+ * The predicate must be decidable from the filesystem, never from prose. That is
+ * what keeps the false-positive class empty by construction: a skill either ships
+ * a directory or it does not, so there is nothing for a heuristic to get wrong,
+ * and the check can ship as `error` on day one instead of as an open-ended
+ * advisory (the stage-vs-hedge argument in `check_suppression_hygiene.ts`).
+ *
+ * `skill-writing` carries two further section patterns — `Rationalizations to
+ * reject` and `Non-negotiable deliverable`. Neither is listed here, and neither
+ * is labelled required any more. Their populations ("security-stop-routed",
+ * "adjacent-technology cluster") are judgement calls that no property of the tree
+ * declares, so a predicate for them would be exactly the heuristic this table
+ * refuses; compliance stood at 0 of 289 skills while the label said required.
+ * Council 2026-08-11 (2/2, anthropic + openai) resolved the mismatch by
+ * reclassifying both to `recommended pattern` rather than by adding a declared
+ * frontmatter key — an authored opt-in cannot see the skill that should have
+ * opted in and did not, so it would buy a gate without buying the guarantee.
+ */
+const CONDITIONAL_SKILL_SECTIONS: { section: string; when: (skillDir: string) => boolean; reason: string }[] = [
+    {
+        section: 'Security constraints',
+        // `isDirectory()`, not `existsSync` — a FILE named `scripts` would satisfy
+        // an existence test while shipping no script at all, and the predicate is
+        // only false-positive-free because it means what it says.
+        when: (skillDir) => {
+            try {
+                return fs.statSync(path.join(skillDir, 'scripts')).isDirectory();
+            } catch {
+                return false;
+            }
+        },
+        reason: 'the skill ships a scripts/ directory',
+    },
+];
+
 const RULE_BAD_SIGNS = ['## Procedure', '## Output format', '## Gotchas'];
 
 const FRUGALITY_WRITER_SKILLS = new Set([
@@ -1346,7 +1384,7 @@ function lint_execution_metadata(execution: ExecutionBlock): Issue[] {
     return issues;
 }
 
-export function lint_skill(p: string, text: string): LintResult {
+export function lint_skill(p: string, text: string, absPath: string | null = null): LintResult {
     const issues: Issue[] = [];
     const suggestions: string[] = [];
 
@@ -1359,6 +1397,24 @@ export function lint_skill(p: string, text: string): LintResult {
         }
     }
 
+    // `p` may be a repo-relative DISPLAY path, so it is not resolvable on its own;
+    // `absPath` is the path actually read and `lint_file` always supplies it. A
+    // caller that supplies neither gets no conditional check rather than a check
+    // resolved against whatever the process cwd happens to be — a gate whose
+    // verdict depends on the caller's directory is worse than an absent one.
+    const skillDir = absPath !== null ? path.dirname(absPath) : path.isAbsolute(p) ? path.dirname(p) : null;
+    for (const { section, when, reason } of CONDITIONAL_SKILL_SECTIONS) {
+        if (skillDir !== null && when(skillDir) && !sectionMatches(section, sections)) {
+            issues.push(
+                new Issue(
+                    'error',
+                    'missing_conditional_section',
+                    `Missing required section: ${section} (${reason})`,
+                ),
+            );
+        }
+    }
+
     for (const section of RECOMMENDED_SKILL_SECTIONS) {
         if (!sectionMatches(section, sections)) {
             issues.push(
@@ -3533,7 +3589,7 @@ export function lint_file(p: string, repoRoot: string | null = null): LintResult
 
     let result: LintResult;
     if (artifactType === 'skill') {
-        result = lint_skill(displayPath, text);
+        result = lint_skill(displayPath, text, p);
     } else if (artifactType === 'rule') {
         result = lint_rule(displayPath, text);
     } else if (artifactType === 'command') {