Fix scope gaps, depth-protect git root discovery, consolidate API

Move checkout directories to ApplicationData:
- AssembleContext: .artifacts/checkouts/{env} → ApplicationData/checkouts/{env}
- CodexContext:    .artifacts/codex/clone     → ApplicationData/codex/clone
Both now resolve within the existing ApplicationData scope root; no
worktree detection or scope expansion needed. Paths.ResolveGitCommonRoot
(IFileSystem) had no remaining callers and is removed along with its tests.

Depth protection on git root discovery:
- DetermineWorkingDirectoryRoot: only adopts a .git anchor ≤ 1 directory
  above CWD in release builds. Debug builds allow deeper traversal when
  a *.slnx is adjacent (developer running from IDE output directory).
- FindGitRoot(string) gets the same depth limit — documentation is not
  expected to live deep inside a repo tree.

Consolidate FindGitRoot / DetermineSourceDirectoryRoot:
- DetermineSourceDirectoryRoot removed; FindGitRoot(IDirectoryInfo)
  overload added with the same semantics (IFileSystem-abstracted,
  same depth protection, returns IDirectoryInfo?).
- Callers updated: BuildContext, ChangelogCommand, LocalChangesService.

Rename ForPath/ForPathWrite → RealForPath/RealForPathWrite:
- Signals these always create a real FileSystem.
- Doc comment notes suitability for command layer; service layer is
  tested via InMemory() at unit test level.

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

Author: Mpdreamz

src/Elastic.Codex/CodexContext.cs

