Merge pull request #56 from engineeredsoftware/v32/gate-2-proof-matrix-inventory

V32 Gate 2: Proof Matrix Inventory

Author: geraldarthurdavis

.bitcode/v32-proof-coverage-matrix.json

@@ -112,6 +112,7 @@ jobs:
             node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V31 --draft-target V32
             node scripts/check-v31-gate10-promotion-readiness.mjs --promotion-mode --skip-branch-check
             node scripts/check-v32-gate1-provation-roadmap-opening.mjs --skip-branch-check
+            node scripts/check-v32-gate2-proof-matrix-inventory.mjs --skip-branch-check
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1

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

@@ -8,7 +8,7 @@
 - Canonical proof-source commit: none until V32 promotion
 - Prior canonical anchor: `BITCODE_SPEC_V31.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V31_PROVEN.md`
-- Generated structured artifact inventory: planned draft `.bitcode/v32-spec-family-report.json`, `.bitcode/v32-canonical-input-report.json`, `.bitcode/v32-canon-posture-drift-report.json`, V32 proof/test coverage artifacts, V32 gate-quality and promotion workflow evidence, and `BITCODE_SPEC_V32_PROVEN.md` only after promotion
+- Generated structured artifact inventory: planned draft `.bitcode/v32-spec-family-report.json`, `.bitcode/v32-canonical-input-report.json`, `.bitcode/v32-canon-posture-drift-report.json`, generated Gate 2 `.bitcode/v32-proof-coverage-matrix.json`, later V32 proof/test coverage artifacts, V32 gate-quality and promotion workflow evidence, and `BITCODE_SPEC_V32_PROVEN.md` only after promotion
 - Source parity state: V32 source-side proof-family replay, deterministic artifact generation, scenario matrices, cross-surface regression coverage, browser/accessibility/visual evidence, testnet/mainnet-readiness rehearsal, and promotion-proof hardening are opened but not yet closed
 - State: draft target opened
 - Active canonical pointer during draft opening: `BITCODE_SPEC.txt` -> `V31`
@@ -229,6 +229,14 @@ Gate 2 proof matrix precision:
 - coverage gaps are represented as planned rows with blockers rather than silently omitted proof;
 - Terminal, Reading, Protocol/BTD, Auxillaries, MCP, ChatGPT App, API, ledger, database, object storage, promotion, and protocol-demonstration all appear in the matrix.
 
+Gate 2 closes the first V32 proof inventory with `.bitcode/v32-proof-coverage-matrix.json`.
+That artifact is generated by `pnpm run generate:v32-proof-coverage-matrix` and checked by `pnpm run check:v32-gate2`.
+Each row uses these required fields: owner package/interface, fixture, replay command, expected artifact, source-safety class, coverage status, required contexts, failure mode, and repair posture.
+The required surface ids are `terminal`, `reading`, `protocol-btd`, `auxillaries`, `mcp`, `chatgpt-app`, `api`, `ledger`, `database`, `object-storage`, `promotion`, and `protocol-demonstration`.
+The accepted source-safety class vocabulary is `source-safe-public`, `source-safe-internal`, `secret-presence-only`, `protected-source-locked`, `source-safe-generated-proof`, and `deferred-blocker`.
+The accepted coverage-status vocabulary is `inherited-covered`, `v32-expansion-required`, and `planned-gap`.
+Rows with `planned-gap` must name blockers so future gates inherit explicit missing proof rather than hidden confidence.
+
 Gate 3 deterministic replay precision:
 
 - generated JSON artifacts must sort keys or otherwise define deterministic ordering;
@@ -825,7 +833,7 @@ V32 continues operator-quality proof: Terminal workflow claims must be backed by
 | `.bitcode/v32-spec-family-report.json` | yes | yes | validates the hand-authored V32 family shape |
 | `.bitcode/v32-canonical-input-report.json` | yes | yes | records canonical input closure for active V31 plus V32 draft |
 | `.bitcode/v32-canon-posture-drift-report.json` | gate-dependent | yes | proves runtime/docs active/draft posture |
