arkaos 4.3.1 → 4.3.2

package/README.md

@@ -491,7 +491,7 @@ npx arkaos uninstall           # Remove ArkaOS
 **Release pipeline (operator-side, headless):**
 
 ```
-python -m core.release.preflight_cli --expected-npm-user <user>
+~/.arkaos/bin/arka-py -m core.release.preflight_cli --expected-npm-user <user>
 # Step 0 NON-NEGOTIABLE before any tag/push/publish (v2.43.0+).
 # Six checks: version-alignment / npm-auth / npm-publish-capability /
 # gh-auth / git-remote / git-clean. Plus no-client-name-leaks

package/VERSION

@@ -1 +1 @@
-4.3.1
+4.3.2

package/arka/SKILL.md

@@ -180,10 +180,10 @@ violation (squad-routing, arka-supremacy, spec-driven, mandatory-qa).
 | Command | Description |
 |---------|-------------|
 | `/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")`. Also includes **Enforcement (24h)** section: total calls, block rate, top blocked tools/reasons from `core.governance.enforcement_telemetry.summarise(period="today")` (PR19 v2.41.0). Plus **Reorganization (today)** section: today's proposal path + artifact count from `core.cognition.reorganizer_scheduler.status_summary()` (PR24 v2.46.0). |
-| `/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 enforcement [period]` | Enforcement compliance — aggregates flow-marker enforcement telemetry by day/week/month/all. Shows block rate, top blocked tools, top reasons. Shells out to `python -m core.governance.enforcement_telemetry_cli <period>`. |
-| `/arka compliance [period]` | Behavior compliance summary (PR29 v2.48.0) — aggregates stop-hook telemetry by day/week/month/all. Shows rates for the four contracts: closing marker, `[arka:meta]` tag, KB citation pass, sycophancy clean. Shells out to `python -m core.governance.compliance_telemetry_cli <period>`. |
-| `/arka reorganize [--since-days N]` | Dreaming → Agent reorganizer. Aggregates recent KB pattern/anti-pattern/lesson artifacts (default last 7 days) into a markdown proposal at `~/.arkaos/reorganize-proposals/<date>.md`. **Propose-only** — never modifies agent YAMLs. Sanitizes client identifiers from titles and body excerpts; drops `tags:` field entirely to prevent project-name leaks. **Auto-fires on session start when today's proposal is missing** (PR24 v2.46.0 stale-aware trigger, 30s timeout, background). Shells out to `python -m core.cognition.reorganizer_cli [--since-days N] [--dry-run]`. |
+| `/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 `~/.arkaos/bin/arka-py -m core.runtime.llm_cost_telemetry_cli <period>`. |
+| `/arka enforcement [period]` | Enforcement compliance — aggregates flow-marker enforcement telemetry by day/week/month/all. Shows block rate, top blocked tools, top reasons. Shells out to `~/.arkaos/bin/arka-py -m core.governance.enforcement_telemetry_cli <period>`. |
+| `/arka compliance [period]` | Behavior compliance summary (PR29 v2.48.0) — aggregates stop-hook telemetry by day/week/month/all. Shows rates for the four contracts: closing marker, `[arka:meta]` tag, KB citation pass, sycophancy clean. Shells out to `~/.arkaos/bin/arka-py -m core.governance.compliance_telemetry_cli <period>`. |
+| `/arka reorganize [--since-days N]` | Dreaming → Agent reorganizer. Aggregates recent KB pattern/anti-pattern/lesson artifacts (default last 7 days) into a markdown proposal at `~/.arkaos/reorganize-proposals/<date>.md`. **Propose-only** — never modifies agent YAMLs. Sanitizes client identifiers from titles and body excerpts; drops `tags:` field entirely to prevent project-name leaks. **Auto-fires on session start when today's proposal is missing** (PR24 v2.46.0 stale-aware trigger, 30s timeout, background). Shells out to `~/.arkaos/bin/arka-py -m core.cognition.reorganizer_cli [--since-days N] [--dry-run]`. |
 | `/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

@@ -42,7 +42,7 @@ surfaces usage and emits soft advisories. It never blocks a call.
 This skill shells out to the Python CLI:
 
 ```bash
-python -m core.runtime.llm_cost_telemetry_cli <period>
+~/.arkaos/bin/arka-py -m core.runtime.llm_cost_telemetry_cli <period>
 ```
 
 Source:

package/arka/skills/fusion/SKILL.md

@@ -24,9 +24,9 @@ mechanical work economises.
 Run and read all three:
 
 ```bash
-python -m core.runtime.model_router_cli discover        # Ollama + local models
-python -m core.runtime.model_router_cli --json          # current routing
-python -m core.runtime.model_router_cli usage --period week --json
+~/.arkaos/bin/arka-py -m core.runtime.model_router_cli discover        # Ollama + local models
+~/.arkaos/bin/arka-py -m core.runtime.model_router_cli --json          # current routing
+~/.arkaos/bin/arka-py -m core.runtime.model_router_cli usage --period week --json
 ```
 
 Also check key presence (never print values): `OPENROUTER_API_KEY` /

package/config/claude-agents/marta-cqo.md

@@ -23,7 +23,7 @@ evidence, not from model size.
 ## Review Rubric (evidence interpretation, not role-play)
 
 1. Run the engine first — no verdict without a report:
-   `python -m core.governance.evidence_checks <project_dir> [--changed-files ...] [--test-command '...'] --json`
+   `~/.arkaos/bin/arka-py -m core.governance.evidence_checks <project_dir> [--changed-files ...] [--test-command '...'] --json`
 2. Dispatch Eduardo (spellcheck + changed copy) and Francisca
    (lint/typecheck/tests/coverage/security-grep) with the report and the
    structured output schema `QG_VERDICT_JSON_SCHEMA` from

package/config/claude-agents/paulo-tech-lead.md

@@ -24,7 +24,7 @@ not cut corners to look fast.
    dispatch with `[arka:dispatch] paulo -> <specialist>`.
 3. Evidence over narration: a task is done when its tests RAN and exited 0
    on record — never when a subagent says it is done. Run
-   `python -m core.governance.evidence_checks <project_dir> --json` before
+   `~/.arkaos/bin/arka-py -m core.governance.evidence_checks <project_dir> --json` before
    claiming completion.
 4. Submit to the Quality Gate (marta-cqo) with the evidence report; expect
    a structured `QGVerdict` back. REJECTED means loop, not negotiate.

package/config/constitution.yaml

@@ -142,7 +142,7 @@ enforcement_levels:
           scope: "All technical: code quality, tests, UX/UI, data integrity, security, performance"
           veto_power: true
     process:
-      - "Evidence engine runs first: python -m core.governance.evidence_checks — the verdict derives from its report"
+      - "Evidence engine runs first: ~/.arkaos/bin/arka-py -m core.governance.evidence_checks — the verdict derives from its report"
       - "Marta receives all output from execution phase plus the evidence report"
       - "Marta dispatches Eduardo (text) and Francisca (technical) in parallel, each in an INDEPENDENT subagent context (clean context, no stake in the work being approved)"
       - "Each reviewer returns a structured QGVerdict (APPROVED or REJECTED) with specific issues; the verdict MUST name the benchmark used (reference_companies.application) and enumerate the concrete rejections a top-tier lead would raise; evidence overall=fail forces REJECTED"
