Skip to content

Commit 415146f

Browse files
V29 Gate 10: Local And Staging Promotion Readiness
Closes Gate 10 by adding local/staging promotion-readiness specification, QA ledger, V29 promotion workflow automation, V29 promotion command planning, and runtime posture promotion coverage.
1 parent 7a2c464 commit 415146f

17 files changed

Lines changed: 977 additions & 52 deletions

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

Lines changed: 22 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -20,12 +20,22 @@ jobs:
2020
- name: Checkout repository
2121
uses: actions/checkout@v4
2222

23-
- name: Validate active canon and V29 draft posture
23+
- name: Validate active canon and V29 posture
2424
run: |
25-
node scripts/check-bitcode-canonical-inputs.mjs --current-target V28
26-
node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V28 --draft-target V29
27-
node scripts/check-bitcode-spec-family.mjs --version V28 --mode promoted --current-target V28
28-
node scripts/check-bitcode-spec-family.mjs --version V29 --mode draft --current-target V28
25+
POINTER="$(cat BITCODE_SPEC.txt)"
26+
if [ "$POINTER" = "V28" ]; then
27+
node scripts/check-bitcode-canonical-inputs.mjs --current-target V28
28+
node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V28 --draft-target V29
29+
node scripts/check-bitcode-spec-family.mjs --version V28 --mode promoted --current-target V28
30+
node scripts/check-bitcode-spec-family.mjs --version V29 --mode draft --current-target V28
31+
elif [ "$POINTER" = "V29" ]; then
32+
node scripts/check-bitcode-canonical-inputs.mjs --current-target V29
33+
node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V29 --draft-target V30
34+
node scripts/check-bitcode-spec-family.mjs --version V29 --mode promoted --current-target V29
35+
else
36+
echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
37+
exit 1
38+
fi
2939
3040
bitcode-demonstration-mvp:
3141
name: Bitcode Demonstration MVP
@@ -54,11 +64,16 @@ jobs:
5464
- name: Checkout repository
5565
uses: actions/checkout@v4
5666

57-
- name: Run V29 strict draft conformance for spec-title changes
67+
- name: Run V29 strict conformance for spec-title changes
5868
run: |
5969
case "$SPEC_TITLE" in
6070
spec:\ V29*|spec:\ v29*)
61-
node scripts/check-bitcode-spec-family.mjs --version V29 --mode draft --current-target V28
71+
POINTER="$(cat BITCODE_SPEC.txt)"
72+
if [ "$POINTER" = "V29" ]; then
73+
node scripts/check-bitcode-spec-family.mjs --version V29 --mode promoted --current-target V29
74+
else
75+
node scripts/check-bitcode-spec-family.mjs --version V29 --mode draft --current-target V28
76+
fi
6277
;;
6378
*)
6479
echo "Skipping strict spec-title conformance; title is not a V29 spec change."

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

