@event4u/agent-config 9.33.0 → 9.34.0

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') {