@skyramp/mcp 0.3.1 → 0.3.2-rc.pom-1

package/build/prompts/test-recommendation/fullRepoCatalog.d.ts

@@ -1,7 +1,7 @@
 import { DraftedScenario } from "../../types/RepositoryAnalysis.js";
-import { PriorityTier } from "../../types/TestRecommendation.js";
+import { Novelty, PriorityTier } from "../../types/TestRecommendation.js";
 export declare function buildFullRepoRecommendations(scored: Array<{
     scenario: DraftedScenario;
     priority: PriorityTier;
-    novelty: string;
+    novelty: Novelty;
 }>, topN: number, baseUrl: string, authHeaderValue: string, authSchemeSnippet: string, authTypeValue: string, isFrontendProject?: boolean, isFrontendOnlyProject?: boolean, externalCoverage?: Set<string>): string;

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

@@ -51,7 +51,7 @@ Before each GENERATE tool call, confirm WHERE each key value comes from:
 - **endpointURL** → workspace \`baseUrl\` + endpoint path (both required — never path alone)
 - **authHeader / authScheme** → workspace config or OpenAPI \`securitySchemes\`
 - **Foreign-key path params** → chained from a prior step's response — never invented or hardcoded. Common field names: \`id\`, \`uuid\`, \`_id\`, \`*_id\`; use whatever identifier field the server returns for this resource. The chaining source can be a response body (POST or GET), a response header (e.g. \`Location\`), or a cookie.
-- **Names / string values** → realistic; append timestamp suffix to avoid re-run conflicts
+- **Names / string values** → realistic. Do NOT hardcode a timestamp/uuid suffix. Instead, for create fields that carry a UNIQUE constraint (e.g. \`name\`, \`slug\`, \`email\` — confirm from the source schema: \`unique=True\`, SQL \`UNIQUE\`, DTO), list their field paths in the step's \`uniqueFields\` (gjson notation) — the generator injects a run-unique value so re-runs don't 409.
 
 ## Ranking Rule
 For each GENERATE item, include one sentence in your output (before the tool calls) stating the specific bug or failure it targets — derived from \`bugCatchingTarget\` or your source-code reading. Example: "Targets: order total miscalculation — total_amount = sum(item.price × item.quantity) should recompute when items array changes."
@@ -332,7 +332,10 @@ ${authGuidance}
    collection array (e.g. \`"items": [{"product_id": <chained from prior POST>, "quantity": 2}]\`).
    Never send a PATCH that only modifies metadata (discount, status) without also including the
    items/products collection — such a test will not catch collection-level or total-recalculation bugs.
-   Use unique names with timestamp suffix to avoid conflicts on re-runs.
+   For UNIQUE-constrained create fields, set the step's \`uniqueFields\` (gjson paths) rather than
+   hardcoding timestamp suffixes — the generator makes them run-unique so re-runs don't 409.
+   For every resource-creating step (POST/PUT), also add a matching DELETE step for the created
+   resource (path ID chained from the create response) so the scenario cleans up after itself.
    For GET/PUT/DELETE with path IDs, use a placeholder — chaining resolves the real ID.
 2. Produces a \`scenario_<name>.json\` in the same \`outputDir\` as the test files (not \`.skyramp/\`).
 3. Call \`skyramp_integration_test_generation\` with \`scenarioFile\`: ${integrationAuthNote}

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

@@ -200,7 +200,7 @@ Budget Plan: 0 total — no new, modified, or removed endpoints were classified
 
 With a 0-total Budget Plan: generate zero tests, recommend zero tests, and follow the zero-test report path. Do NOT draft baseline or generic tests for unchanged endpoints to fill a budget — an empty diff surface is a valid, expected outcome.
 
-**Exception — claim the ceiling only with evidence:** if your code review of the changed files shows an observable API behavior change the classifier missed (e.g. a DTO/serializer/service change that alters a response shape, or a deployment/config change that newly exposes or removes endpoints), raise your Budget Plan to cover exactly those affected endpoints, up to ${maxTotal} total (${effectiveGenerate} generate + ${additional} additional), 0% UI/E2E. Every test must name the changed file that justifies it. State your raised plan now in the canonical format — \`Budget Plan: <total> total (<generate> generate + <additional> additional), 0% UI/E2E\` — and use those exact numbers throughout the rest of the prompt; the raised generate count is your committed generate count.`;
+**Exception — claim the ceiling only with evidence:** if your code review of the changed files shows an observable API behavior change the classifier missed (e.g. a DTO/serializer/service change that alters a response shape, a deployment/config change that newly exposes or removes endpoints, or a schema-defined API contract change — a CRD type/kubebuilder validation marker, GraphQL schema, or gRPC proto edit that adds, removes, or re-validates what the server accepts or returns), raise your Budget Plan to cover exactly those affected endpoints, up to ${maxTotal} total (${effectiveGenerate} generate + ${additional} additional), 0% UI/E2E. Note: repositories whose entire API surface is schema-defined (e.g. a Kubernetes operator serving CRDs through the kube-apiserver) ALWAYS classify zero endpoints — for these, a schema change in the diff IS the endpoint change; evaluate this exception against the schema files instead of concluding there is nothing to test. Every test must name the changed file that justifies it. State your raised plan now in the canonical format — \`Budget Plan: <total> total (<generate> generate + <additional> additional), 0% UI/E2E\` — and use those exact numbers throughout the rest of the prompt; the raised generate count is your committed generate count.`;
     }
     // Unambiguous backend-only or UI-only: emit a single Budget Plan line — no LLM counting needed.
     if (precomputedUIPct !== undefined) {

package/build/prompts/test-recommendation/test-recommendation-prompt.d.ts

@@ -1,6 +1,31 @@
-import { RepositoryAnalysis, AnalysisScope } from "../../types/RepositoryAnalysis.js";
+import { RepositoryAnalysis, AnalysisScope, DraftedScenario } from "../../types/RepositoryAnalysis.js";
 import { WorkspaceAuthType } from "../../utils/workspaceAuth.js";
 import { PRTestContext } from "../../utils/pr-comment-parser.js";
+import { Novelty, PriorityTier } from "../../types/TestRecommendation.js";
 import { buildExternalCoverageSet, externalDedupKey } from "./recommendationShared.js";
 export { buildExternalCoverageSet, externalDedupKey };
+/** Result of {@link computeScoredCandidates} — the scoring/classification
+ *  inputs shared between prompt rendering and the SKYR-3879 register-plan
+ *  pre-seed (analyzeChangesTool.ts), so both derive the exact same numbers. */
+export interface ScoredCandidatesResult {
+    scored: Array<{
+        scenario: DraftedScenario;
+        priority: PriorityTier;
+        novelty: Novelty;
+    }>;
+    filteredChangedFiles: string[];
+    isUIOnlyPR: boolean;
+    hasFrontendChanges: boolean;
+    hasApiChanges: boolean;
+    maxGen: number;
+    seed: string;
+}
+/**
+ * Compute the pre-ranked scenario scoring, the UI/API classification flags,
+ * and the effective GENERATE cap — extracted from buildRecommendationPrompt
+ * so skyramp_analyze_changes (SKYR-3879 Path B pre-seed) can derive the exact
+ * same candidate set the Execution Plan prompt is built from, without
+ * duplicating (and risking drift from) this scoring logic.
+ */
+export declare function computeScoredCandidates(analysis: RepositoryAnalysis, analysisScope?: AnalysisScope, topN?: number, maxGenerateOverride?: number): ScoredCandidatesResult;
 export declare function buildRecommendationPrompt(analysis: RepositoryAnalysis, analysisScope?: AnalysisScope, topN?: number, prContext?: PRTestContext, workspaceAuthHeader?: string, workspaceAuthType?: WorkspaceAuthType, workspaceAuthScheme?: string, maxGenerateOverride?: number, sessionId?: string): string;

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

@@ -3,7 +3,7 @@ import { AnalysisScope, isDiff, } from "../../types/RepositoryAnalysis.js";
 import { WorkspaceAuthType, getDefaultAuthHeader } from "../../utils/workspaceAuth.js";
 import { logger } from "../../utils/logger.js";
 import { buildArchitectPreamble, buildContextFetchingGuidance, buildReasoningProtocol, buildToolWorkflows, buildFewShotExamples, buildVerificationChecklist, getAuthSnippets, MAX_TESTS_TO_GENERATE, MAX_RECOMMENDATIONS, } from "./recommendationSections.js";
-import { CATEGORY_PRIORITY } from "../../types/TestRecommendation.js";
+import { CATEGORY_PRIORITY, Novelty, PriorityTier } from "../../types/TestRecommendation.js";
 import { buildScopeAssessmentSection, isFrontendFile } from "./scopeAssessment.js";
 import { buildExecutionPlan, EXEC_STEP_CODE_REVIEW } from "./diffExecutionPlan.js";
 import { buildFullRepoRecommendations } from "./fullRepoCatalog.js";
@@ -36,21 +36,21 @@ 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)
-        return "existing";
+        return Novelty.EXISTING;
     const paths = scenario.steps.map(s => s.path);
     const newPaths = new Set((diffContext.newEndpoints || []).map(ep => ep.path));
     const modPaths = new Set((diffContext.modifiedEndpoints || []).map(ep => ep.path));
     const removedPaths = new Set((diffContext.removedEndpoints || []).map(ep => ep.path));
     if (paths.some(p => newPaths.has(p)))
