AEGIS Component Gap Analysis¶

Version: 1.93.0 Created: 2025-12-27 Updated: 2026-02-25 Status: Released (v1.0.0) | AWS Deployed (dev) Release Tag: aegis-v1.0.0-pq-complete (commit 418e164) Scope: Gap identification across all five AEGIS components Metrics: 3041 tests passing (2 skipped) | ~94.9% coverage | All CI passing | All bugs fixed (v1.0.0) AWS Deployment: 4/4 CDK stacks deployed to us-west-2 (account 164171672016)

1. Executive Summary¶

This document identifies misalignments, missing capabilities, and bridging requirements across the five AEGIS components:

• Guardrails - Risk & Invariant Layer
• DOS - Policy-as-Code Engine
• Rubric - Mathematical Kernel
• LIBERTAS OPUS - Orchestration & Collaboration
• AFA - Autonomous Execution Engine

Gap Severity Classification¶

2. Gap Inventory¶

2.1 Category: Decision Logic¶

GAP-C1: Decision Logic Divergence [CRITICAL]¶

Components Affected: Guardrails, Rubric v2.1

Description: Guardrails uses Bayesian posterior probability (P(Δ≥2|data) > 0.95) for gate decisions, while Rubric v2.1 uses Lower Confidence Bound (LCB(U) > θ) for utility-based decisions. These are mathematically different approaches that can produce conflicting results.

Impact: - A proposal may pass Bayesian gate but fail LCB gate (or vice versa) - No clear conflict resolution mechanism - Potential for inconsistent decisions

Bridging Solution:

class DualValidationGate:
    """Requires both Bayesian and LCB validation."""

    def evaluate(self, proposal: Proposal) -> GateResult:
        # Bayesian validation (Guardrails)
        bayesian_result = self.bayesian_gate.evaluate(proposal)

        # LCB validation (Rubric)
        lcb_result = self.lcb_gate.evaluate(proposal)

        # Both must pass
        if bayesian_result.passed and lcb_result.passed:
            return GateResult(
                passed=True,
                confidence=min(
                    bayesian_result.confidence,
                    lcb_result.confidence
                )
            )

        return GateResult(
            passed=False,
            reason=self._explain_failure(bayesian_result, lcb_result)
        )

Resolution Priority: Phase 1 (Immediate)

GAP-C2: Override Mechanism Incompatibility [CRITICAL]¶

Components Affected: Guardrails, AFA, LIBERTAS OPUS

Description: - Guardrails: Requires BIP-322 dual-signature override (two-key) - AFA: No override mechanism; relies on gate pass/fail - LIBERTAS: Has HandoffProtocol abstraction but no TWO_KEY_OVERRIDE implementation

Impact: - AFA cannot handle governance overrides - LIBERTAS lacks cryptographic signature support - No unified override flow

Bridging Solution:

1. Extend LIBERTAS: Add TWO_KEY_OVERRIDE handoff protocol (see afa-libertas-integration.md)
2. Extend AFA: Add override callback to pcw_decide():

async def pcw_decide(
    candidates: List[CodeProposal],
    context: AEGISContext,
    override_handler: Optional[OverrideHandler] = None
) -> DecisionResult:
    # ... normal evaluation ...

    if result.failed and override_handler:
        override_result = await override_handler.request_override(
            proposal=result.best_candidate,
            gate_results=result.gate_results,
            rationale=context.override_rationale
        )

        if override_result.approved:
            return DecisionResult(
                decision=Decision.APPROVE,
                proposal=result.best_candidate,
                approval_path="TWO_KEY_OVERRIDE",
                audit_trail=override_result.audit_entries
            )

    return result

Resolution Priority: Phase 1 (Immediate)

GAP-C3: AFABridge Gate Integration [CRITICAL]¶

Components Affected: AFA, Guardrails

Description: src/integration/afa_bridge.py contains scaffold gate evaluation (lines 142-196) using trivial comparisons instead of proper GateEvaluator with Bayesian posterior calculations. This is the same issue that was fixed in pcw_decide.py on 2025-12-27.

Current Implementation (scaffold):

# src/integration/afa_bridge.py:161
# Scaffold evaluation - in production uses real gate evaluator
risk_delta = proposed_risk - baseline_risk
if risk_delta < 2.0:  # Trivial comparison, not Bayesian
    risk_passed = True

