@aarwitz/tapp 0.16.5 → 0.17.0-rc.2

package/AGENTS.md

@@ -8,16 +8,16 @@ Android emulators/devices, plus (beta) web apps in a real browser.
 Every core capability works as a plain command — no server, no config. `[target]` is
 optional: with nothing, tapp finds + builds the Xcode project in the cwd (or falls back to
 the app already on the simulator); it also accepts a repo dir, a `path/to/App.app`, a
-bundle id, or (qa only) an http(s) URL. You never need to know a bundle id up front.
+bundle id, or (web) an http(s) URL. You never need to know a bundle id up front.
 
 ```bash
-npx -y @aarwitz/tapp qa [target]     # autonomous QA → scoped release verdict + findings (≈ tapp_run_qa)
+npx -y @aarwitz/tapp explore [target]     # autonomous exploration → findings + evidence (observation, not a gate; ≈ tapp_explore)
 npx -y @aarwitz/tapp open [target]   # launch + screen summary + screenshot saved to a file (≈ tapp_open_app)
 npx -y @aarwitz/tapp tree [target]   # accessibility tree, --json for every element (≈ tapp_ui_tree)
 npx -y @aarwitz/tapp shot            # screenshot the booted sim → file path (≈ tapp_screenshot)
 npx -y @aarwitz/tapp apps            # what's installed on the simulator, with bundle ids
 npx -y @aarwitz/tapp build [dir]     # build the app in an Xcode repo + install it (≈ tapp_build)
-npx -y @aarwitz/tapp qa app.apk --platform android --app-id com.acme.app
+npx -y @aarwitz/tapp explore app.apk --platform android --app-id com.acme.app
 npx -y @aarwitz/tapp flow run .tapp/flows/smoke.yml  # committed, keyless E2E replay
 ```
 
@@ -30,21 +30,22 @@ loading or changing.
 Code's Read tool, Codex's view-image), open the saved screenshot path the CLI prints —
 that IS the screen. If you cannot (Cursor, VS Code Copilot), connect the MCP server
 instead: its tool results carry the screenshot inline. Screen *recordings* are for the
-human: `tapp qa` records the full exploration and embeds it in the report.html evidence
-page — tell the user the report path so they can watch it.
+human: on **iOS**, `tapp explore` records the full exploration and embeds it in the report.html
+evidence page (Android does not currently record video) — tell the user the report path so they can
+watch it.
 
 The interactive session/record loop is MCP-only (it needs a long-lived process). Flow replay is
 also available in the CLI. The rest of this playbook assumes the `tapp_*` MCP tools are connected. With
 MCP, the no-bundle-id path is: `tapp_build {projectDir}` (auto-detects + builds +
-installs, returns the bundle id) → `tapp_run_qa {appBundleId}`.
+installs, returns the bundle id) → `tapp_explore {appBundleId}`.
 
 ## Pick the right tool for the job
 
 | The user wants… | Use | NOT |
 |---|---|---|
-| "Show me / screenshot a screen" | `tapp_open_app` (launch + screenshot + tree, ~15s) | `tapp_run_qa` (a full multi-minute QA exploration) |
+| "Show me / screenshot a screen" | `tapp_open_app` (launch + screenshot + tree, ~15s) | `tapp_explore` (a full multi-minute QA exploration) |
 | "Tap through / drive / fill a form / log in" | `tapp_session_start` → `session_act` loop | repeated `open_app` calls (cold relaunch each time) |
-| "Is my app broken? Is it ship-ready? Find bugs" | `tapp_run_qa` — `appBundleId` for iOS, `androidAppId` for Android, `url` for owned web apps; web `ready` means the disclosed automated checks passed, not that copy/privacy/brand claims were reviewed | a manual session (QA exploration is autonomous) |
+| "Is my app broken? Find bugs" | `tapp_explore` — `appBundleId` for iOS, `androidAppId` for Android, `url` for owned web apps; returns an observation (findings + evidence), not a ship verdict — gate a merge with the CI gate (`tapp ci` CLI / the GitHub Action) + a contract | a manual session (exploration is autonomous) |
 | "Make this flow a repeatable test" | drive it in a session, then `tapp_flow_save`; replay with `tapp_flow_run` | re-driving it by hand every time |
 | "What's on screen right now?" | `tapp_screenshot` / `tapp_ui_tree` | relaunching the app |
 
@@ -80,15 +81,19 @@ Rules that prevent 90% of failures:
    auto-dismisses keyboards and retries), `not_found` (nothing matches — re-read the tree).
 6. One session at a time. `session_start` always begins from a fresh app launch.
 
-## Autonomous QA (`tapp_run_qa`)
+## Autonomous exploration (`tapp_explore`)
 
