V39 Gate 3: Enterprise Reading UX State Machine

Closes the V39 Gate 3 enterprise Reading UX state machine, Terminal five-step Reading guidance, conversation handoff state, source-safe disclosure contract, protocol artifact, and gate-quality proof coverage.

Author: geraldarthurdavis

.bitcode/v39-enterprise-reading-ux-state.json

@@ -187,6 +187,9 @@ jobs:
               if [ -f scripts/check-v39-gate2-depository-supply-indexing.mjs ]; then
                 node scripts/check-v39-gate2-depository-supply-indexing.mjs --skip-branch-check --skip-package-tests
               fi
+              if [ -f scripts/check-v39-gate3-enterprise-reading-ux-state.mjs ]; then
+                node scripts/check-v39-gate3-enterprise-reading-ux-state.mjs --skip-branch-check --skip-uapi-tests
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2

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

@@ -316,6 +316,9 @@ jobs:
               if [ -f scripts/check-v39-gate2-depository-supply-indexing.mjs ]; then
                 node scripts/check-v39-gate2-depository-supply-indexing.mjs --skip-branch-check --skip-package-tests
               fi
+              if [ -f scripts/check-v39-gate3-enterprise-reading-ux-state.mjs ]; then
+                node scripts/check-v39-gate3-enterprise-reading-ux-state.mjs --skip-branch-check --skip-uapi-tests
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
@@ -456,6 +459,7 @@ jobs:
             tests/api/readReviewRoute.test.ts \
             tests/api/pipelineHarnessRoute.test.ts \
             tests/terminalPipelineHarnessClient.test.ts \
+            tests/terminalEnterpriseReadingUxState.test.ts \
             tests/terminalDepositReadWorkbench.test.ts \
             tests/terminalTransactionQuery.test.ts \
             tests/terminalTransactionReadModel.test.ts \

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

@@ -105,6 +105,15 @@ source-safe `DepositoryAsset` candidates for Finding Fits.
 Gate 3 implements the five-step enterprise Reading path in Terminal and connected Conversation handoffs.
 The UX must default to clear low-detail guidance while preserving expandable source-safe operational detail for every step, pipeline run, quote, settlement, and delivery state.
 The gate is closed by route state contracts, component tests, browser proof, stream-log integration, and source-safe disclosure tests.
+The implementation basis is `TerminalEnterpriseReadingUxState`, exported from
+`uapi/app/terminal/terminal-enterprise-reading-ux-state.ts`, with five stable
+steps: `request-read`, `review-synthesized-need`, `request-fit`,
+`review-synthesized-asset-pack`, and `buy-asset-pack-settle`.
+Conversation handoffs may carry only source-safe stage intent through the
+`readingStage` query parameter and `terminalEnterpriseReadingStage` metadata;
+Terminal remains the transaction authority. The generated source-safe proof
+artifact is `.bitcode/v39-enterprise-reading-ux-state.json`, checked by
+`pnpm run check:v39-gate3`.
 
 ### Gate 4: ReadNeed Review, Resynthesis, And Admission Runtime
 

BITCODE_SPEC_V39.md

@@ -99,7 +99,24 @@ Closure acceptance:
 
 Closure implementation:
 
-- Pending Gate 3 work must define route contracts, UI tests, and generated UX-state proof artifact.
+- Gate 3 defines `TerminalEnterpriseReadingUxState` as the Terminal-owned
+  route/UI state contract for the five Reading stages.
+- The state contract defaults to low-detail guidance, preserves expandable
+  source-safe detail, and forbids protected source, raw protected prompts, raw
+  provider responses, unpaid AssetPack source, wallet private material,
+  private settlement payloads, and ledger write authority.
+- Conversation handoff now serializes source-safe `readingStage` route intent
+  and `terminalEnterpriseReadingStage` metadata while Terminal keeps authority.
+- The Terminal workbench renders stable `terminal-enterprise-reading-step-*`
+  stage rows, state chips, blockers, and source-safe detail accordions.
+- `ReadFitsFindingSynthesis` telemetry continues to stream through the rich
+  execution log with pipeline phase, PTRR, Failsafe, ThricifiedGeneration, tool,
+  prompt, and schema metadata.
+- The deterministic proof artifact is
+  `.bitcode/v39-enterprise-reading-ux-state.json`; `pnpm run check:v39-gate3`
+  validates artifact freshness, protocol tests, focused UAPI tests, source-safe
+  disclosure, route contracts, stream-log integration, docs, and workflow
+  wiring.
 
 ### Gate 4: ReadNeed Review, Resynthesis, And Admission Runtime
 

