# Meet Kevin v2 — Paper Trading + Backtest + Strategy UI — Design

> Synthesises the work of two parallel architect agents:
> - `kevin-strategy-design.md` (strategy + paper-trading rules) — Architect A
> - `kevin-backtest-ui-design.md` (backtest + UI surface) — Architect B

## Goal

Translate Meet Kevin's per-mention signals into automated Alpaca paper trades, surface the strategy's performance against a benchmark in a dedicated UI, and prove it works through a backtest before any real money would be considered.

## Premise

A new `kevin_stock_mentions` row is the primary stimulus. Everything else is plumbing. **Long-only on Alpaca paper for v1.**

## Scope summary

| Area | Owner | New / Existing |
|---|---|---|
| Strategy logic (signal → trade) | `shared/strategies/kevin.py` (NEW) | `BaseStrategy` extension |
| Mention → signal bridging | `services/kevin_signal_bridge/` (NEW) | New service container |
| Trade execution | `services/trade_executor/` | EXISTING — re-enable, no behavior change |
| Risk controls | `services/trade_executor/risk_manager.py` | EXISTING — extend in place |
| Backtest engine | `backtester/` | EXISTING — add `KevinMentionAdapter` |
| Metrics | `backtester/metrics.py` | EXISTING — extend `compute_metrics` |
| Backtest API + persistence | `services/api_gateway/routes/meet_kevin_backtest.py` (NEW) + 2 tables | New |
| Strategy UI page | `dashboard/src/pages/meetKevin/Strategy.tsx` (NEW) | New |
| Paper account UI page | `dashboard/src/pages/meetKevin/PaperAccount.tsx` (NEW) | ~50-line clone of `Portfolio.tsx` |

Total new files: ~12. Total modified files: ~6. Estimated implementer time: 6–8 hours across a subagent team.

---

## Architecture

```
Postgres
┌──────────────────────┐
│ kevin_stock_mentions │ ← (v1 watcher writes; unchanged)
└──────────┬───────────┘
           │ poll every 60s
           ▼
┌──────────────────────────────────────────────────────────┐
│ services/kevin_signal_bridge/                       NEW  │
│   - cursor in Redis (kevin:bridge:last_mention_id)       │
│   - applies signal filter (action, conviction, age)      │
│   - aggregates multi-mention boost                       │
│   - checks Redis blocklist + per-day caps                │
│   - calls KevinStrategy.evaluate(mention, snapshot)      │
│   - daily exit-scan job @ 09:35 ET (time-based exits)    │
│   - watches trades:executed for fill confirmations       │
│   - master kill-switch: TRADING_KEVIN_ENABLE_TRADING=off │
└────────────────┬─────────────────────────────────────────┘
                 │ publishes TradeSignal with
                 │ strategy_sources=["kevin:<action>:<conviction>"]
                 ▼
        Redis Stream signals:generated
                 │
                 ▼
┌──────────────────────────────────────────────────────────┐
│ services/trade_executor/                       EXISTING  │
│   - RiskManager.check_risk (extended with new caps)      │
│   - AlpacaBroker.submit_order (BRACKET: stop+take-profit)│
│   - Trade persistence with strategy_name="kevin"         │
│   - publishes trades:executed                            │
└────────────────┬─────────────────────────────────────────┘
                 │
                 ▼
        Alpaca Paper (long-only, BRACKET orders)
                 │
                 ▼
        Redis Stream trades:executed
                 │
                 ▼
        portfolio_sync (existing) — equity curve, positions

Parallel observability path
┌──────────────────────────────────────────────────────────┐
│ services/api_gateway/routes/meet_kevin_backtest.py  NEW  │
│   - POST /backtest/run  → async job, polls Redis status  │
│   - calls backtester/engine.BacktestEngine with          │
│     KevinMentionAdapter(KevinStrategy)                   │
│   - persists final run to kevin_backtest_runs            │
│     + per-trade detail in kevin_backtest_trades          │
│   - meet_kevin_watcher gains a daily post-poll cron      │
│     stage that triggers the scheduled run                │
└──────────────────────────────────────────────────────────┘
```

### Key architectural rule

**One source of truth for strategy behavior: `shared/strategies/kevin.py::KevinStrategy`.**

