/runtime-gate

name: runtime-gate
description: Use before advancing a ticket past QA and before any release — builds the app and launches it, then drives the P0 journey where UI automation exists. Triggers from /app-build's QA wave, /app-ship, qa-engineer and verification-engineer, and any moment someone is about to certify that an app works without having run it.

Runtime gate

Every other gate in this plugin verifies that the **process** was followed. `verify-done.sh` checks the branch exists and the test command exited zero. `board-doctor` checks the board is coherent. `ship-gate.sh` checks nothing is in flight and no S1/S2 is open. `code-reviewer` checks the diff reads correctly. A sprint can run green through all four on an app that does not compile in Xcode, does not launch, or launches to a blank screen — because nothing ever ran it.

This is `defect-hunting` §2 — *never certify by reading, execute it* — pointed at the app itself.

Run it

sh "${CLAUDE_PLUGIN_ROOT}/scripts/runtime-gate.sh" [--platform ios|android|auto] [--project-root .]

| Exit | Meaning | What to do | |---|---|---| | `0` | PASS — built **and** launched | Record the evidence path. Continue. | | `1` | FAIL — does not build, or does not launch | **Blocks the row.** Re-spawn the developer with the compiler output the gate printed, verbatim. | | `2` | CANNOT EVALUATE — the toolchain is not on this machine | **Not a pass.** Report it as CANNOT EVALUATE in the standup and in the verdict block. |

**Exit 2 is the point of the script.** A machine without Xcode is a normal state — a CI runner, a Linux box, an Android-only project. It is not an error and it is not a pass. The gate prints what was missing and what would make it evaluable; surface those lines rather than paraphrasing them.

Two traps it already closes, so do not re-open them by hand: `command -v xcodebuild` succeeds on a Command-Line-Tools-only Mac where every invocation fails, and a build that compiles is **not** a pass — "BUILDS, but launch UNKNOWN" is exit 2. Timeouts are stated and enforced; a hung simulator produces CANNOT EVALUATE, never an infinite wait.

Escalate past the script when the toolchain allows

The script is the floor — it proves the app starts. On iOS the Axiom toolchain, when installed, gives far more, and you should route to it:

• `axiom:simulator-tester` — drives the running app, captures screenshots, reads the log for

crashes and errors. This is what turns "it launched" into "the journey works".

• `axiom:test-runner` — runs XCUITests and parses the `.xcresult` for real failure detail.
• XcodeBuildMCP (the `xcodebuildmcp` skill) — build, install, launch and UI automation as tools.

All three are **external and optional** — separate plugins, not this one's `skills/`. Their absence is normal; it is never a defect to file.

Absent toolchain → **degrade to the plain script and say so**. Never silently skip a step: an unavailable capability produces a stated CANNOT EVALUATE for that step, never a quiet pass. An unstated gap reads as a cleared one.

Drive the P0 flow, not just the launch

Building and launching is the floor. Where UI automation is available, exercise the **primary user journey** and capture evidence at each step.

Pick the flow this way:

1. `docs/10-prd.md` — take the P0 features in priority order. The first P0 journey is the one that, if broken, makes the release pointless. 2. The ticket's acceptance criteria — the `Given / When / Then` rows are already the script. Drive them literally: the `When` is the interaction, the `Then` is what the screenshot must show. 3. `docs/50-test-plan.md` — qa-engineer's rows for those tickets, if the plan exists.

A journey that cannot be driven is stated as not driven, with the reason.

Evidence discipline

The script writes `docs/evidence/runtime-<date>-<platform>.png` on a successful launch. Anything you drive beyond that writes its own artifact to `docs/evidence/` too — a screenshot, or a log excerpt for a step with nothing visual to show.

**Reference the artifact by path in the DONE report, the QA verdict, or the ship summary.** A claim with no artifact behind it is exactly the class of self-report this whole system exists to distrust — and per `defect-hunting` §4, a finding with no evidence and no owner is one that gets silently skipped.

Never

• Never report a pass for a platform the gate could not evaluate.
• Never treat "it compiles" as "it works". They are different exit codes for a reason.
• Never paraphrase a failure. The compiler already said exactly what is wrong; pass it through.