@aarwitz/tapp 0.15.1 → 0.16.1

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

@@ -1,7 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
+import { LEGACY_TAPP_DIRECTORY, TAPP_DIRECTORY, projectArtifactDirectory } from "./project-paths.js";
 
-export const PROJECT_CONFIG_RELATIVE_PATH = ".autotap/project.json";
+export const PROJECT_CONFIG_RELATIVE_PATH = `${TAPP_DIRECTORY}/project.json`;
+export const LEGACY_PROJECT_CONFIG_RELATIVE_PATH = `${LEGACY_TAPP_DIRECTORY}/project.json`;
 
 const ACTOR_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
 const ENV_NAME = /^[A-Z_][A-Z0-9_]{0,127}$/;
@@ -58,15 +60,16 @@ export function validateProjectConfig(config) {
 
 export function readProjectConfig(projectDir, { required = false } = {}) {
   const root = fs.realpathSync(path.resolve(projectDir || process.cwd()));
-  const configPath = path.join(root, PROJECT_CONFIG_RELATIVE_PATH);
+  const relativePath = `${projectArtifactDirectory(root)}/project.json`;
+  const configPath = path.join(root, relativePath);
   if (!fs.existsSync(configPath)) {
     if (required) throw new Error(`Project configuration not found: ${configPath}`);
-    return { root, path: configPath, relativePath: PROJECT_CONFIG_RELATIVE_PATH, config: { kind: "tapp-project-config", schemaVersion: 1, actors: {} }, exists: false, errors: [] };
+    return { root, path: configPath, relativePath, config: { kind: "tapp-project-config", schemaVersion: 1, actors: {} }, exists: false, errors: [] };
   }
   let config;
   try { config = JSON.parse(fs.readFileSync(configPath, "utf8")); }
-  catch (error) { return { root, path: configPath, relativePath: PROJECT_CONFIG_RELATIVE_PATH, config: null, exists: true, errors: [`Invalid JSON: ${error.message}`] }; }
-  return { root, path: configPath, relativePath: PROJECT_CONFIG_RELATIVE_PATH, config, exists: true, errors: validateProjectConfig(config) };
+  catch (error) { return { root, path: configPath, relativePath, config: null, exists: true, errors: [`Invalid JSON: ${error.message}`] }; }
+  return { root, path: configPath, relativePath, config, exists: true, errors: validateProjectConfig(config) };
 }
 
 export function configureActor(projectDir, { name, role = "", session = "default", provisioning = "existing", credentials = {}, replace = false } = {}) {

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

@@ -0,0 +1,32 @@
+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 projectArtifactPath(projectDir, ...parts) {
+  return path.join(path.resolve(projectDir), projectArtifactDirectory(projectDir), ...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;
+}
+
+export function isProjectArtifactDirectory(name) {
+  return name === TAPP_DIRECTORY || name === LEGACY_TAPP_DIRECTORY;
+}

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

@@ -7,6 +7,7 @@ import path from "node:path";
 import { spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { semanticUiKey } from "./ui-map.js";
+import { isProjectArtifactDirectory, projectArtifactDirectory } from "./project-paths.js";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 
@@ -84,12 +85,15 @@ export function loadTaskFile(taskPath) {
   return { ...task, __path: path.resolve(taskPath) };
 }
 
-function findAutotapDir(sourcePath, explicitProjectDir = "") {
-  if (explicitProjectDir) return path.join(path.resolve(explicitProjectDir), ".autotap");
+function findTappDir(sourcePath, explicitProjectDir = "") {
+  if (explicitProjectDir) {
+    const root = path.resolve(explicitProjectDir);
+    return path.join(root, projectArtifactDirectory(root));
+  }
   let current = path.dirname(path.resolve(sourcePath));
   while (current !== path.dirname(current)) {
-    if (path.basename(current) === ".autotap") return current;
-    const candidate = path.join(current, ".autotap");
+    if (isProjectArtifactDirectory(path.basename(current))) return current;
+    const candidate = path.join(current, projectArtifactDirectory(current));
     if (fs.existsSync(candidate)) return candidate;
     current = path.dirname(current);
   }
@@ -97,16 +101,16 @@ function findAutotapDir(sourcePath, explicitProjectDir = "") {
 }
 
 export function loadTaskRegistry({ sourcePath, projectDir = "", taskFiles = [] }) {
-  const autotapDir = findAutotapDir(sourcePath, projectDir);
-  const taskDir = autotapDir ? path.join(autotapDir, "tasks") : "";
+  const tappDir = findTappDir(sourcePath, projectDir);
+  const taskDir = tappDir ? path.join(tappDir, "tasks") : "";
   const reviewed = taskDir && fs.existsSync(taskDir)
     ? fs.readdirSync(taskDir).filter((name) => /\.ya?ml$|\.json$/i.test(name)).map((name) => path.join(taskDir, name))
     : [];
-  // Draft contracts generated under `.autotap/proposals/contracts` may compile
+  // 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 = String(path.resolve(sourcePath || "")).includes(`${path.sep}.autotap${path.sep}proposals${path.sep}`);
-  const proposalDir = proposalSource && autotapDir ? path.join(autotapDir, "proposals", "tasks") : "";
+  const proposalSource = [".tapp", ".autotap"].some((directory) => String(path.resolve(sourcePath || "")).includes(`${path.sep}${directory}${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))
     : [];
@@ -169,7 +173,7 @@ export function compileTaskSteps({ steps, registry, platform = "", flowVars = {}
     const invocation = taskCall(step);
     if (!invocation) { expanded.push(step); continue; }
     const task = registry.get(invocation.call.task);
-    if (!task) throw new Error(`Task '${invocation.call.task}' was not found in .autotap/tasks`);
+    if (!task) throw new Error(`Task '${invocation.call.task}' was not found in .tapp/tasks`);
     if (stack.includes(task.name)) throw new Error(`Task cycle detected: ${[...stack, task.name].join(" -> ")}`);
     const implementation = implementationSteps(task, platform);
     if (!implementation?.steps) throw new Error(`Task '${task.name}' has no '${platform || "shared"}' implementation`);

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

@@ -97,6 +97,65 @@ export function webBrowserLaunchOptions(environment = process.env) {
   };
 }
 
+// Focused one-screen inspection for the agent-facing `tapp open <url>` and `tapp tree <url>`
+// commands. This deliberately does no exploration or judgment; it opens exactly one page,
+// captures the visible semantic controls, and optionally takes one screenshot.
+export async function inspectWebPage({ url, timeoutMs = NAV_TIMEOUT_MS, screenshot = true }) {
+  let target;
+  try { target = new URL(url); }
+  catch { throw new Error("Web inspection needs a valid http(s) URL"); }
+  if (!/^https?:$/.test(target.protocol)) throw new Error("Web inspection needs a valid http(s) URL");
+
+  const { chromium } = await loadPlaywright();
+  const browser = await chromium.launch(webBrowserLaunchOptions());
+  try {
+    const context = await browser.newContext({ viewport: { width: 1280, height: 900 } });
+    const page = await context.newPage();
+    const boundedTimeout = Math.max(1000, Math.min(60_000, Number(timeoutMs) || NAV_TIMEOUT_MS));
+    page.setDefaultTimeout(boundedTimeout);
+    const response = await page.goto(target.href, { waitUntil: "domcontentloaded", timeout: boundedTimeout });
+    if (response && response.status() >= 400) throw new Error(`Could not open ${target.href}: HTTP ${response.status()}`);
+    await page.waitForTimeout(SETTLE_MS);
+    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]")]
+        .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 label = (element.labels?.[0]?.textContent || element.getAttribute("aria-label") || element.textContent || element.placeholder || element.name || element.id || "").trim().slice(0, 120);
+          return {
+            type: field ? (secure ? "SecureTextField" : "TextField") : "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,
+          };
+        })
+        .filter((control) => control.label || control.identifier);
+      return {
+        heading: document.querySelector("h1")?.textContent?.trim() || "",
+        title: document.title.trim(),
+        controls,
+      };
+    });
+    const image = screenshot ? await page.screenshot({ type: "png" }) : null;
+    return {
+      url: page.url(),
+      screenTitle: webScreenTitle(observed, target.pathname || target.href),
+      elements: observed.controls,
+      image,
+    };
+  } finally {
+    await browser.close().catch(() => {});
+  }
+}
+
 export function normalizeWebSeedRoutes(url, routes, limit = 5) {
   const origin = new URL(url);
   const boundedLimit = Math.max(0, Math.min(10, Number(limit) || 0));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aarwitz/tapp",
-  "version": "0.15.1",
+  "version": "0.16.1",
   "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/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": "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: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

@@ -15,9 +15,9 @@
 #                      # bundle id is detected from the .app when omitted
 #                      [--actions N]              # exploration budget (default 40)
 #                      [--timeout S]              # exploration watchdog (default 600)
-#                      [--flows <glob>]           # Flow YAMLs to replay (default: <app repo>/.autotap/flows/*.yml if --project-dir given)
-#                      [--scenarios <glob>]       # Multi-actor Scenario YAMLs (web; default: <app repo>/.autotap/scenarios/*.yml)
-#                      [--contracts <glob>]       # TypeScript release contracts (default: <app repo>/.autotap/contracts/*.contract.ts)
+#                      [--flows <glob>]           # Flow YAMLs to replay (default: <app repo>/.tapp/flows/*.yml if --project-dir given)
+#                      [--scenarios <glob>]       # Multi-actor Scenario YAMLs (web; default: <app repo>/.tapp/scenarios/*.yml)
+#                      [--contracts <glob>]       # TypeScript release contracts (default: <app repo>/.tapp/contracts/*.contract.ts)
 #                      [--project-dir <dir>]      # the app repo checkout (for flows + baseline defaults)
 #                      [--pr-base <git-ref>]      # select critical + diff-relevant contracts from base...head
 #                      [--pr-head <git-ref>]      # default HEAD
@@ -79,10 +79,15 @@ 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
-[[ -z "$FLOWS" && -n "$PROJECT_DIR" && -d "$PROJECT_DIR/.autotap/flows" ]] && FLOWS="$PROJECT_DIR/.autotap/flows/*.yml"
-[[ "$PLATFORM" == "web" && -z "$SCENARIOS" && -n "$PROJECT_DIR" && -d "$PROJECT_DIR/.autotap/scenarios" ]] && SCENARIOS="$PROJECT_DIR/.autotap/scenarios/*.yml"
-[[ -z "$CONTRACTS" && -n "$PROJECT_DIR" && -d "$PROJECT_DIR/.autotap/contracts" ]] && CONTRACTS="$PROJECT_DIR/.autotap/contracts/*.contract.ts"
-[[ -z "$BASELINE" && -n "$PROJECT_DIR" && -f "$PROJECT_DIR/.autotap/baseline.json" ]] && BASELINE="$PROJECT_DIR/.autotap/baseline.json"
+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"
+[[ -z "$CONTRACTS" && -n "$TAPP_PROJECT_ARTIFACTS" && -d "$TAPP_PROJECT_ARTIFACTS/contracts" ]] && CONTRACTS="$TAPP_PROJECT_ARTIFACTS/contracts/*.contract.ts"
+[[ -z "$BASELINE" && -n "$TAPP_PROJECT_ARTIFACTS" && -f "$TAPP_PROJECT_ARTIFACTS/baseline.json" ]] && BASELINE="$TAPP_PROJECT_ARTIFACTS/baseline.json"
 [[ -z "$BASELINE" || -f "$BASELINE" ]] || { echo "❌ Baseline not found: $BASELINE" >&2; exit 2; }
 if [[ -n "$BASELINE" ]]; then
   python3 -c 'import json,sys; json.load(open(sys.argv[1]))' "$BASELINE" 2>/dev/null \

package/scripts/flow_lib.py

@@ -23,7 +23,7 @@ def load_flow(path):
 
 
 def to_yaml(json_str):
-    """Emit a recorded/inline Flow (JSON string) as tidy YAML for saving to .autotap/flows/*.yml."""
+    """Emit a recorded/inline Flow (JSON string) as tidy YAML for saving to .tapp/flows/*.yml."""
     import yaml
     flow = json.loads(json_str)
     # Order keys for readability. `platform` + `url` make the same repository-native

package/docs/BROWSER-PRODUCT.md

@@ -1,72 +0,0 @@
-# Browser Release Studio
-
-Status: current local-product contract as of 2026-08-08.
-
-The browser is Tapp's primary customer workflow. Web is also one application target beside iOS and
-Android; it is not a separate QA product. CLI, MCP, VS Code, the Action, desktop, and future managed
-SaaS adapt the shared product operations described in [`PRODUCT-ENGINE.md`](PRODUCT-ENGINE.md).
-
-## Start locally
-
-```bash
-npx -y @aarwitz/tapp app
-```
-
-Tapp prints an authenticated one-time launch URL and opens it in the default browser. Use
-`--no-open` when copying the URL manually and `--port 4317` only when a fixed loopback port is
-needed. Drag/drop or Browse Folder copies source into a Tapp-owned workspace. Connect GitHub lists
-repositories authorized to the local `gh` session and makes a shallow isolated clone.
-`tapp app /path/to/repo` intentionally works directly in that checkout.
-
-The local server binds to `127.0.0.1`. It owns workspace paths; browser requests cannot submit an
-arbitrary server path. Mutations require an `HttpOnly` same-site session cookie, the exact local
-Origin, and an in-memory CSRF token. Application runtimes, repository credentials, and evidence stay
-in the local process/filesystem. This is a local trust boundary, not hosted multi-tenancy.
-
-## Product journey
-
-1. **Connect** a copied folder, an explicit checkout, or a repository authorized by local `gh`.
-2. **Detect and choose** an iOS, Android, or web target. Continue automatically only when the target
-   and configuration are conclusive.
-3. **Build, launch, and explore** the real simulator, emulator/device, or browser surface.
-4. **Understand the UI Map** through observed states, transitions, controls, provenance, and gaps.
-5. **Review intent** by approving, rejecting, deferring, or constraining a compact release plan.
-6. **Generate drafts** of Tasks and contracts. Drafts remain visibly untrusted.
-7. **Validate** approved drafts deterministically against the real target.
-8. **Promote** only validated artifacts into the canonical suite and refreshed Application Model.
-9. **Gate** with autonomous evidence plus the promoted deterministic suite.
-10. **Baseline** only a passing, conclusive, target-scoped gate.
-11. **Install CI** by previewing and writing a reviewable repository patch. Tapp does not commit,
-    push, create GitHub secrets, or enable branch protection.
-
-Successful semantic actions can be saved in `.autotap/flows/`; credential values are templated to
-environment references. Long-lived repository artifacts store binding names, not resolved secret
-values.
-
-## Verified reference journey
-
-`tests/browser-journey.test.js` drives the visible local browser against a fresh CommerceDemo copy.
-It exercises startup, a real live web surface and semantic action, UI Map creation, Flow recording
-and replay, proposal review, generation, deterministic validation, promotion, a first gate,
-baseline-aware rerun, and CI preview.
-
-The opt-in `tests/browser-native-journey.test.js` passed on 2026-08-06 against a booted iOS
-simulator: the browser built and installed a disposable DemoApp checkout, ran shared target
-preparation and exploration, rendered an observed UI Map, drove the live surface, and saved a
-repository-native iOS Flow. The equivalent Android browser journey was not verified in that audit
-because no emulator/device was connected.
-
-This evidence proves representative local journeys. It does not prove arbitrary frameworks,
-production credentials, third-party services, hosted execution, or complete inference of business
-intent.
-
-## Hosted relationship
-
-The future hosted application will present the same product journey through a different adapter: application
-accounts/organizations, GitHub App repository authorization, private storage, a durable queue, and
-isolated managed workers. It cannot reuse the loopback session, local `gh` authority, filesystem
-boundary, or in-memory ownership assumptions.
-
-The old hosted preview and `cloud/` prototype do not satisfy this boundary. Follow
-[`SAAS-ARCHITECTURE.md`](SAAS-ARCHITECTURE.md) and do not market or accept private repositories until
-[`SAAS-READINESS.md`](SAAS-READINESS.md) passes.

package/docs/PRODUCT-ENGINE.md

@@ -1,102 +0,0 @@
-# One Tapp product engine
-
-Status: current product-engine contract as of 2026-08-08.
-
-Tapp has several interfaces, not several products. The source of truth for customer-critical
-operations is [`mcp-server/src/product-operations.js`](../mcp-server/src/product-operations.js).
-An interface may validate its transport and render a result; it must not redefine onboarding,
-review, trust, baseline, or gate semantics.
-
-## Product operation contract
-
-The shared engine owns these operations:
-
-| Operation | Authoritative result |
-|---|---|
-| `initializeProductProject` | detected targets, real exploration, Application Model, UI Map, release plan |
-| `readProductProject` | one current, read-only product snapshot for any interface |
-| `reviewProductPlan` | explicit approve/reject/defer decisions |
-| `generateProductPlan` | compile-checked but untrusted Task/contract drafts |
-| `validateProductPlan` | real-target, deterministic replay evidence |
-| `promoteProductPlan` | canonical Tasks/contracts, refreshed model/plan, updated map coverage |
-| `prepareProductCi` / `installProductCi` | target-aware workflow and machine-readable CI manifest |
-| `runProductGate` | autonomous evidence plus the committed deterministic suite and one gate decision |
-| `createProductBaseline` | conclusive, platform-and-target-specific comparison state |
-
-Deterministic contract execution is in
-[`mcp-server/src/product-execution.js`](../mcp-server/src/product-execution.js). It invokes platform
-executors directly; MCP does not shell through the CLI, and the browser does not shell through MCP.
-
-## Interfaces
-
-```text
-Browser Release Studio ─┐
-CLI                     ├── product-operations ── application model / UI Map / Tasks / contracts
-MCP                     ┘             │
-                                      └── deterministic executors / portable gate / evidence
-
-VS Code ── MCP client
-Desktop ── canonical artifact reader (migration to operation client remains)
-Action  ── portable gate adapter
-Hosted  ── tenant-aware SaaS adapter + queued isolated shared-operation workers (not built)
-```
-
-Current convergence:
-
-- the browser calls only shared product operations;
-- CLI initialization, plan lifecycle, deterministic draft validation, promotion, gate/baseline
-  lifecycle, and CI installation call the same operations. Native build preparation remains at the
-  adapter boundary and passes a resolved `.app` or APK into the shared gate;
-- MCP initialization, plan lifecycle, deterministic draft validation, promotion, baseline, and CI
-  installation call the same operations;
-- the GitHub Action and `runProductGate` call the same portable gate and evidence protocol;
-- VS Code remains a thin MCP client;
-- desktop reads the same `.autotap` artifacts but still has legacy import/build orchestration. It is
-  retained, not the launch UX, until that orchestration is removed;
-- `cloud/runner` is retained prototype evidence for exact checkout, versioned operation envelopes,
-  leases, and cleanup. It is not the production hosted adapter or an adequate arbitrary-customer
-  isolation boundary. The new SaaS must call these shared operations only through the tenant-aware,
-  queued worker contract in [`SAAS-ARCHITECTURE.md`](SAAS-ARCHITECTURE.md).
-
-## Canonical repository protocol
-
-New product behavior writes only `.autotap/`:
-
-```text
-.autotap/
-  project.json              # actors, env binding names, controlled lifecycle; never secret values
-  application-model.json    # detected/observed/declared product facts
-  ui-map.json               # grounded screen/action/transition graph
-  release-plan.json         # proposals and explicit human decisions
-  tasks/                    # reusable deterministic semantic operations
-  contracts/                # reviewed business guarantees
-  baselines/<platform>/     # conclusive target-specific comparison state
-  ci.json                   # generated CI installation manifest
-```
-
-`.autotap.yml` and `.tapp.yml` are legacy compatibility inputs, not parallel sources of product
-truth. Do not add a fourth configuration format. Migration readers may normalize old input into the
-canonical model; only an explicit reviewed operation may write new repository artifacts.
-
-## Anti-duplication rules
-
-1. Trust states (`pending`, `approved`, `validated-draft`, `promoted`) are computed by the engine.
-2. Interfaces render `readProductProject`; they do not infer readiness from file existence.
-3. Re-exploration refreshes evidence while preserving reviewed decisions everywhere.
-4. Promotion refreshes the Application Model immediately; no interface may show stale pre-promotion
-   requirements.
-5. Baselines are identified by platform and stable target id everywhere.
-6. An adapter-specific feature is not complete until its engine operation is useful without that
-   adapter.
-7. Equivalence tests should assert artifacts and structured results, not merely matching copy.
-
-## Remaining migration
-
-The next safe convergence work is deliberately narrow:
-
-1. replace desktop import/build orchestration with a local product-operation client;
-2. delete the two desktop detection/scaffolding paths only after equivalence fixtures pass;
-3. implement managed account, organization, and tenant authorization before connecting repositories;
-4. implement scoped GitHub authorization, private evidence, and disposable per-job
-   identity/simulator/credential isolation before accepting customer code;
-5. preserve CLI/MCP/VS Code/Action as adapters—do not rebuild their product logic.