-Returns `{verdict, confidence, releaseScore, headline, screensExplored, actionsPerformed, findings[]}`.
-Exploratory web runs set `confidence` and `releaseScore` to `null`; report their deterministic
-finding counts, advisory sampled-probe counts, and coverage instead of inventing a scalar.
+Exploration **observes** — it returns an observation, NOT a ship verdict or score. To get a release
+decision, run the deterministic gate (`tapp ci` / the GitHub Action). It applies versioned policy to
+the findings + coverage plus any selected Flows/Scenarios/contracts and an optional target-scoped
+baseline (both optional — a clean bootstrap can pass without them) and returns `pass | fail |
+inconclusive`.
+
+Returns `{kind:"tapp-exploration-run", headline, inconclusive, screensExplored, actionsPerformed,
+findingCounts, findings[]}` — **no** `verdict`, `confidence`, or `releaseScore`. Each finding carries
+`authority` (`deterministic` — marker-derived; model/vision findings would be `model-observed` and
+advisory). Report the finding counts and coverage; do not invent a scalar or a ship verdict.
 
-- `verdict`: `ready` | `caution` | `blocked`. Report it as-is; never soften a `blocked` or inflate a
-  `caution`. Judgment is deterministic for a given evidence trace, while adaptive exploration and
-  live target state can still change which evidence a run observes.
 - `inconclusive: true` means the run couldn't see enough (crash on launch, login wall). That is
   **not a pass** — tell the user what blocked exploration and what would unblock it.
 - Login walls: pass `testEmail`/`testPassword` (auto-typed into login forms), `appLaunchArgs`
@@ -96,12 +101,12 @@ finding counts, advisory sampled-probe counts, and coverage instead of inventing
   backend URL). If the result shows `inputFieldsEncountered` and you have no credentials, **ask
   the user** for them rather than re-running blind.
 - Diff two runs: pass the previous run's `findings` as `baselineFindings` → you get a
-  `regression` block (`new` / `persisting` / `resolved`, plus a CI `gate` signal).
-- On web, report the exact verdict but preserve its scope: Tapp deterministically checks technical
-  behavior such as failed requests, missing assets, and placeholder links. Dead-control probes are
-  budget-capped advisory findings and do not drive the verdict. Tapp does
-  not validate marketing claims against APIs, API field privacy, brand consistency, or subjective
-  marketplace credibility unless an explicit reviewed test/contract or verifier covers them.
+  `regression` **comparison** (`new` / `persisting` / `resolved`) — an observation, not a gate. To gate
+  a merge on regressions, run the CI gate (`tapp ci` / the GitHub Action).
+- On web, preserve scope: Tapp deterministically checks technical behavior such as failed requests,
+  missing assets, and placeholder links. Dead-control probes are budget-capped advisory findings.
+  Tapp does not validate marketing claims against APIs, API field privacy, brand consistency, or
+  subjective marketplace credibility unless an explicit reviewed test/contract or verifier covers them.
 
 ## Flows (deterministic E2E tests)
 

package/Harness/OCQAHarnessUITests/ExplorerTests.swift

