Merge pull request #30 from engineeredsoftware/version/v29

V29 Canonical Promotion: Terminal Transaction Depth

Author: geraldarthurdavis

.github/pull_request_template.md

@@ -0,0 +1,11 @@
+## Title
+
+Use the version and gate prefix for gate PRs: `V29 Gate N: Concise Topical Title`.
+Use the version and promotion prefix for version promotion PRs: `V29: Promote Canon`.
+
+## Closure
+
+- Gate:
+- Acceptance criteria closed:
+- Tests/checks run:
+- Accepted boundaries:

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

@@ -20,11 +20,22 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Validate active canon and V28 draft posture
+      - name: Validate active canon and V29 posture
         run: |
-          node scripts/check-bitcode-canonical-inputs.mjs --current-target V27
-          node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V27 --draft-target V28
-          node scripts/check-bitcode-spec-family.mjs --version V28 --mode draft --current-target V27
+          POINTER="$(cat BITCODE_SPEC.txt)"
+          if [ "$POINTER" = "V28" ]; then
+            node scripts/check-bitcode-canonical-inputs.mjs --current-target V28
+            node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V28 --draft-target V29
+            node scripts/check-bitcode-spec-family.mjs --version V28 --mode promoted --current-target V28
+            node scripts/check-bitcode-spec-family.mjs --version V29 --mode draft --current-target V28
+          elif [ "$POINTER" = "V29" ]; then
+            node scripts/check-bitcode-canonical-inputs.mjs --current-target V29
+            node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V29 --draft-target V30
+            node scripts/check-bitcode-spec-family.mjs --version V29 --mode promoted --current-target V29
+          else
+            echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
+            exit 1
+          fi
 
   bitcode-demonstration-mvp:
     name: Bitcode Demonstration MVP
@@ -53,13 +64,18 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Run V28 strict draft conformance for spec-title changes
+      - name: Run V29 strict conformance for spec-title changes
         run: |
           case "$SPEC_TITLE" in
-            spec:\ V28*|spec:\ v28*)
-              node scripts/check-bitcode-spec-family.mjs --version V28 --mode draft --current-target V27
+            spec:\ V29*|spec:\ v29*)
+              POINTER="$(cat BITCODE_SPEC.txt)"
+              if [ "$POINTER" = "V29" ]; then
+                node scripts/check-bitcode-spec-family.mjs --version V29 --mode promoted --current-target V29
+              else
+                node scripts/check-bitcode-spec-family.mjs --version V29 --mode draft --current-target V28
+              fi
               ;;
             *)
-              echo "Skipping strict spec-title conformance; title is not a V28 spec change."
+              echo "Skipping strict spec-title conformance; title is not a V29 spec change."
               ;;
           esac

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

