arkaos 2.20.1 → 2.22.0

package/VERSION

@@ -1 +1 @@
-2.20.1
+2.22.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**
@@ -95,7 +109,8 @@ violation (squad-routing, arka-supremacy, spec-driven, mandatory-qa).
 
 | Command | Description |
 |---------|-------------|
-| `/arka status` | System status (version, departments, agents, active projects) |
+| `/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 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 standup` | Daily standup (projects, priorities, blockers, updates) |
 | `/arka monitor` | System health monitoring |
 | `/arka onboard <path>` | Onboard an existing project into ArkaOS |

package/arka/skills/costs/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: arka-costs
+description: >
+  LLM cost visibility — aggregates `~/.arkaos/telemetry/llm-cost.jsonl` by
+  day/week/month/all, breaks down by provider/model/session, surfaces top
+  expensive sessions and cache hit rate. Visibility-only per ADR-011;
+  never imposes hard caps.
+allowed-tools: [Bash, Read]
+---
+
+# /arka costs — LLM cost visibility
+
+Aggregates runtime-agnostic LLM call telemetry written by
+`core/runtime/llm_cost_telemetry.record_cost`. Per ADR-011, token
+budgets are **informational, not restrictive** — this command only
+surfaces usage and emits soft advisories. It never blocks a call.
+
+## Usage
+
+| Command | What it shows |
+| --- | --- |
+| `/arka costs` | Today (UTC midnight → now) |
+| `/arka costs today` | Same as above |
+| `/arka costs week` | Rolling last 7 days |
+| `/arka costs month` | Rolling last 30 days |
+| `/arka costs all` | Entire history in the JSONL |
+| `/arka costs sessions` | Top 10 most expensive sessions (all time) |
+
+## Output
+
+- Total cost (USD, `n/a` when all entries are unpriced models)
+- Total tokens in / out, plus cached tokens
+- Cache hit rate (`cached / tokens_in`)
+- Breakdown by provider
+- Breakdown by model (`<unknown>` bucket for calls with no model)
+- Top 10 sessions sorted by cost
+- Advisories — a soft line per session that crossed the
+  `advisory_threshold_usd` (default $5 per session)
+
+## Implementation
+
+This skill shells out to the Python CLI:
+
+```bash
+python -m core.runtime.llm_cost_telemetry_cli <period>
+```
+
+Source:
+- `core/runtime/llm_cost_telemetry.py` — `summarise`, `list_expensive_sessions`
+- `core/runtime/llm_cost_telemetry_cli.py` — markdown renderer
+
+## Data source
+
+`~/.arkaos/telemetry/llm-cost.jsonl` (override with `ARKA_LLM_COST_PATH`).
+One JSONL line per LLM call, written by every provider adapter.
+Malformed lines are skipped and counted, never raised.
+
+## Non-negotiables
+
+1. Read-only. This skill never edits state.
+2. No hard budget caps — advisories are strings, not errors.
+3. No external dependencies; stdlib only.

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/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

@@ -27,11 +27,6 @@ $transcriptPath = [string]$inp.transcript_path
 $sessionId = [string]$inp.session_id
 $cwd = [string]$inp.cwd
 
-# --- Fast allow: not a gated tool ---
-if ($toolName -ne "Write" -and $toolName -ne "Edit" -and $toolName -ne "MultiEdit") {
-    exit 0
-}
-
 # --- Resolve ARKAOS_ROOT ---
 if ([string]::IsNullOrWhiteSpace($env:ARKAOS_ROOT)) {
     $repoPathFile = Join-Path $HOME ".arkaos/.repo-path"
@@ -44,13 +39,91 @@ if ([string]::IsNullOrWhiteSpace($env:ARKAOS_ROOT)) {
     }
 }
 
-$enforcerPy = Join-Path $env:ARKAOS_ROOT "core/workflow/flow_enforcer.py"
-if (-not (Test-Path $enforcerPy)) { exit 0 }
-
 $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

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

@@ -31,12 +31,6 @@ if command -v jq &>/dev/null; then
   CWD=$(echo "$input" | jq -r '.cwd // ""' 2>/dev/null)
 fi
 
-# ─── Fast allow: not a gated tool
-case "$TOOL_NAME" in
-  Write|Edit|MultiEdit) ;;
-  *) exit 0 ;;
-esac
-
 # ─── Resolve ARKAOS_ROOT (same rules as user-prompt-submit.sh) ──────────
 if [ -z "${ARKAOS_ROOT:-}" ]; then
   if [ -f "$HOME/.arkaos/.repo-path" ]; then
@@ -48,10 +42,90 @@ if [ -z "${ARKAOS_ROOT:-}" ]; then
   fi
 fi
 
