Merge pull request #5 from HanSun103/agent/live-forward-readme

Redesign live-forward research and documentation

Author: HanSun103

.gitignore

@@ -39,3 +39,6 @@ data/raw/fnspid_source/
 Thumbs.db
 
 /pokestock-catalog-fix/
+
+# Local Codex research skills and accumulated private knowledge
+/local_skills/

README.md

@@ -0,0 +1,23 @@
+# Preregistered matched comparison of one-, two-, and four-week forecast horizons.
+experiment:
+  id: forecast_horizon_sweep_v1
+  status: development_horizon_selection
+
+forecast_horizon_sweep:
+  horizons: [5, 10, 20]
+  training_cutoff: "2021-01-01"
+  test_start: "2021-01-04"
+  selection_end: "2022-12-30"
+  confirmation_start: "2023-01-03"
+  test_end: "2023-12-29"
+  ridge_alpha: 10.0
+  feature_count: 40
+  holdings: 40
+  maximum_sector_fraction: 0.25
+  sentiment_arms: [false, true]
+
+inputs:
+  features: data/processed/residual_rank_v2_repaired/features.parquet
+  prices: data/processed/residual_rank_v2_repaired/prices_repaired_aliases.parquet
+
+output: reports/experiments/forecast_horizon_sweep_v1

configs/experiments/forecast_horizon_sweep.yaml

@@ -0,0 +1,140 @@
+experiment:
+  id: live_forward_horizon_matched_v2
+  status: paper_live_research
+  version: 2
+
+live_forward_20d:
+  horizons: [20, 10, 5]
+  primary_horizon_sessions: 20
+  comparison_design: horizon_matched_refit_and_rebalance
+  refit_sessions_by_horizon:
+    5: 5
+    10: 10
+    20: 20
+  rebalance_policy:
+    active: full_top40_refresh_on_horizon_clock
+    status: under_audit
+    buffer_enabled: false
+    next_comparison:
+      - full_refresh
+      - frozen_holdings
+      - rank_margin_buffer
+      - score_percentile_buffer
+  training_lookback_sessions: 756
+  holdings: 40
+  invested_weight: 1.0
+  maximum_sector_fraction: 0.25
+  feature_count: 40
+  minimum_sentiment_coverage: 0.01
+
+  live_data:
+    refresh_by_default: true
+    recent_training_start: "2021-01-01"
+    lookback_days: 2200
+    nlp_history_days: 90
+    maximum_news_staleness_hours: 72
+    finbert_local_files_only: true
+    split_cache_file: data/cache/yfinance/split_events.csv
+    sector_file: data/processed/residual_rank_v2_repaired/inferred_sector_history.csv
+    cache_root: data/cache/live_forward_20d
+
+  model_selection:
+    enabled: true
+    rank_config: configs/experiments/sparse_rank_v3_fnspid_2018_2023.yaml
+    validation_sessions: 42
+    folds: 5
+    ridge_optuna_trials: 30
+    xgb_optuna_trials: 25
+    timeout_seconds: 7200
+    selection_metric: top40_raw_excess
+
+  models:
+    ridge:
+      alpha: 10.0
+    xgb_ranker:
+      n_estimators: 200
+      max_depth: 3
+      learning_rate: 0.03
+      subsample: 0.8
+      colsample_bytree: 0.8
+      reg_lambda: 10.0
+      random_state: 42
+      n_jobs: 4
+
+  universe:
+    maximum_names: 250
+    liquidity_lookback_sessions: 63
+    minimum_names: 40
+
+  survival_guardrail:
+    label_horizon_sessions: 63
+    validation_sessions: 252
+    training_lookback_sessions: 756
+    training_stride_sessions: 5
+    target_recall: 0.90
+    minimum_yearly_recall: 0.80
+    maximum_exclusion_fraction: 0.25
+    activate_ml_exclusions: true
+    hard_event_types:
+      - index_deletion
+      - delisting
+      - bankruptcy
+      - completed_acquisition
+      - trading_suspension
+    features:
+      - momentum_21
+      - momentum_63
+      - vol_21d
+      - vol_63d
+      - rolling_beta
+      - idiosyncratic_vol
+      - cs_return_rank
+      - log_volume
+      - volume_ratio_20d
+      - rsi_14
+      - bb_pct
+      - atr_14
+      - overnight_gap
+      - sector
+
+  tactical_sentiment:
+    enabled: true
+    timezone: America/New_York
+    strategic_news_cutoff: "15:45"
+    same_close_available_cutoff: "15:30"
+    order_freeze_time: "15:45"
+    processing_latency_minutes: 15
+    maximum_news_age_hours: 4
+    minimum_scope_confidence: 0.70
+    minimum_relevance: 0.70
+    minimum_sentiment_confidence: 0.70
+    minimum_absolute_sentiment: 0.25
+    minimum_confirming_sources: 2
+    maximum_pre_signal_move: 0.03
+    maximum_overlay_weight: 0.05
+    maximum_combined_ticker_weight: 0.15
+    maximum_daily_turnover: 0.10
+    signal_expiry_sessions: 2
+    cooldown_sessions: 2
+    same_close_enabled: false
+    broker_cutoff: null
+    primary_sources:
+      - sec
+      - exchange_notice
+      - court
+      - issuer_release
+
+  evidence_gates:
+    early_matured_forecasts: 60
+    preliminary_matured_forecasts: 252
+    promotion_matured_forecasts: 504
+    promotion_nonoverlapping_blocks: 24
+
+inputs:
+  features: data/processed/residual_rank_v2_repaired/features.parquet
+  prices: data/processed/residual_rank_v2_repaired/prices_repaired_aliases.parquet
+  membership: data/raw/sp500_ticker_start_end_source.csv
+  posts: data/raw/nlp_posts.parquet
+  corporate_events: data/raw/corporate_events.csv
+
+output: reports/live_forward_horizon_matched_v2

