claude-flow 3.25.5 → 3.26.0

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

@@ -1,410 +0,0 @@
-/**
- * Guidance Compiler
- *
- * Parses root CLAUDE.md and optional CLAUDE.local.md into a compiled policy bundle:
- * 1. A small always-loaded constitution (first 30-60 lines of invariants)
- * 2. A set of task-scoped rule shards tagged by intent, risk, domain, repo path, tool class
- * 3. A machine-readable manifest with rule IDs, triggers, and verifiers
- *
- * @module @claude-flow/guidance/compiler
- */
-import { createHash } from 'node:crypto';
-// ============================================================================
-// Parser Patterns
-// ============================================================================
-/** Matches a rule declaration: "R001:" or "RULE-001:" or "[R001]" or "- [R001]" */
-const RULE_ID_PATTERN = /^(?:#{1,4}\s+)?(?:[-*]\s+)?\[?([A-Z]+-?\d{3,4})\]?[:\s]/;
-/** Matches risk class annotations: "(critical)", "[high-risk]", etc. */
-const RISK_PATTERN = /\(?(critical|high|medium|low|info)(?:-risk)?\)?/i;
-/** Matches domain tags: @security, @testing, etc. */
-const DOMAIN_TAG_PATTERN = /@(security|testing|performance|architecture|debugging|deployment|general)/gi;
-/** Matches tool class tags: [edit], [bash], etc. */
-const TOOL_TAG_PATTERN = /\[(edit|bash|read|write|mcp|task|all)\]/gi;
-/** Matches intent tags: #bug-fix, #feature, etc. */
-const INTENT_TAG_PATTERN = /#(bug-fix|feature|refactor|security|performance|testing|docs|deployment|architecture|debug|general)/gi;
-/** Matches repo scope: scope:src/**, scope:tests/**, etc. */
-const SCOPE_PATTERN = /scope:([\w\/\*\.\-]+)/gi;
-/** Matches verifier annotations: verify:tests-pass, verify:lint-clean */
-const VERIFIER_PATTERN = /verify:([\w\-]+)/i;
-/** Matches priority override: priority:N */
-const PRIORITY_PATTERN = /priority:(\d+)/i;
-/** Section markers for constitution identification */
-const CONSTITUTION_MARKERS = [
-    /^#+\s*(safety|security|invariant|constitution|critical|non[- ]?negotiable|always)/i,
-    /^#+\s*(must|never|always|required|mandatory)/i,
-];
-/** Section markers for shard boundaries */
-const SHARD_MARKERS = [
-    /^#+\s/, // Any heading
-    /^---+\s*$/, // Horizontal rule
-    /^\*\*\*+\s*$/, // Bold horizontal rule
-];
-const DEFAULT_CONFIG = {
-    maxConstitutionLines: 60,
-    defaultRiskClass: 'medium',
-    defaultPriority: 50,
-    autoGenerateIds: true,
-};
-// ============================================================================
-// Guidance Compiler
-// ============================================================================
-export class GuidanceCompiler {
-    config;
-    nextAutoId = 1;
-    constructor(config = {}) {
-        this.config = { ...DEFAULT_CONFIG, ...config };
-    }
-    /**
-     * Compile guidance files into a policy bundle
-     */
-    compile(rootContent, localContent) {
-        // Parse both files into raw rules
-        const rootRules = this.parseGuidanceFile(rootContent, 'root');
-        const localRules = localContent
-            ? this.parseGuidanceFile(localContent, 'local')
-            : [];
-        // Merge rules (local overrides root for same ID)
-        const allRules = this.mergeRules(rootRules, localRules);
-        // Split into constitution and shards
-        const constitutionRules = allRules.filter(r => r.isConstitution);
-        const shardRules = allRules.filter(r => !r.isConstitution);
-        // Build constitution
-        const constitution = this.buildConstitution(constitutionRules);
-        // Build shards
-        const shards = this.buildShards(shardRules);
-        // Build manifest
-        const manifest = this.buildManifest(allRules, rootContent, localContent);
-        return { constitution, shards, manifest };
-    }
-    /**
-     * Parse a guidance markdown file into rules
-     */
-    parseGuidanceFile(content, source) {
-        const rules = [];
-        const lines = content.split('\n');
-        let currentSection = '';
-        let currentBlock = [];
-        let inConstitutionSection = false;
-        let blockStartLine = 0;
-        for (let i = 0; i < lines.length; i++) {
-            const line = lines[i];
-            // Detect section boundaries
-            if (SHARD_MARKERS.some(m => m.test(line))) {
-                // Flush current block
-                if (currentBlock.length > 0) {
-                    const blockRules = this.extractRulesFromBlock(currentBlock.join('\n'), source, inConstitutionSection, currentSection);
-                    rules.push(...blockRules);
-                    currentBlock = [];
-                }
-                // Check if this is a constitution section
-                inConstitutionSection = CONSTITUTION_MARKERS.some(m => m.test(line));
-                currentSection = line.replace(/^#+\s*/, '').trim();
-                blockStartLine = i;
-            }
-            currentBlock.push(line);
-        }
-        // Flush last block
-        if (currentBlock.length > 0) {
-            const blockRules = this.extractRulesFromBlock(currentBlock.join('\n'), source, inConstitutionSection, currentSection);
-            rules.push(...blockRules);
-        }
-        return rules;
-    }
-    /**
-     * Extract rules from a content block
-     */
-    extractRulesFromBlock(block, source, isConstitution, section) {
-        const rules = [];
-        const lines = block.split('\n');
-        // Try to extract explicit rules (with IDs)
-        let ruleBuffer = [];
-        let currentRuleId = null;
-        for (const line of lines) {
-            const idMatch = line.match(RULE_ID_PATTERN);
-            if (idMatch) {
-                // Flush previous rule
-                if (currentRuleId && ruleBuffer.length > 0) {
-                    rules.push(this.parseRule(currentRuleId, ruleBuffer.join('\n'), source, isConstitution));
-                    ruleBuffer = [];
-                }
-                currentRuleId = idMatch[1];
-                ruleBuffer.push(line.replace(RULE_ID_PATTERN, '').trim());
-            }
-            else if (currentRuleId) {
-                ruleBuffer.push(line);
-            }
-        }
-        // Flush last rule
-        if (currentRuleId && ruleBuffer.length > 0) {
-            rules.push(this.parseRule(currentRuleId, ruleBuffer.join('\n'), source, isConstitution));
-        }
-        // If no explicit rules found, try to extract implicit rules from bullet points
-        if (rules.length === 0) {
-            const implicitRules = this.extractImplicitRules(block, source, isConstitution, section);
-            rules.push(...implicitRules);
-        }
-        return rules;
-    }
-    /**
-     * Extract implicit rules from bullet points and paragraphs
-     */
-    extractImplicitRules(block, source, isConstitution, section) {
-        const rules = [];
-        const lines = block.split('\n');
-        for (const line of lines) {
-            const trimmed = line.trim();
-            // Skip empty lines, headings, and non-actionable content
-            if (!trimmed || /^#+\s/.test(trimmed) || /^---/.test(trimmed))
-                continue;
-            // Match actionable bullet points
-            const bulletMatch = trimmed.match(/^[-*]\s+(.+)/);
-            if (!bulletMatch)
-                continue;
-            const text = bulletMatch[1].trim();
-            // Only create rules for actionable statements
-            if (!this.isActionableRule(text))
-                continue;
-            // Auto-generate ID if enabled
-            if (this.config.autoGenerateIds) {
-                const id = `AUTO-${String(this.nextAutoId++).padStart(3, '0')}`;
-                rules.push(this.parseRule(id, text, source, isConstitution));
-            }
-        }
-        return rules;
-    }
-    /**
-     * Check if text represents an actionable rule
-     */
-    isActionableRule(text) {
-        const actionPatterns = [
-            /\b(must|never|always|should|require|forbid|ensure|validate|check|verify)\b/i,
-            /\b(do not|don't|cannot|can't|avoid|prevent|block|deny|reject)\b/i,
-            /\b(use|prefer|apply|follow|implement|enforce|maintain|keep|run|include|write|mock|respect)\b/i,
-        ];
-        return actionPatterns.some(p => p.test(text));
-    }
-    /**
-     * Parse a single rule from its text content
-     */
-    parseRule(id, text, source, isConstitution) {
-        const now = Date.now();
-        // Extract risk class
-        const riskMatch = text.match(RISK_PATTERN);
-        const riskClass = riskMatch?.[1]?.toLowerCase() ?? this.config.defaultRiskClass;
-        // Phase 1 perf — replace 4 `new RegExp(PATTERN.source, 'gi')` calls per
-        // parseRule with `text.matchAll(PATTERN)` against the existing
-        // module-level global regex. On a 500-rule file that previously meant
-        // 2,000 RegExp constructions per compile; matchAll is allocation-free
-        // per call and the module-level pattern is constructed exactly once.
-        const toolClasses = [];
-        for (const m of text.matchAll(TOOL_TAG_PATTERN)) {
-            toolClasses.push(m[1].toLowerCase());
-        }
-        if (toolClasses.length === 0)
-            toolClasses.push('all');
-        const intents = [];
-        for (const m of text.matchAll(INTENT_TAG_PATTERN)) {
-            intents.push(m[1].toLowerCase());
-        }
-        if (intents.length === 0)
-            intents.push(...this.inferIntents(text));
-        const domains = [];
-        for (const m of text.matchAll(DOMAIN_TAG_PATTERN)) {
-            domains.push(m[1].toLowerCase());
-        }
-        if (domains.length === 0)
-            domains.push(...this.inferDomains(text));
-        const repoScopes = [];
-        for (const m of text.matchAll(SCOPE_PATTERN)) {
-            repoScopes.push(m[1]);
-        }
-        if (repoScopes.length === 0)
-            repoScopes.push('**/*');
-        // Extract verifier
-        const verifierMatch = text.match(VERIFIER_PATTERN);
-        const verifier = verifierMatch?.[1];
-        // Extract priority
-        const priorityMatch = text.match(PRIORITY_PATTERN);
-        const priority = priorityMatch ? parseInt(priorityMatch[1], 10) : this.config.defaultPriority;
-        // Clean rule text (remove annotations)
-        const cleanText = text
-            .replace(RISK_PATTERN, '')
-            .replace(TOOL_TAG_PATTERN, '')
-            .replace(INTENT_TAG_PATTERN, '')
-            .replace(DOMAIN_TAG_PATTERN, '')
-            .replace(SCOPE_PATTERN, '')
-            .replace(VERIFIER_PATTERN, '')
-            .replace(PRIORITY_PATTERN, '')
-            .replace(/\s+/g, ' ')
-            .trim();
-        return {
-            id,
-            text: cleanText,
-            riskClass,
-            toolClasses,
-            intents,
-            repoScopes,
-            domains,
-            priority: isConstitution ? priority + 100 : priority,
-            source,
-            isConstitution,
-            verifier,
-            createdAt: now,
-            updatedAt: now,
-        };
-    }
-    /**
-     * Infer intents from rule text
-     */
-    inferIntents(text) {
-        const intents = [];
-        const lower = text.toLowerCase();
-        if (/secur|auth|secret|password|token|cve|vuln|encrypt/i.test(lower))
-            intents.push('security');
-        if (/test|spec|mock|coverage|assert|tdd/i.test(lower))
-            intents.push('testing');
-        if (/perf|optim|fast|slow|cache|memory|speed/i.test(lower))
-            intents.push('performance');
-        if (/refactor|clean|restructur|simplif/i.test(lower))
-            intents.push('refactor');
-        if (/bug|fix|error|broken|fail|debug/i.test(lower))
-            intents.push('bug-fix');
-        if (/architect|design|pattern|structure|boundary/i.test(lower))
-            intents.push('architecture');
-        if (/deploy|release|publish|ci|cd/i.test(lower))
-            intents.push('deployment');
-        if (/doc|readme|comment|jsdoc/i.test(lower))
-            intents.push('docs');
-        return intents.length > 0 ? intents : ['general'];
-    }
-    /**
-     * Infer domains from rule text
-     */
-    inferDomains(text) {
-        const domains = [];
-        const lower = text.toLowerCase();
-        if (/secur|auth|secret|password|token|cve|vuln/i.test(lower))
-            domains.push('security');
-        if (/test|spec|mock|coverage|assert/i.test(lower))
-            domains.push('testing');
-        if (/perf|optim|fast|slow|cache|speed/i.test(lower))
-            domains.push('performance');
-        if (/architect|design|ddd|domain|boundary/i.test(lower))
-            domains.push('architecture');
-        if (/bug|fix|error|debug/i.test(lower))
-            domains.push('debugging');
-        return domains.length > 0 ? domains : ['general'];
-    }
-    /**
-     * Merge root and local rules, local overrides root for same ID
-     */
-    mergeRules(rootRules, localRules) {
-        const ruleMap = new Map();
-        for (const rule of rootRules) {
-            ruleMap.set(rule.id, rule);
-        }
-        for (const rule of localRules) {
-            if (ruleMap.has(rule.id)) {
-                // Local overrides root, but mark as updated
-                const existing = ruleMap.get(rule.id);
-                ruleMap.set(rule.id, {
-                    ...rule,
-                    priority: Math.max(rule.priority, existing.priority),
-                    updatedAt: Date.now(),
-                });
-            }
-            else {
-                ruleMap.set(rule.id, rule);
-            }
-        }
-        return Array.from(ruleMap.values()).sort((a, b) => b.priority - a.priority);
-    }
-    /**
-     * Build the constitution from constitution-class rules
-     */
-    buildConstitution(rules) {
-        // Sort by priority descending
-        const sorted = [...rules].sort((a, b) => b.priority - a.priority);
-        // Build compact text
-        const lines = [
-            '# Constitution - Always Active Rules',
-            '',
-        ];
-        let currentDomain = '';
-        for (const rule of sorted) {
-            const domain = rule.domains[0] || 'general';
-            if (domain !== currentDomain) {
-                currentDomain = domain;
-                lines.push(`## ${domain.charAt(0).toUpperCase() + domain.slice(1)}`);
-            }
-            lines.push(`- [${rule.id}] ${rule.text}`);
-        }
-        // Trim to max lines
-        const text = lines.slice(0, this.config.maxConstitutionLines).join('\n');
-        return {
-            rules: sorted,
-            text,
-            hash: this.hashContent(text),
-        };
-    }
-    /**
-     * Build shards from non-constitution rules
-     */
-    buildShards(rules) {
-        return rules.map(rule => ({
-            rule,
-            compactText: this.buildCompactShardText(rule),
-        }));
-    }
-    /**
-     * Build compact text for a shard
-     */
-    buildCompactShardText(rule) {
-        const tags = [
-            rule.riskClass,
-            ...rule.domains,
-            ...rule.intents,
-            ...rule.toolClasses.filter(t => t !== 'all'),
-        ].map(t => `@${t}`).join(' ');
-        return `[${rule.id}] ${rule.text} ${tags}`.trim();
-    }
-    /**
-     * Build the manifest
-     */
-    buildManifest(allRules, rootContent, localContent) {
-        const sourceHashes = {
-            root: this.hashContent(rootContent),
-        };
-        if (localContent) {
-            sourceHashes.local = this.hashContent(localContent);
-        }
-        return {
-            rules: allRules.map(r => ({
-                id: r.id,
-                triggers: [...r.intents, ...r.domains, ...r.toolClasses],
-                verifier: r.verifier ?? null,
-                riskClass: r.riskClass,
-                priority: r.priority,
-                source: r.source,
-            })),
-            compiledAt: Date.now(),
-            sourceHashes,
-            totalRules: allRules.length,
-            constitutionRules: allRules.filter(r => r.isConstitution).length,
-            shardRules: allRules.filter(r => !r.isConstitution).length,
-        };
-    }
-    /**
-     * Hash content for change detection
-     */
-    hashContent(content) {
-        return createHash('sha256').update(content).digest('hex').slice(0, 16);
-    }
-}
-/**
- * Create a compiler instance
- */
-export function createCompiler(config) {
-    return new GuidanceCompiler(config);
-}
-//# sourceMappingURL=compiler.js.map

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

@@ -1,225 +0,0 @@
-/**
- * Agent Cell Conformance Kit
- *
- * Canonical acceptance test proving the entire guidance control plane works
- * end-to-end. Implements the "Memory Clerk" agent cell pattern:
- *
- * 1. Read 20 memory entries (knowledge retrieval)
- * 2. Run 1 model inference (reasoning)
- * 3. Propose 5 memory writes based on inference
- * 4. Inject a coherence drop at write #3
- * 5. Verify the system switches to read-only and blocks remaining writes
- * 6. Emit a signed proof envelope
- * 7. Return a complete, replayable trace
- *
- * @module @claude-flow/guidance/conformance-kit
- */
-import { MemoryWriteGate } from './memory-gate.js';
-import type { MemoryAuthority } from './memory-gate.js';
-import { ProofChain } from './proof.js';
-import type { MemoryOperation } from './proof.js';
-import { RunLedger } from './ledger.js';
-import { CoherenceScheduler, EconomicGovernor } from './coherence.js';
-import { DeterministicToolGateway } from './gateway.js';
-/**
- * A single event in the agent cell execution trace.
- */
-export interface TraceEvent {
-    /** Monotonically increasing sequence number starting at 0 */
-    seq: number;
-    /** Epoch-ms timestamp when the event was recorded */
-    ts: number;
-    /** Event classification */
-    type: 'memory_read' | 'memory_write_proposed' | 'memory_write_committed' | 'memory_write_blocked' | 'model_infer' | 'tool_invoke' | 'coherence_check' | 'privilege_change' | 'run_start' | 'run_end';
-    /** Arbitrary structured data describing the event */
-    payload: Record<string, unknown>;
-    /** Human-readable decision string for replay verification */
-    decision: string;
-    /** Snapshot of budget counters at event time */
-    budgetSnapshot: Record<string, number>;
-}
-/**
- * Complete result of an agent cell run including the full trace,
- * memory operation counts, proof hash, and budget usage.
- */
-export interface CellRunResult {
-    cellId: string;
-    runId: string;
-    traceEvents: TraceEvent[];
-    memoryReads: number;
-    memoryWritesAttempted: number;
-    memoryWritesCommitted: number;
-    memoryWritesBlocked: number;
-    proofEnvelopeHash: string;
-    coherenceHistory: number[];
-    budgetUsage: Record<string, number>;
-    outcome: 'completed' | 'restricted' | 'suspended';
-}
-/**
- * Runtime services provided to an agent cell.
- */
-export interface CellRuntime {
-    readMemory(key: string, namespace: string): unknown;
-    writeMemory(key: string, namespace: string, value: unknown, evidence?: Record<string, unknown>): {
-        allowed: boolean;
-        reason: string;
-    };
-    invokeModel(prompt: string): string;
-    invokeTool(name: string, params: Record<string, unknown>): {
-        result: unknown;
-        allowed: boolean;
-    };
-    getCoherenceScore(): number;
-    setCoherenceScore(score: number): void;
-    getProofChain(): ProofChain;
-    getLedger(): RunLedger;
-}
-/**
- * An agent cell is a self-contained unit of work that executes against
- * a CellRuntime, producing a fully traced CellRunResult.
- */
-export interface AgentCell {
-    cellId: string;
-    name: string;
-    run(runtime: CellRuntime): CellRunResult;
-}
-export interface SimulatedRuntimeConfig {
-    memoryGate: MemoryWriteGate;
-    proofChain: ProofChain;
-    ledger: RunLedger;
-    coherenceScheduler: CoherenceScheduler;
-    economicGovernor: EconomicGovernor;
-    toolGateway?: DeterministicToolGateway;
-    authority: MemoryAuthority;
-    initialCoherenceScore?: number;
-    initialMemory?: Map<string, {
-        namespace: string;
-        value: unknown;
-    }>;
-}
-/**
- * A test runtime that wires together all guidance control plane components
- * and records every operation as a TraceEvent.
- */
-export declare class SimulatedRuntime implements CellRuntime {
-    private readonly memoryGate;
-    private readonly proofChain;
-    private readonly ledger;
-    private readonly coherenceScheduler;
-    private readonly economicGovernor;
-    private readonly toolGateway;
-    private readonly authority;
-    private coherenceScore;
-    private readonly memoryStore;
-    private readonly memoryEntries;
-    private readonly traceEvents;
-    private readonly coherenceHistory;
-    private seq;
-    private memoryReadCount;
-    private memoryWritesAttemptedCount;
-    private memoryWritesCommittedCount;
-    private memoryWritesBlockedCount;
-    private readonly memoryOps;
-    constructor(config: SimulatedRuntimeConfig);
-    readMemory(key: string, namespace: string): unknown;
-    writeMemory(key: string, namespace: string, value: unknown, evidence?: Record<string, unknown>): {
-        allowed: boolean;
-        reason: string;
-    };
-    invokeModel(prompt: string): string;
-    invokeTool(name: string, params: Record<string, unknown>): {
-        result: unknown;
-        allowed: boolean;
-    };
-    getCoherenceScore(): number;
-    setCoherenceScore(score: number): void;
-    getProofChain(): ProofChain;
-    getLedger(): RunLedger;
-    /**
-     * Emit a custom trace event. Exposed so agent cells can record
-     * lifecycle events (run_start, run_end) through the same trace stream.
-     */
-    emitCustomTrace(type: TraceEvent['type'], payload: Record<string, unknown>, decision: string): void;
-    getTraceEvents(): TraceEvent[];
-    getCoherenceHistory(): number[];
-    getMemoryReads(): number;
-    getMemoryWritesAttempted(): number;
-    getMemoryWritesCommitted(): number;
-    getMemoryWritesBlocked(): number;
-    getMemoryOps(): MemoryOperation[];
-    getBudgetUsage(): Record<string, number>;
-    private resolvePrivilegeLevel;
-    private emitTrace;
-}
-/**
- * The canonical test agent cell. Exercises every layer of the guidance
- * control plane by performing reads, inference, and gated writes with
- * a deliberate coherence drop mid-run.
- */
-export declare class MemoryClerkCell implements AgentCell {
-    readonly cellId: string;
-    readonly name = "MemoryClerk";
-    private readonly readCount;
-    private readonly inferenceCount;
-    private readonly writeCount;
-    private readonly coherenceDropAtWrite;
-    private readonly droppedCoherenceScore;
-    constructor(cellId?: string, options?: {
-        readCount?: number;
-        inferenceCount?: number;
-        writeCount?: number;
-        coherenceDropAtWrite?: number;
-        droppedCoherenceScore?: number;
-    });
-    run(runtime: CellRuntime): CellRunResult;
-}
-export interface ConformanceTestResult {
-    passed: boolean;
-    checks: Array<{
-        name: string;
-        passed: boolean;
-        expected: unknown;
-        actual: unknown;
-        details: string;
-    }>;
-    trace: TraceEvent[];
-    proofHash: string;
-    duration: number;
-}
-export interface ReplayTestResult {
-    identical: boolean;
-    totalEvents: number;
-    divergences: Array<{
-        seq: number;
-        originalDecision: string;
-        replayDecision: string;
-    }>;
-}
-/**
- * Orchestrates conformance tests by creating all control plane components,
- * running the MemoryClerkCell, and verifying every invariant.
- */
-export declare class ConformanceRunner {
-    private readonly authority;
-    private readonly signingKey;
-    constructor(authority?: MemoryAuthority, signingKey?: string);
-    /**
-     * Run the full conformance test suite and return a structured result
-     * with individual pass/fail checks.
-     */
-    runConformanceTest(): ConformanceTestResult;
-    /**
-     * Replay a previously captured trace and verify that every decision
-     * is reproduced identically by the control plane logic.
-     */
-    runReplayTest(originalTrace: TraceEvent[]): ReplayTestResult;
-}
-/**
- * Create a MemoryClerkCell with an optional cellId override.
- */
-export declare function createMemoryClerkCell(cellId?: string): MemoryClerkCell;
-/**
- * Create a ConformanceRunner with optional authority override.
- */
-export declare function createConformanceRunner(authority?: MemoryAuthority, signingKey?: string): ConformanceRunner;
-//# sourceMappingURL=conformance-kit.d.ts.map