-# ─── Degrade gracefully if Python or module is unavailable ──────────────
+# ─── Degrade gracefully if Python is unavailable ────────────────────────
 if ! command -v python3 &>/dev/null; then
   exit 0
 fi
+
+# ─── KB-first gate (Task #6, independent from flow_enforcer) ────────────
+# Runs BEFORE the flow-marker gate so that external research tools are
+# always KB-checked regardless of whether the tool is Write/Edit/MultiEdit.
+# Extract the user query (if present) to feed the nudge generator.
+QUERY_HINT=""
+if command -v jq &>/dev/null; then
+  QUERY_HINT=$(echo "$input" | jq -r '.tool_input.query // .tool_input.prompt // .tool_input.url // ""' 2>/dev/null | head -c 500)
+fi
+
+if [ -f "$ARKAOS_ROOT/core/workflow/research_gate.py" ]; then
+  KB_DECISION_JSON=$(TOOL_NAME="$TOOL_NAME" \
+                     SESSION_ID="$SESSION_ID" \
+                     QUERY_HINT="$QUERY_HINT" \
+                     ARKAOS_ROOT="$ARKAOS_ROOT" \
+                     python3 - <<'PY' 2>/dev/null
+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(),
+}))
+PY
+)
+
+  if [ -n "$KB_DECISION_JSON" ]; then
+    KB_ALLOW=$(echo "$KB_DECISION_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('allow', True))" 2>/dev/null)
+    KB_NUDGE=$(echo "$KB_DECISION_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('nudge', False))" 2>/dev/null)
+    KB_STDERR=$(echo "$KB_DECISION_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('stderr_msg',''))" 2>/dev/null)
+
+    if [ "$KB_ALLOW" != "True" ] && [ "$KB_ALLOW" != "true" ]; then
+      echo "$KB_STDERR" >&2
+      STDERR_MSG="$KB_STDERR" python3 - <<'PY'
+import json, os
+print(json.dumps({"hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": os.environ.get("STDERR_MSG", ""),
+}}))
+PY
+      exit 2
+    fi
+
+    # Nudge path: emit advisory to stderr, continue to flow-marker gate.
+    if [ "$KB_NUDGE" = "True" ] || [ "$KB_NUDGE" = "true" ]; then
+      [ -n "$KB_STDERR" ] && echo "$KB_STDERR" >&2
+    fi
+  fi
+fi
+
+# ─── Fast allow: not a flow-gated tool (Write/Edit/MultiEdit) ───────────
+case "$TOOL_NAME" in
+  Write|Edit|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
 if [ ! -f "$ARKAOS_ROOT/core/workflow/flow_enforcer.py" ]; then
   exit 0
 fi

package/config/hooks/stop.ps1

@@ -104,6 +104,85 @@ except Exception:
 
 $pyScript | & $python.Source - | Out-Null
 
