@skyramp/mcp 0.1.4 → 0.1.6

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

@@ -4,9 +4,11 @@ import { WorkspaceAuthType, getDefaultAuthHeader, AUTH_MIDDLEWARE_PATTERNS_STR }
 import { logger } from "../../utils/logger.js";
 import { extractResourceFromPath } from "../../utils/routeParsers.js";
 import { buildArchitectPreamble, buildContextFetchingGuidance, buildReasoningProtocol, buildToolWorkflows, buildTestPatternGuidelines, buildTestQualityCriteria, buildFewShotExamples, buildVerificationChecklist, buildGenerationRules, getAuthSnippets, MAX_TESTS_TO_GENERATE, MAX_RECOMMENDATIONS, MAX_CRITICAL_TESTS, } from "./recommendationSections.js";
-import { CATEGORY_PRIORITY, PRIORITY_TIER_ORDER, TEST_CATEGORIES } from "../../types/TestRecommendation.js";
+import { CATEGORY_PRIORITY, TEST_CATEGORIES } from "../../types/TestRecommendation.js";
 import { buildScopeAssessmentSection, isFrontendFile } from "./scopeAssessment.js";
-import { resolveServiceDetailsRef } from "../../utils/featureFlags.js";
+import { resolveServiceDetailsRef } from "../../utils/utils.js";
+// Cached at module-load — flag is process-wide and cannot change per call.
+const SERVICE_REFS = resolveServiceDetailsRef();
 function formatTestLocations(locs) {
     const entries = Object.entries(locs || {});
     if (entries.length === 0)
@@ -27,8 +29,8 @@ function formatTestLocations(locs) {
 // Categories map to HIGH / MEDIUM / LOW tiers.
 // Within a tier, novelty (new > modified > existing) breaks ties,
 // then cross-resource, step count, and finally the deterministic SHA-256 seed.
-// Single source of truth for priority ordering — imported from types.
-const PRIORITY_ORDER = PRIORITY_TIER_ORDER;
+// CATEGORY_PRIORITY and PriorityTier imported from ../../types/TestRecommendation.js
+const PRIORITY_ORDER = { CRITICAL: 4, HIGH: 3, MEDIUM: 2, LOW: 1 };
 const NOVELTY_ORDER = { new: 3, modified: 2, existing: 1 };
 function classifyNovelty(scenario, diffContext) {
     if (!diffContext)
@@ -134,6 +136,12 @@ function buildExternalCoverageSet(testLocations) {
 }
 // ── Execution Plan (replaces pre-ranked + scenarios + heuristic sections) ──
 function buildFullRepoRecommendations(scored, topN, baseUrl, authHeaderValue, authSchemeSnippet, authTypeValue, isFrontendProject = false, isFrontendOnlyProject = false, externalCoverage = new Set()) {
+    // Full-repo mode only — percentage-based UI/E2E slot targets (15% each, floor 1).
+    const rawE2E = isFrontendProject ? Math.max(1, Math.round(topN * 0.15)) : 0;
+    const rawUI = isFrontendProject ? Math.max(1, Math.round(topN * 0.15)) : 0;
+    const slotsFloor = Math.floor(topN / 2);
+    const minE2ESlots = Math.min(rawE2E, slotsFloor);
+    const minUISlots = Math.min(rawUI, Math.max(0, topN - minE2ESlots));
     const authRef = authHeaderValue
         ? `, authHeader: "${authHeaderValue}"${authSchemeSnippet}`
         : `, authHeader: <check OpenAPI securitySchemes or auth middleware; "" if confirmed unauthenticated>`;
@@ -162,9 +170,11 @@ function buildFullRepoRecommendations(scored, topN, baseUrl, authHeaderValue, au
             return true;
         })
         : scored;
-    // All backend slots — UI/E2E split is determined by the LLM's Budget Plan
-    // (via buildScopeAssessmentSection), not by hardcoded percentage allocation.
-    const allItems = scoredFiltered.slice(0, topN);
+    // For full-stack repos, carve out E2E and UI slots before filling with backend tests.
+    const backendSlotCount = isFrontendProject
+        ? Math.max(0, topN - minE2ESlots - minUISlots)
+        : topN;
+    const allItems = scoredFiltered.slice(0, backendSlotCount);
     const byType = new Map();
     for (const t of TYPE_ORDER)
         byType.set(t, []);
@@ -188,7 +198,7 @@ function buildFullRepoRecommendations(scored, topN, baseUrl, authHeaderValue, au
             return [
                 `**${rank}. ${title}**`,
                 `  ${s.description}`,
-                `  ${step.method} ${step.path}${step.expectedStatusCode ? ` \u2192 ${step.expectedStatusCode}` : ""}`,
+                `  ${step.method} ${step.path} \u2192 ${step.expectedStatusCode}`,
                 `  Tool: \`skyramp_contract_test_generation({ endpointURL: "${endpointURL}", method: "${step.method}"${authRef}${dataParam} })\``,
                 `  From source: fill in requestData field names and the specific production boundary this validates`,
             ].join("\n");
@@ -197,7 +207,7 @@ function buildFullRepoRecommendations(scored, topN, baseUrl, authHeaderValue, au
             const stepLines = s.steps.map(st => {
                 const isBody = ["POST", "PUT", "PATCH"].includes(st.method);
                 const bodyHint = isBody ? ` \u2014 body: <${st.method} ${st.path} required fields from source>` : "";
-                return `  ${st.order}. ${st.method} ${st.path}${st.expectedStatusCode ? ` \u2192 ${st.expectedStatusCode}` : ""}: ${st.description}${bodyHint}`;
+                return `  ${st.order}. ${st.method} ${st.path} \u2192 ${st.expectedStatusCode}: ${st.description}${bodyHint}`;
             }).join("\n");
             const isTraceBased = testType === "e2e" || testType === "ui";
             let toolCallsBlock;
@@ -243,7 +253,7 @@ function buildFullRepoRecommendations(scored, topN, baseUrl, authHeaderValue, au
                             dataParam = `, requestBody: <${st.method} ${st.path} required fields from source code>`;
                         }
                     }
-                    return `    { method: "${st.method}", path: "${st.path}"${st.expectedStatusCode ? `, statusCode: ${st.expectedStatusCode}` : ""}${dataParam} }`;
+                    return `    { method: "${st.method}", path: "${st.path}", statusCode: ${st.expectedStatusCode}${dataParam} }`;
                 }).join(",\n");
                 toolCallsBlock = [
                     `  skyramp_batch_scenario_test_generation({ scenarioName: "${s.scenarioName}", destination: "${destinationHost}", baseURL: "${baseUrl}"${scenarioAuthRef}, steps: [\n${batchSteps}\n  ] })`,
@@ -275,11 +285,55 @@ function buildFullRepoRecommendations(scored, topN, baseUrl, authHeaderValue, au
         const entries = items.map((item, i) => renderItem(item, globalRank + i + 1)).join("\n\n");
         return `### ${label} (${items.length})\n\n${entries}`;
     });
-    const sections = backendSections.join("\n\n");
+    // Pre-allocate E2E and UI placeholder sections for full-stack repos.
+    const e2eSectionParts = [];
+    const uiSectionParts = [];
+    if (isFrontendProject) {
+        for (let i = 0; i < minE2ESlots; i++) {
+            const rank = i + 1;
+            e2eSectionParts.push(`**${rank}. E2E User Journey ${i + 1}**\n` +
+                `  End-to-end test covering a complete user journey through the frontend and backend.\n` +
+                `  To generate: record a browser trace, then call the generation tool.\n` +
+                `    browser_navigate({ url: "${baseUrl}" }) \u2192 exercise key user flow \u2192 skyramp_export_zip({ outputPath: "<repo>/.skyramp/e2e_journey_${i + 1}.zip" })\n` +
+                `  Tool: \`skyramp_e2e_test_generation({ playwrightInput: "<repo>/.skyramp/e2e_journey_${i + 1}.zip"${authHeaderOnlyRef} })\`\n` +
+                `  From source: read frontend components and their API calls to identify the highest-value user journey`);
+        }
+        for (let i = 0; i < minUISlots; i++) {
+            const rank = minE2ESlots + i + 1;
+            uiSectionParts.push(`**${rank}. UI Component Test ${i + 1}**\n` +
+                `  Test key UI component interactions and state changes.\n` +
+                `  To generate: record a browser trace, then call the generation tool.\n` +
+                `    browser_navigate({ url: "${baseUrl}" }) \u2192 interact with UI components \u2192 skyramp_export_zip({ outputPath: "<repo>/.skyramp/ui_component_${i + 1}.zip" })\n` +
+                `  Tool: \`skyramp_ui_test_generation({ playwrightInput: "<repo>/.skyramp/ui_component_${i + 1}.zip"${authHeaderOnlyRef} })\`\n` +
+                `  From source: read frontend component files to identify interactions, form submissions, and state transitions`);
+        }
+        // Offset backend section ranks by the number of E2E + UI placeholders
+        const offset = minE2ESlots + minUISlots;
+        backendSections.forEach((_, idx) => {
+            const t = TYPE_ORDER.filter(t => (byType.get(t) ?? []).length > 0)[idx];
+            if (!t)
+                return;
+            const items = byType.get(t);
+            const label = TYPE_LABEL[t];
+            let globalRank = offset;
+            for (const prev of TYPE_ORDER) {
+                if (prev === t)
+                    break;
+                globalRank += (byType.get(prev) ?? []).length;
+            }
+            backendSections[idx] = `### ${label} (${items.length})\n\n${items.map((item, i) => renderItem(item, globalRank + i + 1)).join("\n\n")}`;
+        });
+    }
+    const allSections = [
+        ...(e2eSectionParts.length > 0 ? [`### E2E (${e2eSectionParts.length})\n\n${e2eSectionParts.join("\n\n")}`] : []),
+        ...(uiSectionParts.length > 0 ? [`### UI (${uiSectionParts.length})\n\n${uiSectionParts.join("\n\n")}`] : []),
+        ...backendSections,
+    ];
+    const sections = allSections.join("\n\n");
     const frontendTierNote = isFrontendOnlyProject
-        ? `\n\n**Frontend repo:** add E2E and UI tests only — no integration or contract tests. The number of each is determined by the UI/E2E percentage you committed to in your Budget Plan above.`
+        ? `\n\n**Frontend repo:** supplement MUST include at least ${minE2ESlots} E2E test${minE2ESlots > 1 ? "s" : ""} (\`skyramp_e2e_test_generation\`) and at least ${minUISlots} UI test${minUISlots > 1 ? "s" : ""} (\`skyramp_ui_test_generation\`). Do NOT add integration or contract tests.`
         : isFrontendProject
-            ? `\n\n**Full-stack repo:** add E2E and UI tests alongside backend tests. Fill your Budget Plan's UI/E2E percentage first, then use remaining slots for backend tests (Tiers 1-4 above).`
+            ? `\n\n**Full-stack repo:** supplement MUST include at least ${minE2ESlots} E2E test${minE2ESlots > 1 ? "s" : ""} (\`skyramp_e2e_test_generation\`) and at least ${minUISlots} UI test${minUISlots > 1 ? "s" : ""} (\`skyramp_ui_test_generation\`). Add these before exhausting backend tiers.`
             : "";
     const repoSupplementNote = supplementCount > 0
         ? `
@@ -306,9 +360,9 @@ function buildFullRepoRecommendations(scored, topN, baseUrl, authHeaderValue, au
 </supplement_guidance>`
         : "";
     const typeMixText = isFrontendOnlyProject
-        ? `This is a frontend repo. Focus on E2E and UI tests only. Do NOT add integration or contract tests. Split between E2E and UI based on the percentage in your Budget Plan above.`
+        ? `This is a frontend repo. Focus on E2E and UI tests only. Include at least ${minE2ESlots} E2E test${minE2ESlots > 1 ? "s" : ""} (\`skyramp_e2e_test_generation\`) and at least ${minUISlots} UI test${minUISlots > 1 ? "s" : ""} (\`skyramp_ui_test_generation\`). Do NOT add integration or contract tests.`
         : isFrontendProject
-            ? `This is a full-stack repo. Coverage ranking: E2E > UI > Integration > Contract. Use \`skyramp_e2e_test_generation\` for E2E and \`skyramp_ui_test_generation\` for UI tests. Split between frontend and backend tests based on the percentage in your Budget Plan above.`
+            ? `This is a full-stack repo. Coverage ranking: E2E > UI > Integration > Contract. Include at least ${minE2ESlots} E2E test${minE2ESlots > 1 ? "s" : ""} (\`skyramp_e2e_test_generation\`) and at least ${minUISlots} UI test${minUISlots > 1 ? "s" : ""} (\`skyramp_ui_test_generation\`), in addition to backend integration and contract tests.`
             : `Focus on integration and contract tests for all API endpoints.`;
     return `## Test Recommendations — ${topN} total (grouped by test type)
 
@@ -337,7 +391,7 @@ Before filling in tool call parameters for each item, use the analysis data alre
 - Computed/derived response fields and their formulas — assert exact values; read source for formula details not captured in the analysis
 - Auth middleware — set authHeader/authScheme from the repository context above; FastAPI HTTPBearer → 403 not 401
 - Storage backend — if Redis or schema-less, discard unique-constraint and cascade-delete scenarios
-- Delete behavior — read the route handler to determine actual response code (hard-delete may use 204, soft-delete/cancel may use 200)
+- Delete behavior — hard-delete → 204; soft-delete/cancel → 200
 
 ${buildTestQualityCriteria()}
 
@@ -351,6 +405,16 @@ ${buildTestQualityCriteria()}
 </enrichment_notes>`;
 }
 function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValue, authSchemeSnippet, authTypeValue, seed, endpointCount, isUIOnlyPR, hasFrontendChanges = false, hasTraces = false, externalCoverage = new Set(), relevantExternalTestPaths = []) {
+    const frontendUrl = "<frontend_url>";
+    // Slot allocation:
+    // - UI-only PR: all GENERATE slots are UI placeholders (no pre-ranked backend scenarios)
+    // - Mixed PR:   last GENERATE slot is a UI placeholder; remaining slots are backend
+    // - Backend-only PR: all GENERATE slots are backend scenarios
+    const backendGenerateCount = isUIOnlyPR
+        ? 0
+        : hasFrontendChanges
+            ? Math.max(0, maxGen - 1)
+            : maxGen;
     // Filter out scenarios whose primary method + resource + test type is already covered by external tests.
     // Method-aware: an external test covering GET /orders won't block PUT /orders scenarios.
     // This is the programmatic complement to the prompt-level Step 0 dedup instructions.
@@ -364,10 +428,8 @@ function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValue, auth
             return true;
         })
         : scored;