`KevinStrategy` is a **stand-alone class**, NOT a `BaseStrategy` subclass — the existing `BaseStrategy.evaluate(ticker, market: MarketSnapshot, sentiment)` signature is bar/article-driven and would force the Kevin code to fabricate fake `MarketSnapshot` objects. Instead `KevinStrategy` exposes:

```python
async def evaluate_mention(
    self,
    mention: KevinStockMention,
    account_state: KevinAccountState,
) -> KevinDecision | None
```

Both the live `kevin_signal_bridge` AND the backtest engine call this method directly. The unification guarantee comes from "one class, one method, called by both" — not from an inheritance decoration. This applies to:

- Action filtering (which actions trigger trades)
- Conviction floor
- Position sizing (conviction-weighted)
- Holding period (time_horizon-derived)
- Multi-mention aggregation (latest-wins + conviction boost)
- Long-only treatment (sell/avoid semantics)

The backtest *parameterises* slippage + commission + initial capital (per-run knobs) but **never overrides** strategy logic.

---

## Signal translation rules

A `kevin_stock_mentions` row produces (or cancels) exactly one `TradeSignal` when **all** of:

| Condition | Threshold | Rationale |
|---|---|---|
| `action` ∈ {buy, sell, avoid} | Mandatory | hold/watch never trade — UI-only |
| `conviction` | `>= 0.60` | Kevin makes many low-conviction asides |
| `time_horizon` | not `intraday` | 3h poll cadence can't catch intraday |
| Age of mention | `<= 48h` since `created_at` | Past 48h, thesis is stale; backtest handles older |
| Symbol tradable on Alpaca | `broker.get_asset(symbol).tradable == True` | Skip OTC / foreign / crypto |
| `asset.class_ == 'us_equity'` | Hardcoded | v1: no crypto, no options |

**`time_horizon` → target hold period** (used for time-based exit):

