icdev 0.0.3__py3-none-any.whl

docs/architecture/bounded-contexts.md

@@ -0,0 +1,1032 @@
+# CUI // SP-CTI
+
+# ICDEV Bounded Contexts — Domain-Driven Design Reference
+
+**Classification:** CUI // SP-CTI
+**Impact Level:** IL4
+**Last Updated:** 2026-03-08
+**Status:** Living Document
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Context Map](#context-map)
+3. [Bounded Contexts](#bounded-contexts)
+   - [Compliance](#1-compliance)
+   - [Security](#2-security)
+   - [Requirements](#3-requirements)
+   - [Simulation](#4-simulation)
+   - [DevSecOps](#5-devsecops)
+   - [Supply Chain](#6-supply-chain)
+   - [MBSE](#7-mbse)
+   - [Embedded](#8-embedded)
+   - [Observability](#9-observability)
+   - [GovCon](#10-govcon)
+   - [CloudForge](#11-cloudforge)
+   - [Knowledge](#12-knowledge)
+4. [Integration Patterns Summary](#integration-patterns-summary)
+5. [Anti-Corruption Layer Index](#anti-corruption-layer-index)
+
+---
+
+## Overview
+
+ICDEV (Intelligent Certified Development) is decomposed into 12 bounded contexts following Domain-Driven Design principles. Each context owns its aggregate roots, enforces its invariants independently, and communicates with other contexts through well-defined integration patterns.
+
+All contexts share the storage abstraction layer (`tools/db/storage.py`, decision D-DB-21) but maintain logical isolation of their domain models. The audit trail is append-only across all contexts (NIST 800-53 AU compliance, decision D6).
+
+### Bounded Context Summary
+
+| Bounded Context | Directory | Core Aggregate | Key Invariant |
+|---|---|---|---|
+| Compliance | `tools/compliance/` | ComplianceControl | Cannot be "Implemented" without non-expired evidence |
+| Security | `tools/security/` | ThreatModel | Every STRIDE threat maps to >= 1 NIST control |
+| Requirements | `tools/requirements/` | IntakeSession | Cannot pass Stage 3 without readiness >= 0.7 |
+| Simulation | `tools/simulation/` | Scenario | Monte Carlo requires >= 1000 iterations |
+| DevSecOps | `tools/devsecops/` | DevSecOpsProfile | IL4+ requires ZTA maturity >= Advanced |
+| Supply Chain | `tools/supply_chain/` | DependencyGraph | All vendors must have SCRM assessment |
+| MBSE | `tools/mbse/` | DigitalThread | Every model element must have trace link |
+| Embedded | `tools/embedded/` + `fleet/` + `edge_ai/` | Device | Deployed firmware must have SBOM |
+| Observability | `tools/observability/` | Trace | Active tracing required for production |
+| GovCon | `tools/govcon/` | Proposal | Read-only bridge to compliance (D-WG-8) |
+| CloudForge | `tools/cloudforge/` | Runbook | DAG execution via Kahn's algorithm |
+| Knowledge | `tools/memory/` + `tools/rag/` | MemoryEntry | Hybrid search: 0.7 BM25 + 0.3 semantic |
+
+---
+
+## Context Map
+
+```mermaid
+graph TB
+    subgraph core["Core Domain"]
+        COMP[Compliance]
+        SEC[Security]
+        REQ[Requirements]
+    end
+
+    subgraph supporting["Supporting Domain"]
+        SIM[Simulation]
+        DSO[DevSecOps]
+        SC[Supply Chain]
+        MBSE_CTX[MBSE]
+        OBS[Observability]
+    end
+
+    subgraph generic["Generic Domain"]
+        EMB[Embedded]
+        GOV[GovCon]
+        CF[CloudForge]
+        KN[Knowledge]
+    end
+
+    subgraph external["External Systems"]
+        EXT_VENDORS[External Vendors]
+        EXT_FRAMEWORKS[Compliance Frameworks]
+    end
+
+    %% Conformist
+    SEC -->|Conformist| COMP
+    COMP -.->|publishes controls| SEC
+
+    %% Customer/Supplier
+    REQ -->|Customer/Supplier| COMP
+    REQ -->|Customer/Supplier| SIM
+    COMP -.->|control status| REQ
+    SIM -.->|simulation results| REQ
+
+    %% Partnership
+    MBSE_CTX <-->|Partnership| REQ
+
+    %% ACL boundaries
+    SC -->|ACL| EXT_VENDORS
+    EMB -->|ACL| COMP
+    EMB -->|ACL| EXT_FRAMEWORKS
+
+    %% Published Language
+    GOV -->|Published Language| COMP
+
+    %% Shared Kernel
+    CF <-->|Shared Kernel| DSO
+
+    %% Observability monitors everything
+    OBS -.->|monitors| COMP
+    OBS -.->|monitors| SEC
+    OBS -.->|monitors| DSO
+
+    %% Knowledge serves everything
+    KN -.->|serves| REQ
+    KN -.->|serves| COMP
+    KN -.->|serves| SEC
+
+    classDef core fill:#2d5f8a,stroke:#1a3a5c,color:#fff
+    classDef supporting fill:#5a8a3d,stroke:#3a5c1a,color:#fff
+    classDef generic fill:#8a6b2d,stroke:#5c4a1a,color:#fff
+    classDef external fill:#8a2d2d,stroke:#5c1a1a,color:#fff
+
+    class COMP,SEC,REQ core
+    class SIM,DSO,SC,MBSE_CTX,OBS supporting
+    class EMB,GOV,CF,KN generic
+    class EXT_VENDORS,EXT_FRAMEWORKS external
+```
+
+### Relationship Types
+
+| Relationship | Upstream | Downstream | Pattern | Description |
+|---|---|---|---|---|
+| Conformist | Compliance | Security | Security conforms to Compliance's control model without translation |
+| Customer/Supplier | Compliance | Requirements | Requirements consumes control status; Compliance fulfills on its own schedule |
+| Customer/Supplier | Simulation | Requirements | Requirements triggers simulations; Simulation delivers results asynchronously |
+| Partnership | MBSE | Requirements | Co-evolving models; both teams collaborate on shared traceability schema |
+| ACL | External Vendors | Supply Chain | Supply Chain translates vendor data through anti-corruption layer |
+| ACL | Compliance | Embedded | Embedded translates between IEC 62443/DO-178C and NIST 800-53 |
+| Published Language | Compliance | GovCon | GovCon reads compliance data via standardized read-only bridge |
+| Shared Kernel | DevSecOps | CloudForge | Shared pipeline/policy models; changes require mutual agreement |
+
+---
+
+## Bounded Contexts
+
+---
+
+### 1. Compliance
+
+**Directory:** `tools/compliance/`
+**Agent:** Compliance (port 9446)
+**Domain Type:** Core
+
+#### Overview
+
+The Compliance context is the authoritative source for control implementation status, evidence collection, and framework assessments across 9 compliance frameworks. It enforces the control crosswalk (D-SBD-4): implementing one NIST 800-53 control auto-populates FedRAMP, CMMC, and 800-171 status. This context is the single source of truth for ATO readiness.
+
+#### Core Aggregate: ComplianceControl
+
+```
+ComplianceControl (Aggregate Root)
+├── control_id: str           # e.g., "AC-2"
+├── framework: str            # e.g., "NIST 800-53"
+├── status: enum              # not_started | partial | implemented | not_applicable
+├── evidence: List[Evidence]
+│   ├── evidence_id: str
+│   ├── collected_at: datetime
+│   ├── expires_at: datetime
+│   └── artifact_type: str    # ssp | poam | scan_result | test_result
+├── crosswalk_mappings: List[CrosswalkMapping]
+│   ├── target_framework: str
+│   └── target_control_id: str
+└── sbd_requirements: List[SbdRequirement]
+    ├── requirement_id: str   # e.g., "SBD-04"
+    ├── pillar: str           # Cloudyrion 8-pillar
+    └── exception: Optional[SbdException]
+```
+
+#### Key Invariants
+
+1. **Evidence freshness:** A control cannot be "Implemented" without at least one non-expired evidence artifact (D-INV-2: current <= 30d, stale <= 90d, expired > 90d).
+2. **Crosswalk propagation:** Status change on a NIST 800-53 control must trigger crosswalk update to all mapped frameworks.
+3. **SbD exception aging:** Expired SbD exceptions block deployment (D-SBD-3). Maximum exception duration is 365 days.
+4. **Append-only audit:** All compliance evidence and assessment results are immutable (D6, D-WG-9).
+5. **Classification markings:** All generated artifacts must include CUI // SP-CTI markings at IL4 (D5).
+
+#### Domain Events
+
+| Event | Published/Consumed | Description |
+|---|---|---|
+| `ControlStatusChanged` | Published | Emitted when a control transitions status |
+| `EvidenceCollected` | Published | New evidence artifact linked to control |
+| `EvidenceExpired` | Published | Evidence crosses freshness threshold |
+| `CrosswalkUpdated` | Published | Mapped framework status propagated |
+| `SbdExceptionExpired` | Published | Exception aging triggered |
+| `AssessmentCompleted` | Published | FedRAMP/CMMC/STIG assessment finished |
+| `ThreatMitigationLinked` | Consumed | From Security — threat mapped to control |
+| `RequirementDecomposed` | Consumed | From Requirements — new control needed |
+
+#### Anti-Corruption Layer
+
+- **Inbound from Security:** Accepts `ThreatMitigationLinked` events, validates that referenced control IDs exist in the control catalog before linking.
+- **Inbound from Requirements:** Accepts decomposed requirements, maps to controls via `control_mapper.py`.
+- **Outbound to GovCon:** Exposes read-only bridge (D-WG-8) — GovCon can query control status but never write.
+
+#### Integration Patterns
+
+- **Crosswalk Engine** (`crosswalk_engine.py`): Internal pattern that propagates status across frameworks. Implements the "implement once, satisfy many" principle.
+- **cATO Live Evidence** (`cato_live_engine.py`): Continuous OSCAL streaming with incremental assessment-results (D-INV-1).
+- **Template Exchange** (`template_exchange.py`): Community template sharing with SHA-256 content hash for tamper detection (D-INV-5).
+
+---
+
+### 2. Security
+
+**Directory:** `tools/security/`
+**Agent:** Security (port 9447)
+**Domain Type:** Core
+
+#### Overview
+
+The Security context owns threat modeling, vulnerability scanning, AI security assessment, and agent trust scoring. It operates as a conformist to the Compliance context — it adopts the Compliance control model directly for STRIDE-to-NIST mapping without translating it into a separate model.
+
+#### Core Aggregate: ThreatModel
+
+```
+ThreatModel (Aggregate Root)
+├── model_id: str
+├── project_id: str
+├── name: str
+├── components: List[Component]
+│   ├── component_id: str
+│   ├── type: enum            # web_application | api | database | message_queue | ...
+│   └── stride_threats: List[StrideThreat]
+│       ├── category: enum    # Spoofing | Tampering | Repudiation | InfoDisclosure | DoS | EoP
+│       ├── severity: enum    # critical | high | medium | low
+│       └── nist_controls: List[str]  # mapped controls
+├── trust_scores: List[AgentTrustScore]
+│   ├── agent_id: str
+│   ├── score: float          # 0.0 - 1.0
+│   └── dimensions: dict      # behavioral_drift, tool_chain, rbac, ...
+└── scan_results: List[ScanResult]
+    ├── scanner: enum         # sast | dependency | secret | container | prompt_injection
+    └── findings: List[Finding]
+```
+
+#### Key Invariants
+
+1. **STRIDE-to-NIST completeness:** Every STRIDE threat must map to at least one NIST 800-53 control (D-INV-25, D-INV-26). Mapping: Spoofing -> AC/IA, Tampering -> SC/SI, Repudiation -> AU, InfoDisclosure -> SC, DoS -> SC/CP, EoP -> AC.
+2. **AI security gates:** Prompt injection defense must be active, AI telemetry enabled, AI BOM present, ATLAS coverage >= 80%.
+3. **Agent trust threshold:** Agents with trust score < 0.5 are flagged for review; < 0.3 triggers isolation.
+4. **Deterministic threat analysis:** STRIDE analysis is rule-based per component type (D-INV-25) — no LLM in the critical path.
+
+#### Domain Events
+
+| Event | Published/Consumed | Description |
+|---|---|---|
+| `ThreatIdentified` | Published | New STRIDE threat detected |
+| `ThreatMitigationLinked` | Published | Threat mapped to NIST control(s) |
+| `VulnerabilityFound` | Published | SAST/dependency/secret scan finding |
+| `AgentTrustScoreUpdated` | Published | Agent trust recalculated |
+| `PromptInjectionDetected` | Published | Injection attempt flagged |
+| `ControlStatusChanged` | Consumed | From Compliance — mitigation status update |
+
+#### Anti-Corruption Layer
+
+- **Inbound from Compliance:** Consumes `ControlStatusChanged` to update threat mitigation status. No translation needed (conformist relationship).
+- **Outbound to Compliance:** Publishes `ThreatMitigationLinked` with NIST control IDs in Compliance's ubiquitous language.
+
+#### Integration Patterns
+
+- **Conformist to Compliance:** Security adopts Compliance's control catalog verbatim. The STRIDE-to-NIST mapping table (D-INV-26) is the integration seam.
+- **AI telemetry:** Privacy-preserving SHA-256 hashed prompts/responses (D216).
+- **ATLAS/OWASP assessors:** Consume from multiple contexts to build comprehensive AI security posture.
+
+---
+
+### 3. Requirements
+
+**Directory:** `tools/requirements/`
+**Agent:** Requirements Analyst (port 9453)
+**Domain Type:** Core
+
+#### Overview
+
+The Requirements context implements RICOAS (Requirements Intake, COA & Approval System) — an AI-driven conversational intake pipeline with gap detection, readiness scoring, and SAFe decomposition. It is the upstream supplier of work items to Compliance and Simulation.
+
+#### Core Aggregate: IntakeSession
+
+```
+IntakeSession (Aggregate Root)
+├── session_id: str
+├── project_id: str
+├── customer_name: str
+├── customer_org: str
+├── impact_level: enum        # IL2 | IL4 | IL5 | IL6
+├── stage: enum               # 1_discovery | 2_elicitation | 3_validation | 4_decomposition | 5_approval
+├── readiness_score: ReadinessScore
+│   ├── overall: float        # 0.0 - 1.0
+│   └── dimensions: dict      # 7-dimension scoring
+├── gaps: List[Gap]
+│   ├── gap_id: str
+│   ├── severity: enum        # critical | high | medium | low
+│   └── resolved: bool
+├── decomposed_items: List[DecomposedItem]
+│   ├── level: enum           # epic | feature | story
+│   ├── bdd_scenarios: List[str]
+│   └── acceptance_criteria: List[str]
+└── boundary_assessment: BoundaryAssessment
+    ├── tier: enum             # GREEN | YELLOW | ORANGE | RED
+    └── ato_impact: str
+```
+
+#### Key Invariants
+
+1. **Readiness gate:** Cannot advance past Stage 3 (validation) without readiness score >= 0.7 (D21 — deterministic weighted average).
+2. **Critical gap blocking:** Unresolved critical gaps block progression regardless of readiness score.
+3. **RED boundary requires COA:** Requirements assessed as RED (ATO boundary impact) cannot proceed without an alternative Course of Action.
+4. **Stage sequencing:** Stages must execute in order (1 through 5); no skipping.
+
+#### Domain Events
+
+| Event | Published/Consumed | Description |
+|---|---|---|
+| `IntakeSessionCreated` | Published | New requirements intake started |
+| `StageAdvanced` | Published | Session progressed to next stage |
+| `GapDetected` | Published | New gap identified |
+| `GapResolved` | Published | Gap marked as resolved |
+| `ReadinessScoreComputed` | Published | 7-dimension score calculated |
+| `RequirementDecomposed` | Published | SAFe decomposition completed |
+| `BoundaryAssessed` | Published | ATO impact tier assigned |
+| `SimulationResultReceived` | Consumed | From Simulation — Monte Carlo results |
+| `ModelElementLinked` | Consumed | From MBSE — traceability link established |
+
+#### Anti-Corruption Layer
+
+- **Outbound to Compliance:** Decomposed requirements are translated into control mapping requests via `control_mapper.py`.
+- **Outbound to Simulation:** Scenario creation requests are translated into Simulation's scenario model.
+- **Inbound from MBSE:** Model elements are accepted and linked to requirements through the digital thread.
+
+#### Integration Patterns
+
+- **Customer/Supplier with Compliance:** Requirements is the customer; Compliance fulfills control mapping on its own timeline.
+- **Customer/Supplier with Simulation:** Requirements triggers Monte Carlo simulations; results flow back asynchronously.
+- **Partnership with MBSE:** Bidirectional — requirements inform models, models inform requirements.
+
+---
+
+### 4. Simulation
+
+**Directory:** `tools/simulation/`
+**Agent:** Simulation (port 9455)
+**Domain Type:** Supporting
+
+#### Overview
+
+The Simulation context implements the Digital Program Twin — a multi-dimensional simulation engine with Monte Carlo analysis and Course of Action (COA) generation. It operates as a supplier to the Requirements context.
+
+#### Core Aggregate: Scenario
+
+```
+Scenario (Aggregate Root)
+├── scenario_id: str
+├── project_id: str
+├── name: str
+├── scenario_type: enum       # what_if | baseline | stress_test
+├── dimensions: List[Dimension]
+│   ├── name: str             # schedule | cost | risk | quality | compliance | security
+│   └── parameters: dict
+├── monte_carlo_runs: List[MonteCarloRun]
+│   ├── run_id: str
+│   ├── iterations: int       # must be >= 1000
+│   ├── results: dict         # p10, p50, p90 distributions
+│   └── confidence: float
+├── coas: List[CourseOfAction]
+│   ├── coa_id: str
+│   ├── name: str
+│   ├── simulated: bool
+│   └── comparison_metrics: dict
+└── ato_simulation: Optional[AtoSimulation]
+    ├── pert_samples: List[float]  # betavariate sampling (D-INV-41)
+    └── predicted_timeline: dict
+```
+
+#### Key Invariants
+
+1. **Minimum iterations:** Monte Carlo simulations require >= 1000 iterations for statistical validity (D22 — Python stdlib `random`).
+2. **ATO PERT sampling:** ATO timeline predictions use `random.betavariate` (D-INV-41) — zero external dependencies.
+3. **COA comparison:** COAs cannot be compared unless all have been simulated.
+4. **Dimension validity:** At least one dimension must be specified per scenario.
+
+#### Domain Events
+
+| Event | Published/Consumed | Description |
+|---|---|---|
+| `ScenarioCreated` | Published | New simulation scenario defined |
+| `MonteCarloCompleted` | Published | Simulation run finished |
+| `CoaGenerated` | Published | Course of Action produced |
+| `AtoTimelinePredicted` | Published | ATO simulator results ready |
+| `RequirementDecomposed` | Consumed | From Requirements — triggers scenario creation |
+
+#### Anti-Corruption Layer
+
+- **Inbound from Requirements:** Translates decomposed requirements into scenario parameters. Requirements speaks in SAFe terms; Simulation translates to dimension-based models.
+
+#### Integration Patterns
+
+- **Customer/Supplier with Requirements:** Simulation fulfills scenario requests from Requirements. Results are returned via `MonteCarloCompleted` events.
+- **ATO Simulator** (`ato_simulator.py`): Standalone Monte Carlo for ATO timeline prediction, consumed by both Requirements and Compliance.
+
+---
+
+### 5. DevSecOps
+
+**Directory:** `tools/devsecops/`
+**Agent:** DevSecOps ZTA (port 9457)
+**Domain Type:** Supporting
+
+#### Overview
+
+The DevSecOps context owns pipeline security generation, policy-as-code (Kyverno/OPA), service mesh configuration, and Zero Trust Architecture maturity scoring across the DoD 7-pillar model. It has a hard veto on `pipeline_configuration` and `zero_trust_policy` (D117).
+
+#### Core Aggregate: DevSecOpsProfile
+
+```
+DevSecOpsProfile (Aggregate Root)
+├── profile_id: str
+├── project_id: str
+├── maturity_level: enum      # Level 1 (Initial) | 2 | 3 | 4 | 5 (Optimized)
+├── zta_maturity: ZtaMaturity
+│   ├── overall: enum         # Traditional | Advanced | Optimal
+│   └── pillars: dict         # 7 pillar scores
+│       ├── identity: enum
+│       ├── devices: enum
+│       ├── networks: enum
+│       ├── applications: enum
+│       ├── data: enum
+│       ├── visibility: enum
+│       └── automation: enum
+├── pipeline_config: PipelineSecurityConfig
+│   ├── stages: List[Stage]
+│   └── gates: List[Gate]
+├── policies: List[Policy]
+│   ├── engine: enum          # kyverno | opa
+│   └── policy_yaml: str
+└── service_mesh: Optional[ServiceMeshConfig]
+    ├── mesh_type: enum       # istio | linkerd
+    └── mtls_enforced: bool
+```
+
+#### Key Invariants
+
+1. **IL4+ ZTA requirement:** Impact levels IL4 and above require ZTA maturity >= Advanced (D120).
+2. **mTLS enforcement:** Service mesh deployments must enforce mTLS (ZTA gate).
+3. **Default-deny NetworkPolicy:** All deployments must have default-deny NetworkPolicy (ZTA gate).
+4. **Hard veto authority:** DevSecOps agent has hard veto on pipeline_configuration and zero_trust_policy (D117).
+
+#### Domain Events
+
+| Event | Published/Consumed | Description |
+|---|---|---|
+| `ProfileAssessed` | Published | DevSecOps maturity level computed |
+| `ZtaMaturityScored` | Published | 7-pillar ZTA score computed |
+| `PipelineGenerated` | Published | Security pipeline configuration created |
+| `PolicyGenerated` | Published | Kyverno/OPA policy produced |
+| `ServiceMeshConfigured` | Published | Istio/Linkerd config generated |
+| `VetoExercised` | Published | Hard veto on configuration change |
+
+#### Anti-Corruption Layer
+
+- **Shared Kernel with CloudForge:** Pipeline and policy models are co-owned. Changes require coordination between DevSecOps and CloudForge teams.
+
+#### Integration Patterns
+
+- **Shared Kernel with CloudForge:** Both contexts share pipeline security and policy-as-code models. The shared kernel is defined in `args/` YAML configurations.
+- **ZTA maturity feeds Compliance:** ZTA scores are consumed by Compliance for NIST 800-207 assessment (`nist_800_207_assessor.py`).
+
+---
+
+### 6. Supply Chain
+
+**Directory:** `tools/supply_chain/`
+**Agent:** Supply Chain (port 9454)
+**Domain Type:** Supporting
+
+#### Overview
+
+The Supply Chain context manages vendor dependency graphs, SBOM aggregation, ISA lifecycle, and CVE triage with SLA enforcement. It operates behind an anti-corruption layer that shields the internal domain from volatile external vendor data formats.
+
+#### Core Aggregate: DependencyGraph
+
+```
+DependencyGraph (Aggregate Root)
+├── project_id: str
+├── vendors: List[Vendor]
+│   ├── vendor_id: str
+│   ├── name: str
+│   ├── scrm_assessment: ScrmAssessment
+│   │   ├── assessed: bool
+│   │   ├── risk_level: enum  # critical | high | medium | low
+│   │   └── assessed_at: datetime
+│   └── isa_status: enum      # draft | active | expired | terminated
+├── dependencies: List[Dependency]  # adjacency list (D27)
+│   ├── source_id: str
+│   ├── target_id: str
+│   ├── relationship: enum
+│   └── depth: int
+├── sbom_entries: List[SbomEntry]
+│   ├── component: str
+│   ├── version: str
+│   └── license: str
+└── cve_triage: List[CveTriage]
+    ├── cve_id: str
+    ├── severity: enum
+    ├── sla_deadline: datetime
+    └── status: enum          # open | triaged | mitigated | accepted
+```
+
+#### Key Invariants
+
+1. **SCRM assessment required:** All vendors in the dependency graph must have a completed SCRM assessment before being marked as approved.
+2. **Graph stored as adjacency list:** No graph database needed — SQL adjacency list (D27).
+3. **CVE SLA enforcement:** Critical CVEs have 48h SLA, High 7d, Medium 30d, Low 90d.
+4. **ISA lifecycle:** ISAs must be active (not expired/terminated) for vendor dependencies to be valid.
+
+#### Domain Events
+
+| Event | Published/Consumed | Description |
+|---|---|---|
+| `VendorAdded` | Published | New vendor registered |
+| `ScrmAssessmentCompleted` | Published | Vendor risk assessment finished |
+| `CveDetected` | Published | New CVE found in dependency |
+| `CveTriaged` | Published | CVE triaged with disposition |
+| `SlaBreach` | Published | CVE SLA deadline passed |
+| `IsaExpired` | Published | Vendor ISA expired |
+| `SbomGenerated` | Published | SBOM regenerated on build |
+
+#### Anti-Corruption Layer
+
+- **Outbound to External Vendors:** All vendor data passes through the ACL in `scrm_assessor.py`. External vendor formats (NVD JSON, vendor security questionnaires) are translated into the internal `Vendor` and `ScrmAssessment` models.
+- **Inbound from External CVE feeds:** CVE data is normalized into the internal `CveTriage` model regardless of source format.
+
+#### Integration Patterns
+
+- **ACL to External Vendors:** Translates heterogeneous vendor data formats into uniform internal models.
+- **SBOM feeds Compliance:** Generated SBOMs are consumed by Compliance for control evidence.
+
+---
+
+### 7. MBSE
+
+**Directory:** `tools/mbse/`
+**Agent:** (shares Architect agent, port 9444)
+**Domain Type:** Supporting
+
+#### Overview
+
+The MBSE (Model-Based Systems Engineering) context manages SysML model import, DOORS NG ReqIF parsing, digital thread traceability, model-to-code generation, and drift detection. It maintains the N:M digital thread links (D12) that connect model elements to code, requirements, tests, and compliance controls.
+
+#### Core Aggregate: DigitalThread
+
+```
+DigitalThread (Aggregate Root)
+├── project_id: str
+├── model_elements: List[ModelElement]
+│   ├── element_id: str
+│   ├── element_type: enum    # block | requirement | interface | activity | state
+│   ├── source: enum          # xmi | reqif | manual
+│   └── trace_links: List[TraceLink]    # N:M (D12)
+│       ├── target_type: enum # code | requirement | test | control
+│       ├── target_id: str
+│       └── link_type: enum   # implements | satisfies | verifies | traces_to
+├── heatmap: ThreadHeatmap
+│   ├── matrix: dict          # N x M artifact-type cross-reference (D-INV-17)
+│   └── orphans: List[str]    # unlinked elements
+└── drift_report: Optional[DriftReport]
+    ├── drifted_elements: List[str]
+    └── detected_at: datetime
+```
+
+#### Key Invariants
+
+1. **Trace completeness:** Every model element must have at least one trace link to another artifact (requirement, code, test, or control).
+2. **N:M linking:** One block can trace to many code modules; one control can trace to many requirements (D12).
+3. **Drift detection:** Model-to-code drift must be detected and reported; does not auto-fix (advisory only).
+4. **XML parsing:** Uses Python stdlib `xml.etree.ElementTree` only — zero external dependencies, air-gap safe (D7).
+
+#### Domain Events
+
+| Event | Published/Consumed | Description |
+|---|---|---|
+| `ModelImported` | Published | XMI or ReqIF model parsed and stored |
+| `TraceLinkCreated` | Published | New digital thread link established |
+| `OrphanDetected` | Published | Model element without trace link |
+| `DriftDetected` | Published | Model-code drift identified |
+| `CodeGenerated` | Published | Model-to-code generation completed |
+| `ModelElementLinked` | Published | Sent to Requirements for bidirectional linking |
+| `RequirementDecomposed` | Consumed | From Requirements — new element to link |
+
+#### Anti-Corruption Layer
+
+- **Inbound from XMI/ReqIF:** Parsers (`xmi_parser.py`, `reqif_parser.py`) translate vendor-specific model formats into normalized `ModelElement` records.
+- **Outbound to Requirements:** Model elements are expressed in Requirements' ubiquitous language when creating trace links.
+
+#### Integration Patterns
+
+- **Partnership with Requirements:** Both contexts co-evolve. MBSE provides model elements; Requirements provides decomposed stories. Both contribute to the digital thread.
+- **Heatmap** (`thread_heatmap.py`): Cross-context coverage gap detection across artifact types (D-INV-17).
+
+---
+
+### 8. Embedded
+
+**Directory:** `tools/embedded/` + `tools/fleet/` + `tools/edge_ai/`
+**Agents:** (multiple, via Orchestrator)
+**Domain Type:** Generic
+
+#### Overview
+
+The Embedded context spans three subdirectories and covers the SparkPilot four-tier architecture: natural language to firmware, device fleet management, OTA updates, edge AI model lifecycle, gamified missions, and the browser simulator. It operates behind an ACL when interfacing with Compliance because embedded systems use different compliance frameworks (IEC 62443, DO-178C) than the core NIST 800-53.
+
+#### Core Aggregate: Device
+
+```
+Device (Aggregate Root)
+├── device_id: str
+├── name: str
+├── board: enum               # esp32-s3 | stm32f407 | nrf52840 | rpi-pico | simulator
+├── status: enum              # registered | online | offline | degraded
+├── firmware: FirmwareState
+│   ├── current_version: str
+│   ├── sbom: Optional[Sbom]  # CycloneDX 1.5 JSON (D-INV-45)
+│   ├── vex: Optional[Vex]    # CSAF 2.0 (D-INV-46)
+│   └── deployed_at: datetime
+├── telemetry: DeviceTelemetry
+│   ├── last_heartbeat: datetime
+│   ├── health_metrics: dict
+│   └── crash_dumps: List[CrashDump]
+├── ml_models: List[DeployedModel]
+│   ├── model_id: str
+│   ├── task: enum            # anomaly_detection | classification | regression
+│   └── inference_stats: dict
+├── ota_history: List[OtaUpdate]
+│   ├── firmware_id: str
+│   ├── status: enum          # pending | downloading | installing | verified | rolled_back
+│   └── canary: bool
+└── group_id: Optional[str]   # fleet group for canary deployments
+```
+
+#### Key Invariants
+
+1. **SBOM required for deployment:** No firmware can be deployed to a device without an accompanying SBOM (D-INV-45).
+2. **Self-healing stability window:** After crash-triggered rollback, 72-hour stability window before re-deployment.
+3. **Canary deployment:** Fleet-wide OTA requires canary phase (configurable percentage) before full rollout.
+4. **SDK size constraint:** SparkPilot Device SDK must remain under ~8KB flash footprint.
+
+#### Domain Events
+
+| Event | Published/Consumed | Description |
+|---|---|---|
+| `DeviceRegistered` | Published | New device added to fleet |
+| `FirmwareDeployed` | Published | OTA update completed |
+| `FirmwareRolledBack` | Published | Self-healing rollback triggered |
+| `CrashDetected` | Published | Crash dump received from device |
+| `HeartbeatReceived` | Published | Device health telemetry |
+| `ModelDeployed` | Published | TinyML model pushed to device |
+| `SbomGenerated` | Published | Firmware SBOM created, forwarded to Compliance ACL |
+
+#### Anti-Corruption Layer
+
+- **Outbound to Compliance:** Embedded compliance frameworks (IEC 62443, DO-178C, ISO 26262, IEC 62304, MISRA C:2023, FIPS 140-3, EU AI Act) are translated into NIST 800-53 equivalents when crossing the context boundary to Compliance. The `firmware_sbom.py` tool produces CycloneDX format that Compliance consumes directly.
+- **Inbound from Compliance:** NIST control requirements are translated into embedded-specific checks by the compliance ACL layer.
+
+#### Integration Patterns
+
+- **ACL to Compliance:** Framework translation layer. Embedded speaks IEC 62443; Compliance speaks NIST 800-53. The ACL maintains the mapping table.
+- **Progressive compliance:** Beginner Mode hides compliance complexity; Pro Mode exposes full framework coverage.
+
+---
+
+### 9. Observability
+
+**Directory:** `tools/observability/`
+**Agent:** Monitor (port 9450)
+**Domain Type:** Supporting
+
+#### Overview
+
+The Observability context provides distributed tracing (OTel + SQLite dual-mode), W3C PROV provenance graphs, AgentSHAP tool attribution, and XAI compliance assessment. It is a cross-cutting concern that monitors all other contexts.
+
+#### Core Aggregate: Trace
+
+```
+Trace (Aggregate Root)
+├── trace_id: str
+├── project_id: str
+├── tracer_type: enum         # otel | sqlite | null (D280)
+├── spans: List[Span]
+│   ├── span_id: str
+│   ├── parent_span_id: Optional[str]
+│   ├── operation: str
+│   ├── start_time: datetime
+│   ├── end_time: datetime
+│   └── attributes: dict
+├── provenance: ProvenanceGraph    # W3C PROV-AGENT (D287)
+│   ├── entities: List[Entity]
+│   ├── activities: List[Activity]
+│   └── derivations: List[Derivation]
+├── shap_values: Optional[ShapAnalysis]
+│   ├── tool_attributions: dict    # Monte Carlo Shapley values
+│   └── top_contributors: List[str]
+└── xai_assessment: Optional[XaiAssessment]
+    ├── checks_passed: int         # out of 10
+    └── findings: List[str]
+```
+
+#### Key Invariants
+
+1. **Active tracing required:** Production deployments must have tracing active (not NullTracer).
+2. **Provenance append-only:** PROV-AGENT provenance stored in 3 append-only SQLite tables (D287).
+3. **XAI compliance gate:** XAI assessment must be completed before production release.
+4. **Pluggable tracer:** Tracer ABC with three implementations — OTelTracer (production), SQLiteTracer (air-gapped), NullTracer (fallback) (D280).
+
+#### Domain Events
+
+| Event | Published/Consumed | Description |
+|---|---|---|
+| `TraceStarted` | Published | New distributed trace initiated |
+| `TraceCompleted` | Published | Trace finalized with all spans |
+| `ProvenanceRecorded` | Published | W3C PROV entity/activity stored |
+| `ShapAnalysisCompleted` | Published | AgentSHAP attribution computed |
+| `XaiAssessmentCompleted` | Published | 10-check XAI assessment finished |
+| `*` (all events) | Consumed | Observability monitors events from all contexts |
+
+#### Anti-Corruption Layer
+
+- **Inbound from all contexts:** Observability accepts events from every bounded context. It normalizes diverse event formats into its span/trace model. No context-specific logic leaks into Observability.
+
+#### Integration Patterns
+
+- **Cross-cutting monitor:** Subscribes to events from all contexts for tracing and provenance.
+- **Dual-mode deployment:** OTel for connected environments, SQLite for air-gapped (D280).
+
+---
+
+### 10. GovCon
+
+**Directory:** `tools/govcon/`
+**Agent:** (accessed via Orchestrator)
+**Domain Type:** Generic
+
+#### Overview
+
+The GovCon (Government Contracting) context manages the proposal lifecycle, SAM.gov opportunity scanning, RFP requirement extraction, compliance matrix generation, color reviews, and post-award CPMP (Contract Performance Management). It is feature-flag isolated (`ICDEV_GOVCON_ENABLED`) and communicates with Compliance via a read-only Published Language.
+
+#### Core Aggregate: Proposal
+
+```
+Proposal (Aggregate Root)
+├── proposal_id: str
+├── opportunity: SamOpportunity
+│   ├── notice_id: str
+│   ├── title: str
+│   └── requirements: List[ShallStatement]
+├── volumes: List[Volume]
+│   ├── volume_type: enum     # technical | management | past_performance | cost
+│   └── sections: List[Section]
+│       ├── section_id: str
+│       ├── drafts: List[Draft]  # versioned
+│       └── compliance_status: enum
+├── compliance_matrix: ComplianceMatrix
+│   ├── entries: List[MatrixEntry]
+│   └── coverage_pct: float
+├── color_reviews: List[ColorReview]
+│   ├── color: enum           # pink | red | green | blue | gold
+│   └── findings: List[str]
+└── cpmp: Optional[CpmpContract]
+    ├── contract_id: str
+    ├── evm_metrics: dict
+    ├── cpars_prediction: dict
+    └── cdrls: List[Cdrl]
+```
+
+#### Key Invariants
+
+1. **Read-only bridge to Compliance:** GovCon can query compliance control status but NEVER writes to compliance tables (D-WG-8).
+2. **Feature-flag isolation:** Entire context gated by `ICDEV_GOVCON_ENABLED` env var.
+3. **Excluded from child apps:** `PARENT_ONLY_DIRS` ensures GovCon is not inherited by generated child applications.
+4. **Management Volume references portal:** Management Volume responses must reference the post-award management portal.
+
+#### Domain Events
+
+| Event | Published/Consumed | Description |
+|---|---|---|
+| `OpportunityScanned` | Published | SAM.gov opportunity imported |
+| `ProposalCreated` | Published | New proposal lifecycle started |
+| `SectionDrafted` | Published | Volume section draft generated |
+| `ColorReviewCompleted` | Published | Review gate passed/failed |
+| `ComplianceMatrixUpdated` | Published | Matrix coverage recalculated |
+| `ControlStatusChanged` | Consumed | From Compliance — read-only query |
+
+#### Anti-Corruption Layer
+
+- **Inbound from Compliance:** Published Language — GovCon reads compliance data through a standardized query interface. The bridge translates Compliance's internal model into GovCon's compliance matrix format.
+- **No outbound writes:** GovCon never publishes events that modify Compliance state.
+
+#### Integration Patterns
+
+- **Published Language with Compliance:** Compliance publishes a stable read-only API. GovCon consumes it without coupling to Compliance internals.
+- **RAG integration:** 9 GovCon tables registered in `tools/rag/source_registry.py` for hybrid search enrichment.
+- **Fine-tuning bridge:** `pair_generator.py --generate-from-govcon` creates training pairs from approved drafts.
+
+---
+
+### 11. CloudForge
+
+**Directory:** `tools/cloudforge/`
+**Agent:** (accessed via Orchestrator + Ops MCP server)
+**Domain Type:** Generic
+
+#### Overview
+
+The CloudForge context manages operational runbooks (DAG-based workflow execution), the application metastore (dependency graph, RTO/RPO tracking), and cross-domain operations queries (zones, budgets, SIEM, migrations, deployments, topologies). It shares a kernel with DevSecOps for pipeline and policy models.
+
+#### Core Aggregate: Runbook
+
+```
+Runbook (Aggregate Root)
+├── runbook_id: str
+├── name: str
+├── description: str
+├── tasks_json: dict          # JSON DAG (D-CF-19)
+│   └── tasks: List[Task]
+│       ├── task_id: str
+│       ├── task_type: enum
+│       ├── parameters: dict
+│       └── condition: Optional[Condition]  # key-operator-value (D-CF-25)
+├── edges_json: dict          # DAG edges for topological sort
+├── executions: List[Execution]  # append-only (D-CF-20)
+│   ├── execution_id: str
+│   ├── status: enum          # pending | running | completed | failed
+│   └── task_logs: List[TaskLog]
+├── snippets: List[Snippet]   # self-contained sub-DAGs (D-CF-22)
+│   ├── snippet_id: str
+│   └── usage_count: int
+└── metastore_app: Optional[MetastoreApp]
+    ├── app_id: str
+    ├── dependencies: List[str]  # adjacency list (D-CF-23)
+    ├── rto_hours: float         # (D-CF-27)
+    └── rpo_hours: float
+```
+
+#### Key Invariants
+
+1. **Kahn's algorithm execution:** DAG execution uses topological sort — deterministic O(V+E), no LLM in critical path (D-CF-21).
+2. **Append-only execution log:** All execution records and task logs are immutable (D-CF-20, NIST AU).
+3. **Conditional branching safety:** Conditions use key-operator-value triples only — no `eval()` (D-CF-25).
+4. **AI generation is draft-only:** AI-generated runbooks always output `status='draft'` (D-CF-26).
+5. **Auto-discovery idempotent:** Metastore auto-discovery from db_connections, cf_landing_zones, devices uses idempotent upsert (D-CF-24).
+
+#### Domain Events
+
+| Event | Published/Consumed | Description |
+|---|---|---|
+| `RunbookCreated` | Published | New runbook DAG defined |
+| `RunbookExecutionStarted` | Published | DAG execution initiated |
+| `RunbookExecutionCompleted` | Published | All tasks finished |
+| `TaskCompleted` | Published | Individual task in DAG finished |
+| `AppRegistered` | Published | Application added to metastore |
+| `DependencyDiscovered` | Published | Auto-discovery found new dependency |
+| `RtoBreachRisk` | Published | Application approaching RTO threshold |
+| `PolicyGenerated` | Consumed | From DevSecOps — shared kernel |
+
+#### Anti-Corruption Layer
+
+- **Shared Kernel with DevSecOps:** Pipeline security configurations and policy-as-code models are co-owned. Changes to shared YAML schemas in `args/` require agreement from both contexts.
+
+#### Integration Patterns
+
+- **Shared Kernel with DevSecOps:** Both contexts read/write shared pipeline and policy configurations.
+- **YAML runbook templates:** Stored in `args/cloudforge_runbook_templates/` following GOTCHA args layer convention (D-CF-29).
+- **Ops MCP server:** Unified 18-tool MCP server (D-CF-28) exposes both runbook and metastore operations.
+
+---
+
+### 12. Knowledge
+
+**Directory:** `tools/memory/` + `tools/rag/`
+**Agent:** Knowledge (port 9449)
+**Domain Type:** Generic
+
+#### Overview
+
+The Knowledge context manages the dual-storage memory system (markdown files + SQLite databases), hybrid search (keyword + semantic), self-healing pattern detection, and RAG (Retrieval-Augmented Generation) source registry. It serves as a utility context consumed by all other bounded contexts.
+
+#### Core Aggregate: MemoryEntry
+
+```
+MemoryEntry (Aggregate Root)
+├── entry_id: str
+├── content: str
+├── memory_type: enum         # fact | preference | event | insight | task | relationship
+├── importance: int           # 1-10
+├── created_at: datetime
+├── embedding: Optional[bytes]  # OpenAI text-embedding-3-small, 1536 dims
+├── access_log: List[AccessRecord]
+│   ├── accessed_at: datetime
+│   └── query: str
+└── source: MemorySource
+    ├── source_type: enum     # manual | daily_log | tool_output | rag
+    └── source_ref: str
+```
+
+```
+RagSourceRegistry
+├── sources: List[RegisteredSource]
+│   ├── source_name: str
+│   ├── table_name: str
+│   ├── content_columns: List[str]
+│   └── search_type: enum    # keyword | semantic | hybrid
+```
+
+#### Key Invariants
+
+1. **Hybrid search weights:** Default ranking is 0.7 * BM25 (keyword) + 0.3 * semantic (vector). Configurable via `--bm25-weight` and `--semantic-weight` flags.
+2. **Embedding model:** OpenAI `text-embedding-3-small` (1536 dimensions), stored as BLOBs in SQLite.
+3. **Dual storage:** Every memory entry exists in both markdown (human-readable) and SQLite (searchable).
+4. **Access logging:** All memory reads are logged for access pattern analysis.
+
+#### Domain Events
+
+| Event | Published/Consumed | Description |
+|---|---|---|
+| `MemoryWritten` | Published | New entry stored in both markdown and DB |
+| `MemoryAccessed` | Published | Entry retrieved via search |
+| `EmbeddingGenerated` | Published | Vector embedding computed for entry |
+| `PatternDetected` | Published | Self-healing pattern identified |
+| `RecommendationGenerated` | Published | Knowledge-based recommendation produced |
+| `*` (queries from all contexts) | Consumed | Knowledge responds to search requests from any context |
+
+#### Anti-Corruption Layer
+
+- **Inbound from all contexts:** Search queries from any context are normalized into the hybrid search interface. Context-specific terminology is handled by the RAG source registry which knows how to search each registered table.
+
+#### Integration Patterns
+
+- **Utility service:** Knowledge is a generic subdomain that serves all other contexts. It has no upstream dependencies.
+- **RAG source registry:** 9 GovCon tables + core tables registered for cross-context semantic search.
+- **Self-healing loop:** Pattern detection feeds Knowledge agent recommendations back to requesting contexts.
+
+---
+
+## Integration Patterns Summary
+
+```mermaid
+graph LR
+    subgraph patterns["Integration Patterns"]
+        CF_CONF[Conformist]
+        CF_CS[Customer/Supplier]
+        CF_PART[Partnership]
+        CF_ACL[Anti-Corruption Layer]
+        CF_PL[Published Language]
+        CF_SK[Shared Kernel]
+    end
+
+    subgraph relationships["Context Relationships"]
+        R1["Security --Conformist--> Compliance"]
+        R2["Requirements --C/S--> Compliance"]
+        R3["Requirements --C/S--> Simulation"]
+        R4["MBSE <--Partnership--> Requirements"]
+        R5["Supply Chain --ACL--> External Vendors"]
+        R6["Embedded --ACL--> Compliance"]
+        R7["GovCon --Pub Language--> Compliance"]
+        R8["CloudForge <--Shared Kernel--> DevSecOps"]
+    end
+```
+
+| Pattern | Upstream | Downstream | Coupling | Data Flow |
+|---|---|---|---|---|
+| **Conformist** | Compliance | Security | High (intentional) | Security adopts Compliance's control model verbatim |
+| **Customer/Supplier** | Compliance | Requirements | Medium | Requirements requests; Compliance fulfills on own schedule |
+| **Customer/Supplier** | Simulation | Requirements | Medium | Requirements triggers; Simulation delivers results |
+| **Partnership** | MBSE | Requirements | High (co-evolution) | Bidirectional trace link management |
+| **ACL** | External Vendors | Supply Chain | Low (isolated) | Vendor data translated at boundary |
+| **ACL** | Compliance | Embedded | Low (framework translation) | IEC 62443/DO-178C translated to NIST 800-53 |
+| **Published Language** | Compliance | GovCon | Low (read-only) | Stable read-only query interface |
+| **Shared Kernel** | DevSecOps | CloudForge | High (co-owned) | Shared pipeline/policy YAML schemas |
+
+---
+
+## Anti-Corruption Layer Index
+
+| ACL | Location | Purpose |
+|---|---|---|
+| Supply Chain External ACL | `tools/supply_chain/scrm_assessor.py` | Translates external vendor formats to internal models |
+| Embedded-Compliance ACL | `tools/compliance/firmware_sbom.py` | Translates IEC 62443/DO-178C to NIST 800-53 |
+| GovCon Read Bridge | `tools/govcon/` (read-only queries) | Prevents GovCon from writing to Compliance tables |
+| MBSE Import ACL | `tools/mbse/xmi_parser.py`, `reqif_parser.py` | Normalizes vendor model formats to internal schema |
+| Knowledge RAG ACL | `tools/rag/source_registry.py` | Normalizes cross-context search queries |
+| Observability Event ACL | `tools/observability/` | Normalizes diverse event formats to span/trace model |
+
+---
+
+## Key Architecture Decisions Referenced
+
+| Decision | Summary |
+|---|---|
+| D6 | Audit trail is append-only/immutable (NIST AU) |
+| D7 | Python stdlib XML parsing (zero deps, air-gap safe) |
+| D12 | N:M digital thread links |
+| D21 | Deterministic weighted average for readiness scoring |
+| D22 | Monte Carlo uses Python stdlib random |
+| D27 | SQL adjacency list for dependency graphs |
+| D117 | DevSecOps hard veto on pipeline/ZTA configuration |
+| D120 | DoD 7-pillar ZTA scoring model |
+| D280 | Pluggable Tracer ABC (OTel/SQLite/Null) |
+| D287 | W3C PROV-AGENT in append-only SQLite |
+| D-DB-21 | Storage abstraction — all tools use `get_connection()` |
+| D-CF-21 | Kahn's algorithm for DAG execution |
+| D-CF-25 | No `eval()` — key-operator-value conditions only |
+| D-INV-25 | Deterministic STRIDE analysis (no LLM) |
+| D-INV-26 | STRIDE-to-NIST control mapping |
+| D-WG-8 | GovCon read-only bridge to Compliance |
+
+---
+
+*CUI // SP-CTI*