@skyramp/mcp 0.1.5 → 0.1.7

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

@@ -0,0 +1,154 @@
+jest.mock("@skyramp/skyramp", () => ({
+    WorkspaceConfigManager: { create: jest.fn() },
+}));
+import { buildAnalysisOutputText } from "./analysisOutputPrompt.js";
+import { AnalysisScope } from "../../types/RepositoryAnalysis.js";
+// ---------------------------------------------------------------------------
+// Minimal fixture factory
+// ---------------------------------------------------------------------------
+function baseParams(overrides = {}) {
+    return {
+        sessionId: "test-session-id",
+        repositoryPath: "/repo",
+        analysisScope: AnalysisScope.CurrentBranchDiff,
+        scannedEndpoints: [],
+        wsBaseUrl: "http://localhost:3000",
+        wsAuthHeader: "Authorization",
+        wsAuthType: "",
+        wsSchemaPath: "",
+        routerMountContext: [],
+        parsedDiff: {
+            changedFiles: [],
+            newEndpoints: [],
+            modifiedEndpoints: [],
+        },
+        ...overrides,
+    };
+}
+// ---------------------------------------------------------------------------
+// Step 2.3 caller-tracing block
+// ---------------------------------------------------------------------------
+describe("buildAnalysisOutputText — unmatchedFiles / Step 2.3 caller-tracing", () => {
+    it("includes Step 2.3 block when unmatchedFiles is non-empty and scope is CurrentBranchDiff", () => {
+        const params = baseParams({
+            unmatchedFiles: [
+                "server/src/main/java/helpers/DataUtils.java",
+                "server/src/main/java/helpers/MustacheHelper.java",
+            ],
+        });
+        const output = buildAnalysisOutputText(params);
+        expect(output).toContain("### Step 2.3: Trace callers of changed non-route files");
+        expect(output).toContain("DataUtils.java");
+        expect(output).toContain("MustacheHelper.java");
+        expect(output).toContain("/execute");
+    });
+    it("lists each unmatched file as a bullet in the Step 2.3 block", () => {
+        const params = baseParams({
+            unmatchedFiles: ["src/services/OrderService.ts", "src/utils/pricingHelper.ts"],
+        });
+        const output = buildAnalysisOutputText(params);
+        expect(output).toContain("- `src/services/OrderService.ts`");
+        expect(output).toContain("- `src/utils/pricingHelper.ts`");
+    });
+    it("omits Step 2.3 block when unmatchedFiles is empty", () => {
+        const params = baseParams({ unmatchedFiles: [] });
+        const output = buildAnalysisOutputText(params);
+        expect(output).not.toContain("Step 2.3");
+        expect(output).not.toContain("Trace callers of changed non-route files");
+    });
+    it("omits Step 2.3 block when unmatchedFiles is undefined", () => {
+        const params = baseParams({ unmatchedFiles: undefined });
+        const output = buildAnalysisOutputText(params);
+        expect(output).not.toContain("Step 2.3");
+    });
+    it("omits Step 2.3 block when scope is full_repo even if unmatchedFiles is non-empty", () => {
+        const params = baseParams({
+            analysisScope: AnalysisScope.FullRepo,
+            unmatchedFiles: ["src/services/SomeService.ts"],
+        });
+        const output = buildAnalysisOutputText(params);
+        expect(output).not.toContain("Step 2.3");
+    });
+    it("Step 2.3 appears before Step 2.5 in the output", () => {
+        const params = baseParams({
+            unmatchedFiles: ["src/utils/helper.ts"],
+        });
+        const output = buildAnalysisOutputText(params);
+        const pos23 = output.indexOf("Step 2.3");
+        const pos25 = output.indexOf("Step 2.5");
+        expect(pos23).toBeGreaterThan(-1);
+        expect(pos25).toBeGreaterThan(-1);
+        expect(pos23).toBeLessThan(pos25);
+    });
+    it("Step 2.5 critical-patterns block is always present regardless of unmatchedFiles", () => {
+        const withUnmatched = buildAnalysisOutputText(baseParams({ unmatchedFiles: ["src/utils/foo.ts"] }));
+        const withoutUnmatched = buildAnalysisOutputText(baseParams({ unmatchedFiles: [] }));
+        expect(withUnmatched).toContain("Step 2.5: Identify critical patterns");
+        expect(withoutUnmatched).toContain("Step 2.5: Identify critical patterns");
+    });
+    it("omits Step 2.3 block when unmatchedFiles contains only frontend component files (UI-only PR)", () => {
+        // Frontend files (.tsx, .jsx, .vue, .svelte) end up in unmatchedFiles because they
+        // have no route annotations, but they have no HTTP callers to trace — emitting
+        // Step 2.3 for them would produce irrelevant instructions. (Copilot review fix)
+        const params = baseParams({
+            unmatchedFiles: [
+                "src/components/Button.tsx",
+                "src/pages/Dashboard.jsx",
+                "src/views/UserProfile.vue",
+                "src/routes/Settings.svelte",
+            ],
+        });
+        const output = buildAnalysisOutputText(params);
+        expect(output).not.toContain("Step 2.3");
+        expect(output).not.toContain("Trace callers of changed non-route files");
+    });
+    it("omits Step 2.3 block when unmatchedFiles contains only non-code files (docs/config)", () => {
+        // README.md, package.json, etc. have no changed symbols to trace — listing them
+        // in Step 2.3 is misleading. (Copilot review fix)
+        const params = baseParams({
+            unmatchedFiles: [
+                "README.md",
+                "package.json",
+                "docker-compose.yml",
+                ".github/workflows/ci.yml",
+            ],
+        });
+        const output = buildAnalysisOutputText(params);
+        expect(output).not.toContain("Step 2.3");
+        expect(output).not.toContain("Trace callers of changed non-route files");
+    });
+    it("emits Step 2.3 for backend code files but excludes frontend/non-code siblings", () => {
+        // Mixed PR: one Java helper + one React component + one config file.
+        // Only the Java file should appear in the Step 2.3 bullets.
+        const params = baseParams({
+            unmatchedFiles: [
+                "server/helpers/DataUtils.java",
+                "client/components/ActionButton.tsx",
+                "package.json",
+            ],
+        });
+        const output = buildAnalysisOutputText(params);
+        expect(output).toContain("Step 2.3");
+        expect(output).toContain("DataUtils.java");
+        expect(output).not.toContain("ActionButton.tsx");
+        expect(output).not.toContain("package.json");
+    });
+    it("omits Step 2.3 when unmatchedFiles contains .ts/.js frontend files but isUIOnly is true", () => {
+        // Angular services, React hooks, Vue composables — all .ts/.js — pass the
+        // BACKEND_CODE_EXT filter but belong to a UI-only PR. The !isUIOnly guard
+        // prevents Step 2.3 from emitting contradictory caller-tracing instructions
+        // alongside the UI-only Step 2 guidance. (Copilot review fix)
+        const params = baseParams({
+            // parsedDiff.changedFiles drives isUIOnly detection; all frontend-ext → isUIOnly=true
+            parsedDiff: {
+                changedFiles: ["src/services/auth.service.ts", "src/hooks/useAuth.ts"],
+                newEndpoints: [],
+                modifiedEndpoints: [],
+            },
+            unmatchedFiles: ["src/services/auth.service.ts", "src/hooks/useAuth.ts"],
+        });
+        const output = buildAnalysisOutputText(params);
+        expect(output).not.toContain("Step 2.3");
+        expect(output).not.toContain("Trace callers of changed non-route files");
+    });
+});

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

