arkaos 2.47.0 → 2.48.0

package/VERSION

@@ -1 +1 @@
-2.47.0
+2.48.0

package/arka/SKILL.md

@@ -188,6 +188,7 @@ violation (squad-routing, arka-supremacy, spec-driven, mandatory-qa).
 | `/arka status` | System status (version, departments, agents, active projects). Includes **LLM costs (24h)** section: top-line cost + cache hit rate + call count from `core.runtime.llm_cost_telemetry.summarise(period="today")`. Also includes **Enforcement (24h)** section: total calls, block rate, top blocked tools/reasons from `core.governance.enforcement_telemetry.summarise(period="today")` (PR19 v2.41.0). Plus **Reorganization (today)** section: today's proposal path + artifact count from `core.cognition.reorganizer_scheduler.status_summary()` (PR24 v2.46.0). |
 | `/arka costs [period]` | LLM cost visibility — aggregates telemetry by day/week/month/all, with top expensive sessions. See `arka/skills/costs/SKILL.md`. Shells out to `python -m core.runtime.llm_cost_telemetry_cli <period>`. |
 | `/arka enforcement [period]` | Enforcement compliance — aggregates flow-marker enforcement telemetry by day/week/month/all. Shows block rate, top blocked tools, top reasons. Shells out to `python -m core.governance.enforcement_telemetry_cli <period>`. |
+| `/arka compliance [period]` | Behavior compliance summary (PR29 v2.48.0) — aggregates stop-hook telemetry by day/week/month/all. Shows rates for the four contracts: closing marker, `[arka:meta]` tag, KB citation pass, sycophancy clean. Shells out to `python -m core.governance.compliance_telemetry_cli <period>`. |
 | `/arka reorganize [--since-days N]` | Dreaming → Agent reorganizer. Aggregates recent KB pattern/anti-pattern/lesson artifacts (default last 7 days) into a markdown proposal at `~/.arkaos/reorganize-proposals/<date>.md`. **Propose-only** — never modifies agent YAMLs. Sanitizes client identifiers from titles and body excerpts; drops `tags:` field entirely to prevent project-name leaks. **Auto-fires on session start when today's proposal is missing** (PR24 v2.46.0 stale-aware trigger, 30s timeout, background). Shells out to `python -m core.cognition.reorganizer_cli [--since-days N] [--dry-run]`. |
 | `/arka standup` | Daily standup (projects, priorities, blockers, updates) |
 | `/arka monitor` | System health monitoring |

package/core/governance/compliance_telemetry.py

