arkaos 2.39.0 → 2.40.0

package/VERSION

@@ -1 +1 @@
-2.39.0
+2.40.0

package/config/hooks/stop.sh

@@ -113,6 +113,47 @@ try:
 except Exception:
     pass
 
+# PR18 v2.40.0 — KB citation soft-block. Records whether the closing
+# assistant message cited the vault on an ArkaOS topic. Result is also
+# persisted to /tmp/arkaos-cite/<session>.json so the next UserPromptSubmit
+# can surface a nudge if passed=False. Non-blocking; never raises.
+cite_passed = True
+cite_reason = "trivial"
+cite_count = 0
+cite_topic_score = 0.0
+cite_suggestion: str | None = None
+try:
+    from core.governance.kb_cite_check import check_citation
+    cr = check_citation(last)
+    cite_passed = cr.passed
+    cite_reason = cr.reason
+    cite_count = cr.citation_count
+    cite_topic_score = cr.topic_score
+    cite_suggestion = cr.suggestion
+    # PR18 security fix: session_id comes from the runtime via stdin JSON
+    # and is untrusted. Reuse the shared allowlist before building any
+    # filesystem path. Reject (skip write) on anything outside
+    # [A-Za-z0-9._-]{1,128} — no `..`, no slashes, no whitespace, no NUL.
+    try:
+        from core.shared.safe_session_id import safe_session_id as _safe_sid
+        safe_sid = _safe_sid(session_id)
+    except Exception:
+        safe_sid = None
+    if safe_sid:
+        cite_dir = Path("/tmp/arkaos-cite")
+        cite_dir.mkdir(parents=True, exist_ok=True)
+        cite_path = cite_dir / f"{safe_sid}.json"
+        cite_payload = {
+            "passed": cr.passed,
+            "reason": cr.reason,
+            "suggestion": cr.suggestion,
+            "citation_count": cr.citation_count,
+            "topic_score": cr.topic_score,
+        }
+        cite_path.write_text(json.dumps(cite_payload), encoding="utf-8")
+except Exception:
+    pass
+
 entry = {
     "ts": datetime.now(timezone.utc).isoformat(),
     "session_id": session_id,
@@ -125,6 +166,10 @@ entry = {
     "sycophancy_is_flagged": is_sycophantic,
     "sycophancy_signals": sycophancy_signals,
     "sycophancy_confidence": sycophancy_confidence,
+    "kb_cite_passed": cite_passed,
+    "kb_cite_reason": cite_reason,
+    "kb_cite_count": cite_count,
+    "kb_cite_topic_score": cite_topic_score,
     "mode": "warn",
 }
 

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

@@ -370,9 +370,34 @@ if [ -n "$SESSION_ID" ]; then
   fi
 fi
 
+# ─── KB citation nudge (PR18 v2.40.0) ────────────────────────────────────
+# Read the cite-check result written by the previous Stop hook. If the
+# last assistant turn was on an ArkaOS topic without any citation, surface
+# the suggestion to the model in this turn's additionalContext. One-shot:
+# the file is deleted after read so the nudge does not repeat across turns.
+_KB_CITE_NUDGE=""
+if [ -n "$SESSION_ID" ]; then
+  _CITE_FILE="/tmp/arkaos-cite/${SESSION_ID}.json"
+  if [ -f "$_CITE_FILE" ]; then
+    if command -v jq &>/dev/null; then
+      # NOTE: do not use `// true` here — jq's `//` treats false as needing
+      # the default, which would suppress the nudge in the exact case we
+      # care about. Read .passed raw and compare to the literal "false".
+      _CITE_PASSED=$(jq -r '.passed' "$_CITE_FILE" 2>/dev/null)
+      _CITE_SUGGEST=$(jq -r '.suggestion // ""' "$_CITE_FILE" 2>/dev/null)
+      if [ "$_CITE_PASSED" = "false" ] && [ -n "$_CITE_SUGGEST" ] && [ "$_CITE_SUGGEST" != "null" ]; then
+        _KB_CITE_NUDGE="[arka:suggest] ${_CITE_SUGGEST}"
+      fi
+    fi
+    rm -f "$_CITE_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 "$_ARKA_CONTEXT_HITS" ] && _OUT_CONTEXT="$_OUT_CONTEXT
 $_ARKA_CONTEXT_HITS"
 # Escape for JSON

package/core/governance/__init__.py

@@ -1,5 +1,11 @@
 """Governance engine — Constitution, quality gates, audit trails."""
 
 from core.governance.constitution import Constitution, load_constitution
+from core.governance.kb_cite_check import CitationResult, check_citation
 
-__all__ = ["Constitution", "load_constitution"]
+__all__ = [
+    "CitationResult",
+    "Constitution",
+    "check_citation",
+    "load_constitution",
+]

package/core/governance/kb_cite_check.py

@@ -0,0 +1,129 @@
+"""KB citation check for ArkaOS responses (PR18 v2.40.0).
+
+Soft-block classifier. Inspects an assistant response for KB
+citations (`[[wikilink]]`, `[knowledge:` marker, `file.ext:line`
+code references) and reports whether the response honored the
+KB-first contract on an ArkaOS topic.
+
+Non-blocking by design — hooks consume CitationResult and decide
+whether to surface a nudge to the next turn's additionalContext.
+This module never raises; on malformed input it returns a passed
+"trivial" verdict so the caller never crashes the hook pipeline.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# ─── Patterns ───────────────────────────────────────────────────────────
+
+_WIKILINK_PATTERN: re.Pattern[str] = re.compile(r"\[\[([^\[\]]+)\]\]")
+_KNOWLEDGE_PATTERN: re.Pattern[str] = re.compile(r"\[knowledge:", re.IGNORECASE)
+# File:line — requires at least one path separator. Quantifiers are bounded
+# to prevent catastrophic backtracking on pathological input (PR18 security
+# review: unbounded variant blew past Stop's 5s budget by ~8x on 100KB of
+# `a/a/a/...` with no trailing extension).
+_FILE_LINE_PATTERN: re.Pattern[str] = re.compile(
+    r"(?:[\w._-]{1,64}/){1,8}[\w._-]{1,64}\.\w{1,8}:\d{1,6}"
+)
+# Hard upper bound on input scanned for citations. Anything beyond is
+# almost certainly a code dump / log paste and not human prose — skip the
+# more expensive file-line regex entirely above this threshold.
+_MAX_SCAN_CHARS: int = 50_000
+
+# ArkaOS topic keywords. Match is case-insensitive substring.
+_ARKAOS_KEYWORDS: frozenset[str] = frozenset({
+    "arkaos", "arka", "constitution", "quality gate", "synapse",
+    "conclave", "forge", "dreaming", "marta", "eduardo", "francisca",
+    "marco", "helena", "sofia", "paulo", "luna", "valentina",
+    "tomas", "ricardo", "clara", "daniel", "carolina", "tiago",
+    "ines", "rafael", "beatriz", "miguel", "rodrigo",
+    "non-negotiable", "tier 0", "squad lead",
+    "core/governance", "core/synapse", "core/cognition",
+    "core/workflow", "mcp__obsidian", "kb-first",
+    "departments/", "agent yaml", "obsidian vault",
+})
+
+_BYPASS_DEFAULTS: tuple[str, ...] = ("[arka:trivial]",)
+_TRIVIAL_WORD_THRESHOLD: int = 15
+_TOPIC_THRESHOLD: float = 0.4
+_SUGGESTION_TEXT: str = (
+    "KB-first — last response had no citation on ArkaOS topic. "
+    "Use @[[note-name]], /kb search, or mcp__obsidian__search_notes "
+    "to ground the next answer."
+)
+
+
+# ─── Result ─────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class CitationResult:
+    """Verdict of a citation check. Immutable; safe to log as JSON."""
+    passed: bool
+    reason: str
+    suggestion: str | None
+    citation_count: int
+    topic_score: float
+
+
+# ─── Public API ─────────────────────────────────────────────────────────
+
+
+def check_citation(
+    response_text: str,
+    *,
+    topic_keywords: frozenset[str] | None = None,
+    bypass_markers: tuple[str, ...] = _BYPASS_DEFAULTS,
+) -> CitationResult:
+    """Classify an assistant response for KB citation discipline."""
+    text = response_text or ""
+    citation_count = _count_citations(text)
+    topic_score = _compute_topic_score(text, topic_keywords or _ARKAOS_KEYWORDS)
+
+    if _has_bypass_marker(text, bypass_markers):
+        return CitationResult(True, "trivial", None, citation_count, topic_score)
+
+    if _is_trivial_length(text):
+        return CitationResult(True, "trivial", None, citation_count, topic_score)
+
+    if citation_count > 0:
+        return CitationResult(True, "cited", None, citation_count, topic_score)
+
+    if topic_score < _TOPIC_THRESHOLD:
+        return CitationResult(True, "off-topic", None, 0, topic_score)
+
+    return CitationResult(False, "missing", _SUGGESTION_TEXT, 0, topic_score)
+
+
+# ─── Helpers (private) ──────────────────────────────────────────────────
+
+
+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
+
+
+def _count_citations(text: str) -> int:
+    # Truncate to _MAX_SCAN_CHARS first; the file-line regex is the only
+    # backtracking-prone pattern and the bounded quantifiers (capped at 8
+    # segments × 64 chars each) combined with this slice make all three
+    # patterns safe to run unconditionally below.
+    scan = text if len(text) <= _MAX_SCAN_CHARS else text[:_MAX_SCAN_CHARS]
+    wikilinks = len(_WIKILINK_PATTERN.findall(scan))
+    knowledge = 1 if _KNOWLEDGE_PATTERN.search(scan) else 0
+    files = len(_FILE_LINE_PATTERN.findall(scan))
+    return wikilinks + knowledge + files
+
+
+def _compute_topic_score(text: str, keywords: frozenset[str]) -> float:
+    if not keywords:
+        return 0.0
+    lower = text.lower()
+    hits = sum(1 for k in keywords if k.lower() in lower)
+    denom = max(1, len(keywords) // 10)
+    return min(1.0, hits / denom)

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "arkaos",
-  "version": "2.39.0",
+  "version": "2.40.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {
-    "arkaos": "./installer/cli.js"
+    "arkaos": "installer/cli.js"
   },
   "scripts": {
     "test": "node --test \"tests/installer/**/*.test.js\"",

package/pyproject.toml

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