Merge pull request #90 from engineeredsoftware/v35/gate-2-documentation-surface-catalog

V35 Gate 2: Documentation Surface Catalog

Author: geraldarthurdavis

.bitcode/v35-documentation-surface-catalog.json

@@ -164,6 +164,9 @@ jobs:
             if [ -f BITCODE_SPEC_V35.md ]; then
               node scripts/check-bitcode-spec-family.mjs --version V35 --mode draft --current-target V34
               node scripts/check-v35-gate1-telemetry-docs-roadmap-opening.mjs --skip-branch-check
+              if [ -f scripts/check-v35-gate2-documentation-surface-catalog.mjs ]; then
+                node scripts/check-v35-gate2-documentation-surface-catalog.mjs --skip-branch-check
+              fi
             fi
             node scripts/check-v34-gate10-promotion-readiness.mjs --promotion-mode --skip-branch-check
           else
@@ -211,6 +214,7 @@ jobs:
           pnpm --filter @bitcode/btd test -- --runTestsByPath __tests__/deployment-promotion-readiness-report.test.ts
           pnpm --filter @bitcode/btd test -- --runTestsByPath __tests__/v32-testnet-mainnet-readiness-rehearsal.test.ts
           pnpm --dir packages/protocol exec node --test --test-force-exit test/v32-promotion-proof-generation.test.js
+          pnpm --dir packages/protocol exec node --test --test-force-exit test/v35-documentation-surface-catalog.test.js
           pnpm --filter @bitcode/api exec jest --config jest.config.cjs --runTestsByPath src/routes/__tests__/btd-crypto.test.ts --runInBand
           pnpm --filter @bitcode/api exec jest --config jest.config.cjs --runTestsByPath src/routes/__tests__/auxillaries-contract.test.ts --runInBand
           pnpm --dir packages/executions-mcp/src/mcp-server run test:mcp -- --runTestsByPath src/__tests__/unit/auth.test.ts --runInBand

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

@@ -7,7 +7,7 @@
 - Current canonical/latest target: `V34`
 - Prior canonical anchor: `BITCODE_SPEC_V34.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V34_PROVEN.md`
-- Generated structured artifact inventory: draft `.bitcode/v35-spec-family-report.json`, draft `.bitcode/v35-canonical-input-report.json`, future source-safe V35 telemetry/documentation artifacts, and `BITCODE_SPEC_V35_PROVEN.md` only after V35 promotion
+- Generated structured artifact inventory: draft `.bitcode/v35-spec-family-report.json`, draft `.bitcode/v35-canonical-input-report.json`, source-safe `.bitcode/v35-documentation-surface-catalog.json`, future source-safe V35 telemetry/documentation artifacts, and `BITCODE_SPEC_V35_PROVEN.md` only after V35 promotion
 - Source parity state: V35 source parity opens with Gate 1 and will close telemetry taxonomy, documentation surface, dashboard/runbook, documentation QA, onboarding, integration, rehearsal, and promotion-readiness gates before canonical promotion
 - Active canonical pointer during draft opening: `BITCODE_SPEC.txt` -> `V34`
 - Notes companion: `BITCODE_SPEC_V35_NOTES.md`
@@ -212,6 +212,28 @@ V35 closes through ten gates:
 9. **Gate 9: Local Staging Telemetry Documentation Rehearsal** rehearses local and staging-testnet telemetry/docs visibility, dashboard/runbook paths, docs QA, and source-safe proof roots.
 10. **Gate 10: V35 Promotion Readiness** generates V35 telemetry/documentation proof artifacts, promotion readiness, active V35 / draft V36 posture, and canonical promotion support.
 
+## V35 DocumentationSurfaceCatalog canon
+
+Gate 2 materializes `DocumentationSurfaceCatalog` as package-owned protocol truth.
+The deterministic artifact `.bitcode/v35-documentation-surface-catalog.json` carries `source-safe-documentation-surface-metadata` and proves twelve required documentation surface rows:
+
+- `canonical_spec_family`
+- `roadmap_contributor_governance`
+- `internal_codebase_docs`
+- `public_docs_surface`
+- `package_readmes`
+- `route_api_docs`
+- `api_interface_docs`
+- `generated_artifact_docs`
+- `deployment_operations_docs`
+- `telemetry_observability_docs`
+- `demonstration_docs`
+- `security_boundary_docs`
+
+Every row names audience, owner, disclosure class, source roots, linked spec sections, linked generated artifacts, route or package bindings, proof coverage, forbidden content, freshness checks, and deterministic row root.
+The catalog fails closed on missing source roots, stale source roots, `_legacy/` source roots, secret-shaped values, unsupported public disclosure, protected source, wallet private material, provider tokens, raw protected prompts, and unpaid AssetPack source.
+The artifact is generated by `pnpm run generate:v35-documentation-surface-catalog`, checked by `pnpm run check:v35-documentation-surface-catalog`, closed by `pnpm run check:v35-gate2`, and exported by `@bitcode/protocol` through `buildDocumentationSurfaceCatalog`.
+
 ## V35 whole Bitcode operator chain
 
 The V35 operator chain keeps V34 behavior and adds source-safe documentation and telemetry visibility:

BITCODE_SPEC_V35.md

@@ -7,7 +7,7 @@
 - Current canonical/latest target: `V34`
 - Prior canonical anchor: `BITCODE_SPEC_V34.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V34_PROVEN.md`
-- Generated structured artifact inventory: draft `.bitcode/v35-spec-family-report.json`, draft `.bitcode/v35-canonical-input-report.json`, future source-safe V35 telemetry/documentation artifacts, and `BITCODE_SPEC_V35_PROVEN.md` only after V35 promotion
+- Generated structured artifact inventory: draft `.bitcode/v35-spec-family-report.json`, draft `.bitcode/v35-canonical-input-report.json`, source-safe `.bitcode/v35-documentation-surface-catalog.json`, future source-safe V35 telemetry/documentation artifacts, and `BITCODE_SPEC_V35_PROVEN.md` only after V35 promotion
 - Source parity state: V35 opens source parity for telemetry taxonomy, documentation surfaces, dashboard/runbook, documentation QA, onboarding, integration, rehearsal, and promotion-readiness gates
 - Spec companion: `BITCODE_SPEC_V35.md`
 - Notes companion: `BITCODE_SPEC_V35_NOTES.md`
@@ -82,6 +82,13 @@ Closure acceptance:
 - every docs surface names audience, owner, disclosure class, source roots, generated artifacts, spec links, test coverage, and freshness checks;
 - source-bearing material, secrets, wallet private material, and unpaid AssetPack contents remain blocked from public docs.
 
+Gate 2 closure implementation:
+
+- `@bitcode/protocol` exports `DocumentationSurfaceCatalog` support through `buildDocumentationSurfaceCatalog`;
+- `.bitcode/v35-documentation-surface-catalog.json` records twelve source-safe documentation rows under `source-safe-documentation-surface-metadata`;
+- `pnpm run check:v35-documentation-surface-catalog` verifies artifact freshness and source roots;
+- `pnpm run check:v35-gate2` verifies package source, generated artifact, package tests, workflows, docs, parity, and roadmap advancement.
+
 ### Gate 3: Telemetry Taxonomy Event Schema And Redaction
 
 Gate 3 defines source-safe event law.

BITCODE_SPEC_V35_DELTA.md

@@ -7,7 +7,7 @@
 - Current canonical/latest target: `V34`
 - Prior canonical anchor: `BITCODE_SPEC_V34.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V34_PROVEN.md`
-- Generated structured artifact inventory: draft `.bitcode/v35-spec-family-report.json`, draft `.bitcode/v35-canonical-input-report.json`, future source-safe V35 telemetry/documentation artifacts, and `BITCODE_SPEC_V35_PROVEN.md` only after V35 promotion
+- Generated structured artifact inventory: draft `.bitcode/v35-spec-family-report.json`, draft `.bitcode/v35-canonical-input-report.json`, source-safe `.bitcode/v35-documentation-surface-catalog.json`, future source-safe V35 telemetry/documentation artifacts, and `BITCODE_SPEC_V35_PROVEN.md` only after V35 promotion
 - Source parity state: V35 opens source parity for telemetry taxonomy, documentation surfaces, dashboard/runbook, documentation QA, onboarding, integration, rehearsal, and promotion-readiness gates
 - Scope: V35 draft notes for telemetry and documentation depth over promoted V34 deployment canon
 - Last fully realized canonical target preserved in source: `V34`
@@ -56,6 +56,7 @@ Read the system as:
 - `OperatorRunbookCatalog` binds dashboards, alerts, incidents, escalation, repair commands, and post-incident documentation updates to telemetry taxonomy rows.
 - `TestnetRolloutReadinessGuide` carries contributor, operator, enterprise reader, depositor, and interface consumer paths for local and staging-testnet use.
 - V35 public docs can expose measurements, proof posture, fee/right boundaries, setup steps, and known blockers; they cannot expose secrets, wallet private material, protected source, raw prompts containing protected data, or unpaid AssetPack source.
+- Gate 2 closes `DocumentationSurfaceCatalog` with `.bitcode/v35-documentation-surface-catalog.json`, `source-safe-documentation-surface-metadata`, package export `buildDocumentationSurfaceCatalog`, package test coverage, and `check:v35-gate2`.
 
 ## Inherited deployment-depth notes
 

BITCODE_SPEC_V35_NOTES.md

@@ -7,7 +7,7 @@
 - Current canonical/latest target: `V34`
 - Prior canonical anchor: `BITCODE_SPEC_V34.md`
 - Prior generated proof appendix: `BITCODE_SPEC_V34_PROVEN.md`
-- Generated structured artifact inventory: draft `.bitcode/v35-spec-family-report.json`, draft `.bitcode/v35-canonical-input-report.json`, future source-safe V35 telemetry/documentation artifacts, and `BITCODE_SPEC_V35_PROVEN.md` only after V35 promotion
+- Generated structured artifact inventory: draft `.bitcode/v35-spec-family-report.json`, draft `.bitcode/v35-canonical-input-report.json`, source-safe `.bitcode/v35-documentation-surface-catalog.json`, future source-safe V35 telemetry/documentation artifacts, and `BITCODE_SPEC_V35_PROVEN.md` only after V35 promotion
 - Source parity state: V35 opens source parity for telemetry taxonomy, documentation surfaces, dashboard/runbook, documentation QA, onboarding, integration, rehearsal, and promotion-readiness gates
 - Spec companion: `BITCODE_SPEC_V35.md`
 - Notes companion: `BITCODE_SPEC_V35_NOTES.md`
@@ -54,7 +54,7 @@ No `_legacy/` source is active source truth.
 | --- | --- | --- | --- | --- |
 | Draft family and branch posture | Gate 1 | `BITCODE_SPEC_V35.md`, DELTA, NOTES, PARITY, `BITCODE_SPEC.txt`, branch `v35/gate-1-telemetry-docs-roadmap-opening` | drafted | V35 family validates in draft mode over active V34 and `check:v35-gate1` passes. |
 | Roadmap truth | Gate 1 | `SPECIFICATIONS_ROADMAP.md`, README, PR template, workflow posture | drafted | Roadmap states V34 active, V35 draft, and coherent V36-V37 responsibilities. |
-| Documentation surface catalog | Gate 2 | `DocumentationSurfaceCatalog`, generated docs surface artifact, tests, and `check:v35-gate2` | drafted | Internal codebase docs, public `/docs`, package docs, route docs, generated artifact docs, API/interface docs, owners, freshness checks, and disclosure classes have package-owned rows. |
+| Documentation surface catalog | Gate 2 | `DocumentationSurfaceCatalog`, `.bitcode/v35-documentation-surface-catalog.json`, `packages/protocol/src/canonical/documentation-surface-catalog.js`, `packages/protocol/test/v35-documentation-surface-catalog.test.js`, and `check:v35-gate2` | closed | Internal codebase docs, public `/docs`, package docs, route docs, generated artifact docs, API/interface docs, owners, freshness checks, and disclosure classes have package-owned rows. |
 | Telemetry taxonomy event schema | Gate 3 | `TelemetryTaxonomyCatalog`, generated telemetry taxonomy artifact, tests, and `check:v35-gate3` | drafted | Pipeline, execution, PTRR agent, ThricifiedGeneration, tool, ledger, wallet, storage, interface, deployment, observer, repair, docs QA, and promotion events are source-safe and proof-rooted. |
 | Public docs usage guides | Gate 4 | public `/docs`, internal docs roots, package docs, source-safe examples, and `check:v35-gate4` | drafted | Terminal, Protocol, Auxillaries, MCP API, ChatGPT App, BTD, AssetPack ranges, Reads, fees, and proof posture docs derive from package/SPEC truth. |
 | Dashboards alerts runbooks incident escalation | Gate 5 | `OperatorRunbookCatalog`, dashboard/runbook bindings, incident fixtures, and `check:v35-gate5` | drafted | Telemetry events bind to dashboard panels, alert thresholds, incident classes, escalation paths, safe commands, forbidden data, and post-incident docs updates. |
@@ -72,6 +72,7 @@ No `_legacy/` source is active source truth.
 | Gate branch pattern | V35 work happens on `version/v35` or `v35/gate-N-*` branches | drafted |
 | Spec-family shape | V35 SPEC, DELTA, NOTES, and PARITY satisfy the full spec-family checker | drafted |
 | Gate 1 script | `pnpm run check:v35-gate1` fails closed on stale posture, missing roadmap truth, or missing telemetry/documentation scope | drafted |
+| Gate 2 script | `pnpm run check:v35-gate2` fails closed on stale documentation surface catalog, missing source roots, source-unsafe disclosure, missing package export, missing package test, missing workflow wiring, or missing generated artifact profile binding | closed |
 | Gate-quality workflow | Gate workflow validates V34 active / V35 draft posture and the V35 Gate 1 checker | drafted |
 | Canon-quality workflow | Canon workflow validates promoted V34 canon, V35 draft family when present, and V34/V35 posture | drafted |
 | Package docs | README, protocol package README, demonstration README, and PR template state V34 active / V35 draft workflow | drafted |
@@ -101,9 +102,11 @@ No `_legacy/` source is active source truth.
 
 | Requirement | Source evidence | Current V35 judgment |
 | --- | --- | --- |
-| Documentation surface catalog planned | `DocumentationSurfaceCatalog` in SPEC/DELTA/NOTES/PARITY | drafted |
-| Public/internal docs scope named | V35 SPEC, README, roadmap, and notes | drafted |
-| Disclosure classes planned | V35 Gate 2 acceptance criteria | drafted |
+| Documentation surface catalog implemented | `packages/protocol/src/canonical/documentation-surface-catalog.js` exports `buildDocumentationSurfaceCatalog` and required surface ids | closed |
+| Generated artifact exists | `.bitcode/v35-documentation-surface-catalog.json` with `source-safe-documentation-surface-metadata` | closed |
+| Public/internal docs scope named | Catalog rows include `public_docs_surface`, `internal_codebase_docs`, `package_readmes`, `route_api_docs`, `api_interface_docs`, and `generated_artifact_docs` | closed |
+| Disclosure classes enforced | Catalog rows include disclosure classes, forbidden content, freshness checks, source roots, generated artifacts, and row roots | closed |
+| Gate 2 package and workflow proof | `packages/protocol/test/v35-documentation-surface-catalog.test.js`, `scripts/check-v35-gate2-documentation-surface-catalog.mjs`, `package.json`, and `.github/workflows/bitcode-gate-quality.yml` | closed |
 
 ## Gate 3 Parity
 

BITCODE_SPEC_V35_PARITY_MATRIX.md

@@ -17,6 +17,9 @@ V35 closure focuses on telemetry and documentation depth over promoted V34:
 internal codebase docs, public `/docs`, telemetry taxonomy, dashboards, alert
 runbooks, incident response, operator escalation, documentation QA, developer
 onboarding, operator guides, and testnet-rollout readiness.
+V35 Gate 2 now anchors documentation surfaces through the package-owned
+`DocumentationSurfaceCatalog` and the source-safe generated artifact
+`.bitcode/v35-documentation-surface-catalog.json`.
 
 The protocol demonstration remains the minimal deterministic reference for the
 same protocol. Commercial code may mount or compare against demonstration

README.md

@@ -5,7 +5,7 @@
 - Current active canonical pointer: `BITCODE_SPEC.txt` -> `V34`
 - Current active canon: `BITCODE_SPEC_V34.md`
 - Current draft target: `BITCODE_SPEC_V35.md`
-- Current working gate: V35 Gate 1 Telemetry Documentation Roadmap And Spec Opening, following promoted V34 Deployment Depth.
+- Current working gate: V35 Gate 3 Telemetry Taxonomy Event Schema And Redaction, following the closed V35 Documentation Surface Catalog gate.
 - Latest closed version: V34 Deployment Depth, which promoted host capabilities, environment lanes, distributed executions, storage posture, secret rotation, migration approvals, observers, repair jobs, rollback/upgrade playbooks, local/staging-testnet deployment rehearsal, and V34 promotion readiness.
 - Recent V34 closure anchor: V34 Gate 10 Promotion Readiness generated V34 proof support, promoted `BITCODE_SPEC.txt` to `V34`, prepared V34 active / V35 draft runtime posture, and closed deployment-depth canon.
 - V34 Gate 2 closure anchor: deployment-depth now owns package-backed `DeploymentHostCapabilityCatalog` and `EnvironmentLaneContract` source, deterministic `.bitcode/v34-deployment-host-capability-catalog.json` and `.bitcode/v34-environment-lane-contracts.json`, and visible `value-bearing-mainnet` blocking through `blocked_future_canon_required`.
@@ -18,6 +18,7 @@
 - V34 Gate 9 closure anchor: deployment-depth now owns package-backed `DeploymentReadinessRehearsal` source, deterministic `.bitcode/v34-local-staging-testnet-deployment-rehearsal.json`, local full-stack deployment rehearsal, staging-testnet full-stack deployment rehearsal, value-bearing mainnet blocked rehearsal, Terminal, public API, MCP API, ChatGPT App, Reading pipeline execution receipts, settlement/finality simulation, storage posture, repair posture, source-safe logs, proof-rooted screenshots or logs, validation commands, proof roots, and no secret values serialization coverage.
 - V34 Gate 10 closure anchor: deployment-depth now owns package-backed `DeploymentPromotionReadinessReport` source, deterministic `.bitcode/v34-promotion-readiness-report.json`, V34 promotion command planning, generated appendix support through `BITCODE_SPEC_V34_PROVEN.md`, V34 canon promotion workflow support, gate/canon workflow postures, source-safe deployment artifact evidence, direct-main push denial, and active V34 / draft V35 post-promotion readiness.
 - V35 Gate 1 opening anchor: telemetry/documentation depth opens over promoted V34 with V35 SPEC, DELTA, NOTES, and PARITY files, `check:v35-gate1`, V34 active / V35 draft posture, and a ten-gate plan for documentation surfaces, telemetry taxonomy, public docs, dashboards/runbooks/incidents, documentation QA, onboarding/testnet guides, interface integration, rehearsal, and promotion readiness.
+- V35 Gate 2 closure anchor: telemetry/documentation depth now owns package-backed `DocumentationSurfaceCatalog` source, deterministic `.bitcode/v35-documentation-surface-catalog.json`, `source-safe-documentation-surface-metadata`, public `/docs`, internal docs, package docs, route docs, generated artifact docs, API/interface docs, owner/freshness/disclosure posture, package tests, workflow wiring, and `check:v35-gate2`.
 - Purpose: concise running index of Bitcode/ENGI specification history, current work, and planned work.
 
 This roadmap is not an active system specification.

SPECIFICATIONS_ROADMAP.md

@@ -1,11 +1,12 @@
 # Bitcode Internal Notes
 
-Status: non-canonical scratch documentation. The active canonical system specification is `BITCODE_SPEC_V27.md`; these notes are useful only insofar as they help draft, implement, or verify the active SPEC family or the explicitly opened draft-target family.
+Status: non-canonical internal documentation. The active canonical system specification pointer is `BITCODE_SPEC.txt` -> `V34`; V35 is the active draft-target family for telemetry and documentation depth. These notes are useful only insofar as they help draft, implement, or verify the active SPEC family or the explicitly opened draft-target family.
 
 ## Rules
 
 - Do not treat this directory as canonical truth.
 - Promote requirements into the active SPEC/PARITY/proof family, or into the explicitly opened draft-target SPEC family, before relying on them as requirements.
+- Keep internal docs registered through `DocumentationSurfaceCatalog` when they become gate, operator, route, package, or proof dependencies.
 - Keep note filenames and content Bitcode-only.
 - Prefer Read, fit, AssetPack, shares, Finish, delivery mechanism, Terminal, Exchange, Protocol, proof, and settlement vocabulary.
 - Treat compatibility source names as implementation corridors, not product vocabulary.