kiri-cli 1.0.0b3__py3-none-any.whl

kiri_cli/sla_cmd.py

@@ -0,0 +1,769 @@
+"""``kiri sla check`` — runtime SLA enforcement (#161 / ADR 0036).
+
+Reads each contract's ``kiri.sla.*`` block (#160), checks declared
+freshness + quality thresholds against observed signals, and routes
+breaches via the prefix-dispatcher (slack: / teams: / local:).
+
+Two pure layers + one I/O layer:
+
+- :func:`evaluate_freshness` / :func:`evaluate_quality` — pure
+  functions that compare a SlaMeta to a single observed value and
+  return a :class:`SlaCheckResult`. Pure = directly unit-testable.
+- :func:`build_breach_message` — turns a breached report into the
+  payload shape webhooks accept. Also pure.
+- :func:`dispatch` — the HTTP layer. Mockable through a callable
+  parameter so tests don't speak HTTP.
+
+The CLI command (``sla_check_cmd``) glues them together: load
+project, fetch signals via the platform adapter, evaluate, dispatch.
+
+Why route is a free-form prefix descriptor rather than a typed enum
+of providers: each provider has its own auth shape (Slack uses an
+incoming webhook URL from env, PagerDuty needs a routing key, etc).
+The descriptor stays in the contract; the env wiring lives in the
+deployment. Adding a new provider = one prefix branch in
+:func:`dispatch` + one env var documented in ADR 0036.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from collections.abc import Callable, Mapping
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+from typing import Annotated, Any, Literal
+from urllib.request import Request, urlopen
+
+import typer
+from kiri_adapters import get_adapter
+from kiri_adapters.base import ProjectManifest
+from kiri_core import Project, load_project
+from kiri_core.odcs import CanonicalContract, SlaMeta
+from pydantic import BaseModel, ConfigDict
+from rich.console import Console
+from rich.table import Table
+
+from kiri_cli._project_option import resolve_project
+
+console = Console()
+
+
+# Match SlaMeta.freshness shape — same regex, kept local so we can
+# tokenise the digit + unit cleanly without re-parsing.
+_DURATION_RE = re.compile(r"^(\d+)([smhdw])$", re.IGNORECASE)
+
+
+# ---------------------------------------------------------------------------
+# Result models
+# ---------------------------------------------------------------------------
+
+
+CheckStatus = Literal["ok", "breach", "skipped", "unmeasured"]
+CheckKind = Literal["freshness", "quality"]
+
+
+class SlaCheckResult(BaseModel):
+    """One SLA check outcome on one contract.
+
+    ``status="skipped"`` means the check itself doesn't apply (e.g. the
+    contract didn't declare a threshold) — operators read it as "no
+    SLA set, nothing to evaluate".
+
+    ``status="unmeasured"`` means the check applies but the observed
+    signal isn't wired through yet (e.g. catalog quality signal not
+    plumbed into ``sla check``). Operators read it as "we owe you a
+    real answer here" — distinct from "passed".
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    contract_name: str
+    kind: CheckKind
+    status: CheckStatus
+    threshold: str | None = None  # human-readable, e.g. "4h" or "0.99"
+    observed: str | None = None
+    message: str = ""
+
+
+class SlaContractReport(BaseModel):
+    """Aggregate per-contract report — every check + the route used."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+    contract_name: str
+    results: list[SlaCheckResult]
+    route: str | None = None
+    severity: str | None = None
+
+    @property
+    def has_breach(self) -> bool:
+        return any(r.status == "breach" for r in self.results)
+
+
+# ---------------------------------------------------------------------------
+# Pure evaluators
+# ---------------------------------------------------------------------------
+
+
+def _parse_duration(spec: str) -> timedelta:
+    """Convert a freshness spec like ``4h`` to a :class:`timedelta`."""
+    match = _DURATION_RE.match(spec)
+    if match is None:  # pragma: no cover — gated by SlaMeta validator
+        raise ValueError(f"invalid duration: {spec!r}")
+    n, unit = int(match.group(1)), match.group(2).lower()
+    multipliers: dict[str, timedelta] = {
+        "s": timedelta(seconds=1),
+        "m": timedelta(minutes=1),
+        "h": timedelta(hours=1),
+        "d": timedelta(days=1),
+        "w": timedelta(weeks=1),
+    }
+    return n * multipliers[unit]
+
+
+def evaluate_freshness(
+    *,
+    contract_name: str,
+    sla: SlaMeta,
+    manifest: ProjectManifest | None,
+    now: datetime | None = None,
+) -> SlaCheckResult:
+    """Compare ``sla.freshness`` to the latest apply timestamp.
+
+    ``now`` is injectable for deterministic tests. ``manifest`` is
+    fetched once by the caller for the active ``(project, target)`` and
+    is None when no apply has stamped the manifest yet.
+
+    Returns ``status="skipped"`` when the contract didn't declare
+    ``kiri.sla.freshness`` — silent skip beats noisy "no SLA set" rows
+    in the report.
+    """
+    if sla.freshness is None:
+        return SlaCheckResult(
+            contract_name=contract_name,
+            kind="freshness",
+            status="skipped",
+            message="no kiri.sla.freshness declared",
+        )
+    latest_apply_iso = manifest.release_ts if manifest else None
+    if latest_apply_iso is None:
+        return SlaCheckResult(
+            contract_name=contract_name,
+            kind="freshness",
+            status="skipped",
+            threshold=sla.freshness,
+            message="no apply has stamped the manifest yet",
+        )
+
+    threshold = _parse_duration(sla.freshness)
+    try:
+        latest = datetime.fromisoformat(latest_apply_iso.replace("Z", "+00:00"))
+    except ValueError:
+        return SlaCheckResult(
+            contract_name=contract_name,
+            kind="freshness",
+            status="skipped",
+            threshold=sla.freshness,
+            message=f"can't parse manifest release_ts: {latest_apply_iso!r}",
+        )
+    if latest.tzinfo is None:
+        latest = latest.replace(tzinfo=UTC)
+
+    current = now if now is not None else datetime.now(UTC)
+    age = current - latest
+    age_str = _format_timedelta(age)
+
+    if age <= threshold:
+        return SlaCheckResult(
+            contract_name=contract_name,
+            kind="freshness",
+            status="ok",
+            threshold=sla.freshness,
+            observed=age_str,
+        )
+    return SlaCheckResult(
+        contract_name=contract_name,
+        kind="freshness",
+        status="breach",
+        threshold=sla.freshness,
+        observed=age_str,
+        message=(f"latest apply was {age_str} ago, exceeds {sla.freshness}"),
+    )
+
+
+def evaluate_quality(
+    *,
+    contract_name: str,
+    sla: SlaMeta,
+    latest_pass_rate: float | None,
+) -> SlaCheckResult:
+    """Compare ``sla.quality_threshold`` to the latest GE pass-rate.
+
+    The catalog wiring that surfaces ``latest_pass_rate`` lives in a
+    separate task (see TODO at ``sla_check_cmd`` and follow-up issue
+    referenced in CODEX-TECH-DEBT-V1 slice F / finding F11). When the
+    threshold is declared but the signal isn't wired through, this
+    function emits ``status="unmeasured"`` — explicitly different from
+    "skipped" (= no threshold to evaluate). Operators see at a glance
+    that the check is owed a real answer, not silently passing.
+    """
+    if sla.quality_threshold is None:
+        return SlaCheckResult(
+            contract_name=contract_name,
+            kind="quality",
+            status="skipped",
+            message="no kiri.sla.quality_threshold declared",
+        )
+    if latest_pass_rate is None:
+        return SlaCheckResult(
+            contract_name=contract_name,
+            kind="quality",
+            status="unmeasured",
+            threshold=f"{sla.quality_threshold:.2f}",
+            message=(
+                "quality signal not wired — GE pass-rate is not yet "
+                "plumbed into `sla check` (CODEX-TECH-DEBT-V1 F11)"
+            ),
+        )
+    threshold = sla.quality_threshold
+    if latest_pass_rate >= threshold:
+        return SlaCheckResult(
+            contract_name=contract_name,
+            kind="quality",
+            status="ok",
+            threshold=f"{threshold:.2f}",
+            observed=f"{latest_pass_rate:.2f}",
+        )
+    return SlaCheckResult(
+        contract_name=contract_name,
+        kind="quality",
+        status="breach",
+        threshold=f"{threshold:.2f}",
+        observed=f"{latest_pass_rate:.2f}",
+        message=(f"pass-rate {latest_pass_rate:.2f} below threshold {threshold:.2f}"),
+    )
+
+
+def _format_timedelta(td: timedelta) -> str:
+    """Compact human-readable timedelta — '3d 4h' / '15m' / '12h'."""
+    total_minutes = int(td.total_seconds() // 60)
+    if total_minutes < 1:
+        return f"{int(td.total_seconds())}s"
+    if total_minutes < 60:
+        return f"{total_minutes}m"
+    days, hours = divmod(total_minutes // 60, 24)
+    if days:
+        return f"{days}d {hours}h" if hours else f"{days}d"
+    return f"{hours}h"
+
+
+# ---------------------------------------------------------------------------
+# Breach message + dispatcher
+# ---------------------------------------------------------------------------
+
+
+def build_breach_message(report: SlaContractReport) -> dict[str, Any]:
+    """Render a breached report as a webhook-friendly payload.
+
+    Same shape for every transport (Slack/Teams/local) — we keep the
+    payload structured (not pre-formatted markdown) so each
+    transport's renderer can choose its own visual treatment. For
+    Slack/Teams that's a Block Kit / Adaptive Card; for local stdout
+    it's just JSON dumped.
+    """
+    breaches = [r for r in report.results if r.status == "breach"]
+    return {
+        "contract": report.contract_name,
+        "severity": report.severity or "medium",
+        "breaches": [
+            {
+                "kind": b.kind,
+                "threshold": b.threshold,
+                "observed": b.observed,
+                "message": b.message,
+            }
+            for b in breaches
+        ],
+    }
+
+
+HttpPoster = Callable[[str, str, Mapping[str, str] | None], int]
+"""Callable that POSTs ``body`` to ``url`` with optional extra headers and
+returns the status code.
+
+Injected so tests don't speak HTTP. The default implementation uses
+``urllib.request.urlopen`` — no extra dependency, pure stdlib.
+
+Sprint 1.7 (2026-05-23): the third positional ``headers`` argument is
+required by the OpsGenie route, which authenticates via an
+``Authorization: GenieKey <api_key>`` header rather than a webhook URL
+that embeds the secret. Slack / Teams / PagerDuty paths pass
+``headers=None``. Tests inject deterministic posters that mirror the
+same three-positional signature.
+"""
+
+
+def _default_http_post(
+    url: str,
+    body: str,
+    headers: Mapping[str, str] | None = None,
+) -> int:
+    """Default poster: stdlib urlopen with JSON content-type plus any
+    operator-supplied headers (e.g. OpsGenie ``Authorization: GenieKey``).
+    """
+    request_headers = {"Content-Type": "application/json"}
+    if headers:
+        request_headers.update(headers)
+    req = Request(  # noqa: S310 — URL is operator-supplied via env
+        url,
+        data=body.encode("utf-8"),
+        headers=request_headers,
+        method="POST",
+    )
+    with urlopen(req, timeout=10) as resp:  # noqa: S310
+        return int(resp.status)
+
+
+def dispatch(
+    route: str,
+    payload: dict[str, Any],
+    *,
+    poster: HttpPoster | None = None,
+    dry_run: bool = False,
+) -> str:
+    """Send a breach notification via the route's prefix dispatcher.
+
+    Supported prefixes:
+
+    - ``local:`` — print JSON to stdout (no HTTP). Useful in CI / dev.
+    - ``slack:`` — POST to ``$SLACK_WEBHOOK_URL`` (operator configures
+      the incoming webhook URL out-of-band).
+    - ``teams:`` — POST to ``$TEAMS_WEBHOOK_URL``.
+
+    Sprint 1.7 (2026-05-23) closes the deferred PagerDuty + Opsgenie
+    wiring. The route prefix selects the transport, the suffix is the
+    instance identifier (PagerDuty Events v2 service-routing key,
+    Opsgenie team alias). The secret itself MUST come from an
+    environment variable, never the CLI argument, so the routing key
+    is never logged to shell history.
+
+    ``dry_run=True`` short-circuits transport and returns a "(dry-run)"
+    marker — same control-flow path as a real send but without I/O.
+    """
+    poster = poster or _default_http_post
+    body = json.dumps(payload, indent=2)
+
+    if dry_run:
+        return f"(dry-run) would route to {route}: {payload['contract']}"
+
+    if route.startswith("local:"):
+        print(body)
+        return f"local: printed payload for {payload['contract']}"
+
+    if route.startswith("slack:"):
+        url = os.environ.get("SLACK_WEBHOOK_URL")
+        if not url:
+            return f"slack: SLACK_WEBHOOK_URL not set — skipped {payload['contract']}"
+        # Slack incoming webhooks accept simple {"text": "..."} bodies.
+        text = _format_for_slack(payload)
+        status = poster(url, json.dumps({"text": text}), None)
+        return f"slack: HTTP {status} for {payload['contract']}"
+
+    if route.startswith("teams:"):
+        url = os.environ.get("TEAMS_WEBHOOK_URL")
+        if not url:
+            return f"teams: TEAMS_WEBHOOK_URL not set — skipped {payload['contract']}"
+        text = _format_for_teams(payload)
+        status = poster(url, json.dumps({"text": text}), None)
+        return f"teams: HTTP {status} for {payload['contract']}"
+
+    if route.startswith("pagerduty:"):
+        # PagerDuty Events API v2 (https://events.pagerduty.com/v2/enqueue).
+        # The routing key is a 32-char service-integration token; we
+        # require it via PAGERDUTY_ROUTING_KEY rather than splicing it
+        # into the route argument so it never lands in shell history or
+        # in a git-tracked kiri.yml.
+        routing_key = os.environ.get("PAGERDUTY_ROUTING_KEY")
+        if not routing_key:
+            return f"pagerduty: PAGERDUTY_ROUTING_KEY not set — skipped {payload['contract']}"
+        event_body = json.dumps(_format_for_pagerduty(payload, routing_key))
+        status = poster("https://events.pagerduty.com/v2/enqueue", event_body, None)
+        return f"pagerduty: HTTP {status} for {payload['contract']}"
+
+    if route.startswith("opsgenie:"):
+        # Opsgenie Alerts API
+        # (https://api.opsgenie.com/v2/alerts). Auth header is
+        # ``Authorization: GenieKey <api_key>``; the key comes from
+        # OPSGENIE_API_KEY for the same reason PagerDuty's routing key
+        # does not live on the CLI.
+        api_key = os.environ.get("OPSGENIE_API_KEY")
+        if not api_key:
+            return f"opsgenie: OPSGENIE_API_KEY not set — skipped {payload['contract']}"
+        alert_body = json.dumps(_format_for_opsgenie(payload))
+        status = poster(
+            "https://api.opsgenie.com/v2/alerts",
+            alert_body,
+            {"Authorization": f"GenieKey {api_key}"},
+        )
+        return f"opsgenie: HTTP {status} for {payload['contract']}"
+
+    return f"unknown route prefix: {route!r} (skipped {payload['contract']})"
+
+
+def _format_for_slack(payload: dict[str, Any]) -> str:
+    """Plain-text Slack message — one line per breach, severity tag."""
+    lines = [
+        f":rotating_light: *SLA breach* on `{payload['contract']}` (severity {payload['severity']})"
+    ]
+    for b in payload["breaches"]:
+        lines.append(
+            f"  • {b['kind']}: {b['message']} "
+            f"(threshold {b['threshold']}, observed {b['observed']})"
+        )
+    return "\n".join(lines)
+
+
+def _format_for_teams(payload: dict[str, Any]) -> str:
+    """Plain-text Teams message — same shape, different emoji conventions."""
+    lines = [f"⚠️ SLA breach on **{payload['contract']}** (severity {payload['severity']})"]
+    for b in payload["breaches"]:
+        lines.append(
+            f"- {b['kind']}: {b['message']} (threshold {b['threshold']}, observed {b['observed']})"
+        )
+    return "\n".join(lines)
+
+
+_PAGERDUTY_SEVERITY_MAP: dict[str, str] = {
+    "critical": "critical",
+    "high": "error",
+    "warning": "warning",
+    "low": "info",
+}
+
+
+def _format_for_pagerduty(payload: dict[str, Any], routing_key: str) -> dict[str, Any]:
+    """Build a PagerDuty Events API v2 ``trigger`` event.
+
+    The ``dedup_key`` keys on contract identity so re-firing the same
+    breach updates the same incident instead of creating duplicates.
+    The full breach payload rides in ``custom_details`` for
+    on-call responders.
+    """
+
+    severity = _PAGERDUTY_SEVERITY_MAP.get(str(payload.get("severity", "")).lower(), "warning")
+    summaries = [
+        f"{b['kind']}: {b['message']} (threshold {b['threshold']}, observed {b['observed']})"
+        for b in payload["breaches"]
+    ]
+    summary = (
+        f"SLA breach on {payload['contract']} — {len(summaries)} "
+        f"breach{'es' if len(summaries) != 1 else ''}"
+    )
+    return {
+        "routing_key": routing_key,
+        "event_action": "trigger",
+        "dedup_key": f"kirimana:sla:{payload['contract']}",
+        "payload": {
+            "summary": summary,
+            "severity": severity,
+            "source": "kirimana",
+            "component": payload["contract"],
+            "group": "sla",
+            "class": "sla_breach",
+            "custom_details": {
+                "contract": payload["contract"],
+                "severity_input": payload.get("severity"),
+                "breaches": payload["breaches"],
+                "details": summaries,
+            },
+        },
+    }
+
+
+_OPSGENIE_PRIORITY_MAP: dict[str, str] = {
+    "critical": "P1",
+    "high": "P2",
+    "warning": "P3",
+    "low": "P4",
+}
+
+
+def _format_for_opsgenie(payload: dict[str, Any]) -> dict[str, Any]:
+    """Build an Opsgenie alert payload.
+
+    ``alias`` keys on contract identity (same dedup semantics as the
+    PagerDuty ``dedup_key``); ``priority`` derives from the SLA
+    severity via the closed-menu mapping above. The full breach
+    payload rides in ``details`` so on-call responders can drill in
+    without leaving Opsgenie.
+    """
+
+    priority = _OPSGENIE_PRIORITY_MAP.get(str(payload.get("severity", "")).lower(), "P3")
+    message = (
+        f"SLA breach on {payload['contract']} ({len(payload['breaches'])} "
+        f"breach{'es' if len(payload['breaches']) != 1 else ''})"
+    )
+    description_lines = [
+        f"{b['kind']}: {b['message']} (threshold {b['threshold']}, observed {b['observed']})"
+        for b in payload["breaches"]
+    ]
+    return {
+        "message": message,
+        "alias": f"kirimana:sla:{payload['contract']}",
+        "priority": priority,
+        "source": "kirimana",
+        "tags": ["kirimana", "sla", payload["contract"]],
+        "description": "\n".join(description_lines),
+        "details": {
+            "contract": payload["contract"],
+            "severity_input": str(payload.get("severity") or ""),
+            "breach_count": str(len(payload["breaches"])),
+        },
+    }
+
+
+# ---------------------------------------------------------------------------
+# CLI command
+# ---------------------------------------------------------------------------
+
+
+def _evaluate_contract(
+    contract: CanonicalContract,
+    *,
+    manifest: ProjectManifest | None,
+    latest_pass_rate: float | None,
+    now: datetime | None = None,
+) -> SlaContractReport:
+    """Run both checks on one contract."""
+    sla = contract.kiri.sla
+    name = contract.contract.name
+    results = [
+        evaluate_freshness(
+            contract_name=name,
+            sla=sla,
+            manifest=manifest,
+            now=now,
+        ),
+        evaluate_quality(
+            contract_name=name,
+            sla=sla,
+            latest_pass_rate=latest_pass_rate,
+        ),
+    ]
+    route = sla.on_breach.route if sla.on_breach else None
+    severity = sla.on_breach.severity.value if sla.on_breach else None
+    return SlaContractReport(
+        contract_name=name,
+        results=results,
+        route=route,
+        severity=severity,
+    )
+
+
+_STATUS_GLYPHS = {
+    "ok": "[green]✓[/green]",
+    "breach": "[red]✗[/red]",
+    "skipped": "[dim]·[/dim]",
+    "unmeasured": "[yellow]?[/yellow]",
+}
+
+
+def _render_report(reports: list[SlaContractReport]) -> None:
+    table = Table(show_header=True, header_style="bold")
+    table.add_column("Contract")
+    table.add_column("Check")
+    table.add_column("", width=2)
+    table.add_column("Threshold")
+    table.add_column("Observed")
+    table.add_column("Detail", overflow="fold")
+    for rep in reports:
+        for r in rep.results:
+            table.add_row(
+                rep.contract_name,
+                r.kind,
+                _STATUS_GLYPHS[r.status],
+                r.threshold or "—",
+                r.observed or "—",
+                r.message,
+            )
+    console.print(table)
+
+
+def sla_check_cmd(
+    project: Annotated[
+        Path | None,
+        typer.Option("--project", "-p", help="Project root."),
+    ] = None,
+    target: Annotated[
+        str | None,
+        typer.Option(
+            "--target",
+            help="Environment target (default: project's default_target).",
+        ),
+    ] = None,
+    contract: Annotated[
+        str | None,
+        typer.Option(
+            "--contract",
+            help="Check only this contract (by name).",
+        ),
+    ] = None,
+    dry_run: Annotated[
+        bool,
+        typer.Option(
+            "--dry-run",
+            help="Don't actually dispatch breaches; print what would happen.",
+        ),
+    ] = False,
+) -> None:
+    """Check SLA declarations across the project + route breaches.
+
+    Reads each contract's ``kiri.sla.*`` block, fetches the platform's
+    manifest for the freshness signal, evaluates, dispatches breaches
+    via the configured ``on_breach.route``.
+
+    Exit codes:
+
+    - ``0`` — no breaches (every check ok or skipped).
+    - ``1`` — at least one breach detected.
+    - ``2`` — project failed to load.
+    """
+    project = resolve_project(project)
+    try:
+        p = load_project(project)
+    except Exception as e:
+        console.print(f"[red]✗[/red] failed to load project: {e}")
+        raise typer.Exit(code=2) from e
+
+    chosen_target = target or p.config.default_target
+    profile = p.config.profile_for(chosen_target)
+    adapter = get_adapter(p.config.adapter, profile)
+
+    # Filter to contracts that declare any kiri.sla.* — otherwise the
+    # report is mostly skipped rows. Operators wanting "everything"
+    # can pass --contract.
+    declared = (
+        [c for c in p.contracts if c.contract.name == contract]
+        if contract is not None
+        else [
+            c
+            for c in p.contracts
+            if c.kiri.sla.freshness is not None
+            or c.kiri.sla.quality_threshold is not None
+            or c.kiri.sla.on_breach is not None
+        ]
+    )
+
+    if not declared:
+        if contract is not None:
+            console.print(f"[red]✗[/red] no contract named {contract!r}.")
+            raise typer.Exit(code=2)
+        console.print("[yellow]![/yellow] no contracts declare kiri.sla.* — nothing to check.")
+        return
+
+    # read_manifest returns None when no apply has stamped the slot yet
+    # — fine, evaluate_freshness emits "skipped" with a clear message.
+    try:
+        manifest = adapter.read_manifest(p.config.name, chosen_target)
+    except Exception:
+        manifest = None
+
+    reports: list[SlaContractReport] = []
+    for c in declared:
+        # Catalog quality signal lands later (CODEX-TECH-DEBT-V1 F11) —
+        # pass None so the quality check renders as ``unmeasured`` with
+        # a "signal not wired" message rather than a misleading
+        # ``skipped`` row. The status taxonomy distinguishes the two:
+        # ``skipped`` = check doesn't apply; ``unmeasured`` = check
+        # applies but we owe a real answer.
+        reports.append(
+            _evaluate_contract(
+                c,
+                manifest=manifest,
+                latest_pass_rate=None,
+            )
+        )
+
+    # Surface the wiring gap loudly above the table so an operator who
+    # only glances at the report can't mistake ``unmeasured`` quality
+    # rows for ``ok``.
+    if any(
+        r.status == "unmeasured" and r.kind == "quality" for rep in reports for r in rep.results
+    ):
+        console.print(
+            "[yellow]![/yellow] quality signal not wired — GE pass-rate "
+            "is not yet plumbed into `sla check`. Quality rows below "
+            "will show `unmeasured`, not `ok`. "
+            "(CODEX-TECH-DEBT-V1 F11)"
+        )
+
+    _render_report(reports)
+
+    breaches = [r for r in reports if r.has_breach]
+    if not breaches:
+        console.print("\n[green]✓ no breaches[/green]")
+        return
+
+    console.print(f"\n[bold]{len(breaches)} breach(es) — dispatching:[/bold]")
+    for rep in breaches:
+        if not rep.route:
+            console.print(
+                f"  [yellow]·[/yellow] {rep.contract_name}: "
+                "no on_breach.route declared — logged only"
+            )
+        else:
+            outcome = dispatch(rep.route, build_breach_message(rep), dry_run=dry_run)
+            console.print(f"  → {outcome}")
+        # ADR 0038 #173: also dispatch to ITSM if configured. Peer
+        # surface to slack/teams — operators get both a notification
+        # and a tracked ticket.
+        if not dry_run:
+            _route_to_itsm(p, project, rep, chosen_target)
+    raise typer.Exit(code=1)
+
+
+def _route_to_itsm(
+    project_obj: Project,
+    project_root: Path,
+    report: SlaContractReport,
+    target_env: str,
+) -> None:
+    """Best-effort fan-out to the ITSM dispatcher (#173).
+
+    Imported lazily so projects without an ``incidents:`` block don't
+    pay the kiri_adapters import cost on every SLA check.
+    """
+    from kiri_core import incident_from_sla_breach
+    from kiri_core.apply.incident_router import route_incident
+
+    incident = incident_from_sla_breach(report, target_env=target_env)
+    result = route_incident(project_obj, project_root, incident)
+    if result is not None:
+        console.print(
+            f"  → itsm:{result.backend} ticket={result.ticket_id} ({result.action.value})"
+        )
+
+
+def build_sla_app() -> typer.Typer:
+    """Build the ``kiri sla ...`` sub-app."""
+    sla_app = typer.Typer(
+        name="sla",
+        help="Data SLA enforcement — check freshness/quality + route breaches (ADR 0036).",
+        no_args_is_help=True,
+    )
+    sla_app.command("check")(sla_check_cmd)
+    return sla_app
+
+
+__all__ = [
+    "SlaCheckResult",
+    "SlaContractReport",
+    "build_breach_message",
+    "build_sla_app",
+    "dispatch",
+    "evaluate_freshness",
+    "evaluate_quality",
+    "sla_check_cmd",
+]