@@ -197,7 +197,7 @@ enforcement_levels:
       # ─── Rule added in PR3 Squad Intelligence Upgrade (2026-05-28) ───────
       - id: agent-experience-persistence
         rule: "Quality Gate REJECTED verdicts MUST result in an Experience record for the failing agent, written to ~/.arkaos/agents/<agent_id>/experiences.jsonl via core.governance.cqo_experience_recorder. Next dispatch of that agent loads the experiences via the Synapse L2.6 layer (core.synapse.agent_experiences_layer) so the lesson carries across sessions. Without this, REJECTED reports evaporate as conversation turns and the same structural mistakes recur."
-        enforcement: "PR3 v3.74.0 ships the storage, parser, and Synapse layer. v3.74.1 will wire a PostToolUse hook on the Agent tool that auto-records on REJECTED verdicts. Until then orchestrators MUST call cqo_experience_recorder.record_from_verdict() after every CQO dispatch. Audit via python -m core.governance.agent_experiences_cli list <agent_id>."
+        enforcement: "PR3 v3.74.0 ships the storage, parser, and Synapse layer. v3.74.1 will wire a PostToolUse hook on the Agent tool that auto-records on REJECTED verdicts. Until then orchestrators MUST call cqo_experience_recorder.record_from_verdict() after every CQO dispatch. Audit via ~/.arkaos/bin/arka-py -m core.governance.agent_experiences_cli list <agent_id>."
 
   should:
     description: "Best practices. Encouraged but not enforced."
@@ -221,17 +221,17 @@ enforcement_levels:
       # ─── Rule added in PR6 Squad Intelligence Upgrade (2026-05-28) ───────
       - id: design-system-locked
         rule: "Each project SHOULD declare a `design-system.yaml` at its root listing tokens (colors, spacing, fonts), allowed_components, file_globs to scan, and forbidden_patterns with suggestions. The per-project linter (core.governance.design_system_lint) detects UI/UX drift — hex literals outside the palette, inline style attributes, raw HTML where a Nuxt UI component exists, etc. Adoption is opt-in per project (no YAML at project root → no violations). v3.77.0 is advisory-only; pre-commit hook integration lands in v3.77.x once the rule sets stabilise across the operator's projects."
-        enforcement: "Run via `python -m core.governance.design_system_lint_cli <project_path>` (text or JSON output, optional --exit-on-violations). Example template at `docs/examples/design-system-example.yaml`."
+        enforcement: "Run via `~/.arkaos/bin/arka-py -m core.governance.design_system_lint_cli <project_path>` (text or JSON output, optional --exit-on-violations). Example template at `docs/examples/design-system-example.yaml`."
 
       # ─── Rule added in PR5 Squad Intelligence Upgrade (2026-05-28) ───────
       - id: dna-fidelity-warn
         rule: "Agent outputs are compared against the `signature_markers` block in each agent's YAML at the end of every turn. Forbidden patterns (avoid_patterns) and missing opening phrases (opening_phrases) generate FidelityViolation records in ~/.arkaos/telemetry/dna-fidelity.jsonl. v3.76.0 is soft-warn — violations are recorded for telemetry and operator review, not blocked. Hard-block mode lands later once the marker set is calibrated against real production usage."
-        enforcement: "Stop hook (config/hooks/stop.sh) calls core.governance.dna_fidelity.check_fidelity at turn end. Telemetry inspection: python -m core.governance.dna_fidelity_cli list|summary. Agents in scope for v3.76.0: tech-lead-paulo, cqo-marta, copy-director-eduardo, tech-director-francisca. Remaining 61 agent YAMLs get signature_markers in v3.76.x curation work."
+        enforcement: "Stop hook (config/hooks/stop.sh) calls core.governance.dna_fidelity.check_fidelity at turn end. Telemetry inspection: ~/.arkaos/bin/arka-py -m core.governance.dna_fidelity_cli list|summary. Agents in scope for v3.76.0: tech-lead-paulo, cqo-marta, copy-director-eduardo, tech-director-francisca. Remaining 61 agent YAMLs get signature_markers in v3.76.x curation work."
 
       # ─── Rule added in PR4 Squad Intelligence Upgrade (2026-05-28) ───────
       - id: pattern-library-first
         rule: "Before designing any new feature, consult the Pattern Library (core.knowledge.pattern_cards). If a similar pattern exists, reuse it or explicitly document why divergence is justified in the spec. New patterns SHOULD be registered with record_pattern() after Quality Gate APPROVED so future feature work inherits the prior art."
-        enforcement: "Synapse layer L7.5 (core.synapse.pattern_library_layer) auto-injects top matching cards as context. Audit via python -m core.knowledge.pattern_cards_cli list. SHOULD level — promoted from advisory once telemetry shows consistent consultation."
+        enforcement: "Synapse layer L7.5 (core.synapse.pattern_library_layer) auto-injects top matching cards as context. Audit via ~/.arkaos/bin/arka-py -m core.knowledge.pattern_cards_cli list. SHOULD level — promoted from advisory once telemetry shows consistent consultation."
 
 tier_hierarchy:
   description: "Agent authority levels inspired by SpaceX/Google/Anthropic org structures"

package/config/hooks/_lib/arka_python.ps1

@@ -0,0 +1,43 @@
+# ArkaOS shared Python resolver (PowerShell side) — single source of truth.
+#
+# Windows mirror of config/hooks/_lib/arka_python.sh and
+# installer/python-resolver.js. Prefers the ~/.arkaos venv (has pyyaml/
+# pydantic); never silently falls back to a system python that lacks ArkaOS
+# deps. Dot-source this file: it sets $env:ARKA_PY.
+#
+# 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`.
+#   4. Bare `python` as a last resort.
+
+function Resolve-ArkaPython {
+    if ($env:ARKAOS_PYTHON -and (Test-Path -LiteralPath $env:ARKAOS_PYTHON)) {
+        return $env:ARKAOS_PYTHON
+    }
+
+    $base = if ($env:USERPROFILE) { $env:USERPROFILE } elseif ($HOME) { $HOME } else { "" }
+    if ($base) {
+        $candidates = @(
+            (Join-Path $base ".arkaos\venv\Scripts\python.exe"),
+            (Join-Path $base ".arkaos/venv/bin/python"),
+            (Join-Path $base ".arkaos\.venv\Scripts\python.exe"),
+            (Join-Path $base ".arkaos/.venv/bin/python")
+        )
+        foreach ($c in $candidates) {
+            if (Test-Path -LiteralPath $c) { return $c }
+        }
+    }
+
+    foreach ($name in @("python3", "python", "py")) {
+        $cmd = Get-Command $name -ErrorAction SilentlyContinue
+        if ($cmd) {
+            & $cmd.Source -c "import yaml" 2>$null
+            if ($LASTEXITCODE -eq 0) { return $cmd.Source }
+        }
+    }
+
+    return "python"
+}
+
+$env:ARKA_PY = Resolve-ArkaPython