Lines changed: 25 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -57,20 +57,31 @@ jobs:
5757
5858
- name: Validate draft canon posture
5959
run: |
60-
test "$(cat BITCODE_SPEC.txt)" = "V28"
61-
node scripts/check-bitcode-spec-family.mjs --version V28 --mode promoted --current-target V28
62-
node scripts/check-bitcode-spec-family.mjs --version V29 --mode draft --current-target V28
63-
node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V28 --draft-target V29
64-
node scripts/check-bitcode-canonical-inputs.mjs --current-target V28
65-
node scripts/check-v29-gate1-objectives-and-gating.mjs --skip-branch-check
66-
node scripts/check-v29-gate2-terminal-transaction-read-models.mjs --skip-branch-check
67-
node scripts/check-v29-gate3-wallet-signer-btc-operations.mjs --skip-branch-check
68-
node scripts/check-v29-gate4-reading-pipeline-observability.mjs --skip-branch-check
69-
node scripts/check-v29-gate5-assetpack-disclosure-rights.mjs --skip-branch-check
70-
node scripts/check-v29-gate6-settlement-reconciliation-repair.mjs --skip-branch-check
71-
node scripts/check-v29-gate7-organization-permission-authority.mjs --skip-branch-check
72-
node scripts/check-v29-gate8-demonstration-origin-formalization.mjs --skip-branch-check
73-
node scripts/check-v29-gate9-terminal-ux-browser-proof.mjs --skip-branch-check
60+
POINTER="$(cat BITCODE_SPEC.txt)"
61+
if [ "$POINTER" = "V28" ]; then
62+
node scripts/check-bitcode-spec-family.mjs --version V28 --mode promoted --current-target V28
63+
node scripts/check-bitcode-spec-family.mjs --version V29 --mode draft --current-target V28
64+
node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V28 --draft-target V29
65+
node scripts/check-bitcode-canonical-inputs.mjs --current-target V28
66+
node scripts/check-v29-gate1-objectives-and-gating.mjs --skip-branch-check
67+
node scripts/check-v29-gate2-terminal-transaction-read-models.mjs --skip-branch-check
68+
node scripts/check-v29-gate3-wallet-signer-btc-operations.mjs --skip-branch-check
69+
node scripts/check-v29-gate4-reading-pipeline-observability.mjs --skip-branch-check
70+
node scripts/check-v29-gate5-assetpack-disclosure-rights.mjs --skip-branch-check
71+
node scripts/check-v29-gate6-settlement-reconciliation-repair.mjs --skip-branch-check
72+
node scripts/check-v29-gate7-organization-permission-authority.mjs --skip-branch-check
73+
node scripts/check-v29-gate8-demonstration-origin-formalization.mjs --skip-branch-check
74+
node scripts/check-v29-gate9-terminal-ux-browser-proof.mjs --skip-branch-check
75+
node scripts/check-v29-gate10-local-staging-promotion-readiness.mjs --skip-branch-check
76+
elif [ "$POINTER" = "V29" ]; then
77+
node scripts/check-bitcode-spec-family.mjs --version V29 --mode promoted --current-target V29
78+
node scripts/check-bitcode-canonical-inputs.mjs --current-target V29
79+
node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V29 --draft-target V30
80+
node scripts/check-v29-gate10-local-staging-promotion-readiness.mjs --promotion-mode --skip-branch-check
81+
else
82+
echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
83+
exit 1
84+
fi
7485
7586
- name: Validate source casing and imports
7687
run: |
Lines changed: 145 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
name: V29 Canon Promotion
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- main
7+
types:
8+
- opened
9+
- synchronize
10+
- reopened
11+
- ready_for_review
12+
workflow_dispatch:
13+
14+
concurrency:
15+
group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
16+
cancel-in-progress: true
17+
18+
permissions:
19+
contents: write
20+
pull-requests: read
21+
22+
jobs:
23+
promote-v29:
24+
name: V29 Promotion Validation
25+
if: >-
26+
${{
27+
github.event_name == 'workflow_dispatch' ||
28+
(
29+
github.event.pull_request.base.ref == 'main' &&
30+
github.event.pull_request.head.ref == 'version/v29' &&
31+
github.event.pull_request.head.repo.full_name == github.repository
32+
)
33+
}}
34+
runs-on: ubuntu-latest
35+
36+
steps:
37+
- name: Checkout version branch
38+
uses: actions/checkout@v4
39+
with:
40+
ref: ${{ github.event.pull_request.head.ref || github.ref_name }}
41+
token: ${{ github.token }}
42+
fetch-depth: 0
43+
44+
- name: Setup pnpm
45+
uses: pnpm/action-setup@v4
46+
47+
- name: Setup Node
48+
uses: actions/setup-node@v4
49+
with:
50+
node-version: "24"
51+
cache: pnpm
52+
53+
- name: Install dependencies
54+
run: pnpm install --frozen-lockfile
55+
56+
- name: Validate V29 promotion readiness
57+
run: |
58+
POINTER="$(cat BITCODE_SPEC.txt)"
59+
if [ "$POINTER" = "V28" ]; then
60+
node scripts/check-bitcode-spec-family.mjs --version V29 --mode draft --current-target V28
61+
node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V28 --draft-target V29
62+
node scripts/check-bitcode-canonical-inputs.mjs --current-target V28
63+
node scripts/check-v29-gate1-objectives-and-gating.mjs --skip-branch-check
64+
node scripts/check-v29-gate2-terminal-transaction-read-models.mjs --skip-branch-check
65+
node scripts/check-v29-gate3-wallet-signer-btc-operations.mjs --skip-branch-check
66+
node scripts/check-v29-gate4-reading-pipeline-observability.mjs --skip-branch-check
67+
node scripts/check-v29-gate5-assetpack-disclosure-rights.mjs --skip-branch-check
68+
node scripts/check-v29-gate6-settlement-reconciliation-repair.mjs --skip-branch-check
69+
node scripts/check-v29-gate7-organization-permission-authority.mjs --skip-branch-check
70+
node scripts/check-v29-gate8-demonstration-origin-formalization.mjs --skip-branch-check
71+
node scripts/check-v29-gate9-terminal-ux-browser-proof.mjs --skip-branch-check
72+
node scripts/check-v29-gate10-local-staging-promotion-readiness.mjs --promotion-mode --skip-branch-check
73+
node scripts/promote-bitcode-canon.mjs --version V29 --commit HEAD --dry-run
74+
elif [ "$POINTER" = "V29" ]; then
75+
node scripts/check-bitcode-spec-family.mjs --version V29 --mode promoted --current-target V29
76+
node scripts/check-bitcode-canonical-inputs.mjs --current-target V29
77+
node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V29 --draft-target V30
78+
node scripts/check-v29-gate10-local-staging-promotion-readiness.mjs --promotion-mode --skip-branch-check
79+
else
80+
echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
81+
exit 1
82+
fi
83+
pnpm test:qa:v28:pipeline-readback
84+
pnpm --filter @bitcode/protocol typecheck
85+
pnpm --filter @bitcode/protocol test
86+
pnpm --filter @bitcode/btd typecheck
87+
pnpm --filter @bitcode/btd test
88+
npm --prefix protocol-demonstration test
89+
npm --prefix protocol-demonstration run test:v28-mvp-qa
90+
pnpm --filter @bitcode/pipeline-asset-pack typecheck
91+
pnpm --filter @bitcode/pipeline-hosts typecheck
92+
pnpm --filter @bitcode/pipeline-asset-pack exec jest --config jest.config.cjs --passWithNoTests --forceExit
93+
pnpm --filter @bitcode/pipeline-hosts exec jest --config jest.config.cjs --passWithNoTests --forceExit
94+
pnpm --dir uapi exec jest --runTestsByPath \
95+
tests/api/readReviewRoute.test.ts \
96+
tests/api/pipelineHarnessRoute.test.ts \
97+
tests/terminalPipelineHarnessClient.test.ts \
98+
tests/terminalDepositReadWorkbench.test.ts \
99+
tests/terminalTransactionQuery.test.ts \
100+
tests/terminalTransactionReadModel.test.ts \
101+
tests/terminalWalletBtcOperation.test.ts \
102+
tests/terminalJournalReconciliation.test.ts \
103+
tests/terminalOrganizationAuthority.test.ts \
104+
tests/protocolCommercialBoundary.test.ts \
105+
tests/terminalTransactionDetailCards.test.tsx \
106+
tests/terminalTransactionDetailSnapshot.test.ts \
107+
tests/terminalUxBrowserProof.test.tsx \
108+
tests/pipelineExecutionLogHeader.test.tsx \
109+
--runInBand
110+
pnpm --dir uapi exec playwright install chromium --with-deps
111+
pnpm --dir uapi run test:e2e:terminal-ux
112+
git diff --check
113+
114+
- name: Promote V29 canon files
115+
if: >-
116+
${{
117+
github.event_name == 'pull_request' &&
118+
github.event.pull_request.head.ref == 'version/v29'
119+
}}
120+
env:
121+
HEAD_BRANCH: ${{ github.event.pull_request.head.ref }}
122+
run: |
123+
if [ "$(cat BITCODE_SPEC.txt)" = "V29" ]; then
124+
echo "BITCODE_SPEC.txt already points to V29."
125+
exit 0
126+
fi
127+
PROOF_SOURCE_COMMIT="$(git rev-parse HEAD)"
128+
npm run promote:canon -- --version V29 --commit "$PROOF_SOURCE_COMMIT"
129+
git config user.name "github-actions[bot]"
130+
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
131+
git add \
132+
BITCODE_SPEC.txt \
133+
BITCODE_SPEC_V29.md \
134+
BITCODE_SPEC_V29_DELTA.md \
135+
BITCODE_SPEC_V29_NOTES.md \
136+
BITCODE_SPEC_V29_PARITY_MATRIX.md \
137+
BITCODE_SPEC_V29_PROVEN.md \
138+
protocol-demonstration/src/canon-posture.js \
139+
protocol-demonstration/README.md \
140+
packages/protocol/src/canon-posture.js \
141+
packages/protocol/data/state.json \
142+
packages/protocol/README.md \
143+
.bitcode
144+
git commit -m "Promote Bitcode canon to V29"
145+
git push origin "HEAD:$HEAD_BRANCH"

