@skyramp/mcp 0.3.5 → 0.3.6-rc.1

package/build/playwright/registerPlaywrightTools.js

@@ -4,36 +4,111 @@
  */
 import { z } from "zod";
 import { logger } from "../utils/logger.js";
-import { dualChannelResult } from "../utils/utils.js";
 import { PlaywrightTraceService, } from "./PlaywrightTraceService.js";
 let _service = null;
 export function getPlaywrightTraceService() {
     return _service;
 }
 /**
- * The one browser tool whose result is re-shaped on the way out — see
- * toStructuredBlueprintResult.
+ * The one browser tool whose text payload is shrunk on the way out — see
+ * shrinkBlueprintResult.
  */
 const BLUEPRINT_TOOL = "browser_blueprint";
 /**
- * Re-shape a browser_blueprint result onto both MCP result channels.
+ * Shrink a browser_blueprint result on the text channel it already arrives on.
  *
- * SKYR-4194. The browser tools are registered here as passthroughs, and the fork
- * returns the captured DOM as one `content[]` text block with no
- * `structuredContent` — the shape whose spill the agent's file reader refuses.
- * See `dualChannelResult` for why both channels carry the payload.
+ * SKYR-4267. SKYR-4194 (#752) also copied the capture into `structuredContent`
+ * as a JSON string. Claude Code measures that copy against its size cap and
+ * drops `content[]` when both channels are present, so the escape added to
+ * every quote and newline counted against the cap. On the largest real capture
+ * (`sb20-bucket-visibility`) the text is 26,542 bytes and the escaped string
+ * 29,411 — which BOTH channels carried, because `dualChannelResult` puts the
+ * JSON serialization of `structuredContent` into `content[]`, so 58,822 went on
+ * the wire.
  *
- * An error result is returned untouched: the SDK's outputSchema check returns
- * early on `isError`, so it needs no structuredContent.
+ * The escaping also collapsed the whole payload onto ONE line, so a spill file
+ * read at a line offset returned nothing at all
+ * (`repo14-U06-field-reorder-toast`). Dropping it does not give the capture its
+ * newlines back: the fork pretty-prints the JSON, but shrinkBlueprintText below
+ * re-serializes with no indent, so the body is still one line. What returns are
+ * the `### ` section headers around it, so an offset read now lands on a header
+ * instead of erroring — the failure is mitigated, not closed.
+ *
+ * The text channel is the one every agent CLI reads, and it is what the other
+ * browser tools already return, so the capture rides it alone.
+ *
+ * An error result is returned untouched.
  */
