@skyramp/mcp 0.4.1 → 0.4.2-rc.2

package/build/playwright/traceExportStore.d.ts

@@ -0,0 +1,22 @@
+/** A run recording more traces than this has a problem no counter fixes; the cap is
+ *  here so a runaway loop cannot grow the number without bound. */
+export declare const MAX_COUNTED_EXPORTS = 100;
+/** How many times the report may be refused for an unrecorded planned UI test.
+ *  The refusal is meant to cost the agent a recording, not the whole run: a
+ *  resubmission that records nothing still advances nothing, and without this cap
+ *  an agent that will not record and a job timeout are the same outcome. */
+export declare const MAX_UI_DELIVERY_REFUSALS = 3;
+/** Record one `skyramp_export_zip` call, or do nothing. NOTHING HERE MAY COST THE
+ *  EXPORT: the payload the agent receives is untouched and every failure is
+ *  swallowed with a log line. */
+export declare function recordTraceExport(): void;
+/** Recording attempts this run. */
+export declare function traceExportAttempts(): number;
+/** Count one refusal and return the new total. */
+export declare function countUiDeliveryRefusal(): number;
+/** Refusals so far, without counting one. */
+export declare function uiDeliveryRefusals(): number;
+/** Test seam. The store is module state keyed by the run; a suite that writes a
+ *  fresh state file per test reseats it anyway, but an explicit reset keeps a test
+ *  that reuses one honest. */
+export declare function resetTraceExportStoreForTests(): void;

package/build/playwright/traceExportStore.js

@@ -0,0 +1,81 @@
+import { currentRunStateFile } from "../utils/AnalysisStateManager.js";
+import { logger } from "../utils/logger.js";
+/** How many times this run called `skyramp_export_zip`, and how many times the
+ *  report was refused for a planned UI test nobody recorded. IN PROCESS, not in the
+ *  state file, for the same reason as the blueprint digests: the only reader shares
+ *  a process with the browser tools, and a read-modify-write per export buys
+ *  nothing. KEYED BY THE RUN, one slot — a new key means the previous run is over.
+ *
+ *  ATTEMPTS, never successes. An export that errored still cost the agent a
+ *  recording, and the gate reading this has to be satisfiable by TRYING: counting
+ *  only successes lets one screen that cannot be recorded refuse the report for the
+ *  rest of the run. */
+let countedRunStateFile;
+let exportAttempts = 0;
+let deliveryRefusals = 0;
+/** A run recording more traces than this has a problem no counter fixes; the cap is
+ *  here so a runaway loop cannot grow the number without bound. */
+export const MAX_COUNTED_EXPORTS = 100;
+/** How many times the report may be refused for an unrecorded planned UI test.
+ *  The refusal is meant to cost the agent a recording, not the whole run: a
+ *  resubmission that records nothing still advances nothing, and without this cap
+ *  an agent that will not record and a job timeout are the same outcome. */
+export const MAX_UI_DELIVERY_REFUSALS = 3;
+/** The slot this run writes to. NOT gated on a resolvable state file: a run whose
+ *  path cannot be resolved still records and still reports, and a counter that
+ *  stayed at zero there made the gate below refuse a report it could never let
+ *  through. `NO_RUN` is one slot like any other — a new key still clears it. */
+const NO_RUN = "<no-run>";
+function reseatRun() {
+    let runStateFile;
+    try {
+        runStateFile = currentRunStateFile() ?? NO_RUN;
+    }
+    catch {
+        runStateFile = NO_RUN;
+    }
+    if (runStateFile !== countedRunStateFile) {
+        countedRunStateFile = runStateFile;
+        exportAttempts = 0;
+        deliveryRefusals = 0;
+    }
+}
+/** Record one `skyramp_export_zip` call, or do nothing. NOTHING HERE MAY COST THE
+ *  EXPORT: the payload the agent receives is untouched and every failure is
+ *  swallowed with a log line. */
+export function recordTraceExport() {
+    try {
+        reseatRun();
+        if (exportAttempts >= MAX_COUNTED_EXPORTS)
+            return;
+        exportAttempts += 1;
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        logger.warning(`recordTraceExport failed: ${detail}`);
+    }
+}
+/** Recording attempts this run. */
+export function traceExportAttempts() {
+    reseatRun();
+    return exportAttempts;
+}
+/** Count one refusal and return the new total. */
+export function countUiDeliveryRefusal() {
+    reseatRun();
+    deliveryRefusals += 1;
+    return deliveryRefusals;
+}
+/** Refusals so far, without counting one. */
+export function uiDeliveryRefusals() {
+    reseatRun();
+    return deliveryRefusals;
+}
+/** Test seam. The store is module state keyed by the run; a suite that writes a
+ *  fresh state file per test reseats it anyway, but an explicit reset keeps a test
+ *  that reuses one honest. */
+export function resetTraceExportStoreForTests() {
+    countedRunStateFile = undefined;
+    exportAttempts = 0;
+    deliveryRefusals = 0;
+}

