V29 Gate 9: Terminal UX Quality And Browser Proof

Closes Gate 9 by proving the Terminal cockpit UX with source-safe landmarks, state semantics, responsive Playwright coverage, and maintained gate-quality automation.

Author: geraldarthurdavis

.github/workflows/bitcode-gate-quality.yml

@@ -70,6 +70,7 @@ jobs:
           node scripts/check-v29-gate6-settlement-reconciliation-repair.mjs --skip-branch-check
           node scripts/check-v29-gate7-organization-permission-authority.mjs --skip-branch-check
           node scripts/check-v29-gate8-demonstration-origin-formalization.mjs --skip-branch-check
+          node scripts/check-v29-gate9-terminal-ux-browser-proof.mjs --skip-branch-check
 
       - name: Validate source casing and imports
         run: |
@@ -116,9 +117,16 @@ jobs:
             tests/protocolCommercialBoundary.test.ts \
             tests/terminalTransactionDetailCards.test.tsx \
             tests/terminalTransactionDetailSnapshot.test.ts \
+            tests/terminalUxBrowserProof.test.tsx \
             tests/pipelineExecutionLogHeader.test.tsx \
             --runInBand
 
+      - name: Install Terminal browser proof browser
+        run: pnpm --dir uapi exec playwright install chromium --with-deps
+
+      - name: Browser proof Terminal cockpit
+        run: pnpm --dir uapi run test:e2e:terminal-ux
+
       - name: Test pipeline readback verifier
         run: pnpm test:qa:v28:pipeline-readback
 

BITCODE_SPEC_V29.md

@@ -223,6 +223,29 @@ The Terminal transaction read model must contain:
 The model is deterministic from execution history, detail readback, route query state, and data mode.
 It must tolerate partial live readback by preserving a fallback selected-run projection while naming empty or blocked sections.
 
+## V29 Terminal UX quality and browser-proof canon
+
+The Terminal transaction cockpit is a protocol-facing operator interface.
+It must be readable by default, keyboard reachable, responsive, and browser-proven.
+
+The cockpit must expose:
+
+- one named `main` landmark for the Terminal route;
+- a keyboard-reachable skip link to the selected transaction workspace;
+- a named transaction workspace region for activity selection, filtering, and selected-result digest;
+- a named selected activity detail region for the low-detail detail hero, route-owned section controls, and source-safe detail surfaces;
+- explicit loading, empty, failed, blocked, and source-safe preview states with `status` or `alert` semantics where appropriate;
+- contained table overflow so phone and tablet viewports do not acquire document-level horizontal overflow;
+- route-owned detail controls whose current, available, empty, and blocked states are understandable before raw payload expansion.
+
+The browser-proof contract is package-local to Terminal and exported by `uapi/app/terminal/terminal-ux-browser-proof.ts`.
+It identifies the required landmarks, viewports, state semantics, route checks, and evidence files.
+The focused Jest test proves the contract and state semantics.
+The focused Playwright spec proves the cockpit in a real browser in deterministic mock mode across key route and responsive states.
+
+Gate 9 acceptance does not change Reading law, source disclosure law, settlement law, or organization authority law.
+It makes the current V29 Terminal cockpit commercially operable enough that later local/staging promotion readiness can debug failures from the UI rather than from browser network logs alone.
+
 ## V29 Wallet/BTC operation canon
 
 Wallet and BTC fee state is an ordinary Terminal transaction surface, not an opaque settlement footnote.

BITCODE_SPEC_V29_DELTA.md

@@ -183,6 +183,16 @@ Closure acceptance:
 
 Gate 9 owns accessibility, responsive layout, copy/prose clarity, empty/loading/blocked/failed states, Playwright coverage, and visual/browser verification for the complete Terminal transaction cockpit.
 
+Closure acceptance:
+
+- Terminal exposes one named cockpit `main` landmark, a keyboard-reachable skip link to the selected transaction workspace, named regions for the transaction workspace and selected activity detail, and accessible controls for route-owned detail sections.
+- The default operator path remains low-detail: activity summary, selected result digest, section availability, blockers, and source-safe preview metadata are readable before raw payload expansion.
+- Loading, empty, failed, blocked, and source-safe preview states are represented by typed UI states with `status` or `alert` semantics where appropriate, not only by browser-network inspection.
+- The complete cockpit is responsive across phone, tablet, laptop, and widescreen viewports without document-level horizontal overflow; table overflow remains contained inside the table scroller.
+- Browser proof is executable through a focused Playwright spec that opens Terminal in deterministic mock mode, verifies landmarks, skip navigation, blocked Console posture, source-safe detail, route-owned selection, and responsive readability.
+- Focused Jest coverage proves the UI state contract and the exported browser-proof contract that CI and documentation name.
+- `check:v29-gate9` fails closed unless V29 specification, Terminal README, Terminal UX contract, Jest tests, Playwright spec, package scripts, and gate-quality workflow all name the Gate 9 browser-proof surface.
+
 ### Gate 10: Local And Staging Promotion Readiness
 
 Gate 10 owns non-mocked local validation, staging-testnet readback, generated proof artifacts, V29 promotion workflow support, promotion dry-run, and final version branch readiness.

