V42 Gate 9: Close promotion readiness

Adds the V42 promotion readiness report, generator, checker, canon-promotion workflow, package exports, PROVEN generator support, and promotion dry-run wiring.

Updates V42 spec/docs/roadmap with Gate 9 closure and defers the /packs, /deposit, and /read route cleanup into V43+ planning.

Tightens canonical-input artifact inventory for V41/V42 so demonstration promotion tests match current generated artifact requirements.

Author: geraldarthurdavis

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

@@ -316,6 +316,17 @@ jobs:
               if [ -f scripts/check-v42-gate8-local-staging-mvp-rehearsal.mjs ]; then
                 node scripts/check-v42-gate8-local-staging-mvp-rehearsal.mjs --skip-branch-check --skip-package-tests --skip-uapi-tests
               fi
+              if [ -f scripts/check-v42-gate9-promotion-readiness.mjs ]; then
+                node scripts/check-v42-gate9-promotion-readiness.mjs --promotion-mode --skip-branch-check --skip-package-tests
+              fi
+            fi
+          elif [ "$POINTER" = "V42" ]; then
+            node scripts/check-bitcode-spec-family.mjs --version V42 --mode promoted --current-target V42
+            node scripts/check-bitcode-canonical-inputs.mjs --current-target V42
+            node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V42 --draft-target V43
+            node scripts/check-v42-gate9-promotion-readiness.mjs --promotion-mode --skip-branch-check --skip-package-tests
+            if [ -f BITCODE_SPEC_V43.md ]; then
+              node scripts/check-bitcode-spec-family.mjs --version V43 --mode draft --current-target V42
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2

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

@@ -445,6 +445,17 @@ jobs:
               if [ -f scripts/check-v42-gate8-local-staging-mvp-rehearsal.mjs ]; then
                 node scripts/check-v42-gate8-local-staging-mvp-rehearsal.mjs --skip-branch-check --skip-package-tests --skip-uapi-tests
               fi
+              if [ -f scripts/check-v42-gate9-promotion-readiness.mjs ]; then
+                node scripts/check-v42-gate9-promotion-readiness.mjs --promotion-mode --skip-branch-check --skip-package-tests
+              fi
+            fi
+          elif [ "$POINTER" = "V42" ]; then
+            node scripts/check-bitcode-spec-family.mjs --version V42 --mode promoted --current-target V42
+            node scripts/check-bitcode-canonical-inputs.mjs --current-target V42
+            node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V42 --draft-target V43
+            node scripts/check-v42-gate9-promotion-readiness.mjs --promotion-mode --skip-branch-check --skip-package-tests
+            if [ -f BITCODE_SPEC_V43.md ]; then
+              node scripts/check-bitcode-spec-family.mjs --version V43 --mode draft --current-target V42
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2

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

