# HERMES TRADING INTELLIGENCE — SYSTEM ARCHITECTURE MASTER SPEC
**v5.4.0 · 2026-07-06 · supersedes hermes_trading_spec v4.0.1 (260613)**

> 🌐 **Interactive version:** https://whale-command.srv1663871.hstgr.cloud/arch.html — clickable master diagram, per-process drill-down (what/why/when/design/pro-con), live benefit-vs-cost blocks fed by `arch_data_gen.py` (2h cron).

> **Audience:** Chris, Claude (any instance), Hermes, other LLMs, and any code that needs to understand the whole machine.
> **How to use:** §2 gives the one master diagram. Each layer section then gives WHAT / WHY / HOW / WHEN, a diagram, and a PRO/CON verdict so future collaborators understand not just the design but the *reasoning* — and can safely improve it.
> **Living document rule:** every finished build gets appended here (habit [[feedback_document_builds_in_spec]]). Bump SemVer via `version_manager.py`.

---

## §0 — Table of Contents

1. Core Philosophy & Design Principles
2. Master Architecture Diagram (the whole machine)
3. Layer 0 — Infrastructure & Ops Safety
4. Layer 1 — Data Ingestion (sources & costs)
5. Layer 2 — Signal Detection (detectors)
6. Layer 3 — Enrichment (the intelligence multiplier)
7. Layer 4 — Convergence & Conviction
8. Layer 5 — Decision & Execution
9. Layer 6 — Learning Loop (Karpathy / Self-Improvement Machine)
10. Layer 7 — Wallet Intelligence & the Wallet DB
11. Layer 8 — Edge Discovery Program (EP-1..10)
12. Layer 9 — Governance, Cost & Ops
13. Layer 10 — Knowledge & Memory (the shared brain)
14. Telegram Channel Map
15. Design Decision Log (why we chose what we chose)
16. Known Issues & Risk Register
17. IMPROVEMENT ROADMAP (profit · edge · design · efficiency · cost)
18. Invocation Commands
19. Changelog

---

## §1 — Core Philosophy & Design Principles

### North star
> *Discover and front-run the highest-performing on-chain traders and alpha signals before anyone else — fully automated, self-improving.*

### 🎯 The Copy-Timing Edge (CORE, 260625)
**It is not the token — it is the wallet and the moment.** Our asymmetric edge is perfecting WHICH / WHAT / HOW / WHEN to copy FRESH, DORMANT-AWAKENING, and SMART wallets. Every layer below exists to sharpen wallet classification and copy-timing. Dormancy and freshness are **first-class enrichment dimensions** on every wallet, token, and card.

**Why this edge and not others:** token-picking is a crowded, reflexive game where we're late by construction. Wallet-behavior alpha decays much slower — a profitable operator's *pattern* (funding chains, generation rotation, entry sizing, dormancy cycles) persists across many tokens. GMGN et al. have already paid to compute the raw data; our edge is **combing it smarter** ([[feedback_edge_discovery_mandate]]).

### Design principles (each is a hard-won lesson)

| # | Principle | Why (the lesson) | Trade-off accepted |
|---|-----------|------------------|--------------------|
| P1 | **Piggyback first, build second** | Others (GMGN, Cielo, dexLions, ProTrending, Dune, Cipher) already aggregate; reusing is 10–100× cheaper than building. Build in-house copies only when shadow-validated to beat the original ([[feedback_piggyback_better_copies]]) | Dependency on third parties; mitigated by in-house shadow copies (e.g. protrending in-house) |
| P2 | **Never delete wallets/data** | Dormant alpha wakes up for asymmetric trades; deletion destroyed 1499→690 DB once (260617 incident). Flag dormant, rank lower, never delete | DB grows; mitigated by tiering + dormancy flags |
| P3 | **Expectancy + tail > win rate** | WR is a weak filter — the 1000× winner looked like a 42% WR loser. Rank by expectancy, payoff ratio, p95/top-20% tail ([[feedback_winrate_vs_size]], [[percentile_alpha_tail]]) | Higher variance tolerance; needs distribution profiling first |
| P4 | **Distribution-aware stats** | Sniper ROI is extreme power-law; means bury the alpha. Profile shape first (`distribution_profiler.py`), then pick the metric | Slightly more compute per report |
| P5 | **Approval + backtest gate on every deploy** | No discovery process deploys and no wallet auto-adds without Chris's approval AND backtest proof (FDR vs control). Prevents plausible-sounding noise from compounding | Slower deployment; that's the point |
| P6 | **Everything versioned** | SemVer on every algo/job/config via `version_manager.py`; snapshots enable rollback. A self-modifying system without versioning is unauditable | Small bookkeeping overhead per change |
| P7 | **Measure → Compare → Promote → Mutate** | Every signal writes outcome fields; every param has an A/B challenger; every change states WHY ([[feedback_self_improvement_machine]]) | Ledger volume; storage is cheap, amnesia is not |
| P8 | **Cost discipline: scripts ≈ $0, LLM only where judgment matters** | Deterministic Python for detection/enrichment/formatting; LLM (DeepSeek V4 cheap tier) only for synthesis/review. Claude-tier only on Chris's direct sessions | Occasional stiffness in generated text; acceptable |
| P9 | **Boost, don't filter** | Conviction layers ADD score; they never silently drop candidates (a filter that's wrong once costs a 100×). Only hard scam-gates (deployer blacklist) filter | More items to scan; mitigated by ranking |
| P10 | **Association > performance for retention** | A weak-performing wallet inside an alpha cluster is C-tier *intel*, not junk — it may reveal the next generation ([[feedback_association_vs_performance]]) | Bigger tracked set |
| P11 | **Dispatch, don't block** | Chris monitors via Telegram on phone; every process reports to its thread; approvals happen async via the queue (37479) | None material |
| P12 | **One Loop First** | Scope freeze on new verticals until the core loop (signal→decision→paper→real $) closes profitably at each tiered gate ($0→$300→$2K→$10K) ([[master_profit_plan]]) | Deliberately foregone breadth |

---

## §2 — Master Architecture Diagram

The whole machine, end to end. Annotations: 🔍=detect · ✚=enrich · 🚪=gate · ⚡=boost · 🔁=learn.

