arkaos 2.47.0 → 2.49.0

package/VERSION

@@ -1 +1 @@
-2.47.0
+2.49.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/config/hooks/stop.sh

@@ -162,6 +162,38 @@ try:
 except Exception:
     pass
 
+# PR30 v2.49.0 — Meta-tag soft block. Mirrors the KB cite-check
+# pipeline. Records whether the closing message carried the required
+# [arka:meta] one-liner; persists result to /tmp/arkaos-meta/<session>.json
+# so the next UserPromptSubmit can surface a nudge if missing.
+meta_passed = True
+meta_reason = "trivial"
+meta_suggestion: str | None = None
+try:
+    from core.governance.meta_tag_check import check_meta_tag
+    mr = check_meta_tag(last)
+    meta_passed = mr.passed
+    meta_reason = mr.reason
+    meta_suggestion = mr.suggestion
+    if safe_sid:
+        prev_umask = os.umask(0o077)
+        try:
+            meta_dir = Path("/tmp/arkaos-meta")
+            meta_dir.mkdir(parents=True, exist_ok=True)
+            meta_path = meta_dir / f"{safe_sid}.json"
+            meta_path.write_text(
+                json.dumps({
+                    "passed": mr.passed,
+                    "reason": mr.reason,
+                    "suggestion": mr.suggestion,
+                }),
+                encoding="utf-8",
+            )
+        finally:
+            os.umask(prev_umask)
+except Exception:
+    pass
+
 entry = {
     "ts": datetime.now(timezone.utc).isoformat(),
     "session_id": session_id,
@@ -178,6 +210,8 @@ entry = {
     "kb_cite_reason": cite_reason,
     "kb_cite_count": cite_count,
     "kb_cite_topic_score": cite_topic_score,
+    "meta_tag_check_passed": meta_passed,
+    "meta_tag_check_reason": meta_reason,
     "mode": "warn",
 }
 

package/config/hooks/user-prompt-submit.sh

@@ -393,11 +393,31 @@ if [ -n "$SESSION_ID" ]; then
   fi
 fi
 
+# ─── Meta-tag nudge (PR30 v2.49.0) ───────────────────────────────────────
+# Mirror of the KB citation nudge but for the [arka:meta] one-liner
+# contract. One-shot; deleted after read.
+_META_TAG_NUDGE=""
+if [ -n "$SESSION_ID" ]; then
+  _META_FILE="/tmp/arkaos-meta/${SESSION_ID}.json"
+  if [ -f "$_META_FILE" ]; then
+    if command -v jq &>/dev/null; then
+      _META_PASSED=$(jq -r '.passed' "$_META_FILE" 2>/dev/null)
+      _META_SUGGEST=$(jq -r '.suggestion // ""' "$_META_FILE" 2>/dev/null)
+      if [ "$_META_PASSED" = "false" ] && [ -n "$_META_SUGGEST" ] && [ "$_META_SUGGEST" != "null" ]; then
+        _META_TAG_NUDGE="[arka:suggest] ${_META_SUGGEST}"
+      fi
+    fi
+    rm -f "$_META_FILE" 2>/dev/null
+  fi
+fi
+
 # ─── Output ──────────────────────────────────────────────────────────────
 _OUT_CONTEXT="${_ARKA_GREETING:-}${_SYNC_NOTICE:-}${_ROUTE_REMINDER}${_WORKFLOW_DIRECTIVE} $python_result"
 [ -n "$_HYGIENE" ] && _OUT_CONTEXT="$_OUT_CONTEXT $_HYGIENE"
 [ -n "$_KB_CITE_NUDGE" ] && _OUT_CONTEXT="$_OUT_CONTEXT
 $_KB_CITE_NUDGE"
+[ -n "$_META_TAG_NUDGE" ] && _OUT_CONTEXT="$_OUT_CONTEXT
+$_META_TAG_NUDGE"
 [ -n "$_ARKA_CONTEXT_HITS" ] && _OUT_CONTEXT="$_OUT_CONTEXT
 $_ARKA_CONTEXT_HITS"
 # Escape for JSON

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/core/governance/meta_tag_check.py

@@ -0,0 +1,63 @@
+"""[arka:meta] one-liner soft-block check (PR30 v2.49.0).
+
+Response-side classifier. Inspects an assistant response for the
+``[arka:meta] kb=N research=X persona=Y gap=Z critic=W`` one-liner
+established by the session-start hook in PR12 v2.34.0.
+
+Soft-block contract — never raises. Hooks consume MetaTagResult and
+decide whether to surface a suggestion. Mirrors the shape of
+``core.governance.kb_cite_check`` (PR18 v2.40.0).
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+_META_TAG_RE: re.Pattern[str] = re.compile(r"\[arka:meta\]", re.IGNORECASE)
+_BYPASS_DEFAULTS: tuple[str, ...] = ("[arka:trivial]",)
+_TRIVIAL_WORD_THRESHOLD: int = 15
+_SUGGESTION_TEXT: str = (
+    "Meta-tag missing — end substantive responses with a single "
+    "`[arka:meta] kb=N research=X persona=Y gap=Z critic=W` line. "
+    "Fields: kb=N (notes consulted), research=X (MCPs invoked or "
+    "'none'), persona=Y (advisor or 'orchestrator'), gap=Z (KB gap "
+    "or 'none'), critic=W (passed|failed|skipped)."
+)
+
+
+@dataclass(frozen=True)
+class MetaTagResult:
+    """Verdict of a meta-tag check. Immutable; safe to log as JSON."""
+    passed: bool
+    reason: str
+    suggestion: str | None
+
+
+def check_meta_tag(
+    response_text: str,
+    *,
+    bypass_markers: tuple[str, ...] = _BYPASS_DEFAULTS,
+) -> MetaTagResult:
+    """Classify whether a response carries the [arka:meta] one-liner.
+
+    Order matters: a SHORT response *with* the tag still counts as
+    `present` — the trivial-length bypass only short-circuits when
+    the tag genuinely isn't there.
+    """
+    text = response_text or ""
+    if _has_bypass_marker(text, bypass_markers):
+        return MetaTagResult(True, "trivial", None)
+    if _META_TAG_RE.search(text):
+        return MetaTagResult(True, "present", None)
+    if _is_trivial_length(text):
+        return MetaTagResult(True, "trivial", None)
+    return MetaTagResult(False, "missing", _SUGGESTION_TEXT)
+
+
+def _has_bypass_marker(text: str, markers: tuple[str, ...]) -> bool:
+    return any(marker in text for marker in markers)
+
+
+def _is_trivial_length(text: str) -> bool:
+    return len(text.split()) < _TRIVIAL_WORD_THRESHOLD

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "2.47.0",
+  "version": "2.49.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.49.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}