Merge pull request #116 from engineeredsoftware/v37/gate-6-conversation-terminal-handoff

V37 Gate 6: Conversation Terminal Handoff

Author: geraldarthurdavis

.bitcode/v37-conversation-terminal-handoff.json

@@ -121,6 +121,9 @@ jobs:
               if [ -f scripts/check-v37-gate5-conversation-source-selector.mjs ]; then
                 node scripts/check-v37-gate5-conversation-source-selector.mjs --skip-branch-check
               fi
+              if [ -f scripts/check-v37-gate6-conversation-terminal-handoff.mjs ]; then
+                node scripts/check-v37-gate6-conversation-terminal-handoff.mjs --skip-branch-check
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2

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

@@ -250,6 +250,9 @@ jobs:
               if [ -f scripts/check-v37-gate5-conversation-source-selector.mjs ]; then
                 node scripts/check-v37-gate5-conversation-source-selector.mjs --skip-branch-check
               fi
+              if [ -f scripts/check-v37-gate6-conversation-terminal-handoff.mjs ]; then
+                node scripts/check-v37-gate6-conversation-terminal-handoff.mjs --skip-branch-check
+              fi
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
@@ -339,6 +342,7 @@ jobs:
             tests/api/conversationSessionRouteHistoryContract.test.ts \
             tests/api/conversationStreamEventContract.test.ts \
             tests/conversationStreamPipelineLog.test.tsx \
+            tests/conversationTerminalHandoff.test.tsx \
             tests/conversationSourceSelector.test.tsx \
             tests/conversationWritingWorkspace.test.tsx \
             tests/auxillariesExternalsPane.test.tsx \

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

@@ -3,12 +3,12 @@
 ## Status
 
 - Version: `V37`
-- V37 state: draft implementation; Gate 5 closes ConversationSourceSelector source selection and context policy over active V36 Exchange canon
+- V37 state: draft implementation; Gate 6 closes ConversationTerminalHandoff transaction handoff over active V36 Exchange canon
 - Current canonical/latest target: `V36`
 - Prior canonical anchor: `BITCODE_SPEC_V36.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V36_PROVEN.md`
-- Generated structured artifact inventory: draft `.bitcode/v37-spec-family-report.json`, `.bitcode/v37-canonical-input-report.json`, `.bitcode/v37-canon-posture-drift-report.json`, `.bitcode/v37-conversation-session-route-history.json`, `.bitcode/v37-conversation-stream-event-contract.json`, `.bitcode/v37-conversation-writing-workspace.json`, and `.bitcode/v37-conversation-source-selector.json`
-- Source parity state: V37 source parity includes Gate 1 spec family, roadmap, docs, workflow, and checker posture, Gate 2 package-owned ConversationSession route-history contracts, Gate 3 package-owned ConversationStreamEvent stream UI/event contracts, Gate 4 package-owned ConversationWritingWorkspace fullscreen writing contracts, and Gate 5 package-owned ConversationSourceSelector source/context policy contracts
+- Generated structured artifact inventory: draft `.bitcode/v37-spec-family-report.json`, `.bitcode/v37-canonical-input-report.json`, `.bitcode/v37-canon-posture-drift-report.json`, `.bitcode/v37-conversation-session-route-history.json`, `.bitcode/v37-conversation-stream-event-contract.json`, `.bitcode/v37-conversation-writing-workspace.json`, `.bitcode/v37-conversation-source-selector.json`, and `.bitcode/v37-conversation-terminal-handoff.json`
+- Source parity state: V37 source parity includes Gate 1 spec family, roadmap, docs, workflow, and checker posture, Gate 2 package-owned ConversationSession route-history contracts, Gate 3 package-owned ConversationStreamEvent stream UI/event contracts, Gate 4 package-owned ConversationWritingWorkspace fullscreen writing contracts, Gate 5 package-owned ConversationSourceSelector source/context policy contracts, and Gate 6 package-owned ConversationTerminalHandoff transaction handoff contracts
 - Active canonical pointer during draft opening: `BITCODE_SPEC.txt` -> `V36`
 - Notes companion: `BITCODE_SPEC_V37_NOTES.md`
 - Delta companion: `BITCODE_SPEC_V37_DELTA.md`
@@ -158,6 +158,37 @@ package tests, UI tests, docs, workflow wiring, selector kind coverage,
 governance coverage, allowed/denied/retry preview states, rights and
 settlement posture, proof roots, event ids, and source-safe preview metadata.
 
