@skyramp/mcp 0.0.65 → 0.1.0-rc.2

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

@@ -1,8 +1,10 @@
 jest.mock("@skyramp/skyramp", () => ({
     WorkspaceConfigManager: { create: jest.fn() },
 }));
+import { TestType } from "../../types/TestTypes.js";
 import { buildRecommendationPrompt } from "./test-recommendation-prompt.js";
-import { PATH_PARAM_UUID_GUIDANCE, MAX_TESTS_TO_GENERATE, buildTestQualityCriteria } from "./recommendationSections.js";
+import { PATH_PARAM_UUID_GUIDANCE, MAX_TESTS_TO_GENERATE, buildTestQualityCriteria, buildArchitectPreamble, buildContextFetchingGuidance, buildReasoningProtocol, buildFewShotExamples, buildVerificationChecklist, } from "./recommendationSections.js";
+import { AnalysisScope } from "../../types/RepositoryAnalysis.js";
 // ---------------------------------------------------------------------------
 // Minimal fixtures
 // ---------------------------------------------------------------------------
@@ -60,7 +62,7 @@ describe("buildRecommendationPrompt — PR History section", () => {
         expect(prompt).not.toContain("Stability rule");
     });
     it("omits PR History section when prContext has no recommendations", () => {
-        const prompt = buildRecommendationPrompt(minimalAnalysis(), "current_branch_diff", 10, makePRContext());
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 10, makePRContext());
         expect(prompt).not.toContain("PR History");
     });
     it("includes PR History section with prNumber when recommendations exist", () => {
@@ -70,7 +72,7 @@ describe("buildRecommendationPrompt — PR History section", () => {
                 { testType: "integration", endpoint: "POST /api/items", status: "implemented", commentId: "1" },
             ],
         });
-        const prompt = buildRecommendationPrompt(minimalAnalysis(), "current_branch_diff", 10, ctx);
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 10, ctx);
         expect(prompt).toContain("PR History (PR #99)");
     });
     it("renders Previously Generated Tests for implemented recommendations", () => {
@@ -80,7 +82,7 @@ describe("buildRecommendationPrompt — PR History section", () => {
             ],
             implementedTestFiles: ["test_items_contract.py"],
         });
-        const prompt = buildRecommendationPrompt(minimalAnalysis(), "current_branch_diff", 10, ctx);
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 10, ctx);
         expect(prompt).toContain("Previously Generated Tests");
         expect(prompt).toContain("contract — GET /api/items");
         expect(prompt).toContain("test_items_contract.py");
@@ -91,7 +93,7 @@ describe("buildRecommendationPrompt — PR History section", () => {
                 { testType: "contract", endpoint: "GET /api/items", status: "implemented", commentId: "1" },
             ],
         });
-        const prompt = buildRecommendationPrompt(minimalAnalysis(), "current_branch_diff", 10, ctx);
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 10, ctx);
         expect(prompt).not.toContain("Stability rule");
         expect(prompt).not.toContain("Previously Recommended");
     });
@@ -101,7 +103,7 @@ describe("buildRecommendationPrompt — PR History section", () => {
                 { testType: "integration", endpoint: "POST /api/orders", scenarioName: "order-lifecycle", status: "recommended", commentId: "1" },
             ],
         });
-        const prompt = buildRecommendationPrompt(minimalAnalysis(), "current_branch_diff", 10, ctx);
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 10, ctx);
         expect(prompt).toContain("Previously Recommended (not generated)");
         expect(prompt).toContain("Stability rule");
         expect(prompt).toContain("integration — POST /api/orders (scenario: order-lifecycle)");
@@ -112,7 +114,7 @@ describe("buildRecommendationPrompt — PR History section", () => {
                 { testType: "integration", endpoint: "POST /api/orders", status: "recommended", commentId: "1" },
             ],
         });
-        const prompt = buildRecommendationPrompt(minimalAnalysis(), "current_branch_diff", 10, ctx);
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 10, ctx);
         const stabilityBlock = prompt.slice(prompt.indexOf("**Stability rule**"), prompt.indexOf("Only add NEW recommendations"));
         expect(stabilityBlock).toContain("scenarioName");
         expect(stabilityBlock).toContain("endpoint");
@@ -126,7 +128,7 @@ describe("buildRecommendationPrompt — PR History section", () => {
                 { testType: "integration", endpoint: "POST /api/orders", status: "recommended", commentId: "1" },
             ],
         });
-        const prompt = buildRecommendationPrompt(minimalAnalysis(), "current_branch_diff", 10, ctx);
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 10, ctx);
         expect(prompt).toContain("Do not churn recommendations without cause");
         expect(prompt).toContain("Carry forward");
     });
@@ -138,7 +140,7 @@ describe("buildRecommendationPrompt — PR History section", () => {
             ],
             implementedTestFiles: ["test_items_contract.py"],
         });
-        const prompt = buildRecommendationPrompt(minimalAnalysis(), "current_branch_diff", 10, ctx);
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 10, ctx);
         expect(prompt).toContain("Previously Generated Tests");
         expect(prompt).toContain("Previously Recommended (not generated)");
         expect(prompt).toContain("Stability rule");
@@ -152,7 +154,7 @@ describe("buildRecommendationPrompt — PR History section", () => {
                 { testFile: "test_items_contract.py", status: "fail", timestamp: "2026-01-01T00:00:00Z" },
             ],
         });