Expected Implementation:

# Wire GateEvaluator for proper Bayesian gate logic
from engine.gates import GateEvaluator

evaluator = GateEvaluator()
gate_result = evaluator.evaluate_all(
    risk_baseline=baseline_risk,
    risk_proposed=proposed_risk,
    # ... other parameters
)

Impact: - AFA bridge decisions lack proper Bayesian confidence calculations - No posterior probability (P(Δ≥2|data) > 0.95) validation - Inconsistent with now-fixed pcw_decide.py - Missing gate confidence audit trail

Bridging Solution: Wire GateEvaluator into AFABridge._evaluate_proposal() method following the same pattern used in pcw_decide.py (see lines 147, 162-173).

Resolution Priority: Phase 1 (Immediate)

2.2 Category: Parameter Naming¶

GAP-H1: Inconsistent Parameter Nomenclature [HIGH]¶

Components Affected: All five components

Description: Each component uses different naming conventions for equivalent concepts:

Impact: - Configuration confusion - Mapping errors in integration code - Documentation inconsistency

Bridging Solution: Create unified parameter registry in /schema/interface-contract.yaml:

# Canonical parameter definitions with aliases
parameters:
  risk_epsilon:
    canonical_name: epsilon_R
    type: float
    default: 0.01
    aliases:
      guardrails: epsilon_R
      dos: risk_floor
      rubric: ε_R
      afa: min_risk

  confidence_threshold:
    canonical_name: trigger_confidence_prob
    type: float
    default: 0.95
    aliases:
      guardrails: trigger_confidence_prob
      dos: confidence
      rubric: α
      afa: conf_threshold

Resolution Priority: Phase 1 (Immediate)

GAP-H2: Telemetry Schema Extension [HIGH]¶

Components Affected: AFA, Guardrails

Description: AFA telemetry doesn't include all fields required by Guardrails telemetry schema.

Impact: - Incomplete audit trail - Cannot compute drift metrics - Non-compliant with 100% logging requirement

Bridging Solution: Extend AFA telemetry collector:

class AEGISTelemetryCollector:
    """Extended telemetry for AEGIS compliance."""

    REQUIRED_FIELDS = [
        "proposal_id", "timestamp", "risk_score", "profit_score",
        "novelty_score", "complexity_score", "quality_score",
        "guardrail_decision", "human_decision", "param_snapshot_id",
        "baseline_feed_hash", "kl_divergence", "drift_status"
    ]

    def emit(self, entry: Dict[str, Any]) -> None:
        # Validate all required fields present
        missing = set(self.REQUIRED_FIELDS) - set(entry.keys())
        if missing:
            raise TelemetryValidationError(
                f"Missing required fields: {missing}"
            )

        # Add AEGIS metadata
        entry["aegis_version"] = self.version
        entry["param_snapshot_id"] = self.current_snapshot_id
        entry["baseline_feed_hash"] = self.baseline_hash

        self.backend.write(entry)

Resolution Priority: Phase 2 (Short-term)

GAP-H3: RBAC Model Reconciliation [HIGH]¶

Components Affected: Guardrails, AFA, LIBERTAS OPUS

Description: Each component defines different role hierarchies:

Guardrails RBAC:

admin → risk_lead → reviewer → analyst → viewer
              ↓
        security_lead

AFA RBAC:

system_admin → repo_admin → developer → reader

LIBERTAS OPUS:

(No predefined roles; uses Actor types: AI, HUMAN, HYBRID)

Impact: - Role mapping confusion - Permission gaps or overlaps - No unified access control

Bridging Solution: Create unified role hierarchy in /schema/rbac-definitions.yaml:

roles:
  # View-only access
  viewer:
    guardrails: viewer
    afa: reader
    libertas: null  # Read-only actor
    permissions: [read_proposals, read_telemetry]

  # Analysis access
  analyst:
    inherits: viewer
    guardrails: analyst
    afa: reader
    libertas: AI (read-only)
    permissions: [run_queries, export_reports]

  # Development access
  developer:
    inherits: analyst
    guardrails: reviewer
    afa: developer
    libertas: AI
    permissions: [submit_proposals, view_own_decisions]

  # Review access
  reviewer:
    inherits: developer
    guardrails: reviewer
    afa: developer
    libertas: HUMAN
    permissions: [approve_proposals, request_override]

  # Governance access
  risk_lead:
    inherits: reviewer
    guardrails: risk_lead
    afa: repo_admin
    libertas: GOVERNANCE
    permissions: [first_key_override, adjust_thresholds_propose]

  security_lead:
    inherits: reviewer
    guardrails: security_lead
    afa: repo_admin
    libertas: GOVERNANCE
    permissions: [second_key_override]

  # Administrative access
  admin:
    inherits: [risk_lead, security_lead]
    guardrails: admin
    afa: system_admin
    libertas: GOVERNANCE
    permissions: [manage_roles, audit_all, system_config]

Resolution Priority: Phase 2 (Short-term)

2.3 Category: Orchestration¶

GAP-M1: Feedback Loop Timing [MEDIUM]¶

Components Affected: Guardrails, Rubric, AFA

Description: Different components assume different calibration cadences:

Impact: - Thresholds may drift between components - Inconsistent baseline updates - Potential for stale parameters

Bridging Solution: Standardize on 30-day rolling window with event-driven triggers:

# schema/calibration-config.yaml
calibration:
  window_days: 30
  triggers:
    - type: scheduled
      cron: "0 0 * * 0"  # Weekly
    - type: drift
      condition: "kl_divergence >= tau_critical"
    - type: manual
      requires: calibrator_role

  components:
    guardrails:
      sync: true
      priority: 1
    rubric:
      sync: true
      priority: 2
    afa:
      sync: true
      priority: 3

Resolution Priority: Phase 3 (Medium-term)

GAP-M2: Actor Type Extension [MEDIUM]¶

Components Affected: LIBERTAS OPUS

Description: LIBERTAS defines only AI, HUMAN, HYBRID actors. AEGIS requires additional types for governance workflows.

Required Extensions: - GOVERNANCE - Two-key override authority - CALIBRATOR - Statistical threshold tuning - AUDITOR - Read-only audit access

Impact: - Cannot model governance workflows natively - Workaround with HUMAN type loses type safety - No capability enforcement

Bridging Solution: See afa-libertas-integration.md Section 5.1

Resolution Priority: Phase 2 (Short-term)

GAP-M3: Workflow State Persistence [MEDIUM] - IMPLEMENTED¶

Components Affected: LIBERTAS OPUS

Description: LIBERTAS workflows are ephemeral; no durable state persistence for long-running workflows (e.g., human review that spans days).

Impact: - Workflow state lost on restart - Cannot resume interrupted workflows - No audit trail for in-progress workflows

Implementation: - ADR: ADR-001-workflow-persistence (Status: Accepted) - EPCC Plan: gap-m3-workflow-persistence (Completed) - Effort: 12 hours (completed 2025-12-27) - Architecture: SQLAlchemy 2.0 async + asyncpg (PostgreSQL) / aiosqlite (testing)

Implementation Details: 1. Persistence Module: src/workflows/persistence/ - models.py - ORM models (WorkflowInstance, WorkflowTransition, WorkflowCheckpoint) - engine.py - Database configuration (DatabaseConfig, create_database_engine) - repository.py - WorkflowPersistence with async methods - durable.py - DurableWorkflowEngine wrapper

1. Workflow Serialization: Added to_dict() / from_dict() to:
2. ProposalWorkflow
3. ConsensusWorkflow

4. OverrideWorkflow

5. Database Schema:

6. workflow_instances - Core workflow state with JSONB state_data
7. workflow_transitions - Audit trail with SHA-256 integrity hashes (chained)

8. workflow_checkpoints - Resume points for crash recovery

9. Test Coverage: 51 new tests in tests/test_persistence.py

Usage Example:

from workflows.persistence import WorkflowPersistence, DurableWorkflowEngine, DatabaseConfig

# Initialize
config = DatabaseConfig.for_testing()  # SQLite in-memory
persistence = WorkflowPersistence(config)
await persistence.initialize()

engine = DurableWorkflowEngine(persistence)

# Create durable workflow
workflow = await engine.create(
    ProposalWorkflow,
    actor_id="user-123",
    proposal_id="prop-456",
    metadata=metadata,
)

