ruvnet--ruflo/v3/plugins/prime-radiant/plugin.yaml

# Prime Radiant Plugin Manifest
# Mathematical AI Interpretability for Claude Flow V3

name: prime-radiant
version: 0.1.3
description: |
  Advanced mathematical AI interpretability plugin providing sheaf cohomology,
  spectral analysis, causal inference, and quantum topology for coherence
  validation, consensus verification, and hallucination prevention.

author: rUv
license: MIT
repository: https://github.com/ruvnet/claude-flow
documentation: https://github.com/ruvnet/claude-flow/blob/main/v3/plugins/prime-radiant/README.md

# Plugin metadata
metadata:
  category: interpretability
  tags:
    - sheaf-cohomology
    - causal-inference
    - quantum-topology
    - ai-interpretability
    - coherence-engine
    - rag
    - attention-mechanism
  stability: alpha
  wasmSize: 92KB
  dependencies: zero

# V3 domain integration
domains:
  - memory       # Pre-storage coherence gate
  - security     # Input validation
  - coordination # Swarm stability analysis
  - hive-mind    # Consensus verification

# Required Claude Flow dependencies
dependencies:
  required:
    - "@claude-flow/memory": ">=3.0.0"
    - "@claude-flow/security": ">=3.0.0"
    - "@claude-flow/coordination": ">=3.0.0"
  optional:
    - "@claude-flow/embeddings": ">=3.0.0"  # For embedding generation
    - "@claude-flow/aidefence": ">=3.0.0"   # For enhanced threat detection

# Capabilities provided by this plugin
capabilities:
  - coherence-checking      # Sheaf Laplacian contradiction detection
  - spectral-analysis       # Eigenvalue stability analysis
  - causal-inference        # Do-calculus interventional queries
  - consensus-verification  # Multi-agent agreement validation
  - quantum-topology        # Betti numbers, persistence diagrams
  - category-theory         # Functor and morphism operations
  - hott-proofs            # Homotopy Type Theory verification

# 6 Mathematical Engines
engines:
  cohomology:
    name: CohomologyEngine
    description: Sheaf Laplacian for coherence detection
    performance: "<5ms per check"
    key_features:
      - Sheaf Laplacian energy computation
      - Contradiction detection
      - Coherence scoring (0=coherent, 1=contradictory)

  spectral:
    name: SpectralEngine
    description: Stability and spectral analysis
    performance: "<20ms for 100x100 matrix"
    key_features:
      - Eigenvalue computation
      - Spectral gap analysis
      - Stability index calculation

  causal:
    name: CausalEngine
    description: Do-calculus causal inference
    performance: "<10ms per query"
    key_features:
      - Causal effect estimation
      - Confounder identification
      - Backdoor path detection

  quantum:
    name: QuantumEngine
    description: Quantum topology operations
    performance: "<50ms per computation"
    key_features:
      - Betti number computation
      - Persistence diagrams
      - Homology class counting

  category:
    name: CategoryEngine
    description: Category theory functors/morphisms
    performance: "<5ms per operation"
    key_features:
      - Morphism validation
      - Functor application
      - Natural transformation detection

  hott:
    name: HottEngine
    description: Homotopy Type Theory
    performance: "<10ms per verification"
    key_features:
      - Proof verification
      - Type inference
      - Term normalization

