shipwright-cli 1.7.0 → 1.9.0

package/scripts/sw-adversarial.sh

@@ -0,0 +1,274 @@
+#!/usr/bin/env bash
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  shipwright adversarial — Adversarial Agent Code Review                 ║
+# ║  Red-team code changes · Find security flaws · Iterative hardening     ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+set -euo pipefail
+trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
+
+VERSION="1.9.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+CYAN='\033[38;2;0;212;255m'
+PURPLE='\033[38;2;124;58;237m'
+BLUE='\033[38;2;0;102;255m'
+GREEN='\033[38;2;74;222;128m'
+YELLOW='\033[38;2;250;204;21m'
+RED='\033[38;2;248;113;113m'
+DIM='\033[2m'
+BOLD='\033[1m'
+RESET='\033[0m'
+
+# ─── Cross-platform compatibility ──────────────────────────────────────────
+# shellcheck source=lib/compat.sh
+[[ -f "$SCRIPT_DIR/lib/compat.sh" ]] && source "$SCRIPT_DIR/lib/compat.sh"
+
+info()    { echo -e "${CYAN}${BOLD}▸${RESET} $*"; }
+success() { echo -e "${GREEN}${BOLD}✓${RESET} $*"; }
+warn()    { echo -e "${YELLOW}${BOLD}⚠${RESET} $*"; }
+error()   { echo -e "${RED}${BOLD}✗${RESET} $*" >&2; }
+
+now_iso() { date -u +"%Y-%m-%dT%H:%M:%SZ"; }
+now_epoch() { date +%s; }
+
+# ─── Structured Event Log ────────────────────────────────────────────────
+EVENTS_FILE="${HOME}/.shipwright/events.jsonl"
+
+emit_event() {
+    local event_type="$1"; shift
+    local json_fields=""
+    for kv in "$@"; do
+        local key="${kv%%=*}"; local val="${kv#*=}"
+        if [[ "$val" =~ ^-?[0-9]+\.?[0-9]*$ ]]; then
+            json_fields="${json_fields},\"${key}\":${val}"
+        else
+            val="${val//\"/\\\"}"; json_fields="${json_fields},\"${key}\":\"${val}\""
+        fi
+    done
+    mkdir -p "${HOME}/.shipwright"
+    echo "{\"ts\":\"$(now_iso)\",\"ts_epoch\":$(now_epoch),\"type\":\"${event_type}\"${json_fields}}" >> "$EVENTS_FILE"
+}
+
+# ─── Source Intelligence Core ─────────────────────────────────────────────
+if [[ -f "$SCRIPT_DIR/sw-intelligence.sh" ]]; then
+    source "$SCRIPT_DIR/sw-intelligence.sh"
+fi
+
+# ─── Configuration ───────────────────────────────────────────────────────
+MAX_ROUNDS="${ADVERSARIAL_MAX_ROUNDS:-3}"
+
+_adversarial_enabled() {
+    local config="${REPO_DIR}/.claude/daemon-config.json"
+    if [[ -f "$config" ]]; then
+        local enabled
+        enabled=$(jq -r '.intelligence.adversarial_enabled // false' "$config" 2>/dev/null || echo "false")
+        [[ "$enabled" == "true" ]]
+    else
+        return 1
+    fi
+}
+
+# ─── GitHub Security Context ─────────────────────────────────────────────
+
+_adversarial_security_context() {
+    local diff_paths="$1"
+    local context=""
+
+    type _gh_detect_repo &>/dev/null 2>&1 || { echo ""; return 0; }
+    _gh_detect_repo 2>/dev/null || { echo ""; return 0; }
+
+    local owner="${GH_OWNER:-}" repo="${GH_REPO:-}"
+    [[ -z "$owner" || -z "$repo" ]] && { echo ""; return 0; }
+
+    # Get CodeQL alerts for changed files
+    if type gh_security_alerts &>/dev/null 2>&1; then
+        local alerts
+        alerts=$(gh_security_alerts "$owner" "$repo" 2>/dev/null || echo "[]")
+        local relevant_alerts
+        relevant_alerts=$(echo "$alerts" | jq -c --arg paths "$diff_paths" \
+            '[.[] | select(.most_recent_instance.location.path as $p | ($paths | split("\n") | any(. == $p)))]' 2>/dev/null || echo "[]")
+        local alert_count
+        alert_count=$(echo "$relevant_alerts" | jq 'length' 2>/dev/null || echo "0")
+        if [[ "${alert_count:-0}" -gt 0 ]]; then
+            local alert_summary
+            alert_summary=$(echo "$relevant_alerts" | jq -r '.[] | "- \(.rule.description // .rule.id): \(.most_recent_instance.location.path):\(.most_recent_instance.location.start_line)"' 2>/dev/null || echo "")
+            context="EXISTING SECURITY ALERTS in changed files:
+${alert_summary}
+"
+        fi
+    fi
+
+    # Get Dependabot alerts
+    if type gh_dependabot_alerts &>/dev/null 2>&1; then
+        local dep_alerts
+        dep_alerts=$(gh_dependabot_alerts "$owner" "$repo" 2>/dev/null || echo "[]")
+        local dep_count
+        dep_count=$(echo "$dep_alerts" | jq 'length' 2>/dev/null || echo "0")
+        if [[ "${dep_count:-0}" -gt 0 ]]; then
+            local dep_summary
+            dep_summary=$(echo "$dep_alerts" | jq -r '.[0:5] | .[] | "- \(.security_advisory.summary // "unknown"): \(.dependency.package.name // "unknown") (\(.security_vulnerability.severity // "unknown"))"' 2>/dev/null || echo "")
+            context="${context}DEPENDENCY VULNERABILITIES:
+${dep_summary}
+"
+        fi
+    fi
+
+    echo "$context"
+}
+
+# ─── Adversarial Review ──────────────────────────────────────────────────
+
+adversarial_review() {
+    local code_diff="${1:-}"
+    local context="${2:-}"
+
+    if ! _adversarial_enabled; then
+        warn "Adversarial review disabled — enable intelligence.adversarial_enabled" >&2
+        echo "[]"
+        return 0
+    fi
+
+    if [[ -z "$code_diff" ]]; then
+        error "Usage: adversarial review <code_diff> [context]"
+        return 1
+    fi
+
+    info "Running adversarial review..." >&2
+
+    # Inject GitHub security context if available
+    local security_context=""
+    local diff_paths
+    diff_paths=$(echo "$code_diff" | grep '^[+-][+-][+-] [ab]/' | sed 's|^[+-]\{3\} [ab]/||' | sort -u 2>/dev/null || true)
+    if [[ -n "$diff_paths" ]]; then
+        security_context=$(_adversarial_security_context "$diff_paths" 2>/dev/null || true)
+    fi
+    if [[ -n "$security_context" ]]; then
+        context="The following security alerts exist for files in this change. Pay special attention to these areas:
+${security_context}
+${context}"
+    fi
+
+    local prompt
+    prompt=$(jq -n --arg diff "$code_diff" --arg ctx "$context" '{
+        role: "You are a hostile security researcher and QA expert. Your job is to find bugs, security vulnerabilities, race conditions, edge cases, and logic errors in this code change. Be thorough and adversarial.",
+        instruction: "Analyze this code diff and return a JSON array of findings. Each finding must have: severity (critical|high|medium|low), category (security|logic|race_condition|edge_case), description, location, and exploit_scenario.",
+        diff: $diff,
+        context: $ctx
+    }' | jq -r 'to_entries | map("\(.key): \(.value)") | join("\n\n")')
+
+    local result
+    if ! result=$(_intelligence_call_claude "$prompt" "adversarial_review_$(echo -n "$code_diff" | head -c 200 | _intelligence_md5)" 300); then
+        warn "Claude call failed — returning empty findings" >&2
+        echo "[]"
+        return 0
+    fi
+
+    # Ensure result is a JSON array
+    if ! echo "$result" | jq 'if type == "array" then . else empty end' >/dev/null 2>&1; then
+        # Try to extract array from response
+        local extracted
+        extracted=$(echo "$result" | jq '.findings // .results // []' 2>/dev/null || echo "[]")
+        result="$extracted"
+    fi
+
+    # Emit events for each finding
+    local count
+    count=$(echo "$result" | jq 'length' 2>/dev/null || echo "0")
+    local i=0
+    while [[ $i -lt $count ]]; do
+        local severity category
+        severity=$(echo "$result" | jq -r ".[$i].severity // \"unknown\"" 2>/dev/null || echo "unknown")
+        category=$(echo "$result" | jq -r ".[$i].category // \"unknown\"" 2>/dev/null || echo "unknown")
+        emit_event "adversarial.finding" "severity=$severity" "category=$category" "index=$i"
+        i=$((i + 1))
+    done
+
+    echo "$result"
+}
+
+# ─── Adversarial Iteration ───────────────────────────────────────────────
+
+adversarial_iterate() {
+    local primary_code="${1:-}"
+    local findings="${2:-[]}"
+    local round="${3:-1}"
+
+    if [[ -z "$primary_code" ]]; then
+        error "Usage: adversarial iterate <primary_code> <findings_json> [round]"
+        return 1
+    fi
+
+    if [[ "$round" -gt "$MAX_ROUNDS" ]]; then
+        info "Max adversarial rounds ($MAX_ROUNDS) reached" >&2
+        echo "$findings"
+        return 0
+    fi
+
+    emit_event "adversarial.round" "round=$round" "max_rounds=$MAX_ROUNDS"
+
+    local critical_count
+    critical_count=$(echo "$findings" | jq '[.[] | select(.severity == "critical" or .severity == "high")] | length' 2>/dev/null || echo "0")
+
+    if [[ "$critical_count" -eq 0 ]]; then
+        success "No critical/high findings — adversarial review converged at round $round" >&2
+        emit_event "adversarial.converged" "round=$round" "total_findings=0"
+        echo "[]"
+        return 0
+    fi
+
+    info "Round $round: $critical_count critical/high findings — requesting fixes..." >&2
+
+    local prompt
+    prompt=$(jq -n --arg code "$primary_code" --arg findings "$findings" --arg round "$round" '{
+        instruction: "These issues were found by adversarial security review. For each critical/high finding, suggest a specific fix. Return a JSON array with: original_finding, suggested_fix, fixed_code_snippet.",
+        code: $code,
+        findings: $findings,
+        round: $round
+    }' | jq -r 'to_entries | map("\(.key): \(.value)") | join("\n\n")')
+
+    local result
+    if ! result=$(_intelligence_call_claude "$prompt" "adversarial_iterate_r${round}_$(echo -n "$primary_code" | head -c 200 | _intelligence_md5)" 300); then
+        warn "Claude call failed during iteration" >&2
+        echo "$findings"
+        return 0
+    fi
+
+    echo "$result"
+}
+
+# ─── Help ─────────────────────────────────────────────────────────────────
+
+show_help() {
+    echo ""
+    echo -e "${CYAN}${BOLD}  Shipwright Adversarial${RESET}  ${DIM}v${VERSION}${RESET}"
+    echo -e "${DIM}  ══════════════════════════════════════════${RESET}"
+    echo ""
+    echo -e "  ${BOLD}USAGE${RESET}"
+    echo -e "    shipwright adversarial <command> [options]"
+    echo ""
+    echo -e "  ${BOLD}COMMANDS${RESET}"
+    echo -e "    ${CYAN}review${RESET}   <diff> [context]              Run adversarial review on code diff"
+    echo -e "    ${CYAN}iterate${RESET}  <code> <findings> [round]     Fix findings and re-review"
+    echo -e "    ${CYAN}help${RESET}                                   Show this help"
+    echo ""
+    echo -e "  ${BOLD}CONFIGURATION${RESET}"
+    echo -e "    Feature flag:  ${DIM}intelligence.adversarial_enabled${RESET} in daemon-config.json"
+    echo -e "    Max rounds:    ${DIM}ADVERSARIAL_MAX_ROUNDS env var (default: 3)${RESET}"
+    echo ""
+}
+
+# ─── Command Router ──────────────────────────────────────────────────────
+
+main() {
+    case "${1:-help}" in
+        review)   shift; adversarial_review "$@" ;;
+        iterate)  shift; adversarial_iterate "$@" ;;
+        help|--help|-h) show_help ;;
+        *)        error "Unknown: $1"; exit 1 ;;
+    esac
+}
+
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+    main "$@"
+fi

