V30 Gate 1: Roadmap And Gating

.github/pull_request_template.md

@@ -1,7 +1,7 @@
 ## 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`.
+Use the version and gate prefix for gate PRs: `V30 Gate N: Concise Topical Title`.
+Use the version and promotion prefix for version promotion PRs: `V30 Canonical Promotion: Concise Topical Title`.
 
 ## Closure
 

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

@@ -20,7 +20,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Validate active canon and V29 posture
+      - name: Validate active canon and draft posture
         run: |
           POINTER="$(cat BITCODE_SPEC.txt)"
           if [ "$POINTER" = "V28" ]; then
@@ -32,6 +32,7 @@ jobs:
             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
+            node scripts/check-bitcode-spec-family.mjs --version V30 --mode draft --current-target V29
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1
@@ -64,7 +65,7 @@ jobs:
       - name: Checkout repository
         uses: actions/checkout@v4
 
-      - name: Run V29 strict conformance for spec-title changes
+      - name: Run strict conformance for spec-title changes
         run: |
           case "$SPEC_TITLE" in
             spec:\ V29*|spec:\ v29*)
@@ -75,7 +76,10 @@ jobs:
                 node scripts/check-bitcode-spec-family.mjs --version V29 --mode draft --current-target V28
               fi
               ;;
+            spec:\ V30*|spec:\ v30*)
+              node scripts/check-bitcode-spec-family.mjs --version V30 --mode draft --current-target V29
+              ;;
             *)
-              echo "Skipping strict spec-title conformance; title is not a V29 spec change."
+              echo "Skipping strict spec-title conformance; title is not a V29/V30 spec change."
               ;;
           esac

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

@@ -75,9 +75,11 @@ jobs:
             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-spec-family.mjs --version V30 --mode draft --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
+            node scripts/check-v30-gate1-roadmap-and-gating.mjs --skip-branch-check
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1

BITCODE_SPEC_V30_DELTA.md

