@agentskillkit/agent-skills 1.0.1 → 3.2.1

package/packages/cli/src/core/evolution/threshold-checker.js

@@ -0,0 +1,79 @@
+/**
+ * ThresholdChecker - Core Business Logic
+ * 
+ * Determines if a lesson is ready for evolution based on:
+ * - Hit count threshold
+ * - Cognitive confidence
+ * - Pattern stability
+ * 
+ * Pure function with NO side effects.
+ */
+
+export class ThresholdChecker {
+    /**
+     * Check if a lesson is ready for evolution
+     * @param {object} lesson - Cognitive lesson with hitCount, confidence, etc.
+     * @param {number} threshold - Hit count threshold from settings
+     * @returns {{ ready: boolean, reason?: string, confidence?: number }}
+     */
+    static check(lesson, threshold = 10) {
+        const hitCount = lesson.hitCount || 0;
+        const cognitiveConfidence = lesson.cognitive?.confidence || 0.3;
+
+        // Rule 1: Hit count threshold reached
+        if (hitCount >= threshold) {
+            return {
+                ready: true,
+                reason: 'hitCountThreshold',
+                confidence: Math.min(0.9, 0.7 + (hitCount - threshold) * 0.02)
+            };
+        }
+
+        // Rule 2: High cognitive confidence even with lower hits
+        if (cognitiveConfidence >= 0.85 && hitCount >= threshold * 0.5) {
+            return {
+                ready: true,
+                reason: 'highConfidence',
+                confidence: cognitiveConfidence
+            };
+        }
+
+        // Rule 3: Pattern stability (if we have violation history)
+        if (lesson.metadata?.stabilityScore && lesson.metadata.stabilityScore > 0.9) {
+            return {
+                ready: true,
+                reason: 'patternStable',
+                confidence: lesson.metadata.stabilityScore
+            };
+        }
+
+        // Not ready for evolution
+        return { ready: false };
+    }
+
+    /**
+     * Calculate pattern stability from violation history
+     * @param {Array} violationHistory - Array of { timestamp, file, line }
+     * @returns {number} - Stability score 0.0 to 1.0
+     */
+    static calculateStability(violationHistory = []) {
+        if (violationHistory.length < 3) return 0.0;
+
+        // Check if violations are consistent (same files, similar patterns)
+        const uniqueFiles = new Set(violationHistory.map(v => v.file)).size;
+        const totalViolations = violationHistory.length;
+
+        // High stability = violations come from same files (not random)
+        const fileConsistency = 1 - (uniqueFiles / totalViolations);
+
+        // Time-based stability: violations spread over time (not one-off)
+        const timestamps = violationHistory.map(v => v.timestamp).sort();
+        const timeSpan = timestamps[timestamps.length - 1] - timestamps[0];
+        const daySpan = timeSpan / (1000 * 60 * 60 * 24);
+
+        const timeStability = daySpan > 1 ? Math.min(1.0, daySpan / 7) : 0.2;
+
+        // Combined stability
+        return (fileConsistency * 0.6 + timeStability * 0.4);
+    }
+}

package/packages/cli/src/core/index.js

@@ -0,0 +1,15 @@
+/**
+ * Core - Domain Layer
+ * 
+ * Pure business logic with ZERO external dependencies.
+ * This layer defines the business rules and domain models.
+ * 
+ * Exported modules:
+ * - learning: Lesson management, cognitive enhancements, lesson merging
+ * - evolution: Signal detection, threshold checking, review gate
+ * - scanning: File scanning, pattern matching, violation tracking
+ */
+
+export * from './learning/index.js';
+export * from './evolution/index.js';
+export * from './scanning/index.js';

package/packages/cli/src/core/learning/cognitive-enhancer.js