| `time_horizon` | Trading days held |
|---|---|
| `days` | 3 |
| `weeks` | 10 |
| `months` | 45 |
| `long_term` | 90 (re-enter via fresh mention if Kevin re-affirms) |
| `unspecified` | 10 (default to weeks — Kevin's modal horizon) |
| `intraday` | filtered out |

**Long-only direction mapping:**

| Action | Currently held? | Behavior |
|---|---|---|
| `buy` | no | Open at sized target |
| `buy` | yes, below per-ticker cap | Top up to cap |
| `buy` | yes, at cap | No-op |
| `sell` | yes | Emit market SELL for full position |
| `sell` | no | No-op (never short in v1) |
| `avoid` | yes | Emit market SELL (controlled by `AVOID_CLOSES_LONGS=true`) + add Redis blocklist `kevin:blocked:{symbol}` with TTL `AVOID_BLOCKS_DAYS=7` |
| `avoid` | no | Add to blocklist; no trade |

**Note on `avoid` policy:** the close-action and the blocklist are split into two env knobs (`TRADING_KEVIN_AVOID_CLOSES_LONGS`, `TRADING_KEVIN_AVOID_BLOCKS_DAYS`). A subsequent `buy` mention on the same ticker **clears** the blocklist early — "latest mention wins" applies symmetrically.
| `hold` | — | Never trade |
| `watch` | — | Never trade |

---

## Position sizing

Conviction-weighted fixed-fractional:

```
base_pct        = 0.04                                  # 4% of equity for max-conviction
conviction_mult = (conviction - 0.6) / 0.4              # 0.6 → 0.0; 1.0 → 1.0
target_pct      = base_pct * (0.5 + 0.5 * conviction_mult)
target_dollars  = clamp(account.equity * target_pct, MIN_USD, MAX_USD)
qty             = floor(target_dollars / current_price)
```

| Conviction | `target_pct` | $ for $100k equity |
|---|---|---|
| 0.60 | 2.0% | $2,000 |
| 0.80 | 3.0% | $3,000 |
| 1.00 | 4.0% | $4,000 |

**Hard caps:**
- Per-trade floor: $500
- Per-trade ceiling: $5,000 (5% of $100k starting equity)
- Per-ticker total cost basis ceiling: $7,500 (absorbs multi-mention boost)

Rejected Kelly sizing (no historical edge data yet). Revisit after backtest reports per-conviction-bucket hit rates.

---

## Exit logic

Closes on **first** of:

1. **Time-based:** `holding_days` for that mention's `time_horizon` (table above). Daily cron in `kevin_signal_bridge` at 09:35 ET scans open Kevin trades, emits SELL.
2. **Stop-loss:** -8% from entry. Implemented as Alpaca BRACKET order (`order_class=BRACKET, stop_loss=...`). **Requires extending the broker abstraction** — see §"Broker extension" below.
3. **Take-profit:** +20% from entry. Implemented as Alpaca BRACKET order's `take_profit` leg.
4. **Kevin reverses:** new `sell` or `avoid` mention on the same ticker → cancel bracket legs + market SELL.
5. **Manual close:** `POST /api/meet-kevin/positions/{symbol}/close` (sets a `kevin:manual_close:{symbol}` Redis flag the bridge reads).

**Not implemented (deliberate YAGNI):** trailing stops, partial scaling out, end-of-week rebalance.

### Broker extension (required for BRACKET orders)

`AlpacaBroker._build_order_request` currently emits only `MarketOrderRequest`/`LimitOrderRequest`/`StopOrderRequest` (no BRACKET). `OrderRequest` schema in `shared/schemas/trading.py` lacks `take_profit_price` / `stop_loss_price` / `order_class` fields.

Required changes:
- Extend `OrderRequest` with optional `take_profit_price: Decimal | None`, `stop_loss_price: Decimal | None`, `order_class: Literal["simple","bracket"] = "simple"`.
- `_build_order_request` branches on `order_class`: when `bracket`, returns `MarketOrderRequest(order_class=OrderClass.BRACKET, take_profit=TakeProfitRequest(limit_price=...), stop_loss=StopLossRequest(stop_price=...))`.
- Cancellation: `broker.cancel_order` already exists; for Kevin-reverses we cancel the parent bracket which auto-cancels the legs.

---

## Multi-mention aggregation

Kevin mentions NVDA `buy` three times in 48 hours:

- **Latest mention wins** the action + time_horizon (most recent thesis is canonical).
- **Conviction boost:** `effective_conviction = min(1.0, latest.conviction + 0.05 * (extra_mentions_in_48h))`, capped at +0.20 (i.e. 4 extra mentions).
- **One position per ticker per active window.** No 3x position size.
- If the latest is `sell`/`avoid`, earlier `buy`s are dead — exit immediately.

Aggregation is done in `kevin_signal_bridge` (windowed SQL over `kevin_stock_mentions`); `KevinStrategy` itself stays stateless and per-mention.

---

## Risk controls

Extends `services/trade_executor/risk_manager.py::RiskManager.check_risk`. **All hard caps, all blocking, all configurable:**

| Control | Default | Notes |
|---|---|---|
| Max position size per ticker | 7.5% of equity | Per-ticker cap absorbs multi-mention boost |
| Max total long exposure | 60% of equity | Existing `max_total_exposure_pct` |
| Max concurrent positions | 15 | Existing `max_positions` (lowered from 20) |
| Max NEW trades / day | 5 | New Redis counter `kevin:daily_trades:{YYYYMMDD}` (atomic `INCR`) |
| Max NEW $ allocated / day | $15,000 | New Redis sum counter `kevin:daily_alloc:{YYYYMMDD}` (atomic `INCRBY`) |

**Daily counter mechanics:**
- Owner: `kevin_signal_bridge` writes the counters **after** `trades:executed` confirms a fill (consumes the stream).
- Reset: keys have `EXPIRE 172800` (48h) so they self-clean. `RiskManager.check_risk` reads `kevin:daily_trades:{YYYYMMDD using UTC date}` for today.
- Idempotency: counter increment is keyed off `Trade.id`, deduplicated by an `INSERT … ON CONFLICT DO NOTHING` audit row in `kevin_signal_bridge_state`.
| Daily P&L circuit breaker | -3% of equity | Sets `trading:paused=1` until next market open |
| Account drawdown halt | Equity < 80% of starting | Sets `trading:paused=PERMANENT` until manually cleared |
| Per-ticker cooldown after exit | 60 min | Bumped from 30 |
| Sector concentration | NOT enforced v1 | Alpaca asset metadata lacks sector — YAGNI |

The circuit breaker + drawdown halt are new periodic checks running inside `kevin_signal_bridge` (writing `trading:paused` which `RiskManager.check_risk` already honours).

---

## Backtest engine

### Methodology

| Knob | Default | Rationale |
|---|---|---|
| Mention window | `[channel_first_polled_at, run_end)` | Use everything we have |
| Entry fill | next trading session OPEN (T+1) | Avoids look-ahead bias |
| Exit fill | OPEN of `entry_session + holding_days_for_that_mention` | `holding_days` is per-mention from strategy spec |
| Price source | Alpaca daily bars (IEX feed) via `market_data` cache, lazy back-fetch | Same wrapper as existing `routes/backtest.py::_fetch_alpaca_bars` |
| Slippage | 5 bps symmetric | `slippage_pct = 0.0005` |
| Commission | $0 (Alpaca paper) | |
| Initial capital | $100,000 | Match Alpaca paper default |
| Benchmark | SPY buy-and-hold over `[first_mention_at, run_end]` window | |
| Walk-forward vs single-pass | Single-pass | <30 days of data — walk-forward statistically meaningless |
| Dedupe policy | `roll` (latest mention extends exit) | Mirrors live `KevinStrategy` aggregation |

### Backtest implementation: separate mention-driven engine

The existing `BacktestEngine` in `backtester/engine.py` is **bar-driven** (iterates daily bars, evaluates all strategies per tick). The Kevin backtest is **event-driven** (mention → T+1 open entry → time-based exit). Rather than fabricate per-bar evaluations or graft a mention loop onto a bar engine, write a parallel mini-engine:

```
backtester/kevin_backtest.py                              ~150 lines
  - takes (KevinStrategy, list[KevinStockMention], price_loader, params)
  - walks mentions chronologically
  - calls strategy.evaluate_mention() per mention to get KevinDecision
  - simulates fills at T+1 open (entry) and exit_date open (exit)
  - tracks portfolio state, equity curve, trade log
  - emits BacktestResult (reusing existing dataclass)
  - reuses compute_metrics() for headline numbers
```

Keep `BacktestEngine` untouched — the 9 existing strategies still backtest there. `compute_metrics` is the shared utility both engines call.

### Metrics

`backtester/metrics.py::compute_metrics` extended **in place** (no fork) with these additional fields:

| Field | Formula |
|---|---|
| `total_return_pct` | `(final - initial) / initial * 100` |
| `annualized_return_pct` | `(final/initial)^(365.25/days) - 1) * 100` |
| `sharpe_ratio` | `mean(daily_ret) / stddev(daily_ret) * sqrt(252)`, rf=0 |
| `max_drawdown_pct` | `max((peak - trough) / peak)` over equity curve |
| `win_rate_pct` | `wins / closed_trades * 100` |
| `avg_winner_pct` | `mean(pnl_pct where pnl > 0)` |
| `avg_loser_pct` | `mean(pnl_pct where pnl <= 0)` |
| `best_trade` / `worst_trade` | `{symbol, pnl_pct}` |
| `alpha_vs_spy_pct` | `total_return_pct - spy_return_pct` |
| `beta_vs_spy` | `cov(daily_ret, spy_daily_ret) / var(spy_daily_ret)` |

### Execution surface

- **On-demand:** `POST /api/meet-kevin/backtest/run` → 202 `{run_uuid, status: running}`. Async via `asyncio.Task`; Redis stores `kevin:backtest:status:{uuid}` with 24h TTL for the dashboard's 2s poll.
- **Scheduled:** the `meet_kevin_watcher` service gains a post-analysis cron stage that calls the same internal `run_backtest_for_kevin_strategy()` helper. This produces the canonical "latest" run the UI defaults to.
- **Persistence:** final result lives in `kevin_backtest_runs` + `kevin_backtest_trades` (Postgres). Redis is only the in-flight surface.

### Schema additions (1 Alembic migration)

Three new tables (all `uuid` PKs for consistency with `Trade` / `Position` / `Signal`):

```sql
kevin_signal_bridge_state
  id                  uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  mention_id          bigint UNIQUE NOT NULL REFERENCES kevin_stock_mentions(id),
  bridge_status       enum('emitted','skipped_non_tradable','skipped_blocklist',
                           'skipped_caps','deferred','broker_rejected','dry_run') NOT NULL,
  signal_id           uuid REFERENCES signals(id),      -- nullable; null on skip
  trade_id            uuid REFERENCES trades(id),       -- nullable; null until fill
  effective_conviction numeric(4,3),                    -- after multi-mention boost
  decided_at          timestamptz NOT NULL DEFAULT now(),
  notes               text,
  INDEX (mention_id),
  INDEX (bridge_status, decided_at DESC);

kevin_backtest_runs
  id                  uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  run_uuid            uuid UNIQUE NOT NULL,
  started_at          timestamptz NOT NULL DEFAULT now(),
  finished_at         timestamptz,
  status              enum('running','completed','failed') NOT NULL,
  trigger_source      enum('manual','scheduled') NOT NULL DEFAULT 'manual',
  params_json         jsonb NOT NULL,
  metrics_json        jsonb,
  equity_curve_json   jsonb,
  benchmark_curve_json jsonb,
  error_message       text,
  INDEX (started_at DESC),
  INDEX (status, started_at DESC);

kevin_backtest_trades
  id                  uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  run_id              uuid NOT NULL REFERENCES kevin_backtest_runs(id) ON DELETE CASCADE,
  symbol              varchar(16) NOT NULL,
  source_mention_id   bigint REFERENCES kevin_stock_mentions(id),
  entry_at            timestamptz NOT NULL,
  entry_price         numeric(12,4) NOT NULL,
  exit_at             timestamptz,
  exit_price          numeric(12,4),
  qty                 numeric(14,4) NOT NULL,
  pnl_usd             numeric(14,4),
  pnl_pct             numeric(8,4),
  holding_days_actual int,
  INDEX (run_id, symbol),
  INDEX (run_id, entry_at);
```

**Not reusing the existing `trades` table** — those are real fills; backtest trades are hypothetical history; mixing them breaks consumer assumptions.

---

## UI surface

Two new pages under the existing `/meet-kevin/*` group.

### Filtering paper-account trades to "kevin" — strategy_id FK

`Trade` has `strategy_id` (UUID FK to `strategies` table) NOT `strategy_name`. To filter paper-account UI:

1. Migration **seeds** a row in `strategies`: `('kevin', 'Meet Kevin Strategy', current_weight=1.0, active=true)` — known UUID generated and pinned as a constant in code.
2. `kevin_signal_bridge` sets `strategy_id` to this UUID on every emitted `TradeSignal`.
3. `trade_executor` already passes `signal.strategy_id` through to `Trade.strategy_id` during persistence.
4. The paper-account API filters: `WHERE trades.strategy_id = $kevin_strategy_uuid`.

### `/meet-kevin/strategy` — backtest + tracking (PRIMARY)

```
┌───────────────────────────────────────────────────────────────────────────────┐
│ Meet Kevin / Strategy                              [Run backtest ▾]  [Refresh] │
├──────────────────┬──────────────────┬──────────────────┬──────────────────────┤
│ Strategy Equity  │ Total P&L        │ vs SPY (alpha)   │ Win rate / # trades  │
│ $103,420  +3.4%  │ +$3,420 (+3.4%)  │ +1.8%            │ 64.3% · 14 trades    │
└──────────────────┴──────────────────┴──────────────────┴──────────────────────┘
┌───────────────────────────────────────────────────────────────────────────────┐
│ Equity curve — Strategy (blue)  ·  SPY benchmark (gray)                       │
│ [recharts/lightweight-charts dual-line]                                       │
│                              [1W] [2W] [1M] [ALL]                             │
└───────────────────────────────────────────────────────────────────────────────┘
┌───────────────────────────────────────────────────────────────────────────────┐
│ Ticker scorecard                                              [filter: ____]  │
├──────┬────────┬──────┬─────────────┬─────────┬─────────┬─────────┬───────────┤
│ Sym  │ Action │ Conv │ Entry date  │ Live $  │ Unreal. │ Realized│ Status    │
│ NVDA │ BUY    │ 0.85 │ 2026-05-15  │ $182.40 │ +$420   │   —     │ HOLDING   │
│ INTC │ BUY    │ 0.70 │ 2026-05-14  │  $24.10 │   —     │  +$85   │ CLOSED    │
│ AMD  │ HOLD   │ 0.40 │ —           │ $145.20 │   —     │   —     │ WATCH ONLY│
│ ...  │        │      │             │         │         │         │           │
└──────┴────────┴──────┴─────────────┴─────────┴─────────┴─────────┴───────────┘
   ▲ click row → drill-down panel below (per-mention list + per-trade P&L + price chart with mention markers)

┌───────────────────────────────────────────────────────────────────────────────┐
│ Backtest run history (last 5)                                                 │
│ [table: run_uuid_short, started_at, holding_days, return, sharpe, status]     │
└───────────────────────────────────────────────────────────────────────────────┘
```

**Live prices** come from the `market_data` table (Alpaca-cached daily closes), never from the dashboard's direct Alpaca calls. The API gateway is the single source.

**Empty state** (mention count < 5 or span < 2 trading days): show "Insufficient mention history" but keep the ticker table visible.

### `/meet-kevin/paper-account` — real paper-trading P&L

A separate page, ~50 lines, near-clone of `Portfolio.tsx` with the data filtered to `Trade.strategy_name = "kevin"`. Reuses `EquityCurve`, `MetricsRow`, `PositionsTable` as-is.

Justification for two pages, not one: `/strategy` is "what if" (backtest history + signal universe); `/paper-account` is "what actually happened" (real fills, real positions). Overloading muddles the lenses.

### Sidebar nav

Adds two entries under the existing "Meet Kevin" group:
- Strategy (after Stocks)
- Paper Account

### Dual-line chart component (NEW, not contingent)

`EquityCurve.tsx` renders exactly one `LineSeries`. The strategy-vs-SPY chart needs two series with a legend. **Definitely create a new component** `dashboard/src/components/meetKevin/StrategyVsBenchmarkCurve.tsx` (~80 lines, lightweight-charts) — don't extend `EquityCurve` in place (it's used by other pages).