@@ -38,19 +38,50 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Validate gate pull request title
+        if: github.event_name == 'pull_request'
+        env:
+          PR_BASE_REF: ${{ github.base_ref }}
+          PR_HEAD_REF: ${{ github.head_ref }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          if [[ "$PR_BASE_REF" == version/* && "$PR_HEAD_REF" =~ ^v([0-9]+)/gate-([0-9]+)- ]]; then
+            expected_version="V${BASH_REMATCH[1]}"
+            expected_gate="${BASH_REMATCH[2]}"
+            if [[ ! "$PR_TITLE" =~ ^${expected_version}[[:space:]]+Gate[[:space:]]+${expected_gate}:[[:space:]].+ ]]; then
+              echo "Gate pull request titles must begin with: ${expected_version} Gate ${expected_gate}:"
+              echo "Observed: ${PR_TITLE}"
+              exit 1
+            fi
+          fi
+
       - name: Validate draft canon posture
         run: |
-          test "$(cat BITCODE_SPEC.txt)" = "V27"
-          node scripts/check-bitcode-spec-family.mjs --version V28 --mode draft --current-target V27
-          node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V27 --draft-target V28
-          node scripts/check-bitcode-canonical-inputs.mjs --current-target V27
-          node scripts/check-v28-metadevelopment-readiness.mjs --skip-branch-check
-          node scripts/check-v28-gate9-depository-evidence.mjs
-          node scripts/check-v28-gate10-read-need-comprehension.mjs
-          node scripts/check-v28-gate11-read-fits-finding-preview.mjs
-          node scripts/check-v28-gate12-settlement-rights-delivery.mjs
-          node scripts/check-v28-gate13-product-closure-promotion-readiness.mjs
-          node scripts/promote-bitcode-canon.mjs --version V28 --commit HEAD --dry-run
+          POINTER="$(cat BITCODE_SPEC.txt)"
+          if [ "$POINTER" = "V28" ]; then
+            node scripts/check-bitcode-spec-family.mjs --version V28 --mode promoted --current-target V28
+            node scripts/check-bitcode-spec-family.mjs --version V29 --mode draft --current-target V28
+            node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V28 --draft-target V29
+            node scripts/check-bitcode-canonical-inputs.mjs --current-target V28
+            node scripts/check-v29-gate1-objectives-and-gating.mjs --skip-branch-check
+            node scripts/check-v29-gate2-terminal-transaction-read-models.mjs --skip-branch-check
+            node scripts/check-v29-gate3-wallet-signer-btc-operations.mjs --skip-branch-check
+            node scripts/check-v29-gate4-reading-pipeline-observability.mjs --skip-branch-check
+            node scripts/check-v29-gate5-assetpack-disclosure-rights.mjs --skip-branch-check
+            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
+            node scripts/check-v29-gate10-local-staging-promotion-readiness.mjs --skip-branch-check
+          elif [ "$POINTER" = "V29" ]; then
+            node scripts/check-bitcode-spec-family.mjs --version V29 --mode promoted --current-target V29
+            node scripts/check-bitcode-canonical-inputs.mjs --current-target V29
+            node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V29 --draft-target V30
+            node scripts/check-v29-gate10-local-staging-promotion-readiness.mjs --promotion-mode --skip-branch-check
+          else
+            echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
+            exit 1
+          fi
 
       - name: Validate source casing and imports
         run: |
@@ -60,14 +91,27 @@ jobs:
       - name: Type-check gate packages
         run: |
           pnpm --filter @bitcode/btd typecheck
+          pnpm --filter @bitcode/api build
+          pnpm --dir packages/executions-mcp/src/mcp-server run type-check
+          pnpm --dir packages/chatgptapp exec tsc --noEmit --pretty false
           pnpm --filter @bitcode/pipeline-asset-pack typecheck
           pnpm --filter @bitcode/pipeline-hosts typecheck
+          pnpm --filter @bitcode/protocol typecheck
 
       - name: Test gate packages
         run: |
           pnpm --filter @bitcode/btd test
+          pnpm --filter @bitcode/btd test -- --runTestsByPath __tests__/btc-fee-operation.test.ts
+          pnpm --filter @bitcode/btd test -- --runTestsByPath __tests__/btd.test.ts
+          pnpm --filter @bitcode/api exec jest --config jest.config.cjs --runTestsByPath src/routes/__tests__/btd-crypto.test.ts --runInBand
+          pnpm --dir packages/executions-mcp/src/mcp-server run test:mcp -- --runTestsByPath src/__tests__/unit/auth.test.ts --runInBand
+          pnpm --dir packages/chatgptapp exec jest --runTestsByPath src/__tests__/tools.test.ts --runInBand
+          pnpm --filter @bitcode/pipeline-hosts exec jest --config jest.config.cjs --runTestsByPath src/__tests__/asset-pack-harness.test.ts --runInBand
           pnpm --filter @bitcode/pipeline-asset-pack exec jest --config jest.config.cjs --passWithNoTests --forceExit
+          pnpm --filter @bitcode/pipeline-asset-pack exec jest --config jest.config.cjs --runTestsByPath src/__tests__/reading-pipeline-observability.test.ts src/__tests__/reading-pipeline-contract.test.ts --runInBand
+          pnpm --filter @bitcode/pipeline-asset-pack exec jest --config jest.config.cjs --runTestsByPath src/__tests__/asset-pack-disclosure.test.ts src/__tests__/postprocess.test.ts src/__tests__/read-need.test.ts --runInBand
           pnpm --filter @bitcode/pipeline-hosts exec jest --config jest.config.cjs --passWithNoTests --forceExit
+          pnpm --filter @bitcode/protocol test
 
       - name: Test staged Reading route and Terminal harness contracts
         run: |
@@ -76,9 +120,24 @@ jobs:
             tests/api/pipelineHarnessRoute.test.ts \
             tests/terminalPipelineHarnessClient.test.ts \
             tests/terminalDepositReadWorkbench.test.ts \
+            tests/terminalTransactionQuery.test.ts \
+            tests/terminalTransactionReadModel.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/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
 

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

@@ -0,0 +1,145 @@
+name: V29 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-v29:
+    name: V29 Promotion Validation
+    if: >-
+      ${{
+        github.event_name == 'workflow_dispatch' ||
+        (
+          github.event.pull_request.base.ref == 'main' &&
+          github.event.pull_request.head.ref == 'version/v29' &&
+          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 V29 promotion readiness
+        run: |
+          POINTER="$(cat BITCODE_SPEC.txt)"
+          if [ "$POINTER" = "V28" ]; then
+            node scripts/check-bitcode-spec-family.mjs --version V29 --mode draft --current-target V28
+            node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V28 --draft-target V29
+            node scripts/check-bitcode-canonical-inputs.mjs --current-target V28
+            node scripts/check-v29-gate1-objectives-and-gating.mjs --skip-branch-check
+            node scripts/check-v29-gate2-terminal-transaction-read-models.mjs --skip-branch-check
+            node scripts/check-v29-gate3-wallet-signer-btc-operations.mjs --skip-branch-check
+            node scripts/check-v29-gate4-reading-pipeline-observability.mjs --skip-branch-check
+            node scripts/check-v29-gate5-assetpack-disclosure-rights.mjs --skip-branch-check
+            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
+            node scripts/check-v29-gate10-local-staging-promotion-readiness.mjs --promotion-mode --skip-branch-check
+            node scripts/promote-bitcode-canon.mjs --version V29 --commit HEAD --dry-run
+          elif [ "$POINTER" = "V29" ]; then
+            node scripts/check-bitcode-spec-family.mjs --version V29 --mode promoted --current-target V29
+            node scripts/check-bitcode-canonical-inputs.mjs --current-target V29
+            node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V29 --draft-target V30
+            node scripts/check-v29-gate10-local-staging-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/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/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/pipelineExecutionLogHeader.test.tsx \
+            --runInBand
+          pnpm --dir uapi exec playwright install chromium --with-deps
+          pnpm --dir uapi run test:e2e:terminal-ux
+          git diff --check
+
+      - name: Promote V29 canon files
+        if: >-
+          ${{
+            github.event_name == 'pull_request' &&
+            github.event.pull_request.head.ref == 'version/v29'
+          }}
+        env:
+          HEAD_BRANCH: ${{ github.event.pull_request.head.ref }}
+        run: |
+          if [ "$(cat BITCODE_SPEC.txt)" = "V29" ]; then
+            echo "BITCODE_SPEC.txt already points to V29."
+            exit 0
+          fi
+          PROOF_SOURCE_COMMIT="$(git rev-parse HEAD)"
+          npm run promote:canon -- --version V29 --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_V29.md \
+            BITCODE_SPEC_V29_DELTA.md \
+            BITCODE_SPEC_V29_NOTES.md \
+            BITCODE_SPEC_V29_PARITY_MATRIX.md \
+            BITCODE_SPEC_V29_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 V29"
+          git push origin "HEAD:$HEAD_BRANCH"

AGENTS.md

@@ -5,6 +5,7 @@
 - Do not consider any legacy code. All legacy code is located under `_legacy/`.
 - Highest caliber software engineering crafstmanship (maintainibility, abstractions, architectures, naming, patterns, comments, documentation, structures, algorithmic and data flow designs, UI/UX, etc.), correctness (specification and implementation precision, reliability, completeness, boundaried, scoped, encapsulated, etc.), and auditable (totalistic proofs systems from static code, build time, runtime, etc. etc. as is Bitcode, tests from unit, integration, E2E, linting and building, etc.).
 - Do not push work directly to `main`. Create a version base branch for each draft target, such as `version/v28`, then create scoped gate branches from that version branch. Gate branches must be prefixed with the gate number, such as `v28/gate-3-read-fit-workflow` or `v28/gate-8-promotion-proof`. Pull-request each closed gate back into the version branch. Pull-request the version branch into `main` only when all gates are closed and the version is formally promoted as canon. The default branch is protected by the `Bitcode Core Contributions` ruleset and requires pull requests plus verified signatures.
+- Gate pull request titles must begin with the uppercase version and gate prefix, followed by a concise topical title, for example `V29 Gate 5: AssetPack Disclosure Rights And Preview Depth`. Version-promotion pull requests must begin with the uppercase version and name canonical promotion.
 - Once implementation starts on a gate branch, do not stop at partial progress unless blocked by missing external input or explicit user pause. A gate branch is ready to stop only when the gate's acceptance criteria are implemented, specified, tested, documented, committed, pushed, and pull-requested for closure into the version branch.
 - Treat gate and promotion workflow health as part of gate closure. Gate pull requests into version branches must be green through the maintained gate-quality checks, and repository-wide canon-quality checks must remain greenable during draft work. Version pull requests into `main` must pass the version promotion workflow, which performs promotion-grade validations and commits the standalone `BITCODE_SPEC.txt` pointer change only after those validations pass.
 - Keep CI greenable rather than ceremonial. Required application CI uses root pnpm workspace installation and maintained uapi lint/typecheck/build/Jest coverage. Heavy legacy scans such as full DB/browser E2E, Storybook build, super-linter, and advanced CodeQL are opt-in by repository variables until their backing catalogs and service assumptions are maintained for required branch protection.

BITCODE_SPEC.txt

@@ -1 +1 @@
-V28
+V29