configs/experiments/live_forward_20d.yaml

@@ -0,0 +1,36 @@
+# Historical replay of the current live-forward monitor. This is intentionally
+# separate from the weekly five-session final reference.
+experiment:
+  id: live_settings_backtest_v1
+  status: observed_historical_diagnostic
+  description: Daily one-session replay of the current live monitor contract
+
+live_settings_backtest:
+  start_date: "2023-01-03"
+  end_date: "2023-12-28"
+  holdings: 40
+  label_horizon_sessions: 1
+  training_lookback_sessions: 644
+  validation_days: 42
+  tuning_folds: 5
+  purge_days: 1
+  ridge_optuna_trials: 50
+  xgb_optuna_trials: 50
+  selection_metric: top40_raw_excess
+  one_way_cost_bps: 8.0
+  fixed_fee_per_trade: 10.0
+  starting_capital: 1000000.0
+  bootstrap_samples: 5000
+  block_days: 20
+  permutation_samples: 100
+  seed: 42
+
+inputs:
+  prices: data/processed/residual_rank_v2_repaired/prices_repaired_aliases.parquet
+  membership: data/raw/sp500_ticker_start_end_source.csv
+  sector_history: data/processed/residual_rank_v2_repaired/inferred_sector_history.csv
+  live_panel_cache: data/processed/live_settings_backtest_v1/features.parquet
+  rank_config: configs/experiments/sparse_rank_v3_fnspid_2018_2023.yaml
+  spy_prices: data/cache/yfinance/spy_2017_2023.parquet
+
+output: reports/experiments/live_settings_backtest_v1

configs/experiments/live_settings_backtest.yaml

@@ -1,5 +1,11 @@
 # Live-Forward Monitoring
 
+> **Legacy specification:** This document describes the archived one-session
+> live experiment. Do not add its outcomes to the new 20-session evidence
+> record. See
+> [the horizon decision](experiments/2026-07-28-live-horizon-decision.md) and
+> [the 20-session redesign draft](design/LIVE_FORWARD_20_SESSION_DRAFT.md).
+
 ## Purpose
 
 The live-forward experiment tests whether two independently tuned ranking models can select stocks
@@ -179,3 +185,18 @@ The complete historical portfolio comparison is recorded in the
 [Ridge-XGBoost ensemble experiment](experiments/2026-07-27-ridge-xgb-rank-ensemble.md).
 It includes compounding, identical execution costs, SPY, risk metrics, moving-block confidence
 intervals, a shuffled-score placebo, and a final chronological-fold check.
+
+## Live rebalancing ablation
+
+`run_live_rebalance_ablation()` compares each model's actual daily frozen selections with two
+controls beginning from the same decision date:
+
+- **Frozen names, buy and hold:** buy the first top 40 once and allow weights to drift.
+- **Frozen names, equal weight:** keep the first top 40 but apply the normal execution threshold
+  around equal weights. This separates membership changes from weight drift.
+- **Daily selection:** use the top 40 that was genuinely frozen after each completed close.
+
+All arms use the same cached adjusted closes, starting capital, spread/slippage assumption, fixed
+trade fee, and completed close-to-close sessions. The report intentionally emphasizes cumulative
+return, cost drag, turnover, trades, and drawdown; annualized statistics are not meaningful for a
+handful of live observations.

docs/LIVE_FORWARD_MONITOR.md

@@ -1,9 +1,45 @@
 # Project status, limitations, and improvement roadmap
 
-Status date: 2026-07-17
+Status date: 2026-07-29
 
 ## Executive summary
 