---

## API surface

All under existing `/api/meet-kevin/*` prefix. New router file `routes/meet_kevin_backtest.py` (keeps `meet_kevin.py` from ballooning).

```
POST /api/meet-kevin/backtest/run                          → 202 {run_uuid, status}
GET  /api/meet-kevin/backtest/runs?limit=20                → run list (headline metrics)
GET  /api/meet-kevin/backtest/runs/{run_uuid}              → full result
GET  /api/meet-kevin/backtest/latest                       → latest scheduled (or most recent)

GET  /api/meet-kevin/strategy/tickers                      → scorecard table data
GET  /api/meet-kevin/strategy/equity-curve?from=&to=&include_benchmark=spy
GET  /api/meet-kevin/strategy/performance                  → headline metrics

POST /api/meet-kevin/positions/{symbol}/close              → manual close (sets Redis flag)
```

Frontend `dashboard/src/api/meetKevin.ts` gains 7 methods using the same axios `client`.

---

## Code locations

```
NEW
  shared/strategies/kevin.py                                ~120 lines (KevinStrategy)
  services/kevin_signal_bridge/__init__.py
  services/kevin_signal_bridge/config.py
  services/kevin_signal_bridge/main.py                      ~250 lines (async loop + exit-scan cron)
  services/kevin_signal_bridge/aggregator.py                multi-mention window logic
  services/api_gateway/routes/meet_kevin_backtest.py        backtest routes
  backtester/adapters/kevin.py                              KevinMentionAdapter(BaseStrategy)
  shared/market_data/alpaca_fetch.py                        extracted from existing routes/backtest.py
  shared/models/trading.py                                  +KevinTrade audit-link table
  shared/models/meet_kevin.py                               +KevinBacktestRun, KevinBacktestTrade models
  alembic/versions/<ts>_kevin_backtest_tables.py            migration
  dashboard/src/pages/meetKevin/Strategy.tsx
  dashboard/src/pages/meetKevin/PaperAccount.tsx            ~50 lines
  dashboard/src/components/meetKevin/TickerScorecardTable.tsx
  dashboard/src/components/meetKevin/BacktestRunHistory.tsx
  dashboard/src/components/meetKevin/StrategyVsBenchmarkCurve.tsx  if EquityCurve extension is messy

MODIFIED
  services/trade_executor/risk_manager.py                   +daily_trade_count, +daily_alloc_sum, +drawdown halt
  services/trade_executor/config.py                         +new env knobs
  shared/strategies/__init__.py                             export KevinStrategy
  backtester/metrics.py                                     extend compute_metrics with alpha, beta, winners, losers
  dashboard/src/App.tsx                                     +2 routes
  dashboard/src/components/Layout.tsx                       +2 sidebar entries
  dashboard/src/api/meetKevin.ts                            +7 methods

INFRA (separately owned commit)
  infra/stacks/trading-bot/main.tf                          +kevin_signal_bridge + trade_executor containers
```

