arkaos 2.20.0 → 2.21.0

package/VERSION

@@ -1 +1 @@
-2.20.0
+2.21.0

package/arka/SKILL.md

@@ -7,6 +7,20 @@ description: >
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
+<!-- arka:kb-first-prefix begin -->
+## KB-First Research (non-negotiable)
+
+Before any external research (Context7, WebSearch, WebFetch, Firecrawl):
+
+1. Call `mcp__obsidian__search_notes` on the query first.
+2. Cite relevant hits with `[[wikilinks]]` or explicitly declare a KB gap.
+3. Only after (1) and (2) may external tools run.
+
+The Synapse L2.5 layer pre-injects top KB matches on every user prompt;
+treat them as your default source. External research supplements, it
+does not replace the vault.
+<!-- arka:kb-first-prefix end -->
+
 # ArkaOS v2 — Main Orchestrator
 
 > **The Operating System for AI Agent Teams**

package/arka/skills/flow/SKILL.md

@@ -7,6 +7,20 @@ description: >
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
+<!-- arka:kb-first-prefix begin -->
+## KB-First Research (non-negotiable)
+
+Before any external research (Context7, WebSearch, WebFetch, Firecrawl):
+
+1. Call `mcp__obsidian__search_notes` on the query first.
+2. Cite relevant hits with `[[wikilinks]]` or explicitly declare a KB gap.
+3. Only after (1) and (2) may external tools run.
+
+The Synapse L2.5 layer pre-injects top KB matches on every user prompt;
+treat them as your default source. External research supplements, it
+does not replace the vault.
+<!-- arka:kb-first-prefix end -->
+
 # ArkaOS — Mandatory Workflow
 
 > This flow runs on **every** user request inside an ArkaOS-managed context.

package/arka/skills/forge/SKILL.md

@@ -8,6 +8,20 @@ description: >
 allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 ---
 
+<!-- arka:kb-first-prefix begin -->
+## KB-First Research (non-negotiable)
+
+Before any external research (Context7, WebSearch, WebFetch, Firecrawl):
+
+1. Call `mcp__obsidian__search_notes` on the query first.
+2. Cite relevant hits with `[[wikilinks]]` or explicitly declare a KB gap.
+3. Only after (1) and (2) may external tools run.
+
+The Synapse L2.5 layer pre-injects top KB matches on every user prompt;
+treat them as your default source. External research supplements, it
+does not replace the vault.
+<!-- arka:kb-first-prefix end -->
+
 # The Forge — ArkaOS Intelligent Planning Engine
 
 > **Engine:** `core/forge/` | **Plans stored:** `~/.arkaos/plans/` | **Obsidian:** `ArkaOS/Forge/`