-        const prompt = buildRecommendationPrompt(minimalAnalysis(), "current_branch_diff", 10, ctx);
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 10, ctx);
         expect(prompt).toContain("Execution Results from Prior Run");
         expect(prompt).toContain("test_items_contract.py");
         expect(prompt).toContain("fail");
@@ -163,7 +165,7 @@ describe("buildRecommendationPrompt — PR History section", () => {
                 { testType: "contract", endpoint: "GET /api/items", status: "recommended", commentId: "1" },
             ],
         });
-        const prompt = buildRecommendationPrompt(minimalAnalysis(), "current_branch_diff", 10, ctx);
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 10, ctx);
         expect(prompt).toContain("contract — GET /api/items");
         expect(prompt).not.toContain("(scenario:");
     });
@@ -175,7 +177,7 @@ describe("buildRecommendationPrompt — PR History section", () => {
                 { testType: "integration", endpoint: "DELETE /api/users/{id}", scenarioName: "cascade-delete-user", status: "recommended", commentId: "1" },
             ],
         });
-        const prompt = buildRecommendationPrompt(minimalAnalysis(), "current_branch_diff", 10, ctx);
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 10, ctx);
         expect(prompt).toContain("order-lifecycle");
         expect(prompt).toContain("item-schema-check");
         expect(prompt).toContain("cascade-delete-user");
@@ -188,7 +190,7 @@ describe("buildRecommendationPrompt — PR History section", () => {
                 { testType: "contract", endpoint: "GET /api/items", status: "recommended", commentId: "1" },
             ],
         });
-        const prompt = buildRecommendationPrompt(minimalAnalysis(), "current_branch_diff", 10, ctx);
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 10, ctx);
         expect(prompt).not.toContain("order-lifecycle");
         expect(prompt).toContain("contract — GET /api/items");
     });
@@ -198,7 +200,7 @@ describe("buildRecommendationPrompt — PR History section", () => {
                 { testType: "integration", endpoint: "POST /api/orders", status: "recommended", commentId: "1" },
             ],
         });
-        const prompt = buildRecommendationPrompt(minimalAnalysis(), "current_branch_diff", 10, ctx);
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 10, ctx);
         expect(prompt).toContain("Promote the highest-priority ones");
         expect(prompt).toContain("into generation slots if capacity allows");
     });
@@ -208,7 +210,7 @@ describe("buildRecommendationPrompt — PR History section", () => {
                 { testType: "contract", endpoint: "GET /api/items", status: "implemented", commentId: "1" },
             ],
         });
-        const prompt = buildRecommendationPrompt(minimalAnalysis(), "current_branch_diff", 10, ctx);
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 10, ctx);
         expect(prompt).toContain("Do NOT re-recommend");
         expect(prompt).toContain("Previously Generated Tests");
     });
@@ -220,7 +222,7 @@ describe("buildRecommendationPrompt — PR History section", () => {
                 { testType: "integration", endpoint: "GET /api/orders/{id}", scenarioName: "order-lifecycle", status: "recommended", commentId: "1" },
             ],
         });
-        const prompt = buildRecommendationPrompt(minimalAnalysis(), "current_branch_diff", 10, ctx);
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 10, ctx);
         const recSection = prompt.slice(prompt.indexOf("Previously Recommended"), prompt.indexOf("**Stability rule**"));
         const scenarioOccurrences = (recSection.match(/order-lifecycle/g) || []).length;
         expect(scenarioOccurrences).toBe(1);
@@ -236,7 +238,7 @@ describe("buildRecommendationPrompt — PR History section", () => {
                 { testType: "contract", endpoint: "POST /api/items", status: "recommended", commentId: "1" },
             ],
         });
-        const prompt = buildRecommendationPrompt(minimalAnalysis(), "current_branch_diff", 10, ctx);
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 10, ctx);
         const recSection = prompt.slice(prompt.indexOf("Previously Recommended"), prompt.indexOf("**Stability rule**"));
         const getOccurrences = (recSection.match(/contract — GET \/api\/items/g) || []).length;
         expect(getOccurrences).toBe(1);
@@ -252,7 +254,7 @@ describe("buildRecommendationPrompt — PR History section", () => {
                 { testType: "integration", endpoint: "DELETE /api/items/{id}", scenarioName: "cascade-delete", status: "recommended", commentId: "1" },
             ],
         });
-        const prompt = buildRecommendationPrompt(minimalAnalysis(), "current_branch_diff", 10, ctx);
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 10, ctx);
         const recSection = prompt.slice(prompt.indexOf("Previously Recommended"), prompt.indexOf("**Stability rule**"));
         const orderOccurrences = (recSection.match(/order-lifecycle/g) || []).length;
         const cascadeOccurrences = (recSection.match(/cascade-delete/g) || []).length;
