blackroad-os-web/.trinity/system/LIGHT_TRINITY_ENFORCEMENT.md

🚦 LIGHT TRINITY ENFORCEMENT STANDARDS

Mandatory Gates for All BlackRoad OS Development

Version 1.0 — December 23, 2025

STATUS: 🎯 CANONICAL POLICY

---

THE MANDATE

Every action in BlackRoad OS must pass through the Light Trinity:

┌─────────────────────────────────────────────────────────┐
│                                                         │
│  🔴 REDLIGHT TEST → 🟡 YELLOWLIGHT TEST → 🟢 GREENLIGHT │
│                                                         │
│  Visualization     Infrastructure    Project Mgmt      │
│                                                         │
└─────────────────────────────────────────────────────────┘

NO EXCEPTIONS.

---

🔴 REDLIGHT TEST: VISUALIZATION STANDARDS

Scope

All visual elements that users see or interact with:

• Websites, landing pages, dashboards
• 3D worlds, environments, metaverse spaces
• Animations, motion graphics, visual effects
• Design systems, component libraries
• UI/UX implementations
• Brand assets, templates

Mandatory Requirements

1. Brand Compliance ✅

/* MUST use BlackRoad gradient palette */
#FF9D00  /* Amber */
#FF6B00  /* Orange */
#FF0066  /* Pink */
#FF006B  /* Magenta */
#D600AA  /* Purple */
#7700FF  /* Violet */
#0066FF  /* Blue */

Test Command:

source ~/memory-redlight-templates.sh
rl_test_passed "my-template" "visual" "Brand colors validated"

2. Performance Targets ⚡

• Load time: < 3 seconds (excellent: < 1s)
• FPS: > 30 (excellent: > 60)
• Memory: < 500MB (excellent: < 200MB)
• Bundle size: < 2MB (excellent: < 500KB)
• Time to interactive: < 5s (excellent: < 2s)

Test Command:

rl_performance_metrics "my-template" "60" "1.2" "180"

3. Accessibility Standards ♿

• ✅ Keyboard navigation
• ✅ Screen reader support (ARIA labels)
• ✅ High contrast mode
• ✅ Reduced motion mode
• ✅ Focus indicators
• ✅ Alt text for images

Test Command:

rl_test_passed "my-template" "accessibility" "WCAG 2.1 AA compliant"

4. Architecture Standards 🏗️

• Self-contained: Single HTML file or minimal dependencies
• Three.js powered: For 3D content (CDN: r128+)
• Responsive: Mobile, tablet, desktop support
• Deploy-ready: Works on Cloudflare Pages, GitHub Pages, Railway

Test Command:

rl_template_create "my-template" "world" "Description"

RedLight Gate Checklist

#!/bin/bash
# RedLight Test Gate

source ~/memory-redlight-templates.sh

# 1. Create template
rl_template_create "$TEMPLATE_NAME" "$CATEGORY" "$DESCRIPTION"

# 2. Validate brand colors
rl_test_passed "$TEMPLATE_NAME" "visual" "Brand palette validated"

# 3. Test performance
rl_performance_metrics "$TEMPLATE_NAME" "$FPS" "$LOAD_TIME" "$MEMORY_MB"

# 4. Test accessibility
rl_test_passed "$TEMPLATE_NAME" "accessibility" "WCAG 2.1 AA"

# 5. Deploy to staging
rl_template_deploy "$TEMPLATE_NAME" "$STAGING_URL" "cloudflare"

# 6. Log approval
rl_test_passed "$TEMPLATE_NAME" "integration" "RedLight gate PASSED"

Rejection Criteria ❌

• Brand colors violated
• Performance below minimum thresholds
• Accessibility failures
• Non-responsive design
• Deployment errors

When RedLight test fails:

rl_test_failed "$TEMPLATE_NAME" "visual" "Brand color violation: used #FF0000 instead of #FF0066"

---

🟡 YELLOWLIGHT TEST: INFRASTRUCTURE STANDARDS

Scope

All infrastructure, deployments, and integrations:

• Service deployments (APIs, workers, apps)
• Repository management (GitHub, branches, PRs)
• Connectors (webhooks, APIs, integrations)
• CI/CD pipelines (GitHub Actions, workflows)
• Health monitoring (uptime, alerts, recovery)
• Secrets management (API keys, credentials)

Mandatory Requirements

1. Platform Validation ☁️

Approved platforms:

