icdev 1.0.0__py3-none-any.whl

icdev/data/docs/features/phase-29-proactive-monitoring.md

@@ -0,0 +1,212 @@
+# Phase 29 — Proactive Monitoring
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 29 |
+| Title | Proactive Monitoring |
+| Status | Implemented |
+| Priority | P1 |
+| Dependencies | Phase 8 (Self-Healing System), Phase 9 (Monitoring & Observability), Phase 28 (Remote Command Gateway) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+ICDEV's existing monitoring is reactive -- the system waits for failures to occur, then matches them against known patterns for remediation. In Gov/DoD environments operating at IL4/IL5/IL6 impact levels, reactive monitoring is insufficient. Compliance evidence expires silently, certificate renewals are missed, dependency vulnerabilities accumulate unnoticed, and operator workload spikes without warning. By the time a human notices, the damage is done: an ATO lapses, a critical CVE goes unpatched past SLA, or a pipeline breaks during a mission-critical deployment window.
+
+Proactive monitoring addresses this gap through four complementary capabilities. First, a heartbeat daemon continuously checks system health across 7 configurable dimensions with per-check intervals, detecting drift before it becomes failure. Second, webhook-triggered auto-resolution receives external alerts (from Prometheus, CloudWatch, or other monitoring systems) and automatically analyzes, diagnoses, and fixes known issues -- creating branches and pull requests for the fixes. Third, selective skill injection dynamically loads only the Claude Code skills relevant to the current task context, reducing token overhead and improving response quality. Fourth, time-decay memory ranking ensures that recent, relevant memories surface first while stale information naturally fades, improving the quality of AI-assisted decision-making.
+
+Together, these four capabilities transform ICDEV from a system that reacts to failure into one that anticipates and prevents it, while simultaneously improving the quality of AI interactions through smarter context management.
+
+---
+
+## 2. Goals
+
+1. Implement a heartbeat daemon with 7 configurable health checks (cATO evidence freshness, certificate expiry, dependency currency, pipeline health, agent responsiveness, DB integrity, disk usage) running at independently configurable intervals
+2. Enable webhook-triggered auto-resolution that receives external alerts, applies the 3-tier confidence model (auto-fix >= 0.7, suggest 0.3-0.7, escalate < 0.3), and creates fix branches/PRs via the existing VCS abstraction
+3. Provide selective skill injection that matches task context to relevant Claude Code skills using deterministic keyword-based category matching across 9 categories, reducing unnecessary skill loading
+4. Implement time-decay memory ranking using an exponential decay formula with per-memory-type half-lives (fact=90d, event=7d, insight=30d, task=14d, preference=180d, relationship=120d) to surface the most relevant memories
+5. Fan out heartbeat notifications to 3 sinks: append-only audit trail (always), SSE dashboard events (if dashboard running), and gateway channels (if configured)
+6. Enforce rate limiting on auto-resolution (max 5/hour) and require human approval for infrastructure-level fixes regardless of confidence
+7. Maintain backward compatibility -- all new features are opt-in via CLI flags and configuration, with no changes to existing behavior when flags are omitted
+
+---
+
+## 3. Architecture
+
+```
++---------------------------------------------------------------+
+|                    Proactive Monitoring Layer                   |
+|                                                                |
+|  +--------------------+    +-----------------------------+     |
+|  | Heartbeat Daemon   |    | Webhook Auto-Resolver       |     |
+|  | (7 checks, YAML    |    | /alert-webhook endpoint     |     |
+|  |  configurable       |    | 3-tier confidence model     |     |
+|  |  intervals)        |    | VCS branch/PR creation      |     |
+|  +--------+-----------+    +-------------+---------------+     |
+|           |                              |                     |
+|           v                              v                     |
+|  +---------------------------------------------------+        |
+|  |              Notification Fan-Out                  |        |
+|  |  [Audit Trail] + [SSE Dashboard] + [Gateway]      |        |
+|  +---------------------------------------------------+        |
+|                                                                |
+|  +--------------------+    +-----------------------------+     |
+|  | Skill Selector     |    | Time-Decay Memory Ranker    |     |
+|  | 9 categories,      |    | Exponential decay formula   |     |
+|  | keyword matching,   |    | Per-type half-lives         |     |
+|  | file-based detect   |    | Integrated with hybrid      |     |
+|  +--------------------+    | search via --time-decay      |     |
+|                            +-----------------------------+     |
++---------------------------------------------------------------+
+```
+
+### Heartbeat Check Registry
+
+| Check | Default Interval | Description |
+|-------|-----------------|-------------|
+| cATO Evidence Freshness | 6 hours | Verify no expired critical evidence |
+| Certificate Expiry | 12 hours | Check TLS/mTLS certificates |
+| Dependency Currency | 24 hours | Scan for known CVEs |
+| Pipeline Health | 1 hour | Verify CI/CD pipeline status |
+| Agent Responsiveness | 5 minutes | Ping all registered agents |
+| DB Integrity | 12 hours | SQLite integrity checks |
+| Disk Usage | 1 hour | Monitor storage thresholds |
+
+---
+
+## 4. Requirements
+
+### 4.1 Heartbeat Daemon
+
+#### REQ-29-001: Configurable Health Checks
+The system SHALL maintain a heartbeat daemon with 7 configurable health checks, each with an independently settable interval defined in YAML configuration (D26 pattern).
+
+#### REQ-29-002: Per-Check Cadence
+Each health check type SHALL run at its own cadence (e.g., agent responsiveness every 5 minutes, dependency currency every 24 hours) as configured in `args/monitoring_config.yaml`.
+
+#### REQ-29-003: Single-Pass Mode
+The heartbeat daemon SHALL support a `--once` flag for single-pass execution and a `--check <name>` flag for running a specific check, in addition to continuous daemon mode.
+
+#### REQ-29-004: Notification Fan-Out
+Heartbeat results SHALL fan out to 3 sinks: the append-only audit trail (always), SSE dashboard events (if the dashboard is running), and gateway channels (if configured per Phase 28).
+
+### 4.2 Webhook Auto-Resolution
+
+#### REQ-29-005: Alert Webhook Endpoint
+The system SHALL extend the existing webhook server with an `/alert-webhook` endpoint that receives external alerts from Prometheus, CloudWatch, or other monitoring systems.
+
+#### REQ-29-006: Three-Tier Auto-Resolution
+The auto-resolver SHALL apply the existing 3-tier self-healing decision engine: auto-fix at confidence >= 0.7, suggest fix at 0.3-0.7, and escalate with full context at < 0.3.
+
+#### REQ-29-007: VCS Branch and PR Creation
+When auto-resolution produces a fix, the system SHALL create a fix branch and pull request via the existing VCS abstraction (`tools/ci/modules/vcs.py`), with the fix code and explanation.
+
+#### REQ-29-008: Rate Limiting
+Auto-resolution SHALL enforce a maximum of 5 auto-fix actions per hour and a 10-minute cooldown between fixes targeting the same component.
+
+### 4.3 Selective Skill Injection
+
+#### REQ-29-009: Keyword-Based Category Matching
+The skill selector SHALL match task context (user query text) against 9 skill categories using deterministic keyword matching, without requiring an LLM call.
+
+#### REQ-29-010: File-Based Detection
+The skill selector SHALL support file-based detection, inferring relevant categories from file extensions and path patterns present in the working directory.
+
+#### REQ-29-011: Injection-Ready Output
+The skill selector SHALL produce markdown-formatted context blocks suitable for direct injection into Claude Code sessions, including relevant commands, goals, and context directories.
+
+#### REQ-29-012: Confidence Threshold
+Skill matches below the configured confidence threshold (default 0.5) SHALL be excluded from injection to prevent irrelevant context loading.
+
+### 4.4 Time-Decay Memory Ranking
+
+#### REQ-29-013: Exponential Decay Formula
+The system SHALL rank memory entries using the formula `2^(-(age / half_life))` where age is the time since last access and half_life is configured per memory type.
+
+#### REQ-29-014: Per-Type Half-Lives
+The system SHALL support configurable half-lives per memory type: fact (90 days), preference (180 days), event (7 days), insight (30 days), task (14 days), relationship (120 days).
+
+#### REQ-29-015: Hybrid Search Integration
+Time-decay ranking SHALL integrate with the existing hybrid search system via an opt-in `--time-decay` flag (D44 backward compatible pattern), combining relevance (0.60), recency (0.25), and importance (0.15) weights.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `heartbeat_checks` | Per-check status records: check_name, last_run, result, next_scheduled, alert_level |
+| `auto_resolution_log` | Append-only record of auto-resolution actions: alert_source, confidence, action_taken, branch_name, pr_url, result |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/monitor/heartbeat_daemon.py` | Continuous or single-pass health checking with 7 configurable checks |
+| `tools/monitor/auto_resolver.py` | Webhook-triggered alert analysis, fix generation, branch/PR creation |
+| `tools/agent/skill_selector.py` | Keyword-based skill category matching with file-based detection fallback |
+| `tools/memory/time_decay.py` | Exponential time-decay scoring and ranking for memory entries |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D162 | Heartbeat daemon uses configurable check registry with per-check intervals in YAML | Each check type has its own cadence; D26 declarative pattern enables adding checks without code changes |
+| D163 | Heartbeat notifications fan out to 3 sinks: audit trail (always), SSE (if dashboard), gateway channels (if configured) | Ensures visibility across all operator interfaces without coupling to any single one |
+| D164 | Auto-resolver extends existing webhook_server.py with `/alert-webhook` endpoint | Avoids second Flask app, reuses HMAC verification and existing infrastructure |
+| D165 | Auto-resolver reuses existing 3-tier self-healing decision engine (>= 0.7 auto, 0.3-0.7 suggest, < 0.3 escalate) and rate limits (5/hour) | Consistent behavior with Phase 8 self-healing; operators learn one decision model |
+| D166 | Auto-resolver creates fix branches/PRs via existing VCS abstraction (`tools/ci/modules/vcs.py`) | Reuses Phase 13 CI/CD infrastructure; fixes are reviewable before merge |
+| D167 | Selective skill injection via deterministic keyword-based category matching | No LLM required, declarative YAML config (D26 pattern), air-gap safe, reproducible |
+| D168 | Time-decay uses exponential formula `2^(-(age/half_life))` with per-memory-type half-lives, opt-in via `--time-decay` flag | Natural decay model; events fade fast while facts persist; backward compatible (D44 pattern) |
+
+---
+
+## 8. Security Gate
+
+**Proactive Monitoring Gate:**
+- Auto-resolution rate limited to 5 actions per hour with 10-minute cooldown per target
+- Infrastructure-level fixes (rollback, scale, failover) require human approval regardless of confidence score
+- All heartbeat results and auto-resolution actions recorded in append-only audit trail (NIST AU-2, IR-4, SI-5)
+- HMAC-SHA256 signature verification required on all alert webhook payloads
+- Alert webhook endpoint validates source IP against configured allowlist
+- Auto-generated PRs require code review approval before merge
+
+---
+
+## 9. Commands
+
+```bash
+# Heartbeat daemon
+python tools/monitor/heartbeat_daemon.py                # Foreground daemon (7 configurable checks)
+python tools/monitor/heartbeat_daemon.py --once          # Single pass of all checks
+python tools/monitor/heartbeat_daemon.py --check cato_evidence  # Specific check
+python tools/monitor/heartbeat_daemon.py --status --json # Show all check statuses
+
+# Webhook-triggered auto-resolution
+python tools/monitor/auto_resolver.py --analyze --alert-file alert.json --json   # Analyze without acting
+python tools/monitor/auto_resolver.py --resolve --alert-file alert.json --json   # Full pipeline: analyze + fix + PR
+python tools/monitor/auto_resolver.py --history --json                            # Resolution history
+
+# Selective skill injection
+python tools/agent/skill_selector.py --query "fix the login tests" --json         # Keyword-based category matching
+python tools/agent/skill_selector.py --detect --project-dir /path --json          # File-based detection
+python tools/agent/skill_selector.py --query "deploy to staging" --format-context # Injection-ready markdown
+
+# Time-decay memory ranking
+python tools/memory/time_decay.py --score --entry-id 42 --json                    # Score single entry
+python tools/memory/time_decay.py --rank --query "keyword" --top-k 10 --json      # Time-decay ranked search
+python tools/memory/hybrid_search.py --query "test" --time-decay                   # Integrated time-decay search
+```
+
+**CUI // SP-CTI**

icdev/data/docs/features/phase-30-dashboard-auth.md

@@ -0,0 +1,215 @@
+# Phase 30 — Dashboard Authentication & RBAC
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 30 |
+| Title | Dashboard Authentication & RBAC |
+| Status | Implemented |
+| Priority | P1 |
+| Dependencies | Phase 10 (Web Dashboard), Phase 29 (Proactive Monitoring) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+The ICDEV dashboard exposes project status, compliance posture, security findings, audit trails, and agent health information -- all of which may contain CUI or other controlled information at IL4/IL5/IL6 impact levels. Despite this sensitivity, the dashboard currently has no authentication mechanism. Any user with network access can view every project, every compliance gap, every security finding, and the complete audit trail. This is a direct violation of NIST 800-53 AC-2 (Account Management), AC-3 (Access Enforcement), and IA-2 (Identification and Authentication).
+
+Furthermore, different operator roles have fundamentally different information needs. A program manager needs project status and schedule risk; an ISSO needs compliance posture and security findings; a developer needs build status and test results; a contracting officer needs deliverable tracking. Presenting all information to all users creates cognitive overload and increases the risk of inadvertent CUI exposure to unauthorized personnel.
+
+This phase adds self-contained authentication against `icdev.db` (not dependent on the SaaS layer), role-based access control with 5 operator roles, per-user API key authentication with SHA-256 hashing, Flask signed sessions for browser access, admin user management, a CUI banner toggle, and a merged activity feed combining audit trail and hook events.
+
+---
+
+## 2. Goals
+
+1. Implement per-user API key authentication with SHA-256 hashing stored in `dashboard_api_keys` table, independent of the SaaS layer (D169)
+2. Establish 5 RBAC roles (admin, pm, developer, isso, co) with role-based page visibility mapped to existing `ROLE_VIEWS` configuration
+3. Provide admin user management capabilities: create admin, list users, assign roles, generate and revoke API keys
+4. Use Flask signed sessions (`app.secret_key` from `ICDEV_DASHBOARD_SECRET` env var or auto-generated) for browser-based access (D171)
+5. Add a CUI banner toggle via `ICDEV_CUI_BANNER_ENABLED` env var (default `true`) while preserving existing `CUI_BANNER_TOP/BOTTOM` env vars (D173)
+6. Create a merged activity feed at `/activity` combining `audit_trail` and `hook_events` via UNION ALL query, maintaining the append-only contract (D174)
+7. Log all authentication events (login, logout, failed attempts, key generation, key revocation) in `dashboard_auth_log` table for NIST AU-2 compliance
+
+---
+
+## 3. Architecture
+
+```
++---------------------------------------------------------------+
+|                    Dashboard Auth Layer                         |
+|                                                                |
+|  +------------------+    +-------------------------------+     |
+|  | Login Page       |    | API Key Middleware             |     |
+|  | /login           |    | Authorization: Bearer icdev_.. |     |
+|  | API key entry    |    | SHA-256 hash lookup            |     |
+|  +--------+---------+    +---------------+---------------+     |
+|           |                              |                     |
+|           v                              v                     |
+|  +---------------------------------------------------+        |
+|  |              Session Management                    |        |
+|  |  Flask signed sessions                             |        |
+|  |  ICDEV_DASHBOARD_SECRET env var                    |        |
+|  |  30-minute timeout                                 |        |
+|  +---------------------------------------------------+        |
+|           |                                                    |
+|           v                                                    |
+|  +---------------------------------------------------+        |
+|  |              RBAC Engine (5 Roles)                 |        |
+|  |  admin: Full access + user management              |        |
+|  |  pm: Projects, status, schedule, deliverables      |        |
+|  |  developer: Build, test, code, deployments         |        |
+|  |  isso: Compliance, security, audit, agents         |        |
+|  |  co: Projects, deliverables, audit (read-only)     |        |
+|  +---------------------------------------------------+        |
+|           |                                                    |
+|           v                                                    |
+|  +---------------------------------------------------+        |
+|  |              Protected Dashboard Pages             |        |
+|  |  Role-based tab visibility per page                |        |
+|  |  CUI banner toggle (env var controlled)            |        |
+|  |  Activity feed (audit + hook events merged)        |        |
+|  +---------------------------------------------------+        |
++---------------------------------------------------------------+
+```
+
+### Authentication Flow
+
+1. User navigates to any dashboard page
+2. Middleware checks for valid Flask session cookie
+3. If no session: redirect to `/login`
+4. User enters API key on login page
+5. Key is SHA-256 hashed, looked up in `dashboard_api_keys`
+6. On match: Flask session created with user_id, role, expiry
+7. Session validated on every subsequent request
+8. Session expires after 30 minutes of inactivity
+
+---
+
+## 4. Requirements
+
+### 4.1 Authentication
+
+#### REQ-30-001: API Key Authentication
+The system SHALL authenticate dashboard users via per-user API keys, hashed with SHA-256 and stored in the `dashboard_api_keys` table within `icdev.db`.
+
+#### REQ-30-002: Self-Contained Auth (D169)
+Dashboard authentication SHALL be self-contained against `icdev.db`, with no dependency on the SaaS platform layer, keeping the dashboard independently deployable.
+
+#### REQ-30-003: Flask Signed Sessions (D171)
+The system SHALL use Flask's built-in signed sessions for browser access, with the secret key sourced from `ICDEV_DASHBOARD_SECRET` environment variable or auto-generated on first run.
+
+#### REQ-30-004: Session Expiry
+Dashboard sessions SHALL expire after 30 minutes of inactivity, requiring re-authentication.
+
+#### REQ-30-005: Authentication Logging
+All authentication events (login success, login failure, logout, key generation, key revocation) SHALL be recorded in the `dashboard_auth_log` table for NIST AU-2 compliance.
+
+### 4.2 Role-Based Access Control
+
+#### REQ-30-006: Five Operator Roles (D172)
+The system SHALL enforce 5 RBAC roles with distinct page visibility:
+- **admin**: Full access to all pages plus user/key management at `/admin/users`
+- **pm**: Projects, status, monitoring, wizard, quick-paths, batch, activity
+- **developer**: Projects, build, test, agents, monitoring, chat, activity
+- **isso**: Compliance, security, audit, agents, monitoring, gateway, activity
+- **co**: Projects, deliverables, audit (read-only access)
+
+#### REQ-30-007: Role-Based Tab Visibility
+Project detail pages SHALL show or hide tabs (compliance, security, deployments, audit) based on the authenticated user's role.
+
+#### REQ-30-008: Admin User Management
+Admin users SHALL be able to create users, assign roles, generate API keys, revoke API keys, and list all users via CLI commands and the `/admin/users` dashboard page.
+
+### 4.3 CUI Banner and Activity Feed
+
+#### REQ-30-009: CUI Banner Toggle (D173)
+The system SHALL support toggling CUI banners via the `ICDEV_CUI_BANNER_ENABLED` environment variable (default `true`), while preserving the existing `CUI_BANNER_TOP` and `CUI_BANNER_BOTTOM` env vars for content customization.
+
+#### REQ-30-010: Merged Activity Feed (D174)
+The system SHALL provide a merged activity feed at `/activity` that combines entries from `audit_trail` and `hook_events` tables via UNION ALL query, maintaining the append-only contract (D6) with no modification to either source table.
+
+#### REQ-30-011: Activity Feed Delivery
+The activity feed SHALL support both WebSocket (via Flask-SocketIO, additive) and HTTP polling for real-time updates, falling back gracefully when SocketIO is unavailable (D170).
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| `dashboard_users` | User records: user_id, email, name, role, created_at, active |
+| `dashboard_api_keys` | API keys: key_hash (SHA-256), user_id, created_at, last_used, revoked |
+| `dashboard_auth_log` | Append-only authentication event log: event_type, user_id, ip_address, timestamp, success |
+| `dashboard_user_llm_keys` | BYOK LLM keys: user_id, provider, encrypted_key (Fernet AES-256), created_at |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/dashboard/auth.py` | CLI for admin user management: create-admin, list-users, generate-key, revoke-key |
+| `tools/dashboard/app.py` | Enhanced Flask app with auth middleware, session management, RBAC enforcement |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D169 | Dashboard auth is self-contained against `icdev.db` (not imported from SaaS layer) | Keeps dashboard independently deployable; no coupling to Phase 21 SaaS infrastructure |
+| D170 | WebSocket via Flask-SocketIO is additive; HTTP polling remains for backward compat | Falls back automatically when SocketIO unavailable; no breaking changes |
+| D171 | Session cookies use Flask's built-in signed sessions with `ICDEV_DASHBOARD_SECRET` | Stdlib-compatible, no additional dependencies, air-gap safe |
+| D172 | Dashboard RBAC: 5 roles (admin, pm, developer, isso, co) mapped to existing ROLE_VIEWS | Matches organizational structure of Gov/DoD teams without over-engineering |
+| D173 | CUI banner toggle via `ICDEV_CUI_BANNER_ENABLED` env var (default true) | Allows non-CUI deployments (ISV, healthcare) to disable banners without code changes |
+| D174 | Activity feed merges `audit_trail` + `hook_events` via UNION ALL query | Read-only merge preserves append-only contract (D6); no data duplication |
+| D175 | BYOK keys stored AES-256 encrypted in `dashboard_user_llm_keys` table (Fernet) | Per-user keys override department env vars; encrypted at rest for CUI compliance |
+
+---
+
+## 8. Security Gate
+
+**Dashboard Auth Gate:**
+- All dashboard pages require authentication (no anonymous access to any page)
+- API keys stored as SHA-256 hashes only (plaintext never persisted)
+- Failed login attempts rate-limited (5 failures per IP per 15 minutes)
+- Session cookies signed with HMAC; tamper-evident
+- Admin role required for user management operations
+- All auth events recorded in append-only `dashboard_auth_log` (NIST AC-2, AC-3, IA-2, AU-2)
+- CUI banners enforced on all pages when `ICDEV_CUI_BANNER_ENABLED=true`
+- BYOK keys encrypted with Fernet AES-256 (PBKDF2, 600K iterations) before storage
+
+---
+
+## 9. Commands
+
+```bash
+# Dashboard auth management
+python tools/dashboard/auth.py create-admin --email admin@icdev.local --name "Admin"   # Create first admin + API key
+python tools/dashboard/auth.py list-users            # List all dashboard users
+
+# Start dashboard (with auth enabled)
+python tools/dashboard/app.py                        # Start web dashboard on port 5000
+
+# Environment variables
+# ICDEV_DASHBOARD_SECRET    — Flask session signing key
+# ICDEV_CUI_BANNER_ENABLED  — Toggle CUI banners (default: true)
+# ICDEV_BYOK_ENABLED        — Enable BYOK LLM key management (default: false)
+# ICDEV_BYOK_ENCRYPTION_KEY — Fernet key for BYOK encryption
+
+# Dashboard pages (auth required)
+# /login           — API key login page
+# /logout          — Clear session and redirect to login
+# /activity        — Merged activity feed (audit + hook events)
+# /admin/users     — Admin user/key management (admin role only)
+# /profile         — User profile + BYOK LLM key management
+# /usage           — Usage tracking + cost dashboard (per-user, per-provider)
+```
+
+**CUI // SP-CTI**

