Merge pull request #170 from engineeredsoftware/v42/gate-1-mvp-experience-roadmap-opening

V42 Gate 1: MVP Experience Roadmap Opening

Author: geraldarthurdavis

.github/pull_request_template.md

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

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

@@ -292,6 +292,10 @@ jobs:
             node scripts/check-bitcode-canonical-inputs.mjs --current-target V41
             node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V41 --draft-target V42
             node scripts/check-v41-gate9-promotion-readiness.mjs --promotion-mode --skip-branch-check --skip-package-tests
+            if [ -f BITCODE_SPEC_V42.md ]; then
+              node scripts/check-bitcode-spec-family.mjs --version V42 --mode draft --current-target V41
+              node scripts/check-v42-gate1-mvp-experience-roadmap-opening.mjs --skip-branch-check
+            fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1
@@ -431,7 +435,15 @@ jobs:
                 node scripts/check-bitcode-spec-family.mjs --version V41 --mode draft --current-target V40
               fi
               ;;
+            spec:\ V42*|spec:\ v42*)
+              POINTER="$(cat BITCODE_SPEC.txt)"
+              if [ "$POINTER" = "V42" ]; then
+                node scripts/check-bitcode-spec-family.mjs --version V42 --mode promoted --current-target V42
+              else
+                node scripts/check-bitcode-spec-family.mjs --version V42 --mode draft --current-target V41
+              fi
+              ;;
             *)
-              echo "Skipping strict spec-title conformance; title is not a V29/V30/V31/V32/V33/V34/V35/V36/V37/V38/V39/V40/V41 spec change."
+              echo "Skipping strict spec-title conformance; title is not a V29/V30/V31/V32/V33/V34/V35/V36/V37/V38/V39/V40/V41/V42 spec change."
               ;;
           esac

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

@@ -421,6 +421,10 @@ jobs:
             node scripts/check-bitcode-canonical-inputs.mjs --current-target V41
             node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V41 --draft-target V42
             node scripts/check-v41-gate9-promotion-readiness.mjs --promotion-mode --skip-branch-check --skip-package-tests
+            if [ -f BITCODE_SPEC_V42.md ]; then
+              node scripts/check-bitcode-spec-family.mjs --version V42 --mode draft --current-target V41
+              node scripts/check-v42-gate1-mvp-experience-roadmap-opening.mjs --skip-branch-check
+            fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
             exit 1

BITCODE_SPEC_V42.md

