Merge pull request #136 from engineeredsoftware/v39/gate-1-commercial-reading-roadmap-opening

V39 Gate 1: Commercial Reading Roadmap Opening

Author: geraldarthurdavis

.github/pull_request_template.md

@@ -1,7 +1,7 @@
 ## Title
 
-Use the version and gate prefix for gate PRs: `V38 Gate N: Concise Topical Title`.
-Use the version and promotion prefix for version promotion PRs: `V38 Canonical Promotion: Concise Topical Title`.
+Use the version and gate prefix for gate PRs: `V39 Gate N: Concise Topical Title`.
+Use the version and promotion prefix for version promotion PRs: `V39 Canonical Promotion: Concise Topical Title`.
 
 ## Closure
 

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

@@ -181,6 +181,10 @@ jobs:
             node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V38 --draft-target V39
             node scripts/check-bitcode-spec-family.mjs --version V38 --mode promoted --current-target V38
             node scripts/check-v38-gate11-promotion-readiness.mjs --promotion-mode --skip-branch-check --skip-package-tests
+            if [ -f BITCODE_SPEC_V39.md ]; then
+              node scripts/check-bitcode-spec-family.mjs --version V39 --mode draft --current-target V38
+              node scripts/check-v39-gate1-commercial-reading-roadmap-opening.mjs --skip-branch-check
+            fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1
@@ -296,7 +300,15 @@ jobs:
                 node scripts/check-bitcode-spec-family.mjs --version V38 --mode draft --current-target V37
               fi
               ;;
+            spec:\ V39*|spec:\ v39*)
+              POINTER="$(cat BITCODE_SPEC.txt)"
+              if [ "$POINTER" = "V39" ]; then
+                node scripts/check-bitcode-spec-family.mjs --version V39 --mode promoted --current-target V39
+              else
+                node scripts/check-bitcode-spec-family.mjs --version V39 --mode draft --current-target V38
+              fi
+              ;;
             *)
-              echo "Skipping strict spec-title conformance; title is not a V29/V30/V31/V32/V33/V34/V35/V36/V37/V38 spec change."
+              echo "Skipping strict spec-title conformance; title is not a V29/V30/V31/V32/V33/V34/V35/V36/V37/V38/V39 spec change."
               ;;
           esac

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

@@ -310,6 +310,10 @@ jobs:
             node scripts/check-bitcode-canonical-inputs.mjs --current-target V38
             node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V38 --draft-target V39
             node scripts/check-v38-gate11-promotion-readiness.mjs --promotion-mode --skip-branch-check --skip-package-tests
+            if [ -f BITCODE_SPEC_V39.md ]; then
+              node scripts/check-bitcode-spec-family.mjs --version V39 --mode draft --current-target V38
+              node scripts/check-v39-gate1-commercial-reading-roadmap-opening.mjs --skip-branch-check
+            fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1

BITCODE_SPEC_V39.md

