Merge pull request #18 from engineeredsoftware/v28/gate-13-product-closure-promotion-readiness

Close V28 gate 13 promotion readiness

Author: geraldarthurdavis

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

@@ -49,6 +49,7 @@ jobs:
           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
 
       - name: Validate source casing and imports
@@ -78,8 +79,13 @@ jobs:
             tests/pipelineExecutionLogHeader.test.tsx \
             --runInBand
 
+      - name: Test pipeline readback verifier
+        run: pnpm test:qa:v28:pipeline-readback
+
       - name: Test protocol demonstration
-        run: npm --prefix protocol-demonstration run test:v28-mvp-qa
+        run: |
+          npm --prefix protocol-demonstration test
+          npm --prefix protocol-demonstration run test:v28-mvp-qa
 
       - name: Check diff hygiene
         run: git diff --check

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

@@ -61,15 +61,29 @@ jobs:
             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 --promotion-mode --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
           elif [ "$POINTER" = "V28" ]; then
             node scripts/check-bitcode-spec-family.mjs --version V28 --mode promoted --current-target V28
             node scripts/check-bitcode-canonical-inputs.mjs --current-target V28
             node scripts/check-v28-metadevelopment-readiness.mjs --promotion-mode --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
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1
           fi
+          pnpm test:qa:v28:pipeline-readback
+          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

BITCODE_SPEC_V28.md

@@ -911,7 +911,36 @@ Gate 12 acceptance requires:
 Gate 13 owns final commercial-product closure: website application UX, package
 abstractions, tests, local live validation, staging-testnet readback evidence,
 public/internal documentation, generated proof coverage, and the final
-`version/v28` promotion pull request.
+`version/v28` promotion pull request. This version/v28 promotion pull request
+is the only path that may advance `BITCODE_SPEC.txt` to V28.
+
+Gate 13 acceptance requires:
+
+- the full `protocol-demonstration` proof suite passes, not only the V28 MVP
+  witness subset. The older proof-member, theorem-evidence, public projection,
+  and V26-proven expectations must either match the active V27/V28 posture or
+  explicitly record superseded promotion-readiness as false;
+- the staging-testnet readback verifier is green against project
+  `tkpyosihuouusyaxtbau` / `tkpyosihuouusyaxtbau.supabase.co`, proving recent
+  Depositing -> Reading -> settlement -> PR-delivery evidence can be reread
+  through the Supabase Data API from pipeline, stream, phase, agent-step,
+  generation, tool, ledger, journal, BTC fee, BTD range, ownership,
+  read-license, crypto telemetry, and delivery rows. DB readback is a stricter
+  optional lane when local network access can reach the Supabase Postgres host
+  or pooler, and it must fail fast with bounded connection/query timeouts;
+- local promotion readiness includes `check:v28-gate9` through
+  `check:v28-gate13`, BTD primitive typecheck/tests, pipeline package
+  typecheck/tests, UAPI Terminal/route focused tests, readback verifier tests,
+  full demonstration proof-suite tests, V28 MVP demonstration tests, source
+  casing/import checks, and promotion dry-run;
+- the V28 promotion workflow runs only for a `version/v28` pull request into
+  `main`, validates every Gate 9-13 closure check plus promotion-grade tests,
+  and writes `BITCODE_SPEC.txt` plus generated V28 proof artifacts only after
+  those validations pass;
+- no protected source visibility, BTC fee, read-license, or BTD ownership
+  claims are promoted from stale manual notes alone. Promotion evidence must be
+  source-controlled, testable, and replayable or explicitly named as external
+  staging-testnet readback evidence in QA.
 
 ## Draft Boundary
 

BITCODE_SPEC_V28_PARITY_MATRIX.md

@@ -206,6 +206,17 @@ read back together. Terminal must show the unlock state, read-license id, BTC
 fee receipt id, ledger status, and PR target without treating unpaid preview
 metadata as source access.
 
+Gate 13 closure closes the two final carryforward rows by making promotion
+readiness executable: the full `protocol-demonstration` suite is green under
+the active V27/V28 posture, the staging-testnet readback verifier is required
+for complete Depositing -> Reading -> settlement -> delivery evidence through
+the Supabase Data API, bounded DB readback remains available for stricter local
+network lanes, and the promotion workflow validates every Gate 9-13 check
+before it can promote `version/v28` into `main`. Older demonstration matrices
+now track the current proof catalog counts and the V26-proven generator no
+longer overstates superseded promotion readiness while V27 remains the active
+canon pointer.
+
 ## V28 implementation matrix
 
 | Area | Current source evidence | Judgment | Gate owner |

BITCODE_V28_QA.md

@@ -2180,3 +2180,63 @@ Expected evidence:
 - Missing read-license, BTC fee, ownership, journal, ledger anchor, telemetry,
   or delivery readback leaves protected source withheld and records the blocking
   readback key.
