devtorch-core 3.0.1__py3-none-any.whl

devtorch_core/dashboard_api.py

@@ -0,0 +1,2012 @@
+"""
+Sprint 13 – Browser-based Org Dashboard REST API.
+
+Serves governance state from a local `.GCC/` directory over HTTP.
+This is a read-only surface: it never writes to `.GCC/`.
+
+Endpoints
+---------
+GET /api/v1/dashboard         → DashboardData (full snapshot)
+GET /api/v1/branches          → list[BranchSummary]
+GET /api/v1/sensitivities     → list[SensitivityEvent] (query: limit=50)
+
+Usage
+-----
+    from devtorch_core.dashboard_api import run_dashboard_api
+    run_dashboard_api(port=8766, host="127.0.0.1", gcc_repo="/path/to/project")
+
+Or run directly:
+    python -m devtorch_core.dashboard_api --port 8766 --repo /path/to/project
+"""
+
+from __future__ import annotations
+
+import asyncio
+import datetime as _dt
+import json
+import math
+import os
+import subprocess
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from devtorch_core.projects import ProjectRegistry
+from devtorch_core.metrics.aggregate import (
+    aggregate_tokens,
+    aggregate_speedup,
+)
+from devtorch_core.metrics.shadow_ai import detect_shadow_ai
+from devtorch_core.metrics.delivery_time import compute_delivery_time_summary
+from devtorch_core.metrics.sprint_writer import (
+    compute_sprint_metrics as _compute_sprint_metrics,
+    read_sprint_metrics as _read_sprint_metrics,
+)
+from devtorch_core.broadcast import EventBroadcaster, GCCWatcher
+
+try:
+    from fastapi import FastAPI, HTTPException, Query, Response
+    from fastapi.middleware.cors import CORSMiddleware
+    from fastapi.responses import JSONResponse, PlainTextResponse, StreamingResponse
+    from pydantic import BaseModel
+    import uvicorn
+    _FASTAPI_AVAILABLE = True
+except ImportError:  # pragma: no cover
+    _FASTAPI_AVAILABLE = False
+
+    class BaseModel:  # type: ignore[no-redef]
+        """Fallback when FastAPI/Pydantic are not installed."""
+
+        def __init__(self, **data: Any) -> None:
+            pass
+
+
+# ---------------------------------------------------------------------------
+# Pydantic response models (mirrors src/api/types.ts)
+# ---------------------------------------------------------------------------
+
+class GCCStatusModel(BaseModel):
+    branch: str
+    nodeState: str
+    lastCommitId: str
+    locked: bool
+    lockReason: Optional[str] = None
+
+
+class ThetaEntryModel(BaseModel):
+    concept: str
+    meanConfidence: float
+    eventCount: int
+    disclosureLevel: Optional[str] = None
+    lastUpdated: Optional[str] = None
+
+
+class SensitivityEventModel(BaseModel):
+    id: str
+    timestamp: str
+    concept: str
+    disclosureLevel: int
+    signal: str
+    confidence: Optional[float] = None
+    sourceNode: Optional[str] = None
+
+
+class BranchSummaryModel(BaseModel):
+    name: str
+    tipCommitId: str
+    commitCount: int
+    mcsScore: Optional[float] = None
+    gitSha: Optional[str] = None
+
+
+class DashboardSavingsModel(BaseModel):
+    tokensUsed: int
+    tokensSaved: int
+    latencySpeedup: float
+
+
+class DashboardDataModel(BaseModel):
+    status: GCCStatusModel
+    theta: List[ThetaEntryModel]
+    recentSensitivities: List[SensitivityEventModel]
+    branches: List[BranchSummaryModel]
+    lastUpdated: str
+    githubUrl: Optional[str] = None
+    savings: DashboardSavingsModel
+
+
+class RDPBudgetModel(BaseModel):
+    epsilon_used: float
+    epsilon_max: float
+    read_only: bool
+    exhausted: bool
+
+
+class ConformanceModel(BaseModel):
+    I1_commit_backed: bool
+    I3_semantic_grounding: bool
+    A1_capability_gate: bool
+    A2_variance_control: bool
+    A3_sis_quarantine: bool
+    A4_deltaf_bound: bool
+
+
+class ProjectSummaryModel(BaseModel):
+    name: str
+    path: str
+    branch: str
+    lastCommitId: str
+    lastActivity: str
+    tokensUsed30d: int
+    tokensSaved30d: int
+    latencySpeedup: float
+    healthScore: Optional[float] = None
+    healthLabel: str
+
+
+class OrgDependencyNodeModel(BaseModel):
+    id: str
+    name: str
+    path: str
+    healthScore: Optional[float] = None
+
+
+class OrgDependencyEdgeModel(BaseModel):
+    source: str
+    target: str
+    concept: str
+    weight: float
+
+
+class OrgDependencyGraphModel(BaseModel):
+    nodes: List[OrgDependencyNodeModel]
+    edges: List[OrgDependencyEdgeModel]
+
+
+class ProjectsSavingsModel(BaseModel):
+    projects: List[ProjectSummaryModel]
+    aggregateTokensUsed: int
+    aggregateTokensSaved: int
+    aggregateLatencySpeedup: float
+
+
+class SensitivitySummaryModel(BaseModel):
+    total: int
+    by_disclosure_level: Dict[str, int]
+    high_disclosure_count: int
+
+
+class CISODataModel(BaseModel):
+    rdp_budget: RDPBudgetModel
+    conformance: ConformanceModel
+    sensitivity_summary: SensitivitySummaryModel
+    sis_quarantine_count: int
+    variance_alert_count: int
+    last_pst_passed: Optional[bool] = None
+    last_updated: str
+
+
+# S13 / S14 models -----------------------------------------------------------
+
+class ForensicEventModel(BaseModel):
+    ts: str
+    type: str
+    detail: str
+    raw: Dict[str, Any]
+
+
+class ForensicTimelineModel(BaseModel):
+    events: List[ForensicEventModel]
+
+
+class AgentContributionModel(BaseModel):
+    agent_id: str
+    confidence: float
+    message: str
+
+
+class CollisionModel(BaseModel):
+    concept: str
+    agents: List[AgentContributionModel]
+    severity: str  # "HIGH" | "MEDIUM" | "LOW"
+
+
+class SprintSummaryModel(BaseModel):
+    total_commits: int
+    commits_per_branch: Dict[str, int]
+    i3_violations: int
+    collisions_detected: int
+    top_concepts: List[ThetaEntryModel]
+    mcs_note: str
+
+
+class MCSTrendPointModel(BaseModel):
+    date: str          # ISO date "2026-04-13"
+    mcs: Optional[float]   # None = no events that day
+    eventCount: int
+
+
+class AuditExportMetaModel(BaseModel):
+    exported_at: str
+    gcc_version: str
+    event_count: int
+    events: List[Dict[str, Any]]
+
+
+class ShadowAIModel(BaseModel):
+    git_commits: int
+    gcc_commits: int
+    unregistered: int
+    shadow_ratio: float
+    flagged: bool
+
+
+class CompliancePostureModel(BaseModel):
+    event_log_integrity: bool
+    i1_compliance_rate: float
+    rdp_budget_exhausted: bool
+    rdp_read_only: bool
+    private_span_count: int
+    sis_quarantine_count: int
+    variance_alert_count: int
+    overall_score: int
+
+
+class GovernancePolicyModel(BaseModel):
+    allowed_models: List[str]
+    max_tokens_per_session: int
+    racp_compliance_required: bool
+    racp_compliance_threshold: float
+    require_devtorch_commit: bool
+    blocked_concepts: List[str]
+
+
+class ConceptDriftResponseModel(BaseModel):
+    concepts: List[str]
+    time_labels: List[str]
+    matrix: List[List[float]]
+    mean_confidences: List[List[float]]
+    event_counts: List[List[int]]
+
+
+class SprintMetricsModel(BaseModel):
+    sprint_id: str
+    mcs_score: float
+    i3_violations: int
+    collisions_prevented: int
+    override_rate: float
+    acceptance_rate: float
+    branch_count: int
+    commit_count: int
+
+
+class DeliveryTimeTrendPointModel(BaseModel):
+    date: str
+    current_min: float
+    baseline_min: float
+    delta_min: float
+
+
+# ---------------------------------------------------------------------------
+# GCC reader helpers (read-only; never write)
+# ---------------------------------------------------------------------------
+
+GCC_DIR_NAME = ".GCC"
+REFS_DIR_NAME = "refs"
+BRANCHES_DIR_NAME = "branches"
+HEAD_FILE_NAME = "HEAD"
+COMMITS_DIR_NAME = "commits"
+NODE_STATE_FILE_NAME = "NODE_STATE"
+CONSENSUS_LOCK_FILE = "consensus_lock.json"
+SENSITIVITIES_DIR_NAME = "sensitivities"
+SENSITIVITY_EVENTS_FILE = "events.jsonl"
+THETA_FILE = "theta.json"
+
+# Map string disclosure levels to int for the API model
+_DISCLOSURE_INT: Dict[str, int] = {
+    "PUBLIC": 0,
+    "PROTECTED": 1,
+    "PRIVATE": 2,
+}
+
+
+def _gcc_dir(gcc_repo: Path) -> Path:
+    return gcc_repo / GCC_DIR_NAME
+
+
+def _is_initialized(gcc_repo: Path) -> bool:
+    return (_gcc_dir(gcc_repo) / "VERSION").exists()
+
+
+def _read_current_branch(gcc_repo: Path) -> str:
+    head = _gcc_dir(gcc_repo) / REFS_DIR_NAME / HEAD_FILE_NAME
+    if not head.exists():
+        return "main"
+    return head.read_text(encoding="utf-8").strip() or "main"
+
+
+def _read_branch_tip(gcc_repo: Path, branch: str) -> str:
+    ref = _gcc_dir(gcc_repo) / REFS_DIR_NAME / BRANCHES_DIR_NAME / branch
+    if not ref.exists():
+        return ""
+    return ref.read_text(encoding="utf-8").strip()
+
+
+def _read_node_state(gcc_repo: Path) -> str:
+    node_state_file = _gcc_dir(gcc_repo) / NODE_STATE_FILE_NAME
+    if not node_state_file.exists():
+        return "ACTIVE"
+    try:
+        data = json.loads(node_state_file.read_text(encoding="utf-8"))
+        mode = data.get("mode", "idle")
+        # Map internal modes to display states
+        mode_map = {
+            "running": "ACTIVE",
+            "idle": "ACTIVE",
+            "paused": "DEGRADED",
+            "error": "ISOLATED",
+        }
+        return mode_map.get(mode.lower(), mode.upper())
+    except (json.JSONDecodeError, OSError):
+        return "ACTIVE"
+
+
+def _read_lock_state(gcc_repo: Path) -> tuple[bool, Optional[str]]:
+    lock_file = _gcc_dir(gcc_repo) / CONSENSUS_LOCK_FILE
+    if not lock_file.exists():
+        return False, None
+    try:
+        data = json.loads(lock_file.read_text(encoding="utf-8"))
+        locked = bool(data.get("locked", False))
+        reason = data.get("reason") if locked else None
+        return locked, reason
+    except (json.JSONDecodeError, OSError):
+        return False, None
+
+
+def _read_gcc_status(gcc_repo: Path) -> GCCStatusModel:
+    branch = _read_current_branch(gcc_repo)
+    last_commit_id = _read_branch_tip(gcc_repo, branch)
+    node_state = _read_node_state(gcc_repo)
+    locked, lock_reason = _read_lock_state(gcc_repo)
+    return GCCStatusModel(
+        branch=branch,
+        nodeState=node_state,
+        lastCommitId=last_commit_id,
+        locked=locked,
+        lockReason=lock_reason,
+    )
+
+
+def _compute_health_score(gcc_repo: Path) -> Optional[float]:
+    """Best-effort Deployment Health Score proxy (0-100)."""
+    try:
+        from devtorch_core.metrics.shadow_ai import detect_shadow_ai
+        from devtorch_core.metrics.dhs import DHSComponents, compute_dhs
+
+        shadow = detect_shadow_ai(gcc_repo.parent)
+        components = DHSComponents(
+            commit_health=1.0 if shadow.get("gcc_commits", 0) > 0 else 0.0,
+            sensitivity_health=1.0,
+            capability_health=0.0,
+            variance_health=1.0,
+        )
+        return compute_dhs(components)
+    except Exception:
+        return None
+
+
+def _health_label(score: Optional[float]) -> str:
+    if score is None:
+        return "UNKNOWN"
+    if score >= 90:
+        return "AUTONOMOUS"
+    if score >= 75:
+        return "STANDARD"
+    if score >= 60:
+        return "REVIEW"
+    return "BLOCKED"
+
+
+def _read_theta(gcc_repo: Path) -> List[ThetaEntryModel]:
+    theta_file = _gcc_dir(gcc_repo) / THETA_FILE
+    if not theta_file.exists():
+        return []
+    try:
+        data = json.loads(theta_file.read_text(encoding="utf-8"))
+        cv: Dict[str, Any] = data.get("coordination_vector", {})
+        entries: List[ThetaEntryModel] = []
+        for concept, info in cv.items():
+            entries.append(
+                ThetaEntryModel(
+                    concept=concept,
+                    meanConfidence=float(info.get("mean_confidence", 0.0)),
+                    eventCount=int(info.get("event_count", 0)),
+                    disclosureLevel=info.get("disclosure_level"),
+                    lastUpdated=info.get("last_updated"),
+                )
+            )
+        # Sort by confidence descending for consistent presentation
+        entries.sort(key=lambda e: e.meanConfidence, reverse=True)
+        return entries
+    except (json.JSONDecodeError, OSError, KeyError):
+        return []
+
+
+def _disclosure_str_to_int(level: str) -> int:
+    """Convert disclosure level string to integer. Supports both str and int inputs."""
+    if isinstance(level, int):
+        return level
+    return _DISCLOSURE_INT.get(str(level).upper(), 0)
+
+
+def _read_sensitivities(gcc_repo: Path, limit: int = 50, concept: Optional[str] = None) -> List[SensitivityEventModel]:
+    events_file = (
+        _gcc_dir(gcc_repo) / SENSITIVITIES_DIR_NAME / SENSITIVITY_EVENTS_FILE
+    )
+    if not events_file.exists():
+        return []
+    raw_events: List[dict] = []
+    try:
+        with events_file.open("r", encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    raw_events.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    except OSError:
+        return []
+
+    # Newest first; apply concept filter before slicing so limit is per-concept
+    raw_events = raw_events[::-1]
+    if concept:
+        raw_events = [
+            ev for ev in raw_events
+            if ev.get("target_concept", ev.get("concept", "")) == concept
+        ]
+    raw_events = raw_events[:limit]
+
+    result: List[SensitivityEventModel] = []
+    for ev in raw_events:
+        ev_concept = ev.get("target_concept", ev.get("concept", "unknown"))
+        signal = ev.get("counterfactuals", ev.get("message", ev.get("signal", "")))
+        timestamp = ev.get("created_at", ev.get("timestamp", ""))
+        disclosure_raw = ev.get("disclosure_level", "PUBLIC")
+        raw_conf = ev.get("confidence")
+        confidence = float(raw_conf) if raw_conf is not None else None
+        result.append(
+            SensitivityEventModel(
+                id=ev.get("event_id", ev.get("id", "")),
+                timestamp=timestamp,
+                concept=ev_concept,
+                disclosureLevel=_disclosure_str_to_int(disclosure_raw),
+                signal=str(signal),
+                confidence=confidence,
+                sourceNode=ev.get("source_node"),
+            )
+        )
+    return result
+
+
+def _list_branch_names(gcc_repo: Path) -> List[str]:
+    branches_dir = _gcc_dir(gcc_repo) / REFS_DIR_NAME / BRANCHES_DIR_NAME
+    if not branches_dir.exists():
+        return []
+    return sorted(
+        p.name for p in branches_dir.iterdir() if p.is_file()
+    )
+
+
+def _count_commits(gcc_repo: Path, branch: str) -> int:
+    """Walk commit chain for branch and count commits."""
+    tip = _read_branch_tip(gcc_repo, branch)
+    if not tip:
+        return 0
+    commits_dir = _gcc_dir(gcc_repo) / COMMITS_DIR_NAME
+    count = 0
+    current = tip
+    visited: set = set()
+    while current and current not in visited:
+        visited.add(current)
+        commit_file = commits_dir / f"{current}.json"
+        if not commit_file.exists():
+            break
+        try:
+            obj = json.loads(commit_file.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            break
+        count += 1
+        current = obj.get("parent") or ""
+    return count
+
+
+def _get_github_url(gcc_repo: Path) -> Optional[str]:
+    """Return the GitHub web URL for the repo (https://github.com/user/repo), or None."""
+    try:
+        r = subprocess.run(
+            ["git", "remote", "get-url", "origin"],
+            capture_output=True, text=True, cwd=gcc_repo, timeout=5,
+        )
+        if r.returncode != 0:
+            return None
+        url = r.stdout.strip()
+        # SSH → HTTPS: git@github.com:user/repo.git → https://github.com/user/repo
+        if url.startswith("git@"):
+            url = url.replace(":", "/", 1).replace("git@", "https://")
+        if url.endswith(".git"):
+            url = url[:-4]
+        return url or None
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+
+
+def _get_git_sha(gcc_repo: Path, branch: str) -> Optional[str]:
+    """Return the full git SHA for the tip of a branch, or None if not found."""
+    try:
+        r = subprocess.run(
+            ["git", "rev-parse", branch],
+            capture_output=True, text=True, cwd=gcc_repo, timeout=5,
+        )
+        if r.returncode != 0:
+            return None
+        sha = r.stdout.strip()
+        return sha if sha else None
+    except (OSError, subprocess.TimeoutExpired):
+        return None
+
+
+def _read_branches(gcc_repo: Path) -> List[BranchSummaryModel]:
+    names = _list_branch_names(gcc_repo)
+    result: List[BranchSummaryModel] = []
+    for name in names:
+        tip = _read_branch_tip(gcc_repo, name)
+        commit_count = _count_commits(gcc_repo, name)
+        result.append(
+            BranchSummaryModel(
+                name=name,
+                tipCommitId=tip,
+                commitCount=commit_count,
+                mcsScore=None,  # MCS not yet computed per-branch in S13
+                gitSha=_get_git_sha(gcc_repo, name),
+            )
+        )
+    return result
+
+
+def _read_rdp_budget(gcc_repo: Path) -> RDPBudgetModel:
+    rdp_file = _gcc_dir(gcc_repo) / "rdp" / "rdp_state.json"
+    defaults = RDPBudgetModel(epsilon_used=0.0, epsilon_max=1.0, read_only=False, exhausted=False)
+    if not rdp_file.exists():
+        return defaults
+    try:
+        data = json.loads(rdp_file.read_text(encoding="utf-8"))
+        epsilon_used = float(data.get("epsilon_used", 0.0))
+        epsilon_max = float(data.get("epsilon_max", data.get("epsilon_budget", 1.0)))
+        read_only = bool(data.get("read_only", False))
+        exhausted = bool(data.get("exhausted", read_only))
+        return RDPBudgetModel(
+            epsilon_used=epsilon_used,
+            epsilon_max=epsilon_max,
+            read_only=read_only,
+            exhausted=exhausted,
+        )
+    except (json.JSONDecodeError, OSError, TypeError, ValueError):
+        return defaults
+
+
+def _read_conformance(gcc_repo: Path) -> ConformanceModel:
+    gcc = _gcc_dir(gcc_repo)
+    # I1: commits/ non-empty
+    try:
+        commits_dir = gcc / "commits"
+        i1 = commits_dir.exists() and any(True for _ in commits_dir.iterdir())
+    except OSError:
+        i1 = False
+    # I3: concepts/ non-empty
+    try:
+        concepts_dir = gcc / "concepts"
+        i3 = concepts_dir.exists() and any(True for _ in concepts_dir.iterdir())
+    except OSError:
+        i3 = False
+    # A1: capabilities/omega.json exists
+    a1 = (gcc / "capabilities" / "omega.json").exists()
+    # A2: variance/ directory exists
+    a2 = (gcc / "variance").exists()
+    # A3: sis/ directory exists
+    a3 = (gcc / "sis").exists()
+    # A4: deltaf/deltaf_report.json exists
+    a4 = (gcc / "deltaf" / "deltaf_report.json").exists()
+    return ConformanceModel(
+        I1_commit_backed=i1,
+        I3_semantic_grounding=i3,
+        A1_capability_gate=a1,
+        A2_variance_control=a2,
+        A3_sis_quarantine=a3,
+        A4_deltaf_bound=a4,
+    )
+
+
+def _read_sensitivity_summary(gcc_repo: Path) -> SensitivitySummaryModel:
+    events_file = _gcc_dir(gcc_repo) / SENSITIVITIES_DIR_NAME / SENSITIVITY_EVENTS_FILE
+    by_level: Dict[str, int] = {"1": 0, "2": 0, "3": 0, "4": 0, "5": 0}
+    total = 0
+    if events_file.exists():
+        try:
+            with events_file.open("r", encoding="utf-8") as fh:
+                for line in fh:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        ev = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    total += 1
+                    raw = ev.get("disclosure_level", 0)
+                    # Normalize: string names map to int, numeric strings kept as-is
+                    if isinstance(raw, str):
+                        # Try numeric string first
+                        try:
+                            level_int = int(raw)
+                        except ValueError:
+                            # Named levels: treat PUBLIC=1, PROTECTED=3, PRIVATE=5
+                            name_map = {
+                                "PUBLIC": 1,
+                                "PROTECTED": 3,
+                                "PRIVATE": 5,
+                            }
+                            level_int = name_map.get(raw.upper(), 1)
+                    else:
+                        level_int = int(raw)
+                    key = str(max(1, min(5, level_int)))
+                    by_level[key] = by_level.get(key, 0) + 1
+        except OSError:
+            pass
+    high_disclosure_count = by_level.get("4", 0) + by_level.get("5", 0)
+    return SensitivitySummaryModel(
+        total=total,
+        by_disclosure_level=by_level,
+        high_disclosure_count=high_disclosure_count,
+    )
+
+
+def _read_sis_quarantine_count(gcc_repo: Path) -> int:
+    sis_report = _gcc_dir(gcc_repo) / "sis" / "sis_tc_report.json"
+    if not sis_report.exists():
+        return 0
+    try:
+        data = json.loads(sis_report.read_text(encoding="utf-8"))
+        return int(data.get("quarantine_count", data.get("quarantined_count", 0)))
+    except (json.JSONDecodeError, OSError, TypeError, ValueError):
+        return 0
+
+
+def _read_variance_alert_count(gcc_repo: Path) -> int:
+    events_log = _gcc_dir(gcc_repo) / "events.log.jsonl"
+    if not events_log.exists():
+        return 0
+    count = 0
+    try:
+        with events_log.open("r", encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    ev = json.loads(line)
+                    if ev.get("event_type") == "VARIANCE_ALERT":
+                        count += 1
+                except json.JSONDecodeError:
+                    continue
+    except OSError:
+        pass
+    return count
+
+
+def _read_last_pst_passed(gcc_repo: Path) -> Optional[bool]:
+    pst_dir = _gcc_dir(gcc_repo) / "pst_reports"
+    if not pst_dir.exists():
+        return None
+    try:
+        report_files = sorted(
+            (f for f in pst_dir.iterdir() if f.suffix == ".json"),
+            key=lambda p: p.name,
+        )
+        if not report_files:
+            return None
+        latest = report_files[-1]
+        data = json.loads(latest.read_text(encoding="utf-8"))
+        passed = data.get("passed")
+        if passed is None:
+            return None
+        return bool(passed)
+    except (OSError, json.JSONDecodeError):
+        return None
+
+
+def _read_ciso_data(gcc_repo: Path) -> CISODataModel:
+    rdp_budget = _read_rdp_budget(gcc_repo)
+    conformance = _read_conformance(gcc_repo)
+    sensitivity_summary = _read_sensitivity_summary(gcc_repo)
+    sis_quarantine_count = _read_sis_quarantine_count(gcc_repo)
+    variance_alert_count = _read_variance_alert_count(gcc_repo)
+    last_pst_passed = _read_last_pst_passed(gcc_repo)
+    last_updated = _dt.datetime.now(tz=_dt.timezone.utc).isoformat()
+    return CISODataModel(
+        rdp_budget=rdp_budget,
+        conformance=conformance,
+        sensitivity_summary=sensitivity_summary,
+        sis_quarantine_count=sis_quarantine_count,
+        variance_alert_count=variance_alert_count,
+        last_pst_passed=last_pst_passed,
+        last_updated=last_updated,
+    )
+
+
+def _event_log_integrity_ok(gcc_repo: Path) -> bool:
+    """Best-effort hash-chain integrity check over events.log.jsonl."""
+    from devtorch_core.signing import verify_log
+    try:
+        return len(verify_log(_gcc_dir(gcc_repo))) == 0
+    except Exception:
+        return False
+
+
+def _read_governance_policy(gcc_repo: Path) -> GovernancePolicyModel:
+    """Read the project governance policy file (.GCC/policy.json) or return defaults."""
+    policy_file = _gcc_dir(gcc_repo) / "policy.json"
+    try:
+        from devtorch_core.gateway.policy import GovernancePolicy
+        policy = GovernancePolicy.load_from_file(str(policy_file))
+    except Exception:
+        policy = None
+    if policy is None:
+        return GovernancePolicyModel(
+            allowed_models=[],
+            max_tokens_per_session=1_000_000,
+            racp_compliance_required=False,
+            racp_compliance_threshold=0.0,
+            require_devtorch_commit=False,
+            blocked_concepts=[],
+        )
+    return GovernancePolicyModel(
+        allowed_models=policy.allowed_models,
+        max_tokens_per_session=policy.max_tokens_per_session,
+        racp_compliance_required=policy.racp_compliance_required,
+        racp_compliance_threshold=policy.racp_compliance_threshold,
+        require_devtorch_commit=policy.require_devtorch_commit,
+        blocked_concepts=policy.blocked_concepts,
+    )
+
+
+def _read_compliance_posture(gcc_repo: Path) -> CompliancePostureModel:
+    rdp = _read_rdp_budget(gcc_repo)
+    shadow = detect_shadow_ai(gcc_repo)
+    git_commits = max(1, shadow["git_commits"])
+    gcc_commits = shadow["gcc_commits"]
+    i1_rate = min(1.0, gcc_commits / git_commits)
+    private_count = _read_sensitivity_summary(gcc_repo).high_disclosure_count
+    sis_quarantine_count = _read_sis_quarantine_count(gcc_repo)
+    variance_alert_count = _read_variance_alert_count(gcc_repo)
+    integrity_ok = _event_log_integrity_ok(gcc_repo)
+
+    score = 100
+    if not integrity_ok:
+        score -= 25
+    if i1_rate < 0.5:
+        score -= 25
+    if rdp.exhausted:
+        score -= 15
+    if private_count > 0:
+        score -= 10
+    if sis_quarantine_count > 0:
+        score -= 10
+    if variance_alert_count > 0:
+        score -= 10
+    score = max(0, score)
+
+    return CompliancePostureModel(
+        event_log_integrity=integrity_ok,
+        i1_compliance_rate=i1_rate,
+        rdp_budget_exhausted=rdp.exhausted,
+        rdp_read_only=rdp.read_only,
+        private_span_count=private_count,
+        sis_quarantine_count=sis_quarantine_count,
+        variance_alert_count=variance_alert_count,
+        overall_score=score,
+    )
+
+
+def _read_org_dependency_graph() -> OrgDependencyGraphModel:
+    """Build a cross-project concept-coupling graph from registered project Θ files."""
+    registry = ProjectRegistry()
+    project_concepts: Dict[str, Dict[str, float]] = {}
+    project_meta: Dict[str, Dict[str, Any]] = {}
+
+    for entry in registry.list():
+        project_root = Path(entry.path)
+        gcc_dir = project_root / ".GCC"
+        if not gcc_dir.exists():
+            continue
+        try:
+            theta = _read_theta(project_root)
+        except Exception:
+            continue
+        concepts: Dict[str, float] = {}
+        for t in theta:
+            concepts[t.concept] = t.meanConfidence
+        if concepts:
+            project_concepts[entry.name] = concepts
+            project_meta[entry.name] = {
+                "path": entry.path,
+                "health_score": _compute_health_score(gcc_dir),
+            }
+
+    nodes = [
+        OrgDependencyNodeModel(
+            id=name,
+            name=name,
+            path=meta["path"],
+            healthScore=meta["health_score"],
+        )
+        for name, meta in project_meta.items()
+    ]
+
+    edges: List[OrgDependencyEdgeModel] = []
+    project_names = list(project_concepts.keys())
+    for i in range(len(project_names)):
+        for j in range(i + 1, len(project_names)):
+            a, b = project_names[i], project_names[j]
+            shared = set(project_concepts[a].keys()) & set(project_concepts[b].keys())
+            for concept in shared:
+                weight = (project_concepts[a][concept] + project_concepts[b][concept]) / 2
+                edges.append(OrgDependencyEdgeModel(
+                    source=a,
+                    target=b,
+                    concept=concept,
+                    weight=weight,
+                ))
+
+    return OrgDependencyGraphModel(nodes=nodes, edges=edges)
+
+
+def _read_dashboard(gcc_repo: Path, sensitivity_limit: int = 20) -> DashboardDataModel:
+    status = _read_gcc_status(gcc_repo)
+    theta = _read_theta(gcc_repo)
+    sensitivities = _read_sensitivities(gcc_repo, limit=sensitivity_limit)
+    branches = _read_branches(gcc_repo)
+    github_url = _get_github_url(gcc_repo)
+    tokens = aggregate_tokens(_gcc_dir(gcc_repo))
+    speedup = aggregate_speedup(_gcc_dir(gcc_repo))
+    last_updated = _dt.datetime.now(tz=_dt.timezone.utc).isoformat()
+    return DashboardDataModel(
+        status=status,
+        theta=theta,
+        recentSensitivities=sensitivities,
+        branches=branches,
+        githubUrl=github_url,
+        lastUpdated=last_updated,
+        savings=DashboardSavingsModel(
+            tokensUsed=tokens["total_tokens_used"],
+            tokensSaved=tokens["total_tokens_saved"],
+            latencySpeedup=speedup["latency_speedup_factor"],
+        ),
+    )
+
+
+# ---------------------------------------------------------------------------
+# S13 / S14 reader helpers
+# ---------------------------------------------------------------------------
+
+EVENT_LOG_FILE = "events.log.jsonl"
+COMMIT_INDEX_FILE = "COMMIT_INDEX"
+
+
+def _summarize_event(ev: Dict[str, Any]) -> str:
+    """Produce a human-readable one-liner for an event dict."""
+    etype = ev.get("event_type", ev.get("type", "UNKNOWN"))
+    concept = ev.get("concept", ev.get("target_concept", ""))
+    message = ev.get("message", ev.get("detail", ""))
+    commit_id = ev.get("commit_id", "")
+    branch = ev.get("branch", "")
+
+    parts: List[str] = []
+    if etype:
+        parts.append(f"[{etype}]")
+    if concept:
+        parts.append(f"concept={concept}")
+    if branch:
+        parts.append(f"branch={branch}")
+    if commit_id:
+        parts.append(f"commit={commit_id[:8]}")
+    if message:
+        parts.append(message[:120])
+    return " ".join(parts) if parts else str(ev)
+
+
+def _read_events_log(gcc_repo: Path) -> List[Dict[str, Any]]:
+    """Read all events from events.log.jsonl; return empty list on any error."""
+    log_file = _gcc_dir(gcc_repo) / EVENT_LOG_FILE
+    events: List[Dict[str, Any]] = []
+    if not log_file.exists():
+        return events
+    try:
+        with log_file.open("r", encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    events.append(json.loads(line))
+                except json.JSONDecodeError:
+                    continue
+    except OSError:
+        pass
+    return events
+
+
+def _read_forensic_timeline(
+    gcc_repo: Path,
+    limit: int = 100,
+    event_types_filter: str = "",
+    branch_filter: str = "",
+) -> ForensicTimelineModel:
+    raw_events = _read_events_log(gcc_repo)
+
+    # Apply event type filter
+    if event_types_filter:
+        wanted = {t.strip().upper() for t in event_types_filter.split(",") if t.strip()}
+        raw_events = [
+            ev for ev in raw_events
+            if ev.get("event_type", ev.get("type", "")).upper() in wanted
+        ]
+
+    # Apply branch filter
+    if branch_filter:
+        raw_events = [
+            ev for ev in raw_events
+            if ev.get("branch", "").lower() == branch_filter.lower()
+        ]
+
+    # Chronological order (already append-only so just slice)
+    raw_events = raw_events[:limit]
+
+    result: List[ForensicEventModel] = []
+    for ev in raw_events:
+        ts = ev.get("ts", ev.get("timestamp", ev.get("created_at", "")))
+        etype = ev.get("event_type", ev.get("type", "UNKNOWN"))
+        result.append(
+            ForensicEventModel(
+                ts=ts,
+                type=etype,
+                detail=_summarize_event(ev),
+                raw=ev,
+            )
+        )
+    return ForensicTimelineModel(events=result)
+
+
+def _read_commit_chain(gcc_repo: Path, commit_id: str, max_depth: int = 10) -> List[Dict[str, Any]]:
+    """Return the commit object + up to max_depth parents."""
+    commits_dir = _gcc_dir(gcc_repo) / COMMITS_DIR_NAME
+    chain: List[Dict[str, Any]] = []
+    current = commit_id
+    visited: set = set()
+    while current and current not in visited and len(chain) <= max_depth:
+        visited.add(current)
+        commit_file = commits_dir / f"{current}.json"
+        if not commit_file.exists():
+            break
+        try:
+            obj = json.loads(commit_file.read_text(encoding="utf-8"))
+            chain.append(obj)
+            current = obj.get("parent") or ""
+        except (json.JSONDecodeError, OSError):
+            break
+    return chain
+
+
+def _read_sensitivity_events_between(
+    gcc_repo: Path, parent_ts: str, child_ts: str
+) -> List[Dict[str, Any]]:
+    """Return all sensitivity events whose timestamp falls between parent and child."""
+    events_file = _gcc_dir(gcc_repo) / "sensitivities" / "events.jsonl"
+    result: List[Dict[str, Any]] = []
+    if not events_file.exists():
+        return result
+    try:
+        with events_file.open("r", encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    ev = json.loads(line)
+                    ts = ev.get("created_at", ev.get("timestamp", ""))
+                    if parent_ts <= ts <= child_ts:
+                        result.append(ev)
+                except json.JSONDecodeError:
+                    continue
+    except OSError:
+        pass
+    return result
+
+
+def _read_invariant_violations_between(
+    gcc_repo: Path, parent_ts: str, child_ts: str
+) -> List[Dict[str, Any]]:
+    """Return all INVARIANT_VIOLATION events between the two timestamps."""
+    all_events = _read_events_log(gcc_repo)
+    return [
+        ev for ev in all_events
+        if ev.get("event_type", ev.get("type", "")) == "INVARIANT_VIOLATION"
+        and parent_ts <= ev.get("ts", ev.get("timestamp", "")) <= child_ts
+    ]
+
+
+def _read_collision_list(gcc_repo: Path) -> List[CollisionModel]:
+    """Detect collisions from theta.json where multiple source_nodes conflict (std_dev > 0.2)."""
+    theta_file = _gcc_dir(gcc_repo) / THETA_FILE
+    if not theta_file.exists():
+        return []
+    try:
+        data = json.loads(theta_file.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return []
+
+    cv: Dict[str, Any] = data.get("coordination_vector", {})
+    collisions: List[CollisionModel] = []
+
+    for concept, info in cv.items():
+        source_nodes: List[Dict[str, Any]] = info.get("source_nodes", [])
+        if not source_nodes or len(source_nodes) < 2:
+            continue
+
+        confidences = [float(n.get("confidence", 0.0)) for n in source_nodes]
+        mean_c = sum(confidences) / len(confidences)
+        variance = sum((c - mean_c) ** 2 for c in confidences) / len(confidences)
+        std_dev = math.sqrt(variance)
+
+        if std_dev <= 0.2:
+            continue
+
+        if std_dev > 0.4:
+            severity = "HIGH"
+        else:
+            severity = "MEDIUM"
+
+        agents: List[AgentContributionModel] = []
+        for node in source_nodes:
+            agents.append(
+                AgentContributionModel(
+                    agent_id=str(node.get("agent_id", node.get("node_id", "unknown"))),
+                    confidence=float(node.get("confidence", 0.0)),
+                    message=str(node.get("message", node.get("signal", ""))),
+                )
+            )
+
+        collisions.append(CollisionModel(concept=concept, agents=agents, severity=severity))
+
+    return collisions
+
+
+def _read_commit_index(gcc_repo: Path) -> List[str]:
+    """Read the flat COMMIT_INDEX file and return list of commit IDs."""
+    index_file = _gcc_dir(gcc_repo) / COMMIT_INDEX_FILE
+    if not index_file.exists():
+        return []
+    try:
+        lines = index_file.read_text(encoding="utf-8").splitlines()
+        return [line.strip() for line in lines if line.strip()]
+    except OSError:
+        return []
+
+
+def _read_sprint_summary(gcc_repo: Path) -> SprintSummaryModel:
+    """Compute sprint review summary from commits + events."""
+    commit_ids = _read_commit_index(gcc_repo)
+    total_commits = len(commit_ids)
+
+    # commits_per_branch: walk each commit and group by branch field
+    commits_dir = _gcc_dir(gcc_repo) / COMMITS_DIR_NAME
+    commits_per_branch: Dict[str, int] = {}
+    for cid in commit_ids:
+        cfile = commits_dir / f"{cid}.json"
+        if not cfile.exists():
+            continue
+        try:
+            obj = json.loads(cfile.read_text(encoding="utf-8"))
+            branch = obj.get("branch", "main")
+            commits_per_branch[branch] = commits_per_branch.get(branch, 0) + 1
+        except (json.JSONDecodeError, OSError):
+            continue
+
+    # Count I3 violations and collision events from events.log
+    all_events = _read_events_log(gcc_repo)
+    i3_violations = sum(
+        1 for ev in all_events
+        if ev.get("event_type", ev.get("type", "")) == "INVARIANT_VIOLATION"
+        and "I3" in str(ev.get("invariant", ev.get("detail", "")))
+    )
+    # Broaden to any INVARIANT_VIOLATION if no I3-specific found
+    if i3_violations == 0:
+        i3_violations = sum(
+            1 for ev in all_events
+            if ev.get("event_type", ev.get("type", "")) == "INVARIANT_VIOLATION"
+        )
+    collisions_detected = sum(
+        1 for ev in all_events
+        if ev.get("event_type", ev.get("type", "")) == "VARIANCE_ALERT"
+    )
+
+    top_concepts = _read_theta(gcc_repo)[:5]
+
+    return SprintSummaryModel(
+        total_commits=total_commits,
+        commits_per_branch=commits_per_branch,
+        i3_violations=i3_violations,
+        collisions_detected=collisions_detected,
+        top_concepts=top_concepts,
+        mcs_note="MCS weights are DevTorch design choices pending empirical calibration",
+    )
+
+
+def _build_audit_json(gcc_repo: Path, since: str = "") -> AuditExportMetaModel:
+    """Build the audit export JSON payload."""
+    all_events = _read_events_log(gcc_repo)
+
+    # Apply since filter
+    if since:
+        filtered: List[Dict[str, Any]] = []
+        for ev in all_events:
+            ts = ev.get("ts", ev.get("timestamp", ev.get("created_at", "")))
+            if ts >= since:
+                filtered.append(ev)
+        all_events = filtered
+
+    # Read version
+    version_file = _gcc_dir(gcc_repo) / "VERSION"
+    gcc_version = "unknown"
+    if version_file.exists():
+        try:
+            gcc_version = version_file.read_text(encoding="utf-8").strip()
+        except OSError:
+            pass
+
+    return AuditExportMetaModel(
+        exported_at=_dt.datetime.now(tz=_dt.timezone.utc).isoformat(),
+        gcc_version=gcc_version,
+        event_count=len(all_events),
+        events=all_events,
+    )
+
+
+def _build_audit_text(gcc_repo: Path, since: str = "") -> str:
+    """Build a human-readable plain-text audit report."""
+    export = _build_audit_json(gcc_repo, since=since)
+    status = _read_gcc_status(gcc_repo)
+    branches = _read_branches(gcc_repo)
+    sensitivity_events = _read_sensitivities(gcc_repo, limit=200)
+
+    now_str = _dt.datetime.now(tz=_dt.timezone.utc).strftime("%Y-%m-%d %H:%M:%S UTC")
+    lines: List[str] = []
+
+    # Header
+    lines.append("=" * 72)
+    lines.append("  DEVTORCH AUDIT REPORT")
+    lines.append(f"  Generated: {now_str}")
+    lines.append(f"  GCC Version: {export.gcc_version}")
+    lines.append("=" * 72)
+    lines.append("")
+    lines.append(
+        "DISCLAIMER: This report was generated by DevTorch OSS. "
+        "Weights and scores are design choices pending empirical calibration."
+    )
+    lines.append("")
+
+    # Repository Info
+    lines.append("-" * 72)
+    lines.append("REPOSITORY INFO")
+    lines.append("-" * 72)
+    lines.append(f"  Current Branch : {status.branch}")
+    lines.append(f"  Node State     : {status.nodeState}")
+    lines.append(f"  Last Commit ID : {status.lastCommitId or '(none)'}")
+    lines.append(f"  Locked         : {'YES' if status.locked else 'NO'}")
+    if status.lockReason:
+        lines.append(f"  Lock Reason    : {status.lockReason}")
+    lines.append("")
+
+    # Branch Summary
+    lines.append("-" * 72)
+    lines.append("BRANCH SUMMARY")
+    lines.append("-" * 72)
+    if branches:
+        for br in branches:
+            lines.append(f"  {br.name:<20} commits={br.commitCount:<5} tip={br.tipCommitId[:12] if br.tipCommitId else '(empty)'}")
+    else:
+        lines.append("  (no branches)")
+    lines.append("")
+
+    # Event Summary
+    lines.append("-" * 72)
+    lines.append("EVENT SUMMARY")
+    lines.append("-" * 72)
+    lines.append(f"  Total events in export: {export.event_count}")
+    if since:
+        lines.append(f"  Filtered since: {since}")
+
+    # Group by type
+    type_counts: Dict[str, int] = {}
+    for ev in export.events:
+        etype = ev.get("event_type", ev.get("type", "UNKNOWN"))
+        type_counts[etype] = type_counts.get(etype, 0) + 1
+    if type_counts:
+        lines.append("")
+        lines.append("  Event type breakdown:")
+        for etype, cnt in sorted(type_counts.items()):
+            lines.append(f"    {etype:<35} {cnt}")
+    lines.append("")
+
+    # Sensitivity Events
+    lines.append("-" * 72)
+    lines.append("SENSITIVITY EVENTS (most recent 50)")
+    lines.append("-" * 72)
+    if sensitivity_events:
+        for ev in sensitivity_events[:50]:
+            lines.append(
+                f"  [{ev.timestamp[:19]}] L{ev.disclosureLevel} {ev.concept:<25} {ev.signal[:60]}"
+            )
+    else:
+        lines.append("  (no sensitivity events)")
+    lines.append("")
+
+    # Commit History
+    lines.append("-" * 72)
+    lines.append("COMMIT HISTORY")
+    lines.append("-" * 72)
+    commit_ids = _read_commit_index(gcc_repo)
+    if commit_ids:
+        commits_dir = _gcc_dir(gcc_repo) / COMMITS_DIR_NAME
+        for cid in commit_ids[-50:]:  # last 50
+            cfile = commits_dir / f"{cid}.json"
+            if cfile.exists():
+                try:
+                    obj = json.loads(cfile.read_text(encoding="utf-8"))
+                    msg = str(obj.get("message", ""))[:60]
+                    br = obj.get("branch", "?")
+                    ts = str(obj.get("created_at", ""))[:19]
+                    lines.append(f"  {cid[:12]}  [{ts}]  ({br})  {msg}")
+                except (json.JSONDecodeError, OSError):
+                    lines.append(f"  {cid[:12]}  (unreadable)")
+    else:
+        lines.append("  (no commits)")
+    lines.append("")
+
+    # Invariant Status
+    lines.append("-" * 72)
+    lines.append("INVARIANT STATUS")
+    lines.append("-" * 72)
+    conformance = _read_conformance(gcc_repo)
+    lines.append(f"  I1 Commit-Backed    : {'PASS' if conformance.I1_commit_backed else 'FAIL'}")
+    lines.append(f"  I3 Semantic Ground  : {'PASS' if conformance.I3_semantic_grounding else 'FAIL'}")
+    lines.append(f"  A1 Capability Gate  : {'PASS' if conformance.A1_capability_gate else 'FAIL'}")
+    lines.append(f"  A2 Variance Control : {'PASS' if conformance.A2_variance_control else 'FAIL'}")
+    lines.append(f"  A3 SIS Quarantine   : {'PASS' if conformance.A3_sis_quarantine else 'FAIL'}")
+    lines.append(f"  A4 Deltaf Bound     : {'PASS' if conformance.A4_deltaf_bound else 'FAIL'}")
+    lines.append("")
+    lines.append("=" * 72)
+    lines.append("END OF REPORT")
+    lines.append("=" * 72)
+
+    return "\n".join(lines)
+
+
+def _read_mcs_trend(gcc_repo: Path, days: int = 7) -> List[MCSTrendPointModel]:
+    """
+    Compute a per-day confidence average from sensitivity events for the last
+    `days` days.  Used as a proxy for MCS trend until sprint-level MCS scores
+    are persisted by `devtorch merge`.
+    """
+    events_file = _gcc_dir(gcc_repo) / SENSITIVITIES_DIR_NAME / SENSITIVITY_EVENTS_FILE
+    today = _dt.date.today()
+
+    # Build a bucket per day: date_str → [confidence, ...]
+    buckets: Dict[str, List[float]] = {}
+    for i in range(days):
+        day = (today - _dt.timedelta(days=days - 1 - i)).isoformat()
+        buckets[day] = []
+
+    if events_file.exists():
+        try:
+            with events_file.open("r", encoding="utf-8") as fh:
+                for line in fh:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        ev = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    ts_raw = ev.get("created_at", ev.get("timestamp", ""))
+                    if not ts_raw:
+                        continue
+                    try:
+                        day_str = ts_raw[:10]  # "2026-04-19"
+                    except (TypeError, IndexError):
+                        continue
+                    if day_str not in buckets:
+                        continue
+                    conf = ev.get("confidence")
+                    if conf is not None:
+                        try:
+                            buckets[day_str].append(float(conf))
+                        except (TypeError, ValueError):
+                            pass
+        except OSError:
+            pass
+
+    result: List[MCSTrendPointModel] = []
+    for day_str, confs in buckets.items():
+        mcs = (sum(confs) / len(confs)) if confs else None
+        result.append(MCSTrendPointModel(date=day_str, mcs=mcs, eventCount=len(confs)))
+    return result
+
+
+# ---------------------------------------------------------------------------
+# S27: Concept drift heatmap
+# ---------------------------------------------------------------------------
+
+CONCEPT_DRIFT_MAX_CONCEPTS = 20
+
+
+def _compute_concept_drift(
+    gcc_repo: Path,
+    days: int = 14,
+) -> ConceptDriftResponseModel:
+    """
+    Compute per-concept confidence drift over the last `days` days.
+
+    Drift is defined as the absolute change in mean confidence for a concept
+    between two consecutive day buckets. The first populated bucket for each
+    concept has drift 0.0. Empty buckets inherit the previous mean so that
+    drift resumes when events reappear.
+    """
+    events_file = _gcc_dir(gcc_repo) / SENSITIVITIES_DIR_NAME / SENSITIVITY_EVENTS_FILE
+    today = _dt.date.today()
+
+    time_labels: List[str] = []
+    for i in range(days):
+        day = (today - _dt.timedelta(days=days - 1 - i)).isoformat()
+        time_labels.append(day)
+
+    # concept -> day -> list of confidence values
+    raw_buckets: Dict[str, Dict[str, List[float]]] = {}
+    if events_file.exists():
+        try:
+            with events_file.open("r", encoding="utf-8") as fh:
+                for line in fh:
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        ev = json.loads(line)
+                    except json.JSONDecodeError:
+                        continue
+                    concept = ev.get("target_concept", ev.get("concept", ""))
+                    if not concept:
+                        continue
+                    ts = ev.get("created_at", ev.get("timestamp", ""))
+                    if not ts:
+                        continue
+                    day_str = ts[:10]
+                    if day_str not in time_labels:
+                        continue
+                    conf = ev.get("confidence")
+                    if conf is None:
+                        continue
+                    try:
+                        conf_val = float(conf)
+                    except (TypeError, ValueError):
+                        continue
+                    raw_buckets.setdefault(concept, {}).setdefault(day_str, []).append(conf_val)
+        except OSError:
+            pass
+
+    # Keep the top concepts by total event volume
+    concept_counts = {
+        concept: sum(len(vals) for vals in days.values())
+        for concept, days in raw_buckets.items()
+    }
+    concepts = sorted(
+        concept_counts.keys(),
+        key=lambda c: concept_counts[c],
+        reverse=True,
+    )[:CONCEPT_DRIFT_MAX_CONCEPTS]
+
+    matrix: List[List[float]] = []
+    mean_confidences: List[List[float]] = []
+    event_counts: List[List[int]] = []
+
+    for concept in concepts:
+        days_for_concept = raw_buckets.get(concept, {})
+        means: List[Optional[float]] = []
+        counts: List[int] = []
+        for day in time_labels:
+            vals = days_for_concept.get(day, [])
+            if vals:
+                means.append(sum(vals) / len(vals))
+                counts.append(len(vals))
+            else:
+                means.append(None)
+                counts.append(0)
+
+        drifts: List[float] = []
+        prev_mean: Optional[float] = None
+        for mean in means:
+            if mean is None:
+                drifts.append(0.0)
+            else:
+                if prev_mean is None:
+                    drifts.append(0.0)
+                else:
+                    drifts.append(abs(mean - prev_mean))
+                prev_mean = mean
+
+        matrix.append(drifts)
+        mean_confidences.append([m if m is not None else 0.0 for m in means])
+        event_counts.append(counts)
+
+    return ConceptDriftResponseModel(
+        concepts=concepts,
+        time_labels=time_labels,
+        matrix=matrix,
+        mean_confidences=mean_confidences,
+        event_counts=event_counts,
+    )
+
+
+# ---------------------------------------------------------------------------
+# S29: SSE broadcaster and watcher helpers
+# ---------------------------------------------------------------------------
+
+_broadcaster: Optional[EventBroadcaster] = None
+_watcher: Optional[GCCWatcher] = None
+
+
+def _ensure_broadcaster(gcc_repo: Path) -> EventBroadcaster:
+    """Return a global EventBroadcaster and start a GCCWatcher for this repo."""
+    global _broadcaster, _watcher
+    if _broadcaster is None:
+        _broadcaster = EventBroadcaster()
+    if _watcher is None and _is_initialized(gcc_repo):
+        _watcher = GCCWatcher(_gcc_dir(gcc_repo), _broadcaster, poll_interval=0.5)
+        _watcher.start()
+    return _broadcaster
+
+
+def _stop_broadcaster() -> None:
+    """Stop the global watcher (useful for tests)."""
+    global _watcher
+    if _watcher is not None:
+        _watcher.stop()
+        _watcher = None
+
+
+# ---------------------------------------------------------------------------
+# S29: Sprint metrics helpers
+# ---------------------------------------------------------------------------
+
+
+def _read_latest_sprint_metrics(gcc_repo: Path) -> Optional[Dict[str, Any]]:
+    """Return the most recent sprint metrics file, or None if none exist."""
+    sprint_dir = _gcc_dir(gcc_repo) / "metrics" / "sprint"
+    if not sprint_dir.exists():
+        return None
+    files = sorted(
+        (p for p in sprint_dir.iterdir() if p.suffix == ".json"),
+        key=lambda p: p.name,
+    )
+    if not files:
+        return None
+    try:
+        data = json.loads(files[-1].read_text(encoding="utf-8"))
+        if isinstance(data, dict):
+            return data
+    except (json.JSONDecodeError, OSError):
+        pass
+    return None
+
+
+def _list_sprint_metrics(gcc_repo: Path) -> List[Dict[str, Any]]:
+    """Return all sprint metrics files sorted by sprint_id."""
+    sprint_dir = _gcc_dir(gcc_repo) / "metrics" / "sprint"
+    if not sprint_dir.exists():
+        return []
+    results: List[Dict[str, Any]] = []
+    for path in sorted(p for p in sprint_dir.iterdir() if p.suffix == ".json"):
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+            if isinstance(data, dict):
+                results.append(data)
+        except (json.JSONDecodeError, OSError):
+            continue
+    return results
+
+
+# ---------------------------------------------------------------------------
+# S29: Delivery-time trend helper
+# ---------------------------------------------------------------------------
+
+
+def _session_effective_date(session_path: Path) -> Optional[str]:
+    """Return ISO date for a session file (created_at field, then mtime)."""
+    try:
+        data = json.loads(session_path.read_text(encoding="utf-8"))
+        if isinstance(data, dict):
+            created_at = data.get("created_at")
+            if created_at:
+                return str(created_at)[:10]
+    except (json.JSONDecodeError, OSError):
+        pass
+    try:
+        mtime = session_path.stat().st_mtime
+        return _dt.datetime.fromtimestamp(mtime, tz=_dt.timezone.utc).date().isoformat()
+    except OSError:
+        return None
+
+
+def _compute_delivery_time_trend(
+    gcc_repo: Path, days: int = 30
+) -> List[DeliveryTimeTrendPointModel]:
+    """
+    Return a per-day delivery-time trend over the last N days.
+
+    Each point uses the team calibration baseline and all sessions whose
+    effective date is <= that day. Points are returned oldest-first.
+    """
+    metrics_dir = _gcc_dir(gcc_repo) / "metrics"
+    session_dir = metrics_dir / "session"
+    sessions: List[Dict[str, Any]] = []
+    if session_dir.exists():
+        for path in session_dir.glob("*.json"):
+            try:
+                data = json.loads(path.read_text(encoding="utf-8"))
+                if isinstance(data, dict):
+                    data = dict(data)
+                    if "created_at" not in data:
+                        mdate = _session_effective_date(path)
+                        if mdate:
+                            data["created_at"] = f"{mdate}T00:00:00Z"
+                    sessions.append(data)
+            except (json.JSONDecodeError, OSError):
+                continue
+
+    # Load calibration from .GCC/metrics/calibration.json if present
+    calibration: Dict[str, Any] = {}
+    calibration_path = metrics_dir / "calibration.json"
+    if calibration_path.exists():
+        try:
+            calibration = json.loads(calibration_path.read_text(encoding="utf-8"))
+            if not isinstance(calibration, dict):
+                calibration = {}
+        except (json.JSONDecodeError, OSError):
+            calibration = {}
+
+    baseline = float(calibration.get("complex_problem_delivery_time_baseline_min", 240.0))
+
+    today = _dt.date.today()
+    time_labels: List[str] = []
+    for i in range(days):
+        day = (today - _dt.timedelta(days=days - 1 - i)).isoformat()
+        time_labels.append(day)
+
+    # Group sessions by effective date
+    sessions_by_day: Dict[str, List[Dict[str, Any]]] = {}
+    for s in sessions:
+        created_at = s.get("created_at", "")
+        day = str(created_at)[:10] if created_at else ""
+        if day:
+            sessions_by_day.setdefault(day, []).append(s)
+
+    cumulative_sessions: List[Dict[str, Any]] = []
+    result: List[DeliveryTimeTrendPointModel] = []
+    for day in time_labels:
+        cumulative_sessions.extend(sessions_by_day.get(day, []))
+        # Build a synthetic metrics_dir with only cumulative sessions
+        summary = compute_delivery_time_summary(
+            metrics_dir,
+            calibration,
+        )
+        # Override session count and recompute current based on cumulative sessions
+        total_tokens = sum(s.get("tokens_used", 0) for s in cumulative_sessions)
+        session_count = len(cumulative_sessions)
+        complexity = 1.0 + (total_tokens / 100_000.0)
+        current = baseline * complexity * (1.0 + session_count * 0.05)
+        result.append(
+            DeliveryTimeTrendPointModel(
+                date=day,
+                current_min=round(current, 2),
+                baseline_min=round(baseline, 2),
+                delta_min=round(current - baseline, 2),
+            )
+        )
+    return result
+
+
+# ---------------------------------------------------------------------------
+# FastAPI application factory
+# ---------------------------------------------------------------------------
+
+def create_app(gcc_repo: Optional[Path] = None) -> "FastAPI":
+    """
+    Build and return a FastAPI application instance.
+
+    Parameters
+    ----------
+    gcc_repo:
+        Path to the project root containing the `.GCC/` directory.
+        Falls back to the current working directory when None.
+    """
+    if not _FASTAPI_AVAILABLE:
+        raise ImportError(
+            "FastAPI and uvicorn are required for the dashboard API. "
+            "Install them with: pip install fastapi uvicorn"
+        )
+
+    resolved_repo: Path = gcc_repo if gcc_repo is not None else Path.cwd()
+
+    app = FastAPI(
+        title="DevTorch Dashboard API",
+        description="Read-only REST API serving DevTorch governance state from .GCC/",
+        version="0.1.0",
+    )
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],  # No auth in S13; tightened in enterprise tier
+        allow_credentials=False,
+        allow_methods=["GET"],
+        allow_headers=["*"],
+    )
+
+    # Start the global SSE broadcaster/watcher for this repo.
+    _ensure_broadcaster(resolved_repo)
+
+    def _require_init() -> Path:
+        if not _is_initialized(resolved_repo):
+            raise HTTPException(
+                status_code=503,
+                detail=(
+                    f"No initialized .GCC/ directory found at '{resolved_repo}'. "
+                    "Run `devtorch init` in the project root first."
+                ),
+            )
+        return resolved_repo
+
+    @app.get("/api/v1/dashboard", response_model=DashboardDataModel)
+    def get_dashboard() -> DashboardDataModel:
+        """Return a full governance snapshot."""
+        repo = _require_init()
+        return _read_dashboard(repo)
+
+    @app.get("/api/v1/branches", response_model=List[BranchSummaryModel])
+    def get_branches() -> List[BranchSummaryModel]:
+        """Return a list of branch summaries."""
+        repo = _require_init()
+        return _read_branches(repo)
+
+    @app.get("/api/v1/sensitivities", response_model=List[SensitivityEventModel])
+    def get_sensitivities(
+        limit: int = Query(default=50, ge=1, le=500),
+        concept: Optional[str] = Query(default=None),
+    ) -> List[SensitivityEventModel]:
+        """Return sensitivity events, newest first. Filter by concept with ?concept=auth."""
+        repo = _require_init()
+        return _read_sensitivities(repo, limit=limit, concept=concept)
+
+    @app.get("/api/v1/concepts/drift", response_model=ConceptDriftResponseModel)
+    def get_concept_drift(
+        days: int = Query(default=14, ge=1, le=90),
+    ) -> ConceptDriftResponseModel:
+        """Per-concept confidence drift heatmap over the last N days."""
+        repo = _require_init()
+        return _compute_concept_drift(repo, days=days)
+
+    @app.get("/api/v1/ciso", response_model=CISODataModel)
+    def get_ciso_data() -> CISODataModel:
+        """CISO-focused governance metrics."""
+        # CISO endpoint returns safe defaults for uninitialized repos — never 503
+        return _read_ciso_data(resolved_repo)
+
+    @app.get("/api/v1/shadow-ai", response_model=ShadowAIModel)
+    def get_shadow_ai() -> ShadowAIModel:
+        """Shadow AI detection: compare git commits to .GCC COMMIT events."""
+        from devtorch_core.metrics.shadow_ai import detect_shadow_ai
+        result = detect_shadow_ai(resolved_repo)
+        return ShadowAIModel(
+            git_commits=result["git_commits"],
+            gcc_commits=result["gcc_commits"],
+            unregistered=result["unregistered"],
+            shadow_ratio=result["shadow_ratio"],
+            flagged=result["flagged"],
+        )
+
+    @app.get("/api/v1/compliance-posture", response_model=CompliancePostureModel)
+    def get_compliance_posture() -> CompliancePostureModel:
+        """Compliance posture summary for CISO audit."""
+        return _read_compliance_posture(resolved_repo)
+
+    @app.get("/api/v1/governance-policy", response_model=GovernancePolicyModel)
+    def get_governance_policy() -> GovernancePolicyModel:
+        """Read-only governance policy console for the project."""
+        return _read_governance_policy(resolved_repo)
+
+    @app.get("/api/v1/org/dependencies", response_model=OrgDependencyGraphModel)
+    def get_org_dependencies() -> OrgDependencyGraphModel:
+        """Cross-project concept coupling graph."""
+        return _read_org_dependency_graph()
+
+    @app.get("/api/v1/health")
+    def get_health() -> dict:
+        """Simple health probe."""
+        initialized = _is_initialized(resolved_repo)
+        return {
+            "status": "ok" if initialized else "degraded",
+            "initialized": initialized,
+            "gcc_repo": str(resolved_repo),
+        }
+
+    # -----------------------------------------------------------------------
+    # S19: Multi-project endpoints
+    # -----------------------------------------------------------------------
+
+    @app.get("/api/v1/projects", response_model=List[ProjectSummaryModel])
+    def get_projects() -> List[ProjectSummaryModel]:
+        """List all projects in the registry with health summary."""
+        registry = ProjectRegistry()
+        out: List[ProjectSummaryModel] = []
+        for entry in registry.list():
+            gcc_dir = Path(entry.path) / ".GCC"
+            if not gcc_dir.exists():
+                continue
+            try:
+                status = _read_gcc_status(gcc_dir)
+            except Exception:
+                continue
+            tokens = aggregate_tokens(gcc_dir)
+            speedup = aggregate_speedup(gcc_dir)
+            health_score = _compute_health_score(gcc_dir)
+            out.append(ProjectSummaryModel(
+                name=entry.name,
+                path=entry.path,
+                branch=status.branch,
+                lastCommitId=status.lastCommitId,
+                lastActivity=entry.last_synced[:19],
+                tokensUsed30d=tokens["total_tokens_used"],
+                tokensSaved30d=tokens["total_tokens_saved"],
+                latencySpeedup=speedup["latency_speedup_factor"],
+                healthScore=health_score,
+                healthLabel=_health_label(health_score),
+            ))
+        return out
+
+    @app.get("/api/v1/projects/savings", response_model=ProjectsSavingsModel)
+    def get_projects_savings() -> ProjectsSavingsModel:
+        """Cross-project aggregate of tokens saved and speedup."""
+        registry = ProjectRegistry()
+        projects: List[ProjectSummaryModel] = []
+        total_used = 0
+        total_saved = 0
+        total_full = 0
+        total_bundle = 0
+        for entry in registry.list():
+            gcc_dir = Path(entry.path) / ".GCC"
+            if not gcc_dir.exists():
+                continue
+            try:
+                status = _read_gcc_status(gcc_dir)
+            except Exception:
+                continue
+            tokens = aggregate_tokens(gcc_dir)
+            speedup = aggregate_speedup(gcc_dir)
+            total_used += tokens["total_tokens_used"]
+            total_saved += tokens["total_tokens_saved"]
+            total_full += speedup["total_full_history_tokens"]
+            total_bundle += speedup["total_bundle_tokens"]
+            projects.append(ProjectSummaryModel(
+                name=entry.name,
+                path=entry.path,
+                branch=status.branch,
+                lastCommitId=status.lastCommitId,
+                lastActivity=entry.last_synced[:19],
+                tokensUsed30d=tokens["total_tokens_used"],
+                tokensSaved30d=tokens["total_tokens_saved"],
+                latencySpeedup=speedup["latency_speedup_factor"],
+                healthScore=_compute_health_score(gcc_dir),
+                healthLabel=_health_label(_compute_health_score(gcc_dir)),
+            ))
+        weighted_speedup = total_full / total_bundle if total_bundle > 0 else 1.0
+        return ProjectsSavingsModel(
+            projects=projects,
+            aggregateTokensUsed=total_used,
+            aggregateTokensSaved=total_saved,
+            aggregateLatencySpeedup=weighted_speedup,
+        )
+
+    # -----------------------------------------------------------------------
+    # S13: Forensic Replay endpoints
+    # -----------------------------------------------------------------------
+
+    @app.get("/api/v1/forensic/timeline", response_model=ForensicTimelineModel)
+    def get_forensic_timeline(
+        branch: str = Query(default=""),
+        limit: int = Query(default=100, ge=1, le=1000),
+        event_types: str = Query(default=""),
+    ) -> ForensicTimelineModel:
+        """Forensic event timeline from events.log.jsonl."""
+        return _read_forensic_timeline(
+            resolved_repo,
+            limit=limit,
+            event_types_filter=event_types,
+            branch_filter=branch,
+        )
+
+    @app.get("/api/v1/forensic/trace/{commit_id}")
+    def get_forensic_trace(commit_id: str) -> dict:
+        """Return commit + parent chain + sensitivity events between parent and this commit."""
+        chain = _read_commit_chain(resolved_repo, commit_id)
+        if not chain:
+            return {"commit": {}, "parents": [], "sensitivities": [], "invariant_violations": []}
+
+        commit = chain[0]
+        parents = chain[1:]
+
+        child_ts = str(commit.get("created_at", commit.get("ts", "")))
+        parent_ts = str(parents[0].get("created_at", parents[0].get("ts", ""))) if parents else ""
+
+        sensitivities = _read_sensitivity_events_between(resolved_repo, parent_ts, child_ts)
+        invariant_violations = _read_invariant_violations_between(resolved_repo, parent_ts, child_ts)
+
+        return {
+            "commit": commit,
+            "parents": parents,
+            "sensitivities": sensitivities,
+            "invariant_violations": invariant_violations,
+        }
+
+    @app.get("/api/v1/collisions", response_model=List[CollisionModel])
+    def get_collisions() -> List[CollisionModel]:
+        """Return concept collisions where agent confidence diverges (std_dev > 0.2)."""
+        return _read_collision_list(resolved_repo)
+
+    @app.get("/api/v1/sprint/summary", response_model=SprintSummaryModel)
+    def get_sprint_summary() -> SprintSummaryModel:
+        """Sprint review: commit stats, invariant violations, collisions, top concepts."""
+        return _read_sprint_summary(resolved_repo)
+
+    @app.get("/api/v1/mcs/trend", response_model=List[MCSTrendPointModel])
+    def get_mcs_trend(days: int = Query(default=7, ge=1, le=30)) -> List[MCSTrendPointModel]:
+        """Per-day average AI confidence for the last N days (proxy for MCS trend)."""
+        return _read_mcs_trend(resolved_repo, days=days)
+
+    # -----------------------------------------------------------------------
+    # S29: Real-time SSE and auto sprint metrics
+    # -----------------------------------------------------------------------
+
+    @app.get("/api/v1/events/stream")
+    async def get_event_stream() -> StreamingResponse:
+        """SSE stream of coordination events from the global broadcaster."""
+        broadcaster = _ensure_broadcaster(resolved_repo)
+        q = broadcaster.subscribe()
+
+        async def generate():
+            try:
+                # Initial connected event
+                yield "data: " + json.dumps({"type": "connected"}) + "\n\n"
+                while True:
+                    try:
+                        event = await asyncio.wait_for(q.get(), timeout=30.0)
+                        yield "data: " + json.dumps(event) + "\n\n"
+                    except asyncio.TimeoutError:
+                        yield ": keepalive\n\n"
+            finally:
+                broadcaster.unsubscribe(q)
+
+        return StreamingResponse(generate(), media_type="text/event-stream")
+
+    @app.get("/api/v1/sprint/latest", response_model=Optional[SprintMetricsModel])
+    def get_sprint_latest() -> Optional[SprintMetricsModel]:
+        """Return the most recent sprint metrics file."""
+        data = _read_latest_sprint_metrics(resolved_repo)
+        if data is None:
+            return None
+        return SprintMetricsModel(**data)
+
+    @app.get("/api/v1/sprint/metrics", response_model=List[SprintMetricsModel])
+    def get_sprint_metrics() -> List[SprintMetricsModel]:
+        """Return all sprint metrics files, sorted by sprint_id."""
+        items = _list_sprint_metrics(resolved_repo)
+        return [SprintMetricsModel(**d) for d in items]
+
+    @app.get("/api/v1/metrics/delivery-time/trend", response_model=List[DeliveryTimeTrendPointModel])
+    def get_delivery_time_trend(
+        days: int = Query(default=30, ge=1, le=90),
+    ) -> List[DeliveryTimeTrendPointModel]:
+        """Per-day complex-problem delivery-time trend over the last N days."""
+        return _compute_delivery_time_trend(resolved_repo, days=days)
+
+    # -----------------------------------------------------------------------
+    # S14: Audit Export endpoints
+    # -----------------------------------------------------------------------
+
+    @app.get("/api/v1/audit/export.json")
+    def get_audit_export_json(since: str = Query(default="")) -> JSONResponse:
+        """Download all events as a JSON audit export."""
+        export = _build_audit_json(resolved_repo, since=since)
+        date_str = _dt.date.today().isoformat()
+        return JSONResponse(
+            content=export.model_dump(),
+            headers={
+                "Content-Disposition": f'attachment; filename="devtorch-audit-{date_str}.json"',
+            },
+        )
+
+    @app.get("/api/v1/audit/export.txt", response_class=PlainTextResponse)
+    def get_audit_export_txt(
+        since: str = Query(default=""),
+    ) -> PlainTextResponse:
+        """Download a human-readable plain-text audit report."""
+        report = _build_audit_text(resolved_repo, since=since)
+        date_str = _dt.date.today().isoformat()
+        return PlainTextResponse(
+            content=report,
+            headers={
+                "Content-Disposition": f'attachment; filename="devtorch-audit-{date_str}.txt"',
+            },
+        )
+
+    return app
+
+
+# ---------------------------------------------------------------------------
+# Launcher
+# ---------------------------------------------------------------------------
+
+def run_dashboard_api(
+    port: int = 8766,
+    host: str = "127.0.0.1",
+    gcc_repo: Optional[Path] = None,
+) -> None:
+    """
+    Start the dashboard API server.
+
+    Parameters
+    ----------
+    port:
+        TCP port to listen on (default 8766).
+    host:
+        Bind address (default 127.0.0.1; use 0.0.0.0 for external access).
+    gcc_repo:
+        Path to the project root. Defaults to CWD.
+    """
+    if not _FASTAPI_AVAILABLE:
+        raise ImportError(
+            "FastAPI and uvicorn are required. "
+            "Install with: pip install fastapi uvicorn"
+        )
+    resolved = gcc_repo if gcc_repo is not None else Path.cwd()
+    app = create_app(gcc_repo=resolved)
+    uvicorn.run(app, host=host, port=port)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    import argparse
+
+    parser = argparse.ArgumentParser(description="DevTorch Dashboard API server")
+    parser.add_argument("--port", type=int, default=8766)
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--repo", type=Path, default=Path.cwd())
+    args = parser.parse_args()
+    run_dashboard_api(port=args.port, host=args.host, gcc_repo=args.repo)