# Resume after crash
restored = await engine.resume(ProposalWorkflow, "prop-456")

# Verify audit trail integrity
is_valid, error = await engine.verify_integrity("prop-456")

Resolution Priority: Phase 3 (Medium-term) Status: IMPLEMENTED - Full persistence layer with audit trail

2.4 Category: Security¶

GAP-M4: Signature Format Standardization [MEDIUM]¶

Components Affected: Guardrails, LIBERTAS OPUS

Description: Guardrails specifies BIP-322 signatures, but current implementation uses Ed25519 (incorrectly labeled as "BIP-322 compatible"). True BIP-322 requires BIP-340 Schnorr signatures on secp256k1 curve.

Current State: | Aspect | Current (Ed25519) | Required (BIP-322) | |--------|-------------------|-------------------| | Curve | Curve25519 | secp256k1 | | Algorithm | EdDSA | Schnorr (BIP-340) | | Message Format | JSON → SHA-256 | BIP-340 tagged hash | | Bitcoin Compatible | No | Yes |

Impact: - Specification non-compliance (§6 RBAC) - Cannot verify with Bitcoin tooling - Blocks GAP-Q1 post-quantum hybrid signatures - Audit concerns for external reviewers

Bridging Solution: Provider-based architecture with BIP322Provider using btclib>=2023.7.12:

from src.crypto.bip322_provider import BIP322Provider

validator = DualSignatureValidator(provider=BIP322Provider())
msg_hash = validator.create_message_hash(proposal_id, justification, gates)
# Returns BIP-340 tagged hash: SHA256(tag || tag || message)

Key Decisions (see ADR-002): - Format: BIP-322 Simple (witness stack, base64-encoded) - Library: btclib (100% test coverage, MIT license) - Migration: Hybrid approach with Ed25519 deprecation path

Resolution Priority: Phase 2 (Short-term) - Critical Path for GAP-Q1/Q2

Effort Estimate: 8-12 hours

Dependencies: None (unlocks GAP-Q1, GAP-Q2)

Implementation Plan: See docs/implementation-plans/gap-m4-bip322-signatures.md

ADR: See docs/architecture/adr/ADR-002-bip322-signature-format.md

Implementation: src/crypto/ module with: - bip340.py: BIP-340 tagged hash implementation - bip322_provider.py: BIP-322 Simple format provider using btclib - ed25519_provider.py: Legacy Ed25519 provider (deprecated) - providers.py: SignatureProvider protocol definition

Status: IMPLEMENTED - Full BIP-322 support with provider-based architecture

2.5 Category: Observability¶

GAP-L1: Unified Monitoring Dashboard [LOW]¶

Components Affected: All components

Description: Each component has separate monitoring; no unified AEGIS dashboard.

Impact: - Fragmented operational view - Cross-component issues harder to diagnose - Increased operational overhead

Progress Update (2025-12-30)¶

Phase 1: COMPLETE (Prometheus Foundation) - Prometheus exporter module created (src/telemetry/prometheus_exporter.py) - 12 metric families implemented - Integrated into gates.py (6 gates instrumented) - Integrated into pcw_decide.py (decision metrics) - Integrated into proposal.py (state transitions) - Comprehensive test suite (553 lines, 20+ tests) - Performance validated: <1ms overhead per emission - Thread safety validated: concurrent updates safe

Deliverables: - /metrics endpoint support via get_metrics() - Gate evaluation metrics (pass/fail, latency) - Decision outcome metrics - Proposal lifecycle tracking - System health gauges (active proposals, KL divergence, drift status)

Phase 2: COMPLETE (HTTP Metrics Server + Grafana Configs) - src/telemetry/metrics_server.py -- Lightweight HTTP server on /metrics - monitoring/grafana/ -- Dashboard JSON configs (overview + risk analysis) - monitoring/prometheus/ -- Recording rules + alerting rules YAML - CLI aegis metrics and aegis health subcommands

Phase 3: COMPLETE (Alerting Infrastructure) - src/telemetry/alert.py -- AlertSink protocol with LogAlertSink, WebhookAlertSink, CompositeAlertSink - monitoring/prometheus/alerting-rules.yaml -- Prometheus alerting rules - Override workflow wired with alerts (INFO/CRITICAL/WARNING/EMERGENCY)

