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

package/build/tools/test-management/registerTestPlanTool.js

@@ -0,0 +1,329 @@
+import { z } from "zod";
+import { TOOL_BATCH_SCENARIO_TEST_GENERATION, TOOL_CONTRACT_TEST_GENERATION, TOOL_E2E_TEST_GENERATION, TOOL_INTEGRATION_TEST_GENERATION, TOOL_REGISTER_TEST_PLAN, TOOL_UI_TEST_GENERATION, } from "../../toolNames.js";
+import * as path from "path";
+import * as crypto from "crypto";
+import { logger } from "../../utils/logger.js";
+import { StateManager, } from "../../utils/AnalysisStateManager.js";
+import { toolError } from "../../utils/utils.js";
+import { buildApprovedPlanItem } from "../../utils/planMatchKeys.js";
+import { SCENARIO_CATEGORIES, CATEGORY_PRIORITY, Novelty, PriorityTier } from "../../types/TestRecommendation.js";
+import { HttpMethod, TestType } from "../../types/TestTypes.js";
+import { CandidateSource, computeCandidateId, DiscriminatorKind } from "../../types/Recommendation.js";
+import { selectPlan } from "../../recommendation/planRanker.js";
+import { validateDiscriminator } from "../../recommendation/discriminators.js";
+import { isAttackSurfaceSecurityBoundary } from "../../prompts/test-recommendation/recommendationShared.js";
+import { MAX_RECOMMENDATIONS, MAX_TESTS_TO_GENERATE } from "../../prompts/test-recommendation/recommendationSections.js";
+const TOOL_NAME = TOOL_REGISTER_TEST_PLAN;
+// ── Zod schema ──────────────────────────────────────────────────────────────
+/** Test types eligible for a registered test plan — a subset of TestType
+ *  (excludes smoke/fuzz/load/mock/unit/unknown, which this checkpoint doesn't
+ *  govern). */
+const PLAN_TEST_TYPES = new Set([
+    TestType.CONTRACT,
+    TestType.INTEGRATION,
+    TestType.E2E,
+    TestType.UI,
+]);
+const chainingRefSchema = z.object({
+    sourceStep: z.number().int(),
+    sourceField: z.string(),
+    sourceLocation: z.enum(["body", "header", "cookie"]),
+    targetParam: z.string(),
+    targetLocation: z.enum(["path", "body", "query", "header", "cookie"]),
+});
+const registerStepSchema = z.object({
+    order: z.number().int().min(1).describe("Order of this step within the scenario, starting at 1."),
+    method: z.nativeEnum(HttpMethod).describe("HTTP method of this step's request."),
+    path: z.string().describe("Endpoint path, e.g. '/api/v1/products/{product_id}'."),
+    description: z.string().describe("What this step does."),
+    interactionType: z
+        .enum(["success", "error", "edge-case"])
+        .describe("Whether this step exercises the happy path, an expected error, or an edge case."),
+    requestBody: z
+        .record(z.any())
+        .optional()
+        .describe("Request body fields with concrete values. Used to verify boundary_equality claims (two distinct fields with equal values)."),
+    queryParams: z
+        .record(z.any())
+        .optional()
+        .describe("Query parameters with concrete values. Also scanned for boundary_equality and negative_match verification."),
+    responseBody: z.record(z.any()).optional().describe("Expected response body shape/values, when asserted."),
+    expectedStatusCode: z.number().int().describe("HTTP status code this step asserts (e.g. 201, 400, 404)."),
+    expectedResponseFields: z
+        .array(z.string())
+        .optional()
+        .describe("Response fields (optionally with expected values, e.g. 'account_count=2') this step asserts. Used to verify multi_record_aggregate claims."),
+    bodyMustInclude: z
+        .array(z.string())
+        .optional()
+        .describe("Fields that MUST appear in the request body for this step."),
+    chainsFrom: z.union([chainingRefSchema, z.array(chainingRefSchema)]).optional(),
+});
+const discriminatorClaimSchema = z.object({
+    kind: z.nativeEnum(DiscriminatorKind),
+    changedCodeAnchor: z
+        .string()
+        .min(1)
+        .describe("Verbatim snippet copied EXACTLY from the diff that this test probes. Must occur character-for-character in the PR diff to verify — a paraphrase or reconstruction will fail verification and demote the claim."),
+});
+const registerCandidateSchema = z.object({
+    scenarioName: z.string().min(1).describe("Name for this test/scenario. Reused as the match key against the generation tool's scenarioName — keep it identical when you later call the generation tool."),
+    description: z.string().min(1),
+    category: z.enum(SCENARIO_CATEGORIES).describe("Test category — drives ranking (never your own priority tag)."),
+    priority: z.enum(["high", "medium", "low"]).describe("Your own assessment — recorded, but ranking is derived from category, not this field."),
+    testType: z.nativeEnum(TestType).refine((t) => PLAN_TEST_TYPES.has(t), {
+        message: `testType must be one of ${[...PLAN_TEST_TYPES].join(", ")}`,
+    }),
+    steps: z.array(registerStepSchema).min(1),
+    discriminator: discriminatorClaimSchema
+        .optional()
+        .describe("Declare when this candidate specifically probes changed logic (a structural bug-shape). Verified against `steps[]` and the PR diff — a failed claim demotes (with a reason) but never rejects the candidate."),
+});
+const registerTestPlanSchema = {
+    stateFile: z
+        .string()
+        .refine((p) => path.isAbsolute(p), { message: "stateFile must be an absolute path" })
+        .describe("Path to state file from skyramp_analyze_changes"),
+    repository: z
+        .string()
+        .optional()
+        .describe("The owner/repo whose analysis section to register against (e.g. 'letsramp/api-insight'). In a multi-repo run, ALWAYS set it. Omit only for a single-repo run."),
+    candidates: z
+        .array(registerCandidateSchema)
+        .default([])
+        .describe("Your COMPLETE candidate list — every test you would generate OR recommend this run, including ones already suggested by skyramp_analyze_changes. Merged with any server pre-ranked candidates, re-ranked, and split into GENERATE vs ADDITIONAL. Call this again (with your full updated list) if you want to add or change candidates — each call replaces your previous submission."),
+};
+// ── Handler helpers ─────────────────────────────────────────────────────────
+function derivePriorityTier(scenario) {
+    if (isAttackSurfaceSecurityBoundary(scenario))
+        return PriorityTier.CRITICAL;
+    return CATEGORY_PRIORITY[scenario.category] ?? PriorityTier.LOW;
+}
+function toScenarioStep(step) {
+    return {
+        order: step.order,
+        method: step.method,
+        path: step.path,
+        description: step.description,
+        interactionType: step.interactionType,
+        requestBody: step.requestBody,
+        queryParams: step.queryParams,
+        responseBody: step.responseBody,
+        expectedStatusCode: step.expectedStatusCode,
+        expectedResponseFields: step.expectedResponseFields,
+        bodyMustInclude: step.bodyMustInclude,
+        chainsFrom: step.chainsFrom,
+    };
+}
+function toDraftedScenario(input) {
+    return {
+        scenarioName: input.scenarioName,
+        description: input.description,
+        category: input.category,
+        priority: input.priority,
+        steps: input.steps.map(toScenarioStep),
+        chainingKeys: [],
+        requiresAuth: false,
+        estimatedComplexity: "moderate",
+        testType: input.testType,
+    };
+}
+/** Build the agent-submitted candidates, running discriminator verification
+ *  against the persisted diff text. Failed claims demote (never reject). */
+function buildAgentCandidates(candidates, diffText) {
+    const demotions = [];
+    const built = candidates.map((input) => {
+        const scenario = toDraftedScenario(input);
+        const candidateId = computeCandidateId(scenario);
+        let verifiedDiscriminator;
+        if (input.discriminator) {
+            const claim = input.discriminator;
+            const result = validateDiscriminator(scenario, claim, diffText);
+            if (result.verified) {
+                verifiedDiscriminator = claim.kind;
+            }
+            else {
+                demotions.push({
+                    candidateId,
+                    reason: result.reason ?? `${claim.kind} discriminator claim could not be verified.`,
+                });
+            }
+        }
+        const candidate = {
+            scenario,
+            priority: derivePriorityTier(scenario),
+            novelty: Novelty.NEW,
+            source: CandidateSource.AGENT,
+            candidateId,
+            ...(verifiedDiscriminator ? { verifiedDiscriminator } : {}),
+        };
+        return candidate;
+    });
+    return { candidates: built, demotions };
+}
+/** Recover full Candidates for pre-seeded ("server") plan items by matching
+ *  candidateId back to the analyzed scenarios (repositoryAnalysis.scenarios) —
+ *  ApprovedPlanItem is deliberately slim and doesn't carry steps[]. */
+function recoverServerCandidates(priorPlan, allScenarios) {
+    if (!priorPlan)
+        return [];
+    const scenarioById = new Map();
+    for (const scenario of allScenarios) {
+        scenarioById.set(computeCandidateId(scenario), scenario);
+    }
+    const serverItems = [...priorPlan.generate, ...priorPlan.additional].filter((item) => item.source === CandidateSource.SERVER);
+    const recovered = [];
+    for (const item of serverItems) {
+        const scenario = scenarioById.get(item.candidateId);
+        if (!scenario) {
+            logger.warning(`${TOOL_NAME}: pre-seeded server candidate ${item.candidateId} not found in repositoryAnalysis.scenarios — dropping`);
+            continue;
+        }
+        recovered.push({
+            scenario,
+            priority: derivePriorityTier(scenario),
+            novelty: Novelty.EXISTING,
+            source: CandidateSource.SERVER,
+            candidateId: item.candidateId,
+            ...(item.verifiedDiscriminator ? { verifiedDiscriminator: item.verifiedDiscriminator } : {}),
+        });
+    }
+    return recovered;
+}
+function resolveBudgetContext(stateData) {
+    const pbc = stateData.planBudgetContext;
+    return {
+        maxGenerate: pbc?.maxGenerate ?? MAX_TESTS_TO_GENERATE,
+        maxTotal: pbc?.maxTotal ?? MAX_RECOMMENDATIONS,
+        isUIOnlyPR: pbc?.isUIOnlyPR ?? false,
+        hasFrontendChanges: pbc?.hasFrontendChanges ?? false,
+        externalCoverage: new Set(pbc?.externalCoverageKeys ?? []),
+    };
+}
+function describeGenerationCall(item) {
+    switch (item.testType) {
+        case "contract":
+            return `call ${TOOL_CONTRACT_TEST_GENERATION}`;
+        case "integration":
+            return `call ${TOOL_BATCH_SCENARIO_TEST_GENERATION}, then ${TOOL_INTEGRATION_TEST_GENERATION} with the returned scenarioFile`;
+        case "e2e":
+            return `call ${TOOL_E2E_TEST_GENERATION}`;
+        case "ui":
+            return `call ${TOOL_UI_TEST_GENERATION}`;
+        default:
+            return "use the generation tool matching this testType";
+    }
+}
+function renderPlanItem(item, rank) {
+    const discriminatorNote = item.verifiedDiscriminator ? `, verified discriminator: ${item.verifiedDiscriminator}` : "";
+    return `${rank}. [${item.testType}] "${item.scenarioName}" (${item.category}${discriminatorNote}) — ${describeGenerationCall(item)}`;
+}
+function renderPlanText(plan) {
+    const lines = [];
+    lines.push(`## Approved Test Plan (${plan.planId})`);
+    lines.push("");
+    lines.push("This plan is AUTHORITATIVE and FINAL. Generation tools reject scenarios that are not in the GENERATE list below. " +
+        "If you need to add, drop, or change a candidate, call skyramp_register_test_plan again with your full updated candidate list.");
+    lines.push("");
+    lines.push(`### GENERATE (${plan.generate.length}) — generate exactly these, in this order`);
+    if (plan.generate.length === 0) {
+        lines.push("  (none — nothing to generate this run)");
+    }
+    else {
+        plan.generate.forEach((item, i) => lines.push(renderPlanItem(item, i + 1)));
+    }
+    lines.push("");
+    lines.push(`### ADDITIONAL (${plan.additional.length}) — report as recommendations; only generate if backfilling a failed GENERATE item`);
+    if (plan.additional.length === 0) {
+        lines.push("  (none)");
+    }
+    else {
+        plan.additional.forEach((item, i) => lines.push(renderPlanItem(item, plan.generate.length + i + 1)));
+    }
+    if (plan.demotions.length > 0) {
+        lines.push("");
+        lines.push(`### Demotions (${plan.demotions.length}) — discriminator claims that did NOT verify (candidate still registered, claim dropped)`);
+        for (const demotion of plan.demotions) {
+            lines.push(`- ${demotion.candidateId}: ${demotion.reason}`);
+        }
+    }
+    return lines.join("\n");
+}
+// ── Tool registration ───────────────────────────────────────────────────────
+export function registerRegisterTestPlanTool(server) {
+    server.registerTool(TOOL_NAME, {
+        annotations: {
+            destructiveHint: false,
+            readOnlyHint: false,
+            idempotentHint: false,
+            openWorldHint: false,
+        },
+        description: "REQUIRED before generation tools in testbot runs — the deterministic selection checkpoint that decides which candidate tests get generated. " +
+            "Register your COMPLETE candidate list (every test you would generate OR recommend) BEFORE calling any generation tool. " +
+            "Merges your candidates with any server pre-ranked candidates from skyramp_analyze_changes, verifies declared `discriminator` " +
+            "claims against the PR diff, re-ranks the union, and returns the mandated GENERATE list plus ADDITIONAL recommendations and " +
+            "demotion reasons for claims that failed verification. In an active testbot run, generation tools (skyramp_batch_scenario_test_generation, " +
+            "skyramp_contract_test_generation, skyramp_integration_test_generation) reject any scenario not in the returned GENERATE list — " +
+            "call this tool first, then generate exactly what it returns. Standalone/IDE MCP usage (no active testbot run) is unaffected.",
+        inputSchema: registerTestPlanSchema,
+    }, async (params) => {
+        let errorResult;
+        try {
+            logger.info(`Registering test plan${params.repository ? ` for repository ${params.repository}` : ""}`, {
+                candidateCount: params.candidates?.length ?? 0,
+            });
+            const stateManager = StateManager.fromStatePath(params.stateFile);
+            const stateData = await stateManager.readRepoData(params.repository);
+            const repositoryPath = (await stateManager.getRepoRepositoryPath(params.repository)) || "";
+            if (!stateData) {
+                errorResult = toolError(`State file is empty or invalid: ${params.stateFile}. Call skyramp_analyze_changes first to generate a valid state file.`);
+                return errorResult;
+            }
+            const diffText = stateData.diffText ?? "";
+            const allScenarios = stateData.repositoryAnalysis?.scenarios ?? [];
+            const { candidates: agentCandidates, demotions } = buildAgentCandidates(params.candidates ?? [], diffText);
+            const serverCandidates = recoverServerCandidates(stateData.approvedPlan, allScenarios);
+            // Merge by candidateId; a pre-seeded server candidate wins over an agent
+            // submission that happens to hash to the same id (identical scenario
+            // content) — source: "server" is preserved per the unified-plan design.
+            const merged = new Map();
+            for (const candidate of agentCandidates)
+                merged.set(candidate.candidateId, candidate);
+            for (const candidate of serverCandidates)
+                merged.set(candidate.candidateId, candidate);
+            const allCandidates = [...merged.values()];
+            // An empty union would persist an authoritative plan with an empty
+            // GENERATE list, which the generation gate then enforces — bricking
+            // the run until re-registration. Reject instead so the agent can
+            // self-correct in one step.
+            if (allCandidates.length === 0) {
+                errorResult = toolError("No candidates submitted and no server pre-ranked candidates exist for this run. " +
+                    "Submit your complete candidate list (every test you would generate or recommend) in `candidates` — an empty plan would block all generation.");
+                return errorResult;
+            }
+            const budgetContext = resolveBudgetContext(stateData);
+            const result = selectPlan(allCandidates, { ...budgetContext, demotions });
+            const approvedPlan = {
+                planId: crypto.randomUUID(),
+                createdAt: new Date().toISOString(),
+                generate: result.generate.map(buildApprovedPlanItem),
+                additional: result.additional.map(buildApprovedPlanItem),
+                demotions: result.demotions,
+            };
+            try {
+                await stateManager.writeRepoData({ ...stateData, approvedPlan }, { repo: params.repository, repositoryPath, step: TOOL_NAME });
+            }
+            catch (error) {
+                errorResult = toolError(`Failed to persist approved test plan to state file: ${error.message}. Retry this call.`);
+                return errorResult;
+            }
+            return {
+                content: [{ type: "text", text: renderPlanText(approvedPlan) }],
+            };
+        }
+        catch (error) {
+            errorResult = toolError(`skyramp_register_test_plan failed: ${error?.message ?? String(error)}`);
+            return errorResult;
+        }
+    });
+}