BITCODE_SPEC_V39_DELTA.md

@@ -188,7 +188,15 @@ without reading source-bearing payloads before settlement. The proof artifact is
 
 ## Gate 3 implementation notes
 
-Gate 3 closes the enterprise Reading UX state machine. Terminal and Conversation handoff must expose the five-step Reading path with low-detail guidance by default and expandable source-safe pipeline detail.
+Gate 3 closes the enterprise Reading UX state machine. Terminal and
+Conversation handoff expose the five-step Reading path with low-detail guidance
+by default and expandable source-safe pipeline detail.
+The state carrier is `TerminalEnterpriseReadingUxState`; Conversation can
+suggest only a source-safe `readingStage`, and Terminal reads it back as
+operator posture while retaining transaction authority.
+The generated artifact `.bitcode/v39-enterprise-reading-ux-state.json` binds
+stage ids, source-safe disclosure, rich execution stream integration, route
+state tests, component tests, and the maintained opt-in browser proof workflow.
 
 ## Gate 4 implementation notes
 

BITCODE_SPEC_V39_NOTES.md

@@ -71,7 +71,7 @@ No `_legacy/` source is active source truth.
 | Depository search scope | Gate 1 | depository-search source and tools, embedding policy, fit ranking expectations | drafted | Gate plan requires many-candidate Finding Fits across lexical, symbolic, path, metadata, measurement, vector, and provider channels. |
 | Settlement and delivery scope | Gate 1 | BTD receipts, source-to-shares compensation, ledger/database/storage synchronization, pull-request delivery | drafted | Gate plan keeps source-bearing AssetPack delivery blocked until settlement unlock. |
 | Depository supply indexing | Gate 2 | `packages/pipelines/asset-pack/src/depository-supply-index.ts`, `.bitcode/v39-depository-supply-indexing.json`, `packages/pipelines/asset-pack/src/__tests__/depository-supply-index.test.ts`, `packages/protocol/test/v39-depository-supply-indexing.test.js` | implemented | Deposited source becomes measurable, indexable, rights-aware, searchable, and repairable through source-safe `DepositorySupplyIndex` records. |
-| Enterprise Reading UX state machine | Gate 3 | Terminal route state, Conversation handoff, rich execution log, browser proof | pending | The five-step enterprise Reading UX is implemented with low-detail defaults and expandable source-safe detail. |
+| Enterprise Reading UX state machine | Gate 3 | `uapi/app/terminal/terminal-enterprise-reading-ux-state.ts`, `TerminalDepositReadWorkbench.tsx`, Conversation handoff, Terminal route query, `.bitcode/v39-enterprise-reading-ux-state.json`, focused UAPI tests, opt-in browser proof workflow | implemented | The five-step enterprise Reading UX is implemented with low-detail defaults, expandable source-safe detail, route-state handoff, rich execution stream integration, and source-safe disclosure proof. |
 | ReadNeed review and resynthesis | Gate 4 | `ReadNeedComprehensionSynthesis`, Need storage, feedback, resynthesis, accepted-Need admission | pending | Finding Fits remains blocked until a reviewed Need is accepted. |
 | ReadFitsFinding runtime and replay | Gate 5 | `ReadFitsFindingSynthesis`, search tools, embeddings, ranking, selected-fit provenance, replay receipts | pending | Finding Fits searches the whole available Depository for many above-threshold candidates. |
 | AssetPack preview and quote boundary | Gate 6 | AssetPack preview tests, quote tests, disclosure leak scans, proof roots | pending | Preview is commercially sufficient without exposing source-bearing AssetPack content. |
