fix: auto-correct conflicting feature prefixes

daniel-graham · daniel-graham · commit 05bf2bff971e · 2026-07-22T18:38:45.000-04:00
Treat an explicit feature number as a preference when an existing spec directory already uses that prefix. Advance to the next available spec prefix and warn without fetching or scanning git branches.

Keep Bash, PowerShell, and Python variants aligned. Preserve 64-bit numbering, timestamp mode, dry-run output, matching-file behavior, and exact-directory reuse through the allow-existing option.

Assisted-by: Codex (model: GPT-5, autonomous)
diff --git a/scripts/bash/create-new-feature.sh b/scripts/bash/create-new-feature.sh
@@ -8,6 +8,7 @@ ALLOW_EXISTING=false
 SHORT_NAME=""
 BRANCH_NUMBER=""
 USE_TIMESTAMP=false
+NUMBER_EXPLICIT=false
 ARGS=()
 i=1
 while [ $i -le $# ]; do
@@ -48,6 +49,7 @@ while [ $i -le $# ]; do
                 exit 1
             fi
             BRANCH_NUMBER="$next_arg"
+            NUMBER_EXPLICIT=true
             ;;
         --timestamp)
             USE_TIMESTAMP=true
@@ -60,7 +62,7 @@ while [ $i -le $# ]; do
             echo "  --dry-run           Compute feature name and paths without creating directories or files"
             echo "  --allow-existing-branch  Reuse an existing feature directory if it already exists"
             echo "  --short-name <name> Provide a custom short name (2-4 words) for the feature"
-            echo "  --number N          Specify branch number manually (overrides auto-detection)"
+            echo "  --number N          Prefer a feature number (auto-corrected if its specs prefix exists)"
             echo "  --timestamp         Use timestamp prefix (YYYYMMDD-HHMMSS) instead of sequential numbering"
             echo "  --help, -h          Show this help message"
             echo ""
@@ -253,6 +255,35 @@ else
 
     # 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))")
+
+    # Treat an explicit number as a preference when its prefix is already used
+    # by a feature directory. Auto-detected numbers are already conflict-free.
+    if [ "$NUMBER_EXPLICIT" = true ]; then
+        SPEC_CONFLICT=false
+        REQUESTED_DIR="$SPECS_DIR/${FEATURE_NUM}-${BRANCH_SUFFIX}"
+        for spec_path in "$SPECS_DIR/${FEATURE_NUM}-"*; do
+            if [ -d "$spec_path" ]; then
+                if [ "$ALLOW_EXISTING" = true ] && [ "$spec_path" = "$REQUESTED_DIR" ]; then
+                    continue
+                fi
+                SPEC_CONFLICT=true
+                break
+            fi
+        done
+
+        if [ "$SPEC_CONFLICT" = true ]; then
+            REQUESTED_NUM="$FEATURE_NUM"
+            HIGHEST=$(get_highest_from_specs "$SPECS_DIR")
+            if [ "$HIGHEST" -eq "$MAX_FEATURE_NUMBER" ]; then
+                echo "Error: feature number must be between 0 and $MAX_FEATURE_NUMBER, got '9223372036854775808'" >&2
+                exit 1
+            fi
+            BRANCH_NUMBER=$((HIGHEST + 1))
+            FEATURE_NUM=$(printf "%03d" "$((10#$BRANCH_NUMBER))")
+            >&2 echo "[specify] Warning: --number $REQUESTED_NUM conflicts with an existing spec directory; using $FEATURE_NUM instead"
+        fi
+    fi
+
     BRANCH_NAME="${FEATURE_NUM}-${BRANCH_SUFFIX}"
 fi
 
diff --git a/scripts/powershell/create-new-feature.ps1 b/scripts/powershell/create-new-feature.ps1
@@ -24,7 +24,7 @@ if ($Help) {
     Write-Host "  -DryRun             Compute feature name and paths without creating directories or files"
     Write-Host "  -AllowExistingBranch  Reuse an existing feature directory if it already exists"
     Write-Host "  -ShortName <name>   Provide a custom short name (2-4 words) for the feature"
-    Write-Host "  -Number N           Specify branch number manually (overrides auto-detection)"
+    Write-Host "  -Number N           Prefer a feature number (auto-corrected if its specs prefix exists)"
     Write-Host "  -Timestamp          Use timestamp prefix (YYYYMMDD-HHMMSS) instead of sequential numbering"
     Write-Host "  -Help               Show this help message"
     Write-Host ""
@@ -176,6 +176,32 @@ if ($Timestamp) {
     }
 
     $featureNum = ('{0:000}' -f $resolvedNumber)
+
+    # Treat an explicit number as a preference when its prefix is already used
+    # by a feature directory. Auto-detected numbers are already conflict-free.
+    $specConflict = $false
+    if ($hasNumber -and (Test-Path -LiteralPath $specsDir -PathType Container)) {
+        $requestedDir = Join-Path $specsDir "$featureNum-$branchSuffix"
+        $specConflict = $null -ne (Get-ChildItem -LiteralPath $specsDir -Directory -ErrorAction SilentlyContinue |
+            Where-Object {
+                $_.Name -like "$featureNum-*" -and
+                (-not $AllowExistingBranch -or $_.FullName -ne $requestedDir)
+            } |
+            Select-Object -First 1)
+    }
+
+    if ($specConflict) {
+        $requestedNum = $featureNum
+        $highestNumber = Get-HighestNumberFromSpecs -SpecsDir $specsDir
+        if ($highestNumber -eq [long]::MaxValue) {
+            Write-Error "Error: feature number must be between 0 and $([long]::MaxValue), got '9223372036854775808'"
+            exit 1
+        }
+        $resolvedNumber = $highestNumber + 1
+        $featureNum = ('{0:000}' -f $resolvedNumber)
+        [Console]::Error.WriteLine("[specify] Warning: -Number $requestedNum conflicts with an existing spec directory; using $featureNum instead")
+    }
+
     $branchName = "$featureNum-$branchSuffix"
 }
 
diff --git a/scripts/python/create_new_feature.py b/scripts/python/create_new_feature.py
@@ -76,7 +76,7 @@ def _help_text(argv0: str) -> str:
   --dry-run           Compute feature name and paths without creating directories or files
   --allow-existing-branch  Reuse an existing feature directory if it already exists
   --short-name <name> Provide a custom short name (2-4 words) for the feature
-  --number N          Specify branch number manually (overrides auto-detection)
+  --number N          Prefer a feature number (auto-corrected if its specs prefix exists)
   --timestamp         Use timestamp prefix (YYYYMMDD-HHMMSS) instead of sequential numbering
   --help, -h          Show this help message
 
@@ -261,6 +261,33 @@ def main(argv: list[str] | None = None) -> int:
             return 1
         feature_num = f"{number:03d}"
 
+        # Treat an explicit number as a preference when its prefix is already used
+        # by a feature directory. Auto-detected numbers are already conflict-free.
+        if branch_number and specs_dir.is_dir():
+            requested_dir = specs_dir / f"{feature_num}-{branch_suffix}"
+            spec_conflict = any(
+                entry.is_dir()
+                and entry.name.startswith(f"{feature_num}-")
+                and not (args.allow_existing and entry == requested_dir)
+                for entry in specs_dir.iterdir()
+            )
+            if spec_conflict:
+                requested_num = feature_num
+                number = _get_highest_from_specs(specs_dir) + 1
+                if number > _MAX_FEATURE_NUMBER:
+                    print(
+                        f"Error: feature number must be between 0 and "
+                        f"{_MAX_FEATURE_NUMBER}, got '{number}'",
+                        file=sys.stderr,
+                    )
+                    return 1
+                feature_num = f"{number:03d}"
+                print(
+                    f"[specify] Warning: --number {requested_num} conflicts with "
+                    f"an existing spec directory; using {feature_num} instead",
+                    file=sys.stderr,
+                )
+
     max_suffix_length = _MAX_BRANCH_LENGTH - (len(feature_num) + 1)
     if max_suffix_length <= 0:
         print("Error: feature number is too long for a branch name", file=sys.stderr)
diff --git a/tests/test_create_new_feature_python_parity.py b/tests/test_create_new_feature_python_parity.py
@@ -355,7 +355,7 @@ def test_python_missing_template_warning_matches_bash(
 
 
 @requires_bash
-def test_python_existing_directory_error_matches_bash(
+def test_python_existing_prefix_auto_correct_matches_bash(
     repo_pair: tuple[Path, Path],
 ) -> None:
     repo_a, repo_b = repo_pair
@@ -377,8 +377,8 @@ def test_python_existing_directory_error_matches_bash(
     bash = run(bash_cmd(repo_a, SCRIPT, "--json", "--number", "1", description), repo_a)
     py = run(py_cmd(repo_b, SCRIPT, "--json", "--number", "1", description), repo_b)
 
-    assert py.returncode == bash.returncode == 1
-    assert py.stdout == bash.stdout == ""
+    assert py.returncode == bash.returncode == 0
+    assert json_stdout(py)["FEATURE_NUM"] == json_stdout(bash)["FEATURE_NUM"] == "002"
     assert normalize_repo_paths(py.stderr, repo_b) == normalize_repo_paths(
         bash.stderr, repo_a
     )
@@ -819,19 +819,24 @@ def test_all_variants_allow_existing_branch(repo: Path) -> None:
 
 @requires_bash
 @pytest.mark.skipif(not HAS_POWERSHELL, reason="no PowerShell available")
-def test_all_variants_existing_directory_failure_diagnostics(repo: Path) -> None:
+def test_all_variants_existing_prefix_auto_correct_diagnostics(repo: Path) -> None:
     (repo / "specs" / "001-x").mkdir(parents=True)
-    expected = (
-        "Error: Feature directory '<REPO>/specs/001-x' already exists. "
-        "Please use a different feature name or specify a different number "
-        "with --number."
-    )
+    expected = "conflicts with an existing spec directory; using 002 instead"
 
-    bash = run(bash_cmd(repo, SCRIPT, "--json", "--number", "1", "x"), repo)
-    ps = run(ps_cmd(repo, SCRIPT, "-Json", "-Number", "1", "x"), repo)
-    py = run(py_cmd(repo, SCRIPT, "--json", "--number", "1", "x"), repo)
+    bash = run(
+        bash_cmd(repo, SCRIPT, "--json", "--dry-run", "--number", "1", "x"),
+        repo,
+    )
+    ps = run(
+        ps_cmd(repo, SCRIPT, "-Json", "-DryRun", "-Number", "1", "x"),
+        repo,
+    )
+    py = run(
+        py_cmd(repo, SCRIPT, "--json", "--dry-run", "--number", "1", "x"),
+        repo,
+    )
 
-    assert bash.returncode == ps.returncode == py.returncode == 1
-    assert bash.stdout == ps.stdout == py.stdout == ""
+    assert bash.returncode == ps.returncode == py.returncode == 0
+    assert json_stdout(bash) == json_stdout(ps) == json_stdout(py)
     for result in (bash, ps, py):
         assert expected in _normalized_error_text(result.stderr, repo)
diff --git a/tests/test_timestamp_branches.py b/tests/test_timestamp_branches.py
@@ -288,6 +288,50 @@ def test_explicit_number_zero_is_honored(self, git_repo: Path):
         assert data["FEATURE_NUM"] == "000"
         assert data["BRANCH_NAME"] == "000-zero"
 
+    def test_explicit_conflicting_number_uses_next_spec_prefix(self, git_repo: Path):
+        """An explicit number is advanced when its spec prefix already exists."""
+        (git_repo / "specs" / "001-existing").mkdir(parents=True)
+        (git_repo / "specs" / "1000-latest").mkdir()
+
+        result = run_script(
+            git_repo,
+            "--json",
+            "--dry-run",
+            "--number",
+            "1",
+            "--short-name",
+            "test",
+            "Test feature",
+        )
+
+        assert result.returncode == 0, result.stderr
+        data = json.loads(result.stdout)
+        assert data["FEATURE_NUM"] == "1001"
+        assert data["BRANCH_NAME"] == "1001-test"
+        assert "--number 001 conflicts with an existing spec directory" in result.stderr
+        assert "using 1001 instead" in result.stderr
+
+    def test_explicit_number_ignores_matching_file(self, git_repo: Path):
+        """A matching file does not count as a conflicting spec directory."""
+        specs_dir = git_repo / "specs"
+        specs_dir.mkdir()
+        (specs_dir / "001-placeholder").write_text("not a directory", encoding="utf-8")
+
+        result = run_script(
+            git_repo,
+            "--json",
+            "--dry-run",
+            "--number",
+            "1",
+            "--short-name",
+            "test",
+            "Test feature",
+        )
+
+        assert result.returncode == 0, result.stderr
+        assert json.loads(result.stdout)["FEATURE_NUM"] == "001"
+        assert "conflicts with an existing spec directory" not in result.stderr
+
 
 class TestSequentialBranchPowerShell:
     def test_powershell_scanner_uses_long_tryparse_for_large_prefixes(self):
@@ -332,6 +376,50 @@ def test_explicit_number_zero_is_honored_matching_bash(self, ps_git_repo: Path):
         assert data["FEATURE_NUM"] == "000"
         assert data["BRANCH_NAME"] == "000-zero"
 
+    @pytest.mark.skipif(not _has_pwsh(), reason="pwsh not installed")
+    def test_explicit_conflicting_number_uses_next_spec_prefix(
+        self, ps_git_repo: Path
+    ):
+        """PowerShell advances an explicit number when its spec prefix exists."""
+        script = ps_git_repo / "scripts" / "powershell" / "create-new-feature.ps1"
+        (ps_git_repo / "specs" / "001-existing").mkdir(parents=True)
+        (ps_git_repo / "specs" / "1000-latest").mkdir()
+
+        result = subprocess.run(
+            [
+                "pwsh", "-NoProfile", "-File", str(script), "-Json", "-DryRun",
+                "-Number", "1", "-ShortName", "test", "Test feature",
+            ],
+            cwd=ps_git_repo, capture_output=True, text=True,
+        )
+
+        assert result.returncode == 0, result.stderr
+        data = json.loads(result.stdout)
+        assert data["FEATURE_NUM"] == "1001"
+        assert data["BRANCH_NAME"] == "1001-test"
+        assert "-Number 001 conflicts with an existing spec directory" in result.stderr
+        assert "using 1001 instead" in result.stderr
+
+    @pytest.mark.skipif(not _has_pwsh(), reason="pwsh not installed")
+    def test_explicit_number_ignores_matching_file(self, ps_git_repo: Path):
+        """PowerShell ignores files that resemble numbered spec directories."""
+        script = ps_git_repo / "scripts" / "powershell" / "create-new-feature.ps1"
+        specs_dir = ps_git_repo / "specs"
+        specs_dir.mkdir()
+        (specs_dir / "001-placeholder").write_text("not a directory", encoding="utf-8")
+
+        result = subprocess.run(
+            [
+                "pwsh", "-NoProfile", "-File", str(script), "-Json", "-DryRun",
+                "-Number", "1", "-ShortName", "test", "Test feature",
+            ],
+            cwd=ps_git_repo, capture_output=True, text=True,
+        )
+
+        assert result.returncode == 0, result.stderr
+        assert json.loads(result.stdout)["FEATURE_NUM"] == "001"
+        assert "conflicts with an existing spec directory" not in result.stderr
+
     @pytest.mark.skipif(not _has_pwsh(), reason="pwsh not installed")
     def test_missing_spec_template_warns_matching_bash(self, ps_git_repo: Path):
         """When no spec template can be resolved, create-new-feature.ps1 must warn on
@@ -531,14 +619,15 @@ def test_allow_existing_reuses_existing_feature_dir(self, git_repo: Path):
         assert feature_dir.is_dir()
         assert (feature_dir / "spec.md").exists()
 
-    def test_without_flag_still_errors(self, git_repo: Path):
-        """T009: Existing feature directories still fail without the flag."""
+    def test_without_flag_auto_corrects_existing_prefix(self, git_repo: Path):
+        """T009: Existing prefix advances when exact reuse is not allowed."""
         (git_repo / "specs" / "007-no-flag").mkdir(parents=True)
         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 (git_repo / "specs" / "008-no-flag").is_dir()
+        assert "using 008 instead" in result.stderr
 
     def test_allow_existing_no_overwrite_spec(self, git_repo: Path):
         """T010: Pre-create spec.md with content, verify it is preserved."""
@@ -598,6 +687,26 @@ def test_powershell_reuses_existing_feature_dir(self):
         assert "Feature directory '$featureDir' already exists" in contents
         assert "-not $AllowExistingBranch" in contents
 
+    @pytest.mark.skipif(not _has_pwsh(), reason="pwsh not installed")
+    def test_powershell_reuses_exact_feature_dir(self, ps_git_repo: Path):
+        """PowerShell exact-directory reuse bypasses prefix auto-correction."""
+        script = ps_git_repo / "scripts" / "powershell" / "create-new-feature.ps1"
+        feature_dir = ps_git_repo / "specs" / "004-pre-exist"
+        feature_dir.mkdir(parents=True)
+
+        result = subprocess.run(
+            [
+                "pwsh", "-NoProfile", "-File", str(script), "-Json",
+                "-AllowExistingBranch", "-Number", "4", "-ShortName",
+                "pre-exist", "Pre-existing feature",
+            ],
+            cwd=ps_git_repo, capture_output=True, text=True,
+        )
+
+        assert result.returncode == 0, result.stderr
+        assert json.loads(result.stdout)["BRANCH_NAME"] == "004-pre-exist"
+        assert (feature_dir / "spec.md").is_file()
+
     @pytest.mark.skipif(not _has_pwsh(), reason="pwsh not installed")
     @pytest.mark.skipif(
         os.name != "nt" or shutil.which("powershell.exe") is None,
