specweave 1.0.299 → 1.0.301

package/plugins/specweave/hooks/user-prompt-submit.sh

@@ -5,10 +5,10 @@
 # Purpose: Auto-load plugins, discipline validation, context injection, instant command execution
 #
 # FEATURES:
-# - v1.0.278: DIRECT PLUGIN COPY - sw-* plugins installed via direct file copy instead of
-#   npx vskill (which was broken for all production users). Uses install_plugin_direct() that
-#   reads marketplace.json, copies source dir to ~/.claude/commands/<name>/, and fixes .sh
-#   permissions. No external dependencies. vskill.lock fast-path still used for skip check.
+# - v1.0.279: VSKILL INSTALL - sw-* plugins installed via vskill at project scope.
+#   Uses install_plugin_via_vskill(): node <vskill-cli> install <specweave-dir>
+#   --plugin <name> --plugin-dir <dir> --force, run from SW_PROJECT_ROOT.
+#   Installs to .claude/commands/<name>/ (project scope). Never ~/.claude/commands/.
 # - v1.0.201: LSP CLI FALLBACK INSTRUCTIONS - When LSP requested, instruct Claude to use
 #   `specweave lsp` commands instead of Grep. These use TsServerClient for REAL semantic
 #   analysis. Key fix: "find references" now gets semantic refs, not text matches!
@@ -266,61 +266,72 @@ fi
 
 if [[ "$SCOPE_GUARD_RUN" == "true" ]] && command -v jq >/dev/null 2>&1 && command -v claude >/dev/null 2>&1; then
   USER_SETTINGS="$HOME/.claude/settings.json"
+  PROJECT_SETTINGS="${SW_PROJECT_ROOT}/.claude/settings.json"
 
+  # ---- 1. Clean user-level settings ----
+  # Remove: sw-* domain plugins at user scope (should be project-scoped via vskill)
+  #         any *@claude-plugins-official (never allowed)
+  # Exempt: sw@specweave (core plugin, user-scoped by design)
   if [[ -f "$USER_SETTINGS" ]]; then
