Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 6 additions & 5 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,8 +77,8 @@ use `smoke` for the base image. Assertions write machine-readable Evidence when
Evidence rather than inferring a pass from job status.

Changes to persistence, setup, ownership, Compose, Dev Containers, Windows, or
Podman must update the automated scenarios where possible and the remaining
manual matrix in `uat-checklist.md`.
Podman must update the automated scenarios where possible. Optional follow-up
checks live in `uat-checklist.md`; they are not an implied release gate.

## Project structure

Expand Down Expand Up @@ -156,8 +156,8 @@ creates a non-discoverable draft GitHub Release, and verifies the downloaded
draft before publication can run. There is no release rebuild.

Prerelease tags publish automatically after those automated gates. For a stable
release, create the immutable final-version tag before physical qualification,
test the prepared digest and draft assets, then approve the separate
release, create the immutable final-version tag, verify the prepared digest and
draft assets, then approve the separate
`publish-release` job. Repository administrators must configure
`stable-release` with a required human reviewer and leave
`prerelease-auto` unprotected. Approval publishes the exact prepared bytes;
Expand Down Expand Up @@ -186,7 +186,8 @@ published immutable reruns must verify metadata without editing it.
## Pull requests and issues

Keep commits outcome-oriented and explain why the change is needed. Include
tests, Evidence IDs, supported migration behavior, and any remaining manual UAT.
tests, Evidence IDs, supported migration behavior, and any explicitly requested
optional UAT.

GitHub Issues is the tracker. A ready implementation issue contains reproduction
or design evidence, acceptance criteria, dependencies, and the relevant triage
Expand Down
23 changes: 11 additions & 12 deletions ROADMAP.md
Original file line number Diff line number Diff line change
@@ -1,22 +1,21 @@
# Roadmap

## v1.1.0 release gate
## v1.2.1 release gate

