icdev 0.0.3__py3-none-any.whl

docs/research/architecture-patterns-c4-ddd-agentic.md

@@ -0,0 +1,871 @@
+# CUI // SP-CTI
+# ICDEV Architecture Research: C4, Microservices, Agentic Patterns, and DDD
+
+**Date:** 2026-03-08
+**Scope:** Software architecture and design patterns for ICDEV's evolution
+**Classification:** CUI // SP-CTI
+
+---
+
+## Table of Contents
+
+1. [C4 Model Mapping to GOTCHA Framework](#1-c4-model-mapping-to-gotcha-framework)
+2. [Microservices Patterns for ICDEV](#2-microservices-patterns-for-icdev)
+3. [Agentic Architecture Patterns](#3-agentic-architecture-patterns)
+4. [Domain-Driven Design for ICDEV](#4-domain-driven-design-for-icdev)
+5. [Prioritized Recommendations](#5-prioritized-recommendations)
+6. [Sources](#6-sources)
+
+---
+
+## 1. C4 Model Mapping to GOTCHA Framework
+
+The C4 model (Context, Container, Component, Code) provides four zoom levels for
+visualizing software architecture. Each level maps to a specific layer of ICDEV's
+GOTCHA framework and multi-agent architecture.
+
+### 1.1 Level 1 — System Context
+
+This diagram answers: "What is ICDEV and who/what interacts with it?"
+
+ICDEV appears as the central software system, surrounded by actors and external systems:
+
+| Actor / External System | Type | Relationship |
+|---|---|---|
+| Developer / Engineer | Person | Uses ICDEV for compliance automation, firmware dev, threat modeling |
+| Authorizing Official (AO) | Person | Consumes ATO artifacts, approves P-ATO/ATO |
+| ISSO | Person | Reviews compliance posture, manages security exceptions |
+| AWS GovCloud (us-gov-west-1) | External System | Infrastructure target, Bedrock LLM provider |
+| Jira / GitLab | External System | Issue tracking, CI/CD pipeline integration |
+| DOORS NG | External System | Requirements source via ReqIF import |
+| SAM.gov | External System | GovCon opportunity scanning |
+| Ollama | External System | Local LLM inference (qwen3.5, phi4-reasoning, llava) |
+| NIST NVD | External System | CVE feed for supply chain triage |
+| Supabase | External System | Marketplace SaaS backend (D-DB-24) |
+
+**Key decision:** The 12 internal agents do NOT appear at Level 1. Per C4 microservices
+guidance, components owned by the same team remain internal details at this level. Agents
+should only be promoted to "software system" boxes if a separate team owns them.
+
+### 1.2 Level 2 — Container Diagram
+
+Zooms into ICDEV to show major runtime containers:
+
+| Container | Technology | Purpose |
+|---|---|---|
+| Orchestrator Agent | Python, port 9443 | API Gateway + task routing (A2A JSON-RPC 2.0) |
+| Architect Agent | Python, port 9444 | ATLAS A/T phases, system design |
+| Builder Agent | Python, port 9445 | TDD code generation (RED->GREEN->REFACTOR) |
+| Compliance Agent | Python, port 9446 | ATO artifacts, 9-framework compliance |
+| Security Agent | Python, port 9447 | SAST, dependency audit, secret detection |
+| Knowledge Agent | Python, port 9449 | Self-healing patterns, recommendations |
+| Monitor Agent | Python, port 9450 | Log analysis, metrics, alerts |
+| Requirements Agent | Python, port 9453 | Conversational intake, gap detection |
+| Supply Chain Agent | Python, port 9454 | Dependency graph, SBOM, CVE triage |
+| Simulation Agent | Python, port 9455 | Digital Program Twin, Monte Carlo |
+| DevSecOps/ZTA Agent | Python, port 9457 | Pipeline security, Zero Trust policy |
+| Connector Forge Agent | Python, port 9458 | Dynamic connector generation |
+| MCP Servers (12) | Python stdio | Tool exposure to Claude Code |
+| Flask Dashboard | Python/Jinja2, port 5000 | Web UI for humans |
+| PostgreSQL | PostgreSQL (primary) | Operational data, 348+ tables |
+| SQLite | SQLite (fallback) | Air-gap/portable: memory.db, activity.db, icdev.db |
+| Ollama Runtime | Go + GGUF models | Local LLM inference |
+
+**Communication pathways to show on diagram:**
+- Agent <-> Agent: JSON-RPC 2.0 over mTLS (A2A protocol)
+- Claude Code <-> MCP Server: stdio (Model Context Protocol)
+- Dashboard <-> Database: SQL via storage abstraction layer
+- Agent <-> Ollama: HTTP `/api/chat`
+- Agent <-> AWS Bedrock: HTTPS (Claude Sonnet)
+- Agent <-> External Systems: HTTPS with auth
+
+### 1.3 Level 3 — Component Diagram
+
+Each agent zooms into its internal components. These map directly to GOTCHA's Tools
+layer. Example for the Compliance Agent (port 9446):
+
+| Component | Module | Responsibility |
+|---|---|---|
+| SSP Generator | `tools/compliance/ssp_generator.py` | System Security Plan generation |
+| POAM Generator | `tools/compliance/poam_generator.py` | Plan of Action & Milestones |
+| STIG Checker | `tools/compliance/stig_checker.py` | Security Technical Implementation Guide |
+| Crosswalk Engine | `tools/compliance/crosswalk_engine.py` | Multi-framework control mapping |
+| FedRAMP Assessor | `tools/compliance/fedramp_assessor.py` | Moderate/High baseline assessment |
+| CMMC Assessor | `tools/compliance/cmmc_assessor.py` | Cybersecurity maturity certification |
+| SbD Assessor | `tools/compliance/sbd_assessor.py` | CISA Secure by Design |
+| cATO Engine | `tools/compliance/cato_live_engine.py` | Continuous ATO evidence streaming |
+| Narrative Workflow | `tools/compliance/narrative_workflow.py` | AI-generated compliance narratives |
+| OSCAL Generator | `tools/compliance/oscal_generator.py` | OSCAL artifact output |
+| Template Exchange | `tools/compliance/template_exchange.py` | Community template sharing |
+| Classification Mgr | `tools/compliance/classification_manager.py` | Impact level classification |
+
+Similar component diagrams exist for each of the 12 agents, with the `tools/` subdirectory
+structure defining natural component boundaries.
+
+### 1.4 Level 4 — Code Diagram
+
+Individual tool scripts and their internal classes/functions. The C4 model explicitly
+recommends that Level 4 be auto-generated from code (IDE class diagrams) rather than
+manually maintained. ICDEV's `tools/analysis/code_analyzer.py` AST-based analysis
+already provides the raw data for this level.
+
+### 1.5 GOTCHA-to-C4 Mapping Summary
+
+| GOTCHA Layer | C4 Level | Rationale |
+|---|---|---|
+| Goals | N/A (process, not runtime) | Goals are workflow definitions, not architectural elements |
+| Orchestration (Claude) | Level 2 Container (Orchestrator Agent) | The LLM orchestrator is a runtime container |
+| Tools | Level 3 Components | Each tool is a component within its owning agent |
+| Args | Level 3 (config artifacts) | Configuration that parameterizes components |
+| Context | N/A (static reference) | Not a runtime element |
+| Hard Prompts | N/A (LLM instructions) | Operational artifacts, not architectural elements |
+
+### 1.6 Recommendation: Structurizr DSL
+
+Adopt Structurizr DSL to define the architecture model as code (a `.dsl` file checked
+into the repository). Benefits:
+
+- Version-controlled architecture diagrams (diff-able in PRs)
+- Auto-generation of all four C4 levels from one model
+- Export to PlantUML, Mermaid, PNG, SVG
+- Aligns with GOTCHA principle of "deterministic tools, not probabilistic LLM"
+
+Proposed file: `docs/architecture/icdev.dsl`
+
+Example skeleton:
+
+```
+workspace "ICDEV" "Intelligent Certified Development Platform" {
+    model {
+        developer = person "Developer" "Uses ICDEV for compliance automation"
+        ao = person "Authorizing Official" "Approves ATO"
+        isso = person "ISSO" "Reviews compliance posture"
+
+        icdev = softwareSystem "ICDEV" "AI-powered compliance & development platform" {
+            orchestrator = container "Orchestrator Agent" "Task routing, workflow mgmt" "Python" "Agent"
+            compliance = container "Compliance Agent" "ATO artifacts, 9 frameworks" "Python" "Agent" {
+                sspGen = component "SSP Generator" "System Security Plan" "Python"
+                crosswalk = component "Crosswalk Engine" "Multi-framework mapping" "Python"
+                catoEngine = component "cATO Engine" "Continuous evidence streaming" "Python"
+            }
+            dashboard = container "Flask Dashboard" "Web UI" "Python/Jinja2" "WebApp"
+            postgresql = container "PostgreSQL" "Operational data" "PostgreSQL" "Database"
+            sqlite = container "SQLite" "Air-gap fallback" "SQLite" "Database"
+        }
+
+        aws = softwareSystem "AWS GovCloud" "Infrastructure & Bedrock LLM" "External"
+        doorsng = softwareSystem "DOORS NG" "Requirements source" "External"
+        samgov = softwareSystem "SAM.gov" "Opportunity scanning" "External"
+        ollama = softwareSystem "Ollama" "Local LLM inference" "External"
+
+        developer -> icdev "Uses"
+        ao -> icdev "Reviews ATO artifacts"
+        icdev -> aws "Deploys to, uses Bedrock"
+        icdev -> doorsng "Imports ReqIF"
+        icdev -> samgov "Scans opportunities"
+        icdev -> ollama "Local LLM inference"
+    }
+
+    views {
+        systemContext icdev "SystemContext" {
+            include *
+            autoLayout
+        }
+        container icdev "Containers" {
+            include *
+            autoLayout
+        }
+        component compliance "ComplianceComponents" {
+            include *
+            autoLayout
+        }
+    }
+}
+```
+
+---
+
+## 2. Microservices Patterns for ICDEV
+
+### 2.1 Sidecar Pattern — Compliance Injection
+
+**Current state:** Compliance markings (CUI // SP-CTI) are applied inline at generation
+time (D5). Each of the 255+ tools independently handles classification marking.
+
+**Problem:** Duplicated CUI marking logic across every tool. If the classification policy
+changes (e.g., IL4 -> IL5), every tool must be updated individually.
+
+**Recommendation:** Extract compliance marking, audit trail logging, and classification
+validation into a sidecar module that wraps tool execution:
+
+```python
+# tools/compliance/sidecar.py — compliance injection sidecar
+from functools import wraps
+
+def compliance_sidecar(impact_level="IL4", marking="CUI // SP-CTI"):
+    """Decorator that injects compliance markings and audit logging."""
+    def decorator(func):
+        @wraps(func)
+        def wrapper(*args, **kwargs):
+            # Pre-execution: validate classification context
+            validate_classification_context(impact_level)
+
+            # Execute the tool
+            result = func(*args, **kwargs)
+
+            # Post-execution: apply markings to output
+            result = apply_classification_markings(result, marking)
+
+            # Post-execution: write audit trail entry
+            emit_audit_event(func.__name__, impact_level, result)
+
+            return result
+        return wrapper
+    return decorator
+```
+
+This is the "process sidecar" variant (same-process, not separate container), appropriate
+for ICDEV's deployment model. It centralizes classification policy in one location and
+ensures no tool can accidentally skip marking.
+
+### 2.2 Circuit Breaker — LLM Provider Failover
+
+**Current state:** `tools/llm/router.py` implements a fallback chain (qwen3.5 ->
+phi4-reasoning -> claude-sonnet) with availability probing and TTL-based caching (1800s).
+
+**Gap:** The current implementation is a static fallback chain, not a true circuit breaker.
+It lacks failure counting with thresholds, half-open recovery probing, and metrics emission.
+
+**Recommendation:** Add three states to the router's availability cache:
+
+```
+CLOSED (normal)
+  └── failures >= threshold? ──> OPEN (tripped, skip provider)
+                                   └── cooldown elapsed? ──> HALF-OPEN (probe)
+                                                               ├── probe succeeds ──> CLOSED
+                                                               └── probe fails ──> OPEN
+```
+
+Implementation approach — add to `LLMRouter.__init__`:
+
+```python
+self._failure_counts: Dict[str, int] = {}       # provider -> consecutive failure count
+self._breaker_state: Dict[str, str] = {}         # provider -> "closed" | "open" | "half_open"
+self._breaker_opened_at: Dict[str, float] = {}   # provider -> timestamp when breaker opened
+self._failure_threshold: int = 5                  # trips after N consecutive failures
+self._half_open_cooldown: float = 300.0           # 5 min before probing
+```
+
+The existing 1800s `_cache_ttl` becomes the full reset interval. The 300s half-open
+cooldown provides faster recovery for transient Ollama restarts.
+
+### 2.3 Saga Pattern — ATLAS Workflow Orchestration
+
+**Current state:** ATLAS workflows (Model -> Architect -> Trace -> Link -> Assemble ->
+Stress_test) are orchestrated by Claude reading `goals/build_app.md` and executing steps
+sequentially. If step 3 (Link) fails, there is no automated compensating transaction.
+
+**Recommendation:** Implement an orchestration-based saga where the Orchestrator Agent
+maintains saga state:
+
+```
+saga_executions table:
+  saga_id TEXT PRIMARY KEY,
+  workflow TEXT,           -- "ATLAS", "RICOAS", "DevSecOps"
+  current_step INTEGER,
+  status TEXT,             -- "running", "compensating", "completed", "failed"
+  created_at TEXT,
+  updated_at TEXT
+
+saga_steps table:
+  saga_id TEXT,
+  step_index INTEGER,
+  step_name TEXT,          -- "architect", "trace", "link", "assemble", "stress_test"
+  status TEXT,             -- "pending", "running", "completed", "failed", "compensated"
+  output_ref TEXT,         -- reference to artifacts produced
+  compensation_ref TEXT,   -- reference to compensating action
+  started_at TEXT,
+  completed_at TEXT
+```
+
+Each ATLAS step registers a compensating action:
+- **Architect** compensation: archive generated design documents
+- **Trace** compensation: remove traceability matrix entries for this saga
+- **Link** compensation: unregister wired components, rollback dependency injection
+- **Assemble** compensation: delete build artifacts, revert test results
+- **Stress_test** compensation: invalidate gate check results
+
+On failure at step N, the coordinator executes compensations for steps N-1 through 1
+in reverse order. All compensations are audit-logged (append-only, D6).
+
+### 2.4 Event Sourcing — Enhancement Opportunities
+
+**Current state:** The audit trail is append-only/immutable (D6, NIST AU compliance).
+All state changes produce audit events. This is event sourcing.
+
+**Enhancements:**
+
+1. **Event replay:** Add `replay_from(timestamp)` to reconstruct system state at any
+   point. Supports FedRAMP continuous monitoring forensics and incident investigation.
+
+2. **Event snapshots:** For high-volume tables, periodically write snapshots to avoid
+   replaying thousands of events on startup. Snapshot interval configurable in
+   `args/storage_config.yaml`.
+
+3. **Event schema versioning:** As event payloads evolve, add a `schema_version` field
+   to audit events. Upcasters transform old events to current schema during replay.
+
+### 2.5 CQRS — Compliance Read/Write Separation
+
+**Current state:** All compliance operations go through the same `get_connection()` path.
+Reads (dashboard, reports) and writes (evidence collection, control updates) share the
+same connection pool.
+
+**Problem:** Compliance dashboards are read-heavy (AOs and ISSOs refreshing posture views)
+while evidence collection is write-heavy (continuous monitoring ingestion). Contention
+causes dashboard latency spikes during bulk evidence ingestion.
+
+**Recommendation:** Logical CQRS separation:
+
+```
+                  ┌──────────────────┐
+                  │   Command Side   │
+                  │ (write path)     │
+                  │                  │
+  ssp_generator ──┤  PostgreSQL      │
+  poam_generator ─┤  (primary)       │
+  cato_engine ────┤                  │
+                  └────────┬─────────┘
+                           │ logical replication
+                           │ or materialized views
+                  ┌────────▼─────────┐
+                  │   Query Side     │
+                  │ (read path)      │
+                  │                  │
+  dashboard ──────┤  Read replica    │
+  report_gen ─────┤  or mat. views   │
+  assessors ──────┤                  │
+                  └──────────────────┘
+```
+
+For SQLite fallback: use WAL mode (already implied by D-SC-3) which allows concurrent
+readers during writes.
+
+For PostgreSQL: use logical replication to a read replica, or materialized views
+refreshed on a configurable interval (default: 60 seconds).
+
+### 2.6 API Gateway — Orchestrator Formalization
+
+**Current state:** The Orchestrator Agent (port 9443) already routes tasks to domain
+agents. It functions as an implicit API gateway.
+
+**Recommendation:** Formalize with:
+
+- **Rate limiting** per agent (configurable in `args/agent_config.yaml`)
+- **Request correlation IDs** propagated through the full call chain (supports
+  distributed tracing, D280)
+- **Circuit breakers** per downstream agent (reuse pattern from 2.2)
+- **Load shedding** when Ollama or PostgreSQL reports high latency
+- **Authentication** via Agent Cards with JWT verification
+
+### 2.7 Service Mesh — Self-Consumption
+
+**Current state:** `service_mesh_generator.py` generates Istio/Linkerd configs for child
+applications. ICDEV itself does not run inside a service mesh.
+
+**Recommendation:** When deployed to AWS GovCloud EKS, ICDEV should consume its own
+generated service mesh configuration. The 12 agents become 12 pods with Istio sidecars:
+
+- mTLS between all agents (already required by D2)
+- Traffic management (canary deployments for agent updates)
+- Observability (distributed tracing via OTel, D280)
+- Rate limiting and circuit breaking at the infrastructure level
+
+This closes the gap between "we generate mesh configs" and "we run under mesh governance,"
+which is important for FedRAMP assessors who expect infrastructure-level controls.
+
+---
+
+## 3. Agentic Architecture Patterns
+
+### 3.1 GOTCHA as Structured ReAct
+
+ICDEV's GOTCHA framework is effectively a structured ReAct pattern with guardrails:
+
+| ReAct Step | GOTCHA Equivalent | Key Difference |
+|---|---|---|
+| **Reason** | Claude reads Goals + Context + Hard Prompts | Constrained by goal definitions |
+| **Act** | Claude invokes a Tool with Args | Action space limited to deterministic tools |
+| **Observe** | Claude reads tool output | Structured JSON output, not freeform |
+
+The critical insight: GOTCHA constrains the action space to deterministic tools, solving
+the "90% accuracy/step = 59% over 5 steps" problem described in CLAUDE.md. This is a
+deliberate architectural choice, not a limitation.
+
+Pure ReAct agents choose actions freely from their tool set. GOTCHA agents follow
+goal-defined sequences with tools as the execution mechanism. This is closer to a
+**structured Plan-and-Execute** pattern than pure ReAct.
+
+### 3.2 Plan-and-Execute for Cost Optimization
+
+**Current state:** ICDEV's three-tier LLM routing already implements the core
+Plan-and-Execute insight. The scanner tier (zero Claude tokens) and worker tier (~40%
+savings) provide significant cost optimization.
+
+**Recommendation — extend to ATLAS workflows:**
+
+```
+Phase 1: Claude (planner) generates full ATLAS execution plan
+  - Expected inputs/outputs per step
+  - Decision points and fallback strategies
+  - Estimated token budget per step
+
+Phase 2: qwen3.5 (executor) runs each step
+  - Invokes tools according to plan
+  - Monitors outputs against expected patterns
+  - Escalates to Claude ONLY on anomalies (unexpected output, tool failure)
+
+Phase 3: Claude (reviewer) validates final output
+  - Compliance gate verification
+  - Quality assessment against plan expectations
+  - Feedback loop for plan improvement
+```
+
+Estimated additional token savings: 50-60% for build workflows, based on the observation
+that most ATLAS steps involve deterministic tool invocation that qwen3.5 can handle.
+
+### 3.3 Multi-Agent Orchestration — Hybrid Hierarchical + Peer-to-Peer
+
+**Current architecture:** Pure hierarchical supervisor pattern.
+
+```
+Orchestrator (9443)
+  ├── Architect (9444)
+  ├── Builder (9445)
+  ├── Compliance (9446)
+  ├── Security (9447)
+  ├── Knowledge (9449)
+  ├── Monitor (9450)
+  ├── Requirements (9453)
+  ├── Supply Chain (9454)
+  ├── Simulation (9455)
+  ├── DevSecOps/ZTA (9457)
+  └── Connector Forge (9458)
+```
+
+**Problem:** Every inter-agent interaction routes through the Orchestrator, creating a
+bottleneck for tightly-coupled domain interactions.
+
+**Recommendation — selective peer-to-peer channels:**
+
+| Peer Pair | Interaction | Rationale |
+|---|---|---|
+| Security <-> Compliance | Threat-to-control mapping | STRIDE findings feed crosswalk engine directly |
+| Builder <-> Knowledge | Self-healing pattern lookup during TDD | Tight feedback loop, latency-sensitive |
+| Requirements <-> Simulation | Requirements feasibility simulation | Iterative feedback, many round-trips |
+| Compliance <-> DevSecOps | Policy generation from control requirements | Pipeline security depends on compliance state |
+| MBSE <-> Requirements | Model-to-requirement traceability | Digital thread creation is iterative |
+
+Implementation: agents maintain direct A2A connections for approved peer channels while
+the Orchestrator retains observability (agents report peer interactions back via audit
+events). The Orchestrator can revoke peer channels if behavioral anomalies are detected.
+
+### 3.4 A2A Protocol — Adopt the Formal Spec
+
+**Current state:** JSON-RPC 2.0 over mTLS with custom Agent Cards at
+`/.well-known/agent.json`.
+
+**Industry context (2025-2026):** Google's A2A protocol and Anthropic's MCP are both now
+under the Linux Foundation's Agentic AI Foundation (AAIF), launched December 2025 with
+six co-founders (OpenAI, Anthropic, Google, Microsoft, AWS, Block).
+
+Key distinction:
+- **MCP** = vertical (agent <-> tools/data) — ICDEV uses this correctly with 12 servers
+- **A2A** = horizontal (agent <-> agent) — ICDEV should adopt the formal spec
+
+**Migration path:**
+
+1. **Agent Cards:** Migrate from custom format to A2A Agent Card spec:
+   - Add capability declarations (what tasks each agent can handle)
+   - Add supported input/output modalities
+   - Add authentication scheme declarations
+   - Add rate limit declarations
+
+2. **Task lifecycle:** Adopt A2A task states:
+   ```
+   submitted -> working -> input-required -> completed
+                                          -> failed
+                                          -> canceled
+   ```
+   Maps to existing agent_tasks table with additional state granularity.
+
+3. **Streaming:** Add SSE (Server-Sent Events) support for long-running tasks:
+   - cATO evidence collection (may take minutes)
+   - Monte Carlo simulations (thousands of iterations)
+   - Full compliance assessments (9 frameworks)
+
+4. **Interoperability:** Register ICDEV agents with an A2A directory service for
+   cross-organization scenarios (e.g., a partner organization's compliance agent
+   querying ICDEV's compliance posture via standard A2A protocol).
+
+### 3.5 Agent Trust and Verification — CSA Agentic Trust Framework
+
+**Current state:** `agent_trust_scorer.py` provides trust scoring. `tool_chain_validator.py`
+validates tool chains. ZTA maturity scorer covers the 7-pillar DoD ZTA Strategy.
+
+**Industry evolution (February 2026):** The Cloud Security Alliance published the
+Agentic Trust Framework (ATF) defining tiered trust levels for AI agents:
+
+| Trust Level | Capabilities | ICDEV Mapping |
+|---|---|---|
+| **Intern** | Read-only, no modifications | New agent during validation period |
+| **Junior** | Recommend actions, require human approval | Agent with < N successful tasks |
+| **Senior** | Execute approved action types autonomously | Agent with established trust score |
+| **Principal** | Full autonomy within bounded context | Orchestrator after maturity assessment |
+
+**Recommendations:**
+
+1. **Tier mapping:** Map `agent_trust_scorer.py` output to these four tiers with explicit
+   promotion criteria:
+   - Intern -> Junior: 50 successful read-only tasks, zero anomalies
+   - Junior -> Senior: 200 successful tasks, < 2% anomaly rate, 30-day history
+   - Senior -> Principal: 1000 successful tasks, < 0.5% anomaly rate, security review
+
+2. **Behavioral drift detection:** Compare an agent's recent action patterns against its
+   historical baseline. Flag anomalies (e.g., the Compliance agent suddenly making
+   Builder-type tool calls). This extends the existing OWASP agentic security work.
+
+3. **Trust score decay:** Scores decrease over time without positive signals, forcing
+   continuous verification. A Senior agent that has been idle for 30 days reverts to
+   Junior, requiring re-validation. Aligned with ZTA "never trust, always verify."
+
+4. **Cryptographic agent identity:** Each agent gets a keypair. All inter-agent messages
+   are signed. The Orchestrator verifies signatures before routing. This builds on the
+   existing mTLS infrastructure.
+
+### 3.6 MCP Pattern Maturity
+
+ICDEV has 12 MCP servers. MCP crossed 97 million monthly SDK downloads by February 2026.
+
+**Recommendations for MCP evolution:**
+
+1. **MCP Resources:** Beyond tools, expose read-only data as MCP resources:
+   - Compliance posture summary (current control implementation status)
+   - Project metadata (impact level, classification, agent health)
+   - Recent audit events (last N entries)
+   This lets the LLM reference context without invoking a tool call.
+
+2. **MCP Sampling:** Use MCP's sampling capability to let tools request LLM completions
+   through a controlled interface. Useful for `narrative_workflow.py`'s two-tier LLM
+   pattern — the tool requests a draft from qwen3.5, then a review from Claude, all
+   through the MCP sampling protocol.
+
+3. **MCP Roots:** Declare project roots so the LLM understands file system boundaries.
+   Prevents accidental reads outside the project directory.
+
+4. **Server consolidation:** Consider merging related MCP servers to reduce connection
+   overhead:
+   - `compliance` + `devsecops` -> `governance` server
+   - `requirements` + `simulation` -> `analysis` server
+   - `security` + `supply-chain` -> `risk` server
+   This reduces 12 servers to ~8, cutting stdio connection overhead.
+
+---
+
+## 4. Domain-Driven Design for ICDEV
+
+### 4.1 Bounded Contexts
+
+ICDEV's `tools/` directory structure already reflects natural bounded contexts. Formalizing:
+
+| Bounded Context | Tools Directory | Core Domain Concept | Database Tables (examples) |
+|---|---|---|---|
+| **Compliance** | `tools/compliance/` | Control implementation & evidence | compliance_controls, compliance_evidence, sbd_exceptions |
+| **Security** | `tools/security/` | Threat detection & mitigation | threat_models, vulnerabilities, agent_trust_scores |
+| **Requirements** | `tools/requirements/` | Stakeholder needs decomposition | intake_sessions, requirements, requirement_gaps |
+| **Simulation** | `tools/simulation/` | Digital twin modeling | simulation_scenarios, monte_carlo_runs, coa_results |
+| **DevSecOps** | `tools/devsecops/` | Pipeline security & policy | devsecops_profiles, policies, zta_maturity_scores |
+| **Supply Chain** | `tools/supply_chain/` | Vendor & dependency management | vendors, dependency_graph, cve_triage_results |
+| **MBSE** | `tools/mbse/` | Model-based system engineering | model_elements, trace_links, digital_thread_coverage |
+| **Embedded** | `tools/embedded/`, `tools/fleet/`, `tools/edge_ai/` | Firmware & IoT lifecycle | devices, firmware_builds, ml_models |
+| **Observability** | `tools/observability/` | System behavior understanding | traces, provenance_entities, shap_attributions |
+| **GovCon** | `tools/govcon/` | Government contracting | sam_gov_opportunities, proposals, cpmp_contracts |
+| **CloudForge** | `tools/cloudforge/` | Infrastructure operations | cf_applications, runbooks, cf_landing_zones |
+| **Knowledge** | `tools/memory/`, `tools/rag/` | Organizational learning | memory_entries, knowledge_base, embeddings |
+
+### 4.2 Context Map — Relationships Between Bounded Contexts
+
+```
+┌─────────────┐    Conformist     ┌─────────────┐
+│  Security   │◄─────────────────►│ Compliance  │
+│             │  Security findings │             │
+│  (threats,  │  feed compliance   │  (controls, │
+│   vulns,    │  evidence.         │   evidence, │
+│   trust)    │  Compliance defines│   ATO)      │
+│             │  what Security     │             │
+└──────┬──────┘  must check.       └──────┬──────┘
+       │                                  │
+       │                                  │ Customer/Supplier
+       │                                  │
+       │         ┌─────────────┐          │
+       │         │Requirements │◄─────────┘
+       │         │             │  Requirements define
+       │         │  (intake,   │  what must be compliant.
+       │         │   gaps,     │  Compliance validates
+       │         │   SAFe)     │  against frameworks.
+       │         └──────┬──────┘
+       │                │
+       │                │ Customer/Supplier
+       │                │
+       │         ┌──────▼──────┐
+       │         │ Simulation  │
+       │         │             │  Requirements feed
+       │         │  (twin,     │  simulation scenarios.
+       │         │   Monte     │  Simulation validates
+       │         │   Carlo)    │  feasibility.
+       │         └─────────────┘
+       │
+       │         ┌─────────────┐    Partnership    ┌─────────────┐
+       │         │    MBSE     │◄──────────────────►│Requirements │
+       │         │             │  SysML models      │             │
+       │         │  (models,   │  generate reqs.    │             │
+       │         │   threads)  │  Reqs trace to     │             │
+       │         └─────────────┘  model elements.   └─────────────┘
+       │
+       │         ┌─────────────┐
+       └────────►│Supply Chain │  Anti-Corruption Layer
+                 │             │  to external vendor data.
+                 │  (vendors,  │  Normalizes heterogeneous
+                 │   deps,     │  SBOMs and CVE feeds into
+                 │   CVEs)     │  internal model.
+                 └─────────────┘
+
+┌─────────────┐    Anti-Corruption Layer    ┌─────────────┐
+│  Embedded   │◄───────────────────────────►│ Compliance  │
+│             │  Firmware compliance uses    │             │
+│  (devices,  │  different frameworks        │  (NIST,     │
+│   firmware, │  (IEC 62443, DO-178C) than  │   FedRAMP,  │
+│   edge AI)  │  IT compliance (NIST, etc.) │   CMMC)     │
+└─────────────┘                              └─────────────┘
+
+┌─────────────┐    Published Language (read-only bridge)
+│   GovCon    │◄──────────────────────────── Compliance
+│             │  GovCon reads compliance posture
+│  (proposals,│  via read-only bridge (D-WG-8).
+│   contracts)│  Never writes to compliance tables.
+└─────────────┘
+
+┌─────────────┐    Shared Kernel    ┌─────────────┐
+│ CloudForge  │◄───────────────────►│  DevSecOps  │
+│             │  Both share pipeline│             │
+│  (runbooks, │  and infrastructure │  (profiles, │
+│   apps)     │  concepts.          │   policies) │
+└─────────────┘                      └─────────────┘
+```
+
+### 4.3 Key Aggregates
+
+**Compliance Bounded Context:**
+
+```
+ComplianceControl (Aggregate Root)
+  ├── Evidence[]           — proof of implementation
+  ├── Assessment[]         — evaluation results per framework
+  ├── CrosswalkMapping[]   — auto-populated mappings to other frameworks
+  └── Exception[]          — SbD exception registry entries
+
+Invariants:
+  - A control cannot be "Implemented" without >= 1 non-expired evidence item
+  - Crosswalk mappings auto-populate on control status change (D-SBD-4)
+  - Expired exceptions block deployment (D-SBD-3)
+```
+
+**Requirements Bounded Context:**
+
+```
+IntakeSession (Aggregate Root)
+  ├── Requirement[]        — decomposed needs (epic -> feature -> story)
+  ├── Gap[]                — detected coverage gaps
+  ├── ReadinessScore       — 7-dimension scoring
+  └── BoundaryImpact       — ATO impact assessment (GREEN/YELLOW/ORANGE/RED)
+
+Invariants:
+  - Session cannot proceed past Stage 3 without readiness score >= 0.7
+  - RED boundary impacts require alternative COAs before proceeding
+```
+
+**Security Bounded Context:**
+
+```
+ThreatModel (Aggregate Root)
+  ├── Threat[]             — STRIDE analysis results
+  ├── Mitigation[]         — proposed/implemented mitigations
+  └── POAMEntry[]          — auto-generated POAM items
+
+Invariants:
+  - Every STRIDE threat must map to >= 1 NIST 800-53 control (D-INV-26)
+  - CAT1 STIG findings block deployment
+```
+
+**Simulation Bounded Context:**
+
+```
+Scenario (Aggregate Root)
+  ├── Dimension[]          — 6 simulation dimensions
+  ├── MonteCarloRun[]      — iteration results
+  └── COA[]                — generated courses of action
+
+Invariants:
+  - Monte Carlo requires >= 1000 iterations for statistical validity
+  - COAs must include risk assessment before comparison
+```
+
+### 4.4 Domain Events
+
+Formalize these domain events (many are already implicitly captured in the audit trail):
+
+| Event | Source Context | Consuming Contexts | Reaction |
+|---|---|---|---|
+| `ControlImplemented` | Compliance | Security, GovCon | Update threat posture; update proposal claims |
+| `ControlEvidenceExpired` | Compliance | cATO Engine, Dashboard | Flag for re-collection; alert ISSO |
+| `VulnerabilityDiscovered` | Security | Compliance, Supply Chain | Create POAM entry; flag vendor |
+| `ThreatModelCreated` | Security | Compliance, DevSecOps | Map threats to controls; update policies |
+| `RequirementDecomposed` | Requirements | MBSE, Simulation | Create trace links; seed scenarios |
+| `ATOBoundaryChanged` | Requirements | Compliance, DevSecOps | Re-assess all controls; regenerate policies |
+| `FirmwareDeployed` | Embedded | Compliance, Security | Regenerate SBOM; trigger security scan |
+| `TrustScoreDecayed` | Security | Orchestrator | Restrict agent permissions |
+| `SagaStepCompleted` | Orchestrator | Audit, Monitor | Log progress; check for anomalies |
+| `SagaCompensationTriggered` | Orchestrator | All affected agents | Execute rollback actions |
+| `PeerInteractionRecorded` | Any agent | Orchestrator, Audit | Verify authorized peer channel |
+
+**Implementation recommendation:** Create a lightweight event bus module at
+`tools/events/event_bus.py` using Python's built-in `queue.Queue` for in-process pub/sub.
+Events are simultaneously written to the audit trail (append-only, D6) and dispatched to
+registered subscribers. For multi-process deployment, replace with NATS or Redis Streams.
+
+### 4.5 Anti-Corruption Layers
+
+Three ACLs are critical:
+
+1. **External vendor data ACL** (`tools/supply_chain/`):
+   Vendor-provided SBOMs, CVE feeds, and dependency metadata arrive in heterogeneous
+   formats (CycloneDX, SPDX, custom JSON). The ACL normalizes into ICDEV's internal
+   `DependencyGraph` model. Already partially implemented via `dependency_graph.py`.
+
+2. **Embedded/IT compliance ACL** (`tools/compliance/` boundary):
+   Firmware frameworks (IEC 62443, DO-178C, ISO 26262) use fundamentally different
+   control structures than IT frameworks (NIST 800-53, FedRAMP). The crosswalk engine
+   partially serves this role but should be formalized as an explicit ACL with:
+   - Framework-specific adapters that translate to a common internal control model
+   - Mapping tables maintained in `args/` (GOTCHA separation)
+   - Validation rules preventing invalid cross-framework comparisons
+
+3. **Storage abstraction ACL** (`tools/db/storage.py`):
+   Already implemented as the storage abstraction layer (D-DB-20). Translates between
+   SQLite and PostgreSQL dialects transparently. The placeholder translation (? -> %s)
+   is a textbook ACL pattern.
+
+4. **External system integration ACL** (proposed `tools/integration/`):
+   Currently, DOORS NG ReqIF import, SAM.gov scanning, and Jira/GitLab integration
+   each handle their own data normalization. A common integration ACL would provide:
+   - Standard data ingestion pipeline (fetch -> validate -> normalize -> store)
+   - Error isolation (external system failures don't corrupt internal state)
+   - Rate limiting and retry logic per external system
+
+---
+
+## 5. Prioritized Recommendations
+
+Ordered by impact-to-effort ratio and alignment with ICDEV's architectural maturity:
+
+### Tier 1 — Quick Wins (1-2 days each)
+
+| # | Recommendation | Pattern | Effort | Impact |
+|---|---|---|---|---|
+| 1 | Adopt Structurizr DSL for C4 architecture-as-code | C4 | Low | High |
+| 2 | Add circuit breaker states to LLM router | Circuit Breaker | Low | Medium |
+| 3 | Implement compliance sidecar decorator | Sidecar | Low | Medium |
+| 4 | Map trust scores to CSA Agentic Trust Framework tiers | Agent Trust | Low | Medium |
+
+### Tier 2 — Medium Effort (3-5 days each)
+
+| # | Recommendation | Pattern | Effort | Impact |
+|---|---|---|---|---|
+| 5 | Formalize domain events with lightweight pub/sub bus | DDD Events | Medium | High |
+| 6 | Migrate Agent Cards to A2A spec | A2A Protocol | Medium | High |
+| 7 | Add ATLAS saga coordinator with compensating actions | Saga | Medium | Medium |
+| 8 | Enable selective peer-to-peer agent communication | Multi-Agent | Medium | Medium |
+| 9 | Introduce CQRS read model for compliance dashboards | CQRS | Medium | Medium |
+
+### Tier 3 — Strategic Investment (1-2 weeks each)
+
+| # | Recommendation | Pattern | Effort | Impact |
+|---|---|---|---|---|
+| 10 | Extend Plan-and-Execute to ATLAS workflows | Plan-Execute | High | High |
+| 11 | Consume own service mesh generation (self-hosting) | Service Mesh | High | Medium |
+| 12 | Add event replay and snapshot capabilities | Event Sourcing | High | Medium |
+| 13 | MCP server consolidation and resource exposure | MCP Patterns | Medium | Medium |
+| 14 | External system integration ACL standardization | DDD ACL | High | Medium |
+
+### Key Architecture Decisions (proposed)
+
+| Decision ID | Decision | Rationale |
+|---|---|---|
+| D-ARCH-1 | Structurizr DSL for architecture-as-code | Version-controlled, diff-able diagrams in PRs |
+| D-ARCH-2 | Circuit breaker with 3 states in LLM router | Faster recovery from Ollama restarts |
+| D-ARCH-3 | Compliance sidecar decorator for all tools | Centralize CUI marking, eliminate duplication |
+| D-ARCH-4 | Domain event bus (in-process Queue, NATS for K8s) | Enable reactive cross-context communication |
+| D-ARCH-5 | A2A spec-compliant Agent Cards | Industry interoperability, AAIF alignment |
+| D-ARCH-6 | ATLAS saga coordinator with compensation registry | Automated workflow recovery |
+| D-ARCH-7 | CSA ATF trust tiers (Intern/Junior/Senior/Principal) | Industry-standard agent trust model |
+| D-ARCH-8 | Selective peer-to-peer agent channels | Reduce orchestrator bottleneck |
+| D-ARCH-9 | CQRS read model via PostgreSQL mat. views | Dashboard performance under load |
+| D-ARCH-10 | Plan-Execute delegation to qwen3.5 for ATLAS steps | 50-60% additional token savings |
+
+---
+
+## 6. Sources
+
+### C4 Model
+- [C4 Model Official Site](https://c4model.com/)
+- [C4 Model — Microservices Guidance](https://c4model.com/abstractions/microservices)
+- [IcePanel: How to Create Common Architecture Diagrams with C4](https://icepanel.io/blog/2025-01-30-how-to-create-common-architecture-diagrams-with-the-c4-model)
+- [Structurizr DSL](https://structurizr.com/)
+- [InfoQ: The C4 Model for Software Architecture](https://www.infoq.com/articles/C4-architecture-model/)
+- [Revision: Practical C4 Modeling Tips](https://revision.app/blog/practical-c4-modeling-tips)
+
+### Microservices Patterns
+- [Microservices.io: Saga Pattern](https://microservices.io/patterns/data/saga.html)
+- [Microservices.io: Event Sourcing](https://microservices.io/patterns/data/event-sourcing.html)
+- [Microservices.io: CQRS](https://microservices.io/patterns/data/cqrs.html)
+- [DocuWriter: 7 Essential Microservices Architecture Patterns for 2025](https://www.docuwriter.ai/posts/microservices-architecture-patterns)
+- [Kiteworks: FedRAMP Audit Logging Best Practices](https://www.kiteworks.com/regulatory-compliance/fedramp-audit-log/)
+
+### Agentic AI Architecture
+- [Google Cloud: Choose a Design Pattern for Agentic AI](https://docs.google.com/architecture/choose-design-pattern-agentic-ai-system)
+- [Dextralabs: Top AI Agentic Workflow Patterns for Enterprises 2026](https://dextralabs.com/blog/ai-agentic-workflow-patterns-for-enterprises/)
+- [SpaceO: Agentic AI Frameworks Guide 2026](https://www.spaceo.ai/blog/agentic-ai-frameworks/)
+- [Microsoft Azure: Agent Factory Design Patterns](https://azure.microsoft.com/en-us/blog/agent-factory-the-new-era-of-agentic-ai-common-use-cases-and-design-patterns/)
+- [Sitepoint: Agentic Design Patterns 2026 Guide](https://www.sitepoint.com/the-definitive-guide-to-agentic-design-patterns-in-2026/)
+- [MachineLearningMastery: 7 Agentic AI Trends 2026](https://machinelearningmastery.com/7-agentic-ai-trends-to-watch-in-2026/)
+
+### A2A and MCP Protocols
+- [Google Developers: Announcing the A2A Protocol](https://developers.googleblog.com/en/a2a-a-new-era-of-agent-interoperability/)
+- [IBM: What Is Agent2Agent Protocol](https://www.ibm.com/think/topics/agent2agent-protocol)
+- [DEV Community: MCP vs A2A Complete Guide 2026](https://dev.to/pockit_tools/mcp-vs-a2a-the-complete-guide-to-ai-agent-protocols-in-2026-30li)
+- [Auth0: MCP vs A2A Guide](https://auth0.com/blog/mcp-vs-a2a/)
+- [Gravitee: Google A2A and Anthropic MCP](https://www.gravitee.io/blog/googles-agent-to-agent-a2a-and-anthropics-model-context-protocol-mcp)
+- [Koyeb: A2A and MCP Protocol Wars](https://www.koyeb.com/blog/a2a-and-mcp-start-of-the-ai-agent-protocol-wars)
+
+### Agent Trust and Zero Trust
+- [CSA: Agentic Trust Framework](https://cloudsecurityalliance.org/blog/2026/02/02/the-agentic-trust-framework-zero-trust-governance-for-ai-agents)
+- [Security Boulevard: Lattice-Based Zero Trust Identity for AI Agents](https://securityboulevard.com/2026/02/lattice-based-zero-trust-identity-verification-for-ai-agents/)
+- [Red Hat: Zero Trust for Autonomous Agentic AI](https://next.redhat.com/2026/02/26/zero-trust-for-autonomous-agentic-ai-systems-building-more-secure-foundations/)
+- [ISACA: Zero Trust in the Age of AI](https://www.isaca.org/resources/news-and-trends/isaca-now-blog/2025/zero-trust-in-the-age-of-ai-securing-cloud-environments-against-evolving-threats)
+
+### Domain-Driven Design
+- [Microsoft Learn: Domain Analysis for Microservices](https://learn.microsoft.com/en-us/azure/architecture/microservices/model/domain-analysis)
+- [Microsoft Learn: Tactical DDD for Microservices](https://learn.microsoft.com/en-us/azure/architecture/microservices/model/tactical-ddd)
+- [SayOneTech: Domain Driven Design for Microservices 2026](https://www.sayonetech.com/blog/domain-driven-design-microservices/)
+- [Martin Fowler: Bounded Context](https://martinfowler.com/bliki/BoundedContext.html)
+- [DZone: Strategic Domain-Driven Design](https://dzone.com/articles/strategic-domain-driven-design)