Merge pull request #4 from HanSun103/live-forward-test-2026-07-17

Deploy live-forward dashboard with GitHub Pages

Author: HanSun103

.github/workflows/deploy-dashboard.yml

@@ -0,0 +1,57 @@
+name: Deploy live-forward dashboard
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - "site/**"
+      - "src/experiments/public_dashboard_validation.py"
+      - ".github/workflows/deploy-dashboard.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: github-pages
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    name: Validate and package dashboard
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Validate sanitized public bundle
+        run: python -m src.experiments.public_dashboard_validation --site-dir site
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload dashboard artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: site
+
+  deploy:
+    name: Deploy dashboard
+    needs: validate
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.gitignore

@@ -37,3 +37,5 @@ data/raw/fnspid_source/
 # OS/editor noise
 .DS_Store
 Thumbs.db
+
+/pokestock-catalog-fix/

README.md

@@ -253,6 +253,8 @@ python -m src.cli run-live-forward-daily --as-of 2026-07-22
 
 The [live-forward operating guide](docs/LIVE_FORWARD_MONITOR.md) documents the close-data guard,
 frozen-snapshot contract, dashboard timestamps, model-overlap metrics, and generated artifacts.
+The [GitHub Pages deployment guide](docs/GITHUB_PAGES_DEPLOYMENT.md) documents the public-data
+boundary, static-site publication, validation gate, and one-time repository configuration.
 
 The daily command first refreshes the latest prior Ridge and XGBoost portfolios against the
 completed session. Yahoo's final hourly bar begins at 15:30, so the command requires that bar and
@@ -310,6 +312,17 @@ and SPY on one multi-session chart, provides date-range controls, identifies the
 portfolios whose returns are pending, and shows human-readable model and stock-level evidence. It
 is refreshed by the daily pipeline, snapshot, intraday-report, and evaluation commands.
 
+Publish and validate the sanitized GitHub Pages bundle without retraining:
+
+```bash
+python -m src.cli publish-live-dashboard
+python -m src.cli validate-live-dashboard-site
+```
+
+The daily pipeline runs the publication step automatically. Only `site/` is deployed; private
+research evidence under `reports/live_forward/`, cached inputs, trained artifacts, and local paths
+remain outside the public bundle.
+
 Build the earlier conservative final-reference package:
 
 ```bash

docs/GITHUB_PAGES_DEPLOYMENT.md

@@ -0,0 +1,74 @@
+# GitHub Pages Dashboard Deployment
+
+## Architecture
+
+The live-forward pipeline keeps research artifacts and the public website separate:
+
+```text
+Yahoo Finance and cached inputs
+             |
+             v
+Daily live-forward pipeline
+  - evaluate prior frozen portfolios
+  - tune and refit Ridge and XGBoost
+  - freeze tomorrow's top-40 lists
+  - calculate stability diagnostics
+             |
+             +--> reports/live_forward/   private, ignored research evidence
+             |
+             +--> public sanitizer and validator
+                          |
+                          v
+                       site/               committed static bundle
+                          |
+                          v
+                  GitHub Actions / Pages
+```
+
+`reports/live_forward/` remains the full local evidence store. The publisher uses explicit field
+allowlists to create `site/data/dashboard.json`; it does not copy local paths, cached input names,
+raw feature rows, model files, credentials, or candidate-trial details. The public bundle is then
+validated for required files, duplicate holdings, forbidden private strings, and a SHA-256 digest.
+
+## Daily publication
+
+The standard daily command now refreshes both the local dashboard and the public bundle:
+
+```bash
+python -m src.cli run-live-forward-daily --as-of YYYY-MM-DD
+```
+
+To rebuild the public bundle without retraining:
+
+```bash
+python -m src.cli publish-live-dashboard \
+  --live-root reports/live_forward \
+  --output-dir site
+```
+
+Validate exactly what will be published:
+
+```bash
+python -m src.cli validate-live-dashboard-site --site-dir site
+```
+
+Commit `site/` after reviewing the generated changes. A push to `main` that changes the public
+bundle starts `.github/workflows/deploy-dashboard.yml`. The workflow validates the bundle again,
+uploads it as a Pages artifact, and deploys it to the `github-pages` environment.
+
+## One-time repository setting
+
+In the GitHub repository, open **Settings > Pages** and set **Source** to **GitHub Actions**. After
+the workflow succeeds, the expected project URL is:
+
+`https://hansun103.github.io/AI-Driven-Portfolio-Optimization-Backtesting-System/`
+
+Deployment intentionally runs from `main`, so work on the live-forward branch must be reviewed and
+merged before it becomes public. The browser fetches only static JSON, CSS, and JavaScript; no API
+server, token, database, or LLM service is required.
+
+## Failure behavior
+
+The workflow does not deploy when the sanitizer output is absent, malformed, contains a blocked
+private marker, contains duplicate selected tickers, or does not match its deployment-manifest
+hash. A failed deployment leaves the previously successful Pages version online.