# MCP Tools
tools:
  - name: pr_coherence_check
    description: Check coherence of vectors using Sheaf Laplacian energy
    category: coherence
    input:
      vectors:
        type: array[array[number]]
        required: true
        description: Array of embedding vectors to check
      threshold:
        type: number
        default: 0.3
        description: Energy threshold for coherence (0-1)
    output:
      coherent: boolean
      energy: number
      violations: array[string]
      confidence: number

  - name: pr_spectral_analyze
    description: Analyze stability using spectral graph theory
    category: spectral
    input:
      adjacencyMatrix:
        type: array[array[number]]
        required: true
        description: Adjacency matrix representing connections
      analyzeType:
        type: enum[stability, clustering, connectivity]
        default: stability
    output:
      stable: boolean
      spectralGap: number
      stabilityIndex: number
      eigenvalues: array[number]

  - name: pr_causal_infer
    description: Perform causal inference using do-calculus
    category: causal
    input:
      treatment:
        type: string
        required: true
        description: Treatment/intervention variable
      outcome:
        type: string
        required: true
        description: Outcome variable
      graph:
        type: object
        required: true
        description: Causal graph with nodes and edges
    output:
      causalEffect: number
      confounders: array[string]
      interventionValid: boolean
      backdoorPaths: array[array[string]]

  - name: pr_consensus_verify
    description: Verify multi-agent consensus mathematically
    category: consensus
    input:
      agentStates:
        type: array[object]
        required: true
        description: Array of agent states with embeddings and votes
      consensusThreshold:
        type: number
        default: 0.8
        description: Required agreement threshold (0-1)
    output:
      consensusAchieved: boolean
      agreementRatio: number
      coherenceEnergy: number
      spectralStability: boolean

  - name: pr_quantum_topology
    description: Compute quantum topology features
    category: topology
    input:
      points:
        type: array[array[number]]
        required: true
        description: Point cloud for topological analysis
      maxDimension:
        type: number
        default: 2
        description: Maximum homology dimension to compute
    output:
      bettiNumbers: array[number]
      persistenceDiagram: array[array[number]]
      homologyClasses: number

  - name: pr_memory_gate
    description: Pre-storage coherence gate for memory entries
    category: memory
    input:
      entry:
        type: object
        required: true
        description: Memory entry with key, content, and embedding
      contextEmbeddings:
        type: array[array[number]]
        description: Existing context embeddings to check against
      thresholds:
        type: object
        description: Custom thresholds (reject, warn)
    output:
      action: enum[allow, warn, reject]
      coherent: boolean
      energy: number
      violations: array[string]

# Hooks
hooks:
  - name: pr/pre-memory-store
    event: pre-memory-store
    priority: high
    description: Validates memory entry coherence before storage
    behavior: |
      - Gets existing context from same namespace
      - Validates coherence using Sheaf Laplacian
      - Rejects entries with energy > 0.7
      - Warns for entries with energy 0.3-0.7
      - Adds coherence metadata to stored entries

  - name: pr/pre-consensus
    event: pre-consensus
    priority: high
    description: Validates consensus proposal coherence before voting
    behavior: |
      - Checks proposal against existing decisions
      - Rejects proposals with energy > 0.7
      - Adds coherence metrics to accepted proposals

  - name: pr/post-swarm-task
    event: post-task
    priority: normal
    description: Analyzes swarm stability after task completion
    conditions:
      - payload.isSwarmTask === true
    behavior: |
      - Builds communication adjacency matrix
      - Analyzes spectral stability
      - Stores stability metrics in memory
      - Adds stability metrics to task result

  - name: pr/pre-rag-retrieval
    event: pre-rag-retrieval
    priority: high
    description: Checks retrieved context coherence to prevent hallucinations
    behavior: |
      - Validates coherence of retrieved documents
      - Filters contradictory documents if energy > 0.5
      - Adds coherence filtering metadata

# Memory namespaces used
namespaces:
  - name: pr/coherence-checks
    description: Stores coherence check history
    retention: 7d

  - name: pr/stability-metrics
    description: Stores stability analysis results
    retention: 30d

  - name: pr/causal-models
    description: Stores causal relationship models
    retention: persistent

  - name: pr/thresholds
    description: Stores configured thresholds
    retention: persistent

