docs(integration): Phase E §1.4 prereq — BoJ-side observability spec (standards#100)

[hyperpolymath]

Summary

Adds docs/integration/boj-side-observability-spec.md — the contract for the BoJ-side telemetry events and Prometheus metrics that the rollout-runbook §4.2 signals require, plus coordinated edits to the sister spec and the runbook.

The gap this closes: gateway-observability-spec.md §3 currently defers all BoJ-side templates to !OWNER: scaffolded qualifiers, because BoJ has zero telemetry today (elixir/mix.exs carries no Prometheus dep, BojRest.Application mounts no exporter, BojRest.Router emits no :telemetry.execute/3 events). The rollout-runbook §3.1 success criterion 4 ("No X-Trust-Level mismatches in BoJ access logs") and rollback trigger §5.1 row 4 are consequently unobservable via Prometheus.

What lands

New spec — docs/integration/boj-side-observability-spec.md declares:

• Four telemetry events (§1): [:boj_rest, :router, :decision], [:boj_rest, :router, :trust_level_present], [:boj_rest, :http, :response], [:boj_rest, :request, :received].
• Five Prometheus metric prefixes (§2) — the names gateway-observability-spec.md §3 PromQL templates expect.
• Exact BojRest.Router instrumentation sites (§3) with file:line anchors against elixir/lib/boj_rest/router.ex.
• The mix.exs dep (:telemetry_metrics_prometheus_core ~> 1.2), supervisor child, and new BojRest.Telemetry module the wiring PR adds (§4).
• The /metrics exposure policy implication (§5): the new endpoint MUST be governed by a new metrics-get policy rule (internal+stealth-404) — leaking the BoJ scrape externally would defeat stealth_profiles. The scripts/hcg-policy-smoke.sh stealth canary list extends in the same wiring PR.
• The §1.4 prerequisite this spec adds to the runbook (§6) and the wiring PR checklist (§7).

Sister spec edit — gateway-observability-spec.md:

• §3 introduction: drop !OWNER: scaffolded qualifier; anchor templates to the new sister spec.
• §3.1, §3.2, §3.3: each template's "Replace metric name with the BoJ-side equivalent" placeholder removed; queries now name the normative metric.
• §7 References: add the sister spec.
• Header bumped 0.1 → 0.2.

Runbook edit — hcg-tier2-rollout-runbook.md:

• §1.4: new stop-the-rollout checkbox for the BoJ-side observability prerequisite.
• Appendix B: cross-reference the new spec.
• Header bumped 0.7 → 0.8.

What does NOT land here

• The actual mix.exs / application.ex / router.ex wiring. That's a follow-up PR following the spec's §7 checklist. Splitting the contract from the implementation lets the spec land independently and gives the wiring PR an unambiguous target.
• Any change to Trustfile.a2ml tier_2_gateway (still PENDING; flip is the last action per runbook §6.4).
• Any change to existing telemetry on the gateway side.

Scope of edits

File	Change
docs/integration/boj-side-observability-spec.md	New (279 lines).
docs/integration/gateway-observability-spec.md	§3 templates anchored; header bump.
docs/integration/hcg-tier2-rollout-runbook.md	§1.4 new prereq; Appendix B; header bump.

No code, no schemas, no policy YAML touched.

Test plan

• bash scripts/hcg-surface-drift-check.sh — passes (router/policy coverage unchanged).
• bash scripts/hcg-spec-coverage-check.sh — passes (openapi/policy coverage unchanged).
• CI: doc-only diff; no required-gate workflow has a path filter that would skip in a way that blocks merge (per the §"CI / Required Status Checks" pattern documented in .claude/CLAUDE.md).

Channel discipline

Phase E is multi-PR by construction (#226, #228, #229, #230, hcg#38 are prior Phase E slices, none of which closed #100). Per runbook §6.5 (and the channel brief) standards#100 is joint-close-only by the owner. This PR therefore uses Refs not Closes — same convention as the in-flight Phase E PR set.

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

🤖 Generated with Claude Code

---

Generated by Claude Code

[github-actions]

🔍 Hypatia Security Scan

Findings: 218 issues detected

Severity	Count
🔴 Critical	15
🟠 High	132
🟡 Medium	71

⚠️ Action Required: Critical security issues found!

View findings

[
  {
    "reason": "Stale AI session file -- delete",
    "type": "stale",
    "file": "GEMINI.md",
    "action": "delete",
    "rule_module": "root_hygiene",
    "severity": "medium"
  },
  {
    "reason": "Issue in scorecard-enforcer.yml",
    "type": "missing_timeout_minutes",
    "file": "scorecard-enforcer.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "Issue in scorecard-enforcer.yml",
    "type": "scorecard_publish_with_run_step",
    "file": "scorecard-enforcer.yml",
    "action": "split_scorecard_publish_job",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Issue in instant-sync.yml",
    "type": "secret_action_without_presence_gate",
    "file": "instant-sync.yml",
    "action": "peter-evans/repository-dispatch",
    "rule_module": "workflow_audit",
    "severity": "high"
  },
  {
    "reason": "Issue in codeql.yml",
    "type": "codeql_missing_actions_language",
    "file": "codeql.yml",
    "action": "flag",
    "rule_module": "workflow_audit",
    "severity": "medium"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/academic-workflow-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/ephapax-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/bofig-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/fireflag-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  },
  {
    "reason": "TypeScript file detected -- banned language",
    "type": "banned_language_file",
    "file": "/home/runner/work/boj-server/boj-server/cartridges/sanctify-mcp/adapter/mod.ts",
    "action": "flag",
    "rule_module": "cicd_rules",
    "severity": "critical"
  }
]

Powered by Hypatia Neurosymbolic CI/CD Intelligence