-function toStructuredBlueprintResult(result) {
+function shrinkBlueprintResult(result) {
     if (result?.isError)
         return result;
-    const blueprint = (result?.content ?? [])
-        .filter((block) => block?.type === "text")
-        .map((block) => block.text)
-        .join("\n");
-    return dualChannelResult({ blueprint });
+    return {
+        ...result,
+        content: (result?.content ?? []).map((block) => block?.type === "text"
+            ? { ...block, text: shrinkBlueprintText(block.text) }
+            : block),
+    };
+}
+/**
+ * Drop every null-valued key, at any depth.
+ *
+ * SKYR-4208. Array entries are left alone — a null there holds a position, and
+ * removing it would renumber everything after it.
+ */
+function dropNulls(value) {
+    if (Array.isArray(value))
+        return value.map(dropNulls);
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, v]) => v !== null)
+        .map(([k, v]) => [k, dropNulls(v)]));
+}
+/**
+ * Minify the JSON body of a browser_blueprint payload and drop its null keys.
+ *
+ * SKYR-4208. The fork pretty-prints the capture behind a `### Result` header.
+ * On eval run 32458076607 (962 payloads, 11,368 elements) the indentation is
+ * 35.4% of the payload's tokens, and the null keys a further 6.8% — `stableId`,
+ * `testId` and `fingerprint` are null on 72-94% of elements and cost their key
+ * name on every one.
+ *
+ * Both steps are lossless: the agent parses the same fields with the same
+ * values, and an absent key already says what a null key says. Keys that merely
+ * hold their DEFAULT (`framePath: []`, `shadowRoot: false`) are deliberately
+ * kept — dropping those makes the agent infer the default from an absence, and
+ * `framePath` stops being empty as soon as the page has an iframe.
+ *
+ * The header and anything else outside the JSON survive unchanged, and a body
+ * that does not parse is returned as it arrived.
+ */
+function shrinkBlueprintText(text) {
+    const start = text.indexOf("{");
+    if (start === -1)
+        return text;
+    // The fork can append more sections after `### Result` — `### Page` whenever
+    // the title or URL changed since the last call, and `### Modal state`,
+    // `### Snapshot` or `### Events` when the page produced them. Only the Result
+    // section holds JSON, so the body has to stop at the next header; reading to
+    // the end of the string makes the parse throw and costs the whole saving.
+    // A `### ` at the start of a line cannot sit inside the JSON, because JSON
+    // escapes the newline that would have to precede it.
+    const nextSection = text.slice(start).search(/\n### /);
+    const end = nextSection === -1 ? text.length : start + nextSection;
+    // The blank line the fork puts after a section belongs to the payload, not to
+    // the JSON, so it is put back byte-for-byte rather than parsed away.
+    const body = text.slice(start, end);
+    const json = body.trimEnd();
+    try {
+        return (text.slice(0, start) +
+            JSON.stringify(dropNulls(JSON.parse(json))) +
+            body.slice(json.length) +
+            text.slice(end));
+    }
+    catch {
+        logger.warning("browser_blueprint payload did not parse as JSON — delivering it unshrunk (SKYR-4208)");
+        return text;
+    }
 }
 export async function registerPlaywrightTools(server, options) {
     _service = new PlaywrightTraceService(options);
@@ -98,19 +173,6 @@ export async function registerPlaywrightTools(server, options) {
         server.registerTool(tool.name, {
             description: tool.description || `Playwright tool: ${tool.name}`,
             inputSchema: zodSchema,
-            // SKYR-4194: only browser_blueprint returns its payload via
-            // structuredContent, which requires a declared outputSchema. The other
-            // browser tools return small results, and some return images, which this
-            // text-only re-shaping would drop.
-            ...(isBlueprint
-                ? {
-                    outputSchema: {
-                        blueprint: z
-                            .string()
-                            .describe("The captured PageBlueprint — sections, elements, and their logical names. Read and follow this field."),
-                    },
-                }
-                : {}),
         }, async (params) => {
             if (!_service?.isInitialized()) {
                 return {
@@ -124,7 +186,7 @@ export async function registerPlaywrightTools(server, options) {
                 };
             }
             const result = await _service.callTool(tool.name, params);
-            return isBlueprint ? toStructuredBlueprintResult(result) : result;
+            return isBlueprint ? shrinkBlueprintResult(result) : result;
         });
     }
     logger.info(`Registered ${filteredTools.length} Playwright tools: ${filteredTools.map((t) => t.name).join(", ")}`);

package/build/playwright/traceRecordingPrompt.d.ts

@@ -8,6 +8,12 @@ export interface TraceRecordingPromptOpts {
     outputDir?: string;
     /** Whether to run skyramp_modularization after generation. Default: true. Set false in CI. */
     modularize?: boolean;
+    /**
+     * With modularize=false: the generation result itself may still instruct a
+     * modularization pass (codeReuse flows that seed a shared utils file). When
+     * true, the note defers to that result instead of banning the tool outright.
+     */
+    modularizeViaGenerationResult?: boolean;
 }
 export declare function getTraceRecordingPromptText(opts?: TraceRecordingPromptOpts): string;
 export declare function registerTraceRecordingPrompt(server: McpServer): void;

package/build/playwright/traceRecordingPrompt.js

@@ -13,10 +13,14 @@ export function getTraceRecordingPromptText(opts) {
         : `Call \`skyramp_export_zip\` with \`outputPath\` set to the absolute zip path (same directory and base name as the test file, replacing \`.spec.ts\` with \`.zip\`).`;
     const generateInstruction = modularize
         ? `Call \`skyramp_ui_test_generation\` with \`playwrightInput\` set to the absolute zip path from the Export step.`
-        : `Call \`skyramp_ui_test_generation\` with \`playwrightInput\` set to the absolute zip path from step 5 and \`modularizeCode: false\`.`;
+        : opts?.modularizeViaGenerationResult
+            ? `Call \`skyramp_ui_test_generation\` with \`playwrightInput\` set to the absolute zip path from step 5, \`modularizeCode: false\`, and \`codeReuse: true\` — its result lists the post-generation steps (assertion enhancement, modularization, reuse) with their arguments.`
+            : `Call \`skyramp_ui_test_generation\` with \`playwrightInput\` set to the absolute zip path from step 5 and \`modularizeCode: false\`.`;
     const modularizeNote = modularize
         ? `- **After generating the test**, run \`skyramp_modularization\` for code quality.`
-        : `- Do NOT run \`skyramp_modularization\` — skip modularization in CI.`;
+        : opts?.modularizeViaGenerationResult
+            ? `- Run \`skyramp_modularization\` ONLY when the generation result's CRITICAL NEXT STEPS instruct it (with the arguments they give) — never on your own initiative.`
+            : `- Do NOT run \`skyramp_modularization\` — skip modularization in CI.`;
     return `## Skyramp UI Test Recording
 
 ${getPersonaPrefix()} For UI recording, every action must be grounded in what \`browser_snapshot\` returns. If an element is not visible in the snapshot, do not interact with it.

package/build/prompts/code-reuse.d.ts

@@ -1,3 +1,2 @@
 import type { ScopedPomInput } from "../utils/pom-scope/index.js";
-export declare function isPomAwareTarget(language: string, framework?: string): boolean;
-export declare function getCodeReusePrompt(testFile: string, language: string, framework?: string, scopedPoms?: ScopedPomInput): string;
+export declare function getCodeReusePrompt(testFile: string, language: string, framework?: string, scopedPoms?: ScopedPomInput, testType?: string): string;

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;