# Configuration options
config:
  coherence:
    warnThreshold:
      type: number
      default: 0.3
      description: Energy threshold for warnings
    rejectThreshold:
      type: number
      default: 0.7
      description: Energy threshold for rejection
    cacheEnabled:
      type: boolean
      default: true
      description: Enable result caching
    cacheTTL:
      type: number
      default: 60000
      description: Cache TTL in milliseconds

  spectral:
    stabilityThreshold:
      type: number
      default: 0.1
      description: Spectral gap threshold for stability
    maxMatrixSize:
      type: number
      default: 1000
      description: Maximum adjacency matrix size

  causal:
    maxBackdoorPaths:
      type: number
      default: 10
      description: Maximum backdoor paths to compute
    confidenceThreshold:
      type: number
      default: 0.8
      description: Minimum confidence for effect estimation

# Performance targets
performance:
  wasmLoadTime: "<50ms"
  coherenceCheck: "<5ms"
  spectralAnalysis: "<20ms"
  causalInference: "<10ms"
  memoryOverhead: "<10MB"
  mcpToolResponse: "<100ms"

# Use cases
useCases:
  - name: Memory Coherence Gate
    description: Check vectors for contradiction before storage
    domains: [memory]
    tools: [pr_memory_gate, pr_coherence_check]
    hooks: [pr/pre-memory-store]

  - name: Consensus Verification
    description: Mathematically validate multi-agent agreement
    domains: [hive-mind, coordination]
    tools: [pr_consensus_verify, pr_spectral_analyze]
    hooks: [pr/pre-consensus]

  - name: Hallucination Detection
    description: Catch RAG inconsistencies before use
    domains: [memory, security]
    tools: [pr_coherence_check]
    hooks: [pr/pre-rag-retrieval]

  - name: Swarm Stability Monitoring
    description: Spectral analysis of swarm coordination health
    domains: [coordination, hive-mind]
    tools: [pr_spectral_analyze]
    hooks: [pr/post-swarm-task]

# Related ADRs
references:
  - ADR-031: Prime Radiant Integration
  - ADR-006: Unified Memory Service
  - ADR-013: Core Security Module
  - ADR-015: Unified Plugin System
  - ADR-022: AIDefence Integration

# ═══════════════════════════════════════════════════════════════════════════════
# IMPLEMENTATION STATUS & CODE REVIEW
# ═══════════════════════════════════════════════════════════════════════════════

