Merge pull request #120 from engineeredsoftware/v37/gate-10-promotion-readiness

V37 Gate 10: Conversation Promotion Readiness

Author: geraldarthurdavis

.bitcode/v37-promotion-readiness-report.json

@@ -133,7 +133,15 @@ jobs:
               if [ -f scripts/check-v37-gate9-conversation-rehearsal.mjs ]; then
                 node scripts/check-v37-gate9-conversation-rehearsal.mjs --skip-branch-check
               fi
+              if [ -f scripts/check-v37-gate10-promotion-readiness.mjs ]; then
+                node scripts/check-v37-gate10-promotion-readiness.mjs --promotion-mode --skip-branch-check
+              fi
             fi
+          elif [ "$POINTER" = "V37" ]; then
+            node scripts/check-bitcode-canonical-inputs.mjs --current-target V37
+            node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V37 --draft-target V38
+            node scripts/check-bitcode-spec-family.mjs --version V37 --mode promoted --current-target V37
+            node scripts/check-v37-gate10-promotion-readiness.mjs --promotion-mode --skip-branch-check
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1

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

@@ -262,7 +262,15 @@ jobs:
               if [ -f scripts/check-v37-gate9-conversation-rehearsal.mjs ]; then
                 node scripts/check-v37-gate9-conversation-rehearsal.mjs --skip-branch-check
               fi
+              if [ -f scripts/check-v37-gate10-promotion-readiness.mjs ]; then
+                node scripts/check-v37-gate10-promotion-readiness.mjs --promotion-mode --skip-branch-check
+              fi
             fi
+          elif [ "$POINTER" = "V37" ]; then
+            node scripts/check-bitcode-spec-family.mjs --version V37 --mode promoted --current-target V37
+            node scripts/check-bitcode-canonical-inputs.mjs --current-target V37
+            node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V37 --draft-target V38
+            node scripts/check-v37-gate10-promotion-readiness.mjs --promotion-mode --skip-branch-check
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1
@@ -337,6 +345,7 @@ jobs:
           pnpm --filter @bitcode/api exec jest --config jest.config.cjs --runTestsByPath src/conversations/__tests__/stream-events.test.ts src/conversations/__tests__/privacy.test.ts src/conversations/__tests__/telemetry.test.ts --runInBand --forceExit
           pnpm --dir packages/protocol exec node --test --test-force-exit test/conversation-telemetry-proof-hooks.test.js
           pnpm --dir packages/protocol exec node --test --test-force-exit test/conversation-rehearsal.test.js
+          pnpm --dir packages/protocol exec node --test --test-force-exit test/v37-promotion-readiness.test.js
           pnpm --filter @bitcode/protocol test
 
       - name: Test staged Reading route and Terminal harness contracts

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