+
+### Gate 13 Commercial Product Closure And Promotion Readiness QA
+
+Gate 13 closure proves that V28 is ready for a `version/v28` promotion pull
+request by requiring the final product, demonstration, readback, and promotion
+checks to be executable instead of manually inferred.
+
+Required local checks:
+
+```bash
+pnpm run check:v28-gate13
+npm --prefix protocol-demonstration test
+npm --prefix protocol-demonstration run test:v28-mvp-qa
+pnpm test:qa:v28:pipeline-readback
+pnpm qa:v28:pipeline-readback -- --env-file .env.local --expected-host tkpyosihuouusyaxtbau.supabase.co --readback-source rest --lookback-hours 96
+# Optional stricter lane when local network can reach the Supabase Postgres host or pooler:
+pnpm qa:v28:pipeline-readback -- --env-file .env.local --expected-host tkpyosihuouusyaxtbau.supabase.co --readback-source db --lookback-hours 96
+node scripts/promote-bitcode-canon.mjs --version V28 --commit HEAD --dry-run
+```
+
+Expected evidence:
+
+- The full demonstration proof suite passes with the current proof catalog:
+  V18 proof-member semantic matrix has 736 cells, V18 theorem-evidence matrix
+  has 928 cells, and V26-proven preview records `promotionReady=false` when the
+  active canon pointer is not V26.
+- The V28 MVP demonstration witness remains self-contained and passes its
+  bounded Need/Finding Fits/AssetPack preview tests without importing product
+  packages or UAPI runtime code.
+- The pipeline readback verifier tests prove host mismatch, stale/missing
+  credentials, missing ledger rows, missing tool rows, and failed deliverable
+  runs fail closed; the staging-testnet Data API readback command must report a
+  recent ready run for project `tkpyosihuouusyaxtbau`. DB readback is a stricter
+  optional lane when local network access can reach the Supabase Postgres host
+  or pooler, and it must fail fast with bounded connection/query timeouts rather
+  than hanging gate validation.
+- Gate Quality and V28 Canon Promotion workflows include `check:v28-gate13`,
+  BTD primitive checks, full demonstration tests, readback verifier tests, and
+  the promotion dry-run. Promotion must only write the V28 pointer and generated
+  proof artifacts from a `version/v28` pull request into `main`.
+
+Observed Gate 13 local evidence on 2026-05-20:
+
+- `--readback-source rest --lookback-hours 96` against
+  `tkpyosihuouusyaxtbau.supabase.co` returned
+  `ready_for_v28_result_review`: `pipeline_runs=11`, `stream_logs=11`,
+  `deliverable_pipeline_runs=11`, `deliverable_pipeline_events=8513`,
+  `deliverable_pipeline_phase_delegations=123`,
+  `deliverable_pipeline_agent_steps=418`,
+  `deliverable_pipeline_generations=122`,
+  `deliverable_pipeline_tool_executions=14`,
+  `btd_asset_pack_ranges=6`, `btc_fee_transactions=6`,
+  `btd_terminal_journal_entries=24`,
+  `btd_asset_pack_ledger_anchors=6`, `btd_ownership_events=6`,
+  `btd_read_licenses=6`, and `btd_crypto_telemetry_events=6`.
+  `phase_executions` remains substituted by deliverable phase delegation rows.
+- `--readback-source db --lookback-hours 96` reached the expected DB host but
+  timed out locally at connection/query time. The verifier now fails fast with
+  bounded DB client settings, so this is recorded as local Postgres network
+  reachability rather than a hanging product gate.

package.json

@@ -43,6 +43,7 @@
     "check:v28-gate10": "node scripts/check-v28-gate10-read-need-comprehension.mjs",
     "check:v28-gate11": "node scripts/check-v28-gate11-read-fits-finding-preview.mjs",
     "check:v28-gate12": "node scripts/check-v28-gate12-settlement-rights-delivery.mjs",
+    "check:v28-gate13": "node scripts/check-v28-gate13-product-closure-promotion-readiness.mjs",
     "check:spec-quality": "node scripts/run-bitcode-spec-quality.mjs --mode basic",
     "check:spec-quality:title": "node scripts/run-bitcode-spec-quality.mjs --mode strict-from-title",
     "check:spec-quality:v24": "node scripts/run-bitcode-spec-quality.mjs --mode strict-version --version V24",

protocol-demonstration/src/canonical/enums.js

