arkaos 2.40.0 → 2.41.0

package/VERSION

@@ -1 +1 @@
-2.40.0
+2.41.0

package/arka/SKILL.md

@@ -185,8 +185,9 @@ violation (squad-routing, arka-supremacy, spec-driven, mandatory-qa).
 
 | Command | Description |
 |---------|-------------|
-| `/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")`. |
+| `/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). |
 | `/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 standup` | Daily standup (projects, priorities, blockers, updates) |
 | `/arka monitor` | System health monitoring |
 | `/arka onboard <path>` | Onboard an existing project into ArkaOS |

package/core/governance/enforcement_telemetry.py

@@ -0,0 +1,144 @@
+"""Enforcement telemetry summarizer (PR19 v2.41.0).
+
+Reads ``~/.arkaos/telemetry/enforcement.jsonl`` (the JSONL stream the
+PreToolUse hook appends to on every gated tool decision) and produces
+compact summaries for ``/arka status`` and downstream tuning.
+
+Mirrors the pattern of ``core.runtime.llm_cost_telemetry`` so periods,
+malformed-line tolerance, and zero-division safety behave the same way
+across the two telemetry surfaces. Read-only — never writes to the
+JSONL itself.
+"""
+
+from __future__ import annotations
+
+import json
+from collections import Counter
+from dataclasses import dataclass, field
+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"})
+_TOP_N: int = 5
+
+
+@dataclass(frozen=True)
+class EnforcementSummary:
+    """Aggregated enforcement telemetry over a time slice."""
+    period: str
+    total_calls: int
+    blocked_calls: int
+    block_rate: float
+    bypass_used: int
+    top_blocked_tools: list[tuple[str, int]] = field(default_factory=list)
+    top_block_reasons: list[tuple[str, int]] = field(default_factory=list)
+    corrupt_line_count: int = 0
+
+
+def summarise(period: str, *, path: Path | None = None) -> EnforcementSummary:
+    """Return an EnforcementSummary for the requested period.
+
+    period: one of "today", "week", "month", "all".
+    path:   override telemetry source (used by tests; defaults to DEFAULT_PATH).
+    """
+    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_jsonl(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_jsonl(src: Path, cutoff: datetime | None) -> tuple[list[dict[str, Any]], int]:
+    if not src.exists():
+        return [], 0
+    entries: list[dict[str, Any]] = []
+    corrupt = 0
+    # Line-stream the file to keep memory O(1) regardless of telemetry size.
+    # A runaway hook could grow this file to multiple GB; reading it whole
+    # would OOM the /arka status / /arka enforcement caller.
+    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 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"))
+    if ts is None:
+        return False
+    return 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,
+) -> EnforcementSummary:
+    total = 0
+    blocked = 0
+    bypass = 0
+    blocked_tools: Counter[str] = Counter()
+    block_reasons: Counter[str] = Counter()
+    for entry in entries:
+        total += 1
+        if entry.get("bypass_used"):
+            bypass += 1
+        if entry.get("allow") is False:
+            blocked += 1
+            tool = str(entry.get("tool", ""))
+            reason = str(entry.get("reason", ""))
+            if tool:
+                blocked_tools[tool] += 1
+            if reason:
+                block_reasons[reason] += 1
+    return EnforcementSummary(
+        period=period,
+        total_calls=total,
+        blocked_calls=blocked,
+        block_rate=(blocked / total) if total else 0.0,
+        bypass_used=bypass,
+        top_blocked_tools=blocked_tools.most_common(_TOP_N),
+        top_block_reasons=block_reasons.most_common(_TOP_N),
+        corrupt_line_count=corrupt,
+    )

package/core/governance/enforcement_telemetry_cli.py

@@ -0,0 +1,67 @@
+"""CLI entry for the enforcement telemetry summarizer (PR19 v2.41.0).
+
+Invoked as ``python -m core.governance.enforcement_telemetry_cli <period>``
+where ``<period>`` is one of: today, week, month, all.
+
+Output is plain markdown so it renders cleanly in both the terminal and
+the ``/arka status`` skill which concatenates it into its report.
+"""
+
+from __future__ import annotations
+
+import sys
+
+from core.governance.enforcement_telemetry import (
+    EnforcementSummary,
+    summarise,
+)
+
+
+def _fmt_rate(value: float) -> str:
+    return f"{value * 100:.2f}%"
+
+
+def _sanitize_md(value: str) -> str:
+    """Strip markdown-breaking characters before rendering JSONL strings.
+
+    Telemetry is local-writer-only, but a malformed tool/reason value (newline,
+    backtick) can still distort the markdown if /arka status pipes the output
+    to a UI. Belt-and-braces against passive corruption, not active attack.
+    """
+    return value.replace("\n", " ").replace("\r", " ").replace("`", "").strip()
+
+
+def _render(summary: EnforcementSummary) -> str:
+    lines = [
+        f"# Enforcement — {summary.period}",
+        "",
+        f"- Calls: **{summary.total_calls}**",
+        f"- Blocked: **{summary.blocked_calls}** ({_fmt_rate(summary.block_rate)})",
+        f"- Bypass used (`ARKA_BYPASS_FLOW=1`): **{summary.bypass_used}**",
+    ]
+    if summary.top_blocked_tools:
+        lines += ["", "## Top blocked tools"]
+        for tool, count in summary.top_blocked_tools:
+            lines.append(f"- `{_sanitize_md(tool)}` — {count}")
+    if summary.top_block_reasons:
+        lines += ["", "## Top block reasons"]
+        for reason, count in summary.top_block_reasons:
+            lines.append(f"- {_sanitize_md(reason)} — {count}")
+    if summary.corrupt_line_count:
+        lines += ["", f"_(skipped {summary.corrupt_line_count} corrupt line(s))_"]
+    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/workflow/flow_enforcer.py