---

## Config (env vars, all `TRADING_` prefix)

```
# Signal translation
TRADING_KEVIN_MIN_CONVICTION                 = 0.60
TRADING_KEVIN_MAX_MENTION_AGE_HOURS          = 48
TRADING_KEVIN_HOLD_DAYS                      = '{"days":3,"weeks":10,"months":45,"long_term":90,"unspecified":10}'

# Sizing
TRADING_KEVIN_BASE_POSITION_PCT              = 0.04
TRADING_KEVIN_MIN_TRADE_USD                  = 500
TRADING_KEVIN_MAX_TRADE_USD                  = 5000
TRADING_KEVIN_MAX_PER_TICKER_USD             = 7500

# Exits
TRADING_KEVIN_STOP_LOSS_PCT                  = 0.08
TRADING_KEVIN_TAKE_PROFIT_PCT                = 0.20
TRADING_KEVIN_AVOID_BLOCKLIST_DAYS           = 7

# Aggregation
TRADING_KEVIN_MENTION_BOOST_PER_REPEAT       = 0.05
TRADING_KEVIN_MAX_MENTION_BOOST              = 0.20

# Risk
TRADING_KEVIN_MAX_POSITION_PCT               = 0.075
TRADING_KEVIN_DAILY_TRADE_CAP                = 5
TRADING_KEVIN_DAILY_ALLOC_CAP_USD            = 15000
TRADING_KEVIN_DAILY_LOSS_CIRCUIT_PCT         = 0.03
TRADING_KEVIN_EQUITY_DRAWDOWN_HALT_PCT       = 0.80

# Backtest
TRADING_KEVIN_BACKTEST_SLIPPAGE_PCT          = 0.0005
TRADING_KEVIN_BACKTEST_INITIAL_CAPITAL       = 100000
TRADING_KEVIN_BACKTEST_DAILY_CRON            = "30 16 * * 1-5"   # 4:30pm ET post-close

# Bridge plumbing
TRADING_KEVIN_BRIDGE_POLL_INTERVAL_SECONDS   = 60
TRADING_KEVIN_BRIDGE_EXIT_SCAN_CRON          = "35 9 * * 1-5"     # 9:35 ET market open
TRADING_KEVIN_ENABLE_TRADING                 = "false"            # MASTER KILL-SWITCH — default OFF
```

