fix: address PR review feedback

Five issues addressed per review from @mnriem and @Copilot:

1. Scope guardrail to explicit --number/-Number only
   Previously the guardrail fired unconditionally. It now only activates
   when the caller explicitly passed --number (Bash) or -Number (PS).
   Auto-detected numbers are not affected, preserving the existing contract.

2. Reuse check_existing_branches / Get-NextBranchNumber in guardrail
   Previously the guardrail re-implemented get_highest_from_* without a
   git fetch, meaning the corrected number could still collide with an
   unfetched remote branch. Both scripts now delegate to the existing
   functions that already fetch remotes before computing the max.

3. Extend collision check to git branches (not just spec dirs)
   The guardrail trigger now checks both specs/NNN-* directories and
   existing local/remote git branches before deciding to auto-correct,
   providing a consistent experience.

4. Update help text
   --number / -Number help text updated from "overrides auto-detection"
   to "Preferred branch number (auto-corrected if prefix already exists
   in specs or branches)" to accurately reflect the new behavior.

5. Port guardrail to PowerShell (create-new-feature.ps1)
   Mirrors all Bash changes for cross-platform parity.

Author: daniel-graham

scripts/bash/create-new-feature.sh

@@ -5,6 +5,7 @@ set -e
 JSON_MODE=false
 SHORT_NAME=""
 BRANCH_NUMBER=""
