fix(scripts): validate --number flag against existing branches/specs

When an AI assistant ignores the prompt instruction to omit --number
and passes a conflicting value (e.g. --number 1), the script now
detects the collision and auto-detects the next available number
instead of silently reusing it. This prevents branch numbering
from resetting to 001 — the root cause of #1744.

- Check specs directories and git branches (after fetch) for collisions
- Warn on stderr and fall back to auto-detection on conflict
- Skip validation when --allow-existing-branch is set (intentional reuse)
- Applied symmetrically to both Bash and PowerShell scripts

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: fsilvaortiz

scripts/bash/create-new-feature.sh

@@ -251,6 +251,7 @@ if [ "$USE_TIMESTAMP" = true ]; then
 else
     # Determine branch number
     if [ -z "$BRANCH_NUMBER" ]; then
+        # No manual number provided -- auto-detect
         if [ "$HAS_GIT" = true ]; then
             # Check existing branches on remotes
             BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR")
@@ -259,6 +260,49 @@ else
             HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
             BRANCH_NUMBER=$((HIGHEST + 1))
         fi
+    elif [ "$ALLOW_EXISTING" = false ]; then
+        # Manual number provided -- validate it is not already in use
+        # (skip when --allow-existing-branch, as the caller intentionally targets an existing branch)
+        MANUAL_NUM=$((10#$BRANCH_NUMBER))
+        MANUAL_NUM_PADDED=$(printf "%03d" "$MANUAL_NUM")
+        NUMBER_IN_USE=false
+
+        # Check specs directory for collision
+        if [ -d "$SPECS_DIR" ]; then
+            for dir in "$SPECS_DIR"/*/; do
+                [ -d "$dir" ] || continue
+                dirname=$(basename "$dir")
+                if echo "$dirname" | grep -q "^${MANUAL_NUM_PADDED}-"; then
+                    NUMBER_IN_USE=true
+                    break
+                fi
+            done
+        fi
+
+        # Check git branches for collision (fetch first to catch remote-only branches)
+        if [ "$NUMBER_IN_USE" = false ] && [ "$HAS_GIT" = true ]; then
+            git fetch --all --prune 2>/dev/null || true
+            branches=$(git branch -a 2>/dev/null || echo "")
+            if [ -n "$branches" ]; then
+                while IFS= read -r branch; do
+                    clean_branch=$(echo "$branch" | sed 's/^[* ]*//; s|^remotes/[^/]*/||')
+                    if echo "$clean_branch" | grep -q "^${MANUAL_NUM_PADDED}-"; then
+                        NUMBER_IN_USE=true
+                        break
+                    fi
+                done <<< "$branches"
+            fi
+        fi
+
+        if [ "$NUMBER_IN_USE" = true ]; then
+            >&2 echo "Warning: --number $BRANCH_NUMBER conflicts with existing branch/spec (${MANUAL_NUM_PADDED}-*). Auto-detecting next available number."
+            if [ "$HAS_GIT" = true ]; then
+                BRANCH_NUMBER=$(check_existing_branches "$SPECS_DIR")
+            else
+                HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
+                BRANCH_NUMBER=$((HIGHEST + 1))
+            fi
+        fi
     fi
 
     # Force base-10 interpretation to prevent octal conversion (e.g., 010 → 8 in octal, but should be 10 in decimal)

scripts/powershell/create-new-feature.ps1

@@ -203,13 +203,57 @@ if ($Timestamp) {
 } else {
     # Determine branch number
     if ($Number -eq 0) {
+        # No manual number provided -- auto-detect
         if ($hasGit) {
             # Check existing branches on remotes
             $Number = Get-NextBranchNumber -SpecsDir $specsDir
         } else {
             # Fall back to local directory check
             $Number = (Get-HighestNumberFromSpecs -SpecsDir $specsDir) + 1
         }
+    } elseif (-not $AllowExistingBranch) {
+        # Manual number provided -- validate it is not already in use
+        # (skip when -AllowExistingBranch, as the caller intentionally targets an existing branch)
+        $manualNumPadded = '{0:000}' -f $Number
+        $numberInUse = $false
+
+        # Check specs directory for collision
+        if (Test-Path $specsDir) {
+            foreach ($dir in (Get-ChildItem -Path $specsDir -Directory)) {
+                if ($dir.Name -match "^$manualNumPadded-") {
+                    $numberInUse = $true
+                    break
+                }
+            }
+        }
+
+        # Check git branches for collision (fetch first to catch remote-only branches)
+        if (-not $numberInUse -and $hasGit) {
+            try {
+                git fetch --all --prune 2>$null | Out-Null
+                $branches = git branch -a 2>$null
+                if ($LASTEXITCODE -eq 0 -and $branches) {
+                    foreach ($branch in $branches) {
+                        $cleanBranch = $branch.Trim() -replace '^\*?\s*', '' -replace '^remotes/[^/]+/', ''
+                        if ($cleanBranch -match "^$manualNumPadded-") {
+                            $numberInUse = $true
+                            break
+                        }
+                    }
+                }
+            } catch {
+                Write-Verbose "Could not check Git branches: $_"
+            }
+        }
+
+        if ($numberInUse) {
+            Write-Warning "-Number $Number conflicts with existing branch/spec ($manualNumPadded-*). Auto-detecting next available number."
+            if ($hasGit) {
+                $Number = Get-NextBranchNumber -SpecsDir $specsDir
+            } else {
+                $Number = (Get-HighestNumberFromSpecs -SpecsDir $specsDir) + 1
+            }
+        }
     }
 
     $featureNum = ('{0:000}' -f $Number)

tests/test_timestamp_branches.py

@@ -326,8 +326,8 @@ def test_allow_existing_creates_spec_dir(self, git_repo: Path):
         assert (git_repo / "specs" / "006-spec-dir").is_dir()
         assert (git_repo / "specs" / "006-spec-dir" / "spec.md").exists()
 
-    def test_without_flag_still_errors(self, git_repo: Path):
-        """T009: Verify backwards compatibility (error without flag)."""
+    def test_without_flag_auto_detects_on_collision(self, git_repo: Path):
+        """T009: Without --allow-existing-branch, a conflicting --number auto-detects next available."""
         subprocess.run(
             ["git", "checkout", "-b", "007-no-flag"],
             cwd=git_repo, check=True, capture_output=True,
@@ -339,8 +339,9 @@ def test_without_flag_still_errors(self, git_repo: Path):
         result = run_script(
             git_repo, "--short-name", "no-flag", "--number", "7", "No flag feature",
         )
-        assert result.returncode != 0, "should fail without --allow-existing-branch"
-        assert "already exists" in result.stderr
+        assert result.returncode == 0, result.stderr
+        assert "conflicts with existing branch/spec" in result.stderr
+        assert "008-no-flag" in result.stdout
 
     def test_allow_existing_no_overwrite_spec(self, git_repo: Path):
         """T010: Pre-create spec.md with content, verify it is preserved."""