Cross-Platform Guardian
Outcome
Keep the setup path reproducible across macOS, Ubuntu, Fedora, and Linux/WSL
without hard-coded machine paths or untested platform assumptions.
Current Setup Boundary
bootstrap.sh is the supported entry point. It loads Nix, enters nix develop .#default, and runs uv run --locked python -m dotfiles_setup.
- macOS delegates missing-Nix installation to the Determinate package handoff.
- Linux and WSL require
./bootstrap.sh --install-nix --yes before the
bootstrapper runs the official Determinate installer.
- Python modules under
src/dotfiles_setup/ own profile, link, cleanup,
diagnostics, Rust, Git identity, and opt-in shell handoff behavior.
- The default install must not edit Bash or zsh startup files;
shell-handoff
is explicit.
Review Workflow
- Inspect
bootstrap.sh, the affected Python module, flake.nix, and the
matching pytest coverage before proposing a change.
- Check macOS and Linux/WSL behavior separately. Preserve the macOS package
handoff and the Linux explicit-install confirmation.
- Resolve HOME, XDG, CODEX, and platform paths through
paths.py. Keep the
managed destination inventory in links.py.
- Run
make test-pre, then the focused suite: make test-local for links,
make test-shell for handoff, and make test-docker for Ubuntu/Fedora
acceptance when the blast radius is cross-platform.
- Report platform evidence, skipped checks, and the rollback path. Nix package
regressions roll back with
nix profile rollback; managed links preserve
timestamped backups.
Stop Conditions
Do not claim macOS packaged behavior from a Linux container. Do not add a
second installer, restore retired shell setup scripts, or mutate user startup
files without the explicit shell-handoff request.
1---2name: cross-platform-guardian3description: "Protect macOS, Ubuntu, Fedora, and Linux/WSL compatibility in this dotfiles repository. Use for portability reviews, Nix changes, bootstrap changes, and platform test failures."4metadata:5 source: https://skillmd.com/skills/wcygan/cross-platform-guardian6---78# Cross-Platform Guardian910## Outcome1112Keep the setup path reproducible across macOS, Ubuntu, Fedora, and Linux/WSL13without hard-coded machine paths or untested platform assumptions.1415## Current Setup Boundary1617- `bootstrap.sh` is the supported entry point. It loads Nix, enters `nix18 develop .#default`, and runs `uv run --locked python -m dotfiles_setup`.19- macOS delegates missing-Nix installation to the Determinate package handoff.20- Linux and WSL require `./bootstrap.sh --install-nix --yes` before the21 bootstrapper runs the official Determinate installer.22- Python modules under `src/dotfiles_setup/` own profile, link, cleanup,23 diagnostics, Rust, Git identity, and opt-in shell handoff behavior.24- The default install must not edit Bash or zsh startup files; `shell-handoff`25 is explicit.2627## Review Workflow28291. Inspect `bootstrap.sh`, the affected Python module, `flake.nix`, and the30 matching pytest coverage before proposing a change.312. Check macOS and Linux/WSL behavior separately. Preserve the macOS package32 handoff and the Linux explicit-install confirmation.333. Resolve HOME, XDG, CODEX, and platform paths through `paths.py`. Keep the34 managed destination inventory in `links.py`.354. Run `make test-pre`, then the focused suite: `make test-local` for links,36 `make test-shell` for handoff, and `make test-docker` for Ubuntu/Fedora37 acceptance when the blast radius is cross-platform.385. Report platform evidence, skipped checks, and the rollback path. Nix package39 regressions roll back with `nix profile rollback`; managed links preserve40 timestamped backups.4142## Stop Conditions4344Do not claim macOS packaged behavior from a Linux container. Do not add a45second installer, restore retired shell setup scripts, or mutate user startup46files without the explicit shell-handoff request.