docs(integration): Phase E observability spec (standards#100) (#226)

## Summary

Phase E §3 traffic-shift sign-off has four success criteria (rollout
runbook §3.1). The runbook §4 names the signals that gate sign-off at
the human level — p99 latency, throughput, circuit-breaker state, 5xx
rate, policy reload counter, trust-level decision distribution, plus
three BoJ-side signals — but stops short of giving the on-call a query
they can paste. This PR adds
`docs/integration/gateway-observability-spec.md` to fill that gap.

For every runbook §4.1 + §4.2 signal, the spec wires:

1. The **telemetry event** emitted by the gateway (audit document §5 /
§1.6).
2. The **Prometheus metric** the `telemetry_metrics_prometheus_core`
reporter exports for that event, anchored to the canonical declaration
in `http-capability-gateway/lib/http_capability_gateway/application.ex`
`telemetry_metrics/0` (lines 259–296).
3. A **PromQL query template** the operator pastes verbatim into a
dashboard panel or alert rule.
4. An **alert threshold** anchored to a canonical source — the rollback
runbook §5.1 trigger value, the perf contract tolerance ratio, or the
load-profile §2 SLO budget. Absolute-µs values that depend on Phase D-4
baseline collection are left as `${BASELINE_*}` placeholders with the
lookup site (`bench/baseline.json` after `_status` flips to `active`)
named — not invented numbers.

§5 closes the loop with a table mapping every runbook §5.1 rollback
trigger to the PromQL alert rule in this spec, plus three follow-up gaps
surfaced honestly:

- **Circuit-breaker state** — no dedicated telemetry event today; the
503 spike + log inspection is the interim signal. Spec flags
`[:http_capability_gateway, :circuit_breaker, :state_change]` as a
post-Phase-E gateway follow-up.
- **Policy reload counter** — logged via `Logger.info`, not telemetry.
Treat as log-based until the event is added.
- **VeriSimDB write failures** — cast-only (audit §4), no metric surface
today. Phase E §1.3 already lists VeriSimDB integration as an `!OWNER:`
confirmation; the metric-side consequence is recorded here.

Edits the rollout runbook §4 lead-in and Appendix B cross-reference list
to point at the spec, so an operator landing in §4 can find the queries
without grep. No changes to the §4 signal list itself or to any
§1/§3/§5/§6 procedure — the runbook stays normative; the spec is its
declarative half.

## What this PR does NOT do

- Does not invent absolute percentile budgets (those live in
`bench/baseline.json` after D-4).
- Does not commit a dashboard URL (the `!OWNER:` rows in runbook §4.3
stand).
- Does not pre-empt the §6.4 Trustfile flip (`tier_2_gateway.status`
stays `PENDING`).
- Per single-lane HCG channel discipline (pattern set in
http-capability-gateway PRs #14, #22, #26, #30, #38 and boj-server PRs
#168, #173, #224): joint-close is owner-only. This PR **refs but does
not close** `standards#100`.

## Test plan

- [ ] Review `docs/integration/gateway-observability-spec.md` end-to-end
— verify the cited line numbers in
`http-capability-gateway/lib/http_capability_gateway/application.ex`
(259–296) and `lib/http_capability_gateway/gateway.ex` (228–232, 411)
match the current gateway main (commit `46116cf` at PR open time).
- [ ] Verify the metric naming convention
(`http_capability_gateway_<event>_<measurement>_<suffix>` with `_total`
on counters and `_bucket`/`_count`/`_sum` on distributions) matches
`TelemetryMetricsPrometheus.Core.scrape()` output against a locally
running gateway. If the naming convention diverges from this spec, the
spec is wrong — open a fix-up PR.
- [ ] Verify the rollout runbook §4 back-link renders correctly in
GitHub's markdown viewer.
- [ ] Verify no Hypatia / governance / spdx gates fire on the new file
(matches the existing `gateway-load-profile.md` MPL-2.0 + SPDX header
shape).

Refs hyperpolymath/standards#91
Refs hyperpolymath/standards#100

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---
_Generated by [Claude
Code](https://claude.ai/code/session_01MkuwduQrd7anDHzGNZhvGj)_

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

Author: hyperpolymath