@@ -276,34 +278,34 @@ function minimalScenario(overrides = {}) {
         chainingKeys: ["id"],
         requiresAuth: false,
         estimatedComplexity: "simple",
-        testType: "integration",
+        testType: TestType.INTEGRATION,
         ...overrides,
     };
 }
 describe("buildRecommendationPrompt — Stability and supplement section", () => {
-    it("includes Recommendation Stability section in output when scenarios exist", () => {
+    it("includes Recommendation Stability section in output when scenarios exist (PR mode)", () => {
         const analysis = minimalAnalysis({
             businessContext: { mainPurpose: "Test API", userFlows: [], dataFlows: [], integrationPatterns: [], draftedScenarios: [minimalScenario()] },
         });
-        const prompt = buildRecommendationPrompt(analysis, "full_repo", 10);
+        const prompt = buildRecommendationPrompt(analysis, AnalysisScope.CurrentBranchDiff, 10);
         expect(prompt).toContain("## Recommendation Stability");
     });
-    it("stability section uses scenarioName/endpoint matching strategy", () => {
+    it("stability section uses scenarioName/endpoint matching strategy (PR mode)", () => {
         const analysis = minimalAnalysis({
             businessContext: { mainPurpose: "Test API", userFlows: [], dataFlows: [], integrationPatterns: [], draftedScenarios: [minimalScenario()] },
         });
-        const prompt = buildRecommendationPrompt(analysis, "full_repo", 10);
+        const prompt = buildRecommendationPrompt(analysis, AnalysisScope.CurrentBranchDiff, 10);
         const stabilityStart = prompt.indexOf("## Recommendation Stability");
         const stabilityBlock = prompt.slice(stabilityStart, stabilityStart + 500);
         expect(stabilityBlock).toContain("scenarioName");
         expect(stabilityBlock).toContain("endpoint");
         expect(stabilityBlock).toContain("Re-derive category and priority");
     });
-    it("stability section specifies when to drop a recommendation", () => {
+    it("stability section specifies when to drop a recommendation (PR mode)", () => {
         const analysis = minimalAnalysis({
             businessContext: { mainPurpose: "Test API", userFlows: [], dataFlows: [], integrationPatterns: [], draftedScenarios: [minimalScenario()] },
         });
-        const prompt = buildRecommendationPrompt(analysis, "full_repo", 10);
+        const prompt = buildRecommendationPrompt(analysis, AnalysisScope.CurrentBranchDiff, 10);
         expect(prompt).toContain("target endpoint was removed");
         expect(prompt).toContain("business logic changed");
         expect(prompt).toContain("covered by a generated test");
@@ -313,21 +315,21 @@ describe("buildRecommendationPrompt — Stability and supplement section", () =>
         const analysis = minimalAnalysis({
             businessContext: { mainPurpose: "Test API", userFlows: [], dataFlows: [], integrationPatterns: [], draftedScenarios: [minimalScenario()] },
         });
-        const prompt = buildRecommendationPrompt(analysis, "full_repo", 10);
-        expect(prompt).toContain("REQUIRED — You MUST add");
-        expect(prompt).toContain("6-dimension rubric");
+        const prompt = buildRecommendationPrompt(analysis, AnalysisScope.FullRepo, 10);
+        expect(prompt).toContain("<supplement_guidance>");
+        expect(prompt).toContain("5-dimension rubric");
     });
     // Verify MAX_TESTS_TO_GENERATE is still exported and equals 3
     it("MAX_TESTS_TO_GENERATE is 3", () => {
         expect(MAX_TESTS_TO_GENERATE).toBe(3);
     });
-    it("uses MAX_CRITICAL_TESTS in category-aware selection rules", () => {
+    it("uses MAX_CRITICAL_TESTS in category-aware selection rules (PR mode)", () => {
         const analysis = minimalAnalysis({
             businessContext: { mainPurpose: "Test API", userFlows: [], dataFlows: [], integrationPatterns: [], draftedScenarios: [minimalScenario()] },
         });
-        const prompt = buildRecommendationPrompt(analysis, "full_repo", 10);
-        // The critical-category minimum line references MAX_CRITICAL_TESTS (= 3)
-        expect(prompt).toContain("GENERATE items MUST be from HIGH-priority categories");
+        const prompt = buildRecommendationPrompt(analysis, AnalysisScope.CurrentBranchDiff, 10);
+        // MAX_CRITICAL_TESTS applies to PR mode (GENERATE items) — full_repo mode only presents, does not execute
+        expect(prompt).toContain("GENERATE items should be from HIGH-priority categories");
     });
 });
 // ---------------------------------------------------------------------------
@@ -364,7 +366,7 @@ describe("PATH_PARAM_UUID_GUIDANCE — no hardcoded UUID anchor", () => {
                     }],
             },
         });
-        const prompt = buildRecommendationPrompt(analysis, "current_branch_diff", 10);
+        const prompt = buildRecommendationPrompt(analysis, AnalysisScope.CurrentBranchDiff, 10);
         expect(prompt).toContain("<random-uuid-v4>");
         expect(prompt).not.toMatch(UUID_V4_REGEX);
     });
@@ -373,12 +375,24 @@ describe("PATH_PARAM_UUID_GUIDANCE — no hardcoded UUID anchor", () => {
 // Tests — maxGenerateOverride parameter in buildRecommendationPrompt
 // ---------------------------------------------------------------------------
 describe("buildRecommendationPrompt — maxGenerateOverride", () => {
-    const scenariosForOverride = Array.from({ length: 6 }, (_, i) => minimalScenario({
-        scenarioName: `scenario-${i}`,
-        description: `Test scenario ${i}`,
-        category: i < 2 ? "security_boundary" : "crud",
-        priority: i < 2 ? "high" : "low",
-    }));
+    const scenariosForOverride = [
+        // One single-step scenario (auto-classified as contract in full_repo mode) to verify contract tool calls
+        minimalScenario({
+            scenarioName: "scenario-0",
+            description: "Test scenario 0",
+            category: "security_boundary",
+            priority: "high",
+            testType: TestType.CONTRACT,
+            steps: [{ order: 1, method: "GET", path: "/api/items", description: "Get items", interactionType: "success", expectedStatusCode: 200 }],
+        }),
+        // Five multi-step integration scenarios
+        ...Array.from({ length: 5 }, (_, i) => minimalScenario({
+            scenarioName: `scenario-${i + 1}`,
+            description: `Test scenario ${i + 1}`,
+            category: i < 1 ? "security_boundary" : "crud",
+            priority: i < 1 ? "high" : "low",
+        })),
+    ];
     const analysisWithScenarios = minimalAnalysis({
         businessContext: {
             mainPurpose: "Test API",
@@ -389,35 +403,85 @@ describe("buildRecommendationPrompt — maxGenerateOverride", () => {
         },
     });
     it("uses MAX_TESTS_TO_GENERATE as default when maxGenerateOverride is undefined", () => {
-        const prompt = buildRecommendationPrompt(analysisWithScenarios, "current_branch_diff", 10);
+        const prompt = buildRecommendationPrompt(analysisWithScenarios, AnalysisScope.CurrentBranchDiff, 10);
         expect(prompt).toContain(`Budget: ${MAX_TESTS_TO_GENERATE} generate`);
     });
     it("respects maxGenerateOverride when provided", () => {
-        const prompt = buildRecommendationPrompt(analysisWithScenarios, "current_branch_diff", 10, undefined, undefined, undefined, 5);
+        const prompt = buildRecommendationPrompt(analysisWithScenarios, AnalysisScope.CurrentBranchDiff, 10, undefined, undefined, undefined, 5);
         expect(prompt).toContain("Budget: 5 generate");
         expect(prompt).toContain("additional = 10 total");
     });
     it("clamps maxGenerateOverride to topN when override exceeds topN", () => {
-        const prompt = buildRecommendationPrompt(analysisWithScenarios, "current_branch_diff", 4, undefined, undefined, undefined, 10);
+        const prompt = buildRecommendationPrompt(analysisWithScenarios, AnalysisScope.CurrentBranchDiff, 4, undefined, undefined, undefined, 10);
         expect(prompt).toContain("Budget: 4 generate");
     });
     it("clamps maxGenerateOverride to 0 when negative", () => {
-        const prompt = buildRecommendationPrompt(analysisWithScenarios, "current_branch_diff", 10, undefined, undefined, undefined, -5);
+        const prompt = buildRecommendationPrompt(analysisWithScenarios, AnalysisScope.CurrentBranchDiff, 10, undefined, undefined, undefined, -5);
         expect(prompt).toContain("Budget: 0 generate");
     });
     it("allows maxGenerateOverride of 0 to produce no generate items", () => {
-        const prompt = buildRecommendationPrompt(analysisWithScenarios, "current_branch_diff", 10, undefined, undefined, undefined, 0);
+        const prompt = buildRecommendationPrompt(analysisWithScenarios, AnalysisScope.CurrentBranchDiff, 10, undefined, undefined, undefined, 0);
         expect(prompt).toContain("Budget: 0 generate");
-        expect(prompt).not.toContain("#1 — GENERATE");
-    });
-    it("uses topN as default maxGen in full_repo scope when maxGenerateOverride is undefined", () => {
-        const prompt = buildRecommendationPrompt(analysisWithScenarios, "full_repo", 6);
-        expect(prompt).toContain("Budget: 6 generate");
-    });
-    it("overrides full_repo default when maxGenerateOverride is provided", () => {
-        const prompt = buildRecommendationPrompt(analysisWithScenarios, "full_repo", 6, undefined, undefined, undefined, 2);
-        expect(prompt).toContain("Budget: 2 generate");
-        expect(prompt).toContain("additional = 6 total");
+        // The few-shot examples section contains "#1 — GENERATE" as an illustration,
+        // so check the execution plan's GENERATE section is empty instead.
+        expect(prompt).toContain("(no pre-ranked generate items");
+    });
+    it("uses topN as default maxGen in full_repo scope — Repo mode output format", () => {
+        const prompt = buildRecommendationPrompt(analysisWithScenarios, AnalysisScope.FullRepo, 6);
+        expect(prompt).toContain("Test Recommendations — 6 total (grouped by test type)");
+        expect(prompt).toContain("Repo mode");
+        expect(prompt).not.toContain("Budget:");
+        // Full-repo mode: no execution, just presentation
+        expect(prompt).toContain("no tests are executed");
+        expect(prompt).toContain("Present up to 6 recommendations.");
+        // Full-repo items must include tool calls for on-demand generation
+        expect(prompt).toContain("skyramp_contract_test_generation");
+    });
+    it("full_repo mode ignores maxGenerateOverride — always presents all", () => {
+        const prompt = buildRecommendationPrompt(analysisWithScenarios, AnalysisScope.FullRepo, 6, undefined, undefined, undefined, 2);
+        expect(prompt).toContain("Test Recommendations — 6 total (grouped by test type)");
+        expect(prompt).toContain("Repo mode");
+        expect(prompt).not.toContain("Budget:");
+        expect(prompt).toContain("no tests are executed");
+    });
+    it("full_repo mode includes tool calls in each recommendation item", () => {
+        const prompt = buildRecommendationPrompt(analysisWithScenarios, AnalysisScope.FullRepo, 6);
+        // Contract items should have tool calls
+        expect(prompt).toContain("skyramp_contract_test_generation");
+        // Integration items should use the batch tool
+        expect(prompt).toContain("skyramp_batch_scenario_test_generation");
+        // MANDATORY language for test type mix and item counts
+        expect(prompt).toContain("Test type mix");
+    });
+    it("full_repo mode uses MANDATORY language for item count and test type mix", () => {
+        const prompt = buildRecommendationPrompt(analysisWithScenarios, AnalysisScope.FullRepo, 6);
+        expect(prompt).toContain("Test type mix — MANDATORY");
+        expect(prompt).toContain("Present up to 6 recommendations.");
+    });
+    it("full_repo mode pre-allocates E2E and UI sections for full-stack repos", () => {
+        const fullStackAnalysis = minimalAnalysis({
+            projectClassification: {
+                projectType: "full-stack",
+                primaryLanguage: "TypeScript",
+                primaryFramework: "Express",
+                deploymentPattern: "traditional",
+            },
+            businessContext: {
+                mainPurpose: "Test API",
+                userFlows: [],
+                dataFlows: [],
+                integrationPatterns: [],
+                draftedScenarios: scenariosForOverride,
+            },
+        });
+        const prompt = buildRecommendationPrompt(fullStackAnalysis, AnalysisScope.FullRepo, 10);
+        // E2E and UI sections must be present even though scenarioDrafting only produces backend types
+        expect(prompt).toContain("### E2E");
+        expect(prompt).toContain("### UI");
+        expect(prompt).toContain("skyramp_e2e_test_generation");
+        expect(prompt).toContain("skyramp_ui_test_generation");
+        // Backend sections should still be present
+        expect(prompt).toContain("### Integration");
     });
 });
 // ---------------------------------------------------------------------------
@@ -438,7 +502,7 @@ describe("buildRecommendationPrompt — additional recommendation dedup", () =>
             chainingKeys: ["id"],
             requiresAuth: false,
             estimatedComplexity: "complex",
-            testType: "integration",
+            testType: TestType.INTEGRATION,
             ...overrides,
         };
     }
@@ -479,7 +543,7 @@ describe("buildRecommendationPrompt — additional recommendation dedup", () =>
             patchOrdersScenario("orders-patch-another-variant"),
         ];
         const analysis = analysisWithPatchScenarios(scenarios);
-        const prompt = buildRecommendationPrompt(analysis, "current_branch_diff", 10, undefined, undefined, undefined, 2);
+        const prompt = buildRecommendationPrompt(analysis, AnalysisScope.CurrentBranchDiff, 10, undefined, undefined, undefined, 2);
         // First 2 become GENERATE, the remaining share orders::integration → should be filtered
         const additionalMatches = prompt.match(/#\d+ \[ADDITIONAL\]/g) || [];
         const ordersPatchAdditional = (prompt.match(/\[ADDITIONAL\].*orders-patch/g) || []);
@@ -493,12 +557,12 @@ describe("buildRecommendationPrompt — additional recommendation dedup", () =>
             // Contract test for same endpoint — different test type, should survive dedup
             {
                 ...patchOrdersScenario("orders-patch-contract"),
-                testType: "contract",
+                testType: TestType.CONTRACT,
                 steps: [{ order: 1, method: "PATCH", path: "/api/v1/orders/{order_id}", description: "Contract test", interactionType: "success", expectedStatusCode: 200 }],
             },
         ];
         const analysis = analysisWithPatchScenarios(scenarios);
-        const prompt = buildRecommendationPrompt(analysis, "current_branch_diff", 10, undefined, undefined, undefined, 2);
+        const prompt = buildRecommendationPrompt(analysis, AnalysisScope.CurrentBranchDiff, 10, undefined, undefined, undefined, 2);
         // Contract test targets orders but is a different type → should be in ADDITIONAL
         expect(prompt).toContain("orders-patch-contract");
     });
@@ -516,7 +580,7 @@ describe("buildRecommendationPrompt — additional recommendation dedup", () =>
             },
         ];
         const analysis = analysisWithPatchScenarios(scenarios);
-        const prompt = buildRecommendationPrompt(analysis, "current_branch_diff", 10, undefined, undefined, undefined, 2);
+        const prompt = buildRecommendationPrompt(analysis, AnalysisScope.CurrentBranchDiff, 10, undefined, undefined, undefined, 2);
         expect(prompt).toContain("products-unique-constraint");
     });
 });
@@ -533,7 +597,7 @@ describe("buildRecommendationPrompt — E2E slot guard (Fix 2)", () => {
             chainingKeys: [],
             requiresAuth: false,
             estimatedComplexity: "simple",
-            testType: "ui",
+            testType: TestType.UI,
         };
     }
     it("suppresses E2E additional slot when UI test is in GENERATE list", () => {
@@ -552,7 +616,7 @@ describe("buildRecommendationPrompt — E2E slot guard (Fix 2)", () => {
                 affectedServices: [],
             },
         });
-        const prompt = buildRecommendationPrompt(analysis, "current_branch_diff", 10, undefined, undefined, undefined, 3);
+        const prompt = buildRecommendationPrompt(analysis, AnalysisScope.CurrentBranchDiff, 10, undefined, undefined, undefined, 3);
         expect(prompt).not.toContain("e2e-flow-for-changed-feature");
     });
     it("includes E2E additional slot when no UI test is generated and no UI slot reserved", () => {
@@ -573,7 +637,7 @@ describe("buildRecommendationPrompt — E2E slot guard (Fix 2)", () => {
         });
         // maxGen=1 so reserveUIGenSlot is false (requires maxGen > 1),
         // and no UI scenario in GENERATE → E2E slot should appear
-        const prompt = buildRecommendationPrompt(analysis, "current_branch_diff", 10, undefined, undefined, undefined, 1);
+        const prompt = buildRecommendationPrompt(analysis, AnalysisScope.CurrentBranchDiff, 10, undefined, undefined, undefined, 1);
         expect(prompt).toContain("e2e-flow-for-changed-feature");
     });
 });