AWS Deployment Update (2026-02-10)¶

Phase 4: DEPLOYED (AWS CloudWatch + SNS) - AegisMonitoringStack-dev deployed to us-west-2 - CloudWatch dashboard AEGIS-Governance-dev with Lambda/ECS metrics - SNS topic aegis-governance-alarms-dev for alarm routing - 4 CloudWatch alarms: Lambda errors, Lambda throttles, ECS unhealthy, billing protection - ADOT sidecar on ECS Fargate for Prometheus remote write to AMP

Bridging Solution: Create unified Grafana dashboard with panels for each layer:

# dashboards/aegis-unified.yaml
dashboard:
  title: "AEGIS Unified Monitoring"
  rows:
    - title: "Layer 0: Invariants"
      panels:
        - security_gate_pass_rate
        - sast_finding_trend
        - slsa_compliance_rate

    - title: "Layer 1: Policy"
      panels:
        - decision_path_distribution
        - utility_score_histogram
        - three_point_accuracy

    - title: "Layer 2: Gates"
      panels:
        - gate_pass_rates
        - confidence_distribution
        - posterior_probability_trend

    - title: "Layer 3: Orchestration"
      panels:
        - workflow_completion_rate
        - handoff_count
        - override_frequency

    - title: "Layer 4: Execution"
      panels:
        - proposals_executed
        - lines_modified
        - test_pass_rate

    - title: "Layer 5: Feedback"
      panels:
        - kl_divergence_trend
        - drift_alerts
        - calibration_events

Resolution Priority: Backlog Status: 100% code-complete (Phases 1-3) + AWS deployed (Phase 4: CloudWatch + SNS + ADOT)

GAP-L2: Cross-Component Tracing [LOW]¶

Components Affected: All components

Description: HTTP telemetry sink infrastructure is now complete (ROADMAP Item 14 -- HTTPEventSink, BatchHTTPSink), enabling remote event streaming. ADOT sidecar deployed on ECS Fargate (AegisMcpStack-dev) for Prometheus remote write to AMP. Full OpenTelemetry distributed tracing with OTLP protocol integration remains deferred to v2.0.0 for cross-component span correlation.

2.6 Category: Quantum Resistance¶

GAP-Q1: Post-Quantum Signature Hardening [MEDIUM] - IMPLEMENTED¶

Components Affected: Guardrails, LIBERTAS OPUS, Override Workflow

Description: Current cryptographic signatures (Ed25519, planned BIP-322/Schnorr) are vulnerable to quantum attacks via Shor's algorithm. A cryptographically relevant quantum computer (CRQC) could forge signatures, bypassing two-key governance controls. NIST has standardized post-quantum algorithms that should be evaluated for future-proofing.

Implementation: - ML-DSA Wrapper: src/crypto/mldsa.py - ML-DSA-44 (Dilithium Level 2) via liboqs-python - Hybrid Provider: src/crypto/hybrid_provider.py - HybridSignatureProvider combining Ed25519 + ML-DSA-44 - Algorithm Field: SignatureRecord.algorithm field added to track signature type - Tests: tests/crypto/test_mldsa.py, tests/crypto/test_hybrid_provider.py (comprehensive unit tests) - Integration Tests: tests/test_workflows.py (TestHybridSignatureIntegration class)

Hybrid Signature Format: | Component | Size | Description | |-----------|------|-------------| | Ed25519 signature | 64 bytes | Classical signature | | ML-DSA-44 signature | 2,420 bytes | Post-quantum signature | | Total | 2,484 bytes | Combined hybrid signature |

Hybrid Public Key Format: | Component | Size | Description | |-----------|------|-------------| | Ed25519 public key | 32 bytes | Classical public key | | ML-DSA-44 public key | 1,312 bytes | Post-quantum public key | | Total | 1,344 bytes | Combined hybrid key |

Security Properties: 1. Defense in depth: BOTH signatures must verify for acceptance 2. Harvest-now-decrypt-later protection: Even if classical signatures are broken in the future, the PQ signature protects 3. Backward compatibility: BIP-322 remains default; hybrid opt-in via provider injection 4. Graceful degradation: When liboqs not installed, system falls back to classical signatures

Usage Example:

from src.crypto import get_hybrid_provider, HYBRID_AVAILABLE