@@ -0,0 +1,126 @@
+name: V42 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-v42:
+    name: V42 Promotion Validation
+    if: >-
+      ${{
+        github.event_name == 'workflow_dispatch' ||
+        (
+          github.event.pull_request.base.ref == 'main' &&
+          github.event.pull_request.head.ref == 'version/v42' &&
+          github.event.pull_request.head.repo.full_name == github.repository
+        )
+      }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    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 V42 promotion readiness
+        run: |
+          POINTER="$(cat BITCODE_SPEC.txt)"
+          if [ "$POINTER" = "V41" ]; then
+            node scripts/check-bitcode-spec-family.mjs --version V42 --mode draft --current-target V41
+            node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V41 --draft-target V42
+            node scripts/check-bitcode-canonical-inputs.mjs --current-target V41
+            node scripts/check-v42-gate1-mvp-experience-roadmap-opening.mjs --skip-branch-check
+            node scripts/check-v42-gate2-depositing-shortest-path.mjs --skip-branch-check --skip-package-tests
+            node scripts/check-v42-gate3-reading-shortest-path-state-machine.mjs --skip-branch-check --skip-uapi-tests
+            node scripts/check-v42-gate4-readneed-review-resynthesis-product-closure.mjs --skip-branch-check --skip-package-tests --skip-uapi-tests
+            node scripts/check-v42-gate5-readfitsfinding-preview-quote.mjs --skip-branch-check --skip-package-tests --skip-uapi-tests
+            node scripts/check-v42-gate6-settlement-rights-delivery.mjs --skip-branch-check --skip-package-tests --skip-uapi-tests
+            node scripts/check-v42-gate7-ai-reading-demonstration.mjs --skip-branch-check --skip-package-tests --skip-demonstration-tests
+            node scripts/check-v42-gate8-local-staging-mvp-rehearsal.mjs --skip-branch-check --skip-package-tests --skip-uapi-tests
+            node scripts/check-v42-gate9-promotion-readiness.mjs --promotion-mode --skip-branch-check --skip-package-tests
+            node scripts/promote-bitcode-canon.mjs --version V42 --commit HEAD --dry-run
+          elif [ "$POINTER" = "V42" ]; then
+            node scripts/check-bitcode-spec-family.mjs --version V42 --mode promoted --current-target V42
+            node scripts/check-bitcode-canonical-inputs.mjs --current-target V42
+            node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V42 --draft-target V43
+            node scripts/check-v42-gate9-promotion-readiness.mjs --promotion-mode --skip-branch-check --skip-package-tests
+          else
+            echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
+            exit 1
+          fi
+          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
+          git diff --check
+
+      - name: Promote V42 canon files
+        if: >-
+          ${{
+            github.event_name == 'pull_request' &&
+            github.event.pull_request.head.ref == 'version/v42'
+          }}
+        env:
+          HEAD_BRANCH: ${{ github.event.pull_request.head.ref }}
+        run: |
+          if [ "$(cat BITCODE_SPEC.txt)" = "V42" ]; then
+            echo "BITCODE_SPEC.txt already points to V42."
+            exit 0
+          fi
+          PROOF_SOURCE_COMMIT="$(git rev-parse HEAD)"
+          npm run promote:canon -- --version V42 --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_V42.md \
+            BITCODE_SPEC_V42_DELTA.md \
+            BITCODE_SPEC_V42_NOTES.md \
+            BITCODE_SPEC_V42_PARITY_MATRIX.md \
+            BITCODE_SPEC_V42_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 V42"
+          git push origin "HEAD:$HEAD_BRANCH"

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

@@ -72,6 +72,19 @@ Non-goals:
 
 Design principles: shortest credible path, source-safe preview, proof-on-expand, purchase-before-source, depositor compensation visibility, AI-reading demonstration value, and production-hardening through tests.
 
+## V43+ route vocabulary and pack activity cleanup
+
+V42 proves the current MVP path before route vocabulary is renamed.
+The next product cleanup must remove the transitional Terminal/Exchange posture from the core experience.
+`/terminal` should split into `/deposit` and `/read`, and `/exchange` should become `/packs` across route names, component prefixes, tests, docs, and operator vocabulary.
+`/packs` is the searchable master-detail activity surface for all pack activity: deposited AssetPack options, admitted Depository AssetPacks, Finding Fits previews, settled Need-Fit AssetPacks, quotes, rights transfers, compensation posture, repository delivery, proofs, and repair states.
+Its master view must support column sorting, filtering, and search over measurements, synthesized AssetPack titles and descriptions, values, activity or transaction type, settlement state, compensation state, and proof roots.
+Its detail view exposes the selected activity's source-safe proof, telemetry, ledger/database/storage synchronization, and expandable metadata.
+`/deposit` should let enterprises connect source, instruct or accept Bitcode's proposed deposit AssetPack options, review source-safe measurements and likely demand/ROI posture, and approve or reject Depository admission.
+`/read` should own the shortest Reading path from Read Request through reviewed Need, Finding Fits, preview, settlement, and delivery.
+AssetPacks become the in/out simplification: Depositing creates AssetPacks for the Depository, and Reading buys synthesized Need-Fit AssetPacks.
+Outside public documentation, product UX must not rely on self-referential explanatory copy; route structure, progressive detail, labels, and reusable rich components must make core behavior self-explanatory while preserving power-user inspection depth.
+
 ## V42 system architecture and layer boundaries
 
 V42 acts through existing layers:
@@ -180,6 +193,8 @@ The validating command is `pnpm run check:v42-gate8`.
 Gate 9 closes V42 promotion readiness.
 It must bind every V42 artifact, test, workflow, generated proof support, promotion command, active V42 / draft V43 runtime preparation, source-safe generated appendix output, and value-bearing mainnet blocking where relevant.
 It closes only when V42 can be promoted as the reliable MVP experience canon.
+The V42 promotion readiness canon is the generated artifact `.bitcode/v42-promotion-readiness-report.json`, the `BITCODE_SPEC_V42_PROVEN.md` generation path, `.github/workflows/v42-canon-promotion.yml`, package scripts, and promotion dry-run support.
+The accepted post-promotion posture is V42 active / draft V43, with value-bearing mainnet still blocked unless a later promoted canon admits it.
 
 ## V42 canonical subsystem surfaces
 

BITCODE_SPEC_V42.md

@@ -73,13 +73,22 @@ The rehearsal artifact is metadata only and does not serialize secrets, protecte
 ### Gate 9: V42 Promotion Readiness
 
 Bind every V42 product artifact, workflow, generated proof, promotion command, source-safety result, and active V42 / draft V43 runtime posture.
+Gate 9 now closes through `.bitcode/v42-promotion-readiness-report.json`.
+The report proves all V42 gate artifacts are covered, parseable, source-safe, workflow-bound, generated-proof-bound, and blocked from value-bearing mainnet admission.
+The promotion scripts support V42 through `scripts/promote-bitcode-canon.mjs`, `scripts/prepare-bitcode-spec-family-promotion.mjs`, `scripts/prepare-bitcode-runtime-canon-promotion.mjs`, and `.github/workflows/v42-canon-promotion.yml`.
+After promotion, the maintained runtime posture is V42 active / draft V43.
 
 ## Explicitly deferred
 
 - V43+ agentic deposit AssetPack option synthesis remains deferred.
 - `/terminal` is not split into `/read` and `/deposit` during V42.
 - `/exchange` is not renamed to `/packs` during V42.
 - V43+ must take the route-vocabulary cleanup seriously: `/packs` replaces Exchange as the searchable master-detail activity route, including route names, component prefixes, tests, docs, and product vocabulary, while `/read` and `/deposit` become the short core paths for buying and selling AssetPacks.
+- `/packs` must cover all pack activity, including deposited AssetPack options, Depository admission, Finding Fits previews, settled Need-Fit AssetPacks, quotes, rights transfers, compensation posture, delivery, proofs, and repair.
+- `/packs` master view must support column sorting, filtering, and search over measurements, synthesized AssetPack titles and descriptions, values, activity or transaction type, settlement posture, compensation state, and proof roots; the detail view must expose selected source-safe activity data with expandable telemetry, ledger, database, storage, and proof metadata.
+- `/deposit` must evolve beyond manual admission into an agentic connected-repository flow where Bitcode proposes source-safe deposit AssetPack options from enterprise code, depositor instructions, Depository state, and Reading demand; enterprises review measurements, likely demand, likely positive ROI, and sub-criticality before approval.
+- `/read` must own the shortest Reading path without requiring the old Terminal cockpit as the default experience.
+- Outside public documentation, product copy should not compensate for unclear flows with self-referential explanations; V43+ UX should use route structure, concise labels, progressive disclosure, and rich reusable themed components to make core behavior legible.
 - Production-mainnet value-bearing operation remains blocked unless a later promoted canon explicitly admits it.
 - V42 Gate 1 does not change route behavior, pipeline behavior, settlement behavior, or demonstration behavior.
 

BITCODE_SPEC_V42_DELTA.md

@@ -92,6 +92,12 @@ The rehearsal binds `ReadingLocalStagingRehearsal`, Vercel Sandbox operator rece
 It is intentionally source-safe metadata only: secrets, protected source, raw protected prompts, raw interpolated prompts, raw provider responses, unpaid AssetPack source, wallet private material, private settlement payloads, and live rehearsal logs remain outside tracked artifacts.
 Gate 8 does not implement the V43+ route vocabulary, but it keeps the future product shape visible: `/read`, `/deposit`, and `/packs` remain the next route cleanup once V42 proves the current MVP path.
 
+## Gate 9: V42 Promotion Readiness
+
+Gate 9 records the V42 promotion-readiness closure state.
+The generated artifact `.bitcode/v42-promotion-readiness-report.json` binds every V42 product proof from Gates 2 through 8, the V42 promotion workflow, generated proof appendix support, promotion dry-run support, source-safety checks, and value-bearing mainnet blocking.
+The intended post-promotion runtime posture is active V42 / draft V43, so V43 can start from the reliable MVP experience canon and focus on the next product vocabulary and deposit-side evolution.
+
 ## V43+ agentic depositing roadmap note
 
 V43 or a later explicitly opened version should evolve the deposit side into an agentic AssetPack option experience for enterprises.

BITCODE_SPEC_V42_NOTES.md

@@ -40,7 +40,7 @@ This matrix records the reliable MVP product surfaces that must become promotion
 | Settlement and delivery | BTC/BTD settlement, rights transfer, compensation, and repository PR delivery are synchronized | `.bitcode/v42-settlement-rights-delivery.json`, `AssetPackSettlementRightsDeliveryBoundary`, live harness settlement boundary, route summary, Terminal settlement readback | implemented |
 | AI-reading demonstration | Standalone demonstration proves AssetPack improves AI beyond public-data-only baseline | `.bitcode/v42-ai-reading-demonstration.json`, `protocol-demonstration/src/ai-reading-demonstration.js`, `test:v42-ai-reading-mvp` | implemented |
 | Local/staging rehearsal | Full MVP path rehearsed locally and in staging-testnet with mainnet blocked | `.bitcode/v42-local-staging-mvp-rehearsal.json`, `ReadingLocalStagingRehearsal`, `rehearse:v42-local-staging`, `check:v42-gate8` | implemented |
-| Promotion readiness | V42 proof and workflow promotion ready | later V42 Gate 9 artifact | draft-required |
+| Promotion readiness | V42 proof and workflow promotion ready | `.bitcode/v42-promotion-readiness-report.json`, `BITCODE_SPEC_V42_PROVEN.md`, `.github/workflows/v42-canon-promotion.yml`, `check:v42-gate9` | closed |
 
 ## V42 implementation checklist
 
@@ -54,7 +54,17 @@ This matrix records the reliable MVP product surfaces that must become promotion
 | Gate 6 | Settlement rights transfer and repository delivery closure artifact | implemented |
 | Gate 7 | AI-reading dominant demonstration MVP artifact | implemented |
 | Gate 8 | Local and staging-testnet full MVP rehearsal artifact | implemented |
-| Gate 9 | Promotion readiness artifact and workflow | draft-required |
+| Gate 9 | Promotion readiness artifact and workflow | closed |
+
+## Gate 9 Promotion readiness parity
+
+| Area | Closure evidence | Judgment |
+| --- | --- | --- |
+| V42 gate artifacts | Gates 2 through 8 generated artifacts are covered, parseable, and source-safe | closed |
+| Promotion workflow | `.github/workflows/v42-canon-promotion.yml` validates V42 before canon promotion and prepares the V42 active / V43 draft posture | closed |
+| Promotion scripts | `scripts/promote-bitcode-canon.mjs`, `scripts/prepare-bitcode-spec-family-promotion.mjs`, and runtime canon promotion support V42 | closed |
+| Generated proof appendix | `BITCODE_SPEC_V42_PROVEN.md` generation includes `.bitcode/v42-promotion-readiness-report.json` | closed |
+| Value-bearing mainnet | V42 promotion readiness keeps value-bearing mainnet blocked | closed |
 
 ## V42 accepted boundaries
 
@@ -64,6 +74,7 @@ It may not implement route, pipeline, settlement, or demonstration behavior.
 V42 later gates may implement product behavior only if source-safe disclosure, Need review, BTD/BTC settlement, depositor compensation, repository delivery, telemetry, and generated proof obligations are represented in tests and artifacts.
 
 V42 may not split `/terminal` into `/read` and `/deposit`, and may not rename `/exchange` to `/packs`; those are V43+ roadmap items unless explicitly reopened.
+The V43+ parity target is stricter than a route rename: `/packs` must become the searchable master-detail activity route for AssetPacks in and out, `/deposit` must propose and admit reviewable deposit AssetPack options from connected source and Bitcode demand, `/read` must own the Reading purchase path, and product UX outside public documentation must be self-explanatory without self-referential copy.
 
 ## V42 completion condition