```mermaid
flowchart TB
    subgraph L1["LAYER 1 · DATA INGESTION (~$0 API cost by design)"]
        GMGN["GMGN API<br/>tokens·wallets·traders·smartmoney"]
        DEX["DexScreener<br/>volume (free, reliable)"]
        TG_IN["@FutureLanding userbot<br/>30+ alpha channels, Tier 1/2/3"]
        DUNE["Dune Analytics<br/>daily alpha comb"]
        CHAIN["Blockscout / on-chain<br/>forensics·funding chains"]
        MACRO["DeFiLlama TVL + Farside ETF<br/>regime inputs"]
        PT["ProTrending / dexLions / BurpBoard / Cipher<br/>piggybacked curation (P1)"]
    end

    subgraph L2["LAYER 2 · SIGNAL DETECTION 🔍 (deterministic Python, staggered crons)"]
        DET["Detectors: trending · sniper · base_launch<br/>doppler (DERC20) · volume_spike · sapphy_floor<br/>fresh_predecessor (EP-7) · dormancy_scanner"]
        ACC["accumulation_engine (30m)<br/>REPEAT·RANGE·STEALTH·SWARM·WM signatures"]
        WMT["whalemover_tracker<br/>58 wallets · 5 groups · coordination"]
    end

    subgraph L3["LAYER 3 · ENRICHMENT ✚ (the multiplier — cache-first, ~$0)"]
        CARD["token_card v2.15<br/>Wallet-Intel card on EVERY token"]
        ENR["volume 6-lens · deployer intel 🚪blacklist<br/>dormancy/freshness · profile_sigs 🏆<br/>TA 4-tier regime · gmgn_links"]
    end

    subgraph L4["LAYER 4 · CONVERGENCE ⚡"]
        MS["master_scanner_180 (30m)<br/>2+ independent sources = high conviction"]
        CONV["conviction.py — boost-not-filter (P9)<br/>APEX siren (shadow-staged)"]
    end

    subgraph L5["LAYER 5 · DECISION & EXECUTION"]
        CD["copy_decision engine<br/>WHICH·WHAT·HOW·WHEN → PLAY verdict"]
        PAPER["paper_trader v1.1 (cooldown+5m)"]
        REAL["GMGN real rails (verified, awaiting funding)<br/>⚡EXECUTE buttons via trade_links"]
    end

    subgraph L6["LAYER 6 · LEARNING LOOP 🔁 (Karpathy machine)"]
        OT["outcome_tracker → outcome_ledger<br/>(every signal gets outcome fields, P7)"]
        PE["param_evaluator v2.2 (EV+OOS+FDR)<br/>replay_engine · control cohort"]
        KR["Karpathy reviews 2×/day<br/>promote / mutate params + weights"]
    end

    subgraph L7["LAYER 7 · WALLET INTELLIGENCE (the crown jewels)"]
        WDB[("wallet_db.json ~1719 wallets<br/>keyed chain:address · NEVER deleted (P2)")]
        DISC["TDWA · mega_cluster_discovery (7-method)<br/>EP-1..7 · protrending_harvester"]
    end

    subgraph L8["LAYER 8 · GOVERNANCE & BRAIN"]
        Q["hermes_todo queue → thread 37479<br/>🚪 Chris approve/deny + backtest proof (P5)"]
        GOV["version_manager · watchdogs · cost guard<br/>ops dashboard · system_edge_digest"]
        KB[("Knowledge layer: vault ↔ VPS bridge<br/>MEMORY.md · spec (this file) · learnings")]
    end

    TGOUT["📱 TELEGRAM — Nousman HQ<br/>threads per function (§14)"]

    L1 --> DET & ACC & WMT
    DET & ACC & WMT -->|raw signals| CARD
    CARD --> ENR --> MS --> CONV --> CD
    CD --> PAPER --> OT
    CD -.->|when funded| REAL
    OT --> PE --> KR
    KR -->|🔁 weight/param updates| DET & ENR & CD
    DISC -->|graduated wallets 🚪via Q| WDB
    WDB --> ENR & DET
    KR --> KB
    Q --- GOV
    CD & MS & KR & GOV --> TGOUT
    TGOUT -->|Chris replies: approve/deny/tdwa/comment| Q
```

**Reading the machine in one sentence:** free/cheap data flows in → deterministic detectors fire → every token gets a wallet-intel-enriched card → convergence boosts conviction → the copy-decision engine says COPY / FRONT-RUN / SKIP with sizing → paper (soon real) trades execute → every outcome is measured → the Karpathy loop re-tunes the weights → wallet discovery keeps refilling the crown-jewel DB → Chris governs by Telegram reply.

---

## §3 — Layer 0 · Infrastructure & Ops Safety

### WHAT
| Component | Detail |
|-----------|--------|
| VPS | Hostinger `2.24.93.240`, SSH root, Docker + Traefik |
| Containers | `hermes-agent-iczm-hermes-gateway-1` (everything), `traefik` |
| Schedulers | ~113 Hermes cron jobs (jobs.json, CLI-managed) + ~60 host crontab entries |
| Dashboards | hermes-dashboard · ops.srv1663871 (ops/cost) · whale-command.srv1663871 (per-whale tabs) |
| Safety | `runaway_reaper.py` (host, */10 — kills whole-FS grep/find >10min) · `restagger_cron.py` (phase-stagger) · health watchdog → kanban · cost watchdog |

### WHY these choices
- **One VPS, one container** — a solo operator can hold the whole system in his head; k8s-style sprawl would kill maintainability with zero benefit at this scale.
- **Cron-first, not event-bus** — crons are inspectable, restartable, individually cheap. *Known limitation:* convergence timing suffers (see APEX §16); an event bus is the roadmapped keystone upgrade.
- **CLI-only cron edits** ([[feedback_hermes_cron_cli_only]]) — editing jobs.json directly isn't hot-loaded, and `model:'none'` typos spin paid agent-fallback loops ($14/day incident, 260702). `hermes cron edit --no-agent` is the only sanctioned path.
- **Phase-staggering** ([[feedback_cron_stagger]]) — `START-59/STEP` phases per interval class cut max-simultaneous jobs 20→5; aggregators scheduled after their inputs.

```mermaid
flowchart LR
    subgraph HOST["VPS host"]
        CRON["host crontab ~60<br/>staggered START-59/STEP"]
        REAPER["runaway_reaper */10 🚪<br/>kills >10min FS scans"]
    end
    subgraph DOCKER["hermes-gateway container"]
        JOBS["~113 hermes cron jobs<br/>CLI-managed only"]
        GW["gateway → Telegram"]
        DATA[("/opt/data<br/>scripts·trading·knowledge·_versions")]
    end
    CRON --> DOCKER
    REAPER -.->|protects| HOST
    JOBS --> GW
```

**PRO:** dead simple, fully inspectable, ~$10/mo infra, one SSH away.
**CON:** single point of failure (no HA); cron-polling latency (30m worst-case) on convergence; container restart loses in-flight state. **Verdict:** right for current scale; event-bus is the one structural upgrade worth making (§17-A3).

---

## §4 — Layer 1 · Data Ingestion

**Design rule:** the edge is *combing already-computed data*, so ingestion must be ≈ $0 and piggyback-first (P1, P8).