package/scripts/sw-architecture-enforcer.sh

@@ -0,0 +1,330 @@
+#!/usr/bin/env bash
+# ╔═══════════════════════════════════════════════════════════════════════════╗
+# ║  shipwright architecture — Living Architecture Model & Enforcer         ║
+# ║  Build models · Validate changes · Evolve patterns                     ║
+# ╚═══════════════════════════════════════════════════════════════════════════╝
+set -euo pipefail
+trap 'echo "ERROR: $BASH_SOURCE:$LINENO exited with status $?" >&2' ERR
+
+VERSION="1.9.0"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
+
+CYAN='\033[38;2;0;212;255m'
+PURPLE='\033[38;2;124;58;237m'
+BLUE='\033[38;2;0;102;255m'
+GREEN='\033[38;2;74;222;128m'
+YELLOW='\033[38;2;250;204;21m'
+RED='\033[38;2;248;113;113m'
+DIM='\033[2m'
+BOLD='\033[1m'
+RESET='\033[0m'
+
+# ─── Cross-platform compatibility ──────────────────────────────────────────
+# shellcheck source=lib/compat.sh
+[[ -f "$SCRIPT_DIR/lib/compat.sh" ]] && source "$SCRIPT_DIR/lib/compat.sh"
+
+info()    { echo -e "${CYAN}${BOLD}▸${RESET} $*"; }
+success() { echo -e "${GREEN}${BOLD}✓${RESET} $*"; }
+warn()    { echo -e "${YELLOW}${BOLD}⚠${RESET} $*"; }
+error()   { echo -e "${RED}${BOLD}✗${RESET} $*" >&2; }
+
+now_iso() { date -u +"%Y-%m-%dT%H:%M:%SZ"; }
+now_epoch() { date +%s; }
+
+# ─── Structured Event Log ────────────────────────────────────────────────
+EVENTS_FILE="${HOME}/.shipwright/events.jsonl"
+
+emit_event() {
+    local event_type="$1"; shift
+    local json_fields=""
+    for kv in "$@"; do
+        local key="${kv%%=*}"; local val="${kv#*=}"
+        if [[ "$val" =~ ^-?[0-9]+\.?[0-9]*$ ]]; then
+            json_fields="${json_fields},\"${key}\":${val}"
+        else
+            val="${val//\"/\\\"}"; json_fields="${json_fields},\"${key}\":\"${val}\""
+        fi
+    done
+    mkdir -p "${HOME}/.shipwright"
+    echo "{\"ts\":\"$(now_iso)\",\"ts_epoch\":$(now_epoch),\"type\":\"${event_type}\"${json_fields}}" >> "$EVENTS_FILE"
+}
+
+# ─── Source Intelligence Core ─────────────────────────────────────────────
+if [[ -f "$SCRIPT_DIR/sw-intelligence.sh" ]]; then
+    source "$SCRIPT_DIR/sw-intelligence.sh"
+fi
+
+# ─── Configuration ───────────────────────────────────────────────────────
+MEMORY_DIR="${HOME}/.shipwright/memory"
+
+_architecture_enabled() {
+    local config="${REPO_DIR}/.claude/daemon-config.json"
+    if [[ -f "$config" ]]; then
+        local enabled
+        enabled=$(jq -r '.intelligence.architecture_enabled // false' "$config" 2>/dev/null || echo "false")
+        [[ "$enabled" == "true" ]]
+    else
+        return 1
+    fi
+}
+
+repo_hash() {
+    local origin
+    origin=$(git config --get remote.origin.url 2>/dev/null || echo "local")
+    echo -n "$origin" | shasum -a 256 | cut -c1-12
+}
+
+_model_path() {
+    local hash
+    hash=$(repo_hash)
+    echo "${MEMORY_DIR}/${hash}/architecture.json"
+}
+
+# ─── Build Architecture Model ────────────────────────────────────────────
+
+architecture_build_model() {
+    local repo_root="${1:-$REPO_DIR}"
+
+    if ! _architecture_enabled; then
+        warn "Architecture enforcer disabled — enable intelligence.architecture_enabled" >&2
+        echo "{}"
+        return 0
+    fi
+
+    info "Building architecture model for: $repo_root" >&2
+
+    # Sample key files for context
+    local context=""
+    local readme=""
+    if [[ -f "$repo_root/README.md" ]]; then
+        readme=$(head -100 "$repo_root/README.md" 2>/dev/null || true)
+        context="${context}README.md:\n${readme}\n\n"
+    fi
+
+    # Detect project type and read manifest
+    local manifest=""
+    for mf in package.json Cargo.toml go.mod pyproject.toml; do
+        if [[ -f "$repo_root/$mf" ]]; then
+            manifest=$(head -50 "$repo_root/$mf" 2>/dev/null || true)
+            context="${context}${mf}:\n${manifest}\n\n"
+            break
+        fi
+    done
+
+    # Sample directory structure
+    local tree=""
+    if command -v find >/dev/null 2>&1; then
+        tree=$(find "$repo_root" -maxdepth 3 -type f -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" -o -name "*.sh" 2>/dev/null | head -50 || true)
+        context="${context}File structure:\n${tree}\n"
+    fi
+
+    local prompt
+    prompt=$(jq -n --arg ctx "$context" '{
+        instruction: "Analyze this codebase and extract its architectural model. Return a JSON object with: layers (array of layer names like presentation/business/data), patterns (array of design patterns used like MVC/provider/pipeline), conventions (array of coding conventions), and dependencies (array of key external dependencies).",
+        codebase_context: $ctx
+    }' | jq -r 'to_entries | map("\(.key): \(.value)") | join("\n\n")')
+
+    local result
+    if ! result=$(_intelligence_call_claude "$prompt" "architecture_model_$(repo_hash)" 7200); then
+        warn "Claude call failed — returning empty model" >&2
+        echo "{}"
+        return 0
+    fi
+
+    # Ensure valid model structure
+    result=$(echo "$result" | jq '{
+        layers: (.layers // []),
+        patterns: (.patterns // []),
+        conventions: (.conventions // []),
+        dependencies: (.dependencies // []),
+        built_at: (now | todate),
+        repo_hash: "'"$(repo_hash)"'"
+    }' 2>/dev/null || echo '{"layers":[],"patterns":[],"conventions":[],"dependencies":[]}')
+
+    # Store model atomically
+    local model_file
+    model_file=$(_model_path)
+    local model_dir
+    model_dir=$(dirname "$model_file")
+    mkdir -p "$model_dir"
+
+    local tmp_file="${model_file}.tmp"
+    echo "$result" > "$tmp_file"
+    mv "$tmp_file" "$model_file"
+
+    local layer_count pattern_count
+    layer_count=$(echo "$result" | jq '.layers | length' 2>/dev/null || echo "0")
+    pattern_count=$(echo "$result" | jq '.patterns | length' 2>/dev/null || echo "0")
+
+    emit_event "architecture.model_built" "layers=$layer_count" "patterns=$pattern_count" "repo_hash=$(repo_hash)"
+    success "Architecture model built: $layer_count layers, $pattern_count patterns" >&2
+
+    echo "$result"
+}
+
+# ─── Validate Changes ────────────────────────────────────────────────────
+
+architecture_validate_changes() {
+    local diff="${1:-}"
+    local model_file="${2:-$(_model_path)}"
+
+    if ! _architecture_enabled; then
+        warn "Architecture enforcer disabled" >&2
+        echo "[]"
+        return 0
+    fi
+
+    if [[ -z "$diff" ]]; then
+        error "Usage: architecture validate <diff> [model_file]"
+        return 1
+    fi
+
+    if [[ ! -f "$model_file" ]]; then
+        warn "No architecture model found — run 'architecture build' first" >&2
+        echo "[]"
+        return 0
+    fi
+
+    info "Validating changes against architecture model..." >&2
+
+    local model
+    model=$(jq -c '.' "$model_file" 2>/dev/null || echo '{}')
+
+    local prompt
+    prompt=$(jq -n --arg model "$model" --arg diff "$diff" '{
+        instruction: "Given this architectural model, does this code change follow the established patterns and conventions? Report any violations. Return a JSON array of violations, each with: violation (description), severity (critical|high|medium|low), pattern_broken (which pattern/convention was violated), and suggestion (how to fix it). Return an empty array [] if no violations found.",
+        architecture_model: $model,
+        code_diff: $diff
+    }' | jq -r 'to_entries | map("\(.key): \(.value)") | join("\n\n")')
+
+    local result
+    if ! result=$(_intelligence_call_claude "$prompt" "architecture_validate_$(echo -n "$diff" | head -c 200 | _intelligence_md5)" 300); then
+        warn "Claude call failed — returning empty violations" >&2
+        echo "[]"
+        return 0
+    fi
+
+    # Ensure result is a JSON array
+    if ! echo "$result" | jq 'if type == "array" then . else empty end' >/dev/null 2>&1; then
+        result=$(echo "$result" | jq '.violations // []' 2>/dev/null || echo "[]")
+    fi
+
+    # Emit events for violations
+    local count
+    count=$(echo "$result" | jq 'length' 2>/dev/null || echo "0")
+    local i=0
+    while [[ $i -lt $count ]]; do
+        local severity pattern
+        severity=$(echo "$result" | jq -r ".[$i].severity // \"medium\"" 2>/dev/null || echo "medium")
+        pattern=$(echo "$result" | jq -r ".[$i].pattern_broken // \"unknown\"" 2>/dev/null | head -c 50)
+        emit_event "architecture.violation" "severity=$severity" "pattern=$pattern"
+        i=$((i + 1))
+    done
+
+    if [[ "$count" -eq 0 ]]; then
+        success "No architecture violations found" >&2
+    else
+        warn "$count architecture violation(s) found" >&2
+    fi
+
+    echo "$result"
+}
+
+# ─── Evolve Model ────────────────────────────────────────────────────────
+
+architecture_evolve_model() {
+    local model_file="${1:-$(_model_path)}"
+    local changes_summary="${2:-}"
+
+    if ! _architecture_enabled; then
+        warn "Architecture enforcer disabled" >&2
+        return 0
+    fi
+
+    if [[ ! -f "$model_file" ]]; then
+        warn "No architecture model to evolve" >&2
+        return 0
+    fi
+
+    if [[ -z "$changes_summary" ]]; then
+        error "Usage: architecture evolve [model_file] <changes_summary>"
+        return 1
+    fi
+
+    info "Checking for architectural evolution..." >&2
+
+    local model
+    model=$(jq -c '.' "$model_file" 2>/dev/null || echo '{}')
+
+    local prompt
+    prompt=$(jq -n --arg model "$model" --arg changes "$changes_summary" '{
+        instruction: "This code change was validated against the architecture model. Does it represent an intentional architectural evolution? If so, return a JSON object with evolved: true and updated_model containing the full updated model (layers, patterns, conventions, dependencies arrays). If no evolution, return {evolved: false}.",
+        current_model: $model,
+        validated_changes: $changes
+    }' | jq -r 'to_entries | map("\(.key): \(.value)") | join("\n\n")')
+
+    local result
+    if ! result=$(_intelligence_call_claude "$prompt" "architecture_evolve_$(echo -n "$changes_summary" | head -c 200 | _intelligence_md5)" 300); then
+        warn "Claude call failed during evolution check" >&2
+        return 0
+    fi
+
+    local evolved
+    evolved=$(echo "$result" | jq -r '.evolved // false' 2>/dev/null || echo "false")
+
+    if [[ "$evolved" == "true" ]]; then
+        local updated_model
+        updated_model=$(echo "$result" | jq '.updated_model // empty' 2>/dev/null || true)
+
+        if [[ -n "$updated_model" ]] && echo "$updated_model" | jq '.layers' >/dev/null 2>&1; then
+            local tmp_file="${model_file}.tmp"
+            echo "$updated_model" > "$tmp_file"
+            mv "$tmp_file" "$model_file"
+            emit_event "architecture.evolved" "repo_hash=$(repo_hash)"
+            success "Architecture model evolved" >&2
+        else
+            warn "Evolution detected but updated model invalid — keeping current model" >&2
+        fi
+    else
+        info "No architectural evolution detected" >&2
+    fi
+}
+
+# ─── Help ─────────────────────────────────────────────────────────────────
+
+show_help() {
+    echo ""
+    echo -e "${CYAN}${BOLD}  Shipwright Architecture${RESET}  ${DIM}v${VERSION}${RESET}"
+    echo -e "${DIM}  ══════════════════════════════════════════${RESET}"
+    echo ""
+    echo -e "  ${BOLD}USAGE${RESET}"
+    echo -e "    shipwright architecture <command> [options]"
+    echo ""
+    echo -e "  ${BOLD}COMMANDS${RESET}"
+    echo -e "    ${CYAN}build${RESET}     [repo_root]                   Build architecture model"
+    echo -e "    ${CYAN}validate${RESET}  <diff> [model_file]           Validate changes against model"
+    echo -e "    ${CYAN}evolve${RESET}   [model_file] <changes_summary> Evolve model with new patterns"
+    echo -e "    ${CYAN}help${RESET}                                    Show this help"
+    echo ""
+    echo -e "  ${BOLD}CONFIGURATION${RESET}"
+    echo -e "    Feature flag:  ${DIM}intelligence.architecture_enabled${RESET} in daemon-config.json"
+    echo -e "    Model stored:  ${DIM}~/.shipwright/memory/<repo-hash>/architecture.json${RESET}"
+    echo ""
+}
+
+# ─── Command Router ──────────────────────────────────────────────────────
+
+main() {
+    case "${1:-help}" in
+        build)     shift; architecture_build_model "$@" ;;
+        validate)  shift; architecture_validate_changes "$@" ;;
+        evolve)    shift; architecture_evolve_model "$@" ;;
+        help|--help|-h) show_help ;;
+        *)         error "Unknown: $1"; exit 1 ;;
+    esac
+}
+
+if [[ "${BASH_SOURCE[0]}" == "$0" ]]; then
+    main "$@"
+fi