claude-flow 3.25.6 → 3.26.1

package/v3/@claude-flow/guidance/dist/optimizer.d.ts

@@ -1,104 +0,0 @@
-/**
- * Optimizer Loop
- *
- * Weekly loop that edits guidance like code:
- * 1. Rank top violations by frequency and cost
- * 2. For the top 3, propose one rule change each
- * 3. Run the fixed task suite with and without the change
- * 4. Promote only if risk does not increase and rework decreases
- * 5. Record the decision in an ADR note
- *
- * Promotion rule: Local rules that win twice become root rules.
- *
- * @module @claude-flow/guidance/optimizer
- */
-import type { PolicyBundle, ViolationRanking, RuleChange, ABTestResult, OptimizationMetrics, RuleADR } from './types.js';
-import type { RunLedger } from './ledger.js';
-export interface OptimizerConfig {
-    /** Number of top violations to address per cycle */
-    topViolationsPerCycle: number;
-    /** Minimum events required before optimization */
-    minEventsForOptimization: number;
-    /** Required improvement threshold for promotion (0-1) */
-    improvementThreshold: number;
-    /** Maximum risk increase tolerance (0-1) */
-    maxRiskIncrease: number;
-    /** Number of consecutive wins needed for promotion to root */
-    promotionWins: number;
-    /** ADR storage path */
-    adrPath: string;
-}
-export declare class OptimizerLoop {
-    private config;
-    private proposedChanges;
-    private testResults;
-    private adrs;
-    private promotionTracker;
-    private lastOptimizationRun;
-    constructor(config?: Partial<OptimizerConfig>);
-    /**
-     * Run a full optimization cycle
-     *
-     * Steps:
-     * 1. Rank violations
-     * 2. Propose changes for top N
-     * 3. Evaluate changes against baseline
-     * 4. Promote winners, record ADRs
-     */
-    runCycle(ledger: RunLedger, currentBundle: PolicyBundle): Promise<{
-        rankings: ViolationRanking[];
-        changes: RuleChange[];
-        results: ABTestResult[];
-        adrs: RuleADR[];
-        promoted: string[];
-        demoted: string[];
-    }>;
-    /**
-     * Propose rule changes for top violations
-     */
-    proposeChanges(violations: ViolationRanking[], bundle: PolicyBundle): RuleChange[];
-    /**
-     * Propose modification to an existing rule
-     */
-    private proposeRuleModification;
-    /**
-     * Propose a new rule for unhandled violations
-     */
-    private proposeNewRule;
-    /**
-     * Evaluate a proposed change against baseline metrics
-     */
-    evaluateChange(change: RuleChange, baseline: OptimizationMetrics, ledger: RunLedger): ABTestResult;
-    /**
-     * Heuristic estimation of how a rule change would affect metrics.
-     *
-     * This does NOT run a real A/B test against live traffic — it applies
-     * fixed multipliers per change-type to the baseline numbers.  The
-     * percentages (e.g. 40% for modify, 60% for add) are conservative
-     * estimates, not measured values.  Results should be treated as
-     * directional guidance, not ground truth.
-     */
-    private simulateChangeEffect;
-    /**
-     * Record an ADR for a rule change decision
-     */
-    private recordADR;
-    /**
-     * Find a rule in the policy bundle
-     */
-    private findRule;
-    /**
-     * Apply promoted changes to a policy bundle
-     */
-    applyPromotions(bundle: PolicyBundle, promoted: string[], changes: RuleChange[]): PolicyBundle;
-    get lastRun(): number | null;
-    getADRs(): RuleADR[];
-    getProposedChanges(): RuleChange[];
-    getTestResults(): ABTestResult[];
-    getPromotionTracker(): Map<string, number>;
-}
-/**
- * Create an optimizer instance
- */
-export declare function createOptimizer(config?: Partial<OptimizerConfig>): OptimizerLoop;
-//# sourceMappingURL=optimizer.d.ts.map

package/v3/@claude-flow/guidance/dist/optimizer.js