@@ -0,0 +1,171 @@
+name: V37 Canon Promotion
+
+on:
+  pull_request:
+    branches:
+      - main
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - ready_for_review
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+  pull-requests: read
+
+jobs:
+  promote-v37:
+    name: V37 Promotion Validation
+    if: >-
+      ${{
+        github.event_name == 'workflow_dispatch' ||
+        (
+          github.event.pull_request.base.ref == 'main' &&
+          github.event.pull_request.head.ref == 'version/v37' &&
+          github.event.pull_request.head.repo.full_name == github.repository
+        )
+      }}
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout version branch
+        uses: actions/checkout@v4
+        with:
+          ref: ${{ github.event.pull_request.head.ref || github.ref_name }}
+          token: ${{ github.token }}
+          fetch-depth: 0
+
+      - name: Setup pnpm
+        uses: pnpm/action-setup@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "24"
+          cache: pnpm
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Validate V37 promotion readiness
+        run: |
+          POINTER="$(cat BITCODE_SPEC.txt)"
+          if [ "$POINTER" = "V36" ]; then
+            node scripts/check-bitcode-spec-family.mjs --version V37 --mode draft --current-target V36
+            node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V36 --draft-target V37
+            node scripts/check-bitcode-canonical-inputs.mjs --current-target V36
+            node scripts/check-v37-gate1-conversations-roadmap-opening.mjs --skip-branch-check
+            node scripts/check-v37-gate2-conversation-session-route-history-contracts.mjs --skip-branch-check
+            node scripts/check-v37-gate3-conversation-stream-event-contracts.mjs --skip-branch-check
+            node scripts/check-v37-gate4-conversation-writing-workspace.mjs --skip-branch-check
+            node scripts/check-v37-gate5-conversation-source-selector.mjs --skip-branch-check
+            node scripts/check-v37-gate6-conversation-terminal-handoff.mjs --skip-branch-check
+            node scripts/check-v37-gate7-conversation-persistence-privacy-redaction.mjs --skip-branch-check
+            node scripts/check-v37-gate8-conversation-telemetry-proof-hooks.mjs --skip-branch-check
+            node scripts/check-v37-gate9-conversation-rehearsal.mjs --skip-branch-check
+            node scripts/check-v37-gate10-promotion-readiness.mjs --promotion-mode --skip-branch-check
+            node scripts/promote-bitcode-canon.mjs --version V37 --commit HEAD --dry-run
+          elif [ "$POINTER" = "V37" ]; then
+            node scripts/check-bitcode-spec-family.mjs --version V37 --mode promoted --current-target V37
+            node scripts/check-bitcode-canonical-inputs.mjs --current-target V37
+            node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V37 --draft-target V38
+            node scripts/check-v37-gate10-promotion-readiness.mjs --promotion-mode --skip-branch-check
+          else
+            echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
+            exit 1
+          fi
+          pnpm test:qa:v28:pipeline-readback
+          pnpm --filter @bitcode/protocol typecheck
+          pnpm --filter @bitcode/protocol test
+          pnpm --filter @bitcode/btd typecheck
+          pnpm --filter @bitcode/btd test
+          npm --prefix protocol-demonstration test
+          npm --prefix protocol-demonstration run test:v28-mvp-qa
+          pnpm --filter @bitcode/pipeline-asset-pack typecheck
+          pnpm --filter @bitcode/pipeline-hosts typecheck
+          pnpm --filter @bitcode/pipeline-asset-pack exec jest --config jest.config.cjs --passWithNoTests --forceExit
+          pnpm --filter @bitcode/pipeline-hosts exec jest --config jest.config.cjs --passWithNoTests --forceExit
+          pnpm --dir uapi exec jest --runTestsByPath \
+            tests/userDataRoute.test.ts \
+            tests/auxillariesWalletPane.test.tsx \
+            tests/auxillariesContent.access.test.tsx \
+            tests/auxillariesWorkspacePanels.access.test.tsx \
+            tests/auxillariesWorkspacePanels.test.tsx \
+            tests/api/auxillariesGithubConnectionRoute.test.ts \
+            tests/api/vcsRoutes.test.ts \
+            tests/auxillariesExternalsPane.test.tsx \
+            tests/profileStep.test.tsx \
+            tests/api/readReviewRoute.test.ts \
+            tests/api/pipelineHarnessRoute.test.ts \
+            tests/terminalPipelineHarnessClient.test.ts \
+            tests/terminalDepositReadWorkbench.test.ts \
+            tests/terminalTransactionQuery.test.ts \
+            tests/terminalTransactionReadModel.test.ts \
+            tests/terminalProtocolProjection.test.ts \
+            tests/terminalInterfaceIntegrationRegression.test.ts \
+            tests/terminalWalletBtcOperation.test.ts \
+            tests/terminalJournalReconciliation.test.ts \
+            tests/terminalOrganizationAuthority.test.ts \
+            tests/protocolCommercialBoundary.test.ts \
+            tests/terminalTransactionDetailCards.test.tsx \
+            tests/terminalTransactionDetailSnapshot.test.ts \
+            tests/terminalUxBrowserProof.test.tsx \
+            tests/bitcodeBrowserAccessibilityResponsiveProof.test.ts \
+            tests/pipelineExecutionLogHeader.test.tsx \
+            tests/api/conversationSessionRouteHistory.test.ts \
+            tests/api/conversationSessionRouteHistoryContract.test.ts \
+            tests/api/conversationStreamEventContract.test.ts \
+            tests/conversationStreamPipelineLog.test.tsx \
+            tests/conversationWritingWorkspace.test.tsx \
+            tests/conversationSourceSelector.test.tsx \
+            tests/conversationTerminalHandoff.test.tsx \
+            tests/api/conversationPersistencePrivacyRedaction.test.ts \
+            tests/conversationPersistencePrivacyPanel.test.tsx \
+            tests/api/conversationTelemetryProofHooks.test.ts \
+            tests/conversationTelemetryProofPanel.test.tsx \
+            tests/api/conversationRehearsal.test.ts \
+            tests/conversationRehearsalPanel.test.tsx \
+            --runInBand
+          pnpm --dir uapi exec playwright install chromium --with-deps
+          pnpm --dir uapi run test:e2e:terminal-ux
+          pnpm --dir uapi run test:e2e:v32-browser-proof
+          git diff --check
+
+      - name: Promote V37 canon files
+        if: >-
+          ${{
+            github.event_name == 'pull_request' &&
+            github.event.pull_request.head.ref == 'version/v37'
+          }}
+        env:
+          HEAD_BRANCH: ${{ github.event.pull_request.head.ref }}
+        run: |
+          if [ "$(cat BITCODE_SPEC.txt)" = "V37" ]; then
+            echo "BITCODE_SPEC.txt already points to V37."
+            exit 0
+          fi
+          PROOF_SOURCE_COMMIT="$(git rev-parse HEAD)"
+          npm run promote:canon -- --version V37 --commit "$PROOF_SOURCE_COMMIT"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git add \
+            BITCODE_SPEC.txt \
+            BITCODE_SPEC_V37.md \
+            BITCODE_SPEC_V37_DELTA.md \
+            BITCODE_SPEC_V37_NOTES.md \
+            BITCODE_SPEC_V37_PARITY_MATRIX.md \
+            BITCODE_SPEC_V37_PROVEN.md \
+            protocol-demonstration/src/canon-posture.js \
+            protocol-demonstration/README.md \
+            packages/protocol/src/canon-posture.js \
+            packages/protocol/data/state.json \
+            packages/protocol/README.md \
+            .bitcode
+          git commit -m "Promote Bitcode canon to V37"
+          git push origin "HEAD:$HEAD_BRANCH"