@@ -93,7 +93,7 @@ No `_legacy/` source is active source truth.
 | Canon-quality workflow | Canon workflow validates promoted V38 canon, V39 draft family when present, and V38/V39 posture | drafted |
 | Package docs | README, protocol package README, demonstration README, and PR template state V38 active / V39 draft workflow | drafted |
 | Depository supply indexing | Deposits become measurable, embedded, indexable, rights-aware, searchable, and repairable | implemented |
-| Enterprise Reading UX | Terminal implements request read, review Need, request Finding Fits, review preview, buy and settle | pending |
+| Enterprise Reading UX | Terminal implements request read, review Need, request Finding Fits, review preview, buy and settle | implemented |
 | ReadNeed runtime | `ReadNeedComprehensionSynthesis` persists reviewable Needs, feedback, resynthesis, measurements, and accepted-Need admission | pending |
 | ReadFitsFinding runtime | `ReadFitsFindingSynthesis` searches many above-threshold deposits with replayable query, ranking, threshold, and selected-fit provenance receipts | pending |
 | Preview and quote | AssetPack preview is source-safe and quote is deterministic before settlement | pending |
@@ -138,16 +138,28 @@ No `_legacy/` source is active source truth.
 | Gate 2 proof artifact is source-safe | `.bitcode/v39-depository-supply-indexing.json`, `packages/protocol/src/canonical/v39-depository-supply-indexing.js`, `packages/protocol/test/v39-depository-supply-indexing.test.js` | implemented |
 | Gate 2 checker is wired | `scripts/check-v39-gate2-depository-supply-indexing.mjs`, `package.json`, canon/gate workflows | implemented |
 
+## Gate 3 Parity
+
+| Requirement | Source evidence | Current V39 judgment |
+| --- | --- | --- |
+| Five-step Reading state machine exists | `uapi/app/terminal/terminal-enterprise-reading-ux-state.ts`, `uapi/tests/terminalEnterpriseReadingUxState.test.ts` | implemented |
+| Terminal renders low-detail and expandable source-safe detail | `uapi/app/terminal/TerminalDepositReadWorkbench.tsx`, `uapi/tests/terminalDepositReadWorkbench.test.ts` | implemented |
+| Conversation handoff carries source-safe Reading stage intent | `uapi/app/conversations/conversation-terminal-handoff.ts`, `uapi/app/terminal/terminal-transaction-query.ts`, `uapi/tests/conversationTerminalHandoff.test.tsx`, `uapi/tests/terminalTransactionQuery.test.ts` | implemented |
+| Rich execution log remains the live Reading pipeline stream | `uapi/app/terminal/terminal-pipeline-harness-client.ts`, `uapi/tests/pipelineExecutionLogHeader.test.tsx` | implemented |
+| Proof artifact and checker exist | `.bitcode/v39-enterprise-reading-ux-state.json`, `packages/protocol/src/canonical/v39-enterprise-reading-ux-state.js`, `packages/protocol/test/v39-enterprise-reading-ux-state.test.js`, `scripts/check-v39-gate3-enterprise-reading-ux-state.mjs` | implemented |
+| Browser proof remains wired as opt-in gate-quality evidence | `.github/workflows/bitcode-gate-quality.yml`, `uapi/tests/terminalUxBrowserProof.test.tsx`, `uapi/tests/e2e/commercial-mvp.terminal-ux.spec.ts` | implemented |
+
 ## Later Gate Parity
 
-Later V39 gates must add gate-specific parity sections when their implementation begins. Gates 1 and 2 intentionally do not claim closure for enterprise Reading UX, Need review, Finding Fits runtime, preview/quote, settlement/delivery, telemetry/repair, interface parity, rehearsal, or promotion readiness.
+Later V39 gates must add gate-specific parity sections when their implementation begins. Gates 1 through 3 intentionally do not claim closure for Need review, Finding Fits runtime, preview/quote, settlement/delivery, telemetry/repair, interface parity, rehearsal, or promotion readiness.
 
 ## accepted boundaries and reopen conditions
 
 V39 Gate 1 accepts only draft-family, roadmap, workflow, branch, and documentation posture closure.
 V39 Gate 2 accepts only Depository supply indexing, source-safe search document, vector projection, storage readback posture, rights boundary, repair posture, and Finding Fits handoff closure.
