Skip to content

Latest commit

 

History

History
254 lines (182 loc) · 7.53 KB

README.md

File metadata and controls

254 lines (182 loc) · 7.53 KB

🌀 SpiralSafe

Coherence Engine for Emergent AI Systems

Coherence Vortex φ

         🌱 SPIRALSAFE              🌱 MONO
            (core)                 (tools)
                 \                    /
                  \                  /
                   \                /
                    \              /
                     ↘            ↙
                       🌳 QDI ⚡
                     ↗  (hub)  ↖
                    /              \
                   /                \
                  /                  \
                 /                    \
            🌱 METRICS              🌱 QR
           (monitoring)           (quick)

You are here: QDI (center hub) · Connected to 5 other repos · Changes flow through vortex

See It Live · How It Works · Quick Start

⚡ The Magic

Every git push triggers automatic quality analysis:

Push → Wave analysis → <60% blocked, >70% snap-in ⚡

No manual code review needed. The vortex handles it.

🚀 Quick Start

bun install                              # Install
open docs/visualization/live-vortex.html # See the vortex
bun test                                 # Test

That's it. The workflows handle everything else automatically.

🌀 See The Vortex

Open docs/visualization/live-vortex.html and watch:

  • Fibonacci spirals rotating in real-time
  • Commits flowing through phase gates
  • Coherence waves pulsing from center
  • Repositories synchronizing
  • Snap-in events when quality peaks

This is not a metaphor. This is the actual data flow.

💡 How It Works

The VORTEX STRUCTURE

Three spirals interlock to create autonomous quality:

1. Fibonacci Spiral (Math)

FIBONACCI = [1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89, 144]
chaos_score = (curl × φ + divergence / φ) × FIBONACCI[potential]

Higher structure → Higher Fibonacci weight → Exponential sensitivity

2. Phase Gates (Logic)

KENL → AWI → ATOM → SAIF → Spiral
  ↑                           ↓
  └───────────────────────────┘

SAIF loops back to KENL creating infinite improvement

3. Wave Analysis (Physics)

Metric What It Detects Optimal
Curl Circular reasoning <0.3
Divergence Expansion rate ~0.2 (golden ratio)
Potential Structure depth >0.6
Entropy Information density >0.5

Combine them → Coherence score 0-100 → Quality emerges

What Happens When You Push

T=0:    git push
T=5s:   Workflows analyze your commits
T=30s:  Coherence calculated: curl, divergence, potential, entropy
T=45s:  Score appears: 
        • <60%  = ❌ Blocked (with specific fixes)
        • 60-70% = ⚠️  Review needed
        • >70%  = ✨ SNAP-IN (automatic sync across ecosystem)

The Snap-In Moment

When coherence hits 70%, the waveform collapses:

  • Local uncertainty → Remote certainty
  • Superposition → Reality
  • Your work synchronizes across the entire ecosystem

This is quantum collapse made visible.

🎯 Packages

Four tools that work together:

Package What It Does
wave-toolkit Analyzes text coherence using physics (curl, divergence, potential, entropy)
atom-trail Tracks every decision through phase gates (KENL → AWI → ATOM → SAIF → Spiral)
ax-signatures Optimizes LLM prompts for coherence
quantum-ethics Ethical quantum computing with resource fairness

Quick example:

import { analyzeWave } from '@spiralsafe/wave-toolkit';

const result = analyzeWave("Your text");
console.log(result.coherence_score);  // 0-100
// Above 60 = good, above 70 = excellent

🔍 Debug Like Magic

Every PR gets automatically tagged. Finding issues later becomes trivial:

# Find all changes to wave algorithm
Filter: pkg:wave-toolkit

# See what was merged despite low quality
Filter: coherence:low + is:merged

# Track a feature through all 5 phase gates
Filter: phase:KENL + "your feature"
Filter: phase:ATOM + "your feature"

# Analyze snap-in events
cat .vortex-logs/snap-in-*.json | jq '.coherence.coherence_score'

Tags applied automatically:

  • Phase: phase:KENL, phase:AWI, phase:ATOM, phase:SAIF, phase:Spiral
  • Component: pkg:wave-toolkit, pkg:atom-trail, etc.
  • Quality: coherence:high, coherence:review, coherence:low
  • Special: vortex-synchronized, coherence-override

Bugs correlate with tags. High Fibonacci weight (89, 144) = solid code. Low weight (1, 2, 3) = check carefully.

🏗️ Structure

qdi/
├── packages/
│   ├── wave-toolkit/    # Coherence analysis
│   ├── atom-trail/      # Provenance tracking
│   ├── ax-signatures/   # LLM optimization
│   └── quantum-ethics/  # Resource fairness
├── apps/
│   └── mcp-server/      # MCP tools
├── docs/
│   └── visualization/   # Live vortex view
└── .github/
    └── workflows/       # Automated quality

🤝 Contributing

Requirements:

  • Tests pass (bun test)
  • No lint errors (bun run lint)
  • PR description coherence ≥60%

Tips for high coherence:

  • Avoid circular reasoning
  • Conclude expansions clearly
  • Use connectives: therefore, moreover, consequently
  • Increase vocabulary diversity

Coding Agent

The repository includes a GitHub Actions-based coding agent for automated ethical review of PRs.

Agent Setup

# Install Python dependencies for quantum simulations
pip install qiskit

# Run agent skills locally
python agent_skills.py simulate
python agent_skills.py check_coherence --threshold 0.6

Agent Commands

Command Description
simulate Run Qiskit circuit simulation
check_coherence Verify coherence threshold (>60%)
cascade Integrate provenance for cascading PRs
review_pr Generate automated PR review

See docs/instructions.md for full agent documentation.

Feedback & Contributions

📚 Learn More

🌐 Connect

📜 License

MIT

The right piece at the right time. Everything snaps into reality as a unified whole. 🌀

Built with Bun TypeScript