claude-flow 3.25.6 → 3.26.0

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

@@ -1,321 +0,0 @@
-/**
- * @claude-flow/guidance - Guidance Control Plane
- *
- * Sits beside Claude Code (not inside it) to:
- * 1. Compile CLAUDE.md into constitution + shards + manifest
- * 2. Retrieve task-relevant shards at runtime via intent classification
- * 3. Enforce non-negotiables through hook gates
- * 4. Log every run to a ledger with evaluators
- * 5. Evolve the rule set through an optimizer loop
- *
- * Architecture:
- * - Root CLAUDE.md → Repo constitution (rare changes)
- * - CLAUDE.local.md → Overlay / experiment sandbox (frequent changes)
- * - Optimizer → Promotes winning local rules to root
- *
- * Integration with Claude Code:
- * - Headless mode (claude -p --output-format json) for automated testing
- * - Hook system for enforcement gates
- * - RuVector/HNSW for semantic shard retrieval
- *
- * @module @claude-flow/guidance
- */
-import { readFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-// Core components
-import { createCompiler } from './compiler.js';
-import { createRetriever } from './retriever.js';
-import { createGates } from './gates.js';
-import { createLedger } from './ledger.js';
-import { createOptimizer } from './optimizer.js';
-import { createHeadlessRunner } from './headless.js';
-// Re-export components
-export { GuidanceCompiler, createCompiler } from './compiler.js';
-export { ShardRetriever, createRetriever, HashEmbeddingProvider } from './retriever.js';
-export { EnforcementGates, createGates } from './gates.js';
-export { GuidanceHookProvider, createGuidanceHooks, gateResultsToHookResult, } from './hooks.js';
-export { RunLedger, createLedger, TestsPassEvaluator, ForbiddenCommandEvaluator, ForbiddenDependencyEvaluator, ViolationRateEvaluator, DiffQualityEvaluator, } from './ledger.js';
-export { OptimizerLoop, createOptimizer } from './optimizer.js';
-export { PersistentLedger, EventStore, createPersistentLedger, createEventStore, } from './persistence.js';
-export { HeadlessRunner, createHeadlessRunner, ProcessExecutor, createComplianceSuite, } from './headless.js';
-export { DeterministicToolGateway, createToolGateway } from './gateway.js';
-export { ArtifactLedger, createArtifactLedger } from './artifacts.js';
-export { EvolutionPipeline, createEvolutionPipeline } from './evolution.js';
-export { ManifestValidator, ConformanceSuite, createManifestValidator, createConformanceSuite, } from './manifest-validator.js';
-export { ProofChain, createProofChain } from './proof.js';
-export { MemoryWriteGate, createMemoryWriteGate, createMemoryEntry, } from './memory-gate.js';
-export { CoherenceScheduler, EconomicGovernor, createCoherenceScheduler, createEconomicGovernor, } from './coherence.js';
-export { CapabilityAlgebra, createCapabilityAlgebra } from './capabilities.js';
-export { SimulatedRuntime, MemoryClerkCell, ConformanceRunner, createMemoryClerkCell, createConformanceRunner, } from './conformance-kit.js';
-export { RuvBotGuidanceBridge, AIDefenceGate, RuvBotMemoryAdapter, createRuvBotBridge, createAIDefenceGate, createRuvBotMemoryAdapter, } from './ruvbot-integration.js';
-export { MetaGovernor, createMetaGovernor } from './meta-governance.js';
-export { ThreatDetector, CollusionDetector, MemoryQuorum, createThreatDetector, createCollusionDetector, createMemoryQuorum, } from './adversarial.js';
-export { ContinueGate, createContinueGate } from './continue-gate.js';
-// WASM Kernel exports
-export { getKernel, isWasmAvailable, resetKernel, } from './wasm-kernel.js';
-export { generateClaudeMd, generateClaudeLocalMd, generateSkillMd, generateAgentMd, generateAgentIndex, scaffold, } from './generators.js';
-export { analyze, benchmark, autoOptimize, optimizeForSize, headlessBenchmark, validateEffect, abBenchmark, getDefaultABTasks, formatReport, formatBenchmark, } from './analyzer.js';
-export { TrustAccumulator, TrustLedger as TrustScoreLedger, TrustSystem, getTrustBasedRateLimit, createTrustAccumulator, createTrustSystem, } from './trust.js';
-export { TruthAnchorStore, TruthResolver, createTruthAnchorStore, createTruthResolver, } from './truth-anchors.js';
-export { UncertaintyLedger, UncertaintyAggregator, createUncertaintyLedger, createUncertaintyAggregator, } from './uncertainty.js';
-export { TemporalStore, TemporalReasoner, createTemporalStore, createTemporalReasoner, } from './temporal.js';
-export { AuthorityGate, IrreversibilityClassifier, createAuthorityGate, createIrreversibilityClassifier, isHigherAuthority, getAuthorityHierarchy, } from './authority.js';
-// ============================================================================
-// Default Configuration
-// ============================================================================
-const DEFAULT_CONFIG = {
-    rootGuidancePath: './CLAUDE.md',
-    localGuidancePath: './CLAUDE.local.md',
-    gates: {},
-    maxShardsPerTask: 5,
-    optimizationCycleDays: 7,
-    dataDir: './.claude-flow/guidance',
-    headlessMode: false,
-};
-// ============================================================================
-// Guidance Control Plane
-// ============================================================================
-/**
- * The main Guidance Control Plane
- *
- * Orchestrates all components:
- * - Compiler: CLAUDE.md → PolicyBundle
- * - Retriever: PolicyBundle → task-relevant shards
- * - Gates: enforcement hooks
- * - Ledger: run logging + evaluation
- * - Optimizer: rule evolution
- * - Headless: automated testing
- */
-export class GuidanceControlPlane {
-    config;
-    compiler;
-    retriever;
-    gates;
-    ledger;
-    optimizer;
-    headless = null;
-    bundle = null;
-    initialized = false;
-    constructor(config = {}) {
-        this.config = { ...DEFAULT_CONFIG, ...config };
-        this.compiler = createCompiler();
-        this.retriever = createRetriever();
-        this.gates = createGates(this.config.gates);
-        this.ledger = createLedger();
-        this.optimizer = createOptimizer();
-    }
-    /**
-     * Initialize the control plane
-     *
-     * 1. Read and compile guidance files
-     * 2. Load shards into retriever
-     * 3. Configure gates
-     * 4. Set up headless runner if enabled
-     */
-    async initialize() {
-        if (this.initialized)
-            return;
-        // Step 1: Read guidance files
-        const rootContent = await this.readGuidanceFile(this.config.rootGuidancePath);
-        const localContent = this.config.localGuidancePath
-            ? await this.readGuidanceFile(this.config.localGuidancePath)
-            : undefined;
-        if (!rootContent) {
-            throw new Error(`Root guidance file not found: ${this.config.rootGuidancePath}`);
-        }
-        // Step 2: Compile
-        this.bundle = this.compiler.compile(rootContent, localContent ?? undefined);
-        // Step 3: Load into retriever
-        await this.retriever.loadBundle(this.bundle);
-        // Step 4: Set active rules on gates
-        const allRules = [
-            ...this.bundle.constitution.rules,
-            ...this.bundle.shards.map(s => s.rule),
-        ];
-        this.gates.setActiveRules(allRules);
-        // Step 5: Set up headless runner if enabled
-        if (this.config.headlessMode) {
-            this.headless = createHeadlessRunner(undefined, this.ledger, this.bundle.constitution.hash);
-        }
-        this.initialized = true;
-    }
-    /**
-     * Compile guidance files (can be called independently)
-     */
-    async compile(rootContent, localContent) {
-        this.bundle = this.compiler.compile(rootContent, localContent);
-        await this.retriever.loadBundle(this.bundle);
-        const allRules = [
-            ...this.bundle.constitution.rules,
-            ...this.bundle.shards.map(s => s.rule),
-        ];
-        this.gates.setActiveRules(allRules);
-        // Mark as initialized since we have a valid bundle
-        this.initialized = true;
-        return this.bundle;
-    }
-    /**
-     * Retrieve relevant guidance for a task
-     *
-     * This is the main entry point called at task start.
-     * Returns the constitution + relevant shards.
-     */
-    async retrieveForTask(request) {
-        this.ensureInitialized();
-        return this.retriever.retrieve({
-            ...request,
-            maxShards: request.maxShards ?? this.config.maxShardsPerTask,
-        });
-    }
-    /**
-     * Evaluate a command through enforcement gates
-     */
-    evaluateCommand(command) {
-        return this.gates.evaluateCommand(command);
-    }
-    /**
-     * Evaluate a tool use through enforcement gates
-     */
-    evaluateToolUse(toolName, params) {
-        return this.gates.evaluateToolUse(toolName, params);
-    }
-    /**
-     * Evaluate a file edit through enforcement gates
-     */
-    evaluateEdit(filePath, content, diffLines) {
-        return this.gates.evaluateEdit(filePath, content, diffLines);
-    }
-    /**
-     * Start a run event for tracking
-     */
-    startRun(taskId, intent) {
-        this.ensureInitialized();
-        const event = this.ledger.createEvent(taskId, intent, this.bundle?.constitution.hash ?? 'unknown');
-        return event;
-    }
-    /**
-     * Record a violation during a run
-     */
-    recordViolation(event, violation) {
-        event.violations.push(violation);
-    }
-    /**
-     * Finalize a run and evaluate it
-     */
-    async finalizeRun(event) {
-        this.ledger.finalizeEvent(event);
-        return this.ledger.evaluate(event);
-    }
-    /**
-     * Run the optimization cycle
-     */
-    async optimize() {
-        this.ensureInitialized();
-        if (this.ledger.eventCount < 10) {
-            return { promoted: [], demoted: [], adrsCreated: 0 };
-        }
-        const result = await this.optimizer.runCycle(this.ledger, this.bundle);
-        // Apply promotions
-        if (result.promoted.length > 0) {
-            this.bundle = this.optimizer.applyPromotions(this.bundle, result.promoted, result.changes);
-            await this.retriever.loadBundle(this.bundle);
-        }
-        return {
-            promoted: result.promoted,
-            demoted: result.demoted,
-            adrsCreated: result.adrs.length,
-        };
-    }
-    /**
-     * Get control plane status
-     */
-    getStatus() {
-        return {
-            initialized: this.initialized,
-            constitutionLoaded: this.bundle?.constitution != null,
-            shardCount: this.retriever.shardCount,
-            activeGates: this.gates.getActiveGateCount(),
-            ledgerEventCount: this.ledger.eventCount,
-            lastOptimizationRun: this.optimizer.lastRun,
-            metrics: this.ledger.eventCount > 0
-                ? this.ledger.computeMetrics()
-                : null,
-        };
-    }
-    /**
-     * Get the current policy bundle
-     */
-    getBundle() {
-        return this.bundle;
-    }
-    /**
-     * Get the run ledger
-     */
-    getLedger() {
-        return this.ledger;
-    }
-    /**
-     * Get the optimizer
-     */
-    getOptimizer() {
-        return this.optimizer;
-    }
-    /**
-     * Get the headless runner
-     */
-    getHeadlessRunner() {
-        return this.headless;
-    }
-    /**
-     * Get metrics for benefit tracking
-     */
-    getMetrics() {
-        const metrics = this.ledger.computeMetrics();
-        const rankings = this.ledger.rankViolations();
-        return {
-            violationRatePer10Tasks: metrics.violationRate,
-            selfCorrectionRate: metrics.selfCorrectionRate,
-            reworkLinesAvg: metrics.reworkLines,
-            clarifyingQuestionsAvg: metrics.clarifyingQuestions,
-            taskCount: metrics.taskCount,
-            topViolations: rankings.slice(0, 5).map(r => ({
-                ruleId: r.ruleId,
-                frequency: r.frequency,
-                cost: r.cost,
-            })),
-        };
-    }
-    // ===== Private =====
-    async readGuidanceFile(path) {
-        try {
-            if (existsSync(path)) {
-                return await readFile(path, 'utf-8');
-            }
-            return null;
-        }
-        catch {
-            return null;
-        }
-    }
-    ensureInitialized() {
-        if (!this.initialized) {
-            throw new Error('GuidanceControlPlane not initialized. Call initialize() first.');
-        }
-    }
-}
-/**
- * Create a guidance control plane instance
- */
-export function createGuidanceControlPlane(config) {
-    return new GuidanceControlPlane(config);
-}
-/**
- * Quick setup: create and initialize the control plane
- */
-export async function initializeGuidanceControlPlane(config) {
-    const plane = new GuidanceControlPlane(config);
-    await plane.initialize();
-    return plane;
-}
-export default GuidanceControlPlane;
-//# sourceMappingURL=index.js.map

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

@@ -1,162 +0,0 @@
-/**
- * Run Ledger + Evaluators
- *
- * Logs every run as an event with a minimum schema, then runs evaluators
- * to assess compliance and quality.
- *
- * Objective evaluators:
- * 1. Tests pass
- * 2. Lint pass
- * 3. Forbidden dependency scan
- * 4. Forbidden command scan
- * 5. Required sections present in plan
- *
- * Subjective evaluators:
- * 1. Reviewer rating (pass/fail)
- * 2. Architecture compliance (pass/fail)
- *
- * @module @claude-flow/guidance/ledger
- */
-import type { RunEvent, EvaluatorResult, TaskIntent, OptimizationMetrics, ViolationRanking } from './types.js';
-export interface IEvaluator {
-    /** Evaluator name */
-    name: string;
-    /** Whether this is objective (automated) or subjective (human) */
-    type: 'objective' | 'subjective';
-    /** Run the evaluation */
-    evaluate(event: RunEvent): Promise<EvaluatorResult>;
-}
-/**
- * Tests Pass evaluator - checks test results
- */
-export declare class TestsPassEvaluator implements IEvaluator {
-    name: string;
-    type: "objective";
-    evaluate(event: RunEvent): Promise<EvaluatorResult>;
-}
-/**
- * Forbidden command scan evaluator
- */
-export declare class ForbiddenCommandEvaluator implements IEvaluator {
-    name: string;
-    type: "objective";
-    private forbiddenPatterns;
-    constructor(forbiddenPatterns?: RegExp[]);
-    evaluate(event: RunEvent): Promise<EvaluatorResult>;
-}
-/**
- * Forbidden dependency scan evaluator
- */
-export declare class ForbiddenDependencyEvaluator implements IEvaluator {
-    name: string;
-    type: "objective";
-    private forbiddenPackages;
-    constructor(forbiddenPackages?: string[]);
-    evaluate(event: RunEvent): Promise<EvaluatorResult>;
-}
-/**
- * Violation rate evaluator - checks violation count
- */
-export declare class ViolationRateEvaluator implements IEvaluator {
-    name: string;
-    type: "objective";
-    private maxViolations;
-    constructor(maxViolations?: number);
-    evaluate(event: RunEvent): Promise<EvaluatorResult>;
-}
-/**
- * Diff quality evaluator - checks rework ratio
- */
-export declare class DiffQualityEvaluator implements IEvaluator {
-    name: string;
-    type: "objective";
-    private maxReworkRatio;
-    constructor(maxReworkRatio?: number);
-    evaluate(event: RunEvent): Promise<EvaluatorResult>;
-}
-export declare class RunLedger {
-    private events;
-    private evaluators;
-    private readonly maxEvents;
-    /**
-     * @param maxEvents - Maximum events to retain in memory (0 = unlimited).
-     *   When the limit is exceeded the oldest events are evicted.
-     */
-    constructor(maxEvents?: number);
-    /**
-     * Add a custom evaluator
-     */
-    addEvaluator(evaluator: IEvaluator): void;
-    /**
-     * Remove an evaluator by name
-     */
-    removeEvaluator(name: string): void;
-    /**
-     * Log a run event
-     */
-    logEvent(event: RunEvent | Omit<RunEvent, 'eventId'>): RunEvent;
-    /**
-     * Create a new run event with defaults
-     */
-    createEvent(taskId: string, intent: TaskIntent, guidanceHash: string): RunEvent;
-    /**
-     * Finalize and store an event
-     */
-    finalizeEvent(event: RunEvent): RunEvent;
-    /**
-     * Evict oldest events when maxEvents is exceeded.
-     * Trims 10% in a batch to amortize the O(n) splice cost.
-     */
-    private evictIfNeeded;
-    /**
-     * Run all evaluators against an event
-     */
-    evaluate(event: RunEvent): Promise<EvaluatorResult[]>;
-    /**
-     * Get all events
-     */
-    getEvents(): RunEvent[];
-    /**
-     * Get events by task ID
-     */
-    getEventsByTask(taskId: string): RunEvent[];
-    /**
-     * Get events within a time range
-     */
-    getEventsInRange(startMs: number, endMs: number): RunEvent[];
-    /**
-     * Get recent events
-     */
-    getRecentEvents(count: number): RunEvent[];
-    /**
-     * Compute optimization metrics from events
-     */
-    computeMetrics(events?: RunEvent[]): OptimizationMetrics;
-    /**
-     * Rank violations by frequency and cost (rework lines)
-     */
-    rankViolations(windowEvents?: RunEvent[]): ViolationRanking[];
-    /**
-     * Get event count
-     */
-    get eventCount(): number;
-    /**
-     * Export events for persistence
-     */
-    exportEvents(): RunEvent[];
-    /**
-     * Import events from persistence
-     */
-    importEvents(events: RunEvent[]): void;
-    /**
-     * Clear all events
-     */
-    clear(): void;
-}
-/**
- * Create a run ledger instance
- *
- * @param maxEvents - Maximum events to retain in memory (0 = unlimited).
- */
-export declare function createLedger(maxEvents?: number): RunLedger;
-//# sourceMappingURL=ledger.d.ts.map