@@ -946,6 +946,7 @@ class ExplorerTests: XCTestCase {
         var elementScreenPresence: [String: Set<String>] = [:]
         var totalDistinctStates = 0
         var recentStateHashes: [String] = []
+        var recentScreenTitles: [String] = []
         var actionsSinceNewState = 0
         var sameScreenStreak = 0
         var screenTextEntryCount: [String: Int] = [:]
@@ -1238,6 +1239,15 @@ class ExplorerTests: XCTestCase {
         let initialControlsJson = mapControlsJSON(initialElements)
         print("OCQA_STATE:{\"screen\":\"\(escapeJSON(initialTitle))\",\"hash\":\"\(computeHash(initialElements))\",\"elements\":\(initialElements.count),\"action\":0,\"role\":\"\(escapeJSON(initialRole))\",\"summary\":\"\(escapeJSON(initialSummary))\",\"settled\":\(isScreenSettled() ? "true" : "false"),\"atext\":[\(initialAtext)],\"inputs\":[\(initialInputJson)],\"controls\":[\(initialControlsJson)]}")
 
+        // The launch surface is real evidence even when root normalization immediately dismisses
+        // it. Attach it before the first action so the HTML report's "every screen explored" claim
+        // includes onboarding/login sheets rather than beginning at the post-dismiss destination.
+        let initialScreenshot = app.screenshot()
+        let initialAttachment = XCTAttachment(screenshot: initialScreenshot)
+        initialAttachment.name = "state_0_\(initialTitle.replacingOccurrences(of: " ", with: "_"))"
+        initialAttachment.lifetime = .keepAlways
+        add(initialAttachment)
+
         navigateToRootScreen(actionCount: &actionCount)
 
         // The first state is the true customer launch surface. Directed replay begins after
@@ -1386,8 +1396,10 @@ class ExplorerTests: XCTestCase {
             }
 
             recentStateHashes.append(stateHash)
+            recentScreenTitles.append(titleStr)
             if recentStateHashes.count > 12 {
                 recentStateHashes.removeFirst(recentStateHashes.count - 12)
+                recentScreenTitles.removeFirst(recentScreenTitles.count - 12)
             }
 
             if previousStateHash == stateHash {
@@ -1474,10 +1486,19 @@ class ExplorerTests: XCTestCase {
             // is the fuller a11y text inventory that grounds the vision reviewer (see visionTextInventory).
             let escapedTitle = escapeJSON(titleStr)
             let settled = isScreenSettled()
-            let atextJson = visionTextInventory(elements).map { "\"\(escapeJSON($0))\"" }.joined(separator: ",")
+            let visibleTextInventory = visionTextInventory(elements)
+            let atextJson = visibleTextInventory.map { "\"\(escapeJSON($0))\"" }.joined(separator: ",")
             let controlsJson = mapControlsJSON(elements)
             print("OCQA_STATE:{\"screen\":\"\(escapedTitle)\",\"hash\":\"\(stateHash)\",\"elements\":\(elements.count),\"action\":\(actionCount),\"role\":\"\(escapeJSON(screenRole))\",\"summary\":\"\(escapeJSON(screenSummary))\",\"settled\":\(settled ? "true" : "false"),\"atext\":[\(atextJson)],\"inputs\":[\(inputJsonArray)],\"controls\":[\(controlsJson)]}")
 
+            // Signing out after a successful login is a completed auth cycle, not a navigation
+            // trap and not lost-form-state. Stop cleanly instead of probing the root login screen
+            // for an impossible back path or expecting credentials to persist after logout.
+            if authSucceeded && detectedInputs.contains(where: { $0.secure }) {
+                print("OCQA_STATE:auth_cycle_complete screen=\(escapedTitle) step=\(actionCount)")
+                break
+            }
+
             // ---- Persistence probe: on a fresh RE-ARRIVAL at a screen, fields we previously
             // typed into (and verified visible in the a11y value) should still hold their value.
             // An empty field here means the entered state was silently lost on navigation —
@@ -1591,14 +1612,14 @@ class ExplorerTests: XCTestCase {
             // content-feed app: post detail + replies-loading spinner flagged app_hang HIGH).
             let visibleTextCount = elements.filter { isStaticTextType($0.type) && normalizeVisibleText($0.label).count >= 3 }.count
             if screenVisitCount[titleStr] ?? 0 <= 1, visibleTextCount <= 4,
-               app.activityIndicators.firstMatch.exists || app.progressIndicators.firstMatch.exists {
+               hasIndeterminateLoadingIndicator() {
                 let loadingKey = "loading:\(titleStr)"
                 if !reportedIssueKeys.contains(loadingKey) {
                     var resolved = false
                     let deadline = Date().addingTimeInterval(8.0)
                     while Date() < deadline {
                         Thread.sleep(forTimeInterval: 1.0)
-                        if !(app.activityIndicators.firstMatch.exists || app.progressIndicators.firstMatch.exists) {
+                        if !hasIndeterminateLoadingIndicator() {
                             resolved = true
                             break
                         }
@@ -1658,7 +1679,7 @@ class ExplorerTests: XCTestCase {
 
             // ---- Blank-screen detection ----
             // Distinguish between "no a11y labels / custom UI" vs genuinely empty.
-            if elements.count < 5 && interactable.count == 0 {
+            if visibleTextInventory.isEmpty && interactable.count == 0 {
                 let blankKey = "blank:\(titleStr)"
                 let blankCount = (actionCounts[blankKey] ?? 0) + 1
                 actionCounts[blankKey] = blankCount
@@ -1690,16 +1711,26 @@ class ExplorerTests: XCTestCase {
             }
 
             // ---- Navigation-loop detection ----
-            // Check if recentStateHashes has a repeating cycle of length 2 or 3
+            // A cycle must actually move across distinct states. Four identical reads satisfy the
+            // arithmetic shape A,A,A,A of the old period-2 check, which mislabeled ordinary
+            // scroll/probe recovery on a stable screen as a navigation loop.
             if recentStateHashes.count >= 6 {
                 let recent = recentStateHashes
+                // Distinct structural hashes are not enough: a list and its detail rows can share
+                // one navigation title and alternate A/B while the explorer intentionally samples
+                // different rows. Calling that a navigation loop is a false positive. Require the
+                // cycle to cross distinct user-visible screen titles as well.
                 let hasLoop2 = recent.count >= 4 &&
                     recent[recent.count - 1] == recent[recent.count - 3] &&
-                    recent[recent.count - 2] == recent[recent.count - 4]
+                    recent[recent.count - 2] == recent[recent.count - 4] &&
+                    Set(recent.suffix(2)).count == 2 &&
+                    Set(recentScreenTitles.suffix(2)).count == 2
                 let hasLoop3 = recent.count >= 6 &&
                     recent[recent.count - 1] == recent[recent.count - 4] &&
                     recent[recent.count - 2] == recent[recent.count - 5] &&
-                    recent[recent.count - 3] == recent[recent.count - 6]
+                    recent[recent.count - 3] == recent[recent.count - 6] &&
+                    Set(recent.suffix(3)).count == 3 &&
+                    Set(recentScreenTitles.suffix(3)).count == 3
                 if (hasLoop2 || hasLoop3) && !(authSucceeded && detectedInputs.contains { $0.secure }) {
                     let loopKey = "nav_loop:\(titleStr)"
                     if actionCounts[loopKey] == nil {
@@ -1711,17 +1742,10 @@ class ExplorerTests: XCTestCase {
                 }
             }
 
-            // ---- Unresponsive-element detection ----
-            // Skip when we're merely re-poking a login screen we've already passed (Sign Out → re-login
-            // churn) — that's an exploration artifact, not a frozen/broken screen.
-            if repeatedStateCount >= 5 && !(authSucceeded && detectedInputs.contains { $0.secure }) {
-                let unrespKey = "unresponsive:\(titleStr)"
-                if actionCounts[unrespKey] == nil {
-                    issues.append((type: "unresponsive_element", severity: "medium", title: "Unresponsive UI on \(titleStr)", desc: "Actions are not changing app state — possible frozen or broken screen"))
-                    print("OCQA_ISSUE:{\"type\":\"unresponsive_element\",\"severity\":\"medium\",\"title\":\"Unresponsive UI\",\"screen\":\"\(escapedTitle)\",\"repeated_state_count\":\(repeatedStateCount),\"step\":\(actionCount)}")
-                    actionCounts[unrespKey] = 1
-                }
-            }
+            // Do not infer an unresponsive app merely from an unchanged state streak: recovery
+            // gestures (scroll, carousel probe, center probe) are expected to be no-ops on many
+            // healthy screens. Labeled controls have a stronger detector below: a direct tap plus
+            // two delayed, content-signature reads. Hangs have their own time-based detector.
 
             if interactable.count < 3 {
                 print("OCQA_STATE:low_interactable screen=\(escapedTitle) total=\(elements.count) interactable=\(interactable.count) global=\(globalNavElements.count) nonGlobal=\(nonGlobalCandidates.count)")
@@ -1757,10 +1781,10 @@ class ExplorerTests: XCTestCase {
                     break
                 }
 
-                let issueTitle = "Dead end: \(titleStr)"
-                issues.append((type: "dead_end", severity: "medium", title: issueTitle, desc: "No interactable elements found"))
-                print("OCQA_ISSUE:{\"type\":\"dead_end\",\"severity\":\"medium\",\"title\":\"\(escapedTitle)\",\"screen\":\"\(escapedTitle)\",\"step\":\(actionCount)}")
-
+                // Exhausting Tapp's untried candidate pool is not itself a user-visible dead end:
+                // leaf screens commonly have only a working Back control that was already mapped.
+                // Recover first; only the stronger navigation-trap path below emits a finding when
+                // every real back/dismiss route fails.
                 // tryGoBack does swipe-down as its last resort (sheet dismiss)
                 let preBackTitle = titleStr
                 let backWorked = tryGoBack()
@@ -1772,6 +1796,7 @@ class ExplorerTests: XCTestCase {
                     print("OCQA_ACTION:{\"type\":\"back\",\"reason\":\"dead_end_escape\",\"from\":\"\(escapedTitle)\",\"to\":\"\(escapeJSON(postTitle))\",\"step\":\(actionCount),\"screen\":\"\(escapedTitle)\",\"narrative\":\"\(escapeJSON(recoveryNarrative("back_dead_end", screen: titleStr, to: postTitle)))\"}")
                     continue
                 }
+                if actionCount >= maxActions { break }
                 // Swipe right (back gesture) as another option
                 let swipeStart = app.coordinate(withNormalizedOffset: CGVector(dx: 0.02, dy: 0.5))
                 let swipeEnd = app.coordinate(withNormalizedOffset: CGVector(dx: 0.8, dy: 0.5))
@@ -2047,6 +2072,7 @@ class ExplorerTests: XCTestCase {
                 }
                 // Back didn't change screens — fall through to global nav
                 print("OCQA_ACTION:{\"type\":\"back\",\"reason\":\"screen_exhausted_failed\",\"screen\":\"\(escapedTitle)\",\"step\":\(actionCount),\"narrative\":\"\(escapeJSON(recoveryNarrative("back_failed", screen: titleStr)))\"}")
+                if actionCount >= maxActions { break }
                 // Stuck on this screen — use global navigation (tab bar) to reach unexplored areas
                 let globalNav = interactable
                     .filter { isLikelyGlobalNavigation($0, screenBounds: screenBounds) }
@@ -3679,6 +3705,20 @@ class ExplorerTests: XCTestCase {
         return kb.exists ? kb.frame : .zero
     }
 
+    /// Activity indicators are inherently indeterminate. `ProgressIndicator`, however, is also the
+    /// XCTest type for legitimate determinate progress bars (loyalty points, upload percentage,
+    /// onboarding completion). Only value-less/loading-valued progress indicators are hang signals.
+    private func hasIndeterminateLoadingIndicator() -> Bool {
+        if app.activityIndicators.allElementsBoundByIndex.contains(where: { $0.exists && $0.frame.width > 0 && $0.frame.height > 0 }) {
+            return true
+        }
+        return app.progressIndicators.allElementsBoundByIndex.contains { indicator in
+            guard indicator.exists, indicator.frame.width > 0, indicator.frame.height > 0 else { return false }
+            let value = (indicator.value as? String ?? "").trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
+            return value.isEmpty || value == "in progress" || value == "loading"
+        }
+    }
+
     /// True when the screen is in a "settled" resting state — no on-screen keyboard and no open
     /// transient overlay (menu / dropdown / popover / sheet / picker wheel). A screenshot taken while
     /// one of these is up is inherently ambiguous to a visual reviewer (the keyboard "covers" the

package/README.md

@@ -12,21 +12,24 @@ It turns a repository and real product into an observed UI Map, a compact review
 suite, and an inspectable merge decision.
 
 Coding agents can write the code, and (with Playwright & friends) they can even drive the app.
-What nobody gives them is **judgment**: did it actually work? tapp explores your app like a user —
-no test code, no app changes — detects what's broken, and commits to a verdict your merge queue
-can trust: `ready`, `caution`, or `blocked`, with evidence.
+What nobody gives them is **proof it works**. tapp explores your app like a user — no test code,
+no app changes — and surfaces what's broken, with evidence. Then a deterministic gate applies
+versioned policy to that evidence — the findings and coverage, any selected deterministic suites
+(Flows/Scenarios/contracts), and, when available, a target-scoped baseline — and returns a merge
+decision your queue can trust: `pass`, `fail`, or `inconclusive`. Exploration **observes**; the gate
+**judges** — never a soft "ship-ready" guess.
 
-Three platforms, one judgment layer:
+Three platforms, one observe-and-gate engine:
 
-- **iOS** — the missing Playwright for iOS. tapp is hands *and* judgment: a generic XCUITest
+- **iOS** — the missing Playwright for iOS. tapp is hands *and* eyes: a generic XCUITest
   harness drives any app on the simulator via the accessibility surface. Native — no Appium,
   no WebDriverAgent.
 - **Android** — black-box native driving through ADB + UIAutomator. Install an APK, target its
-  application id, and run the same QA, committed Flows, evidence, and regression gate. The app
-  does not link a Tapp SDK.
+  application id, and run the same exploration, committed Flows, evidence, and regression gate. The
+  app does not link a Tapp SDK.
 - **Web (beta)** — built *on* Playwright. Your agent already has browser hands; tapp adds the
   autonomous exploration, the deterministic detectors (uncaught exceptions, failed requests,
-  dead buttons, broken links, placeholder `href="#"` links, error pages), and the same verdict.
+  dead buttons, broken links, placeholder `href="#"` links, error pages), and the same gate.
 
 ```
 you:    "Add a logout button to the settings screen"
@@ -40,17 +43,17 @@ agent:  "Done — and here it is working on the simulator: [screenshot]"
 Requirements: **Node ≥ 18**. iOS needs **macOS + Xcode**; Android needs `adb` plus a connected
 emulator/device; web needs Playwright + Chromium.
 
-From the app repository, let the agent see the current screen and then ask for a release verdict:
+From the app repository, let the agent see the current screen and then explore it:
 
 ```bash
 npx -y @aarwitz/tapp open   # builds/launches as needed; prints a screenshot path + screen summary
-npx -y @aarwitz/tapp qa     # explores the real app; prints verdict, findings, and evidence report
+npx -y @aarwitz/tapp explore     # explores the real app; prints findings + evidence (an observation, not a gate)
 ```
 
 Claude Code can read the saved image with its file-reading tool; Codex can open it with
-`view_image`. The agent should report what the screenshot proves, preserve Tapp's exact
-`ready`/`caution`/`blocked` verdict, and link the HTML evidence report. No server, account, config
-file, test code, API key, or bundle id is required for this loop.
+`view_image`. The agent should report what the screenshot proves, relay the exploration findings
+as-is (an observation, not a merge decision — `tapp ci` gates that), and link the HTML evidence
+report. No server, account, config file, test code, API key, or bundle id is required for this loop.
 
 The product, executable, and package leaf are all Tapp: npm distributes it as
 `@aarwitz/tapp`, while the installed command remains `tapp`.
@@ -77,7 +80,7 @@ npx -y @aarwitz/tapp baseline create . --platform web
 npx -y @aarwitz/tapp ci install .
 ```
 
-The baseline command writes only after autonomous QA and every selected deterministic suite pass
+The baseline command writes only after exploration and every selected deterministic suite pass
 conclusively. It stores `.tapp/baselines/<platform>/<target-id>.json`; the generated workflow
 uses that exact target identity so two apps on the same platform never share a baseline. `ci
 install` writes `.github/workflows/tapp.yml` plus `.tapp/ci.json`, refuses unresolved build
@@ -96,7 +99,7 @@ npx -y @aarwitz/tapp apps            # what's installed on the simulator (names
 npx -y @aarwitz/tapp build [dir]     # just build + install (scheme auto-detected)
 ```
 
-Web (beta): `npx -y @aarwitz/tapp qa http://localhost:3000` *(one-time setup:
+Web (beta): `npx -y @aarwitz/tapp explore http://localhost:3000` *(one-time setup:
 `npm i -g playwright && npx playwright install chromium`)*
 
 Focused web inspection waits briefly for loading states to settle. If a consent or location modal
@@ -110,7 +113,7 @@ npx -y @aarwitz/tapp tree https://example.com --tap "Not now" --wait-for "Dashbo
 Android:
 
 ```bash
-npx -y @aarwitz/tapp qa path/to/app-debug.apk --platform android --app-id com.acme.app
+npx -y @aarwitz/tapp explore path/to/app-debug.apk --platform android --app-id com.acme.app
 npx -y @aarwitz/tapp open com.acme.app --platform android
 ```
 
@@ -124,7 +127,7 @@ npx -y @aarwitz/tapp doctor     # verify Xcode / simulators / toolchain
 
 `npx -y @aarwitz/tapp app .` opens a local Release Studio for people who want visual repository
 onboarding, release-plan review, and CI preparation. It is not required for the coding-agent
-`open`/`qa` workflow.
+`open`/`explore` workflow.
 
 ### MCP hookup (optional)
 
@@ -156,7 +159,7 @@ args = ["-y", "@aarwitz/tapp", "mcp"]
 **Any other MCP client:** stdio command `npx -y @aarwitz/tapp mcp`.
 
 Then ask your agent:
-> "Run tapp qa on my app — is it ship-ready?"
+> "Explore my app and show me what breaks."
 > "Open com.mycompany.app on the simulator and screenshot the home screen."
 > "Log in with test@example.com, drive to checkout, and record it as a replayable test."
 
@@ -168,7 +171,7 @@ Then ask your agent:
 | 📸 | `tapp_screenshot` | Whatever's on the sim right now, as an inline image. |
 | 🌳 | `tapp_ui_tree` | The accessibility tree of the current screen (ids, labels, hittability). |
 | 🕹 | `tapp_session_start/act/end` | **Interactive driving** — the Playwright loop. App launches once; each act (tap/type/swipe/back/wait) returns the fresh tree. |
-| 🧪 | `tapp_run_qa` | **Autonomous QA** — explores with no authored test, returns `{verdict, releaseScore, findings[]}` (`releaseScore` is `null` for exploratory web). Takes `appBundleId` (iOS), `androidAppId` (Android), or `url` (web). |
+| 🔭 | `tapp_explore` | **Autonomous exploration** — explores with no authored test, returns an observation `{kind, headline, inconclusive, findingCounts, findings[]}` (no verdict/score — the deterministic gate judges). Takes `appBundleId` (iOS), `androidAppId` (Android), or `url` (web). |
 | 🧭 | `tapp_init` | **Repository import** — detect targets; optionally explore a real surface; persist the shared UI Map; construct the evidence-classified model and grounded release plan. |
 | 👤 | `tapp_actor_config` | **Actor/session setup** — store roles, isolation/provisioning, and environment-variable names without accepting or persisting credential values. |
 | ✅ | `tapp_release_plan` | **Release-plan lifecycle** — inspect, approve/reject/defer, generate, real-target validate, and explicitly promote proposed guarantees without silent test edits. |
@@ -189,49 +192,43 @@ The desktop Coverage view reads the same `.tapp/application-model.json`,
 does not maintain a separate product model. Map nodes identify both the real launch entry and the
 deterministic per-platform navigation root used for bounded changed-surface replay.
 
-## The verdict you can trust
-
-**Adaptive exploration, deterministic judgment.** Exploration is adaptive — two runs may
-traverse different paths through your app. Judgment is deterministic: the same evidence
-trace always produces the same findings and verdict — no LLM variability
-in the decision loop. PR gating keys on the **regression diff**
-(stable finding signatures vs. a baseline), so it reacts to what *changed*, not to
-run-to-run path variance. For critical user journeys, committed **Tasks and Flows** provide the stable CI
-suite: reusable semantic actions, exact assertions, condition-based waits, fresh launch state, bounded timeouts,
-and evidence on failure. We call this *flake-resistant*, not magically flake-free—backend outages,
-unstable test data, and poorly identified controls can still make any E2E test fail.
-
-**Native has a heuristic release score; exploratory web does not.** The native 0–100 number comes
-from fixed deductions and is not calibrated probability. Web reports deterministic findings,
-advisory budget-capped control probes, and concrete coverage instead of compressing those unlike
-signals into a scalar. Committed Flows, Tasks, contracts, and baseline regressions provide the web
-merge decision.
-
-`tapp_run_qa` explores like a user — accessibility surfaces on iOS/Android and a real browser on web —
-and detects crashes, failed sign-ins, dead buttons, stuck loading screens, error surfaces,
-navigation loops, and dead ends (plus, on web: uncaught JS exceptions, failed/5xx requests,
-broken links and assets, and visible placeholder links with no destination). The verdict is
-**deterministic** (no LLM in the run loop) and **honest**:
-
-- `blocked` — a release-blocking issue was found.
-- `caution` — issues to review, or the run couldn't see enough.
-- `ready` — genuinely explored with no detected blockers in the checks that ran. **A shallow run
-  is never `ready`** — if the
-  app crashed on launch or a login wall blocked exploration, you get `inconclusive: true`,
-  not a false pass. Absence of findings is not a pass.
-
-Web beta presents a `ready` result as **AUTOMATED CHECKS COMPLETE**, not “ship-ready,” and displays
-no scalar score. Exhaustive checks on each exercised page drive the verdict; sampled control probes
-remain visible findings but are advisory. The report
-explicitly excludes content/claim accuracy, privacy and API data minimization, brand/SEO
-consistency, and subjective visual credibility. Those require reviewed contracts, privacy review,
-or human/vision judgment; an exploratory crawl must not imply they were validated.
+## Observation you can read, judgment you can trust
+
+**Exploration observes; the gate judges.** Exploration is adaptive — two runs may traverse different
+paths — and it produces an **observation**, never a ship verdict: findings + coverage + evidence. The
+**gate** is deterministic: the same evidence trace, contracts, and baseline always produce the same
+outcome — `pass`, `fail`, or `inconclusive` — with no LLM in the decision loop. PR gating keys on the
+**regression diff** (stable finding signatures vs. a baseline), so it reacts to what *changed*, not to
+run-to-run path variance. For critical user journeys, committed **Tasks and Flows** provide the stable
+CI suite: reusable semantic actions, exact assertions, condition-based waits, fresh launch state,
+bounded timeouts, and evidence on failure. We call this *flake-resistant*, not magically flake-free —
+backend outages, unstable test data, and poorly identified controls can still make any E2E test fail.
+
+**No scores, no soft verdicts.** Exploration reports deterministic findings, advisory budget-capped
+control probes, and concrete coverage — never a 0–100 number or a "ready/ship" label a shallow crawl
+can't honestly earn. The merge decision comes only from the gate: reviewed contracts, committed
+Flows/Scenarios, and baseline regressions.
+
+`tapp_explore` explores like a user — accessibility surfaces on iOS/Android and a real browser on web
+— and detects crashes, failed sign-ins, dead buttons, stuck loading screens, error surfaces,
+navigation loops, and dead ends (plus, on web: uncaught JS exceptions, failed/5xx requests, broken
+links and assets, and visible placeholder links with no destination). The observation is honest about
+its limits:
+
+- It **surfaces findings**; it does not pronounce "ready." **A shallow run is never a pass** — if the
+  app crashed on launch or a login wall blocked exploration, you get `inconclusive: true`, not a false
+  green. Absence of findings is not a pass.
+- The **gate** turns findings + coverage + your reviewed contracts + a baseline into `pass` / `fail` /
+  `inconclusive` (`inconclusive` fails closed). Deterministic — no LLM in the run loop.
+- An exploratory crawl explicitly **excludes** content/claim accuracy, privacy and API data
+  minimization, brand/SEO consistency, and subjective visual credibility. Those require reviewed
+  contracts, privacy review, or human/vision judgment; a crawl must not imply they were validated.
 
 For a business guarantee such as “every coach is insured,” use a deterministic app-owned verifier
 endpoint that returns success only when the invariant holds, then require that status and the
 customer-visible claim in a release contract. The current DSL does not yet read arbitrary JSON
 response bodies or compare a cross-origin API payload directly with page copy; use a verifier or an
-explicit CI preflight rather than assuming autonomous QA inferred the guarantee.
+explicit CI preflight rather than assuming exploration inferred the guarantee.
 
 Apps behind a login? Pass `testEmail`/`testPassword` (typed into the login form automatically),
 `appLaunchArgs` (e.g. `["--uitesting"]` if your app supports a bypass), or explicit `loginSteps`
@@ -350,30 +347,30 @@ your agent proves its UI work instead of claiming it:
 This repo uses tapp (https://github.com/aarwitz/tapp) to verify UI work on a real app surface
 (iOS simulator, Android emulator/device, or a browser for web). After any UI change, run `npx -y @aarwitz/tapp open` from the
 repo root (it finds and builds the Xcode project itself) and look at the screenshot it saves as
-proof. Before declaring a feature done, run `npx -y @aarwitz/tapp qa` (or `qa <url>` for web) and
-report the ship/no-ship verdict. A change is not "done" until it has been seen working.
+proof. Before declaring a feature done, run `npx -y @aarwitz/tapp explore` (or `explore <url>` for web)
+and report the findings + evidence. A change is not "done" until it has been seen working.
 (If the tapp MCP server is connected, the tapp_* tools do the same with inline screenshots —
-tapp_build builds + installs the app and returns the bundle id for tapp_run_qa.)
+tapp_build builds + installs the app and returns the bundle id for tapp_explore.)
 ```
 
 ## How it works
 
 Every driver speaks one protocol: structured `OCQA_*` markers (state, actions, issues,
-transitions) that the judgment layer parses into trees, screenshots, findings, and the verdict.
+transitions) that the engine parses into trees, screenshots, findings, coverage, and the gate outcome.
 On **iOS**, a generic **XCUITest harness** attaches to any app by bundle id — no SDK or app code
 changes — and acts through the accessibility tree. On **Android**, ADB + UIAutomator provide the
 same black-box driver contract. On **web** (beta), a deterministic **Playwright crawler** does the
 same in a real browser. Same detectors' spirit,
-same dedup, same regression gate, same honest verdict. Core exploration, evidence collection, and
-verdict calculation run entirely locally — no telemetry, nothing phones home. Optional AI
+same dedup, same regression gate, same honest `pass`/`fail`/`inconclusive` outcome. Core exploration,
+evidence collection, and gate evaluation run entirely locally — no telemetry, nothing phones home. Optional AI
 features are explicit: finding enrichment requires `TAPP_ENABLE_REMOTE_AI=1` (an ambient
 API key alone never changes data handling), and AI flow generation / `assert_ai` only run
 when you invoke them; these send selected metadata (screen names, finding titles) to your
 configured model provider. Runtime configuration uses `TAPP_*` environment variables. Repository
-artifacts live under `.tapp/`, and desktop run configuration uses `.tapp.yml`. Existing
-`.autotap/`, `.autotap.yml`, and `AUTOTAP_*` inputs remain readable as migration fallbacks; when
-both names exist, Tapp uses the canonical one. Rename the old directory/config in your next
-reviewed repository change—no secrets or evidence formats need to be rewritten.
+artifacts live under `.tapp/`, and desktop run configuration uses `.tapp.yml`. These are the only
+names Tapp reads: the pre-rename `.autotap/`, `.autotap.yml`, and `AUTOTAP_*` inputs are no longer
+supported. If you still have an old directory or config, rename it to the `.tapp` names in a
+reviewed change—no secrets or evidence formats need to be rewritten.
 
 Committed Flow replay, recording a driven session, autonomous exploration, exact assertions,
 regression comparison, and CI gating require **no API key and no coding agent at runtime**. AI is