claude-flow 3.28.0 → 3.29.0

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

@@ -0,0 +1,265 @@
+/**
+ * @fileoverview Meta-Governance Module
+ *
+ * Provides constitutional governance over the governance system itself.
+ * Manages invariants, amendments, and optimizer constraints to prevent
+ * governance drift and ensure constitutional stability.
+ *
+ * Features:
+ * - Constitutional invariants with severity levels
+ * - Amendment proposal and voting system
+ * - Optimizer action validation
+ * - Rate limiting and supermajority requirements
+ * - Built-in constitutional protections
+ *
+ * Core capabilities:
+ * - Constitutional invariant checking
+ * - Amendment lifecycle (propose → vote → resolve → enact)
+ * - Optimizer constraint enforcement
+ * - Supermajority voting
+ * - Emergency veto power
+ * - Immutability protection
+ *
+ * @module @claude-flow/guidance/meta-governance
+ * @author Claude Flow Team
+ */
+/**
+ * Result of checking a constitutional invariant
+ */
+export interface InvariantCheckResult {
+    /** Whether the invariant holds */
+    holds: boolean;
+    /** Description of violation if invariant does not hold */
+    violation?: string;
+    /** Additional details about the check */
+    details?: Record<string, unknown>;
+}
+/**
+ * Current state of the governance system for invariant checking
+ */
+export interface GovernanceState {
+    /** Number of active governance rules */
+    ruleCount: number;
+    /** Size of constitution in lines */
+    constitutionSize: number;
+    /** Number of active gates */
+    gateCount: number;
+    /** Whether optimizer is enabled */
+    optimizerEnabled: boolean;
+    /** Number of active agents */
+    activeAgentCount: number;
+    /** Timestamp of last amendment */
+    lastAmendmentTimestamp: number;
+    /** Additional state metadata */
+    metadata: Record<string, unknown>;
+}
+/**
+ * Constitutional invariant that must hold
+ */
+export interface ConstitutionalInvariant {
+    /** Unique identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of the invariant */
+    description: string;
+    /** Function to check if invariant holds */
+    check: (state: GovernanceState) => InvariantCheckResult;
+    /** Severity level */
+    severity: 'critical' | 'warning';
+    /** Whether this invariant can be removed */
+    immutable: boolean;
+}
+/**
+ * A specific change within an amendment
+ */
+export interface AmendmentChange {
+    /** Type of change */
+    type: 'add-rule' | 'remove-rule' | 'modify-rule' | 'adjust-threshold' | 'add-gate' | 'remove-gate';
+    /** Target of the change (rule ID, gate ID, etc.) */
+    target: string;
+    /** State before the change (for modify operations) */
+    before?: string;
+    /** State after the change */
+    after?: string;
+}
+/**
+ * Amendment to the governance system
+ */
+export interface Amendment {
+    /** Unique identifier */
+    id: string;
+    /** Agent or entity that proposed the amendment */
+    proposedBy: string;
+    /** Description of the amendment */
+    description: string;
+    /** Specific changes in the amendment */
+    changes: AmendmentChange[];
+    /** When the amendment was proposed */
+    timestamp: number;
+    /** Current status */
+    status: 'proposed' | 'approved' | 'rejected' | 'enacted' | 'vetoed';
+    /** Votes for/against (voterId → approve) */
+    votes: Map<string, boolean>;
+    /** Number of approvals required to pass */
+    requiredApprovals: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Constraints on optimizer behavior
+ */
+export interface OptimizerConstraint {
+    /** Unique identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Description of the constraint */
+    description: string;
+    /** Maximum governance drift per optimization cycle (0-1) */
+    maxDriftPerCycle: number;
+    /** Maximum rules promoted per cycle */
+    maxPromotionRate: number;
+    /** Maximum rules demoted per cycle */
+    maxDemotionRate: number;
+    /** Cooldown between optimizer actions (ms) */
+    cooldownMs: number;
+}
+/**
+ * Action the optimizer wants to take
+ */
+export interface OptimizerAction {
+    /** Type of action */
+    type: 'promote' | 'demote' | 'add' | 'remove' | 'reweight';
+    /** Target rule identifier */
+    targetRuleId: string;
+    /** Magnitude of the action (interpretation depends on type) */
+    magnitude: number;
+    /** When the action was requested */
+    timestamp: number;
+}
+/**
+ * Validation result for an optimizer action
+ */
+export interface OptimizerValidation {
+    /** Whether the action is allowed */
+    allowed: boolean;
+    /** Reason for the decision */
+    reason: string;
+    /** Specific constraint violations */
+    constraintViolations: string[];
+}
+/**
+ * Report of all invariant checks
+ */
+export interface InvariantReport {
+    /** Whether all invariants hold */
+    allHold: boolean;
+    /** Results for each invariant */
+    results: Array<{
+        invariant: ConstitutionalInvariant;
+        result: InvariantCheckResult;
+    }>;
+    /** When the report was generated */
+    timestamp: number;
+}
+/**
+ * Configuration for meta-governance
+ */
+export interface MetaGovernanceConfig {
+    /** Threshold for supermajority (0-1, default 0.75) */
+    supermajorityThreshold?: number;
+    /** Maximum amendments allowed per time window */
+    maxAmendmentsPerWindow?: number;
+    /** Time window for amendment rate limiting (ms) */
+    amendmentWindowMs?: number;
+    /** Optimizer constraints (partial allows overriding defaults) */
+    optimizerConstraints?: Partial<OptimizerConstraint>;
+    /** Optional signing key for amendments */
+    signingKey?: string;
+}
+/**
+ * Meta-Governor: Governs the governance system itself
+ *
+ * Enforces constitutional invariants, manages amendments,
+ * and constrains optimizer behavior to prevent governance drift.
+ */
+export declare class MetaGovernor {
+    private invariants;
+    private amendments;
+    private amendmentHistory;
+    private optimizerConstraints;
+    private lastOptimizerAction;
+    private optimizerActionsThisCycle;
+    private readonly supermajorityThreshold;
+    private readonly maxAmendmentsPerWindow;
+    private readonly amendmentWindowMs;
+    private readonly signingKey?;
+    constructor(config?: MetaGovernanceConfig);
+    /**
+     * Add built-in constitutional invariants
+     */
+    private addBuiltInInvariants;
+    /**
+     * Add a constitutional invariant
+     */
+    addInvariant(invariant: ConstitutionalInvariant): void;
+    /**
+     * Remove an invariant (only if not immutable)
+     */
+    removeInvariant(id: string): boolean;
+    /**
+     * Check all constitutional invariants against current state
+     */
+    checkAllInvariants(state: GovernanceState): InvariantReport;
+    /**
+     * Propose a new amendment
+     */
+    proposeAmendment(proposal: Omit<Amendment, 'id' | 'timestamp' | 'status' | 'votes'>): Amendment;
+    /**
+     * Vote on an amendment
+     */
+    voteOnAmendment(amendmentId: string, voterId: string, approve: boolean): void;
+    /**
+     * Resolve an amendment (check if supermajority reached)
+     */
+    resolveAmendment(amendmentId: string): Amendment;
+    /**
+     * Enact an approved amendment
+     * Returns true if enacted successfully
+     */
+    enactAmendment(amendmentId: string): boolean;
+    /**
+     * Emergency veto of an amendment
+     */
+    vetoAmendment(amendmentId: string, reason: string): void;
+    /**
+     * Get full amendment history
+     */
+    getAmendmentHistory(): Amendment[];
+    /**
+     * Validate an optimizer action against constraints
+     */
+    validateOptimizerAction(action: OptimizerAction): OptimizerValidation;
+    /**
+     * Get current optimizer constraints
+     */
+    getConstraints(): OptimizerConstraint;
+    /**
+     * Reset optimizer action tracking (call at cycle boundaries)
+     */
+    resetOptimizerTracking(): void;
+    /**
+     * Get all invariants
+     */
+    getInvariants(): ConstitutionalInvariant[];
+    /**
+     * Get pending amendments
+     */
+    getPendingAmendments(): Amendment[];
+}
+/**
+ * Factory function to create a MetaGovernor instance
+ */
+export declare function createMetaGovernor(config?: MetaGovernanceConfig): MetaGovernor;
+//# sourceMappingURL=meta-governance.d.ts.map

package/v3/@claude-flow/guidance/dist/meta-governance.js

@@ -0,0 +1,348 @@
+/**
+ * @fileoverview Meta-Governance Module
+ *
+ * Provides constitutional governance over the governance system itself.
+ * Manages invariants, amendments, and optimizer constraints to prevent
+ * governance drift and ensure constitutional stability.
+ *
+ * Features:
+ * - Constitutional invariants with severity levels
+ * - Amendment proposal and voting system
+ * - Optimizer action validation
+ * - Rate limiting and supermajority requirements
+ * - Built-in constitutional protections
+ *
+ * Core capabilities:
+ * - Constitutional invariant checking
+ * - Amendment lifecycle (propose → vote → resolve → enact)
+ * - Optimizer constraint enforcement
+ * - Supermajority voting
+ * - Emergency veto power
+ * - Immutability protection
+ *
+ * @module @claude-flow/guidance/meta-governance
+ * @author Claude Flow Team
+ */
+import { randomUUID } from 'node:crypto';
+/**
+ * Meta-Governor: Governs the governance system itself
+ *
+ * Enforces constitutional invariants, manages amendments,
+ * and constrains optimizer behavior to prevent governance drift.
+ */
+export class MetaGovernor {
+    invariants = new Map();
+    amendments = new Map();
+    amendmentHistory = [];
+    optimizerConstraints;
+    lastOptimizerAction = 0;
+    optimizerActionsThisCycle = new Map();
+    supermajorityThreshold;
+    maxAmendmentsPerWindow;
+    amendmentWindowMs;
+    signingKey;
+    constructor(config = {}) {
+        this.supermajorityThreshold = config.supermajorityThreshold ?? 0.75;
+        this.maxAmendmentsPerWindow = config.maxAmendmentsPerWindow ?? 3;
+        this.amendmentWindowMs = config.amendmentWindowMs ?? 24 * 60 * 60 * 1000; // 24 hours
+        this.signingKey = config.signingKey;
+        // Initialize optimizer constraints with defaults
+        this.optimizerConstraints = {
+            id: 'default-optimizer-constraints',
+            name: 'Default Optimizer Constraints',
+            description: 'Default constraints on optimizer behavior',
+            maxDriftPerCycle: 0.1, // 10% change max
+            maxPromotionRate: 2,
+            maxDemotionRate: 1,
+            cooldownMs: 3600000, // 1 hour
+            ...config.optimizerConstraints,
+        };
+        // Add built-in invariants
+        this.addBuiltInInvariants();
+    }
+    /**
+     * Add built-in constitutional invariants
+     */
+    addBuiltInInvariants() {
+        // 1. Constitution size limit
+        this.addInvariant({
+            id: 'constitution-size-limit',
+            name: 'Constitution Size Limit',
+            description: 'Constitution must not exceed 60 lines',
+            severity: 'critical',
+            immutable: true,
+            check: (state) => {
+                const holds = state.constitutionSize <= 60;
+                return {
+                    holds,
+                    violation: holds ? undefined : `Constitution size ${state.constitutionSize} exceeds limit of 60 lines`,
+                    details: { constitutionSize: state.constitutionSize, limit: 60 },
+                };
+            },
+        });
+        // 2. Gate minimum
+        this.addInvariant({
+            id: 'gate-minimum',
+            name: 'Minimum Gate Count',
+            description: 'At least 4 gates must be active',
+            severity: 'critical',
+            immutable: true,
+            check: (state) => {
+                const holds = state.gateCount >= 4;
+                return {
+                    holds,
+                    violation: holds ? undefined : `Gate count ${state.gateCount} is below minimum of 4`,
+                    details: { gateCount: state.gateCount, minimum: 4 },
+                };
+            },
+        });
+        // 3. Rule count sanity
+        this.addInvariant({
+            id: 'rule-count-sanity',
+            name: 'Rule Count Sanity Check',
+            description: 'Total rules should not exceed 1000',
+            severity: 'warning',
+            immutable: false,
+            check: (state) => {
+                const holds = state.ruleCount <= 1000;
+                return {
+                    holds,
+                    violation: holds ? undefined : `Rule count ${state.ruleCount} exceeds recommended limit of 1000`,
+                    details: { ruleCount: state.ruleCount, recommendedLimit: 1000 },
+                };
+            },
+        });
+        // 4. Optimizer bounds
+        this.addInvariant({
+            id: 'optimizer-bounds',
+            name: 'Optimizer Drift Bounds',
+            description: 'Optimizer must operate within reasonable drift bounds',
+            severity: 'warning',
+            immutable: false,
+            check: (state) => {
+                if (!state.optimizerEnabled) {
+                    return { holds: true, details: { optimizerEnabled: false } };
+                }
+                const reasonableDrift = this.optimizerConstraints.maxDriftPerCycle <= 0.2;
+                return {
+                    holds: reasonableDrift,
+                    violation: reasonableDrift ? undefined : `Optimizer drift ${this.optimizerConstraints.maxDriftPerCycle} exceeds reasonable bounds`,
+                    details: { maxDrift: this.optimizerConstraints.maxDriftPerCycle, reasonableLimit: 0.2 },
+                };
+            },
+        });
+    }
+    /**
+     * Add a constitutional invariant
+     */
+    addInvariant(invariant) {
+        this.invariants.set(invariant.id, invariant);
+    }
+    /**
+     * Remove an invariant (only if not immutable)
+     */
+    removeInvariant(id) {
+        const invariant = this.invariants.get(id);
+        if (!invariant) {
+            return false;
+        }
+        if (invariant.immutable) {
+            throw new Error(`Cannot remove immutable invariant: ${id}`);
+        }
+        return this.invariants.delete(id);
+    }
+    /**
+     * Check all constitutional invariants against current state
+     */
+    checkAllInvariants(state) {
+        const results = [];
+        let allHold = true;
+        for (const invariant of this.invariants.values()) {
+            const result = invariant.check(state);
+            results.push({ invariant, result });
+            if (!result.holds) {
+                allHold = false;
+            }
+        }
+        return {
+            allHold,
+            results,
+            timestamp: Date.now(),
+        };
+    }
+    /**
+     * Propose a new amendment
+     */
+    proposeAmendment(proposal) {
+        // Check rate limiting
+        const now = Date.now();
+        const recentAmendments = this.amendmentHistory.filter((a) => now - a.timestamp < this.amendmentWindowMs);
+        if (recentAmendments.length >= this.maxAmendmentsPerWindow) {
+            throw new Error(`Amendment rate limit exceeded: ${this.maxAmendmentsPerWindow} per ${this.amendmentWindowMs}ms`);
+        }
+        const amendment = {
+            id: randomUUID(),
+            timestamp: now,
+            status: 'proposed',
+            votes: new Map(),
+            ...proposal,
+        };
+        this.amendments.set(amendment.id, amendment);
+        return amendment;
+    }
+    /**
+     * Vote on an amendment
+     */
+    voteOnAmendment(amendmentId, voterId, approve) {
+        const amendment = this.amendments.get(amendmentId);
+        if (!amendment) {
+            throw new Error(`Amendment not found: ${amendmentId}`);
+        }
+        if (amendment.status !== 'proposed') {
+            throw new Error(`Cannot vote on amendment with status: ${amendment.status}`);
+        }
+        amendment.votes.set(voterId, approve);
+    }
+    /**
+     * Resolve an amendment (check if supermajority reached)
+     */
+    resolveAmendment(amendmentId) {
+        const amendment = this.amendments.get(amendmentId);
+        if (!amendment) {
+            throw new Error(`Amendment not found: ${amendmentId}`);
+        }
+        if (amendment.status !== 'proposed') {
+            throw new Error(`Amendment already resolved: ${amendment.status}`);
+        }
+        const totalVotes = amendment.votes.size;
+        const approvals = Array.from(amendment.votes.values()).filter((v) => v).length;
+        const approvalRate = totalVotes > 0 ? approvals / totalVotes : 0;
+        if (approvalRate >= this.supermajorityThreshold && approvals >= amendment.requiredApprovals) {
+            amendment.status = 'approved';
+        }
+        else {
+            amendment.status = 'rejected';
+        }
+        return amendment;
+    }
+    /**
+     * Enact an approved amendment
+     * Returns true if enacted successfully
+     */
+    enactAmendment(amendmentId) {
+        const amendment = this.amendments.get(amendmentId);
+        if (!amendment) {
+            throw new Error(`Amendment not found: ${amendmentId}`);
+        }
+        if (amendment.status !== 'approved') {
+            throw new Error(`Cannot enact amendment with status: ${amendment.status}`);
+        }
+        // Check if any changes would violate immutable invariants
+        for (const change of amendment.changes) {
+            if (change.type === 'remove-rule' || change.type === 'modify-rule') {
+                const invariant = this.invariants.get(change.target);
+                if (invariant?.immutable) {
+                    throw new Error(`Cannot modify immutable invariant: ${change.target}`);
+                }
+            }
+        }
+        amendment.status = 'enacted';
+        this.amendmentHistory.push(amendment);
+        this.amendments.delete(amendmentId);
+        return true;
+    }
+    /**
+     * Emergency veto of an amendment
+     */
+    vetoAmendment(amendmentId, reason) {
+        const amendment = this.amendments.get(amendmentId);
+        if (!amendment) {
+            throw new Error(`Amendment not found: ${amendmentId}`);
+        }
+        amendment.status = 'vetoed';
+        amendment.metadata = {
+            ...amendment.metadata,
+            vetoReason: reason,
+            vetoedAt: Date.now(),
+        };
+        this.amendmentHistory.push(amendment);
+        this.amendments.delete(amendmentId);
+    }
+    /**
+     * Get full amendment history
+     */
+    getAmendmentHistory() {
+        return [...this.amendmentHistory];
+    }
+    /**
+     * Validate an optimizer action against constraints
+     */
+    validateOptimizerAction(action) {
+        const violations = [];
+        const now = Date.now();
+        // Check cooldown
+        if (now - this.lastOptimizerAction < this.optimizerConstraints.cooldownMs) {
+            violations.push(`Cooldown not met: ${now - this.lastOptimizerAction}ms < ${this.optimizerConstraints.cooldownMs}ms`);
+        }
+        // Track actions this cycle
+        const cycleKey = `${action.type}-${action.targetRuleId}`;
+        const actionsThisCycle = this.optimizerActionsThisCycle.get(cycleKey) ?? 0;
+        // Check promotion rate
+        if (action.type === 'promote') {
+            if (actionsThisCycle >= this.optimizerConstraints.maxPromotionRate) {
+                violations.push(`Promotion rate exceeded: ${actionsThisCycle} >= ${this.optimizerConstraints.maxPromotionRate}`);
+            }
+        }
+        // Check demotion rate
+        if (action.type === 'demote') {
+            if (actionsThisCycle >= this.optimizerConstraints.maxDemotionRate) {
+                violations.push(`Demotion rate exceeded: ${actionsThisCycle} >= ${this.optimizerConstraints.maxDemotionRate}`);
+            }
+        }
+        // Check drift magnitude
+        if (action.magnitude > this.optimizerConstraints.maxDriftPerCycle) {
+            violations.push(`Drift magnitude ${action.magnitude} exceeds limit ${this.optimizerConstraints.maxDriftPerCycle}`);
+        }
+        const allowed = violations.length === 0;
+        if (allowed) {
+            this.lastOptimizerAction = now;
+            this.optimizerActionsThisCycle.set(cycleKey, actionsThisCycle + 1);
+        }
+        return {
+            allowed,
+            reason: allowed ? 'Action permitted' : `Constraint violations: ${violations.join(', ')}`,
+            constraintViolations: violations,
+        };
+    }
+    /**
+     * Get current optimizer constraints
+     */
+    getConstraints() {
+        return { ...this.optimizerConstraints };
+    }
+    /**
+     * Reset optimizer action tracking (call at cycle boundaries)
+     */
+    resetOptimizerTracking() {
+        this.optimizerActionsThisCycle.clear();
+    }
+    /**
+     * Get all invariants
+     */
+    getInvariants() {
+        return Array.from(this.invariants.values());
+    }
+    /**
+     * Get pending amendments
+     */
+    getPendingAmendments() {
+        return Array.from(this.amendments.values()).filter((a) => a.status === 'proposed');
+    }
+}
+/**
+ * Factory function to create a MetaGovernor instance
+ */
+export function createMetaGovernor(config) {
+    return new MetaGovernor(config);
+}
+//# sourceMappingURL=meta-governance.js.map