@agentskillkit/agent-skills 1.0.1 → 3.2.2

package/packages/cli/src/README.md

@@ -0,0 +1,367 @@
+# Agent Skill Kit - New Architecture
+
+> **Status:** 🚧 In Progress - Migrating to FAANG-style layered architecture
+
+## Overview
+
+This directory contains the new **layered architecture** for Agent Skill Kit, following FAANG best practices for maintainability, testability, and scalability.
+
+---
+
+## Architecture Principles
+
+### 1. **Layered Architecture** (Clean Architecture)
+```
+┌─────────────────────────────────────┐
+│       Presentation Layer            │  (CLI, UI)
+├─────────────────────────────────────┤
+│       Service Layer                 │  (Orchestration)
+├─────────────────────────────────────┤
+│       Core Domain Layer             │  (Business Logic)
+├─────────────────────────────────────┤
+│       Data Layer                    │  (Persistence)
+├─────────────────────────────────────┤
+│       Infrastructure Layer          │  (Config, DI, Logging)
+└─────────────────────────────────────┘
+```
+
+### 2. **Dependency Rule**
+- **Core** has ZERO external dependencies (pure business logic)
+- **Data** implements interfaces defined in Core
+- **Services** orchestrate Core + Data
+- **Presentation** uses Services
+- **Infrastructure** provides cross-cutting concerns
+
+### 3. **Single Responsibility Principle**
+Each class/module has ONE clear purpose:
+- ✅ `EvolutionSignal` - Represents a signal
+- ✅ `ThresholdChecker` - Checks evolution readiness
+- ✅ `SignalRepository` - Persists signals
+- ✅ `SignalDetector` - Orchestrates signal workflow
+
+---
+
+## Folder Structure
+
+```
+src/
+├── core/                    # Domain Layer (Pure Business Logic)
+│   ├── learning/
+│   │   ├── lesson-manager.js
+│   │   ├── cognitive-enhancer.js
+│   │   ├── lesson-merger.js
+│   │   └── index.js
+│   ├── evolution/           [✅ COMPLETE]
+│   │   ├── evolution-signal.js
+│   │   ├── threshold-checker.js
+│   │   ├── review-gate.js
+│   │   ├── signal-detector.js
+│   │   └── index.js
+│   ├── scanning/
+│   │   ├── file-scanner.js
+│   │   ├── pattern-matcher.js
+│   │   ├── violation-tracker.js
+│   │   └── index.js
+│   └── index.js
+│
+├── services/                # Application Services (Orchestration)
+│   ├── auto-learning-service.js
+│   ├── stats-service.js
+│   ├── backup-service.js
+│   ├── export-service.js
+│   └── index.js
+│
+├── data/                    # Data Access Layer
+│   ├── repositories/        [✅ COMPLETE]
+│   │   ├── signal-repository.js
+│   │   ├── lesson-repository.js
+│   │   ├── settings-repository.js
+│   │   └── index.js
+│   ├── storage/             [✅ COMPLETE]
+│   │   ├── json-storage.js
+│   │   ├── yaml-storage.js
+│   │   ├── file-storage.js
+│   │   └── index.js
+│   └── index.js
+│
+├── presentation/            # Presentation Layer (UI/CLI)
+│   └── cli/
+│       ├── commands/
+│       ├── menus/
+│       └── views/
+│
+├── infrastructure/          # Cross-cutting Concerns
+│   ├── config/
+│   ├── di/                  # Dependency Injection
+│   └── logging/
+│
+└── shared/                  # Shared Utilities
+    ├── utils/
+    └── types/
+```
+
+---
+
+## Migration Status
+
+### ✅ Completed Modules
+
+#### Evolution Module (100%)
+- [x] `EvolutionSignal` - Domain model
+- [x] `ThresholdChecker` - Business rules
+- [x] `ReviewGate` - Decision logic
+- [x] `SignalRepository` - Data access
+- [x] `JsonStorage` - Storage adapter
+- [x] `SignalDetector` - Service orchestration
+
+**Files:** 7 new files, avg 70 lines each
+**Test Status:** ✅ Passing
+
+### 🚧 In Progress
+
+#### Learning Module (0%)
+- [ ] `LessonManager`
+- [ ] `CognitiveEnhancer`
+- [ ] `LessonMerger`
+- [ ] `LessonRepository`
+
+#### Scanning Module (0%)
+- [ ] `FileScanner`
+- [ ] `PatternMatcher`
+- [ ] `ViolationTracker`
+
+---
+
+## How to Use New Architecture
+
+### Example: Using SignalDetector
+
+```javascript
+// 1. Import components
+import { SignalDetector } from './src/core/evolution/signal-detector.js';
+import { SignalRepository } from './src/data/repositories/signal-repository.js';
+import { JsonStorage } from './src/data/storage/json-storage.js';
+import { KNOWLEDGE_DIR } from './lib/config.js';
+
+// 2. Create instances (Dependency Injection)
+const storage = new JsonStorage(KNOWLEDGE_DIR);
+const repository = new SignalRepository(storage);
+const detector = new SignalDetector(repository, { updateThreshold: 10 });
+
+// 3. Use async API
+const stats = await detector.getStats();
+console.log(`Pending: ${stats.pending}`);
+
+const pending = await detector.getPending();
+pending.forEach(signal => {
+    console.log(`${signal.lessonId}: ${signal.reason}`);
+});
+
+// 4. Approve signals
+await detector.approve(signalId);
+```
+
+### Testing with Mocks
+
+```javascript
+import { SignalDetector } from './src/core/evolution/signal-detector.js';
+
+// Create mock repository
+const mockRepo = {
+    findAll: async () => [mockSignal1, mockSignal2],
+    findPending: async () => [mockSignal1],
+    save: async (signal) => signal
+};
+
+// Inject mock
+const detector = new SignalDetector(mockRepo);
+
+// Test easily!
+const pending = await detector.getPending();
+expect(pending).toHaveLength(1);
+```
+
+---
+
+## Benefits of New Architecture
+
+### Before (Flat Structure)
+```javascript
+// lib/evolution-signal.js (343 lines)
+export class EvolutionSignal { ... }
+export class SignalQueue { 
+    constructor() {
+        this.signals = [];
+        this.signalFilePath = path.join(...);  // ❌ Tight coupling
+    }
+    
+    load() {
+        fs.readFileSync(...);  // ❌ Direct filesystem access
+    }
+}
+```
+
+**Problems:**
+- ❌ SignalQueue mixes business logic + persistence
+- ❌ Hard to test (can't mock filesystem)
+- ❌ Tight coupling
+- ❌ Violates Single Responsibility
+
+### After (Layered Architecture)
+```javascript
+// Domain Model (core/evolution/evolution-signal.js)
+export class EvolutionSignal {
+    approve() { this.status = 'approved'; }  // ✅ Pure business logic
+}
+
+// Repository (data/repositories/signal-repository.js)
+export class SignalRepository {
+    constructor(storage) {
+        this.storage = storage;  // ✅ Dependency injection
+    }
+    
+    async findAll() {
+        return this.storage.read('signals');  // ✅ Uses abstraction
+    }
+}
+
+// Storage Adapter (data/storage/json-storage.js)
+export class JsonStorage {
+    async read(key) {
+        return JSON.parse(fs.readFileSync(...));  // ✅ Isolated I/O
+    }
+}
+
+// Service (core/evolution/signal-detector.js)
+export class SignalDetector {
+    constructor(repository) {
+        this.repository = repository;  // ✅ Dependency injection
+    }
+    
+    async approve(id) {
+        const signal = await this.repository.findById(id);
+        signal.approve();  // ✅ Uses domain model
+        await this.repository.save(signal);
+    }
+}
+```
+
+**Benefits:**
+- ✅ Single Responsibility (each class has ONE job)
+- ✅ Easy to test (inject mocks)
+- ✅ Loose coupling (swap storage without touching logic)
+- ✅ Clear ownership (know where each responsibility lives)
+
+---
+
+## Design Patterns Used
+
+### 1. Repository Pattern
+**Purpose:** Separate data access from business logic
+
+**Implementation:**
+- `SignalRepository` for evolution signals
+- `LessonRepository` for lessons
+- All repositories use storage abstraction
+
+### 2. Dependency Injection
+**Purpose:** Enable testability and flexibility
+
+**Implementation:**
+```javascript
+class SignalDetector {
+    constructor(signalRepository, settings) {
+        this.signalRepository = signalRepository;  // Injected!
+        this.settings = settings;
+    }
+}
+```
+
+### 3. Strategy Pattern (Storage)
+**Purpose:** Swap storage implementations
+
+**Implementation:**
+- `JsonStorage` for JSON files
+- `YamlStorage` for YAML files  
+- All implement same interface (`read`, `write`, `delete`)
+
+---
+
+## Testing Strategy
+
+### Unit Tests (Core Layer)
+```javascript
+// Test pure business logic
+describe('ThresholdChecker', () => {
+    it('should detect hitCountThreshold', () => {
+        const lesson = { hitCount: 10 };
+        const result = ThresholdChecker.check(lesson, 10);
+        
+        expect(result.ready).toBe(true);
+        expect(result.reason).toBe('hitCountThreshold');
+    });
+});
+```
+
+### Integration Tests (Service Layer)
+```javascript
+// Test with real repository + mock storage
+describe('SignalDetector', () => {
+    it('should queue signal when threshold reached', async () => {
+        const mockStorage = {
+            read: async () => ({ signals: [] }),
+            write: async () => {}
+        };
+        
+        const repository = new SignalRepository(mockStorage);
+        const detector = new SignalDetector(repository);
+        
+        const result = await detector.queue('LESSON-1', {
+            ready: true,
+            reason: 'hitCountThreshold',
+            confidence: 0.9
+        });
+        
+        expect(result.lessonId).toBe('LESSON-1');
+    });
+});
+```
+
+---
+
+## Migration Guide
+
+See [MIGRATION.md](./MIGRATION.md) for detailed migration instructions.
+
+**Quick Start:**
+1. New code → Use new architecture
+2. Existing code → Gradually migrate
+3. Backward compatibility maintained in `lib/` folder
+
+---
+
+## Next Steps
+
+1. **Complete Learning Module** - Extract from `cognitive-lesson.js`, `learn.js`
+2. **Complete Scanning Module** - Extract from `recall.js`
+3. **Create DI Container** - Centralize dependency management
+4. **Migrate UI Layer** - Extract to `presentation/cli/`
+5. **Full Test Coverage** - Unit + integration tests
+
+---
+
+## Contributing
+
+When adding new features:
+1. **Core logic** → `src/core/`
+2. **Data access** → `src/data/repositories/`
+3. **Orchestration** → `src/services/`
+4. **UI** → `src/presentation/`
+
+**Remember:** Core layer has ZERO dependencies!
+
+---
+
+## Questions?
+
+See [ARCHITECTURE.md](../../../.gemini/antigravity/brain/.../architecture_refactoring_plan.md) for full architecture details.

package/packages/cli/src/core/evolution/evolution-signal.js

@@ -0,0 +1,42 @@
+/**
+ * EvolutionSignal - Domain Model
+ * 
+ * Represents a detected evolution opportunity.
+ * Pure domain object with NO external dependencies.
+ */
+
+export class EvolutionSignal {
+    constructor(lessonId, reason, confidence, metadata = {}) {
+        this.id = `signal_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
+        this.lessonId = lessonId;
+        this.reason = reason; // 'hitCountThreshold', 'patternStable', 'highConfidence'
+        this.confidence = confidence; // 0.0 to 1.0
+        this.status = 'pending'; // 'pending', 'approved', 'rejected', 'executed'
+        this.metadata = metadata; // Additional context
+        this.createdAt = Date.now();
+        this.resolvedAt = null;
+    }
+
+    approve() {
+        this.status = 'approved';
+        this.resolvedAt = Date.now();
+    }
+
+    reject() {
+        this.status = 'rejected';
+        this.resolvedAt = Date.now();
+    }
+
+    execute() {
+        this.status = 'executed';
+        this.resolvedAt = Date.now();
+    }
+
+    isPending() {
+        return this.status === 'pending';
+    }
+
+    isResolved() {
+        return this.status !== 'pending';
+    }
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Evolution Module - Core Domain
+ * 
+ * Business logic for evolution signal detection and management.
+ * 
+ * Exported:
+ * - SignalDetector: Detect evolution opportunities
+ * - SignalQueue: Manage signal lifecycle
+ * - ThresholdChecker: Check if lesson ready for evolution
+ * - ReviewGate: Determine auto vs manual evolution
+ */
+
+export { SignalDetector } from './signal-detector.js';
+export { SignalQueue } from './signal-queue.js';
+export { ThresholdChecker } from './threshold-checker.js';
+export { ReviewGate } from './review-gate.js';
+export { EvolutionSignal } from './evolution-signal.js';

package/packages/cli/src/core/evolution/review-gate.js

@@ -0,0 +1,40 @@
+/**
+ * ReviewGate - Core Business Logic
+ * 
+ * Determines if a signal should auto-evolve or require manual review.
+ * Pure function based on signal confidence and settings.
+ */
+
+export class ReviewGate {
+    /**
+     * Determine if a signal should auto-evolve or require manual review
+     * @param {object} signal - Evolution signal
+     * @param {object} settings - { autoUpdating: boolean, confidenceThreshold: number }
+     * @returns {{ shouldAuto: boolean, reason: string }}
+     */
+    static evaluate(signal, settings = {}) {
+        const { autoUpdating = false, confidenceThreshold = 0.8 } = settings;
+
+        // If auto-updating is disabled, always require review
+        if (!autoUpdating) {
+            return {
+                shouldAuto: false,
+                reason: 'autoUpdatingDisabled'
+            };
+        }
+
+        // If confidence is below threshold, require review
+        if (signal.confidence < confidenceThreshold) {
+            return {
+                shouldAuto: false,
+                reason: 'lowConfidence'
+            };
+        }
+
+        // High confidence + auto-updating enabled = auto-evolve
+        return {
+            shouldAuto: true,
+            reason: 'highConfidenceAutoApproved'
+        };
+    }
+}

package/packages/cli/src/core/evolution/signal-detector.js

@@ -0,0 +1,137 @@
+/**
+ * SignalDetector - Application Service
+ * 
+ * Orchestrates evolution signal detection and queuing.
+ * Coordinates between core business logic and data layer.
+ */
+
+import { EvolutionSignal } from './evolution-signal.js';
+import { ThresholdChecker } from './threshold-checker.js';
+
+export class SignalDetector {
+    constructor(signalRepository, settings = {}) {
+        this.signalRepository = signalRepository;
+        this.settings = settings;
+    }
+
+    /**
+     * Check if lesson is ready for evolution
+     * @param {object} lesson - Lesson to check
+     * @returns {Promise<{ready: boolean, reason?: string, confidence?: number}>}
+     */
+    async check(lesson) {
+        const threshold = this.settings.updateThreshold || 10;
+        return ThresholdChecker.check(lesson, threshold);
+    }
+
+    /**
+     * Queue an evolution signal
+     * @param {string} lessonId
+     * @param {object} checkResult - From check()
+     * @param {object} metadata - Additional context
+     * @returns {Promise<EvolutionSignal|null>}
+     */
+    async queue(lessonId, checkResult, metadata = {}) {
+        if (!checkResult.ready) return null;
+
+        // Create signal
+        const signal = new EvolutionSignal(
+            lessonId,
+            checkResult.reason,
+            checkResult.confidence,
+            metadata
+        );
+
+        // Check for duplicates
+        const existing = await this.signalRepository.findByLesson(lessonId);
+        const duplicate = existing.find(s =>
+            s.isPending() && s.reason === signal.reason
+        );
+
+        if (duplicate) {
+            // Update confidence if higher
+            if (signal.confidence > duplicate.confidence) {
+                duplicate.confidence = signal.confidence;
+                duplicate.metadata = signal.metadata;
+                await this.signalRepository.save(duplicate);
+            }
+            return duplicate;
+        }
+
+        // Save new signal
+        return await this.signalRepository.save(signal);
+    }
+
+    /**
+     * Get all pending signals
+     * @returns {Promise<Array<EvolutionSignal>>}
+     */
+    async getPending() {
+        return await this.signalRepository.findPending();
+    }
+
+    /**
+     * Get signals for a specific lesson
+     * @param {string} lessonId
+     * @returns {Promise<Array<EvolutionSignal>>}
+     */
+    async getByLesson(lessonId) {
+        return await this.signalRepository.findByLesson(lessonId);
+    }
+
+    /**
+     * Approve a signal
+     * @param {string} signalId
+     * @returns {Promise<EvolutionSignal>}
+     */
+    async approve(signalId) {
+        const signal = await this.signalRepository.findById(signalId);
+        if (signal) {
+            signal.approve();
+            await this.signalRepository.save(signal);
+        }
+        return signal;
+    }
+
+    /**
+     * Reject a signal
+     * @param {string} signalId
+     * @returns {Promise<EvolutionSignal>}
+     */
+    async reject(signalId) {
+        const signal = await this.signalRepository.findById(signalId);
+        if (signal) {
+            signal.reject();
+            await this.signalRepository.save(signal);
+        }
+        return signal;
+    }
+
+    /**
+     * Execute a signal
+     * @param {string} signalId
+     * @returns {Promise<EvolutionSignal>}
+     */
+    async execute(signalId) {
+        const signal = await this.signalRepository.findById(signalId);
+        if (signal) {
+            signal.execute();
+            await this.signalRepository.save(signal);
+        }
+        return signal;
+    }
+
+    /**
+     * Get evolution statistics
+     * @returns {Promise<{pending: number, approved: number, rejected: number, executed: number}>}
+     */
+    async getStats() {
+        const all = await this.signalRepository.findAll();
+        return {
+            pending: all.filter(s => s.status === 'pending').length,
+            approved: all.filter(s => s.status === 'approved').length,
+            rejected: all.filter(s => s.status === 'rejected').length,
+            executed: all.filter(s => s.status === 'executed').length
+        };
+    }
+}

package/packages/cli/src/core/evolution/signal-queue.js

@@ -0,0 +1,79 @@
+/**
+ * Signal Queue - Service Facade
+ * 
+ * Backward compatible wrapper around SignalDetector.
+ * Provides singleton-style access for legacy code.
+ */
+
+import { SignalRepository } from '../data/repositories/signal-repository.js';
+import { JsonStorage } from '../data/storage/json-storage.js';
+import { SignalDetector } from './signal-detector.js';
+import path from 'path';
+
+// Lazy initialization
+let _instance = null;
+
+async function getInstance() {
+    if (!_instance) {
+        // Get KNOWLEDGE_DIR from old config
+        const { KNOWLEDGE_DIR } = await import('../../lib/config.js');
+
+        // Create storage and repository
+        const storage = new JsonStorage(KNOWLEDGE_DIR);
+        const repository = new SignalRepository(storage);
+
+        // Create detector
+        _instance = new SignalDetector(repository);
+    }
+    return _instance;
+}
+
+/**
+ * SignalQueue - Facade for backward compatibility
+ * 
+ * Provides same interface as old evolution-signal.js
+ */
+export class SignalQueue {
+    static async add(signal) {
+        const detector = await getInstance();
+        return detector.queue(signal.lessonId, {
+            ready: true,
+            reason: signal.reason,
+            confidence: signal.confidence
+        }, signal.metadata);
+    }
+
+    static async getPending() {
+        const detector = await getInstance();
+        return detector.getPending();
+    }
+
+    static async getByLesson(lessonId) {
+        const detector = await getInstance();
+        return detector.getByLesson(lessonId);
+    }
+
+    static async approve(signalId) {
+        const detector = await getInstance();
+        return detector.approve(signalId);
+    }
+
+    static async reject(signalId) {
+        const detector = await getInstance();
+        return detector.reject(signalId);
+    }
+
+    static async execute(signalId) {
+        const detector = await getInstance();
+        return detector.execute(signalId);
+    }
+
+    static async cleanup() {
+        const detector = await getInstance();
+        const repository = detector.signalRepository;
+        await repository.cleanup();
+    }
+}
+
+// Export singleton instance for compatibility
+export const signalQueue = SignalQueue;