<!-- Android mobile verification is ENABLED for this project. The stop hook
     enforces an android cycle whenever an edited file matches
     `android.verifyPatterns`. -->

## ⚠️ CRITICAL: when NOT to use android-devtools

**`android-devtools` is ONLY for Android apps** (native Kotlin/Java + React Native / Expo with an Android target). Do **NOT** call `MCP:adt_*` tools for projects that do not have an Android target.

**How to tell whether the project targets Android:**
- `android/` directory at the project root (React Native, Expo)
- `app/build.gradle` or `build.gradle.kts` with `com.android.application`
- `AndroidManifest.xml` present under `android/` or `app/src/main/`

If you see only `ios/`, `web/`, or no mobile directories — the project does NOT target Android. Do NOT call any `MCP:adt_*` tools.

**Misconfiguration recovery.** If this cycle activated but the project isn't an Android project, the operator enabled the android cycle by mistake. The stop hook will keep blocking with `incomplete_tools` until `maxRetries` is exhausted. Don't attempt a device connection. Stop and tell the user clearly: the project does not target Android; ask them to run `ironbee android disable` to unblock the gate.

## Android flow

> **Recording (only when `recording.enable` is on in config):** the gate blocks every other android tool until you first call `MCP:adt_content_start-recording`, and `submit-verdict` rejects with `"recording is still active"` unless you call `MCP:adt_content_stop-recording` after the steps below. **Treat start/stop as bookends around steps 1-3.** The recording ships to the collector as verification evidence.

1. **Connect to a running device or emulator**: `MCP:adt_device_connect` (list available targets first with `MCP:adt_device_list-targets` if needed).
   - For an emulator, the device is usually `emulator-5554`.
   - For a physical device with USB debugging on, it will appear in the target list.
2. **Ensure the app is running** on the target device: `MCP:adt_device_launch-app` with the package name.
3. **Pick an evidence path** per changed code area:
   - **Device-evidence path** (UI interaction confirms the change is live):
     - Drive the app UI to exercise the changed code: `MCP:adt_interaction_tap`, `MCP:adt_interaction_input-text`, `MCP:adt_interaction_swipe`, `MCP:adt_interaction_scroll` as needed (use `MCP:adt_a11y_find-element` to locate elements).
     - Take a screenshot: `MCP:adt_content_take-screenshot` — then STOP and visually analyze it (readability, layout, cut-off content, expected state rendered). The screenshot tells you what the user actually sees.
     - Take a UI snapshot: `MCP:adt_a11y_take-ui-snapshot` — verify the view hierarchy / labels / structure match the change.
     - Screenshot AND UI snapshot are BOTH MANDATORY on this path (the stop hook checks each) — visual + structural evidence, like the browser cycle's screenshot + aria-snapshot pair.
   - **Log-evidence path** (device logs confirm the changed code path executed):
     - Read Logcat output for the tag(s) relevant to the changed code: `MCP:adt_o11y_log-read` or `MCP:adt_o11y_log-follow` (drain a follow with `MCP:adt_o11y_log-get-followed`, stop it with `MCP:adt_o11y_log-stop-follow`).
     - Confirm expected log lines appear AND no unexpected crashes (FATAL / E/ entries for the app package).
   - **Network-evidence path** (captured HTTP traffic confirms a network/API-related change):
     - Capture the app's outgoing HTTP(S) requests: `MCP:adt_o11y_get-http-requests` (Frida/OkHttp in-process — no proxy, no CA install; OkHttp-based stacks only — Retrofit / React Native / HttpURLConnection). **Capture is forward-looking**: call it once to start capture, drive the app to trigger traffic (`MCP:adt_interaction_*`), then call it again to read. Confirm the expected request(s) / response status appear.
     - **Auxiliary (NOT evidence — setup/correlation only):** to pin one correlation root across the flow, optionally `MCP:adt_o11y_new-trace-id` first (it stamps `traceparent` on every captured request; inspect/clear via `MCP:adt_o11y_set-trace-context` / `MCP:adt_o11y_get-trace-context`). To set up test conditions, `MCP:adt_stub_mock-http-response` / `MCP:adt_stub_intercept-http-request` mock or mutate responses (list/clear with `MCP:adt_stub_list` / `MCP:adt_stub_clear`). `MCP:adt_figma_compare-screen-with-design` checks emulator-vs-Figma parity (optional, requires `FIGMA_ACCESS_TOKEN`). None of these count toward the gate — they shape the test, they don't inspect it.

**Batch (speed):** connect + launch-app run standalone first (prerequisites). On the device-evidence path, batch the UI interactions + the UI snapshot into one `MCP:adt_execute`; the snapshot captures the state after the batched interactions, so to assert an intermediate state take a snapshot at that point too. The device-evidence screenshot is usually pixel-judged (a visual change) — take THAT one standalone with `includeBase64: true` so you can see it; batch it only when it's purely gate evidence. Log-evidence reads batch together too.

### Verdict fields
The verdict is platform-agnostic — submit only semantic judgment:

```json
{
  "session_id": "<sid>",
  "status": "pass",
  "checks": ["LoginActivity renders correctly after auth change", "no crash in Logcat"]
}
```

On fail, include `issues`. On pass after a previous fail, include `fixes`.

Android-cycle pass criteria:
- **Device-evidence**: at least one UI interaction tool fired AND a screenshot was taken AND a UI snapshot was taken AND both show the expected UI state/structure.
- **Log-evidence**: Logcat was read AND the expected log lines are present AND no crash (FATAL / unhandled exception) from the app's package.
- **Network-evidence**: the app's outgoing HTTP traffic was captured AND the expected request(s) / response status confirm the change behaved correctly.

## Multi-cycle (browser + android simultaneously)

Both cycles can be active simultaneously. One `verification-start` covers all active cycles; one platform-agnostic verdict covers them all; one retry counter applies globally.