@aarwitz/tapp 0.15.1 → 0.16.0

package/mcp-server/src/application-model.js

@@ -8,6 +8,7 @@ import { credentialBindingsFromValue, readProjectConfig } from "./project-config
 import { applyReleaseContractCoverage, compileReleaseContract, loadReleaseContractFile, validateReleaseContractAgainstUiMap } from "./release-contract.js";
 import { applyTaskCoverage, loadTaskFile, validateTaskAgainstUiMap } from "./task-runtime.js";
 import { semanticUiKey } from "./ui-map.js";
+import { isProjectArtifactDirectory, projectArtifactDirectory } from "./project-paths.js";
 
 const SKIP = new Set([".git", ".build", ".gradle", ".next", ".swiftpm", "Pods", "Carthage", "DerivedData", "build", "dist", "node_modules", "vendor"]);
 
@@ -25,7 +26,7 @@ function walk(root, maxDepth = 4) {
     let entries;
     try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
     for (const entry of entries) {
-      if (SKIP.has(entry.name) || (entry.name.startsWith(".") && entry.name !== ".autotap")) continue;
+      if (SKIP.has(entry.name) || (entry.name.startsWith(".") && !isProjectArtifactDirectory(entry.name))) continue;
       const absolute = path.join(dir, entry.name);
       if (entry.isDirectory()) {
         directories.push(absolute);
@@ -124,7 +125,8 @@ function applyRuntimeTargetValidation(root, targets, validation) {
 }
 
 function persistedTargetValidations(root, outDir) {
-  const artifactDir = path.resolve(root, String(outDir || ".autotap"));
+  const requested = String(outDir || ".tapp");
+  const artifactDir = path.resolve(root, projectArtifactDirectory(root, requested));
   const relativeArtifactDir = path.relative(root, artifactDir);
   if (path.isAbsolute(relativeArtifactDir) || relativeArtifactDir === ".." || relativeArtifactDir.startsWith(`..${path.sep}`)) return [];
   const prior = readJson(path.join(artifactDir, "application-model.json"));
@@ -299,10 +301,11 @@ function uiMapTargetsTarget(map, target, targets) {
 }
 
 function loadTargetUiMaps(root, targets) {
-  const rootMap = loadUiMapAt(root, path.join(".autotap", "ui-map.json"));
+  const rootMap = loadUiMapAt(root, path.join(projectArtifactDirectory(root), "ui-map.json"));
   const records = targets.map((target) => {
     const scope = targetArtifactScope(target);
-    const expectedPath = posix(path.join(scope === "." ? "" : scope, ".autotap", "ui-map.json"));
+    const scopeRoot = path.join(root, scope === "." ? "" : scope);
+    const expectedPath = posix(path.join(scope === "." ? "" : scope, projectArtifactDirectory(scopeRoot), "ui-map.json"));
     let loaded = expectedPath === rootMap.summary.path ? rootMap : loadUiMapAt(root, expectedPath);
     if (!loaded.map && rootMap.map && (targets.length === 1 || uiMapTargetsTarget(rootMap.map, target, targets))) loaded = rootMap;
     return {
@@ -328,7 +331,7 @@ function loadTargetUiMaps(root, targets) {
   const prefixCoverage = unique.length > 1;
   const coverageValues = (field) => unique.flatMap((record) => (record.summary[field] || []).map((id) => prefixCoverage ? `${record.summary.targetId}:${id}` : id));
   const summary = {
-    path: unique.length === 1 ? unique[0].summary.path : ".autotap/ui-map.json",
+    path: unique.length === 1 ? unique[0].summary.path : ".tapp/ui-map.json",
     paths: unique.map((record) => record.summary.path).sort(),
     status: allObserved ? "observed" : someObserved ? "partial" : someInconclusive ? "inconclusive" : "missing",
     nodeCount: unique.reduce((total, record) => total + record.summary.nodeCount, 0),
@@ -348,14 +351,14 @@ function loadTargetUiMaps(root, targets) {
 
 function artifactScope(root, file) {
   const parts = relative(root, file).split("/");
-  const index = parts.indexOf(".autotap");
+  const index = parts.findIndex(isProjectArtifactDirectory);
   return index > 0 ? parts.slice(0, index).join("/") : ".";
 }
 
 function artifactFiles(root, inventory, kind, pattern) {
   return inventory.files.filter((file) => {
     const parts = relative(root, file).split("/");
-    const index = parts.indexOf(".autotap");
+    const index = parts.findIndex(isProjectArtifactDirectory);
     return index >= 0 && parts[index + 1] === kind && pattern.test(path.basename(file));
   }).sort();
 }
@@ -421,7 +424,7 @@ function applicationName(root, targets) {
   return pkg?.name || (targets.length === 1 ? targets[0].name : path.basename(root));
 }
 
-export async function inspectApplicationRepository({ projectDir, ownedUrl = "", platform = "", targetValidation = null, outDir = ".autotap" } = {}) {
+export async function inspectApplicationRepository({ projectDir, ownedUrl = "", platform = "", targetValidation = null, outDir = ".tapp" } = {}) {
   const root = fs.realpathSync(path.resolve(projectDir || process.cwd()));
   const inventory = walk(root);
   let targets = [
@@ -550,7 +553,7 @@ export async function inspectApplicationRepository({ projectDir, ownedUrl = "",
     requirements.push({
       id: targets.length <= 1 ? "ui-map" : `${target.id}:ui-map`, severity: "blocking", status: summary.status === "inconclusive" ? "inconclusive" : "missing",
       message: target ? (summary.status === "inconclusive" ? `The UI Map for ${target.name} is inconclusive.` : `No grounded UI Map exists for ${target.name}.`) : "No repository UI Map has been grounded in a real run.",
-      remediation: target ? `Build/launch ${target.name}, explore the real target, and retain its map at ${summary.expectedPath || summary.path}.` : "Build/launch the target and run tapp init --explore so real exploration evidence is merged into .autotap/ui-map.json.",
+      remediation: target ? `Build/launch ${target.name}, explore the real target, and retain its map at ${summary.expectedPath || summary.path}.` : "Build/launch the target and run tapp init --explore so real exploration evidence is merged into .tapp/ui-map.json.",
     });
   }
   if (!contracts.length) requirements.push({ id: "contracts", severity: "warning", status: "missing", message: "No reviewed release contracts exist yet.", remediation: "Review the proposed release plan, then generate and validate a compact set of contracts." });
@@ -925,7 +928,7 @@ function invalidateGeneratedTaskFiles(root, plan) {
   for (const record of plan.generation?.generatedTasks || []) {
     if (!record.path) continue;
     const absolute = path.resolve(root, record.path);
-    const proposalRoot = path.join(root, ".autotap", "proposals", "tasks");
+    const proposalRoot = path.join(root, projectArtifactDirectory(root), "proposals", "tasks");
     if (!isInsideRoot(proposalRoot, absolute) || !fs.existsSync(absolute)) continue;
     const task = readJson(absolute);
     if (!task || task.generation?.origin !== "deterministic-ui-map") continue;
@@ -937,8 +940,8 @@ function invalidateGeneratedTaskFiles(root, plan) {
   }
 }
 
-export function writeInitArtifacts({ root, model, plan, outDir = ".autotap", refresh = false, invalidateValidation = false } = {}) {
-  const directory = path.resolve(root, outDir);
+export function writeInitArtifacts({ root, model, plan, outDir = ".tapp", refresh = false, invalidateValidation = false } = {}) {
+  const directory = path.resolve(root, projectArtifactDirectory(root, outDir));
   const modelPath = path.join(directory, "application-model.json");
   const planPath = path.join(directory, "release-plan.json");
   if (!refresh && (fs.existsSync(modelPath) || fs.existsSync(planPath))) throw new Error(`Init artifacts already exist under ${relative(root, directory)}; inspect them or rerun with --refresh to preserve reviewed decisions while updating evidence`);
@@ -1069,7 +1072,7 @@ function generatedTaskName(node, entryOnly, occupied, identity) {
   return `${base}${crypto.createHash("sha256").update(identity).digest("hex").slice(0, 6)}`;
 }
 
-function prepareMapBackedItem(item, map, existingTasks, taskDrafts, { targetId = "", mapPath = ".autotap/ui-map.json" } = {}) {
+function prepareMapBackedItem(item, map, existingTasks, taskDrafts, { targetId = "", mapPath = ".tapp/ui-map.json" } = {}) {
   const ground = (item.groundedBy || []).find((entry) => entry.type === "ui-map-node");
   if (!ground) throw new Error("Approved UI-only proposal is not grounded by a UI Map node");
   const nodes = new Map((map.nodes || []).map((node) => [node.id, node]));
@@ -1168,7 +1171,7 @@ function writeGeneratedTaskDrafts(root, taskDrafts) {
   for (const draft of [...taskDrafts.values()].sort((a, b) => a.name.localeCompare(b.name))) {
     const scopeRoot = path.resolve(root, draft.scope === "." || !draft.scope ? "" : draft.scope);
     if (!isInsideRoot(root, scopeRoot)) throw new Error(`Generated Task scope escapes repository: ${draft.scope}`);
-    const output = path.join(scopeRoot, ".autotap", "proposals", "tasks", `${kebab(draft.name)}.task.json`);
+    const output = path.join(scopeRoot, projectArtifactDirectory(scopeRoot), "proposals", "tasks", `${kebab(draft.name)}.task.json`);
     const definition = {
       kind: "task", version: 1, name: draft.name, description: draft.description,
       ...(Object.keys(draft.inputs || {}).length ? { inputs: draft.inputs } : {}),
@@ -1189,7 +1192,7 @@ function writeGeneratedTaskDrafts(root, taskDrafts) {
     }
     try {
       const task = loadTaskFile(output);
-      const mapPath = path.resolve(root, draft.mapPath || ".autotap/ui-map.json");
+      const mapPath = path.resolve(root, draft.mapPath || ".tapp/ui-map.json");
       if (!isInsideRoot(root, mapPath)) throw new Error(`Generated Task UI Map escapes repository: ${draft.mapPath}`);
       const map = readJson(mapPath);
       if (!map || map.schemaVersion !== 1) throw new Error(`Generated Task UI Map is missing or invalid: ${draft.mapPath}`);
@@ -1304,7 +1307,7 @@ export async function generateApprovedContractProposals(plan, { projectDir } = {
     let prepared = item;
     if (item.origin === "deterministic-ui-map-proposal") {
       const grounding = (item.groundedBy || []).find((entry) => entry.type === "ui-map-node");
-      const mapPath = grounding?.mapPath || ".autotap/ui-map.json";
+      const mapPath = grounding?.mapPath || ".tapp/ui-map.json";
       const absoluteMapPath = path.resolve(root, mapPath);
       const itemMap = isInsideRoot(root, absoluteMapPath) ? readJson(absoluteMapPath) : null;
       if (!itemMap || itemMap.schemaVersion !== 1) {
@@ -1329,7 +1332,7 @@ export async function generateApprovedContractProposals(plan, { projectDir } = {
     if (!prepared) continue;
     const scopeRoot = path.resolve(root, item.scope === "." || !item.scope ? "" : item.scope);
     if (scopeRoot !== root && !scopeRoot.startsWith(root + path.sep)) throw new Error(`Plan scope escapes repository: ${item.scope}`);
-    const output = path.join(scopeRoot, ".autotap", "proposals", "contracts", `${kebab(item.name)}.contract.ts`);
+    const output = path.join(scopeRoot, projectArtifactDirectory(scopeRoot), "proposals", "contracts", `${kebab(item.name)}.contract.ts`);
     const source = draftContractSource(prepared, projectConfiguration.config || {});
     if (fs.existsSync(output) && fs.readFileSync(output, "utf8") !== source) throw new Error(`Draft contract already exists with different content and was not overwritten: ${relative(root, output)}`);
     const created = !fs.existsSync(output);
@@ -1412,13 +1415,13 @@ export function recordContractProposalValidation(plan, { id = "", name = "", pla
 export function recordGeneratedTaskProposalValidation({ projectDir, item, platform, evidence = "", detail = "" } = {}) {
   if (!["ios", "android", "web"].includes(platform)) throw new Error("platform must be ios|android|web");
   const root = fs.realpathSync(path.resolve(projectDir || process.cwd()));
-  const proposalMarker = `${path.sep}.autotap${path.sep}proposals${path.sep}tasks${path.sep}`;
-  const reviewedMarker = `${path.sep}.autotap${path.sep}tasks${path.sep}`;
+  const proposalMarkers = [".tapp", ".autotap"].map((directory) => `${path.sep}${directory}${path.sep}proposals${path.sep}tasks${path.sep}`);
+  const reviewedMarkers = [".tapp", ".autotap"].map((directory) => `${path.sep}${directory}${path.sep}tasks${path.sep}`);
   const updated = [];
   for (const taskPath of item?.generation?.taskPaths || []) {
     const absolute = path.resolve(root, taskPath);
-    const proposed = isInsideRoot(root, absolute) && absolute.includes(proposalMarker);
-    const reviewed = isInsideRoot(root, absolute) && absolute.includes(reviewedMarker) && !absolute.includes(proposalMarker);
+    const proposed = isInsideRoot(root, absolute) && proposalMarkers.some((marker) => absolute.includes(marker));
+    const reviewed = isInsideRoot(root, absolute) && reviewedMarkers.some((marker) => absolute.includes(marker)) && !proposed;
     if ((!proposed && !reviewed) || !fs.existsSync(absolute)) throw new Error(`Generated Task is missing or outside Tapp Task directories: ${taskPath}`);
     const task = readJson(absolute);
     if (!task || task.kind !== "task" || task.generation?.origin !== "deterministic-ui-map") throw new Error(`Generated Task draft has invalid provenance: ${taskPath}`);
@@ -1458,10 +1461,13 @@ export function mergeGeneratedTaskProposalValidation(plan, updates = []) {
 }
 
 function promotedDestination(root, source, kind) {
-  const marker = `${path.sep}.autotap${path.sep}proposals${path.sep}${kind}${path.sep}`;
+  const marker = [".tapp", ".autotap"]
+    .map((directory) => `${path.sep}${directory}${path.sep}proposals${path.sep}${kind}${path.sep}`)
+    .find((candidate) => source.includes(candidate));
+  if (!marker) throw new Error(`Proposal ${kind.slice(0, -1)} is outside .tapp/proposals/${kind}: ${relative(root, source)}`);
   const index = source.indexOf(marker);
-  if (index < 0) throw new Error(`Proposal ${kind.slice(0, -1)} is outside .autotap/proposals/${kind}: ${relative(root, source)}`);
-  const destination = `${source.slice(0, index)}${path.sep}.autotap${path.sep}${kind}${path.sep}${source.slice(index + marker.length)}`;
+  const directory = marker.split(path.sep).filter(Boolean)[0];
+  const destination = `${source.slice(0, index)}${path.sep}${directory}${path.sep}${kind}${path.sep}${source.slice(index + marker.length)}`;
   if (!isInsideRoot(root, destination)) throw new Error(`Promotion destination escapes repository: ${destination}`);
   return destination;
 }
@@ -1480,7 +1486,7 @@ export async function promoteValidatedProposals(plan, { projectDir, ids = [] } =
 
   const mapCache = new Map();
   const mapForItem = (item) => {
-    const relativeMapPath = item.generation?.mapPath || (item.groundedBy || []).find((entry) => entry.type === "ui-map-node")?.mapPath || ".autotap/ui-map.json";
+    const relativeMapPath = item.generation?.mapPath || (item.groundedBy || []).find((entry) => entry.type === "ui-map-node")?.mapPath || ".tapp/ui-map.json";
     const absolute = path.resolve(root, relativeMapPath);
     if (!isInsideRoot(root, absolute)) throw new Error(`UI Map for '${item.name}' escapes the repository: ${relativeMapPath}`);
     if (!mapCache.has(absolute)) {
@@ -1499,7 +1505,7 @@ export async function promoteValidatedProposals(plan, { projectDir, ids = [] } =
     for (const taskPath of item.generation.taskPaths || []) {
       const source = path.resolve(root, taskPath);
       if (!fs.existsSync(source)) throw new Error(`Generated Task is missing: ${taskPath}`);
-      if (!String(source).includes(`${path.sep}.autotap${path.sep}proposals${path.sep}tasks${path.sep}`)) continue;
+      if (![".tapp", ".autotap"].some((directory) => String(source).includes(`${path.sep}${directory}${path.sep}proposals${path.sep}tasks${path.sep}`))) continue;
       const destination = promotedDestination(root, source, "tasks");
       moves.set(source, destination);
       let task = taskRecords.get(source);

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;