+## V37 Gate 6 ConversationTerminalHandoff canon
+
+Gate 6 implements `ConversationTerminalHandoff` as the package-owned
+transaction handoff contract from Website Conversations into the Bitcode
+Terminal. It owns source-safe handoff envelopes for Depositing, Reading,
+Finding Fits, Exchange, settlement, and delivery workflows. It emits
+`.bitcode/v37-conversation-terminal-handoff.json` with
+`source-safe-conversation-terminal-handoff-metadata`, deterministic row roots,
+deterministic detail roots, workflow ids, field ids, authority boundary ids,
+policy states, proof roots, event ids, source evidence roots, and source-safe
+disclosure limits.
+
+Conversation handoff is not execution. Conversations may prepare source-safe
+transaction intent, preserve a route-local conversation id, selected
+transaction id, repository anchor, source selector summaries, a user-readable
+summary, policy result, proof root, and Terminal detail focus. The Terminal
+remains the transaction cockpit and the only website surface that may proceed
+into ledger, wallet, settlement, Exchange, delivery, and BTD ownership actions.
+Conversation handoff payloads must not expose protected source, raw protected
+prompts, protected model responses with source, provider tokens, wallet
+private material, settlement private payloads, unpaid AssetPack source, ledger
+write authority, wallet signing authority, or a Terminal authority bypass.
+
+The Terminal route reads `conversationHandoff=1` context as source-safe
+operator context. It may display the workflow, policy state, proof root,
+repository anchor, source selector count, and handoff summary before the
+operator chooses any Terminal action. `check:v37-gate6` validates package
+source, generated artifact freshness, package tests, UI tests, Terminal route
+tests, docs, workflow wiring, workflow coverage, authority boundaries,
+proof roots, event ids, and source-safe handoff metadata.
+
 ## Inherited V36 Exchange canon
 
 The promoted V36 sections below remain inherited canonical law for Exchange.

BITCODE_SPEC_V37.md

@@ -3,12 +3,12 @@
 ## Status
 
 - Version: `V37`
-- V37 state: draft implementation; this delta records the V36-to-V37 Website Conversations opening through Gate 4 ConversationWritingWorkspace fullscreen writing contracts
+- V37 state: draft implementation; this delta records the V36-to-V37 Website Conversations opening through Gate 6 ConversationTerminalHandoff transaction handoff contracts
 - Current canonical/latest target: `V36`
 - Prior canonical anchor: `BITCODE_SPEC_V36.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V36_PROVEN.md`
-- Generated structured artifact inventory: draft `.bitcode/v37-spec-family-report.json`, `.bitcode/v37-canonical-input-report.json`, `.bitcode/v37-canon-posture-drift-report.json`, `.bitcode/v37-conversation-session-route-history.json`, `.bitcode/v37-conversation-stream-event-contract.json`, and `.bitcode/v37-conversation-writing-workspace.json`
-- Source parity state: V37 source parity begins at Gate 1 with spec family, roadmap, docs, workflow, and checker posture; Gate 2 adds package-owned ConversationSession route-history contracts; Gate 3 adds package-owned ConversationStreamEvent contracts and stream UI binding; Gate 4 adds package-owned ConversationWritingWorkspace fullscreen composer contracts
+- Generated structured artifact inventory: draft `.bitcode/v37-spec-family-report.json`, `.bitcode/v37-canonical-input-report.json`, `.bitcode/v37-canon-posture-drift-report.json`, `.bitcode/v37-conversation-session-route-history.json`, `.bitcode/v37-conversation-stream-event-contract.json`, `.bitcode/v37-conversation-writing-workspace.json`, `.bitcode/v37-conversation-source-selector.json`, and `.bitcode/v37-conversation-terminal-handoff.json`
+- Source parity state: V37 source parity begins at Gate 1 with spec family, roadmap, docs, workflow, and checker posture; Gate 2 adds package-owned ConversationSession route-history contracts; Gate 3 adds package-owned ConversationStreamEvent contracts and stream UI binding; Gate 4 adds package-owned ConversationWritingWorkspace fullscreen composer contracts; Gate 5 adds package-owned ConversationSourceSelector context policy; Gate 6 adds package-owned ConversationTerminalHandoff transaction handoff contracts
 - Spec companion: `BITCODE_SPEC_V37.md`
 - Notes companion: `BITCODE_SPEC_V37_NOTES.md`
 - Parity companion: `BITCODE_SPEC_V37_PARITY_MATRIX.md`
@@ -148,6 +148,13 @@ Closure acceptance:
 - handoff routes preserve transaction ids, repository anchors, source selectors, user-readable summary, policy result, and proof roots;
 - `pnpm run check:v37-gate6` validates handoff contracts, route tests, Terminal integration tests, docs, telemetry, and workflow wiring.
 
