@the-bearded-bear/claude-craft 8.26.0-next.2a54921 → 8.26.0-next.defc34b

package/Dev/i18n/de/Common/commands/ralph-run.md

@@ -51,6 +51,12 @@ Führt Claude in einer kontinuierlichen Schleife aus, bis die Aufgabe abgeschlos
    - Maximale Iterationen, Timeouts, DoD-Kriterien festlegen
    - Hooks initialisieren, falls aktiviert
 
+#### Isolierung von Sessions und parallelen Workern
+
+- **Explizite Claude-Session**: Jede Ralph-Session legt ihre eigene Claude-Konversations-ID fest — `claude --session-id <uuid>` in der ersten Iteration, danach `claude --resume <uuid>`. Die UUID wird in `.ralph/sessions/<session>/claude_session_id` gespeichert, sodass `--continue=<session>` die richtige Konversation fortsetzt. Ralph verwendet `claude --continue` nicht mehr, das „die neueste Konversation im Verzeichnis“ fortsetzte (geteilt zwischen Workern oder sogar mit der interaktiven Session des Benutzers).
+- **Ein Git-Worktree pro Worker** (paralleler Modus, `lib/parallel-manager.sh`): Jede Story läuft in einem eigenen Worktree `.ralph/parallel/worktrees/<session>` auf dem Branch `ralph/<session>`, mit ihrem Ralph-Zustand unter `.ralph/parallel/sessions/<session>/ralph/`. Am Ende des Laufs werden verbleibende Änderungen als `wip(ralph): <story>` auf diesem Branch committet, danach wird der Worktree entfernt (`git worktree remove`). Schlägt dieser Commit fehl, bleibt der Worktree erhalten (kein Datenverlust) und wird in `output.log` gemeldet. Die Arbeit wird durch Mergen der `ralph/*`-Branches übernommen.
+- **Außerhalb eines Git-Repositorys**: kein Worktree; der Worker läuft im aktuellen Verzeichnis (eine Warnung wird ausgegeben), die Isolierung der Claude-Sessions bleibt bestehen.
+
 ### 2. Hauptschleife mit Dashboard
 
 ```

package/Dev/i18n/en/Common/commands/ralph-run.md

@@ -51,6 +51,12 @@ Execute Claude in a continuous loop until the task is complete or the Definition
    - Set max iterations, timeouts, DoD criteria
    - Initialize hooks if enabled
 
+#### Session and parallel worker isolation
+
+- **Explicit Claude session**: each Ralph session pins its own Claude conversation ID — `claude --session-id <uuid>` on the first iteration, then `claude --resume <uuid>`. The UUID is stored in `.ralph/sessions/<session>/claude_session_id`, so `--continue=<session>` resumes the right conversation. Ralph no longer uses `claude --continue`, which resumed "the most recent conversation in the directory" (shared between workers, or even with the user's interactive session).
+- **One git worktree per worker** (parallel mode, `lib/parallel-manager.sh`): each story runs in a dedicated worktree `.ralph/parallel/worktrees/<session>` on branch `ralph/<session>`, with its Ralph state under `.ralph/parallel/sessions/<session>/ralph/`. At the end of the run, leftover changes are committed as `wip(ralph): <story>` on that branch, then the worktree is removed (`git worktree remove`). If that commit fails, the worktree is kept (no data loss) and reported in `output.log`. Collect the work by merging the `ralph/*` branches.
+- **Outside a git repository**: no worktree; the worker runs in the current directory (a warning is printed), Claude session isolation still applies.
+
 ### 2. Main Loop with Dashboard
 
 ```

package/Dev/i18n/es/Common/commands/ralph-run.md

@@ -51,6 +51,12 @@ Ejecuta Claude en un bucle continuo hasta que la tarea esté completa o se cumpl
    - Establecer máximo de iteraciones, timeouts y criterios DoD
    - Inicializar hooks si están habilitados
 
+#### Aislamiento de sesiones y workers paralelos
+
+- **Sesión de Claude explícita**: cada sesión de Ralph fija su propio identificador de conversación de Claude — `claude --session-id <uuid>` en la primera iteración y luego `claude --resume <uuid>`. El UUID se guarda en `.ralph/sessions/<session>/claude_session_id`, de modo que `--continue=<session>` reanuda la conversación correcta. Ralph ya no usa `claude --continue`, que reanudaba «la conversación más reciente del directorio» (compartida entre workers, o incluso con la sesión interactiva del usuario).
+- **Un worktree de git por worker** (modo paralelo, `lib/parallel-manager.sh`): cada historia se ejecuta en un worktree dedicado `.ralph/parallel/worktrees/<session>` sobre la rama `ralph/<session>`, con su estado de Ralph en `.ralph/parallel/sessions/<session>/ralph/`. Al final de la ejecución, los cambios pendientes se confirman como `wip(ralph): <story>` en esa rama y después se elimina el worktree (`git worktree remove`). Si ese commit falla, el worktree se conserva (sin pérdida de datos) y se indica en `output.log`. El trabajo se recupera fusionando las ramas `ralph/*`.
+- **Fuera de un repositorio git**: sin worktree; el worker se ejecuta en el directorio actual (se muestra un aviso) y el aislamiento de sesiones de Claude se mantiene.
+
 ### 2. Bucle Principal con Dashboard
 
 ```

package/Dev/i18n/fr/Common/commands/ralph-run.md

@@ -51,6 +51,12 @@ Exécuter Claude en boucle continue jusqu'à ce que la tâche soit terminée ou
    - Définir les itérations max, les timeouts, les critères DoD
    - Initialiser les hooks si activés
 
+#### Isolation des sessions et des workers parallèles
+
+- **Session Claude explicite** : chaque session Ralph fixe son propre identifiant de conversation Claude — `claude --session-id <uuid>` à la première itération, puis `claude --resume <uuid>`. L'UUID est stocké dans `.ralph/sessions/<session>/claude_session_id`, ce qui permet à `--continue=<session>` de reprendre la bonne conversation. Ralph n'utilise plus `claude --continue`, qui reprenait « la conversation la plus récente du répertoire » (partagée entre workers, voire avec une session interactive de l'utilisateur).
+- **Worktree git par worker** (mode parallèle, `lib/parallel-manager.sh`) : chaque story s'exécute dans un worktree dédié `.ralph/parallel/worktrees/<session>` sur la branche `ralph/<session>`, avec son état Ralph sous `.ralph/parallel/sessions/<session>/ralph/`. En fin de run, les modifications restantes sont commitées en `wip(ralph): <story>` sur cette branche, puis le worktree est retiré (`git worktree remove`). Si ce commit échoue, le worktree est conservé (aucune perte) et signalé dans `output.log`. Le travail se récupère en fusionnant les branches `ralph/*`.
+- **Hors dépôt git** : pas de worktree ; le worker s'exécute dans le répertoire courant (avertissement affiché), l'isolation des sessions Claude restant assurée.
+
 ### 2. Boucle principale avec Dashboard
 
 ```

package/Dev/i18n/pt/Common/commands/ralph-run.md

@@ -51,6 +51,12 @@ Executa o Claude em loop contínuo até que a tarefa seja concluída ou os crit
    - Definir máximo de iterações, timeouts e critérios de DoD
    - Inicializar hooks se habilitados
 
+#### Isolamento de sessões e workers paralelos
+
+- **Sessão Claude explícita**: cada sessão Ralph fixa seu próprio identificador de conversa Claude — `claude --session-id <uuid>` na primeira iteração e depois `claude --resume <uuid>`. O UUID é armazenado em `.ralph/sessions/<session>/claude_session_id`, para que `--continue=<session>` retome a conversa correta. O Ralph não usa mais `claude --continue`, que retomava "a conversa mais recente do diretório" (compartilhada entre workers, ou até com a sessão interativa do usuário).
+- **Um worktree git por worker** (modo paralelo, `lib/parallel-manager.sh`): cada história é executada em um worktree dedicado `.ralph/parallel/worktrees/<session>` na branch `ralph/<session>`, com seu estado Ralph em `.ralph/parallel/sessions/<session>/ralph/`. No fim da execução, as alterações restantes são commitadas como `wip(ralph): <story>` nessa branch e o worktree é removido (`git worktree remove`). Se esse commit falhar, o worktree é mantido (sem perda de dados) e sinalizado em `output.log`. O trabalho é recuperado fazendo merge das branches `ralph/*`.
+- **Fora de um repositório git**: sem worktree; o worker é executado no diretório atual (um aviso é exibido) e o isolamento das sessões Claude continua garantido.
+
 ### 2. Loop Principal com Painel
 
 ```

package/Tools/Ralph/lib/checkpoint.sh

@@ -207,12 +207,12 @@ list_checkpoints() {
 
     # Find commits matching the checkpoint pattern
     local commits
-    commits=$(git log --oneline --grep="checkpoint: Ralph" 2>/dev/null | head -20)
+    commits=$(git log --oneline --grep="checkpoint: Ralph" 2>/dev/null | head -20) || true
 
     if [[ -n "$commits" ]]; then
         echo "$commits" | while read -r line; do
-            local hash=$(echo "$line" | cut -d' ' -f1)
-            local msg=$(echo "$line" | cut -d' ' -f2-)
+            local hash=$(echo "$line" | cut -d' ' -f1) || true
+            local msg=$(echo "$line" | cut -d' ' -f2-) || true
             echo "{\"hash\":\"$hash\",\"message\":\"$msg\"}"
         done | jq -s '.'
     else

package/Tools/Ralph/lib/circuit-breaker.sh

@@ -30,35 +30,35 @@ CB_LEARNING_MIN_SAMPLES=5
 # =============================================================================
 # Each profile defines thresholds optimized for different task types
 
-declare -A CB_PROFILE_QUICK_FIX=(
+declare -gA CB_PROFILE_QUICK_FIX=(
     ["no_changes"]=2
     ["errors"]=3
     ["max_iterations"]=10
     ["keywords"]="fix bug typo hotfix patch"
 )
 
-declare -A CB_PROFILE_SMALL_FEATURE=(
+declare -gA CB_PROFILE_SMALL_FEATURE=(
     ["no_changes"]=3
     ["errors"]=4
     ["max_iterations"]=15
     ["keywords"]="add implement small simple"
 )
 
-declare -A CB_PROFILE_MEDIUM_FEATURE=(
+declare -gA CB_PROFILE_MEDIUM_FEATURE=(
     ["no_changes"]=4
     ["errors"]=6
     ["max_iterations"]=25
     ["keywords"]="feature create with tests"
 )
 
-declare -A CB_PROFILE_LARGE_FEATURE=(
+declare -gA CB_PROFILE_LARGE_FEATURE=(
     ["no_changes"]=5
     ["errors"]=8
     ["max_iterations"]=50
     ["keywords"]="refactor migrate complex large"
 )
 
-declare -A CB_PROFILE_EXPLORATION=(
+declare -gA CB_PROFILE_EXPLORATION=(
     ["no_changes"]=10
     ["errors"]=15
     ["max_iterations"]=100
@@ -66,7 +66,7 @@ declare -A CB_PROFILE_EXPLORATION=(
 )
 
 # Autonomous profile for overnight/unattended runs
-declare -A CB_PROFILE_AUTONOMOUS=(
+declare -gA CB_PROFILE_AUTONOMOUS=(
     ["no_changes"]=5
     ["errors"]=8
     ["max_iterations"]=50
@@ -162,7 +162,7 @@ init_circuit_breaker() {
 detect_task_profile() {
     local prompt="$1"
     local prompt_lower
-    prompt_lower=$(echo "$prompt" | tr '[:upper:]' '[:lower:]')
+    prompt_lower=$(echo "$prompt" | tr '[:upper:]' '[:lower:]') || true
 
     # Check each profile's keywords
     local profiles=("quick_fix" "small_feature" "medium_feature" "large_feature" "exploration" "autonomous")
@@ -265,7 +265,7 @@ apply_learned_adjustments() {
     ' "$history_file" 2>/dev/null)
 
     local samples
-    samples=$(echo "$profile_data" | jq -r '.samples // 0')
+    samples=$(echo "$profile_data" | jq -r '.samples // 0') || samples=0
 
     if [[ $samples -lt $CB_LEARNING_MIN_SAMPLES ]]; then
         print_verbose "Not enough samples for learning ($samples < $CB_LEARNING_MIN_SAMPLES)"
@@ -274,10 +274,10 @@ apply_learned_adjustments() {
 
     # Apply adjustments based on historical success rate
     local success_rate
-    success_rate=$(echo "$profile_data" | jq -r '.success_rate // 0')
+    success_rate=$(echo "$profile_data" | jq -r '.success_rate // 0') || success_rate=0
 
     local avg_iterations
-    avg_iterations=$(echo "$profile_data" | jq -r '.avg_iterations // 0')
+    avg_iterations=$(echo "$profile_data" | jq -r '.avg_iterations // 0') || avg_iterations=0
 
     # If success rate is low, increase thresholds
     if [[ $success_rate -lt 50 ]]; then

package/Tools/Ralph/lib/context-manager.sh

@@ -106,6 +106,17 @@ init_context_manager() {
     print_verbose "  - Smart reconstruction: $CONTEXT_SMART_RECONSTRUCTION"
 }
 
+# Print the first lines of `/context` for a Claude session UUID.
+# Best effort: prints nothing on failure, always succeeds (set -e safe).
+probe_context_usage() {
+    local claude_uuid="$1"
+    if command -v timeout &> /dev/null; then
+        timeout 10s "${CLAUDE_CMD[@]}" --resume "$claude_uuid" -p "/context" 2>/dev/null | head -5 || true
+    else
+        "${CLAUDE_CMD[@]}" --resume "$claude_uuid" -p "/context" 2>/dev/null | head -5 || true
+    fi
+}
+
 # =============================================================================
 # Auto-Compact
 # =============================================================================
@@ -120,16 +131,21 @@ run_auto_compact() {
         return 1
     fi
 
+    # /context and /compact must target this Ralph session's Claude session,
+    # never "the most recent conversation in this directory" (--continue).
+    local claude_uuid
+    claude_uuid=$(get_claude_session_uuid "$session_id")
+    if [[ -z "$claude_uuid" ]]; then
+        log_session "$session_id" "WARN" "No Claude session yet, nothing to compact"
+        return 1
+    fi
+
     # Check if context is above minimum threshold before compacting
     if [[ "$CONTEXT_MIN_THRESHOLD" -gt 0 ]]; then
         local context_info
-        if command -v timeout &> /dev/null; then
-            context_info=$(timeout 10s "${CLAUDE_CMD[@]}" -p "/context" 2>/dev/null | head -5)
-        else
-            context_info=$("${CLAUDE_CMD[@]}" -p "/context" 2>/dev/null | head -5)
-        fi
+        context_info=$(probe_context_usage "$claude_uuid")
         local current_usage
-        current_usage=$(echo "$context_info" | grep -oP '\d+(?=%)' | head -1)
+        current_usage=$(echo "$context_info" | grep -oP '\d+(?=%)' | head -1 || true)
 
         if [[ -n "$current_usage" && "$current_usage" -lt "$CONTEXT_MIN_THRESHOLD" ]]; then
             log_session "$session_id" "INFO" "Context at ${current_usage}% - below minimum threshold (${CONTEXT_MIN_THRESHOLD}%), skipping compact"
@@ -145,8 +161,8 @@ run_auto_compact() {
 
         # Handle overflow strategy
         local overflow_result
-        overflow_result=$(handle_max_compacts_reached "$session_id")
-        local overflow_status=$?
+        local overflow_status=0
+        overflow_result=$(handle_max_compacts_reached "$session_id") || overflow_status=$?
 
         if [[ $overflow_status -eq 0 && -n "$overflow_result" ]]; then
             # New session ID returned - signal continuation
@@ -185,11 +201,10 @@ run_auto_compact() {
 
     # Execute /compact via Claude CLI
     local compact_output
-    local compact_status
+    local compact_status=0
 
     if command -v timeout &> /dev/null; then
-        compact_output=$(timeout 60s "${CLAUDE_CMD[@]}" --continue -p "/compact" 2>&1)
-        compact_status=$?
+        compact_output=$(timeout 60s "${CLAUDE_CMD[@]}" --resume "$claude_uuid" -p "/compact" 2>&1) || compact_status=$?
 
         # Handle timeout specifically (exit code 124)
         if [[ $compact_status -eq 124 ]]; then
@@ -198,8 +213,7 @@ run_auto_compact() {
             return 1
         fi
     else
-        compact_output=$("${CLAUDE_CMD[@]}" --continue -p "/compact" 2>&1)
-        compact_status=$?
+        compact_output=$("${CLAUDE_CMD[@]}" --resume "$claude_uuid" -p "/compact" 2>&1) || compact_status=$?
     fi
 
     if [[ $compact_status -eq 0 ]]; then
@@ -359,10 +373,10 @@ create_continuation_session() {
     elif command -v xxd &>/dev/null; then
         random_suffix=$(head -c 4 /dev/urandom | xxd -p)
     elif command -v od &>/dev/null; then
-        random_suffix=$(head -c 4 /dev/urandom | od -An -tx1 | tr -d ' \n')
+        random_suffix=$(head -c 4 /dev/urandom | od -An -tx1 | tr -d ' \n') || true
     else
         # Fallback: use $RANDOM (less entropy but portable)
-        random_suffix=$(printf '%04x%04x' $RANDOM $RANDOM | head -c 8)
+        random_suffix=$(printf '%04x%04x' $RANDOM $RANDOM | head -c 8) || true
     fi
 
     local new_session_id="ralph-cont-${timestamp}-${random_suffix}"
@@ -404,18 +418,19 @@ check_preventive_compact() {
         return 1
     fi
 
+    # Nothing to measure before the first Claude call of this session.
+    local claude_uuid
+    claude_uuid=$(get_claude_session_uuid "$session_id")
+    [[ -z "$claude_uuid" ]] && return 1
+
     # Try to get context usage from Claude CLI
     # Note: This is a best-effort check, Claude may not always report usage
     local context_info
-    if command -v timeout &> /dev/null; then
-        context_info=$(timeout 10s "${CLAUDE_CMD[@]}" -p "/context" 2>/dev/null | head -5)
-    else
-        context_info=$("${CLAUDE_CMD[@]}" -p "/context" 2>/dev/null | head -5)
-    fi
+    context_info=$(probe_context_usage "$claude_uuid")
 
     # Try to extract percentage from output
     local usage
-    usage=$(echo "$context_info" | grep -oP '\d+(?=%)' | head -1)
+    usage=$(echo "$context_info" | grep -oP '\d+(?=%)' | head -1 || true)
 
     if [[ -n "$usage" && "$usage" -ge "$CONTEXT_PREVENTIVE_THRESHOLD" ]]; then
         print_warning "${MSG_CONTEXT_PREVENTIVE:-Context at ${usage}% - running preventive compact}"
@@ -423,7 +438,7 @@ check_preventive_compact() {
 
         # Save progress before preventive compact
         if type save_sprint_progress &>/dev/null; then
-            save_sprint_progress "$session_id"
+            save_sprint_progress "$session_id" || print_verbose "No sprint progress file to save"
         fi
 
         run_auto_compact "$session_id"

package/Tools/Ralph/lib/context-reconstruction.sh

@@ -109,7 +109,7 @@ build_git_section() {
     echo ""
     echo "### Uncommitted Changes"
     local status
-    status=$(git status --porcelain 2>/dev/null | head -10)
+    status=$(git status --porcelain 2>/dev/null | head -10) || true
     if [[ -n "$status" ]]; then
         echo "\`\`\`"
         echo "$status"

package/Tools/Ralph/lib/dod-templates.sh

@@ -18,7 +18,7 @@ get_dod_template() {
 
     # Normalize project type (remove version suffixes)
     local base_type
-    base_type=$(echo "$project_type" | sed 's/-[0-9.]*$//' | sed 's/-typescript$//')
+    base_type=$(echo "$project_type" | sed 's/-[0-9.]*$//' | sed 's/-typescript$//') || true
 
     # Map to template file
     local template_file=""
@@ -69,7 +69,7 @@ get_dod_template_path() {
     local templates_dir="${2:-$DOD_TEMPLATES_DIR}"
 
     local base_type
-    base_type=$(echo "$project_type" | sed 's/-[0-9.]*$//' | sed 's/-typescript$//')
+    base_type=$(echo "$project_type" | sed 's/-[0-9.]*$//' | sed 's/-typescript$//') || true
 
     case "$base_type" in
         symfony|laravel|php)

package/Tools/Ralph/lib/dod-validator.sh

@@ -9,7 +9,7 @@ set -euo pipefail
 DOD_COMPLETION_MARKER="${DOD_COMPLETION_MARKER:-<promise>COMPLETE</promise>}"
 
 # DoD validator types
-declare -A DOD_VALIDATORS=(
+declare -gA DOD_VALIDATORS=(
     ["command"]="validate_command"
     ["output_contains"]="validate_output_contains"
     ["file_changed"]="validate_file_changed"
@@ -27,12 +27,12 @@ validate_dod() {
 
     # If no config, use simple completion marker check
     if [[ -z "$config_file" || ! -f "$config_file" ]]; then
-        return $(validate_simple_completion "$output")
+        validate_simple_completion "$output"; return
     fi
 
     # Check if yq is available for YAML parsing
     if ! command -v yq &> /dev/null; then
-        return $(validate_simple_completion "$output")
+        validate_simple_completion "$output"; return
     fi
 
     # Get DoD checklist from config
@@ -44,7 +44,7 @@ validate_dod() {
         if [[ -n "$marker" ]]; then
             DOD_COMPLETION_MARKER="$marker"
         fi
-        return $(validate_simple_completion "$output")
+        validate_simple_completion "$output"; return
     fi
 
     # Process checklist items
@@ -52,14 +52,14 @@ validate_dod() {
     local results=()
 
     # Get count of checklist items
-    local count=$(echo "$checklist" | yq e 'length' -)
+    local count=$(echo "$checklist" | yq e 'length' -) || true
 
     for ((i=0; i<count; i++)); do
         local item=$(yq e ".definition_of_done.checklist[$i]" "$config_file")
-        local id=$(echo "$item" | yq e '.id' -)
-        local name=$(echo "$item" | yq e '.name' -)
-        local type=$(echo "$item" | yq e '.type' -)
-        local required=$(echo "$item" | yq e '.required // true' -)
+        local id=$(echo "$item" | yq e '.id' -) || true
+        local name=$(echo "$item" | yq e '.name' -) || true
+        local type=$(echo "$item" | yq e '.type' -) || true
+        local required=$(echo "$item" | yq e '.required // true' -) || true
 
         # Validate based on type
         local passed=false
@@ -67,7 +67,7 @@ validate_dod() {
 
         case "$type" in
             command)
-                local cmd=$(echo "$item" | yq e '.command' -)
+                local cmd=$(echo "$item" | yq e '.command' -) || true
                 if validate_command "$cmd"; then
                     passed=true
                     message="Command passed"
@@ -76,7 +76,7 @@ validate_dod() {
                 fi
                 ;;
             output_contains)
-                local pattern=$(echo "$item" | yq e '.pattern' -)
+                local pattern=$(echo "$item" | yq e '.pattern' -) || true
                 if validate_output_contains "$output" "$pattern"; then
                     passed=true
                     message="Pattern found"
@@ -85,7 +85,7 @@ validate_dod() {
                 fi
                 ;;
             file_changed)
-                local pattern=$(echo "$item" | yq e '.pattern' -)
+                local pattern=$(echo "$item" | yq e '.pattern' -) || true
                 if validate_file_changed "$pattern"; then
                     passed=true
                     message="Files changed"
@@ -94,7 +94,7 @@ validate_dod() {
                 fi
                 ;;
             hook)
-                local script=$(echo "$item" | yq e '.script' -)
+                local script=$(echo "$item" | yq e '.script' -) || true
                 if validate_hook "$script" "$output"; then
                     passed=true
                     message="Hook passed"
@@ -103,7 +103,7 @@ validate_dod() {
                 fi
                 ;;
             human)
-                local prompt=$(echo "$item" | yq e '.prompt // ""' -)
+                local prompt=$(echo "$item" | yq e '.prompt // ""' -) || true
                 if validate_human "$name" "$prompt"; then
                     passed=true
                     message="Human approved"
@@ -209,13 +209,13 @@ validate_file_changed() {
 
     # Use git to check for changes matching pattern
     if command -v git &> /dev/null && git rev-parse --git-dir &> /dev/null; then
-        local changes=$(git status --porcelain 2>/dev/null | grep -E "$pattern" | wc -l)
+        local changes=$(git status --porcelain 2>/dev/null | grep -E "$pattern" | wc -l) || true
         if [[ $changes -gt 0 ]]; then
             return 0
         fi
     else
         # Fallback: check for recently modified files
-        local changes=$(find . -name "$pattern" -mmin -5 2>/dev/null | wc -l)
+        local changes=$(find . -name "$pattern" -mmin -5 2>/dev/null | wc -l) || true
         if [[ $changes -gt 0 ]]; then
             return 0
         fi
@@ -381,7 +381,7 @@ export_dod_status() {
 
     # Count checks
     local total
-    total=$(echo "$checklist" | yq e 'length' -)
+    total=$(echo "$checklist" | yq e 'length' -) || total=0
 
     local required=0
     for ((i=0; i<total; i++)); do
@@ -424,7 +424,7 @@ get_dod_summary() {
 
     # Build summary
     local count
-    count=$(echo "$checklist" | yq e 'length' -)
+    count=$(echo "$checklist" | yq e 'length' -) || count=0
 
     local checks="["
     for ((i=0; i<count; i++)); do

package/Tools/Ralph/lib/escalation-service.sh

@@ -21,7 +21,7 @@ ESCALATION_RESOLVED_DIR=""
 ESCALATION_AUDIT_FILE=""
 
 # Escalation priorities
-declare -A ESCALATION_PRIORITIES=(
+declare -gA ESCALATION_PRIORITIES=(
     ["critical"]=1
     ["high"]=2
     ["medium"]=3
@@ -421,7 +421,7 @@ build_slack_payload() {
 
     local title="Ralph Escalation: $event"
     local truncated_details
-    truncated_details=$(echo "$details" | head -c 500 | tr '\n' ' ')
+    truncated_details=$(echo "$details" | head -c 500 | tr '\n' ' ') || true
 
     jq -n \
         --arg color "$color" \
@@ -441,7 +441,7 @@ build_teams_payload() {
     [[ "$event" == "resolved" ]] && color="good"
 
     local truncated_details
-    truncated_details=$(echo "$details" | head -c 500 | tr '\n' ' ')
+    truncated_details=$(echo "$details" | head -c 500 | tr '\n' ' ') || true
 
     jq -n \
         --arg type "MessageCard" \
@@ -462,7 +462,7 @@ build_discord_payload() {
     [[ "$event" == "resolved" ]] && color=65280  # Green
 
     local truncated_details
-    truncated_details=$(echo "$details" | head -c 500 | tr '\n' ' ')
+    truncated_details=$(echo "$details" | head -c 500 | tr '\n' ' ') || true
 
     jq -n \
         --arg title "Ralph Escalation: $event" \
@@ -479,7 +479,7 @@ build_generic_payload() {
     local id="$1" event="$2" level="$3" error="$4" details="$5" session="$6"
 
     local truncated_details
-    truncated_details=$(echo "$details" | head -c 500 | tr '\n' ' ')
+    truncated_details=$(echo "$details" | head -c 500 | tr '\n' ' ') || true
 
     jq -n \
         --arg event "$event" \

package/Tools/Ralph/lib/hooks-generator.sh

@@ -95,7 +95,8 @@ generate_hooks_config() {
     # Merge with existing settings
     local merged
     if command -v jq &>/dev/null; then
-        merged=$(echo "$existing_settings" | jq --argjson hooks "$hooks_config" '. + {hooks: $hooks}')
+        merged=$(echo "$existing_settings" | jq --argjson hooks "$hooks_config" '. + {hooks: $hooks}') \
+            || merged="{\"hooks\": $hooks_config}"
     else
         # Fallback: just write hooks config
         merged="{\"hooks\": $hooks_config}"

package/Tools/Ralph/lib/loop-finalizer.sh

@@ -56,7 +56,7 @@ ralph_finalize_loop() {
 
     # Save sprint progress before summary
     if type save_sprint_progress &>/dev/null; then
-        save_sprint_progress "$session_id"
+        save_sprint_progress "$session_id" || print_verbose "No sprint progress file to save"
     fi
 
     # Save metrics export

package/Tools/Ralph/lib/loop.sh

@@ -13,6 +13,30 @@ CLAUDE_ARGS="${CLAUDE_ARGS:-}"
 # Claude Invocation
 # =============================================================================
 
+# Print a random RFC 4122 v4 UUID (`claude --session-id` requires a valid UUID).
+generate_uuid() {
+    if [[ -r /proc/sys/kernel/random/uuid ]]; then
+        cat /proc/sys/kernel/random/uuid
+    elif command -v uuidgen &> /dev/null; then
+        uuidgen | tr '[:upper:]' '[:lower:]'
+    else
+        local hex
+        hex=$(od -An -N16 -tx1 /dev/urandom | tr -d ' \n') || true
+        printf '%s-%s-4%s-%x%s-%s\n' "${hex:0:8}" "${hex:8:4}" "${hex:13:3}" \
+            $(( (0x${hex:16:1} & 0x3) | 0x8 )) "${hex:17:3}" "${hex:20:12}"
+    fi
+}
+
+# Print the Claude session UUID pinned to a Ralph session, or nothing if
+# Claude has not been invoked yet for it. Always succeeds (set -e safe).
+get_claude_session_uuid() {
+    local id_file="$RALPH_SESSION_BASE/sessions/$1/claude_session_id"
+    if [[ -n "$1" && -s "$id_file" ]]; then
+        cat "$id_file"
+    fi
+    return 0
+}
+
 invoke_claude() {
     local session_id="$1"
     local prompt="$2"
@@ -25,9 +49,21 @@ invoke_claude() {
     local -a cmd
     IFS=' ' read -r -a cmd <<< "${CLAUDE_COMMAND:-claude}"
 
-    # Add continue flag if we have a session
+    # Pin an explicit Claude session per Ralph session. `--continue` resumes
+    # "the most recent conversation in this directory", which parallel workers
+    # (and unrelated user sessions) would share.
     if [[ -n "$session_id" ]]; then
-        cmd+=(--continue)
+        local claude_session_uuid
+        claude_session_uuid=$(get_claude_session_uuid "$session_id")
+        if [[ -n "$claude_session_uuid" ]]; then
+            cmd+=(--resume "$claude_session_uuid")
+        else
+            local id_file="$RALPH_SESSION_BASE/sessions/$session_id/claude_session_id"
+            claude_session_uuid=$(generate_uuid)
+            mkdir -p "$(dirname "$id_file")"
+            echo "$claude_session_uuid" > "$id_file"
+            cmd+=(--session-id "$claude_session_uuid")
+        fi
     fi
 
     # Add prompt
@@ -39,12 +75,11 @@ invoke_claude() {
     # Execute with timeout
     local timeout_sec=$((timeout / 1000))
     local output
-    local exit_code
+    local exit_code=0
 
     # Use timeout command if available
     if command -v timeout &> /dev/null; then
-        output=$(timeout "${timeout_sec}s" "${cmd[@]}" "$prompt" 2>&1)
-        exit_code=$?
+        output=$(timeout "${timeout_sec}s" "${cmd[@]}" "$prompt" 2>&1) || exit_code=$?
 
         # Check for timeout (exit code 124)
         if [[ $exit_code -eq 124 ]]; then
@@ -53,8 +88,7 @@ invoke_claude() {
         fi
     else
         # Fallback without timeout
-        output=$("${cmd[@]}" "$prompt" 2>&1)
-        exit_code=$?
+        output=$("${cmd[@]}" "$prompt" 2>&1) || exit_code=$?
     fi
 
     # Log result
@@ -104,7 +138,7 @@ detect_file_changes() {
 
     # Use git to detect changes if available
     if command -v git &> /dev/null && git rev-parse --git-dir &> /dev/null; then
-        local changes=$(git status --porcelain 2>/dev/null | wc -l)
+        local changes=$(git status --porcelain 2>/dev/null | wc -l) || true
         log_session "$session_id" "DEBUG" "Detected $changes file changes"
         echo "$changes"
     else
@@ -112,7 +146,7 @@ detect_file_changes() {
         local changes=0
         for dir in src lib app tests; do
             if [[ -d "$dir" ]]; then
-                local recent=$(find "$dir" -type f -mmin -1 2>/dev/null | wc -l)
+                local recent=$(find "$dir" -type f -mmin -1 2>/dev/null | wc -l) || true
                 changes=$((changes + recent))
             fi
         done
@@ -219,7 +253,7 @@ get_loop_state() {
         status: (.status // "unknown"),
         circuit_breaker: (.circuit_breaker // {}),
         dod_results: (.dod_results // [])
-    }' 2>/dev/null)
+    }' 2>/dev/null) || result=""
 
     if [[ -n "$result" ]]; then
         echo "$result"

package/Tools/Ralph/lib/metrics-exporter.sh

@@ -12,7 +12,7 @@ METRICS_REALTIME_ENABLED="${METRICS_REALTIME_ENABLED:-true}"
 METRICS_REALTIME_INTERVAL="${METRICS_REALTIME_INTERVAL:-1000}"
 
 # Metrics data
-declare -A METRICS_DATA
+declare -gA METRICS_DATA
 METRICS_START_TIME=0
 METRICS_ITERATION_TIMES=()
 METRICS_CONTEXT_SAMPLES=()

package/Tools/Ralph/lib/parallel-manager.sh

@@ -17,8 +17,9 @@ PARALLEL_RESOURCE_LIMIT_CPU="${PARALLEL_RESOURCE_LIMIT_CPU:-80}"
 PARALLEL_RESOURCE_LIMIT_MEM="${PARALLEL_RESOURCE_LIMIT_MEM:-80}"
 
 # Session tracking
-declare -A PARALLEL_SESSIONS
-declare -A PARALLEL_PIDS
+# `=()`: a declared-but-unassigned array is "unbound" for `${#arr[@]}` under set -u
+declare -gA PARALLEL_SESSIONS=()
+declare -gA PARALLEL_PIDS=()
 PARALLEL_SESSION_COUNT=0
 PARALLEL_COMPLETED_COUNT=0
 PARALLEL_FAILED_COUNT=0
@@ -36,6 +37,8 @@ PARALLEL_WORKER_DIR=""
 init_parallel_manager() {
     PARALLEL_BASE_DIR="${RALPH_SESSION_BASE:-.ralph}/parallel"
     mkdir -p "$PARALLEL_BASE_DIR"
+    # Absolute: workers cd into their own worktree
+    PARALLEL_BASE_DIR="$(cd "$PARALLEL_BASE_DIR" && pwd)"
 
     PARALLEL_STATE_FILE="$PARALLEL_BASE_DIR/state.yaml"
     PARALLEL_DEPENDENCY_GRAPH="$PARALLEL_BASE_DIR/dependencies.json"
@@ -102,10 +105,11 @@ build_dependency_graph() {
     local bmad_dir="${BMAD_DIR:-.bmad}"
     local status_file="$bmad_dir/sprint-status.yaml"
 
+    # Without a status file (or yq), all stories are independent nodes: the
+    # graph must still list them, get_ready_stories reads it.
+    local with_deps=true
     if [[ ! -f "$status_file" ]] || ! command -v yq &>/dev/null; then
-        # No dependencies, all stories are independent
-        echo '{"nodes":{},"edges":[]}'
-        return
+        with_deps=false
     fi
 
     local nodes="{}"
@@ -113,17 +117,20 @@ build_dependency_graph() {
 
     for story_id in $stories; do
         # Get story dependencies
-        local deps
-        deps=$(yq ".stories.${story_id}.blocked_by // []" "$status_file" 2>/dev/null)
+        local deps="[]"
+        if [[ "$with_deps" == "true" ]]; then
+            deps=$(yq ".stories.${story_id}.blocked_by // []" "$status_file" 2>/dev/null) || deps="[]"
+        fi
 
-        # Add node
-        nodes=$(echo "$nodes" | jq --arg id "$story_id" '. + {($id): {"status": "pending", "deps": []}}')
+        # Add node (on jq failure, keep the previous value: `next` buffers it)
+        local next
+        next=$(echo "$nodes" | jq --arg id "$story_id" '. + {($id): {"status": "pending", "deps": []}}') && nodes="$next"
 
         # Add edges for dependencies
         if [[ "$deps" != "[]" && "$deps" != "null" ]]; then
-            for dep in $(echo "$deps" | jq -r '.[]' 2>/dev/null); do
-                edges=$(echo "$edges" | jq --arg from "$dep" --arg to "$story_id" '. + [{"from": $from, "to": $to}]')
-                nodes=$(echo "$nodes" | jq --arg id "$story_id" --arg dep "$dep" '.[$id].deps += [$dep]')
+            for dep in $(echo "$deps" | jq -r '.[]' 2>/dev/null || true); do
+                next=$(echo "$edges" | jq --arg from "$dep" --arg to "$story_id" '. + [{"from": $from, "to": $to}]') && edges="$next"
+                next=$(echo "$nodes" | jq --arg id "$story_id" --arg dep "$dep" '.[$id].deps += [$dep]') && nodes="$next"
             done
         fi
     done
@@ -144,18 +151,20 @@ get_ready_stories() {
     fi
 
     # Find nodes with status=pending and all deps completed
+    # ($root: jq has no `$.` root accessor — that syntax failed to compile)
     jq -r '
+        . as $root |
         .nodes | to_entries[] |
         select(.value.status == "pending") |
         select(
             (.value.deps | length) == 0 or
             (
                 .value.deps as $deps |
-                ($deps | map(. as $d | $.nodes[$d].status == "completed") | all)
+                ($deps | map(. as $d | $root.nodes[$d].status == "completed") | all)
             )
         ) |
         .key
-    ' "$PARALLEL_DEPENDENCY_GRAPH" 2>/dev/null
+    ' "$PARALLEL_DEPENDENCY_GRAPH" 2>/dev/null || true
 }
 
 # Mark story as completed in dependency graph
@@ -171,6 +180,19 @@ mark_story_completed() {
     echo "$updated" > "$PARALLEL_DEPENDENCY_GRAPH"
 }
 
+# Mark story as running in dependency graph (leader only, at spawn time)
+mark_story_running() {
+    local story_id="$1"
+
+    if [[ ! -f "$PARALLEL_DEPENDENCY_GRAPH" ]] || ! command -v jq &>/dev/null; then
+        return 0
+    fi
+
+    local updated
+    updated=$(jq --arg id "$story_id" '.nodes[$id].status = "running"' "$PARALLEL_DEPENDENCY_GRAPH")
+    echo "$updated" > "$PARALLEL_DEPENDENCY_GRAPH"
+}
+
 # Mark story as failed in dependency graph
 mark_story_failed() {
     local story_id="$1"
@@ -211,11 +233,11 @@ check_resource_availability() {
         mem_usage=$(free | grep Mem | awk '{print int($3/$2 * 100)}' 2>/dev/null || echo "0")
     elif [[ "$(uname)" == "Darwin" ]]; then
         local pages_free pages_active pages_inactive pages_speculative pages_wired
-        pages_free=$(vm_stat | grep "Pages free" | awk '{print $3}' | tr -d '.')
-        pages_active=$(vm_stat | grep "Pages active" | awk '{print $3}' | tr -d '.')
-        pages_inactive=$(vm_stat | grep "Pages inactive" | awk '{print $3}' | tr -d '.')
-        pages_speculative=$(vm_stat | grep "Pages speculative" | awk '{print $3}' | tr -d '.')
-        pages_wired=$(vm_stat | grep "Pages wired" | awk '{print $4}' | tr -d '.')
+        pages_free=$(vm_stat | grep "Pages free" | awk '{print $3}' | tr -d '.') || pages_free=0
+        pages_active=$(vm_stat | grep "Pages active" | awk '{print $3}' | tr -d '.') || pages_active=0
+        pages_inactive=$(vm_stat | grep "Pages inactive" | awk '{print $3}' | tr -d '.') || pages_inactive=0
+        pages_speculative=$(vm_stat | grep "Pages speculative" | awk '{print $3}' | tr -d '.') || pages_speculative=0
+        pages_wired=$(vm_stat | grep "Pages wired" | awk '{print $4}' | tr -d '.') || pages_wired=0
         local total=$((pages_free + pages_active + pages_inactive + pages_speculative + pages_wired))
         local used=$((pages_active + pages_wired))
         mem_usage=$((used * 100 / total))
@@ -232,9 +254,7 @@ check_resource_availability() {
 # Get number of available slots
 get_available_slots() {
     local active_count=0
-    if [[ -v PARALLEL_PIDS ]]; then
-        active_count=${#PARALLEL_PIDS[@]}
-    fi
+    active_count=${#PARALLEL_PIDS[@]}
     local available=$((PARALLEL_MAX_CONCURRENT - active_count))
 
     # Further limit if resources are constrained
@@ -279,7 +299,7 @@ EOF
     local ralph_script=""
     for path in "${SCRIPT_DIR}/ralph.sh" "Tools/Ralph/ralph.sh" "$(dirname "${BASH_SOURCE[0]}")/../ralph.sh"; do
         if [[ -f "$path" ]]; then
-            ralph_script="$path"
+            ralph_script="$(cd "$(dirname "$path")" && pwd)/$(basename "$path")"
             break
         fi
     done
@@ -290,19 +310,35 @@ EOF
     fi
 
     # Build command
-    local cmd="$ralph_script"
-    [[ -n "$config" ]] && cmd="$cmd --config=$config"
+    local -a cmd=("$ralph_script")
+    [[ -n "$config" ]] && cmd+=("--config=$config")
+
+    # Isolate the worker's working tree (one git worktree per session)
+    local worktree_dir=""
+    if ! worktree_dir=$(create_worker_worktree "$session_id"); then
+        worktree_dir=""
+        print_warning "No git worktree for $session_id: worker shares the current directory"
+    fi
 
     # Spawn in background
     # Workers write to individual temp files (single-writer pattern).
     # The leader merges results after all workers complete.
     local worker_id="${story_id}-$$-$(date +%s)"
     (
-        cd "$(pwd)" || exit 1
+        if [[ -n "$worktree_dir" ]]; then
+            cd "$worktree_dir" || exit 1
+        fi
+        # Per-worker Ralph state (incl. the Claude session UUID) under the
+        # leader's .ralph/, so it survives the worktree removal.
+        export RALPH_SESSION_BASE="$session_dir/ralph"
 
         local output
-        output=$($cmd "$prompt" 2>&1)
-        local status=$?
+        local status=0
+        output=$("${cmd[@]}" "$prompt" 2>&1) || status=$?
+
+        if [[ -n "$worktree_dir" ]] && ! cleanup_worker_worktree "$worktree_dir" "$story_id"; then
+            output+=$'\n'"[WARN] Worktree kept: $worktree_dir"
+        fi
 
         # Save output (per-session dir, no conflict)
         echo "$output" > "$session_dir/output.log"
@@ -340,6 +376,30 @@ EOF
     echo "$session_id"
 }
 
+# Create a dedicated git worktree on branch ralph/<session_id> so parallel
+# workers never share a working tree. Prints its path; fails outside git.
+create_worker_worktree() {
+    local session_id="$1"
+    local worktree_dir="$PARALLEL_BASE_DIR/worktrees/$session_id"
+
+    git rev-parse --is-inside-work-tree &> /dev/null || return 1
+    git worktree add -q -b "ralph/$session_id" "$worktree_dir" HEAD &> /dev/null || return 1
+    echo "$worktree_dir"
+}
+
+# Commit leftover changes as WIP on the worker branch, then remove the
+# worktree. If the commit fails, the dirty worktree is kept (no data loss).
+cleanup_worker_worktree() {
+    local worktree_dir="$1"
+    local story_id="$2"
+
+    if [[ -n "$(git -C "$worktree_dir" status --porcelain)" ]]; then
+        git -C "$worktree_dir" add -A
+        git -C "$worktree_dir" commit -q -m "wip(ralph): $story_id" || return 1
+    fi
+    git -C "$worktree_dir" worktree remove "$worktree_dir"
+}
+
 # =============================================================================
 # Session Management
 # =============================================================================
@@ -359,9 +419,9 @@ collect_completed_sessions() {
             local session_id="${PARALLEL_PIDS[$pid]}"
             local story_id="${PARALLEL_SESSIONS[$session_id]}"
 
-            # Check exit status
-            wait "$pid" 2>/dev/null
-            local exit_code=$?
+            # Check exit status (a failed worker must not kill the leader)
+            local exit_code=0
+            wait "$pid" 2>/dev/null || exit_code=$?
 
             if [[ $exit_code -eq 0 ]]; then
                 completed+=("$story_id")
@@ -395,9 +455,7 @@ wait_all_sessions() {
     start_time=$(date +%s)
 
     local active_count=0
-    if [[ -v PARALLEL_PIDS ]]; then
-        active_count=${#PARALLEL_PIDS[@]}
-    fi
+    active_count=${#PARALLEL_PIDS[@]}
 
     while [[ $active_count -gt 0 ]]; do
         collect_completed_sessions > /dev/null
@@ -415,9 +473,7 @@ wait_all_sessions() {
 
         # Update active count
         active_count=0
-        if [[ -v PARALLEL_PIDS ]]; then
-            active_count=${#PARALLEL_PIDS[@]}
-        fi
+        active_count=${#PARALLEL_PIDS[@]}
     done
 
     return 0
@@ -426,9 +482,7 @@ wait_all_sessions() {
 # Get active session count
 get_active_count() {
     local count=0
-    if [[ -v PARALLEL_PIDS ]]; then
-        count=${#PARALLEL_PIDS[@]}
-    fi
+    count=${#PARALLEL_PIDS[@]}
     echo "$count"
 }
 
@@ -455,7 +509,7 @@ process_stories_parallel() {
 
     local processed=0
     local total
-    total=$(echo "$stories" | wc -w | tr -d ' ')
+    total=$(echo "$stories" | wc -w | tr -d ' ') || total=0
 
     while [[ $processed -lt $total ]]; do
         # Collect completed sessions
@@ -473,9 +527,6 @@ process_stories_parallel() {
             for story_id in $ready; do
                 [[ $slots -le 0 ]] && break
 
-                # Skip if already processed
-                [[ -n "${PARALLEL_SESSIONS[$story_id]:-}" ]] && continue
-
                 # Build prompt
                 local prompt="$prompt_template $story_id"
 
@@ -488,10 +539,15 @@ process_stories_parallel() {
                     prompt="Implement user story $story_id: $title. Follow TDD approach."
                 fi
 
-                # Spawn session
-                spawn_session "$story_id" "$prompt"
-                ((slots--))
-                ((processed++))
+                # Spawn session. "running" keeps get_ready_stories (pending
+                # only) from re-spawning it before its report is merged.
+                if spawn_session "$story_id" "$prompt"; then
+                    mark_story_running "$story_id"
+                else
+                    mark_story_failed "$story_id"
+                fi
+                slots=$((slots - 1))
+                processed=$((processed + 1))
             done
         fi
 
@@ -503,6 +559,9 @@ process_stories_parallel() {
     print_info "Waiting for remaining sessions to complete..."
     wait_all_sessions
 
+    # Drop stale worktree metadata (e.g. a worker killed before its cleanup)
+    git worktree prune &> /dev/null || true
+
     # Print summary
     print_parallel_summary
 }
@@ -567,7 +626,7 @@ merge_worker_reports() {
         if [[ "$dry_run" == "true" ]]; then
             print_info "DRY RUN - Would merge: session=$session_id story=$story_id status=$status" 2>/dev/null \
                 || echo "[INFO] DRY RUN - Would merge: session=$session_id story=$story_id status=$status"
-            ((merged_count++))
+            merged_count=$((merged_count + 1))
             continue
         fi
 
@@ -591,7 +650,7 @@ merge_worker_reports() {
         fi
 
         rm -f "$report_file"
-        ((merged_count++))
+        merged_count=$((merged_count + 1))
     done
 
     # Update efficiency after merge
@@ -781,6 +840,11 @@ cmd_parallel_manager() {
             echo "Single-Writer Pattern:"
             echo "  Background workers write to .ralph/parallel/workers/worker-{id}.yaml"
             echo "  Only the leader merges results into shared state files"
+            echo ""
+            echo "Isolation:"
+            echo "  Each worker runs in its own git worktree (branch ralph/<session>),"
+            echo "  removed at the end of the run (leftover changes committed as WIP)."
+            echo "  Each Ralph session pins its own Claude session (--session-id, then --resume)."
             ;;
         *)
             echo "Usage: parallel-manager.sh <command> [args]"

package/Tools/Ralph/lib/project-detector.sh

@@ -72,7 +72,7 @@ detect_symfony() {
 
         # Detect Symfony version
         local version
-        version=$(grep -o '"symfony/framework-bundle"[[:space:]]*:[[:space:]]*"[^"]*"' "$composer_file" | grep -o '[0-9]\+\.[0-9]\+' | head -1)
+        version=$(grep -o '"symfony/framework-bundle"[[:space:]]*:[[:space:]]*"[^"]*"' "$composer_file" | grep -o '[0-9]\+\.[0-9]\+' | head -1) || true
         if [[ -n "$version" ]]; then
             DETECTED_PROJECT_TYPE="symfony-$version"
         fi
@@ -325,7 +325,7 @@ detect_dotnet() {
 
     # Look for .csproj files
     local csproj_count
-    csproj_count=$(find "$project_dir" -maxdepth 3 -name "*.csproj" 2>/dev/null | wc -l)
+    csproj_count=$(find "$project_dir" -maxdepth 3 -name "*.csproj" 2>/dev/null | wc -l) || csproj_count=0
 
     if [[ $csproj_count -gt 0 ]]; then
         DETECTED_PROJECT_TYPE="dotnet"
@@ -340,7 +340,7 @@ detect_dotnet() {
 
         # Detect specific framework
         local csproj_file
-        csproj_file=$(find "$project_dir" -maxdepth 3 -name "*.csproj" 2>/dev/null | head -1)
+        csproj_file=$(find "$project_dir" -maxdepth 3 -name "*.csproj" 2>/dev/null | head -1) || true
         if [[ -f "$csproj_file" ]]; then
             if grep -q 'Microsoft.NET.Sdk.Web' "$csproj_file" 2>/dev/null; then
                 DETECTED_PROJECT_TYPE="dotnet-web"

package/Tools/Ralph/lib/recovery-engine.sh

@@ -17,7 +17,7 @@ RECOVERY_AUTO_FIX_TESTS="${RECOVERY_AUTO_FIX_TESTS:-retry_tdd}"
 RECOVERY_AUTO_RETRY_TRANSIENT="${RECOVERY_AUTO_RETRY_TRANSIENT:-true}"
 
 # Error classification levels
-declare -A RECOVERY_LEVELS=(
+declare -gA RECOVERY_LEVELS=(
     [0]="transient"      # Auto-retry immediately
     [1]="recoverable"    # Auto-fix possible
     [2]="degraded"       # Continue with warning
@@ -25,14 +25,14 @@ declare -A RECOVERY_LEVELS=(
 )
 
 # Error patterns for classification
-declare -A ERROR_PATTERNS_TRANSIENT=(
+declare -gA ERROR_PATTERNS_TRANSIENT=(
     ["timeout"]="timeout|timed out|ETIMEDOUT"
     ["rate_limit"]="rate limit|429|too many requests"
     ["network"]="ECONNRESET|ECONNREFUSED|network error"
     ["temporary"]="temporary failure|try again|service unavailable|503"
 )
 
-declare -A ERROR_PATTERNS_RECOVERABLE=(
+declare -gA ERROR_PATTERNS_RECOVERABLE=(
     ["lint"]="lint error|eslint|phpcs|flake8|prettier|stylelint"
     ["test_fail"]="test failed|assertion failed|tests? (failed|failing)"
     ["deps"]="dependency|package not found|module not found|could not resolve"
@@ -40,14 +40,14 @@ declare -A ERROR_PATTERNS_RECOVERABLE=(
     ["type_error"]="type error|typescript error|type mismatch"
 )
 
-declare -A ERROR_PATTERNS_DEGRADED=(
+declare -gA ERROR_PATTERNS_DEGRADED=(
     ["docs"]="documentation|readme|changelog"
     ["optional_gate"]="optional.*gate|non-blocking"
     ["coverage"]="coverage below|coverage threshold"
     ["warning"]="warning:|deprecated"
 )
 
-declare -A ERROR_PATTERNS_BLOCKED=(
+declare -gA ERROR_PATTERNS_BLOCKED=(
     ["security"]="security vulnerability|CVE-|critical security|injection"
     ["architecture"]="architecture violation|circular dependency|breaking change"
     ["auth"]="authentication failed|unauthorized|permission denied"
@@ -55,7 +55,7 @@ declare -A ERROR_PATTERNS_BLOCKED=(
 )
 
 # Recovery strategies
-declare -A RECOVERY_STRATEGIES=(
+declare -gA RECOVERY_STRATEGIES=(
     ["lint"]="run_auto_lint_fix"
     ["test_fail"]="run_tdd_retry"
     ["deps"]="run_deps_install"
@@ -124,7 +124,7 @@ init_recovery_engine() {
 classify_error() {
     local error_output="$1"
     local error_lower
-    error_lower=$(echo "$error_output" | tr '[:upper:]' '[:lower:]')
+    error_lower=$(echo "$error_output" | tr '[:upper:]' '[:lower:]') || true
 
     # Check Level 3 - Blocked (security, architecture)
     for pattern_name in "${!ERROR_PATTERNS_BLOCKED[@]}"; do
@@ -415,7 +415,7 @@ run_tdd_retry() {
 
     # Try to parse test output
     if echo "$error_output" | grep -qE "FAIL|FAILED|Error:"; then
-        failing_tests=$(echo "$error_output" | grep -E "FAIL|FAILED|Error:" | head -5)
+        failing_tests=$(echo "$error_output" | grep -E "FAIL|FAILED|Error:" | head -5) || true
     fi
 
     # Update sprint progress with TDD phase

package/Tools/Ralph/lib/session.sh

@@ -23,10 +23,10 @@ generate_session_id() {
     elif command -v xxd &>/dev/null; then
         random=$(head -c 4 /dev/urandom | xxd -p)
     elif command -v od &>/dev/null; then
-        random=$(head -c 4 /dev/urandom | od -An -tx1 | tr -d ' \n')
+        random=$(head -c 4 /dev/urandom | od -An -tx1 | tr -d ' \n') || true
     else
         # Fallback: use $RANDOM (less entropy but portable)
-        random=$(printf '%04x%04x' $RANDOM $RANDOM | head -c 8)
+        random=$(printf '%04x%04x' $RANDOM $RANDOM | head -c 8) || true
     fi
 
     echo "ralph-${timestamp}-${random}"

package/Tools/Ralph/lib/sprint-conductor.sh

@@ -196,7 +196,7 @@ run_sprint_conductor_parallel() {
     fi
 
     local story_count
-    story_count=$(echo "$all_stories" | wc -w | tr -d ' ')
+    story_count=$(echo "$all_stories" | wc -w | tr -d ' ') || story_count=0
     log_conductor "Found $story_count stories for parallel processing"
 
     # Build dependency graph
@@ -749,7 +749,7 @@ build_story_prompt() {
         local title description acceptance_criteria
         title=$(yq ".stories.${story_id}.title" "$status_file" 2>/dev/null)
         description=$(yq ".stories.${story_id}.description" "$status_file" 2>/dev/null)
-        acceptance_criteria=$(yq ".stories.${story_id}.acceptance_criteria[]" "$status_file" 2>/dev/null | tr '\n' '; ')
+        acceptance_criteria=$(yq ".stories.${story_id}.acceptance_criteria[]" "$status_file" 2>/dev/null | tr '\n' '; ') || true
 
         prompt="Implement user story: $title
 

package/Tools/Ralph/lib/sprint-progress.sh

@@ -288,7 +288,7 @@ get_completed_tasks_count() {
 
 update_sprint_progress() {
     local section="$1"
-    local content="$2"
+    local content="${2:-}"  # optional: "compact" is called without content
 
     if [[ "$SPRINT_PROGRESS_ENABLED" != "true" ]]; then
         return 0
@@ -343,10 +343,10 @@ update_state_section() {
     local state_json="$1"
 
     # Parse JSON and update each field
-    local sprint=$(echo "$state_json" | grep -oP '"sprint":\s*"\K[^"]*' 2>/dev/null)
-    local current_us=$(echo "$state_json" | grep -oP '"current_us":\s*"\K[^"]*' 2>/dev/null)
-    local current_task=$(echo "$state_json" | grep -oP '"current_task":\s*"\K[^"]*' 2>/dev/null)
-    local phase=$(echo "$state_json" | grep -oP '"phase":\s*"\K[^"]*' 2>/dev/null)
+    local sprint=$(echo "$state_json" | grep -oP '"sprint":\s*"\K[^"]*' 2>/dev/null) || true
+    local current_us=$(echo "$state_json" | grep -oP '"current_us":\s*"\K[^"]*' 2>/dev/null) || true
+    local current_task=$(echo "$state_json" | grep -oP '"current_task":\s*"\K[^"]*' 2>/dev/null) || true
+    local phase=$(echo "$state_json" | grep -oP '"phase":\s*"\K[^"]*' 2>/dev/null) || true
 
     # Build list of sed patterns (escape special chars)
     local patterns=()
@@ -657,7 +657,7 @@ compact_on_sprint_start() {
     print_info "${MSG_CONTEXT_SPRINT_START:-Compact at sprint start for clean context}..."
 
     # Save initial state
-    save_sprint_progress "$session_id"
+    save_sprint_progress "$session_id" || print_verbose "No sprint progress file to save"
 
     # Run compact if available
     if type run_auto_compact &>/dev/null; then
@@ -688,7 +688,7 @@ compact_on_task_complete() {
     if [[ -n "$task_info" ]]; then
         update_sprint_progress "task_complete" "$task_info"
     fi
-    save_sprint_progress "$session_id"
+    save_sprint_progress "$session_id" || print_verbose "No sprint progress file to save"
 
     # Run compact
     if type run_auto_compact &>/dev/null; then
@@ -710,7 +710,7 @@ compact_on_us_complete() {
 
     if [[ "$SPRINT_COMPACT_ON_US_COMPLETE" != "true" ]]; then
         # Even if compact is disabled, we should save and checkpoint
-        save_sprint_progress "$session_id"
+        save_sprint_progress "$session_id" || print_verbose "No sprint progress file to save"
         if type create_checkpoint &>/dev/null; then
             create_checkpoint "$session_id" "us-complete-$us_id"
         fi
@@ -721,7 +721,7 @@ compact_on_us_complete() {
     print_info "${MSG_CONTEXT_US_COMPLETE:-US complete - running strategic compact}..."
 
     # Save and checkpoint
-    save_sprint_progress "$session_id"
+    save_sprint_progress "$session_id" || print_verbose "No sprint progress file to save"
     if type create_checkpoint &>/dev/null; then
         create_checkpoint "$session_id" "us-complete-$us_id"
     fi

package/Tools/Ralph/ralph.sh

@@ -499,14 +499,15 @@ run_ralph() {
 
         # Check for preventive compact (before hitting the limit)
         if type check_preventive_compact &>/dev/null; then
-            check_preventive_compact "$SESSION_ID"
+            check_preventive_compact "$SESSION_ID" || true
         fi
 
         # Check if we have a continuation prompt (after compact/session handoff)
         local effective_prompt="$PROMPT"
         if type get_context_continuation_prompt &>/dev/null; then
             local continuation_prompt
-            continuation_prompt=$(get_context_continuation_prompt)
+            # Returns 1 when there is no continuation context (nominal).
+            continuation_prompt=$(get_context_continuation_prompt) || true
             if [[ -n "$continuation_prompt" ]]; then
                 # Prepend continuation context to the prompt
                 effective_prompt="$continuation_prompt
@@ -520,9 +521,11 @@ $PROMPT"
 
         # Invoke Claude
         print_info "${MSG_INVOKING_CLAUDE}"
+        # `|| invoke_status=$?`: a failed call must reach the circuit breaker,
+        # not kill the loop through errexit.
         local response
-        response=$(invoke_claude "$SESSION_ID" "$effective_prompt" "$TIMEOUT")
-        local invoke_status=$?
+        local invoke_status=0
+        response=$(invoke_claude "$SESSION_ID" "$effective_prompt" "$TIMEOUT") || invoke_status=$?
 
         if [[ $invoke_status -ne 0 ]]; then
             print_error "${MSG_ERROR}: Claude invocation failed"
@@ -536,8 +539,8 @@ $PROMPT"
 
             if type run_auto_compact &>/dev/null; then
                 local compact_result
-                compact_result=$(run_auto_compact "$SESSION_ID")
-                local compact_status=$?
+                local compact_status=0
+                compact_result=$(run_auto_compact "$SESSION_ID") || compact_status=$?
 
                 case $compact_status in
                     0)
@@ -548,7 +551,7 @@ $PROMPT"
                         local retry_prompt="$PROMPT"
                         if type get_context_continuation_prompt &>/dev/null; then
                             local cont_prompt
-                            cont_prompt=$(get_context_continuation_prompt)
+                            cont_prompt=$(get_context_continuation_prompt) || true
                             if [[ -n "$cont_prompt" ]]; then
                                 retry_prompt="$cont_prompt
 
@@ -558,8 +561,8 @@ $PROMPT"
                             fi
                         fi
 
-                        response=$(invoke_claude "$SESSION_ID" "$retry_prompt" "$TIMEOUT")
-                        invoke_status=$?
+                        invoke_status=0
+                        response=$(invoke_claude "$SESSION_ID" "$retry_prompt" "$TIMEOUT") || invoke_status=$?
 
                         if [[ $invoke_status -ne 0 ]]; then
                             print_error "${MSG_ERROR}: Claude invocation failed after compact"
@@ -581,10 +584,10 @@ $PROMPT"
                         fi
 
                         # Retry with new session and handoff context
+                        invoke_status=0
                         response=$(invoke_claude "$SESSION_ID" "$handoff_prompt
 
-$PROMPT" "$TIMEOUT")
-                        invoke_status=$?
+$PROMPT" "$TIMEOUT") || invoke_status=$?
 
                         if [[ $invoke_status -ne 0 ]]; then
                             print_error "${MSG_ERROR}: Claude invocation failed in continuation session"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@the-bearded-bear/claude-craft",
-  "version": "8.26.0-next.2a54921",
+  "version": "8.26.0-next.defc34b",
   "description": "A comprehensive framework for AI-assisted development with Claude Code. Install standardized rules, agents, and commands for your projects.",
   "type": "module",
   "main": "cli/index.js",