shipwright-cli 2.4.0 → 3.1.0

package/scripts/sw-memory.sh

@@ -6,7 +6,7 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="2.4.0"
+VERSION="3.1.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_DIR="${REPO_DIR:-$(cd "$SCRIPT_DIR/.." && pwd)}"
 
@@ -34,15 +34,9 @@ if [[ "$(type -t emit_event 2>/dev/null)" != "function" ]]; then
     echo "${payload}}" >> "${HOME}/.shipwright/events.jsonl"
   }
 fi
-CYAN="${CYAN:-\033[38;2;0;212;255m}"
-PURPLE="${PURPLE:-\033[38;2;124;58;237m}"
-BLUE="${BLUE:-\033[38;2;0;102;255m}"
-GREEN="${GREEN:-\033[38;2;74;222;128m}"
-YELLOW="${YELLOW:-\033[38;2;250;204;21m}"
-RED="${RED:-\033[38;2;248;113;113m}"
-DIM="${DIM:-\033[2m}"
-BOLD="${BOLD:-\033[1m}"
-RESET="${RESET:-\033[0m}"
+# ─── Database (for dual-write memory to DB) ───────────────────────────────────
+# shellcheck source=sw-db.sh
+[[ -f "$SCRIPT_DIR/sw-db.sh" ]] && source "$SCRIPT_DIR/sw-db.sh"
 
 # ─── Intelligence Engine (optional) ──────────────────────────────────────────
 # shellcheck source=sw-intelligence.sh
@@ -52,6 +46,192 @@ RESET="${RESET:-\033[0m}"
 MEMORY_ROOT="${HOME}/.shipwright/memory"
 GLOBAL_MEMORY="${MEMORY_ROOT}/global.json"
 
