# Unified Trading Intelligence Framework — v1 Blueprint

**Status:** Draft 2 (2026-05-15) — architectural spec for the existing TR Sports Academy platform; not a parallel system
**Owner:** James
**Hub-role:** Doctrine layer — composes the existing 13 Properties into a coherent strategy/scoring/optimization theory. Does not introduce new surfaces; does not redefine any property.
**This doc is the architectural reference for:** [trsportsacademy.com/system/](https://trsportsacademy.com/system/) (= `/system/index.html` here)

**Adjacent canonical docs:**
- [index.html](index.html) — the 13-Property hub (production: `trsportsacademy.com/system/`)
- [strategy-schema-v1.md](strategy-schema-v1.md) — current canonical entry schema
- [strategy-schema-v1_1-draft.md](strategy-schema-v1_1-draft.md) — promoted live-eval extensions (`schema_version: 2`)
- [strategies.json](strategies.json) — registry (9 strategies)
- [DECISIONS-streaming.md](DECISIONS-streaming.md) — fills/streaming architecture (Einstein WebApp → SSE)

> **Read first:** `project_system_contract.md` (memory) — single-source-of-truth rules for the 5 properties. Nothing in this doc redefines a property; it composes existing ones into a coherent operating system.

---

## Part −1 — Anchor to canonical doctrine

This framework extends — does **not replace** — these production facts:

**The mental model (verbatim from `/system/`):** "spine, cockpit, lenses"
- **Spine** (green): PostgreSQL `trsports_tradingjournal_dev` — owns trades, alerts, journal, users. If the spine dies, everything dies.
- **Cockpit** (orange): Accountability HUD — daily landing, enforces rules across 6 traders.
- **Lens** (blue): every analytical view onto the spine. If a lens dies, you rebuild it in a weekend.

**The trader lifecycle (verbatim, left-to-right):**
1. **Strategy Library** — "what am I trading?"
2. **Playbooks** — "how do I teach this?"
3. **Morning Game Plan** — "plan today?"
4. **Accountability HUD** — "obeying the rules?"
5. **Scorecards** — "how did I execute?"
6. **Monthly Reports** — "what's the trend?"
7. **Param Surface** — "which works best?"

**The 5 non-negotiable rules (Fix-It-Once Contract):**
1. Single source of truth per concept (no page computes its own version).
2. All timestamps in America/New_York timezone.
3. All identities resolve through one `account_id → user_id → trader_name` function.
4. Every generator is idempotent with declared provenance (`generator_version`, `source_tables`, `row_counts`).
5. Pre-publish chart validation (non-zero rows, ET timestamps, axis alignment, session deltas).

**Canonical family taxonomy (`/strategies/` page filter — LIVE 2026-04-30):**
- VWAP / Pullback
- Counter-trend
- Level Breakout
- Event-Driven
- Gap Fade

Everything below maps into these existing structures. Where this doc proposes a NEW field, type, or table, it is explicitly flagged "v1.2 candidate" or "P1/P2/P3" — it does not silently displace anything in production.

---

## Part 0 — Operating Principles (the doctrine layer)

Six principles that govern every decision below. If a later choice contradicts one of these, the choice is wrong.

| # | Principle | Implication |
|---|---|---|
| 1 | **Setup ≠ Strategy ≠ System.** A *setup* is a pattern on a chart. A *strategy* is a setup + entry + stop + target + management rules. A *system* is a strategy + an environment in which it has edge + position sizing + portfolio constraints. | The current registry encodes strategies. The system layer (when to use which strategy) is still implicit in the trader's head. **That gap is the highest-leverage thing to externalize.** |
| 2 | **Price is the truth, context decides the trade.** Indicators are compressions of price. Two strategies firing on the same price action diverge because their *environment gates* differ. | Environment classification is a first-class primitive, not an afterthought. The broken regime classifier is not a bug — it is a load-bearing wall that's currently collapsed. |
| 3 | **AVWAP is the institutional fair-value layer; SD bands are the intraday execution layer; Volume Profile is the acceptance layer.** They answer different questions: *who is in control since when*, *where do they execute*, *what price levels are accepted*. | Stop comparing them. Compose them. See Part 4. |
| 4 | **Every quantifiable variable is a candidate field. Every field is a candidate optimization parameter. Every parameter is a candidate scorecard metric.** But not every variable should become all three — overfitting risk grows multiplicatively. | Variable promotion is gated: variable → field (when persisted) → parameter (when optimized) → metric (when graded against). Each step requires explicit justification. |
| 5 | **Empirical edge dominates theoretical elegance.** A backtested PF of 1.67 from the Param Surface DB wins over a "book default" with no data. But empirical edge is only valid within the regime it was measured in. | All edge claims carry a regime attribution. "PF 1.67 in rotation" ≠ "PF 1.67 always". |
| 6 | **The accountability loop closes the system.** Without Setup A → Execute B → Review C → Optimize D → back to Setup A', the system devolves into discretion with extra steps. | Every component below has a feedback edge into the trader's review loop. If a component has no review loop, it is decoration. |

---

## Part 1 — The Architecture, Two Orthogonal Views

The platform has TWO valid decompositions. They answer different questions. Both are needed.

### 1.A View by ownership — Spine / Cockpit / Lens (canonical, production)

This is the model on `/system/`. It answers: **"if X breaks, what dies with it?"**

```
                                  ┌────────────────────────────────────────┐
                                  │  COCKPITS (daily-driver UIs)           │
                                  │  • Accountability HUD v2               │
                                  │  • Risk Manager HUD                    │
                                  │  • Live Classifier HUD                 │
                                  │  • Daily Stop tool                     │
                                  └────────────────┬───────────────────────┘
                                                   │ reads
┌──────────────────────┐                           ▼
│  SPINE               │ ←──── all facts ─── ┌─────────────────────────────┐
│  PostgreSQL          │ ◄─── written by ─── │  LENSES (analytical views)  │
│  trsports_           │ ───── read by ───►  │  • Scorecards               │
│  tradingjournal_dev  │                     │  • Monthly Reports          │
│                      │                     │  • Param Surface            │
│  Owns:               │                     │  • Playbooks                │
│   • trades           │                     │  • Backtests + Walk-Forward │
│   • alerts           │                     │  • MGP                      │
│   • journal          │                     │  • Strategy Library         │
│   • users            │                     │  • MTF VP Scanner           │
└──────────────────────┘                     │  • User Strategy Upload     │
                                             └─────────────────────────────┘
```

If a lens dies, you rebuild it in a weekend. If a cockpit dies, the trader works blind for a day. If the spine dies, everything dies. **This framework adds nothing to the spine, nothing to the cockpits, and only one new lens (the Unified-Framework lens, which is this doc).**

### 1.B View by data flow — Substrate → Primitives → Strategy → Environment → Decision

This is a different cut, useful for reasoning about *what flows through the system*. Not in conflict with 1.A — it sits underneath it.

```mermaid
graph TB
    L5["DECISION & ACCOUNTABILITY<br/>(maps to: Cockpits + Lifecycle steps 4-7)"]
    L4["ENVIRONMENT<br/>(maps to: MGP breadth + Live Classifier env tags)"]
    L3["STRATEGY LIBRARY<br/>(maps to: /strategies/ page + strategies.json + playbooks/)"]
    L2["PRIMITIVES<br/>(maps to: AVWAP + VWAP+SD bands + VP + MTF Trend Matrix + MA stack)"]
    L1["SUBSTRATE<br/>(maps to: the SPINE — trades, alerts, journal, indicator_alerts)"]
    L1 --> L2 --> L3 --> L4 --> L5
    L5 -.review.-> L3
    L5 -.regime calibration.-> L4
```

| Flow layer | Production residence | Maturity | Gap |
|---|---|---|---|
| **Substrate** | Spine (PostgreSQL) + TV/KTI/Liberator feeds | Mature | None |
| **Primitives** | Indicator code + Strategy Bar + MTF Trend Matrix module | Partial | **AVWAP not a first-class primitive; MTF VP scanner exists but not wired to evaluator** |
| **Strategy Library** | `/strategies/` page (5-family taxonomy LIVE 2026-04-30) + `strategies.json` (9 entries) + `/playbooks/` | Active | **`/strategies/` family filter (5 values) ≠ `strategies.json` `family` field (4 values: mean-reversion, trend, fade, off-book). Presentation/data layer mismatch.** |
| **Environment** | MGP breadth section + Live Classifier HUD (14 symbols) + classifier-divergence dashboard | Broken | **Regime classifier returns 100% rotation; blocks trend strategies; three "Off-Book" definitions in conflict** |
| **Decision & Accountability** | The 7-step lifecycle: Strategy Library → Playbooks → MGP → HUD → Scorecards → Reports → Param Surface | Mature | **Edge-by-environment matrix doesn't exist as a table; strategy selection by environment is implicit** |

**Thesis:** Spine + Cockpits are mature production. Primitives, Environment classifier, and the edge-by-env matrix are the three load-bearing missing pieces. Build those and every existing surface gets sharper without any of them moving.

---

## Part 2 — Universal Strategy DNA

Behind the 15 archetypes (Part 3) sit a small number of universal components that compose every strategy. This is the "shared building blocks" James asked for.

### 2.1 The 12 components

Every strategy is a vector across these 12 axes. Most strategies score on 4-7 of them; only a few engage all 12.

| # | Component | What it measures | Primitive(s) used | Field in schema |
|---|---|---|---|---|
| 1 | **Location** | Where price sits relative to a reference plane | AVWAP, SD bands, prior swing levels, VP nodes | `band_range`, `level_hold`, **`avwap_position`** (proposed) |
| 2 | **Trend** | Direction + magnitude of price drift across timeframes | MA stack, AVWAP slope, MTF Trend Matrix (Points/Slope/Period) | `band_slope_threshold`, **`avwap_slope`** (proposed), **`mtf_trend_score`** (proposed) |
| 3 | **Compression** | Range contraction / volatility compression | ATR percentile, Bollinger width, **AVWAP Pinch (Shannon Ch.5)** | **`avwap_pinch`** (proposed), `band_slope_threshold` |
| 4 | **Expansion** | Range release after compression | Bar range vs ATR, gap vs ADR | **`expansion_thrust`** (proposed) |
| 5 | **Momentum** | Rate of change in price/volume | RSI, MACD, vol-of-vol, time-elapsed-to-level | (none yet — proposed `momentum_score`) |
| 6 | **Participation** | How many names / sectors agree | A/D, % above 20/50/200 MA, sector breadth | **none — Environment Engine gap** |
| 7 | **Volume Behavior** | Cumulative + per-bar volume vs expectation | Vol/ADV, vol regime, prints vs auction quality | `volume_above`, MTF VP confluence |
| 8 | **Volatility** | Realized + implied vol context | ATR, IV rank, vol-of-vol | (none yet) |
| 9 | **Liquidity** | Spread + depth + impact | Tape (book microstructure) | (none yet — option for L1+) |
| 10 | **Acceptance/Rejection** | Did price stay at a level (VP node) or fail | Volume profile, MFE/MAE at level | MTF VP scanner (not yet wired) |
| 11 | **Timeframe Continuity** | Do multiple TFs agree on direction | MTF Trend Matrix (6-TF × 4-tier) | `mtf_trend.py` (live on scorecards) |
| 12 | **Catalyst Quality** | News / earnings / Fed / VK proximity | News skill, MGP tape read, VK ingest | (planned, not in evaluator) |

### 2.2 Which matter most — and which are redundant

**Top-tier (must be in every strategy gate):** Location, Trend, Timeframe Continuity, Volume Behavior. These are the "is this set up at all?" filters.

**Mid-tier (modify quality, not feasibility):** Momentum, Compression/Expansion, Catalyst Quality, Acceptance/Rejection. These move grade A↔B↔C without rejecting the setup.

**Lower-tier (situational):** Participation, Volatility regime, Liquidity. Matter at portfolio scale and at extremes; ignorable mid-day in normal regime.

**Redundancy traps to avoid:**
- **Trend on the same TF as Timeframe Continuity** — collapsing both into one input double-counts. The schema already separates them (`band_slope_threshold` for the entry TF; MTF for cross-TF). Keep them separate.
- **MA stack + AVWAP slope** — they correlate ~0.8 on most stocks. Use AVWAP slope for *event-relative* trend; MA stack for *time-relative* trend. They diverge most usefully right after high-volume events (the AVWAP "knows" earlier).
- **Volume profile + SD bands** — both encode "where price has been". VP is the *distribution*; bands are the *2σ envelope*. Use VP to find HVN/LVN; use bands to size the entry zone.

### 2.3 The component interaction matrix

Some component combinations multiply; others cancel.

| Combination | Effect | Example |
|---|---|---|
| Trend + Timeframe Continuity (aligned) | **Multiplicative** edge | All 6 MTF tiers green → trend-trade is 2× as likely to deliver R |
| Compression + Volume drying up | **Multiplicative** edge | Bollinger squeeze + below-avg volume → expansion thrust expected |
| Location (at AVWAP) + Acceptance (HVN) | **Multiplicative** edge | Pullback to AVWAP at a value node = high-conviction support |
| Momentum (overbought RSI) + Trend (strong up) | **Cancelling** in retail framings, **multiplicative** in trend-following | RSI 75 in a markup stage is a feature, not a sell signal |
| Participation (weak breadth) + Trend (strong individual) | **Warning** flag | Single-stock strength in weak tape = lower expected R, faster exits |

The schema needs to express "X *modifies* Y", not just "X required". v1.2 candidate: `modifier_rules[]` array. See Part 6.

---

## Part 3 — Unified Strategy Taxonomy (mapped into the canonical 5 families)

**Canonical families (from `/strategies/` page filter, LIVE 2026-04-30):**
1. **VWAP / Pullback**
2. **Counter-trend**
3. **Level Breakout**
4. **Event-Driven**
5. **Gap Fade**

The registry (`strategies.json`) currently tags strategies with a different `family` field — `mean-reversion / trend / fade / off-book` — which **does not match** the page filter taxonomy. That's a real data/presentation mismatch (Part 12.1, item 5). The reconciliation:

| `strategies.json` `family` value | Maps to page family |
|---|---|
| `mean-reversion` (td-vwap-{long,short}) | **Counter-trend** |
| `trend` (vwap-pull-in-{long,short}, trend-trade-{long,short}) | **VWAP / Pullback** |
| `fade` (backside-scalp-short, backside-long-long) | **Counter-trend** (structural variant) OR a new family **"Structural Fade"** — depends on James's intent |
| `off-book` (sentinel) | (none — sentinel) |

**Decision needed (cheap, paper-only):** is "fade" the same family as "Counter-trend", or should the page filter add a 6th family "Structural Fade"? Recommend the latter — Back$ide is a structurally distinct setup mechanism (LB3 break + structural-stop) from a flat-band Counter-trend rotation. *Two-minute task: add the filter on `/strategies/`, set `family` in `strategies.json` to the matching string.*

### 3.1 Archetypes — what setups live in each family

These are *archetypes*, not strategies. An archetype is a recurring pattern; a strategy is an archetype + entry + stop + target + management. Multiple strategies can express one archetype with different parameters (e.g. `td-vwap-long` and a future `range-rotation-long` are both Counter-trend rotation archetypes, distinguished by what defines the range).

Below: each archetype slotted into the canonical 5-family taxonomy.

```
VWAP / PULLBACK
  ├── VWAP-Pull-In (entry VWAP→-1 SD in fanning bands)            ✅ vwap-pull-in-{long,short}
  ├── Trend-Trade-Pullback (MA pullback in trending tape)         ✅ trend-trade-{long,short} [⛔ regime classifier]
  ├── Markup-Anticipation (Stage 1→2 transition, 5-signal gate)   ❌ NEW — Shannon Appx A + Ch.6/7
  ├── AVWAP-Cross-Purchase (cross AVWAP from prior swing high)    ❌ Shannon Ch.7 p121
  ├── AVWAP-Reclaim (bar closes back across any lost AVWAP)       ❌ Shannon Ch.7 — generic reclaim
  ├── AVWAP-Handoff (anchor to new HL/LH as trend matures)        ❌ Shannon Ch.6 — "layering"
  ├── Multi-Day-AVWAP Continuation (day-2/day-3 entry technique)  ❌ Shannon Ch.8
  └── Continuation-Gap Entry (running gap mid-trend)              ❌ Shannon Ch.9

COUNTER-TREND
  ├── VWAP-Rotation (flat bands, -1↔+1 SD)                  ✅ td-vwap-{long,short}
  ├── Range-Rotation (HVN→HVN inside a defined range)       🟡 partial — MTF VP scanner not wired
  ├── Time-of-Day Mean Reversion (lunch fade, pre-FOMC)     ❌ not in registry
  └── (proposed split) STRUCTURAL FADE family ──────────────────────────────────────
        ├── Back$ide-Scalp (LB3 break + structural stop)    ✅ backside-scalp-short, backside-long-long
        └── Liquidity-Vacuum / Stop-Run                     ❌ not in registry

LEVEL BREAKOUT
  ├── AVWAP-Pinch Breakout (Shannon Ch.5, compression release) ❌ not in registry
  ├── Range-Break + VP-Vacuum (LVN above breakout)           ❌ MTF VP not wired
  └── PDH/PDL Break with retest                              ❌ not in registry

EVENT-DRIVEN
  ├── Earnings Gap Continuation (anchor from gap)            ❌ not in registry
  ├── Short-Squeeze Reversal (Shannon Ch.10)                 ❌ not in registry
  ├── News-Catalyst Continuation                             ❌ requires news taxonomy
  └── IPO-AVWAP Trade (Shannon Ch.11)                        ❌ not in registry

GAP FADE
  ├── Gap-and-Go (gap holds AVWAP-from-open)                 ❌ Shannon Ch.9
  ├── Gap-Fade (failed gap, AVWAP rejection)                 ❌ Shannon Ch.9
  └── Pre-Market High/Low Fade                               ❌ not in registry
```

**Coverage:** 5 archetypes have registry entries (td-vwap mirror, vwap-pull-in mirror, trend-trade mirror, backside-scalp, backside-long). ~13 archetypes are mapped to families but not yet encoded. AVWAP-anchored archetypes (Shannon Ch.5/6/7/8/9/11) are the largest single block of unimplemented family members.

### 3.2 Archetype definitions — one-line spec for each

| Archetype | Family | Canonical question | Required env |
|---|---|---|---|
| VWAP-Pull-In | VWAP/Pullback | Is trend pulling back into VWAP→-1 SD zone? | Trend, fanning bands |
| Trend-Trade-Pullback | VWAP/Pullback | Is price pulling back to a structural MA in a trending tape? | Trend confirmed |
| **Markup-Anticipation** | **VWAP/Pullback** | **Are 4+ of 5 Stage 1→2 transition signals confirmed?** | **Stage 1→2 transition** |
| **AVWAP-Cross-Purchase** | **VWAP/Pullback** | **Did price cross AVWAP from a prior swing high (long) / low (short)?** | **Markup or decline confirmed** |
| AVWAP-Reclaim | VWAP/Pullback | Did price reclaim any meaningful AVWAP after losing it? | Any stage transition |
| AVWAP-Handoff | VWAP/Pullback | Trend layer N+1: new HL/LH formed above original anchor? | Markup or decline |
| Multi-Day-AVWAP | VWAP/Pullback | Is the 2/3/N-day AVWAP guiding continuation? | Multi-day trend |
| **Continuation-Gap** | **VWAP/Pullback** | **Mid-trend gap with catalyst holding AVWAP?** | **Established trend + earnings/news** |
| VWAP-Rotation | Counter-trend | Are bands flat enough to rotate -1↔+1 SD? | Rotation, low ATR |
| Range-Rotation | Counter-trend | Are HVN-HVN bounds wide enough to fade? | Rotation, defined range |
| Time-of-Day MR | Counter-trend | Is this a known mean-reverting window? | Rotation + window |
| Back$ide-Scalp | Structural Fade* | Is range broken to extremes with structural failure? | Trend exhaustion |
| Liquidity-Vacuum | Structural Fade* | Is there a stop-cluster + thin book? | News/event-driven |
| AVWAP-Pinch Breakout | Level Breakout | Are multiple AVWAPs converging within X SD? | Compression → expansion |
| Range+VP-Vacuum | Level Breakout | Is there LVN above the breakout? | Breakout-friendly |
| PDH/PDL Break Retest | Level Breakout | Did PDH/PDL break with retest hold? | Trending day |
| Earnings Gap Cont. | Event-Driven | Anchor from earnings gap holding? | Earnings day + |
| Short-Squeeze | Event-Driven | High SI + price reclaiming key AVWAP? | Forced-buy regime |
| News-Catalyst Cont. | Event-Driven | Material news + trend continuation? | News-of-day |
| IPO-AVWAP | Event-Driven | Stock holding/rejecting AVWAP-from-IPO? | New issue (≤180 days) |
| Gap-and-Go | Gap Fade | Is gap holding AVWAP-from-gap-open? | Gap day |
| Gap-Fade | Gap Fade | Did the gap fail to hold AVWAP? | Failed-gap day |
| Pre-Market H/L Fade | Gap Fade | Pre-market level failing post-open? | Premarket-set range |

\* = proposed new family. See decision needed above.

### 3.3 Archetype × Environment edge matrix (the missing piece)

This is the **single highest-leverage table to populate**. Each cell is a per-archetype expected R-multiple, conditional on environment. Today it doesn't exist; the trader holds it in head. Externalizing it lets:
- The Live Classifier HUD recommend strategies before entry
- The Scorecard mark trades as "wrong tool for the environment"
- The Param Surface focus optimization search on high-edge cells only

```
                       │ Rotation │ Trend-Up │ Trend-Dn │ Compression │ Expansion │ Risk-Off │
───────────────────────┼──────────┼──────────┼──────────┼─────────────┼───────────┼──────────┤
VWAP-Rotation          │  green   │   amber  │   amber  │   green     │   red     │  amber   │
Range-Rotation         │  green   │   red    │   red    │   green     │   red     │   ?      │
VWAP-Pull-In           │   red    │   green  │   green  │   amber     │  amber    │  amber   │
Trend-Trade-Pullback   │   red    │   green  │   green  │   red       │  green    │   red    │
AVWAP-Reclaim          │   amber  │   green  │   amber  │   amber     │  green    │   ?      │
AVWAP-Pinch Breakout   │   amber  │   amber  │   amber  │   green     │  green    │   ?      │
Back$ide-Scalp         │   red    │   amber  │   amber  │   red       │  green    │  green   │
... (fill remainder per archetype × regime cell)
```

Status today: **all cells empty**. v1.2 schema candidate: a new `edge_by_environment` table (canonical, per Fix-It-Once rule #1), auto-populated nightly by joining `main.journal` to a new `main.env_classifications` table. Lens to render on `/system/edge-matrix.html` or as a panel on `/strategies/`.

---

## Part 4 — AVWAP / VWAP / Volume Profile Unified Lens

This is the deepest architectural question James asked. Answer in one phrase: **L-T-L lens** — *Location, Trend, Liquidity*. Each of the three tools answers exactly one of those questions, and combining all three is the unifying framework.

### 4.1 The three tools answer three different questions

| Tool | Question it answers | Time horizon it speaks to | Strength | Weakness |
|---|---|---|---|---|
| **AVWAP (Shannon)** | *Who has been in control since this event?* | Event-anchored (IPO, earnings, gap, swing high/low, YTD, QTD) | Objective, institution-aligned, time-invariant once anchored | Anchor selection is subjective; many AVWAPs clutter |
| **VWAP + SD bands (Trader Dale / Fashionably Late)** | *Where will price execute against today's mean?* | Intraday only (resets each session) | Precise execution zones, fits param-surface optimization | Loses meaning past the close; not multi-day |
| **Volume Profile** | *Which prices were accepted vs rejected?* | Any range, but typically session or composite | Shows real auction value, finds HVN/LVN | Needs a defined range; lagging by definition |

**The integration insight:** They are NOT competing indicators of the same thing. They are three orthogonal lenses on price.

- AVWAP says **"institutions are above their fair value since the IPO"** → strategic bias.
- VWAP bands say **"today's mean is X; -1 SD is Y; bands are fanning"** → tactical execution.
- VP says **"$140 is an HVN (acceptance), $144 is an LVN (vacuum above)"** → location quality.

### 4.2 Where Brian Shannon, Trader Dale, and Fashionably Late align — and differ

| Topic | Shannon (AVWAP) | Dale (VWAP+bands) | Fashionably Late (VWAP-band variants) |
|---|---|---|---|
| Reference plane | Event-anchored VWAP | Session VWAP + flat ±1/±2/±3 SD | Session VWAP + same bands |
| Primary edge | "Who is in control since [event]" | Rotation between ±1 SD in flat regime | Trend continuation entries inside fanning bands |
| Stop logic | Below prior swing or prior AVWAP | -2 SD (LB3) for rotation | Param-surface optimized: -2 SD best per Param Surface DB |
| Target logic | Next AVWAP, prior pivot, or trail | +1 SD for rotation | Param-surface: 4 SD optimal for pull-in |
| Trend definition | AVWAP slope + 4-stage Weinstein structure | Band fanning (slope-threshold) | Same as Dale (regime classifier output) |
| Multi-timeframe | Min 3 TFs; uses Table B-7 (5-DMA equivalence) | Single intraday | Lives in MTF Trend Matrix (6-TF × 4-tier) on scorecards |
| Compression signal | **AVWAP Pinch** (multiple AVWAPs converge) | Flat bands | Flat bands + low ATR |
| New-trend signal | **Handoff** (anchor to new pivot in trend) | Bands fanning | Regime flip rotation → trend |

**Key alignments:**
1. All three treat **slope** as a control signal. Shannon: slope of AVWAP. Dale: band slope (fanning vs flat). Fashionably Late: regime classifier reads band slope.
2. All three respect **MTF continuity**. Shannon explicitly (Appendix B-7 equivalence table). Dale implicitly (regime persists across TF). Fashionably Late through the MTF Trend Matrix.
3. All three end up at **structural levels** — Shannon's prior pivots, Dale's range high/low, Fashionably Late's "no major overhead resistance" gate.

**Key differences (the real edge opportunities):**

1. **Shannon's edge is multi-day; Dale/Fashionably Late's edge is intraday.** Shannon's IPO anchor, gap anchor, earnings anchor live for weeks. Dale's session VWAP dies at 4pm. Combining them gives you a multi-day setup + intraday execution.

2. **Shannon explicitly handles re-anchoring (Handoff).** Dale assumes today's VWAP is the reference; Shannon shifts the anchor as new significant events occur. **Implication:** the current schema has no `avwap_handoff` primitive — every multi-day trend trade is implicitly using the wrong anchor by day 2.

3. **Shannon explicitly handles the Pinch.** Dale's flat-bands regime is a *single-tool* compression signal. Shannon's Pinch is *multi-tool* — multiple AVWAPs from different anchors converging. The Pinch breakout has a different expected R than a flat-bands-only breakout because it implicates more historical participants. **Implication:** C1 (AVWAP-Pinch Breakout) is a strict superset of a Dale-style breakout; it's a higher-edge archetype.

4. **Shannon doesn't optimize stops/targets parametrically.** Dale uses fixed -2/+1 SD; Fashionably Late uses Param Surface (4 SD target empirical). Shannon uses structural stops (prior pivot). **Implication:** the param surface methodology should extend to AVWAP-based strategies — but the parameter is "which AVWAP to use as stop" not "how many SDs". A different optimization shape.

### 4.2.5 Markup Anticipation — the Stage 1→2 Transition Framework (Shannon's deeper material)

This subsection added in Draft 2.2 after a closer read of Shannon's Appx A (Four Stages), Ch.6 (Handoff/Layering), Ch.7 (Pullbacks/Breakouts), and Ch.8 (Multi-Day). Markup anticipation is one of James's existing frameworks; Shannon adds operational specifics that promote it from a discretionary read to a quantifiable setup.

**The Four Stages (Shannon Appx A, verbatim doctrine):**

| Stage | Definition | Stop-placement / posture | Identifiable when? |
|---|---|---|---|
| **1 Accumulation** | Sideways after a drop; buyers gaining control from sellers | AVOID for trend traders | **Only in retrospect**, AFTER Stage 2 starts |
| **2 Markup** | Uptrend (HH + HL); "innocent until proven guilty" | GO LONG; trade with the trend | While it's happening |
| **3 Distribution** | Sideways after a run-up; sellers overwhelming | AVOID for trend traders | **Only in retrospect**, AFTER Stage 4 starts |
| **4 Decline** | Downtrend (LH + LL); "guilty until proven innocent" | SHORT or stand aside | While it's happening |

Critical implication: **Stages 1 and 3 are unobservable while they're happening.** "Markup anticipation" therefore is not "I see Stage 1 and I'm waiting for Stage 2" — it's *"I see signals that suggest Stage 2 has already started and Stage 1 just ended, retrospectively."* This is a meaningful reframe — it means the setup is **transition detection**, not **state detection**.

**The 5 confirming signals of a Stage 1→2 transition** (synthesized from Shannon's text):

1. **Reclaim of descending AVWAP** — price closes back above the previously-falling AVWAP from the Stage 1 anchor (Ch.7 "AVWAP Cross Purchase")
2. **Slope of relevant AVWAP rolls flat → positive** (Ch.2, p55: "the slope is more important than position above/below")
3. **AVWAP Cross of prior swing high's anchor** — definitive: "the average buyer from that point is now profitable" (Ch.7, p121)
4. **First Handoff fires** — a new HL forms above the original Stage 1 anchor, and a new AVWAP anchored there starts rising (Ch.6 "layering" concept)
5. **Volume confirmation** — at minimum, above-average; ideally a breakaway gap with catalyst (Ch.9 "Breakaway Gaps")

When 4 of 5 confirm: high-conviction markup setup. The current Live Classifier HUD doesn't score against any of these. **Each is a candidate schema field/type.**

**"Layering" as trend-maturity depth (Ch.6, p107):**

> "When we have several Handoff points on the chart, it looks like there are different 'layers' of trend to measure, which is why we can also refer to an AVWAP Handoff as layering."

The current strategy registry has no notion of *which leg of the trend* a setup is in. Treating leg 1 (first Handoff confirms markup) the same as leg 3 (third Handoff = trend maturity) discards real edge information — leg 1 trades have multi-month potential; leg 3 trades are short-leash continuation. **Proposed field:** `trend_layer_depth: 1|2|3|N` on each trade — number of Handoffs since the Stage 1→2 transition.

**Time correction vs Price correction (Appx A, p171-172):**

> "A time correction is a stronger candidate for a trend to continue higher than a price correction. The lack of a deeper price pullback in a time correction indicates a continued strong bid for shares."

Two consolidations after the same up-move are NOT the same setup:
- **Time correction** (sideways/flat range) → stronger trend, stronger continuation odds
- **Price correction** (deeper pullback) → still valid, but lower conviction

**Proposed quality indicator type:** `correction_type` (values: `time` / `price` / `mixed`), computed from range-width and depth-below-prior-high over the pullback.

**"Most recent and relevant HL/LH" stop type (Ch.6, Ch.7, Ch.8 — appears repeatedly as canonical):**

> "Place the stop below the most recent and relevant higher-low... If it breaks that low, the emergent trend has failed because the definition of the uptrend no longer exists."

The current `stop_variants` types are `sd_band` and `structural`. Shannon's "most recent and relevant HL" is a **third stop type** — it's structural (anchored to a price pivot) but not arbitrary like back$ide's "$0.02 above range_high" — it's *defined by the trend itself*. If the HL breaks, the trend is over — exit. **Proposed type:** `most_recent_swing` with `lookback_bars` and `min_relevance_filter` (only consider HLs that lasted ≥ N bars).

**AVWAP Cross Purchase — a NAMED archetype (Ch.7, p121):**

This is currently lumped into B3 "AVWAP-Reclaim" in the Part 3 taxonomy, but Shannon treats it as a discrete technique with its own metrics:
- 19% better entry price than a Breakout buy (his example)
- Tighter stop possible (below the pullback low, not below the prior breakout level)
- Definitive control-signal: "average buyer from that point is now profitable"

**Recommend:** keep "AVWAP-Reclaim" and "AVWAP Cross Purchase" as **two distinct archetypes** within VWAP/Pullback:
- **AVWAP-Reclaim** = bar closes back across an AVWAP that was previously lost. Generic reclaim.
- **AVWAP Cross Purchase** = price specifically crosses an AVWAP anchored at a *prior swing high* (for longs) or *prior swing low* (for shorts). Stricter; explicitly a Stage 1→2 transition signal.

**"Where has it come from?" — compression quality (Ch.7, p119):**

> "Riskier breakouts typically emerge after the stock has made a large percentage prior move... Narrow price ranges produce higher quality breakouts."

Quality indicator that already partly exists conceptually (the Pinch is the extreme version), but isn't formalized. **Proposed quality indicator:** `range_compression` = (ATR of last N bars) / (ATR percentile over prior 6 months). Lower compression ratio → higher-quality breakout candidate.

### 4.3 The unified framework: composing all three

A single high-quality setup uses all three lenses. Example: a B3 (AVWAP-Reclaim) long entry.

```
LOCATION (AVWAP lens — Shannon):
  - Price closed back above the YTD AVWAP and the post-earnings-gap AVWAP within 2 days
  - Both AVWAPs slope flat→positive
  - Pinch forming (two AVWAPs within 0.3% of each other)

TREND (multi-tool — Dale + MTF):
  - Daily MTF trend score: 7/12 (mild bull)
  - 65-min trend: positive slope
  - Session VWAP bands fanning up (regime: trend)
  - 9 EMA / 20 EMA / 50 SMA stacking bullishly

LIQUIDITY (VP lens):
  - Entry zone is HVN from last 3 sessions (acceptance)
  - Overhead is LVN to the next prior swing high (vacuum — fast move when broken)
  - Below entry: thick HVN (defended floor)

EXECUTION (Dale/Param-Surface lens):
  - Entry: pullback to VWAP→-0.5 SD
  - Stop: LB3 (-2 SD) — empirical winner from param surface
  - Target1: +2 SD; Target2: 4 SD (param surface optimal); Target3: prior swing
  - Management: scale half at +2 SD, trail rest at +1 SD
```

Each lens scores the trade independently. The **Setup Quality Score** is a weighted sum of the three lens scores, with the multi-lens-confluence multiplier when all three agree:

```
Setup Quality = w_L · score_L + w_T · score_T + w_Liq · score_Liq + λ · confluence
where confluence ∈ {0, 1, 2, 3} = count of lenses scoring ≥ 0.7
```

This is the v1.2 schema candidate `setup_quality_components[]`.

### 4.4 Concrete AVWAP primitives to add to the evaluator catalog

The current Type Catalog (21 types) has no AVWAP-specific types. Proposed v1.2 additions:

| New type | Inputs | Used in | Semantics |
|---|---|---|---|
| `avwap_position` | `anchor_id`, `side` (above/below), `tolerance_sd` | validation, quality | Price is above/below the named AVWAP |
| `avwap_slope` | `anchor_id`, `direction` (positive/negative/flat), `min_abs_slope` | validation, quality | AVWAP slope direction + magnitude (Shannon p55) |
| `avwap_reclaim` | `anchor_id`, `lookback_bars` | invalidation (event), trigger | Bar closed back across AVWAP after being on the other side |
| `avwap_cross_from_swing` | `swing_type` (high/low), `min_swing_age_bars`, `min_swing_size_pct` | trigger, quality | Price crossed AVWAP anchored at a *qualifying* prior swing — Shannon Ch.7 "AVWAP Cross Purchase" — strict subset of `avwap_reclaim` |
| `avwap_test_count` | `anchor_id`, `lookback_bars`, `max_count` | quality | Level tested ≤N times (Shannon p70: "more tests = more likely to fail") |
| `avwap_pinch` | `anchor_ids[]`, `max_spread_sd` | quality, trigger | Multiple AVWAPs converged within X SD (Shannon Ch.5) |
| `avwap_handoff_eligible` | `anchor_id`, `min_bars_since_anchor`, `min_R_from_anchor` | trigger | Conditions met to re-anchor to a new pivot (Shannon Ch.6) |
| `stage_transition_signals` | `from_stage` (1/3), `to_stage` (2/4), `min_signals` (default 4) | validation, quality | Count of Stage transition signals confirmed (Shannon Appx A + Ch.6/7) — for Markup-Anticipation archetype |
| `correction_type` | `expected` (time/price/mixed), `lookback_bars`, `range_threshold_pct` | quality | Is the recent consolidation a time correction (bullish) or price correction (less bullish)? Shannon Appx A p171 |
| `trend_layer_depth` | `min_depth`, `max_depth` | quality | Number of Handoffs since Stage transition. Leg-1 trades > leg-3 trades for R potential |
| `mtf_trend_score_above` | `min_score`, `tier` | validation, quality | MTF Trend Matrix score ≥ threshold on a tier |
| `vp_node_proximity` | `node_type` (HVN/LVN), `max_distance_sd` | quality | Nearby acceptance (HVN) or rejection (LVN) node |
| `range_compression` | `lookback_bars`, `atr_percentile_max` | quality | "Where has it come from?" — recent ATR vs 6mo percentile. Lower = better breakout candidate (Shannon Ch.7 p119) |
| `breadth_above` | `metric` (advance_decline / pct_above_50ma / mcclellan), `min_value` | validation (env gate), quality | Breadth metric exceeds threshold |
| `participation_score` | `min_score` | validation (env gate) | Combined participation score above threshold |

**New stop-variant type (also v1.2 candidate):**

| New stop type | Inputs | Semantics |
|---|---|---|
| `most_recent_swing` | `side` (HL for long / LH for short), `lookback_bars`, `min_relevance_filter` (min bars the swing held) | Stop placed below the most recent and relevant higher-low (long) or above lower-high (short). Shannon's canonical trend-continuation stop (Ch.6, Ch.7, Ch.8 — appears repeatedly). The trend definition itself: if this breaks, "the emergent trend has failed" — Shannon Ch.7 p119. Distinct from `structural` (which is arbitrary like back$ide's "$0.02 above range_high") and `sd_band` (which doesn't reference price structure). |

A separate registry — `avwap_anchors.json` — defines which anchors are tracked for each symbol. Anchor categories:

```yaml
anchors:
  # Time-based (every symbol)
  - ytd                  # year-to-date
  - qtd                  # quarter-to-date
  - mtd                  # month-to-date
  - wtd                  # week-to-date

  # Event-based (per symbol)
  - last_earnings_gap    # most recent earnings open gap
  - prior_earnings_gap   # one before
  - last_swing_high
  - last_swing_low
  - ipo                  # for newer issues
  - last_news_event      # if material news in last N days

  # Index-relative (per symbol)
  - last_spy_swing_high  # AVWAP from SPY's prior swing — measures the symbol's behavior since the tape's last pivot
```

This is a new registry, distinct from `strategies.json`. Per the System Contract: single source of truth — anchors live in `avwap_anchors.json`, strategies reference them by `anchor_id`.

---

## Part 5 — Market Environment Engine

The biggest *unbuilt* piece of the system. Without it, L3 strategies can't gate properly; with it, the entire library becomes context-aware.

### 5.1 Six environment dimensions

Every moment in time has 6 environment coordinates. Strategies declare which coordinates they require.

| Dimension | Values | Source | Update cadence |
|---|---|---|---|
| **Regime** | `rotation` / `trend-up` / `trend-down` / `compression` / `expansion` / `unknown` | Per-symbol band-slope classifier (fix the broken one) + Pinch detector | Per bar |
| **Breadth** | `risk-on` / `risk-off` / `mixed` | A/D line, % above 50/200 MA, McClellan — derive from Liberator or roll-up | Per session |
| **Participation** | `broad` / `narrow` / `thin` | Sector breadth + volume across leaders | Per session |
| **Volatility** | `low` / `normal` / `elevated` / `crisis` | VIX, ATR percentile, realized vol | Per session + intraday |
| **Sentiment** | `complacent` / `neutral` / `fear` | Put/Call, AAII, VK tone | Per session |
| **Calendar** | `pre-FOMC` / `OPEX-week` / `earnings-day` / `holiday-thin` / `normal` | Event calendar + earnings | Per session |

### 5.2 The regime classifier rebuild

**Current state:** classifier returns ROTATION for 452/452 trades (per memory). This is the single largest blocker — `trend-trade-long`/`short` are unevaluatable until fixed.

**Root cause hypothesis (untested):**
- The HUD modal uses a band-blind JS heuristic (`strategies-fuzzy.js`)
- The Python `classify_v2.py` uses something different
- Three meanings of "Off-Book" coexist
- The Pine reference indicator at `trading\indicators\src\indicators\TraderDale_VWAP.pine` has its own regime logic
- These four sources disagree

**Fix proposal:**
1. **Pick one canonical regime function.** Make it Python (testable, deterministic). All other surfaces (JS HUD, Pine, classifier-divergence dashboard) call it via API or are regenerated from its output.
2. **Specify the regime function inputs explicitly:**
   ```
   regime(symbol, asof_ts) -> {regime, confidence, evidence}
     inputs:
       - last 20 bars of OHLCV on the active TF
       - band slope (rate of change of ±1 SD) over last 10 bars
       - bar range relative to ATR(20)
       - distance of price from VWAP in SD
       - (optional) AVWAP Pinch detector: are 2+ event-anchored AVWAPs within 0.3% spread?
   ```
3. **Calibrate on historical labeled data.** Pull 30 days of labeled trades from the cockpit, run candidate functions, pick the one that doesn't return ROTATION 100% of the time. Confusion matrix vs human-labeled regime is the acceptance test.

This is on the implementation queue at P1.

### 5.3 Breadth — concrete next step

Per [DECISIONS-streaming.md](DECISIONS-streaming.md), breadth is the "Ned Davis indicators" section that's been deferred behind the fills path. The plan:

1. Run `kti liberator datasets --all` and filter for breadth-named sets
2. If a breadth dataset exists in Liberator → nightly query → `alerts_tradingview.breadth_daily`
3. If not → roll up from `price-daily` over a fixed universe (S&P 1500 tractable, NYSE-composite if needed)
4. Compute: A/D line, A/D ratio, McClellan Osc (19/39-EMA of A/D ratio), % above 50/200 MA, NYSE up-vol vs down-vol, new highs/lows

Once persisted, the env engine reads `breadth_daily` for the current session and exposes `env.breadth` to evaluator gates.

### 5.4 Strategy gating against environment (concrete schema change)

Today the schema has `gating.regime_required`. v1.2 candidate: `gating.environment[]` — an array of multi-dimensional gates.

```json
"gating": {
  "environment": [
    { "dimension": "regime", "values": ["trend-up", "expansion"], "required": true },
    { "dimension": "breadth", "values": ["risk-on", "mixed"], "required": true },
    { "dimension": "volatility", "values": ["normal", "elevated"], "required": false, "modifier": "downgrade_one" }
  ]
}
```

When breadth says risk-off, B-family (trend) strategies auto-downgrade or auto-disable in the HUD recommender.

---

## Part 6 — Quantifiable Variables → Schema → Optimization

James asked for variables broken out per strategy type. Here is the universal field catalog. Every variable has a single canonical promotion path: **measure → field → parameter → metric**.

### 6.1 Universal field catalog (entry-time)

| Category | Variable | Type | Persisted | Optimized | Scorecard? |
|---|---|---|---|---|---|
| **Entry** | entry_price | float | ✅ | — | — |
|  | entry_time_et | timestamp | ✅ | — | — |
|  | entry_extension_sd | float | ✅ | ⚠️ candidate | ✅ |
|  | entry_method | enum | ✅ | ✅ (which method works in which env) | ✅ |
|  | entry_avwap_position | dict of {anchor: above/below/at} | ⚠️ proposed | — | ✅ |
|  | entry_vp_node | enum (HVN/LVN/in-range/at-edge) | ⚠️ proposed | — | ✅ |
| **Stop** | stop_id | str (ref to stop_variants) | ✅ | ✅ (already param-surfaced for pull-in) | ✅ |
|  | stop_distance_R | float | ✅ | — | ✅ |
|  | stop_type | enum (sd_band / structural / avwap) | ✅ | ⚠️ optimization candidate | — |
| **Target** | target_id | str | ✅ | ✅ | ✅ |
|  | target_distance_R | float | ✅ | — | ✅ |
|  | rr_planned | float | ✅ | — | ✅ |
| **Trend** | mtf_trend_score | int (0-12) | ⚠️ injected on scorecards, not persisted as field | ⚠️ correlation candidate | ✅ |
|  | band_slope_at_entry | float | ⚠️ proposed | ⚠️ candidate | ✅ |
|  | avwap_slope_at_entry | dict per anchor | ⚠️ proposed | — | ✅ |
| **Momentum** | rsi_at_entry | float | ⚠️ proposed | — | ✅ |
|  | bars_since_last_pivot | int | ⚠️ proposed | — | ✅ |
| **Volume** | volume_vs_adv | float | ⚠️ proposed | — | ✅ |
|  | cumulative_session_volume | float | ⚠️ proposed | — | — |
| **Volatility** | atr_percentile | float | ⚠️ proposed | — | ✅ |
|  | iv_rank | float | ⚠️ proposed (if options) | — | ✅ |
| **Structure** | distance_to_prior_swing | float (in R) | ⚠️ proposed | — | ✅ |
|  | distance_to_pdh_pdl | float (in R) | ⚠️ proposed | — | ✅ |
|  | level_test_count | int | ⚠️ proposed | — | ✅ |
| **AVWAP** | nearest_avwap_anchor | str | ⚠️ proposed | ✅ (best anchor per archetype) | ✅ |
|  | avwap_pinch_active | bool | ⚠️ proposed | — | ✅ |
| **Time-of-Day** | session_minute | int | ✅ | ✅ (already shows late-session edge) | ✅ |
| **Market Env** | regime_at_entry | enum | ✅ (if classifier fixed) | — | ✅ |
|  | breadth_at_entry | enum | ⚠️ proposed | — | ✅ |
|  | participation_at_entry | enum | ⚠️ proposed | — | ✅ |
|  | volatility_regime | enum | ⚠️ proposed | — | ✅ |
| **Catalyst** | minutes_to_next_event | int | ⚠️ proposed | — | ✅ |
|  | news_proximity | enum (none/recent/breaking) | ⚠️ proposed | — | ✅ |

### 6.2 Promotion rules (gate against overfitting)

A variable promotes from "field" to "parameter" only when:
1. **Theoretical motivation exists** (a published or codified hypothesis — Shannon ch. ref, Dale, CMT)
2. **Sample size ≥ 30 trades in each leg of the parameter sweep** (rule of thumb; tighter for binary parameters)
3. **Out-of-sample stability** (Part 8) — parameter holds in walk-forward
4. **Regime attribution** — parameter's edge is conditional on stated regime, not "always"

A variable promotes from "field" to "scorecard metric" only when:
1. **It's actionable** — the trader can change behavior on the next trade based on it
2. **It's observable in real-time** — not a post-hoc derivation
3. **It correlates with PnL with sample size ≥ 30**

### 6.3 The optimization target hierarchy

Not all optimization runs are equal. Order them by leverage:

```
TIER 1 — STRATEGY SELECTION (highest leverage)
  Which archetype to deploy given the environment?
  Currently: implicit (in trader's head)
  Optimization: edge_by_environment matrix (Part 3.2)

TIER 2 — ENVIRONMENT GATING
  Should this strategy be live or disabled in current env?
  Currently: regime_required only
  Optimization: gate calibration on the env matrix

TIER 3 — STRUCTURAL PARAMETERS
  Stop variant, target variant, anchor choice
  Currently: param surface for pull-in stop/target
  Extension: same methodology for trend-trade, backside, AVWAP archetypes

TIER 4 — TACTICAL PARAMETERS (lowest leverage)
  Entry trigger precision, scale-out fractions
  Currently: book defaults
  Extension: optimize last, on largest samples
```

The mistake to avoid: over-optimizing T4 (entry triggers) before T1 (strategy selection). T1 dominates outcomes.

---

## Part 7 — Institutional Scoring System

James asked for a multi-dimensional scoring framework. The current evaluator returns `grade: A/B/C/F/OFF-BOOK` with a `quality_score`. That's one dimension; institutions track at least four.

### 7.1 Four orthogonal score axes

| Axis | What it measures | Lives in | Failure mode if missing |
|---|---|---|---|
| **Setup Quality** | Was this a good setup? | Entry-time evaluator (current `quality_score`) | Trades feel "random" — can't tell A from C setups |
| **Execution Quality** | Did you execute the setup well? | Post-fill evaluator (slippage, entry vs ideal, timing) | Can't separate "bad system" from "bad you" |
| **Management Quality** | Did you manage the trade per playbook? | Live evaluator (`management_rules` adherence) | Discretion creeps in; rules erode silently |
| **Environment Alignment** | Was the setup right for the environment? | Env engine × edge matrix | Right setup, wrong day; can't see the pattern |

The composite **Trade Grade** is a weighted product, not a sum:

```
Trade Grade = Setup × Execution × Management × Env_Alignment
           ∈ [0, 1] each, multiplicative so any one F is fatal
```

This is institutional logic: a perfect setup, poorly executed, badly managed, in the wrong environment is not a "B trade". It's an F. The current scorecard implicitly collapses all four into one dimension, which is why trader behavior change is slow — you can't fix what you can't disaggregate.

### 7.2 Weighting by environment

Different environments make different score axes more important.

- **High volatility / crisis regime:** Management × 2. Setups deteriorate fast; rules adherence matters most.
- **Low-vol rotation:** Setup × Execution × 1.5. Edge is thin; entry precision dominates.
- **Trending day:** Env_Alignment × 1.5. Wrong tool kills the day; right tool printed money you missed.

Per-environment weighting is a v1.2 candidate.

### 7.3 Discipline score (the fifth axis)

Independent of P&L. Tracks:
- Stuck to daily stop?
- Respected the playbook count limit?
- Took every A-grade setup that appeared (didn't pass on edge)?
- Avoided every off-book / F-environment setup?

Discipline can be 100% on a losing day. The point: PnL is random short-term; Discipline is the operator's deterministic input. The system surfaces both.

---

## Part 8 — Research & Optimization Framework

What separates institutional research from retail backtesting:

### 8.1 The seven research disciplines

| # | Discipline | Purpose | Currently in stack | Implementation note |
|---|---|---|---|---|
| 1 | **Parameter surface (Tier 3)** | Find optimal stop/target combos | ✅ for pull-in | Extend to all archetypes |
| 2 | **Walk-forward analysis** | Test parameter stability over time | ❌ | Train on first N days, test on next M, slide window |
| 3 | **Regime segmentation** | Edge conditional on environment | ❌ (depends on env engine) | Cell-by-cell expectancy from edge matrix |
| 4 | **Expectancy analysis** | E[PnL / trade] = WR×Avg(W) − LR×Avg(L) | Partial (param surface shows PF) | Add expectancy explicitly; not just win-rate or PF |
| 5 | **Robustness / stability** | Does small parameter perturbation kill edge? | ❌ | ±10% param change → expect <20% PF change |
| 6 | **Monte Carlo on trade order** | Distribution of outcomes if trade order were randomized | ❌ | Compute drawdown distribution, not point estimate |
| 7 | **Fragility detection** | Is edge concentrated in a few outlier trades? | ❌ | Remove top 5% trades; if PF collapses, edge is fragile |

### 8.2 Walk-forward (concrete proposal)

Smallest valid loop, given current data volume:

```
For each strategy with ≥ 60 historical trades:
  Window 1: train_start = T-60, train_end = T-40
  Window 2: train_start = T-50, train_end = T-30  (10-day step)
  ...
  For each window:
    1. Fit optimal stop/target from training half
    2. Apply to test half (next 20 days)
    3. Record out-of-sample PnL and PF
  Aggregate: is OOS PF within 0.7× of in-sample PF? → robust
            OOS PF < 0.5× IS PF → overfit, do not deploy
```

### 8.3 Regime-segmented backtests

Every backtest run produces a *cell* in the edge matrix, not a single number. Output format:

```
Strategy: vwap-pull-in-long
Backtest period: 2026-01-01 to 2026-05-01 (84 trading days)

  Regime          │ Trades │ Win% │ Avg R │ PF   │ Expectancy/$/sh │
  ────────────────┼────────┼──────┼───────┼──────┼─────────────────┤
  trend-up        │   42   │  64% │ 1.8R  │ 2.1  │   $4.20         │
  trend-up+breadth│   18   │  72% │ 2.1R  │ 2.8  │   $5.95         │  ← the real edge cell
  rotation        │   12   │  33% │ -0.4R │ 0.6  │  -$0.80         │  ← do not deploy
  expansion       │    8   │  50% │ 1.1R  │ 1.4  │   $1.50         │
  ...
```

Without segmentation, "PF 1.67" lies. With segmentation, you find the cell where PF 2.8 lives and the cells where you're losing money to mean.

### 8.4 Robustness / fragility tests

```
Stop-perturbation test:
  Optimal stop = -2 SD. Run again with -1.8 SD, -2.2 SD.
  If PF moves from 2.1 to 0.9: stop is on a knife-edge → fragile
  If PF moves from 2.1 to 1.9: robust

Outlier-trade removal test:
  Remove top 5% of trades by R.
  If PF drops from 2.1 to 1.3: edge is real but lumpy
  If PF drops from 2.1 to 0.7: edge is mostly luck

Time-sliced sensitivity:
  PF on Mon/Tue/Wed/Thu/Fri separately.
  If 80% of PF comes from one day: edge is calendar-dependent, not setup-dependent
```

### 8.5 Monte Carlo on equity curve

Re-order the historical trade sequence 10,000 times. Report:
- 5th/50th/95th percentile of max drawdown
- 5th/50th/95th percentile of final equity
- Probability of new equity high in next 30 trades

This is the institutional sizing input. A point-estimate drawdown of -8% with an MC-95th of -22% means you cannot size to risk-of-ruin against the -8% — you size against the -22%.

---

## Part 9 — Database & Versioning Design

The current registry is one JSON file with 9 entries. For evolution at scale:

### 9.1 The seven canonical tables

```
strategies          (the registry — one row per strategy_id × strategy_version)
strategy_versions   (history; promotion notes; canonical-at timestamp)
parameter_sets     (named param combos per strategy; e.g. "pull-in-stop=lb3, target=4sd")
parameter_runs     (each backtest/optimization run; inputs, outputs, regime breakdown)
edge_by_env_matrix (strategy × regime → expectancy/PF/sample size)
trade_evaluations  (the live eval log; one row per evaluation; already in DDL pipeline)
trade_outcomes     (closed trades joined to evaluations; the truth)
```

### 9.2 Versioning rules (gate against silent change)

- **No mutation of a strategy_version once it has trades attributed to it.** Mutating breaks the param surface lineage.
- **A "release" of a strategy is `{strategy_id, version, canonical_at_timestamp}`.** Trades carry the canonical version at entry; evaluator joins back to that version.
- **Schema bump rules:** additive types are minor; signature changes are major; removing a type is forbidden (deprecate only).
- **Edge claims live in `edge_by_env_matrix`, never in `strategies.json`.** The strategy doc is the rule book; the edge matrix is the empirical attestation. Separation prevents "we wrote it down so it must be true" decay.

### 9.3 Strategy inheritance (DRY)

Mirror pairs (long/short) and family-level rules duplicate today. v1.2 candidate: composition.

```yaml
templates:
  mean_reversion_base:
    management_rules:
      - scratch_if_stalled_15min
    invalidation_conditions:
      - stop_breached
      - target_reached

strategies:
  td-vwap-long:
    extends: mean_reversion_base
    overrides:
      direction: long
      ...
```

This is a real refactor with non-trivial schema impact. Defer to v1.3+ unless the strategy count crosses ~15.

---

## Part 10 — Execution Quality & Accountability Loop (the canonical 7-step lifecycle)

The loop that closes the system. **This is your existing lifecycle from `/system/` — not a new construct.** Each step has a current question, an existing surface, and (where the framework adds value) an augmentation.

```mermaid
flowchart LR
    SL["1 · Strategy Library<br/>'what am I trading?'<br/>/strategies/"] --> PB["2 · Playbooks<br/>'how do I teach this?'<br/>/playbooks/"]
    PB --> MGP["3 · MGP<br/>'plan today?'<br/>/mgp/ (05:47 ET)"]
    MGP --> HUD["4 · Accountability HUD<br/>'obeying the rules?'<br/>live-accountability-v2/"]
    HUD --> SC["5 · Scorecards<br/>'how did I execute?'<br/>/scorecards/"]
    SC --> MR["6 · Monthly Reports<br/>'what's the trend?'<br/>db_reports/james-monthly-reports/"]
    MR --> PS["7 · Param Surface<br/>'which works best?'<br/>strategy-registry"]
    PS -.calibrate library.-> SL
    PS -.update playbook math.-> PB
    SC -.flag rule break.-> HUD
```

| Step | Existing surface | Question | This framework adds |
|---|---|---|---|
| 1. Strategy Library | `/strategies/` (live) | "what am I trading?" | Reconcile `family` field tags with page filter; add Structural Fade family; populate AVWAP archetypes |
| 2. Playbooks | `/playbooks/` (live) | "how do I teach this?" | Tie each playbook to one canonical archetype; reference the 3-lens L-T-L checklist (Part 4) |
| 3. MGP | `/mgp/` (LIVE 05:47 ET) | "plan today?" | Add a "today's live archetypes" panel: which family is in-edge given today's env coordinates |
| 4. Accountability HUD | live-accountability-v2 | "obeying the rules?" | Surface 4-axis grade in real-time (Setup × Exec × Mgmt × Env), not just the SMB rule violations |
| 5. Scorecards | `/scorecards/` | "how did I execute?" | Disaggregate the current `quality_score` into 4 axes; mark "wrong tool for env" trades |
| 6. Monthly Reports | `db_reports/james-monthly-reports/` | "what's the trend?" | Add per-archetype × per-regime equity curves |
| 7. Param Surface | strategy-registry + param-surface-db | "which works best?" | Extend the VWAP-bands 3×4 grid methodology to all archetypes; populate `edge_by_environment` |

**The missing edges in the loop today:**
- Step 4 (HUD) doesn't see Env-Alignment — the env classifier is broken (Part 12.1).
- Step 5 (Scorecards) collapses 4 axes into 1, hiding management failures inside "C" trades.
- Step 7 (Param Surface) doesn't yet write into `edge_by_environment` because that table doesn't exist.

Three edges, three projects. Sequenced in Part 13.

---

## Part 11 — Visual Architecture Maps

### 11.1 The five-layer stack (full)

```mermaid
graph TB
    subgraph L5["L5 — DECISION & ACCOUNTABILITY"]
        HUD["Accountability HUD<br/>(read-only spine)"]
        MGP["MGP — 3 editions"]
        DSTOP["Daily Stop Intel"]
        SCORE["Scorecards (4-axis)"]
        REVIEW["EOD / Weekly Review"]
    end
    subgraph L4["L4 — MARKET ENVIRONMENT ENGINE"]
        REGIME["Regime<br/>(rebuild P1)"]
        BREADTH["Breadth<br/>(P2)"]
        PARTIC["Participation"]
        VOL["Volatility regime"]
        SENT["Sentiment / VK"]
        CAL["Calendar / Events"]
    end
    subgraph L3["L3 — STRATEGY LIBRARY"]
        FAMA["A · Mean-Rev"]
        FAMB["B · Trend-Cont"]
        FAMC["C · Breakout"]
        FAMD["D · Structural"]
        FAME["E · RelStr"]
        EDGE["edge_by_env_matrix"]
    end
    subgraph L2["L2 — PRIMITIVES"]
        AVWAP["AVWAP family<br/>(P1 NEW)"]
        VWAP["VWAP + SD bands"]
        VP["Volume Profile<br/>(MTF VP scanner)"]
        TREND["MTF Trend Matrix"]
        MA["MA stack (9/20/50/200)"]
        MOM["Momentum (RSI/MACD)"]
        LEVELS["Levels (PDH/PDL/swing)"]
    end
    subgraph L1["L1 — SUBSTRATE"]
        OHLCV["OHLCV (TV/KTI/Liberator)"]
        TAPE["Tape / fills (Einstein relay)"]
        NEWS["News / VK"]
        CALEV["Event calendar"]
    end
    L1 --> L2 --> L3 --> L4 --> L5
    L5 -. review .-> L3
    L4 -. gate .-> L3
    L3 -. signals .-> L5
```

### 11.2 AVWAP anchor hierarchy

```
ANCHORS (ordered by strategic horizon)
│
├── MULTI-YEAR
│   └── IPO
│
├── ANNUAL
│   ├── YTD (institutional fair value — Shannon ch.4)
│   └── Prior YTD (often still relevant — Shannon)
│
├── QUARTERLY
│   └── QTD (PM benchmarking horizon)
│
├── MONTHLY / EVENT
│   ├── Last earnings gap          ← most useful for stock-specific edge
│   ├── Last guidance / news event
│   └── MTD / WTD
│
├── INTRADAY EVENT
│   ├── Pre-market high/low VWAP
│   ├── Session VWAP (Dale's domain)
│   └── Last 30-min VWAP
│
└── REL-INDEX
    ├── SPY swing high AVWAP
    └── SPY swing low AVWAP
```

### 11.3 Setup → Trade lifecycle (decision tree)

```
Premarket
  ├─ Read MGP Morning + VK
  ├─ Check Env coords: regime / breadth / vol
  ├─ Edge matrix → which families are live today?
  └─ Build watchlist of A/B candidates

Pre-Trigger
  ├─ Alert lands or eye sees setup
  ├─ Identify archetype (1 of 15)
  ├─ Run 3-lens check: AVWAP / VWAP / VP
  └─ Pre-trade grade: Setup × Env_Alignment
        ↓
   Grade < B → SKIP (log skip)
   Grade ≥ B → execute

Execute
  ├─ Entry, stop, R-defined, target plan
  └─ Live evaluator engages

In-Trade
  ├─ Bar close / alert tick → re-evaluate
  ├─ validation_rules: still in book?
  ├─ invalidation_conditions: triggered?
  ├─ management_rules: due to fire?
  └─ Live grade displayed on HUD

Exit
  ├─ exit_reason captured
  └─ Score axes computed

Post-Trade
  ├─ 4-axis grade: Setup × Exec × Mgmt × Env
  ├─ Slot into scorecard
  └─ Flag deltas vs playbook

Weekly
  ├─ Drift report, classifier-divergence, edge matrix update
  └─ Strategy registry: promotion / demotion candidates
```

### 11.4 The edge-by-environment matrix as a heat map

(Conceptual — to be populated; described in Part 3.2)

---

## Part 12 — Blind Spots, Missing Pieces, Contradictions

A blueprint isn't honest without naming what's wrong.

### 12.1 Hard contradictions in the current stack

1. **Three meanings of "Off-Book"** (per memory `feedback_strategy_classifier_divergence`):
   - HUD JS heuristic: band-blind
   - Python `classify_v2.py`: band-aware
   - Sentinel `off-book` strategy entry in `strategies.json`: auto-F catch-all
   The three disagree on what gets tagged. Until reconciled to one canonical function (Fix-It-Once rule #1), scorecard numbers are partially fiction.

2. **Regime classifier returns 100% rotation** (per `project_strategy_classifier_divergence`):
   - This breaks `trend-trade-long`/`short` evaluation entirely
   - Schema author wrote `_blocker_note` inline — formalize to `blockers: string[]` per strategy
   - **Highest-leverage P1 task**

3. **MTF Trend Matrix runs on scorecards but isn't a strategy gate.** It's lens; not gate. The matrix knows when 6 TFs disagree but doesn't refuse the trade.

4. **MTF VP scanner exists** (per `project_mtf_vp_scanner` / `project_mtf_scan_engine`) **but isn't wired to the evaluator.** Acceptance/rejection is computable but not consumed.

5. **THREE divergent strategy taxonomies in production simultaneously** (partially resolved 2026-05-15):
   - **`strategies.json` `family` field** (the evaluator's source of truth): was `{mean-reversion, trend, fade, off-book}` — 4 values, 9 strategies. **Now aligned** to the `/strategies/` page snake_case codes (`vwap_pullback_continuation`, `counter_trend_scalp`, `off-book`). Migration log appended to `meta.generated_by` on 2026-05-15. Backup at `strategies.json.pre-family-migration.bak`.
   - **`/strategies/` page inline data** (the trader's reference UI at `trsportsacademy.com/strategies/`): uses snake_case codes `{vwap_pullback_continuation, counter_trend_scalp, gap_fade, level_breakout, event_driven, volume_profile}` — 6 values, ~17 strategies. **Canonical going forward.**
   - **`/system/` hub description** (the documentation): names the filter "VWAP/Pullback, Counter-trend, Level Breakout, Event-Driven, Gap Fade" — humanized form of the page codes. *Should be regenerated from the page codes mechanically, not hand-edited.*

6. **`/strategies/` page has ~17 strategies; `strategies.json` registry has 9** (uncovered by the migration audit). The page enumerates additional setups — Back Through Open, VWAP Continuation, Day 3 Breakout/Down, Opening Range Break, Higher Timeframe Breakout/Down, Breaking News, Earnings Day 1, Gap Give and Go, plus two volume_profile entries and a "VWAP Pull-In → Trend" hybrid — that are NOT in `strategies.json`. These strategies are visible to the trader (on `/strategies/`) but **cannot be live-evaluated** (no schema entry, no validation/invalidation/management/quality rules). The Live Classifier HUD scores only the ~6 playbooks in the registry; the trader sees a wider menu on the strategies page. This is a real coverage gap, separate from the family-tag mismatch. **Recommend:** audit the ~8 missing strategies, decide which are real (need schema entries) vs which are scrap (remove from page).

7. **Live Classifier HUD scores 6 playbooks against 14 symbols** (production), but the post-migration registry has 9 entries (with off-book sentinel; 5 distinct archetypes after mirror dedup). The 6-vs-5 mismatch overlaps with #6 — likely the classifier ingests a few page-only setups via hardcoded logic.

### 12.2 Architectural blind spots

1. **No portfolio layer.** Every component reasons about single trades. Sizing, correlation, sector concentration, gross/net exposure — all absent. At one trader's scale this is OK. At firm scale (4 internal traders + 2 external) this is a real gap.

2. **No latency budget.** The streaming architecture (Einstein WebApp → ingest → SSE → HUD) doesn't have an explicit "this entire loop must complete in <2 seconds for HUD push to be useful" SLA. If the relay falls behind, the system silently degrades.

3. **No survivorship/look-ahead audit on backtests.** When edge matrix populates, it'll show optimistic numbers if symbol universe is "stocks that exist today" (survivorship) or if features use post-close data on the entry bar (look-ahead). Calling this out before backtests run is cheap; debugging after is expensive.

4. **No formal trader behavior model.** The Discipline score axis (Part 7.3) is proposed but doesn't yet capture *patterns* — averaging down, revenge-trading after stop, position-creep across a losing day. Behavioral red-flag detection is mature in Brett Steenbarger's work and easy to wire to the scorecard.

5. **No "what was on the menu" log.** When the trader passes on a setup, we don't capture it. The dataset is biased to executed trades only. Passing on A-grade setups (the worst kind of skip) is invisible. Capturing skips is a simple cron over the alert log filtered by "alert without subsequent fill".

6. **"TR Sports Academy" is James's own platform** (`trsportsacademy.com`), not a third-party coaching system. The `/system/` page on that domain IS the production mirror of `index.html` here. Draft 1 incorrectly framed this framework as integrating WITH an external system; Draft 2 corrects it — this framework is the architectural spec FOR that platform. No external content to integrate.

### 12.3 Where the framework might be wrong

- **The 15-archetype taxonomy may be over- or under-fitted.** 15 is a starting count, calibrated to Shannon + Dale + the current registry. After 6 months of trading data, expect 2-3 to collapse (low-incidence/no-edge) and 1-2 to subdivide. Don't lock the taxonomy.

- **Multiplicative grade (Part 7.1) is harsh.** A trader who scores 0.9 × 0.9 × 0.9 × 0.9 = 0.66 has done excellent work on every axis but reads as "C". An additive variant with high weighting is more forgiving. Pick after collecting 30+ trades graded both ways.

- **Component DNA (Part 2) doesn't separate "intent" from "outcome".** A pull-in *intended* as B1 but managed as D1 (you held through the band failure as a structural fade) is graded against B1 today. Should "executed archetype" be a separate field from "intended archetype"? Probably yes — but no current support.

---

## Part 13 — Implementation Sequencing & Leverage Ranking

Final asks from the prompt: blind spots ✅, contradictions ✅, integration opportunities ✅, scalability ✅, **sequencing** — below.

### 13.1 Leverage-ranked roadmap

The single number to optimize: *expected change in trader behavior × probability of completion × persistence.* Each item below is scored 0-5 on each.

| # | Initiative | Lev | Prob | Pers | Score | Sequence |
|---|---|---|---|---|---|---|
| 1 | **Fix regime classifier** — one canonical function, calibrate on 30d labeled data | 5 | 4 | 5 | **100** | **P1 now** |
| 2 | **Build edge-by-environment matrix table + nightly populate** (depends on #1) | 5 | 4 | 5 | **100** | **P1 after #1** |
| 3 | **Reconcile "Off-Book" — single canonical function** | 4 | 5 | 5 | **100** | **P1 parallel to #1** |
| 3.5 | ~~Align `strategies.json` `family` tags with `/strategies/` page taxonomy~~ — **COMPLETED 2026-05-15** (migrate_family.py applied; 8 of 9 entries re-tagged; off-book preserved; backup saved) | — | — | — | ✅ | **DONE** |
| 3.6 | **Audit ~8 strategies on `/strategies/` page but not in `strategies.json`** (Back Through Open, VWAP Continuation, Day 3 Breakout/Down, Opening Range Break, HTF Breakout/Down, Breaking News, Earnings Day 1, Gap Give and Go, 2× volume_profile) — decide: author schema entries OR remove from page | 4 | 4 | 5 | **80** | **P1.5 (uncovered by migration)** |
| 4 | **Add AVWAP primitives to evaluator catalog (v1.2)** + `avwap_anchors.json` registry | 4 | 4 | 5 | 80 | P2 |
| 5 | **4-axis trade grading** (Setup × Exec × Mgmt × Env) — disaggregate the scorecard | 4 | 5 | 4 | 80 | P2 |
| 6 | **Wire MTF VP scanner into evaluator** as `vp_node_proximity` | 3 | 5 | 5 | 75 | P2 |
| 7 | **Author B3, B4, B5 AVWAP strategies** in registry (Reclaim, Handoff, Multi-Day) | 4 | 3 | 5 | 60 | P3 (after #4) |
| 8 | **Walk-forward + regime-segmented backtest harness** | 3 | 4 | 5 | 60 | P3 |
| 9 | **Skip-capture cron** — log A/B setups passed on | 2 | 5 | 5 | 50 | P3 |
| 10 | **Breadth daily** — Liberator probe + breadth_daily table | 3 | 3 | 5 | 45 | P3 (gate for full env engine) |
| 11 | **C1 Pinch Breakout strategy** in registry | 4 | 2 | 5 | 40 | P4 (needs AVWAP catalog) |
| 12 | **Behavioral red-flag detector** (averaging down, revenge, creep) | 3 | 4 | 4 | 48 | P4 |
| 13 | **Portfolio layer** (correlation, exposure, sector concentration) | 2 | 3 | 5 | 30 | P5 |

### 13.2 The two-week sprint that unlocks everything

If James does only these in the next two weeks, the system snaps into a new performance class:

**Week 1:**
- Day 1-2: Pull 30 days of labeled trades. Run `classify_v2.py` and 2-3 candidate regime functions side-by-side. Build confusion matrix. Pick the winner. Wire it everywhere (delete the JS heuristic; regenerate Pine).
- Day 3-5: Build `edge_by_env_matrix` table; nightly cron that segments closed trades by (strategy, regime) and writes expectancy/PF cells.

**Week 2:**
- Day 6-8: Disaggregate trade grade into the 4 axes; update scorecard rendering.
- Day 9-10: Add `avwap_position`, `avwap_slope`, `avwap_reclaim` types to evaluator. Author one strategy (B3: AVWAP-Reclaim-Long) to prove the catalog.

End-state: HUD recommends strategies given env coords. Scorecard tells trader where the 4-axis decay is. Edge matrix tells the trader (and the optimizer) which cells make money. AVWAP is a first-class citizen.

### 13.3 What James is *not* missing

A list as honest as the blind-spot list. Things you don't need to build because they already exist:

- TradingView feed + alert webhook + ingest — solid
- Param surface methodology (extend, don't redesign)
- MTF Trend Matrix — 6-TF × 4-tier, well-engineered, lives on scorecards
- The /system/ hub — placement and SoT discipline is mature
- Daily Stop Intel — a sophisticated tool retail traders never build
- MGP 3-edition pipeline — CMT-grounded tape read
- Live-accountability-v2 — read-only spine
- Schema v1.1 evaluator API — pure function, well-specified, 21-type catalog
- Memory system — keeping behavior consistent across sessions

The framework above is an *upgrade path*, not a rewrite. Everything in `/system/` survives. The new pieces (AVWAP catalog, env engine, edge matrix, 4-axis grade) compose with existing surfaces; they don't displace them.

---

## Appendix A — Mapping to Brian Shannon's book

| Shannon chapter | Concept | Where it lives in this framework |
|---|---|---|
| Pt I Ch.1-2 | VWAP/AVWAP foundations | Part 4.1-4.2 |
| Pt I Ch.3 | Why institutions use VWAP | Part 4.1 (institutional fair value) + Part 4.4 `ytd`/`qtd` anchors |
| Pt I Ch.4-5 | Anchoring psychology, components | Part 4.4 anchor registry |
| Pt II Ch.2 | AVWAP as S/R | Component 1 (Location), `avwap_position` type |
| Pt II Ch.3 | Entry/exit techniques (Buy the Touch vs Momentum) | `entry_method` discriminator (already in v1.1) |
| Pt II Ch.4 | Where to anchor | `avwap_anchors.json` registry |
| Pt II Ch.5 | **The Pinch** | Component 3 (Compression), `avwap_pinch` type, archetype C1 |
| Pt II Ch.6 | **The Handoff** | `avwap_handoff_eligible` type, archetype B4 |
| Pt II Ch.7 | Pullbacks vs breakouts; AVWAP Cross Purchase; "buy strength after the dip"; "where has it come from?"; "trim and trail" | Markup-Anticipation + AVWAP-Cross-Purchase archetypes (Part 4.2.5); `range_compression` quality indicator; `most_recent_swing` stop type; explicit trim-and-trail management rule |
| Pt II Ch.8 | Multi-day AVWAP; 2-day VWAP reclaim; day-3 continuation | Multi-Day-AVWAP archetype; new anchors (`day_minus_1_avwap`, `day_minus_2_avwap`) in `avwap_anchors.json` |
| Pt II Ch.9 | Gap trading | Archetypes C3 (gap-and-go) and D2 (gap-fade) |
| Pt II Ch.10 | Short squeeze | Archetype D3 |
| Pt II Ch.11 | IPO trades | `ipo` anchor; AVWAP-from-IPO is a permanent anchor on newer issues |
| App. A | Four-stage market structure; time vs price correction; "innocent until proven guilty" framing | Environment Engine regime values (Stage 1 = compression, Stage 2 = trend-up, Stage 3 = distribution/compression, Stage 4 = trend-down). **Key insight (added Draft 2.2):** Stages 1 and 3 are recognizable ONLY in retrospect — "markup anticipation" is therefore *transition detection*, not state detection. The 5-signal Stage 1→2 gate (Part 4.2.5) operationalizes this. |
| App. B (Table B-7) | MTF equivalence | Already in chart defaults + MTF Trend Matrix |

## Appendix B — Mapping to Trader Dale

| Dale concept | Where it lives |
|---|---|
| Session VWAP + flat ±1/±2/±3 SD | L2 primitive (existing) |
| Rotation strategy (entry -1 SD, stop -2 SD, target +1 SD) | Archetype A1, strategy `td-vwap-long`/`short` |
| Trend continuation entry inside fanning bands | Archetype B1, strategy `vwap-pull-in-long`/`short` |
| 15-min scratch rule (rotation stall) | `management_rules.scratch_if_stalled_15min` in registry |

## Appendix C — CMT/SMB/Markup-Anticipation slots

| Source concept | Slot |
|---|---|
| CMT Ch.35-37 (system design, backtesting, optimization) | Part 8 entirely |
| CMT Ch.36 falsification | MGP tape read (already in pipeline); also informs walk-forward acceptance criteria |
| Stan Weinstein 4-stage | Part 5 regime values (Stage 1-4) |
| Stovall sector rotation | Part 5 breadth / participation |
| Shannon (Tape Reading) tape-control rules | MGP Tape Read (already) |
| Murphy intermarket | Future: env engine's risk-on/off coordinate from cross-asset signals |
| SMB intraday playbooks | Family A/B/D entries; archetype refinement |
| Markup-anticipation (your framework) | Trend-Trade-Pullback + AVWAP-Reclaim + AVWAP-Handoff + Multi-Day-AVWAP archetypes (VWAP/Pullback family); gate is "Stage 1→2 transition + AVWAP slope rolling positive" |
| TR Sports Academy | **N/A — `trsportsacademy.com` is James's own production platform; the `/system/` page is the canonical mirror of [index.html](index.html); this framework IS that platform's architectural spec.** |

---

*End Draft 2 (2026-05-15). Next iteration after: (a) Env Engine fixed, (b) `strategies.json` family tags reconciled to `/strategies/` page taxonomy, (c) AVWAP catalog merged into the evaluator.*

---

## Changelog

- **Draft 2.2 (2026-05-15):** Deeper read of Shannon Appx A (Four Stages), Ch.6 (Handoff/Layering), Ch.7 (Pullbacks/Breakouts), Ch.8 (Multi-Day) to extract Shannon's full markup-anticipation framework. Added new Part 4.2.5 ("Markup Anticipation — the Stage 1→2 Transition Framework") with the 5 confirming signals, layering depth, time-vs-price correction, "most recent and relevant HL" stop logic. Promoted **Markup-Anticipation** and **AVWAP-Cross-Purchase** from sub-bullets to first-class archetypes in the VWAP/Pullback family. Added **Continuation-Gap** archetype. Added 6 new evaluator types to Part 6: `avwap_cross_from_swing`, `stage_transition_signals`, `correction_type`, `trend_layer_depth`, `range_compression`, plus new stop type `most_recent_swing`. Expanded Appendix A (Shannon mapping) with the operational details previously missed.
- **Draft 2.1 (2026-05-15):** Applied family-tag migration to `strategies.json`. All 8 non-sentinel strategies re-tagged to the `/strategies/` page canonical taxonomy (`vwap_pullback_continuation` × 6, `counter_trend_scalp` × 2). `vwap-pull-in-{long,short}` corrected from incorrect `mean-reversion` to `vwap_pullback_continuation` (matching its actual setup mechanism — pullback in trending bands). `off-book` sentinel preserved. Backup at `strategies.json.pre-family-migration.bak`. The migration audit uncovered a deeper gap (Contradiction #6): `/strategies/` page enumerates ~17 strategies, but the registry only schemas 9 — promoted to P1.5 sequenced task.
- **Draft 2 (2026-05-15):** Reframed as architectural spec FOR `trsportsacademy.com/system/` (= this hub) — clarified that "TR Sports Academy" is James's own production platform. Adopted canonical Spine/Cockpit/Lens model as primary architecture; my 5-layer flow demoted to secondary. Rewrote 15-archetype taxonomy to map into the live `/strategies/` page filter. Lifecycle replaced with canonical 7-step flow from `/system/`. Proposed 6th family "Structural Fade" for back$ide setups (cheap decision).
- **Draft 1 (2026-05-15):** Initial synthesis. Framework invented its own A/B/C/D/E family taxonomy and L1-L5 layer model. TR Sports Academy treated as external integration point. Both corrected in Draft 2.
