specweave 1.0.300 → 1.0.301

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-*/`

package/plugins/specweave-jira/skills/jira-mapper/SKILL.md

@@ -87,29 +87,28 @@ JIRA_DOMAIN="$(grep '^JIRA_DOMAIN=' .env | head -1 | cut -d '=' -f2-)"
 ### Domain Validation (before ANY API call)
 
 ```bash
-# Must be a valid hostname — no special chars, no consecutive dots
-if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*$ ]]; then
-  echo "Error: JIRA_DOMAIN contains invalid characters"
+# Reject IP addresses FIRST — IPv4, IPv6 brackets, hex-encoded (SSRF prevention)
+if [[ "$JIRA_DOMAIN" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+ ]] || [[ "$JIRA_DOMAIN" =~ ^\[.*\]$ ]] || [[ "$JIRA_DOMAIN" =~ ^0x ]]; then
+  echo "Error: IP addresses not allowed — use a hostname"
   exit 1
 fi
 
-# Cloud JIRA: must match <subdomain>.atlassian.net
-if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9-]+\.atlassian\.net$ ]]; then
-  echo "Error: Domain does not match <subdomain>.atlassian.net pattern"
-  echo "Self-hosted JIRA requires explicit user confirmation"
+# Reject localhost and private networks
+if [[ "$JIRA_DOMAIN" =~ ^(localhost|127\.|10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.) ]]; then
+  echo "Error: Internal/localhost addresses not allowed"
   exit 1
-  # Agent: use AskUserQuestion to confirm non-standard domain before retrying
 fi
 
-# Reject IP addresses (SSRF prevention)
-if [[ "$JIRA_DOMAIN" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+ ]] || [[ "$JIRA_DOMAIN" =~ ^\[.*\]$ ]] || [[ "$JIRA_DOMAIN" =~ ^0x ]]; then
-  echo "Error: IP addresses not allowed — use a hostname"
+# Must be a valid hostname — no special chars, no consecutive dots
+if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*$ ]]; then
+  echo "Error: JIRA_DOMAIN contains invalid characters"
   exit 1
 fi
 