-| `.bitcode/v32-proof-coverage-matrix.json` | gate-dependent | yes | records source-safe V32 proof/test coverage inventory across promoted surfaces |
+| `.bitcode/v32-proof-coverage-matrix.json` | yes | yes | records source-safe V32 proof/test coverage inventory across promoted surfaces |
 | `BITCODE_SPEC_V32_PROVEN.md` | no | yes | generated proof appendix for promoted V32 |
 
 ### V32 specifying generated artifacts

BITCODE_SPEC_V32.md

@@ -8,7 +8,7 @@
 - Canonical proof-source commit: none until V32 promotion
 - Prior canonical anchor: `BITCODE_SPEC_V31.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V31_PROVEN.md`
-- Generated structured artifact inventory: planned draft `.bitcode/v32-spec-family-report.json`, `.bitcode/v32-canonical-input-report.json`, `.bitcode/v32-canon-posture-drift-report.json`, V32 proof/test coverage artifacts, V32 gate-quality and promotion workflow evidence, and `BITCODE_SPEC_V32_PROVEN.md` only after promotion
+- Generated structured artifact inventory: planned draft `.bitcode/v32-spec-family-report.json`, `.bitcode/v32-canonical-input-report.json`, `.bitcode/v32-canon-posture-drift-report.json`, generated Gate 2 `.bitcode/v32-proof-coverage-matrix.json`, later V32 proof/test coverage artifacts, V32 gate-quality and promotion workflow evidence, and `BITCODE_SPEC_V32_PROVEN.md` only after promotion
 - Source parity state: V32 source-side proof-family replay, deterministic artifacts, test matrices, cross-surface regression, browser/accessibility/visual proof, testnet/mainnet-readiness rehearsal, and promotion-proof hardening are opened but not yet closed
 - State: draft target delta opened
 - Active canonical pointer during draft opening: `BITCODE_SPEC.txt` -> `V31`
@@ -93,6 +93,11 @@ Closure acceptance:
 - each proof row names owner package/interface, fixtures, replay command, generated artifact, source-safety class, and failure mode;
 - missing proof coverage is represented as planned work, not hidden confidence.
 
+Gate 2 source closure is `.bitcode/v32-proof-coverage-matrix.json`, generated by `pnpm run generate:v32-proof-coverage-matrix` and checked by `pnpm run check:v32-gate2`.
+The matrix uses explicit surface ids `terminal`, `reading`, `protocol-btd`, `auxillaries`, `mcp`, `chatgpt-app`, `api`, `ledger`, `database`, `object-storage`, `promotion`, and `protocol-demonstration`.
+It also introduces the Gate 2 source-safety vocabulary: `source-safe-public`, `source-safe-internal`, `secret-presence-only`, `protected-source-locked`, `source-safe-generated-proof`, and `deferred-blocker`.
+The `planned-gap` coverage status is required for missing proof rows, and such rows must carry blockers and repair posture.
+
 ### Gate 3: Deterministic Replay Harness And Artifact Stability
 
 Gate 3 hardens replay and generated artifact determinism.

BITCODE_SPEC_V32_DELTA.md

@@ -8,7 +8,7 @@
 - Current active draft target: `V32`
 - Prior canonical anchor: `BITCODE_SPEC_V31.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V31_PROVEN.md`
-- Generated structured artifact inventory: planned `.bitcode/v32-spec-family-report.json`, `.bitcode/v32-canonical-input-report.json`, `.bitcode/v32-canon-posture-drift-report.json`, V32 proof/test coverage artifacts, and `BITCODE_SPEC_V32_PROVEN.md` only at promotion
+- Generated structured artifact inventory: planned `.bitcode/v32-spec-family-report.json`, `.bitcode/v32-canonical-input-report.json`, `.bitcode/v32-canon-posture-drift-report.json`, generated Gate 2 `.bitcode/v32-proof-coverage-matrix.json`, later V32 proof/test coverage artifacts, and `BITCODE_SPEC_V32_PROVEN.md` only at promotion
 - Source parity state: V32 proof/test parity begins with Gate 1 and closes only through gate-specific implementation, tests, documentation, and workflow evidence
 - Scope: deeper provation and testing over promoted Terminal, Reading, Protocol/BTD, Auxillaries, MCP, ChatGPT App, API, ledger/database/object-storage, and protocol-demonstration surfaces.
 
