v0.1 Release Candidate — process + QA build-out design

v0.1 Release Candidate — process + QA build-out design

Date: 2026-07-14 · Status: approved by Chris (approach: Full QA build-out; tracking: docs/RELEASE-0.1.md; scope exclusions confirmed)

Problem

Issue discovery for the 0.1 launch is ad-hoc: Chris and Toby find “little issues” by playing, one at a time. The known-owed work is scattered across CLAUDE.md ⚠️ items, NEXT_TASKS.md, two overnight-review docs (07-08: 146 findings; 07-13: open triage), and the roadmap memory. The three devices run three different builds (Apple TV 165, Mac 162, iPhone 147) and four merged features have never been deployed, so every playtest tests a different game.

The recurring bug class (Disruptor slow inert, Halo Chain buff never applied, Wyrm 20× kill rewards) is code that runs without erroring but silently does nothing or the wrong amount — invisible to unit tests nobody thought to write, but detectable by measurement at scale.

Goal & exit criteria

Ship a v0.1 release candidate to TestFlight. The RC is DONE when ALL of:

1. docs/RELEASE-0.1.md has zero open RC-blockers.
2. Soak harness clean across the full config sweep (no invariant failures, no unexplained telemetry anomalies).
3. Full GUT suite green + test-count guard passes + determinism baseline holds (re-pinned where a deliberate change requires it).
4. Screenshot sweep shows no unexplained visual regressions vs baseline.
5. Structured playtest script passed on all three device classes (Mac, Apple TV, iPhone), including the 2-controller co-op checklist.
6. ADAPTIVE_QUALITY := true re-enabled and verified live on Apple TV under load.
7. TestFlight build approved and distributed to the Friends & Family group; a few days’ soak with only showstoppers blocking.

0.1 scope (confirmed by Chris)

Out: networked MP (stays unmerged in its worktree); the dimension-choice popup’s 4 open design questions (current behaviour ships as-is); bespoke elite powers for the ~12 generic-elite enemies; normal-mapped 2D hull lighting. All are 0.2 candidates.

In: everything currently on main, polished; the QA tooling below; the release gates.

Phase 0 — Freeze & consolidate (½ day)

• Feature freeze on main: bug fixes, QA tooling, docs, and release tasks only, until the RC ships. Toby coordinates through the punch list.
• Create docs/RELEASE-0.1.md — the single punch list, consolidated from: CLAUDE.md ⚠️ items, NEXT_TASKS.md open entries, docs/overnight-review-2026-07-08.md unactioned findings, docs/overnight-review-2026-07-13.md open triage, roadmap-memory owed items. Every item triaged: RC-blocker / fix-if-cheap / post-0.1. Standing rule from now on: anything anyone finds goes on this list first — no ad-hoc fixing mid-other-work.
• Commit the untracked 2026-07-09-dimension-choice-popup-design.md spec (docs-only).
• Commit the dirty docs/overnight-review-2026-07-13.md.

Phase 1 — QA build-out (~1–2 days)

1a. Headless autopilot soak harness (tools/soak/)

A SceneTree script run via godot --headless -s, ticking the pure sim far faster than real time. AutoPlayer (ai/auto_player.gd) already moves, picks upgrades, and picks dimensions; extend it minimally (occasional dash; decoy deploy) to exercise more code paths.

• Config sweep: seeds × all hulls (6 frigates + cruiser) × dimensions × solo/2-pilot co-op. Target ~200 runs of 10–20 min game-time each, overnight-capable.
• Invariants asserted every N ticks: no SCRIPT ERROR output; no NaN/inf positions; HP within bounds; entity pool counts sane; no softlock (XP still accruing, bosses eventually die, upgrade offers never empty, run reaches its target duration or a legitimate game-over).
• Effect telemetry: damage share per weapon, trigger counts per enemy mechanic/attack, XP/gold/kill curves, per-dimension spawn rosters actually seen. A weapon at ~0 damage share or a mechanic at 0 triggers across the sweep is a finding (this is exactly how the Disruptor/Halo Chain class of bug becomes machine-visible). Doubles as ground-truth data for the owed balance-tuning items.
• Instrumentation stays determinism-safe: an optional read-only stats sink on the sim (plain-logic callback field, default null, no Node/Engine APIs) or post-hoc reads of sim state — never a change to rng draws or tick order. Determinism suite must stay green with the sink attached and detached.
• Output: one markdown/JSON anomaly report per sweep, diffable between sweeps.

