arkaos 5.11.0 → 5.12.0

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v5.10.0 — 89 agents, 17 departments, 340 skills, 306 commands, 20 ADRs.
+> v5.12.0 — 89 agents, 17 departments, 340 skills, 306 commands, 20 ADRs.
 > One file, everything you need to start. Generated by `scripts/guide_gen.py` — never hand-edited.
 
 ## What it is

package/VERSION

@@ -1 +1 @@
-5.11.0
+5.12.0

package/config/hooks/_lib/arka_python.ps1

@@ -8,9 +8,37 @@
 # Resolution order:
 #   1. $env:ARKAOS_PYTHON (explicit override), if it exists.
 #   2. The ArkaOS venv — Scripts\python.exe (Windows) then bin/python.
-#   3. Any python3/python/py on PATH that can `import yaml`.
+#   3. Any python3/python/py on PATH that can `import yaml`, skipping the
+#      Microsoft Store App Execution Aliases (see Test-StoreAlias).
 #   4. Bare `python` as a last resort.
 
+function Test-StoreAlias {
+    <#
+    .SYNOPSIS
+        True when a resolved command is a Microsoft Store App Execution Alias.
+
+    .DESCRIPTION
+        %LOCALAPPDATA%\Microsoft\WindowsApps holds zero-length reparse points
+        that Get-Command resolves like any other executable. On a default
+        Windows install `python3.exe` there points at the Python install
+        manager, and *running* it — which the probe below does, with
+        `-c "import yaml"` — makes the manager download and install a full
+        CPython into the current working directory.
+
+        For a hook that is a catastrophic side effect: the cwd is the user's
+        project, so a background hook silently drops a ~3700-file Python/
+        tree and a python_install_<timestamp>.log into their repo. Observed
+        on Windows 10, Python install manager 26.3.
+
+        Probing an alias can never help anyway: the stub carries no site
+        packages, so the `import yaml` check it exists to answer would fail
+        after paying the install.
+    #>
+    param([string]$Path)
+    if ([string]::IsNullOrWhiteSpace($Path)) { return $false }
+    return $Path -match '\\Microsoft\\WindowsApps\\'
+}
+
 function Resolve-ArkaPython {
     if ($env:ARKAOS_PYTHON -and (Test-Path -LiteralPath $env:ARKAOS_PYTHON)) {
         return $env:ARKAOS_PYTHON
@@ -29,9 +57,11 @@ function Resolve-ArkaPython {
         }
     }
 
-    foreach ($name in @("python3", "python", "py")) {
+    # "python" before "python3": on Windows a real interpreter answers to
+    # the former, while the latter is usually only the Store alias.
+    foreach ($name in @("python", "py", "python3")) {
         $cmd = Get-Command $name -ErrorAction SilentlyContinue
-        if ($cmd) {
+        if ($cmd -and -not (Test-StoreAlias $cmd.Source)) {
             & $cmd.Source -c "import yaml" 2>$null
             if ($LASTEXITCODE -eq 0) { return $cmd.Source }
         }

package/config/hooks/_lib/arka_python.sh

@@ -28,24 +28,54 @@ arka_resolve_python() {
     return 0
   fi
 
+  # Scripts/python.exe is the Windows venv layout. Without it, a Git-Bash
+  # hook on Windows never matches the venv and always falls through to the
+  # PATH probe below -- which is where the Store alias lives.
   for cand in \
       "$HOME/.arkaos/venv/bin/python" \
       "$HOME/.arkaos/venv/bin/python3" \
+      "$HOME/.arkaos/venv/Scripts/python.exe" \
       "$HOME/.arkaos/.venv/bin/python" \
-      "$HOME/.arkaos/.venv/bin/python3"; do
+      "$HOME/.arkaos/.venv/bin/python3" \
+      "$HOME/.arkaos/.venv/Scripts/python.exe"; do
     if [ -x "$cand" ]; then
       printf '%s\n' "$cand"
       return 0
     fi
   done
 
-  for cand in python3 /opt/homebrew/bin/python3 /usr/local/bin/python3 /usr/bin/python3; do
-    if command -v "$cand" >/dev/null 2>&1 && "$cand" -c "import yaml" >/dev/null 2>&1; then
+  # Never probe a Microsoft Store App Execution Alias: under Git Bash on
+  # Windows `command -v python3` resolves to .../Microsoft/WindowsApps/
+  # python3, which is the Python install manager, not an interpreter. The
+  # `import yaml` check RUNS each candidate, and running that one installs
+  # a CPython into the current working directory -- the user's project, for
+  # a hook. It could not have succeeded anyway: an alias stub carries no
+  # site packages. On POSIX nothing ever matches that path: pure no-op.
+  #
+  # `python` is LAST on purpose. On Windows it is the only real interpreter
+  # left once the alias is filtered out; on POSIX one of the entries before
+  # it always matches first, so an old box where `python` is Python 2 keeps
+  # resolving exactly as it does today.
+  for cand in python3 /opt/homebrew/bin/python3 /usr/local/bin/python3 /usr/bin/python3 python; do
+    case "$(command -v "$cand" 2>/dev/null)" in
+      "") continue ;;
+      *[Ww]indows[Aa]pps*) continue ;;
+    esac
+    if "$cand" -c "import yaml" >/dev/null 2>&1; then
       printf '%s\n' "$cand"
       return 0
     fi
   done
 
+  # Last resort. The documented contract is `python3` + rc 1, kept as-is,
+  # except where that name is the Store alias: handing an alias back to a
+  # caller that will `exec` it is the very trap this function now avoids.
+  case "$(command -v python3 2>/dev/null)" in
+    *[Ww]indows[Aa]pps*)
+      printf '%s\n' "python"
+      return 1
+      ;;
+  esac
   printf '%s\n' "python3"
   return 1
 }

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

@@ -40,6 +40,13 @@ arka_wf_safe_session_id() {
 # missed prompts were short continuations ("continua", "força") or
 # ship-tier verbs ("ship", "publish", "merge", "release", "deploy")
 # that prolong existing flow-required activity.
+# Keep in sync with _WF_QUESTION_LEAD_PATTERN in core/hooks/
+# user_prompt_submit.py. Interrogative-led prompts ending in "?" are
+# information questions, not creation intent, even when they contain an
+# action verb ("o que e que este projeto faz?"). Polite requests ("podes
+# implementar X?") keep matching: their lead word is not interrogative.
+ARKA_WF_QUESTION_LEAD='^[[:space:]]*(o[[:space:]]+que|porqu[eê]|por[[:space:]]+que|para[[:space:]]+que|qual|quais|quando|onde|quem|como|what|why|which|who|whose|when|where|how|does)\b'
+
 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]?|continuar?|continua[mr]?|forçar?|força[mr]?|colocar?|coloca[mr]?|p[oô]r|melhorar?|melhora[mr]?|terminar?|termina[mr]?|acabar?|acaba[mr]?|publicar?|publica[mr]?|lançar?|lança[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|continue[sd]?|continuing|ship(s|ped|ping)?|merge[sd]?|merging|publish(es|ed|ing)?|release[sd]?|releasing|deploy(s|ed|ing)?|finish(es|ed|ing)?|improve[sd]?|improving)'
 
 # Classify: returns "true" if the prompt looks like a creation/
@@ -56,6 +63,19 @@ arka_wf_classify() {
     return 0
   fi
 
+  # Question guard: interrogative lead + trailing "?" = information
+  # question, never creation intent (X5 false positive).
+  local trimmed
+  trimmed=$(printf '%s' "$text" | sed 's/[[:space:]]*$//')
+  case "$trimmed" in
+    *\?)
+      if echo "$text" | grep -qiE "$ARKA_WF_QUESTION_LEAD"; then
+        echo "false"
+        return 0
+      fi
+      ;;
+  esac
+
   if echo "$text" | grep -qiE "\b${ARKA_WF_VERB_PATTERN}\b"; then
     echo "true"
   else

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

@@ -203,9 +203,16 @@ if ($shouldProcessGotchas -and $null -ne $payload) {
                 if (Test-Path -LiteralPath $venvPy) {
                     $pythonForMarker = $venvPy
                 } else {
-                    foreach ($cmd in 'python3','python','py') {
+                    # Never accept %LOCALAPPDATA%\Microsoft\WindowsApps: the
+                    # python3.exe there is the Store install-manager alias,
+                    # and running it downloads a full CPython into the cwd —
+                    # which for a hook is the user's own project directory.
+                    # Same reason "python" is tried before "python3" here.
+                    foreach ($cmd in 'python','py','python3') {
                         $resolved = Get-Command $cmd -ErrorAction SilentlyContinue
-                        if ($resolved) { $pythonForMarker = $resolved.Source; break }
+                        if ($resolved -and $resolved.Source -notmatch '\\Microsoft\\WindowsApps\\') {
+                            $pythonForMarker = $resolved.Source; break
+                        }
                     }
                 }
                 if ($pythonForMarker) {

package/config/hooks/session-start.ps1

@@ -1,121 +1,80 @@
 # ============================================================================
-# ArkaOS — SessionStart Hook (Windows / PowerShell 5.1+)
+# ArkaOS - SessionStart Hook (Windows / PowerShell 5.1+)
 #
-# Port of config/hooks/session-start.sh. Must remain behaviourally identical:
-# - Same profile lookup, time-based greeting, version-drift detection.
-# - Same JSON output contract: {"systemMessage": "<...>"} on stdout.
+# Thin wrapper - mirror of config/hooks/session-start.sh. ONE python process
+# (core.hooks.session_start) builds the whole payload: the visible banner in
+# "systemMessage" AND the operating contracts in
+# hookSpecificOutput.additionalContext. This file only resolves the
+# interpreter and delegates; with no usable interpreter it emits a static
+# banner and exits 0 (fail-open, dependency-free).
+#
+# WHY A WRAPPER AND NOT A PORT
+# The previous version reimplemented the banner natively in PowerShell. It
+# was a faithful port of the *older* .sh, from the era when the .sh built the
+# banner in bash. When the .sh became a thin wrapper delegating to Python,
+# this file did not follow - so on Windows the four contract blocks
+# (EVIDENCE-FLOW, META-TAG, AUTHORITY, MODEL-FABRIC) were computed by nobody
+# and never reached the model, while the Linux side got them every session.
+# Reimplementing the blocks here would duplicate the producer and recreate
+# the same drift one release later. One producer, two thin wrappers.
 #
 # Minimum PowerShell: 5.1 (shipped with every Windows 10+). No pwsh 7 prereq.
-# Box-drawing characters are built from [char] codes so this file stays pure
-# ASCII and avoids source-encoding pitfalls with PS 5.1 default ANSI reads.
+# This file stays pure ASCII; every non-ASCII byte in the output comes from
+# Python's UTF-8 stdout, which is why the encoding setup below is required.
 # ============================================================================
 
-$ErrorActionPreference = 'Stop'
-# Force UTF-8 on stdout so ConvertTo-Json does not emit mojibake box chars.
-[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+$ErrorActionPreference = 'SilentlyContinue'
 
-$arkaosHome = Join-Path $env:USERPROFILE '.arkaos'
+# Captured BEFORE any location change - inside a compound command the CWD
+# would resolve after the push (QG blocker F1-A3: cross-project leak).
+$env:ARKA_HOOK_CWD = (Get-Location).Path
 
-# ─── Profile ───────────────────────────────────────────────────────────
-$name    = 'founder'
-$company = 'WizardingCode'
-$version = '2.x'
+# Force UTF-8 on both sides of the pipe. Python emits UTF-8; without this
+# PS 5.1 decodes it as the ANSI codepage (cp1252 on pt-PT/pt-BR machines)
+# and the banner arrives as mojibake - the failure mode tracked in #395/#396.
+# PYTHONIOENCODING covers the producer, OutputEncoding the consumer.
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+$env:PYTHONIOENCODING = 'utf-8'
 
-$profilePath = Join-Path $arkaosHome 'profile.json'
-if (Test-Path -LiteralPath $profilePath) {
-    try {
-        # $profile is an automatic variable in PowerShell — use $arkaosProfile.
-        $arkaosProfile = Get-Content -Raw -LiteralPath $profilePath -Encoding UTF8 | ConvertFrom-Json
-        if ($arkaosProfile.name)      { $name    = [string]$arkaosProfile.name }
-        elseif ($arkaosProfile.role)  { $name    = [string]$arkaosProfile.role }
-        if ($arkaosProfile.company)   { $company = [string]$arkaosProfile.company }
-    } catch {
-        # Corrupt profile — keep defaults and continue.
-    }
-}
+# --- Shared Python resolver (sets $env:ARKA_PY, provides Resolve-ArkaRoot) ---
+$arkaLib = Join-Path $PSScriptRoot '_lib\arka_python.ps1'
+if (Test-Path -LiteralPath $arkaLib) { . $arkaLib }
 
-$repoPathFile = Join-Path $arkaosHome '.repo-path'
-if (Test-Path -LiteralPath $repoPathFile) {
-    try {
+# --- Resolve the repo root ---
+# .repo-path can point at a purged npx cache; Resolve-ArkaRoot falls through
+# to the ~/.arkaos/lib snapshot instead of returning a dead root.
+$repo = ''
+if (Get-Command Resolve-ArkaRoot -ErrorAction SilentlyContinue) {
+    $repo = Resolve-ArkaRoot
+} else {
+    $repoPathFile = Join-Path $HOME '.arkaos/.repo-path'
+    if (Test-Path -LiteralPath $repoPathFile) {
         $repo = (Get-Content -Raw -LiteralPath $repoPathFile -Encoding UTF8).Trim()
-        if ($repo) {
-            $versionFile = Join-Path $repo 'VERSION'
-            if (Test-Path -LiteralPath $versionFile) {
-                $version = (Get-Content -Raw -LiteralPath $versionFile -Encoding UTF8).Trim()
-            }
-        }
-    } catch { }
-}
-# .repo-path may point at a purged npx cache — the installer's snapshot
-# keeps the drift banner alive ('2.x' is the untouched default above).
-if ($version -eq '2.x') {
-    $libVersionFile = Join-Path $arkaosHome 'lib\VERSION'
-    if (Test-Path -LiteralPath $libVersionFile) {
-        try {
-            $version = (Get-Content -Raw -LiteralPath $libVersionFile -Encoding UTF8).Trim()
-        } catch { }
     }
 }
 
-# ─── Time greeting ─────────────────────────────────────────────────────
-$hour = [int](Get-Date -Format 'HH')
-if     ($hour -ge 5  -and $hour -lt 12) { $greeting = 'Bom dia' }
-elseif ($hour -ge 12 -and $hour -lt 19) { $greeting = 'Boa tarde' }
-else                                     { $greeting = 'Boa noite' }
+# The MODULE file is the guard, not just core/: an older installed snapshot
+# without it would delegate into "No module named ..." (exit 1, empty output
+# - a broken SessionStart instead of a degraded banner).
+$moduleFile = if ($repo) { Join-Path $repo 'core/hooks/session_start.py' } else { '' }
 
-# ─── Version drift ─────────────────────────────────────────────────────
-$drift = ''
-$syncStatePath = Join-Path $arkaosHome 'sync-state.json'
-if (Test-Path -LiteralPath $syncStatePath) {
+if ($repo -and $moduleFile -and (Test-Path -LiteralPath $moduleFile) -and $env:ARKA_PY) {
+    $env:PYTHONPATH = $repo
+    Push-Location -LiteralPath $repo
     try {
-        $syncState = Get-Content -Raw -LiteralPath $syncStatePath -Encoding UTF8 | ConvertFrom-Json
-        $synced = if ($null -ne $syncState.version) { [string]$syncState.version } else { 'none' }
-        if ($synced -ne $version) {
-            $drift = "`n[arka:update-available] Core v$version != synced v$synced. Run /arka update."
-        }
+        & $env:ARKA_PY -m core.hooks.session_start
+        if ($LASTEXITCODE -eq 0) { Pop-Location; exit 0 }
     } catch {
-        $drift = "`n[arka:update-available] Sync state unreadable. Run /arka update."
+        # fall through to the degraded banner
     }
-} else {
-    $drift = "`n[arka:update-available] Never synced. Run /arka update."
-}
-
-# ─── Build ASCII header from char codes ───────────────────────────────
-$tl  = [char]0x2554  # ╔
-$tr  = [char]0x2557  # ╗
-$bl  = [char]0x255A  # ╚
-$br  = [char]0x255D  # ╝
-$h   = [char]0x2550  # ═
-$v   = [char]0x2551  # ║
-$bar = [string]($h.ToString() * 46)
-
-$topLine    = "$tl$bar$tr"
-$bottomLine = "$bl$bar$br"
-$empty      = "$v" + (' ' * 46) + "$v"
-function Pad-Line([string]$text) {
-    $innerWidth = 46
-    $padLeft  = [int](($innerWidth - $text.Length) / 2)
-    $padRight = $innerWidth - $text.Length - $padLeft
-    return "$v" + (' ' * $padLeft) + $text + (' ' * $padRight) + "$v"
+    Pop-Location
 }
 
-$lines = @(
-    $topLine
-    $empty
-    (Pad-Line 'A R K A   O S')
-    $empty
-    (Pad-Line 'The Operating System for AI Teams')
-    (Pad-Line 'by WizardingCode')
-    $empty
-    $bottomLine
-    ''
-    "$greeting, $name ($company)"
-    # Counts intentionally omitted (prompt-surface P0 2026-07-08): hand-typed
-    # numbers drift from docs_stats.py truth and change no model behavior.
-    "ArkaOS v$version$drift"
-)
-
-$msg = "`n" + ($lines -join "`n")
-
-# ─── Output as systemMessage JSON (single line, same contract as .sh) ──
-[pscustomobject]@{ systemMessage = $msg } | ConvertTo-Json -Compress
+# --- Degraded fallback: static banner, valid JSON, exit 0 ------------------
+# Same contract as the .sh fallback. Built from [char] codes so this source
+# file needs no particular encoding to produce correct output.
+$tri = [char]0x25B2
+$oAcute = [char]0x00F3
+$banner = "`n  $tri  A R K A   O S`n     The Operating System for AI Agent Teams`n`n  Ol$oAcute, founder`n  degraded: no usable interpreter - run npx arkaos doctor"
+[pscustomobject]@{ systemMessage = $banner } | ConvertTo-Json -Compress
+exit 0

package/config/hooks/stop.ps1

@@ -24,7 +24,17 @@ $cwd = [string]$inp.cwd
 
 if ($stopHookActive -eq "true") { exit 0 }
 
-$wfMarker = Join-Path "/tmp/arkaos-wf-required" $sessionId
+# Marker dir must match the Python writer (_wf_mark_required /
+# core.shared.temp_paths.arkaos_temp_dir): %TEMP%\arkaos-wf-required on
+# Windows, with the same ARKA_WF_REQUIRED_DIR override the writer honors.
+# The previous hardcoded "/tmp/arkaos-wf-required" resolves to a path that
+# exists on no stock Windows machine, so this gate exited 0 on every real
+# session and the whole compliance chain below never ran.
+$wfDir = $env:ARKA_WF_REQUIRED_DIR
+if ([string]::IsNullOrWhiteSpace($wfDir)) {
+    $wfDir = Join-Path ([System.IO.Path]::GetTempPath()) 'arkaos-wf-required'
+}
+$wfMarker = Join-Path $wfDir $sessionId
 if ([string]::IsNullOrWhiteSpace($sessionId) -or -not (Test-Path $wfMarker)) {
     exit 0
 }
@@ -193,6 +203,134 @@ try {
     # Swallow — enqueue is fire-and-forget.
 }
 
+# ─── Governance parity (skill capture + warn-only detectors) ───────────
+# config/hooks/stop.sh delegates the whole event to `python -m
+# core.hooks.stop`, which runs seventeen core modules. This port
+# reimplements the event inline and reached only two of them, so four
+# detectors that exist, are tested and are wired on POSIX never ran on
+# Windows at all — most visibly skill_proposer, whose constitution rule
+# (mandatory-skill-evaluation) mandates a capability sweep after every
+# completed task.
+#
+# Scope is deliberately the NON-ENFORCEMENT subset: these four write
+# proposals and diagnostic state only. The gating checks
+# (closing_marker_check, meta_tag_check, kb_cite_check, dna_fidelity)
+# are left out of this change — they feed enforcement surfaces and
+# deserve their own baseline on Windows before being switched on.
+$governanceScript = @'
+import os
+import sys
+from pathlib import Path
+
+sys.path.insert(0, os.environ.get("ARKAOS_ROOT", ""))
+try:
+    from core.workflow.flow_enforcer import _load_last_assistant_messages
+except Exception:
+    sys.exit(0)
+
+transcript_path = os.environ.get("TRANSCRIPT_PATH_VAL", "")
+session_id = os.environ.get("SESSION_ID_VAL", "")
+if not transcript_path:
+    sys.exit(0)
+
+try:
+    msgs = _load_last_assistant_messages(transcript_path, n=1)
+    last = msgs[-1] if msgs else ""
+except Exception:
+    last = ""
+
+raw = None
+try:
+    raw = Path(transcript_path).read_text(encoding="utf-8", errors="replace")
+except Exception:
+    raw = None
+
+
+def _write_tmp_state(prefix, sid, payload):
+    """Mirror of core.hooks.stop._write_tmp_state (best-effort)."""
+    if not sid:
+        return
+    try:
+        import json
+
+        from core.shared.temp_paths import arkaos_temp_dir
+
+        target = arkaos_temp_dir(prefix)
+        target.mkdir(parents=True, exist_ok=True)
+        (target / f"{sid}.json").write_text(
+            json.dumps(payload), encoding="utf-8"
+        )
+    except Exception:
+        pass
+
+
+safe_sid = None
+try:
+    from core.shared.safe_session_id import safe_session_id
+
+    safe_sid = safe_session_id(session_id)
+except Exception:
+    safe_sid = None
+
+# 1. Capability capture — the constitution rule this port was missing.
+try:
+    from core.governance.skill_proposer import evaluate as _eval_skill
+
+    _eval_skill(last)
+except Exception:
+    pass
+
+# 2. Sycophancy (warn-only telemetry).
+try:
+    from core.governance.sycophancy_detector import detect_sycophancy
+
+    sv = detect_sycophancy(last)
+    if sv.is_sycophantic and safe_sid:
+        _write_tmp_state("arkaos-sycophancy", safe_sid, {
+            "is_sycophantic": sv.is_sycophantic,
+            "signals": sv.signals,
+            "confidence": sv.confidence,
+        })
+except Exception:
+    pass
+
+# 3. Phantom actions — narrated effects with no tool call in the turn.
+try:
+    from core.governance.phantom_action_check import check_phantom_actions
+
+    pr = check_phantom_actions(last, raw)
+    if safe_sid:
+        _write_tmp_state("arkaos-phantom", safe_sid, {
+            "passed": pr.passed,
+            "reason": pr.reason,
+            "claims": pr.claims,
+            "suggestion": pr.suggestion,
+        })
+except Exception:
+    pass
+
+# 4. Tool loops.
+try:
+    from core.governance.tool_loop_check import check_tool_loops
+
+    lv = check_tool_loops(raw)
+    if lv.detected and safe_sid:
+        _write_tmp_state("arkaos-tool-loop", safe_sid, {
+            "tool": lv.tool,
+            "repeats": lv.repeats,
+            "pattern": lv.pattern,
+            "total_tool_uses": lv.total_tool_uses,
+        })
+except Exception:
+    pass
+'@
+
+try {
+    $governanceScript | & $pythonExe - | Out-Null
+} catch {
+    # Swallow — governance observation must never affect the Stop hook.
+}
+
 # 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