**Master kill-switch: `TRADING_KEVIN_ENABLE_TRADING=false` by default.** Bridge writes audit rows but never publishes to `signals:generated`. Flip to `true` only after the backtest looks sane.

---

## Edge cases

| Case | Handling |
|---|---|
| Symbol not tradable on Alpaca | `kevin_signal_bridge_state.bridge_status='skipped_non_tradable'` |
| Crypto / OTC / pink sheet | Filtered by `asset.class_ == 'us_equity'` |
| Conviction = 0 | Filtered by 0.60 floor |
| `time_horizon='unspecified'` | Default to 10 trading days |
| Mention created after market close | Re-queued with `bridge_status='deferred'`; next morning's poll picks up if still <48h |
| Alpaca 5xx | `submit_order` returns `OrderStatus.REJECTED`; bridge logs to `kevin_signal_bridge_state` |
| Partial fill | BRACKET order's `filled_avg_price` is used; stop/TP legs attach to filled qty |
| Same mention processed twice | Redis cursor + `INSERT…ON CONFLICT DO NOTHING` audit |
| Kevin reverses while stop-loss order is open | Cancel bracket legs via `broker.cancel_order`, then market SELL |
| Backtest: ticker has no `market_data` rows | Lazy back-fetch from Alpaca for `[entry-1d, end+1d]`; if Alpaca returns nothing, mark trade `skipped` and exclude from denominators |
| Backtest: <5 mentions OR <2 trading-day span | API returns 400 `insufficient_history` |
| Backtest: weekend/holiday mention | Entry shifts to next trading session open |
| Backtest: SPY price gap | Forward-fill from previous trading day |
| Backtest >60s | Status remains `running`; dashboard keeps polling. Watchdog kills at 5min, marks `failed` |