1b. Screenshot regression sweep (tools/ui_sweep/)

Windowed (NOT headless — MultiMesh/per-instance colours are unreadable headless, per the ui-look memory), building on the existing capture patterns (marketing/capture/shoot.gd, tools/ship_preview/). Captures every menu/panel at device-representative sizes: start-menu carousel (all cards), ship config carousel, shop (all tabs incl. RESET SHOP dialog), bestiary, pause menu, level-up panel, dimension-choice popup, HUD in-run, game-over. Baselines stored in-repo; compare with a perceptual diff (ImageMagick compare) and a generous-but-alerting threshold. Respect the staggered-entrance-tween wait gotcha (generous, card-count-scaled waits). First run establishes baselines by human eyeball, then it’s a regression net.

1c. Input-replay integration tests

The sim already consumes an InputState per tick deterministically, so a replay is just a recorded array. Add a dev-flag recorder in main.gd (record the InputState stream + seed of a real session to a file) and a headless replay runner that re-ticks the sim from the same seed asserting no script errors and a stable end-state checksum. Record a handful of canonical sessions (a normal run, a co-op run, heavy menu traffic) as fixtures. This covers the sim↔input integration layer that unit tests and the soak’s synthetic AutoPlayer input don’t.

1d. Close the co-op determinism gap

Known open 07-13 finding: no 2-pilot determinism test, and state_checksum() / snapshot_string() omit drone state. Add both. Adding drone state to the checksum changes the pinned value — that’s a deliberate re-pin via the bh-determinism-repin skill, done once, with the 2-pilot baseline pinned alongside the existing single-pilot one.

1e. Overnight review swarm re-run

The 07-13 run was cut to 4 cycles by API degradation. Re-run with targeted lenses (UI/input leaks, co-op paths, tvOS-specific, the new content batch) once the API is healthy. Proven cheap yield.

Phase 2 — Burn-down (2–3 days, parallelizable)

Fix RC-blockers from the punch list plus whatever Phase 1 surfaces. Every non-trivial fix goes through the normal ritual (bh-dev-chunk; SDD with review for anything multi-file). Includes the Obsidian cruiser’s real sprite bake (owed). Fixes land on main under the freeze rules; Toby picks items off the same list.

Phase 3 — Aligned deploy + structured playtest (1 session per person)

• BUILD 166 to all three device classes (Mac export, Apple TV + iPhone via bh-deploy) so every device matches main for the first time in weeks.
• One structured playtest script (written as part of this phase, lives next to the punch list) batching every owed human check: ship-tilt A/B decision (Off/Shader Warp/Baked Flipbook — pick a winner), start-menu carousel click-through, Reset Shop dialog + save/refresh path, manual aim-weapon feel + threshold ladder, the full 2-controller co-op checklist (panel chaining P1→P2, device gating incl. mouse-hijack, P2 drone deploy/recharge), new content batch feel pass (6 weapons / 6 enemies), balance consts gut-check against the soak telemetry. Remote Playtest Console live for telemetry capture. Findings go on the punch list — not fixed mid-session.

Phase 4 — Release gates → RC

1. Flip ADAPTIVE_QUALITY := true (main.gd); deploy; verify tier-shedding actually engages on Apple TV under load via telemetry (it’s been pinned at tier 0 since 2026-06-28).
2. Flag audit: every V01_*, SHIP3D_MEASURE, MEASURE_FULL_QUALITY, dev-tools gating — confirm each is in its intended release state, recorded in the punch list.
3. Full suite + test-count guard + determinism (+ the new 2-pilot baseline) green.
4. bh-appstore-release → TestFlight; distribute to Friends & Family; monitor the build 19 review outcome in parallel (if rejected, read the tvOS-metal memory before assuming the fix was wrong).
5. RC soak: several days of tester feedback through the punch list; only showstoppers block. Then tag v0.1.

Risks / notes

• Soak telemetry needs attribution hooks in the damage pipeline; keep them optional and read-only so /sim purity and determinism are untouched (verified by running the determinism suite with the sink attached).
• Screenshot sweep is Mac-local and windowed — it can’t run in headless CI; it’s a pre-deploy ritual, not a per-commit gate.
• Two-dev coordination: freeze + single punch list is the mitigation for the concurrent- session collisions documented in the multiagent-deploy memory; deploys stay serialized.
• Build 19 App Store review is an external dependency; nothing in this plan waits on it except final distribution.