-    // All pre-ranked backend scenarios go into GENERATE slots (up to maxGen).
-    // UI/E2E split is determined by the LLM's Budget Plan — not hardcoded here.
-    const generateItems = scoredAfterExternalDedup.slice(0, Math.min(maxGen, scoredAfterExternalDedup.length));
-    const rawAdditionalItems = scoredAfterExternalDedup.slice(maxGen, topN);
+    const generateItems = scoredAfterExternalDedup.slice(0, Math.min(backendGenerateCount, scoredAfterExternalDedup.length));
+    const rawAdditionalItems = scoredAfterExternalDedup.slice(backendGenerateCount, topN);
     // Filter additional items whose primary resource + test type already appear in GENERATE
     const generatedCoverage = new Set(generateItems.map(item => scenarioCoverageKey(item.scenario)));
     const additionalItems = rawAdditionalItems.filter(item => !generatedCoverage.has(scenarioCoverageKey(item.scenario)));
@@ -380,10 +442,47 @@ function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValue, auth
         : authHeaderValue
             ? `, authHeader: "${authHeaderValue}"`
             : `, authHeader: <check OpenAPI securitySchemes or auth middleware; "" if confirmed unauthenticated>`;
-    // UI-only PR: provide guidance template for the LLM to derive UI tests from changed files.
-    // The LLM's Budget Plan (100% UI for UI-only PRs) determines how many to generate.
-    const uiOnlyGenerateGuidance = isUIOnlyPR
-        ? `**UI-only PR — derive ${maxGen} UI tests from changed frontend files.**\nEach test must target a distinct changed component or user flow. Use \`skyramp_ui_test_generation\` to generate each test.`
+    // UI-only: all GENERATE slots are UI test placeholders (one per changed component/flow)
+    const uiGenerateBlocks = isUIOnlyPR
+        ? Array.from({ length: maxGen }, (_, i) => {
+            const rank = i + 1;
+            const zipPath = `<repositoryPath>/.skyramp/ui_test_${rank}_trace.zip`;
+            return hasTraces
+                ? (`**#${rank} — GENERATE** | ui | workflow | new\n` +
+                    `Scenario: ui-test-from-trace-${rank} (rename from the actual changed component/flow)\n` +
+                    `Validates: UI interactions for a changed frontend component or flow.\n\n` +
+                    `**Tool**: \`skyramp_ui_test_generation({ playwrightInput: "<discovered_trace_file_path>", outputDir: "<frontend_output_dir>" })\` — set \`outputDir\` to ${SERVICE_REFS.frontendTestDirRef}`)
+                : (`**#${rank} — GENERATE** | ui | workflow | new\n` +
+                    `Scenario: ui-test-for-changed-component-${rank} (rename from the actual changed component/flow)\n` +
+                    `Validates: UI interactions for changed frontend component/flow ${rank}.\n\n` +
+                    `**Tool workflow:**\n` +
+                    `  1. \`browser_navigate({ url: "${frontendUrl}" })\`\n` +
+                    `  2. Interact with the changed component (read the diff to identify which component changed and what interactions it supports)\n` +
+                    `  3. \`browser_snapshot()\` after each key interaction\n` +
+                    `  4. \`skyramp_export_zip({ outputPath: "${zipPath}" })\` — absolute path\n` +
+                    `  5. \`skyramp_ui_test_generation({ playwrightInput: "${zipPath}", outputDir: "<frontend_output_dir>" })\` — set \`outputDir\` to ${SERVICE_REFS.frontendTestDirRef}\n\n` +
+                    `Each item must target a distinct changed component or user flow.`);
+        }).join("\n\n")
+        : "";
+    // Mixed PR: reserve the last GENERATE slot for a UI test for the changed frontend components.
+    // Guard: skip when maxGen=0 (caller explicitly requested no generation)
+    const uiRank = generateItems.length + 1;
+    const uiPlaceholderBlock = (hasFrontendChanges && !isUIOnlyPR && maxGen > 0)
+        ? hasTraces
+            ? (`**#${uiRank} — GENERATE** | ui | workflow | new\n` +
+                `Scenario: ui-test-for-changed-components (rename from the actual changed component/flow)\n` +
+                `Validates: UI interactions for the changed frontend components in this PR.\n\n` +
+                `**Tool**: \`skyramp_ui_test_generation({ playwrightInput: "<discovered_trace_file_path>", outputDir: "<frontend_output_dir>" })\` — set \`outputDir\` to ${SERVICE_REFS.frontendTestDirRef}`)
+            : (`**#${uiRank} — GENERATE** | ui | workflow | new\n` +
+                `Scenario: ui-test-for-changed-components (rename from the actual changed component/flow)\n` +
+                `Validates: UI interactions for the changed frontend components in this PR.\n\n` +
+                `**Tool workflow:**\n` +
+                `  1. \`browser_navigate({ url: "${frontendUrl}" })\`\n` +
+                `  2. Interact with the changed component (read the diff to identify which component changed and what interactions it supports)\n` +
+                `  3. \`browser_snapshot()\` after each key interaction\n` +
+                `  4. \`skyramp_export_zip({ outputPath: "<repositoryPath>/.skyramp/ui_mixed_pr_trace.zip" })\` — absolute path\n` +
+                `  5. \`skyramp_ui_test_generation({ playwrightInput: "<repositoryPath>/.skyramp/ui_mixed_pr_trace.zip", outputDir: "<frontend_output_dir>" })\` — set \`outputDir\` to ${SERVICE_REFS.frontendTestDirRef}\n\n` +
+                `Derive scenario name and steps from the actual changed frontend files.`)
         : "";
     const generateBlocks = generateItems.map((item, i) => {
         const rank = i + 1;
@@ -400,7 +499,7 @@ function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValue, auth
                 ? `\n  authHeader: "${authHeaderValue}"${authSchemeSnippet}`
                 : `\n  authHeader: <resolve from workspace or OpenAPI securitySchemes>; authScheme: <if Authorization>`;
             return (`**#${rank} — GENERATE** | ${testType} | ${s.category} | ${item.novelty}\n` +
-                `${step.method} ${step.path}${step.expectedStatusCode ? ` → ${step.expectedStatusCode}` : ""}\n` +
+                `${step.method} ${step.path} → ${step.expectedStatusCode}\n` +
                 `Validates: ${s.description}\n\n` +
                 `**Context for generation**:\n` +
                 `  Endpoint URL: ${endpointURL}${requestBodyData}${authContext}\n\n` +
@@ -423,7 +522,7 @@ function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValue, auth
                 const bodyData = st.requestBody && Object.keys(st.requestBody).length > 0
                     ? ` [use requestBody: ${JSON.stringify(st.requestBody)} — pass as JSON string in tool call]`
                     : "";
-                return `  ${st.order}. ${st.method} ${st.path}${st.expectedStatusCode ? ` → ${st.expectedStatusCode}` : ""}: ${st.description}${chains}${bodyHint}${bodyData}${responseHint}`;
+                return `  ${st.order}. ${st.method} ${st.path} → ${st.expectedStatusCode}: ${st.description}${chains}${bodyHint}${bodyData}${responseHint}`;
             }).join("\n");
             let destinationHost = "localhost";
             try {
@@ -434,7 +533,9 @@ function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValue, auth
             const authContext = authHeaderValue
                 ? `authHeader: "${authHeaderValue}"${authSchemeSnippet}`
                 : "authHeader: <resolve from workspace or OpenAPI securitySchemes>; authScheme: <if Authorization>";
-            const prereqNote = `\n**Prerequisite discovery**: Check for Foreign Key fields (product_id, user_id, order_id) in the endpoint's request body. If found, prepend a step to create that prerequisite resource first, then chain its primary key field into the dependent step using template variable syntax. Check the actual field name from the response body (\`id\`, \`uuid\`, \`_id\`, etc.), response header (\`Location\`), or cookie — do not assume \`id\`.`;
+            const prereqNote = s.category === "new_endpoint"
+                ? `\n**Prerequisite discovery**: Check for FK fields (product_id, user_id, order_id) in the endpoint's request body. If found, prepend a step to create that prerequisite resource first, then chain its primary key field into the dependent step using template variable syntax. Check the actual field name from the response body (\`id\`, \`uuid\`, \`_id\`, etc.), response header (\`Location\`), or cookie — do not assume \`id\`.`
+                : "";
             const bugLine = s.bugCatchingTarget
                 ? `**Bug to catch**: ${s.bugCatchingTarget}\n`
                 : "";
@@ -463,16 +564,17 @@ function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValue, auth
         const s = item.scenario;
         const testType = s.testType ?? (s.steps.length === 1 ? "contract" : "integration");
         const target = s.steps.length === 1
-            ? `${s.steps[0].method} ${s.steps[0].path}${s.steps[0].expectedStatusCode ? ` → ${s.steps[0].expectedStatusCode}` : ""}`
+            ? `${s.steps[0].method} ${s.steps[0].path} → ${s.steps[0].expectedStatusCode}`
             : `Scenario: ${s.scenarioName} (${s.steps.map(st => `${st.method} ${st.path}`).join(" → ")})`;
         return `#${rank} [ADDITIONAL] | ${testType} | ${s.category} | ${item.novelty}\n  ${target}\n  Validates: ${s.description}`;
     }).join("\n\n");
