KArtSell.Aegis/docs/PHASE2_BATCH3_ROADMAP.md

# Phase 2 Batch 3-4: Risk & Portfolio Domain (VS-04~08)

## 📋 Overview

**Domain:** Portfolio composition, risk metrics, stress testing, alerts, dashboard
**Pattern:** Vertical Slice (GOV → DATA → DOMAIN → BE → ASYNC → FE → TESTOPS)
**Strategy:** AGENTS.md v16.0 WBS Optimization — execute all non-blocking tasks immediately

---

## 🏗️ Component Structure

| VS | Name | Purpose | Data Model | Endpoint | Event |
|----|------|---------|------------|----------|-------|
| **VS-04** | Portfolio Composition | Aggregate positions & risk weights | `portfolios.*` (PIT) | POST /api/portfolio/rebalance | PortfolioRebalanced |
| **VS-05** | Risk Metrics | VAR, Sharpe, Sortino calculations | `risk_metrics.*` (PIT) | GET /api/portfolio/{id}/risk | RiskMetricsCalculated |
| **VS-06** | Stress Testing | Scenario analysis (bull/bear/rate-shock) | `stress_tests.*` (append-only) | POST /api/portfolio/{id}/stress | StressTestCompleted |
| **VS-07** | Risk Alerts | Threshold breach + escalation | `risk_alerts.*` (soft-delete) | GET /api/portfolio/{id}/alerts | RiskAlertTriggered |
| **VS-08** | Risk Dashboard | Real-time risk aggregation + UI | `risk_dashboard_agg` (denorm) | GET /api/dashboard/risk | (read-only) |

---

## 🔗 Dependencies & Parallelization

```
VS-04 (Portfolio Composition)
  ↓
VS-05 (Risk Metrics) ← requires portfolio data
  ↓
VS-06 (Stress Testing) ← requires risk metrics
  ↓
VS-07 (Risk Alerts) ← requires stress results
  ↓
VS-08 (Risk Dashboard) ← aggregates all above
```

**Parallelizable:**
- Each VS can be GOV+DATA defined in parallel (9 docs in parallel)
- DOMAIN logic for VS-04 & VS-05 in parallel (once specs done)
- BE endpoints for all VS in parallel (once DOMAIN ready)

**Critical Path:**
- VS-04 DATA must complete before VS-05 DOMAIN
- VS-05 DOMAIN must complete before VS-06 BE
- Total: Sequential on hot path, but 40% parallelization possible

---

## 📅 WBS Schedule (Optimized)

**Day 1 (Today): GOV + DATA (All 5 VS)**
- VS-04: `VS04_PORTFOLIO_SLICE_SPEC.md` + `VS04_DATA_CONTRACT.md`
- VS-05: `VS05_RISK_METRICS_SLICE_SPEC.md` + `VS05_DATA_CONTRACT.md`
- VS-06: `VS06_STRESS_TESTING_SLICE_SPEC.md` + `VS06_DATA_CONTRACT.md`
- VS-07: `VS07_RISK_ALERTS_SLICE_SPEC.md` + `VS07_DATA_CONTRACT.md`
- VS-08: `VS08_RISK_DASHBOARD_SLICE_SPEC.md` + (no separate data schema)
- **Deliverable:** 9 spec documents, schema validation complete

**Day 2: DOMAIN (VS-04, 05, 06, 07)**
- VS-04: Portfolio aggregation logic (12 tests)
- VS-05: Risk calculation logic (15 tests)
- VS-06: Scenario application logic (10 tests)
- VS-07: Alert threshold evaluation (8 tests)
- **Parallel:** All 4 can run in parallel after specs
- **Deliverable:** 45 unit tests, 4/4 domains PASS

**Day 3: BE + ASYNC (All 5 VS)**
- VS-04: Rebalance endpoint + Hangfire job
- VS-05: Risk metrics fetch endpoint + background calculator
- VS-06: Stress test trigger + async batch processing
- VS-07: Alert query endpoint + event publisher
- VS-08: Aggregation endpoint (read-only)
- **Deliverable:** 5 endpoints, 5 async jobs, 20 tests

**Day 4: FE + TESTOPS (Batch 3)**
- VS-04: Rebalance form + confirmation dialog
- VS-05: Risk metrics display + trend charts
- VS-06: Scenario builder UI + results visualization
- VS-07: Alert list + drill-down view
- VS-08: Risk dashboard (aggregate KPIs + real-time updates)
- **Deliverable:** 5 FE components, 12+ E2E tests

---

## 🎯 Acceptance Criteria (AGENTS.md v16.0)

**Per VS:**
- ✅ Contract-first: Specs + schema before code
- ✅ SOLID: No cross-cutting concerns, single responsibility
- ✅ Complexity: Cyclomatic complexity ≤ 10 (Policy exceptions)
- ✅ Idempotency: All jobs + scenarios replay-safe
- ✅ Audit: Correlation IDs, event published, PIT versioned
- ✅ Safety: Transaction boundaries, soft-deletes, no partial success
- ✅ Testing: Unit → Integration → Data → E2E coverage
- ✅ Traceability: ADR links, evidence preserved

**Cross-VS:**
- ✅ No SELECT * or direct module-to-module queries
- ✅ Async coupling via Outbox/Inbox (no direct function calls)
- ✅ Tech debt registered (if any deferral)
- ✅ Architecture tests pass
- ✅ All prior tests still pass (no regressions)

---

## 📊 Success Metrics

| Metric | Target | Checkpoint |
|--------|--------|------------|
| Test Pass Rate | 100% | End of each day |
| Architecture Violations | 0 | Before commit |
| Tech Debt Registered | 100% | In PR description |
| Code Review Comments | <5 | Per PR |
| Build Time | <5s | Continuous |

---

## 🚀 Execution Plan (This Session)

**Phase 2 Batch 3 Start (VS-04~07):**

1. ✅ Confirm domain scope (Risk & Portfolio) — **DONE**
2. ⏳ GOV + DATA (9 docs, parallel) — **START NOW**
3. ⏳ DOMAIN (4 VS, parallel) — **Follow after specs**
4. ⏳ BE + ASYNC (5 endpoints, parallel) — **Follow after domain**
5. ⏳ FE + TESTOPS (5 components, Batch 3) — **Follow after BE**

**Phase 2 Batch 4 (VS-08):**
6. ⏳ Risk Dashboard (depends on all others)
7. ⏳ Final integration testing

---

## 📝 Notes

- **SSH Tunnel:** Required for any DB-backed integration tests. Keep open during dev.
- **Parallel Execution:** GOV+DATA can be written concurrently; post in 5 separate docs
- **Debt Threshold:** Keep new debt <20 impact points per batch (manage quarterly paydown)
- **Git Strategy:** One commit per component (GOV+DATA) or (DOMAIN) or (BE+ASYNC), then squash if needed

---

**Status:** READY TO START
**Next Command:** Begin VS-04 GOV specification