Merge pull request #180 from engineeredsoftware/v43/gate-1-packs-read-deposit-roadmap

V43 Gate 1: Packs Read Deposit Roadmap

Author: geraldarthurdavis

.github/pull_request_template.md

@@ -1,7 +1,7 @@
 ## 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`.
+Use the version and gate prefix for gate PRs: `V43 Gate N: Concise Topical Title`.
+Use the version and promotion prefix for version promotion PRs: `V43 Canonical Promotion: Concise Topical Title`.
 
 ## Closure
 

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

@@ -327,6 +327,7 @@ jobs:
             node scripts/check-v42-gate9-promotion-readiness.mjs --promotion-mode --skip-branch-check --skip-package-tests
             if [ -f BITCODE_SPEC_V43.md ]; then
               node scripts/check-bitcode-spec-family.mjs --version V43 --mode draft --current-target V42
+              node scripts/check-v43-gate1-packs-read-deposit-roadmap.mjs --skip-branch-check
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2

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

@@ -456,6 +456,7 @@ jobs:
             node scripts/check-v42-gate9-promotion-readiness.mjs --promotion-mode --skip-branch-check --skip-package-tests
             if [ -f BITCODE_SPEC_V43.md ]; then
               node scripts/check-bitcode-spec-family.mjs --version V43 --mode draft --current-target V42
+              node scripts/check-v43-gate1-packs-read-deposit-roadmap.mjs --skip-branch-check
             fi
           else
             echo "Unexpected BITCODE_SPEC.txt pointer: $POINTER" >&2
@@ -486,6 +487,9 @@ jobs:
             else
               node scripts/check-v42-gate9-promotion-readiness.mjs --promotion-mode --skip-branch-check
             fi
+            if [ -f scripts/check-v43-gate1-packs-read-deposit-roadmap.mjs ]; then
+              node scripts/check-v43-gate1-packs-read-deposit-roadmap.mjs --skip-branch-check
+            fi
             pnpm --filter @bitcode/protocol test
             pnpm --filter @bitcode/btd exec jest --config jest.config.cjs --runInBand --forceExit
             pnpm --filter @bitcode/pipeline-asset-pack exec jest --config jest.config.cjs --passWithNoTests --forceExit

BITCODE_SPEC_V43.md

@@ -0,0 +1,48 @@
+# Bitcode Spec V43 Delta
+
+## Status
+
+- Version: `V43`
+- V43 state: draft opened over promoted V42 for product-route cleanup and agentic deposit AssetPack option synthesis
+- Current canonical/latest target: `V42`
+- Prior canonical anchor: `BITCODE_SPEC_V42.md`
+- Prior generated proof appendix: `BITCODE_SPEC_V42_PROVEN.md`
+- Generated structured artifact inventory: `.bitcode/v43-spec-family-report.json`, `.bitcode/v43-canonical-input-report.json`, and V43 gate artifacts as introduced
+- Source parity state: Gate 1 opens V43 specification and validation posture; implementation parity is gate-scoped
+
+## Why V43 exists
+
+V42 proved the reliable MVP path, but the product route vocabulary is still transitional. V43 exists to make the commercial website experience match Bitcode's actual protocol objects: AssetPacks in and AssetPacks out, Reading through a clear `/read` path, Depositing through a clear `/deposit` path, and all activity through a searchable `/packs` surface.
+
+## Accepted V43 decisions
+
+1. `/exchange` becomes `/packs` across route names, component prefixes, tests, docs, telemetry labels, and operator vocabulary.
+2. `/terminal` splits into `/read` and `/deposit` as the default product paths; retained cockpit/debug surfaces must not be the main experience.
+3. `/packs` becomes the master-detail table for all pack activity, with search, filtering, sorting, and source-safe detail expansion.
+4. `/deposit` gains agentic deposit AssetPack option synthesis from connected source, depositor instructions, Depository state, and Reading demand.
+5. Deposit options must expose source-safe measurements, sub-criticality, demand, likely ROI, BTD potential, compensation posture, and admission blockers before approval.
+6. `/read` remains the five-step Reading path: request read, review synthesized Need, request Finding Fits, review source-safe AssetPack preview, settle/buy/deliver.
+7. Product UX outside public documentation must be self-explanatory through structure, labels, progressive detail, rich components, and visual quality, not self-referential copy.
+
+## Explicitly deferred
+
+- Value-bearing mainnet admission remains gated by a later canon.
+- Advanced conversational overlays are not the default V43 route experience unless a gate explicitly scopes them.
+- BTD supply law, BTC settlement conservation, source-to-shares accounting, and unpaid source disclosure boundaries remain inherited from V42/V27.
+
+## Pre-Implementation Sequence
+
+1. Open V43 spec family, roadmap, checker, package script, and workflow posture.
+2. Inventory current Exchange/Terminal naming and define route migration.
+3. Implement `/packs` data contracts and searchable master-detail.
+4. Extract `/read` from Terminal into the default Reading path.
+5. Implement `/deposit` and agentic deposit AssetPack option synthesis.
+6. Add criticality, demand, ROI, BTD potential, and compensation policy.
+7. Close deposit option review/admission and pack activity synchronization.
+8. Run UX/UI excellence pass and remove self-referential product copy.
+9. Rehearse cross-route local/staging-testnet path.
+10. Close promotion readiness.
+
+## Commit-Body Direction
+
+V43 gate commits should state the route/product surface changed, the protocol objects preserved, the proof/test commands run, and the source-safety boundaries maintained. Gate PR titles must begin with `V43 Gate N:`.