+NUMBER_EXPLICIT=false   # true only when --number was explicitly passed by the caller
 ARGS=()
 i=1
 while [ $i -le $# ]; do
@@ -39,14 +40,15 @@ while [ $i -le $# ]; do
                 exit 1
             fi
             BRANCH_NUMBER="$next_arg"
+            NUMBER_EXPLICIT=true
             ;;
         --help|-h) 
             echo "Usage: $0 [--json] [--short-name <name>] [--number N] <feature_description>"
             echo ""
             echo "Options:"
             echo "  --json              Output in JSON format"
             echo "  --short-name <name> Provide a custom short name (2-4 words) for the branch"
-            echo "  --number N          Specify branch number manually (overrides auto-detection)"
+            echo "  --number N          Preferred branch number (auto-corrected if prefix already exists in specs or branches)"
             echo "  --help, -h          Show this help message"
             echo ""
             echo "Examples:"
@@ -256,27 +258,37 @@ fi
 # Force base-10 interpretation to prevent octal conversion (e.g., 010 → 8 in octal, but should be 10 in decimal)
 FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
 
-# ── Guardrail: auto-correct if the chosen prefix already exists ──────────────
-# If a specs directory with this numeric prefix already exists, the requested
-# number is stale or wrong (e.g., an agent passed --number with a conflicting
-# value). Auto-correct to the global max + 1 so the workflow never fails due
-# to numbering collisions.
-if compgen -G "$SPECS_DIR/${FEATURE_NUM}-*" > /dev/null 2>&1; then
-    REQUESTED_NUM="$FEATURE_NUM"
-    # Recalculate from the true global max across specs + branches
-    if [ "$HAS_GIT" = true ]; then
-        GLOBAL_MAX_BRANCH=$(get_highest_from_branches)
-    else
-        GLOBAL_MAX_BRANCH=0
+# ── Guardrail: auto-correct if --number was explicitly passed and the prefix
+# already exists in specs/ or as a git branch. Only fires on explicit --number
+# to preserve the existing auto-detection contract.
+# Reuses check_existing_branches, which fetches remotes and checks both
+# specs directories and all local/remote branches.
+if [ "$NUMBER_EXPLICIT" = true ]; then
+    # Check for conflict in spec directories
+    SPEC_CONFLICT=false
+    if compgen -G "$SPECS_DIR/${FEATURE_NUM}-*" > /dev/null 2>&1; then
+        SPEC_CONFLICT=true
+    fi
+
+    # Check for conflict in git branches (local and remote)
+    BRANCH_CONFLICT=false
+    if [ "$HAS_GIT" = true ] && git branch -a 2>/dev/null | grep -qE "(^|[[:space:]])(remotes/[^/]+/)?${FEATURE_NUM}-"; then
+        BRANCH_CONFLICT=true
     fi
-    GLOBAL_MAX_SPEC=$(get_highest_from_specs "$SPECS_DIR")
-    GLOBAL_MAX=$GLOBAL_MAX_BRANCH
-    if [ "$GLOBAL_MAX_SPEC" -gt "$GLOBAL_MAX" ]; then
-        GLOBAL_MAX=$GLOBAL_MAX_SPEC
+
+    if [ "$SPEC_CONFLICT" = true ] || [ "$BRANCH_CONFLICT" = true ]; then
+        REQUESTED_NUM="$FEATURE_NUM"
+        # Delegate to check_existing_branches, which fetches and computes
+        # max(all specs, all branches) + 1 — same logic used by auto-detection.
+        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
+        FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
+        >&2 echo "⚠️  [specify] --number $REQUESTED_NUM conflicts with an existing spec dir or branch. Auto-corrected to $FEATURE_NUM."
     fi
-    BRANCH_NUMBER=$((GLOBAL_MAX + 1))
-    FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
-    >&2 echo "⚠️  Requested number $REQUESTED_NUM conflicts with existing spec directory. Auto-corrected to $FEATURE_NUM."
 fi
 
 BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"

scripts/powershell/create-new-feature.ps1

@@ -18,7 +18,7 @@ if ($Help) {
     Write-Host "Options:"
     Write-Host "  -Json               Output in JSON format"
     Write-Host "  -ShortName <name>   Provide a custom short name (2-4 words) for the branch"
-    Write-Host "  -Number N           Specify branch number manually (overrides auto-detection)"
+    Write-Host "  -Number N           Preferred branch number (auto-corrected if prefix already exists in specs or branches)"
     Write-Host "  -Help               Show this help message"
     Write-Host ""
     Write-Host "Examples:"
@@ -213,6 +213,9 @@ if ($ShortName) {
 }
 
 # Determine branch number
+# Track whether the caller explicitly passed -Number so the guardrail below
+# only fires for explicit overrides, not for auto-detected numbers.
+$numberExplicit = ($Number -ne 0)
 if ($Number -eq 0) {
     if ($hasGit) {
         # Check existing branches on remotes
@@ -224,6 +227,41 @@ if ($Number -eq 0) {
 }
 
 $featureNum = ('{0:000}' -f $Number)
+
+# ── Guardrail: auto-correct if -Number was explicitly passed and the prefix
+# already exists in specs/ or as a git branch. Only fires on explicit -Number
+# to preserve the existing auto-detection contract.
+# Reuses Get-NextBranchNumber, which fetches remotes and checks both
+# specs directories and all local/remote branches.
+if ($numberExplicit) {
+    $requestedNum = $featureNum
+
+    # Check for conflict in spec directories
+    $specConflict = (Get-ChildItem -Path $specsDir -Directory -ErrorAction SilentlyContinue |`
+        Where-Object { $_.Name -match "^$featureNum-" }).Count -gt 0
+
+    # Check for conflict in git branches (local and remote)
+    $branchConflict = $false
+    if ($hasGit) {
+        $allBranches = git branch -a 2>$null
+        if ($LASTEXITCODE -eq 0) {
+            $branchConflict = ($allBranches | Where-Object { $_ -match "(^|\s)(remotes/[^/]+/)?$featureNum-" }).Count -gt 0
+        }
+    }
+
+    if ($specConflict -or $branchConflict) {
+        # Delegate to Get-NextBranchNumber, which fetches and computes
+        # max(all specs, all branches) + 1 — same logic used by auto-detection.
+        if ($hasGit) {
+            $Number = Get-NextBranchNumber -SpecsDir $specsDir
+        } else {
+            $Number = (Get-HighestNumberFromSpecs -SpecsDir $specsDir) + 1
+        }
+        $featureNum = ('{0:000}' -f $Number)
+        Write-Warning "[specify] -Number $requestedNum conflicts with an existing spec dir or branch. Auto-corrected to $featureNum."
+    }
+}
+
 $branchName = "$featureNum-$branchSuffix"
 
 # GitHub enforces a 244-byte limit on branch names