package/build/playwright/traceRecordingPrompt.js

@@ -43,7 +43,8 @@ Then execute in strict order:
 
 - **After every action that changes the page**, call \`browser_snapshot\` before the next interaction — refs become stale after navigation, clicks that trigger page updates, and form submissions.
 - **Iframe content** appears inline in the snapshot — interact with those elements using their refs normally.
-- **Trace deduplication**: if you retry from the start URL, only the last complete attempt is exported.
+- **One recorder, and the export drains it**: every \`browser_*\` call accumulates into ONE buffer, exploration included — whatever you did before the flow is in the trace with it. A successful \`skyramp_export_zip\` writes that buffer, EMPTIES it and closes the browser, so the next recording starts clean. A trace that came out polluted is therefore a reason to record again, not a reason to stop, and the retry costs you one navigation and the flow. Record each test in its own pass: \`browser_navigate\` to the start URL, the flow, export.
+- **Trace deduplication is narrower than it sounds**: a repeated \`browser_navigate\` drops the attempt before it only when it repeats the MOST RECENT \`browser_navigate\`. Clicks and types in between are fine; another navigation is not — a detour through a sign-out page, say, and BOTH attempts are exported. Never rely on it to clean up an exploratory session: export that session to a throwaway path and discard the zip, which leaves the recorder empty for the real one.
 - **No Docker required**: the \`browser_*\` tools run a local browser session managed by the MCP server. Docker is ONLY used by \`skyramp_start_trace_collection\` (manual recording mode). Never suggest or check for Docker when using AI-driven recording.
 ${modularizeNote}
 
@@ -55,11 +56,18 @@ These concepts drive the DOM Analyzer capture tools and constrain how their outp
 - **\`browser_blueprint\` — stable logical names**: logical names like \`add_order_btn\` and their derived \`getByRole\` locators survive page reloads and playback. Use them in generated test code. Call \`browser_blueprint\` before and after each meaningful action to capture state changes.
 
 ### Assertions
-Call \`browser_assert\` when assertions are needed. Always provide the \`expected\` value.
+Call \`browser_assert\` when assertions are needed. Provide \`expected\` for every type that takes one (all except \`visible\`).
 - \`type: "text"\` — verify an element contains expected text
 - \`type: "value"\` — verify an input field has an expected value
+- \`type: "css"\` — verify a computed style (\`property\` = the CSS property, e.g. \`background-color\`; \`expected\` = the value the app computes)
+- \`type: "class"\` — verify the element carries a class (\`expected\` = one class name)
+- \`type: "attribute"\` — verify an attribute value (\`property\` = the attribute name; \`expected\` = its value)
 
-**Visual / screenshot assertions.** When the instruction asks to take a screenshot, capture a baseline, or verify how a page/element/region *looks* (as opposed to its text or value), call \`browser_visual_snapshot\` — it records a \`toHaveScreenshot()\` assertion so the generated test pixel-compares against a baseline image on every run. Do NOT use \`browser_take_screenshot\` for this: it only captures a throwaway image, is dropped at export (it produces no assertion), and will NOT appear in the generated test. Use \`browser_take_screenshot\` only to view the page yourself while recording — never to record a visual check. \`filename\` is optional: if the instruction names a baseline file (e.g. \`page-001.png\`) pass it as \`filename\`, otherwise omit it and \`browser_visual_snapshot\` auto-generates one per \`snapshotType\` (\`page-NNN.png\` for a page, \`el-NNN.png\` for an element, \`region-NNN.png\` for a region).
+**Visual / screenshot assertions.** When the instruction asks to take a screenshot, capture a baseline, or verify how a page/element/region *looks* (as opposed to its text or value), call \`browser_visual_snapshot\` — it records a \`toHaveScreenshot()\` assertion so the generated test pixel-compares against a baseline image on every run.
+
+**When the change under test is how something looks** — a colour, class or attribute the diff changes — assert it directly with \`browser_assert\` \`type: css/class/attribute\` on the element that OWNS the property (the flex container for \`flex-direction\`, not its children); if it has no stable ref, note a recording gap rather than assert the wrong element. Order has no kind: \`flex-direction\` when the diff flipped it, else a \`boundingBox()\` comparison at enhance. \`browser_visual_snapshot\` only for a look no property expresses (image, gradient, chart).
+
+Do NOT use \`browser_take_screenshot\` to record a visual check: it only captures a throwaway image, is dropped at export (it produces no assertion), and will NOT appear in the generated test. Use it only to view the page yourself while recording. \`filename\` is optional on \`browser_visual_snapshot\`: if the instruction names a baseline file (e.g. \`page-001.png\`) pass it as \`filename\`, otherwise omit it and one is auto-generated per \`snapshotType\` (\`page-NNN.png\` for a page, \`el-NNN.png\` for an element, \`region-NNN.png\` for a region).
 
 ### Tips
 - **Custom dropdowns (Radix, MUI, etc.)**: click the combobox trigger → \`browser_snapshot\` → click the option. Do NOT use \`browser_select_option\` — it only works on native \`<select>\` elements.

package/build/prompts/code-reuse.js

@@ -1,25 +1,22 @@
 import { generateSkyrampHeader, SKYRAMP_UTILS_HEADER } from "../utils/utils.js";
 import { isUtilsReuseEnabled } from "../utils/featureFlags.js";
-import { isModularizeFirstTarget, isPomAwareTarget, } from "../utils/reuseRouting.js";
+import { inlineCallSiteFamily, isModularizeFirstTarget, isPomAwareTarget, } from "../utils/reuseRouting.js";
 import { getPomAwareCodeReusePrompt } from "./pom-aware-code-reuse.js";
-import { NO_SHADOWING_RULE, selectHelperPolicy, } from "./shared-helper-policy.js";
+import { NO_SHADOWING_RULE, SELECTOR_OWNING_MODULE_RULE, selectHelperPolicy, } from "./shared-helper-policy.js";
+import { UTILS_LANGUAGE_SPECS } from "../utils/utils-verify/language-spec.js";
+/** The prescribed module name comes from the verifier's language table, which is the
+ *  ONE declaration of it: the instruction the agent reads and the name the verify pass
+ *  demands cannot drift apart. Java is stated here because utils reuse is disabled for
+ *  it, so the verifier has no entry to read. */
 const LANGUAGE_MAP = {
-    python: {
-        extension: "py",
-        fileName: "SkyrampUtils.py",
-    },
+    ...Object.fromEntries(Object.entries(UTILS_LANGUAGE_SPECS).map(([language, spec]) => [
+        language,
+        { extension: spec.extensions[0].slice(1), fileName: spec.fileName },
+    ])),
     java: {
         extension: "java",
         fileName: "SkyrampUtils.java",
     },
-    javascript: {
-        extension: "js",
-        fileName: "skyrampUtils.js",
-    },
-    typescript: {
-        extension: "ts",
-        fileName: "skyrampUtils.ts",
-    },
 };
 function genericNearDupExample(testFile) {
     return `### Worked example
