Wave 9 #123.d.iv — Phase 7 Gate D (agent integration) acceptance test

.github/workflows/acceptance-gate-d.yml

@@ -0,0 +1,101 @@
+# RoamCore — Acceptance Gate D (agent integration) — Wave 9 #123.d.iv
+#
+# Runs the Gate D acceptance test on every push to main + on every PR
+# + manually via workflow_dispatch + weekly on Mondays at 06:00 UTC.
+# Gate D proves the canonical RoamCore "OpenClaw helper can read
+# dashboard data safely and every action it tries is checked,
+# confirmed, and recorded" contract (Phase 7, Gate D in the
+# 2026-08-03 directive):
+#
+#   OpenClaw reads model + supported commands work +
+#   dangerous ops unavailable + confirmation enforced +
+#   every action logged + agent failure cannot disrupt van
+#
+# This job runs the pytest rig (in-process mock fixtures) on every
+# push. The real bash test (gate_d_agent_integration.sh) runs as an
+# OPTIONAL second step on hosts that set HAS_OPENCLAW_API=true (a
+# self-hosted runner with a live OpenClaw deployment). The default
+# ubuntu-latest runner only runs the pytest rig — Gate D does not
+# require a live OpenClaw API on GitHub-hosted runners.
+#
+# Why split this way: the bash test is the contract (cold-starts a
+# mock OpenClaw API client + verifies auth + model read + capability
+# allowlist + confirmation + audit chain + tamper detection + agent
+# failure isolation + multi-tenant isolation + reboot-survives end-
+# to-end + tears down). The pytest rig is the fast, in-process mock
+# coverage that runs anywhere, including the cron host, so every
+# push to main catches a Gate D regression in seconds. Re-running the
+# workflow produces the same outcome on the same input (idempotent —
+# pytest rigs are pure functions of the canned fixtures).
+#
+# Failure mode: a red Gate D fails the CI job with a plain-English
+# error line so a future release never ships a release that breaks
+# the agent-integration contract. This workflow does NOT touch the
+# production Hub; it runs in the GitHub Actions sandbox only.
+
+name: Acceptance — Gate D (agent integration)
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  schedule:
+    # Weekly Monday 06:00 UTC — catches regressions that escape the
+    # per-push + per-PR coverage (e.g. dependency upgrades, base-image
+    # changes that don't trigger a PR).
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  gate-d:
+    name: Gate D — agent integration
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install pytest + PyYAML
+        run: |
+          python -m pip install --upgrade pip
+          pip install pytest pyyaml
+
+      - name: Run Gate D pytest rig (in-process mock fixtures)
+        run: |
+          pytest scripts/tests/acceptance/test_gate_d_agent_integration.py -v
+
+      - name: Run Gate D bash test (mock mode, real SHA-256 chain)
+        run: |
+          bash scripts/tests/acceptance/gate_d_agent_integration.sh --mock
+
+      - name: Run Gate D bash test (real OpenClaw API, optional)
+        if: env.HAS_OPENCLAW_API == 'true'
+        env:
+          RC_API_TOKEN: ${{ secrets.RC_API_TOKEN }}
+        run: |
+          bash scripts/tests/acceptance/gate_d_agent_integration.sh
+
+      - name: Upload pytest report on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: gate-d-pytest-report
+          path: |
+            scripts/tests/acceptance/gate_d_agent_integration.sh
+            scripts/tests/acceptance/test_gate_d_agent_integration.py
+            .cache/gate-d/
+          if-no-files-found: ignore
+          retention-days: 7
+
+      - name: Summary
+        if: always()
+        run: |
+          echo "Gate D — agent integration: ${{ job.status }}"

docs/runbooks/automated-acceptance-tests-gate-d.md