@@ -48,7 +48,10 @@ Open the V32 draft family over active V31:
 Inventory all promoted proof/test surfaces and define required V32 coverage:
 
 - Terminal, Reading, Protocol/BTD, Auxillaries, MCP, ChatGPT App, API, ledger, database, object storage, promotion, and protocol-demonstration;
+- explicit surface ids `terminal`, `reading`, `protocol-btd`, `auxillaries`, `mcp`, `chatgpt-app`, `api`, `ledger`, `database`, `object-storage`, `promotion`, and `protocol-demonstration`;
 - owner package/interface, fixture, replay command, artifact path, source-safety class, and failure mode per row;
+- source-safety class vocabulary `source-safe-public`, `source-safe-internal`, `secret-presence-only`, `protected-source-locked`, `source-safe-generated-proof`, and `deferred-blocker`;
+- generated artifact `.bitcode/v32-proof-coverage-matrix.json` checked by `pnpm run check:v32-gate2`;
 - explicit planned work for every coverage gap.
 
 ### Gate 3: Deterministic Replay Harness And Artifact Stability

BITCODE_SPEC_V32_NOTES.md

@@ -8,7 +8,7 @@
 - Canonical proof-source commit: none until V32 promotion
 - Prior canonical anchor: `BITCODE_SPEC_V31.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V31_PROVEN.md`
-- Generated structured artifact inventory: planned `.bitcode/v32-spec-family-report.json`, `.bitcode/v32-canonical-input-report.json`, `.bitcode/v32-canon-posture-drift-report.json`, V32 proof/test coverage artifacts, and `BITCODE_SPEC_V32_PROVEN.md` only after promotion
+- Generated structured artifact inventory: planned `.bitcode/v32-spec-family-report.json`, `.bitcode/v32-canonical-input-report.json`, `.bitcode/v32-canon-posture-drift-report.json`, generated Gate 2 `.bitcode/v32-proof-coverage-matrix.json`, later V32 proof/test coverage artifacts, and `BITCODE_SPEC_V32_PROVEN.md` only after promotion
 - Source parity state: V32 proof-family replay, deterministic artifact generation, scenario/failure-state coverage, cross-surface regression, browser/accessibility/visual proof, readiness rehearsal, and promotion-proof hardening are opened but not yet closed
 - State: draft target parity matrix opened
 - Active canonical pointer during draft opening: `BITCODE_SPEC.txt` -> `V31`
@@ -45,6 +45,10 @@ Gate 1 audit basis:
 - `.github/workflows/bitcode-gate-quality.yml`
 - `.github/workflows/bitcode-canon-quality.yml`
 - `package.json`
+- `.bitcode/v32-proof-coverage-matrix.json`
+- `scripts/v32-proof-coverage-matrix.mjs`
+- `scripts/generate-v32-proof-coverage-matrix.mjs`
+- `scripts/check-v32-gate2-proof-matrix-inventory.mjs`
 - `packages/protocol/README.md`
 - `protocol-demonstration/README.md`
 - `packages/protocol/src/canon-posture.js`
@@ -58,7 +62,7 @@ No `_legacy/` source is active source truth.
 | --- | --- | --- | --- | --- |
 | Draft family and branch posture | Gate 1 | `BITCODE_SPEC_V32.md`, DELTA, NOTES, PARITY, `BITCODE_SPEC.txt`, branch `v32/gate-1-provation-roadmap-opening` | drafted | V32 family validates in draft mode over active V31 and `check:v32-gate1` passes. |
 | Roadmap truth | Gate 1 | `SPECIFICATIONS_ROADMAP.md`, README, PR template, workflow posture | drafted | Roadmap states V31 active, V32 draft, and coherent V33-V37 responsibilities. |