implementation:
  status: planning  # planning | in-progress | complete
  lastUpdated: "2026-01-23"
  reviewedBy: "code-reviewer"
  reviewDate: "2026-01-23"

  # Code Review Results
  codeReview:
    overallStatus: "architecture-complete"
    performanceTargetsMet: "pending-implementation"
    securityIssuesFound: 0
    documentationComplete: true
    testCoverage: "0%"

    # Performance Assessment (Critical Targets)
    performanceAssessment:
      wasmLoadTime:
        target: "<50ms"
        achievable: true
        notes: "92KB bundle, single load at init"
        optimization: "Lazy load WASM on first use"
      coherenceCheck:
        target: "<5ms"
        achievable: true
        notes: "Core operation, must meet target"
        optimization: "LRU cache for repeated checks"
      spectralAnalysis:
        target: "<20ms"
        achievable: true
        notes: "For matrices up to 100x100"
        optimization: "Approximate methods for larger matrices"
      causalInference:
        target: "<10ms"
        achievable: true
        notes: "Single query operation"
      memoryOverhead:
        target: "<10MB"
        achievable: true
        notes: "WASM + 6 engine instances"
      mcpToolResponse:
        target: "<100ms"
        achievable: true
        notes: "V3 MCP requirement"

    # Architecture Quality
    architectureQuality:
      wasmBundleSize: "92KB (excellent)"
      zeroDependencies: true
      crossPlatform: true  # Browser + Node.js
      ddpPrinciples: true
      solidCompliance: "pending-verification"
      typeScriptStrict: "pending"
      zodValidation: "pending"
      errorHandling: "pending"

    # Integration Readiness
    integrationReadiness:
      pluginRegistration: "architecture-defined"
      mcpToolDiscovery: "architecture-defined"
      hookIntegration: "architecture-defined"
      memoryNamespaceIsolation: "architecture-defined"

    # Engine Status
    engineStatus:
      cohomologyEngine:
        status: "architecture-defined"
        priority: "critical"
        purpose: "Sheaf Laplacian coherence detection"
      spectralEngine:
        status: "architecture-defined"
        priority: "high"
        purpose: "Stability and eigenvalue analysis"
      causalEngine:
        status: "architecture-defined"
        priority: "medium"
        purpose: "Do-calculus causal inference"
      quantumEngine:
        status: "architecture-defined"
        priority: "low"
        purpose: "Quantum topology operations"
      categoryEngine:
        status: "architecture-defined"
        priority: "low"
        purpose: "Category theory operations"
      hottEngine:
        status: "architecture-defined"
        priority: "low"
        purpose: "Homotopy Type Theory proofs"

    # Critical Path Items
    criticalPathItems:
      - "Phase 1: WASM bridge and loader implementation"
      - "Phase 2: CohomologyEngine integration (coherence checking)"
      - "Phase 3: Memory pre-store hook for coherence gate"

    # Recommendations
    recommendations:
      - "Implement WASM lazy loading - load on first tool call, not plugin init"
      - "Add LRU cache with TTL for coherence check results (60s default)"
      - "Batch vector operations where possible for spectral analysis"
      - "Keep all TypeScript files under 500 lines"
      - "Add comprehensive JSDoc comments to all public APIs"
      - "Implement graceful degradation if WASM fails to load"
      - "Add telemetry for performance monitoring"

  # Required Files
  files:
    existing:
      - path: plugin.yaml
        status: complete
        lines: 450
        description: Plugin manifest with full configuration
      - path: README.md
        status: complete
        lines: 463
        description: Usage documentation

    required:
      # Phase 1: Plugin Scaffold
      - path: package.json
        status: pending
        phase: 1
        priority: critical
        estimatedLines: 40

      - path: tsconfig.json
        status: pending
        phase: 1
        priority: critical
        estimatedLines: 25

      - path: src/index.ts
        status: pending
        phase: 1
        priority: critical
        estimatedLines: 60
        description: Plugin entry point and exports

      - path: src/plugin.ts
        status: pending
        phase: 1
        priority: critical
        estimatedLines: 150
        description: PRPlugin class with lifecycle

      - path: src/types.ts
        status: pending
        phase: 1
        priority: critical
        estimatedLines: 200
        description: TypeScript type definitions

      # Phase 2: WASM Bridge
      - path: src/infrastructure/prime-radiant-bridge.ts
        status: pending
        phase: 2
        priority: critical
        estimatedLines: 300
        description: WASM bridge for 6 engines

      - path: src/infrastructure/cache.ts
        status: pending
        phase: 2
        priority: high
        estimatedLines: 100
        description: LRU cache with TTL

      # Phase 3: Domain Layer
      - path: src/domain/coherence-gate.ts
        status: pending
        phase: 3
        priority: critical
        estimatedLines: 200
        description: Coherence validation service

      - path: src/domain/stability-analyzer.ts
        status: pending
        phase: 3
        priority: high
        estimatedLines: 150
        description: Spectral stability analysis

      # Phase 4: MCP Tools (6 tools)
      - path: src/tools/index.ts
        status: pending
        phase: 4
        priority: critical
        estimatedLines: 50

      - path: src/tools/coherence-check.ts
        status: pending
        phase: 4
        priority: critical
        estimatedLines: 80

      - path: src/tools/spectral-analyze.ts
        status: pending
        phase: 4
        priority: high
        estimatedLines: 80

      - path: src/tools/causal-infer.ts
        status: pending
        phase: 4
        priority: medium
        estimatedLines: 100

      - path: src/tools/consensus-verify.ts
        status: pending
        phase: 4
        priority: high
        estimatedLines: 120

      - path: src/tools/quantum-topology.ts
        status: pending
        phase: 4
        priority: low
        estimatedLines: 80

      - path: src/tools/memory-gate.ts
        status: pending
        phase: 4
        priority: critical
        estimatedLines: 100

      # Phase 5: Hooks (4 hooks)
      - path: src/hooks/index.ts
        status: pending
        phase: 5
        priority: high
        estimatedLines: 40

      - path: src/hooks/pre-memory-store.ts
        status: pending
        phase: 5
        priority: critical
        estimatedLines: 80
        description: Coherence gate for memory storage

      - path: src/hooks/pre-consensus.ts
        status: pending
        phase: 5
        priority: high
        estimatedLines: 70

      - path: src/hooks/post-swarm-task.ts
        status: pending
        phase: 5
        priority: medium
        estimatedLines: 80

      - path: src/hooks/pre-rag-retrieval.ts
        status: pending
        phase: 5
        priority: high
        estimatedLines: 70
        description: Hallucination prevention

      # Phase 6: Integration
      - path: src/integration/memory-integration.ts
        status: pending
        phase: 6
        priority: high
        estimatedLines: 150

      - path: src/integration/hive-mind-integration.ts
        status: pending
        phase: 6
        priority: high
        estimatedLines: 180

      # Phase 7: Tests
      - path: vitest.config.ts
        status: pending
        phase: 7
        priority: high
        estimatedLines: 30

      - path: __tests__/unit/plugin.test.ts
        status: pending
        phase: 7
        priority: high
        estimatedLines: 100

      - path: __tests__/unit/coherence-gate.test.ts
        status: pending
        phase: 7
        priority: critical
        estimatedLines: 150

      - path: __tests__/integration/mcp-tools.test.ts
        status: pending
        phase: 7
        priority: high
        estimatedLines: 200

  # Phase Summary
  phases:
    - phase: 1
      name: Plugin Scaffold
      status: pending
      duration: "3 days"
      files: 5
      estimatedLines: 475
      deliverables:
        - Plugin registers with @claude-flow/plugins SDK
        - Type-safe configuration
        - Basic lifecycle hooks

    - phase: 2
      name: WASM Bridge
      status: pending
      duration: "3 days"
      files: 2
      estimatedLines: 400
      deliverables:
        - WASM loader with lazy initialization
        - All 6 engines accessible
        - Result caching

    - phase: 3
      name: Domain Layer
      status: pending
      duration: "2 days"
      files: 2
      estimatedLines: 350
      deliverables:
        - CoherenceGate service
        - StabilityAnalyzer service

    - phase: 4
      name: MCP Tools
      status: pending
      duration: "3 days"
      files: 7
      estimatedLines: 610
      deliverables:
        - All 6 MCP tools registered
        - Tools accessible via mcp__prime-radiant__*
        - Zod input validation

    - phase: 5
      name: Hooks
      status: pending
      duration: "2 days"
      files: 5
      estimatedLines: 340
      deliverables:
        - Pre-memory-store coherence gate
        - Pre-consensus validation
        - Post-task stability analysis
        - Pre-RAG hallucination prevention

    - phase: 6
      name: Domain Integration
      status: pending
      duration: "3 days"
      files: 2
      estimatedLines: 330
      deliverables:
        - Memory domain integration
        - Hive-Mind domain integration

    - phase: 7
      name: Testing
      status: pending
      duration: "3 days"
      files: 4
      estimatedLines: 480
      deliverables:
        - 80%+ test coverage
        - Integration tests passing
        - Performance benchmarks documented

  # Totals
  totals:
    totalPhases: 7
    totalDuration: "19 days (~4 weeks)"
    totalFiles: 27
    totalEstimatedLines: 2985

  # Final Checklist
  finalChecklist:
    allTestsPassing: pending
    noTypeScriptErrors: pending
    securityIssuesAddressed: pending  # None found
    performanceTargetsMet: pending
    documentationComplete: true
    filesUnder500Lines: pending
    consistentNaming: pending
    properErrorHandling: pending
    noAnyTypes: pending
    jsdocComments: pending