@skyramp/mcp 0.4.4 → 0.5.0-rc.10

package/build/playwright/registerPlaywrightTools.js

@@ -8,7 +8,11 @@ import { PlaywrightTraceService, } from "./PlaywrightTraceService.js";
 import { blueprintJsonSpan } from "./blueprintDigest.js";
 import { recordBlueprintCapture, recordBrowserNavigation, } from "./blueprintDigestStore.js";
 import { recordTraceExport } from "./traceExportStore.js";
+import { ESSENTIAL_TOOLS } from "./essentialTools.js";
+import { isOffLimitsUrl } from "./dataSafetyConfig.js";
+import { safeResolveDataSafety } from "./safeResolveDataSafety.js";
 let _service = null;
+let _dataSafety = null;
 export function getPlaywrightTraceService() {
     return _service;
 }
@@ -156,6 +160,78 @@ function shrinkBlueprintText(text) {
         return text;
     }
 }
+/** Courtesy pre-check so the agent gets an immediate, readable refusal
+ *  instead of a page-level network error. The fork's network layer remains
+ *  the hard guarantee — this is UX, not enforcement — so a throw from the
+ *  matcher (e.g. the vendored fork's require() resolving a partial install)
+ *  must degrade to "not off-limits" rather than block navigation outright. */
+export function precheckNavigate(url, config) {
+    let offLimits;
+    try {
+        offLimits = isOffLimitsUrl(url, config);
+    }
+    catch (error) {
+        logger.warning("offLimits matcher threw during the navigate pre-check — proceeding as not off-limits", { error });
+        return null;
+    }
+    if (!offLimits)
+        return null;
+    return (`### Blocked by data safety\n` +
+        `Navigation to ${url} is off-limits (matches a configured offLimits pattern). ` +
+        `Do not retry this URL; plan the flow using permitted surfaces.`);
+}
+/**
+ * Pure regression guard for the per-call browser_navigate pre-check: the
+ * `tool.name === "browser_navigate" && config` gate, the params.url
+ * extraction, and the isError result shape, all extracted out of the tool
+ * handler closure so they can be exercised directly under Jest without a
+ * real McpServer/PlaywrightTraceService. The registration call site becomes
+ * `const refusal = maybeRefuseNavigate(...); if (refusal) return refusal;`.
+ * Returns undefined for every "let the call through" case: wrong tool, no
+ * url param, or no config (data safety not configured for this run).
+ */
+export function maybeRefuseNavigate(toolName, params, config) {
+    if (toolName !== "browser_navigate" || !config)
+        return undefined;
+    const url = params?.url;
+    if (url === undefined)
+        return undefined;
+    const refusal = precheckNavigate(String(url), config);
+    if (!refusal)
+        return undefined;
+    return { content: [{ type: "text", text: refusal }], isError: true };
+}
+/**
+ * Resolves the data-safety pre-check config for `registerPlaywrightTools`
+ * and normalizes an inert result (mode "off" with
+ * no offLimits) to `null`. MUST go through `safeResolveDataSafety` — this
+ * runs after `_service.initialize()` has already succeeded, so an unguarded
+ * rejection here (e.g. the vendored fork's `require()` resolving a partial
+ * install) would abort registration of all 23 Playwright browser tools, not
+ * just the advisory pre-check. The inner try/catch is defense in depth in
+ * case `safeResolveDataSafety` itself ever regresses its no-throw contract —
+ * either way, an undefined/failed resolution degrades to "pre-check inert"
+ * (`null`), never a thrown error.
+ *
+ * Exported (rather than inlined) so it can be exercised directly under Jest
+ * without driving the McpServer-dependent registration flow — see
+ * `registerPlaywrightTools.dataSafety.test.ts`.
+ */
+export async function resolveDataSafetyForRegistration(cwd) {
+    let resolved;
+    try {
+        resolved = await safeResolveDataSafety(cwd);
+    }
+    catch (error) {
+        logger.error("Failed to resolve data-safety config for the navigate pre-check — proceeding without it", { error });
+        return null;
+    }
+    if (!resolved)
+        return null;
+    return resolved.mode === "off" && resolved.offLimits.length === 0
+        ? null
+        : resolved;
+}
 export async function registerPlaywrightTools(server, options) {
     _service = new PlaywrightTraceService(options);
     try {
@@ -167,51 +243,16 @@ export async function registerPlaywrightTools(server, options) {
         _service = null;
         return;
     }
+    // This pre-check config is scoped to the whole running server process
+    // (module-level `_dataSafety`, set once here, read by every browser_navigate
+    // call — see maybeRefuseNavigate below), not to any one caller's request.
+    // Registration happens once at startup with no per-call `repositoryPath`, so
+    // process.cwd() is the only path to resolve from. When SKYRAMP_DATA_SAFETY is
+    // set (the testbot lane) the workspace file is not read: the env value wins,
+    // as it does in the fork's own parseDataSafetyConfig.
+    _dataSafety = await resolveDataSafetyForRegistration(process.cwd());
     const tools = _service.getTools();
     logger.info(`Registering ${tools.length} Playwright browser tools`);
-    // Only expose essential browser tools to reduce LLM confusion.
-    // The full set (23 tools) overwhelms the LLM and causes it to use
-    // browser_evaluate/browser_run_code instead of the simpler tools.
-    //
-    // browser_blueprint is the only DOM Analyzer tool registered — it handles
-    // both full captures and same-URL deltas via the URL-cache (isFullCapture).
-    // browser_blueprint_diff, browser_sitemap_build, browser_sitemap_query fire
-    // 0 times in production evals and have no active call path in the testbot prompt.
-    //
-    // browser_widget_contract_lookup / browser_widget_contract_cache are
-    // intentionally excluded: the curated fingerprint library only covers
-    // test fixtures (not production widgets), and the LLM can handle custom
-    // widgets via snapshot-driven trial-and-error without the tool.
-    // The widgetType field on blueprint elements still signals "custom" to
-    // the agent — no guidance is lost.
-    const ESSENTIAL_TOOLS = new Set([
-        "browser_navigate",
-        "browser_snapshot",
-        "browser_click",
-        "browser_type",
-        "browser_press_key",
-        "browser_select_option",
-        "browser_hover",
-        "browser_drag",
-        "browser_file_upload",
-        "browser_evaluate",
-        "browser_tabs",
-        "browser_navigate_back",
-        "browser_wait_for",
-        "browser_take_screenshot",
-        "browser_assert",
-        "browser_assert_hidden",
-        "browser_assert_api_request",
-        "browser_assert_table_cell",
-        "browser_mouse_action",
-        "browser_visual_snapshot",
-        "browser_gojs_add_node",
-        "browser_gojs_link",
-        "skyramp_export_zip",
-        "skyramp_load_trace",
-        // DOM Analyzer: blueprint capture (capture-act-capture pattern)
-        "browser_blueprint",
-    ]);
     const filteredTools = tools.filter((t) => ESSENTIAL_TOOLS.has(t.name));
     logger.info(`Filtering to ${filteredTools.length} essential tools (from ${tools.length} total)`);
     for (const tool of filteredTools) {
@@ -233,6 +274,9 @@ export async function registerPlaywrightTools(server, options) {
                     isError: true,
                 };
             }
+            const refusal = maybeRefuseNavigate(tool.name, params, _dataSafety ?? undefined);
+            if (refusal)
+                return refusal;
             const result = await _service.callTool(tool.name, params);
             // Counted BEFORE any early return and REGARDLESS of isError: an export
             // that failed still cost the agent a recording, and the report gate that

package/build/playwright/safeResolveDataSafety.d.ts

@@ -0,0 +1,24 @@
+/**
+ * `effectiveDataSafetyConfig` does a synchronous
+ * `require("playwright/lib/mcp/skyramp")` with no guard against that module
+ * resolution failing (partial install, vendored-tarball mismatch, monorepo
+ * hoisting difference) — an unhandled rejection here would propagate straight
+ * out of any async caller that doesn't expect it. Fail OPEN here (and only
+ * here): the `browser_navigate` pre-check is advisory UX — real enforcement
+ * lives in the fork's network layer — so a broken resolution must degrade to
+ * "no pre-check" rather than break server startup,
+ * mirroring the `readWorkspaceConfigRaw` convention for workspace-file reads
+ * (src/utils/workspaceAuth.ts).
+ *
+ * Kept in its own module (not inlined into dataSafetyConfig.ts) so it can
+ * import `effectiveDataSafetyConfig` across a real module boundary — that's
+ * what lets tests substitute a rejecting implementation. Under this
+ * project's native-ESM Jest setup, an imported module's namespace is
+ * read-only, so a same-module call cannot be swapped out from a test the
+ * way a cross-module import can (see src/utils/uiPageEnumerator.test.ts).
+ *
+ * Its only caller is `resolveDataSafetyForRegistration`
+ * (registerPlaywrightTools.ts), which builds the navigate pre-check.
+ */
+import { type DataSafetyConfig } from "./dataSafetyConfig.js";
+export declare function safeResolveDataSafety(cwd: string): Promise<DataSafetyConfig | undefined>;

package/build/playwright/safeResolveDataSafety.js

@@ -0,0 +1,33 @@
+/**
+ * `effectiveDataSafetyConfig` does a synchronous
+ * `require("playwright/lib/mcp/skyramp")` with no guard against that module
+ * resolution failing (partial install, vendored-tarball mismatch, monorepo
+ * hoisting difference) — an unhandled rejection here would propagate straight
+ * out of any async caller that doesn't expect it. Fail OPEN here (and only
+ * here): the `browser_navigate` pre-check is advisory UX — real enforcement
+ * lives in the fork's network layer — so a broken resolution must degrade to
+ * "no pre-check" rather than break server startup,
+ * mirroring the `readWorkspaceConfigRaw` convention for workspace-file reads
+ * (src/utils/workspaceAuth.ts).
+ *
+ * Kept in its own module (not inlined into dataSafetyConfig.ts) so it can
+ * import `effectiveDataSafetyConfig` across a real module boundary — that's
+ * what lets tests substitute a rejecting implementation. Under this
+ * project's native-ESM Jest setup, an imported module's namespace is
+ * read-only, so a same-module call cannot be swapped out from a test the
+ * way a cross-module import can (see src/utils/uiPageEnumerator.test.ts).
+ *
+ * Its only caller is `resolveDataSafetyForRegistration`
+ * (registerPlaywrightTools.ts), which builds the navigate pre-check.
+ */
+import { logger } from "../utils/logger.js";
+import { effectiveDataSafetyConfig, } from "./dataSafetyConfig.js";
+export async function safeResolveDataSafety(cwd) {
+    try {
+        return await effectiveDataSafetyConfig(cwd);
+    }
+    catch (error) {
+        logger.error("Data-safety resolution failed — proceeding without data-safety context", { error });
+        return undefined;
+    }
+}

package/build/prompts/initialize-workspace/initializeWorkspacePrompt.d.ts

@@ -1 +1,18 @@
 export declare const INIT_WORKSPACE_INSTRUCTIONS: string;
+/** A repository of the Target other than the workspace's own, scanned into the same workspace.yml. */
+export interface ScanRelatedRepository {
+    /** owner/repo (org/project/repo on Azure DevOps), set verbatim as each of its services' `repository`. */
+    repository: string;
+    repositoryPath: string;
+}
+/**
+ * The scan instructions for one workspace. With related repositories, every
+ * repository is scanned into the one workspace.yml at `workspacePath`, each
+ * related repository's services carrying its `repository`. With a test
+ * repository, testDirectory is read from, and relative to, that checkout.
+ */
+export declare function buildInitWorkspaceInstructions(target: {
+    workspacePath: string;
+    relatedRepositories?: ScanRelatedRepository[];
+    testRepositoryPath?: string;
+}): string;

package/build/prompts/initialize-workspace/initializeWorkspacePrompt.js

@@ -1,178 +1,47 @@
 import { getPersonaPrefix } from "../personas.js";
-import { AUTH_TYPES_PROMPT_LIST } from "../../utils/workspaceAuth.js";
-export const INIT_WORKSPACE_INSTRUCTIONS = `${getPersonaPrefix()}Your task is to scan this repository, discover ALL services, and call the skyramp_init_workspace tool with the discovered services array and the scanToken.
-
-After scanning the workspace, before calling the skyramp_init_workspace tool, you MUST:
-1. Output a <thinking> block to justify the reasoning behind each field mapping for every discovered service. Follow the scanning sections first, then field definitions, then verification.
-2. Then output a Discovery Summary with the exact services array you will pass to the tool:
-\`\`\`json
-[
-  {
-    "serviceName": "<name>",
-    "language": "<language>",
-    "framework": "<framework>",
-    "testDirectory": "<path>",
-    "api": { "schemaPath": "<path-or-url>", "baseUrl": "<url>", "authType": "<type>", "authHeader": "<header>" },
-    "runtimeDetails": { "runtime": "<runtime>", "serverStartCommand": "<command>", "serverStopCommand": "<docker stop command>", "dockerNetwork": "<network>" }
-  }
-]
-\`\`\`
-
-### List all top-level directories
-<list_directories>
-Run a directory listing of the workspace root. Every top-level directory is a potential service. Common layouts:
-| Layout | Example dirs | Expect |
-|--------|-------------|--------|
-| Monorepo | apps/web, apps/api, packages/shared | 1 service per app |
-| Microservices | services/auth, services/orders | 1 service per service dir |
-| Single service | src/, lib/ | 1 service (the root) |
-
-If the repo is a monorepo, check for workspace manifests BEFORE scanning individual directories:
-1. JavaScript/TypeScript monorepos:
-   - If pnpm-workspace.yaml exists, read the packages array to find all package directories (for example, ["apps/*", "packages/*"]).
-   - If turbo.json exists, read the root package.json workspaces field to enumerate all packages.
-   - If lerna.json exists, read the packages array in lerna.json (for example, ["packages/*"]).
-   - If the root package.json has a "workspaces" field, use the glob patterns to identify all packages.
-   - If nx.json exists, scan the projects in nx.json or project.json files in subdirectories.
-2. Java monorepos:
-   - If a parent pom.xml has a <modules> section, each listed module is a separate service (Maven multi-module project).
-   - If settings.gradle or settings.gradle.kts has include statements, each included project is a separate service (Gradle multi-project).
-3. Python monorepos:
-   - If a pyproject.toml has a [tool.poetry.packages] or [tool.setuptools.packages] section with multiple paths, each is a potential service.
-   - If multiple directories each contain their own pyproject.toml or requirements.txt, treat each as an independent service.
-When any of these exist, use the workspace manifest to enumerate ALL packages and apps. Each package with its own server entry point, API routes, or UI framework is a separate service. Do NOT skip frontend packages. A Next.js app, React SPA, or Vue app in the monorepo is a service.
-</list_directories>
-
-### Inspect every candidate directory
-<inspect_directories>
-For each top-level directory, check for service indicator files.
-
-Language indicators (presence of any means an independent service):
-1. package.json indicates typescript or javascript
-2. requirements.txt, pyproject.toml, or Pipfile indicates python
-3. pom.xml or build.gradle indicates java
-
-Test framework (look inside the service directory):
-1. playwright.config.* indicates playwright
-2. pytest.ini, conftest.py, or pyproject.toml [tool.pytest] indicates pytest
-3. junit in pom.xml indicates junit
-
-API schemas (look inside the service directory and check known framework defaults):
-1. openapi.json/yaml or swagger.json/yaml provides the schema file path
-2. FastAPI projects serve the schema at http://localhost:{port}/openapi.json
-3. Express with swagger-ui serves at http://localhost:{port}/api-docs
-4. Spring Boot serves at http://localhost:{port}/v3/api-docs
-</inspect_directories>
-
-### Check root-level runtime config
-<runtime_config>
-Inspect the repo root (and subdirectories like .devcontainer/) for shared runtime configuration:
-1. CLAUDE.md or AGENTS.md: if either file exists at the repo root, check it for dev/test/CI setup instructions including how to start services, required environment variables, and runtime configuration.
-2. Docker Compose files: scan for ALL compose files including docker-compose.yml, docker-compose.yaml, docker-compose.*.yml (such as docker-compose.testbot.yml or docker-compose.dev.yml), compose.yml, and compose.*.yaml in the repo root and subdirectories. Distinguish between application compose files and infrastructure-only compose files. Infrastructure compose files contain only supporting services like databases, Redis, Minio, mail servers, or message queues and do NOT run the application itself. Application compose files contain the actual application services that build from the repo source code (look for "build:" directives pointing to the repo, or services that map to discovered application directories). Only use application compose files for determining runtime, serverStartCommand, and serverStopCommand. When a non-default compose file is found, the serverStartCommand and serverStopCommand must reference it explicitly (such as "docker compose -f docker-compose.testbot.yml up -d --build <service-name>" and "docker compose -f docker-compose.testbot.yml stop <service-name>"). Docker Compose ALWAYS prefixes the network name with the project name. If compose has "networks: { my-net: ... }", the actual network name is "<project-name>_my-net". If there is no explicit networks section, the default network is "<project-name>_default". The project name is the basename of the working directory where docker compose runs.
-3. Makefile: extract start and dev targets.
-4. Root package.json scripts: extract workspace-level commands.
-</runtime_config>
-
-### Build the complete services array
-<build_services>
-Create one service entry per deployable unit. You MUST include every backend/API service (Python, Java, Go, Node.js) and every frontend service (React, Vue, Angular, Next.js). Set runtime fields from docker-compose.yml if present.
-</build_services>
-
-### Basic fields
-<basic_fields>
-1. serviceName (required): A unique identifier for the service. Use the format <repoName>-<serviceDirName>-<frontend or backend> for consistency. For example: directus-api-backend, directus-app-frontend. If the directory name already ends with "backend" or "frontend", do not duplicate the suffix (use "demoshop-fullstack-backend" not "demoshop-fullstack-backend-backend"). For single-service repos where the service directory is the root, omit the directory portion such as onlineBoutique-frontend.
-2. language (required): One of python, typescript, javascript, or java. Detect from package.json (typescript or javascript), requirements.txt or pyproject.toml (python), or pom.xml or build.gradle (java).
-3. framework (required): One of playwright, pytest, robot, or junit. Detect from pytest.ini, playwright.config, jest.config, or junit in pom.xml. The framework MUST match the language: python uses pytest or robot, typescript or javascript uses playwright, and java uses junit.
-4. testDirectory (required): A stable path relative to the repo root where generated tests for this service will be placed. For each service, use the test directory configured by that service's test framework when one is discoverable:
-   - Playwright: Read playwright.config.ts (or .js/.mjs) and extract the testDir value.
-   - pytest: Read pytest.ini, pyproject.toml [tool.pytest.ini_options], or setup.cfg [tool:pytest] for testpaths.
-   - JUnit: Usually src/test/java. Check pom.xml or build.gradle for custom test source directories.
-   If no framework-configured test directory is available, use the Skyramp deterministic fallback:
-   - Single service: set testDirectory to tests/skyramp.
-   - Multiple services or monorepos: set testDirectory to tests/skyramp/<serviceDirName>, where <serviceDirName> is the service directory name with path separators and whitespace replaced by hyphens.
-   Framework config takes precedence. Use the Skyramp deterministic fallback only when no framework-configured test directory is available.
-   NEVER set testDirectory to \`.skyramp\`, to any path inside it, or to \`.\` or the repo root, whatever the framework config or existing test files say. \`.skyramp\` is the executor's own working area: it holds the run videos and executor artefacts. skyramp_init_workspace rejects all of these, and the generation tools refuse to write there.
-</basic_fields>
-
-### API fields
-<api_fields>
-1. api.schemaPath: Path or URL to an OpenAPI or Swagger schema. Search for openapi.json, openapi.yaml, swagger.json, or swagger.yaml files. Framework defaults are: FastAPI serves /openapi.json, Express serves /api-docs, and Spring serves /v3/api-docs. For locally-run services, use a localhost URL. For cloud or externally hosted services (such as Salesforce, Vercel, or Cloudflare), use the actual deployment URL found in config or documentation.
-2. api.baseUrl (required): The base URL where the service is reachable, such as "http://localhost:3000" or "https://api.example.com". Derive from docker-compose ports, app config, README, or environment variables. Use localhost for services run locally and the actual deployment URL for cloud or externally hosted services. NEVER fabricate a URL. Only use URLs found in config files, README, or environment variables.
-   Include the API path prefix (e.g. \`/api\`, \`/api/v1\`, \`/v1\`) when one applies — not just \`host:port\`. A bare host means every test request hits the root and 404s. Derive the prefix from the strongest available signal: OpenAPI \`servers[].url\` or \`basePath\`; the app's routing config (FastAPI \`root_path\`, Express \`app.use('/api/v1', ...)\`, Rails routes prefix, Django \`urlpatterns\` mount); or the longest common leading path across the existing test suite's endpoints. If none of those yield a prefix, leave it bare AND flag it in your summary so the user can review.
-3. api.authType (required): The authentication type. Valid values are: ${AUTH_TYPES_PROMPT_LIST}
-   Detect by checking in the following order (language-agnostic, apply whichever signals match):
-   a. Dependencies and packages (package.json, requirements.txt, go.mod, Gemfile, composer.json, pom.xml, build.gradle):
-      - jsonwebtoken, passport-jwt, @nestjs/jwt, jose, fastapi[security], PyJWT, python-jose, github.com/golang-jwt/jwt, jjwt, or spring-security-oauth2 indicates bearer. Spring exception: if spring-security is present but the security config uses HttpSecurity.formLogin() or sessionManagement() without a JwtDecoder bean, the actual auth is session cookies so use cookie. Check the SecurityConfig or WebSecurityConfigurerAdapter class before assigning bearer to any Spring service.
-      - passport-http or Spring basic auth indicates basic.
-      - passport-oauth2, openid-client, doorkeeper, keycloak-connect, spring-security-oauth2-resource-server, or github.com/coreos/go-oidc indicates oauth.
-      - rest_framework with TokenAuthentication or djangorestframework-simplejwt (Token scheme) indicates token.
-      - express-session, cookie-session, iron-session, next-auth, gorilla/sessions, or laravel/session indicates cookie.
-      - laravel/sanctum or laravel/passport on API routes indicates bearer; on frontend web routes indicates cookie.
-   b. Environment variables (.env, docker-compose, README):
-      - JWT_SECRET, ACCESS_TOKEN_SECRET, FIREBASE_SECRET, or SUPABASE_JWT_SECRET indicates bearer.
-      - API_KEY, X_API_KEY, ADMIN_KEY, or SERVICE_KEY (used as header value, not JWT signing) indicates apiKey.
-      - CLIENT_ID paired with CLIENT_SECRET, OAUTH_CLIENT_*, or OIDC_* indicates oauth.
-      - SESSION_SECRET, COOKIE_SECRET, or NEXTAUTH_SECRET indicates cookie.
-   c. Source code and middleware patterns (auth, middleware, or security config files):
-      - Node/Express: req.headers.authorization split "Bearer" indicates bearer. "Authorization: Token" indicates token. Custom header check indicates apiKey. Session or cookie middleware indicates cookie.
-      - FastAPI/Starlette: HTTPBearer, OAuth2PasswordBearer, or Depends(get_current_user) indicates bearer. SessionMiddleware indicates cookie.
-      - Django/DRF: TokenAuthentication indicates token. JWTAuthentication indicates bearer. SessionAuthentication indicates cookie.
-      - Spring: JwtDecoder or JwtAuthenticationFilter indicates bearer. HttpSecurity.formLogin() with sessions indicates cookie.
-      - Go: ParseWithClaims or GetHeader("Authorization") indicates bearer. gorilla/sessions indicates cookie.
-      - Rails: authenticate_or_request_with_http_token indicates bearer. before_action :authenticate_user! (Devise) indicates cookie.
-      - Laravel: auth:sanctum on API indicates bearer. middleware("auth") on web indicates cookie.
-      - Rust/Axum: Authorization<Bearer> extraction indicates bearer.
-   d. Query-parameter auth: Some APIs pass credentials as a URL query param rather than a header (such as ?key=<key>, ?api_key=<key>, or ?access_token=<token>). Signals include source code reading credentials from req.query.key, request.query_params["api_key"], or @RequestParam("token"), and API docs or README showing auth examples like /endpoint?key=<your-key>.
-   e. Fallback: For frontend or UI services, use none. For backend APIs with no header-based auth signals, use bearer.
-4. api.authHeader: The exact HTTP header name carrying the credential.
-   - For bearer, basic, oauth, or token: always "Authorization" (inferred automatically, so you may omit it).
-   - For cookie or session: always "Cookie" (also inferred automatically).
-   - For apiKey: this is required. Set to the actual custom header name such as "X-API-Key" or "X-Admin-Key".
-   - For none: set authHeader to "".
-5. api.authScheme: The Authorization header prefix (the word before the token). Standard types derive this automatically: bearer uses "Bearer", token uses "Token", and basic uses "Basic". Set explicitly only for custom or non-standard schemes (for example, Hawk uses "Hawk" and Digest uses "Digest"). Omit for cookie, session, or apiKey since they do not use the Authorization header.
-</api_fields>
-
-### Runtime fields
-<runtime_fields>
-1. runtimeDetails.runtime (required): One of local, docker, or k8s. Detect per service:
-   - If the service is listed in an application docker compose file (one that builds or runs the application, not infrastructure-only files containing only databases, caches, or queues) or has a Dockerfile as its intended run method, use "docker".
-   - If k8s manifests exist (charts/, k8s/, deploy/) AND the service is intended to run in K8s for local development, use "k8s".
-   - If the service has no Docker or k8s configuration and is run directly via a language runtime (npm, python, java, etc.), use "local".
-   A repo may have MIXED runtimes. A backend in docker-compose.yml uses "docker" while a frontend run with pnpm or npm locally uses "local". Include ALL services regardless of runtime.
-   If the frontend is bundled inside the API Docker container (no separate frontend service in the compose file), both frontend and backend services should use runtime "docker", share the same baseUrl (the container's exposed URL), and use the same serverStartCommand since they run in the same container.
-   IMPORTANT — proxy parameters are NOT runtime indicators: If proxyKubeconfig, proxyNamespace, or proxyUrl appear in the conversation context, they are for a Skyramp proxy worker that collects traffic samples for mock generation. They do NOT indicate the repo's runtime. Do not use proxy K8s params to set runtime, k8sNamespace, or k8sContext. Determine the runtime solely from the repo's own files (docker-compose.yml, Dockerfile, k8s manifests that are part of the repo's own local dev workflow). Note that many repos have K8s deployment manifests for staging/production but use Docker Compose for local development — check which setup the repo actually uses for local dev.
-2. runtimeDetails.serverStartCommand: The command to start or deploy the service. It MUST match the runtime:
-   - For "docker" runtime: Use a Docker command that rebuilds application services from the working tree before starting them, such as "docker compose up -d --build <service-name>" for the default docker-compose.yml, or "docker compose -f <compose-file> up -d --build <service-name>" when using a non-default compose file. This is always derivable from the application docker compose file and service name. If the compose service has no build context and only references an image, note that the command cannot rebuild local code.
-   - For "k8s" runtime: Use a deploy command such as "kubectl apply -f deploy/", "helm install myrelease .", or "skaffold run". This is always derivable from the manifests or charts present in the repo.
-   - For "local" runtime: Use an application command such as "uvicorn main:app", "npm run dev", or "java -jar app.jar". Derive from Makefile, package.json scripts, or README. If no start command is discoverable, omit this field entirely.
-   NEVER mix runtime types with incompatible commands (for example, using "uvicorn" with runtime "docker" will cause errors). For "local" runtime, NEVER fabricate a command. Only use commands found in Makefile, package.json scripts, or README.
-3. runtimeDetails.serverStopCommand: Optional command to stop the service after test execution. ONLY set when runtime is "docker" and serverStartCommand starts persistent Docker infrastructure. For docker compose starts, prefer matching stop/down commands from the same compose file. Omit this field for "local" and "k8s" runtimes, or when teardown is unsafe or not discoverable.
-4. runtimeDetails.dockerNetwork: Docker network name. ONLY set when runtime is "docker". NEVER set for "local" or "k8s".
-5. runtimeDetails.k8sNamespace: Kubernetes namespace. ONLY set when runtime is "k8s". NEVER set for "local" or "docker".
-6. runtimeDetails.k8sContext: Kubernetes context. ONLY set when runtime is "k8s". NEVER set for "local" or "docker".
-</runtime_fields>
-
-### Verification
-<verification>
-Before calling skyramp_init_workspace, confirm all of the following:
-1. Always scan the repo and find services. A repo should have at least one service.
-2. ALL services are included, both backend and frontend. The workspace config is a complete registry of the entire repo, not just the service relevant to your current task. A fullstack or monorepo MUST have multiple services. If you found only one, re-scan every top-level directory before proceeding.
-3. Services NOT in docker-compose.yml (such as a frontend run with pnpm or npm locally) MUST still be included with runtime "local".
-4. Every service has api.baseUrl set to a valid, discoverable URL. Use localhost for local services or the actual deployment URL for cloud or external services. Never fabricate a URL.
-5. Every service with authType apiKey has authHeader explicitly set to the actual custom header name (such as "X-API-Key" or "X-Admin-Key"). If you cannot find the header name in the source code, env vars, or README, do NOT use authType apiKey. Use authType none instead and add a YAML comment explaining auth is unresolved.
-6. framework matches language (python uses pytest or robot, typescript or javascript uses playwright, java uses junit).
-7. testDirectory follows the stable resolution rules above: framework config file when present (Playwright testDir in playwright.config.ts, pytest testpaths in pytest.ini or pyproject.toml, JUnit test source dir in pom.xml or build.gradle); otherwise the deterministic default (tests/skyramp for a single service, tests/skyramp/<serviceDirName> for multiple services). No service uses \`.skyramp\`, \`.\` or the repo root.
-8. If serverStartCommand is provided, it matches the runtime. If serverStopCommand is provided, runtime is "docker" and the command is a Docker command.
-9. For services in docker-compose.yml: runtime MUST be "docker" and the command MUST be a docker command such as "docker compose up -d --build <service-name>" when the service has a build context. Always include it since it is derivable from the service name.
-10. NEVER use application-level commands (uvicorn, npm, node, python, java, etc.) with runtime "docker".
-11. For "local" runtime: if no start command is discoverable from Makefile, package.json scripts, or README, omit serverStartCommand rather than guessing.
-12. dockerNetwork is set only when runtime is "docker".
-13. k8sNamespace and k8sContext are set only when runtime is "k8s".
-14. If force-recreating a workspace.yml due to a schema validation error, correct the schema error but keep any valid system-under-test setup (serviceName, baseUrl, auth config, runtime details) as it is.
-</verification>
-
-Once verified, call skyramp_init_workspace with:
-- workspacePath: the repository root path
-- services: the array built above
-- scanToken: the token returned by the first call to skyramp_init_scan
-- force: defaults to false. Set to true only if the user explicitly asks to overwrite an existing .skyramp/workspace.yml, or if the existing file must be regenerated due to a validation failure such as a schema mismatch, unknown fields, or a parse error.`;
+export const INIT_WORKSPACE_INSTRUCTIONS = `${getPersonaPrefix()}Scan this repository and register every component of the system under test in .skyramp/workspace.yml.
+
+### Find the components
+A component runs on its own: a backend API, a frontend app, or a worker with its own entry point. Shared libraries are not components. Read the workspace manifests, compose and container files, CI workflows, README, CLAUDE.md and AGENTS.md, then check every top-level directory. Register every component, frontends included; a monorepo usually has several.
+
+### Fields
+Take every value from a file you read or a rule below; never invent one. For each component:
+- serviceName: always \`<repoName>-<componentDir>\`, or \`<repoName>\` for a component at the root.
+- language: the language of its tests, or of its code when it has none, in lowercase.
+- framework: the framework of its API or UI tests; when it has none, the one its repository or language commonly uses. Never leave it out.
+- testDirectory: where generated tests go, relative to the repository root. Use the directory its test framework config names; otherwise \`tests/skyramp\` for a single component, or \`tests/skyramp/<componentDir>\` for several, with \`/\` in the directory replaced by \`-\`. Never \`.skyramp\`, a path inside it, or the root.
+- api.baseUrl: the URL its API paths are appended to: scheme, host and port where it runs locally (or its hosted URL), plus a base path only when its OpenAPI \`servers\` URL or \`basePath\` holds one the paths leave out. A frontend the backend serves shares the backend's. api.schemaPath: its OpenAPI file or URL, if any.
+- api.authType: from its auth code, dependencies or environment variables; \`none\` without a signal. For \`apiKey\`, set api.authHeader to the header name.
+- runtimeDetails.runtime: \`docker\` when it runs in containers, \`k8s\` when it runs on Kubernetes, else \`local\`, as the repository runs it. dockerNetwork: the network its containers join, if any.
+
+### Call the tool
+First write a Discovery Summary: the services array, and for each value the file or rule that set it. Then call skyramp_init_workspace with workspacePath (the repository root), services and scanToken. Set force only when the user asks to overwrite, or the existing file fails validation; then keep its valid values. When the tool refuses, fix every problem it lists and call it again with the full array and the same scanToken.`;
+/**
+ * The scan instructions for one workspace. With related repositories, every
+ * repository is scanned into the one workspace.yml at `workspacePath`, each
+ * related repository's services carrying its `repository`. With a test
+ * repository, testDirectory is read from, and relative to, that checkout.
+ */
+export function buildInitWorkspaceInstructions(target) {
+    const related = target.relatedRepositories ?? [];
+    const deliveryRoot = target.testRepositoryPath ?? target.workspacePath;
+    const blocks = [];
+    if (related.length > 0) {
+        blocks.push(`### Target repositories
+<target_repositories>
+Scan each repository below as above; pass the components of all ${related.length + 1} to one skyramp_init_workspace call with workspacePath "${target.workspacePath}":
+- ${target.workspacePath}: this workspace's own, with no repository.
+${related.map((r) => `- ${r.repositoryPath}: set repository to "${r.repository}" on each of its components.`).join("\n")}
+Write a related repository's paths from its own root, except testDirectory: every testDirectory is relative to ${deliveryRoot}, and a related repository's fallback is \`tests/skyramp/<repoName>\`, or \`tests/skyramp/<repoName>-<componentDir>\` with several components.
+</target_repositories>`);
+    }
+    if (target.testRepositoryPath) {
+        blocks.push(`### Test repository
+<test_repository>
+Generated tests go to the test repository at ${target.testRepositoryPath}. Read testDirectory from its framework config, relative to its root, with the same fallback. Register no component for it.
+</test_repository>`);
+    }
+    return blocks.length
+        ? `${INIT_WORKSPACE_INSTRUCTIONS}\n\n${blocks.join("\n\n")}`
+        : INIT_WORKSPACE_INSTRUCTIONS;
+}

package/build/prompts/modularization/ui-test-modularization.d.ts

@@ -1,3 +1,4 @@
+export declare const PICKED_OPTION_RULE = "ONE exception, because there the selector IS the value this scenario selects: the locator of the option or item the scenario picks from a list, when its test id or role name carries that option's label (`getByTestId(\"add-order-product-option-Adidas Running Shoes\")`, `getByRole(\"option\", { name: \"Adidas Running Shoes\" })`). That one argument becomes a parameter, and the call site passes the original string whole and byte-identical (`getByTestId(productOptionTestId)` called with `\"add-order-product-option-Adidas Running Shoes\"`; `getByRole(\"option\", { name: productName })` called with `\"Adidas Running Shoes\"`) \u2014 never rebuilt from a template or a shorter value. Every other selector, including the control that opens the list and the button that confirms the pick, stays verbatim.";
 export declare function getModularizationPrompt(filePath: string, testType: string, language?: string): string;
 /** Structured view of which steps render for the given inputs (for tests). */
 export declare function previewModularizationPlan(filePath: string, testType: string, language?: string): import("../test-recommendation/promptPlan.js").PlanPreview;

package/build/prompts/modularization/ui-test-modularization.js

@@ -151,7 +151,7 @@ ${p.utilsReuse
 **SHARED HELPER SHAPE:**
 - [ ] Every helper name is a canonical intent (\`openEditOrderForm\`, \`applyDiscount\`) with no scenario value or adjective in it
 - [ ] No helper contains a value assertion (${BROWSER_VALUE_ASSERTIONS}) — each sits in the test body, right after the helper call it verifies
-- [ ] Every selector inside a helper is byte-identical to the original test
+- [ ] Every selector inside a helper is byte-identical to the original test, except a picked option's locator argument, which is a parameter whose call-site argument is byte-identical
 - [ ] The assertion COUNT is unchanged: every \`expect(\` from the original is still in this file or inside a helper it calls, and the \`page.on('pageerror'...)\` guard and its final \`expect\` over the collected errors are still here — cross-cutting guards are never removed (the verify step counts both)
 `
     : ""}
@@ -184,10 +184,17 @@ If ANY answer is "no", fix it before submitting.
 // scenario's data — a `toHaveText("Total: $899.98")` inside a shared helper
 // fails every other caller. Selectors stay verbatim regardless (a selector is
 // not scenario data; parameterizing it invents a template the recorder never saw).
+// SKYR-4537: the one selector that is scenario data. An option picked from a list
+// is often located by its own label (test id or role name), so the value the
+// scenario selects lives only inside that locator. Kept verbatim in the helper it
+// pins every caller to this scenario's option, and the reuse scan can never match
+// another test that picks a different one. Passing the whole string (no template)
+// keeps the selector byte-identical at the call site.
+export const PICKED_OPTION_RULE = 'ONE exception, because there the selector IS the value this scenario selects: the locator of the option or item the scenario picks from a list, when its test id or role name carries that option\'s label (`getByTestId("add-order-product-option-Adidas Running Shoes")`, `getByRole("option", { name: "Adidas Running Shoes" })`). That one argument becomes a parameter, and the call site passes the original string whole and byte-identical (`getByTestId(productOptionTestId)` called with `"add-order-product-option-Adidas Running Shoes"`; `getByRole("option", { name: productName })` called with `"Adidas Running Shoes"`) — never rebuilt from a template or a shorter value. Every other selector, including the control that opens the list and the button that confirms the pick, stays verbatim.';
 function sharedHelperShape() {
     return `**SHARED HELPER SHAPE (this project consolidates helpers into a shared utils file):**
 - ${BROWSER_HELPERS.namingRule}
-- **PARAMETERS**: \`page\`, plus every value this scenario types or selects (${BROWSER_HELPERS.liftableLiterals}). Selectors are NEVER parameters — they stay verbatim inside the helper body.
+- **PARAMETERS**: \`page\`, plus every value this scenario types or selects (${BROWSER_HELPERS.liftableLiterals}). Selectors are NEVER parameters — they stay verbatim inside the helper body. ${PICKED_OPTION_RULE}
 - ${BROWSER_HELPERS.assertionRule} ${ASSERTION_BOUNDARY_RULE_EXTRACT}
 - Helpers are module-level named functions in this file; the test body becomes navigation + a sequence of helper calls + this scenario's assertions, in the original order.`;
 }

package/build/prompts/test-maintenance/driftAnalysisShared.js

@@ -57,7 +57,7 @@ ${opts.domainNotes}
 
 **If your rationale concludes the test is unaffected, assign IGNORE, not VERIFY.** Assign VERIFY only for a doubt that the code you read does not settle. A rule that forbids IGNORE still applies.
 
-**A stated requirement wins over the code.** Before you write a new value or refresh a screenshot in an existing test, compare it with what the pull request title, the description and any requirements file they name state. If the new value breaks a stated requirement, do not write it: keep that assertion on the requirement's value and make only the other edits. If no other edit remains, mark the test VERIFY. The test stays red; do not relax it. If the requirements file is unchanged and the description presents the new behaviour as intended, the file is out of date: update the test.
+**A stated requirement wins over the code.** Before you write a new value or refresh a screenshot in an existing test, compare it with what the pull request title, the description and any requirements file they name state. If the new value breaks a stated requirement, do not write it: keep that assertion on the requirement's value and make only the other edits. If no other edit remains, mark the test VERIFY. The test stays red; do not relax it. Authority runs requirements > PR description > code change: an unchanged requirements file that the description contradicts still wins — keep the assertion on the file's value and report the requirement conflict.
 
 **Pre-commit verification — confirm before finalizing UPDATE/REGENERATE/DELETE:**
 1. You can quote a specific diff line${opts.blueprintSuffix} this test observes that triggered the action.