feat: expand performance report diagnostics

Author: magnaprog

PERFORMANCE.md

@@ -12,7 +12,11 @@ Use a licensed or otherwise permitted wide adjusted-close CSV:
 ```bash
 PYTHONPATH=. python scripts/generate_report.py \
   --prices-csv local_data/rotation_prices.csv \
-  --start 2018 --end 2025 --n-trials 10
+  --start 2018 --end 2025 --n-trials 10 \
+  --data-provider "$DATA_PROVIDER" \
+  --permission-basis "$DATA_PERMISSION_BASIS" \
+  --retrieved-at "$DATA_RETRIEVED_AT" \
+  --adjustment-method "$DATA_ADJUSTMENT_METHOD"
 ```
 
 The required columns are documented in `local_data/README.md`. The command
@@ -23,6 +27,9 @@ state into the requested evaluation window, and excludes the pre-roll returns
 from reported metrics. The source must contain at least 274 pre-evaluation
 sessions. Use `--warmup-years 0` only when a deliberately cold-started report
 is appropriate; that override is disclosed in the generated settings.
+The provenance options record owner-supplied facts and assertions; they do not
+constitute independent verification that publication or redistribution is
+permitted. Missing fields are labeled incomplete in the report.
 
 For an explicitly requested live download:
 
@@ -38,21 +45,34 @@ exact reproduction matters.
 
 ## Generated Artifacts
 
-The reference report currently produces three plots:
+The command writes `reports/report.md` plus these plots under `reports/img/`:
 
+- `report_overview.png`: equity, drawdown, allocation, turnover, and costs in a
+  compact review image.
 - `equity_vs_benchmarks.png`: strategy net of modeled costs versus gross SPY
   and equal-weight buy-and-hold benchmarks.
 - `drawdown.png`: the strategy underwater curve.
 - `rolling_sharpe.png`: trailing 126-session Sharpe.
-
-It also prints performance metrics, evaluation settings, data provenance, and a
-monthly-return table. Outputs remain ignored under `reports/`; do not copy them
-into the README without a redistributable input dataset and complete provenance.
-
-For an external investment review, also generate exposure/cash, turnover and
-cumulative cost, rolling volatility and beta, walk-forward boundary, and
-liquidity/capacity sensitivity diagnostics. Those plots require additional
-inputs or engine semantics and are not implied by the current report command.
+- `rolling_risk.png`: trailing 126-session annualized volatility and beta to
+  SPY.
+- `allocation_and_exposure.png`: post-trade asset weights, invested gross
+  exposure, and cash.
+- `turnover_and_costs.png`: executed one-way turnover and the cumulative sum of
+  modeled per-period cost fractions.
+- `monthly_returns.png`: monthly net-return heatmap.
+- `return_distribution.png`: daily net-return histogram, historical tail
+  markers, and a normal Q-Q diagnostic.
+
+The Markdown report links every plot and includes performance metrics,
+evaluation settings, data provenance, and the monthly-return table. Outputs
+remain ignored; do not copy them into the README without a redistributable input
+dataset and complete provenance.
+
+The current command must not fabricate diagnostics it cannot support. Add
+walk-forward or live-start boundaries only when the run records those regimes;
+capacity and slippage curves only with spread, volume, and order-size inputs;
+factor attribution only with validated factor returns/exposures; and fill
+quality only from authenticated order and execution records.
 
 ## Reporting Requirements
 

README.md

@@ -33,6 +33,37 @@ against appropriate benchmarks. See [PERFORMANCE.md](PERFORMANCE.md).
 
 ---
 
