moflo 4.8.31 → 4.8.32

package/src/@claude-flow/guidance/dist/truth-anchors.d.ts

@@ -1,276 +0,0 @@
-/**
- * Truth Anchor System
- *
- * Immutable, externally-signed facts that anchor the system to reality
- * beyond tool outputs and internal memory.
- *
- * A Truth Anchor is a fact that:
- * - Is immutable once recorded (cannot be overwritten or decayed)
- * - Is externally signed (by a human, hardware sensor, or external authority)
- * - Supersedes any internal belief that contradicts it
- * - Can be referenced but never mutated
- * - Has a verifiable signature chain
- *
- * TruthAnchorStore:
- * - Creates and signs new truth anchors with HMAC-SHA256
- * - Append-only storage (anchors are never mutated after creation)
- * - Retrieval by ID, time range, kind, attester, or tags
- * - Signature verification for individual anchors or the full store
- * - Supersession chain: new anchors can declare they supersede old ones
- * - Export/import for persistence and transfer
- * - Max 50,000 anchors with LRU eviction of expired ones only
- *
- * TruthResolver:
- * - Resolves conflicts between internal beliefs and truth anchors
- * - Memory conflict resolution (truth anchor always wins)
- * - Decision conflict resolution (constrains proposed actions)
- * - Topic-based ground truth retrieval with fuzzy tag matching
- *
- * @module @claude-flow/guidance/truth-anchors
- */
-/**
- * The kind of external source that attested to a truth anchor.
- */
-export type TruthSourceKind = 'human-attestation' | 'hardware-signal' | 'regulatory-input' | 'external-observation' | 'signed-document' | 'consensus-result';
-/**
- * An immutable, externally-signed fact anchored to the system.
- *
- * Once created, a TruthAnchor is never mutated. It can only be
- * superseded by a new anchor that references the old one.
- */
-export interface TruthAnchor {
-    /** Unique identifier (UUID v4) */
-    id: string;
-    /** The kind of external source that attested to this fact */
-    kind: TruthSourceKind;
-    /** The fact being asserted, in natural language */
-    claim: string;
-    /** Supporting data or evidence for the claim */
-    evidence: string;
-    /** Who or what signed this anchor (human ID, sensor ID, authority ID) */
-    attesterId: string;
-    /** HMAC-SHA256 signature over the canonical anchor content */
-    signature: string;
-    /** Unix timestamp (ms) when the anchor was created */
-    timestamp: number;
-    /** Unix timestamp (ms) when the fact became true */
-    validFrom: number;
-    /** Unix timestamp (ms) when the fact expires, or null for indefinite */
-    validUntil: number | null;
-    /** IDs of anchors that this anchor supersedes */
-    supersedes: string[];
-    /** Searchable tags for topic-based retrieval */
-    tags: string[];
-    /** Arbitrary metadata attached to the anchor */
-    metadata: Record<string, unknown>;
-}
-/**
- * Configuration for the TruthAnchorStore.
- */
-export interface TruthAnchorConfig {
-    /** HMAC-SHA256 signing key */
-    signingKey: string;
-    /** Maximum number of anchors to retain (default 50,000) */
-    maxAnchors: number;
-}
-/**
- * Parameters for creating a new truth anchor.
- */
-export interface AnchorParams {
-    kind: TruthSourceKind;
-    claim: string;
-    evidence: string;
-    attesterId: string;
-    validFrom?: number;
-    validUntil?: number | null;
-    supersedes?: string[];
-    tags?: string[];
-    metadata?: Record<string, unknown>;
-}
-/**
- * Query options for filtering truth anchors.
- */
-export interface TruthAnchorQuery {
-    /** Filter by source kind */
-    kind?: TruthSourceKind;
-    /** Filter by attester ID */
-    attesterId?: string;
-    /** Filter by tags (anchor must have at least one matching tag) */
-    tags?: string[];
-    /** Only return anchors valid at this timestamp */
-    validAt?: number;
-}
-/**
- * Result of verifying all anchors in the store.
- */
-export interface VerifyAllResult {
-    /** Number of anchors with valid signatures */
-    valid: number;
-    /** IDs of anchors with invalid signatures */
-    invalid: string[];
-}
-/**
- * Result of resolving a conflict between an internal belief and truth anchors.
- */
-export interface ConflictResolution {
-    /** Whether a truth anchor overrides the internal belief */
-    truthWins: boolean;
-    /** The truth anchor that overrides, if any */
-    anchor?: TruthAnchor;
-    /** Human-readable explanation of the resolution */
-    reason: string;
-}
-/**
- * Append-only store for truth anchors.
- *
- * Anchors are immutable once created. The store provides signing,
- * verification, querying, supersession, and capacity management
- * with LRU eviction of expired anchors only.
- */
-export declare class TruthAnchorStore {
-    private readonly config;
-    private readonly anchors;
-    private readonly indexById;
-    constructor(config?: Partial<TruthAnchorConfig>);
-    /**
-     * Create and sign a new truth anchor.
-     *
-     * The anchor is appended to the store and can never be mutated.
-     * If the store exceeds capacity, expired anchors are evicted
-     * starting from the oldest.
-     */
-    anchor(params: AnchorParams): TruthAnchor;
-    /**
-     * Retrieve a truth anchor by its ID.
-     *
-     * Returns undefined if the anchor does not exist.
-     */
-    get(id: string): TruthAnchor | undefined;
-    /**
-     * Get all anchors that are valid at the given timestamp.
-     *
-     * An anchor is active when:
-     * - `validFrom <= timestamp`
-     * - `validUntil` is null (indefinite) or `validUntil > timestamp`
-     *
-     * Defaults to the current time if no timestamp is provided.
-     */
-    getActive(timestamp?: number): TruthAnchor[];
-    /**
-     * Query anchors with optional filters.
-     *
-     * All provided filters are ANDed together. An anchor must match
-     * every specified filter to be included in the result.
-     */
-    query(opts: TruthAnchorQuery): TruthAnchor[];
-    /**
-     * Verify the HMAC-SHA256 signature of a single anchor.
-     *
-     * Recomputes the signature from the anchor's content and compares
-     * it to the stored signature. Returns true if they match.
-     */
-    verify(id: string): boolean;
-    /**
-     * Verify all anchors in the store.
-     *
-     * Returns a summary with the count of valid anchors and the
-     * IDs of any anchors whose signatures do not match.
-     */
-    verifyAll(): VerifyAllResult;
-    /**
-     * Create a new anchor that supersedes an existing one.
-     *
-     * The old anchor remains in the store (immutable) but the new
-     * anchor's `supersedes` array includes the old anchor's ID.
-     * This creates a verifiable supersession chain.
-     *
-     * Throws if the old anchor ID does not exist.
-     */
-    supersede(oldId: string, params: AnchorParams): TruthAnchor;
-    /**
-     * Resolve a claim against an internal belief.
-     *
-     * Searches for active truth anchors whose claim matches the
-     * provided claim text. If a matching truth anchor exists and
-     * is currently valid, it wins over the internal belief.
-     *
-     * Returns the truth anchor if it exists, otherwise returns
-     * undefined (meaning the internal belief stands).
-     */
-    resolve(claim: string, _internalBelief: string): TruthAnchor | undefined;
-    /**
-     * Export all anchors for persistence or transfer.
-     *
-     * Returns a shallow copy of the anchor array. The individual
-     * anchor objects are returned as-is since they are immutable.
-     */
-    exportAnchors(): TruthAnchor[];
-    /**
-     * Import anchors from an external source.
-     *
-     * Imported anchors are appended to the store. Duplicate IDs
-     * (anchors already in the store) are silently skipped.
-     * Capacity enforcement runs after import.
-     */
-    importAnchors(anchors: TruthAnchor[]): void;
-    /**
-     * Get the total number of anchors in the store.
-     */
-    get size(): number;
-    /**
-     * Enforce the maximum anchor capacity.
-     *
-     * Only expired anchors are evicted, starting from the oldest.
-     * If no expired anchors can be evicted and the store is still
-     * over capacity, the oldest expired anchors are removed first.
-     * Active (non-expired) anchors are never evicted.
-     */
-    private enforceCapacity;
-}
-/**
- * Resolves conflicts between internal system beliefs and externally
- * anchored truth.
- *
- * The fundamental principle: truth anchors always win. If a valid,
- * active truth anchor contradicts an internal belief, the anchor
- * takes precedence.
- */
-export declare class TruthResolver {
-    private readonly store;
-    constructor(store: TruthAnchorStore);
-    /**
-     * Check if any active truth anchor contradicts a memory value.
-     *
-     * Searches by namespace and key as tags, and by the memory value
-     * as a claim. If a truth anchor exists that covers the same topic,
-     * it wins over the internal memory.
-     */
-    resolveMemoryConflict(memoryKey: string, memoryValue: string, namespace: string): ConflictResolution;
-    /**
-     * Check if any active truth anchor constrains a proposed action.
-     *
-     * Searches for anchors whose claims or tags relate to the proposed
-     * action and its context. Returns a conflict resolution indicating
-     * whether the action is constrained.
-     */
-    resolveDecisionConflict(proposedAction: string, context: Record<string, unknown>): ConflictResolution;
-    /**
-     * Get all active truth anchors relevant to a topic.
-     *
-     * Uses fuzzy tag matching: a tag matches the topic if either
-     * the tag contains the topic or the topic contains the tag
-     * (case-insensitive). Also matches against the claim text.
-     */
-    getGroundTruth(topic: string): TruthAnchor[];
-}
-/**
- * Create a TruthAnchorStore with the given configuration.
- *
- * @param config - Must include `signingKey`. `maxAnchors` defaults to 50,000.
- */
-export declare function createTruthAnchorStore(config?: Partial<TruthAnchorConfig>): TruthAnchorStore;
-/**
- * Create a TruthResolver backed by the given store.
- */
-export declare function createTruthResolver(store: TruthAnchorStore): TruthResolver;
-//# sourceMappingURL=truth-anchors.d.ts.map