@@ -0,0 +1,178 @@
+# Bitcode Spec V30 Delta
+
+## Status
+
+- Version: `V30`
+- V30 state: draft target delta opened for Protocol/BTD hardening
+- Current canonical/latest target: `V29`
+- Prior canonical anchor: `BITCODE_SPEC_V29.md`
+- Prior generated proof appendix: `BITCODE_SPEC_V29_PROVEN.md`
+- Generated structured artifact inventory: none for V30 yet; draft gates must create V30 reports and generated proof only as acceptance evidence
+- Source parity state: V30 source parity is draft-opened for Protocol/BTD package APIs, Bitcoin/Taproot/PSBT rigor, BTD receipts, testnet ledger projection, source-to-shares proof cleanup, bridge-readiness boundaries, telemetry hooks, and promotion automation
+- State: draft target delta opened
+- Active canonical pointer during draft opening: `BITCODE_SPEC.txt` -> `V29`
+- Scope: V30 draft delta for Protocol/BTD hardening over promoted V29
+- Spec companion: `BITCODE_SPEC_V30.md`
+- Notes companion: `BITCODE_SPEC_V30_NOTES.md`
+- Parity companion: `BITCODE_SPEC_V30_PARITY_MATRIX.md`
+- Generated proof appendix: none until V30 promotion
+
+## Why V30 exists
+
+V29 canonically promoted Terminal transaction depth over the commercial Reading system.
+It made the operator cockpit more navigable, recoverable, source-safe, repairable, and promotion-proven.
+
+V30 exists because the protocol rails beneath that cockpit now need commercial hardening before Bitcode can responsibly expand into Auxillaries depth, proof depth, interface depth, deployment depth, documentation depth, Exchange, and Conversations.
+The focus is not a new product surface.
+The focus is making Protocol/BTD packages, Bitcoin/Taproot/PSBT flow, BTD receipts, ledger/database/object-storage projections, source-to-shares proofs, and bridge-readiness boundaries stable enough for enterprise shippability.
+
+## Accepted V30 decisions
+
+- V29 remains active canon during V30 drafting.
+- V30 gate branches are opened from `version/v30` and merged back only when their gate acceptance criteria are closed.
+- V30 owns Protocol/BTD hardening, not another Terminal redesign.
+- V30 preserves the V29 Reading journey: request Read, review synthesized Need, request Finding Fits, review source-safe AssetPack preview, buy/settle, and receive paid delivery.
+- V30 narrows shared package APIs before they become Exchange, Auxillaries, interface, deployment, or documentation dependencies.
+- V30 makes Bitcoin fee, Taproot, PSBT, signer, broadcast, replacement, reorg, blocked-readiness, and finality semantics typed and testable.
+- V30 binds BTD-AssetPack mint/read/right-transfer receipts to source-safe preview, paid unlock, delivery, and reconciliation.
+- V30 cleans source-to-shares contribution accounting, settlement conservation, zero-cell/refit tail posture, and no-overpayment/no-underpayment proof surfaces.
+- V30 records bridge-readiness research without treating any bridge as current `$BTD` chain-of-record truth.
+- V30 workflows and scripts must validate V29 active / V30 draft posture.
+
+## Explicitly deferred
+
+- V31 Auxillaries depth remains V31.
+- V32 proof-family/provation expansion remains V32.
+- V33 interface/MCP/ChatGPT/API depth remains V33 except for Protocol/BTD hooks needed by V30.
+- V34 deployment/runtime/storage depth remains V34 except for host-capability facts needed by V30.
+- V35 telemetry/documentation depth remains V35 except for Protocol/BTD telemetry hooks needed by V30.
+- Exchange product/market depth remains beyond V35.
+- Website Conversations product depth remains beyond V35.
+- New `$BTD` supply law remains out of scope.
+- Value-bearing mainnet launch remains separately approval-gated.
+- Bridge integrations remain research posture, not chain-of-record implementation.
+
+## Pre-Implementation Sequence
+
+1. Open `version/v30` from promoted `main`.
+2. Open `v30/gate-1-roadmap-and-gating` from `version/v30`.
+3. Create the V30 SPEC, DELTA, NOTES, and PARITY family while preserving `BITCODE_SPEC.txt -> V29`.
+4. Refresh `SPECIFICATIONS_ROADMAP.md` so V29 is active canon, V30 is draft target, and V31-V37 scopes remain coherent after recent V28/V29 work.
+5. Retarget gate-quality and canon-quality workflow posture checks to V29 active / V30 draft.
+6. Add `check:v30-gate1` and a V30 Gate 1 checker.
+7. Define V30 gates, acceptance criteria, carryforward parity rows, and post-V30 roadmap responsibilities.
+8. Validate spec family, canonical inputs, canon posture, workflows, roadmap truth, README/docs, and diff hygiene.
+9. Push the gate branch and open a pull request to `version/v30`.
+
+## Commit-Body Direction
+
+V30 gate commit bodies should describe the closed gate, specification changes, implementation surfaces, tests, proof commands, and accepted boundaries.
+The eventual V30 promotion commit body must name all closed V30 gates, generated proof artifacts, Protocol/BTD hardening surfaces, and the `BITCODE_SPEC.txt` pointer change from `V29` to `V30`.
+It must explicitly defer V31+ scopes, Exchange, Conversations, bridge chain-of-record implementation, and value-bearing mainnet launch.
+
+## Gate Delta
+
+### Gate 1: V30 Roadmap And Gating
+
+Gate 1 opens V30 correctly:
+
+- V30 SPEC, DELTA, NOTES, and PARITY files exist.
+- `BITCODE_SPEC.txt` remains `V29`.
+- README, roadmap, PR template, and workflows describe V29 active / V30 draft posture.
+- `check:v30-gate1` validates branch naming, spec family, notes, parity, roadmap truth, workflow posture, and promotion boundaries.
+- The V30 gate list is explicit before product implementation begins.
+
+### Gate 2: Protocol Package API Boundaries
+
+Gate 2 narrows the commercial Protocol/BTD package API surface.
+
+Closure acceptance:
+
+- shared Protocol/BTD objects used by multiple interfaces have package-owned builders, parsers, validators, tests, and JSON-safe serialization;
+- route code delegates policy and receipt derivation to packages rather than duplicating it;
+- no commercial runtime code imports `protocol-demonstration/src/*`;
+- package READMEs name ownership boundaries and accepted imports.
+
+### Gate 3: Bitcoin Taproot PSBT Fee Rigor
+
+Gate 3 hardens Bitcoin fee and signer semantics.
+
+Closure acceptance:
+
+- BTC fee quote, signer recovery, PSBT handoff, Taproot/script posture, broadcast, replacement, reorg, and finality states are typed;
+- server-custody rejection remains explicit;
+- testnet/mainnet distinction is policy-enforced and proof-rooted;
+- focused BTD/API tests prove fee lifecycle and blocked-readiness behavior.
+
+### Gate 4: BTD AssetPack Mint And Read Receipts
+
+Gate 4 creates typed BTD receipt boundaries.
+
+Closure acceptance:
+
+- `BtdAssetPackMintReceipt`, `BtdReadReceipt`, and `BtdRightsTransferReceipt` are package-owned;
+- receipts bind AssetPack ids, BTD ranges, Reader/Depositor identities, source-safe preview roots, paid unlock, delivery admission, and ledger projection roots;
+- protected source remains hidden before settlement;
+- receipts are stored, streamed, and rendered through existing execution and Terminal surfaces.
+
+### Gate 5: Testnet Ledger Projection Hardening
+
+Gate 5 hardens ledger/database/object-storage projection and repair.
+
+Closure acceptance:
+
+- ledger-observed facts, database projections, object-storage artifacts, and private metaphysical facts remain distinct;
+- projection repair classes and proof roots are deterministic;
+- Supabase staging-testnet readback can prove synchronized or blocked state without secrets in tracked files;
+- reconciliation tests cover drift, quarantine, retry, and unlock blocking.
+
+### Gate 6: Source-To-Shares Proof Cleanup
+
+Gate 6 cleans contribution measurement and settlement conservation.
+
+Closure acceptance:
+
+- source-to-shares proof surfaces bind measurements, fit deposits, range slices, fee quote, contribution weights, settlement conservation, zero-cell/refit tail posture, and ancestry evidence where available;
+- no-overpayment and no-underpayment invariants are testable;
+- later Exchange work can reuse the proof without reinterpreting V30 accounting.
+
+### Gate 7: Bridge Readiness Research Boundaries
+
+Gate 7 records bridge-readiness without false chain-of-record claims.
+
+Closure acceptance:
+
+- Taproot, BitVM, BSC/opBNB, Binance Web3 Wallet, and future distribution paths have research posture records;
+- each record names feasibility, risks, current non-admission, rereview triggers, and required proof before admission;
+- no bridge path is treated as current `$BTD` chain-of-record truth.
+
+### Gate 8: Protocol Telemetry And Proof Hooks
+
+Gate 8 adds Protocol/BTD telemetry and proof hooks.
+
+Closure acceptance:
+
+- BTD receipts, BTC fee states, ledger projection, source-to-shares proofs, and bridge-readiness posture emit typed telemetry;
+- telemetry avoids protected source and secrets;
+- proof hooks are compatible with V32 provation and V35 documentation/observability work.
+
+### Gate 9: Interface Integration And Regression Proof
+
+Gate 9 proves existing interfaces can consume the hardened Protocol/BTD rails.
+
+Closure acceptance:
+
+- Terminal, API, MCP, ChatGPT App, and future Auxillaries/Exchange hooks consume package-owned objects without route-local reinvention;
+- low-detail source-safe UX remains intact;
+- focused regression tests prove no V29 transaction cockpit behavior regresses.
+
+### Gate 10: V30 Promotion Readiness
+
+Gate 10 owns final local/staging proof, generated artifacts, and V30 promotion workflow support.
+
+Closure acceptance:
+
+- `check:v30-gate10` validates promoted-readiness posture;
+- V30 promotion workflow validates source branch, local proof commands, staging-testnet readback evidence, generated `.bitcode/v30-*` reports, and `BITCODE_SPEC_V30_PROVEN.md`;
+- promotion scripts support V30 and rewrite post-promotion active V30 / draft V31 posture;
+- `version/v30` can be requested into `main` only after all V30 gates close.

