@skyramp/mcp 0.1.5 → 0.1.7

package/build/index.js

@@ -35,6 +35,7 @@ import { registerAnalysisResources } from "./resources/analysisResources.js";
 import { registerProgressResource } from "./resources/progressResource.js";
 import { AnalyticsService } from "./services/AnalyticsService.js";
 import { registerInitTriggerOnMCPInitialized } from "./utils/initAgent.js";
+import { isTestbotEnabled } from "./utils/featureFlags.js";
 import { registerPlaywrightTools, registerTraceRecordingPrompt, getPlaywrightTraceService, } from "./playwright/index.js";
 const oneClickEnabled = process.env.SKYRAMP_FEATURE_ONE_CLICK === "1";
 const oneClickInstructions = oneClickEnabled
@@ -95,8 +96,8 @@ After \`skyramp_analyze_changes\`, inspect enriched data via MCP Resources (use
 Before calling ANY test generation tool, you MUST follow this flow:
 
 1. **Read** the .skyramp/workspace.yml file to get the configured defaults.
-2. **Extract** the \`language\`, \`framework\`, \`outputDir\`, \`api.baseUrl\`, \`api.authHeader\`, and \`api.authType\` from the services section.
-3. **Use those values** as defaults for the test generation tool call. Do NOT ask the user for these values if they are already configured in the workspace file.
+2. **Extract** the \`language\`, \`framework\`, \`testDirectory\`, \`api.baseUrl\`, \`api.authHeader\`, and \`api.authType\` from the matching service in the services section.
+3. **Use those values** as defaults for the test generation tool call. Pass the service \`testDirectory\` as the generation tool \`outputDir\`. Do NOT ask the user for these values if they are already configured in the workspace file.
 4. **CRITICAL — endpointURL**: The \`endpointURL\` parameter MUST be the full URL to the specific endpoint being tested, NOT just the base URL. Construct it by combining \`api.baseUrl\` with the endpoint path. Example: if \`api.baseUrl\` is \`http://localhost:8000\` and the endpoint is \`/api/v1/products\`, pass \`endpointURL: "http://localhost:8000/api/v1/products"\`. NEVER pass just the base URL (e.g. \`http://localhost:8000\`) as \`endpointURL\`.
 5. **CRITICAL — scenario generation**: When calling \`skyramp_batch_scenario_test_generation\`, ALWAYS pass:
    - \`baseURL\`: The full base URL from \`api.baseUrl\` (e.g., \`http://localhost:3000\`). This determines the scheme, host, and port in the generated trace. Without it, the trace defaults to https:443 which is almost always wrong for local development.
@@ -107,7 +108,7 @@ Before calling ANY test generation tool, you MUST follow this flow:
 6. **CRITICAL — integration test from scenario**: When calling \`skyramp_integration_test_generation\` with a \`scenarioFile\`:
    - If workspace has \`api.authType\` set: omit auth params entirely — passing auth here alongside workspace \`authType\` causes "${AUTH_CONFLICT_ERROR_MSG}".
    - If workspace has no \`api.authType\`: pass \`authHeader\` only (no \`authScheme\`).
-7. **If the workspace file does not exist**, or the needed values (language, framework, outputDir) are missing from the workspace config, ASK the user which language and framework they want before calling the tool.
+7. **If the workspace file does not exist**, or the needed values (language, framework, testDirectory) are missing from the workspace config, ASK the user which language, framework, and outputDir they want before calling the tool.
 8. The user can always override workspace defaults by explicitly specifying values in their request.
 `,
 });
@@ -118,7 +119,7 @@ const prompts = [
     registerRecommendTestsPrompt,
     registerTraceRecordingPrompt,
 ];