BITCODE_SPEC_V29.md

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -246,6 +246,41 @@ The focused Playwright spec proves the cockpit in a real browser in deterministi
246246
Gate 9 acceptance does not change Reading law, source disclosure law, settlement law, or organization authority law.
247247
It makes the current V29 Terminal cockpit commercially operable enough that later local/staging promotion readiness can debug failures from the UI rather than from browser network logs alone.
248248

249+
## V29 local and staging promotion readiness canon
250+
251+
V29 promotion is admissible only when the version branch can prove both source
252+
closure and promotion automation without relying on unstated operator memory.
253+
Gate 10 owns that closure.
254+
255+
The promotion-readiness contract has five parts:
256+
257+
- all V29 gate scripts are invoked by gate-quality CI while `BITCODE_SPEC.txt`
258+
remains `V28`;
259+
- gate-quality and canon-quality workflows also accept the promoted state after
260+
the V29 promotion workflow commits `BITCODE_SPEC.txt -> V29`;
261+
- the canonical promotion command supports `--version V29`, validates the V29
262+
draft family, runs local proof suites, prepares V29 hand-authored status
263+
truth, prepares runtime canon posture for V29 active / V30 draft, generates
264+
`BITCODE_SPEC_V29_PROVEN.md`, writes `.bitcode/v29-*` proof artifacts, and
265+
then validates the promoted V29 family;
266+
- the version-promotion workflow runs only for a `version/v29` pull request into
267+
`main`, validates the same proof surface, and commits the generated promotion
268+
artifacts back to the version branch;
269+
- local and staging-testnet QA evidence remains source-safe: environment
270+
readiness, pipeline readback, Terminal browser proof, ledger/database
271+
reconciliation posture, protocol package posture, and promotion dry-run are
272+
named without committing secrets.
273+
274+
`packages/protocol/src/canon-posture.js` and
275+
`packages/protocol/data/state.json` are commercial runtime posture carriers.
276+
They must align to V28 active / V29 draft during Gate 10 work and be rewritten
277+
to V29 active / V30 draft by promotion automation.
278+
279+
Gate 10 does not itself promote `BITCODE_SPEC.txt`.
280+
It closes when `version/v29` can be pull-requested to `main` and the V29
281+
promotion workflow has enough scripted proof to produce the standalone
282+
canonical promotion commit.
283+
249284
## V29 Wallet/BTC operation canon
250285