BITCODE_SPEC_V30_NOTES.md

@@ -3,7 +3,7 @@
 ## Status
 
 - Version: `V30`
-- V30 state: notes-only draft opening
+- V30 state: draft target opened; Gate 1 converts this file from planning memory into the V30 notes companion
 - Current canonical/latest target: `V29`
 - Current active draft target: `V30`
 - Canonical pointer: `BITCODE_SPEC.txt` -> `V29`
@@ -12,23 +12,34 @@
 - Prior canonical anchor: `BITCODE_SPEC_V29.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V29_PROVEN.md`
 - Generated structured artifact inventory: none for V30 yet
-- Source parity state: notes-only draft opening; V30 source parity begins only after V30 first-gate work
+- Source parity state: V30 source parity begins with Gate 1 roadmap/gating and then closes through Protocol/BTD package API, Bitcoin/PSBT, BTD receipt, ledger projection, source-to-shares, bridge-readiness, telemetry/proof, interface-regression, and promotion-readiness gates
 - Scope: future notes for Protocol/BTD hardening after V28 commercial Protocol/Terminal MVP and V29 deeper Terminal work. Exchange is deferred beyond V35.
 
-This NOTES file does not promote V30 and does not open V30 implementation.
-It preserves roadmap intent so V30 first-gate work can open from promoted V29 without rediscovering deferred Protocol/BTD hardening pressure.
+This NOTES file does not promote V30.
+Gate 1 opens V30 implementation discipline from promoted V29 without rediscovering deferred Protocol/BTD hardening pressure.
 
-## Notes-only draft rule
+## Notes companion rule
 
