@skyramp/mcp 0.0.64-rc.8 → 0.0.64

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

@@ -8,7 +8,7 @@ import { parseWorkspaceAuthType } from "../../utils/workspaceAuth.js";
 import { AnalyticsService } from "../../services/AnalyticsService.js";
 import { StateManager, registerSession, storeSessionData, } from "../../utils/AnalysisStateManager.js";
 import { buildRecommendationPrompt } from "../../prompts/test-recommendation/test-recommendation-prompt.js";
-import { MAX_RECOMMENDATIONS } from "../../prompts/test-recommendation/recommendationSections.js";
+import { MAX_RECOMMENDATIONS, MAX_TESTS_TO_GENERATE } from "../../prompts/test-recommendation/recommendationSections.js";
 import { WorkspaceConfigManager } from "@skyramp/skyramp";
 import { TestDiscoveryService } from "../../services/TestDiscoveryService.js";
 import { computeBranchDiff } from "../../utils/branchDiff.js";
@@ -172,6 +172,12 @@ const analyzeChangesSchema = {
         .default(MAX_RECOMMENDATIONS)
         .optional()
         .describe(`Number of ranked test recommendations to generate. Defaults to ${MAX_RECOMMENDATIONS}.`),
+    maxGenerate: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe(`Number of tests to generate and execute. Defaults to ${MAX_TESTS_TO_GENERATE} (diff mode) or all recommendations (full repo).`),
     prNumber: z
         .number()
         .optional()
@@ -526,12 +532,16 @@ to produce a unified state file for the test health workflow.
             // ── Step 10: Build full RepositoryAnalysis for ranked recommendations ──
             const sessionId = crypto.randomUUID();
             // Build existing test locations map (type → file list) for deduplication in recommendations
+            // Include covered endpoints so the agent can cross-check resource paths before creating new files.
             const testLocationsByType = {};
             for (const t of existingTests) {
                 const type = t.testType || "unknown";
-                testLocationsByType[type] = testLocationsByType[type]
-                    ? `${testLocationsByType[type]}, ${t.testFile}`
+                const entry = t.apiEndpoint
+                    ? `${t.testFile} (covers: ${t.apiEndpoint})`
                     : t.testFile;
+                testLocationsByType[type] = testLocationsByType[type]
+                    ? `${testLocationsByType[type]}, ${entry}`
+                    : entry;
             }
             // Build the full RepositoryAnalysis object — same structure as analyzeRepositoryTool
             // so buildRecommendationPrompt can reason over enriched endpoint + scenario data
@@ -700,7 +710,7 @@ to produce a unified state file for the test health workflow.
                     }
                 }
             }
-            const recommendationPrompt = buildRecommendationPrompt(fullAnalysis, analysisScope, topN, prContext, wsAuthHeader, wsAuthType);
+            const recommendationPrompt = buildRecommendationPrompt(fullAnalysis, analysisScope, topN, prContext, wsAuthHeader, wsAuthType, params.maxGenerate);
             const routerMountContext = grepRouterMountingContext(params.repositoryPath);
             await sendProgress(100, 100, "Analysis complete.");
             const stateSize = await stateManager.getSizeFormatted();

package/build/types/RepositoryAnalysis.js