if HYBRID_AVAILABLE:
    provider = get_hybrid_provider()  # Returns HybridSignatureProvider
    private_key, public_key = provider.generate_keypair()
    msg_hash = provider.create_message_hash(proposal_id, justification, gates)
    signature = provider.sign(msg_hash, private_key)
    assert provider.verify(signature, msg_hash, public_key)

Dependencies: - liboqs-python>=0.10.0 - NIST post-quantum algorithms - cryptography>=41.0.0 - Ed25519 for hybrid signatures

Resolution Priority: Phase 4 (Long-term / Future-proofing)

Effort Estimate: 16-24 hours (completed)

Status: IMPLEMENTED - Full hybrid post-quantum signature support

References: - NIST FIPS 204 (ML-DSA) - NIST FIPS 203 (ML-KEM) - Open Quantum Safe Project - Hybrid Signatures RFC Draft

GAP-Q2: Post-Quantum Key Encapsulation [MEDIUM]¶

Components Affected: Guardrails, LIBERTAS OPUS, Telemetry, Key Management

Description: While GAP-Q1 addresses signature security, sensitive data at rest (governance keys, audit trail fields, PII in telemetry) remains protected only by classical encryption vulnerable to "harvest-now-decrypt-later" attacks. ML-KEM (Kyber) provides quantum-resistant key encapsulation for encrypting sensitive data.

Current State: | Component | Protection | Vulnerability | |-----------|------------|---------------| | Governance private keys | AES-256 (classical) | Grover reduces to 128-bit | | Audit trail signatures | Plaintext storage | N/A (integrity, not confidentiality) | | Telemetry PII fields | SHA-256 hash | One-way, but quantum-vulnerable | | Key transport | TLS 1.3 (ECDHE) | Shor breaks key exchange |

Post-Quantum Solution: Hybrid Encryption (X25519 + ML-KEM-768)

@dataclass
class HybridEncryptedBlob:
    """Quantum-resistant encrypted data container."""

    classical_ephemeral: bytes    # X25519 ephemeral public key (32 bytes)
    pq_ciphertext: bytes          # ML-KEM-768 ciphertext (1,088 bytes)
    encrypted_data: bytes         # AES-256-GCM encrypted payload
    nonce: bytes                  # 12-byte nonce
    tag: bytes                    # 16-byte authentication tag
    algorithm: str = "X25519+ML-KEM-768+AES-256-GCM"

    def decrypt(self, recipient_keys: HybridKeyPair) -> bytes:
        """Decrypt using both classical and PQ key exchange."""
        # Derive shared secret from both mechanisms
        classical_secret = x25519_derive(
            self.classical_ephemeral,
            recipient_keys.classical_private
        )
        pq_secret = ml_kem_decapsulate(
            self.pq_ciphertext,
            recipient_keys.pq_private
        )

        # Combine secrets (both must be correct)
        combined_key = hkdf(classical_secret || pq_secret)

        return aes_gcm_decrypt(
            self.encrypted_data,
            combined_key,
            self.nonce,
            self.tag
        )

Use Cases in AEGIS:

Algorithm Selection:

Selected: ML-KEM-768 (192-bit security, balances size/security)

Impact: - Encrypted blobs grow by ~1.1 KB per encapsulation - Key generation adds ~0.1ms overhead - Decryption adds ~0.15ms overhead - Storage for encrypted keys increases 35x

Implementation Considerations:

Bridging Solution: 1. Implement HybridKEM class in src/crypto/kem.py 2. Create EncryptedKeyStore for governance key management 3. Add encrypt_field() / decrypt_field() helpers for telemetry 4. Update key generation to produce hybrid encryption keys 5. Create migration script for existing encrypted data

Resolution Priority: Phase 4 (Long-term / Future-proofing)

Effort Estimate: 12-16 hours (completed)

Status: IMPLEMENTED - Phase 1 (primitives) and Phase 2 (key store, PII) complete

Phase 1 Implementation (2025-12-28): src/crypto/ module with: - mlkem.py: ML-KEM-768 wrapper using liboqs-python (FIPS 203) - hybrid_kem.py: HybridKEMProvider with X25519 + ML-KEM-768 + AES-256-GCM - Test suite: tests/crypto/test_mlkem.py, tests/crypto/test_hybrid_kem.py (70 tests)