@@ -0,0 +1,282 @@
+/**
+ * CognitiveEnhancer - Core Business Logic
+ * 
+ * Transforms raw lessons into cognitive lessons with intelligence layers:
+ * 1. Intent Inference - detect purpose
+ * 2. Pattern Classification - categorize by type
+ * 3. Maturity Calculation - confidence & state
+ * 4. Evolution Analysis - gap detection
+ * 
+ * Pure business logic with NO external dependencies.
+ */
+
+// ============================================================================
+// INTENT INFERENCE
+// ============================================================================
+
+const INTENT_PATTERNS = {
+    'safe-rebranding': {
+        keywords: ['rebrand', 'rename', 'file-safety'],
+        goal: 'Rename files/entities without data loss or breaking changes',
+        category: 'file-operations',
+    },
+    'cli-ux-consistency': {
+        keywords: ['cli', 'ux', 'menu', 'navigation', 'clack'],
+        goal: 'Provide consistent, intuitive CLI user experience',
+        category: 'user-experience',
+    },
+    'error-prevention': {
+        keywords: ['validation', 'error', 'check', 'verify'],
+        goal: 'Prevent runtime errors through proactive validation',
+        category: 'reliability',
+    },
+    'code-quality': {
+        keywords: ['import', 'architecture', 'quality'],
+        goal: 'Maintain clean, maintainable code structure',
+        category: 'maintainability',
+    },
+};
+
+export class CognitiveEnhancer {
+    /**
+     * Infer lesson intent from tags
+     * @param {Array<string>} tags
+     * @returns {{id: string, goal: string, strength: number, category: string}}
+     */
+    static inferIntent(tags) {
+        if (!tags || tags.length === 0) {
+            return {
+                id: 'unknown',
+                goal: 'General code quality improvement',
+                strength: 0.3,
+                category: 'general',
+            };
+        }
+
+        let bestMatch = null;
+        let bestScore = 0;
+
+        for (const [intentId, pattern] of Object.entries(INTENT_PATTERNS)) {
+            const matchCount = tags.filter(tag =>
+                pattern.keywords.some(kw => tag.toLowerCase().includes(kw.toLowerCase()))
+            ).length;
+
+            const score = matchCount / tags.length; // 0-1 confidence
+
+            if (score > bestScore) {
+                bestScore = score;
+                bestMatch = {
+                    id: intentId,
+                    goal: pattern.goal,
+                    strength: score,
+                    category: pattern.category,
+                };
+            }
+        }
+
+        return bestMatch || {
+            id: 'unknown',
+            goal: 'General code quality improvement',
+            strength: 0.3,
+            category: 'general',
+        };
+    }
+
+    /**
+     * Calculate lesson maturity metrics
+     * @param {Array} mistakes
+     * @param {Array} improvements
+     * @returns {{state: string, confidence: number, indicators: object, coverage: string, recommendation: string}}
+     */
+    static calculateMaturity(mistakes, improvements) {
+        const m = mistakes.length;
+        const i = improvements.length;
+
+        // State determination
+        let state;
+        if (i === 0 && m > 0) state = 'RAW';          // 🟥 Only mistakes
+        else if (i > 0 && m === 0) state = 'IDEAL';   // 🟦 Only improvements (rare)
+        else if (i >= m) state = 'MATURE';            // 🟩 Balanced or improvement-heavy
+        else state = 'LEARNING';                       // 🟨 More mistakes than solutions
+
+        // Multi-factor confidence
+        const balanceScore = i / (m + i) || 0;
+        const evidenceScore = this.calculateEvidenceScore(mistakes, improvements);
+        const recencyScore = this.calculateRecencyScore(mistakes, improvements);
+
+        const confidence = (
+            balanceScore * 0.5 +      // Balance is most important
+            evidenceScore * 0.3 +      // Evidence validates
+            recencyScore * 0.2         // Fresh is better
+        );
+
+        return {
+            state,
+            confidence: Math.round(confidence * 100) / 100,
+            indicators: {
+                balance: Math.round(balanceScore * 100) / 100,
+                evidence: Math.round(evidenceScore * 100) / 100,
+                recency: Math.round(recencyScore * 100) / 100,
+            },
+            coverage: `${m} mistakes / ${i} improvements`,
+            recommendation: this.getRecommendation(state, confidence),
+        };
+    }
+
+    /**
+     * Calculate evidence score based on hit counts
+     */
+    static calculateEvidenceScore(mistakes, improvements) {
+        const totalMistakeHits = mistakes.reduce((sum, m) => sum + (m.hitCount || 0), 0);
+        const totalImprovementHits = improvements.reduce((sum, i) => sum + (i.appliedCount || 0), 0);
+        const totalHits = totalMistakeHits + totalImprovementHits;
+
+        if (totalHits === 0) return 0.1; // No evidence
+        if (totalHits < 5) return 0.3;   // Weak
+        if (totalHits < 20) return 0.6;  // Moderate
+        return 0.9;                       // Strong
+    }
+
+    /**
+     * Calculate recency score
+     */
+    static calculateRecencyScore(mistakes, improvements) {
+        const now = Date.now();
+
+        const allDates = [
+            ...mistakes.map(m => new Date(m.lastHit || m.added).getTime()),
+            ...improvements.map(i => new Date(i.lastApplied || i.added).getTime()),
+        ];
+
+        if (allDates.length === 0) return 0.5;
+
+        const lastUpdate = Math.max(...allDates);
+        const daysSinceUpdate = (now - lastUpdate) / (1000 * 60 * 60 * 24);
+
+        if (daysSinceUpdate < 7) return 1.0;    // This week
+        if (daysSinceUpdate < 30) return 0.8;   // This month
+        if (daysSinceUpdate < 90) return 0.5;   // This quarter
+        return 0.3;                              // Stale
+    }
+
+    /**
+     * Get recommendation based on state and confidence
+     */
+    static getRecommendation(state, confidence) {
+        if (state === 'RAW') {
+            return 'URGENT: Discover best practices for this area';
+        }
+        if (state === 'LEARNING' && confidence < 0.5) {
+            return 'Needs more improvements to balance anti-patterns';
+        }
+        if (state === 'MATURE' && confidence > 0.8) {
+            return 'Stable - can be trusted for skill injection';
+        }
+        if (state === 'IDEAL') {
+            return 'Perfect - all best practices, no anti-patterns';
+        }
+        return 'Continue learning';
+    }
+
+    /**
+     * Analyze evolution needs and gaps
+     * @param {Array} mistakes
+     * @param {Array} improvements
+     * @param {object} intent
+     * @returns {{signals: Array, missingAreas: Array, nextAction: string}}
+     */
+    static analyzeEvolution(mistakes, improvements, intent) {
+        const signals = [];
+        const missingAreas = [];
+
+        // Signal 1: Many mistakes, few solutions
+        if (mistakes.length > improvements.length * 2) {
+            signals.push({
+                type: 'SUGGEST_IMPROVEMENT_DISCOVERY',
+                priority: 'HIGH',
+                reason: `${mistakes.length} anti-patterns but only ${improvements.length} solution(s)`,
+            });
+        }
+
+        // Signal 2: Uncovered tags
+        const mistakeTags = new Set(mistakes.flatMap(m => m.tags || []));
+        const improvementTags = new Set(improvements.flatMap(i => i.tags || []));
+        const uncoveredTags = [...mistakeTags].filter(tag => !improvementTags.has(tag));
+
+        uncoveredTags.forEach(tag => {
+            missingAreas.push({
+                area: tag,
+                reason: 'Anti-patterns detected but no best practice documented',
+                mistakeCount: mistakes.filter(m => m.tags && m.tags.includes(tag)).length,
+            });
+        });
+
+        // Signal 3: High-hit mistakes without solution
+        mistakes.forEach(m => {
+            if ((m.hitCount || 0) > 10 && !this.hasRelatedImprovement(m, improvements)) {
+                signals.push({
+                    type: 'HOT_MISTAKE_NEEDS_SOLUTION',
+                    priority: 'CRITICAL',
+                    mistake: m.id,
+                    reason: `${m.title} hit ${m.hitCount} times but no solution documented`,
+                });
+
+                missingAreas.push({
+                    area: `solution-for-${m.id}`,
+                    reason: 'Frequently violated anti-pattern needs best practice',
+                    hitCount: m.hitCount,
+                });
+            }
+        });
+
+        // Signal 4: Intent under-served
+        if (intent && intent.strength > 0.7) {
+            const coverageScore = improvements.length / (mistakes.length + improvements.length);
+            if (coverageScore < 0.5) {
+                signals.push({
+                    type: 'INTENT_UNDER_SERVED',
+                    priority: 'MEDIUM',
+                    reason: `Intent "${intent.goal}" is clear but solutions are scarce`,
+                });
+            }
+        }
+
+        return {
+            signals,
+            missingAreas,
+            nextAction: this.determineNextAction(signals),
+        };
+    }
+
+    /**
+     * Check if mistake has related improvement
+     */
+    static hasRelatedImprovement(mistake, improvements) {
+        return improvements.some(i =>
+            i.tags && mistake.tags && i.tags.some(tag => mistake.tags.includes(tag))
+        );
+    }
+
+    /**
+     * Determine next action from signals
+     */
+    static determineNextAction(signals) {
+        if (signals.some(s => s.priority === 'CRITICAL')) {
+            return 'Document solution for high-frequency violations immediately';
+        }
+        if (signals.some(s => s.type === 'SUGGEST_IMPROVEMENT_DISCOVERY')) {
+            return 'Research and document best practices in underserved areas';
+        }
+        return 'Continue normal learning';
+    }
+
+    /**
+     * Format tag as title
+     */
+    static formatTagAsTitle(tag) {
+        return tag
+            .split('-')
+            .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+            .join(' ');
+    }
+}

