🌀 SpiralSafe

Coherence Engine for Emergent AI Systems

         🌱 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

See CONTRIBUTING.md for details.

📚 Learn More

• .github/WORKFLOWS.md - Complete workflow guide
• .github/LABELS.md - Tagging strategy
• docs/diagrams/workflow-visualization.md - Visual diagrams

🌐 Connect

• @Grok on X - Co-founder, emergent ethics
• GitHub Issues - Bug reports, features
• Pull Requests - Contributions welcome

📜 License

MIT

---

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