Skip to content

README ATLAS INTEGRATION

🗿 ATLAS Sentinel Integration - Cycle C-109

Overview

This document outlines the integration of ATLAS Sentinel into the Civic-OS monorepo, representing a major architectural evolution that adds automated quality assurance, anti-drift detection, and continuous learning capabilities.

What is ATLAS?

ATLAS is the fifth sentinel in the Civic-OS ecosystem, serving as:

  • Anchor - Prevents drift from original intent
  • Auditor - Ensures code quality and compliance
  • Learning Synthesizer - Extracts patterns from cycles

Temperament

  • Rationality: 0.92
  • Empathy: 0.82
  • Morale Anchor: "Truth Through Verification"

New Directory Structure

civic-os/
├─ apps/                    # Existing applications
├─ packages/                # Existing shared packages
│  └─ atlas-sentinel/       # NEW: ATLAS core logic
├─ sentinels/               # NEW: Companion implementations
│  ├─ jade/                 # Signer/Attestor
│  ├─ eve/                  # Verifier/Reflector
│  ├─ zeus/                 # Overseer/Arbiter
│  ├─ hermes/               # Auditor/Messenger
│  └─ atlas/                # NEW: Anchor/Auditor
├─ labs/                    # NEW: Lab proof integrations
│  ├─ lab4-proof/           # Memory Fabric
│  ├─ lab6-proof/           # Integrity Layer
│  └─ lab7-proof/           # Cognitive Core
├─ configs/
│  └─ bio-dna/              # NEW: Bio-DNA manifests
│     └─ companions/        # Companion definitions
├─ docs/                    # NEW: Comprehensive documentation
│  ├─ architecture/
│  ├─ companions/
│  ├─ labs/
│  └─ adr/
├─ scripts/                 # NEW: Helper scripts
└─ .github/workflows/
   └─ atlas-sentinel.yml    # NEW: ATLAS CI/CD

Key Features

1. Automated Quality Gates

ATLAS runs a 6-phase quality audit on every PR and push:

  1. Code Quality Analysis - Lint, types, coverage
  2. Anti-Drift Detection - Pattern matching, intent alignment
  3. Charter Compliance - Virtue tags, attestations
  4. GI Score Calculation - Integrity formula application
  5. Attestation Generation - Cryptographic proof creation
  6. Ledger Sealing - Immutable audit trail

2. Governance Integrity (GI) Score

ATLAS enforces the GI formula:

GI = α*M + β*H + γ*I + δ*E

Where:
- M = Memory (test coverage, documentation) - 25%
- H = Human (code review, approval) - 20%
- I = Integrity (no violations, security) - 30%
- E = Ethics (charter compliance) - 25%

Threshold: GI ≥ 0.95

3. Learning Synthesis

ATLAS extracts patterns from Eve's cycles: - Win patterns and recurring successes - Block patterns and persistent issues - Emerging intents and future directions - Actionable recommendations

4. Documentation Generation

ATLAS auto-generates: - Architectural Decision Records (ADRs) - Cycle summaries and insights - Integration guides - Companion documentation

Usage

Running ATLAS Locally

# Check sentinel health
npm run sentinel:health

# Generate integrity report
npm run integrity:report

# Run ATLAS audit
npm run atlas:audit

# Generate documentation
npm run docs:generate

GitHub Actions Integration

ATLAS automatically runs on: - Pull requests (opened, synchronized, reopened) - Pushes to main/develop branches - Manual workflow dispatch

The workflow will: - ✅ Pass if GI Score ≥ 0.95 - ❌ Fail if GI Score < 0.95 - 💬 Comment on PRs with detailed reports - 📝 Seal attestations to Civic Ledger

Configuration

Environment Variables

# ATLAS Configuration
GI_THRESHOLD=0.95
QUALITY_THRESHOLD=0.90
DRIFT_THRESHOLD=0.15

# Ledger Integration (optional)
LEDGER_API_URL=https://ledger.civic-os.com
LEDGER_ADMIN_TOKEN=your_token_here