+Gate 6 closure adds package-backed `ConversationTerminalHandoff` source,
+`.bitcode/v37-conversation-terminal-handoff.json`,
+`source-safe-conversation-terminal-handoff-metadata`, Depositing, Reading,
+Finding Fits, Exchange, settlement, and delivery handoff workflow rows,
+Terminal route context parsing, source-safe handoff UI binding, package tests,
+UI tests, Terminal route tests, workflow wiring, and `check:v37-gate6`.
+
 ### Gate 7: Conversation Persistence Privacy And Redaction
 
 Gate 7 defines durable storage and privacy controls.

BITCODE_SPEC_V37_DELTA.md

@@ -3,13 +3,13 @@
 ## Status
 
 - Version: `V37`
-- V37 state: draft implementation; Gate 4 closes ConversationWritingWorkspace fullscreen writing mode and composer workspace over active V36 Exchange canon
+- V37 state: draft implementation; Gate 6 closes ConversationTerminalHandoff transaction handoff over active V36 Exchange canon
 - Current canonical/latest target: `V36`
 - Current active draft target: `V37`
 - Prior canonical anchor: `BITCODE_SPEC_V36.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V36_PROVEN.md`
-- Generated structured artifact inventory: draft `.bitcode/v37-spec-family-report.json`, `.bitcode/v37-canonical-input-report.json`, `.bitcode/v37-canon-posture-drift-report.json`, `.bitcode/v37-conversation-session-route-history.json`, `.bitcode/v37-conversation-stream-event-contract.json`, and `.bitcode/v37-conversation-writing-workspace.json`
-- Source parity state: V37 source parity begins at Gate 1 with spec family, roadmap, docs, workflow, and checker posture; Gate 2 adds package-owned ConversationSession route-history contracts; Gate 3 adds package-owned ConversationStreamEvent stream contracts; Gate 4 adds package-owned ConversationWritingWorkspace fullscreen composer contracts
+- Generated structured artifact inventory: draft `.bitcode/v37-spec-family-report.json`, `.bitcode/v37-canonical-input-report.json`, `.bitcode/v37-canon-posture-drift-report.json`, `.bitcode/v37-conversation-session-route-history.json`, `.bitcode/v37-conversation-stream-event-contract.json`, `.bitcode/v37-conversation-writing-workspace.json`, `.bitcode/v37-conversation-source-selector.json`, and `.bitcode/v37-conversation-terminal-handoff.json`
+- Source parity state: V37 source parity begins at Gate 1 with spec family, roadmap, docs, workflow, and checker posture; Gate 2 adds package-owned ConversationSession route-history contracts; Gate 3 adds package-owned ConversationStreamEvent stream contracts; Gate 4 adds package-owned ConversationWritingWorkspace fullscreen composer contracts; Gate 5 adds package-owned ConversationSourceSelector context policy; Gate 6 adds package-owned ConversationTerminalHandoff transaction handoff contracts
 - Scope: draft notes for website Conversations work after V36 Exchange depth and after the V28 ChatGPT App MVP proved the interface path.
 
 This NOTES file does not promote V37. It is binding draft guidance while V37 gates are in flight.
@@ -103,6 +103,25 @@ source, unpaid AssetPack source, private BTD material, wallet private material,
 provider tokens, protected prompts/responses, settlement private payloads, and
 global ledger authority claims remain outside Conversations.
 
+## Gate 6 implementation notes
+
+ConversationTerminalHandoff contracts are source-safe transaction-intent
+contracts, not Terminal execution, ledger writes, or wallet signing. Gate 6
+adds `.bitcode/v37-conversation-terminal-handoff.json`,
+`buildConversationTerminalHandoff`, the route-facing handoff helper, the
+handoff component, Terminal route context parsing, package tests, UI tests,
+Terminal route tests, and `check:v37-gate6`.
+
+The required workflows are Depositing, Reading, Finding Fits, Exchange,
+settlement, and delivery. Handoff envelopes may carry conversation id,
+transaction id, repository anchor, source selector summaries, a source-safe
+summary, policy result, Terminal route, transaction detail, proof root, and
+event id. They must not carry protected source, raw protected prompts,
+protected model responses with source, provider tokens, wallet private
+material, settlement private payloads, unpaid AssetPack source, ledger write
+authority, wallet signing authority, or a Terminal authority bypass. The
+Terminal remains the transaction cockpit.
+
 ## V37 gate plan
 
 - Gate 1: V37 Conversations Roadmap And Spec Opening