bigpowers 2.68.4 → 2.68.6

package/.pi/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.68.4",
+  "version": "2.68.6",
   "description": "75 skills — 73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "keywords": [
     "pi-package"

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [2.68.6](https://github.com/danielvm-git/bigpowers/compare/v2.68.5...v2.68.6) (2026-07-06)
+
+
+### Bug Fixes
+
+* **ci:** retry GitHub Pages deploy on transient API failure ([fe15c20](https://github.com/danielvm-git/bigpowers/commit/fe15c209f4184ea3473e7f2504ec3466321c4245))
+
+## [2.68.5](https://github.com/danielvm-git/bigpowers/compare/v2.68.4...v2.68.5) (2026-07-06)
+
+
+### Bug Fixes
+
+* **bug:** python-interpreter-fragility — wire python-env.sh into 29 scripts ([1088995](https://github.com/danielvm-git/bigpowers/commit/10889957c5b4fb07fe2be5f4624a3608461802c7))
+
 ## [2.68.4](https://github.com/danielvm-git/bigpowers/compare/v2.68.3...v2.68.4) (2026-07-06)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bigpowers",
-  "version": "2.68.4",
+  "version": "2.68.6",
   "description": "73 agent skills synthesizing 17 years of software engineering discipline into a prescriptive methodology for solo developers",
   "main": "index.js",
   "scripts": {

package/scripts/bp-opensrc-check.sh

@@ -3,6 +3,7 @@
 # Usage: bash scripts/bp-opensrc-check.sh [package.json|requirements.txt]
 # Output: one line per dependency — FOUND or NOT CACHED, with local path when found.
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 
 INPUT="${1:-package.json}"
 
@@ -20,7 +21,7 @@ extract_deps() {
   local file="$1"
   case "$file" in
     *.json)
-      python3 -c "
+      $PYTHON -c "
 import json, sys
 data = json.load(open('$file'))
 deps = list(data.get('dependencies', {}).keys()) + list(data.get('devDependencies', {}).keys())

package/scripts/bp-timing.sh

@@ -2,8 +2,9 @@
 # bp-timing.sh — Record skill invocation timings for stocktake effectiveness analysis.
 # Usage: bash scripts/bp-timing.sh start <skill-name>
 #        bash scripts/bp-timing.sh end <skill-name>
-# Requires: python3 (for YAML-safe state updates)
+# Requires: $PYTHON (for YAML-safe state updates)
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 
 STATE_YAML="specs/state.yaml"
 TIMINGS_KEY="metrics.skill_timings"
@@ -21,7 +22,7 @@ SKILL="$2"
 case "$ACTION" in
   start)
     STAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-    python3 -c "
+    $PYTHON -c "
 import yaml, sys
 try:
     with open('$STATE_YAML') as f:
@@ -42,7 +43,7 @@ with open('$STATE_YAML', 'w') as f:
 
   end)
     STAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
-    python3 -c "
+    $PYTHON -c "
 import yaml
 from datetime import datetime
 

package/scripts/bp-yaml-set.sh

@@ -2,7 +2,8 @@
 # bp-yaml-set.sh — patch a dotted key in a specs YAML file
 # Usage: bp-yaml-set.sh <file> <dotted.key> <value>
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 FILE="${1:?file}"
 KEY="${2:?dotted.key}"
 VAL="${3:?value}"
-python3 "$REPO_ROOT/scripts/yaml-tools.py" set "$FILE" "$KEY" "$VAL"
+$PYTHON "$REPO_ROOT/scripts/yaml-tools.py" set "$FILE" "$KEY" "$VAL"

package/scripts/build-receipts.sh

@@ -2,11 +2,12 @@
 # story: e41s01
 # build-receipts.sh — aggregate all quality evidence into specs/receipts.json.
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || { echo "build-receipts: not inside a git repo" >&2; exit 1; }
 OUTFILE="$ROOT/specs/receipts.json"
 TIMESTAMP="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 emit_json() {
-  python3 -c "
+  $PYTHON -c "
 import json, sys, os, subprocess, glob as gb
 sections = {}
 

package/scripts/build-skill-graph.sh

@@ -4,6 +4,7 @@
 #   - specs/skill-graph.json    — machine-readable dependency graph
 #   - specs/skills-wiki/        — OKF wiki with per-skill pages
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
@@ -41,7 +42,7 @@ TMP_NODES=$(mktemp)
 TMP_EDGES=$(mktemp)
 TMP_ALL=$(mktemp)
 
-python3 -c "
+$PYTHON -c "
 import json, sys
 
 nodes = {}
@@ -68,7 +69,7 @@ with open('$GRAPH_JSONL') as f:
 print(json.dumps(list(nodes.values()), indent=2))
 " > "$TMP_NODES"
 
-python3 -c "
+$PYTHON -c "
 import json
 # re-read edges into a separate file
 edges = []
@@ -86,7 +87,7 @@ print(json.dumps(edges, indent=2))
 " > "$TMP_EDGES"
 
 # --- Write skill-graph.json ---
-python3 -c "
+$PYTHON -c "
 import json
 
 with open('$TMP_NODES') as f:
@@ -133,7 +134,7 @@ context: benchmark
 WEOF
 
 # Generate one .md per skill
-python3 -c "
+$PYTHON -c "
 import json, os
 
 # Re-read nodes

package/scripts/check-blind-spots.sh

@@ -10,6 +10,7 @@
 # Severities: HIGH / MEDIUM / LOW. Exit 1 on HIGH findings.
 
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 
 BLIND_SPOTS_JSON="$REPO_ROOT/specs/blind-spots.json"
 EXEC_STATUS="$REPO_ROOT/specs/execution-status.yaml"
@@ -47,5 +48,5 @@ if [[ ! -f "$EXEC_STATUS" ]]; then
   exit 1
 fi
 
-exec python3 "$(dirname "${BASH_SOURCE[0]}")/lib/blind-spots.py" \
+exec $PYTHON "$(dirname "${BASH_SOURCE[0]}")/lib/blind-spots.py" \
   "$REPO_ROOT" "$BLIND_SPOTS_JSON" "$EXEC_STATUS" "$MATRIX_JSON" "$VERIFICATIONS_DIR" "$EPICS_DIR"

package/scripts/check-spec-drift.sh

@@ -3,6 +3,7 @@
 # Compare spec-file mtimes against implementing source-file mtimes,
 # mark suspect links, write to specs/drift-report.json
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
@@ -32,7 +33,7 @@ if [ ! -f "$TRACE_MATRIX" ]; then
   exit 1
 fi
 
-python3 -c "
+$PYTHON -c "
 import json, os, sys
 
 with open('$TRACE_MATRIX') as f:

package/scripts/check-spec-version-gap.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 # check-spec-version-gap.sh — detect spec format gap (e44s02)
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 BP_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 
@@ -33,12 +34,12 @@ emit_json() {
 }
 
 get_installed_version() {
-  python3 -c "import json; d=json.load(open('$BP_ROOT/package.json')); print(d.get('version','unknown'))" 2>/dev/null || echo "unknown"
+  $PYTHON -c "import json; d=json.load(open('$BP_ROOT/package.json')); print(d.get('version','unknown'))" 2>/dev/null || echo "unknown"
 }
 
 yaml_get() {
   [[ ! -f "$1" ]] && { echo ""; return; }
-  python3 -c "
+  $PYTHON -c "
 import sys, yaml
 d = yaml.safe_load(open('$1')) or {}
 parts = '$2'.split('.')
@@ -64,7 +65,7 @@ version_lt() {
 find_migrations() {
   local ver="$1" reg="$BP_ROOT/specs/migrations/registry.okf.md"
   [[ ! -f "$reg" ]] && { echo "[]"; return; }
-  python3 -c "
+  $PYTHON -c "
 import json, yaml
 def vt(v): return tuple(int(p) if p.isdigit() else 0 for p in v.lstrip('v').split('.')[:3])
 dt = vt('$ver')
@@ -108,8 +109,8 @@ if [[ -n "$SV" && "$SV" != "null" && "$SV" != "None" ]]; then
     exit 0
   fi
   APP=$(find_migrations "$SV")
-  CNT=$(echo "$APP" | python3 -c "import json,sys; print(len(json.load(sys.stdin)))" 2>/dev/null || echo 0)
-  emit_json "$(python3 -c "import json; a=json.loads('''$APP'''); print(json.dumps({'gap':True,'stamp':True,'detected_version':'$SV','detection_method':'stamp','installed_version':'$IV','applicable_migrations':len(a),'migration_ids':[m['id'] for m in a],'confidence':'high','active_work_blocked':False}))")"
+  CNT=$(echo "$APP" | $PYTHON -c "import json,sys; print(len(json.load(sys.stdin)))" 2>/dev/null || echo 0)
+  emit_json "$($PYTHON -c "import json; a=json.loads('''$APP'''); print(json.dumps({'gap':True,'stamp':True,'detected_version':'$SV','detection_method':'stamp','installed_version':'$IV','applicable_migrations':len(a),'migration_ids':[m['id'] for m in a],'confidence':'high','active_work_blocked':False}))")"
   exit 1
 fi
 
@@ -136,8 +137,8 @@ if [[ "$DV" != "unknown" ]] && ! version_lt "$DV" "$IV"; then
 fi
 
 APP=$(find_migrations "$DV")
-CNT=$(echo "$APP" | python3 -c "import json,sys; print(len(json.load(sys.stdin)))" 2>/dev/null || echo 0)
-MJ=$(printf '%s\n' "${MARKERS[@]}" | python3 -c "import json,sys; print(json.dumps([l.strip() for l in sys.stdin if l.strip()]))" 2>/dev/null || echo "[]")
+CNT=$(echo "$APP" | $PYTHON -c "import json,sys; print(len(json.load(sys.stdin)))" 2>/dev/null || echo 0)
+MJ=$(printf '%s\n' "${MARKERS[@]}" | $PYTHON -c "import json,sys; print(json.dumps([l.strip() for l in sys.stdin if l.strip()]))" 2>/dev/null || echo "[]")
 
-emit_json "$(python3 -c "import json; a=json.loads('''$APP'''); m=json.loads('''$MJ'''); print(json.dumps({'gap':True,'stamp':False,'detected_version':'$DV','detection_method':'fingerprint','installed_version':'$IV','applicable_migrations':len(a),'migration_ids':[x['id'] for x in a],'confidence':'$CONF','active_work_blocked':False,'matched_markers':m}))")"
+emit_json "$($PYTHON -c "import json; a=json.loads('''$APP'''); m=json.loads('''$MJ'''); print(json.dumps({'gap':True,'stamp':False,'detected_version':'$DV','detection_method':'fingerprint','installed_version':'$IV','applicable_migrations':len(a),'migration_ids':[x['id'] for x in a],'confidence':'$CONF','active_work_blocked':False,'matched_markers':m}))")"
 exit 1

package/scripts/check-stale-locks.sh

@@ -2,6 +2,7 @@
 # story: e39s02
 # Validate that no agent lock in specs/agent-locks.yaml is >24h old.
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 
 LOCK_FILE="specs/agent-locks.yaml"
 if [ ! -f "$LOCK_FILE" ]; then
@@ -9,7 +10,7 @@ if [ ! -f "$LOCK_FILE" ]; then
   exit 0
 fi
 
-python3 -c "
+$PYTHON -c "
 import yaml, datetime, sys
 
 now = datetime.datetime.now(datetime.timezone.utc)

package/scripts/convert-legado.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env bash
 # convert-legado.sh — RELEASE-PLAN.md + SCOPE.md → YAML layout (one-time migration helper)
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 SPECS="$REPO_ROOT/specs"
 RP_MD="$SPECS/RELEASE-PLAN.md"
 SCOPE_MD="$SPECS/SCOPE.md"
@@ -26,7 +27,7 @@ archive_if_needed() {
 }
 
 # Parse ### WSn — Title · WSJF X.X from RELEASE-PLAN.md
-python3 - "$RP_MD" "$SPECS" <<'PY'
+$PYTHON - "$RP_MD" "$SPECS" <<'PY'
 import json
 import re
 import sys
@@ -112,7 +113,7 @@ fi
 # requirements/SCOPE stub from SCOPE.md if missing
 if [[ -f "$SCOPE_MD" && ! -f "$SPECS/requirements/SCOPE_LATEST.yaml" ]]; then
   mkdir -p "$SPECS/requirements"
-  python3 - "$SCOPE_MD" "$SPECS/requirements/SCOPE_LATEST.yaml" <<'PY'
+  $PYTHON - "$SCOPE_MD" "$SPECS/requirements/SCOPE_LATEST.yaml" <<'PY'
 import sys
 from pathlib import Path
 src = Path(sys.argv[1]).read_text(encoding="utf-8")

package/scripts/decompose-conventions.sh

@@ -2,6 +2,7 @@
 # story: e39s05
 # Decompose CONVENTIONS.md into specs/conventions-wiki/ OKF concept bundle
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
@@ -51,7 +52,7 @@ context: conventions
 IDXEOF
 
 # Parse CONVENTIONS.md headings into sections
-python3 -c "
+$PYTHON -c "
 import re, os, json
 
 with open('$CONVENTIONS') as f:

package/scripts/enrich-epics-from-archive.sh

@@ -1,10 +1,11 @@
 #!/usr/bin/env bash
 # enrich-epics-from-archive.sh — populate specs/epics from archive RELEASE-PLAN.md
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 ARCHIVE="${1:-$REPO_ROOT/specs/archive/RELEASE-PLAN.md}"
 SPECS="$REPO_ROOT/specs"
 
-python3 - "$ARCHIVE" "$SPECS" <<'PY'
+$PYTHON - "$ARCHIVE" "$SPECS" <<'PY'
 import json
 import re
 import sys

package/scripts/generate-adr-wiki.sh

@@ -2,6 +2,7 @@
 # story: e45s01 e45s06
 # generate-adr-wiki.sh — emit OKF concept bundles from specs/adr/*.md
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 ADRS="$ROOT/specs/adr"
@@ -30,7 +31,7 @@ for adr_file in "$ADRS"/*.md; do
   # Parse YAML frontmatter if present
   fm="{}"
   if head -1 "$adr_file" 2>/dev/null | grep -q '^---$'; then
-    fm=$(python3 -c "
+    fm=$($PYTHON -c "
 import sys, yaml, json
 content = open('$adr_file').read()
 parts = content.split('---')
@@ -43,9 +44,9 @@ if len(parts) >= 3:
 " 2>/dev/null) || fm="{}"
   fi
 
-  title=$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('title',''))" 2>/dev/null || echo "")
-  status=$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('status','accepted'))" 2>/dev/null || echo "accepted")
-  decision=$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('decision',''))" 2>/dev/null || echo "")
+  title=$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('title',''))" 2>/dev/null || echo "")
+  status=$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('status','accepted'))" 2>/dev/null || echo "accepted")
+  decision=$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('decision',''))" 2>/dev/null || echo "")
 
   # Fallback title from first heading
   if [ -z "$title" ]; then

package/scripts/generate-agent-guide.sh

@@ -2,6 +2,7 @@
 # story: e39s06
 # Decompose CLAUDE.md into specs/agent-guide/ for progressive disclosure
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
@@ -36,7 +37,7 @@ fi
 
 mkdir -p "$AGENT_GUIDE"
 
-python3 -c "
+$PYTHON -c "
 import re, os
 
 with open('$CLAUDE_MD') as f:

package/scripts/generate-reference-tables.sh

@@ -3,6 +3,7 @@
 # from live */SKILL.md frontmatter. Run after any SKILL.md addition/rename.
 # Called by sync-skills.sh and npm version hooks.
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 
 REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 TARGET="$REPO_ROOT/docs/references/model-profiles.md"
@@ -44,7 +45,7 @@ Total: **$TOTAL** skills — verify with \`find . skills -maxdepth 2 -name SKILL
 # --- 3. Splice block into target file ---
 # Replace between marker comments if they exist; otherwise append.
 if grep -q "AUTO-GENERATED-CATALOG: begin" "$TARGET"; then
-  python3 - "$TARGET" "$BLOCK" <<'PYEOF'
+  $PYTHON - "$TARGET" "$BLOCK" <<'PYEOF'
 import sys, re
 path = sys.argv[1]
 block = sys.argv[2]

package/scripts/generate-viz-graph.sh

@@ -2,11 +2,12 @@
 # story: e45s04
 # generate-viz-graph.sh — build specs/viz.html from bigpowers-mcp/graph.jsonl
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 GRAPH="$ROOT/bigpowers-mcp/graph.jsonl"
 OUT="$ROOT/specs/viz.html"
 
-ENTITIES_JSON=$(python3 -c "
+ENTITIES_JSON=$($PYTHON -c "
 import json, sys
 entities = []
 with open('$GRAPH') as f:
@@ -17,7 +18,7 @@ with open('$GRAPH') as f:
 print(json.dumps(entities))
 ")
 
-EDGES_JSON=$(python3 -c "
+EDGES_JSON=$($PYTHON -c "
 import json, sys
 edges = []
 with open('$GRAPH') as f:
@@ -28,7 +29,7 @@ with open('$GRAPH') as f:
 print(json.dumps(edges))
 ")
 
-python3 - "$ENTITIES_JSON" "$EDGES_JSON" "$OUT" << 'PY'
+$PYTHON - "$ENTITIES_JSON" "$EDGES_JSON" "$OUT" << 'PY'
 import sys, json
 
 entities_json = sys.argv[1]

package/scripts/golden-g09-yaml-roundtrip.sh

@@ -17,6 +17,7 @@
 # Exit 1: round trip destroyed structure (corruption bug is back)
 
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
 resolve_repo_root
 
@@ -38,10 +39,10 @@ WORKDIR="$(mktemp -d)"
 trap 'rm -rf "$WORKDIR"' EXIT
 cp "$FIXTURE" "$WORKDIR/sample.yaml"
 
-python3 "$TOOL" set "$WORKDIR/sample.yaml" release.version "9.9.9-test"
+$PYTHON "$TOOL" set "$WORKDIR/sample.yaml" release.version "9.9.9-test"
 
 set +e
-RESULT="$(python3 -c "
+RESULT="$($PYTHON -c "
 import sys, yaml
 
 try:

package/scripts/golden-g10-trace-anti-vacuity.sh

@@ -13,6 +13,7 @@
 # Exit 1: trace-stories.py passed vacuously on the degenerate fixture (fail-open risk)
 
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
 resolve_repo_root
 
@@ -38,7 +39,7 @@ OKF_DIR=$(mktemp -d)
 trap 'rm -f "$MATRIX_JSON" "$TRACE_MD"; rm -rf "$OKF_DIR"' EXIT
 
 set +e
-actual_output=$(python3 "$TRACE_ENGINE" "$FIXTURE_DIR" "$MATRIX_JSON" "$TRACE_MD" "$OKF_DIR" 1 "" 2>&1)
+actual_output=$($PYTHON "$TRACE_ENGINE" "$FIXTURE_DIR" "$MATRIX_JSON" "$TRACE_MD" "$OKF_DIR" 1 "" 2>&1)
 actual_exit=$?
 set -e
 source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"

package/scripts/migrate-version.sh

@@ -3,6 +3,7 @@
 # migrate-version.sh — one-shot ordered migration engine with triple safety net.
 # Safety: (1) backup, (2) dry-run diff, (3) auto-commit.
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
@@ -40,7 +41,7 @@ installed_version() {
 
 yaml_get() {
   local file="$1" key="$2"
-  python3 -c "
+  $PYTHON -c "
 import yaml, sys
 try:
     d = yaml.safe_load(open('$file'))
@@ -157,7 +158,7 @@ fi
 # ── build migration plan ──────────────────────────────────────────────────
 echo "migrate-version: building migration plan from $REGISTRY …"
 
-MIGRATION_PLAN="$(python3 -c "
+MIGRATION_PLAN="$($PYTHON -c "
 import yaml, json, sys
 
 with open('$REGISTRY') as f:
@@ -181,7 +182,7 @@ applicable = [m for m in plan if m['since_version'] > detected and m['since_vers
 print(json.dumps(applicable))
 " 2>/dev/null)"
 
-MIGRATION_COUNT="$(echo "$MIGRATION_PLAN" | python3 -c "import json,sys; print(len(json.load(sys.stdin)))" 2>/dev/null)"
+MIGRATION_COUNT="$(echo "$MIGRATION_PLAN" | $PYTHON -c "import json,sys; print(len(json.load(sys.stdin)))" 2>/dev/null)"
 
 if [ "${MIGRATION_COUNT:-0}" -eq 0 ]; then
   echo "migrate-version: no applicable migrations for $DETECTED → $INSTALLED — stamping version only"
@@ -190,7 +191,7 @@ fi
 echo "migrate-version: $MIGRATION_COUNT migration(s) to apply"
 
 if [ "$VERBOSE" = "true" ]; then
-  echo "$MIGRATION_PLAN" | python3 -c "
+  echo "$MIGRATION_PLAN" | $PYTHON -c "
 import json,sys
 for m in json.load(sys.stdin):
     print(f\"  {m['order']}. {m['id']}: {m['title']} (since {m['since_version']})\")
@@ -216,7 +217,7 @@ if [ "$DRY_RUN" = "true" ]; then
   echo "Detected version: $DETECTED"
   echo "Target version:   $INSTALLED"
   echo "Migrations:"
-  echo "$MIGRATION_PLAN" | python3 -c "
+  echo "$MIGRATION_PLAN" | $PYTHON -c "
 import json,sys
 for m in json.load(sys.stdin):
     deps = m.get('depends_on', [])
@@ -226,7 +227,7 @@ for m in json.load(sys.stdin):
 
   echo ""
   echo "Transforms preview:"
-  echo "$MIGRATION_PLAN" | python3 -c "
+  echo "$MIGRATION_PLAN" | $PYTHON -c "
 import json, sys, os
 for m in json.load(sys.stdin):
     bundle_path = os.path.join('$MIGRATIONS_DIR', m['file'])
@@ -287,15 +288,15 @@ apply_transform() {
   case "$action" in
     convert_md_to_yaml)
       local src tgt hm unc_count arch
-      src="$(echo "$tjson" | python3 -c "import json,sys; print(json.load(sys.stdin).get('source',''))")"
-      tgt="$(echo "$tjson" | python3 -c "import json,sys; print(json.load(sys.stdin).get('target',''))")"
-      arch="$(echo "$tjson" | python3 -c "import json,sys; print(json.load(sys.stdin).get('archive_source','false'))" 2>/dev/null)" || arch="false"
+      src="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('source',''))")"
+      tgt="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('target',''))")"
+      arch="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('archive_source','false'))" 2>/dev/null)" || arch="false"
       if [ ! -f "$REPO_ROOT/$src" ]; then
         log_skip "$action: source '$src' not found"
         SKIPPED+=("$action:$src"); return
       fi
-      hm="$(echo "$tjson" | python3 -c "import json,sys; print(json.dumps(json.load(sys.stdin).get('heuristic_map',{})))")"
-      python3 -c "
+      hm="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.dumps(json.load(sys.stdin).get('heuristic_map',{})))")"
+      $PYTHON -c "
 import json, re, yaml, sys, os
 src = '$REPO_ROOT/$src'
 tgt = '$REPO_ROOT/$tgt'
@@ -320,7 +321,7 @@ os.makedirs(os.path.dirname(tgt), exist_ok=True)
 with open(tgt, 'w') as f:
     yaml.safe_dump(result, f, sort_keys=False, allow_unicode=True, width=100)
 "
-      unc_count="$(echo "$tjson" | python3 -c "import json,sys; print(len(json.load(sys.stdin).get('uncertainty',[])))")"
+      unc_count="$(echo "$tjson" | $PYTHON -c "import json,sys; print(len(json.load(sys.stdin).get('uncertainty',[])))")"
       UNCERTAINTY_COUNT=$((UNCERTAINTY_COUNT + unc_count))
       # Archive source file if requested
       if [ "$arch" = "true" ] || [ "$arch" = "True" ]; then
@@ -335,8 +336,8 @@ with open(tgt, 'w') as f:
 
     rename_file)
       local src tgt
-      src="$(echo "$tjson" | python3 -c "import json,sys; print(json.load(sys.stdin).get('source',''))")"
-      tgt="$(echo "$tjson" | python3 -c "import json,sys; print(json.load(sys.stdin).get('target',''))")"
+      src="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('source',''))")"
+      tgt="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('target',''))")"
       if [ ! -e "$REPO_ROOT/$src" ]; then
         log_skip "$action: source '$src' not found — idempotent"
         SKIPPED+=("$action:$src"); return
@@ -352,8 +353,8 @@ with open(tgt, 'w') as f:
 
     move_file)
       local src tgt
-      src="$(echo "$tjson" | python3 -c "import json,sys; print(json.load(sys.stdin).get('source',''))")"
-      tgt="$(echo "$tjson" | python3 -c "import json,sys; print(json.load(sys.stdin).get('target',''))")"
+      src="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('source',''))")"
+      tgt="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('target',''))")"
       if [ ! -e "$REPO_ROOT/$src" ]; then
         log_skip "$action: source '$src' not found"
         SKIPPED+=("$action:$src"); return
@@ -369,7 +370,7 @@ with open(tgt, 'w') as f:
 
     delete_file)
       local path
-      path="$(echo "$tjson" | python3 -c "import json,sys; print(json.load(sys.stdin).get('path',''))")"
+      path="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('path',''))")"
       if [ ! -e "$REPO_ROOT/$path" ]; then
         log_skip "$action: '$path' not found — idempotent"
         SKIPPED+=("$action:$path"); return
@@ -380,10 +381,10 @@ with open(tgt, 'w') as f:
 
     set_yaml_key)
       local file key val if_missing
-      file="$(echo "$tjson" | python3 -c "import json,sys; print(json.load(sys.stdin).get('file',''))")"
-      key="$(echo "$tjson" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('path') or d.get('key',''))")"
-      val="$(echo "$tjson" | python3 -c "import json,sys; print(json.load(sys.stdin).get('value',''))")"
-      if_missing="$(echo "$tjson" | python3 -c "import json,sys; print(json.load(sys.stdin).get('if_missing','false'))" 2>/dev/null)" || if_missing="false"
+      file="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('file',''))")"
+      key="$(echo "$tjson" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('path') or d.get('key',''))")"
+      val="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('value',''))")"
+      if_missing="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('if_missing','false'))" 2>/dev/null)" || if_missing="false"
       if [ "$if_missing" = "true" ] || [ "$if_missing" = "True" ]; then
         if yaml_get "$REPO_ROOT/$file" "$key" >/dev/null 2>&1; then
           log_skip "$action: $file $key already set (if_missing=true) — idempotent"
@@ -391,22 +392,22 @@ with open(tgt, 'w') as f:
           return
         fi
       fi
-      python3 "$YAML_TOOLS" set "$REPO_ROOT/$file" "$key" "$val"
+      $PYTHON "$YAML_TOOLS" set "$REPO_ROOT/$file" "$key" "$val"
       log_done "$action: $file $key = $val"
       ;;
 
     rename_yaml_key)
       local file old_key new_key old_val
-      file="$(echo "$tjson" | python3 -c "import json,sys; print(json.load(sys.stdin).get('file',''))")"
-      old_key="$(echo "$tjson" | python3 -c "import json,sys; print(json.load(sys.stdin).get('old_key',''))")"
-      new_key="$(echo "$tjson" | python3 -c "import json,sys; print(json.load(sys.stdin).get('new_key',''))")"
+      file="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('file',''))")"
+      old_key="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('old_key',''))")"
+      new_key="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('new_key',''))")"
       old_val="$(yaml_get "$REPO_ROOT/$file" "$old_key" 2>/dev/null)" || true
       if [ -z "${old_val:-}" ]; then
         log_skip "$action: key '$old_key' not found in $file"
         SKIPPED+=("$action:$old_key"); return
       fi
-      python3 "$YAML_TOOLS" set "$REPO_ROOT/$file" "$new_key" "$old_val"
-      python3 -c "
+      $PYTHON "$YAML_TOOLS" set "$REPO_ROOT/$file" "$new_key" "$old_val"
+      $PYTHON -c "
 import yaml
 data = yaml.safe_load(open('$REPO_ROOT/$file'))
 parts = '$old_key'.split('.')
@@ -424,13 +425,13 @@ with open('$REPO_ROOT/$file', 'w') as f:
 
     delete_yaml_key)
       local file key
-      file="$(echo "$tjson" | python3 -c "import json,sys; print(json.load(sys.stdin).get('file',''))")"
-      key="$(echo "$tjson" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('path') or d.get('key',''))")"
+      file="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('file',''))")"
+      key="$(echo "$tjson" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('path') or d.get('key',''))")"
       if ! yaml_get "$REPO_ROOT/$file" "$key" >/dev/null 2>&1; then
         log_skip "$action: key '$key' not found in $file — idempotent"
         SKIPPED+=("$action:$key"); return
       fi
-      python3 -c "
+      $PYTHON -c "
 import yaml
 data = yaml.safe_load(open('$REPO_ROOT/$file'))
 parts = '$key'.split('.')
@@ -448,10 +449,10 @@ with open('$REPO_ROOT/$file', 'w') as f:
 
     create_file_from_template)
       local src tgt subs inline_tmpl
-      src="$(echo "$tjson" | python3 -c "import json,sys; print(json.load(sys.stdin).get('source',''))")"
-      tgt="$(echo "$tjson" | python3 -c "import json,sys; print(json.load(sys.stdin).get('target',''))")"
-      subs="$(echo "$tjson" | python3 -c "import json,sys; print(json.dumps(json.load(sys.stdin).get('substitutions',{})))")"
-      inline_tmpl="$(echo "$tjson" | python3 -c "import json,sys; print(json.load(sys.stdin).get('template',''))")"
+      src="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('source',''))")"
+      tgt="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('target',''))")"
+      subs="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.dumps(json.load(sys.stdin).get('substitutions',{})))")"
+      inline_tmpl="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('template',''))")"
       if [ -e "$REPO_ROOT/$tgt" ]; then
         log_skip "$action: target '$tgt' already exists — idempotent"
         SKIPPED+=("$action:$tgt"); return
@@ -461,7 +462,7 @@ with open('$REPO_ROOT/$file', 'w') as f:
       if [ -n "$inline_tmpl" ]; then
         echo "$inline_tmpl" > "$REPO_ROOT/$tgt"
         if [ "$subs" != "{}" ]; then
-          python3 -c "
+          $PYTHON -c "
 import json
 subs = json.loads('''$subs''')
 content = open('$REPO_ROOT/$tgt').read()
@@ -489,7 +490,7 @@ with open('$REPO_ROOT/$tgt', 'w') as f:
         SKIPPED+=("$action:$src"); return
       fi
       cp "$template_path" "$REPO_ROOT/$tgt"
-      python3 -c "
+      $PYTHON -c "
 import json
 subs = json.loads('''$subs''')
 content = open('$REPO_ROOT/$tgt').read()
@@ -509,12 +510,12 @@ with open('$REPO_ROOT/$tgt', 'w') as f:
 }
 
 # Execute each migration in order
-MIG_LIST="$(echo "$MIGRATION_PLAN" | python3 -c "import json,sys; [print(json.dumps(m)) for m in json.load(sys.stdin)]")"
+MIG_LIST="$(echo "$MIGRATION_PLAN" | $PYTHON -c "import json,sys; [print(json.dumps(m)) for m in json.load(sys.stdin)]")"
 while IFS= read -r mig_json; do
   [ -z "$mig_json" ] && continue
-  MIG_ID="$(echo "$mig_json" | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")"
-  MIG_FILE="$(echo "$mig_json" | python3 -c "import json,sys; print(json.load(sys.stdin)['file'])")"
-  MIG_TITLE="$(echo "$mig_json" | python3 -c "import json,sys; print(json.load(sys.stdin)['title'])")"
+  MIG_ID="$(echo "$mig_json" | $PYTHON -c "import json,sys; print(json.load(sys.stdin)['id'])")"
+  MIG_FILE="$(echo "$mig_json" | $PYTHON -c "import json,sys; print(json.load(sys.stdin)['file'])")"
+  MIG_TITLE="$(echo "$mig_json" | $PYTHON -c "import json,sys; print(json.load(sys.stdin)['title'])")"
 
   BUNDLE_PATH="$MIGRATIONS_DIR/$MIG_FILE"
   if [ ! -f "$BUNDLE_PATH" ]; then
@@ -526,7 +527,7 @@ while IFS= read -r mig_json; do
   echo ""
   echo "── $MIG_ID: $MIG_TITLE ──"
 
-  TRANSFORMS="$(python3 -c "
+  TRANSFORMS="$($PYTHON -c "
 import yaml, json
 with open('$BUNDLE_PATH') as f:
     parts = f.read().split('---')
@@ -534,15 +535,15 @@ with open('$BUNDLE_PATH') as f:
 print(json.dumps(fm.get('transforms', []), default=str))
 " 2>/dev/null)"
 
-  T_LIST="$(echo "$TRANSFORMS" | python3 -c "import json,sys; [print(json.dumps(t, default=str)) for t in json.load(sys.stdin)]")"
+  T_LIST="$(echo "$TRANSFORMS" | $PYTHON -c "import json,sys; [print(json.dumps(t, default=str)) for t in json.load(sys.stdin)]")"
   while IFS= read -r tjson; do
     [ -z "$tjson" ] && continue
-    action="$(echo "$tjson" | python3 -c "import json,sys; print(json.load(sys.stdin).get('action',''))")"
+    action="$(echo "$tjson" | $PYTHON -c "import json,sys; print(json.load(sys.stdin).get('action',''))")"
     apply_transform "$MIG_ID" "$action" "$tjson"
   done <<< "$T_LIST"
 
   # Run verify commands
-  VERIFY_CMDS="$(python3 -c "
+  VERIFY_CMDS="$($PYTHON -c "
 import yaml, json
 with open('$BUNDLE_PATH') as f:
     parts = f.read().split('---')
@@ -574,7 +575,7 @@ done <<< "$MIG_LIST"
 # ── stamp ─────────────────────────────────────────────────────────────────
 if [ -f "$SPECS_DIR/state.yaml" ]; then
   log_info "Stamping bigpowers_version=$INSTALLED in state.yaml"
-  python3 "$YAML_TOOLS" set "$SPECS_DIR/state.yaml" "bigpowers_version" "$INSTALLED"
+  $PYTHON "$YAML_TOOLS" set "$SPECS_DIR/state.yaml" "bigpowers_version" "$INSTALLED"
   log_done "stamp applied"
 fi
 

package/scripts/okf-post-sync.sh

@@ -4,6 +4,7 @@
 # Called by sync-skills.sh --okf after concept files are rendered.
 # Steps: cross-references from skill-graph.json → index.md → validate-okf.sh
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
 resolve_repo_root
 
@@ -28,13 +29,13 @@ fi
 # ── Step 2: Add cross-references from skill-graph.json ─────────────
 echo "Step 2: Adding cross-references to OKF concepts..."
 
-if [[ -f "$GRAPH_JSON" ]] && command -v python3 &>/dev/null; then
-  python3 "$REPO_ROOT/scripts/okf-add-references.py" "$GRAPH_JSON" "$OKF_WIKI_SKILLS"
+if [[ -f "$GRAPH_JSON" ]] && command -v $PYTHON &>/dev/null; then
+  $PYTHON "$REPO_ROOT/scripts/okf-add-references.py" "$GRAPH_JSON" "$OKF_WIKI_SKILLS"
 else
   echo "  Adding fallback references..."
   for f in "$OKF_WIKI_SKILLS"/*.md; do
     [[ -f "$f" ]] || continue
-    python3 -c "
+    $PYTHON -c "
 import re
 c = open('$f').read()
 c = re.sub(r'references:\s*\[\]', 'references:\n  - concept: skills-wiki\n    type: belongs_to', c)
@@ -46,7 +47,7 @@ fi
 # ── Step 3: Generate index.md with progressive disclosure ──────────
 echo "Step 3: Generating index.md..."
 
-python3 - "$OKF_WIKI_SKILLS" "$OKF_INDEX" <<'PYEOF'
+$PYTHON - "$OKF_WIKI_SKILLS" "$OKF_INDEX" <<'PYEOF'
 import re, sys
 from pathlib import Path
 from collections import defaultdict

package/scripts/run-golden-suite.sh

@@ -13,6 +13,7 @@
 #   bash scripts/run-golden-suite.sh --baseline         # run + pin baseline
 
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 
 REPORT_DIR="specs/benchmarks/reports"
 BASELINE_FILE="$REPORT_DIR/BASELINE-GOLDEN.yaml"
@@ -80,9 +81,9 @@ agent_dry_run() {
     (( yaml_count += 1 ))
     story_id=$(basename "$yaml_file" .yaml)
 
-    if python3 -c "import yaml; yaml.safe_load(open('$yaml_file'))" 2>/dev/null; then
-      local grader_type=$(python3 -c "import yaml; d=yaml.safe_load(open('$yaml_file')); print(d.get('grader',{}).get('type',''))" 2>/dev/null)
-      local pass_k=$(python3 -c "import yaml; d=yaml.safe_load(open('$yaml_file')); pk=d.get('pass_at_k',{}); print(f\"{pk.get('k',0)}-of-{pk.get('threshold',0)}\")" 2>/dev/null)
+    if $PYTHON -c "import yaml; yaml.safe_load(open('$yaml_file'))" 2>/dev/null; then
+      local grader_type=$($PYTHON -c "import yaml; d=yaml.safe_load(open('$yaml_file')); print(d.get('grader',{}).get('type',''))" 2>/dev/null)
+      local pass_k=$($PYTHON -c "import yaml; d=yaml.safe_load(open('$yaml_file')); pk=d.get('pass_at_k',{}); print(f\"{pk.get('k',0)}-of-{pk.get('threshold',0)}\")" 2>/dev/null)
       echo -e "  ${GREEN}OK${NC}   $story_id — grader=$grader_type, pass@k=$pass_k"
       (( yaml_ok += 1 ))
     else
@@ -235,8 +236,8 @@ if $AGENT_MODE && $DETERMINISTIC_PASSED; then
       echo -n "[$story_id] "
 
       # Read pass@k policy
-      PASS_K=$(python3 -c "import yaml; d=yaml.safe_load(open('$yaml_file')); print(d.get('pass_at_k',{}).get('k',3))" 2>/dev/null || echo 3)
-      PASS_THRESHOLD=$(python3 -c "import yaml; d=yaml.safe_load(open('$yaml_file')); print(d.get('pass_at_k',{}).get('threshold',2))" 2>/dev/null || echo 2)
+      PASS_K=$($PYTHON -c "import yaml; d=yaml.safe_load(open('$yaml_file')); print(d.get('pass_at_k',{}).get('k',3))" 2>/dev/null || echo 3)
+      PASS_THRESHOLD=$($PYTHON -c "import yaml; d=yaml.safe_load(open('$yaml_file')); print(d.get('pass_at_k',{}).get('threshold',2))" 2>/dev/null || echo 2)
 
       story_pass=0
       story_fail=0
@@ -254,7 +255,7 @@ if $AGENT_MODE && $DETERMINISTIC_PASSED; then
         # gh-aw run would go here. For now, check if workflow exists and is valid.
         # The actual agent execution is triggered via gh workflow run in CI;
         # local runs validate YAML definitions only.
-        if python3 -c "
+        if $PYTHON -c "
 import yaml
 d = yaml.safe_load(open('$yaml_file'))
 assert d.get('grader',{}).get('type') == 'code', 'grader must be code'

package/scripts/run-smoke.sh

@@ -5,6 +5,7 @@
 # Reads from smoke-checks.yaml by default. Falls back to single-URL check.
 # Env vars: DEPLOY_URL, SMOKE_CHECKS_FILE, SMOKE_TIMEOUT, SMOKE_RETRIES
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 
 SMOKE_CHECKS_FILE="${2:-${SMOKE_CHECKS_FILE:-smoke-checks.yaml}}"
 BASE_URL="${1:-${DEPLOY_URL:-}}"
@@ -27,9 +28,9 @@ run_single_url_check() {
   local content_signal="${4:-}"
 
   echo "[$name]"
-  start_time=$(python3 -c 'import time; print(int(time.time() * 1000))')
+  start_time=$($PYTHON -c 'import time; print(int(time.time() * 1000))')
   response=$(curl -s -o "$TMPDIR/body.txt" -w "%{http_code}" --max-time "$SMOKE_TIMEOUT" "$url")
-  response_time=$(( $(python3 -c 'import time; print(int(time.time() * 1000))') - start_time ))
+  response_time=$(( $($PYTHON -c 'import time; print(int(time.time() * 1000))') - start_time ))
   status="$response"
   body=$(cat "$TMPDIR/body.txt" 2>/dev/null || echo "")
 
@@ -147,9 +148,9 @@ run_parsed_check() {
 
   echo "[$name]"
   echo "  URL: $url"
-  start_time=$(python3 -c 'import time; print(int(time.time() * 1000))')
+  start_time=$($PYTHON -c 'import time; print(int(time.time() * 1000))')
   response=$(curl -s -o "$TMPDIR/body.txt" -w "%{http_code}" --max-time "$SMOKE_TIMEOUT" "$url" 2>/dev/null || echo "000")
-  response_time=$(( $(python3 -c 'import time; print(int(time.time() * 1000))') - start_time ))
+  response_time=$(( $($PYTHON -c 'import time; print(int(time.time() * 1000))') - start_time ))
   status="$response"
   body=$(cat "$TMPDIR/body.txt" 2>/dev/null || echo "")
 

package/scripts/sync-bugs-registry.sh

@@ -2,11 +2,12 @@
 # story: e45s03
 # sync-bugs-registry.sh — rebuild specs/bugs/registry.yaml + OKF concept bundles
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
 BUGS="$REPO_ROOT/specs/bugs"
 mkdir -p "$BUGS"
 
-python3 - "$BUGS" "$REPO_ROOT" <<'PY'
+$PYTHON - "$BUGS" "$REPO_ROOT" <<'PY'
 import re
 import sys
 from pathlib import Path

package/scripts/sync-skills.sh

@@ -8,6 +8,7 @@
 #   --okf          Generate specs/skills-wiki/ OKF concept bundle from SKILL.md frontmatter
 #   --opencode <p> Sync to bigpowers-opencode repo
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 
 # ── Parse CLI flags (must happen before source to allow early --help) ─
 OKF_MODE=0
@@ -409,7 +410,7 @@ if [[ "$OKF_MODE" -eq 1 ]]; then
   # Step 2b: Add cross-references from skill-graph.json edges into OKF concepts
   if [[ -f "$GRAPH_JSON" ]]; then
     echo "Adding cross-references from skill-graph.json..."
-    python3 - "$GRAPH_JSON" "$OKF_WIKI_SKILLS" <<'PYEOF'
+    $PYTHON - "$GRAPH_JSON" "$OKF_WIKI_SKILLS" <<'PYEOF'
 import json, sys, re
 from pathlib import Path
 
@@ -489,8 +490,8 @@ PYEOF
     # Add fallback references to all concepts
     for f in "$OKF_WIKI_SKILLS"/*.md; do
       [[ -f "$f" ]] || continue
-      if command -v python3 &>/dev/null; then
-        python3 -c "
+      if command -v $PYTHON &>/dev/null; then
+        $PYTHON -c "
 import re, sys
 content = open('$f').read()
 content = re.sub(r'references:\s*\[\]', 'references:\n  - concept: skills-wiki\n    type: belongs_to', content)
@@ -503,7 +504,7 @@ open('$f', 'w').write(content)
   # Step 3: Generate specs/skills-wiki/index.md with progressive disclosure
   echo "Generating index.md..."
   OKF_INDEX="$OKF_WIKI_DIR/index.md"
-  python3 - "$OKF_WIKI_SKILLS" "$OKF_WIKI_DIR" "$OKF_INDEX" <<'PYEOF'
+  $PYTHON - "$OKF_WIKI_SKILLS" "$OKF_WIKI_DIR" "$OKF_INDEX" <<'PYEOF'
 import json, sys, re
 from pathlib import Path
 from collections import defaultdict
@@ -662,10 +663,10 @@ fi
 
 # Regression guard (BUG-2026-06-18T100000): validate generated YAML frontmatter
 validate_script="$REPO_ROOT/scripts/validate-skill-yaml.py"
-if [[ -f "$validate_script" ]] && command -v python3 &>/dev/null; then
-  if ! python3 "$validate_script" > /dev/null 2>&1; then
+if [[ -f "$validate_script" ]] && command -v $PYTHON &>/dev/null; then
+  if ! $PYTHON "$validate_script" > /dev/null 2>&1; then
     echo "sync-skills: FAIL — YAML frontmatter validation failed" >&2
-    python3 "$validate_script" >&2
+    $PYTHON "$validate_script" >&2
     exit 1
   fi
 fi

package/scripts/sync-status-from-epics.sh

@@ -1,13 +1,14 @@
 #!/usr/bin/env bash
 # sync-status-from-epics.sh — seed execution-status.yaml keys from epic shards
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
 resolve_repo_root
 SPECS="$REPO_ROOT/specs"
 OUT="$SPECS/execution-status.yaml"
 EPICS="$SPECS/epics"
 
-python3 - "$EPICS" "$OUT" <<'PY'
+$PYTHON - "$EPICS" "$OUT" <<'PY'
 import re
 import sys
 from pathlib import Path

package/scripts/sync-version-mirrors.sh

@@ -9,6 +9,7 @@
 # Runs BEFORE @semantic-release/git commits everything.
 
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 
 VERSION="${1:?usage: sync-version-mirrors.sh <version>}"
 REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
@@ -16,10 +17,10 @@ REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 echo "sync-version-mirrors.sh: bumping mirrors to $VERSION"
 
 # ── 1. YAML mirror fields ──────────────────────────────────────────────
-python3 "$REPO_ROOT/scripts/yaml-tools.py" set \
+$PYTHON "$REPO_ROOT/scripts/yaml-tools.py" set \
   "$REPO_ROOT/specs/state.yaml" bigpowers_version "$VERSION"
 
-python3 "$REPO_ROOT/scripts/yaml-tools.py" set \
+$PYTHON "$REPO_ROOT/scripts/yaml-tools.py" set \
   "$REPO_ROOT/specs/release-plan.yaml" release.version "$VERSION"
 
 # ── 2. Regenerate derived artifacts (reads already-bumped package.json) ─

package/scripts/trace-stories.sh

@@ -16,6 +16,7 @@
 #   2 — --strict mode: P0 story has 0% coverage
 
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 
 source "$(dirname "${BASH_SOURCE[0]}")/lib/skill-common.sh"
 
@@ -68,5 +69,5 @@ if [[ ! -f "$EXEC_STATUS" ]]; then
   exit 1
 fi
 
-exec python3 "$(dirname "${BASH_SOURCE[0]}")/lib/trace-stories.py" \
+exec $PYTHON "$(dirname "${BASH_SOURCE[0]}")/lib/trace-stories.py" \
   "$REPO_ROOT" "$MATRIX_JSON" "$TRACE_MD" "$OKF_DIR" "$STRICT" "$MODE"

package/scripts/validate-okf.sh

@@ -5,6 +5,7 @@
 # and verification-report bundles.
 # Multi-dir default: specs/metrics/ + specs/migrations/.
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 
 ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || { echo "validate-okf: not inside a git repo"; exit 1; }
 EXIT_CODE=0
@@ -42,7 +43,7 @@ val_nullish_or_empty() { val_nullish "$1" || [ "$1" = "[]" ]; }
 
 parse_frontmatter() {
   local file="$1"
-  python3 -c "
+  $PYTHON -c "
 import yaml, sys, json
 
 class SafeEncoder(json.JSONEncoder):
@@ -74,7 +75,7 @@ validate_story_metrics() {
   local errs=0
   for key in id epic bcps commit_range source generated_at generator; do
     local val
-    val="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('$key',''))" 2>/dev/null)"
+    val="$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('$key',''))" 2>/dev/null)"
     if val_nullish "$val"; then
       printf "${RED}FAIL${NC} %s: missing required key '%s'\n" "$name" "$key"
       errs=$((errs + 1))
@@ -83,28 +84,28 @@ validate_story_metrics() {
   [ "$errs" -gt 0 ] && { EXIT_CODE=1; return; }
 
   local source
-  source="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('source',''))" 2>/dev/null)"
+  source="$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('source',''))" 2>/dev/null)"
   if ! echo "measured estimated backfilled" | grep -qw "$source"; then
     printf "${RED}FAIL${NC} %s: invalid source '%s' — must be measured|estimated|backfilled\n" "$name" "$source"
     EXIT_CODE=1; return
   fi
 
   local generator
-  generator="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('generator',''))" 2>/dev/null)"
+  generator="$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('generator',''))" 2>/dev/null)"
   if [ "$generator" != "scripts/record-cycle-time.sh" ]; then
     printf "${RED}FAIL${NC} %s: wrong generator '%s' — expected scripts/record-cycle-time.sh\n" "$name" "$generator"
     EXIT_CODE=1; return
   fi
 
   local commit_range
-  commit_range="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('commit_range',''))" 2>/dev/null)"
+  commit_range="$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('commit_range',''))" 2>/dev/null)"
   if ! git -C "$ROOT" log --oneline -1 "$commit_range" >/dev/null 2>&1; then
     printf "${RED}FAIL${NC} %s: commit_range '%s' does not resolve\n" "$name" "$commit_range"
     EXIT_CODE=1; return
   fi
 
   local eff
-  eff="$(echo "$fm" | python3 -c "
+  eff="$(echo "$fm" | $PYTHON -c "
 import json,sys
 d=json.load(sys.stdin)
 e=d.get('effort',{}).get('effort_hours')
@@ -128,7 +129,7 @@ validate_spec_migration() {
   local errs=0
   for key in id title since_version order actions_needed; do
     local val
-    val="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('$key',''))" 2>/dev/null)"
+    val="$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('$key',''))" 2>/dev/null)"
     if val_nullish_or_empty "$val"; then
       printf "${RED}FAIL${NC} %s: missing required key '%s'\n" "$name" "$key"
       errs=$((errs + 1))
@@ -137,7 +138,7 @@ validate_spec_migration() {
   [ "$errs" -gt 0 ] && { EXIT_CODE=1; return; }
 
   local fp_count
-  fp_count="$(echo "$fm" | python3 -c "
+  fp_count="$(echo "$fm" | $PYTHON -c "
 import json,sys
 d=json.load(sys.stdin)
 fp=d.get('fingerprint',{}).get('any',[])
@@ -150,14 +151,14 @@ print(len(fp))
 
   printf "${GREEN}PASS${NC} %s (actions=%s, fingerprint has %s check(s))\n" \
     "$name" \
-    "$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(len(d.get('actions_needed',[])))" 2>/dev/null)" \
+    "$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(len(d.get('actions_needed',[])))" 2>/dev/null)" \
     "$fp_count"
 }
 
 validate_migration_registry() {
   local file="$1" fm="$2" name="$3"
   local count
-  count="$(echo "$fm" | python3 -c "
+  count="$(echo "$fm" | $PYTHON -c "
 import json,sys
 d=json.load(sys.stdin)
 migrations=d.get('migrations',[])
@@ -169,7 +170,7 @@ print(len(migrations))
   fi
 
   local bad
-  bad="$(echo "$fm" | python3 -c "
+  bad="$(echo "$fm" | $PYTHON -c "
 import json,sys
 d=json.load(sys.stdin)
 for m in d.get('migrations',[]):
@@ -188,14 +189,14 @@ validate_concept() {
   local errs=0
   for key in id title category; do
     local val
-    val="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('$key',''))" 2>/dev/null)"
+    val="$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('$key',''))" 2>/dev/null)"
     if val_nullish "$val"; then
       printf "${RED}FAIL${NC} %s: missing required key '%s'\n" "$name" "$key"
       errs=$((errs + 1))
     fi
   done
   local ref_count
-  ref_count="$(echo "$fm" | python3 -c "
+  ref_count="$(echo "$fm" | $PYTHON -c "
 import json,sys
 d=json.load(sys.stdin)
 r=d.get('references',[])
@@ -207,7 +208,7 @@ print(len(r) if isinstance(r,list) else 0)
   fi
   [ "$errs" -gt 0 ] && { EXIT_CODE=1; return; }
   local cat
-  cat="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('category',''))" 2>/dev/null)"
+  cat="$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('category',''))" 2>/dev/null)"
   printf "${GREEN}PASS${NC} %s (category=%s, %s reference(s))\n" "$name" "$cat" "$ref_count"
 }
 
@@ -217,7 +218,7 @@ validate_verification_report() {
   local errs=0
   for key in score gate_status threshold total_pass total_fail generated_by; do
     local val
-    val="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('$key',''))" 2>/dev/null)"
+    val="$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('$key',''))" 2>/dev/null)"
     if val_nullish "$val"; then
       printf "${RED}FAIL${NC} %s: missing required key '%s'\n" "$name" "$key"
       errs=$((errs + 1))
@@ -226,14 +227,14 @@ validate_verification_report() {
   [ "$errs" -gt 0 ] && { EXIT_CODE=1; return; }
 
   local gs
-  gs="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('gate_status',''))" 2>/dev/null)"
+  gs="$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('gate_status',''))" 2>/dev/null)"
   if ! echo "pass fail concerns waived" | grep -qw "$gs"; then
     printf "${RED}FAIL${NC} %s: invalid gate_status '%s' — must be pass|fail|concerns|waived\n" "$name" "$gs"
     EXIT_CODE=1; return
   fi
 
   local score
-  score="$(echo "$fm" | python3 -c "
+  score="$(echo "$fm" | $PYTHON -c "
 import json,sys
 d=json.load(sys.stdin)
 s=d.get('score')
@@ -254,14 +255,14 @@ print(s)
 
   printf "${GREEN}PASS${NC} %s (score=%.1f, gate=%s, threshold=%.1f)\n" \
     "$name" "$score" "$gs" \
-    "$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('threshold',0))" 2>/dev/null)"
+    "$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('threshold',0))" 2>/dev/null)"
 }
 
 # ---- Receipts validation (e41s04) ----
 validate_receipts() {
   local f="$ROOT/specs/receipts.json"
   if [ ! -f "$f" ]; then printf "${YELLOW}SKIP${NC} receipts.json not found\n"; return; fi
-  python3 -c "
+  $PYTHON -c "
 import json, sys
 d=json.load(open('$f'))
 vs={'measured','estimated','backfilled','absent'}
@@ -296,7 +297,7 @@ validate_bundle() {
   # ── OKF v0.1 Generic Frontmatter Conformance (e39s10) ──
   # Check required 'type' field
   local fm_type
-  fm_type="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('type',''))" 2>/dev/null)"
+  fm_type="$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('type',''))" 2>/dev/null)"
   if [ -z "$fm_type" ]; then
     printf "${RED}FAIL${NC} %s: OKF v0.1 — missing required 'type' field\n" "$name"
     EXIT_CODE=1
@@ -311,7 +312,7 @@ validate_bundle() {
   fi
 
   local kind
-  kind="$(echo "$fm" | python3 -c "import json,sys; d=json.load(sys.stdin); print(d.get('okf_kind',''))" 2>/dev/null)"
+  kind="$(echo "$fm" | $PYTHON -c "import json,sys; d=json.load(sys.stdin); print(d.get('okf_kind',''))" 2>/dev/null)"
   case "$kind" in
     story-metrics)       validate_story_metrics "$file" "$fm" "$name" ;;
     spec-migration)      validate_spec_migration "$file" "$fm" "$name" ;;

package/scripts/validate-specs-yaml.sh

@@ -8,6 +8,7 @@
 # specs/**/*.yaml with PyYAML first, and runs the required-key checks
 # against the *parsed* objects, not against grep.
 set -euo pipefail
+source "$(dirname "${BASH_SOURCE[0]}")/lib/python-env.sh"
 
 # Resolve REPO_ROOT from script location
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
@@ -18,7 +19,7 @@ SPECS="${1:-$REPO_ROOT/specs}"
 err=0
 
 # ── Phase 1: real parse pass — every specs/**/*.yaml must be valid YAML ──────
-parse_report="$(python3 -c "
+parse_report="$($PYTHON -c "
 import sys, glob, os
 import yaml
 
@@ -61,7 +62,7 @@ need_key() {
     err=1
     return
   fi
-  if ! python3 -c "
+  if ! $PYTHON -c "
 import sys, yaml
 d = yaml.safe_load(open(sys.argv[1])) or {}
 sys.exit(0 if ($py_check) else 1)
@@ -79,7 +80,7 @@ need_key "$SPECS/execution-status.yaml" "isinstance(d.get('development_status'),
 
 # ── Phase 3: every epic's `file` reference must exist, read from the parsed object ──
 if [[ -f "$SPECS/release-plan.yaml" ]]; then
-  missing_files="$(python3 -c "
+  missing_files="$($PYTHON -c "
 import sys, os, yaml
 specs = sys.argv[1]
 d = yaml.safe_load(open(os.path.join(specs, 'release-plan.yaml'))) or {}