251286
Wallet and BTC fee state is an ordinary Terminal transaction surface, not an opaque settlement footnote.

BITCODE_SPEC_V29_DELTA.md

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -196,3 +196,30 @@ Closure acceptance:
196196
### Gate 10: Local And Staging Promotion Readiness
197197

198198
Gate 10 owns non-mocked local validation, staging-testnet readback, generated proof artifacts, V29 promotion workflow support, promotion dry-run, and final version branch readiness.
199+
200+
Closure acceptance:
201+
202+
- `check:v29-gate10` validates the V29 promotion-readiness surface from a clean
203+
Gate 10 branch and can run in `--promotion-mode` after `BITCODE_SPEC.txt`
204+
advances to `V29`.
205+
- Gate-quality CI invokes all V29 gate scripts while V29 is still a draft and
206+
switches to promoted V29 validation after the promotion workflow writes the
207+
canonical pointer commit.
208+
- Canon-quality CI validates either V28 active / V29 draft posture or V29 active
209+
/ V30 draft posture so the version branch remains green before and after
210+
promotion automation commits generated canon.
211+
- `promote:canon -- --version V29 --commit <sha> --dry-run` renders a V29
212+
command plan naming all local proof suites, staging-testnet readback
213+
verifier, Terminal browser proof, generated `.bitcode/v29-*` reports,
214+
`BITCODE_SPEC_V29_PROVEN.md`, and promoted-family checks.
215+
- `.github/workflows/v29-canon-promotion.yml` runs only for `version/v29`
216+
pull requests into `main`, validates the source branch, runs promotion-grade
217+
proof, and commits the generated V29 promotion artifacts back to `version/v29`.
218+
- `prepare-bitcode-spec-family-promotion.mjs` rewrites V29 hand-authored status
219+
truth for promoted mode.
220+
- `prepare-bitcode-runtime-canon-promotion.mjs` rewrites both standalone
221+
demonstration posture and commercial `packages/protocol` posture for V29
222+
active / V30 draft.
223+
- `BITCODE_V29_QA.md`, README, V29 SPEC, DELTA, NOTES, PARITY, package scripts,
224+
and workflows describe local/staging readiness without committing secrets or
225+
staging credentials.