| Source | What we take | Cadence | Cost | Why / PRO | CON / risk |
|--------|-------------|---------|------|-----------|------------|
| **GMGN API** | trending, smartmoney track, token traders, wallet stats, fresh_edge | per-detector | ~$0 (cache-first token_card) | Richest pre-computed wallet analytics anywhere; already ranks wallets per timeframe | Rate limits; ROI field needs 50× clamp; no guarantee of stability |
| **DexScreener** | volume | 5m spike scanner | free | Reliable volume where GMGN field-guessing failed (260624 lesson) | Less depth |
| **@FutureLanding userbot** | 30+ channels, watchlisted callers, Rick-bot replies | realtime | ~$0 | Human-curated alpha at zero marginal cost; convergence raw material | Channel quality drift; 6 channels still unjoined; Rick-reply dependency for outcomes |
| **ProTrending (piggyback + harvest)** | their whale/fresh/dormant wallet curation | 30m harvester | ~$0 | They already curate; we mine their curation INTO our DB (P1 embodied) | If they degrade, shadow in-house copy takes over (already live) |
| **dexLions / BurpBoard / Cipher** | KOL-call cascade · proven-winner boards · revival signals | daily/eventual | ~$0 | Confirm-only tiers sharpen convergence | Never generate calls alone (Tier-3 rule) |
| **Dune** | custom SQL alpha/deployer comb | daily | API key gated | The only place for arbitrary cross-wallet SQL | Query cost; propose-only, never auto-add |
| **Blockscout MCP** | funding chains, cluster forensics | on-demand | free | Ground truth for cluster confirmation | Slow for bulk |
| **DeFiLlama TVL + Farside ETF** | chain flows, macro regime | 4h / 2×day | free | Cheap regime context (Tier 2/3) | Coarse |

**Key insight encoded here:** we deliberately buy **zero** premium data. Every dollar of edge comes from *recombination* of free tiers — this keeps the system's break-even near zero and makes every improvement pure margin.

---

## §5 — Layer 2 · Signal Detection

### WHAT — the detector fleet (all deterministic Python, all output → signal files + threads)

| Detector | Signature it hunts | Cadence | Notes |
|----------|--------------------|---------|-------|
| `trending` / `sniper` / `base_launch` | GMGN momentum · sniper entries · new Base launches | continuous | Highest volume, lowest precision — exists to feed enrichment, not to trade raw |
| **`accumulation_engine`** (260705, LIVE) | REPEAT · RANGE · STEALTH · SWARM · WM accumulation signatures, scored 30m, graded `source=accum_engine` | 30m | Day-1 validation: FLORK. The most "wallet-and-moment" native detector we have |
| `doppler_scanner` | new DERC20 Doppler launches w/ KOL/SM or 2+ buys ≥0.15 ETH | 5m | Thread 181 |
| `volume_spike_scanner` | DexScreener rvol spikes | 5m | Volume = CONTEXT not signal (6-lens doctrine) |
| `fresh_predecessor_scanner` (EP-7 v3) | fresh wallets buying $500+ BEFORE clusters at sub-$300k MC | 2h | 3 auto-add gates + manual review — the purest front-run detector |
| `sapphy_floor_scanner` | sapphy generation rotation + sub-$50K floor + Elon lexicon | 15m | Whale-specific MO exploitation |
| `whalemover_tracker` v2 | 58 known wallets, 5 groups, coordination timing | realtime-ish | ⚠️ captures no sells (§16) |
| `dormancy_scanner` | dormant-wallet awakenings | daily+ | Feeds first-class dormancy enrichment everywhere |

```mermaid
flowchart LR
    IN["GMGN / DexScreener / chains"] --> D1[🔍 momentum detectors<br/>trending·sniper·launch]
    IN --> D2[🔍 behavior detectors<br/>accum_engine·fresh_pred·dormancy]
    IN --> D3[🔍 identity detectors<br/>whalemover·sapphy_floor·doppler]
    D1 & D2 & D3 -->|signal files /opt/data/trading/*.json| OUT["→ Layer 3 enrichment<br/>every signal gets outcome fields 🔁"]
```

### WHY this shape
- **Behavior > momentum.** Momentum detectors (trending/sniper) have structurally low WR — Karpathy data shows it. They stay because they're free *context* and feed the outcome ledger with volume. The behavior/identity detectors (accum, fresh-pred, dormancy, whale-specific) carry the copy-timing edge.
- **Per-whale detectors** (sapphy_floor) exist because top operators have *stable MOs* — sapphy rotates wallet generations; detecting the rotation beats tracking the dead gen-2 wallets (FLOOR-001 lesson).

**PRO:** cheap, parallel, individually replaceable; each detector = one hypothesis, testable via ledger.
**CON:** detector sprawl (each new one adds cron + thread noise); convergence must dedupe across them (delta-tagging NEW/UPD/RPT solves briefing duplication — [[feedback_alpha_report_cadence]]). **When to add a new detector:** only when it encodes a *new behavioral signature*, not a new data source for an old one.

---

## §6 — Layer 3 · Enrichment (the intelligence multiplier)

**Doctrine:** a raw signal is worth ~nothing; the same signal + wallet context + deployer history + dormancy + volume lens + regime = a decision-grade card. Enrichment is where P1 (piggyback) pays out hardest — all enrichment is cache-first and ≈$0.

### The Token Card (`token_card.py` v2.15) — the atomic unit of intelligence
Every token surfaced anywhere gets the same standard card:

| Card block | Source | What it answers |
|------------|--------|-----------------|
| Wallet-Intel card | wallet_db + GMGN tags | WHO is in this token (9 wallet types, smart/fresh/dormant counts) |
| 🏗️ Deployer line | deployer_intel (158 deployers) | Has this deployer rugged before? 🚪 BLACKLIST pre-filter in gate_token — the ONE hard filter (P9 exception) |
| Dormancy/freshness | level0_lookup | Are dormant wallets waking up on this? (first-class edge dim) |
| Volume 6-lens | volume_signal v1.1 | Is volume real or wash? (context, not trigger) |
| 📐 µTA + regime header | ta_chart_regime + market_regime 3-tier | Weinstein stage, Bollinger, market regime — sets sizing posture |
| 🏆 profile_sigs | wallet_profile_sig (4h) | Top-3-ROI signature tags per wallet |
| PLAY verdict | copy_decision | COPY vs FRONT-RUN vs SKIP + TP profile |
| ⚡ EXECUTE row | trade_links | One-click GMGN/bot execution keyboard |
| GMGN links everywhere | gmgn_links v1.1 lib | Every $name / bare CA / wallet is clickable ([[feedback_gmgn_links_standard]]) |

```mermaid
flowchart TB
    SIG["raw signal (any detector)"] --> GATE{🚪 deployer<br/>BLACKLIST?}
    GATE -->|yes| DROP["dropped — only hard filter in system"]
    GATE -->|no| E1[✚ wallet-intel<br/>9 types·smart·fresh·dormant]
    E1 --> E2[✚ dormancy/freshness<br/>first-class dims]
    E2 --> E3[✚ volume 6-lens + deployer history + µTA/regime]
    E3 --> CARD["📇 TOKEN CARD → threads + master scanner<br/>with PLAY verdict + ⚡EXECUTE"]
```