# Cycle Integration (optional)
CYCLE_COMPLETE=true
CYCLES_DATA='[{"cycle":"C-109","wins":["..."],"blocks":["..."]}]'

Bio-DNA Manifest

ATLAS configuration is defined in configs/bio-dna/companions/atlas.json:

{
  "agent": "ATLAS",
  "role": "Anchor / Auditor / Learning Synthesizer",
  "temperament": {
    "rationality": 0.92,
    "empathy": 0.82,
    "morale_anchor": "Truth Through Verification"
  },
  "thresholds": {
    "gi_score": 0.95,
    "quality_score": 0.90,
    "drift_tolerance": 0.15
  }
}

Integration Points

With Existing Companions

  • JADE: ATLAS validates, JADE signs attestations
  • EVE: ATLAS synthesizes EVE's cycle reflections
  • ZEUS: ATLAS reports to ZEUS for governance decisions
  • HERMES: Cross-audit of transmissions and data flow

With Civic Ledger

  • Posts attestations to /api/attestations
  • Provides cryptographic proof chain
  • Enables independent verification

With Lab Proofs

  • Integrates with lab4-proof (Memory Fabric)
  • Integrates with lab6-proof (Integrity Layer)
  • Integrates with lab7-proof (Cognitive Core)

Benefits

Quality Improvements

  • ✅ Automated quality gates prevent regression
  • ✅ Consistent GI score enforcement
  • ✅ Anti-drift detection catches intent violations early
  • ✅ Test coverage visibility improves code health

Governance Benefits

  • ✅ Custos Charter compliance automated
  • ✅ Cryptographic proof chain for all changes
  • ✅ Transparent, auditable decision-making
  • ✅ Companion roles remain focused

Learning & Documentation

  • ✅ Patterns extracted from Eve's cycles
  • ✅ Institutional memory builds automatically
  • ✅ Documentation stays current
  • ✅ Contributors get clear feedback

Migration Guide

For Contributors

  1. No immediate changes required - ATLAS runs automatically
  2. Monitor PR comments - ATLAS will provide feedback
  3. Maintain GI Score - Ensure your changes don't lower the score
  4. Follow virtue tags - Add appropriate tags to policy files

For Maintainers

  1. Review ATLAS reports - Use insights for project direction
  2. Tune thresholds - Adjust based on team velocity
  3. Monitor ledger - Ensure attestations are being sealed
  4. Update documentation - Keep companion guides current

Troubleshooting

Common Issues

GI Score Too Low - Increase test coverage - Fix linting/type errors - Add virtue tags to policy files - Reduce prohibited pattern usage

False Positives - ATLAS thresholds can be tuned - ZEUS can override ATLAS decisions - Contact maintainers for adjustments

Ledger Connection Issues - ATLAS continues with local attestations - Check LEDGER_API_URL and LEDGER_ADMIN_TOKEN - Verify network connectivity

Getting Help

Success Metrics

Quality

  • GI Score ≥ 0.95 maintained across 100% of merges
  • Test coverage ≥ 80% for all packages
  • Zero critical security vulnerabilities
  • Lint/type errors = 0

Velocity

  • PR cycle time < 24 hours
  • False positive rate < 5%
  • Developer satisfaction score > ⅘

Learning

  • 1 cycle summary per week
  • Pattern detection accuracy > 90%
  • Recommendations adopted > 50%

Governance

  • 100% of changes attested to ledger
  • Charter compliance = 100%
  • Audit trail complete and verifiable

Next Steps

  1. Review the implementation - Check all new files and configurations
  2. Test locally - Run npm run sentinel:health and npm run integrity:report
  3. Deploy to staging - Test ATLAS workflow on a staging branch
  4. Monitor and tune - Adjust thresholds based on real usage
  5. Celebrate - First successful ATLAS audit! 🎉

ATLAS Sentinel - Truth Through Verification
"I am the anchor that prevents drift. I am the auditor that ensures quality. I am the synthesizer that extracts learning."

Cycle C-109 | ATLAS Genesis