package/config/hooks/_lib/workflow-classifier.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# ============================================================================
+# ArkaOS v2 — Shared Workflow Classifier
+#
+# Decides whether a user prompt triggers the mandatory 13-phase flow.
+# Used by: user-prompt-submit.sh, pre-tool-use.sh, stop.sh.
+#
+# Contract:
+#   arka_wf_classify "<prompt text>"  → echoes "true" or "false", exits 0.
+#   arka_wf_mark_required "<session_id>"  → writes marker file.
+#   arka_wf_is_required "<session_id>"  → exits 0 if required, 1 otherwise.
+#   arka_wf_clear_required "<session_id>"  → removes marker file.
+#
+# Markers live under /tmp/arkaos-wf-required/<session_id>.
+# Python path for mark/clear: delegates to flow_enforcer.py when available,
+# otherwise falls back to touching the marker file directly.
+# ============================================================================
+
+ARKA_WF_REQUIRED_DIR="${ARKA_WF_REQUIRED_DIR:-/tmp/arkaos-wf-required}"
+
+# Reject any session_id outside [A-Za-z0-9._-]{1,128}. Protects the marker
+# directory from path-traversal writes (CWE-22). Must stay in sync with
+# core/workflow/flow_enforcer.py::_safe_session_id.
+arka_wf_safe_session_id() {
+  local session_id="${1:-}"
+  [ -z "$session_id" ] && return 1
+  [ ${#session_id} -gt 128 ] && return 1
+  case "$session_id" in
+    *[!A-Za-z0-9._-]*) return 1 ;;
+  esac
+  return 0
+}
+
+# Verb + noun patterns shared with the original inline classifier in
+# user-prompt-submit.sh. Keep in sync when adding new intent verbs.
+ARKA_WF_VERB_PATTERN='(criar?|crie[ms]?|cria[mr]?|adicionar?|adiciona[mr]?|implementar?|implementa[mr]?|desenvolver?|desenvolve[mr]?|construir?|constru[ií]a?[mr]?|fazer?|faz[ae][mr]?|refactor(izar?)?|corrigir?|corrige[mr]?|consertar?|conserta[mr]?|create[sd]?|creating|build(s|ing)?|add(s|ed|ing)?|implement(s|ed|ing)?|develop(s|ed|ing)?|fix(es|ed|ing)?|refactor(s|ed|ing)?|make[sd]?|making)'
+
+# Classify: returns "true" if the prompt looks like a creation/
+# implementation/modification request, "false" otherwise.
+# Skips: explicit slash commands (already routed) and bang shells.
+arka_wf_classify() {
+  local text="${1:-}"
+  [ -z "$text" ] && { echo "false"; return 0; }
+
+  local first_char
+  first_char=$(printf '%s' "$text" | head -c 1)
+  if [ "$first_char" = "/" ] || [ "$first_char" = "!" ]; then
+    echo "false"
+    return 0
+  fi
+
+  if echo "$text" | grep -qiE "\b${ARKA_WF_VERB_PATTERN}\b"; then
+    echo "true"
+  else
+    echo "false"
+  fi
+}
+
+# Mark that the flow is required for this session. Safe no-op if session_id
+# is empty or fails the allowlist check.
+arka_wf_mark_required() {
+  local session_id="${1:-}"
+  arka_wf_safe_session_id "$session_id" || return 0
+  mkdir -p "$ARKA_WF_REQUIRED_DIR" 2>/dev/null
+  date -u +"%Y-%m-%dT%H:%M:%SZ" > "$ARKA_WF_REQUIRED_DIR/$session_id" 2>/dev/null
+}
+
+# Test whether flow is required. Exit code 0 = required, 1 = not required.
+arka_wf_is_required() {
+  local session_id="${1:-}"
+  arka_wf_safe_session_id "$session_id" || return 1
+  [ -f "$ARKA_WF_REQUIRED_DIR/$session_id" ]
+}
+
+# Clear the requirement marker. Safe no-op if absent or unsafe.
+arka_wf_clear_required() {
+  local session_id="${1:-}"
+  arka_wf_safe_session_id "$session_id" || return 0
+  rm -f "$ARKA_WF_REQUIRED_DIR/$session_id" 2>/dev/null
+  return 0
+}
+
+# When invoked directly (not sourced), expose a simple CLI for ad-hoc use.
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+  case "${1:-}" in
+    classify)   arka_wf_classify "${2:-}" ;;
+    mark)       arka_wf_mark_required "${2:-}" ;;
+    is-required) arka_wf_is_required "${2:-}" && echo "true" || echo "false" ;;
+    clear)      arka_wf_clear_required "${2:-}" ;;
+    *)
+      echo "Usage: $0 {classify <text>|mark <session_id>|is-required <session_id>|clear <session_id>}" >&2
+      exit 64
+      ;;
+  esac
+fi

package/config/hooks/post-tool-use.ps1