BITCODE_SPEC_V29_NOTES.md

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,42 @@ For a simplified reading of V29:
8181
10. **Gate 10: Local And Staging Promotion Readiness**
8282
- Run non-mocked local validation, staging-testnet readback, generated proof artifacts, promotion dry-run, and `version/v29` promotion readiness.
8383

84+
## Gate 10 working notes
85+
86+
Gate 10 is the final V29 gate before the version branch can be requested into
87+
`main`.
88+
It is not a product redesign gate.
89+
It proves that every preceding Terminal-depth gate is promotable and that the
90+
automation can safely advance canon.
91+
92+
Accepted Gate 10 posture:
93+
94+
- V29 remains draft while Gate 10 is implemented; `BITCODE_SPEC.txt` stays
95+
`V28` until the V29 promotion workflow creates the canonical promotion commit.
96+
- Gate-quality CI runs the Gate 10 checker and remains greenable before and
97+
after promotion by branching on the active pointer.
98+
- Canon-quality CI similarly accepts V28/V29 draft posture before promotion and
99+
V29/V30 promoted posture after promotion.
100+
- `promote-bitcode-canon.mjs` supports V29 and names every required local proof
101+
suite, the staging-testnet readback verifier, Terminal browser proof, runtime
102+
posture preparation, generated proof creation, and promoted-family validation.
103+
- `.github/workflows/v29-canon-promotion.yml` owns the `version/v29` to `main`
104+
promotion proof and generated-artifact commit.
105+
- `packages/protocol/src/canon-posture.js`, `packages/protocol/data/state.json`,
106+
and the standalone demonstration posture are kept aligned so local/staging
107+
readback does not present stale active/draft truth.
108+
- The V29 QA ledger records staging-testnet readback expectations and required
109+
local proof commands without writing environment values into tracked files.
110+
111+
Gate 10 completion condition:
112+
113+
- `pnpm run check:v29-gate10` passes.
114+
- `npm run promote:canon -- --version V29 --commit HEAD --dry-run` prints a V29
115+
promotion plan.
116+
- The focused local suites named by the gate checker pass or are intentionally
117+
delegated to the promotion workflow with documented rationale.
118+
- The gate branch is committed, pushed, and pull-requested into `version/v29`.
119+
84120
## Gate 1 closure notes
85121

86122
Gate 1 is complete only when the V29 family exists, validates, and is wired to CI.

0 commit comments

Comments
 (0)