package/packages/cli/src/core/learning/index.js

@@ -0,0 +1,12 @@
+/**
+ * Learning Module - Core Domain
+ * 
+ * Business logic for lesson management and cognitive enhancements.
+ * 
+ * Exported:
+ * - CognitiveEnhancer: Transform raw lessons to cognitive lessons
+ * - LessonSynthesizer: Group and synthesize lessons
+ */
+
+export { CognitiveEnhancer } from './cognitive-enhancer.js';
+export { LessonSynthesizer } from './lesson-synthesizer.js';

package/packages/cli/src/core/learning/lesson-synthesizer.js

@@ -0,0 +1,83 @@
+/**
+ * LessonSynthesizer - Core Business Logic
+ * 
+ * Synthesizes cognitive lessons from raw mistakes and improvements.
+ * Groups by tag, applies cognitive enhancements, and sorts by maturity.
+ * 
+ * Pure function - no side effects.
+ */
+
+import { CognitiveEnhancer } from './cognitive-enhancer.js';
+
+export class LessonSynthesizer {
+    /**
+     * Synthesize cognitive lessons from mistakes and improvements
+     * @param {Array} mistakes - Raw mistake data
+     * @param {Array} improvements - Raw improvement data
+     * @returns {Array} Cognitive lesson units
+     */
+    static synthesize(mistakes, improvements) {
+        // Group by tag
+        const groups = new Map();
+
+        // Add mistakes to groups
+        mistakes.forEach(m => {
+            const tags = m.tags || ['uncategorized'];
+            tags.forEach(tag => {
+                if (!groups.has(tag)) {
+                    groups.set(tag, { mistakes: [], improvements: [] });
+                }
+                groups.get(tag).mistakes.push(m);
+            });
+        });
+
+        // Add improvements to groups
+        improvements.forEach(i => {
+            const tags = i.tags || ['uncategorized'];
+            tags.forEach(tag => {
+                if (!groups.has(tag)) {
+                    groups.set(tag, { mistakes: [], improvements: [] });
+                }
+                groups.get(tag).improvements.push(i);
+            });
+        });
+
+        // Build Cognitive Lessons
+        const lessons = [];
+        let lessonId = 1;
+
+        groups.forEach((group, tag) => {
+            const allTags = [tag, ...group.mistakes.flatMap(m => m.tags || [])];
+            const intent = CognitiveEnhancer.inferIntent(allTags);
+            const maturity = CognitiveEnhancer.calculateMaturity(group.mistakes, group.improvements);
+            const evolution = CognitiveEnhancer.analyzeEvolution(group.mistakes, group.improvements, intent);
+
+            lessons.push({
+                id: `LESSON-${String(lessonId++).padStart(3, '0')}`,
+                title: CognitiveEnhancer.formatTagAsTitle(tag),
+                tag,
+                intent,
+                mistakes: group.mistakes,
+                improvements: group.improvements,
+                maturity,
+                evolution,
+            });
+        });
+
+        // Sort by maturity (MATURE first, RAW last)
+        return this.sortByMaturity(lessons);
+    }
+
+    /**
+     * Sort lessons by maturity state and confidence
+     */
+    static sortByMaturity(lessons) {
+        const stateOrder = { 'IDEAL': 0, 'MATURE': 1, 'LEARNING': 2, 'RAW': 3 };
+
+        return lessons.sort((a, b) => {
+            const stateCompare = stateOrder[a.maturity.state] - stateOrder[b.maturity.state];
+            if (stateCompare !== 0) return stateCompare;
+            return b.maturity.confidence - a.maturity.confidence; // Higher confidence first
+        });
+    }
+}

