KArtSell.Aegis/PHASE_3_IMPLEMENTATION_PLAN.md

# Phase 3 Implementation Plan: Sell Decision + Trade Execution

**Date:** 2026-08-07  
**Status:** 📋 PLANNING (Ready for execution)  
**Execution Model:** WBS Optimization (Parallel + Phase 1 concurrent)  
**Compliance:** AGENTS.md v16.0 13/13 criteria  

---

## 📊 PHASE 3 OVERVIEW

### Context
```
Phase 1:  🚀 Shadow Run (autonomous, 50-90 days, data generating)
Phase 2:  ✅ Complete (10 PRs merged, code integrated)
Phase 3:  📋 Ready to plan (use Phase 1 data → decisions → execution)
Phase 4:  🔮 Advanced (post-Phase 1, Gate 2+ prerequisites)
```

### Phase 3 Goals
```
1️⃣  Sell Decision Engine
    → Generate sell signals based on model recommendations
    → Implement approval workflow integration
    → Enforce PBO/DSR validation gates

2️⃣  Trade Execution System
    → Execute approved sell decisions
    → Handle KIS API integration
    → Track execution lifecycle

3️⃣  Portfolio Reconciliation
    → Verify execution vs. approval
    → Update holdings & cost basis
    → Generate reconciliation reports
```

### Key Dependencies
```
Blockers:   Phase 1 must provide OOS/PBO/DSR evidence ✅ (autonomous)
Ready Now:  Phase 2 infrastructure (approval/audit) ✅ (merged)
New Work:   VS-10 (Sell Decision), VS-05+ (advanced features)
```

---

## 🎯 PHASE 3 WORKSTREAMS

### **WORKSTREAM J: VS-10 Sell Decision Engine**

**Owner:** Quant Lead + PM  
**Duration:** 4-5 weeks  
**Start:** 2026-09-05 (after Phase 1 reaches 50% progress)  
**Blocks:** VS-12, VS-13 (downstream)  

#### Deliverables

**J1: Data Contract & Slice Spec**
- **Document:** `VS-10-SLICE_SPEC.md` (300-400 lines)
- **Inputs:** Model recommendations, PBO/DSR scores, OOS validation
- **Outputs:** Sell decision (quantity, timing, exit strategy)
- **State Machine:**
  ```
  PENDING (awaiting Phase 1 evidence)
  ↓
  SIGNAL_GENERATED (model consensus)
  ↓
  PBO_VALIDATED (score check ≥ threshold)
  ↓
  DSR_VALIDATED (ratio check ≥ threshold)
  ↓
  OOS_APPROVED (out-of-sample performance confirmed)
  ↓
  READY_FOR_APPROVAL (meets governance gates)
  ↓
  APPROVED (maker-checker approval from VS-03)
  ↓
  EXECUTED (trade sent to KIS)
  ↓
  CONFIRMED (settlement confirmed)
  ```

**J2: Sell Priority Logic**
- **Immutable Sell Priority:** `HARD_IMPAIRMENT → PORTFOLIO_SURVIVAL → DYNAMIC_PROFIT_FLOOR → CONCENTRATION/LIQUIDITY → OPPORTUNITY_COST → REENTRY_OPTION`
- **Algorithm:** Score-based ranking (fairness + compliance)
- **Output:** Ordered list of candidates for execution

**J3: API Endpoints (3)**
```
POST /sell-decisions
  Input: model_id, threshold_pbo, threshold_dsr
  Output: 201 Created with decision_id

GET /sell-decisions
  Query: status, model_id, execution_date
  Output: Paginated list

POST /sell-decisions/{id}/execute
  Input: approval_id (from VS-03)
  Output: 202 Accepted (job queued)
```

