feat(system): fix(setup): add ensurepip check to prevent broken venv on Debian/Ubuntu — closes #495

Co-Authored-By: @devpulse <devpulse@aipass>

setup.sh

@@ -133,6 +133,19 @@ if [ "$PY_OK" != "1" ]; then
     fi
 fi
 
+# --- Check ensurepip (Debian/Ubuntu split it into python3-venv apt package) ---
+if ! $PYTHON -c 'import ensurepip' &>/dev/null 2>&1; then
+    echo ""
+    echo "FAIL: ensurepip is unavailable for $PYTHON."
+    echo "  Without it, 'python3 -m venv' creates a broken venv (no pip, no activate)."
+    echo ""
+    echo "  Debian/Ubuntu:  sudo apt install python3-venv python3-pip"
+    echo "  Fedora/RHEL:    sudo dnf install python3-pip"
+    echo "  Arch:           (included in base python — file a bug if you hit this)"
+    echo ""
+    exit 1
+fi
+
 # --- Create venv ---
 if [ "$IS_WINDOWS" -eq 1 ] && [ -f ".venv/Scripts/python.exe" ]; then
     # Windows: skip venv recreation if python.exe exists (rm -rf unreliable due to file locking)

src/aipass/prax/README.md

@@ -143,8 +143,7 @@ prax/
 │       └── watcher/                   # Background system watchers
 ├── prax_json/                         # Auto-created per-module config/data/log files
 ├── templates/                         # Dashboard template schema (DASHBOARD.template.json)
-├── tests/                             # 375 tests across 16 files
-└── tools/                             # Standalone utilities (inbox_watchdog.py, verify_branch.py)
+└── tests/                             # 911 tests across 16 files
 ```
 
 ### Design Pattern

src/aipass/spawn/README.md

@@ -139,9 +139,7 @@ spawn/
 │           └── json_handler.py          # Standard JSON I/O, operation logging, 7 API functions
 ├── templates/
 │   ├── builder/                         # Full scaffold template (45 files, 24 dirs)
-│   ├── birthright/                      # Minimal template
-│   └── .archive/
-│       └── agent_mock_branch/           # Reference implementation
+│   └── birthright/                      # Minimal template
 ├── tests/                               # 13 test files, 253 tests
 ├── spawn_json/                          # JSON tracking directory
 ├── tools/                               # Branch verification utilities

src/aipass/spawn/templates/builder/.spawn/.template_registry.json

@@ -155,7 +155,7 @@
       "content_hash": "a4cf0a8e3b4f",
       "has_branch_placeholder": false
     },
-    "f015": {
+    "f026": {
       "path": "apps/modules/__init__.py",
       "name": "__init__.py",
       "content_hash": "e3b0c44298fc",
@@ -263,7 +263,7 @@
       "content_hash": "28e9ae373563",
       "has_branch_placeholder": false
     },
-    "f026": {
+    "f015": {
       "path": "apps/plugins/__init__.py",
       "name": "__init__.py",
       "content_hash": "e3b0c44298fc",

src/aipass/trigger/README.md

@@ -5,7 +5,7 @@
 **Purpose:** Event bus and error dispatch for AIPass. Branches fire events, registered handlers react. Medic watches logs for errors, fingerprints them, gates dispatch through an 8-stage pipeline, and notifies the responsible branch.
 **Module:** `aipass.trigger`
 **Version:** 2.2.0
-**Last Updated:** 2026-04-22
+**Last Updated:** 2026-05-02
 
 ## Commands