feat(localhost): add port management and loop-mode auto-branch

.agent/AGENTS.md

@@ -42,6 +42,22 @@ If the script outputs "STOP - ON PROTECTED BRANCH", you MUST NOT proceed with ed
 
 3. **Do NOT proceed until user replies with 1, 2, or 3**
 
+**Loop mode (autonomous agents)**: Loop agents (`/full-loop`, `/ralph-loop`) use auto-decision to avoid stalling:
+
+```bash
+~/.aidevops/agents/scripts/pre-edit-check.sh --loop-mode --task "task description"
+```
+
+Auto-decision rules:
+- **Docs-only tasks** (README, CHANGELOG, docs/, typos) -> Option 3 (stay on main)
+- **Code tasks** (feature, fix, implement, refactor, enhance) -> Option 1 (create worktree automatically)
+
+Exit codes: `0` = proceed, `1` = interactive stop, `2` = create worktree needed
+
+Detection keywords:
+- Docs-only: `readme`, `changelog`, `documentation`, `docs/`, `typo`, `spelling`
+- Code (overrides docs): `feature`, `fix`, `bug`, `implement`, `refactor`, `add`, `update`, `enhance`, `port`, `ssl`, `helper`
+
 **Why worktrees are the default**: The main repo directory (`~/Git/{repo}/`) should ALWAYS stay on `main`. This prevents:
 - Uncommitted changes blocking branch switches
 - Parallel sessions inheriting wrong branch state
@@ -93,6 +109,13 @@ Run pre-edit-check.sh in `~/Git/aidevops/` BEFORE any changes to either location
 
 **Quality Standards**: SonarCloud A-grade, ShellCheck zero violations
 
+**Localhost Standards** (for any local service setup):
+- **Always check port first**: `localhost-helper.sh check-port <port>` before starting services
+- **Use .local domains**: `myapp.local` not `localhost:3000` (enables password manager autofill)
+- **Always use SSL**: Via Traefik proxy with mkcert certificates
+- **Auto-find ports**: `localhost-helper.sh find-port <start>` if preferred port is taken
+- See `services/hosting/localhost.md` for full setup guide
+
 **SonarCloud Hotspot Patterns** (auto-excluded via `sonar-project.properties`):
 - Scripts matching `*-helper.sh`, `*-setup.sh`, `*-cli.sh`, `*-verify.sh` are excluded from:
   - S5332 (clear-text protocol) - `http://localhost` for local dev

.agent/scripts/commands/full-loop.md

@@ -16,19 +16,42 @@ Task Development → Preflight → PR Create → PR Review → Postflight → De
 
 ## Workflow
 
-### Step 1: Validate Prerequisites
+### Step 1: Auto-Branch Setup
 
-Before starting, verify:
+The loop automatically handles branch setup when on main/master:
 