**J4: Database Schema**
```sql
CREATE TABLE sell_decisions (
  id UUID PRIMARY KEY,
  model_id UUID REFERENCES models(id),
  status VARCHAR(50),  -- PENDING, SIGNAL_GENERATED, PBO_VALIDATED, ..., CONFIRMED
  pbo_score DECIMAL(5,4),
  dsr_metric DECIMAL(5,4),
  oos_performance JSONB,
  sell_priority INT,
  target_quantity INT,
  target_price DECIMAL(15,2),
  approval_id UUID REFERENCES approval_proposals(id),
  execution_id UUID,  -- Reference to KIS trade
  published_at TIMESTAMPTZ,
  correlation_id UUID,
  revision INT
);

CREATE TABLE sell_decision_evidence (
  id UUID PRIMARY KEY,
  decision_id UUID REFERENCES sell_decisions(id),
  evidence_type VARCHAR(50),  -- PBO_REPORT, OOS_BACKTEST, DSR_METRIC
  evidence_url TEXT,
  validated_at TIMESTAMPTZ,
  published_at TIMESTAMPTZ,
  correlation_id UUID
);
```

**J5: Handlers & Jobs**
- `GenerateSellDecisionHandler` — Orchestrates scoring + validation
- `ValidatePboHandler` — PBO score gate (≥ 0.65 recommended)
- `ValidateDsrHandler` — DSR ratio gate (≥ 0.015 recommended)
- `ValidateOosHandler` — OOS performance gate (pass/fail)
- `ExecuteSellDecisionJob` — Queues trade via KIS API

**J6: Tests**
- 15+ unit tests (scoring logic, validation gates, priority ranking)
- 8+ integration tests (E2E from signal to approval)
- 3+ contract tests (approval/audit integration)

**J7: Compliance**
- ✅ AGENTS.md 13/13 (SOLID, complexity, audit, necessity, etc.)
- ✅ PIT tracking (published_at, correlation_id, revision)
- ✅ Immutable decisions (INSERT-only, no UPDATE)
- ✅ Evidence linkage (S3 artifacts)

---

### **WORKSTREAM K: VS-12 Trade Execution**

**Owner:** Backend Lead + Trading Ops  
**Duration:** 3-4 weeks  
**Start:** 2026-09-10 (parallel with J, overlapping)  
**Depends On:** J (sell decision approval)  

#### Deliverables

**K1: KIS API Integration**
- **Service:** `KisTradeExecutionService.cs`
- **Methods:**
  ```csharp
  ExecuteTradeAsync(tradeRequest, correlationId)
  GetOrderStatusAsync(orderId)
  CancelOrderAsync(orderId, reason)
  ConfirmSettlementAsync(orderId)
  ```
- **Features:**
  - Connection pooling + retry logic (exponential backoff)
  - Order validation (quantity, price, liquidity checks)
  - Failure classification (transient/permanent/liquidity)

**K2: Trade Lifecycle States**
```
PENDING (awaiting execution)
↓
SUBMITTED (sent to KIS)
↓
ACCEPTED (KIS confirmed receipt)
↓
PARTIAL_FILLED / FILLED (execution progress)
↓
CONFIRMED (settlement confirmed)
↓
RECONCILED (cost basis updated)
```

**K3: API Endpoints (2)**
```
POST /trades
  Input: sell_decision_id, quantity, limit_price
  Output: 202 Accepted with trade_id

GET /trades
  Query: status, decision_id, execution_date
  Output: Paginated list with execution details
```

**K4: Database Schema**
```sql
CREATE TABLE trades (
  id UUID PRIMARY KEY,
  sell_decision_id UUID REFERENCES sell_decisions(id),
  kis_order_id VARCHAR(50),  -- KIS-assigned order ID
  status VARCHAR(50),  -- PENDING, SUBMITTED, ACCEPTED, FILLED, CONFIRMED, RECONCILED
  quantity INT,
  executed_quantity INT,
  unit_price DECIMAL(15,2),
  total_amount DECIMAL(18,2),
  commission DECIMAL(15,2),
  net_proceeds DECIMAL(18,2),
  execution_timestamp TIMESTAMPTZ,
  settlement_timestamp TIMESTAMPTZ,
  error_message TEXT,
  kis_response JSONB,
  published_at TIMESTAMPTZ,
  correlation_id UUID,
  revision INT
);
```

**K5: Handlers & Jobs**
- `SubmitTradeHandler` — Submit to KIS
- `PollTradeStatusJob` — Hangfire polling (q-evaluation queue)
- `ConfirmSettlementHandler` — Mark settlement complete
- `ReconcileTradeHandler` — Update cost basis

