Merge pull request #160 from engineeredsoftware/v41/gate-1-prompt-program-roadmap-opening

V41 Gate 1: Open Prompt Program Roadmap

Author: geraldarthurdavis

.github/pull_request_template.md

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

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

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

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

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

BITCODE_SPEC_V41.md

@@ -0,0 +1,81 @@
+# Bitcode Spec V41 Delta
+
+## Status
+
+- Version: `V41`
+- V41 state: draft opened; this delta records the V40-to-V41 prompt-program opening plan
+- Current canonical/latest target: `V40`
+- Prior canonical anchor: `BITCODE_SPEC_V40.md`
+- Prior generated proof appendix: `BITCODE_SPEC_V40_PROVEN.md`
+- Generated structured artifact inventory: draft `.bitcode/v41-spec-family-report.json`, draft `.bitcode/v41-canonical-input-report.json`, planned prompt-program catalogue artifacts, planned benchmark artifacts, planned promotion-readiness artifact, and eventual `BITCODE_SPEC_V41_PROVEN.md` after V41 promotion
+- Source parity state: V41 source parity begins at specification and workflow posture; prompt rewrites are explicitly deferred until catalogue and benchmark gates close
+- Scope: V41 draft delta for Prompt and PromptPart excellence over promoted V40
+
+## Why V41 exists
+
+V38 hardened inference architecture and V40 hardened testing and benchmark lanes.
+V41 uses that base to treat prompts as programs: enumerable, benchmarkable, typed, source-safe, and registry-bound.
+
+## Accepted V41 decisions
+
+- V41 is singularly focused on Prompt and PromptPart implementation quality.
+- Reading prompts are the priority, especially `ReadNeedComprehensionSynthesis` and `ReadFitsFindingSynthesis`.
+- Prompt rewrites require prior inventory, registry composition proof, interpolation proof, benchmark baselines, parsed return-type checks, and source-safe telemetry proof.
+- Prompt artifacts may carry ids, hashes, metrics, verdicts, and redacted summaries, but not raw protected prompt text, raw provider responses, secrets, wallet material, protected source, private settlement payloads, or unpaid AssetPack source.
+- V41 preserves V27 BTC/BTD law, V38 inference call-stack law, V39 Reading product law, and V40 testing law.
+
+## V41 gate plan
+
+### Gate 1: Prompt Program Roadmap And Spec Opening
+
+Open the V41 full specification family, roadmap, package script, workflow posture, documentation posture, branch convention, and checker.
+
+### Gate 2: PromptPart And Prompt Inventory Catalog
+
+Inventory every raw PromptPart and composed Prompt across Reading, Conversation, tool-definition, and interface inference surfaces.
+
+### Gate 3: Registry Composition And Interpolation Contracts
+
+Prove registry composition, prompt context interpolation, execution ancestry, tool prompt injection, and parsed return type bindings.
+
+### Gate 4: Reading Pipeline Prompt Benchmark Baselines
+
+Create source-safe baseline benchmarks for Reading prompt surfaces before rewriting them.
+
+### Gate 5: ReadNeedComprehensionSynthesis Prompt Rewrite And Return-Type Hardening
+
+Rewrite and repartition ReadNeed prompts only after evidence proves the rewrite improves exact Need comprehension and typed output reliability.
+
+### Gate 6: ReadFitsFindingSynthesis Prompt Rewrite Search And AssetPack Context Hardening
+
+Rewrite and repartition Finding Fits prompts only after evidence proves the rewrite improves Depository search, ranking, selected-fit provenance, and AssetPack context source-safely.
+
+### Gate 7: Conversation Tool And Interface Prompt Rewrite
+
+Apply the same prompt-program discipline to Conversation, tool-definition, MCP API, ChatGPT App, public API, Terminal, and other interface prompts.
+
+### Gate 8: Prompt Benchmark Report And Telemetry Integration
+
+Close post-rewrite benchmark deltas, prompt lineage, telemetry integration, and source-safe rich stream projections.
+
+### Gate 9: Promotion Readiness
+
+Bind all V41 prompt artifacts, tests, workflow checks, generated proof support, promotion commands, and active V41 / draft V42 posture.
+
+## Explicitly deferred
+
+- No prompt content is rewritten during Gate 1.
+- New commercial product behavior is deferred unless needed to make prompt-program tests truthful.
+- Production-mainnet value-bearing prompt rehearsals remain opt-in.
+
+## Pre-Implementation Sequence
+
+1. Open `version/v41` and `v41/gate-1-prompt-program-roadmap-opening`.
+2. Keep `BITCODE_SPEC.txt` at `V40`.
+3. Add the V41 spec family and Gate 1 checker.
+4. Update roadmap, docs, package scripts, and workflows for active V40 / draft V41.
+5. Validate V41 draft family and V40 active posture.
+
+## Commit-Body Direction
+
+V41 commits should name the prompt-program surface, generated artifact or checker, benchmark posture, registry/callsite scope, source-safety boundary, and tests run.