Phase 2 Implementation (2025-12-28): Key store and PII encryption: - src/crypto/kek_provider.py: KEK provider abstraction (EnvironmentKEKProvider, InMemoryKEKProvider) - src/workflows/persistence/models.py: GovernanceKey, KeyUsageAudit ORM models - src/workflows/persistence/key_store.py: KeyStoreRepository with hash-chained audit - src/telemetry/encryption.py: PIIEncryptionEnricher, DEKCache, DEKRotator - src/telemetry/decryption.py: PIIDecryptor with integrity verification - src/workflows/override.py: sign_with_stored_key() integration - src/telemetry/pipeline.py: PII encryption stage in telemetry pipeline - Test suite: tests/crypto/test_kek_provider.py, tests/telemetry/test_pii_encryption.py (58 tests) - Total tests: 128 (70 Phase 1 + 58 Phase 2) - Outstanding: KeyStoreRepository (key_store.py) tests pending - requires async database fixtures

ADR: See docs/architecture/adr/ADR-004-hybrid-post-quantum-encryption.md

Key Features: - KEK-encrypted governance keys at rest - 12 PII fields encrypted (6 CRITICAL, 4 HIGH, 2 MEDIUM) - Hash-chained audit trail for key operations - DEK rotation support for telemetry encryption

Synergy with GAP-Q1:

┌─────────────────────────────────────────────────────────────┐
│              Quantum-Resistant Governance                    │
├─────────────────────────────────────────────────────────────┤
│  GAP-Q1: ML-DSA (Dilithium)     GAP-Q2: ML-KEM (Kyber)     │
│  ├── Override signatures         ├── Key encryption         │
│  ├── Audit trail integrity       ├── Sensitive field enc    │
│  └── Actor authentication        └── Key transport          │
├─────────────────────────────────────────────────────────────┤
│  Together: Complete PQ protection for governance workflows  │
└─────────────────────────────────────────────────────────────┘

References: - NIST FIPS 203 (ML-KEM) - Hybrid Key Exchange RFC - liboqs KEM Documentation

Impact: - Cannot trace proposal through entire lifecycle - Latency attribution difficult - Root cause analysis limited

Bridging Solution: Implement OpenTelemetry instrumentation:

from opentelemetry import trace
from opentelemetry.trace import SpanKind

tracer = trace.get_tracer("aegis")

async def pcw_decide(candidates, context):
    with tracer.start_as_current_span(
        "aegis.pcw_decide",
        kind=SpanKind.SERVER,
        attributes={
            "aegis.candidate_count": len(candidates),
            "aegis.context.version": context.version
        }
    ) as span:
        # Layer 0
        with tracer.start_span("aegis.layer0.security_gate"):
            security_result = await security_gate.evaluate(candidates)

        # Layer 1
        with tracer.start_span("aegis.layer1.policy"):
            policy_result = await policy_engine.evaluate(candidates)

        # ... etc

Resolution Priority: Backlog

3. Gap Resolution Roadmap¶

Status: All gaps COMPLETED as of v4.5.52 (2026-02-23). Original timeline labels preserved for historical reference.

Phase 1: Critical Gaps — COMPLETED¶

Week 1-2 (COMPLETED):
├── ✅ GAP-C1: Implement DualValidationGate
├── ✅ GAP-C2: Extend LIBERTAS with TWO_KEY_OVERRIDE
└── ✅ GAP-H1: Create unified parameter registry

Phase 2: High Priority Gaps — COMPLETED¶

Week 3-4 (COMPLETED):
├── ✅ GAP-H2: Extend AFA telemetry schema
├── ✅ GAP-H3: Create unified RBAC mapping
├── ✅ GAP-M2: Add GOVERNANCE/CALIBRATOR actor types
└── ✅ GAP-M4: Implement BIP-322 signature support

Phase 3: Medium Priority Gaps — COMPLETED¶

Week 5-8 (COMPLETED):
├── ✅ GAP-M1: Standardize calibration windows
└── ✅ GAP-M3: Add workflow state persistence

Phase 4: Long-term Future-proofing — COMPLETED¶

