Skip to content

Windows Developer Guide for Cornerstone

Cornerstone is fully compatible with Windows, which is critical given DeAcero's dominant SQL Server legacy ecosystem. However, Windows development environments possess specific quirks regarding execution policies, line endings, and terminal contexts.

This guide outlines the standard operating procedures for developing on Windows.

1. PowerShell Execution Policy

By default, Windows restricts running unsigned PowerShell and .bat scripts to prevent malicious execution. This security feature will block setup\install.bat and any bash emulation attempted by Git hooks.

Solution: When triggering the template scaffolding or running the setup scripts for a newly generated project, dynamically bypass the policy for that single session: 

# In PowerShell:
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\setup\install.bat
Note: The Technical Committee explicitly decided not to hardcode registry-level ExecutionPolicy bypasses within the Cornerstone template (Tracked in Technical Decisions). Developers must authorize the execution manually per session.

2. Git Line Endings (CRLF vs LF)

Cornerstone's Agentic CI and pre-commit framework expects LF line endings (Linux/Unix standard) to maintain consistency with the GitHub Actions Ubuntu runners. If git clone converts your checkout to CRLF (Windows standard), tools like import-linter or bash Git hooks will crash with obscure errors.

Solution: Ensure your global Git configuration strictly preserves LF: 

git config --global core.autocrlf false

3. Virtual Environments (Anaconda / Conda)

Following Rule #12 (AGENTS.md), you must install dependencies in an isolated manner. If you utilize Anaconda (conda): 1. Avoid installing Cornerstone into your base environment to prevent version smashes with data science libraries. 2. Initialize an environment with Python 3.11+: 

conda create -n agentic-env python=3.13
conda activate agentic-env
pip install -e ".[dev]"

4. Git GUI Context vs CLI Context

If git commit hangs or fails to execute the pre-commit hooks when using GitHub Desktop or VSCode Source Control, it is because the GUI does not inherit your Conda/Python paths. Solution: Always perform your first commits from the CLI terminal where your agentic-env is active so the hooks can locate the ruff and mypy binaries.