- Pass every assertion in `scripts/e2e-required.tsv` against one immutable Candidate digest.
- Complete the real-host matrix in `uat-checklist.md`, especially Windows,
macOS, Fedora rootless Podman/SELinux, Dev Containers/Codespaces, and
physical arm64 (tracked by GitHub issues #99–#105).
- `v1.1.0-rc5` completed the automatic publication rehearsal.
- Keep platform-specific manual qualification optional; automated Candidate
Evidence is the release gate.
- `v1.2.1-rc5` completed the automatic publication rehearsal.
- Keep GitHub immutable Releases enabled, keep the no-bypass `v*` update and
deletion ruleset active, and verify the stable/prerelease environment
protections before creating a final tag.
- Create the immutable `v1.1.0` tag so CI builds one final Candidate and
prepares its signed assets as a non-discoverable draft. Complete physical
qualification against that exact digest and draft asset set, then approve
the `v1.1-production` environment to publish those bytes without rebuilding.
- Create the immutable `v1.2.1` tag so CI builds one final Candidate and
prepares its signed assets as a non-discoverable draft, then approve the
protected stable environment to publish those bytes without rebuilding.
Do not retarget the final tag if qualification fails; fix forward with a new
version.
- Resolve or explicitly defer every open release-blocking GitHub issue.
- Verify the final Candidate identity, attestation, aliases, and non-rewind
behavior in issue #131.

## After v1.1

Expand All @@ -38,5 +37,5 @@
tmux, and Zellij with clear overrides for bat/delta themes.
- **Assistant completion notifications** — opt-in terminal bell/desktop adapter
around long-running assistant commands.
- **Native platform depth** — move remaining Windows, macOS, Podman/SELinux,
and physical-arm64 UAT into automated adapters where runners permit.
- **Native platform depth** — improve platform adapters when concrete defects
justify the work; do not maintain a standing manual qualification matrix.
94 changes: 13 additions & 81 deletions uat-checklist.md
Original file line number Diff line number Diff line change
@@ -1,24 +1,21 @@
# Squarebox v1.2 manual UAT
# Squarebox v1.2.1 release checks

Automated release assertions are defined in `scripts/e2e-required.tsv` and
reported from exact Evidence by `.github/workflows/e2e.yml`. This checklist
contains only behavior that still needs a person, real host integration, or
hardware outside GitHub-hosted runners. An unchecked item is **untested**, not
an automated pass.
reported from exact Evidence by `.github/workflows/e2e.yml`. That automated
Candidate workflow is the v1.2.1 release gate. A per-platform manual
qualification matrix is not required for this release.

Record the Candidate version, source SHA, image digest, host OS, architecture,
container runtime/version, and result for every run.
Native PowerShell remains a separate adapter and does not claim `SSH_AUTH_SOCK` forwarding;
adapter boundaries are covered by automated/static checks.

Record the Candidate version, source SHA, image digest, and result for any
optional follow-up run.

Release tracker: [v1.2.1 #125](https://github.com/SquareWaveSystems/squarebox/issues/125).
Qualification issues: [Linux desktop #126](https://github.com/SquareWaveSystems/squarebox/issues/126),
[Fedora/Podman #127](https://github.com/SquareWaveSystems/squarebox/issues/127),
[macOS #128](https://github.com/SquareWaveSystems/squarebox/issues/128),
[Windows/Git Bash #129](https://github.com/SquareWaveSystems/squarebox/issues/129),
[Dev Containers/Codespaces #130](https://github.com/SquareWaveSystems/squarebox/issues/130),
[demo regeneration #104](https://github.com/SquareWaveSystems/squarebox/issues/104), and
[physical Candidate qualification #131](https://github.com/SquareWaveSystems/squarebox/issues/131).
Optional primary-Linux follow-up: [#126](https://github.com/SquareWaveSystems/squarebox/issues/126).
Final Candidate and publication: [#131](https://github.com/SquareWaveSystems/squarebox/issues/131).

## Linux desktop — Docker
## Optional primary-Linux follow-up

- [ ] Fresh Bash installer: launch, interactive setup, exit, resume, rebuild, uninstall
- [ ] Existing v1.1 Managed home upgrade: no repeated prompts; Selections reconcile
Expand All @@ -29,77 +26,12 @@ Qualification issues: [Linux desktop #126](https://github.com/SquareWaveSystems/
- [ ] Purge refuses an unrelated directory/container/image/volume with a colliding name
- [ ] Docker daemon unavailable during uninstall produces a clear nonzero partial-cleanup result

## Rootless Podman and SELinux

- [ ] Fedora with enforcing SELinux: Workspace/SSH/system labels remain unchanged and the documented `label=disable` tradeoff is acceptable
- [ ] Rootless keep-id mapping: host and Box create mutually writable files
- [ ] Rootless Podman rejects PUID/PGID values that differ from the invoking host identity
- [ ] Stop/start, replacement, rebuild, and purge honor the same Install identity
- [ ] SSH agent and read-only SSH fallback both work

## macOS — Docker Desktop

- [ ] Fresh install and upgrade with paths containing spaces
- [ ] SSH agent forwarding works; fallback private-key mount remains read-only
- [ ] Missing `/etc/localtime` uses the documented timezone fallback
- [ ] Rebuild and purge preserve/remove only recorded Managed resources

## Windows — native PowerShell 7 and Docker Desktop

- [ ] Fresh `install.ps1`, Box launch, PowerShell rebuild, and `uninstall.ps1` remain on the same native adapter
- [ ] Shell functions work in ConsoleHost and VS Code PowerShell hosts
- [ ] Install from one PowerShell host and uninstall from another removes the intended integration
- [ ] Git identity contains only name/email; host credential/signing configuration is not mounted
- [ ] Native PowerShell mounts `%USERPROFILE%\.ssh` read-only and does not claim `SSH_AUTH_SOCK` forwarding
- [ ] Paths containing spaces and non-ASCII characters survive every lifecycle action
- [ ] Install identity access is limited by the current user's Windows install-directory ACL
- [ ] Native PowerShell rejects a Git Bash-created Install identity without modifying its resources or profiles

## Git Bash compatibility

- [ ] Bash integration uses the MSYS home while the Install identity uses the Windows user home
- [ ] SSH agent socket translation works with Docker Desktop path conversion disabled
- [ ] Git Bash install, rebuild, and uninstall consume the Bash-created identity only
- [ ] Git Bash rejects a native PowerShell-created Install identity without modifying its resources or shell integration

## Interactive setup

- [ ] Cancel each multi-select and confirm the prior Selection is preserved
- [ ] Deliberately choose an empty Selection and confirm it is saved distinctly from cancel
- [ ] Fail one assistant install and confirm aliases target the first successfully observed assistant
- [ ] GitHub device authentication succeeds; decline marker and credentials survive Box replacement
- [ ] Claude, Copilot, Gemini, Codex, OpenCode, Pi, and Oh My Pi launch after installation
- [ ] Copilot uses the supported `copilot` command
- [ ] Bash initializes Starship, Zoxide, fzf keybindings/completion, aliases, and mise shims
- [ ] Zsh and Fish initialize Starship, Zoxide, the `fzf`/`ff` command path, aliases, and mise shims
- [ ] Section-only AI/editor/TUI reruns refresh Fish derived configuration
- [ ] A non-first default editor survives Box replacement and noninteractive reconciliation
- [ ] Explicit `set -g mouse off` remains respected during tmux migration
- [ ] Herdr launches after installation and survives Box replacement from the Managed home

## Interactive tools

- [ ] `lazygit`, `yazi`, `elio`, `gh-dash`, and Helix (`hx`) render and accept input
- [ ] `gum` and `fzf` interactive modes work with the host terminal
- [ ] tmux and Zellij keybindings match the documentation
- [ ] Neovim/LazyVim first launch completes without wedging dpkg under the timezone mount

## Dev Containers and Codespaces

- [ ] VS Code Dev Containers builds the tagged Candidate source, runs `postCreateCommand`, and reopens successfully (source rebuild is not byte-identical to the published image)
- [ ] `gh codespace ssh` attaches to a Codespace built from the custom Squarebox image
- [ ] GitHub Codespaces runs the noninteractive defaults and preserves independent successful Selections after one section fails
- [ ] Custom `SQUAREBOX_DC_MULTIPLEXERS` defaults are observed; an explicit empty value opts out; and an existing multiplexer Selection takes precedence on rebuild
- [ ] Rebuilds preserve Workspace Selection state and Managed-home authentication/toolchains

## Candidate promotion

- [ ] Pull the published Candidate by digest on real amd64 hardware
- [ ] Pull the same Candidate digest on real arm64 hardware
- [ ] Verify the version file, MOTD, Git source ref, and `release.json` agree
- [ ] Confirm the active release-tag ruleset rejects update/deletion of the `v*` tag and that its peeled remote commit still equals the Candidate source SHA
- [ ] Download the non-discoverable draft assets with authenticated `gh release download` and verify their hashes and Cosign identity signature
- [ ] Run fresh and upgraded Compose flows against the digest
- [ ] Run the automated Candidate suite and confirm all required Evidence passes
- [ ] Confirm stable installers cannot discover the Release until all gates pass
- [ ] Record the qualification evidence and explicit promote/no-promote decision in [issue #131](https://github.com/SquareWaveSystems/squarebox/issues/131)
- [ ] Approve the waiting `stable-release` environment deployment to publish the tested Candidate without rebuilding different image bytes
Expand Down