Merge pull request #204 from engineeredsoftware/v45/gate-1-v44-promotion-addendum

Author: geraldarthurdavis

BITCODE_SPEC_V44.md

@@ -53,15 +53,30 @@ operating many technical knowledge trades.
 
 ## V44 source-of-truth hierarchy
 
-`BITCODE_SPEC.txt` points to `V43` while V44 is draft.
-`BITCODE_SPEC_V43.md` and `BITCODE_SPEC_V43_PROVEN.md` are active canon.
-`BITCODE_SPEC_V44.md`, `BITCODE_SPEC_V44_DELTA.md`,
-`BITCODE_SPEC_V44_NOTES.md`, and `BITCODE_SPEC_V44_PARITY_MATRIX.md` define
-the draft target only on `version/v44` and `v44/gate-*` branches.
+`BITCODE_SPEC.txt` points to `V44`; V44 is the active promoted Bitcode canon.
+`BITCODE_SPEC_V44.md` and `BITCODE_SPEC_V44_PROVEN.md` are active canon.
+`BITCODE_SPEC_V44_DELTA.md`, `BITCODE_SPEC_V44_NOTES.md`, and
+`BITCODE_SPEC_V44_PARITY_MATRIX.md` are promoted V44 companion canon. V43 is
+the prior canonical anchor only. `BITCODE_SPEC_V45_NOTES.md` is discussion-prep
+draft material only until a V45 version branch and first gate explicitly open.
 Implementation remains unversioned in source paths; package, route, component,
 test, prompt, script, and telemetry names move in place as the single current
 Bitcode system.
 
+## V44 promotion addendum: canonical posture repair
+
+V44 promotion discovered and repaired a source-of-truth prose contradiction:
+the promoted V44 status and `BITCODE_SPEC.txt` pointer correctly named V44 as
+active canon, while the source-of-truth hierarchy still contained pre-promotion
+V43-active / V44-draft language. That was a protocol-law contradiction in the
+canon-posture layer, even though it did not change BTC settlement, BTD rights,
+source withholding, source-to-shares, or repository delivery law.
+
+The repaired enforcement rule is: promoted spec-family validation fails when a
+promoted source-of-truth hierarchy says the active pointer targets an older
+version, says the promoted version remains a draft, or classifies the promoted
+spec family as draft-only branch material. Canon posture is protocol law.
+
 ## V44 full-system, re-implementation, and audit rule
 
 V44 work must be reconstructable from specification, source, generated
@@ -797,13 +812,12 @@ Gate 9 validates with `pnpm run generate:v44-scaled-network-rehearsal`,
 `pnpm run rehearse:v44-scaled-network -- --lane local --json`,
 `pnpm run rehearse:v44-scaled-network -- --lane staging-testnet --json`, and
 `pnpm run check:v44-gate9`.
-Shared draft posture validates with
-`node scripts/check-bitcode-spec-family.mjs --version V44 --mode draft --current-target V43`,
-`node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V43 --draft-target V44`,
-and `git diff --check`.
-
-Later gates must bind promotion readiness, PROVEN generation, and active V44 /
-draft V45 posture after scaled local/staging rehearsal proof is closed.
+Promoted V44 posture validates with
+`node scripts/check-bitcode-spec-family.mjs --version V44 --mode promoted --current-target V44`,
+`node scripts/check-bitcode-canon-posture-drift.mjs --active-canon V44 --draft-target V45`,
+and `git diff --check`. Historical V43-active / V44-draft checks are retained
+only as pre-promotion evidence in gate artifacts and prior branch history; they
+are not active V44 canon after promotion.
 
 ## V44 promotion canon
 

BITCODE_SPEC_V44_DELTA.md

@@ -36,6 +36,9 @@ settlements, contributors, compensation statements, and repair states.
 - Bind Gate 2 economic contracts in package code before route/API/UI surfaces
   consume portfolio, quote, settlement, compensation, governance, or repair
   objects.
+- Treat promoted source-of-truth hierarchy prose as protocol law: stale
+  active/draft wording after promotion is a canon-posture defect and must fail
+  promoted spec-family validation.
 
 ## V44 gate plan
 

BITCODE_SPEC_V44_NOTES.md

@@ -78,6 +78,15 @@ must remain metadata and proof roots. They must not serialize protected source,
 unpaid AssetPack source, raw prompts, raw provider responses, credentials,
 wallet private material, or private settlement payloads.
 
+## Promotion addendum note
+
+V44 promotion includes a post-promotion addendum repairing stale
+source-of-truth hierarchy prose. `BITCODE_SPEC.txt` now points to `V44`; V44 is
+the active canon; V45 notes are discussion-prep material only. Promoted
+spec-family validation must fail closed when promoted source-of-truth hierarchy
+prose still says an older version is active, the promoted version is draft, or
+the promoted spec family is draft-only branch material.
+
 ## Gate 1 note
 
 Gate 1 is intentionally a posture gate. It opens the V44 family and validates

BITCODE_SPEC_V44_PARITY_MATRIX.md