Future (COMPLETED):
├── ✅ GAP-Q1: Post-quantum signature hardening (ML-DSA + Ed25519 hybrid)
└── ✅ GAP-Q2: Post-quantum key encapsulation (ML-KEM + X25519 hybrid)

Backlog: Low Priority Gaps — COMPLETED¶

Future (COMPLETED):
├── ✅ GAP-L1: Unified monitoring dashboard
└── ✅ GAP-L2: Cross-component tracing

4. Gap Dependency Graph¶

                           ┌─────────────────────────┐
                           │   GAP-C1: Dual Logic    │
                           │       (CRITICAL)        │
                           └───────────┬─────────────┘
                                       │
                                       ▼
┌─────────────────────────┐     ┌─────────────────────────┐     ┌─────────────────────────┐
│  GAP-C2: Override Mech  │────▶│   GAP-M4: BIP-322       │────▶│  GAP-Q1: Post-Quantum   │
│      (CRITICAL)         │     │       (MEDIUM)          │     │     Signatures (MED)    │
└───────────┬─────────────┘     └─────────────────────────┘     └───────────┬─────────────┘
                                                                            │
                                                                            ▼
                                                                ┌─────────────────────────┐
                                                                │  GAP-Q2: Post-Quantum   │
                                                                │    Encryption (MED)     │
                                                                └─────────────────────────┘
            │
            ▼
┌─────────────────────────┐     ┌─────────────────────────┐
│  GAP-M2: Actor Types    │────▶│  GAP-M3: Persistence    │
│      (MEDIUM)           │     │      (MEDIUM)           │
└─────────────────────────┘     └─────────────────────────┘

┌─────────────────────────┐
│  GAP-H1: Parameter Names│
│       (HIGH)            │
└───────────┬─────────────┘
            │
            ▼
┌─────────────────────────┐     ┌─────────────────────────┐
│  GAP-H2: Telemetry      │────▶│   GAP-L1: Dashboard     │
│       (HIGH)            │     │       (LOW)             │
└─────────────────────────┘     └─────────────────────────┘
            │
            ▼
┌─────────────────────────┐
│  GAP-H3: RBAC           │
│       (HIGH)            │
└─────────────────────────┘

┌─────────────────────────┐
│  GAP-M1: Calibration    │
│       (MEDIUM)          │
└─────────────────────────┘

┌─────────────────────────┐
│  GAP-L2: Tracing        │
│       (LOW)             │
└─────────────────────────┘

5. Gap Summary Table¶

See Also¶

Project Planning¶

• ROADMAP - Future work roadmap, active PRs, release milestones (single source of truth)

Architecture Decision Records¶

• ADR-001: Workflow Persistence - Database architecture for GAP-M3
• ADR-002: BIP-322 Signature Format - Provider-based crypto for GAP-M4
• ADR-003: Hybrid Post-Quantum Signatures - ML-DSA-44 + Ed25519 for GAP-Q1
• ADR-004: Hybrid Post-Quantum Encryption - ML-KEM-768 + X25519 for GAP-Q2
• ADR-005: KL Divergence Threshold Calibration - Threshold calibration for GAP-H1 (shadow mode Phase 1 complete -- data collection enabled)
• ADR-006: Posterior Predictive for Bayesian Gates - Posterior predictive for GAP-MATH-1
• ADR-007: AWS Deployment Architecture - Hybrid Lambda+ECS deployment decision

Analysis Documents¶

• Multi-Model Coherence Review - Claude-GPT validation of mathematical foundations (source of GAP-MATH-* and GAP-SEC-1)
• Test Count Methodology - Historical test counting methodology (current: 3041 tests)
• Cross-Reference Verification Report - 99.6% accuracy across all documentation cross-references
• Comprehensive TODO Discovery - Historical progress tracking

Implementation Plans¶

• GAP-M3: Workflow Persistence - EPCC plan (12 hours)
• GAP-M4: BIP-322 Signatures - EPCC plan (8-12 hours)
• GAP-Q1: Post-Quantum Signatures - EPCC plan (16-20 hours)
• GAP-Q2: Post-Quantum Encryption - EPCC plan (24-32 hours)

Core Specifications¶

• Unified AEGIS Specification - Complete system architecture
• AFA-LIBERTAS Integration - Orchestration patterns
• Repository Structure - Directory organization and module dependencies

Changelog¶