-    // UI/E2E guidance — the LLM adds UI/E2E items as its Budget Plan dictates.
-    // Only rendered for non-UI-only PRs (UI-only PRs have dedicated guidance above).
-    const uiGuidance = (!isUIOnlyPR && hasFrontendChanges) ? `
-**UI/E2E tests (add per your Budget Plan):** If your Budget Plan allocates UI/E2E slots, add them here. Tool workflow for each new item:
+    // UI/E2E guidance — the LLM adds as many as its Budget Plan calls for.
+    // Note: if a UI test already occupies a GENERATE slot (uiPlaceholderBlock), that slot
+    // satisfies the UI generate count — do not add it again in ADDITIONAL.
+    const uiGuidance = !isUIOnlyPR ? `
+**UI/E2E tests (add per your Budget Plan):** If your Budget Plan requires UI/E2E items beyond what is already in your GENERATE list, append an [ADDITIONAL] entry for each. If a UI test already occupies a GENERATE slot above, that slot satisfies your UI/E2E generate count — do NOT add it again to ADDITIONAL. Tool workflow for each new item:
 - **E2E**: ${hasTraces ? "Use discovered trace/recording files with `skyramp_e2e_test_generation`." : "Add to additionalRecommendations with a note that both a backend API trace (`skyramp_start_trace_collection` / `skyramp_stop_trace_collection`) and a browser Playwright recording must be collected in a live environment first. Do NOT attempt `skyramp_e2e_test_generation` without both traces present."}