docs/LIVE_FORWARD_MONITOR.md

@@ -18,7 +18,8 @@ python -m src.cli run-live-forward-daily --as-of YYYY-MM-DD
 
 The command performs these steps in order:
 
-1. Incrementally refreshes market data and evaluates portfolios frozen before the current session.
+1. Incrementally refreshes market data and evaluates portfolios frozen before the current session,
+   including one holding-level return record per selected stock.
 2. Waits for the final 15:30 hourly bar and verifies the official daily close is available.
 3. Rebuilds price features through the decision date.
 4. Builds forward-return training labels only where the future outcome was already known before the
@@ -27,6 +28,7 @@ The command performs these steps in order:
    configurations, and freezes both top-40 lists for the next evaluation session.
 6. Writes model-agreement and day-over-day selection-stability diagnostics.
 7. Rebuilds `reports/live_forward/dashboard.html`.
+8. Publishes and validates the sanitized static bundle under `site/` for GitHub Pages.
 
 If final market data is unavailable, the command retries and then fails closed. It must not create a
 snapshot from a partial trading day.
@@ -52,6 +54,11 @@ previous official close, not to the session open.
 The date controls aggregate every completed observation in the selected range. Because the top-40
 holdings can change each day, each session uses the list frozen before that session.
 
+The stock-level view defaults to the newest decision date with a completed holding-level evaluation.
+The newest frozen portfolios remain available in the selector with a `Pending` label until their next
+session closes. Experiment history defaults to the newest evaluation date and can be filtered by
+evaluation date or selected model, limited to a compact number of rows, and sorted by any column.
+
 ## Selection-stability metrics
 
 All dashboard insights are deterministic calculations; no LLM API is required.
@@ -76,9 +83,15 @@ Generated outputs remain under the ignored `reports/live_forward/` directory:
 - dated Ridge and XGBoost snapshot directories with manifests, tuning results, predictions, and
   selected holdings;
 - intraday and close-to-close evaluation files for each frozen portfolio;
+- holding-level returns, benchmark-relative returns, and beat-SPY indicators for completed sessions;
 - `selection_stability_YYYY-MM-DD.json`;
 - `dashboard.html`.
 
+The daily command also refreshes the tracked `site/` directory. It contains only the allowlisted
+dashboard fields and split static assets required by GitHub Pages. See the
+[deployment guide](GITHUB_PAGES_DEPLOYMENT.md) for the privacy boundary, validation command, and
+one-time repository setting.
+
 Keep source code, configurations, tests, and documentation in Git. Do not commit cached prices,
 trained artifacts, generated reports, credentials, or temporary pytest directories.
 

docs/README.md

@@ -6,6 +6,7 @@
 - [2026-07-16 consolidation release notes](RELEASE_NOTES_2026-07-16.md)
 - [GitHub push plan](GITHUB_PUSH_PLAN.md)
 - [Live-forward monitoring and daily operations](LIVE_FORWARD_MONITOR.md)
+- [GitHub Pages dashboard deployment](GITHUB_PAGES_DEPLOYMENT.md)
 
 ## Branch Policy