icdev/data/docs/features/phase-31-dashboard-ux-low-impact.md

@@ -0,0 +1,188 @@
+# Phase 31 — Dashboard UX Low Impact
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 31 |
+| Title | Dashboard UX -- Low Impact Enhancements |
+| Status | Implemented |
+| Priority | P2 |
+| Dependencies | Phase 10 (Web Dashboard), Phase 30 (Dashboard Authentication & RBAC) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-23 |
+
+---
+
+## 1. Problem Statement
+
+The ICDEV dashboard serves a diverse audience: program managers tracking schedule risk, ISSOs verifying compliance posture, developers monitoring build pipelines, and contracting officers reviewing deliverables. Many of these users operate in high-stress, time-constrained environments where cognitive overload directly impacts mission effectiveness. The existing dashboard presents raw technical data -- STIG CAT1 counts, POAM identifiers, NIST control families, CVE severity scores -- without any translation layer for non-technical operators.
+
+A program manager seeing "0 CAT1 STIG findings" does not know whether that is good or bad. An ISSO encountering "FedRAMP Moderate baseline: 325 controls" needs to know which controls are satisfied without reading a 200-page SSP. A contracting officer viewing an audit trail full of JSON event types cannot quickly assess whether deliverables are on track.
+
+Furthermore, the dashboard lacks basic usability affordances that users of modern web applications expect: no glossary for domain-specific acronyms, no breadcrumb navigation, no accessibility features (skip-to-content, ARIA labels), no friendly timestamps ("2 hours ago" vs "2026-02-23T14:32:00Z"), no notification system for important events, no error recovery guidance when gates fail, and no role-based filtering to show each persona only what they need.
+
+These are "low impact" changes -- they require no new backend logic, no database schema changes, and no API modifications. They are purely presentation-layer enhancements that transform raw technical output into actionable, role-appropriate information.
+
+---
+
+## 2. Goals
+
+1. Implement a glossary tooltip system using `data-glossary` HTML attributes and client-side JavaScript, providing plain-English definitions for every Gov/DoD and ICDEV-specific acronym on hover
+2. Add friendly timestamps throughout the dashboard ("2 hours ago", "yesterday", "last Tuesday") alongside ISO-8601 precision timestamps for auditability
+3. Provide breadcrumb navigation on all pages for spatial orientation within the dashboard hierarchy
+4. Implement ARIA accessibility features: skip-to-content link, role attributes, aria-labels, focus management, and WCAG 2.1 AA compliance on all interactive elements
+5. Add notification toasts for important events (gate failures, build completions, compliance alerts) with auto-dismiss and persistence options
+6. Create an error recovery dictionary that maps gate failure codes to plain-English fix instructions with who/what/why/fix/estimated-time fields so non-technical users can self-serve
+7. Implement role-based views via `?role=` query parameter with Flask context processor for progressive disclosure by persona (pm, developer, isso, co)
+8. Add help icons next to complex metrics with expandable explanations
+
+---
+
+## 3. Architecture
+
+```
++---------------------------------------------------------------+
+|                    Dashboard UX Layer (Low Impact)              |
+|                                                                |
+|  +-------------------+    +-----------------------------+      |
+|  | Jinja2 Filters    |    | JavaScript Modules          |      |
+|  | friendly_time()   |    | glossary.js (tooltips)       |      |
+|  | breadcrumb()      |    | notifications.js (toasts)    |      |
+|  | help_icon()       |    | accessibility.js (skip-to,   |      |
+|  | role_visible()    |    |   focus management)          |      |
+|  +-------------------+    +-----------------------------+      |
+|                                                                |
+|  +-------------------+    +-----------------------------+      |
+|  | UX Helpers        |    | Error Recovery Dictionary   |      |
+|  | tools/dashboard/  |    | Gate failure code ->         |      |
+|  |   ux_helpers.py   |    | plain-English instructions   |      |
+|  | Role views, term  |    | who/what/why/fix/est-time   |      |
+|  | definitions,      |    |                             |      |
+|  | progress pipeline |    |                             |      |
+|  +-------------------+    +-----------------------------+      |
++---------------------------------------------------------------+
+```
+
+### Role-Based View Filtering
+
+| Role | Visible Sections | Hidden Sections |
+|------|-----------------|-----------------|
+| pm | Project status, schedule, risk, deliverables, activity | Security scan details, STIG internals, agent config |
+| developer | Build status, test results, code metrics, agents, deployments | Compliance scores, POAM details, ATO status |
+| isso | Compliance posture, security findings, audit trail, agents | Build internals, code metrics |
+| co | Project status, deliverables, audit trail (read-only) | Security details, build details, agent config |
+
+---
+
+## 4. Requirements
+
+### 4.1 Glossary and Tooltips
+
+#### REQ-31-001: Glossary Tooltip System
+The system SHALL implement a glossary tooltip system using `data-glossary` HTML attributes on domain-specific terms, with client-side JavaScript rendering plain-English definitions on hover.
+
+#### REQ-31-002: Comprehensive Term Coverage
+The glossary SHALL include definitions for all Gov/DoD acronyms (ATO, SSP, POAM, STIG, CUI, SBOM, FedRAMP, CMMC, cATO, IL2-IL6), ICDEV-specific terms (GOTCHA, ATLAS, RICOAS), and compliance concepts (CAT1/CAT2/CAT3, control families).
+
+#### REQ-31-003: No Backend Changes
+The glossary system SHALL be implemented entirely in client-side JavaScript with no backend API calls, database queries, or server-side rendering changes required.
+
+### 4.2 Timestamps and Navigation
+
+#### REQ-31-004: Friendly Timestamps
+The system SHALL display friendly timestamps ("2 hours ago", "yesterday", "3 days ago") alongside ISO-8601 precision timestamps (shown on hover or in title attribute) throughout the dashboard.
+
+#### REQ-31-005: Breadcrumb Navigation
+Every dashboard page SHALL include breadcrumb navigation showing the current page's position in the hierarchy (e.g., Home > Projects > proj-123 > Compliance).
+
+### 4.3 Accessibility
+
+#### REQ-31-006: Skip-to-Content Link
+Every dashboard page SHALL include a skip-to-content link as the first focusable element, visible on keyboard focus, for WCAG 2.1 AA compliance.
+
+#### REQ-31-007: ARIA Attributes
+All interactive elements (buttons, links, form controls, status indicators) SHALL include appropriate ARIA roles, labels, and state attributes.
+
+#### REQ-31-008: Focus Management
+The system SHALL manage focus appropriately during page transitions, modal openings, and notification appearances, ensuring keyboard-only users can navigate the full dashboard.
+
+### 4.4 Notifications and Error Recovery
+
+#### REQ-31-009: Notification Toasts
+The system SHALL display notification toasts for important events (gate failures, build completions, compliance alerts) with configurable auto-dismiss timing and a manual dismiss option.
+
+#### REQ-31-010: Error Recovery Dictionary (D92)
+The system SHALL maintain an error recovery dictionary mapping gate failure codes to plain-English fix instructions containing: who should fix it, what failed, why it matters, how to fix it, and estimated time to resolution.
+
+### 4.5 Role-Based Views
+
+#### REQ-31-011: Role Query Parameter (D90)
+The system SHALL support role-based views via `?role=` query parameter, with a Flask context processor providing role information to all templates for progressive disclosure by persona.
+
+#### REQ-31-012: Help Icons
+Complex metrics and compliance scores SHALL include help icons that expand to show plain-English explanations of what the metric means and what constitutes a good or bad value.
+
+---
+
+## 5. Database Schema
+
+### Tables
+
+| Table | Purpose |
+|-------|---------|
+| (No new tables) | Phase 31 is presentation-layer only; all data comes from existing tables |
+
+---
+
+## 6. Tools
+
+| Tool | Purpose |
+|------|---------|
+| `tools/dashboard/ux_helpers.py` | UX translation functions: glossary terms, role views, error recovery dictionary, progress pipeline rendering, Quick Path templates |
+
+---
+
+## 7. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D88 | UX Translation Layer wraps existing tools without rewriting them | Jinja2 filters + JS modules convert technical output to business-friendly display; zero backend changes |
+| D89 | Glossary tooltip system uses `data-glossary` HTML attributes + client-side JS | No backend changes needed to add new terms; air-gap safe, self-contained |
+| D90 | Role-based views via `?role=` query parameter + Flask context processor | No authentication required for role filtering; progressive disclosure by persona |
+| D91 | Getting Started wizard uses declarative path mapping (goal x role x classification) | Add new paths without code changes; guides new users to recommended workflows |
+| D92 | Error recovery dictionary maps gate failure codes to plain-English fix instructions | Non-technical users (PMs, COs) can self-serve without requiring developer assistance |
+| D93 | Quick Path templates are declarative data (list of dicts in ux_helpers.py) | Add new workflow shortcuts without touching templates |
+
+---
+
+## 8. Security Gate
+
+**No dedicated security gate for Phase 31.**
+
+Phase 31 is a presentation-layer enhancement with no new data exposure, no new APIs, and no new database tables. Security is enforced by:
+- Phase 30 authentication and RBAC (all pages require login)
+- Role-based views restrict information visibility per persona
+- CUI banners remain enforced on all pages
+- No client-side JavaScript makes API calls or modifies data
+
+---
+
+## 9. Commands
+
+```bash
+# Start dashboard with UX enhancements (all low-impact features auto-enabled)
+python tools/dashboard/app.py
+
+# Role-based view filtering (append to any dashboard URL)
+# /projects?role=pm           — PM-focused project view
+# /projects?role=developer    — Developer-focused project view
+# /projects?role=isso         — ISSO-focused project view
+# /projects?role=co           — CO-focused project view
+
+# Dashboard pages with UX enhancements
+# /wizard            — Getting Started wizard (3 questions -> workflow recommendation)
+# /quick-paths       — Quick Path workflow templates + error recovery reference
+```
+
+**CUI // SP-CTI**