javi-forge 1.6.0 → 1.6.1

package/dist/commands/skills.js

@@ -1,8 +1,8 @@
-import fs from 'fs-extra';
-import path from 'path';
-import { parseFrontmatter } from '../lib/frontmatter.js';
+import fs from "fs-extra";
+import path from "path";
+import { parseFrontmatter } from "../lib/frontmatter.js";
 // ── Constants ────────────────────────────────────────────────────────────────
-const DEFAULT_SKILLS_DIR = path.join(process.env['HOME'] ?? '~', '.claude', 'skills');
+const DEFAULT_SKILLS_DIR = path.join(process.env["HOME"] ?? "~", ".claude", "skills");
 const DEFAULT_BUDGET = 8000;
 /** Approximate tokens per character (GPT/Claude rough average) */
 const CHARS_PER_TOKEN = 4;
@@ -22,6 +22,172 @@ const CONTRADICTION_PAIRS = [
     [/\bavoid\b/i, /\bprefer\b/i],
     [/\bdo not\b/i, /\bmust\b/i],
 ];
+/**
+ * Positive and negative signal patterns.
+ * Order matters — first match wins, so more specific patterns go first.
+ */
+const POSITIVE_SIGNALS = [
+    /\balways use\b/i,
+    /\bmust use\b/i,
+    /\bprefer\b/i,
+    /\balways\b/i,
+    /\bmust\b/i,
+    /\brequire\b/i,
+    /\buse\b/i,
+    /\benable\b/i,
+    /\bshould\b/i,
+];
+const NEGATIVE_SIGNALS = [
+    /\bnever use\b/i,
+    /\bdo not use\b/i,
+    /\bdon't use\b/i,
+    /\bnever\b/i,
+    /\bavoid\b/i,
+    /\bdo not\b/i,
+    /\bdon't\b/i,
+    /\bdisable\b/i,
+    /\bno\b/i,
+    /\bforbid\b/i,
+];
+/**
+ * Extract a directive (sentiment + subject) from a rule string.
+ * Returns null if the rule has no clear directive.
+ */
+export function extractDirective(rule) {
+    const norm = rule.toLowerCase().trim();
+    // Try negative first (more specific: "never use X" before "use X")
+    for (const pattern of NEGATIVE_SIGNALS) {
+        const match = norm.match(pattern);
+        if (match) {
+            const subject = norm
+                .slice(match.index + match[0].length)
+                .trim()
+                .replace(/^(the|a|an)\s+/i, "")
+                .replace(/[.;,!]+$/, "")
+                .trim();
+            if (subject.length >= 3) {
+                return { sentiment: "negative", subject };
+            }
+        }
+    }
+    for (const pattern of POSITIVE_SIGNALS) {
+        const match = norm.match(pattern);
+        if (match) {
+            const subject = norm
+                .slice(match.index + match[0].length)
+                .trim()
+                .replace(/^(the|a|an)\s+/i, "")
+                .replace(/[.;,!]+$/, "")
+                .trim();
+            if (subject.length >= 3) {
+                return { sentiment: "positive", subject };
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Check if two subjects are similar enough to be "about the same thing".
+ * Uses simple word-overlap (Jaccard-like) — no external NLP needed.
+ */
+export function subjectsSimilar(a, b, threshold = 0.5) {
+    const wordsA = new Set(a.split(/\s+/).filter((w) => w.length > 2));
+    const wordsB = new Set(b.split(/\s+/).filter((w) => w.length > 2));
+    if (wordsA.size === 0 || wordsB.size === 0)
+        return false;
+    let intersection = 0;
+    for (const w of wordsA) {
+        if (wordsB.has(w))
+            intersection++;
+    }
+    const union = new Set([...wordsA, ...wordsB]).size;
+    return union > 0 && intersection / union >= threshold;
+}
+/**
+ * Detect a directive clash between two rules:
+ * opposite sentiments about the same subject.
+ */
+export function detectDirectiveClash(ruleA, ruleB) {
+    const dA = extractDirective(ruleA);
+    const dB = extractDirective(ruleB);
+    if (!dA || !dB)
+        return null;
+    if (dA.sentiment === dB.sentiment)
+        return null;
+    if (subjectsSimilar(dA.subject, dB.subject)) {
+        const posRule = dA.sentiment === "positive" ? ruleA : ruleB;
+        const negRule = dA.sentiment === "negative" ? ruleA : ruleB;
+        return `Directive clash on "${dA.subject}": positive="${posRule.slice(0, 50)}" vs negative="${negRule.slice(0, 50)}"`;
+    }
+    return null;
+}
+// ── Budget Optimization ─────────────────────────────────────────────────────
+/**
+ * Generate minimal disable sets to bring total tokens under budget.
+ * Uses a greedy approach: disable largest skills first until under budget.
+ * Returns up to 3 alternative optimization suggestions.
+ */
+export function generateBudgetOptimizations(entries, totalTokens, budget) {
+    if (totalTokens <= budget)
+        return [];
+    const excess = totalTokens - budget;
+    const suggestions = [];
+    // Strategy 1: Greedy — disable largest skills first
+    const greedy = greedyDisableSet(entries, excess);
+    suggestions.push(makeSuggestion(greedy, entries, totalTokens, budget));
+    // Strategy 2: Minimal count — find smallest number of skills to disable
+    // (try single-skill solutions first, then pairs)
+    const singles = entries.filter((e) => e.tokens >= excess);
+    if (singles.length > 0) {
+        // Pick the smallest single that still meets budget
+        const sorted = [...singles].sort((a, b) => a.tokens - b.tokens);
+        const minimal = sorted[0];
+        if (minimal.skillName !== greedy[0]?.skillName) {
+            suggestions.push(makeSuggestion([minimal], entries, totalTokens, budget));
+        }
+    }
+    // Strategy 3: If we have many small skills, show a "trim many" approach
+    // Disable the bottom 50% by token count (many small skills)
+    if (entries.length >= 4) {
+        const sortedAsc = [...entries].sort((a, b) => a.tokens - b.tokens);
+        const halfCount = Math.ceil(sortedAsc.length / 2);
+        const bottomHalf = sortedAsc.slice(0, halfCount);
+        const saved = bottomHalf.reduce((s, e) => s + e.tokens, 0);
+        if (saved >= excess) {
+            const trimSet = greedyDisableSet([...bottomHalf].sort((a, b) => b.tokens - a.tokens), excess);
+            const names = new Set(trimSet.map((e) => e.skillName));
+            const alreadySuggested = suggestions.some((s) => s.disableSkills.length === names.size &&
+                s.disableSkills.every((n) => names.has(n)));
+            if (!alreadySuggested) {
+                suggestions.push(makeSuggestion(trimSet, entries, totalTokens, budget));
+            }
+        }
+    }
+    return suggestions;
+}
+/** Greedy: pick largest entries until saved >= excess */
+function greedyDisableSet(entries, excess) {
+    const sorted = [...entries].sort((a, b) => b.tokens - a.tokens);
+    const result = [];
+    let saved = 0;
+    for (const entry of sorted) {
+        if (saved >= excess)
+            break;
+        result.push(entry);
+        saved += entry.tokens;
+    }
+    return result;
+}
+function makeSuggestion(disableSet, _allEntries, totalTokens, budget) {
+    const tokensSaved = disableSet.reduce((s, e) => s + e.tokens, 0);
+    const remaining = totalTokens - tokensSaved;
+    return {
+        disableSkills: disableSet.map((e) => e.skillName),
+        tokensSaved,
+        remainingTokens: remaining,
+        meetsbudget: remaining <= budget,
+    };
+}
 // ── Helpers ──────────────────────────────────────────────────────────────────
 /** Estimate token count from a string */
 export function estimateTokens(text) {
@@ -29,15 +195,15 @@ export function estimateTokens(text) {
 }
 /** Read a SKILL.md and extract its name + critical rules section */
 export async function parseSkillFile(skillPath) {
-    if (!await fs.pathExists(skillPath))
+    if (!(await fs.pathExists(skillPath)))
         return null;
-    const raw = await fs.readFile(skillPath, 'utf-8');
+    const raw = await fs.readFile(skillPath, "utf-8");
     const fm = parseFrontmatter(raw);
-    const name = fm?.data?.['name'] ?? path.basename(path.dirname(skillPath));
+    const name = fm?.data?.["name"] ?? path.basename(path.dirname(skillPath));
     // Extract critical rules — look for "Critical Rules" or numbered list after it
     const rules = extractCriticalRules(fm?.content ?? raw);
     // Extract trigger keywords from description
-    const description = fm?.data?.['description'] ?? '';
+    const description = fm?.data?.["description"] ?? "";
     const triggers = extractTriggers(description);
     return { name, rules, rawContent: raw, triggers };
 }
@@ -60,7 +226,7 @@ export function extractCriticalRules(content) {
 }
 /** Extract a markdown section body by heading pattern */
 function extractSection(content, headingPattern) {
-    const lines = content.split('\n');
+    const lines = content.split("\n");
     let capturing = false;
     const blockLines = [];
     for (const line of lines) {
@@ -74,13 +240,13 @@ function extractSection(content, headingPattern) {
             capturing = true;
         }
     }
-    return blockLines.length > 0 ? blockLines.join('\n') : null;
+    return blockLines.length > 0 ? blockLines.join("\n") : null;
 }
 /** Extract numbered or bulleted list items from a markdown block */
 function extractListItems(block, out) {
-    const lines = block.split('\n');
+    const lines = block.split("\n");
     for (const line of lines) {
-        const match = line.match(/^\s*(?:\d+[\.\)]\s+|-\s+|\*\s+)(.+)/);
+        const match = line.match(/^\s*(?:\d+[.)]\s+|-\s+|\*\s+)(.+)/);
         if (match) {
             const cleaned = match[1].trim();
             if (cleaned.length > 5)
@@ -97,21 +263,24 @@ export function extractTriggers(description) {
     // Split on commas, "or", "and", common delimiters
     const keywords = triggerText
         .split(/[,;]|\bor\b/i)
-        .map(k => k.trim().toLowerCase().replace(/^when\s+/i, ''))
-        .filter(k => k.length > 2);
+        .map((k) => k
+        .trim()
+        .toLowerCase()
+        .replace(/^when\s+/i, ""))
+        .filter((k) => k.length > 2);
     return keywords;
 }
 // ── Core: Scan installed skills ─────────────────────────────────────────────
 /** Discover all SKILL.md files in a skills directory */
 export async function discoverSkills(skillsDir) {
-    if (!await fs.pathExists(skillsDir))
+    if (!(await fs.pathExists(skillsDir)))
         return [];
     const entries = await fs.readdir(skillsDir);
     const skillFiles = [];
     for (const entry of entries) {
-        if (entry.startsWith('.') || entry.startsWith('_'))
+        if (entry.startsWith(".") || entry.startsWith("_"))
             continue;
-        const skillPath = path.join(skillsDir, entry, 'SKILL.md');
+        const skillPath = path.join(skillsDir, entry, "SKILL.md");
         if (await fs.pathExists(skillPath)) {
             skillFiles.push(skillPath);
         }
@@ -119,16 +288,25 @@ export async function discoverSkills(skillsDir) {
     return skillFiles.sort();
 }
 // ── Conflict Detection ──────────────────────────────────────────────────────
-/** Check if two rules contradict each other */
+/** Check if two rules contradict each other (regex pairs + directive clash) */
 export function detectRuleConflict(ruleA, ruleB) {
     const normA = ruleA.toLowerCase().trim();
     const normB = ruleB.toLowerCase().trim();
+    // Strategy 1: Hardcoded regex pairs (fast, high confidence)
     for (const [patternA, patternB] of CONTRADICTION_PAIRS) {
         if ((patternA.test(normA) && patternB.test(normB)) ||
             (patternB.test(normA) && patternA.test(normB))) {
-            return `"${ruleA.slice(0, 60)}" vs "${ruleB.slice(0, 60)}"`;
+            return {
+                reason: `"${ruleA.slice(0, 60)}" vs "${ruleB.slice(0, 60)}"`,
+                kind: "regex-pair",
+            };
         }
     }
+    // Strategy 2: Semantic directive clash (broader, medium confidence)
+    const clashReason = detectDirectiveClash(ruleA, ruleB);
+    if (clashReason) {
+        return { reason: clashReason, kind: "directive-clash" };
+    }
     return null;
 }
 /** Scan all skills for conflicting critical rules */
@@ -157,9 +335,14 @@ export async function findConflicts(skillsDir) {
             // Skip rules from the same skill
             if (a.skillName === b.skillName)
                 continue;
-            const reason = detectRuleConflict(a.rule, b.rule);
-            if (reason) {
-                conflicts.push({ ruleA: a, ruleB: b, reason });
+            const result = detectRuleConflict(a.rule, b.rule);
+            if (result) {
+                conflicts.push({
+                    ruleA: a,
+                    ruleB: b,
+                    reason: result.reason,
+                    kind: result.kind,
+                });
             }
         }
     }
@@ -197,7 +380,15 @@ export async function calculateBudget(skillsDir, budget = DEFAULT_BUDGET) {
             saved += entry.tokens;
         }
     }
-    return { entries, totalTokens, budget, overBudget, suggestions };
+    const optimizations = generateBudgetOptimizations(entries, totalTokens, budget);
+    return {
+        entries,
+        totalTokens,
+        budget,
+        overBudget,
+        suggestions,
+        optimizations,
+    };
 }
 // ── Duplicate Detection ─────────────────────────────────────────────────────
 /** Find skills that overlap in scope/triggers */
@@ -215,7 +406,7 @@ export async function findDuplicates(skillsDir) {
         for (let j = i + 1; j < skillData.length; j++) {
             const a = skillData[i];
             const b = skillData[j];
-            const sharedTriggers = a.triggers.filter(t => b.triggers.some(bt => bt.includes(t) || t.includes(bt)));
+            const sharedTriggers = a.triggers.filter((t) => b.triggers.some((bt) => bt.includes(t) || t.includes(bt)));
             if (sharedTriggers.length === 0)
                 continue;
             const maxTriggers = Math.max(a.triggers.length, b.triggers.length);
@@ -244,7 +435,7 @@ export async function findDuplicates(skillsDir) {
 export async function runSkillsDoctor(options) {
     const skillsDir = options.skillsDir ?? DEFAULT_SKILLS_DIR;
     const budget = options.budget ?? DEFAULT_BUDGET;
-    if (options.mode === 'budget') {
+    if (options.mode === "budget") {
         const budgetResult = await calculateBudget(skillsDir, budget);
         return { conflicts: [], budget: budgetResult, duplicates: [] };
     }
@@ -260,16 +451,89 @@ export async function runSkillsDoctor(options) {
 const DEFAULT_THRESHOLD = 50;
 /** Vague terms that reduce clarity score */
 const VAGUE_TERMS = [
-    /\bstuff\b/i, /\bthings?\b/i, /\betc\.?\b/i, /\bmisc\b/i,
-    /\bvarious\b/i, /\bsome\b/i, /\bmaybe\b/i, /\bprobably\b/i,
+    /\bstuff\b/i,
+    /\bthings?\b/i,
+    /\betc\.?\b/i,
+    /\bmisc\b/i,
+    /\bvarious\b/i,
+    /\bsome\b/i,
+    /\bmaybe\b/i,
+    /\bprobably\b/i,
 ];
 /** Action verbs that indicate actionable rules */
 const ACTION_VERBS = [
-    /\buse\b/i, /\bavoid\b/i, /\bprefer\b/i, /\bnever\b/i,
-    /\balways\b/i, /\bmust\b/i, /\bshould\b/i, /\bshall\b/i,
-    /\bensure\b/i, /\bwrite\b/i, /\bcreate\b/i, /\bfollow\b/i,
-    /\bdo not\b/i, /\bapply\b/i, /\bimplement\b/i, /\brun\b/i,
+    /\buse\b/i,
+    /\bavoid\b/i,
+    /\bprefer\b/i,
+    /\bnever\b/i,
+    /\balways\b/i,
+    /\bmust\b/i,
+    /\bshould\b/i,
+    /\bshall\b/i,
+    /\bensure\b/i,
+    /\bwrite\b/i,
+    /\bcreate\b/i,
+    /\bfollow\b/i,
+    /\bdo not\b/i,
+    /\bapply\b/i,
+    /\bimplement\b/i,
+    /\brun\b/i,
+];
+/** Dangerous patterns in skill content that indicate safety risks */
+const DANGEROUS_PATTERNS = [
+    { pattern: /\beval\s*\(/i, label: "eval() usage", weight: 20 },
+    { pattern: /\bexec\s*\(/i, label: "exec() usage", weight: 15 },
+    {
+        pattern: /\bchild_process\b/i,
+        label: "child_process reference",
+        weight: 10,
+    },
+    { pattern: /\brm\s+-rf\b/i, label: "rm -rf command", weight: 20 },
+    {
+        pattern: /\bcurl\b.*\|\s*(?:sh|bash)\b/i,
+        label: "curl piped to shell",
+        weight: 25,
+    },
+    { pattern: /\bsudo\b/i, label: "sudo usage", weight: 15 },
+    { pattern: /\bchmod\s+777\b/i, label: "chmod 777", weight: 15 },
+    {
+        pattern: /\b(?:password|secret|token|api_key)\s*[:=]\s*['"][^'"]+['"]/i,
+        label: "hardcoded secret",
+        weight: 25,
+    },
+    {
+        pattern: /\b__proto__\b|\bconstructor\s*\[/i,
+        label: "prototype pollution",
+        weight: 20,
+    },
+    {
+        pattern: /\binnerHTML\s*=/i,
+        label: "innerHTML assignment (XSS risk)",
+        weight: 10,
+    },
+    {
+        pattern: /\bdangerouslySetInnerHTML\b/i,
+        label: "dangerouslySetInnerHTML",
+        weight: 10,
+    },
+    {
+        pattern: /\bno[- ]?verify\b.*\bgit\b|\bgit\b.*\bno[- ]?verify\b/i,
+        label: "git --no-verify bypass",
+        weight: 10,
+    },
+    {
+        pattern: /\bforce[- ]?push\b|\bpush\s+--force\b/i,
+        label: "force push instruction",
+        weight: 10,
+    },
+    {
+        pattern: /\bdisable.*(?:eslint|typescript|security)\b/i,
+        label: "linter/security disable",
+        weight: 10,
+    },
 ];
+/** Default registry quality threshold */
+const DEFAULT_REGISTRY_THRESHOLD = 60;
 /**
  * Score completeness (0-100): frontmatter fields, critical rules, structure.
  */
@@ -313,7 +577,7 @@ export function scoreClarity(parsed) {
         score += 20;
     // Rules contain action verbs (up to 40 pts)
     if (parsed.rules.length > 0) {
-        const actionableCount = parsed.rules.filter(rule => ACTION_VERBS.some(verb => verb.test(rule))).length;
+        const actionableCount = parsed.rules.filter((rule) => ACTION_VERBS.some((verb) => verb.test(rule))).length;
         const ratio = actionableCount / parsed.rules.length;
         score += Math.round(ratio * 40);
     }
@@ -355,7 +619,10 @@ export function scoreTestability(parsed) {
     else if (gwtCount >= 1)
         score += 25;
     // Rules are specific enough (contain file paths, code refs, or patterns)
-    const specificRules = parsed.rules.filter(rule => /[`'"]/.test(rule) || /\.\w+/.test(rule) || /\bfile\b/i.test(rule) || /\bpath\b/i.test(rule)).length;
+    const specificRules = parsed.rules.filter((rule) => /[`'"]/.test(rule) ||
+        /\.\w+/.test(rule) ||
+        /\bfile\b/i.test(rule) ||
+        /\bpath\b/i.test(rule)).length;
     if (parsed.rules.length > 0) {
         const specificity = specificRules / parsed.rules.length;
         score += Math.round(specificity * 30);
@@ -407,7 +674,81 @@ export function scoreTokenEfficiency(parsed) {
     return Math.max(0, Math.min(score, 100));
 }
 /**
- * Score a skill on all 4 dimensions and compute overall.
+ * Score safety (0-100): absence of dangerous patterns, injection risks, credential leaks.
+ * Starts at 100 and deducts for each dangerous pattern found.
+ */
+export function scoreSafety(parsed) {
+    let score = 100;
+    for (const { pattern, weight } of DANGEROUS_PATTERNS) {
+        if (pattern.test(parsed.rawContent)) {
+            score -= weight;
+        }
+    }
+    // Bonus: skill explicitly mentions security best practices (+10, capped at 100)
+    if (/\bsanitiz/i.test(parsed.rawContent) ||
+        /\bescap/i.test(parsed.rawContent)) {
+        score += 10;
+    }
+    if (/\bvalidat/i.test(parsed.rawContent)) {
+        score += 5;
+    }
+    return Math.max(0, Math.min(score, 100));
+}
+/**
+ * Score agent readiness (0-100): how well-prepared a skill is for AI agent consumption.
+ * Checks for triggers, tool restrictions, examples, structured output, and error handling.
+ */
+export function scoreAgentReadiness(parsed) {
+    let score = 0;
+    // Has triggers for auto-activation (25 pts)
+    if (parsed.triggers.length >= 3)
+        score += 25;
+    else if (parsed.triggers.length >= 1)
+        score += 15;
+    // Has tool restrictions or permissions (e.g., "only use", "do not use", "allowed tools") (20 pts)
+    if (/\b(?:only use|allowed tools?|restricted to|do not use|forbidden|prohibited)\b/i.test(parsed.rawContent)) {
+        score += 20;
+    }
+    // Has examples with expected input/output or code blocks (20 pts)
+    const codeBlocks = (parsed.rawContent.match(/```/g) ?? []).length / 2;
+    if (codeBlocks >= 3)
+        score += 20;
+    else if (codeBlocks >= 1)
+        score += 10;
+    // Has structured output format (JSON, YAML, or explicit format section) (15 pts)
+    if (/\boutput format\b/i.test(parsed.rawContent) ||
+        /\breturn.*(?:json|yaml|structured)\b/i.test(parsed.rawContent)) {
+        score += 15;
+    }
+    else if (/```(?:json|yaml)/i.test(parsed.rawContent)) {
+        score += 10;
+    }
+    // Has error handling guidance ("if error", "when fails", "fallback") (10 pts)
+    if (/\b(?:if.*(?:error|fail)|fallback|edge case|error handling)\b/i.test(parsed.rawContent)) {
+        score += 10;
+    }
+    // Has a clear "when NOT to use" or scope boundary (10 pts)
+    if (/\b(?:do not trigger|not applicable|out of scope|when not to)\b/i.test(parsed.rawContent)) {
+        score += 10;
+    }
+    return Math.min(score, 100);
+}
+/**
+ * Convert numeric score to letter grade.
+ */
+export function computeGrade(overall) {
+    if (overall >= 90)
+        return "A";
+    if (overall >= 80)
+        return "B";
+    if (overall >= 70)
+        return "C";
+    if (overall >= 60)
+        return "D";
+    return "F";
+}
+/**
+ * Score a skill on all 6 dimensions and compute overall with letter grade.
  */
 export async function scoreSkill(skillPath, threshold = DEFAULT_THRESHOLD) {
     const parsed = await parseSkillFile(skillPath);
@@ -417,22 +758,62 @@ export async function scoreSkill(skillPath, threshold = DEFAULT_THRESHOLD) {
     const clarity = scoreClarity(parsed);
     const testability = scoreTestability(parsed);
     const tokenEfficiency = scoreTokenEfficiency(parsed);
-    // Weighted average: completeness 30%, clarity 25%, testability 25%, token-efficiency 20%
-    const overall = Math.round(completeness * 0.30 +
-        clarity * 0.25 +
-        testability * 0.25 +
-        tokenEfficiency * 0.20);
+    const safety = scoreSafety(parsed);
+    const agentReadiness = scoreAgentReadiness(parsed);
+    // Weighted average: completeness 20%, clarity 20%, testability 15%,
+    // token-efficiency 15%, safety 15%, agent-readiness 15%
+    const overall = Math.round(completeness * 0.2 +
+        clarity * 0.2 +
+        testability * 0.15 +
+        tokenEfficiency * 0.15 +
+        safety * 0.15 +
+        agentReadiness * 0.15);
+    const grade = computeGrade(overall);
     return {
         skillName: parsed.name,
         completeness,
         clarity,
         testability,
         tokenEfficiency,
+        safety,
+        agentReadiness,
         overall,
+        grade,
         threshold,
         passing: overall >= threshold,
     };
 }
+/**
+ * Gate check for registry inclusion. Rejects skills below the configured threshold.
+ */
+export async function registryGate(skillPath, threshold = DEFAULT_REGISTRY_THRESHOLD) {
+    const score = await scoreSkill(skillPath, threshold);
+    if (!score)
+        return null;
+    const accepted = score.passing;
+    let reason;
+    if (!accepted) {
+        const failures = [];
+        if (score.safety < 60)
+            failures.push(`safety=${score.safety}`);
+        if (score.completeness < 40)
+            failures.push(`completeness=${score.completeness}`);
+        if (score.clarity < 40)
+            failures.push(`clarity=${score.clarity}`);
+        if (score.agentReadiness < 30)
+            failures.push(`agent-readiness=${score.agentReadiness}`);
+        reason =
+            failures.length > 0
+                ? `Rejected (${score.grade}, ${score.overall}/100): weak dimensions — ${failures.join(", ")}`
+                : `Rejected (${score.grade}, ${score.overall}/100): below threshold ${threshold}`;
+    }
+    return {
+        skillName: score.skillName,
+        score,
+        accepted,
+        reason,
+    };
+}
 // ── Benchmarking ───────────────────────────────────────────────────────────
 /**
  * Run structural quality benchmark checks against a skill.
@@ -444,13 +825,16 @@ export async function benchmarkSkill(skillPath) {
     const checks = [];
     // Check 1: Has YAML frontmatter with name
     checks.push({
-        name: 'has-frontmatter-name',
-        passed: parsed.name.length > 0 && parsed.name !== path.basename(path.dirname(skillPath)),
-        detail: parsed.name.length > 0 ? `name: ${parsed.name}` : 'No explicit name in frontmatter',
+        name: "has-frontmatter-name",
+        passed: parsed.name.length > 0 &&
+            parsed.name !== path.basename(path.dirname(skillPath)),
+        detail: parsed.name.length > 0
+            ? `name: ${parsed.name}`
+            : "No explicit name in frontmatter",
     });
     // Check 2: Has trigger keywords
     checks.push({
-        name: 'has-triggers',
+        name: "has-triggers",
         passed: parsed.triggers.length > 0,
         detail: parsed.triggers.length > 0
             ? `${parsed.triggers.length} trigger(s) found`
@@ -458,48 +842,49 @@ export async function benchmarkSkill(skillPath) {
     });
     // Check 3: Has critical rules (>= 3)
     checks.push({
-        name: 'has-critical-rules',
+        name: "has-critical-rules",
         passed: parsed.rules.length >= 3,
         detail: `${parsed.rules.length} rule(s) found`,
     });
     // Check 4: Rules are actionable (contain verbs)
-    const actionableRules = parsed.rules.filter(rule => ACTION_VERBS.some(verb => verb.test(rule)));
+    const actionableRules = parsed.rules.filter((rule) => ACTION_VERBS.some((verb) => verb.test(rule)));
     checks.push({
-        name: 'rules-actionable',
-        passed: parsed.rules.length > 0 && actionableRules.length / parsed.rules.length >= 0.5,
+        name: "rules-actionable",
+        passed: parsed.rules.length > 0 &&
+            actionableRules.length / parsed.rules.length >= 0.5,
         detail: `${actionableRules.length}/${parsed.rules.length} rules have action verbs`,
     });
     // Check 5: Has code examples
     const codeBlocks = (parsed.rawContent.match(/```/g) ?? []).length / 2;
     checks.push({
-        name: 'has-code-examples',
+        name: "has-code-examples",
         passed: codeBlocks >= 1,
         detail: `${Math.floor(codeBlocks)} code block(s)`,
     });
     // Check 6: Has structured sections (headings)
     const headings = (parsed.rawContent.match(/^#+\s/gm) ?? []).length;
     checks.push({
-        name: 'has-sections',
+        name: "has-sections",
         passed: headings >= 3,
         detail: `${headings} section heading(s)`,
     });
     // Check 7: Token budget reasonable (< 3000 tokens)
     const tokens = estimateTokens(parsed.rawContent);
     checks.push({
-        name: 'token-budget-ok',
+        name: "token-budget-ok",
         passed: tokens <= 3000,
         detail: `~${tokens} tokens`,
     });
     // Check 8: No vague terms in rules
-    const vagueRules = parsed.rules.filter(rule => VAGUE_TERMS.some(vague => vague.test(rule)));
+    const vagueRules = parsed.rules.filter((rule) => VAGUE_TERMS.some((vague) => vague.test(rule)));
     checks.push({
-        name: 'no-vague-rules',
+        name: "no-vague-rules",
         passed: vagueRules.length === 0,
         detail: vagueRules.length > 0
             ? `${vagueRules.length} rule(s) contain vague terms`
-            : 'All rules are specific',
+            : "All rules are specific",
     });
-    const passedCount = checks.filter(c => c.passed).length;
+    const passedCount = checks.filter((c) => c.passed).length;
     const passRate = Math.round((passedCount / checks.length) * 100);
     return {
         skillName: parsed.name,