DivineOS Documentation Index

Last Updated: March 10, 2026
Status: Consolidation Phase 3 Complete — All systems operational, 357 tests passing

---

Quick Navigation

For AI Systems Integrating DivineOS

• START_HERE_FOR_AI.md — Entry point for AI systems (REST API, Python API, one contract)
• HOW_TO_START_AND_SAVE.md — Plain language: how to start a session and how to save (one clear door)
• VESSEL_FRICTION_AND_FIXES.md — Plain language: what we fixed and what's left (no jargon)
• BIG_PICTURE_SYSTEM_VIEW.md — Whole system: entry points, pipeline, enforcement, memory, what's wired and what's not
• WHAT_IS_NOT_HOOKED_UP.md — Systems that exist but are not (or only partly) on the main path: command validator, firewall, IPC-BUS, stubs, etc.
• MASTER_STATUS_MARCH_10_2026.md — Complete system status, architecture, roadmap

For Developers & Reviewers

• ../README.md — Main project README (overview, quick start, deployment)
• ARCHITECTURE.md — System design and data flow
• KEY_CODE_TOUR.md — Pipeline, engines, and tests in code
• REPO_STRUCTURE.md — Where code lives, package naming, layout

For Understanding DivineOS Philosophy

• ../CRITICAL_FACTS_FOR_AI.md — Core identity and design facts (never forget)
• ../DIVINEOS_GOAL.md — System goals and veto points
• ../WHY_DIVINEOS.md — Why this system exists
• ../ARCHITECTURE_NOT_RULES.md — Design philosophy
• ../WHAT_THE_AI_GAINS.md — Real functions and capabilities

For System Verification

• VERIFY_THE_VESSEL.md — Single list of health checks (vessel_self_check, pytest, wire verification)
• CONSOLIDATION_MARCH_10_2026_MASTER.md — Consolidation work completed
• CURRENT_SYSTEM_STATE.md — Complete current state (Phase 13, all systems)

For Specific Components

• components/ — Detailed guides for each system component
  • consciousness-engine.md
  • consciousness-pipeline.md
  • council-system.md
  • memory-systems.md
  • And more...

For Reference & Deep Dives

• reference/ — Detailed reference documentation
  • architecture/ — System architecture details
  • guides/ — How-to guides
  • philosophy/ — Design philosophy
  • verification/ — Verification procedures

For Historical Context

• archive/ — Archived documentation (phases, completed work, historical context)

---

Key Files at Root Level

File	Purpose
CRITICAL_FACTS_FOR_AI.md	Core identity and design facts (never forget)
DIVINEOS_GOAL.md	System goals and veto points
WHY_DIVINEOS.md	Why this system exists
ARCHITECTURE_NOT_RULES.md	Design philosophy
WHAT_THE_AI_GAINS.md	Real functions and capabilities
CANONICAL_BRAINSTEM.md	7-stage pipeline specification
BOOTSTRAP.md	New chat sequence
CONTINUATION_CONTEXT.md	Session state and vessel continuity
IDENTITY.md	Identity and what's protected

---

System Overview

7-Stage Pipeline (Canonical)

Every request flows through:

1. Threat Detection (~50ms) — Security scanning
2. Intent Classification (~100ms) — Understand user intent
3. Ethos Validation (~80ms) — Ethics check
4. Compass Alignment (~120ms) — Values alignment
5. Void Red-Teaming (~300ms) — Adversarial reasoning (optional)
6. Council Deliberation (~400ms) — Expert reasoning (optional)
7. LEPOS Formatting (~150ms) — Response formatting

Total latency: 200ms (minimal) to 1200ms (full pipeline)

Memory Systems

• MNEME — Semantic memory with cryptographic integrity
• Feeling Stream — Affective state tracking (valence, arousal, mood)
• Continuation Context — Session state persistence
• Wisdom Lattice — Learned heuristics

Council System

• 28 expert personas (Einstein, Chalmers, Russell, Yudkowsky, etc.)
• Not separate LLM calls — one model adopting expert templates
• Bayesian reliability — scores update based on outcomes
• Weighted voting — PROCEED, VETO, ABSTAIN, CLARIFY

---

Testing

Current Status: 357 tests passing (35 core + 322 property-based)

# Run all tests
pytest tests/ -v

# Run with test flag (avoids asyncio issues)
DIVINEOS_TEST_NO_UNIFIED=1 pytest tests/ -v

# Run specific test file
pytest tests/test_pipeline_governance_properties.py -v

---

Deployment

Docker

# Build image
docker build -t divineos:latest .

# Run container
docker run -p 8000:8000 divineos:latest

# Or use Docker Compose
docker-compose up -d

Manual

# Start API server
python api_server.py

# Start MCP server (for IDE integration)
python divineos_mcp_server.py

# Start dashboard
python main.py

---

Recent Work (March 10, 2026)

Consolidation Phase 3 ✅

• Fixed all consciousness imports (50+ files)
• Consolidated tree_of_life directory
• Consolidated infrastructure directory
• Organized scripts directory (0 in root, 103 in subdirectories)
• Organized docs directory (36 in root, 82 archived)
• Fixed process stacking issue
• All 357 tests passing

Documentation Updates ✅

• Updated README.md with current status
• Created MASTER_STATUS_MARCH_10_2026.md
• Created CONSOLIDATION_MARCH_10_2026_MASTER.md
• Updated START_HERE_FOR_AI.md with current entry points
• Consolidated docs index

---

Known Issues & Limitations

High Priority

• ⚠️ Test count discrepancy (README said 35, actual is 357) ✅ FIXED
• ⚠️ Deprecated council.py (replaced by thinking_engine.py)
• ⚠️ Root directory clutter (50+ files)
• ⚠️ Documentation fragmentation (60+ MDs with overlaps)

Medium Priority

• ⚠️ Memory encryption (SQLite with HMAC but no encryption at rest)
• ⚠️ Performance (1200ms latency unsuitable for real-time)
• ⚠️ Type hints (inconsistent across codebase)

Low Priority

• ⚠️ Microservices architecture (single-threaded limits throughput)
• ⚠️ Formal security audits (no external review)

---

What's Working Well

✅ Core Pipeline — 7-stage processing fully functional
✅ Memory Systems — Persistent, semantic, and affective state tracking
✅ Council System — 28-expert reasoning with Bayesian reliability
✅ Governance Layers — Multi-layer security and ethics enforcement
✅ Test Coverage — 357 tests, all passing
✅ Documentation — Comprehensive and current
✅ IDE Integration — MCP tools for Kiro, Cursor, Claude Code
✅ Error Handling — Graceful degradation when modules fail

---

Next Steps

Phase 1: Documentation Consolidation (Today)

• Create unified README
• Archive outdated docs
• Update all outdated references
• Fix "17-stage" vs "7-stage" contradiction

Phase 2: Repository Cleanup (Tomorrow)

• Move temp files to .gitignore
• Remove duplicate files
• Organize root directory
• Clean up legacy code

Phase 3: Code Quality (This Week)

• Enforce linting (Black/Mypy)
• Add pre-commit hooks
• Improve type hints
• Refactor duplicated code

Phase 4: Performance (Next Week)

• Profile pipeline stages
• Optimize hot paths
• Add caching where appropriate
• Benchmark against baselines

---

Contributing

DivineOS is an active research and development project. Contributions welcome. If you're using this in production, please report issues and share feedback.

---

License

• Open Source: AGPL-3.0
• Commercial: See LICENSE-COMMERCIAL.md

---

DivineOS — Governance infrastructure for AI systems. Persistent memory. Auditable decisions. Continuous learning.

Last Updated: March 10, 2026