@@ -1,329 +0,0 @@
-/**
- * Optimizer Loop
- *
- * Weekly loop that edits guidance like code:
- * 1. Rank top violations by frequency and cost
- * 2. For the top 3, propose one rule change each
- * 3. Run the fixed task suite with and without the change
- * 4. Promote only if risk does not increase and rework decreases
- * 5. Record the decision in an ADR note
- *
- * Promotion rule: Local rules that win twice become root rules.
- *
- * @module @claude-flow/guidance/optimizer
- */
-import { randomUUID } from 'node:crypto';
-const DEFAULT_CONFIG = {
-    topViolationsPerCycle: 3,
-    minEventsForOptimization: 10,
-    improvementThreshold: 0.1,
-    maxRiskIncrease: 0.05,
-    promotionWins: 2,
-    adrPath: './docs/adrs',
-};
-// ============================================================================
-// Optimizer Loop
-// ============================================================================
-export class OptimizerLoop {
-    config;
-    proposedChanges = [];
-    testResults = [];
-    adrs = [];
-    promotionTracker = new Map(); // ruleId -> win count
-    lastOptimizationRun = null;
-    constructor(config = {}) {
-        this.config = { ...DEFAULT_CONFIG, ...config };
-    }
-    /**
-     * Run a full optimization cycle
-     *
-     * Steps:
-     * 1. Rank violations
-     * 2. Propose changes for top N
-     * 3. Evaluate changes against baseline
-     * 4. Promote winners, record ADRs
-     */
-    async runCycle(ledger, currentBundle) {
-        this.lastOptimizationRun = Date.now();
-        // Step 1: Rank violations
-        const rankings = ledger.rankViolations();
-        if (rankings.length === 0) {
-            return { rankings: [], changes: [], results: [], adrs: [], promoted: [], demoted: [] };
-        }
-        // Step 2: Propose changes for top violations
-        const topViolations = rankings.slice(0, this.config.topViolationsPerCycle);
-        const changes = this.proposeChanges(topViolations, currentBundle);
-        this.proposedChanges.push(...changes);
-        // Step 3: Evaluate each change
-        const baselineMetrics = ledger.computeMetrics();
-        const results = [];
-        for (const change of changes) {
-            const result = this.evaluateChange(change, baselineMetrics, ledger);
-            results.push(result);
-            this.testResults.push(result);
-        }
-        // Step 4: Promote winners, record ADRs
-        const promoted = [];
-        const demoted = [];
-        const newAdrs = [];
-        for (const result of results) {
-            const adr = this.recordADR(result);
-            newAdrs.push(adr);
-            this.adrs.push(adr);
-            if (result.shouldPromote) {
-                // Track wins for promotion from local to root
-                const ruleId = result.change.targetRuleId;
-                const wins = (this.promotionTracker.get(ruleId) ?? 0) + 1;
-                this.promotionTracker.set(ruleId, wins);
-                if (wins >= this.config.promotionWins) {
-                    promoted.push(ruleId);
-                }
-            }
-            else {
-                // Demote if change failed
-                const ruleId = result.change.targetRuleId;
-                this.promotionTracker.set(ruleId, 0);
-                if (result.change.changeType === 'promote') {
-                    demoted.push(ruleId);
-                }
-            }
-        }
-        return {
-            rankings,
-            changes,
-            results,
-            adrs: newAdrs,
-            promoted,
-            demoted,
-        };
-    }
-    /**
-     * Propose rule changes for top violations
-     */
-    proposeChanges(violations, bundle) {
-        const changes = [];
-        for (const violation of violations) {
-            // Find the rule
-            const rule = this.findRule(violation.ruleId, bundle);
-            if (rule) {
-                // Existing rule that's being violated too often
-                changes.push(this.proposeRuleModification(rule, violation));
-            }
-            else {
-                // No rule exists for this violation type - propose new rule
-                changes.push(this.proposeNewRule(violation));
-            }
-        }
-        return changes;
-    }
-    /**
-     * Propose modification to an existing rule
-     */
-    proposeRuleModification(rule, violation) {
-        // Analyze violation pattern to suggest improvement
-        let proposedText = rule.text;
-        let changeType = 'modify';
-        if (violation.frequency > 5) {
-            // Rule is violated frequently - make it more specific or add enforcement
-            proposedText = `${rule.text}. This rule requires automated enforcement via gates.`;
-        }
-        else if (violation.cost > 50) {
-            // Violations are expensive - elevate priority
-            proposedText = `[HIGH PRIORITY] ${rule.text}. Violations of this rule are costly (avg ${violation.cost.toFixed(0)} rework lines).`;
-        }
-        // If rule is local and performing well, propose promotion
-        if (rule.source === 'local') {
-            const wins = this.promotionTracker.get(rule.id) ?? 0;
-            if (wins >= this.config.promotionWins - 1) {
-                changeType = 'promote';
-            }
-        }
-        return {
-            changeId: randomUUID(),
-            targetRuleId: rule.id,
-            changeType,
-            originalText: rule.text,
-            proposedText,
-            rationale: `Violated ${violation.frequency} times with avg cost of ${violation.cost.toFixed(0)} rework lines (score: ${violation.score.toFixed(1)})`,
-            triggeringViolation: violation,
-        };
-    }
-    /**
-     * Propose a new rule for unhandled violations
-     */
-    proposeNewRule(violation) {
-        return {
-            changeId: randomUUID(),
-            targetRuleId: violation.ruleId,
-            changeType: 'add',
-            proposedText: `[${violation.ruleId}] Enforce compliance for pattern "${violation.ruleId}". Auto-generated from ${violation.frequency} violations with avg cost ${violation.cost.toFixed(0)} lines.`,
-            rationale: `No existing rule covers violations classified as "${violation.ruleId}". ${violation.frequency} occurrences detected.`,
-            triggeringViolation: violation,
-        };
-    }
-    /**
-     * Evaluate a proposed change against baseline metrics
-     */
-    evaluateChange(change, baseline, ledger) {
-        // Get events that would be affected by this rule
-        const events = ledger.getEvents();
-        const affectedEvents = events.filter(e => e.violations.some(v => v.ruleId === change.targetRuleId) ||
-            e.retrievedRuleIds.includes(change.targetRuleId));
-        // Compute "candidate" metrics: simulate the effect of the change
-        // For now, estimate based on the violation pattern
-        const candidateMetrics = this.simulateChangeEffect(change, baseline, affectedEvents.length);
-        // Decision logic:
-        // 1. Risk must not increase (violation rate stays same or drops)
-        // 2. Rework must decrease
-        const riskIncrease = candidateMetrics.violationRate - baseline.violationRate;
-        const reworkDecrease = baseline.reworkLines - candidateMetrics.reworkLines;
-        const shouldPromote = riskIncrease <= this.config.maxRiskIncrease &&
-            reworkDecrease > 0 &&
-            (reworkDecrease / Math.max(baseline.reworkLines, 1)) >= this.config.improvementThreshold;
-        const reason = shouldPromote
-            ? `Rework decreased by ${reworkDecrease.toFixed(1)} lines (${((reworkDecrease / Math.max(baseline.reworkLines, 1)) * 100).toFixed(1)}%) without increasing risk`
-            : riskIncrease > this.config.maxRiskIncrease
-                ? `Risk increased by ${riskIncrease.toFixed(2)} (exceeds threshold ${this.config.maxRiskIncrease})`
-                : `Insufficient rework improvement (${((reworkDecrease / Math.max(baseline.reworkLines, 1)) * 100).toFixed(1)}% < ${(this.config.improvementThreshold * 100).toFixed(0)}% required)`;
-        return {
-            change,
-            baseline,
-            candidate: candidateMetrics,
-            shouldPromote,
-            reason,
-        };
-    }
-    /**
-     * Heuristic estimation of how a rule change would affect metrics.
-     *
-     * This does NOT run a real A/B test against live traffic — it applies
-     * fixed multipliers per change-type to the baseline numbers.  The
-     * percentages (e.g. 40% for modify, 60% for add) are conservative
-     * estimates, not measured values.  Results should be treated as
-     * directional guidance, not ground truth.
-     */
-    simulateChangeEffect(change, baseline, affectedEventCount) {
-        const affectedRatio = baseline.taskCount > 0
-            ? affectedEventCount / baseline.taskCount
-            : 0;
-        // Conservative estimates based on change type
-        let violationReduction = 0;
-        let reworkReduction = 0;
-        switch (change.changeType) {
-            case 'modify':
-                // Modifying a rule typically reduces its specific violations by 30-50%
-                violationReduction = affectedRatio * 0.4;
-                reworkReduction = change.triggeringViolation.cost * 0.3;
-                break;
-            case 'add':
-                // Adding a new rule typically catches 50-70% of unhandled violations
-                violationReduction = affectedRatio * 0.6;
-                reworkReduction = change.triggeringViolation.cost * 0.5;
-                break;
-            case 'promote':
-                // Promoting to root means it's always active, catching 80%+
-                violationReduction = affectedRatio * 0.8;
-                reworkReduction = change.triggeringViolation.cost * 0.6;
-                break;
-            case 'remove':
-                // Removing a bad rule might increase violations temporarily
-                violationReduction = -affectedRatio * 0.2;
-                reworkReduction = -change.triggeringViolation.cost * 0.1;
-                break;
-            default:
-                break;
-        }
-        return {
-            violationRate: Math.max(0, baseline.violationRate * (1 - violationReduction)),
-            selfCorrectionRate: Math.min(1, baseline.selfCorrectionRate + violationReduction * 0.1),
-            reworkLines: Math.max(0, baseline.reworkLines - reworkReduction),
-            clarifyingQuestions: baseline.clarifyingQuestions,
-            taskCount: baseline.taskCount,
-        };
-    }
-    /**
-     * Record an ADR for a rule change decision
-     */
-    recordADR(result) {
-        const adrNumber = this.adrs.length + 1;
-        return {
-            number: adrNumber,
-            title: `${result.shouldPromote ? 'Promote' : 'Reject'}: ${result.change.changeType} rule ${result.change.targetRuleId}`,
-            decision: result.shouldPromote
-                ? `Apply ${result.change.changeType} to rule ${result.change.targetRuleId}`
-                : `Reject proposed ${result.change.changeType} for rule ${result.change.targetRuleId}`,
-            rationale: result.reason,
-            change: result.change,
-            testResult: result,
-            date: Date.now(),
-        };
-    }
-    /**
-     * Find a rule in the policy bundle
-     */
-    findRule(ruleId, bundle) {
-        const constitutionRule = bundle.constitution.rules.find(r => r.id === ruleId);
-        if (constitutionRule)
-            return constitutionRule;
-        const shardRule = bundle.shards.find(s => s.rule.id === ruleId);
-        return shardRule?.rule;
-    }
-    /**
-     * Apply promoted changes to a policy bundle
-     */
-    applyPromotions(bundle, promoted, changes) {
-        // Clone the bundle
-        const newConstitution = { ...bundle.constitution, rules: [...bundle.constitution.rules] };
-        const newShards = [...bundle.shards];
-        for (const ruleId of promoted) {
-            const change = changes.find(c => c.targetRuleId === ruleId);
-            if (!change)
-                continue;
-            // Find the shard to promote
-            const shardIdx = newShards.findIndex(s => s.rule.id === ruleId);
-            if (shardIdx >= 0) {
-                const shard = newShards[shardIdx];
-                const promotedRule = {
-                    ...shard.rule,
-                    source: 'root',
-                    isConstitution: true,
-                    priority: shard.rule.priority + 100,
-                    text: change.proposedText || shard.rule.text,
-                    updatedAt: Date.now(),
-                };
-                // Add to constitution
-                newConstitution.rules.push(promotedRule);
-                // Remove from shards
-                newShards.splice(shardIdx, 1);
-            }
-        }
-        return {
-            constitution: newConstitution,
-            shards: newShards,
-            manifest: bundle.manifest, // Manifest would need recompilation
-        };
-    }
-    // ===== Getters =====
-    get lastRun() {
-        return this.lastOptimizationRun;
-    }
-    getADRs() {
-        return [...this.adrs];
-    }
-    getProposedChanges() {
-        return [...this.proposedChanges];
-    }
-    getTestResults() {
-        return [...this.testResults];
-    }
-    getPromotionTracker() {
-        return new Map(this.promotionTracker);
-    }
-}
-/**
- * Create an optimizer instance
- */
-export function createOptimizer(config) {
-    return new OptimizerLoop(config);
-}
-//# sourceMappingURL=optimizer.js.map

