icdev 1.0.0__py3-none-any.whl

icdev/data/docs/features/phase-51-unified-chat-dashboard.md

@@ -0,0 +1,240 @@
+# Phase 51 — Unified Chat Dashboard
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 51 |
+| Title | Unified Chat Dashboard |
+| Status | Implemented |
+| Priority | P1 |
+| Dependencies | Phase 44 (Innovation Adaptation — multi-stream chat, extensions), Phase 50 (AI Governance — chat advisory, sidebar) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-24 |
+
+---
+
+## 1. Problem Statement
+
+Prior to Phase 51, the ICDEV dashboard had two separate chat pages serving overlapping purposes:
+
+- **`/chat`** — RICOAS requirements intake chat with session-based conversations, wizard parameter passing, readiness gauges, COA generation, BDD preview, and build pipeline sidebar. Tightly coupled to the intake engine.
+- **`/chat-streams`** — Phase 44 multi-stream parallel chat with context sidebar, message stream, intervention controls, and dirty-tracking state queries. General-purpose agent chat without RICOAS features.
+
+This split created user confusion (which page to use?), duplicated frontend code (both pages rendered message streams), and made Phase 50's governance sidebar difficult to maintain across two templates. The separation also meant operators could not seamlessly transition from a general agent conversation into a requirements intake session or vice versa within the same interface.
+
+Phase 51 merges both pages into a single unified `/chat` page that supports both workflows through a context-aware 3-pane layout. General chat contexts use the multi-stream backbone. Intake-linked contexts activate RICOAS sidebar features. The governance sidebar is available on all contexts. The separate `/chat-streams` page, its JavaScript, its E2E test, and its portal template are removed.
+
+---
+
+## 2. Goals
+
+1. Merge `/chat` (RICOAS intake) and `/chat-streams` (multi-stream) into a single unified `/chat` page
+2. Preserve all RICOAS sidebar features: readiness gauge, compliance frameworks, complexity indicator, elicitation techniques, BDD preview, COA cards, build pipeline, export actions
+3. Preserve all multi-stream features: context creation/switching/closing, intervention bar, dirty-tracking polling, message roles (user, assistant, system, intervention, governance_advisory)
+4. Add toggle buttons for RICOAS and Governance sidebars in the chat header
+5. Support intake-linked contexts via checkbox in the "New Chat" modal
+6. Remove the deprecated `/chat-streams` route, template, JavaScript, E2E spec, and portal template
+7. Mirror the unified chat to the SaaS portal as a tenant-scoped page
+8. Update the E2E test spec to cover the unified interface
+
+---
+
+## 3. Architecture
+
+```
+                     Unified /chat Page (Phase 51)
+          ┌──────────────────────────────────────────────┐
+          │                  Stats Bar                    │
+          │  Active Chats | Processing | Queued | Total   │
+          ├─────────┬─────────────────────┬──────────────┤
+          │ Context │   Message Stream    │    Right     │
+          │ Sidebar │                     │   Sidebar    │
+          │         │ user / assistant /  │              │
+          │ + New   │ system / interven-  │  RICOAS      │
+          │ ctx-1   │ tion / governance_  │  (toggle)    │
+          │ ctx-2   │ advisory            │              │
+          │ ctx-3   │                     │  Governance  │
+          │         │                     │  (toggle)    │
+          │         ├─────────────────────┤              │
+          │         │ Intervention Bar    │              │
+          │         ├─────────────────────┤              │
+          │         │ Input + Upload +    │              │
+          │         │ Send                │              │
+          ├─────────┴─────────────────────┴──────────────┤
+          │            New Context Modal                  │
+          │  Title | Model | Intake Checkbox | Prompt     │
+          └──────────────────────────────────────────────┘
+
+Backend:
+  /api/chat/*    → ChatManager (Phase 44, D257-D260)
+  /api/intake/*  → IntakeEngine (RICOAS)
+  /api/ai-transparency/stats → Governance sidebar
+  /api/ai-accountability/stats → Governance sidebar
+```
+
+### Key Design Principles
+
+- **Context-aware layout** — Right sidebar shows/hides based on context type and toggle state
+- **Backward compatible** — Existing `/chat/<session_id>` routes still work for RICOAS session URLs
+- **No new backend** — Reuses Phase 44 chat API and existing RICOAS intake API
+- **Wizard passthrough** — Getting Started wizard parameters are passed to the unified page and auto-create an intake context
+
+---
+
+## 4. Page Layout
+
+### Left Panel: Context Sidebar (280px)
+- **Header**: "Contexts" label + "New" button
+- **Context list**: Scrollable list of all contexts (active and closed)
+- Each context shows title, status badge, and click-to-select behavior
+
+### Center Panel: Chat Area (flex)
+- **Header**: Context title, status badge, RICOAS toggle, Gov toggle, Close button
+- **Message stream**: Scrollable message list with role-specific styling
+  - `user` — right-aligned, blue background
+  - `assistant` — left-aligned, default background
+  - `system` — centered, muted styling
+  - `intervention` — yellow left border
+  - `governance_advisory` — purple left border (D327)
+- **Intervention bar**: Appears during agent processing with text input and "Intervene" button (D265-D267)
+- **Input area**: Message text input, file upload button (intake contexts only), Send button
+
+### Right Panel: Sidebars (280px, toggleable)
+
+**RICOAS Sidebar** (visible for intake-linked contexts):
+- Compliance framework tags
+- Project complexity gauge with recommendation
+- Readiness score SVG arc gauge with 5 dimension bars
+- Requirements/documents/turns stats
+- Elicitation technique chips (activate/deactivate)
+- BDD scenario preview
+- COA cards with selection
+- Action buttons: Generate Plan, Export Requirements
+- Post-export actions: Generate Application, Run Simulation, View Requirements, Generate PRD, Validate PRD
+- Build pipeline phase progress
+
+**Governance Sidebar** (available on all contexts):
+- AI Transparency stats: AI Systems, Model Cards, System Cards
+- AI Accountability stats: Oversight Plans, CAIO Designations, Open Appeals, Ethics Reviews, Reassessments
+- Auto-refreshes on `governance_advisory` state changes
+
+---
+
+## 5. JavaScript Architecture
+
+The unified [chat.js](tools/dashboard/static/js/chat.js) (~1515 LOC) organizes into 18 sections:
+
+| Section | Purpose |
+|---------|---------|
+| Config & State | Global variables, context maps, framework names, poll interval |
+| Utility Helpers | HTML escaping, localStorage, API fetch helpers |
+| Multi-Stream Backbone | Context CRUD, switching, lifecycle management, sidebar visibility |
+| Messaging | Routes to `/api/chat` or `/api/intake` depending on context type |
+| File Upload | Single/batch document upload with extraction (intake contexts only) |
+| Polling | Dirty-tracking state queries with version comparison (D268-D270) |
+| Readiness | SVG arc gauge rendering, 5 dimension progress bars |
+| Complexity | Project complexity scoring and recommendation text |
+| Framework Tags | Compliance framework badge rendering |
+| Elicitation | Technique loading, chip rendering, activate/deactivate |
+| BDD Preview | Gherkin scenario rendering from intake session data |
+| Export & Actions | Plan generation, COA selection, PRD export, post-export workflows |
+| COA Rendering | COA card display with tier badges (Speed/Balanced/Comprehensive) |
+| Build Pipeline | Phase progress rendering with polling |
+| Sidebar Management | Show/hide RICOAS and governance sidebars based on toggles |
+| Rendering | Message rendering, context list updates, intervention bar state |
+| Intake Bridge | Create/load intake-linked contexts, RICOAS session mapping |
+| Event Bindings | Modal handlers, message send, file upload, keyboard shortcuts |
+
+---
+
+## 6. New Context Modal
+
+The "New Chat" modal provides:
+- **Title**: Free-text context name
+- **Agent Model**: Dropdown (Sonnet default, Opus, Haiku)
+- **Link to Requirements Intake (RICOAS)**: Checkbox that creates a linked intake session
+- **System Prompt**: Optional custom system prompt for the context
+
+When the RICOAS checkbox is selected, context creation calls both the chat API (create context) and the intake API (create session), then stores the mapping in `localStorage` under `icdev_intake_map`.
+
+---
+
+## 7. Removed Files
+
+| File | Was | Replacement |
+|------|-----|-------------|
+| `tools/dashboard/templates/chat_streams.html` | Phase 44 multi-stream page | Merged into `chat.html` |
+| `tools/dashboard/static/js/chat_streams.js` | Phase 44 multi-stream JS | Merged into `chat.js` |
+| `.claude/commands/e2e/chat_streams.md` | Phase 44 E2E test spec | Replaced by `e2e/chat.md` |
+| `tools/saas/portal/templates/chat_streams.html` | Phase 44 portal template | Replaced by `chat.html` |
+
+---
+
+## 8. Modified Files
+
+| File | Change |
+|------|--------|
+| `tools/dashboard/templates/chat.html` | Rewritten: 3-pane layout, context modal, RICOAS sidebar, governance sidebar, intervention bar (~332 LOC) |
+| `tools/dashboard/static/js/chat.js` | Rewritten: merged multi-stream backbone + RICOAS features + governance (~1515 LOC) |
+| `tools/dashboard/templates/base.html` | Removed `/chat-streams` nav link |
+| `tools/dashboard/app.py` | Removed `/chat-streams` route |
+| `tools/saas/portal/app.py` | Updated chat route docstring |
+
+---
+
+## 9. New Files
+
+| File | LOC | Purpose |
+|------|-----|---------|
+| `tools/saas/portal/templates/chat.html` | ~71 | Portal-scoped unified chat (3-pane layout, tenant context) |
+| `.claude/commands/e2e/chat.md` | ~54 | E2E test spec for unified chat interface |
+
+---
+
+## 10. Portal Integration
+
+The SaaS portal receives a tenant-scoped version at `/chat` with:
+- 4-metric stats bar (Active Chats, Processing, Queued, Total)
+- Left sidebar: context list with "New" button
+- Center pane: message stream, intervention bar, input area
+- The portal template uses `portal_base.html` and portal-specific CSS variables
+- Chat API calls are scoped to the tenant via `g.tenant_id`
+
+---
+
+## 11. E2E Test Coverage
+
+The unified E2E spec (`.claude/commands/e2e/chat.md`) covers:
+1. Page loads without errors at `/chat`
+2. CUI banners present (top and bottom)
+3. Context sidebar visible with "New Chat" button
+4. Context creation via modal
+5. New context appears in sidebar list
+6. Message input enabled after context selection
+7. Message send and display in stream
+8. Navigation preserves context state
+9. Screenshots at key interaction points
+
+---
+
+## 12. Testing
+
+```bash
+# Chat manager tests (Phase 44 backbone)
+pytest tests/test_chat_manager.py -v              # 22 tests
+
+# AI governance chat extension tests (Phase 50)
+pytest tests/test_ai_governance_chat_extension.py -v  # 28 tests
+
+# E2E test (requires running dashboard)
+python tools/testing/e2e_runner.py --test-file .claude/commands/e2e/chat.md
+```
+
+---
+
+## 13. Related
+
+- [Phase 44: Innovation Adaptation](phase-44-innovation-adaptation.md) — Multi-stream chat manager, extension hooks, dirty-tracking
+- [Phase 50: AI Governance Integration](phase-50-ai-governance-intake-chat.md) — Governance advisory, sidebar, extension handlers
+- [Phase 52: Code Intelligence](phase-52-code-intelligence.md) — Depends on Phase 51 dashboard patterns