BITCODE_SPEC_V29_NOTES.md

@@ -76,6 +76,7 @@ For a simplified reading of V29:
 
 9. **Gate 9: Terminal UX Quality And Browser Proof**
    - Close accessibility, responsive, copy, loading/empty/error/blocked states, browser checks, and Playwright coverage for the complete Terminal cockpit.
+   - Acceptance detail: the Terminal page exposes a named cockpit `main`, skip navigation into the selected transaction workspace, named workspace/detail regions, source-safe low-detail defaults, explicit state semantics, and deterministic Playwright coverage for landmarks, blocked Console posture, route-owned selection, and phone/tablet/laptop/widescreen readability.
 
 10. **Gate 10: Local And Staging Promotion Readiness**
     - Run non-mocked local validation, staging-testnet readback, generated proof artifacts, promotion dry-run, and `version/v29` promotion readiness.
@@ -209,6 +210,34 @@ Gate 8 completion condition:
 - Protocol package tests pass.
 - The spec family, package README, root scripts, and CI all name and enforce the package-native boundary.
 
+## Gate 9 working notes
+
+Gate 9 closes the Terminal cockpit quality slice.
+It treats UX quality as protocol evidence: operators must be able to read the transaction state, section availability, source-safe preview posture, blocked actions, and activity stream without relying on browser network logs.
+
+Accepted surfaces:
+
+- `uapi/app/terminal/terminal-ux-browser-proof.ts` records the browser-proof contract: required landmarks, state semantics, viewports, route checks, and evidence files.
+- `TerminalPageClient.tsx` owns the named cockpit `main` landmark and skip link.
+- `TerminalTransactionWorkspace.tsx` owns the named transaction workspace region, loading/empty/error semantics, and selected result status.
+- `TerminalTransactionDetailSurface.tsx`, `TerminalTransactionDetailHero.tsx`, and `TerminalTransactionDetailActionBar.tsx` own the selected activity detail region, low-detail source-safe header, section controls, blocked Console posture, and action errors.
+- `BitcodeTransactionsTable.tsx` and `BitcodeTransactionsDataTable.tsx` keep transaction table overflow contained while exposing loading, empty, error, and selectable-row states to tests and assistive technology.
+- `uapi/tests/terminalUxBrowserProof.test.tsx` proves the typed state contract.
+- `uapi/tests/e2e/commercial-mvp.terminal-ux.spec.ts` proves the cockpit in a real browser in deterministic mock mode.
+
+Gate 9 accepted boundaries:
+
+- Gate 9 does not redesign the five-step Reading product flow; it makes the current transaction cockpit accessible and provable.
+- Gate 9 does not reveal protected AssetPack source before settlement.
+- Gate 9 does not add versioned routes, gate-named runtime routes, or work-in-progress source identifiers.
+- Gate 9 does not require live staging credentials; Gate 10 owns non-mocked local/staging promotion readiness.
+
+Gate 9 completion condition:
+
+- `pnpm run check:v29-gate9` passes.
+- Focused UAPI Jest coverage and Terminal Playwright browser proof pass locally.
+- Gate-quality CI invokes the Gate 9 checker, focused Jest test, and focused Playwright browser proof.
+
 ## Later-version boundaries
 
 - V30 remains reserved for Protocol/BTD hardening that is not necessary to close Terminal transaction depth.

BITCODE_SPEC_V29_PARITY_MATRIX.md

@@ -56,7 +56,7 @@ No `_legacy/` source is active source truth.
 | Settlement reconciliation repair | Gate 6 | BTD journal/reconciliation, Supabase readback, sandbox harness settlement evidence, Terminal repair UI, Gate 6 checker | drafted | Ledger, database, and metaphysical state drift is classified, proof-rooted, repair-actioned, and visible. |
 | Organization permission authority | Gate 7 | `packages/btd/src/authority.ts`, BTD/API/MCP/ChatGPT App tests, sandbox harness authority evidence, Terminal Authority section, Gate 7 checker | drafted | Registry-derived roles, holdings, read-license authority, settlement, confirmation, and interface admission govern actions. |
 | Commercial formalization | Gate 8 | `packages/protocol/src/index.js`, `packages/protocol/src/canon-posture.js`, root scripts, protocol package tests, import scans, docs, Gate 8 checker | drafted | Demonstration-origin commercial internals are package-native and no direct demonstration-source imports remain in commercial/runtime sources. |
