AlphaForge — System Handbook

1What this system is

AlphaForge is a self-improving systematic trading research platform that runs unattended on a small VPS. It operates two markets:

The defining design choice: improving the system is itself a subsystem. Signal weights adapt daily from measured accuracy; strategy changes must survive a purged 2015–2024 walk-forward and ten statistical gates; a nightly OODA loop reviews each day's real decisions and proposes one experiment per night; every lesson is written down permanently and machine-enforced where possible. Nothing changes on opinion.

2Where the edge is — a measured answer, not a belief

Months of gated experiments converge on one conclusion: allocation is the edge; stock selection has not been.

The decisive measurement (2026-07-01 ablation, 2015–2024, identical frictions for every arm):

The trained picker earned less than random selection under the same sizing. Every accepted experiment in the ledger is allocation-side (bear gate, continuous GMM sizing, concentration caps, pure benchmark core, reversal sizing, conditional leverage). Consequently the live book holds the market itself, sized by regime — and the individual-name machinery runs in advisory shadow mode, graded daily (§15), until a names-strategy beats the core through the full gate battery. Nothing is discarded; it is held to evidence.

3Track record & honesty rules

The honesty rules that produce these numbers

• Point-in-time everywhere: survivorship-free S&P membership (delisted names included), EDGAR fundamentals keyed by filing date, purged/embargoed training windows, frozen per-year models.
• Live-only signals never enter backtest evidence (law L10) — no retroactive credit for data that has no honest history.
• 2025 is a locked holdout the optimization loop cannot touch, and holdout results never feed hypothesis selection.
• A rising evidence bar: the deflated-Sharpe threshold increases with every experiment tried — the loop gets harder to impress the longer it searches (multiple-testing correction).
• Costs are modeled: 8bps one-way + square-root market impact + 5%/yr margin financing on any levered day.

4Risk architecture (defense in depth)

5The real-money bar

6Architecture map

INFRA    QuestDB (bitemporal store) · Redis Streams (signals/kill/heartbeats) · Watchdog
TIER 3   Daily Switch (nightly): universe → regime → fundamentals → sentiment → capital allocation
TIER 2   AI Brain (every 10 min): freshness gate → xreg → TimesFM quantiles → decision engine
TIER 1   Live Risk (continuous): P&L ticks · noise band · risk matrices · kill switch · reconciler
TIER 4   Research (nightly): attribution → scorecard → drift → hypotheses → shadow backtest
         → champion/challenger → promotion gate (human-approved only)
─────────────────────────────────────────────────────────────────────────────
CLASSIC  The validated daily strategy (host venv): screen → verdicts → orders at 14:55 ET

The two surfaces share repo, config, and credentials but run independently: the classic daily strategy is the validated track that trades; the Beast is the always-on research/monitoring stack whose intraday engine must still earn promotion (§12, §14).

7Data layer

8The five thinking parts

Plus ~10 frozen wf_*.pkl walk-forward snapshots used only to measure historical performance honestly. They never trade.

9US daily decision pipeline — layer by layer

10How a daily verdict is made (Ticker Inspector)

For any ticker, the UI reconstructs the exact live-engine reasoning:

1. Score vs floor — final blended score against the 0.55 entry floor, with the full layer attribution table (exactly which signal added or subtracted how much).
2. Rank vs regime budget — is it inside today's top-N for the current regime tier?
3. Rotation edge — an incumbent is only displaced if the challenger beats it by ≥ 0.05 (churn costs money).
4. Stop ladder — the regime hard stop, catastrophic stop, trailing stop and time exit drawn on the chart.
5. AI-brain second opinion — T2's independent TimesFM-based verdict (§12) plus a CONFIRMED/CONFLICT consensus banner between the two engines.

Verdict vocabulary: BUY / WATCH / HOLD / SELL / AVOID (US, advisory while the core trades) and STRONG BUY → SELL (BVMT, always advisory, always carrying the backtest caveat).