-- **UI**: ${hasTraces ? "Use an existing Playwright `.zip` trace with `skyramp_ui_test_generation`." : `Record a trace using \`browser_navigate\` + \`browser_snapshot\` + \`skyramp_export_zip\`, then call \`skyramp_ui_test_generation({ playwrightInput: "<zip_path>", outputDir: "<frontend_test_directory>" })\`. Resolve \`<frontend_test_directory>\` from ${resolveServiceDetailsRef().frontendTestDirRef}.`}
+- **UI**: ${hasTraces ? "Use an existing Playwright `.zip` trace with `skyramp_ui_test_generation`." : `Record a trace using \`browser_navigate\` + \`browser_snapshot\` + \`skyramp_export_zip\`, then call \`skyramp_ui_test_generation({ playwrightInput: "<zip_path>", outputDir: "<frontend_output_dir>" })\` — set \`outputDir\` to ${SERVICE_REFS.frontendTestDirRef}.`}
 Derive scenario names and steps from the actual changed frontend files. If your Budget Plan calls for 0% UI/E2E, omit this entirely.` : "";
     const supplementNote = `\n**If your Budget Plan total exceeds the pre-ranked items listed above:** draft additional tests from source-code enrichment (Step 1). For each new or changed endpoint, identify boundary or variation scenarios — formula parameters, search/filter constraints, required field validation. Only after exhausting PR-specific scenarios, add generic patterns (auth boundary → 401, non-existent ID → 404). Do NOT supplement with tests whose endpoint + test type match a GENERATE item.`;
     // ── PR / branch-diff mode: execution plan ────────────────────────────────
@@ -499,7 +601,7 @@ ${externalTestFilesList}For every GENERATE item below, check its endpoint path a
 
 **Step 1 — Source-Code Enrichment (before executing anything)**
 Read the source code for ALL changed files. Before generating each recommendation, quote the relevant source code in a <source_evidence> block — include the route handler signature, request body schema fields, response shape, and any computed field formulas. Use these quotes to derive tool call parameters. Look for:
-- **Auth middleware** — check for known signals (${AUTH_MIDDLEWARE_PATTERNS_STR}). If any match, override \`authHeader\` and \`authScheme\` even if ${resolveServiceDetailsRef().authSourceRef} says authType: none. **If no known signal matches but the diff shows security-adjacent code** (decorators like \`@requiresRole\`/\`@Protected\`, function names like \`validateToken\`/\`checkPermission\`/\`verifyHMAC\`, or imports from auth/security packages), read the relevant source file to determine the actual auth scheme before proceeding. Auth handling for \`skyramp_integration_test_generation\` with \`scenarioFile\` is covered in the Tool Workflows section below.
+- **Auth middleware** — check for known signals (${AUTH_MIDDLEWARE_PATTERNS_STR}). If any match, override \`authHeader\` and \`authScheme\` even if workspace.yml says authType: none. **If no known signal matches but the diff shows security-adjacent code** (decorators like \`@requiresRole\`/\`@Protected\`, function names like \`validateToken\`/\`checkPermission\`/\`verifyHMAC\`, or imports from auth/security packages), read the relevant source file to determine the actual auth scheme before proceeding. Auth handling for \`skyramp_integration_test_generation\` with \`scenarioFile\` is covered in the Tool Workflows section below.
 - Business rules and formulas (e.g. total_cost = compute * rate + memory * rate)
 - State transitions and domain constraints (e.g. budget cannot drop below current spend)
 - Validation logic (field constraints, cross-field dependencies)
@@ -534,7 +636,7 @@ If these conditions are not met, add it to ADDITIONAL only — do NOT displace a
 When a qualifying candidate is inserted: place it HIGH before MEDIUM before LOW; within the same priority, source-code-derived candidates go BEFORE structural ones. Re-number ranks after insertion. The top ${maxGen} ranked items become GENERATE candidates.
 
 **Source-code validation gates (apply during Step 1):**
-- **Cascade vs referential integrity**: If both a cascade-delete and a delete-blocked scenario appear for the same resource pair, keep only the one matching the source Foreign Key delete policy (ON DELETE CASCADE / cascade=True / onDelete: 'CASCADE' → keep cascade-delete; RESTRICT/PROTECT/no annotation → keep delete-blocked). Remove the inapplicable variant.
+- **Cascade vs referential integrity**: If both a cascade-delete and a delete-blocked scenario appear for the same resource pair, keep only the one matching the source FK delete policy (ON DELETE CASCADE / cascade=True / onDelete: 'CASCADE' → keep cascade-delete; RESTRICT/PROTECT/no annotation → keep delete-blocked). Remove the inapplicable variant.
 - **Unique constraints**: Unique-constraint scenarios (duplicate POST → 409) are pre-drafted for all resources. Confirm enforcement before keeping: SQL UNIQUE index, Mongoose unique: true, Prisma @unique, or explicit duplicate-check code. If the backend is Redis, schema-less, or has no explicit constraint in the changed files, move to ADDITIONAL with a note — do NOT generate.
 
 **Step 2 — Diversity check (using enriched knowledge from Step 1)**
@@ -550,7 +652,7 @@ For each pair of GENERATE items, ask: same HTTP method + path + step sequence +
 Same step sequence with only payload differences (e.g. 10% vs 5% discount both returning 200) = same code path = duplicate. Different scenario names do not make duplicate tests distinct.
 
 **Step 3 — Execute merged plan in rank order**
-Replace any scenario that pairs unrelated resources with one reflecting actual Foreign Key relationships in the codebase.
+Replace any scenario that pairs unrelated resources with one reflecting actual FK relationships in the codebase.
 Use the field names and values from the \`<source_evidence>\` blocks you quoted in Step 1 to fill all tool call parameters. Prefer reusing Step 1 evidence when it already resolves a placeholder, but if a placeholder cannot be replaced with concrete values from files already read, you may read the specific schema, model, or handler file needed to resolve it. Assert response field values, not just status codes.
 
 ${buildTestQualityCriteria()}
@@ -566,10 +668,10 @@ ${buildGenerationRules(isUIOnlyPR)}
 ### GENERATE (process these EXACTLY as listed, in order — after completing Steps 0–2 above; if Step 0 converts an item to UPDATE, backfill the ADD slot from ADDITIONAL following the priority order in Step 0)
 
 ${isUIOnlyPR
-        ? (uiOnlyGenerateGuidance || "  (no UI generate items — derive scenarios from changed frontend files)")
-        : (generateBlocks || "  (no pre-ranked generate items — draft your own based on endpoint analysis)")}
+        ? (uiGenerateBlocks || "  (no UI generate items — derive scenarios from changed frontend files)")
+        : ([generateBlocks, uiPlaceholderBlock].filter(Boolean).join("\n\n") || "  (no pre-ranked generate items — draft your own based on endpoint analysis)")}
 
-**VERIFICATION CHECK**: Before proceeding, verify your generate list covers the same endpoints and test types as the items above. Add genuinely new scenarios to ADDITIONAL instead. One retry on failure then skip to next item.
+**COMPLIANCE CHECK**: Before proceeding, verify your generate list matches the items above. If you plan to generate a scenario with a different name than what is listed (e.g. you want to generate "order-update-discount-calculation" but the plan says "orders-patch-add-items-recalculate"), STOP — use the plan's scenario name and steps. Add your alternative to ADDITIONAL instead. One retry on failure then skip to next item.
 
 ### ADDITIONAL (list in additionalRecommendations in this order after Step 1 insertion)
 
@@ -604,17 +706,10 @@ export function buildRecommendationPrompt(analysis, analysisScope = AnalysisScop
     const hasFrontendChanges = isDiffScope && diffContext
         ? filteredChangedFiles.some(f => isFrontendFile(f))
         : false;
-    // Backend changes detected if:
-    // 1. Endpoints directly matched from changed files (new/modified/removed), OR
-    // 2. Changed files are in backend service/model/middleware directories (affectedServices non-empty)
-    //    but couldn't be mapped to specific endpoints (service-layer changes like services/items.ts)
     const hasApiChanges = isDiffScope && diffContext
         ? (diffContext.newEndpoints.length > 0 || diffContext.modifiedEndpoints.length > 0 || (diffContext.removedEndpoints?.length ?? 0) > 0)
         : false;
-    const hasBackendServiceChanges = isDiffScope && diffContext
-        ? (diffContext.affectedServices.length > 0 && filteredChangedFiles.some(f => !isFrontendFile(f) && /\.(ts|js|py|java|go|rb|rs|cs)$/.test(f)))
-        : false;
-    const isUIOnlyPR = hasFrontendChanges && !hasApiChanges && !hasBackendServiceChanges;
+    const isUIOnlyPR = hasFrontendChanges && !hasApiChanges;
     const hasTraces = (analysis.artifacts?.traceFiles?.length ?? 0) > 0 ||
         (analysis.artifacts?.playwrightRecordings?.length ?? 0) > 0;
     // ── Mode preamble ──
@@ -661,7 +756,7 @@ Output should be concise and immediately actionable.`
                 changedLines.push(`  ${m.method} ${ep.path} [removed]`);
             }
         }
