@skyramp/mcp 0.3.4 → 0.3.6-rc.1

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;

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

@@ -1,37 +1,37 @@
-export function getModularizationPrompt(filePath) {
-    return `# UI TEST MODULARIZATION - IMPROVE READABILITY AND REDUCE DUPLICATION
-
-**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 INTERFACES, CLASSES, TYPES, NEW FILES, OR NEW DATA STRUCTURES
-- DO NOT CHANGE TEST LOGIC, DATA VALUES, CALCULATIONS, OR ASSERTIONS
-- DO NOT CREATE/UPDATE  DEPENDENCY FILES package.json, requirements.txt, pom.xml, build.gradle file
-
-## STEP 1: READ THE ORIGINAL TEST
-Read ${filePath} completely and identify:
+import { isModularizeFirstTarget } from "../../utils/reuseRouting.js";
+import { PromptPlan } from "../test-recommendation/promptPlan.js";
+import { ASSERTION_BOUNDARY_RULE_EXTRACT, BROWSER_HELPERS, BROWSER_VALUE_ASSERTIONS, } from "../shared-helper-policy.js";
+import { renderModularizationPrompt, } from "./render.js";
+// On modularize-first UI flows (utils reuse on, POM reuse off), downstream
+// skyramp_reuse_code consolidates this file's helpers into the shared
+// SkyrampUtils file, where the next scenario's test calls them. That changes
+// what a helper may be named and may assert — the mechanism (logical-section
+// extraction) is the same either way. E2E shares this prompt but is not a
+// modularize-first target, so it never sees these rules.
+const _plan = new PromptPlan()
+    .addPhase("main", "UI Test Modularization", {
+    headerLevel: "hidden",
+    stepFormat: "hash",
+})
+    .step("READ", "READ THE ORIGINAL TEST", (p) => `Read ${p.filePath} completely and identify:
 - All test data values (names, prices, quantities, totals)
-- All test data including calculations and expected results 
+- All test data including calculations and expected results
 - The exact test flow
-- **Check if code is already modularized** (e.g., \`breakpoint_section_0\`, \`breakpoint_section_1\` functions)
-
-## STEP 2: HANDLE PRE-MODULARIZED CODE
-
-**IF CODE IS ALREADY MODULARIZED** (has functions like \`breakpoint_section_0\`, \`breakpoint_section_1\`):
+- **Check if code is already modularized** (e.g., \`breakpoint_section_0\`, \`breakpoint_section_1\` functions)`)
+    .step("PREMOD", "HANDLE PRE-MODULARIZED CODE", (p) => `**IF CODE IS ALREADY MODULARIZED** (has functions like \`breakpoint_section_0\`, \`breakpoint_section_1\`):
 1. **RENAME** functions with meaningful names that describe what they do
    - BAD: \`breakpoint_section_0\`, \`breakpoint_section_1\`
    - GOOD: \`createProduct\`, \`editProductPrice\`, \`createOrder\`
 2. **PARAMETERIZE** hardcoded values in these functions
 3. **DO NOT** change the function logic or structure
-4. **DO NOT** create new functions - work with existing ones
-5. **SKIP to STEP 5** for verification
+4. **DO NOT** create new functions - work with existing ones${p.utilsReuse
+    ? ` — with ONE exception, item 5
+5. **APPLY THE SHARED HELPER SHAPE** (the rules block inside Step ${_plan.labels.EXTRACT}; read that block, then return here): canonical intent names; value assertions moved out of the helper into the test body right after its call; a value assertion that sits BETWEEN two actions splits the function at that point into two intent-named functions — the only new functions this branch may create`
+    : ""}
+${p.utilsReuse ? "6" : "5"}. **SKIP to Step ${_plan.labels.VERIFY}** for verification
 
-**IF CODE IS NOT MODULARIZED**, proceed to STEP 3.
-
-## STEP 3: IDENTIFY EXTRACTION OPPORTUNITIES
-
-Extract code in TWO scenarios:
+**IF CODE IS NOT MODULARIZED**, proceed to Step ${_plan.labels.IDENTIFY}.`)
+    .step("IDENTIFY", "IDENTIFY EXTRACTION OPPORTUNITIES", (p) => `Extract code in TWO scenarios:
 
 **A) REPETITIVE CODE** - Code that repeats 2+ times with IDENTICAL structure but different data
 - Extract EACH occurrence as a separate helper call
@@ -39,15 +39,17 @@ Extract code in TWO scenarios:
 
 **B) LOGICAL SECTIONS** - Self-contained operations (5+ lines) that improve readability
 - Examples: "create product", "fill form", "verify result"
-- Must be cohesive - related operations that achieve one goal
+- Must be cohesive - related operations that achieve one goal${p.utilsReuse
+    ? `
+- This project consolidates test helpers into a shared utils file, so EVERY logical section that performs a user action (open a form, fill and submit it, add or remove an item, apply an option) becomes a named helper — the section does NOT need to repeat. Another scenario's test will call the same helper with its own values.`
+    : ""}
 
 **Don't extract:**
-- Code less than 5 lines (unless highly repetitive)
-- Navigation sequences (\`navbar-\` clicks, \`page.goto\`)
-
-## STEP 3: EXTRACT INTO HELPERS
-
-**GOLDEN RULE: Copy the original code exactly, only add parameters for values that differ**
+- Code less than 5 lines (unless highly repetitive${p.utilsReuse
+    ? ", or a cohesive user-action section — those become helpers regardless of length, per B above"
+    : ""})
+- Navigation sequences (\`navbar-\` clicks, \`page.goto\`)`)
+    .step("EXTRACT", "EXTRACT INTO HELPERS", (p) => `**GOLDEN RULE: Copy the original code exactly, only add parameters for values that differ**
 
 **CRITICAL - AVOID BUGS:**
 - Copy the code block EXACTLY as-is from the original test
@@ -62,9 +64,11 @@ Extract code in TWO scenarios:
 - **Replace ALL hardcoded values with parameters** - No leftover hardcoded fills (selectors are the ONLY exception: selectors must remain exactly as in the original code)
 - **NEVER create new conditional logic** (no ternaries, no if/else, no loops to derive parameter values)
 - **NEVER add logic that wasn't in the original code**
-- Keep ALL existing logic, calculations, and assertions unchanged
+- Keep ALL existing logic, calculations, and assertions unchanged${p.utilsReuse
+    ? " — ONE exception: a value assertion that would land inside a helper is placed in the test body instead (same selector, same expected value, same relative order): after the helper call if it trailed the helper's actions, or between two helper calls — splitting the helper there — if it sat between actions. That relocation is the only assertion move allowed; see SHARED HELPER SHAPE below"
+    : ""}
 - Keep ALL lines in the same order (except: remove fills with wrong/temporary hardcoded values)
-
+${p.utilsReuse ? `\n${sharedHelperShape()}\n` : ""}
 **PARAMETERIZATION BEST PRACTICES:**
 1. **Use individual parameters, not data objects** - Makes helper usage clearer
    - GOOD: \`createProduct(page, name, price, category)\`
@@ -129,25 +133,27 @@ await addItem(page, "item1");
 await addItem(page, "item2");
 await addItem(page, "item3");
 
-\`\`\`
-
-## STEP 4: CALL HELPERS WITH EXACT SAME VALUES
-Use the EXACT same values from the original test when calling helpers.
-
-## STEP 5: VERIFY - CRITICAL CHECKS
-
-**BUGS TO AVOID:**
+\`\`\``)
+    .step("USE", "CALL HELPERS WITH EXACT SAME VALUES", () => `Use the EXACT same values from the original test when calling helpers.`)
+    .step("VERIFY", "VERIFY - CRITICAL CHECKS", (p) => `**BUGS TO AVOID:**
 - [ ] **NO TYPE ANNOTATIONS FOR \`page\` IN FUNCTION SIGNATURES** - Parameters must be untyped (e.g., \`page\`, not \`page: Page\`)
 - [ ] **NO RETURN TYPES** - Do not add \`: Promise<void>\` or any return type annotations
-- [ ] **ALL field mappings verified** - EVERY \`.fill()\` uses the correct parameter. Check field gets quantity parameter, NOT hardcoded 
+- [ ] **ALL field mappings verified** - EVERY \`.fill()\` uses the correct parameter. Check field gets quantity parameter, NOT hardcoded
 - [ ] **No duplicate helpers** - Consolidate similar helpers (e.g., one createOrder vs createSimpleOrder + createOrderWithItems)
 - [ ] **No nested helpers** - Helpers don't call other helpers unnecessarily
 - [ ] **Clear parameters** - Individual parameters (name, price) not data objects
 - [ ] **No duplicate actions** - Don't click "Add Product" button in test AND in helper - choose one place
 - [ ] **No new loops** - Exception: acceptable if it improves readability and items are explicit at call site
-
+${p.utilsReuse
+    ? `
+**SHARED HELPER SHAPE:**
+- [ ] Every helper name is a canonical intent (\`openEditOrderForm\`, \`applyDiscount\`) with no scenario value or adjective in it
+- [ ] No helper contains a value assertion (${BROWSER_VALUE_ASSERTIONS}) — each sits in the test body, right after the helper call it verifies
+- [ ] Every selector inside a helper is byte-identical to the original test
+`
+    : ""}
 **DATA INTEGRITY:**
-- [ ] Helpers are exact copies of original + parameters only
+- [ ] Helpers are exact copies of original + parameters only${p.utilsReuse ? " (minus the value assertions relocated to the test body)" : ""}
 - [ ] All data values match the original test exactly
 - [ ] All calculations produce identical results
 - [ ] Helper calls use the same values as original
@@ -167,5 +173,41 @@ Use the EXACT same values from the original test when calling helpers.
 
 If ANY answer is "no", fix it before submitting.
 
-**When in doubt, don't extract - keep original code unchanged.**`;
+**When in doubt, don't extract - keep original code unchanged.**`)
+    .done();
+// Shared-file helper shape: the reuse pass moves these helpers into SkyrampUtils,
+// where the next scenario's test calls them with its own values. A helper is
+// therefore named for the action it performs and carries no claim about this
+// scenario's data — a `toHaveText("Total: $899.98")` inside a shared helper
+// fails every other caller. Selectors stay verbatim regardless (a selector is
+// not scenario data; parameterizing it invents a template the recorder never saw).
+function sharedHelperShape() {
+    return `**SHARED HELPER SHAPE (this project consolidates helpers into a shared utils file):**
+- ${BROWSER_HELPERS.namingRule}
+- **PARAMETERS**: \`page\`, plus every value this scenario types or selects (${BROWSER_HELPERS.liftableLiterals}). Selectors are NEVER parameters — they stay verbatim inside the helper body.
+- ${BROWSER_HELPERS.assertionRule} ${ASSERTION_BOUNDARY_RULE_EXTRACT}
+- Helpers are module-level named functions in this file; the test body becomes navigation + a sequence of helper calls + this scenario's assertions, in the original order.`;
+}
+export function getModularizationPrompt(filePath, testType, language) {
+    const params = {
+        filePath,
+        utilsReuse: isModularizeFirstTarget(testType, language),
+    };
+    return renderModularizationPrompt({
+        title: "UI TEST MODULARIZATION - IMPROVE READABILITY AND REDUCE DUPLICATION",
+        forbidden: [
+            "DO NOT CREATE INTERFACES, CLASSES, TYPES, NEW FILES, OR NEW DATA STRUCTURES",
+            `DO NOT CHANGE TEST LOGIC, DATA VALUES, CALCULATIONS, OR ASSERTIONS${params.utilsReuse ? " (moving a value assertion out of a helper into the test body, verbatim, is a placement — not a change)" : ""}`,
+            "DO NOT CREATE/UPDATE  DEPENDENCY FILES package.json, requirements.txt, pom.xml, build.gradle file",
+        ],
+        plan: _plan,
+        params,
+    });
+}
+/** Structured view of which steps render for the given inputs (for tests). */
+export function previewModularizationPlan(filePath, testType, language) {
+    return _plan.preview({
+        filePath,
+        utilsReuse: isModularizeFirstTarget(testType, language),
+    });
 }

package/build/prompts/pom-aware-code-reuse.js

@@ -148,9 +148,11 @@ Use this exact format for the file:
 - **Properties:**
   - \`propertyName\` — selector: \`exact-selector-string\`
 - **Methods:**
-  - \`methodName(param1, param2)\` — description; ⏱ timing-aware: waitForTimeout(Xms) + sleep(Ys) | 🌐 network-aware: waitForResponse('**/pattern**') | (omit tags if neither)
+  - \`methodName(param1, param2)\` — description; selectors: \`login-submit-btn\`, \`table-row-*\`; ⏱ timing-aware: waitForTimeout(Xms) + sleep(Ys) | 🌐 network-aware: waitForResponse('**/pattern**') | (omit tags if neither)
 \`\`\`
 
+**Selectors on methods are REQUIRED.** List every selector string the method touches, each in backticks, in the same form the source uses. If the method builds a selector from a parameter or matches a family of elements, record the WILDCARD form, not one concrete instance — \`o2-table-row-*\` for \`starts-with(@data-test,"o2-table-row-")\`, \`function-list-name-cell-*\` for \`[data-test="function-list-name-cell-\${name}"]\`. A method that touches no selector (a pure wait, a getter over another method) records \`selectors: none\`.
+
 **Tier-2 entries in the catalog:** for files cataloged at signature level, the entry contains the class name, the import path, a \`- **Methods:**\` list of names/signatures only, and the matched selectors from STEP 1 under \`- **Properties:**\`. Mark such entries with \`<!-- depth: signature -->\` on the line after the class heading so a later run knows the entry is shallow.
 
 **Free-function helper modules** use the same format with the module basename as the heading (add \`(module functions, not a class)\` after it), each exported function as a Method, and no Iframe line unless a function scopes one. They substitute as imported calls — \`import { bookFirstEvent } from '<path>'; await bookFirstEvent(page);\` — under the same evidence and confidence rules as class methods, and are verified the same way.

package/build/prompts/shared-helper-policy.d.ts

@@ -0,0 +1,57 @@
+/** Why the assertion rule exists — quoted wherever the rule is stated. */
+export declare const SHARED_HELPER_WHY = "A scenario-specific assertion inside a helper carries one scenario's data into a shared function and fails the next scenario that calls it \u2014 the helper is shared, the claims are not.";
+export declare const BROWSER_STRUCTURAL_WAITS = "`waitForResponse`, `waitForLoadState`, `waitFor({ state: \"visible\" })`, and `toBeVisible` on a STRUCTURAL locator (a test id, or a role + name of a control) \u2014 a check that an element rendered, not what it says";
+/**
+ * Relocation never reorders execution. Two variants, because the two ends of the
+ * chain may do different things with a helper whose value assertion sits BETWEEN
+ * two actions: modularization (which authors helpers) splits it; reuse (which
+ * only moves existing helpers) leaves it local.
+ */
+export declare const ASSERTION_BOUNDARY_RULE_EXTRACT = "Relocation must preserve the original order: an assertion that sits BETWEEN two actions is a HELPER BOUNDARY \u2014 end the helper before it and start the next helper after it (each named per the naming rule), so the assertion sits between the two calls in the test body exactly where it was. Never move an assertion across an action.";
+export declare const ASSERTION_BOUNDARY_RULE_MOVE = "Relocation must preserve the original order: only a TRAILING assertion (after the helper's last action) may move to the test body right after the call. A helper whose excluded assertion sits BETWEEN two actions is NOT moved and NOT split \u2014 leave it local in the test file; splitting is modularization's job, not this step's.";
+export declare const BROWSER_VALUE_ASSERTIONS = "any `expect` whose matcher OR locator carries scenario data: `toHaveText`, `toContainText`, `toHaveValue`, `toHaveCount`, `toHaveURL` with a literal, or ANY matcher \u2014 `toBeVisible` included \u2014 on a locator that embeds scenario text such as `getByText(\"Total: $899.98\")`";
+/**
+ * A helper kept local must never share a name with a utils export — the import
+ * and the local definition would then describe two different behaviours under
+ * one name, and a later reader (or a deterministic gate) cannot tell which runs.
+ */
+export declare const NO_SHADOWING_RULE = "If a helper stays local for any reason, it must NOT share a name with any export of the utils file \u2014 rename the local one to state what differs (e.g. `submitEditOrderFormNoWait`). A test file never defines a helper with the same name as a utils export.";
+export interface HelperPolicy {
+    kind: "api" | "browser";
+    /** How two helpers are recognised as "the same step" (lower-case phrase). */
+    sameStep: string;
+    /** The literals that may legitimately differ between two versions of a step. */
+    liftableLiterals: string;
+    /**
+     * Differences that are generator noise, not structure — two bodies that differ
+     * only by these are the same step. Empty when the kind has none.
+     */
+    structuralNoise: string;
+    /** Canonical naming rule (full sentence(s)). */
+    namingRule: string;
+    /** What a shared helper may and may not assert (full sentence(s)). */
+    assertionRule: string;
+    /** Where a relocated assertion goes in the test body. */
+    relocationTarget: string;
+    /**
+     * Order-preserving rule for MOVING an existing helper (reuse). Empty when the
+     * kind's helpers cannot carry a between-actions assertion (API: one request
+     * plus trailing assertions).
+     */
+    moveRule: string;
+    /** Naming example for STEP 4b's procedure, matching the rendered worked example. */
+    namingExample: string;
+    /** "One X = one helper" closing line for a utils file. */
+    oneHelperRule: (fileName: string) => string;
+    /** Kind-specific near-duplicate / merge section for STEP 4b of code reuse. */
+    nearDupRules: (fileName: string) => string;
+    /**
+     * Replacement for the generic STEP 4b worked example when helpers are headed
+     * to the shared file. Empty string → no example beyond the kind's own section.
+     */
+    nearDupExample: (testFile: string) => string;
+}
+export declare const API_HELPERS: HelperPolicy;
+export declare const BROWSER_HELPERS: HelperPolicy;
+/** Which helper policy a test type's helpers follow. */
+export declare function selectHelperPolicy(testType?: string): HelperPolicy;

package/build/prompts/shared-helper-policy.js

@@ -0,0 +1,135 @@
+/**
+ * Shared-helper policy — the ONE place that says what a helper destined for the
+ * shared SkyrampUtils file may be named and may assert. Both the modularization
+ * prompts (which create the helpers) and the code-reuse prompt (which moves and
+ * merges them) read these fragments, so the rule cannot drift between the two
+ * ends of the modularize → reuse chain.
+ *
+ * Two kinds of helper exist, keyed by what the test type drives:
+ * - API helpers (integration) wrap one SDK request: equivalence is method+path,
+ *   scenario values travel via `data_override`, the only assertion is the
+ *   status code.
+ * - Browser helpers (ui) wrap a Playwright action sequence: equivalence is the
+ *   primitive sequence with identical selectors, scenario values are fill
+ *   values / literal arguments, the helper holds actions + structural waits.
+ */
+import { isBrowserTestType } from "../utils/reuseRouting.js";
+/** Why the assertion rule exists — quoted wherever the rule is stated. */
+export const SHARED_HELPER_WHY = "A scenario-specific assertion inside a helper carries one scenario's data into a shared function and fails the next scenario that calls it — the helper is shared, the claims are not.";
+export const BROWSER_STRUCTURAL_WAITS = '`waitForResponse`, `waitForLoadState`, `waitFor({ state: "visible" })`, and `toBeVisible` on a STRUCTURAL locator (a test id, or a role + name of a control) — a check that an element rendered, not what it says';
+/**
+ * Relocation never reorders execution. Two variants, because the two ends of the
+ * chain may do different things with a helper whose value assertion sits BETWEEN
+ * two actions: modularization (which authors helpers) splits it; reuse (which
+ * only moves existing helpers) leaves it local.
+ */
+export const ASSERTION_BOUNDARY_RULE_EXTRACT = "Relocation must preserve the original order: an assertion that sits BETWEEN two actions is a HELPER BOUNDARY — end the helper before it and start the next helper after it (each named per the naming rule), so the assertion sits between the two calls in the test body exactly where it was. Never move an assertion across an action.";
+export const ASSERTION_BOUNDARY_RULE_MOVE = "Relocation must preserve the original order: only a TRAILING assertion (after the helper's last action) may move to the test body right after the call. A helper whose excluded assertion sits BETWEEN two actions is NOT moved and NOT split — leave it local in the test file; splitting is modularization's job, not this step's.";
+export const BROWSER_VALUE_ASSERTIONS = 'any `expect` whose matcher OR locator carries scenario data: `toHaveText`, `toContainText`, `toHaveValue`, `toHaveCount`, `toHaveURL` with a literal, or ANY matcher — `toBeVisible` included — on a locator that embeds scenario text such as `getByText("Total: $899.98")`';
+const BROWSER_LIFTABLE = "fill values, option labels, or literal arguments";
+const API_LIFTABLE = "body literals, `data_override` values, or expected status";
+const API_ASSERTION_MERGE_LINE = `a merged helper asserts ONLY the status code. If either version carries response-body assertions, relocate them to that version's test body (applied to the returned response) before merging. ${SHARED_HELPER_WHY}`;
+// (API helpers are one request + trailing assertions, so the move variant's
+// between-actions case does not arise; API_HELPERS.moveRule is empty.)
+function oneHelperLine(fileName, unit) {
+    return `One ${unit} = one helper in \`${fileName}\`.`;
+}
+/**
+ * A helper kept local must never share a name with a utils export — the import
+ * and the local definition would then describe two different behaviours under
+ * one name, and a later reader (or a deterministic gate) cannot tell which runs.
+ */
+export const NO_SHADOWING_RULE = "If a helper stays local for any reason, it must NOT share a name with any export of the utils file — rename the local one to state what differs (e.g. `submitEditOrderFormNoWait`). A test file never defines a helper with the same name as a utils export.";
+export const API_HELPERS = {
+    kind: "api",
+    sameStep: "the SAME method+path",
+    liftableLiterals: API_LIFTABLE,
+    structuralNoise: "",
+    namingRule: "**NAME** each helper by method + resource ONLY: `create_product`, `update_order`, `get_order`, `get_orders_list`. Scenario adjectives in names are FORBIDDEN (`create_discount_test_product`, `update_order_50_discount`) — other tests define the same step, and a shared utils file can hold only one canonical name per step. Scenario data belongs in ARGUMENTS, never in the name.",
+    assertionRule: `**THE ONLY ASSERTION INSIDE A SHARED HELPER IS THE STATUS CODE**, written in the test's own assertion syntax (Python \`assert response.status_code == expected_status\`; TypeScript/JavaScript \`expect(response.status).toBe(expectedStatus)\`), with the expected status a parameter defaulted to this scenario's expected code. EVERY response-body assertion (echo-backs, computed totals, field checks) stays in the test body, applied to the response the helper returns. ${SHARED_HELPER_WHY}`,
+    relocationTarget: "the test body, applied to the response the helper returns",
+    moveRule: "",
+    namingExample: "E.g. `update_order`, not `update_order_discount` or `update_order_50_discount`.",
+    oneHelperRule: (fileName) => `One method+path = one helper in \`${fileName}\`.`,
+    // The API section below carries its own worked example; the generic
+    // Playwright one would teach intent-naming and locator merges to a Python prompt.
+    nearDupExample: () => "",
+    // API request helpers are one SDK call + assertions, so near-duplicate
+    // equivalence is judged by method+path, not Playwright primitives — and the
+    // SDK's data_override makes literal-lifting mechanical, which is why this
+    // merge may lift body literals that the Playwright rules refuse.
+    nearDupRules: (fileName) => `
+### API request helpers: near-duplicate definition and merge (this flow's tests)
+
+For helpers that wrap one SDK request call (e.g. \`client.send_request(...)\`), judge near-duplication by the REQUEST, not by the criteria above. Two such helpers are near-duplicates when **ALL** of the following are true:
+
+1. **Same method and same path** (path parameters count as the same path).
+2. **Same call structure** — same request-call shape; no extra steps in one but not the other.
+3. **Differences are limited to**: literals inside the request-body string, values in \`data_override\`, the expected status code, or which values are lifted to parameters.
+
+Merge procedure for an API near-duplicate pair — these rules OVERRIDE the generic procedure below on two points: body literals ARE liftable differences (via \`data_override\`), and defaults are REQUIRED (the generic "no defaults" rule applies to Playwright helpers only):
+- **Name**: method + resource only (\`create_product\`, \`update_order\`) — never a scenario adjective.
+- **Lift each differing body literal into a parameter applied via \`data_override\`, with the parameter's DEFAULT set to the literal the incumbent version used.** Defaults make the merge additive: every existing call site keeps its behavior without edits; only the other test passes its values explicitly.
+- **Union the parameter lists**; a parameter one version lacked gets the default from that version's literal. A differing expected status lifts the same way: \`expected_status\` parameter, default from the incumbent.
+- **Assertions**: ${API_ASSERTION_MERGE_LINE}
+- Structural differences (different items-array shape, extra request) → NOT near-duplicates; leave them alone.
+
+Worked example: \`update_order_discount(client, headers, order_id, product_id)\` with \`"discount_percent": 25\` in the body, and \`update_order_50_discount(client, headers, order_id, product_id, quantity)\` with \`"discount_percent": 50\` → ONE helper \`update_order(client, headers, order_id, product_id, discount_percent=25, quantity=2)\` that applies \`discount_percent\` and \`quantity\` via \`data_override\`. ${oneHelperLine(fileName, "method+path")}
+`,
+};
+export const BROWSER_HELPERS = {
+    kind: "browser",
+    sameStep: "the SAME action sequence (same Playwright primitives in the same order, selectors identical)",
+    liftableLiterals: BROWSER_LIFTABLE,
+    structuralNoise: "`waitForTimeout(...)` lines and the `getValue(playwrightRequestN, ...)` value wrapper around a fill are RECORDER NOISE, not structure — two bodies that differ only by them perform the same step; keep the utils version (it carries the waits) and import it",
+    namingRule: "**NAME** each helper by the user INTENT it performs, shared across tests: `openEditOrderForm`, `applyDiscount`, `submitProductForm`, `removeOrderItem`. Scenario values or adjectives in names are FORBIDDEN (`applyFiftyPercentDiscount`, `editOrder1Discount`, `createExpensiveProduct`) — another test performs the same action with different data, and a shared utils file holds ONE canonical name per action. Scenario data belongs in ARGUMENTS, never in the name.",
+    assertionRule: `**A SHARED HELPER CONTAINS ACTIONS AND STRUCTURAL WAITS ONLY**: clicks, fills, selects, ${BROWSER_STRUCTURAL_WAITS}. EVERY VALUE ASSERTION (${BROWSER_VALUE_ASSERTIONS}) stays in the test body, placed immediately after the helper call it verifies, with its selector verbatim and its expected value unchanged. ${SHARED_HELPER_WHY}`,
+    relocationTarget: "the test body, immediately after the helper call, selector verbatim",
+    moveRule: ASSERTION_BOUNDARY_RULE_MOVE,
+    namingExample: "E.g. `applyDiscount`, not `applyTwentyPercentDiscount`.",
+    oneHelperRule: (fileName) => `One action sequence = one helper in \`${fileName}\`.`,
+    nearDupExample: (testFile) => `### Worked example (shared-file browser helpers)
+
+\`edit_order_apply_discount.spec.ts\` has:
+\`\`\`ts
+export async function applyDiscount(page) {
+    await page.getByTestId("edit-order-input-discount").fill("10");
+    await page.getByTestId("edit-order-submit-btn").click();
+}
+\`\`\`
+
+\`${testFile}\` (current) has:
+\`\`\`ts
+export async function applyTwentyPercentDiscount(page) {
+    await page.getByTestId("edit-order-input-discount").fill("20");
+    await page.getByTestId("edit-order-submit-btn").click();
+}
+\`\`\`
+
+These ARE near-duplicates: same primitive sequence, selectors byte-identical, the only difference is the fill literal. Correct merge (name = intent, the literal becomes a parameter passed exactly as it was written — no conversion or other logic added, selectors untouched):
+
+\`\`\`ts
+export async function applyDiscount(page, discountPercent) {
+    await page.getByTestId("edit-order-input-discount").fill(discountPercent);
+    await page.getByTestId("edit-order-submit-btn").click();
+}
+\`\`\`
+
+Both test files import and call \`applyDiscount(page, "10")\` / \`applyDiscount(page, "20")\`. A pair whose selectors differ (\`getByTestId("edit-order-submit-btn")\` vs \`getByRole("button", { name: "Save" })\`, or one side carrying \`.first()\`) is NOT a near-duplicate — leave both in place.`,
+    // Browser helpers already have the Playwright near-duplicate criteria in the
+    // generic STEP 4b text; what they lack for a shared file is the
+    // defaulted-parameter merge (so an incumbent utils helper can absorb a new
+    // scenario without touching its existing call sites) and the assertion rule.
+    nearDupRules: (fileName) => `
+### Browser action helpers: merging into an existing \`${fileName}\` helper (this flow's tests)
+
+For this flow the rules below OVERRIDE two points of the generic text above and below: (a) selectors are NOT liftable differences — two helpers whose selectors differ are NOT near-duplicates (criterion 2 applies to ${BROWSER_LIFTABLE} only); (b) the procedure's "no defaults" rule applies to cross-test pairs (both call sites pass values explicitly) but NOT to merges into a helper that already lives in \`${fileName}\` (STEP 3 / STEP 5b), which MUST use defaults so existing call sites stay untouched. Merge additively:
+- **Name**: the INTENT the action sequence performs (\`openEditOrderForm\`, \`applyDiscount\`, \`submitProductForm\`) — never a scenario adjective or value (\`applyFiftyPercentDiscount\`, \`editOrder1Discount\`). ${oneHelperLine(fileName, "intent")}
+- **Lift each differing literal into a parameter with its DEFAULT set to the literal the incumbent version used** (${BROWSER_LIFTABLE}). Defaults make the merge additive: every existing call site keeps its behavior without edits; only the new test passes its values explicitly. Selectors stay verbatim in the body.
+- **Assertions**: before merging, apply the assertion rule to both versions — relocate a trailing value assertion to that version's test body immediately after the helper call. ${ASSERTION_BOUNDARY_RULE_MOVE} ${SHARED_HELPER_WHY}
+`,
+};
+/** Which helper policy a test type's helpers follow. */
+export function selectHelperPolicy(testType) {
+    return isBrowserTestType(testType) ? BROWSER_HELPERS : API_HELPERS;
+}