**K6: Tests**
- 12+ unit tests (validation, state transitions)
- 8+ integration tests (KIS mock + real DB)
- 3+ failure scenario tests (transient/permanent errors)

**K7: Compliance**
- ✅ AGENTS.md 13/13
- ✅ Idempotent execution (no duplicate trades)
- ✅ Audit trail (all state changes logged)
- ✅ Error classification

---

### **WORKSTREAM L: VS-14 Portfolio Reconciliation**

**Owner:** Data Architecture + Finance  
**Duration:** 2-3 weeks  
**Start:** 2026-09-15 (parallel with K, uses K output)  
**Depends On:** K (trade execution)  

#### Deliverables

**L1: Reconciliation Engine**
- **Algorithm:** Compare approved decisions vs. executed trades
- **Inputs:**
  - Sell decision (approved, PBO/DSR/OOS validated)
  - Trade execution (settled, cost basis confirmed)
  - Holdings (before execution)
- **Outputs:**
  - Holdings updated
  - Cost basis adjusted
  - Reconciliation report (matches/mismatches)

**L2: Mismatch Detection**
- Quantity mismatch (approved vs. executed)
- Price variance (approved limit vs. actual)
- Timing variance (decision date vs. execution date)
- Settlement delay (execution vs. confirmation)

**L3: Cost Basis Update**
- Weighted average cost tracking
- Lot tracking (FIFO/LIFO methods)
- Gain/loss calculation
- Tax lot reporting

**L4: API Endpoints (2)**
```
GET /reconciliation/holdings
  Response: Current portfolio state (updated after trade)

GET /reconciliation/mismatches
  Query: date_range, severity
  Response: Flagged discrepancies for manual review
```

**L5: Database Schema**
```sql
CREATE TABLE holdings (
  id UUID PRIMARY KEY,
  security_id UUID REFERENCES financial_security_master.securities(id),
  quantity INT,
  weighted_avg_cost DECIMAL(15,2),
  total_cost_basis DECIMAL(18,2),
  market_value DECIMAL(18,2),
  unrealized_gain_loss DECIMAL(18,2),
  updated_at TIMESTAMPTZ,
  published_at TIMESTAMPTZ,
  correlation_id UUID,
  revision INT
);

CREATE TABLE reconciliation_logs (
  id UUID PRIMARY KEY,
  trade_id UUID REFERENCES trades(id),
  holding_id UUID REFERENCES holdings(id),
  quantity_before INT,
  quantity_after INT,
  cost_basis_delta DECIMAL(18,2),
  mismatch_detected BOOLEAN,
  mismatch_reason TEXT,
  reconciled_at TIMESTAMPTZ,
  published_at TIMESTAMPTZ,
  correlation_id UUID
);
```

**L6: Tests**
- 10+ unit tests (cost basis, gain/loss calculation)
- 6+ integration tests (reconciliation workflow)
- 3+ scenario tests (edge cases: splits, dividends)

---

## 📈 EXECUTION TIMELINE

### Week 1-2 (2026-09-05 ~ 2026-09-18)
```
J1: VS-10 Spec & Contract Design (parallel)
K1: VS-12 API & KIS Integration (parallel)
L1: VS-14 Design & Algorithm (parallel)

Status: D/E/F design docs, ready for implementation
Phase 1: 50%-75% progress
```

### Week 3-4 (2026-09-19 ~ 2026-10-02)
```
J2-J7: VS-10 Implementation & Tests
K2-K6: VS-12 Implementation & Tests
L2-L5: VS-14 Implementation & Tests

Status: All 3 slices in parallel, 50% code complete
Phase 1: 75%-90% progress
```

### Week 5-6 (2026-10-03 ~ 2026-10-16)
```
J/K/L: Integration testing (cross-slice)
       Phase 1 final results available
       Gate 2 validation begins

Status: All code complete, integration verified
Phase 1: 90-100% (completion), results ready
```

### Week 7+ (2026-10-17+)
```
Phase 1 Complete → Gate 2 Execution
Phase 3 Implementation → Production Deployment (~November)
```