package/src/@claude-flow/guidance/dist/types.d.ts

@@ -1,378 +0,0 @@
-/**
- * Guidance Control Plane - Type Definitions
- *
- * Types for the guidance compiler, shard retriever, enforcement gates,
- * run ledger, evaluators, and optimizer loop.
- *
- * @module @claude-flow/guidance/types
- */
-/**
- * Risk classification for rules
- */
-export type RiskClass = 'critical' | 'high' | 'medium' | 'low' | 'info';
-/**
- * Tool class a rule applies to
- */
-export type ToolClass = 'edit' | 'bash' | 'read' | 'write' | 'mcp' | 'task' | 'all';
-/**
- * Intent categories for task classification
- */
-export type TaskIntent = 'bug-fix' | 'feature' | 'refactor' | 'security' | 'performance' | 'testing' | 'docs' | 'deployment' | 'architecture' | 'debug' | 'general';
-/**
- * A single guidance rule
- */
-export interface GuidanceRule {
-    /** Unique rule identifier (e.g., R001) */
-    id: string;
-    /** Human-readable rule text */
-    text: string;
-    /** Risk classification */
-    riskClass: RiskClass;
-    /** Which tool classes this rule applies to */
-    toolClasses: ToolClass[];
-    /** Task intents this rule is relevant for */
-    intents: TaskIntent[];
-    /** Repository path globs where this rule applies */
-    repoScopes: string[];
-    /** Domain tags (security, testing, architecture, etc.) */
-    domains: string[];
-    /** Priority (higher = takes precedence in contradictions) */
-    priority: number;
-    /** Source file this rule came from */
-    source: 'root' | 'local' | 'optimizer';
-    /** Whether this rule is part of the always-loaded constitution */
-    isConstitution: boolean;
-    /** Optional verifier function name or pattern */
-    verifier?: string;
-    /** Rule creation timestamp */
-    createdAt: number;
-    /** Last modification timestamp */
-    updatedAt: number;
-}
-/**
- * A rule shard - a short snippet tagged for retrieval
- */
-export interface RuleShard {
-    /** The rule this shard represents */
-    rule: GuidanceRule;
-    /** Compact text form for injection into context */
-    compactText: string;
-    /** Embedding vector for semantic retrieval */
-    embedding?: Float32Array;
-}
-/**
- * The constitution - always-loaded core rules
- */
-export interface Constitution {
-    /** Rules that must always be active */
-    rules: GuidanceRule[];
-    /** Compact text representation (30-60 lines) */
-    text: string;
-    /** Hash for change detection */
-    hash: string;
-}
-/**
- * Machine-readable manifest of all rules
- */
-export interface RuleManifest {
-    /** All rule IDs with their triggers and verifiers */
-    rules: Array<{
-        id: string;
-        triggers: string[];
-        verifier: string | null;
-        riskClass: RiskClass;
-        priority: number;
-        source: string;
-    }>;
-    /** Compilation timestamp */
-    compiledAt: number;
-    /** Source file hashes */
-    sourceHashes: Record<string, string>;
-    /** Total rule count */
-    totalRules: number;
-    /** Constitution rule count */
-    constitutionRules: number;
-    /** Shard rule count */
-    shardRules: number;
-}
-/**
- * Compiled policy bundle output
- */
-export interface PolicyBundle {
-    /** The always-loaded constitution */
-    constitution: Constitution;
-    /** Task-scoped rule shards for retrieval */
-    shards: RuleShard[];
-    /** Machine-readable manifest */
-    manifest: RuleManifest;
-}
-/**
- * Retrieval request
- */
-export interface RetrievalRequest {
-    /** Task description to match against */
-    taskDescription: string;
-    /** Optional intent override */
-    intent?: TaskIntent;
-    /** Optional risk class filter */
-    riskFilter?: RiskClass[];
-    /** Optional repo path filter */
-    repoScope?: string;
-    /** Maximum shards to retrieve */
-    maxShards?: number;
-}
-/**
- * Retrieval result
- */
-export interface RetrievalResult {
-    /** The constitution (always included) */
-    constitution: Constitution;
-    /** Retrieved shards, ordered by relevance */
-    shards: Array<{
-        shard: RuleShard;
-        similarity: number;
-        reason: string;
-    }>;
-    /** Detected task intent */
-    detectedIntent: TaskIntent;
-    /** Whether any contradictions were found and resolved */
-    contradictionsResolved: number;
-    /** Combined policy text for injection */
-    policyText: string;
-    /** Retrieval latency in ms */
-    latencyMs: number;
-}
-/**
- * Gate decision
- */
-export type GateDecision = 'allow' | 'block' | 'warn' | 'require-confirmation';
-/**
- * Gate evaluation result
- */
-export interface GateResult {
-    /** The decision */
-    decision: GateDecision;
-    /** Gate that produced this result */
-    gateName: string;
-    /** Reason for the decision */
-    reason: string;
-    /** Rule IDs that triggered this gate */
-    triggeredRules: string[];
-    /** Suggested remediation */
-    remediation?: string;
-    /** Additional metadata */
-    metadata?: Record<string, unknown>;
-}
-/**
- * Gate configuration
- */
-export interface GateConfig {
-    /** Enable destructive ops gate */
-    destructiveOps: boolean;
-    /** Enable tool allowlist gate */
-    toolAllowlist: boolean;
-    /** Enable diff size gate */
-    diffSize: boolean;
-    /** Enable secrets detection gate */
-    secrets: boolean;
-    /** Diff size threshold (lines) before requiring a plan */
-    diffSizeThreshold: number;
-    /** Allowed tools list (empty = all allowed) */
-    allowedTools: string[];
-    /** Custom secret patterns */
-    secretPatterns: RegExp[];
-    /** Destructive command patterns */
-    destructivePatterns: RegExp[];
-}
-/**
- * Run event logged to the ledger
- */
-export interface RunEvent {
-    /** Unique event ID */
-    eventId: string;
-    /** Task ID this event belongs to */
-    taskId: string;
-    /** Hash of the guidance bundle used */
-    guidanceHash: string;
-    /** Rule IDs that were active during this run */
-    retrievedRuleIds: string[];
-    /** Tools used during the task */
-    toolsUsed: string[];
-    /** Files touched during the task */
-    filesTouched: string[];
-    /** Summary of diffs produced */
-    diffSummary: {
-        linesAdded: number;
-        linesRemoved: number;
-        filesChanged: number;
-    };
-    /** Tests run and their results */
-    testResults: {
-        ran: boolean;
-        passed: number;
-        failed: number;
-        skipped: number;
-    };
-    /** Violations detected during the run */
-    violations: Violation[];
-    /** Whether the outcome was accepted */
-    outcomeAccepted: boolean | null;
-    /** Lines of rework needed */
-    reworkLines: number;
-    /** Task intent classification */
-    intent: TaskIntent;
-    /** Timestamp */
-    timestamp: number;
-    /** Duration in ms */
-    durationMs: number;
-    /** Session ID */
-    sessionId?: string;
-}
-/**
- * A rule violation
- */
-export interface Violation {
-    /** Rule ID that was violated */
-    ruleId: string;
-    /** Violation description */
-    description: string;
-    /** Severity */
-    severity: RiskClass;
-    /** Where the violation occurred */
-    location?: string;
-    /** Whether it was auto-corrected */
-    autoCorrected: boolean;
-}
-/**
- * Evaluator result
- */
-export interface EvaluatorResult {
-    /** Evaluator name */
-    name: string;
-    /** Pass or fail */
-    passed: boolean;
-    /** Details */
-    details: string;
-    /** Score (0-1) for subjective evaluators */
-    score?: number;
-}
-/**
- * Violation ranking entry
- */
-export interface ViolationRanking {
-    /** Rule ID */
-    ruleId: string;
-    /** Number of times violated */
-    frequency: number;
-    /** Estimated cost (rework lines) */
-    cost: number;
-    /** Combined score (frequency * cost) */
-    score: number;
-}
-/**
- * Proposed rule change
- */
-export interface RuleChange {
-    /** Change ID */
-    changeId: string;
-    /** Target rule ID (or 'new' for new rules) */
-    targetRuleId: string;
-    /** Type of change */
-    changeType: 'modify' | 'add' | 'remove' | 'promote' | 'demote';
-    /** Original rule text (if modifying) */
-    originalText?: string;
-    /** Proposed new text */
-    proposedText: string;
-    /** Rationale */
-    rationale: string;
-    /** Violation ranking that triggered this */
-    triggeringViolation: ViolationRanking;
-}
-/**
- * A/B test result for rule changes
- */
-export interface ABTestResult {
-    /** Change being tested */
-    change: RuleChange;
-    /** Metrics with the original rule */
-    baseline: OptimizationMetrics;
-    /** Metrics with the changed rule */
-    candidate: OptimizationMetrics;
-    /** Whether the change should be promoted */
-    shouldPromote: boolean;
-    /** Reason for decision */
-    reason: string;
-}
-/**
- * Optimization metrics
- */
-export interface OptimizationMetrics {
-    /** Violations per 10 tasks */
-    violationRate: number;
-    /** Self-correction rate */
-    selfCorrectionRate: number;
-    /** Rework lines after first output */
-    reworkLines: number;
-    /** Clarifying questions per task */
-    clarifyingQuestions: number;
-    /** Number of tasks measured */
-    taskCount: number;
-}
-/**
- * ADR (Architecture Decision Record) for rule changes
- */
-export interface RuleADR {
-    /** ADR number */
-    number: number;
-    /** Title */
-    title: string;
-    /** Decision */
-    decision: string;
-    /** Rationale */
-    rationale: string;
-    /** Change applied */
-    change: RuleChange;
-    /** A/B test results */
-    testResult: ABTestResult;
-    /** Date */
-    date: number;
-}
-/**
- * Guidance Control Plane configuration
- */
-export interface GuidanceControlPlaneConfig {
-    /** Path to root CLAUDE.md */
-    rootGuidancePath: string;
-    /** Path to CLAUDE.local.md (optional) */
-    localGuidancePath?: string;
-    /** Gate configuration */
-    gates: Partial<GateConfig>;
-    /** Maximum shards to retrieve per task */
-    maxShardsPerTask: number;
-    /** Optimization cycle (in days) */
-    optimizationCycleDays: number;
-    /** Data directory for ledger and state */
-    dataDir: string;
-    /** Enable headless mode integration */
-    headlessMode: boolean;
-}
-/**
- * Control plane status
- */
-export interface ControlPlaneStatus {
-    /** Whether initialized */
-    initialized: boolean;
-    /** Constitution loaded */
-    constitutionLoaded: boolean;
-    /** Number of shards available */
-    shardCount: number;
-    /** Number of gates active */
-    activeGates: number;
-    /** Ledger event count */
-    ledgerEventCount: number;
-    /** Last optimization run */
-    lastOptimizationRun: number | null;
-    /** Metrics summary */
-    metrics: OptimizationMetrics | null;
-}
-//# sourceMappingURL=types.d.ts.map