claude-flow 3.25.5 → 3.26.0

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

@@ -1,375 +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 { randomUUID } from 'node:crypto';
-// ============================================================================
-// Built-in Evaluators
-// ============================================================================
-/**
- * Tests Pass evaluator - checks test results
- */
-export class TestsPassEvaluator {
-    name = 'tests-pass';
-    type = 'objective';
-    async evaluate(event) {
-        if (!event.testResults.ran) {
-            return {
-                name: this.name,
-                passed: false,
-                details: 'Tests were not run during this task',
-                score: 0,
-            };
-        }
-        const passed = event.testResults.failed === 0;
-        const total = event.testResults.passed + event.testResults.failed + event.testResults.skipped;
-        return {
-            name: this.name,
-            passed,
-            details: passed
-                ? `All ${event.testResults.passed} tests passed (${event.testResults.skipped} skipped)`
-                : `${event.testResults.failed} of ${total} tests failed`,
-            score: total > 0 ? event.testResults.passed / total : 0,
-        };
-    }
-}
-/**
- * Forbidden command scan evaluator
- */
-export class ForbiddenCommandEvaluator {
-    name = 'forbidden-command-scan';
-    type = 'objective';
-    forbiddenPatterns;
-    constructor(forbiddenPatterns) {
-        this.forbiddenPatterns = forbiddenPatterns ?? [
-            /\brm\s+-rf\s+\//,
-            /\bgit\s+push\s+--force\s+origin\s+(?:main|master)\b/,
-            /\bcurl\s+.*\|\s*(?:sh|bash)\b/,
-            /\beval\s*\(/,
-            /\bexec\s*\(/,
-        ];
-    }
-    async evaluate(event) {
-        const violations = [];
-        for (const tool of event.toolsUsed) {
-            for (const pattern of this.forbiddenPatterns) {
-                if (pattern.test(tool)) {
-                    violations.push(`Forbidden command pattern: ${pattern.source} matched in "${tool}"`);
-                }
-            }
-        }
-        return {
-            name: this.name,
-            passed: violations.length === 0,
-            details: violations.length === 0
-                ? 'No forbidden commands detected'
-                : `Found ${violations.length} forbidden command(s): ${violations.join('; ')}`,
-            score: violations.length === 0 ? 1 : 0,
-        };
-    }
-}
-/**
- * Forbidden dependency scan evaluator
- */
-export class ForbiddenDependencyEvaluator {
-    name = 'forbidden-dependency-scan';
-    type = 'objective';
-    forbiddenPackages;
-    constructor(forbiddenPackages) {
-        this.forbiddenPackages = forbiddenPackages ?? [];
-    }
-    async evaluate(event) {
-        if (this.forbiddenPackages.length === 0) {
-            return { name: this.name, passed: true, details: 'No forbidden dependencies configured', score: 1 };
-        }
-        // Check if any forbidden packages were introduced in touched files
-        const packageFiles = event.filesTouched.filter(f => f.endsWith('package.json') || f.endsWith('package-lock.json'));
-        return {
-            name: this.name,
-            passed: true,
-            details: packageFiles.length > 0
-                ? `Package files modified: ${packageFiles.join(', ')} - manual review recommended`
-                : 'No package files modified',
-            score: 1,
-        };
-    }
-}
-/**
- * Violation rate evaluator - checks violation count
- */
-export class ViolationRateEvaluator {
-    name = 'violation-rate';
-    type = 'objective';
-    maxViolations;
-    constructor(maxViolations = 0) {
-        this.maxViolations = maxViolations;
-    }
-    async evaluate(event) {
-        const count = event.violations.length;
-        const passed = count <= this.maxViolations;
-        return {
-            name: this.name,
-            passed,
-            details: passed
-                ? `${count} violation(s) within threshold (max: ${this.maxViolations})`
-                : `${count} violation(s) exceeds threshold (max: ${this.maxViolations})`,
-            score: Math.max(0, 1 - count / Math.max(this.maxViolations + 1, 1)),
-        };
-    }
-}
-/**
- * Diff quality evaluator - checks rework ratio
- */
-export class DiffQualityEvaluator {
-    name = 'diff-quality';
-    type = 'objective';
-    maxReworkRatio;
-    constructor(maxReworkRatio = 0.3) {
-        this.maxReworkRatio = maxReworkRatio;
-    }
-    async evaluate(event) {
-        const totalLines = event.diffSummary.linesAdded + event.diffSummary.linesRemoved;
-        if (totalLines === 0) {
-            return { name: this.name, passed: true, details: 'No diff produced', score: 1 };
-        }
-        const reworkRatio = event.reworkLines / totalLines;
-        const passed = reworkRatio <= this.maxReworkRatio;
-        return {
-            name: this.name,
-            passed,
-            details: `Rework ratio: ${(reworkRatio * 100).toFixed(1)}% (${event.reworkLines}/${totalLines} lines). Threshold: ${(this.maxReworkRatio * 100).toFixed(0)}%`,
-            score: Math.max(0, 1 - reworkRatio),
-        };
-    }
-}
-// ============================================================================
-// Run Ledger
-// ============================================================================
-export class RunLedger {
-    events = [];
-    evaluators = [];
-    maxEvents;
-    /**
-     * @param maxEvents - Maximum events to retain in memory (0 = unlimited).
-     *   When the limit is exceeded the oldest events are evicted.
-     */
-    constructor(maxEvents = 0) {
-        this.maxEvents = maxEvents;
-        // Register default evaluators
-        this.evaluators = [
-            new TestsPassEvaluator(),
-            new ForbiddenCommandEvaluator(),
-            new ForbiddenDependencyEvaluator(),
-            new ViolationRateEvaluator(),
-            new DiffQualityEvaluator(),
-        ];
-    }
-    /**
-     * Add a custom evaluator
-     */
-    addEvaluator(evaluator) {
-        this.evaluators.push(evaluator);
-    }
-    /**
-     * Remove an evaluator by name
-     */
-    removeEvaluator(name) {
-        this.evaluators = this.evaluators.filter(e => e.name !== name);
-    }
-    /**
-     * Log a run event
-     */
-    logEvent(event) {
-        const fullEvent = {
-            ...event,
-            eventId: randomUUID(),
-        };
-        this.events.push(fullEvent);
-        this.evictIfNeeded();
-        return fullEvent;
-    }
-    /**
-     * Create a new run event with defaults
-     */
-    createEvent(taskId, intent, guidanceHash) {
-        return {
-            eventId: randomUUID(),
-            taskId,
-            guidanceHash,
-            retrievedRuleIds: [],
-            toolsUsed: [],
-            filesTouched: [],
-            diffSummary: { linesAdded: 0, linesRemoved: 0, filesChanged: 0 },
-            testResults: { ran: false, passed: 0, failed: 0, skipped: 0 },
-            violations: [],
-            outcomeAccepted: null,
-            reworkLines: 0,
-            intent,
-            timestamp: Date.now(),
-            durationMs: 0,
-        };
-    }
-    /**
-     * Finalize and store an event
-     */
-    finalizeEvent(event) {
-        event.durationMs = Date.now() - event.timestamp;
-        this.events.push(event);
-        this.evictIfNeeded();
-        return event;
-    }
-    /**
-     * Evict oldest events when maxEvents is exceeded.
-     * Trims 10% in a batch to amortize the O(n) splice cost.
-     */
-    evictIfNeeded() {
-        if (this.maxEvents > 0 && this.events.length > this.maxEvents) {
-            const trimCount = Math.max(1, Math.floor(this.maxEvents * 0.1));
-            this.events.splice(0, trimCount);
-        }
-    }
-    /**
-     * Run all evaluators against an event
-     */
-    async evaluate(event) {
-        const results = [];
-        for (const evaluator of this.evaluators) {
-            const result = await evaluator.evaluate(event);
-            results.push(result);
-        }
-        return results;
-    }
-    /**
-     * Get all events
-     */
-    getEvents() {
-        return [...this.events];
-    }
-    /**
-     * Get events by task ID
-     */
-    getEventsByTask(taskId) {
-        return this.events.filter(e => e.taskId === taskId);
-    }
-    /**
-     * Get events within a time range
-     */
-    getEventsInRange(startMs, endMs) {
-        return this.events.filter(e => e.timestamp >= startMs && e.timestamp <= endMs);
-    }
-    /**
-     * Get recent events
-     */
-    getRecentEvents(count) {
-        return this.events.slice(-count);
-    }
-    /**
-     * Compute optimization metrics from events
-     */
-    computeMetrics(events) {
-        const evts = events ?? this.events;
-        if (evts.length === 0) {
-            return {
-                violationRate: 0,
-                selfCorrectionRate: 0,
-                reworkLines: 0,
-                clarifyingQuestions: 0,
-                taskCount: 0,
-            };
-        }
-        // Violations per 10 tasks
-        const totalViolations = evts.reduce((sum, e) => sum + e.violations.length, 0);
-        const violationRate = evts.length > 0 ? (totalViolations / evts.length) * 10 : 0;
-        // Self-correction rate: violations that were auto-corrected
-        const totalCorrectable = evts.reduce((sum, e) => sum + e.violations.length, 0);
-        const totalCorrected = evts.reduce((sum, e) => sum + e.violations.filter(v => v.autoCorrected).length, 0);
-        const selfCorrectionRate = totalCorrectable > 0
-            ? totalCorrected / totalCorrectable
-            : 1;
-        // Average rework lines
-        const reworkLines = evts.reduce((sum, e) => sum + e.reworkLines, 0) / evts.length;
-        // Clarifying questions are tracked in metadata (placeholder for now)
-        const clarifyingQuestions = 0;
-        return {
-            violationRate,
-            selfCorrectionRate,
-            reworkLines,
-            clarifyingQuestions,
-            taskCount: evts.length,
-        };
-    }
-    /**
-     * Rank violations by frequency and cost (rework lines)
-     */
-    rankViolations(windowEvents) {
-        const evts = windowEvents ?? this.events;
-        const violationMap = new Map();
-        for (const event of evts) {
-            for (const violation of event.violations) {
-                const existing = violationMap.get(violation.ruleId) ?? { frequency: 0, totalRework: 0 };
-                existing.frequency++;
-                existing.totalRework += event.reworkLines;
-                violationMap.set(violation.ruleId, existing);
-            }
-        }
-        const rankings = [];
-        for (const [ruleId, stats] of violationMap) {
-            const cost = stats.totalRework / stats.frequency;
-            rankings.push({
-                ruleId,
-                frequency: stats.frequency,
-                cost,
-                score: stats.frequency * cost,
-            });
-        }
-        return rankings.sort((a, b) => b.score - a.score);
-    }
-    /**
-     * Get event count
-     */
-    get eventCount() {
-        return this.events.length;
-    }
-    /**
-     * Export events for persistence
-     */
-    exportEvents() {
-        return [...this.events];
-    }
-    /**
-     * Import events from persistence
-     */
-    importEvents(events) {
-        this.events.push(...events);
-    }
-    /**
-     * Clear all events
-     */
-    clear() {
-        this.events = [];
-    }
-}
-/**
- * Create a run ledger instance
- *
- * @param maxEvents - Maximum events to retain in memory (0 = unlimited).
- */
-export function createLedger(maxEvents = 0) {
-    return new RunLedger(maxEvents);
-}
-//# sourceMappingURL=ledger.js.map

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

@@ -1,289 +0,0 @@
-/**
- * Manifest Validator & Conformance Suite
- *
- * Validates AgentCellManifest documents against the Agentic Container spec,
- * computes risk scores, selects execution lanes, and fails closed on any
- * validation error. The ConformanceSuite runs golden traces through an
- * evaluator to prove the platform behaves as specified.
- *
- * @module @claude-flow/guidance/manifest-validator
- */
-/** Data sensitivity levels ordered by severity */
-declare const DATA_SENSITIVITY_LEVELS: readonly ["public", "internal", "confidential", "restricted"];
-type DataSensitivity = typeof DATA_SENSITIVITY_LEVELS[number];
-/** Write modes for memory policy */
-declare const WRITE_MODES: readonly ["append", "overwrite", "merge"];
-type WriteMode = typeof WRITE_MODES[number];
-/** Authority scopes for memory policy */
-declare const AUTHORITY_SCOPES: readonly ["self", "team", "tenant", "global"];
-type AuthorityScope = typeof AUTHORITY_SCOPES[number];
-/** Trace levels for observability */
-declare const TRACE_LEVELS: readonly ["none", "errors", "decisions", "full"];
-/** Execution lanes ordered by privilege (lowest to highest) */
-declare const LANES: readonly ["wasm", "sandboxed", "native"];
-type Lane = typeof LANES[number];
-/**
- * The manifest describing an agent cell per the Agentic Container spec.
- */
-export interface AgentCellManifest {
-    /** API version string (must be 'agentic_cells.v0_1') */
-    apiVersion: string;
-    /** Cell identity */
-    cell: {
-        name: string;
-        purpose: string;
-        ownerTenant: string;
-        codeRef: {
-            kind: string;
-            digest: string;
-            entry: string;
-        };
-    };
-    /** Lane execution policy */
-    lanePolicy: {
-        portabilityRequired: boolean;
-        needsNativeThreads: boolean;
-        preferredLane: Lane;
-        maxRiskScore: number;
-    };
-    /** Resource budgets */
-    budgets: {
-        maxWallClockSeconds: number;
-        maxToolCalls: number;
-        maxBytesEgress: number;
-        maxTokensInMtok: number;
-        maxTokensOutMtok: number;
-        maxMemoryWrites: number;
-    };
-    /** Data handling policy */
-    dataPolicy: {
-        dataSensitivity: DataSensitivity;
-        piiAllowed: boolean;
-        retentionDays: number;
-        exportControls: {
-            allowedRegions: string[];
-            blockedRegions: string[];
-        };
-    };
-    /** Tool usage policy */
-    toolPolicy: {
-        toolsAllowed: string[];
-        networkAllowlist: string[];
-        writeActionsRequireConfirmation: boolean;
-    };
-    /** Memory system policy */
-    memoryPolicy: {
-        namespace: string;
-        authorityScope: AuthorityScope;
-        writeMode: WriteMode;
-        requiresCoherenceGate: boolean;
-        requiresAntiHallucinationGate: boolean;
-    };
-    /** Observability configuration */
-    observability: {
-        traceLevel: typeof TRACE_LEVELS[number];
-        emitArtifacts: boolean;
-        artifactBucket: string;
-    };
-}
-/**
- * A single validation error or warning.
- */
-export interface ValidationError {
-    /** Error code (e.g., 'MISSING_FIELD', 'INVALID_DIGEST', 'BUDGET_EXCEED') */
-    code: string;
-    /** JSON path to the problematic field */
-    field: string;
-    /** Human-readable description */
-    message: string;
-    /** Severity level */
-    severity: 'error';
-}
-/**
- * A single validation warning.
- */
-export interface ValidationWarning {
-    /** Warning code */
-    code: string;
-    /** JSON path to the problematic field */
-    field: string;
-    /** Human-readable description */
-    message: string;
-    /** Severity level */
-    severity: 'warning';
-}
-/**
- * Complete validation result for a manifest.
- */
-export interface ValidationResult {
-    /** Whether the manifest passed all validation checks */
-    valid: boolean;
-    /** Validation errors (each causes rejection) */
-    errors: ValidationError[];
-    /** Validation warnings (informational, do not block admission) */
-    warnings: ValidationWarning[];
-    /** Admission decision: admit, reject, or review */
-    admissionDecision: 'admit' | 'reject' | 'review';
-    /** Selected execution lane (null if rejected) */
-    laneSelection: Lane | null;
-    /** Computed risk score (0-100) */
-    riskScore: number;
-}
-/**
- * Validates AgentCellManifest documents against the Agentic Container spec.
- *
- * Fails closed: any validation error results in a 'reject' decision.
- * Warnings alone do not block admission but may trigger a 'review' decision
- * when the risk score is between thresholds.
- */
-export declare class ManifestValidator {
-    /** Risk score threshold: below this, admit. Above reject threshold, reject. Between, review. */
-    private readonly admitThreshold;
-    private readonly rejectThreshold;
-    constructor(options?: {
-        admitThreshold?: number;
-        rejectThreshold?: number;
-    });
-    /**
-     * Validate a manifest, compute its risk score, select a lane, and decide admission.
-     *
-     * FAILS CLOSED: any validation error leads to reject.
-     */
-    validate(manifest: AgentCellManifest): ValidationResult;
-    /**
-     * Compute a risk score (0-100) from tool risk, data sensitivity, and privilege surface.
-     *
-     * Components:
-     * - tool_risk (0-40): based on tool types and network access
-     * - data_sensitivity (0-30): based on sensitivity level and PII
-     * - privilege_surface (0-30): based on memory scope, write mode, native threads
-     */
-    computeRiskScore(manifest: AgentCellManifest): number;
-    /**
-     * Select the execution lane based on risk score and manifest policy.
-     *
-     * Lane selection rules:
-     * - If portabilityRequired or risk <= 30: wasm
-     * - If needsNativeThreads and risk > 50: native
-     * - Otherwise: sandboxed
-     * - Always respect preferredLane if risk score allows it
-     * - Risk exceeding maxRiskScore forces the most restrictive lane
-     */
-    selectLane(manifest: AgentCellManifest, riskScore: number): Lane;
-    /**
-     * Validate budget values: no negatives, within sanity limits.
-     */
-    validateBudgets(budgets: AgentCellManifest['budgets']): ValidationError[];
-    /**
-     * Validate tool policy: network allowlist must not contain wildcards
-     * unless the cell explicitly has Bash (privileged).
-     */
-    validateToolPolicy(toolPolicy: AgentCellManifest['toolPolicy']): ValidationError[];
-    /**
-     * Validate data policy fields.
-     */
-    validateDataPolicy(dataPolicy: AgentCellManifest['dataPolicy']): ValidationError[];
-    private validateRequiredFields;
-    private validateApiVersion;
-    private validateDigest;
-    private validateWarnings;
-}
-/**
- * A single event within a golden trace.
- */
-export interface GoldenTraceEvent {
-    /** Sequence number within the trace */
-    seq: number;
-    /** Type of event (e.g., 'command', 'tool-use', 'memory-write', 'budget-check') */
-    eventType: string;
-    /** Event payload */
-    payload: Record<string, unknown>;
-    /** Expected outcome from the platform */
-    expectedOutcome: 'allow' | 'deny' | 'warn';
-}
-/**
- * A complete golden trace including events and expected decisions.
- */
-export interface GoldenTrace {
-    /** Unique trace identifier */
-    traceId: string;
-    /** Human-readable name */
-    name: string;
-    /** Description of what the trace verifies */
-    description: string;
-    /** Ordered sequence of events */
-    events: GoldenTraceEvent[];
-    /** Map from event seq (as string) to expected decision string */
-    expectedDecisions: Record<string, string>;
-    /** Map from memory key to expected parent chain for lineage verification */
-    expectedMemoryLineage: Record<string, string[]>;
-}
-/**
- * Result of running the conformance suite.
- */
-export interface ConformanceResult {
-    /** Whether all events matched their expected outcomes */
-    passed: boolean;
-    /** Total number of events evaluated */
-    totalEvents: number;
-    /** Number of events that matched expectations */
-    matchedEvents: number;
-    /** Details of any mismatches */
-    mismatches: Array<{
-        traceId: string;
-        seq: number;
-        expected: string;
-        actual: string;
-        details: unknown;
-    }>;
-}
-/**
- * Runs golden traces through an evaluator and reports conformance.
- *
- * Each trace contains events with expected outcomes. The suite feeds every
- * event to the evaluator and compares the actual decision to the expectation.
- */
-export declare class ConformanceSuite {
-    private traces;
-    /**
-     * Add a golden trace to the suite.
-     */
-    addTrace(trace: GoldenTrace): void;
-    /**
-     * Run every event in every trace through the evaluator and compare
-     * actual decisions against expected outcomes.
-     */
-    run(evaluator: (event: GoldenTraceEvent) => {
-        decision: string;
-        details: unknown;
-    }): ConformanceResult;
-    /**
-     * Get all registered traces.
-     */
-    getTraces(): GoldenTrace[];
-    /**
-     * Create built-in default golden traces that verify core platform invariants:
-     *
-     * 1. Destructive command blocked
-     * 2. Secret detected and blocked
-     * 3. Budget exceeded and denied
-     * 4. Memory write without evidence blocked
-     * 5. Valid operation allowed
-     */
-    createDefaultTraces(): GoldenTrace[];
-}
-/**
- * Create a new ManifestValidator instance.
- */
-export declare function createManifestValidator(options?: {
-    admitThreshold?: number;
-    rejectThreshold?: number;
-}): ManifestValidator;
-/**
- * Create a new ConformanceSuite instance, optionally pre-loaded with default traces.
- */
-export declare function createConformanceSuite(options?: {
-    includeDefaults?: boolean;
-}): ConformanceSuite;
-export {};
-//# sourceMappingURL=manifest-validator.d.ts.map