package/config/hooks/_lib/arka_python.sh

@@ -0,0 +1,63 @@
+# shellcheck shell=bash
+# ArkaOS shared Python resolver (shell side) — single source of truth.
+#
+# Mirrors installer/python-resolver.js (getArkaosPython). Every hook, the
+# state reader, the agent-provision helper, and the `arka-py` shim source
+# THIS file instead of probing for `python3` on their own. Rationale: an
+# unrelated project venv first on PATH, or a system python without pyyaml/
+# pydantic, silently degrades every gate. The ArkaOS venv is authoritative.
+#
+# 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).
+#
+# Resolution order:
+#   1. $ARKAOS_PYTHON (explicit operator override), if executable.
+#   2. The ArkaOS venv — ~/.arkaos/venv then ~/.arkaos/.venv, python then
+#      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).
+
+arka_resolve_python() {
+  local cand
+
+  if [ -n "${ARKAOS_PYTHON:-}" ] && [ -x "${ARKAOS_PYTHON}" ]; then
+    printf '%s\n' "${ARKAOS_PYTHON}"
+    return 0
+  fi
+
+  for cand in \
+      "$HOME/.arkaos/venv/bin/python" \
+      "$HOME/.arkaos/venv/bin/python3" \
+      "$HOME/.arkaos/.venv/bin/python" \
+      "$HOME/.arkaos/.venv/bin/python3"; 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
+      printf '%s\n' "$cand"
+      return 0
+    fi
+  done
+
+  printf '%s\n' "python3"
+  return 1
+}
+
+# Sourcing this file exports ARKA_PY once, so hooks can `exec "$ARKA_PY" ...`
+# without each re-running the probe. Callers that need the return code call
+# arka_resolve_python directly.
+#
+# `|| true` is REQUIRED: arka_resolve_python returns 1 on the last-resort
+# fallback, and under `set -e` a failing command substitution in an
+# assignment aborts the sourcing file mid-way (reproduced on bash 3.2.57).
+# We still want ARKA_PY set to the fallback value, so swallow the status and
+# keep the export unconditional.
+ARKA_PY="$(arka_resolve_python)" || true
+export ARKA_PY

package/config/hooks/agent-provision.sh

@@ -7,6 +7,13 @@
 
 set -euo pipefail
 
+# ─── Shared Python resolver (exports ARKA_PY) ──────────────────────────
+# The resolver guards its own ARKA_PY assignment with `|| true`, so sourcing
+# is set -e-safe even on the last-resort fallback. The trailing `|| true`
+# here is belt-and-suspenders for a partially-updated lib.
+_ARKA_LIB="$(dirname "${BASH_SOURCE[0]:-$0}")/_lib/arka_python.sh"
+if [ -f "$_ARKA_LIB" ]; then . "$_ARKA_LIB" || true; else ARKA_PY="python3"; fi
+
 # Hook contract: stdin is a JSON payload with fields tool_name + tool_input.
 payload="$(cat)"
 
@@ -44,7 +51,7 @@ fi
 if [ -d "$core_root/departments" ]; then
     mkdir -p "$project_agents_dir"
     set +e
-    python3 - "$core_root" "$subagent_type" "$target" <<'PY'
+    "$ARKA_PY" - "$core_root" "$subagent_type" "$target" <<'PY'
 import os, re, sys
 from pathlib import Path
 

package/config/hooks/cwd-changed.sh

@@ -8,6 +8,10 @@
 input=$(cat)
 NEW_CWD=$(echo "$input" | jq -r '.cwd // ""' 2>/dev/null)
 
+# ─── Shared Python resolver (exports ARKA_PY) ──────────────────────────
+_ARKA_LIB="$(dirname "${BASH_SOURCE[0]:-$0}")/_lib/arka_python.sh"
+if [ -f "$_ARKA_LIB" ]; then . "$_ARKA_LIB"; else ARKA_PY="python3"; fi
+
 if [ -z "$NEW_CWD" ] || [ ! -d "$NEW_CWD" ]; then
   exit 0
 fi
@@ -23,8 +27,8 @@ fi
 ECOSYSTEM=""
 ECOSYSTEM_NAME=""
 
-if [ -f "$ECOSYSTEMS_FILE" ] && command -v python3 &>/dev/null; then
-  eval "$(python3 -c "
+if [ -f "$ECOSYSTEMS_FILE" ] && command -v "$ARKA_PY" >/dev/null 2>&1; then
+  eval "$("$ARKA_PY" -c "
 import json, os, sys
 
 cwd = '$NEW_CWD'

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

@@ -7,6 +7,10 @@
 
 input=$(cat)
 
+# ─── Shared Python resolver (exports ARKA_PY) ──────────────────────────
+_ARKA_LIB="$(dirname "${BASH_SOURCE[0]:-$0}")/_lib/arka_python.sh"
+if [ -f "$_ARKA_LIB" ]; then . "$_ARKA_LIB"; else ARKA_PY="python3"; fi
+
 ARKAOS_HOME="${HOME}/.arkaos"
 GOTCHAS_FILE="$ARKAOS_HOME/gotchas.json"
 
@@ -74,8 +78,8 @@ project=$(basename "$cwd")
     echo "[]" > "$GOTCHAS_FILE"
   fi
 
-  if command -v python3 &>/dev/null; then
-    python3 -c "
+  if command -v "$ARKA_PY" >/dev/null 2>&1; then
+    "$ARKA_PY" -c "
 import json, sys
 try:
     with open('$GOTCHAS_FILE') as f:

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

@@ -31,7 +31,11 @@ if [ -z "${ARKAOS_ROOT:-}" ]; then
 fi
 export ARKAOS_ROOT
 
-if ! command -v python3 &>/dev/null; then
+# ─── Shared Python resolver (exports ARKA_PY) ──────────────────────────
+_ARKA_LIB="$(dirname "${BASH_SOURCE[0]:-$0}")/_lib/arka_python.sh"
+if [ -f "$_ARKA_LIB" ]; then . "$_ARKA_LIB"; else ARKA_PY="python3"; fi
+
+if ! command -v "$ARKA_PY" >/dev/null 2>&1; then
   echo '{}'
   exit 0
 fi
@@ -49,20 +53,7 @@ if [ ! -f "$ARKAOS_ROOT/core/hooks/post_tool_use.py" ]; then
   fi
 fi
 
-# Interpreter resolution: prefer the ArkaOS venv (has pyyaml/pydantic);
-# otherwise probe — an unrelated project venv first on PATH would give a
-# python3 without yaml and silently degrade every gate.
-_PY=""
-for _cand in "$HOME/.arkaos/venv/bin/python3" "$HOME/.arkaos/.venv/bin/python3"; do
-  if [ -x "$_cand" ]; then _PY="$_cand"; break; fi
-done
-if [ -z "$_PY" ]; then
-  _PY="python3"
-  if ! "$_PY" -c "import yaml" 2>/dev/null; then
-    for _cand in /opt/homebrew/bin/python3 /usr/local/bin/python3 /usr/bin/python3; do
-      if [ -x "$_cand" ] && "$_cand" -c "import yaml" 2>/dev/null; then _PY="$_cand"; break; fi
-    done
-  fi
-fi
+# Interpreter resolution handled by the shared resolver (ARKA_PY): prefers
+# the ArkaOS venv (has pyyaml/pydantic), falls back to a yaml-capable python3.
 PYTHONPATH="$ARKAOS_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