-    # Find SpecWeave domain plugins and LSP plugins at user level
-    # Exempt: sw@specweave (core plugin, intentionally user-scoped)
-    POLLUTED_PLUGINS=$(jq -r '
+    POLLUTED_USER=$(jq -r '
       .enabledPlugins // {} | to_entries[]
       | select(
           (.key | test("^sw-.*@specweave$")) or
-          (.key | test("-lsp@"))
+          (.key | test("@claude-plugins-official$"))
         )
       | .key
     ' "$USER_SETTINGS" 2>/dev/null)
 
-    if [[ -n "$POLLUTED_PLUGINS" ]]; then
-      MIGRATED=""
-      for plugin_key in $POLLUTED_PLUGINS; do
-        # Uninstall from user scope
+    if [[ -n "$POLLUTED_USER" ]]; then
+      REMOVED=""
+      REINSTALLED=""
+      for plugin_key in $POLLUTED_USER; do
         if timeout 5 claude plugin uninstall "$plugin_key" >/dev/null 2>&1; then
-          # v1.0.278: sw-* plugins reinstall via direct copy, LSP plugins via claude CLI
           if [[ "$plugin_key" == sw-*@specweave ]]; then
-            # Extract plugin name from "sw-name@specweave" format
+            # Reinstall sw-* at project scope via vskill
             _sw_name="${plugin_key%%@*}"
-            if install_plugin_direct "$_sw_name"; then
-              [[ -n "$MIGRATED" ]] && MIGRATED="$MIGRATED, "
-              MIGRATED="${MIGRATED}${plugin_key}"
-            fi
-          else
-            # LSP and other plugins: reinstall via claude CLI at project scope
-            if timeout 10 claude plugin install "$plugin_key" --scope project >/dev/null 2>&1; then
-              [[ -n "$MIGRATED" ]] && MIGRATED="$MIGRATED, "
-              MIGRATED="${MIGRATED}${plugin_key}"
+            if install_plugin_via_vskill "$_sw_name"; then
+              [[ -n "$REINSTALLED" ]] && REINSTALLED="$REINSTALLED, "
+              REINSTALLED="${REINSTALLED}${plugin_key}"
             fi
           fi
+          # *@claude-plugins-official: uninstall only — never reinstall
+          [[ -n "$REMOVED" ]] && REMOVED="$REMOVED, "
+          REMOVED="${REMOVED}${plugin_key}"
         fi
       done
 
-      if [[ -n "$MIGRATED" ]]; then
-        echo "[$(date -Iseconds)] scope-guard | migrated user→project: $MIGRATED" >> "$SW_PROJECT_ROOT/.specweave/state/hook.log" 2>/dev/null || true
+      if [[ -n "$REMOVED" ]]; then
+        echo "[$(date -Iseconds)] scope-guard | removed user-level: $REMOVED | reinstalled@project: ${REINSTALLED:-none}" >> "$SW_PROJECT_ROOT/.specweave/state/hook.log" 2>/dev/null || true
       fi
 
-      # CRITICAL FIX: Restore sw@specweave enabled state after uninstall operations
-      # The `claude plugin uninstall` commands above may corrupt ~/.claude/settings.json
-      # and disable sw@specweave as collateral damage. Re-enable it explicitly.
-      if [[ -f "$USER_SETTINGS" ]]; then
-        SW_ENABLED=$(jq -r '.enabledPlugins."sw@specweave" // "not_set"' "$USER_SETTINGS" 2>/dev/null)
-        if [[ "$SW_ENABLED" != "true" ]]; then
-          # Re-enable core plugin (preserves all other settings)
-          jq '.enabledPlugins."sw@specweave" = true' "$USER_SETTINGS" > "${USER_SETTINGS}.tmp" 2>/dev/null && \
-            mv "${USER_SETTINGS}.tmp" "$USER_SETTINGS" 2>/dev/null || true
-          echo "[$(date -Iseconds)] scope-guard | restored sw@specweave enabled state" >> "$SW_PROJECT_ROOT/.specweave/state/hook.log" 2>/dev/null || true
-        fi
+      # Restore sw@specweave core plugin enabled state (uninstall may collateral-damage it)
+      SW_ENABLED=$(jq -r '.enabledPlugins."sw@specweave" // "not_set"' "$USER_SETTINGS" 2>/dev/null)
+      if [[ "$SW_ENABLED" != "true" ]]; then
+        jq '.enabledPlugins."sw@specweave" = true' "$USER_SETTINGS" > "${USER_SETTINGS}.tmp" 2>/dev/null && \
+          mv "${USER_SETTINGS}.tmp" "$USER_SETTINGS" 2>/dev/null || true
+        echo "[$(date -Iseconds)] scope-guard | restored sw@specweave" >> "$SW_PROJECT_ROOT/.specweave/state/hook.log" 2>/dev/null || true
       fi
     fi
   fi
 
+  # ---- 2. Clean project-level settings ----
+  # Remove any *@claude-plugins-official from project settings — never allowed
+  if [[ -f "$PROJECT_SETTINGS" ]]; then
+    POLLUTED_PROJECT=$(jq -r '
+      .enabledPlugins // {} | to_entries[]
+      | select(.key | test("@claude-plugins-official$"))
+      | .key
+    ' "$PROJECT_SETTINGS" 2>/dev/null)
+
+    if [[ -n "$POLLUTED_PROJECT" ]]; then
+      for plugin_key in $POLLUTED_PROJECT; do
+        timeout 5 claude plugin uninstall "$plugin_key" >/dev/null 2>&1 || true
+      done
+      echo "[$(date -Iseconds)] scope-guard | removed project official plugins: $POLLUTED_PROJECT" >> "$SW_PROJECT_ROOT/.specweave/state/hook.log" 2>/dev/null || true
+    fi
+  fi
+
   # Write today's marker
   mkdir -p "$(dirname "$SCOPE_GUARD_MARKER")" 2>/dev/null
   date +%Y-%m-%d > "$SCOPE_GUARD_MARKER" 2>/dev/null || true
@@ -472,85 +483,59 @@ check_plugin_in_vskill_lock() {
   fi
 }
 
-# Helper: Install sw-* plugin via direct copy (v1.0.278)
-# Copies plugin source dir to ~/.claude/commands/<name>/ and fixes hook permissions.
-# No external dependencies (replaces npx vskill shell-out).
+# Helper: Install sw-* plugin via vskill (v1.0.279)
+# Uses: node <vskill-cli> install <specweave-dir> --plugin <name> --plugin-dir <specweave-dir> --force
+# Installs to project scope: ${SW_PROJECT_ROOT}/.claude/commands/<name>/
 # Args: $1=plugin name (e.g., "sw-frontend")
 # Returns: 0 if installed successfully, 1 if failed
 # Sets VSKILL_INSTALL_OUTPUT with status message
-install_plugin_direct() {
+install_plugin_via_vskill() {
   local plugin="$1"
-  local plugin_dir="${HOME}/.claude/plugins/marketplaces/specweave"
-  local marketplace_json="$plugin_dir/.claude-plugin/marketplace.json"
-
-  # Verify marketplace directory exists
-  if [[ ! -d "$plugin_dir" ]] || [[ ! -f "$marketplace_json" ]]; then
-    VSKILL_INSTALL_OUTPUT="marketplace directory not found at $plugin_dir"
+  local specweave_dir="${HOME}/.claude/plugins/marketplaces/specweave"
+  local project_dir="${SW_PROJECT_ROOT:-$PWD}"
+
+  # Find node binary
+  local node_bin
+  node_bin=$(command -v node 2>/dev/null)
+  if [[ -z "$node_bin" ]]; then
+    VSKILL_INSTALL_OUTPUT="node not found in PATH"
     return 1
   fi
 
-  # Resolve plugin source directory from marketplace.json
-  local source_rel=""
-  if command -v jq >/dev/null 2>&1; then
-    source_rel=$(jq -r --arg name "$plugin" '.plugins[] | select(.name == $name) | .source' "$marketplace_json" 2>/dev/null)
+  # Find vskill CLI — check global first, then bundled with specweave
+  local vskill_cli=""
+  if command -v vskill >/dev/null 2>&1; then
+    vskill_cli=$(command -v vskill)
   else
-    # Fallback: grep-based extraction
-    source_rel=$(grep -oP "\"name\"\\s*:\\s*\"${plugin}\"[^}]*\"source\"\\s*:\\s*\"([^\"]+)\"" "$marketplace_json" | grep -oP '"source"\s*:\s*"\K[^"]+' || true)
+    # Look for vskill bundled alongside specweave in node_modules
+    local candidate="${specweave_dir}/../../../node_modules/.bin/vskill"
+    if [[ -f "$candidate" ]]; then
+      vskill_cli="$candidate"
+    fi
   fi
 
-  if [[ -z "$source_rel" ]]; then
-    VSKILL_INSTALL_OUTPUT="plugin '$plugin' not found in marketplace.json"
+  if [[ -z "$vskill_cli" ]]; then
+    VSKILL_INSTALL_OUTPUT="vskill not found — install with: npm install -g vskill"
     return 1
   fi
 
-  # Resolve full path (source is relative to plugin_dir, e.g. ./plugins/specweave)
-  local source_dir="$plugin_dir/${source_rel#./}"
-  if [[ ! -d "$source_dir" ]]; then
-    VSKILL_INSTALL_OUTPUT="source dir not found: $source_dir"
+  # Verify specweave marketplace dir exists
+  if [[ ! -d "$specweave_dir" ]]; then
+    VSKILL_INSTALL_OUTPUT="specweave marketplace dir not found at $specweave_dir"
     return 1
   fi
 
-  # Copy to target
-  local target_dir="${HOME}/.claude/commands/${plugin}"
-  mkdir -p "$target_dir"
-  if cp -R "$source_dir/." "$target_dir/" 2>/dev/null; then
-    # Fix hook permissions (.sh files need to be executable)
-    find "$target_dir" -name "*.sh" -exec chmod 755 {} \; 2>/dev/null || true
-
-    # Write lockfile entry so subsequent prompts skip re-install
-    local lock_dir="${SW_PROJECT_ROOT:-$PWD}"
-    local lockfile="$lock_dir/vskill.lock"
-    local now
-    now=$(date -u +"%Y-%m-%dT%H:%M:%SZ" 2>/dev/null || date -Iseconds 2>/dev/null)
-
-    if command -v jq >/dev/null 2>&1 && [[ -n "$lock_dir" ]]; then
-      local skill_entry
-      skill_entry=$(jq -n \
-        --arg ver "0.0.0" \
-        --arg now "$now" \
-        '{version: $ver, sha: "", tier: "BUNDLED", installedAt: $now, source: "local:specweave"}')
-
-      if [[ -f "$lockfile" ]]; then
-        # Merge into existing lockfile
-        jq --arg key "$plugin" --argjson entry "$skill_entry" --arg now "$now" \
-          '.skills[$key] = $entry | .updatedAt = $now' \
-          "$lockfile" > "${lockfile}.tmp" 2>/dev/null && \
-          mv "${lockfile}.tmp" "$lockfile" 2>/dev/null || true
-      else
-        # Create new lockfile
-        jq -n \
-          --arg now "$now" \
-          --arg key "$plugin" \
-          --argjson entry "$skill_entry" \
-          '{version: 1, agents: ["claude-code"], skills: {($key): $entry}, createdAt: $now, updatedAt: $now}' \
-          > "$lockfile" 2>/dev/null || true
-      fi
-    fi
+  # Run vskill install at project scope (cwd = project root)
+  local output
+  output=$(cd "$project_dir" && "$node_bin" "$vskill_cli" install "$specweave_dir" \
+    --plugin "$plugin" --plugin-dir "$specweave_dir" --force 2>&1)
+  local exit_code=$?
 
-    VSKILL_INSTALL_OUTPUT="installed $plugin via direct copy"
+  if [[ $exit_code -eq 0 ]]; then
+    VSKILL_INSTALL_OUTPUT="installed $plugin via vskill (project scope)"
     return 0
   else
-    VSKILL_INSTALL_OUTPUT="copy failed for $plugin"
+    VSKILL_INSTALL_OUTPUT="vskill install failed for $plugin: $output"
     return 1
   fi
 }
@@ -1158,6 +1143,16 @@ if [[ "${SPECWEAVE_DISABLE_AUTO_LOAD:-0}" != "1" ]] && [[ "${SPECWEAVE_DISABLE_H
     # Quick skip: already using /sw: commands (user is in workflow)
     if ! echo "$PROMPT" | grep -qE "^[[:space:]]*/sw:"; then
 
+      # BYPASS: Native Claude Code slash commands (e.g., /context, /help, /doctor)
+      # Prevents 15s detect-intent timeout -> LLM_DETECTION_FAILED -> keyword fallback
+      # that falsely matches "test" as substring inside "/context". Pattern matches
+      # /word or /word-word prompts that do not mention specweave.
+      if echo "$PROMPT" | grep -qE "^[[:space:]]*/[a-z][a-z0-9-]*([[:space:]]|$)" &&
+         ! echo "$PROMPT" | grep -qiE "specweave"; then
+        echo '{"decision":"approve"}'
+        exit 0
+      fi
+
       # Check if specweave CLI is available
       if command -v specweave >/dev/null 2>&1; then
         # Setup logging (use project root, never create dirs at $HOME)
@@ -1260,13 +1255,10 @@ if [[ "${SPECWEAVE_DISABLE_AUTO_LOAD:-0}" != "1" ]] && [[ "${SPECWEAVE_DISABLE_H
                   for plugin in $DETECTED_PLUGINS; do
                     [[ -z "$plugin" ]] && continue
 
-                    # v1.0.159: Determine marketplace based on plugin name
-                    # sw-* plugins → @specweave (via vskill), others → @claude-plugins-official (via claude CLI)
-                    # v1.0.240 (0198): context7/playwright removed from auto-install
-                    # v1.0.278 (0241): sw-* plugins now installed via direct copy (no vskill dependency)
+                    # v1.0.279: Only @specweave plugins allowed — no claude-plugins-official
+                    # Install via vskill (project scope: .claude/commands/<name>/)
                     if [[ "$plugin" == sw-* ]] || [[ "$plugin" == "sw" ]]; then
-                      # ---- SW-* PLUGINS: Install via direct copy (v1.0.278) ----
-                      # Fast-path: check vskill.lock first (no CLI invocation needed)
+                      # Fast-path: check vskill.lock first
                       if check_plugin_in_vskill_lock "$plugin"; then
                         [[ -n "$PLUGINS_ALREADY" ]] && PLUGINS_ALREADY="$PLUGINS_ALREADY, "
                         PLUGINS_ALREADY="${PLUGINS_ALREADY}${plugin}"
@@ -1275,61 +1267,18 @@ if [[ "${SPECWEAVE_DISABLE_AUTO_LOAD:-0}" != "1" ]] && [[ "${SPECWEAVE_DISABLE_H
                         [[ -n "$PLUGINS_ALREADY" ]] && PLUGINS_ALREADY="$PLUGINS_ALREADY, "
                         PLUGINS_ALREADY="${PLUGINS_ALREADY}${plugin}"
                       else
-                        # Not installed - install via direct copy
-                        if install_plugin_direct "$plugin"; then
+                        # Install via vskill at project scope
+                        if install_plugin_via_vskill "$plugin"; then
                           [[ -n "$PLUGINS_INSTALLED" ]] && PLUGINS_INSTALLED="$PLUGINS_INSTALLED, "
                           PLUGINS_INSTALLED="${PLUGINS_INSTALLED}${plugin}"
-
-                          # Display scan result if available
-                          if [[ -n "$VSKILL_INSTALL_OUTPUT" ]]; then
-                            SCAN_RESULT=$(echo "$VSKILL_INSTALL_OUTPUT" | grep -oE "Score:[[:space:]]*[0-9]+/100[[:space:]]*Verdict:[[:space:]]*[A-Z]+" || true)
-                            [[ -n "$SCAN_RESULT" ]] && echo "[$(date -Iseconds)] vskill | ${plugin} | ${SCAN_RESULT}" >> "$LAZY_LOAD_LOG"
-                          fi
+                          echo "[$(date -Iseconds)] vskill | ${plugin} | ${VSKILL_INSTALL_OUTPUT:-ok}" >> "$LAZY_LOAD_LOG"
                         else
                           echo "[$(date -Iseconds)] vskill | ${plugin} | FAILED: ${VSKILL_INSTALL_OUTPUT:-unknown}" >> "$LAZY_LOAD_LOG"
                         fi
                       fi
                     else
-                      # ---- NON-SW PLUGINS: Install via claude CLI (unchanged) ----
-                      MARKETPLACE="claude-plugins-official"
-                      PLUGIN_SCOPE="$DEFAULT_PLUGIN_SCOPE"
-                      FULL_PLUGIN_NAME="${plugin}@${MARKETPLACE}"
-                      ALREADY_INSTALLED=false
-
-                      if check_plugin_installed_from_json "$plugin" "$MARKETPLACE"; then
-                        ALREADY_INSTALLED=true
-                      else
-                        CURRENT_PLUGINS=""
-                        if command -v timeout >/dev/null 2>&1; then
-                          CURRENT_PLUGINS=$(timeout 10 claude plugin list 2>/dev/null | grep -E "^  ❯ " | sed 's/^  ❯ //' || true)
-                        else
-                          CURRENT_PLUGINS=$(claude plugin list 2>/dev/null | grep -E "^  ❯ " | sed 's/^  ❯ //' || true)
-                        fi
-                        if echo "$CURRENT_PLUGINS" | grep -q "^${FULL_PLUGIN_NAME}$"; then
-                          ALREADY_INSTALLED=true
-                        fi
-                      fi
-
-                      if [[ "$ALREADY_INSTALLED" == "true" ]]; then
-                        [[ -n "$PLUGINS_ALREADY" ]] && PLUGINS_ALREADY="$PLUGINS_ALREADY, "
-                        PLUGINS_ALREADY="${PLUGINS_ALREADY}${plugin}"
-                      else
-                        if command -v timeout >/dev/null 2>&1; then
-                          OUT=$(timeout 10 claude plugin install "${FULL_PLUGIN_NAME}" --scope "$PLUGIN_SCOPE" 2>&1) || true
-                        else
-                          OUT=$(claude plugin install "${FULL_PLUGIN_NAME}" --scope "$PLUGIN_SCOPE" 2>&1) || true
-                        fi
-                        if echo "$OUT" | grep -qiE "(success|installed)"; then
-                          sleep 0.5
-                          if check_plugin_installed_from_json "$plugin" "$MARKETPLACE"; then
-                            [[ -n "$PLUGINS_INSTALLED" ]] && PLUGINS_INSTALLED="$PLUGINS_INSTALLED, "
-                            PLUGINS_INSTALLED="${PLUGINS_INSTALLED}${plugin}"
-                          else
-                            [[ -n "$PLUGINS_ALREADY" ]] && PLUGINS_ALREADY="$PLUGINS_ALREADY, "
-                            PLUGINS_ALREADY="${PLUGINS_ALREADY}${plugin}"
-                          fi
-                        fi
-                      fi
+                      # Non-sw-* plugin detected — skip (only @specweave plugins allowed)
+                      echo "[$(date -Iseconds)] plugins | SKIPPED non-specweave plugin: $plugin" >> "$LAZY_LOAD_LOG"
                     fi
                   done
 

package/plugins/specweave/scripts/setup-auto.sh

@@ -249,21 +249,61 @@ if [ "$ALL_BACKLOG" = "true" ]; then
     fi
 fi
 
-# If no increments specified, find current in-progress increment
+# If no increments specified, find current in-progress increment(s) via intent scoring
 if [ ${#INCREMENT_IDS[@]} -eq 0 ]; then
+    # Collect ALL active/in-progress increments (no blind first-match break)
+    _ACTIVE_DIRS=()
     for dir in "$INCREMENTS_DIR"/[0-9][0-9][0-9][0-9]-*/; do
         if [ -d "$dir" ]; then
             META_FILE="$dir/metadata.json"
             if [ -f "$META_FILE" ]; then
                 STATUS=$(jq -r '.status' "$META_FILE" 2>/dev/null || echo "")
                 if [ "$STATUS" = "active" ] || [ "$STATUS" = "in-progress" ]; then
-                    INCREMENT_ID=$(basename "$dir")
-                    INCREMENT_IDS+=("$INCREMENT_ID")
-                    break
+                    _ACTIVE_DIRS+=("$dir")
                 fi
             fi
         fi
     done
+
+    if [ ${#_ACTIVE_DIRS[@]} -eq 1 ]; then
+        # Fast path: single active increment, no scoring needed
+        INCREMENT_IDS+=("$(basename "${_ACTIVE_DIRS[0]}")")
+    elif [ ${#_ACTIVE_DIRS[@]} -gt 1 ]; then
+        select_best_increment() {
+            local prompt_text="$1"; shift; local dirs=("$@")
+            local _setup_dir; _setup_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+            local _score_script="$_setup_dir/../hooks/lib/score-increment.sh"
+
+            if [ -n "$prompt_text" ] && [ -f "$_score_script" ]; then
+                # Score each increment against the prompt, pick best
+                local _best_score=-1 _best_dir=""
+                for _dir in "${dirs[@]}"; do
+                    local _score; _score=$(bash "$_score_script" "$_dir" "$prompt_text" 2>/dev/null || echo "0")
+                    if [ "$_score" -gt "$_best_score" ]; then
+                        _best_score="$_score"; _best_dir="$_dir"
+                    fi
+                done
+                local _sel; _sel=$(basename "$_best_dir")
+                echo "🎯 Selected '$_sel' by intent match (score: $_best_score/100)" >&2
+                echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"event\":\"increment_selected\",\"increment\":\"$_sel\",\"method\":\"intent_scoring\",\"score\":$_best_score}" >> "$LOGS_DIR/auto-sessions.log"
+                echo "$_sel"
+            else
+                # No prompt: pick most-recently-modified increment
+                local _latest_mtime=0 _latest_dir=""
+                for _dir in "${dirs[@]}"; do
+                    local _mtime; _mtime=$(stat -f%m "$_dir/metadata.json" 2>/dev/null || stat -c%Y "$_dir/metadata.json" 2>/dev/null || echo "0")
+                    if [ "$_mtime" -gt "$_latest_mtime" ]; then
+                        _latest_mtime="$_mtime"; _latest_dir="$_dir"
+                    fi
+                done
+                local _sel; _sel=$(basename "${_latest_dir:-${dirs[0]}}")
+                echo "📅 Selected '$_sel' by most recent activity" >&2
+                echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"event\":\"increment_selected\",\"increment\":\"$_sel\",\"method\":\"recent_activity\"}" >> "$LOGS_DIR/auto-sessions.log"
+                echo "$_sel"
+            fi
+        }
+        INCREMENT_IDS+=("$(select_best_increment "$PROMPT" "${_ACTIVE_DIRS[@]}")")
+    fi
 fi
 
 if [ ${#INCREMENT_IDS[@]} -eq 0 ]; then
@@ -472,6 +512,20 @@ echo "$SESSION_JSON" | jq . > "$SESSION_FILE"
 # Log session start
 echo "{\"timestamp\":\"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\"event\":\"session_start\",\"sessionId\":\"$SESSION_ID\",\"increments\":${#INCREMENT_IDS[@]}}" >> "$LOGS_DIR/auto-sessions.log"
 
+# Write userGoal to auto-mode.json BEFORE the session start banner
+AUTO_MODE_FILE="$STATE_DIR/auto-mode.json"
+if [ -f "$AUTO_MODE_FILE" ]; then
+    if [ -n "$PROMPT" ]; then
+        _UPDATED_AM=$(jq --arg g "$PROMPT" '.userGoal = $g' "$AUTO_MODE_FILE" 2>/dev/null)
+    else
+        _UPDATED_AM=$(jq '.userGoal = null' "$AUTO_MODE_FILE" 2>/dev/null)
+    fi
+    [ -n "$_UPDATED_AM" ] && echo "$_UPDATED_AM" > "$AUTO_MODE_FILE"
+elif [ -n "$PROMPT" ]; then
+    # Create stub so stop hook can read userGoal even before LLM writes full auto-mode.json
+    jq -n --arg g "$PROMPT" '{"active":false,"userGoal":$g}' > "$AUTO_MODE_FILE"
+fi
+
 # Output - Session Start Banner
 echo ""
 echo "╔══════════════════════════════════════════════════════════════════════════════╗"

package/plugins/specweave/scripts/tests/test-setup-auto-selection.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# Tests for scored increment selection in setup-auto.sh (AC-US1-01, AC-US1-03, AC-US1-04)
+# Uses score-increment.sh directly to verify selection logic.
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCORE_SCRIPT="$SCRIPT_DIR/../../hooks/lib/score-increment.sh"
+TMPDIR_ROOT=$(mktemp -d)
+trap 'rm -rf "$TMPDIR_ROOT"' EXIT
+
+PASS=0; FAIL=0
+
+assert_eq() {
+    if [ "$1" = "$2" ]; then
+        echo "  ✓ $3"; PASS=$((PASS+1))
+    else
+        echo "  ✗ $3 (expected '$2', got '$1')"; FAIL=$((FAIL+1))
+    fi
+}
+
+assert_gt() {
+    if [ "$1" -gt "$2" ]; then
+        echo "  ✓ $3 ($1 > $2)"; PASS=$((PASS+1))
+    else
+        echo "  ✗ $3 (expected $1 > $2)"; FAIL=$((FAIL+1))
+    fi
+}
+
+make_increment() {
+    local dir="$TMPDIR_ROOT/$1"
+    mkdir -p "$dir"
+    echo "{\"title\":\"$2\",\"status\":\"active\",\"lastActivity\":\"$5\"}" > "$dir/metadata.json"
+    printf "# %s\n\n%s\n" "$2" "$3" > "$dir/spec.md"
+    printf "### T-001: %s\n**Status**: [ ] pending\n" "$4" > "$dir/tasks.md"
+    echo "$dir"
+}
+
+echo "scored increment selection tests"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# TC-007: Prompt-based selection picks best match
+d1=$(make_increment "0100-user-auth" "Authentication Login Feature" "Implement user authentication and login" "Add login endpoint" "2026-02-18T10:00:00Z")
+d2=$(make_increment "0101-deploy-pipeline" "CI/CD Deploy Pipeline" "Setup deployment pipeline with Docker" "Configure CI workflow" "2026-02-19T10:00:00Z")
+
+s1=$(bash "$SCORE_SCRIPT" "$d1" "authentication login" 2>/dev/null)
+s2=$(bash "$SCORE_SCRIPT" "$d2" "authentication login" 2>/dev/null)
+assert_gt "$s1" "$s2" "TC-007: auth scores higher than deploy for 'authentication login'"
+
+# TC-007b: Reverse -- deploy query should score deploy higher
+s3=$(bash "$SCORE_SCRIPT" "$d1" "deploy pipeline docker" 2>/dev/null)
+s4=$(bash "$SCORE_SCRIPT" "$d2" "deploy pipeline docker" 2>/dev/null)
+assert_gt "$s4" "$s3" "TC-007b: deploy scores higher than auth for 'deploy pipeline docker'"
+
+# TC-008: Single increment -- score still works (fast path skips scoring in setup-auto.sh)
+d3=$(make_increment "0102-single" "Single Active Feature" "Only one active increment exists" "Implement feature" "2026-02-19T12:00:00Z")
+result=$(bash "$SCORE_SCRIPT" "$d3" "single feature" 2>/dev/null)
+echo "$result" | grep -qE '^[0-9]+$' && \
+    echo "  ✓ TC-008: single increment scoring returns integer ($result)" && PASS=$((PASS+1)) || \
+    { echo "  ✗ TC-008: non-integer output: '$result'"; FAIL=$((FAIL+1)); }
+
+# TC-009: Empty query → 0 for all (triggers mtime fallback in setup-auto.sh)
+s5=$(bash "$SCORE_SCRIPT" "$d1" "" 2>/dev/null)
+s6=$(bash "$SCORE_SCRIPT" "$d2" "" 2>/dev/null)
+assert_eq "$s5" "0" "TC-009: empty query → 0 for increment A"
+assert_eq "$s6" "0" "TC-009b: empty query → 0 for increment B"
+
+# TC-X: Scoring is deterministic (same inputs → same output)
+s7=$(bash "$SCORE_SCRIPT" "$d1" "authentication login" 2>/dev/null)
+assert_eq "$s7" "$s1" "TC-X: scoring is deterministic"
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ] || exit 1

package/plugins/specweave/scripts/tests/test-setup-auto-usergoal.sh

@@ -0,0 +1,83 @@
+#!/bin/bash
+# Tests for userGoal wiring in setup-auto.sh (AC-US2-01, AC-US2-02, AC-US2-04)
+# Tests the logic directly without running the full setup-auto.sh.
+
+set -e
+
+TMPDIR_ROOT=$(mktemp -d)
+trap 'rm -rf "$TMPDIR_ROOT"' EXIT
+
+PASS=0; FAIL=0
+
+assert_eq() {
+    if [ "$1" = "$2" ]; then
+        echo "  ✓ $3"; PASS=$((PASS+1))
+    else
+        echo "  ✗ $3 (expected '$2', got '$1')"; FAIL=$((FAIL+1))
+    fi
+}
+
+# Helper: run userGoal wiring logic (extracted from setup-auto.sh)
+write_user_goal() {
+    local prompt="$1" file="$2"
+    if [ -f "$file" ]; then
+        if [ -n "$prompt" ]; then
+            local updated; updated=$(jq --arg g "$prompt" '.userGoal = $g' "$file" 2>/dev/null)
+        else
+            local updated; updated=$(jq '.userGoal = null' "$file" 2>/dev/null)
+        fi
+        [ -n "$updated" ] && echo "$updated" > "$file"
+    elif [ -n "$prompt" ]; then
+        jq -n --arg g "$prompt" '{"active":false,"userGoal":$g}' > "$file"
+    fi
+}
+
+echo "setup-auto.sh userGoal wiring tests"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+# TC-005: Prompt sets userGoal on existing file
+AM="$TMPDIR_ROOT/auto-mode.json"
+echo '{"active":false}' > "$AM"
+write_user_goal "fix auth bug" "$AM"
+result=$(jq -r '.userGoal' "$AM")
+assert_eq "$result" "fix auth bug" "TC-005: prompt sets userGoal"
+
+# TC-006: No prompt sets userGoal to null on existing file
+echo '{"active":false,"userGoal":"old goal"}' > "$AM"
+write_user_goal "" "$AM"
+result=$(jq -r '.userGoal' "$AM")
+assert_eq "$result" "null" "TC-006: no prompt → userGoal null"
+
+# TC-X: Prompt creates new file when absent
+rm -f "$AM"
+write_user_goal "add payment feature" "$AM"
+result=$(jq -r '.userGoal' "$AM")
+assert_eq "$result" "add payment feature" "TC-X1: creates file with userGoal"
+
+# TC-X: No prompt does NOT create file when absent (userGoal null only on existing files)
+rm -f "$AM"
+write_user_goal "" "$AM"
+if [ -f "$AM" ]; then
+    result=$(jq -r '.userGoal' "$AM")
+    assert_eq "$result" "null" "TC-X2: no-prompt no-file → file absent or null"
+else
+    echo "  ✓ TC-X2: no-prompt no-file → no file created"; PASS=$((PASS+1))
+fi
+
+# TC-X: Prompt preserves other fields in existing auto-mode.json
+echo '{"active":true,"incrementIds":["0100-auth"],"tddMode":false}' > "$AM"
+write_user_goal "fix login" "$AM"
+active=$(jq -r '.active' "$AM")
+goal=$(jq -r '.userGoal' "$AM")
+assert_eq "$active" "true" "TC-X3: existing fields preserved after goal write"
+assert_eq "$goal" "fix login" "TC-X3: userGoal set correctly"
+
+# TC-X: Special characters in prompt are handled safely
+echo '{"active":false}' > "$AM"
+write_user_goal 'fix "tricky" bug & deploy' "$AM"
+result=$(jq -r '.userGoal' "$AM")
+assert_eq "$result" 'fix "tricky" bug & deploy' "TC-X4: special chars in prompt"
+
+echo ""
+echo "Results: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ] || exit 1

package/plugins/specweave/skills/auto/SKILL.md

@@ -75,7 +75,7 @@ Use Read/Write/Edit/Glob tools directly (no CLI needed):
   "incrementIds": ["0001-feature"],
   "tddMode": false,
   "requireTests": false,
-  "userGoal": "optional",
+  "userGoal": null,
   "successCriteria": [
     { "type": "tasks_complete", "description": "All tasks marked complete", "required": true },
     { "type": "acs_satisfied", "description": "All ACs satisfied", "required": true }
@@ -96,6 +96,8 @@ Map flags to extra `successCriteria` entries:
 
 Always include `tasks_complete` and `acs_satisfied` as base criteria. Ensure `.specweave/state/` dir exists.
 
+**`userGoal` field**: Set to the user's stated intent from conversation context. If the user said "fix the auth bug", set `userGoal` to `"fix the auth bug"`. If no clear intent is expressed, set to `null`. This field is read by the stop hook to provide context-aware feedback and guide `/sw:do` to the correct increment.
+
 ### Step 1.5a: MANDATORY - Complexity Check for Team-Lead Routing
 
 **Before starting autonomous execution, check if this increment needs team-lead:**

package/plugins/specweave/skills/do/SKILL.md

@@ -49,6 +49,17 @@ When no ID provided, auto-select (NEVER ask user for ID):
 3. Select best candidate and auto-promote to in-progress if needed
 4. If no candidates, show status summary and offer: create new, close ready_for_review, resume backlog, or view status
 
+### Step 1.5: Auto-Mode Context Override
+
+When running inside an active auto session (`.specweave/state/auto-mode.json` has `active: true`):
+
+1. **Explicit ID takes priority**: If an explicit increment ID was passed (e.g., `/sw:do 0252`), use it directly — skip this step
+2. **Stop hook guidance**: If the stop hook feedback in the current conversation mentions a specific increment ID (e.g., "Continue: /sw:do 0252"), use that ID
+3. **Read incrementIds**: If no ID from above, read `incrementIds` array from `auto-mode.json` and use the **first entry** — this is the increment prioritized by scoring at session start
+4. **Skip filesystem scanning**: When auto-mode context provides an increment ID via steps 2 or 3, skip Step 1's filesystem scanning entirely — auto-mode context takes priority
+
+This ensures the execution loop stays focused on the contextually correct increment rather than re-scanning the filesystem each iteration.
+
 ### Step 2: Load Context
 
 1. **Find increment directory**: Normalize ID to 4-digit format, match `.specweave/increments/NNNN-*/`