icdev/data/docs/features/phase-52-code-intelligence.md

@@ -0,0 +1,244 @@
+# Phase 52 — Code Intelligence & Adaptive Learning
+
+**CUI // SP-CTI**
+
+| Field | Value |
+|-------|-------|
+| Phase | 52 |
+| Title | Code Intelligence & Adaptive Learning |
+| Status | Implemented |
+| Priority | P2 |
+| Dependencies | Phase 35 (Innovation Engine), Phase 44 (Innovation Adaptation), Phase 51 (Unified Chat Dashboard) |
+| Author | ICDEV Architect Agent |
+| Date | 2026-02-24 |
+
+---
+
+## 1. Problem Statement
+
+ICDEV builds applications with TDD, security scanning, and compliance validation — but it has no systematic visibility into the quality of its own codebase. When a developer asks "which functions are the most complex?" or "is our maintainability improving?", there is no tool to answer. Code smells accumulate silently. Functions grow in complexity without triggering any alert. Test failures correlate to source functions only by manual inspection. The Innovation Engine identifies external improvement opportunities but lacks internal code quality signals.
+
+Without code self-analysis, ICDEV cannot:
+- Identify its own technical debt quantitatively
+- Correlate test failures to source complexity
+- Track maintainability trends over time
+- Feed code quality insights into the Innovation Engine for guided refactoring
+
+Phase 52 closes this gap with 4 read-only, advisory-only components that analyze ICDEV's own code without modifying it.
+
+---
+
+## 2. Goals
+
+1. Provide per-function code quality metrics via AST analysis (Python) and regex analysis (Java, Go, Rust, C#, TypeScript)
+2. Detect 5 code smell types: long functions, deep nesting, high complexity, too many parameters, god classes
+3. Compute deterministic maintainability scores using a weighted formula (D337)
+4. Parse JUnit XML test results and correlate them to source functions via naming convention
+5. Compute per-function health scores by joining code quality metrics with test reliability
+6. Extend the production audit with 5 code quality checks (CODE-001 through CODE-005)
+7. Provide a `/code-quality` dashboard page with stats, charts, and drill-down tables
+8. Feed code quality signals into the Innovation Engine for guided refactoring recommendations
+9. Enable pattern-based TDD learning via existing confidence adjustment model (+0.1/-0.2)
+
+---
+
+## 3. Architecture
+
+```
+                    Code Intelligence Pipeline
+          ┌──────────────────────────────────────┐
+          │        code_quality_config.yaml       │
+          │   (thresholds, weights, exclusions)   │
+          └──────────────┬───────────────────────┘
+                         │
+          ┌──────────────┼───────────────────┐
+          ↓              ↓                    ↓
+   AST Analysis    Runtime Feedback    Innovation Engine
+   (code_analyzer)  (runtime_feedback)  (introspective)
+          │              │                    │
+          ↓              ↓                    ↓
+   code_quality_     runtime_          Innovation signals
+   metrics table     feedback table    (code_quality_
+   (append-only)     (append-only)      introspective)
+          │              │                    │
+          └──────┬───────┘                    ↓
+                 ↓                     Pattern Detector
+          Dashboard API                (TDD learning)
+          /api/code-quality/*
+          /code-quality page
+          /prod-audit (CODE-001..005)
+```
+
+### Key Design Principles
+
+- **Read-only, advisory-only** — No component modifies source files (D331)
+- **Append-only storage** — Both tables are time-series, never updated/deleted (D332)
+- **Deterministic scoring** — Maintainability formula uses fixed weights, no probabilistic element (D337)
+- **Air-gap safe** — Python `ast` module and `xml.etree.ElementTree` only, zero external dependencies (D333, D7)
+
+---
+
+## 4. Components
+
+### Component 1: AST Self-Analysis (`tools/analysis/code_analyzer.py`)
+
+**Class `CodeAnalyzer`** with 3 AST visitors for Python:
+- `_PythonComplexityVisitor` — Cyclomatic complexity (branch counting)
+- `_CognitiveComplexityVisitor` — Nesting-aware cognitive complexity
+- `_NestingDepthVisitor` — Maximum nesting depth
+
+Non-Python languages use regex-based branch counting (same pattern as `modular_design_analyzer.py`).
+
+**5 Smell Detectors:**
+| Smell | Threshold | Description |
+|-------|-----------|-------------|
+| `long_function` | >50 LOC | Function body exceeds 50 lines |
+| `deep_nesting` | >4 levels | Control flow nesting exceeds 4 |
+| `high_complexity` | >10 CC | Cyclomatic complexity exceeds 10 |
+| `too_many_params` | >5 params | Function has more than 5 parameters |
+| `god_class` | >10 methods | File contains more than 10 functions |
+
+**Maintainability Score (D337):**
+```
+score = (complexity_weight * complexity_factor
+       + smell_weight * smell_factor
+       + test_weight * test_factor
+       + coupling_weight * coupling_factor
+       + coverage_weight * coverage_factor)
+
+Weights: complexity=0.30, smell_density=0.20, test_health=0.20,
+         coupling=0.15, coverage=0.15
+```
+
+### Component 2: Code Fitness Dashboard
+
+5 production audit checks added to `tools/testing/production_audit.py`:
+
+| ID | Check | Severity | Condition |
+|----|-------|----------|-----------|
+| CODE-001 | Code analyzer syntax | warning | AST parse of code_analyzer.py |
+| CODE-002 | Avg complexity | blocking | Avg CC > 25 |
+| CODE-003 | High complexity % | warning | >5% functions with CC > 15 |
+| CODE-004 | Smell density | warning | >10/KLOC warn, >20 fail |
+| CODE-005 | Maintainability trend | warning | Latest < previous - 0.05 |
+
+Dashboard page at `/code-quality` with:
+- 7-metric stat grid
+- SVG maintainability trend chart
+- Smell distribution horizontal bar chart
+- Top 20 complex functions table
+- Runtime feedback table
+
+### Component 3: Runtime Feedback (`tools/analysis/runtime_feedback.py`)
+
+**Class `RuntimeFeedbackCollector`:**
+- Parses JUnit XML via `xml.etree.ElementTree` (D7)
+- Falls back to pytest stdout regex parsing
+- Maps `test_foo` → `foo` via naming convention (D334)
+- Computes per-function health: `0.40 × complexity_factor + 0.35 × pass_rate + 0.25 × maintainability`
+
+### Component 4: Guided Refactoring & Pattern Learning
+
+**Introspective Analyzer** extended with `analyze_code_quality()`:
+- Cross-references high-complexity functions with low test pass rates
+- Generates innovation signals for guided refactoring
+
+**Pattern Detector** extended with:
+- `seed_code_quality_patterns()` — 4 initial patterns
+- `learn_from_tdd_outcome()` — After TDD cycle, adjusts pattern confidence using existing +0.1/-0.2 model (D336)
+
+---
+
+## 5. Database Tables
+
+### `code_quality_metrics` (append-only)
+Per-function/per-file snapshots: complexity, nesting, LOC, params, smells, maintainability score. Grouped by `scan_id` for trend tracking.
+
+### `runtime_feedback` (append-only)
+Per-test-case results correlated to source functions. Includes pass/fail, duration, error type/message.
+
+---
+
+## 6. Security Gate
+
+```yaml
+code_quality:
+  blocking:
+    - avg_cyclomatic_complexity_exceeds_critical
+  warning:
+    - maintainability_score_declining
+    - high_smell_density
+    - dead_code_exceeds_threshold
+  thresholds:
+    max_avg_complexity: 25
+    min_maintainability_score: 0.40
+    max_smell_density_per_kloc: 20
+    max_dead_code_pct: 10
+```
+
+---
+
+## 7. MCP Tools
+
+3 tools registered in unified gateway:
+- `code_analyze` — Scan directory/file, optionally store metrics
+- `code_quality_report` — Get trend data for project
+- `runtime_feedback_collect` — Parse JUnit XML, store feedback
+
+---
+
+## 8. Architecture Decisions
+
+| ID | Decision | Rationale |
+|----|----------|-----------|
+| D331 | Read-only, advisory-only | Never modifies source files (D110 pattern) |
+| D332 | Append-only time-series tables | D6 audit trail pattern, D131 modularity metrics pattern |
+| D333 | Python AST + regex for others | D13 pattern, same dispatch as modular_design_analyzer.py |
+| D334 | Naming convention test→source mapping | Advisory correlation only, no AST cross-reference needed |
+| D335 | Signals feed existing Innovation Engine | No new pipeline, no autonomous modification |
+| D336 | +0.1/-0.2 confidence model | Reuses existing pattern_detector.py learning model |
+| D337 | Deterministic weighted maintainability | Fixed weights, reproducible, not probabilistic (D21 pattern) |
+
+---
+
+## 9. Testing
+
+```bash
+pytest tests/test_code_analyzer.py -v        # 29 tests
+pytest tests/test_runtime_feedback.py -v     # 22 tests
+pytest tests/test_production_audit.py -v     # 42 tests (includes CODE-001..005)
+```
+
+**Total: 93 tests covering all Phase 52 functionality.**
+
+---
+
+## 10. Files
+
+### New Files (9)
+| File | LOC | Purpose |
+|------|-----|---------|
+| `tools/analysis/__init__.py` | 2 | Package |
+| `tools/analysis/code_analyzer.py` | ~420 | AST self-analysis |
+| `tools/analysis/runtime_feedback.py` | ~260 | Runtime feedback collector |
+| `tools/dashboard/api/code_quality.py` | ~180 | Dashboard API Blueprint |
+| `tools/dashboard/templates/code_quality.html` | ~215 | Dashboard page |
+| `tests/test_code_analyzer.py` | ~320 | 29 tests |
+| `tests/test_runtime_feedback.py` | ~200 | 22 tests |
+| `goals/code_intelligence.md` | ~150 | Goal document |
+| `args/code_quality_config.yaml` | ~60 | Configuration |
+
+### Modified Files (11)
+| File | Change |
+|------|--------|
+| `tools/db/init_icdev_db.py` | +2 CREATE TABLE statements |
+| `tools/testing/production_audit.py` | +5 check functions, 7th category |
+| `tools/innovation/introspective_analyzer.py` | +analyze_code_quality() |
+| `tools/knowledge/pattern_detector.py` | +seed_code_quality_patterns(), +learn_from_tdd_outcome() |
+| `tools/dashboard/app.py` | +/code-quality route, +Blueprint registration |
+| `tools/mcp/tool_registry.py` | +3 tool entries |
+| `tools/mcp/gap_handlers.py` | +3 handler functions |
+| `args/security_gates.yaml` | +code_quality gate |
+| `CLAUDE.md` | +D331-D337, +tables, +commands, +config |
+| `tools/manifest.md` | +Code Intelligence section |
+| `goals/manifest.md` | +Code Intelligence entry |