---

## 🎯 WBS OPTIMIZATION STRATEGY

### Parallel Execution (J + K + L Simultaneous)
```
Sequential (Baseline):  J(4w) → K(3w) → L(2w) = 9 weeks
Parallel (Actual):      All 3 simultaneous = 5 weeks
────────────────────────────────────────────────
TIME SAVED:             4 weeks ⏱️

Dependencies:
  J outputs → K inputs (sell decision → trade execution)
  K outputs → L inputs (trade execution → reconciliation)
  
Overlap Strategy:
  Week 1-2: J design, K design, L design (PARALLEL)
  Week 2-3: J → 50%, K start (J unblocks K)
  Week 3-4: J → 100%, K → 50%, L start (K unblocks L)
  Week 4-5: All 3 at 75-100% (overlapping)
  Week 5-6: Integration testing (all done)
```

### Phase 1 Concurrent Execution
```
Phase 1:  🚀 Autonomous (50-90 days, data generating)
Phase 3:  📋 Implementation in parallel (uses accumulated data)

Benefit:
  • No waiting for Phase 1 to complete
  • Infrastructure ready when Phase 1 evidence available
  • Gate 2 validation can begin on Day 75+ (mid-way through Phase 1)
  • Production deployment by November 2026
```

---

## ✅ AGENTS.md v16.0 COMPLIANCE PLAN

### Verification Framework (Apply to J/K/L)

| Criterion | J (Sell Decision) | K (Trade Execution) | L (Reconciliation) |
|-----------|------------------|---------------------|-------------------|
| 1. SOLID | 3 services (scoring, validation, approval) | KIS service + handlers | Reconciliation + reports |
| 2. Complexity | Each <300 lines, readable | Connection pool, retry logic | Calc engine, mismatch detection |
| 3. Audit | correlation_id, PIT tracking | All state changes logged | Cost basis trail |
| 4. Necessity | Grounded in Phase 1 evidence | Spec-before-code ✅ | Portfolio integrity |
| 5. Normalization | 3NF schema, append-only | PIT tracked decisions | Versioned holdings |
| 6. Simplicity | State machine clear | No magic numbers | Algorithm transparent |
| 7. Pattern | Vertical Slice (Services/Handlers/Endpoints/Sql) | Contract-driven | Domain-driven design |
| 8. Guardrails | Validation gates (PBO/DSR/OOS) | Error classification | Mismatch alerts |
| 9. Traceability | Evidence links to S3 | CorrelationId throughout | Audit trail immutable |
| 10. Safety | Idempotent operations | Rollback-safe state | No partial reconciliation |
| 11. Maturity | Spec-before-code ✅ | Data contracts ✅ | Design docs ✅ |
| 12. Right-Way | Formal gates, no shortcuts | KIS official API | Regulatory compliance |
| 13. Debt | No new tech debt | Enables Phase 4 | Tech debt registry |

---

## 📊 RESOURCE ALLOCATION

### Team Assignment (Recommended)

**Workstream J (Sell Decision)** — 3 people, 5 weeks
```
Lead:     Quant Lead (decision logic, PBO/DSR validation)
Backend:  2 engineers (API, database, handlers, tests)
Effort:   ~200 hours
```

**Workstream K (Trade Execution)** — 3 people, 4 weeks
```
Lead:     Backend Lead (KIS integration, error handling)
Trading:  1 operations engineer (KIS API knowledge)
Backend:  1 engineer (handlers, jobs, reconciliation)
Effort:   ~150 hours
```

**Workstream L (Portfolio Reconciliation)** — 2 people, 3 weeks
```
Lead:     Data Architect (reconciliation algorithm)
Finance:  1 engineer (cost basis, gain/loss, reporting)
Effort:   ~100 hours
```

**Total Phase 3 Effort:** ~450 hours (~11 weeks serial, 5 weeks parallel)

---

## 📋 MILESTONE CHECKLIST

### Phase 3 Gates (Pre-Merge)