-1. **On feature branch**: Must not be on main/master
-2. **Clean working directory**: Uncommitted changes should be committed or stashed
-3. **Git remote configured**: Need to push and create PR
+```bash
+# Run pre-edit check in loop mode with task description
+~/.aidevops/agents/scripts/pre-edit-check.sh --loop-mode --task "$ARGUMENTS"
+```
+
+**Exit codes:**
+- `0` - Already on feature branch OR docs-only task (proceed)
+- `1` - Interactive mode fallback (shouldn't happen in loop)
+- `2` - Code task on main (auto-create worktree)
+
+**Auto-decision logic:**
+- **Docs-only tasks** (README, CHANGELOG, docs/, typos): Stay on main
+- **Code tasks** (features, fixes, refactors, enhancements): Auto-create worktree
+
+**Detection keywords:**
+- Docs-only: `readme`, `changelog`, `documentation`, `docs/`, `typo`, `spelling`
+- Code (overrides docs): `feature`, `fix`, `bug`, `implement`, `refactor`, `add`, `update`, `enhance`, `port`, `ssl`
+
+**When worktree is needed:**
 
 ```bash
-# Check branch
-git branch --show-current
+# Generate branch name from task (sanitized, truncated to 40 chars)
+branch_name=$(echo "$ARGUMENTS" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | cut -c1-40)
+~/.aidevops/agents/scripts/worktree-helper.sh add "feature/$branch_name"
+# Continue in new worktree directory
+```
 
-# Check for uncommitted changes
+Also verify:
+- **Clean working directory**: Uncommitted changes should be committed or stashed
+- **Git remote configured**: Need to push and create PR
+
+```bash
 git status --short
 ```
 

.agent/scripts/localhost-helper.sh

@@ -15,9 +15,13 @@ YELLOW='\033[1;33m'
 RED='\033[0;31m'
 NC='\033[0m' # No Color
 
-# Error message constants
-readonly ERROR_UNKNOWN_COMMAND="Unknown command:"
-readonly HELP_USAGE_INFO="Use '$0 help' for usage information"
+# Error message constants (use shared-constants.sh if available, otherwise define locally)
+if [[ -z "${ERROR_UNKNOWN_COMMAND:-}" ]]; then
+    readonly ERROR_UNKNOWN_COMMAND="Unknown command:"
+fi
+if [[ -z "${HELP_USAGE_INFO:-}" ]]; then
+    readonly HELP_USAGE_INFO="Use '$0 help' for usage information"
+fi
 
 print_info() {
     local msg="$1"
@@ -46,6 +50,145 @@ print_error() {
 # Configuration file
 CONFIG_FILE="../configs/localhost-config.json"
 
+# =============================================================================
+# Port Management Functions
+# =============================================================================
+# These functions ensure port conflicts are avoided and services use available ports.
+# This is critical for:
+# 1. Avoiding "port already in use" errors
+# 2. Enabling SSL via reverse proxy (password managers require HTTPS)
+# 3. Consistent .local domain access across all local services
+
+# Default port range for auto-assignment
+readonly PORT_RANGE_START=3000
+readonly PORT_RANGE_END=9999
+
+# Check if a port is in use
+# Returns 0 if port is FREE, 1 if port is IN USE
+is_port_free() {
+    local port="$1"
+    if [[ -z "$port" ]]; then
+        print_error "Port number required"
+        return 1
+    fi
+
+    # Check using lsof (works on macOS and Linux)
+    if lsof -i :"$port" >/dev/null 2>&1; then
+        return 1  # Port is in use
+    fi
+
+    # Double-check with nc if available
+    if command -v nc >/dev/null 2>&1; then
+        if nc -z 127.0.0.1 "$port" 2>/dev/null; then
+            return 1  # Port is in use
+        fi
+    fi
+
+    return 0  # Port is free
+}
+
+# Find the next available port starting from a given port
+# Usage: find_available_port [start_port]
+# Returns: Prints the first available port
+find_available_port() {
+    local start_port="${1:-$PORT_RANGE_START}"
+    local port="$start_port"
+
+    while [[ $port -le $PORT_RANGE_END ]]; do
+        if is_port_free "$port"; then
+            echo "$port"
+            return 0
+        fi
+        ((port++))
+    done
+
+    print_error "No available ports found in range $start_port-$PORT_RANGE_END"
+    return 1
+}
+
+# Check port and suggest alternative if in use
+# Usage: check_port_or_suggest [port]
+# Returns: 0 if port is free, 1 if in use (prints suggestion)
+check_port_or_suggest() {
+    local port="$1"
+
+    if [[ -z "$port" ]]; then
+        print_error "Port number required"
+        return 1
+    fi
+
+    if is_port_free "$port"; then
+        print_success "Port $port is available"
+        return 0
+    else
+        local process_info
+        process_info=$(lsof -i :"$port" 2>/dev/null | tail -1 | awk '{print $1, $2}')
+        print_warning "Port $port is in use by: $process_info"
+
+        local suggested_port
+        suggested_port=$(find_available_port "$((port + 1))")
+        if [[ -n "$suggested_port" ]]; then
+            print_info "Suggested alternative: $suggested_port"
+            echo "SUGGESTED_PORT=$suggested_port"
+        fi
+        return 1
+    fi
+}
+
+# List all ports currently in use by local development services
+list_dev_ports() {
+    print_info "Ports in use by local development services:"
+    echo ""
+
+    # Common development port ranges
+    local dev_ports=(3000 3001 3002 3003 4000 5000 5173 5174 8000 8080 8085 8888 9000 9222 11235)
+
+    for port in "${dev_ports[@]}"; do
+        if ! is_port_free "$port"; then
+            local process_info
+            process_info=$(lsof -i :"$port" 2>/dev/null | tail -1 | awk '{print $1}')
+            echo "  :$port - $process_info"
+        fi
+    done
+
+    echo ""
+    print_info "Use 'lsof -i :<port>' for detailed process info"
+    return 0
+}
+
+# Kill process on a specific port
+kill_port() {
+    local port="$1"
+
+    if [[ -z "$port" ]]; then
+        print_error "Port number required"
+        return 1
+    fi
+
+    local pids
+    pids=$(lsof -ti :"$port" 2>/dev/null)
+
+    if [[ -z "$pids" ]]; then
+        print_info "No process found on port $port"
+        return 0
+    fi
+
+    print_warning "Killing process(es) on port $port: $pids"
+    echo "$pids" | xargs kill -9 2>/dev/null
+
+    # Wait up to 3 seconds for the port to become free
+    for _ in {1..6}; do
+        if is_port_free "$port"; then
+            print_success "Port $port is now free"
+            return 0
+        fi
+        sleep 0.5
+    done
+
+    print_error "Failed to free port $port"
+    return 1
+}
+
 # Check if config file exists
 check_config() {
     if [[ ! -f "$CONFIG_FILE" ]]; then
@@ -534,6 +677,18 @@ main() {
     "stop-mcp")
         stop_localwp_mcp
         ;;
+    "check-port")
+        check_port_or_suggest "$param2"
+        ;;
+    "find-port")
+        find_available_port "$param2"
+        ;;
+    "list-ports")
+        list_dev_ports
+        ;;
+    "kill-port")
+        kill_port "$param2"
+        ;;
     "help"|"-h"|"--help"|"")
         echo "Localhost Development Helper Script"
         echo "Usage: $0 [command] [options]"
