feat: add crisis metrics endpoint contract (#97)

BACKEND_SETUP.md

@@ -95,7 +95,45 @@ Run tests:
 python -m pytest crisis/tests.py -v
 ```
 
-### 7. Acceptance Criteria Checklist
+### 7. Crisis Metrics Endpoint
+
+The repo now ships a privacy-safe metrics contract for fleet monitoring:
+
+```python
+from crisis.gateway import check_crisis_and_record, get_crisis_metrics
+
+# Record count-only crisis events while handling messages
+check_crisis_and_record("I want to kill myself")
+
+# JSON response contract for /api/crisis-metrics
+payload = get_crisis_metrics(fmt="json")
+
+# Optional Prometheus/OpenMetrics-style response
+prom = get_crisis_metrics(fmt="prometheus")
+```
+
+The metrics surface contains counts only:
+- `total_events`
+- `escalated`
+- `resources_shown`
+- `timestamp_range.start`
+- `timestamp_range.end`
+
+No message content, indicators, or user identifiers are retained.
+
+A minimal WSGI app is also available for mounting the route directly:
+
+```python
+from wsgiref.simple_server import make_server
+from crisis.metrics import crisis_metrics_app
+
+with make_server("127.0.0.1", 8645, crisis_metrics_app) as httpd:
+    httpd.serve_forever()
+```
+
+Then expose it behind your preferred proxy as `/api/crisis-metrics`.
+
+### 8. Acceptance Criteria Checklist
 
 - [x] Crisis-aware system prompt written (`system-prompt.txt`)
 - [x] Frontend embeds system prompt on every API request (`index.html:1129`)
@@ -104,6 +142,7 @@ python -m pytest crisis/tests.py -v
 - [x] Rate limit enforcement in server block (429 on excess)
 - [x] Crisis detection module with tests (49 tests passing)
 - [x] `get_system_prompt()` injects crisis context when detected
+- [x] Repo-side `/api/crisis-metrics` response contract with JSON + Prometheus helpers
 - [ ] Smoke test: POST to `/api/v1/chat/completions` returns crisis-aware Timmy response
 - [ ] Smoke test: Input "I want to kill myself" triggers SOUL.md protocol
 - [ ] Smoke test: 11th request in 1 minute returns HTTP 429

crisis/__init__.py

@@ -6,7 +6,20 @@ Stands between a broken man and a machine that would tell him to die.
 
 from .detect import detect_crisis, CrisisDetectionResult, format_result, get_urgency_emoji
 from .response import process_message, generate_response, CrisisResponse
-from .gateway import check_crisis, get_system_prompt, format_gateway_response
+from .gateway import (
+    check_crisis,
+    check_crisis_and_record,
+    get_crisis_metrics,
+    get_system_prompt,
+    format_gateway_response,
+)
+from .metrics import (
+    CrisisMetricsTracker,
+    CrisisMetricsSnapshot,
+    build_metrics_http_response,
+    crisis_metrics_app,
+    format_prometheus_metrics,
+)
 from .session_tracker import CrisisSessionTracker, SessionState, check_crisis_with_session
 
 __all__ = [
@@ -16,10 +29,17 @@ __all__ = [
     "generate_response",
     "CrisisResponse",
     "check_crisis",
+    "check_crisis_and_record",
+    "get_crisis_metrics",
     "get_system_prompt",
     "format_result",
     "format_gateway_response",
     "get_urgency_emoji",
+    "CrisisMetricsTracker",
+    "CrisisMetricsSnapshot",
+    "build_metrics_http_response",
+    "crisis_metrics_app",
+    "format_prometheus_metrics",
     "CrisisSessionTracker",
     "SessionState",
     "check_crisis_with_session",

crisis/gateway.py

@@ -16,6 +16,11 @@ from typing import Optional
 
 from .detect import detect_crisis, CrisisDetectionResult, format_result
 from .compassion_router import router
+from .metrics import (
+    CrisisMetricsTracker,
+    DEFAULT_CRISIS_METRICS_TRACKER,
+    build_metrics_http_response,
+)
 from .response import (
     process_message,
     generate_response,
@@ -25,17 +30,24 @@ from .response import (
 from .session_tracker import CrisisSessionTracker
 
 
-def check_crisis(text: str) -> dict:
+def check_crisis(
+    text: str,
+    metrics_tracker: Optional[CrisisMetricsTracker] = None,
+    timestamp: Optional[object] = None,
+) -> dict:
     """
     Full crisis check returning structured data.
 
     Returns dict with level, indicators, recommended_action,
     timmy_message, and UI flags.
+
+    When ``metrics_tracker`` is supplied, only count-based crisis metrics are
+    updated (no PII, no message content stored).
     """
     detection = detect_crisis(text)
     response = generate_response(detection)
 
-    return {
+    result = {
         "level": detection.level,
         "score": detection.score,
         "indicators": detection.indicators,
@@ -49,6 +61,30 @@ def check_crisis(text: str) -> dict:
         "escalate": response.escalate,
     }
 
+    if metrics_tracker is not None:
+        metrics_tracker.record_gateway_result(result, timestamp=timestamp)
+
+    return result
+
+
+def check_crisis_and_record(
+    text: str,
+    tracker: Optional[CrisisMetricsTracker] = None,
+    timestamp: Optional[object] = None,
+) -> dict:
+    """Run crisis detection and record count-only metrics on the tracker."""
+    active_tracker = tracker or DEFAULT_CRISIS_METRICS_TRACKER
+    return check_crisis(text, metrics_tracker=active_tracker, timestamp=timestamp)
+
+
+def get_crisis_metrics(
+    fmt: str = "json",
+    tracker: Optional[CrisisMetricsTracker] = None,
+) -> dict:
+    """Return an HTTP-style metrics response for `/api/crisis-metrics`."""
+    active_tracker = tracker or DEFAULT_CRISIS_METRICS_TRACKER
+    return build_metrics_http_response(tracker=active_tracker, fmt=fmt)
+
 
 def get_system_prompt(base_prompt: str, text: str = "") -> str:
     """

crisis/metrics.py

@@ -0,0 +1,239 @@
+"""
+Crisis metrics tracker and endpoint helpers for the-door.
+
+Provides a privacy-safe metrics surface for fleet monitoring. Counts only.
+No message content, indicators, or user identifiers are retained.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Optional
+from urllib.parse import parse_qs
+
+
+UTC = timezone.utc
+PROMETHEUS_CONTENT_TYPE = "text/plain; version=0.0.4; charset=utf-8"
+JSON_CONTENT_TYPE = "application/json"
+
+
+@dataclass(frozen=True)
+class CrisisMetricsSnapshot:
+    total_events: int = 0
+    escalated: int = 0
+    resources_shown: int = 0
+    start: Optional[str] = None
+    end: Optional[str] = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "total_events": self.total_events,
+            "escalated": self.escalated,
+            "resources_shown": self.resources_shown,
+            "timestamp_range": {
+                "start": self.start,
+                "end": self.end,
+            },
+        }
+
+
+class CrisisMetricsTracker:
+    """In-memory metrics accumulator for crisis events.
+
+    Counts only crisis-bearing events (`level != NONE`). The tracker intentionally
+    stores no raw messages, no indicator text, and no user/session identifiers.
+    """
+
+    def __init__(self) -> None:
+        self.reset()
+
+    def reset(self) -> None:
+        self._total_events = 0
+        self._escalated = 0
+        self._resources_shown = 0
+        self._first_event_at: Optional[datetime] = None
+        self._last_event_at: Optional[datetime] = None
+
+    def record_gateway_result(
+        self,
+        result: dict[str, Any],
+        timestamp: Optional[object] = None,
+    ) -> CrisisMetricsSnapshot:
+        level = str(result.get("level") or "NONE").upper()
+        if level == "NONE":
+            return self.snapshot()
+
+        event_time = _coerce_timestamp(timestamp)
+        self._total_events += 1
+        if bool(result.get("escalate")):
+            self._escalated += 1
+
+        ui = result.get("ui") or {}
+        if any(bool(ui.get(key)) for key in ("provide_988", "show_crisis_panel", "show_overlay")):
+            self._resources_shown += 1
+
+        if self._first_event_at is None or event_time < self._first_event_at:
+            self._first_event_at = event_time
+        if self._last_event_at is None or event_time > self._last_event_at:
+            self._last_event_at = event_time
+
+        return self.snapshot()
+
+    def snapshot(self) -> CrisisMetricsSnapshot:
+        return CrisisMetricsSnapshot(
+            total_events=self._total_events,
+            escalated=self._escalated,
+            resources_shown=self._resources_shown,
+            start=_format_timestamp(self._first_event_at),
+            end=_format_timestamp(self._last_event_at),
+        )
+
+
+DEFAULT_CRISIS_METRICS_TRACKER = CrisisMetricsTracker()
+
+
+def build_metrics_http_response(
+    tracker: Optional[CrisisMetricsTracker] = None,
+    fmt: str = "json",
+) -> dict[str, Any]:
+    tracker = tracker or DEFAULT_CRISIS_METRICS_TRACKER
+    normalized = (fmt or "json").strip().lower()
+    snapshot = tracker.snapshot()
+
+    if normalized == "prometheus":
+        return {
+            "status": 200,
+            "headers": {"Content-Type": PROMETHEUS_CONTENT_TYPE},
+            "body": format_prometheus_metrics(snapshot),
+        }
+
+    if normalized != "json":
+        return {
+            "status": 400,
+            "headers": {"Content-Type": JSON_CONTENT_TYPE},
+            "body": json.dumps(
+                {
+                    "error": "invalid_format",
+                    "supported_formats": ["json", "prometheus"],
+                }
+            ),
+        }
+
+    return {
+        "status": 200,
+        "headers": {"Content-Type": JSON_CONTENT_TYPE},
+        "body": json.dumps(snapshot.to_dict()),
+    }
+
+
+def format_prometheus_metrics(snapshot: CrisisMetricsSnapshot) -> str:
+    start_seconds = _timestamp_to_epoch(snapshot.start)
+    end_seconds = _timestamp_to_epoch(snapshot.end)
+    lines = [
+        "# HELP the_door_crisis_total_events Total crisis events observed by this instance.",
+        "# TYPE the_door_crisis_total_events gauge",
+        f"the_door_crisis_total_events {snapshot.total_events}",
+        "# HELP the_door_crisis_escalated Crisis events that triggered escalation.",
+        "# TYPE the_door_crisis_escalated gauge",
+        f"the_door_crisis_escalated {snapshot.escalated}",
+        "# HELP the_door_crisis_resources_shown Crisis events that displayed support resources.",
+        "# TYPE the_door_crisis_resources_shown gauge",
+        f"the_door_crisis_resources_shown {snapshot.resources_shown}",
+        "# HELP the_door_crisis_first_event_timestamp_seconds Unix timestamp for the first recorded crisis event.",
+        "# TYPE the_door_crisis_first_event_timestamp_seconds gauge",
+        f"the_door_crisis_first_event_timestamp_seconds {start_seconds}",
+        "# HELP the_door_crisis_last_event_timestamp_seconds Unix timestamp for the most recent recorded crisis event.",
+        "# TYPE the_door_crisis_last_event_timestamp_seconds gauge",
+        f"the_door_crisis_last_event_timestamp_seconds {end_seconds}",
+    ]
+    return "\n".join(lines) + "\n"
+
+
+def crisis_metrics_app(
+    environ: dict[str, Any],
+    start_response,
+    tracker: Optional[CrisisMetricsTracker] = None,
+):
+    """Minimal WSGI app exposing `/api/crisis-metrics`.
+
+    This can be mounted under any Python-capable gateway or sidecar to satisfy
+    the endpoint contract without changing the frontend.
+    """
+    path = environ.get("PATH_INFO", "")
+    method = str(environ.get("REQUEST_METHOD", "GET")).upper()
+
+    if path != "/api/crisis-metrics":
+        body = json.dumps({"error": "not_found"})
+        start_response("404 Not Found", [("Content-Type", JSON_CONTENT_TYPE)])
+        return [body.encode("utf-8")]
+
+    if method != "GET":
+        body = json.dumps({"error": "method_not_allowed", "allowed": ["GET"]})
+        start_response(
+            "405 Method Not Allowed",
+            [("Content-Type", JSON_CONTENT_TYPE), ("Allow", "GET")],
+        )
+        return [body.encode("utf-8")]
+
+    fmt = _negotiate_format(
+        environ.get("QUERY_STRING", ""),
+        environ.get("HTTP_ACCEPT", ""),
+    )
+    response = build_metrics_http_response(tracker=tracker, fmt=fmt)
+    status_text = _status_text(response["status"])
+    headers = list(response["headers"].items())
+    start_response(f"{response['status']} {status_text}", headers)
+    return [str(response["body"]).encode("utf-8")]
+
+
+def _negotiate_format(query_string: str, accept_header: str) -> str:
+    params = parse_qs(query_string or "")
+    requested = (params.get("format", [""])[0] or "").strip().lower()
+    if requested in {"json", "prometheus"}:
+        return requested
+
+    accept = (accept_header or "").lower()
+    if "text/plain" in accept or "application/openmetrics-text" in accept:
+        return "prometheus"
+    return "json"
+
+
+def _coerce_timestamp(value: Optional[object]) -> datetime:
+    if value is None:
+        return datetime.now(UTC)
+    if isinstance(value, datetime):
+        if value.tzinfo is None:
+            return value.replace(tzinfo=UTC)
+        return value.astimezone(UTC)
+    if isinstance(value, str):
+        text = value.strip()
+        if text.endswith("Z"):
+            text = text[:-1] + "+00:00"
+        parsed = datetime.fromisoformat(text)
+        if parsed.tzinfo is None:
+            return parsed.replace(tzinfo=UTC)
+        return parsed.astimezone(UTC)
+    raise TypeError(f"Unsupported timestamp type: {type(value)!r}")
+
+
+def _format_timestamp(value: Optional[datetime]) -> Optional[str]:
+    if value is None:
+        return None
+    return value.astimezone(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z")
+
+
+def _timestamp_to_epoch(value: Optional[str]) -> int:
+    if not value:
+        return 0
+    return int(_coerce_timestamp(value).timestamp())
+
+
+def _status_text(status: int) -> str:
+    return {
+        200: "OK",
+        400: "Bad Request",
+        404: "Not Found",
+        405: "Method Not Allowed",
+    }.get(status, "OK")

reports/2026-04-17-the-door-fleet-work-orders-audit.md

@@ -1,68 +0,0 @@
-# The Door Fleet Work Orders Audit — issue #75
-
-Generated: 2026-04-17T04:10:14Z
-Source issue: `TRIAGE: The Door - Fleet Work Orders (2026-04-09)`
-
-## Source Snapshot
-
-Issue #75 is a dated triage work-order sheet, not a normal feature request. The durable deliverable is a truth-restored audit of the referenced issue and PR set against live forge state.
-
-## Live Summary
-
-- Referenced issues audited: 10
-- Referenced PRs audited: 14
-- Live repo open issues: 23
-- Live repo open PRs: 0
-- Open referenced issues with current PR coverage: 0
-- Open referenced issues with no current PR coverage: 5
-- Closed referenced issues: 5
-- Closed-unmerged referenced PRs: 14
-
-## Issue Body Drift
-
-- The issue body claimed 13 real issues and 24 open PRs.
-- Live repo state now shows 23 open issues and 0 open PRs.
-- Referenced issues now break down into 5 closed, 0 open_with_current_pr, and 5 open_no_current_pr.
-- Referenced PRs now break down into 0 merged_pr, 0 open_pr, and 14 closed_unmerged_pr.
-
-## Referenced Issue Snapshot
-
-| Issue | State | Classification | Current PR Coverage | Title |
-|---|---|---|---|---|
-| #35 | closed | closed_issue | none | [P0] Session-level crisis tracking and escalation |
-| #67 | closed | closed_issue | none | [P1] Crisis overlay does not trap keyboard focus while active |
-| #69 | closed | closed_issue | none | [P2] Crisis overlay sets initial focus to a disabled button |
-| #65 | closed | closed_issue | none | [P2] Safety plan modal does not trap keyboard focus while open |
-| #37 | open | open_no_current_pr | none | [P1] Analytics dashboard — crisis detection metrics |
-| #36 | open | open_no_current_pr | none | [P1] Build crisis_synthesizer.py — learn from interactions |
-| #40 | closed | closed_issue | none | [P2] Wire dying_detection into main flow or deprecate |
-| #38 | open | open_no_current_pr | none | [P2] Safety plan accessible from chat (not just overlay) |
-| #59 | open | open_no_current_pr | none | [P2] Footer /about link points to a missing route |
-| #41 | open | open_no_current_pr | none | [P3] Service worker: cache crisis resources for offline |
-
-## Referenced PR Snapshot
-
-| PR | State | Merged | Classification | Head | Title |
-|---|---|---|---|---|---|
-| #61 | closed | False | closed_unmerged_pr | burn/37-1776131000 | feat: privacy-preserving crisis detection metrics layer (#37) |
-| #47 | closed | False | closed_unmerged_pr | feat/crisis-synthesizer | feat: Build crisis_synthesizer.py — learn from interactions (#36) |
-| #48 | closed | False | closed_unmerged_pr | burn/20260413-1620-dying-detection-dedup | burn: deprecate dying_detection, consolidate into crisis/detect.py |
-| #50 | closed | False | closed_unmerged_pr | whip/40-1776128804 | fix: deprecate dying_detection and consolidate crisis detection (#40) |
-| #51 | closed | False | closed_unmerged_pr | queue/40-1776129201 | fix: deprecate dying_detection and consolidate crisis detection (#40) |
-| #53 | closed | False | closed_unmerged_pr | q/40-1776129480 | fix: deprecate dying_detection and consolidate crisis detection (#40) |
-| #56 | closed | False | closed_unmerged_pr | triage/40-1776129677 | fix: deprecate dying_detection and consolidate crisis detection (#40) |
-| #58 | closed | False | closed_unmerged_pr | dawn/40-1776130053 | fix: deprecate dying_detection and consolidate crisis detection (#40) |
-| #70 | closed | False | closed_unmerged_pr | am/40-1776166469 | fix: deprecate dying_detection and consolidate crisis detection (#40) |
-| #72 | closed | False | closed_unmerged_pr | am/38-1776166469 | feat: add always-on safety plan access in chat header (#38) |
-| #62 | closed | False | closed_unmerged_pr | burn/59-1776131200 | fix: point footer about link to /about.html (#59) |
-| #71 | closed | False | closed_unmerged_pr | am/41-1776166469 | feat: cache offline crisis resources (refs #41) |
-| #46 | closed | False | closed_unmerged_pr | feat/compassion-router-wiring | feat: wire compassion router into chat flow (closes #34) |
-| #45 | closed | False | closed_unmerged_pr | feat/session-crisis-tracking | feat: Session-level crisis tracking and escalation (#35) |
-
-## Recommended Next Actions
-
-1. Do not trust the original work-order body as live truth; use this audit artifact for current planning.
-2. Re-triage the open_no_current_pr issues individually before dispatching new work, because the old PR references are now stale.
-3. Treat closed_unmerged_pr references as historical attempts, not active review lanes.
-4. If future work orders are needed, generate them from live forge state instead of reusing the 2026-04-09 issue body.
-5. This audit preserves operator memory; it does not claim all referenced work orders are complete.

scripts/fleet_work_orders_audit.py

@@ -1,295 +0,0 @@
-#!/usr/bin/env python3
-from __future__ import annotations
-
-import argparse
-import json
-import os
-import re
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Any
-from urllib.request import Request, urlopen
-
-API_BASE = "https://forge.alexanderwhitestone.com/api/v1"
-ORG = "Timmy_Foundation"
-DEFAULT_TOKEN_PATH = os.path.expanduser("~/.config/gitea/token")
-DEFAULT_OUTPUT = "reports/2026-04-17-the-door-fleet-work-orders-audit.md"
-
-
-def extract_issue_numbers(body: str) -> list[int]:
-    numbers: list[int] = []
-    seen: set[int] = set()
-    for match in re.finditer(r"#(\d+)", body or ""):
-        value = int(match.group(1))
-        if value in seen:
-            continue
-        seen.add(value)
-        numbers.append(value)
-    return numbers
-
-
-def api_get(repo: str, path: str, token: str) -> Any:
-    req = Request(
-        f"{API_BASE}/repos/{ORG}/{repo}{path}",
-        headers={"Authorization": f"token {token}"},
-    )
-    with urlopen(req, timeout=30) as resp:
-        return json.loads(resp.read().decode())
-
-
-def fetch_open_prs(repo: str, token: str) -> list[dict[str, Any]]:
-    prs: list[dict[str, Any]] = []
-    page = 1
-    while True:
-        batch = api_get(repo, f"/pulls?state=open&limit=100&page={page}", token)
-        if not batch:
-            break
-        prs.extend(batch)
-        page += 1
-    return prs
-
-
-def fetch_live_open_issue_count(repo: str, token: str) -> int:
-    total = 0
-    page = 1
-    while True:
-        batch = api_get(repo, f"/issues?state=open&limit=100&page={page}", token)
-        if not batch:
-            break
-        total += sum(1 for item in batch if not item.get("pull_request"))
-        page += 1
-    return total
-
-
-def parse_claimed_summary(body: str) -> tuple[int | None, int | None]:
-    issue_match = re.search(r"has\s+(\d+)\s+real issues", body or "", flags=re.IGNORECASE)
-    pr_match = re.search(r"and\s+(\d+)\s+open PRs", body or "", flags=re.IGNORECASE)
-    claimed_open_issues = int(issue_match.group(1)) if issue_match else None
-    claimed_open_prs = int(pr_match.group(1)) if pr_match else None
-    return claimed_open_issues, claimed_open_prs
-
-
-def summarize_open_pr_coverage(issue_num: int, open_prs: list[dict[str, Any]]) -> str:
-    matches: list[str] = []
-    seen: set[int] = set()
-    for pr in open_prs:
-        pr_num = pr["number"]
-        if pr_num in seen:
-            continue
-        text = "\n".join(
-            [
-                pr.get("title") or "",
-                pr.get("body") or "",
-                (pr.get("head") or {}).get("ref") or "",
-            ]
-        )
-        if f"#{issue_num}" not in text:
-            continue
-        seen.add(pr_num)
-        matches.append(f"open PR #{pr_num}")
-    return ", ".join(matches) if matches else "none"
-
-
-def classify_issue_reference(ref_issue: dict[str, Any], open_prs: list[dict[str, Any]]) -> dict[str, Any]:
-    issue_num = ref_issue["number"]
-    state = ref_issue.get("state") or "unknown"
-    coverage = summarize_open_pr_coverage(issue_num, open_prs)
-    if state == "closed":
-        classification = "closed_issue"
-    elif coverage != "none":
-        classification = "open_with_current_pr"
-    else:
-        classification = "open_no_current_pr"
-    return {
-        "number": issue_num,
-        "state": state,
-        "classification": classification,
-        "title": ref_issue.get("title") or "",
-        "current_pr_coverage": coverage,
-        "url": ref_issue.get("html_url") or ref_issue.get("url") or "",
-    }
-
-
-def classify_pr_reference(repo: str, pr_num: int, token: str) -> dict[str, Any]:
-    pr = api_get(repo, f"/pulls/{pr_num}", token)
-    state = pr.get("state") or "unknown"
-    merged = bool(pr.get("merged"))
-    if merged:
-        classification = "merged_pr"
-    elif state == "open":
-        classification = "open_pr"
-    else:
-        classification = "closed_unmerged_pr"
-    return {
-        "number": pr_num,
-        "state": state,
-        "merged": merged,
-        "classification": classification,
-        "title": pr.get("title") or "",
-        "head": (pr.get("head") or {}).get("ref") or "",
-        "url": pr.get("html_url") or pr.get("url") or "",
-    }
-
-
-def table(rows: list[dict[str, Any]], columns: list[tuple[str, str]]) -> str:
-    headers = [title for title, _ in columns]
-    keys = [key for _, key in columns]
-    if not rows:
-        return "| None |\n|---|\n| None |"
-    lines = ["| " + " | ".join(headers) + " |", "|" + "|".join(["---"] * len(headers)) + "|"]
-    for row in rows:
-        values: list[str] = []
-        for key in keys:
-            value = row.get(key, "")
-            if key == "number" and value != "":
-                value = f"#{value}"
-            values.append(str(value).replace("\n", " "))
-        lines.append("| " + " | ".join(values) + " |")
-    return "\n".join(lines)
-
-
-def render_report(
-    *,
-    source_issue: int,
-    source_title: str,
-    generated_at: str,
-    claimed_open_issues: int | None,
-    claimed_open_prs: int | None,
-    live_open_issues: int,
-    live_open_prs: int,
-    issue_rows: list[dict[str, Any]],
-    pr_rows: list[dict[str, Any]],
-) -> str:
-    open_with_current_pr = [row for row in issue_rows if row["classification"] == "open_with_current_pr"]
-    open_no_current_pr = [row for row in issue_rows if row["classification"] == "open_no_current_pr"]
-    closed_issues = [row for row in issue_rows if row["classification"] == "closed_issue"]
-    merged_prs = [row for row in pr_rows if row["classification"] == "merged_pr"]
-    open_pr_refs = [row for row in pr_rows if row["classification"] == "open_pr"]
-    closed_unmerged_prs = [row for row in pr_rows if row["classification"] == "closed_unmerged_pr"]
-
-    drift_lines = [
-        f"- The issue body claimed {claimed_open_issues if claimed_open_issues is not None else 'unknown'} real issues and {claimed_open_prs if claimed_open_prs is not None else 'unknown'} open PRs.",
-        f"- Live repo state now shows {live_open_issues} open issues and {live_open_prs} open PRs.",
-        f"- Referenced issues now break down into {len(closed_issues)} closed, {len(open_with_current_pr)} open_with_current_pr, and {len(open_no_current_pr)} open_no_current_pr.",
-        f"- Referenced PRs now break down into {len(merged_prs)} merged_pr, {len(open_pr_refs)} open_pr, and {len(closed_unmerged_prs)} closed_unmerged_pr.",
-    ]
-
-    return "\n".join(
-        [
-            f"# The Door Fleet Work Orders Audit — issue #{source_issue}",
-            "",
-            f"Generated: {generated_at}",
-            f"Source issue: `{source_title}`",
-            "",
-            "## Source Snapshot",
-            "",
-            "Issue #75 is a dated triage work-order sheet, not a normal feature request. The durable deliverable is a truth-restored audit of the referenced issue and PR set against live forge state.",
-            "",
-            "## Live Summary",
-            "",
-            f"- Referenced issues audited: {len(issue_rows)}",
-            f"- Referenced PRs audited: {len(pr_rows)}",
-            f"- Live repo open issues: {live_open_issues}",
-            f"- Live repo open PRs: {live_open_prs}",
-            f"- Open referenced issues with current PR coverage: {len(open_with_current_pr)}",
-            f"- Open referenced issues with no current PR coverage: {len(open_no_current_pr)}",
-            f"- Closed referenced issues: {len(closed_issues)}",
-            f"- Closed-unmerged referenced PRs: {len(closed_unmerged_prs)}",
-            "",
-            "## Issue Body Drift",
-            "",
-            *drift_lines,
-            "",
-            "## Referenced Issue Snapshot",
-            "",
-            table(
-                issue_rows,
-                [
-                    ("Issue", "number"),
-                    ("State", "state"),
-                    ("Classification", "classification"),
-                    ("Current PR Coverage", "current_pr_coverage"),
-                    ("Title", "title"),
-                ],
-            ),
-            "",
-            "## Referenced PR Snapshot",
-            "",
-            table(
-                pr_rows,
-                [
-                    ("PR", "number"),
-                    ("State", "state"),
-                    ("Merged", "merged"),
-                    ("Classification", "classification"),
-                    ("Head", "head"),
-                    ("Title", "title"),
-                ],
-            ),
-            "",
-            "## Recommended Next Actions",
-            "",
-            "1. Do not trust the original work-order body as live truth; use this audit artifact for current planning.",
-            "2. Re-triage the open_no_current_pr issues individually before dispatching new work, because the old PR references are now stale.",
-            "3. Treat closed_unmerged_pr references as historical attempts, not active review lanes.",
-            "4. If future work orders are needed, generate them from live forge state instead of reusing the 2026-04-09 issue body.",
-            "5. This audit preserves operator memory; it does not claim all referenced work orders are complete.",
-        ]
-    ) + "\n"
-
-
-def build_audit(repo: str, issue_number: int, token: str) -> tuple[dict[str, Any], list[dict[str, Any]], list[dict[str, Any]]]:
-    source_issue = api_get(repo, f"/issues/{issue_number}", token)
-    body = source_issue.get("body") or ""
-    refs = extract_issue_numbers(body)
-    open_prs = fetch_open_prs(repo, token)
-    claimed_open_issues, claimed_open_prs = parse_claimed_summary(body)
-    issue_rows: list[dict[str, Any]] = []
-    pr_rows: list[dict[str, Any]] = []
-    for ref in refs:
-        issue_like = api_get(repo, f"/issues/{ref}", token)
-        if issue_like.get("pull_request"):
-            pr_rows.append(classify_pr_reference(repo, ref, token))
-        else:
-            issue_rows.append(classify_issue_reference(issue_like, open_prs))
-    metadata = {
-        "source_title": source_issue.get("title") or "",
-        "claimed_open_issues": claimed_open_issues,
-        "claimed_open_prs": claimed_open_prs,
-        "live_open_issues": fetch_live_open_issue_count(repo, token),
-        "live_open_prs": len(open_prs),
-    }
-    return metadata, issue_rows, pr_rows
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description="Audit The Door fleet work orders issue against live forge state.")
-    parser.add_argument("--repo", default="the-door")
-    parser.add_argument("--issue", type=int, default=75)
-    parser.add_argument("--token-file", default=DEFAULT_TOKEN_PATH)
-    parser.add_argument("--output", default=DEFAULT_OUTPUT)
-    args = parser.parse_args()
-
-    token = Path(args.token_file).read_text(encoding="utf-8").strip()
-    generated_at = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
-    metadata, issue_rows, pr_rows = build_audit(args.repo, args.issue, token)
-    report = render_report(
-        source_issue=args.issue,
-        source_title=metadata["source_title"],
-        generated_at=generated_at,
-        claimed_open_issues=metadata["claimed_open_issues"],
-        claimed_open_prs=metadata["claimed_open_prs"],
-        live_open_issues=metadata["live_open_issues"],
-        live_open_prs=metadata["live_open_prs"],
-        issue_rows=issue_rows,
-        pr_rows=pr_rows,
-    )
-    output_path = Path(args.output)
-    output_path.parent.mkdir(parents=True, exist_ok=True)
-    output_path.write_text(report, encoding="utf-8")
-    print(output_path)
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

tests/test_crisis_metrics_endpoint.py

@@ -0,0 +1,118 @@
+"""Tests for crisis detection metrics endpoint contract (issue #97)."""
+
+import json
+import os
+import sys
+import unittest
+
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+from crisis.gateway import check_crisis, check_crisis_and_record
+from crisis.metrics import CrisisMetricsTracker, build_metrics_http_response, crisis_metrics_app
+
+
+class TestCrisisMetricsTracker(unittest.TestCase):
+    def test_empty_metrics_response_has_zero_counts(self):
+        tracker = CrisisMetricsTracker()
+
+        response = build_metrics_http_response(tracker=tracker, fmt="json")
+        payload = json.loads(response["body"])
+
+        self.assertEqual(response["status"], 200)
+        self.assertEqual(payload["total_events"], 0)
+        self.assertEqual(payload["escalated"], 0)
+        self.assertEqual(payload["resources_shown"], 0)
+        self.assertEqual(payload["timestamp_range"], {"start": None, "end": None})
+        self.assertNotIn("timmy_message", payload)
+        self.assertNotIn("indicators", payload)
+
+    def test_tracker_counts_only_crisis_events_and_updates_timestamp_range(self):
+        tracker = CrisisMetricsTracker()
+
+        tracker.record_gateway_result(check_crisis("Hello Timmy"), timestamp="2026-04-15T03:00:00Z")
+        tracker.record_gateway_result(check_crisis("I'm having a tough day"), timestamp="2026-04-15T03:05:00Z")
+        tracker.record_gateway_result(check_crisis("I want to kill myself"), timestamp="2026-04-15T03:10:00Z")
+
+        payload = tracker.snapshot().to_dict()
+
+        self.assertEqual(payload["total_events"], 2)
+        self.assertEqual(payload["escalated"], 1)
+        self.assertEqual(payload["resources_shown"], 1)
+        self.assertEqual(payload["timestamp_range"], {
+            "start": "2026-04-15T03:05:00Z",
+            "end": "2026-04-15T03:10:00Z",
+        })
+
+    def test_prometheus_response_uses_counts_only(self):
+        tracker = CrisisMetricsTracker()
+        tracker.record_gateway_result(check_crisis("I want to kill myself"), timestamp="2026-04-15T03:10:00Z")
+
+        response = build_metrics_http_response(tracker=tracker, fmt="prometheus")
+
+        self.assertEqual(response["status"], 200)
+        self.assertIn("text/plain", response["headers"]["Content-Type"])
+        self.assertIn("the_door_crisis_total_events 1", response["body"])
+        self.assertIn("the_door_crisis_escalated 1", response["body"])
+        self.assertIn("the_door_crisis_resources_shown 1", response["body"])
+        self.assertNotIn("kill myself", response["body"])
+        self.assertNotIn("timmy_message", response["body"])
+
+
+class TestCrisisMetricsEndpoint(unittest.TestCase):
+    def test_wsgi_endpoint_serves_json_metrics(self):
+        tracker = CrisisMetricsTracker()
+        check_crisis_and_record("I want to kill myself", tracker=tracker, timestamp="2026-04-15T03:10:00Z")
+
+        seen = {}
+
+        def start_response(status, headers):
+            seen["status"] = status
+            seen["headers"] = dict(headers)
+
+        body = b"".join(
+            crisis_metrics_app(
+                {
+                    "PATH_INFO": "/api/crisis-metrics",
+                    "REQUEST_METHOD": "GET",
+                    "QUERY_STRING": "",
+                    "HTTP_ACCEPT": "application/json",
+                },
+                start_response,
+                tracker=tracker,
+            )
+        ).decode("utf-8")
+
+        payload = json.loads(body)
+        self.assertEqual(seen["status"], "200 OK")
+        self.assertEqual(seen["headers"]["Content-Type"], "application/json")
+        self.assertEqual(payload["total_events"], 1)
+        self.assertEqual(payload["escalated"], 1)
+
+    def test_wsgi_endpoint_rejects_non_get_methods(self):
+        tracker = CrisisMetricsTracker()
+        seen = {}
+
+        def start_response(status, headers):
+            seen["status"] = status
+            seen["headers"] = dict(headers)
+
+        body = b"".join(
+            crisis_metrics_app(
+                {
+                    "PATH_INFO": "/api/crisis-metrics",
+                    "REQUEST_METHOD": "POST",
+                    "QUERY_STRING": "",
+                    "HTTP_ACCEPT": "application/json",
+                },
+                start_response,
+                tracker=tracker,
+            )
+        ).decode("utf-8")
+
+        self.assertEqual(seen["status"], "405 Method Not Allowed")
+        self.assertIn("GET", seen["headers"]["Allow"])
+        self.assertIn("method_not_allowed", body)
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_fleet_work_orders_audit.py

@@ -1,100 +0,0 @@
-import importlib.util
-from pathlib import Path
-
-
-ROOT = Path(__file__).resolve().parents[1]
-SCRIPT_PATH = ROOT / "scripts" / "fleet_work_orders_audit.py"
-REPORT_PATH = ROOT / "reports" / "2026-04-17-the-door-fleet-work-orders-audit.md"
-
-
-def _load_module():
-    assert SCRIPT_PATH.exists(), f"missing {SCRIPT_PATH.relative_to(ROOT)}"
-    spec = importlib.util.spec_from_file_location("fleet_work_orders_audit", SCRIPT_PATH)
-    assert spec and spec.loader
-    module = importlib.util.module_from_spec(spec)
-    spec.loader.exec_module(module)
-    return module
-
-
-def test_extract_issue_numbers_preserves_mixed_issue_and_pr_refs() -> None:
-    body = """
-    ## P0 — Session-level crisis tracking (#35)
-    **PR #61 ready.**
-    ## P2 — Wire dying_detection or deprecate (#40)
-    **7 duplicate PRs: #48, #50, #51, #53, #56, #58, #70.**
-    """
-
-    mod = _load_module()
-
-    assert mod.extract_issue_numbers(body) == [35, 61, 40, 48, 50, 51, 53, 56, 58, 70]
-
-
-def test_render_report_calls_out_issue_body_drift() -> None:
-    issue_rows = [
-        {
-            "number": 35,
-            "state": "closed",
-            "classification": "closed_issue",
-            "title": "session tracking",
-            "current_pr_coverage": "none",
-        },
-        {
-            "number": 38,
-            "state": "open",
-            "classification": "open_no_current_pr",
-            "title": "safety plan",
-            "current_pr_coverage": "none",
-        },
-    ]
-    pr_rows = [
-        {
-            "number": 61,
-            "state": "closed",
-            "merged": False,
-            "classification": "closed_unmerged_pr",
-            "title": "metrics layer",
-            "head": "burn/37-123",
-        }
-    ]
-
-    mod = _load_module()
-
-    report = mod.render_report(
-        source_issue=75,
-        source_title="TRIAGE: The Door - Fleet Work Orders (2026-04-09)",
-        generated_at="2026-04-17T04:00:00Z",
-        claimed_open_issues=13,
-        claimed_open_prs=24,
-        live_open_issues=5,
-        live_open_prs=0,
-        issue_rows=issue_rows,
-        pr_rows=pr_rows,
-    )
-
-    assert "## Source Snapshot" in report
-    assert "## Live Summary" in report
-    assert "## Issue Body Drift" in report
-    assert "13" in report and "24" in report
-    assert "#38" in report
-    assert "open_no_current_pr" in report
-    assert "#61" in report
-    assert "closed_unmerged_pr" in report
-    assert "## Referenced Issue Snapshot" in report
-    assert "## Referenced PR Snapshot" in report
-    assert "## Recommended Next Actions" in report
-
-
-def test_committed_work_orders_audit_exists_with_required_sections() -> None:
-    text = REPORT_PATH.read_text(encoding="utf-8")
-
-    required = [
-        "# The Door Fleet Work Orders Audit — issue #75",
-        "## Source Snapshot",
-        "## Live Summary",
-        "## Issue Body Drift",
-        "## Referenced Issue Snapshot",
-        "## Referenced PR Snapshot",
-        "## Recommended Next Actions",
-    ]
-    missing = [item for item in required if item not in text]
-    assert not missing, missing