@aarwitz/tapp 0.17.5 → 0.17.7

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "tapp",
   "description": "Give Claude hands and eyes on iOS, Android, and web apps, with exploration, replayable flows, evidence, and deterministic CI gates.",
-  "version": "0.17.5",
+  "version": "0.17.7",
   "author": {
     "name": "Aaron Horowitz",
     "url": "https://github.com/aarwitz"
@@ -24,7 +24,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@aarwitz/tapp@0.17.5",
+        "@aarwitz/tapp@0.17.7",
         "mcp"
       ],
       "cwd": "${CLAUDE_PROJECT_DIR}"

package/README.md

@@ -348,7 +348,7 @@ jobs:
     timeout-minutes: 45
     steps:
       - uses: actions/checkout@v4
-      - uses: aarwitz/tapp@v0.17.5 # or pin the reviewed release commit SHA
+      - uses: aarwitz/tapp@v0.17.7 # or pin the reviewed release commit SHA
         with:
           project: MyApp.xcodeproj # or MyApp.xcworkspace
           scheme: MyApp
@@ -398,7 +398,7 @@ Android CI runs on Linux with an emulator/device already connected. The Action c
 or accept a prebuilt one:
 
 ```yaml
-- uses: aarwitz/tapp@v0.17.5 # or pin the reviewed release commit SHA
+- uses: aarwitz/tapp@v0.17.7 # or pin the reviewed release commit SHA
   with:
     platform: android
     android-app-id: com.acme.app

package/bin/tapp.js

@@ -270,10 +270,10 @@ function safeCommandUsage(verb) {
     shot: "tapp shot [--out FILE]",
     apps: "tapp apps",
     build: "tapp build [repo] [--scheme NAME] [--configuration NAME]",
-    flow: "tapp flow example\ntapp flow validate FILE [--platform PLATFORM] [--map FILE]\ntapp flow run FILE [--actor NAME] [--email VALUE] [--password VALUE] [--device \"iPhone 13\"] [--viewport 390x844]",
+    flow: "tapp flow example\ntapp flow validate FILE [--platform PLATFORM] [--map FILE]\ntapp flow run FILE [--actor NAME] [--email VALUE] [--password VALUE] [--device \"iPhone 13\"] [--viewport 390x844]\n  Exit codes: 0 replay passed · 1 replay failed · 2 infrastructure/usage error",
     task: "tapp task validate FILE [--platform PLATFORM] [--map FILE]\ntapp task compile FILE --platform PLATFORM [--inputs JSON] [--out FILE]\ntapp task run FILE --platform PLATFORM [--url URL|--bundle-id ID|--app-id ID] [--inputs JSON]",
-    contract: "tapp contract validate FILE [--platform PLATFORM] [--map FILE]\ntapp contract compile FILE --platform PLATFORM [--out FILE]\ntapp contract run FILE --platform PLATFORM [--url URL|--bundle-id ID|--app-id ID]",
-    scenario: "tapp scenario validate FILE [--project-dir DIR]\ntapp scenario run FILE --platform web --url URL [--project-dir DIR]",
+    contract: "tapp contract validate FILE [--platform PLATFORM] [--map FILE]\ntapp contract compile FILE --platform PLATFORM [--out FILE]\ntapp contract run FILE --platform PLATFORM [--url URL|--bundle-id ID|--app-id ID]\n  Exit codes: 0 contract held · 1 contract failed · 2 infrastructure/usage error",
+    scenario: "tapp scenario validate FILE [--project-dir DIR]\ntapp scenario run FILE --platform web --url URL [--project-dir DIR]\n  Exit codes: 0 scenario passed · 1 scenario failed · 2 infrastructure/usage error",
     map: "tapp map build MARKERS [--platform PLATFORM] [--out FILE] [--replace]\ntapp map inspect [FILE]\ntapp map diff BEFORE AFTER [--comparable]",
     pr: "tapp pr plan [--base REF|--changed-files FILE] [--head REF] [--platform PLATFORM] [--out FILE]\ntapp pr gate PLAN [gate target/options]\ntapp pr adopt PLAN --item ID [--project-dir DIR]",
     plan: "tapp plan show [FILE]\ntapp plan review [FILE] --approve NAME[,NAME] --reject NAME[,NAME] --defer NAME[,NAME]\ntapp plan generate|validate|promote [FILE] [options]",
@@ -282,7 +282,7 @@ function safeCommandUsage(verb) {
     actor: "tapp actor set NAME --email-env ENV --password-env ENV [--replace] [--project-dir DIR]\ntapp actor list [repo]",
     app: "tapp app [repo] [--no-open] [--port PORT]",
     report: "tapp report [captureId|latest]",
-    doctor: "tapp doctor",
+    doctor: "tapp doctor [--json]\n  Exit codes: 0 environment healthy · 1 blocked (fix ❌ items)",
     install: "tapp install",
     mcp: "tapp mcp",
   };
@@ -1425,37 +1425,51 @@ switch (command) {
   }
 
   case "doctor": {
-    console.log(`tapp v${pkg.version} — doctor\n`);
+    const { flags: doctorFlags } = parseVerbArgs(rest);
+    const jsonMode = doctorFlags.json === true;
+    const report = { version: pkg.version, healthy: true, node: {}, python3: {}, disk: {},
+      platforms: { ios: {}, android: {}, web: {} }, home: tappHome };
+    const say = (line) => { if (!jsonMode) console.log(line); };
+    const sayOk = (label, detail = "") => { if (!jsonMode) ok(label, detail); };
+    const sayBad = (label, detail = "") => { if (!jsonMode) bad(label, detail); };
+    say(`tapp v${pkg.version} — doctor\n`);
     let healthy = true;
 
     const major = Number(process.versions.node.split(".")[0]);
-    major >= 18 ? ok("Node", `v${process.versions.node}`) : (bad("Node", `v${process.versions.node} (need >= 18)`), (healthy = false));
+    report.node = { ok: major >= 18, version: process.versions.node };
+    major >= 18 ? sayOk("Node", `v${process.versions.node}`) : (sayBad("Node", `v${process.versions.node} (need >= 18)`), (healthy = false));
 
     const python = run("python3", ["--version"]);
-    python.code === 0 ? ok("python3", `${python.stdout} (used by Flows)`) : bad("python3", "not found — Flow replay needs python3 + pyyaml (everything else works)");
+    report.python3 = { ok: python.code === 0, version: python.code === 0 ? python.stdout : null };
+    python.code === 0 ? sayOk("python3", `${python.stdout} (used by Flows)`) : sayBad("python3", "not found — Flow replay needs python3 + pyyaml (everything else works)");
 
     const { storagePreflight } = await import(path.join(packageRoot, "mcp-server", "src", "environment-preflight.js"));
     const storage = storagePreflight(tappHome);
-    if (storage.level === "blocked") { bad("Disk space", storage.message); healthy = false; }
-    else if (storage.level === "warning") console.log(`  ⚠️  Disk space — ${storage.message}`);
-    else if (storage.level === "ok") ok("Disk space", storage.message);
-    else console.log(`  ⬜ Disk space — ${storage.message || "could not be checked"}`);
+    report.disk = { level: storage.level, message: storage.message || null };
+    if (storage.level === "blocked") { sayBad("Disk space", storage.message); healthy = false; }
+    else if (storage.level === "warning") say(`  ⚠️  Disk space — ${storage.message}`);
+    else if (storage.level === "ok") sayOk("Disk space", storage.message);
+    else say(`  ⬜ Disk space — ${storage.message || "could not be checked"}`);
 
-    console.log("\n  Platforms:");
+    say("\n  Platforms:");
     if (process.platform === "darwin") {
       const xcode = run("xcode-select", ["-p"]);
       const simctl = run("xcrun", ["simctl", "help"]);
       if (xcode.code === 0 && simctl.code === 0) {
         const ver = run("xcodebuild", ["-version"]).stdout.split("\n")[0];
         const booted = bootedSims();
-        ok("iOS", `${ver || "Xcode"}; ${booted.length ? `${booted[0].name} booted` : "no simulator booted yet"}`);
         const xctestrun = harnessXctestrun();
-        xctestrun ? ok("iOS harness cache", xctestrun) : console.log("  ⬜ iOS harness cache — builds on first use (or: npx -y @aarwitz/tapp@latest install)");
+        report.platforms.ios = { available: true, xcode: ver || "Xcode",
+          bootedSimulator: booted.length ? booted[0].name : null, harnessCache: Boolean(xctestrun) };
+        sayOk("iOS", `${ver || "Xcode"}; ${booted.length ? `${booted[0].name} booted` : "no simulator booted yet"}`);
+        xctestrun ? sayOk("iOS harness cache", xctestrun) : say("  ⬜ iOS harness cache — builds on first use (or: npx -y @aarwitz/tapp@latest install)");
       } else {
-        console.log("  ⬜ iOS — unavailable (install Xcode + simulator runtime)");
+        report.platforms.ios = { available: false, reason: "install Xcode + simulator runtime" };
+        say("  ⬜ iOS — unavailable (install Xcode + simulator runtime)");
       }
     } else {
-      console.log(`  ⬜ iOS — requires macOS (this host: ${process.platform})`);
+      report.platforms.ios = { available: false, reason: `requires macOS (this host: ${process.platform})` };
+      say(`  ⬜ iOS — requires macOS (this host: ${process.platform})`);
     }
 
     const { resolveAdbPath, resolveAndroidSdkRoot } = await import(path.join(packageRoot, "mcp-server", "src", "android-driver.js"));
@@ -1463,17 +1477,20 @@ switch (command) {
     const adb = adbPath ? run(adbPath, ["devices"]) : { code: 1, stdout: "" };
     if (adb.code === 0) {
       const devices = adb.stdout.split(/\r?\n/).slice(1).filter((line) => /\sdevice(?:\s|$)/.test(line));
-      ok("Android", devices.length ? `${devices.length} connected emulator/device` : "adb available; no device connected");
+      report.platforms.android = { adb: true, devicesConnected: devices.length };
+      sayOk("Android", devices.length ? `${devices.length} connected emulator/device` : "adb available; no device connected");
     } else {
-      console.log("  ⬜ Android — adb not found (install Android SDK platform-tools)");
+      report.platforms.android = { adb: false, devicesConnected: 0 };
+      say("  ⬜ Android — adb not found (install Android SDK platform-tools)");
     }
     const { resolveJavaRuntime } = await import(path.join(packageRoot, "mcp-server", "src", "environment-preflight.js"));
     const java = resolveJavaRuntime();
     const androidSdkRoot = resolveAndroidSdkRoot();
-    if (java && androidSdkRoot) ok("Android source builds", `${java.version || java.javaHome}; SDK ${androidSdkRoot}`);
+    report.platforms.android.sourceBuilds = Boolean(java && androidSdkRoot);
+    if (java && androidSdkRoot) sayOk("Android source builds", `${java.version || java.javaHome}; SDK ${androidSdkRoot}`);
     else {
       const missing = [!java ? "JDK 17" : "", !androidSdkRoot ? "Android SDK root" : ""].filter(Boolean).join(" and ");
-      console.log(`  ⬜ Android source builds — install/configure ${missing} (prebuilt APK testing still works)`);
+      say(`  ⬜ Android source builds — install/configure ${missing} (prebuilt APK testing still works)`);
     }
 
     try {
@@ -1481,18 +1498,26 @@ switch (command) {
       let executable = "";
       try { executable = chromium.executablePath(); } catch { /* report the missing browser below */ }
       if (executable && fs.existsSync(executable)) {
-        ok("Web", `Playwright + Chromium (${executable})`);
+        report.platforms.web = { available: true, chromium: executable };
+        sayOk("Web", `Playwright + Chromium (${executable})`);
       } else {
-        console.log("  ⬜ Web — Playwright installed; Chromium browser missing (run: npx playwright install chromium)");
+        report.platforms.web = { available: false, reason: "Chromium browser missing (run: npx playwright install chromium)" };
+        say("  ⬜ Web — Playwright installed; Chromium browser missing (run: npx playwright install chromium)");
       }
     } catch {
-      console.log("  ⬜ Web — install Playwright in the app workspace: npm install -D playwright && npx playwright install chromium");
+      report.platforms.web = { available: false, reason: "Playwright not installed" };
+      say("  ⬜ Web — install Playwright in the app workspace: npm install -D playwright && npx playwright install chromium");
     }
 
-    console.log(`\n  Home: ${tappHome}`);
-    console.log(healthy
-      ? "\nReady. Start with:\n  npx -y @aarwitz/tapp@latest open [target]\n  npx -y @aarwitz/tapp@latest explore [target]"
-      : "\nFix the ❌ items above, then re-run: npx -y @aarwitz/tapp@latest doctor");
+    report.healthy = healthy;
+    if (jsonMode) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      console.log(`\n  Home: ${tappHome}`);
+      console.log(healthy
+        ? "\nReady. Start with:\n  npx -y @aarwitz/tapp@latest open [target]\n  npx -y @aarwitz/tapp@latest explore [target]"
+        : "\nFix the ❌ items above, then re-run: npx -y @aarwitz/tapp@latest doctor");
+    }
     process.exit(healthy ? 0 : 1);
   }
 

package/docs/scenarios.md

@@ -74,7 +74,7 @@ tapp ci --platform web --url http://127.0.0.1:4180 \
 GitHub Action:
 
 ```yaml