@@ -0,0 +1,85 @@
+# Bitcode Spec V42 Delta
+
+## Status
+
+- Version: `V42`
+- V42 state: draft opened; this delta records the planned V41-to-V42 reliable MVP experience work
+- Current canonical/latest target: `V41`
+- Prior canonical anchor: `BITCODE_SPEC_V41.md`
+- Prior generated proof appendix: `BITCODE_SPEC_V41_PROVEN.md`
+- Generated structured artifact inventory: draft `.bitcode/v42-spec-family-report.json`, `.bitcode/v42-canonical-input-report.json`, `.bitcode/v42-canon-posture-drift-report.json`, and later V42 gate artifacts for Depositing, Reading, Finding Fits, settlement/delivery, AI-reading demonstration, local/staging rehearsal, and promotion readiness
+- Source parity state: V42 source parity is opened by Gate 1 and remains incomplete until later gates implement the product paths
+- Scope: V42 draft delta for reliable MVP product experience over promoted V41 prompt-program excellence canon
+
+## Why V42 exists
+
+V42 turns the promoted V39 Reading product, V40 testing depth, and V41 prompt-program excellence into a reliable MVP enterprise experience.
+The version focuses on shortest-path Depositing, shortest-path Reading, settlement-gated AssetPack delivery, depositor compensation visibility, and an AI-reading dominant demonstration that proves AssetPacks improve an AI system beyond public-data-only baseline performance.
+
+## Accepted V42 decisions
+
+- V42 starts from active `V41` canon and keeps `BITCODE_SPEC.txt` at `V41` until promotion.
+- V42 product work stays unversioned in source paths.
+- Depositing must minimize the path to Depository admission proof and future compensation visibility.
+- Reading must use five product steps: request read, review synthesized Need, request Finding Fits, review source-safe AssetPack preview, and buy/settle/deliver AssetPack.
+- `ReadNeedComprehensionSynthesis` and `ReadFitsFindingSynthesis` remain the formal Reading pipeline names.
+- Source-bearing AssetPack content remains withheld until BTC settlement, BTD rights transfer, and storage/delivery reconciliation.
+- The demonstration remains self-contained in `protocol-demonstration/` and must prove AI-reading value without importing commercial code.
+
+## V42 gate plan
+
+### Gate 1: MVP Experience Roadmap And Spec Opening
+
+Open the V42 full specification family, roadmap, package script, workflow posture, documentation posture, branch convention, and checker.
+
+### Gate 2: Depositing Shortest Path And Compensation Visibility
+
+Implement and prove the shortest path from source material to Depository admission proof and later compensation readback.
+
+### Gate 3: Reading Shortest Path State Machine
+
+Implement and prove the five-step Reading product state machine with low-detail defaults and expandable proof/telemetry detail.
+
+### Gate 4: ReadNeed Review And Resynthesis Product Closure
+
+Implement and prove reviewed synthesized Need flow, feedback/resynthesis, accepted-Need admission, storage projection, telemetry, and UI readback.
+
+### Gate 5: ReadFitsFinding AssetPack Preview And Quote Closure
+
+Implement and prove many-candidate Depository search, selected-fit provenance, source-safe AssetPack preview, deterministic BTD/BTC quote, and no pre-settlement source leakage.
+
+### Gate 6: Settlement Rights Transfer And Repository Delivery Closure
+
+Implement and prove purchase, settlement observation, BTD rights transfer, source unlock, repository pull request delivery, compensation accounting, and repair posture.
+
+### Gate 7: AI-Reading Dominant Demonstration MVP
+
+Implement and prove the standalone demonstration where deposited technical intelligence improves an AI system beyond a public-data-only baseline.
+
+### Gate 8: Local And Staging-Testnet Full MVP Rehearsal
+
+Run and prove the complete MVP path locally and in staging-testnet with value-bearing mainnet blocked.
+
+### Gate 9: V42 Promotion Readiness
+
+Bind every V42 product artifact, workflow, generated proof, promotion command, source-safety result, and active V42 / draft V43 runtime posture.
+
+## Explicitly deferred
+
+- V43+ agentic deposit AssetPack option synthesis remains deferred.
+- `/terminal` is not split into `/read` and `/deposit` during V42.
+- `/exchange` is not renamed to `/packs` during V42.
+- Production-mainnet value-bearing operation remains blocked unless a later promoted canon explicitly admits it.
+- V42 Gate 1 does not change route behavior, pipeline behavior, settlement behavior, or demonstration behavior.
+
+## Pre-Implementation Sequence
+
+1. Open `version/v42` and `v42/gate-1-mvp-experience-roadmap-opening`.
+2. Keep `BITCODE_SPEC.txt` at `V41`.
+3. Add the V42 spec family and Gate 1 checker.
+4. Update roadmap, docs, package scripts, and workflows for active V41 / draft V42.
+5. Validate V42 draft family and V41 active posture.
+
+## Commit-Body Direction
+
+V42 commits should name the product path, protocol object, pipeline or route ownership, source-safety boundary, generated artifact or checker, and tests run.

BITCODE_SPEC_V42_DELTA.md