BITCODE_SPEC_V41_DELTA.md

@@ -3,18 +3,37 @@
 ## Status
 
 - Version: `V41`
-- V41 state: notes-only draft opening
+- V41 state: draft opened; V41 notes now accompany the full prompt-program specification family
+- Current canonical/latest target: `V40`
 - Canonical pointer: `BITCODE_SPEC.txt` -> `V40`
-- Active canonical anchor: `BITCODE_SPEC_V40.md`
-- Active generated proof appendix: `BITCODE_SPEC_V40_PROVEN.md`
-- Draft target posture: V41 is opened as planning notes only until its first gate creates the full SPEC, DELTA, NOTES companion, and PARITY family.
+- Prior canonical anchor: `BITCODE_SPEC_V40.md`
+- Prior generated proof appendix: `BITCODE_SPEC_V40_PROVEN.md`
+- Generated structured artifact inventory: draft `.bitcode/v41-spec-family-report.json`, draft `.bitcode/v41-canonical-input-report.json`, planned prompt-program catalogue artifacts, planned benchmark artifacts, planned promotion-readiness artifact, and eventual `BITCODE_SPEC_V41_PROVEN.md` after V41 promotion
+- Source parity state: V41 notes track prompt-program planning, catalogue, benchmark, rewrite, telemetry, and promotion parity over active V40
+- Draft target posture: V41 Gate 1 creates the full SPEC, DELTA, NOTES, and PARITY family.
 - Scope: Prompt and PromptPart excellence over the promoted V40 exhaustive testing base.
 
+## Notes companion rule
+
+This notes companion records the working prompt-program plan and simplified reading for V41.
+It does not override `BITCODE_SPEC_V41.md`.
+Prompt content changes remain blocked until the relevant catalogue and benchmark gates admit them.
+
+## Concise current-system reading
+
+Bitcode is active at V40.
+V41 now drafts the next canon: every PromptPart and composed Prompt must become catalogue-visible, benchmarkable, registry-bound, interpolation-checked, parser-typed, and source-safe.
+The first priority is Reading through `ReadNeedComprehensionSynthesis` and `ReadFitsFindingSynthesis`; Conversation, tool-definition, and interface prompts follow with the same discipline.
+
+## Simplified-spec reading rule
+
+Read V41 as prompts as programs.
+If a prompt cannot be found in the catalogue, traced through a registry, benchmarked against fixtures, tied to a parsed return type, and projected source-safely into telemetry, it is not V41-ready.
+
 ## Notes-only draft rule
 
-This file is the only opened V41 draft-target file until V41 Gate 1 formally creates the full V41 specification family.
-It records next-version intent so strict draft-target spec-quality can remain truthful after V40 promotion.
-It is not first-gate implementation evidence and does not by itself admit V41 source changes, route changes, generated artifact requirements, or promotion checks.
+This heading is retained as historical context only.
+V41 is no longer notes-only after Gate 1; the full V41 specification family is the draft target.
 
 ## Deferred from V40
 

BITCODE_SPEC_V41_NOTES.md

