Skip to content

armgit / AiSOC

Public Imported from GitHub
0

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.

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.yml
new file mode 100644
index 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.py
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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.md
index 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 gui
By 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 minutes
If you've never contributed to AiSOC before, here's the shortest path from
diff --git a/GOVERNANCE.md b/GOVERNANCE.md
new file mode 100644
index 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.md
new file mode 100644
index 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.md
index 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 — Shipped
diff --git a/docs/operations/observability.md b/docs/operations/observability.md
new file mode 100644
index 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.yaml
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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())