@@ -71,6 +71,7 @@ export const scenarioStepSchema = z.object({
     chainsFrom: z
         .union([chainingRefSchema, z.array(chainingRefSchema)])
         .optional(),
+    bodyMustInclude: z.array(z.string()).optional(),
 });
 export const draftedScenarioSchema = z.object({
     scenarioName: z.string(),

package/build/utils/scenarioDrafting.js

@@ -573,6 +573,66 @@ function diffDirectValidation(method, path, resource) {
         testType: "contract",
     };
 }
+/**
+ * Draft a "mutation with collection modification" scenario for PUT/PATCH endpoints.
+ * This tests adding/removing child items (e.g., order line items) and verifying that
+ * derived totals (total_amount, item_count, subtotal) are recalculated.
+ * This pattern catches the most common class of user-reported bugs.
+ */
+function diffDirectMutationRecalc(method, resource, singular, group) {
+    const steps = [];
+    if (group.methods.has("POST")) {
+        steps.push({
+            order: 1,
+            method: "POST",
+            path: group.basePath,
+            description: `Create a ${singular} with initial items`,
+            interactionType: "success",
+            expectedStatusCode: 201,
+        });
+    }
+    const targetPath = group.paramPath ?? group.basePath;
+    const pathParamName = group.paramPath?.match(/\{([^}]+)\}/)?.[1] ?? `${singular}_id`;
+    const sourceStep = steps.length;
+    steps.push({
+        order: steps.length + 1,
+        method,
+        path: targetPath,
+        description: `${method} the ${singular} — add/replace items in the child collection (e.g. items array with product references chained from prior steps) and verify total_amount is recalculated`,
+        interactionType: "success",
+        expectedStatusCode: 200,
+        bodyMustInclude: ["child collection array (e.g. items)", "FK reference to parent resource (e.g. product_id)", "quantity or amount"],
+        ...(sourceStep > 0 && group.paramPath
+            ? { chainsFrom: { sourceStep, sourceField: "id", sourceLocation: "body", targetParam: pathParamName, targetLocation: "path" } }
+            : {}),
+    });
+    if (group.paramPath && group.methods.has("GET")) {
+        steps.push({
+            order: steps.length + 1,
+            method: "GET",
+            path: group.paramPath,
+            description: `Verify the ${singular} reflects the updated child collection with correct FK references, quantities, and recalculated totals`,
+            interactionType: "success",
+            expectedStatusCode: 200,
+            expectedResponseFields: ["child collection array", "each child's FK reference", "each child's quantity", "recalculated total"],
+            ...(sourceStep > 0 && group.paramPath
+                ? { chainsFrom: { sourceStep, sourceField: "id", sourceLocation: "body", targetParam: pathParamName, targetLocation: "path" } }
+                : {}),
+        });
+    }
+    return {
+        scenarioName: `${resource}-${method.toLowerCase()}-add-items-recalculate`,
+        description: `Mutation recalculation: ${method} ${targetPath} — modify child collection and verify derived totals are recomputed`,
+        category: "new_endpoint",
+        priority: "high",
+        steps,
+        chainingKeys: ["id", pathParamName],
+        requiresAuth: true,
+        estimatedComplexity: "complex",
+        source: "code-inferred",
+        testType: "integration",
+    };
+}
 /**
  * Draft scenarios that directly test each new endpoint in the branch diff.
  *
@@ -597,15 +657,64 @@ export function draftDiffDirectScenarios(newEndpoints, resourceGroups) {
         methods.add(ep.method.toUpperCase());
         grouped.set(ep.path, methods);
     }
+    // Segment-boundary suffix match: avoids "/orders" matching "/preorders".
+    const pathSuffixMatches = (fullPath, suffix) => {
+        if (fullPath === suffix)
+            return true;
+        const fullSegs = fullPath.split("/").filter(Boolean);
+        const suffixSegs = suffix.split("/").filter(Boolean);
+        if (suffixSegs.length === 0 || suffixSegs.length > fullSegs.length)
+            return false;
+        const offset = fullSegs.length - suffixSegs.length;
+        for (let i = 0; i < suffixSegs.length; i++) {
+            if (fullSegs[offset + i] !== suffixSegs[i])
+                return false;
+        }
+        return true;
+    };
     for (const [epPath, methods] of grouped) {
-        const resource = extractResourceName(epPath);
-        if (!resource)
-            continue;
+        let resource = extractResourceName(epPath);
+        let resolvedPath = epPath;
+        // When resource was found but epPath may be router-relative (e.g. "/orders"
+        // instead of "/api/v1/orders"), try to upgrade resolvedPath to the full path.
+        if (resource) {
+            const existingGroup = resourceGroups.get(resource);
+            if (existingGroup) {
+                if (existingGroup.paramPath && existingGroup.paramPath !== epPath && pathSuffixMatches(existingGroup.paramPath, epPath)) {
+                    resolvedPath = existingGroup.paramPath;
+                }
+                else if (existingGroup.basePath !== epPath && pathSuffixMatches(existingGroup.basePath, epPath)) {
+                    resolvedPath = existingGroup.basePath;
+                }
+            }
+        }
+        // When extractResourceName returns null (e.g. "/{order_id}"), fall back to
+        // matching the path suffix against known resourceGroup paths using segment
+        // boundaries. Prefer the longest (most specific) match.
+        if (!resource) {
+            let bestMatch = null;
+            for (const [rName, rGroup] of resourceGroups) {
+                if (rGroup.paramPath && pathSuffixMatches(rGroup.paramPath, epPath)) {
+                    if (!bestMatch || rGroup.paramPath.length > bestMatch.length) {
+                        bestMatch = { name: rName, path: rGroup.paramPath, length: rGroup.paramPath.length };
+                    }
+                }
+                if (pathSuffixMatches(rGroup.basePath, epPath)) {
+                    if (!bestMatch || rGroup.basePath.length > bestMatch.length) {
+                        bestMatch = { name: rName, path: rGroup.basePath, length: rGroup.basePath.length };
+                    }
+                }
+            }
+            if (!bestMatch)
+                continue;
+            resource = bestMatch.name;
+            resolvedPath = bestMatch.path;
+        }
         const group = resourceGroups.get(resource);
         if (!group)
             continue;
         const singular = singularize(resource);
-        const hasPathParam = epPath.includes("{");
+        const hasPathParam = resolvedPath.includes("{");
         const add = (s) => {
             if (!seen.has(s.scenarioName)) {
                 seen.add(s.scenarioName);
@@ -614,23 +723,24 @@ export function draftDiffDirectScenarios(newEndpoints, resourceGroups) {
         };
         for (const method of methods) {
             if (method === "PUT" || method === "PATCH") {
+                add(diffDirectMutationRecalc(method, resource, singular, group));
                 add(diffDirectIntegration(method, resource, singular, group));
-                add(diffDirectContract(method, epPath, resource));
+                add(diffDirectContract(method, resolvedPath, resource));
                 if (hasPathParam)
-                    add(diffDirectNotFound(method, epPath, resource, singular));
+                    add(diffDirectNotFound(method, resolvedPath, resource, singular));
             }
             else if (method === "POST") {
                 add(diffDirectIntegration(method, resource, singular, group));
-                add(diffDirectContract(method, epPath, resource));
-                add(diffDirectValidation(method, epPath, resource));
+                add(diffDirectContract(method, resolvedPath, resource));
+                add(diffDirectValidation(method, resolvedPath, resource));
             }
             else if (method === "DELETE") {
                 add(diffDirectIntegration(method, resource, singular, group));
-                add(diffDirectContract(method, epPath, resource));
+                add(diffDirectContract(method, resolvedPath, resource));
             }
             else if (method === "GET" && hasPathParam) {
-                add(diffDirectContract(method, epPath, resource));
-                add(diffDirectNotFound(method, epPath, resource, singular));
+                add(diffDirectContract(method, resolvedPath, resource));
+                add(diffDirectNotFound(method, resolvedPath, resource, singular));
             }
         }
     }

package/build/utils/scenarioDrafting.test.js

@@ -317,12 +317,17 @@ describe("draftDiffDirectScenarios", () => {
             orders: { basePath: "/api/orders", methods: ["GET", "POST", "PUT"], paramPath: "/api/orders/{order_id}" },
         });
         const scenarios = draftDiffDirectScenarios([{ method: "PUT", path: "/api/orders/{order_id}" }], groups);
-        expect(scenarios.length).toBeGreaterThanOrEqual(2);
+        expect(scenarios.length).toBeGreaterThanOrEqual(3);
         for (const s of scenarios) {
             expect(s.category).toBe("new_endpoint");
         }
+        // Mutation-recalculation scenario is drafted first for PUT/PATCH
+        const mutationRecalc = scenarios.find(s => s.testType === "integration" && s.scenarioName.includes("add-items-recalculate"));
+        expect(mutationRecalc).toBeDefined();
+        expect(mutationRecalc.steps.some(st => st.method === "PUT")).toBe(true);
+        expect(mutationRecalc.description).toContain("recalculation");
         // Integration happy path includes the PUT step
-        const integration = scenarios.find(s => s.testType === "integration");
+        const integration = scenarios.find(s => s.testType === "integration" && s.scenarioName.includes("happy-path"));
         expect(integration).toBeDefined();
         expect(integration.steps.some(st => st.method === "PUT")).toBe(true);
         // Description prompts LLM to discover prerequisites from source code
@@ -334,12 +339,40 @@ describe("draftDiffDirectScenarios", () => {
         const notFound = scenarios.find(s => s.steps.some(st => st.expectedStatusCode === 404));
         expect(notFound).toBeDefined();
     });
+    it("generates mutation-recalc scenario for a new PATCH endpoint", () => {
+        const groups = makeGroups({
+            orders: { basePath: "/api/orders", methods: ["GET", "POST", "PATCH"], paramPath: "/api/orders/{order_id}" },
+        });
+        const scenarios = draftDiffDirectScenarios([{ method: "PATCH", path: "/api/orders/{order_id}" }], groups);
+        // Mutation-recalculation scenario is drafted for PATCH
+        const mutationRecalc = scenarios.find(s => s.scenarioName === "orders-patch-add-items-recalculate");
+        expect(mutationRecalc).toBeDefined();
+        expect(mutationRecalc.testType).toBe("integration");
+        expect(mutationRecalc.category).toBe("new_endpoint");
+        expect(mutationRecalc.priority).toBe("high");
+        expect(mutationRecalc.description).toContain("recalculation");
+        expect(mutationRecalc.description).toContain("derived totals");
+        // Should have 3 steps: POST (create) → PATCH (add items) → GET (verify)
+        expect(mutationRecalc.steps).toHaveLength(3);
+        expect(mutationRecalc.steps[0].method).toBe("POST");
+        expect(mutationRecalc.steps[1].method).toBe("PATCH");
+        expect(mutationRecalc.steps[2].method).toBe("GET");
+        // Happy-path integration scenario is also still present
+        const happyPath = scenarios.find(s => s.scenarioName.includes("happy-path") && s.testType === "integration");
+        expect(happyPath).toBeDefined();
+    });
     it("integration scenario minimum steps: POST resource then PUT — LLM discovers prereqs from source code", () => {
         const groups = makeGroups({
             orders: { basePath: "/api/orders", methods: ["GET", "POST", "PUT"], paramPath: "/api/orders/{order_id}" },
         });
         const scenarios = draftDiffDirectScenarios([{ method: "PUT", path: "/api/orders/{order_id}" }], groups);
-        const integration = scenarios.find(s => s.testType === "integration");
+        // Mutation-recalculation scenario comes first
+        const mutationRecalc = scenarios.find(s => s.testType === "integration" && s.scenarioName.includes("add-items-recalculate"));
+        expect(mutationRecalc).toBeDefined();
+        expect(mutationRecalc.steps.some(st => st.method === "POST" && st.path === "/api/orders")).toBe(true);
+        expect(mutationRecalc.steps.some(st => st.method === "PUT")).toBe(true);
+        // Happy-path integration scenario
+        const integration = scenarios.find(s => s.testType === "integration" && s.scenarioName.includes("happy-path"));
         expect(integration).toBeDefined();
         // Minimum steps: create the resource + call the new endpoint
         expect(integration.steps.some(st => st.method === "POST" && st.path === "/api/orders")).toBe(true);
@@ -378,4 +411,234 @@ describe("draftDiffDirectScenarios", () => {
         expect(diffDirect.length).toBeGreaterThan(0);
         expect(diffDirect.some(s => s.steps.some(st => st.method === "PUT"))).toBe(true);
     });
+    it("resolves router-relative param paths (e.g. /{order_id}) against known resourceGroups", () => {
+        const groups = makeGroups({
+            orders: { basePath: "/api/v1/orders", methods: ["GET", "POST", "PATCH", "DELETE"], paramPath: "/api/v1/orders/{order_id}" },
+            products: { basePath: "/api/v1/products", methods: ["GET", "POST"], paramPath: "/api/v1/products/{id}" },
+        });
+        // Diff scanner reports router-relative path, not the full API path
+        const scenarios = draftDiffDirectScenarios([{ method: "PATCH", path: "/{order_id}" }], groups);
+        expect(scenarios.length).toBeGreaterThanOrEqual(3);
+        // Mutation-recalculation scenario is drafted
+        const mutationRecalc = scenarios.find(s => s.scenarioName === "orders-patch-add-items-recalculate");
+        expect(mutationRecalc).toBeDefined();
+        expect(mutationRecalc.testType).toBe("integration");
+        expect(mutationRecalc.category).toBe("new_endpoint");
+        expect(mutationRecalc.steps[1].method).toBe("PATCH");
+        // Contract and not-found scenarios use the resolved full path
+        const contract = scenarios.find(s => s.scenarioName.includes("contract"));
+        expect(contract).toBeDefined();
+        expect(contract.steps[0].path).toBe("/api/v1/orders/{order_id}");
+        const notFound = scenarios.find(s => s.scenarioName.includes("not-found"));
+        expect(notFound).toBeDefined();
+        expect(notFound.steps[0].path).toBe("/api/v1/orders/{order_id}");
+    });
+    it("resolves router-relative base paths (e.g. /orders) against known resourceGroups", () => {
+        const groups = makeGroups({
+            orders: { basePath: "/api/v1/orders", methods: ["GET", "POST"], paramPath: "/api/v1/orders/{order_id}" },
+        });
+        const scenarios = draftDiffDirectScenarios([{ method: "POST", path: "/orders" }], groups);
+        expect(scenarios.length).toBeGreaterThanOrEqual(2);
+        const integration = scenarios.find(s => s.testType === "integration");
+        expect(integration).toBeDefined();
+        expect(integration.category).toBe("new_endpoint");
+    });
+    it("skips unresolvable router-relative paths", () => {
+        const groups = makeGroups({
+            products: { basePath: "/api/v1/products", methods: ["GET", "POST"], paramPath: "/api/v1/products/{id}" },
+        });
+        // /{nonexistent_id} doesn't match any known resource
+        const scenarios = draftDiffDirectScenarios([{ method: "PATCH", path: "/{nonexistent_id}" }], groups);
+        expect(scenarios).toEqual([]);
+    });
+    it("PR #195 regression: PATCH /{order_id} produces mutation-recalculate scenario in GENERATE slots", () => {
+        // Simulates the exact data from PR #195:
+        // - Full endpoint list with orders, products, reviews
+        // - newEndpoints has PATCH /{order_id} (router-relative)
+        const endpoints = [
+            { path: "/api/v1/orders", methods: ["GET", "POST"] },
+            { path: "/api/v1/orders/{order_id}", methods: ["GET", "PATCH", "DELETE"] },
+            { path: "/api/v1/products", methods: ["GET", "POST"] },
+            { path: "/api/v1/products/{product_id}", methods: ["GET", "PUT", "DELETE"] },
+            { path: "/api/v1/reviews", methods: ["GET", "POST"] },
+            { path: "/api/v1/reset", methods: ["POST"] },
+        ];
+        const newEndpoints = [{ method: "PATCH", path: "/{order_id}" }];
+        const allScenarios = draftScenariosFromEndpoints(endpoints, newEndpoints);
+        // The diff-direct scenarios should include orders-patch-add-items-recalculate
+        const mutationRecalc = allScenarios.find(s => s.scenarioName === "orders-patch-add-items-recalculate");
+        expect(mutationRecalc).toBeDefined();
+        expect(mutationRecalc.category).toBe("new_endpoint"); // → CRITICAL priority tier
+        expect(mutationRecalc.steps).toHaveLength(3);
+        expect(mutationRecalc.steps[0].method).toBe("POST");
+        expect(mutationRecalc.steps[1].method).toBe("PATCH");
+        expect(mutationRecalc.steps[2].method).toBe("GET");
+        expect(mutationRecalc.description).toContain("derived totals");
+        // Verify it outranks all non-new_endpoint scenarios (cascade-delete, unique-constraint, etc.)
+        const newEndpointScenarios = allScenarios.filter(s => s.category === "new_endpoint");
+        const otherScenarios = allScenarios.filter(s => s.category !== "new_endpoint");
+        expect(newEndpointScenarios.length).toBeGreaterThanOrEqual(3);
+        // All new_endpoint scenarios should include our mutation-recalculate
+        expect(newEndpointScenarios.some(s => s.scenarioName === "orders-patch-add-items-recalculate")).toBe(true);
+        // Non-new_endpoint scenarios should NOT include mutation-recalculate
+        expect(otherScenarios.every(s => s.scenarioName !== "orders-patch-add-items-recalculate")).toBe(true);
+    });
+});
+describe("diffDirectMutationRecalc — diverse app types (no hardcoded field names)", () => {
+    const makeGroups = (defs) => new Map(Object.entries(defs).map(([k, v]) => [k, { ...v, methods: new Set(v.methods) }]));
+    const testCases = [
+        {
+            name: "E-commerce: PATCH /orders/{order_id}",
+            resource: "orders",
+            group: { basePath: "/api/v1/orders", methods: ["GET", "POST", "PATCH"], paramPath: "/api/v1/orders/{order_id}" },
+            method: "PATCH",
+            expectedParamName: "order_id",
+        },
+        {
+            name: "Project management: PUT /projects/{id}",
+            resource: "projects",
+            group: { basePath: "/api/projects", methods: ["GET", "POST", "PUT"], paramPath: "/api/projects/{id}" },
+            method: "PUT",
+            expectedParamName: "id",
+        },
+        {
+            name: "Invoicing: PATCH /invoices/{invoice_id}",
+            resource: "invoices",
+            group: { basePath: "/v2/invoices", methods: ["GET", "POST", "PATCH"], paramPath: "/v2/invoices/{invoice_id}" },
+            method: "PATCH",
+            expectedParamName: "invoice_id",
+        },
+        {
+            name: "Education LMS: PUT /courses/{course_id}",
+            resource: "courses",
+            group: { basePath: "/api/courses", methods: ["GET", "POST", "PUT"], paramPath: "/api/courses/{course_id}" },
+            method: "PUT",
+            expectedParamName: "course_id",
+        },
+        {
+            name: "Healthcare: PATCH /prescriptions/{prescription_id}",
+            resource: "prescriptions",
+            group: { basePath: "/api/prescriptions", methods: ["GET", "POST", "PATCH"], paramPath: "/api/prescriptions/{prescription_id}" },
+            method: "PATCH",
+            expectedParamName: "prescription_id",
+        },
+        {
+            name: "Logistics: PUT /shipments/{shipment_id}",
+            resource: "shipments",
+            group: { basePath: "/api/shipments", methods: ["GET", "POST", "PUT"], paramPath: "/api/shipments/{shipment_id}" },
+            method: "PUT",
+            expectedParamName: "shipment_id",
+        },
+        {
+            name: "Restaurant: PATCH /menus/{menuId}",
+            resource: "menus",
+            group: { basePath: "/api/menus", methods: ["GET", "POST", "PATCH"], paramPath: "/api/menus/{menuId}" },
+            method: "PATCH",
+            expectedParamName: "menuId",
+        },
+        {
+            name: "Cloud billing: PUT /subscriptions/{subscription_id}",
+            resource: "subscriptions",
+            group: { basePath: "/billing/subscriptions", methods: ["GET", "POST", "PUT"], paramPath: "/billing/subscriptions/{subscription_id}" },
+            method: "PUT",
+            expectedParamName: "subscription_id",
+        },
+        {
+            name: "Warehouse: PATCH /inventories/{uuid}",
+            resource: "inventories",
+            group: { basePath: "/api/inventories", methods: ["GET", "POST", "PATCH"], paramPath: "/api/inventories/{uuid}" },
+            method: "PATCH",
+            expectedParamName: "uuid",
+        },
+        {
+            name: "Minimal: PATCH /items (no paramPath)",
+            resource: "items",
+            group: { basePath: "/items", methods: ["GET", "POST", "PATCH"] },
+            method: "PATCH",
+            expectedParamName: "item_id",
+        },
+    ];
+    it.each(testCases)("$name — produces valid mutation-recalc scenario", ({ resource, group, method, expectedParamName }) => {
+        const groups = makeGroups({ [resource]: group });
+        const scenarios = draftDiffDirectScenarios([{ method, path: group.paramPath ?? group.basePath }], groups);
+        const mutationRecalc = scenarios.find(s => s.scenarioName.endsWith("-add-items-recalculate"));
+        expect(mutationRecalc).toBeDefined();
+        expect(mutationRecalc.category).toBe("new_endpoint");
+        expect(mutationRecalc.testType).toBe("integration");
+        expect(mutationRecalc.priority).toBe("high");
+        // Step 1: POST to create resource (all test cases have POST)
+        expect(mutationRecalc.steps[0].method).toBe("POST");
+        expect(mutationRecalc.steps[0].path).toBe(group.basePath);
+        // Step 2: PUT/PATCH with mutation
+        const mutationStep = mutationRecalc.steps[1];
+        expect(mutationStep.method).toBe(method);
+        expect(mutationStep.bodyMustInclude).toBeDefined();
+        expect(mutationStep.bodyMustInclude.length).toBe(3);
+        // Verify NO hardcoded domain-specific field names
+        for (const hint of mutationStep.bodyMustInclude) {
+            expect(hint).not.toBe("items");
+            expect(hint).not.toBe("product_id");
+            expect(hint).not.toBe("quantity");
+            expect(hint).not.toBe("total_amount");
+        }
+        // Verify hints are descriptive (contain "e.g." or similar guidance)
+        expect(mutationStep.bodyMustInclude.some(h => h.includes("e.g."))).toBe(true);
+        // Chaining uses the actual path param name (only when paramPath exists)
+        if (group.paramPath) {
+            expect(mutationStep.chainsFrom).toBeDefined();
+            const chaining = mutationStep.chainsFrom;
+            expect(chaining.targetParam).toBe(expectedParamName);
+            expect(chaining.sourceStep).toBe(1);
+            expect(chaining.sourceField).toBe("id");
+        }
+        else {
+            expect(mutationStep.chainsFrom).toBeUndefined();
+        }
+        // Step 3: GET verification (if paramPath exists)
+        if (group.paramPath) {
+            expect(mutationRecalc.steps).toHaveLength(3);
+            const getStep = mutationRecalc.steps[2];
+            expect(getStep.method).toBe("GET");
+            expect(getStep.expectedResponseFields).toBeDefined();
+            // Verify NO hardcoded domain-specific field names in response fields
+            for (const field of getStep.expectedResponseFields) {
+                expect(field).not.toBe("items");
+                expect(field).not.toMatch(/^items\.\*/);
+                expect(field).not.toBe("total_amount");
+            }
+        }
+        // chainingKeys uses the actual path param name, not hardcoded singular_id
+        expect(mutationRecalc.chainingKeys).toContain("id");
+        expect(mutationRecalc.chainingKeys).toContain(expectedParamName);
+        // Description is domain-agnostic
+        expect(mutationRecalc.description).toContain("derived totals");
+        expect(mutationRecalc.description).toContain("Mutation recalculation");
+    });
+    it("no paramPath: PATCH step targets basePath, no GET verification, fallback param name", () => {
+        const groups = makeGroups({
+            items: { basePath: "/items", methods: ["GET", "POST", "PATCH"] },
+        });
+        const scenarios = draftDiffDirectScenarios([{ method: "PATCH", path: "/items" }], groups);
+        const mutationRecalc = scenarios.find(s => s.scenarioName.endsWith("-add-items-recalculate"));
+        expect(mutationRecalc).toBeDefined();
+        // No paramPath → PATCH targets basePath, no GET step
+        expect(mutationRecalc.steps).toHaveLength(2);
+        expect(mutationRecalc.steps[1].path).toBe("/items");
+        // Fallback param name: singular + _id
+        expect(mutationRecalc.chainingKeys).toContain("item_id");
+    });
+    it("resource without POST: no create step, no chaining", () => {
+        const groups = makeGroups({
+            configs: { basePath: "/api/configs", methods: ["GET", "PATCH"], paramPath: "/api/configs/{config_id}" },
+        });
+        const scenarios = draftDiffDirectScenarios([{ method: "PATCH", path: "/api/configs/{config_id}" }], groups);
+        const mutationRecalc = scenarios.find(s => s.scenarioName.endsWith("-add-items-recalculate"));
+        expect(mutationRecalc).toBeDefined();
+        // No POST → starts with PATCH directly, no chaining
+        expect(mutationRecalc.steps[0].method).toBe("PATCH");
+        expect(mutationRecalc.steps[0].chainsFrom).toBeUndefined();
+        // Still has GET verification
+        expect(mutationRecalc.steps[1].method).toBe("GET");
+        expect(mutationRecalc.steps[1].chainsFrom).toBeUndefined();
+    });
 });