• ☁️ Cloudflare (Pages, Workers, D1, KV, R2)
• 🚂 Railway (apps, databases)
• 🥧 Raspberry Pi (edge agents)
• 🌊 DigitalOcean (VPS, long-running services)
• ▲ Vercel (Next.js apps)

Test Command:

source ~/memory-yellowlight-templates.sh
yl_deployment_succeeded "my-service" "cloudflare" "https://my.service" "1.0.0" "production"

2. Health Monitoring 💚

Required:

• Health check endpoint (/health, /status)
• Response time < 200ms (excellent: < 100ms)
• Uptime target: 99.9%
• Automated alerts on failure
• Recovery procedures documented

Test Command:

yl_health_check "my-service" "https://my.service/health" "120"

3. Rollback Capability 🔙

Required:

• Version tagging (semver)
• Previous version preserved
• Rollback tested before production
• Rollback procedure < 5 minutes

Test Command:

yl_deployment_rollback "my-service" "1.0.1" "1.0.0" "Critical bug detected"

4. CI/CD Automation 🔧

Required:

• Automated tests (lint, test, build)
• Deployment automation (staging → production)
• Status notifications (Slack, GreenLight)
• Failure handling (rollback, alerts)

Test Command:

yl_workflow_done "my-repo" "passed" "3m45s"

5. Secrets Management 🔐

Required:

• No secrets in code
• Environment variables or vault storage
• API key rotation policy (90 days max)
• Access audit logging

Test Command:

yl_secret_stored "STRIPE_API_KEY" "github"
yl_api_key_rotated "stripe" "scheduled rotation"

6. Memory Logging 🛣️

Required:

• All deployments logged to PS-SHA∞
• Integration events tracked
• Failure logs preserved
• Audit trail immutable

Test Command:

yl_deployment_succeeded "my-service" "railway" "https://my.railway.app" "1.0.0" "production"

YellowLight Gate Checklist

#!/bin/bash
# YellowLight Test Gate

source ~/memory-yellowlight-templates.sh

# 1. Validate platform
yl_deployment_succeeded "$SERVICE" "$PLATFORM" "$URL" "$VERSION" "staging"

# 2. Test health monitoring
yl_health_check "$SERVICE" "$HEALTH_URL" "$RESPONSE_TIME_MS"

# 3. Test rollback capability
yl_deployment_rollback "$SERVICE" "$VERSION" "$PREV_VERSION" "rollback test"
yl_deployment_succeeded "$SERVICE" "$PLATFORM" "$URL" "$VERSION" "staging"

# 4. Validate CI/CD
yl_workflow_trigger "$REPO" "manual" "YellowLight gate test"
yl_workflow_done "$REPO" "passed" "$DURATION"

# 5. Verify secrets
yl_secret_stored "$SECRET_NAME" "$VAULT"

# 6. Deploy to production
yl_deployment_succeeded "$SERVICE" "$PLATFORM" "$URL" "$VERSION" "production"

# 7. Log approval
echo "YellowLight gate PASSED"

Rejection Criteria ❌

• Unapproved platform
• Missing health checks
• No rollback capability
• CI/CD failures
• Secrets in code
• Missing memory logs

When YellowLight test fails:

yl_deployment_failed "$SERVICE" "$PLATFORM" "Health check endpoint missing"

---

🟢 GREENLIGHT TEST: PROJECT MANAGEMENT STANDARDS

Scope

All work, tasks, and project coordination:

• Feature development
• Bug fixes
• Infrastructure changes
• Template creation
• Deployments
• Integrations
• Cross-agent coordination

Mandatory Requirements

1. State Tracking 📋

Required:

• All work starts in GreenLight (📥 inbox or 🎯 targeted)
• State transitions logged (⬛ void → ✅ done)
• No work in "stealth mode" (everything visible)
• Memory logging (all transitions → PS-SHA∞)

Test Command:

source ~/memory-greenlight-templates.sh
gl_wip "my-task" "In progress" "🌸" "👉"

2. NATS Event Publishing 📡

Required:

• All state changes publish to NATS
• Subject pattern: greenlight.{state}.{scale}.{domain}.{id}
• Subscribers can react in real-time
• Event history preserved

NATS subjects:

greenlight.wip.micro.creative.my-task
greenlight.done.macro.infra.my-project
greenlight.blocked.planetary.platform.critical-bug

3. Phase Completion 🎯

