icdev 1.0.0__py3-none-any.whl

icdev/data/docs/features/phase-55-a2a-v03-mcp-oauth.md

@@ -0,0 +1,322 @@
+# Phase 55 — A2A v0.3 Protocol + MCP OAuth 2.1
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 55 |
+| Title | A2A v0.3 Protocol + MCP OAuth 2.1 |
+| Status | Implemented |
+| Priority | P2 |
+| Dependencies | Phase 11 (Multi-Agent Architecture), Phase 21 (SaaS Multi-Tenancy), Phase 46 (Observability & XAI), Phase 47 (Unified MCP Gateway) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-25 |
+
+---
+
+## 1. Problem Statement
+
+ICDEV's 15-agent multi-agent architecture communicates via the A2A protocol (JSON-RPC 2.0 over mutual TLS). The prior implementation used a minimal Agent Card format that lacked structured capability advertisement, task subscription streaming, and version negotiation. When a new agent joined the cluster or an existing agent gained new skills, the Orchestrator had no standardized way to discover what capabilities were available without hardcoded routing tables. There was no streaming subscription model for long-running inter-agent tasks.
+
+Separately, MCP Streamable HTTP transport (Phase 21) relied solely on API key authentication. Connected environments need OAuth 2.1 support for external identity providers, while air-gapped IL5/IL6 environments need offline token verification without calling an external authorization server. Additionally, MCP tools had no mechanism to request user input mid-execution (elicitation) or to track long-running tool invocations as first-class lifecycle objects (tasks).
+
+Without these capabilities, ICDEV cannot:
+- Dynamically discover agent capabilities at runtime
+- Subscribe to task completion events across agents
+- Negotiate protocol versions for backward compatibility
+- Authenticate MCP clients via OAuth 2.1 in connected environments
+- Verify tokens offline in air-gapped deployments
+- Pause tool execution to request user clarification
+- Track long-running MCP tool invocations with progress updates
+
+Phase 55 closes these gaps with A2A v0.3 protocol compliance, an agent discovery server, and MCP OAuth 2.1 with elicitation and task lifecycle support.
+
+---
+
+## 2. Goals
+
+1. Upgrade all 15 Agent Cards to A2A v0.3 format with structured `capabilities`, `skills`, and `tasks/sendSubscribe` metadata
+2. Add backward-compatible `protocolVersion` field for version negotiation between v0.2 and v0.3 agents
+3. Provide a centralized discovery server for agent registration, skill-based lookup, and capability-based filtering
+4. Implement OAuth 2.1 token verification for MCP Streamable HTTP transport with 3 verification modes (JWT, API key, HMAC)
+5. Generate offline HMAC-signed tokens for air-gapped environments without requiring an external authorization server
+6. Support MCP Elicitation — allow tools to pause and request user input mid-execution
+7. Support MCP Tasks — wrap long-running tool invocations with create/progress/complete lifecycle tracking
+8. Register new tools in the unified MCP gateway for A2A discovery and MCP OAuth operations
+
+---
+
+## 3. Architecture
+
+```
+                   A2A v0.3 + MCP OAuth Architecture
+     ┌───────────────────────────────────────────────────────┐
+     │                  agent_config.yaml                     │
+     │    (15 agents, ports, TLS certs, capabilities)         │
+     └──────────────────────┬────────────────────────────────┘
+                            │
+          ┌─────────────────┼─────────────────────┐
+          ↓                 ↓                      ↓
+   Agent Card Gen     Discovery Server       MCP OAuth 2.1
+   (a2a_agent_card_   (a2a_discovery_        (mcp_oauth.py)
+    generator.py)      server.py)
+          │                 │                      │
+          ↓                 ↓                      ↓
+   v0.3 Agent Cards   Skill/Capability       3-Mode Verifier
+   (per-agent JSON)    Routing + Health       (JWT/APIKey/HMAC)
+          │                 │                      │
+          │                 ↓                      │
+          │          agent_registry            ┌───┴───┐
+          │          (health, status)          ↓       ↓
+          │                                Elicitation Tasks
+          │                                Handler    Manager
+          │                                   │       │
+          └───────────────────────────────────┘       │
+                            │                          │
+                            ↓                          ↓
+                   Unified MCP Gateway           Long-Running
+                   (tool_registry.py)            Tool Lifecycle
+                   + A2A Discovery Tools         (create/progress/
+                   + MCP OAuth Tools              complete/fail)
+```
+
+### Key Design Principles
+
+- **Backward compatible** — v0.3 Agent Cards include `protocolVersion` field; v0.2 clients ignore new fields (D344)
+- **Reuse existing auth** — MCP OAuth reuses SaaS auth middleware patterns, not a new auth stack (D345)
+- **Air-gap safe** — HMAC offline tokens use stdlib `hmac` + `hashlib`, zero external dependencies (D345)
+- **Non-blocking elicitation** — Tools create elicitation requests and yield; user responds asynchronously (D346)
+- **Task lifecycle** — Long-running tools get create/progress/complete/fail states with percentage tracking (D346)
+
+---
+
+## 4. Components
+
+### Component 1: A2A v0.3 Agent Card Generator (`tools/agent/a2a_agent_card_generator.py`)
+
+Generates v0.3-compliant Agent Cards from `args/agent_config.yaml` for all 15 ICDEV agents.
+
+**Agent Card v0.3 Schema:**
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | string | Agent identifier (e.g., `orchestrator-agent`) |
+| `description` | string | Agent role description |
+| `url` | string | Agent endpoint URL (mTLS) |
+| `version` | string | Agent version (semver) |
+| `protocolVersion` | string | A2A protocol version (`0.3`) |
+| `contextId` | string | Context preservation identifier |
+| `capabilities` | object | Structured capability flags |
+| `authentication` | object | Supported auth schemes (`mutual_tls`, `api_key`) |
+| `skills` | array | Skill definitions with input/output modes |
+| `tasks` | object | Task subscription endpoints (`sendSubscribe`) |
+| `metadata` | object | Tier, classification, ICDEV version |
+
+**Default Capabilities (all agents):**
+| Capability | Default | Description |
+|------------|---------|-------------|
+| `streaming` | false | Real-time response streaming |
+| `pushNotifications` | false | Push notification support |
+| `taskSubscription` | true | Subscribe to task completion events |
+| `contextPreservation` | true | Preserve context across invocations |
+| `asyncNotifications` | true | Asynchronous notification support |
+| `stateTransitionHistory` | true | Task state transition history |
+
+**Skill Definitions:** 15 agents with 30+ total skills mapped from `AGENT_SKILLS` registry, covering task dispatch, system design, TDD code generation, compliance (SSP/POAM/SBOM), security scanning, infrastructure, knowledge, monitoring, MBSE, modernization, requirements intake, supply chain, simulation, ZTA, and remote gateway operations.
+
+### Component 2: A2A v0.3 Discovery Server (`tools/agent/a2a_discovery_server.py`)
+
+Centralized agent discovery with health-aware routing and capability-based filtering.
+
+**Discovery Operations:**
+| Operation | Method | Description |
+|-----------|--------|-------------|
+| `discover_agents()` | List all | Returns all agents with cards and health status from `agent_registry` |
+| `find_agent_for_skill(skill_id)` | Skill lookup | Find agents providing a specific skill (e.g., `ssp_generate`) |
+| `find_agents_by_capability(cap)` | Capability filter | Find agents with a specific capability (e.g., `taskSubscription`) |
+| `get_discovery_summary()` | Summary | Aggregate stats: tier distribution, health counts, skill totals, capability coverage |
+
+**Health Integration:** Discovery server joins Agent Card data with live health status from the `agent_registry` table, providing real-time health-aware routing (healthy/unhealthy/unknown).
+
+**Tier Distribution:** Agents classified as core (Orchestrator, Architect), domain (Builder, Compliance, Security, Infrastructure, MBSE, Modernization, Requirements Analyst, Supply Chain, Simulation, DevSecOps/ZTA, Gateway), and support (Knowledge, Monitor).
+
+### Component 3: MCP OAuth 2.1 Verifier (`tools/saas/mcp_oauth.py`)
+
+Three-mode token verification for MCP Streamable HTTP transport.
+
+**Verification Chain (priority order):**
+1. **API Key** (`icdev_*` prefix) — SHA-256 hash lookup against `platform.db` API keys table. Most common in ICDEV deployments.
+2. **Offline HMAC** (`hmac_*` prefix) — HMAC-SHA256 signed payload with expiry. Air-gap safe, no database or network required.
+3. **JWT** (3-part dot-separated) — Payload decode with expiry check. Full JWKS verification delegated to API gateway.
+
+**Token Format (HMAC offline):**
+```
+hmac_<base64url(payload)>.<base64url(signature)>
+```
+Payload contains: `sub`, `email`, `role`, `scopes`, `tenant_id`, `iat`, `exp`, `jti`.
+
+**Caching:** Verification results cached by SHA-256 hash of token with 5-minute TTL to reduce repeated database lookups.
+
+**Scopes:** `mcp:read`, `mcp:write`, `mcp:execute` — granular permission control for MCP tool invocations.
+
+### Component 4: MCP Elicitation Handler (`MCPElicitationHandler`)
+
+Allows MCP tools to pause execution and request user input.
+
+**Elicitation Types:**
+| Type | Description |
+|------|-------------|
+| `text` | Free-form text input |
+| `choice` | Select from predefined options |
+| `confirm` | Yes/no confirmation |
+
+**Lifecycle:** `create_elicitation()` -> pending -> `resolve_elicitation(id, response)` -> resolved. Tools check `get_pending()` for outstanding requests.
+
+### Component 5: MCP Task Manager (`MCPTaskManager`)
+
+Wraps long-running MCP tool invocations as trackable tasks with lifecycle management.
+
+**Task States:**
+```
+created -> running (with progress 0-100%) -> completed | failed
+```
+
+**Operations:**
+| Method | Description |
+|--------|-------------|
+| `create_task(tool, params)` | Create task, returns task_id |
+| `update_progress(id, pct)` | Update progress percentage |
+| `complete_task(id, result)` | Mark complete with result payload |
+| `fail_task(id, error)` | Mark failed with error message |
+| `get_task(id)` | Get current task status |
+| `list_tasks(status)` | List tasks, optionally filtered |
+
+---
+
+## 5. Database
+
+### Existing Tables Used
+
+| Table | Database | Usage |
+|-------|----------|-------|
+| `agent_registry` | `data/icdev.db` | Agent health status and heartbeat for discovery server health-aware routing |
+| `api_keys` | `data/platform.db` | API key hash lookup for MCP OAuth API key verification mode |
+| `users` | `data/platform.db` | User email and role lookup joined with API keys |
+
+No new database tables are created by Phase 55. Agent Cards are generated dynamically from `agent_config.yaml`. Elicitation and task state are held in-memory (stateless per request cycle). HMAC tokens are self-contained and verified without database access.
+
+---
+
+## 6. Configuration
+
+### `args/agent_config.yaml` (existing, extended)
+
+Agent definitions now consumed by the Agent Card generator. Each agent entry contributes `port`, `host`, `id`, `description`, and optional `streaming` flag to the v0.3 Agent Card.
+
+### Environment Variables
+
+| Variable | Purpose | Default |
+|----------|---------|---------|
+| `ICDEV_MCP_OAUTH_SECRET` | HMAC secret key for offline token signing/verification | Falls back to `ICDEV_DASHBOARD_SECRET` |
+| `ICDEV_DASHBOARD_SECRET` | Fallback HMAC secret | Auto-generated if not set |
+
+---
+
+## 7. Dashboard
+
+Phase 55 does not introduce new dashboard pages. Agent discovery and health information is surfaced through:
+
+- `/agents` page — Existing agent registry with heartbeat age (Phase 10)
+- `/traces` page — A2A distributed trace visualization (Phase 46)
+
+Discovery server data is available via CLI and MCP tools for programmatic consumption.
+
+---
+
+## 8. Security Gates
+
+A2A v0.3 and MCP OAuth integrate with existing security gates:
+
+- **Remote Command Gate** — User binding required before any command execution; MCP OAuth token verification enforces identity chain (D136)
+- **A2A mutual TLS** — All inter-agent communication uses mTLS within K8s cluster; Agent Cards declare `mutual_tls` as authentication scheme
+- **Token expiry enforcement** — All three verification modes (JWT, API key, HMAC) check token expiry; expired tokens are rejected
+- **HMAC tamper detection** — Offline tokens use HMAC-SHA256 with constant-time comparison (`hmac.compare_digest`) to prevent timing attacks
+- **Scope-based access** — MCP tools require appropriate scopes (`mcp:read`, `mcp:write`, `mcp:execute`) verified from token payload
+
+No new gate added to `args/security_gates.yaml` — Phase 55 operates within the existing authentication and authorization framework established by Phase 21 (SaaS) and Phase 28 (Remote Command Gateway).
+
+---
+
+## 9. Verification
+
+```bash
+# A2A v0.3 Agent Card generation
+python tools/agent/a2a_agent_card_generator.py --all --json         # Generate all 15 agent cards
+python tools/agent/a2a_agent_card_generator.py --agent-id builder --json  # Single agent card
+python tools/agent/a2a_agent_card_generator.py --list --json        # List agents summary
+
+# A2A v0.3 Discovery Server
+python tools/agent/a2a_discovery_server.py --list --json            # Discover all agents with health
+python tools/agent/a2a_discovery_server.py --find-skill ssp_generate --json  # Skill-based lookup
+python tools/agent/a2a_discovery_server.py --find-capability taskSubscription --json  # Capability filter
+python tools/agent/a2a_discovery_server.py --summary --json         # Discovery landscape summary
+
+# MCP OAuth 2.1 verification (programmatic)
+python -c "
+from tools.saas.mcp_oauth import MCPOAuthVerifier
+v = MCPOAuthVerifier()
+token = v.generate_offline_token('user-1', 'admin@icdev.local', 'admin')
+result = v.verify_token(token)
+print(f'Verified: {result[\"verified\"]}, Method: {result[\"method\"]}, Role: {result[\"role\"]}')
+"
+
+# MCP Elicitation (programmatic)
+python -c "
+from tools.saas.mcp_oauth import MCPElicitationHandler
+h = MCPElicitationHandler()
+req = h.create_elicitation('ssp_generate', 'Select impact level', options=['IL4','IL5','IL6'], input_type='choice')
+print(f'Elicitation: {req[\"elicitation_id\"]}, Status: {req[\"status\"]}')
+resolved = h.resolve_elicitation(req['elicitation_id'], 'IL5')
+print(f'Resolved: {resolved[\"status\"]}, Response: {resolved[\"response\"]}')
+"
+
+# MCP Tasks (programmatic)
+python -c "
+from tools.saas.mcp_oauth import MCPTaskManager
+tm = MCPTaskManager()
+task = tm.create_task('sbom_generate', {'project_id': 'proj-123'})
+print(f'Task: {task[\"task_id\"]}, Status: {task[\"status\"]}')
+tm.update_progress(task['task_id'], 50, 'running')
+tm.complete_task(task['task_id'], {'sbom_path': '/tmp/sbom.json'})
+print(f'Final: {tm.get_task(task[\"task_id\"])[\"status\"]}')
+"
+```
+
+---
+
+## 10. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D344 | A2A v0.3 adds `capabilities` to Agent Card and `tasks/sendSubscribe` for streaming. Backward compatible via `protocolVersion` field. | v0.2 clients ignore unknown fields; v0.3 clients use capabilities for intelligent routing. Discovery server provides skill-based and capability-based agent lookup without hardcoded routing tables. |
+| D345 | MCP OAuth 2.1 reuses existing SaaS auth middleware. Supports offline HMAC token verification for air-gap. | No new auth stack — reuses Phase 21 API key infrastructure (SHA-256 hash lookup), extends with HMAC offline tokens for IL5/IL6 air-gapped deployments. JWT verification degrades gracefully when JWKS endpoint unavailable. |
+| D346 | MCP Elicitation allows tools to request user input mid-execution. MCP Tasks wraps long-running tools with create/progress/complete lifecycle. | Elicitation supports interactive compliance workflows (e.g., selecting impact level during SSP generation). Task lifecycle enables progress tracking for operations that span minutes (e.g., full SBOM generation, Monte Carlo simulation). Both use in-memory state — no new database tables. |
+
+---
+
+## 11. Files
+
+### New Files (3)
+| File | LOC | Purpose |
+|------|-----|---------|
+| `tools/agent/a2a_agent_card_generator.py` | ~285 | A2A v0.3 Agent Card generation for all 15 agents |
+| `tools/agent/a2a_discovery_server.py` | ~250 | Centralized agent discovery with health-aware routing |
+| `tools/saas/mcp_oauth.py` | ~400 | MCP OAuth 2.1 verifier, elicitation handler, task manager |
+
+### Modified Files (5)
+| File | Change |
+|------|--------|
+| `tools/mcp/tool_registry.py` | +A2A discovery and MCP OAuth tool entries |
+| `tools/mcp/gap_handlers.py` | +Handler functions for discovery/oauth tools |
+| `CLAUDE.md` | +D344-D346, +Phase 55 commands, +A2A v0.3 goal entry |
+| `tools/manifest.md` | +A2A v0.3 and MCP OAuth section |
+| `goals/manifest.md` | +A2A v0.3 goal entry |