**PRO:** one shared card = one shared mental model across 100+ jobs; cache-first = zero marginal cost; every enrichment field also lands in the outcome ledger, so enrichments are *backtestable*.
**CON:** card real-estate is finite (Telegram); each new block must earn its line. Regime enrichment is only as good as Tier-4 chart capture, which is still broken (§16).

---

## §7 — Layer 4 · Convergence & Conviction

### WHAT
- **`master_scanner_180`** (30m, thread 180): aggregates ALL signal sources; **2+ independent sources on the same token = high conviction**; maps source→quality for an accurate PLAY.
- **`conviction.py`** — boost-not-filter (P9): cross-confirm boosts (e.g. Downsin cipher + our native agree), KOL-cascade boost (dexLions), EARLY-GEM path for sub-threshold gems.
- **KOL labeling standard** — every caller carries TIER S/A/B/C/⛔ computed from expectancy+hit-rate+consistency+recency (script-computed ≈$0).
- **APEX Convergence Siren** (staged, shadow-only): WATCH→FLASHING→APEX→APEX PRIME escalation when many systems converge fast. Motivating case: ANSEM was caught by 14 systems / 321 events, earliest at 2.6 min = 625×.

```mermaid
flowchart LR
    S1["detector A"] & S2["detector B"] & S3["channel call (TIER-weighted)"] --> AGG["master_scanner_180<br/>30m aggregation window"]
    AGG --> C{"2+ independent<br/>sources?"}
    C -->|no| WATCH["single-source: report only ⚡EARLY-GEM path if gem-shaped"]
    C -->|yes| HI["HIGH CONVICTION → thread 180<br/>⚡boosts: cipher-agree · KOL-cascade · SM sub-$1M thesis fit"]
    HI -.->|future| APEX["APEX siren (event-driven)<br/>shadow-staged, gated on backtest"]
```

### WHY convergence is the top-level trade trigger
Independent-source agreement is the cheapest possible ensemble: each detector has low precision alone, but their false positives are nearly uncorrelated (different data, different logic). Agreement multiplies precision without any new data cost.

**PRO:** massive precision gain for free; naturally resistant to any single source degrading.
**CON:** the 30m polling window is the single biggest latency leak in the system — ANSEM-class moves are decided in minutes. **This is why the event bus (§17-A3) is the keystone architecture upgrade: APEX can't work properly on cron polling.**

---

## §8 — Layer 5 · Decision & Execution

### WHAT
- **`copy_decision.py` v1.1.1** — embodies the copy-timing edge as code. Inputs: wallet class (fresh/dormant/smart/cluster), buy size & quality (fresh+large-buy counts as quality — the Kien edge), MC band, convergence, regime. Output: **COPY / FRONT-RUN / SKIP** + sizing + TP profile. Gates tunable in `copy_decision_gates.json`.
- **`paper_trader` v1.1.0** — full simulated execution with cooldown + 5m maturation (fixes day-1 lesson: 3/3 SL from late entries — LAUNCH_HINT was age-blind).
- **Real rails** — GMGN-cli live, signing proven (Ed25519), 4 Base burner wallets, logging harness at `/opt/data/trading/`. **Awaiting funding — deliberately.** (P12: One Loop First; paper must prove the loop.)
- **⚡EXECUTE UX** — every card carries a one-click keyboard (GMGN link + TA-strategy ⭐ preset; bots config-gated in `exec_bots_config.json`). `trade_cmd.py` retired in favor of links: fewer moving parts, zero key custody in the hot path.
- **Sizing doctrine** — Quarter-Kelly, entry tiers by MC band, universal filters (Tier1 <$50K/<24h, Tier2 <$100K/<24h all chains).

```mermaid
flowchart TB
    IN["high-conviction candidate"] --> W{"wallet class?"}
    W -->|"smart + already pumped"| SKIP["SKIP — we are exit liquidity"]
    W -->|"fresh, large first buy"| FR["FRONT-RUN play<br/>(Kien edge: fresh+size = insider-shaped)"]
    W -->|"dormant awakening / cluster early"| COPY["COPY play + TP profile"]
    FR & COPY --> SZ["size: quarter-Kelly × MC tier × regime posture"]
    SZ --> PT["paper_trader 🔁outcome"] -.->|"gates pass at $ tier"| RT["real rails (funded)"]
```

**PRO:** decision logic is *explicit, versioned, and backtestable* — no vibes; the paper→real gating means the first funded dollar rides a proven loop.
**CON:** paper fills are optimistic (no slippage/MEV modeling yet — §17-P4); FRONT-RUN plays need faster convergence than cron latency allows (again §17-A3).

---

## §9 — Layer 6 · Learning Loop (the Karpathy Machine)

**This is the system's compounding engine — and currently its most dangerous bug lives here (§16-1).**

### The loop
```mermaid
flowchart LR
    SIG["every signal<br/>(outcome fields mandatory, P7)"] --> OT["outcome_tracker v1.1<br/>tracks fwd returns + 9 volume fields"]
    OT --> OL["outcome_ledger<br/>top-20% EV + p95 columns (P3)"]
    OL --> PE["param_evaluator v2.2<br/>EV + OOS + FDR across 9 buckets"]
    OL --> RE["replay_engine v2.1<br/>combo backtests vs control cohort"]
    PE & RE --> KP["karpathy_prep → 2× daily Karpathy review (LLM)<br/>6-step + STEP 2c regime cross-check"]
    KP -->|"promote GOLDEN / mutate challenger<br/>WHY required on every change"| WEIGHTS["detector weights · copy gates · card params"]
    WEIGHTS -.-> SIG
    GOLD["GOLDEN STACK: +4.2% net/trade (n=1,188)<br/>challengers GOLDEN-001/002 forward-grading"] --- KP
```

### WHY this design
- **FDR (false-discovery control) + control cohort + OOS split** — with thousands of param combos and power-law payoffs, naive backtests will always find fake gold. FDR and a control cohort are the statistical immune system.
- **Percentile tail columns everywhere** (p95, top-20% EV) — the alpha lives in the tail (P3/P4); every table must show it or the review LLM optimizes the wrong thing.
- **LLM only at the top** — measurement and evaluation are pure Python; the LLM (Karpathy review) only *interprets and proposes*, and its proposals still flow through versioned config changes.

**PRO:** genuine closed-loop self-improvement with statistical guardrails; cheap (2 LLM calls/day).
**CON / CRITICAL RISK:** *the loop is only as honest as the outcome tracker.* The 260629 BOMBSHELL: the tracker scored a 1000× winner as a net loser (141L/98W, max gain captured only +1.33) because tracking windows/caps clip moonshots → **the doom-loop down-weights exactly the strategies that make the asymmetric thesis work.** Fixing outcome-truth (window length, clamp policy, moonbag accounting) is **the single highest-ROI engineering task in the entire system** (§17-P1).

