Merge pull request #93 from engineeredsoftware/v35/gate-5-dashboards-alerts-runbooks-incident-escalation

V35 Gate 5: Dashboards Alerts Runbooks Incident Escalation

Author: geraldarthurdavis

.bitcode/v35-operator-runbook-catalog.json

@@ -173,6 +173,9 @@ jobs:
               if [ -f scripts/check-v35-gate4-public-docs-usage-guides.mjs ]; then
                 node scripts/check-v35-gate4-public-docs-usage-guides.mjs --skip-branch-check
               fi
+              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
             fi
             node scripts/check-v34-gate10-promotion-readiness.mjs --promotion-mode --skip-branch-check
           else
@@ -223,6 +226,7 @@ jobs:
           pnpm --dir packages/protocol exec node --test --test-force-exit test/v35-documentation-surface-catalog.test.js
           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 --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`, 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`, 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`
@@ -260,6 +260,7 @@ Telemetry payloads are source-safe metadata only.
 They may carry event ids, correlation ids, proof roots, counts, state enums, policy ids, dashboard panel ids, and runbook ids.
 They must not carry secret values, service key values, provider tokens, wallet private material, raw protected prompts, raw model responses with protected source, protected source payloads, or unpaid AssetPack source.
 The catalog fails closed on missing event families, missing source roots, missing runbook links, missing dashboard panels, missing proof root fields, missing redaction posture, missing correlation ids, 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-telemetry-taxonomy-catalog`, checked by `pnpm run check:v35-telemetry-taxonomy-catalog`, closed by `pnpm run check:v35-gate3`, and exported by `@bitcode/protocol` through `buildTelemetryTaxonomyCatalog`.
 
 ## V35 PublicDocsUsageGuideCatalog canon
 
@@ -286,7 +287,33 @@ Public docs must not expose secret values, provider tokens, wallet private mater
 The settlement boundary is explicit: measurements and proof posture may be previewed before payment, but source-bearing AssetPack contents cross to the reader only after settlement and rights transfer.
 V35 public docs catalog Exchange and Conversations usage while deeper Exchange and website Conversations product depth remains future-canon work.
 The artifact is generated by `pnpm run generate:v35-public-docs-usage-guides`, checked by `pnpm run check:v35-public-docs-usage-guides`, closed by `pnpm run check:v35-gate4`, and exported by `@bitcode/protocol` through `buildPublicDocsUsageGuideCatalog`.
-The artifact is generated by `pnpm run generate:v35-telemetry-taxonomy-catalog`, checked by `pnpm run check:v35-telemetry-taxonomy-catalog`, closed by `pnpm run check:v35-gate3`, and exported by `@bitcode/protocol` through `buildTelemetryTaxonomyCatalog`.
+
+## V35 OperatorRunbookCatalog canon
+
+Gate 5 materializes `OperatorRunbookCatalog` as package-owned protocol truth.
+The deterministic artifact `.bitcode/v35-operator-runbook-catalog.json` carries `source-safe-runbook-metadata` and proves fourteen dashboard, alert, runbook, incident, and escalation rows derived from the fourteen `TelemetryTaxonomyCatalog` event families:
+
+- `runbook.pipeline.execution-repair`
+- `runbook.execution.orphan-repair`
+- `runbook.inference.ptrr-agent-debug`
+- `runbook.inference.generation-redaction`
+- `runbook.tools.policy-denial`
+- `runbook.ledger.reconciliation-repair`
+- `runbook.wallet.signing-failure`
+- `runbook.storage.object-repair`
+- `runbook.interfaces.auth-denial`
+- `runbook.deployment.lane-repair`
+- `runbook.observer.finality-lag`
+- `runbook.repair.failed`
+- `runbook.docs.qa-repair`
+- `runbook.promotion.blocked`
+
+Every row binds a telemetry event family and event ids to a dashboard panel, alert id, alert threshold, runbook id, incident class, severity, escalation path, command sequence, verification commands, safe operator data, forbidden operator data, proof root basis, repair references, post-incident documentation updates, source-safety class, redaction posture, storage target, correlation ids, source roots, replay expectation, and deterministic runbook root.
+Dashboard, alert, runbook, incident, and escalation posture must derive from telemetry taxonomy rows; they must not become dashboard-only assertions or operator folklore.
+Operator runbook payloads may carry event ids, correlation ids, proof roots, state enums, policy ids, dashboard panel ids, runbook ids, and redacted error classes.
+They must not carry secret values, privileged database key values, provider tokens, wallet private material, raw protected prompts, raw model responses with protected source, protected source payloads, or unpaid AssetPack source.
+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 whole Bitcode operator chain
 

