@skyramp/mcp 0.1.0-rc.3 → 0.1.0-rc.5

package/build/commands/recommendTestsAndExecuteCommand.js

@@ -5,7 +5,6 @@
  *   skyramp_analyze_changes (combined analyze + discover + recommend)
  *   → Generate tests for top N recommended types
  *   → Execute each via skyramp_execute_test
- *   → State cleanup
  */
 const fullRepoRecommendGenerateExecuteTopNSteps = [
     {
@@ -62,24 +61,11 @@ const fullRepoRecommendGenerateExecuteTopNSteps = [
         },
         conditionalGuidance: "Skip if step 2 generated no tests. Iterate over each generated test file path returned directly from the tools invoked in step 2 and call skyramp_execute_test once per file. Token resolution: (1) user-provided token; (2) token from .skyramp/workspace.yml or repo config; (3) empty string '' — let skyramp_execute_test surface auth errors, then ask the user for a Bearer token to re-run.",
     },
-    {
-        stepIndex: 4,
-        title: "Clean up state files",
-        description: "Call skyramp_state_cleanup with action 'cleanup' and maxAgeHours set to 1 to remove temporary state files created by the recommendation toolset. These live in system temp (e.g. /tmp) — not in the user repo.",
-        toolCall: {
-            toolName: "skyramp_state_cleanup",
-            description: "Remove temporary state files from system temp",
-            inputs: {
-                action: { source: "literal", value: "cleanup" },
-                maxAgeHours: { source: "literal", value: 1 },
-            },
-        },
-    },
 ];
 export const FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND = {
     id: "full_repo_scan_recommend_generate_and_execute_top_n_tests",
     name: "Full Repo: Recommend, Generate and Run TopN Tests",
-    description: "Run skyramp_analyze_changes to scan the repo and get ranked recommendations, generate tests for the top N recommended types, execute the generated tests, then clean up state files.",
+    description: "Run skyramp_analyze_changes to scan the repo and get ranked recommendations, generate tests for the top N recommended types, then execute the generated tests.",
     intent: {
         contextIndicators: [
             "Use when the user wants to scan the entire repository with no specific endpoint or PR diff in mind — to get ranked test recommendations across all endpoints, generate the top N recommended test types, and execute them",
@@ -89,8 +75,8 @@ export const FULLREPO_RECOMMEND_GENERATE_EXECUTE_TOPN_TESTS_COMMAND = {
             "Do NOT use when the user asks about a PR diff or branch-scoped analysis — use skyramp_analyze_changes directly instead",
             "Do NOT use for simple single-tool requests such as 'generate a smoke test' or 'recommend tests for this PR'",
         ],
-        purpose: "Full repo scan: get recommendations → Generate top N types → Execute generated tests → Clean up (no specific endpoint, no PR diff)",
-        workflowSummary: "Full Repo Scan → Recommend → Generate top N → Execute each test → Clean up",
+        purpose: "Full repo scan: get recommendations → Generate top N types → Execute generated tests (no specific endpoint, no PR diff). Cleanup is handled automatically.",
+        workflowSummary: "Full Repo Scan → Recommend → Generate top N → Execute each test (cleanup is automatic)",
         examples: {
             use: [
                 "scan the full repo and recommend and execute top 3 tests",

package/build/commands/testThisEndpointCommand.js

@@ -7,7 +7,6 @@
  *   → Generate missing tests (by type)
  *   → Execute generated tests
  *   → [if existing tests found] Analyze test health → Optional batch execute → Actions
- *   → State cleanup
  */
 const comprehensivelyTestGivenEndpointSteps = [
     {
@@ -82,41 +81,39 @@ const comprehensivelyTestGivenEndpointSteps = [
             },
             outputs: ["stateFile"],
         },
-        conditionalGuidance: "Only run when step 1 found existing tests specifically for the target endpoint. If no tests were found for the target endpoint, skip steps 5–7 and go to step 8 (cleanup).",
+        conditionalGuidance: "Only run when step 1 found existing tests specifically for the target endpoint. If no tests were found for the target endpoint, skip steps 5–7.",
     },
     {
         stepIndex: 6,
-        title: "Optional: execute existing tests in batch (only if step 5 ran)",
-        description: "Run only if step 5 ran. Optionally call skyramp_execute_tests with the stateFile from step 5 to run existing tests and capture pass/fail results. Merge results back into the state file for use by skyramp_actions. Use token from user or empty string. If you skip this step, pass the stateFile from step 5 directly to step 7.",
+        title: "Optional: execute existing tests (only if step 5 ran)",
+        description: "Run only if step 5 ran. Optionally execute existing tests using skyramp_execute_test for each test file discovered in the stateFile. Extract test file paths, languages, and types from the stateFile (from step 1), then call skyramp_execute_test once per test with stateFile parameter to write results back. Use token from user or empty string. If you skip this step, proceed directly to step 7.",
         toolCall: {
-            toolName: "skyramp_execute_tests",
-            description: "Optionally run existing tests in batch; updates state with results",
+            toolName: "skyramp_execute_test",
+            description: "Optionally run existing tests individually; iterate over tests from stateFile and write results back",
             inputs: {
-                stateFile: { source: "step", stepIndex: 5, outputKey: "stateFile" },
-                authToken: { source: "user", paramKey: "token" },
+                workspacePath: { source: "user", paramKey: "repositoryPath" },
+                testFile: { source: "literal", value: "path from stateFile existingTests array" },
+                language: { source: "literal", value: "language from stateFile existingTests array" },
+                testType: { source: "literal", value: "testType from stateFile existingTests array" },
+                token: { source: "user", paramKey: "token" },
+                stateFile: { source: "step", stepIndex: 1, outputKey: "stateFile" },
             },
-            outputs: ["stateFile"],
+            outputs: [],
         },
-        conditionalGuidance: "Only run when step 5 was executed. This step is optional — skip if batch execution is not needed.",
+        conditionalGuidance: "Only run when step 5 was executed. This step is optional — skip if execution is not needed. Read the stateFile from step 1 to get the list of existing tests (existingTests array), then iterate and call skyramp_execute_test once per test with its testFile, language, testType, AND stateFile (from step 1) so execution results are written back for health scoring in step 7.",
     },
     {
         stepIndex: 7,
         title: "Run maintenance actions (only if step 5 ran)",
-        description: "Run only if step 5 ran. Call skyramp_actions with the stateFile from step 6 if step 6 ran, or step 5's stateFile if step 6 was skipped. This applies recommended fixes (UPDATE/REGENERATE/VERIFY) to existing tests and generates tests for new endpoints. Call it immediately after the assessment without waiting for user confirmation.",
-        conditionalGuidance: "Only run when step 5 was executed. Use step 6's stateFile if step 6 ran; use step 5's stateFile if step 6 was skipped. Call skyramp_actions with the resolved stateFile.",
-    },
-    {
-        stepIndex: 8,
-        title: "Clean up state files",
-        description: "Call skyramp_state_cleanup with action 'cleanup' and maxAgeHours set to 1 to remove temporary state files created by the analysis and maintenance toolsets. These live in system temp (e.g. /tmp) — not in the user repo.",
+        description: "Run only if step 5 ran. Call skyramp_actions with the stateFile from step 1 (which now contains execution results if step 6 ran, since skyramp_execute_test writes results back in-place). This applies recommended fixes (UPDATE/REGENERATE/VERIFY) to existing tests and generates tests for new endpoints. Call it immediately after the assessment without waiting for user confirmation.",
         toolCall: {
-            toolName: "skyramp_state_cleanup",
-            description: "Remove temporary state files from system temp",
+            toolName: "skyramp_actions",
+            description: "Apply recommended test maintenance actions",
             inputs: {
-                action: { source: "literal", value: "cleanup" },
-                maxAgeHours: { source: "literal", value: 1 },
+                stateFile: { source: "step", stepIndex: 1, outputKey: "stateFile" },
             },
         },
+        conditionalGuidance: "Only run when step 5 was executed. Always use stateFile from step 1 — if step 6 ran, it has updated this file in-place with execution results. The stateFile now contains all the context needed for execution-aware recommendations.",
     },
 ];
 export const TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND = {
@@ -131,8 +128,8 @@ export const TEST_GIVEN_ENDPOINT_COMPREHENSIVELY_COMMAND = {
             "Do NOT use for broad repo-level requests where no specific endpoint is named — use skyramp_analyze_changes directly instead",
             "Do NOT use for simple single-tool requests such as 'generate a smoke test for this endpoint' — those go directly to the generation tool",
         ],
-        purpose: "Deep test a given endpoint: discover existing → evaluate missing → generate missing → execute → (if existing found) health analysis → maintenance actions → clean up",
-        workflowSummary: "Analyze Changes → Evaluate missing → Generate missing → Execute generated → [if existing] Test Health → Batch execute → Actions → Clean up",
+        purpose: "Deep test a given endpoint: discover existing → evaluate missing → generate missing → execute → (if existing found) health analysis → maintenance actions. Cleanup is handled automatically.",
+        workflowSummary: "Analyze Changes → Evaluate missing → Generate missing → Execute generated → [if existing] Test Health → Batch execute → Actions (cleanup is automatic)",
         examples: {
             use: [
                 "comprehensively test the products endpoint",

package/build/index.js

@@ -22,8 +22,9 @@ import { registerModularizationTool } from "./tools/code-refactor/modularization
 import { registerCodeReuseTool } from "./tools/code-refactor/codeReuseTool.js";
 import { registerBatchScenarioTestTool } from "./tools/generate-tests/generateBatchScenarioRestTool.js";
 import { registerMockTool } from "./tools/generate-tests/generateMockRestTool.js";
-import { registerAnalyzeChangesTool, registerAnalyzeTestHealthTool, registerExecuteTestsTool, registerActionsTool, registerStateCleanupTool, } from "./tools/test-management/index.js";
-import { registerTestbotPrompt, registerTestbotResource, } from "./prompts/testbot/testbot-prompts.js";
+import { registerAnalyzeChangesTool, registerAnalyzeTestHealthTool, registerActionsTool, } from "./tools/test-management/index.js";
+import { registerTestbotPrompt } from "./prompts/testbot/testbot-prompts.js";
+import { registerTestbotResource } from "./resources/testbotResource.js";
 import { registerSubmitReportTool } from "./tools/submitReportTool.js";
 import { registerInitializeWorkspaceTool } from "./tools/workspace/initializeWorkspaceTool.js";
 import { registerInitScanWorkspaceTool } from "./tools/workspace/initScanWorkspaceTool.js";
@@ -33,6 +34,10 @@ import { registerProgressResource } from "./resources/progressResource.js";
 import { AnalyticsService } from "./services/AnalyticsService.js";
 import { registerInitTriggerOnMCPInitialized } from "./utils/initAgent.js";
 import { registerPlaywrightTools, registerTraceRecordingPrompt, getPlaywrightTraceService, } from "./playwright/index.js";
+const oneClickEnabled = process.env.SKYRAMP_FEATURE_ONE_CLICK === "1";
+const oneClickInstructions = oneClickEnabled
+    ? `\n- When the user asks to comprehensively, thoroughly, or deeply test a specific endpoint: MUST call \`skyramp_one_click_tool\` with workflow \`test_given_endpoint_comprehensively\` first. Do NOT self-orchestrate the steps manually.\n- When the user asks to scan the full repo, recommend, generate, and execute top N tests: MUST call \`skyramp_one_click_tool\` with workflow \`full_repo_scan_recommend_generate_and_execute_top_n_tests\`.`
+    : "";
 const server = new McpServer({
     name: "Skyramp MCP Server",
     version: "1.0.0",
@@ -58,12 +63,10 @@ If the workspace root is a git repo AND \`.skyramp/workspace.yml\` does not exis
 Skip only if: not a git repo, \`.skyramp/workspace.yml\` already exists, or user explicitly declines.
   
 ## Rules
-- NEVER show CLI commands. ALWAYS use the MCP tools provided.
+- NEVER show CLI commands. NEVER attempt to install or configure the Skyramp CLI. ALWAYS use the MCP tools provided.
 - For UI and E2E tests, there are TWO recording modes:
   1. **AI-driven recording** (default): Use the browser_* tools (browser_navigate, browser_click, etc.) to record interactions, then call skyramp_export_zip to export the trace, then call skyramp_ui_test_generation with the zip path.
-  2. **Manual recording**: ONLY when the user explicitly says "manual recording", "record myself", "I will interact", or "Docker trace" — use skyramp_start_trace_collection / skyramp_stop_trace_collection to let the user interact with the browser themselves.
-- When the user asks to comprehensively, thoroughly, or deeply test a specific endpoint: MUST call \`skyramp_one_click_tool\` with workflow \`test_given_endpoint_comprehensively\` first. Do NOT self-orchestrate the steps manually.
-- When the user asks to scan the full repo, recommend, generate, and execute top N tests: MUST call \`skyramp_one_click_tool\` with workflow \`full_repo_scan_recommend_generate_and_execute_top_n_tests\`.
+  2. **Manual recording**: ONLY when the user explicitly says "manual recording", "record myself", "I will interact", or "Docker trace" — use skyramp_start_trace_collection / skyramp_stop_trace_collection to let the user interact with the browser themselves.${oneClickInstructions}
 
 ## Test Management Flow
 Use \`skyramp_analyze_changes\` as the single entry point for both test recommendations and test health analysis.
@@ -75,8 +78,8 @@ Use \`skyramp_analyze_changes\` as the single entry point for both test recommen
 ### Health Analysis (4-step)
 1. Call \`skyramp_analyze_changes\` with \`repositoryPath\` and \`scope\` → returns a \`stateFile\`.
 2. Call \`skyramp_analyze_test_health\` with \`stateFile\` → runs drift analysis + health scoring + LLM semantic assessment.
-3. (Optional) Call \`skyramp_execute_tests\` with \`stateFile\` → runs tests live to verify status.
-4. Call \`skyramp_actions\` with \`stateFile\` → executes UPDATE/REGENERATE/ADD recommendations.
+3. (Optional) Execute tests using \`skyramp_execute_test\` with \`stateFile\` param → validates test status live and writes results back to stateFile for health scoring.
+4. Call \`skyramp_actions\` with \`stateFile\` → executes UPDATE/REGENERATE/ADD recommendations (with execution-aware prioritization if step 3 ran).
 
 After \`skyramp_analyze_changes\`, inspect enriched data via MCP Resources (use the \`sessionId\` returned in the output):
 - \`skyramp://analysis/{sessionId}/summary\` — high-level overview
@@ -146,14 +149,15 @@ registerProgressResource(server);
 // Register unified test-management tools (replaces separate test-maintenance tools)
 registerAnalyzeChangesTool(server);
 registerAnalyzeTestHealthTool(server);
-registerExecuteTestsTool(server);
 registerActionsTool(server);
-registerStateCleanupTool(server);
 // Register workspace management tools
 registerInitScanWorkspaceTool(server);
 registerInitializeWorkspaceTool(server);
 // Register one-click orchestrated workflows
-registerOneClickTool(server);
+if (oneClickEnabled) {
+    registerOneClickTool(server);
+    logger.info("One-click tools enabled via SKYRAMP_FEATURE_ONE_CLICK");
+}
 // Register other Skyramp tools
 const infrastructureTools = [
     registerLoginTool,

package/build/playwright/traceRecordingPrompt.js

@@ -2,21 +2,24 @@
  * MCP prompt that guides the LLM through the Playwright-based trace recording
  * and Skyramp test generation flow.
  */
+import { z } from "zod";
 import { logger } from "../utils/logger.js";
-export function registerTraceRecordingPrompt(server) {
-    logger.info("Registering trace recording prompt");
-    server.registerPrompt("skyramp_trace_recording_prompt", {
-        description: "Guide for recording browser interactions as a Skyramp trace and generating UI tests",
-        argsSchema: {},
-    }, () => ({
-        messages: [
-            {
-                role: "user",
-                content: {
-                    type: "text",
-                    text: `## Skyramp UI Test Recording
+import { SKYRAMP_QA_PERSONA } from "../prompts/personas.js";
+export function getTraceRecordingPromptText(opts) {
+    const outputDir = opts?.outputDir;
+    const modularize = opts?.modularize ?? true;
+    const exportInstruction = outputDir
+        ? `Call \`skyramp_export_zip\` with \`outputPath\` set to \`${outputDir}/<test_name>_trace.zip\` (absolute path).`
+        : `Call \`skyramp_export_zip\` with \`outputPath\` set to the absolute zip path (same directory and base name as the test file, replacing \`.spec.ts\` with \`.zip\`).`;
+    const generateInstruction = modularize
+        ? `Call \`skyramp_ui_test_generation\` with \`playwrightInput\` set to the absolute zip path from the Export step.`
+        : `Call \`skyramp_ui_test_generation\` with \`playwrightInput\` set to the absolute zip path from step 5 and \`modularizeCode: false\`.`;
+    const modularizeNote = modularize
+        ? `- **After generating the test**, run \`skyramp_modularization\` for code quality.`
+        : `- Do NOT run \`skyramp_modularization\` — skip modularization in CI.`;
+    return `## Skyramp UI Test Recording
 
-You are a Skyramp Integration Architect. Your role is to record browser interactions with zero hallucination: every action must be grounded in what \`browser_snapshot\` returns. If an element is not visible in the snapshot, do not interact with it.
+${SKYRAMP_QA_PERSONA} For UI recording, every action must be grounded in what \`browser_snapshot\` returns. If an element is not visible in the snapshot, do not interact with it.
 
 ### Required workflow
 
@@ -28,25 +31,60 @@ Then execute in strict order:
 2. **Snapshot**: Call \`browser_snapshot\` to get the current ARIA tree and element refs.
 3. **Interact**: Call the appropriate tool (\`browser_click\`, \`browser_type\`, \`browser_hover\`, etc.) using refs from the snapshot.
 4. **Repeat steps 2–3** for each user action until all steps are complete.
-5. **Export**: Call \`skyramp_export_zip\` with \`outputPath\` set to the absolute zip path (same directory and base name as the test file, replacing \`.spec.ts\` with \`.zip\`). Do NOT ask the user first — call it automatically.
-6. **Generate**: Call \`skyramp_ui_test_generation\` with \`playwrightInput\` set to the absolute zip path from step 5.
+5. **Export**: ${exportInstruction} Do NOT ask the user first — call it automatically.
+6. **Generate**: ${generateInstruction}
 
 ### Cross-tool rules
 
 - **After every action that changes the page**, call \`browser_snapshot\` before the next interaction — refs become stale after navigation, clicks that trigger page updates, and form submissions.
 - **Iframe content** appears inline in the snapshot — interact with those elements using their refs normally.
 - **Trace deduplication**: if you retry from the start URL, only the last complete attempt is exported.
-- **After generating the test**, run \`skyramp_modularization\` for code quality.
+- **No Docker required**: the \`browser_*\` tools run a local browser session managed by the MCP server. Docker is ONLY used by \`skyramp_start_trace_collection\` (manual recording mode). Never suggest or check for Docker when using AI-driven recording.
+${modularizeNote}
 
 ### Assertions
-Call \`browser_assert\` when the user requests verification. Always provide the \`expected\` value.
+Call \`browser_assert\` when assertions are needed. Always provide the \`expected\` value.
 - \`type: "text"\` — verify an element contains expected text
 - \`type: "value"\` — verify an input field has an expected value
 
+When generating test code that uses \`expect\`, always import it from \`@skyramp/skyramp\`, never from \`@playwright/test\`:
+\`\`\`ts
+import { expect } from '@skyramp/skyramp';
+\`\`\`
+
+### Tips
+- **Custom dropdowns (Radix, MUI, etc.)**: click the combobox trigger → \`browser_snapshot\` → click the option. Do NOT use \`browser_select_option\` — it only works on native \`<select>\` elements.
+
 ### Constraints
-- Do NOT write JSONL or HAR files manually — \`skyramp_export_zip\` handles everything.
+- Do NOT write JSONL or HAR files manually — \`skyramp_export_zip\` reads the recorded trace, builds the JSONL action log and HAR, and packages them into the zip.
 - Do NOT reuse zip files from previous sessions — always record fresh.
-`,
+`;
+}
+export function registerTraceRecordingPrompt(server) {
+    logger.info("Registering trace recording prompt");
+    server.registerPrompt("skyramp_trace_recording_prompt", {
+        description: "Guide for recording browser interactions as a Skyramp trace and generating UI tests",
+        argsSchema: {
+            outputDir: z
+                .string()
+                .optional()
+                .describe("Directory where zip files should be written. Defaults to same directory as the test file."),
+            modularize: z
+                .boolean()
+                .default(true)
+                .optional()
+                .describe("Whether to run skyramp_modularization after generation. Default: true. Set to false in CI."),
+        },
+    }, (args) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: getTraceRecordingPromptText({
+                        outputDir: args.outputDir,
+                        modularize: args.modularize,
+                    }),
                 },
             },
         ],

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

@@ -1,4 +1,4 @@
-import { getPersonaPrefix } from "../architectPersona.js";
+import { getPersonaPrefix } from "../personas.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:

package/build/prompts/personas.js

@@ -0,0 +1,19 @@
+/**
+ * Skyramp personas injected into tool descriptions and prompts.
+ *
+ * In TestBot environments (ENABLE_SKYRAMP_TESTBOT=true), the persona is injected
+ * once as a system prompt via `claude --system-prompt` rather than repeating it in
+ * every tool description. In that case getPersonaPrefix() returns empty string
+ * to avoid wasting context tokens.
+ *
+ * In IDE/MCP-direct environments, it is included in each tool description so the
+ * model has the role context available without a separate system prompt.
+ */
+export const SKYRAMP_QA_PERSONA = `You are acting as a Skyramp QA Automation Engineer. Your responsibility is to translate user test intent into precise, deterministic test artifacts — whether generating API tests from specs, recording browser interactions for UI flows, or maintaining existing test suites. Derive all parameters strictly from the codebase, workspace config, API schemas, and page snapshots. Never guess or hallucinate values.`;
+/**
+ * Returns the persona prefix for use in tool descriptions.
+ * Returns an empty string when running inside TestBot (persona is injected via system prompt instead).
+ */
+export function getPersonaPrefix() {
+    return process.env.SKYRAMP_FEATURE_TESTBOT ? '' : `${SKYRAMP_QA_PERSONA}\n\n`;
+}

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

@@ -1,6 +1,6 @@
 import { buildDriftScoringGuide, buildActionDecisionMatrix, buildBreakingChangePatterns, buildTestAssessmentGuidelines, buildAddRecommendationGuidelines, buildDriftOutputChecklist, buildUpdateExecutionRules, } from "./driftAnalysisSections.js";
 export function buildDriftAnalysisPrompt(params) {
-    const { existingTests, parsedDiff, scannedEndpoints, repositoryPath, stateFile } = params;
+    const { existingTests, parsedDiff, scannedEndpoints, repositoryPath, stateFile, routerMountContext, candidateRouteFiles } = params;
     const inlineMode = !stateFile;
     // Detect new endpoints count from parsedDiff
     let newEndpointCount = 0;
@@ -30,6 +30,7 @@ No existing Skyramp tests found in repository.
 `;
     const scannedSection = scannedEndpoints.length > 0
         ? `## Scanned Endpoints (${scannedEndpoints.length})
+Note: paths below come from static analysis and may be incomplete for nested resources or unsupported frameworks. Use the Routing entry-point files section below to verify and reconstruct full paths.
 ${scannedEndpoints.map((ep) => {
             let methods;
             if (Array.isArray(ep.methods)) {
@@ -40,6 +41,19 @@ ${scannedEndpoints.map((ep) => {
             }
             return `- ${methods} ${ep.path}`;
         }).join("\n")}
+`
+        : "";
+    const mountSection = routerMountContext?.length
+        ? `## Routing entry-point files
+Read these to trace the full router/module hierarchy when verifying endpoint paths:
+${routerMountContext.map(f => `- \`${f}\``).join("\n")}
+`
+        : "";
+    const hasJavaFiles = candidateRouteFiles?.some(f => /\.(java|kt)$/.test(f)) ?? false;
+    const candidateFilesSection = candidateRouteFiles && candidateRouteFiles.length > 0
+        ? `## Route Files (read these to find endpoints from any framework)
+${candidateRouteFiles.map(f => `- ${f}`).join("\n")}
+${hasJavaFiles ? "Note — Java Spring: full URL = class-level `@RequestMapping` prefix + method-level path. If the prefix is a constant reference (e.g. `@RequestMapping(Url.PAGE_URL)`), find the constant — same file, inner class, or a separate `Url.java` — and resolve it (including `+` concatenation)." : ""}
 `
         : "";
     // In inline mode (testbot), skip the context header — existing tests and diff
@@ -54,7 +68,9 @@ ${scannedEndpoints.map((ep) => {
 
 ${diffSection}
 ${testListSection}
-${scannedSection}`;
+${scannedSection}
+${mountSection}
+${candidateFilesSection}`;
     if (inlineMode) {
         // Testbot inline mode: all maintenance logic lives here so the testbot
         // prompt only orchestrates steps without duplicating rules.

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

@@ -1,4 +1,44 @@
 import { AnalysisScope } from "../../types/RepositoryAnalysis.js";
+// File extensions that indicate a frontend-only file — no API route definitions.
+// Uses extensions rather than path-segment patterns so backend files named
+// e.g. Spring /services/Foo.java or Gin handlers/main.go are not misclassified.
+// Keep this narrow: .json/.md can contain backend-affecting artifacts (OpenAPI specs,
+// config, API docs) and would incorrectly classify a PR as UI-only.
+const FRONTEND_EXT = /\.(tsx?|jsx?|vue|svelte|css|scss|less|html|svg)$/i;
+/**
+ * Returns a Step 1.5 instruction block that forces the LLM to read the
+ * entry-point files from the Router Mounting section and build an authoritative
+ * file→full-prefix table before touching any endpoint URLs.
+ * 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):
+- 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
+- Go (Gin/Echo/Chi): \`r.Group('/path')\`, \`r.Mount('/path', sub)\`
+- Ruby (Rails): \`namespace\`, \`scope\`, \`resources ... do\`
+- Django: \`path('prefix/', include(urls))\`
+
+Chain all segments from the app root down through every intermediate mount to each leaf router file. Build a table:
+
+| Source file | Full URL prefix |
+|-------------|----------------|
+| (leaf router file) | (fully chained prefix, e.g. /api/v1/products/{id}/reviews) |
+
+**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.
+
+`;
+}
+// Inline note added to any step where the LLM reads Java source files. Java Spring
+// has no router-mounting file — each controller defines its own class-level prefix,
+// and that prefix may reference a constant defined elsewhere.
+const JAVA_SPRING_NOTE = `For Java Spring: full URL = class-level \`@RequestMapping\` prefix + method-level path. If the prefix is a constant reference (e.g. \`@RequestMapping(Url.PAGE_URL)\`), find the constant — same file, inner class, or a separate \`Url.java\` — and resolve it (including \`+\` concatenation).`;
 function buildEnrichmentInstructions(p) {
     const isDiffScope = p.analysisScope === AnalysisScope.CurrentBranchDiff;
     const useHealthFlow = p.nextTool === "skyramp_analyze_test_health";
@@ -16,38 +56,59 @@ The ranked test recommendation catalog is pre-built and shown below (after the s
 3. Do NOT call any Skyramp generation tools. The catalog shows ready-to-use tool calls that can be executed on demand.
 
 **If** Steps 1–2 revealed additional scenarios the catalog does not cover (e.g. a computed formula or FK relationship that was missed), you may optionally call \`skyramp_recommend_tests\` with \`stateFile: "${p.stateFile ?? p.sessionId}"\` and \`enrichedScenarios\` to regenerate a more complete catalog — but only after presenting the current one.`;
+        const hasJavaFiles = p.candidateRouteFiles?.some(f => /\.(java|kt)$/.test(f)) ?? false;
+        const routeFilesSection = p.candidateRouteFiles && p.candidateRouteFiles.length > 0
+            ? `\nRoute/controller files found by static scan (read these to discover endpoints — the regex-based catalog below may be incomplete for your framework):\n${p.candidateRouteFiles.map(f => `- ${f}`).join("\n")}\n`
+            : "";
+        const resolvePathsNote = p.routerMountContext.length
+            ? `**Resolve nested paths** using your Step 1.5 table — a router in the table with prefix \`/api/v1/products/{product_id}/reviews\` means every endpoint in that file lives under that full path.`
+            : `**Resolve full paths** using the prefixes you identified in Step 1 (e.g. Java Spring class-level \`@RequestMapping\` prefix + method-level path).`;
         return `## Your Task — Fill in and Present the Catalog (full repo)
 
 ### Step 1: Read key files
-Read route/controller files and model/schema files (Pydantic models, Zod schemas, DTOs)
-to find: required request body fields, computed response fields and formulas, auth middleware type, storage backend, and how sub-routers are mounted (cross-check against Router Mounting section above).
+${routeFilesSection}Read the route/controller files above **and** model/schema files (Pydantic models, Zod schemas, DTOs) to find: required request body fields, computed response fields and formulas, auth middleware type, storage backend, and how sub-routers are mounted (cross-check against Router Mounting section above).
+${hasJavaFiles ? JAVA_SPRING_NOTE : ""}
+If the endpoint catalog below is missing endpoints visible in these files (e.g. from a framework the static scanner doesn't recognise), extract them now and include them in Step 3's \`enrichedScenarios\`.
 
-### Step 2: Map cross-resource relationships and resolve endpoint paths
+${buildPathResolutionTableStep(p)}### Step 2: Map cross-resource relationships and resolve endpoint paths
 (Distinct from Step 1 — Step 1 reads individual schemas; Step 2 maps how endpoints relate to each other.)
 For each endpoint: which POST creates resources consumed by other endpoints?
-**Resolve nested paths** from the Router Mounting section — a router mounted at \`/products/{product_id}/reviews\` means \`GET /\` in that file is actually \`GET /api/v1/products/{product_id}/reviews\`.
+${resolvePathsNote}
 For GET list endpoints: identify query params (\`limit\`, \`offset\`, \`order\`, \`orderBy\`) from framework annotations (FastAPI \`Query()\`, Express \`req.query\`, etc.).
 
 ${nextStep}`;
     }
     const changedFiles = p.parsedDiff?.changedFiles.join(", ") ?? "";
-    const hasApiEndpoints = p.parsedDiff && (p.parsedDiff.newEndpoints.length > 0 || p.parsedDiff.modifiedEndpoints.length > 0);
-    const isUIOnly = !hasApiEndpoints && (p.parsedDiff?.changedFiles.every(f => !f.match(/\/(api|routes?|controllers?|routers?|handlers?|endpoints?)\//)) ?? false);
-    const step2 = hasApiEndpoints
-        ? `### Step 2: Discover related endpoints
-Read handler code for the changed endpoints and their model/schema files (Zod schemas,
-Pydantic models, DTOs) to understand request/response shapes. Find related endpoints via
-imports, shared models, adjacent route files. Resolve nested/sub-router paths from Router
-Mounting context.
+    // Whether the regex pre-detected any API endpoints — used as a hint only.
+    // Step 2 always asks the LLM to extract endpoints from the diff so unknown
+    // frameworks (e.g. Spring class-level @RequestMapping, Django, Rails) are
+    // covered even when the static regex returns nothing.
+    const regexFoundEndpoints = p.parsedDiff && (p.parsedDiff.newEndpoints.length > 0 || p.parsedDiff.modifiedEndpoints.length > 0);
+    const diffFiles = p.parsedDiff?.changedFiles ?? [];
+    const isUIOnly = diffFiles.length > 0 &&
+        !regexFoundEndpoints &&
+        diffFiles.every(f => FRONTEND_EXT.test(f));
+    const diffHasJavaFiles = diffFiles.some(f => /\.(java|kt)$/.test(f));
+    const diffSection = p.diffContent
+        ? `\n<diff>\n${p.diffContent}\n</diff>`
+        : "";
+    const step2 = isUIOnly
+        ? `### Step 2: Identify consumed API endpoints
+UI-only PR — read changed components to find API calls (fetch, axios, hooks).`
+        : p.diffContent
+            ? `### Step 2: Extract new and modified API endpoints from the diff
+Read the \`<diff>\` above and identify every new or modified API endpoint — route registrations, handler methods, controller annotations. Then use the **Router Mounting / Nesting** section above to reconstruct the full URL path for each endpoint by chaining all parent router prefixes down to the handler (e.g. a handler in a file with \`prefix="/reviews"\` that is mounted at \`/{product_id}\` under a router mounted at \`/api/v1/products\` → full path \`/api/v1/products/{product_id}/reviews\`).
+${diffHasJavaFiles ? JAVA_SPRING_NOTE : ""}
+For each endpoint found: note the HTTP method, full path, and source file.
+${regexFoundEndpoints ? "The static analysis above pre-detected some endpoints — verify and augment with anything it missed." : "The static analysis did not detect endpoints for this framework — rely on the diff to extract them."}
 **CRITICAL — Query params vs body:** For GET endpoints (especially search/filter/list),
 identify which parameters are URL query params vs request body. Look at framework-specific
 annotations (FastAPI \`Query()\`, Express \`req.query\`, Spring \`@RequestParam\`, etc.).
 Pass these as \`queryParams\` (not \`requestBody\`) when generating scenarios.`
-        : isUIOnly
-            ? `### Step 2: Identify consumed API endpoints
-UI-only PR — read changed components to find API calls (fetch, axios, hooks).`
-            : `### Step 2: Identify affected endpoints
-No API route changes detected — read changed files to identify affected endpoints.`;
+            : `### Step 2: Extract new and modified API endpoints from source files
+No diff was available — read the changed source files listed above directly to identify new or modified API endpoints. Use the **Router Mounting / Nesting** section to reconstruct full paths.
+${diffHasJavaFiles ? JAVA_SPRING_NOTE : ""}
+For each endpoint found: note the HTTP method, full path, and source file.`;
     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
@@ -88,10 +149,10 @@ Call \`skyramp_recommend_tests\` with:
 - \`enrichedScenarios\`: (optional) JSON array of your Step 3 scenarios — see the tool's inputSchema for the exact shape. Your enriched scenarios override server-side ones with the same \`scenarioName\` and are prioritized in ranking. Omit if you drafted nothing in Step 3.`;
     return `## Your Task — Enrich & Recommend (PR-scoped)
 
-### Step 1: Read the changed files
-${changedFiles}
+### Step 1: Read the changed files and diff
+${changedFiles}${diffSection}
 
-${step2}
+${buildPathResolutionTableStep(p)}${step2}
 
 ${criticalPatternStep}
 
@@ -103,13 +164,11 @@ export function buildAnalysisOutputText(p) {
     // 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
+    const routerSection = !p.wsSchemaPath && p.routerMountContext.length
         ? `
-## Router Mounting / Nesting
-\`\`\`
-${p.routerMountContext}
-\`\`\`
-Use this to resolve full URL paths for nested endpoints.`
+## Routing entry-point files
+Read these in Step 1.5 to trace the full router/module hierarchy:
+${p.routerMountContext.map(f => `- \`${f}\``).join("\n")}`
         : "";
     const enrichment = buildEnrichmentInstructions(p);
     return `# Repository Analysis

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

@@ -156,9 +156,10 @@ When no Playwright trace exists, use the Playwright browser tools (\`browser_nav
 recommend a different test that adds new coverage.`;
 }
 export function buildVerificationChecklist(topN, maxGen) {
+    const minTotal = Math.min(maxGen + 1, topN);
     return `<verification>
 Before finalizing your output, verify:
-1. **Count**: Total recommendation count equals exactly ${topN} (${maxGen} GENERATE + ${topN - maxGen} ADDITIONAL). Not fewer.
+1. **Count**: Total recommendation count equals the total you stated in your Budget Plan (between ${minTotal} and ${topN}). Your GENERATE + ADDITIONAL counts must match the split you committed to. Not fewer than your stated Budget Plan total.
 2. **Distinct paths**: Each GENERATE item targets a distinct code path — no two share the same HTTP method + endpoint + expected status.
 3. **Auth parameters are consistent** across all tool calls (same authHeader and authScheme).
 4. Every endpointURL includes both the base URL and the path (not just the base, e.g. \`http://host/api/v1/orders/{id}\`).
@@ -334,7 +335,7 @@ ${PATH_PARAM_UUID_GUIDANCE}
 3. Interact using \`browser_click\`, \`browser_type\`, \`browser_fill_form\`, etc.
 4. \`browser_snapshot\` after each interaction that changes the page
 5. \`skyramp_export_zip\` with an **absolute** output path: \`<repositoryPath>/.skyramp/<test_name>_trace.zip\`
-6. \`skyramp_ui_test_generation\` with \`playwrightInput\` = the **absolute** path of the exported zip
+6. \`skyramp_ui_test_generation\` with \`playwrightInput\` = the **absolute** path of the exported zip, and \`outputDir\` = the **frontend** service's \`testDirectory\` from workspace.yml (e.g. \`frontend/tests\`). Do NOT use the backend service's testDirectory — UI tests must go in the frontend service's test directory.
 
 Tips: For custom dropdowns (Radix, MUI): click combobox → snapshot → click option (NOT \`browser_select_option\`).
 

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

@@ -158,7 +158,11 @@ export function registerRecommendTestsPrompt(server) {
         if (!fullAnalysis) {
             throw new Error(`Analysis data for session not found in memory or on disk. Re-run skyramp_analyze_changes.`);
         }
-        const analysisScope = state.analysisScope === "branch_diff"
+        // Normalize legacy state files: before AnalysisScope enum normalization, state stored
+        // the user-facing param value "branch_diff". Map it explicitly so diff-mode detection
+        // works correctly on state created before this deployment (2-hour TTL window).
+        const rawScope = state.analysisScope;
+        const analysisScope = rawScope === "branch_diff" || rawScope === AnalysisScope.CurrentBranchDiff
             ? AnalysisScope.CurrentBranchDiff
             : AnalysisScope.FullRepo;
         const effectiveTopN = args.topN;