---

## §10 — Layer 7 · Wallet Intelligence & the Wallet DB

### WHAT
- **`wallet_db.json`** — ~1,719 wallets, keyed `chain:address`, 9 archetypes, tiered (tracked_alpha never gated), dormancy-flagged, **never deleted** (P2). #1 wallet: `0xa075aca8` ($390K/30d ETH).
- **Discovery inflows:** TDWA (`tdwa <CA>` — token → its profitable wallets/clusters), mega_cluster_discovery (7-method), EP-1..7, protrending_harvester, whale_cluster_expander, dune comb, onboard_whale (one-JSON onboarding).
- **Grading:** wallet_rankings.json (hourly, compound labels), 6-window param system (SNIPER window n=304 best sub-5min proxy), profile_sigs 🏆, asymmetry-ranked (expectancy/tail, not WR).
- **Cluster intel:** whalemover_intel (58 wallets/5 groups), funding-chain tracing, generation detection (15min), Whale Command dashboard per-whale tabs.

```mermaid
flowchart TB
    subgraph INFLOW["discovery (no hand-seeding — the mandate)"]
        TDWA["TDWA: token→wallets"]
        MCD["mega_cluster 7-method"]
        EP["EP-1..7 edge processes"]
        PTH["protrending_harvester"]
    end
    INFLOW --> Q{"🚪 approval queue 37479<br/>+ backtest proof (P5)"}
    Q -->|approved| WDB[("wallet_db 1719<br/>chain:address · P2 never delete")]
    WDB --> RANK["hourly rankings · 6-window params<br/>expectancy+tail ranked (P3)"]
    RANK --> USE["→ enrichment cards · detectors · copy_decision"]
    USE -->|"outcomes 🔁"| RANK
    WDB -->|dormant| FLAG["flagged, ranked lower,<br/>dormancy_scanner watches for awakening"]
    FLAG -->|awakens| USE
```

**WHY the DB is the moat:** every other layer is rebuildable from public data in days; the wallet DB + its outcome history is the *accumulated* asset — it embodies every backtest, every cluster trace, every graduation decision. This is why P2 (never delete) is absolute and why the 260617 drain incident got a same-day restore + bug post-mortem.

**PRO:** compounding, proprietary, cheap to maintain.
**CON:** growth without pruning → ranking quality must carry the load (mitigated by tiering); dormant majority creates scan cost (mitigated by dormancy flags).

---

## §11 — Layer 8 · Edge Discovery Program

**The mandate ([[feedback_edge_discovery_mandate]]):** continuously comb GMGN's already-computed data+filters to DISCOVER profitable wallets/clusters *without hand-seeding*, derive the underlying STRUCTURE, and find more of it. Standing habit: ≥1 new edge-combo proposal per session → queue 37479.

### The hard-gated operating loop
```mermaid
flowchart LR
    EX["EXPLORE<br/>comb GMGN data+filters"] --> PR["PROPOSE → queue 37479<br/>WITH reasons + cost"]
    PR --> AP{"🚪 Chris:<br/>approve?"}
    AP -->|deny/comment| EX
    AP -->|approve| BT["🚪 BACKTEST PROOF<br/>replay + outcomes + FDR vs control"]
    BT -->|fails| EX
    BT -->|passes| DEP["DEPLOY (versioned)"]
    DEP --> ME["MEASURE (ledger)"] --> PM{"promote or<br/>mutate?"} --> EX
```

### EP roster (status)
| EP | Idea | Status |
|----|------|--------|
| EP-1 | wallet leaderboard comb (fresh ranked by conviction) | v0.1.1 shipped |
| EP-2 | seedless multi-method cluster discovery (noisy-OR confidence) | v0.1.0 — known over-merge (160-blob) → EP-2.1 community detection needed |
| EP-3..6 | queued in 37479 | pending |
| EP-7 | fresh_predecessor_scanner — fresh $500+ buys BEFORE clusters, sub-$300k | **LIVE v3.0.0, cron 2h** |
| EP-9/10 | accumulation-engine spin-offs | queued |

**Cost by design:** V4 Flash ~$0.005–0.03/run; `token_cluster_intel.py` went $1.53 → $0.0001/run after cache-first rewrite — proof that the "comb smarter, not richer" doctrine holds.

---

## §12 — Layer 9 · Governance, Cost & Ops

| Mechanism | What it does | Why it exists |
|-----------|--------------|---------------|
| **hermes_todo queue → 37479** | Claude proposes numbered items; Chris replies approve/deny/done/comment | The single human gate; async so nothing blocks (P11) |
| **version_manager** | SemVer + snapshots on every component; VERSION_REGISTRY.md | Auditability of a self-modifying system (P6) |
| **Watchdogs** | health→kanban, cost watchdog, cron-fail tagging (💳/❌/⏰), fresh-only dedup 6h | Silent failure is the default failure mode of cron systems |
| **system_edge_digest (2×/day)** | System Improvements + cost-benefit · process-card scorecard · Dune-first alpha · AI take | Forces the system to explain itself daily; caught live 402 credit exhaustion + 31 cron fails |
| **Cost routing** | DeepSeek V4 = cheapest smart model, default; free-llama for watchdogs; NEVER route GLM/Kimi/Qwen "for cost" | 260618 lesson: burn was volume not price; trust cost_watchdog numbers only |
| **Ops dashboard** | 113 jobs, model routing, est $/day reconciles with real (~$3/day baseline) | One glance = whole system health |

**Cost model (target):** infra ~$10/mo + LLM ~$2–4/day + $0 data = the entire intelligence stack for under ~$150/mo. Every profit improvement is nearly pure margin.

---

## §13 — Layer 10 · Knowledge & Memory (the shared brain)

```mermaid
flowchart LR
    subgraph MAC["Mac / iCloud vault"]
        VAULT["Obsidian vault<br/>CLAUDE_MEMORY/ + session outputs"]
        CC["Claude Code sessions<br/>(memory symlinked to vault)"]
    end
    subgraph VPS["VPS knowledge layer"]
        KL["/opt/data/knowledge/<br/>learnings·spec·registry·intel files"]
        CI["conversation_intelligence.py<br/>distills sessions → intelligence_feed.md"]
    end
    CC <-->|"SessionStart hook loads MASTER_CONTEXT+MEMORY"| VAULT
    VAULT -->|"sync-to-hermes.sh (launchd 2h + watchdog)"| KL
    KL --> CI --> HERMES["Hermes jobs read distilled intel"]
    HERMES -->|hermes_learnings.md daily| KL
    KL -->|"session-start ssh cat"| CC
```

**WHY:** three brains (Chris, Claude, Hermes) must share one memory or they diverge. The vault is canonical (human-ownable, iCloud-synced, git-migratable); the VPS layer is the machine-readable projection. MEGA-TODO: port to private GitHub repo ([[project_memory_github_migration]]).