@@ -120,6 +120,86 @@ if ($shouldProcessGotchas -and $null -ne $payload) {
     $exitCode   = if ($null -ne $payload.exit_code)   { [string]$payload.exit_code   } else { '0' }
     $cwd        = if ($null -ne $payload.cwd)         { [string]$payload.cwd         } else { '' }
 
+    # --- Flow marker cache write (v2 ALLOW accelerator) ------------------
+    # Mirror of the bash hook: detect [arka:routing] or [arka:trivial] in
+    # $payload.assistant_message and persist via core.workflow.marker_cache.
+    # Non-blocking — any failure is swallowed.
+    try {
+        $sessionIdPtu = if ($null -ne $payload.session_id) { [string]$payload.session_id } else { '' }
+        $assistantMsg = if ($null -ne $payload.assistant_message) { [string]$payload.assistant_message } else { '' }
+        if ($sessionIdPtu -and $assistantMsg) {
+            $routingRe = [regex]'(?i)\[arka:routing\]\s*([A-Za-z_-]+)\s*->\s*([A-Za-z_-]+)'
+            $trivialRe = [regex]'(?i)\[arka:trivial\]\s*\S+'
+            $markerKind = ''
+            $markerDept = ''
+            $markerLead = ''
+            $routingMatch = $routingRe.Match($assistantMsg)
+            if ($routingMatch.Success) {
+                $markerKind = 'routing'
+                $markerDept = $routingMatch.Groups[1].Value
+                $markerLead = $routingMatch.Groups[2].Value
+            } elseif ($trivialRe.IsMatch($assistantMsg)) {
+                $markerKind = 'trivial'
+            }
+            if ($markerKind) {
+                $arkaosRootPtu = $env:ARKAOS_ROOT
+                if (-not $arkaosRootPtu) {
+                    $repoPathFile = Join-Path $env:USERPROFILE '.arkaos\.repo-path'
+                    if (Test-Path -LiteralPath $repoPathFile) {
+                        try {
+                            $arkaosRootPtu = (Get-Content -Raw -LiteralPath $repoPathFile -Encoding UTF8).Trim()
+                        } catch { }
+                    }
+                }
+                if (-not $arkaosRootPtu) {
+                    $arkaosRootPtu = Join-Path $env:USERPROFILE '.arkaos'
+                }
+                # Locate Python (venv-first, then system).
+                $pythonForMarker = $null
+                $venvPy = Join-Path $env:USERPROFILE '.arkaos\venv\Scripts\python.exe'
+                if (Test-Path -LiteralPath $venvPy) {
+                    $pythonForMarker = $venvPy
+                } else {
+                    foreach ($cmd in 'python3','python','py') {
+                        $resolved = Get-Command $cmd -ErrorAction SilentlyContinue
+                        if ($resolved) { $pythonForMarker = $resolved.Source; break }
+                    }
+                }
+                if ($pythonForMarker) {
+                    $pyCode = @"
+import os
+try:
+    from core.workflow.marker_cache import write_marker
+    write_marker(
+        os.environ.get('SESSION_ID_PTU', ''),
+        os.environ.get('MARKER_KIND', ''),
+        os.environ.get('MARKER_DEPT', ''),
+        os.environ.get('MARKER_LEAD', ''),
+    )
+except Exception:
+    pass
+"@
+                    $psi = New-Object System.Diagnostics.ProcessStartInfo
+                    $psi.FileName = $pythonForMarker
+                    $psi.Arguments = "-c `"$($pyCode -replace '"','\"' -replace "`r?`n",'; ')`""
+                    $psi.UseShellExecute = $false
+                    $psi.CreateNoWindow = $true
+                    $psi.RedirectStandardOutput = $true
+                    $psi.RedirectStandardError = $true
+                    [void]$psi.EnvironmentVariables.Add('SESSION_ID_PTU', $sessionIdPtu)
+                    [void]$psi.EnvironmentVariables.Add('MARKER_KIND', $markerKind)
+                    [void]$psi.EnvironmentVariables.Add('MARKER_DEPT', $markerDept)
+                    [void]$psi.EnvironmentVariables.Add('MARKER_LEAD', $markerLead)
+                    [void]$psi.EnvironmentVariables.Add('PYTHONPATH', $arkaosRootPtu)
+                    try {
+                        $proc = [System.Diagnostics.Process]::Start($psi)
+                        if (-not $proc.WaitForExit(1500)) { try { $proc.Kill() } catch { } }
+                    } catch { }
+                }
+            }
+        }
+    } catch { }
+
     # ─── Only process when there is actually an error ─────────────────
     $errorPattern = '(?i)(error:|fatal:|exception:|failed|ENOENT|EACCES|EPERM|panic:)'
     if ($exitCode -eq '0' -or [string]::IsNullOrEmpty($exitCode)) {

package/config/hooks/post-tool-use.sh

@@ -24,6 +24,53 @@ TOOL_NAME=$(echo "$input" | jq -r '.tool_name // ""' 2>/dev/null)
 TOOL_OUTPUT=$(echo "$input" | jq -r '.tool_output // ""' 2>/dev/null)
 EXIT_CODE=$(echo "$input" | jq -r '.exit_code // "0"' 2>/dev/null)
 CWD=$(echo "$input" | jq -r '.cwd // ""' 2>/dev/null)
+SESSION_ID_PTU=$(echo "$input" | jq -r '.session_id // ""' 2>/dev/null)
+ASSISTANT_MSG=$(echo "$input" | jq -r '.assistant_message // ""' 2>/dev/null)
+
+# ─── Flow marker cache write (v2 — turn-scoped ALLOW accelerator) ───────
+# Detect [arka:routing] or [arka:trivial] in the assistant message that
+# accompanied this tool call, and persist it so the PreToolUse enforcer
+# can short-circuit the transcript scan for the rest of the turn.
+# Never blocks the hook — all failures are swallowed.
+if [ -n "$SESSION_ID_PTU" ] && [ -n "$ASSISTANT_MSG" ] && command -v python3 &>/dev/null; then
+  _MARKER_KIND=""
+  _MARKER_DEPT=""
+  _MARKER_LEAD=""
+  if printf '%s' "$ASSISTANT_MSG" | grep -qiE '\[arka:routing\][[:space:]]*[A-Za-z_-]+[[:space:]]*->[[:space:]]*[A-Za-z_-]+'; then
+    _MARKER_KIND="routing"
+    _ROUTE_LINE=$(printf '%s' "$ASSISTANT_MSG" | grep -iEo '\[arka:routing\][[:space:]]*[A-Za-z_-]+[[:space:]]*->[[:space:]]*[A-Za-z_-]+' | head -1)
+    _MARKER_DEPT=$(printf '%s' "$_ROUTE_LINE" | sed -E 's/.*\[arka:routing\][[:space:]]*([A-Za-z_-]+).*/\1/')
+    _MARKER_LEAD=$(printf '%s' "$_ROUTE_LINE" | sed -E 's/.*->[[:space:]]*([A-Za-z_-]+).*/\1/')
+  elif printf '%s' "$ASSISTANT_MSG" | grep -qiE '\[arka:trivial\][[:space:]]*\S+'; then
+    _MARKER_KIND="trivial"
+  fi
+
+  if [ -n "$_MARKER_KIND" ]; then
+    _MARKER_ROOT="${ARKAOS_ROOT:-}"
+    if [ -z "$_MARKER_ROOT" ] && [ -f "$HOME/.arkaos/.repo-path" ]; then
+      _MARKER_ROOT=$(cat "$HOME/.arkaos/.repo-path" 2>/dev/null)
+    fi
+    [ -z "$_MARKER_ROOT" ] && _MARKER_ROOT="$HOME/.arkaos"
+    SESSION_ID_PTU="$SESSION_ID_PTU" \
+    MARKER_KIND="$_MARKER_KIND" \
+    MARKER_DEPT="$_MARKER_DEPT" \
+    MARKER_LEAD="$_MARKER_LEAD" \
+    PYTHONPATH="$_MARKER_ROOT" \
+    python3 -c "
+import os, sys
+try:
+    from core.workflow.marker_cache import write_marker
+    write_marker(
+        os.environ.get('SESSION_ID_PTU', ''),
+        os.environ.get('MARKER_KIND', ''),
+        os.environ.get('MARKER_DEPT', ''),
+        os.environ.get('MARKER_LEAD', ''),
+    )
+except Exception:
+    pass
+" 2>/dev/null || true
+  fi
+fi
 
 # Only process if there was an error
 if [ "$EXIT_CODE" = "0" ] || [ -z "$EXIT_CODE" ]; then

package/config/hooks/pre-tool-use.ps1

@@ -0,0 +1,190 @@
+# ============================================================================
+# ArkaOS v2 — PreToolUse Hook (Windows PowerShell)
+#
+# Parity with config/hooks/pre-tool-use.sh. Blocks Write/Edit/MultiEdit when
+# the mandatory 13-phase flow is required for the session AND the assistant
+# has not emitted a flow marker in its last 3 messages of the transcript.
+#
+# Delegates the decision to core/workflow/flow_enforcer.py.
+#
+# Exit 0 = allow (silent). Exit 2 = deny + structured hookSpecificOutput JSON.
+# ============================================================================
+
+$ErrorActionPreference = "SilentlyContinue"
+
+# --- Read stdin JSON ---
+$inputJson = [Console]::In.ReadToEnd()
+if ([string]::IsNullOrWhiteSpace($inputJson)) { exit 0 }
+
+try {
+    $inp = $inputJson | ConvertFrom-Json
+} catch {
+    exit 0
+}
+
+$toolName = [string]$inp.tool_name
+$transcriptPath = [string]$inp.transcript_path
+$sessionId = [string]$inp.session_id
+$cwd = [string]$inp.cwd
+
+# --- Resolve ARKAOS_ROOT ---
+if ([string]::IsNullOrWhiteSpace($env:ARKAOS_ROOT)) {
+    $repoPathFile = Join-Path $HOME ".arkaos/.repo-path"
+    if (Test-Path $repoPathFile) {
+        $env:ARKAOS_ROOT = (Get-Content $repoPathFile -Raw).Trim()
+    } elseif (Test-Path (Join-Path $HOME ".arkaos")) {
+        $env:ARKAOS_ROOT = (Join-Path $HOME ".arkaos")
+    } else {
+        $env:ARKAOS_ROOT = if ($env:ARKA_OS) { $env:ARKA_OS } else { Join-Path $HOME ".claude/skills/arkaos" }
+    }
+}
+
+$python = Get-Command python3 -ErrorAction SilentlyContinue
+if (-not $python) { $python = Get-Command python -ErrorAction SilentlyContinue }
+if (-not $python) { exit 0 }
+
+# --- KB-first gate (Task #6, runs before flow-marker gate) ---
+$queryHint = ""
+if ($inp.tool_input) {
+    if ($inp.tool_input.query) { $queryHint = [string]$inp.tool_input.query }
+    elseif ($inp.tool_input.prompt) { $queryHint = [string]$inp.tool_input.prompt }
+    elseif ($inp.tool_input.url) { $queryHint = [string]$inp.tool_input.url }
+    if ($queryHint.Length -gt 500) { $queryHint = $queryHint.Substring(0, 500) }
+}
+
+$researchGatePy = Join-Path $env:ARKAOS_ROOT "core/workflow/research_gate.py"
+if (Test-Path $researchGatePy) {
+    $env:TOOL_NAME = $toolName
+    $env:SESSION_ID = $sessionId
+    $env:QUERY_HINT = $queryHint
+
+    $kbScript = @'
+import json
+import os
+import sys
+
+sys.path.insert(0, os.environ["ARKAOS_ROOT"])
+try:
+    from core.workflow.research_gate import evaluate_research_gate, record_telemetry
+except Exception:
+    print(json.dumps({"allow": True, "nudge": False, "reason": "kb-gate-import-failed"}))
+    sys.exit(0)
+
+decision = evaluate_research_gate(
+    tool_name=os.environ.get("TOOL_NAME", ""),
+    session_id=os.environ.get("SESSION_ID", ""),
+    query=os.environ.get("QUERY_HINT", ""),
+)
+try:
+    record_telemetry(
+        session_id=os.environ.get("SESSION_ID", ""),
+        tool=os.environ.get("TOOL_NAME", ""),
+        decision=decision,
+    )
+except Exception:
+    pass
+print(json.dumps({
+    "allow": decision.allow,
+    "nudge": decision.nudge,
+    "reason": decision.reason,
+    "stderr_msg": decision.to_stderr_message(),
+}))
+'@
+
+    $kbDecisionJson = $kbScript | & $python.Source -
+    if (-not [string]::IsNullOrWhiteSpace($kbDecisionJson)) {
+        try {
+            $kbDecision = $kbDecisionJson | ConvertFrom-Json
+        } catch { $kbDecision = $null }
+
+        if ($kbDecision -and -not $kbDecision.allow) {
+            [Console]::Error.WriteLine($kbDecision.stderr_msg)
+            $denyOut = @{
+                hookSpecificOutput = @{
+                    hookEventName = "PreToolUse"
+                    permissionDecision = "deny"
+                    permissionDecisionReason = $kbDecision.stderr_msg
+                }
+            } | ConvertTo-Json -Compress -Depth 5
+            Write-Output $denyOut
+            exit 2
+        }
+
+        if ($kbDecision -and $kbDecision.nudge -and -not [string]::IsNullOrWhiteSpace($kbDecision.stderr_msg)) {
+            [Console]::Error.WriteLine($kbDecision.stderr_msg)
+        }
+    }
+}
+
+# --- Fast allow: not a flow-gated tool ---
+if ($toolName -ne "Write" -and $toolName -ne "Edit" -and $toolName -ne "MultiEdit") {
+    exit 0
+}
+
+$enforcerPy = Join-Path $env:ARKAOS_ROOT "core/workflow/flow_enforcer.py"
+if (-not (Test-Path $enforcerPy)) { exit 0 }
+
+# --- Delegate to Python enforcer ---
+$env:TOOL_NAME = $toolName
+$env:TRANSCRIPT_PATH = $transcriptPath
+$env:SESSION_ID = $sessionId
+$env:CWD = $cwd
+
+$pyScript = @'
+import json
+import os
+import sys
+
+sys.path.insert(0, os.environ["ARKAOS_ROOT"])
+try:
+    from core.workflow.flow_enforcer import evaluate, record_telemetry
+except Exception:
+    print(json.dumps({"allow": True, "reason": "enforcer-import-failed"}))
+    sys.exit(0)
+
+decision = evaluate(
+    tool_name=os.environ.get("TOOL_NAME", ""),
+    transcript_path=os.environ.get("TRANSCRIPT_PATH", ""),
+    session_id=os.environ.get("SESSION_ID", ""),
+    cwd=os.environ.get("CWD", ""),
+)
+try:
+    record_telemetry(
+        session_id=os.environ.get("SESSION_ID", ""),
+        tool=os.environ.get("TOOL_NAME", ""),
+        decision=decision,
+        cwd=os.environ.get("CWD", ""),
+    )
+except Exception:
+    pass
+print(json.dumps({
+    "allow": decision.allow,
+    "reason": decision.reason,
+    "stderr_msg": decision.to_stderr_message(),
+}))
+'@
+
+$decisionJson = $pyScript | & $python.Source -
+if ([string]::IsNullOrWhiteSpace($decisionJson)) { exit 0 }
+
+try {
+    $decision = $decisionJson | ConvertFrom-Json
+} catch {
+    exit 0
+}
+
+if ($decision.allow) { exit 0 }
+
+# --- Deny path ---
+[Console]::Error.WriteLine($decision.stderr_msg)
+
+$denyOut = @{
+    hookSpecificOutput = @{
+        hookEventName = "PreToolUse"
+        permissionDecision = "deny"
+        permissionDecisionReason = $decision.stderr_msg
+    }
+} | ConvertTo-Json -Compress -Depth 5
+
+Write-Output $denyOut
+exit 2