icdev/data/docs/features/phase-56-evidence-lineage.md

@@ -0,0 +1,352 @@
+# Phase 56 — Compliance Evidence & Artifact Lineage
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 56 |
+| Title | Compliance Evidence & Artifact Lineage |
+| Status | Implemented |
+| Priority | P1 |
+| Dependencies | Phase 46 (Observability & XAI), Phase 18 (MBSE Integration), Phase 23 (Universal Compliance Platform), Phase 4 (NIST Compliance) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-26 |
+
+---
+
+## 1. Problem Statement
+
+ICDEV supports 14 compliance frameworks (NIST 800-53, FedRAMP, CMMC, HIPAA, CJIS, PCI DSS, ISO 27001, SOC 2, NIST 800-207, MITRE ATLAS, AI Transparency, SBOM, audit trail, and more), each generating evidence across different DB tables and file artifacts. Before Phase 56, there was no unified mechanism to:
+
+- Collect evidence across all frameworks in a single operation
+- Check whether collected evidence is still fresh enough for an upcoming ATO assessment
+- Integrate evidence freshness into the heartbeat monitoring daemon for continuous compliance
+- Visualize the relationships between artifacts produced at every stage of the SDLC — from MBSE model elements through provenance activities to audit events and SBOM components
+
+Assessors had to query each framework's DB tables individually. Compliance officers had no cross-framework inventory view. The digital thread, provenance graph, audit trail, and SBOM were four separate data silos with no unified visualization.
+
+Phase 56 closes these gaps with two capabilities: universal evidence auto-collection with freshness monitoring (D347), and an artifact lineage DAG that joins all four data sources into a single interactive visualization (D348).
+
+---
+
+## 2. Goals
+
+1. Provide a universal evidence collector that spans all 14 compliance frameworks in a single CLI invocation
+2. Map each framework to its backing DB tables and file artifact patterns via a declarative registry
+3. Compute per-framework evidence counts, freshness timestamps, and staleness alerts
+4. Support configurable max-age thresholds for freshness checking (default 168 hours / 7 days)
+5. Integrate evidence freshness into the heartbeat daemon for continuous compliance monitoring
+6. Build a unified artifact lineage DAG joining 4 data sources: digital thread, W3C PROV, audit trail, and SBOM
+7. Render the lineage DAG as an SVG visualization on the `/lineage` dashboard page
+8. Provide a `/evidence` dashboard page with framework inventory, collection trigger, and freshness checking
+9. Expose REST API endpoints for both evidence and lineage operations
+
+---
+
+## 3. Architecture
+
+```
+         Universal Compliance Evidence & Artifact Lineage
+  ┌─────────────────────────────────────────────────────────────┐
+  │                evidence_collector.py (D347)                 │
+  │   FRAMEWORK_EVIDENCE_MAP: 14 frameworks → tables + globs   │
+  └──────────────┬──────────────────────────────┬───────────────┘
+                 │                              │
+     ┌───────────┴───────────┐       ┌──────────┴──────────┐
+     │  collect_evidence()   │       │  check_freshness()  │
+     │  per-table counts     │       │  max_age_hours      │
+     │  per-file hashing     │       │  staleness alerts    │
+     └───────────┬───────────┘       └──────────┬──────────┘
+                 │                              │
+      ┌──────────┴──────────────────────────────┴──────────┐
+      │              Dashboard: /evidence                   │
+      │  stat grid · framework table · collect · freshness  │
+      └─────────────────────────────────────────────────────┘
+
+  ┌─────────────────────────────────────────────────────────────┐
+  │              lineage_api.py (D348)                          │
+  │   4 data sources → unified DAG (nodes + edges)             │
+  └──────────────┬──────────────────────────────────────────────┘
+                 │
+     ┌───────────┼───────────────┬──────────────┐
+     ↓           ↓               ↓              ↓
+  Digital     W3C PROV       Audit Trail     SBOM
+  Thread      Entities       Events          Components
+  (MBSE)      + Relations    (append-only)   (sbom_records)
+     │           │               │              │
+     └───────────┼───────────────┘              │
+                 ↓                              ↓
+          Nodes + Edges ────────────────────────┘
+                 │
+      ┌──────────┴──────────────────────────────────────────┐
+      │              Dashboard: /lineage                     │
+      │  stat grid · SVG DAG · artifact inventory table     │
+      └─────────────────────────────────────────────────────┘
+
+  Heartbeat Integration:
+  ┌──────────────────────────────────────────────────────────┐
+  │  heartbeat_daemon.py  →  check_evidence_freshness()     │
+  │  Periodic probe → stale evidence → audit + SSE alert    │
+  └──────────────────────────────────────────────────────────┘
+```
+
+### Key Design Principles
+
+- **Extends existing patterns** — Evidence collector follows the `cssp_evidence_collector.py` pattern, not a new architecture (D347)
+- **Declarative registry** — `FRAMEWORK_EVIDENCE_MAP` maps each framework to DB tables and file globs; add new frameworks without code changes (D26 pattern)
+- **Read-only DAG** — Lineage visualization joins existing tables without creating new data or modifying sources (D348)
+- **Air-gap safe** — All operations use stdlib `sqlite3`, `hashlib`, `pathlib`, and `xml.etree.ElementTree`; zero external dependencies
+- **Append-only audit** — Evidence collection events recorded in the audit trail (D6 pattern)
+
+---
+
+## 4. Implementation
+
+### Component 1: Universal Evidence Collector (`tools/compliance/evidence_collector.py`)
+
+**Declarative Framework Registry** — `FRAMEWORK_EVIDENCE_MAP` defines 14 frameworks, each with:
+
+| Field | Purpose |
+|-------|---------|
+| `description` | Human-readable framework name |
+| `tables` | List of DB tables containing evidence for this framework |
+| `file_patterns` | Glob patterns for file-based artifacts (e.g., `**/ssp_*.json`) |
+| `required` | Whether this framework is mandatory for ATO readiness |
+
+**14 Supported Frameworks:**
+
+| Framework | Tables | Required |
+|-----------|--------|----------|
+| `nist_800_53` | control_implementations, audit_trail, stig_results | Yes |
+| `fedramp` | fedramp_assessments, control_implementations, oscal_validation_log | Yes |
+| `cmmc` | cmmc_assessments, control_implementations | No |
+| `hipaa` | hipaa_assessments | No |
+| `cjis` | cjis_assessments | No |
+| `pci_dss` | pci_dss_assessments | No |
+| `iso27001` | iso27001_assessments | No |
+| `soc2` | soc2_assessments | No |
+| `nist_800_207` | nist_800_207_assessments, zta_maturity_scores | No |
+| `atlas` | atlas_assessments, atlas_red_team_results | No |
+| `ai_transparency` | omb_m25_21_assessments, omb_m26_04_assessments, nist_ai_600_1_assessments, gao_ai_assessments, model_cards, system_cards, ai_use_case_inventory | No |
+| `sbom` | sbom_records | Yes |
+| `audit_trail` | audit_trail | Yes |
+| `hitrust` | hitrust_assessments | No |
+
+**Core Functions:**
+
+- `collect_evidence(project_id, project_dir, framework)` — Scans all or one framework, counts DB records per table, hashes file artifacts, returns structured summary
+- `check_freshness(project_id, max_age_hours)` — Computes evidence age for each framework, flags stale items beyond threshold
+- `list_frameworks()` — Returns all registered frameworks with metadata
+
+**Helper Utilities:**
+
+- `_count_project_records()` — Counts records for a project in a table, auto-detects timestamp columns (`created_at`, `collected_at`, `assessed_at`, `timestamp`) for freshness
+- `_hash_file()` — SHA-256 file hashing for artifact integrity verification
+- `_compute_age_hours()` — Parses multiple timestamp formats (ISO, SQLite datetime) and computes age in hours
+- `_table_exists()` — Safe table existence check via `sqlite_master`
+
+### Component 2: Artifact Lineage API (`tools/dashboard/api/lineage.py`)
+
+**Blueprint `lineage_api`** with routes:
+
+- `GET /api/lineage/graph` — Builds the unified DAG for a project by querying 4 data sources
+- `GET /api/lineage/stats` — Returns node/edge counts per data source
+
+**4 Data Sources Joined into DAG:**
+
+| Source | Table(s) | Node Type | Edge Type |
+|--------|----------|-----------|-----------|
+| Digital Thread | `digital_thread_links` | `source_type:source_id` | `link_type` (traces_to, implements, etc.) |
+| W3C Provenance | `prov_entities`, `prov_relations` | `entity_type` | `relation_type` (wasGeneratedBy, used, wasDerivedFrom) |
+| Audit Trail | `audit_trail` | `audit_event` | Temporal ordering (last 50 events) |
+| SBOM | `sbom_records` | `sbom_component` | Component dependency (up to 100 components) |
+
+Each node carries: `id`, `type`, `label`, `source`. Each edge carries: `source`, `target`, `relation`, `origin`.
+
+### Component 3: Evidence Dashboard API (`tools/dashboard/api/evidence.py`)
+
+**Blueprint `evidence_api`** with routes:
+
+- `GET /api/evidence/stats` — Overall evidence statistics (framework count, required count, per-framework record totals)
+- `POST /api/evidence/collect` — Trigger evidence collection for a project (accepts `project_id`, `framework`, `project_dir`)
+- `GET /api/evidence/freshness` — Check evidence freshness for a project (accepts `project_id`, `max_age_hours`)
+
+### Component 4: Heartbeat Integration
+
+The heartbeat daemon (`tools/monitor/heartbeat_daemon.py`) includes an evidence freshness check that periodically probes stale evidence across all required frameworks. When evidence exceeds the configured max-age threshold, the daemon:
+
+1. Records the staleness event in the audit trail
+2. Pushes an SSE notification to the dashboard
+3. Sends an alert to configured gateway channels (if enabled)
+
+---
+
+## 5. Database
+
+Phase 56 does not create new database tables. It reads from existing tables across multiple subsystems:
+
+### Evidence Collection — Tables Read
+
+| Table | Framework | Purpose |
+|-------|-----------|---------|
+| `control_implementations` | NIST 800-53, FedRAMP, CMMC | Control implementation evidence |
+| `audit_trail` | Audit Trail | Append-only event log |
+| `stig_results` | NIST 800-53 | STIG scan results |
+| `fedramp_assessments` | FedRAMP | FedRAMP assessment records |
+| `oscal_validation_log` | FedRAMP | OSCAL validation attempts |
+| `cmmc_assessments` | CMMC | CMMC practice assessments |
+| `hipaa_assessments` | HIPAA | HIPAA safeguard assessments |
+| `cjis_assessments` | CJIS | CJIS policy area assessments |
+| `pci_dss_assessments` | PCI DSS | PCI DSS requirement assessments |
+| `iso27001_assessments` | ISO 27001 | ISO 27001 control assessments |
+| `soc2_assessments` | SOC 2 | SOC 2 trust criteria assessments |
+| `nist_800_207_assessments` | NIST 800-207 | ZTA assessment records |
+| `zta_maturity_scores` | NIST 800-207 | ZTA pillar maturity scores |
+| `atlas_assessments` | ATLAS | MITRE ATLAS assessments |
+| `atlas_red_team_results` | ATLAS | Red team test results |
+| `omb_m25_21_assessments` | AI Transparency | OMB M-25-21 assessments |
+| `omb_m26_04_assessments` | AI Transparency | OMB M-26-04 assessments |
+| `nist_ai_600_1_assessments` | AI Transparency | NIST AI 600-1 assessments |
+| `gao_ai_assessments` | AI Transparency | GAO AI assessments |
+| `model_cards` | AI Transparency | AI model cards |
+| `system_cards` | AI Transparency | AI system cards |
+| `ai_use_case_inventory` | AI Transparency | AI use case registry |
+| `sbom_records` | SBOM | Software bill of materials |
+| `hitrust_assessments` | HITRUST | HITRUST CSF assessments |
+
+### Lineage DAG — Tables Read
+
+| Table | Source | Node Type |
+|-------|--------|-----------|
+| `digital_thread_links` | MBSE Digital Thread | Requirements, model elements, code modules |
+| `prov_entities` | W3C Provenance | Provenance entities (artifacts, agents) |
+| `prov_relations` | W3C Provenance | Provenance relationships |
+| `audit_trail` | Audit Trail | Audit events (actions by actors) |
+| `sbom_records` | SBOM | Software components with versions |
+
+---
+
+## 6. Configuration
+
+Evidence freshness thresholds are configurable via CLI flags:
+
+```bash
+# Default: 168 hours (7 days)
+python tools/compliance/evidence_collector.py --project-id "proj-123" --freshness --max-age-hours 168 --json
+
+# Stricter: 72 hours (3 days) for cATO environments
+python tools/compliance/evidence_collector.py --project-id "proj-123" --freshness --max-age-hours 72 --json
+```
+
+Heartbeat daemon configuration in `args/monitoring_config.yaml` includes the evidence freshness check interval and max-age threshold.
+
+The framework registry (`FRAMEWORK_EVIDENCE_MAP`) is defined as a Python dict constant in `evidence_collector.py`. To add a new framework, add a new entry with `description`, `tables`, `file_patterns`, and `required` fields.
+
+---
+
+## 7. Dashboard
+
+### `/evidence` — Compliance Evidence Inventory
+
+- **Stat grid** (4 cards): total frameworks, required frameworks, frameworks with evidence, coverage percentage
+- **Controls**: project ID input, "Collect Evidence" button (POST), "Check Freshness" button (GET)
+- **Framework table**: framework ID, description, required flag, record count, status badge (green/yellow/red)
+- **Freshness results**: per-framework age display with stale/fresh indicators
+
+### `/lineage` — Artifact Lineage DAG
+
+- **Stat grid** (3 cards): total nodes, total edges, data sources contributing
+- **Controls**: project ID input, "Load Lineage" button
+- **SVG DAG visualization**: client-side rendered DAG with color-coded nodes by source (digital thread, provenance, audit trail, SBOM); WCAG accessible (`role="img"`, `aria-label`)
+- **Artifact inventory table**: all nodes listed with ID, type, label, source; auto-enhanced by `tables.js` (search, sort, filter, CSV export)
+
+Both pages follow existing dashboard patterns: `base.html` extension, stat-grid layout, `table-container` wrapper, `charts.js` SVG rendering, CUI banner integration.
+
+---
+
+## 8. Security Gates
+
+Phase 56 does not introduce a new named security gate. Evidence freshness is enforced through the existing gate infrastructure:
+
+- **cATO Gate** — `0 expired evidence on critical controls, readiness >= 50%` already blocks on stale evidence. Phase 56's freshness checker provides the data that feeds this gate evaluation.
+- **Multi-Regime Gate** — `All applicable frameworks must pass individual gates` depends on evidence being current across all detected frameworks.
+
+The evidence collector's `--freshness` flag and heartbeat integration ensure that staleness is detected proactively before gate evaluation occurs, rather than discovering it at deployment time.
+
+---
+
+## 9. Verification
+
+```bash
+# CLI — Collect evidence for all frameworks
+python tools/compliance/evidence_collector.py --project-id "proj-123" --json
+
+# CLI — Collect evidence for a single framework
+python tools/compliance/evidence_collector.py --project-id "proj-123" --framework fedramp --json
+
+# CLI — Check evidence freshness (default 168-hour threshold)
+python tools/compliance/evidence_collector.py --project-id "proj-123" --freshness --max-age-hours 168 --json
+
+# CLI — List supported frameworks
+python tools/compliance/evidence_collector.py --list-frameworks --json
+
+# Dashboard — Evidence page
+# Navigate to /evidence, enter project ID, click "Collect Evidence" or "Check Freshness"
+
+# Dashboard — Lineage page
+# Navigate to /lineage, enter project ID, click "Load Lineage" to render SVG DAG
+
+# API — Evidence endpoints
+curl http://localhost:5000/api/evidence/stats
+curl -X POST http://localhost:5000/api/evidence/collect -d '{"project_id":"proj-123"}'
+curl "http://localhost:5000/api/evidence/freshness?project_id=proj-123&max_age_hours=168"
+
+# API — Lineage endpoints
+curl "http://localhost:5000/api/lineage/graph?project_id=proj-123"
+curl "http://localhost:5000/api/lineage/stats"
+```
+
+---
+
+## 10. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D347 | Evidence collector extends `cssp_evidence_collector.py` pattern to all 14 frameworks | Proven pattern from Phase 14; declarative framework-to-table mapping enables adding new frameworks without code changes (D26 pattern). Uses crosswalk engine for multi-framework evidence mapping. |
+| D348 | Lineage dashboard joins digital thread + provenance + audit trail + SBOM into unified DAG visualization | Read-only SVG rendering from existing DB tables. No new data storage, no data duplication. Four previously siloed data sources become a single navigable graph for compliance officers and assessors. |
+
+### Related Decisions
+
+| ID | Relevance |
+|----|-----------|
+| D6 | Audit trail is append-only/immutable — lineage reads but never modifies |
+| D7 | stdlib `xml.etree.ElementTree` for file parsing — air-gap safe |
+| D26 | Declarative JSON/dict registries — add frameworks without code changes |
+| D94 | SVG chart library (zero dependencies) — lineage DAG uses same rendering approach |
+| D287 | W3C PROV-AGENT provenance in 3 append-only SQLite tables — lineage reads prov_entities and prov_relations |
+| D163 | Heartbeat notifications fan out to audit trail, SSE, gateway — evidence staleness alerts use same channels |
+
+---
+
+## 11. Files
+
+### New Files (5)
+
+| File | Purpose |
+|------|---------|
+| `tools/compliance/evidence_collector.py` | Universal compliance evidence auto-collector (14 frameworks) |
+| `tools/dashboard/api/evidence.py` | Dashboard API Blueprint for evidence collection |
+| `tools/dashboard/api/lineage.py` | Dashboard API Blueprint for artifact lineage DAG |
+| `tools/dashboard/templates/evidence.html` | Evidence collection dashboard page |
+| `tools/dashboard/templates/lineage.html` | Artifact lineage DAG dashboard page |
+
+### Modified Files
+
+| File | Change |
+|------|--------|
+| `tools/dashboard/app.py` | +/evidence and /lineage routes, +Blueprint registrations |
+| `tools/monitor/heartbeat_daemon.py` | +evidence_freshness check integration |
+| `tools/mcp/tool_registry.py` | +evidence and lineage tool entries in unified gateway |
+| `CLAUDE.md` | +D347-D348, +CLI commands, +dashboard pages, +evidence collection section |
+| `tools/manifest.md` | +Evidence Collection and Artifact Lineage entries |
+| `goals/manifest.md` | +Evidence Collection entry |