package/build/tools/test-management/registerTestPlanTool.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/tools/test-management/registerTestPlanTool.test.js

@@ -0,0 +1,296 @@
+// @ts-nocheck - Jest ESM type inference issues
+import { jest } from "@jest/globals";
+import * as fs from "fs/promises";
+import * as path from "path";
+import * as os from "os";
+import { z } from "zod";
+jest.unstable_mockModule("../../utils/logger.js", () => ({
+    logger: { info: jest.fn(), error: jest.fn(), warning: jest.fn(), debug: jest.fn() },
+}));
+const { registerRegisterTestPlanTool } = await import("./registerTestPlanTool.js");
+const { computeCandidateId, DiscriminatorKind, CandidateSource } = await import("../../types/Recommendation.js");
+function captureToolHandler() {
+    let handler;
+    let inputSchema;
+    const fakeServer = {
+        registerTool: (_name, opts, fn) => {
+            handler = fn;
+            inputSchema = opts.inputSchema;
+        },
+    };
+    registerRegisterTestPlanTool(fakeServer);
+    // Mirrors the real MCP SDK's registerTool: validates args against inputSchema via Zod
+    // before invoking the handler, so tests exercise the real tool contract.
+    return async (params) => {
+        const parsed = z.object(inputSchema).safeParse(params);
+        if (!parsed.success) {
+            return { isError: true, content: [{ type: "text", text: parsed.error.message }] };
+        }
+        return handler(parsed.data);
+    };
+}
+async function writeStateFile(dir, overrides = {}) {
+    const stateFile = path.join(dir, "analyze-changes-state.json");
+    await fs.writeFile(stateFile, JSON.stringify({
+        existingTests: [],
+        analysisScope: "current_branch_diff",
+        newEndpoints: [],
+        repositoryAnalysis: {},
+        ...overrides,
+        metadata: {
+            sessionId: "test-session",
+            stateType: "analysis",
+            repositoryPath: dir,
+            createdAt: "2026-01-01T00:00:00.000Z",
+            updatedAt: "2026-01-01T00:00:00.000Z",
+        },
+    }), "utf-8");
+    return stateFile;
+}
+async function readStateFile(stateFile) {
+    return JSON.parse(await fs.readFile(stateFile, "utf-8"));
+}
+const AGGREGATE_ANCHOR = "order_count = len(existing_orders)";
+function multiRecordCandidate(overrides = {}) {
+    return {
+        scenarioName: "orders_multi_record_aggregate",
+        description: "Create two orders then assert the aggregate count.",
+        category: "business_rule",
+        priority: "high",
+        testType: "integration",
+        steps: [
+            {
+                order: 1,
+                method: "POST",
+                path: "/api/v1/orders",
+                description: "Create first order",
+                interactionType: "success",
+                expectedStatusCode: 201,
+            },
+            {
+                order: 2,
+                method: "GET",
+                path: "/api/v1/orders/summary",
+                description: "Assert order_count is 2",
+                interactionType: "success",
+                expectedStatusCode: 200,
+                expectedResponseFields: ["order_count == 2"],
+            },
+        ],
+        ...overrides,
+    };
+}
+describe("skyramp_register_test_plan — SKYR-3879 Path B", () => {
+    let handler;
+    let tmpDirs = [];
+    beforeAll(() => {
+        handler = captureToolHandler();
+    });
+    afterEach(async () => {
+        for (const dir of tmpDirs) {
+            await fs.rm(dir, { recursive: true, force: true });
+        }
+        tmpDirs = [];
+    });
+    async function mkTmpDir() {
+        const dir = await fs.mkdtemp(path.join(os.tmpdir(), "register-plan-test-"));
+        tmpDirs.push(dir);
+        return dir;
+    }
+    it("errors when stateFile does not exist", async () => {
+        const dir = await mkTmpDir();
+        const result = await handler({
+            stateFile: path.join(dir, "does-not-exist.json"),
+            candidates: [],
+        });
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain("State file is empty or invalid");
+    });
+    it("rejects a relative stateFile path (schema refine)", async () => {
+        const result = await handler({ stateFile: "relative/path.json", candidates: [] });
+        expect(result.isError).toBe(true);
+    });
+    it("rejects an empty candidate union instead of persisting an empty plan", async () => {
+        const dir = await mkTmpDir();
+        const stateFile = await writeStateFile(dir, { diffText: "" });
+        const result = await handler({ stateFile, candidates: [] });
+        expect(result.isError).toBe(true);
+        expect(result.content[0].text).toContain("No candidates submitted");
+        const persisted = JSON.parse(await fs.readFile(stateFile, "utf-8"));
+        expect(persisted.approvedPlan).toBeUndefined();
+    });
+    it("promotes a verified discriminator candidate into GENERATE ahead of an unverified one", async () => {
+        const dir = await mkTmpDir();
+        const stateFile = await writeStateFile(dir, {
+            diffText: `--- a/orders.py\n+++ b/orders.py\n+${AGGREGATE_ANCHOR}\n`,
+            planBudgetContext: {
+                maxGenerate: 2,
+                maxTotal: 3,
+                isUIOnlyPR: false,
+                hasFrontendChanges: false,
+                externalCoverageKeys: [],
+            },
+        });
+        const result = await handler({
+            stateFile,
+            candidates: [
+                multiRecordCandidate({
+                    discriminator: { kind: DiscriminatorKind.MULTI_RECORD_AGGREGATE, changedCodeAnchor: AGGREGATE_ANCHOR },
+                }),
+                {
+                    scenarioName: "products_crud",
+                    description: "Basic CRUD happy path.",
+                    category: "crud",
+                    priority: "low",
+                    testType: "contract",
+                    steps: [
+                        {
+                            order: 1,
+                            method: "GET",
+                            path: "/api/v1/products",
+                            description: "List products",
+                            interactionType: "success",
+                            expectedStatusCode: 200,
+                        },
+                    ],
+                },
+            ],
+        });
+        expect(result.isError).toBeFalsy();
+        expect(result.content[0].text).toContain("orders_multi_record_aggregate");
+        expect(result.content[0].text).toContain("verified discriminator: multi_record_aggregate");
+        const persisted = await readStateFile(stateFile);
+        expect(persisted.approvedPlan.generate[0].scenarioName).toBe("orders_multi_record_aggregate");
+        expect(persisted.approvedPlan.generate[0].verifiedDiscriminator).toBe(DiscriminatorKind.MULTI_RECORD_AGGREGATE);
+        expect(persisted.approvedPlan.demotions).toEqual([]);
+    });
+    it("demotes a gamed discriminator claim (no structural evidence) but keeps the candidate registered", async () => {
+        const dir = await mkTmpDir();
+        const stateFile = await writeStateFile(dir, {
+            diffText: `--- a/orders.py\n+++ b/orders.py\n+${AGGREGATE_ANCHOR}\n`,
+            planBudgetContext: {
+                maxGenerate: 2,
+                maxTotal: 3,
+                isUIOnlyPR: false,
+                hasFrontendChanges: false,
+                externalCoverageKeys: [],
+            },
+        });
+        const result = await handler({
+            stateFile,
+            candidates: [
+                multiRecordCandidate({
+                    // No aggregate assertion — steps.length === 2 but the second step doesn't
+                    // assert a count. A gamed claim: declares the discriminator anyway.
+                    steps: [
+                        {
+                            order: 1,
+                            method: "POST",
+                            path: "/api/v1/orders",
+                            description: "Create order",
+                            interactionType: "success",
+                            expectedStatusCode: 201,
+                        },
+                    ],
+                    discriminator: { kind: DiscriminatorKind.MULTI_RECORD_AGGREGATE, changedCodeAnchor: AGGREGATE_ANCHOR },
+                }),
+            ],
+        });
+        expect(result.isError).toBeFalsy();
+        expect(result.content[0].text).toContain("Demotions (1)");
+        expect(result.content[0].text).toContain("multi_record_aggregate unverified");
+        const persisted = await readStateFile(stateFile);
+        expect(persisted.approvedPlan.demotions).toHaveLength(1);
+        expect(persisted.approvedPlan.demotions[0].reason).toContain("multi_record_aggregate unverified");
+        // The candidate itself is NOT dropped — it must still appear somewhere in the plan.
+        const allScenarioNames = [...persisted.approvedPlan.generate, ...persisted.approvedPlan.additional].map((item) => item.scenarioName);
+        expect(allScenarioNames).toContain("orders_multi_record_aggregate");
+        // And it must NOT carry a verifiedDiscriminator.
+        const item = [...persisted.approvedPlan.generate, ...persisted.approvedPlan.additional].find((i) => i.scenarioName === "orders_multi_record_aggregate");
+        expect(item.verifiedDiscriminator).toBeUndefined();
+    });
+    it("merges agent candidates with pre-seeded server candidates from analyze_changes", async () => {
+        const dir = await mkTmpDir();
+        const serverScenario = {
+            scenarioName: "server_seeded_scenario",
+            description: "Pre-ranked by the server's own classification.",
+            category: "business_rule",
+            priority: "high",
+            steps: [
+                {
+                    order: 1,
+                    method: "GET",
+                    path: "/api/v1/reports",
+                    description: "Fetch report",
+                    interactionType: "success",
+                    expectedStatusCode: 200,
+                },
+            ],
+            chainingKeys: [],
+            requiresAuth: false,
+            estimatedComplexity: "simple",
+            testType: "contract",
+        };
+        const serverCandidateId = computeCandidateId(serverScenario);
+        const stateFile = await writeStateFile(dir, {
+            diffText: "",
+            repositoryAnalysis: { scenarios: [serverScenario] },
+            planBudgetContext: {
+                maxGenerate: 5,
+                maxTotal: 5,
+                isUIOnlyPR: false,
+                hasFrontendChanges: false,
+                externalCoverageKeys: [],
+            },
+            approvedPlan: {
+                planId: "prior-plan",
+                createdAt: "2026-01-01T00:00:00.000Z",
+                generate: [
+                    {
+                        candidateId: serverCandidateId,
+                        scenarioName: "server_seeded_scenario",
+                        testType: "contract",
+                        category: "business_rule",
+                        source: CandidateSource.SERVER,
+                        matchKeys: [`name:server-seeded-scenario`, `ep:contract:GET:/api/v1/reports`],
+                    },
+                ],
+                additional: [],
+                demotions: [],
+            },
+        });
+        const result = await handler({
+            stateFile,
+            candidates: [
+                {
+                    scenarioName: "agent_drafted_scenario",
+                    description: "Agent-drafted candidate this run.",
+                    category: "workflow",
+                    priority: "medium",
+                    testType: "integration",
+                    steps: [
+                        {
+                            order: 1,
+                            method: "POST",
+                            path: "/api/v1/carts",
+                            description: "Create cart",
+                            interactionType: "success",
+                            expectedStatusCode: 201,
+                        },
+                    ],
+                },
+            ],
+        });
+        expect(result.isError).toBeFalsy();
+        const persisted = await readStateFile(stateFile);
+        const names = persisted.approvedPlan.generate.map((item) => item.scenarioName);
+        expect(names).toContain("server_seeded_scenario");
+        expect(names).toContain("agent_drafted_scenario");
+        const serverItem = persisted.approvedPlan.generate.find((item) => item.scenarioName === "server_seeded_scenario");
+        expect(serverItem.source).toBe("server");
+        const agentItem = persisted.approvedPlan.generate.find((item) => item.scenarioName === "agent_drafted_scenario");
+        expect(agentItem.source).toBe("agent");
+        // New plan replaces the old planId (fresh registration, not an append).
+        expect(persisted.approvedPlan.planId).not.toBe("prior-plan");
+    });
+});