-        return "new";
+        return Novelty.NEW;
     if (paths.some(p => modPaths.has(p) || removedPaths.has(p)))
-        return "modified";
-    return "existing";
+        return Novelty.MODIFIED;
+    return Novelty.EXISTING;
 }
 function prioritiseCandidate(scenario, diffContext) {
     const priority = isAttackSurfaceSecurityBoundary(scenario)
-        ? "CRITICAL"
-        : CATEGORY_PRIORITY[scenario.category] ?? "LOW";
+        ? PriorityTier.CRITICAL
+        : CATEGORY_PRIORITY[scenario.category] ?? PriorityTier.LOW;
     const novelty = classifyNovelty(scenario, diffContext);
     return { priority, novelty };
 }
@@ -58,15 +58,20 @@ function computeTiebreakerSeed(endpoints, diffFiles) {
     const canonical = [...endpoints].sort().join("|") + "::" + [...diffFiles].sort().join("|");
     return crypto.createHash("sha256").update(canonical).digest("hex").slice(0, 8);
 }
-// ── Execution Plan (replaces pre-ranked + scenarios + heuristic sections) ──
-export function buildRecommendationPrompt(analysis, analysisScope = AnalysisScope.FullRepo, topN = MAX_RECOMMENDATIONS, prContext, workspaceAuthHeader, workspaceAuthType, workspaceAuthScheme, maxGenerateOverride, sessionId) {
+// Prevents bot-committed test files from being treated as application changes
+// on subsequent testbot runs on the same PR.
+const SKYRAMP_TEST_FILE_PATTERN = /(?:_test|_smoke|_contract|_fuzz|_integration|_load|_e2e|_ui)\.[^/]+$|scenario_[^/]+\.json$/;
+/**
+ * Compute the pre-ranked scenario scoring, the UI/API classification flags,
+ * and the effective GENERATE cap — extracted from buildRecommendationPrompt
+ * so skyramp_analyze_changes (SKYR-3879 Path B pre-seed) can derive the exact
+ * same candidate set the Execution Plan prompt is built from, without
+ * duplicating (and risking drift from) this scoring logic.
+ */
+export function computeScoredCandidates(analysis, analysisScope = AnalysisScope.FullRepo, topN = MAX_RECOMMENDATIONS, maxGenerateOverride) {
     const isDiffScope = isDiff(analysisScope);
     const diffContext = analysis.branchDiffContext;
-    const openApiSpec = analysis.artifacts?.openApiSpecs?.[0];
     // ── Filter out bot-generated test files from changedFiles ──
-    // Prevents bot-committed test files from being treated as application changes
-    // on subsequent testbot runs on the same PR.
-    const SKYRAMP_TEST_FILE_PATTERN = /(?:_test|_smoke|_contract|_fuzz|_integration|_load|_e2e|_ui)\.[^/]+$|scenario_[^/]+\.json$/;
     const filteredChangedFiles = diffContext
         ? diffContext.changedFiles.filter(f => !SKYRAMP_TEST_FILE_PATTERN.test(f))
         : [];
@@ -81,6 +86,56 @@ export function buildRecommendationPrompt(analysis, analysisScope = AnalysisScop
         ? (diffContext.newEndpoints.length > 0 || diffContext.modifiedEndpoints.length > 0 || (diffContext.removedEndpoints?.length ?? 0) > 0)
         : false;
     const isUIOnlyPR = hasFrontendChanges && !hasApiChanges;
+    // ── Scoring ──
+    const baseMaxGen = Math.min(Math.max(maxGenerateOverride ?? (isDiffScope ? MAX_TESTS_TO_GENERATE : topN), 0), topN);
+    const maxGen = isUIOnlyPR ? Math.max(baseMaxGen, 1) : baseMaxGen;
+    const scenarios = analysis.businessContext.draftedScenarios;
+    let scored = [];
+    let seed = "";
+    if (!isUIOnlyPR && scenarios.length > 0) {
+        const diffFiles = filteredChangedFiles; // use filtered list so bot-committed test files don't shift the seed
+        const endpointPaths = analysis.apiEndpoints.endpoints.map(ep => ep.path);
+        seed = computeTiebreakerSeed(endpointPaths, diffFiles);
+        scored = scenarios.map(s => {
+            const result = prioritiseCandidate(s, diffContext ?? undefined);
+            return { scenario: s, ...result };
+        });
+        scored.sort((a, b) => {
+            const pa = PRIORITY_ORDER[a.priority], pb = PRIORITY_ORDER[b.priority];
+            if (pb !== pa)
+                return pb - pa;
+            const na = NOVELTY_ORDER[a.novelty], nb = NOVELTY_ORDER[b.novelty];
+            if (nb !== na)
+                return nb - na;
+            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)
+                return -1;
+            if (nameA > nameB)
+                return 1;
+            const hashA = parseInt(crypto.createHash("sha256").update(seed + a.scenario.scenarioName).digest("hex").slice(0, 8), 16);
+            const hashB = parseInt(crypto.createHash("sha256").update(seed + b.scenario.scenarioName).digest("hex").slice(0, 8), 16);
+            return hashA - hashB;
+        });
+    }
+    return { scored, filteredChangedFiles, isUIOnlyPR, hasFrontendChanges, hasApiChanges, maxGen, seed };
+}
+export function buildRecommendationPrompt(analysis, analysisScope = AnalysisScope.FullRepo, topN = MAX_RECOMMENDATIONS, prContext, workspaceAuthHeader, workspaceAuthType, workspaceAuthScheme, maxGenerateOverride, sessionId) {
+    const isDiffScope = isDiff(analysisScope);
+    const diffContext = analysis.branchDiffContext;
+    const openApiSpec = analysis.artifacts?.openApiSpecs?.[0];
+    const { scored, filteredChangedFiles, isUIOnlyPR, hasFrontendChanges, hasApiChanges, maxGen, seed, } = computeScoredCandidates(analysis, analysisScope, topN, maxGenerateOverride);
     const hasTraces = (analysis.artifacts?.traceFiles?.length ?? 0) > 0 ||
         (analysis.artifacts?.playwrightRecordings?.length ?? 0) > 0;
     // ── Mode preamble ──
@@ -277,50 +332,7 @@ ${isDiffScope ? "Changed endpoints only. " : ""}Use source code schemas (Zod/Pyd
 ${detailBlocks}
 `;
     }
-    // ── Scoring ──
     const endpointCount = allEndpoints.reduce((acc, ep) => acc + (ep.methods ?? []).length, 0);
-    const baseMaxGen = Math.min(Math.max(maxGenerateOverride ?? (isDiffScope ? MAX_TESTS_TO_GENERATE : topN), 0), topN);
-    const maxGen = isUIOnlyPR ? Math.max(baseMaxGen, 1) : baseMaxGen;
-    const scenarios = analysis.businessContext.draftedScenarios;
-    let scored = [];
-    let seed = "";
-    if (!isUIOnlyPR && scenarios.length > 0) {
-        const diffFiles = filteredChangedFiles; // use filtered list so bot-committed test files don't shift the seed
-        const endpointPaths = allEndpoints.map(ep => ep.path);
-        seed = computeTiebreakerSeed(endpointPaths, diffFiles);
-        scored = scenarios.map(s => {
-            const result = prioritiseCandidate(s, diffContext ?? undefined);
-            return { scenario: s, ...result };
-        });
-        scored.sort((a, b) => {
-            const pa = PRIORITY_ORDER[a.priority], pb = PRIORITY_ORDER[b.priority];
-            if (pb !== pa)
-                return pb - pa;
-            const na = NOVELTY_ORDER[a.novelty], nb = NOVELTY_ORDER[b.novelty];
-            if (nb !== na)
-                return nb - na;
-            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)
-                return -1;
-            if (nameA > nameB)
-                return 1;
-            const hashA = parseInt(crypto.createHash("sha256").update(seed + a.scenario.scenarioName).digest("hex").slice(0, 8), 16);
-            const hashB = parseInt(crypto.createHash("sha256").update(seed + b.scenario.scenarioName).digest("hex").slice(0, 8), 16);
-            return hashA - hashB;
-        });
-    }
     // ── Main section: execution plan, UI-only guidance, or draft-your-own ──
     let mainSection;
     if (!isDiffScope && scored.length > 0) {

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

@@ -1,10 +1,11 @@
 import { jest } from "@jest/globals";
+import { Novelty, PriorityTier } from "../../types/TestRecommendation.js";
 import { TestType } from "../../types/TestTypes.js";
 jest.unstable_mockModule("@skyramp/skyramp", () => ({
     WorkspaceConfigManager: { create: jest.fn() },
 }));
 const { buildRecommendationPrompt, buildExternalCoverageSet, externalDedupKey } = await import("./test-recommendation-prompt.js");
-const { buildExecutionPlan } = await import("./diffExecutionPlan.js");
+const { buildExecutionPlan, EXEC_STEP_REGISTER } = await import("./diffExecutionPlan.js");
 const { PATH_PARAM_UUID_GUIDANCE, MAX_TESTS_TO_GENERATE, buildTestQualityCriteria, buildArchitectPreamble, buildContextFetchingGuidance, buildReasoningProtocol, buildFewShotExamples, buildVerificationChecklist, } = await import("./recommendationSections.js");
 import { AnalysisScope } from "../../types/RepositoryAnalysis.js";
 // ---------------------------------------------------------------------------
@@ -746,6 +747,42 @@ describe("buildRecommendationPrompt — zero-classified diff (SKYR-3820)", () =>
     });
 });
 // ---------------------------------------------------------------------------
+// Tests — REGISTER step (SKYR-3879 Path B checkpoint)
+// ---------------------------------------------------------------------------
+describe("buildRecommendationPrompt — REGISTER step (SKYR-3879 Path B)", () => {
+    it("diff-scope execution plan includes the REGISTER step and its skyramp_register_test_plan instruction", () => {
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 5);
+        expect(prompt).toContain(`Step ${EXEC_STEP_REGISTER} — Register your test plan`);
+        expect(prompt).toContain("skyramp_register_test_plan");
+    });
+    it("diff-scope execution plan's GENERATE header references the REGISTER step", () => {
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 5);
+        expect(prompt).toContain(`registering via Step ${EXEC_STEP_REGISTER}`);
+    });
+    it("full-repo mode (no execution plan) never mentions skyramp_register_test_plan", () => {
+        const scenariosForFullRepo = [
+            minimalScenario({
+                scenarioName: "scenario-0",
+                category: "crud",
+                priority: "low",
+                testType: TestType.CONTRACT,
+                steps: [{ order: 1, method: "GET", path: "/api/items", description: "Get items", interactionType: "success", expectedStatusCode: 200 }],
+            }),
+        ];
+        const analysis = minimalAnalysis({
+            businessContext: { mainPurpose: "Test API", userFlows: [], dataFlows: [], integrationPatterns: [], draftedScenarios: scenariosForFullRepo },
+        });
+        const prompt = buildRecommendationPrompt(analysis, AnalysisScope.FullRepo, 6);
+        expect(prompt).not.toContain("skyramp_register_test_plan");
+    });
+    it("diff-scope 'draft your own' fallback (no pre-drafted scenarios) still includes the REGISTER step — the execution plan is always used in diff scope", () => {
+        const prompt = buildRecommendationPrompt(minimalAnalysis(), AnalysisScope.CurrentBranchDiff, 5);
+        // minimalAnalysis() has no draftedScenarios and no branchDiffContext, so scored=[]
+        // but buildExecutionPlan still renders (see buildRecommendationPrompt's isDiffScope branch).
+        expect(prompt).toContain("skyramp_register_test_plan");
+    });
+});
+// ---------------------------------------------------------------------------
 // Tests — GENERATE slot allocation (UI vs backend slots)
 // ---------------------------------------------------------------------------
 describe("buildRecommendationPrompt — GENERATE slot allocation", () => {
@@ -920,13 +957,13 @@ describe("buildRecommendationPrompt — GENERATE slot allocation", () => {
         });
         const prompt = buildExecutionPlan([attackSurface, bugCaught, ordinary].map((scenario) => ({
             scenario,
-            priority: scenario.category === "crud" ? "LOW" : "CRITICAL",
-            novelty: "modified",
+            priority: scenario.category === "crud" ? PriorityTier.LOW : PriorityTier.CRITICAL,
+            novelty: Novelty.MODIFIED,
         })), 3, 3, "http://localhost:3000", "Authorization", ", authScheme: \"Bearer\"", "", "seed", 3, false, false, false, new Set(["POST::flows::contract", "POST::orders::contract", "POST::customers::contract"]));
         expect(prompt).toContain("POST /api/flows/bulk_delete → 401");
         expect(prompt).toContain("POST /api/orders → 201");
         expect(prompt).not.toContain("POST /api/customers → 201");
-        expect(prompt).toContain("except for `bug_caught` and attack-surface `security_boundary` items");
+        expect(prompt).toContain("`bug_caught` and attack-surface `security_boundary` items get the strictest reading");
     });
     it("keeps symmetric attack-surface siblings together before ordinary auth boundaries", () => {
         const directWidgets = minimalScenario({
@@ -959,8 +996,8 @@ describe("buildRecommendationPrompt — GENERATE slot allocation", () => {
         });
         const prompt = buildExecutionPlan([directWidgets, directGadgets, widgetsBulk, gadgetsBulk].map((scenario) => ({
             scenario,
-            priority: "CRITICAL",
-            novelty: "modified",
+            priority: PriorityTier.CRITICAL,
+            novelty: Novelty.MODIFIED,
         })), 3, 4, "http://localhost:3000", "Authorization", ", authScheme: \"Bearer\"", "", "seed", 4, false);
         const generatedBlock = prompt.slice(0, prompt.indexOf("#4 [ADDITIONAL]"));
         const additionalBlock = prompt.slice(prompt.indexOf("#4 [ADDITIONAL]"));
@@ -975,7 +1012,7 @@ describe("buildExecutionPlan — even-with-spillover test-type distribution", ()
     // Backend-only PR (hasFrontendChanges=false) so every GENERATE slot is a backend
     // scenario drawn from `scored` — this is where contract-vs-integration distribution
     // applies. baseUrl/auth args mirror the existing buildExecutionPlan tests above.
-    const contract = (name, path, priority = "HIGH") => ({
+    const contract = (name, path, priority = PriorityTier.HIGH) => ({
         scenario: minimalScenario({
             scenarioName: name,
             category: "crud",
@@ -983,9 +1020,9 @@ describe("buildExecutionPlan — even-with-spillover test-type distribution", ()
             steps: [{ order: 1, method: "POST", path, description: `POST ${path}`, interactionType: "success", expectedStatusCode: 201 }],
         }),
         priority: priority,
-        novelty: "new",
+        novelty: Novelty.NEW,
     });
-    const integration = (name, p1, p2, priority = "HIGH") => ({
+    const integration = (name, p1, p2, priority = PriorityTier.HIGH) => ({
         scenario: minimalScenario({
             scenarioName: name,
             category: "data_integrity",
@@ -996,7 +1033,7 @@ describe("buildExecutionPlan — even-with-spillover test-type distribution", ()
             ],
         }),
         priority: priority,
-        novelty: "new",
+        novelty: Novelty.NEW,
     });
     const plan = (items, maxGen, topN) => buildExecutionPlan(items, maxGen, topN, "http://localhost:3000", "Authorization", ", authScheme: \"Bearer\"", "", "seed", items.length, false);
     it("distributes GENERATE slots across contract AND integration when budget < candidates", () => {
@@ -1025,7 +1062,7 @@ describe("buildExecutionPlan — even-with-spillover test-type distribution", ()
         // A CRITICAL integration sits after several HIGH contracts in rank order.
         const items = [
             contract("c1", "/api/a"), contract("c2", "/api/b"), contract("c3", "/api/c"),
-            integration("crit", "/api/orders", "/api/orders/{id}", "CRITICAL"),
+            integration("crit", "/api/orders", "/api/orders/{id}", PriorityTier.CRITICAL),
         ];
         const prompt = plan(items, 3, 6);
         const generated = prompt.slice(0, prompt.indexOf("[ADDITIONAL]") >= 0 ? prompt.indexOf("[ADDITIONAL]") : prompt.length);

package/build/prompts/testbot/testbot-prompts.d.ts

@@ -16,7 +16,7 @@ export interface RelatedRepository {
  */
 export declare function parseRelatedRepositories(raw: string | undefined): RelatedRepository[] | undefined;
 export declare function getTestbotPrompt(prTitle: string, prDescription: string, summaryOutputFile: string, repositoryPath: string, baseBranch?: string, maxRecommendations?: number, maxGenerate?: number, _maxCritical?: number, // Reserved — accepted for API compat but not yet wired into prompt
-prNumber?: number, userPrompt?: string, services?: Service[], uiCredentials?: string, testsRepoDir?: string, relatedRepositories?: RelatedRepository[], primaryRepo?: string): string;
+prNumber?: number, userPrompt?: string, services?: Service[], uiCredentials?: string, testsRepoDir?: string, relatedRepositories?: RelatedRepository[], primaryRepo?: string, planOnly?: boolean): string;
 /**
  * Read services from .skyramp/workspace.yml. Returns empty array if
  * the workspace file doesn't exist or can't be parsed.

package/build/prompts/testbot/testbot-prompts.js

@@ -47,7 +47,7 @@ export function parseRelatedRepositories(raw) {
     }
 }
 export function getTestbotPrompt(prTitle, prDescription, summaryOutputFile, repositoryPath, baseBranch, maxRecommendations = MAX_RECOMMENDATIONS, maxGenerate = MAX_TESTS_TO_GENERATE, _maxCritical = MAX_CRITICAL_TESTS, // Reserved — accepted for API compat but not yet wired into prompt
-prNumber, userPrompt, services, uiCredentials, testsRepoDir, relatedRepositories, primaryRepo) {
+prNumber, userPrompt, services, uiCredentials, testsRepoDir, relatedRepositories, primaryRepo, planOnly = false) {
     maxGenerate = Math.min(Math.max(maxGenerate, 0), maxRecommendations);
     // TODO(SKYR-3636 follow-up): migrate Task 1 + Task 2 step bodies to PromptPlan
     // (src/prompts/test-recommendation/promptPlan.ts) so step numbers don't have
@@ -65,6 +65,17 @@ prNumber, userPrompt, services, uiCredentials, testsRepoDir, relatedRepositories
     // testDirectory, relative to the delivery root (the configured test repo if set,
     // otherwise the primary repo).
     const hasRelatedRepos = !!relatedRepositories?.length;
+    // Task 1 maintenance step 2c branches in plan-only eval runs (SKYR-3879
+    // plan-only lane): the SUT is not running, so the pre-edit baseline
+    // execution is replaced by static-analysis-only verdicts. Defined before
+    // task1Section, which interpolates it.
+    let maintenanceBeforeExecStep;
+    if (planOnly) {
+        maintenanceBeforeExecStep = `   c. Plan-only run: skip the pre-edit baseline execution — the application is not running. Record every maintenance verdict from static drift analysis alone; execution statuses simply remain unrecorded.`;
+    }
+    else {
+        maintenanceBeforeExecStep = `   c. Call \`skyramp_execute_test\` with \`phase: "before"\` and \`stateFile\` for every UPDATE/REGENERATE/DELETE test. Exclude tests marked \`[external]\`. Run them sequentially, not in parallel. This captures the pre-edit baseline — do not skip even if you expect the test to fail.`;
+    }
     // For follow-up requests: emit the @skyramp-testbot header + guardrails + retrieve-recommendations step.
     // For first-run prompts: emit the full Task 1 analysis + maintenance section.
     const task1Section = userPrompt
@@ -131,7 +142,7 @@ ${hasRelatedRepos ? `
 
    b. Write \`updateInstructions\` for each UPDATE or REGENERATE test before calling \`skyramp_actions\` — articulating the change first prevents file content from overriding diff-based reasoning.
 
-   c. Call \`skyramp_execute_test\` with \`phase: "before"\` and \`stateFile\` for every UPDATE/REGENERATE/DELETE test. Exclude tests marked \`[external]\`. Run them sequentially, not in parallel. This captures the pre-edit baseline — do not skip even if you expect the test to fail.
+${maintenanceBeforeExecStep}
 
    d. Call \`skyramp_actions\` with \`stateFile\` (from \`skyramp_analyze_changes\` output) and apply the edits it returns.
 
@@ -343,19 +354,37 @@ ${hasRelatedRepos ? `
     const testDirInstruction = testsRepoDir
         ? `the \`<output_dir>\` from the \`<services>\` block, rooted under the test repository at \`${testsRepoDir}\` (i.e. \`${testsRepoDir}/<output_dir>\`). Write ALL test output files to paths under \`${testsRepoDir}\`, not under \`${repositoryPath}\`. Do NOT write any test files to the app repository.`
         : `${SERVICE_REFS.testDirRef}. Do NOT create a new \`tests/\` directory at the repo root — use that path. If no \`testDirectory\` is configured, default to the language-conventional location (e.g. \`src/test/java/...\` for Java, \`tests/\` for Python).`;
-    const primaryRepoBlock = primaryRepo ? `<REPOSITORY>${primaryRepo}</REPOSITORY>\n` : '';
-    return `<TITLE>${prTitle}</TITLE>
-<DESCRIPTION>${prDescription}</DESCRIPTION>
-${primaryRepoBlock}<REPOSITORY PATH>${repositoryPath}</REPOSITORY PATH>
-${relatedReposBlock}${testsRepoDirBlock}${serviceContext ? serviceContext + '\n' : ''}${uiCredentialsBlock ? uiCredentialsBlock + '\n' : ''}Use the Skyramp MCP server tools for all tasks below.
-
-${task1Section}
-
-## Task 2: Generate New Tests
+    // Task 3's non-zero-budget count rule branches in plan-only eval runs: the
+    // report DECLARES the final GENERATE selection instead of recording
+    // generated files. The zero-surface abstention rules above it are shared.
+    let task3CountRule;
+    if (planOnly) {
+        task3CountRule = `Otherwise (your Budget Plan is non-zero): this is a plan-only run — \`newTestsCreated\` DECLARES your final GENERATE selection instead of recording generated files: exactly one entry per item of your final GENERATE list (the list returned by \`skyramp_register_test_plan\` when that tool was available — it may contain fewer items than your committed budget — otherwise your Budget Plan selection, at most ${maxGenerate}), with \`fileName\` set to the file name you would have used. \`testResults\` must be \`[]\` — nothing was executed. The declaration itself is the deliverable; do not generate or backfill.`;
+    }
+    else {
+        task3CountRule = `Otherwise (your Budget Plan is non-zero): in \`newTestsCreated\`, you must have exactly as many budget-counting new tests as your committed Budget Plan's generate count (at most ${maxGenerate}). Only new files (ADD) created for the planned GENERATE items count toward this target — GENERATE items converted to UPDATE do not. You may also include at most one additional discovered-scenario file in \`newTestsCreated\` (the bug-catching test generated after all planned items); that extra test does **not** count against the budget. If you have fewer budget-counting new tests than your generate count, backfill from the remaining ADDITIONAL candidates before proceeding. Only proceed with fewer if all candidates failed after retry AND the fallback single-contract test also failed.`;
+    }
+    // Task 2 branches wholesale in plan-only eval runs (SKYR-3879 plan-only
+    // lane): the standard task mandates generation and execution, which a
+    // plan-only run must not do — branching the section (rather than appending
+    // an override) means the agent never sees conflicting instructions.
+    let task2Section;
+    if (planOnly) {
+        task2Section = `## Task 2: Commit the Test Plan (plan-only run)
+
+This is a plan-only evaluation run: the application under test is NOT running, and this run evaluates test SELECTION only. Nothing is generated or executed in this task.
+
+- Draft your complete candidate list exactly as the Execution Plan directs — every API test (contract / integration / batch-scenario) you would generate OR recommend for this PR, grounded in the analysis output and the diff. Favor tests that would FAIL if the changed logic were buggy, not just tests that exercise the new surface.
+- If a tool named \`skyramp_register_test_plan\` is available, call it with the full candidate union — include a \`discriminator\` claim \`{kind, changedCodeAnchor}\` for every candidate that probes changed logic — and treat its returned GENERATE list as your final selection. If that tool is not available, commit to your Budget Plan's GENERATE selection (at most ${maxGenerate}).
+- Skip UI and E2E candidates entirely — with no running app there are no blueprints to ground them, and this lane evaluates API test selection only.
+- Take no other actions in this task: no test generation tools, no browser traces or blueprint captures, no test files written, no test executions. Proceed directly to ${taskRef(TASK_SUBMIT)}.`;
+    }
+    else {
+        task2Section = `## Task 2: Generate New Tests
 
 ${userPrompt ? "Generate only the tests that the user requested from the Additional Recommendations. The rules below still apply." : "Drift-based maintenance (Task 1) is complete. This step only processes the GENERATE list. Exception: if a GENERATE item targets a resource with an existing `[skyramp]` contract test, UPDATE that test file (see covered-resource handling below) — a new test case added to an existing file counts toward the budget and is reported in `newTestsCreated`."}
 
-- **MANDATORY — use the pre-ranked GENERATE list as-is**: The Execution Plan's GENERATE section governs ADD actions. You MUST generate exactly those scenarios in the exact order listed. Do NOT substitute, rename, or replace a GENERATE item. If parameter grounding uncovers a distinct bug-catching scenario not already in the GENERATE or ADDITIONAL list, generate it after all planned GENERATE items are complete and report it in \`newTestsCreated\` — this is an additional test driven by source-code analysis and does not count against the GENERATE budget.${hasRelatedRepos ? `\n  - **Multi-repo exception:** this run has related repositories, so the per-repo GENERATE lists are NOT final — they are candidates re-selected by the cross-repo round-robin described in Task 1's "Cross-repo test generation". Follow that pooled, type-distributed selection instead of any single repo's GENERATE list. (In single-repo runs the GENERATE list IS final — generate it exactly as-is.)` : ""}
+- **MANDATORY — use the plan returned by \`skyramp_register_test_plan\` as-is**: Before generating anything, call \`skyramp_register_test_plan\` (\`stateFile\` required) with your complete candidate list — every test you would generate OR recommend, including the Execution Plan's own pre-ranked GENERATE/ADDITIONAL items and any candidate you drafted yourself, with a \`discriminator\` claim \`{kind, changedCodeAnchor}\` for candidates probing changed logic. Its returned GENERATE list — not the Execution Plan's raw pre-ranked GENERATE section — governs ADD actions from this point on. You MUST generate exactly those scenarios in the exact order listed, keeping each item's \`scenarioName\` exactly as registered — the generation tools match on it and reject renamed or substituted scenarios. If parameter grounding uncovers a distinct bug-catching scenario not already registered, generate it after all planned GENERATE items are complete and report it in \`newTestsCreated\` — this is an additional test driven by source-code analysis and does not count against the GENERATE budget.${hasRelatedRepos ? `\n  - **Multi-repo exception:** this run has related repositories, so the per-repo GENERATE lists are NOT final — they are candidates re-selected by the cross-repo round-robin described in Task 1's "Cross-repo test generation". Register the pooled, type-distributed selection instead of any single repo's GENERATE list. (In single-repo runs, register the GENERATE list exactly as-is.)` : ""}
 - **Do not fabricate tests outside the GENERATE list.** New test files cover NEW observable surface only — a new endpoint, or a newly-integrated component/route not already covered by an existing test. Changes that only modify, delete, or add fields to an EXISTING covered endpoint or component are maintenance: handle them in ${taskRef(TASK_ANALYZE_MAINTAIN)} by UPDATE/DELETE of the existing test, never by creating a new spec. If the GENERATE list is empty (deletion-only, cosmetic, or modification-of-existing PRs with no new surface), create zero new tests and proceed to ${taskRef(TASK_SUBMIT)} — do not invent a new spec to have something to report.
 - Scenario JSON files are always new files — always generate them for new methods. Every generated scenario JSON must have a corresponding new integration test generated from it via \`skyramp_integration_test_generation\`.
 - Covered-resource handling (aligns with Execution Plan Step 0): When a GENERATE item targets a resource that already has an existing test file covering the same endpoint:
@@ -416,7 +445,7 @@ ${userPrompt ? "Generate only the tests that the user requested from the Additio
 ${CONTRACT_MODE_GUIDANCE}
 - ${PATH_PARAM_UUID_GUIDANCE}
 - **UI**: First check for existing Playwright trace \`.zip\` files in the repo (Testbot scans recursively up to 5 directory levels — the per-service output directories, \`frontend/\`, \`public/\`, \`.skyramp/\`, or any subdirectory).
-  If a relevant trace exists (covers the UI changes in this PR), use it directly with \`skyramp_ui_test_generation\` and \`modularizeCode: false\`.
+  If a relevant trace exists (covers the UI changes in this PR), use it directly with \`skyramp_ui_test_generation\`, \`modularizeCode: false\`, and \`codeReuse: true\` (when generating a TypeScript/JavaScript Playwright test — the default; leave \`codeReuse\` unset for other languages).
   If NO relevant trace exists, **you MUST write out your full trace plan as text BEFORE calling \`browser_navigate\`**. Do not touch the browser until the plan is written.
 
   **Browser authentication (check BEFORE navigating)**: If \`<ui-credentials>\` appears in your context above, the app requires login. Parse the credentials — one per line, two supported formats:
@@ -460,7 +489,7 @@ ${CONTRACT_MODE_GUIDANCE}
   Follow the **UI Recording Workflow** section at the end of this prompt. Additional CI constraints:
   - Navigate **directly** to the deepest relevant URL (e.g. \`/orders/1/edit\` instead of \`/\` then \`/orders\` then \`/orders/1\`) — minimize multi-hop navigation so the trace stays focused on the scenario under test.
   - \`skyramp_export_zip\` outputPath: \`${repositoryPath}/.skyramp/<test_name>_trace.zip\`
-  - \`skyramp_ui_test_generation\`: set \`modularizeCode: false\`
+  - \`skyramp_ui_test_generation\`: set \`modularizeCode: false\` and \`codeReuse: true\` (TypeScript/JavaScript Playwright only — the default; leave \`codeReuse\` unset for other languages)
   - **\`browser_assert\` — MANDATORY**: at least one per page navigated. Call multiple assertions in the same tool call batch when checking independent elements. If you navigate to 2 pages, assert on both. Each assertion should verify a business outcome (state change, computed value, error condition) — not just that an element is visible.
   - **\`browser_visual_snapshot\` — for visual/appearance checks**: when the instruction asks to take a screenshot, capture a baseline, or verify how a page/element/region *looks* (not its text or value), call \`browser_visual_snapshot\` — it records a \`toHaveScreenshot()\` assertion so the generated test pixel-compares against a baseline on every run. Do NOT use \`browser_take_screenshot\` for this: it captures a throwaway image that is dropped at export and never appears in the generated test (use it only to view the page yourself).
   - **Wait for stable state before the second capture**: After performing an action that affects computed fields (filling a discount, submitting a form, adding an item), check the current page state before calling the second \`browser_blueprint\` (the capture after the action). If a computed field — total, price, count, derived text — still shows its initial empty or zero value (e.g. \`$0.00\`, \`0\`, \`Loading...\`, empty string), that means async data hasn't finished loading yet. Use \`browser_wait_for\` to wait up to 10 seconds for the field to update to a real value (for example, wait for the total to show a non-zero amount like \`$799.99\` instead of \`$0.00\`). Once the field shows a real value, THEN call the second \`browser_blueprint\` to capture stable state. If after 10 seconds the field still hasn't updated, skip the assertion on that field — don't capture and assert a value that hasn't loaded.
@@ -512,7 +541,7 @@ ${CONTRACT_MODE_GUIDANCE}
 
   **The Blueprint Citation Invariant applies during recording too.** Every assertion you emit cites element names — those names must come from blueprint captures, not invention. For N user-intent-level actions, the reference target is N+1 \`browser_blueprint\` calls (the first returns full, the rest return deltas). Traces that follow the pattern produce assertions grounded in observable state changes; traces that skip captures fall back to author-inferred assertions and risk citing names that don't exist in the rendered DOM.
 
-  The rest of the UI workflow stays the same: trace plan, browser auth, navigation, export (\`skyramp_export_zip\`), generation (\`skyramp_ui_test_generation\`), \`skyramp_enhance_assertions\` post-call. Capture-act-capture adds blueprint captures alongside the existing steps; it doesn't replace anything.
+  The rest of the UI workflow stays the same: trace plan, browser auth, navigation, export (\`skyramp_export_zip\`), generation (\`skyramp_ui_test_generation\`), then \`skyramp_reuse_code\` (when \`codeReuse: true\`) and \`skyramp_enhance_assertions\` post-calls. Capture-act-capture adds blueprint captures alongside the existing steps; it doesn't replace anything.
 - **E2E**: Only if BOTH a backend trace \`.json\` AND a Playwright \`.zip\` already exist in the repo. Without both, move to \`additionalRecommendations\`.
 - Skip smoke tests entirely.
 
@@ -545,13 +574,24 @@ Do NOT use \`page.waitForTimeout()\` with fixed delays. Do NOT retry more than o
 **After generation, you MUST do exactly these steps — nothing more, nothing less:**
 1. **[MANDATORY] After \`skyramp_integration_test_generation\`**: Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated integration test file, \`testType: "integration"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file.
 2. **[MANDATORY] After \`skyramp_contract_test_generation\` with \`providerMode\`**: Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated provider contract test file, \`testType: "contract"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file.
-3. **[MANDATORY] After \`skyramp_ui_test_generation\`**: Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated UI test file, \`testType: "ui"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file. The HIGH-tier \`possibleAssertions\` from your second \`browser_blueprint\` captures (after each action) during trace recording are in your context — when the enhance instructions ask you to add assertions for state-changing actions, use those grounded candidates first (they contain exact computed values from the DOM delta, e.g. \`toHaveText('Total: $899.98')\`). Only fall back to deriving values from the test file or source code when no HIGH-tier candidate covers the action.
-4. **Wait**: Do NOT proceed to test execution until steps 1–3 are complete and the verification checklist in the \`skyramp_enhance_assertions\` tool result has been validated for EVERY generated test file.
-Do not make any changes other than the assertion enhancements described above. For example: do not modify auth headers, cookies, tokens, env vars, or imports that the generation tool already set correctly — those are correct by construction and changing them breaks auth or execution.
+3. **[MANDATORY] After \`skyramp_ui_test_generation\` with \`codeReuse: true\`**: the generation result directs you to call \`skyramp_reuse_code\` — do this BEFORE \`skyramp_enhance_assertions\`. Two outcomes: (1) a response starting "No reusable POM layer detected" — this is a normal outcome, continue immediately (do NOT retry), and note "no POM layer — reuse skipped" in that test's \`testResults\` entry \`details\`; (2) a refactoring workflow — follow it to completion INCLUDING its verification loop (\`skyramp_reuse_code\` with \`verify: true\`), finish only when it reports PASSED, and include \`verification: passed\` in that test's \`testResults\` entry \`details\` in your final report. If a reused test later fails execution and the failure points at a substituted POM call, restore the saved \`<testFile>.raw.bak\` over the test file and re-run — do NOT hand-edit the customer's POM methods (this re-run counts toward the 2-attempt execution cap — prefer this restore over the generic timeout fix-up when the failing locator came from a POM substitution).
+4. **[MANDATORY] After \`skyramp_ui_test_generation\`**: Call \`skyramp_enhance_assertions\` with \`testFile\` set to the absolute path of the generated UI test file, \`testType: "ui"\`, and \`enhanceType: "generation"\`. Apply every instruction returned to that file. The HIGH-tier \`possibleAssertions\` from your second \`browser_blueprint\` captures (after each action) during trace recording are in your context — when the enhance instructions ask you to add assertions for state-changing actions, use those grounded candidates first (they contain exact computed values from the DOM delta, e.g. \`toHaveText('Total: $899.98')\`). Only fall back to deriving values from the test file or source code when no HIGH-tier candidate covers the action.
+5. **Wait**: Do NOT proceed to test execution until steps 1–4 are complete and the verification checklist in the \`skyramp_enhance_assertions\` tool result has been validated for EVERY generated test file.
+Do not make any changes other than the code-reuse refactoring (step 3) and the assertion enhancements described above. For example: do not modify auth headers, cookies, tokens, env vars, or imports that the generation tool already set correctly — those are correct by construction and changing them breaks auth or execution.
 
 **Final execution (mandatory):** Do NOT call \`skyramp_execute_test\` until ALL maintenance edits AND ALL new test generation/enhancement are complete. Run these calls sequentially, not in parallel. Exclude tests marked \`[external]\`.
 - Only report test results for files you actually ran.
-**Auth**: If \`skyramp_analyze_changes\` reports an auth token or \`SKYRAMP_TEST_TOKEN\` is set, pass it in **every** \`skyramp_execute_test\` call from the first attempt — do NOT wait for a 401/403 to discover auth is needed.
+**Auth**: If \`skyramp_analyze_changes\` reports an auth token or \`SKYRAMP_TEST_TOKEN\` is set, pass it in **every** \`skyramp_execute_test\` call from the first attempt — do NOT wait for a 401/403 to discover auth is needed.`;
+    }
+    const primaryRepoBlock = primaryRepo ? `<REPOSITORY>${primaryRepo}</REPOSITORY>\n` : '';
+    return `<TITLE>${prTitle}</TITLE>
+<DESCRIPTION>${prDescription}</DESCRIPTION>
+${primaryRepoBlock}<REPOSITORY PATH>${repositoryPath}</REPOSITORY PATH>
+${relatedReposBlock}${testsRepoDirBlock}${serviceContext ? serviceContext + '\n' : ''}${uiCredentialsBlock ? uiCredentialsBlock + '\n' : ''}Use the Skyramp MCP server tools for all tasks below.
+
+${task1Section}
+
+${task2Section}
 
 ## Task 3: Submit Report
 
@@ -571,7 +611,7 @@ In these cases:
 - \`businessCaseAnalysis\` must be a one-sentence summary of what the PR actually does (do NOT leave it blank)
 - \`additionalRecommendations\` must be \`[]\` — do NOT recommend tests for a no-surface PR
 
-Otherwise (your Budget Plan is non-zero): in \`newTestsCreated\`, you must have exactly as many budget-counting new tests as your committed Budget Plan's generate count (at most ${maxGenerate}). Only new files (ADD) created for the planned GENERATE items count toward this target — GENERATE items converted to UPDATE do not. You may also include at most one additional discovered-scenario file in \`newTestsCreated\` (the bug-catching test generated after all planned items); that extra test does **not** count against the budget. If you have fewer budget-counting new tests than your generate count, backfill from the remaining ADDITIONAL candidates before proceeding. Only proceed with fewer if all candidates failed after retry AND the fallback single-contract test also failed.
+${task3CountRule}
 
 Call \`skyramp_submit_report\` with \`summaryOutputFile\`: "${summaryOutputFile}" and \`stateFile\` (from \`skyramp_analyze_changes\` output) — the stateFile is required for execution outcome tracking. Field names, types, and formats are defined in the tool's parameter schema — follow them exactly.
 
@@ -683,10 +723,16 @@ export function registerTestbotPrompt(server) {
                 .string()
                 .optional()
                 .describe("The primary repository's owner/repo slug (where the testbot workflow runs). Used verbatim as the `repository` attribution for the primary repo's analysis, tests, and report items in multi-repo runs."),
+            planOnly: z
+                // Prompt/resource URL args arrive as strings — accept "true"/"1"
+                // alongside a real boolean; anything else (incl. undefined) is false.
+                .preprocess((v) => v === true || v === "true" || v === "1", z.boolean())
+                .optional()
+                .describe("Plan-only eval mode (eval harness only, SKYR-3879): run the full recommendation phase — analysis, maintenance verdicts, candidate drafting, plan registration — but generate and execute nothing; the report declares the final plan. Used by the eval pipeline to A/B selection changes without a running SUT."),
         },
     }, async (args) => {
         const services = await readWorkspaceServices(args.repositoryPath);
-        let prompt = getTestbotPrompt(args.prTitle, args.prDescription, args.summaryOutputFile, args.repositoryPath, args.baseBranch, args.maxRecommendations, args.maxGenerate, args.maxCritical, args.prNumber, args.userPrompt, services.length ? services : undefined, args.uiCredentials, args.testsRepoDir, parseRelatedRepositories(args.relatedRepositories), args.primaryRepo);
+        let prompt = getTestbotPrompt(args.prTitle, args.prDescription, args.summaryOutputFile, args.repositoryPath, args.baseBranch, args.maxRecommendations, args.maxGenerate, args.maxCritical, args.prNumber, args.userPrompt, services.length ? services : undefined, args.uiCredentials, args.testsRepoDir, parseRelatedRepositories(args.relatedRepositories), args.primaryRepo, args.planOnly);
         if (args.workspaceValidationFailed) {
             prompt = buildWorkspaceRecoveryPrefix(args.repositoryPath) + prompt;
         }