didericis
9d82535390
Adds scripts/linux-install-test.sh, a throwaway-VM harness that exercises install.sh the way a brand-new user would across a Linux distro matrix (Ubuntu, Fedora, Arch, Alpine, NixOS), plus the research note docs/research/testing-clean-install-on-linux.md that motivates the approach. This is the Linux counterpart to the macOS clean-install harness. On Linux the boundary of choice flips from a throwaway user account to a disposable KVM VM: it's a genuine kernel + userland + package-manager boundary that wipes to nothing on teardown, and a single harness can swap distro cloud images to cover the several package-management regimes Linux fragments into. The host already needs KVM for the Firecracker backend, so a per-run, copy-on-write VM (qemu-img create -b base) is cheap here -- the equivalent of `docker run --rm`, for a whole machine. Per run the harness caches one read-only base image, boots a throwaway overlay via QEMU/KVM with user-mode networking (no root, no bridge), injects an ephemeral SSH key + passwordless login through a cloud-init seed ISO, installs the distro's prerequisites (python3 + git + pipx), pipes THIS checkout's install.sh into the guest exactly as `curl ... | sh` would, and asserts the CLI installed cleanly. The overlay is deleted on teardown, so even the OS-level prerequisites are wiped -- unlike a throwaway user, the reset is total. Subcommands mirror the macOS harness (up/run/status/down/test) plus test-all (the matrix) and ssh (an interactive guest shell). test arms an EXIT/INT/TERM trap the moment the VM exists, so a failure or Ctrl-C still tears it down. Scope is installer correctness, not runtime: there is no nested KVM/Docker in the VM, so `bot-bottle doctor` correctly reports every backend not-ready and exits non-zero by design. The pass criterion is therefore install.sh exiting 0, the bot-bottle entry point being present on the fresh user's PATH, and `bot-bottle --version` running -- not a green doctor. doctor's output is still printed so a real installer regression (broken shim, import error) stays visible. Validated with `bash -n` and `shellcheck`. Runtime is host-only (needs /dev/kvm, qemu, cloud-localds), so like the macOS harness it isn't exercised by the Linux PR CI. The cloud-image URLs in the DISTRO table are the one place to bump when a distro cuts a newer build. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Research notes
Investigations into a question or a design space — landscape surveys,
tradeoff analyses, "should we do X or Y," assessments of an approach
before (or instead of) committing it to a PRD. A research note is where
the thinking lives; a PRD is where a decided feature lives, and a
decision record is where a settled choice lives (see
../README.md for picking between them).
Notes are opinionated. They reach a conclusion rather than dumping a neutral survey — the point is to move a decision forward and leave a durable record of why it went the way it did.
Naming
kebab-case-topic.md, named by subject and not numbered (unlike
PRDs and decision records). Pick a name that says what was
investigated: bash-vs-python-vs-go.md, pipelock-assessment.md,
issue-tracking-vs-in-repo-decision-history.md.
Shape (freeform)
There's no fixed template — use whatever structure fits the question. In practice most notes share a loose shape:
- Open with the question — a sentence or two on what's being investigated and why it came up.
- Lead with the verdict — a
## Summarynear the top stating the conclusion, so a reader gets the answer without reading the whole thing. - Then the analysis — whatever the argument needs: comparison tables, per-option sections, failure-mode walkthroughs, the axes that actually matter.
- End with a recommendation when the note exists to drive a decision.
Keep the reasoning self-contained and grounded: cite sources, link files and PRDs, and prefer concrete evidence from this repo over generic claims — a note should stand on its own without a chat log or a Gitea thread. When a note's recommendation gets acted on, capture the resulting decision in a PRD or a decision record; the note stays as the "why we looked into it," not the system of record for the choice.