+## Project Demo
+
+The best demonstration is a locally generated, provenance-bearing report rather
+than a permanent equity curve detached from its input data. With an authorized
+price file, run:
+
+```bash
+PYTHONPATH=. python scripts/generate_report.py \
+  --prices-csv local_data/rotation_prices.csv \
+  --start 2018 --end 2025 --n-trials 10 \
+  --data-provider "$DATA_PROVIDER" \
+  --permission-basis "$DATA_PERMISSION_BASIS" \
+  --retrieved-at "$DATA_RETRIEVED_AT" \
+  --adjustment-method "$DATA_ADJUSTMENT_METHOD"
+```
+
+Open `reports/report.md`. It links a compact diagnostic overview and detailed
+performance, drawdown, rolling-risk, allocation, exposure, turnover, cost,
+monthly-return, and tail-distribution plots. The report also records the input
+digest, evaluation window, warm-up, cost assumptions, DSR settings, and whether
+all publication metadata was supplied. Metadata records the owner's assertions;
+the tool does not determine whether a license permits redistribution.
+
+The architecture diagram below is safe to publish because it is independent of
+market data. A generated `report_overview.png` should be added to this README
+only when the input license permits publication of derived images and the
+adjacent text identifies the source, date window, file digest, costs, benchmark
+treatment, and true research trial count. Never publish an equity curve alone.
+
+---
+
 ## Getting Started
 
 The scientific core, test suite, broker mocks, and labeled paper-trading dry run
@@ -110,14 +141,15 @@ python scripts/paper_trade_cycle.py --offline # labeled synthetic dry-run; no br
 
 `validate_performance.py` explicitly fetches live yfinance data; `--pit` uses a
 fixed start-date cohort from historical index membership. `generate_report.py`
-accepts either an owner-supplied wide CSV or explicit live yfinance, writes three
-charts under ignored `reports/img/`, and prints source metadata plus markdown
-tables. Its default report requires at least 274 pre-evaluation sessions for
-full signal initialization; `--warmup-years 0` explicitly permits and labels a
-cold start. `survivorship_demo.py` requires the same explicit live-data opt-in and
-shows the current pricing gap for past index members. `verify_brokers.py` checks
-Alpaca/IB/CCXT request construction and response parsing against SDK-shaped
-mocks; it does not verify a live SDK or authenticated connection.
+accepts either an owner-supplied wide CSV or explicit live yfinance, writes a
+Markdown report plus nine plots under ignored `reports/`, and prints source
+metadata plus markdown tables. Its default report requires at least 274
+pre-evaluation sessions for full signal initialization; `--warmup-years 0`
+explicitly permits and labels a cold start. `survivorship_demo.py` requires the
+same explicit live-data opt-in and shows the current pricing gap for past index
+members. `verify_brokers.py` checks Alpaca/IB/CCXT request construction and
+response parsing against SDK-shaped mocks; it does not verify a live SDK or
+authenticated connection.
 `paper_trade_cycle.py` runs the full execution path (use
 `--live-yfinance --submit` with `ALPACA_*` set to place paper orders). It
 refuses unresolved open orders, records deterministic client order IDs before
@@ -162,11 +194,11 @@ PYTHONPATH=. python scripts/generate_report.py \
 The report records the file path, SHA-256 digest, observed date window, cost
 assumptions, signal warm-up, DSR trial count/variance assumption, and whether
 liquidity constraints are active.
-Each run writes `equity_vs_benchmarks.png`, `drawdown.png`, and
-`rolling_sharpe.png` under ignored `reports/img/`, and prints performance and
-monthly-return tables. These are local research evidence, not repository
-fixtures. The README intentionally contains no fixed performance plot because
-the repository does not ship a redistributable input dataset. See
+Each run writes `reports/report.md`, a compact `report_overview.png`, and eight
+detailed diagnostics under ignored `reports/img/`. These are local research
+evidence, not repository fixtures. The README intentionally contains no fixed
+performance plot because the repository does not ship a redistributable input
+dataset. See
 [PERFORMANCE.md](PERFORMANCE.md) for interpretation requirements and known
 limitations.
 

local_data/README.md

@@ -29,6 +29,11 @@ For a performance report, include at least the requested pre-evaluation warm-up
 history (two calendar years by default); the loader cannot reconstruct signal
 history that is absent from the file.
 
+For a report intended for external review, also pass `--data-provider`,
+`--permission-basis`, `--retrieved-at`, and `--adjustment-method`. These fields
+record the owner's provenance assertions but do not independently establish
+that redistribution is permitted.
+
 ## Single-Symbol OHLCV CSV
 
 Notebook 02 also requires actual OHLCV data when using local files: