Merge pull request #94 from engineeredsoftware/v35/gate-6-documentation-qa-alignment-proofs

V35 Gate 6: Documentation QA Alignment Proofs

Author: geraldarthurdavis

.bitcode/v35-docs-qa-alignment-report.json

@@ -176,6 +176,9 @@ jobs:
               if [ -f scripts/check-v35-gate5-dashboards-alerts-runbooks-incident-escalation.mjs ]; then
                 node scripts/check-v35-gate5-dashboards-alerts-runbooks-incident-escalation.mjs --skip-branch-check
               fi
+              if [ -f scripts/check-v35-gate6-documentation-qa-alignment-proofs.mjs ]; then
+                node scripts/check-v35-gate6-documentation-qa-alignment-proofs.mjs --skip-branch-check
+              fi
             fi
             node scripts/check-v34-gate10-promotion-readiness.mjs --promotion-mode --skip-branch-check
           else
@@ -227,6 +230,7 @@ jobs:
           pnpm --dir packages/protocol exec node --test --test-force-exit test/v35-telemetry-taxonomy-catalog.test.js
           pnpm --dir packages/protocol exec node --test --test-force-exit test/v35-public-docs-usage-guide-catalog.test.js
           pnpm --dir packages/protocol exec node --test --test-force-exit test/v35-operator-runbook-catalog.test.js
+          pnpm --dir packages/protocol exec node --test --test-force-exit test/v35-docs-qa-alignment-report.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`, source-safe `.bitcode/v35-documentation-surface-catalog.json`, source-safe `.bitcode/v35-telemetry-taxonomy-catalog.json`, source-safe `.bitcode/v35-public-docs-usage-guides.json`, source-safe `.bitcode/v35-operator-runbook-catalog.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`, source-safe `.bitcode/v35-telemetry-taxonomy-catalog.json`, source-safe `.bitcode/v35-public-docs-usage-guides.json`, source-safe `.bitcode/v35-operator-runbook-catalog.json`, source-safe `.bitcode/v35-docs-qa-alignment-report.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, public docs usage, 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`
@@ -315,6 +315,29 @@ They must not carry secret values, privileged database key values, provider toke
 The catalog fails closed on missing telemetry event family bindings, missing runbook ids, missing dashboard panels, missing alert thresholds, missing incident classes, missing escalation paths, missing command sequences, missing verification commands, missing proof roots, missing post-incident documentation updates, missing forbidden-data boundaries, missing source roots, secret-shaped markers, protected source disclosure, wallet private material disclosure, raw protected prompts, and unpaid AssetPack source disclosure.
 The artifact is generated by `pnpm run generate:v35-operator-runbook-catalog`, checked by `pnpm run check:v35-operator-runbook-catalog`, closed by `pnpm run check:v35-gate5`, and exported by `@bitcode/protocol` through `buildOperatorRunbookCatalog`.
 
+## V35 DocsQaAlignmentReport canon
+
+Gate 6 materializes `DocsQaAlignmentReport` as package-owned protocol truth.
+The deterministic artifact `.bitcode/v35-docs-qa-alignment-report.json` carries `source-safe-docs-qa-metadata` and proves ten documentation alignment rows:
+
+- `spec_family_alignment`
+- `roadmap_readme_alignment`
+- `generated_artifact_inventory_alignment`
+- `catalog_implementation_alignment`
+- `public_docs_disclosure_alignment`
+- `internal_docs_alignment`
+- `route_docs_alignment`
+- `interface_docs_alignment`
+- `generated_proof_appendix_alignment`
+- `workflow_checker_alignment`
+
+Every row names alignment class, owner, checked sources, expected tokens, observed tokens, stale token blockers, generated artifacts, missing generated artifacts, unsupported disclosure claims, forbidden payload classes, validation command, repair command, fail-closed result, source evidence, and deterministic alignment root.
+Docs QA covers code, SPEC, DELTA, NOTES, PARITY, generated proof posture, generated artifacts, public docs, internal docs, route docs, interface docs, package READMEs, and workflow checkers.
+Docs QA payloads may carry file paths, token names, generated artifact paths, proof roots, and failure codes.
+They must not carry secret values, provider tokens, wallet private material, raw protected prompts, protected source payloads, or unpaid AssetPack source.
+The report fails closed on missing alignment ids, missing source roots, missing expected tokens, missing generated artifacts, unsupported disclosure claims, secret-shaped markers, protected source disclosure, wallet private material disclosure, raw protected prompts, and unpaid AssetPack source disclosure.
+The artifact is generated by `pnpm run generate:v35-docs-qa-alignment-report`, checked by `pnpm run check:v35-docs-qa-alignment-report`, closed by `pnpm run check:v35-gate6`, and exported by `@bitcode/protocol` through `buildDocsQaAlignmentReport`.
+
 ## V35 whole Bitcode operator chain
 
 The V35 operator chain keeps V34 behavior and adds source-safe documentation and telemetry visibility:

BITCODE_SPEC_V35.md

@@ -142,6 +142,9 @@ Closure acceptance:
 - `DocsQaAlignmentReport` checks code, SPEC, DELTA, NOTES, PARITY, generated proof, generated artifacts, public docs, internal docs, route docs, and interface docs;
 - stale tokens, missing source roots, missing generated artifacts, and unsupported disclosure claims fail closed;
 - package scripts and workflows run the docs QA checks.
+- `DocsQaAlignmentReport` is exported by `@bitcode/protocol`, generated into `.bitcode/v35-docs-qa-alignment-report.json` with `source-safe-docs-qa-metadata`, and checked by `pnpm run check:v35-gate6`;
+- rows cover spec family, roadmap/README, generated artifact inventory, package catalog implementations, public docs disclosure, internal docs, route docs, interface docs, generated proof appendix posture, and workflow/checker wiring;
+- docs QA payloads allow file paths, expected token names, observed token names, missing token names, generated artifact paths, proof roots, and failure codes while blocking secrets, provider tokens, wallet private material, raw protected prompts, protected source payloads, and unpaid AssetPack source.
 
 ### Gate 7: Developer Operator Testnet Rollout Guides
 

BITCODE_SPEC_V35_DELTA.md

@@ -61,6 +61,7 @@ Read the system as:
 - Gate 3 closes `TelemetryTaxonomyCatalog` with `.bitcode/v35-telemetry-taxonomy-catalog.json`, `source-safe-telemetry-taxonomy-metadata`, package export `buildTelemetryTaxonomyCatalog`, package test coverage, redaction posture for every event family, ThricifiedGeneration inference telemetry boundaries, and `check:v35-gate3`.
 - Gate 4 closes `PublicDocsUsageGuideCatalog` with `.bitcode/v35-public-docs-usage-guides.json`, `source-safe-public-docs-metadata`, package export `buildPublicDocsUsageGuideCatalog`, package test coverage, public disclosure-limit docs content, and `check:v35-gate4`.
 - Gate 5 closes `OperatorRunbookCatalog` with `.bitcode/v35-operator-runbook-catalog.json`, `source-safe-runbook-metadata`, package export `buildOperatorRunbookCatalog`, package test coverage, dashboard/alert/runbook derivation from telemetry taxonomy rows, incident escalation paths, operator command sequences, forbidden-data boundaries, post-incident documentation update requirements, and `check:v35-gate5`.
+- Gate 6 closes `DocsQaAlignmentReport` with `.bitcode/v35-docs-qa-alignment-report.json`, `source-safe-docs-qa-metadata`, package export `buildDocsQaAlignmentReport`, package test coverage, stale token blockers, generated artifact inventory checks, source-root evidence, unsupported disclosure claim blockers, workflow/checker wiring, and `check:v35-gate6`.
 
 ## Inherited deployment-depth notes
 

BITCODE_SPEC_V35_NOTES.md

@@ -58,7 +58,7 @@ No `_legacy/` source is active source truth.
 | Telemetry taxonomy event schema | Gate 3 | `TelemetryTaxonomyCatalog`, `.bitcode/v35-telemetry-taxonomy-catalog.json`, `packages/protocol/src/canonical/telemetry-taxonomy-catalog.js`, `packages/protocol/test/v35-telemetry-taxonomy-catalog.test.js`, and `check:v35-gate3` | closed | 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 | `PublicDocsUsageGuideCatalog`, `.bitcode/v35-public-docs-usage-guides.json`, `source-safe-public-docs-metadata`, `packages/protocol/src/canonical/public-docs-usage-guide-catalog.js`, `packages/protocol/test/v35-public-docs-usage-guide-catalog.test.js`, public `/docs` disclosure-limit section, and `check:v35-gate4` | closed | Terminal, Protocol, Auxillaries, MCP API, ChatGPT App, BTD, AssetPack ranges, Reads, fees, proof posture, Exchange deferred boundary, and Conversations deferred boundary docs derive from package/SPEC truth. |
 | Dashboards alerts runbooks incident escalation | Gate 5 | `OperatorRunbookCatalog`, `.bitcode/v35-operator-runbook-catalog.json`, `source-safe-runbook-metadata`, `packages/protocol/src/canonical/operator-runbook-catalog.js`, `packages/protocol/test/v35-operator-runbook-catalog.test.js`, dashboard/alert/runbook bindings, incident fixtures, and `check:v35-gate5` | closed | Telemetry events bind to dashboard panels, alert thresholds, incident classes, escalation paths, safe commands, forbidden data, proof roots, repair references, and post-incident docs updates. |
-| Documentation QA alignment proofs | Gate 6 | `DocsQaAlignmentReport`, generated alignment artifact, tests, workflows, and `check:v35-gate6` | drafted | Code, SPEC, DELTA, NOTES, PARITY, generated proofs, generated artifacts, public docs, internal docs, route docs, and interface docs fail closed on drift. |
+| Documentation QA alignment proofs | Gate 6 | `DocsQaAlignmentReport`, `.bitcode/v35-docs-qa-alignment-report.json`, `source-safe-docs-qa-metadata`, `packages/protocol/src/canonical/docs-qa-alignment-report.js`, `packages/protocol/test/v35-docs-qa-alignment-report.test.js`, workflow wiring, and `check:v35-gate6` | closed | Code, SPEC, DELTA, NOTES, PARITY, generated proofs, generated artifacts, public docs, internal docs, route docs, interface docs, package READMEs, and workflow checkers fail closed on drift. |
 | Developer operator testnet rollout guides | Gate 7 | `TestnetRolloutReadinessGuide`, onboarding/operations docs, rehearsal evidence, and `check:v35-gate7` | drafted | Contributors, operators, enterprise readers, depositors, and interface consumers can follow source-safe local/staging-testnet guides. |
 | Telemetry documentation interface integration | Gate 8 | Terminal, Auxillaries, API, MCP API, ChatGPT App, route payloads, and `check:v35-gate8` | drafted | Interfaces expose event ids, docs links, runbook links, proof roots, and redaction posture without protected source leakage. |
 | Local staging telemetry documentation rehearsal | Gate 9 | local/staging rehearsal logs, docs QA output, dashboard/runbook proof roots, and `check:v35-gate9` | drafted | Operators can follow docs and telemetry through local and staging-testnet drills while value-bearing mainnet remains blocked. |
@@ -76,14 +76,15 @@ No `_legacy/` source is active source truth.
 | Gate 3 script | `pnpm run check:v35-gate3` fails closed on stale telemetry taxonomy catalog, missing event families, missing redaction posture, missing proof roots, missing source roots, source-unsafe telemetry payloads, missing package export, missing package test, missing workflow wiring, or missing generated artifact profile binding | closed |
 | Gate 4 script | `pnpm run check:v35-gate4` fails closed on stale public docs usage guides, missing public `/docs` routes, missing source roots, missing disclosure-limit docs content, source-unsafe public payloads, missing package export, missing package test, missing workflow wiring, or missing generated artifact profile binding | closed |
 | Gate 5 script | `pnpm run check:v35-gate5` fails closed on stale operator runbook catalog, missing telemetry event family bindings, missing dashboard panels, missing alert thresholds, missing incident classes, missing escalation paths, missing commands, missing proof roots, source-unsafe runbook payloads, missing package export, missing package test, missing workflow wiring, or missing generated artifact profile binding | closed |
+| Gate 6 script | `pnpm run check:v35-gate6` fails closed on stale docs QA alignment report, missing source roots, stale expected tokens, missing generated artifacts, unsupported disclosure claims, 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 |
 | Telemetry/documentation vocabulary | V35 spec family names `TelemetryTaxonomyCatalog`, `DocumentationSurfaceCatalog`, `DocsQaAlignmentReport`, `OperatorRunbookCatalog`, and `TestnetRolloutReadinessGuide` | drafted |
 | Public docs disclosure boundary | Public docs disclose guidance, measurements, proof posture, fee/right boundaries, readiness states, and source-safe previews, not protected source, raw protected prompts, wallet private material, provider tokens, or unpaid AssetPack source | closed |
 | Telemetry source-safety boundary | Telemetry events carry redaction posture, source-safety class, proof roots, and correlation ids without raw protected prompts or unpaid source | drafted |
 | Dashboard/runbook derivation | Dashboard panels, alert thresholds, runbooks, incident classes, and escalation paths derive from telemetry taxonomy rows | closed |
-| Documentation QA failure posture | Docs QA fails closed on stale tokens, missing source roots, unsupported disclosure claims, and missing generated artifacts | drafted |
+| Documentation QA failure posture | Docs QA fails closed on stale tokens, missing source roots, unsupported disclosure claims, and missing generated artifacts | closed |
 | Testnet rollout guide posture | Rollout guides distinguish local, staging-testnet, public testnet, mainnet-ready dry run, and blocked value-bearing mainnet | drafted |
 | Promotion readiness report | `DocumentationTelemetryPromotionReadinessReport` covers all V35 telemetry/documentation artifacts, proofs, workflows, and active V35 / draft V36 post-promotion posture | drafted |
 
@@ -145,9 +146,11 @@ No `_legacy/` source is active source truth.
 
 | Requirement | Source evidence | Current V35 judgment |
 | --- | --- | --- |
-| Docs QA report planned | `DocsQaAlignmentReport` in SPEC/DELTA/NOTES/PARITY | drafted |
-| Alignment sources named | V35 Gate 6 acceptance criteria | drafted |
-| Fail-closed stale docs posture named | V35 SPEC and notes | drafted |
+| Docs QA report implemented | `packages/protocol/src/canonical/docs-qa-alignment-report.js` exports `buildDocsQaAlignmentReport`, `DOCS_QA_ALIGNMENT_IDS`, and `DOCS_QA_ALIGNMENT_ROWS` | closed |
+| Generated artifact exists | `.bitcode/v35-docs-qa-alignment-report.json` with `source-safe-docs-qa-metadata` | closed |
+| Alignment sources named and checked | report rows cover SPEC, DELTA, NOTES, PARITY, generated proof posture, generated artifacts, public docs, internal docs, route docs, interface docs, package READMEs, and workflows | closed |
+| Fail-closed stale docs posture implemented | stale token blockers, missing source roots, missing generated artifacts, unsupported disclosure claims, and forbidden payload classes are explicit report fields | closed |
+| Gate 6 package and workflow proof | `packages/protocol/test/v35-docs-qa-alignment-report.test.js`, `scripts/check-v35-gate6-documentation-qa-alignment-proofs.mjs`, `.github/workflows/bitcode-gate-quality.yml`, and `package.json` | closed |
 
 ## Gate 7 Parity
 

BITCODE_SPEC_V35_PARITY_MATRIX.md

@@ -34,6 +34,11 @@ V35 Gate 5 now anchors operator action through the package-owned
 dashboard panels, alerts, runbooks, incident classes, escalation paths,
 commands, proof roots, repair references, and post-incident documentation
 updates.
+V35 Gate 6 now anchors documentation QA through the package-owned
+`DocsQaAlignmentReport` and the source-safe generated artifact
+`.bitcode/v35-docs-qa-alignment-report.json`, failing closed on stale tokens,
+missing source roots, missing generated artifacts, unsupported disclosure
+claims, or docs/proof/workflow drift.
 
 The protocol demonstration remains the minimal deterministic reference for the
 same protocol. Commercial code may mount or compare against demonstration