---

## Testing strategy

Mirrors v1's bar (404 tests, 1 behavior per test, no internal mocking of own code):

```
tests/strategies/test_kevin_strategy.py                      ~25 tests
  - per-action signal generation (buy/sell/hold/watch/avoid × held/not-held)
  - conviction threshold filtering
  - mention age filtering
  - time_horizon → holding_days mapping
  - non-tradable symbol skip
  - blocklist hit short-circuits LONG
tests/services/kevin_signal_bridge/test_main.py              ~15 tests
  - cursor advances, dedupe via ON CONFLICT
  - multi-mention aggregation (latest wins, conviction boost capped)
  - daily cap counter increments + resets at UTC midnight
  - master kill-switch suppresses publish
  - exit-scan emits SELL for elapsed holds
tests/services/kevin_signal_bridge/test_aggregator.py        ~10 tests
tests/backtester/test_kevin_adapter.py                       ~15 tests
  - happy path: 3 mentions → 3 backtest trades with correct entry/exit
  - dedupe roll: 2nd buy on held ticker extends exit
  - SPY benchmark math (alpha/beta)
  - extended metrics correctness (winners, losers, best, worst)
tests/api_gateway/routes/test_meet_kevin_backtest.py         ~8 tests
  - POST /backtest/run returns 202 with run_uuid
  - GET /backtest/runs/{uuid} returns full result
  - GET /strategy/tickers shapes correctly
  - insufficient_history 400
tests/integration/test_kevin_e2e_paper.py  [@integration]    ~3 tests
  - full pipeline against docker-compose Postgres + Redis, mocked Alpaca

Manual QA
  - dashboard /meet-kevin/strategy renders backtest + ticker table
  - dashboard /meet-kevin/paper-account renders Kevin-only positions
```