-if (process.env.SKYRAMP_FEATURE_TESTBOT === "1") {
+if (isTestbotEnabled()) {
     prompts.push(registerTestbotPrompt);
     registerTestbotResource(server);
     logger.info("TestBot prompt enabled via SKYRAMP_FEATURE_TESTBOT");
@@ -169,7 +170,7 @@ const infrastructureTools = [
     registerTraceTool,
     registerTraceStopTool,
 ];
-if (process.env.SKYRAMP_FEATURE_TESTBOT === "1") {
+if (isTestbotEnabled()) {
     infrastructureTools.push(registerSubmitReportTool);
     logger.info("TestBot tools enabled via SKYRAMP_FEATURE_TESTBOT");
 }

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

@@ -1,13 +1,10 @@
 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.
-
-**2. Then output a Discovery Summary** with the exact services array you will pass to the tool:
+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
 [
   {
@@ -18,156 +15,160 @@ After scanning the workspace, before calling the \`skyramp_init_workspace\` tool
     "api": { "schemaPath": "<path-or-url>", "baseUrl": "<url>", "authType": "<type>", "authHeader": "<header>" },
     "runtimeDetails": { "runtime": "<runtime>", "serverStartCommand": "<command>", "dockerNetwork": "<network>" }
   }
-  // ... one entry per discovered service
 ]
 \`\`\`
 
-## Step 1 — List ALL Top-Level Directories
-
+### 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) |
 
-## Step 2 — Inspect EVERY Candidate Directory
-
-For **each** top-level directory, check for service indicator files:
-
-**Language indicators** (presence of ANY = independent service):
-- package.json → typescript / javascript
-- requirements.txt, pyproject.toml, Pipfile → python
-- pom.xml, build.gradle → java
-
-**Test framework** (look inside the service dir):
-- playwright.config.* → playwright
-- pytest.ini, conftest.py, pyproject.toml [tool.pytest] → pytest
-- junit in pom.xml → junit
-
-**API schemas** (look inside the service dir AND check known framework defaults):
-- openapi.json/yaml, swagger.json/yaml → schema file path
-- FastAPI projects → http://localhost:{port}/openapi.json
-- Express with swagger-ui → http://localhost:{port}/api-docs
-- Spring Boot → http://localhost:{port}/v3/api-docs
-
-## Step 3 — Check Root-Level Runtime Config
-
+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:
-- docker-compose.yml → extract service names, ports, start commands
-  Docker Compose ALWAYS prefixes the network name with "<project-name>_".
-  If compose has "networks: { my-net: ... }" → actual network = "<project-name>_my-net".
-  If no explicit networks section → default network = "<project-name>_default".
-  Project name = basename of the CWD where docker compose runs.
-- Makefile → extract start/dev targets
-- Root package.json scripts → workspace-level commands
-
-## Step 4 — Build the Complete Services Array
-
-Create one service entry per deployable unit. You MUST include:
-- Every backend/API service (Python, Java, Go, Node.js)
-- Every frontend service (React, Vue, Angular, Next.js)
-- Set runtime fields from docker-compose.yml if present
-
-**Basic fields:**
-- \`serviceName\` *(required)* — unique identifier, e.g. "api-gateway", "user-service"
-- \`language\` — \`python\` | \`typescript\` | \`javascript\` | \`java\`
-  Detect from: package.json → typescript/javascript | requirements.txt/pyproject.toml → python | pom.xml/build.gradle → java
-- \`framework\` — \`playwright\` | \`pytest\` | \`robot\` | \`junit\`
-  Detect from: pytest.ini/playwright.config/jest.config/junit in pom.xml
-  MUST match the language: python → pytest or robot | typescript/javascript → playwright | java → junit
-- \`testDirectory\` — path relative to repo root where generated tests will be placed. **MUST match the test framework's configured test directory**:
-  - **Playwright**: Read \`playwright.config.ts\` (or \`.js\`/\`.mjs\`) and extract the \`testDir\` value. If no \`testDir\` is specified, common defaults: "tests/", "test/".
-  - **pytest**: Read \`pytest.ini\`, \`pyproject.toml [tool.pytest.ini_options]\`, or \`setup.cfg [tool:pytest]\` for \`testpaths\`. Common defaults: "tests/", "test/".
-  - **JUnit**: Usually "src/test/java" — check \`pom.xml\` or \`build.gradle\` for custom test source directories.
-  ⚠️ **CRITICAL**: If the framework config specifies a test directory, you MUST use that exact path
-
-**API fields:**
-- \`api.schemaPath\` — path or URL to OpenAPI/Protobuf/GraphQL schema
-  Search for: openapi.json, swagger.yaml, *.proto, *.graphql
-  Framework defaults: FastAPI → /openapi.json | Express → /api-docs | Spring → /v3/api-docs
-  For locally-run services, use a localhost URL. For cloud/externally hosted services (e.g. Salesforce, Vercel, Cloudflare), use the actual deployment URL found in config or documentation.
-- \`api.baseUrl\` *(required)* — the base URL where the service is reachable, e.g. "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; use the actual deployment URL for cloud/externally hosted services.
-  ⚠️  NEVER fabricate a URL — only use URLs found in config files, README, or environment variables.
-- \`api.authType\` — auth type: ${AUTH_TYPES_PROMPT_LIST}
-
-  Detect by checking in order (language-agnostic — apply whichever signals match):
-  1. **Dependencies / 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\`, \`spring-security-oauth2\` → \`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 → \`cookie\`. Check the \`SecurityConfig\` / \`WebSecurityConfigurerAdapter\` class before assigning \`bearer\` to any Spring service.
-     - \`passport-http\`, Spring basic auth → \`basic\`
-     - \`passport-oauth2\`, \`openid-client\`, \`doorkeeper\`, \`keycloak-connect\`, \`spring-security-oauth2-resource-server\`, \`github.com/coreos/go-oidc\` → \`oauth\`
-     - \`rest_framework\` with \`TokenAuthentication\`, \`djangorestframework-simplejwt\` (Token scheme) → \`token\`
-     - \`express-session\`, \`cookie-session\`, \`iron-session\`, \`next-auth\`, \`gorilla/sessions\`, \`laravel/session\` → \`cookie\`
-     - \`laravel/sanctum\`, \`laravel/passport\` (API routes) → \`bearer\`; frontend web routes → \`cookie\`
-  2. **Environment variables** (.env, docker-compose, README):
-     - \`JWT_SECRET\`, \`ACCESS_TOKEN_SECRET\`, \`FIREBASE_SECRET\`, \`SUPABASE_JWT_SECRET\` → \`bearer\`
-     - \`API_KEY\`, \`X_API_KEY\`, \`ADMIN_KEY\`, \`SERVICE_KEY\` (used as header value, not JWT signing) → \`apiKey\`
-     - \`CLIENT_ID\` + \`CLIENT_SECRET\`, \`OAUTH_CLIENT_*\`, \`OIDC_*\` → \`oauth\`
-     - \`SESSION_SECRET\`, \`COOKIE_SECRET\`, \`NEXTAUTH_SECRET\` → \`cookie\`
-  3. **Source code / middleware patterns** (auth, middleware, or security config files):
-     - Node/Express: \`req.headers.authorization\` split \`"Bearer"\` → \`bearer\` | \`Authorization: Token\` → \`token\` | custom header check → \`apiKey\` | session/cookie middleware → \`cookie\`
-     - FastAPI/Starlette: \`HTTPBearer\`, \`OAuth2PasswordBearer\`, \`Depends(get_current_user)\` → \`bearer\` | \`SessionMiddleware\` → \`cookie\`
-     - Django/DRF: \`TokenAuthentication\` → \`token\` | \`JWTAuthentication\` → \`bearer\` | \`SessionAuthentication\` → \`cookie\`
-     - Spring: \`JwtDecoder\` / \`JwtAuthenticationFilter\` → \`bearer\` | \`HttpSecurity.formLogin()\` + sessions → \`cookie\`
-     - Go: \`ParseWithClaims\` / \`GetHeader("Authorization")\` → \`bearer\` | \`gorilla/sessions\` → \`cookie\`
-     - Rails: \`authenticate_or_request_with_http_token\` → \`bearer\` | \`before_action :authenticate_user!\` (Devise) → \`cookie\`
-     - Laravel: \`auth:sanctum\` (API) → \`bearer\` | \`middleware("auth")\` web → \`cookie\`
-     - Rust/Axum: \`Authorization<Bearer>\` extraction → \`bearer\`
-  4. **Query-parameter auth** — some APIs pass credentials as a URL query param rather than a header (e.g. \`?key=<key>\`, \`?api_key=<key>\`, \`?access_token=<token>\`). Signals:
-     - Source code reads credentials from \`req.query.key\`, \`request.query_params["api_key"]\`, \`@RequestParam("token")\`, etc.
-     - API docs / README show auth examples like \`/endpoint?key=<your-key>\`
-  5. Fallback: frontend/UI service → \`none\` | backend API with no header-based auth signals → \`bearer\`
-- \`api.authHeader\` — the exact HTTP header name carrying the credential:
-  - \`bearer\` / \`basic\` / \`oauth\` / \`token\`: always \`"Authorization"\` (inferred automatically, so you may omit it)
-  - \`cookie\` / \`session\`: always \`"Cookie"\` (also inferred automatically)
-  - \`apiKey\`: **required** — set to the actual custom header name (e.g. \`"X-API-Key"\`, \`"X-Admin-Key"\`)
-  - \`none\`: omit or \`""\`
-- \`api.authScheme\` *(optional)* — the Authorization header prefix (the word before the token):
-  - Standard types derive this automatically: \`bearer\` → \`"Bearer"\`, \`token\` → \`"Token"\`, \`basic\` → \`"Basic"\`
-  - **Set explicitly for custom/non-standard schemes** (e.g. Hawk uses \`"Hawk"\`, Digest uses \`"Digest"\`)
-  - Example: \`authType: bearer\`, \`authScheme: "Hawk"\` → produces \`Authorization: Hawk <token>\`
-  - Omit for cookie/session/apiKey (they don't use Authorization header)
-
-**Runtime fields:**
-- \`runtimeDetails.runtime\` — \`local\` | \`docker\` | \`k8s\`
-  Detect per service:
-  - Service listed in docker-compose.yml → \`"docker"\`
-  - Service has only a Dockerfile (no compose entry) → \`"local"\` or \`"docker"\`
-  - k8s manifests exist (charts/, k8s/, deploy/) → \`"k8s"\`
-  ⚠️  A repo may have MIXED runtimes — a backend in docker-compose.yml uses "docker" while a frontend run with pnpm/npm locally uses "local". Include ALL services regardless of runtime.
-
-- \`runtimeDetails.serverStartCommand\` — command to start the service. MUST match runtime:
-  - \`"local"\`  → application command: "uvicorn main:app", "npm run dev", "java -jar app.jar"
-  - \`"docker"\` → Docker command: "docker compose up -d \<service-name\>"  ← prefer service-scoped
-  - \`"k8s"\`    → k8s command: "kubectl apply -f deploy/", "helm install myrelease ."
-  ⚠️  NEVER mix (e.g. "uvicorn …" with runtime "docker" will cause errors).
-
-- \`runtimeDetails.dockerNetwork\` — Docker network name. ONLY set when runtime is \`"docker"\`. NEVER set for "local" or "k8s".
-- \`runtimeDetails.k8sNamespace\` — Kubernetes namespace. ONLY set when runtime is \`"k8s"\`. NEVER set for "local" or "docker".
-- \`runtimeDetails.k8sContext\` — Kubernetes context. ONLY set when runtime is \`"k8s"\`. NEVER set for "local" or "docker".
-
-## Verification Steps
-
-Before calling \`skyramp_init_workspace\`, confirm all of the following:
-- ALWAYS SCAN REPO AND FIND SERVICES. A REPO SHOULD HAVE AT LEAST ONE SERVICE.
-- **CRITICAL**: ALL services are included — 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.
-- Services NOT in docker-compose.yml (e.g. a frontend run with pnpm/npm locally) MUST still be included with runtime "local".
-- Every service has \`api.baseUrl\` set to a valid, discoverable URL — localhost for local services, or the actual deployment URL for cloud/external services. Never fabricate a URL.
-- Every service with \`authType: apiKey\` has \`authHeader\` explicitly set to the actual custom header name (e.g. \`"X-API-Key"\`, \`"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\` and add a YAML comment explaining auth is unresolved.
-- \`framework\` matches \`language\` (python → pytest/robot | typescript/javascript → playwright | java → junit)
-- \`testDirectory\` matches the framework's config file (Playwright: \`testDir\` in playwright.config.ts | pytest: \`testpaths\` in pytest.ini/pyproject.toml | JUnit: test source dir in pom.xml/build.gradle). If no config file is found, use the common defaults: "tests/", "test/".
-- \`serverStartCommand\` matches \`runtime\`
-- For services in docker-compose.yml: runtime MUST be "docker" and command MUST be a docker command (e.g. "docker compose up -d <service-name>").
-- NEVER use application-level commands (uvicorn, npm, node, python, java, etc.) with runtime "docker".
-- \`dockerNetwork\` is set only when runtime is "docker"
-- \`k8sNamespace\` and \`k8sContext\` are set only when runtime is "k8s"
-
-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_workspace\` (called with only workspacePath)
-- \`force\`: defaults to false — only set to true if the user explicitly asks to overwrite an existing \`.skyramp/workspace.yml\``;
+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 and serverStartCommand. When a non-default compose file is found, the serverStartCommand must reference it explicitly (such as "docker compose -f docker-compose.testbot.yml up -d <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>-<serviceName>-<frontend or backend> for consistency. For example: directus-api-backend, directus-app-frontend. 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.
+</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.
+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/), 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.
+2. runtimeDetails.serverStartCommand: The command to start or deploy the service. It MUST match the runtime:
+   - For "docker" runtime: Use a Docker command such as "docker compose up -d <service-name>" for the default docker-compose.yml, or "docker compose -f <compose-file> up -d <service-name>" when using a non-default compose file. This is always derivable from the application docker compose file and service name.
+   - 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.dockerNetwork: Docker network name. ONLY set when runtime is "docker". NEVER set for "local" or "k8s".
+4. runtimeDetails.k8sNamespace: Kubernetes namespace. ONLY set when runtime is "k8s". NEVER set for "local" or "docker".
+5. 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).
+8. If serverStartCommand is provided, it matches the runtime.
+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 <service-name>". 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.`;

package/build/prompts/personas.js

@@ -1,3 +1,4 @@
+import { isTestbotEnabled } from "../utils/featureFlags.js";
 /**
  * Skyramp personas injected into tool descriptions and prompts.
  *
@@ -19,5 +20,5 @@ export const SKYRAMP_QA_PERSONA = `You are acting as a Skyramp QA Automation Eng
  * avoid duplicating it in every tool description.
  */
 export function getPersonaPrefix() {
-    return process.env.SKYRAMP_FEATURE_TESTBOT ? '' : `${SKYRAMP_QA_PERSONA}\n\n`;
+    return isTestbotEnabled() ? '' : `${SKYRAMP_QA_PERSONA}\n\n`;
 }

package/build/prompts/test-maintenance/drift-analysis-prompt.js

@@ -74,8 +74,9 @@ ${candidateFilesSection}`;
     if (inlineMode) {
         // Testbot inline mode: all maintenance logic lives here so the testbot
         // prompt only orchestrates steps without duplicating rules.
+        // No persona statement here — the outer testbot prompt already establishes
+        // the agent's context; a nested identity statement causes role confusion.
         return `<drift_analysis_rules>
-You are acting as a Skyramp Integration Architect.
 For this maintenance step: assess each existing test against the diff returned by \`skyramp_analyze_changes\` and apply the correct action (IGNORE, UPDATE, REGENERATE, or DELETE) directly — no separate analysis step.
 
 ${buildActionDecisionMatrix()}

package/build/prompts/test-maintenance/drift-analysis-prompt.test.js

@@ -1,4 +1,32 @@
 import { buildDriftAnalysisPrompt } from "./drift-analysis-prompt.js";
+describe("buildDriftAnalysisPrompt - inline mode (no stateFile)", () => {
+    function inlinePrompt() {
+        return buildDriftAnalysisPrompt({
+            existingTests: [],
+            scannedEndpoints: [],
+            repositoryPath: "/repo",
+            // stateFile omitted → inline mode
+        });
+    }
+    it("wraps inline rules in drift_analysis_rules XML tags", () => {
+        const prompt = inlinePrompt();
+        expect(prompt).toContain("<drift_analysis_rules>");
+        expect(prompt).toContain("</drift_analysis_rules>");
+    });
+    it("does not contain the persona statement", () => {
+        const prompt = inlinePrompt();
+        expect(prompt).not.toContain("You are acting as a Skyramp Integration Architect");
+    });
+    it("does not contain the standalone Test Health Analysis header", () => {
+        const prompt = inlinePrompt();
+        expect(prompt).not.toContain("# Test Health Analysis");
+    });
+    it("does not contain the skyramp_actions CTA (that belongs to standalone mode)", () => {
+        const prompt = inlinePrompt();
+        // Inline mode final step directs applying changes directly, not calling skyramp_actions
+        expect(prompt).not.toContain("call `skyramp_actions`");
+    });
+});
 describe("buildDriftAnalysisPrompt - scanned endpoints rendering", () => {
     // Reproduces the [object Object] bug: skeletonEndpoints from analyzeChangesTool
     // stores methods as objects { method: string, ... }, not plain strings.

package/build/prompts/test-recommendation/analysisOutputPrompt.js

@@ -12,12 +12,22 @@ const FRONTEND_EXT = /\.(tsx?|jsx?|vue|svelte|css|scss|less|html|svg)$/i;
  * Returned as an empty string when no router context is available.
  */
 function buildPathResolutionTableStep(p) {
-    if (!p.routerMountContext.length || p.wsSchemaPath)
-        return "";
-    return `### Step 1.5: Build path resolution table
-The **Routing entry-point files** section above lists the files to read.
-
-**Read each of those files** and trace every router mount call to understand nesting — the pattern varies by framework but the structure is universal: a parent attaches a child router with an optional extra prefix segment. If a prefix is a variable (e.g. \`prefix=api_prefix\`), resolve the variable's value by reading the assignment or the config/settings file it comes from. Examples of what to look for (non-exhaustive):
+    // Case A: spec was fetched successfully — instruct LLM to validate paths against it
+    if (p.wsSchemaPath && p.specFetchSucceeded) {
+        return `### Step 1.5: Validate all endpoint paths against the OpenAPI spec
+Fetch \`${p.wsSchemaPath}\` and extract all keys from \`spec.paths\`.
+**Before placing any path in a tool call**, confirm it exists in that list.
+If a path is NOT in the spec **and it did not come from the PR diff**, find the correct spelling by matching resource name — do NOT use it unverified.
+Paths the PR explicitly added or modified may not yet appear in the spec (spec lag) — treat those as valid.
+`;
+    }
+    // Case B: no spec (or spec unreachable) but router mount context available
+    if (p.routerMountContext.length) {
+        const hasInlined = (p.routerFileContents?.length ?? 0) > 0;
+        return `### Step 1.5: Build path resolution table
+${hasInlined
+            ? "The **Routing entry-point files** section above contains the inlined file contents — use them directly to trace every router mount call"
+            : "The **Routing entry-point files** section above lists the files to read.\n\n**Read each of those files** and trace every router mount call"} to understand nesting — the pattern varies by framework but the structure is universal: a parent attaches a child router with an optional extra prefix segment. If a prefix is a variable (e.g. \`prefix=api_prefix\`), resolve the variable's value by reading the assignment or the config/settings file it comes from. Examples of what to look for (non-exhaustive):
 - Python (FastAPI/Flask): \`parent.include_router(child, prefix="...")\`, \`app.register_blueprint(...)\`
 - JS/TS (Express/Fastify/Hapi): \`app.use('/path', childRouter)\`, \`router.use('/path', sub)\`
 - NestJS: \`@Module({ imports: [FeatureModule] })\` — trace the module import chain; each \`@Controller('prefix')\` contributes a segment
@@ -33,6 +43,20 @@ Chain all segments from the app root down through every intermediate mount to ea
 
 **This table is authoritative.** Before placing any URL in a tool call, look up the source file. If the pre-built catalog shows a different path, use the table value.
 
+`;
+    }
+    // Case C: no spec AND no router context — source-verify fallback
+    // Note: also fires when a spec was configured (wsSchemaPath set) but could not be
+    // fetched at analysis time (specFetchSucceeded = false). When that happens the LLM
+    // should know a spec was expected so it can be extra-skeptical about path correctness.
+    const specFailedNote = p.wsSchemaPath && !p.specFetchSucceeded
+        ? `\n> ⚠️ A spec was configured (\`${p.wsSchemaPath}\`) but could not be loaded at analysis time — treat all paths as unverified until confirmed against source.`
+        : "";
+    return `### Step 1.5: Verify endpoint paths from source files
+The endpoint catalog below was produced by static regex analysis and is **unverified**.
+Before using any path in a tool call, read the route definition file identified in the "Source" column and confirm the path string exactly.
+Pay special attention to mount prefixes — a router at \`/api/v1\` + route \`/version\` → path is \`/api/v1/version\`, not \`/api/server-version\`.
+${specFailedNote}
 `;
 }
 // Inline note added to any step where the LLM reads Java source files. Java Spring
@@ -125,6 +149,33 @@ No diff was available — read the changed source files listed above directly to
 ${diffHasJavaFiles ? JAVA_SPRING_NOTE : ""}
 For each endpoint found: note the HTTP method, full path, and source file.
 Also compare against the endpoint catalog to identify any endpoints that appear in the catalog but are no longer present in the source files — these are removed endpoints.`;
+    // Step 2.3: Caller-tracing instruction — only emitted when the PR touches backend code
+    // files that contain no route annotations (utilities, helpers, services). Tells the LLM
+    // to search for callers of the changed functions to find the actual HTTP surface
+    // rather than falling back to the proximity-scanned CRUD endpoints. (Bug 5 fix)
+    //
+    // We filter out:
+    //   - Frontend component files (.jsx/.tsx/.vue/.svelte) — UI changes have no callers
+    //     in the HTTP graph; emitting this block for them produces irrelevant instructions.
+    //   - Non-code files (docs, config, assets, lockfiles) — they have no "changed symbols"
+    //     to trace and listing them as bullets is misleading.
+    const BACKEND_CODE_EXT = /\.(ts|js|mjs|cjs|py|java|kt|rb|go|cs|php|rs|scala|swift|c|cpp|h|hpp)$/i;
+    const traceableUnmatched = (p.unmatchedFiles ?? []).filter(f => BACKEND_CODE_EXT.test(f));
+    const callerTracingStep = isDiffScope && !isUIOnly && traceableUnmatched.length > 0
+        ? `
+### Step 2.3: Trace callers of changed non-route files
+The following changed files contain **no HTTP endpoint registrations** (no route annotations, controller mappings, or handler decorators). Their changes will only be tested if you find and target the HTTP endpoints that *call* them:
+
+${traceableUnmatched.map(f => `- \`${f}\``).join("\n")}
+
+For each file above:
+1. **Find the changed symbols** — read the diff (or the file) to identify which functions, methods, or classes were modified.
+2. **Search for callers** — look for import statements and call sites of those symbols across service, handler, and controller files. Use fully qualified names (e.g. \`DataUtils.addFileData\`, not just \`addFileData\`) to avoid false matches in large monorepos.
+3. **Trace to HTTP registration** — from each caller, follow up to the route/controller registration (Spring \`@PostMapping\`, Express \`router.post\`, FastAPI \`@router.post\`, etc.) to identify the endpoint(s) that invoke the changed logic.
+4. **Augment the endpoint list** from Step 2 with these execution-path endpoints.
+5. If an execution or processing endpoint is found (path ending in \`/execute\`, \`/run\`, \`/trigger\`, \`/process\`, \`/invoke\`, or similar), it **MUST** be included in the test candidates. Do not produce coverage consisting solely of CRUD endpoints when an execution-path endpoint was found — CRUD tests may still be included but must not be the only coverage.
+`
+        : "";
     const criticalPatternStep = `### Step 2.5: Identify critical patterns for test categorization
 Look for these patterns in model/schema/handler files to inform test recommendations:
 - **Unique constraints**: \`@unique\`, \`unique: true\`, unique indexes, \`.refine()\` uniqueness checks, \`UNIQUE\` in SQL migrations
@@ -168,22 +219,29 @@ Call \`skyramp_recommend_tests\` with:
 ### Step 1: Read the changed files and diff
 ${changedFiles}${diffFileRef}
 ${buildPathResolutionTableStep(p)}${step2}
-
+${callerTracingStep}
 ${criticalPatternStep}
 
 ${step3Content}`;
 }
 export function buildAnalysisOutputText(p) {
     const isDiffScope = p.analysisScope === AnalysisScope.CurrentBranchDiff;
-    // Router mounting context is unique to this prompt (not in recommendationPrompt).
-    // Branch diff, endpoint catalog, auth config, and OpenAPI spec are omitted here
-    // because they are already present in the recommendation prompt that is
-    // concatenated in the same tool response.
-    const routerSection = !p.wsSchemaPath && p.routerMountContext.length
+    // Router mounting context is unique to this prompt; shown whenever mount context
+    // is available, regardless of whether a spec is configured.
+    const routerSection = p.routerMountContext.length
         ? `
 ## Routing entry-point files
-Read these in Step 1.5 to trace the full router/module hierarchy:
-${p.routerMountContext.map(f => `- \`${f}\``).join("\n")}`
+${p.routerFileContents?.length
+            ? p.routerFileContents.map(({ file, content }) => `### \`${file}\`\n\`\`\`\n${content}\n\`\`\``)
+                .join("\n\n") + (p.routerMountContext.length > (p.routerFileContents?.length ?? 0)
+                ? `\n\nAdditional files (too large to inline — read manually if needed):\n` +
+                    p.routerMountContext
+                        .filter(f => !(p.routerFileContents ?? []).some(r => r.file === f))
+                        .map(f => `- \`${f}\``)
+                        .join("\n")
+                : "")
+            : `Read these in Step 1.5 to trace the full router/module hierarchy:\n` +
+                p.routerMountContext.map(f => `- \`${f}\``).join("\n")}`
         : "";
     const enrichment = buildEnrichmentInstructions(p);
     return `# Repository Analysis