-        endpointLines = `**Changed in this PR:**\n${changedLines.join("\n") || "  none"}\n\n**Other endpoints (reference only — do not prioritize for testing):**\n${otherLines.join("\n") || "  none"}`;
+        endpointLines = `**Likely changed in this PR (from static file→endpoint mapping — verify against diff in Step 2):**\n${changedLines.join("\n") || "  none"}\n\n**Other endpoints (reference only):**\n${otherLines.join("\n") || "  none"}`;
     }
     else {
         endpointLines = allEndpoints
@@ -734,7 +829,7 @@ Framework: ${analysis.projectClassification.primaryFramework} (${analysis.projec
 Project type: ${analysis.projectClassification.projectType}
 Auth: ${authMethod} (header: ${authHeaderValue}${authTypeValue ? `, type: ${authTypeValue}` : ""})
 Base URL: ${analysis.apiEndpoints.baseUrl}
-Endpoints (${analysis.apiEndpoints.totalCount}):
+Candidate endpoints from static scan — unverified, confirm paths against spec or source before use (${analysis.apiEndpoints.totalCount}):
 ${endpointLines}${testFingerprint}
 `.trim();
     // ── Branch diff ──
@@ -755,7 +850,7 @@ Affected services: ${diffContext.affectedServices.join(", ") || "N/A"}
 
 Focus on tests that validate these changes and how they interact with existing resources.
 For removed endpoints: verify they now return 404 or the appropriate deprecation status code.
-Allocate your test budget to endpoints listed under "Changed in this PR". Use other endpoints only as setup steps (e.g. creating a resource before testing its deletion).
+Allocate your test budget to endpoints listed under "Likely changed in this PR". Use other endpoints only as setup steps (e.g. creating a resource before testing its deletion).
 `;
     }
     // ── Interactions ──
@@ -814,11 +909,17 @@ ${detailBlocks}
             const na = NOVELTY_ORDER[a.novelty], nb = NOVELTY_ORDER[b.novelty];
             if (nb !== na)
                 return nb - na;
-            // Deterministic tiebreaker: when priority and novelty are equal, sort by
-            // scenario name then seeded hash. This ensures identical inputs always produce
-            // the same ordering regardless of runtime locale or JS sort stability — important
-            // because the LLM receives a ranked list and would otherwise produce inconsistent
-            // recommendations across runs for equally-ranked scenarios.
+            const crossA = a.scenario.steps.length > 2 ? 1 : 0;
+            const crossB = b.scenario.steps.length > 2 ? 1 : 0;
+            if (crossB !== crossA)
+                return crossB - crossA;
+            if (b.scenario.steps.length !== a.scenario.steps.length)
+                return b.scenario.steps.length - a.scenario.steps.length;
+            const errorA = a.scenario.steps.some(s => s.interactionType === "error" || s.interactionType === "edge-case") ? 1 : 0;
+            const errorB = b.scenario.steps.some(s => s.interactionType === "error" || s.interactionType === "edge-case") ? 1 : 0;
+            if (errorB !== errorA)
+                return errorB - errorA;
+            // Use locale-independent comparison to avoid runtime-locale non-determinism
             const nameA = a.scenario.scenarioName;
             const nameB = b.scenario.scenarioName;
             if (nameA < nameB)
@@ -853,23 +954,12 @@ ${detailBlocks}
         mainSection = buildExecutionPlan(scored, maxGen, topN, analysis.apiEndpoints.baseUrl, authHeaderValue, authSchemeSnippet, authTypeValue, seed, endpointCount, isUIOnlyPR, hasFrontendChanges, hasTraces, externalCoverage, analysis.existingTests.relevantExternalTestPaths ?? []);
     }
     else {
-        // Endpoint discovery hint: when backend service files changed but no endpoints were
-        // directly matched, guide the LLM to trace from service files → controllers → routes.
-        const endpointDiscoveryHint = hasBackendServiceChanges && diffContext
-            ? `
-**Endpoint Discovery Required** — the diff modifies backend service files (affected services: ${diffContext.affectedServices.join(", ")}) that don't directly define routes. You MUST:
-1. Read the Routing entry-point files listed above
-2. Trace which controllers/routers import the affected services
-3. Identify the specific HTTP endpoints those controllers register
-4. Use discovered endpoints as your GENERATE targets (contract + integration tests)
-Do NOT default to UI-only tests — this PR has backend logic changes that require API-level testing.`
-            : "";
         mainSection = `
 ## Draft Your Execution Plan
 
-No pre-drafted scenarios available.${endpointDiscoveryHint}
+No pre-drafted scenarios available.
 
-${buildScopeAssessmentSection(topN, maxGen, isUIOnlyPR)}
+${buildScopeAssessmentSection(topN, maxGen)}
 
 Draft tests from the endpoint interactions and source code above, following the same tool pipeline described in Tool Workflows below. Prioritize critical categories: security_boundary > data_integrity > business_rule > workflow > crud.
 
@@ -877,8 +967,6 @@ For each test: pick the highest-impact endpoint(s), draft a realistic scenario w
 
 **Honor your Budget Plan: produce exactly the total you committed to (GENERATE + ADDITIONAL). No fewer, no padding with low-value tests.**
 
-**Coverage breadth enforcement:** Your GENERATE items must span DIFFERENT HTTP methods or endpoints from your Coverage Reasoning surfaces. If you identified 5+ testable surfaces but all GENERATE items target the same method + path (e.g. all POST /permissions), you are violating diversity. Spread GENERATE slots across distinct surfaces; put remaining surfaces in ADDITIONAL recommendations.
-
 ## Recommendation Stability
 - **Carry forward** previous additionalRecommendations that still apply — match by scenarioName (multi-step) or endpoint (single-endpoint). Re-derive category and priority from test content.
 - **Only drop** a previous recommendation if its target endpoint was removed, its business logic changed, or it is now covered by a generated test.