-- uses: aarwitz/tapp@v0.17.5 # or pin the reviewed release commit SHA
+- uses: aarwitz/tapp@v0.17.7 # or pin the reviewed release commit SHA
   with:
     platform: web
     url: http://127.0.0.1:4180

package/mcp-server/src/ci-report.js

@@ -16,7 +16,7 @@
 //                         [--pr-plan <plan.json>]           # selected PR contract execution manifest
 //                         [--project-dir <repo> --maintenance-url <url>]
 //                                                           # optional disposable web patch replay
-//                         [--fail-on <gate|absolute|any>]    # default: gate
+//                         [--fail-on <gate|absolute|any|high|medium>]  # default: gate (web CLI defaults to medium)
 //
 // Gate policy (--fail-on):
 //   gate     fail when the run introduced NEW high/critical findings vs. the baseline
@@ -25,6 +25,9 @@
 //   absolute fail on any current-run deterministic findings-block (critical / risk threshold) or an
 //            inconclusive run, or any failed suite — no baseline needed.
 //   any      fail on any finding at all, or any suite failure. Strictest.
+//   high     fail on any deterministic finding at high/critical severity (absolute; no baseline).
+//   medium   fail on any deterministic finding at medium severity or above. The `tapp ci` CLI
+//            defaults web targets to this: on a website, a broken link IS the release blocker.
 import fs from "fs";
 import path from "node:path";
 import { execSync } from "node:child_process";