+# ─── Domain keyword expansion (shared semantic concept) ──────────────────────
+
+_expand_domain_keywords() {
+    local text="$1"
+    local expanded="$text"
+
+    local dom
+    for dom in auth api db ui test deploy error perf; do
+        case "$dom" in
+            auth)   [[ "$text" =~ [aA]uth ]] && expanded="$expanded authentication authorization login session token credential permission access" ;;
+            api)    [[ "$text" =~ [aA]pi ]]  && expanded="$expanded endpoint route handler request response rest graphql" ;;
+            db)     [[ "$text" =~ [dD]b ]]   && expanded="$expanded database query migration schema model table sql" ;;
+            ui)     [[ "$text" =~ [uU]i ]]   && expanded="$expanded component view render template layout style css frontend" ;;
+            test)   [[ "$text" =~ [tT]est ]] && expanded="$expanded testing assertion coverage mock stub fixture spec" ;;
+            deploy) [[ "$text" =~ [dD]eploy ]] && expanded="$expanded deployment release publish ship ci cd pipeline" ;;
+            error)  [[ "$text" =~ [eE]rror ]] && expanded="$expanded exception failure crash bug issue defect" ;;
+            perf)   [[ "$text" =~ [pP]erf ]] && expanded="$expanded performance optimization speed latency throughput cache" ;;
+        esac
+    done
+
+    echo "$expanded"
+}
+
+# ─── Embedding & Semantic Search ───────────────────────────────────────────
+
+# Generate content hash for deduplication
+_memory_content_hash() {
+    echo -n "$1" | shasum -a 256 | cut -d' ' -f1
+}
+
+# TF-IDF-like ranked search across failures, patterns, decisions
+# Returns JSON array of {source_type, content_text} for injection compatibility
+memory_ranked_search() {
+    local query="$1"
+    local memory_dir="$2"
+    local max_results="${3:-5}"
+
+    # Use repo memory dir when not specified
+    if [[ -z "$memory_dir" ]] && type repo_memory_dir &>/dev/null 2>&1; then
+        memory_dir="$(repo_memory_dir)"
+    fi
+    memory_dir="${memory_dir:-$HOME/.shipwright/memory}"
+    if [[ ! -d "$memory_dir" ]]; then
+        info "Memory dir not found at ${memory_dir} — auto-creating"
+        mkdir -p "$memory_dir"
+        emit_event "memory.not_available" "path=$memory_dir" "action=auto_created"
+        echo "[]"
+        return 0
+    fi
+
+    # Extract and expand query keywords
+    local keywords
+    keywords=$(echo "$query" | tr '[:upper:]' '[:lower:]' | tr -cs '[:alnum:]' '\n' | sort -u | \
+        grep -vxE '^.{1,2}$|^(the|and|for|not|with|this|that|from)$' || true)
+    keywords=$(_expand_domain_keywords "$keywords" 2>/dev/null || echo "$keywords")
+
+    local results_file
+    results_file=$(mktemp)
+
+    # Search failures.json
+    if [[ -f "$memory_dir/failures.json" ]]; then
+        jq -c '.failures[]? // empty' "$memory_dir/failures.json" 2>/dev/null | while IFS= read -r entry; do
+            [[ -z "$entry" ]] && continue
+            local entry_text
+            entry_text=$(echo "$entry" | jq -r '(.pattern // "") + " " + (.root_cause // "") + " " + (.fix // "")' 2>/dev/null)
+            local score=0
+            while IFS= read -r kw; do
+                [[ -z "$kw" ]] && continue
+                if echo "$entry_text" | grep -qiF "$kw" 2>/dev/null; then
+                    score=$((score + 1))
+                fi
+            done <<< "$keywords"
+
+            # Boost by effectiveness
+            local effectiveness
+            effectiveness=$(echo "$entry" | jq -r '.fix_effectiveness_rate // 0' 2>/dev/null)
+            if [[ "$effectiveness" =~ ^[0-9]+$ ]] && [[ "$effectiveness" -gt 50 ]]; then
+                score=$((score + 2))
+            fi
+
+            if [[ "$score" -gt 0 ]]; then
+                local content
+                content=$(echo "$entry" | jq -r '(.pattern // "") + " | " + (.root_cause // "") + " | " + (.fix // "")' 2>/dev/null)
+                echo "${score}|{\"source_type\":\"failure\",\"content_text\":$(echo "$content" | jq -Rs .)}" >> "$results_file"
+            fi
+        done
+    fi
+
+    # Search decisions.json
+    if [[ -f "$memory_dir/decisions.json" ]]; then
+        jq -c '.decisions[]? // empty' "$memory_dir/decisions.json" 2>/dev/null | while IFS= read -r entry; do
+            [[ -z "$entry" ]] && continue
+            local entry_text
+            entry_text=$(echo "$entry" | jq -r '(.summary // "") + " " + (.detail // "") + " " + (.type // "")' 2>/dev/null)
+            local score=0
+            while IFS= read -r kw; do
+                [[ -z "$kw" ]] && continue
+                echo "$entry_text" | grep -qiF "$kw" 2>/dev/null && score=$((score + 1))
+            done <<< "$keywords"
+            if [[ "$score" -gt 0 ]]; then
+                local content
+                content=$(echo "$entry" | jq -r '(.summary // "") + " | " + (.detail // "")' 2>/dev/null)
+                echo "${score}|{\"source_type\":\"decision\",\"content_text\":$(echo "$content" | jq -Rs .)}" >> "$results_file"
+            fi
+        done
+    fi
+
+    # Search patterns.json (project, conventions, known_issues as text)
+    if [[ -f "$memory_dir/patterns.json" ]]; then
+        local entry_text
+        entry_text=$(jq -r 'to_entries | map(select(.key != "known_issues")) | from_entries | tostring' "$memory_dir/patterns.json" 2>/dev/null || echo "")
+        entry_text="$entry_text $(jq -r '.known_issues[]? // empty' "$memory_dir/patterns.json" 2>/dev/null | tr '\n' ' ')"
+        local score=0
+        while IFS= read -r kw; do
+            [[ -z "$kw" ]] && continue
+            echo "$entry_text" | grep -qiF "$kw" 2>/dev/null && score=$((score + 1))
+        done <<< "$keywords"
+        if [[ "$score" -gt 0 ]]; then
+            local content
+            content=$(jq -r 'to_entries | map("\(.key): \(.value)") | join(" | ")' "$memory_dir/patterns.json" 2>/dev/null | head -c 500)
+            echo "${score}|{\"source_type\":\"pattern\",\"content_text\":$(echo "$content" | jq -Rs .)}" >> "$results_file"
+        fi
+    fi
+
+    # Sort by score and output as JSON array
+    local output
+    if [[ -s "$results_file" ]]; then
+        output=$(sort -t'|' -k1 -rn "$results_file" | head -"$max_results" | cut -d'|' -f2- | jq -s '.' 2>/dev/null || echo "[]")
+    else
+        output="[]"
+    fi
+    rm -f "$results_file" 2>/dev/null || true
+    echo "$output"
+}
+
+# Store a memory with its text content for future embedding
+memory_store_for_embedding() {
+    local source_type="$1" content_text="$2" repo_hash="${3:-}"
+    local content_hash
+    content_hash=$(_memory_content_hash "$content_text")
+
+    if type db_save_embedding >/dev/null 2>&1; then
+        db_save_embedding "$content_hash" "$source_type" "$content_text" "$repo_hash" 2>/dev/null || true
+    fi
+}
+
+# Check if vector embeddings search is available (future: SQLite vec0, etc.)
+_has_embeddings() {
+    return 1  # No embedding-based search yet
+}
+
+# Semantic search: embeddings when available, else TF-IDF-like ranked keyword search
+memory_semantic_search() {
+    local query="$1" repo_hash="${2:-}" limit="${3:-5}"
+
+    if _has_embeddings 2>/dev/null; then
+        # Future: _search_embeddings "$query" "$repo_hash" "$limit"
+        :
+    fi
+
+    # Fall back to ranked keyword search (better than SQL LIKE or grep)
+    local mem_dir
+    mem_dir=""
+    if type repo_memory_dir &>/dev/null 2>&1; then
+        mem_dir="$(repo_memory_dir)"
+    fi
+    memory_ranked_search "$query" "$mem_dir" "$limit"
+}
+
+# Inject relevant memories into agent prompts (goal-based)
+memory_inject_goal_context() {
+    local goal="$1" repo_hash="${2:-}" max_tokens="${3:-2000}"
+
+    local memories
+    memories=$(memory_semantic_search "$goal" "$repo_hash" 5 2>/dev/null || echo "[]")
+
+    if [[ "$memories" == "[]" || -z "$memories" ]]; then
+        return
+    fi
+
+    echo "## Relevant Past Context"
+    echo ""
+    echo "$memories" | jq -r '.[] | "- [\(.source_type)] \(.content_text | .[0:200])"' 2>/dev/null || true
+    echo ""
+}
+
 # Get a deterministic hash for the current repo
 repo_hash() {
     local origin
@@ -198,7 +378,10 @@ memory_capture_failure() {
         pattern=$(echo "$error_output" | head -1 | cut -c1-200)
     fi
 
-    [[ -z "$pattern" ]] && return 0
+    if [[ -z "$pattern" ]]; then
+        warn "Memory capture: empty error pattern — skipping"
+        return 0
+    fi
 
     # Check for duplicate — increment seen_count if pattern already exists
     local existing_idx
@@ -207,7 +390,7 @@ memory_capture_failure() {
         "$failures_file" 2>/dev/null || echo "-1")
 
     (
-        if command -v flock &>/dev/null; then
+        if command -v flock >/dev/null 2>&1; then
             flock -w 10 200 2>/dev/null || { warn "Memory lock timeout"; return 1; }
         fi
         local tmp_file
@@ -237,6 +420,15 @@ memory_capture_failure() {
         fi
     ) 200>"${failures_file}.lock"
 
+    # Dual-write to DB
+    if type db_record_failure >/dev/null 2>&1; then
+        local rhash
+        rhash="$(repo_hash)"
+        db_record_failure "$rhash" "unknown" "$pattern" "" "" "" "$stage" 2>/dev/null || true
+    fi
+
+    memory_store_for_embedding "failure" "$pattern" "$(repo_hash)" 2>/dev/null || true
+
     emit_event "memory.failure" "stage=${stage}" "pattern=${pattern:0:80}"
 }
 
@@ -274,7 +466,7 @@ memory_record_fix_outcome() {
     [[ "$fix_resolved" == "true" ]] && resolved_inc=1
 
     (
-        if command -v flock &>/dev/null; then
+        if command -v flock >/dev/null 2>&1; then
             flock -w 10 200 2>/dev/null || { warn "Memory lock timeout"; return 1; }
         fi
         local tmp_file
@@ -583,7 +775,7 @@ Return JSON only, no markdown fences, no explanation."
     fi
 
     # Validate category against shared taxonomy (compat.sh) or built-in list
-    if type sw_valid_error_category &>/dev/null 2>&1; then
+    if type sw_valid_error_category >/dev/null 2>&1; then
         if ! sw_valid_error_category "$category"; then
             category="unknown"
         fi
@@ -725,6 +917,14 @@ memory_capture_pattern() {
                    }
                }' "$patterns_file" > "$tmp_file" && mv "$tmp_file" "$patterns_file"
 
+            # Dual-write to DB
+            if type db_save_pattern >/dev/null 2>&1; then
+                local rhash proj_desc
+                rhash="$(repo_hash)"
+                proj_desc="type=$proj_type,framework=$framework,test_runner=$test_runner,package_manager=$pkg_mgr,language=$language"
+                db_save_pattern "$rhash" "project" "project" "$proj_desc" "" 2>/dev/null || true
+            fi
+            memory_store_for_embedding "pattern" "project: $proj_type/$framework, $pkg_mgr, $language" "$(repo_hash)" 2>/dev/null || true
             emit_event "memory.pattern" "type=project" "proj_type=${proj_type}" "framework=${framework}"
             success "Captured project patterns (${proj_type}/${framework:-none})"
             ;;
@@ -740,6 +940,14 @@ memory_capture_pattern() {
                     else . + {known_issues: [$issue]}
                     end | .known_issues = (.known_issues | .[-50:])' \
                    "$patterns_file" > "$tmp_file" && mv "$tmp_file" "$patterns_file"
+                # Dual-write to DB
+                if type db_save_pattern >/dev/null 2>&1; then
+                    local rhash issue_key
+                    rhash="$(repo_hash)"
+                    issue_key=$(echo -n "$pattern_data" | shasum -a 256 | cut -c1-16)
+                    db_save_pattern "$rhash" "known_issue" "$issue_key" "$pattern_data" "" 2>/dev/null || true
+                fi
+                memory_store_for_embedding "pattern" "known_issue: $pattern_data" "$(repo_hash)" 2>/dev/null || true
                 emit_event "memory.pattern" "type=known_issue"
             fi
             ;;
@@ -758,7 +966,7 @@ memory_inject_context() {
     local stage_id="${1:-}"
 
     # Try intelligence-ranked search first
-    if type intelligence_search_memory &>/dev/null 2>&1; then
+    if type intelligence_search_memory >/dev/null 2>&1; then
         local config="${REPO_DIR:-.}/.claude/daemon-config.json"
         local intel_enabled="false"
         if [[ -f "$config" ]]; then
@@ -788,6 +996,7 @@ memory_inject_context() {
     done
 
     if [[ "$has_memory" == "false" ]]; then
+        info "No memory available for repo (${mem_dir}) — first pipeline run will seed it"
         echo "# No memory available for this repository yet."
         return 0
     fi
@@ -928,7 +1137,17 @@ memory_inject_context() {
             ;;
 
         *)
-            # Generic context for any stage — inject top-K most relevant across all categories
+            # Generic context — use ranked semantic search when intelligence unavailable
+            if ! type intelligence_search_memory &>/dev/null 2>&1; then
+                local ranked_json
+                ranked_json=$(memory_ranked_search "${stage_id} stage context" "$mem_dir" 5 2>/dev/null || echo "[]")
+                if [[ -n "$ranked_json" && "$ranked_json" != "[]" ]]; then
+                    echo "## Ranked Relevant Memory"
+                    echo "$ranked_json" | jq -r '.[]? | "- [\(.source_type)] \(.content_text[0:200])"' 2>/dev/null || true
+                    echo ""
+                fi
+            fi
+
             echo "## Repository Patterns"
             if [[ -f "$mem_dir/patterns.json" ]]; then
                 jq -r 'to_entries | map(select(.key != "known_issues")) | from_entries' \
@@ -1155,6 +1374,15 @@ memory_capture_decision() {
        }] | .decisions = (.decisions | .[-100:])' \
        "$decisions_file" > "$tmp_file" && mv "$tmp_file" "$decisions_file"
 
+    # Dual-write to DB
+    if type db_save_decision >/dev/null 2>&1; then
+        local rhash
+        rhash="$(repo_hash)"
+        db_save_decision "$rhash" "$dec_type" "${detail:-}" "$summary" "" 2>/dev/null || true
+    fi
+
+    memory_store_for_embedding "decision" "${dec_type}: ${summary} - ${detail:-}" "$(repo_hash)" 2>/dev/null || true
+
     emit_event "memory.decision" "type=${dec_type}" "summary=${summary:0:80}"
     success "Recorded decision: ${summary}"
 }
@@ -1276,10 +1504,17 @@ memory_show() {
 }
 
 memory_search() {
+    if [[ "${1:-}" == "--semantic" ]]; then
+        shift
+        memory_semantic_search "$*" "" 10
+        exit 0
+    fi
+
     local keyword="${1:-}"
 
     if [[ -z "$keyword" ]]; then
         error "Usage: shipwright memory search <keyword>"
+        echo -e "  ${DIM}Or: shipwright memory search --semantic <query>${RESET}"
         return 1
     fi
 
@@ -1296,10 +1531,10 @@ memory_search() {
     local found=0
 
     # ── Semantic search via intelligence (if available) ──
-    if type intelligence_search_memory &>/dev/null 2>&1; then
+    if type intelligence_search_memory >/dev/null 2>&1; then
         local semantic_results
         semantic_results=$(intelligence_search_memory "$keyword" "$mem_dir" 5 2>/dev/null || echo "")
-        if [[ -n "$semantic_results" ]] && echo "$semantic_results" | jq -e '.results | length > 0' &>/dev/null; then
+        if [[ -n "$semantic_results" ]] && echo "$semantic_results" | jq -e '.results | length > 0' >/dev/null 2>&1; then
             echo -e "  ${BOLD}${CYAN}Semantic Results (AI-ranked):${RESET}"
             local result_count
             result_count=$(echo "$semantic_results" | jq '.results | length')
@@ -1417,6 +1652,11 @@ memory_export() {
     local mem_dir
     mem_dir="$(repo_memory_dir)"
 
+    # Ensure all memory files exist (jq --slurpfile fails on missing files)
+    for f in patterns.json failures.json decisions.json metrics.json; do
+        [[ -f "$mem_dir/$f" ]] || echo '{}' > "$mem_dir/$f"
+    done
+
     # Merge all memory files into a single JSON export
     local export_json
     export_json=$(jq -n \
@@ -1532,8 +1772,10 @@ memory_stats() {
     # Event-based hit rate
     local inject_count capture_count
     if [[ -f "$EVENTS_FILE" ]]; then
-        inject_count=$(grep -c '"memory.inject"' "$EVENTS_FILE" 2>/dev/null || echo 0)
-        capture_count=$(grep -c '"memory.capture"' "$EVENTS_FILE" 2>/dev/null || echo 0)
+        inject_count=$(grep -c '"memory.inject"' "$EVENTS_FILE" 2>/dev/null || true)
+        inject_count="${inject_count:-0}"
+        capture_count=$(grep -c '"memory.capture"' "$EVENTS_FILE" 2>/dev/null || true)
+        capture_count="${capture_count:-0}"
         echo ""
         echo -e "  ${BOLD}Usage${RESET}"
         printf "    %-18s %s\n" "Context injections:" "$inject_count"
@@ -1557,6 +1799,7 @@ show_help() {
     echo -e "  ${CYAN}show${RESET}               Display memory for current repo"
     echo -e "  ${CYAN}show${RESET} --global       Display cross-repo learnings"
     echo -e "  ${CYAN}search${RESET} <keyword>    Search memory for keyword"
+    echo -e "  ${CYAN}search${RESET} --semantic <query>  Semantic search via memory_embeddings"
     echo -e "  ${CYAN}forget${RESET} --all         Clear memory for current repo"
     echo -e "  ${CYAN}export${RESET}              Export memory as JSON"
     echo -e "  ${CYAN}import${RESET} <file>        Import memory from JSON"

package/scripts/sw-mission-control.sh

@@ -7,7 +7,7 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="2.4.0"
+VERSION="3.1.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
@@ -35,16 +35,6 @@ if [[ "$(type -t emit_event 2>/dev/null)" != "function" ]]; then
     echo "${payload}}" >> "${HOME}/.shipwright/events.jsonl"
   }
 fi
-CYAN="${CYAN:-\033[38;2;0;212;255m}"
-PURPLE="${PURPLE:-\033[38;2;124;58;237m}"
-BLUE="${BLUE:-\033[38;2;0;102;255m}"
-GREEN="${GREEN:-\033[38;2;74;222;128m}"
-YELLOW="${YELLOW:-\033[38;2;250;204;21m}"
-RED="${RED:-\033[38;2;248;113;113m}"
-DIM="${DIM:-\033[2m}"
-BOLD="${BOLD:-\033[1m}"
-RESET="${RESET:-\033[0m}"
-
 format_duration() {
     local secs="$1"
     if [[ "$secs" -ge 3600 ]]; then
@@ -268,7 +258,7 @@ show_resource_usage() {
 
     echo -e "${BOLD}System Resources${RESET}"
 
-    if command -v top &>/dev/null || command -v ps &>/dev/null; then
+    if command -v top >/dev/null 2>&1 || command -v ps >/dev/null 2>&1; then
         # Get system memory and CPU stats
         local mem_pct=65
         local cpu_pct=42

package/scripts/sw-model-router.sh

@@ -7,7 +7,7 @@
 set -euo pipefail
 trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
 
-VERSION="2.4.0"
+VERSION="3.1.0"
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
@@ -35,21 +35,17 @@ if [[ "$(type -t emit_event 2>/dev/null)" != "function" ]]; then
     echo "${payload}}" >> "${HOME}/.shipwright/events.jsonl"
   }
 fi
-CYAN="${CYAN:-\033[38;2;0;212;255m}"
-PURPLE="${PURPLE:-\033[38;2;124;58;237m}"
-BLUE="${BLUE:-\033[38;2;0;102;255m}"
-GREEN="${GREEN:-\033[38;2;74;222;128m}"
-YELLOW="${YELLOW:-\033[38;2;250;204;21m}"
-RED="${RED:-\033[38;2;248;113;113m}"
-DIM="${DIM:-\033[2m}"
-BOLD="${BOLD:-\033[1m}"
-RESET="${RESET:-\033[0m}"
-
 # ─── File Paths ────────────────────────────────────────────────────────────
-MODEL_ROUTING_CONFIG="${HOME}/.shipwright/model-routing.json"
-MODEL_USAGE_LOG="${HOME}/.shipwright/model-usage.jsonl"
+# Unified: prefer optimization dir (written by self-optimize), fallback to legacy
+OPTIMIZATION_DIR="${HOME}/.shipwright/optimization"
+MODEL_ROUTING_OPTIMIZATION="${OPTIMIZATION_DIR}/model-routing.json"
+MODEL_ROUTING_LEGACY="${HOME}/.shipwright/model-routing.json"
+MODEL_USAGE_LOG="${OPTIMIZATION_DIR}/model-usage.jsonl"
 AB_RESULTS_FILE="${HOME}/.shipwright/ab-results.jsonl"
 
+# Resolve which config file to use (set by _resolve_routing_config)
+MODEL_ROUTING_CONFIG=""
+
 # ─── Model Costs (per million tokens) ───────────────────────────────────────
 HAIKU_INPUT_COST="0.80"
 HAIKU_OUTPUT_COST="4.00"
@@ -70,9 +66,25 @@ OPUS_STAGES="plan|design|build|compound_quality"
 COMPLEXITY_LOW=30          # Below this: use sonnet
 COMPLEXITY_HIGH=80         # Above this: use opus
 
+# ─── Resolve Routing Config Path ────────────────────────────────────────────
+# Priority: optimization (self-optimize writes) > legacy > create in optimization
+_resolve_routing_config() {
+    if [[ -f "$MODEL_ROUTING_OPTIMIZATION" ]]; then
+        MODEL_ROUTING_CONFIG="$MODEL_ROUTING_OPTIMIZATION"
+        return
+    fi
+    if [[ -f "$MODEL_ROUTING_LEGACY" ]]; then
+        MODEL_ROUTING_CONFIG="$MODEL_ROUTING_LEGACY"
+        return
+    fi
+    # Neither exists — use optimization as canonical location
+    MODEL_ROUTING_CONFIG="$MODEL_ROUTING_OPTIMIZATION"
+}
+
 # ─── Ensure Config File Exists ──────────────────────────────────────────────
 ensure_config() {
-    mkdir -p "${HOME}/.shipwright"
+    _resolve_routing_config
+    mkdir -p "$(dirname "$MODEL_ROUTING_CONFIG")"
 
     if [[ ! -f "$MODEL_ROUTING_CONFIG" ]]; then
         cat > "$MODEL_ROUTING_CONFIG" <<'CONFIG'
@@ -127,26 +139,53 @@ route_model() {
     fi
 
     local model=""
+    _resolve_routing_config
+
+    # Strategy 1: Optimization file (self-optimize format) — .routes.stage.model or .routes.stage.recommended
+    if [[ -n "$MODEL_ROUTING_CONFIG" && -f "$MODEL_ROUTING_CONFIG" ]] && command -v jq >/dev/null 2>&1; then
+        local from_routes
+        from_routes=$(jq -r --arg s "$stage" '.routes[$s].model // .routes[$s].recommended // .[$s].recommended // .[$s].model // empty' "$MODEL_ROUTING_CONFIG" 2>/dev/null || true)
+        if [[ -n "$from_routes" && "$from_routes" =~ ^(haiku|sonnet|opus)$ ]]; then
+            model="$from_routes"
+        fi
+        # Fallback: legacy default_routing format
+        if [[ -z "$model" ]]; then
+            local from_default
+            from_default=$(jq -r --arg s "$stage" '.default_routing[$s] // empty' "$MODEL_ROUTING_CONFIG" 2>/dev/null || true)
+            if [[ -n "$from_default" && "$from_default" =~ ^(haiku|sonnet|opus)$ ]]; then
+                model="$from_default"
+            fi
+        fi
+    fi
 
-    # Complexity-based override (applies to all stages)
-    if [[ "$complexity" -lt "$COMPLEXITY_LOW" ]]; then
-        model="sonnet"
-    elif [[ "$complexity" -gt "$COMPLEXITY_HIGH" ]]; then
-        model="opus"
-    else
-        # Stage-based routing for medium complexity
-        if [[ "$stage" =~ $HAIKU_STAGES ]]; then
-            model="haiku"
-        elif [[ "$stage" =~ $SONNET_STAGES ]]; then
+    # Strategy 2: Built-in defaults (complexity + stage rules)
+    if [[ -z "$model" ]]; then
+        if [[ "$complexity" -lt "$COMPLEXITY_LOW" ]]; then
             model="sonnet"
-        elif [[ "$stage" =~ $OPUS_STAGES ]]; then
+        elif [[ "$complexity" -gt "$COMPLEXITY_HIGH" ]]; then
             model="opus"
         else
-            # Default to sonnet for unknown stages
-            model="sonnet"
+            if [[ "$stage" =~ $HAIKU_STAGES ]]; then
+                model="haiku"
+            elif [[ "$stage" =~ $SONNET_STAGES ]]; then
+                model="sonnet"
+            elif [[ "$stage" =~ $OPUS_STAGES ]]; then
+                model="opus"
+            else
+                model="sonnet"
+            fi
         fi
     fi
 
+    # Complexity override: upgrade/downgrade based on complexity even when config says otherwise
+    if [[ "$complexity" -lt "$COMPLEXITY_LOW" && "$model" == "opus" ]]; then
+        model="sonnet"
+    elif [[ "$complexity" -gt "$COMPLEXITY_HIGH" && "$model" == "haiku" ]]; then
+        model="opus"
+    elif [[ "$complexity" -gt "$COMPLEXITY_HIGH" ]]; then
+        model="opus"
+    fi
+
     echo "$model"
 }
 
@@ -177,7 +216,7 @@ show_config() {
     info "Model Routing Configuration"
     echo ""
 
-    if command -v jq &>/dev/null; then
+    if command -v jq >/dev/null 2>&1; then
         jq . "$MODEL_ROUTING_CONFIG" 2>/dev/null || cat "$MODEL_ROUTING_CONFIG"
     else
         cat "$MODEL_ROUTING_CONFIG"
@@ -196,7 +235,7 @@ set_config() {
 
     ensure_config
 
-    if ! command -v jq &>/dev/null; then
+    if ! command -v jq >/dev/null 2>&1; then
         error "jq is required for config updates"
         return 1
     fi
@@ -298,7 +337,7 @@ record_usage() {
     local input_tokens="${3:-0}"
     local output_tokens="${4:-0}"
 
-    mkdir -p "${HOME}/.shipwright"
+    mkdir -p "$(dirname "$MODEL_USAGE_LOG")"
 
     local cost
     cost=$(awk "BEGIN {}" ) # Calculate actual cost
@@ -330,7 +369,7 @@ configure_ab_test() {
 
     ensure_config
 
-    if ! command -v jq &>/dev/null; then
+    if ! command -v jq >/dev/null 2>&1; then
         error "jq is required for A/B test configuration"
         return 1
     fi
@@ -370,7 +409,7 @@ show_report() {
         return 0
     fi
 
-    if ! command -v jq &>/dev/null; then
+    if ! command -v jq >/dev/null 2>&1; then
         error "jq is required to view reports"
         return 1
     fi
@@ -432,7 +471,7 @@ show_ab_results() {
         return 0
     fi
 
-    if ! command -v jq &>/dev/null; then
+    if ! command -v jq >/dev/null 2>&1; then
         error "jq is required to view A/B test results"
         return 1
     fi
@@ -520,7 +559,7 @@ main() {
             elif [[ "${1:-}" == "disable" ]]; then
                 # Disable A/B testing
                 ensure_config
-                if command -v jq &>/dev/null; then
+                if command -v jq >/dev/null 2>&1; then
                     local tmp_config
                     tmp_config=$(mktemp)
                     trap "rm -f '$tmp_config'" RETURN