@aarwitz/tapp 0.16.5 → 0.17.0-rc.2

package/mcp-server/src/project-paths.js

@@ -1,32 +1,20 @@
-import fs from "node:fs";
 import path from "node:path";
 
 export const TAPP_DIRECTORY = ".tapp";
-export const LEGACY_TAPP_DIRECTORY = ".autotap";
 export const TAPP_CONFIG = ".tapp.yml";
-export const LEGACY_TAPP_CONFIG = ".autotap.yml";
 
-export function projectArtifactDirectory(projectDir, requested = TAPP_DIRECTORY) {
-  const root = path.resolve(projectDir);
-  if (requested !== TAPP_DIRECTORY) return requested;
-  const canonical = path.join(root, TAPP_DIRECTORY);
-  const legacy = path.join(root, LEGACY_TAPP_DIRECTORY);
-  if (!fs.existsSync(canonical) && fs.existsSync(legacy)) return LEGACY_TAPP_DIRECTORY;
-  return TAPP_DIRECTORY;
+export function projectArtifactDirectory(_projectDir, requested = TAPP_DIRECTORY) {
+  return requested;
 }
 
 export function projectArtifactPath(projectDir, ...parts) {
-  return path.join(path.resolve(projectDir), projectArtifactDirectory(projectDir), ...parts);
+  return path.join(path.resolve(projectDir), TAPP_DIRECTORY, ...parts);
 }
 
 export function existingProjectArtifactPath(projectDir, ...parts) {
-  const root = path.resolve(projectDir);
-  const canonical = path.join(root, TAPP_DIRECTORY, ...parts);
-  if (fs.existsSync(canonical)) return canonical;
-  const legacy = path.join(root, LEGACY_TAPP_DIRECTORY, ...parts);
-  return fs.existsSync(legacy) ? legacy : canonical;
+  return path.join(path.resolve(projectDir), TAPP_DIRECTORY, ...parts);
 }
 
 export function isProjectArtifactDirectory(name) {
-  return name === TAPP_DIRECTORY || name === LEGACY_TAPP_DIRECTORY;
+  return name === TAPP_DIRECTORY;
 }

package/mcp-server/src/release-contract.js

@@ -11,8 +11,8 @@ import { semanticUiKey } from "./ui-map.js";
 
 const PLATFORMS = new Set(["ios", "android", "web"]);
 const CRITICALITIES = new Set(["low", "medium", "high", "critical"]);
-const CONTRACT_AUTHORING_SPECIFIERS = new Set(["@aarwitz/tapp/contracts", "runtapp/contracts", "tapp-mcp/contracts"]);
-const CONTRACT_AUTHORING_IMPORT = /(["'])(?:@aarwitz\/tapp|runtapp|tapp-mcp)\/contracts\1/g;
+const CONTRACT_AUTHORING_SPECIFIERS = new Set(["@aarwitz/tapp/contracts"]);
+const CONTRACT_AUTHORING_IMPORT = /(["'])@aarwitz\/tapp\/contracts\1/g;
 const authoringUrl = pathToFileURL(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "contract-authoring.js")).href;
 
 function expectationAction(expectation) {
@@ -86,7 +86,7 @@ function rewriteAuthoringImport(source, contractPath) {
   }
   const imports = [...source.matchAll(/(?:from\s*|import\s*)["']([^"']+)["']/g)].map((match) => match[1]);
   const unsupported = imports.filter((specifier) => !CONTRACT_AUTHORING_SPECIFIERS.has(specifier));
-  if (unsupported.length) throw new Error(`Release contract imports are limited to @aarwitz/tapp/contracts (legacy runtapp/contracts and tapp-mcp/contracts are also accepted; found ${unsupported.join(", ")})`);
+  if (unsupported.length) throw new Error(`Release contract imports are limited to @aarwitz/tapp/contracts (found ${unsupported.join(", ")})`);
   const output = ts.transpileModule(source, {
     fileName: contractPath,
     compilerOptions: { module: ts.ModuleKind.ES2022, target: ts.ScriptTarget.ES2022, verbatimModuleSyntax: true },

package/mcp-server/src/report.js

@@ -1,6 +1,6 @@
 // Pure report/gate logic shared by the MCP server (index.js) and the CI gate CLI
-// (ci-report.js). Turns a capture's OCQA markers into the same ship/no-ship report the Tapp
-// app produces, and diffs two runs' findings into the CI regression gate. No shell, no server —
+// (ci-report.js). Turns a capture's OCQA markers into a scoreless exploration observation,
+// and applies explicit policy separately in the CI gate. No shell, no server —
 // keep it dependency-free so the CI path stays importable and testable.
 import fs from "fs";
 import path from "path";
@@ -106,21 +106,36 @@ export function findingEvaluationTier(finding, platform = "ios") {
   return platform === "web" && WEB_SAMPLED_ISSUE_TYPES.has(finding?.type) ? "sampled" : "deterministic";
 }
 
-export function verdictBadge(report) {
-  if (report?.platform === "web" && report?.verdict === "ready") return "🔵 AUTOMATED CHECKS COMPLETE";
-  return { ready: "🟢 SHIP-READY", caution: "🟡 CAUTION", blocked: "🔴 BLOCKED" }[report?.verdict] || report?.verdict;
+// The deterministic block-by-findings rule, expressed over verdict-tier finding COUNTS — not the
+// score scalar and not the `verdict` label — so the CI gate survives removal of verdict/releaseScore
+// from exploration output. It encodes exactly what `verdict === "blocked"` used to: a critical
+// finding always blocks; otherwise, on a CONCLUSIVE run, a risk threshold blocks. The risk threshold
+// is kept as an explicit, chosen rule (ADR-0005) — `riskFromCounts` is the single source of that
+// formula, shared with buildQaReport's verdict label. Inconclusive runs are a separate gate outcome,
+// never a findings-block, so a thin run reports `inconclusive`, not `fail`.
+export function riskFromCounts({ critical = 0, high = 0, medium = 0 } = {}) {
+  return Math.max(0, Math.min(100, 100 - critical * 25 - high * 10 - medium * 3));
+}
+export function findingsBlock(deterministicFindingCounts = {}, { inconclusive = false } = {}) {
+  if ((deterministicFindingCounts.critical || 0) > 0) return true;
+  if (inconclusive) return false;
+  return riskFromCounts(deterministicFindingCounts) < 50;
+}
+
+// Exploration OBSERVES; it never renders a ship verdict or score (ADR-0005). These label the
+// observation honestly. The release decision (pass/fail/inconclusive) is the gate's, shown separately.
+export function observationBadge(report) {
+  return report?.inconclusive ? "🟡 INCONCLUSIVE (exploration)" : "🔭 EXPLORED";
 }
 
-export function qaScoreLabel(report) {
-  const score = report?.releaseScore ?? report?.confidence;
-  if (Number.isFinite(score)) return `release score ${score}/100`;
-  if (report?.platform === "web") return "exploratory web · no scalar score";
-  return "score unavailable";
+export function observationSummary(report) {
+  const n = report?.findingCounts?.total || 0;
+  return `${report?.screensExplored || 0} screens · ${report?.actionsPerformed || 0} actions · ${n} finding(s) · observation only`;
 }
 
-// Turn a capture's OCQA markers into the same ship/no-ship report Tapp produces:
-// deduped findings + a trustworthy verdict with a coverage floor (mirrors OrchestratorService).
-export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
+// Turn a capture's OCQA markers into a scoreless observation with deduped findings and an
+// explicit coverage floor. Release judgment is applied later by evaluateGate.
+export function buildQaReport(markersFilePath, { platform = "ios", target = null } = {}) {
   const base = parseOcqaMarkers(markersFilePath);
   if (!base) return null;
 
@@ -130,6 +145,7 @@ export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
   const inputsByScreen = new Map();
   const screenElementCounts = {}; // screen -> max elements observed (content-collapse detection)
   let anySecure = false;
+  let loginAttempted = false;
   let actions = 0;
 
   for (const line of raw.split(/\r?\n/)) {
@@ -148,6 +164,17 @@ export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
       }
     } else if (t.startsWith("OCQA_ACTION:")) {
       actions += 1;
+      try {
+        const action = JSON.parse(t.slice("OCQA_ACTION:".length));
+        if (action?.type === "login" || String(action?.type || "").startsWith("login_")) loginAttempted = true;
+      } catch {
+        /* ignore malformed */
+      }
+    } else if (
+      t === "OCQA_STATE:login_preamble_submitted" ||
+      t === "OCQA_STATE:login_preamble_two_step_submitted"
+    ) {
+      loginAttempted = true;
     } else if (t.startsWith("OCQA_STATE:{")) {
       try {
         const s = JSON.parse(t.slice("OCQA_STATE:".length));
@@ -187,7 +214,12 @@ export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
   const missingResources = new Set(normalizedIssues
     .filter((issue) => issue.type === "missing_asset" && issue.target)
     .map((issue) => issue.target));
+  // Older native captures represented the caller's wall-clock budget as a high-severity app
+  // finding. A timeout makes the evidence partial/inconclusive; it does not prove an app
+  // performance defect (the harness has a separate app_hang detector for that).
+  const timeBudgetExhausted = base.complete?.timedOut === true || normalizedIssues.some((issue) => issue.type === "explore_timeout");
   const reportIssues = normalizedIssues.filter((issue) =>
+    issue.type !== "explore_timeout" &&
     !(issue.type === "network_error" && issue.target && missingResources.has(issue.target) && /^Request failed:/i.test(String(issue.title || ""))));
 
   // Dedup by stable signature (type|screen|target) so repeated detections count once —
@@ -201,14 +233,23 @@ export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
     findings.push({
       ...i,
       category: ISSUE_CATEGORY[i.type] || i.type,
+      // Structural evidence authority (ADR-0005): marker-derived findings are deterministic. The
+      // default gate consumes only deterministic-authority evidence; model-observed findings
+      // (vision/assert_ai) carry authority:"model-observed" and are advisory, never gate fails.
+      authority: "deterministic",
       ...(platform === "web" ? { evaluationTier: findingEvaluationTier(i, platform) } : {}),
     });
   }
   findings.sort((a, b) => severityRank(a.severity) - severityRank(b.severity));
 
   const screensExplored = screens.size || base.uniqueScreens.length;
-  const actionsPerformed =
-    actions || (base.complete && typeof base.complete === "object" ? base.complete.actions || 0 : 0);
+  // Some native recovery operations are counted by the harness budget but intentionally do not
+  // emit a public action narrative. Preserve the larger authoritative completion count instead of
+  // understating coverage whenever at least one narrated action exists.
+  const actionsPerformed = Math.max(
+    actions,
+    base.complete && typeof base.complete === "object" ? base.complete.actions || 0 : 0,
+  );
   const crit = findings.filter((f) => f.severity === "critical").length;
   const high = findings.filter((f) => f.severity === "high").length;
   const med = findings.filter((f) => f.severity === "medium").length;
@@ -222,29 +263,33 @@ export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
   const verdictLow = verdictFindings.filter((f) => f.severity === "low").length;
   const sampledFindings = platform === "web" ? findings.filter((finding) => finding.evaluationTier === "sampled") : [];
 
-  // Coverage floor: a verdict is only trustworthy if the app was actually exercised.
-  const inconclusive = screensExplored < 2 || actionsPerformed < 3;
-  let riskScore = Math.max(0, Math.min(100, 100 - verdictCrit * 25 - verdictHigh * 10 - verdictMed * 3));
-  if (inconclusive) riskScore = Math.min(riskScore, 40);
-
-  let verdict;
-  if (verdictCrit > 0) verdict = "blocked";
-  else if (inconclusive) verdict = "caution";
-  else if (riskScore < 50) verdict = "blocked";
-  else if (verdictHigh > 0 || riskScore < 80) verdict = "caution";
-  else verdict = "ready";
-
-  const headline = inconclusive
+  // Coverage floor: exploration is inconclusive if the app wasn't actually exercised. Exploration
+  // OBSERVES — it does not render a ship verdict or score (ADR-0005). Judgment (pass/fail/
+  // inconclusive) is the gate's job (evaluateGate), computed from these findings + coverage + policy.
+  // A one-page web target can still be swept exhaustively: page errors, requests, links, assets,
+  // placeholder anchors, and visible controls do not require a second route. Native exploration
+  // retains the stronger multi-screen/action floor. A credentialless single-screen login remains
+  // inconclusive so a login wall can never turn into a clean pass.
+  const coverageFloorMet = platform === "web"
+    ? screensExplored >= 1 && actionsPerformed >= 1
+    : screensExplored >= 2 && actionsPerformed >= 3;
+  const credentiallessLoginWall = anySecure && !loginAttempted && screensExplored <= 1;
+  const inconclusive = !coverageFloorMet || credentiallessLoginWall || timeBudgetExhausted;
+  const stopReason = credentiallessLoginWall ? "login-wall-no-credentials"
+    : timeBudgetExhausted ? "time-budget-exhausted"
+    : coverageFloorMet ? "completed" : "coverage-floor-not-met";
+
+  const headline = timeBudgetExhausted
+    ? `Inconclusive — exploration reached its ${base.complete?.timeoutSeconds || "configured"}s time budget after ${actionsPerformed} action(s) across ${screensExplored} screen(s). Findings are partial; this is not an app performance finding. Increase --timeout or request fewer actions.`
+    : inconclusive
     ? `Inconclusive — only ${screensExplored} screen(s) / ${actionsPerformed} action(s) explored. The app may have crashed on launch, be stuck behind a sign-in wall, or otherwise prevent exploration. Absence of issues is NOT a pass.`
-    : verdict === "ready"
+    : findings.length === 0
     ? platform === "web"
-      ? "Automated web checks completed — no release-blocking deterministic findings in the exercised surfaces. Sampled control probes are advisory. This is not a content, privacy, brand, or business-claim review."
-      : "Ship-ready — no release-blocking issues found."
-    : verdict === "caution"
-    ? `Proceed with caution — ${findings.length} issue(s) to review.`
-    : `Not ready — ${findings.length} issue(s): ${crit} critical, ${high} high, ${med} medium, ${low} low.`;
+      ? "Automated web checks completed — no deterministic findings in the exercised surfaces. Sampled control probes are advisory. An observation, not a release decision, and not a content, privacy, brand, or business-claim review."
+      : "No issues surfaced in the exercised surfaces. An observation, not a release decision."
+    : `${findings.length} issue(s) surfaced for review (${crit} critical, ${high} high, ${med} medium, ${low} low). An observation, not a release decision.`;
 
-  // The verdict's own honesty label: exactly which defect classes this run checked, which
+  // The observation's honesty label: exactly which defect classes this run checked, which
   // it structurally could NOT check, and which conditions never came up — so "checked" is
   // never claimed for a state the run didn't reach. Platform-aware: a web run doesn't
   // inherit iOS keyboard assertions and vice versa.
@@ -290,30 +335,38 @@ export function buildQaReport(markersFilePath, { platform = "ios" } = {}) {
       "content & reachability regressions require a baseline" ,
     ];
   }
-  // "Failed sign-ins" is only a claim when a sign-in surface was actually encountered.
-  if (anySecure) checkedFor.splice(2, 0, "failed sign-ins");
+  // "Failed sign-ins" is only a claim when credentials were actually submitted. Merely seeing a
+  // password field proves that a login surface was reached, not that authentication was exercised.
+  if (loginAttempted) checkedFor.splice(2, 0, "failed sign-ins");
+  else if (anySecure) notChecked.push("sign-in behavior (login form reached, no test credentials supplied)");
   else conditionsNotReached.push("sign-in (no login form encountered this run)");
+  if (timeBudgetExhausted) notChecked.push("the full requested action budget (run reached its wall-clock timeout)");
 
   return {
-    verdict,
-    // Exploratory web QA deliberately has no scalar. Its verdict derives from deterministic
-    // checks on exercised pages; budget-capped control probes remain visible but advisory.
-    // Native keeps the legacy heuristic score until it has an equivalent tier split.
-    confidence: platform === "web" ? null : riskScore,
-    releaseScore: platform === "web" ? null : riskScore,
-    scoreUnavailableReason: platform === "web"
-      ? "Exploratory web runs report deterministic findings, advisory sampled probes, and coverage instead of a scalar release score."
-      : null,
+    // An ExplorationRun observation: findings + coverage + evidence, NO ship verdict or score
+    // (ADR-0005). The gate (evaluateGate) turns this into a pass/fail/inconclusive release outcome.
+    kind: "tapp-exploration-run",
+    schemaVersion: 1,
+    // Complete ExplorationRun contract (ADR-0005 §4). runStatus/stopReason describe HOW the run
+    // ended; coverage/evidence/uiMap/comparison are the structured observation. uiMap and comparison
+    // are populated by consumers that build the map / diff a baseline (null in the bare observation).
+    runStatus: inconclusive ? "limited" : "completed",
+    stopReason,
     headline,
     inconclusive,
+    coverage: { screensExplored, actionsPerformed, screens: Array.from(screens) },
+    evidence: { markers: base.relativeMarkersFilePath },
+    uiMap: null,
+    comparison: null,
     checkedFor,
     notChecked,
     conditionsNotReached,
     platform,
+    target: typeof target === "string" && target.trim() ? target.trim() : null,
     screensExplored,
     actionsPerformed,
     findingCounts: { critical: crit, high, medium: med, low, total: findings.length },
-    verdictFindingCounts: {
+    deterministicFindingCounts: {
       critical: verdictCrit,
       high: verdictHigh,
       medium: verdictMed,
@@ -355,6 +408,7 @@ export function computeContentCollapse(currentCounts, baselineCounts) {
         type: "content_collapse",
         severity: "high",
         category: "content_collapse",
+        authority: "deterministic",
         title: `Screen lost most of its content (${base} → ${cur} elements)`,
         screen,
         step: null,
@@ -383,6 +437,7 @@ export function computeReachabilityLoss(current, baseline) {
       type: "screen_unreachable",
       severity: "high",
       category: "navigation_dead_end",
+      authority: "deterministic",
       title: "Screen explored in the baseline was never reached this run",
       screen,
       step: null,
@@ -421,15 +476,94 @@ export function computeRegression(current, baseline) {
   const newFindings = current.filter((f) => !currentMatches(f));
   const persisting = current.filter((f) => currentMatches(f));
   const resolved = baseline.filter((b) => !baselineMatched(b));
-  const newCritical = newFindings.filter((f) => f.severity === "critical").length;
-  const newHigh = newFindings.filter((f) => f.severity === "high").length;
 
+  // Comparison ONLY — no gate/pass/fail signal (ADR-0005). Exploration surfaces this diff; the merge
+  // decision is the gate's job. evaluateGate derives its regression fail from `newFindings` severities.
   return {
     hadBaseline: true,
     counts: { new: newFindings.length, persisting: persisting.length, resolved: resolved.length },
     newFindings,
     resolved,
-    // CI gate: fail the build when this run introduced new high/critical findings vs. the baseline.
-    gate: { newCritical, newHigh, failed: newCritical + newHigh > 0 },
+  };
+}
+
+// The gate's public outcome model (ADR-0005). A merge gate is ultimately block / don't-block, but
+// callers need to distinguish WHY: a deterministic violation is not the same as "we couldn't get
+// 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";
+
+// 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
+// merge decision (block/don't-block) is unchanged; this only classifies each reason as a
+// deterministic `fail` or an evidence-absent `inconclusive` and folds them by precedence. Reason
+// MESSAGES are preserved exactly (several are asserted by tests).
+//
+// DECOUPLED FROM THE SCORE (ADR-0005): the block-by-findings decision reads `deterministicFindingCounts` +
+// `inconclusive` via `findingsBlock`, NOT the score scalar or the `verdict` label. `verdict`/
+// `releaseScore` can therefore be removed from exploration output without changing any merge
+// decision. The `riskScore < 50` threshold is retained deliberately (kept explicit, inside
+// `findingsBlock`) and locked by the `[char]` risk-threshold test.
+export function evaluateGate({ report, regression = null, flows = [], scenarios = [], contracts = [], prPlan = null, baseline = null, failOn = "gate" } = {}) {
+  const reasons = []; // { kind: "fail" | "inconclusive", message }
+  const fail = (message) => reasons.push({ kind: "fail", message });
+  const inconclusive = (message) => reasons.push({ kind: "inconclusive", message });
+
+  // Classify each replayed suite by evidence authority (ADR-0005): a DETERMINISTIC step failure (or
+  // a non-model failure like an aborted/missing run) is a real fail; a suite with no deterministic
+  // failure that carries a model-observed (assert_ai) assertion cannot be decided by the default
+  // deterministic gate → inconclusive/needs-review (it must not silently pass, and a model verdict
+  // must not masquerade as a deterministic fail). No `--policy probabilistic` opt-in in 0.17.
+  const deterministicFail = (s) => s.deterministicFailed === true || (s.passed === false && !s.modelObserved);
+  const classify = (s) => (deterministicFail(s) ? "fail" : s.modelObserved ? "needs-review" : "pass");
+  for (const [label, suites] of [["flow", flows], ["multi-actor scenario", scenarios], ["release contract", contracts]]) {
+    const failed = suites.filter((s) => classify(s) === "fail");
+    if (failed.length) fail(`${failed.length} ${label}(s) failed`);
+    const needsReview = suites.filter((s) => classify(s) === "needs-review");
+    if (needsReview.length) inconclusive(`${needsReview.length} ${label}(s) contain assert_ai (model-observed); the deterministic gate cannot decide them — review, or add an explicit probabilistic policy`);
+  }
+  // A submitted sign-in that remains on the login surface is an explicit exercised guarantee,
+  // not ordinary pre-existing UI debt. Letting it pass without a baseline would produce the
+  // contradictory public result "failed sign-in detected" + gate PASS. Keep sampled probes out,
+  // but fail every deterministic auth failure under every gate policy (including with a baseline).
+  const authFailures = (report.findings || []).filter((finding) =>
+    finding?.type === "auth_failed" &&
+    finding?.authority !== "model-observed" &&
+    finding?.evaluationTier !== "sampled"
+  );
+  if (authFailures.length) fail(`${authFailures.length} deterministic sign-in attempt(s) failed`);
+  // Selected-but-unexecuted work is missing evidence, not an observed violation → inconclusive.
+  if (prPlan?.execution?.notRun) inconclusive(`${prPlan.execution.notRun} selected release contract(s) did not run`);
+  if (prPlan?.execution?.explorationFailed) inconclusive(`${prPlan.execution.explorationFailed} planned PR exploration target(s) failed or were not reached`);
+
+  if (failOn === "any") {
+    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 === "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)");
+  } else {
+    if (regression?.newFindings?.length) {
+      const newCritical = regression.newFindings.filter((f) => f.severity === "critical").length;
+      const newHigh = regression.newFindings.filter((f) => f.severity === "high").length;
+      if (newCritical + newHigh > 0) fail(`${newCritical} new critical + ${newHigh} new high vs. baseline`);
+    }
+    if (findingsBlock(report.deterministicFindingCounts, { inconclusive: report.inconclusive })) fail("blocking deterministic finding(s)");
+    if (report.inconclusive && !baseline?.inconclusive) inconclusive("run became inconclusive vs. baseline (app may no longer launch/explore)");
+  }
+
+  const outcome = reasons.some((r) => r.kind === "fail") ? "fail"
+    : reasons.some((r) => r.kind === "inconclusive") ? "inconclusive"
+    : "pass";
+  return {
+    policy: failOn,
+    outcome,
+    exitCode: GATE_EXIT[outcome],
+    failed: outcome !== "pass", // retained for markdown/JSON consumers during migration
+    reasons: reasons.map((r) => r.message),
+    reasonDetails: reasons,
+    policyVersion: GATE_POLICY_VERSION,
   };
 }

package/mcp-server/src/task-runtime.js

@@ -109,7 +109,7 @@ export function loadTaskRegistry({ sourcePath, projectDir = "", taskFiles = [] }
   // Draft contracts generated under `.tapp/proposals/contracts` may compile
   // against sibling untrusted Task drafts. Ordinary committed contracts never
   // see this directory, so a proposal cannot silently enter the release gate.
-  const proposalSource = [".tapp", ".autotap"].some((directory) => String(path.resolve(sourcePath || "")).includes(`${path.sep}${directory}${path.sep}proposals${path.sep}`));
+  const proposalSource = String(path.resolve(sourcePath || "")).includes(`${path.sep}.tapp${path.sep}proposals${path.sep}`);
   const proposalDir = proposalSource && tappDir ? path.join(tappDir, "proposals", "tasks") : "";
   const proposed = proposalDir && fs.existsSync(proposalDir)
     ? fs.readdirSync(proposalDir).filter((name) => /\.ya?ml$|\.json$/i.test(name)).map((name) => path.join(proposalDir, name))

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

@@ -45,7 +45,7 @@ export function webPlaceholderLinkFindings(links = []) {
   const seen = new Set();
   for (const link of links || []) {
     const rawHref = String(link?.rawHref || "").trim().toLowerCase();
-    const placeholder = rawHref === "#" || /^javascript:(?:void\(0\);?|;?)$/.test(rawHref);
+    const placeholder = rawHref === "" || rawHref === "#" || /^javascript:(?:void\(0\);?|;?)$/.test(rawHref);
     if (!placeholder || link?.handlerHint) continue;
     const label = String(link?.label || "").replace(/\s+/g, " ").trim().slice(0, 100);
     const fingerprint = String(link?.fingerprint || "link").replace(/\s+/g, " ").trim().slice(0, 100) || "link";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.16.5",
+  "version": "0.17.0-rc.2",
   "mcpName": "io.github.aarwitz/tapp",
   "description": "Release contracts, autonomous QA, and evidence-backed CI gates for iOS, Android, and web.",
   "license": "MIT",
@@ -87,7 +87,7 @@
     "mobile"
   ],
   "scripts": {
-    "test": "node --test tests/report.test.js tests/regression.test.js tests/engine.test.js tests/project-config.test.js tests/application-model.test.js tests/ui-map.test.js tests/task-runtime.test.js tests/release-contract.test.js tests/pr-selection.test.js tests/flow-runtime.test.js tests/web-explorer.test.js tests/web-session.test.js tests/web-flow.test.js tests/scenario-runtime.test.js tests/android-driver.test.js tests/android-explorer.test.js tests/android-flow.test.js tests/managed-web.test.js tests/product-operations.test.js tests/browser-product.test.js tests/browser-onboarding.test.js tests/managed-operation.test.js tests/ci-setup.test.js tests/ci-install.test.js tests/cli.test.js tests/action.test.js tests/package-surface.test.js tests/ci-gate.test.js tests/ci-report.test.js tests/desktop-protocol.test.js tests/ios-flow-protocol.test.js",
+    "test": "node --test tests/report.test.js tests/regression.test.js tests/engine.test.js tests/project-config.test.js tests/application-model.test.js tests/ui-map.test.js tests/task-runtime.test.js tests/release-contract.test.js tests/pr-selection.test.js tests/flow-runtime.test.js tests/web-explorer.test.js tests/web-session.test.js tests/web-flow.test.js tests/scenario-runtime.test.js tests/android-driver.test.js tests/android-explorer.test.js tests/android-flow.test.js tests/android-primitives-protocol.test.js tests/managed-web.test.js tests/product-operations.test.js tests/browser-product.test.js tests/browser-onboarding.test.js tests/managed-operation.test.js tests/cloud-runner.test.js tests/ci-setup.test.js tests/ci-install.test.js tests/cli.test.js tests/action.test.js tests/package-surface.test.js tests/ci-gate.test.js tests/ci-report.test.js tests/desktop-protocol.test.js tests/ios-flow-protocol.test.js",
     "test:browser-journey": "node --test tests/browser-journey.test.js",
     "test:browser-native": "TAPP_RUN_NATIVE_BROWSER=1 node --test tests/browser-native-journey.test.js"
   }

package/scripts/ci-gate.sh

@@ -3,9 +3,11 @@
 #
 # Boots a simulator if needed, installs the app build under test, runs the autonomous exploration
 # harness, replays every committed Flow (deterministic E2E tests), diffs the findings against a
-# stored baseline, writes a GitHub Actions step summary, and exits non-zero when the gate fails
-# (new high/critical findings vs. baseline, or any failed Flow). Wrapped by ../action.yml for
-# GitHub Actions; equally usable from any other CI or locally.
+# stored baseline, writes a GitHub Actions step summary, and exits with the public outcome contract:
+# pass 0, deterministic fail 1, infrastructure/usage error 2, inconclusive evidence 3. Absolute
+# blockers and reviewed Flow/Scenario/Contract failures are enforced even without a baseline;
+# baseline comparisons additionally catch new high/critical regressions. Wrapped by ../action.yml
+# 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>]
@@ -25,7 +27,7 @@
 #                      [--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|blocked|any]  # gate policy (default gate; see ci-report.js)
+#                      [--fail-on gate|absolute|any]  # gate policy (default gate; 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")
@@ -35,7 +37,7 @@ set -uo pipefail
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 
 usage() {
-  sed -n '2,30p' "$0" | sed 's/^# \{0,1\}//'
+  sed -n '2,/^set -uo pipefail$/p' "$0" | sed '$d; s/^# \{0,1\}//'
 }
 
 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=""
@@ -74,7 +76,7 @@ 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" == "blocked" || "$FAIL_ON" == "any" ]] || { echo "❌ --fail-on must be gate|blocked|any" >&2; exit 2; }
+[[ "$FAIL_ON" == "gate" || "$FAIL_ON" == "absolute" || "$FAIL_ON" == "any" ]] || { echo "❌ --fail-on must be gate|absolute|any" >&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)"
@@ -82,7 +84,6 @@ fi
 TAPP_PROJECT_ARTIFACTS=""
 if [[ -n "$PROJECT_DIR" ]]; then
   [[ -d "$PROJECT_DIR/.tapp" ]] && TAPP_PROJECT_ARTIFACTS="$PROJECT_DIR/.tapp"
-  [[ -z "$TAPP_PROJECT_ARTIFACTS" && -d "$PROJECT_DIR/.autotap" ]] && TAPP_PROJECT_ARTIFACTS="$PROJECT_DIR/.autotap"
 fi
 [[ -z "$FLOWS" && -n "$TAPP_PROJECT_ARTIFACTS" && -d "$TAPP_PROJECT_ARTIFACTS/flows" ]] && FLOWS="$TAPP_PROJECT_ARTIFACTS/flows/*.yml"
 [[ "$PLATFORM" == "web" && -z "$SCENARIOS" && -n "$TAPP_PROJECT_ARTIFACTS" && -d "$TAPP_PROJECT_ARTIFACTS/scenarios" ]] && SCENARIOS="$TAPP_PROJECT_ARTIFACTS/scenarios/*.yml"
@@ -274,7 +275,7 @@ xcrun simctl install "$UDID" "$APP_PATH" || { echo "❌ simctl install failed
 # ── Autonomous exploration (quick-capture builds the harness itself if needed).
 step "Explore ($ACTIONS actions, ${TIMEOUT}s watchdog)"
 set +e
-CAPTURE_ROOT="${TAPP_HOME:-${AUTOTAP_HOME:-$ROOT}}/captures"
+CAPTURE_ROOT="${TAPP_HOME:-$ROOT}/captures"
 mkdir -p "$CAPTURE_ROOT"
 CAPTURE_DIR="$(mktemp -d "$CAPTURE_ROOT/ci.XXXXXX")"
 TAPP_CAPTURE_DIR="$CAPTURE_DIR" OCQA_PR_TARGET_JSON="$IOS_PR_TARGET_JSON" "$ROOT/scripts/quick-capture.sh" explore "$BUNDLE_ID" --actions "$ACTIONS" --timeout "$TIMEOUT"

package/scripts/platform-gate.js

@@ -37,7 +37,10 @@ for (let i = 2; i < process.argv.length; i += 1) {
   else if (key === "--json-out") args.jsonOut = value;
   else if (key === "--md-out") args.mdOut = value;
   else if (key === "--pr-plan") args.prPlan = value;
-  else throw new Error(`Unknown argument: ${key}`);
+  else {
+    console.error(`Unknown argument: ${key}`);
+    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");
@@ -94,7 +97,7 @@ if (args.prPlan) {
 }
 
 let managedRuntime = null;
-let exitCode = 1;
+let exitCode = 2;
 try {
   if (args.platform === "web" && !args.url) {
     const started = await startManagedWebTarget({
@@ -106,7 +109,7 @@ try {
     if (started.error) {
       console.error(`❌ ${started.error}`);
       if (started.details?.remediation) console.error(`   ${started.details.remediation}`);
-      process.exitCode = 1;
+      exitCode = 2;
     } else {
       managedRuntime = started;
       args.url = started.url;
@@ -114,7 +117,7 @@ try {
     }
   }
   if (args.platform === "web" && !args.url) {
-    exitCode = 1;
+    exitCode = 2;
   } else {
     const qa = args.platform === "web"
       ? await runQaWeb({ url: args.url, maxActions: args.actions, timeout: args.timeout, testEmail: process.env.OCQA_TEST_EMAIL, testPassword: process.env.OCQA_TEST_PASSWORD, seedTargets: prExplorationTargets })
@@ -122,7 +125,7 @@ try {
           testEmail: process.env.OCQA_TEST_EMAIL, testPassword: process.env.OCQA_TEST_PASSWORD, seedTargets: prExplorationTargets });
     if (qa.error) {
       console.error(`❌ ${qa.error}`);
-      exitCode = 1;
+      exitCode = 2;
     } else {
       const captureDir = qa.structured.capture.path;
       const markers = path.join(captureDir, "ocqa-markers.txt");
@@ -177,6 +180,9 @@ try {
       exitCode = report.status ?? 1;
     }
   }
+} catch (error) {
+  console.error(`❌ ${error?.message || String(error)}`);
+  exitCode = 2;
 } finally {
   if (managedRuntime) {
     await stopManagedWebTarget(managedRuntime);