BITCODE_SPEC_V35.md

@@ -129,6 +129,9 @@ Closure acceptance:
 - `OperatorRunbookCatalog` rows bind telemetry events to dashboard panels, alert thresholds, incident classes, escalation paths, safe commands, forbidden data, and post-incident docs updates;
 - dashboard and alert definitions derive from `TelemetryTaxonomyCatalog`;
 - incident evidence is source-safe and proof-rooted.
+- `OperatorRunbookCatalog` is exported by `@bitcode/protocol`, generated into `.bitcode/v35-operator-runbook-catalog.json` with `source-safe-runbook-metadata`, and checked by `pnpm run check:v35-gate5`;
+- every runbook row binds one telemetry event family to dashboard panel id, alert id, threshold, incident class, escalation path, command sequence, verification command, proof root basis, repair reference, post-incident docs update, source roots, and deterministic runbook root;
+- operator payloads allow source-safe event ids, correlation ids, proof roots, state enums, policy ids, dashboard panel ids, runbook ids, and redacted error classes while blocking secrets, provider tokens, wallet private material, raw protected prompts, protected source payloads, and unpaid AssetPack source.
 
 ### Gate 6: Documentation QA Alignment Proofs
 

BITCODE_SPEC_V35_DELTA.md

@@ -60,6 +60,7 @@ Read the system as:
 - 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`.
 - 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`.
 
 ## Inherited deployment-depth notes
 

BITCODE_SPEC_V35_NOTES.md

@@ -57,7 +57,7 @@ No `_legacy/` source is active source truth.
 | 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`, `.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`, 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. |
+| 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. |
 | 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. |
@@ -75,13 +75,14 @@ No `_legacy/` source is active source truth.
 | 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 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-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 | 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 |
 | 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 |
@@ -134,9 +135,11 @@ No `_legacy/` source is active source truth.
 
 | Requirement | Source evidence | Current V35 judgment |
 | --- | --- | --- |
-| Operator runbook catalog planned | `OperatorRunbookCatalog` in SPEC/DELTA/NOTES/PARITY | drafted |
-| Dashboard and alert derivation planned | Gate 5 acceptance criteria | drafted |
-| Incident escalation boundaries named | V35 SPEC and notes | drafted |
+| Operator runbook catalog implemented | `packages/protocol/src/canonical/operator-runbook-catalog.js` exports `buildOperatorRunbookCatalog`, `OPERATOR_RUNBOOK_IDS`, and `OPERATOR_RUNBOOK_ROWS` | closed |
+| Generated artifact exists | `.bitcode/v35-operator-runbook-catalog.json` with `source-safe-runbook-metadata` | closed |
+| Dashboard and alert derivation implemented | every catalog row derives `dashboardPanel`, `alertThreshold`, and `runbookId` from `TelemetryTaxonomyCatalog` rows | closed |
+| Incident escalation boundaries implemented | every catalog row names incident class, escalation path, command sequence, verification commands, proof root basis, repair references, forbidden data, and post-incident documentation updates | closed |
+| Gate 5 package and workflow proof | `packages/protocol/test/v35-operator-runbook-catalog.test.js`, `scripts/check-v35-gate5-dashboards-alerts-runbooks-incident-escalation.mjs`, `.github/workflows/bitcode-gate-quality.yml`, and `package.json` | closed |
 
 ## Gate 6 Parity
 

BITCODE_SPEC_V35_PARITY_MATRIX.md

@@ -28,6 +28,12 @@ V35 Gate 4 now anchors public usage guidance through the package-owned
 `.bitcode/v35-public-docs-usage-guides.json`, including the public docs
 disclosure boundary that blocks protected source, raw protected prompts, wallet
 private material, provider tokens, and unpaid AssetPack source.
+V35 Gate 5 now anchors operator action through the package-owned
+`OperatorRunbookCatalog` and the source-safe generated artifact
+`.bitcode/v35-operator-runbook-catalog.json`, binding telemetry-derived
+dashboard panels, alerts, runbooks, incident classes, escalation paths,
+commands, proof roots, repair references, and post-incident documentation
+updates.
 
 The protocol demonstration remains the minimal deterministic reference for the
 same protocol. Commercial code may mount or compare against demonstration