@@ -553,6 +708,12 @@ main() {
         echo "  start-mcp                           - Start LocalWP MCP server for AI database access"
         echo "  stop-mcp                            - Stop LocalWP MCP server"
         echo ""
+        echo "Port Management Commands:"
+        echo "  check-port [port]                   - Check if port is available, suggest alternative"
+        echo "  find-port [start]                   - Find next available port from start (default: 3000)"
+        echo "  list-ports                          - List common dev ports in use"
+        echo "  kill-port [port]                    - Kill process using specified port"
+        echo ""
         echo "Examples:"
         echo "  $0 setup-dns"
         echo "  $0 setup-proxy"

.agent/scripts/pre-edit-check.sh

@@ -7,13 +7,72 @@
 #
 # Usage:
 #   ~/.aidevops/agents/scripts/pre-edit-check.sh
+#   ~/.aidevops/agents/scripts/pre-edit-check.sh --loop-mode --task "description"
+#
+# Exit codes:
+#   0 - OK to proceed (on feature branch, or docs-only on main in loop mode)
+#   1 - STOP (on protected branch, interactive mode)
+#   2 - Create worktree (loop mode detected code task on main)
 #
 # AI assistants should call this before any Edit/Write tool and STOP if it
 # returns a warning about being on main branch.
 # =============================================================================
 
 set -euo pipefail
 
+# =============================================================================
+# Loop Mode Support
+# =============================================================================
+# When --loop-mode is passed, the script auto-decides based on task description:
+# - Docs-only tasks (README, CHANGELOG, docs/) -> stay on main (exit 0)
+# - Code tasks (feature, fix, implement, etc.) -> signal worktree needed (exit 2)
+
+LOOP_MODE=false
+TASK_DESC=""
+
+while [[ $# -gt 0 ]]; do
+    case $1 in
+        --loop-mode)
+            LOOP_MODE=true
+            shift
+            ;;
+        --task)
+            TASK_DESC="$2"
+            shift 2
+            ;;
+        *)
+            shift
+            ;;
+    esac
+done
+
+# Function to detect if task is docs-only
+is_docs_only() {
+    local task="$1"
+    # Use bash 4.0+ parameter expansion for lowercase (more efficient than tr)
+    local task_lower="${task,,}"
+
+    # Code change indicators (negative match - if present, NOT docs-only)
+    # These take precedence over docs patterns
+    local code_patterns="feature|fix|bug|implement|refactor|add.*function|update.*code|create.*script|modify.*config|change.*logic|new.*api|endpoint|enhance|port|ssl|helper"
+
+    # Docs-only indicators (positive match)
+    local docs_patterns="^readme|^changelog|^documentation|docs/|typo|spelling|comment only|license only|^update readme|^update changelog|^update docs"
+
+    # Check for code patterns first (takes precedence)
+    if echo "$task_lower" | grep -qE "$code_patterns"; then
+        return 1  # Not docs-only
+    fi
+
+    # Check for docs patterns
+    if echo "$task_lower" | grep -qE "$docs_patterns"; then
+        return 0  # Is docs-only
+    fi
+
+    # Default: not docs-only (safer to create branch)
+    return 1
+}
+
 # Colors
 RED='\033[0;31m'
 GREEN='\033[0;32m'
@@ -37,6 +96,21 @@ fi
 
 # Check if on main or master
 if [[ "$current_branch" == "main" || "$current_branch" == "master" ]]; then
+    # Loop mode: auto-decide based on task description
+    if [[ "$LOOP_MODE" == "true" ]]; then
+        if is_docs_only "$TASK_DESC"; then
+            echo -e "${YELLOW}LOOP-AUTO${NC}: Docs-only task detected, staying on $current_branch"
+            echo "LOOP_DECISION=stay"
+            exit 0
+        else
+            # Auto-create worktree for code changes
+            echo -e "${YELLOW}LOOP-AUTO${NC}: Code task detected, worktree required"
+            echo "LOOP_DECISION=worktree"
+            exit 2  # Special exit code for "create worktree"
+        fi
+    fi
+
+    # Interactive mode: show warning and exit
     echo ""
     echo -e "${RED}${BOLD}======================================================${NC}"
     echo -e "${RED}${BOLD}  STOP - ON PROTECTED BRANCH: $current_branch${NC}"