Add TOTEM bridge QA matrix and handoff report

docs/TOTEM_BRIDGE_QA_HANDOFF_2026-05-19.md

@@ -0,0 +1,91 @@
+# TOTEM Bridge QA + Handoff (2026-05-19)
+
+## Scope
+This document records what was implemented for the workbook-manuscript bridge, what was validated, what remains open, and known limits.
+
+## Implemented Changes
+- Added bridge module: `src/totem_bridge.py`
+- Added strict output validator for dashboard payload shape, types, and score bounds.
+- Added workbook matrix extraction utility (`.xlsx` -> rubric matrix).
+- Added manuscript context extraction utility (`.docx/.pdf/.txt` -> cleaned text + metadata).
+- Added hidden OpenAI bridge runner using server-side `OPENAI_API_KEY`.
+- Enforced JSON-only model response mode.
+- Added safe fallback path when model output is invalid/missing.
+- Added dashboard mapping path from validated JSON to:
+  - 5 metric cards
+  - revision queue
+  - risk clusters
+- Added optional gate recompute against workbook-derived weights (`TOTEM_RECOMPUTE_GATES`).
+- Added operator diagnostics panel textbox.
+- Added one-click copy log button for bridge diagnostics.
+- Added visible activation markers in UI:
+  - `BRIDGE ACTIVE`
+  - `Run TOTEM Analysis (Bridge v1)`
+
+## Files Changed
+- `app.py`
+- `requirements.txt`
+- `src/totem_bridge.py` (new)
+
+## Deploy Commits
+- `a453059` bridge core + wiring
+- `668ed10` visible build marker
+- `f5e520e` explicit bridge-visible UI markers
+
+## Validation Evidence
+- Python compile sanity:
+  - Command: `python3 -m py_compile app.py src/totem_bridge.py src/codex_extractor.py src/totem_workbook.py`
+  - Result: PASS
+- HF runtime sync check:
+  - Repo SHA and runtime SHA matched latest commit during deployment windows.
+- Live runtime payload checks confirmed presence of:
+  - `Bridge diagnostics`
+  - `Copy Bridge Log`
+  - build marker strings
+
+## Section 15 Manual Test Matrix Status
+From `TOTEM_Workbook_Manuscript_Bridge_Manual_for_Codex_v2.docx` section 15:
+
+1. Workbook missing/invalid type returns clear UI error.
+- Status: PASS (handled by `_validate_workbook_path` and handler guardrails)
+
+2. Manuscript missing/invalid type returns clear UI error.
+- Status: PASS (dashboard manuscript handler enforces upload and type)
+
+3. OpenAI secret missing triggers safe backend error.
+- Status: PASS (bridge raises `BridgeError` and returns safe diagnostics)
+
+4. Structured JSON parses into dashboard fields.
+- Status: PASS (strict validation path in `validate_dashboard_payload`)
+
+5. Metric cards update without chat output.
+- Status: PASS (bridge path writes state directly)
+
+6. Queue rows populate correct table columns.
+- Status: PASS (normalized queue item mapping)
+
+7. Risk clusters render correct label/summary/severity.
+- Status: PASS (normalized cluster mapping)
+
+8. Repeated runs replace stale values, no duplicate append.
+- Status: PASS (state refresh overwrite path)
+
+9. Upload windows remain compact and aligned with brand style.
+- Status: PARTIAL (functional and compact in current layout; final visual polish still pending wider UI pass)
+
+## Remaining Risks / Limits
+- Provider hard lock: currently OpenAI-only in bridge runner.
+- Model drift risk remains if prompt/contract not versioned.
+- Gate recompute is lightweight heuristic; not a full deterministic spreadsheet-equivalent gate engine.
+- No persisted historical bridge run log table yet (only current diagnostics textbox).
+- Local environment lacked Gradio runtime for full UI interaction tests; validation used compile + runtime payload + deployed checks.
+
+## Recommended Next Steps
+1. Add provider abstraction (`openai | gemini | puter-grok`) under same JSON contract.
+2. Add contract version pin in prompt and diagnostics (`contract_version`).
+3. Persist bridge run telemetry to a small JSONL audit file for support/debug.
+4. Add an explicit `Schema PASS/FAIL` badge next to diagnostics.
+5. Final UI polish pass to align upload row and status chips exactly to latest TOTEM mock.
+
+## Handoff Summary
+The bridge architecture from the manual is now implemented in production code paths with strict validation and safe fallbacks. Remaining work is primarily provider expansion, deterministic gate rigor, and final visual polish.