@@ -0,0 +1,80 @@
+# Bitcode Spec V42 Notes
+
+## Status
+
+- Version: `V42`
+- V42 state: draft opened; notes track reliable MVP experience planning over active V41
+- Current canonical/latest target: `V41`
+- Prior canonical anchor: `BITCODE_SPEC_V41.md`
+- Prior generated proof appendix: `BITCODE_SPEC_V41_PROVEN.md`
+- Generated structured artifact inventory: draft `.bitcode/v42-spec-family-report.json`, `.bitcode/v42-canonical-input-report.json`, `.bitcode/v42-canon-posture-drift-report.json`, and later V42 gate artifacts
+- Source parity state: notes are source-facing planning until later gates implement and prove product behavior
+- Scope: V42 notes for reliable MVP product experience
+
+## Notes companion rule
+
+This notes companion records the working V42 product plan and simplified reading.
+It does not override `BITCODE_SPEC_V42.md`.
+Product behavior changes remain blocked until the relevant V42 gate admits and verifies them.
+
+## V42 Gate 1 opening note
+
+Gate 1 is intentionally specification, documentation, workflow, and checker posture only.
+It opens the reliable MVP experience version after V41 prompt-program promotion and prepares later gates to implement Depositing, Reading, settlement, delivery, and demonstration behavior without ad hoc scope drift.
+
+## Depositing shortest-path note
+
+The V42 Depositing path should minimize the journey from source material to Depository admission proof.
+The user needs to know that the source is admitted, searchable for future Need-Fit work, and eligible for BTC compensation if it contributes to a synthesized AssetPack.
+The UX can stay simple, but expandable details must show source authority, admission proof, storage projection, search-document posture, compensation route, and repair state.
+
+## Reading shortest-path note
+
+The V42 Reading path should be a five-step enterprise flow:
+
+1. request read;
+2. review synthesized Need;
+3. request Finding Fits;
+4. review source-safe AssetPack measurements and preview metadata;
+5. buy, settle, transfer rights, and receive repository delivery.
+
+The default UI should be guided and low-detail.
+The rich execution log, proof roots, telemetry rows, and ledger/storage details remain available on expansion.
+
+## AssetPack source-safety note
+
+V42 must make the preview valuable without leaking the source-bearing AssetPack before settlement.
+Readers may see measurements, fit confidence, quote posture, selected-fit provenance summaries, proof roots, and source-safe explanations.
+They may not see protected source, raw provider responses, protected prompts, private settlement payloads, wallet private material, or unpaid AssetPack source before BTC settlement and BTD rights transfer.
+
+## AI-reading demonstration note
+
+The standalone demonstration should prove why Bitcode matters for AI-dominant Reading.
+A deposited proprietary or otherwise non-public technical intelligence source should contribute to an AssetPack that measurably improves an AI system's training, prompt/context, or evaluation result beyond what a public-data-only baseline can do.
+The demonstration must remain minimal, local, deterministic where feasible, and self-contained inside `protocol-demonstration/`.
+
+## V43+ agentic depositing roadmap note
+
+V43 or a later explicitly opened version should evolve the deposit side into an agentic AssetPack option experience for enterprises.
+Repository-installed Bitcode Agents should compare a connected enterprise codebase, the current Bitcode Depository, and Reading activity to propose deposit AssetPack options.
+Those options should be source-safe, sub-critical, likely positive ROI, and approve/rejectable before Depository admission.
+That later version should split `/terminal` into `/read` and `/deposit`, and rename `/exchange` to `/packs` across routes, code naming, docs, and operator vocabulary.
+
+## Concise current-system reading
+
+Bitcode is active at V41.
+V42 drafts the next canon: the reliable MVP experience for enterprise Depositing and Reading.
+The central product promise is that a user can deposit source, request a read, review a synthesized Need, find fitting Depository sources, preview a source-safe AssetPack, pay in BTC/BTD settlement terms, receive rights, and get repository delivery.
+
+## Simplified-spec reading rule
+
+Read V42 as shortest credible paths over existing protocol law.
+If a product step cannot be routed, stored, replayed, telemetered, proven, and source-safely explained, it is not V42-ready.
+
+## Non-goals during V42 opening
+
+- Do not implement product behavior in Gate 1.
+- Do not split `/terminal` or rename `/exchange`.
+- Do not expose protected source or unpaid AssetPack source.
+- Do not bypass Need review before Finding Fits.
+- Do not claim settlement, BTD rights transfer, or repository delivery without synchronized ledger/database/storage proof.

BITCODE_SPEC_V42_NOTES.md