-# Reject localhost and private networks
-if [[ "$JIRA_DOMAIN" =~ ^(localhost|127\.|10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.) ]]; then
-  echo "Error: Internal/localhost addresses not allowed"
+# Cloud JIRA: must match <subdomain>.atlassian.net
+# Agent: use AskUserQuestion to confirm non-standard domain before retrying
+if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9-]+\.atlassian\.net$ ]]; then
+  echo "Error: Domain does not match <subdomain>.atlassian.net pattern"
   exit 1
 fi
 ```

package/plugins/specweave-jira/skills/jira-resource-validator/SKILL.md

@@ -9,6 +9,76 @@ allowed-tools: Read, Bash, Write, Edit
 
 **Auto-Activation**: Triggers when Jira setup or validation is needed.
 
+## Security Rules (MANDATORY)
+
+These rules apply to ALL JIRA API operations in this skill.
+
+### Credential Handling
+
+1. **Never collect credentials** — this skill reads from `.env` only, never prompts the user
+2. **Never log secrets** — never echo token values, auth headers, or base64 credentials
+3. **Never write credentials** — the user configures `.env` themselves (this skill may update non-secret keys like `JIRA_BOARDS` and `JIRA_PROJECT`)
+
+### Credential Loading
+
+```bash
+# 1. Validate presence FIRST (before reading any values)
+for KEY in JIRA_API_TOKEN JIRA_EMAIL JIRA_DOMAIN; do
+  if ! grep -qE "^${KEY}=.+" .env; then
+    echo "Error: ${KEY} missing or empty in .env"
+    exit 1
+  fi
+done
+
+# 2. Load credentials ONLY after validation passes (never display values)
+#    head -1 ensures only first match used if .env has duplicate keys
+JIRA_API_TOKEN="$(grep '^JIRA_API_TOKEN=' .env | head -1 | cut -d '=' -f2-)"
+JIRA_EMAIL="$(grep '^JIRA_EMAIL=' .env | head -1 | cut -d '=' -f2-)"
+JIRA_DOMAIN="$(grep '^JIRA_DOMAIN=' .env | head -1 | cut -d '=' -f2-)"
+```
+
+### Domain Validation (before ANY API call)
+
+```bash
+# Reject IP addresses first (SSRF prevention)
+if [[ "$JIRA_DOMAIN" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+ ]] || [[ "$JIRA_DOMAIN" =~ ^\[.*\]$ ]] || [[ "$JIRA_DOMAIN" =~ ^0x ]]; then
+  echo "Error: IP addresses not allowed — use a hostname"
+  exit 1
+fi
+
+# Reject localhost and private networks
+if [[ "$JIRA_DOMAIN" =~ ^(localhost|127\.|10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.) ]]; then
+  echo "Error: Internal/localhost addresses not allowed"
+  exit 1
+fi
+
+# Must be a valid hostname — no special chars, no consecutive dots
+if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*$ ]]; then
+  echo "Error: JIRA_DOMAIN contains invalid characters"
+  exit 1
+fi
+
+# Cloud JIRA: must match <subdomain>.atlassian.net
+if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9-]+\.atlassian\.net$ ]]; then
+  echo "Error: Domain does not match <subdomain>.atlassian.net pattern"
+  exit 1
+fi
+```
+
+### API Call Pattern (HTTPS only, quoted variables)
+
+```bash
+AUTH="$(printf '%s:%s' "$JIRA_EMAIL" "$JIRA_API_TOKEN" | base64)"
+
+# All API calls MUST use https://, double-quote all variables
+curl -s -f \
+  -H "Authorization: Basic $AUTH" \
+  -H "Content-Type: application/json" \
+  "https://${JIRA_DOMAIN}/rest/api/3/..."
+```
+
+---
+
 ## What This Skill Does
 
 This skill ensures your Jira configuration in `.env` is valid and all resources exist. It's **smart enough** to:
@@ -31,10 +101,10 @@ This skill ensures your Jira configuration in `.env` is valid and all resources
 
 ### Required .env Variables
 
-```bash
-JIRA_API_TOKEN=your_token_here
-JIRA_EMAIL=your_email@company.com
-JIRA_DOMAIN=yourcompany.atlassian.net
+```
+JIRA_API_TOKEN=<your-token>
+JIRA_EMAIL=<your-email>
+JIRA_DOMAIN=<your-company>.atlassian.net
 JIRA_STRATEGY=board-based
 JIRA_PROJECT=PROJECTKEY
 JIRA_BOARDS=1,2,3  # IDs (if exist) OR names (if creating)

package/plugins/specweave-jira/skills/jira-sync/SKILL.md

@@ -106,29 +106,28 @@ if [ -z "$JIRA_DOMAIN" ]; then
   exit 1
 fi
 
-# Must be a valid hostname — each label: alphanumeric, hyphens allowed mid-label, no consecutive dots
-if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*$ ]]; then
-  echo "Error: JIRA_DOMAIN is not a valid hostname"
+# Reject IP addresses FIRST — IPv4, IPv6 brackets, hex-encoded (SSRF prevention)
+if [[ "$JIRA_DOMAIN" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+ ]] || [[ "$JIRA_DOMAIN" =~ ^\[.*\]$ ]] || [[ "$JIRA_DOMAIN" =~ ^0x ]]; then
+  echo "Error: IP addresses not allowed — use a hostname"
   exit 1
 fi
 
-# Must end with .atlassian.net for cloud JIRA
-if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9-]+\.atlassian\.net$ ]]; then
-  echo "Error: Domain does not match <subdomain>.atlassian.net pattern"
-  echo "Self-hosted JIRA requires explicit user confirmation"
+# Reject localhost and internal hostnames
+if [[ "$JIRA_DOMAIN" =~ ^(localhost|127\.|10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.) ]]; then
+  echo "Error: Internal/localhost addresses not allowed"
   exit 1
-  # Agent: use AskUserQuestion to confirm non-standard domain before retrying
 fi
 
-# Reject IP addresses — IPv4, IPv6 brackets, hex-encoded (SSRF prevention)
-if [[ "$JIRA_DOMAIN" =~ ^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+ ]] || [[ "$JIRA_DOMAIN" =~ ^\[.*\]$ ]] || [[ "$JIRA_DOMAIN" =~ ^0x ]]; then
-  echo "Error: IP addresses not allowed — use a hostname"
+# Must be a valid hostname — each label: alphanumeric, hyphens allowed mid-label, no consecutive dots
+if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?(\.[a-zA-Z0-9]([a-zA-Z0-9-]*[a-zA-Z0-9])?)*$ ]]; then
+  echo "Error: JIRA_DOMAIN is not a valid hostname"
   exit 1
 fi
 
-# Reject localhost and internal hostnames
-if [[ "$JIRA_DOMAIN" =~ ^(localhost|127\.|10\.|172\.(1[6-9]|2[0-9]|3[01])\.|192\.168\.) ]]; then
-  echo "Error: Internal/localhost addresses not allowed"
+# Must end with .atlassian.net for cloud JIRA
+# Agent: use AskUserQuestion to confirm non-standard domain before retrying
+if [[ ! "$JIRA_DOMAIN" =~ ^[a-zA-Z0-9-]+\.atlassian\.net$ ]]; then
+  echo "Error: Domain does not match <subdomain>.atlassian.net pattern"
   exit 1
 fi
 ```
@@ -168,7 +167,7 @@ JIRA and Confluence are both Atlassian products and often used together. This sk
 
 ### Confluence Credentials
 
-Same authentication and security rules as JIRA — user configures `.env`, skill only validates presence. Same domain validation applies (must be `<subdomain>.atlassian.net`, HTTPS only, no IPs).
+Same authentication and security rules as JIRA — user configures `.env`, skill only validates presence. Same domain validation applies (must be `<subdomain>.atlassian.net`, HTTPS only, no IPs). `CONFLUENCE_DOMAIN` MUST pass the same validation as `JIRA_DOMAIN` (Step 4) before any Confluence API call.
 
 Required `.env` keys (configured by the user, NOT by this skill):
 ```
@@ -190,20 +189,12 @@ CONFLUENCE_SPACE_KEY=<space-key>
 
 **Every page update MUST increment the version number**:
 
-```bash
-# 1. Get current version
-curl -s GET ".../pages/{id}" | jq '.version.number'
-# Returns: 5
+1. GET current page to retrieve `version.number` (e.g., returns 5)
+2. PUT update with `version.number` set to current + 1 (e.g., 6)
 
-# 2. Update with version + 1
-PUT ".../pages/{id}"
-{ "version": { "number": 6 } }
-```
+If version is not incremented, the API returns `409 Conflict`.
 
-**Error if version not incremented**:
-```
-409 Conflict: "Version must be incremented on update. Current version is: 5"
-```
+All Confluence API calls follow the same security rules as JIRA (HTTPS only, domain validation, credential handling). See the `jira-mapper` skill's **Security Rules** section for implementation patterns.
 
 ### Reference Documentation