claude-flow 3.28.0 → 3.29.0

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

@@ -0,0 +1,104 @@
+/**
+ * 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

@@ -0,0 +1,329 @@
+/**
+ * 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

@@ -0,0 +1,189 @@
+/**
+ * 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