From a57b04a3d52298612b659ad9bf2cd61f4560247b Mon Sep 17 00:00:00 2001 From: mach273 Date: Fri, 29 May 2026 12:18:54 +0530 Subject: [PATCH] docs(v0.3): add #22 Windows support candidate (WSL2 callout + demand-gated port) Consolidates the 2026-05-18 Windows port evaluation (nucleus session windows-port-eval-1779112103) into the v0.3 candidate list so the decision lives with the roadmap, not just the nucleus log. Two-phase: Phase A WSL2 callout (v0.2.x stopgap), Phase B native port demand-gated. Captures bootstrap-vs-runtime split and half-port pitfall. Co-Authored-By: Claude Opus 4.8 --- docs/planning/v0.3.md | 70 ++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 69 insertions(+), 1 deletion(-) diff --git a/docs/planning/v0.3.md b/docs/planning/v0.3.md index 60093f9..19bdc8e 100644 --- a/docs/planning/v0.3.md +++ b/docs/planning/v0.3.md @@ -253,6 +253,71 @@ agent. --- +### #22 Windows support (WSL2 callout now, native port conditional) + +**What**: two-phase Windows story. + +- **Phase A (v0.2.x stopgap, ~1hr)**: ship a one-paragraph WSL2 callout + in `INSTALL.md` (and a README link). Tells Windows users explicitly: + use WSL2 (or Git Bash for read-only commands); native PowerShell is + not supported today. Closes the "does atom work on Windows?" question + without committing to a port. +- **Phase B (v0.3+, demand-gated)**: native Windows port — but only if + real user demand surfaces. Not speculative. + +**Why**: today the README has a single line ("Windows users need Git +Bash, WSL, or similar") buried at line 53. That's not enough for a +Windows user to know whether to invest. The cheap callout fixes that. +The native port is a different question that depends on demand. + +**Findings from 2026-05-18 evaluation session** (nucleus session +`windows-port-eval-1779112103`): + +- *Runtime is portable*. The 5 atom CLIs (atom, atom-setup, nucleus, + learnings, model-race) are pure Node ESM using `os.homedir()` — + `~/.atom` resolves correctly on Windows already. +- *Bootstrap is where the cost lives*. The bash `atom-setup` bootstrap + (shebang + `tr`/`grep`/`sed` PATH-scan) and the symlink-based dev/use + globals from the 2026-05-07 separation work are the real blockers. + These need PowerShell equivalents or a Node rewrite. +- *Half-port is a trap*. A native Windows port done halfway is **worse + UX than "use WSL2"** — atom-setup installs cleanly, then the user + hits Claude Code (officially macOS/Linux/WSL only), Multica, VHS, or + Freeze and dead-ends two steps later. If committing to native, the + **full downstream chain must be validated on a real Windows box**, + not just atom itself. +- *Cross-platform porting framework*. Separate **bootstrap layer** + (bash/PowerShell — where Unix-isms like sudo/EACCES/PATH-scan/ + symlinks/chmod/exec accumulate) from **runtime layer** (already + portable via stdlib abstractions). Audit each independently. + +**Open questions** (for Phase B only): + +- Is there real user demand, or is this maintainer speculation? Phase A + is the demand-detection mechanism — if Windows users hit the WSL2 + callout and complain, that's signal. +- Downstream-chain validation: which of Claude Code / Codex / Gemini / + Multica / VHS / Freeze actually work on native Windows? Without this + audit, a native port is a trap (see above). +- Bootstrap rewrite path: PowerShell port of `atom-setup` bash, or + Node rewrite of the bootstrap so there's one implementation? Node + rewrite probably wins long-term but is bigger work. +- Symlink alternative: Windows symlinks need admin or Developer Mode. + Replace with copy-on-install or `.cmd` shims? + +**Effort**: +- Phase A: small (~1hr — one paragraph in INSTALL.md + README link). +- Phase B: large (bootstrap rewrite + downstream-chain validation + + Windows CI). Don't size precisely until Phase A surfaces demand. + +**Decision**: Phase A ships in v0.2.x as a cheap stopgap. Phase B is +**conditionally deferred** — gated on real user demand, not +speculative porting. Decision pattern: ship the cheap option to keep +optionality open; the deep option only pays off if users actually +exist. + +--- + ## Pre-existing v0.3 deferrals (locked decisions, build deferred) These were locked during v0.2 planning with full design surface @@ -288,7 +353,10 @@ it — the embedding column belongs in the DB. (semantic) is in scope and on whether scale demands it yet. 6. **Decide on #17 (research)**. Lowest urgency; defer to v0.4 if v0.3 already fills up. -7. **#19, #20** ride along with whichever wave fits. +7. **Ship #22 Phase A now (out-of-band v0.2.x)**. WSL2 callout is a + ~1hr stopgap independent of the v0.3 wave. Phase B (native port) is + demand-gated — re-evaluate after Phase A surfaces signal. +8. **#19, #20** ride along with whichever wave fits. ---