The same tab carries two further modes. Smart search: a Compass-style filter-query bar across the US screen and BVMT factor screen (webui/search.py). Monte Carlo (webui/montecarlo.py, /api/montecarlo/{ticker}): simulate up to 10,000 possible price futures for any US or BVMT name, resampled from that ticker's own cached daily history — models are i.i.d. bootstrap, block bootstrap (preserves volatility clustering), or GBM; controls cover horizon, path count, lookback, annualized drift/vol overrides, invested amount, and seed. Output is percentile fan bands, a terminal-return distribution, and tail stats (P(loss), VaR/CVaR 95, max drawdown). Data-error days (|move| > ~50%, the known spike/zero-row cache artifacts) are dropped and counted, and a sub-one-year sample triggers an explicit "drift estimate is noisy" warning. It is a visualization of the historical return distribution only — deliberately advisory, feeding no score, no verdict, and no live state.

11The Beast — four tiers on four clocks

12T2 decision engine, gate by gate

The intraday engine is a challenger, not the validated strategy — its daily-blend cousin measured −9.87pp and was removed (exp0022). It must earn promotion through T4 with out-of-sample evidence. Its live record started 2026-07-17 after threshold recalibration.

13Self-learning — seven loops, each with a written gate

The evolve loop (structural learning)

baseline → propose (backlog + OODA nominations + registry candidates + optional LLM)
        ↳ the LLM proposer is the ONLY replenishing source: once the static
          backlog is spent, an LLM outage means "pool exhausted" and the loop
          exits rc=0 having learned nothing. Model id: alphaforge/llm.py
          (one definition, GROQ_MODEL overrides) — see the 2026-08-21 changelog.
        → guardrails (static veto: banned features, regime-in-model, momentum saturation)
        → precheck (1-year WF, minutes — catches crashes & catastrophes)
        → full purged walk-forward 2015–2024
        → gatekeeper G1–G10 (two acceptance routes: CAGR or risk)
        → accepted: overlay merges into baseline, git commit, LIVE runner parity required
          rejected: overlay dropped, never applied
        → lesson appended to memory/LESSONS.md either way — feeds the next iteration

The recursion is deliberately conservative: the ledger dedups every overlay ever tried (the ledger is part of the migration payload — L24), rejected categories sort to the back of the queue, and the deflated-Sharpe bar only rises. The loop cannot edit its own gates.

14Gates, guardrails & laws

Gatekeeper — ten gates, two routes

Laws (machine-enforced where possible; each cost real money to learn)

15Reports & observability

The counterfactual ledger — the "should we ever pick names?" mechanism

Every real decision day is graded next-close against the implementable alternatives, so vetoes and capital budgets become statistics instead of anecdotes:

Each day's top-N is also re-graded at +1/3/5/10/20-day horizons as closes mature — a swing that fades by day 5 should not count as regret.

Daily counterfactual gap report (added 2026-08-07)

AlphaForge's version of the predecessor project's (ai_portfolio_experiment_v2) daily "Counterfactual Gap Analysis" recap, adapted to data this project actually has — computed from real journal/ledger/OODA records, never estimated. Runs automatically every trading night inside the nightly OODA pass (right after the counterfactual ledger grades whatever became newly gradable that night — a decision day needs the NEXT trading day's close before it can be graded, so this always has fresh numbers, never runs on its own ungradable same-day). Writes reports/daily-adjustment/ {date}.md: prior/EOD equity, day P&L vs the do-nothing floor, the real close-to-close counterfactual policies from the ledger above, fired reason codes, dev==prod deployment check, cumulative track record. The satellite-capital wording in this report is derived from benchmark_core.weight at render time, not hardcoded — it spent 2026-08-08..09-06 asserting the satellite was "0% live capital" after the sleeve had already gone live at 5%, which under-rated how much of the topN_eq ceiling was already fundable inside an approved budget. Self-healing — any date missed on a prior night gets its report the first night it matures. Unlike the general reports/ tree (mostly one-off analysis, gitignored), this specific subdirectory is git-tracked and synced nightly so it's readable on the desktop, same tier as journal/state/counterfactuals.

Trend-following satellite — forward shadow tracker (added 2026-08-07)

Diagnosis: the live book never holds a multi-quarter secular winner (e.g. PLTR) because (a) the blend's non-ML 40% is deliberately mean-reversion (§2's L1, a tested two-sided optimum, not reblendable) and (b) the two existing satellites (§9 below) are both short-horizon (3-30 day) setups, too short to ever hold a trend that plays out over months. alphaforge/portfolio/trend_following.py is a THIRD, orthogonal satellite mode: intermediate (12-1 month) momentum gated by a long-horizon SMA50/SMA200 golden-cross structure, meant to run at a much longer min_hold_days (~60) than the other two when active.