-This file is planning memory only and is not first-gate implementation.
-Requirements become binding only when V30 is explicitly opened as a full draft-target SPEC family.
+This file is a required companion to `BITCODE_SPEC_V30.md`.
+It may carry planning detail, QA observations, and simplified reading, but it must not override the main V30 SPEC.
+Binding V30 requirements must be reflected in SPEC, DELTA, and PARITY before a gate closes.
 
 ## Concise current-system reading
 
 V29 is active canon.
-V30 is expected to harden Protocol/BTD surfaces after V28/V29 reveal implementation pressure.
+V30 hardens Protocol/BTD surfaces after V28/V29 revealed implementation pressure.
 Exchange is not V30 work.
 
+## Simplified-spec reading rule
+
+For a simplified reading of V30:
+
+1. V29 is the current law.
+2. V30 does not change `$BTD` supply, BTC fee asset, source-safe paid unlock, or the five-step Reading journey.
+3. V30 makes the underlying Protocol/BTD rails more precise: packages, Bitcoin fee flow, receipts, ledger projection, source-to-shares accounting, bridge boundaries, telemetry, and proof hooks.
+4. If a Protocol/BTD fact matters for money, source visibility, rights, proof, delivery, or repair, it must be typed, stored, testable, and source-safe.
+5. `BITCODE_SPEC.txt` remains `V29` until V30 promotion automation advances canon.
+
 ## Deferred from V29
 
 V29 canonically closes deeper Terminal transaction depth, local/staging promotion readiness, and promotion automation.
@@ -46,6 +57,46 @@ V30 owns Protocol/BTD hardening:
 - source-to-shares proof cleanup revealed by V28/V29;
 - Protocol/BTD-specific tests, proofs, and telemetry hooks needed before Exchange returns beyond V35.
 
+## V30 gate plan
+
+1. **Gate 1: V30 Roadmap And Gating**
+   - Open the V30 spec family.
+   - Refresh `SPECIFICATIONS_ROADMAP.md` to current V29 active / V30 draft truth and V31-V37 progressive scopes.
+   - Wire V30 Gate 1 checks, README posture, PR title guidance, gate-quality, and canon-quality posture.
+
+2. **Gate 2: Protocol Package API Boundaries**
+   - Narrow package APIs for shared Protocol/BTD objects used by API, Terminal, MCP, ChatGPT App, and future Auxillaries/Exchange work.
+   - Require package-owned builders, validators, parsers, tests, and JSON-safe serialization before cross-interface use.
+
+3. **Gate 3: Bitcoin Taproot PSBT Fee Rigor**
+   - Harden BTC fee quote, signer recovery, PSBT, Taproot/script posture, broadcast, replacement, reorg, finality, and testnet/mainnet boundaries.
+
+4. **Gate 4: BTD AssetPack Mint And Read Receipts**
+   - Make BTD mint, read, and rights-transfer receipts typed, proof-rooted, stored, streamed, and source-safe.
+
+5. **Gate 5: Testnet Ledger Projection Hardening**
+   - Harden ledger/database/object-storage projection, repair, proof roots, and staging-testnet readback.
+
+6. **Gate 6: Source-To-Shares Proof Cleanup**
+   - Clean contribution measurements, settlement conservation, zero-cell/refit tail, ancestry, and no-overpayment/no-underpayment proof surfaces.
+
+7. **Gate 7: Bridge Readiness Research Boundaries**
+   - Document Taproot, BitVM, BSC/opBNB, Binance Web3 Wallet, and future bridge postures without admitting any as current chain-of-record truth.
+
+8. **Gate 8: Protocol Telemetry And Proof Hooks**
+   - Add typed Protocol/BTD telemetry and proof hooks needed by V32 provation, V34 deployment, and V35 documentation/observability.
+
+9. **Gate 9: Interface Integration And Regression Proof**
+   - Prove existing interfaces consume package-owned Protocol/BTD objects without regressing V29 Terminal transaction behavior.
+
+10. **Gate 10: V30 Promotion Readiness**
+    - Close local/staging proof, generated artifacts, V30 promotion workflow, and post-promotion V30 active / V31 draft posture.
+
+## Gate 1 working notes
+
+Gate 1 is complete only when the V30 family exists, validates in draft mode over active V29, and makes the roadmap truthful enough to drive V31 through V37 without stale V27/V28/V29 posture.
+Gate 1 does not implement Protocol/BTD product hardening; it creates the exact gate map, checks, and documentation needed to do that hardening safely.
+
 ## Non-goals during V30 opening
 
 V30 must not redefine `$BTD` supply, BTC fee separation, AssetPack range identity, owner-read/licensed-read law, measureminting, or ancestry.