Project-Kiln/docs/spec/06_DEVELOPMENT_ROADMAP_AND_ACCEPTANCE.md

## 14. Development and validation strategy

Development will use a layered workflow: fast, repeatable testing in virtual machines, followed by targeted bare-metal validation for behavior that virtualization cannot represent accurately. This keeps iteration safe without pretending a virtual GPU can prove gaming performance.

### 14.1 Primary development environment

- QEMU/KVM managed through libvirt is the primary environment for boot, installer, service, networking, package, and recovery testing.
- A powered-off libvirt guest consumes no guest RAM or CPU; only negligible host management services remain active.
- ISO and root-filesystem builds may run directly on the host, in a container, or in a dedicated build VM, provided the process remains reproducible.
- VirtualBox is not a primary project dependency. It may be used for an additional compatibility check, but it offers no useful substitute for bare-metal graphics testing.
- GPU passthrough is optional and must not become a prerequisite for development or release validation.

### 14.2 Validation stages

| **Stage**   | **Environment**                     | **Purpose**                                                                                          |
|-------------|-------------------------------------|------------------------------------------------------------------------------------------------------|
| Build       | Host, container, or build VM        | Produce the package set, root filesystem, and ISO reproducibly.                                      |
| Fast boot   | Disposable libvirt VM               | Validate the bootloader, initramfs, installer flow, networking, services, and TTY behavior.          |
| Destructive | Snapshot-backed libvirt VM          | Exercise failed upgrades, rollback, recovery, repartitioning, and installer edge cases safely.       |
| Hardware    | Dedicated spare SSD or test machine | Validate GPU drivers, Bluetooth, controllers, audio, displays, suspend, and real device permissions. |
| Performance | Bare metal                          | Measure frame pacing, latency, Gamescope, GameMode, Proton behavior, thermals, and system overhead.  |

### 14.3 Bare-metal isolation and safety

- Do not use the primary EndeavourOS installation as the distro install target during routine development.
- Prefer a dedicated physical SSD for test installations and select it through UEFI, keeping production and test bootloaders isolated.
- The first reference install uses a dedicated external USB drive on the Ryzen 9 7900X3D/RTX 5070 desktop. Installer tests must resolve that exact device by stable identity and display model, capacity, transport, and destructive target confirmation; never select it through changing `/dev/sdX` order alone.
- Run early installer tests only against disposable virtual disks or physical disks whose contents may be destroyed.
- Keep game libraries separate from replaceable system state where practical so repeated installs do not require repeated downloads.
- Automate VM creation and smoke tests as the project matures; a clean guest should be reproducible from source rather than maintained as a precious snowflake.

### 14.4 Incremental development and test gates

- Implement one vertical capability at a time and verify it before starting the next dependent capability.
- Avoid broad simultaneous implementation across providers or system layers; narrow failures are easier to diagnose and revert.
- Every task must state its scope, exclusions, affected components, acceptance criteria, and exact verification commands before implementation begins.
- A capability advances through four gates: unit tests for pure logic and parsers; contract tests for schemas and adapter behavior; isolated integration tests using fixtures or temporary state; and real-system or VM acceptance tests where applicable.
- Work may proceed in parallel only when tasks are demonstrably independent and do not edit the same files or depend on unsettled contracts.
- Failures at any gate block the next dependent phase. Exceptions require an explicit documented decision rather than silent scope expansion.
- Rust 1.97.1 is both the minimum supported compiler and the reviewed local toolchain. The complete local gate rejects any different active compiler before compilation.
- Every internal path dependency declares an exact compatible version as well as its path. Dependency changes update the lockfile, source inventory where applicable, license policy, and advisory/license/source audit evidence in the same task.
- Do not preapprove dependency licenses that are not present. Add a license to the allowlist only with the reviewed dependency that requires it.
- Each real-system gate records the exact package versions, hardware/driver/kernel tuple, fixture or test account, commands, expected result, observed result, logs, and cleanup. "Launch one game" without a reproducible evidence record is not an acceptance test.
- Networked-provider tests use dedicated non-primary test accounts where provider terms and practical setup permit. Fixtures contain no live tokens, personal library dumps, or redistributable proprietary content.

### 14.5 Work Mode and local execution split

- ChatGPT Work Mode is used for specification maintenance, architecture, schemas, fixtures, task definitions, lightweight scaffolding, reviews, and handoff preparation.
- Compilation, dependency downloads, full Rust test suites, Clippy, Arch package builds, VM execution, launcher inspection, game launching, graphical-session tests, controller tests, Archiso generation, and performance benchmarks run locally through Codex CLI unless a later lightweight check is clearly cheaper here.
- Work Mode tasks must avoid unnecessary CPU, RAM, disk, and dependency use. Resource-heavy validation belongs on the user's desktop or disposable VM, where failures and resource pressure are observable.
- Phase 0 completion is the default handoff point for implementation to local Codex CLI. Keep Work Mode involved for specification maintenance, architecture and schema review, decision clarification, and evidence-backed corrections; use the repository-root `AGENTS.md` and bounded handoff briefs to preserve those constraints locally.

## 15. Delivery roadmap

| **Phase** | **Focus**       | **Exit condition**                                                                             |
|-----------|-----------------|------------------------------------------------------------------------------------------------|
| 0         | Repository and evidence baseline | Create the Rust workspace and component boundaries using the approved temporary, repository-local Kiln family; establish a rename manifest and automated placeholder scan; pin the local toolchain and lockfile; configure formatting, linting, tests, a complete local verification entrypoint, dependency/license/security audits, release/version policy, ADRs, fixture rules, threat model, package/source inventory, test-evidence template, requirement-to-test traceability matrix, and supported-platform decision record. Final collision-checked project/package/crate/executable/configuration/IPC namespaces are required before any public, published, or globally installed artifact, but do not block private implementation. No provider implementation begins before the remaining baseline passes. |
| 1         | Contracts       | Define and aggressively test versioned game/installation identity, the durable installation registry, store/adapter/configuration-owner/execution-backend separation, provider and runtime interfaces, JSON records, launch plans, lifecycle confidence, structured errors, and configuration precedence/provenance using a mock adapter. |
| 2         | Native vertical slice | Complete native discovery, normalization, search, dry-run planning, launch execution, logging, and failure handling before beginning Steam execution. |
| 3         | Steam discovery | Parse Steam installation and library state through read-only, fixture-driven tests; normalize installed games without launching them. |
| 4         | Steam execution | Generate and verify Steam launch plans, then launch representative native and Proton titles through the common contract. |
| 5         | Minimal session proof | Choose the prototype terminal and login/session mechanism; define logind seat/TTY ownership, D-Bus and systemd-user behavior; start Labwc and Xwayland, launch native and Steam/Proton games, return cleanly, and prove compositor/initial-shell failures cannot trap the user in a graphical restart loop. This proves architecture, not the complete session product. |
| 6         | Controllers     | Validate at least one Xbox-family and one PlayStation-family controller over both USB and Bluetooth, including hotplugging, reboot reconnection, structured diagnostics, BlueZ automation, and the Bluetui management path; verify optional Blueman separately and prove a controller-accessible session/recovery action without relying on a running game. Record the exact tested controller revisions before execution. |
| 7         | Additional providers and runtimes | Add Lutris, then separate Epic/Legendary, GOG/GOGDL, and Amazon/Nile capability adapters, followed by custom Windows manifests and the UMU runtime, one at a time; each must pass its own four test gates before the next begins. Whether an adapter reuses Heroic state or owns independent helper configuration is decided by its prototype evidence, not assumed globally. |
| 8         | Session hardening | Harden the proven compositor architecture into Lean, Ready, Frontend, Custom, and TTY policies; complete launcher switching, controller session actions, Gamescope nesting, Xorg/TTY fallbacks, audio, portals, multi-monitor behavior, permissions, cleanup, and crash recovery. Reference or reuse ChimeraOS gamescope-session only for dedicated frontend-session paths where validated. |
| 9         | Performance     | Benchmark tuning changes against minimal Arch and a conventional Arch desktop.                 |
| 10        | Packaging       | Create modular Arch packages and hardware profiles, including optional ProtonPlus/Blueman desktop tools and an optional Btrfs Snapper recovery profile with pacman hooks. |
| 11        | Installer       | After the base-Arch package set and configuration are stable, create an Archiso profile and an archinstall-based guided path using a maintained project profile/configuration plus a pinned local plugin or custom script only where required. Do not reimplement archinstall's storage, encryption, account, or base-install functions, and never fetch executable installer plugins from an unpinned URL. |
|           | **Version 1 release boundary** | Version 1 may ship when phases 0–11 and the version 1 acceptance criteria pass; phases 12–15 are post-v1 work. |
| 12        | Frontend adapter | Integrate unmodified upstream Pegasus through generated metadata and backend-owned launch commands, using the session policies completed for version 1. |
| 13        | Public API       | Stabilize schemas, structured errors, compatibility policy, local IPC, events, and an example external client if real frontend needs justify a service. |
| 14        | Future UI and input | Evaluate OpenGamepadUI, optional InputPlumber integration, upstream contributions, a small Pegasus patch set or fork, or a first-party OS frontend using evidence from the reference integrations. |
| 15        | Vendor launchers | Add Battle.net, EA App, Ubisoft Connect, Rockstar, and similar clients individually through the managed-prefix architecture; publish tested/experimental/unsupported status rather than promising universal compatibility. |

## 16. Version 1 acceptance criteria

- Normal gaming mode starts a minimal graphical shell whose default visible interface is a fullscreen terminal, without starting a conventional DE.
- Lean, Ready, Frontend, Custom, and TTY selections can be changed after installation; each starts only its declared components and survives logout/reboot according to its documented persistence policy.
- A true TTY-only recovery target works independently of the graphical shell.
- An installed game can be found and launched by name.
- Steam, Lutris, native, Epic, GOG, and Amazon provider paths each discover and launch at least one representative installed title, or a store is explicitly downgraded from v1 through a recorded scope decision before release. Passing one Heroic-managed store does not stand in for the other two.
- At least one custom Windows game launches through the UMU runtime while retaining its custom or store identity.
- Representative USB and Bluetooth controllers work in Gamescope and fallback sessions; Bluetui can pair, trust, connect, disconnect, and forget a representative Bluetooth controller without a desktop settings panel.
- The published controller matrix names exact representative devices and records kernel/driver, USB/Bluetooth mode, hotplug, reboot reconnection, SDL mapping, Steam Input interaction, session/recovery action, and supported advanced features; unsupported features are reported honestly.
- The system returns to the functioning session shell after successful launch, game exit, and common launch failures without reconstructing the graphical environment.
- Lean starts heavyweight provider interfaces only when needed; Ready can autostart and rapidly switch among at least Steam, Heroic, and the terminal.
- Keyboard switching works on every supported compositor path. A controller can reach the terminal or recovery action even when a frontend or game captures ordinary navigation input. Programmatic focus commands return an explicit unsupported result on compositors without a tested focus API.
- Each v1 Epic, GOG, and Amazon path demonstrates whether it can launch through a validated helper without Heroic's Electron interface; any path that still requires Heroic must report `client-required` honestly and preserve configuration ownership.
- UMU runtime assets can be prefetched, a warm cached launch succeeds without network access, and an uncached offline launch fails promptly with a clear actionable error.
- GameMode remains requested for the actual game lifetime in representative direct, Steam, and non-Steam provider launches; lower-confidence lifecycle tracking alone must not hold or release the request.
- Gamescope launches use MangoApp for their supported HUD path, while fallback/non-Gamescope launches validate MangoHud separately.
- Safe mode can bypass Gamescope overlays and optional tuning.
- A dry-run launch plan provides enough information to reproduce and diagnose the launch.
- Performance tests use a frozen workload, hardware/driver/kernel tuple, warm-up policy, repeated samples, variance reporting, and predeclared regression budgets. Statistically meaningful regressions beyond those budgets block the affected tuning/profile unless an explicit tradeoff decision records the benefit.
- A clean supported installation completes an ordinary full `pacman -Syu` plus a project-package update and still boots, enters the session, discovers games, and launches the smoke-test titles. A deliberately incompatible VM transaction produces actionable diagnostics and follows the documented downgrade or optional snapshot-recovery path.
- Supported audio and networking paths are tested from a clean install, including PipeWire/WirePlumber startup, one declared game-audio output path, NetworkManager reconnect after reboot, and offline launch behavior for cached and uncached provider/runtime cases.
- No project component requires telemetry or root execution for ordinary game launches.
- A clean-install listener inventory contains no undocumented project-owned TCP/UDP service; any local IPC socket has owner-only access and rejects unauthorized peers and oversized/malformed requests.
- Game-lifetime tracking drives temporary performance settings, sleep inhibition, status, logging, and cleanup at the strongest confidence each provider permits; provider clients are not automatically closed after play.
- Public build records identify repository state, exact package/project versions, hashes, and build inputs sufficiently to reconstruct an equivalent installation; bit-for-bit reproducibility is claimed only after independent verification.
- Project packages and releases are signed, include source/license provenance and an SBOM, and do not execute untrusted metadata through interpolated shell commands.
- Adversarial tests cover malformed/oversized manifests, invalid encodings, shell metacharacters, Desktop Entry field codes, environment injection, symlink/path traversal, concurrent file changes, hostile artwork paths, log redaction, and local IPC permissions where applicable.
- The release matrix states the supported CPU architecture, firmware/boot mode, GPU/driver families, display arrangements, audio path, controller classes, and filesystem profiles. Untested combinations are labeled untested rather than implied supported.
- The v1 matrix is explicitly x86_64/UEFI and single-local-user. AMD and NVIDIA rows are release-blocking; Intel rows are best-effort. Multi-user isolation is a documented post-v1 capability and v1 tests ensure no project state depends on a fixed username, UID, or hard-coded home directory.
- Every Required requirement ID maps to an owning roadmap phase and at least one automated or manual evidence record; release review fails if a required item is orphaned, deferred, or covered only by prose.
- The archinstall-based guided path installs a bootable system onto a disposable virtual disk, records its selected profile, handles a failed installation without corrupting unrelated disks, and produces the same project package/configuration state as the documented base-Arch path.
- If the optional Btrfs recovery profile is offered at v1, its Snapper and pacman-hook snapshots, retention behavior, rollback instructions, and selected boot integration pass destructive VM tests; failure of that optional profile blocks advertising it, not the filesystem-neutral installation path.