@@ -52,18 +49,16 @@ export async function uploadFileToRFI(page, fileName, tabName) {
 }
 \`\`\`
 
-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:
+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. The \`waitForTimeout\` lines are recorder noise too: a fixed sleep is not a structural wait, and in a shared helper every importer pays it on every run. The \`waitForResponse\` correlation and the \`filechooser\` event already cover this step, so the merged helper waits on those; where a step has no such signal, wait on the element the next line touches. Correct merge:
 
 \`\`\`ts
 export async function uploadFileViaChooser(page: Page, fileName: string) {
-    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);
 }
 \`\`\`
 
@@ -101,6 +96,11 @@ export function getCodeReusePrompt(testFile, language, framework, scopedPoms, te
     // 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;
+    // The name is prescribed in LANGUAGE_MAP and, until the verify pass checked it,
+    // nothing held a run to it: testplan-run-9 delivered `skyrampUiUtils.ts` on one
+    // fixture and `skyrampUtils.ts` on another, for the same role on one repository.
+    // Stated once and rendered at both places that create the file.
+    const moduleNameRule = `**THE MODULE'S NAME IS NOT A CHOICE.** The shared module for ${lang} is \`${fileName}\`, and a module you create carries exactly that name — a later run against this repository then finds and extends it instead of writing a second module beside it under another name. A module that ALREADY EXISTS keeps the name it has: never rename it, whatever it is called, because tests you cannot see import it. Only where \`${fileName}\` is already large may a SECOND module carry another name.`;
     // 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);