@@ -0,0 +1,194 @@
+# Bitcode Spec V39 Delta
+
+## Status
+
+- Version: `V39`
+- V39 state: draft opened; this delta records the planned V38-to-V39 commercial Reading readiness closure set
+- Current canonical/latest target: `V38`
+- Draft proof-source commit: unbound until V39 promotion
+- Prior canonical anchor: `BITCODE_SPEC_V38.md`
+- Prior generated proof appendix: `BITCODE_SPEC_V38_PROVEN.md`
+- Generated structured artifact inventory: draft opening requires `.bitcode/v39-spec-family-report.json` and `.bitcode/v39-canonical-input-report.json`; later V39 gates must add package-backed source-safe artifacts for Depository indexing, Reading UX state, ReadNeed review/resynthesis, ReadFitsFinding runtime, AssetPack preview/quote, settlement/delivery rights, telemetry/repair, interface parity, rehearsal, and promotion readiness
+- Source parity state: V39 delta opens parity requirements; implementation parity remains pending until each V39 gate closes with source, artifacts, tests, workflow checks, and source-safe documentation
+- Spec companion: `BITCODE_SPEC_V39.md`
+- Notes companion: `BITCODE_SPEC_V39_NOTES.md`
+- Parity companion: `BITCODE_SPEC_V39_PARITY_MATRIX.md`
+- Generated proof appendix: `BITCODE_SPEC_V39_PROVEN.md` only after V39 promotion
+- Scope: V39 draft delta for commercial Reading readiness over promoted V38 inference correctness canon
+
+## Why V39 exists
+
+V38 promoted inference correctness.
+It made pipeline execution, PTRR agents, FailsafeGenerationSequence, ThricifiedGeneration, prompt benchmarking, source-safe inference telemetry, and Reading fit-search primitives exact enough to use as production-grade infrastructure.
+
+V39 exists because Bitcode now needs the full enterprise Reading path to become commercially reliable.
+V39 closes product runtime gaps across Depository supply indexing, Read Request capture, reviewable ReadNeed synthesis and resynthesis, Finding Fits across many candidate deposits, source-safe AssetPack preview, deterministic BTC quote, BTD rights transfer, post-settlement delivery, ledger/database/storage synchronization, repair, and interface parity.
+
+## Accepted V39 decisions
+
+- V38 remains active canon during V39 drafting.
+- V39 gate branches are opened from `version/v39` and merged back only when their gate acceptance criteria are closed.
+- V39 owns commercial Reading readiness across Terminal, Conversation, MCP/API, ChatGPT App, package contracts, Depository, ledger, database, storage, wallet, and delivery surfaces.
+- V38 inference law remains binding: PTRR agent steps use `FailsafeGenerationSequence` above `ThricifiedGeneration`, tools are step-owned, prompt registry composition is preserved, and telemetry disclosure tiers govern all inference evidence.
+- `ReadNeedComprehensionSynthesis` must become a persisted review/resynthesis loop whose accepted Need gates Finding Fits.
+- `ReadFitsFindingSynthesis` must discover many candidate deposits above threshold before AssetPack synthesis and settlement handoff.
+- Fit-finding must preserve the active OpenAI embedding policy (`text-embedding-3-small`, 1536 dimensions, cosine `match_deliverable_vectors`) unless a replacement is explicitly specified, tested, and migrated.
+- Source-bearing AssetPack delivery is forbidden before settlement unlock and BTD rights transfer.
+
+## Explicitly deferred
+
+- Production-mainnet value-bearing launch remains blocked.
+- Bridge chain-of-record implementation remains deferred.
+- V39 does not reopen BTD supply law, Exchange law, or Bitcoin settlement law except for inference and fit-finding traceability needed by AssetPack preview and post-settlement delivery.
+- New LlamaIndex, Pinecone, or provider-specific search channels may be specified only after boundaries, credentials, storage, telemetry, and tests are explicit.
+
+## Pre-Implementation Sequence
+
+1. Open `version/v39` from promoted `main`.
+2. Open `v39/gate-1-commercial-reading-roadmap-opening` from `version/v39`.
+3. Create the V39 SPEC, DELTA, NOTES, and PARITY family while preserving `BITCODE_SPEC.txt -> V38`.
+4. Refresh `SPECIFICATIONS_ROADMAP.md` so V38 is active canon, V39 is draft target, and post-V39 work remains coherent.
+5. Retarget gate-quality and canon-quality workflow posture checks to V38 active / V39 draft.
+6. Add `check:v39-gate1` and a V39 Gate 1 checker.
+7. Define V39 gates, acceptance criteria, carryforward parity rows, and promotion boundaries.
+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/v39`.
+
+## Commit-Body Direction
+
+V39 gate commit bodies should describe the closed gate, product surface, pipeline/runtime changes, generated proof artifacts, tests, telemetry/disclosure boundaries, and accepted deferrals.
+The eventual V39 promotion commit body must name all closed V39 gates, generated commercial Reading proof artifacts, Depository indexing evidence, ReadNeed and ReadFitsFinding runtime evidence, AssetPack preview/quote evidence, settlement/delivery evidence, telemetry/repair evidence, local/staging rehearsal proof, promotion workflow evidence, and the `BITCODE_SPEC.txt` pointer change from `V38` to `V39`.
+
+## Gate Delta
+
+### Gate 1: V39 Commercial Reading Roadmap And Spec Opening
+
+Gate 1 opens V39 correctly:
+
+- V39 SPEC, DELTA, NOTES, and PARITY files exist.
+- `BITCODE_SPEC.txt` remains `V38`.
+- README, roadmap, PR template, package docs, demonstration docs, and workflows describe V38 active / V39 draft posture.
+- `check:v39-gate1` validates branch naming, spec family, notes, parity, roadmap truth, workflow posture, inference vocabulary, depository-search vocabulary, and promotion boundaries.
+- The V39 gate list is explicit before inference implementation begins.
+
+### Gate 2: Depository Supply Indexing And Searchable Deposit Lifecycle
+
+Closure acceptance:
+
+- deposited source materials are measurable, indexable, vector-searchable, metadata-searchable, rights-aware, and repairable;
+- deposit lifecycle receipts bind repository/deposit anchors, measurement roots, embedding roots, ownership boundaries, and source-safe telemetry;
+- `pnpm run check:v39-gate2` validates package-backed source, generated artifact freshness, tests, and workflow wiring without exposing protected source or credentials.
+
+Closure implementation:
+
+- Pending Gate 2 work must define its package-owned canonical source and deterministic artifact path before implementation begins.
+- The artifact must use a source-safe disclosure posture and include repair/replay acceptance criteria.
+
+### Gate 3: Enterprise Reading UX State Machine
+
+Closure acceptance:
+
+- Terminal implements the five-step enterprise Reading flow: request read, review synthesized Need, request Finding Fits, review source-safe AssetPack preview, buy and settle;
+- each step has clear low-detail default UI and expandable source-safe detail;
+- `pnpm run check:v39-gate3` validates state contracts, component tests, browser proof, and disclosure boundaries.
+
+Closure implementation:
+
+- Pending Gate 3 work must define route contracts, UI tests, and generated UX-state proof artifact.
+
+### Gate 4: ReadNeed Review, Resynthesis, And Admission Runtime
+
+Closure acceptance:
+
+- `ReadNeedComprehensionSynthesis` persists Read Requests, synthesized Needs, feedback, resynthesis attempts, Need measurements, accepted-Need admission, rejected-Need posture, and source-safe telemetry receipts;
+- Finding Fits remains blocked until a reviewed Need is accepted;
+- `pnpm run check:v39-gate4` validates pipeline contracts, storage, telemetry, UI, tests, artifact freshness, and workflow wiring.
+
+Closure implementation:
+
+- Pending Gate 4 work must define package-backed source, deterministic artifact, pipeline tests, route tests, and accepted-Need admission tests.
+
+### Gate 5: ReadFitsFinding Runtime, Ranking, And Replay
+
+Closure acceptance:
+
+- Finding Fits uses inference-derived queries and depository search tools across lexical, symbolic, path, metadata, measurement, embedding/vector, and provider-specific channels;
+- candidate deposits above threshold are ranked, verified, replayable, and traceable into selected-fit provenance;
+- `pnpm run check:v39-gate5` validates search tools, embeddings, ranking, thresholding, replay receipts, tests, and generated evidence.
+
+Closure implementation:
+
+- Pending Gate 5 work must define runtime search artifacts, active embedding policy checks, and many-candidate replay evidence.
+
+### Gate 6: AssetPack Preview, Quote, And Disclosure Boundary
+
+Closure acceptance:
+
+- source-safe AssetPack preview exposes measurements, fit reasons, selected-fit provenance, proof roots, quality posture, deterministic BTC quote, and delivery posture;
+- source-bearing AssetPack content remains blocked until settlement unlock;
+- `pnpm run check:v39-gate6` validates quote determinism, preview disclosure, leak scanning, tests, and generated evidence.
+
+Closure implementation:
+
+- Pending Gate 6 work must define preview/quote artifacts, disclosure tests, and deterministic quote source.
+
+### Gate 7: Settlement, BTD Rights Transfer, And Delivery
+
+Closure acceptance:
+
+- BTC settlement observation, finality, BTD rights transfer, source-to-shares compensation, post-settlement delivery, and repair paths are auditable;
+- ledger, database, and object-storage projections remain synchronized or repairable;
+- `pnpm run check:v39-gate7` validates settlement, rights, delivery, repair, and synchronization evidence.
+
+Closure implementation:
+
+- Pending Gate 7 work must define settlement/delivery artifacts, receipt tests, and PR delivery repair evidence.
+
+### Gate 8: Operational Telemetry, Repair, And Operator Readback
+
+Closure acceptance:
+
+- Reading telemetry streams source-safe phase, agent, step, Failsafe, ThricifiedGeneration, tool, storage, ledger, wallet, delivery, and UI events;
+- operator readback binds proof roots, runbook hooks, repair commands, and failure posture;
+- `pnpm run check:v39-gate8` validates telemetry contracts, UI readback, repair proof, and source-safe disclosure.
+
+Closure implementation:
+
+- Pending Gate 8 work must define telemetry/repair artifacts and route or component tests.
+
+### Gate 9: Interface And Conversation Product Parity
+
+Closure acceptance:
+
+- Conversation, MCP/API, ChatGPT App, and package-facing interfaces obey the same Reading authority as Terminal;
+- no interface bypasses accepted-Need gating, source-safe preview, settlement unlock, BTD rights, or delivery boundaries;
+- `pnpm run check:v39-gate9` validates interface contract tests, Conversation handoff tests, and no-bypass posture.
+
+Closure implementation:
+
+- Pending Gate 9 work must define interface parity artifacts and consumer contract tests.
+
+### Gate 10: Local And Staging Commercial Reading Rehearsal
+
+Closure acceptance:
+
+- local and staging-testnet rehearsals run the five-step Reading flow with real non-mocked inference where credentials are available;
+- rehearsals cover Depository search, source-safe preview, telemetry streaming/readback, ledger/database/storage synchronization, PR delivery posture, and blocked production-mainnet value-bearing admission;
+- `pnpm run check:v39-gate10` validates rehearsal evidence and workflow wiring.
+
+Closure implementation:
+
+- Pending Gate 10 work must define local/staging artifacts, credential gates, and source-safe rehearsal evidence.
+
+### Gate 11: V39 Promotion Readiness
+
+Closure acceptance:
+
+- all V39 gates are closed;
+- V39 generated proof appendix support exists;
+- promotion workflow validates V39 and commits only the canonical pointer and generated promotion artifacts;
+- `pnpm run check:v39-gate11` validates promotion readiness, source-safety, generated artifacts, and V39 draft posture preparation.
+
+Closure implementation:
+
+- Pending Gate 11 work must define the package-backed commercial Reading promotion readiness report, V39 promotion workflow, promotion command support, generated proof appendix support, active V39 / draft V40 post-promotion posture, and blocked value-bearing mainnet evidence.