@@ -61,8 +64,8 @@ function parseArgs(argv) {
     console.error("Required: --markers <ocqa-markers.txt>");
     process.exit(2);
   }
-  if (!["gate", "absolute", "any"].includes(args.failOn)) {
-    console.error(`--fail-on must be gate|absolute|any, got: ${args.failOn}`);
+  if (!["gate", "absolute", "any", "high", "medium"].includes(args.failOn)) {
+    console.error(`--fail-on must be gate|absolute|any|high|medium, got: ${args.failOn}`);
     process.exit(2);
   }
   return args;
@@ -175,6 +178,7 @@ function loadBaseline(baselinePath) {
     actionsPerformed: parsed.actionsPerformed || 0,
     platform: parsed.baselineIdentity?.platform || parsed.platform || null,
     targetKey: parsed.baselineIdentity?.targetId || parsed.targetKey || null,
+    capture: parsed.capture || null,
   };
 }
 
@@ -396,6 +400,10 @@ function renderMarkdown(report, regression, flows, scenarios, contracts, prPlan,
     lines.push(`### Since baseline — ${regFailed ? "🔴 regression gate FAILED" : "🟢 regression gate passed"}`);
     lines.push(`+${regression.counts.new} new · ${regression.counts.persisting} persisting · ${regression.counts.resolved} resolved` +
       (regFailed ? ` — **${newCritical} new critical, ${newHigh} new high**` : ""));
+    if (regression.captureMismatch) {
+      const describe = (c) => [c?.device, c?.viewport ? `${c.viewport.width}x${c.viewport.height}` : null, c?.deviceScaleFactor ? `@${c.deviceScaleFactor}x` : null].filter(Boolean).join(" ") || "unknown";
+      lines.push(`⚠️ **Capture mismatch**: baseline was captured at ${describe(regression.captureMismatch.baseline)}, this run at ${describe(regression.captureMismatch.current)}. "Resolved" findings may reflect layout differences at the new size, not fixes — re-baseline at the same device/viewport to compare honestly.`);
+    }
     for (const f of regression.newFindings) {
       lines.push(`- NEW ${SEV_ICON[f.severity] || ""} ${f.severity}: ${f.title} (${f.screen ?? "—"})`);
     }
@@ -477,10 +485,22 @@ function renderMarkdown(report, regression, flows, scenarios, contracts, prPlan,
   }
   lines.push("");
   const badge = GATE_BADGE[gate.outcome] || (gate.failed ? "🔴 FAIL" : "🟢 PASS");
-  lines.push(`**Gate (${gate.policy}): ${badge}**${gate.reasons.length ? " — " + gate.reasons.join("; ") : ""}`);
+  // A PASS must state what it chose to ignore — a green banner over known findings without
+  // saying so is exactly the dishonest verdict this product refuses to render.
+  const ignored = gate.outcome === "pass" && report.deterministicFindingCounts
+    ? ["high", "medium", "low"].map((sev) => [sev, report.deterministicFindingCounts[sev] || 0]).filter(([, n]) => n > 0)
+    : [];
+  const ignoredNote = ignored.length
+    ? ` — ${ignored.reduce((n, [, c]) => n + c, 0)} deterministic finding(s) below the fail threshold (${ignored.map(([sev, n]) => `${n} ${sev}`).join(", ")})`
+    : "";
+  lines.push(`**Gate (${gate.policy}): ${badge}**${gate.reasons.length ? " — " + gate.reasons.join("; ") : ""}${ignoredNote}`);
   // The gate is only authoritative about what it actually ran — record the scope explicitly.
   const rev = gate.revision?.sha ? `${String(gate.revision.sha).slice(0, 12)}${gate.revision.dirty ? "-dirty" : ""}` : "unknown";
-  lines.push(`_target: ${gate.target || "—"} · revision: ${rev} · policy: ${gate.policy} v${gate.policyVersion || "?"}_`);
+  const captured = report.capture
+    ? ` · capture: ${[report.capture.device, report.capture.viewport ? `${report.capture.viewport.width}x${report.capture.viewport.height}` : null, report.capture.deviceScaleFactor ? `@${report.capture.deviceScaleFactor}x` : null].filter(Boolean).join(" ")}`
+    : "";
+  const stableId = report.targetKey && report.targetKey !== gate.target ? ` (${report.targetKey})` : "";
+  lines.push(`_target: ${gate.target || "—"}${stableId} · revision: ${rev} · policy: ${gate.policy} v${gate.policyVersion || "?"}${captured}_`);
   if (Array.isArray(gate.checked) && gate.checked.length) lines.push(`_Checked: ${gate.checked.join(" · ")}_`);
   if (Array.isArray(gate.notChecked) && gate.notChecked.length) lines.push(`_Not checked: ${gate.notChecked.join(" · ")}_`);
   return lines.join("\n");
@@ -539,6 +559,12 @@ if (collapsed.length) {
   report.headline = `${collapsed.length} screen(s) regressed vs. baseline (content collapsed or became unreachable).`;
 }
 const regression = computeRegression(report.findings, baseline?.findings ?? null);
+// A baseline captured at a different device/viewport is a layout comparison, not a regression
+// signal: a phone run legitimately hides desktop nav links, so its "resolved" list lies. Keep
+// the diff (new findings still gate) but stamp the mismatch so every consumer can see it.
+if (regression && baseline?.capture && report.capture && JSON.stringify(baseline.capture) !== JSON.stringify(report.capture)) {
+  regression.captureMismatch = { baseline: baseline.capture, current: report.capture };
+}
 const runs = args.flowLogs.map(parseFlowLog);
 const contracts = runs.filter((run) => run.kind === "release-contract");
 const flows = runs.filter((run) => !["scenario", "release-contract"].includes(run.kind));
@@ -561,7 +587,9 @@ try {
 const decision = evaluateGate({ report, regression, flows, scenarios, contracts, prPlan, baseline, failOn: args.failOn });
 const gate = {
   ...decision,
-  target: args.targetKey || report.target || null,
+  // Display identity is the URL/bundle the run exercised; the stable application-model id
+  // stays on report.targetKey for baseline matching (a hash is not a target name).
+  target: report.target || args.targetKey || null,
   revision: gitRevision(args.projectDir),
   checked: report.checkedFor,
   notChecked: report.notChecked,

package/mcp-server/src/html-report.js

@@ -125,6 +125,9 @@ ${r.conditionsNotReached?.length ? `<div><h2>Conditions not reached</h2><ul>${sc
   .scope ul { margin-top: 0; padding-left: 1.2rem; }
   .sev { color: #fff; border-radius: 4px; padding: 0.05rem 0.45rem; font-size: 0.78rem; font-weight: 600; margin-right: 0.4rem; }
   ul.findings { padding-left: 1.1rem; } ul.findings li { margin-bottom: 0.6rem; }
+  table.trace { border-collapse: collapse; font-size: 0.88rem; width: 100%; }
+  table.trace th, table.trace td { text-align: left; padding: 0.25rem 0.7rem 0.25rem 0; border-bottom: 1px solid #eceef1; }
+  table.trace th { color: #57606a; font-weight: 600; }
   .ai { color: #57606a; font-size: 0.88rem; margin: 0.15rem 0 0 0.2rem; }
   .dim { color: #57606a; }
   .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 0.8rem; }
@@ -137,6 +140,7 @@ ${r.conditionsNotReached?.length ? `<div><h2>Conditions not reached</h2><ul>${sc
 <h1>${esc(observationBadge(r))} <span class="dim">· ${esc(observationSummary(r))}</span></h1>
 <div class="meta">${esc(label)} · evidence page (observation, not a release decision)</div>
 ${r.platform === "web" ? `<div class="meta">Deterministic basis: ${r.deterministicFindingCounts?.total || 0} deterministic finding(s); ${r.sampledFindingCounts?.total || 0} sampled probe finding(s) are advisory.</div>` : ""}
+${r.capture ? `<div class="meta">Captured at ${esc([r.capture.device, r.capture.viewport ? `${r.capture.viewport.width}×${r.capture.viewport.height}` : null, r.capture.deviceScaleFactor ? `@${r.capture.deviceScaleFactor}x` : null].filter(Boolean).join(" "))} — every screenshot on this page shares these conditions.</div>` : ""}
 <div class="headline">${esc(r.headline)}</div>
 ${r.credentialWarning ? `<div class="warning">${esc(r.credentialWarning)}</div>` : ""}
 ${scopeHtml}
@@ -144,6 +148,10 @@ ${scopeHtml}
 <ul class="findings">
 ${findingsHtml}
 </ul>
+${Array.isArray(r.trace) && r.trace.length ? `<h2>Action trace — what was done, in order</h2>
+<table class="trace"><thead><tr><th>t</th><th>action</th><th>target</th><th>screen</th></tr></thead><tbody>
+${r.trace.map((a) => `<tr><td>${typeof a.t === "number" ? (a.t / 1000).toFixed(1) + "s" : "—"}</td><td>${esc(a.type || "")}</td><td>${esc(a.target || "")}</td><td>${esc(a.screen || "")}</td></tr>`).join("\n")}
+</tbody></table>` : ""}
 <h2>Evidence — every screen explored</h2>
 <div class="grid">
 ${shotsHtml || "<p class='dim'>No screenshots captured.</p>"}

package/mcp-server/src/index.js

@@ -1721,9 +1721,10 @@ async function writeRunUiMap({ markersPath, platform, target, runId, outDir }) {
 /** One-line "3 buttons · 2 fields · 8 text" breakdown of an accessibility element list. */
 function elementBreakdown(elements) {
   const has = (e, ...pats) => pats.some((p) => String(e.type || "").includes(p));
-  let buttons = 0, fields = 0, texts = 0, cells = 0, other = 0;
+  let buttons = 0, links = 0, fields = 0, texts = 0, cells = 0, other = 0;
   for (const e of elements || []) {
-    if (has(e, "Button", "rawValue: 9", "Link", "rawValue: 39")) buttons++;
+    if (has(e, "Link", "rawValue: 39")) links++;
+    else if (has(e, "Button", "rawValue: 9")) buttons++;
     else if (has(e, "TextField", "rawValue: 49", "rawValue: 50", "SecureTextField")) fields++;
     else if (has(e, "StaticText", "rawValue: 48")) texts++;
     else if (has(e, "Cell", "rawValue: 75")) cells++;
@@ -1731,6 +1732,7 @@ function elementBreakdown(elements) {
   }
   return [
     buttons && `${buttons} button${buttons > 1 ? "s" : ""}`,
+    links && `${links} link${links > 1 ? "s" : ""}`,
     fields && `${fields} field${fields > 1 ? "s" : ""}`,
     cells && `${cells} cell${cells > 1 ? "s" : ""}`,
     texts && `${texts} text`,
@@ -1740,13 +1742,15 @@ function elementBreakdown(elements) {
 /** Scannable "Read screen X — N elements (...)" readout, plus the tappable/typeable controls. */
 export function formatScreen(screenTitle, elements) {
   const els = elements || [];
-  const interactable = els.filter((e) => e.isEnabled !== false && (String(e.type).includes("Button") || String(e.type).includes("rawValue: 9") || String(e.type).includes("TextField") || String(e.type).includes("rawValue: 49") || String(e.type).includes("rawValue: 50") || String(e.type).includes("Cell") || String(e.type).includes("rawValue: 75")));
-  const labels = interactable
+  const interactable = els.filter((e) => e.isEnabled !== false && (String(e.type).includes("Button") || String(e.type).includes("Link") || String(e.type).includes("rawValue: 9") || String(e.type).includes("TextField") || String(e.type).includes("rawValue: 49") || String(e.type).includes("rawValue: 50") || String(e.type).includes("Cell") || String(e.type).includes("rawValue: 75")));
+  const allLabels = interactable
     .map((e) => (e.label || e.identifier || "").trim())
-    .filter((s) => s && s.length <= 40 && !s.includes("."))
-    .slice(0, 8);
+    .filter((s) => s && s.length <= 40 && !s.includes("."));
+  const labels = allLabels.slice(0, 8);
   const L = [`🌳 Read screen **${screenTitle || "Unknown"}** — ${els.length} elements (${elementBreakdown(els)})`];
-  if (labels.length) L.push("", "**Controls:** " + labels.map((l) => `\`${l}\``).join(" · "));
+  // A silently cut list reads as complete; say when it isn't.
+  if (labels.length) L.push("", "**Controls:** " + labels.map((l) => `\`${l}\``).join(" · ")
+    + (allLabels.length > labels.length ? ` · … and ${allLabels.length - labels.length} more` : ""));
   return L.join("\n");
 }
 

package/mcp-server/src/report.js

@@ -30,6 +30,7 @@ export function parseOcqaMarkers(markersFilePath) {
   const transitions = [];
   const issues = [];
   let complete = null;
+  let context = null;
 
   for (const line of lines) {
     if (!line.startsWith("OCQA_")) continue;
@@ -57,6 +58,7 @@ export function parseOcqaMarkers(markersFilePath) {
     if (category === "TRANSITION") transitions.push(parsed);
     if (category === "ISSUE") issues.push(parsed);
     if (category === "COMPLETE") complete = parsed;
+    if (category === "CONTEXT") context = parsed;
   }
 
   return {
@@ -72,6 +74,7 @@ export function parseOcqaMarkers(markersFilePath) {
       )
     ),
     complete,
+    context,
     actions,
     recentActions: actions.slice(-5),
     recentTransitions: transitions.slice(-5),
@@ -101,7 +104,11 @@ export const ISSUE_CATEGORY = {
   explore_timeout: "performance_timeout",
 };
 export const CRITICAL_ISSUE_TYPES = new Set(["crash"]);
-export const WEB_SAMPLED_ISSUE_TYPES = new Set(["unresponsive_element", "outbound_unavailable"]);
+// outbound_unavailable graduated to the deterministic tier in policy v4: since 0.17.6 the
+// outbound audit renders each link in the live browser, so the unavailable-shell phrase match
+// is a stable observation of the page, not a sampled probe — and a dead social link is exactly
+// the broken-link class the web fail-on default exists to block.
+export const WEB_SAMPLED_ISSUE_TYPES = new Set(["unresponsive_element"]);
 
 export function severityRank(s) {
   return { critical: 0, high: 1, medium: 2, low: 3 }[s] ?? 4;
@@ -295,6 +302,7 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
     : timeBudgetExhausted ? "time-budget-exhausted"
     : !coverageFloorMet ? "coverage-floor-not-met"
     : driverStop === "frontier-drained" ? "no-unexplored-in-scope-controls"
+    : driverStop === "probe-cap" ? "probe-cap-reached"
     : "completed";
 
   const headline = timeBudgetExhausted
@@ -320,12 +328,12 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
       "page errors (uncaught exceptions)", "failed/5xx requests", "broken links (404, same-origin crawl)",
       "placeholder links and anchors with no destination", "sampled dead-button probes (advisory)", "error text on pages", "load timeouts",
     ];
-    if (outbound && !outbound.skipped && (outbound.total || outbound.mailtos)) {
+    if (outbound && outbound.total) {
       checkedFor.push(outbound.total > outbound.checked
-        ? `outbound link reachability — DNS · HTTP · unavailable-shell heuristic (first ${outbound.checked} of ${outbound.total})`
-        : "outbound link reachability (DNS · HTTP · unavailable-shell heuristic)");
-      if (outbound.mailtos) checkedFor.push("mailto address domains (MX/A records)");
+        ? `outbound link reachability — browser-rendered · DNS · HTTP · unavailable-shell heuristic (first ${outbound.checked} of ${outbound.total})`
+        : "outbound link reachability (browser-rendered · DNS · HTTP · unavailable-shell heuristic)");
     }
+    if (outbound?.mailtos && !outbound.mailtoSkipped) checkedFor.push("mailto address domains (MX/A records)");
     notChecked = [
       "app-specific business logic (cover with Flows: record or generate, then assert)",
       "content and claim accuracy (including copy versus API data)",
@@ -335,8 +343,8 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
       "only the first few visible buttons per page are probed (web beta)",
       "content & reachability regressions require a baseline",
     ];
-    if (outbound?.skipped === "egress-policy") notChecked.push("outbound links and mailto domains (skipped by the public-egress policy)");
-    else if (!outbound || (!outbound.total && !outbound.mailtos)) conditionsNotReached.push("outbound links (none encountered this run)");
+    if (outbound?.mailtoSkipped === "egress-policy") notChecked.push("mailto address domains (MX lookups are skipped by the public-egress policy)");
+    if (!outbound || (!outbound.total && !outbound.mailtos)) conditionsNotReached.push("outbound links (none encountered this run)");
     if (inputFieldsEncountered.length && !loginAttempted) {
       notChecked.push(`form submission (${inputFieldsEncountered.reduce((n, s) => n + s.fields.length, 0)} field(s) catalogued, none submitted)`);
     }
@@ -400,6 +408,12 @@ export function buildQaReport(markersFilePath, { platform = "ios", target = null
         ...(action.reason ? { reason: action.reason } : {}),
       })),
     evidence: { markers: base.relativeMarkersFilePath },
+    // Capture conditions shared by every screenshot/marker in this run (web: from the driver's
+    // CONTEXT marker). A baseline diff across different captures is a layout comparison, not a
+    // regression signal — consumers must be able to see that.
+    capture: base.context && typeof base.context === "object"
+      ? { device: base.context.device || null, viewport: base.context.viewport || null, deviceScaleFactor: base.context.deviceScaleFactor ?? null }
+      : null,
     uiMap: null,
     comparison: null,
     checkedFor,
@@ -543,7 +557,11 @@ export function computeRegression(current, baseline) {
 // the evidence." Exit codes are the CI contract; precedence is fail > inconclusive > pass.
 export const GATE_EXIT = { pass: 0, fail: 1, error: 2, inconclusive: 3 };
 // Bump when the gate's decision semantics change (NOT the npm version). Recorded on every GateRun.
-export const GATE_POLICY_VERSION = "2";
+// v3: `failOn` gained severity thresholds ("high" | "medium") that block on any deterministic-tier
+// finding at or above that severity, and the CLI defaults web targets to `medium` — a 404 in the
+// nav is the release blocker on a website, and a field-tested green PASS over six deterministic
+// findings was exactly the dishonest verdict this product refuses to render.
+export const GATE_POLICY_VERSION = "4";
 
 // Pure gate evaluator: frozen evidence + policy → a GateRun decision. Extracted verbatim from the
 // former inline logic in ci-report.js so the `[char]` characterization tests keep passing — the
@@ -592,6 +610,13 @@ export function evaluateGate({ report, regression = null, flows = [], scenarios
     if (report.findingCounts.total > 0) fail(`${report.findingCounts.total} finding(s) (fail-on: any)`);
     // "any" is the strictest policy — an inconclusive run (evidence not obtained) must never pass it.
     if (report.inconclusive) inconclusive("run was inconclusive (coverage floor not met)");
+  } else if (failOn === "medium" || failOn === "high") {
+    // Severity thresholds are absolute over the deterministic tier: anything at or above the
+    // requested severity blocks, baseline or not. Sampled/advisory findings never participate.
+    const counts = report.deterministicFindingCounts || {};
+    const blocking = (counts.critical || 0) + (counts.high || 0) + (failOn === "medium" ? counts.medium || 0 : 0);
+    if (blocking > 0) fail(`${blocking} deterministic finding(s) at or above ${failOn} severity (fail-on: ${failOn})`);
+    if (report.inconclusive) inconclusive("run was inconclusive (coverage floor not met)");
   } else if (failOn === "absolute" || (failOn === "gate" && !regression)) {
     if (findingsBlock(report.deterministicFindingCounts, { inconclusive: report.inconclusive })) fail("blocking deterministic finding(s)");
     if (report.inconclusive) inconclusive("run was inconclusive (coverage floor not met)");

package/mcp-server/src/web-explorer.js

@@ -466,23 +466,26 @@ export async function inspectWebPage({ url, timeoutMs = NAV_TIMEOUT_MS, screensh
     }
     const observed = await page.evaluate(() => {
       const visible = (element) => element.offsetParent !== null;
-      const controls = [...document.querySelectorAll("button, a[href], input, textarea, select, [role=button], [role=tab], [role=checkbox], [role=switch]")]
+      const controls = [...document.querySelectorAll("button, a[href], input, textarea, select, summary, [role=button], [role=tab], [role=checkbox], [role=switch]")]
         .filter((element) => element.type !== "hidden" && visible(element))
         .slice(0, 80)
         .map((element) => {
           const tag = element.tagName.toLowerCase();
           const field = ["input", "textarea", "select"].includes(tag);
           const secure = element.type === "password";
-          const role = element.getAttribute("role") || (tag === "a" ? "link" : tag === "button" ? "button" : "");
+          const role = element.getAttribute("role") || (tag === "a" ? "link" : tag === "button" || tag === "summary" ? "button" : "");
           const label = (element.labels?.[0]?.textContent || element.getAttribute("aria-label") || element.textContent || element.placeholder || element.name || element.id || "").trim().slice(0, 120);
+          const box = element.getBoundingClientRect();
           return {
-            type: field ? (secure ? "SecureTextField" : "TextField") : "Button",
+            // `type` stays faithful so an agent follows links and presses buttons, not vice versa.
+            type: field ? (secure ? "SecureTextField" : "TextField") : tag === "a" ? "Link" : "Button",
             role,
             label,
             identifier: element.id || element.getAttribute("data-testid") || element.getAttribute("aria-label") || "",
             isEnabled: !element.disabled && element.getAttribute("aria-disabled") !== "true",
             hittable: true,
             secure,
+            rect: { x: Math.round(box.x), y: Math.round(box.y), width: Math.round(box.width), height: Math.round(box.height) },
           };
         })
         .filter((control) => control.label || control.identifier);
@@ -573,7 +576,12 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
 
   const { chromium, devices } = await loadPlaywright();
   const browser = await chromium.launch(webBrowserLaunchOptions(process.env, { watch }));
-  const context = await browser.newContext(webContextOptions({ device, viewport, devices }));
+  const captureProfile = webContextOptions({ device, viewport, devices });
+  // Evidence is only comparable when the capture conditions are on record: a desktop run and a
+  // phone run legitimately disagree about which nav links exist, and a baseline diff across
+  // them must be able to say so instead of reporting "resolved".
+  emit("CONTEXT", { ...(String(device || "").trim() ? { device: String(device).trim() } : {}), viewport: captureProfile.viewport, deviceScaleFactor: captureProfile.deviceScaleFactor ?? 1 });
+  const context = await browser.newContext(captureProfile);
   await installWebListenerTracking(context);
   if (watch) await installWebWatchUi(context);
   const page = await context.newPage();
@@ -581,9 +589,12 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
 
   const deadline = Date.now() + timeoutSec * 1000;
   const issues = []; // emitted immediately; kept for counting only
-  const issue = (type, severity, title, screen, target) => {
+  const issue = (type, severity, title, screen, target, sourceUrl) => {
     issues.push(type);
-    const pageUrl = page.url();
+    // Findings belong to the page that CARRIED the defect. Async detectors default to the
+    // current page; the post-crawl outbound audit passes the link's source page explicitly so
+    // a bad footer link is never attributed to whatever page happened to be visited last.
+    const pageUrl = sourceUrl || page.url();
     emit("ISSUE", { type, severity, title, screen, ...(target ? { target } : {}), ...(pageUrl && pageUrl !== "about:blank" ? { url: pageUrl } : {}) });
   };
 
@@ -628,6 +639,7 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
   const outboundLinks = new Map(); // href → { label, screen }
   const mailtoLinks = new Map(); // address → { screen }
   const outbound = { total: 0, checked: 0, mailtos: 0 };
+  let probeCapHit = false;
   let actions = 0;
   let screenCount = 0;
   let lastScreen = null;
@@ -930,14 +942,14 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
         try {
           if (/^mailto:/i.test(link.raw)) {
             const address = link.raw.replace(/^mailto:/i, "").split("?")[0].trim();
-            if (address.includes("@") && !mailtoLinks.has(address)) mailtoLinks.set(address, { screen: ob.screen });
+            if (address.includes("@") && !mailtoLinks.has(address)) mailtoLinks.set(address, { screen: ob.screen, sourceUrl: start.origin + ob.key });
             continue;
           }
           const u = new URL(link.href);
           if (!/^https?:$/.test(u.protocol)) continue;
           if (u.origin !== start.origin) {
             const clean = u.origin + u.pathname;
-            if (!outboundLinks.has(clean)) outboundLinks.set(clean, { label: link.label, screen: ob.screen });
+            if (!outboundLinks.has(clean)) outboundLinks.set(clean, { label: link.label, screen: ob.screen, sourceUrl: start.origin + ob.key });
             continue;
           }
           const key = u.pathname.replace(/\/+$/, "") + u.search || "/";
@@ -950,7 +962,9 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
       // Bounded button pass: click, watch for effect, flag dead controls (the web analog
       // of the iOS dead-button detector). Navigations are undone so BFS order holds.
       const buttons = page.locator("button:visible, [role=button]:visible, input[type=submit]:visible, summary:visible");
-      const n = Math.min(await buttons.count().catch(() => 0), BUTTONS_PER_PAGE);
+      const buttonTotal = await buttons.count().catch(() => 0);
+      const n = Math.min(buttonTotal, BUTTONS_PER_PAGE);
+      if (buttonTotal > BUTTONS_PER_PAGE) probeCapHit = true;
       for (let i = 0; i < n && actions < maxActions && Date.now() < deadline; i++) {
         const b = buttons.nth(i);
         const label = webControlLabel({
@@ -1000,56 +1014,65 @@ export async function exploreWeb({ url, maxActions = 40, timeoutSec = 300, outDi
       progress();
     }
 
-    // Post-crawl outbound audit: DNS + bounded HTTP for external links, MX for mailto.
-    // These calls leave the proxied browser, so the whole pass is skipped (and reported as
-    // not-checked) when the public-egress policy is enforced.
+    // Post-crawl outbound audit. Link checks run through the LIVE browser context: JS-rendered
+    // "unavailable" shells (Facebook et al.) are only visible to a real renderer, and browser
+    // navigation honors the egress proxy policy, so these checks never bypass it. Only the
+    // mailto MX lookups use node:dns and are therefore skipped under the enforced-egress policy.
     outbound.total = outboundLinks.size;
     outbound.mailtos = mailtoLinks.size;
-    if (process.env.TAPP_ENFORCE_PUBLIC_EGRESS === "1") {
-      outbound.skipped = "egress-policy";
-    } else if (outboundLinks.size || mailtoLinks.size) {
-      const dns = await import("node:dns/promises");
-      const hostResolvable = new Map();
-      const resolves = async (host) => {
-        if (!hostResolvable.has(host)) {
-          hostResolvable.set(host, await dns.lookup(host).then(() => true).catch(() => false));
-        }
-        return hostResolvable.get(host);
-      };
+    if (outboundLinks.size) {
+      const auditPage = await context.newPage();
+      auditPage.setDefaultTimeout(8000);
       const targets = [...outboundLinks.entries()].slice(0, OUTBOUND_LINK_LIMIT);
       outbound.checked = targets.length;
       for (const [href, meta] of targets) {
         if (Date.now() >= deadline) break;
-        const u = new URL(href);
-        if (!(await resolves(u.hostname))) {
-          issue("unresolvable_host", "medium", `Outbound link host does not resolve: ${u.hostname}`, meta.screen, href);
+        const nav = await auditPage.goto(href, { waitUntil: "domcontentloaded", timeout: 8000 })
+          .catch((error) => ({ navError: String(error && error.message || error) }));
+        if (nav && nav.navError) {
+          const dnsFailure = /ERR_NAME_NOT_RESOLVED/i.test(nav.navError);
+          issue("unresolvable_host", "medium",
+            dnsFailure
+              ? `Outbound link host does not resolve: ${new URL(href).hostname}`
+              : `Outbound link unreachable: ${href.slice(0, 100)} (${nav.navError.slice(0, 60)})`,
+            meta.screen, href, meta.sourceUrl);
           continue;
         }
-        try {
-          const res = await fetch(href, { redirect: "follow", signal: AbortSignal.timeout(6000), headers: { "user-agent": "Mozilla/5.0 (compatible; tapp-link-audit)" } });
-          if (res.status >= 400) {
-            issue("broken_link", "medium", `Outbound link returns HTTP ${res.status}: ${href.slice(0, 100)}`, meta.screen, href);
-          } else {
-            const phrase = webUnavailableShellPhrase(await res.text().catch(() => ""));
-            if (phrase) issue("outbound_unavailable", "low", `Outbound link returns 200 but shows "${phrase}": ${href.slice(0, 100)}`, meta.screen, href);
-          }
-        } catch (error) {
-          issue("unresolvable_host", "medium", `Outbound link unreachable: ${href.slice(0, 100)}`, meta.screen, href);
+        if (nav && typeof nav.status === "function" && nav.status() >= 400) {
+          issue("broken_link", "medium", `Outbound link returns HTTP ${nav.status()}: ${href.slice(0, 100)}`, meta.screen, href, meta.sourceUrl);
+          continue;
         }
+        await auditPage.waitForTimeout(400); // let client-rendered shells paint their copy
+        const text = await auditPage.evaluate(() => (document.body && document.body.innerText || "").slice(0, 120000)).catch(() => "");
+        const phrase = webUnavailableShellPhrase(text);
+        if (phrase) issue("outbound_unavailable", "medium", `Outbound link returns 200 but shows "${phrase}": ${href.slice(0, 100)}`, meta.screen, href, meta.sourceUrl);
       }
-      for (const [address, meta] of mailtoLinks) {
-        if (Date.now() >= deadline) break;
-        const domain = (address.split("@")[1] || "").toLowerCase();
-        if (!domain) continue;
-        // RFC 5321 implicit-MX: a domain with no MX but an A/AAAA record can still receive.
-        const deliverable = await dns.resolveMx(domain).then((records) => records.length > 0).catch(() => false)
-          || await dns.lookup(domain).then(() => true).catch(() => false);
-        if (!deliverable) issue("mailto_no_mx", "medium", `mailto: domain cannot receive email (no MX or address record): ${address}`, meta.screen, address);
+      await auditPage.close().catch(() => {});
+    }
+    if (mailtoLinks.size) {
+      if (process.env.TAPP_ENFORCE_PUBLIC_EGRESS === "1") {
+        outbound.mailtoSkipped = "egress-policy"; // node:dns would bypass the enforced proxy
+      } else {
+        const dns = await import("node:dns/promises");
+        for (const [address, meta] of mailtoLinks) {
+          if (Date.now() >= deadline) break;
+          const domain = (address.split("@")[1] || "").toLowerCase();
+          if (!domain) continue;
+          // RFC 5321 implicit-MX: a domain with no MX but an A/AAAA record can still receive.
+          const deliverable = await dns.resolveMx(domain).then((records) => records.length > 0).catch(() => false)
+            || await dns.lookup(domain).then(() => true).catch(() => false);
+          if (!deliverable) issue("mailto_no_mx", "medium", `mailto: domain cannot receive email (no MX or address record): ${address}`, meta.screen, address, meta.sourceUrl);
+        }
       }
     }
   } finally {
     const timedOut = Date.now() >= deadline;
-    const stop = timedOut ? "time-budget" : actions >= maxActions ? "action-budget" : "frontier-drained";
+    // A drained frontier with a truncating probe cap is NOT "nothing left" — twin controls may
+    // sit untapped past the per-page cap, and the stop reason must not claim otherwise.
+    const stop = timedOut ? "time-budget"
+      : actions >= maxActions ? "action-budget"
+      : probeCapHit ? "probe-cap"
+      : "frontier-drained";
     emit("COMPLETE", { actions, screens: screenCount, credentialsProvided: !!(testEmail || testPassword), credentialsUsed: loginTried, timedOut, stop, outbound });
     fs.closeSync(markersFd);
     await browser.close().catch(() => {});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.17.5",
+  "version": "0.17.7",
   "mcpName": "io.github.aarwitz/tapp",
   "description": "Let coding agents verify UI changes on real iOS, Android, and web surfaces, then enforce reviewed proof in deterministic CI.",
   "license": "MIT",

package/scripts/ci-gate.sh

@@ -10,9 +10,10 @@
 # for GitHub Actions; equally usable from any other CI or locally.
 #
 # Usage:
-#   scripts/ci-gate.sh [--platform ios] --app <path/to/App.app> [--bundle-id <com.example.app>]
-#   scripts/ci-gate.sh --platform android --apk <path/to/app.apk> --app-id <com.example.app> [--serial <adb-serial>]
-#   scripts/ci-gate.sh --platform web [--url <http(s)://owned-app>]
+#   tapp ci [--platform ios] --app <path/to/App.app> [--bundle-id <com.example.app>]
+#   tapp ci --platform android --apk <path/to/app.apk> --app-id <com.example.app> [--serial <adb-serial>]
+#   tapp ci --platform web [--url <http(s)://owned-app>]
+#   tapp ci        # in an initialized repo: reads .tapp/application-model.json for platform/target
 #                      # omit --url with --project-dir to detect/build/start/stop one owned web target
 #                      # bundle id is detected from the .app when omitted
 #                      [--actions N]              # exploration budget (default 40)
@@ -27,7 +28,10 @@
 #                      [--pr-plan-out <file.json>] # persist the reviewable selection plan
 #                      [--baseline <file.json>]   # prior report to diff against (skipped if absent)
 #                      [--target-key <stable-id>] # isolates target-specific baselines in monorepos
-#                      [--fail-on gate|absolute|any]  # gate policy (default gate; see ci-report.js)
+#                      [--fail-on gate|absolute|any|high|medium]
+#                                                 # gate policy (default: gate; web targets default
+#                                                 # to medium — any deterministic medium+ finding
+#                                                 # blocks; see ci-report.js)
 #                      [--json-out <file.json>]   # write the full report (use as the next baseline)
 #                      [--md-out <file.md>]       # write the rendered markdown report (for a PR comment)
 #                      [--device <name>]          # simulator device to boot if none is (default "iPhone 16 Pro")
@@ -43,10 +47,10 @@ usage() {
 
 PLATFORM="ios" APP_PATH="" BUNDLE_ID="" APK_PATH="" APP_ID="" URL="" WEB_TARGET="" TARGET_KEY="" SERIAL="" ACTIONS=40 TIMEOUT=600 FLOWS="" SCENARIOS="" CONTRACTS="" PROJECT_DIR="" BASELINE="" FAIL_ON="gate" JSON_OUT="" MD_OUT="" DEVICE="iPhone 16 Pro" PR_BASE="" PR_HEAD="HEAD" CHANGED_FILES_FILE="" PR_PLAN_OUT=""
 IOS_PR_TARGET_JSON=""
-FLOWS_EXPLICIT=false SCENARIOS_EXPLICIT=false CONTRACTS_EXPLICIT=false
+FLOWS_EXPLICIT=false SCENARIOS_EXPLICIT=false CONTRACTS_EXPLICIT=false PLATFORM_EXPLICIT=false FAIL_ON_EXPLICIT=false
 while [[ $# -gt 0 ]]; do
   case "$1" in
-    --platform) PLATFORM="$2"; shift 2 ;;
+    --platform) PLATFORM="$2"; PLATFORM_EXPLICIT=true; shift 2 ;;
     --app) APP_PATH="$2"; shift 2 ;;
     --bundle-id) BUNDLE_ID="$2"; shift 2 ;;
     --apk) APK_PATH="$2"; shift 2 ;;
@@ -66,7 +70,7 @@ while [[ $# -gt 0 ]]; do
     --changed-files-file) CHANGED_FILES_FILE="$2"; shift 2 ;;
     --pr-plan-out) PR_PLAN_OUT="$2"; shift 2 ;;
     --baseline) BASELINE="$2"; shift 2 ;;
-    --fail-on) FAIL_ON="$2"; shift 2 ;;
+    --fail-on) FAIL_ON="$2"; FAIL_ON_EXPLICIT=true; shift 2 ;;
     --json-out) JSON_OUT="$2"; shift 2 ;;
     --md-out) MD_OUT="$2"; shift 2 ;;
     --device) DEVICE="$2"; shift 2 ;;
@@ -77,16 +81,48 @@ done
 [[ "$PLATFORM" == "ios" || "$PLATFORM" == "android" || "$PLATFORM" == "web" ]] || { echo "❌ --platform must be ios|android|web" >&2; exit 2; }
 [[ "$ACTIONS" =~ ^[1-9][0-9]*$ ]] || { echo "❌ --actions must be a positive integer" >&2; exit 2; }
 [[ "$TIMEOUT" =~ ^[1-9][0-9]*$ ]] || { echo "❌ --timeout must be a positive integer" >&2; exit 2; }
-[[ "$FAIL_ON" == "gate" || "$FAIL_ON" == "absolute" || "$FAIL_ON" == "any" ]] || { echo "❌ --fail-on must be gate|absolute|any" >&2; exit 2; }
+[[ "$FAIL_ON" == "gate" || "$FAIL_ON" == "absolute" || "$FAIL_ON" == "any" || "$FAIL_ON" == "high" || "$FAIL_ON" == "medium" ]] || { echo "❌ --fail-on must be gate|absolute|any|high|medium" >&2; exit 2; }
 if [[ -n "$PROJECT_DIR" ]]; then
   [[ -d "$PROJECT_DIR" ]] || { echo "❌ Project directory not found: $PROJECT_DIR" >&2; exit 2; }
   PROJECT_DIR="$(cd "$PROJECT_DIR" && pwd)"
 fi
+# A repository-connected gate should connect to the repository it is run from: when no
+# --project-dir was given but the working directory is an initialized Tapp repo, use it.
+if [[ -z "$PROJECT_DIR" && -f "$(pwd)/.tapp/application-model.json" ]]; then
+  PROJECT_DIR="$(pwd)"
+  echo "Using repository artifacts from $PROJECT_DIR/.tapp"
+fi
 TAPP_PROJECT_ARTIFACTS=""
 if [[ -n "$PROJECT_DIR" ]]; then
   [[ -d "$PROJECT_DIR/.tapp" ]] && TAPP_PROJECT_ARTIFACTS="$PROJECT_DIR/.tapp"
 fi
 
+# When --platform was not given, derive it from the application model instead of assuming iOS —
+# but only when the model is unambiguous (exactly one platform across its targets).
+if [[ "$PLATFORM_EXPLICIT" == "false" && -n "$TAPP_PROJECT_ARTIFACTS" && -f "$TAPP_PROJECT_ARTIFACTS/application-model.json" ]]; then
+  MODEL_PLATFORM="$(node - "$TAPP_PROJECT_ARTIFACTS/application-model.json" <<'NODE'
+const fs = require("fs");
+try {
+  const model = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+  const platforms = [...new Set((model.targets || []).map((t) => t.platform).filter(Boolean))];
+  if (platforms.length === 1) process.stdout.write(platforms[0]);
+} catch {}
+NODE
+  )"
+  if [[ -n "$MODEL_PLATFORM" && "$MODEL_PLATFORM" != "$PLATFORM" ]]; then
+    PLATFORM="$MODEL_PLATFORM"
+    echo "Platform derived from the application model: $PLATFORM (pass --platform to override)"
+  fi
+fi
+
+# Web policy default (gate policy v3): on a website, a deterministic broken link IS the release
+# blocker — default web targets to fail-on medium. Pass --fail-on gate to restore baseline-diff
+# semantics for a web target.
+if [[ "$FAIL_ON_EXPLICIT" == "false" && "$PLATFORM" == "web" ]]; then
+  FAIL_ON="medium"
+  echo "Gate policy: fail-on medium (web default; any deterministic medium+ finding blocks — override with --fail-on)"
+fi
+
 # A repository-connected gate must retain the stable application-model target identity in its
 # report. Otherwise its first passing report cannot become a target-scoped baseline, even though
 # Tapp already knows exactly which application it built and exercised. Explicit --target-key still

package/scripts/platform-gate.js

@@ -42,12 +42,18 @@ for (let i = 2; i < process.argv.length; i += 1) {
     process.exit(2);
   }
 }
-if (!["web", "android"].includes(args.platform)) throw new Error("--platform must be web|android");
-if (args.platform === "web" && !args.url && !args.projectDir) throw new Error("Web gate requires --url or --project-dir for managed build/start");
-if (args.platform === "android" && !args.appId) throw new Error("Android gate requires --app-id");
+// Usage problems are part of the public outcome contract (exit 2), never an uncaught stack trace.
+const usageError = (message) => { console.error(`❌ ${message}`); process.exit(2); };
+if (!["web", "android"].includes(args.platform)) usageError("--platform must be web|android");
+if (args.platform === "web" && !args.url && !args.projectDir) usageError("The web gate needs a target: pass --url <http(s)://owned-app>, or --project-dir <repo> to build/start the repository's own web target.");
+if (args.platform === "android" && !args.appId) usageError("The Android gate requires --app-id");
 if (args.projectDir) {
-  args.projectDir = fs.realpathSync(path.resolve(args.projectDir));
-  if (!fs.statSync(args.projectDir).isDirectory()) throw new Error(`Project directory not found: ${args.projectDir}`);
+  try {
+    args.projectDir = fs.realpathSync(path.resolve(args.projectDir));
+    if (!fs.statSync(args.projectDir).isDirectory()) usageError(`Project directory not found: ${args.projectDir}`);
+  } catch {
+    usageError(`Project directory not found: ${args.projectDir}`);
+  }
 }
 
 // Parse and platform-filter before launching a browser/device so a typo cannot