@@ -0,0 +1,290 @@
+import { AUTH_MIDDLEWARE_PATTERNS_STR } from "../../utils/workspaceAuth.js";
+import { resolveServiceDetailsRef } from "../../utils/utils.js";
+import { logger } from "../../utils/logger.js";
+import { TEST_CATEGORIES } from "../../types/TestRecommendation.js";
+import { buildScopeAssessmentSection } from "./scopeAssessment.js";
+import { buildTestPatternGuidelines, buildTestQualityCriteria, buildGenerationRules, MAX_CRITICAL_TESTS, } from "./recommendationSections.js";
+import { externalDedupKey, scenarioCoverageKey } from "./recommendationShared.js";
+const SERVICE_REFS = resolveServiceDetailsRef();
+export 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.
+    const scoredAfterExternalDedup = externalCoverage.size > 0
+        ? scored.filter(item => {
+            const key = externalDedupKey(item.scenario);
+            if (externalCoverage.has(key)) {
+                logger.info(`External dedup: skipping "${item.scenario.scenarioName}" (${key}) — covered by external test`);
+                return false;
+            }
+            return true;
+        })
+        : scored;
+    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)));
+    const hasWorkspaceAuthType = !!authTypeValue && authTypeValue !== "none";
+    // For skyramp_integration_test_generation with scenarioFile:
+    // - If workspace has authType set: omit auth entirely — workspace handles Bearer prefix.
+    // - If no authType: pass authHeader only (no authScheme).
+    const authHeaderOnlyRef = hasWorkspaceAuthType
+        ? ""
+        : authHeaderValue
+            ? `, authHeader: "${authHeaderValue}"`
+            : `, authHeader: <check OpenAPI securitySchemes or auth middleware; "" if confirmed unauthenticated>`;
+    // 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;
+        const s = item.scenario;
+        const testType = s.testType ?? (s.steps.length === 1 ? "contract" : "integration");
+        if (testType === "contract") {
+            const step = s.steps[0];
+            const endpointURL = `${baseUrl}${step.path}`;
+            const isBodyMethod = ["POST", "PUT", "PATCH"].includes(step.method);
+            const requestBodyData = step.requestBody && Object.keys(step.requestBody).length > 0
+                ? `\n  Request body: ${JSON.stringify(step.requestBody)} (pass as JSON string in tool call, NOT as object)`
+                : (isBodyMethod ? `\n  Request body: <derive from source code schemas>` : "");
+            const authContext = authHeaderValue
+                ? `\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}\n` +
+                `Validates: ${s.description}\n\n` +
+                `**Context for generation**:\n` +
+                `  Endpoint URL: ${endpointURL}${requestBodyData}${authContext}\n\n` +
+                `**Tool**: skyramp_contract_test_generation (see tool description for parameter structure)`);
+        }
+        else {
+            // integration / e2e / ui — multi-step scenario pipeline
+            const stepLines = s.steps.map((st) => {
+                const chains = st.chainsFrom
+                    ? ` (chains: ${Array.isArray(st.chainsFrom)
+                        ? st.chainsFrom.map(c => `${c.sourceField} from step ${c.sourceStep}`).join(", ")
+                        : `${st.chainsFrom.sourceField} from step ${st.chainsFrom.sourceStep}`})`
+                    : "";
+                const bodyHint = st.bodyMustInclude?.length
+                    ? ` [required fields: ${st.bodyMustInclude.join(", ")}]`
+                    : "";
+                const responseHint = st.expectedResponseFields?.length
+                    ? ` [assert: ${st.expectedResponseFields.join(", ")}]`
+                    : "";
+                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.description}${chains}${bodyHint}${bodyData}${responseHint}`;
+            }).join("\n");
+            let destinationHost = "localhost";
+            try {
+                const parsed = new URL(baseUrl);
+                destinationHost = parsed.hostname;
+            }
+            catch { /* use localhost as fallback */ }
+            const authContext = authHeaderValue
+                ? `authHeader: "${authHeaderValue}"${authSchemeSnippet}`
+                : "authHeader: <resolve from workspace or OpenAPI securitySchemes>; authScheme: <if Authorization>";
+            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`
+                : "";
+            const fromSource = s.source === "agent-enriched"
+                ? "Auth: OpenAPI securitySchemes or auth middleware"
+                : "Request/response shapes: source code schemas; Auth: OpenAPI securitySchemes or auth middleware";
+            return (`**#${rank} — GENERATE** | ${testType} | ${s.category} | ${item.novelty}\n` +
+                `Scenario: ${s.scenarioName} (${s.steps.length} steps)\n` +
+                bugLine +
+                `${stepLines}\n\n` +
+                `**Context for generation**:\n` +
+                `  - Destination: ${destinationHost}\n` +
+                `  - Base URL: ${baseUrl}\n` +
+                `  - ${authContext}\n` +
+                `  - From source: ${fromSource}\n\n` +
+                `**Tool pipeline**:\n` +
+                `  1. skyramp_batch_scenario_test_generation (see tool description for parameter structure)\n` +
+                `  2. skyramp_integration_test_generation with returned scenarioFile${authHeaderOnlyRef ? ` and ${authHeaderOnlyRef.replace(/^,\s*/, '')}` : ""}\n` +
+                `  **Note**: requestBody/responseBody must be JSON strings (e.g. "{\\"field\\":\\"value\\"}"), not objects.` +
+                prereqNote);
+        }
+    }).join("\n\n");
+    // Pre-ranked backend additional candidates — the LLM picks from these per its Budget Plan.
+    const additionalLines = additionalItems.map((item, i) => {
+        const rank = maxGen + i + 1;
+        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}`
+            : `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 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_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 ────────────────────────────────
+    const externalTestFilesList = relevantExternalTestPaths.length > 0
+        ? `**Read these external test files first** (paths are relative to the \`repositoryPath\` you passed to \`skyramp_analyze_changes\` — prepend it to get the absolute path). Determine exactly which HTTP methods + paths each one covers. This is the definitive source of truth for external coverage:\n${relevantExternalTestPaths.map(p => `- \`${p}\``).join("\n")}\n\n`
+        : "";
+    return `## Execution Plan
+Seed: ${seed} | Endpoints: ${endpointCount} | Max: ${maxGen} generate + up to ${Math.max(topN - maxGen, 0)} additional (your Budget Plan determines the exact count)
+
+${buildScopeAssessmentSection(topN, maxGen, isUIOnlyPR)}
+
+**Step 0 — External test coverage verification (before executing anything)**
+${externalTestFilesList}For every GENERATE item below, check its endpoint path and test type against the Existing Tests list (further down in the prompt).
+- **\`[external]\` tests**: If the endpoint is already covered by an \`[external]\` test of the same type → skip the resource entirely (do NOT create or update). Backfill from ADDITIONAL using the priority order below:
+  1. **BUG-CATCHING TESTS FIRST (CRITICAL)**: If source code analysis revealed a bug, logic error, or incorrect formula (e.g. discount math adding instead of subtracting, off-by-one errors, missing validation), CREATE A TEST THAT EXPOSES IT. The test SHOULD FAIL — that's the point. Document the bug. Example: if discount formula is wrong, test with discount=20% and assert correct math. If no bug found, skip to #2.
+  2. **PR-endpoint edge cases**: Look for integration test candidates covering error paths, boundary values, or alternative scenarios for the SAME endpoints changed in the PR diff. If no suitable candidate exists in ADDITIONAL, derive one from your source-code enrichment findings.
+  3. **Same-resource other scenarios**: Other HTTP methods or flows on the same resource group touched by the PR.
+  4. **Cross-resource workflows involving the PR endpoint**: Integration scenarios that include the PR's changed endpoint as one of the steps.
+  5. **Unrelated endpoint coverage (last resort)**: Tests for endpoints with no connection to the PR diff, only when ALL options above have been exhausted.
+  **Avoid backfilling with a test for a completely unrelated resource (e.g. \`POST /reviews\` when the PR only changes \`/orders\`) if any PR-endpoint edge-case integration test is feasible.**
+- **Contract tests (\`[skyramp]\`)**: If an existing \`[skyramp]\` contract test already covers that resource path → UPDATE the existing test file instead of creating a new one. A new test case is a new test even if the file already exists — count it toward \`newTestsCreated\`.
+- **Integration/scenario tests**: Always generate as a new file via the scenario pipeline, even if an existing integration test covers the same resource. A new multi-step scenario is a distinct test. Count it toward \`newTestsCreated\`.
+- **UI tests**: Always generate as a new file. Count toward \`newTestsCreated\`.
+
+**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 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)
+- Security boundaries not covered by the structural candidates below
+
+For each one found, evaluate it against these 6 dimensions and assign priority:
+  | Dimension | What to assess |
+  | Production Safety | Guards a critical boundary (auth, unique constraint, cascade delete, data integrity, breaking migration)? → HIGH |
+  | Bug-Finding Potential | Targets a known failure mode (race condition, data consistency, state transition, cascade effect)? → HIGH |
+  | Mutation Side Effects | Does PUT/PATCH modify a collection of child items (line items, cart entries) and trigger recalculation (totals, counts, amounts)? → HIGH — this is the most common source of user-reported bugs |
+  | User Journey Relevance | Reflects how real users interact (from traces, business flows, critical paths)? → HIGH or MEDIUM |
+  | Coverage Gap | Addresses an area with zero existing test coverage? → bump up one tier |
+  | Code Insight | Derived from actual implementation (spotted middleware pattern, N+1 risk, unique constraint)? → bump up one tier |
+
+Quality gate — ask all three questions:
+  1. "Would this test prevent a production incident?" → YES = HIGH priority regardless of other dimensions
+  2. "Does this test exercise a real workflow or catch a real bug?" → YES = at least MEDIUM
+  3. "Does this test cover a mutation that modifies child items and triggers total/amount recalculation?" → YES = HIGH priority, and prefer it for GENERATE over simple single-field update tests for the same endpoint
+
+Assign category: ${TEST_CATEGORIES.join(" | ")}
+
+${buildTestPatternGuidelines()}
+
+INSERT a source-code-derived candidate into the ranked list **only if ALL three conditions are met**:
+1. Priority is HIGH (it guards a critical boundary or would prevent a production incident)
+2. It is specific to THIS codebase — derived from a concrete business rule, formula, or constraint found in the changed files (not a general pattern that applies to any API)
+3. It is not already covered by a structural candidate in the list below
+
+If these conditions are not met, add it to ADDITIONAL only — do NOT displace a pre-ranked GENERATE item.
+**CRITICAL-tier items (category: new_endpoint) should never be displaced** — they test the actual endpoints introduced in this PR and must always occupy GENERATE slots.
+
+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 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)**
+Each GENERATE item must exercise a **distinct code path** — not just different input values on the same path.
+
+For each pair of GENERATE items, ask: same HTTP method + path + step sequence + expected status? → DUPLICATE. Keep the richer item; replace the other with a test from a different path below. Move the displaced item to ADDITIONAL.
+
+**Good diversity — aim for this mix across GENERATE slots:**
+- **Happy-path**: create prerequisites → call the new endpoint → verify computed fields and child collections
+- **Error-path**: trigger a distinct error status (404 for non-existent resource, 422 for invalid input, 400 for malformed request — whichever the source code handles)
+- **State-variation**: same endpoint, different logic branch (empty array, remove instead of add, boundary value that triggers a guard)
+
+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 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()}
+
+${buildGenerationRules(isUIOnlyPR)}
+
+**ADDITIONAL recommendations** are submitted via \`skyramp_submit_report\`. Refer to its schema for required fields. Only include recommendations that add distinct coverage beyond what was generated.
+
+**Never mark a recommendation "blocked":** No OpenAPI spec → use source code for shapes. No traces → provide \`skyramp_start_trace_collection\` instructions. No backend trace → use the scenario pipeline.
+
+**Critical-category minimum:** At least ${Math.min(MAX_CRITICAL_TESTS, maxGen)} of the ${maxGen} GENERATE items should be from HIGH-priority categories (security_boundary, business_rule, data_integrity, breaking_change). The pre-ranked plan below already prioritises this — only override if source-code enrichment reveals a higher-value candidate.
+
+### 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
+        ? (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)")}
+
+**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)
+
+${additionalLines || "  (none pre-ranked)"}
+${uiGuidance}
+${supplementNote}
+
+**Honor your Budget Plan: produce exactly the total you committed to (GENERATE + ADDITIONAL). No fewer, no padding with low-value tests.**
+
+## 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.
+- **Only add** new recommendations for code paths introduced since the last run.`;
+}