arkaos 4.3.1 → 4.3.3

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