add zeroclaw preflight flow and docs for zacus (#99)

.gitignore

@@ -17,6 +17,11 @@ logs/
 **/logs/
 **/*.log
 
+# ZeroClaw local runtime (generated locally, never committed)
+/.zeroclaw/
+/config.toml
+/workspace/
+
 # Artifacts and caches
 artifacts/
 __pycache__/

README.md

@@ -34,6 +34,7 @@ Dossier : `printables/`
 - `docs/index.md` + `docs/repo-status.md` pour la navigation et l’état du dépôt
 - `include-humain-IA/` (contenus annexes, renommé pour la portabilité)
 - `tools/dev/zacus.sh codex --prompt tools/dev/codex_prompts/zacus_overhaul_one_shot.md` lance le prompt de Codex directement depuis le dépôt.
+- `tools/dev/zacus.sh zeroclaw-preflight --require-port` lance le préflight USB ZeroClaw avant actions hardware.
 - Les artifacts de résolution de ports sont écrits sous `artifacts/ports/<timestamp>/ports_resolve.json` avec un pointeur `artifacts/ports/latest_ports_resolve.json`. Utilisez `ZACUS_MOCK_PORTS=1` (et `ZACUS_PORTS_FIXTURE=tools/test/fixtures/ports_list_macos.txt`) pour tester la boucle sans matériel.
 - `tools/dev/zacus.sh codex --prompt tools/dev/codex_prompts/zacus_overhaul_one_shot.md` lance le prompt de Codex directement depuis le dépôt.
 

docs/QUICKSTART.md

@@ -31,6 +31,7 @@ python3 tools/test/zacus_menu.py
 ```
 
 Codex CLI intégré : `./tools/dev/zacus.sh codex --prompt tools/dev/codex_prompts/zacus_overhaul_one_shot.md`
+Préflight USB ZeroClaw : `./tools/dev/zacus.sh zeroclaw-preflight --require-port`
 
 Checks contenu (sans hardware):
 
@@ -55,6 +56,8 @@ Pour résoudre les ports sans matériel, la commande `./tools/dev/zacus.sh ports
 
 Codex CLI intégré : `./tools/dev/zacus.sh codex --prompt tools/dev/codex_prompts/zacus_overhaul_one_shot.md`. Le script note aussi l’état des ports résolus et place les logs dans `artifacts/codex/<timestamp>/`.
 
+Guide orchestration ZeroClaw: `docs/zeroclaw_orchestration.md`
+
 Dépendances optionnelles:
 - `pip install pyyaml` pour `run_content_checks.sh`
 - `pip install pyserial` pour suites USB, UI Link sim et console série

docs/index.md

@@ -13,6 +13,7 @@
 - Styleguide (ton & structure) : `docs/STYLEGUIDE.md`
 - Workflows (validate/export) : `docs/WORKFLOWS.md`
 - Glossaire des identifiants : `docs/GLOSSARY.md`
+- Orchestration ZeroClaw (préflight + agent) : `docs/zeroclaw_orchestration.md`
 - Contribuer (workflow & licence) : `CONTRIBUTING.md`
 
 ## Astuce

docs/zeroclaw_orchestration.md

@@ -0,0 +1,46 @@
+# Orchestration ZeroClaw (Zacus)
+
+Dernière mise à jour: 2026-02-21.
+
+## Objectif
+
+Fiabiliser les sessions Zacus avec cartes branchées:
+
+- préflight USB explicite avant upload/flash/tests live,
+- session agent ciblée `zacus`,
+- boucle courte issue -> PR reproductible.
+
+## Préflight hardware
+
+Commande dédiée:
+
+```bash
+./tools/dev/zacus.sh zeroclaw-preflight --require-port
+```
+
+Commande directe:
+
+```bash
+./tools/dev/zeroclaw_hw_preflight.sh --require-port
+```
+
+## Conversation agent ciblée Zacus
+
+Depuis `Kill_LIFE`:
+
+```bash
+tools/ai/zeroclaw_dual_chat.sh zacus -m "fais un état hardware et propose 3 actions"
+```
+
+Si credentials provider absents:
+
+- `zeroclaw auth login --provider openai-codex --device-code`
+- ou `export OPENROUTER_API_KEY=... && export ZEROCLAW_PROVIDER=openrouter`
+
+## Boucle recommandée
+
+1. `zacus.sh zeroclaw-preflight --require-port`
+2. prompt court Zacus
+3. patch minimal
+4. validation locale ciblée
+5. PR Zacus avec liens d’artefacts

tools/dev/zacus.sh

@@ -6,6 +6,7 @@ REPO_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 FW_ROOT="$REPO_ROOT/hardware/firmware"
 RC_RUNNER="$FW_ROOT/tools/dev/run_matrix_and_smoke.sh"
 SMOKE_SCRIPT="$FW_ROOT/tools/dev/serial_smoke.py"
+ZEROCLAW_PREFLIGHT="$SCRIPT_DIR/zeroclaw_hw_preflight.sh"
 PROMPT_DIR="$SCRIPT_DIR/codex_prompts"
 ARTIFACT_ROOT="$REPO_ROOT/artifacts"
 PORTS_ARTIFACT_ROOT="$ARTIFACT_ROOT/ports"
@@ -35,6 +36,7 @@ Commands:
   rc       Run the RC live gate (always strict)
   smoke    Run the serial smoke helper (pass --role ... args)
   ports    Resolve ports once and show summary
+  zeroclaw-preflight  Run ZeroClaw USB preflight before hardware actions
   codex    Invoke Codex CLI with a prompt
   menu     Show the Zacus cockpit menu
   help     Show this usage
@@ -165,6 +167,14 @@ cmd_smoke() {
   (cd "$FW_ROOT" && python3 "$SMOKE_SCRIPT" "$@")
 }
 
+cmd_zeroclaw_preflight() {
+  if [[ ! -x "$ZEROCLAW_PREFLIGHT" ]]; then
+    die "missing preflight script: $ZEROCLAW_PREFLIGHT"
+  fi
+  info "running zeroclaw hardware preflight"
+  "$ZEROCLAW_PREFLIGHT" "$@"
+}
+
 ensure_codex_ready() {
   if ! command -v codex >/dev/null 2>&1; then
     die_codex "codex CLI not found. Install it from https://app.codex.com/docs/cli"
@@ -329,6 +339,7 @@ cmd_menu() {
     printf '  2) Serial smoke\n'
     printf '  3) Codex (run prompt)\n'
     printf '  4) Ports: resolve now\n'
+    printf '  5) ZeroClaw preflight\n'
     printf '  0) Exit\n'
     read -rp 'Choice: ' choice
     case "$choice" in
@@ -344,6 +355,9 @@ cmd_menu() {
       4)
         cmd_ports
         ;;
+      5)
+        cmd_zeroclaw_preflight --require-port
+        ;;
       0)
         return 0
         ;;
@@ -366,6 +380,9 @@ case "$command" in
   ports)
     cmd_ports
     ;;
+  zeroclaw-preflight|zc-preflight)
+    cmd_zeroclaw_preflight "$@"
+    ;;
   codex)
     cmd_codex "$@"
     ;;

tools/dev/zeroclaw_hw_preflight.sh

@@ -0,0 +1,88 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ZEROCLAW_BIN="${ZEROCLAW_BIN:-/Users/cils/Documents/Lelectron_rare/Kill_LIFE/zeroclaw/target/release/zeroclaw}"
+REQUIRE_PORT=0
+declare -a PORTS=()
+
+usage() {
+  cat <<'USAGE'
+Usage: zeroclaw_hw_preflight.sh [--zeroclaw-bin <path>] [--port <tty>]... [--require-port]
+
+Run ZeroClaw USB discovery + per-port introspection before hardware actions.
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --zeroclaw-bin)
+      ZEROCLAW_BIN="${2:-}"
+      shift 2
+      ;;
+    --port)
+      PORTS+=("${2:-}")
+      shift 2
+      ;;
+    --require-port)
+      REQUIRE_PORT=1
+      shift
+      ;;
+    --help|-h)
+      usage
+      exit 0
+      ;;
+    *)
+      echo "unknown option: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+done
+
+if [[ ! -x "$ZEROCLAW_BIN" ]]; then
+  if command -v "$ZEROCLAW_BIN" >/dev/null 2>&1; then
+    ZEROCLAW_BIN="$(command -v "$ZEROCLAW_BIN")"
+  elif command -v zeroclaw >/dev/null 2>&1; then
+    ZEROCLAW_BIN="$(command -v zeroclaw)"
+  else
+    echo "[fail] zeroclaw binary not found (use --zeroclaw-bin)." >&2
+    exit 2
+  fi
+fi
+
+echo "$ $ZEROCLAW_BIN hardware discover"
+"$ZEROCLAW_BIN" hardware discover
+
+if [[ ${#PORTS[@]} -eq 0 ]]; then
+  while IFS= read -r candidate; do PORTS+=("$candidate"); done < <(
+    {
+      ls /dev/tty.SLAB_USBtoUART 2>/dev/null || true
+      ls /dev/tty.usbserial-* 2>/dev/null || true
+      ls /dev/tty.usbmodem* 2>/dev/null || true
+    } | awk 'NF' | sort -u
+  )
+fi
+
+if [[ ${#PORTS[@]} -eq 0 ]]; then
+  if [[ "$REQUIRE_PORT" == "1" ]]; then
+    echo "[fail] no candidate serial ports detected." >&2
+    exit 3
+  fi
+  echo "[warn] no candidate serial ports detected."
+  exit 0
+fi
+
+failures=0
+for port in "${PORTS[@]}"; do
+  echo "$ $ZEROCLAW_BIN hardware introspect $port"
+  if ! "$ZEROCLAW_BIN" hardware introspect "$port"; then
+    failures=$((failures + 1))
+  fi
+done
+
+if [[ "$failures" -gt 0 ]]; then
+  echo "[fail] introspection failed on $failures port(s)." >&2
+  exit 4
+fi
+
+echo "[ok] zeroclaw hardware preflight passed."