@@ -115,13 +115,31 @@ export function getCodeReusePrompt(testFile, language, framework, scopedPoms, te
         ? `**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.**`;
+    // The repository's own browser helper modules. UI only, and only on the seeded
+    // (utils reuse on, page-object reuse off) flow: a browser test and the helpers it
+    // calls drive one library, so the verifier's action key compares a step to the
+    // customer's helper; the API side has no such key and is a separate change.
+    const inHouseBrowser = seedsUtils && policy.kind === "browser";
+    const inHouseDiscoveryStep = inHouseBrowser
+        ? inHouseDiscovery(testFile, fileName)
+        : "";
+    const inHouseMatchStep = inHouseBrowser
+        ? inHouseMatch(testFile, fileName, policy)
+        : "";
+    const inHouseSeedRule = inHouseBrowser
+        ? `
+**IF STEP 2b FOUND A QUALIFYING IN-HOUSE MODULE, SKIP THIS STEP.** STEP 3b already placed each of this test's helpers: replaced by a call to one of theirs, or added to their module in their style. A helper STEP 3b left local (their matching helper's key is undefined) stays local in ${testFile} — it is not moved into \`${fileName}\`, and \`${fileName}\` is not created beside their module. Where a \`${fileName}\` from an earlier run already sits beside their module, leave it as it is. This step runs only when STEP 2b found no qualifying module.
+`
+        : "";
     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.
-
+skyramp_modularization already ran on ${testFile} and extracted its steps into named helper functions. Those helpers belong in a shared module${inHouseBrowser ? " — the repository's own browser helper module when STEP 2b found one (STEP 3b), otherwise" : ", "} \`${fileName}\`${inHouseBrowser ? " —" : ","} so later tests import them instead of re-defining them.
+${inHouseSeedRule}
 ${pyImportRuleLine(fileName)}
 
+${moduleNameRule}
+
 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}
@@ -141,35 +159,38 @@ This step MOVES helpers that skyramp_modularization already created — it does
 **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
+    // SKYR-4219: an inline copy of a step 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.`
+    // `data_override`/`uniqueSuffix`) never meets the scenario-mode helper for the
+    // same request, a step still inline in the current test never meets the utils
+    // helper, and a browser spec that repeats a helper's action sequence keeps its copy
+    // — reuse degrades to a no-op in any mixed directory. The text is the policy's, in
+    // the kind's own terms; the gate is inlineCallSiteFamily, which the verify pass runs
+    // its sibling scan on, so the rule and the scan cannot drift apart.
+    const inlineCallSiteRule = inlineCallSiteFamily(testType, lang)
+        ? policy.inlineCallSiteRule
         : "";
+    const site = policy.inlineSite;
     // 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}\`
+    const siblingCallSitesStep = inlineCallSiteRule
+        ? `## STEP 5c: REPLACE ${site.nouns.toUpperCase()} IN OTHER SKYRAMP-GENERATED TESTS WITH ${site.target(fileName)}
 
-**Run this step EVEN IF STEP 3 already satisfied ${testFile} and STEPS 4–5b did nothing.** ${inlineRequestRule}
+**Run this step EVEN IF STEP 3 already satisfied ${testFile} and STEPS 4–5b did nothing.** ${inlineCallSiteRule}
 
 ${pyImportRuleLine(fileName)} (this applies to the import you add to the SIBLING file too — its directory is what decides the form.)
 
 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.
-
+2. In each, find every ${site.noun} ${site.match(fileName)}.
+3. For each match: import the helper into that file and replace the ${site.unit} with the call, passing the ${site.unit}'s literals (or expressions) as arguments; ${site.lift(fileName)}. Change NOTHING else in that file — ${site.keeps}.
+4. A ${site.unit} 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.
+${site.afterSteps}
 `
         : "";
     const finalReminderScope = seedsUtils
-        ? `**ONLY MOVE HELPERS THAT ALREADY EXIST IN TEST FILES — NEVER AUTHOR NEW ONES**`
+        ? `**ONLY MOVE HELPERS THAT ALREADY EXIST IN TEST FILES — NEVER AUTHOR NEW ONES**${inHouseBrowser ? " (adding one of THIS test's helpers to the repository's own module in STEP 3b is a move, not authoring; an inline step with no matching helper of theirs stays inline)" : ""}`
         : `**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)
@@ -181,7 +202,7 @@ ${pyImportRuleLine(fileName)} (this applies to the import you add to the SIBLING
 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.
+**PRECONDITION — check your own tool-call history, not the file**: this flow moves the helpers skyramp_modularization created into \`${fileName}\` (STEP 5b)${inHouseBrowser ? " — or into the repository's own browser helper module when it has one (STEP 3b)" : ""}. 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 
@@ -214,17 +235,16 @@ Use the Grep tool to search for files containing "${SKYRAMP_UTILS_HEADER}":
 - Output mode: "files_with_matches"
 **CRITICAL: Only look for util files with header ${SKYRAMP_UTILS_HEADER}** - exclude test files (files with "test", "spec", ".test.", ".spec." in the name).
 Read the matching non-test files and check if any helpers can be reused in ${testFile}.
-
+${inHouseDiscoveryStep}
 ## 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${inlineRequestRule ? " — or, for API request helpers, by EXTENDING them with defaulted parameters as the rules below allow" : ""}:
+If helpers exist in util file that can be reused in ${testFile} without modifying them${inlineCallSiteRule ? site.extendClause : ""}:
 - Import them into ${testFile}
 - Remove any duplicate code in ${testFile}
-${inlineRequestRule
-        ? `- ${inlineRequestRule} This applies to every request step still inline in ${testFile} that matches a utils helper.
+${inlineCallSiteRule
+        ? `- ${inlineCallSiteRule} This applies to every ${site.stepNoun} 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}
-
+${utilsMergeRule}${inHouseMatchStep}
 ## STEP 4: FIND LOCAL HELPERS IN OTHER SKYRAMP-GENERATED TEST FILES
 
 You are looking for sibling test files generated by Skyramp's codegen. They start with the comment line \`${codegenMarker}…\` (note: the version suffix is what distinguishes them from the SkyrampUtils header). The substring \`${SKYRAMP_UTILS_HEADER}\` is contained in that line, so:
@@ -255,8 +275,8 @@ NOT A HELPER FUNCTION (do not extract):
    - No function definition/signature
    - Example: Multiple \`await page.getByTestId("xyz").click()\` directly in test
 
-${inlineRequestRule
-        ? `(Inline request blocks in OTHER test files are not helpers to move — STEP 5c replaces them with calls to the shared helpers.)
+${inlineCallSiteRule
+        ? `(${site.nouns} 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}**
@@ -300,7 +320,7 @@ For each helper defined locally in ${testFile}:
 - **Conservative bias**: a wrong merge breaks both tests; a missed merge leaves a duplicate. When in doubt, do NOT merge.
 - **No "cleanup"**: the merged body must mirror the original primitive sequence — same waits, same correlation patterns, same order. This is not refactoring.
 ${pyImportRuleLine(fileName)}
-- **Typed parameters (TypeScript)**: the merged helper types every parameter (\`page: Page\`, values by their type); add \`import type { Page } from '@playwright/test'\` to the utils file if it is missing. Never \`page: any\` or an untyped \`page\` — that fails a repo that type-checks its tests under \`noImplicitAny\`.
+- **Typed parameters (TypeScript)**: the merged helper types every parameter (\`page: Page\`, values by their type); add \`import type { Page } from '@playwright/test'\` to the utils file if it is missing. Never \`page: any\`, \`page: unknown\`, or an untyped \`page\` — an untyped one fails a repo that type-checks its tests under \`noImplicitAny\`, and \`unknown\` fails at its first use under every setting.
 - **Don't merge with helpers already in \`${fileName}\`**: those are STEP 3's territory. STEP 4b is strictly cross-test merge between sibling Skyramp-generated test files.
 
 ---
@@ -328,7 +348,7 @@ ${pyImportRuleLine(fileName)}
    \`\`\`${ext}
    ${generateSkyrampHeader(lang)}
    \`\`\`
-**CRITICAL: IF \`${fileName}\` is already big, create a new file with a different name and add the header to the new file.**
+${moduleNameRule}
 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.
@@ -348,7 +368,7 @@ ${seedStepBlock}${siblingCallSitesStep}## STEP 6: VERIFY AND VALIDATE
 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${inlineRequestRule ? " — and, in this flow, replacing an inline request block with a call to the shared helper it duplicates (STEP 3 / STEP 5c)" : ""}
+9. **NEVER** refactor, reorganize, or restructure existing source test files beyond moving helpers${inlineCallSiteRule ? ` — and, in this flow, replacing an ${site.noun} with a call to the shared helper it duplicates (STEP 3 / STEP 5c)` : ""}
 10. **RUN TESTS** to ensure functionality is preserved after refactoring
 11. **NEVER** drop an assertion or a cross-cutting guard (\`page.on('pageerror'...)\`, error collectors and their final \`expect\`) while moving code — the verify step compares the assertion count against the modularization hand-out and fails on a loss
 
@@ -357,14 +377,14 @@ ${finalReminderScope}
 
 **IMPORTANT NOTES:**
 - The process is designed to REUSE existing helper functions, not create new ones
-- ${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"}
+- ${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${inHouseBrowser ? "; when STEP 2b found the repository's own browser helper module, STEP 3b does that placement into THEIR module instead and STEP 5b is skipped" : ""}` : "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
 - Repetitive inline test code is NOT a helper function
 
 **DECISION TREE:**
-1. Found existing utils file with helpers? → Import and use them (Step 3)
+${inHouseBrowser ? "0. STEP 2b found a qualifying in-house browser helper module? → call its helpers and add this test's helpers to it (Step 3b); Step 5b is skipped and no `" + fileName + "` is created\n" : ""}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)
 ${decisionTreeTail}
 
@@ -374,9 +394,58 @@ ${
     // 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`
+        ? `**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).${inHouseBrowser
+            ? ` It also checks every in-house module this test imports: each imported name must exist there with an argument count its signature accepts, and every change this run made to their module must add a helper or add a defaulted parameter — anything else is refused and you restore it. On that call pass \`inHouse: { filesRead: [...], declined: [{ file, helper, reason }, ...] }\` — every file STEP 2b read, and every helper STEP 3b read and did not call, with the reason. These are your declarations and the report labels them as such.`
+            : ""} Resolve anything it reports and re-verify; finish only when it reports PASSED. It passes immediately when no utils file was written${inHouseBrowser ? " and no in-house module is imported" : ""}. 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.
 `;
 }
+/**
+ * STEP 2b — find the repository's own browser helper modules. The agent searches;
+ * the search is a sample, and the report carries that cost: every file read is
+ * declared on the verify call. No fixed list of file names and no language filter,
+ * so a module nobody enumerated is still found; a module not written for Playwright
+ * is then reported as unreadable rather than filtered out in silence.
+ */
+function inHouseDiscovery(testFile, fileName) {
+    return `
+## STEP 2b: FIND THE REPOSITORY'S OWN BROWSER HELPER MODULES
+
+The header grep in STEP 2 finds only modules Skyramp wrote. The repository may already hold browser helpers of its own — a module the team wrote, carrying no Skyramp header — and a test that ignores it ends with two helper layers for the same steps. Find them.
+
+1. **Search the directory of ${testFile} and each of its parent directories up to the repository root.** Use Grep for Playwright locator and action calls (\`getBy\`, \`.locator(\`, \`page.\`, \`.click(\`, \`.fill(\`) in files that are NOT test files. Do NOT limit the search to a fixed list of file or directory names (\`pages/\`, \`helpers/\`, \`*.page.ts\` are hints, not the search), and do NOT limit it to one extension or language. Exclude \`node_modules\`, \`${fileName}\` and every other file carrying the \`${SKYRAMP_UTILS_HEADER}\` header (STEP 2 owns those), and test files — by BASENAME only: a basename ending in \`.spec.ts\`, \`.spec.js\`, \`.test.ts\`, \`.test.js\` is a test; a directory called \`tests/\` is not.
+2. **Read every candidate.** ${SELECTOR_OWNING_MODULE_RULE} A module written for a browser library other than Playwright shares no vocabulary with this test: read it, record it, and report it as unreadable — do not call it and do not extend it.
+3. **Catalog each qualifying module** to chat before changing anything: for each helper its name, **whether the module exports it UNDER THAT NAME** (an \`export\` on the definition, or an unaliased entry in an \`export { … }\` list of its own bindings — a default export and an aliased one export something else, and a helper this test cannot import is one it cannot call), its parameters (with defaults), what it returns, and its ACTION KEY — the sequence of Playwright actions it performs, in body order, each as the verb plus the locator chain it is called on (\`fill page.getByTestId("email"); click page.getByRole("button", { name: "Sign in" })\`). Argument VALUES are not part of the key, with two exceptions that ARE: a \`goto\` target and a \`dragTo\` destination — where a navigation goes and where a drag lands are the identity of those steps, so a helper that opens another page never matches. The key is UNDEFINED for a helper whose locator is not built from plain string literals — a variable, a template literal, a regex, a parameter; record it as undefined.
+4. **Record every file the search read** — qualifying or not — as a repository-relative path. You pass this list to the verify call at the end (\`inHouse.filesRead\`). A file you did not read is not on it.
+
+**Which module to extend when there is more than one:** the module the tests in this directory already import; of those, the one holding the helpers STEP 3b matches; otherwise the module nearest to ${testFile}.
+
+**Decision:** no qualifying module → continue to STEP 3 as written; STEP 3b and the in-house rule in STEP 5b then have nothing to do. One or more → continue to STEP 3, then STEP 3b.
+`;
+}
+/**
+ * STEP 3b — match each step to the customer's helpers by the action key, call
+ * theirs where the keys agree, and add to their module where nothing does. The
+ * two edits their file may receive are stated here and enforced by the verify
+ * call's additive gate; the header rule is stated because the old verify text told
+ * the agent the opposite.
+ */
+function inHouseMatch(testFile, fileName, policy) {
+    return `
+## STEP 3b: CALL THE REPOSITORY'S OWN HELPERS, AND ADD TO THEIR MODULE WHAT IT LACKS
+
+Run this step only if STEP 2b found a qualifying module. Match every helper skyramp_modularization extracted in ${testFile} AND every action sequence still inline in it; ADD to their module only for the extracted helpers — an inline step with no match stays inline, as modularization left it (single-use steps are not helpers).
+
+**Match by the action key, not by name or by intent.** Compute the key of the step exactly as STEP 2b computed the helpers' keys, and compare:
+
+- **Keys equal → call their helper.** Replace the step (or delete the local helper and replace its calls) with a call to their helper, passing this test's values as arguments where their signature takes them. Where their helper hardcodes a value this test needs to differ (a filled text, an option label) and takes no parameter for it, ADD a parameter to their helper — APPENDED AFTER its existing parameters, never inserted among them, which would shift every caller they already have onto the wrong argument — whose DEFAULT is exactly the literal it replaces, and pass this test's value — every existing caller keeps its behaviour, and the verify call checks that with the default substituted back the helper reads as it did at HEAD. That is the ONLY edit an existing helper of theirs may receive.
+- **Their key is undefined** (a variable, template-literal or regex locator) **→ do not call it and do not extend it.** Leave the step as it is and record the helper with the reason (\`inHouse.declined\` on the verify call).
+- **No key matches (an extracted helper) → add it to THEIR module.** Move its body into their module written in that file's own style: its naming convention, its parameter style (positional, options object, defaults), the browser API and the import forms it already uses; delete the local definition and import it, keeping the call sites. It carries the action sequence and structural waits only — a value assertion stays in ${testFile} right after the call (${policy.assertionRule}). Do not add a helper whose key equals a helper the module already holds; call that one. Do not import the Skyramp runtime into their file.
+
+**Never change what an existing helper of theirs does** — no edited body, no renamed helper, no removed line, no parameter without a default. **Never write the \`${SKYRAMP_UTILS_HEADER}\` header into their file.** It stays their file; the verify call compares it against HEAD and refuses any other change, and you undo it.
+
+A step their helper covers is NOT moved into \`${fileName}\` in STEP 5b. Record, for the verify call, each helper of theirs you read and did not call, with the reason.
+`;
+}

package/build/prompts/fix-error-prompt.d.ts

@@ -1 +1,9 @@
-export declare function getFixErrorsPrompt(): string;
+import { ProgrammingLanguage } from "../types/TestTypes.js";
+interface FixErrorsPromptParams {
+    testFile: string;
+    language: `${ProgrammingLanguage}`;
+    framework: string;
+}
+/** Render the repair skill for clients that do not load the plugin. */
+export declare function getFixErrorsPrompt(params: FixErrorsPromptParams): string;
+export {};

package/build/prompts/fix-error-prompt.js

@@ -1,29 +1,32 @@
-export function getFixErrorsPrompt() {
-    return `
-**Fix errors in refactored code.**
-
-1. **Parameter Passing:** Identify functions using variables from outside scope (like 'page' object). Pass these as parameters.
-2. **Validate Correctness:** Ensure code is free of reference errors, undefined variables, runtime issues.
-3. **Import Paths:** Ensure import paths are correct and there are no circular imports.
-4. **Import Validation:** Ensure all remaining imports are necessary and no missing imports cause reference errors.
-5. **Unused Import Cleanup:** Verify that unused imports were properly removed without breaking functionality.
-6. **UI State Management:** Check for UI state conflicts, modal interference, or element interaction issues.
-7. **Sequential Operations:** Ensure UI operations don't interfere with each other when called in sequence.
-
-**IMPORT ERROR DEBUGGING:**
-- Check for missing imports that cause undefined reference errors
-- Verify that import removal didn't break existing functionality
-- Ensure all imported modules are actually available in the project
-- Confirm that import syntax is correct for the target language
-
-**CRITICAL CONSTRAINTS:**
-- DO NOT CREATE/UPDATE package.json or requirements.txt or pom.xml or build.gradle file
-- NEVER create dependency management files, even when linting errors suggest missing dependencies
-- Focus on fixing code errors within existing files only
-
-**KEY: Variables not defined within function scope MUST be passed as parameters.**
-**UI KEY: Helper functions that perform UI operations must be self-contained and not leave modals/dialogs open.**
-**IMPORT KEY: All imports must be either used in the code or properly removed.**
-**DEPENDENCY KEY: DO NOT create package.json, requirements.txt, or any dependency files regardless of linting errors.**
-`;
+import { FIX_TEST_IMPORT_ERRORS_SKILL } from "../skills/fixTestImportErrorsSkill.js";
+import { readSkillBody, section, sliceBetween } from "../skills/skillFiles.js";
+import { ProgrammingLanguage } from "../types/TestTypes.js";
+/** Render the repair skill for clients that do not load the plugin. */
+export function getFixErrorsPrompt(params) {
+    let languageHeading;
+    switch (params.language) {
+        case ProgrammingLanguage.PYTHON:
+            languageHeading = "### Python";
+            break;
+        case ProgrammingLanguage.JAVASCRIPT:
+        case ProgrammingLanguage.TYPESCRIPT:
+            languageHeading = "### JavaScript and TypeScript";
+            break;
+        case ProgrammingLanguage.JAVA:
+            languageHeading = "### Java";
+            break;
+        default:
+            throw new Error(`Unsupported repair language: ${params.language}`);
+    }
+    const skill = readSkillBody(FIX_TEST_IMPORT_ERRORS_SKILL);
+    const instructions = [
+        sliceBetween(skill, "## Workflow", "## Steps for"),
+        // Match the whole heading: "Java" must not select "JavaScript".
+        section(skill, `${languageHeading}\n`),
+        section(skill, "## Execution guidance"),
+    ].join("\n\n");
+    const values = [params.testFile, params.language, params.framework];
+    // Replace once: dollar signs in a supplied path must not become placeholders.
+    // Named shell variables in the Java example are left intact.
+    return instructions.replace(/\$([012])(?!\d)/g, (_match, index) => values[Number(index)]);
 }

package/build/prompts/local-dev/local-dev-plan.d.ts

@@ -17,6 +17,9 @@ export declare const GRPC_SERVICE_NAME_GUIDANCE = "the bare service name as decl
 export declare const ASSERTION_API_GUIDANCE = "Use the SDK helper for all field-level assertions: Python `skyramp.get_response_value(response, \"json.path\")`, TypeScript `getResponseValue(response, \"json.path\")`. The helper supports dot-path notation for nested access (e.g., `\"data.items[0].name\"`). Do NOT use dict/attribute access on the response variable (`response[\"field\"]`, `response.field`) or `json.loads(response.response_body)`";
 export interface LocalDevPlanCtx {
     repositoryPath: string;
+    /** `owner/repo` of the checkout at repositoryPath. skyramp_analyze_changes and
+     *  skyramp_execute_test both name their repository on every call. */
+    repository: string;
     baseCommit: string;
     maxRecommendations: number;
     maxGenerate: number;