@@ -0,0 +1,140 @@
+"""Behavior compliance telemetry summarizer (PR29 v2.48.0).
+
+Reads the stop-hook entries in ``~/.arkaos/telemetry/enforcement.jsonl``
+and reports compliance with the four contracts the session-start hook
+establishes:
+
+  - closing_marker_found  — [arka:phase:13] or [arka:trivial] present
+  - meta_tag_found        — [arka:meta] one-liner present (PR12)
+  - kb_cite_passed        — KB citation soft block result (PR18)
+  - sycophancy clean      — inverse of sycophancy_is_flagged (PR13)
+
+Mirrors the period vocabulary of ``enforcement_telemetry.summarise``
+(today / week / month / all). Empty/missing file = no-op zero rates.
+Null fields excluded from denominators so rates reflect *observed*
+behavior, not ``unknown``-padded data.
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Iterable
+
+DEFAULT_PATH: Path = Path.home() / ".arkaos" / "telemetry" / "enforcement.jsonl"
+_VALID_PERIODS: frozenset[str] = frozenset({"today", "week", "month", "all"})
+_STOP_EVENT: str = "stop-hook-flow-check"
+
+
+@dataclass(frozen=True)
+class ComplianceSummary:
+    """Compliance snapshot over a slice of stop-hook telemetry."""
+    period: str
+    stop_events: int
+    closing_marker_rate: float
+    meta_tag_rate: float
+    kb_cite_pass_rate: float
+    sycophancy_clean_rate: float
+    corrupt_line_count: int = 0
+
+
+def summarise(period: str, *, path: Path | None = None) -> ComplianceSummary:
+    """Return a ComplianceSummary for the requested period."""
+    if period not in _VALID_PERIODS:
+        raise ValueError(f"invalid period: {period!r}")
+    src = path or DEFAULT_PATH
+    cutoff = _period_cutoff(period)
+    entries, corrupt = _read_stop_entries(src, cutoff)
+    return _build_summary(period, entries, corrupt)
+
+
+def _period_cutoff(period: str, now: datetime | None = None) -> datetime | None:
+    ref = now or datetime.now(timezone.utc)
+    if period == "today":
+        return ref.replace(hour=0, minute=0, second=0, microsecond=0)
+    if period == "week":
+        return ref - timedelta(days=7)
+    if period == "month":
+        return ref - timedelta(days=30)
+    return None
+
+
+def _read_stop_entries(
+    src: Path, cutoff: datetime | None,
+) -> tuple[list[dict[str, Any]], int]:
+    if not src.exists():
+        return [], 0
+    entries: list[dict[str, Any]] = []
+    corrupt = 0
+    try:
+        with src.open("r", encoding="utf-8", errors="replace") as fh:
+            for line in fh:
+                if not line.strip():
+                    continue
+                try:
+                    entry = json.loads(line)
+                except json.JSONDecodeError:
+                    corrupt += 1
+                    continue
+                if not isinstance(entry, dict):
+                    corrupt += 1
+                    continue
+                if entry.get("event") != _STOP_EVENT:
+                    continue
+                if cutoff is not None and not _within_cutoff(entry, cutoff):
+                    continue
+                entries.append(entry)
+    except OSError:
+        return entries, corrupt
+    return entries, corrupt
+
+
+def _within_cutoff(entry: dict[str, Any], cutoff: datetime) -> bool:
+    ts = _parse_ts(entry.get("ts"))
+    return ts is not None and ts >= cutoff
+
+
+def _parse_ts(raw: Any) -> datetime | None:
+    if not isinstance(raw, str) or not raw:
+        return None
+    try:
+        parsed = datetime.fromisoformat(raw.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    if parsed.tzinfo is None:
+        parsed = parsed.replace(tzinfo=timezone.utc)
+    return parsed
+
+
+def _build_summary(
+    period: str,
+    entries: Iterable[dict[str, Any]],
+    corrupt: int,
+) -> ComplianceSummary:
+    rows = list(entries)
+    return ComplianceSummary(
+        period=period,
+        stop_events=len(rows),
+        closing_marker_rate=_true_rate(rows, "closing_marker_found"),
+        meta_tag_rate=_true_rate(rows, "meta_tag_found"),
+        kb_cite_pass_rate=_true_rate(rows, "kb_cite_passed"),
+        sycophancy_clean_rate=_false_rate(rows, "sycophancy_is_flagged"),
+        corrupt_line_count=corrupt,
+    )
+
+
+def _true_rate(rows: list[dict[str, Any]], key: str) -> float:
+    observed = [r for r in rows if isinstance(r.get(key), bool)]
+    if not observed:
+        return 0.0
+    return sum(1 for r in observed if r[key] is True) / len(observed)
+
+
+def _false_rate(rows: list[dict[str, Any]], key: str) -> float:
+    """Rate of `key is False` among rows where the field was observed."""
+    observed = [r for r in rows if isinstance(r.get(key), bool)]
+    if not observed:
+        return 0.0
+    return sum(1 for r in observed if r[key] is False) / len(observed)

package/core/governance/compliance_telemetry_cli.py

@@ -0,0 +1,65 @@
+"""CLI entry for the behavior-compliance summarizer (PR29 v2.48.0).
+
+Invoked as ``python -m core.governance.compliance_telemetry_cli <period>``.
+Renders a markdown report covering the four stop-hook behavior contracts:
+closing marker, meta tag, KB cite pass, sycophancy clean.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from core.governance.compliance_telemetry import (
+    ComplianceSummary,
+    summarise,
+)
+
+
+def _fmt_rate(value: float) -> str:
+    return f"{value * 100:.2f}%"
+
+
+def _render(summary: ComplianceSummary) -> str:
+    lines = [
+        f"# Behavior compliance — {summary.period}",
+        "",
+        f"- Stop-hook events observed: **{summary.stop_events}**",
+        "",
+        "| Contract | Compliance rate |",
+        "|---|---|",
+        f"| `[arka:phase:13]` / `[arka:trivial]` closing marker "
+        f"| {_fmt_rate(summary.closing_marker_rate)} |",
+        f"| `[arka:meta]` one-liner (PR12 v2.34.0) "
+        f"| {_fmt_rate(summary.meta_tag_rate)} |",
+        f"| KB citation pass (PR18 v2.40.0) "
+        f"| {_fmt_rate(summary.kb_cite_pass_rate)} |",
+        f"| Sycophancy clean (inverse of flagged, PR13 v2.35.0) "
+        f"| {_fmt_rate(summary.sycophancy_clean_rate)} |",
+    ]
+    if summary.corrupt_line_count:
+        lines += [
+            "",
+            f"_(skipped {summary.corrupt_line_count} corrupt line(s) in telemetry)_",
+        ]
+    if summary.stop_events == 0:
+        lines += [
+            "",
+            "_(no stop-hook events in window — open a session and complete "
+            "a turn to populate telemetry)_",
+        ]
+    return "\n".join(lines)
+
+
+def main(argv: list[str]) -> int:
+    period = argv[1] if len(argv) > 1 else "today"
+    try:
+        summary = summarise(period)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+    print(_render(summary))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "2.47.0",
+  "version": "2.48.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "2.47.0"
+version = "2.48.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}