-| Proof matrix inventory | Gate 2 | planned proof inventory artifact and checker | draft-required | Every promoted proof/test surface has owner, fixture, replay command, artifact, source-safety class, and failure mode. |
+| Proof matrix inventory | Gate 2 | `.bitcode/v32-proof-coverage-matrix.json`, `scripts/v32-proof-coverage-matrix.mjs`, generator, checker, `check:v32-gate2` | drafted | Every promoted proof/test surface has owner package/interface, fixture, replay command, artifact, source-safety class, coverage status, required contexts, failure mode, and repair posture. |
 | Deterministic replay and artifacts | Gate 3 | planned replay harness, volatility inventory, artifact checks | draft-required | Generated artifacts are stable, source-safe, and fail closed on drift. |
 | Reading pipeline proof coverage | Gate 4 | planned `ReadNeedComprehensionSynthesis` and `ReadFitsFindingSynthesis` tests | draft-required | Pipeline phases, PTRR agents, steps, ThricifiedGenerations, prompts, tools, telemetry, and outputs are covered. |
 | Ledger/BTD settlement failure states | Gate 5 | planned BTD/BTC/ledger/reconciliation tests | draft-required | Economic and ownership state has success, blocked, and repair proof. |
@@ -76,7 +80,9 @@ No `_legacy/` source is active source truth.
 | Gate branch pattern | V32 work happens on `version/v32` or `v32/gate-N-*` branches | drafted |
 | Spec-family shape | V32 SPEC, DELTA, NOTES, and PARITY satisfy the full spec-family checker | drafted |
 | Gate 1 script | `pnpm run check:v32-gate1` fails closed on stale posture, missing roadmap truth, or missing provation/testing scope | drafted |
-| Gate-quality workflow | Gate workflow validates V31 active / V32 draft posture and the opened V32 Gate 1 checker | drafted |
+| Gate 2 matrix artifact | `.bitcode/v32-proof-coverage-matrix.json` records required proof/test surfaces with source-safe rows | drafted |
+| Gate 2 scripts | `pnpm run generate:v32-proof-coverage-matrix` regenerates the artifact and `pnpm run check:v32-gate2` fails closed on drift, missing fields, hidden gaps, or secret-like payloads | drafted |
+| Gate-quality workflow | Gate workflow validates V31 active / V32 draft posture plus V32 Gate 1 and Gate 2 checkers | drafted |
 | Canon-quality workflow | Canon workflow validates V31 active / V32 draft posture and promoted V31 canon | drafted |
 
 ## Gate 1 Parity
@@ -97,9 +103,11 @@ No `_legacy/` source is active source truth.
 
 | Requirement | Source evidence | Current V32 judgment |
 | --- | --- | --- |
-| Promoted surfaces are inventoried | planned proof inventory artifact | draft-required |
-| Coverage gaps are explicit | planned parity rows and generated proof matrix | draft-required |
-| Source-safety classes are assigned | planned artifact contract | draft-required |
+| Promoted surfaces are inventoried | `.bitcode/v32-proof-coverage-matrix.json` rows for `terminal`, `reading`, `protocol-btd`, `auxillaries`, `mcp`, `chatgpt-app`, `api`, `ledger`, `database`, `object-storage`, `promotion`, and `protocol-demonstration` | drafted |
+| Coverage gaps are explicit | matrix `coverageStatus` vocabulary includes `planned-gap`, with blockers on planned-gap rows | drafted |
+| Source-safety classes are assigned | matrix source-safety class vocabulary includes `source-safe-public`, `source-safe-internal`, `secret-presence-only`, `protected-source-locked`, `source-safe-generated-proof`, and `deferred-blocker` | drafted |
+| Matrix is deterministic | `scripts/generate-v32-proof-coverage-matrix.mjs` and `stableStringify` in `scripts/v32-proof-coverage-matrix.mjs` | drafted |
+| Gate check is wired | `scripts/check-v32-gate2-proof-matrix-inventory.mjs`, `check:v32-gate2`, and `bitcode-gate-quality.yml` | drafted |
 
 ## Gate 3 Parity
 
