@skyramp/mcp 0.3.5 → 0.3.6-rc.2.ac20

package/build/prompts/code-reuse.js

@@ -1,6 +1,8 @@
 import { generateSkyrampHeader, SKYRAMP_UTILS_HEADER } from "../utils/utils.js";
-import { isPomReuseEnabled } from "../utils/featureFlags.js";
+import { isUtilsReuseEnabled } from "../utils/featureFlags.js";
+import { isModularizeFirstTarget, isPomAwareTarget, } from "../utils/reuseRouting.js";
 import { getPomAwareCodeReusePrompt } from "./pom-aware-code-reuse.js";
+import { NO_SHADOWING_RULE, selectHelperPolicy, } from "./shared-helper-policy.js";
 const LANGUAGE_MAP = {
     python: {
         extension: "py",
@@ -19,23 +21,159 @@ const LANGUAGE_MAP = {
         fileName: "skyrampUtils.ts",
     },
 };
-export function isPomAwareTarget(language, framework) {
-    if (!isPomReuseEnabled())
-        return false;
-    const lang = language.toLowerCase();
-    return (lang === "typescript" || lang === "javascript") && framework?.toLowerCase() === "playwright";
+function genericNearDupExample(testFile) {
+    return `### Worked example
+
+\`flow-1.spec.ts\` has:
+\`\`\`ts
+export async function upload_translation_file(page, fileName) {
+    await page.waitForTimeout(1500);
+    const responsePromise1 = page.waitForResponse("**/api/files/upload**");
+    const fileUploadPromise0 = page.waitForEvent("filechooser");
+    await page.getByText("Choose a file").first().click();
+    const fileChooser0 = await fileUploadPromise0;
+    await fileChooser0.setFiles(fileName);
+    const response1 = await responsePromise1;
+    await page.waitForTimeout(1500);
 }
-export function getCodeReusePrompt(testFile, language, framework, scopedPoms) {
+\`\`\`
+
+\`${testFile}\` (current) has:
+\`\`\`ts
+export async function uploadFileToRFI(page, fileName, tabName) {
+    await page.waitForTimeout(1500);
+    const responsePromise1 = page.waitForResponse("**/api/files/upload**");
+    const fileUploadPromise0 = page.waitForEvent("filechooser");
+    await page.getByText("Choose a file").click();
+    const fileChooser0 = await fileUploadPromise0;
+    await fileChooser0.setFiles(fileName);
+    const response1 = await responsePromise1;
+    await page.waitForTimeout(1500);
+}
+\`\`\`
+
+These ARE near-duplicates. Same primitive sequence; the only material difference is the \`.first()\` qualifier on the locator. \`tabName\` is unused in the body — recorder noise, drop it. Correct merge:
+
+\`\`\`ts
+export async function uploadFileViaChooser(page, fileName) {
+    await page.waitForTimeout(1500);
+    const responsePromise = page.waitForResponse("**/api/files/upload**");
+    const fileUploadPromise = page.waitForEvent("filechooser");
+    await page.getByText("Choose a file").first().click();
+    const fileChooser = await fileUploadPromise;
+    await fileChooser.setFiles(fileName);
+    await responsePromise;
+    await page.waitForTimeout(1500);
+}
+\`\`\`
+
+Both test files import and call \`uploadFileViaChooser(page, fileName)\`.`;
+}
+export function getCodeReusePrompt(testFile, language, framework, scopedPoms, testType) {
     const lang = language.toLowerCase();
-    if (isPomAwareTarget(lang, framework)) {
+    if (isPomAwareTarget(lang, framework, testType)) {
         return getPomAwareCodeReusePrompt(testFile, lang, scopedPoms);
     }
-    const ext = LANGUAGE_MAP[language].extension || "py";
-    const fileName = LANGUAGE_MAP[language].fileName || "SkyrampUtils.py";
+    const languageEntry = LANGUAGE_MAP[lang] ?? LANGUAGE_MAP.python;
+    const ext = languageEntry.extension;
+    const fileName = languageEntry.fileName;
     const codegenMarker = `${ext === "py" ? "#" : "//"} Generated by Skyramp v`;
+    // Modularize-first flows (see isModularizeFirstTarget) reach reuse already
+    // modularized, so the trailing hand-off must not send the agent back into
+    // modularization a second time — it would re-extract the helpers this pass
+    // just consolidated.
+    const modularizeFirst = isModularizeFirstTarget(testType, lang);
+    const modularizationTail = modularizeFirst
+        ? `**MANDATORY**: ${testType} tests are modularized BEFORE code reuse (see the PRECONDITION at the top). This reuse pass is the FINAL step for this file — do NOT call skyramp_modularization after it; a second modularization pass would re-extract the helpers this pass just consolidated.`
+        : `**MANDATORY**: After code reuse is complete, proceed to modularization by calling skyramp_modularization tool ONLY for UI, E2E, or INTEGRATION test types generated from traces.`;
+    // Modularize-first tests reach reuse freshly modularized: their helpers exist
+    // only in the current file, and STEP 5's other-files-only rule would strand
+    // them there forever — the FIRST test in a repo could never create the utils
+    // file. STEP 5b seeds the utils file from the current test's own helpers so
+    // this run's output carries it and later tests import instead of re-defining.
+    const seedsUtils = modularizeFirst;
+    // Naming, equivalence and assertion rules for helpers headed to the shared
+    // file are the helper policy's — selected once by test type, stated once.
+    const policy = selectHelperPolicy(testType);
+    // The generic worked example treats a locator qualifier (.first()) as a
+    // liftable difference; a shared-file browser helper must not, so seeded
+    // browser flows show an identical-selector merge instead.
+    const workedExample = seedsUtils
+        ? policy.nearDupExample(testFile)
+        : genericNearDupExample(testFile);
+    const skipTarget = seedsUtils ? "STEP 5b" : "STEP 6";
+    const noSiblingsRule = seedsUtils
+        ? `**IF NO OTHER SKYRAMP-GENERATED TEST FILES ARE FOUND, SKIP DIRECTLY TO STEP 5b — do not process STEP 4b or STEP 5.**`
+        : `**STOP HERE IF NO OTHER SKYRAMP-GENERATED TEST FILES FOUND**
+**IF NO OTHER SKYRAMP-GENERATED TEST FILES ARE FOUND, SKIP TO STEP 6 - DO NOT CREATE ANY UTILS FILES.**`;
+    const seedStepBlock = seedsUtils
+        ? `## STEP 5b: MOVE THIS TEST'S OWN HELPERS INTO \`${fileName}\`
+
+skyramp_modularization already ran on ${testFile} and extracted its steps into named helper functions. Those helpers belong in the shared \`${fileName}\` so later tests import them instead of re-defining them.
+
+For each helper function still defined locally in ${testFile} (i.e. not already merged by STEP 4b):
+1. **CREATE** \`${fileName}\` if it does not exist, with the standard header:
+   \`\`\`${ext}
+   ${generateSkyrampHeader(lang)}
+   \`\`\`
+2. **CHECK ITS ASSERTIONS FIRST**: ${policy.assertionRule} Relocate a trailing excluded assertion to ${policy.relocationTarget} before the move.${policy.moveRule ? ` ${policy.moveRule}` : ""}
+3. **MOVE** the helper into \`${fileName}\` — no renames, no signature changes, no changes beyond the trailing-assertion relocation above.
+4. **IMPORT** it from \`${fileName}\` into ${testFile}; keep every call site unchanged.
+5. If \`${fileName}\` already contains a helper for ${policy.sameStep} (or the same name): identical bodies → delete the local copy and import the utils version; differs only by ${policy.liftableLiterals} → apply the defaulted-parameter merge rule from STEP 4b (extend the utils helper with parameters defaulted to its current literals, import it, pass this test's values); differs structurally → leave the local helper in place and do not overwrite the utils version. ${policy.structuralNoise ? `${policy.structuralNoise}. ` : ""}${NO_SHADOWING_RULE}
+
+This step MOVES helpers that skyramp_modularization already created — it does not author new ones. If ${testFile} defines no helper functions, skip this step and do not create an empty \`${fileName}\`.
+`
+        : "";
+    const nearDupRules = seedsUtils ? policy.nearDupRules(fileName) : "";
+    const utilsMergeRule = seedsUtils
+        ? `
+**IF \`${fileName}\` ALREADY CONTAINS A HELPER FOR ${policy.sameStep}** that differs from what ${testFile} needs only by ${policy.liftableLiterals}: do NOT define a second helper — EXTEND the utils helper by lifting the differing literals to parameters whose defaults are the utils version's current literals (existing call sites stay valid unchanged), then import and call it with this test's values. ${policy.oneHelperRule(fileName)}${policy.structuralNoise ? ` ${policy.structuralNoise}.` : ""} ${NO_SHADOWING_RULE}
+`
+        : "";
+    // SKYR-4219: an inline request block is a CALL SITE for an existing helper, not a
+    // helper to move. Without this, a direct-mode sibling (plain literals, no
+    // \`data_override\`/\`uniqueSuffix\`) never meets the scenario-mode helper for the
+    // same request, and a step still inline in the current test never meets the utils
+    // helper — reuse degrades to a no-op in any mixed directory. Explicit test-type
+    // gate, not \`seedsUtils\`: the rule is stated in API terms.
+    const inlineRequestRule = testType === "integration"
+        ? `**INLINE REQUEST BLOCKS ARE CALL SITES, NOT HELPERS.** A request step written inline — one \`client.send_request(...)\` / \`client.sendRequest(...)\` call plus its status-code assertion, not wrapped in a function — is never something to move or author a helper from. But when a helper for the SAME method+path already exists, the block is that helper's near-duplicate (judge it by the API near-duplicate criteria in STEP 4b: same method+path and call structure; differences limited to body literals, \`data_override\` values, or expected status): REPLACE the block with a call to the helper, passing the block's own literals as arguments, and lift any literal the helper does not yet take to a parameter DEFAULTED to the helper's current value (existing call sites unchanged). KEEP the block's response variable — \`<same variable> = <helper>(...)\` — so the assertions that read it afterwards are unchanged. A value the block wraps in \`uniqueSuffix(...)\` or routes through \`data_override\` where the helper uses a plain literal (or vice versa) is a LITERAL difference, not a structural one — pass the expression as the argument. A block whose request differs structurally (extra step, different method or path) stays as it is.`
+        : "";
+    // Its own step, placed after 5b: the agent routinely satisfies ${testFile} in STEP 3
+    // and jumps straight to verification, never entering STEP 4 — so a sibling rule parked
+    // there is never read (measured: eval run u4219b). This is where the shared helper is
+    // guaranteed to exist and the agent is guaranteed to still be running.
+    const siblingCallSitesStep = testType === "integration"
+        ? `## STEP 5c: REPLACE INLINE REQUEST BLOCKS IN OTHER SKYRAMP-GENERATED TESTS WITH CALLS TO \`${fileName}\`
+
+**Run this step EVEN IF STEP 3 already satisfied ${testFile} and STEPS 4–5b did nothing.** ${inlineRequestRule}
+
+1. Grep for the other Skyramp-generated test files exactly as in STEP 4 (codegen marker \`${codegenMarker}\`, excluding ${testFile} and \`${fileName}\`).
+2. In each, find every inline request block whose method+path matches a helper now defined in \`${fileName}\`.
+3. For each match: import the helper into that file and replace the block with the call, passing the block's literals (or expressions) as arguments; lift a literal the helper lacks to a defaulted parameter in \`${fileName}\`. Change NOTHING else in that file — its other steps, assertions and order stay verbatim.
+4. A block with no matching helper, or one that differs structurally, stays as it is. Conservative bias: a wrong replacement breaks a passing test; a missed one leaves a duplicate.
+
+`
+        : "";
+    const finalReminderScope = seedsUtils
+        ? `**ONLY MOVE HELPERS THAT ALREADY EXIST IN TEST FILES — NEVER AUTHOR NEW ONES**`
+        : `**ONLY MOVE EXISTING HELPERS FROM OTHER TEST FILES**`;
+    const decisionTreeTail = seedsUtils
+        ? `3. Found other test files with only repetitive patterns? → Step 5b (seed utils from this test's own helpers)
+4. Found no other test files? → Step 5b
+5. Other test files identical to current? → Step 5b
+6. This test file defines no helpers either? → Step 6, NO utils file`
+        : `3. Found other test files with only repetitive patterns? → SKIP to Step 6, NO utils file
+4. Found no other test files? → SKIP to Step 6, NO utils file
+5. Other test files identical to current? → SKIP to Step 6, NO utils file`;
+    const precondition = modularizeFirst
+        ? `
+**PRECONDITION — check your own tool-call history, not the file**: this flow moves the helpers skyramp_modularization created into \`${fileName}\` (STEP 5b). If you have NOT called skyramp_modularization on ${testFile} in this run, STOP: call it now with \`testFile\` set to ${testFile}, \`testType: "${testType}"\`, and \`isTraceBased: true\`, apply its instructions, then call skyramp_reuse_code again with the same arguments as this call. If you HAVE called it and the file still defines no helper functions, that is a legitimate outcome — proceed; STEP 5b will simply have nothing to move.
+`
+        : "";
     return `# CODE REUSE - 6 CLEAR STEPS 
 **CRITICAL WARNING: VIOLATION OF THESE RULES WILL RESULT IN ERROR**
-
+${precondition}
 ## DEFINITIONS (READ FIRST):
 **What is a "Helper Function"?**
 - A helper function is a STANDALONE, DISTINCT function that is ALREADY DEFINED in the code
@@ -65,10 +203,14 @@ Use the Grep tool to search for files containing "${SKYRAMP_UTILS_HEADER}":
 Read the matching non-test files and check if any helpers can be reused in ${testFile}.
 
 ## STEP 3: USE EXISTING HELPERS FROM UTILS SOURCE FILES FOUND IN STEP 2
-If helpers exist in util file that can be reused in ${testFile} without modifying them:
+If helpers exist in util file that can be reused in ${testFile} without modifying them${inlineRequestRule ? " — or, for API request helpers, by EXTENDING them with defaulted parameters as the rules below allow" : ""}:
 - Import them into ${testFile}
 - Remove any duplicate code in ${testFile}
-- Test that ${testFile} still works without any errors and logical is same as original test file.
+${inlineRequestRule
+        ? `- ${inlineRequestRule} This applies to every request step still inline in ${testFile} that matches a utils helper.
+`
+        : ""}- Test that ${testFile} still works without any errors and logical is same as original test file.
+${utilsMergeRule}
 
 ## STEP 4: FIND LOCAL HELPERS IN OTHER SKYRAMP-GENERATED TEST FILES
 
@@ -85,8 +227,7 @@ The result will mix two kinds of files:
 - **Utils file(s)** — already handled by STEP 2/STEP 3.
 - **Other Skyramp-generated test files** — these are the targets of STEP 4 / 4b / 5. Identify them by the \`${codegenMarker}\` codegen marker on line 1 (NOT the bare utils header).
 
-**STOP HERE IF NO OTHER SKYRAMP-GENERATED TEST FILES FOUND**
-**IF NO OTHER SKYRAMP-GENERATED TEST FILES ARE FOUND, SKIP TO STEP 6 - DO NOT CREATE ANY UTILS FILES.**
+${noSiblingsRule}
 
 If other Skyramp-generated test files are found, read those files and look for ALREADY DEFINED helper functions with clear function signatures.
 
@@ -101,8 +242,12 @@ NOT A HELPER FUNCTION (do not extract):
    - No function definition/signature
    - Example: Multiple \`await page.getByTestId("xyz").click()\` directly in test
 
-**IF OTHER TEST FILES ONLY CONTAIN REPETITIVE PATTERNS (NO ACTUAL HELPER FUNCTIONS), SKIP TO STEP 6**
-**IF OTHER SKYRAMP-GENERATED TEST FILES ARE BYTE-FOR-BYTE IDENTICAL TO ${testFile}, SKIP TO STEP 6** (note: helpers being NEAR-duplicates does NOT count as identical — proceed to STEP 4b)
+${inlineRequestRule
+        ? `(Inline request blocks in OTHER test files are not helpers to move — STEP 5c replaces them with calls to the shared helpers.)
+
+`
+        : ""}**IF OTHER TEST FILES ONLY CONTAIN REPETITIVE PATTERNS (NO ACTUAL HELPER FUNCTIONS), SKIP TO ${skipTarget}**
+**IF OTHER SKYRAMP-GENERATED TEST FILES ARE BYTE-FOR-BYTE IDENTICAL TO ${testFile}, SKIP TO ${skipTarget}** (note: helpers being NEAR-duplicates does NOT count as identical — proceed to STEP 4b)
 
 ## STEP 4b: PARAMETERIZE NEAR-DUPLICATE HELPERS ACROSS SKYRAMP-GENERATED TEST FILES
 
@@ -117,53 +262,8 @@ Two helpers (one in ${testFile}, one in another Skyramp-generated test file foun
 3. **The differing literals are trivially liftable to parameters** — no logic needs to be invented to derive them.
 
 If any of the three is false → NOT near-duplicates. Leave them alone.
-
-### Worked example
-
-\`flow-1.spec.ts\` has:
-\`\`\`ts
-export async function upload_translation_file(page, fileName) {
-    await page.waitForTimeout(1500);
-    const responsePromise1 = page.waitForResponse("**/api/files/upload**");
-    const fileUploadPromise0 = page.waitForEvent("filechooser");
-    await page.getByText("Choose a file").first().click();
-    const fileChooser0 = await fileUploadPromise0;
-    await fileChooser0.setFiles(fileName);
-    const response1 = await responsePromise1;
-    await page.waitForTimeout(1500);
-}
-\`\`\`
-
-\`${testFile}\` (current) has:
-\`\`\`ts
-export async function uploadFileToRFI(page, fileName, tabName) {
-    await page.waitForTimeout(1500);
-    const responsePromise1 = page.waitForResponse("**/api/files/upload**");
-    const fileUploadPromise0 = page.waitForEvent("filechooser");
-    await page.getByText("Choose a file").click();
-    const fileChooser0 = await fileUploadPromise0;
-    await fileChooser0.setFiles(fileName);
-    const response1 = await responsePromise1;
-    await page.waitForTimeout(1500);
-}
-\`\`\`
-
-These ARE near-duplicates. Same primitive sequence; the only material difference is the \`.first()\` qualifier on the locator. \`tabName\` is unused in the body — recorder noise, drop it. Correct merge:
-
-\`\`\`ts
-export async function uploadFileViaChooser(page, fileName) {
-    await page.waitForTimeout(1500);
-    const responsePromise = page.waitForResponse("**/api/files/upload**");
-    const fileUploadPromise = page.waitForEvent("filechooser");
-    await page.getByText("Choose a file").first().click();
-    const fileChooser = await fileUploadPromise;
-    await fileChooser.setFiles(fileName);
-    await responsePromise;
-    await page.waitForTimeout(1500);
-}
-\`\`\`
-
-Both test files import and call \`uploadFileViaChooser(page, fileName)\`.
+${nearDupRules}
+${workedExample}
 
 ### Procedure
 
@@ -172,7 +272,7 @@ For each helper defined locally in ${testFile}:
 1. **Scan** each OTHER Skyramp-generated test file from STEP 4 for a helper that matches the near-duplicate criteria above.
 2. **If no match** → skip this helper, move on.
 3. **If exactly one match** → parameterize and merge:
-   - **Name**: pick a name describing INTENT, not the originating test. E.g. \`uploadFileViaChooser\`, not \`upload_translation_file\` or \`uploadFileToRFI\`.
+   - **Name**: pick a name describing INTENT, not the originating test. ${seedsUtils ? policy.namingExample : "E.g. `uploadFileViaChooser`, not `upload_translation_file` or `uploadFileToRFI`."}
    - **Parameters**: the literal values that differ across the two call sites. Drop any parameter that is unused in the body (recorder noise).
    - **Body**: the common primitive sequence with the differing literals replaced by parameters.
    - **Forbidden**: do NOT add if/else, ternaries, defaults, or any logic to bridge the differences. If a single body can't cover both call sites without new logic, they are NOT near-duplicates — leave them alone.
@@ -201,7 +301,7 @@ For each helper defined locally in ${testFile}:
 - The helper functions are ALREADY IMPLEMENTED and working in those OTHER test files
 - The helper in the OTHER test file is byte-for-byte usable in ${testFile} without any modification — if a helper would need parameterizing to fit both call sites, it is a near-duplicate and STEP 4b owns it; do NOT process those helpers here
 
-**IF ANY CONDITION IS NOT MET, SKIP TO STEP 6 - DO NOT CREATE ANY UTILS FILES.**
+**IF ANY CONDITION IS NOT MET, SKIP TO ${skipTarget}${seedsUtils ? "" : " - DO NOT CREATE ANY UTILS FILES"}.**
 
 **Examples of when to SKIP STEP 5:**
 - Other test files have identical repetitive code but no helper functions
@@ -212,10 +312,10 @@ For each helper defined locally in ${testFile}:
 **CRITICAL:** For helpers found in STEP 4:
 1. **CREATE** \`${fileName}\` file if it doesn't exist with the following header:
    \`\`\`${ext}
-   ${generateSkyrampHeader(language)}
+   ${generateSkyrampHeader(lang)}
    \`\`\`
 **CRITICAL: IF \`${fileName}\` is already big, create a new file with a different name and add the header to the new file.**
-2. **COPY** those local helper functions from original test source files to \`${fileName}\` without modifying them
+2. **COPY** those local helper functions from original test source files to \`${fileName}\` without modifying them${seedsUtils ? ` — with ONE exception, checked BEFORE the copy: ${policy.assertionRule} Relocate a trailing excluded assertion into the owning test's body first; the copy that lands in \`${fileName}\` carries none.${policy.moveRule ? ` ${policy.moveRule}` : ""}` : ""}
 3. **DELETE** those local helper functions from test source files (REMOVE THEM COMPLETELY) WITHOUT ANY OTHER CHANGES.
 4. **IMPORT** those local helper functions from \`${fileName}\` back into test source files WITHOUT MAKING ANY OTHER CHANGE.
 5. **IMPORT** those local helper functions from \`${fileName}\` into ${testFile}
@@ -224,7 +324,7 @@ For each helper defined locally in ${testFile}:
 **CRITICAL: DO NOT CREATE UNNECESSARY HELPER FUNCTIONS** 
 **DO NOT CREATE HELPERS BASED ON PATTERNS IN THE CURRENT FILE** 
 
-## STEP 6: VERIFY AND VALIDATE
+${seedStepBlock}${siblingCallSitesStep}## STEP 6: VERIFY AND VALIDATE
 1. **BEFORE** making any changes, read the original test file and identify ALL helper functions
 2. **AFTER** copying helpers to utils, read the original file again to confirm helpers are GONE
 3. **VERIFY** that helper functions are NO LONGER in original test files
@@ -234,15 +334,15 @@ For each helper defined locally in ${testFile}:
 6. **VERIFY** that no unnecessary helper functions were created (functions that duplicate existing functionality)
 7. **VERIFY** that all helper functions in utils are actually imported and used in the test files
 8. **REMOVE** any helper functions that are not being used after refactoring
-9. **NEVER** refactor, reorganize, or restructure existing source test files beyond moving helpers
+9. **NEVER** refactor, reorganize, or restructure existing source test files beyond moving helpers${inlineRequestRule ? " — and, in this flow, replacing an inline request block with a call to the shared helper it duplicates (STEP 3 / STEP 5c)" : ""}
 10. **RUN TESTS** to ensure functionality is preserved after refactoring
 
-**FINAL REMINDER: DO NOT CREATE HELPER FUNCTIONS FROM SCRATCH** 
-**ONLY MOVE EXISTING HELPERS FROM OTHER TEST FILES** 
+**FINAL REMINDER: DO NOT CREATE HELPER FUNCTIONS FROM SCRATCH**
+${finalReminderScope}
 
 **IMPORTANT NOTES:**
 - The process is designed to REUSE existing helper functions, not create new ones
-- If no existing helpers are found, the test file should remain unchanged
+- ${seedsUtils ? `If no existing helpers are found in utils or sibling tests, STEP 5b still moves this test's own helpers into \`${fileName}\` and imports them back — that is the expected first-run outcome, not a no-op` : "If no existing helpers are found, the test file should remain unchanged"}
 - Code reuse is about moving existing, working helper functions between files
 - Never create helper functions based on patterns you see in the current test file
 - Helper functions must have explicit function signatures/definitions
@@ -251,11 +351,16 @@ For each helper defined locally in ${testFile}:
 **DECISION TREE:**
 1. Found existing utils file with helpers? → Import and use them (Step 3)
 2. Found other test files with ACTUAL helper functions? → Move to utils (Step 5)
-3. Found other test files with only repetitive patterns? → SKIP to Step 6, NO utils file
-4. Found no other test files? → SKIP to Step 6, NO utils file
-5. Other test files identical to current? → SKIP to Step 6, NO utils file
+${decisionTreeTail}
+
+${modularizationTail}
 
-**MANDATORY**: After code reuse is complete, proceed to modularization by calling skyramp_modularization tool ONLY for UI, E2E, INTEGRATION or LOAD test types generated from traces.
+${
+    // Gated with the debt it describes: with SkyrampUtils reuse off nothing refuses, and
+    // this text would send the agent to spend a call being told the feature is disabled.
+    isUtilsReuseEnabled()
+        ? `**MANDATORY FINAL STEP — VERIFY**: once every edit above is written, call skyramp_reuse_code again with the SAME testFile, language, framework and testType and \`verify: true\`. It stages the shared utils file for the output commit and checks its invariants (for API helpers: one helper per method+path, status-code-only assertions, method+resource names; for browser helpers: actions and structural waits only, intent names). Resolve anything it reports and re-verify; finish only when it reports PASSED. It passes immediately when no utils file was written. skyramp_enhance_assertions and skyramp_execute_test refuse this test until that verify pass has run.\n`
+        : ""}
 
 SUMMARIZE THE CODE REUSE PROCESS AND THE RESULTS.
 `;

package/build/prompts/modularization/integration-test-modularization.d.ts

@@ -1 +1,3 @@
 export declare function getModularizationPrompt(filePath: string): string;
+/** Structured view of which steps render for the given inputs (for tests). */
+export declare function previewModularizationPlan(filePath: string): import("../test-recommendation/promptPlan.js").PlanPreview;

package/build/prompts/modularization/integration-test-modularization.js

@@ -1,44 +1,44 @@
-export function getModularizationPrompt(filePath) {
-    return `# INTEGRATION TEST MODULARIZATION - SIMPLE AND SAFE
-
-**CRITICAL: Use the 'write' tool to save the modularized code to: ${filePath}**
-**DO NOT use search_replace - use the 'write' tool to overwrite the entire file with the modularized version**
-
-**ABSOLUTELY FORBIDDEN:**
-- DO NOT CREATE ANY INTERFACES, CLASSES, TYPES, OR NEW DATA STRUCTURES. USE INLINE TYPES ONLY.
-- DO NOT CREATE/UPDATE package.json or requirements.txt or pom.xml or build.gradle file
-- DO NOT CHANGE TEST LOGIC, DATA VALUES, ASSERTIONS, OR API CALLS
-- DO NOT MODIFY EXPECTED RESPONSES OR STATUS CODES
-
-## STEP 1: READ AND UNDERSTAND THE ORIGINAL TEST
-**CRITICAL: Before making ANY changes:**
-1. Read ${filePath} completely
+import { isModularizeFirstTarget } from "../../utils/reuseRouting.js";
+import { PromptPlan } from "../test-recommendation/promptPlan.js";
+import { API_HELPERS, ASSERTION_BOUNDARY_RULE_EXTRACT, } from "../shared-helper-policy.js";
+import { renderModularizationPrompt, } from "./render.js";
+// On modularize-first flows (see isModularizeFirstTarget), downstream
+// skyramp_reuse_code consolidates this file's helpers into the shared
+// SkyrampUtils file — so EVERY request step must become a named helper, even
+// when nothing repeats in-file (a linear CRUD scenario calls each endpoint once,
+// so repetition-based extraction yields zero helpers and the utils file can
+// never materialize).
+const _plan = new PromptPlan()
+    .addPhase("main", "Integration Test Modularization", {
+    headerLevel: "hidden",
+    stepFormat: "hash",
+})
+    .step("READ", "READ AND UNDERSTAND THE ORIGINAL TEST", (p) => `**CRITICAL: Before making ANY changes:**
+1. Read ${p.filePath} completely
 2. Identify all API endpoints and their parameters
 3. Identify all test data (request bodies, expected responses)
 4. Identify all assertions and expected values
 5. Document the test flow
-6. **DO NOT PROCEED** until you fully understand what the test does
-
-## STEP 2: FIND REPETITIVE CODE
-Look for API calls that repeat 2+ times with IDENTICAL structure but different data.
-
-## STEP 3: CREATE HELPER FUNCTIONS - EXTRACT ONLY, NO CHANGES
-
-**GOLDEN RULE: COPY-PASTE THE ORIGINAL CODE INTO HELPERS, JUST ADD PARAMETERS AND REPLACE HARDCODED VALUES WITH PARAMETERS**
+6. **DO NOT PROCEED** until you fully understand what the test does`)
+    .step("IDENTIFY", (p) => (p.utilsReuse ? "IDENTIFY REQUEST STEPS" : "FIND REPETITIVE CODE"), (p) => p.utilsReuse
+    ? `A request step = one API call plus the assertions that verify its response.
+This project consolidates test helpers into a shared utils file, so EVERY request step becomes a named helper function — the step does NOT need to repeat.
+List every request step in the test (e.g. create product, create order, update order, get order).`
+    : `Look for API calls that repeat 2+ times with IDENTICAL structure but different data.`)
+    .step("EXTRACT", "CREATE HELPER FUNCTIONS - EXTRACT ONLY, NO CHANGES", (p) => `**GOLDEN RULE: COPY-PASTE THE ORIGINAL CODE INTO HELPERS, JUST ADD PARAMETERS AND REPLACE HARDCODED VALUES WITH PARAMETERS**
 
 **CRITICAL RULES:**
 1. **EXACT CODE COPY** - Copy the API call code EXACTLY as-is from the original test
-2. **ONLY ADD PARAMETERS** - The ONLY change allowed is converting hardcoded values to parameters
+2. **ONLY ADD PARAMETERS** - The ONLY change allowed is converting hardcoded values to parameters${p.utilsReuse
+    ? " — plus ONE placement exception: a response-body assertion that would land inside a helper is placed in the test body, applied to the response the helper returns (same check, same expected value, same relative order). That relocation is the only assertion move allowed; see HELPER SHAPE below"
+    : ""}
 3. **NEVER GENERALIZE SELECTORS** - Keep all selectors/locators exactly as they are in the original code (do not refactor into dynamic template strings)
-4. **NO LOGIC CHANGES** - Do not modify conditions, validations, or assertions
+4. **NO LOGIC CHANGES** - Do not modify conditions, validations, or assertions${p.utilsReuse ? " (relocating a body assertion per rule 2 is a placement, not a change)" : ""}
 5. **NO DATA CHANGES** - Do not change any request/response values or expected results
 6. **PRESERVE PATH PARAMETERS** - API path parameters must be passed as function parameters
 7. **PRESERVE ORDER** - Keep all operations in the exact same order
 
-**PARAMETER CONVERSION RULES:**
-- Find the values that DIFFER between repetitions (e.g., user IDs, product names)
-- Make ONLY those differing values into parameters
-- Keep everything else EXACTLY the same
+${p.utilsReuse ? sharedHelperShape(p) : repetitionParameterRules()}
 
 **EXAMPLE OF CORRECT EXTRACTION:**
 \`\`\`typescript
@@ -49,12 +49,18 @@ expect(response1.status).toBe(200);
 const response2 = await fetch("/api/users/2");
 expect(response2.status).toBe(200);
 
-// Correct helper (EXACT copy + parameters):
-async function getUser(userId: number) {
+// Correct helper (EXACT copy + parameters${p.utilsReuse ? "; the expected status is a defaulted parameter per HELPER SHAPE" : ""}):
+${p.utilsReuse
+    ? `async function getUser(userId: number, expectedStatus = 200) {
+  const response = await fetch(\`/api/users/\${userId}\`);
+  expect(response.status).toBe(expectedStatus);
+  return response;
+}`
+    : `async function getUser(userId: number) {
   const response = await fetch(\`/api/users/\${userId}\`);
   expect(response.status).toBe(200);
   return response;
-}
+}`}
 \`\`\`
 
 **WHAT NOT TO DO:**
@@ -64,14 +70,9 @@ Modifying expected status codes
 Changing request/response validation
 Reordering operations
 "Improving" error handling
-Adding new assertions
-
-## STEP 4: USE HELPERS WITH EXACT SAME DATA
-When calling the helpers, use the EXACT same values from the original test.
-
-## STEP 5: FINAL VERIFICATION
-
-**BEFORE WRITING ANY CODE, VERIFY:**
+Adding new assertions`)
+    .step("USE", "USE HELPERS WITH EXACT SAME DATA", () => `When calling the helpers, use the EXACT same values from the original test.`)
+    .step("VERIFY", "FINAL VERIFICATION", () => `**BEFORE WRITING ANY CODE, VERIFY:**
 - [ ] I have read and understood the original test completely
 - [ ] I have identified all API calls and their parameters
 - [ ] I have documented all expected responses and assertions
@@ -91,5 +92,46 @@ Run through the modularized test mentally:
 2. Does it use the exact same request data?
 3. Does it expect the exact same responses?
 
-If ANY answer is "no", DO NOT submit - fix the modularization first.`;
+If ANY answer is "no", DO NOT submit - fix the modularization first.`)
+    .done();
+// Shared-file helper shape: the helpers this step creates are consolidated into
+// SkyrampUtils by the reuse pass, so each one must be nameable and callable by
+// the next scenario — canonical names, scenario values as arguments, and no
+// scenario-specific claims inside the helper.
+function sharedHelperShape(p) {
+    return `**HELPER SHAPE (one helper per request step from Step ${_plan.labels.IDENTIFY}):**
+- ${API_HELPERS.namingRule}
+- **PARAMETERS**: pass in the client/session object, plus every value the step reads from a previous step's response (IDs used in paths or bodies), plus every body value this scenario varies or its assertions reference (names, prices, quantities, percentages). Values that never vary and that no assertion reads may stay hardcoded — do not invent parameters nothing passes differently.
+- **SCENARIO VALUES GO THROUGH \`data_override\`, NOT THE BODY STRING**: apply each parameterized body value via the request's \`data_override\` map (that is what it is for) and leave the raw body string as generated. A scenario literal edited into the body string makes this helper unmergeable with the same step from another test.
+- **RETURN** the response object so later steps can chain and assert from it.
+- ${API_HELPERS.assertionRule} ${ASSERTION_BOUNDARY_RULE_EXTRACT}
+- Helpers are module-level named functions in ${p.filePath}; the test body becomes a sequence of helper calls plus this scenario's assertions, in the original order.
+- Keep everything else EXACTLY the same.`;
+}
+function repetitionParameterRules() {
+    return `**PARAMETER CONVERSION RULES:**
+- Find the values that DIFFER between repetitions (e.g., user IDs, product names)
+- Make ONLY those differing values into parameters
+- Keep everything else EXACTLY the same`;
+}
+export function getModularizationPrompt(filePath) {
+    const utilsReuse = isModularizeFirstTarget("integration");
+    return renderModularizationPrompt({
+        title: "INTEGRATION TEST MODULARIZATION - SIMPLE AND SAFE",
+        forbidden: [
+            "DO NOT CREATE ANY INTERFACES, CLASSES, TYPES, OR NEW DATA STRUCTURES. USE INLINE TYPES ONLY.",
+            "DO NOT CREATE/UPDATE package.json or requirements.txt or pom.xml or build.gradle file",
+            `DO NOT CHANGE TEST LOGIC, DATA VALUES, ASSERTIONS, OR API CALLS${utilsReuse ? " (moving a response-body assertion out of a helper into the test body, verbatim, is a placement — not a change)" : ""}`,
+            "DO NOT MODIFY EXPECTED RESPONSES OR STATUS CODES",
+        ],
+        plan: _plan,
+        params: { filePath, utilsReuse },
+    });
+}
+/** Structured view of which steps render for the given inputs (for tests). */
+export function previewModularizationPlan(filePath) {
+    return _plan.preview({
+        filePath,
+        utilsReuse: isModularizeFirstTarget("integration"),
+    });
 }

package/build/prompts/modularization/render.d.ts

@@ -0,0 +1,18 @@
+import type { PromptPlan } from "../test-recommendation/promptPlan.js";
+/**
+ * Parameters both modularization plans render against.
+ * `utilsReuse` is true on modularize-first flows (see isModularizeFirstTarget):
+ * downstream skyramp_reuse_code consolidates this file's helpers into the shared
+ * SkyrampUtils file, which changes what a helper may be named and may assert.
+ */
+export interface ModularizationParams {
+    filePath: string;
+    utilsReuse: boolean;
+}
+/** The scaffold shared by the UI and integration modularization prompts. */
+export declare function renderModularizationPrompt(opts: {
+    title: string;
+    forbidden: string[];
+    plan: PromptPlan<ModularizationParams>;
+    params: ModularizationParams;
+}): string;

package/build/prompts/modularization/render.js

@@ -0,0 +1,12 @@
+/** The scaffold shared by the UI and integration modularization prompts. */
+export function renderModularizationPrompt(opts) {
+    return `# ${opts.title}
+
+**CRITICAL: Use the 'write' tool to save the modularized code to: ${opts.params.filePath}**
+**DO NOT use search_replace - use the 'write' tool to overwrite the entire file with the modularized version**
+
+**ABSOLUTELY FORBIDDEN:**
+${opts.forbidden.map((f) => `- ${f}`).join("\n")}
+
+${opts.plan.render(opts.params)}`;
+}

package/build/prompts/modularization/ui-test-modularization.d.ts

@@ -1 +1,3 @@
-export declare function getModularizationPrompt(filePath: string): string;
+export declare function getModularizationPrompt(filePath: string, testType: string, language?: string): string;
+/** Structured view of which steps render for the given inputs (for tests). */
+export declare function previewModularizationPlan(filePath: string, testType: string, language?: string): import("../test-recommendation/promptPlan.js").PlanPreview;