@@ -39,6 +39,7 @@ artifacts, workflow checks, and local/staging rehearsal receipts.
 | Enterprise UX | Dense economic surfaces, proof expansion, responsive/accessibility proof through `.bitcode/v44-enterprise-product-ux.json` | implemented |
 | Scaled rehearsal | Many-pack, many-org local/staging-testnet economic rehearsal through `.bitcode/v44-scaled-network-rehearsal.json` | implemented |
 | Promotion readiness | Generated PROVEN, workflow, all V44 artifacts bound | closed |
+| Promotion addendum | Promoted source-of-truth hierarchy repaired and enforced against stale V43-active / V44-draft prose | closed |
 
 ## V44 implementation checklist
 
@@ -49,6 +50,7 @@ artifacts, workflow checks, and local/staging rehearsal receipts.
 | Ledger reconciliation | Portfolio statements reconcile to receipts before finality | implemented |
 | Route authority | `/packs`, `/read`, `/deposit` do not bypass protocol law | implemented prerequisite |
 | Tests and proofs | Each gate has generated artifacts, package tests, route tests, and workflow checks | implemented prerequisite |
+| Canon posture prose | Promoted source-of-truth hierarchy fails closed when it contains stale draft/active wording | implemented |
 
 ## Accepted boundaries
 

BITCODE_SPEC_V45_NOTES.md

@@ -46,6 +46,69 @@ build/process validation.
 - Operational proof: preserve V44 workflow reliability while identifying the
   next proof, test, and replay obligations needed for the commercial system.
 
+## V45 opening discussion frame
+
+V45 opens from the premise that specification is the source of protocol truth.
+Before a V45 parity matrix or gate plan exists, the first work is a protocol
+audit over the promoted V44 canon. The audit should classify each framing as
+clearly specified, vaguely specified, incorrectly specified, missing, or already
+production-grade:
+
+- Bitcode as the world's knowledge commoditization system.
+- AssetPacks as the packaged knowledge commodity entering and leaving the
+  Depository.
+- Depositing as source-safe supply formation and later contributor
+  compensation.
+- Reading as demand formation, Need synthesis, Finding Fits, quote approval,
+  BTC settlement, BTD rights transfer, and repository delivery.
+- `/packs` as the searchable master-detail surface for Bitcode network
+  activity, proofs, statements, repairs, and economic state.
+- BTC as settlement money and source of payment truth.
+- BTD as the measured/mined/minted read-right object bound to AssetPack value,
+  rights transfer, source unlock, and ownership boundaries.
+- Proof roots, ledgerized journaling, telemetry, database/storage
+  synchronization, and generated canon as auditability rails.
+- Website routes, ChatGPT App, Bitcode Chat conversation overlays, API/MCP,
+  public docs, and landing page as coherent interface windows into the same
+  protocol law.
+
+## V45 known starting observations
+
+- V44 is strong on source-safe economic labels, route law, proof families,
+  generated artifacts, organization governance, and scaled rehearsal.
+- V44 needed this promotion addendum because canon posture text is protocol law:
+  a promoted spec cannot contain stale active/draft hierarchy prose.
+- V44 states the BTD/BTC/source-to-shares roles clearly, but V45 must decide
+  whether BTD measuring, mining, minting, ownership, and lifecycle state are
+  specified precisely enough for enterprise and public protocol comprehension.
+- V44 names BTC settlement, quote, observed payment, final settlement,
+  reconciliation, and repair states, but V45 should audit whether the exact
+  payment/finality/source-unlock/delivery state machine is complete enough.
+- V44 identifies interface surfaces beyond the website only as future alignment
+  targets; V45 should decide how deeply each interface must be specified before
+  implementation gates.
+
+## V45 questions before a parity matrix
+
+1. What is the smallest complete protocol-law statement for Bitcode as
+   knowledge commoditization system?
+2. What exact state transitions define an AssetPack from potential deposit
+   option through admitted supply, Finding Fits, paid Need-Fit pack, delivery,
+   compensation, and repair?
+3. What exact state transitions define BTD measuring, mining, minting,
+   ownership transfer, source unlock, and post-settlement rights?
+4. What exact state transitions define BTC quote, payment observation,
+   confirmation/finality, repair, refund/escalation if any, and contributor
+   compensation?
+5. Which user-visible statements are allowed before settlement, after preview,
+   after quote, after payment observation, after finality, after rights
+   transfer, and after repository delivery?
+6. Which surfaces are protocol-authoritative in V45: `/packs`, `/read`,
+   `/deposit`, API/MCP, ChatGPT App, Bitcode Chat, public docs, and landing
+   page?
+7. Which V45 gates should be specification-only, proof-only, interface-only,
+   implementation, rehearsal, and promotion gates?
+
 ## Non-goals during V45 opening
 
 - Do not implement V45 gate behavior before the V45 intent discussion is

packages/protocol/src/canonical/v21-specifying.js

@@ -1255,6 +1255,49 @@ function recordFailure(failures, condition, message) {
   if (!condition) failures.push(message);
 }
 