BITCODE_SPEC_V43_DELTA.md

@@ -0,0 +1,49 @@
+# Bitcode Spec V43 Notes
+
+## Status
+
+- Version: `V43`
+- V43 state: draft notes opened for product-route cleanup, pack activity, agentic deposit options, and enterprise UX
+- Current canonical/latest target: `V42`
+- Prior canonical anchor: `BITCODE_SPEC_V42.md`
+- Prior generated proof appendix: `BITCODE_SPEC_V42_PROVEN.md`
+- Generated structured artifact inventory: `.bitcode/v43-spec-family-report.json`, `.bitcode/v43-canonical-input-report.json`, and future V43 gate artifacts
+- Source parity state: notes define operating memory for V43 gates; implementation parity is pending gate work
+
+## Notes companion rule
+
+These notes clarify V43 only. The active canon remains V42 until V43 promotion.
+
+## Concise current-system reading
+
+V42 made the reliable MVP path real enough to refine product shape. V43 should now remove transitional vocabulary and make the primary enterprise experience:
+
+- `/deposit`: connect source, synthesize deposit AssetPack options, review source-safe measurements and demand/ROI posture, approve or reject Depository admission.
+- `/read`: request technical knowledge, review synthesized Need, request Finding Fits, preview source-safe AssetPack measurements, settle in BTC/BTD, receive repository delivery.
+- `/packs`: inspect and search all pack activity, including deposit options, Depository admission, previews, settlement, rights transfer, compensation, delivery, proof roots, and repair states.
+
+The strongest simplification is AssetPacks in and AssetPacks out. Depositing creates AssetPacks for the Depository; Reading buys synthesized Need-Fit AssetPacks.
+
+## Simplified-spec reading rule
+
+When V43 work feels broad, reduce it to the route law:
+
+1. Packs is activity and inspection.
+2. Read is buying source-bearing technical knowledge after Need review and settlement.
+3. Deposit is selling source-derived AssetPack options only after depositor review and approval.
+4. Source is never disclosed before settlement and rights transfer.
+5. The UI should explain itself through the workflow, not through in-app essays.
+
+## V43 UX/product note
+
+The current UX is not good enough. V43 should keep strong themed components where they work, especially execution-log rows and proof expansion, but replace confusing cockpit flow with direct route paths and dense, legible master-detail surfaces.
+
+The `/packs` master table must support search over measurements, synthesized titles and descriptions, values, activity/transaction type, settlement state, compensation posture, proof roots, and repair state.
+
+## V43 agentic deposit note
+
+The deposit-side pipeline should help an enterprise decide what IP to sell. It should compare connected source, Depository supply, and Reading demand. It should propose multiple deposit AssetPack options, reject or warn on critical IP, estimate positive ROI where possible, expose BTD potential as an estimate only, and preserve final BTD mint/right law for paid Need-Fit settlement.
+
+## V43 copy boundary
+
+Outside public docs, avoid self-referential copy such as text explaining that a component is powerful or that Bitcode is doing a thing. Use clear route names, labels, status rows, measurement summaries, empty states, and expandable proof metadata. Public docs may explain the protocol; product UI should operate it.

BITCODE_SPEC_V43_NOTES.md