+V39 Gate 3 accepts only enterprise Reading UX state, source-safe route handoff/readback, low-detail/expandable Terminal rendering, rich stream-log integration, opt-in browser proof wiring, and generated UX proof artifact closure.
 Later gate scope is intentionally pending and must be reopened into gate-specific parity sections before implementation starts.
 
 ## completion condition
 
-V39 Gate 2 is complete when `check:v39-gate2`, package Depository supply tests, V39 draft spec-family validation, V38/V39 canon-posture drift validation, and promoted V38 spec-family validation all pass on a `v39/gate-2-*` branch.
+V39 Gate 3 is complete when `check:v39-gate3`, focused Terminal/Conversation/UAPI tests, V39 draft spec-family validation, V38/V39 canon-posture drift validation, and promoted V38 spec-family validation all pass on a `v39/gate-3-*` branch.

BITCODE_SPEC_V39_PARITY_MATRIX.md

@@ -257,6 +257,15 @@ wallet, source-safe search documents, active embedding/vector projection,
 Supabase storage readback posture, deterministic repair actions, and a
 source-safe Finding Fits handoff. Use `pnpm run generate:v39-depository-supply-indexing`
 and `pnpm run check:v39-gate2` before closing the gate.
+V39 Gate 3 adds the package-owned `TerminalEnterpriseReadingUxState` and
+source-safe generated artifact `.bitcode/v39-enterprise-reading-ux-state.json`.
+Terminal now owns the five-stage enterprise Reading state machine: request
+Read, review synthesized Need, request Finding Fits, review source-safe
+AssetPack preview, and buy AssetPack/settle. Conversation handoffs may pass
+only source-safe `readingStage` intent, Terminal parses it as posture, and the
+rich execution stream remains the live Reading pipeline log. Use
+`pnpm run generate:v39-enterprise-reading-ux-state` and
+`pnpm run check:v39-gate3` before closing the gate.
 V36 Gate 2 anchors market-wide activity through the package-owned
 `ExchangeActivityBook` and the source-safe generated artifact
 `.bitcode/v36-exchange-activity-book.json`, including listing, bid, ask,
@@ -417,6 +426,9 @@ commit promotion artifacts plus the `BITCODE_SPEC.txt` pointer change from
 For V39, Gate 1 opens `version/v39` and the gate-quality posture through
 `pnpm run check:v39-gate1` before later gates add generated commercial Reading
 artifacts and the V39 promotion workflow.
+V39 Gate 2 is wired through `pnpm run check:v39-gate2`; V39 Gate 3 is wired
+through `pnpm run check:v39-gate3` and its generated
+`.bitcode/v39-enterprise-reading-ux-state.json` artifact.
 V38 Gates 1 through 11 are wired through `pnpm run check:v38-gate1`,
 `pnpm run check:v38-gate2`, `pnpm run check:v38-gate3`,
 `pnpm run check:v38-gate4`, `pnpm run check:v38-gate5`,

README.md

@@ -5,8 +5,8 @@
 - Current active canonical pointer: `BITCODE_SPEC.txt` -> `V38`
 - Current active canon: `BITCODE_SPEC_V38.md`
 - Current draft target: `BITCODE_SPEC_V39.md`.