+/**
+ * @param {string[]} failures
+ * @param {string} section
+ * @param {string} version
+ */
+function validatePromotedSourceOfTruthHierarchy(failures, section, version) {
+  if (versionNumber(version) < 44) return;
+
+  recordFailure(
+    failures,
+    section.length > 0,
+    `spec promoted-mode validation requires a ${version} source-of-truth hierarchy section.`
+  );
+
+  recordFailure(
+    failures,
+    section.includes('BITCODE_SPEC.txt') && section.includes(`points to \`${version}\``),
+    `spec promoted source-of-truth hierarchy must state BITCODE_SPEC.txt points to ${version}.`
+  );
+
+  recordFailure(
+    failures,
+    /\bactive\b[\s\S]{0,80}\bcanon\b/i.test(section),
+    `spec promoted source-of-truth hierarchy must state ${version} is active canon.`
+  );
+
+  const staleDraftPosturePattern = new RegExp(
+    [
+      `BITCODE_SPEC\\.txt[\\s\\S]{0,160}points to[\\s\\S]{0,80}\\bV\\d+\\b[\\s\\S]{0,120}while[\\s\\S]{0,80}${version}[\\s\\S]{0,80}draft`,
+      `${version}[\\s\\S]{0,80}(?:is|remains)[\\s\\S]{0,80}draft`,
+      `${version}[\\s\\S]{0,160}draft target only`,
+      `define[\\s\\S]{0,80}the draft target only[\\s\\S]{0,80}${version}`
+    ].join('|'),
+    'i'
+  );
+
+  recordFailure(
+    failures,
+    !staleDraftPosturePattern.test(section),
+    `spec promoted source-of-truth hierarchy still contains stale draft posture for ${version}.`
+  );
+}
+
 /**
  * @param {{
  *   repoRoot?: string,
@@ -1367,6 +1410,14 @@ export function buildV21SpecFamilyReport({
   }
 
   const specContent = contents['spec'] || '';
+  if (mode === 'promoted') {
+    validatePromotedSourceOfTruthHierarchy(
+      failures,
+      extractSection(specContent, 'source-of-truth hierarchy'),
+      version
+    );
+  }
+
   for (const phrase of profile.requiredSpecSections) {
     recordFailure(failures, hasSection(specContent, phrase), `spec is missing required section containing "${phrase}".`);
   }

packages/protocol/test/spec-family-promotion-posture.test.js

@@ -0,0 +1,64 @@
+import assert from 'node:assert/strict';
+import { copyFileSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import test from 'node:test';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, '..', '..', '..');
+
+const V44_SPEC_FAMILY_FILES = [
+  'BITCODE_SPEC.txt',
+  'BITCODE_SPECIFYING.md',
+  'BITCODE_SPEC_TEMPLATEGUIDE.md',
+  'BITCODE_SPEC_V44.md',
+  'BITCODE_SPEC_V44_DELTA.md',
+  'BITCODE_SPEC_V44_NOTES.md',
+  'BITCODE_SPEC_V44_PARITY_MATRIX.md',
+];
+
+test('promoted spec-family validation rejects stale draft source-of-truth prose', async () => {
+  const protocol = await import('../src/index.js');
+  const tempDir = mkdtempSync(path.join(tmpdir(), 'bitcode-promoted-spec-posture-'));
+
+  try {
+    for (const relativePath of V44_SPEC_FAMILY_FILES) {
+      copyFileSync(path.join(repoRoot, relativePath), path.join(tempDir, relativePath));
+    }
+
+    const specPath = path.join(tempDir, 'BITCODE_SPEC_V44.md');
+    const spec = readFileSync(specPath, 'utf8');
+    const staleSpec = spec.replace(
+      /## V44 source-of-truth hierarchy[\s\S]*?## V44 promotion addendum: canonical posture repair/u,
+      [
+        '## V44 source-of-truth hierarchy',
+        '',
+        '`BITCODE_SPEC.txt` points to `V43` while V44 is draft.',
+        '`BITCODE_SPEC_V43.md` and `BITCODE_SPEC_V43_PROVEN.md` are active canon.',
+        '`BITCODE_SPEC_V44.md`, `BITCODE_SPEC_V44_DELTA.md`,',
+        '`BITCODE_SPEC_V44_NOTES.md`, and `BITCODE_SPEC_V44_PARITY_MATRIX.md` define',
+        'the draft target only on `version/v44` and `v44/gate-*` branches.',
+        '',
+        '## V44 promotion addendum: canonical posture repair',
+      ].join('\n')
+    );
+
+    writeFileSync(specPath, staleSpec);
+
+    const report = protocol.buildV21SpecFamilyReport({
+      repoRoot: tempDir,
+      version: 'V44',
+      mode: 'promoted',
+      currentTarget: 'V44',
+    });
+
+    assert.equal(report.passed, false);
+    assert.ok(
+      report.failures.some((failure) => failure.includes('promoted source-of-truth hierarchy')),
+      `expected promoted source-of-truth failure, got: ${report.failures.join('; ')}`
+    );
+  } finally {
+    rmSync(tempDir, { recursive: true, force: true });
+  }
+});