Define the staged native Windows support contract

.ai-context/DECISIONS.md

@@ -12,7 +12,10 @@ architecture discussion.
   setup for conservative Base prerequisites are implemented. Broader Linux
   distribution and WSL support remain outside the current contract; keep
   platform details in `docs/linux-support.md`.
-- Windows support is not currently in scope.
+- Native Windows is a staged future capability targeted for 1.10.0. Phase 0 may
+  define and test the contract, but the native launcher and read-only command
+  subset remain deferred until their platform adapters exist. Git Bash is not a
+  native Windows tier, and WSL2 remains a Linux runtime path.
 - Base should solve the author's real multi-repo workflow elegantly while
   keeping single-repository project adoption low-friction; it should not become
   a broad general-purpose platform.

.ai-context/PROJECT.md

@@ -9,7 +9,10 @@
 - Linux posture: Ubuntu/Debian runtime support, source-checkout validation, and
   apt-backed setup are implemented and tested; broader Linux distribution
   support remains tracked in `docs/linux-support.md`.
-- Windows support is not currently in scope.
+- Native Windows is a staged future capability targeted for 1.10.0. The current
+  Phase 0 contract and CI are documented in `docs/windows-support.md`, but the
+  current release does not support native Windows; Git Bash and WSL2 are not
+  substitutes for that contract.
 
 Base is a local operating contract for developers and platform engineers who
 need deterministic local readiness and handoff within a project, whether that

.github/workflows/windows-contract.yml

@@ -0,0 +1,65 @@
+name: Windows contract
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  contract:
+    name: Native Windows contract (Phase 0)
+    runs-on: windows-latest
+    timeout-minutes: 10
+
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5
+
+      - name: Set up Python
+        uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065
+        with:
+          python-version: "3.13"
+
+      - name: Install contract test dependencies
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          python -m pip install --upgrade pip
+          python -m pip install -r requirements-dev.txt
+
+      - name: Run documentation contract tests
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          python -m pytest -q tests/test_windows_support_docs.py
+
+      - name: Verify native Windows prerequisites
+        shell: pwsh
+        run: |
+          $ErrorActionPreference = "Stop"
+          $minimumPowerShell = [version]"7.4"
+          if ($PSVersionTable.PSVersion -lt $minimumPowerShell) {
+            throw "The native Windows contract requires PowerShell $minimumPowerShell or newer; found $($PSVersionTable.PSVersion)."
+          }
+          $git = Get-Command git -ErrorAction Stop
+          $python = Get-Command python -ErrorAction Stop
+          Write-Host "PowerShell: $($PSVersionTable.PSVersion)"
+          & $git.Source --version
+          & $python.Source --version
+
+          $manifest = Join-Path $PWD "base_manifest.yaml"
+          if (-not (Test-Path -LiteralPath $manifest -PathType Leaf)) {
+            throw "Expected Base manifest at $manifest"
+          }
+          python -c "from pathlib import Path; import yaml; payload = yaml.safe_load(Path('base_manifest.yaml').read_text(encoding='utf-8')); assert payload['project']['name'] == 'base'"
+
+          if (Get-Command bash -ErrorAction SilentlyContinue) {
+            Write-Host "Bash is present on the hosted runner, but this Phase 0 gate does not invoke it."
+          }

README.md

@@ -585,11 +585,14 @@ Ubuntu/Debian support currently covers runtime checks, project diagnostics,
 source-checkout validation, and apt-backed setup for the simple prerequisites
 Base owns. Linux setup remains narrower than macOS setup and should stay behind
 the platform-policy boundary described in [docs/linux-support.md](docs/linux-support.md).
-Windows is out of scope for Base. Existing Ubuntu/Debian-under-WSL2 guidance is
-read-only/development guidance, not part of the coordinated Base release
-matrix. See the [ecosystem platform, license, and release
-policy](docs/ecosystem-policy.md) for the boundary between Base and the
-standalone component repositories.
+For the current coordinated release matrix, Windows is out of scope for Base.
+Native Windows is planned but not supported yet. The staged target, compatibility
+matrix, and explicit feature deferrals are documented in
+[Native Windows Support Contract](docs/windows-support.md).
+Existing Ubuntu/Debian-under-WSL2 guidance is read-only/development guidance,
+not part of the coordinated Base release matrix. See the [ecosystem platform,
+license, and release policy](docs/ecosystem-policy.md) for the boundary between
+Base and the standalone component repositories.
 
 The macOS CI floor runs on GitHub's `macos-14` runner. Newer macOS runners may
 be added for coverage, but the floor job should stay until Base intentionally