.github/workflows/v37-canon-promotion.yml

@@ -3,18 +3,18 @@
 ## Status
 
 - Version: `V37`
-- V37 state: draft implementation; Gate 9 closes ConversationRehearsal local/staging proof over active V36 Exchange canon
+- V37 state: draft implementation; Gate 10 closes ConversationPromotionReadinessReport 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`, `.bitcode/v37-conversation-source-selector.json`, `.bitcode/v37-conversation-terminal-handoff.json`, `.bitcode/v37-conversation-persistence-privacy-redaction.json`, `.bitcode/v37-conversation-telemetry-proof-hooks.json`, and `.bitcode/v37-conversation-rehearsal.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, Gate 6 package-owned ConversationTerminalHandoff transaction handoff contracts, Gate 7 package-owned ConversationPersistencePrivacyRedaction durable storage privacy contracts, Gate 8 package-owned ConversationTelemetryProofHooks telemetry, dashboard, runbook, and docs contracts, and Gate 9 package-owned ConversationRehearsal local/staging proof 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`, `.bitcode/v37-conversation-terminal-handoff.json`, `.bitcode/v37-conversation-persistence-privacy-redaction.json`, `.bitcode/v37-conversation-telemetry-proof-hooks.json`, `.bitcode/v37-conversation-rehearsal.json`, and `.bitcode/v37-promotion-readiness-report.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, Gate 6 package-owned ConversationTerminalHandoff transaction handoff contracts, Gate 7 package-owned ConversationPersistencePrivacyRedaction durable storage privacy contracts, Gate 8 package-owned ConversationTelemetryProofHooks telemetry, dashboard, runbook, and docs contracts, Gate 9 package-owned ConversationRehearsal local/staging proof contracts, and Gate 10 package-owned ConversationPromotionReadinessReport promotion closure 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`
 - Parity companion: `BITCODE_SPEC_V37_PARITY_MATRIX.md`
 - Generated proof appendix: `BITCODE_SPEC_V37_PROVEN.md` only after V37 promotion
-- Scope: V37 draft system specification for Website Conversations, route-local conversational state, stream UI, fullscreen writing mode, source selectors, Terminal handoff, persistence/privacy, telemetry/proof hooks, and local/staging rehearsal over promoted V36 Exchange canon
+- Scope: V37 draft system specification for Website Conversations, route-local conversational state, stream UI, fullscreen writing mode, source selectors, Terminal handoff, persistence/privacy, telemetry/proof hooks, local/staging rehearsal, and promotion readiness over promoted V36 Exchange canon
 - Last fully realized canonical target preserved in source: `V36`
 
 ## Version executive summary
@@ -297,6 +297,42 @@ docs, workflow wiring, rehearsal flow coverage, lane coverage, route/UI check
 coverage, telemetry check coverage, source-safe screenshot/log coverage, proof
 roots, source evidence roots, and `source-safe-conversation-rehearsal-metadata`.
 
+## V37 Gate 10 ConversationPromotionReadinessReport canon
+
+V37 promotion readiness canon is carried by
+`ConversationPromotionReadinessReport` and
+`.bitcode/v37-promotion-readiness-report.json`.
+
+Gate 10 implements `ConversationPromotionReadinessReport` as the package-owned
+promotion readiness contract for Website Conversations. It binds the eight V37
+Conversation artifacts, generated proof outputs, gate-quality workflow,
+canon-quality workflow, V37 promotion workflow, promotion script, spec-family
+promotion script, runtime posture promotion script, and proven generator into a
+single source-safe readiness artifact:
+`.bitcode/v37-promotion-readiness-report.json`.
+
+The readiness report is source-safe promotion metadata. It records
+`source-safe-conversation-promotion-readiness-metadata`, V36 active / V37 draft
+pre-promotion posture, V37 active / draft V38 post-promotion posture, branch
+protection expectations, generated proof output expectations, the validation
+commands required for all V37 gates, and a V37 promotion dry-run command. It
+must fail closed when any Conversation artifact is missing, unparseable,
+source-unsafe, stale, or disconnected from source evidence; when workflow,
+promotion, spec-family, runtime, or proven-generator support is missing; or
+when any value-bearing mainnet, credential, protected source, raw protected
+prompt, unpaid AssetPack source, or wallet private material is admitted.
+
+Gate 10 adds `generate:v37-promotion-readiness`,
+`check:v37-promotion-readiness`, `check:v37-gate10`, package tests for
+`ConversationPromotionReadinessReport`, V37 proven-generator support,
+`v37-canon-promotion.yml`, and V37 promotion support in
+`promote-bitcode-canon.mjs` and
+`prepare-bitcode-spec-family-promotion.mjs`. V37 promotion may rewrite
+`BITCODE_SPEC.txt` from `V36` to `V37` only after the promotion workflow proves
+the hand-authored V37 family, generated V37 artifacts, generated
+`BITCODE_SPEC_V37_PROVEN.md`, and runtime posture rewrite to V37 active / draft
+V38 are coherent.
+
 ## Inherited V36 Exchange canon
 
 The promoted V36 sections below remain inherited canonical law for Exchange.
@@ -979,6 +1015,7 @@ V36 inherits operator quality, visual/accessibility/performance posture, project
 | `.bitcode/v37-conversation-persistence-privacy-redaction.json` | Gate 7 | source-safe | ConversationPersistencePrivacyRedaction durable storage privacy contracts |
 | `.bitcode/v37-conversation-telemetry-proof-hooks.json` | Gate 8 | source-safe | ConversationTelemetryProofHooks dashboard/runbook contracts |
 | `.bitcode/v37-conversation-rehearsal.json` | Gate 9 | source-safe | ConversationRehearsal local/staging proof contracts |
+| `.bitcode/v37-promotion-readiness-report.json` | Gate 10 | source-safe | ConversationPromotionReadinessReport promotion readiness |
 
 ### V37 specifying generated artifacts
 
@@ -991,6 +1028,7 @@ Gate 6 adds `.bitcode/v37-conversation-terminal-handoff.json` from the package-o
 Gate 7 adds `.bitcode/v37-conversation-persistence-privacy-redaction.json` from the package-owned ConversationPersistencePrivacyRedaction builder with package tests, API storage redaction tests, UI tests, workflow checks, and source-safety checks.
 Gate 8 adds `.bitcode/v37-conversation-telemetry-proof-hooks.json` from the package-owned ConversationTelemetryProofHooks builder with package tests, API telemetry tests, UI tests, docs, runbooks, workflow checks, and source-safety checks.
 Gate 9 adds `.bitcode/v37-conversation-rehearsal.json` from the package-owned ConversationRehearsal builder with package tests, UI tests, local/staging rehearsal proof, route/UI checks, telemetry roots, source-safe screenshot/log roots, workflow checks, and source-safety checks.
+Gate 10 adds `.bitcode/v37-promotion-readiness-report.json` from the package-owned ConversationPromotionReadinessReport builder with package tests, generated proof support, promotion workflow support, V37 active / draft V38 posture coverage, promotion dry-run support, and source-safety checks.
 
 ### Shared generated-artifact fields