icdev 0.0.3__py3-none-any.whl

docs/research/secure-by-design-cloudyrion-adaptation.md

@@ -0,0 +1,270 @@
+# CUI // SP-CTI
+# Secure by Design (SbD) Research Report — Cloudyrion Adaptation for ICDEV
+## Innovation, Creative & Research Engine Output
+
+**Date:** 2026-03-06
+**Sources:** Cloudyrion SbD Insights, CISA SbD Pledge, NIST SP 800-218 SSDF
+**Classification:** CUI // SP-CTI
+**Impact Level:** IL4
+
+---
+
+## 1. Executive Summary
+
+This report synthesizes Secure by Design research from Cloudyrion's published insights with CISA's latest SbD Pledge requirements, maps them against ICDEV's current posture, and produces an actionable adaptation plan for ICDEV and all child applications.
+
+**Key Finding:** ICDEV already implements a **comprehensive SbD assessment framework** (35 requirements, 20 auto-checks, 14 domains) that covers all 7 CISA Pledge commitments. However, Cloudyrion's **8-Pillar SbD Framework** identifies higher-order organizational and architectural principles that extend beyond CISA's technical pledge — particularly in adaptive architecture, shared ownership, blast-radius containment, and customer-first security. These pillars reveal **5 enhancement opportunities** that would elevate ICDEV from SbD Level 3 (Defined) to Level 4 (Measured).
+
+---
+
+## 2. Source Analysis
+
+### 2.1 Cloudyrion's 8-Pillar SbD Framework
+
+Source: [Transform Security with Secure by Design](https://cloudyrion.com/en/insights/transform-security-with-secure-by-design/) and [Secure by Design 101](https://cloudyrion.com/en/insights/secure-by-design-101-turning-security-into-a-competitive-advantage/)
+
+| # | Pillar | Core Principle |
+|---|--------|---------------|
+| 1 | **Proactive, Secure Design** | Threat modeling at project kickoff; trust boundaries and sensitive data flows identified in architecture sketches; risky features eliminated when exposure exceeds value |
+| 2 | **Holistic Security Across Stack & Supply Chain** | Hardware, software, APIs, data, networks, and suppliers as integrated ecosystem; SBOM and dependency lifecycle policies |
+| 3 | **Shared Ownership Across Product, Engineering & Operations** | Designers create fraud-resistant flows; engineers ship secure defaults; operators maintain least-privilege; leadership incentivizes "shipping safely" |
+| 4 | **Adaptive Security Architecture** | Systems remain evolvable without major rewrites; new threats trigger rapid posture updates; decisions remain deliberately reversible |
+| 5 | **Assume Breach & Limit Blast Radius** | Each failure must be survivable; sensitive data isolation prevents total compromise; system observability creates detectable footprints |
+| 6 | **Risk-Driven Prioritization** | Security investments based on measurable risk reduction (impact x likelihood); some risks deliberately accepted; decisions link to outcomes and accountability |
+| 7 | **Customer-First Security & Privacy** | Default settings prioritize user safety, transparency, and recoverability; plain language security explanations; low-friction recovery |
+| 8 | **Continuous Security Improvement** | Security as a living system; incidents update organizational patterns; metrics show smaller blast radii; teams share lessons and raise standards |
+
+### 2.2 Cloudyrion's 6-Step Implementation Framework
+
+1. **Cultural Foundation** — Leadership buy-in; security as enabler, not bottleneck
+2. **Skills Development** — Secure coding, cryptography, zero-trust training
+3. **Workflow Integration** — Security checks in CI/CD before coding starts
+4. **Tooling Optimization** — Minimize false positives and alert fatigue
+5. **Governance Structure** — Clear policies, accountability, transparent decision-making
+6. **Continuous Monitoring** — Real-time threat detection, regular audits, adaptive strategies
+
+### 2.3 Cloudyrion's 4 Anti-Patterns to Avoid
+
+| Anti-Pattern | Description | ICDEV Risk |
+|-------------|-------------|-----------|
+| **Security Theater** | Running scans without structural fixes; alert fatigue | Low — ICDEV gates block on findings |
+| **Lone-Wolf Security** | Isolated security team policing engineering | Medium — compliance agent is separate domain agent |
+| **Lingering Exceptions** | Temporary access/endpoints persisting indefinitely | Medium — no exception aging/expiry tracking |
+| **One-and-Done Pentests** | Annual assessments creating false security sense | Low — continuous assessment in pipeline |
+
+### 2.4 CISA SbD Pledge — 7 Commitments (Latest 2025-2026)
+
+| # | Commitment | ICDEV Status |
+|---|-----------|-------------|
+| 1 | Multi-Factor Authentication | **Implemented** — SBD-01 auto-check |
+| 2 | Default Password Elimination | **Implemented** — SBD-02, SBD-28 scanning |
+| 3 | Vulnerability Class Reduction | **Implemented** — SBD-03, SBD-04 memory safety |
+| 4 | Security Patch Deployment | **Implemented** — SBD-05 Dependabot detection |
+| 5 | Vulnerability Disclosure Policy | **Gap** — SECURITY.md missing at repo root |
+| 6 | CVE Transparency | **Partial** — tracking framework exists, no CWE/CPE in CVE records |
+| 7 | Intrusion Evidence Collection | **Implemented** — SBD-08/09/10 audit logging |
+
+---
+
+## 3. ICDEV Current SbD Posture vs. Cloudyrion 8 Pillars
+
+### Mapping Matrix
+
+| Cloudyrion Pillar | ICDEV Implementation | Coverage | Gap Analysis |
+|-------------------|---------------------|----------|-------------|
+| **P1: Proactive Design** | Threat Modeler (F7), STRIDE analysis, ATLAS Architect phase | **Strong** | Threat modeling not mandatory at project init; no pre-design security review gate |
+| **P2: Holistic Stack/Supply Chain** | SBOM generator, supply chain graph, SCRM assessor, CVE triager, firmware SBOM | **Strong** | Supply chain covers software; hardware/API boundary coverage limited |
+| **P3: Shared Ownership** | 12-agent architecture distributes responsibility; compliance/security/builder agents | **Moderate** | No "security champion" role per team; no shared ownership metrics; compliance agent is separate, not embedded |
+| **P4: Adaptive Architecture** | Plugin architecture (MCP), modular tools, GOTCHA layers | **Strong** | No formal "reversible decision" tracking; no rapid posture update automation |
+| **P5: Assume Breach / Blast Radius** | ZTA 7-pillar scoring, mTLS, NetworkPolicy, service mesh, container isolation | **Strong** | No blast-radius simulation; no formal failure-survivability testing |
+| **P6: Risk-Driven Prioritization** | Readiness scoring (7 dimensions), Monte Carlo simulation, COA generator | **Strong** | Risk scoring is per-requirement, not per-security-investment; no ROI model |
+| **P7: Customer-First Security** | Golden Path scaffolder, progressive compliance (beginner/pro mode), secure defaults | **Moderate** | No plain-language security explanations in child app UIs; no recovery-flow design patterns |
+| **P8: Continuous Improvement** | Harness trace analyzer, knowledge self-heal, maturity assessor | **Strong** | No formal "lessons learned" pipeline from incidents to pattern updates; exception aging absent |
+
+### Composite Score
+
+| Dimension | Score (0-4) | Notes |
+|-----------|-------------|-------|
+| CISA 7 Commitments | **3.4** | 6/7 implemented, 1 gap (VDP file) |
+| Cloudyrion 8 Pillars | **2.8** | Strong technical, moderate organizational |
+| Child App Inheritance | **2.5** | Golden Path covers basics; SbD assessment not auto-inherited |
+| Overall SbD Maturity | **Level 3 (Defined)** | Path to Level 4 requires 5 enhancements |
+
+---
+
+## 4. Gap Analysis — 5 Enhancement Opportunities
+
+### Gap 1: Vulnerability Disclosure Policy (CISA Commitment 5)
+**Severity:** High — Blocks CISA pledge compliance
+**Current:** No `SECURITY.md` at repo root; SBD-06 auto-check will fail
+**Cloudyrion Alignment:** Pillar 7 (Customer-First) — "clear, jargon-free signals"
+**Recommendation:** Create `SECURITY.md` + `.well-known/security.txt` at repo root
+**Child App Impact:** Golden Path scaffolder should auto-generate both files
+
+### Gap 2: Exception Aging & Blast-Radius Tracking
+**Severity:** Medium — Cloudyrion anti-pattern "Lingering Exceptions"
+**Current:** No mechanism to track temporary security exceptions, their age, or expiry
+**Cloudyrion Alignment:** Pillar 5 (Assume Breach), Pillar 8 (Continuous Improvement)
+**Recommendation:** Add exception registry to SbD assessor — track creation date, expiry, owner, blast-radius estimate; gate on exceptions > 90 days without renewal
+**Child App Impact:** Exception registry should propagate to child app compliance profiles
+
+### Gap 3: SbD Auto-Inheritance for Child Apps
+**Severity:** Medium — Child apps don't automatically run SbD assessment
+**Current:** Golden Path provides CUI markings and basic security defaults but no SbD assessment integration
+**Cloudyrion Alignment:** Pillar 2 (Holistic) — security across entire ecosystem
+**Recommendation:** Add SbD assessment as mandatory step in child app scaffolding; include SbD gate configuration in Golden Path templates; auto-generate baseline SbD evidence
+**Child App Impact:** Every child app starts with SbD Level 2 minimum
+
+### Gap 4: Crosswalk Engine Integration
+**Severity:** Low — SbD assessment is standalone, doesn't benefit from multi-framework mapping
+**Current:** `control_crosswalk.json` has 15+ frameworks but not CISA SbD
+**Cloudyrion Alignment:** Pillar 6 (Risk-Driven) — unified risk view across frameworks
+**Recommendation:** Add `cisa_sbd` as framework key in crosswalk engine; map all 35 SBD requirements to existing NIST/FedRAMP/CMMC controls
+**Child App Impact:** Implementing one NIST control auto-satisfies corresponding SbD requirement
+
+### Gap 5: Shared Ownership Metrics & Security Champion Model
+**Severity:** Low — Organizational, not technical
+**Current:** Security is a separate domain agent; no per-team ownership model
+**Cloudyrion Alignment:** Pillar 3 (Shared Ownership), Anti-pattern "Lone-Wolf Security"
+**Recommendation:** Add "security_champion" field to project metadata; track per-team SbD scores in Developer Scorecard (F8); add SbD dimension to scorecard weighted composite
+**Child App Impact:** Each child app project declares a security champion
+
+---
+
+## 5. Adaptation Plan for ICDEV Modules & Child Apps
+
+### 5.1 Immediate Actions (This Sprint)
+
+| # | Action | Tool/File | Effort |
+|---|--------|-----------|--------|
+| 1 | Create `SECURITY.md` at repo root | New file | 30 min |
+| 2 | Create `.well-known/security.txt` | New file | 15 min |
+| 3 | Add SbD pillar tags to existing SBD requirements | `cisa_sbd_requirements.json` | 1 hr |
+| 4 | Update Golden Path templates to include `SECURITY.md` | `tools/scaffold/golden_path.py` | 1 hr |
+
+### 5.2 Near-Term Enhancements (Next 2 Sprints)
+
+| # | Action | Tool/File | Effort |
+|---|--------|-----------|--------|
+| 5 | Add CISA SbD to crosswalk engine | `context/compliance/control_crosswalk.json` | 2 hr |
+| 6 | Build exception registry in SbD assessor | `tools/compliance/sbd_assessor.py` | 4 hr |
+| 7 | Add SbD gate to Golden Path scaffold output | `tools/scaffold/golden_path.py` | 2 hr |
+| 8 | Add `sbd_score` dimension to Developer Scorecard | `tools/analytics/scorecard.py` | 3 hr |
+| 9 | Create `goals/secure_by_design.md` goal workflow | New file | 2 hr |
+
+### 5.3 Strategic Enhancements (Backlog)
+
+| # | Action | Rationale |
+|---|--------|-----------|
+| 10 | Blast-radius simulation via Digital Program Twin | Cloudyrion P5 — quantify containment |
+| 11 | Security champion metadata per project | Cloudyrion P3 — shared ownership |
+| 12 | Plain-language security explanations in child app UIs | Cloudyrion P7 — customer-first |
+| 13 | Reversible-decision registry for architecture choices | Cloudyrion P4 — adaptive architecture |
+| 14 | Incident-to-pattern pipeline in knowledge agent | Cloudyrion P8 — continuous improvement |
+
+### 5.4 Child App SbD Inheritance Model
+
+```
+┌─────────────────────────────────────────────────┐
+│                 ICDEV (Parent)                   │
+│  SbD Level 3 — 35 requirements, 20 auto-checks  │
+│  Crosswalk: NIST↔FedRAMP↔CMMC↔SbD             │
+└──────────────────────┬──────────────────────────┘
+                       │ Golden Path Scaffold
+                       ▼
+┌─────────────────────────────────────────────────┐
+│              Child App (Generated)               │
+│  Inherits:                                       │
+│  ├── SECURITY.md (VDP)                          │
+│  ├── .well-known/security.txt                    │
+│  ├── CUI markings (all files)                   │
+│  ├── SbD gate config (args/security_gates.yaml) │
+│  ├── SBOM generation hook (build pipeline)      │
+│  ├── Secret detection (pre-commit)              │
+│  ├── Audit trail (append-only)                  │
+│  └── SbD assessment baseline (SBD Level 2)      │
+│                                                  │
+│  Must Demonstrate:                               │
+│  ├── MFA enforcement (SBD-01)                   │
+│  ├── No default passwords (SBD-02)              │
+│  ├── Security headers (SBD-18)                  │
+│  ├── Input validation (SBD-16)                  │
+│  └── Logging baseline (SBD-08)                  │
+└─────────────────────────────────────────────────┘
+```
+
+---
+
+## 6. Cloudyrion SbD Metrics Adopted for ICDEV
+
+Per Cloudyrion's recommended KPIs, adapted for ICDEV's measurement framework:
+
+| Metric | Source | Target | Tracking Tool |
+|--------|--------|--------|--------------|
+| % services with least-privilege roles | ZTA maturity scorer | > 90% | `zta_maturity_scorer.py` |
+| Open temporary exceptions count | Exception registry (new) | < 5 active | `sbd_assessor.py` |
+| Exception age (p90) | Exception registry (new) | < 90 days | `sbd_assessor.py` |
+| Blast radius reduction (incident) | Harness trace analyzer | Decreasing trend | `trace_analyzer.py` |
+| Audit closure velocity | Compliance workflow | < 14 days | `cato_live_engine.py` |
+| Threat-to-posture-update time | Threat modeler + pipeline | < 48 hours | `threat_modeler.py` |
+| Release cadence consistency | VSM engine (DORA) | < 10% variance | `vsm_engine.py` |
+| SbD assessment score | SbD assessor | > 85% | `sbd_assessor.py` |
+| Child app SbD inheritance rate | Golden Path | 100% | `golden_path.py` |
+
+---
+
+## 7. Competitive Advantage Framing
+
+Per Cloudyrion's "SbD as competitive advantage" thesis, ICDEV can position its SbD capabilities as differentiators:
+
+| Advantage | ICDEV Capability | Market Signal |
+|-----------|-----------------|---------------|
+| **Prevention over remediation** | 35-requirement automated SbD assessment catches issues before deployment | "Zero SbD-class findings in production" |
+| **Compliance streamlining** | Crosswalk engine satisfies SbD + FedRAMP + CMMC from single control implementation | "One control implementation = 4 framework checks" |
+| **Faster ATO** | ATO Simulator (F11) with SbD gates predicts timeline reduction | "SbD compliance reduces ATO timeline by X days" |
+| **Supply chain integrity** | SBOM + VEX + SCRM + CVE triage pipeline | "Full software supply chain transparency" |
+| **Child app security** | Golden Path auto-inherits SbD baseline | "Every generated app is Secure by Design from day one" |
+
+---
+
+## 8. Framework Alignment Summary
+
+| Framework | Alignment to Cloudyrion 8 Pillars | Notes |
+|-----------|----------------------------------|-------|
+| CISA SbD Pledge | P1, P2, P5, P7 | Technical commitments only; Cloudyrion adds organizational pillars |
+| NIST 800-53 Rev 5 | P1 (SA-11, SA-15), P2 (SA-12), P5 (SC-7, SI-4), P7 (AC-2) | Strong per-control mapping via crosswalk |
+| NIST 800-218 SSDF | P1 (PW), P2 (PS), P8 (RV) | Secure Software Development Framework |
+| FedRAMP | P2 (supply chain), P5 (incident response), P6 (risk assessment) | Continuous monitoring = P8 |
+| CMMC L2/L3 | P1 (SI), P2 (SC), P3 (AT), P5 (IR), P7 (AC) | Practice-level mapping |
+| DoD ZTA (800-207) | P4 (adaptive), P5 (assume breach), P6 (risk-driven) | 7-pillar overlap with Cloudyrion P4/P5/P6 |
+| MITRE ATLAS | P5 (AI adversarial), P8 (continuous) | AI-specific SbD |
+| OWASP LLM Top 10 | P1 (proactive), P2 (holistic), P7 (customer-first) | Agentic security = shared ownership |
+
+---
+
+## 9. Conclusion
+
+ICDEV's existing SbD posture is **strong technically** — 35 requirements, 20 automated checks, full CISA pledge coverage (minus VDP file), and integrated security gates. Cloudyrion's 8-Pillar framework reveals that **organizational and architectural principles** (shared ownership, adaptive architecture, blast-radius quantification, exception lifecycle management) are the primary growth areas.
+
+The 5 identified enhancements would:
+1. Close the sole CISA pledge gap (VDP)
+2. Prevent the "lingering exceptions" anti-pattern
+3. Ensure every child app inherits SbD compliance from birth
+4. Enable multi-framework mapping through crosswalk integration
+5. Distribute security ownership across teams
+
+**Estimated effort:** ~15 hours for near-term enhancements; strategic items are backlog-appropriate.
+
+---
+
+## Sources
+
+- [Cloudyrion: Transform Security with Secure by Design](https://cloudyrion.com/en/insights/transform-security-with-secure-by-design/)
+- [Cloudyrion: Secure by Design 101 — Turning Security into a Competitive Advantage](https://cloudyrion.com/en/insights/secure-by-design-101-turning-security-into-a-competitive-advantage/)
+- [CISA Secure by Design Pledge](https://www.cisa.gov/securebydesign/pledge)
+- [CISA Secure by Design](https://www.cisa.gov/securebydesign)
+- [CISA Secure by Design Pledge (Resources)](https://www.cisa.gov/resources-tools/resources/cisa-secure-design-pledge)
+
+////////////////////////////////////////////////////////////////////
+CUI // SP-CTI | Department of Defense
+////////////////////////////////////////////////////////////////////

goals/agent_management.md

@@ -0,0 +1,144 @@
+# Goal: Agent Management
+
+## Purpose
+Manage the 8-agent multi-tier architecture: registration, health monitoring, task routing, A2A communication, and lifecycle management. Ensures all agents are operational and properly communicating via the A2A protocol.
+
+## Trigger
+- System startup (agent registration)
+- `/icdev-status` skill invoked (agent health section)
+- Agent heartbeat failure detected
+- Task routing required by Orchestrator
+
+## Inputs
+- Agent configuration (`args/agent_config.yaml`)
+- Agent cards (`tools/a2a/agent_cards/*.json`)
+- A2A task model (`tools/a2a/task.py`)
+- Agent registry state (`agents` table in icdev.db)
+
+## Architecture
+
+### Agent Tiers
+| Tier | Agent | Port | Responsibilities |
+|------|-------|------|-----------------|
+| Core | Orchestrator | 8443 | Task routing, workflow coordination |
+| Core | Architect | 8444 | ATLAS A/T phases, system design |
+| Domain | Builder | 8445 | TDD code generation, testing, linting |
+| Domain | Compliance | 8446 | ATO artifacts, STIG, SBOM, CUI |
+| Domain | Security | 8447 | SAST, dependency audit, secret detection |
+| Domain | Infrastructure | 8448 | Terraform, Ansible, K8s, CI/CD |
+| Support | Knowledge | 8449 | Pattern detection, self-healing, recommendations |
+| Support | Monitor | 8450 | Log analysis, metrics, alerts, health checks |
+
+### Communication Protocol
+- **A2A (Agent-to-Agent):** JSON-RPC 2.0 over HTTPS with mutual TLS
+- **Agent Cards:** Published at `/.well-known/agent.json` per A2A spec
+- **Task Lifecycle:** submitted → working → input-required → completed/failed
+- **Within K8s:** Service mesh handles mTLS certificates
+
+## Process
+
+### Step 1: Agent Registration
+**Tool:** `tools/a2a/agent_registry.py`
+- Each agent registers on startup with:
+  - Agent ID, name, version
+  - Capabilities (skills list from agent card)
+  - Endpoint URL
+  - Health check URL
+- Stored in `agents` table
+
+### Step 2: Health Monitoring
+**Tool:** `tools/a2a/agent_registry.py` → `check_health()`
+- Periodic heartbeat checks (every 30 seconds)
+- HTTP GET to each agent's health endpoint
+- Track response time and availability
+- Update `agents` table with last_heartbeat timestamp
+- After 3 consecutive failures: mark agent as `offline`
+
+### Step 3: Agent Discovery
+**Tool:** `tools/a2a/agent_client.py` → `discover()`
+- Fetch agent card from `/.well-known/agent.json`
+- Parse capabilities, accepted input modes, output modes
+- Cache agent cards for routing decisions
+
+### Step 4: Task Routing
+**Tool:** `tools/a2a/agent_client.py` → `send_task()`
+- Orchestrator receives high-level task
+- Analyze task to determine required agent(s)
+- Route to appropriate agent via A2A protocol:
+  ```json
+  {
+    "jsonrpc": "2.0",
+    "method": "tasks/send",
+    "params": {
+      "id": "<uuid>",
+      "message": {
+        "role": "user",
+        "parts": [{"type": "text", "text": "<task description>"}]
+      }
+    }
+  }
+  ```
+- Track task in `a2a_tasks` table
+
+### Step 5: Task Lifecycle Management
+Track task state transitions:
+1. `submitted` — Task received by target agent
+2. `working` — Agent actively processing
+3. `input-required` — Agent needs additional input
+4. `completed` — Task finished successfully (with artifacts)
+5. `failed` — Task failed (with error details)
+
+Record all transitions in `a2a_task_history` table.
+
+### Step 6: Multi-Agent Workflows
+Complex tasks involve multiple agents:
+1. Orchestrator breaks down high-level task
+2. Routes subtasks to domain agents in dependency order
+3. Passes artifacts between agents (via `a2a_task_artifacts` table)
+4. Aggregates results
+5. Reports completion to user
+
+Example workflow for `/icdev-init`:
+```
+Orchestrator → Architect (design)
+            → Builder (scaffold)
+            → Compliance (baseline controls)
+            → Security (initial scan)
+```
+
+### Step 7: Error Handling
+- **Agent offline:** Route to backup or queue for retry
+- **Task timeout:** Cancel after configurable timeout, retry once
+- **Task failure:** Record failure, attempt alternative approach
+- **Cascading failure:** Circuit breaker pattern (fail fast after 5 failures in 1 minute)
+
+### Step 8: Audit Trail
+**Tool:** `tools/audit/audit_logger.py`
+- Record: agent registration, health state changes, task routing decisions
+- **NIST Controls:** AC-2 (Account Management), AU-12 (Audit Record Generation)
+
+## Outputs
+- Agent registry (all 8 agents with health status)
+- Task routing logs
+- Agent health dashboard data
+- A2A task history with artifacts
+
+## K8s Deployment
+Each agent runs as a separate Kubernetes Deployment:
+- Resource limits: 256Mi-512Mi memory, 250m-500m CPU
+- Liveness and readiness probes on health endpoint
+- NetworkPolicy restricts inter-agent communication
+- Service mesh provides mTLS
+- HPA for auto-scaling based on task queue depth
+
+## Edge Cases
+- Agent startup order: Orchestrator must start first, others can start in any order
+- Network partition: agents continue independently, reconcile when reconnected
+- Version mismatch: agent cards include version, routing considers compatibility
+- Resource exhaustion: throttle task submission when agent is overloaded
+- Agent restart: re-register on startup, resume in-progress tasks from last checkpoint
+
+## Related Goals
+- `self_healing.md` — Agent self-healing on failure
+- `monitoring.md` — Agent metric collection
+- `dashboard.md` — Agent health display

goals/ai_accountability.md

@@ -0,0 +1,90 @@
+# CUI // SP-CTI
+# Goal: AI Accountability (Phase 49)
+
+## Overview
+Implement the accountability half of AI Transparency & Accountability.
+Phase 48 delivered transparency (model cards, system cards, AI inventory, confabulation detection, fairness assessment, 4 framework assessors). Phase 49 delivers accountability (human oversight, appeals, CAIO designation, incident response, ethics reviews, reassessment scheduling).
+
+## When to Use
+- After Phase 48 AI Transparency is complete
+- When a project uses AI components that require accountability evidence
+- When `data_classifications` includes AI data category
+- When assessors report accountability gaps (M25-OVR-*, M26-REV-*, GAO-MON-*, FAIR-6/7)
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/compliance/accountability_manager.py` | Central coordinator: oversight plans, CAIO, appeals, ethics reviews, reassessments |
+| `tools/compliance/ai_impact_assessor.py` | Algorithmic impact assessment (M26-IMP-1) |
+| `tools/compliance/ai_incident_response.py` | AI-specific incident tracking (M25-RISK-4, GAO-MON-3) |
+| `tools/compliance/ai_reassessment_scheduler.py` | Periodic reassessment tracking (M25-INV-3, GAO-MON-4) |
+| `tools/compliance/ai_accountability_audit.py` | Cross-framework accountability audit (all 4 frameworks) |
+
+## Workflow
+
+1. **Register Oversight Plan** — Create human oversight plan for AI system
+2. **Designate CAIO** — Assign Chief AI Officer / responsible official
+3. **Submit Ethics Review** — Document ethics framework, legal compliance, opt-out policy
+4. **Run Impact Assessment** — Evaluate algorithmic impact on affected populations
+5. **Schedule Reassessments** — Set periodic review cadence
+6. **Run Accountability Audit** — Cross-framework gap analysis
+7. **Address Gaps** — File appeals, log incidents, remediate as needed
+
+## Database Tables (6 new)
+
+| Table | Purpose | Mutability |
+|-------|---------|------------|
+| `ai_oversight_plans` | Human oversight plans | Append-only (D6) |
+| `ai_accountability_appeals` | Appeal tracking | Append-only (D6) |
+| `ai_caio_registry` | CAIO/responsible official | UPDATE allowed |
+| `ai_incident_log` | AI-specific incidents | Append-only (D6) |
+| `ai_reassessment_schedule` | Reassessment cadence | UPDATE allowed |
+| `ai_ethics_reviews` | Ethics reviews with boolean flags | Append-only (D6) |
+
+## Assessor Fixes (14 checks across 4 assessors)
+
+### OMB M-25-21 (6 fixes)
+- M25-OVR-1: Human oversight plan → `ai_oversight_plans`
+- M25-OVR-3: Appeal process → `ai_accountability_appeals`
+- M25-OVR-4: CAIO designation → `ai_caio_registry`
+- M25-INV-2: Responsible official → `ai_use_case_inventory.responsible_official IS NOT NULL`
+- M25-INV-3: Reassessment schedule → `ai_reassessment_schedule`
+- M25-RISK-4: Incident response → `ai_incident_log`
+
+### OMB M-26-04 (3 fixes)
+- M26-REV-2: Appeal process → `ai_accountability_appeals`
+- M26-REV-3: Opt-out policy → `ai_ethics_reviews.opt_out_policy = 1`
+- M26-IMP-1: Impact assessment → `ai_ethics_reviews.review_type = 'impact_assessment'`
+
+### GAO-21-519SP (5 fixes)
+- GAO-MON-2: Feedback collection → `audit_trail.event_type LIKE '%feedback%'`
+- GAO-MON-3: Incident detection → `ai_incident_log`
+- GAO-MON-4: Reassessment schedule → `ai_reassessment_schedule`
+- GAO-GOV-2: Legal compliance → `ai_ethics_reviews.legal_compliance_matrix = 1`
+- GAO-GOV-3: Ethics framework → `ai_ethics_reviews` (any record)
+
+### Fairness (4 fixes + gate)
+- FAIR-1: Bias testing policy → `ai_ethics_reviews.review_type = 'bias_testing_policy'`
+- FAIR-3: Disparity analysis → `ai_ethics_reviews.pre_deployment_review = 1`
+- FAIR-6: Human review → `ai_oversight_plans`
+- FAIR-7: Appeal process → `ai_accountability_appeals`
+- Gate threshold: 50% → 25% (D321)
+
+## Security Gate: `ai_accountability`
+- **Blocking:** CAIO not designated for high-impact, oversight plan missing, critical incident unresolved, reassessment overdue >90 days
+- **Warning:** Appeal process not defined, ethics review not conducted, impact assessment missing, fairness gate not passing
+
+## Architecture Decisions
+- D316: Accountability tables append-only except CAIO/reassessment (officials change, schedules shift)
+- D317: Single coordinator tool (accountability_manager.py) consolidates 7 functions
+- D318: AI incident log separate from audit_trail (AI-specific corrective action events)
+- D319: Boolean flags (opt_out_policy, legal_compliance_matrix, pre_deployment_review) for fast assessor checks
+- D320: Impact assessment stored in ai_ethics_reviews with review_type='impact_assessment'
+- D321: Fairness gate lowered to 25% — achievable with DB-only checks (no project_dir required)
+
+## Edge Cases
+- Project with no AI components: accountability tools return empty results gracefully
+- Multiple CAIO designations: latest entry takes precedence (query ORDER BY created_at DESC LIMIT 1)
+- Overdue reassessments: `check_overdue()` returns items where `next_due < now`
+- Appeal resolution: requires `resolved_by` field — accountability chain is tracked

goals/ai_narratives.md

@@ -0,0 +1,79 @@
+# CUI // SP-CTI
+
+# F4: AI-Generated Compliance Narratives
+
+## Purpose
+
+Generate human-quality compliance control narratives from structured evidence. Supports deterministic template-based generation (air-gap safe) with optional LLM enhancement for natural language polish. Includes review/approval workflow for compliance officer sign-off.
+
+## Prerequisites
+
+- `data/icdev.db` initialized with compliance controls and evidence
+- Control mappings populated via `tools/compliance/control_mapper.py`
+- For LLM-enhanced mode: LLM router configured in `args/llm_config.yaml`
+
+## Workflow Steps
+
+### 1. Generate Narrative
+```bash
+python tools/compliance/narrative_workflow.py --generate --project-id "sparkpilot" --control-id "AC-2" --mode deterministic --json
+```
+**Expected output:** JSON with narrative ID, control ID, generated text, mode (deterministic/llm), word count, and status (draft).
+
+### 2. Submit for Review
+```bash
+python tools/compliance/narrative_workflow.py --submit-review --narrative-id "nar-001" --reviewer "isso@example.com" --json
+```
+**Expected output:** JSON with review ID, narrative ID, reviewer, submission timestamp, and status (pending_review).
+
+### 3. Approve or Reject
+```bash
+python tools/compliance/narrative_workflow.py --approve --narrative-id "nar-001" --reviewer "isso@example.com" --json
+python tools/compliance/narrative_workflow.py --reject --narrative-id "nar-001" --reviewer "isso@example.com" --comment "Needs more detail on monitoring" --json
+```
+**Expected output:** JSON with updated status (approved/rejected), reviewer, timestamp, and comment if rejected.
+
+### 4. Batch Generate
+```bash
+python tools/compliance/narrative_workflow.py --batch --project-id "sparkpilot" --control-family AC --mode deterministic --json
+```
+**Expected output:** JSON with batch ID, count of narratives generated, success/failure counts, and per-control status.
+
+### 5. Export Narratives
+```bash
+python tools/compliance/narrative_workflow.py --export --project-id "sparkpilot" --status approved --format markdown --json
+```
+**Expected output:** JSON with export path, narrative count, and CUI markings applied.
+
+## Decision Reference
+
+| Decision | Description |
+|----------|-------------|
+| D-INV-13 | Deterministic mode uses Jinja2 templates populated from evidence tables -- air-gap safe |
+| D-INV-14 | LLM mode sends template output + evidence to worker tier for natural language polish |
+| D-INV-15 | Review workflow is 3-state: draft -> pending_review -> approved/rejected |
+| D-INV-16 | Narratives are versioned -- rejection creates new draft version, preserves history |
+
+## Edge Cases
+
+- Control with no evidence generates narrative stub with "[EVIDENCE NEEDED]" placeholders
+- LLM unavailable falls back to deterministic mode silently
+- Batch generation skips controls with approved narratives (use `--force` to regenerate)
+- Rejected narrative preserves reviewer comment for next iteration
+
+## Tier Gating
+
+| Capability | Community | Pro |
+|------------|-----------|-----|
+| Deterministic generation | Yes | Yes |
+| LLM-enhanced generation | No | Yes |
+| Review/approval workflow | Yes | Yes |
+| Batch generation | 10 controls max | Unlimited |
+| Export with CUI markings | Yes | Yes |
+
+## Security
+
+- All narratives and reviews are append-only (NIST AU compliant)
+- Reviewer identity logged for accountability
+- CUI markings applied at generation time
+- LLM inputs/outputs hashed in AI telemetry (D-216)

goals/ai_transparency.md

@@ -0,0 +1,76 @@
+# CUI // SP-CTI
+# Goal: AI Transparency & Accountability (Phase 48)
+
+## Purpose
+Bridge the vocabulary gap between SPARKPILOT's technical AI capabilities (XAI, SHAP, telemetry)
+and government stakeholder terminology (model cards, High-Impact AI, bias testing, GAO audit
+readiness). Implements 4 new compliance frameworks and 8 supporting tools.
+
+## Trigger
+- User runs `/sparkpilot-transparency`
+- AI data category detected in project (auto-triggers via D314)
+- Manual: any Phase 48 tool invoked via CLI or MCP
+
+## Frameworks
+| Framework | Source | Requirements | Assessor |
+|-----------|--------|-------------|----------|
+| OMB M-25-21 | Nov 2025 | 15 (AI inventory, high-impact classification, risk management, oversight) | `omb_m25_21_assessor.py` |
+| OMB M-26-04 | Jan 2026 | 16 (model cards, bias testing, fairness, human review, impact assessment) | `omb_m26_04_assessor.py` |
+| NIST AI 600-1 | Jul 2024 | 18 (12 GAI risk categories: confabulation, privacy, integrity, CBRN, etc.) | `nist_ai_600_1_assessor.py` |
+| GAO-21-519SP | Jun 2021 | 16 (4 principles: governance, data, performance, monitoring) | `gao_ai_assessor.py` |
+
+## Tools
+| Tool | File | Purpose |
+|------|------|---------|
+| AI Inventory Manager | `tools/compliance/ai_inventory_manager.py` | OMB M-25-21 public AI use case inventory |
+| Model Card Generator | `tools/compliance/model_card_generator.py` | OMB M-26-04 / Google Model Cards format |
+| System Card Generator | `tools/compliance/system_card_generator.py` | System-level AI documentation |
+| Confabulation Detector | `tools/security/confabulation_detector.py` | NIST AI 600-1 GAI.1 hallucination detection |
+| Fairness Assessor | `tools/compliance/fairness_assessor.py` | OMB M-26-04 bias/fairness compliance evidence |
+| GAO Evidence Builder | `tools/compliance/gao_evidence_builder.py` | GAO-21-519SP audit evidence compilation |
+| AI Transparency Audit | `tools/compliance/ai_transparency_audit.py` | Cross-framework unified transparency report |
+
+## Workflow
+1. Check AI inventory for registered components
+2. Generate model cards for each AI model
+3. Generate system card for the project
+4. Run all 4 framework assessors
+5. Check confabulation detection status
+6. Run fairness assessment
+7. Build GAO evidence package
+8. Run cross-framework transparency audit
+9. Report gaps with remediation commands
+
+## Gates
+- **Blocking**: high_impact_ai_not_classified, model_cards_missing, ai_inventory_incomplete, gao_evidence_gaps, confabulation_detection_not_active
+- **Warning**: system_card_stale, fairness_assessment_not_conducted, bias_mitigation_not_documented, appeal_process_not_defined
+
+## Database Tables (9 new)
+- `omb_m25_21_assessments` — BaseAssessor standard schema
+- `omb_m26_04_assessments` — BaseAssessor standard schema
+- `nist_ai_600_1_assessments` — BaseAssessor standard schema
+- `gao_ai_assessments` — BaseAssessor standard schema
+- `model_cards` — id, project_id, model_name, card_data, card_hash, version, created_at
+- `system_cards` — id, project_id, card_data, card_hash, version, created_at
+- `confabulation_checks` — id, project_id, check_type, input_hash, result, risk_score, findings_count, created_at
+- `ai_use_case_inventory` — id, project_id, name, purpose, risk_level, classification, deployment_status, etc.
+- `fairness_assessments` — id, project_id, assessment_data, overall_score, created_at
+
+## Architecture Decisions
+- **D307**: BaseAssessor ABC pattern (D116) — ~150-200 LOC each, automatic gate/CLI/crosswalk
+- **D308**: Google Model Cards format — open standard, Gov AI community
+- **D309**: System cards are SPARKPILOT-specific — broader than model cards
+- **D310**: Confabulation detector — deterministic methods only, air-gap safe
+- **D311**: Fairness assessor — compliance documentation evidence, not statistical bias testing
+- **D312**: AI inventory — OMB M-25-21 schema for government reporting
+- **D313**: GAO evidence builder — reuses existing SPARKPILOT data, no new collection
+- **D314**: AI data category trigger — auto-activates all 4 frameworks
+- **D315**: COSAiS overlay — deferred until NIST publishes final spec (late 2026)
+
+## Success Criteria
+- All 4 assessors produce valid JSON output with --json flag
+- Crosswalk engine returns Phase 48 frameworks for mapped NIST controls
+- Gate evaluation works (--gate flag)
+- Dashboard /ai-transparency page renders with stat grid and tables
+- AI data category trigger auto-activates frameworks when AI components detected
+- 120+ tests pass across 6 test files