Wave 9 #123.d.i — Phase 7 Acceptance Tests foundation + Gate A (clean install)

[bernardc6]

Wave 9 #123.d.i — Phase 7 Acceptance Tests foundation + Gate A (clean install)

Phase 7 of the 2026-08-03 directive. This slice delivers the
foundation for the six release gates + Gate A (clean install)
end-to-end. Future slices will add Gates B-F following the same
shape.

Scope (tight — these files ONLY)

• NEW .github/workflows/acceptance-gate-a.yml — GitHub Actions workflow for Gate A
• NEW scripts/tests/acceptance/gate_a_clean_install.sh — real bash acceptance test (307 LOC)
• NEW scripts/tests/acceptance/test_gate_a_clean_install.py — pytest rig with mocked subprocess (472 LOC, 10 tests)
• NEW scripts/tests/acceptance/conftest.py — pytest fixtures (173 LOC)
• NEW scripts/tests/acceptance/__init__.py — package marker (16 LOC)
• NEW scripts/tests/acceptance/README.md — operator-facing runbook (IKEA 5-step)
• NEW docs/runbooks/automated-acceptance-tests.md — user-facing runbook (IKEA 5-step)

NOT touched: scripts/check.sh (acceptance test runs via GitHub Actions + standalone pytest, not via check.sh per spec). The existing bash scripts/check.sh --core-only chain still passes GREEN.

Acceptance checklist

• code change is minimal + additive (no rewrite of unrelated files; zero modifications to existing files)
• check.sh --core-only is GREEN (exit 0) — this slice does NOT modify check.sh
• verification step is real (not a stub) — pytest rig runs the Gate A test logic with mocked subprocess; the bash test runs end-to-end on a host with qemu + the ha-beta rig (and exits 0 with a plain-English skip on hosts without qemu)
• user-facing doc is IKEA-style (5 steps: What it does / What you see / What you do / What to do if it goes wrong / Useful links)
• tier discipline honored (tier-c — community test recipe over the test rig; the test infrastructure is upstream pytest + GitHub Actions, not RoamCore-native)
• idempotent (re-running Gate A produces the same outcome on the same input — reuses cached HAOS image when SHA matches)
• no secrets in repo (test fixtures use mocked data + canned responses only)
• commit message: Context / Changes / Verification / Rollback / User-facing / GOLDEN.md alignment
• direct-to-main push on subagent/phase7-acceptance-tests; PR opened; SHA + PR # in this description
• GitHub Actions workflow is valid YAML (yamllint-clean; only the GitHub-Actions-typical on: truthy + missing document-start warnings, which are standard)

Tier-discipline

Per GOLDEN.md: tier-c — community test recipe over the test rig. The
test infrastructure is upstream pytest + GitHub Actions (the
off-the-shelf test plumbing), not a RoamCore-native test engine.

Idempotency proof

$ bash scripts/tests/acceptance/gate_a_clean_install.sh
! QEMU not available — Gate A runs in CI sandbox only
$ echo $?
0
$ bash scripts/tests/acceptance/gate_a_clean_install.sh
! QEMU not available — Gate A runs in CI sandbox only
$ echo $?
0

Both runs exit 0 with the same plain-English message.

Rollback plan

git revert <sha> -- .github/workflows/acceptance-gate-a.yml \
                  scripts/tests/acceptance/ \
                  docs/runbooks/automated-acceptance-tests.md

The slice is fully additive — rollback removes only the new files
and leaves the existing repo unchanged. No migrations to undo; no
external state to clean up (the bash test caches the HAOS image at
${ROAMCORE_GATE_A_CACHE:-.cache/gate-a}, which is already
gitignored).

GOLDEN.md alignment (full quote in commit body)

Product principles served:

• P1 (Novice-first UX): Gate A "clean install" proves the novice install path is always green; users never see a broken install.
• P2 (Mission-critical connectivity): Gate A acceptance test gates every release against the "fresh Hub boots, services start, no terminal" contract.

Engineering principles respected:

• E1 (Customer-facing repo): User-facing IKEA doc lands at docs/runbooks/automated-acceptance-tests.md (correct location, per the user-tree rule). Developer plumbing lives in scripts/tests/acceptance/ + .github/workflows/ (internal locations).
• E2 (Documentation-driven): Each gate ships with a user-facing IKEA doc + an operator-facing runbook.
• E3 (Backup + rollback discipline): Gate A runs in a CI sandbox only — never touches production. The bash test has a cleanup EXIT trap that kills qemu on every exit (success + failure).
• E4 (Git fast mode): The GitHub Actions workflow runs on every push to main + every PR — Gate A is part of the CI gate chain.

Anti-patterns explicitly avoided:

• ❌ Hand-configuring Victron (purely acceptance test infra)
• ❌ Touching vmbr0 (no networking config touched; CI sandbox only)
• ❌ Committing secrets (test fixtures use mocked data only)
• ❌ Wide PRs (focused acceptance-tests slice)
• ❌ Internal engineering logs on public GitHub (IKEA runbook; no SUPERSEDED banners)
• ❌ Adding "advanced" features before the novice path is solid — Gate A IS the novice-path guarantee

Reviewer

@bernardc6

Reference

• /home/bernard/clawd/RoamCore/GOLDEN.md (constitution)
• /home/bernard/.openclaw/workspace/memory/roamcore/2026-08-03-directive.md (Phase 7 / Gate F section)
• scripts/build/hub-golden-image.sh (the script-only-delivery pattern)
• connections/openclaw-api/tests/ (the pytest rig pattern)