@@ -30,7 +30,7 @@ export const NormalizationPressure = Object.freeze({
 export const RealizationStage = Object.freeze({
   DEPOSITING: 'depositing',
   READING: 'reading',
-  DEPOSIT_TO_NEED_FIT: 'deposit-to-read-fit',
+  DEPOSIT_TO_READ_FIT: 'deposit-to-read-fit',
   ASSET_PACK: 'asset-pack',
   BRANCH: 'branch-materialization',
   PROOF: 'proof-closure',

protocol-demonstration/src/canonical/run-artifacts.js

@@ -1458,16 +1458,16 @@ function buildTestCoverageReport({ state, scenarioFixtureManifest, activeScenari
         runner: 'node --test',
         requiredForV18Canon: true,
         validates: [
-          'V18 proof-member semantic matrix: 45 members x 8 scenarios x 2 branch modes = 720 cells',
-          'V18 theorem evidence matrix: 57 theorems x 8 scenarios x 2 branch modes = 912 cells',
+          'V18 proof-member semantic matrix: current proof catalog x 8 scenarios x 2 branch modes = 736 cells',
+          'V18 theorem evidence matrix: current proof catalog x 8 scenarios x 2 branch modes = 928 cells',
           'V18 state-machine matrix: repeated-run, reset-after-run, mixed-deposit, and no-survivor workflow cells = 200 cells',
           'generated matrix artifacts expose predicate ids, evidence paths, evidence digest refs, pass/fail, and failure reasons'
         ],
         matrixCellCounts: {
-          proofMemberSemantic: 720,
-          theoremEvidence: 912,
+          proofMemberSemantic: 736,
+          theoremEvidence: 928,
           stateMachine: 200,
-          total: 1832
+          total: 1864
         }
       },
       e2e: {

protocol-demonstration/test/proof-member-matrix.test.js

@@ -24,8 +24,8 @@ test('V18 proof-member semantic matrix executes all canonical member cells', ()
 
   assert.equal(matrix.matrixId, V18_PROOF_MEMBER_MATRIX_ID);
   assert.equal(matrix.sourceRunCount, 16);
-  assert.equal(matrix.cellCount, 720);
-  assert.equal(matrix.passedCellCount, 720);
+  assert.equal(matrix.cellCount, 736);
+  assert.equal(matrix.passedCellCount, 736);
   assert.deepEqual(matrix.failedCells, []);
   assert.deepEqual(matrix.acceptedExclusions, []);
   assertV18MatrixClosed(matrix);
@@ -43,7 +43,7 @@ test('V18 proof-member semantic matrix executes all canonical member cells', ()
     familyCounts.set(cell.proofFamily, (familyCounts.get(cell.proofFamily) || 0) + 1);
   }
 
-  assert.equal(familyCounts.get('settlement-source-to-shares'), 112);
+  assert.equal(familyCounts.get('settlement-source-to-shares'), 128);
   assert.equal(familyCounts.get('static-code-analysis'), 64);
   assert.equal(familyCounts.get('prompt-completeness'), 80);
 });

protocol-demonstration/test/proven-generator.test.js

@@ -253,7 +253,7 @@ test('V25 proven generator renders a Bitcode-branded appendix with BTD rename cl
   assert.ok(generated.markdown.includes('BTD'));
 });
 
-test('V26 proven generator renders the active Bitcode appendix with all eight gates procedurally closed', () => {
+test('V26 proven generator renders active Bitcode posture without overstating superseded promotion readiness', () => {
   const generated = generateCanonicalProvenMarkdown({
     version: 'V26',
     canonicalCommit: 'draft-v26',
@@ -269,6 +269,23 @@ test('V26 proven generator renders the active Bitcode appendix with all eight ga
   ]);
   assert.equal(generated.data.v26.activeCanonicalTarget, ACTIVE_CANON_VERSION);
   assert.equal(generated.data.v26.draftPreview, ACTIVE_CANON_VERSION !== 'V26');
+
+  if (ACTIVE_CANON_VERSION !== 'V26') {
+    assert.equal(generated.data.v26.checkpointReady, false);
+    assert.equal(generated.data.v26.throughFourthGateReady, false);
+    assert.equal(generated.data.v26.fourthGatePromotedClosed, false);
+    assert.equal(generated.data.v26.throughFourthGatePromotionReady, false);
+    assert.equal(generated.data.v26.promotionReady, false);
+    assert.equal(generated.data.v26.specFamilyReport.passed, false);
+    assert.equal(generated.data.v26.specFamilyReport.mode, 'draft');
+    assert.equal(generated.data.v26.canonicalInputReport.passed, true);
+    assert.equal(generated.data.aggregate.fullyProven, false);
+    assert.ok(generated.markdown.includes('# Bitcode Spec V26 Proven'));
+    assert.ok(generated.markdown.includes('- draftPreview: `true`'));
+    assert.ok(generated.markdown.includes('- promotionReady: `false`'));
+    return;
+  }
+
   assert.equal(generated.data.v26.checkpointReady, true);
   assert.equal(generated.data.v26.throughFourthGateReady, true);
   assert.equal(generated.data.v26.fourthGatePromotedClosed, true);