arkaos 2.40.0 → 2.42.0

package/VERSION

@@ -1 +1 @@
-2.40.0
+2.42.0

package/arka/SKILL.md

@@ -185,8 +185,10 @@ 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 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. 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 |
 | `/arka onboard <path>` | Onboard an existing project into ArkaOS |

package/core/cognition/reorganizer.py

@@ -0,0 +1,412 @@
+"""Dreaming → Agent reorganizer MVP (PR20 v2.42.0).
+
+Propose-only. Scans the KB for pattern/anti-pattern/lesson artifacts
+produced by Dreaming, sanitizes client identifiers, and renders a
+markdown proposal report. Never modifies agent YAMLs — that step is
+left for human review (and PR21 will wire optional auto-PR creation).
+
+Reads only. The only write is the proposal markdown file under
+``output_dir`` (default ``~/.arkaos/reorganize-proposals/``), and only
+when ``dry_run=False``.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import tempfile
+from dataclasses import dataclass, field
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+
+_FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---\n(.*)", re.DOTALL)
+_BODY_EXCERPT_LIMIT = 500
+_PROPOSAL_FILENAME_FMT = "%Y-%m-%d.md"
+_DEFAULT_OUTPUT_DIR = Path.home() / ".arkaos" / "reorganize-proposals"
+_REDACT_TOKEN = "<redacted-client>"
+
+# Client-name redaction patterns are loaded from a user-local JSON file —
+# NEVER hard-coded in source. v2.18.0 shipped client names in source and
+# leaked them to the npm registry (see feedback_npm_publish_safety in
+# user memory); v2.42.0 fixes that class of mistake by design.
+#
+# File: ~/.arkaos/redaction-clients.json
+# Shape: {"clients": ["client-a", "client-b", ...]}
+# Missing file or malformed JSON → empty list (no redaction, tags-drop
+# safety net at `_render` is the architectural backstop).
+#
+# Word boundary uses negative lookaround that allows hyphens so
+# `client-a-billing-quirk` redacts the `client-a` segment correctly
+# without false-positives on `client-axfoo`.
+_REDACT_CONFIG_PATH = Path.home() / ".arkaos" / "redaction-clients.json"
+
+
+def _load_client_patterns() -> tuple[str, ...]:
+    """Read the user-local redaction list. Empty tuple on any error."""
+    try:
+        data = json.loads(_REDACT_CONFIG_PATH.read_text(encoding="utf-8"))
+        raw = data.get("clients", [])
+        return tuple(str(c).strip().lower() for c in raw if c and isinstance(c, str))
+    except (OSError, json.JSONDecodeError, AttributeError):
+        return ()
+
+
+def _build_redact_re(patterns: tuple[str, ...]) -> re.Pattern[str] | None:
+    if not patterns:
+        return None
+    escaped = [re.escape(p) for p in patterns]
+    return re.compile(
+        r"(?<![a-z0-9])(" + "|".join(escaped) + r")(?![a-z0-9])",
+        re.IGNORECASE,
+    )
+
+
+_CLIENT_PATTERNS: tuple[str, ...] = _load_client_patterns()
+_REDACT_RE: re.Pattern[str] | None = _build_redact_re(_CLIENT_PATTERNS)
+
+_KNOWN_CATEGORIES = ("pattern", "anti-pattern", "lesson")
+
+
+@dataclass(frozen=True)
+class KbArtifact:
+    """One pattern / anti-pattern / lesson surfaced from the KB."""
+    path: Path
+    category: str
+    title: str
+    confidence: str
+    tags: list[str] = field(default_factory=list)
+    first_seen: str = ""
+    last_seen: str = ""
+    times_used: int = 0
+    body_excerpt: str = ""
+
+
+@dataclass(frozen=True)
+class ProposalReport:
+    """Result of build_proposal — never contains client identifiers."""
+    generated_at: str
+    since_days: int
+    kb_dir: str
+    artifact_count: int
+    by_category: dict[str, int] = field(default_factory=dict)
+    report_markdown: str = ""
+    report_path: Path | None = None
+
+
+def build_proposal(
+    kb_dir: Path,
+    *,
+    since_days: int = 7,
+    output_dir: Path | None = None,
+    dry_run: bool = False,
+) -> ProposalReport:
+    """Aggregate recent KB artifacts into a propose-only markdown report."""
+    kb_dir = Path(kb_dir)
+    cutoff = datetime.now(timezone.utc).date() - timedelta(days=max(since_days - 1, 0))
+    artifacts = _scan_kb(kb_dir, cutoff)
+    by_category = _aggregate_by_category(artifacts)
+    generated_at = datetime.now(timezone.utc).isoformat()
+    markdown = _render(artifacts, by_category, since_days, kb_dir, generated_at)
+    report_path = None if dry_run else _write_report(markdown, output_dir)
+    return ProposalReport(
+        generated_at=generated_at,
+        since_days=since_days,
+        kb_dir=str(kb_dir),
+        artifact_count=len(artifacts),
+        by_category=by_category,
+        report_markdown=markdown,
+        report_path=report_path,
+    )
+
+
+def _aggregate_by_category(artifacts: list[KbArtifact]) -> dict[str, int]:
+    counts: dict[str, int] = {}
+    for art in artifacts:
+        counts[art.category] = counts.get(art.category, 0) + 1
+    return counts
+
+
+def _write_report(markdown: str, output_dir: Path | None) -> Path:
+    """Atomic markdown write to a validated output directory."""
+    out = _validate_output_dir(output_dir)
+    out.mkdir(parents=True, exist_ok=True)
+    report_path = out / datetime.now(timezone.utc).strftime(_PROPOSAL_FILENAME_FMT)
+    tmp_path = report_path.with_suffix(f".tmp-{os.getpid()}.md")
+    tmp_path.write_text(markdown, encoding="utf-8")
+    os.replace(tmp_path, report_path)
+    return report_path
+
+
+def _validate_output_dir(output_dir: Path | None) -> Path:
+    """Allowlist the output directory to a safe parent.
+
+    Without this guard, programmatic callers passing an attacker-controlled
+    ``output_dir`` could write the proposal report anywhere the process has
+    write access (e.g., ``~/.ssh/``). Even though the CLI does not expose
+    ``--output-dir``, the public API does — defence in depth.
+
+    Allowed roots:
+      - ``~/.arkaos`` — the canonical production location
+      - the system tempdir — for tests using pytest's ``tmp_path`` and any
+        deliberate scratch use; still bounded by OS process privilege
+    """
+    if output_dir is None:
+        return _DEFAULT_OUTPUT_DIR
+    resolved = Path(output_dir).expanduser().resolve()
+    allowed_roots = (
+        (Path.home() / ".arkaos").resolve(),
+        Path(tempfile.gettempdir()).resolve(),
+    )
+    for root in allowed_roots:
+        try:
+            resolved.relative_to(root)
+            return resolved
+        except ValueError:
+            continue
+    raise ValueError(
+        "output_dir must be under one of "
+        f"{[str(r) for r in allowed_roots]}; got {resolved}"
+    )
+
+
+def _scan_kb(kb_dir: Path, cutoff) -> list[KbArtifact]:
+    if not kb_dir.is_dir():
+        return []
+    out: list[KbArtifact] = []
+    for md in sorted(kb_dir.rglob("*.md")):
+        category = _category_from_filename(md.name)
+        if category is None:
+            continue
+        try:
+            text = md.read_text(encoding="utf-8")
+        except OSError:
+            continue
+        artifact = _parse_artifact(md, text, category)
+        if artifact is None:
+            continue
+        if not _within_window(artifact, cutoff):
+            continue
+        out.append(artifact)
+    return out
+
+
+def _category_from_filename(name: str) -> str | None:
+    lower = name.lower()
+    if lower.startswith("anti-pattern-"):
+        return "anti-pattern"
+    if lower.startswith("pattern-"):
+        return "pattern"
+    if lower.startswith("lesson-"):
+        return "lesson"
+    return None
+
+
+def _parse_artifact(path: Path, text: str, default_category: str) -> KbArtifact | None:
+    match = _FRONTMATTER_RE.match(text)
+    if not match:
+        return None
+    fm = _parse_frontmatter(match.group(1))
+    if not fm:
+        return None
+    body = match.group(2)
+    category = str(fm.get("category", default_category))
+    if category not in _KNOWN_CATEGORIES:
+        category = default_category
+    raw_title = str(fm.get("title", path.stem))
+    excerpt = _redact(_body_excerpt(body))
+    times_used = _safe_int(fm.get("times_used"))
+    return KbArtifact(
+        path=path,
+        category=category,
+        title=_redact(raw_title),
+        confidence=str(fm.get("confidence", "")),
+        tags=_parse_list(fm.get("tags")),
+        first_seen=str(fm.get("first_seen", "")),
+        last_seen=str(fm.get("last_seen", "")),
+        times_used=times_used,
+        body_excerpt=excerpt,
+    )
+
+
+def _within_window(artifact: KbArtifact, cutoff) -> bool:
+    for raw in (artifact.last_seen, artifact.first_seen):
+        try:
+            seen = datetime.strptime(raw, "%Y-%m-%d").date()
+        except (ValueError, TypeError):
+            continue
+        if seen >= cutoff:
+            return True
+    return not artifact.first_seen and not artifact.last_seen
+
+
+def _parse_frontmatter(block: str) -> dict:
+    out: dict[str, object] = {}
+    current_key: str | None = None
+    current_list: list[str] = []
+    for raw_line in block.splitlines():
+        if not raw_line.strip():
+            continue
+        if raw_line.startswith("  - "):
+            current_list.append(raw_line[4:].strip())
+            continue
+        if current_key is not None and current_list:
+            out[current_key] = list(current_list)
+            current_list = []
+        current_key = None
+        if ":" not in raw_line:
+            continue
+        key, _, value = raw_line.partition(":")
+        key, value = key.strip(), value.strip()
+        if value == "":
+            current_key = key
+            continue
+        out[key] = _parse_inline_value(value)
+    if current_key is not None and current_list:
+        out[current_key] = list(current_list)
+    return out
+
+
+def _parse_inline_value(value: str) -> object:
+    if value.startswith("[") and value.endswith("]"):
+        inner = value[1:-1].strip()
+        if not inner:
+            return []
+        return [item.strip() for item in inner.split(",")]
+    return value
+
+
+def _parse_list(value: object) -> list[str]:
+    if isinstance(value, list):
+        return [str(v) for v in value]
+    if isinstance(value, str) and value:
+        return [value]
+    return []
+
+
+def _safe_int(value: object) -> int:
+    try:
+        return int(str(value))
+    except (TypeError, ValueError):
+        return 0
+
+
+def _redact(text: str) -> str:
+    if _REDACT_RE is None:
+        return text
+    return _REDACT_RE.sub(_REDACT_TOKEN, text)
+
+
+def _md_escape(text: str) -> str:
+    """Escape markdown control characters that would distort a table row.
+
+    Titles and excerpts come from frontmatter the operator controls, but
+    a `|` in a title silently shifts table columns and corrupts the raw-
+    artifact table. Escape pipes, newlines, and stray backticks.
+    """
+    return (
+        text.replace("\\", "\\\\")
+            .replace("|", "\\|")
+            .replace("\n", " ")
+            .replace("\r", " ")
+            .replace("`", "")
+    )
+
+
+def _body_excerpt(body: str) -> str:
+    stripped = body.strip()
+    if len(stripped) <= _BODY_EXCERPT_LIMIT:
+        return stripped
+    return stripped[:_BODY_EXCERPT_LIMIT].rstrip() + "..."
+
+
+def _render(
+    artifacts: list[KbArtifact],
+    by_category: dict[str, int],
+    since_days: int,
+    kb_dir: Path,
+    generated_at: str,
+) -> str:
+    today = generated_at.split("T", 1)[0]
+    parts = [
+        _render_header(today, len(artifacts), since_days),
+        _render_summary(by_category, since_days, len(artifacts)),
+    ]
+    if not artifacts:
+        parts.append("\n_(no artifacts in window — nothing to propose)_")
+        return "\n".join(parts)
+    parts.append(_render_suggested_actions(artifacts))
+    parts.append("## Raw artifact list\n\n" + _render_table(artifacts))
+    return "\n".join(parts)
+
+
+def _render_header(today: str, count: int, since_days: int) -> str:
+    return (
+        f"# ArkaOS Reorganization Proposal — {today}\n"
+        "\n"
+        f"> Generated by `/arka reorganize` from {count} artifact(s) "
+        f"learned in the last {since_days} days.\n"
+        "> **Propose-only** — no agent YAML changes have been applied."
+    )
+
+
+def _render_summary(by_category: dict[str, int], since_days: int, count: int) -> str:
+    lines = [
+        "\n## Summary\n",
+        f"- Window: last {since_days} days",
+        f"- Artifacts: **{count}**",
+    ]
+    for cat in _KNOWN_CATEGORIES:
+        if cat in by_category:
+            lines.append(f"- {cat.capitalize()}s: {by_category[cat]}")
+    return "\n".join(lines)
+
+
+def _render_suggested_actions(artifacts: list[KbArtifact]) -> str:
+    lines = ["\n## Suggested actions\n"]
+    for cat in _KNOWN_CATEGORIES:
+        cat_items = [a for a in artifacts if a.category == cat]
+        if not cat_items:
+            continue
+        lines.append(f"### {cat.capitalize()}s\n")
+        for art in cat_items:
+            lines.append(_render_artifact_bullet(art, cat))
+    return "\n".join(lines)
+
+
+def _render_artifact_bullet(art: KbArtifact, category: str) -> str:
+    # Tags intentionally NOT rendered — see _CLIENT_PATTERNS comment.
+    line = (
+        f"- **{art.title}** (confidence: {art.confidence or 'n/a'}, "
+        f"times_used: {art.times_used})\n"
+        f"  suggested: review for {_suggest_target(category)}"
+    )
+    if art.body_excerpt:
+        line += f"\n  > {art.body_excerpt}"
+    return line + "\n"
+
+
+def _suggest_target(category: str) -> str:
+    if category == "pattern":
+        return "surfacing in the relevant department squad's context"
+    if category == "anti-pattern":
+        return "candidate detector in `core/governance/learning_detector.py`"
+    if category == "lesson":
+        return "Tier 0 review — potential constitution amendment"
+    return "manual review"
+
+
+def _render_table(artifacts: list[KbArtifact]) -> str:
+    rows = [
+        "| Category | Title | Confidence | first_seen | last_seen | times_used |",
+        "|---|---|---|---|---|---|",
+    ]
+    for art in artifacts:
+        rows.append(
+            f"| {_md_escape(art.category)} | {_md_escape(art.title)} "
+            f"| {_md_escape(art.confidence) or 'n/a'} "
+            f"| {_md_escape(art.first_seen) or 'n/a'} "
+            f"| {_md_escape(art.last_seen) or 'n/a'} "
+            f"| {art.times_used} |"
+        )
+    return "\n".join(rows)

package/core/cognition/reorganizer_cli.py

@@ -0,0 +1,72 @@
+"""CLI for the propose-only Dreaming reorganizer (PR20 v2.42.0).
+
+Invoked as ``python -m core.cognition.reorganizer_cli [options]``.
+Reads recent KB artifacts (pattern / anti-pattern / lesson files),
+sanitizes client identifiers, and writes a proposal markdown report.
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from pathlib import Path
+
+from core.cognition.reorganizer import build_proposal
+
+# Default KB location — the Obsidian vault subfolder where Dreaming v2
+# writes pattern/anti-pattern/lesson artifacts. Overridable via env var
+# or --kb-dir for tests and unusual installs.
+_DEFAULT_KB_DIR = (
+    Path.home()
+    / "Documents" / "Personal" / "Projects"
+    / "WizardingCode Internal" / "ArkaOS" / "Knowledge Base"
+)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="arkaos-reorganize",
+        description="Aggregate recent KB artifacts into a propose-only "
+                    "markdown report. Never modifies agent YAMLs.",
+    )
+    parser.add_argument(
+        "--since-days", type=int, default=7,
+        help="Window in days for first_seen/last_seen filter (default: 7).",
+    )
+    parser.add_argument(
+        "--kb-dir", type=Path, default=None,
+        help="Override the KB directory to scan (default: ArkaOS vault).",
+    )
+    parser.add_argument(
+        "--dry-run", action="store_true",
+        help="Print the report to stdout, do not write to disk.",
+    )
+    return parser
+
+
+def main(argv: list[str]) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv[1:])
+    kb_dir = args.kb_dir or Path(os.environ.get("ARKAOS_KB_DIR", _DEFAULT_KB_DIR))
+
+    report = build_proposal(
+        kb_dir,
+        since_days=args.since_days,
+        dry_run=args.dry_run,
+    )
+
+    if args.dry_run:
+        print(report.report_markdown)
+        return 0
+
+    print(f"Artifacts: {report.artifact_count}")
+    for cat, count in sorted(report.by_category.items()):
+        print(f"  {cat}: {count}")
+    if report.report_path is not None:
+        print(f"Report: {report.report_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv))

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.42.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.42.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}