@@ -214,11 +214,10 @@ class Decision:
         if self.allow:
             return ""
         return (
-            f"[ARKA:ENFORCEMENT] Flow marker missing. "
-            f"Emit `[arka:routing] <dept> -> <lead>` or `[arka:trivial] <reason>` "
-            f"before any tool that mutates state "
-            f"(Write/Edit/MultiEdit/NotebookEdit/Task/Skill, or Bash with effect commands like rm/mv/git commit/npm install). "
-            f"Reason: {self.reason}"
+            f"[ARKA:ENFORCEMENT] Missing `[arka:routing] <dept> -> <lead>` or "
+            f"`[arka:trivial] <reason>` before "
+            f"Write/Edit/MultiEdit/NotebookEdit/Task/Skill/Bash-effect. "
+            f"Bypass once with `ARKA_BYPASS_FLOW=1`. Reason: {self.reason}."
         )
 
 

package/installer/config-seed.js

@@ -0,0 +1,63 @@
+// ~/.arkaos/config.json seed/migration (PR19 v2.41.0).
+//
+// Run on every `npx arkaos install` and `npx arkaos@latest update`.
+// Idempotent: writes `hooks.hardEnforcement = true` only when the key
+// is unset. Explicit user choice (true OR false) is preserved.
+//
+// Returns a status object:
+//   { action: "created" | "added-key" | "noop"
+//          | "preserved-user-false" | "rewrote-corrupt" }
+// so the installer caller can log a human-readable line per run.
+
+import {
+  existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, copyFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+
+export function seedArkaosConfig({ home = homedir() } = {}) {
+  const cfgPath = join(home, ".arkaos", "config.json");
+
+  if (!existsSync(cfgPath)) {
+    writeConfig(cfgPath, { hooks: { hardEnforcement: true } });
+    return { action: "created", path: cfgPath };
+  }
+
+  let config;
+  try {
+    config = JSON.parse(readFileSync(cfgPath, "utf-8"));
+    if (typeof config !== "object" || config === null) {
+      throw new Error("config root is not an object");
+    }
+  } catch {
+    // Corrupt JSON — keep the broken copy for recovery, write safe default.
+    const backup = `${cfgPath}.broken-${Date.now()}`;
+    try { copyFileSync(cfgPath, backup); } catch { /* best effort */ }
+    writeConfig(cfgPath, { hooks: { hardEnforcement: true } });
+    return { action: "rewrote-corrupt", path: cfgPath, backup };
+  }
+
+  config.hooks = config.hooks && typeof config.hooks === "object" ? config.hooks : {};
+  const current = config.hooks.hardEnforcement;
+
+  if (current === true) {
+    return { action: "noop", path: cfgPath };
+  }
+  if (current === false) {
+    return { action: "preserved-user-false", path: cfgPath };
+  }
+
+  // Key unset (undefined, null, or any non-boolean) — set to true.
+  config.hooks.hardEnforcement = true;
+  writeConfig(cfgPath, config);
+  return { action: "added-key", path: cfgPath };
+}
+
+function writeConfig(cfgPath, payload) {
+  mkdirSync(dirname(cfgPath), { recursive: true });
+  // Atomic write: render to a sibling .tmp then rename. Prevents partial-write
+  // corruption if the process is interrupted between open and close.
+  const tmp = `${cfgPath}.tmp-${process.pid}`;
+  writeFileSync(tmp, JSON.stringify(payload, null, 2) + "\n");
+  renameSync(tmp, cfgPath);
+}

package/installer/index.js

@@ -275,6 +275,26 @@ export async function install({ runtime, path, force, skipSystem, withOllama })
 
   // ═══ Step 14: Finalize ═══
   step(14, 14, "Finalizing...");
+
+  // PR19 v2.41.0 — seed/migrate hooks.hardEnforcement so the PreToolUse
+  // gate blocks tool calls without [arka:routing] on fresh installs.
+  // Idempotent + preserves explicit user `false`.
+  try {
+    const { seedArkaosConfig } = await import("./config-seed.js");
+    const seedResult = seedArkaosConfig({ home: homedir() });
+    if (seedResult.action === "created") {
+      console.log(`         hardEnforcement enabled (default).`);
+    } else if (seedResult.action === "added-key") {
+      console.log(`         hardEnforcement enabled (key was unset).`);
+    } else if (seedResult.action === "preserved-user-false") {
+      console.log(`         hardEnforcement is OFF (user-set, preserved).`);
+    } else if (seedResult.action === "rewrote-corrupt") {
+      console.log(`         config.json was corrupt — rewrote, backup at ${seedResult.backup}`);
+    }
+  } catch (err) {
+    console.log(`         Warning: could not seed config.json (${err.message})`);
+  }
+
   const manifest = {
     version: VERSION,
     runtime,

package/package.json

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