Shadow-only at the time of writing, and not through the evolve loop. config/LIVE_BASELINE_FREEZE.md forbade editing baseline_overlay.json/live_baseline.json before 2026-10-13 (a 3-month clean-paper-record policy; the clock was consciously reset to 2026-11-08 by the 2026-08-08 activation itself), and the ledger's own strongest lesson (exp0081) says five prior satellite-mechanism attempts all failed the same gates regardless of selection philosophy, concluding the gates may reject the mechanism itself, not any one selector — so this was deliberately tested and tracked, not silently activated. scripts/momentum_sleeve_sweep.py answers the historical (2015-2024 walk-forward) question directly: does ANY nonzero satellite weight (swept 5/10/15/20%) clear the gates with this genuinely orthogonal signal — see reports/momentum_sleeve_sweep_*.md for the honest result. Separately, scripts/trend_sleeve_shadow.py tracks what the sleeve would do FORWARD, starting 2026-08-07 — real (not backtested) evidence, originally at zero live capital and now running alongside the live 5% sleeve as an independent shadow. Runs nightly via the OODA pass, writes artifacts/live/trend_sleeve_shadow.json, never touches the frozen config files, never submits an order.

Everything else

• Weekly report card (Sat 09:00 ET, committed to git, rendered in the UI's Reports tab): live vs SPY, experiments run, commits, reason codes, out-of-universe movers. Both sides are measured Friday→Friday: the live equity series is seeded with the last journal mark strictly BEFORE the week, the same window _spy_ret() uses, so the two are comparable (fixed 2026-09-06 — see the changelog).
• Telegram: tick done/skipped/crashed, watchdog kills and remediations, clock drift, boot notifications, self-learning outcomes.
• Web UI (Tailscale-private + public HTTPS front door with RBAC): Overview, Ticker Inspector, BVMT, Self-Learning dashboard, Reports, Control, Console, Accounts, Health.
• The one log that matters daily: artifacts/reports/live_run.log.

16BVMT (Tunis) pipeline

A transparent factor screen — deliberately not ML (too little honest point-in-time data to validate one):

• Factors: momentum 0.40 (tanh-blended multi-window) · value 0.35 (1/PE, 1/PB, dividend yield percentiles) · technical 0.25 (price vs SMA20/60 + up/down-volume balance). Liquidity floor 2,000 TND 20-session dinar volume plus a trading-frequency filter (a print on ≥ half the trailing 60 sessions) that halved backtest drawdown by excluding rarely-traded names that cleared the dinar floor on one chunky print.
• Verdicts: top-5 liquid with all factors ≥ 0.6 → STRONG BUY · top-10 liquid → BUY · illiquid top-decile → WATCH · bottom quartile → SELL. Every BUY carries the backtest caveat.
• The honest card, shown in the UI: 14.4 years, monthly top-N vs equal-weight market, 60bps/side — still FAIL (5.2%/yr at −40% DD vs market 6.0% at −28%). Same lesson as the US: ownership beat picking. The ranking is research, not a money machine.
• Real benchmark: the actual TUNINDEX (PX1, 2010→present) is cached for honest regime work; headline-tone sentiment was tested and found actively misleading (PR-framed "resilience" headlines scored positive while earnings fell 43%) — it is deliberately NOT wired in.

17Operations & failure modes (learned the hard way)

Timer table (systemd, self-installing from git)

Incident learnings now baked into the system

Changelog — this document

This is a living document. Whenever functionality it covers is added or modified, the relevant section AND this changelog must be updated in the same change.