docs/README.md

@@ -83,6 +83,9 @@ reference. The filename should answer "what is this about?"
   dispatch order, public launchers, and runtime shell behavior.
 - [Linux Support](linux-support.md) defines the Ubuntu/Debian runtime support,
   apt-backed setup path, and bootstrap boundaries.
+- [Native Windows Support Contract](windows-support.md) defines the proposed
+  PowerShell-first contract, staged parity model, compatibility matrix, and
+  boundaries for future native Windows work.
 - [Runtime Environment](runtime-environment.md) is the canonical reference for
   Base-managed environment variables, `~/.baserc`, and mutability rules.
 - [Shell Startup Files](shell-startup.md) documents the marked Bash/Zsh dotfile

docs/architecture.md

@@ -11,7 +11,9 @@ readiness, trust, onboarding, and handoff evidence needed to operate that repo
 set through one CLI interface. The current implementation support contract
 covers macOS plus narrow Ubuntu/Debian source-checkout runtime and apt-backed
 setup paths. Broader Linux distribution support, WSL, and Windows are not in
-scope today.
+scope today. Native Windows has a separate staged proposal in
+[Native Windows Support Contract](windows-support.md); it must not be treated as
+supported until its native launcher and command subset have passed that contract.
 
 The governing philosophy: **solve your own problem elegantly first**. Base is
 built for a specific workflow: multiple peer Git repositories under a shared

docs/contracts.md

