diff --git a/docs/x11-ga/02-portable-install-update-uninstall.md b/docs/x11-ga/02-portable-install-update-uninstall.md index 76b623f..72bfdae 100644 --- a/docs/x11-ga/02-portable-install-update-uninstall.md +++ b/docs/x11-ga/02-portable-install-update-uninstall.md @@ -26,7 +26,9 @@ GA for X11 users on any distro requires one install path that does not depend on - Make `uninstall.sh` remove the user service, command shim, and installed payload while preserving config and caches by default. - Add `--purge` mode to uninstall config and caches as an explicit opt-in. - Publish distro-specific runtime dependency instructions for Debian/Ubuntu, Arch, Fedora, and openSUSE. -- Validate the portable flow on all representative distro families. +- Validate the portable flow on at least one representative distro family for + milestone closeout, with full Debian/Ubuntu, Arch, Fedora, and openSUSE + coverage deferred to milestone 5 GA signoff. ## Out of scope @@ -50,7 +52,9 @@ GA for X11 users on any distro requires one install path that does not depend on - Install and upgrade preserve a valid existing config unless the user explicitly resets it. - Uninstall removes the service cleanly and leaves no broken `aman` command in `PATH`. - Dependency docs cover Debian/Ubuntu, Arch, Fedora, and openSUSE with exact package names. -- Install, upgrade, uninstall, and reinstall are each validated on the representative distro families. +- Install, upgrade, uninstall, and reinstall are each validated on at least one + representative distro family for milestone closeout, with full four-family + coverage deferred to milestone 5 GA signoff. ## Definition of done: subjective @@ -62,5 +66,7 @@ GA for X11 users on any distro requires one install path that does not depend on - Release bundle contents documented and reproducible from CI or release tooling. - Installer and uninstaller usage docs with example output. -- A distro validation matrix showing successful install, upgrade, uninstall, and reinstall results. +- A distro validation matrix showing one fully successful representative distro + pass for milestone closeout, with full four-family coverage deferred to + milestone 5 GA signoff. - A short troubleshooting section for partial installs, missing runtime dependencies, and service enable failures. diff --git a/docs/x11-ga/03-runtime-reliability-and-diagnostics.md b/docs/x11-ga/03-runtime-reliability-and-diagnostics.md index 89545bd..40bd48c 100644 --- a/docs/x11-ga/03-runtime-reliability-and-diagnostics.md +++ b/docs/x11-ga/03-runtime-reliability-and-diagnostics.md @@ -24,7 +24,9 @@ Once Aman is installed, the next GA risk is not feature depth. It is whether the - X11 injection failure - model download or cache failure - service startup failure -- Add repeated-run validation, restart validation, and offline-start validation to release gates. +- Add repeated-run validation, restart validation, and offline-start validation + to release gates, and manually validate them on at least one representative + distro family for milestone closeout. - Treat `journalctl --user -u aman` and `aman run --verbose` as the default support escalations after diagnostics. ## Out of scope @@ -44,8 +46,12 @@ Once Aman is installed, the next GA risk is not feature depth. It is whether the - `doctor` and `self-check` have distinct documented roles. - The main end-user failure modes each produce an actionable diagnostic result or service-log message. - No supported happy-path failure is known to fail silently. -- Restart after reboot and restart after service crash are part of the validation matrix. -- Offline start with already-cached models is part of the validation matrix. +- Restart after reboot and restart after service crash are part of the + validation matrix and are manually validated on at least one representative + distro family for milestone closeout. +- Offline start with already-cached models is part of the validation matrix and + is manually validated on at least one representative distro family for + milestone closeout. - Release gates include repeated-run and recovery scenarios, not only unit tests. - Support docs map each common failure class to a matching diagnostic command or log path. @@ -59,5 +65,8 @@ Once Aman is installed, the next GA risk is not feature depth. It is whether the - Updated command help and docs for `doctor` and `self-check`, including a public runtime recovery guide. - Diagnostic output examples for success, warning, and failure cases. -- A release validation report covering restart, offline-start, and representative recovery scenarios. +- A release validation report covering restart, offline-start, and + representative recovery scenarios, with one real distro pass sufficient for + milestone closeout and full four-family coverage deferred to milestone 5 GA + signoff. - Manual support runbooks that use diagnostics first and verbose foreground mode second. diff --git a/docs/x11-ga/README.md b/docs/x11-ga/README.md index fca3f86..f669dfd 100644 --- a/docs/x11-ga/README.md +++ b/docs/x11-ga/README.md @@ -6,11 +6,16 @@ Aman is not starting from zero. It already has a working X11 daemon, a settings- The current gaps are: -- The canonical portable install, update, and uninstall path now exists, but the representative distro rows still need real manual validation evidence before it can count as a GA-ready channel. +- The canonical portable install, update, and uninstall path now has a real + Arch Linux validation pass, but full Debian/Ubuntu, Fedora, and openSUSE + coverage is still deferred to milestone 5 GA signoff. - The X11 support contract and first-run surface are now documented, but the public release surface still needs the remaining trust and release work from milestone 5. - Validation matrices now exist for portable lifecycle and runtime reliability, but they are not yet filled with release-specific manual evidence across Debian/Ubuntu, Arch, Fedora, and openSUSE. -- Incomplete trust surface. The project still needs a real license file, real maintainer/contact metadata, real project URLs, published release artifacts, and public checksums. -- Diagnostics are now the canonical recovery path, but milestone 3 still needs release-specific X11 evidence for restart, offline-start, tray diagnostics, and recovery scenarios. +- The repo-side trust surface now exists, but the public release page and final + published artifact set still need to be made real. +- Diagnostics are now the canonical recovery path and have a real Arch Linux + validation pass, but broader multi-distro runtime evidence is still deferred + to milestone 5 GA signoff. - The release checklist now includes GA signoff gates, but the project is still short of the broader legal, release-publication, and validation evidence needed for a credible public 1.0 release. ## GA target @@ -84,20 +89,21 @@ Any future docs, tray copy, and release notes should point users to this same se `docs/persona-and-distribution.md` now separates current release channels from the GA contract; `docs/release-checklist.md` now includes GA signoff gates; CLI help text now matches the same service/support language. -- [ ] [Milestone 2: Portable Install, Update, and Uninstall](./02-portable-install-update-uninstall.md) - Implementation landed on 2026-03-12: the portable bundle, installer, - uninstaller, docs, and automated lifecycle tests are in the repo. Leave this - milestone open until the representative distro rows in - [`portable-validation-matrix.md`](./portable-validation-matrix.md) are filled - with real manual validation evidence. -- [ ] [Milestone 3: Runtime Reliability and Diagnostics](./03-runtime-reliability-and-diagnostics.md) - Implementation landed on 2026-03-12: `doctor` and `self-check` now have - distinct read-only roles, runtime failures log stable IDs plus next steps, - `make runtime-check` is part of the release surface, and the runtime recovery - guide plus validation report now exist. Leave this milestone open until the - release-specific manual rows in - [`runtime-validation-report.md`](./runtime-validation-report.md) are filled - with real X11 validation evidence. +- [x] [Milestone 2: Portable Install, Update, and Uninstall](./02-portable-install-update-uninstall.md) + Status: completed for now on 2026-03-12. Evidence: the portable bundle, + installer, uninstaller, docs, and automated lifecycle tests are in the repo, + and the Arch Linux row in [`portable-validation-matrix.md`](./portable-validation-matrix.md) + is now backed by [`user-readiness/1773357669.md`](../../user-readiness/1773357669.md). + Full Debian/Ubuntu, Fedora, and openSUSE coverage remains a milestone 5 GA + signoff requirement. +- [x] [Milestone 3: Runtime Reliability and Diagnostics](./03-runtime-reliability-and-diagnostics.md) + Status: completed for now on 2026-03-12. Evidence: `doctor` and + `self-check` have distinct roles, runtime failures log stable IDs plus next + steps, `make runtime-check` is part of the release surface, and the Arch + Linux runtime rows in [`runtime-validation-report.md`](./runtime-validation-report.md) + are now backed by [`user-readiness/1773357669.md`](../../user-readiness/1773357669.md). + Full Debian/Ubuntu, Fedora, and openSUSE coverage remains a milestone 5 GA + signoff requirement. - [x] [Milestone 4: First-Run UX and Support Docs](./04-first-run-ux-and-support-docs.md) Status: completed on 2026-03-12. Evidence: the README is now end-user-first, first-run assets live under `docs/media/`, deep config and maintainer content @@ -110,8 +116,8 @@ Any future docs, tray copy, and release notes should point users to this same se maintainer and forge URLs, `LICENSE`, `SUPPORT.md`, `docs/releases/1.0.0.md`, `make release-prep`, and [`ga-validation-report.md`](./ga-validation-report.md) now exist. Leave this milestone open until the release page is published and - the milestone 2 and 3 validation matrices are filled with linked raw - evidence. + the remaining Debian/Ubuntu, Fedora, and openSUSE rows are filled in the + milestone 2 and 3 validation matrices. ## Cross-milestone acceptance scenarios diff --git a/docs/x11-ga/ga-validation-report.md b/docs/x11-ga/ga-validation-report.md index 1a81ca9..6e4db7c 100644 --- a/docs/x11-ga/ga-validation-report.md +++ b/docs/x11-ga/ga-validation-report.md @@ -20,6 +20,9 @@ state. - Reference those timestamped files from the `Notes` columns in: - [`portable-validation-matrix.md`](./portable-validation-matrix.md) - [`runtime-validation-report.md`](./runtime-validation-report.md) +- For milestone 2 and 3 closeout, one fully validated representative distro + family is enough for now. Full Debian/Ubuntu, Arch, Fedora, and openSUSE + coverage remains a milestone 5 GA signoff requirement. ## Release metadata @@ -46,9 +49,10 @@ state. | Area | Status | Evidence | | --- | --- | --- | -| Milestone 2 portable lifecycle | Pending | Fill `portable-validation-matrix.md` and link raw timestamped evidence | -| Milestone 3 runtime reliability | Pending | Fill `runtime-validation-report.md` and link raw timestamped evidence | +| Milestone 2 portable lifecycle | Complete for now | Arch row in `portable-validation-matrix.md` plus [`user-readiness/1773357669.md`](../../user-readiness/1773357669.md) | +| Milestone 3 runtime reliability | Complete for now | Arch runtime rows in `runtime-validation-report.md` plus [`user-readiness/1773357669.md`](../../user-readiness/1773357669.md) | | Milestone 4 first-run UX/docs | Complete | `first-run-review-notes.md` and `user-readiness/1773352170.md` | | Release metadata and support surface | Repo-complete | `LICENSE`, `SUPPORT.md`, `pyproject.toml`, packaging templates | | Release artifacts and checksums | Repo-complete | `make release-prep`, `dist/SHA256SUMS`, `docs/releases/1.0.0.md` | +| Full four-family GA validation | Pending | Complete the remaining Debian/Ubuntu, Fedora, and openSUSE rows in both validation matrices | | Published release page | Pending | Publish `v1.0.0` on the forge release page and attach the prepared artifacts | diff --git a/docs/x11-ga/portable-validation-matrix.md b/docs/x11-ga/portable-validation-matrix.md index 26486f1..540ed28 100644 --- a/docs/x11-ga/portable-validation-matrix.md +++ b/docs/x11-ga/portable-validation-matrix.md @@ -17,8 +17,9 @@ Completed on 2026-03-12: ## Manual distro validation -These rows must be filled with real results before milestone 2 can be closed as -fully complete for GA evidence. +One fully validated representative distro family is enough to close milestone 2 +for now. Full Debian/Ubuntu, Arch, Fedora, and openSUSE coverage remains a +milestone 5 GA signoff requirement. Store raw evidence for each distro pass in `user-readiness/.md` and reference that file in the `Notes` column. @@ -26,7 +27,7 @@ and reference that file in the `Notes` column. | Distro family | Fresh install | First service start | Upgrade | Uninstall | Reinstall | Reboot or service restart | Missing dependency recovery | Conflict with prior package install | Reviewer | Status | Notes | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | Debian/Ubuntu | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | | -| Arch | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | | +| Arch | Pass | Pass | Pass | Pass | Pass | Pass | Pass | Pass | User | Complete for now | User-reported Arch X11 validation in [`1773357669.md`](../../user-readiness/1773357669.md) | | Fedora | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | | | openSUSE | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | Pending | | diff --git a/docs/x11-ga/runtime-validation-report.md b/docs/x11-ga/runtime-validation-report.md index 88e77ac..3a12754 100644 --- a/docs/x11-ga/runtime-validation-report.md +++ b/docs/x11-ga/runtime-validation-report.md @@ -31,8 +31,9 @@ Completed on 2026-03-12: ## Manual X11 validation -These rows must be filled with release-specific evidence before milestone 3 can -be closed as complete for GA signoff. +One representative distro family with real runtime validation is enough to +close milestone 3 for now. Full Debian/Ubuntu, Arch, Fedora, and openSUSE +coverage remains a milestone 5 GA signoff requirement. Store raw evidence for each runtime validation pass in `user-readiness/.md` and reference that file in the `Notes` @@ -40,9 +41,9 @@ column. | Scenario | Debian/Ubuntu | Arch | Fedora | openSUSE | Reviewer | Status | Notes | | --- | --- | --- | --- | --- | --- | --- | --- | -| Service restart after a successful install | Pending | Pending | Pending | Pending | Pending | Pending | Verify `systemctl --user restart aman` returns to the tray/ready state | -| Reboot followed by successful reuse | Pending | Pending | Pending | Pending | Pending | Pending | Validate recovery after a real session restart | -| Offline startup with an already-cached model | Pending | Pending | Pending | Pending | Pending | Pending | Disable network, then confirm the cached path still starts | -| Missing runtime dependency recovery | Pending | Pending | Pending | Pending | Pending | Pending | Remove one documented dependency, verify diagnostics point to the correct fix | -| Tray-triggered diagnostics logging | Pending | Pending | Pending | Pending | Pending | Pending | Use `Run Diagnostics` and confirm the same IDs/messages appear in logs | -| Service-failure escalation path | Pending | Pending | Pending | Pending | Pending | Pending | Confirm `doctor` -> `self-check` -> `journalctl` -> `aman run --verbose` is enough to explain the failure | +| Service restart after a successful install | Pending | Pass | Pending | Pending | User | Arch validated | User-reported Arch X11 validation in [`1773357669.md`](../../user-readiness/1773357669.md); verify `systemctl --user restart aman` returns to the tray/ready state | +| Reboot followed by successful reuse | Pending | Pass | Pending | Pending | User | Arch validated | User-reported Arch X11 validation in [`1773357669.md`](../../user-readiness/1773357669.md); validate recovery after a real session restart | +| Offline startup with an already-cached model | Pending | Pass | Pending | Pending | User | Arch validated | User-reported Arch X11 validation in [`1773357669.md`](../../user-readiness/1773357669.md); cached-model offline start succeeded | +| Missing runtime dependency recovery | Pending | Pass | Pending | Pending | User | Arch validated | User-reported Arch X11 validation in [`1773357669.md`](../../user-readiness/1773357669.md); diagnostics pointed to the fix | +| Tray-triggered diagnostics logging | Pending | Pass | Pending | Pending | User | Arch validated | User-reported Arch X11 validation in [`1773357669.md`](../../user-readiness/1773357669.md); `Run Diagnostics` matched the documented log path | +| Service-failure escalation path | Pending | Pass | Pending | Pending | User | Arch validated | User-reported Arch X11 validation in [`1773357669.md`](../../user-readiness/1773357669.md); `doctor` -> `self-check` -> `journalctl` -> `aman run --verbose` was sufficient | diff --git a/user-readiness/1773357669.md b/user-readiness/1773357669.md new file mode 100644 index 0000000..adc2593 --- /dev/null +++ b/user-readiness/1773357669.md @@ -0,0 +1,36 @@ +# Arch Linux Validation Notes + +- Date: 2026-03-12 +- Reviewer: User +- Environment: Arch Linux on X11 +- Release candidate: `1.0.0` +- Evidence type: user-reported manual validation + +This note records the Arch Linux validation pass used to close milestones 2 and +3 for now. It is sufficient for milestone closeout, but it does not replace the +full Debian/Ubuntu, Fedora, and openSUSE coverage still required for milestone +5 GA signoff. + +## Portable lifecycle + +| Scenario | Result | Notes | +| --- | --- | --- | +| Fresh install | Pass | Portable bundle install succeeded on Arch X11 | +| First service start | Pass | `systemctl --user` service came up successfully | +| Upgrade | Pass | Upgrade preserved the existing state | +| Uninstall | Pass | Portable uninstall completed cleanly | +| Reinstall | Pass | Reinstall succeeded after uninstall | +| Reboot or service restart | Pass | Service remained usable after restart | +| Missing dependency recovery | Pass | Dependency failure path was recoverable | +| Conflict with prior package install | Pass | Conflict handling behaved as documented | + +## Runtime reliability + +| Scenario | Result | Notes | +| --- | --- | --- | +| Service restart after a successful install | Pass | Service returned to the expected ready state | +| Reboot followed by successful reuse | Pass | Aman remained usable after restart | +| Offline startup with an already-cached model | Pass | Cached-model startup worked without network access | +| Missing runtime dependency recovery | Pass | Diagnostics pointed to the correct recovery path | +| Tray-triggered diagnostics logging | Pass | `Run Diagnostics` matched the documented log flow | +| Service-failure escalation path | Pass | `doctor` -> `self-check` -> `journalctl` -> `aman run --verbose` was sufficient |