Commercial Research Beta release candidate

.github/workflows/commercial-research-beta.yml

@@ -0,0 +1,49 @@
+name: Commercial Research Beta
+
+on:
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  local-engineering-gate:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    env:
+      PYTHONDONTWRITEBYTECODE: "1"
+      PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+      PR_HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+    steps:
+      - name: Check out pull request revision
+        uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event.pull_request.head.sha }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install dependencies
+        run: python3 -m pip install -e . pytest
+
+      - name: Run full test suite
+        run: python3 -m pytest tests -q
+
+      - name: Smoke-test dashboard startup
+        run: make dashboard-smoke
+
+      - name: Render Personal Research routes
+        run: make research-dashboard-render-smoke
+
+      - name: Check public wording
+        run: make public-wording-check
+
+      - name: Check generated-artifact hygiene
+        run: make pr-range-hygiene-check BASE_SHA="$PR_BASE_SHA" HEAD_SHA="$PR_HEAD_SHA"
+
+      - name: Check whitespace
+        run: git diff --check "$PR_BASE_SHA...$PR_HEAD_SHA"

PRODUCT_SPEC.md

@@ -6,15 +6,31 @@ This project is a local, CSV-first stock research command center. It helps a use
 
 The product is not a trading bot. It does not place orders, connect to brokers, recommend options trades, or fabricate missing market, fundamentals, earnings, or analyst-estimate data.
 
+The supported workflow is `Research Desk -> Discover -> Company Workbench -> Monitor`. Operator-only legacy compatibility utilities are retained for deterministic regression and historical file contracts, not as current investing capability.
+
+## In-App Reviewed Research Records
+
+Thesis, evidence, catalyst, and outcome records are all available in the collapsed Company Workbench composer.
+A valid record requires an exact preview and explicit confirmation before save.
+Final integrity commit `e3a090dba` ensures confirmation appends only the receipt-matched recomputed record and enforces one readable active thesis lineage: revisions must supersede the exact active entry and preserve its thesis ID. The Company Workbench locks and explains that relationship, with temporary-ledger create -> revise -> reload coverage.
+Confirmation-integrity commit `5a6c55921` binds every displayed preview field, preview time, and destination label to the exact receipt. If an append raises after it may have written, confirmation returns one-shot `save_pending_reload` with the exact record ID unless the locked ledger is provably unchanged; it never invites a blind duplicate retry.
+Drafts are untrusted and preview receipts are session-only.
+Production tests never append repository ledgers; persistence tests use temporary ledgers.
+A saved record cannot change readiness, forecasts, probabilities, recommendations, or any other ledger.
+
+Priority 4's local validator is frozen; its permitted real-data exit gate remains externally incomplete.
+Priority 6's provider-neutral authorization contract is complete locally; hosted implementation remains environment-dependent.
+Priority 7 accessibility remediation is the next safe executable local lane.
+
 ## Target User
 
 The target user is an individual investor or research reviewer who wants a deterministic local workflow for:
 
 - maintaining a broad market universe;
 - narrowing that universe into an active research list;
-- reviewing portfolio holdings;
+- reviewing one company and its source-backed research record;
 - tracking readiness by analysis feature;
-- generating watchlists only when the needed data exists;
+- monitoring a focused cohort without ranking companies for action;
 - seeing exact data blockers and next import actions.
 
 ## Non-Goals
@@ -99,6 +115,12 @@ The product is now organized around a few research-facing surfaces:
 
 The primary public path is: Home workflow start -> Stock Selector -> Single-Stock Report -> Data Health lane answer -> Proof History evidence.
 
+## Legacy Compatibility Boundary
+
+`Monthly Picks`, `Momentum Leaders`, `Portfolio Review`, `Value / Re-rating`, and `Final Watchlist` are Operator-only compatibility utilities. Every retained page is labeled **Legacy research utility — not part of Personal Research Mode**, and its detailed output is hidden behind an explicit collapsed compatibility control.
+
+These utilities preserve historical algorithms, regression checks, and output filenames only. They cannot feed Research Decision Lab, cannot change readiness, and cannot produce recommendations, sizing, or transaction behavior. Public and Personal Research routes cannot open them. Retained position, cost-basis, disposition, ranked-candidate, or action-like fields are not supported product claims.
+
 These surfaces must show supported, blocked, partial, and excluded states before showing detailed tables. Broad-universe tables, command blocks, route maps, and proof ledgers should stay filtered, row-limited, collapsed, or operator-scoped by default.
 
 ## MVP Definition

READINESS_MODEL.md

@@ -37,6 +37,8 @@ The feature does not apply to this ticker or asset type.
 | `portfolio_ready` | holdings, prices, purpose metadata | holding row plus enough relevant data for review component | holding ticker parseable, position fields numeric when present | `portfolio_review.csv` | show review state | show missing components | mark holding blocked | not applicable |
 | `final_decision_ready` | central readiness report plus analysis outputs | enough data for the chosen decision bucket | blocked features reduce confidence | `research_decisions.csv`, `final_watchlist.csv` | show decision bucket and confidence | show reduced confidence | classify as Blocked by Data | classify as Excluded |
 
+`momentum_ready`, `portfolio_ready`, and `final_decision_ready` remain compatibility-only readiness rows for historical pipelines. Their retained pages are labeled **Legacy research utility — not part of Personal Research Mode** and are available only in Operator mode behind a collapsed compatibility control. They cannot feed Research Decision Lab, cannot change readiness outside their own historical calculation contracts, and cannot produce recommendations, sizing, or transaction behavior. Personal Research and Public routes do not expose these rows as current product capability.
+
 ## General Dashboard Rules
 
 - Show readiness before conclusions.