**PRO:** any new Claude session is fully context-loaded in one hook; Hermes learns from Claude sessions automatically.
**CON:** hermes_learnings.md accretes repetitive daily blocks (3,113 lines, mostly duplicate tables — §17-E4); spec staleness happens when the document-builds habit slips (this v5 closes a 3-week gap).

---

## §14 — Telegram Channel Map (Nousman HQ `-1003965540537`)

| Thread | Function | Producers |
|--------|----------|-----------|
| 180 | Master Scanner (convergence) | master_scanner_180, dune_alpha_comb |
| 181 | Signals (real-time) | doppler, watchlisted callers, detectors |
| 182 | Alpha briefings (2h cadence — NEVER cut slots) + TDWA + sapphy | alpha reports, sapphy_reporter, system_edge_digest (6am+3pm) |
| 185 | Sniper digest 3×/day | sniper synthesis |
| 186 | WhaleMover alerts | whalemover_tracker, sapphy reporter |
| 188 | TA channel (all chatter captured) | ta_link_ingest, userbot |
| 16 | Whales Alpha Methods (Kien) | whales_alpha_methods reporter |
| 200 | Runaway reaper reports | host cron |
| 201 | Deployer intel | deployer_enrich (4h) |
| 7423 | ProTrending in-house + EP proposals detail | protrending_scanner/runner, EP-2 |
| 37082 | Whale onboarding (pinned template) | onboard_queue_processor |
| 37479 | Roadmap/TODO queue — **the approval gate** | hermes_todo, Claude proposals, EP queue |

**Design rule:** one thread = one function; Chris's reply grammar (approve/deny/tdwa/comment) makes threads *bidirectional control surfaces*, not just feeds.

---

## §15 — Design Decision Log (the WHY table)

| Decision | Alternatives rejected | Why we chose this | Revisit when |
|----------|----------------------|-------------------|--------------|
| Wallet-and-moment edge (copy-timing) over token-picking | narrative trading, TA-first, sniping | Wallet behavior persists; tokens are one-shot; GMGN pre-computes the data | If wallet-copy alpha measurably decays (ledger will show it) |
| Cron fleet over event bus | event-driven from day 1 | Simplicity for a solo operator; each job independently testable | NOW — APEX + FRONT-RUN plays need minutes-latency (§17-A3) |
| Boost-not-filter conviction | hard filter stacks | One wrong filter costs a 100×; power-law payoffs punish false negatives ≫ false positives | Never fully — but deployer BLACKLIST stays a hard gate (scam ≠ alpha) |
| Approval+backtest gate on deploys | full autonomy | Statistical immune system + human judgment where it's cheapest (async reply) | If backtest infra becomes trusted enough for pre-approved classes |
| Paper before real $ (tiered gates) | fund immediately | Day-1 paper already caught late-entry bug; real $ would have paid for that lesson | Paper loop shows sustained positive expectancy at gate thresholds |
| DeepSeek default, Claude only interactive | Claude everywhere | 90%+ of jobs are formatting/synthesis; V4 is the cheapest smart model | Model price shifts (cost_watchdog tracks) |
| Vault as canonical memory | DB, Notion, GitHub-first | Human-readable, survivable, already Chris's daily tool | GitHub migration planned (private repo) — improves diff/versioning |
| Never delete wallets | prune losers | Dormant alpha wakes; association > performance (P10); deletion incident proved fragility | Never |
| Telegram as the only UI | web app first | Chris lives on phone; threads+reply-grammar = full control surface at $0 | Web exec panel is Phase-4 roadmap, additive not replacing |

---

## §16 — Known Issues & Risk Register (ranked)

| # | Issue | Impact | Status / next step |
|---|-------|--------|--------------------|
| 1 | **Outcome-tracker doom-loop** — 1000× winner scored as net loser (max gain captured +1.33); loop down-weights our best strategies | CRITICAL — corrupts the entire learning layer | ✅ **TRACKER SIDE FIXED 260705 (v1.2.0):** alpha view walks past SL (`alpha_class`/`alpha_return_pct`), moonbag accounting, `sl_recovered`, class-aware `win_final`, winner-follow 4h/24h/72h windows for signals peaking ≥+30%, attribution on class-final window (was hardcoded 1hr → never fired for fast classes). First live rows prove it: Indy booked SL_HIT (execution) with alpha TP3_HIT +208% peak. **REMAINING:** param_evaluator/Karpathy must switch discovery grading to alpha/moonbag fields once ~2wk of new-field data accrues |
| 2 | **Cron-polling latency** (30m convergence window) | HIGH — ANSEM-class moves decided in minutes; APEX blocked on it | ✅ **A3 SHIPPED 260706:** `event_bus.emit()` fire-time bus (accum_engine + whalemover wired); `apex_runner` v0.4.0 merges live events (dedup keep-earliest). **Backtest proof:** 69% of fires (334/486) would fire earlier under live emit, median 160min saved; WATCH-LATE tier (the too-late/ANSEM class) 94% would-earlier at 191min median. REMAINING: wire remaining detectors + a triggered sub-5min fusion loop |
| 3 | **WhaleMover captures no sells** → no net-position view | HIGH — copy decisions blind to distribution | ✅ **E2 SHIPPED 260706:** `wallet_sell_tracker` v2 captures tracked-wallet sells → `wallet_sell_events.jsonl` bus; paper_trader consumes it as `SM_DISTRIB` (block+force-close). REMAINING: surface a net-position line on WhaleMover cards + wire SM_DISTRIB as a live SKIP into copy_decision (not just paper) |
| 4 | **ta_capture.py broken** — 0/97k signals have TA fields → Tier-4 chart regime dead | MED — regime posture missing chart tier | Fix capture, then chart_regime.py |
| 5 | **EP-2 union-find over-merges** (160-wallet blob) | MED — cluster precision | EP-2.1 community detection (Louvain/Leiden) |
| 6 | Watchdog content-repetition blindspot (jobs "succeed" while repeating themselves) | MED | Add content-hash dedup check to watchdog |
| 7 | Paper fills optimistic (no slippage/MEV) | MED — will overstate paper edge | §17-P4 |
| 8 | hermes_learnings.md bloat (3.1k lines of duplicate daily tables) | LOW — brain noise, sync cost | §17-E4 compactor |
| 9 | 6 alpha channels still unjoined; caller scoring depends on Rick replies | LOW-MED | Self-outcome-track from GMGN (≈$0) |
| 10 | TG context limit on long Hermes chats; gptpro fallback | LOW | Pre-LLM gates continue |

---

## §17 — IMPROVEMENT ROADMAP

Ranked within each track by (expected impact ÷ effort). Every item flows through the queue (P5) before deploy.