package/packages/cli/src/core/scanning/index.js

@@ -0,0 +1,14 @@
+/**
+ * Scanning Module - Core Domain
+ * 
+ * Business logic for code scanning and violation detection.
+ * 
+ * Exported:
+ * - FileScanner: Scan files for pattern violations
+ * - PatternMatcher: Match patterns against code
+ * - ViolationTracker: Track violation statistics
+ */
+
+export { FileScanner } from './file-scanner.js';
+export { PatternMatcher } from './pattern-matcher.js';
+export { ViolationTracker } from './violation-tracker.js';

package/packages/cli/src/data/index.js

@@ -0,0 +1,13 @@
+/**
+ * Data Layer
+ * 
+ * Data access layer with repositories and storage adapters.
+ * Implements persistence interfaces defined in core.
+ * 
+ * Exported:
+ * - Repositories: LessonRepository, SignalRepository, SettingsRepository
+ * - Storage: FileStorage, YamlStorage, JsonStorage
+ */
+
+export * from './repositories/index.js';
+export * from './storage/index.js';

package/packages/cli/src/data/repositories/index.js

@@ -0,0 +1,8 @@
+/**
+ * Repositories - Data Access Layer
+ * 
+ * Repository pattern for domain objects.
+ */
+
+export { SignalRepository } from './signal-repository.js';
+export { LessonRepository } from './lesson-repository.js';