@@ -602,7 +666,335 @@ describe("buildTestQualityCriteria — contract test guidance for error-handling
                 draftedScenarios: [minimalScenario()],
             },
         });
-        const prompt = buildRecommendationPrompt(analysis, "full_repo", 10);
+        const prompt = buildRecommendationPrompt(analysis, AnalysisScope.FullRepo, 10);
         expect(prompt).toContain("Do NOT add setup steps just to avoid hardcoding an ID");
     });
 });
+// ---------------------------------------------------------------------------
+// Tests — Architect Persona Preamble
+// ---------------------------------------------------------------------------
+describe("buildRecommendationPrompt — Architect Persona Preamble", () => {
+    it("includes Skyramp Integration Architect persona at the beginning of the prompt", () => {
+        const prompt = buildRecommendationPrompt(minimalAnalysis());
+        expect(prompt).toContain("Skyramp Integration Architect");
+    });
+    it("persona appears before the mode preamble", () => {
+        const prompt = buildRecommendationPrompt(minimalAnalysis());
+        const architectIdx = prompt.indexOf("Skyramp Integration Architect");
+        const modeIdx = prompt.indexOf("Repo mode");
+        expect(architectIdx).toBeLessThan(modeIdx);
+        expect(architectIdx).toBeGreaterThan(-1);
+    });
+    it("persona instructs not to guess or fabricate values", () => {
+        const prompt = buildRecommendationPrompt(minimalAnalysis());
+        expect(prompt).toContain("No guessing");
+        expect(prompt).toContain("derive all parameters");
+    });
+    it("buildArchitectPreamble(diff) returns the diff persona", () => {
+        const preamble = buildArchitectPreamble(true);
+        expect(preamble).toContain("Skyramp Integration Architect");
+        expect(preamble).toContain("generate tests for this PR");
+        expect(preamble).toContain("duplicate coverage");
+    });
+    it("buildArchitectPreamble(full_repo) returns the full-repo persona", () => {
+        const preamble = buildArchitectPreamble(false);
+        expect(preamble).toContain("Skyramp Integration Architect");
+        expect(preamble).toContain("comprehensive test recommendation catalog");
+        expect(preamble).toContain("Do not call any generation tools");
+    });
+});
+// ---------------------------------------------------------------------------
+// Tests — Mandatory Reasoning Protocol
+// ---------------------------------------------------------------------------
+describe("buildRecommendationPrompt — Mandatory Reasoning Protocol", () => {
+    it("includes reasoning protocol section in the prompt", () => {
+        const analysis = minimalAnalysis({
+            businessContext: {
+                mainPurpose: "Test API",
+                userFlows: [],
+                dataFlows: [],
+                integrationPatterns: [],
+                draftedScenarios: [minimalScenario()],
+            },
+        });
+        const prompt = buildRecommendationPrompt(analysis, AnalysisScope.FullRepo, 10);
+        expect(prompt).toContain("Parameter Grounding Rule");
+    });
+    it("reasoning protocol covers the key parameter sources", () => {
+        const protocol = buildReasoningProtocol();
+        expect(protocol).toContain("requestBody");
+        expect(protocol).toContain("endpointURL");
+        expect(protocol).toContain("authHeader");
+        expect(protocol).toContain("FK path params");
+    });
+    it("reasoning protocol instructs to read source file when value cannot be sourced", () => {
+        const protocol = buildReasoningProtocol();
+        expect(protocol).toContain("read the relevant source file");
+    });
+});
+// ---------------------------------------------------------------------------
+// Tests — Context Fetching Guidance
+// ---------------------------------------------------------------------------
+describe("buildRecommendationPrompt — Context Fetching Guidance", () => {
+    it("includes execution plan context when sessionId is provided", () => {
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.FullRepo, 10, undefined, undefined, undefined, undefined, "test-session-123");
+        expect(prompt).toContain("Execution Plan Context");
+        expect(prompt).toContain("relevant source file");
+    });
+    it("omits execution plan context when sessionId is not provided", () => {
+        const prompt = buildRecommendationPrompt(minimalAnalysis());
+        expect(prompt).not.toContain("Execution Plan Context");
+    });
+    it("buildContextFetchingGuidance returns empty string when no sessionId", () => {
+        expect(buildContextFetchingGuidance()).toBe("");
+        expect(buildContextFetchingGuidance(undefined)).toBe("");
+    });
+    it("buildContextFetchingGuidance references enriched scenarios and source files", () => {
+        const guidance = buildContextFetchingGuidance("session-1");
+        expect(guidance).toContain("placeholder");
+        expect(guidance).toContain("relevant source file");
+    });
+});
+// ---------------------------------------------------------------------------
+// Tests — Tool Contract Framing
+// ---------------------------------------------------------------------------
+describe("buildRecommendationPrompt — Tool Contract Framing", () => {
+    it("includes contract language in tool workflows section (PR mode only)", () => {
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff);
+        expect(prompt).toContain("strict technical contracts");
+    });
+    it("includes thinking block reminder in tool workflows (PR mode only)", () => {
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff);
+        expect(prompt).toContain("Output a <thinking> block");
+    });
+});
+// ---------------------------------------------------------------------------
+// Tests — Long-context best practices: XML tags structure
+// ---------------------------------------------------------------------------
+describe("buildRecommendationPrompt — XML tag structure (long-context best practice)", () => {
+    it("wraps repository context in <repository_context> tags", () => {
+        const prompt = buildRecommendationPrompt(minimalAnalysis());
+        expect(prompt).toContain("<repository_context>");
+        expect(prompt).toContain("</repository_context>");
+    });
+    it("wraps endpoint interactions in <endpoint_interactions> tags", () => {
+        const prompt = buildRecommendationPrompt(minimalAnalysis());
+        expect(prompt).toContain("<endpoint_interactions>");
+        expect(prompt).toContain("</endpoint_interactions>");
+    });
+    it("wraps existing tests in <existing_tests> tags", () => {
+        const prompt = buildRecommendationPrompt(minimalAnalysis());
+        expect(prompt).toContain("<existing_tests>");
+        expect(prompt).toContain("</existing_tests>");
+    });
+    it("wraps instructions in <instructions> tags", () => {
+        const prompt = buildRecommendationPrompt(minimalAnalysis());
+        expect(prompt).toContain("<instructions>");
+        expect(prompt).toContain("</instructions>");
+    });
+    it("wraps branch diff in <branch_diff> tags when diff context is present", () => {
+        const analysis = minimalAnalysis({
+            branchDiffContext: {
+                baseBranch: "main",
+                currentBranch: "feature/test",
+                changedFiles: ["src/routes.ts"],
+                newEndpoints: [{ path: "/api/new", methods: [{ method: "POST", sourceFile: "routes.ts", interactionCount: 0 }] }],
+                modifiedEndpoints: [],
+                affectedServices: [],
+            },
+        });
+        const prompt = buildRecommendationPrompt(analysis, AnalysisScope.CurrentBranchDiff, 10);
+        expect(prompt).toContain("<branch_diff>");
+        expect(prompt).toContain("</branch_diff>");
+    });
+    it("wraps PR history in <pr_history> tags when present", () => {
+        const ctx = makePRContext({
+            prNumber: 42,
+            previousRecommendations: [
+                { testType: "contract", endpoint: "GET /api/items", status: "implemented", commentId: "1" },
+            ],
+        });
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 10, ctx);
+        expect(prompt).toContain("<pr_history>");
+        expect(prompt).toContain("</pr_history>");
+    });
+});
+// ---------------------------------------------------------------------------
+// Tests — Long-context best practice: data before instructions
+// ---------------------------------------------------------------------------
+describe("buildRecommendationPrompt — data-before-instructions ordering", () => {
+    it("places repository_context before instructions", () => {
+        const prompt = buildRecommendationPrompt(minimalAnalysis());
+        const dataIdx = prompt.indexOf("<repository_context>");
+        const instructionsIdx = prompt.indexOf("<instructions>");
+        expect(dataIdx).toBeLessThan(instructionsIdx);
+    });
+    it("places existing_tests before instructions", () => {
+        const prompt = buildRecommendationPrompt(minimalAnalysis());
+        const testsIdx = prompt.indexOf("<existing_tests>");
+        const instructionsIdx = prompt.indexOf("<instructions>");
+        expect(testsIdx).toBeLessThan(instructionsIdx);
+    });
+    it("places endpoint_interactions before instructions", () => {
+        const prompt = buildRecommendationPrompt(minimalAnalysis());
+        const interactionsIdx = prompt.indexOf("<endpoint_interactions>");
+        const instructionsIdx = prompt.indexOf("<instructions>");
+        expect(interactionsIdx).toBeLessThan(instructionsIdx);
+    });
+});
+// ---------------------------------------------------------------------------
+// Tests — Few-shot examples
+// ---------------------------------------------------------------------------
+describe("buildFewShotExamples — concrete few-shot examples with thinking", () => {
+    it("returns examples wrapped in <examples> tags", () => {
+        const examples = buildFewShotExamples();
+        expect(examples).toContain("<examples>");
+        expect(examples).toContain("</examples>");
+    });
+    it("contains at least 2 example blocks", () => {
+        const examples = buildFewShotExamples();
+        const count = (examples.match(/<example /g) || []).length;
+        expect(count).toBeGreaterThanOrEqual(2);
+    });
+    it("includes <thinking> blocks inside examples to demonstrate reasoning", () => {
+        const examples = buildFewShotExamples();
+        expect(examples).toContain("<thinking>");
+        expect(examples).toContain("</thinking>");
+    });
+    it("includes an integration test example with tool calls", () => {
+        const examples = buildFewShotExamples();
+        expect(examples).toContain("skyramp_batch_scenario_test_generation");
+        expect(examples).toContain("skyramp_integration_test_generation");
+    });
+    it("includes a contract test example", () => {
+        const examples = buildFewShotExamples();
+        expect(examples).toContain("skyramp_contract_test_generation");
+    });
+    it("includes an ADDITIONAL example", () => {
+        const examples = buildFewShotExamples();
+        expect(examples).toContain("[ADDITIONAL]");
+    });
+    it("thinking blocks demonstrate parameter grounding", () => {
+        const examples = buildFewShotExamples();
+        expect(examples).toContain("**Parameter grounding**:");
+        expect(examples).toContain("workspace");
+        expect(examples).toContain("chained from");
+    });
+    it("integration example uses filePath from batch response, not a guessed filename", () => {
+        const examples = buildFewShotExamples();
+        expect(examples).toContain("<filePath returned by skyramp_batch_scenario_test_generation");
+        expect(examples).not.toContain('scenarioFile: "scenario_');
+    });
+    it("integration example includes bugCatchingTarget", () => {
+        const examples = buildFewShotExamples();
+        expect(examples).toContain("bugCatchingTarget:");
+    });
+    it("is included in the recommendation prompt (PR mode only)", () => {
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff);
+        expect(prompt).toContain("<examples>");
+    });
+});
+// ---------------------------------------------------------------------------
+// Tests — Verification checklist
+// ---------------------------------------------------------------------------
+describe("buildVerificationChecklist — self-check at end of prompt", () => {
+    it("returns checklist wrapped in <verification> tags", () => {
+        const checklist = buildVerificationChecklist(10, 3);
+        expect(checklist).toContain("<verification>");
+        expect(checklist).toContain("</verification>");
+    });
+    it("includes total count check with correct numbers", () => {
+        const checklist = buildVerificationChecklist(10, 3);
+        expect(checklist).toContain("equals exactly 10");
+        expect(checklist).toContain("3 GENERATE + 7 ADDITIONAL");
+    });
+    it("includes scenarioFile source check", () => {
+        const checklist = buildVerificationChecklist(10, 3);
+        expect(checklist).toContain("filePath");
+        expect(checklist).toContain("skyramp_batch_scenario_test_generation");
+    });
+    it("includes bugCatchingTarget check", () => {
+        const checklist = buildVerificationChecklist(10, 3);
+        expect(checklist).toContain("bugCatchingTarget");
+    });
+    it("includes distinct code path check", () => {
+        const checklist = buildVerificationChecklist(10, 3);
+        expect(checklist).toContain("distinct code path");
+    });
+    it("includes auth consistency check", () => {
+        const checklist = buildVerificationChecklist(10, 3);
+        expect(checklist).toContain("Auth parameters are consistent");
+    });
+    it("includes endpointURL format check", () => {
+        const checklist = buildVerificationChecklist(10, 3);
+        expect(checklist).toContain("base URL and the path");
+    });
+    it("includes placeholder removal check", () => {
+        const checklist = buildVerificationChecklist(10, 3);
+        expect(checklist).toContain("from source");
+    });
+    it("is included in the recommendation prompt (PR mode only)", () => {
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff);
+        expect(prompt).toContain("<verification>");
+    });
+});
+// ---------------------------------------------------------------------------
+// Tests — Source evidence grounding
+// ---------------------------------------------------------------------------
+describe("buildRecommendationPrompt — source evidence grounding", () => {
+    it("includes source_evidence instruction in repo-mode enrichment", () => {
+        const analysis = minimalAnalysis({
+            businessContext: {
+                mainPurpose: "Test API",
+                userFlows: [],
+                dataFlows: [],
+                integrationPatterns: [],
+                draftedScenarios: [minimalScenario()],
+            },
+        });
+        const prompt = buildRecommendationPrompt(analysis, AnalysisScope.FullRepo, 10);
+        expect(prompt).toContain("Test Recommendations");
+    });
+    it("includes source_evidence instruction in PR-mode enrichment", () => {
+        const analysis = minimalAnalysis({
+            businessContext: {
+                mainPurpose: "Test API",
+                userFlows: [],
+                dataFlows: [],
+                integrationPatterns: [],
+                draftedScenarios: [minimalScenario()],
+            },
+        });
+        const prompt = buildRecommendationPrompt(analysis, AnalysisScope.CurrentBranchDiff, 10);
+        expect(prompt).toContain("Execution Plan");
+    });
+});
+// ---------------------------------------------------------------------------
+// Tests — Over-prompting reduction
+// ---------------------------------------------------------------------------
+describe("buildRecommendationPrompt — reduced over-prompting", () => {
+    it("uses softer language for step labels (no MANDATORY)", () => {
+        const analysis = minimalAnalysis({
+            businessContext: {
+                mainPurpose: "Test API",
+                userFlows: [],
+                dataFlows: [],
+                integrationPatterns: [],
+                draftedScenarios: [minimalScenario()],
+            },
+        });
+        const prompt = buildRecommendationPrompt(analysis, AnalysisScope.CurrentBranchDiff, 10);
+        expect(prompt).not.toContain("(MANDATORY before executing anything)");
+        expect(prompt).toContain("(before executing anything)");
+    });
+    it("uses XML tags in context fetching guidance", () => {
+        const guidance = buildContextFetchingGuidance("session-1");
+        expect(guidance).toContain("<context_fetching_protocol>");
+        expect(guidance).toContain("</context_fetching_protocol>");
+    });
+    it("uses XML tags in reasoning protocol", () => {
+        const protocol = buildReasoningProtocol();
+        expect(protocol).toContain("<reasoning_protocol>");
+        expect(protocol).toContain("</reasoning_protocol>");
+    });
+});