+The live research direction was revised after a matched zero-cost forecast-
+horizon comparison. Using the same frozen Ridge winner-selection design,
+20-session forecasts produced the strongest 2021-2023 point estimate and rank
+IC, while 10-session forecasts were a statistically indistinguishable
+challenger. The project therefore adopts 20 sessions as the leading live-test
+horizon, preserves 10 sessions as a mandatory paired challenger, and archives
+the one-session monitor as a legacy diagnostic. This is a research-design
+decision, not a validated-alpha claim. The paper-live runner is now implemented
+as `python -m src.cli run-live-forward-20d`; it creates daily overlapping
+forecast cohorts and separately tracked horizon-matched strategies. Five-day
+arms refit and rebalance every 5 sessions, ten-day arms every 10, and
+twenty-day arms every 20. The first refreshed v1 run was frozen on 2026-07-28
+under the earlier shared-20-session clock after live market and news refresh,
+strict FinBERT processing, and independent purged Optuna searches. It remains
+an immutable operational record and has no matured outcomes. The corrected v2
+history begins in `reports/live_forward_horizon_matched_v2/`. See
+[`experiments/2026-07-28-live-horizon-decision.md`](experiments/2026-07-28-live-horizon-decision.md)
+and
+[`design/LIVE_FORWARD_20_SESSION_DRAFT.md`](design/LIVE_FORWARD_20_SESSION_DRAFT.md).
+The first-run audit is
+[`experiments/2026-07-28-live-forward-20d-first-run.md`](experiments/2026-07-28-live-forward-20d-first-run.md).
+
+A six-session July 20–28 ablation now audits the assumption that every
+rebalance should fully replace the top 40. Freezing the July 20 names improved
+Ridge by 3.93 percentage points net, while daily XGBoost replacement improved
+by only 0.53 point net after costs. Daily turnover was 615.6% for Ridge and
+661.6% for XGBoost including initial purchases, compared with approximately
+100% for frozen buy-and-hold portfolios. This supports eliminating daily full
+replacement but does not validate a permanent freeze or a buffer from only six
+sessions. The horizon-matched v2 full-refresh policy is therefore explicitly
+under audit; the next preregistered comparison is full refresh versus frozen
+holdings versus model-specific rank- and score-margin buffers. See
+[`experiments/2026-07-29-live-rebalancing-ablation.md`](experiments/2026-07-29-live-rebalancing-ablation.md).
+The controlled follow-up protocol is documented in
+[`design/REBALANCE_BUFFER_EXPERIMENT.md`](design/REBALANCE_BUFFER_EXPERIMENT.md).
+
 The newest repaired development run supports a sharper project direction: ML-based weekly stock
 selection is the strongest current signal. After repairing suspicious price-history truncations,
 the full weekly rank-40 portfolio returned 37.22% net CAGR from 2020-04-24 through 2023-06-30,

docs/PROJECT_STATUS.md

@@ -36,6 +36,7 @@ decision explicitly says they are active.
 ## Final Architecture And Design History
 
 - [Final evidence-backed system proposal](design/FINAL_SYSTEM_PROPOSAL.md)
+- [Rebalance-buffer experiment draft](design/REBALANCE_BUFFER_EXPERIMENT.md)
 - [Next research direction: transparent selection, topics, LLM events, and pairs](design/NEXT_RESEARCH_DIRECTION.md)
 - [Sentiment and event overlay](design/SENTIMENT_EVENT_OVERLAY.md)
 
@@ -45,6 +46,12 @@ decision explicitly says they are active.
 
 ## Experiment Logs
 
+- [2026-07-29 - Live daily-selection versus frozen-holdings ablation](experiments/2026-07-29-live-rebalancing-ablation.md)
+- [2026-07-28 - First refreshed 20-session live-forward run](experiments/2026-07-28-live-forward-20d-first-run.md)
+- [2026-07-28 - Live horizon evidence and design decision](experiments/2026-07-28-live-horizon-decision.md)
+- [2026-07-28 - Matched 5/10/20-session forecast-horizon sweep](experiments/2026-07-28-forecast-horizon-sweep.md)
+- [2026-07-28 - Legacy live-settings backtest](experiments/2026-07-28-live-settings-backtest.md)
+- [2026-07-27 - Ridge-XGBoost rank ensemble](experiments/2026-07-27-ridge-xgb-rank-ensemble.md)
 - [2026-07-20 - Model-specific tuning and ensemble v10](experiments/2026-07-20-double-ensemble-v10.md)
 - [2026-07-20 - Qlib Alpha158 and LightGBM U.S. comparison](experiments/2026-07-20-qlib-alpha158-us.md)
 - [2026-07-17 - Survival-risk filter diagnostic for v8](experiments/2026-07-17-survival-filter-v8.md)