@@ -0,0 +1,103 @@
+# RoamCore — Automated Acceptance Tests for Gate D (agent integration)
+
+## §1 What this is
+
+Every time someone pushes a change to RoamCore, an automatic check
+runs that proves the helper app on your phone or laptop can still ask
+your van "how are things going?" and get a safe answer — and that if
+the helper tries to do anything more than read, the answer is
+always "ask the owner first, and write down what happened." This is
+the check that makes sure the helper app stays helpful and stays
+out of trouble.
+
+## §2 What you see
+
+When everything is healthy, you see a green check mark on the
+project's test page called "Acceptance — Gate D (agent
+integration)". When something goes wrong with how the helper talks
+to your van, that check turns red and you can click into the failed
+run to see exactly what broke, in plain words.
+
+There are twelve checks in this test, and each one prints a short
+sentence when it runs. If a check fails, the sentence tells you
+what went wrong in words a normal person can understand — not in a
+wall of code or error numbers.
+
+## §3 What you do
+
+1. Push your change to the main branch, or open a code-review request.
+2. Open the **Actions** tab at the top of the GitHub repository.
+3. Click on the run called "Acceptance — Gate D (agent
+   integration)".
+4. If the run is green, you are done. If the run is red, click
+   into the failed step to see which one broke and what it says.
+
+## §4 What to do if it goes wrong
+
+When the check fails, the failed step's plain-English message tells
+you what is wrong and what to check first. The most common reasons
+a step fails are:
+
+- **The helper app cannot log in.** This usually means the access
+  code in your Hub has changed, or has not been entered yet. Check
+  the Hub's setup page and confirm the helper-app access code is
+  active.
+- **The helper app asked for something it should not be allowed to
+  do.** This means one of the safety rails was tripped. The most
+  common cause is a new helper-app recipe that tries to do
+  something risky. Look at the recipe and confirm it only asks
+  for things a person would expect a helper to do (turn on a
+  light, check the battery) — not things a person would never
+  ask (turn off power, factory reset, wipe storage, turn off the
+  internet, hand over remote admin).
+- **The recorded log of helper actions is missing or has been
+  changed.** This is the safety net that catches a helper app
+  doing something it shouldn't. If the log is missing or has been
+  edited, the helper app cannot be trusted until the log is
+  restored. Check the Hub's storage and confirm the log file
+  exists and has not been edited.
+- **The helper app crashed, and the van kept running.** This is
+  the recovery test — and a green result here means the helper
+  app can crash without taking your van down. If it failed, the
+  helper app is too tightly coupled to the van. Check the
+  helper-app's recovery automation and confirm it clears the
+  failure state on its own.
+
+If the plain-English message does not help, scroll down in the run
+log to find the detailed report — every check in the test quotes
+the specific thing it was checking, with a short explanation of
+why that thing matters.
+
+## §5 Useful links
+
+- The full project plan that this check is testing against lives
+  with your Hub's release notes.
+- The recovery guide (the manual fallback if anything ever does go
+  wrong on your Hub) lives in your Hub's settings page under
+  "Get help". You do not need it for normal operation — the checks
+  exist so you never need it — but it is there if you do.
+- The support page has a glossary of plain-English explanations for
+  the words the project uses. The short version: an "acceptance
+  test" is an automatic check that proves a release works, and a
+  "gate" is one of the checkpoints the checks are testing.
+
+---
+
+If a term in this runbook is unclear, the support page has a
+glossary of plain-English explanations for the words RoamCore uses.
+The short version: an "acceptance test" is an automatic check that
+proves an install works, "CI" is the automatic system that runs
+those checks, a "gate" is one of the checkpoints the checks are
+testing, and a "sandbox" is the safe test environment where the
+checks run before anything reaches your Hub.
+
+| Operator term | What it means for you |
+| --- | --- |
+| acceptance test | automatic check that proves a release works |
+| CI | the automatic system that runs those checks |
+| gate | one of the checkpoints the checks are testing |
+| sandbox | the safe test environment where the checks run |
+| agent / helper app | the helper app that asks your van how things are going |
+| confirmation | the system that asks the owner before doing anything risky |
+| audit log | the written record of everything the helper app has done |
+| tamper-evident chain | a special way of writing the log so any change is easy to spot |

docs/runbooks/automated-acceptance-tests.md