@@ -0,0 +1,70 @@
+# Bitcode Spec V42 Parity Matrix
+
+## Status
+
+- Version: `V42`
+- V42 state: draft opened; parity tracks reliable MVP experience gaps and closure gates over active V41
+- Current canonical/latest target: `V41`
+- Prior canonical anchor: `BITCODE_SPEC_V41.md`
+- Prior generated proof appendix: `BITCODE_SPEC_V41_PROVEN.md`
+- Generated structured artifact inventory: draft `.bitcode/v42-spec-family-report.json`, `.bitcode/v42-canonical-input-report.json`, `.bitcode/v42-canon-posture-drift-report.json`, and later V42 gate artifacts
+- Source parity state: Gate 1 parity is documentation/checker/workflow posture; product behavior rows remain draft-required until their gates close
+- Scope: V42 parity ledger for reliable MVP product experience
+
+## Purpose
+
+This matrix records the reliable MVP product surfaces that must become promotion-grade before V42 can replace V41 as active canon.
+
+## Audit basis
+
+- `BITCODE_SPEC.txt` -> `V41`
+- `BITCODE_SPEC_V41.md`
+- `BITCODE_SPEC_V41_PROVEN.md`
+- `BITCODE_SPEC_V42.md`
+- `BITCODE_SPEC_V42_DELTA.md`
+- `BITCODE_SPEC_V42_NOTES.md`
+- commercial product routes, packages, pipelines, BTD/ledger code, generated artifacts, workflows, and `protocol-demonstration/`
+
+## V42 implementation matrix
+
+| Area | Required V42 result | Source evidence | Judgment |
+| --- | --- | --- | --- |
+| Draft family | V42 SPEC, DELTA, NOTES, and PARITY files exist over active V41 | `BITCODE_SPEC_V42.md` family | drafted |
+| Roadmap truth | Roadmap states V41 active and V42 draft reliable MVP experience | `SPECIFICATIONS_ROADMAP.md` | drafted |
+| Gate workflow | Gate quality knows active V41 / draft V42 posture and V42 Gate 1 | `.github/workflows/bitcode-gate-quality.yml` | drafted |
+| Canon workflow | Canon quality knows active V41 / draft V42 posture and V42 Gate 1 | `.github/workflows/bitcode-canon-quality.yml` | drafted |
+| Depositing shortest path | Source material can be admitted with Depository proof and compensation visibility | later V42 Gate 2 artifact | draft-required |
+| Reading state machine | Five-step Reading UX is route-owned, persistent, and source-safe | later V42 Gate 3 artifact | draft-required |
+| ReadNeed product closure | Need synthesis, review, feedback, resynthesis, and accepted-Need admission are product-ready | later V42 Gate 4 artifact | draft-required |
+| Finding Fits preview and quote | Many-candidate search, selected-fit provenance, source-safe preview, and quote are product-ready | later V42 Gate 5 artifact | draft-required |
+| Settlement and delivery | BTC/BTD settlement, rights transfer, compensation, and repository PR delivery are synchronized | later V42 Gate 6 artifact | draft-required |
+| AI-reading demonstration | Standalone demonstration proves AssetPack improves AI beyond public-data-only baseline | later V42 Gate 7 artifact | draft-required |
+| Local/staging rehearsal | Full MVP path rehearsed locally and in staging-testnet with mainnet blocked | later V42 Gate 8 artifact | draft-required |
+| Promotion readiness | V42 proof and workflow promotion ready | later V42 Gate 9 artifact | draft-required |
+
+## V42 implementation checklist
+
+| Area | Closure requirement | Judgment |
+| --- | --- | --- |
+| Gate 1 | Open V42 family, roadmap, docs, workflow posture, package script, and checker | drafted |
+| Gate 2 | Depositing shortest path and compensation visibility artifact | draft-required |
+| Gate 3 | Reading shortest path state machine artifact | draft-required |
+| Gate 4 | ReadNeed review and resynthesis product closure artifact | draft-required |
+| Gate 5 | ReadFitsFinding AssetPack preview and quote closure artifact | draft-required |
+| Gate 6 | Settlement rights transfer and repository delivery closure artifact | draft-required |
+| Gate 7 | AI-reading dominant demonstration MVP artifact | draft-required |
+| Gate 8 | Local and staging-testnet full MVP rehearsal artifact | draft-required |
+| Gate 9 | Promotion readiness artifact and workflow | draft-required |
+
+## V42 accepted boundaries
+
+V42 Gate 1 may open specification, workflow, docs, and validation posture.
+It may not implement route, pipeline, settlement, or demonstration behavior.
+
+V42 later gates may implement product behavior only if source-safe disclosure, Need review, BTD/BTC settlement, depositor compensation, repository delivery, telemetry, and generated proof obligations are represented in tests and artifacts.
+
+V42 may not split `/terminal` into `/read` and `/deposit`, and may not rename `/exchange` to `/packs`; those are V43+ roadmap items unless explicitly reopened.
+
+## V42 completion condition
+
+V42 closes when reliable MVP Depositing, Reading, Finding Fits, AssetPack preview, BTD/BTC settlement, repository delivery, compensation visibility, AI-reading demonstration, local/staging rehearsal, and promotion readiness are all specified, implemented, tested, generated, workflow-bound, source-safe, and promotion-ready.