@@ -0,0 +1,52 @@
+# Bitcode Spec V43 Parity Matrix
+
+## Status
+
+- Version: `V43`
+- V43 state: draft parity matrix opened over active V42
+- Current canonical/latest target: `V42`
+- Prior canonical anchor: `BITCODE_SPEC_V42.md`
+- Prior generated proof appendix: `BITCODE_SPEC_V42_PROVEN.md`
+- Generated structured artifact inventory: `.bitcode/v43-spec-family-report.json`, `.bitcode/v43-canonical-input-report.json`, and future V43 gate artifacts
+- Source parity state: V43 Gate 1 parity is documentation/workflow posture; implementation parity is pending
+
+## Purpose
+
+This matrix tracks V43 parity from product-route specification through source implementation, tests, generated artifacts, and promotion readiness.
+
+## Audit basis
+
+Audit V43 against `BITCODE_SPEC_V43.md`, V42 active canon, route source, package source, generated artifacts, workflow checks, and local/staging rehearsal receipts.
+
+## V43 implementation matrix
+
+| Area | Required V43 result | Source evidence | Judgment |
+| --- | --- | --- | --- |
+| Gate 1 roadmap | Active V42 / draft V43 posture, route vocabulary, gate plan, docs, checker, workflows | `BITCODE_SPEC_V43.md`, `scripts/check-v43-gate1-packs-read-deposit-roadmap.mjs` | drafted |
+| Route vocabulary | `/exchange` renamed to `/packs`; `/terminal` split into `/read` and `/deposit` default paths | future Gate 2 artifact | draft-required |
+| Packs master-detail | Searchable, sortable, filterable pack activity table and source-safe detail route | future Gate 3 artifact | draft-required |
+| Read route | Five-step Reading UX owns Read Request through settlement/delivery | future Gate 4 artifact | draft-required |
+| Deposit route | Connected-source deposit AssetPack option synthesis and review | future Gate 5 artifact | draft-required |
+| Criticality/ROI policy | Source criticality, demand, ROI, BTD potential, and compensation posture | future Gate 6 artifact | draft-required |
+| Admission sync | Approved deposit options enter Depository and `/packs` activity | future Gate 7 artifact | draft-required |
+| UX excellence | Self-explanatory, polished, progressive-detail UI without self-referential product copy | future Gate 8 artifact | draft-required |
+| Rehearsal | Local/staging-testnet cross-route path verifies deposit, read, packs, settlement, compensation, delivery | future Gate 9 artifact | draft-required |
+| Promotion readiness | V43 generated proof and active V43 / draft V44 posture ready | future Gate 10 artifact | draft-required |
+
+## V43 implementation checklist
+
+| Area | Closure requirement | Current judgment |
+| --- | --- | --- |
+| Specification family | V43 SPEC, DELTA, NOTES, PARITY files exist and pass spec-family check | drafted |
+| Package script | `check:v43-gate1` exists | drafted |
+| Workflows | Gate/canon quality know active V42 / draft V43 | drafted |
+| Documentation | README and roadmap name V43 route/product scope | drafted |
+| Implementation | Route and pipeline source changes are not part of Gate 1 | accepted boundary |
+
+## V43 accepted boundaries
+
+Gate 1 is allowed to specify and wire validation posture only. It must not rename application routes or add deposit option synthesis behavior before the migration inventory is complete.
+
+## V43 completion condition
+
+The matrix is complete when every V43 gate row is closed with source, tests, documentation, generated artifacts, and promotion proof.

BITCODE_SPEC_V43_PARITY_MATRIX.md

@@ -1,17 +1,24 @@
 # Bitcode Repository
 
 `BITCODE_SPEC.txt` is the canonical pointer for active-system work. It currently
-resolves to `V41`; V42 is the active draft target for reliable MVP product
-experience after the promoted Prompt and PromptPart excellence canon.
+resolves to `V42`; V43 is the active draft target for the Packs, Read, Deposit
+route model, agentic deposit AssetPack options, and product UX cleanup after the
+promoted reliable MVP experience canon.
 
 ## Current Product Posture
 
 Bitcode is the protocol and the commercial source tree implements it in-place.
-The primary operator routes are:
+The promoted V42 operator route is still:
 
 - `/terminal` for depositing, reading, transaction work, and protocol follow-through.
 - `/auxillaries` for Wallet, Externals, Profile, and Interfaces support surfaces.
 
+The active V43 draft target moves the primary enterprise routes to:
+
+- `/packs` for searchable master-detail pack activity.
+- `/read` for the five-step Reading path from Read Request to settlement-gated delivery.
+- `/deposit` for connected-source deposit AssetPack option synthesis, review, and admission.
+
 V41 Gate 1 opens the prompts-as-programs specification family over active V40
 with `check:v41-gate1`. V41 will catalogue every raw PromptPart and composed
 Prompt, map registry composition and interpolation contracts, benchmark Reading
@@ -155,13 +162,14 @@ V42 Gate 9 adds promotion readiness with `buildV42PromotionReadinessReport`,
 The report binds every V42 product artifact, workflow posture, promotion
 script, generated proof path, source-safety result, value-bearing mainnet
 block, and post-promotion V42 active / draft V43 runtime preparation.
-V43+ is roadmapped as the later agentic depositing evolution: repository
+V43 Gate 1 opens the Packs, Read, Deposit roadmap over active V42 with
+`check:v43-gate1`. V43 owns the agentic depositing evolution: repository
 agents synthesize deposit AssetPack options from connected enterprise code,
 Depository state, and Reading demand; enterprises approve or reject
 sub-critical positive-ROI options; `/terminal` separates into `/read` and
 `/deposit`; and `/exchange` is renamed to `/packs` across routes, component
-prefixes, tests, docs, and product naming.
-That future route model treats AssetPacks as the product object in and out:
+prefixes, tests, docs, telemetry labels, and product naming.
+The V43 route model treats AssetPacks as the product object in and out:
 `/deposit` proposes deposit AssetPack options from source and Bitcode demand,
 `/read` buys synthesized Need-Fit AssetPacks, and `/packs` becomes the
 searchable master-detail activity surface for pack measurements, values,