@@ -46,9 +46,7 @@ public CodexContext(
 		ReadFileSystem = readFileSystem;
 		WriteFileSystem = writeFileSystem;
 
-		var workingRoot = ReadFileSystem.DirectoryInfo.New(Paths.WorkingDirectoryRoot.FullName);
-		var gitCommonRoot = Paths.ResolveGitCommonRoot(ReadFileSystem, workingRoot);
-		var defaultCheckoutDirectory = Path.Join(gitCommonRoot.FullName, ".artifacts", "codex", "clone");
+		var defaultCheckoutDirectory = Path.Join(Paths.ApplicationData.FullName, "codex", "clone");
 		CheckoutDirectory = ReadFileSystem.DirectoryInfo.New(checkoutDirectory ?? defaultCheckoutDirectory);
 
 		var defaultOutputDirectory = Path.Join(Paths.WorkingDirectoryRoot.FullName, ".artifacts", "codex", "docs");

src/Elastic.Documentation.Configuration/BuildContext.cs

@@ -108,7 +108,7 @@ public BuildContext(
 
 		(DocumentationSourceDirectory, ConfigurationPath) = Paths.FindDocsFolderFromRoot(ReadFileSystem, rootFolder);
 
-		DocumentationCheckoutDirectory = Paths.DetermineSourceDirectoryRoot(DocumentationSourceDirectory);
+		DocumentationCheckoutDirectory = Paths.FindGitRoot(DocumentationSourceDirectory);
 
 		OutputDirectory = !string.IsNullOrWhiteSpace(output)
 			? WriteFileSystem.DirectoryInfo.New(output)

src/Elastic.Documentation.Configuration/FileSystemFactory.cs

@@ -30,8 +30,7 @@ public static class FileSystemFactory
 	};
 
 	// AppData-only options: for components that only access caches/state files.
-	private static readonly ScopedFileSystemOptions AppDataOptions = new(
-		[Paths.ApplicationData.FullName])
+	private static readonly ScopedFileSystemOptions AppDataOptions = new([Paths.ApplicationData.FullName])
 	{
 		// .git needed for codex-link-index clone directory inside ApplicationData
 		AllowedHiddenFolderNames = new HashSet<string>(StringComparer.OrdinalIgnoreCase) { ".git" }
@@ -103,7 +102,7 @@ public static ScopedFileSystem WrapToWrite(IFileSystem inner) =>
 	/// <paramref name="path"/>. Falls back to <see cref="RealRead"/> when <paramref name="path"/>
 	/// is <see langword="null"/>. Use in commands that accept an explicit <c>--path</c> argument.
 	/// </summary>
-	public static ScopedFileSystem ForPath(string? path)
+	public static ScopedFileSystem RealForPath(string? path)
 	{
 		if (path is null)
 			return RealRead;
@@ -121,7 +120,7 @@ public static ScopedFileSystem ForPath(string? path)
 	/// Falls back to <see cref="RealWrite"/> when both are <see langword="null"/>.
 	/// Use in commands that accept explicit <c>--path</c> and/or <c>--output</c> arguments.
 	/// </summary>
-	public static ScopedFileSystem ForPathWrite(string? path, string? output = null)
+	public static ScopedFileSystem RealForPathWrite(string? path, string? output = null)
 	{
 		if (path is null && output is null)
 			return RealWrite;

src/Elastic.Documentation.Configuration/Paths.cs

@@ -16,86 +16,103 @@ public static class Paths
 	/// <summary>
 	/// Walks up from <paramref name="startPath"/> until a <c>.git</c> directory or file
 	/// (worktree pointer) is found and returns that ancestor. Returns <paramref name="startPath"/>
-	/// itself when no git root is found.
+	/// itself when no git root is found within the allowed depth.
 	/// </summary>
+	/// <remarks>
+	/// Depth protection: in release builds the <c>.git</c> anchor must be at most 1 directory
+	/// above <paramref name="startPath"/> — documentation is not expected to live deep inside
+	/// a repo. In debug builds a deeper <c>.git</c> is accepted when a <c>*.slnx</c> file is
+	/// adjacent (developer running the binary from an IDE output directory).
+	/// </remarks>
 	public static string FindGitRoot(string startPath)
 	{
 		var resolved = Path.IsPathRooted(startPath) ? startPath : Path.GetFullPath(startPath);
 		var dir = Directory.Exists(resolved)
 			? new DirectoryInfo(resolved)
 			: new DirectoryInfo(Path.GetDirectoryName(resolved) ?? resolved);
+		var depth = 0;
 		while (dir != null)
 		{
-			if (dir.GetDirectories(".git").Length > 0 || dir.GetFiles(".git").Length > 0)
-				return dir.FullName;
+			var hasGit = dir.GetDirectories(".git").Length > 0 || dir.GetFiles(".git").Length > 0;
+			if (hasGit)
+			{
+#if DEBUG
+				if (depth <= 1 || dir.GetFiles("*.slnx").Length > 0)
+					return dir.FullName;
+#else
+				if (depth <= 1)
+					return dir.FullName;
+#endif
+				// .git found but too deep — stop searching
+				return resolved;
+			}
+			depth++;
 			dir = dir.Parent;
 		}
 		return resolved;
 	}
 
-	private static DirectoryInfo DetermineWorkingDirectoryRoot()
+	/// <summary>
+	/// Walks up from <paramref name="startDirectory"/> via <see cref="IFileSystem"/> until
+	/// a <c>.git</c> directory or file (worktree pointer) is found.
+	/// Returns <see langword="null"/> if no git root is found within the allowed depth.
+	/// </summary>
+	/// <remarks>Same depth protection as <see cref="FindGitRoot(string)"/>.</remarks>
+	public static IDirectoryInfo? FindGitRoot(IDirectoryInfo startDirectory)
 	{
-		var directory = new DirectoryInfo(Directory.GetCurrentDirectory());
+		var directory = startDirectory;
+		var depth = 0;
 		while (directory != null)
 		{
-			if (directory.GetFiles("*.slnx").Length > 0)
-				break;
-			if (directory.GetDirectories(".git").Length > 0)
-				break;
-			// support for git worktrees
-			if (directory.GetFiles(".git").Length > 0)
-				break;
+			var hasGit = directory.GetDirectories(".git").Length > 0
+					  || directory.GetFiles(".git").Length > 0;
+			if (hasGit)
+			{
+#if DEBUG
+				if (depth <= 1 || directory.GetFiles("*.slnx").Length > 0)
+					return directory;
+#else
+				if (depth <= 1)
+					return directory;
+#endif
+				// .git found but too deep
+				return null;
+			}
+			depth++;
 			directory = directory.Parent;
 		}
-		return directory ?? new DirectoryInfo(Directory.GetCurrentDirectory());
+		return null;
 	}
 
-	/// <summary>
-	/// Walks up from <paramref name="sourceDirectory"/> via <see cref="IFileSystem"/> until a
-	/// <c>.git</c> directory or file (worktree pointer) is found.
-	/// </summary>
-	public static IDirectoryInfo? DetermineSourceDirectoryRoot(IDirectoryInfo sourceDirectory)
+	private static DirectoryInfo DetermineWorkingDirectoryRoot()
 	{
-		var directory = sourceDirectory;
+		var cwd = new DirectoryInfo(Directory.GetCurrentDirectory());
+		var directory = cwd;
+		var depth = 0;
 		while (directory != null)
 		{
-			if (directory.GetDirectories(".git").Length > 0)
-				return directory;
-			// support for git worktrees
-			if (directory.GetFiles(".git").Length > 0)
+			if (directory.GetFiles("*.slnx").Length > 0)
 				return directory;
+			var hasGit = directory.GetDirectories(".git").Length > 0
+					  || directory.GetFiles(".git").Length > 0;
+			if (hasGit)
+			{
+				// Only accept .git beyond 1 level up in debug when a *.slnx is adjacent
+				// (developer running from IDE output directory such as bin/Debug/net10.0/).
+#if DEBUG
+				if (depth <= 1 || directory.GetFiles("*.slnx").Length > 0)
+					return directory;
+#else
+				if (depth <= 1)
+					return directory;
+#endif
+				// .git found but too deep — stop without adopting it
+				return cwd;
+			}
+			depth++;
 			directory = directory.Parent;
 		}
-		return null;
-	}
-
-	/// <summary>Resolves the root of the main git repository, following worktree links when present. Disabled on CI.</summary>
-	public static IDirectoryInfo ResolveGitCommonRoot(IFileSystem fileSystem, IDirectoryInfo workingDirectoryRoot, bool? isCI = null)
-	{
-		if (isCI ?? !string.IsNullOrEmpty(Environment.GetEnvironmentVariable("GITHUB_ACTIONS")))
-			return workingDirectoryRoot;
-
-		var gitPath = Path.Join(workingDirectoryRoot.FullName, ".git");
-
-		if (fileSystem.Directory.Exists(gitPath))
-			return workingDirectoryRoot;
-
-		if (!fileSystem.File.Exists(gitPath))
-			return workingDirectoryRoot;
-
-		var content = fileSystem.File.ReadAllText(gitPath).Trim();
-		if (!content.StartsWith("gitdir:", StringComparison.OrdinalIgnoreCase))
-			return workingDirectoryRoot;
-
-		var gitDirPath = content["gitdir:".Length..].Trim();
-		if (!Path.IsPathRooted(gitDirPath))
-			gitDirPath = Path.GetFullPath(gitDirPath, workingDirectoryRoot.FullName);
-
-		var dir = fileSystem.DirectoryInfo.New(gitDirPath);
-		while (dir != null && dir.Name != ".git")
-			dir = dir.Parent;
-
-		return dir?.Parent ?? workingDirectoryRoot;
+		return cwd;
 	}
 
 	/// Used in debug to locate static folder, so we can change js/css files while the server is running

src/authoring/Elastic.Documentation.Refactor/Tracking/LocalChangesService.cs

@@ -39,7 +39,7 @@ public Task<bool> ValidateRedirects(IDiagnosticsCollector collector, string? pat
 			return Task.FromResult(false);
 		}
 
-		var root = Paths.DetermineSourceDirectoryRoot(buildContext.DocumentationSourceDirectory);
+		var root = Paths.FindGitRoot(buildContext.DocumentationSourceDirectory);
 		if (root is null)
 		{
 			collector.EmitError(redirectFile.Source, $"Unable to determine the root of the source directory {buildContext.DocumentationSourceDirectory}.");

src/services/Elastic.Documentation.Assembler/AssembleContext.cs

@@ -89,9 +89,7 @@ public AssembleContext(
 		Endpoints.Environment = environment;
 
 		var contentSource = Environment.ContentSource.ToStringFast(true);
-		var workingRoot = ReadFileSystem.DirectoryInfo.New(Paths.WorkingDirectoryRoot.FullName);
-		var gitCommonRoot = Paths.ResolveGitCommonRoot(ReadFileSystem, workingRoot);
-		var defaultCheckoutDirectory = Path.Join(gitCommonRoot.FullName, ".artifacts", "checkouts", contentSource);
+		var defaultCheckoutDirectory = Path.Join(Paths.ApplicationData.FullName, "checkouts", contentSource);
 		CheckoutDirectory = ReadFileSystem.DirectoryInfo.New(checkoutDirectory ?? defaultCheckoutDirectory);
 		var defaultOutputDirectory = Path.Join(Paths.WorkingDirectoryRoot.FullName, ".artifacts", "assembly");
 		OutputDirectory = ReadFileSystem.DirectoryInfo.New(output ?? defaultOutputDirectory);

src/tooling/docs-builder/Commands/ChangelogCommand.cs

@@ -91,7 +91,7 @@ public Task<int> Init(
 
 		var useNonDefaultChangelogDir = changelogDir != null;
 		var useNonDefaultBundlesDir = bundlesDir != null;
-		var repoRoot = Paths.DetermineSourceDirectoryRoot(docsFolder)?.FullName ?? docsFolder.FullName;
+		var repoRoot = Paths.FindGitRoot(docsFolder)?.FullName ?? docsFolder.FullName;
 
 		// Create changelog.yml from example if it does not exist
 		if (!_fileSystem.File.Exists(configPath))

src/tooling/docs-builder/Commands/DiffCommands.cs

@@ -29,7 +29,7 @@ public async Task<int> ValidateRedirects(string? path = null, Cancel ctx = defau
 		await using var serviceInvoker = new ServiceInvoker(collector);
 
 		var service = new LocalChangeTrackingService(logFactory, configurationContext);
-		var fs = FileSystemFactory.ForPath(path);
+		var fs = FileSystemFactory.RealForPath(path);
 
 		serviceInvoker.AddCommand(service, (path, fs),
 				async static (s, collector, state, _) => await s.ValidateRedirects(collector, state.path, state.fs)

src/tooling/docs-builder/Commands/FormatCommand.cs

@@ -43,7 +43,7 @@ public async Task<int> Format(
 		await using var serviceInvoker = new ServiceInvoker(collector);
 
 		var service = new FormatService(logFactory, configurationContext);
-		var fs = FileSystemFactory.ForPath(path);
+		var fs = FileSystemFactory.RealForPath(path);
 
 		serviceInvoker.AddCommand(service, (path, check, fs),
 			async static (s, collector, state, ctx) => await s.Format(collector, state.path, state.check, state.fs, ctx)

src/tooling/docs-builder/Commands/IndexCommand.cs

@@ -86,7 +86,7 @@ public async Task<int> Index(
 	)
 	{
 		await using var serviceInvoker = new ServiceInvoker(collector);
-		var fs = FileSystemFactory.ForPath(path);
+		var fs = FileSystemFactory.RealForPath(path);
 		var service = new IsolatedIndexService(logFactory, configurationContext, githubActionsService, environmentVariables);
 		var state = (fs, path,
 				// endpoint options