@aarwitz/tapp 0.15.1 → 0.16.1

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

@@ -31,6 +31,7 @@ import { writeHtmlReport } from "./html-report.js";
 import { buildUiMapFromMarkers, writeUiMap } from "./ui-map.js";
 import { proposeSelectorMaintenance, validateWebMaintenanceProposal } from "./maintenance-proposal.js";
 import { isBusinessUiMapNode, releasePlanCandidateFromUiMapNode } from "./application-model.js";
+import { existingProjectArtifactPath } from "./project-paths.js";
 
 function parseArgs(argv) {
   const args = { flowLogs: [], failOn: "gate" };
@@ -201,14 +202,14 @@ function targetCoverageDisposition(target, currentNode, projectDir = "") {
     provenance: "runtime-observed",
   });
   if (projectDir) {
-    const releasePlanPath = path.join(path.resolve(projectDir), ".autotap", "release-plan.json");
+    const releasePlanPath = existingProjectArtifactPath(path.resolve(projectDir), "release-plan.json");
     try {
       const releasePlan = JSON.parse(fs.readFileSync(releasePlanPath, "utf8"));
       const existing = (releasePlan.items || []).find((candidate) => candidate.id === item.id || candidate.name === item.name ||
         (candidate.groundedBy || []).some((ground) => ground.type === "ui-map-node" && ground.id === currentNode.id));
       if (existing) return {
         existingReleasePlanItem: {
-          path: ".autotap/release-plan.json",
+          path: ".tapp/release-plan.json",
           id: existing.id,
           name: existing.name,
           decision: existing.decision,
@@ -219,7 +220,7 @@ function targetCoverageDisposition(target, currentNode, projectDir = "") {
           kind: "release-plan-item-proposal",
           status: "matches-existing-release-plan",
           autoApply: false,
-          targetPath: ".autotap/release-plan.json",
+          targetPath: ".tapp/release-plan.json",
           operation: { op: "reconcile-item", item },
           reason: "Fresh PR runtime and changed-file evidence can be attached to the existing grounded item only through explicit adoption; its current human decision is preserved.",
           requiredValidation: "After explicit evidence reconciliation, keep the normal review, generation, deterministic replay, and promotion requirements.",
@@ -231,7 +232,7 @@ function targetCoverageDisposition(target, currentNode, projectDir = "") {
     kind: "release-plan-item-proposal",
     status: "awaiting-explicit-adoption",
     autoApply: false,
-    targetPath: ".autotap/release-plan.json",
+    targetPath: ".tapp/release-plan.json",
     operation: { op: "add-item", item },
     reason: `The changed ${currentNode.name} surface was observed in this PR run but is not covered by a selected release contract.`,
     requiredValidation: "Explicitly adopt and review this item, generate reusable UI-Map-backed Tasks, then replay the resulting contract against the real target before promotion.",

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

@@ -1,5 +1,6 @@
 import fs from "node:fs";
 import path from "node:path";
+import { existingProjectArtifactPath, projectArtifactDirectory } from "./project-paths.js";
 
 function inside(root, candidate) {
   const value = path.relative(root, candidate);
@@ -36,7 +37,12 @@ export function selectApplicationTarget(model, { platform = "", target = "" } =
 
 export function baselinePathForTarget(projectDir, target) {
   const root = fs.realpathSync(path.resolve(projectDir));
-  return path.join(root, ".autotap", "baselines", target.platform, `${targetSlug(target.id)}.json`);
+  return path.join(root, ".tapp", "baselines", target.platform, `${targetSlug(target.id)}.json`);
+}
+
+export function existingBaselinePathForTarget(projectDir, target) {
+  const root = fs.realpathSync(path.resolve(projectDir));
+  return existingProjectArtifactPath(root, "baselines", target.platform, `${targetSlug(target.id)}.json`);
 }
 
 export function validateBaselineReport(report, { platform, targetId } = {}) {
@@ -134,8 +140,11 @@ function posix(value) {
 }
 
 function suiteDirectories(root, target, kind) {
-  const candidates = [path.join(root, ".autotap", kind)];
-  if (target.sourcePath && target.sourcePath !== ".") candidates.push(path.join(root, target.sourcePath, ".autotap", kind));
+  const candidates = [path.join(root, projectArtifactDirectory(root), kind)];
+  if (target.sourcePath && target.sourcePath !== ".") {
+    const targetRoot = path.join(root, target.sourcePath);
+    candidates.push(path.join(targetRoot, projectArtifactDirectory(targetRoot), kind));
+  }
   return [...new Set(candidates)].filter((candidate) => fs.existsSync(candidate) && fs.statSync(candidate).isDirectory())
     .map((candidate) => `${posix(path.relative(root, candidate))}/*.yml`);
 }
@@ -176,7 +185,7 @@ function credentialConfiguration(model, targetContracts = []) {
     if (requirements.has("email")) bindings.add("TAPP_TEST_EMAIL");
     if (requirements.has("password")) bindings.add("TAPP_TEST_PASSWORD");
   }
-  for (const name of bindings) if (!/^[A-Z_][A-Z0-9_]{0,127}$/.test(String(name))) throw new Error(`Actor credential binding '${name}' is not a safe environment-variable name; rerun tapp init from valid .autotap/project.json`);
+  for (const name of bindings) if (!/^[A-Z_][A-Z0-9_]{0,127}$/.test(String(name))) throw new Error(`Actor credential binding '${name}' is not a safe environment-variable name; rerun tapp init from valid .tapp/project.json`);
   const inputs = {};
   const primaryEmail = primary.credentialBindings?.email || (!primary.credentialBindings && requirements.has("email") ? "TAPP_TEST_EMAIL" : "");
   const primaryPassword = primary.credentialBindings?.password || (!primary.credentialBindings && requirements.has("password") ? "TAPP_TEST_PASSWORD" : "");
@@ -220,7 +229,7 @@ function targetInputs(root, model, target) {
   if (flows.length) inputs.flows = flows.join(" ");
   if (scenarios.length) inputs.scenarios = scenarios.join(" ");
   if (contracts.length) inputs.contracts = contracts.join(" ");
-  const baselinePath = baselinePathForTarget(root, target);
+  const baselinePath = existingBaselinePathForTarget(root, target);
   if (fs.existsSync(baselinePath)) inputs.baseline = posix(path.relative(root, baselinePath));
   const credentials = credentialConfiguration(model, targetContracts);
   Object.assign(inputs, credentials.inputs);
@@ -292,7 +301,7 @@ export function renderGithubWorkflow({ projectDir, model, actionRef, defaultBran
     jobs.push(lines.join("\n"));
   }
   const workflow = [
-    "# Generated by `tapp ci install` from .autotap/application-model.json.",
+    "# Generated by `tapp ci install` from .tapp/application-model.json.",
     "# Review this patch. Tapp never overwrites it silently.",
     "name: Tapp release gate",
     "",
@@ -341,7 +350,7 @@ export function renderGithubWorkflow({ projectDir, model, actionRef, defaultBran
   return { workflow, manifest };
 }
 
-export function writeCiInstallation({ projectDir, workflow, manifest, workflowPath = ".github/workflows/tapp.yml", manifestPath = ".autotap/ci.json", replace = false } = {}) {
+export function writeCiInstallation({ projectDir, workflow, manifest, workflowPath = ".github/workflows/tapp.yml", manifestPath = ".tapp/ci.json", replace = false } = {}) {
   const root = fs.realpathSync(path.resolve(projectDir || process.cwd()));
   const destinations = [path.resolve(root, workflowPath), path.resolve(root, manifestPath)];
   for (const destination of destinations) if (!inside(root, destination)) throw new Error("CI installation outputs must remain inside the repository");

package/mcp-server/src/index.js

@@ -13,6 +13,7 @@ import {
 } from "@modelcontextprotocol/sdk/types.js";
 
 import { parseOcqaMarkers, buildQaReport, computeRegression } from "./report.js";
+import { existingProjectArtifactPath, projectArtifactDirectory } from "./project-paths.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -918,7 +919,7 @@ export async function saveInteractiveSessionFlow({ projectDir, name, addFinalAss
     steps,
   };
   const slug = flowName.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60) || "flow";
-  const dir = path.join(root, ".autotap", "flows");
+  const dir = path.join(root, ".tapp", "flows");
   const outPath = path.join(dir, `${slug}.yml`);
   if (fs.existsSync(outPath) && !replace) {
     const error = new Error(`Flow '${path.relative(root, outPath)}' already exists. Choose another name or explicitly replace it.`);
@@ -1589,7 +1590,7 @@ export async function runQaIos({ bundleId, maxActions, timeout, args = {}, onPro
 export async function runInitExploration({
   projectDir,
   platform,
-  outDir = ".autotap",
+  outDir = ".tapp",
   url = "",
   target = "",
   bundleId = "",
@@ -1610,7 +1611,7 @@ export async function runInitExploration({
   catch { return { error: `Repository directory not found: ${projectDir || process.cwd()}` }; }
   const selected = String(platform || (url ? "web" : appId || apkPath ? "android" : "ios")).toLowerCase();
   if (!["ios", "android", "web"].includes(selected)) return { error: "platform must be ios|android|web" };
-  const mapPath = path.resolve(root, outDir, "ui-map.json");
+  const mapPath = path.resolve(root, projectArtifactDirectory(root, outDir), "ui-map.json");
   if (!isInsideDir(root, mapPath)) return { error: "UI Map output must remain inside the repository" };
 
   let resolvedTarget = "";
@@ -2152,7 +2153,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           testEmail: { type: "string", description: "Explore: actor/login email; never persisted in the model" },
           testPassword: { type: "string", description: "Explore: actor/login password; never persisted in the model" },
           maxContracts: { type: "integer", minimum: 1, maximum: 50, default: 15 },
-          outDir: { type: "string", description: "Repo-relative artifact directory; default .autotap" },
+          outDir: { type: "string", description: "Repo-relative artifact directory; default .tapp" },
         },
       },
     },
@@ -2160,7 +2161,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       name: "tapp_actor_config",
       title: "Inspect or configure named test actors without storing credential values",
       description:
-        "Manage the repository-native .autotap/project.json actor/session contract used by init, release-contract generation, and CI. `read` is inspect-only. `set` writes an explicit actor role, isolation/provisioning policy, and credential-name to environment-variable-name bindings. The tool never accepts, returns, or persists credential values and never overwrites an actor unless replace is explicit.",
+        "Manage the repository-native .tapp/project.json actor/session contract used by init, release-contract generation, and CI. `read` is inspect-only. `set` writes an explicit actor role, isolation/provisioning policy, and credential-name to environment-variable-name bindings. The tool never accepts, returns, or persists credential values and never overwrites an actor unless replace is explicit.",
       inputSchema: {
         type: "object",
         properties: {
@@ -2180,14 +2181,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       name: "tapp_release_plan",
       title: "Inspect or explicitly review a Tapp release plan",
       description:
-        "Read the repository-native release plan, apply explicit approve/reject/defer decisions, generate grounded Task/contract drafts, deterministically validate drafts on a real target, or explicitly promote fully replay-validated drafts into reviewed repository-native artifacts. Review changes only decision metadata. Generation writes under .autotap/proposals, never overwrites, never invokes AI, and remains untrusted until real deterministic replay passes. Web validation can build/start/stop the detected managed target when url is omitted.",
+        "Read the repository-native release plan, apply explicit approve/reject/defer decisions, generate grounded Task/contract drafts, deterministically validate drafts on a real target, or explicitly promote fully replay-validated drafts into reviewed repository-native artifacts. Review changes only decision metadata. Generation writes under .tapp/proposals, never overwrites, never invokes AI, and remains untrusted until real deterministic replay passes. Web validation can build/start/stop the detected managed target when url is omitted.",
       inputSchema: {
         type: "object",
         properties: {
           authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           operation: { type: "string", enum: ["read", "review", "generate", "validate", "promote"], default: "read" },
-          planPath: { type: "string", description: "Repo-relative plan path; default .autotap/release-plan.json" },
-          projectDir: { type: "string", description: "Generate: repo-relative project root containing the scoped .autotap Task directories" },
+          planPath: { type: "string", description: "Repo-relative plan path; default .tapp/release-plan.json" },
+          projectDir: { type: "string", description: "Generate: repo-relative project root containing the scoped .tapp Task directories" },
           approve: { type: "array", items: { type: "string" }, description: "Plan item ids or names to approve" },
           reject: { type: "array", items: { type: "string" }, description: "Plan item ids or names to reject" },
           defer: { type: "array", items: { type: "string" }, description: "Plan item ids or names to defer" },
@@ -2214,11 +2215,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           operation: { type: "string", enum: ["inspect", "install", "baseline"], default: "inspect" },
           projectDir: { type: "string", description: "Repo-relative project root; defaults to the MCP workspace root" },
-          modelPath: { type: "string", description: "Repo-relative application model path; defaults to <projectDir>/.autotap/application-model.json" },
+          modelPath: { type: "string", description: "Repo-relative application model path; defaults to <projectDir>/.tapp/application-model.json" },
           actionRef: { type: "string", description: "GitHub Action reference owner/repository@release-tag-or-sha; defaults to the current Tapp release tag" },
           defaultBranch: { type: "string", default: "main" },
           workflowPath: { type: "string", description: "Install: project-relative output; default .github/workflows/tapp.yml" },
-          manifestPath: { type: "string", description: "Install: project-relative output; default .autotap/ci.json" },
+          manifestPath: { type: "string", description: "Install: project-relative output; default .tapp/ci.json" },
           allowUnresolved: { type: "boolean", default: false, description: "Permit writing a draft whose manifest names unresolved target configuration" },
           replace: { type: "boolean", default: false, description: "Explicitly replace an existing generated workflow/manifest or target baseline" },
           reportPath: { type: "string", description: "Baseline: repo-relative successful conclusive portable-gate JSON report" },
@@ -2240,7 +2241,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           operation: { type: "string", enum: ["read", "build", "diff"], default: "read" },
           captureId: { type: "string", description: "Read/build from this Tapp capture's ocqa-markers.txt/ui-map.json" },
-          mapPath: { type: "string", description: "Repo-relative UI Map path for read, or build output (default .autotap/ui-map.json)" },
+          mapPath: { type: "string", description: "Repo-relative UI Map path for read, or build output (default .tapp/ui-map.json)" },
           markersPath: { type: "string", description: "Repo-relative OCQA markers path for build when captureId is not supplied" },
           beforePath: { type: "string", description: "Repo-relative baseline UI Map for diff" },
           afterPath: { type: "string", description: "Repo-relative current UI Map for diff" },
@@ -2255,7 +2256,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       name: "tapp_task",
       title: "Inspect, validate, or compile a reusable deterministic Task",
       description:
-        "Work with repository-native compositional Tasks in .autotap/tasks. Tasks define inputs, outputs, pre/postconditions, platform implementations, and the UI Map states/transitions they cover. " +
+        "Work with repository-native compositional Tasks in .tapp/tasks. Tasks define inputs, outputs, pre/postconditions, platform implementations, and the UI Map states/transitions they cover. " +
         "Validation is deterministic and can ground selectors/coverage against ui-map.json. Compilation expands a Task into the shared keyless Flow contract with reviewable Task provenance; pass that returned flow to tapp_flow_run to replay it. No AI or API key is used.",
       inputSchema: {
         type: "object",
@@ -2263,7 +2264,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         properties: {
           authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           operation: { type: "string", enum: ["read", "validate", "compile"], default: "validate" },
-          taskPath: { type: "string", description: "Repo-relative .autotap/tasks/*.yml|json file" },
+          taskPath: { type: "string", description: "Repo-relative .tapp/tasks/*.yml|json file" },
           platform: { type: "string", enum: ["ios", "android", "web"], description: "Implementation to validate/compile" },
           inputs: { type: "object", additionalProperties: { type: "string" }, description: "Task inputs for compile. Secret inputs must be environment placeholders such as $TEST_PASSWORD, never plaintext." },
           mapPath: { type: "string", description: "Optional repo-relative UI Map v1 used to ground states, edges, and semantic controls" },
@@ -2276,7 +2277,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       name: "tapp_release_contract",
       title: "Inspect, validate, compile, or run a release contract",
       description:
-        "Work with repository-native TypeScript release contracts in .autotap/contracts. Contracts express business guarantees through reusable Tasks, named actors, exact/eventual expectations, criticality, policy, and UI Map coverage. " +
+        "Work with repository-native TypeScript release contracts in .tapp/contracts. Contracts express business guarantees through reusable Tasks, named actors, exact/eventual expectations, criticality, policy, and UI Map coverage. " +
         "Compilation targets the same deterministic Flow/Scenario evidence contract; ordinary run is keyless and never invokes a model. Multi-actor isolated replay is currently web-only.",
       inputSchema: {
         type: "object",
@@ -2284,7 +2285,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         properties: {
           authToken: { type: "string", description: "Required when TAPP_MCP_TOKEN is set" },
           operation: { type: "string", enum: ["read", "validate", "compile", "run"], default: "validate" },
-          contractPath: { type: "string", description: "Repo-relative .autotap/contracts/*.contract.ts file" },
+          contractPath: { type: "string", description: "Repo-relative .tapp/contracts/*.contract.ts file" },
           platform: { type: "string", enum: ["ios", "android", "web"], description: "Target platform; optional when the contract declares exactly one" },
           mapPath: { type: "string", description: "Optional repo-relative UI Map v1 for coverage grounding" },
           updateMap: { type: "boolean", default: false, description: "Explicitly add the reviewed contract coverage to mapPath" },
@@ -2326,10 +2327,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
           },
           projectDir: { type: "string", description: "Repo-relative project root; defaults to the MCP workspace root" },
           platform: { type: "string", enum: ["ios", "android", "web"], description: "Optional platform filter" },
-          mapPath: { type: "string", description: "Project-relative UI Map; defaults to .autotap/ui-map.json" },
+          mapPath: { type: "string", description: "Project-relative UI Map; defaults to .tapp/ui-map.json" },
           prPlanPath: { type: "string", description: "Adopt: project-relative executed PR plan containing conclusive exploration evidence" },
           item: { type: "string", description: "Adopt: stable exploration target id whose reviewable proposal should be appended" },
-          releasePlanPath: { type: "string", description: "Adopt: project-relative target; defaults to .autotap/release-plan.json" },
+          releasePlanPath: { type: "string", description: "Adopt: project-relative target; defaults to .tapp/release-plan.json" },
         },
       },
     },
@@ -2356,7 +2357,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             description:
               "Inline Flow: {name, app, steps:[...], vars?}. Example: {name:'login', app:'com.acme.app', steps:[{tap:'Sign In'}, {type:{field:'Email', value:'$TEST_EMAIL'}}, {tap:'Continue'}, {assert_screen:'Home'}]}",
           },
-          flowPath: { type: "string", description: "Alternative to `flow`: repo-relative path to a .yml/.json Flow (e.g. .autotap/flows/login.yml)" },
+          flowPath: { type: "string", description: "Alternative to `flow`: repo-relative path to a .yml/.json Flow (e.g. .tapp/flows/login.yml)" },
           platform: { type: "string", enum: ["ios", "web", "android"], description: "Overrides Flow platform detection" },
           appBundleId: { type: "string", description: "iOS: overrides the Flow's `app:` field" },
           androidAppId: { type: "string", description: "Android: overrides the Flow's `app:` field" },
@@ -2394,7 +2395,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
         "Write a deterministic E2E Flow from a natural-language goal (e.g. 'sign in and open Settings'), " +
         "GROUNDED in the app's real screens so it can't invent steps. Tapp explores the app to build a " +
         "screen/control map (or reuses a recent run via captureId), then a model authors a Flow using only " +
-        "screens/controls that were actually observed. Saves it to .autotap/flows/<name>.yml and returns the " +
+        "screens/controls that were actually observed. Saves it to .tapp/flows/<name>.yml and returns the " +
         "YAML for review (optionally runs it). Needs a model backend (Tapp subscription token or " +
         "ANTHROPIC_API_KEY). Use this to bootstrap a test you then refine; use tapp_flow_run to replay it.",
       inputSchema: {
@@ -2418,7 +2419,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
       description:
         "Save what you've done in the CURRENT interactive session as a reusable, deterministic Flow " +
         "(record-by-doing). Every successful tapp_session_act (tap/type/swipe/back) is recorded; this " +
-        "writes them to .autotap/flows/<name>.yml with wait_for steps auto-inserted on screen changes and a " +
+        "writes them to .tapp/flows/<name>.yml with wait_for steps auto-inserted on screen changes and a " +
         "final assert_screen checkpoint. Typed credentials are templated to $TEST_EMAIL/$TEST_PASSWORD so the " +
         "flow is shareable. The saved flow replays with tapp_flow_run. Do it once → it's a test.",
       inputSchema: {
@@ -2908,7 +2909,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (maxContracts < 1 || maxContracts > 50) return errorResult("maxContracts must be between 1 and 50");
     const { initializeProductProject } = await import("./product-operations.js");
     try {
-      const outDir = isNonEmptyString(args.outDir) ? args.outDir.trim() : ".autotap";
+      const outDir = isNonEmptyString(args.outDir) ? args.outDir.trim() : ".tapp";
       const resolvedOut = path.resolve(projectDir, outDir);
       if (!isInsideDir(projectDir, resolvedOut)) return errorResult("outDir must be inside projectDir");
       const selectedPlatform = isNonEmptyString(args.platform) ? args.platform.trim().toLowerCase()
@@ -2979,7 +2980,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (unauthorized) return unauthorized;
     const operation = String(args.operation || "read").toLowerCase();
     if (!["read", "review", "generate", "validate", "promote"].includes(operation)) return errorResult("operation must be read|review|generate|validate|promote");
-    const planPath = path.resolve(repoRoot, isNonEmptyString(args.planPath) ? args.planPath.trim() : ".autotap/release-plan.json");
+    const planPath = isNonEmptyString(args.planPath) ? path.resolve(repoRoot, args.planPath.trim()) : existingProjectArtifactPath(repoRoot, "release-plan.json");
     if (!isInsideDir(repoRoot, planPath)) return errorResult("planPath must be inside the repo");
     if (!fs.existsSync(planPath)) return errorResult("Release plan not found", { planPath });
     let plan;
@@ -3054,7 +3055,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (!["inspect", "install", "baseline"].includes(operation)) return errorResult("operation must be inspect|install|baseline");
     const projectDir = isNonEmptyString(args.projectDir) ? path.resolve(repoRoot, args.projectDir.trim()) : repoRoot;
     if (!isInsideDir(repoRoot, projectDir) || !fs.existsSync(projectDir) || !fs.statSync(projectDir).isDirectory()) return errorResult("projectDir must be an existing directory inside the repo");
-    const modelPath = isNonEmptyString(args.modelPath) ? path.resolve(repoRoot, args.modelPath.trim()) : path.join(projectDir, ".autotap", "application-model.json");
+    const modelPath = isNonEmptyString(args.modelPath) ? path.resolve(repoRoot, args.modelPath.trim()) : existingProjectArtifactPath(projectDir, "application-model.json");
     if (!isInsideDir(projectDir, modelPath) || !fs.existsSync(modelPath)) return errorResult("Application model not found inside projectDir; run tapp_init first", { modelPath });
     let model;
     try { model = JSON.parse(fs.readFileSync(modelPath, "utf8")); }
@@ -3078,7 +3079,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const rendered = prepareProductCi({ projectDir, modelPath, actionRef, defaultBranch });
       if (operation === "inspect") return richResult(`🧩 CI plan — ${rendered.manifest.targets.length} target job(s) · ${rendered.manifest.unresolved.length} unresolved · read-only`, rendered);
       if (rendered.manifest.unresolved.length && !asBoolean(args.allowUnresolved)) return errorResult("CI workflow not installed because target configuration remains unresolved", { unresolved: rendered.manifest.unresolved, next: "Resolve the application model requirements or explicitly allow an inspect-only draft." });
-      const result = installProductCi({ projectDir, modelPath, actionRef, defaultBranch, workflowPath: isNonEmptyString(args.workflowPath) ? args.workflowPath.trim() : ".github/workflows/tapp.yml", manifestPath: isNonEmptyString(args.manifestPath) ? args.manifestPath.trim() : ".autotap/ci.json", replace: asBoolean(args.replace), allowUnresolved: asBoolean(args.allowUnresolved) });
+      const result = installProductCi({ projectDir, modelPath, actionRef, defaultBranch, workflowPath: isNonEmptyString(args.workflowPath) ? args.workflowPath.trim() : ".github/workflows/tapp.yml", manifestPath: isNonEmptyString(args.manifestPath) ? args.manifestPath.trim() : ".tapp/ci.json", replace: asBoolean(args.replace), allowUnresolved: asBoolean(args.allowUnresolved) });
       return richResult(`✅ Reviewable CI gate installed — ${result.manifest.targets.length} target job(s); no commit, push, branch protection, or GitHub resource was created`, result);
     } catch (error) { return errorResult("Could not prepare CI installation", { detail: error.message || String(error) }); }
   }
@@ -3109,7 +3110,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       const markersPath = capture ? path.join(capture.path, "ocqa-markers.txt") : resolveRepoFile(args.markersPath);
       if (!markersPath) return errorResult("markersPath must be inside the repo, or provide captureId");
       if (!fs.existsSync(markersPath)) return errorResult("OCQA markers not found", { markersPath });
-      const outPath = resolveRepoFile(args.mapPath, path.join(".autotap", "ui-map.json"));
+      const outPath = isNonEmptyString(args.mapPath) ? resolveRepoFile(args.mapPath) : existingProjectArtifactPath(repoRoot, "ui-map.json");
       if (!outPath) return errorResult("mapPath must be inside the repo");
       try {
         const observed = buildUiMapFromMarkers({ markersPath, platform: args.platform || "ios", target: args.target || "", runId: capture?.id || "" });
@@ -3120,7 +3121,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       } catch (error) { return errorResult("Could not build UI Map", { detail: error.message || String(error) }); }
     }
     if (operation !== "read") return errorResult("operation must be read|build|diff");
-    const mapPath = capture ? path.join(capture.path, "ui-map.json") : resolveRepoFile(args.mapPath, path.join(".autotap", "ui-map.json"));
+    const mapPath = capture ? path.join(capture.path, "ui-map.json") : isNonEmptyString(args.mapPath) ? resolveRepoFile(args.mapPath) : existingProjectArtifactPath(repoRoot, "ui-map.json");
     if (!mapPath) return errorResult("mapPath must be inside the repo");
     if (!fs.existsSync(mapPath)) return errorResult("UI Map not found; run QA or operation=build first", { mapPath });
     try {
@@ -3480,7 +3481,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const ungrounded = ungroundedScreens(parsed.steps, grounding);
     const flow = { name: args.name || parsed.name, app: bundleId, steps: parsed.steps };
     const slug = flow.name.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 60) || "generated-flow";
-    const dir = path.join(repoRoot, ".autotap", "flows");
+    const dir = path.join(repoRoot, ".tapp", "flows");
     fs.mkdirSync(dir, { recursive: true });
     const outPath = path.join(dir, `${slug}.yml`);
     const yamlRes = await runCommand("python3", [path.join(scriptsDir, "flow_lib.py"), "to-yaml", JSON.stringify(flow)], { cwd: repoRoot });

package/mcp-server/src/maintenance-proposal.js

@@ -125,16 +125,16 @@ export async function validateWebMaintenanceProposal({ proposal, projectDir, url
   if (!projectDir || !url) throw new Error("web maintenance validation requires projectDir and the running target URL");
   const root = fs.realpathSync(path.resolve(projectDir));
   const operation = proposal.operations[0];
-  const taskRoot = fs.realpathSync(path.join(root, ".autotap", "tasks"));
+  const taskRoot = fs.realpathSync(path.join(root, ".tapp", "tasks"));
   const sourceTask = fs.realpathSync(path.resolve(root, operation.taskPath));
   const sourceContract = fs.realpathSync(path.resolve(root, proposal.contractIntent.path));
-  if (!inside(taskRoot, sourceTask)) throw new Error("maintenance Task must be a regular reviewed file under .autotap/tasks");
+  if (!inside(taskRoot, sourceTask)) throw new Error("maintenance Task must be a regular reviewed file under .tapp/tasks");
   if (!inside(root, sourceContract)) throw new Error("maintenance contract must remain inside the project");
   if (digest(sourceTask) !== operation.taskSha256) throw new Error("Task digest changed after the proposal was created");
   if (digest(sourceContract) !== proposal.contractIntent.sha256) throw new Error("release-contract intent digest changed after the proposal was created");
 
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), "tapp-maintenance-validation-"));
-  const tempTasks = path.join(tempRoot, ".autotap", "tasks");
+  const tempTasks = path.join(tempRoot, ".tapp", "tasks");
   const stem = String(proposal.contractIntent.name || "contract").replace(/[^A-Za-z0-9._-]/g, "-");
   const outputDir = evidenceDir ? path.resolve(evidenceDir, stem) : path.join(tempRoot, "evidence");
   const logPath = path.join(outputDir, "validation.log");
@@ -153,7 +153,7 @@ export async function validateWebMaintenanceProposal({ proposal, projectDir, url
     if (!(contract.setup || []).length || !(contract.teardown || []).length) {
       throw new Error("automatic disposable maintenance validation requires controlled contract setup and teardown");
     }
-    const pseudoContractPath = path.join(tempRoot, ".autotap", "contracts", path.basename(sourceContract));
+    const pseudoContractPath = path.join(tempRoot, ".tapp", "contracts", path.basename(sourceContract));
     const execution = compileReleaseContract(contract, { platform: "web", sourcePath: pseudoContractPath });
     const result = await runWebFlow({ flow: execution, url, logPath, screenshotDir: outputDir });
     const contractUnchanged = digest(sourceContract) === proposal.contractIntent.sha256;

package/mcp-server/src/pr-selection.js

@@ -8,6 +8,7 @@ import crypto from "node:crypto";
 import { loadReleaseContractFile } from "./release-contract.js";
 import { loadTaskRegistry } from "./task-runtime.js";
 import { replayableUiMapNavigation, semanticUiKey } from "./ui-map.js";
+import { existingProjectArtifactPath, isProjectArtifactDirectory } from "./project-paths.js";
 
 function posix(value) {
   return String(value || "").replaceAll("\\", "/").replace(/^\.\//, "").replace(/^\/+/, "");
@@ -28,8 +29,8 @@ export function sourcePathMatches(changedFile, ownershipPath) {
 function repoRootFor(sourcePath) {
   let current = path.dirname(path.resolve(sourcePath));
   while (current !== path.dirname(current)) {
-    if (path.basename(current) === ".autotap") return path.dirname(current);
-    if (fs.existsSync(path.join(current, ".autotap"))) return current;
+    if (isProjectArtifactDirectory(path.basename(current))) return path.dirname(current);
+    if (fs.existsSync(existingProjectArtifactPath(current))) return current;
     current = path.dirname(current);
   }
   return process.cwd();
@@ -403,11 +404,11 @@ function mergeGroundingEvidence(existing, incoming) {
   return merged;
 }
 
-export function adoptPrCoverageProposal({ projectDir, prPlanPath, item, releasePlanPath = ".autotap/release-plan.json" } = {}) {
+export function adoptPrCoverageProposal({ projectDir, prPlanPath, item, releasePlanPath = ".tapp/release-plan.json" } = {}) {
   const root = fs.realpathSync(path.resolve(projectDir || process.cwd()));
   const source = path.resolve(prPlanPath || "");
   if (!prPlanPath || !fs.existsSync(source)) throw new Error(`PR plan not found: ${source || "(missing path)"}`);
-  const targetPath = path.resolve(root, releasePlanPath);
+  const targetPath = releasePlanPath === ".tapp/release-plan.json" ? existingProjectArtifactPath(root, "release-plan.json") : path.resolve(root, releasePlanPath);
   if (!inside(root, targetPath)) throw new Error("Release plan path must stay inside the project directory");
   if (!fs.existsSync(targetPath)) throw new Error(`Release plan not found: ${targetPath}; run tapp init first`);
   const prPlan = JSON.parse(fs.readFileSync(source, "utf8"));
@@ -423,7 +424,7 @@ export function adoptPrCoverageProposal({ projectDir, prPlanPath, item, releaseP
   const proposed = structuredClone(proposal.operation.item);
   if (proposed?.origin !== "deterministic-ui-map-proposal" || proposed?.decision !== "pending") throw new Error("Coverage proposal is not a pending UI-Map-grounded release-plan item");
   const ground = (proposed.groundedBy || []).find((entry) => entry.type === "ui-map-node");
-  const mapPath = path.join(root, ".autotap", "ui-map.json");
+  const mapPath = existingProjectArtifactPath(root, "ui-map.json");
   if (!ground || !fs.existsSync(mapPath)) throw new Error("Coverage proposal requires the repository's persistent UI Map");
   const map = JSON.parse(fs.readFileSync(mapPath, "utf8"));
   const node = (map.nodes || []).find((candidate) => candidate.id === ground.id && candidate.status !== "proposed");
@@ -583,7 +584,7 @@ export async function buildPrContractPlan({
     ...(Array.isArray(changedSymbolEvidence) ? changedSymbolEvidence : []),
   ]);
   const evidenceByFile = new Map(diffEvidence.map((item) => [item.file, item]));
-  const contractDir = path.join(root, ".autotap", "contracts");
+  const contractDir = existingProjectArtifactPath(root, "contracts");
   const discovered = discoverContracts && fs.existsSync(contractDir)
     ? fs.readdirSync(contractDir).filter((name) => /\.contract\.(?:ts|mts|mjs|js|json)$/i.test(name)).map((name) => path.join(contractDir, name)) : [];
   const files = [...new Set([...discovered, ...contractPaths.map((item) => path.resolve(root, item))])];
@@ -594,10 +595,10 @@ export async function buildPrContractPlan({
   }
 
   let tasks = new Map();
-  const registrySource = files[0] || path.join(root, ".autotap", "contracts", "contract.ts");
+  const registrySource = files[0] || existingProjectArtifactPath(root, "contracts", "contract.ts");
   try { tasks = loadTaskRegistry({ sourcePath: registrySource, projectDir: root }); } catch {}
   let map = null;
-  const resolvedMapPath = mapPath ? path.resolve(root, mapPath) : path.join(root, ".autotap", "ui-map.json");
+  const resolvedMapPath = mapPath ? path.resolve(root, mapPath) : existingProjectArtifactPath(root, "ui-map.json");
   if (fs.existsSync(resolvedMapPath)) map = JSON.parse(fs.readFileSync(resolvedMapPath, "utf8"));
 
   const impactedNodes = map ? map.nodes.filter((node) => matchedFiles(changes, node.sourcePaths || []).length) : [];

package/mcp-server/src/product-operations.js

@@ -16,8 +16,9 @@ import {
   reviewReleasePlan,
   writeInitArtifacts,
 } from "./application-model.js";
-import { baselinePathForTarget, renderGithubWorkflow, selectApplicationTarget, writeCiInstallation, writeTargetBaseline } from "./ci-setup.js";
+import { baselinePathForTarget, existingBaselinePathForTarget, renderGithubWorkflow, selectApplicationTarget, writeCiInstallation, writeTargetBaseline } from "./ci-setup.js";
 import { executeReleaseContract, runProductProcess } from "./product-execution.js";
+import { projectArtifactDirectory } from "./project-paths.js";
 
 const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
 const packageVersion = JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8")).version;
@@ -50,8 +51,9 @@ function atomicJson(file, value) {
   fs.renameSync(temporary, file);
 }
 
-function artifactPaths(root, outDir = ".autotap") {
-  const dir = path.resolve(root, outDir);
+function artifactPaths(root, outDir = ".tapp") {
+  const selectedOutDir = projectArtifactDirectory(root, outDir);
+  const dir = path.resolve(root, selectedOutDir);
   if (!inside(root, dir)) throw new Error("Artifact directory must remain inside the repository");
   return {
     dir,
@@ -94,7 +96,7 @@ function listProductRuns(root) {
 }
 
 function listRepositoryFlows(root) {
-  const directory = path.join(root, ".autotap", "flows");
+  const directory = path.join(root, projectArtifactDirectory(root), "flows");
   if (!fs.existsSync(directory)) return [];
   return fs.readdirSync(directory, { withFileTypes:true })
     .filter((entry) => entry.isFile() && /\.(?:ya?ml|json)$/i.test(entry.name))
@@ -127,7 +129,7 @@ function listRepositoryFlows(root) {
     .sort((left, right) => left.path.localeCompare(right.path));
 }
 
-export function readProductProject({ projectDir, outDir = ".autotap" } = {}) {
+export function readProductProject({ projectDir, outDir = ".tapp" } = {}) {
   const root = realProject(projectDir);
   const paths = artifactPaths(root, outDir);
   const model = readJson(paths.model);
@@ -137,7 +139,7 @@ export function readProductProject({ projectDir, outDir = ".autotap" } = {}) {
   const requirements = model?.requirements || [];
   const planItems = plan?.items || [];
   const baselines = (model?.targets || []).map((target) => {
-    const file = baselinePathForTarget(root, target);
+    const file = existingBaselinePathForTarget(root, target);
     return { targetId: target.id, platform: target.platform, path: file, relativePath: path.relative(root, file).replaceAll(path.sep, "/"), exists: fs.existsSync(file) };
   });
   return {
@@ -177,7 +179,7 @@ export function readProductProject({ projectDir, outDir = ".autotap" } = {}) {
 // target identity or configuration rules.
 export async function prepareProductTarget({
   projectDir,
-  outDir = ".autotap",
+  outDir = ".tapp",
   platform = "",
   target = "",
   appPath = "",
@@ -262,7 +264,7 @@ export async function prepareProductTarget({
 export async function initializeProductProject({
   projectDir,
   mode = "inspect",
-  outDir = ".autotap",
+  outDir = ".tapp",
   ownedUrl = "",
   platform = "",
   target = "",
@@ -326,7 +328,7 @@ function resolvePlan(root, outDir, planPath = "") {
   return { file, plan: readJson(file, { required: true }) };
 }
 
-export function reviewProductPlan({ projectDir, outDir = ".autotap", planPath = "", approve = [], reject = [], defer = [] } = {}) {
+export function reviewProductPlan({ projectDir, outDir = ".tapp", planPath = "", approve = [], reject = [], defer = [] } = {}) {
   const root = realProject(projectDir);
   const resolved = resolvePlan(root, outDir, planPath);
   const plan = reviewReleasePlan(resolved.plan, { approve, reject, defer });
@@ -334,7 +336,7 @@ export function reviewProductPlan({ projectDir, outDir = ".autotap", planPath =
   return { operation: "review-plan", plan, planPath: resolved.file, project: readProductProject({ projectDir: root, outDir }) };
 }
 
-export async function generateProductPlan({ projectDir, outDir = ".autotap", planPath = "" } = {}) {
+export async function generateProductPlan({ projectDir, outDir = ".tapp", planPath = "" } = {}) {
   const root = realProject(projectDir);
   const resolved = resolvePlan(root, outDir, planPath);
   const result = await generateApprovedContractProposals(resolved.plan, { projectDir: root });
@@ -344,7 +346,7 @@ export async function generateProductPlan({ projectDir, outDir = ".autotap", pla
 
 export async function validateProductPlan({
   projectDir,
-  outDir = ".autotap",
+  outDir = ".tapp",
   planPath = "",
   items = [],
   platform = "",
@@ -411,7 +413,7 @@ export async function validateProductPlan({
   return { operation: "validate-plan", platform: selectedPlatform, passed: results.every((item) => item.passed), results, plan, planPath: resolved.file, project: readProductProject({ projectDir: root, outDir }) };
 }
 
-export async function promoteProductPlan({ projectDir, outDir = ".autotap", planPath = "", items = [] } = {}) {
+export async function promoteProductPlan({ projectDir, outDir = ".tapp", planPath = "", items = [] } = {}) {
   const root = realProject(projectDir);
   const resolved = resolvePlan(root, outDir, planPath);
   const result = await promoteValidatedProposals(resolved.plan, { projectDir: root, ids: items || [] });
@@ -423,7 +425,7 @@ export async function promoteProductPlan({ projectDir, outDir = ".autotap", plan
   return { operation: "promote-plan", ...result, plan: written.plan, planPath: written.planPath, modelPath: written.modelPath, project: readProductProject({ projectDir: root, outDir }) };
 }
 
-export function prepareProductCi({ projectDir, outDir = ".autotap", modelPath = "", actionRef = DEFAULT_ACTION_REF, defaultBranch = "main" } = {}) {
+export function prepareProductCi({ projectDir, outDir = ".tapp", modelPath = "", actionRef = DEFAULT_ACTION_REF, defaultBranch = "main" } = {}) {
   const root = realProject(projectDir);
   const modelFile = modelPath ? path.resolve(root, modelPath) : artifactPaths(root, outDir).model;
   if (!inside(root, modelFile)) throw new Error("Application model must remain inside the repository");
@@ -433,7 +435,7 @@ export function prepareProductCi({ projectDir, outDir = ".autotap", modelPath =
   return { operation: "prepare-ci", ...rendered, project: readProductProject({ projectDir: root, outDir }) };
 }
 
-export function installProductCi({ projectDir, outDir = ".autotap", modelPath = "", actionRef = DEFAULT_ACTION_REF, defaultBranch = "main", workflowPath = ".github/workflows/tapp.yml", manifestPath = ".autotap/ci.json", replace = false, allowUnresolved = false } = {}) {
+export function installProductCi({ projectDir, outDir = ".tapp", modelPath = "", actionRef = DEFAULT_ACTION_REF, defaultBranch = "main", workflowPath = ".github/workflows/tapp.yml", manifestPath = ".tapp/ci.json", replace = false, allowUnresolved = false } = {}) {
   const root = realProject(projectDir);
   const rendered = prepareProductCi({ projectDir: root, outDir, modelPath, actionRef, defaultBranch });
   if (rendered.manifest.unresolved.length && !allowUnresolved) throw new Error(`CI installation is unresolved: ${rendered.manifest.unresolved.map((item) => `${item.platform}:${item.message}`).join("; ")}`);
@@ -443,7 +445,7 @@ export function installProductCi({ projectDir, outDir = ".autotap", modelPath =
 
 export async function runProductGate({
   projectDir,
-  outDir = ".autotap",
+  outDir = ".tapp",
   platform = "web",
   target = "",
   url = "",
@@ -501,7 +503,7 @@ export async function runProductGate({
     if (!inside(root, baselinePath) || !fs.existsSync(baselinePath)) throw new Error("Baseline must be an existing file inside the repository");
     args.push("--baseline", baselinePath);
   } else {
-    const targetBaseline = baselinePathForTarget(root, selected);
+    const targetBaseline = existingBaselinePathForTarget(root, selected);
     if (fs.existsSync(targetBaseline)) args.push("--baseline", targetBaseline);
   }
   onProgress({ phase: "gate", text: `Running ${selected.platform}:${selected.name} release gate` });
@@ -515,7 +517,7 @@ export async function runProductGate({
   return { operation: "run-gate", passed: execution.code === 0, code: execution.code, stdout: execution.stdout, stderr: execution.stderr, selectedTarget: selected, report, reportPath, markdownPath, runDir, project: readProductProject({ projectDir: root, outDir }) };
 }
 
-export function createProductBaseline({ projectDir, outDir = ".autotap", reportPath, platform = "web", target = "", replace = false, baselinePath = "" } = {}) {
+export function createProductBaseline({ projectDir, outDir = ".tapp", reportPath, platform = "web", target = "", replace = false, baselinePath = "" } = {}) {
   const root = realProject(projectDir);
   const project = readProductProject({ projectDir: root, outDir });
   const selected = selectApplicationTarget(project.model, { platform, target });