WSL port 0/7: index the work as a checklist
First of a stack of six. This one is documentation only — it writes down what
the port has to fix and what it will be measured against.
What breaks on a stock WSL2 box
| Feature | Promised | Actual |
|---|---|---|
Ctrl+C/X/V system clipboard | README.md, KEYS.md | broken — clipboard=unnamedplus with no provider; Ctrl+V over a selection deletes and pastes nothing |
| timer sound + desktop notification | README.md | silent — afplay/osascript absent, paplay/notify-send not installed |
d two-sum at all | README.md | install.sh says apt install neovim; Ubuntu ships 0.6.1, which its own 0.9 gate then rejects |
demo.sh | docs/recording.md | every keystroke shells out to bc, which Ubuntu/WSL does not ship |
./tests/run.sh | docs/testing.md | 4 clipboard cases fail; tests/bin/timeout shadows real GNU timeout |
Every one of these fails quietly. That is the reason this is worth doing
properly rather than patching the first thing someone notices.
The rule that keeps macOS safe
Every change in this stack is additive and capability-probed, never if not mac. The existing macOS branch stays first in every chain with its exact
semantics. pbcopy, afplay and osascript all exist on a Mac, so every new
branch in the stack is dead code there.
The stack
| # | Branch | Base |
|---|---|---|
| 0 | wsl/00-todo | main ← you are here |
| 1 | wsl/01-install | wsl/00-todo |
| 2 | wsl/02-clipboard | wsl/01-install |
| 3 | wsl/03-timer | wsl/02-clipboard |
| 4 | wsl/04-demo-tests | wsl/03-timer |
| 5 | wsl/05-ci-docs | wsl/04-demo-tests |
Honest caveat, stated up front
The suite cannot check Ctrl+Shift+Q: suite_quit.sh synthesises ESC[113;6u
straight onto the pty, so it passes on a terminal where the chord could never
fire. That one has to be pressed by hand in Windows Terminal, and the result
gets recorded in docs/wsl.md at checkpoint 5.
🤖 Generated with Claude Code
https://claude.ai/code/session_01WveBqAyhoM49p9gWfwBDBx
Summary by CodeRabbit
- Documentation
- Added a measured WSL2 portability roadmap documenting observed failures and additive capability probing.
- Organized the work into six checkpointed pull requests with validation gates.
- Documented a Windows Terminal quit-key limitation and components intentionally excluded from portability efforts.
- Removed the outdated empty feature-ideas note.
Greptile Summary
Documentation-only change that replaces the empty feature-ideas note with a measured WSL portability roadmap.
- Records current WSL2 compatibility failures and the environment used to observe them.
- Defines five implementation checkpoints with explicit validation gates.
- Documents the macOS compatibility invariant, the manual quit-key check, and intentionally excluded work.
Confidence Score: 5/5
This documentation-only PR appears safe to merge.
No blocking failure remains.
Important Files Changed
| Filename | Overview |
|---|---|
| TODO.md | Adds a clear, checkpointed WSL portability plan without changing runtime behavior. |
Reviews (3): Last reviewed commit: "Stop sending the reader to look for a hi..." | Re-trigger Greptile