Target: ~76 new unit + integration tests.

---

## Phasing (3 phases, staged)

Adjusted after challenger review — Phase A was leaking live-state into the ticker scorecard (which expects HOLDING positions). Merged A+B into Phase 1.

1. **Phase 1 — Strategy + backtest + bridge (audit-only).** Land `KevinStrategy` (standalone), `backtester/kevin_backtest.py`, all 3 new tables, backtest API routes, `kevin_signal_bridge` service. Bridge runs with `TRADING_KEVIN_ENABLE_TRADING=false` — writes `kevin_signal_bridge_state` audit rows showing what it WOULD trade, but never publishes to `signals:generated`. `/meet-kevin/strategy` page shows backtest history + a ticker scorecard with "WOULD-TRADE" status badges (no live positions yet). User reviews the bridge's decisions against the backtest before flipping the switch.
2. **Phase 2 — Trade executor re-enabled, kill-switch ON.** Add `trade_executor` container back to the K8s Pod. Extend `OrderRequest`/`AlpacaBroker` for BRACKET orders. Seed the `kevin` row in `strategies`. Flip `TRADING_KEVIN_ENABLE_TRADING=true`. Live paper trades begin. Ticker scorecard now shows real HOLDING/CLOSED rows.
3. **Phase 3 — Paper-account UI.** Land `/meet-kevin/paper-account` page (Kevin-strategy-only slice of `Portfolio.tsx` filtered by `strategy_id`).

Each phase is independently deployable. User reviews after each.

---

## Out of scope (intentional)

- Real money (live brokerage account)
- Short selling
- Options
- Crypto
- Multi-account allocation
- Per-mention attribution analytics ("high-conviction-only" filter view)
- CSV export of trades
- Strategy parameter sweeps in the UI (grid search via `scripts/` for now)
- "What-if" UI for tweaking conviction thresholds — the live strategy owns that
- Trailing stops
- End-of-week rebalances
- Sector concentration limits

---

## Success criteria

- Backtest runs against the current 63+ mentions and produces a coherent equity curve + metrics card
- The strategy page renders the ticker scorecard with live prices, action chips, and conviction bars
- After flipping the kill-switch, at least one paper trade executes via Alpaca within 60s of a new Kevin mention that passes the filters
- `/meet-kevin/paper-account` shows the Kevin-attributed equity curve diverging from the unified `/portfolio` view
- All hard-cap risk controls fire correctly in tests (verified by integration test that synthesises a 5-mention burst)

---

## Open questions for the user

1. **Phasing:** ship Phase 1 → 2 → 3 with review checkpoints, or hand all three to one big subagent push?
2. **Initial paper capital:** $100k Alpaca default — or override to a smaller number ($10k?) for less abstract dollar signs?
3. **`avoid` policy split:** the design splits into `AVOID_CLOSES_LONGS` (default `true`) + `AVOID_BLOCKS_DAYS` (default `7`). Subsequent `buy` clears the blocklist. Acceptable?
4. **`/meet-kevin/paper-account` vs reusing `/portfolio`:** two pages (Kevin slice) or one with a Kevin filter?

Defaults if no override: stage all 3 phases, $100k, split-knob avoid, two pages.