+# ─── Auto-documentor enqueue (fire-and-forget) ─────────────────────────
+# Queues a background job when classifier flagged flow, QG approved, and
+# external research happened. Never blocks the Stop hook.
+$env:SESSION_ID_VAL = $sessionId
+$env:TRANSCRIPT_PATH_VAL = $transcriptPath
+$env:CWD_VAL = $cwd
+$env:ARKAOS_ROOT = $env:ARKAOS_ROOT
+
+$autoDocScript = @'
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, os.environ.get("ARKAOS_ROOT", ""))
+try:
+    from core.jobs.auto_doc_worker import enqueue_job
+    from core.workflow.flow_enforcer import _load_last_assistant_messages
+except Exception:
+    sys.exit(0)
+
+session_id = os.environ.get("SESSION_ID_VAL", "")
+transcript_path = os.environ.get("TRANSCRIPT_PATH_VAL", "")
+if not session_id or not transcript_path:
+    sys.exit(0)
+
+last = ""
+try:
+    msgs = _load_last_assistant_messages(transcript_path, n=1)
+    last = msgs[-1] if msgs else ""
+except Exception:
+    last = ""
+
+qg_approved = bool(re.search(r"\[arka:qg:approved\]", last, re.IGNORECASE))
+if not qg_approved:
+    qg_log = Path.home() / ".arkaos" / "telemetry" / "qg.jsonl"
+    if qg_log.exists():
+        try:
+            for line in reversed(qg_log.read_text(encoding="utf-8").splitlines()):
+                if not line.strip():
+                    continue
+                try:
+                    rec = json.loads(line)
+                except Exception:
+                    continue
+                if rec.get("session_id") == session_id:
+                    qg_approved = rec.get("verdict", "").upper() == "APPROVED"
+                    break
+        except Exception:
+            pass
+if not qg_approved:
+    sys.exit(0)
+
+external_markers = (
+    "WebFetch", "WebSearch", "mcp__context7", "mcp__firecrawl",
+    "http://", "https://",
+)
+has_external = False
+try:
+    data = Path(transcript_path).read_text(encoding="utf-8", errors="replace")
+    has_external = any(marker in data for marker in external_markers)
+except Exception:
+    has_external = False
+if not has_external:
+    sys.exit(0)
+
+try:
+    enqueue_job(session_id, transcript_path, "APPROVED")
+except Exception:
+    pass
+'@
+
+try {
+    $autoDocScript | & $python.Source - | Out-Null
+} catch {
+    # Swallow — enqueue is fire-and-forget.
+}
+
 # Belt-and-braces marker cleanup (safe even if the Python block crashed).
 if ($sessionId -match '^[A-Za-z0-9._-]{1,128}$') {
     Remove-Item -LiteralPath $wfMarker -ErrorAction SilentlyContinue

package/config/hooks/stop.sh

@@ -115,6 +115,94 @@ except Exception:
     pass
 PY
 
+# ─── Auto-documentor enqueue (fire-and-forget) ──────────────────────────
+# Queues a background job when:
+#   (a) the session was flagged flow-required (classifier match above),
+#   (b) Quality Gate approved — last assistant message carries
+#       `[arka:qg:approved]`, OR the most recent entry for this session
+#       in ~/.arkaos/telemetry/qg.jsonl has verdict APPROVED, AND
+#   (c) at least one external research tool was invoked this session
+#       (URL, WebFetch/WebSearch, Context7, Firecrawl in the transcript).
+# The actual documentation runs async via `core/jobs/auto_doc_worker.py`;
+# this block never blocks Stop — 2s Python budget, errors swallowed.
+if command -v timeout &>/dev/null; then
+  _ARKA_AUTO_DOC_RUNNER=(timeout 2s python3 -)
+elif command -v gtimeout &>/dev/null; then
+  _ARKA_AUTO_DOC_RUNNER=(gtimeout 2s python3 -)
+else
+  _ARKA_AUTO_DOC_RUNNER=(python3 -)
+fi
+
+SESSION_ID_VAL="$SESSION_ID" \
+TRANSCRIPT_PATH_VAL="$TRANSCRIPT_PATH" \
+CWD_VAL="$CWD" \
+ARKAOS_ROOT_VAL="$ARKAOS_ROOT" \
+"${_ARKA_AUTO_DOC_RUNNER[@]}" <<'PY' 2>/dev/null || true
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+sys.path.insert(0, os.environ["ARKAOS_ROOT_VAL"])
+try:
+    from core.jobs.auto_doc_worker import enqueue_job
+    from core.workflow.flow_enforcer import _load_last_assistant_messages
+except Exception:
+    sys.exit(0)
+
+session_id = os.environ.get("SESSION_ID_VAL", "")
+transcript_path = os.environ.get("TRANSCRIPT_PATH_VAL", "")
+if not session_id or not transcript_path:
+    sys.exit(0)
+
+last = ""
+try:
+    msgs = _load_last_assistant_messages(transcript_path, n=1)
+    last = msgs[-1] if msgs else ""
+except Exception:
+    last = ""
+
+qg_approved = bool(re.search(r"\[arka:qg:approved\]", last, re.IGNORECASE))
+if not qg_approved:
+    qg_log = Path.home() / ".arkaos" / "telemetry" / "qg.jsonl"
+    if qg_log.exists():
+        try:
+            for line in reversed(qg_log.read_text(encoding="utf-8").splitlines()):
+                if not line.strip():
+                    continue
+                try:
+                    rec = json.loads(line)
+                except Exception:
+                    continue
+                if rec.get("session_id") == session_id:
+                    qg_approved = rec.get("verdict", "").upper() == "APPROVED"
+                    break
+        except Exception:
+            pass
+if not qg_approved:
+    sys.exit(0)
+
+# Heuristic check that some external research happened this session.
+external_markers = (
+    "WebFetch", "WebSearch", "mcp__context7", "mcp__firecrawl",
+    "http://", "https://",
+)
+has_external = False
+try:
+    data = Path(transcript_path).read_text(encoding="utf-8", errors="replace")
+    has_external = any(marker in data for marker in external_markers)
+except Exception:
+    has_external = False
+if not has_external:
+    sys.exit(0)
+
+try:
+    enqueue_job(session_id, transcript_path, "APPROVED")
+except Exception:
+    pass
+PY
+
 # Belt-and-braces: remove the marker at shell level in case the Python
 # block above crashed before reaching clear_flow_required(). Session_id
 # is already validated by the Python helper; this shell remove is scoped