### P — Profit improvements
| # | Idea | Why it pays | Effort |
|---|------|-------------|--------|
| **P1** | **Outcome-truth repair** (fix #16-1): extend tracking windows for moonbag legs, uncap tail capture (report clamped + raw), add "still-holding" accounting | The learning loop currently *punishes* 100× strategies; fixing this re-aims the whole machine at the asymmetric thesis. Highest ROI task in the system | M |
| P2 | **Fund the first tier ($300)** once paper shows 2-week positive expectancy post-P1 | Real fills teach what paper can't (slippage, MEV, timing); tiered gates cap downside by design | S (decision + transfer) |
| P3 | **Moonbag doctrine as code**: TP profile always leaves a tracked residual on FRONT-RUN plays; ledger gets a moonbag column | The tail is the thesis (P3 principle); today exits truncate it | S |
| P4 | **Slippage/MEV model in paper_trader** (simple: entry = signal price × (1 + MC-band slippage curve)) | Prevents funding a paper mirage | S–M |
| P5 | **Regime-gated sizing live** — wire the 3-tier regime posture directly into copy_decision size multiplier (currently advisory text) | Regime is computed but not mechanically consumed; free risk reduction | S |

### E$ — Edge & alpha-source improvements
| # | Idea | Why it pays | Effort |
|---|------|-------------|--------|
| E1 | **Serial early-winner intersection (proposed this session → queue):** for every token that did ≥10× in 7d (GMGN trending, all 4 chains), pull `token traders`, take the earliest-20 profitable buyers, intersect across winners → wallets that are early on *multiple* independent 10×s. Pure GMGN-data comb, no hand-seeding — the mandate's purest form | Serial earliness across independent winners is the strongest possible wallet signal; output feeds TDWA grading + EP gates | S–M |
| E2 | **Sell-side intelligence** (fix #16-3): capture smart-wallet *exits* → "smart money distributing" as a SKIP/TP trigger | Half the copy-timing edge (the WHEN-to-exit half) is currently blind | M |
| E3 | **Funding-chain frontrun**: when a known banker wallet funds N fresh wallets (ping/funding detectors exist), alert BEFORE first buy | Moves us from copying trades to anticipating them — the ultimate front-run | M |
| E4 | **Deployer-cluster alpha**: serial deployers whose tokens repeatedly graduate → pre-position on their next deploy (deployer DB already exists, 158 entries) | Reuses built asset; inverts blacklist logic into a whitelist edge | S |
| E5 | **Cross-chain wallet identity stitching** (bridge tracing via Blockscout) — same operator on Base+Sol | Operators rotate chains; our DB keys chain:address so we see two strangers | M–L |

### A — Architecture & design improvements
| # | Idea | Why | Effort |
|---|------|-----|--------|
| **A3** | **Event bus keystone** (approved-pending per APEX plan): detectors publish events; convergence/APEX consume in-memory; crons remain as fallback | Kills the 30m latency leak; enables APEX, FRONT-RUN timing, and E3. Extend master_scanner_180, don't duplicate it | M–L |
| A1 | **Signal schema v2**: one canonical signal envelope (source, wallet_refs, enrichments, outcome block) — today each detector's JSON drifts | Every downstream consumer simplifies; new detectors get outcomes for free | M |
| A2 | **Config unification**: gates/thresholds live in 4+ JSON files; one `master_filter_thresholds` with per-component overlays | One place for Karpathy to mutate; fewer drift bugs | S–M |
| A4 | **GitHub private-repo migration** of vault memory + scripts (planned) | Real diffs, PR-able changes by any LLM, CI hooks for version_manager | M |

### C — Cost & efficiency improvements
| # | Idea | Why | Effort |
|---|------|-----|--------|
| C1 | **Learnings compactor** (fix #16-8): nightly job rewrites hermes_learnings.md keeping only deltas + latest tables | Smaller brain = cheaper syncs + better LLM recall | S |
| C2 | **Watchdog content-hash** (fix #16-6) | Catches the "successful but repeating itself" failure class | S |
| C3 | **Batch GMGN pulls in accum/scanner runs** (shared cache window per 30m tick) | Fewer duplicate API hits across 113 jobs | S |
| C4 | **Job census & retirement pass**: ops dashboard flags jobs whose outputs nobody read/acted on in 30d → propose retirement (never auto-kill) | 113 jobs accreted; each idle job is cost + noise | S |

**Sequencing recommendation:** P1 → E1 (cheap, this week) → A3+APEX → E2/E3 → P2 funding gate. P1 comes first because *every* other improvement is graded by the ledger P1 repairs.

---

## §18 — Invocation Commands ([[feedback_always_include_invocation_commands]])

| Task | Claude (Mac) | Hermes (Telegram) |
|------|--------------|-------------------|
| Token deep-dive | `tdwa <CA>` in session | post `tdwa <CA>` in thread 182 |
| Wallet card | ask for wallet intel card | `intel <address>` (thread 182) |
| Read this spec | vault: `260705 System Architecture Master Spec/` | `docker exec hermes-agent-iczm-hermes-gateway-1 cat /opt/data/knowledge/hermes_trading_system_spec.md` |
| Queue a proposal | run `hermes_todo.py add ...` via SSH | reply in thread 37479 |
| Approve/deny | — | reply `approve N` / `deny N reason` in 37479 |
| Ops health | ops.srv1663871.hstgr.cloud | system_edge_digest lands 6am+3pm in 182 |
| Version check | — | `docker exec ... cat /opt/data/knowledge/VERSION_REGISTRY.md` |

---

## §18b — Spec ⇄ Site Version-Sync Protocol (260705, standing rule)

The interactive site **always shows the spec version it was generated from**, and every version is archived for rollback. The chain is automatic:

1. **Edit the spec** (vault canonical) → sync to `/opt/data/knowledge/hermes_trading_system_spec.md`.
2. **Bump via version_manager** (never edit VERSION_REGISTRY.md by hand — it is regenerated from `component_versions.json`):
   `python3 /opt/data/scripts/version_manager.py bump hermes_trading_spec <major|minor|patch> "why"`
   → auto-snapshots the previous spec into `/opt/data/_versions/hermes_trading_spec/`.
3. **Site follows automatically:** `arch_data_gen.py` (2h host cron @:41) reads the registry version → stamps the arch.html masthead/footer, and archives `arch_<ver>.html` + `spec_<ver>.md` into the public **[/versions/](https://whale-command.srv1663871.hstgr.cloud/versions/)** shelf (browsable, with `spec_current.md` always pointing at latest).
4. **Instant refresh** (don't wait for the tick): `docker exec hermes-agent-iczm-hermes-gateway-1 python3 /opt/data/scripts/arch_data_gen.py`.
5. **Rollback:** open any archived version from `/versions/`, or `version_manager.py rollback hermes_trading_spec <ver>` for the markdown.

**Cost of the site:** ≈ **$0 marginal**. Static HTML on the already-paid VPS (Traefik + gateway serve it); diagrams render client-side via the free jsDelivr mermaid CDN; the data generator is pure Python (no LLM, no paid API), ~3 s CPU every 2 h ≈ 36 s CPU/day; each archived version ≈ 120 KB disk.

## §19 — Changelog

- **v5.4.0 (260706 late)** — Chris: "analyze/score/improve APEX so the signal is improving" + graduate the EP-11 wallets. Both done:
  - **APEX self-improvement loop** (`apex_score` v1.0.0 daily · `apex_detector` v0.4.0 · `apex_weights` config v1.0.0). apex_score reads every APEX fire's realized outcome from `paper_ledger` and scores by tier / source / boost / entry-lateness on **expectancy + p95 tail** (P3, not WR), then retunes per-source weights (expectancy lift → weight, EMA-smoothed, clamped 0.6–1.5). apex_detector v0.4.0 now fuses on the **SUM of learned per-source weights** instead of a raw source count (defaults 1.0 = unchanged until data speaks). **Headline finding: APEX is currently net-NEGATIVE expectancy (-0.063 across 617 paper trades)** — the plain APEX tier is worst (-0.204, 18.5% WR), and the culprits are the `trench` (-0.44 exp, 7% WR) and `whalemover` (-0.44, 11% WR) sources plus the `reliable-caller` boost (-0.35, 7% WR). The loop applied v1 weights down-weighting all of them (trench 0.85, whalemover 0.85, reliable-caller 0.88) and up-weighting `trending` (1.09, the best source at +0.15); toxic-source-only convergences now fall below the FLASHING threshold. All shadow/paper, registry-snapshotted, reversible. Runs daily 13:40 UTC (`--apply --post`).
  - **EP-11 graduation** (`ep11_graduate` v1.0.0): Chris approved → 10 new serial-early wallets added to `wallet_db` (1526→1536) as archetype `SERIAL_EARLY`, `tracked_alpha`+`intel_only` (enriched/watched/never-deleted, but copy_decision returns INTEL_ONLY — copy-value gated until the forward-grade backtest earns a real grade). File-level DB backup taken first (P2).
- **v5.3.0 (260706 PM)** — Chris approved A3 + EP-11 ("keep it coming"). Both SHIPPED:
  - **A3 event bus** (`event_bus` v1.0.0 + `apex_runner` v0.4.0): `emit(source,chain,ca,…)` appends one canonical line to `detections.jsonl` at fire-time (atomic O_APPEND, never raises into caller). Wired into `accumulation_engine` + `whalemover_tracker` (additive — behavior unchanged if a detector doesn't emit). apex_runner now MERGES live events with its file rebuild (dedup by ca+source+5m-bucket, keep earliest ts) instead of clobbering them. **Backtest** (`apex_latency_backtest` v1.0.0): of 486 matched fires, **69% would fire earlier under live emit, median 160min saved**; the WATCH-LATE tier (fires downgraded because price already 2×'d since first-sight — the too-late/ANSEM class) is **94% would-earlier at 191min median latency**. That is exactly the latency live emit removes. PRIME siren already posts live to 182; other tiers stay shadow until paper proves them.
  - **EP-11 serial early-winner intersection** (`edge_ep11_serial_winners` v0.1.0, daily 13:00 UTC, proposal-only): combs GMGN trending (24h, 4 chains) → winners with `history_highest_market_cap` ≥ $500k that did ≥10× within 3d (kline-confirmed) → for each, `token traders` order-by profit → `realized_profit`>0 (ROI filter) → sort by `start_holding_at` (entry filter) → earliest ~20 → intersect wallets early+profitable on ≥2 **independent** winners (distinct token AND creator). **First run: 12 serial wallets, 8 new; the #1 result (`0x9999b0cd`, early+profitable on 4 winners, $122k) was ALREADY in wallet_db** — the method rediscovering known alpha unprompted = self-validation. Proposals → thread 7423; graduation gated on `approve ep11` + forward-grade backtest (never auto-adds). Queue #53 marked approved/built.
- **v5.2.0 (260706)** — Chris-approved roadmap batch shipped to `paper_trader` **v2.2.0**: **P3** moonbag/runner-bag (was already v2.1.0 — TRAIL closes 75%, keeps 25% at loose 50% trail; CZ +214% lesson); **P4** slippage fills (SNIPE 2.5% / MOMENTUM 1.5% / SWING 1%, applied to entry AND exit) so paper P&L isn't a mirage; **P5** regime→sizing made mechanical (paper size = $100 × `copy_decision_gates.regime_size_mult`, same config the copy engine uses — contrarian: bull 0.7× / ground 1.0× / poor 1.1× / extreme_poor 1.2×); **E2** sell-side intelligence LIVE — `wallet_sell_tracker` v2 (Hermes cron 30m) captures tracked-wallet sells to `wallet_sell_events.jsonl`; paper_trader now treats **≥2 distinct tracked wallets selling a CA within 6h** as `SM_DISTRIB` → blocks new entries and force-closes open positions (full exit, no bag). **Live proof:** first run force-closed 中公教育 at **+142%** (peak +174%) and TUT at **+51%** — winners the trailing stop alone was giving back. Open tunable: `DISTRIB_WALLETS=2 / DISTRIB_WINDOW=6h` — the ledger will show whether SM_DISTRIB exits beat let-ride.
- **v5.1.0 (260705 PM)** — Chris approved "fix all these". SHIPPED: (1) **outcome_tracker v1.2.0 doom-loop fix** (§16-1, alpha view + moonbag + winner-follow + class-aware wins; snapshot of v1.1.0 in `_versions/`); (2) **arch.html Architecture Explorer LIVE** at whale-command `/arch.html` (clickable master diagram, 19 process drill-downs, live benefit-vs-cost via `arch_data_gen.py` v1.0.0, 2h host cron @:41, cross-linked from ops.html); (3) **learnings_compactor v1.0.0** (C1, daily 4:17). LIVE DATA FINDING: paper trader 401 closed trades, P&L −$6,180, WR 19%, **p95 peak +326%** — entries find winners, exits give them back → same doom-loop pattern in paper exits; fix = moonbag/trailing exit doctrine (P3) + evaluator switch to alpha fields after data accrual. Paper ledger already runs APEX-tier lanes (A/B/C sizing experiment).
- **v5.0.0 (260705)** — Full architecture rewrite: 10-layer model, master + 9 supplemental mermaid diagrams, WHAT/WHY/HOW/PRO/CON on every layer, design-decision log (§15), risk register (§16), ranked improvement roadmap (§17). Incorporates everything shipped since v4.0.1: copy_decision engine, master_scanner_180, conviction, accumulation_engine, paper_trader, APEX staging, deployer intel, protrending harvest, profile_sigs, dormancy first-class, EP-7, gmgn_links standard, system_edge_digest, runaway_reaper, cron stagger, KOL labeling.
- v4.0.1 (260613) — prior spec (detector/wallet-intel/AlphaFeed detail; still valid as component-level reference).