-- Current working gate: V39 Gate 2 Depository Supply Indexing And Searchable Deposit Lifecycle.
-- Next queued gate after V39 Gate 2 closure: V39 Gate 3 Enterprise Reading UX State Machine.
+- Current working gate: V39 Gate 3 Enterprise Reading UX State Machine.
+- Next queued gate after V39 Gate 3 closure: V39 Gate 4 ReadNeed Review, Resynthesis, And Admission Runtime.
 - Latest closed version: V38 Inference Correctness, which promoted pipeline execution call-stack law, PTRR/Failsafe/Thricified parity, prompt and PromptPart benchmarking, source-safe inference telemetry, ReadNeedComprehensionSynthesis hardening, ReadFitsFindingSynthesis search and embeddings, AssetPack economic traceability, local/staging inference rehearsal, and V38 promotion readiness.
 - Recent V38 closure anchor: V38 Gate 11 Promotion Readiness generated V38 proof support, promoted `BITCODE_SPEC.txt` to `V38`, prepared V38 active / V39 draft runtime posture, and closed inference correctness canon.
 - V34 Gate 2 closure anchor: deployment-depth now owns package-backed `DeploymentHostCapabilityCatalog` and `EnvironmentLaneContract` source, deterministic `.bitcode/v34-deployment-host-capability-catalog.json` and `.bitcode/v34-environment-lane-contracts.json`, and visible `value-bearing-mainnet` blocking through `blocked_future_canon_required`.
@@ -62,6 +62,7 @@
 - V38 Gate 11 closure anchor: Inference correctness depth now owns package-backed `V38InferencePromotionReadinessReport` source, deterministic `.bitcode/v38-promotion-readiness-report.json`, `source-safe-inference-promotion-readiness-metadata`, source-safe coverage for all V38 inference artifacts, `BITCODE_SPEC_V38_PROVEN.md` generation support, promotion command dry-run support, `v38-canon-promotion.yml`, active V38 / draft V39 posture preparation, package tests, workflow wiring, and `check:v38-gate11`.
 - V39 Gate 1 opening anchor: Commercial Reading readiness opens over promoted V38 with V39 SPEC, DELTA, NOTES, and PARITY files, `check:v39-gate1`, V38 active / V39 draft posture, and an eleven-gate plan for Depository supply indexing, enterprise Reading UX state, ReadNeed review/resynthesis, ReadFitsFinding runtime and replay, AssetPack preview/quote disclosure, settlement/BTD rights/delivery, operational telemetry/repair, interface parity, local/staging rehearsal, and promotion readiness.
 - V39 Gate 2 closure anchor: Commercial Reading readiness now owns package-backed `DepositorySupplyIndex` source, deterministic `.bitcode/v39-depository-supply-indexing.json`, source-safe Depository supply records, lexical/metadata/measurement/vector search documents, active OpenAI embedding/vector projection, Supabase storage readback posture, depositor/Reader settlement boundary, repair actions, Finding Fits handoff, package tests, protocol tests, workflow wiring, and `check:v39-gate2`.
+- V39 Gate 3 closure anchor: Commercial Reading readiness now owns package-backed `TerminalEnterpriseReadingUxState` source, deterministic `.bitcode/v39-enterprise-reading-ux-state.json`, five-step Reading state, source-safe `readingStage` Conversation handoff and Terminal readback, low-detail defaults, expandable source-safe detail, rich execution stream integration, component/route tests, opt-in browser proof workflow wiring, and `check:v39-gate3`.
 - Purpose: concise running index of Bitcode/ENGI specification history, current work, and planned work.
 
 This roadmap is not an active system specification.

SPECIFICATIONS_ROADMAP.md

@@ -218,6 +218,9 @@
     "generate:v39-depository-supply-indexing": "node scripts/generate-v39-depository-supply-indexing.mjs",
     "check:v39-depository-supply-indexing": "node scripts/generate-v39-depository-supply-indexing.mjs --check",
     "check:v39-gate2": "node scripts/check-v39-gate2-depository-supply-indexing.mjs",
+    "generate:v39-enterprise-reading-ux-state": "node scripts/generate-v39-enterprise-reading-ux-state.mjs",
+    "check:v39-enterprise-reading-ux-state": "node scripts/generate-v39-enterprise-reading-ux-state.mjs --check",
+    "check:v39-gate3": "node scripts/check-v39-gate3-enterprise-reading-ux-state.mjs",
     "generate:v38-inference-surface-inventory": "node scripts/generate-v38-inference-surface-inventory.mjs",
     "check:v38-inference-surface-inventory": "node scripts/generate-v38-inference-surface-inventory.mjs --check",
     "check:v38-gate2": "node scripts/check-v38-gate2-inference-surface-inventory.mjs",