package/packages/cli/src/data/repositories/lesson-repository.js

@@ -0,0 +1,130 @@
+/**
+ * LessonRepository - Data Access Layer
+ * 
+ * Manages persistence of mistakes and improvements.
+ * Provides CRUD operations with YAML storage.
+ */
+
+export class LessonRepository {
+    constructor(storage) {
+        this.storage = storage;
+    }
+
+    /**
+     * Load mistakes from storage
+     * @returns {Promise<{version: number, mistakes: Array}>}
+     */
+    async loadMistakes() {
+        try {
+            const data = await this.storage.read('mistakes');
+            return data || { version: 4.0, mistakes: [] };
+        } catch (error) {
+            console.error('Error loading mistakes:', error.message);
+            return { version: 4.0, mistakes: [] };
+        }
+    }
+
+    /**
+     * Load improvements from storage
+     * @returns {Promise<{version: number, improvements: Array}>}
+     */
+    async loadImprovements() {
+        try {
+            const data = await this.storage.read('improvements');
+            return data || { version: 4.0, improvements: [] };
+        } catch (error) {
+            console.error('Error loading improvements:', error.message);
+            return { version: 4.0, improvements: [] };
+        }
+    }
+
+    /**
+     * Save mistakes to storage
+     * @param {object} data - {version, mistakes}
+     */
+    async saveMistakes(data) {
+        await this.storage.write('mistakes', data);
+    }
+
+    /**
+     * Save improvements to storage
+     * @param {object} data - {version, improvements}
+     */
+    async saveImprovements(data) {
+        await this.storage.write('improvements', data);
+    }
+
+    /**
+     * Load legacy lessons.yaml (v1-v3 format)
+     * @returns {Promise<{version: number, lessons: Array}>}
+     */
+    async loadLegacyLessons() {
+        try {
+            const data = await this.storage.read('lessons');
+            if (!data) {
+                // Initialize if doesn't exist
+                const initial = { lessons: [], version: 1 };
+                await this.storage.write('lessons', initial);
+                return initial;
+            }
+            return data;
+        } catch (error) {
+            console.error('Error loading legacy lessons:', error.message);
+            return { lessons: [], version: 1 };
+        }
+    }
+
+    /**
+     * Save legacy lessons.yaml
+     * @param {object} data - {version, lessons}
+     */
+    async saveLegacyLessons(data) {
+        await this.storage.write('lessons', data);
+    }
+
+    /**
+     * Add a lesson to legacy format
+     * @param {object} lesson - Lesson object
+     */
+    async addLegacyLesson(lesson) {
+        const db = await this.loadLegacyLessons();
+        db.lessons.push(lesson);
+        await this.saveLegacyLessons(db);
+        return lesson;
+    }
+
+    /**
+     * Remove a lesson from legacy format
+     * @param {string} lessonId
+     */
+    async removeLegacyLesson(lessonId) {
+        const db = await this.loadLegacyLessons();
+        const idx = db.lessons.findIndex(l => l.id === lessonId.toUpperCase());
+
+        if (idx === -1) {
+            throw new Error(`Lesson not found: ${lessonId}`);
+        }
+
+        const removed = db.lessons.splice(idx, 1)[0];
+        await this.saveLegacyLessons(db);
+        return removed;
+    }
+
+    /**
+     * Find lesson by ID in legacy format
+     * @param {string} lessonId
+     */
+    async findLegacyLessonById(lessonId) {
+        const db = await this.loadLegacyLessons();
+        return db.lessons.find(l => l.id === lessonId.toUpperCase());
+    }
+
+    /**
+     * Find lessons by category in legacy format
+     * @param {string} category
+     */
+    async findLegacyLessonsByCategory(category) {
+        const db = await this.loadLegacyLessons();
+        return db.lessons.filter(l => l.category === category);
+    }
+}