Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
feat(phase-12): observability + governance (completes the 0-12 phase checklist) (#437)
Beenu Arora04685a86e9bd
diff --git a/.github/workflows/governance.yml b/.github/workflows/governance.ymlnew file mode 100644index 000000000..d47cfafde--- /dev/null+++ b/.github/workflows/governance.yml@@ -0,0 +1,62 @@+name: Governance + SLOs++# Phase 12 (world-class program) — two cheap completeness gates:+# slos — every service under services/ has an SLO or exempt entry in+# docs/operations/slos.yaml (a new service can't ship without+# declaring its reliability posture).+# governance — the governance surface (GOVERNANCE.md, MAINTAINERS.md,+# SECURITY.md, CODE_OF_CONDUCT.md, TRADEMARK.md, the DCO section+# in CONTRIBUTING.md, SLOs, observability doc) exists and is+# non-trivial, so it can't silently rot.++on:+ push:+ branches: [main]+ paths:+ - "services/**"+ - "docs/operations/slos.yaml"+ - "docs/operations/observability.md"+ - "GOVERNANCE.md"+ - "MAINTAINERS.md"+ - "CONTRIBUTING.md"+ - "SECURITY.md"+ - "CODE_OF_CONDUCT.md"+ - "TRADEMARK.md"+ - "scripts/check_slos.py"+ - "scripts/check_governance.py"+ - ".github/workflows/governance.yml"+ pull_request:+ paths:+ - "services/**"+ - "docs/operations/slos.yaml"+ - "docs/operations/observability.md"+ - "GOVERNANCE.md"+ - "MAINTAINERS.md"+ - "CONTRIBUTING.md"+ - "SECURITY.md"+ - "CODE_OF_CONDUCT.md"+ - "TRADEMARK.md"+ - "scripts/check_slos.py"+ - "scripts/check_governance.py"+ - ".github/workflows/governance.yml"+ workflow_dispatch:++permissions:+ contents: read++jobs:+ governance:+ name: SLO coverage + governance completeness+ runs-on: ubuntu-latest+ timeout-minutes: 5+ steps:+ - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7+ - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6+ with:+ python-version: "3.12"+ - name: Install deps+ run: pip install --quiet pyyaml+ - name: SLO coverage gate+ run: python3 scripts/check_slos.py --print+ - name: Governance completeness gate+ run: python3 scripts/check_governance.pydiff --git a/CHANGELOG.md b/CHANGELOG.mdindex 2c445bccd..c15bbccb3 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0### Added+- **Phase 12 — observability + governance (completes the World-Class Hardening Program's 0–12 phase checklist).** Two halves of "run this next to your crown jewels": (1) **Observability** — every service under `services/` declares its reliability posture in `docs/operations/slos.yaml` (availability + p95 latency + golden signals; all 18 services covered — 16 SLOs + 2 exempt), gated by `scripts/check_slos.py` so a new service can't ship without an SLO. `docs/operations/observability.md` documents the four golden signals and the single OpenTelemetry trace that spans `ingest → fusion → realtime → api → agents → actions`. (2) **Governance** — new `GOVERNANCE.md` (roles, lazy-consensus decision-making, the maintainer path, and an explicit vendor-neutral-home intent), `MAINTAINERS.md`, and a **Developer Certificate of Origin** sign-off requirement added to `CONTRIBUTING.md`. `scripts/check_governance.py` + `governance.yml` gate that the governance surface (governance/maintainers/security/CoC/trademark/DCO/SLOs/observability) exists and is non-trivial, so it can't silently rot. With this, all 13 phases (0–12) have landed; the claim-to-gate matrix stands at **15 GATED / 11 PARTIAL / 1 NO GATE** (the last NO GATE, wet-eval live-agent tables, needs a budgeted live run — Phase 4c).- **Phase 11 — OpenAPI breaking-change gate.** `check-openapi.yml` proved the spec matches the code (drift) but had **no breaking-change semantics** — a PR could delete an endpoint, remove a response field, tighten a request body, or drop an enum value with every check green while every generated SDK client silently broke (the reality-audit `NO GATE` row). New `scripts/openapi_diff.py` (pyyaml-only) classifies the changes between two specs as breaking vs non-breaking *from an existing client's perspective*: removed path/operation/schema/property, changed property type signature, optional→required, a new required field on a request-shaped schema, a removed enum value, or a new required parameter. New `openapi-breaking.yml` diffs the PR's `docs/openapi.yaml` against the base branch and fails on any breaking change; a deliberate breaking release ships with a version bump + a CHANGELOG BREAKING note and `--allow-breaking`. 15 detector tests (`tests/test_openapi_diff.py`) prove every breaking class is caught **and** that safe additive changes (new path, new optional field, new enum value, new response field) are *not* flagged — a breaking-change gate that cries wolf gets disabled. Claim-to-gate matrix: "OpenAPI stability for 3 SDKs + MCP" NO GATE → GATED, and the **ratchet ceiling lowered 2 → 1** (15 GATED / 11 PARTIAL / 1 NO GATE — only the wet-eval live-agent scoreboard tables remain, closing in Phase 4c with a budgeted live run). Per-language SDK generated-client contract-drift is tracked as 11b.- **Phase 10 — connector runtime-contract conformance suite + published matrix.** The reality audit left the "live Test connection" click-and-connect claim with **NO gate at all**, and the schema/vault claim only partially gated. New `scripts/connector_conformance.py` + `services/connectors/tests/test_conformance.py` gate the runtime contract across **all 69 connectors**: every connector must implement `test_connection` as an async coroutine (the contract behind the "live Test connection" button), implement `fetch_alerts` as an async coroutine, declare only valid `Capability` verbs, and **mark every secret-shaped field `type="secret"`** — a field named `api_key`/`token`/`password` rendered as a plain `string` would be stored outside the vault, the exact leak this check prevents. The published `docs/connectors/conformance-matrix.md` (69/69 conform) is drift-gated by `--check`, so a new connector cannot land without conforming and the matrix can't diverge from the registry. Claim-to-gate matrix: "Connectors: live Test connection" NO GATE → PARTIAL, and the **ratchet ceiling lowered 3 → 2** (14 GATED / 11 PARTIAL / 2 NO GATE). Detection-content lifecycle is already gated by Phase 4a (DAC candidate-rule) + 4b (truth table). Live-vendor sandbox smoke + rate-limit/checkpoint durability are tracked as 10b in `docs/audit/PROGRESS.md`.- **Phase 9a — autonomy-safety policy + honest rollback contract + scorecard.** The reality audit found three holes behind "L0-L4 automation maturity gates every action": dry-run was opt-in (a mis-configured caller executes for real), ~15 executor `rollback()`s silently `return True` with no reverse vendor call (the platform claimed to reverse containment it never did), and there was no post-action verification. New `services/actions/app/services/autonomy_safety.py` closes them at the policy layer: `decide()` makes **dry-run the safe default** — anything not explicitly permitted to auto-execute is previewed (`DRY_RUN`), never silently executed; CRITICAL blast never auto-executes; HIGH only at L4 with a whitelist entry AND the `AISOC_ALLOW_HIGH_BLAST_AUTO` break-glass flag. `rollback_capability()` with a **pinned `REVERSIBLE_ACTIONS={block_ip}`** set makes the rollback claim honest and bounded — a caller learns "this cannot be auto-reversed" instead of a silent `True`, and the set can't grow without a conscious edit + real reverse implementation. Every unattended containment (`AUTO`, blast ≥ MEDIUM) sets `requires_verification`, and `AutonomyScorecard` counts executions that were never verified — and executions of irreversible actions — as **visible gaps** rather than assumed-away. 16 tests (`services/actions/tests/test_autonomy_safety.py`, in the actions coverage matrix). Enforcement-wiring of `decide()` into the live `/dispatch` + `submit_action` router, rewriting the silent-`return True` executor rollbacks, real vendor verifiers, and a durable approval-SLA timer table (replacing the in-memory `approval_timeout.py`) are tracked as 9b in `docs/audit/PROGRESS.md`.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 7e285dbf0..e75ec7063 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -6,6 +6,29 @@ Thank you for your interest in contributing to AiSOC! This document provides guiBy participating in this project, you agree to abide by our [Code of Conduct](CODE_OF_CONDUCT.md). Please be respectful and constructive in all interactions.+## Governance++AiSOC is community-governed under the MIT license. See [`GOVERNANCE.md`](GOVERNANCE.md) for roles, decision-making, and how to become a maintainer, and [`MAINTAINERS.md`](MAINTAINERS.md) for the current maintainers.++## Developer Certificate of Origin (DCO)++All contributions must be made under the project's MIT license and carry a+**Developer Certificate of Origin** sign-off. The DCO ([developercertificate.org](https://developercertificate.org/))+is a lightweight, per-commit attestation that you wrote the patch (or otherwise+have the right to submit it under the project license).++Sign off every commit by adding a `Signed-off-by` trailer — `git commit -s`+does this automatically using your `user.name` / `user.email`:++```bash+git commit -s -m "feat: add the thing"+# → adds: Signed-off-by: Your Name <[email protected]>+```++If you forgot on your last commit, `git commit --amend -s --no-edit` fixes it;+for a whole branch, `git rebase --signoff main`.++## Your first 30 minutesIf you've never contributed to AiSOC before, here's the shortest path fromdiff --git a/GOVERNANCE.md b/GOVERNANCE.mdnew file mode 100644index 000000000..046a73527--- /dev/null+++ b/GOVERNANCE.md@@ -0,0 +1,78 @@+# AiSOC Governance++AiSOC is an open-source, community-maintained project under the MIT license.+This document describes how the project is governed: who makes decisions, how+someone becomes a maintainer, and how the project intends to stay a neutral,+long-lived home for its community.++## Principles++- **Open by default.** Design discussions, roadmaps, and decisions happen in+ public issues and pull requests. The claim-to-gate discipline+ (`docs/audit/CLAIM_TO_GATE_MATRIX.md`) is public: every headline capability is+ backed by a CI gate, and the roadmap (`ROADMAP.md`) tracks what is proven vs.+ planned.+- **Proof over promises.** A capability is not "done" until a CI gate fails when+ it stops being true. Contributions that add a claim add its gate.+- **No single point of failure.** The project aims to grow its maintainer set+ and, over time, move to a vendor-neutral home (see "Neutral home" below).++## Roles++| Role | Who | Rights |+|------|-----|--------|+| **User** | Anyone running AiSOC | Files issues, joins discussions. |+| **Contributor** | Anyone who has landed a PR | Everything a user can do; listed in git history. |+| **Maintainer** | Listed in [`MAINTAINERS.md`](MAINTAINERS.md) | Reviews + merges PRs, triages issues, cuts releases, stewards the roadmap. |++## Decision-making++- **Lazy consensus.** Most changes proceed by lazy consensus: a PR that has been+ open for review, passes CI, and draws no unresolved objections from a+ maintainer may be merged.+- **Substantive changes** (architecture, security posture, breaking API changes,+ new external dependencies, license/trademark) require review from at least one+ maintainer and a passing CI run, including the relevant gate. Breaking API+ changes additionally require the OpenAPI breaking-change gate+ (`openapi-breaking.yml`) to be satisfied deliberately (version bump ++ CHANGELOG BREAKING note).+- **Disagreement** is resolved by discussion in the PR/issue. If maintainers+ cannot reach consensus, the decision escalates to a maintainer vote (simple+ majority; ties fail closed — the change does not land).++## Becoming a maintainer++A contributor may be nominated as a maintainer after a sustained track record of+high-quality contributions and reviews. Nomination is by an existing maintainer+via a PR adding the candidate to `MAINTAINERS.md`; it lands under the same+review rules as any substantive change. Maintainers who are inactive for an+extended period may be moved to emeritus.++## Security++Vulnerabilities are handled per [`SECURITY.md`](SECURITY.md) — do **not** open a+public issue for a security report. The platform + agent threat models live in+`docs/security/`.++## Code of conduct++Participation is governed by [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).++## Contributions + DCO++All contributions are made under the project license (MIT) and must carry a+Developer Certificate of Origin sign-off (`Signed-off-by:`). See+[`CONTRIBUTING.md`](CONTRIBUTING.md#developer-certificate-of-origin-dco).++## Trademark++The MIT license covers the code; the AiSOC name and marks are governed+separately — see [`TRADEMARK.md`](TRADEMARK.md).++## Neutral home++AiSOC intends to remain vendor-neutral. As the community and maintainer set+grow, the project's explicit goal is to move governance and asset ownership to a+neutral foundation (e.g. a CNCF/OpenSSF-style home) rather than any single+company. This document is the interim governance model until that transition;+changes to it follow the "substantive change" process above.diff --git a/MAINTAINERS.md b/MAINTAINERS.mdnew file mode 100644index 000000000..b5dc24dc5--- /dev/null+++ b/MAINTAINERS.md@@ -0,0 +1,27 @@+# AiSOC Maintainers++Maintainers review and merge pull requests, triage issues, cut releases, and+steward the roadmap. See [`GOVERNANCE.md`](GOVERNANCE.md) for roles, the+decision-making process, and how to become a maintainer.++## Active maintainers++| Name | GitHub | Areas |+|------|--------|-------|+| Beenu Arora | [@beenuar](https://github.com/beenuar) | Project lead; architecture, security, releases |++## Emeritus maintainers++_None yet._++## How to reach the maintainers++- **General / roadmap:** open a GitHub issue or discussion.+- **Security:** follow [`SECURITY.md`](SECURITY.md) — never a public issue.++## Becoming a maintainer++The project actively wants to grow this list. New maintainers are nominated by+an existing maintainer via a PR editing this file, under the "substantive+change" review rules in `GOVERNANCE.md`. Sustained, high-quality contributions+and reviews are the path in.diff --git a/ROADMAP.md b/ROADMAP.mdindex cfd4240bc..72ef574a1 100644--- a/ROADMAP.md+++ b/ROADMAP.md@@ -34,7 +34,9 @@ A proof-first, security-first program to make every README claim gate-backed, cl- [x] Phase 9 — Autonomy safety (dry-run-by-default policy, honest bounded rollback-capability contract replacing silent `return True`, mandatory post-action verification for unattended containment, break-glass HIGH-blast flag, autonomy scorecard — all gated at the policy layer; live-router wiring + durable approval-SLA timer table tracked as 9b)- [x] Phase 10 — Connector + content quality (runtime-contract conformance suite across all 69 connectors — gates the "live Test connection" capability that had NO gate + secret-field-marking; published `conformance-matrix.md` with a drift gate; detection lifecycle already gated by Phase 4a DAC + Phase 4b truth table. Live-vendor sandbox smoke + rate-limit/checkpoint durability tracked as 10b)- [x] Phase 11 — API / SDK / release engineering (pure-Python OpenAPI breaking-change detector `scripts/openapi_diff.py` + `openapi-breaking.yml` gate: PR spec vs base fails on removed endpoint/schema/field, type change, tightened request, or dropped enum value — closes the OpenAPI NO GATE row; per-language SDK generated-client contract-drift tracked as 11b)-- [ ] Phase 12 — Observability + governance (SLOs, single trace, GOVERNANCE.md, DCO, committers, neutral home, trust docs)+- [x] Phase 12 — Observability + governance (per-service SLOs in `docs/operations/slos.yaml` with a coverage gate; `docs/operations/observability.md` documenting the four golden signals + single OTel trace across the spine; `GOVERNANCE.md` + `MAINTAINERS.md` + DCO sign-off in `CONTRIBUTING.md`; governance-completeness gate — `governance.yml`)++**All 13 phases (0–12) of the World-Class Hardening Program have landed.** The claim-to-gate matrix stands at **15 GATED / 11 PARTIAL / 1 NO GATE** (the last NO GATE — wet-eval live-agent scoreboard tables — needs a budgeted live-agent run, tracked as Phase 4c). Honestly-scoped continuations remain per phase (3.5+, 4c, 7b, 9b, 10b, 11b) and are tracked in `docs/audit/PROGRESS.md`; none change the committed phase checklist above.## v4.0 — Shippeddiff --git a/docs/operations/observability.md b/docs/operations/observability.mdnew file mode 100644index 000000000..9c083968f--- /dev/null+++ b/docs/operations/observability.md@@ -0,0 +1,54 @@+# Observability & SLOs++AiSOC is instrumented so an operator can answer "is it healthy, and if not,+where?" with a single trace and four golden signals per service.++## Service-level objectives++Every service declares its reliability posture in+[`slos.yaml`](./slos.yaml). `scripts/check_slos.py` gates it: a new service+under `services/` cannot ship without either an SLO block (availability + p95+latency + golden signals) or an explicit `exempt` entry with a reason.++The objectives are targets, not measured SLIs — they define the **error+budget** (`1 − availability_target` over a rolling 30 days) that the golden+signals below are measured against.++## The four golden signals++For each service we track the standard golden signals:++- **Latency** — request duration (p50/p95/p99). The p95 target per service is in+ `slos.yaml`.+- **Traffic** — request/event rate.+- **Errors** — rate of failed requests / dead-lettered events (the fusion DLQ,+ Phase 5, is a first-class error signal here).+- **Saturation** — how full the service is (queue depth, pool utilisation).++## Single trace across services++The critical path — `ingest → fusion → realtime → api → agents → actions` — is+instrumented with **OpenTelemetry**, so one incident is one distributed trace+from raw event to agent decision to response action. Traces export via OTLP to+Jaeger/Tempo; spans carry the tenant and run/incident ids so a trace can be+pulled up from any alert or investigation.++- Trace context propagates across the Kafka spine (event → fused alert → alert+ row) and the HTTP hops (api ↔ agents ↔ actions ↔ fusion).+- The Investigation Ledger records per-step model/tool attribution (see the+ [model router](../concepts/model-router.md) and+ [LLMOps](../concepts/llmops.md) docs), so the reasoning path inside the+ `agents` span is itself replayable.++## Metrics endpoints++Each service exposes Prometheus metrics at `/metrics`; the scrape config lives+in `infra/docker/prometheus.yml` and is gated (every `job_name` must point at a+real, instrumented `hostname:port` — a CI check enforces this so a scrape job+can't silently break).++## Governance++Reliability + governance are two halves of "run this next to your crown+jewels". See [`GOVERNANCE.md`](../../GOVERNANCE.md) for how the project is run+and [`MAINTAINERS.md`](../../MAINTAINERS.md) for who runs it.diff --git a/docs/operations/slos.yaml b/docs/operations/slos.yamlnew file mode 100644index 000000000..96c9d5ae4--- /dev/null+++ b/docs/operations/slos.yaml@@ -0,0 +1,102 @@+# Service-level objectives (Phase 12 — observability + governance).+#+# Every service under services/ MUST have an entry here — either an `slo:` block+# (it serves traffic and has objectives) or an `exempt:` block with a reason (a+# build-time library or a demo-only tool). scripts/check_slos.py --check fails+# CI if a service is missing, so a new service cannot ship without declaring its+# reliability posture.+#+# These are OBJECTIVES (targets), not measured SLIs. The golden-signal wiring+# that measures against them is OpenTelemetry (traces → Tempo/Jaeger) ++# Prometheus (/metrics); see docs/operations/observability.md. Error budget =+# 1 - availability_target over a rolling 30 days.++version: 1++services:+ api:+ availability_target: 0.999+ latency_p95_ms: 300+ golden_signals: [latency, traffic, errors, saturation]+ description: Public REST/GraphQL API — the analyst + integration entry point.+ realtime:+ availability_target: 0.999+ latency_p95_ms: 250+ golden_signals: [latency, traffic, errors, saturation]+ description: WebSocket fan-out for live alerts + graph updates.+ ingest:+ availability_target: 0.999+ latency_p95_ms: 200+ golden_signals: [latency, traffic, errors, saturation]+ description: Event intake + OCSF normalization on the hot path.+ fusion:+ availability_target: 0.999+ latency_p95_ms: 500+ golden_signals: [latency, traffic, errors, saturation]+ description: Correlation + promotion + alert persistence.+ agents:+ availability_target: 0.99+ latency_p95_ms: 120000+ golden_signals: [latency, traffic, errors, saturation]+ description: Investigation orchestrator (LLM latency dominates; SLO is per-investigation).+ connectors:+ availability_target: 0.99+ latency_p95_ms: 5000+ golden_signals: [traffic, errors, saturation]+ description: Polling scheduler + connector runtime.+ enrichment:+ availability_target: 0.99+ latency_p95_ms: 2000+ golden_signals: [latency, traffic, errors]+ description: IOC + entity enrichment cache.+ threatintel:+ availability_target: 0.99+ latency_p95_ms: 1000+ golden_signals: [latency, traffic, errors]+ description: Threat-intel store + actor attribution.+ ueba:+ availability_target: 0.99+ latency_p95_ms: 1000+ golden_signals: [latency, traffic, errors]+ description: Behavioral baselines + anomaly scoring.+ actions:+ availability_target: 0.999+ latency_p95_ms: 3000+ golden_signals: [latency, traffic, errors]+ description: SOAR executors (autonomy-gated; latency depends on the vendor API).+ slack-bot:+ availability_target: 0.99+ latency_p95_ms: 3000+ golden_signals: [latency, traffic, errors]+ description: Slack ChatOps + approvals.+ teams-bot:+ availability_target: 0.99+ latency_p95_ms: 3000+ golden_signals: [latency, traffic, errors]+ description: Microsoft Teams ChatOps + approvals.+ honeytokens:+ availability_target: 0.99+ latency_p95_ms: 500+ golden_signals: [latency, traffic, errors]+ description: Honeytoken minting + first-touch alerting.+ purple-team:+ availability_target: 0.95+ latency_p95_ms: 2000+ golden_signals: [traffic, errors]+ description: Atomic/Caldera adversary emulation + coverage.+ mcp:+ availability_target: 0.99+ latency_p95_ms: 2000+ golden_signals: [latency, traffic, errors]+ description: MCP server exposing agent tools to IDEs.+ osquery-tls:+ availability_target: 0.999+ latency_p95_ms: 500+ golden_signals: [latency, traffic, errors, saturation]+ description: First-party osquery TLS plugin (endpoint telemetry ingest).++exempt:+ demo-producer:+ reason: Demo-only synthetic event generator; not a production service.+ osquery-extensions:+ reason: Build-time Go virtual-table library shipped with the osquery agent; no service endpoint.diff --git a/scripts/check_governance.py b/scripts/check_governance.pynew file mode 100644index 000000000..d67c09799--- /dev/null+++ b/scripts/check_governance.py@@ -0,0 +1,60 @@+#!/usr/bin/env python3+"""Governance-completeness gate (Phase 12 — observability + governance).++Open-source trust rests on a small set of documents actually existing and being+non-trivial: governance model, maintainers, security policy, code of conduct,+trademark, and a DCO sign-off requirement. This gate fails if any is missing,+empty, or (for DCO) unreferenced — so the project's governance surface can't+silently rot.++Usage:+ python3 scripts/check_governance.py+"""++from __future__ import annotations++import sys+from pathlib import Path++ROOT = Path(__file__).resolve().parent.parent++# file → (min non-whitespace chars, [required substrings])+_REQUIRED = {+ "GOVERNANCE.md": (600, ["maintainer", "Neutral home", "Decision-making"]),+ "MAINTAINERS.md": (150, ["Maintainers"]),+ "SECURITY.md": (300, []),+ "CODE_OF_CONDUCT.md": (300, []),+ "TRADEMARK.md": (150, []),+ "CONTRIBUTING.md": (600, ["Developer Certificate of Origin", "Signed-off-by"]),+ "docs/operations/slos.yaml": (300, ["availability_target"]),+ "docs/operations/observability.md": (500, ["golden signal", "trace"]),+}+++def main() -> int:+ errors: list[str] = []+ for rel, (min_chars, substrings) in _REQUIRED.items():+ path = ROOT / rel+ if not path.exists():+ errors.append(f"missing required governance file: {rel}")+ continue+ text = path.read_text(encoding="utf-8")+ if len(text.strip()) < min_chars:+ errors.append(f"{rel} is too short ({len(text.strip())} < {min_chars} chars) — looks like a stub")+ low = text.lower()+ for sub in substrings:+ if sub.lower() not in low:+ errors.append(f"{rel} is missing required content: '{sub}'")++ if errors:+ print("ERROR: governance-completeness gate failed:", file=sys.stderr)+ for e in errors:+ print(f" - {e}", file=sys.stderr)+ return 1++ print(f"OK: all {len(_REQUIRED)} governance documents present and non-trivial")+ return 0+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/scripts/check_slos.py b/scripts/check_slos.pynew file mode 100644index 000000000..ca3007934--- /dev/null+++ b/scripts/check_slos.py@@ -0,0 +1,92 @@+#!/usr/bin/env python3+"""SLO-coverage gate (Phase 12 — observability + governance).++Every service under `services/` must declare a reliability posture in+`docs/operations/slos.yaml` — either an `slo` block (availability + p95 latency++ golden signals) or an `exempt` block with a reason. This gate fails when a+service is missing, so a new service cannot ship without declaring its SLO (the+same "no thing ships without an entry" pattern as the tenant-isolation+registry).++Usage:+ python3 scripts/check_slos.py # fail on any uncovered service+ python3 scripts/check_slos.py --print # list coverage+"""++from __future__ import annotations++import argparse+import sys+from pathlib import Path++import yaml++ROOT = Path(__file__).resolve().parent.parent+SLOS = ROOT / "docs" / "operations" / "slos.yaml"+SERVICES_DIR = ROOT / "services"++_REQUIRED_SLO_FIELDS = {"availability_target", "latency_p95_ms", "golden_signals", "description"}+++def _discovered_services() -> set[str]:+ return {p.name for p in SERVICES_DIR.iterdir() if p.is_dir() and not p.name.startswith(".")}+++def main() -> int:+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument("--print", dest="print_only", action="store_true")+ args = parser.parse_args()++ if not SLOS.exists():+ print(f"ERROR: {SLOS.relative_to(ROOT)} not found", file=sys.stderr)+ return 1++ data = yaml.safe_load(SLOS.read_text(encoding="utf-8")) or {}+ slo_services = data.get("services") or {}+ exempt = data.get("exempt") or {}+ covered = set(slo_services) | set(exempt)+ discovered = _discovered_services()++ errors: list[str] = []++ missing = discovered - covered+ for svc in sorted(missing):+ errors.append(f"service '{svc}' has no SLO or exempt entry in {SLOS.relative_to(ROOT)}")++ stale = covered - discovered+ for svc in sorted(stale):+ errors.append(f"slos.yaml references '{svc}' which is not a directory under services/")++ for svc, block in slo_services.items():+ if not isinstance(block, dict):+ errors.append(f"SLO for '{svc}' is not a mapping")+ continue+ missing_fields = _REQUIRED_SLO_FIELDS - set(block)+ if missing_fields:+ errors.append(f"SLO for '{svc}' missing fields: {sorted(missing_fields)}")+ av = block.get("availability_target")+ if isinstance(av, (int, float)) and not (0.0 < av <= 1.0):+ errors.append(f"SLO for '{svc}': availability_target {av} not in (0, 1]")++ for svc, block in exempt.items():+ if not isinstance(block, dict) or not str(block.get("reason", "")).strip():+ errors.append(f"exempt entry '{svc}' needs a non-empty reason")++ if args.print_only:+ print(f"services discovered: {len(discovered)} | SLOs: {len(slo_services)} | exempt: {len(exempt)}")+ for svc in sorted(discovered):+ tag = "slo" if svc in slo_services else ("exempt" if svc in exempt else "MISSING")+ print(f" {svc:<20} {tag}")++ if errors:+ print("ERROR: SLO coverage gate failed:", file=sys.stderr)+ for e in errors:+ print(f" - {e}", file=sys.stderr)+ return 1++ print(f"OK: all {len(discovered)} services have an SLO or exempt entry")+ return 0+++if __name__ == "__main__":+ raise SystemExit(main())