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

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;
+}

package/build/prompts/test-recommendation/diffExecutionPlan.js

@@ -1,12 +1,12 @@
-import { roundRobinByType } from "../../recommendation/diversity.js";
+import { CandidateSource, computeCandidateId } from "../../types/Recommendation.js";
+import { fixedNBudgeter } from "../../recommendation/budgeters/fixedNBudgeter.js";
 import { AUTH_MIDDLEWARE_PATTERNS_STR } from "../../utils/workspaceAuth.js";
 import { resolveServiceDetailsRef } from "../../utils/utils.js";
-import { logger } from "../../utils/logger.js";
 import { TEST_CATEGORIES, } from "../../types/TestRecommendation.js";
 import { buildScopeAssessmentSection } from "./scopeAssessment.js";
 import { PromptPlan } from "./promptPlan.js";
 import { buildTestPatternGuidelines, buildTestQualityCriteria, buildGenerationRules, MAX_CRITICAL_TESTS, } from "./recommendationSections.js";
-import { TASK_ANALYZE_MAINTAIN, TESTBOT_TASK1_STEP_CODE_REVIEW, externalDedupKey, isAttackSurfaceSecurityBoundary, isOrdinaryDirectAuthBoundary, scenarioCoverageKey, taskStepRef, } from "./recommendationShared.js";
+import { TASK_ANALYZE_MAINTAIN, TESTBOT_TASK1_STEP_CODE_REVIEW, taskStepRef, } from "./recommendationShared.js";
 // ── Step body functions ───────────────────────────────────────────────────────
 function _execCodeReviewBody(_ctx) {
     const codeReviewRef = taskStepRef(TASK_ANALYZE_MAINTAIN, TESTBOT_TASK1_STEP_CODE_REVIEW);
@@ -69,7 +69,7 @@ INSERT a non-bug source-code-derived candidate into the ranked list **only if AL
 3. It is not already covered by a structural candidate in the list below
 
 If these conditions are not met, add it to ADDITIONAL only — do NOT displace a pre-ranked GENERATE item.
-**CRITICAL-tier items (category: new_endpoint) and attack-surface \`security_boundary\` items should never be displaced by non-bug candidates** — they test the actual endpoints introduced in this PR or sibling destructive endpoints that could bypass the changed auth boundary. However, bug-catching tests CAN displace them only after all lower-value non-bug slots are exhausted.
+**Attack-surface \`security_boundary\` items should never be displaced by non-bug candidates** — they test sibling destructive endpoints that could bypass the changed auth boundary. However, bug-catching tests CAN displace them only after all lower-value non-bug slots are exhausted.
 
 When a qualifying candidate is inserted: place it HIGH before MEDIUM before LOW; within the same priority, source-code-derived candidates go BEFORE structural ones. Re-number ranks after insertion. The top ${ctx.maxGen} ranked items become GENERATE candidates.
 
@@ -80,8 +80,8 @@ When a qualifying candidate is inserted: place it HIGH before MEDIUM before LOW;
 function _execDiversityBody(_ctx) {
     return `**Bug-coverage gate (runs BEFORE dedup):**
 Verify that the highest-severity \`<bug_found>\` flaw from Step ${EXEC_STEP_CODE_REVIEW} has exactly one GENERATE item with category \`bug_caught\` targeting it — meaning the test would FAIL on the current buggy code and PASS once the flaw is fixed. At most one promotion per run (per Step ${EXEC_STEP_CODE_REVIEW} cap). If the promoted flaw has no targeting \`bug_caught\` GENERATE item:
-- Check ADDITIONAL for a matching test → promote it into the lowest-priority non-bug, non-CRITICAL GENERATE slot first (lowest category rank per \`crud > error_handling > workflow > data_validation > data_integrity > business_rule\`; preserve attack-surface \`security_boundary\` and internal \`new_endpoint\` items unless no lower-priority slot exists).
-- If no ADDITIONAL candidate matches, create a new \`bug_caught\` test and insert it, displacing the lowest-priority non-bug, non-CRITICAL GENERATE item first; displace an attack-surface \`security_boundary\` or other CRITICAL item only when every GENERATE slot is higher priority.
+- Check ADDITIONAL for a matching test → promote it into the lowest-priority non-bug, non-CRITICAL GENERATE slot first (lowest category rank per \`crud > error_handling > workflow > data_validation > data_integrity > business_rule\`; preserve attack-surface \`security_boundary\` items unless no lower-priority slot exists).
+- If no ADDITIONAL candidate matches, create a new \`bug_caught\` test and insert it, displacing the lowest-priority non-bug, non-CRITICAL GENERATE item first; displace an attack-surface \`security_boundary\` item only when every GENERATE slot is higher priority.
 A \`bug_caught\` test is NEVER considered a "duplicate" of a non-bug test during the dedup below.
 
 Each GENERATE item must exercise a **distinct code path** — not just different input values on the same path.
@@ -98,7 +98,7 @@ Same step sequence with only payload differences (e.g. 10% vs 5% discount both r
 function _execRegisterBody(_ctx) {
     return `Register your complete candidate list — every test you would generate OR recommend — via \`skyramp_register_test_plan\` (\`stateFile\` required). Include a discriminator claim (\`discriminator\` field — valid kinds and anchor rules are in the tool schema) for candidates probing the changed logic identified in Step ${EXEC_STEP_CODE_REVIEW}/Step ${EXEC_STEP_ENRICH}.
 
-The returned GENERATE list is mandatory and final — generation tools reject unregistered scenarios. If the tool demotes a discriminator claim (returned in \`demotions\` with a reason), either strengthen the claim — a step that actually exercises the declared \`kind\`, or a verbatim anchor that occurs in the diff — or drop it; the candidate itself stays in the plan either way.`;
+The returned GENERATE list is mandatory and final — generation tools reject unregistered scenarios. If the tool demotes a discriminator claim (returned in \`demotions\` with a reason), either strengthen the claim — a step that actually exercises the declared \`kind\`, or a verbatim anchor that occurs in the diff — or drop it. A demoted candidate normally stays in the plan. If it also left the plan for another recorded reason, the report lists it under "Demoted AND removed".`;
 }
 function _execExecuteBody(ctx) {
     return `Replace any scenario that pairs unrelated resources with one reflecting actual foreign-key relationships in the codebase.
@@ -149,20 +149,6 @@ export const EXEC_STEP_EXECUTE = _execPlan.labels.EXECUTE; // "4"
 /** "5" — Register test plan (SKYR-3879 Path B checkpoint) */
 export const EXEC_STEP_REGISTER = _execPlan.labels.REGISTER; // "5"
 const SERVICE_REFS = resolveServiceDetailsRef();
-function prioritizeAttackSurfaceBundles(items) {
-    const reordered = [];
-    for (const item of items) {
-        if (isAttackSurfaceSecurityBoundary(item.scenario)) {
-            const firstDirectAuthIndex = reordered.findIndex(candidate => isOrdinaryDirectAuthBoundary(candidate.scenario));
-            if (firstDirectAuthIndex >= 0) {
-                reordered.splice(firstDirectAuthIndex, 0, item);
-                continue;
-            }
-        }
-        reordered.push(item);
-    }
-    return reordered;
-}
 export function buildExecutionPlan(scored, maxGen, topN, baseUrl, authHeaderValue, authSchemeSnippet, authTypeValue, seed, endpointCount, isUIOnlyPR, hasFrontendChanges = false, hasTraces = false, externalCoverage = new Set(), relevantExternalTestPaths = [], 
 /**
  * Whether the diff classified at least one new/modified/removed endpoint.
@@ -184,40 +170,58 @@ hasApiChanges = true) {
         : hasFrontendChanges
             ? Math.max(0, maxGen - 1)
             : maxGen;
-    // Filter out scenarios whose primary method + resource + test type is already covered by external tests.
-    // Method-aware: an external test covering GET /orders won't block PUT /orders scenarios.
-    // This is the programmatic complement to the prompt-level Step ${EXEC_STEP_COVERAGE} dedup instructions.
-    const scoredAfterExternalDedup = externalCoverage.size > 0
-        ? scored.filter((item) => {
-            const key = externalDedupKey(item.scenario);
-            if (externalCoverage.has(key)) {
-                if (item.scenario.category === "bug_caught" || isAttackSurfaceSecurityBoundary(item.scenario)) {
-                    logger.info(`External dedup: preserving "${item.scenario.scenarioName}" (${key}) — protected bug/attack-surface scenario requires semantic flaw coverage`);
-                    return true;
-                }
-                logger.info(`External dedup: skipping "${item.scenario.scenarioName}" (${key}) — covered by external test`);
-                return false;
-            }
-            return true;
-        })
-        : scored;
-    const slotOrderedItems = prioritizeAttackSurfaceBundles(scoredAfterExternalDedup);
-    // Distribute the backend GENERATE slots evenly across the test types present
-    // (contract vs integration) with spillover, instead of a pure top-N rank slice —
-    // so a backend change isn't starved of (say) integration coverage just because
-    // contract scenarios out-ranked it. See roundRobinByType.
-    const generateItems = roundRobinByType(slotOrderedItems, Math.min(backendGenerateCount, slotOrderedItems.length));
-    // ADDITIONAL = everything not chosen for GENERATE, in original rank order, capped
-    // at the remaining budget. Computed by set-difference (not a positional slice)
-    // because round-robin may pick items that aren't the first backendGenerateCount by
-    // rank — a positional slice would double-list a generated item or drop one.
-    const generateSet = new Set(generateItems);
-    const rawAdditionalItems = slotOrderedItems
-        .filter((it) => !generateSet.has(it))
-        .slice(0, Math.max(0, topN - backendGenerateCount));
-    // Filter additional items whose primary resource + test type already appear in GENERATE
-    const generatedCoverage = new Set(generateItems.map((item) => scenarioCoverageKey(item.scenario)));
-    const additionalItems = rawAdditionalItems.filter((item) => !generatedCoverage.has(scenarioCoverageKey(item.scenario)));
+    // Both this renderer and the register-plan path run the SAME selection
+    // pipeline — `runBudget` — instead of two copies of it (SKYR-4214 item 7).
+    // This file used to hold its own external dedup, attack-surface ordering,
+    // round-robin GENERATE pick and ADDITIONAL set-difference, so a fix in one
+    // copy left the other wrong.
+    //
+    // The two are NOT guaranteed to produce the same GENERATE set, and this
+    // comment must not claim they are: `selectPlan` re-ranks and calls
+    // `diversityBalancedBudgeter` (planRanker.ts:96) where this calls
+    // `fixedNBudgeter`, and the two differ in the `pick` step —
+    // diversityBalancedBudgeter.test.ts covers that divergence. What is now
+    // shared is the dedup rule, the ordering and the ADDITIONAL cap.
+    //
+    // `runBudget` needs a Candidate, which carries provenance and a stable id
+    // that only the register-plan path fills. Everything reaching this renderer
+    // is server-drafted, and `computeCandidateId` is a pure function of the
+    // scenario, so both fields are derivable here.
+    //
+    // The context deliberately reports no frontend work, whatever this PR
+    // contains: this renderer never had the UI-promotion loop, and the backend
+    // count it computed above already applied the UI reservation. Passing the
+    // real flags would introduce UI slots into the prompt's GENERATE list, which
+    // is a behaviour change this item does not carry.
+    const candidates = scored.map((item) => ({
+        ...item,
+        source: CandidateSource.SERVER,
+        candidateId: computeCandidateId(item.scenario),
+    }));
+    const selection = fixedNBudgeter.select(candidates, {
+        maxGenerate: backendGenerateCount,
+        maxTotal: topN,
+        isUIOnlyPR: false,
+        hasFrontendChanges: false,
+        externalCoverage,
+        // This renderer never receives the branch diff, so it cannot tell whether the
+        // PR wrote tests of its own. `true` is the same abstain direction the analyze
+        // end takes for an unknown (SKYR-4024): the covered-candidate reserve stays
+        // shut here, and those candidates are reported in the Removed section below
+        // rather than promoted to ADDITIONAL.
+        diffChangesTestFiles: true,
+    });
+    const generateItems = selection.generate;
+    const additionalItems = selection.additional;
+    // A candidate the selection stage removed — covered by an external test, or
+    // past the maxTotal cap — leaves no trace in the two lists above. In the
+    // recommendation-only flow (analyze_changes plus this prompt, with no
+    // register call) this section is the ONLY place the agent can read that a
+    // candidate existed and why it went, which is what SKYR-4214 exists to fix.
+    const scenarioNameById = new Map(candidates.map((c) => [c.candidateId, c.scenario.scenarioName]));
+    const removedLines = selection.dropped
+        .map((drop) => `- ${scenarioNameById.get(drop.candidateId) ?? drop.candidateId}: ${drop.reason}`)
+        .join("\n");
     const hasWorkspaceAuthType = !!authTypeValue && authTypeValue !== "none";
     // For skyramp_integration_test_generation with scenarioFile:
     // - If workspace has authType set: omit auth entirely — workspace handles Bearer prefix.
@@ -432,7 +436,9 @@ ${isUIOnlyPR
 ### ADDITIONAL (list in additionalRecommendations in this order after Step ${EXEC_STEP_ENRICH} insertion)
 
 ${additionalLines || "  (none pre-ranked)"}
-${uiGroundingGuidance}
+${removedLines
+        ? `\n### Removed (${selection.dropped.length}) — candidates the selection stage dropped before ranking. They are NOT in the lists above; do not re-add them.\n\n${removedLines}\n`
+        : ""}${uiGroundingGuidance}
 ${uiGuidance}
 ${supplementNote}