Add single-command GTL tuning matrix

README.md

@@ -459,6 +459,33 @@ metrics. Keep the SSH tunnel open only while creating the snapshot; the backtest
 run itself is local/offline. `backtest_snapshots/` and generated backtest reports
 are git-ignored.
 
+### One-command GTL tuning run
+
+The Gate Target Ladder has a research-only, single-variable matrix for testing
+whether its useful screening behavior can be made more explicit. It runs 20
+complete backtests **sequentially** so each arm gets the full worker pool:
+
+```bash
+# macOS/Linux
+.venv/bin/python scripts/run_gtl_tuning_matrix.py \
+  backtest_snapshots/prod.sqlite --workers 14
+```
+
+The arms cover GTL history length, grid density, pivots, price-traffic scoring,
+proposal merging, target-zone width, candidate count, and maximum target
+distance. Every arm includes the full-period production book, the fixed
+`2024-07-01` train/test split, a candidate-level paired audit, and the same
+pre-registered robustness screen. This is one long command, not a Cartesian
+parameter search; expect total runtime to be roughly 20 times one full local
+backtest.
+
+Progress is checkpointed after every arm to
+`reports/backtest-YYYYMMDD-gtl-tuning-matrix.json` and the matching `.md` table.
+The large per-arm reports are removed only after successful consolidation. If
+the run fails, they remain available for diagnosis; pass `--keep-arm-reports`
+to retain them after success too. No arm changes live scanner defaults or
+deploys anything.
+
 ### Reading a local backtest report
 
 The deployed **Signals → Track Record** page is deliberately trimmed to validation
@@ -497,6 +524,7 @@ Research-only flags, all off by default (the default report is byte-identical to
 | `BACKTEST_HOLDOUT_SPLIT=YYYY-MM-DD` | Adds a `holdout` section: train (entries before) vs test (entries on/after), as disjoint books |
 | `BACKTEST_MIN_RR_SWEEP=1` | Sweeps the activation R:R floor against portfolio Sharpe. Combine with `BACKTEST_HOLDOUT_SPLIT` to sweep out-of-sample |
 | `BACKTEST_SR_VARIANT=<arm>` | Research-only S/R detector/gate arm; see `docs/research/sr-levels-and-exits.md` for the detector and hidden-feature matrices |
+| `BACKTEST_GTL_CONFIG=<json>` | Parameterizes only the `gtl_tuning` research arm; normally set by `run_gtl_tuning_matrix.py` |
 | `BACKTEST_ENTRY_START=YYYY-MM-DD` | Restrict candidate entry dates to a validation window |
 | `BACKTEST_ENTRY_END=YYYY-MM-DD` | Restrict candidate entry dates to a training window |
 | `BACKTEST_SR_AUDIT=1` | Add momentum-slice candidate rows for paired S/R cohort comparison |