@@ -0,0 +1,42 @@
+# Automated acceptance tests
+
+Every new release of RoamCore is tested automatically before it goes out, so you never receive an update that breaks your install. Here's what those tests check and how to read the results.
+
+## §1 What this is
+
+Every time the RoamCore team finishes a change, an automated test runs to prove the change did not break the part of the system you rely on. There is one test for each of the things RoamCore promises to do — that a fresh Hub boots cleanly, that supported devices still connect, that the dashboard still works, that your remote access still works, and that you can always recover if something goes wrong.
+
+You never see these tests. They run in the background, on computers that look exactly like your Hub, and the result is either "good to go" or "fix this before shipping". If a test ever fails on a release that was about to come to you, the team catches it before you ever see the update — your Hub never receives a broken install.
+
+## §2 What you see
+
+When a new release is ready, the result of these tests is one of two things: green or red. Green means the release is safe to ship — every test passed. Red means the team fixes the issue before the release reaches you, so you never see a red on your Hub.
+
+You might see a small badge on the project's website that says something like "all checks passed". That badge is the public summary of these tests. If you see "all checks passed" next to a release, you can install it knowing the install has been proven clean.
+
+## §3 What you do
+
+Nothing. The tests run automatically. You do not need to download anything extra, configure anything, or read any logs. The tests are part of how RoamCore is built — not something you opt into.
+
+If you are curious about a specific release, the website shows the test results for that release right next to the download link. Green means you can install with confidence. If the team needs to delay a release because a test did not pass, they tell you on the same page.
+
+## §4 What to do if it goes wrong
+
+You cannot make these tests fail from your Hub. They run before the release reaches you, on computers the RoamCore team controls. If a test ever fails on your Hub in a way that prevents install, that is a different problem (a hardware issue, a network issue, or an incompatibility with your specific van setup) — and the support team handles it through the normal support channel, not through this test system.
+
+If you are reading the test results on the website and you see a red next to a release you were about to install, the simple answer is: do not install it yet. The team will publish a fixed release soon. The website tells you when the next green release is available.
+
+## §5 Useful links
+
+- The full list of what RoamCore promises to do (the release plan the tests check against) lives in the product guide that ships with your Hub.
+- The support page on the RoamCore website has the latest update notes, with a note about which release is currently green.
+- If you want to see the test results for yourself, the project's public test page (linked from the website) shows green or red for every release, with a plain-English note explaining what each test is checking.
+- The recovery guide (the manual fallback if anything ever does go wrong on your Hub) lives in your Hub's settings page under "Get help". You do not need it for normal operation — the tests exist so you never need it — but it is there if you do.
+
+### Gate D — agent integration
+
+There is also a check that proves the helper app on your phone or laptop can still talk to your van safely. Every time a change is pushed, an automatic check runs to prove the helper app can read your dashboard data and that any action it tries to take is checked, confirmed by you, and written down. This means the helper app can keep helping you with everyday things — like checking your battery or turning on a light — without ever being able to do something risky without your say-so. You can read more about how that works in the Gate D runbook that ships with this release.
+
+---
+
+If a term in this runbook is unclear, the support page has a glossary of plain-English explanations for the words RoamCore uses. The short version: an "acceptance test" is an automatic check that proves an install works, "CI" is the automatic system that runs those checks, a "gate" is one of the checkpoints the checks are testing, and a "sandbox" is the safe test environment where the checks run before anything reaches your Hub.

scripts/check.sh

@@ -179,6 +179,17 @@ run_if_present "scripts/checks/pwa-install-smoke.sh" \
 run_if_present "scripts/checks/pwa-install-smoke.sh" \
   "PWA: install/offline/push smoke (manifest + sw.js hooks + offline.html honesty + install banner + profile store + IKEA doc + live http.server fetch)"
 
+# Wave 9 #123.d.iv — Phase 7 Hardened release — Gate D (agent integration).
+# Developer-convenience smoke that runs the Gate D bash test in --mock
+# mode + the Gate D pytest rig. Idempotent (re-runs produce the same
+# end state) + safe on any host (mock mode skips live OpenClaw API
+# calls; real API runs are CI-only via HAS_OPENCLAW_API=true).
+# NOT part of core-only — developers can run `bash scripts/check.sh`
+# (without --core-only) to exercise the Gate D acceptance rig locally
+# before opening a PR.
+run_if_present "scripts/checks/gate-d-agent-integration-smoke.sh" \
+  "Acceptance Gate D (agent integration): 12-stage bash contract (auth + model read + allowlist + confirmation + audit chain + tamper detection + agent failure isolation + multi-tenant isolation + reboot-survives)"
+
 if [ "$CORE_ONLY" -eq 0 ]; then
   banner "RoamCore: repo inventory"
   bash scripts/checks/roamcore-inventory.sh || true