-| Terminal UX quality | Gate 9 | Playwright/Jest/a11y/responsive/browser QA | pending | Complete transaction cockpit is usable by default and inspectable in detail. |
+| Terminal UX quality | Gate 9 | Terminal UX contract, Playwright/Jest/a11y/responsive/browser QA | drafted | Complete transaction cockpit is usable by default and inspectable in detail. |
 | Promotion readiness | Gate 10 | promotion workflow, `.bitcode/v29-*`, `BITCODE_SPEC_V29_PROVEN.md` | pending | `version/v29` can promote to `main` only after all V29 checks pass. |
 
 ## V29 implementation checklist
@@ -73,7 +73,7 @@ No `_legacy/` source is active source truth.
 | Gate 5 AssetPack disclosure | `pnpm run check:v29-gate5` proves source-safe disclosure review, leakage detection, Terminal preview rendering, and PR title enforcement | drafted |
 | Gate 7 organization authority | `pnpm run check:v29-gate7` proves shared org/interface authority across BTD, API, MCP, ChatGPT App, harness, and Terminal | drafted |
 | Gate 8 commercial formalization | `pnpm run check:v29-gate8` proves package-native protocol exports, V28/V29 posture, script import cleanup, docs, tests, and CI wiring | drafted |
-| Product implementation gates | Gate 9 closes remaining Terminal transaction UX quality with browser proof | pending |
+| Gate 9 Terminal UX browser proof | `pnpm run check:v29-gate9` proves named landmarks, explicit state semantics, responsive browser coverage, focused Jest coverage, and CI wiring | drafted |
 | Promotion gate | Gate 10 closes generated proof and promotion automation | pending |
 
 ## Gate 1 Parity
@@ -272,3 +272,31 @@ Gate 8 completion condition:
 - Focused protocol package typecheck/test and the UAPI commercial protocol boundary test pass.
 - V29 SPEC, DELTA, NOTES, PARITY, protocol package README, package scripts, and gate-quality workflow name the formalized package-native boundary.
 - Root scripts use protocol package exports for canonical helpers and do not directly import `protocol-demonstration/src/*`.
+
+## Gate 9 Parity
+
+Gate 9 closes the Terminal UX quality and browser-proof slice by making the transaction cockpit readable, keyboard reachable, responsive, and test-proven.
+
+Accepted surfaces:
+
+- `uapi/app/terminal/terminal-ux-browser-proof.ts` exports the typed contract for Gate 9 landmarks, viewports, states, route checks, and evidence files.
+- `TerminalPageClient.tsx` exposes a named `main` cockpit region and skip link to the selected transaction workspace.
+- `TerminalTransactionWorkspace.tsx` exposes a named transaction workspace region, selected activity status, and explicit loading, empty, and error states.
+- `TerminalTransactionDetailSurface.tsx`, `TerminalTransactionDetailHero.tsx`, and `TerminalTransactionDetailActionBar.tsx` expose a named selected activity detail region, source-safe low-detail detail hero, route-owned section controls, blocked Console posture, and action error alerts.
+- `BitcodeTransactionsTable.tsx` and `BitcodeTransactionsDataTable.tsx` expose table state semantics while containing table overflow inside the table scroller.
+- `uapi/tests/terminalUxBrowserProof.test.tsx` proves the contract and UI state semantics.
+- `uapi/tests/e2e/commercial-mvp.terminal-ux.spec.ts` proves the cockpit through a real browser in deterministic mock mode.
+- `.github/workflows/bitcode-gate-quality.yml` runs the Gate 9 checker, focused Jest test, Playwright browser install, and focused Terminal browser proof.
+
+Accepted boundaries:
+
+- Gate 9 does not redesign Reading into a different flow.
+- Gate 9 does not reveal protected AssetPack source before settlement.
+- Gate 9 does not add versioned API routes or gate/work-in-progress runtime identifiers.
+- Gate 9 does not perform non-mocked staging promotion readiness; Gate 10 owns that slice.
+
+Gate 9 completion condition:
+
+- `pnpm run check:v29-gate9` passes.
+- Focused UAPI Jest coverage and Playwright Terminal browser proof pass.
+- V29 SPEC, DELTA, NOTES, PARITY, Terminal README, package scripts, and gate-quality workflow name the browser-proof contract.

package.json

@@ -52,6 +52,7 @@
     "check:v29-gate6": "node scripts/check-v29-gate6-settlement-reconciliation-repair.mjs",
     "check:v29-gate7": "node scripts/check-v29-gate7-organization-permission-authority.mjs",
     "check:v29-gate8": "node scripts/check-v29-gate8-demonstration-origin-formalization.mjs",
+    "check:v29-gate9": "node scripts/check-v29-gate9-terminal-ux-browser-proof.mjs",
     "check:spec-quality": "node scripts/run-bitcode-spec-quality.mjs --mode basic",
     "check:spec-quality:title": "node scripts/run-bitcode-spec-quality.mjs --mode strict-from-title",
     "check:spec-quality:v24": "node scripts/run-bitcode-spec-quality.mjs --mode strict-version --version V24",