arkaos 5.12.0 → 5.14.0

package/THE-ARKAOS-GUIDE.md

@@ -1,6 +1,6 @@
 # The ArkaOS Guide
 
-> v5.12.0 — 89 agents, 17 departments, 340 skills, 306 commands, 20 ADRs.
+> v5.14.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.12.0
+5.14.0

package/bin/arka-py.ps1

@@ -25,7 +25,22 @@ $libs = @(
 foreach ($lib in $libs) {
     if (Test-Path -LiteralPath $lib) { . $lib; break }
 }
-if (-not $env:ARKA_PY) { $env:ARKA_PY = "python" }
+# Empty/unset means one of two things: the shared resolver was not found at
+# all, or it WAS found and deliberately handed back nothing because every
+# candidate is a Microsoft Store App Execution Alias. A blind `= "python"`
+# here cannot tell those apart, and on a stock Windows box it picks the
+# alias — running the Python install manager, which downloads a full CPython
+# into the caller's cwd. Probe once more, alias-aware, then fail loudly.
+if (-not $env:ARKA_PY) {
+    $fallback = Get-Command python -ErrorAction SilentlyContinue
+    if ($fallback -and $fallback.Source -notmatch '\\Microsoft\\WindowsApps\\') {
+        $env:ARKA_PY = $fallback.Source
+    } else {
+        [Console]::Error.WriteLine(
+            "arka-py: no usable Python interpreter on PATH (none found, or only Store aliases) - run npx arkaos doctor")
+        exit 1
+    }
+}
 
 # ─── Make `-m core.*` resolvable regardless of cwd ────────────────────────
 $root = $env:ARKAOS_ROOT

package/config/evals/marketing.yaml

@@ -389,7 +389,7 @@
     the carousel frames, and the different headline options they can compare. Can you put
     that together?
   expected_properties:
-  - Produces a creative review page from the HTML template, not plain markdown
+  - Produces a self-contained HTML creative review page, not plain markdown
   - Populates the DATA object (concept tabs, in-feed preview, frame storyboard, headline variations,
     copy, destination)
   - Labels storyboard frames by narrative job rather than by pictured content
@@ -398,9 +398,9 @@
   - Does not present invented stats or stock imagery as the brand's real assets
   - Uses placeholders for unrendered frames and keeps image paths relative
   - Explains how to deliver the page (open locally / host / hand off the file)
-  rubric: Should recognize this as a creative review page request and apply references/creative-review-page.md
-    + the assets/creative-review-template.html template rather than producing plain markdown.
-    Should copy the template into the output folder and populate its DATA object with the
+  rubric: Should recognize this as a creative review page request and apply the build spec in
+    references/creative-review-page.md rather than producing plain markdown. Should build a
+    single self-contained review.html in the output folder and populate its DATA block with the
     four concepts as tabs, each with an in-feed Instagram preview, a labeled frame-by-frame
     storyboard (frames labeled by narrative job — Hook / Problem / Proof / Ask — not by pictured
     content), selectable headline variations, primary text, and destination/CTA. Should curate

package/config/hooks/_lib/arka_python.ps1

@@ -8,9 +8,12 @@
 # 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`, skipping the
-#      Microsoft Store App Execution Aliases (see Test-StoreAlias).
-#   4. Bare `python` as a last resort.
+#   3. Any python/py/python3 on PATH that can `import yaml`, in THAT order
+#      (see the comment on the probe loop), skipping the Microsoft Store
+#      App Execution Aliases (see Test-StoreAlias).
+#   4. `python` as a last resort — but '' when that name is a Store alias
+#      too, because a caller cannot tell an alias from an interpreter and
+#      would run it (see Get-ArkaPythonLastResort).
 
 function Test-StoreAlias {
     <#
@@ -30,15 +33,45 @@ function Test-StoreAlias {
         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.
+        Probing an alias can never help anyway. Either the manager installs
+        a CPython and the probe measures THAT interpreter — a fresh install
+        with no pyyaml, so `import yaml` fails and the candidate is rejected
+        after paying the full cost — or the install is declined and the stub
+        exits without ever running the check. There is no path where probing
+        the alias answers the question it was asked.
     #>
     param([string]$Path)
     if ([string]::IsNullOrWhiteSpace($Path)) { return $false }
     return $Path -match '\\Microsoft\\WindowsApps\\'
 }
 
+function Get-ArkaPythonLastResort {
+    <#
+    .SYNOPSIS
+        The interpreter to hand back when no probed candidate answered, or
+        '' when the only name left is a Store alias.
+
+    .DESCRIPTION
+        Extracted from Resolve-ArkaPython so the branch is reachable from a
+        test: in place it sits behind a probe that matches on any machine
+        with a working interpreter.
+
+        Returning the bare string "python" from here was the hole in this
+        file's own guard. Every caller gates on `-and $env:ARKA_PY`, and any
+        non-empty string is truthy in PowerShell, so an aliased "python"
+        passed the gate and was then run — the exact install-manager side
+        effect Test-StoreAlias exists to prevent, arriving through the
+        fallback instead of the probe. '' is the only value that makes the
+        callers degrade, so '' is what a box with nothing but aliases gets.
+
+        Mirror of arka_python_last_resort() in arka_python.sh.
+    #>
+    param([string]$Name = "python")
+    $cmd = Get-Command $Name -ErrorAction SilentlyContinue
+    if ($cmd -and -not (Test-StoreAlias $cmd.Source)) { return $cmd.Source }
+    return ""
+}
+
 function Resolve-ArkaPython {
     if ($env:ARKAOS_PYTHON -and (Test-Path -LiteralPath $env:ARKAOS_PYTHON)) {
         return $env:ARKAOS_PYTHON
@@ -67,7 +100,7 @@ function Resolve-ArkaPython {
         }
     }
 
-    return "python"
+    return (Get-ArkaPythonLastResort)
 }
 
 # Windows mirror of arka_resolve_root() in arka_python.sh: env override wins

package/config/hooks/_lib/arka_python.sh

@@ -10,7 +10,9 @@
 # Contract of arka_resolve_python():
 #   Echoes the interpreter path and returns 0 when a provisioned ArkaOS
 #   interpreter is found; echoes a best-effort fallback and returns 1 when
-#   only a bare `python3` remains (caller degrades gracefully).
+#   only a bare `python3` remains (caller degrades gracefully). Echoes
+#   NOTHING and returns 1 when every remaining candidate is a Microsoft
+#   Store App Execution Alias — see arka_python_last_resort().
 #
 # Resolution order:
 #   1. $ARKAOS_PYTHON (explicit operator override), if executable.
@@ -18,7 +20,39 @@
 #      python3. `[ -x ]` follows symlinks, so a Homebrew-rotated broken
 #      symlink is skipped automatically.
 #   3. Any python3 on PATH / known locations that can `import yaml`.
-#   4. Bare `python3` as a last resort (return 1).
+#   4. Bare `python3` as a last resort (return 1), or nothing at all when
+#      that name — and `python` behind it — is only a Store alias.
+
+# Last-resort name selection, extracted from arka_resolve_python() so the
+# branch is reachable from a test: in place it sits behind a PATH probe
+# that matches on every POSIX box with a yaml-capable python3, so it can
+# only be exercised on the machine it was written for.
+#
+# Contract: echoes the name to hand back, or NOTHING when every remaining
+# candidate is a Store alias. Empty is the point, not an oversight. The
+# callers gate on `command -v "$ARKA_PY"` and an alias stub PASSES that
+# gate — the file is real, it is just the Python install manager rather
+# than an interpreter — so the only value that degrades a hook instead of
+# downloading a CPython into the user's project is no value at all.
+arka_python_last_resort() {
+  local py3 py
+  py3="$(command -v python3 2>/dev/null)"
+  case "$py3" in
+    *[Ww]indows[Aa]pps*) ;;
+    # Absent or real: the documented `python3` contract, unchanged. POSIX
+    # never reaches the alias branch below.
+    *) printf '%s\n' "python3"; return 0 ;;
+  esac
+
+  # `python3` is the alias. On a Windows box that HAS a real interpreter,
+  # `python` is the name it answers to; on a stock box with none, that is
+  # an alias too and we must hand back nothing.
+  py="$(command -v python 2>/dev/null)"
+  case "$py" in
+    "" | *[Ww]indows[Aa]pps*) return 0 ;;
+  esac
+  printf '%s\n' "python"
+}
 
 arka_resolve_python() {
   local cand
@@ -67,16 +101,7 @@ arka_resolve_python() {
     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"
+  arka_python_last_resort
   return 1
 }
 

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

@@ -3,7 +3,13 @@
 # ArkaOS v2 — Shared Workflow Classifier
 #
 # Decides whether a user prompt triggers the 4-gate evidence flow.
-# Used by: user-prompt-submit.sh, pre-tool-use.sh, stop.sh.
+#
+# CLI AND TEST SURFACE ONLY — no hook sources this file. The runtime path
+# is core/hooks/user_prompt_submit.py, which user-prompt-submit.sh execs;
+# these functions survive as the documented CLI (see the dispatcher at the
+# bottom) and as the bash half of the parity contract. That is precisely
+# why the two implementations must be diffed by hand: nothing at runtime
+# will ever notice them disagreeing.
 #
 # Contract:
 #   arka_wf_classify "<prompt text>"  → echoes "true" or "false", exits 0.
@@ -11,9 +17,11 @@
 #   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.
+# Markers live under $ARKA_WF_REQUIRED_DIR/<session_id>, defaulting to
+# /tmp/arkaos-wf-required (see below). The override is the seam that keeps
+# writer and reader on the same directory — core/shared/temp_paths.py
+# ::wf_required_dir is the Python side of it. mark/clear here write the
+# marker file directly; they do NOT call flow_enforcer.py.
 # ============================================================================
 
 ARKA_WF_REQUIRED_DIR="${ARKA_WF_REQUIRED_DIR:-/tmp/arkaos-wf-required}"
@@ -65,11 +73,22 @@ arka_wf_classify() {
 
   # Question guard: interrogative lead + trailing "?" = information
   # question, never creation intent (X5 false positive).
-  local trimmed
+  #
+  # The lead is taken from the FIRST NON-BLANK LINE, never from the whole
+  # text. The Python twin uses re.match on text.strip(), which can only
+  # match at offset 0; grep anchors ^ PER LINE, so feeding it everything
+  # made any later line able to trigger the guard. The two then disagreed
+  # on every multi-line prompt ending in a question — "implementa X\no que
+  # e que isto faz?" is a directive followed by a question, and a directive
+  # still requires the flow. awk reproduces .strip() closely enough for an
+  # anchor that already tolerates leading whitespace: skip blank lines,
+  # print the first line with content, stop.
+  local trimmed lead
   trimmed=$(printf '%s' "$text" | sed 's/[[:space:]]*$//')
   case "$trimmed" in
     *\?)
-      if echo "$text" | grep -qiE "$ARKA_WF_QUESTION_LEAD"; then
+      lead=$(printf '%s' "$text" | awk 'NF { print; exit }')
+      if printf '%s' "$lead" | grep -qiE "$ARKA_WF_QUESTION_LEAD"; then
         echo "false"
         return 0
       fi

package/config/hooks/session-start.ps1

@@ -5,8 +5,10 @@
 # (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).
+# interpreter and delegates; whenever it cannot reach that producer — no
+# repo root, no module file, no interpreter, or the module itself exiting
+# non-zero — 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
@@ -16,7 +18,10 @@
 # (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.
+# the same drift one release later, so this file delegates instead. The
+# twin-parity test in tests/python/test_hook_output_contract.py is what
+# holds that open: it asserts both wrappers run `-m core.hooks
+# .session_start`, and fails if either stops.
 #
 # Minimum PowerShell: 5.1 (shipped with every Windows 10+). No pwsh 7 prereq.
 # This file stays pure ASCII; every non-ASCII byte in the output comes from
@@ -73,8 +78,19 @@ if ($repo -and $moduleFile -and (Test-Path -LiteralPath $moduleFile) -and $env:A
 # --- 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.
+#
+# The message names the SYMPTOM, not a cause. Four conditions reach this
+# line (see the guard above) and only one of them is a missing interpreter;
+# the fourth — the module running and exiting non-zero — asserts the
+# opposite. The .sh twin execs, so its fallback is unreachable once an
+# interpreter is launched and the narrower wording survived there; this
+# port falls through on $LASTEXITCODE, which is what made it false. Sending
+# a Windows operator with a healthy Python to debug their Python, when the
+# real fault is a stale ~/.arkaos/.repo-path, costs more than the wording
+# saves. `npx arkaos doctor` diagnoses all four.
 $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"
+$emDash = [char]0x2014
+$banner = "`n  $tri  A R K A   O S`n     The Operating System for AI Agent Teams`n`n  Ol$oAcute, founder`n  degraded: ArkaOS core not reachable $emDash run npx arkaos doctor"
 [pscustomobject]@{ systemMessage = $banner } | ConvertTo-Json -Compress
 exit 0

package/config/hooks/session-start.sh

@@ -5,8 +5,9 @@
 # ONE python process (core.hooks.session_start) builds the entire
 # systemMessage — the 13 inline python spawns of the previous version
 # live there now (baseline 251ms p50 before consolidation). This file
-# only resolves the interpreter and execs; with no usable interpreter
-# it emits a static banner and exits 0 (fail-open, stdlib-free).
+# only resolves the interpreter and execs; whenever it cannot reach that
+# producer — no repo root, no module file, no interpreter — it emits a
+# static banner and exits 0 (fail-open, stdlib-free).
 # ============================================================================
 
 # _HOOK_CWD captured BEFORE any cd — inside a compound command $PWD
@@ -55,7 +56,10 @@ if [ -n "$REPO" ] && [ -f "$REPO/core/hooks/session_start.py" ] \
 fi
 
 # ─── Degraded fallback: static banner, valid JSON, exit 0 ──────────────
+# Names the symptom, not a cause: three conditions reach here and only one
+# of them is a missing interpreter. Kept byte-identical in wording to the
+# .ps1 twin so an operator on either platform reads the same diagnosis.
 cat <<'EOF'
-{"systemMessage": "\n  ▲  A R K A   O S\n     The Operating System for AI Agent Teams\n\n  Olá, founder\n  degraded: no usable interpreter — run npx arkaos doctor"}
+{"systemMessage": "\n  ▲  A R K A   O S\n     The Operating System for AI Agent Teams\n\n  Olá, founder\n  degraded: ArkaOS core not reachable — run npx arkaos doctor"}
 EOF
 exit 0

package/config/hooks/stop.ps1

@@ -24,9 +24,15 @@ $cwd = [string]$inp.cwd
 
 if ($stopHookActive -eq "true") { exit 0 }
 
-# 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.
+# Marker dir must match the Python writer: core.hooks.user_prompt_submit
+# ::_wf_mark_required resolves it through core.shared.temp_paths
+# ::wf_required_dir — which is arkaos_temp_dir('arkaos-wf-required'),
+# i.e. %TEMP%\arkaos-wf-required on Windows, EXCEPT that it honors
+# ARKA_WF_REQUIRED_DIR first. Read arkaos_temp_dir directly here and the
+# override splits writer from reader: the writer moves, this gate finds no
+# marker and allows everything, silently. That is the fail-open
+# wf_required_dir exists to close, so mirror wf_required_dir, not
+# arkaos_temp_dir.
 # 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.
@@ -204,131 +210,43 @@ try {
 }
 
 # ─── 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
+# config/hooks/stop.sh delegates the whole event to `python -m` the Stop
+# entrypoint, which runs the full detector chain (the authoritative list
+# is that module's own imports — no count is stated here because several
+# are conditional, so no fixed number is true of a given event). This
+# port reimplements the event 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.
 #
+# The sweep is a real module, not an inline script: core/hooks/
+# stop_governance.py. Delegating rather than mirroring is what keeps the
+# owner-only umask on the state files it writes — the previous inline
+# copy of _write_tmp_state had already lost it — and it is what lets the
+# parity test IMPORT AND RUN the sweep instead of grepping module names
+# out of this file, which a comment could satisfy.
+#
 # 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.
+$governanceModule = Join-Path $env:ARKAOS_ROOT "core/hooks/stop_governance.py"
+if (Test-Path -LiteralPath $governanceModule) {
+    # PREPEND, never clobber: an operator's own PYTHONPATH must survive
+    # the hook (the .sh twin prepends for the same reason).
+    $sep = [IO.Path]::PathSeparator
+    $env:PYTHONPATH = if ($env:PYTHONPATH) {
+        "$($env:ARKAOS_ROOT)$sep$($env:PYTHONPATH)"
+    } else {
+        $env:ARKAOS_ROOT
+    }
+    try {
+        & $pythonExe -m core.hooks.stop_governance | Out-Null
+    } catch {
+        # Swallow — governance observation must never affect the Stop hook.
+    }
 }
 
 # Belt-and-braces marker cleanup (safe even if the Python block crashed).

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

@@ -18,8 +18,10 @@
 # called the workflow classifier, so the wf-required marker was never
 # created on Windows: the per-prompt half of the evidence flow (and the
 # whole compliance chain behind the Stop hook) was dead on this platform.
-# Same failure mode as session-start.ps1 (twin drift). One producer, two
-# thin wrappers.
+# Same failure mode as session-start.ps1 (twin drift), and the same fix:
+# delegate, and let the twin-parity test in tests/python/
+# test_hook_output_contract.py fail the build if this file ever stops
+# running `-m core.hooks.user_prompt_submit`.
 #
 # Minimum PowerShell: 5.1. This file stays pure ASCII; every non-ASCII byte
 # in the output comes from Python's UTF-8 stdout.