BITCODE_SPEC_V42_PARITY_MATRIX.md

@@ -1,8 +1,8 @@
 # Bitcode Repository
 
 `BITCODE_SPEC.txt` is the canonical pointer for active-system work. It currently
-resolves to `V40`; V41 is the active draft target for Prompt and PromptPart
-excellence after the promoted exhaustive commercial application testing canon.
+resolves to `V41`; V42 is the active draft target for reliable MVP product
+experience after the promoted Prompt and PromptPart excellence canon.
 
 ## Current Product Posture
 
@@ -81,12 +81,12 @@ dry-run support, gate/canon workflow posture, active V41 / draft V42 runtime
 preparation, and source-safe value-bearing mainnet blocking through
 `generate:v41-promotion-readiness`, `check:v41-promotion-readiness`, and
 `check:v41-gate9`.
-V42 is now roadmapped as the next MVP experience version: shortest-path
-Depositing with later BTC compensation, shortest-path Reading through
-Need review/resynthesis, Finding Fits, source-safe AssetPack preview,
-BTD/BTC settlement, repository delivery, and an AI-reading dominant
-demonstration whose AssetPack measurably improves an AI system beyond
-public-data-only performance.
+V42 Gate 1 opens the reliable MVP experience specification family over active
+V41 with `check:v42-gate1`. V42 is scoped to shortest-path Depositing with
+later BTC compensation, shortest-path Reading through Need review/resynthesis,
+Finding Fits, source-safe AssetPack preview, BTD/BTC settlement, repository
+delivery, and an AI-reading dominant demonstration whose AssetPack measurably
+improves an AI system beyond public-data-only performance.
 V43+ is roadmapped as the later agentic depositing evolution: repository
 agents synthesize deposit AssetPack options from connected enterprise code,
 Depository state, and Reading demand; enterprises approve or reject
@@ -710,9 +710,9 @@ or promotion validation.
 ## Key Surfaces
 
 - [BITCODE_SPEC.txt](BITCODE_SPEC.txt) is the canonical version pointer.
-- [BITCODE_SPEC_V39.md](BITCODE_SPEC_V39.md) is the active promoted spec family.
-- [BITCODE_SPEC_V40.md](BITCODE_SPEC_V40.md) is the active draft target.
-- [BITCODE_SPEC_V40_PARITY_MATRIX.md](BITCODE_SPEC_V40_PARITY_MATRIX.md) tracks V40 gate parity.
+- [BITCODE_SPEC_V41.md](BITCODE_SPEC_V41.md) is the active promoted spec family.
+- [BITCODE_SPEC_V42.md](BITCODE_SPEC_V42.md) is the active draft target.
+- [BITCODE_SPEC_V42_PARITY_MATRIX.md](BITCODE_SPEC_V42_PARITY_MATRIX.md) tracks V42 gate parity.
 - [uapi/README.md](uapi/README.md) documents the commercial website/API surface.
 - [uapi/app/terminal/README.md](uapi/app/terminal/README.md) documents Terminal.
 - [uapi/app/exchange/README.md](uapi/app/exchange/README.md) documents Exchange.