-  exec "$_PY" -m core.hooks.post_tool_use
+  exec "$ARKA_PY" -m core.hooks.post_tool_use

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

@@ -39,9 +39,11 @@ if ([string]::IsNullOrWhiteSpace($env:ARKAOS_ROOT)) {
     }
 }
 
-$python = Get-Command python3 -ErrorAction SilentlyContinue
-if (-not $python) { $python = Get-Command python -ErrorAction SilentlyContinue }
-if (-not $python) { exit 0 }
+# Shared resolver (venv-first, yaml-verified). Mirrors _lib/arka_python.sh.
+$arkaLib = Join-Path $PSScriptRoot "_lib\arka_python.ps1"
+if (Test-Path -LiteralPath $arkaLib) { . $arkaLib }
+$pythonExe = $env:ARKA_PY
+if (-not $pythonExe) { exit 0 }
 
 # --- KB-first gate (Task #6, runs before flow-marker gate) ---
 $queryHint = ""
@@ -91,7 +93,7 @@ print(json.dumps({
 }))
 '@
 
-    $kbDecisionJson = $kbScript | & $python.Source -
+    $kbDecisionJson = $kbScript | & $pythonExe -
     if (-not [string]::IsNullOrWhiteSpace($kbDecisionJson)) {
         try {
             $kbDecision = $kbDecisionJson | ConvertFrom-Json
@@ -172,7 +174,7 @@ print(json.dumps({
 }))
 '@
 
-    $spDecisionJson = $spScript | & $python.Source -
+    $spDecisionJson = $spScript | & $pythonExe -
     if (-not [string]::IsNullOrWhiteSpace($spDecisionJson)) {
         try {
             $spDecision = $spDecisionJson | ConvertFrom-Json
@@ -241,7 +243,7 @@ print(json.dumps({
 }))
 '@
 
-$decisionJson = $pyScript | & $python.Source -
+$decisionJson = $pyScript | & $pythonExe -
 if ([string]::IsNullOrWhiteSpace($decisionJson)) { exit 0 }
 
 try {

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

@@ -34,8 +34,12 @@ if [ -z "${ARKAOS_ROOT:-}" ]; then
 fi
 export ARKAOS_ROOT
 
+# ─── Shared Python resolver (exports ARKA_PY) ──────────────────────────
+_ARKA_LIB="$(dirname "${BASH_SOURCE[0]:-$0}")/_lib/arka_python.sh"
+if [ -f "$_ARKA_LIB" ]; then . "$_ARKA_LIB"; else ARKA_PY="python3"; fi
+
 # ─── Degrade gracefully (fail open, same as before) ─────────────────────
-if ! command -v python3 &>/dev/null; then
+if ! command -v "$ARKA_PY" >/dev/null 2>&1; then
   exit 0
 fi
 # Self-root fallback: the wrapper ships next to its python entrypoint, so
@@ -52,20 +56,7 @@ if [ ! -f "$ARKAOS_ROOT/core/hooks/pre_tool_use.py" ]; then
 fi
 
 # ─── Single python process; stdin/stdout/stderr/exit-code pass through ──
-# Interpreter resolution: prefer the ArkaOS venv (has pyyaml/pydantic);
-# otherwise probe — an unrelated project venv first on PATH would give a
-# python3 without yaml and silently degrade every gate.
-_PY=""
-for _cand in "$HOME/.arkaos/venv/bin/python3" "$HOME/.arkaos/.venv/bin/python3"; do
-  if [ -x "$_cand" ]; then _PY="$_cand"; break; fi
-done
-if [ -z "$_PY" ]; then
-  _PY="python3"
-  if ! "$_PY" -c "import yaml" 2>/dev/null; then
-    for _cand in /opt/homebrew/bin/python3 /usr/local/bin/python3 /usr/bin/python3; do
-      if [ -x "$_cand" ] && "$_cand" -c "import yaml" 2>/dev/null; then _PY="$_cand"; break; fi
-    done
-  fi
-fi
+# Interpreter resolution handled by the shared resolver (ARKA_PY): prefers
+# the ArkaOS venv (has pyyaml/pydantic), falls back to a yaml-capable python3.
 PYTHONPATH="$ARKAOS_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
-  exec "$_PY" -m core.hooks.pre_tool_use
+  exec "$ARKA_PY" -m core.hooks.pre_tool_use

package/config/hooks/session-start.sh

@@ -9,9 +9,13 @@ NAME="founder"
 COMPANY="WizardingCode"
 VERSION="2.x"
 
-if [ -f "$HOME/.arkaos/profile.json" ] && command -v python3 &>/dev/null; then
-  NAME=$(python3 -c "import json; p=json.load(open('$HOME/.arkaos/profile.json')); print(p.get('name', p.get('role', 'founder')))" 2>/dev/null || echo "founder")
-  COMPANY=$(python3 -c "import json; print(json.load(open('$HOME/.arkaos/profile.json')).get('company', 'WizardingCode'))" 2>/dev/null || echo "WizardingCode")
+# ─── Shared Python resolver (exports ARKA_PY) ──────────────────────────
+_ARKA_LIB="$(dirname "${BASH_SOURCE[0]:-$0}")/_lib/arka_python.sh"
+if [ -f "$_ARKA_LIB" ]; then . "$_ARKA_LIB"; else ARKA_PY="python3"; fi
+
+if [ -f "$HOME/.arkaos/profile.json" ] && command -v "$ARKA_PY" >/dev/null 2>&1; then
+  NAME=$("$ARKA_PY" -c "import json; p=json.load(open('$HOME/.arkaos/profile.json')); print(p.get('name', p.get('role', 'founder')))" 2>/dev/null || echo "founder")
+  COMPANY=$("$ARKA_PY" -c "import json; print(json.load(open('$HOME/.arkaos/profile.json')).get('company', 'WizardingCode'))" 2>/dev/null || echo "WizardingCode")
 fi
 
 if [ -f "$HOME/.arkaos/.repo-path" ]; then
@@ -29,7 +33,7 @@ SYNC_STATE="$HOME/.arkaos/sync-state.json"
 DRIFT=""
 
 if [ -f "$SYNC_STATE" ]; then
-  SYNCED=$(python3 -c "import json; print(json.load(open('$SYNC_STATE'))['version'])" 2>/dev/null || echo "none")
+  SYNCED=$("$ARKA_PY" -c "import json; print(json.load(open('$SYNC_STATE'))['version'])" 2>/dev/null || echo "none")
   if [ "$SYNCED" != "$VERSION" ]; then
     DRIFT="\\n[arka:update-available] Core v${VERSION} != synced v${SYNCED}. Run /arka update."
   fi
@@ -71,11 +75,11 @@ _FORGE_LINE=""
 if [ -f "$_FORGE_ACTIVE" ]; then
   _FORGE_ID=$(cat "$_FORGE_ACTIVE" 2>/dev/null)
   _FORGE_FILE="$_FORGE_PLANS/${_FORGE_ID}.yaml"
-  if [ -f "$_FORGE_FILE" ] && command -v python3 &>/dev/null; then
-    _FORGE_NAME=$(FORGE_FILE="$_FORGE_FILE" python3 -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(d.get('name',''))" 2>/dev/null)
-    _FORGE_STATUS=$(FORGE_FILE="$_FORGE_FILE" python3 -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(d.get('status',''))" 2>/dev/null)
-    _FORGE_PHASES=$(FORGE_FILE="$_FORGE_FILE" python3 -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(len(d.get('plan_phases',[])))" 2>/dev/null)
-    _FORGE_BRANCH=$(FORGE_FILE="$_FORGE_FILE" python3 -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(d.get('governance',{}).get('branch_strategy',''))" 2>/dev/null)
+  if [ -f "$_FORGE_FILE" ] && command -v "$ARKA_PY" >/dev/null 2>&1; then
+    _FORGE_NAME=$(FORGE_FILE="$_FORGE_FILE" "$ARKA_PY" -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(d.get('name',''))" 2>/dev/null)
+    _FORGE_STATUS=$(FORGE_FILE="$_FORGE_FILE" "$ARKA_PY" -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(d.get('status',''))" 2>/dev/null)
+    _FORGE_PHASES=$(FORGE_FILE="$_FORGE_FILE" "$ARKA_PY" -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(len(d.get('plan_phases',[])))" 2>/dev/null)
+    _FORGE_BRANCH=$(FORGE_FILE="$_FORGE_FILE" "$ARKA_PY" -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(d.get('governance',{}).get('branch_strategy',''))" 2>/dev/null)
 
     if [ "$_FORGE_STATUS" = "approved" ]; then
       _FORGE_LINE="  ⚒ Forge plan pending: ${_FORGE_NAME} | Phases: ${_FORGE_PHASES} | /forge resume"
@@ -110,12 +114,10 @@ MSG+="\\nAbsence is measured by the Stop hook (warn-only in v2.34.0) before prom
 # dashboard/CLI model choices actually govern agent dispatch. Cheap
 # (single python read); skipped silently if the config can't be resolved.
 if [ -n "$REPO" ]; then
-  # Prefer the ArkaOS venv python (has pydantic + yaml); the ambient
-  # python3 usually lacks them and routing_directive() would return "".
-  _MF_PY="python3"
-  [ -x "$HOME/.arkaos/venv/bin/python3" ] && _MF_PY="$HOME/.arkaos/venv/bin/python3"
-  if command -v "$_MF_PY" &>/dev/null || [ -x "$_MF_PY" ]; then
-    _MF_DIRECTIVE=$(cd "$REPO" && PYTHONPATH="$REPO" "$_MF_PY" -c "
+  # ARKA_PY already resolves to the venv python (has pydantic + yaml); the
+  # ambient python3 usually lacks them and routing_directive() would return "".
+  if command -v "$ARKA_PY" >/dev/null 2>&1 || [ -x "$ARKA_PY" ]; then
+    _MF_DIRECTIVE=$(cd "$REPO" && PYTHONPATH="$REPO" "$ARKA_PY" -c "
 try:
     from core.runtime.model_routing_context import routing_directive
     print(routing_directive())
@@ -132,12 +134,12 @@ fi
 # If today's proposal file is missing, fire the reorganizer in the
 # background with a 30s timeout. Best-effort, never blocks session
 # start. Multiple sessions per day no-op because the file now exists.
-if [ -n "$REPO" ] && command -v python3 &>/dev/null; then
+if [ -n "$REPO" ] && command -v "$ARKA_PY" >/dev/null 2>&1; then
   _PROPOSAL_DIR="$HOME/.arkaos/reorganize-proposals"
   _TODAY="$(date -u +%Y-%m-%d).md"
   if [ ! -f "$_PROPOSAL_DIR/$_TODAY" ]; then
     (
-      cd "$REPO" && timeout 30s python3 -m core.cognition.reorganizer_cli >/dev/null 2>&1
+      cd "$REPO" && timeout 30s "$ARKA_PY" -m core.cognition.reorganizer_cli >/dev/null 2>&1
     ) &
     disown 2>/dev/null || true
   fi
@@ -149,7 +151,7 @@ fi
 # starts API+UI. Background + disown so it never touches the 5s budget.
 # Toggle off: ~/.arkaos/config.json -> {"dashboard": {"ensure_on_session": false}}
 if [ -n "$REPO" ] && [ -f "$REPO/scripts/start-dashboard.sh" ]; then
-  _DASH_ENSURE=$(python3 -c "import json; print(json.load(open('$HOME/.arkaos/config.json')).get('dashboard',{}).get('ensure_on_session', True))" 2>/dev/null || echo "True")
+  _DASH_ENSURE=$("$ARKA_PY" -c "import json; print(json.load(open('$HOME/.arkaos/config.json')).get('dashboard',{}).get('ensure_on_session', True))" 2>/dev/null || echo "True")
   if [ "$_DASH_ENSURE" = "True" ] || [ "$_DASH_ENSURE" = "true" ]; then
     mkdir -p "$HOME/.arkaos/logs"
     (
@@ -166,8 +168,8 @@ if [ -n "$REPO" ] && [ -f "$REPO/scripts/start-dashboard.sh" ]; then
 fi
 
 # --- Session Memory Resume Context ---
-if command -v python3 &>/dev/null && [ -n "$REPO" ]; then
-  _SESSION_CTX=$(cd "$REPO" && python3 -c "
+if command -v "$ARKA_PY" >/dev/null 2>&1 && [ -n "$REPO" ]; then
+  _SESSION_CTX=$(cd "$REPO" && "$ARKA_PY" -c "
 import sys
 sys.path.insert(0, '$REPO')
 try:
@@ -182,7 +184,7 @@ except Exception:
 fi
 
 # ─── Output as systemMessage (same protocol as claude-mem) ─────────────
-python3 -c "
+"$ARKA_PY" -c "
 import json
 msg = '''$(echo -e "$MSG")'''
 print(json.dumps({'systemMessage': msg}))

package/config/hooks/stop.ps1

@@ -43,9 +43,11 @@ 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 }
+# Shared resolver (venv-first, yaml-verified). Mirrors _lib/arka_python.sh.
+$arkaLib = Join-Path $PSScriptRoot "_lib\arka_python.ps1"
+if (Test-Path -LiteralPath $arkaLib) { . $arkaLib }
+$pythonExe = $env:ARKA_PY
+if (-not $pythonExe) { exit 0 }
 
 $env:SESSION_ID_VAL = $sessionId
 $env:TRANSCRIPT_PATH_VAL = $transcriptPath
@@ -102,7 +104,7 @@ except Exception:
     pass
 '@
 
-$pyScript | & $python.Source - | Out-Null
+$pyScript | & $pythonExe - | Out-Null
 
 # ─── Auto-documentor enqueue (fire-and-forget) ─────────────────────────
 # Queues a background job when classifier flagged flow, QG approved, and
@@ -178,7 +180,7 @@ except Exception:
 '@
 
 try {
-    $autoDocScript | & $python.Source - | Out-Null
+    $autoDocScript | & $pythonExe - | Out-Null
 } catch {
     # Swallow — enqueue is fire-and-forget.
 }

package/config/hooks/stop.sh

@@ -33,7 +33,11 @@ if [ -z "${ARKAOS_ROOT:-}" ]; then
 fi
 export ARKAOS_ROOT
 
-if ! command -v python3 &>/dev/null; then
+# ─── Shared Python resolver (exports ARKA_PY) ──────────────────────────
+_ARKA_LIB="$(dirname "${BASH_SOURCE[0]:-$0}")/_lib/arka_python.sh"
+if [ -f "$_ARKA_LIB" ]; then . "$_ARKA_LIB"; else ARKA_PY="python3"; fi
+
+if ! command -v "$ARKA_PY" >/dev/null 2>&1; then
   exit 0
 fi
 # Self-root fallback: the wrapper ships next to its python entrypoint, so
@@ -49,21 +53,8 @@ if [ ! -f "$ARKAOS_ROOT/core/hooks/stop.py" ]; then
   fi
 fi
 
-# Interpreter resolution: prefer the ArkaOS venv (has pyyaml/pydantic);
-# otherwise probe — an unrelated project venv first on PATH would give a
-# python3 without yaml and silently degrade every gate.
-_PY=""
-for _cand in "$HOME/.arkaos/venv/bin/python3" "$HOME/.arkaos/.venv/bin/python3"; do
-  if [ -x "$_cand" ]; then _PY="$_cand"; break; fi
-done
-if [ -z "$_PY" ]; then
-  _PY="python3"
-  if ! "$_PY" -c "import yaml" 2>/dev/null; then
-    for _cand in /opt/homebrew/bin/python3 /usr/local/bin/python3 /usr/bin/python3; do
-      if [ -x "$_cand" ] && "$_cand" -c "import yaml" 2>/dev/null; then _PY="$_cand"; break; fi
-    done
-  fi
-fi
+# Interpreter resolution handled by the shared resolver (ARKA_PY): prefers
+# the ArkaOS venv (has pyyaml/pydantic), falls back to a yaml-capable python3.
 PYTHONPATH="$ARKAOS_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
-  "$_PY" -m core.hooks.stop
+  "$ARKA_PY" -m core.hooks.stop
 exit 0

package/config/hooks/token-hygiene.sh

@@ -13,6 +13,10 @@
 
 set +e  # never fail
 
+# ─── Shared Python resolver (exports ARKA_PY) ──────────────────────────
+_ARKA_LIB="$(dirname "${BASH_SOURCE[0]:-$0}")/_lib/arka_python.sh"
+if [ -f "$_ARKA_LIB" ]; then . "$_ARKA_LIB"; else ARKA_PY="python3"; fi
+
 _prompt="${ARKA_PROMPT:-}"
 _transcript="${ARKA_TRANSCRIPT_PATH:-}"
 _suggestions=""
@@ -64,7 +68,7 @@ if [ -n "$_transcript" ] && [ -f "$_transcript" ] && [ -n "$_prompt" ]; then
   _cur_kw=$(_kw "$_prompt" | head -20)
   # pull last 3 user messages from transcript jsonl
   _prior=$(tail -n 200 "$_transcript" 2>/dev/null \
-    | python3 -c "
+    | "$ARKA_PY" -c "
 import sys, json
 msgs=[]
 for line in sys.stdin:

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

@@ -7,6 +7,10 @@
 
 input=$(cat)
 
+# ─── Shared Python resolver (exports ARKA_PY) ──────────────────────────
+_ARKA_LIB="$(dirname "${BASH_SOURCE[0]:-$0}")/_lib/arka_python.sh"
+if [ -f "$_ARKA_LIB" ]; then . "$_ARKA_LIB"; else ARKA_PY="python3"; fi
+
 # ─── V1 Migration Detection ─────────────────────────────────────────────
 V1_PATHS=("$HOME/.claude/skills/arka-os" "$HOME/.claude/skills/arkaos")
 MIGRATION_MARKER="$HOME/.arkaos/migrated-from-v1"
@@ -27,12 +31,12 @@ if [ -f "$ARKAOS_VERSION_FILE" ]; then
   if [ -f "$_REPO_PATH/VERSION" ]; then
     _CURRENT_VERSION=$(cat "$_REPO_PATH/VERSION")
   elif [ -f "$_REPO_PATH/package.json" ]; then
-    _CURRENT_VERSION=$(python3 -c "import json; print(json.load(open('$_REPO_PATH/package.json'))['version'])" 2>/dev/null || echo "")
+    _CURRENT_VERSION=$("$ARKA_PY" -c "import json; print(json.load(open('$_REPO_PATH/package.json'))['version'])" 2>/dev/null || echo "")
   fi
 
   if [ -n "${_CURRENT_VERSION:-}" ]; then
     if [ -f "$SYNC_STATE" ]; then
-      _SYNCED_VERSION=$(python3 -c "import json; print(json.load(open('$SYNC_STATE'))['version'])" 2>/dev/null || echo "none")
+      _SYNCED_VERSION=$("$ARKA_PY" -c "import json; print(json.load(open('$SYNC_STATE'))['version'])" 2>/dev/null || echo "none")
     else
       _SYNCED_VERSION="none"
     fi
@@ -53,9 +57,9 @@ if [ ! -f "$_SESSION_MARKER" ] && [ ! -f "/tmp/arkaos-greeted-today" ]; then
   _GREETING_COMPANY=""
   _GREETING_VERSION=""
 
-  if [ -f "$HOME/.arkaos/profile.json" ] && command -v python3 &>/dev/null; then
-    _GREETING_NAME=$(python3 -c "import json; p=json.load(open('$HOME/.arkaos/profile.json')); print(p.get('name', p.get('role', 'founder')))" 2>/dev/null)
-    _GREETING_COMPANY=$(python3 -c "import json; print(json.load(open('$HOME/.arkaos/profile.json')).get('company', ''))" 2>/dev/null)
+  if [ -f "$HOME/.arkaos/profile.json" ] && command -v "$ARKA_PY" >/dev/null 2>&1; then
+    _GREETING_NAME=$("$ARKA_PY" -c "import json; p=json.load(open('$HOME/.arkaos/profile.json')); print(p.get('name', p.get('role', 'founder')))" 2>/dev/null)
+    _GREETING_COMPANY=$("$ARKA_PY" -c "import json; print(json.load(open('$HOME/.arkaos/profile.json')).get('company', ''))" 2>/dev/null)
   fi
 
   if [ -f "$HOME/.arkaos/.repo-path" ]; then
@@ -111,12 +115,12 @@ fi
 python_result=""
 BRIDGE_SCRIPT="${ARKAOS_ROOT}/scripts/synapse-bridge.py"
 
-if command -v python3 &>/dev/null && [ -f "$BRIDGE_SCRIPT" ]; then
-  bridge_output=$(echo "{\"user_input\":$(echo "$user_input" | python3 -c "import sys,json; print(json.dumps(sys.stdin.read()))" 2>/dev/null || echo '""')}" \
-    | ARKAOS_ROOT="$ARKAOS_ROOT" python3 "$BRIDGE_SCRIPT" --root "$ARKAOS_ROOT" 2>/dev/null)
+if command -v "$ARKA_PY" >/dev/null 2>&1 && [ -f "$BRIDGE_SCRIPT" ]; then
+  bridge_output=$(echo "{\"user_input\":$(echo "$user_input" | "$ARKA_PY" -c "import sys,json; print(json.dumps(sys.stdin.read()))" 2>/dev/null || echo '""')}" \
+    | ARKAOS_ROOT="$ARKAOS_ROOT" "$ARKA_PY" "$BRIDGE_SCRIPT" --root "$ARKAOS_ROOT" 2>/dev/null)
 
   if [ -n "$bridge_output" ]; then
-    python_result=$(echo "$bridge_output" | python3 -c "import sys,json; print(json.loads(sys.stdin.read()).get('context_string',''))" 2>/dev/null)
+    python_result=$(echo "$bridge_output" | "$ARKA_PY" -c "import sys,json; print(json.loads(sys.stdin.read()).get('context_string',''))" 2>/dev/null)
   fi
 fi
 

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

@@ -34,9 +34,13 @@ if [ -z "${ARKAOS_ROOT:-}" ]; then
 fi
 export ARKAOS_ROOT
 
+# ─── Shared Python resolver (exports ARKA_PY) ──────────────────────────
+_ARKA_LIB="$(dirname "${BASH_SOURCE[0]:-$0}")/_lib/arka_python.sh"
+if [ -f "$_ARKA_LIB" ]; then . "$_ARKA_LIB"; else ARKA_PY="python3"; fi
+
 _ARKA_L0_FALLBACK='{"additionalContext": "[Constitution] NON-NEGOTIABLE: branch-isolation, obsidian-output, authority-boundaries, security-gate, context-first, solid-clean-code, spec-driven, human-writing, squad-routing, full-visibility, sequential-validation, mandatory-qa, arka-supremacy | QUALITY-GATE: marta-cqo, eduardo-copy, francisca-tech-ux | MUST: conventional-commits, test-coverage, pattern-matching, actionable-output, memory-persistence"}'
 
-if ! command -v python3 &>/dev/null; then
+if ! command -v "$ARKA_PY" >/dev/null 2>&1; then
   echo "$_ARKA_L0_FALLBACK"
   exit 0
 fi
@@ -54,20 +58,7 @@ if [ ! -f "$ARKAOS_ROOT/core/hooks/user_prompt_submit.py" ]; then
   fi
 fi
 
-# Interpreter resolution: prefer the ArkaOS venv (has pyyaml/pydantic);
-# otherwise probe — an unrelated project venv first on PATH would give a
-# python3 without yaml and silently degrade every gate.
-_PY=""
-for _cand in "$HOME/.arkaos/venv/bin/python3" "$HOME/.arkaos/.venv/bin/python3"; do
-  if [ -x "$_cand" ]; then _PY="$_cand"; break; fi
-done
-if [ -z "$_PY" ]; then
-  _PY="python3"
-  if ! "$_PY" -c "import yaml" 2>/dev/null; then
-    for _cand in /opt/homebrew/bin/python3 /usr/local/bin/python3 /usr/bin/python3; do
-      if [ -x "$_cand" ] && "$_cand" -c "import yaml" 2>/dev/null; then _PY="$_cand"; break; fi
-    done
-  fi
-fi
+# Interpreter resolution handled by the shared resolver (ARKA_PY): prefers
+# the ArkaOS venv (has pyyaml/pydantic), falls back to a yaml-capable python3.
 PYTHONPATH="$ARKAOS_ROOT${PYTHONPATH:+:$PYTHONPATH}" \
-  exec "$_PY" -m core.hooks.user_prompt_submit
+  exec "$ARKA_PY" -m core.hooks.user_prompt_submit

package/core/workflow/state_reader.sh

@@ -5,6 +5,13 @@
 # Dependencies: jq (required)
 # ============================================================================
 
+# ─── Shared Python resolver (exports ARKA_PY) ──────────────────────────
+# The lib is not a sibling here; try the in-repo path then the installed tree.
+for _l in "$(dirname "${BASH_SOURCE[0]:-$0}")/../../config/hooks/_lib/arka_python.sh" "$HOME/.arkaos/config/hooks/_lib/arka_python.sh"; do
+  if [ -f "$_l" ]; then . "$_l"; break; fi
+done
+: "${ARKA_PY:=python3}"
+
 STATE_FILE="$HOME/.arkaos/workflow-state.json"
 
 if [ ! -f "$STATE_FILE" ]; then
@@ -73,11 +80,11 @@ case "$CMD" in
       echo "none"
       exit 0
     fi
-    if command -v python3 &>/dev/null; then
-      _F_NAME=$(FORGE_FILE="$_FORGE_FILE" python3 -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(d.get('name',''))" 2>/dev/null)
-      _F_STATUS=$(FORGE_FILE="$_FORGE_FILE" python3 -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(d.get('status',''))" 2>/dev/null)
-      _F_PHASES=$(FORGE_FILE="$_FORGE_FILE" python3 -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(len(d.get('plan_phases',[])))" 2>/dev/null)
-      _F_BRANCH=$(FORGE_FILE="$_FORGE_FILE" python3 -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(d.get('governance',{}).get('branch_strategy',''))" 2>/dev/null)
+    if command -v "$ARKA_PY" >/dev/null 2>&1; then
+      _F_NAME=$(FORGE_FILE="$_FORGE_FILE" "$ARKA_PY" -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(d.get('name',''))" 2>/dev/null)
+      _F_STATUS=$(FORGE_FILE="$_FORGE_FILE" "$ARKA_PY" -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(d.get('status',''))" 2>/dev/null)
+      _F_PHASES=$(FORGE_FILE="$_FORGE_FILE" "$ARKA_PY" -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(len(d.get('plan_phases',[])))" 2>/dev/null)
+      _F_BRANCH=$(FORGE_FILE="$_FORGE_FILE" "$ARKA_PY" -c "import yaml,os; d=yaml.safe_load(open(os.environ['FORGE_FILE'])); print(d.get('governance',{}).get('branch_strategy',''))" 2>/dev/null)
       echo "${_FORGE_ID}|${_F_NAME}|${_F_STATUS}|${_F_PHASES}|${_F_BRANCH}"
     else
       echo "${_FORGE_ID}|||0|"

package/departments/ops/skills/update/SKILL.md

@@ -23,7 +23,7 @@ Hybrid sync engine: Python handles deterministic operations (MCPs, settings, des
 
 1. **One-stop: npm refresh + engine (PR61 v2.78.0 orchestrator).**
    ```bash
-   cd $ARKAOS_ROOT && python -m core.sync.update_orchestrator --home ~/.arkaos --skills ~/.claude/skills --output json
+   cd $ARKAOS_ROOT && ~/.arkaos/bin/arka-py -m core.sync.update_orchestrator --home ~/.arkaos --skills ~/.claude/skills --output json
    ```
    The orchestrator detects whether the running ArkaOS is behind npm
    latest. When stale, it shells out to `npx arkaos@latest update`
@@ -38,7 +38,7 @@ Hybrid sync engine: Python handles deterministic operations (MCPs, settings, des
    silently skips the npm step and falls through to the engine.
 
    Fallback (no orchestrator): the underlying engine still runs the
-   same way via `python -m core.sync.engine ...` for callers that
+   same way via `~/.arkaos/bin/arka-py -m core.sync.engine ...` for callers that
    don't need the version-drift gate.
 
 2. **Phase 4 (intelligent, AI subagent):** After the engine completes, dispatch ONE subagent with the engine's JSON report + the feature registry (`core/sync/features/*.yaml`). The subagent injects/removes feature sections in each `~/.claude/skills/arka-{ecosystem}/SKILL.md` while preserving all custom content.

package/departments/ops/skills/update/references/sync-engine.md

@@ -7,7 +7,7 @@ Referenced from SKILL.md. Read only when needed.
 Run the sync engine from the ArkaOS repo root:
 
 ```bash
-cd $ARKAOS_ROOT && python -m core.sync.engine --home ~/.arkaos --skills ~/.claude/skills --output json
+cd $ARKAOS_ROOT && ~/.arkaos/bin/arka-py -m core.sync.engine --home ~/.arkaos --skills ~/.claude/skills --output json
 ```
 
 The engine handles deterministic operations and returns a JSON report.

package/departments/quality/SKILL.md

@@ -24,7 +24,7 @@ Any Department Workflow:
   ...
   Phase N-1: QUALITY GATE
     1. Run the evidence engine over the project/diff:
-         python -m core.governance.evidence_checks <project_dir> \
+         ~/.arkaos/bin/arka-py -m core.governance.evidence_checks <project_dir> \
            [--changed-files f1,f2] [--test-command '...'] --json
     2. Marta dispatches Eduardo + Francisca to INTERPRET the report:
        - Eduardo: spellcheck section + prose review of changed copy

package/installer/index.js

@@ -165,6 +165,12 @@ export async function install({ runtime, path, force, skipSystem, withOllama })
       copyFileSync(cmdSrc, join(binDir, "arka-claude.cmd"));
       installed = true;
     }
+    // arka-py — the ArkaOS Python entrypoint SKILL.md commands invoke.
+    const pyPsSrc  = join(ARKAOS_ROOT, "bin", "arka-py.ps1");
+    const pyCmdSrc = join(ARKAOS_ROOT, "bin", "arka-py.cmd");
+    if (existsSync(pyPsSrc))  copyFileSync(pyPsSrc,  join(binDir, "arka-py.ps1"));
+    if (existsSync(pyCmdSrc)) copyFileSync(pyCmdSrc, join(binDir, "arka-py.cmd"));
+    if (existsSync(pyPsSrc) || existsSync(pyCmdSrc)) ok("arka-py interpreter shim installed (.cmd + .ps1)");
     if (installed) {
       ok("arka-claude wrapper installed (.cmd + .ps1)");
       console.log(`         Add to PATH: setx PATH "%PATH%;%USERPROFILE%\\.arkaos\\bin"`);
@@ -179,6 +185,14 @@ export async function install({ runtime, path, force, skipSystem, withOllama })
       console.log(`         Add to PATH: export PATH="$HOME/.arkaos/bin:$PATH"`);
       console.log(`         Optional alias: alias claude="arka-claude"`);
     }
+    // arka-py — the ArkaOS Python entrypoint SKILL.md commands invoke so the
+    // agent never runs a bare `python` that lacks ArkaOS deps (pyyaml, ...).
+    const arkaPySrc = join(ARKAOS_ROOT, "bin", "arka-py");
+    if (existsSync(arkaPySrc)) {
+      copyFileSync(arkaPySrc, join(binDir, "arka-py"));
+      try { chmodSync(join(binDir, "arka-py"), 0o755); } catch {}
+      ok("arka-py interpreter shim installed");
+    }
   }
   const claudeMdSrc = join(ARKAOS_ROOT, "config", "user-claude.md");
   const userClaudeMd = join(homedir(), ".claude", "CLAUDE.md");

package/installer/update.js

@@ -248,6 +248,13 @@ export async function update() {
     if (existsSync(psSrc) || existsSync(cmdSrc)) {
       console.log("         ✓ arka-claude wrapper updated (.cmd + .ps1)");
     }
+    const pyPsSrc  = join(ARKAOS_ROOT, "bin", "arka-py.ps1");
+    const pyCmdSrc = join(ARKAOS_ROOT, "bin", "arka-py.cmd");
+    if (existsSync(pyPsSrc))  copyFileSync(pyPsSrc,  join(binDir, "arka-py.ps1"));
+    if (existsSync(pyCmdSrc)) copyFileSync(pyCmdSrc, join(binDir, "arka-py.cmd"));
+    if (existsSync(pyPsSrc) || existsSync(pyCmdSrc)) {
+      console.log("         ✓ arka-py interpreter shim updated (.cmd + .ps1)");
+    }
   } else {
     const wrapperSrc = join(ARKAOS_ROOT, "bin", "arka-claude");
     if (existsSync(wrapperSrc)) {
@@ -255,6 +262,12 @@ export async function update() {
       try { chmodSync(join(binDir, "arka-claude"), 0o755); } catch {}
       console.log("         ✓ arka-claude wrapper updated");
     }
+    const arkaPySrc = join(ARKAOS_ROOT, "bin", "arka-py");
+    if (existsSync(arkaPySrc)) {
+      copyFileSync(arkaPySrc, join(binDir, "arka-py"));
+      try { chmodSync(join(binDir, "arka-py"), 0o755); } catch {}
+      console.log("         ✓ arka-py interpreter shim updated");
+    }
   }
   const userClaudeMd = join(homedir(), ".claude", "CLAUDE.md");
   const claudeMdSrc = join(ARKAOS_ROOT, "config", "user-claude.md");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "4.3.1",
+  "version": "4.3.2",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {
@@ -58,5 +58,8 @@
     "CONSTITUTION.md",
     "README.md",
     "LICENSE"
-  ]
+  ],
+  "devDependencies": {
+    "eslint": "^8.57.1"
+  }
 }

package/pyproject.toml

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

package/scripts/seed_initial_patterns.py

@@ -175,7 +175,7 @@ def main() -> int:
     for card in _INITIAL_PATTERNS:
         record_pattern(card)
     print(f"Seeded {len(_INITIAL_PATTERNS)} pattern cards.")
-    print("Inspect: python -m core.knowledge.pattern_cards_cli list")
+    print("Inspect: ~/.arkaos/bin/arka-py -m core.knowledge.pattern_cards_cli list")
     return 0