Address review: fix comments, add nested_repo_scan_depth, test gitignored parents

- Update function header comments in common.sh and common.ps1 to
  accurately describe gitignore-based filtering (no hardcoded skip list)
- Document that scanning will NOT descend into gitignored parent
  directories; use init-options.json nested_repos for those
- Implement nested_repo_scan_depth from init-options.json in both
  setup-plan.sh and setup-plan.ps1 (priority: CLI > config > default 2)
- Fix PowerShell -ScanDepth param: default 2, ValidateRange(1, MaxValue),
  use PSBoundParameters to detect explicit CLI usage
- Add returncode assertion before branch-name comparison in tests
- Add test: repo under gitignored parent not discovered by scan
- Add test: nested_repo_scan_depth from init-options.json

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: sakitA

scripts/bash/common.sh

@@ -287,6 +287,17 @@ check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo "  ✓ $2" |
 #   max_depth       — defaults to 2
 #   explicit_paths  — if provided (3rd arg onward), validate and return these directly (no scanning)
 # Outputs one absolute path per line.
+#
+# Discovery modes:
+#   Explicit — validates paths from init-options.json `nested_repos`; no scanning.
+#   Scan     — recursively searches child directories up to max_depth.
+#              Skips .git directories. Uses `git check-ignore` to prune
+#              gitignored directories during traversal. A directory with
+#              its own .git marker is always reported (even if gitignored).
+#
+# Note: Scanning will NOT descend into gitignored parent directories, so a
+# nested repo beneath one (e.g., vendor/foo/.git when vendor/ is ignored)
+# will not be discovered. Use init-options.json `nested_repos` for those.
 find_nested_git_repos() {
     local repo_root="${1:-$(get_repo_root)}"
     local max_depth="${2:-2}"
@@ -334,7 +345,8 @@ find_nested_git_repos() {
                         echo "$child"
                     fi
                 elif [ "$current_depth" -lt "$max_depth" ]; then
-                    # Skip gitignored directories (they won't contain nested repos)
+                    # Skip gitignored directories — won't descend into them.
+                    # Repos under gitignored parents require explicit init-options config.
                     if git -C "$repo_root" check-ignore -q "$child" 2>/dev/null; then
                         continue
                     fi

scripts/bash/setup-plan.sh

@@ -75,16 +75,18 @@ fi
 # Discover nested independent git repositories (for AI agent to analyze)
 NESTED_REPOS_JSON="[]"
 if [ "$HAS_GIT" = true ]; then
-    scan_depth="${SCAN_DEPTH:-2}"
     INIT_OPTIONS="$REPO_ROOT/.specify/init-options.json"
     explicit_repos=()
+    config_depth=""
 
-    # Read explicit nested_repos from init-options.json if available
+    # Read explicit nested_repos and nested_repo_scan_depth from init-options.json if available
     if [ -f "$INIT_OPTIONS" ]; then
         if has_jq; then
             while IFS= read -r rp; do
                 [ -n "$rp" ] && explicit_repos+=("$rp")
             done < <(jq -r '.nested_repos // [] | .[]' "$INIT_OPTIONS" 2>/dev/null)
+            _cd=$(jq -r '.nested_repo_scan_depth // empty' "$INIT_OPTIONS" 2>/dev/null)
+            [ -n "$_cd" ] && config_depth="$_cd"
         else
             _py=$(command -v python3 2>/dev/null || command -v python 2>/dev/null || echo "")
             if [ -n "$_py" ]; then
@@ -95,10 +97,20 @@ if [ "$HAS_GIT" = true ]; then
 try:
  [print(p) for p in json.load(open(sys.argv[1])).get('nested_repos',[])]
 except: pass" "$INIT_OPTIONS" 2>/dev/null)
+                _cd=$("$_py" -c "import json,sys
+try:
+ v=json.load(open(sys.argv[1])).get('nested_repo_scan_depth')
+ if v is not None: print(v)
+except: pass" "$INIT_OPTIONS" 2>/dev/null)
+                _cd="${_cd%$'\r'}"
+                [ -n "$_cd" ] && config_depth="$_cd"
             fi
         fi
     fi
 
+    # Priority: CLI --scan-depth > init-options nested_repo_scan_depth > default 2
+    scan_depth="${SCAN_DEPTH:-${config_depth:-2}}"
+
     if [ ${#explicit_repos[@]} -gt 0 ]; then
         nested_repos=$(find_nested_git_repos "$REPO_ROOT" "$scan_depth" "${explicit_repos[@]}")
     else

scripts/powershell/common.ps1

@@ -229,11 +229,19 @@ function Test-DirHasFiles {
 }
 
 # Discover nested independent git repositories under RepoRoot.
-# Searches up to 2 directory levels deep for subdirectories containing .git
-# (directory or file, covering worktrees/submodules). Excludes the root repo
-# itself and common non-project directories.
 # Returns an array of absolute paths. Scan depth is configurable (default 2).
 # If ExplicitPaths are provided, validates and returns those directly (no scanning).
+#
+# Discovery modes:
+#   Explicit — validates paths from init-options.json `nested_repos`; no scanning.
+#   Scan     — recursively searches child directories up to MaxDepth.
+#              Skips .git directories. Uses `git check-ignore` to prune
+#              gitignored directories during traversal. A directory with
+#              its own .git marker is always reported (even if gitignored).
+#
+# Note: Scanning will NOT descend into gitignored parent directories, so a
+# nested repo beneath one (e.g., vendor/foo/.git when vendor/ is ignored)
+# will not be discovered. Use init-options.json `nested_repos` for those.
 function Find-NestedGitRepos {
     param(
         [string]$RepoRoot = (Get-RepoRoot),
@@ -278,7 +286,8 @@ function Find-NestedGitRepos {
                     }
                 } catch { }
             } elseif ($CurrentDepth -lt $MaxDepth) {
-                # Skip gitignored directories (they won't contain nested repos)
+                # Skip gitignored directories — won't descend into them.
+                # Repos under gitignored parents require explicit init-options config.
                 $null = git -C $RepoRoot check-ignore -q $child.FullName 2>$null
                 if ($LASTEXITCODE -eq 0) { continue }
                 $found += ScanDir -Dir $child.FullName -CurrentDepth ($CurrentDepth + 1)

scripts/powershell/setup-plan.ps1

@@ -4,8 +4,8 @@
 [CmdletBinding()]
 param(
     [switch]$Json,
-    [ValidateRange(0, [int]::MaxValue)]
-    [int]$ScanDepth = 0,
+    [ValidateRange(1, [int]::MaxValue)]
+    [int]$ScanDepth,
     [switch]$Help
 )
 
@@ -48,20 +48,26 @@ if ($template -and (Test-Path $template)) {
 # Discover nested independent git repositories (for AI agent to analyze)
 $nestedReposResult = @()
 if ($paths.HAS_GIT -eq 'true' -or $paths.HAS_GIT -eq $true) {
-    $effectiveDepth = if ($ScanDepth -gt 0) { $ScanDepth } else { 2 }
     $initOptions = Join-Path $paths.REPO_ROOT '.specify' 'init-options.json'
     $explicitPaths = @()
+    $configDepth = $null
 
-    # Read explicit nested_repos from init-options.json if available
+    # Read explicit nested_repos and nested_repo_scan_depth from init-options.json if available
     if (Test-Path -LiteralPath $initOptions) {
         try {
             $opts = Get-Content $initOptions -Raw | ConvertFrom-Json
             if ($opts.nested_repos -and $opts.nested_repos.Count -gt 0) {
                 $explicitPaths = @($opts.nested_repos)
             }
+            if ($null -ne $opts.nested_repo_scan_depth) {
+                $configDepth = [int]$opts.nested_repo_scan_depth
+            }
         } catch { }
     }
 
+    # Priority: CLI -ScanDepth > init-options nested_repo_scan_depth > default 2
+    $effectiveDepth = if ($PSBoundParameters.ContainsKey('ScanDepth')) { $ScanDepth } elseif ($configDepth) { $configDepth } else { 2 }
+
     if ($explicitPaths.Count -gt 0) {
         $nestedRepos = Find-NestedGitRepos -RepoRoot $paths.REPO_ROOT -MaxDepth $effectiveDepth -ExplicitPaths $explicitPaths
     } else {

tests/test_nested_repos.py

@@ -221,6 +221,48 @@ def test_nested_repo_found_even_if_gitignored(self, tmp_path: Path):
         assert len(paths) == 1
         assert os.path.basename(paths[0]) == "nested-lib"
 
+    def test_repo_under_gitignored_parent_not_discovered_by_scan(self, tmp_path: Path):
+        """A nested repo beneath a gitignored parent dir is NOT found by scanning.
+
+        When vendor/ is gitignored and vendor/foo/.git exists, the scan will not
+        descend into vendor/ so vendor/foo won't be discovered. Users should use
+        init-options.json `nested_repos` for this case.
+        """
+        _init_git_repo(tmp_path)
+        (tmp_path / ".specify").mkdir()
+        scripts_dir = tmp_path / "scripts" / "bash"
+        scripts_dir.mkdir(parents=True)
+        shutil.copy(COMMON_SH, scripts_dir / "common.sh")
+
+        # Gitignore vendor/
+        (tmp_path / ".gitignore").write_text("vendor/\n")
+        subprocess.run(["git", "add", ".gitignore"], cwd=tmp_path, check=True)
+        subprocess.run(["git", "commit", "-m", "ignore vendor", "-q"], cwd=tmp_path, check=True)
+
+        # Create nested repo under gitignored parent: vendor/foo
+        vendor_foo = tmp_path / "vendor" / "foo"
+        vendor_foo.mkdir(parents=True)
+        _init_git_repo(vendor_foo)
+
+        # Scan with depth 3 — should still not find it because vendor/ is pruned
+        result = source_and_call(
+            f'find_nested_git_repos "{tmp_path}" 3',
+            cwd=tmp_path,
+        )
+        assert result.returncode == 0
+        paths = [p.strip().rstrip("/") for p in result.stdout.strip().splitlines() if p.strip()]
+        assert len(paths) == 0
+
+        # But explicit paths mode WILL find it
+        result2 = source_and_call(
+            f'find_nested_git_repos "{tmp_path}" 3 "vendor/foo"',
+            cwd=tmp_path,
+        )
+        assert result2.returncode == 0
+        paths2 = [p.strip().rstrip("/") for p in result2.stdout.strip().splitlines() if p.strip()]
+        assert len(paths2) == 1
+        assert os.path.basename(paths2[0]) == "foo"
+
 
 # ── Explicit Paths Tests ─────────────────────────────────────────────────────
 
@@ -340,6 +382,7 @@ def test_nested_repos_not_branched(self, git_repo_with_nested: Path):
                 cwd=git_repo_with_nested / subdir,
                 capture_output=True, text=True,
             )
+            assert br.returncode == 0, br.stderr
             assert br.stdout.strip() != branch_name
 
 
@@ -437,3 +480,35 @@ def test_explicit_nested_repos_from_init_options(self, git_repo_with_nested: Pat
         assert "NESTED_REPOS" in data
         assert len(data["NESTED_REPOS"]) == 1
         assert data["NESTED_REPOS"][0]["path"] == "components/core"
+
+    def test_scan_depth_from_init_options(self, tmp_path: Path):
+        """setup-plan reads nested_repo_scan_depth from init-options.json as default."""
+        _init_git_repo(tmp_path)
+        _setup_scripts(tmp_path)
+
+        # Level 3 repo
+        deep_dir = tmp_path / "services" / "backend" / "auth"
+        deep_dir.mkdir(parents=True)
+        _init_git_repo(deep_dir)
+
+        # Create feature branch first
+        run_create_feature(
+            tmp_path, "--json", "--short-name", "cfg-depth", "Config depth test",
+        )
+
+        # Without config: default depth 2, should not find level-3 repo
+        result = run_setup_plan(tmp_path, "--json")
+        assert result.returncode == 0, result.stderr
+        data = parse_json_from_output(result.stdout)
+        assert data["NESTED_REPOS"] == []
+
+        # Add nested_repo_scan_depth=3 in init-options.json
+        init_options = tmp_path / ".specify" / "init-options.json"
+        init_options.write_text(json.dumps({"nested_repo_scan_depth": 3}))
+
+        # Now should discover the level-3 repo
+        result2 = run_setup_plan(tmp_path, "--json")
+        assert result2.returncode == 0, result2.stderr
+        data2 = parse_json_from_output(result2.stdout)
+        assert len(data2["NESTED_REPOS"]) == 1
+        assert data2["NESTED_REPOS"][0]["path"] == "services/backend/auth"