@@ -174,6 +182,15 @@ No `_legacy/` source is active source truth.
 - Gate 1 may update V32-V37 roadmap scope to align with promoted V31 and current enterprise-readiness goals.
 - V32 does not redefine V31 Reading, Finding Fits, AssetPack preview, settlement, delivery, BTC fee, or BTD tokenomics law.
 
+## Gate 2 Accepted Boundaries
+
+- Gate 2 inventories proof/test coverage and required contexts; it does not implement Gate 3 deterministic replay hardening, Gate 4 Reading pipeline expansion, Gate 5 economic failure-state proof, Gate 6 shared interface regression suites, Gate 7 browser proof expansion, Gate 8 readiness rehearsal, Gate 9 generated-proof hardening, or Gate 10 promotion.
+- Gate 2 generated artifacts must be source-safe and may not contain protected AssetPack source, provider tokens, wallet secrets, service keys, database passwords, OpenAI keys, Vercel tokens, Supabase service-role material, or private prompts.
+- Gate 2 may represent missing coverage as `planned-gap` only when blockers and repair posture are explicit.
+- Gate 2 does not promote `BITCODE_SPEC.txt` to V32 and does not create `BITCODE_SPEC_V32_PROVEN.md`.
+
 ## completion condition
 
 Gate 1 is complete when the V32 draft family validates, `check:v32-gate1` passes, workflow posture is V32-aware, README and roadmap reflect V32 initiation, V33-V37 scopes are current enough to guide future gates, diff hygiene passes, and the gate branch is committed, pushed, and pull-requested for review into `version/v32`.
+
+Gate 2 is complete when `.bitcode/v32-proof-coverage-matrix.json` exists, is deterministic from `pnpm run generate:v32-proof-coverage-matrix`, enumerates all required promoted surfaces with owner package/interface, fixture, replay command, expected artifact, source-safety class, coverage status, required contexts, failure mode, and repair posture, preserves explicit `planned-gap` blockers, passes `pnpm run check:v32-gate2`, is wired into gate-quality CI, and the gate branch is committed, pushed, and pull-requested for review into `version/v32`.

BITCODE_SPEC_V32_PARITY_MATRIX.md

@@ -5,7 +5,7 @@
 - Current active canonical pointer: `BITCODE_SPEC.txt` -> `V31`
 - Current active canon: `BITCODE_SPEC_V31.md`
 - Current draft target: `BITCODE_SPEC_V32.md`
-- Current working gate: V32 Gate 1 Provation Roadmap Opening, which opens V32 as the proof/testing-deepening version over promoted V31 and wires the roadmap, spec family, workflows, and first checker for V31 active / V32 draft posture.
+- Current working gate: V32 Gate 2 Proof Matrix Inventory And Required Contexts, which turns the opened V32 provation plan into a generated, source-safe proof/test coverage matrix across Terminal, Reading, Protocol/BTD, Auxillaries, MCP, ChatGPT App, API, ledger, database, object storage, promotion, and protocol-demonstration surfaces.
 - Purpose: concise running index of Bitcode/ENGI specification history, current work, and planned work.
 
 This roadmap is not an active system specification.

SPECIFICATIONS_ROADMAP.md

@@ -75,6 +75,8 @@
     "check:v31-gate9": "node scripts/check-v31-gate9-auxillaries-telemetry-proof-recovery-runs.mjs",
     "check:v31-gate10": "node scripts/check-v31-gate10-promotion-readiness.mjs",
     "check:v32-gate1": "node scripts/check-v32-gate1-provation-roadmap-opening.mjs",
+    "generate:v32-proof-coverage-matrix": "node scripts/generate-v32-proof-coverage-matrix.mjs",
+    "check:v32-gate2": "node scripts/check-v32-gate2-proof-matrix-inventory.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",