@@ -0,0 +1,68 @@
+# Bitcode Spec V41 Parity Matrix
+
+## Status
+
+- Version: `V41`
+- V41 state: draft opened; V41 parity begins with prompt-program specification and workflow posture
+- Current canonical/latest target: `V40`
+- Prior canonical anchor: `BITCODE_SPEC_V40.md`
+- Prior generated proof appendix: `BITCODE_SPEC_V40_PROVEN.md`
+- Generated structured artifact inventory: draft `.bitcode/v41-spec-family-report.json`, draft `.bitcode/v41-canonical-input-report.json`, planned prompt-program catalogue artifacts, planned benchmark artifacts, planned promotion-readiness artifact, and eventual `BITCODE_SPEC_V41_PROVEN.md` after V41 promotion
+- Source parity state: Gate 1 closes spec, roadmap, docs, package script, workflow posture, and checker parity; later gates own source prompt inventory, rewrite, benchmark, telemetry, and promotion parity
+- Scope: V41 draft parity ledger for Prompt and PromptPart excellence
+- Last fully realized canonical target preserved in source: `V40`
+
+## Purpose
+
+This matrix records the prompt-program surfaces that must become promotion-grade before V41 can replace V40 as active canon.
+
+## Audit basis
+
+- `BITCODE_SPEC.txt` -> `V40`
+- `BITCODE_SPEC_V40.md`
+- `BITCODE_SPEC_V40_PROVEN.md`
+- `BITCODE_SPEC_V41.md`
+- `BITCODE_SPEC_V41_DELTA.md`
+- `BITCODE_SPEC_V41_NOTES.md`
+- prompt, registry, pipeline, Conversation, tool-definition, benchmark, and telemetry source roots
+
+## V41 implementation matrix
+
+| Area | Required V41 result | Source evidence | Judgment |
+| --- | --- | --- | --- |
+| Draft family | V41 SPEC, DELTA, NOTES, and PARITY files exist over active V40 | `BITCODE_SPEC_V41.md` family | drafted |
+| Roadmap truth | Roadmap states V40 active, V41 draft, prompt-program Gate 1 active | `SPECIFICATIONS_ROADMAP.md` | drafted |
+| Gate workflow | Gate quality knows active V40 and draft V41 Gate 1 | `.github/workflows/bitcode-gate-quality.yml` | drafted |
+| Canon workflow | Canon quality knows active V40 and draft V41 Gate 1 | `.github/workflows/bitcode-canon-quality.yml` | drafted |
+| Prompt inventory | Every raw PromptPart and composed Prompt catalogued | planned V41 Gate 2 artifact | pending |
+| Registry/interpolation | Registry composition and interpolation contracts proven | planned V41 Gate 3 artifact | pending |
+| Reading baselines | Reading prompt benchmarks captured before rewrites | planned V41 Gate 4 artifact | pending |
+| ReadNeed rewrite | ReadNeedComprehensionSynthesis prompts rewritten and type-hardened | planned V41 Gate 5 artifact | pending |
+| Finding Fits rewrite | ReadFitsFindingSynthesis prompts rewritten for search and AssetPack context | planned V41 Gate 6 artifact | pending |
+| Conversation/tool/interface rewrite | Non-Reading prompt surfaces brought to same standard | planned V41 Gate 7 artifact | pending |
+| Benchmark and telemetry | Prompt benchmark deltas and telemetry projections source-safe | planned V41 Gate 8 artifact | pending |
+| Promotion readiness | V41 prompt-program proof and workflow promotion ready | planned V41 Gate 9 artifact | pending |
+
+## V41 implementation checklist
+
+| Area | Closure requirement | Judgment |
+| --- | --- | --- |
+| Gate 1 | Open V41 family, roadmap, docs, workflow posture, package script, and checker | drafted |
+| Gate 2 | PromptPart and Prompt inventory artifact | pending |
+| Gate 3 | Registry composition and interpolation artifact | pending |
+| Gate 4 | Reading prompt benchmark baseline artifact | pending |
+| Gate 5 | ReadNeedComprehensionSynthesis rewrite artifact | pending |
+| Gate 6 | ReadFitsFindingSynthesis rewrite artifact | pending |
+| Gate 7 | Conversation, tool, and interface prompt rewrite artifact | pending |
+| Gate 8 | Prompt benchmark report and telemetry artifact | pending |
+| Gate 9 | Promotion readiness artifact and workflow | pending |
+
+## V41 accepted boundaries
+
+V41 Gate 1 may open specification, workflow, docs, and validation posture.
+It may not rewrite prompt content.
+Later gates may rewrite prompts only after catalogue, registry, interpolation, benchmark, parser, and disclosure checks exist.
+
+## V41 completion condition
+
+V41 closes when prompt-program quality is fully specified, implemented, benchmarked, source-safe, tested, documented, generated, workflow-checked, and promotion-ready across Reading, Conversation, tool-definition, and interface inference surfaces.

BITCODE_SPEC_V41_PARITY_MATRIX.md

@@ -1,8 +1,8 @@
 # Bitcode Repository
 
 `BITCODE_SPEC.txt` is the canonical pointer for active-system work. It currently
-resolves to `V39`; V40 is the active draft target for exhaustive commercial
-application testing after the promoted commercial Reading readiness canon.
+resolves to `V40`; V41 is the active draft target for Prompt and PromptPart
+excellence after the promoted exhaustive commercial application testing canon.
 
 ## Current Product Posture
 
@@ -12,6 +12,14 @@ The primary operator routes are:
 - `/terminal` for depositing, reading, transaction work, and protocol follow-through.
 - `/auxillaries` for Wallet, Externals, Profile, and Interfaces support surfaces.
 
+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
+prompt baselines, then harden `ReadNeedComprehensionSynthesis`,
+`ReadFitsFindingSynthesis`, Conversation, tool-definition, and interface prompts
+without exposing protected prompt payloads, raw provider responses, secrets,
+protected source, or unpaid AssetPack source.
+
 Exchange is inherited V36 canon: market-wide activity master-detail, buy/sell/
 bid/ask/cancel/accept/settle/history flows, AssetPack range trading,
 rights-transfer review, pricing/liquidity/wrapper analysis, settlement