aiyou-dev 3.5.15

package/v3/@aiyou-dev/guidance/dist/compiler.js

@@ -0,0 +1,419 @@
+/**
+ * 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 @aiyou-dev/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;
+        // Extract tool classes
+        const toolClasses = [];
+        let toolMatch;
+        const toolRegex = new RegExp(TOOL_TAG_PATTERN.source, 'gi');
+        while ((toolMatch = toolRegex.exec(text)) !== null) {
+            toolClasses.push(toolMatch[1].toLowerCase());
+        }
+        if (toolClasses.length === 0)
+            toolClasses.push('all');
+        // Extract intents
+        const intents = [];
+        let intentMatch;
+        const intentRegex = new RegExp(INTENT_TAG_PATTERN.source, 'gi');
+        while ((intentMatch = intentRegex.exec(text)) !== null) {
+            intents.push(intentMatch[1].toLowerCase());
+        }
+        if (intents.length === 0) {
+            intents.push(...this.inferIntents(text));
+        }
+        // Extract domains
+        const domains = [];
+        let domainMatch;
+        const domainRegex = new RegExp(DOMAIN_TAG_PATTERN.source, 'gi');
+        while ((domainMatch = domainRegex.exec(text)) !== null) {
+            domains.push(domainMatch[1].toLowerCase());
+        }
+        if (domains.length === 0) {
+            domains.push(...this.inferDomains(text));
+        }
+        // Extract repo scopes
+        const repoScopes = [];
+        let scopeMatch;
+        const scopeRegex = new RegExp(SCOPE_PATTERN.source, 'gi');
+        while ((scopeMatch = scopeRegex.exec(text)) !== null) {
+            repoScopes.push(scopeMatch[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/@aiyou-dev/guidance/dist/conformance-kit.d.ts

@@ -0,0 +1,225 @@
+/**
+ * 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 @aiyou-dev/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