Define the staged native Windows support contract

[codeforester]

Summary

• define a PowerShell-first native Windows support contract and compatibility matrix
• separate native Windows from Git Bash and WSL2 support
• add a pinned windows-latest Phase 0 contract gate and documentation drift tests
• reconcile .ai-context/ and product-assessment platform statements with the staged contract
• distinguish Phase 0 validation from future Phase 1 launcher validation
• enforce the documented PowerShell 7.4 floor and reject affirmative native-Windows support claims in canonical public surfaces
• make the unimplemented native launcher, setup, activation, execution, and IDE work explicit deferrals

Issue

Refs #2082

Validation

• /Users/rameshhp/.base.d/base/.venv/bin/python -m pytest -q tests/test_windows_support_docs.py tests/test_contract_hardening.py tests/test_github_workflows.py (61 passed)
• git diff --check
• Supported full gate: 1,199 passed; two unrelated pre-existing failures remain in base_cli_adapters/run_index and Base CLI context documentation
• Ruff was not installed in the local Base virtualenv; hosted quality checks remain required

Release

This Phase 0 contract slice is intended for the 1.10.0 release line. It does not claim that Base supports native Windows and does not add a fake PowerShell wrapper around the Bash runtime.

Demo Impact

No demo behavior changes. The contract explicitly keeps basectl demo deferred until a native Windows process and project-execution adapter exists.

Context

.ai-context/PROJECT.md and .ai-context/DECISIONS.md now describe the 1.10.0 staged Windows plan.

[codeforester]

Review: staged native Windows support contract

Reviewed ac64a476. This is a docs + CI contract slice with no runtime code, so there are no crash-class bugs. The new pytest assertions match the shipped text, the contract-registry set stays green, and the workflow's pinned SHAs / permissions / concurrency / timeout all satisfy the existing workflow policy tests. The findings below are consistency and contract-integrity gaps.

1. .ai-context/ now contradicts the canonical docs — .ai-context/PROJECT.md:12, .ai-context/DECISIONS.md:15

Both still read Windows support is not currently in scope. after this PR adds a workflow and rewrites the Windows stance in README.md, architecture.md, product-requirements.md, and technical-overview.md. AGENTS.md "AI Context Maintenance" says to update .ai-context/ when a change affects "product shape, architecture, command surface, workflows ... or durable design decisions", and "If .ai-context/ disagrees with the repo docs or code, update .ai-context/." The PR body's rationale ("no shipped command or architecture behavior changed") addresses the typo/formatting carve-out but not the workflows / durable-design-decision / disagreement clauses. Update both lines to point at docs/windows-support.md with the staged-contract wording.

2. product-assessment.md still says Windows is out of scope while its sibling canonical doc was updated — docs/product-assessment.md:65

Under ### Current Platform Contract: "Broader Linux distribution support remains deliberately narrow and Windows is not currently in scope." docs/contracts.md:28 names both Product Assessment and Product Requirements as canonical positioning docs; this PR updates the parallel sentence in product-requirements.md:39-40 to the staged-contract wording but leaves this one. Two canonical docs now say contradictory things about whether a Windows plan exists. (Lines 25, 196, 403 are "don't overstate" framing and are fine as-is; only line 65 is the stale factual claim.)

3. The registered contract isn't actually enforced by its named test — tests/test_windows_support_docs.py

contracts.md:29 declares the failure mode "A public surface claims native Windows support before the launcher, command subset, and clean-install gates exist", enforced by this test. But the test only makes positive substring assertions against windows-support.md, README.md, and the workflow. It never scans architecture.md, product-requirements.md, technical-overview.md, product-assessment.md, CHANGELOG.md, or release notes for affirmative support claims. A future edit adding "Base fully supports native Windows" to the README passes CI as long as the checked marker strings survive, so the registry row provides no real drift protection against the thing it names.

4. Workflow vs. windows-support.md "Phase 1 Validation" list overlap is confusing — .github/workflows/windows-contract.yml:44

docs/windows-support.md:138-146 lists five things "The Windows job should run ... to prove the contract boundary". The committed job does 1–3, a fragment of 4 (a raw yaml.safe_load + name == 'base' assertion — not the pure-Python manifest/workspace readers, and not against spaced paths), and not 5 (the Bash/WSL2/Homebrew/apt absence is only an informational Write-Host, not an assertion). The doc does say the job is Phase 0 and "must be ... expanded when Phase 1 lands", so this is mostly a clarity problem: either split the doc into "Phase 0 job asserts X" vs "Phase 1 will add Y", or add a comment in the job mapping steps to the list, so a maintainer doesn't read items 4–5 as already enforced.

5. PowerShell version gate is dead code and below the documented floor — .github/workflows/windows-contract.yml:47

The "Verify native Windows prerequisites" step runs under shell: pwsh, so $PSVersionTable.PSVersion.Major is always 7+ on windows-latest and if ($PSVersionTable.PSVersion.Major -lt 7) { throw } can never fire. It also only checks major >= 7, while windows-support.md:30 requires "PowerShell 7.4 or newer as the supported interactive shell". If the step is meant to validate the contract's shell floor, compare against [version]"7.4" (and drop $ErrorActionPreference-guarded dead branch), otherwise it's a no-op with a misleading step name.

What's good

Clean separation of native Windows from Git Bash / WSL2, explicit deferral list for launcher / activation / execution / IDE / completion, pinned windows-latest gate wired into the contract registry, and the doc's own instruction to rename the job when Phase 1 lands. The "does not add a fake PowerShell wrapper around the Bash runtime" restraint is the right call.

🤖 Generated with Claude Code

[codeforester]

Follow-up to the Claude review comment:

All five findings were addressed in commit b614d824:

1. Updated .ai-context/PROJECT.md and .ai-context/DECISIONS.md to describe the staged native Windows plan and 1.10.0 target.
2. Updated docs/product-assessment.md so its platform contract matches the staged Windows documentation.
3. Strengthened tests/test_windows_support_docs.py to scan canonical product/context docs and CHANGELOG.md for affirmative native-Windows support claims before the launcher, command subset, and clean-install gates exist. Updated the contract-registry failure-mode wording accordingly.
4. Split docs/windows-support.md into explicit Phase 0 validation, which the current workflow actually performs, and Phase 1 validation, which remains future work.
5. Changed the workflow prerequisite check to enforce PowerShell 7.4+ and added a regression assertion for that floor.

Validation: the focused contract/workflow suite passes 61 tests; Pylint 3.10–3.13 and issue-branch policy pass on the new commit. The PR description now records the 1.10.0 target and the remaining local validation caveats.