**J (Sell Decision):**
- [ ] VS-10 SLICE_SPEC complete (Spec-before-code)
- [ ] PBO/DSR/OOS validation gates designed
- [ ] API contracts finalized
- [ ] Database migration validated (fresh/upgrade/re-run)
- [ ] Unit tests: 15/15 PASS
- [ ] Integration tests: 8/8 PASS
- [ ] Architecture tests: SOLID compliance verified
- [ ] No SELECT *, schema-qualified SQL
- [ ] Immutable decisions (INSERT-only)
- [ ] Correlation_id traceability

**K (Trade Execution):**
- [ ] VS-12 SLICE_SPEC complete
- [ ] KIS API contract finalized
- [ ] Error classification (transient/permanent/liquidity)
- [ ] Idempotency key strategy
- [ ] Unit tests: 12/12 PASS
- [ ] Integration tests: 8/8 PASS
- [ ] State machine transitions verified
- [ ] Rollback-safe design confirmed

**L (Portfolio Reconciliation):**
- [ ] VS-14 SLICE_SPEC complete
- [ ] Reconciliation algorithm validated
- [ ] Cost basis calculations verified
- [ ] Unit tests: 10/10 PASS
- [ ] Integration tests: 6/6 PASS
- [ ] Edge cases (splits, dividends) handled
- [ ] Tax lot tracking verified

**Cross-Slice Integration:**
- [ ] J → K flow verified (decision → execution)
- [ ] K → L flow verified (execution → reconciliation)
- [ ] Audit trail (VS-04) integration complete
- [ ] Approval workflow (VS-03) integration complete
- [ ] E2E tests: PASS
- [ ] Gate 2 prerequisite data ready (Phase 1 evidence)

---

## 🎯 SUCCESS CRITERIA

### Code Quality
```
Tests:      48+ (unit/integration/E2E)
Coverage:   ≥80% code coverage
Complexity: All classes <300 lines
Compliance: AGENTS.md 13/13 ✅
Tech Debt:  No new unbounded debt
```

### Business Metrics
```
Sell Decision Accuracy:  PBO/DSR/OOS validation pass rate ≥95%
Trade Execution Rate:    Approved decisions → executed ≥99%
Reconciliation Success:  Mismatches ≤0.1% (normal variance)
SLA Compliance:          Execution latency <1 hour (from approval)
```

### Timeline
```
Week 5-6:    All code merged to main
Week 6-7:    Integration testing & bug fixes
Week 7+:     Production deployment (Gate 2+ validation)
November:    Production live (full automation)
```

---

## 📈 PHASE 3 ROADMAP DIAGRAM

```
Phase 1 (Autonomous)      Phase 2 (Merged)         Phase 3 (Parallel)
─────────────────        ───────────────          ──────────────────
50-90 days               ✅ Complete              J: Sell Decision  
(Data generating)        10 PRs merged            K: Trade Exec     (Parallel)
                                                  L: Reconciliation 
                                                  
                         VS-03 Approval   ──→  J→K (flow)
                         VS-04 Audit      ──→  all J/K/L logged

                                                  ↓ (Week 6)
                                                  Integration tests
                                                  
                                                  ↓ (Week 7)
                                                  Gate 2 validation
                                                  (Phase 1 evidence)
                                                  
                                                  ↓ (Week 8+)
                                                  Production
```

---

## ✅ APPROVAL & SIGN-OFF

**Phase 3 Plan Status:** 📋 Ready for review and team assignment  
**Dependencies:** Phase 1 autonomous (no manual action needed) ✅  
**Readiness:** Phase 2 infrastructure (approval/audit) merged ✅  
**AGENTS.md Compliance:** 13/13 criteria framework ✅  

**Next Steps:**
1. Team review Phase 3 plan
2. Assign teams to J/K/L workstreams
3. Start Phase 3 implementation (2026-09-05)
4. Monitor Phase 1 progress (autonomous)
5. Execute Phase 3 in parallel with Phase 1 completion

---

**Generated:** 2026-08-07  
**Prepared By:** Claude Haiku 4.5 <noreply@anthropic.com>  
**Framework:** WBS Optimization + AGENTS.md v16.0  
**Status:** ✅ READY FOR EXECUTION