package/v3/@claude-flow/guidance/dist/persistence.d.ts

@@ -1,189 +0,0 @@
-/**
- * Ledger Persistence Layer
- *
- * Connects the in-memory RunLedger to durable file-based storage using
- * newline-delimited JSON (NDJSON). Provides append-only event logging,
- * compaction, and lock-based concurrent access prevention.
- *
- * Storage layout:
- *   {storagePath}/events.ndjson  - Newline-delimited JSON events
- *   {storagePath}/index.json     - Metadata index (counts, timestamps, task IDs)
- *   {storagePath}/.lock          - Lock file for concurrent access prevention
- *
- * @module @claude-flow/guidance/persistence
- */
-import { RunLedger } from './ledger.js';
-import type { RunEvent } from './types.js';
-/**
- * Configuration for the persistent ledger
- */
-export interface PersistenceConfig {
-    /** Directory path for storage files (default: '.claude-flow/guidance') */
-    storagePath: string;
-    /** Maximum events to keep; oldest evicted on compact (default: 10000) */
-    maxEvents: number;
-    /** How often to compact/vacuum in milliseconds (default: 1 hour) */
-    compactIntervalMs: number;
-    /** Enable write-ahead logging style (flush after each write) (default: true) */
-    enableWAL: boolean;
-}
-/**
- * Storage statistics
- */
-export interface StorageStats {
-    /** Total number of stored events */
-    eventCount: number;
-    /** Storage size in bytes */
-    storageSizeBytes: number;
-    /** Timestamp of the oldest event (null if empty) */
-    oldestEvent: number | null;
-    /** Timestamp of the newest event (null if empty) */
-    newestEvent: number | null;
-}
-/**
- * Low-level NDJSON-based event storage.
- *
- * Handles file I/O, append-only writes, range reads, compaction,
- * and lock-based concurrent access prevention.
- */
-export declare class EventStore {
-    private readonly eventsPath;
-    private readonly indexPath;
-    private readonly lockPath;
-    private readonly baseDir;
-    private lockHolder;
-    constructor(storagePath: string);
-    /**
-     * Append a single event to the NDJSON file and update the index.
-     */
-    append(event: RunEvent): Promise<void>;
-    /**
-     * Read and parse all events from storage.
-     */
-    readAll(): Promise<RunEvent[]>;
-    /**
-     * Read events within a time range [startTime, endTime].
-     */
-    readRange(startTime: number, endTime: number): Promise<RunEvent[]>;
-    /**
-     * Compact the event store to keep at most `maxEvents` events.
-     * Oldest events are evicted first. Rewrites the NDJSON file atomically.
-     *
-     * @returns The number of evicted events.
-     */
-    compact(maxEvents: number): Promise<number>;
-    /**
-     * Atomically replace all events in storage with the given array.
-     * Rewrites the NDJSON file and rebuilds the index.
-     */
-    writeAll(events: RunEvent[]): Promise<void>;
-    /**
-     * Get storage statistics.
-     */
-    getStats(): Promise<StorageStats>;
-    /**
-     * Acquire a file-based lock for concurrent access prevention.
-     * Throws if the lock is already held by another process.
-     */
-    acquireLock(): Promise<void>;
-    /**
-     * Release the file-based lock.
-     */
-    releaseLock(): Promise<void>;
-    /**
-     * Remove all storage files (events, index, lock).
-     */
-    destroy(): Promise<void>;
-    /**
-     * Ensure the storage directory exists.
-     */
-    private ensureDirectory;
-    /**
-     * Parse an NDJSON string into RunEvent array, skipping blank/invalid lines.
-     */
-    private parseNdjson;
-    /**
-     * Read the index file, returning a default if it does not exist.
-     */
-    private readIndex;
-    /**
-     * Update the index with a new event.
-     */
-    private updateIndex;
-    /**
-     * Rebuild the index from a given set of events.
-     */
-    private rebuildIndex;
-}
-/**
- * A RunLedger subclass that persists events to NDJSON file storage.
- *
- * Extends the in-memory RunLedger with:
- * - Automatic persistence on logEvent()
- * - Load from storage on init via importEvents()
- * - Explicit save()/load() for bulk operations
- * - Compaction to enforce maxEvents limit
- * - Storage statistics
- * - Automatic periodic compaction via interval timer
- */
-export declare class PersistentLedger extends RunLedger {
-    private readonly config;
-    private readonly store;
-    private compactTimer;
-    private initialized;
-    constructor(config?: Partial<PersistenceConfig>);
-    /**
-     * Initialize the persistent ledger: load existing events from storage
-     * and start the compaction timer.
-     */
-    init(): Promise<void>;
-    /**
-     * Override logEvent to also persist the event to storage.
-     */
-    logEvent(event: RunEvent | Omit<RunEvent, 'eventId'>): RunEvent;
-    /**
-     * Override importEvents to also persist imported events to storage.
-     */
-    importEvents(events: RunEvent[]): void;
-    /**
-     * Flush all in-memory events to storage, replacing the storage contents.
-     * This performs a full atomic rewrite of the NDJSON file.
-     */
-    save(): Promise<void>;
-    /**
-     * Restore events from storage into memory.
-     * Clears the in-memory ledger first, then loads all stored events.
-     */
-    load(): Promise<void>;
-    /**
-     * Compact the storage to keep at most maxEvents events.
-     * Also updates the in-memory ledger to match.
-     *
-     * @returns The number of evicted events.
-     */
-    compact(): Promise<number>;
-    /**
-     * Get storage statistics.
-     */
-    getStorageStats(): Promise<StorageStats>;
-    /**
-     * Clean up resources (stop compaction timer, release locks, etc.).
-     */
-    destroy(): Promise<void>;
-    /**
-     * Get the underlying EventStore (for advanced use / testing).
-     */
-    getEventStore(): EventStore;
-    private startCompactTimer;
-    private stopCompactTimer;
-}
-/**
- * Create a PersistentLedger instance. Call `init()` after creation to load
- * existing events from storage.
- */
-export declare function createPersistentLedger(config?: Partial<PersistenceConfig>): PersistentLedger;
-/**
- * Create an EventStore instance for direct low-level storage access.
- */
-export declare function createEventStore(path: string): EventStore;
-//# sourceMappingURL=persistence.d.ts.map