Windows Engineering

PowerShell 7 (pwsh) is the default shell unless the target or repository requires Windows PowerShell 5.1 or cmd. Apply only the sections the task touches.

Shell execution

• Stop dependent work when a native command fails. In PowerShell 7, && checks $LASTEXITCODE, but a native nonzero status becomes an error record only when $PSNativeCommandUseErrorActionPreference is $true; the default is $false. Handle tool-specific success codes, such as robocopy, explicitly. Cmdlet error handling is separate.
• Use literal paths and direct native invocation with argument arrays where possible. Start-Process -ArgumentList joins array elements into one command-line string; preserve the target program's required quoting for spaces and embedded quotes. PowerShell is not a POSIX shell.
• A name that Get-Command resolves under WindowsApps may be an app-execution alias, such as the Store redirector for python or python3, rather than the installed tool. Invoke the real executable or launcher.

Paths, open files, and DLLs

• Long-path opt-in (system policy plus application manifest) covers many Win32 file APIs, not every API, shell, or runtime. Supported extended paths are absolute \\?\C:\... or \\?\UNC\server\share\..., with backslashes and no ./..; the prefix disables normal normalization. Never blindly prepend it.
• Names are usually case-preserving/insensitive, but NTFS directories can be case-sensitive. No case-only source collisions or lowercasing as universal identity; use a two-step Git move for case-only renames. Avoid device names (CON, PRN, AUX, NUL, COM1–COM9, LPT1–LPT9, including extensions), trailing spaces/dots, and invalid filename characters.
• Open-file deletion/replacement depends on the operation and existing share modes, notably FILE_SHARE_DELETE. Identify the denying handle/process, including LNK1168 holders; retries help only if it will release the handle.
• Load non-system DLLs from trusted absolute paths with appropriate LoadLibraryExW LOAD_LIBRARY_SEARCH_* flags for dependencies. The top-level path does not secure transitive loads. Avoid current-directory/PATH searching and process-wide search-path mutation around individual calls.
• Stay unelevated except for the one operation that needs it; elevation and persistent machine-wide changes need approval. Symlinks may need Developer Mode or privilege; junctions cover only directories, and copies lose update semantics. A fallback that preserves behavior needs no extra approval; one that changes link or update semantics does, and otherwise report the limitation.

Encoding and terminal I/O