@@ -26,6 +26,7 @@ before treating the fix as complete.
 | Read-only inspection JSON | [Inspection JSON](inspection-json.md), [Command Quick Reference](command-reference.md) | `cli/bash/commands/basectl/tests/inspection-json.bats`, `cli/python/base_release/tests/test_engine.py`, [`base-cli/tests/test_inspection.py`](https://github.com/basefoundry/base-cli/blob/main/tests/test_inspection.py), `tests/test_stability_tiers_docs.py` | A scoped command emits prose or invalid JSON, changes the v1 envelope, loses finding/error semantics, or diverges from text-mode exit policy | CLI |
 | Project metadata defaults | `.github/base-project.yml`, [GitHub Workflow](github-workflow.md), [Repository Baseline](repo-baseline.md) | `cli/python/base_github_projects/tests/`, `cli/bash/commands/basectl/tests/gh.bats`, `cli/bash/commands/basectl/tests/repo.bats` | Issue defaults, Project field options, or repo-visible Project configuration drift from the Base Project schema | Product |
 | Canonical positioning documentation | [Product Requirements](product-requirements.md), [Product Assessment](product-assessment.md), [Why Base](why-base.md), and the canonical introduction surfaces | `tests/test_contract_hardening.py` | A canonical newcomer, contributor, or agent surface reintroduces retired product positioning or drops the accepted local-operating-contract thesis and outcome loop | Product |
+| Native Windows support boundary | [Native Windows Support Contract](windows-support.md), `README.md`, canonical product/context docs, and `.github/workflows/windows-contract.yml` | `tests/test_windows_support_docs.py` | A public surface or release note claims native Windows support before the launcher, command subset, and clean-install gates exist | Platform |
 
 ## Contract Check Runner
 

docs/linux-support.md

@@ -28,7 +28,9 @@ Base does not ship a Debian package, own every project runtime dependency, or
 claim support for every Linux distribution. Broader Linux families,
 non-Debian WSL distributions, native Windows, GUI IDE setup on Linux, and
 project-specific dependency ownership need separate product decisions and
-platform adapters.
+platform adapters. The proposed native Windows boundary is maintained in
+[Native Windows Support Contract](windows-support.md); it is not a WSL2
+extension of this Linux contract.
 
 ## Target Scope
 

docs/product-assessment.md

@@ -61,8 +61,10 @@ becoming equal product pillars.
 ### Current Platform Contract
 
 Ubuntu/Debian source-checkout runtime and apt-backed setup support are
-implemented. Broader Linux distribution support remains deliberately narrow and
-Windows is not currently in scope.
+implemented. Broader Linux distribution support remains deliberately narrow.
+Native Windows is planned but not currently shipped; its Phase 0 contract and
+future parity model are maintained in [Native Windows Support Contract](windows-support.md)
+for the 1.10.0 release line.
 
 The local workspace agent brief now summarizes repository readiness for a
 handoff, while onboarding, diagnostics, privacy-conscious history reports, and

docs/product-requirements.md

@@ -39,7 +39,8 @@ across every repository and external tool.
 
 Base remains macOS-primary. Ubuntu/Debian source-checkout runtime and apt-backed
 setup support are implemented, while broader Linux distribution support remains
-intentionally narrow and Windows is not currently in scope.
+intentionally narrow. Native Windows is not currently shipped; its proposed
+staged contract is maintained in [Native Windows Support Contract](windows-support.md).
 
 Major product work should improve the outcome loop. A broad command is not core
 merely because Base can expose it.

docs/technical-overview.md

@@ -19,6 +19,8 @@ inventory -> prepare -> verify -> trust -> onboard -> hand off
 
 The `basectl` CLI provides the execution surface for that loop, including setup,
 diagnostics, project discovery, shell activation, test execution, and releases.
+Native Windows is a planned PowerShell-first target, not a current support tier;
+see [Native Windows Support Contract](windows-support.md) for the staged boundary.
 
 > The repo you check out once per workspace so all other repos become easier to
 > set up, test, and run.

docs/windows-support.md

@@ -0,0 +1,168 @@
+# Native Windows Support Contract
+
+Status: proposal and implementation boundary; native Windows is not supported
+by the current Base release.
+
+This document defines the smallest credible path for bringing Base to native
+Windows. It is intentionally a contract first. Git Bash and WSL2 are useful
+development environments, but neither one is native Windows support and neither
+one satisfies this proposal.
+
+## Compatibility Matrix
+
+| Environment | Current status | Runtime contract |
+|---|---|---|
+| macOS 14+ | Supported | Homebrew, Bash, Python, and Git |
+| Ubuntu/Debian | Supported | Linux runtime with apt-backed setup |
+| Ubuntu/Debian on WSL2 | Supported as Linux | `BASE_PLATFORM=linux-debian`, `BASE_HOST_ENV=wsl2` |
+| Native Windows | Planned, not supported | PowerShell-first launcher and Windows-native adapters |
+| Git Bash on Windows | Not a support tier | May run selected source scripts, but is not the native contract |
+
+The README and release notes must keep native Windows in the planned column until
+the Phase 1 acceptance criteria below pass on a clean `windows-latest` runner
+and a clean supported Windows developer machine.
+
+## Proposed Phase 1 Contract
+
+The first native Windows slice targets Windows 11 22H2 or newer on x64 and
+ARM64, with:
+
+- PowerShell 7.4 or newer as the supported interactive shell;
+- Git for Windows' native `git.exe` as the Git implementation;
+- Python 3.10 through 3.13 from an installation managed by the user or the
+  documented Windows installer route;
+- GitHub CLI only for commands that explicitly need GitHub access;
+- no Bash executable, Bash dotfiles, Homebrew, apt, or WSL2 dependency;
+- a process launcher that passes argument arrays to child processes and does not
+  reconstruct commands through a shell;
+- no automatic profile mutation during install or first use.
+
+`cmd.exe` is not a first-class interactive shell in Phase 1. It may invoke the
+PowerShell entrypoint explicitly, but command completion and profile guidance
+are PowerShell-specific until another shell contract is designed.
+
+## Installation and State
+
+The eventual clean-install route should use a versioned, signed Windows release
+asset (MSI, MSIX, or an equivalently verifiable package) published with the
+GitHub release. A network one-liner that downloads and executes an unpinned
+script is not an acceptable installer contract.
+
+The source checkout remains a supported contributor route. The release installer
+must place the launcher and Base runtime in a versioned application location and
+make updates replaceable without editing a user's project repositories.
+
+Native Windows state is user-scoped:
+
+| State | Location |
+|---|---|
+| Persistent Base state | `%LOCALAPPDATA%\Base` |
+| Base cache | `%LOCALAPPDATA%\Base\Cache` |
+| Temporary run data | `$env:TEMP` |
+| Project checkout | User-selected workspace path; spaces are supported |
+
+The implementation must not reuse the macOS `~/Library` or Linux `~/.cache`
+locations on native Windows. A future state migration must be explicit and
+backward-compatible.
+
+## Initial Command Subset
+
+Phase 1 is intentionally read-only or dry-run oriented. The supported subset is:
+
+| Command surface | Phase 1 behavior |
+|---|---|
+| `basectl check` | Inspect the Windows runtime and report stable findings |
+| `basectl doctor` | Explain readiness findings and recovery commands |
+| `basectl projects list` | Discover projects under an explicit workspace path |
+| `basectl projects status` | Report project state without mutation |
+| `basectl projects manifest` | Parse and validate a project manifest |
+| `basectl workspace status` | Report workspace membership and repository state |
+| `basectl workspace check` | Run local workspace checks without credentials |
+| `basectl workspace doctor` | Render workspace findings without mutation |
+| `basectl setup --dry-run` | Describe planned setup without applying changes |
+| `basectl gh auth status` | Report local GitHub CLI auth state when `gh` is installed |
+
+Text and JSON output must preserve the existing inspection envelope and finding
+semantics wherever the command is already a stable Base surface. Windows paths
+may differ in representation, but they must remain unambiguous and parseable.
+
+## Platform Boundary Rules
+
+Windows-specific behavior belongs behind small platform adapters. The native
+launcher and adapters own:
+
+- `Path` and environment-variable resolution, including spaces and Unicode;
+- process creation with `shell=False`-equivalent semantics;
+- executable lookup and `.exe` resolution;
+- UTF-8 text and CRLF/LF normalization at file boundaries;
+- ACL-aware state-directory creation and permission diagnostics;
+- the absence of POSIX executable bits and optional symlink privileges;
+- Git's line-ending settings without rewriting repository-owned policy.
+
+Command implementations must not scatter `if Windows` branches through their
+business logic. The adapter should expose stable capabilities and return an
+explicit unsupported result when a capability is not available.
+
+The trust model remains unchanged: project-owned commands are still inspected
+and explicitly approved before execution. Native Windows support must not weaken
+that boundary just because process execution uses PowerShell.
+
+## Staged Parity Model
+
+| Phase | Outcome | Exit criteria |
+|---|---|---|
+| 0. Contract and CI | Make the target explicit and prevent documentation drift | This specification, visible matrix, and a Windows-hosted contract gate |
+| 1. Native inspection | Ship the PowerShell launcher and read-only command subset | Clean install, `check`/`doctor`, manifest, workspace, and dry-run tests pass on Windows |
+| 2. Setup and execution | Add Windows tool/runtime adapters and guarded project execution | Setup, trust, test/run, and failure recovery have native behavior and tests |
+| 3. Developer parity | Add activation, demos, IDE integration, and release polish | Each feature has an explicit Windows adapter, docs, and hosted plus local validation |
+
+The current repository is at Phase 0. This document and its CI gate do not claim
+that a native Windows launcher or command subset has shipped. Phase 1 should be
+implemented as a separate reviewable slice once the contract is approved.
+
+## Explicit Deferrals
+
+Until the required adapters exist, native Windows documentation must describe
+these features as deferred:
+
+- `basectl activate` and shell prompt integration;
+- project `run`, `test`, `build`, and `demo` execution;
+- manifest-declared setup mutation and package-manager adapters;
+- IDE installation, extensions, and user settings;
+- Bash completion, Bash startup sections, and `update-profile`;
+- Homebrew and apt-backed artifacts;
+- any claim that Git Bash or WSL2 is an equivalent runtime.
+
+## Phase 0 Validation
+
+The current `.github/workflows/windows-contract.yml` job is deliberately limited
+to the contract boundary and requires no private credentials. It currently:
+
+1. install the pinned Python test dependencies;
+2. run the documentation/contract tests;
+3. verify PowerShell, Python, and native Git discovery;
+4. confirm that `base_manifest.yaml` exists and can be parsed by the test
+   dependency set.
+
+The Phase 0 job intentionally does not invoke a native Base launcher, exercise
+the pure-Python manifest or workspace readers against paths containing spaces,
+or assert that Bash, WSL2, Homebrew, and apt are absent. Those are Phase 1
+acceptance checks, not claims made by the current workflow.
+
+## Phase 1 Validation
+
+When the native launcher and read-only command subset land, rename and expand
+the Windows job to prove the actual native path with no private credentials:
+
+1. install or obtain Base through the documented clean-install route;
+2. invoke the PowerShell launcher for `check`, `doctor`, manifest/project
+   discovery, workspace inspection, and `setup --dry-run`;
+3. exercise the pure-Python manifest and workspace readers against paths
+   containing spaces and Unicode;
+4. validate native executable resolution, argument-array process execution,
+   environment propagation, and CRLF/LF handling;
+5. verify that the supported command subset does not depend on Bash, WSL2,
+   Homebrew, or apt.
+
+Until those checks pass, the workflow must remain named and documented as a
+Phase 0 contract gate and must not be mistaken for full Windows support.

tests/test_contract_hardening.py

@@ -253,6 +253,7 @@ def test_contract_registry_rows_have_complete_enforcement_metadata() -> None:
         "Canonical positioning documentation",
         "Workspace agent-brief JSON schema",
         "Workspace update JSON schema",
+        "Native Windows support boundary",
     }
     for row in rows:
         assert row["Source of truth"], row