AEGIS Repository Structure¶

Version: 2.16.0 Created: 2025-12-27 Last Updated: 2026-02-24 Status: Accepted Scope: AEGIS Governance Decision SDK

Overview¶

This document defines the repository structure for the AEGIS Governance Decision SDK -- the Autonomous Engineering Governance Integration System. AEGIS provides a unified Python SDK integrating five complementary frameworks for autonomous engineering governance:

1. Guardrails - Risk & Invariant Layer
2. DOS - Policy-as-Code Engine
3. Rubric - Mathematical Kernel
4. LIBERTAS OPUS - Orchestration & Collaboration
5. AFA - Autonomous Execution Engine

Repository Layout¶

``` aegis-governance/ # Root repository ├── README.md # Project overview & quick start ├── CLAUDE.md # AI agent guidance (v4.5.56) ├── INTEGRATION.md # Integration architecture (AFA loose coupling) ├── KNOWN_ISSUES.md # Tracked known issues ├── LICENSE # MIT License ├── pyproject.toml # Python project configuration & dependencies ├── Dockerfile # Multi-stage Docker build (non-root, health check) ├── Dockerfile.lambda # Lambda container image (scipy-enabled) ├── docker-compose.yaml # AEGIS + Prometheus + Grafana stack │ ├── src/ # SDK implementation │ ├── aegis_governance/ # Public SDK package │ │ ├── init.py # AegisGovernance facade (public API) │ │ ├── mcp_server.py # MCP (Model Context Protocol) server │ │ └── scoring_guide.py # Domain-specific parameter derivation guidance │ │ │ ├── config.py # SDK configuration & defaults │ ├── cli.py # Command-line interface │ ├── rbac.py # RBAC enforcement layer │ ├── lambda_handler.py # AWS Lambda handler wrapping pcw_decide() │ │ │ ├── engine/ # Core mathematical kernel │ │ ├── init.py │ │ ├── utility.py # Utility function implementation │ │ ├── gates.py # Quantitative gate evaluators │ │ ├── bayesian.py # Posterior probability computation │ │ ├── complexity.py # Complexity decomposition (C_S, C_D) │ │ ├── drift.py # KL divergence monitoring │ │ └── validation.py # Shared parameter validation utilities │ │ │ ├── workflows/ # LIBERTAS OPUS workflows │ │ ├── init.py │ │ ├── proposal.py # Proposal evaluation workflow │ │ ├── consensus.py # Multi-actor consensus workflow │ │ ├── serialization.py # Shared datetime serialization (ensure_utc) │ │ ├── override.py # BIP-322 two-key override workflow │ │ └── persistence/ # Durable state persistence │ │ ├── init.py │ │ ├── models.py # SQLAlchemy ORM models │ │ ├── engine.py # Async database engine configuration │ │ ├── repository.py # WorkflowPersistence async repository │ │ ├── key_store.py # KeyStoreRepository (PQ-encrypted keys) │ │ └── durable.py # DurableWorkflowEngine wrapper │ │ │ ├── actors/ # AI/Human actor implementations │ │ ├── init.py │ │ ├── base.py # Actor base classes │ │ ├── proposer.py # Proposal creation actor │ │ ├── analyst.py # Gate analysis actor │ │ ├── approver.py # Approval decision actor │ │ ├── executor.py # Execution actor │ │ ├── governance.py # Override orchestration + compliance actor │ │ └── calibrator.py # Statistical threshold tuning actor │ │ │ ├── integration/ # AFA integration layer (spec-only coupling) │ │ ├── init.py │ │ ├── pcw_decide.py # pcw_decide() → LIBERTAS bridge (shadow mode support) │ │ └── afa_bridge.py # AFA-AEGIS bridge pattern │ │ │ ├── telemetry/ # Telemetry pipeline (with PII encryption) │ │ ├── init.py │ │ ├── schema.py # Schema validation │ │ ├── emitter.py # Telemetry event emission │ │ ├── pipeline.py # Telemetry processing pipeline │ │ ├── prometheus_exporter.py # Prometheus metrics exporter │ │ ├── encryption.py # PIIEncryptionEnricher (12 fields) │ │ ├── decryption.py # PIIDecryptor with integrity verification │ │ ├── alert.py # Alert sink protocol + implementations │ │ ├── metrics_server.py # HTTP /metrics endpoint for Prometheus │ │ └── url_validation.py # Shared SSRF-safe telemetry URL validation │ │ │ └── crypto/ # Post-quantum cryptography │ ├── init.py │ ├── providers.py # Signature/KEM provider protocols │ ├── ed25519_provider.py # Ed25519 signatures │ ├── bip322_provider.py # BIP-322 Schnorr signatures │ ├── bip340.py # BIP-340 Schnorr key/signature utilities │ ├── mldsa.py # ML-DSA-44 post-quantum signatures │ ├── mlkem.py # ML-KEM-768 post-quantum KEM │ ├── hybrid_provider.py # Ed25519 + ML-DSA-44 hybrid signatures │ ├── hybrid_kem.py # X25519 + ML-KEM-768 hybrid encryption │ ├── kek_provider.py # KEK/DEK key hierarchy management │ └── schema_signer.py # AMTSS Protocol v1 (MCP tool schema signing) │ ├── schema/ # Machine-readable contracts (authoritative) │ ├── interface-contract.yaml # Frozen parameters (source of truth) │ ├── telemetry-schema.yaml # Telemetry v2.2.0 field definitions │ ├── rbac-definitions.yaml # Unified role hierarchy │ └── workflow-definitions.yaml # LIBERTAS workflow templates │ ├── spec/ # Core specification documents │ └── guardrails/ # Guardrail specifications (3 files) │ ├── infra/ # AWS CDK infrastructure │ ├── app.py # CDK app entry point (4 stacks) │ └── stacks/ │ ├── shared_stack.py # DynamoDB, Secrets Manager, S3, KMS │ ├── lambda_stack.py # Lambda container image + API Gateway │ ├── ecs_stack.py # ECS Fargate + MCP keepalive │ └── monitoring_stack.py # CloudWatch alarms + dashboard │ ├── tests/ # Test suite (3041 tests, ~94.9% coverage) │ ├── test_*.py # Unit/integration tests │ ├── crypto/ # Cryptography provider tests │ ├── telemetry/ # Telemetry pipeline tests │ ├── workflows/ # Workflow persistence tests │ ├── integration/ # Integration layer tests │ ├── benchmarks/ # Performance benchmarks │ └── infra/ # Infrastructure tests (Lambda handler) │ ├── docs/ # Documentation │ ├── architecture/ # Architecture decisions, gap analysis, ADRs │ ├── claude/ # AI agent changelog & audit trail │ ├── deployment/ # Production guide, migration, SLAs │ ├── integration/ # Parameter reference, domain templates │ ├── knowledge/ # Concept guides, framework comparisons │ ├── analysis/ # Test methodology, TODO discovery │ ├── compliance/ # Operational runbooks (SOC 2, FedRAMP, EU AI Act) │ │ ├── ACCESS-REVIEW.md # Quarterly access review procedure │ │ ├── BCP-DRP.md # Business continuity & disaster recovery │ │ ├── CHANGE-MANAGEMENT.md # Change control process │ │ ├── DSR-PRIVACY-OPERATIONS.md # Data subject rights / privacy ops │ │ ├── IRP.md # Incident response plan │ │ ├── system-description.md # SOC 2 system description │ │ ├── VENDOR-RISK.md # Vendor risk assessment (AWS) │ │ └── adr/template.md # ADR template │ └── research/ # Research documents (4 papers) │ ├── 001-kl-threshold-calibration-methodology.md │ ├── 002-market-research-competitive-landscape.md │ ├── 003-mcp-security-ecosystem-review.md │ └── 004-mcp-schema-signing-design.md │ ├── ai/ # AI governance artifacts (ISO 42001, NIST AI RMF, EU AI Act) │ ├── system-register.yaml # AI system inventory (AEGIS-001) │ ├── risk-register.yaml # Risk register (6 risks → OWASP Agentic Top 10) │ ├── model-card.yaml # Decision engine characteristics │ ├── data-card.yaml # Telemetry data governance (12 encrypted PII fields) │ ├── oversight-plan.md # Human oversight procedures (kill switch, invariants) │ ├── postmarket-monitoring.md # Continuous monitoring plan │ ├── AIMS-POLICY.md # ISO 42001 AIMS policy (PDCA cycle) │ └── technical_file/ # EU AI Act Annex IV compliance │ ├── README.md │ ├── instructions-for-use.md │ ├── conformity/ # Standards, risk mgmt, declarations │ ├── testing/ # TEVV reports │ └── logs/ # Log mapping to frameworks │ ├── tools/ # Development & CI tools │ └── ci/ # CI validators (9 stdlib-only scripts) │ ├── ai_rmf_validate_artifacts.py # AI RMF/AIMS artifact validator │ ├── ai_act_lint.py # EU AI Act technical file structure │ ├── generate_scorecard.py # Engineering health scorecard │ ├── generate_precommit_config.py # Pre-commit config generator │ ├── validate_scaffold_adoption.py # Placeholder detection │ ├── validate_log_schema.py # Log event schema validator │ ├── validate_agent_messages.py # Agent transcript validator │ ├── enforce_perf_gate.py # Performance gate enforcer │ └── verify_fips.py # FIPS 140-3 verification │ ├── schemas/ # JSON Schema definitions (standardized logging) │ └── log_event.schema.json # Log event schema (Engineering Standards) │ ├── policy/ # OPA/Rego deny-by-default policies │ ├── agent-egress.rego # Agent egress allowlist │ └── README.md # OPA policy documentation │ ├── benchmarks/ # Performance baseline & runner │ ├── perf_baseline.json # Baseline metrics │ └── run.sh # Benchmark runner stub │ ├── Makefile # Quality-of-life make targets ├── CONTRIBUTING.md # Contribution guidelines (change classes, ADRs) ├── .pre-commit-config.yaml # Pre-commit hooks (ELITE tier) ├── .semgrep.yaml # Custom SAST rules │ ├── monitoring/ # Observability configuration │ ├── README.md # Monitoring stack overview │ ├── prometheus/ # Prometheus configuration │ │ ├── prometheus.yml # Prometheus scrape config │ │ ├── alerting-rules.yaml # Prometheus alerting rules │ │ └── recording-rules.yaml # Prometheus recording rules │ └── grafana/ # Grafana dashboard JSON │ ├── overview-dashboard.json # System overview dashboard │ └── risk-analysis-dashboard.json # Risk analysis dashboard │ ├── examples/ # Usage examples │ ├── basic_evaluation.py # 20-line quickstart │ ├── custom_config.py # YAML and dict configuration │ ├── ci_cd_integration.py # GitHub Action usage │ └── autonomous_agent.py # AI agent + AFABridge │ └── scripts/ # Utility scripts └── generate_master_kek.py # Hybrid PQ KEK generation (X25519 + ML-KEM-768)