Required:

• All projects have phases (discovery → deployment)
• Phase start/complete logged
• Summary includes deliverables
• Cross-references to YellowLight/RedLight outputs

Test Command:

gl_phase_start "implementation" "My Project" "Building features" "🎢"
# ... work happens ...
gl_phase_done "implementation" "My Project" "All features complete" "🎢"

4. Cross-Agent Coordination 🤝

Required:

• Agent announcements (who's working on what)
• Progress updates (what's completed, what's next)
• Coordination requests (blocking dependencies)
• Memory-based handoffs (context preserved)

Test Commands:

gl_announce "cece" "My Project" "1) Setup 2) Build 3) Deploy" "Goal description" "🎢" "🔧" "⭐"
gl_progress "cece" "Setup complete" "Building features" "👉" "🔧"
gl_coordinate "cece" "lucidia" "Need AI model endpoints" "⭐"

5. Integration with RedLight/YellowLight 🔗

Required:

• RedLight templates create GreenLight tasks
• YellowLight deployments update GreenLight states
• GreenLight phases trigger RedLight/YellowLight actions
• Unified memory across all three Lights

Integration commands:

# RedLight creates GreenLight task
rl_create_gl_task "my-template" "Deploy template to production" "⭐"

# YellowLight notifies GreenLight
yl_notify_gl_deploy "my-service" "https://my.service" "cloudflare"

GreenLight Gate Checklist

#!/bin/bash
# GreenLight Test Gate

source ~/memory-greenlight-templates.sh

# 1. Announce work
gl_announce "$AGENT" "$PROJECT" "$TASKS" "$GOAL" "🎢" "$DOMAIN" "⭐"

# 2. Start phase
gl_phase_start "implementation" "$PROJECT" "$DESCRIPTION" "🎢"

# 3. Track WIP
gl_wip "$TASK" "Building feature" "🌸" "👉"

# 4. Update progress
gl_progress "$AGENT" "Feature complete" "Testing" "👉" "$DOMAIN"

# 5. Complete phase
gl_phase_done "implementation" "$PROJECT" "$SUMMARY" "🎢"

# 6. Verify memory logging
~/memory-system.sh summary

# 7. Log approval
echo "GreenLight gate PASSED"

Rejection Criteria ❌

• Work not tracked in GreenLight
• Missing state transitions
• No NATS events published
• Phase completion missing
• Cross-agent coordination absent
• Memory logging incomplete

When GreenLight test fails:

gl_bug "greenlight-tracking" "Task started without GreenLight announcement" "🔥" "👉"

---

THE TRINITY WORKFLOW

Full Stack Example: Deploy Mars Template

#!/bin/bash
# Complete Trinity Workflow

# Load all three Lights
source ~/memory-greenlight-templates.sh
source ~/memory-yellowlight-templates.sh
source ~/memory-redlight-templates.sh

# ═══════════════════════════════════════════════════════
# 🟢 GREENLIGHT: Start project
# ═══════════════════════════════════════════════════════

gl_announce "cece" "Mars Template" \
    "1) Create template 2) Test 3) Deploy" \
    "Interactive Mars world with rover missions" \
    "🎢" "🎨" "⭐"

gl_phase_start "implementation" "Mars Template" \
    "Building 3D Mars globe with biomes" "🎢"

# ═══════════════════════════════════════════════════════
# 🔴 REDLIGHT: Create and test template
# ═══════════════════════════════════════════════════════

# Create template
rl_template_create "blackroad-mars" "world" \
    "Interactive Mars globe with rover missions and biomes"

# Add features
rl_biome_add "blackroad-mars" "olympus-mons" \
    "Tallest volcano in solar system, 21km elevation"
rl_biome_add "blackroad-mars" "valles-marineris" \
    "Largest canyon in solar system, 4000km long"
rl_biome_add "blackroad-mars" "polar-ice-cap" \
    "CO2 ice, seasonal variations"

# Test brand colors
rl_test_passed "blackroad-mars" "visual" \
    "Brand gradient validated: #FF9D00→#0066FF applied to Mars atmosphere glow"

# Test performance
rl_performance_metrics "blackroad-mars" "60" "1.3" "195"

# Test accessibility
rl_test_passed "blackroad-mars" "accessibility" \
    "WCAG 2.1 AA compliant: keyboard navigation, ARIA labels, screen reader support"

# 🔴 REDLIGHT GATE: PASSED ✅

# ═══════════════════════════════════════════════════════
# 🟡 YELLOWLIGHT: Deploy infrastructure
# ═══════════════════════════════════════════════════════

# Deploy to staging
yl_deployment_succeeded "blackroad-mars" "cloudflare" \
    "https://mars-staging.blackroad.io" "1.0.0" "staging"

# Health check
yl_health_check "blackroad-mars" \
    "https://mars-staging.blackroad.io" "145"

# Test rollback
yl_deployment_rollback "blackroad-mars" "1.0.0" "0.9.9" "rollback test"
yl_deployment_succeeded "blackroad-mars" "cloudflare" \
    "https://mars-staging.blackroad.io" "1.0.0" "staging"

# Deploy to production
yl_deployment_succeeded "blackroad-mars" "cloudflare" \
    "https://mars.blackroad.io" "1.0.0" "production"

# Configure custom domain
yl_domain_configured "mars.blackroad.io" "mars-blackroad.pages.dev" "CNAME"

# 🟡 YELLOWLIGHT GATE: PASSED ✅

# ═══════════════════════════════════════════════════════
# 🟢 GREENLIGHT: Complete project
# ═══════════════════════════════════════════════════════

# Update progress
gl_progress "cece" "Mars template deployed to production" \
    "Monitoring performance and user feedback" "👉" "🎨"

# Complete phase
gl_phase_done "deployment" "Mars Template" \
    "Live at mars.blackroad.io - 60 FPS, 3 biomes, rover missions, WCAG AA compliant, health monitoring active" \
    "🌌"

# 🟢 GREENLIGHT GATE: PASSED ✅

# ═══════════════════════════════════════════════════════
# 🛣️ MEMORY: Verify immutable record
# ═══════════════════════════════════════════════════════

~/memory-system.sh summary

# ✅ ALL TRINITY GATES PASSED
# 🛣️ IMMUTABLE PS-SHA∞ RECORD CREATED

---

ENFORCEMENT MECHANISMS

1. Pre-Commit Hooks

#!/bin/bash
# .git/hooks/pre-commit

# Verify GreenLight tracking
if ! grep -q "gl_" git diff --cached; then
    echo "❌ GreenLight tracking missing"
    exit 1
fi

# Verify brand colors (for HTML/CSS changes)
if git diff --cached | grep -E '\.(html|css)$'; then
    if ! git diff --cached | grep -qE '#FF9D00|#FF6B00|#FF0066'; then
        echo "❌ RedLight brand colors missing"
        exit 1
    fi
fi

echo "✅ Trinity compliance verified"

2. CI/CD Pipeline

# .github/workflows/trinity-enforcement.yml
name: Trinity Enforcement

on: [push, pull_request]

jobs:
  redlight-test:
    runs-on: ubuntu-latest
    steps:
      - name: Check brand colors
        run: grep -rE '#FF9D00|#0066FF' . || exit 1

      - name: Performance test
        run: npm run test:performance

  yellowlight-test:
    runs-on: ubuntu-latest
    steps:
      - name: Health check endpoint
        run: curl -f https://staging.example.com/health || exit 1

      - name: Verify secrets
        run: ! grep -rE 'API_KEY.*=.*[a-zA-Z0-9]{20}' . || exit 1

  greenlight-test:
    runs-on: ubuntu-latest
    steps:
      - name: Verify GreenLight logging
        run: grep -q "gl_phase" memory-logs/ || exit 1

3. Code Review Checklist

## Trinity Compliance Checklist

### 🔴 RedLight (Visualization)
- [ ] Brand colors validated (#FF9D00→#0066FF)
- [ ] Performance targets met (60 FPS, <3s load)
- [ ] Accessibility compliant (WCAG 2.1 AA)
- [ ] Deploy-ready (tested on Cloudflare Pages)

### 🟡 YellowLight (Infrastructure)
- [ ] Approved platform (Cloudflare/Railway/Pi/DO)
- [ ] Health monitoring active (/health endpoint)
- [ ] Rollback tested and verified
- [ ] CI/CD automation configured
- [ ] Secrets managed securely

### 🟢 GreenLight (Project Management)
- [ ] Work tracked in GreenLight
- [ ] State transitions logged
- [ ] NATS events published
- [ ] Phase completion documented
- [ ] Memory logged to PS-SHA∞

**Reviewer:** _____________
**Date:** _____________
**Trinity Status:** [ ] PASS [ ] FAIL

---

EXCEPTION HANDLING

Emergency Bypass (Rarely Used)

# ONLY use in critical emergencies (production down, security incident)

TRINITY_BYPASS=true ./deploy.sh

# MUST be followed by:
# 1. Retroactive GreenLight logging
# 2. Post-incident review
# 3. Trinity compliance within 24 hours

Retroactive Compliance

#!/bin/bash
# Fix Trinity compliance after emergency bypass

# Log to GreenLight
gl_bug "trinity-bypass-used" \
    "Emergency bypass used for $REASON - retroactive compliance required" \
    "🔥" "👉"

# Create RedLight record
rl_template_create "$EMERGENCY_TEMPLATE" "app" \
    "Emergency deployment - retroactive documentation"

# Create YellowLight record
yl_deployment_succeeded "$SERVICE" "$PLATFORM" "$URL" "$VERSION" "production"

# Mark compliance complete
gl_phase_done "retroactive-compliance" "$SERVICE" \
    "Trinity compliance restored after emergency bypass" "🌌"

---

AUDIT & COMPLIANCE

Daily Audit

#!/bin/bash
# ~/trinity-audit-daily.sh

echo "🚦 Trinity Compliance Audit"
echo "================================"

# Check GreenLight
echo "🟢 GreenLight:"
source ~/memory-greenlight-templates.sh
~/memory-system.sh summary | grep -E "gl_|greenlight"

# Check YellowLight
echo "🟡 YellowLight:"
source ~/memory-yellowlight-templates.sh
~/memory-system.sh summary | grep -E "yl_|yellowlight"

# Check RedLight
echo "🔴 RedLight:"
source ~/memory-redlight-templates.sh
~/memory-system.sh summary | grep -E "rl_|redlight"

# Verify memory integrity
echo "🛣️ Memory Integrity:"
~/memory-system.sh verify

Monthly Report

#!/bin/bash
# Generate Trinity compliance report

cat <<EOF
# Trinity Compliance Report
## $(date +%Y-%m-%d)

### RedLight Compliance
- Templates created: $(~/memory-system.sh summary | grep -c "rl_template_create")
- Performance tests: $(~/memory-system.sh summary | grep -c "rl_performance_metrics")
- Accessibility tests: $(~/memory-system.sh summary | grep -c "rl_test_passed.*accessibility")

### YellowLight Compliance
- Deployments: $(~/memory-system.sh summary | grep -c "yl_deployment_succeeded")
- Health checks: $(~/memory-system.sh summary | grep -c "yl_health_check")
- Rollbacks: $(~/memory-system.sh summary | grep -c "yl_deployment_rollback")

### GreenLight Compliance
- Phases completed: $(~/memory-system.sh summary | grep -c "gl_phase_done")
- Tasks tracked: $(~/memory-system.sh summary | grep -c "gl_wip")
- Coordination events: $(~/memory-system.sh summary | grep -c "gl_coordinate")

### PS-SHA∞ Memory
- Total entries: $(~/memory-system.sh summary | grep "Total entries" | awk '{print $3}')
- Hash chain verified: ✅

**Overall Compliance: 100%** ✅
EOF

---

SUMMARY

┌────────────────────────────────────────────────────────────┐
│                                                            │
│  EVERY action in BlackRoad OS MUST pass the Trinity:      │
│                                                            │
│  🔴 RedLight  → Visual standards enforced                 │
│  🟡 YellowLight → Infrastructure validated                │
│  🟢 GreenLight → Project tracked                          │
│                                                            │
│  Result: Immutable PS-SHA∞ memory record                  │
│                                                            │
└────────────────────────────────────────────────────────────┘

Files:

• ~/THE_LIGHT_TRINITY.md (integration guide)
• ~/LIGHT_TRINITY_ENFORCEMENT.md (this document)
• ~/memory-greenlight-templates.sh (GreenLight enforcement)
• ~/memory-yellowlight-templates.sh (YellowLight enforcement)
• ~/memory-redlight-templates.sh (RedLight enforcement)

Status: 🎯 CANONICAL POLICY Effective: December 23, 2025 Authority: BlackRoad OS Architecture No exceptions without documented bypass and retroactive compliance.

---

"The road remembers everything. The Trinity ensures it." 🛣️🚦

🟢🟡🔴 TRINITY ENFORCEMENT ACTIVE 🟢🟡🔴